use-scroll-animate 8.7.0 → 8.9.0

package/docs/ROADMAP.md

@@ -9,8 +9,8 @@
 - ✅ **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`；低代码组件导出。
+- ✅ **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。

package/docs/components.md

@@ -1108,6 +1108,45 @@ sticker.addEventListener('usa:transform', (e) => save(e.detail)); // { x, y, sca
 - `<usa-gesture-sticker min max label>`: `x`, `y`, `scale`, `angle`, `transformTo(state)`, `reset()`; `usa:transform`.
 - Gesture: `swipe-hint` (`direction`) · `pinch-hint` · `tilt-wobble` · `depth-in` (`stagger`, `data-depth`); `pinchScale`, `pinchAngle`, `orientationToTilt(beta, gamma, max?, rest?)`.
 
+### v8.8 XR / spatial: 360° panorama, spatial card (`components/widgets`) + spatial pack (`motionary/fx/spatial`)
+
+```html
+<usa-panorama src="pano-equirect.jpg" label="Lake at dawn" autorotate="6"></usa-panorama>
+<usa-spatial-card>
+  <h3 data-depth="2">Photos</h3><p data-depth="1">Spatial window</p>
+  <nav slot="ornament"><button>⟲</button><button>♡</button></nav>
+</usa-spatial-card>
+
+<usa-fx effect="portal-open" trigger="enter"><img src="world.jpg" alt=""></usa-fx>
+<usa-fx effect="spatial-float" trigger="loop"><div class="window">…</div></usa-fx>
+```
+```js
+import { defineWidgets } from 'motionary/components/widgets';
+import { registerSpatialPack, xrSupport } from 'motionary/fx/spatial';
+defineWidgets(); registerSpatialPack();
+if ((await xrSupport()) === 'immersive-vr') enterVR();
+pano.addEventListener('usa:look', (e) => console.log(e.detail.yaw));
+```
+- `<usa-panorama src autorotate label>`: `yaw`, `lookAt(deg)`; `usa:look`, `usa:xr`, `usa:xr-request`.
+- `<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: `applyTheme` / `THEMES` / `THEME_NAMES` / `<usa-theme>` are deprecated → `applyMotionTheme` / `MOTION_THEMES` / `MOTION_THEME_NAMES` / `<usa-motion-theme>` (`npx usa-codemod-9 --write src`, see docs/upgrading-9.md).
+
 ## 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
+
+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,27 @@
+# Upgrading to 9.0
+
+9.0.0 is the next major. 8.9 **warns 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 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.7.0",
+  "version": "8.9.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",
@@ -358,6 +358,16 @@
         "default": "./dist/components/fx-gesture.cjs"
       }
     },
+    "./fx/spatial": {
+      "import": {
+        "types": "./dist/components/fx-spatial.d.ts",
+        "default": "./dist/components/fx-spatial.js"
+      },
+      "require": {
+        "types": "./dist/components/fx-spatial.d.cts",
+        "default": "./dist/components/fx-spatial.cjs"
+      }
+    },
     "./components/reveal": {
       "import": {
         "types": "./dist/components/reveal.d.ts",
@@ -948,6 +958,16 @@
         "default": "./dist/components/fx-gesture.cjs"
       }
     },
+    "./components/fx-spatial": {
+      "import": {
+        "types": "./dist/components/fx-spatial.d.ts",
+        "default": "./dist/components/fx-spatial.js"
+      },
+      "require": {
+        "types": "./dist/components/fx-spatial.d.cts",
+        "default": "./dist/components/fx-spatial.cjs"
+      }
+    },
     "./components/lite": {
       "import": {
         "types": "./dist/components/lite.d.ts",
@@ -1081,6 +1101,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"
   }
 }