use-scroll-animate 3.8.0 → 4.0.0

package/docs/components.md

@@ -40,7 +40,7 @@ defineTypewriter();
 No build step (registers every `<usa-*>` and exposes the API as `window.UsaComponents`):
 
 ```html
-<script src="https://unpkg.com/use-scroll-animate@3/dist/components.umd.js"></script>
+<script src="https://unpkg.com/use-scroll-animate@4/dist/components.umd.js"></script>
 <usa-typewriter words="Hello, Windows.|Hello, web."></usa-typewriter>
 <script>UsaComponents.toast('Ready', { type: 'success' });</script>
 ```
@@ -113,11 +113,9 @@ All attributes are optional unless noted. Events are `CustomEvent`s that bubble,
 |---|---|---|---|
 | `<usa-dialog>` | Animated modal / drawer / sheet on the native `<dialog>` (focus trap, Esc, top layer); content is slotted, so frameworks keep owning it | `open`, `kind` (`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>` |
 
 ### 7. Spring & physics — `components/physics`
 
@@ -287,7 +285,7 @@ Fallbacks set `data-fallback` (`webgl` · `image` · `no-image`); cross-origin i
 | `<usa-masonry>` | Masonry grid with animated reflow | `columns` or `min` (220), `gap` (16); `layout()` |
 | `sharedTransition(update, root?)` | Shared-element transition via `data-shared="id"` | `duration` (450), `easing`; View Transitions API or FLIP |
 
-Also see `flip()` / `connectedAnimation()` / `<usa-flip-list>` in `components/transitions`.
+Also see `flip()` in `components/transitions`. (4.0 removed `<usa-flip-list>` and `connectedAnimation()` in favour of these.)
 
 ### v3.7 Visual playground
 
@@ -303,6 +301,20 @@ Also see `flip()` / `connectedAnimation()` / `<usa-flip-list>` in `components/tr
 
 Hybrid / desktop hosts (MAUI, Flutter WebView, Electron, Tauri): [hybrid-apps.md](./hybrid-apps.md).
 
+### v3.9 Effect packs (`components/packs`)
+
+| Pack | `data-role` → effect |
+|---|---|
+| `ecommerce` | `product` reveal + lift · `add-to-cart` press + fly to `cart` · `cart` bump · `price` count up · `badge` pulse |
+| `portfolio` | `project` reveal + lift · `heading` reveal · `stat` count up · `contact` press + pulse |
+| `dashboard` | `card` reveal · `stat` count up · `alert` pulse · `action` press |
+| `game` | `button` press · `score` count up + bump · `item` float · `hit` shake · `reward` pulse |
+| `landing` | `hero` reveal · `feature` reveal + lift · `cta` press + pulse · `logo` float · `stat` count up |
+
+`<usa-pack>` (e.g. `<usa-pack name="ecommerce">…</usa-pack>`) or `applyPack('ecommerce', root)`; helpers `flyToCart(from, to)`, `countUp(el)`.
+
+**Deprecated in 3.9, removed in 4.0.0:** `sequence()`, `connectedAnimation()`, `<usa-flip-list>` — see [upgrading-4.md](./upgrading-4.md).
+
 ## Frameworks
 
 Custom elements work in every framework. Register once (e.g. in your entry file), then use the tags.

package/docs/migration-from-aos.md

@@ -27,7 +27,7 @@ No stylesheet is needed: animations run through the Web Animations API (or opt i
 | `data-aos-once="true"` | `data-sa-once` (default) |
 | `data-aos-mirror="true"` (animate out when scrolling past) | `data-sa-exit` |
 | `data-aos-anchor-placement="top-center"` | `data-sa-threshold="0.5"` or `data-sa-root-margin="0px 0px -50% 0px"` |
-| `data-aos-anchor=".other"` | `sequence([...], { trigger: '.other' })` |
+| `data-aos-anchor=".other"` | `timeline()` played when `.other` enters (or `<usa-timeline>` around it) |
 
 ## 3. Animation names
 

package/docs/migration-from-gsap-scrolltrigger.md

@@ -35,14 +35,14 @@ GSAP + ScrollTrigger is a full animation platform; `use-scroll-animate` covers t
 - tl.from('.title', { opacity: 0, y: 40 })
 -   .from('.subtitle', { opacity: 0 }, '-=0.2')
 -   .from('.cta', { scale: 0.8, opacity: 0 }, 1.2);
-+ sequence([
-+   { target: '.title', animation: 'fade-in-up' },
-+   { target: '.subtitle', animation: 'fade-in', gap: -200 },
-+   { target: '.cta', animation: 'zoom-in', at: 1200 },
-+ ], { trigger: '.hero' });
++ const tl = timeline()
++   .to('.title', 'fade-up')
++   .to('.subtitle', 'fade', { at: '-=200' })
++   .to('.cta', 'scale', { at: 1200 });
++ tl.scrub(document.querySelector('.hero')); // or tl.play() when it enters
 ```
 
-`play()` returns a Promise; `cancel()` stops it and leaves content visible.
+`play()` / `reverse()` return Promises; `seek()`, `progress()`, labels and `scrub()` work like GSAP's timeline controls.
 
 ## Scrub (progress-linked) animations
 

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.8.0",
+  "version": "4.0.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",
@@ -336,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": [
@@ -356,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",

package/dist/chunks/index-tags-BANJ-e4H.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-tags-BANJ-e4H.js","sources":["../../src/components/index-tags.ts"],"sourcesContent":["// The component categories and their default tags (no imports: safe for lazy loaders).\n/** The component categories and their default tags. */\nexport const COMPONENT_CATEGORIES = {\n  reveal: ['usa-reveal', 'usa-stagger', 'usa-scroll-progress', 'usa-scrolly'],\n  text: ['usa-typewriter', 'usa-split-text', 'usa-scramble', 'usa-counter', 'usa-shimmer-text', 'usa-text-rotate', 'usa-wave-text', 'usa-glitch', 'usa-gradient-text', 'usa-handwriting', 'usa-scroll-highlight'],\n  interaction: ['usa-ripple', 'usa-magnetic', 'usa-tilt', 'usa-spotlight', 'usa-press', 'usa-toggle'],\n  feedback: ['usa-spinner', 'usa-skeleton', 'usa-progress', 'usa-toaster', 'usa-check'],\n  background: ['usa-aurora', 'usa-particles', 'usa-grain', 'usa-marquee', 'usa-acrylic', 'usa-grid-glow', 'usa-blobs', 'usa-water-ripple', 'usa-dot-network'],\n  transitions: ['usa-dialog', 'usa-accordion', 'usa-flip-list', 'usa-view-switch'],\n  physics: ['usa-spring', 'usa-draggable', 'usa-overscroll'],\n  cards: ['usa-card', 'usa-card-stack', 'usa-sticky-stack', 'usa-carousel-3d'],\n  click: ['usa-click', 'usa-button', 'usa-icon-morph', 'usa-like', 'usa-hold', 'usa-double-tap', 'usa-checkbox'],\n  ui: ['usa-tabs', 'usa-drawer', 'usa-bottom-sheet', 'usa-pull-refresh', 'usa-fab', 'usa-navbar', 'usa-slider', 'usa-rating', 'usa-tooltip', 'usa-popover', 'usa-badge', 'usa-avatar-stack'],\n  page: ['usa-cursor', 'usa-fullpage', 'usa-loading-bar', 'usa-back-to-top', 'usa-ambient', 'usa-splash', 'usa-auto-skeleton', 'usa-motion-switch'],\n  timeline: ['usa-timeline'],\n  gesture: ['usa-swipeable', 'usa-pinch-zoom'],\n  svg: ['usa-draw', 'usa-morph', 'usa-mask-reveal', 'usa-anim-icon'],\n  webgl: ['usa-shader', 'usa-distort', 'usa-liquid'],\n  depth: ['usa-cube', 'usa-depth'],\n  layout: ['usa-auto-animate', 'usa-masonry'],\n} as const;\n\nexport type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;\n"],"names":[],"mappings":"AAAA;AACA;AACO,MAAM,oBAAoB,GAAG;IAClC,MAAM,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,aAAa,CAAC;IAC3E,IAAI,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,CAAC;AAC/M,IAAA,WAAW,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,CAAC;IACnG,QAAQ,EAAE,CAAC,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,CAAC;AACrF,IAAA,UAAU,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;IAC3J,WAAW,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,CAAC;AAChF,IAAA,OAAO,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,gBAAgB,CAAC;IAC1D,KAAK,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;AAC5E,IAAA,KAAK,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,CAAC;IAC9G,EAAE,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,CAAC;AAC1L,IAAA,IAAI,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,CAAC;IACjJ,QAAQ,EAAE,CAAC,cAAc,CAAC;AAC1B,IAAA,OAAO,EAAE,CAAC,eAAe,EAAE,gBAAgB,CAAC;IAC5C,GAAG,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,eAAe,CAAC;AAClE,IAAA,KAAK,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,YAAY,CAAC;AAClD,IAAA,KAAK,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;AAChC,IAAA,MAAM,EAAE,CAAC,kBAAkB,EAAE,aAAa,CAAC;;;;;"}

package/dist/chunks/index-tags-wbuPiMR6.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-tags-wbuPiMR6.cjs","sources":["../../src/components/index-tags.ts"],"sourcesContent":["// The component categories and their default tags (no imports: safe for lazy loaders).\n/** The component categories and their default tags. */\nexport const COMPONENT_CATEGORIES = {\n  reveal: ['usa-reveal', 'usa-stagger', 'usa-scroll-progress', 'usa-scrolly'],\n  text: ['usa-typewriter', 'usa-split-text', 'usa-scramble', 'usa-counter', 'usa-shimmer-text', 'usa-text-rotate', 'usa-wave-text', 'usa-glitch', 'usa-gradient-text', 'usa-handwriting', 'usa-scroll-highlight'],\n  interaction: ['usa-ripple', 'usa-magnetic', 'usa-tilt', 'usa-spotlight', 'usa-press', 'usa-toggle'],\n  feedback: ['usa-spinner', 'usa-skeleton', 'usa-progress', 'usa-toaster', 'usa-check'],\n  background: ['usa-aurora', 'usa-particles', 'usa-grain', 'usa-marquee', 'usa-acrylic', 'usa-grid-glow', 'usa-blobs', 'usa-water-ripple', 'usa-dot-network'],\n  transitions: ['usa-dialog', 'usa-accordion', 'usa-flip-list', 'usa-view-switch'],\n  physics: ['usa-spring', 'usa-draggable', 'usa-overscroll'],\n  cards: ['usa-card', 'usa-card-stack', 'usa-sticky-stack', 'usa-carousel-3d'],\n  click: ['usa-click', 'usa-button', 'usa-icon-morph', 'usa-like', 'usa-hold', 'usa-double-tap', 'usa-checkbox'],\n  ui: ['usa-tabs', 'usa-drawer', 'usa-bottom-sheet', 'usa-pull-refresh', 'usa-fab', 'usa-navbar', 'usa-slider', 'usa-rating', 'usa-tooltip', 'usa-popover', 'usa-badge', 'usa-avatar-stack'],\n  page: ['usa-cursor', 'usa-fullpage', 'usa-loading-bar', 'usa-back-to-top', 'usa-ambient', 'usa-splash', 'usa-auto-skeleton', 'usa-motion-switch'],\n  timeline: ['usa-timeline'],\n  gesture: ['usa-swipeable', 'usa-pinch-zoom'],\n  svg: ['usa-draw', 'usa-morph', 'usa-mask-reveal', 'usa-anim-icon'],\n  webgl: ['usa-shader', 'usa-distort', 'usa-liquid'],\n  depth: ['usa-cube', 'usa-depth'],\n  layout: ['usa-auto-animate', 'usa-masonry'],\n} as const;\n\nexport type ComponentCategory = keyof typeof COMPONENT_CATEGORIES;\n"],"names":[],"mappings":";;AAAA;AACA;AACO,MAAM,oBAAoB,GAAG;IAClC,MAAM,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,aAAa,CAAC;IAC3E,IAAI,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,CAAC;AAC/M,IAAA,WAAW,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,CAAC;IACnG,QAAQ,EAAE,CAAC,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,CAAC;AACrF,IAAA,UAAU,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;IAC3J,WAAW,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,CAAC;AAChF,IAAA,OAAO,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,gBAAgB,CAAC;IAC1D,KAAK,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;AAC5E,IAAA,KAAK,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,CAAC;IAC9G,EAAE,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,CAAC;AAC1L,IAAA,IAAI,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,CAAC;IACjJ,QAAQ,EAAE,CAAC,cAAc,CAAC;AAC1B,IAAA,OAAO,EAAE,CAAC,eAAe,EAAE,gBAAgB,CAAC;IAC5C,GAAG,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,eAAe,CAAC;AAClE,IAAA,KAAK,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,YAAY,CAAC;AAClD,IAAA,KAAK,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;AAChC,IAAA,MAAM,EAAE,CAAC,kBAAkB,EAAE,aAAa,CAAC;;;;;"}