use-scroll-animate 2.1.0 → 2.3.0

package/dist/components/interaction.d.cts

@@ -0,0 +1,142 @@
+/**
+ * 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-ripple>` — an ink ripple from the pointer (or the centre, for
+ * keyboard presses) on whatever it wraps: buttons, list items, cards.
+ *
+ * Attributes: `color` (default `currentColor`), `opacity` (0.22),
+ * `duration` (ms, 550), `centered`, `disabled`. Clips its content to its
+ * own border radius. Reduced motion: a brief highlight instead of the wave.
+ */
+interface UsaRippleElement extends UsaElement {
+    /** Spawn a ripple at client coordinates (default: centre). */
+    ripple(x?: number, y?: number): void;
+}
+declare function defineRipple(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-magnetic>` — its content leans toward the pointer when the pointer
+ * comes near, and springs back when it leaves (great for CTAs and icons).
+ *
+ * Attributes: `strength` (0–1 share of the pointer offset, 0.35), `radius`
+ * (px of attraction beyond the element's edge, 60), `disabled`. Only on
+ * devices with a fine pointer that hovers; off under reduced motion.
+ * Writes one `transform` per frame through `--usa-mx` / `--usa-my`.
+ */
+type UsaMagneticElement = UsaElement;
+declare function defineMagnetic(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-tilt>` — a 3D card that tilts toward the pointer, with an optional
+ * glare highlight that follows it.
+ *
+ * Attributes: `max` (deg, 10), `scale` (1.03 while hovered), `perspective`
+ * (px, 900), `glare` (add the light reflection), `reverse` (tilt away),
+ * `disabled`. Off under reduced motion. Exposes `--usa-tilt-x` /
+ * `--usa-tilt-y` (−1…1) for parallax layers inside the card.
+ */
+type UsaTiltElement = UsaElement;
+declare function defineTilt(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-spotlight>` — the Windows Fluent "Reveal highlight": a soft light
+ * follows the pointer across a group of items, lighting up their borders
+ * (even of neighbours) and the background of the hovered one. Put buttons,
+ * tiles or menu items inside; each direct child is an item (or mark items
+ * with `data-spotlight` to pick them yourself).
+ *
+ * Attributes: `size` (px, radius of the light, 160), `color` (default a
+ * translucent white), `border` (px width of the lit border, 1),
+ * `no-fill` (only light the borders). Not a motion effect, so it stays on
+ * under reduced motion; off on touch-only devices.
+ */
+type UsaSpotlightElement = UsaElement;
+declare function defineSpotlight(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-press>` — tactile press feedback: content dips while pressed and
+ * springs back on release (the Fluent "pointer down" scale), or bounces once
+ * on click with `bounce`.
+ *
+ * Attributes: `scale` (pressed scale, 0.95), `bounce` (overshoot on
+ * release), `disabled`. Works with mouse, touch, pen and Space/Enter.
+ * Reduced motion: a subtle dim instead of scaling.
+ */
+interface UsaPressElement extends UsaElement {
+    readonly pressed: boolean;
+}
+declare function definePress(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-toggle>` — an accessible switch whose knob stretches while pressed
+ * and glides across (the Windows 11 / iOS toggle). `role="switch"`,
+ * keyboard (Space / Enter), and form-associated where `ElementInternals`
+ * exists (submits `value`, default `"on"`, under `name` when checked).
+ *
+ * Attributes: `checked`, `disabled`, `name`, `value`, `label`
+ * (accessible name if there is no `aria-label` / `<label>`). Events:
+ * `change` and `usa:change` (`detail.checked`). Reduced motion: no glide.
+ */
+interface UsaToggleElement extends UsaElement {
+    checked: boolean;
+    disabled: boolean;
+    toggle(force?: boolean): void;
+}
+declare function defineToggle(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * use-scroll-animate/components/interaction — micro-interactions.
+ * `<usa-ripple>`, `<usa-magnetic>`, `<usa-tilt>`, `<usa-spotlight>`,
+ * `<usa-press>`, `<usa-toggle>`.
+ */
+
+/** Register every component of this category under its default tag. */
+declare function defineInteractionComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-ripple': UsaRippleElement;
+        'usa-magnetic': UsaMagneticElement;
+        'usa-tilt': UsaTiltElement;
+        'usa-spotlight': UsaSpotlightElement;
+        'usa-press': UsaPressElement;
+        'usa-toggle': UsaToggleElement;
+    }
+}
+
+export { configureComponents, defineInteractionComponents, defineMagnetic, definePress, defineRipple, defineSpotlight, defineTilt, defineToggle, prefersReducedMotion };
+export type { ComponentsConfig, UsaElement, UsaMagneticElement, UsaPressElement, UsaRippleElement, UsaSpotlightElement, UsaTiltElement, UsaToggleElement };

package/dist/components/interaction.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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-ripple>` — an ink ripple from the pointer (or the centre, for
+ * keyboard presses) on whatever it wraps: buttons, list items, cards.
+ *
+ * Attributes: `color` (default `currentColor`), `opacity` (0.22),
+ * `duration` (ms, 550), `centered`, `disabled`. Clips its content to its
+ * own border radius. Reduced motion: a brief highlight instead of the wave.
+ */
+interface UsaRippleElement extends UsaElement {
+    /** Spawn a ripple at client coordinates (default: centre). */
+    ripple(x?: number, y?: number): void;
+}
+declare function defineRipple(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-magnetic>` — its content leans toward the pointer when the pointer
+ * comes near, and springs back when it leaves (great for CTAs and icons).
+ *
+ * Attributes: `strength` (0–1 share of the pointer offset, 0.35), `radius`
+ * (px of attraction beyond the element's edge, 60), `disabled`. Only on
+ * devices with a fine pointer that hovers; off under reduced motion.
+ * Writes one `transform` per frame through `--usa-mx` / `--usa-my`.
+ */
+type UsaMagneticElement = UsaElement;
+declare function defineMagnetic(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-tilt>` — a 3D card that tilts toward the pointer, with an optional
+ * glare highlight that follows it.
+ *
+ * Attributes: `max` (deg, 10), `scale` (1.03 while hovered), `perspective`
+ * (px, 900), `glare` (add the light reflection), `reverse` (tilt away),
+ * `disabled`. Off under reduced motion. Exposes `--usa-tilt-x` /
+ * `--usa-tilt-y` (−1…1) for parallax layers inside the card.
+ */
+type UsaTiltElement = UsaElement;
+declare function defineTilt(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-spotlight>` — the Windows Fluent "Reveal highlight": a soft light
+ * follows the pointer across a group of items, lighting up their borders
+ * (even of neighbours) and the background of the hovered one. Put buttons,
+ * tiles or menu items inside; each direct child is an item (or mark items
+ * with `data-spotlight` to pick them yourself).
+ *
+ * Attributes: `size` (px, radius of the light, 160), `color` (default a
+ * translucent white), `border` (px width of the lit border, 1),
+ * `no-fill` (only light the borders). Not a motion effect, so it stays on
+ * under reduced motion; off on touch-only devices.
+ */
+type UsaSpotlightElement = UsaElement;
+declare function defineSpotlight(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-press>` — tactile press feedback: content dips while pressed and
+ * springs back on release (the Fluent "pointer down" scale), or bounces once
+ * on click with `bounce`.
+ *
+ * Attributes: `scale` (pressed scale, 0.95), `bounce` (overshoot on
+ * release), `disabled`. Works with mouse, touch, pen and Space/Enter.
+ * Reduced motion: a subtle dim instead of scaling.
+ */
+interface UsaPressElement extends UsaElement {
+    readonly pressed: boolean;
+}
+declare function definePress(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-toggle>` — an accessible switch whose knob stretches while pressed
+ * and glides across (the Windows 11 / iOS toggle). `role="switch"`,
+ * keyboard (Space / Enter), and form-associated where `ElementInternals`
+ * exists (submits `value`, default `"on"`, under `name` when checked).
+ *
+ * Attributes: `checked`, `disabled`, `name`, `value`, `label`
+ * (accessible name if there is no `aria-label` / `<label>`). Events:
+ * `change` and `usa:change` (`detail.checked`). Reduced motion: no glide.
+ */
+interface UsaToggleElement extends UsaElement {
+    checked: boolean;
+    disabled: boolean;
+    toggle(force?: boolean): void;
+}
+declare function defineToggle(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * use-scroll-animate/components/interaction — micro-interactions.
+ * `<usa-ripple>`, `<usa-magnetic>`, `<usa-tilt>`, `<usa-spotlight>`,
+ * `<usa-press>`, `<usa-toggle>`.
+ */
+
+/** Register every component of this category under its default tag. */
+declare function defineInteractionComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-ripple': UsaRippleElement;
+        'usa-magnetic': UsaMagneticElement;
+        'usa-tilt': UsaTiltElement;
+        'usa-spotlight': UsaSpotlightElement;
+        'usa-press': UsaPressElement;
+        'usa-toggle': UsaToggleElement;
+    }
+}
+
+export { configureComponents, defineInteractionComponents, defineMagnetic, definePress, defineRipple, defineSpotlight, defineTilt, defineToggle, prefersReducedMotion };
+export type { ComponentsConfig, UsaElement, UsaMagneticElement, UsaPressElement, UsaRippleElement, UsaSpotlightElement, UsaTiltElement, UsaToggleElement };