use-scroll-animate 3.9.0 → 4.0.1

package/dist/solid.d.ts

@@ -219,7 +219,12 @@ declare module 'solid-js' {
         }
     }
 }
-/** Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />` */
+/**
+ * Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />`.
+ * 4.0.1: the accessor is tracked — when signals it reads change, callbacks
+ * update right away and the other options are re-applied if the element has
+ * not animated yet (no manual `refresh()` needed).
+ */
 declare function scrollAnimate(el: Element, accessor?: () => SolidScrollAnimateOptions | true | undefined): void;
 /** Directive: `<ul use:scrollStagger={{ stagger: 60, observeChildren: true }} />` */
 declare function scrollStagger(el: Element, accessor?: () => SolidScrollStaggerOptions | true | undefined): void;

package/dist/solid.js

@@ -1,4 +1,4 @@
-import { onMount, onCleanup } from 'solid-js';
+import { createRenderEffect, onMount, onCleanup } from 'solid-js';
 import { c as createScrollAnimate } from './chunks/core-mV_TPgG_.js';
 import { s as staggerChildren } from './chunks/stagger-BFAhKknX.js';
 
@@ -22,16 +22,46 @@ function read(accessor) {
     const v = accessor?.();
     return (v && v !== true ? v : {});
 }
-function observe(el, options) {
-    const { instance, ...opts } = options;
-    const sa = getInstance(instance);
-    // Wait until the element is in the document (directives/refs run before insertion).
-    onMount(() => sa.observe(el, opts));
-    onCleanup(() => sa.unobserve(el));
+const CALLBACKS = ['onStart', 'onComplete', 'onEnter', 'onLeave', 'onProgress'];
+/** Callbacks always call the latest options' version. */
+function liveCallbacks(opts, latest) {
+    const out = { ...opts };
+    CALLBACKS.forEach((name) => {
+        if (typeof opts[name] === 'function')
+            out[name] = (...args) => latest()[name]?.(...args);
+    });
+    return out;
 }
-/** Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />` */
+/**
+ * Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />`.
+ * 4.0.1: the accessor is tracked — when signals it reads change, callbacks
+ * update right away and the other options are re-applied if the element has
+ * not animated yet (no manual `refresh()` needed).
+ */
 function scrollAnimate(el, accessor) {
-    observe(el, read(accessor));
+    let latest = {};
+    let mounted = false;
+    let sa = null;
+    const apply = () => {
+        const { instance, ...opts } = latest;
+        const record = sa?.getObservedElements().find((r) => r.element === el);
+        if (sa && record?.animated)
+            return; // finished: callbacks stay live
+        sa?.unobserve(el);
+        sa = getInstance(instance);
+        sa.observe(el, liveCallbacks(opts, () => latest));
+    };
+    createRenderEffect(() => {
+        latest = read(accessor);
+        if (mounted)
+            apply();
+    });
+    // Wait until the element is in the document (directives/refs run before insertion).
+    onMount(() => {
+        mounted = true;
+        apply();
+    });
+    onCleanup(() => sa?.unobserve(el));
 }
 /** Directive: `<ul use:scrollStagger={{ stagger: 60, observeChildren: true }} />` */
 function scrollStagger(el, accessor) {

package/dist/solid.js.map

@@ -1 +1 @@
-{"version":3,"file":"solid.js","sources":["../src/solid.ts"],"sourcesContent":["/**\n * use-scroll-animate - Solid integration\n *\n * ```tsx\n * import { scrollAnimate, scrollStagger, useScrollAnimate } from 'use-scroll-animate/solid';\n * false && scrollAnimate; // keep the directive import (TypeScript)\n *\n * <div use:scrollAnimate={{ animation: 'zoom-in' }}>…</div>\n * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>\n * <div ref={useScrollAnimate({ animation: 'fade-in-up' })}>…</div>\n * ```\n *\n * `solid-js` is an optional peer dependency (only needed for this entry).\n */\n\nimport { onCleanup, onMount } from 'solid-js';\nimport type { AnimateOptions, ScrollAnimateInstance } from './types';\nimport { createScrollAnimate } from './core';\nimport { staggerChildren, type StaggerOptions } from './stagger';\n\nexport interface SolidScrollAnimateOptions extends AnimateOptions {\n  instance?: ScrollAnimateInstance;\n}\nexport interface SolidScrollStaggerOptions extends StaggerOptions {\n  instance?: ScrollAnimateInstance;\n}\n\ndeclare module 'solid-js' {\n  // eslint-disable-next-line @typescript-eslint/no-namespace\n  namespace JSX {\n    interface Directives {\n      scrollAnimate: SolidScrollAnimateOptions | true;\n      scrollStagger: SolidScrollStaggerOptions | true;\n    }\n  }\n}\n\nlet shared: ScrollAnimateInstance | null = null;\nconst getInstance = (own?: ScrollAnimateInstance) => own || shared || (shared = createScrollAnimate());\n\nfunction read<T>(accessor?: () => T | true | undefined): T {\n  const v = accessor?.();\n  return (v && v !== true ? v : {}) as T;\n}\n\nfunction observe(el: Element, options: SolidScrollAnimateOptions): void {\n  const { instance, ...opts } = options;\n  const sa = getInstance(instance);\n  // Wait until the element is in the document (directives/refs run before insertion).\n  onMount(() => sa.observe(el, opts));\n  onCleanup(() => sa.unobserve(el));\n}\n\n/** Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />` */\nexport function scrollAnimate(el: Element, accessor?: () => SolidScrollAnimateOptions | true | undefined): void {\n  observe(el, read(accessor));\n}\n\n/** Directive: `<ul use:scrollStagger={{ stagger: 60, observeChildren: true }} />` */\nexport function scrollStagger(el: Element, accessor?: () => SolidScrollStaggerOptions | true | undefined): void {\n  const { instance, ...opts } = read<SolidScrollStaggerOptions>(accessor);\n  let stop: (() => void) | undefined;\n  onMount(() => {\n    stop = staggerChildren(el, opts, getInstance(instance));\n  });\n  onCleanup(() => stop?.());\n}\n\n/** Primitive returning a `ref` callback: `<div ref={useScrollAnimate({ animation: 'fade-in-up' })} />` */\nexport function useScrollAnimate(options: SolidScrollAnimateOptions = {}): (el: Element) => void {\n  let el: Element | undefined;\n  const { instance, ...opts } = options;\n  const sa = getInstance(instance);\n  onMount(() => el && sa.observe(el, opts));\n  onCleanup(() => el && sa.unobserve(el));\n  return (node: Element) => {\n    el = node;\n  };\n}\n"],"names":[],"mappings":";;;;AAAA;;;;;;;;;;;;;AAaG;AAwBH,IAAI,MAAM,GAAiC,IAAI;AAC/C,MAAM,WAAW,GAAG,CAAC,GAA2B,KAAK,GAAG,IAAI,MAAM,KAAK,MAAM,GAAG,mBAAmB,EAAE,CAAC;AAEtG,SAAS,IAAI,CAAI,QAAqC,EAAA;AACpD,IAAA,MAAM,CAAC,GAAG,QAAQ,IAAI;AACtB,IAAA,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,GAAG,EAAE;AAClC;AAEA,SAAS,OAAO,CAAC,EAAW,EAAE,OAAkC,EAAA;IAC9D,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO;AACrC,IAAA,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC;;AAEhC,IAAA,OAAO,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACnC,SAAS,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AACnC;AAEA;AACM,SAAU,aAAa,CAAC,EAAW,EAAE,QAA6D,EAAA;IACtG,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC7B;AAEA;AACM,SAAU,aAAa,CAAC,EAAW,EAAE,QAA6D,EAAA;IACtG,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAA4B,QAAQ,CAAC;AACvE,IAAA,IAAI,IAA8B;IAClC,OAAO,CAAC,MAAK;AACX,QAAA,IAAI,GAAG,eAAe,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;AACzD,IAAA,CAAC,CAAC;IACF,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC;AAC3B;AAEA;AACM,SAAU,gBAAgB,CAAC,OAAA,GAAqC,EAAE,EAAA;AACtE,IAAA,IAAI,EAAuB;IAC3B,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO;AACrC,IAAA,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC;AAChC,IAAA,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;AACzC,IAAA,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,IAAa,KAAI;QACvB,EAAE,GAAG,IAAI;AACX,IAAA,CAAC;AACH;;;;"}
+{"version":3,"file":"solid.js","sources":["../src/solid.ts"],"sourcesContent":["/**\n * use-scroll-animate - Solid integration\n *\n * ```tsx\n * import { scrollAnimate, scrollStagger, useScrollAnimate } from 'use-scroll-animate/solid';\n * false && scrollAnimate; // keep the directive import (TypeScript)\n *\n * <div use:scrollAnimate={{ animation: 'zoom-in' }}>…</div>\n * <ul use:scrollStagger={{ stagger: 60 }}>…</ul>\n * <div ref={useScrollAnimate({ animation: 'fade-in-up' })}>…</div>\n * ```\n *\n * `solid-js` is an optional peer dependency (only needed for this entry).\n */\n\nimport { createRenderEffect, onCleanup, onMount } from 'solid-js';\nimport type { AnimateOptions, ScrollAnimateInstance } from './types';\nimport { createScrollAnimate } from './core';\nimport { staggerChildren, type StaggerOptions } from './stagger';\n\nexport interface SolidScrollAnimateOptions extends AnimateOptions {\n  instance?: ScrollAnimateInstance;\n}\nexport interface SolidScrollStaggerOptions extends StaggerOptions {\n  instance?: ScrollAnimateInstance;\n}\n\ndeclare module 'solid-js' {\n  // eslint-disable-next-line @typescript-eslint/no-namespace\n  namespace JSX {\n    interface Directives {\n      scrollAnimate: SolidScrollAnimateOptions | true;\n      scrollStagger: SolidScrollStaggerOptions | true;\n    }\n  }\n}\n\nlet shared: ScrollAnimateInstance | null = null;\nconst getInstance = (own?: ScrollAnimateInstance) => own || shared || (shared = createScrollAnimate());\n\nfunction read<T>(accessor?: () => T | true | undefined): T {\n  const v = accessor?.();\n  return (v && v !== true ? v : {}) as T;\n}\n\nconst CALLBACKS = ['onStart', 'onComplete', 'onEnter', 'onLeave', 'onProgress'] as const;\n\n/** Callbacks always call the latest options' version. */\nfunction liveCallbacks(opts: AnimateOptions, latest: () => AnimateOptions): AnimateOptions {\n  const out: AnimateOptions = { ...opts };\n  CALLBACKS.forEach((name) => {\n    if (typeof opts[name] === 'function') (out as any)[name] = (...args: unknown[]) => (latest()[name] as any)?.(...args);\n  });\n  return out;\n}\n\n/**\n * Directive: `<div use:scrollAnimate={{ animation: 'fade-in' }} />`.\n * 4.0.1: the accessor is tracked — when signals it reads change, callbacks\n * update right away and the other options are re-applied if the element has\n * not animated yet (no manual `refresh()` needed).\n */\nexport function scrollAnimate(el: Element, accessor?: () => SolidScrollAnimateOptions | true | undefined): void {\n  let latest: SolidScrollAnimateOptions = {};\n  let mounted = false;\n  let sa: ScrollAnimateInstance | null = null;\n  const apply = () => {\n    const { instance, ...opts } = latest;\n    const record = sa?.getObservedElements().find((r) => r.element === el);\n    if (sa && record?.animated) return; // finished: callbacks stay live\n    sa?.unobserve(el);\n    sa = getInstance(instance);\n    sa.observe(el, liveCallbacks(opts, () => latest));\n  };\n  createRenderEffect(() => {\n    latest = read<SolidScrollAnimateOptions>(accessor);\n    if (mounted) apply();\n  });\n  // Wait until the element is in the document (directives/refs run before insertion).\n  onMount(() => {\n    mounted = true;\n    apply();\n  });\n  onCleanup(() => sa?.unobserve(el));\n}\n\n/** Directive: `<ul use:scrollStagger={{ stagger: 60, observeChildren: true }} />` */\nexport function scrollStagger(el: Element, accessor?: () => SolidScrollStaggerOptions | true | undefined): void {\n  const { instance, ...opts } = read<SolidScrollStaggerOptions>(accessor);\n  let stop: (() => void) | undefined;\n  onMount(() => {\n    stop = staggerChildren(el, opts, getInstance(instance));\n  });\n  onCleanup(() => stop?.());\n}\n\n/** Primitive returning a `ref` callback: `<div ref={useScrollAnimate({ animation: 'fade-in-up' })} />` */\nexport function useScrollAnimate(options: SolidScrollAnimateOptions = {}): (el: Element) => void {\n  let el: Element | undefined;\n  const { instance, ...opts } = options;\n  const sa = getInstance(instance);\n  onMount(() => el && sa.observe(el, opts));\n  onCleanup(() => el && sa.unobserve(el));\n  return (node: Element) => {\n    el = node;\n  };\n}\n"],"names":[],"mappings":"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"}

package/docs/API.md

@@ -9,7 +9,7 @@
 - [Data attributes](#data-attributes)
 - [Global config (`ScrollAnimateConfig`)](#global-config-scrollanimateconfig)
 - [Presets & easings](#presets--easings)
-- [Helpers: `staggerChildren`, `sequence`, `parallax`, `getScrollProgress`, `supportsScrollTimeline`](#helpers)
+- [Helpers: `staggerChildren`, `timeline`, `parallax`, `getScrollProgress`, `supportsScrollTimeline`](#helpers)
 - [Framework integrations](#framework-integrations)
 - [Behaviour notes](#behaviour-notes)
 
@@ -17,7 +17,7 @@
 
 | Import | Contents |
 |---|---|
-| `use-scroll-animate` | Default instance, `createScrollAnimate`, `staggerChildren`, `sequence`, `parallax`, `getScrollProgress`, `supportsScrollTimeline`, `PRESETS`, `resolvePreset`, `resolveEasing`, `EASING_MAP`, all types |
+| `use-scroll-animate` | Default instance, `createScrollAnimate`, `staggerChildren`, `timeline`, `parallax`, `getScrollProgress`, `supportsScrollTimeline`, `PRESETS`, `resolvePreset`, `resolveEasing`, `EASING_MAP`, all types |
 | `use-scroll-animate/react` | `createReactHooks(React)` |
 | `use-scroll-animate/vue` | `createVueComposables({ ref, onMounted, onUnmounted })` |
 | `use-scroll-animate/svelte` | `scrollAnimate`, `scrollStagger` actions |
@@ -25,7 +25,7 @@
 | `use-scroll-animate/element` | `defineScrollAnimate(tagName?, instance?)` for `<scroll-animate>` |
 | `dist/index.umd.js` | Global `ScrollAnimate` (`ScrollAnimate.default` is the instance, other exports as properties) |
 | `dist/element.umd.js` | Registers `<scroll-animate>` on load; global `ScrollAnimateElement` |
-| `use-scroll-animate/components` (+ `/components/reveal`, `/text`, `/interaction`, `/feedback`, `/background`, `/transitions`) | 30 animated `<usa-*>` Web Components, `defineComponents()`, `configureComponents()`, `toast()`, `viewTransition()`, `flip()`, `connectedAnimation()` — see **[components.md](./components.md)** |
+| `use-scroll-animate/components` (+ `/components/reveal`, `/text`, `/interaction`, `/feedback`, `/background`, `/transitions`) | 30 animated `<usa-*>` Web Components, `defineComponents()`, `configureComponents()`, `toast()`, `viewTransition()`, `flip()` — see **[components.md](./components.md)** |
 | `dist/components.umd.js`, `use-scroll-animate/components.css` | Registers every `<usa-*>` on load (global `UsaComponents`); the component styles as a file |
 
 Every entry is ESM-first (`import` → `.js` + `.d.ts`) with a CommonJS build (`require` → `.cjs` + `.d.cts`), SSR-safe (no DOM access at import), and has zero runtime dependencies.
@@ -111,8 +111,8 @@ Boolean attributes are true when present unless their value is `"false"`.
 ### `staggerChildren(container, options?, instance?)` → `() => void`
 Reveal the children of `container` one after another when it enters. `StaggerOptions` = `AnimateOptions` + `stagger` (default `80` ms) + `observeChildren` (MutationObserver for children added later). Stopping before the reveal makes the children visible.
 
-### `sequence(steps, options?)` → `SequenceController`
-Timeline across targets. `SequenceStep` = `AnimateOptions` + `target` + `gap` (ms after the previous step; negative overlaps) or `at` (absolute ms). `SequenceOptions` = `AnimateOptions` + `trigger` (play once when it enters) + `instance`. Controller: `play(): Promise<void>`, `cancel()`, `duration()`.
+### `timeline(options?)` → `Timeline` (4.0; replaces `sequence()`)
+One playhead for many WAAPI animations. `options` = `{ defaults: { duration = 600, easing, stagger }, speed, onUpdate(p), onComplete() }`. Build with `.to(target, keyframes | preset, { at, duration, easing, stagger })`, `.label(name, at?)`, `.call(fn, at?)`; positions `'>'` (default), `'<'`, `'-=ms'`, `'+=ms'`, `'<+=ms'`, `'label+=ms'` or ms (`resolvePosition()`). Control: `play(from?)` / `reverse()` (Promises), `pause()`, `seek(ms | label)`, `progress(p?)`, `scrub(el, { offset, smooth })` → stop, `cancel()`; read `duration`, `time`, `labels`. Presets: `TIMELINE_PRESETS`. Reduced motion jumps to the end. Also in `use-scroll-animate/components/timeline` with `<usa-timeline>`.
 
 ### `parallax(target, options?)` → `() => void`
 `{ speed = 0.2, axis = 'y', progressVar = '--sa-parallax', root = null, respectReducedMotion = true }`. Offset `(progress − 0.5) × speed × 100vh` (or `vw`) on the `translate` property; progress (0–1) in the CSS variable. The stop function removes listeners and inline styles.
@@ -136,5 +136,5 @@ True scroll progress 0–1 of `el` through the viewport or `root`. `0` without a
 - **Reduced motion**: with `prefers-reduced-motion: reduce` (or `disabled: true`) nothing is hidden or moved; callbacks still fire; `progressVar` is still written (it is data); `parallax()` writes only its variable.
 - **SSR**: every entry can be imported and called on the server; calls are no-ops without a DOM.
 - **No IntersectionObserver**: content is shown immediately.
-- **Native engine**: scroll-linked, so `duration`/`delay`/`threshold`/`offset`/`stagger` don't apply; `once` freezes the end state on completion; class-name mode, reduced motion, `animate()`, `sequence()` and `staggerChildren()` always use JS.
+- **Native engine**: scroll-linked, so `duration`/`delay`/`threshold`/`offset`/`stagger` don't apply; `once` freezes the end state on completion; class-name mode, reduced motion, `animate()`, `timeline()` and `staggerChildren()` always use JS.
 - **Native engine by default**: in browsers without `animation-timeline: view()` everything runs on the JS engine.

package/docs/ROADMAP.md

@@ -0,0 +1,14 @@
+# 路线图（4.0 之后）
+
+> 4.0.0 已完成 API 统一：`timeline()` 取代 `sequence()`，`sharedTransition()` 取代 `connectedAnimation()`，`<usa-auto-animate>` 取代 `<usa-flip-list>`。以下为 4.x → 5.0 的规划，每个版本一个 PR，按需调整。
+
+- **v4.1** — 滚动驱动时间线：`timeline().scrub()` 优先使用原生 `ScrollTimeline` / `ViewTimeline`（脱离主线程），JS 作为回退。
+- **v4.2** — 动效设计令牌：统一的时长 / 缓动 / 弹簧令牌（CSS 变量 + JSON），支持从 Figma Tokens / Style Dictionary 导入。
+- **v4.3** — 文本进阶：按字 / 词 / 行拆分的 `splitText()`，支持中日韩文字与 RTL，配合 `timeline()` 逐字编排。
+- **v4.4** — 无障碍增强：每个组件提供“静态替代”与 `aria-live` 规范，新增运动敏感度分级与自动化 a11y 回归测试。
+- **v4.5** — 性能与体积：按需加载 CSS、共享 rAF 调度器、动画数量自动降级，组件整体 gzip 目标 ≤ 70KB。
+- **v4.6** — 实验室 2.0：时间线可视化编辑（关键帧轨道）、保存 / 分享预设，并可导出为 `<usa-timeline>` 标记。
+- **v4.7** — 原生壳集成：WinUI 3、.NET MAUI、Flutter 的官方桥接示例包，支持系统“减少动态效果”与主题自动同步。
+- **v4.8** — 3D 与 WebGL 扩展：基于 `glQuad()` 的粒子 / 后处理小型预设库，统一 WebGL 回退与电量 / 帧率自适应。
+- **v4.9** — 5.0 预备：标记计划移除或重命名的 API 并输出一次性弃用警告，发布 `upgrading-5.md` 与自动迁移脚本（codemod）。
+- **v5.0** — 下一代主版本：仅支持现代浏览器（原生 View Transitions / Scroll Timeline 基线），移除 4.9 弃用的 API，统一的插件式效果注册机制。

package/docs/components.md

@@ -40,7 +40,7 @@ defineTypewriter();
 No build step (registers every `<usa-*>` and exposes the API as `window.UsaComponents`):
 
 ```html
-<script src="https://unpkg.com/use-scroll-animate@3/dist/components.umd.js"></script>
+<script src="https://unpkg.com/use-scroll-animate@4/dist/components.umd.js"></script>
 <usa-typewriter words="Hello, Windows.|Hello, web."></usa-typewriter>
 <script>UsaComponents.toast('Ready', { type: 'success' });</script>
 ```
@@ -113,11 +113,9 @@ All attributes are optional unless noted. Events are `CustomEvent`s that bubble,
 |---|---|---|---|
 | `<usa-dialog>` | Animated modal / drawer / sheet on the native `<dialog>` (focus trap, Esc, top layer); content is slotted, so frameworks keep owning it | `open`, `kind` (`modal`*, `drawer-start`, `drawer-end`, `drawer-bottom`, `sheet`), `label`, `no-backdrop-close`, `no-esc`; `[data-close]` children close it; `::part(panel/backdrop)`, `--usa-dialog-*` | `show()`, `close(value?)`, `open`, `returnValue`; `usa:open`, `usa:beforeclose` (cancelable), `usa:close` |
 | `<usa-accordion>` | Smooth height animation for native `<details>` | `multiple`, `duration` (300) | `toggleItem(details, open?)`, `items`; `usa:toggle` |
-| `<usa-flip-list>` | Children glide to new places on add / remove / reorder (FLIP) | `duration` (420), `easing`, `disabled` | `flip(mutate)` |
 | `<usa-view-switch>` | One view at a time with direction-aware transitions | `active` (name or index), `effect` (`slide`*, `fade`, `scale`, `drill`), `duration` | `show(view)`, `active`, `views`; `usa:change` |
 | `viewTransition(update, opts?)` | Runs a DOM update inside `document.startViewTransition()`, cross-fade fallback | `{ fallback, duration, types }` | `Promise<void>` |
 | `flip(targets, mutate, opts?)` | FLIP-animates any layout change | `{ duration, easing, animateEnter }` | `Promise<void>` |
-| `connectedAnimation(from, to, opts?)` | WinUI-style connected / shared-element animation | `{ duration, easing, hideSource }` | `Promise<void>` |
 
 ### 7. Spring & physics — `components/physics`
 
@@ -287,7 +285,7 @@ Fallbacks set `data-fallback` (`webgl` · `image` · `no-image`); cross-origin i
 | `<usa-masonry>` | Masonry grid with animated reflow | `columns` or `min` (220), `gap` (16); `layout()` |
 | `sharedTransition(update, root?)` | Shared-element transition via `data-shared="id"` | `duration` (450), `easing`; View Transitions API or FLIP |
 
-Also see `flip()` / `connectedAnimation()` / `<usa-flip-list>` in `components/transitions`.
+Also see `flip()` in `components/transitions`. (4.0 removed `<usa-flip-list>` and `connectedAnimation()` in favour of these.)
 
 ### v3.7 Visual playground
 
@@ -315,7 +313,7 @@ Hybrid / desktop hosts (MAUI, Flutter WebView, Electron, Tauri): [hybrid-apps.md
 
 `<usa-pack>` (e.g. `<usa-pack name="ecommerce">…</usa-pack>`) or `applyPack('ecommerce', root)`; helpers `flyToCart(from, to)`, `countUp(el)`.
 
-**Deprecated in 3.9, removed in 4.0:** `sequence()`, `connectedAnimation()`, `<usa-flip-list>` — see [upgrading-4.md](./upgrading-4.md).
+**Deprecated in 3.9, removed in 4.0.0:** `sequence()`, `connectedAnimation()`, `<usa-flip-list>` — see [upgrading-4.md](./upgrading-4.md).
 
 ## Frameworks
 

package/docs/migration-from-aos.md

@@ -27,7 +27,7 @@ No stylesheet is needed: animations run through the Web Animations API (or opt i
 | `data-aos-once="true"` | `data-sa-once` (default) |
 | `data-aos-mirror="true"` (animate out when scrolling past) | `data-sa-exit` |
 | `data-aos-anchor-placement="top-center"` | `data-sa-threshold="0.5"` or `data-sa-root-margin="0px 0px -50% 0px"` |
-| `data-aos-anchor=".other"` | `sequence([...], { trigger: '.other' })` |
+| `data-aos-anchor=".other"` | `timeline()` played when `.other` enters (or `<usa-timeline>` around it) |
 
 ## 3. Animation names
 

package/docs/migration-from-gsap-scrolltrigger.md

@@ -35,14 +35,14 @@ GSAP + ScrollTrigger is a full animation platform; `use-scroll-animate` covers t
 - tl.from('.title', { opacity: 0, y: 40 })
 -   .from('.subtitle', { opacity: 0 }, '-=0.2')
 -   .from('.cta', { scale: 0.8, opacity: 0 }, 1.2);
-+ sequence([
-+   { target: '.title', animation: 'fade-in-up' },
-+   { target: '.subtitle', animation: 'fade-in', gap: -200 },
-+   { target: '.cta', animation: 'zoom-in', at: 1200 },
-+ ], { trigger: '.hero' });
++ const tl = timeline()
++   .to('.title', 'fade-up')
++   .to('.subtitle', 'fade', { at: '-=200' })
++   .to('.cta', 'scale', { at: 1200 });
++ tl.scrub(document.querySelector('.hero')); // or tl.play() when it enters
 ```
 
-`play()` returns a Promise; `cancel()` stops it and leaves content visible.
+`play()` / `reverse()` return Promises; `seek()`, `progress()`, labels and `scrub()` work like GSAP's timeline controls.
 
 ## Scrub (progress-linked) animations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-scroll-animate",
-  "version": "3.9.0",
+  "version": "4.0.1",
   "description": "A lightweight, high-performance, dependency-free scroll animation library and animated UI components (Web Components) for the web and Windows web-view apps.",
   "type": "module",
   "main": "./dist/index.cjs",

package/dist/chunks/index-tags-BmQR17Sb.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-tags-BmQR17Sb.js","sources":["../../src/components/index-tags.ts"],"sourcesContent":["// The component categories and their default tags (no imports: safe for lazy loaders).\n/** The component categories and their default tags. */\nexport const COMPONENT_CATEGORIES = {\n  reveal: ['usa-reveal', 'usa-stagger', 'usa-scroll-progress', 'usa-scrolly'],\n  text: ['usa-typewriter', 'usa-split-text', 'usa-scramble', 'usa-counter', 'usa-shimmer-text', 'usa-text-rotate', 'usa-wave-text', 'usa-glitch', 'usa-gradient-text', 'usa-handwriting', 'usa-scroll-highlight'],\n  interaction: ['usa-ripple', 'usa-magnetic', 'usa-tilt', 'usa-spotlight', 'usa-press', 'usa-toggle'],\n  feedback: ['usa-spinner', 'usa-skeleton', 'usa-progress', 'usa-toaster', 'usa-check'],\n  background: ['usa-aurora', 'usa-particles', 'usa-grain', 'usa-marquee', 'usa-acrylic', 'usa-grid-glow', 'usa-blobs', 'usa-water-ripple', 'usa-dot-network'],\n  transitions: ['usa-dialog', 'usa-accordion', 'usa-flip-list', 'usa-view-switch'],\n  physics: ['usa-spring', 'usa-draggable', 'usa-overscroll'],\n  cards: ['usa-card', 'usa-card-stack', 'usa-sticky-stack', 'usa-carousel-3d'],\n  click: ['usa-click', 'usa-button', 'usa-icon-morph', 'usa-like', 'usa-hold', 'usa-double-tap', 'usa-checkbox'],\n  ui: ['usa-tabs', 'usa-drawer', 'usa-bottom-sheet', 'usa-pull-refresh', 'usa-fab', 'usa-navbar', 'usa-slider', 'usa-rating', 'usa-tooltip', 'usa-popover', 'usa-badge', 'usa-avatar-stack'],\n  page: ['usa-cursor', 'usa-fullpage', 'usa-loading-bar', 'usa-back-to-top', 'usa-ambient', 'usa-splash', 'usa-auto-skeleton', 'usa-motion-switch'],\n  timeline: ['usa-timeline'],\n  gesture: ['usa-swipeable', 'usa-pinch-zoom'],\n  svg: ['usa-draw', 'usa-morph', 'usa-mask-reveal', 'usa-anim-icon'],\n  webgl: ['usa-shader', 'usa-distort', 'usa-liquid'],\n  depth: ['usa-cube', 'usa-depth'],\n  layout: ['usa-auto-animate', 'usa-masonry'],\n  packs: ['usa-pack'],\n} as const;\n\nexport type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;\n"],"names":[],"mappings":"AAAA;AACA;AACO,MAAM,oBAAoB,GAAG;IAClC,MAAM,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,aAAa,CAAC;IAC3E,IAAI,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,CAAC;AAC/M,IAAA,WAAW,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,CAAC;IACnG,QAAQ,EAAE,CAAC,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,CAAC;AACrF,IAAA,UAAU,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;IAC3J,WAAW,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,CAAC;AAChF,IAAA,OAAO,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,gBAAgB,CAAC;IAC1D,KAAK,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;AAC5E,IAAA,KAAK,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,CAAC;IAC9G,EAAE,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,CAAC;AAC1L,IAAA,IAAI,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,CAAC;IACjJ,QAAQ,EAAE,CAAC,cAAc,CAAC;AAC1B,IAAA,OAAO,EAAE,CAAC,eAAe,EAAE,gBAAgB,CAAC;IAC5C,GAAG,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,eAAe,CAAC;AAClE,IAAA,KAAK,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,YAAY,CAAC;AAClD,IAAA,KAAK,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;AAChC,IAAA,MAAM,EAAE,CAAC,kBAAkB,EAAE,aAAa,CAAC;IAC3C,KAAK,EAAE,CAAC,UAAU,CAAC;;;;;"}

package/dist/chunks/index-tags-DYYsgbba.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-tags-DYYsgbba.cjs","sources":["../../src/components/index-tags.ts"],"sourcesContent":["// The component categories and their default tags (no imports: safe for lazy loaders).\n/** The component categories and their default tags. */\nexport const COMPONENT_CATEGORIES = {\n  reveal: ['usa-reveal', 'usa-stagger', 'usa-scroll-progress', 'usa-scrolly'],\n  text: ['usa-typewriter', 'usa-split-text', 'usa-scramble', 'usa-counter', 'usa-shimmer-text', 'usa-text-rotate', 'usa-wave-text', 'usa-glitch', 'usa-gradient-text', 'usa-handwriting', 'usa-scroll-highlight'],\n  interaction: ['usa-ripple', 'usa-magnetic', 'usa-tilt', 'usa-spotlight', 'usa-press', 'usa-toggle'],\n  feedback: ['usa-spinner', 'usa-skeleton', 'usa-progress', 'usa-toaster', 'usa-check'],\n  background: ['usa-aurora', 'usa-particles', 'usa-grain', 'usa-marquee', 'usa-acrylic', 'usa-grid-glow', 'usa-blobs', 'usa-water-ripple', 'usa-dot-network'],\n  transitions: ['usa-dialog', 'usa-accordion', 'usa-flip-list', 'usa-view-switch'],\n  physics: ['usa-spring', 'usa-draggable', 'usa-overscroll'],\n  cards: ['usa-card', 'usa-card-stack', 'usa-sticky-stack', 'usa-carousel-3d'],\n  click: ['usa-click', 'usa-button', 'usa-icon-morph', 'usa-like', 'usa-hold', 'usa-double-tap', 'usa-checkbox'],\n  ui: ['usa-tabs', 'usa-drawer', 'usa-bottom-sheet', 'usa-pull-refresh', 'usa-fab', 'usa-navbar', 'usa-slider', 'usa-rating', 'usa-tooltip', 'usa-popover', 'usa-badge', 'usa-avatar-stack'],\n  page: ['usa-cursor', 'usa-fullpage', 'usa-loading-bar', 'usa-back-to-top', 'usa-ambient', 'usa-splash', 'usa-auto-skeleton', 'usa-motion-switch'],\n  timeline: ['usa-timeline'],\n  gesture: ['usa-swipeable', 'usa-pinch-zoom'],\n  svg: ['usa-draw', 'usa-morph', 'usa-mask-reveal', 'usa-anim-icon'],\n  webgl: ['usa-shader', 'usa-distort', 'usa-liquid'],\n  depth: ['usa-cube', 'usa-depth'],\n  layout: ['usa-auto-animate', 'usa-masonry'],\n  packs: ['usa-pack'],\n} as const;\n\nexport type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;\n"],"names":[],"mappings":";;AAAA;AACA;AACO,MAAM,oBAAoB,GAAG;IAClC,MAAM,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,aAAa,CAAC;IAC3E,IAAI,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,CAAC;AAC/M,IAAA,WAAW,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,CAAC;IACnG,QAAQ,EAAE,CAAC,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,CAAC;AACrF,IAAA,UAAU,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;IAC3J,WAAW,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,CAAC;AAChF,IAAA,OAAO,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,gBAAgB,CAAC;IAC1D,KAAK,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;AAC5E,IAAA,KAAK,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,CAAC;IAC9G,EAAE,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,CAAC;AAC1L,IAAA,IAAI,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,CAAC;IACjJ,QAAQ,EAAE,CAAC,cAAc,CAAC;AAC1B,IAAA,OAAO,EAAE,CAAC,eAAe,EAAE,gBAAgB,CAAC;IAC5C,GAAG,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,eAAe,CAAC;AAClE,IAAA,KAAK,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,YAAY,CAAC;AAClD,IAAA,KAAK,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;AAChC,IAAA,MAAM,EAAE,CAAC,kBAAkB,EAAE,aAAa,CAAC;IAC3C,KAAK,EAAE,CAAC,UAAU,CAAC;;;;;"}