@castlenine/svelte-aoe 1.5.0 → 2.1.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,71 @@ 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%).
 
+## Scoped Overrides
+
+Set defaults for all `data-aoe` elements within a page or section using `data-aoe-scope` on a container element, or the `<AnimateOnEnterScope>` convenience component. Elements inside a scope inherit its values unless they have their own per-element `data-aoe-*` overrides.
+
+### Using `data-aoe-scope` attribute
+
+```svelte
+<div data-aoe-scope data-aoe-threshold="0.5" data-aoe-root-margin="20px">
+  <!-- All elements inside use threshold=0.5 and rootMargin=20px -->
+  <img data-aoe="fade-up" src="..." />
+
+  <!-- Per-element override still takes priority -->
+  <img data-aoe="fade-up" data-aoe-threshold="0.8" src="..." />
+</div>
+```
+
+### Using `<AnimateOnEnterScope>` component
+
+```svelte
+<script>
+  import { AnimateOnEnterScope } from '@castlenine/svelte-aoe';
+</script>
+
+<AnimateOnEnterScope threshold={0.5} rootMargin="20px">
+  <img data-aoe="fade-up" src="..." />
+</AnimateOnEnterScope>
+```
+
+| Property name | Type                                         | Default value |
+| ------------- | -------------------------------------------- | ------------- |
+| `root`        | CSS selector `string`                        | `undefined`   |
+| `rootMargin`  | `string` in pixel (`px`) or percentage (`%`) | `undefined`   |
+| `threshold`   | `number` between `0` and `1.0`               | `undefined`   |
+
+Scopes can be nested. The innermost scope wins.
+
+## Per-Element Overrides
+
+Individual elements can override scope or global properties using `data-aoe-*` attributes. If an attribute is not set, the value from the nearest `data-aoe-scope` ancestor is used, then `<AnimateOnEnter />`, then 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/AnimateOnEnterScope.svelte

@@ -0,0 +1,27 @@
+<!--
+@component
+### AnimateOnEnterScope
+Convenience wrapper that sets `data-aoe-scope` defaults for all `data-aoe` descendants.
+Elements inside the scope inherit these values unless they have their own `data-aoe-*` overrides.
+
+&nbsp;
+
+@param {string | undefined} `root` - CSS selector for the root element used as the viewport.
+@param {string | undefined} `rootMargin` - Margin around the root (px or %).
+@param {number | undefined} `threshold` - Visibility percentage (0 to 1) to trigger animations.
+-->
+
+<script>export let root = void 0;
+export let rootMargin = void 0;
+export let threshold = void 0;
+</script>
+
+<div
+	{...$$restProps}
+	data-aoe-scope
+	data-aoe-root={root}
+	data-aoe-root-margin={rootMargin}
+	data-aoe-threshold={threshold != null ? String(threshold) : undefined}
+>
+	<slot />
+</div>

package/dist/AnimateOnEnterScope.svelte.d.ts

@@ -0,0 +1,33 @@
+import { SvelteComponentTyped } from "svelte";
+declare const __propDef: {
+    props: {
+        [x: string]: any;
+        root?: string | undefined;
+        rootMargin?: string | undefined;
+        threshold?: number | undefined;
+    };
+    events: {
+        [evt: string]: CustomEvent<any>;
+    };
+    slots: {
+        default: {};
+    };
+};
+export type AnimateOnEnterScopeProps = typeof __propDef.props;
+export type AnimateOnEnterScopeEvents = typeof __propDef.events;
+export type AnimateOnEnterScopeSlots = typeof __propDef.slots;
+/**
+ * ### AnimateOnEnterScope
+ * Convenience wrapper that sets `data-aoe-scope` defaults for all `data-aoe` descendants.
+ * Elements inside the scope inherit these values unless they have their own `data-aoe-*` overrides.
+ *
+ * &nbsp;
+ *
+ * @param {string | undefined} `root` - CSS selector for the root element used as the viewport.
+ * @param {string | undefined} `rootMargin` - Margin around the root (px or %).
+ * @param {number | undefined} `threshold` - Visibility percentage (0 to 1) to trigger animations.
+ */
+export default class AnimateOnEnterScope extends SvelteComponentTyped<AnimateOnEnterScopeProps, AnimateOnEnterScopeEvents, AnimateOnEnterScopeSlots> {
+}
+export {};
+//# sourceMappingURL=AnimateOnEnterScope.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnimateOnEnterScope.svelte.d.ts","sourceRoot":"","sources":["../src/lib/AnimateOnEnterScope.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAE5C;AAeD,QAAA,MAAM,SAAS;;;eADyE,MAAM,GAAG,SAAS;qBAAe,MAAM,GAAG,SAAS;oBAAc,MAAM,GAAG,SAAS;;;;;;;;CAC3F,CAAC;AACjF,MAAM,MAAM,wBAAwB,GAAG,OAAO,SAAS,CAAC,KAAK,CAAC;AAC9D,MAAM,MAAM,yBAAyB,GAAG,OAAO,SAAS,CAAC,MAAM,CAAC;AAChE,MAAM,MAAM,wBAAwB,GAAG,OAAO,SAAS,CAAC,KAAK,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAoB,SAAQ,oBAAoB,CAAC,wBAAwB,EAAE,yBAAyB,EAAE,wBAAwB,CAAC;CACnJ"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 import AnimateOnEnter from './index.svelte';
 export default AnimateOnEnter;
+export { default as AnimateOnEnterScope } from './AnimateOnEnterScope.svelte';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,cAAc,MAAM,gBAAgB,CAAC;AAE5C,eAAe,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,cAAc,MAAM,gBAAgB,CAAC;AAE5C,eAAe,cAAc,CAAC;AAC9B,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 import AnimateOnEnter from './index.svelte';
 export default AnimateOnEnter;
+export { default as AnimateOnEnterScope } from './AnimateOnEnterScope.svelte';

package/dist/index.svelte

@@ -1,30 +1,115 @@
-<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. `data-aoe-scope` on a container: override component props for a page or section
+4. Per-element `data-aoe-*` attributes: override scope or 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 resolveConfig(el) {
+        var _a, _b;
+        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");
+        const SCOPE = el.closest("[data-aoe-scope]");
+        const ROOT_SELECTOR = (_a = ROOT_ATTR !== null && ROOT_ATTR !== void 0 ? ROOT_ATTR : SCOPE === null || SCOPE === void 0 ? void 0 : SCOPE.getAttribute("data-aoe-root")) !== null && _a !== void 0 ? _a : null;
+        const ROOT_MARGIN = (_b = ROOT_MARGIN_ATTR !== null && ROOT_MARGIN_ATTR !== void 0 ? ROOT_MARGIN_ATTR : SCOPE === null || SCOPE === void 0 ? void 0 : SCOPE.getAttribute("data-aoe-root-margin")) !== null && _b !== void 0 ? _b : DEFAULT_ROOT_MARGIN;
+        const RAW_THRESHOLD = THRESHOLD_ATTR !== null && THRESHOLD_ATTR !== void 0 ? THRESHOLD_ATTR : SCOPE === null || SCOPE === void 0 ? void 0 : SCOPE.getAttribute("data-aoe-threshold");
+        const PARSED = RAW_THRESHOLD != null ? parseFloat(RAW_THRESHOLD) : NaN;
+        const THRESHOLD = !isNaN(PARSED) ? PARSED : DEFAULT_THRESHOLD;
+        return { rootSelector: ROOT_SELECTOR, rootMargin: ROOT_MARGIN, threshold: THRESHOLD };
+    }
+    function registerElement(el) {
+        if (REGISTERED.has(el) || el.classList.contains("aoe"))
+            return;
+        REGISTERED.add(el);
+        const { rootSelector: ROOT_SELECTOR, rootMargin: ROOT_MARGIN, threshold: THRESHOLD } = resolveConfig(el);
+        if (!ROOT_SELECTOR && ROOT_MARGIN === DEFAULT_ROOT_MARGIN && THRESHOLD === DEFAULT_THRESHOLD) {
+            DEFAULT_OBSERVER.observe(el);
+            return;
+        }
+        const EL_ROOT = ROOT_SELECTOR ? document.querySelector(ROOT_SELECTOR) : DEFAULT_ROOT;
+        const KEY = configKey(ROOT_SELECTOR, ROOT_MARGIN, THRESHOLD);
+        const OBSERVER = getOrCreateObserver(KEY, {
+            root: EL_ROOT,
+            rootMargin: ROOT_MARGIN,
+            threshold: 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,17 @@ 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. `data-aoe-scope` on a container: override component props for a page or section
+ * 4. Per-element `data-aoe-*` attributes: override scope or 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;AA6H1B,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;;;;;;;;;;;;;;;;;GAiBG;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.1.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 .",