use-scroll-animate 4.2.0 → 4.4.0

package/dist/components/svelte.d.ts

@@ -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`

package/dist/components/svelte.js

@@ -2,29 +2,30 @@ import { defineComponents } from '../components.js';
 import { b as bindUsa } from '../chunks/bind-B_CTL6Qn.js';
 export { u as usaEventName } from '../chunks/bind-B_CTL6Qn.js';
 import './reveal.js';
-import '../chunks/base-BPG5zvex.js';
+import '../chunks/base-BtJDNCB6.js';
 import './text.js';
+import '../chunks/core-DS1nrx5L.js';
+import './tokens.js';
 import './interaction.js';
 import './feedback.js';
 import './background.js';
-import '../chunks/variants-BVYMcxRv.js';
+import '../chunks/variants-dD6SbUMR.js';
 import './transitions.js';
 import './physics.js';
-import '../chunks/spring-BziPsW3r.js';
+import '../chunks/spring-CxRz49Wk.js';
 import './cards.js';
 import './click.js';
 import './ui.js';
 import './page.js';
 import './timeline.js';
-import '../chunks/core-LkGRmgES.js';
-import './tokens.js';
 import './gesture.js';
-import '../chunks/core-eXX8rB_b.js';
+import '../chunks/core-DX6pdOoY.js';
 import './svg.js';
 import './webgl.js';
 import './depth.js';
 import './layout.js';
 import './packs.js';
+import './a11y.js';
 import '../chunks/index-tags-43Xtd01A.js';
 
 /**

package/dist/components/svelte.js.map

@@ -1 +1 @@
-{"version":3,"file":"svelte.js","sources":["../../src/components/frameworks/svelte.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/svelte — Svelte integration (v3.8).\n * Svelte (3, 4, 5) renders `<usa-*>` tags natively; `use:usa` sets\n * **properties** and `usa:*` listeners in one place, and `defineUsa()`\n * registers the elements on the client only (safe in SvelteKit SSR).\n *\n * ```svelte\n * <script>\n *   import { usa, defineUsa } from 'use-scroll-animate/components/svelte';\n *   import { onMount } from 'svelte';\n *   onMount(() => defineUsa(['click', 'ui']));\n *   let on = false;\n * </script>\n * <usa-toggle use:usa={{ props: { checked: on }, on: { change: (e) => (on = e.detail.checked) } }}></usa-toggle>\n * ```\n * Plain `on:usa:change` does not compile in Svelte 3/4 (colon); use the action or `onusa:change` in Svelte 5.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\nimport { bindUsa, type UsaBinding } from './bind';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** Svelte action: `use:usa={{ props, on }}`. */\nexport function usa(node: HTMLElement, binding: UsaBinding = {}): { update(b: UsaBinding): void; destroy(): void } {\n  return bindUsa(node, binding);\n}\n\n/** Register the elements (all, or some categories) — call from `onMount` for SSR apps. */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;AAgBG;AAOH;SACgB,GAAG,CAAC,IAAiB,EAAE,UAAsB,EAAE,EAAA;AAC7D,IAAA,OAAO,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;AAC/B;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,gBAAgB,CAAC,UAAU,CAAC;AACjE;;;;"}
+{"version":3,"file":"svelte.js","sources":["../../src/components/frameworks/svelte.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/svelte — Svelte integration (v3.8).\n * Svelte (3, 4, 5) renders `<usa-*>` tags natively; `use:usa` sets\n * **properties** and `usa:*` listeners in one place, and `defineUsa()`\n * registers the elements on the client only (safe in SvelteKit SSR).\n *\n * ```svelte\n * <script>\n *   import { usa, defineUsa } from 'use-scroll-animate/components/svelte';\n *   import { onMount } from 'svelte';\n *   onMount(() => defineUsa(['click', 'ui']));\n *   let on = false;\n * </script>\n * <usa-toggle use:usa={{ props: { checked: on }, on: { change: (e) => (on = e.detail.checked) } }}></usa-toggle>\n * ```\n * Plain `on:usa:change` does not compile in Svelte 3/4 (colon); use the action or `onusa:change` in Svelte 5.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\nimport { bindUsa, type UsaBinding } from './bind';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** Svelte action: `use:usa={{ props, on }}`. */\nexport function usa(node: HTMLElement, binding: UsaBinding = {}): { update(b: UsaBinding): void; destroy(): void } {\n  return bindUsa(node, binding);\n}\n\n/** Register the elements (all, or some categories) — call from `onMount` for SSR apps. */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;AAgBG;AAOH;SACgB,GAAG,CAAC,IAAiB,EAAE,UAAsB,EAAE,EAAA;AAC7D,IAAA,OAAO,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;AAC/B;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,gBAAgB,CAAC,UAAU,CAAC;AACjE;;;;"}

package/dist/components/svg.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var base = require('../chunks/base-CXx7jZ-o.cjs');
+var base = require('../chunks/base-DE2yzxE7.cjs');
 
 const NUM = /-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/gi;
 /** `true` when two path strings share the same commands (so their numbers can be interpolated). */

package/dist/components/svg.d.cts

@@ -27,7 +27,17 @@ interface ComponentsConfig {
      * 1.25) on `<html>` for your own CSS. See `setMotionIntensity()`.
      */
     motionIntensity?: MotionIntensity;
+    /**
+     * Motion-sensitivity level (v4.4), finer than reduced motion:
+     * `'full'` (default) · `'gentle'` (no spins, zooms, skews or parallax —
+     * translations and fades only, safe for vestibular disorders) ·
+     * `'minimal'` (fades only; components use their reduced-motion variants) ·
+     * `'static'` (no animation: every component shows its static alternative).
+     * See `setMotionSensitivity()` in `use-scroll-animate/components/a11y`.
+     */
+    motionSensitivity?: MotionSensitivity;
 }
+type MotionSensitivity = 'full' | 'gentle' | 'minimal' | 'static';
 type MotionIntensity = 'off' | 'low' | 'normal' | 'high';
 /** Change global component settings (call before `define*()` for `injectStyles`). */
 declare function configureComponents(options: ComponentsConfig): void;

package/dist/components/svg.d.ts

@@ -27,7 +27,17 @@ interface ComponentsConfig {
      * 1.25) on `<html>` for your own CSS. See `setMotionIntensity()`.
      */
     motionIntensity?: MotionIntensity;
+    /**
+     * Motion-sensitivity level (v4.4), finer than reduced motion:
+     * `'full'` (default) · `'gentle'` (no spins, zooms, skews or parallax —
+     * translations and fades only, safe for vestibular disorders) ·
+     * `'minimal'` (fades only; components use their reduced-motion variants) ·
+     * `'static'` (no animation: every component shows its static alternative).
+     * See `setMotionSensitivity()` in `use-scroll-animate/components/a11y`.
+     */
+    motionSensitivity?: MotionSensitivity;
 }
+type MotionSensitivity = 'full' | 'gentle' | 'minimal' | 'static';
 type MotionIntensity = 'off' | 'low' | 'normal' | 'high';
 /** Change global component settings (call before `define*()` for `injectStyles`). */
 declare function configureComponents(options: ComponentsConfig): void;

package/dist/components/svg.js

@@ -1,5 +1,5 @@
-import { b as clamp, m as motionScale, d as caf, p as prefersReducedMotion, n as now, r as raf, h as defineElement, i as EASE_OUT } from '../chunks/base-BPG5zvex.js';
-export { a as configureComponents } from '../chunks/base-BPG5zvex.js';
+import { f as clamp, m as motionScale, h as caf, p as prefersReducedMotion, n as now, r as raf, k as defineElement, l as EASE_OUT } from '../chunks/base-BtJDNCB6.js';
+export { d as configureComponents } from '../chunks/base-BtJDNCB6.js';
 
 const NUM = /-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/gi;
 /** `true` when two path strings share the same commands (so their numbers can be interpolated). */

package/dist/components/text.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
-var base = require('../chunks/base-CXx7jZ-o.cjs');
+var base = require('../chunks/base-DE2yzxE7.cjs');
+var core = require('../chunks/core-BC9S2osy.cjs');
+require('./tokens.cjs');
 
 var css$5 = "usa-typewriter{white-space:pre-wrap}usa-typewriter .usa-tw-caret{display:inline-block;width:var(--usa-caret-width,0.08em);height:1.05em;margin-left:0.06em;vertical-align:-0.12em;background:var(--usa-caret-color,currentColor);animation:usa-caret 1.06s steps(1) infinite}usa-typewriter[data-typing] .usa-tw-caret{animation:none}usa-typewriter[data-no-cursor] .usa-tw-caret{display:none}@keyframes usa-caret{50%{opacity:0}}@media (prefers-reduced-motion:reduce){usa-typewriter .usa-tw-caret,usa-shimmer-text{animation:none}}";
 
@@ -121,12 +123,255 @@ function defineTypewriter(tag = 'usa-typewriter') {
 
 var css$4 = "usa-split-text .usa-split-word{display:inline-block;white-space:nowrap}usa-split-text .usa-split-unit{display:inline-block;white-space:pre}usa-split-text[data-state=\"hidden\"] .usa-split-unit{opacity:0}usa-split-text[data-state=\"play\"] .usa-split-unit{animation:usa-split-rise var(--usa-split-duration,620ms) cubic-bezier(0.22,1,0.36,1) both;animation-delay:calc(var(--usa-split-delay,0ms) + var(--i,0) * var(--usa-split-stagger,28ms))}usa-split-text[effect=\"fade\"][data-state=\"play\"] .usa-split-unit{animation-name:usa-split-fade}usa-split-text[effect=\"blur\"][data-state=\"play\"] .usa-split-unit{animation-name:usa-split-blur}usa-split-text[effect=\"flip\"][data-state=\"play\"] .usa-split-unit{animation-name:usa-split-flip;transform-origin:50% 100%}usa-split-text[effect=\"pop\"][data-state=\"play\"] .usa-split-unit{animation-name:usa-split-pop;animation-timing-function:cubic-bezier(0.34,1.56,0.64,1)}@keyframes usa-split-rise{from{opacity:0;transform:translate3d(0,0.6em,0)}to{opacity:1;transform:none}}@keyframes usa-split-fade{from{opacity:0}to{opacity:1}}@keyframes usa-split-blur{from{opacity:0;filter:blur(8px)}to{opacity:1;filter:none}}@keyframes usa-split-flip{from{opacity:0;transform:perspective(500px) rotateX(-80deg)}to{opacity:1;transform:none}}@keyframes usa-split-pop{from{opacity:0;transform:scale(0.3)}to{opacity:1;transform:none}}@media (prefers-reduced-motion:reduce){usa-split-text .usa-split-unit{animation:none !important;opacity:1 !important}}";
 
+const CJK = /[\u2E80-\u2FFF\u3000-\u303F\u3040-\u30FF\u3100-\u312F\u3130-\u318F\u31A0-\u31FF\u3400-\u4DBF\u4E00-\u9FFF\uAC00-\uD7AF\uF900-\uFAFF\uFF00-\uFFEF]/;
+/** Scripts whose letters join (splitting them would break shaping). */
+const JOINING_SCRIPT = /[\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF\uFB50-\uFDFF\uFE70-\uFEFF]/;
+const RTL = /[\u0590-\u08FF\uFB1D-\uFDFF\uFE70-\uFEFF]/;
+const SR = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0';
+function segmenter(locale, granularity) {
+    const S = globalThis.Intl?.Segmenter;
+    if (typeof S !== 'function')
+        return null;
+    try {
+        return new S(locale || undefined, { granularity });
+    }
+    catch {
+        return null;
+    }
+}
+/** Grapheme clusters of `s` (emoji / combining marks stay whole). */
+function graphemes(s, locale) {
+    const seg = segmenter(locale, 'grapheme');
+    if (seg)
+        return Array.from(seg.segment(s), (x) => x.segment);
+    return Array.from(s);
+}
+/**
+ * Word-ish tokens of `s`, whitespace kept as separate tokens. CJK text is
+ * segmented into words with `Intl.Segmenter`, or per character without it.
+ */
+function words(s, locale) {
+    const seg = segmenter(locale, 'word');
+    const out = [];
+    if (seg) {
+        for (const x of seg.segment(s)) {
+            const last = out[out.length - 1];
+            // glue punctuation onto the previous word so it never starts a line alone
+            if (!x.isWordLike && !/^\s+$/.test(x.segment) && last && !/^\s+$/.test(last))
+                out[out.length - 1] = last + x.segment;
+            else
+                out.push(x.segment);
+        }
+        return out;
+    }
+    for (const part of s.split(/(\s+)/)) {
+        if (!part)
+            continue;
+        if (/^\s+$/.test(part) || !CJK.test(part))
+            out.push(part);
+        else {
+            let buf = '';
+            for (const ch of Array.from(part)) {
+                if (CJK.test(ch)) {
+                    if (buf)
+                        out.push(buf), (buf = '');
+                    out.push(ch);
+                }
+                else if (/[\p{P}]/u.test(ch) && out.length)
+                    out[out.length - 1] += ch;
+                else
+                    buf += ch;
+            }
+            if (buf)
+                out.push(buf);
+        }
+    }
+    return out;
+}
+function dirOf(el, text) {
+    const attr = el.closest?.('[dir]')?.getAttribute('dir');
+    if (attr === 'rtl' || attr === 'ltr')
+        return attr;
+    try {
+        const d = getComputedStyle(el).direction;
+        if (d === 'rtl')
+            return 'rtl';
+    }
+    catch {
+        /* no layout */
+    }
+    return RTL.test(text) && !/[A-Za-z]/.test(text.replace(RTL, '')) ? 'rtl' : 'ltr';
+}
+function splitText(el, options = {}) {
+    const by = new Set((Array.isArray(options.by) ? options.by : String(options.by ?? 'char').split(/[\s,]+/)).filter(Boolean));
+    const cls = options.className || 'usa-split';
+    const locale = options.locale || el.closest?.('[lang]')?.getAttribute('lang') || undefined;
+    const original = Array.from(el.childNodes).map((n) => n.cloneNode(true));
+    const text = el.textContent || '';
+    const direction = dirOf(el, text);
+    const chars = [];
+    const wordEls = [];
+    let lines = [];
+    const doc = el.ownerDocument;
+    const span = (c, t) => {
+        const s = doc.createElement('span');
+        s.className = c;
+        if (t !== undefined)
+            s.textContent = t;
+        return s;
+    };
+    const splitNode = (node) => {
+        if (node.nodeType === 3) {
+            const frag = doc.createDocumentFragment();
+            for (const w of words(node.nodeValue || '', locale)) {
+                if (/^\s+$/.test(w)) {
+                    frag.append(doc.createTextNode(w));
+                    continue;
+                }
+                const wordEl = span(`${cls}-word`);
+                wordEl.style.display = 'inline-block';
+                wordEl.style.whiteSpace = 'nowrap';
+                wordEl.dataset.index = String(wordEls.length);
+                wordEls.push(wordEl);
+                // Arabic script joins its letters: keep the word whole (shaping), even in char mode.
+                if (by.has('char') && !JOINING_SCRIPT.test(w)) {
+                    for (const g of graphemes(w, locale)) {
+                        const c = span(`${cls}-char`, g);
+                        c.style.display = 'inline-block';
+                        c.dataset.index = String(chars.length);
+                        chars.push(c);
+                        wordEl.append(c);
+                    }
+                }
+                else {
+                    wordEl.textContent = w;
+                    if (by.has('char')) {
+                        wordEl.dataset.whole = '';
+                        chars.push(wordEl);
+                    }
+                }
+                frag.append(wordEl);
+            }
+            node.parentNode.replaceChild(frag, node);
+        }
+        else if (node.nodeType === 1 && !/^(BR|SCRIPT|STYLE|SVG|IMG)$/i.test(node.tagName)) {
+            Array.from(node.childNodes).forEach(splitNode);
+        }
+    };
+    const wrap = doc.createElement('span');
+    wrap.setAttribute('aria-hidden', 'true');
+    wrap.className = `${cls}-body`;
+    original.forEach((n) => wrap.append(n.cloneNode(true)));
+    Array.from(wrap.childNodes).forEach(splitNode);
+    const sr = span(`${cls}-sr`, text.replace(/\s+/g, ' ').trim());
+    sr.setAttribute('style', SR);
+    el.replaceChildren(sr, wrap);
+    el.setAttribute('data-split', [...by].join(' '));
+    if (direction === 'rtl')
+        el.setAttribute('data-split-dir', 'rtl');
+    const relayout = () => {
+        // unwrap old lines
+        for (const l of lines)
+            l.replaceWith(...Array.from(l.childNodes));
+        lines = [];
+        if (!by.has('line') || !wordEls.length)
+            return lines;
+        const groups = [];
+        let lastTop = null;
+        for (const w of wordEls) {
+            const top = Math.round(w.offsetTop);
+            if (lastTop === null || Math.abs(top - lastTop) > 2)
+                groups.push([]);
+            groups[groups.length - 1].push(w);
+            lastTop = top;
+        }
+        groups.forEach((g, i) => {
+            // only group words that share a parent (inline markup keeps its words)
+            const parent = g[0].parentNode;
+            const same = g.filter((w) => w.parentNode === parent);
+            const line = span(`${cls}-line`);
+            line.style.display = 'inline-block';
+            line.dataset.index = String(i);
+            parent.insertBefore(line, same[0]);
+            let n = same[0];
+            const end = same[same.length - 1];
+            while (n) {
+                const next = n.nextSibling;
+                line.append(n);
+                if (n === end)
+                    break;
+                n = next;
+            }
+            // keep the space between lines outside the line box
+            lines.push(line);
+        });
+        return lines;
+    };
+    relayout();
+    return {
+        chars,
+        words: wordEls,
+        get lines() {
+            return lines;
+        },
+        direction,
+        relayout,
+        revert() {
+            el.replaceChildren(...original.map((n) => n.cloneNode(true)));
+            el.removeAttribute('data-split');
+            el.removeAttribute('data-split-dir');
+        },
+    };
+}
+/** Order indices `0…n-1` by choreography: from the start, end, center outwards, edges inwards, or random (seeded). */
+function splitOrder(n, from = 'start', seed = 1) {
+    const idx = Array.from({ length: n }, (_, i) => i);
+    const mid = (n - 1) / 2;
+    if (from === 'end')
+        return idx.map((i) => n - 1 - i);
+    if (from === 'center')
+        return idx.map((i) => Math.round(Math.abs(i - mid) * 2) / 2);
+    if (from === 'edges')
+        return idx.map((i) => Math.round((mid - Math.abs(i - mid)) * 2) / 2);
+    if (from === 'random') {
+        let s = seed;
+        const r = () => ((s = (s * 16807) % 2147483647) / 2147483647);
+        const shuffled = idx.slice().sort(() => r() - 0.5);
+        const rank = [];
+        shuffled.forEach((v, i) => (rank[v] = i));
+        return rank;
+    }
+    return idx;
+}
+/**
+ * Split `el` and build a `timeline()` with one step per unit — play it,
+ * `scrub()` it with scroll, `reverse()` or `seek()` it.
+ *
+ * ```ts
+ * const { timeline: tl } = splitTimeline(h1, { by: 'char', preset: 'blur', from: 'center' });
+ * tl.play();
+ * ```
+ */
+function splitTimeline(el, options = {}) {
+    const split = splitText(el, options);
+    const by = Array.isArray(options.by) ? options.by : String(options.by ?? 'char').split(/[\s,]+/);
+    const unit = options.unit || (by.includes('char') ? 'char' : by.includes('word') ? 'word' : 'line');
+    const units = unit === 'char' ? split.chars : unit === 'word' ? split.words : split.lines;
+    const stagger = options.stagger ?? (unit === 'char' ? 30 : unit === 'word' ? 80 : 140);
+    const order = splitOrder(units.length, options.from);
+    const tl = core.timeline({ defaults: { duration: options.duration ?? 500, easing: options.easing } });
+    units.forEach((u, i) => tl.to(u, options.preset || 'fade-up', { at: order[i] * stagger }));
+    tl.seek(0);
+    return { split, timeline: tl };
+}
+
 function defineSplitText(tag = 'usa-split-text') {
     return base.defineElement(tag, (Base) => class UsaSplitText extends Base {
         constructor() {
             super(...arguments);
             this._source = null;
             this._timer = 0;
+            this._steps = 0;
         }
         static get observedAttributes() {
             return ['by', 'text'];
@@ -138,28 +383,50 @@ function defineSplitText(tag = 'usa-split-text') {
             if (this._source === null)
                 this._source = this.getAttribute('text') ?? (this.textContent || '').replace(/\s+/g, ' ').trim();
             const text = this.getAttribute('text') ?? this._source;
-            const byWords = this.str('by', 'chars') === 'words';
+            const mode = this.str('by', 'chars');
+            const byWords = mode !== 'chars';
+            const lang = this.closest('[lang]')?.getAttribute('lang') || undefined;
             const frag = document.createDocumentFragment();
             frag.append(base.srText(text));
-            let i = 0;
-            text.split(' ').forEach((word, w) => {
-                if (w > 0)
+            const units = [];
+            for (const word of words(text, lang)) {
+                if (/^\s+$/.test(word)) {
                     frag.append(' ');
+                    continue;
+                }
                 const wordEl = document.createElement('span');
                 wordEl.className = 'usa-split-word';
                 wordEl.setAttribute('aria-hidden', 'true');
-                const parts = byWords ? [word] : Array.from(word);
+                const parts = byWords || JOINING_SCRIPT.test(word) ? [word] : graphemes(word, lang);
                 for (const part of parts) {
                     const u = document.createElement('span');
                     u.className = 'usa-split-unit';
                     u.textContent = part;
-                    u.style.setProperty('--i', String(i++));
+                    units.push(u);
                     wordEl.append(u);
                 }
                 frag.append(wordEl);
-            });
+            }
             this.replaceChildren(frag);
-            this.style.setProperty('--usa-split-stagger', `${this.num('stagger', byWords ? 70 : 28)}ms`);
+            // cascade order: per unit, or per line for by="lines"
+            let rank = units.map((_, k) => k);
+            if (mode === 'lines') {
+                let line = -1;
+                let top = null;
+                rank = units.map((u) => {
+                    const t = Math.round(u.parentElement.offsetTop);
+                    if (top === null || Math.abs(t - top) > 2)
+                        line++;
+                    top = t;
+                    return line;
+                });
+            }
+            const groups = Math.max(0, ...rank) + 1;
+            const order = splitOrder(groups, this.str('from', 'start'));
+            units.forEach((u, k) => u.style.setProperty('--i', String(order[rank[k]] ?? 0)));
+            const i = Math.max(0, ...units.map((_, k) => order[rank[k]] ?? 0)) + 1;
+            this._steps = i;
+            this.style.setProperty('--usa-split-stagger', `${this.num('stagger', mode === 'lines' ? 140 : byWords ? 70 : 28)}ms`);
             this.style.setProperty('--usa-split-duration', `${this.num('duration', 620)}ms`);
             this.style.setProperty('--usa-split-delay', `${this.num('delay', 0)}ms`);
             this.style.setProperty('--usa-split-count', String(i));
@@ -193,8 +460,8 @@ function defineSplitText(tag = 'usa-split-text') {
             this.setAttribute('data-state', 'hidden');
             void this.offsetWidth;
             this.setAttribute('data-state', 'play');
-            const n = this.units.length;
-            const total = this.num('delay', 0) + this.num('duration', 620) + Math.max(0, n - 1) * this.num('stagger', this.str('by') === 'words' ? 70 : 28);
+            const by = this.str('by', 'chars');
+            const total = this.num('delay', 0) + this.num('duration', 620) + Math.max(0, this._steps - 1) * this.num('stagger', by === 'lines' ? 140 : by === 'words' ? 70 : 28);
             this._timer = setTimeout(() => {
                 this.setAttribute('data-state', 'shown');
                 this.emit('complete');
@@ -680,6 +947,7 @@ function defineTextComponents() {
 
 exports.configureComponents = base.configureComponents;
 exports.prefersReducedMotion = base.prefersReducedMotion;
+exports.JOINING_SCRIPT = JOINING_SCRIPT;
 exports.defineCounter = defineCounter;
 exports.defineGlitch = defineGlitch;
 exports.defineGradientText = defineGradientText;
@@ -693,5 +961,10 @@ exports.defineTextRotate = defineTextRotate;
 exports.defineTypewriter = defineTypewriter;
 exports.defineWaveText = defineWaveText;
 exports.easeOutExpo = easeOutExpo;
+exports.graphemes = graphemes;
 exports.scrambleFrame = scrambleFrame;
+exports.splitOrder = splitOrder;
+exports.splitText = splitText;
+exports.splitTimeline = splitTimeline;
+exports.splitWords = words;
 //# sourceMappingURL=text.cjs.map