@llui/transitions 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Franco Ponticelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @llui/transitions
+
+Animation helpers for [LLui](https://github.com/fponticelli/llui).
+
+`transition()` core + `fade`, `slide`, `scale`, `collapse` presets. Works with `branch`/`show`/`each` enter/leave hooks. Includes `flip()` for FLIP reorder animations and `mergeTransitions()` for combining.
+
+```bash
+pnpm add @llui/transitions
+```
+
+## License
+
+MIT

package/dist/flip.d.ts

@@ -0,0 +1,46 @@
+import type { TransitionOptions } from '@llui/dom';
+export interface FlipOptions {
+    duration?: number;
+    easing?: string;
+}
+/**
+ * FLIP (First-Last-Invert-Play) reorder animation for `each()` lists.
+ *
+ * Attach to an `each()` alongside item enter/leave transitions. After each
+ * reconcile, items whose positions changed animate smoothly from their
+ * previous position to the new one.
+ *
+ * ```ts
+ * each({
+ *   items: s => s.items,
+ *   key: i => i.id,
+ *   render,
+ *   ...fade(),         // animates appear/disappear
+ *   ...flip(),         // animates reorders
+ * })
+ * ```
+ *
+ * Spreading two transition helpers merges their hooks: `fade()` provides
+ * `enter`/`leave`, `flip()` provides `enter` (position capture) and
+ * `onTransition` (apply inverse + play). The `enter` from `flip()` overrides
+ * `fade()`'s only if spread after — put `flip()` last.
+ *
+ * Actually, to combine both, use `mergeTransitions(fade(), flip())` which
+ * chains `enter` handlers.
+ *
+ * Requires WAAPI (`element.animate()`). In environments without it (old
+ * browsers, minimal jsdom) the transforms are applied without animation.
+ */
+export declare function flip(opts?: FlipOptions): TransitionOptions;
+/**
+ * Merge multiple TransitionOptions into one, chaining their `enter`,
+ * `leave`, and `onTransition` handlers in order.
+ *
+ * Useful for combining an item-level animation (fade/slide/...) with flip():
+ *
+ * ```ts
+ * each({ items, key, render, ...mergeTransitions(fade(), flip()) })
+ * ```
+ */
+export declare function mergeTransitions(...parts: TransitionOptions[]): TransitionOptions;
+//# sourceMappingURL=flip.d.ts.map

package/dist/flip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flip.d.ts","sourceRoot":"","sources":["../src/flip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAGlD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,GAAG,iBAAiB,CAoD9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,KAAK,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,CA4BjF"}

package/dist/flip.js

@@ -0,0 +1,120 @@
+import { asElements } from './style-utils';
+/**
+ * FLIP (First-Last-Invert-Play) reorder animation for `each()` lists.
+ *
+ * Attach to an `each()` alongside item enter/leave transitions. After each
+ * reconcile, items whose positions changed animate smoothly from their
+ * previous position to the new one.
+ *
+ * ```ts
+ * each({
+ *   items: s => s.items,
+ *   key: i => i.id,
+ *   render,
+ *   ...fade(),         // animates appear/disappear
+ *   ...flip(),         // animates reorders
+ * })
+ * ```
+ *
+ * Spreading two transition helpers merges their hooks: `fade()` provides
+ * `enter`/`leave`, `flip()` provides `enter` (position capture) and
+ * `onTransition` (apply inverse + play). The `enter` from `flip()` overrides
+ * `fade()`'s only if spread after — put `flip()` last.
+ *
+ * Actually, to combine both, use `mergeTransitions(fade(), flip())` which
+ * chains `enter` handlers.
+ *
+ * Requires WAAPI (`element.animate()`). In environments without it (old
+ * browsers, minimal jsdom) the transforms are applied without animation.
+ */
+export function flip(opts = {}) {
+    const duration = opts.duration ?? 300;
+    const easing = opts.easing ?? 'ease-out';
+    const positions = new WeakMap();
+    const tracked = new Set();
+    const captureAfterFrame = (els) => {
+        const run = () => {
+            for (const el of els) {
+                if (el.isConnected)
+                    positions.set(el, el.getBoundingClientRect());
+            }
+        };
+        if (typeof requestAnimationFrame === 'function') {
+            requestAnimationFrame(run);
+        }
+        else {
+            run();
+        }
+    };
+    return {
+        enter: (nodes) => {
+            const els = asElements(nodes);
+            for (const el of els)
+                tracked.add(el);
+            captureAfterFrame(els);
+        },
+        leave: (nodes) => {
+            for (const el of asElements(nodes))
+                tracked.delete(el);
+        },
+        onTransition: () => {
+            // Snapshot current set (tracked may mutate during iteration).
+            const current = Array.from(tracked);
+            for (const el of current) {
+                if (!el.isConnected) {
+                    tracked.delete(el);
+                    continue;
+                }
+                const prev = positions.get(el);
+                const next = el.getBoundingClientRect();
+                if (prev && (prev.left !== next.left || prev.top !== next.top)) {
+                    const dx = prev.left - next.left;
+                    const dy = prev.top - next.top;
+                    if (typeof el.animate === 'function') {
+                        el.animate([{ transform: `translate(${dx}px, ${dy}px)` }, { transform: 'translate(0, 0)' }], { duration, easing, fill: 'backwards' });
+                    }
+                }
+                positions.set(el, next);
+            }
+        },
+    };
+}
+/**
+ * Merge multiple TransitionOptions into one, chaining their `enter`,
+ * `leave`, and `onTransition` handlers in order.
+ *
+ * Useful for combining an item-level animation (fade/slide/...) with flip():
+ *
+ * ```ts
+ * each({ items, key, render, ...mergeTransitions(fade(), flip()) })
+ * ```
+ */
+export function mergeTransitions(...parts) {
+    const enters = parts.map((p) => p.enter).filter((f) => !!f);
+    const leaves = parts.map((p) => p.leave).filter((f) => !!f);
+    const onTs = parts.map((p) => p.onTransition).filter((f) => !!f);
+    const out = {};
+    if (enters.length > 0) {
+        out.enter = (nodes) => {
+            for (const fn of enters)
+                void fn(nodes);
+        };
+    }
+    if (leaves.length > 0) {
+        out.leave = (nodes) => {
+            // Wait for all leaves to resolve.
+            const results = leaves.map((fn) => fn(nodes));
+            const promises = results.filter((r) => !!r && typeof r.then === 'function');
+            if (promises.length === 0)
+                return;
+            return Promise.all(promises).then(() => undefined);
+        };
+    }
+    if (onTs.length > 0) {
+        out.onTransition = (ctx) => {
+            for (const fn of onTs)
+                void fn(ctx);
+        };
+    }
+    return out;
+}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// Core primitive
+export { transition } from './transition';
+// Presets
+export { fade, slide, scale, collapse } from './presets';
+// Reorder animation + composition
+export { flip, mergeTransitions } from './flip';

package/dist/presets.d.ts

@@ -0,0 +1,48 @@
+import type { TransitionOptions } from '@llui/dom';
+export interface FadeOptions {
+    duration?: number;
+    easing?: string;
+    appear?: boolean;
+}
+export declare function fade(opts?: FadeOptions): TransitionOptions;
+export type SlideDirection = 'up' | 'down' | 'left' | 'right';
+export interface SlideOptions {
+    /** The direction the element slides IN from (default: 'down' — enters from below). */
+    direction?: SlideDirection;
+    /** Pixel distance to slide (default: 20). */
+    distance?: number;
+    duration?: number;
+    easing?: string;
+    /** Also animate opacity (default: true). */
+    fade?: boolean;
+    appear?: boolean;
+}
+export declare function slide(opts?: SlideOptions): TransitionOptions;
+export interface ScaleOptions {
+    /** Starting scale factor (default: 0.95). */
+    from?: number;
+    duration?: number;
+    easing?: string;
+    /** Also animate opacity (default: true). */
+    fade?: boolean;
+    /** Transform origin (default: 'center'). */
+    origin?: string;
+    appear?: boolean;
+}
+export declare function scale(opts?: ScaleOptions): TransitionOptions;
+export interface CollapseOptions {
+    /** Axis to collapse: 'y' = height, 'x' = width (default: 'y'). */
+    axis?: 'x' | 'y';
+    duration?: number;
+    easing?: string;
+    appear?: boolean;
+}
+/**
+ * Animate an element open/closed along the y-axis (height) or x-axis (width).
+ *
+ * Unlike CSS-only presets, `collapse()` measures the element's natural size
+ * at runtime — the animation works regardless of content size. Only the
+ * first element in each `nodes` group is animated.
+ */
+export declare function collapse(opts?: CollapseOptions): TransitionOptions;
+//# sourceMappingURL=presets.d.ts.map

package/dist/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAKlD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,GAAG,iBAAiB,CAc9D;AAED,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE7D,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,SAAS,CAAC,EAAE,cAAc,CAAA;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4CAA4C;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,KAAK,CAAC,IAAI,GAAE,YAAiB,GAAG,iBAAiB,CA4BhE;AAeD,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4CAA4C;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,KAAK,CAAC,IAAI,GAAE,YAAiB,GAAG,iBAAiB,CA8BhE;AAED,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,iBAAiB,CAyDtE"}

package/dist/presets.js

@@ -0,0 +1,146 @@
+import { transition } from './transition';
+import { asElements, forceReflow } from './style-utils';
+export function fade(opts = {}) {
+    const duration = opts.duration ?? 200;
+    const easing = opts.easing ?? 'ease-out';
+    const active = { transition: `opacity ${duration}ms ${easing}` };
+    return transition({
+        appear: opts.appear,
+        duration,
+        enterActive: active,
+        enterFrom: { opacity: 0 },
+        enterTo: { opacity: 1 },
+        leaveActive: active,
+        leaveFrom: { opacity: 1 },
+        leaveTo: { opacity: 0 },
+    });
+}
+export function slide(opts = {}) {
+    const direction = opts.direction ?? 'down';
+    const distance = opts.distance ?? 20;
+    const duration = opts.duration ?? 250;
+    const easing = opts.easing ?? 'ease-out';
+    const withFade = opts.fade !== false;
+    const offset = slideOffset(direction, distance);
+    const props = withFade ? 'transform, opacity' : 'transform';
+    const active = { transition: `${props} ${duration}ms ${easing}` };
+    const hidden = { transform: offset };
+    const visible = { transform: 'translate(0, 0)' };
+    if (withFade) {
+        hidden.opacity = 0;
+        visible.opacity = 1;
+    }
+    return transition({
+        appear: opts.appear,
+        duration,
+        enterActive: active,
+        enterFrom: hidden,
+        enterTo: visible,
+        leaveActive: active,
+        leaveFrom: visible,
+        leaveTo: hidden,
+    });
+}
+function slideOffset(direction, distance) {
+    switch (direction) {
+        case 'down':
+            return `translate(0, -${distance}px)`;
+        case 'up':
+            return `translate(0, ${distance}px)`;
+        case 'right':
+            return `translate(-${distance}px, 0)`;
+        case 'left':
+            return `translate(${distance}px, 0)`;
+    }
+}
+export function scale(opts = {}) {
+    const from = opts.from ?? 0.95;
+    const duration = opts.duration ?? 200;
+    const easing = opts.easing ?? 'ease-out';
+    const withFade = opts.fade !== false;
+    const origin = opts.origin ?? 'center';
+    const props = withFade ? 'transform, opacity' : 'transform';
+    const active = {
+        transition: `${props} ${duration}ms ${easing}`,
+        transformOrigin: origin,
+    };
+    const hidden = { transform: `scale(${from})` };
+    const visible = { transform: 'scale(1)' };
+    if (withFade) {
+        hidden.opacity = 0;
+        visible.opacity = 1;
+    }
+    return transition({
+        appear: opts.appear,
+        duration,
+        enterActive: active,
+        enterFrom: hidden,
+        enterTo: visible,
+        leaveActive: active,
+        leaveFrom: visible,
+        leaveTo: hidden,
+    });
+}
+/**
+ * Animate an element open/closed along the y-axis (height) or x-axis (width).
+ *
+ * Unlike CSS-only presets, `collapse()` measures the element's natural size
+ * at runtime — the animation works regardless of content size. Only the
+ * first element in each `nodes` group is animated.
+ */
+export function collapse(opts = {}) {
+    const axis = opts.axis ?? 'y';
+    const duration = opts.duration ?? 250;
+    const easing = opts.easing ?? 'ease-out';
+    const appear = opts.appear !== false;
+    const sizeProp = axis === 'y' ? 'height' : 'width';
+    const runEnter = (nodes) => {
+        const els = asElements(nodes);
+        if (els.length === 0)
+            return Promise.resolve();
+        const el = els[0];
+        // Measure natural size with content visible.
+        const naturalSize = axis === 'y' ? el.scrollHeight : el.scrollWidth;
+        const style = el.style;
+        // Save values to restore.
+        const prevOverflow = style.overflow;
+        const prevSize = style[sizeProp];
+        const prevTransition = style.transition;
+        style.overflow = 'hidden';
+        style[sizeProp] = '0px';
+        style.transition = `${sizeProp} ${duration}ms ${easing}`;
+        forceReflow(el);
+        style[sizeProp] = `${naturalSize}px`;
+        return wait(duration).then(() => {
+            style.overflow = prevOverflow;
+            style[sizeProp] = prevSize;
+            style.transition = prevTransition;
+        });
+    };
+    const runLeave = (nodes) => {
+        const els = asElements(nodes);
+        if (els.length === 0)
+            return Promise.resolve();
+        const el = els[0];
+        const naturalSize = axis === 'y' ? el.scrollHeight : el.scrollWidth;
+        const style = el.style;
+        style.overflow = 'hidden';
+        style[sizeProp] = `${naturalSize}px`;
+        style.transition = `${sizeProp} ${duration}ms ${easing}`;
+        forceReflow(el);
+        style[sizeProp] = '0px';
+        return wait(duration);
+    };
+    const out = { leave: runLeave };
+    if (appear) {
+        out.enter = (nodes) => {
+            void runEnter(nodes);
+        };
+    }
+    return out;
+}
+function wait(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => setTimeout(resolve, ms + 16));
+}

package/dist/style-utils.d.ts

@@ -0,0 +1,19 @@
+import type { TransitionValue } from './types';
+/**
+ * Filter an array of nodes down to HTMLElements — transition animations
+ * only apply to elements, not comment anchors or text nodes.
+ */
+export declare function asElements(nodes: Node[]): HTMLElement[];
+/** Apply a TransitionValue (classes, styles, or a mix) to an element. */
+export declare function applyValue(el: HTMLElement, value: TransitionValue | undefined): void;
+/** Remove a TransitionValue from an element. */
+export declare function removeValue(el: HTMLElement, value: TransitionValue | undefined): void;
+/**
+ * Detect total transition duration from computed styles.
+ * Returns the maximum of (transition-duration + transition-delay) and
+ * (animation-duration + animation-delay), in milliseconds.
+ */
+export declare function detectDuration(el: HTMLElement): number;
+/** Force a style recalculation so subsequent class/style changes animate. */
+export declare function forceReflow(el: HTMLElement): void;
+//# sourceMappingURL=style-utils.d.ts.map

package/dist/style-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style-utils.d.ts","sourceRoot":"","sources":["../src/style-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,eAAe,EAAE,MAAM,SAAS,CAAA;AA0CtD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,WAAW,EAAE,CAMvD;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAcpF;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAcrF;AA0BD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAKtD;AAiBD,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAGjD"}

package/dist/style-utils.js

@@ -0,0 +1,145 @@
+// CSS properties that are unitless when given a numeric value.
+// All other numeric values are suffixed with `px`.
+const UNITLESS = new Set([
+    'opacity',
+    'flex',
+    'flexGrow',
+    'flexShrink',
+    'flexNegative',
+    'order',
+    'zIndex',
+    'fontWeight',
+    'lineHeight',
+    'zoom',
+    'gridRow',
+    'gridRowStart',
+    'gridRowEnd',
+    'gridColumn',
+    'gridColumnStart',
+    'gridColumnEnd',
+    'columnCount',
+    'tabSize',
+    'scale',
+    'aspectRatio',
+]);
+function formatStyleValue(prop, value) {
+    if (typeof value === 'string')
+        return value;
+    if (UNITLESS.has(prop))
+        return String(value);
+    return `${value}px`;
+}
+function splitClasses(raw) {
+    const out = [];
+    const parts = raw.split(/\s+/);
+    for (const p of parts) {
+        if (p.length > 0)
+            out.push(p);
+    }
+    return out;
+}
+/**
+ * Filter an array of nodes down to HTMLElements — transition animations
+ * only apply to elements, not comment anchors or text nodes.
+ */
+export function asElements(nodes) {
+    const out = [];
+    for (const n of nodes) {
+        if (n.nodeType === 1)
+            out.push(n);
+    }
+    return out;
+}
+/** Apply a TransitionValue (classes, styles, or a mix) to an element. */
+export function applyValue(el, value) {
+    if (value == null)
+        return;
+    if (typeof value === 'string') {
+        applyClasses(el, value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const part of value) {
+            if (typeof part === 'string')
+                applyClasses(el, part);
+            else
+                applyStyles(el, part);
+        }
+        return;
+    }
+    applyStyles(el, value);
+}
+/** Remove a TransitionValue from an element. */
+export function removeValue(el, value) {
+    if (value == null)
+        return;
+    if (typeof value === 'string') {
+        removeClasses(el, value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const part of value) {
+            if (typeof part === 'string')
+                removeClasses(el, part);
+            else
+                removeStyles(el, part);
+        }
+        return;
+    }
+    removeStyles(el, value);
+}
+function applyClasses(el, raw) {
+    const classes = splitClasses(raw);
+    if (classes.length > 0)
+        el.classList.add(...classes);
+}
+function removeClasses(el, raw) {
+    const classes = splitClasses(raw);
+    if (classes.length > 0)
+        el.classList.remove(...classes);
+}
+function applyStyles(el, styles) {
+    const decl = el.style;
+    for (const key in styles) {
+        decl[key] = formatStyleValue(key, styles[key]);
+    }
+}
+function removeStyles(el, styles) {
+    const decl = el.style;
+    for (const key in styles) {
+        decl[key] = '';
+    }
+}
+/**
+ * Detect total transition duration from computed styles.
+ * Returns the maximum of (transition-duration + transition-delay) and
+ * (animation-duration + animation-delay), in milliseconds.
+ */
+export function detectDuration(el) {
+    const cs = getComputedStyle(el);
+    const t = parseTime(cs.transitionDuration) + parseTime(cs.transitionDelay);
+    const a = parseTime(cs.animationDuration) + parseTime(cs.animationDelay);
+    return Math.max(t, a);
+}
+function parseTime(raw) {
+    if (!raw)
+        return 0;
+    let max = 0;
+    const parts = raw.split(',');
+    for (const part of parts) {
+        const trimmed = part.trim();
+        const m = trimmed.match(/^([\d.]+)(m?s)$/);
+        if (!m)
+            continue;
+        const n = parseFloat(m[1]);
+        const ms = m[2] === 's' ? n * 1000 : n;
+        if (ms > max)
+            max = ms;
+    }
+    return max;
+}
+/** Force a style recalculation so subsequent class/style changes animate. */
+export function forceReflow(el) {
+    // Reading an offset property forces synchronous layout.
+    void el.offsetHeight;
+}

package/dist/transition.d.ts

@@ -0,0 +1,21 @@
+import type { TransitionOptions } from '@llui/dom';
+import type { TransitionSpec } from './types';
+/**
+ * Build a `TransitionOptions` bundle ({ enter, leave }) from a spec.
+ *
+ * Pass the result into `branch`, `show`, or `each` to animate the enter/leave
+ * of that structural block.
+ *
+ * Lifecycle:
+ *  - **enter**: apply `enterFrom` + `enterActive` → reflow → swap `enterFrom` → `enterTo`
+ *    → wait for duration → remove all transient values (element rests on its base styles).
+ *  - **leave**: apply `leaveFrom` + `leaveActive` → reflow → swap `leaveFrom` → `leaveTo`
+ *    → wait for duration (Promise-resolved so DOM removal is deferred).
+ *
+ * Duration:
+ *  - If `duration` is given, it is used verbatim.
+ *  - Otherwise, computed `transition-duration + transition-delay` is read after
+ *    the active/from classes are applied, taking the max across properties.
+ */
+export declare function transition(spec: TransitionSpec): TransitionOptions;
+//# sourceMappingURL=transition.d.ts.map

package/dist/transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition.d.ts","sourceRoot":"","sources":["../src/transition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAM7C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,iBAAiB,CA+DlE"}

package/dist/transition.js

@@ -0,0 +1,79 @@
+import { applyValue, removeValue, asElements, detectDuration, forceReflow } from './style-utils';
+// Buffer added to setTimeout so styles have settled before resolution.
+const TIMING_BUFFER_MS = 16;
+/**
+ * Build a `TransitionOptions` bundle ({ enter, leave }) from a spec.
+ *
+ * Pass the result into `branch`, `show`, or `each` to animate the enter/leave
+ * of that structural block.
+ *
+ * Lifecycle:
+ *  - **enter**: apply `enterFrom` + `enterActive` → reflow → swap `enterFrom` → `enterTo`
+ *    → wait for duration → remove all transient values (element rests on its base styles).
+ *  - **leave**: apply `leaveFrom` + `leaveActive` → reflow → swap `leaveFrom` → `leaveTo`
+ *    → wait for duration (Promise-resolved so DOM removal is deferred).
+ *
+ * Duration:
+ *  - If `duration` is given, it is used verbatim.
+ *  - Otherwise, computed `transition-duration + transition-delay` is read after
+ *    the active/from classes are applied, taking the max across properties.
+ */
+export function transition(spec) {
+    const appear = spec.appear !== false;
+    const runEnter = (nodes) => {
+        const els = asElements(nodes);
+        if (els.length === 0)
+            return Promise.resolve();
+        // Apply from + active
+        for (const el of els) {
+            applyValue(el, spec.enterFrom);
+            applyValue(el, spec.enterActive);
+        }
+        // Force reflow so the next class change triggers a transition.
+        forceReflow(els[0]);
+        // Move to target state
+        for (const el of els) {
+            removeValue(el, spec.enterFrom);
+            applyValue(el, spec.enterTo);
+        }
+        const duration = spec.duration ?? detectDuration(els[0]);
+        return wait(duration).then(() => {
+            for (const el of els) {
+                removeValue(el, spec.enterActive);
+                removeValue(el, spec.enterTo);
+            }
+        });
+    };
+    const runLeave = (nodes) => {
+        const els = asElements(nodes);
+        if (els.length === 0)
+            return Promise.resolve();
+        for (const el of els) {
+            applyValue(el, spec.leaveFrom);
+            applyValue(el, spec.leaveActive);
+        }
+        forceReflow(els[0]);
+        for (const el of els) {
+            removeValue(el, spec.leaveFrom);
+            applyValue(el, spec.leaveTo);
+        }
+        const duration = spec.duration ?? detectDuration(els[0]);
+        return wait(duration);
+    };
+    const out = {
+        leave: runLeave,
+    };
+    if (appear) {
+        out.enter = (nodes) => {
+            void runEnter(nodes);
+        };
+    }
+    return out;
+}
+function wait(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms + TIMING_BUFFER_MS);
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CSS style properties as a plain object. Numeric values are automatically
+ * suffixed with `px` for known dimensional properties.
+ *
+ * Example: `{ opacity: 0, transform: 'scale(0.95)', width: 200 }`
+ */
+export type Styles = Record<string, string | number>;
+/**
+ * One "state" in a transition.
+ *
+ * - `string` — space-separated class names (applied via classList)
+ * - `Styles` — inline style object (applied via element.style)
+ * - `Array<string | Styles>` — mix both (useful for utility classes + dynamic styles)
+ */
+export type TransitionValue = string | Styles | Array<string | Styles>;
+export interface TransitionSpec {
+    /** Initial state before enter animation (removed once enter completes). */
+    enterFrom?: TransitionValue;
+    /** Final state during enter animation (removed once enter completes). */
+    enterTo?: TransitionValue;
+    /** Applied throughout enter (typically the `transition-*` / `animation` properties). */
+    enterActive?: TransitionValue;
+    /** Initial state before leave animation. */
+    leaveFrom?: TransitionValue;
+    /** Final state during leave animation. */
+    leaveTo?: TransitionValue;
+    /** Applied throughout leave. */
+    leaveActive?: TransitionValue;
+    /**
+     * Explicit duration in milliseconds. When omitted, the duration is read from
+     * the element's computed `transition-duration` / `transition-delay` after the
+     * active classes are applied.
+     */
+    duration?: number;
+    /** If true, run the enter transition on initial mount (default: true). */
+    appear?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;AAEtE,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,yEAAyE;IACzE,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,wFAAwF;IACxF,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,0CAA0C;IAC1C,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,gCAAgC;IAChC,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@llui/transitions",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit -p tsconfig.check.json",
+    "lint": "eslint src",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@llui/dom": "^0.0.1"
+  },
+  "devDependencies": {
+    "@llui/dom": "workspace:*",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.2"
+  },
+  "sideEffects": false,
+  "description": "LLui animation helpers — transition(), fade, slide, scale, collapse for branch/show/each",
+  "keywords": [
+    "llui",
+    "transitions",
+    "animation",
+    "fade",
+    "slide"
+  ],
+  "author": "Franco Ponticelli <franco.ponticelli@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fponticelli/llui.git",
+    "directory": "packages/transitions"
+  },
+  "bugs": {
+    "url": "https://github.com/fponticelli/llui/issues"
+  },
+  "homepage": "https://github.com/fponticelli/llui/tree/main/packages/transitions#readme",
+  "files": [
+    "dist"
+  ]
+}