use-scroll-animate 2.5.0 → 2.7.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 (79) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/README.md +2 -0
  3. package/README_ja.md +2 -0
  4. package/README_zh.md +2 -0
  5. package/dist/chunks/{base-CJ7XfidP.cjs → base-BR6fYLBA.cjs} +25 -2
  6. package/dist/chunks/base-BR6fYLBA.cjs.map +1 -0
  7. package/dist/chunks/{base-CuvCgqLy.js → base-D6zLiNGH.js} +21 -3
  8. package/dist/chunks/base-D6zLiNGH.js.map +1 -0
  9. package/dist/chunks/{spring-BKUU7-Xm.js → spring-C2Megtcf.js} +3 -3
  10. package/dist/chunks/spring-C2Megtcf.js.map +1 -0
  11. package/dist/chunks/{spring-CGO9Jd9b.cjs → spring-DyHe1Hfa.cjs} +3 -3
  12. package/dist/chunks/spring-DyHe1Hfa.cjs.map +1 -0
  13. package/dist/components/background.cjs +1 -1
  14. package/dist/components/background.d.cts +8 -0
  15. package/dist/components/background.d.ts +8 -0
  16. package/dist/components/background.js +2 -2
  17. package/dist/components/cards.cjs +2 -2
  18. package/dist/components/cards.d.cts +8 -0
  19. package/dist/components/cards.d.ts +8 -0
  20. package/dist/components/cards.js +3 -3
  21. package/dist/components/click.cjs +2 -2
  22. package/dist/components/click.d.cts +8 -0
  23. package/dist/components/click.d.ts +8 -0
  24. package/dist/components/click.js +3 -3
  25. package/dist/components/feedback.cjs +2 -2
  26. package/dist/components/feedback.css +1 -1
  27. package/dist/components/feedback.d.cts +8 -0
  28. package/dist/components/feedback.d.ts +8 -0
  29. package/dist/components/feedback.js +3 -3
  30. package/dist/components/interaction.cjs +2 -2
  31. package/dist/components/interaction.css +1 -1
  32. package/dist/components/interaction.d.cts +8 -0
  33. package/dist/components/interaction.d.ts +8 -0
  34. package/dist/components/interaction.js +3 -3
  35. package/dist/components/page.cjs +801 -0
  36. package/dist/components/page.cjs.map +1 -0
  37. package/dist/components/page.css +11 -0
  38. package/dist/components/page.d.cts +275 -0
  39. package/dist/components/page.d.ts +275 -0
  40. package/dist/components/page.js +776 -0
  41. package/dist/components/page.js.map +1 -0
  42. package/dist/components/physics.cjs +2 -2
  43. package/dist/components/physics.d.cts +8 -0
  44. package/dist/components/physics.d.ts +8 -0
  45. package/dist/components/physics.js +4 -4
  46. package/dist/components/reveal.cjs +1 -1
  47. package/dist/components/reveal.d.cts +8 -0
  48. package/dist/components/reveal.d.ts +8 -0
  49. package/dist/components/reveal.js +2 -2
  50. package/dist/components/text.cjs +1 -1
  51. package/dist/components/text.d.cts +8 -0
  52. package/dist/components/text.d.ts +8 -0
  53. package/dist/components/text.js +2 -2
  54. package/dist/components/transitions.cjs +1 -1
  55. package/dist/components/transitions.d.cts +8 -0
  56. package/dist/components/transitions.d.ts +8 -0
  57. package/dist/components/transitions.js +2 -2
  58. package/dist/components/ui.cjs +1082 -0
  59. package/dist/components/ui.cjs.map +1 -0
  60. package/dist/components/ui.css +14 -0
  61. package/dist/components/ui.d.cts +259 -0
  62. package/dist/components/ui.d.ts +259 -0
  63. package/dist/components/ui.js +1064 -0
  64. package/dist/components/ui.js.map +1 -0
  65. package/dist/components.cjs +51 -4
  66. package/dist/components.cjs.map +1 -1
  67. package/dist/components.css +23 -2
  68. package/dist/components.d.cts +452 -2
  69. package/dist/components.d.ts +452 -2
  70. package/dist/components.js +14 -3
  71. package/dist/components.js.map +1 -1
  72. package/dist/components.umd.js +2 -2
  73. package/dist/components.umd.js.map +1 -1
  74. package/docs/components.md +37 -0
  75. package/package.json +24 -2
  76. package/dist/chunks/base-CJ7XfidP.cjs.map +0 -1
  77. package/dist/chunks/base-CuvCgqLy.js.map +0 -1
  78. package/dist/chunks/spring-BKUU7-Xm.js.map +0 -1
  79. package/dist/chunks/spring-CGO9Jd9b.cjs.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
  /**
@@ -1212,6 +1223,443 @@ declare global {
1212
1223
  }
1213
1224
  }
1214
1225
 
1226
+ /**
1227
+ * `<usa-tabs>` — accessible tabs with a sliding (spring) indicator.
1228
+ * Tabs: `[data-tab]` children (buttons); panels: `[data-panel]` children, in
1229
+ * the same order. Arrow keys / Home / End move between tabs (roving tabindex).
1230
+ *
1231
+ * Attributes: `selected` (index, 0), `indicator` (`line` default, `pill`),
1232
+ * `variant`. Events: `usa:change` (`{ index }`). Panels fade/slide in;
1233
+ * reduced motion: the indicator jumps and panels switch instantly.
1234
+ */
1235
+ interface UsaTabsElement extends UsaElement {
1236
+ selected: number;
1237
+ select(i: number, focus?: boolean): void;
1238
+ }
1239
+ declare function defineTabs(tag?: string): CustomElementConstructor | undefined;
1240
+
1241
+ /**
1242
+ * `<usa-drawer>` — a side panel that slides in with a spring and can be
1243
+ * dragged / swiped closed. Modal: backdrop, Esc, focus returns on close.
1244
+ * Attributes: `open`, `side` (`left` default, `right`, `top`, `bottom`),
1245
+ * `label`, `variant`. Events: `usa:open`, `usa:close`. `[data-close]` closes.
1246
+ * Reduced motion: opens and closes instantly.
1247
+ */
1248
+ interface UsaDrawerElement extends UsaElement {
1249
+ open: boolean;
1250
+ show(): void;
1251
+ close(): void;
1252
+ }
1253
+ /**
1254
+ * `<usa-bottom-sheet>` — a draggable bottom sheet with snap points
1255
+ * (`snap="0.3,0.6,0.92"`, fractions of the viewport height; default
1256
+ * `0.5,0.92`; `start` = index of the snap it opens at, default 0), inertia and drag-down-to-dismiss. `[data-handle]` (or the
1257
+ * built-in grabber) drags it. Attributes: `open`, `snap`, `start` (initial
1258
+ * snap index), `label`, `variant`. Events: `usa:open`, `usa:close`, `usa:snap`.
1259
+ */
1260
+ interface UsaBottomSheetElement extends UsaDrawerElement {
1261
+ }
1262
+ declare function defineDrawer(tag?: string): CustomElementConstructor | undefined;
1263
+ declare function defineBottomSheet(tag?: string): CustomElementConstructor | undefined;
1264
+
1265
+ /**
1266
+ * `<usa-pull-refresh>` — pull-to-refresh for a scroll container (itself):
1267
+ * pull down at the top (touch / pointer) and a spinner stretches in; past
1268
+ * `threshold` (px, 70) releasing fires `usa:refresh` — call
1269
+ * `event.detail.done()` (or return a promise to `onrefresh`) to finish.
1270
+ * Also exposes `refresh()` for a keyboard / button path.
1271
+ * Attributes: `threshold`, `disabled`, `label` (status text, "Refreshing").
1272
+ * Reduced motion: no stretch; the spinner simply appears while refreshing.
1273
+ */
1274
+ interface UsaPullRefreshElement extends UsaElement {
1275
+ readonly refreshing: boolean;
1276
+ refresh(): Promise<void>;
1277
+ }
1278
+ declare function definePullRefresh(tag?: string): CustomElementConstructor | undefined;
1279
+
1280
+ /**
1281
+ * `<usa-fab>` — floating action button with a speed dial. The first element
1282
+ * child is the main button; the others are actions that fan out with a
1283
+ * staggered spring when it opens (`direction="up"` default, `down`, `left`,
1284
+ * `right`, `radial`). Esc / outside click closes; `aria-expanded` on the
1285
+ * main button; actions are hidden from AT while closed.
1286
+ * Attributes: `open`, `direction`, `position` (`bottom-right` default, `bottom-left`,
1287
+ * `inline`), `gap` (px, 56), `variant`. Events: `usa:toggle` (`{ open }`).
1288
+ * Reduced motion: actions appear without travel.
1289
+ */
1290
+ interface UsaFabElement extends UsaElement {
1291
+ open: boolean;
1292
+ toggle(force?: boolean): void;
1293
+ }
1294
+ declare function defineFab(tag?: string): CustomElementConstructor | undefined;
1295
+
1296
+ /**
1297
+ * `<usa-navbar>` — an app bar that hides while you scroll down and returns
1298
+ * as soon as you scroll up (or reach the top); `shrink` makes it compact
1299
+ * once scrolled. Focus inside always reveals it.
1300
+ * Attributes: `threshold` (px of scroll before hiding, 64), `shrink`,
1301
+ * `target` (selector of a scroll container instead of the page), `variant`.
1302
+ * State attributes: `data-hidden`, `data-scrolled`. Events: `usa:hide`, `usa:show`.
1303
+ * Reduced motion: hides/shows without sliding (instant).
1304
+ */
1305
+ interface UsaNavbarElement extends UsaElement {
1306
+ readonly hiddenByScroll: boolean;
1307
+ show(): void;
1308
+ }
1309
+ declare function defineNavbar(tag?: string): CustomElementConstructor | undefined;
1310
+
1311
+ /**
1312
+ * `<usa-slider>` — a form-associated range slider (`role="slider"`). The
1313
+ * thumb follows with a spring, grows while dragged and shows a value bubble.
1314
+ * Keyboard: arrows (step), PageUp/PageDown (10 steps), Home/End.
1315
+ * Attributes: `value`, `min` (0), `max` (100), `step` (1), `name`, `label`,
1316
+ * `bubble` (show the value while dragging), `disabled`, `variant`.
1317
+ * Events: `input` + `usa:input` while moving, `change` + `usa:change` on release.
1318
+ * Reduced motion: the thumb jumps (no spring).
1319
+ */
1320
+ interface UsaSliderElement extends UsaElement {
1321
+ value: number;
1322
+ }
1323
+ declare function defineSlider(tag?: string): CustomElementConstructor | undefined;
1324
+
1325
+ /**
1326
+ * `<usa-rating>` — star rating with hover preview and a springy pop when a
1327
+ * value is chosen. `role="slider"` (arrow keys, Home/End, number keys).
1328
+ * Attributes: `value` (0), `max` (5), `icon` (★), `readonly`, `label`
1329
+ * ("Rating"), `name` (form value), `variant`. Events: `change`, `usa:change` (`{ value }`).
1330
+ * Reduced motion: no pop.
1331
+ */
1332
+ interface UsaRatingElement extends UsaElement {
1333
+ value: number;
1334
+ }
1335
+ declare function defineRating(tag?: string): CustomElementConstructor | undefined;
1336
+
1337
+ /**
1338
+ * `<usa-tooltip text="…">` — a tooltip for the element it wraps, shown on
1339
+ * hover (after `delay` ms, 300) and on keyboard focus, hidden on Esc / blur.
1340
+ * It springs in from its placement side and flips to stay on screen; the
1341
+ * trigger gets `aria-describedby`.
1342
+ * Attributes: `text`, `placement` (`top` default, `bottom`, `left`, `right`),
1343
+ * `delay`, `variant`. Reduced motion: fades only.
1344
+ */
1345
+ interface UsaTooltipElement extends UsaElement {
1346
+ show(): void;
1347
+ hide(): void;
1348
+ }
1349
+ declare function defineTooltip(tag?: string): CustomElementConstructor | undefined;
1350
+
1351
+ /**
1352
+ * `<usa-popover>` — a click-to-open popover: the first element child is the
1353
+ * trigger, `[data-popover]` is the content. Springs open from the trigger,
1354
+ * flips to stay on screen; Esc or an outside click closes and focus returns
1355
+ * to the trigger. `aria-expanded` / `aria-controls` on the trigger.
1356
+ * Attributes: `open`, `placement` (`bottom` default), `variant`. Events:
1357
+ * `usa:open`, `usa:close`. Reduced motion: fades only.
1358
+ */
1359
+ interface UsaPopoverElement extends UsaElement {
1360
+ open: boolean;
1361
+ toggle(force?: boolean): void;
1362
+ }
1363
+ declare function definePopover(tag?: string): CustomElementConstructor | undefined;
1364
+
1365
+ /**
1366
+ * `<usa-badge>` — a count / dot badge on whatever it wraps; bumps with a
1367
+ * spring whenever the value changes and pulses with `pulse`.
1368
+ * Attributes: `value` (number or text; 0 / empty hides it unless
1369
+ * `show-zero`), `max` (99 → "99+"), `dot`, `pulse`, `label` (accessible
1370
+ * text, default "{n} new"), `variant`. Reduced motion: no bump or pulse.
1371
+ */
1372
+ interface UsaBadgeElement extends UsaElement {
1373
+ value: string;
1374
+ }
1375
+ declare function defineBadge(tag?: string): CustomElementConstructor | undefined;
1376
+
1377
+ /**
1378
+ * `<usa-avatar-stack>` — overlapping avatars (its children: `<img>` or any
1379
+ * element) that spread apart with a spring on hover / focus; extra ones
1380
+ * collapse into a "+N" chip.
1381
+ * Attributes: `max` (visible avatars, 5), `size` (px, 36), `overlap` (0–1,
1382
+ * 0.35), `label` (group name), `variant`. Reduced motion: no spreading.
1383
+ */
1384
+ interface UsaAvatarStackElement extends UsaElement {
1385
+ }
1386
+ declare function defineAvatarStack(tag?: string): CustomElementConstructor | undefined;
1387
+
1388
+ /**
1389
+ * Style variants (v2.6): `variant="minimal | neon | glass | brutalist |
1390
+ * fluent | material"` on any `<usa-*>` element — or on any ancestor as
1391
+ * `data-usa-variant`, or page-wide with `setVariant()` — sets the shared
1392
+ * design tokens every component reads:
1393
+ *
1394
+ * `--usa-accent`, `--usa-accent-text`, `--usa-surface`, `--usa-text`,
1395
+ * `--usa-radius`, `--usa-border`, `--usa-shadow`, `--usa-blur`, `--usa-font`.
1396
+ *
1397
+ * (`<usa-spinner>`, `<usa-check>` and `<usa-dialog>` already use `variant`
1398
+ * for their kind; the token names never clash with those values except
1399
+ * `fluent`, which means the same thing there.)
1400
+ */
1401
+ declare const VARIANTS: readonly ["minimal", "neon", "glass", "brutalist", "fluent", "material"];
1402
+ type Variant = (typeof VARIANTS)[number];
1403
+ /** Inject the variant token sheet (done automatically by every `ui` component). */
1404
+ declare function adoptVariants(): void;
1405
+ /** Apply a variant to the whole page (or `root`); `null` removes it. */
1406
+ declare function setVariant(variant: Variant | null, root?: Element | null): void;
1407
+
1408
+ type Placement = 'top' | 'bottom' | 'left' | 'right';
1409
+
1410
+ /**
1411
+ * use-scroll-animate/components/ui — animated UI components + style variants (v2.6).
1412
+ * `<usa-tabs>`, `<usa-drawer>`, `<usa-bottom-sheet>`, `<usa-pull-refresh>`,
1413
+ * `<usa-fab>`, `<usa-navbar>`, `<usa-slider>`, `<usa-rating>`,
1414
+ * `<usa-tooltip>`, `<usa-popover>`, `<usa-badge>`, `<usa-avatar-stack>`,
1415
+ * and `variant="minimal | neon | glass | brutalist | fluent | material"`
1416
+ * design tokens (`setVariant()`, `VARIANTS`).
1417
+ */
1418
+
1419
+ /** Register every component of this category under its default tag. */
1420
+ declare function defineUiComponents(): void;
1421
+ declare global {
1422
+ interface HTMLElementTagNameMap {
1423
+ 'usa-tabs': UsaTabsElement;
1424
+ 'usa-drawer': UsaDrawerElement;
1425
+ 'usa-bottom-sheet': UsaBottomSheetElement;
1426
+ 'usa-pull-refresh': UsaPullRefreshElement;
1427
+ 'usa-fab': UsaFabElement;
1428
+ 'usa-navbar': UsaNavbarElement;
1429
+ 'usa-slider': UsaSliderElement;
1430
+ 'usa-rating': UsaRatingElement;
1431
+ 'usa-tooltip': UsaTooltipElement;
1432
+ 'usa-popover': UsaPopoverElement;
1433
+ 'usa-badge': UsaBadgeElement;
1434
+ 'usa-avatar-stack': UsaAvatarStackElement;
1435
+ }
1436
+ }
1437
+
1438
+ declare const CURSOR_MODES: readonly ["dot", "trail", "magnetic", "glow"];
1439
+ type CursorMode = (typeof CURSOR_MODES)[number];
1440
+ /**
1441
+ * `<usa-cursor mode="dot | trail | magnetic | glow">` — a custom cursor for
1442
+ * the page (place it once, e.g. at the end of `<body>`).
1443
+ * - `dot` — a ring that follows with spring lag around the real pointer;
1444
+ * - `trail` — a comet tail of dots;
1445
+ * - `magnetic` — the ring snaps onto and wraps hovered targets (`a`,
1446
+ * `button`, `[data-cursor]`);
1447
+ * - `glow` — a large soft light following the pointer (great on dark UIs).
1448
+ * Attributes: `mode`, `color`, `size` (px, 28), `hide-native` (hide the
1449
+ * system cursor), `targets` (selector, magnetic). Only for fine pointers
1450
+ * (mouse / pen); never on touch. Reduced motion: not rendered.
1451
+ */
1452
+ interface UsaCursorElement extends UsaElement {
1453
+ readonly active: boolean;
1454
+ }
1455
+ declare function defineCursor(tag?: string): CustomElementConstructor | undefined;
1456
+
1457
+ /**
1458
+ * `<usa-fullpage>` — full-screen sections (its element children) that snap
1459
+ * one at a time (CSS scroll snap), with keyboard paging (PageUp/PageDown,
1460
+ * arrows, Home/End), optional dot navigation and the current section in
1461
+ * `aria-current` + `usa:section`.
1462
+ * Attributes: `dots` (show the dot nav), `axis` (`y` default, `x`).
1463
+ * Methods: `go(i)`, `next()`, `prev()`. Reduced motion: snapping stays,
1464
+ * jumps are instant.
1465
+ */
1466
+ interface UsaFullpageElement extends UsaElement {
1467
+ readonly index: number;
1468
+ go(i: number): void;
1469
+ next(): void;
1470
+ prev(): void;
1471
+ }
1472
+ declare function defineFullpage(tag?: string): CustomElementConstructor | undefined;
1473
+
1474
+ /**
1475
+ * `<usa-loading-bar>` — a slim top loading bar for route changes and fetches
1476
+ * (NProgress-style): `start()` trickles towards 90 %, `done()` completes and
1477
+ * fades out, `set(0–1)` for real progress. `loadingBar` drives the first bar
1478
+ * on the page (created on demand). `role="progressbar"`, `aria-busy`.
1479
+ * Attributes: `color`, `height` (px, 3), `position` (`top` default, `bottom`).
1480
+ * Reduced motion: no trickle animation — the bar shows / hides.
1481
+ */
1482
+ interface UsaLoadingBarElement extends UsaElement {
1483
+ readonly progress: number;
1484
+ start(): void;
1485
+ set(p: number): void;
1486
+ done(): void;
1487
+ }
1488
+ declare function defineLoadingBar(tag?: string): CustomElementConstructor | undefined;
1489
+ /** Drive the page's `<usa-loading-bar>` (created on first use). */
1490
+ declare const loadingBar: {
1491
+ start: () => void;
1492
+ set: (p: number) => void;
1493
+ done: () => void;
1494
+ /** Run `task` with the bar shown; resolves with its result. */
1495
+ track<T>(task: Promise<T> | (() => Promise<T>)): Promise<T>;
1496
+ };
1497
+
1498
+ /**
1499
+ * `<usa-back-to-top>` — a floating button that appears after `offset` px
1500
+ * (300) of scrolling, shows page progress as a ring and springs the page
1501
+ * back to the top (then focuses `focus-target`, default `#main` / `body`).
1502
+ * Attributes: `offset`, `label` ("Back to top"), `focus-target`, `position`
1503
+ * (`bottom-right` default, `bottom-left`). Reduced motion: instant jump.
1504
+ */
1505
+ interface UsaBackToTopElement extends UsaElement {
1506
+ readonly visible: boolean;
1507
+ }
1508
+ declare function defineBackToTop(tag?: string): CustomElementConstructor | undefined;
1509
+
1510
+ declare const AMBIENT_EFFECTS: readonly ["particles", "snow", "stars", "noise", "gradient"];
1511
+ type AmbientEffect = (typeof AMBIENT_EFFECTS)[number];
1512
+ /**
1513
+ * `<usa-ambient effect="particles | snow | stars | noise | gradient">` — a
1514
+ * fixed, page-wide ambient layer behind (or, with `layer="front"`, over)
1515
+ * the content, never catching the pointer.
1516
+ * - `particles` — slow drifting dots; `snow` — falling flakes with sway;
1517
+ * `stars` — twinkling starfield (canvas, paused in hidden tabs, DPR ≤ 2);
1518
+ * - `noise` — animated film grain (CSS, SVG turbulence);
1519
+ * - `gradient` — a gradient whose hue shifts with the scroll position.
1520
+ * Attributes: `effect`, `density` (0.2–3, 1), `color`, `opacity` (0.6),
1521
+ * `layer` (`back` default, `front`), `speed` (1). Reduced motion: one
1522
+ * static frame (no falling, twinkling or grain flicker).
1523
+ */
1524
+ interface UsaAmbientElement extends UsaElement {
1525
+ }
1526
+ declare function defineAmbient(tag?: string): CustomElementConstructor | undefined;
1527
+
1528
+ /**
1529
+ * `<usa-splash>` — an app splash / launch screen: shows its content (logo,
1530
+ * spinner) over the page, then leaves with `exit` (`fade` default, `scale`,
1531
+ * `slide-up`, `circle`) once the page has loaded (or when you call
1532
+ * `done()`), but never sooner than `min` ms (600) — no flash.
1533
+ * Attributes: `min`, `exit`, `manual` (wait for `done()`), `label`.
1534
+ * Events: `usa:done`. The page underneath is `aria-busy` until then.
1535
+ * Reduced motion: fades.
1536
+ */
1537
+ interface UsaSplashElement extends UsaElement {
1538
+ done(): Promise<void>;
1539
+ }
1540
+ declare function defineSplash(tag?: string): CustomElementConstructor | undefined;
1541
+
1542
+ /**
1543
+ * `<usa-auto-skeleton loading>` — automatic skeletons: while `loading` is
1544
+ * set, every text block, image, button and input inside is drawn as a
1545
+ * shimmering placeholder of its own size — no separate skeleton markup.
1546
+ * Remove `loading` (or set `.loading = false`) and the content fades in.
1547
+ * `aria-busy` while loading. Opt elements out with `data-no-skeleton`.
1548
+ * Reduced motion: static placeholders, no shimmer or fade.
1549
+ */
1550
+ interface UsaAutoSkeletonElement extends UsaElement {
1551
+ loading: boolean;
1552
+ }
1553
+ declare function defineAutoSkeleton(tag?: string): CustomElementConstructor | undefined;
1554
+
1555
+ /**
1556
+ * Set the global motion intensity for every `<usa-*>` component:
1557
+ * `'off'` (like reduced motion), `'low'`, `'normal'` (default), `'high'`.
1558
+ * Sets `--usa-motion` and `data-usa-motion` on `<html>`; with `persist`
1559
+ * the choice is remembered (localStorage) and restored by `restoreMotionIntensity()`.
1560
+ */
1561
+ declare function setMotionIntensity(level: MotionIntensity, persist?: boolean): void;
1562
+ /** Re-apply a persisted intensity (call early on page load). Returns it. */
1563
+ declare function restoreMotionIntensity(): MotionIntensity;
1564
+ /**
1565
+ * `<usa-motion-switch>` — a segmented control letting users choose the
1566
+ * app's motion intensity (Off · Low · Normal · High), persisted.
1567
+ * `role="radiogroup"`; arrow keys move. Attributes: `labels` (comma list),
1568
+ * `label` ("Motion"). Events: `usa:change` (`{ level }`).
1569
+ */
1570
+ interface UsaMotionSwitchElement extends UsaElement {
1571
+ value: MotionIntensity;
1572
+ }
1573
+ declare function defineMotionSwitch(tag?: string): CustomElementConstructor | undefined;
1574
+
1575
+ /**
1576
+ * Page & app-wide transitions (v2.7), built on the View Transitions API
1577
+ * (Chromium: Chrome, Edge, Electron, WebView2) with graceful fallbacks.
1578
+ *
1579
+ * - `pageTransition(update, { effect })` — SPA route changes: `fade`,
1580
+ * `slide` (`slide-left` / `slide-right` / `slide-up`), `circle` (reveal
1581
+ * from `x`, `y`), `blinds`, `pixel` (stepped dissolve), `zoom`.
1582
+ * - `enableMpaTransitions(effect)` — the same effects for multi-page sites
1583
+ * (`@view-transition { navigation: auto }`); call it on every page.
1584
+ * - `themeTransition(apply, { x, y })` — a circle-reveal theme switch.
1585
+ *
1586
+ * Without View Transitions (Firefox, older Safari) or under reduced motion
1587
+ * the update runs immediately (`fade` falls back to a short cross-fade of
1588
+ * `fallback` when given).
1589
+ */
1590
+ declare const PAGE_EFFECTS: readonly ["fade", "slide", "slide-left", "slide-right", "slide-up", "circle", "blinds", "pixel", "zoom"];
1591
+ type PageEffect = (typeof PAGE_EFFECTS)[number];
1592
+ interface PageTransitionOptions {
1593
+ effect?: PageEffect;
1594
+ /** Circle origin in client px (default: viewport centre / last pointer). */
1595
+ x?: number;
1596
+ y?: number;
1597
+ /** Duration in ms (default 600). */
1598
+ duration?: number;
1599
+ /** Element to cross-fade when View Transitions are unavailable. */
1600
+ fallback?: Element | null;
1601
+ }
1602
+ /** `true` when `document.startViewTransition` exists. */
1603
+ declare const supportsViewTransitions: () => boolean;
1604
+ /** Run `update` (sync or async) as an animated page transition. Resolves when it is done. */
1605
+ declare function pageTransition(update: () => unknown, options?: PageTransitionOptions): Promise<void>;
1606
+ /** Opt a multi-page site into cross-document view transitions with `effect`. */
1607
+ declare function enableMpaTransitions(effect?: PageEffect, duration?: number): void;
1608
+ /**
1609
+ * Switch theme with a circle reveal from (`x`, `y`) (default: last pointer).
1610
+ * `apply` flips your theme (e.g. toggles a class / `data-theme`).
1611
+ */
1612
+ declare function themeTransition(apply: () => unknown, options?: Omit<PageTransitionOptions, 'effect'>): Promise<void>;
1613
+
1614
+ /**
1615
+ * `smoothScroll()` — inertial wheel smoothing for the page (or a scroll
1616
+ * container): wheel deltas are eased with a lerp each frame. Touch and
1617
+ * keyboard scrolling stay native. Returns a function that turns it off.
1618
+ * No-op under reduced motion, on touch-only devices and on the server.
1619
+ */
1620
+ interface SmoothScrollOptions {
1621
+ /** Scroll container (default: the page). */
1622
+ target?: HTMLElement | null;
1623
+ /** 0–1, lower = smoother / longer glide (default 0.12). */
1624
+ lerp?: number;
1625
+ /** Wheel multiplier (default 1). */
1626
+ wheelMultiplier?: number;
1627
+ }
1628
+ declare function smoothScroll(options?: SmoothScrollOptions): () => void;
1629
+ /**
1630
+ * Scroll to a y position, element or selector with spring timing (or
1631
+ * instantly under reduced motion). Resolves when done.
1632
+ */
1633
+ declare function scrollToTarget(to: number | Element | string, options?: {
1634
+ offset?: number;
1635
+ target?: HTMLElement | null;
1636
+ preset?: string;
1637
+ }): Promise<void>;
1638
+
1639
+ /**
1640
+ * use-scroll-animate/components/page — page & app-wide effects (v2.7).
1641
+ * Page transitions (`pageTransition()`, `enableMpaTransitions()`,
1642
+ * `themeTransition()`), `<usa-cursor>`, `smoothScroll()` / `scrollToTarget()`,
1643
+ * `<usa-fullpage>`, `<usa-loading-bar>` + `loadingBar`, `<usa-back-to-top>`,
1644
+ * `<usa-ambient>`, `<usa-splash>`, `<usa-auto-skeleton>` and the global motion
1645
+ * intensity (`setMotionIntensity()`, `<usa-motion-switch>`).
1646
+ */
1647
+
1648
+ /** Register every component of this category under its default tag. */
1649
+ declare function definePageComponents(): void;
1650
+ declare global {
1651
+ interface HTMLElementTagNameMap {
1652
+ 'usa-cursor': UsaCursorElement;
1653
+ 'usa-fullpage': UsaFullpageElement;
1654
+ 'usa-loading-bar': UsaLoadingBarElement;
1655
+ 'usa-back-to-top': UsaBackToTopElement;
1656
+ 'usa-ambient': UsaAmbientElement;
1657
+ 'usa-splash': UsaSplashElement;
1658
+ 'usa-auto-skeleton': UsaAutoSkeletonElement;
1659
+ 'usa-motion-switch': UsaMotionSwitchElement;
1660
+ }
1661
+ }
1662
+
1215
1663
  /** The component categories and their default tags. */
1216
1664
  declare const COMPONENT_CATEGORIES: {
1217
1665
  readonly reveal: readonly ["usa-reveal", "usa-stagger", "usa-scroll-progress", "usa-scrolly"];
@@ -1223,6 +1671,8 @@ declare const COMPONENT_CATEGORIES: {
1223
1671
  readonly physics: readonly ["usa-spring", "usa-draggable", "usa-overscroll"];
1224
1672
  readonly cards: readonly ["usa-card", "usa-card-stack", "usa-sticky-stack", "usa-carousel-3d"];
1225
1673
  readonly click: readonly ["usa-click", "usa-button", "usa-icon-morph", "usa-like", "usa-hold", "usa-double-tap", "usa-checkbox"];
1674
+ 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"];
1675
+ readonly page: readonly ["usa-cursor", "usa-fullpage", "usa-loading-bar", "usa-back-to-top", "usa-ambient", "usa-splash", "usa-auto-skeleton", "usa-motion-switch"];
1226
1676
  };
1227
1677
  type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
1228
1678
  /**
@@ -1231,5 +1681,5 @@ type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;
1231
1681
  */
1232
1682
  declare function defineComponents(categories?: ComponentCategory[]): void;
1233
1683
 
1234
- 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 };
1235
- 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 };
1684
+ 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, defineBottomSheet, defineButton, defineCard, defineCardComponents, defineCardStack, defineCarousel3d, defineCheck, defineCheckbox, defineClick, defineClickComponents, defineComponents, defineCounter, defineCursor, defineDialog, defineDoubleTap, defineDraggable, defineDrawer, defineFab, defineFeedbackComponents, defineFlipList, defineFullpage, defineGrain, defineHold, defineIconMorph, defineInteractionComponents, defineLike, defineLoadingBar, defineMagnetic, defineMarquee, defineMotionSwitch, defineNavbar, defineOverscroll, definePageComponents, defineParticles, definePhysicsComponents, definePopover, definePress, defineProgress, definePullRefresh, defineRating, defineReveal, defineRevealComponents, defineRipple, defineScramble, defineScrollProgress, defineScrolly, defineShimmerText, defineSkeleton, defineSlider, defineSpinner, defineSplash, defineSplitText, defineSpotlight, defineSpring, defineStagger, defineStickyStack, defineTabs, defineTextComponents, defineTextRotate, defineTilt, defineToaster, defineToggle, defineTooltip, defineTransitionComponents, defineTypewriter, defineUiComponents, defineViewSwitch, easeOutExpo, enableMpaTransitions, flip, 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 };
1685
+ export type { AmbientEffect, BurstOptions, ButtonDeform, ButtonShape, ButtonState, CardEffect, ClickEffect, ComponentCategory, ComponentsConfig, ConfettiOptions, ConnectedOptions, CursorMode, DialogVariant, FlipOptions, MotionIntensity, PageEffect, PageTransitionOptions, Placement, RevealEffect, SmoothScrollOptions, SpinnerVariant, SpringConfig, SpringEffect, SpringInput, SpringPreset, SpringValue, SpringValueOptions, ToastHandle, ToastOptions, ToastType, UsaAccordionElement, UsaAcrylicElement, UsaAmbientElement, UsaAuroraElement, UsaAutoSkeletonElement, UsaAvatarStackElement, UsaBackToTopElement, UsaBadgeElement, UsaBottomSheetElement, UsaButtonElement, UsaCardElement, UsaCardStackElement, UsaCarousel3dElement, UsaCheckElement, UsaCheckboxElement, UsaClickElement, UsaCounterElement, UsaCursorElement, UsaDialogElement, UsaDoubleTapElement, UsaDraggableElement, UsaDrawerElement, UsaElement, UsaFabElement, UsaFlipListElement, UsaFullpageElement, UsaGrainElement, UsaHoldElement, UsaIconMorphElement, UsaLikeElement, UsaLoadingBarElement, UsaMagneticElement, UsaMarqueeElement, UsaMotionSwitchElement, UsaNavbarElement, UsaOverscrollElement, UsaParticlesElement, UsaPopoverElement, UsaPressElement, UsaProgressElement, UsaPullRefreshElement, UsaRatingElement, UsaRevealElement, UsaRippleElement, UsaScrambleElement, UsaScrollProgressElement, UsaScrollyElement, UsaShimmerTextElement, UsaSkeletonElement, UsaSliderElement, UsaSpinnerElement, UsaSplashElement, UsaSplitTextElement, UsaSpotlightElement, UsaSpringElement, UsaStaggerElement, UsaStickyStackElement, UsaTabsElement, UsaTextRotateElement, UsaTiltElement, UsaToasterElement, UsaToggleElement, UsaTooltipElement, UsaTypewriterElement, UsaViewSwitchElement, Variant, ViewTransitionOptions };