use-scroll-animate 8.8.0 → 9.0.0

package/docs/ROADMAP.md

@@ -1,16 +1,14 @@
-# Motionary 路线图（8.0 之后）
+# Motionary 路线图（9.0 之后）
 
-8.0 已发布：统一时间线引擎（`motionary/engine` —— 所有组件、特效与帧循环共享一个时钟，可整体暂停、变速、编排）、SSR 水合动画（`ssrHead()` + `hydrateMotion()` / `<usa-hydrate>`）、移除 7.9 弃用的 `<usa-rating>`；`motionary` 与 `use-scroll-animate` 同时成为 npm `latest`。下面是 8.1 → 9.0 的计划，每个版本一个特效主题 + 一组新的动画组件，x.9 版本负责下一个大版本的弃用与迁移工具。
+9.0 已发布：声明式动效 DSL（`motionary/dsl` —— 用 `data-motion="enter: fade-up 600ms stagger 80ms; hover: pop"` 一行文本描述完整动效，或用 `<usa-motion>`）、插件市场正式版（`motionary/marketplace` —— 目录、搜索、一键安装，`<usa-plugin-store>`）、移除 8.9 弃用的 `applyTheme()` / `THEMES` / `THEME_NAMES` / `<usa-theme>`（改名为 Motion 前缀）；`motionary` 与 `use-scroll-animate` 同时成为 npm `latest`。下面是 9.1 → 10.0 的计划，每个版本一个主题 + 一组新组件，9.9 负责 10.0 的弃用与迁移工具。
 
-- ✅ **v8.1** — 节日特效包：烟花、新春（灯笼、福字、鞭炮）、圣诞飘雪、万圣节；新组件 节日横幅、红包。
-- ✅ **v8.2** — 复古风：像素化、CRT 显示器、VHS 噪点、Y2K；新组件 复古按钮、终端窗口。
-- ✅ **v8.3** — 自然有机：水波涟漪、藤蔓生长、花朵绽放；新组件 有机卡片、液态导航。
-- ✅ **v8.4** — 赛博 / 科幻：HUD 线框、扫描线、全息投影；新组件 HUD 面板、雷达扫描。
-- ✅ **v8.5** — 纸张与手绘：折纸、铅笔素描、水彩晕染；新组件 便利贴墙、手绘图表。
-- ✅ **v8.6** — 霓虹 / 玻璃 / 新拟态主题系统；新组件 主题切换器。
-- ✅ **v8.7** — 手势 3.0：多点触控、陀螺仪；新组件 陀螺仪 3D 卡片。
-- ✅ **v8.8** — XR / 空间界面：WebXR 预览、空间卡片；新组件 全景查看器。
-- **v8.9** — 9.0 预备：9.0 弃用警告、`upgrading-9.md` 与 `usa-codemod-9`；低代码组件导出。
-- **v9.0** — 声明式动效 DSL（用一段文本描述完整动效）、插件市场正式版；移除 8.9 弃用项；npm `latest`。
-
-之后的方向（9.1 → 10.0）：电影化叙事 2.0、Lottie / Rive 导入、生成艺术 2.0、视频动效、无障碍动效 2.0、性能 3.0（OffscreenCanvas / Worker）、设计工具集成、原生 2.0；10.0 目标是零依赖核心 < 10 KB、所有特效插件化、默认 WebGPU。
+- **v9.1** — 电影化叙事 2.0：镜头语言（推拉摇移、景深切换、转场）；新组件 章节导航。
+- **v9.2** — Lottie / Rive 导入（JSON → 动效时间线）；新组件 动画图标集。
+- **v9.3** — 生成艺术 2.0：风格化着色器；新组件 背景生成器。
+- **v9.4** — 视频动效：滚动驱动视频、帧序列；新组件 视频卡片、英雄视频。
+- **v9.5** — 无障碍动效 2.0：更细的动效偏好分级；新组件 动效偏好面板。
+- **v9.6** — 性能 3.0：OffscreenCanvas、Worker 渲染；新组件 性能监视器。
+- **v9.7** — 设计工具集成：Figma 插件脚手架、Framer 导出。
+- **v9.8** — 原生 2.0：React Native / Flutter 组件示例。
+- **v9.9** — 10.0 预备：10.0 弃用警告、`upgrading-10.md` 与 `usa-codemod-10`。
+- **v10.0** — 全新架构：零依赖核心 < 10 KB、所有特效插件化、默认 WebGPU；npm `latest`。

package/docs/components.md

@@ -453,18 +453,18 @@ bindGesture(dial, 'twist', ({ direction }) => step(direction === 'cw' ? 1 : -1))
 ### v5.8 Theme packs & micro-interactions (`components/effects`)
 
 ```html
-<usa-theme name="glass">
+<usa-motion-theme name="glass">
   <div class="usa-surface">
     <button data-theme-fx="click">Tap</button>
     <usa-fx effect="like-heart" trigger="click"><button aria-pressed="false">♥ <span data-count="12">12</span></button></usa-fx>
     <usa-fx effect="copy-success" trigger="click"><button data-copy="npm i motionary">Copy</button></usa-fx>
   </div>
-</usa-theme>
+</usa-motion-theme>
 ```
 ```js
-import { applyTheme, themeCss, playEffect, registerAllEffects } from 'motionary/components/effects';
+import { applyMotionTheme, themeCss, playEffect, registerAllEffects } from 'motionary/components/effects';
 registerAllEffects();
-const undo = applyTheme('neon');          // whole page: design + motion tokens + data-usa-theme
+const undo = applyMotionTheme('neon');          // whole page: design + motion tokens + data-usa-theme
 const css = themeCss('paper', ':root');   // static CSS for SSR
 playEffect(passwordToggle, 'password-reveal');
 ```
@@ -1131,6 +1131,42 @@ pano.addEventListener('usa:look', (e) => console.log(e.detail.yaw));
 - `<usa-spatial-card>`: `active`; `usa:focus-depth`.
 - Spatial: `portal-open` (`color`) · `orbit-in` (`from`) · `spatial-float` · `depth-pop`; `yawToOffset(yaw, width)`, `xrSupport()`.
 
+### v8.9 Low-code export: `exportComponent()`, `<usa-code-export>`, `<usa-prop-panel>` (`components/widgets`)
+
+```html
+<usa-star-rating id="r" value="3"></usa-star-rating>
+<usa-prop-panel for="#r" props="value:number:0:5, icon:select:star|heart, readonly:boolean"></usa-prop-panel>
+<usa-code-export for="#r" formats="html,react,vue,json"></usa-code-export>
+```
+```js
+import { defineWidgets, exportComponent, describeComponent } from 'motionary/components/widgets';
+defineWidgets();
+console.log(exportComponent(document.querySelector('#r'), 'react'));
+```
+- `<usa-code-export for formats>`: `format`, `code`, `copy()`; `usa:copy` { format, ok }.
+- `<usa-prop-panel for props label>`: `props`, `reset()`; `usa:prop` { name, value }; `parseProps(str)`.
+- 9.0 prep: `applyMotionTheme` / `MOTION_THEMES` / `MOTION_THEME_NAMES` / `<usa-motion-theme>` are deprecated → `applyMotionTheme` / `MOTION_THEMES` / `MOTION_THEME_NAMES` / `<usa-motion-theme>` (`npx usa-codemod-9 --write src`, see docs/upgrading-9.md).
+
+### v9.0 Declarative motion DSL (`motionary/dsl`) + plugin marketplace (`motionary/marketplace`): `<usa-motion>`, `<usa-plugin-store>`
+
+```html
+<section data-motion="enter: fade-up 600ms ease-out stagger 80ms; hover: pop">
+  <div class="card">One</div><div class="card">Two</div>
+</section>
+<usa-motion rules="click: confetti count=40"><button>Celebrate</button></usa-motion>
+
+<usa-plugin-store query="neon"></usa-plugin-store>
+```
+```js
+import { applyMotion, parseMotion } from 'motionary/dsl';
+import { searchPlugins, installPlugin } from 'motionary/marketplace';
+const { errors } = applyMotion(document, { observe: true });
+await installPlugin(searchPlugins('retro')[0], { load: () => import('motionary/fx/retro') });
+```
+- DSL: `trigger: effect [600ms] [ease-out] [delay 100ms] [stagger 80ms] [once] [key=value…]`, rules separated by `;`.
+- `<usa-motion rules>`: `parsed`, `errors`; `usa:motion-error` { message }.
+- `<usa-plugin-store query label>`: `plugins`, `loader`, `search(q)`, `install(name)`; `usa:install` { name, effects }, `usa:install-error`.
+
 ## Frameworks
 
 Custom elements work in every framework. Register once (e.g. in your entry file), then use the tags.

package/docs/deprecations.md

@@ -1,5 +1,9 @@
 # Deprecations
 
+## Deprecated in 8.9, removed in 9.0 (released)
+
+See [upgrading-9.md](./upgrading-9.md) — the 5.8 motion-theme names `applyTheme()`, `THEMES`, `THEME_NAMES`, `<usa-theme>` / `defineTheme()` (use `applyMotionTheme()`, `MOTION_THEMES`, `MOTION_THEME_NAMES`, `<usa-motion-theme>` / `defineMotionTheme()`; same behaviour). Run `npx usa-codemod-9 --write src`.
+
 ## Deprecated in 7.9, removed in 8.0 (released)
 
 See [upgrading-8.md](./upgrading-8.md) — `<usa-rating>` / `defineRating()` (use `<usa-star-rating>` / `defineStarRating()`; same `value`, `max`, `readonly`, `label`, `name`; `icon="♥"` → `icon="heart"`). Run `npx usa-codemod-8 --write src`.

package/docs/upgrading-9.md

@@ -0,0 +1,37 @@
+# Upgrading to 9.0
+
+9.0.0 is released. 8.9 **warned once in the console** for everything below, and a codemod rewrites it:
+
+```sh
+npx usa-codemod-9 src            # dry run: lists every change (and what needs a manual edit)
+npx usa-codemod-9 --write src    # apply
+```
+
+## Removed in 9.0 (deprecated in 8.9)
+
+8.6 added *surface* themes (`applySurfaceTheme`, `SURFACE_THEMES`, `data-usa-surface`). To keep them apart from the 5.8 *motion* themes, the 5.8 names get a `Motion` prefix:
+
+| 8.x | 9.0 | Codemod |
+|---|---|---|
+| `applyTheme(name, root?)` | `applyMotionTheme(name, root?)` (same signature, returns the undo) | ✅ |
+| `THEMES` / `THEME_NAMES` | `MOTION_THEMES` / `MOTION_THEME_NAMES` | ✅ |
+| `<usa-theme name="neon">` | `<usa-motion-theme name="neon">` (same `data-theme-fx` bindings) | ✅ tags |
+| `defineTheme()` | `defineMotionTheme()` | ⚠️ manual |
+
+`document.createElement('usa-theme')` and CSS selectors on `usa-theme` are reported for a manual edit. `themeVars`, `themeCss`, `themePreset`, `playThemeEffect`, `THEME_ROLES` and the `data-usa-theme` attribute are unchanged.
+
+## New in 9.0
+
+- **Declarative motion DSL — `motionary/dsl`.** Describe motion as one string: `data-motion="enter: fade-up 600ms ease-out stagger 80ms; hover: pop; click: confetti count=40"` (triggers `enter` · `click` · `hover` · `load` · `loop` · `manual`; modifiers: duration, `delay`, `stagger`, easing, `once`, `key=value` options). `applyMotion(root, { observe })` binds every `[data-motion]`, `bindMotion(el, rules)` one element, `parseMotion()` / `serializeMotion()` round-trip, `motion\`…\`` tagged template, `createComponent(json)` builds markup from the 8.9 component JSON. `<usa-motion rules="…">` is the same as an element.
+- **Plugin marketplace GA — `motionary/marketplace`** (also `motionary/components/marketplace`, which keeps the 6.9 manifest API): `MARKETPLACE` (first-party catalogue), `searchPlugins()`, `installPlugin(listing | url, { load })`, `installedPlugins()`, `fetchMarketplace(url)` for third-party indexes; `<usa-plugin-store>` puts search + one-click install on a page.
+- `motionary` and the `use-scroll-animate` alias are both published with the npm `latest` tag.
+
+## Behaviour
+
+- Nothing else changes: every 8.x widget, effect pack and engine API stays the same; `data-usa-theme`, `themeVars`, `themeCss`, `themePreset`, `playThemeEffect` and `THEME_ROLES` are unchanged.
+
+## New in 8.9 (before the break)
+
+- **Low-code export.** `exportComponent(el, 'html' | 'react' | 'vue' | 'json')` turns any live, configured component into copy-paste code (runtime parts stripped); `describeComponent(el)` gives the portable JSON. `<usa-code-export>` shows it in tabs with a copy button and follows attribute changes; `<usa-prop-panel for="#el" props="…">` edits a live component's attributes with typed fields.
+
+See the [CHANGELOG](../CHANGELOG.md) for the full list.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-scroll-animate",
-  "version": "8.8.0",
+  "version": "9.0.0",
   "description": "Compatibility alias of motionary (same build). The project was renamed to Motionary — install `motionary` instead. Motionary (formerly use-scroll-animate): dependency-free scroll animations + 94 animated Web Components — 214 scroll-reveal presets, card/click/button morphs, physics, page transitions, generative & sound-reactive backgrounds, cursor/gesture effects, themes, micro-interactions, <usa-player>, WebGL. React, Vue, Svelte, Solid, Angular or plain HTML.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -98,6 +98,26 @@
         "default": "./dist/components/engine.cjs"
       }
     },
+    "./dsl": {
+      "import": {
+        "types": "./dist/components/dsl.d.ts",
+        "default": "./dist/components/dsl.js"
+      },
+      "require": {
+        "types": "./dist/components/dsl.d.cts",
+        "default": "./dist/components/dsl.cjs"
+      }
+    },
+    "./marketplace": {
+      "import": {
+        "types": "./dist/components/marketplace.d.ts",
+        "default": "./dist/components/marketplace.js"
+      },
+      "require": {
+        "types": "./dist/components/marketplace.d.cts",
+        "default": "./dist/components/marketplace.cjs"
+      }
+    },
     "./fx": {
       "import": {
         "types": "./dist/components/fx2.d.ts",
@@ -968,6 +988,16 @@
         "default": "./dist/components/fx-spatial.cjs"
       }
     },
+    "./components/dsl": {
+      "import": {
+        "types": "./dist/components/dsl.d.ts",
+        "default": "./dist/components/dsl.js"
+      },
+      "require": {
+        "types": "./dist/components/dsl.d.cts",
+        "default": "./dist/components/dsl.cjs"
+      }
+    },
     "./components/lite": {
       "import": {
         "types": "./dist/components/lite.d.ts",
@@ -1101,6 +1131,7 @@
     "usa-codemod-5": "./bin/usa-codemod-5.mjs",
     "usa-codemod-6": "./bin/usa-codemod-6.mjs",
     "usa-codemod-7": "./bin/usa-codemod-7.mjs",
-    "usa-codemod-8": "./bin/usa-codemod-8.mjs"
+    "usa-codemod-8": "./bin/usa-codemod-8.mjs",
+    "usa-codemod-9": "./bin/usa-codemod-9.mjs"
   }
 }