use-scroll-animate 4.2.0 → 4.4.0

package/dist/components/a11y.js

@@ -0,0 +1,224 @@
+import { e as getMotionSensitivity, a as MOTION_SENSITIVITY_LEVELS, d as configureComponents, j as adoptStyles } from '../chunks/base-BtJDNCB6.js';
+export { b as adaptKeyframes } from '../chunks/base-BtJDNCB6.js';
+import { C as COMPONENT_CATEGORIES } from '../chunks/index-tags-43Xtd01A.js';
+
+/**
+ * use-scroll-animate/components/a11y — accessibility toolkit (4.4).
+ *
+ * - Motion-sensitivity levels: `setMotionSensitivity('full' | 'gentle' | 'minimal' | 'static')`.
+ * - Static alternatives: what every component shows when motion is off, and
+ *   `staticAlternative(root)` to freeze any subtree at its final state.
+ * - `aria-live` conventions: one shared polite and one assertive region,
+ *   `announce(message, { politeness })`.
+ * - `auditMotionA11y(root)`: the rules the automated regression tests run
+ *   over every `<usa-*>` element — usable in your own tests too.
+ *
+ * ```ts
+ * import { setMotionSensitivity, announce, auditMotionA11y } from 'use-scroll-animate/components/a11y';
+ * setMotionSensitivity('gentle', true);           // no spins / zooms / parallax, remembered
+ * announce('3 items added to cart');               // polite live region
+ * expect(auditMotionA11y(document.body).errors).toEqual([]);
+ * ```
+ */
+const KEY = 'usa:sensitivity';
+/** What each level allows, for docs and settings UIs. */
+const MOTION_SENSITIVITY = {
+    full: { en: 'All motion', zh: '全部动效', allows: ['fade', 'translate', 'scale', 'rotate', 'parallax', 'loop', 'flash'] },
+    gentle: { en: 'Gentle — no spins, zooms or parallax', zh: '温和 —— 无旋转、缩放与视差', allows: ['fade', 'translate', 'loop'] },
+    minimal: { en: 'Minimal — fades only', zh: '最少 —— 仅淡入淡出', allows: ['fade'] },
+    static: { en: 'Static — no animation', zh: '静态 —— 无动画', allows: [] },
+};
+/** CSS applied at the `static` / `minimal` / `gentle` levels (also stops your own CSS animations under `static`). */
+const SENSITIVITY_CSS = 'html[data-usa-sensitivity="static"] *,html[data-usa-sensitivity="static"] *::before,html[data-usa-sensitivity="static"] *::after{animation:none!important;transition:none!important;scroll-behavior:auto!important}' +
+    'html[data-usa-sensitivity="minimal"] *,html[data-usa-sensitivity="minimal"] *::before,html[data-usa-sensitivity="minimal"] *::after{animation-duration:1ms!important;animation-iteration-count:1!important;scroll-behavior:auto!important}' +
+    'html[data-usa-sensitivity="gentle"]{--usa-parallax:0;--usa-tilt:0}';
+/**
+ * Set the motion-sensitivity level for every `<usa-*>` component and the page:
+ * sets `data-usa-sensitivity` on `<html>`, adapts component keyframes, and
+ * with `persist` remembers the choice (`restoreMotionSensitivity()`).
+ * Dispatches `usa:sensitivity` on `document`.
+ */
+function setMotionSensitivity(level, persist = false) {
+    if (!MOTION_SENSITIVITY_LEVELS.includes(level))
+        return;
+    configureComponents({ motionSensitivity: level });
+    adoptStyles('a11y-sensitivity', SENSITIVITY_CSS);
+    if (persist) {
+        try {
+            localStorage.setItem(KEY, level);
+        }
+        catch {
+            /* private mode */
+        }
+    }
+    if (level === 'static' && typeof document !== 'undefined')
+        staticAlternative(document.documentElement);
+    if (typeof document !== 'undefined')
+        document.dispatchEvent(new CustomEvent('usa:sensitivity', { detail: { level } }));
+}
+/** Re-apply a persisted level (call early on page load). Returns the active level. */
+function restoreMotionSensitivity() {
+    try {
+        const v = localStorage.getItem(KEY);
+        if (v && MOTION_SENSITIVITY_LEVELS.includes(v))
+            setMotionSensitivity(v);
+    }
+    catch {
+        /* ignore */
+    }
+    return getMotionSensitivity();
+}
+/** `true` when the current level allows a kind of motion (`'rotate'`, `'parallax'`, `'loop'`…). */
+function motionAllowed(kind, level = getMotionSensitivity()) {
+    return MOTION_SENSITIVITY[level].allows.includes(kind);
+}
+/** The static alternative of each category: what its elements show without motion. */
+const STATIC_ALTERNATIVES = {
+    reveal: 'Content visible in place; progress bars show the current value.',
+    text: 'Full final text (screen readers always get a plain copy).',
+    interaction: 'Normal hover / focus styles; no tilt, magnet or ripple.',
+    feedback: 'Spinners become a static busy indicator; progress shows its value; toasts appear without sliding.',
+    background: 'A still frame of the background (gradient / pattern); particles and marquees stop.',
+    transitions: 'Dialogs, accordions and views switch instantly.',
+    physics: 'Values jump to their target; drag still works, without inertia.',
+    cards: 'Cards are shown flat and fully readable; stacks become lists.',
+    click: 'Clicks work and states are announced; no bursts, confetti or deformation.',
+    ui: 'Tabs, drawers, sheets and popovers open instantly with focus management intact.',
+    page: 'Page transitions are instant; cursors and ambient layers are hidden.',
+    timeline: 'Every step is shown at its final state.',
+    gesture: 'Buttons / keys provide the same actions as swipes and pinches.',
+    svg: 'Drawings and icons are shown complete.',
+    webgl: 'A static poster image or CSS gradient instead of the shader.',
+    depth: 'Flat, front-facing layout.',
+    layout: 'Items reflow instantly.',
+    packs: 'Roles are styled but not animated.',
+};
+/**
+ * Freeze a subtree at its static alternative: finishes running animations
+ * (`finish()`, so content lands on its final state), marks the root with
+ * `data-usa-static` and returns an undo that removes the mark.
+ */
+function staticAlternative(root) {
+    const getAll = root.getAnimations;
+    if (typeof getAll === 'function') {
+        for (const a of getAll.call(root, { subtree: true })) {
+            try {
+                const it = a.effect?.getComputedTiming().iterations;
+                if (it === Infinity)
+                    a.cancel();
+                else
+                    a.finish();
+            }
+            catch {
+                /* finished already */
+            }
+        }
+    }
+    root.setAttribute('data-usa-static', '');
+    return () => root.removeAttribute('data-usa-static');
+}
+/** The ids of the shared live regions. */
+const LIVE_REGION_IDS = { polite: 'usa-live-polite', assertive: 'usa-live-assertive' };
+/** The shared live region (created once, visually hidden, `role="status"` / `role="alert"`). */
+function liveRegion(politeness = 'polite') {
+    if (typeof document === 'undefined' || !document.body)
+        return null;
+    const id = LIVE_REGION_IDS[politeness];
+    let el = document.getElementById(id);
+    if (!el) {
+        el = document.createElement('div');
+        el.id = id;
+        el.className = 'usa-sr';
+        el.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');
+        el.setAttribute('aria-live', politeness);
+        el.setAttribute('aria-atomic', 'true');
+        document.body.appendChild(el);
+    }
+    return el;
+}
+let lastMsg = '';
+let lastAt = 0;
+/**
+ * Announce a message through the shared live region. Conventions: `polite`
+ * for results of the user's own actions (added, saved, copied), `assertive`
+ * only for errors that block them. Identical messages within `dedupe` ms
+ * (default 500) are dropped; the region is cleared first so repeats are read.
+ */
+function announce(message, options = {}) {
+    const { politeness = 'polite', dedupe = 500 } = options;
+    const t = Date.now();
+    if (!message || (message === lastMsg && t - lastAt < dedupe))
+        return false;
+    lastMsg = message;
+    lastAt = t;
+    const el = liveRegion(politeness);
+    if (!el)
+        return false;
+    el.textContent = '';
+    el.textContent = message;
+    return true;
+}
+const FOCUSABLE = 'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+const NAMED_ROLES = ['button', 'switch', 'checkbox', 'slider', 'tab', 'progressbar', 'radiogroup', 'dialog'];
+function accessibleName(el) {
+    const label = el.getAttribute('aria-label');
+    if (label)
+        return label;
+    const by = el.getAttribute('aria-labelledby');
+    if (by)
+        return by.split(/\s+/).map((id) => el.ownerDocument.getElementById(id)?.textContent || '').join(' ').trim();
+    return (el.textContent || el.getAttribute('title') || '').trim();
+}
+/**
+ * Check a subtree against the library's motion-a11y rules:
+ * - `aria-hidden-focusable` (error): focusable content inside `aria-hidden`.
+ * - `role-name` (error): a widget role without an accessible name.
+ * - `range-value` (error): a slider / determinate progressbar without `aria-valuenow`.
+ * - `img-alt` (error): an `<img>` without `alt`.
+ * - `assertive-live` (warning): `aria-live="assertive"` outside `role="alert"`.
+ * - `infinite-no-control` (warning, WCAG 2.2.2): an endless animation on a
+ *   page with no way to pause motion (`<usa-motion-switch>` or `[data-usa-pause]`).
+ */
+function auditMotionA11y(root) {
+    const issues = [];
+    const add = (rule, level, element, message) => issues.push({ rule, level, element, message });
+    const scope = root;
+    scope.querySelectorAll('[aria-hidden="true"]').forEach((h) => {
+        const f = (h.matches(FOCUSABLE) ? [h] : Array.from(h.querySelectorAll(FOCUSABLE))).filter((x) => !x.closest('[inert]'));
+        f.forEach((x) => add('aria-hidden-focusable', 'error', x, `focusable <${x.tagName.toLowerCase()}> inside aria-hidden`));
+    });
+    scope.querySelectorAll('[role]').forEach((el) => {
+        const role = el.getAttribute('role');
+        if (NAMED_ROLES.includes(role) && !accessibleName(el))
+            add('role-name', 'error', el, `role="${role}" has no accessible name`);
+        if (role === 'slider' && !el.hasAttribute('aria-valuenow'))
+            add('range-value', 'error', el, 'slider without aria-valuenow');
+    });
+    scope.querySelectorAll('img:not([alt])').forEach((el) => add('img-alt', 'error', el, '<img> without alt'));
+    scope.querySelectorAll('[aria-live="assertive"]').forEach((el) => {
+        if (el.getAttribute('role') !== 'alert')
+            add('assertive-live', 'warning', el, 'assertive live region outside role="alert"');
+    });
+    const doc = root.ownerDocument || root;
+    const anims = typeof root.getAnimations === 'function' ? root.getAnimations({ subtree: true }) : [];
+    const control = doc && (doc.querySelector('usa-motion-switch, [data-usa-pause]') || doc.documentElement.hasAttribute('data-usa-sensitivity'));
+    if (!control)
+        anims.forEach((a) => {
+            try {
+                if (a.effect?.getComputedTiming().iterations === Infinity) {
+                    const t = a.effect.target;
+                    if (t)
+                        add('infinite-no-control', 'warning', t, 'endless animation and no motion control on the page');
+                }
+            }
+            catch {
+                /* ignore */
+            }
+        });
+    return { errors: issues.filter((i) => i.level === 'error'), warnings: issues.filter((i) => i.level === 'warning') };
+}
+/** Every `<usa-*>` tag, for sweeping audits. */
+const ALL_TAGS = Object.values(COMPONENT_CATEGORIES).flat();
+
+export { ALL_TAGS, LIVE_REGION_IDS, MOTION_SENSITIVITY, MOTION_SENSITIVITY_LEVELS, SENSITIVITY_CSS, STATIC_ALTERNATIVES, announce, auditMotionA11y, getMotionSensitivity, liveRegion, motionAllowed, restoreMotionSensitivity, setMotionSensitivity, staticAlternative };
+//# sourceMappingURL=a11y.js.map

package/dist/components/a11y.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.js","sources":["../../src/components/a11y/index.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/a11y — accessibility toolkit (4.4).\n *\n * - Motion-sensitivity levels: `setMotionSensitivity('full' | 'gentle' | 'minimal' | 'static')`.\n * - Static alternatives: what every component shows when motion is off, and\n *   `staticAlternative(root)` to freeze any subtree at its final state.\n * - `aria-live` conventions: one shared polite and one assertive region,\n *   `announce(message, { politeness })`.\n * - `auditMotionA11y(root)`: the rules the automated regression tests run\n *   over every `<usa-*>` element — usable in your own tests too.\n *\n * ```ts\n * import { setMotionSensitivity, announce, auditMotionA11y } from 'use-scroll-animate/components/a11y';\n * setMotionSensitivity('gentle', true);           // no spins / zooms / parallax, remembered\n * announce('3 items added to cart');               // polite live region\n * expect(auditMotionA11y(document.body).errors).toEqual([]);\n * ```\n */\nimport {\n  configureComponents,\n  getMotionSensitivity,\n  adaptKeyframes,\n  adoptStyles,\n  MOTION_SENSITIVITY_LEVELS,\n  type MotionSensitivity,\n} from '../base';\nimport { COMPONENT_CATEGORIES, type ComponentCategory } from '../index-tags';\n\nexport { getMotionSensitivity, adaptKeyframes, MOTION_SENSITIVITY_LEVELS };\nexport type { MotionSensitivity };\n\nconst KEY = 'usa:sensitivity';\n\n/** What each level allows, for docs and settings UIs. */\nexport const MOTION_SENSITIVITY: Record<MotionSensitivity, { en: string; zh: string; allows: string[] }> = {\n  full: { en: 'All motion', zh: '全部动效', allows: ['fade', 'translate', 'scale', 'rotate', 'parallax', 'loop', 'flash'] },\n  gentle: { en: 'Gentle — no spins, zooms or parallax', zh: '温和 —— 无旋转、缩放与视差', allows: ['fade', 'translate', 'loop'] },\n  minimal: { en: 'Minimal — fades only', zh: '最少 —— 仅淡入淡出', allows: ['fade'] },\n  static: { en: 'Static — no animation', zh: '静态 —— 无动画', allows: [] },\n};\n\n/** CSS applied at the `static` / `minimal` / `gentle` levels (also stops your own CSS animations under `static`). */\nexport const SENSITIVITY_CSS =\n  'html[data-usa-sensitivity=\"static\"] *,html[data-usa-sensitivity=\"static\"] *::before,html[data-usa-sensitivity=\"static\"] *::after{animation:none!important;transition:none!important;scroll-behavior:auto!important}' +\n  'html[data-usa-sensitivity=\"minimal\"] *,html[data-usa-sensitivity=\"minimal\"] *::before,html[data-usa-sensitivity=\"minimal\"] *::after{animation-duration:1ms!important;animation-iteration-count:1!important;scroll-behavior:auto!important}' +\n  'html[data-usa-sensitivity=\"gentle\"]{--usa-parallax:0;--usa-tilt:0}';\n\n/**\n * Set the motion-sensitivity level for every `<usa-*>` component and the page:\n * sets `data-usa-sensitivity` on `<html>`, adapts component keyframes, and\n * with `persist` remembers the choice (`restoreMotionSensitivity()`).\n * Dispatches `usa:sensitivity` on `document`.\n */\nexport function setMotionSensitivity(level: MotionSensitivity, persist = false): void {\n  if (!MOTION_SENSITIVITY_LEVELS.includes(level)) return;\n  configureComponents({ motionSensitivity: level });\n  adoptStyles('a11y-sensitivity', SENSITIVITY_CSS);\n  if (persist) {\n    try {\n      localStorage.setItem(KEY, level);\n    } catch {\n      /* private mode */\n    }\n  }\n  if (level === 'static' && typeof document !== 'undefined') staticAlternative(document.documentElement);\n  if (typeof document !== 'undefined') document.dispatchEvent(new CustomEvent('usa:sensitivity', { detail: { level } }));\n}\n\n/** Re-apply a persisted level (call early on page load). Returns the active level. */\nexport function restoreMotionSensitivity(): MotionSensitivity {\n  try {\n    const v = localStorage.getItem(KEY) as MotionSensitivity | null;\n    if (v && MOTION_SENSITIVITY_LEVELS.includes(v)) setMotionSensitivity(v);\n  } catch {\n    /* ignore */\n  }\n  return getMotionSensitivity();\n}\n\n/** `true` when the current level allows a kind of motion (`'rotate'`, `'parallax'`, `'loop'`…). */\nexport function motionAllowed(kind: string, level: MotionSensitivity = getMotionSensitivity()): boolean {\n  return MOTION_SENSITIVITY[level].allows.includes(kind);\n}\n\n/** The static alternative of each category: what its elements show without motion. */\nexport const STATIC_ALTERNATIVES: Record<ComponentCategory, string> = {\n  reveal: 'Content visible in place; progress bars show the current value.',\n  text: 'Full final text (screen readers always get a plain copy).',\n  interaction: 'Normal hover / focus styles; no tilt, magnet or ripple.',\n  feedback: 'Spinners become a static busy indicator; progress shows its value; toasts appear without sliding.',\n  background: 'A still frame of the background (gradient / pattern); particles and marquees stop.',\n  transitions: 'Dialogs, accordions and views switch instantly.',\n  physics: 'Values jump to their target; drag still works, without inertia.',\n  cards: 'Cards are shown flat and fully readable; stacks become lists.',\n  click: 'Clicks work and states are announced; no bursts, confetti or deformation.',\n  ui: 'Tabs, drawers, sheets and popovers open instantly with focus management intact.',\n  page: 'Page transitions are instant; cursors and ambient layers are hidden.',\n  timeline: 'Every step is shown at its final state.',\n  gesture: 'Buttons / keys provide the same actions as swipes and pinches.',\n  svg: 'Drawings and icons are shown complete.',\n  webgl: 'A static poster image or CSS gradient instead of the shader.',\n  depth: 'Flat, front-facing layout.',\n  layout: 'Items reflow instantly.',\n  packs: 'Roles are styled but not animated.',\n};\n\n/**\n * Freeze a subtree at its static alternative: finishes running animations\n * (`finish()`, so content lands on its final state), marks the root with\n * `data-usa-static` and returns an undo that removes the mark.\n */\nexport function staticAlternative(root: Element): () => void {\n  const getAll = (root as any).getAnimations as undefined | ((o: { subtree: boolean }) => Animation[]);\n  if (typeof getAll === 'function') {\n    for (const a of getAll.call(root, { subtree: true })) {\n      try {\n        const it = a.effect?.getComputedTiming().iterations;\n        if (it === Infinity) a.cancel();\n        else a.finish();\n      } catch {\n        /* finished already */\n      }\n    }\n  }\n  root.setAttribute('data-usa-static', '');\n  return () => root.removeAttribute('data-usa-static');\n}\n\n// --- aria-live conventions ---------------------------------------------------\n\nexport type Politeness = 'polite' | 'assertive';\n/** The ids of the shared live regions. */\nexport const LIVE_REGION_IDS: Record<Politeness, string> = { polite: 'usa-live-polite', assertive: 'usa-live-assertive' };\n\n/** The shared live region (created once, visually hidden, `role=\"status\"` / `role=\"alert\"`). */\nexport function liveRegion(politeness: Politeness = 'polite'): HTMLElement | null {\n  if (typeof document === 'undefined' || !document.body) return null;\n  const id = LIVE_REGION_IDS[politeness];\n  let el = document.getElementById(id);\n  if (!el) {\n    el = document.createElement('div');\n    el.id = id;\n    el.className = 'usa-sr';\n    el.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');\n    el.setAttribute('aria-live', politeness);\n    el.setAttribute('aria-atomic', 'true');\n    document.body.appendChild(el);\n  }\n  return el;\n}\n\nlet lastMsg = '';\nlet lastAt = 0;\n/**\n * Announce a message through the shared live region. Conventions: `polite`\n * for results of the user's own actions (added, saved, copied), `assertive`\n * only for errors that block them. Identical messages within `dedupe` ms\n * (default 500) are dropped; the region is cleared first so repeats are read.\n */\nexport function announce(message: string, options: { politeness?: Politeness; dedupe?: number } = {}): boolean {\n  const { politeness = 'polite', dedupe = 500 } = options;\n  const t = Date.now();\n  if (!message || (message === lastMsg && t - lastAt < dedupe)) return false;\n  lastMsg = message;\n  lastAt = t;\n  const el = liveRegion(politeness);\n  if (!el) return false;\n  el.textContent = '';\n  el.textContent = message;\n  return true;\n}\n\n// --- audit ---------------------------------------------------------------------\n\nexport interface A11yIssue {\n  rule: string;\n  level: 'error' | 'warning';\n  element: Element;\n  message: string;\n}\n\nconst FOCUSABLE = 'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex=\"-1\"])';\nconst NAMED_ROLES = ['button', 'switch', 'checkbox', 'slider', 'tab', 'progressbar', 'radiogroup', 'dialog'];\n\nfunction accessibleName(el: Element): string {\n  const label = el.getAttribute('aria-label');\n  if (label) return label;\n  const by = el.getAttribute('aria-labelledby');\n  if (by) return by.split(/\\s+/).map((id) => el.ownerDocument.getElementById(id)?.textContent || '').join(' ').trim();\n  return (el.textContent || el.getAttribute('title') || '').trim();\n}\n\n/**\n * Check a subtree against the library's motion-a11y rules:\n * - `aria-hidden-focusable` (error): focusable content inside `aria-hidden`.\n * - `role-name` (error): a widget role without an accessible name.\n * - `range-value` (error): a slider / determinate progressbar without `aria-valuenow`.\n * - `img-alt` (error): an `<img>` without `alt`.\n * - `assertive-live` (warning): `aria-live=\"assertive\"` outside `role=\"alert\"`.\n * - `infinite-no-control` (warning, WCAG 2.2.2): an endless animation on a\n *   page with no way to pause motion (`<usa-motion-switch>` or `[data-usa-pause]`).\n */\nexport function auditMotionA11y(root: Element | Document): { errors: A11yIssue[]; warnings: A11yIssue[] } {\n  const issues: A11yIssue[] = [];\n  const add = (rule: string, level: A11yIssue['level'], element: Element, message: string) => issues.push({ rule, level, element, message });\n  const scope = root as ParentNode;\n  scope.querySelectorAll('[aria-hidden=\"true\"]').forEach((h) => {\n    const f = (h.matches(FOCUSABLE) ? [h] : Array.from(h.querySelectorAll(FOCUSABLE))).filter((x) => !x.closest('[inert]'));\n    f.forEach((x) => add('aria-hidden-focusable', 'error', x, `focusable <${x.tagName.toLowerCase()}> inside aria-hidden`));\n  });\n  scope.querySelectorAll('[role]').forEach((el) => {\n    const role = el.getAttribute('role')!;\n    if (NAMED_ROLES.includes(role) && !accessibleName(el)) add('role-name', 'error', el, `role=\"${role}\" has no accessible name`);\n    if (role === 'slider' && !el.hasAttribute('aria-valuenow'))\n      add('range-value', 'error', el, 'slider without aria-valuenow');\n  });\n  scope.querySelectorAll('img:not([alt])').forEach((el) => add('img-alt', 'error', el, '<img> without alt'));\n  scope.querySelectorAll('[aria-live=\"assertive\"]').forEach((el) => {\n    if (el.getAttribute('role') !== 'alert') add('assertive-live', 'warning', el, 'assertive live region outside role=\"alert\"');\n  });\n  const doc = (root as Node).ownerDocument || (root as Document);\n  const anims = typeof (root as any).getAnimations === 'function' ? ((root as any).getAnimations({ subtree: true }) as Animation[]) : [];\n  const control = doc && (doc.querySelector('usa-motion-switch, [data-usa-pause]') || doc.documentElement.hasAttribute('data-usa-sensitivity'));\n  if (!control)\n    anims.forEach((a) => {\n      try {\n        if (a.effect?.getComputedTiming().iterations === Infinity) {\n          const t = (a.effect as KeyframeEffect).target;\n          if (t) add('infinite-no-control', 'warning', t, 'endless animation and no motion control on the page');\n        }\n      } catch {\n        /* ignore */\n      }\n    });\n  return { errors: issues.filter((i) => i.level === 'error'), warnings: issues.filter((i) => i.level === 'warning') };\n}\n\n/** Every `<usa-*>` tag, for sweeping audits. */\nexport const ALL_TAGS: string[] = (Object.values(COMPONENT_CATEGORIES) as readonly (readonly string[])[]).flat();\n"],"names":[],"mappings":"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"}

package/dist/components/angular.cjs

@@ -3,29 +3,30 @@
 var components = require('../components.cjs');
 var bind = require('../chunks/bind-Ui43-n2d.cjs');
 require('./reveal.cjs');
-require('../chunks/base-CXx7jZ-o.cjs');
+require('../chunks/base-DE2yzxE7.cjs');
 require('./text.cjs');
+require('../chunks/core-BC9S2osy.cjs');
+require('./tokens.cjs');
 require('./interaction.cjs');
 require('./feedback.cjs');
 require('./background.cjs');
-require('../chunks/variants-BNIrn4ch.cjs');
+require('../chunks/variants-CM2zaG8v.cjs');
 require('./transitions.cjs');
 require('./physics.cjs');
-require('../chunks/spring-2OTnYCzm.cjs');
+require('../chunks/spring-hsmgd7ml.cjs');
 require('./cards.cjs');
 require('./click.cjs');
 require('./ui.cjs');
 require('./page.cjs');
 require('./timeline.cjs');
-require('../chunks/core-BRIIoKeS.cjs');
-require('./tokens.cjs');
 require('./gesture.cjs');
-require('../chunks/core-IaorbTdu.cjs');
+require('../chunks/core-DPYjLqA0.cjs');
 require('./svg.cjs');
 require('./webgl.cjs');
 require('./depth.cjs');
 require('./layout.cjs');
 require('./packs.cjs');
+require('./a11y.cjs');
 require('../chunks/index-tags-BQh_uGqH.cjs');
 
 /**

package/dist/components/angular.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"angular.cjs","sources":["../../src/components/frameworks/angular.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/angular — Angular integration (v3.8).\n * Angular renders `<usa-*>` tags once the component (or NgModule) allows\n * custom elements with `CUSTOM_ELEMENTS_SCHEMA`; property binding\n * `[checked]=\"on\"` and event binding `(usa:change)=\"…\"` then work as is.\n * This entry is framework-free (no `@angular/*` import):\n *\n * ```ts\n * import { CUSTOM_ELEMENTS_SCHEMA, Component, APP_INITIALIZER } from '@angular/core';\n * import { usaInitializer } from 'use-scroll-animate/components/angular';\n *\n * // app.config.ts\n * providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer(['click', 'ui']) }]\n *\n * @Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],\n *   template: `<usa-toggle [checked]=\"on\" (usa:change)=\"on = $any($event).detail.checked\"></usa-toggle>` })\n * ```\n * `bindUsa(el, { props, on })` is available for directives that bind imperatively.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** `APP_INITIALIZER` factory: registers the elements in the browser (no-op during SSR). */\nexport function usaInitializer(categories?: ComponentCategory[]): () => () => void {\n  return () => () => {\n    if (typeof window !== 'undefined') defineComponents(categories);\n  };\n}\n\n/** Register the elements directly (e.g. in `main.ts` before `bootstrapApplication`). */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n\n/** Read `event.detail` from a `usa:*` event in a template handler: `(usa:change)=\"on = usaDetail($event).checked\"`. */\nexport const usaDetail = <T = any>(e: Event): T => (e as CustomEvent<T>).detail;\n"],"names":["defineComponents"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;AAkBG;AAMH;AACM,SAAU,cAAc,CAAC,UAAgC,EAAA;AAC7D,IAAA,OAAO,MAAM,MAAK;QAChB,IAAI,OAAO,MAAM,KAAK,WAAW;YAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE,IAAA,CAAC;AACH;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE;AAEA;AACO,MAAM,SAAS,GAAG,CAAU,CAAQ,KAAS,CAAoB,CAAC;;;;;;;;"}
+{"version":3,"file":"angular.cjs","sources":["../../src/components/frameworks/angular.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/angular — Angular integration (v3.8).\n * Angular renders `<usa-*>` tags once the component (or NgModule) allows\n * custom elements with `CUSTOM_ELEMENTS_SCHEMA`; property binding\n * `[checked]=\"on\"` and event binding `(usa:change)=\"…\"` then work as is.\n * This entry is framework-free (no `@angular/*` import):\n *\n * ```ts\n * import { CUSTOM_ELEMENTS_SCHEMA, Component, APP_INITIALIZER } from '@angular/core';\n * import { usaInitializer } from 'use-scroll-animate/components/angular';\n *\n * // app.config.ts\n * providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer(['click', 'ui']) }]\n *\n * @Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],\n *   template: `<usa-toggle [checked]=\"on\" (usa:change)=\"on = $any($event).detail.checked\"></usa-toggle>` })\n * ```\n * `bindUsa(el, { props, on })` is available for directives that bind imperatively.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** `APP_INITIALIZER` factory: registers the elements in the browser (no-op during SSR). */\nexport function usaInitializer(categories?: ComponentCategory[]): () => () => void {\n  return () => () => {\n    if (typeof window !== 'undefined') defineComponents(categories);\n  };\n}\n\n/** Register the elements directly (e.g. in `main.ts` before `bootstrapApplication`). */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n\n/** Read `event.detail` from a `usa:*` event in a template handler: `(usa:change)=\"on = usaDetail($event).checked\"`. */\nexport const usaDetail = <T = any>(e: Event): T => (e as CustomEvent<T>).detail;\n"],"names":["defineComponents"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;AAkBG;AAMH;AACM,SAAU,cAAc,CAAC,UAAgC,EAAA;AAC7D,IAAA,OAAO,MAAM,MAAK;QAChB,IAAI,OAAO,MAAM,KAAK,WAAW;YAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE,IAAA,CAAC;AACH;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE;AAEA;AACO,MAAM,SAAS,GAAG,CAAU,CAAQ,KAAS,CAAoB,CAAC;;;;;;;;"}

package/dist/components/angular.d.cts

@@ -117,7 +117,11 @@ interface UsaTypewriterElement extends UsaElement {
  * them in a cascade (pure CSS animation per unit, transform / opacity /
  * filter only). Words never break across lines.
  *
- * Attributes: `by` (`chars` | `words`, default `chars`), `effect`
+ * 4.3: `Intl.Segmenter`-aware (emoji, CJK words), Arabic-script words are
+ * never split below the word, `by="lines"` reveals line by line, and `from`
+ * (`start` · `end` · `center` · `edges` · `random`) sets the cascade order.
+ *
+ * Attributes: `by` (`chars` | `words` | `lines`, default `chars`), `effect`
  * (`rise` | `fade` | `blur` | `flip` | `pop`, default `rise`), `stagger`
  * (ms between units, 28 for chars / 70 for words), `duration` (ms, 620),
  * `delay` (ms, 0), `trigger` (`view` | `load` | `manual`, default `view`),
@@ -230,6 +234,81 @@ interface UsaScrollHighlightElement extends UsaElement {
     readonly progress: number;
 }
 
+/**
+ * Where a step starts on a timeline:
+ * - a number: absolute time in ms
+ * - `'>'` (default): when the previous step ends · `'<'`: when it starts
+ * - `'+=200'` / `'-=200'`: after / overlapping the previous end
+ * - `'<+=100'`: 100ms after the previous step's start
+ * - `'intro'` / `'intro+=150'`: at (or relative to) a label
+ */
+type TimelinePosition = number | string;
+interface TimelineStepOptions {
+    /** Duration in ms or a motion token name (`'fast'`, `'slow'`…; 4.2). Default: timeline default, 600. */
+    duration?: number | string;
+    /** CSS easing or a motion token name (`'emphasized'`, `'spring'`…; 4.2). Default `cubic-bezier(0.22, 1, 0.36, 1)`. */
+    easing?: string;
+    /** Start position, see `TimelinePosition`. */
+    at?: TimelinePosition;
+    /** ms between targets when the selector matches several elements. */
+    stagger?: number;
+}
+interface ScrubOptions {
+    /** Scroll offset (px) before the source's top reaches the viewport bottom where progress starts (JS engine only). */
+    offset?: number;
+    /** Smoothing 0–1 (0 = immediate, default 0). Smoothing needs the JS engine. */
+    smooth?: number;
+    /**
+     * 4.1: which progress source drives the timeline.
+     * - `'view'` (default): `source` moving through the viewport (CSS `ViewTimeline`, range `cover`).
+     * - `'scroll'`: the scroll position of `source` itself (a scroll container; CSS `ScrollTimeline`).
+     */
+    source?: 'view' | 'scroll';
+    /** 4.1: `'auto'` (default) uses the browser's native scroll-driven animations when available, `'js'` forces the fallback. */
+    engine?: 'auto' | 'native' | 'js';
+    /** 4.1: scroll axis, `'block'` (default) · `'inline'` · `'x'` · `'y'`. */
+    axis?: 'block' | 'inline' | 'x' | 'y';
+}
+/** The function `scrub()` returns: call it to stop. `native` tells which engine runs it. */
+interface ScrubHandle {
+    (): void;
+    /** `true` when the browser's ScrollTimeline / ViewTimeline drives it (compositor, no JS per frame). */
+    readonly native: boolean;
+}
+interface Timeline {
+    /** Total length in ms. */
+    readonly duration: number;
+    /** Label positions in ms. */
+    readonly labels: Readonly<Record<string, number>>;
+    /** Current playhead in ms. */
+    readonly time: number;
+    /** Add a step: animate `target` with keyframes or a preset name (`fade-up`, `scale`…). */
+    to(target: string | Element | Element[] | NodeList, frames: Keyframe[] | string, options?: TimelineStepOptions): Timeline;
+    /** Name a position (default: the current end). */
+    label(name: string, at?: TimelinePosition): Timeline;
+    /** Run `fn` when the playhead passes `at`. */
+    call(fn: () => void, at?: TimelinePosition): Timeline;
+    /** Play forwards from the playhead (from 0 when at the end). Resolves at the end. */
+    play(from?: TimelinePosition): Promise<void>;
+    /** Play backwards to 0. */
+    reverse(): Promise<void>;
+    pause(): Timeline;
+    /** Jump to a time (ms) or label. */
+    seek(to: TimelinePosition): Timeline;
+    /** Get or set progress 0–1. */
+    progress(p?: number): number;
+    /**
+     * Tie progress to scroll: `source` moving through the viewport (or, with
+     * `{ source: 'scroll' }`, a scroll container's own position). Runs on native
+     * ScrollTimeline / ViewTimeline when available (and no `smooth`, `offset`,
+     * `call()` cues or `onUpdate` need JS), else on a rAF-throttled listener.
+     * Returns a stop function with a `native` flag.
+     */
+    scrub(source: Element, options?: ScrubOptions): ScrubHandle;
+    /** Stop and drop every animation (elements keep their last frame). */
+    cancel(): void;
+}
+
 /**
  * use-scroll-animate/components/text — text effects.
  * `<usa-typewriter>`, `<usa-split-text>`, `<usa-scramble>`, `<usa-counter>`,
@@ -1275,81 +1354,6 @@ declare global {
     }
 }
 
-/**
- * Where a step starts on a timeline:
- * - a number: absolute time in ms
- * - `'>'` (default): when the previous step ends · `'<'`: when it starts
- * - `'+=200'` / `'-=200'`: after / overlapping the previous end
- * - `'<+=100'`: 100ms after the previous step's start
- * - `'intro'` / `'intro+=150'`: at (or relative to) a label
- */
-type TimelinePosition = number | string;
-interface TimelineStepOptions {
-    /** Duration in ms or a motion token name (`'fast'`, `'slow'`…; 4.2). Default: timeline default, 600. */
-    duration?: number | string;
-    /** CSS easing or a motion token name (`'emphasized'`, `'spring'`…; 4.2). Default `cubic-bezier(0.22, 1, 0.36, 1)`. */
-    easing?: string;
-    /** Start position, see `TimelinePosition`. */
-    at?: TimelinePosition;
-    /** ms between targets when the selector matches several elements. */
-    stagger?: number;
-}
-interface ScrubOptions {
-    /** Scroll offset (px) before the source's top reaches the viewport bottom where progress starts (JS engine only). */
-    offset?: number;
-    /** Smoothing 0–1 (0 = immediate, default 0). Smoothing needs the JS engine. */
-    smooth?: number;
-    /**
-     * 4.1: which progress source drives the timeline.
-     * - `'view'` (default): `source` moving through the viewport (CSS `ViewTimeline`, range `cover`).
-     * - `'scroll'`: the scroll position of `source` itself (a scroll container; CSS `ScrollTimeline`).
-     */
-    source?: 'view' | 'scroll';
-    /** 4.1: `'auto'` (default) uses the browser's native scroll-driven animations when available, `'js'` forces the fallback. */
-    engine?: 'auto' | 'native' | 'js';
-    /** 4.1: scroll axis, `'block'` (default) · `'inline'` · `'x'` · `'y'`. */
-    axis?: 'block' | 'inline' | 'x' | 'y';
-}
-/** The function `scrub()` returns: call it to stop. `native` tells which engine runs it. */
-interface ScrubHandle {
-    (): void;
-    /** `true` when the browser's ScrollTimeline / ViewTimeline drives it (compositor, no JS per frame). */
-    readonly native: boolean;
-}
-interface Timeline {
-    /** Total length in ms. */
-    readonly duration: number;
-    /** Label positions in ms. */
-    readonly labels: Readonly<Record<string, number>>;
-    /** Current playhead in ms. */
-    readonly time: number;
-    /** Add a step: animate `target` with keyframes or a preset name (`fade-up`, `scale`…). */
-    to(target: string | Element | Element[] | NodeList, frames: Keyframe[] | string, options?: TimelineStepOptions): Timeline;
-    /** Name a position (default: the current end). */
-    label(name: string, at?: TimelinePosition): Timeline;
-    /** Run `fn` when the playhead passes `at`. */
-    call(fn: () => void, at?: TimelinePosition): Timeline;
-    /** Play forwards from the playhead (from 0 when at the end). Resolves at the end. */
-    play(from?: TimelinePosition): Promise<void>;
-    /** Play backwards to 0. */
-    reverse(): Promise<void>;
-    pause(): Timeline;
-    /** Jump to a time (ms) or label. */
-    seek(to: TimelinePosition): Timeline;
-    /** Get or set progress 0–1. */
-    progress(p?: number): number;
-    /**
-     * Tie progress to scroll: `source` moving through the viewport (or, with
-     * `{ source: 'scroll' }`, a scroll container's own position). Runs on native
-     * ScrollTimeline / ViewTimeline when available (and no `smooth`, `offset`,
-     * `call()` cues or `onUpdate` need JS), else on a rAF-throttled listener.
-     * Returns a stop function with a `native` flag.
-     */
-    scrub(source: Element, options?: ScrubOptions): ScrubHandle;
-    /** Stop and drop every animation (elements keep their last frame). */
-    cancel(): void;
-}
-
 /**
  * `<usa-timeline>` — declarative choreography. Every descendant with
  * `data-tl="<preset>"` becomes a step, in document order; `data-at`