@castlenine/svelte-aoe 2.0.0 → 2.1.0

package/README.md

@@ -143,9 +143,45 @@ 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 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.
+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    |
 | -------------------- | ---------------------------------------------- | ------------ |

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

@@ -8,7 +8,8 @@ Place this component once in your root layout. Elements with `data-aoe` attribut
 #### 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
+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
 
  
 
@@ -58,26 +59,34 @@ onMount(() => {
         }
         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 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) {
+        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_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 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: EL_ROOT_MARGIN,
-            threshold: EL_THRESHOLD
+            rootMargin: ROOT_MARGIN,
+            threshold: THRESHOLD
         });
         OBSERVER.observe(el);
     }

package/dist/index.svelte.d.ts

@@ -23,7 +23,8 @@ export type IndexSlots = typeof __propDef.slots;
  * #### 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
+ * 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
  *
  *  
  *

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;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"}
+{"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": "2.0.0",
+	"version": "2.1.0",
 	"description": "A Svelte component to animate elements, with no dependencies.",
 	"license": "MIT",
 	"keywords": [