use-scroll-animate 2.0.1 → 2.2.0

package/dist/components/text.d.cts

@@ -0,0 +1,164 @@
+/**
+ * use-scroll-animate/components — shared base for the `<usa-*>` custom elements.
+ *
+ * Everything here is lazy: nothing touches `window`, `document`,
+ * `HTMLElement` or `matchMedia` at import time, so the components can be
+ * imported during SSR (Next, Nuxt, Astro…) and in Electron/Tauri preload
+ * scripts. Classes are created the first time a `define*()` function runs.
+ */
+interface ComponentsConfig {
+    /**
+     * Inject each component's CSS when it is defined (default `true`). Uses a
+     * constructable stylesheet (`document.adoptedStyleSheets`, which a strict
+     * `style-src` CSP does not block) and falls back to a `<style>` tag. Set
+     * to `false` when you load `use-scroll-animate/components.css` yourself.
+     */
+    injectStyles?: boolean;
+    /**
+     * `'user'` (default) follows `prefers-reduced-motion`; `'reduce'` always
+     * uses the reduced variants (e.g. a kiosk / battery-saver mode);
+     * `'no-preference'` ignores the OS setting (only for demos — respect your users).
+     */
+    reducedMotion?: 'user' | 'reduce' | 'no-preference';
+}
+/** Change global component settings (call before `define*()` for `injectStyles`). */
+declare function configureComponents(options: ComponentsConfig): void;
+/** `true` when animations should be reduced (OS setting or `configureComponents`). */
+declare function prefersReducedMotion(): boolean;
+/**
+ * Members shared by every `<usa-*>` element. Attribute helpers, a cleanup
+ * bag that is emptied on disconnect, and motion helpers that degrade to the
+ * final state without WAAPI or under reduced motion.
+ */
+interface UsaElement extends HTMLElement {
+    /** `true` while reduced motion applies to this element. */
+    readonly reduced: boolean;
+}
+
+/**
+ * `<usa-typewriter>` — types text character by character, optionally cycling
+ * through several phrases (typing, pausing, deleting).
+ *
+ * Attributes: `text` (default: the element's text), `words` (phrases
+ * separated by `|`, overrides `text`), `speed` (ms per character, 55),
+ * `delete-speed` (ms, 30), `pause` (ms before deleting, 1400), `delay`
+ * (ms, 0), `loop`, `cursor="false"` to hide the caret, `start`
+ * (`view` | `load` | `manual`, default `view`). The full text is exposed to
+ * assistive tech via `aria-label`. Event: `usa:complete` (one pass done).
+ * Reduced motion: the text appears at once.
+ */
+interface UsaTypewriterElement extends UsaElement {
+    /** Phrases being typed. */
+    readonly phrases: string[];
+    start(): void;
+    stop(): void;
+    restart(): void;
+}
+declare function defineTypewriter(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-split-text>` — splits its text into words or characters and reveals
+ * 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`
+ * (`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`),
+ * `repeat`. The original text stays readable via `aria-label`.
+ * Event: `usa:complete`.
+ */
+interface UsaSplitTextElement extends UsaElement {
+    readonly units: HTMLElement[];
+    play(): void;
+    reset(): void;
+}
+declare function defineSplitText(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-scramble>` — "decodes" text out of random glyphs, left to right.
+ *
+ * Attributes: `text` (default: the element's text), `duration` (ms, 900),
+ * `chars` (glyph set), `trigger` (`view` | `hover` | `load` | `manual`,
+ * default `view`). Spaces and punctuation stay in place. Uses a monospace-
+ * friendly fixed width per glyph only if you style it so; the element sets
+ * nothing that causes reflow beyond its own text. Event: `usa:complete`.
+ * Reduced motion: shows the final text.
+ */
+interface UsaScrambleElement extends UsaElement {
+    play(): Promise<void>;
+}
+/** One frame of the scramble: the first `progress` share is resolved. */
+declare function scrambleFrame(text: string, progress: number, glyphs?: string, rnd?: () => number): string;
+declare function defineScramble(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-counter>` — counts up (or down) to a number when it scrolls into view.
+ *
+ * Attributes: `to` (target, required), `from` (0), `duration` (ms, 1600),
+ * `decimals` (0), `locale` (default: the document language), `prefix`,
+ * `suffix`, `grouping="false"` (no thousands separators), `start`
+ * (`view` | `load` | `manual`). Setting the `value` property animates from
+ * the current value — handy for live dashboards. Uses tabular digits so
+ * the width does not jump. Event: `usa:complete`. Reduced motion: jumps.
+ */
+interface UsaCounterElement extends UsaElement {
+    /** Current target; setting it animates to the new number. */
+    value: number;
+    /** Animate to `to` (default: the `to` attribute). */
+    play(to?: number): Promise<void>;
+    format(n: number): string;
+}
+/** easeOutExpo */
+declare const easeOutExpo: (t: number) => number;
+declare function defineCounter(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-shimmer-text>` — a light sweep across gradient-filled text (CSS
+ * only; the element just maps attributes to custom properties).
+ *
+ * Attributes: `duration` (ms, 2600), `color` (base text colour), `shine`
+ * (highlight colour), `angle` (deg, 110). Or style `--usa-shimmer-*`
+ * directly. Reduced motion: static gradient text.
+ */
+type UsaShimmerTextElement = UsaElement;
+declare function defineShimmerText(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-text-rotate>` — cycles through words in place ("Build *fast* /
+ * *small* / *typed* apps"). All words share one grid cell, so the width is
+ * that of the longest word and nothing around it reflows.
+ *
+ * Attributes: `words` (separated by `|`, default: the element's text split
+ * on `|`), `interval` (ms, 2200), `effect` (`slide` | `fade` | `flip` |
+ * `blur`, default `slide`), `paused`. Pauses while off-screen and on hover
+ * is not needed. Event: `usa:change` (`detail.index`, `detail.word`).
+ * Reduced motion: words still change, without movement (fade only).
+ */
+interface UsaTextRotateElement extends UsaElement {
+    readonly index: number;
+    next(): void;
+}
+declare function defineTextRotate(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * use-scroll-animate/components/text — text effects.
+ * `<usa-typewriter>`, `<usa-split-text>`, `<usa-scramble>`, `<usa-counter>`,
+ * `<usa-shimmer-text>`, `<usa-text-rotate>`.
+ */
+
+/** Register every component of this category under its default tag. */
+declare function defineTextComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-typewriter': UsaTypewriterElement;
+        'usa-split-text': UsaSplitTextElement;
+        'usa-scramble': UsaScrambleElement;
+        'usa-counter': UsaCounterElement;
+        'usa-shimmer-text': UsaShimmerTextElement;
+        'usa-text-rotate': UsaTextRotateElement;
+    }
+}
+
+export { configureComponents, defineCounter, defineScramble, defineShimmerText, defineSplitText, defineTextComponents, defineTextRotate, defineTypewriter, easeOutExpo, prefersReducedMotion, scrambleFrame };
+export type { ComponentsConfig, UsaCounterElement, UsaElement, UsaScrambleElement, UsaShimmerTextElement, UsaSplitTextElement, UsaTextRotateElement, UsaTypewriterElement };

package/dist/components/text.d.ts

@@ -0,0 +1,164 @@
+/**
+ * use-scroll-animate/components — shared base for the `<usa-*>` custom elements.
+ *
+ * Everything here is lazy: nothing touches `window`, `document`,
+ * `HTMLElement` or `matchMedia` at import time, so the components can be
+ * imported during SSR (Next, Nuxt, Astro…) and in Electron/Tauri preload
+ * scripts. Classes are created the first time a `define*()` function runs.
+ */
+interface ComponentsConfig {
+    /**
+     * Inject each component's CSS when it is defined (default `true`). Uses a
+     * constructable stylesheet (`document.adoptedStyleSheets`, which a strict
+     * `style-src` CSP does not block) and falls back to a `<style>` tag. Set
+     * to `false` when you load `use-scroll-animate/components.css` yourself.
+     */
+    injectStyles?: boolean;
+    /**
+     * `'user'` (default) follows `prefers-reduced-motion`; `'reduce'` always
+     * uses the reduced variants (e.g. a kiosk / battery-saver mode);
+     * `'no-preference'` ignores the OS setting (only for demos — respect your users).
+     */
+    reducedMotion?: 'user' | 'reduce' | 'no-preference';
+}
+/** Change global component settings (call before `define*()` for `injectStyles`). */
+declare function configureComponents(options: ComponentsConfig): void;
+/** `true` when animations should be reduced (OS setting or `configureComponents`). */
+declare function prefersReducedMotion(): boolean;
+/**
+ * Members shared by every `<usa-*>` element. Attribute helpers, a cleanup
+ * bag that is emptied on disconnect, and motion helpers that degrade to the
+ * final state without WAAPI or under reduced motion.
+ */
+interface UsaElement extends HTMLElement {
+    /** `true` while reduced motion applies to this element. */
+    readonly reduced: boolean;
+}
+
+/**
+ * `<usa-typewriter>` — types text character by character, optionally cycling
+ * through several phrases (typing, pausing, deleting).
+ *
+ * Attributes: `text` (default: the element's text), `words` (phrases
+ * separated by `|`, overrides `text`), `speed` (ms per character, 55),
+ * `delete-speed` (ms, 30), `pause` (ms before deleting, 1400), `delay`
+ * (ms, 0), `loop`, `cursor="false"` to hide the caret, `start`
+ * (`view` | `load` | `manual`, default `view`). The full text is exposed to
+ * assistive tech via `aria-label`. Event: `usa:complete` (one pass done).
+ * Reduced motion: the text appears at once.
+ */
+interface UsaTypewriterElement extends UsaElement {
+    /** Phrases being typed. */
+    readonly phrases: string[];
+    start(): void;
+    stop(): void;
+    restart(): void;
+}
+declare function defineTypewriter(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-split-text>` — splits its text into words or characters and reveals
+ * 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`
+ * (`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`),
+ * `repeat`. The original text stays readable via `aria-label`.
+ * Event: `usa:complete`.
+ */
+interface UsaSplitTextElement extends UsaElement {
+    readonly units: HTMLElement[];
+    play(): void;
+    reset(): void;
+}
+declare function defineSplitText(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-scramble>` — "decodes" text out of random glyphs, left to right.
+ *
+ * Attributes: `text` (default: the element's text), `duration` (ms, 900),
+ * `chars` (glyph set), `trigger` (`view` | `hover` | `load` | `manual`,
+ * default `view`). Spaces and punctuation stay in place. Uses a monospace-
+ * friendly fixed width per glyph only if you style it so; the element sets
+ * nothing that causes reflow beyond its own text. Event: `usa:complete`.
+ * Reduced motion: shows the final text.
+ */
+interface UsaScrambleElement extends UsaElement {
+    play(): Promise<void>;
+}
+/** One frame of the scramble: the first `progress` share is resolved. */
+declare function scrambleFrame(text: string, progress: number, glyphs?: string, rnd?: () => number): string;
+declare function defineScramble(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-counter>` — counts up (or down) to a number when it scrolls into view.
+ *
+ * Attributes: `to` (target, required), `from` (0), `duration` (ms, 1600),
+ * `decimals` (0), `locale` (default: the document language), `prefix`,
+ * `suffix`, `grouping="false"` (no thousands separators), `start`
+ * (`view` | `load` | `manual`). Setting the `value` property animates from
+ * the current value — handy for live dashboards. Uses tabular digits so
+ * the width does not jump. Event: `usa:complete`. Reduced motion: jumps.
+ */
+interface UsaCounterElement extends UsaElement {
+    /** Current target; setting it animates to the new number. */
+    value: number;
+    /** Animate to `to` (default: the `to` attribute). */
+    play(to?: number): Promise<void>;
+    format(n: number): string;
+}
+/** easeOutExpo */
+declare const easeOutExpo: (t: number) => number;
+declare function defineCounter(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-shimmer-text>` — a light sweep across gradient-filled text (CSS
+ * only; the element just maps attributes to custom properties).
+ *
+ * Attributes: `duration` (ms, 2600), `color` (base text colour), `shine`
+ * (highlight colour), `angle` (deg, 110). Or style `--usa-shimmer-*`
+ * directly. Reduced motion: static gradient text.
+ */
+type UsaShimmerTextElement = UsaElement;
+declare function defineShimmerText(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-text-rotate>` — cycles through words in place ("Build *fast* /
+ * *small* / *typed* apps"). All words share one grid cell, so the width is
+ * that of the longest word and nothing around it reflows.
+ *
+ * Attributes: `words` (separated by `|`, default: the element's text split
+ * on `|`), `interval` (ms, 2200), `effect` (`slide` | `fade` | `flip` |
+ * `blur`, default `slide`), `paused`. Pauses while off-screen and on hover
+ * is not needed. Event: `usa:change` (`detail.index`, `detail.word`).
+ * Reduced motion: words still change, without movement (fade only).
+ */
+interface UsaTextRotateElement extends UsaElement {
+    readonly index: number;
+    next(): void;
+}
+declare function defineTextRotate(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * use-scroll-animate/components/text — text effects.
+ * `<usa-typewriter>`, `<usa-split-text>`, `<usa-scramble>`, `<usa-counter>`,
+ * `<usa-shimmer-text>`, `<usa-text-rotate>`.
+ */
+
+/** Register every component of this category under its default tag. */
+declare function defineTextComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-typewriter': UsaTypewriterElement;
+        'usa-split-text': UsaSplitTextElement;
+        'usa-scramble': UsaScrambleElement;
+        'usa-counter': UsaCounterElement;
+        'usa-shimmer-text': UsaShimmerTextElement;
+        'usa-text-rotate': UsaTextRotateElement;
+    }
+}
+
+export { configureComponents, defineCounter, defineScramble, defineShimmerText, defineSplitText, defineTextComponents, defineTextRotate, defineTypewriter, easeOutExpo, prefersReducedMotion, scrambleFrame };
+export type { ComponentsConfig, UsaCounterElement, UsaElement, UsaScrambleElement, UsaShimmerTextElement, UsaSplitTextElement, UsaTextRotateElement, UsaTypewriterElement };