use-scroll-animate 2.0.1 → 2.2.0

package/docs/components.md

@@ -0,0 +1,155 @@
+# Animated components (`use-scroll-animate/components`)
+
+Since **v2.2** the package ships **30 animated UI components** as standard Web Components (`<usa-*>` custom elements) plus three transition helpers. They are built only on Custom Elements, CSS and the Web Animations API, so the same code runs:
+
+- in any modern browser (Chrome, Edge, Firefox, Safari), and with React, Vue, Svelte, Solid, Angular or no framework;
+- in **Windows desktop software** that renders its UI with a web view — Electron, Tauri (WebView2), WinUI 3 / WPF / WinForms with WebView2, and installed PWAs. See **[Windows apps guide](./windows-apps.md)**.
+
+Live gallery: <https://harrisoncn.github.io/use-scroll-animate/showcase/components.html>
+
+## Principles
+
+- **Zero dependencies, tree-shakable.** Import one category (`use-scroll-animate/components/text`) or one component (`import { defineTypewriter } …`) and only that ships.
+- **SSR-safe.** Importing never touches `window`/`document`; every `define*()` is a no-op on the server.
+- **Opt-in registration.** Nothing is registered until you call `define*()` (or load the IIFE bundle). Every `define*()` accepts a custom tag name: `defineSpinner('my-loader')`.
+- **`prefers-reduced-motion` everywhere.** Each component has a calm variant (instant reveal, fade instead of slide, static background…). Override globally with `configureComponents({ reducedMotion: 'reduce' | 'no-preference' | 'user' })`.
+- **GPU-friendly.** Animations use `transform` / `opacity` (plus `filter` for blur effects); layout is read and written in separate phases, at most once per frame, and loops pause when off-screen or the tab is hidden.
+- **Accessible.** Animated text keeps a visually-hidden plain copy for screen readers; switches, progress bars, toasts and dialogs carry the right roles and ARIA states.
+- **Styles included.** Each component injects its own small stylesheet once (as a constructable stylesheet, which a `style-src 'self'` CSP allows). Prefer a file? `import 'use-scroll-animate/components.css'` (or `/components/<category>.css`) and call `configureComponents({ injectStyles: false })`.
+
+## Install & register
+
+```bash
+npm i use-scroll-animate
+```
+
+```js
+// everything
+import { defineComponents } from 'use-scroll-animate/components';
+defineComponents();                       // or defineComponents(['text', 'feedback'])
+
+// one category
+import { defineTextComponents } from 'use-scroll-animate/components/text';
+defineTextComponents();
+
+// one component
+import { defineTypewriter } from 'use-scroll-animate/components/text';
+defineTypewriter();
+```
+
+No build step (registers every `<usa-*>` and exposes the API as `window.UsaComponents`):
+
+```html
+<script src="https://unpkg.com/use-scroll-animate@2/dist/components.umd.js"></script>
+<usa-typewriter words="Hello, Windows.|Hello, web."></usa-typewriter>
+<script>UsaComponents.toast('Ready', { type: 'success' });</script>
+```
+
+| Entry | Contents |
+|---|---|
+| `use-scroll-animate/components` | everything + `defineComponents()`, `COMPONENT_CATEGORIES`, `configureComponents()` |
+| `use-scroll-animate/components/reveal` · `/text` · `/interaction` · `/feedback` · `/background` · `/transitions` | one category + `define<Category>Components()` |
+| `use-scroll-animate/components.css`, `/components/<category>.css` | the same styles as files |
+| `dist/components.umd.js` | IIFE/UMD bundle for `<script>` tags, auto-registers |
+
+## Components by category
+
+All attributes are optional unless noted. Events are `CustomEvent`s that bubble, named `usa:*`.
+
+### 1. Entrance & scroll — `components/reveal`
+
+| Element | What it does | Key attributes | JS API / events |
+|---|---|---|---|
+| `<usa-reveal>` | Reveals content when it enters the viewport | `effect` (`fade`, `fade-up`*, `fade-down`, `fade-left`, `fade-right`, `zoom-in`, `zoom-out`, `blur`, `blur-up`, `flip-up`, `flip-left`, `rise`), `duration` (700), `delay`, `distance` (32), `easing`, `threshold` (0.15), `root-margin`, `repeat` | `reveal()`, `reset()`, `revealed`; `usa:enter`, `usa:leave`, `usa:complete` |
+| `<usa-stagger>` | Reveals its children one after another | `effect`, `interval` (70 ms), `duration`, `delay`, `distance`, `threshold`, `repeat` | `reveal()`, `reset()`; `usa:enter`, `usa:complete` |
+| `<usa-scroll-progress>` | Reading-progress bar for the page or one article | `target` (selector), `position` (`top`*, `bottom`, `inline`), `label`; CSS `--usa-progress-color/-height/-track` | `progress`, `update()`; `usa:progress` (`detail.progress`); `--usa-progress` on the element |
+| `<usa-scrolly>` | Sticky scrollytelling: `[data-sticky]` stays pinned while `[data-step]` children scroll by | `offset` (trigger line, 0.5) | `active`, `steps`; `usa:step` (`detail.index/step/name`); `data-step-name` + `--usa-step` on the host, `data-active` on the step |
+
+### 2. Text — `components/text`
+
+| Element | What it does | Key attributes | JS API / events |
+|---|---|---|---|
+| `<usa-typewriter>` | Types text, or cycles phrases (type → pause → delete) | `text` or `words` (`a\|b\|c`), `speed` (55), `delete-speed` (30), `pause` (1400), `delay`, `loop`, `cursor="false"`, `start` (`view`*, `load`, `manual`) | `start()`, `stop()`, `restart()`; `usa:complete` |
+| `<usa-split-text>` | Splits into characters or words and cascades them in | `by` (`chars`*, `words`), `effect` (`rise`*, `fade`, `blur`, `flip`, `pop`), `stagger`, `duration` (620), `delay`, `trigger` (`view`*, `load`, `manual`), `repeat` | `play()`, `reset()`, `units`; `usa:complete` |
+| `<usa-scramble>` | Decodes text out of random glyphs | `text`, `duration` (900), `chars`, `trigger` (`view`*, `hover`, `load`, `manual`) | `play()`; `usa:complete` |
+| `<usa-counter>` | Counts to a number when visible (locale-formatted, tabular digits) | `to` (required), `from`, `duration` (1600), `decimals`, `locale`, `prefix`, `suffix`, `grouping="false"`, `start` | `value` (set to animate), `play(to?)`, `format(n)`; `usa:complete` |
+| `<usa-shimmer-text>` | Light sweep across gradient text (CSS only) | `duration` (2600), `color`, `shine`, `angle` | — |
+| `<usa-text-rotate>` | Cycles words in place without reflow | `words`, `interval` (2200), `effect` (`slide`*, `fade`, `flip`, `blur`), `paused` | `next()`, `index`; `usa:change` |
+
+### 3. Interaction — `components/interaction`
+
+| Element | What it does | Key attributes | JS API / events |
+|---|---|---|---|
+| `<usa-ripple>` | Ink ripple from the pointer (centre for Space/Enter) | `color`, `opacity` (0.22), `duration` (550), `centered`, `disabled`, `block` | `ripple(x?, y?)` |
+| `<usa-magnetic>` | Content leans toward a nearby pointer and springs back | `strength` (0.35), `radius` (60), `disabled` | — (fine pointers only) |
+| `<usa-tilt>` | 3D tilt toward the pointer, optional glare | `max` (10°), `scale` (1.03), `perspective` (900), `glare`, `reverse`, `disabled` | `--usa-tilt-x/-y` (−1…1) for inner parallax |
+| `<usa-spotlight>` | Windows Fluent **Reveal highlight**: light follows the pointer across a group, lighting borders | `size` (160), `color`, `border` (1), `no-fill`; items = children or `[data-spotlight]` | — |
+| `<usa-press>` | Press feedback: dip + spring back, or `bounce` | `scale` (0.95), `bounce`, `disabled`, `block` | `pressed` |
+| `<usa-toggle>` | Windows 11-style switch, form-associated | `checked`, `disabled`, `name`, `value`, `label` | `checked`, `toggle(force?)`; `change`, `usa:change` |
+
+### 4. Loading & feedback — `components/feedback`
+
+| Element | What it does | Key attributes | JS API / events |
+|---|---|---|---|
+| `<usa-spinner>` | Indeterminate indicators | `variant` (`fluent`* = WinUI ProgressRing, `windows` = Windows 10 orbiting dots, `ring`, `dots`, `pulse`, `bars`), `size` (32), `label`, `paused` | `variant` |
+| `<usa-skeleton>` | Shimmer placeholders; content fades in when loading ends | `loading`, `lines` (3), `avatar`, `circle`, `width`, `height`, `radius` | `loading`; `usa:loaded` |
+| `<usa-progress>` | Linear progress; Fluent indeterminate animation without a value | `value`, `max` (100), `indeterminate`, `state` (`paused`, `error`), `label` | `value`, `max`, `ratio`; `usa:complete` |
+| `<usa-toaster>` + `toast()` | Notifications that slide in, pause on hover, stack with FLIP | `position` (`bottom-right`*, `bottom-left`, `bottom-center`, `top-*`), `max` (4), `label` | `toast(msg, { type, duration, action, dismissible })` → `{ element, close() }`; `show()`, `clear()` |
+| `<usa-check>` | Animated success / error / warning icon | `variant` (`success`*, `error`, `warning`), `size` (56), `start`, `label` | `play()`, `reset()`; `usa:complete` |
+
+### 5. Background & decoration — `components/background`
+
+| Element | What it does | Key attributes | JS API / events |
+|---|---|---|---|
+| `<usa-aurora>` | Drifting aurora / gradient mesh behind content | `colors` (comma list), `speed` (1), `intensity` (0.7), `paused` | — (pauses off-screen) |
+| `<usa-particles>` | Canvas constellation that avoids the pointer | `count` (60), `color`, `size`, `speed`, `links` (110, `0` = off), `interactive`, `paused` | `reset()` |
+| `<usa-grain>` | SVG-noise film-grain overlay | `opacity` (0.12), `animated`, `blend`, `scale` | — |
+| `<usa-marquee>` | Seamless infinite ticker | `speed` (50 px/s), `direction` (`left`*, `right`, `up`, `down`), `gap`, `pause-on-hover`, `fade`, `paused` | `pause()`, `resume()` |
+| `<usa-acrylic>` | Fluent **Acrylic** / **Mica** materials | `variant` (`acrylic`*, `mica`), `tint`, `tint-opacity`, `blur`, `shimmer` (`hover`, `load`) | — (solid under `prefers-reduced-transparency` / forced colours) |
+
+### 6. Transitions — `components/transitions`
+
+| Element / helper | What it does | Key attributes / options | JS API / events |
+|---|---|---|---|
+| `<usa-dialog>` | Animated modal / drawer / sheet on the native `<dialog>` (focus trap, Esc, top layer); content is slotted, so frameworks keep owning it | `open`, `variant` (`modal`*, `drawer-start`, `drawer-end`, `drawer-bottom`, `sheet`), `label`, `no-backdrop-close`, `no-esc`; `[data-close]` children close it; `::part(panel/backdrop)`, `--usa-dialog-*` | `show()`, `close(value?)`, `open`, `returnValue`; `usa:open`, `usa:beforeclose` (cancelable), `usa:close` |
+| `<usa-accordion>` | Smooth height animation for native `<details>` | `multiple`, `duration` (300) | `toggleItem(details, open?)`, `items`; `usa:toggle` |
+| `<usa-flip-list>` | Children glide to new places on add / remove / reorder (FLIP) | `duration` (420), `easing`, `disabled` | `flip(mutate)` |
+| `<usa-view-switch>` | One view at a time with direction-aware transitions | `active` (name or index), `effect` (`slide`*, `fade`, `scale`, `drill`), `duration` | `show(view)`, `active`, `views`; `usa:change` |
+| `viewTransition(update, opts?)` | Runs a DOM update inside `document.startViewTransition()`, cross-fade fallback | `{ fallback, duration, types }` | `Promise<void>` |
+| `flip(targets, mutate, opts?)` | FLIP-animates any layout change | `{ duration, easing, animateEnter }` | `Promise<void>` |
+| `connectedAnimation(from, to, opts?)` | WinUI-style connected / shared-element animation | `{ duration, easing, hideSource }` | `Promise<void>` |
+
+## Frameworks
+
+Custom elements work in every framework. Register once (e.g. in your entry file), then use the tags.
+
+```jsx
+// React 19 passes props to custom elements as properties; React 18 passes strings — both work for attributes.
+import { defineFeedbackComponents, toast } from 'use-scroll-animate/components/feedback';
+defineFeedbackComponents();
+
+export function Save() {
+  return <button onClick={() => toast('Saved', { type: 'success' })}>Save <usa-spinner variant="dots" size="16" /></button>;
+}
+```
+
+```js
+// Vue (vite.config.js): tell the compiler these are custom elements
+vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('usa-') } } });
+```
+
+TypeScript: the entries augment `HTMLElementTagNameMap`, so `document.querySelector('usa-dialog')` is typed as `UsaDialogElement`.
+
+## Size
+
+Gzipped, minified (budgets enforced in CI by `npm run size:check`):
+
+| Import | gzip |
+|---|---:|
+| `dist/components.umd.js` (all 30 + CSS) | ≈ 22 kB |
+| one category (`components/text`, …) | 3.5 – 6.4 kB |
+| one component (`defineTypewriter`, `defineReveal`, `defineRipple`, …) | ≈ 1.8 – 2.5 kB |
+| `viewTransition` only | ≈ 0.4 kB |
+| `dist/components.css` | ≈ 5.5 kB |
+
+The scroll-animation core (`use-scroll-animate`) is unchanged and is not pulled in by the components.

package/docs/windows-apps.md

@@ -0,0 +1,108 @@
+# Using the components in Windows desktop apps
+
+The `<usa-*>` components are plain web platform code (Custom Elements v1, CSS, Web Animations API). Any Windows app whose UI is rendered by a modern web engine can use them unchanged:
+
+| Stack | Engine on Windows | Works | Notes |
+|---|---|---|---|
+| **Electron** | Chromium (bundled) | ✅ | All features, incl. View Transitions. |
+| **Tauri 1/2** | Microsoft Edge **WebView2** (Chromium) | ✅ | Same as Edge. |
+| **WinUI 3 / WPF / WinForms + WebView2** | WebView2 | ✅ | Host a local HTML page (see below). |
+| **.NET MAUI / Blazor Hybrid** | `BlazorWebView` → WebView2 | ✅ | Register in `wwwroot/index.html`. |
+| **Installed PWA** (Edge / Chrome "Install app") | Edge / Chrome | ✅ | Runs in its own window with taskbar icon. |
+| Neutralino, Wails, Flutter `webview_windows` | WebView2 | ✅ | Any WebView2-based shell. |
+| Legacy MSHTML (`WebBrowser` control, IE11) | Trident | ❌ | No Custom Elements / WAAPI — migrate to WebView2. |
+
+Requirements: Custom Elements, `IntersectionObserver` and `Element.animate()` — every Chromium ≥ 84 (all supported Electron/WebView2 versions). `viewTransition()` uses the View Transitions API (Chromium ≥ 111) and falls back to a cross-fade.
+
+Every component respects the Windows setting **Settings → Accessibility → Visual effects → Animation effects** (exposed to web views as `prefers-reduced-motion`), and `<usa-acrylic>` turns solid when **Transparency effects** are off or a high-contrast theme is active (`prefers-reduced-transparency`, `forced-colors`).
+
+## Electron
+
+Bundle the renderer as usual (Vite, webpack, esbuild…):
+
+```js
+// renderer/main.js
+import { defineComponents, toast } from 'use-scroll-animate/components';
+defineComponents();
+
+window.api?.onSaved?.(() => toast('Saved', { type: 'success' }));
+```
+
+```html
+<!-- renderer/index.html -->
+<usa-acrylic variant="mica" style="min-height:100vh">
+  <usa-view-switch active="home">
+    <section data-view="home"><usa-typewriter words="Welcome back"></usa-typewriter></section>
+    <section data-view="settings"><usa-toggle checked>Start with Windows</usa-toggle></section>
+  </usa-view-switch>
+</usa-acrylic>
+```
+
+Without a bundler, copy `node_modules/use-scroll-animate/dist/components.umd.js` next to your HTML and use `<script src="components.umd.js"></script>` — no `nodeIntegration` needed, it works with `contextIsolation: true` and `sandbox: true`.
+
+**Content-Security-Policy.** Components inject styles via constructable stylesheets (`document.adoptedStyleSheets`), which are allowed by `style-src 'self'` without `'unsafe-inline'`. If you prefer files:
+
+```js
+import 'use-scroll-animate/components.css';
+import { configureComponents, defineComponents } from 'use-scroll-animate/components';
+configureComponents({ injectStyles: false });
+defineComponents();
+```
+
+`<usa-grain>` and `<usa-acrylic>` use `data:` SVG noise images — allow `img-src 'self' data:`.
+
+**Real Windows materials.** Electron ≥ 24 can draw real Mica / Acrylic behind a transparent window (`new BrowserWindow({ backgroundMaterial: 'mica' })`). Set the page background to transparent and use `<usa-acrylic tint-opacity="0.2">` for in-page panels on top of it.
+
+## Tauri
+
+```ts
+// src/main.ts (Vite template)
+import { defineFeedbackComponents } from 'use-scroll-animate/components/feedback';
+import { defineTransitionComponents } from 'use-scroll-animate/components/transitions';
+defineFeedbackComponents();
+defineTransitionComponents();
+```
+
+Nothing to configure in `tauri.conf.json`. For window-level Mica/Acrylic use Tauri's `windowEffects` (`"effects": ["mica"]`) with `"transparent": true`.
+
+## WinUI 3 / WPF / WinForms with WebView2
+
+1. Put your page and the bundle in a folder that is copied to the output, e.g. `wwwroot/index.html` and `wwwroot/components.umd.js` (from `node_modules/use-scroll-animate/dist/`, or download it from unpkg).
+2. Map the folder to a virtual host and navigate to it:
+
+```csharp
+// WinUI 3 (C#)
+await MyWebView.EnsureCoreWebView2Async();
+MyWebView.CoreWebView2.SetVirtualHostNameToFolderMapping(
+    "app.local", Path.Combine(AppContext.BaseDirectory, "wwwroot"),
+    CoreWebView2HostResourceAccessKind.Allow);
+MyWebView.Source = new Uri("https://app.local/index.html");
+```
+
+```html
+<!-- wwwroot/index.html -->
+<!doctype html>
+<meta name="color-scheme" content="light dark">
+<script src="components.umd.js"></script>
+<usa-progress id="p" value="0" label="Installing"></usa-progress>
+<usa-spinner variant="fluent"></usa-spinner>
+<script>
+  // messages from C#: CoreWebView2.PostWebMessageAsJson("{\"progress\":42}")
+  chrome.webview.addEventListener('message', (e) => (p.value = e.data.progress));
+</script>
+```
+
+Talk back to the host with `chrome.webview.postMessage(...)` from component events, e.g.
+`dialog.addEventListener('usa:close', (e) => chrome.webview.postMessage({ closed: e.detail.returnValue }))`.
+
+For a transparent WebView2 over a Mica window, set `DefaultBackgroundColor` to `Transparent` and keep the page background transparent.
+
+## PWA
+
+Link the bundle (or import it in your module graph) and install the site from Edge/Chrome. Add `"display": "standalone"` (or `"window-controls-overlay"` for a custom title bar) to the manifest; the components behave exactly as on the web.
+
+## Performance checklist for desktop UIs
+
+- Register only what you use (`define<Category>Components()` or single `define*()` calls) to keep start-up light.
+- Background effects (`<usa-aurora>`, `<usa-particles>`, `<usa-marquee>`) stop animating when off-screen and when the window is hidden/minimised (`document.hidden`).
+- All motion runs on the compositor (`transform` / `opacity`), so it stays smooth on integrated GPUs and in battery-saver mode; call `configureComponents({ reducedMotion: 'reduce' })` to force the calm variants (e.g. for a "Reduce animations" toggle in your app settings).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "use-scroll-animate",
-  "version": "2.0.1",
-  "description": "A lightweight, high-performance, dependency-free scroll animation library for modern web.",
+  "version": "2.2.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",
   "unpkg": "dist/index.umd.js",
@@ -68,6 +68,83 @@
         "default": "./dist/element.cjs"
       }
     },
+    "./components": {
+      "import": {
+        "types": "./dist/components.d.ts",
+        "default": "./dist/components.js"
+      },
+      "require": {
+        "types": "./dist/components.d.cts",
+        "default": "./dist/components.cjs"
+      }
+    },
+    "./components/reveal": {
+      "import": {
+        "types": "./dist/components/reveal.d.ts",
+        "default": "./dist/components/reveal.js"
+      },
+      "require": {
+        "types": "./dist/components/reveal.d.cts",
+        "default": "./dist/components/reveal.cjs"
+      }
+    },
+    "./components/text": {
+      "import": {
+        "types": "./dist/components/text.d.ts",
+        "default": "./dist/components/text.js"
+      },
+      "require": {
+        "types": "./dist/components/text.d.cts",
+        "default": "./dist/components/text.cjs"
+      }
+    },
+    "./components/interaction": {
+      "import": {
+        "types": "./dist/components/interaction.d.ts",
+        "default": "./dist/components/interaction.js"
+      },
+      "require": {
+        "types": "./dist/components/interaction.d.cts",
+        "default": "./dist/components/interaction.cjs"
+      }
+    },
+    "./components/feedback": {
+      "import": {
+        "types": "./dist/components/feedback.d.ts",
+        "default": "./dist/components/feedback.js"
+      },
+      "require": {
+        "types": "./dist/components/feedback.d.cts",
+        "default": "./dist/components/feedback.cjs"
+      }
+    },
+    "./components/background": {
+      "import": {
+        "types": "./dist/components/background.d.ts",
+        "default": "./dist/components/background.js"
+      },
+      "require": {
+        "types": "./dist/components/background.d.cts",
+        "default": "./dist/components/background.cjs"
+      }
+    },
+    "./components/transitions": {
+      "import": {
+        "types": "./dist/components/transitions.d.ts",
+        "default": "./dist/components/transitions.js"
+      },
+      "require": {
+        "types": "./dist/components/transitions.d.cts",
+        "default": "./dist/components/transitions.cjs"
+      }
+    },
+    "./components.css": "./dist/components.css",
+    "./components/reveal.css": "./dist/components/reveal.css",
+    "./components/text.css": "./dist/components/text.css",
+    "./components/interaction.css": "./dist/components/interaction.css",
+    "./components/feedback.css": "./dist/components/feedback.css",
+    "./components/background.css": "./dist/components/background.css",
+    "./components/transitions.css": "./dist/components/transitions.css",
     "./package.json": "./package.json"
   },
   "files": [
@@ -79,14 +156,16 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css"
+  ],
   "scripts": {
     "build": "npm run clean && rollup -c rollup.config.mjs",
     "dev": "rollup -c rollup.config.mjs -w",
     "typecheck": "tsc --noEmit -p .",
     "test": "vitest run",
     "check:exports": "node scripts/check-exports.mjs",
-    "lint:package": "publint && attw --pack . --profile node16",
+    "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",
     "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",
@@ -108,7 +187,16 @@
     "solid",
     "web-component",
     "custom-element",
-    "scroll-timeline"
+    "scroll-timeline",
+    "animated-components",
+    "ui-components",
+    "electron",
+    "tauri",
+    "webview2",
+    "fluent",
+    "typewriter",
+    "skeleton",
+    "toast"
   ],
   "author": "HarrisonCN",
   "license": "MIT",