use-scroll-animate 3.6.0 → 3.8.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.8.0] - 2026-10-07
+
+### Added
+- **Svelte** — `use-scroll-animate/components/svelte`: `use:usa={{ props, on }}` action (sets DOM properties, binds `usa:*` events with update / destroy; works in Svelte 3, 4 and 5) and `defineUsa(categories?)` (client-only, SvelteKit-safe).
+- **Solid** — `use-scroll-animate/components/solid`: `use:usa` directive (`refresh()` / `destroy()`), `defineUsa()`, `SolidUsaIntrinsicElements` JSX types; native `prop:` / `on:usa:change` documented.
+- **Angular** — `use-scroll-animate/components/angular`: `usaInitializer(categories?)` for `APP_INITIALIZER`, `defineUsa()`, `usaDetail($event)`; `CUSTOM_ELEMENTS_SCHEMA` + `[prop]` / `(usa:event)` binding documented. No `@angular/*` import.
+- Shared framework-neutral `bindUsa(el, { props, on })` / `usaEventName()` (exported from all three entries).
+- **Docs**: new [docs/hybrid-apps.md](./docs/hybrid-apps.md) — .NET MAUI (`HybridWebView`, `BlazorWebView`), Flutter (`webview_flutter` / `flutter_inappwebview`, `JavaScriptChannel`), Electron (context isolation, preload bridge), Tauri v2 (strict CSP, `invoke`), with native ↔ web event bridges and OS reduced-motion mirroring; `docs/frameworks-ssr.md` gains Svelte, Solid and Angular sections.
+
+## [3.7.0] - 2026-10-07
+
+### Added
+- **Visual playground** — [`showcase/playground.html`](./showcase/playground.html) (no build, dogfoods `dist/components.js` with a CDN fallback):
+  - **Compose**: stack effect layers around a card, button, heading or image — scroll reveal, 3D tilt, magnetic, spring, mask reveal, depth, swipeable, click ripple, shader background, glitch and gradient text — and reorder or remove them.
+  - **Tweak**: every attribute has a live control (selects, sliders, toggles); the preview re-renders instantly, with a Replay button.
+  - **Export**: HTML (CDN, no build), ES module (per-category imports with the right `define*Components()`), React (JSX via `components/jsx` types) and Vue (`isCustomElement` hint) code, copy to clipboard.
+  - **Share**: the composition is encoded in the URL hash (`encodeState()` / `decodeState()`), so a link reproduces it.
+  - English / 中文, keyboard accessible controls, honours `prefers-reduced-motion` (shows a notice; effects render their final state).
+- Pure, tested playground core in `showcase/playground-core.js` (`PLAYGROUND_EFFECTS`, `composeMarkup()`, `playgroundSnippets()`); the component gallery links to the playground.
+
 ## [3.6.0] - 2026-10-07
 
 ### Added

package/README.md

@@ -10,7 +10,7 @@
 
 [English](./README.md) | [简体中文](./README_zh.md) | [日本語](./README_ja.md)
 
-**[✨ Live showcase — every effect, live, with copy-paste code](https://harrisoncn.github.io/use-scroll-animate/)** · **[🧩 Component gallery](https://harrisoncn.github.io/use-scroll-animate/showcase/components.html)**
+**[✨ Live showcase — every effect, live, with copy-paste code](https://harrisoncn.github.io/use-scroll-animate/)** · **[🧩 Component gallery](https://harrisoncn.github.io/use-scroll-animate/showcase/components.html)** · **[🎛 Playground](https://harrisoncn.github.io/use-scroll-animate/showcase/playground.html)**
 
 </div>
 

package/dist/chunks/bind-B_CTL6Qn.js

@@ -0,0 +1,22 @@
+/** Normalise an event key: `change` → `usa:change`, `usa:change` stays. */
+const usaEventName = (k) => (k.includes(':') ? k : `usa:${k}`);
+/** Bind properties and `usa:*` listeners to an element; returns `{ update, destroy }`. */
+function bindUsa(el, binding = {}) {
+    let current = [];
+    const apply = (b) => {
+        current.forEach(([n, f]) => el.removeEventListener(n, f));
+        current = Object.entries(b.on || {}).map(([k, f]) => [usaEventName(k), f]);
+        current.forEach(([n, f]) => el.addEventListener(n, f));
+        for (const [k, v] of Object.entries(b.props || {}))
+            if (el[k] !== v)
+                el[k] = v;
+    };
+    apply(binding);
+    return {
+        update: apply,
+        destroy: () => current.forEach(([n, f]) => el.removeEventListener(n, f)),
+    };
+}
+
+export { bindUsa as b, usaEventName as u };
+//# sourceMappingURL=bind-B_CTL6Qn.js.map

package/dist/chunks/bind-B_CTL6Qn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-B_CTL6Qn.js","sources":["../../src/components/frameworks/bind.ts"],"sourcesContent":["/**\n * Framework-neutral binding for `<usa-*>` elements (v3.8): set DOM\n * **properties** and listen to `usa:*` events, with update / destroy — the\n * shape Svelte actions, Solid directives and Angular directives all share.\n */\nexport interface UsaBinding {\n  /** DOM properties to set (`checked`, `value`, `open`, `index`…). */\n  props?: Record<string, unknown>;\n  /** Event handlers by name; `change` is shorthand for `usa:change`. */\n  on?: Record<string, (e: CustomEvent) => void>;\n}\n\n/** Normalise an event key: `change` → `usa:change`, `usa:change` stays. */\nexport const usaEventName = (k: string): string => (k.includes(':') ? k : `usa:${k}`);\n\n/** Bind properties and `usa:*` listeners to an element; returns `{ update, destroy }`. */\nexport function bindUsa(el: HTMLElement, binding: UsaBinding = {}): { update(b: UsaBinding): void; destroy(): void } {\n  let current: [string, EventListener][] = [];\n  const apply = (b: UsaBinding) => {\n    current.forEach(([n, f]) => el.removeEventListener(n, f));\n    current = Object.entries(b.on || {}).map(([k, f]) => [usaEventName(k), f as unknown as EventListener]);\n    current.forEach(([n, f]) => el.addEventListener(n, f));\n    for (const [k, v] of Object.entries(b.props || {})) if ((el as any)[k] !== v) (el as any)[k] = v;\n  };\n  apply(binding);\n  return {\n    update: apply,\n    destroy: () => current.forEach(([n, f]) => el.removeEventListener(n, f)),\n  };\n}\n"],"names":[],"mappings":"AAYA;AACO,MAAM,YAAY,GAAG,CAAC,CAAS,MAAc,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAA,IAAA,EAAO,CAAC,CAAA,CAAE;AAEpF;SACgB,OAAO,CAAC,EAAe,EAAE,UAAsB,EAAE,EAAA;IAC/D,IAAI,OAAO,GAA8B,EAAE;AAC3C,IAAA,MAAM,KAAK,GAAG,CAAC,CAAa,KAAI;QAC9B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACzD,QAAA,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAA6B,CAAC,CAAC;QACtG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACtD,QAAA,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;AAAE,YAAA,IAAK,EAAU,CAAC,CAAC,CAAC,KAAK,CAAC;AAAG,gBAAA,EAAU,CAAC,CAAC,CAAC,GAAG,CAAC;AAClG,IAAA,CAAC;IACD,KAAK,CAAC,OAAO,CAAC;IACd,OAAO;AACL,QAAA,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;KACzE;AACH;;;;"}

package/dist/chunks/bind-Ui43-n2d.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+/** Normalise an event key: `change` → `usa:change`, `usa:change` stays. */
+const usaEventName = (k) => (k.includes(':') ? k : `usa:${k}`);
+/** Bind properties and `usa:*` listeners to an element; returns `{ update, destroy }`. */
+function bindUsa(el, binding = {}) {
+    let current = [];
+    const apply = (b) => {
+        current.forEach(([n, f]) => el.removeEventListener(n, f));
+        current = Object.entries(b.on || {}).map(([k, f]) => [usaEventName(k), f]);
+        current.forEach(([n, f]) => el.addEventListener(n, f));
+        for (const [k, v] of Object.entries(b.props || {}))
+            if (el[k] !== v)
+                el[k] = v;
+    };
+    apply(binding);
+    return {
+        update: apply,
+        destroy: () => current.forEach(([n, f]) => el.removeEventListener(n, f)),
+    };
+}
+
+exports.bindUsa = bindUsa;
+exports.usaEventName = usaEventName;
+//# sourceMappingURL=bind-Ui43-n2d.cjs.map

package/dist/chunks/bind-Ui43-n2d.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-Ui43-n2d.cjs","sources":["../../src/components/frameworks/bind.ts"],"sourcesContent":["/**\n * Framework-neutral binding for `<usa-*>` elements (v3.8): set DOM\n * **properties** and listen to `usa:*` events, with update / destroy — the\n * shape Svelte actions, Solid directives and Angular directives all share.\n */\nexport interface UsaBinding {\n  /** DOM properties to set (`checked`, `value`, `open`, `index`…). */\n  props?: Record<string, unknown>;\n  /** Event handlers by name; `change` is shorthand for `usa:change`. */\n  on?: Record<string, (e: CustomEvent) => void>;\n}\n\n/** Normalise an event key: `change` → `usa:change`, `usa:change` stays. */\nexport const usaEventName = (k: string): string => (k.includes(':') ? k : `usa:${k}`);\n\n/** Bind properties and `usa:*` listeners to an element; returns `{ update, destroy }`. */\nexport function bindUsa(el: HTMLElement, binding: UsaBinding = {}): { update(b: UsaBinding): void; destroy(): void } {\n  let current: [string, EventListener][] = [];\n  const apply = (b: UsaBinding) => {\n    current.forEach(([n, f]) => el.removeEventListener(n, f));\n    current = Object.entries(b.on || {}).map(([k, f]) => [usaEventName(k), f as unknown as EventListener]);\n    current.forEach(([n, f]) => el.addEventListener(n, f));\n    for (const [k, v] of Object.entries(b.props || {})) if ((el as any)[k] !== v) (el as any)[k] = v;\n  };\n  apply(binding);\n  return {\n    update: apply,\n    destroy: () => current.forEach(([n, f]) => el.removeEventListener(n, f)),\n  };\n}\n"],"names":[],"mappings":";;AAYA;AACO,MAAM,YAAY,GAAG,CAAC,CAAS,MAAc,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAA,IAAA,EAAO,CAAC,CAAA,CAAE;AAEpF;SACgB,OAAO,CAAC,EAAe,EAAE,UAAsB,EAAE,EAAA;IAC/D,IAAI,OAAO,GAA8B,EAAE;AAC3C,IAAA,MAAM,KAAK,GAAG,CAAC,CAAa,KAAI;QAC9B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACzD,QAAA,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAA6B,CAAC,CAAC;QACtG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACtD,QAAA,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;AAAE,YAAA,IAAK,EAAU,CAAC,CAAC,CAAC,KAAK,CAAC;AAAG,gBAAA,EAAU,CAAC,CAAC,CAAC,GAAG,CAAC;AAClG,IAAA,CAAC;IACD,KAAK,CAAC,OAAO,CAAC;IACd,OAAO;AACL,QAAA,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;KACzE;AACH;;;;;"}

package/dist/components/angular.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+var components = require('../components.cjs');
+var bind = require('../chunks/bind-Ui43-n2d.cjs');
+require('./reveal.cjs');
+require('../chunks/base-CXx7jZ-o.cjs');
+require('./text.cjs');
+require('./interaction.cjs');
+require('./feedback.cjs');
+require('./background.cjs');
+require('../chunks/variants-BNIrn4ch.cjs');
+require('./transitions.cjs');
+require('./physics.cjs');
+require('../chunks/spring-2OTnYCzm.cjs');
+require('./cards.cjs');
+require('./click.cjs');
+require('./ui.cjs');
+require('./page.cjs');
+require('./timeline.cjs');
+require('./gesture.cjs');
+require('../chunks/core-IaorbTdu.cjs');
+require('./svg.cjs');
+require('./webgl.cjs');
+require('./depth.cjs');
+require('./layout.cjs');
+require('../chunks/index-tags-wbuPiMR6.cjs');
+
+/**
+ * use-scroll-animate/components/angular — Angular integration (v3.8).
+ * Angular renders `<usa-*>` tags once the component (or NgModule) allows
+ * custom elements with `CUSTOM_ELEMENTS_SCHEMA`; property binding
+ * `[checked]="on"` and event binding `(usa:change)="…"` then work as is.
+ * This entry is framework-free (no `@angular/*` import):
+ *
+ * ```ts
+ * import { CUSTOM_ELEMENTS_SCHEMA, Component, APP_INITIALIZER } from '@angular/core';
+ * import { usaInitializer } from 'use-scroll-animate/components/angular';
+ *
+ * // app.config.ts
+ * providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer(['click', 'ui']) }]
+ *
+ * @Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ *   template: `<usa-toggle [checked]="on" (usa:change)="on = $any($event).detail.checked"></usa-toggle>` })
+ * ```
+ * `bindUsa(el, { props, on })` is available for directives that bind imperatively.
+ */
+/** `APP_INITIALIZER` factory: registers the elements in the browser (no-op during SSR). */
+function usaInitializer(categories) {
+    return () => () => {
+        if (typeof window !== 'undefined')
+            components.defineComponents(categories);
+    };
+}
+/** Register the elements directly (e.g. in `main.ts` before `bootstrapApplication`). */
+function defineUsa(categories) {
+    if (typeof window !== 'undefined')
+        components.defineComponents(categories);
+}
+/** Read `event.detail` from a `usa:*` event in a template handler: `(usa:change)="on = usaDetail($event).checked"`. */
+const usaDetail = (e) => e.detail;
+
+exports.bindUsa = bind.bindUsa;
+exports.usaEventName = bind.usaEventName;
+exports.defineUsa = defineUsa;
+exports.usaDetail = usaDetail;
+exports.usaInitializer = usaInitializer;
+//# sourceMappingURL=angular.cjs.map

package/dist/components/angular.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"angular.cjs","sources":["../../src/components/frameworks/angular.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/angular — Angular integration (v3.8).\n * Angular renders `<usa-*>` tags once the component (or NgModule) allows\n * custom elements with `CUSTOM_ELEMENTS_SCHEMA`; property binding\n * `[checked]=\"on\"` and event binding `(usa:change)=\"…\"` then work as is.\n * This entry is framework-free (no `@angular/*` import):\n *\n * ```ts\n * import { CUSTOM_ELEMENTS_SCHEMA, Component, APP_INITIALIZER } from '@angular/core';\n * import { usaInitializer } from 'use-scroll-animate/components/angular';\n *\n * // app.config.ts\n * providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer(['click', 'ui']) }]\n *\n * @Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],\n *   template: `<usa-toggle [checked]=\"on\" (usa:change)=\"on = $any($event).detail.checked\"></usa-toggle>` })\n * ```\n * `bindUsa(el, { props, on })` is available for directives that bind imperatively.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** `APP_INITIALIZER` factory: registers the elements in the browser (no-op during SSR). */\nexport function usaInitializer(categories?: ComponentCategory[]): () => () => void {\n  return () => () => {\n    if (typeof window !== 'undefined') defineComponents(categories);\n  };\n}\n\n/** Register the elements directly (e.g. in `main.ts` before `bootstrapApplication`). */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n\n/** Read `event.detail` from a `usa:*` event in a template handler: `(usa:change)=\"on = usaDetail($event).checked\"`. */\nexport const usaDetail = <T = any>(e: Event): T => (e as CustomEvent<T>).detail;\n"],"names":["defineComponents"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;AAkBG;AAMH;AACM,SAAU,cAAc,CAAC,UAAgC,EAAA;AAC7D,IAAA,OAAO,MAAM,MAAK;QAChB,IAAI,OAAO,MAAM,KAAK,WAAW;YAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE,IAAA,CAAC;AACH;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE;AAEA;AACO,MAAM,SAAS,GAAG,CAAU,CAAQ,KAAS,CAAoB,CAAC;;;;;;;;"}