use-scroll-animate 2.3.0 → 2.5.0

package/dist/components.d.cts

@@ -898,6 +898,320 @@ declare global {
     }
 }
 
+declare const CARD_EFFECTS: readonly ["flip", "holo", "glass", "border-glow", "conic-border", "lift", "spotlight", "sheen", "parallax-layers", "expand"];
+type CardEffect = (typeof CARD_EFFECTS)[number];
+/**
+ * `<usa-card>` — card effects, combinable: `effect="lift sheen"`.
+ *
+ * - `flip` — front/back (`[data-front]` / `[data-back]` children) flip on
+ *   hover or `trigger="click"`, `axis="y"` (default, horizontal flip) or `x`.
+ * - `holo` — holographic foil that shifts with the pointer.
+ * - `glass` — frosted glass surface (backdrop blur).
+ * - `border-glow` — a glow on the border that follows the pointer.
+ * - `conic-border` — a rotating conic-gradient border.
+ * - `lift` — rises with a deeper shadow and a slight pointer tilt.
+ * - `spotlight` — a soft light that follows the pointer.
+ * - `sheen` — a light sweep across the card on hover / focus.
+ * - `parallax-layers` — children with `data-depth="0.2…1"` move at different depths.
+ * - `expand` — click to grow into a full detail view (`[data-detail]`
+ *   content is shown), FLIP + spring; Esc, `[data-close]` or the backdrop closes.
+ *
+ * Attributes: `effect`, `axis`, `trigger`, `depth` (parallax px, 16),
+ * `color` (glow / spotlight colour), `flipped`, `expanded`, `disabled`.
+ * CSS variables: `--usa-card-x/-y` (pointer %, 0–100), `--usa-card-nx/-ny` (−1…1).
+ * Methods: `flip(force?)`, `expand()`, `collapse()`. Events: `usa:flip`,
+ * `usa:expand`, `usa:collapse`. Reduced motion: no tilt / parallax / sweep;
+ * flips and expansions cross-fade.
+ */
+interface UsaCardElement extends UsaElement {
+    readonly effects: string[];
+    flipped: boolean;
+    readonly expanded: boolean;
+    flip(force?: boolean): void;
+    expand(): Promise<void>;
+    collapse(): Promise<void>;
+}
+declare function defineCard(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-card-stack>` — a deck of cards (its element children). The top card
+ * can be swiped away left or right (pointer, touch or arrow keys); the rest
+ * fan out behind it and move up with a spring.
+ *
+ * Attributes: `threshold` (px to dismiss, 90), `visible` (cards fanned
+ * behind, 3), `offset` (px between cards, 10), `loop` (swiped cards go back
+ * to the bottom), `disabled`. Methods: `swipe(direction)`, `top`. Events:
+ * `usa:swipe` (`{ direction: 'left' | 'right', card }`), `usa:empty`.
+ * Reduced motion: cards are removed instantly, no rotation.
+ */
+interface UsaCardStackElement extends UsaElement {
+    readonly top: HTMLElement | null;
+    swipe(direction: 'left' | 'right'): Promise<void>;
+}
+declare function defineCardStack(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-sticky-stack>` — cards (element children) stick to the top while
+ * scrolling and the ones underneath scale down and dim as the next card
+ * slides over them, like a deck building up.
+ *
+ * Attributes: `top` (px from the viewport top, 80), `gap` (px each card
+ * peeks below the previous, 16), `scale` (how much a covered card shrinks,
+ * 0.06). Reduced motion: cards still stack (sticky) but do not scale.
+ */
+interface UsaStickyStackElement extends UsaElement {
+    update(): void;
+}
+declare function defineStickyStack(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-carousel-3d>` — its element children on a 3D ring. Rotate with the
+ * arrow keys, a drag/swipe, the wheel (shift) or `next()` / `prev()`; the
+ * front item is `aria-current`. Spring-driven rotation.
+ *
+ * Attributes: `radius` (px, auto from item width), `autoplay` (ms between
+ * steps, pauses on hover/focus), `perspective` (px, 1200), `index`.
+ * Events: `usa:change` (`{ index }`). Reduced motion: a flat, instant
+ * switch (only the current item is shown, others dimmed).
+ */
+interface UsaCarousel3dElement extends UsaElement {
+    index: number;
+    next(): void;
+    prev(): void;
+    goTo(i: number): void;
+}
+declare function defineCarousel3d(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * use-scroll-animate/components/cards — card effects (v2.4).
+ * `<usa-card effect="flip | holo | glass | border-glow | conic-border | lift |
+ * spotlight | sheen | parallax-layers | expand">` (combinable),
+ * `<usa-card-stack>` (swipeable deck), `<usa-sticky-stack>` (stacking on
+ * scroll) and `<usa-carousel-3d>`.
+ */
+
+/** Register every component of this category under its default tag. */
+declare function defineCardComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-card': UsaCardElement;
+        'usa-card-stack': UsaCardStackElement;
+        'usa-sticky-stack': UsaStickyStackElement;
+        'usa-carousel-3d': UsaCarousel3dElement;
+    }
+}
+
+declare const CLICK_EFFECTS: readonly ["ripple", "burst", "confetti", "squish", "press-spring", "shake"];
+type ClickEffect = (typeof CLICK_EFFECTS)[number];
+/**
+ * `<usa-click>` — click / tap effects on whatever it wraps (combinable:
+ * `effect="press-spring burst"`).
+ *
+ * - `ripple` — an ink wave from the pointer (enhanced: `color`, soft edge);
+ * - `burst` — particles radiating from the pointer (`shape`: circle, square, star, heart, emoji);
+ * - `confetti` — a confetti cannon from the click point;
+ * - `squish` — squash on press, stretch on release (spring);
+ * - `press-spring` — dips while pressed, springs back with overshoot;
+ * - `shake` — horizontal error shake; plays on `invalid` events from a form
+ *   inside, on `shake()`, or on click when `trigger="click"`.
+ *
+ * Attributes: `effect`, `color`, `shape`, `count`, `haptic` (vibrate ms,
+ * where supported), `disabled`. Keyboard (Space/Enter) triggers the effects
+ * from the centre. Reduced motion: no particles or movement; press dims.
+ */
+interface UsaClickElement extends UsaElement {
+    readonly effects: string[];
+    play(x?: number, y?: number): void;
+    shake(): void;
+}
+declare function defineClick(tag?: string): CustomElementConstructor | undefined;
+
+declare const BUTTON_DEFORMS: readonly ["squash", "wobble", "gooey", "dent"];
+type ButtonDeform = (typeof BUTTON_DEFORMS)[number];
+type ButtonShape = 'pill' | 'circle' | 'icon';
+type ButtonState = 'idle' | 'loading' | 'success' | 'error';
+/**
+ * `<usa-button>` — **button click deformation** (按钮点击形变) around a
+ * native `<button>` (or `<a>`) child — or the element itself becomes a button.
+ *
+ * `deform` (combinable, e.g. `deform="squash wobble"`):
+ * - `squash` — squash on press, stretch-and-settle on release (spring);
+ * - `wobble` — elastic border-radius wobble after a click;
+ * - `gooey` — liquid blob: droplets squeeze out from the press point and
+ *   merge back (SVG goo filter);
+ * - `dent` — the surface dents toward the pressed point (3D tilt + inner shade).
+ *
+ * `shape="pill | circle | icon"` morphs the outline with a spring (label =
+ * `[data-label]`, icon = `[data-icon]` children); `morphTo(shape)`.
+ *
+ * `morph="submit"` — click → `loading` (shrinks to a circle with a spinner,
+ * `aria-busy`), then `success` (check) or `error` (shake + cross), and back
+ * to `idle` after `reset` ms (1800). Drive it with `state="…"` / `.state`, or
+ * call `event.detail.done(ok)` from a `usa:submit` listener.
+ *
+ * Attributes: `deform`, `shape`, `morph`, `state`, `reset`, `haptic`,
+ * `disabled`. Events: `usa:submit`, `usa:state`. Reduced motion: no
+ * deformation; shape and state changes are instant; status still announced.
+ */
+interface UsaButtonElement extends UsaElement {
+    readonly target: HTMLElement;
+    shape: ButtonShape;
+    state: ButtonState;
+    morphTo(shape: ButtonShape): Promise<void>;
+}
+declare function defineButton(tag?: string): CustomElementConstructor | undefined;
+
+type Pt = [number, number];
+type Quad = [Pt, Pt, Pt, Pt];
+/**
+ * Morphable icons: every icon is three quads (four points each) on a 24×24
+ * grid, so any icon can morph into any other by interpolating points.
+ */
+declare const MORPH_ICONS: Record<string, [Quad, Quad, Quad]>;
+/** SVG path data for an icon, or for the interpolation `t` (0–1) between two. */
+declare function morphPath(from: string, to?: string, t?: number): string;
+/**
+ * `<usa-icon-morph>` — an icon that morphs between shapes with a spring:
+ * play ↔ pause, menu ↔ close, plus ↔ minus, check, arrow-right…
+ *
+ * Attributes: `icons` (comma list, cycled; default `play,pause`), `index`
+ * (current, 0), `size` (px, 24), `toggle` (makes it a button that cycles
+ * on click / Enter / Space), `labels` (comma list of accessible names per
+ * icon, e.g. `Play,Pause`), `preset` (spring, `wobbly`). Methods:
+ * `next()`, `show(nameOrIndex)`. Events: `usa:change` (`{ index, icon }`).
+ * Inside a `<usa-button>` or `<button>` it is decorative. Reduced motion:
+ * the icon switches instantly.
+ */
+interface UsaIconMorphElement extends UsaElement {
+    index: number;
+    readonly icon: string;
+    next(): void;
+    show(icon: string | number): void;
+}
+declare function defineIconMorph(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-like>` — a like / favourite toggle: the heart pops with a spring and
+ * bursts into particles when liked. `role="button"` + `aria-pressed`.
+ *
+ * Attributes: `liked`, `count` (shown next to the heart, updated ±1),
+ * `label` (accessible name, default "Like"), `color`, `size` (px, 24),
+ * `haptic`, `disabled`. Events: `change`, `usa:change` (`{ liked, count }`).
+ * Reduced motion: colour change only.
+ */
+interface UsaLikeElement extends UsaElement {
+    liked: boolean;
+    count: number | null;
+    toggle(force?: boolean): void;
+}
+declare function defineLike(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-hold>` — hold-to-confirm: press and hold (pointer, Space or Enter)
+ * while a progress ring fills; releasing early rewinds it. Good for
+ * destructive actions.
+ *
+ * Attributes: `duration` (ms, 1200), `label` (accessible name), `color`,
+ * `disabled`. CSS variable `--usa-hold` (0–1). Events: `usa:progress`,
+ * `usa:confirm`, `usa:cancel`. Reduced motion: same timing, the ring fills
+ * without the scale pulse.
+ */
+interface UsaHoldElement extends UsaElement {
+    readonly progress: number;
+    cancel(): void;
+}
+declare function defineHold(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-double-tap>` — detects a double tap / double click on its content
+ * (photos, posts) and pops a heart (or `icon`) at the tap point.
+ *
+ * Attributes: `icon` (text / emoji, default ♥), `color`, `delay` (max ms
+ * between taps, 300), `haptic`, `disabled`. Events: `usa:double-tap`
+ * (`{ x, y }`, element-relative). Keyboard users: press `L` while focused.
+ * Reduced motion: the icon fades in and out without scaling or particles.
+ */
+interface UsaDoubleTapElement extends UsaElement {
+    pop(x?: number, y?: number): void;
+}
+declare function defineDoubleTap(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * `<usa-checkbox>` — an animated, form-associated checkbox: the box springs
+ * and the check mark draws itself. `role="checkbox"` + `aria-checked`
+ * (`mixed` with `indeterminate`).
+ *
+ * Attributes: `checked`, `indeterminate`, `disabled`, `name`, `value`
+ * (`on`), `label`, `shape` (`square` default, `circle`). Events: `change`,
+ * `usa:change` (`{ checked }`). Reduced motion: no spring or drawing.
+ */
+interface UsaCheckboxElement extends UsaElement {
+    checked: boolean;
+    indeterminate: boolean;
+    toggle(force?: boolean): void;
+}
+declare function defineCheckbox(tag?: string): CustomElementConstructor | undefined;
+
+interface BurstOptions {
+    /** Number of particles (default 12). */
+    count?: number;
+    /** Colours to pick from (default: accent palette). */
+    colors?: string[];
+    /** Travel distance in px (default 48). */
+    distance?: number;
+    /** Particle size in px (default 6). */
+    size?: number;
+    /** `circle` (default), `square`, `star`, `heart` or any text / emoji. */
+    shape?: 'circle' | 'square' | 'star' | 'heart' | string;
+    /** Duration in ms (default 600). */
+    duration?: number;
+}
+/** Particles radiating from client point (x, y). Returns the number spawned. */
+declare function burst(x: number, y: number, options?: BurstOptions): number;
+interface ConfettiOptions {
+    /** Origin in client px (default: centre-bottom third of the viewport). */
+    x?: number;
+    y?: number;
+    /** Pieces (default 80). */
+    count?: number;
+    /** Spread angle in degrees (default 70). */
+    spread?: number;
+    /** Launch speed multiplier (default 1). */
+    velocity?: number;
+    colors?: string[];
+    /** Duration in ms (default 1600). */
+    duration?: number;
+}
+/** A confetti cannon (paper pieces with gravity, drift and spin). */
+declare function confetti(options?: ConfettiOptions): number;
+/** Horizontal error shake (`intensity` px, default 8). Reduced motion: a red outline flash. */
+declare function shake(el: Element, intensity?: number, duration?: number): Animation | null;
+/** `navigator.vibrate()` where supported (Android Chrome, some WebViews). Returns whether it ran. */
+declare function haptic(pattern?: number | number[]): boolean;
+
+/**
+ * use-scroll-animate/components/click — click & tap effects (v2.5).
+ * `<usa-click>` (ripple, burst, confetti, squish, press-spring, shake),
+ * `<usa-button>` (button click deformation: squash, wobble, gooey, dent;
+ * shape morph; submit → loading → success), `<usa-icon-morph>`,
+ * `<usa-like>`, `<usa-hold>`, `<usa-double-tap>`, `<usa-checkbox>`, plus
+ * `burst()`, `confetti()`, `shake()` and `haptic()`.
+ */
+
+/** Register every component of this category under its default tag. */
+declare function defineClickComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-click': UsaClickElement;
+        'usa-button': UsaButtonElement;
+        'usa-icon-morph': UsaIconMorphElement;
+        'usa-like': UsaLikeElement;
+        'usa-hold': UsaHoldElement;
+        'usa-double-tap': UsaDoubleTapElement;
+        'usa-checkbox': UsaCheckboxElement;
+    }
+}
+
 /** The component categories and their default tags. */
 declare const COMPONENT_CATEGORIES: {
     readonly reveal: readonly ["usa-reveal", "usa-stagger", "usa-scroll-progress", "usa-scrolly"];
@@ -907,6 +1221,8 @@ declare const COMPONENT_CATEGORIES: {
     readonly background: readonly ["usa-aurora", "usa-particles", "usa-grain", "usa-marquee", "usa-acrylic"];
     readonly transitions: readonly ["usa-dialog", "usa-accordion", "usa-flip-list", "usa-view-switch"];
     readonly physics: readonly ["usa-spring", "usa-draggable", "usa-overscroll"];
+    readonly cards: readonly ["usa-card", "usa-card-stack", "usa-sticky-stack", "usa-carousel-3d"];
+    readonly click: readonly ["usa-click", "usa-button", "usa-icon-morph", "usa-like", "usa-hold", "usa-double-tap", "usa-checkbox"];
 };
 type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
 /**
@@ -915,5 +1231,5 @@ type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
  */
 declare function defineComponents(categories?: ComponentCategory[]): void;
 
-export { COMPONENT_CATEGORIES, REVEAL_EFFECTS, SPINNER_VARIANTS, SPRING_EFFECTS, SPRING_PRESETS, configureComponents, connectedAnimation, createSpring, defineAccordion, defineAcrylic, defineAurora, defineBackgroundComponents, defineCheck, defineComponents, defineCounter, defineDialog, defineDraggable, defineFeedbackComponents, defineFlipList, defineGrain, defineInteractionComponents, defineMagnetic, defineMarquee, defineOverscroll, defineParticles, definePhysicsComponents, definePress, defineProgress, defineReveal, defineRevealComponents, defineRipple, defineScramble, defineScrollProgress, defineScrolly, defineShimmerText, defineSkeleton, defineSpinner, defineSplitText, defineSpotlight, defineSpring, defineStagger, defineTextComponents, defineTextRotate, defineTilt, defineToaster, defineToggle, defineTransitionComponents, defineTypewriter, defineViewSwitch, easeOutExpo, flip, linearEasing, prefersReducedMotion, projectInertia, readScrollProgress, resolveSpring, revealKeyframes, rubberBand, scrambleFrame, snapTo, spring, springEasing, springEffectKeyframes, springSamples, stepSpring, supportsLinearEasing, toast, viewTransition };
-export type { ComponentCategory, ComponentsConfig, ConnectedOptions, DialogVariant, FlipOptions, RevealEffect, SpinnerVariant, SpringConfig, SpringEffect, SpringInput, SpringPreset, SpringValue, SpringValueOptions, ToastHandle, ToastOptions, ToastType, UsaAccordionElement, UsaAcrylicElement, UsaAuroraElement, UsaCheckElement, UsaCounterElement, UsaDialogElement, UsaDraggableElement, UsaElement, UsaFlipListElement, UsaGrainElement, UsaMagneticElement, UsaMarqueeElement, UsaOverscrollElement, UsaParticlesElement, UsaPressElement, UsaProgressElement, UsaRevealElement, UsaRippleElement, UsaScrambleElement, UsaScrollProgressElement, UsaScrollyElement, UsaShimmerTextElement, UsaSkeletonElement, UsaSpinnerElement, UsaSplitTextElement, UsaSpotlightElement, UsaSpringElement, UsaStaggerElement, UsaTextRotateElement, UsaTiltElement, UsaToasterElement, UsaToggleElement, UsaTypewriterElement, UsaViewSwitchElement, ViewTransitionOptions };
+export { BUTTON_DEFORMS, CARD_EFFECTS, CLICK_EFFECTS, COMPONENT_CATEGORIES, MORPH_ICONS, REVEAL_EFFECTS, SPINNER_VARIANTS, SPRING_EFFECTS, SPRING_PRESETS, burst, confetti, configureComponents, connectedAnimation, createSpring, defineAccordion, defineAcrylic, defineAurora, defineBackgroundComponents, defineButton, defineCard, defineCardComponents, defineCardStack, defineCarousel3d, defineCheck, defineCheckbox, defineClick, defineClickComponents, defineComponents, defineCounter, defineDialog, defineDoubleTap, defineDraggable, defineFeedbackComponents, defineFlipList, defineGrain, defineHold, defineIconMorph, defineInteractionComponents, defineLike, defineMagnetic, defineMarquee, defineOverscroll, defineParticles, definePhysicsComponents, definePress, defineProgress, defineReveal, defineRevealComponents, defineRipple, defineScramble, defineScrollProgress, defineScrolly, defineShimmerText, defineSkeleton, defineSpinner, defineSplitText, defineSpotlight, defineSpring, defineStagger, defineStickyStack, defineTextComponents, defineTextRotate, defineTilt, defineToaster, defineToggle, defineTransitionComponents, defineTypewriter, defineViewSwitch, easeOutExpo, flip, haptic, linearEasing, morphPath, prefersReducedMotion, projectInertia, readScrollProgress, resolveSpring, revealKeyframes, rubberBand, scrambleFrame, shake, snapTo, spring, springEasing, springEffectKeyframes, springSamples, stepSpring, supportsLinearEasing, toast, viewTransition };
+export type { BurstOptions, ButtonDeform, ButtonShape, ButtonState, CardEffect, ClickEffect, ComponentCategory, ComponentsConfig, ConfettiOptions, ConnectedOptions, DialogVariant, FlipOptions, RevealEffect, SpinnerVariant, SpringConfig, SpringEffect, SpringInput, SpringPreset, SpringValue, SpringValueOptions, ToastHandle, ToastOptions, ToastType, UsaAccordionElement, UsaAcrylicElement, UsaAuroraElement, UsaButtonElement, UsaCardElement, UsaCardStackElement, UsaCarousel3dElement, UsaCheckElement, UsaCheckboxElement, UsaClickElement, UsaCounterElement, UsaDialogElement, UsaDoubleTapElement, UsaDraggableElement, UsaElement, UsaFlipListElement, UsaGrainElement, UsaHoldElement, UsaIconMorphElement, UsaLikeElement, UsaMagneticElement, UsaMarqueeElement, UsaOverscrollElement, UsaParticlesElement, UsaPressElement, UsaProgressElement, UsaRevealElement, UsaRippleElement, UsaScrambleElement, UsaScrollProgressElement, UsaScrollyElement, UsaShimmerTextElement, UsaSkeletonElement, UsaSpinnerElement, UsaSplitTextElement, UsaSpotlightElement, UsaSpringElement, UsaStaggerElement, UsaStickyStackElement, UsaTextRotateElement, UsaTiltElement, UsaToasterElement, UsaToggleElement, UsaTypewriterElement, UsaViewSwitchElement, ViewTransitionOptions };