use-scroll-animate 3.7.0 → 3.9.0

package/docs/hybrid-apps.md

@@ -0,0 +1,130 @@
+# Hybrid & desktop apps: MAUI, Flutter WebView, Electron, Tauri
+
+`<usa-*>` components are plain Web Components (Custom Elements + CSS + Web Animations): anything that hosts a modern web view can run them, with **no bundler** if you want — copy `dist/components.umd.js` (and optionally `dist/components.css`) next to your HTML. For WinUI 3 / WPF / WinForms with WebView2 see [windows-apps.md](./windows-apps.md).
+
+General rules for every host:
+
+- **Load locally, not from a CDN**, so the app works offline and passes store review: ship `components.umd.js` as an asset and reference it with a relative URL.
+- **Strict CSP is fine**: styles are adopted as constructable stylesheets. If you load `components.css` yourself, call `configureComponents({ injectStyles: false })`.
+- **Reduced motion follows the OS** (`prefers-reduced-motion`) inside every web view listed here. To mirror an in-app setting, call `setMotionIntensity('off' | 'low' | 'normal' | 'high')` (or `configureComponents({ reducedMotion: 'reduce' })`) from the native side.
+- **Performance**: canvas / WebGL effects (`<usa-shader>`, `<usa-liquid>`, backgrounds) render only while visible and cap DPR at 2; they fall back to CSS where WebGL is unavailable (some Android web views).
+- **Native ↔ web**: listen to `usa:*` events in JS and forward them over the host bridge (examples below).
+
+## .NET MAUI
+
+MAUI 9+ has `HybridWebView` (raw HTML + JS bridge); `BlazorWebView` also works (Razor renders the tags; enable the elements in `wwwroot/index.html`).
+
+```text
+Resources/Raw/wwwroot/
+  index.html
+  components.umd.js     ← copied from node_modules/use-scroll-animate/dist/
+```
+
+```xml
+<!-- MainPage.xaml -->
+<HybridWebView x:Name="Web" DefaultFile="index.html" RawMessageReceived="OnMessage" />
+```
+
+```html
+<!-- Resources/Raw/wwwroot/index.html -->
+<script src="components.umd.js"></script>
+<script src="_framework/hybridwebview.js"></script>
+<usa-toggle id="t"></usa-toggle>
+<script>
+  document.getElementById('t').addEventListener('usa:change', (e) =>
+    window.HybridWebView.SendRawMessage(JSON.stringify({ checked: e.detail.checked })));
+</script>
+```
+
+```csharp
+void OnMessage(object s, HybridWebViewRawMessageReceivedEventArgs e) => Debug.WriteLine(e.Message);
+// native → web
+await Web.EvaluateJavaScriptAsync("UsaComponents.setMotionIntensity('low')");
+```
+
+Notes: Android uses the system WebView (Chromium) — keep it updated; iOS / Mac Catalyst use WKWebView (Safari engine), where `linear()` spring easings fall back to cubic-bezier automatically.
+
+## Flutter (webview_flutter / flutter_inappwebview)
+
+```yaml
+# pubspec.yaml
+dependencies:
+  webview_flutter: ^4.10.0
+flutter:
+  assets:
+    - assets/web/index.html
+    - assets/web/components.umd.js
+```
+
+```dart
+final controller = WebViewController()
+  ..setJavaScriptMode(JavaScriptMode.unrestricted)
+  ..addJavaScriptChannel('Usa', onMessageReceived: (m) => debugPrint(m.message))
+  ..loadFlutterAsset('assets/web/index.html');
+
+// native → web (e.g. follow the platform's "reduce motion" setting)
+final reduce = MediaQuery.of(context).disableAnimations;
+controller.runJavaScript("UsaComponents.setMotionIntensity('${reduce ? 'off' : 'normal'}')");
+```
+
+```html
+<!-- assets/web/index.html -->
+<script src="components.umd.js"></script>
+<usa-like id="like"></usa-like>
+<script>
+  document.getElementById('like').addEventListener('usa:change', (e) => Usa.postMessage(JSON.stringify(e.detail)));
+</script>
+```
+
+`loadFlutterAsset` serves from a `file://`-like origin; ES-module builds (`components.js`) need an HTTP origin, so prefer the UMD file here. On Flutter Web you can use the components directly in `web/index.html` via `HtmlElementView`.
+
+## Electron
+
+The renderer is Chromium — use the npm package with your bundler, or the UMD file without one.
+
+```js
+// renderer.js (bundled)
+import { defineComponents, configureComponents } from 'use-scroll-animate/components';
+configureComponents({ injectStyles: true });
+defineComponents();
+```
+
+```js
+// main.js — keep contextIsolation on; expose only what you need
+new BrowserWindow({ webPreferences: { preload: path.join(__dirname, 'preload.js'), contextIsolation: true, sandbox: true } });
+```
+
+```js
+// preload.js — forward component events to the main process
+const { contextBridge, ipcRenderer } = require('electron');
+contextBridge.exposeInMainWorld('usaBridge', { send: (type, detail) => ipcRenderer.send('usa', type, detail) });
+```
+
+Imports are SSR-safe (no `window` access at import time), so the same modules can be imported in preload scripts.
+
+## Tauri (v2)
+
+```js
+// src/main.js (Vite)
+import { defineComponents } from 'use-scroll-animate/components';
+import { invoke } from '@tauri-apps/api/core';
+defineComponents();
+document.querySelector('usa-toggle').addEventListener('usa:change', (e) => invoke('set_setting', { on: e.detail.checked }));
+```
+
+```json
+// tauri.conf.json — a strict CSP works (constructable stylesheets)
+{ "app": { "security": { "csp": "default-src 'self'; style-src 'self'; script-src 'self'" } } }
+```
+
+Tauri uses WebView2 on Windows, WKWebView on macOS / iOS and WebKitGTK on Linux. WebKitGTK may disable WebGL on some drivers: WebGL components then set `data-fallback="webgl"` and show their CSS fallback.
+
+## Framework wrappers
+
+| Framework | Entry | What it gives you |
+|---|---|---|
+| React | `use-scroll-animate/components/react` | `createUsaComponents(React)` typed wrappers |
+| Vue | `use-scroll-animate/components/vue` | `UsaPlugin`, `isUsaElement` |
+| Svelte | `use-scroll-animate/components/svelte` | `use:usa={{ props, on }}` action, `defineUsa()` |
+| Solid | `use-scroll-animate/components/solid` | `use:usa` directive, `defineUsa()`, JSX types |
+| Angular | `use-scroll-animate/components/angular` | `usaInitializer()` for `APP_INITIALIZER`, `usaDetail()`; use `CUSTOM_ELEMENTS_SCHEMA` |

package/docs/upgrading-4.md

@@ -0,0 +1,65 @@
+# Upgrading to 4.0
+
+4.0 removes the three APIs that 3.9 deprecated, each replaced by a more capable one added during 3.x. **Run your app on 3.9 first**: it logs one console warning (`[use-scroll-animate] … deprecated …`) for every removed API you still use.
+
+| Removed in 4.0 | Use instead | Since |
+|---|---|---|
+| `sequence(steps, opts)` (`use-scroll-animate`) | `timeline()` — `use-scroll-animate` (re-exported in 4.0) or `use-scroll-animate/components/timeline` | 3.1 |
+| `connectedAnimation(from, to)` (`components/transitions`) | `sharedTransition(update)` with `data-shared="id"` (`components/layout`) | 3.6 |
+| `<usa-flip-list>` / `defineFlipList()` (`components/transitions`) | `<usa-auto-animate>` / `autoAnimate(el)` (`components/layout`) | 3.6 |
+
+## `sequence()` → `timeline()`
+
+```js
+// 3.x
+sequence([
+  { target: '.title', animation: 'fade-in-up' },
+  { target: '.subtitle', animation: 'blur-in', gap: -300 },
+  { target: '.card', animation: 'scale-up', stagger: 80 },
+], { trigger: '.hero' });
+
+// 4.0
+import { timeline } from 'use-scroll-animate';
+const tl = timeline({ defaults: { duration: 600 } })
+  .to('.title', 'fade-up')
+  .to('.subtitle', 'blur', { at: '-=300' })   // gap: -300  →  at: '-=300'
+  .to('.card', 'scale', { stagger: 80 });
+// trigger: '.hero'  →  play when it enters the view (or scrub it with scroll)
+new IntersectionObserver(([e], io) => e.isIntersecting && (io.disconnect(), tl.play())).observe(document.querySelector('.hero'));
+```
+
+Declaratively: wrap the section in `<usa-timeline>` and mark steps with `data-tl="fade-up"`, `data-at="-=300"`.
+
+`gap: n` → `at: '+=n'` (negative → `'-=n'`), `at: ms` stays `at: ms`. Engine presets map to timeline presets: `fade-in-up` → `fade-up`, `blur-in` → `blur`, `scale-up` → `scale`, or pass keyframes.
+
+## `connectedAnimation()` → `sharedTransition()`
+
+```js
+// 3.x
+detail.hidden = false;
+connectedAnimation(thumbnail, detail);
+
+// 4.0 — give both ends the same data-shared id
+// <img data-shared="photo-7"> in the grid and in the detail view
+import { sharedTransition } from 'use-scroll-animate/components/layout';
+await sharedTransition(() => { grid.hidden = true; detail.hidden = false; });
+```
+
+Uses the View Transitions API where available (FLIP fallback elsewhere) and morphs any number of shared elements at once.
+
+## `<usa-flip-list>` → `<usa-auto-animate>`
+
+```html
+<!-- 3.x -->
+<usa-flip-list><li>…</li></usa-flip-list>
+<!-- 4.0 -->
+<usa-auto-animate><li>…</li></usa-auto-animate>
+```
+
+`<usa-auto-animate>` also animates additions and removals, and size changes. Imperatively: `autoAnimate(ul)`.
+
+## Other changes in 4.0
+
+- `timeline` is exported from the root entry (`import { timeline } from 'use-scroll-animate'`) in addition to `components/timeline`.
+- CDN snippets in docs and the showcase use `use-scroll-animate@4`.
+- npm `latest` moves to 4.0.0. 3.x stays available as `use-scroll-animate@3`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-scroll-animate",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "description": "A lightweight, high-performance, dependency-free scroll animation library and animated UI components (Web Components) for the web and Windows web-view apps.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -248,6 +248,16 @@
         "default": "./dist/components/layout.cjs"
       }
     },
+    "./components/packs": {
+      "import": {
+        "types": "./dist/components/packs.d.ts",
+        "default": "./dist/components/packs.js"
+      },
+      "require": {
+        "types": "./dist/components/packs.d.cts",
+        "default": "./dist/components/packs.cjs"
+      }
+    },
     "./components/react": {
       "import": {
         "types": "./dist/components/react.d.ts",
@@ -268,6 +278,36 @@
         "default": "./dist/components/vue.cjs"
       }
     },
+    "./components/svelte": {
+      "import": {
+        "types": "./dist/components/svelte.d.ts",
+        "default": "./dist/components/svelte.js"
+      },
+      "require": {
+        "types": "./dist/components/svelte.d.cts",
+        "default": "./dist/components/svelte.cjs"
+      }
+    },
+    "./components/solid": {
+      "import": {
+        "types": "./dist/components/solid.d.ts",
+        "default": "./dist/components/solid.js"
+      },
+      "require": {
+        "types": "./dist/components/solid.d.cts",
+        "default": "./dist/components/solid.cjs"
+      }
+    },
+    "./components/angular": {
+      "import": {
+        "types": "./dist/components/angular.d.ts",
+        "default": "./dist/components/angular.js"
+      },
+      "require": {
+        "types": "./dist/components/angular.d.cts",
+        "default": "./dist/components/angular.cjs"
+      }
+    },
     "./components/jsx": {
       "import": {
         "types": "./dist/components/jsx.d.ts",
@@ -306,6 +346,7 @@
     "./components/webgl.css": "./dist/components/webgl.css",
     "./components/depth.css": "./dist/components/depth.css",
     "./components/layout.css": "./dist/components/layout.css",
+    "./components/packs.css": "./dist/components/packs.css",
     "./package.json": "./package.json"
   },
   "files": [
@@ -326,7 +367,7 @@
     "typecheck": "tsc --noEmit -p .",
     "test": "vitest run",
     "check:exports": "node scripts/check-exports.mjs",
-    "lint:package": "publint && attw --pack . --profile node16 --exclude-entrypoints ./components.css ./components/reveal.css ./components/text.css ./components/interaction.css ./components/feedback.css ./components/background.css ./components/transitions.css ./components/physics.css ./components/cards.css ./components/click.css ./components/ui.css ./components/page.css ./components/timeline.css ./components/gesture.css ./components/svg.css ./components/webgl.css ./components/depth.css ./components/layout.css",
+    "lint:package": "publint && attw --pack . --profile node16 --exclude-entrypoints ./components.css ./components/reveal.css ./components/text.css ./components/interaction.css ./components/feedback.css ./components/background.css ./components/transitions.css ./components/physics.css ./components/cards.css ./components/click.css ./components/ui.css ./components/page.css ./components/timeline.css ./components/gesture.css ./components/svg.css ./components/webgl.css ./components/depth.css ./components/layout.css ./components/packs.css",
     "size": "node scripts/size.mjs",
     "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run check:exports",
     "size:check": "node scripts/size.mjs --check",