@llui/transitions 0.0.2 → 0.0.3

package/README.md

@@ -26,20 +26,104 @@ view({ show, text }) {
 
 ### Core
 
-| Function                    | Description                                          |
-| --------------------------- | ---------------------------------------------------- |
+| Function                       | Description                                             |
+| ------------------------------ | ------------------------------------------------------- |
 | `transition({ enter, leave })` | Core transition -- define custom enter/leave animations |
-| `mergeTransitions(a, b)`    | Combine two transitions into one                     |
+| `mergeTransitions(a, b)`       | Combine two transitions into one                        |
 
 ### Presets
 
-| Function             | Options                         | Description                    |
-| -------------------- | ------------------------------- | ------------------------------ |
-| `fade(options?)`     | `duration`, `easing`            | Fade in/out                    |
+| Function             | Options                           | Description                                          |
+| -------------------- | --------------------------------- | ---------------------------------------------------- |
+| `fade(options?)`     | `duration`, `easing`              | Fade in/out                                          |
 | `slide(options?)`    | `direction`, `duration`, `easing` | Slide from direction (`up`, `down`, `left`, `right`) |
-| `scale(options?)`    | `from`, `duration`, `easing`    | Scale transform in/out         |
-| `collapse(options?)` | `duration`, `easing`            | Height collapse/expand         |
-| `flip(options?)`     | `duration`, `easing`            | FLIP reorder animation for `each()` |
+| `scale(options?)`    | `from`, `duration`, `easing`      | Scale transform in/out                               |
+| `collapse(options?)` | `duration`, `easing`              | Height collapse/expand                               |
+| `flip(options?)`     | `duration`, `easing`              | FLIP reorder animation for `each()`                  |
+
+### Spring Physics
+
+| Function           | Options                                                               | Description                      |
+| ------------------ | --------------------------------------------------------------------- | -------------------------------- |
+| `spring(options?)` | `stiffness`, `damping`, `mass`, `precision`, `property`, `from`, `to` | Spring-physics animation via rAF |
+
+Uses a damped spring simulation instead of CSS easing. The animation runs via `requestAnimationFrame` and settles naturally based on physics parameters.
+
+```ts
+import { spring } from '@llui/transitions'
+
+// Default: opacity 0 → 1 with react-spring-like defaults
+show({ when: (s) => s.open, render: () => content(), ...spring() })
+
+// Custom spring feel
+show({
+  when: (s) => s.open,
+  render: () => content(),
+  ...spring({ stiffness: 300, damping: 15, property: 'opacity' }),
+})
+```
+
+### Route Transitions
+
+| Function                    | Options                                        | Description                                  |
+| --------------------------- | ---------------------------------------------- | -------------------------------------------- |
+| `routeTransition(options?)` | `duration`, `easing`, `slide`, `slideDistance` | Fade + slide for `branch()` page transitions |
+
+Convenience wrapper for animating page transitions in a `branch()`:
+
+```ts
+import { routeTransition, fade } from '@llui/transitions'
+
+// Default: fade + slight upward slide (250ms)
+branch({
+  on: (s) => s.route.page,
+  cases: { home: () => [...], about: () => [...] },
+  ...routeTransition(),
+})
+
+// Custom duration
+branch({ on, cases, ...routeTransition({ duration: 200 }) })
+
+// Fade only (no slide)
+branch({ on, cases, ...routeTransition({ duration: 200, slide: false }) })
+
+// Pass any preset directly
+branch({ on, cases, ...routeTransition(fade({ duration: 200 })) })
+```
+
+### Stagger
+
+| Function                        | Options                      | Description                                       |
+| ------------------------------- | ---------------------------- | ------------------------------------------------- |
+| `stagger(transition, options?)` | `delayPerItem`, `leaveOrder` | Stagger enter/leave animations for `each()` items |
+
+Wraps any transition preset so batch-entered items animate with incremental delays:
+
+```ts
+import { stagger, fade, slide } from '@llui/transitions'
+
+each({
+  items: (s) => s.items,
+  key: (i) => i.id,
+  render: ({ item }) => [...],
+  ...stagger(fade({ duration: 150 }), { delayPerItem: 30 }),
+})
+
+// Works with any preset
+each({
+  items: (s) => s.items,
+  key: (i) => i.id,
+  render: ({ item }) => [...],
+  ...stagger(slide({ direction: 'up' }), { delayPerItem: 50 }),
+})
+
+// Stagger leave animations too (default is simultaneous)
+each({
+  ...stagger(fade(), { delayPerItem: 30, leaveOrder: 'sequential' }),
+})
+```
+
+Items entering within the same microtask are considered a "batch" and get sequential delays. The counter resets after the microtask boundary, so the next batch starts from index 0.
 
 ### Integration
 
@@ -53,7 +137,11 @@ show({ when: (s) => s.open, render: () => content(), ...fade() })
 each({
   items: (s) => s.list,
   key: (item) => item.id,
-  render: (item) => li({}, text(() => item.name)),
+  render: (item) =>
+    li(
+      {},
+      text(() => item.name),
+    ),
   ...flip({ duration: 200 }),
 })
 ```

package/dist/index.d.ts

@@ -1,7 +1,13 @@
 export { transition } from './transition';
 export { fade, slide, scale, collapse } from './presets';
 export type { FadeOptions, SlideOptions, SlideDirection, ScaleOptions, CollapseOptions, } from './presets';
+export { spring } from './spring';
+export type { SpringOptions } from './spring';
 export { flip, mergeTransitions } from './flip';
 export type { FlipOptions } from './flip';
+export { routeTransition } from './route-transition';
+export type { RouteTransitionOptions } from './route-transition';
+export { stagger } from './stagger';
+export type { StaggerOptions } from './stagger';
 export type { TransitionSpec, TransitionValue, Styles } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAGzC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACxD,YAAY,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,MAAM,WAAW,CAAA;AAGlB,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAA;AAC/C,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAGzC,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAGzC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACxD,YAAY,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,MAAM,WAAW,CAAA;AAGlB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAG7C,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAA;AAC/C,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAGzC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAGhE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAG/C,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA"}

package/dist/index.js

@@ -2,5 +2,11 @@
 export { transition } from './transition';
 // Presets
 export { fade, slide, scale, collapse } from './presets';
+// Spring physics
+export { spring } from './spring';
 // Reorder animation + composition
 export { flip, mergeTransitions } from './flip';
+// Route transitions
+export { routeTransition } from './route-transition';
+// Stagger
+export { stagger } from './stagger';

package/dist/route-transition.d.ts

@@ -0,0 +1,29 @@
+import type { TransitionOptions } from '@llui/dom';
+export interface RouteTransitionOptions {
+    /** Duration in milliseconds (default: 250). */
+    duration?: number;
+    /** Easing function (default: 'ease-out'). */
+    easing?: string;
+    /** Enable a slight vertical slide alongside the fade (default: true). */
+    slide?: boolean;
+    /** Slide distance in pixels (default: 12). */
+    slideDistance?: number;
+}
+/**
+ * Convenience wrapper that returns `{ enter, leave }` hooks suitable for
+ * spreading into a `branch()` call to animate page transitions.
+ *
+ * Can be called two ways:
+ *
+ * 1. With route-specific options (produces a fade + optional slide):
+ *    ```ts
+ *    branch({ on, cases, ...routeTransition({ duration: 200 }) })
+ *    ```
+ *
+ * 2. With a pre-built `TransitionOptions` (e.g. from any preset):
+ *    ```ts
+ *    branch({ on, cases, ...routeTransition(fade({ duration: 200 })) })
+ *    ```
+ */
+export declare function routeTransition(opts?: RouteTransitionOptions | TransitionOptions): TransitionOptions;
+//# sourceMappingURL=route-transition.d.ts.map

package/dist/route-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-transition.d.ts","sourceRoot":"","sources":["../src/route-transition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAKlD,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,IAAI,CAAC,EAAE,sBAAsB,GAAG,iBAAiB,GAChD,iBAAiB,CAyBnB"}

package/dist/route-transition.js

@@ -0,0 +1,41 @@
+import { fade } from './presets';
+import { slide } from './presets';
+import { mergeTransitions } from './flip';
+/**
+ * Convenience wrapper that returns `{ enter, leave }` hooks suitable for
+ * spreading into a `branch()` call to animate page transitions.
+ *
+ * Can be called two ways:
+ *
+ * 1. With route-specific options (produces a fade + optional slide):
+ *    ```ts
+ *    branch({ on, cases, ...routeTransition({ duration: 200 }) })
+ *    ```
+ *
+ * 2. With a pre-built `TransitionOptions` (e.g. from any preset):
+ *    ```ts
+ *    branch({ on, cases, ...routeTransition(fade({ duration: 200 })) })
+ *    ```
+ */
+export function routeTransition(opts) {
+    // If opts already has enter/leave, treat it as a pre-built TransitionOptions.
+    if (opts && ('enter' in opts || 'leave' in opts)) {
+        return opts;
+    }
+    const config = (opts ?? {});
+    const duration = config.duration ?? 250;
+    const easing = config.easing ?? 'ease-out';
+    const withSlide = config.slide !== false;
+    const slideDistance = config.slideDistance ?? 12;
+    const fadeT = fade({ duration, easing });
+    if (!withSlide)
+        return fadeT;
+    const slideT = slide({
+        direction: 'up',
+        distance: slideDistance,
+        duration,
+        easing,
+        fade: false,
+    });
+    return mergeTransitions(fadeT, slideT);
+}

package/dist/spring.d.ts

@@ -0,0 +1,28 @@
+import type { TransitionOptions } from '@llui/dom';
+export interface SpringOptions {
+    /** Spring stiffness (default: 170). */
+    stiffness?: number;
+    /** Damping coefficient (default: 26). */
+    damping?: number;
+    /** Mass (default: 1). */
+    mass?: number;
+    /** Stop threshold for velocity and position (default: 0.01). */
+    precision?: number;
+    /** CSS property to animate (default: 'opacity'). */
+    property?: string;
+    /** Start value (default: 0). */
+    from?: number;
+    /** End value (default: 1). */
+    to?: number;
+}
+/**
+ * Spring-physics transition. Returns `{ enter, leave }` that animate a CSS
+ * property using a damped spring simulation driven by `requestAnimationFrame`.
+ *
+ * ```ts
+ * show({ when: (s) => s.open, render: () => content(), ...spring() })
+ * show({ ...spring({ property: 'transform', from: 0, to: 1 }) })
+ * ```
+ */
+export declare function spring(opts?: SpringOptions): TransitionOptions;
+//# sourceMappingURL=spring.d.ts.map

package/dist/spring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring.d.ts","sourceRoot":"","sources":["../src/spring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAGlD,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8BAA8B;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AA4ED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,iBAAiB,CAoBlE"}

package/dist/spring.js

@@ -0,0 +1,70 @@
+import { asElements } from './style-utils';
+function simulateSpring(state, target, stiffness, damping, mass, dt) {
+    const acceleration = (-stiffness * (state.position - target) - damping * state.velocity) / mass;
+    state.velocity += acceleration * dt;
+    state.position += state.velocity * dt;
+}
+function isSettled(state, target, precision) {
+    return Math.abs(state.velocity) < precision && Math.abs(state.position - target) < precision;
+}
+function animateSpring(els, from, to, property, stiffness, damping, mass, precision) {
+    if (els.length === 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const state = { position: from, velocity: 0 };
+        let lastTime = null;
+        function step(time) {
+            if (lastTime === null) {
+                lastTime = time;
+            }
+            // dt in seconds, clamped to avoid spiral on tab-switch
+            const dt = Math.min((time - lastTime) / 1000, 0.064);
+            lastTime = time;
+            simulateSpring(state, to, stiffness, damping, mass, dt);
+            for (const el of els) {
+                el.style.setProperty(property, String(state.position));
+            }
+            if (isSettled(state, to, precision)) {
+                // Snap to exact target
+                for (const el of els) {
+                    el.style.setProperty(property, String(to));
+                }
+                resolve();
+                return;
+            }
+            requestAnimationFrame(step);
+        }
+        // Apply initial value
+        for (const el of els) {
+            el.style.setProperty(property, String(from));
+        }
+        requestAnimationFrame(step);
+    });
+}
+/**
+ * Spring-physics transition. Returns `{ enter, leave }` that animate a CSS
+ * property using a damped spring simulation driven by `requestAnimationFrame`.
+ *
+ * ```ts
+ * show({ when: (s) => s.open, render: () => content(), ...spring() })
+ * show({ ...spring({ property: 'transform', from: 0, to: 1 }) })
+ * ```
+ */
+export function spring(opts = {}) {
+    const stiffness = opts.stiffness ?? 170;
+    const damping = opts.damping ?? 26;
+    const mass = opts.mass ?? 1;
+    const precision = opts.precision ?? 0.01;
+    const property = opts.property ?? 'opacity';
+    const from = opts.from ?? 0;
+    const to = opts.to ?? 1;
+    const enter = (nodes) => {
+        const els = asElements(nodes);
+        void animateSpring(els, from, to, property, stiffness, damping, mass, precision);
+    };
+    const leave = (nodes) => {
+        const els = asElements(nodes);
+        return animateSpring(els, to, from, property, stiffness, damping, mass, precision);
+    };
+    return { enter, leave };
+}

package/dist/stagger.d.ts

@@ -0,0 +1,26 @@
+import type { TransitionOptions } from '@llui/dom';
+export interface StaggerOptions {
+    /** Delay between each item in milliseconds (default: 30). */
+    delayPerItem?: number;
+    /** How to stagger leave animations: 'sequential' (same order as enter),
+     *  'reverse', or 'simultaneous' (no stagger). Default: 'simultaneous'. */
+    leaveOrder?: 'sequential' | 'reverse' | 'simultaneous';
+}
+/**
+ * Wrap any transition preset so that batch-entered items get staggered delays.
+ *
+ * Items entering within the same microtask are considered a "batch" and get
+ * sequential delays (`index * delayPerItem`). The counter resets after the
+ * microtask, so the next batch starts from 0.
+ *
+ * ```ts
+ * each({
+ *   items: s => s.items,
+ *   key: i => i.id,
+ *   render: ({ item }) => [...],
+ *   ...stagger(fade({ duration: 150 }), { delayPerItem: 30 }),
+ * })
+ * ```
+ */
+export declare function stagger(spec: TransitionOptions, opts?: StaggerOptions): TransitionOptions;
+//# sourceMappingURL=stagger.d.ts.map

package/dist/stagger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagger.d.ts","sourceRoot":"","sources":["../src/stagger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAElD,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;8EAC0E;IAC1E,UAAU,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,cAAc,CAAA;CACvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,iBAAiB,CAwHzF"}

package/dist/stagger.js

@@ -0,0 +1,134 @@
+/**
+ * Wrap any transition preset so that batch-entered items get staggered delays.
+ *
+ * Items entering within the same microtask are considered a "batch" and get
+ * sequential delays (`index * delayPerItem`). The counter resets after the
+ * microtask, so the next batch starts from 0.
+ *
+ * ```ts
+ * each({
+ *   items: s => s.items,
+ *   key: i => i.id,
+ *   render: ({ item }) => [...],
+ *   ...stagger(fade({ duration: 150 }), { delayPerItem: 30 }),
+ * })
+ * ```
+ */
+export function stagger(spec, opts) {
+    const delayPerItem = opts?.delayPerItem ?? 30;
+    const leaveOrder = opts?.leaveOrder ?? 'simultaneous';
+    // ── Enter stagger ──────────────────────────────────────────────
+    let enterIndex = 0;
+    let enterResetScheduled = false;
+    function resetEnterIndex() {
+        enterIndex = 0;
+        enterResetScheduled = false;
+    }
+    // ── Leave stagger ─────────────────────────────────────────────
+    let leaveIndex = 0;
+    let leaveResetScheduled = false;
+    let leaveBatchSize = 0;
+    function resetLeaveIndex() {
+        leaveIndex = 0;
+        leaveBatchSize = 0;
+        leaveResetScheduled = false;
+    }
+    const out = {};
+    if (spec.enter) {
+        const baseEnter = spec.enter;
+        out.enter = (nodes) => {
+            const idx = enterIndex++;
+            if (!enterResetScheduled) {
+                enterResetScheduled = true;
+                queueMicrotask(resetEnterIndex);
+            }
+            const delay = idx * delayPerItem;
+            if (delay === 0) {
+                return baseEnter(nodes);
+            }
+            return new Promise((resolve) => {
+                setTimeout(() => {
+                    const result = baseEnter(nodes);
+                    if (result && typeof result.then === 'function') {
+                        ;
+                        result.then(resolve, resolve);
+                    }
+                    else {
+                        resolve();
+                    }
+                }, delay);
+            });
+        };
+    }
+    if (spec.leave) {
+        const baseLeave = spec.leave;
+        out.leave = (nodes) => {
+            if (leaveOrder === 'simultaneous') {
+                return baseLeave(nodes);
+            }
+            const idx = leaveIndex++;
+            leaveBatchSize = leaveIndex;
+            if (!leaveResetScheduled) {
+                leaveResetScheduled = true;
+                queueMicrotask(resetLeaveIndex);
+            }
+            // For reverse order, compute delay after all items in the batch are known.
+            // Since we can't know the batch size ahead of time, we use a microtask
+            // to capture it, but the delay must be applied now. For reverse, we use
+            // a deferred approach: schedule the animation after the microtask.
+            if (leaveOrder === 'reverse') {
+                const capturedIdx = idx;
+                return new Promise((resolve) => {
+                    // Wait for microtask to know batch size, then schedule with reverse delay.
+                    queueMicrotask(() => {
+                        const reverseIdx = leaveBatchSize - 1 - capturedIdx;
+                        const delay = reverseIdx * delayPerItem;
+                        if (delay === 0) {
+                            const result = baseLeave(nodes);
+                            if (result && typeof result.then === 'function') {
+                                ;
+                                result.then(resolve, resolve);
+                            }
+                            else {
+                                resolve();
+                            }
+                        }
+                        else {
+                            setTimeout(() => {
+                                const result = baseLeave(nodes);
+                                if (result && typeof result.then === 'function') {
+                                    ;
+                                    result.then(resolve, resolve);
+                                }
+                                else {
+                                    resolve();
+                                }
+                            }, delay);
+                        }
+                    });
+                });
+            }
+            // sequential
+            const delay = idx * delayPerItem;
+            if (delay === 0) {
+                return baseLeave(nodes);
+            }
+            return new Promise((resolve) => {
+                setTimeout(() => {
+                    const result = baseLeave(nodes);
+                    if (result && typeof result.then === 'function') {
+                        ;
+                        result.then(resolve, resolve);
+                    }
+                    else {
+                        resolve();
+                    }
+                }, delay);
+            });
+        };
+    }
+    if (spec.onTransition) {
+        out.onTransition = spec.onTransition;
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llui/transitions",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@llui/dom": "^0.0.2"
+    "@llui/dom": "^0.0.3"
   },
   "devDependencies": {
     "@llui/dom": "workspace:*",