use-scroll-animate 3.0.0 → 3.1.0

package/dist/components/vue.d.cts

@@ -1288,6 +1288,92 @@ 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 (default: timeline default, 600). */
+    duration?: number;
+    /** CSS easing (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. */
+    offset?: number;
+    /** Smoothing 0–1 (0 = immediate, default 0). */
+    smooth?: number;
+}
+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 the scroll position of `source` (it moves through the viewport). Returns a stop function. */
+    scrub(source: Element, options?: ScrubOptions): () => void;
+    /** 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`
+ * (`'-=200'`, `'<'`, `'label+=100'`, ms), `data-duration` and `data-label`
+ * fine-tune it.
+ *
+ * Attributes: `trigger` (`view` default · `click` · `manual`), `scrub`
+ * (progress follows scroll instead of playing), `overlap` (ms each step
+ * overlaps the previous, default 0), `duration` (600), `stagger` (ms),
+ * `repeat` (replay every time it enters the viewport). Methods: `play()`,
+ * `reverse()`, `seek(t)`; property `timeline`. Event `usa:complete`.
+ * Reduced motion: steps appear in their final state.
+ */
+interface UsaTimelineElement extends UsaElement {
+    readonly timeline: Timeline | null;
+    play(): Promise<void>;
+    reverse(): Promise<void>;
+    seek(to: number | string): void;
+}
+
+/**
+ * use-scroll-animate/components/timeline — choreography (v3.1).
+ * `timeline()` chains, overlaps, labels, seeks, reverses and scroll-scrubs
+ * WAAPI animations on one playhead; `<usa-timeline>` builds one from
+ * `data-tl` children.
+ */
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-timeline': UsaTimelineElement;
+    }
+}
+
 /** The component categories and their default tags. */
 declare const COMPONENT_CATEGORIES: {
     readonly reveal: readonly ["usa-reveal", "usa-stagger", "usa-scroll-progress", "usa-scrolly"];
@@ -1301,6 +1387,7 @@ declare const COMPONENT_CATEGORIES: {
     readonly click: readonly ["usa-click", "usa-button", "usa-icon-morph", "usa-like", "usa-hold", "usa-double-tap", "usa-checkbox"];
     readonly ui: readonly ["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"];
     readonly page: readonly ["usa-cursor", "usa-fullpage", "usa-loading-bar", "usa-back-to-top", "usa-ambient", "usa-splash", "usa-auto-skeleton", "usa-motion-switch"];
+    readonly timeline: readonly ["usa-timeline"];
 };
 type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
 

package/dist/components/vue.d.ts

@@ -1288,6 +1288,92 @@ 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 (default: timeline default, 600). */
+    duration?: number;
+    /** CSS easing (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. */
+    offset?: number;
+    /** Smoothing 0–1 (0 = immediate, default 0). */
+    smooth?: number;
+}
+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 the scroll position of `source` (it moves through the viewport). Returns a stop function. */
+    scrub(source: Element, options?: ScrubOptions): () => void;
+    /** 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`
+ * (`'-=200'`, `'<'`, `'label+=100'`, ms), `data-duration` and `data-label`
+ * fine-tune it.
+ *
+ * Attributes: `trigger` (`view` default · `click` · `manual`), `scrub`
+ * (progress follows scroll instead of playing), `overlap` (ms each step
+ * overlaps the previous, default 0), `duration` (600), `stagger` (ms),
+ * `repeat` (replay every time it enters the viewport). Methods: `play()`,
+ * `reverse()`, `seek(t)`; property `timeline`. Event `usa:complete`.
+ * Reduced motion: steps appear in their final state.
+ */
+interface UsaTimelineElement extends UsaElement {
+    readonly timeline: Timeline | null;
+    play(): Promise<void>;
+    reverse(): Promise<void>;
+    seek(to: number | string): void;
+}
+
+/**
+ * use-scroll-animate/components/timeline — choreography (v3.1).
+ * `timeline()` chains, overlaps, labels, seeks, reverses and scroll-scrubs
+ * WAAPI animations on one playhead; `<usa-timeline>` builds one from
+ * `data-tl` children.
+ */
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-timeline': UsaTimelineElement;
+    }
+}
+
 /** The component categories and their default tags. */
 declare const COMPONENT_CATEGORIES: {
     readonly reveal: readonly ["usa-reveal", "usa-stagger", "usa-scroll-progress", "usa-scrolly"];
@@ -1301,6 +1387,7 @@ declare const COMPONENT_CATEGORIES: {
     readonly click: readonly ["usa-click", "usa-button", "usa-icon-morph", "usa-like", "usa-hold", "usa-double-tap", "usa-checkbox"];
     readonly ui: readonly ["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"];
     readonly page: readonly ["usa-cursor", "usa-fullpage", "usa-loading-bar", "usa-back-to-top", "usa-ambient", "usa-splash", "usa-auto-skeleton", "usa-motion-switch"];
+    readonly timeline: readonly ["usa-timeline"];
 };
 type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
 

package/dist/components/vue.js

@@ -1,19 +1,20 @@
 import { defineComponents } from '../components.js';
 import './reveal.js';
-import '../chunks/base-Co98Z2iM.js';
+import '../chunks/base-Cu-86Z31.js';
 import './text.js';
 import './interaction.js';
 import './feedback.js';
 import './background.js';
-import '../chunks/variants-Dp_5lJ_J.js';
+import '../chunks/variants-BQ3gCb5L.js';
 import './transitions.js';
 import './physics.js';
-import '../chunks/spring-YNUpez2g.js';
+import '../chunks/spring-BV-cpTHC.js';
 import './cards.js';
 import './click.js';
 import './ui.js';
 import './page.js';
-import '../chunks/index-tags-f37txHmb.js';
+import './timeline.js';
+import '../chunks/index-tags-D7NynL4r.js';
 
 /**
  * use-scroll-animate/components/vue — Vue integration (v2.9).

package/dist/components/vue.js.map

@@ -1 +1 @@
-{"version":3,"file":"vue.js","sources":["../../src/components/frameworks/vue.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/vue — Vue integration (v2.9).\n *\n * ```js\n * // vite.config.js\n * import vue from '@vitejs/plugin-vue';\n * import { isUsaElement } from 'use-scroll-animate/components/vue';\n * export default { plugins: [vue({ template: { compilerOptions: { isCustomElement: isUsaElement } } })] };\n *\n * // main.js\n * import { UsaPlugin } from 'use-scroll-animate/components/vue';\n * app.use(UsaPlugin, { categories: ['click', 'cards'] });\n * ```\n * In templates, listen with `@usa:change=\"…\"` and bind properties with\n * `.prop`: `<usa-toggle :checked.prop=\"on\" @usa:change=\"on = $event.detail.checked\">`.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\n\n/** `compilerOptions.isCustomElement` predicate for every `<usa-*>` tag. */\nexport const isUsaElement = (tag: string): boolean => tag.startsWith('usa-');\n\nexport interface UsaPluginOptions {\n  /** Only register these categories (default: all). */\n  categories?: ComponentCategory[];\n}\n\n/** Vue plugin: registers the `<usa-*>` elements (client only) and sets `isCustomElement` at runtime. */\nexport const UsaPlugin = {\n  install(app: { config: { compilerOptions?: { isCustomElement?: (t: string) => boolean } } }, options: UsaPluginOptions = {}): void {\n    const co = (app.config.compilerOptions ||= {});\n    const prev = co.isCustomElement;\n    co.isCustomElement = (t: string) => isUsaElement(t) || !!prev?.(t);\n    defineComponents(options.categories);\n  },\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;AAeG;AAGH;AACO,MAAM,YAAY,GAAG,CAAC,GAAW,KAAc,GAAG,CAAC,UAAU,CAAC,MAAM;AAO3E;AACO,MAAM,SAAS,GAAG;AACvB,IAAA,OAAO,CAAC,GAAmF,EAAE,OAAA,GAA4B,EAAE,EAAA;;AACzH,QAAA,MAAM,EAAE,IAAG,CAAA,EAAA,GAAC,GAAG,CAAC,MAAM,EAAC,eAAe,KAAA,EAAA,CAAf,eAAe,GAAK,EAAE,EAAC;AAC9C,QAAA,MAAM,IAAI,GAAG,EAAE,CAAC,eAAe;QAC/B,EAAE,CAAC,eAAe,GAAG,CAAC,CAAS,KAAK,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;AAClE,QAAA,gBAAgB,CAAC,OAAO,CAAC,UAAU,CAAC;IACtC,CAAC;;;;;"}
+{"version":3,"file":"vue.js","sources":["../../src/components/frameworks/vue.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/vue — Vue integration (v2.9).\n *\n * ```js\n * // vite.config.js\n * import vue from '@vitejs/plugin-vue';\n * import { isUsaElement } from 'use-scroll-animate/components/vue';\n * export default { plugins: [vue({ template: { compilerOptions: { isCustomElement: isUsaElement } } })] };\n *\n * // main.js\n * import { UsaPlugin } from 'use-scroll-animate/components/vue';\n * app.use(UsaPlugin, { categories: ['click', 'cards'] });\n * ```\n * In templates, listen with `@usa:change=\"…\"` and bind properties with\n * `.prop`: `<usa-toggle :checked.prop=\"on\" @usa:change=\"on = $event.detail.checked\">`.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\n\n/** `compilerOptions.isCustomElement` predicate for every `<usa-*>` tag. */\nexport const isUsaElement = (tag: string): boolean => tag.startsWith('usa-');\n\nexport interface UsaPluginOptions {\n  /** Only register these categories (default: all). */\n  categories?: ComponentCategory[];\n}\n\n/** Vue plugin: registers the `<usa-*>` elements (client only) and sets `isCustomElement` at runtime. */\nexport const UsaPlugin = {\n  install(app: { config: { compilerOptions?: { isCustomElement?: (t: string) => boolean } } }, options: UsaPluginOptions = {}): void {\n    const co = (app.config.compilerOptions ||= {});\n    const prev = co.isCustomElement;\n    co.isCustomElement = (t: string) => isUsaElement(t) || !!prev?.(t);\n    defineComponents(options.categories);\n  },\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;AAeG;AAGH;AACO,MAAM,YAAY,GAAG,CAAC,GAAW,KAAc,GAAG,CAAC,UAAU,CAAC,MAAM;AAO3E;AACO,MAAM,SAAS,GAAG;AACvB,IAAA,OAAO,CAAC,GAAmF,EAAE,OAAA,GAA4B,EAAE,EAAA;;AACzH,QAAA,MAAM,EAAE,IAAG,CAAA,EAAA,GAAC,GAAG,CAAC,MAAM,EAAC,eAAe,KAAA,EAAA,CAAf,eAAe,GAAK,EAAE,EAAC;AAC9C,QAAA,MAAM,IAAI,GAAG,EAAE,CAAC,eAAe;QAC/B,EAAE,CAAC,eAAe,GAAG,CAAC,CAAS,KAAK,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;AAClE,QAAA,gBAAgB,CAAC,OAAO,CAAC,UAAU,CAAC;IACtC,CAAC;;;;;"}

package/dist/components.cjs

@@ -11,9 +11,10 @@ var components_cards = require('./components/cards.cjs');
 var components_click = require('./components/click.cjs');
 var components_ui = require('./components/ui.cjs');
 var components_page = require('./components/page.cjs');
+var components_timeline = require('./components/timeline.cjs');
 var variants = require('./chunks/variants-BNIrn4ch.cjs');
 var base = require('./chunks/base-CXx7jZ-o.cjs');
-var indexTags = require('./chunks/index-tags-BEM98giN.cjs');
+var indexTags = require('./chunks/index-tags-Gw1G06Pb.cjs');
 var spring = require('./chunks/spring-2OTnYCzm.cjs');
 
 /**
@@ -48,6 +49,7 @@ const BY_CATEGORY = {
     click: components_click.defineClickComponents,
     ui: components_ui.defineUiComponents,
     page: components_page.definePageComponents,
+    timeline: components_timeline.defineTimelineComponents,
 };
 /**
  * Register every `<usa-*>` component (or only the given categories).
@@ -177,6 +179,11 @@ exports.setMotionIntensity = components_page.setMotionIntensity;
 exports.smoothScroll = components_page.smoothScroll;
 exports.supportsViewTransitions = components_page.supportsViewTransitions;
 exports.themeTransition = components_page.themeTransition;
+exports.TIMELINE_PRESETS = components_timeline.TIMELINE_PRESETS;
+exports.defineTimeline = components_timeline.defineTimeline;
+exports.defineTimelineComponents = components_timeline.defineTimelineComponents;
+exports.resolvePosition = components_timeline.resolvePosition;
+exports.timeline = components_timeline.timeline;
 exports.VARIANTS = variants.VARIANTS;
 exports.adoptVariants = variants.adoptVariants;
 exports.setVariant = variants.setVariant;

package/dist/components.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"components.cjs","sources":["../src/components/index.ts"],"sourcesContent":["/**\n * use-scroll-animate/components\n *\n * Framework-agnostic, dependency-free animated UI components built on\n * Custom Elements + CSS + the Web Animations API. They run in any browser\n * and in Windows desktop apps that render with a web view: Electron, Tauri\n * (WebView2), WinUI 3 / WPF / WinForms with WebView2, and installed PWAs.\n *\n * ```js\n * import { defineComponents } from 'use-scroll-animate/components';\n * defineComponents(); // registers every <usa-*> element\n * // or only what you use (tree-shakable):\n * import { defineTypewriter } from 'use-scroll-animate/components/text';\n * ```\n *\n * Importing has no side effects and is SSR-safe; nothing is registered\n * until a `define*()` function runs in a browser.\n *\n * @license MIT\n */\nimport { defineRevealComponents } from './reveal/index';\nimport { defineTextComponents } from './text/index';\nimport { defineInteractionComponents } from './interaction/index';\nimport { defineFeedbackComponents } from './feedback/index';\nimport { defineBackgroundComponents } from './background/index';\nimport { defineTransitionComponents } from './transitions/index';\nimport { definePhysicsComponents } from './physics/index';\nimport { defineCardComponents } from './cards/index';\nimport { defineClickComponents } from './click/index';\nimport { defineUiComponents } from './ui/index';\nimport { definePageComponents } from './page/index';\nimport { adoptVariants } from './ui/variants';\nimport { canDefine } from './base';\n\nexport * from './reveal/index';\nexport * from './text/index';\nexport * from './interaction/index';\nexport * from './feedback/index';\nexport * from './background/index';\nexport * from './transitions/index';\nexport * from './physics/index';\nexport * from './cards/index';\nexport * from './click/index';\nexport * from './ui/index';\nexport * from './page/index';\n\nexport { COMPONENT_CATEGORIES } from './index-tags';\nexport type { ComponentCategory } from './index-tags';\nimport { COMPONENT_CATEGORIES, type ComponentCategory } from './index-tags';\n\nconst BY_CATEGORY: Record<ComponentCategory, () => void> = {\n  reveal: defineRevealComponents,\n  text: defineTextComponents,\n  interaction: defineInteractionComponents,\n  feedback: defineFeedbackComponents,\n  background: defineBackgroundComponents,\n  transitions: defineTransitionComponents,\n  physics: definePhysicsComponents,\n  cards: defineCardComponents,\n  click: defineClickComponents,\n  ui: defineUiComponents,\n  page: definePageComponents,\n};\n\n/**\n * Register every `<usa-*>` component (or only the given categories).\n * Safe to call more than once and on the server (no-op without DOM).\n */\nexport function defineComponents(categories?: ComponentCategory[]): void {\n  if (canDefine()) adoptVariants();\n  (categories || (Object.keys(BY_CATEGORY) as ComponentCategory[])).forEach((c) => BY_CATEGORY[c]?.());\n}\n"],"names":["defineRevealComponents","defineTextComponents","defineInteractionComponents","defineFeedbackComponents","defineBackgroundComponents","defineTransitionComponents","definePhysicsComponents","defineCardComponents","defineClickComponents","defineUiComponents","definePageComponents","canDefine","adoptVariants"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;AAmBG;AA+BH,MAAM,WAAW,GAA0C;AACzD,IAAA,MAAM,EAAEA,wCAAsB;AAC9B,IAAA,IAAI,EAAEC,oCAAoB;AAC1B,IAAA,WAAW,EAAEC,kDAA2B;AACxC,IAAA,QAAQ,EAAEC,4CAAwB;AAClC,IAAA,UAAU,EAAEC,gDAA0B;AACtC,IAAA,WAAW,EAAEC,iDAA0B;AACvC,IAAA,OAAO,EAAEC,0CAAuB;AAChC,IAAA,KAAK,EAAEC,qCAAoB;AAC3B,IAAA,KAAK,EAAEC,sCAAqB;AAC5B,IAAA,EAAE,EAAEC,gCAAkB;AACtB,IAAA,IAAI,EAAEC,oCAAoB;CAC3B;AAED;;;AAGG;AACG,SAAU,gBAAgB,CAAC,UAAgC,EAAA;AAC/D,IAAA,IAAIC,cAAS,EAAE;AAAE,QAAAC,sBAAa,EAAE;IAChC,CAAC,UAAU,IAAK,MAAM,CAAC,IAAI,CAAC,WAAW,CAAyB,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;AACtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"components.cjs","sources":["../src/components/index.ts"],"sourcesContent":["/**\n * use-scroll-animate/components\n *\n * Framework-agnostic, dependency-free animated UI components built on\n * Custom Elements + CSS + the Web Animations API. They run in any browser\n * and in Windows desktop apps that render with a web view: Electron, Tauri\n * (WebView2), WinUI 3 / WPF / WinForms with WebView2, and installed PWAs.\n *\n * ```js\n * import { defineComponents } from 'use-scroll-animate/components';\n * defineComponents(); // registers every <usa-*> element\n * // or only what you use (tree-shakable):\n * import { defineTypewriter } from 'use-scroll-animate/components/text';\n * ```\n *\n * Importing has no side effects and is SSR-safe; nothing is registered\n * until a `define*()` function runs in a browser.\n *\n * @license MIT\n */\nimport { defineRevealComponents } from './reveal/index';\nimport { defineTextComponents } from './text/index';\nimport { defineInteractionComponents } from './interaction/index';\nimport { defineFeedbackComponents } from './feedback/index';\nimport { defineBackgroundComponents } from './background/index';\nimport { defineTransitionComponents } from './transitions/index';\nimport { definePhysicsComponents } from './physics/index';\nimport { defineCardComponents } from './cards/index';\nimport { defineClickComponents } from './click/index';\nimport { defineUiComponents } from './ui/index';\nimport { definePageComponents } from './page/index';\nimport { defineTimelineComponents } from './timeline/index';\nimport { adoptVariants } from './ui/variants';\nimport { canDefine } from './base';\n\nexport * from './reveal/index';\nexport * from './text/index';\nexport * from './interaction/index';\nexport * from './feedback/index';\nexport * from './background/index';\nexport * from './transitions/index';\nexport * from './physics/index';\nexport * from './cards/index';\nexport * from './click/index';\nexport * from './ui/index';\nexport * from './page/index';\nexport * from './timeline/index';\n\nexport { COMPONENT_CATEGORIES } from './index-tags';\nexport type { ComponentCategory } from './index-tags';\nimport { COMPONENT_CATEGORIES, type ComponentCategory } from './index-tags';\n\nconst BY_CATEGORY: Record<ComponentCategory, () => void> = {\n  reveal: defineRevealComponents,\n  text: defineTextComponents,\n  interaction: defineInteractionComponents,\n  feedback: defineFeedbackComponents,\n  background: defineBackgroundComponents,\n  transitions: defineTransitionComponents,\n  physics: definePhysicsComponents,\n  cards: defineCardComponents,\n  click: defineClickComponents,\n  ui: defineUiComponents,\n  page: definePageComponents,\n  timeline: defineTimelineComponents,\n};\n\n/**\n * Register every `<usa-*>` component (or only the given categories).\n * Safe to call more than once and on the server (no-op without DOM).\n */\nexport function defineComponents(categories?: ComponentCategory[]): void {\n  if (canDefine()) adoptVariants();\n  (categories || (Object.keys(BY_CATEGORY) as ComponentCategory[])).forEach((c) => BY_CATEGORY[c]?.());\n}\n"],"names":["defineRevealComponents","defineTextComponents","defineInteractionComponents","defineFeedbackComponents","defineBackgroundComponents","defineTransitionComponents","definePhysicsComponents","defineCardComponents","defineClickComponents","defineUiComponents","definePageComponents","defineTimelineComponents","canDefine","adoptVariants"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;AAmBG;AAiCH,MAAM,WAAW,GAA0C;AACzD,IAAA,MAAM,EAAEA,wCAAsB;AAC9B,IAAA,IAAI,EAAEC,oCAAoB;AAC1B,IAAA,WAAW,EAAEC,kDAA2B;AACxC,IAAA,QAAQ,EAAEC,4CAAwB;AAClC,IAAA,UAAU,EAAEC,gDAA0B;AACtC,IAAA,WAAW,EAAEC,iDAA0B;AACvC,IAAA,OAAO,EAAEC,0CAAuB;AAChC,IAAA,KAAK,EAAEC,qCAAoB;AAC3B,IAAA,KAAK,EAAEC,sCAAqB;AAC5B,IAAA,EAAE,EAAEC,gCAAkB;AACtB,IAAA,IAAI,EAAEC,oCAAoB;AAC1B,IAAA,QAAQ,EAAEC,4CAAwB;CACnC;AAED;;;AAGG;AACG,SAAU,gBAAgB,CAAC,UAAgC,EAAA;AAC/D,IAAA,IAAIC,cAAS,EAAE;AAAE,QAAAC,sBAAa,EAAE;IAChC,CAAC,UAAU,IAAK,MAAM,CAAC,IAAI,CAAC,WAAW,CAAyB,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;AACtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/components.css

@@ -66,3 +66,4 @@ usa-loading-bar{--usa-loading:0;--usa-loading-h:3px;--usa-loading-color:var(--us
 usa-motion-switch{--usa-motion-i:2;position:relative;display:inline-grid;grid-auto-flow:column;grid-auto-columns:1fr;padding:3px;border-radius:999px;background:color-mix(in srgb,currentColor 9%,transparent);isolation:isolate}usa-motion-switch button{position:relative;z-index:1;padding:6px 12px;border:0;background:none;color:inherit;font:inherit;font-size:0.85em;border-radius:999px;cursor:pointer}usa-motion-switch button[aria-checked="true"]{color:var(--usa-accent-text,#fff)}usa-motion-switch button:focus-visible{outline:2px solid var(--usa-accent,#7c5cff);outline-offset:1px}usa-motion-switch .usa-motion-thumb{position:absolute;z-index:0;top:3px;bottom:3px;left:3px;width:calc((100% - 6px) / 4);border-radius:999px;background:var(--usa-accent,#7c5cff);transform:translateX(calc(var(--usa-motion-i) * 100%));transition:transform 0.4s cubic-bezier(0.34,1.4,0.64,1)}@media (prefers-reduced-motion:reduce){usa-motion-switch .usa-motion-thumb{transition:none}}
 usa-splash{position:fixed;inset:0;z-index:2147483400;display:grid;place-items:center;background:var(--usa-splash-bg,var(--usa-surface,#0b0d12));color:var(--usa-text,#fff)}usa-splash[hidden]{display:none}
 ::view-transition-group(root){animation-duration:var(--usa-pt-duration,600ms)}html[data-usa-pt] ::view-transition-old(root),html[data-usa-pt] ::view-transition-new(root){animation-duration:var(--usa-pt-duration,600ms);animation-timing-function:cubic-bezier(0.22,1,0.36,1);mix-blend-mode:normal}html[data-usa-pt="slide"] ::view-transition-old(root),html[data-usa-pt="slide-left"] ::view-transition-old(root){animation-name:usa-pt-out-left}html[data-usa-pt="slide"] ::view-transition-new(root),html[data-usa-pt="slide-left"] ::view-transition-new(root){animation-name:usa-pt-in-right}html[data-usa-pt="slide-right"] ::view-transition-old(root){animation-name:usa-pt-out-right}html[data-usa-pt="slide-right"] ::view-transition-new(root){animation-name:usa-pt-in-left}html[data-usa-pt="slide-up"] ::view-transition-old(root){animation-name:usa-pt-out-up}html[data-usa-pt="slide-up"] ::view-transition-new(root){animation-name:usa-pt-in-up}html[data-usa-pt="zoom"] ::view-transition-old(root){animation-name:usa-pt-zoom-out}html[data-usa-pt="zoom"] ::view-transition-new(root){animation-name:usa-pt-zoom-in}html[data-usa-pt="circle"] ::view-transition-old(root){animation:none}html[data-usa-pt="circle"] ::view-transition-new(root){animation-name:usa-pt-circle}html[data-usa-pt="blinds"] ::view-transition-old(root){animation:none}html[data-usa-pt="blinds"] ::view-transition-new(root){animation-name:usa-pt-blinds;-webkit-mask-image:repeating-linear-gradient(to bottom,#000 0 var(--usa-blind),transparent var(--usa-blind) 10vh);mask-image:repeating-linear-gradient(to bottom,#000 0 var(--usa-blind),transparent var(--usa-blind) 10vh)}html[data-usa-pt="pixel"] ::view-transition-old(root){animation-name:usa-pt-pixel-out;animation-timing-function:steps(10,end)}html[data-usa-pt="pixel"] ::view-transition-new(root){animation-name:usa-pt-pixel-in;animation-timing-function:steps(10,end)}@property --usa-blind{syntax:"<length-percentage>";inherits:false;initial-value:0vh}@keyframes usa-pt-out-left{to{transform:translateX(-30%);opacity:0}}@keyframes usa-pt-in-right{from{transform:translateX(30%);opacity:0}}@keyframes usa-pt-out-right{to{transform:translateX(30%);opacity:0}}@keyframes usa-pt-in-left{from{transform:translateX(-30%);opacity:0}}@keyframes usa-pt-out-up{to{transform:translateY(-12%);opacity:0}}@keyframes usa-pt-in-up{from{transform:translateY(12%);opacity:0}}@keyframes usa-pt-zoom-out{to{transform:scale(0.92);opacity:0}}@keyframes usa-pt-zoom-in{from{transform:scale(1.08);opacity:0}}@keyframes usa-pt-circle{from{clip-path:circle(0 at var(--usa-pt-x,50%) var(--usa-pt-y,50%))}to{clip-path:circle(var(--usa-pt-r,150vmax) at var(--usa-pt-x,50%) var(--usa-pt-y,50%))}}@keyframes usa-pt-blinds{from{--usa-blind:0vh}to{--usa-blind:10vh}}@keyframes usa-pt-pixel-out{to{opacity:0;filter:blur(6px) contrast(1.4)}}@keyframes usa-pt-pixel-in{from{opacity:0;filter:blur(6px) contrast(1.4)}}@media (prefers-reduced-motion:reduce){::view-transition-group(*),::view-transition-old(*),::view-transition-new(*){animation:none !important}}
+usa-timeline{display:block}usa-timeline[scrub]{position:relative}@media (prefers-reduced-motion:reduce){usa-timeline [data-tl]{opacity:1 !important;transform:none !important;filter:none !important;clip-path:none !important}}

package/dist/components.d.cts

@@ -1774,6 +1774,123 @@ 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 (default: timeline default, 600). */
+    duration?: number;
+    /** CSS easing (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 TimelineOptions {
+    /** Defaults for every step. */
+    defaults?: Pick<TimelineStepOptions, 'duration' | 'easing' | 'stagger'>;
+    /** Playback rate (1 = normal). */
+    speed?: number;
+    /** Called after `play()` reaches the end (or the start when reversed). */
+    onComplete?: () => void;
+    /** Called on every frame with progress 0–1. */
+    onUpdate?: (progress: number) => void;
+}
+interface ScrubOptions {
+    /** Scroll offset (px) before the source's top reaches the viewport bottom where progress starts. */
+    offset?: number;
+    /** Smoothing 0–1 (0 = immediate, default 0). */
+    smooth?: number;
+}
+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 the scroll position of `source` (it moves through the viewport). Returns a stop function. */
+    scrub(source: Element, options?: ScrubOptions): () => void;
+    /** Stop and drop every animation (elements keep their last frame). */
+    cancel(): void;
+}
+/** Keyframe presets usable by name in `to()` and `data-tl`. */
+declare const TIMELINE_PRESETS: Record<string, Keyframe[]>;
+/** Resolve a position against the previous step and labels (pure). */
+declare function resolvePosition(pos: TimelinePosition | undefined, end: number, prevStart: number, labels?: Record<string, number>): number;
+/**
+ * Choreograph animations on one clock: chain, overlap, label, seek, reverse and
+ * scrub them with scroll. Built on WAAPI (paused animations driven by one
+ * playhead); without WAAPI or under reduced motion it jumps to the end state.
+ *
+ * @example
+ * const tl = timeline({ defaults: { duration: 500 } })
+ *   .to('.title', 'fade-up')
+ *   .label('cards')
+ *   .to('.card', 'scale', { stagger: 80, at: '-=200' })
+ *   .to('.cta', [{ opacity: 0 }, { opacity: 1 }], { at: 'cards+=400' });
+ * tl.play();             // or tl.scrub(document.querySelector('.hero'))
+ */
+declare function timeline(options?: TimelineOptions): Timeline;
+
+/**
+ * `<usa-timeline>` — declarative choreography. Every descendant with
+ * `data-tl="<preset>"` becomes a step, in document order; `data-at`
+ * (`'-=200'`, `'<'`, `'label+=100'`, ms), `data-duration` and `data-label`
+ * fine-tune it.
+ *
+ * Attributes: `trigger` (`view` default · `click` · `manual`), `scrub`
+ * (progress follows scroll instead of playing), `overlap` (ms each step
+ * overlaps the previous, default 0), `duration` (600), `stagger` (ms),
+ * `repeat` (replay every time it enters the viewport). Methods: `play()`,
+ * `reverse()`, `seek(t)`; property `timeline`. Event `usa:complete`.
+ * Reduced motion: steps appear in their final state.
+ */
+interface UsaTimelineElement extends UsaElement {
+    readonly timeline: Timeline | null;
+    play(): Promise<void>;
+    reverse(): Promise<void>;
+    seek(to: number | string): void;
+}
+declare function defineTimeline(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * use-scroll-animate/components/timeline — choreography (v3.1).
+ * `timeline()` chains, overlaps, labels, seeks, reverses and scroll-scrubs
+ * WAAPI animations on one playhead; `<usa-timeline>` builds one from
+ * `data-tl` children.
+ */
+
+/** Register every component of this category under its default tag. */
+declare function defineTimelineComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-timeline': UsaTimelineElement;
+    }
+}
+
 /** The component categories and their default tags. */
 declare const COMPONENT_CATEGORIES: {
     readonly reveal: readonly ["usa-reveal", "usa-stagger", "usa-scroll-progress", "usa-scrolly"];
@@ -1787,6 +1904,7 @@ declare const COMPONENT_CATEGORIES: {
     readonly click: readonly ["usa-click", "usa-button", "usa-icon-morph", "usa-like", "usa-hold", "usa-double-tap", "usa-checkbox"];
     readonly ui: readonly ["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"];
     readonly page: readonly ["usa-cursor", "usa-fullpage", "usa-loading-bar", "usa-back-to-top", "usa-ambient", "usa-splash", "usa-auto-skeleton", "usa-motion-switch"];
+    readonly timeline: readonly ["usa-timeline"];
 };
 type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
 
@@ -1796,5 +1914,5 @@ type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
  */
 declare function defineComponents(categories?: ComponentCategory[]): void;
 
-export { AMBIENT_EFFECTS, BUTTON_DEFORMS, CARD_EFFECTS, CLICK_EFFECTS, COMPONENT_CATEGORIES, CURSOR_MODES, MORPH_ICONS, MOTION_SCALE, PAGE_EFFECTS, REVEAL_EFFECTS, SPINNER_VARIANTS, SPRING_EFFECTS, SPRING_PRESETS, VARIANTS, adoptVariants, burst, confetti, configureComponents, connectedAnimation, createSpring, defineAccordion, defineAcrylic, defineAmbient, defineAurora, defineAutoSkeleton, defineAvatarStack, defineBackToTop, defineBackgroundComponents, defineBadge, defineBlobs, defineBottomSheet, defineButton, defineCard, defineCardComponents, defineCardStack, defineCarousel3d, defineCheck, defineCheckbox, defineClick, defineClickComponents, defineComponents, defineCounter, defineCursor, defineDialog, defineDotNetwork, defineDoubleTap, defineDraggable, defineDrawer, defineFab, defineFeedbackComponents, defineFlipList, defineFullpage, defineGlitch, defineGradientText, defineGrain, defineGridGlow, defineHandwriting, defineHold, defineIconMorph, defineInteractionComponents, defineLike, defineLoadingBar, defineMagnetic, defineMarquee, defineMotionSwitch, defineNavbar, defineOverscroll, definePageComponents, defineParticles, definePhysicsComponents, definePopover, definePress, defineProgress, definePullRefresh, defineRating, defineReveal, defineRevealComponents, defineRipple, defineScramble, defineScrollHighlight, defineScrollProgress, defineScrolly, defineShimmerText, defineSkeleton, defineSlider, defineSpinner, defineSplash, defineSplitText, defineSpotlight, defineSpring, defineStagger, defineStickyStack, defineTabs, defineTextComponents, defineTextRotate, defineTilt, defineToaster, defineToggle, defineTooltip, defineTransitionComponents, defineTypewriter, defineUiComponents, defineViewSwitch, defineWaterRipple, defineWaveText, easeOutExpo, enableMpaTransitions, flip, fluentPreset, getMotionIntensity, haptic, linearEasing, loadingBar, morphPath, pageTransition, prefersReducedMotion, projectInertia, readScrollProgress, resolveSpring, restoreMotionIntensity, revealKeyframes, rubberBand, scrambleFrame, scrollToTarget, setMotionIntensity, setVariant, shake, smoothScroll, snapTo, spring, springEasing, springEffectKeyframes, springSamples, stepSpring, supportsLinearEasing, supportsViewTransitions, themeTransition, toast, viewTransition };
-export type { AmbientEffect, BurstOptions, ButtonDeform, ButtonShape, ButtonState, CardEffect, ClickEffect, ComponentCategory, ComponentsConfig, ConfettiOptions, ConnectedOptions, CursorMode, DialogVariant, FlipOptions, FluentPresetOptions, MotionIntensity, PageEffect, PageTransitionOptions, Placement, RevealEffect, SmoothScrollOptions, SpinnerVariant, SpringConfig, SpringEffect, SpringInput, SpringPreset, SpringValue, SpringValueOptions, ToastHandle, ToastOptions, ToastType, UsaAccordionElement, UsaAcrylicElement, UsaAmbientElement, UsaAuroraElement, UsaAutoSkeletonElement, UsaAvatarStackElement, UsaBackToTopElement, UsaBadgeElement, UsaBlobsElement, UsaBottomSheetElement, UsaButtonElement, UsaCardElement, UsaCardStackElement, UsaCarousel3dElement, UsaCheckElement, UsaCheckboxElement, UsaClickElement, UsaCounterElement, UsaCursorElement, UsaDialogElement, UsaDotNetworkElement, UsaDoubleTapElement, UsaDraggableElement, UsaDrawerElement, UsaElement, UsaFabElement, UsaFlipListElement, UsaFullpageElement, UsaGlitchElement, UsaGradientTextElement, UsaGrainElement, UsaGridGlowElement, UsaHandwritingElement, UsaHoldElement, UsaIconMorphElement, UsaLikeElement, UsaLoadingBarElement, UsaMagneticElement, UsaMarqueeElement, UsaMotionSwitchElement, UsaNavbarElement, UsaOverscrollElement, UsaParticlesElement, UsaPopoverElement, UsaPressElement, UsaProgressElement, UsaPullRefreshElement, UsaRatingElement, UsaRevealElement, UsaRippleElement, UsaScrambleElement, UsaScrollHighlightElement, UsaScrollProgressElement, UsaScrollyElement, UsaShimmerTextElement, UsaSkeletonElement, UsaSliderElement, UsaSpinnerElement, UsaSplashElement, UsaSplitTextElement, UsaSpotlightElement, UsaSpringElement, UsaStaggerElement, UsaStickyStackElement, UsaTabsElement, UsaTextRotateElement, UsaTiltElement, UsaToasterElement, UsaToggleElement, UsaTooltipElement, UsaTypewriterElement, UsaViewSwitchElement, UsaWaterRippleElement, UsaWaveTextElement, Variant, ViewTransitionOptions };
+export { AMBIENT_EFFECTS, BUTTON_DEFORMS, CARD_EFFECTS, CLICK_EFFECTS, COMPONENT_CATEGORIES, CURSOR_MODES, MORPH_ICONS, MOTION_SCALE, PAGE_EFFECTS, REVEAL_EFFECTS, SPINNER_VARIANTS, SPRING_EFFECTS, SPRING_PRESETS, TIMELINE_PRESETS, VARIANTS, adoptVariants, burst, confetti, configureComponents, connectedAnimation, createSpring, defineAccordion, defineAcrylic, defineAmbient, defineAurora, defineAutoSkeleton, defineAvatarStack, defineBackToTop, defineBackgroundComponents, defineBadge, defineBlobs, defineBottomSheet, defineButton, defineCard, defineCardComponents, defineCardStack, defineCarousel3d, defineCheck, defineCheckbox, defineClick, defineClickComponents, defineComponents, defineCounter, defineCursor, defineDialog, defineDotNetwork, defineDoubleTap, defineDraggable, defineDrawer, defineFab, defineFeedbackComponents, defineFlipList, defineFullpage, defineGlitch, defineGradientText, defineGrain, defineGridGlow, defineHandwriting, defineHold, defineIconMorph, defineInteractionComponents, defineLike, defineLoadingBar, defineMagnetic, defineMarquee, defineMotionSwitch, defineNavbar, defineOverscroll, definePageComponents, defineParticles, definePhysicsComponents, definePopover, definePress, defineProgress, definePullRefresh, defineRating, defineReveal, defineRevealComponents, defineRipple, defineScramble, defineScrollHighlight, defineScrollProgress, defineScrolly, defineShimmerText, defineSkeleton, defineSlider, defineSpinner, defineSplash, defineSplitText, defineSpotlight, defineSpring, defineStagger, defineStickyStack, defineTabs, defineTextComponents, defineTextRotate, defineTilt, defineTimeline, defineTimelineComponents, defineToaster, defineToggle, defineTooltip, defineTransitionComponents, defineTypewriter, defineUiComponents, defineViewSwitch, defineWaterRipple, defineWaveText, easeOutExpo, enableMpaTransitions, flip, fluentPreset, getMotionIntensity, haptic, linearEasing, loadingBar, morphPath, pageTransition, prefersReducedMotion, projectInertia, readScrollProgress, resolvePosition, resolveSpring, restoreMotionIntensity, revealKeyframes, rubberBand, scrambleFrame, scrollToTarget, setMotionIntensity, setVariant, shake, smoothScroll, snapTo, spring, springEasing, springEffectKeyframes, springSamples, stepSpring, supportsLinearEasing, supportsViewTransitions, themeTransition, timeline, toast, viewTransition };
+export type { AmbientEffect, BurstOptions, ButtonDeform, ButtonShape, ButtonState, CardEffect, ClickEffect, ComponentCategory, ComponentsConfig, ConfettiOptions, ConnectedOptions, CursorMode, DialogVariant, FlipOptions, FluentPresetOptions, MotionIntensity, PageEffect, PageTransitionOptions, Placement, RevealEffect, ScrubOptions, SmoothScrollOptions, SpinnerVariant, SpringConfig, SpringEffect, SpringInput, SpringPreset, SpringValue, SpringValueOptions, Timeline, TimelineOptions, TimelinePosition, TimelineStepOptions, ToastHandle, ToastOptions, ToastType, UsaAccordionElement, UsaAcrylicElement, UsaAmbientElement, UsaAuroraElement, UsaAutoSkeletonElement, UsaAvatarStackElement, UsaBackToTopElement, UsaBadgeElement, UsaBlobsElement, UsaBottomSheetElement, UsaButtonElement, UsaCardElement, UsaCardStackElement, UsaCarousel3dElement, UsaCheckElement, UsaCheckboxElement, UsaClickElement, UsaCounterElement, UsaCursorElement, UsaDialogElement, UsaDotNetworkElement, UsaDoubleTapElement, UsaDraggableElement, UsaDrawerElement, UsaElement, UsaFabElement, UsaFlipListElement, UsaFullpageElement, UsaGlitchElement, UsaGradientTextElement, UsaGrainElement, UsaGridGlowElement, UsaHandwritingElement, UsaHoldElement, UsaIconMorphElement, UsaLikeElement, UsaLoadingBarElement, UsaMagneticElement, UsaMarqueeElement, UsaMotionSwitchElement, UsaNavbarElement, UsaOverscrollElement, UsaParticlesElement, UsaPopoverElement, UsaPressElement, UsaProgressElement, UsaPullRefreshElement, UsaRatingElement, UsaRevealElement, UsaRippleElement, UsaScrambleElement, UsaScrollHighlightElement, UsaScrollProgressElement, UsaScrollyElement, UsaShimmerTextElement, UsaSkeletonElement, UsaSliderElement, UsaSpinnerElement, UsaSplashElement, UsaSplitTextElement, UsaSpotlightElement, UsaSpringElement, UsaStaggerElement, UsaStickyStackElement, UsaTabsElement, UsaTextRotateElement, UsaTiltElement, UsaTimelineElement, UsaToasterElement, UsaToggleElement, UsaTooltipElement, UsaTypewriterElement, UsaViewSwitchElement, UsaWaterRippleElement, UsaWaveTextElement, Variant, ViewTransitionOptions };

package/dist/components.d.ts

@@ -1774,6 +1774,123 @@ 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 (default: timeline default, 600). */
+    duration?: number;
+    /** CSS easing (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 TimelineOptions {
+    /** Defaults for every step. */
+    defaults?: Pick<TimelineStepOptions, 'duration' | 'easing' | 'stagger'>;
+    /** Playback rate (1 = normal). */
+    speed?: number;
+    /** Called after `play()` reaches the end (or the start when reversed). */
+    onComplete?: () => void;
+    /** Called on every frame with progress 0–1. */
+    onUpdate?: (progress: number) => void;
+}
+interface ScrubOptions {
+    /** Scroll offset (px) before the source's top reaches the viewport bottom where progress starts. */
+    offset?: number;
+    /** Smoothing 0–1 (0 = immediate, default 0). */
+    smooth?: number;
+}
+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 the scroll position of `source` (it moves through the viewport). Returns a stop function. */
+    scrub(source: Element, options?: ScrubOptions): () => void;
+    /** Stop and drop every animation (elements keep their last frame). */
+    cancel(): void;
+}
+/** Keyframe presets usable by name in `to()` and `data-tl`. */
+declare const TIMELINE_PRESETS: Record<string, Keyframe[]>;
+/** Resolve a position against the previous step and labels (pure). */
+declare function resolvePosition(pos: TimelinePosition | undefined, end: number, prevStart: number, labels?: Record<string, number>): number;
+/**
+ * Choreograph animations on one clock: chain, overlap, label, seek, reverse and
+ * scrub them with scroll. Built on WAAPI (paused animations driven by one
+ * playhead); without WAAPI or under reduced motion it jumps to the end state.
+ *
+ * @example
+ * const tl = timeline({ defaults: { duration: 500 } })
+ *   .to('.title', 'fade-up')
+ *   .label('cards')
+ *   .to('.card', 'scale', { stagger: 80, at: '-=200' })
+ *   .to('.cta', [{ opacity: 0 }, { opacity: 1 }], { at: 'cards+=400' });
+ * tl.play();             // or tl.scrub(document.querySelector('.hero'))
+ */
+declare function timeline(options?: TimelineOptions): Timeline;
+
+/**
+ * `<usa-timeline>` — declarative choreography. Every descendant with
+ * `data-tl="<preset>"` becomes a step, in document order; `data-at`
+ * (`'-=200'`, `'<'`, `'label+=100'`, ms), `data-duration` and `data-label`
+ * fine-tune it.
+ *
+ * Attributes: `trigger` (`view` default · `click` · `manual`), `scrub`
+ * (progress follows scroll instead of playing), `overlap` (ms each step
+ * overlaps the previous, default 0), `duration` (600), `stagger` (ms),
+ * `repeat` (replay every time it enters the viewport). Methods: `play()`,
+ * `reverse()`, `seek(t)`; property `timeline`. Event `usa:complete`.
+ * Reduced motion: steps appear in their final state.
+ */
+interface UsaTimelineElement extends UsaElement {
+    readonly timeline: Timeline | null;
+    play(): Promise<void>;
+    reverse(): Promise<void>;
+    seek(to: number | string): void;
+}
+declare function defineTimeline(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * use-scroll-animate/components/timeline — choreography (v3.1).
+ * `timeline()` chains, overlaps, labels, seeks, reverses and scroll-scrubs
+ * WAAPI animations on one playhead; `<usa-timeline>` builds one from
+ * `data-tl` children.
+ */
+
+/** Register every component of this category under its default tag. */
+declare function defineTimelineComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-timeline': UsaTimelineElement;
+    }
+}
+
 /** The component categories and their default tags. */
 declare const COMPONENT_CATEGORIES: {
     readonly reveal: readonly ["usa-reveal", "usa-stagger", "usa-scroll-progress", "usa-scrolly"];
@@ -1787,6 +1904,7 @@ declare const COMPONENT_CATEGORIES: {
     readonly click: readonly ["usa-click", "usa-button", "usa-icon-morph", "usa-like", "usa-hold", "usa-double-tap", "usa-checkbox"];
     readonly ui: readonly ["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"];
     readonly page: readonly ["usa-cursor", "usa-fullpage", "usa-loading-bar", "usa-back-to-top", "usa-ambient", "usa-splash", "usa-auto-skeleton", "usa-motion-switch"];
+    readonly timeline: readonly ["usa-timeline"];
 };
 type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
 
@@ -1796,5 +1914,5 @@ type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
  */
 declare function defineComponents(categories?: ComponentCategory[]): void;
 
-export { AMBIENT_EFFECTS, BUTTON_DEFORMS, CARD_EFFECTS, CLICK_EFFECTS, COMPONENT_CATEGORIES, CURSOR_MODES, MORPH_ICONS, MOTION_SCALE, PAGE_EFFECTS, REVEAL_EFFECTS, SPINNER_VARIANTS, SPRING_EFFECTS, SPRING_PRESETS, VARIANTS, adoptVariants, burst, confetti, configureComponents, connectedAnimation, createSpring, defineAccordion, defineAcrylic, defineAmbient, defineAurora, defineAutoSkeleton, defineAvatarStack, defineBackToTop, defineBackgroundComponents, defineBadge, defineBlobs, defineBottomSheet, defineButton, defineCard, defineCardComponents, defineCardStack, defineCarousel3d, defineCheck, defineCheckbox, defineClick, defineClickComponents, defineComponents, defineCounter, defineCursor, defineDialog, defineDotNetwork, defineDoubleTap, defineDraggable, defineDrawer, defineFab, defineFeedbackComponents, defineFlipList, defineFullpage, defineGlitch, defineGradientText, defineGrain, defineGridGlow, defineHandwriting, defineHold, defineIconMorph, defineInteractionComponents, defineLike, defineLoadingBar, defineMagnetic, defineMarquee, defineMotionSwitch, defineNavbar, defineOverscroll, definePageComponents, defineParticles, definePhysicsComponents, definePopover, definePress, defineProgress, definePullRefresh, defineRating, defineReveal, defineRevealComponents, defineRipple, defineScramble, defineScrollHighlight, defineScrollProgress, defineScrolly, defineShimmerText, defineSkeleton, defineSlider, defineSpinner, defineSplash, defineSplitText, defineSpotlight, defineSpring, defineStagger, defineStickyStack, defineTabs, defineTextComponents, defineTextRotate, defineTilt, defineToaster, defineToggle, defineTooltip, defineTransitionComponents, defineTypewriter, defineUiComponents, defineViewSwitch, defineWaterRipple, defineWaveText, easeOutExpo, enableMpaTransitions, flip, fluentPreset, getMotionIntensity, haptic, linearEasing, loadingBar, morphPath, pageTransition, prefersReducedMotion, projectInertia, readScrollProgress, resolveSpring, restoreMotionIntensity, revealKeyframes, rubberBand, scrambleFrame, scrollToTarget, setMotionIntensity, setVariant, shake, smoothScroll, snapTo, spring, springEasing, springEffectKeyframes, springSamples, stepSpring, supportsLinearEasing, supportsViewTransitions, themeTransition, toast, viewTransition };
-export type { AmbientEffect, BurstOptions, ButtonDeform, ButtonShape, ButtonState, CardEffect, ClickEffect, ComponentCategory, ComponentsConfig, ConfettiOptions, ConnectedOptions, CursorMode, DialogVariant, FlipOptions, FluentPresetOptions, MotionIntensity, PageEffect, PageTransitionOptions, Placement, RevealEffect, SmoothScrollOptions, SpinnerVariant, SpringConfig, SpringEffect, SpringInput, SpringPreset, SpringValue, SpringValueOptions, ToastHandle, ToastOptions, ToastType, UsaAccordionElement, UsaAcrylicElement, UsaAmbientElement, UsaAuroraElement, UsaAutoSkeletonElement, UsaAvatarStackElement, UsaBackToTopElement, UsaBadgeElement, UsaBlobsElement, UsaBottomSheetElement, UsaButtonElement, UsaCardElement, UsaCardStackElement, UsaCarousel3dElement, UsaCheckElement, UsaCheckboxElement, UsaClickElement, UsaCounterElement, UsaCursorElement, UsaDialogElement, UsaDotNetworkElement, UsaDoubleTapElement, UsaDraggableElement, UsaDrawerElement, UsaElement, UsaFabElement, UsaFlipListElement, UsaFullpageElement, UsaGlitchElement, UsaGradientTextElement, UsaGrainElement, UsaGridGlowElement, UsaHandwritingElement, UsaHoldElement, UsaIconMorphElement, UsaLikeElement, UsaLoadingBarElement, UsaMagneticElement, UsaMarqueeElement, UsaMotionSwitchElement, UsaNavbarElement, UsaOverscrollElement, UsaParticlesElement, UsaPopoverElement, UsaPressElement, UsaProgressElement, UsaPullRefreshElement, UsaRatingElement, UsaRevealElement, UsaRippleElement, UsaScrambleElement, UsaScrollHighlightElement, UsaScrollProgressElement, UsaScrollyElement, UsaShimmerTextElement, UsaSkeletonElement, UsaSliderElement, UsaSpinnerElement, UsaSplashElement, UsaSplitTextElement, UsaSpotlightElement, UsaSpringElement, UsaStaggerElement, UsaStickyStackElement, UsaTabsElement, UsaTextRotateElement, UsaTiltElement, UsaToasterElement, UsaToggleElement, UsaTooltipElement, UsaTypewriterElement, UsaViewSwitchElement, UsaWaterRippleElement, UsaWaveTextElement, Variant, ViewTransitionOptions };
+export { AMBIENT_EFFECTS, BUTTON_DEFORMS, CARD_EFFECTS, CLICK_EFFECTS, COMPONENT_CATEGORIES, CURSOR_MODES, MORPH_ICONS, MOTION_SCALE, PAGE_EFFECTS, REVEAL_EFFECTS, SPINNER_VARIANTS, SPRING_EFFECTS, SPRING_PRESETS, TIMELINE_PRESETS, VARIANTS, adoptVariants, burst, confetti, configureComponents, connectedAnimation, createSpring, defineAccordion, defineAcrylic, defineAmbient, defineAurora, defineAutoSkeleton, defineAvatarStack, defineBackToTop, defineBackgroundComponents, defineBadge, defineBlobs, defineBottomSheet, defineButton, defineCard, defineCardComponents, defineCardStack, defineCarousel3d, defineCheck, defineCheckbox, defineClick, defineClickComponents, defineComponents, defineCounter, defineCursor, defineDialog, defineDotNetwork, defineDoubleTap, defineDraggable, defineDrawer, defineFab, defineFeedbackComponents, defineFlipList, defineFullpage, defineGlitch, defineGradientText, defineGrain, defineGridGlow, defineHandwriting, defineHold, defineIconMorph, defineInteractionComponents, defineLike, defineLoadingBar, defineMagnetic, defineMarquee, defineMotionSwitch, defineNavbar, defineOverscroll, definePageComponents, defineParticles, definePhysicsComponents, definePopover, definePress, defineProgress, definePullRefresh, defineRating, defineReveal, defineRevealComponents, defineRipple, defineScramble, defineScrollHighlight, defineScrollProgress, defineScrolly, defineShimmerText, defineSkeleton, defineSlider, defineSpinner, defineSplash, defineSplitText, defineSpotlight, defineSpring, defineStagger, defineStickyStack, defineTabs, defineTextComponents, defineTextRotate, defineTilt, defineTimeline, defineTimelineComponents, defineToaster, defineToggle, defineTooltip, defineTransitionComponents, defineTypewriter, defineUiComponents, defineViewSwitch, defineWaterRipple, defineWaveText, easeOutExpo, enableMpaTransitions, flip, fluentPreset, getMotionIntensity, haptic, linearEasing, loadingBar, morphPath, pageTransition, prefersReducedMotion, projectInertia, readScrollProgress, resolvePosition, resolveSpring, restoreMotionIntensity, revealKeyframes, rubberBand, scrambleFrame, scrollToTarget, setMotionIntensity, setVariant, shake, smoothScroll, snapTo, spring, springEasing, springEffectKeyframes, springSamples, stepSpring, supportsLinearEasing, supportsViewTransitions, themeTransition, timeline, toast, viewTransition };
+export type { AmbientEffect, BurstOptions, ButtonDeform, ButtonShape, ButtonState, CardEffect, ClickEffect, ComponentCategory, ComponentsConfig, ConfettiOptions, ConnectedOptions, CursorMode, DialogVariant, FlipOptions, FluentPresetOptions, MotionIntensity, PageEffect, PageTransitionOptions, Placement, RevealEffect, ScrubOptions, SmoothScrollOptions, SpinnerVariant, SpringConfig, SpringEffect, SpringInput, SpringPreset, SpringValue, SpringValueOptions, Timeline, TimelineOptions, TimelinePosition, TimelineStepOptions, ToastHandle, ToastOptions, ToastType, UsaAccordionElement, UsaAcrylicElement, UsaAmbientElement, UsaAuroraElement, UsaAutoSkeletonElement, UsaAvatarStackElement, UsaBackToTopElement, UsaBadgeElement, UsaBlobsElement, UsaBottomSheetElement, UsaButtonElement, UsaCardElement, UsaCardStackElement, UsaCarousel3dElement, UsaCheckElement, UsaCheckboxElement, UsaClickElement, UsaCounterElement, UsaCursorElement, UsaDialogElement, UsaDotNetworkElement, UsaDoubleTapElement, UsaDraggableElement, UsaDrawerElement, UsaElement, UsaFabElement, UsaFlipListElement, UsaFullpageElement, UsaGlitchElement, UsaGradientTextElement, UsaGrainElement, UsaGridGlowElement, UsaHandwritingElement, UsaHoldElement, UsaIconMorphElement, UsaLikeElement, UsaLoadingBarElement, UsaMagneticElement, UsaMarqueeElement, UsaMotionSwitchElement, UsaNavbarElement, UsaOverscrollElement, UsaParticlesElement, UsaPopoverElement, UsaPressElement, UsaProgressElement, UsaPullRefreshElement, UsaRatingElement, UsaRevealElement, UsaRippleElement, UsaScrambleElement, UsaScrollHighlightElement, UsaScrollProgressElement, UsaScrollyElement, UsaShimmerTextElement, UsaSkeletonElement, UsaSliderElement, UsaSpinnerElement, UsaSplashElement, UsaSplitTextElement, UsaSpotlightElement, UsaSpringElement, UsaStaggerElement, UsaStickyStackElement, UsaTabsElement, UsaTextRotateElement, UsaTiltElement, UsaTimelineElement, UsaToasterElement, UsaToggleElement, UsaTooltipElement, UsaTypewriterElement, UsaViewSwitchElement, UsaWaterRippleElement, UsaWaveTextElement, Variant, ViewTransitionOptions };