diff --git a/CHANGELOG.md b/CHANGELOG.md index d5f0e07..db7b91a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.0.0](https://github.com/svelte-plugins/svelte-viewable/releases/tag/v1.0.0) - 2021-04-02 + +- Interface changes that include exposing observer props and events +- Includes new `on:complete` event +- Replaced `enableObstructionDetection` with `detectObstructions` + ## [0.1.3](https://github.com/svelte-plugins/svelte-viewable/releases/tag/v0.1.3) - 2021-04-01 - Enable SSR support diff --git a/README.md b/README.md index e49fcc7..574f298 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,62 @@ npm i -D @svelte-plugins/viewable Try the basic example in [Svelte REPL](https://svelte.dev/repl/c811481b8e1b48e9bed0f6ff7d1fa9c2). +## API + +### Props +| Prop name | Description | Value | +| :----------- | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- | +| element | Element to observe | `HTMLElement` | +| rules | Viewability rules | `object` (default: `null`) | +| intervalRate | Rate to check measurement while intersecting (ms) | `number` (default: `200`) | +| gridSize | Size of the obstruction grid | `number` (default: `20`) | +| detectObstructions | If `true`, obstructions impacting the element will affect measurement | 'boolean' (default: `false`) | +| root | Containing element | `null` or `HTMLElement` (default: `null`) | +| rootMargin | Margin offset of the containing element | `string` (default: `"0px"`) | +| intersecting | `true` if the observed element is intersecting | `boolean` (default: `false`) | +| observer | IntersectionObserver instance | [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) | +| entry | Observed element metadata | [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) | +| debug | If `true`, debug ouput will be logged to console | `boolean` (default: `false`) | + +#### rules +| Prop name | Description | Value | +| :----------- | :------------------------------------------------------------------ | :---------------------------------- | +| duration | Consecutive time (seconds) that the element must be in view | `number` (default: `0`) | +| percentage | Percentage of the element that must be viewable | `number` (default: `0`) | +| repeat | If `true`, the rule will be applied indefinitely v once | `function` (default: `null`) | +| fn | Callback function to execute when rule has been met | `function` (default: `null`) | + + +```js +const rules = { + dwell: { + duration: 1, + percentage: 50, + fn: () => { + console.log('50% of the element was visible for at least 1 consecutive second.'); + } + } +} +``` + +### Debug props + +The properties below can be used to assist with debugging any issues you might have (ex: `bind:duration`, `bind:percent`, etc.) + +| Prop name | Description | Value | +| :----------- | :---------------------------------------------------------------- | :---------------------- | +| duration | Viewable duration of the tracked element | `number` (default: `0`) | +| percent | Percentage of total viewable area (X+Y) | `number` (default: `0`) | +| percentX | Percentage of horizontal viewable area | `number` (default: `0`) | +| percentY | Percentage of vertical viewable area | `number` (default: `0`) | + + +### Events + +- **on:observe**: Fired when an intersection change occurs (type `IntersectionObserverEntry`) +- **on:intersect**: Fired when an intersection change occurs and the element is intersecting (type `IntersectionObserverEntry`) +- **on:complete**: Fired when all rules have been executed + ## Changelog [Changelog](CHANGELOG.md) diff --git a/docs/src/App.svelte b/docs/src/App.svelte index 92edce9..76c2590 100644 --- a/docs/src/App.svelte +++ b/docs/src/App.svelte @@ -1,21 +1,21 @@ -{#if enableObstructionDetection} +{#if detectObstructions}
{/if}