use-scroll-animate 5.8.0 → 6.0.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.0.0] - 2026-10-08
+
+### ⚠ BREAKING CHANGES
+- **Removed `burst()`, `confetti()`, `shake()`** from `use-scroll-animate/components`, `/components/click` and the UMD global (deprecated in 5.9). Play the registered effects instead: `playEffect(document.body, 'burst', { x, y, …options })`, `playEffect(el, 'confetti', options)`, `playEffect(el, 'shake', { intensity, duration })` (`use-scroll-animate/components/fx`). `haptic()` stays.
+- **Removed `<usa-cursor mode="trail">`** (deprecated in 5.9): `CURSOR_MODES` is now `dot` · `magnetic` · `glow`, and an unknown mode renders as `dot`. Use the 5.7 `comet-trail` effect: `<usa-fx effect="comet-trail" trigger="load" self>…</usa-fx>`.
+- Every effect now goes through the 5.0 registry (`registerEffect()` / `playEffect()` / `bindEffect()` / `<usa-fx>`); the 5.1–5.9 packs live in `use-scroll-animate/components/effects`.
+
+### Migration
+- `npx usa-codemod-6 --write src` rewrites the helper calls and imports (aliases and the `UsaComponents` global included) and lists `<usa-cursor mode="trail">` for a manual edit. Guide: `docs/upgrading-6.md`.
+- CDN URLs move to the `@6` range: `https://unpkg.com/use-scroll-animate@6/dist/components.umd.js`.
+
+### Docs
+- README (EN / 中文 / 日本語): new **Effect packs** (`/components/effects`) row.
+- `docs/ROADMAP.md`: post-6.0 roadmap (v6.1 → v7.0).
+
+## [5.9.0] - 2026-10-08
+
+### Added
+- **`<usa-player>`** (`use-scroll-animate/components/effects`, `definePlayer()`) — plays JSON animations (`format: "use-scroll-animate/animation"`, `version: 1`): tracks with a `target` selector, `start` / `duration`, and a timeline `preset`, your own `keyframes` + `easing`, or any registered `effect` fired at `start`. Source: `src="…json"` or an inline `<script type="application/json">`. `trigger="load | view | scroll | click | manual"` (`scroll` scrubs with the page), `loop`, `rate`, `controls`; methods `play()`, `pause()`, `seek(ms)`, `load(json)`; events `usa-player-ready`, `usa-player-finish`; `data-error` on bad input.
+- `createPlayer(root, animation, { autoplay, loop, rate })` → `{ play, pause, seek, rate, duration, currentTime, playing, finished, destroy }` — keyframe tracks are WAAPI animations driven by one clock; `normalizeAnimation()` validates (and reads Playground presets too).
+- Playground: new **`<usa-player> JSON`** export tab (`tracksToAnimation()`).
+- The registered `burst` effect accepts `x` / `y`.
+- `docs/upgrading-6.md` and **`npx usa-codemod-6 [--write] [paths]`**.
+
+### Deprecated (removed in 6.0 — warned once in the console)
+- `burst()`, `confetti()`, `shake()` (components / components/click entries, UMD global) → `playEffect(el, 'burst' | 'confetti' | 'shake', …)` — the codemod rewrites calls and imports.
+- `<usa-cursor mode="trail">` → the 5.7 `comet-trail` effect (`<usa-fx effect="comet-trail" trigger="load" self>`) — reported by the codemod for a manual edit.
+
+### Accessibility
+- Under reduced motion `<usa-player>` jumps to the final state and fires no effects.
+
 ## [5.8.0] - 2026-10-08
 
 ### Added

package/README.md

@@ -39,7 +39,7 @@ defineComponents(); // or per category: import { defineTextComponents } from 'us
 
 ```html
 <!-- or with no build step -->
-<script src="https://unpkg.com/use-scroll-animate@5/dist/components.umd.js"></script>
+<script src="https://unpkg.com/use-scroll-animate@6/dist/components.umd.js"></script>
 <usa-typewriter words="Hello, Windows.|Hello, web."></usa-typewriter>
 <usa-spinner kind="fluent"></usa-spinner>
 ```
@@ -54,7 +54,7 @@ defineComponents(); // or per category: import { defineTextComponents } from 'us
 | **Transitions** (`/components/transitions`) | `<usa-dialog>` (modal / drawer / sheet) · `<usa-accordion>` · `<usa-view-switch>` · `viewTransition()` · `flip()` |
 | **Spring & physics** (`/components/physics`) | `<usa-spring>` (bounce-in · pop · drop · jelly · rubber-band) · `<usa-draggable>` (spring-back · inertia · snap) · `<usa-overscroll>` · `spring()` · `createSpring()` · `SPRING_PRESETS` |
 | **Card effects** (`/components/cards`) | `<usa-card>` (flip · holo · glass · border-glow · conic-border · lift · spotlight · sheen · parallax-layers · expand — combinable) · `<usa-card-stack>` (swipe) · `<usa-sticky-stack>` · `<usa-carousel-3d>` |
-| **Click & tap** (`/components/click`) | `<usa-button>` **button click deformation** (squash · wobble · gooey · dent · shape morph · submit→loading→success) · `<usa-icon-morph>` · `<usa-click>` (ripple · burst · confetti · squish · press-spring · shake) · `<usa-like>` · `<usa-hold>` · `<usa-double-tap>` · `<usa-checkbox>` · `confetti()` · `haptic()` |
+| **Click & tap** (`/components/click`) | `<usa-button>` **button click deformation** (squash · wobble · gooey · dent · shape morph · submit→loading→success) · `<usa-icon-morph>` · `<usa-click>` (ripple · burst · confetti · squish · press-spring · shake) · `<usa-like>` · `<usa-hold>` · `<usa-double-tap>` · `<usa-checkbox>` · `haptic()` (click effects from code: `playEffect(el, 'confetti')`) |
 | **UI components & variants** (`/components/ui`) | `<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>` · `variant="minimal \| neon \| glass \| brutalist \| fluent \| material"` on every component |
 | **Page & app-wide** (`/components/page`) | `pageTransition()` (fade · slide · circle · blinds · pixel · zoom; SPA + MPA) · `themeTransition()` · `<usa-cursor>` · `smoothScroll()` · `<usa-fullpage>` · `<usa-loading-bar>` · `<usa-back-to-top>` · `<usa-ambient>` (particles · snow · stars · noise · gradient) · `<usa-splash>` · `<usa-auto-skeleton>` · `<usa-motion-switch>` / `setMotionIntensity()` |
 | **Timeline & choreography** (`/components/timeline`) | `timeline()` (chain · overlap · labels · seek · reverse · scrub) · `<usa-timeline>` (`data-tl` steps) |
@@ -65,6 +65,7 @@ defineComponents(); // or per category: import { defineTextComponents } from 'us
 | **Layout animation** (`/components/layout`) | `<usa-auto-animate>` / `autoAnimate()` (list & grid reflow) · `<usa-masonry>` · `sharedTransition()` (shared elements) |
 | **Effect packs** (`/components/packs`) | `<usa-pack>` (`name="ecommerce \| portfolio \| dashboard \| game \| landing"`) · `applyPack()` · `flyToCart()` · `countUp()` |
 | **Effects — plugin API** (`/components/fx`) | `<usa-fx>` (`effect` · `trigger` click / hover / enter / load / loop) · `registerEffect()` · `playEffect()` · `bindEffect()` · built-ins: every timeline entrance, pulse · pop · jelly · wiggle · heartbeat · bounce · flash · tada · shake, burst · confetti · ripple |
+| **Effect packs** (`/components/effects`) | `registerAllEffects()` · card & click 2.0 · physics · page-wide · `<usa-story>` scroll stories · generative backgrounds · sound-reactive (`<usa-audio>`) · cursor trails & gestures (`<usa-gesture-fx>`) · theme packs (`<usa-theme>`) · 23 micro-interactions · `<usa-player>` JSON animations |
 
 Whole bundle ≈ 22 kB gzip (JS + CSS); one category 3.5–6.4 kB; a single component ≈ 2 kB. The scroll-animation core below is unaffected.
 

package/README_ja.md

@@ -53,6 +53,7 @@ defineComponents(); // カテゴリ単位: import { defineTextComponents } from
 | **レイアウト** (`/components/layout`) | `<usa-auto-animate>` / `autoAnimate()` · `<usa-masonry>` · `sharedTransition()`（共有要素） |
 | **エフェクトパック** (`/components/packs`) | `<usa-pack>` (`name="ecommerce \| portfolio \| dashboard \| game \| landing"`) · `applyPack()` · `flyToCart()` |
 | **エフェクト API** (`/components/fx`) | `<usa-fx>` · `registerEffect()` · `playEffect()` · `bindEffect()` · 内蔵: タイムライン入場、pulse · pop · jelly · wiggle · bounce · tada · shake、burst · confetti · ripple |
+| **エフェクトパック** (`/components/effects`) | `registerAllEffects()` · カード & クリック 2.0 · 物理 · ページ全体 · `<usa-story>` スクロールストーリー · ジェネレーティブ背景 · サウンド連動（`<usa-audio>`）· カーソル & ジェスチャー（`<usa-gesture-fx>`）· テーマパック（`<usa-theme>`）· マイクロインタラクション 23 種 · `<usa-player>` JSON アニメーション |
 
 ## ドキュメント
 

package/README_zh.md

@@ -36,7 +36,7 @@ defineComponents(); // 或按分类：import { defineTextComponents } from 'use-
 
 ```html
 <!-- 或免构建直接使用 -->
-<script src="https://unpkg.com/use-scroll-animate@5/dist/components.umd.js"></script>
+<script src="https://unpkg.com/use-scroll-animate@6/dist/components.umd.js"></script>
 <usa-typewriter words="你好，Windows。|你好，Web。"></usa-typewriter>
 <usa-spinner kind="fluent"></usa-spinner>
 ```
@@ -62,6 +62,7 @@ defineComponents(); // 或按分类：import { defineTextComponents } from 'use-
 | **布局动画** (`/components/layout`) | `<usa-auto-animate>` / `autoAnimate()`（列表与网格重排）· `<usa-masonry>`（瀑布流）· `sharedTransition()`（共享元素） |
 | **效果包** (`/components/packs`) | `<usa-pack>` (`name="ecommerce \| portfolio \| dashboard \| game \| landing"`) · `applyPack()` · `flyToCart()` · `countUp()` |
 | **特效插件 API** (`/components/fx`) | `<usa-fx>`（`effect` · `trigger`）· `registerEffect()` · `playEffect()` · `bindEffect()` · 内置：全部时间线入场、pulse · pop · jelly · wiggle · heartbeat · bounce · flash · tada · shake、burst · confetti · ripple |
+| **特效包** (`/components/effects`) | `registerAllEffects()` · 卡片与点击 2.0 · 物理 · 全页特效 · `<usa-story>` 滚动叙事 · 生成式背景 · 声音响应（`<usa-audio>`）· 光标拖尾与手势（`<usa-gesture-fx>`）· 主题包（`<usa-theme>`）· 23 个微交互 · `<usa-player>` JSON 动画 |
 
 完整包约 22 kB gzip（JS + CSS）；单个分类 3.5–6.4 kB；单个组件约 2 kB。下方的滚动动画核心不受影响。
 

package/bin/usa-codemod-6.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// use-scroll-animate 5.x → 6.0 codemod.
+//   npx usa-codemod-6 [--write] [paths…]   (default: ./src; dry run without --write)
+// Rewrites (5.9 deprecations, removed in 6.0 — every effect goes through the registry):
+//   1. burst(x, y[, opts])      → playEffect(document.body, 'burst', { x: x, y: y[, ...opts] })
+//   2. confetti([opts])         → playEffect(document.body, 'confetti'[, opts])
+//   3. shake(el[, i[, d]])      → playEffect(el, 'shake'[, { intensity: i[, duration: d] }])
+//      …and the import of burst / confetti / shake from use-scroll-animate/components[/click]
+//      becomes `import { playEffect } from 'use-scroll-animate/components/fx'`.
+// Reported for a manual change (no safe rewrite):
+//   4. <usa-cursor mode="trail"> → <usa-fx effect="comet-trail" trigger="load" self> around the content
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const EXT = new Set(['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.mts', '.cts', '.vue', '.svelte', '.html', '.astro']);
+const OLD = ['burst', 'confetti', 'shake'];
+
+/** Split a call's argument list at top-level commas (pure). */
+export function splitArgs(s) {
+  const out = [];
+  let depth = 0;
+  let cur = '';
+  let q = '';
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (q) {
+      cur += c;
+      if (c === '\\') cur += s[++i] ?? '';
+      else if (c === q) q = '';
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') q = c;
+    else if ('([{'.includes(c)) depth++;
+    else if (')]}'.includes(c)) depth--;
+    if (c === ',' && depth === 0) {
+      out.push(cur.trim());
+      cur = '';
+    } else cur += c;
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+
+/** Find `name(` calls and their balanced argument text. */
+function rewriteCalls(code, name, fn, changes) {
+  const re = new RegExp(`(?<![\\w.$])${name}\\(`, 'g');
+  let out = '';
+  let last = 0;
+  let m;
+  while ((m = re.exec(code))) {
+    const start = m.index;
+    let i = re.lastIndex;
+    let depth = 1;
+    let q = '';
+    for (; i < code.length && depth; i++) {
+      const c = code[i];
+      if (q) {
+        if (c === '\\') i++;
+        else if (c === q) q = '';
+      } else if (c === '"' || c === "'" || c === '`') q = c;
+      else if (c === '(') depth++;
+      else if (c === ')') depth--;
+    }
+    if (depth) break;
+    const args = splitArgs(code.slice(re.lastIndex, i - 1));
+    const rep = fn(args);
+    if (rep == null) continue;
+    out += code.slice(last, start) + rep;
+    last = i;
+    re.lastIndex = i;
+    changes.push(`${name.replace('\\', '')}() → playEffect(…)`);
+  }
+  return out + code.slice(last);
+}
+
+const objOf = (pairs, rest) => {
+  const lit = rest && /^\{[\s\S]*\}$/.test(rest) ? rest.slice(1, -1).trim() : '';
+  const tail = rest ? [lit || `...${rest}`] : [];
+  return `{ ${[...pairs.filter(([, v]) => v !== undefined).map(([k, v]) => (k === v ? k : `${k}: ${v}`)), ...tail].filter(Boolean).join(', ')} }`;
+};
+
+/** Apply every rewrite to one file's source. Returns { code, changes, manual }. */
+export function transform(source) {
+  const changes = [];
+  const manual = [];
+  let code = source;
+  // Only touch files that import the old helpers from the library (or use the UMD global).
+  const importRe = /import\s*\{([^}]*)\}\s*from\s*(['"])use-scroll-animate\/components(?:\/click)?\2;?/g;
+  const imported = new Map(); // local name → original helper
+  code = code.replace(importRe, (m, names, q) => {
+    const list = names.split(',').map((n) => n.trim()).filter(Boolean);
+    const old = list.filter((n) => OLD.includes(n.split(/\s+as\s+/)[0]));
+    if (!old.length) return m;
+    old.forEach((n) => imported.set(n.split(/\s+as\s+/).pop(), n.split(/\s+as\s+/)[0]));
+    const rest = list.filter((n) => !old.includes(n));
+    const src = m.match(/from\s*(['"])(.*?)\1/)[2];
+    changes.push(`import { ${old.join(', ')} } → import { playEffect } from 'use-scroll-animate/components/fx'`);
+    const keep = rest.length ? `import { ${rest.join(', ')} } from ${q}${src}${q};\n` : '';
+    return `${keep}import { playEffect } from ${q}use-scroll-animate/components/fx${q};`;
+  });
+  const umd = /UsaComponents\.(burst|confetti|shake)\(/.test(code);
+  if (umd) code = code.replace(/UsaComponents\.(burst|confetti|shake)\(/g, (_m, n) => (imported.set(`UsaComponents.${n}`, n), `UsaComponents.${n}(`));
+  for (const [name, kind] of imported) {
+    const pe = name.startsWith('UsaComponents.') ? 'UsaComponents.playEffect' : 'playEffect';
+    const esc = name.replace('.', '\\.');
+    code = rewriteCalls(code, esc, (a) => {
+      if (kind === 'burst') return a.length >= 2 ? `${pe}(document.body, 'burst', ${objOf([['x', a[0]], ['y', a[1]]], a[2])})` : null;
+      if (kind === 'confetti') return `${pe}(document.body, 'confetti'${a[0] ? `, ${a[0]}` : ''})`;
+      if (kind === 'shake') return a.length ? `${pe}(${a[0]}, 'shake'${a.length > 1 ? `, ${objOf([['intensity', a[1]], ['duration', a[2]]])}` : ''})` : null;
+      return null;
+    }, changes);
+  }
+  if (/<usa-cursor\b[^>]*\bmode=(["'])trail\1/.test(code)) manual.push('<usa-cursor mode="trail"> is removed in 6.0 — wrap the content in <usa-fx effect="comet-trail" trigger="load" self> (see docs/upgrading-6.md)');
+  return { code, changes, manual };
+}
+
+function* walk(p) {
+  const st = statSync(p);
+  if (st.isDirectory()) {
+    for (const f of readdirSync(p)) if (!['node_modules', 'dist', '.git'].includes(f)) yield* walk(join(p, f));
+  } else if (EXT.has(extname(p))) yield p;
+}
+
+export function run(args) {
+  const write = args.includes('--write');
+  const paths = args.filter((a) => !a.startsWith('--'));
+  let files = 0;
+  let edits = 0;
+  let todo = 0;
+  for (const root of paths.length ? paths : ['src'])
+    for (const f of walk(root)) {
+      const src = readFileSync(f, 'utf8');
+      const { code, changes, manual } = transform(src);
+      if (!changes.length && !manual.length) continue;
+      files++;
+      edits += changes.length;
+      todo += manual.length;
+      console.log(`${f}${changes.map((c) => `\n  - ${c}`).join('')}${manual.map((c) => `\n  ! manual: ${c}`).join('')}`);
+      if (write && changes.length) writeFileSync(f, code);
+    }
+  console.log(`\n${edits} change(s), ${todo} manual item(s) in ${files} file(s)${write ? ' written' : ' (dry run — add --write to apply)'}.`);
+  return { files, edits, manual: todo };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) run(process.argv.slice(2));

package/dist/components/angular.d.cts

@@ -1033,7 +1033,8 @@ interface UsaCheckboxElement extends UsaElement {
  * `<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()`.
+ * `haptic()`. 6.0: `burst()`, `confetti()` and `shake()` were removed — play
+ * the registered effects instead: `playEffect(el, 'burst' | 'confetti' | 'shake')`.
  */
 
 declare global {
@@ -1225,10 +1226,11 @@ declare global {
 }
 
 /**
- * `<usa-cursor mode="dot | trail | magnetic | glow">` — a custom cursor for
+ * `<usa-cursor mode="dot | magnetic | glow">` — a custom cursor for
  * the page (place it once, e.g. at the end of `<body>`).
  * - `dot` — a ring that follows with spring lag around the real pointer;
- * - `trail` — a comet tail of dots;
+ * (6.0: `mode="trail"` was removed — use the registered `comet-trail` effect;
+ * unknown modes render as `dot`.)
  * - `magnetic` — the ring snaps onto and wraps hovered targets (`a`,
  *   `button`, `[data-cursor]`);
  * - `glow` — a large soft light following the pointer (great on dark UIs).

package/dist/components/angular.d.ts

@@ -1033,7 +1033,8 @@ interface UsaCheckboxElement extends UsaElement {
  * `<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()`.
+ * `haptic()`. 6.0: `burst()`, `confetti()` and `shake()` were removed — play
+ * the registered effects instead: `playEffect(el, 'burst' | 'confetti' | 'shake')`.
  */
 
 declare global {
@@ -1225,10 +1226,11 @@ declare global {
 }
 
 /**
- * `<usa-cursor mode="dot | trail | magnetic | glow">` — a custom cursor for
+ * `<usa-cursor mode="dot | magnetic | glow">` — a custom cursor for
  * the page (place it once, e.g. at the end of `<body>`).
  * - `dot` — a ring that follows with spring lag around the real pointer;
- * - `trail` — a comet tail of dots;
+ * (6.0: `mode="trail"` was removed — use the registered `comet-trail` effect;
+ * unknown modes render as `dot`.)
  * - `magnetic` — the ring snaps onto and wraps hovered targets (`a`,
  *   `button`, `[data-cursor]`);
  * - `glow` — a large soft light following the pointer (great on dark UIs).

package/dist/components/click.cjs

@@ -847,7 +847,8 @@ function defineCheckbox(tag = 'usa-checkbox') {
  * `<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()`.
+ * `haptic()`. 6.0: `burst()`, `confetti()` and `shake()` were removed — play
+ * the registered effects instead: `playEffect(el, 'burst' | 'confetti' | 'shake')`.
  */
 /** Register every component of this category under its default tag. */
 function defineClickComponents() {
@@ -860,10 +861,7 @@ function defineClickComponents() {
     defineCheckbox();
 }
 
-exports.burst = fx.burst;
-exports.confetti = fx.confetti;
 exports.haptic = fx.haptic;
-exports.shake = fx.shake;
 exports.BUTTON_DEFORMS = BUTTON_DEFORMS;
 exports.CLICK_EFFECTS = CLICK_EFFECTS;
 exports.MORPH_ICONS = MORPH_ICONS;