@castlenine/svelte-aoe 1.5.0 → 2.0.0

package/README.md

@@ -23,25 +23,7 @@ npm i @castlenine/svelte-aoe
 
 ## Setup
 
-- Import the package
-
-```svelte
-import AnimateOnEnter from '@castlenine/svelte-aoe';
-```
-
-- Add the component to your layout/page/component.
-
-```svelte
-<AnimateOnEnter />
-```
-
-- Add a `data-aoe` attribute to the element that you want to animate and define an animation.
-
-```svelte
-<img data-aoe="fade-up" src="https://dummyimage.com/500x300"/>
-```
-
-## Example: SvelteKit Global Setup
+1. Import and add the component **once** in your root layout:
 
 File: `src/routes/+layout.svelte`
 
@@ -55,6 +37,14 @@ File: `src/routes/+layout.svelte`
 <slot />
 ```
 
+2. Add a `data-aoe` attribute to any element you want to animate:
+
+```svelte
+<img data-aoe="fade-up" src="https://dummyimage.com/500x300"/>
+```
+
+Elements are automatically detected, including those added dynamically by page navigation.
+
 ## Animations
 
 ### Normal speed
@@ -153,6 +143,35 @@ You can add your own animations by following the same pattern in your CSS.
 
 `threshold` is either a single number or an array of numbers which indicate at what percentage of the target's visibility the observer's callback should be executed. A value of `0.0` or `0` indicates that even a single pixel of the target is visible. A value of `1.0` or `1` indicates that the target is completely visible. Defaults to `0.3` (30%).
 
+## Per-Element Overrides
+
+Individual elements can override the global properties using `data-aoe-*` attributes. If an attribute is not set, the value from `<AnimateOnEnter />` is used, which itself falls back to the package default.
+
+| Attribute            | Type                                           | Overrides    |
+| -------------------- | ---------------------------------------------- | ------------ |
+| `data-aoe-root`      | CSS selector `string`                          | `root`       |
+| `data-aoe-root-margin` | `string` in pixel (`px`) or percentage (`%`) | `rootMargin` |
+| `data-aoe-threshold` | `number` between `0` and `1.0`                 | `threshold`  |
+
+### Examples
+
+```svelte
+<!-- Uses global defaults -->
+<img data-aoe="fade-up" src="..." />
+
+<!-- Overrides threshold only (animates as soon as 1px is visible) -->
+<img data-aoe="fade-up" data-aoe-threshold="0" src="..." />
+
+<!-- Overrides rootMargin only (triggers 200px before entering viewport) -->
+<img data-aoe="fade-up" data-aoe-root-margin="200px" src="..." />
+
+<!-- Overrides root to a specific scroll container -->
+<img data-aoe="fade-up" data-aoe-root="#scroll-container" src="..." />
+
+<!-- Multiple overrides -->
+<img data-aoe="fade-up" data-aoe-threshold="0.8" data-aoe-root-margin="50px" src="..." />
+```
+
 ---
 
 Inspired by [Animate on Scroll](https://michalsnik.github.io/aos/) and forked from [lliamscholtz/svelte-aoe](https://github.com/lliamscholtz/svelte-aoe)

package/dist/index.svelte

@@ -1,30 +1,106 @@
-<script>import "./animations.css";
-import { onMount } from "svelte";
-export let root = null;
-export let rootMargin = "0px";
-export let threshold = 0.3;
-onMount(() => {
-    const OBSERVER = new IntersectionObserver((entries) => {
-        entries.forEach((entry) => {
-            if (entry.isIntersecting) {
-                entry.target.classList.add("aoe");
-                OBSERVER.unobserve(entry.target);
-            }
-        });
-    }, { root, rootMargin, threshold });
-    document.querySelectorAll("[data-aoe]").forEach((el) => OBSERVER.observe(el));
-    return () => OBSERVER.disconnect();
-});
-</script>
-
 <!--
 @component
-### AnimationOnEnter (AOE)
+### AnimateOnEnter (AOE)
 This component is used to animate elements when they enter the viewport with the help of [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
 
+Place this component once in your root layout. Elements with `data-aoe` attributes will be automatically detected, including dynamically added elements from page navigation.
+
+#### Configuration cascade
+1. Package defaults: `root: null`, `rootMargin: '0px'`, `threshold: 0.3`
+2. Component props: override package defaults globally
+3. Per-element `data-aoe-*` attributes: override component props for individual elements
+
 &nbsp;
 
 @param {Document | Element | null | undefined} `root` - The element that is used as the viewport for checking visibility of the target. Must be the ancestor of the target. Defaults to the browser viewport if not specified or if `null`.
 @param {string | undefined} `rootMargin` - Margin around the root. Can have values similar to the CSS margin property, e.g. "10px 20px 30px 40px" (top, right, bottom, left). The values can be percentages. Defaults to '0px' (no margin).
 @param {number | number[]} `threshold` - Either a single number or an array of numbers which indicate at what percentage of the target's visibility the observer's callback should be executed. A value of 0.0 indicates that even a single pixel of the target is visible. A value of 1.0 indicates that the target is completely visible. Defaults to 0.3 (30%).
 -->
+
+<script>import "./animations.css";
+import { onMount } from "svelte";
+export let root = null;
+export let rootMargin = "0px";
+export let threshold = 0.3;
+onMount(() => {
+    const DEFAULT_ROOT = root !== null && root !== void 0 ? root : null;
+    const DEFAULT_ROOT_MARGIN = rootMargin !== null && rootMargin !== void 0 ? rootMargin : "0px";
+    const DEFAULT_THRESHOLD = threshold !== null && threshold !== void 0 ? threshold : 0.3;
+    const OBSERVERS = /* @__PURE__ */ new Map();
+    const REGISTERED = /* @__PURE__ */ new WeakSet();
+    function createObserver(options) {
+        const OBSERVER = new IntersectionObserver((entries) => {
+            for (const ENTRY of entries) {
+                if (ENTRY.isIntersecting) {
+                    ENTRY.target.classList.add("aoe");
+                    OBSERVER.unobserve(ENTRY.target);
+                }
+            }
+        }, options);
+        return OBSERVER;
+    }
+    function configKey(rootSelector, rm, th) {
+        const TH_STR = Array.isArray(th) ? th.join(",") : String(th);
+        return `${rootSelector !== null && rootSelector !== void 0 ? rootSelector : "null"}|${rm}|${TH_STR}`;
+    }
+    const DEFAULT_KEY = configKey(null, DEFAULT_ROOT_MARGIN, DEFAULT_THRESHOLD);
+    const DEFAULT_OBSERVER = createObserver({
+        root: DEFAULT_ROOT,
+        rootMargin: DEFAULT_ROOT_MARGIN,
+        threshold: DEFAULT_THRESHOLD
+    });
+    OBSERVERS.set(DEFAULT_KEY, DEFAULT_OBSERVER);
+    function getOrCreateObserver(key, options) {
+        let observer = OBSERVERS.get(key);
+        if (!observer) {
+            observer = createObserver(options);
+            OBSERVERS.set(key, observer);
+        }
+        return observer;
+    }
+    function registerElement(el) {
+        if (REGISTERED.has(el) || el.classList.contains("aoe"))
+            return;
+        REGISTERED.add(el);
+        const ROOT_ATTR = el.getAttribute("data-aoe-root");
+        const ROOT_MARGIN_ATTR = el.getAttribute("data-aoe-root-margin");
+        const THRESHOLD_ATTR = el.getAttribute("data-aoe-threshold");
+        if (!ROOT_ATTR && !ROOT_MARGIN_ATTR && !THRESHOLD_ATTR) {
+            DEFAULT_OBSERVER.observe(el);
+            return;
+        }
+        const EL_ROOT = ROOT_ATTR ? document.querySelector(ROOT_ATTR) : DEFAULT_ROOT;
+        const EL_ROOT_MARGIN = ROOT_MARGIN_ATTR !== null && ROOT_MARGIN_ATTR !== void 0 ? ROOT_MARGIN_ATTR : DEFAULT_ROOT_MARGIN;
+        const PARSED_THRESHOLD = THRESHOLD_ATTR != null ? parseFloat(THRESHOLD_ATTR) : null;
+        const EL_THRESHOLD = PARSED_THRESHOLD != null && !isNaN(PARSED_THRESHOLD) ? PARSED_THRESHOLD : DEFAULT_THRESHOLD;
+        const KEY = configKey(ROOT_ATTR, EL_ROOT_MARGIN, EL_THRESHOLD);
+        const OBSERVER = getOrCreateObserver(KEY, {
+            root: EL_ROOT,
+            rootMargin: EL_ROOT_MARGIN,
+            threshold: EL_THRESHOLD
+        });
+        OBSERVER.observe(el);
+    }
+    document.querySelectorAll("[data-aoe]").forEach((el) => registerElement(el));
+    const MUTATION_OBSERVER = new MutationObserver((mutations) => {
+        for (const MUTATION of mutations) {
+            for (const NODE of MUTATION.addedNodes) {
+                if (NODE.nodeType !== Node.ELEMENT_NODE)
+                    continue;
+                const el = NODE;
+                if (el.hasAttribute("data-aoe"))
+                    registerElement(el);
+                el.querySelectorAll("[data-aoe]").forEach((child) => registerElement(child));
+            }
+        }
+    });
+    MUTATION_OBSERVER.observe(document.body, { childList: true, subtree: true });
+    return () => {
+        MUTATION_OBSERVER.disconnect();
+        for (const OBSERVER of OBSERVERS.values()) {
+            OBSERVER.disconnect();
+        }
+        OBSERVERS.clear();
+    };
+});
+</script>

package/dist/index.svelte.d.ts

@@ -15,9 +15,16 @@ export type IndexProps = typeof __propDef.props;
 export type IndexEvents = typeof __propDef.events;
 export type IndexSlots = typeof __propDef.slots;
 /**
- * ### AnimationOnEnter (AOE)
+ * ### AnimateOnEnter (AOE)
  * This component is used to animate elements when they enter the viewport with the help of [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
  *
+ * Place this component once in your root layout. Elements with `data-aoe` attributes will be automatically detected, including dynamically added elements from page navigation.
+ *
+ * #### Configuration cascade
+ * 1. Package defaults: `root: null`, `rootMargin: '0px'`, `threshold: 0.3`
+ * 2. Component props: override package defaults globally
+ * 3. Per-element `data-aoe-*` attributes: override component props for individual elements
+ *
  *  
  *
  * @param {Document | Element | null | undefined} `root` - The element that is used as the viewport for checking visibility of the target. Must be the ancestor of the target. Defaults to the browser viewport if not specified or if `null`.

package/dist/index.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.svelte.d.ts","sourceRoot":"","sources":["../src/lib/index.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAE5C;AACD,OAAO,kBAAkB,CAAC;AAqC1B,QAAA,MAAM,SAAS;;eADyE,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS;qBAAe,MAAM,GAAG,SAAS;oBAAc,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;;;;;;CAChJ,CAAC;AAC1D,MAAM,MAAM,UAAU,GAAG,OAAO,SAAS,CAAC,KAAK,CAAC;AAChD,MAAM,MAAM,WAAW,GAAG,OAAO,SAAS,CAAC,MAAM,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,OAAO,SAAS,CAAC,KAAK,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,OAAO,KAAM,SAAQ,oBAAoB,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,CAAC;CAC3F"}
+{"version":3,"file":"index.svelte.d.ts","sourceRoot":"","sources":["../src/lib/index.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAE5C;AACD,OAAO,kBAAkB,CAAC;AA8G1B,QAAA,MAAM,SAAS;;eADyE,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS;qBAAe,MAAM,GAAG,SAAS;oBAAc,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;;;;;;CAChJ,CAAC;AAC1D,MAAM,MAAM,UAAU,GAAG,OAAO,SAAS,CAAC,KAAK,CAAC;AAChD,MAAM,MAAM,WAAW,GAAG,OAAO,SAAS,CAAC,MAAM,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,OAAO,SAAS,CAAC,KAAK,CAAC;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,OAAO,OAAO,KAAM,SAAQ,oBAAoB,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,CAAC;CAC3F"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@castlenine/svelte-aoe",
-	"version": "1.5.0",
+	"version": "2.0.0",
 	"description": "A Svelte component to animate elements, with no dependencies.",
 	"license": "MIT",
 	"keywords": [
@@ -45,7 +45,7 @@
 		"build": "npm run check && vite build",
 		"preview": "vite preview",
 		"package": "npm run remove-dist-folder && svelte-kit sync && svelte-package && publint",
-		"prepublishOnly": "npm run package",
+		"prepublish-only": "npm run package",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"eslint": "eslint --ignore-path ./.eslintignore .",