use-scroll-animate 3.6.0 → 3.8.0

package/dist/components/svelte.js

@@ -0,0 +1,55 @@
+import { defineComponents } from '../components.js';
+import { b as bindUsa } from '../chunks/bind-B_CTL6Qn.js';
+export { u as usaEventName } from '../chunks/bind-B_CTL6Qn.js';
+import './reveal.js';
+import '../chunks/base-BpROOcey.js';
+import './text.js';
+import './interaction.js';
+import './feedback.js';
+import './background.js';
+import '../chunks/variants-CHe1VbSn.js';
+import './transitions.js';
+import './physics.js';
+import '../chunks/spring-C-fw7_9f.js';
+import './cards.js';
+import './click.js';
+import './ui.js';
+import './page.js';
+import './timeline.js';
+import './gesture.js';
+import '../chunks/core-uxs3ETou.js';
+import './svg.js';
+import './webgl.js';
+import './depth.js';
+import './layout.js';
+import '../chunks/index-tags-BANJ-e4H.js';
+
+/**
+ * use-scroll-animate/components/svelte — Svelte integration (v3.8).
+ * Svelte (3, 4, 5) renders `<usa-*>` tags natively; `use:usa` sets
+ * **properties** and `usa:*` listeners in one place, and `defineUsa()`
+ * registers the elements on the client only (safe in SvelteKit SSR).
+ *
+ * ```svelte
+ * <script>
+ *   import { usa, defineUsa } from 'use-scroll-animate/components/svelte';
+ *   import { onMount } from 'svelte';
+ *   onMount(() => defineUsa(['click', 'ui']));
+ *   let on = false;
+ * </script>
+ * <usa-toggle use:usa={{ props: { checked: on }, on: { change: (e) => (on = e.detail.checked) } }}></usa-toggle>
+ * ```
+ * Plain `on:usa:change` does not compile in Svelte 3/4 (colon); use the action or `onusa:change` in Svelte 5.
+ */
+/** Svelte action: `use:usa={{ props, on }}`. */
+function usa(node, binding = {}) {
+    return bindUsa(node, binding);
+}
+/** Register the elements (all, or some categories) — call from `onMount` for SSR apps. */
+function defineUsa(categories) {
+    if (typeof window !== 'undefined')
+        defineComponents(categories);
+}
+
+export { bindUsa, defineUsa, usa };
+//# sourceMappingURL=svelte.js.map

package/dist/components/svelte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"svelte.js","sources":["../../src/components/frameworks/svelte.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/svelte — Svelte integration (v3.8).\n * Svelte (3, 4, 5) renders `<usa-*>` tags natively; `use:usa` sets\n * **properties** and `usa:*` listeners in one place, and `defineUsa()`\n * registers the elements on the client only (safe in SvelteKit SSR).\n *\n * ```svelte\n * <script>\n *   import { usa, defineUsa } from 'use-scroll-animate/components/svelte';\n *   import { onMount } from 'svelte';\n *   onMount(() => defineUsa(['click', 'ui']));\n *   let on = false;\n * </script>\n * <usa-toggle use:usa={{ props: { checked: on }, on: { change: (e) => (on = e.detail.checked) } }}></usa-toggle>\n * ```\n * Plain `on:usa:change` does not compile in Svelte 3/4 (colon); use the action or `onusa:change` in Svelte 5.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\nimport { bindUsa, type UsaBinding } from './bind';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** Svelte action: `use:usa={{ props, on }}`. */\nexport function usa(node: HTMLElement, binding: UsaBinding = {}): { update(b: UsaBinding): void; destroy(): void } {\n  return bindUsa(node, binding);\n}\n\n/** Register the elements (all, or some categories) — call from `onMount` for SSR apps. */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;AAgBG;AAOH;SACgB,GAAG,CAAC,IAAiB,EAAE,UAAsB,EAAE,EAAA;AAC7D,IAAA,OAAO,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;AAC/B;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,gBAAgB,CAAC,UAAU,CAAC;AACjE;;;;"}

package/docs/components.md

@@ -289,6 +289,20 @@ Fallbacks set `data-fallback` (`webgl` · `image` · `no-image`); cross-origin i
 
 Also see `flip()` / `connectedAnimation()` / `<usa-flip-list>` in `components/transitions`.
 
+### v3.7 Visual playground
+
+[`showcase/playground.html`](../showcase/playground.html) — stack `<usa-*>` effects around sample content, tweak every attribute live, and export HTML / ES module / React / Vue code or a share link (state in the URL hash).
+
+### v3.8 Svelte, Solid & Angular
+
+| Entry | API |
+|---|---|
+| `components/svelte` | `use:usa={{ props, on }}`, `defineUsa()` |
+| `components/solid` | `use:usa` directive, `defineUsa()`, JSX types (`prop:` / `on:usa:*` natively) |
+| `components/angular` | `usaInitializer()` (`APP_INITIALIZER`), `defineUsa()`, `usaDetail()`; `CUSTOM_ELEMENTS_SCHEMA` |
+
+Hybrid / desktop hosts (MAUI, Flutter WebView, Electron, Tauri): [hybrid-apps.md](./hybrid-apps.md).
+
 ## Frameworks
 
 Custom elements work in every framework. Register once (e.g. in your entry file), then use the tags.

package/docs/frameworks-ssr.md

@@ -62,3 +62,39 @@ Custom elements work as-is: Svelte (`on:usa:change`), Solid (`on:usa:change`, `p
 
 ## Lazy registration
 `lazyDefine()` (from `use-scroll-animate/components/lazy`) watches the DOM and dynamically imports only the categories whose tags appear — a page with just `<usa-button>` loads the click chunk only.
+
+## Svelte / SvelteKit (v3.8)
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import { usa, defineUsa } from 'use-scroll-animate/components/svelte';
+  onMount(() => defineUsa());
+  let on = false;
+</script>
+<usa-toggle use:usa={{ props: { checked: on }, on: { change: (e) => (on = e.detail.checked) } }}></usa-toggle>
+```
+
+## Solid / SolidStart (v3.8)
+
+```tsx
+import { onMount } from 'solid-js';
+import { defineUsa } from 'use-scroll-animate/components/solid';
+onMount(() => defineUsa());
+<usa-toggle prop:checked={on()} on:usa:change={(e) => setOn(e.detail.checked)} />;
+```
+
+## Angular (v3.8)
+
+```ts
+import { APP_INITIALIZER, CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core';
+import { usaInitializer, usaDetail } from 'use-scroll-animate/components/angular';
+// app.config.ts
+providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer() }];
+// component
+@Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<usa-toggle [checked]="on" (usa:change)="on = detail($event).checked"></usa-toggle>` })
+export class Settings { on = false; detail = usaDetail; }
+```
+
+MAUI, Flutter WebView, Electron and Tauri: see [hybrid-apps.md](./hybrid-apps.md).

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-scroll-animate",
-  "version": "3.6.0",
+  "version": "3.8.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",
@@ -268,6 +268,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",