use-scroll-animate 2.6.0 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +3 -2
  3. package/README_ja.md +3 -2
  4. package/README_zh.md +3 -2
  5. package/dist/chunks/{base-5DFCAnvH.cjs → base-BR6fYLBA.cjs} +23 -2
  6. package/dist/chunks/base-BR6fYLBA.cjs.map +1 -0
  7. package/dist/chunks/{base-08OYzphB.js → base-C_w9ibbn.js} +21 -3
  8. package/dist/chunks/base-C_w9ibbn.js.map +1 -0
  9. package/dist/chunks/{spring-CpeFkxNd.js → spring-Dc8ZqDWE.js} +3 -3
  10. package/dist/chunks/spring-Dc8ZqDWE.js.map +1 -0
  11. package/dist/chunks/{spring-Bi4qY0pL.cjs → spring-DyHe1Hfa.cjs} +3 -3
  12. package/dist/chunks/spring-DyHe1Hfa.cjs.map +1 -0
  13. package/dist/chunks/variants-Bbatdq8d.cjs +39 -0
  14. package/dist/chunks/variants-Bbatdq8d.cjs.map +1 -0
  15. package/dist/chunks/variants-idgMVXhE.js +35 -0
  16. package/dist/chunks/variants-idgMVXhE.js.map +1 -0
  17. package/dist/components/background.cjs +277 -11
  18. package/dist/components/background.cjs.map +1 -1
  19. package/dist/components/background.css +2 -0
  20. package/dist/components/background.d.cts +71 -2
  21. package/dist/components/background.d.ts +71 -2
  22. package/dist/components/background.js +274 -13
  23. package/dist/components/background.js.map +1 -1
  24. package/dist/components/cards.cjs +2 -2
  25. package/dist/components/cards.d.cts +8 -0
  26. package/dist/components/cards.d.ts +8 -0
  27. package/dist/components/cards.js +3 -3
  28. package/dist/components/click.cjs +2 -2
  29. package/dist/components/click.d.cts +8 -0
  30. package/dist/components/click.d.ts +8 -0
  31. package/dist/components/click.js +3 -3
  32. package/dist/components/feedback.cjs +1 -1
  33. package/dist/components/feedback.d.cts +8 -0
  34. package/dist/components/feedback.d.ts +8 -0
  35. package/dist/components/feedback.js +2 -2
  36. package/dist/components/interaction.cjs +1 -1
  37. package/dist/components/interaction.d.cts +8 -0
  38. package/dist/components/interaction.d.ts +8 -0
  39. package/dist/components/interaction.js +2 -2
  40. package/dist/components/page.cjs +801 -0
  41. package/dist/components/page.cjs.map +1 -0
  42. package/dist/components/page.css +11 -0
  43. package/dist/components/page.d.cts +275 -0
  44. package/dist/components/page.d.ts +275 -0
  45. package/dist/components/page.js +776 -0
  46. package/dist/components/page.js.map +1 -0
  47. package/dist/components/physics.cjs +2 -2
  48. package/dist/components/physics.d.cts +8 -0
  49. package/dist/components/physics.d.ts +8 -0
  50. package/dist/components/physics.js +4 -4
  51. package/dist/components/reveal.cjs +1 -1
  52. package/dist/components/reveal.d.cts +8 -0
  53. package/dist/components/reveal.d.ts +8 -0
  54. package/dist/components/reveal.js +2 -2
  55. package/dist/components/text.cjs +180 -11
  56. package/dist/components/text.cjs.map +1 -1
  57. package/dist/components/text.css +1 -0
  58. package/dist/components/text.d.cts +62 -2
  59. package/dist/components/text.d.ts +62 -2
  60. package/dist/components/text.js +177 -13
  61. package/dist/components/text.js.map +1 -1
  62. package/dist/components/transitions.cjs +1 -1
  63. package/dist/components/transitions.d.cts +8 -0
  64. package/dist/components/transitions.d.ts +8 -0
  65. package/dist/components/transitions.js +2 -2
  66. package/dist/components/ui.cjs +18 -48
  67. package/dist/components/ui.cjs.map +1 -1
  68. package/dist/components/ui.d.cts +8 -0
  69. package/dist/components/ui.d.ts +8 -0
  70. package/dist/components/ui.js +6 -35
  71. package/dist/components/ui.js.map +1 -1
  72. package/dist/components.cjs +45 -8
  73. package/dist/components.cjs.map +1 -1
  74. package/dist/components.css +12 -0
  75. package/dist/components.d.cts +354 -4
  76. package/dist/components.d.ts +354 -4
  77. package/dist/components.js +16 -10
  78. package/dist/components.js.map +1 -1
  79. package/dist/components.umd.js +2 -2
  80. package/dist/components.umd.js.map +1 -1
  81. package/docs/components.md +34 -0
  82. package/docs/windows-apps.md +11 -0
  83. package/package.json +13 -2
  84. package/dist/chunks/base-08OYzphB.js.map +0 -1
  85. package/dist/chunks/base-5DFCAnvH.cjs.map +0 -1
  86. package/dist/chunks/spring-Bi4qY0pL.cjs.map +0 -1
  87. package/dist/chunks/spring-CpeFkxNd.js.map +0 -1
@@ -20,9 +20,20 @@ interface ComponentsConfig {
20
20
  * `'no-preference'` ignores the OS setting (only for demos — respect your users).
21
21
  */
22
22
  reducedMotion?: 'user' | 'reduce' | 'no-preference';
23
+ /**
24
+ * Global motion intensity (v2.7): `'off'` (same as reduced motion),
25
+ * `'low'` (shorter, calmer), `'normal'` (default) or `'high'`. Scales every
26
+ * component animation's duration and sets `--usa-motion` (0 / 0.6 / 1 /
27
+ * 1.25) on `<html>` for your own CSS. See `setMotionIntensity()`.
28
+ */
29
+ motionIntensity?: MotionIntensity;
23
30
  }
31
+ type MotionIntensity = 'off' | 'low' | 'normal' | 'high';
32
+ declare const MOTION_SCALE: Record<MotionIntensity, number>;
24
33
  /** Change global component settings (call before `define*()` for `injectStyles`). */
25
34
  declare function configureComponents(options: ComponentsConfig): void;
35
+ /** The current global motion intensity. */
36
+ declare function getMotionIntensity(): MotionIntensity;
26
37
  /** `true` when animations should be reduced (OS setting or `configureComponents`). */
27
38
  declare function prefersReducedMotion(): boolean;
28
39
  /**
@@ -234,6 +245,53 @@ interface UsaTextRotateElement extends UsaElement {
234
245
  }
235
246
  declare function defineTextRotate(tag?: string): CustomElementConstructor | undefined;
236
247
 
248
+ /**
249
+ * `<usa-wave-text>` — letters bob in a travelling wave.
250
+ * Attributes: `amplitude` (em, 0.25), `speed` (s per cycle, 1.6), `stagger`
251
+ * (s between letters, 0.06). Reduced motion: still text.
252
+ */
253
+ interface UsaWaveTextElement extends UsaElement {
254
+ }
255
+ declare function defineWaveText(tag?: string): CustomElementConstructor | undefined;
256
+ /**
257
+ * `<usa-glitch>` — an RGB-split glitch on its text (`trigger="always"`
258
+ * default, or `hover`). Attributes: `intensity` (px, 3), `trigger`.
259
+ * Reduced motion: no animation (plain text).
260
+ */
261
+ interface UsaGlitchElement extends UsaElement {
262
+ }
263
+ declare function defineGlitch(tag?: string): CustomElementConstructor | undefined;
264
+ /**
265
+ * `<usa-gradient-text>` — text filled with a flowing multi-colour gradient.
266
+ * Attributes: `colors` (comma list), `speed` (s, 6), `angle` (deg, 90).
267
+ * Reduced motion: a static gradient.
268
+ */
269
+ interface UsaGradientTextElement extends UsaElement {
270
+ }
271
+ declare function defineGradientText(tag?: string): CustomElementConstructor | undefined;
272
+ /**
273
+ * `<usa-handwriting>` — the text draws itself stroke by stroke (SVG text
274
+ * outline), then fills in, when it scrolls into view.
275
+ * Attributes: `text`, `duration` (ms, 2400), `stroke` (colour), `size` (px,
276
+ * 64), `font` (family; a script font looks best). Events: `usa:complete`.
277
+ * Reduced motion: the filled text appears at once.
278
+ */
279
+ interface UsaHandwritingElement extends UsaElement {
280
+ play(): void;
281
+ }
282
+ declare function defineHandwriting(tag?: string): CustomElementConstructor | undefined;
283
+ /**
284
+ * `<usa-scroll-highlight>` — reading highlight: words light up one by one
285
+ * as the paragraph scrolls through the viewport (`mode="words"`, default),
286
+ * or a highlighter marker sweeps behind the text on enter (`mode="marker"`).
287
+ * Attributes: `mode`, `color` (marker), `dim` (opacity of unread words,
288
+ * 0.2). Reduced motion: fully highlighted text.
289
+ */
290
+ interface UsaScrollHighlightElement extends UsaElement {
291
+ readonly progress: number;
292
+ }
293
+ declare function defineScrollHighlight(tag?: string): CustomElementConstructor | undefined;
294
+
237
295
  /**
238
296
  * use-scroll-animate/components/text — text effects.
239
297
  * `<usa-typewriter>`, `<usa-split-text>`, `<usa-scramble>`, `<usa-counter>`,
@@ -244,6 +302,11 @@ declare function defineTextRotate(tag?: string): CustomElementConstructor | unde
244
302
  declare function defineTextComponents(): void;
245
303
  declare global {
246
304
  interface HTMLElementTagNameMap {
305
+ 'usa-wave-text': UsaWaveTextElement;
306
+ 'usa-glitch': UsaGlitchElement;
307
+ 'usa-gradient-text': UsaGradientTextElement;
308
+ 'usa-handwriting': UsaHandwritingElement;
309
+ 'usa-scroll-highlight': UsaScrollHighlightElement;
247
310
  'usa-typewriter': UsaTypewriterElement;
248
311
  'usa-split-text': UsaSplitTextElement;
249
312
  'usa-scramble': UsaScrambleElement;
@@ -562,6 +625,63 @@ declare function defineMarquee(tag?: string): CustomElementConstructor | undefin
562
625
  type UsaAcrylicElement = UsaElement;
563
626
  declare function defineAcrylic(tag?: string): CustomElementConstructor | undefined;
564
627
 
628
+ /**
629
+ * `<usa-grid-glow>` — a line grid behind its content that lights up around
630
+ * the pointer. Attributes: `size` (cell px, 32), `color`, `radius` (px, 220).
631
+ * Reduced motion: the grid stays, a soft static glow in the centre.
632
+ */
633
+ interface UsaGridGlowElement extends UsaElement {
634
+ }
635
+ declare function defineGridGlow(tag?: string): CustomElementConstructor | undefined;
636
+ /**
637
+ * `<usa-blobs>` — soft, slowly morphing colour blobs (fluid gradient
638
+ * backdrop). Attributes: `colors` (comma list), `speed` (1), `blur` (px, 60).
639
+ * Reduced motion: still blobs.
640
+ */
641
+ interface UsaBlobsElement extends UsaElement {
642
+ }
643
+ declare function defineBlobs(tag?: string): CustomElementConstructor | undefined;
644
+ /**
645
+ * `<usa-water-ripple>` — interactive water ripples on a canvas over its
646
+ * content (pointer moves and taps disturb the surface). Low-resolution height
647
+ * map, paused off-screen. Attributes: `damping` (0.96), `strength` (1),
648
+ * `color` (highlight). Reduced motion: nothing is drawn.
649
+ */
650
+ interface UsaWaterRippleElement extends UsaElement {
651
+ drop(x: number, y: number, strength?: number): void;
652
+ }
653
+ declare function defineWaterRipple(tag?: string): CustomElementConstructor | undefined;
654
+ /**
655
+ * `<usa-dot-network>` — a grid of dots that swell and link up with lines
656
+ * around the pointer (a living network backdrop). Attributes: `gap` (px,
657
+ * 28), `color`, `radius` (px of influence, 140). Reduced motion: a static
658
+ * dot grid.
659
+ */
660
+ interface UsaDotNetworkElement extends UsaElement {
661
+ }
662
+ declare function defineDotNetwork(tag?: string): CustomElementConstructor | undefined;
663
+
664
+ interface FluentPresetOptions {
665
+ /** Root to apply to (default `document.documentElement`). */
666
+ root?: HTMLElement;
667
+ /** Reveal highlight on interactive elements (default `true`). */
668
+ reveal?: boolean;
669
+ /** Reveal targets (default buttons, links, `[data-fluent-reveal]`). */
670
+ selector?: string;
671
+ /** Mica-style tinted window background on `<body>` (default `true`). */
672
+ mica?: boolean;
673
+ }
674
+ /**
675
+ * Windows 11 **Fluent preset** (v2.8): applies the `fluent` variant
676
+ * (Segoe UI Variable, Windows accent, 8 px radii), a Mica-style tinted
677
+ * window background, Acrylic on `.usa-acrylic` / `[data-acrylic]`, and
678
+ * Reveal highlight (a light following the pointer on borders and
679
+ * backgrounds of interactive elements). Ideal for WebView2 / Electron /
680
+ * Tauri apps on Windows. Returns a function that removes it.
681
+ * Respects reduced motion / transparency (no Reveal tracking; solid materials).
682
+ */
683
+ declare function fluentPreset(options?: FluentPresetOptions): () => void;
684
+
565
685
  /**
566
686
  * use-scroll-animate/components/background — backgrounds & decoration.
567
687
  * `<usa-aurora>`, `<usa-particles>`, `<usa-grain>`, `<usa-marquee>`,
@@ -572,6 +692,10 @@ declare function defineAcrylic(tag?: string): CustomElementConstructor | undefin
572
692
  declare function defineBackgroundComponents(): void;
573
693
  declare global {
574
694
  interface HTMLElementTagNameMap {
695
+ 'usa-grid-glow': UsaGridGlowElement;
696
+ 'usa-blobs': UsaBlobsElement;
697
+ 'usa-water-ripple': UsaWaterRippleElement;
698
+ 'usa-dot-network': UsaDotNetworkElement;
575
699
  'usa-aurora': UsaAuroraElement;
576
700
  'usa-particles': UsaParticlesElement;
577
701
  'usa-grain': UsaGrainElement;
@@ -1424,18 +1548,244 @@ declare global {
1424
1548
  }
1425
1549
  }
1426
1550
 
1551
+ declare const CURSOR_MODES: readonly ["dot", "trail", "magnetic", "glow"];
1552
+ type CursorMode = (typeof CURSOR_MODES)[number];
1553
+ /**
1554
+ * `<usa-cursor mode="dot | trail | magnetic | glow">` — a custom cursor for
1555
+ * the page (place it once, e.g. at the end of `<body>`).
1556
+ * - `dot` — a ring that follows with spring lag around the real pointer;
1557
+ * - `trail` — a comet tail of dots;
1558
+ * - `magnetic` — the ring snaps onto and wraps hovered targets (`a`,
1559
+ * `button`, `[data-cursor]`);
1560
+ * - `glow` — a large soft light following the pointer (great on dark UIs).
1561
+ * Attributes: `mode`, `color`, `size` (px, 28), `hide-native` (hide the
1562
+ * system cursor), `targets` (selector, magnetic). Only for fine pointers
1563
+ * (mouse / pen); never on touch. Reduced motion: not rendered.
1564
+ */
1565
+ interface UsaCursorElement extends UsaElement {
1566
+ readonly active: boolean;
1567
+ }
1568
+ declare function defineCursor(tag?: string): CustomElementConstructor | undefined;
1569
+
1570
+ /**
1571
+ * `<usa-fullpage>` — full-screen sections (its element children) that snap
1572
+ * one at a time (CSS scroll snap), with keyboard paging (PageUp/PageDown,
1573
+ * arrows, Home/End), optional dot navigation and the current section in
1574
+ * `aria-current` + `usa:section`.
1575
+ * Attributes: `dots` (show the dot nav), `axis` (`y` default, `x`).
1576
+ * Methods: `go(i)`, `next()`, `prev()`. Reduced motion: snapping stays,
1577
+ * jumps are instant.
1578
+ */
1579
+ interface UsaFullpageElement extends UsaElement {
1580
+ readonly index: number;
1581
+ go(i: number): void;
1582
+ next(): void;
1583
+ prev(): void;
1584
+ }
1585
+ declare function defineFullpage(tag?: string): CustomElementConstructor | undefined;
1586
+
1587
+ /**
1588
+ * `<usa-loading-bar>` — a slim top loading bar for route changes and fetches
1589
+ * (NProgress-style): `start()` trickles towards 90 %, `done()` completes and
1590
+ * fades out, `set(0–1)` for real progress. `loadingBar` drives the first bar
1591
+ * on the page (created on demand). `role="progressbar"`, `aria-busy`.
1592
+ * Attributes: `color`, `height` (px, 3), `position` (`top` default, `bottom`).
1593
+ * Reduced motion: no trickle animation — the bar shows / hides.
1594
+ */
1595
+ interface UsaLoadingBarElement extends UsaElement {
1596
+ readonly progress: number;
1597
+ start(): void;
1598
+ set(p: number): void;
1599
+ done(): void;
1600
+ }
1601
+ declare function defineLoadingBar(tag?: string): CustomElementConstructor | undefined;
1602
+ /** Drive the page's `<usa-loading-bar>` (created on first use). */
1603
+ declare const loadingBar: {
1604
+ start: () => void;
1605
+ set: (p: number) => void;
1606
+ done: () => void;
1607
+ /** Run `task` with the bar shown; resolves with its result. */
1608
+ track<T>(task: Promise<T> | (() => Promise<T>)): Promise<T>;
1609
+ };
1610
+
1611
+ /**
1612
+ * `<usa-back-to-top>` — a floating button that appears after `offset` px
1613
+ * (300) of scrolling, shows page progress as a ring and springs the page
1614
+ * back to the top (then focuses `focus-target`, default `#main` / `body`).
1615
+ * Attributes: `offset`, `label` ("Back to top"), `focus-target`, `position`
1616
+ * (`bottom-right` default, `bottom-left`). Reduced motion: instant jump.
1617
+ */
1618
+ interface UsaBackToTopElement extends UsaElement {
1619
+ readonly visible: boolean;
1620
+ }
1621
+ declare function defineBackToTop(tag?: string): CustomElementConstructor | undefined;
1622
+
1623
+ declare const AMBIENT_EFFECTS: readonly ["particles", "snow", "stars", "noise", "gradient"];
1624
+ type AmbientEffect = (typeof AMBIENT_EFFECTS)[number];
1625
+ /**
1626
+ * `<usa-ambient effect="particles | snow | stars | noise | gradient">` — a
1627
+ * fixed, page-wide ambient layer behind (or, with `layer="front"`, over)
1628
+ * the content, never catching the pointer.
1629
+ * - `particles` — slow drifting dots; `snow` — falling flakes with sway;
1630
+ * `stars` — twinkling starfield (canvas, paused in hidden tabs, DPR ≤ 2);
1631
+ * - `noise` — animated film grain (CSS, SVG turbulence);
1632
+ * - `gradient` — a gradient whose hue shifts with the scroll position.
1633
+ * Attributes: `effect`, `density` (0.2–3, 1), `color`, `opacity` (0.6),
1634
+ * `layer` (`back` default, `front`), `speed` (1). Reduced motion: one
1635
+ * static frame (no falling, twinkling or grain flicker).
1636
+ */
1637
+ interface UsaAmbientElement extends UsaElement {
1638
+ }
1639
+ declare function defineAmbient(tag?: string): CustomElementConstructor | undefined;
1640
+
1641
+ /**
1642
+ * `<usa-splash>` — an app splash / launch screen: shows its content (logo,
1643
+ * spinner) over the page, then leaves with `exit` (`fade` default, `scale`,
1644
+ * `slide-up`, `circle`) once the page has loaded (or when you call
1645
+ * `done()`), but never sooner than `min` ms (600) — no flash.
1646
+ * Attributes: `min`, `exit`, `manual` (wait for `done()`), `label`.
1647
+ * Events: `usa:done`. The page underneath is `aria-busy` until then.
1648
+ * Reduced motion: fades.
1649
+ */
1650
+ interface UsaSplashElement extends UsaElement {
1651
+ done(): Promise<void>;
1652
+ }
1653
+ declare function defineSplash(tag?: string): CustomElementConstructor | undefined;
1654
+
1655
+ /**
1656
+ * `<usa-auto-skeleton loading>` — automatic skeletons: while `loading` is
1657
+ * set, every text block, image, button and input inside is drawn as a
1658
+ * shimmering placeholder of its own size — no separate skeleton markup.
1659
+ * Remove `loading` (or set `.loading = false`) and the content fades in.
1660
+ * `aria-busy` while loading. Opt elements out with `data-no-skeleton`.
1661
+ * Reduced motion: static placeholders, no shimmer or fade.
1662
+ */
1663
+ interface UsaAutoSkeletonElement extends UsaElement {
1664
+ loading: boolean;
1665
+ }
1666
+ declare function defineAutoSkeleton(tag?: string): CustomElementConstructor | undefined;
1667
+
1668
+ /**
1669
+ * Set the global motion intensity for every `<usa-*>` component:
1670
+ * `'off'` (like reduced motion), `'low'`, `'normal'` (default), `'high'`.
1671
+ * Sets `--usa-motion` and `data-usa-motion` on `<html>`; with `persist`
1672
+ * the choice is remembered (localStorage) and restored by `restoreMotionIntensity()`.
1673
+ */
1674
+ declare function setMotionIntensity(level: MotionIntensity, persist?: boolean): void;
1675
+ /** Re-apply a persisted intensity (call early on page load). Returns it. */
1676
+ declare function restoreMotionIntensity(): MotionIntensity;
1677
+ /**
1678
+ * `<usa-motion-switch>` — a segmented control letting users choose the
1679
+ * app's motion intensity (Off · Low · Normal · High), persisted.
1680
+ * `role="radiogroup"`; arrow keys move. Attributes: `labels` (comma list),
1681
+ * `label` ("Motion"). Events: `usa:change` (`{ level }`).
1682
+ */
1683
+ interface UsaMotionSwitchElement extends UsaElement {
1684
+ value: MotionIntensity;
1685
+ }
1686
+ declare function defineMotionSwitch(tag?: string): CustomElementConstructor | undefined;
1687
+
1688
+ /**
1689
+ * Page & app-wide transitions (v2.7), built on the View Transitions API
1690
+ * (Chromium: Chrome, Edge, Electron, WebView2) with graceful fallbacks.
1691
+ *
1692
+ * - `pageTransition(update, { effect })` — SPA route changes: `fade`,
1693
+ * `slide` (`slide-left` / `slide-right` / `slide-up`), `circle` (reveal
1694
+ * from `x`, `y`), `blinds`, `pixel` (stepped dissolve), `zoom`.
1695
+ * - `enableMpaTransitions(effect)` — the same effects for multi-page sites
1696
+ * (`@view-transition { navigation: auto }`); call it on every page.
1697
+ * - `themeTransition(apply, { x, y })` — a circle-reveal theme switch.
1698
+ *
1699
+ * Without View Transitions (Firefox, older Safari) or under reduced motion
1700
+ * the update runs immediately (`fade` falls back to a short cross-fade of
1701
+ * `fallback` when given).
1702
+ */
1703
+ declare const PAGE_EFFECTS: readonly ["fade", "slide", "slide-left", "slide-right", "slide-up", "circle", "blinds", "pixel", "zoom"];
1704
+ type PageEffect = (typeof PAGE_EFFECTS)[number];
1705
+ interface PageTransitionOptions {
1706
+ effect?: PageEffect;
1707
+ /** Circle origin in client px (default: viewport centre / last pointer). */
1708
+ x?: number;
1709
+ y?: number;
1710
+ /** Duration in ms (default 600). */
1711
+ duration?: number;
1712
+ /** Element to cross-fade when View Transitions are unavailable. */
1713
+ fallback?: Element | null;
1714
+ }
1715
+ /** `true` when `document.startViewTransition` exists. */
1716
+ declare const supportsViewTransitions: () => boolean;
1717
+ /** Run `update` (sync or async) as an animated page transition. Resolves when it is done. */
1718
+ declare function pageTransition(update: () => unknown, options?: PageTransitionOptions): Promise<void>;
1719
+ /** Opt a multi-page site into cross-document view transitions with `effect`. */
1720
+ declare function enableMpaTransitions(effect?: PageEffect, duration?: number): void;
1721
+ /**
1722
+ * Switch theme with a circle reveal from (`x`, `y`) (default: last pointer).
1723
+ * `apply` flips your theme (e.g. toggles a class / `data-theme`).
1724
+ */
1725
+ declare function themeTransition(apply: () => unknown, options?: Omit<PageTransitionOptions, 'effect'>): Promise<void>;
1726
+
1727
+ /**
1728
+ * `smoothScroll()` — inertial wheel smoothing for the page (or a scroll
1729
+ * container): wheel deltas are eased with a lerp each frame. Touch and
1730
+ * keyboard scrolling stay native. Returns a function that turns it off.
1731
+ * No-op under reduced motion, on touch-only devices and on the server.
1732
+ */
1733
+ interface SmoothScrollOptions {
1734
+ /** Scroll container (default: the page). */
1735
+ target?: HTMLElement | null;
1736
+ /** 0–1, lower = smoother / longer glide (default 0.12). */
1737
+ lerp?: number;
1738
+ /** Wheel multiplier (default 1). */
1739
+ wheelMultiplier?: number;
1740
+ }
1741
+ declare function smoothScroll(options?: SmoothScrollOptions): () => void;
1742
+ /**
1743
+ * Scroll to a y position, element or selector with spring timing (or
1744
+ * instantly under reduced motion). Resolves when done.
1745
+ */
1746
+ declare function scrollToTarget(to: number | Element | string, options?: {
1747
+ offset?: number;
1748
+ target?: HTMLElement | null;
1749
+ preset?: string;
1750
+ }): Promise<void>;
1751
+
1752
+ /**
1753
+ * use-scroll-animate/components/page — page & app-wide effects (v2.7).
1754
+ * Page transitions (`pageTransition()`, `enableMpaTransitions()`,
1755
+ * `themeTransition()`), `<usa-cursor>`, `smoothScroll()` / `scrollToTarget()`,
1756
+ * `<usa-fullpage>`, `<usa-loading-bar>` + `loadingBar`, `<usa-back-to-top>`,
1757
+ * `<usa-ambient>`, `<usa-splash>`, `<usa-auto-skeleton>` and the global motion
1758
+ * intensity (`setMotionIntensity()`, `<usa-motion-switch>`).
1759
+ */
1760
+
1761
+ /** Register every component of this category under its default tag. */
1762
+ declare function definePageComponents(): void;
1763
+ declare global {
1764
+ interface HTMLElementTagNameMap {
1765
+ 'usa-cursor': UsaCursorElement;
1766
+ 'usa-fullpage': UsaFullpageElement;
1767
+ 'usa-loading-bar': UsaLoadingBarElement;
1768
+ 'usa-back-to-top': UsaBackToTopElement;
1769
+ 'usa-ambient': UsaAmbientElement;
1770
+ 'usa-splash': UsaSplashElement;
1771
+ 'usa-auto-skeleton': UsaAutoSkeletonElement;
1772
+ 'usa-motion-switch': UsaMotionSwitchElement;
1773
+ }
1774
+ }
1775
+
1427
1776
  /** The component categories and their default tags. */
1428
1777
  declare const COMPONENT_CATEGORIES: {
1429
1778
  readonly reveal: readonly ["usa-reveal", "usa-stagger", "usa-scroll-progress", "usa-scrolly"];
1430
- readonly text: readonly ["usa-typewriter", "usa-split-text", "usa-scramble", "usa-counter", "usa-shimmer-text", "usa-text-rotate"];
1779
+ readonly text: readonly ["usa-typewriter", "usa-split-text", "usa-scramble", "usa-counter", "usa-shimmer-text", "usa-text-rotate", "usa-wave-text", "usa-glitch", "usa-gradient-text", "usa-handwriting", "usa-scroll-highlight"];
1431
1780
  readonly interaction: readonly ["usa-ripple", "usa-magnetic", "usa-tilt", "usa-spotlight", "usa-press", "usa-toggle"];
1432
1781
  readonly feedback: readonly ["usa-spinner", "usa-skeleton", "usa-progress", "usa-toaster", "usa-check"];
1433
- readonly background: readonly ["usa-aurora", "usa-particles", "usa-grain", "usa-marquee", "usa-acrylic"];
1782
+ readonly background: readonly ["usa-aurora", "usa-particles", "usa-grain", "usa-marquee", "usa-acrylic", "usa-grid-glow", "usa-blobs", "usa-water-ripple", "usa-dot-network"];
1434
1783
  readonly transitions: readonly ["usa-dialog", "usa-accordion", "usa-flip-list", "usa-view-switch"];
1435
1784
  readonly physics: readonly ["usa-spring", "usa-draggable", "usa-overscroll"];
1436
1785
  readonly cards: readonly ["usa-card", "usa-card-stack", "usa-sticky-stack", "usa-carousel-3d"];
1437
1786
  readonly click: readonly ["usa-click", "usa-button", "usa-icon-morph", "usa-like", "usa-hold", "usa-double-tap", "usa-checkbox"];
1438
1787
  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"];
1788
+ readonly page: readonly ["usa-cursor", "usa-fullpage", "usa-loading-bar", "usa-back-to-top", "usa-ambient", "usa-splash", "usa-auto-skeleton", "usa-motion-switch"];
1439
1789
  };
1440
1790
  type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
1441
1791
  /**
@@ -1444,5 +1794,5 @@ type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
1444
1794
  */
1445
1795
  declare function defineComponents(categories?: ComponentCategory[]): void;
1446
1796
 
1447
- export { BUTTON_DEFORMS, CARD_EFFECTS, CLICK_EFFECTS, COMPONENT_CATEGORIES, MORPH_ICONS, REVEAL_EFFECTS, SPINNER_VARIANTS, SPRING_EFFECTS, SPRING_PRESETS, VARIANTS, adoptVariants, burst, confetti, configureComponents, connectedAnimation, createSpring, defineAccordion, defineAcrylic, defineAurora, defineAvatarStack, defineBackgroundComponents, defineBadge, defineBottomSheet, defineButton, defineCard, defineCardComponents, defineCardStack, defineCarousel3d, defineCheck, defineCheckbox, defineClick, defineClickComponents, defineComponents, defineCounter, defineDialog, defineDoubleTap, defineDraggable, defineDrawer, defineFab, defineFeedbackComponents, defineFlipList, defineGrain, defineHold, defineIconMorph, defineInteractionComponents, defineLike, defineMagnetic, defineMarquee, defineNavbar, defineOverscroll, defineParticles, definePhysicsComponents, definePopover, definePress, defineProgress, definePullRefresh, defineRating, defineReveal, defineRevealComponents, defineRipple, defineScramble, defineScrollProgress, defineScrolly, defineShimmerText, defineSkeleton, defineSlider, defineSpinner, defineSplitText, defineSpotlight, defineSpring, defineStagger, defineStickyStack, defineTabs, defineTextComponents, defineTextRotate, defineTilt, defineToaster, defineToggle, defineTooltip, defineTransitionComponents, defineTypewriter, defineUiComponents, defineViewSwitch, easeOutExpo, flip, haptic, linearEasing, morphPath, prefersReducedMotion, projectInertia, readScrollProgress, resolveSpring, revealKeyframes, rubberBand, scrambleFrame, setVariant, shake, snapTo, spring, springEasing, springEffectKeyframes, springSamples, stepSpring, supportsLinearEasing, toast, viewTransition };
1448
- export type { BurstOptions, ButtonDeform, ButtonShape, ButtonState, CardEffect, ClickEffect, ComponentCategory, ComponentsConfig, ConfettiOptions, ConnectedOptions, DialogVariant, FlipOptions, Placement, RevealEffect, SpinnerVariant, SpringConfig, SpringEffect, SpringInput, SpringPreset, SpringValue, SpringValueOptions, ToastHandle, ToastOptions, ToastType, UsaAccordionElement, UsaAcrylicElement, UsaAuroraElement, UsaAvatarStackElement, UsaBadgeElement, UsaBottomSheetElement, UsaButtonElement, UsaCardElement, UsaCardStackElement, UsaCarousel3dElement, UsaCheckElement, UsaCheckboxElement, UsaClickElement, UsaCounterElement, UsaDialogElement, UsaDoubleTapElement, UsaDraggableElement, UsaDrawerElement, UsaElement, UsaFabElement, UsaFlipListElement, UsaGrainElement, UsaHoldElement, UsaIconMorphElement, UsaLikeElement, UsaMagneticElement, UsaMarqueeElement, UsaNavbarElement, UsaOverscrollElement, UsaParticlesElement, UsaPopoverElement, UsaPressElement, UsaProgressElement, UsaPullRefreshElement, UsaRatingElement, UsaRevealElement, UsaRippleElement, UsaScrambleElement, UsaScrollProgressElement, UsaScrollyElement, UsaShimmerTextElement, UsaSkeletonElement, UsaSliderElement, UsaSpinnerElement, UsaSplitTextElement, UsaSpotlightElement, UsaSpringElement, UsaStaggerElement, UsaStickyStackElement, UsaTabsElement, UsaTextRotateElement, UsaTiltElement, UsaToasterElement, UsaToggleElement, UsaTooltipElement, UsaTypewriterElement, UsaViewSwitchElement, Variant, ViewTransitionOptions };
1797
+ 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 };
1798
+ 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 };