@texuli/core 0.5.0 → 0.7.0

package/dist/motion/presence.js

@@ -0,0 +1,231 @@
+/**
+ * Motion presence: enter and exit animations with interruptible reversal
+ * (ADR-013), on the `@texuli/core/presence` vocabulary (`PresenceSnapshot`,
+ * `data-state`).
+ *
+ * The core presence waits for CSS `transitionend` / `animationend`; Web
+ * Animations fire neither, and an unrelated CSS transition on the node would
+ * end the exit early, so this machine drives the same snapshot from its own
+ * animations instead. Toggling mid-flight reverses the running animation from
+ * where it is (no jump) and resolves the earlier transition `"interrupted"`.
+ *
+ * Nothing animates on the server or on hydration: the first attached node
+ * with `present: true` shows at once unless `appear` is set.
+ */
+import { PRESENCE_STATE_ATTR, } from "../presence/presence.js";
+import { resolveMotion, startAnimation, } from "./animate.js";
+const DEFAULT_ENTER = [{ opacity: 0 }, { opacity: 1 }];
+function reverseFrames(frames) {
+    if (Array.isArray(frames)) {
+        return [...frames].reverse().map((frame) => {
+            const { offset, ...rest } = frame;
+            return typeof offset === 'number' ? { ...rest, offset: 1 - offset } : rest;
+        });
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(frames)) {
+        out[key] = Array.isArray(value) ? [...value].reverse() : value;
+    }
+    return out;
+}
+/**
+ * Create a motion presence controller.
+ *
+ * @example
+ * const presence = createMotionPresence({
+ *   enter: [{ opacity: 0, transform: 'scale(0.96)' }, { opacity: 1, transform: 'none' }],
+ *   onExitComplete: (s) => { if (!s.mounted) unmount(); },
+ * });
+ * presence.setNode(panel);
+ * await presence.setPresent(false); // "finished", or "instant" under reduced motion
+ */
+export function createMotionPresence(options = {}) {
+    const forceMount = options.forceMount === true;
+    const enterFrames = options.enter ?? DEFAULT_ENTER;
+    const exitFrames = options.exit ?? reverseFrames(enterFrames);
+    const timing = options;
+    const exitTiming = { ...options, ...options.exitTiming };
+    let present = options.present === true;
+    let mounted = present || forceMount;
+    let state = present ? 'open' : 'closed';
+    let exiting = false;
+    let node = null;
+    let pendingEnter = present && options.appear === true;
+    let animation = null;
+    let direction = null;
+    let disposed = false;
+    let settle = null;
+    let finished = Promise.resolve('instant');
+    const snapshot = () => ({ present, mounted, state, exiting });
+    const writeAttr = () => {
+        node?.setAttribute(PRESENCE_STATE_ATTR, state);
+    };
+    const emit = () => options.onSnapshot?.(snapshot());
+    function begin() {
+        settle?.('interrupted');
+        let resolve = () => { };
+        finished = new Promise((r) => {
+            resolve = r;
+        });
+        let done = false;
+        settle = (outcome) => {
+            if (done)
+                return;
+            done = true;
+            settle = null;
+            resolve(outcome);
+        };
+        return finished;
+    }
+    function dropAnimation() {
+        const current = animation;
+        animation = null;
+        direction = null;
+        if (current) {
+            current.onfinish = null;
+            try {
+                current.cancel();
+            }
+            catch {
+                // Already gone.
+            }
+        }
+    }
+    function complete(dir, outcome) {
+        animation = null;
+        direction = null;
+        if (dir === 'exit') {
+            exiting = false;
+            state = 'closed';
+            if (!forceMount)
+                mounted = false;
+            writeAttr();
+            const s = snapshot();
+            options.onSnapshot?.(s);
+            options.onExitComplete?.(s);
+        }
+        else {
+            options.onEnterComplete?.(snapshot());
+        }
+        settle?.(outcome);
+    }
+    function play(dir) {
+        const target = node;
+        const plan = resolveMotion(target, dir === 'enter' ? enterFrames : exitFrames, dir === 'enter' ? timing : exitTiming);
+        const started = !plan.instant && target ? startAnimation(target, plan) : null;
+        if (!started) {
+            complete(dir, 'instant');
+            return;
+        }
+        animation = started;
+        direction = dir;
+        started.onfinish = () => {
+            if (animation !== started || direction === null)
+                return;
+            complete(direction, 'finished');
+        };
+    }
+    /** Reverse the running animation in place; false when there is none to reverse. */
+    function reverseTo(dir) {
+        const current = animation;
+        if (!current || direction === dir || typeof current.reverse !== 'function')
+            return false;
+        try {
+            current.reverse();
+        }
+        catch {
+            return false;
+        }
+        direction = dir;
+        return true;
+    }
+    return {
+        getSnapshot: snapshot,
+        get finished() {
+            return finished;
+        },
+        setPresent(next) {
+            if (disposed)
+                return Promise.resolve('cancelled');
+            if (next) {
+                if (present && state === 'open' && !exiting)
+                    return finished;
+                present = true;
+                exiting = false;
+                mounted = true;
+                state = 'open';
+                writeAttr();
+                const result = begin();
+                emit();
+                options.onEnter?.(snapshot());
+                if (reverseTo('enter'))
+                    return result;
+                dropAnimation();
+                if (node)
+                    play('enter');
+                else
+                    pendingEnter = true;
+                return result;
+            }
+            present = false;
+            if (!mounted || (state === 'closed' && !exiting)) {
+                state = 'closed';
+                writeAttr();
+                return finished;
+            }
+            if (exiting)
+                return finished;
+            pendingEnter = false;
+            exiting = true;
+            state = 'closed';
+            writeAttr();
+            const result = begin();
+            emit();
+            if (reverseTo('exit'))
+                return result;
+            dropAnimation();
+            if (node)
+                play('exit');
+            else
+                complete('exit', 'instant');
+            return result;
+        },
+        setNode(next) {
+            if (disposed || next === node)
+                return;
+            if (animation) {
+                // The animated element changed: its animation cannot continue elsewhere.
+                const dir = direction ?? 'enter';
+                dropAnimation();
+                node = next;
+                writeAttr();
+                if (next)
+                    play(dir);
+                else
+                    complete(dir, 'instant');
+                return;
+            }
+            node = next;
+            writeAttr();
+            if (!next) {
+                if (exiting)
+                    complete('exit', 'instant');
+                return;
+            }
+            if (pendingEnter && present) {
+                pendingEnter = false;
+                if (!settle)
+                    begin();
+                play('enter');
+            }
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            dropAnimation();
+            settle?.('cancelled');
+            node = null;
+        },
+    };
+}

package/dist/motion/sequence.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Sequences and timelines (ADR-013): declared steps played as Web Animations
+ * on one shared clock.
+ *
+ * Top-level entries run one after another; a `parallel(...)` group runs its
+ * steps together (the group lasts as long as its longest step). Each step may
+ * add an `at` offset inside its slot, which is how `stagger` spreads a list.
+ * Every animation gets the same total length (`delay` + `duration` +
+ * `endDelay`), so `seek`, `pause` and `reverse` keep the steps aligned.
+ *
+ * Under reduced motion, at level `none`, without the Web Animations API or on
+ * the server, the timeline commits at once: `finished` resolves `"instant"`
+ * and `onFinish` fires once; play, pause, seek and reverse do nothing.
+ */
+import { type InstantReason, type MotionKeyframes, type MotionOutcome, type MotionTiming } from './animate.js';
+/** One animated step. */
+export type TimelineStep = {
+    readonly target: Element | null | undefined;
+    readonly keyframes: MotionKeyframes;
+    /** Milliseconds (clamped to [0, 1000]). Default: the timeline's `duration`. */
+    readonly duration?: number;
+    readonly easing?: string;
+    /** Extra offset inside the step's slot, in ms (clamped to [0, 1000]). */
+    readonly at?: number;
+};
+/** A group whose steps run together. */
+export type ParallelGroup = {
+    readonly parallel: readonly TimelineStep[];
+};
+export type TimelineEntry = TimelineStep | ParallelGroup;
+export type TimelineOptions = MotionTiming & {
+    /** Start playing at once. `timeline` defaults to `false`, `sequence` to `true`. */
+    autoplay?: boolean;
+    onFinish?: (outcome: MotionOutcome) => void;
+};
+export type Timeline = {
+    /** Total length in ms after the level is applied (0 when instant). */
+    readonly duration: number;
+    readonly finished: Promise<MotionOutcome>;
+    readonly instantReason: InstantReason | null;
+    readonly animations: readonly Animation[];
+    play: () => void;
+    pause: () => void;
+    /** Move every step to `ms` on the shared clock (clamped to [0, duration]). */
+    seek: (ms: number) => void;
+    /** Play backwards from the current time. */
+    reverse: () => void;
+    cancel: () => void;
+    finish: () => void;
+};
+/** Most steps one timeline animates; past it the timeline commits at once. */
+export declare const MAX_TIMELINE_STEPS = 500;
+/** Longest stagger spread, in ms: a long list compresses its per-item offset to fit. */
+export declare const MAX_STAGGER_SPAN = 1000;
+/** Group steps to run in parallel. */
+export declare function parallel(...steps: TimelineStep[]): ParallelGroup;
+export type StaggerOptions = {
+    /** Which item starts first. Default `"start"`. */
+    from?: 'start' | 'end' | 'center' | number;
+};
+/**
+ * Offsets in ms for `count` items `each` ms apart, spread from `from`. The
+ * whole spread is held to {@link MAX_STAGGER_SPAN} (a long list staggers
+ * faster instead of taking longer). `count` is clamped to [0, 10000].
+ */
+export declare function stagger(count: number, each: number, options?: StaggerOptions): number[];
+/** Build a timeline, paused until `play()` unless `autoplay` is true. */
+export declare function timeline(entries: readonly TimelineEntry[], options?: TimelineOptions): Timeline;
+/** Play steps now (a timeline that autoplays unless `autoplay: false`). */
+export declare function sequence(entries: readonly TimelineEntry[], options?: TimelineOptions): Timeline;

package/dist/motion/sequence.js

@@ -0,0 +1,159 @@
+/**
+ * Sequences and timelines (ADR-013): declared steps played as Web Animations
+ * on one shared clock.
+ *
+ * Top-level entries run one after another; a `parallel(...)` group runs its
+ * steps together (the group lasts as long as its longest step). Each step may
+ * add an `at` offset inside its slot, which is how `stagger` spreads a list.
+ * Every animation gets the same total length (`delay` + `duration` +
+ * `endDelay`), so `seek`, `pause` and `reverse` keep the steps aligned.
+ *
+ * Under reduced motion, at level `none`, without the Web Animations API or on
+ * the server, the timeline commits at once: `finished` resolves `"instant"`
+ * and `onFinish` fires once; play, pause, seek and reverse do nothing.
+ */
+import { createRun, resolveMotion, startAnimation, } from "./animate.js";
+import { MAX_MOTION_MS, motionDuration } from "./preferences.js";
+/** Most steps one timeline animates; past it the timeline commits at once. */
+export const MAX_TIMELINE_STEPS = 500;
+/** Longest stagger spread, in ms: a long list compresses its per-item offset to fit. */
+export const MAX_STAGGER_SPAN = MAX_MOTION_MS;
+/** Group steps to run in parallel. */
+export function parallel(...steps) {
+    return { parallel: steps };
+}
+/**
+ * Offsets in ms for `count` items `each` ms apart, spread from `from`. The
+ * whole spread is held to {@link MAX_STAGGER_SPAN} (a long list staggers
+ * faster instead of taking longer). `count` is clamped to [0, 10000].
+ */
+export function stagger(count, each, options = {}) {
+    const n = Math.max(0, Math.min(10_000, Math.floor(Number.isFinite(count) ? count : 0)));
+    if (n === 0)
+        return [];
+    const origin = options.from === 'end'
+        ? n - 1
+        : options.from === 'center'
+            ? (n - 1) / 2
+            : typeof options.from === 'number' && Number.isFinite(options.from)
+                ? Math.max(0, Math.min(n - 1, Math.floor(options.from)))
+                : 0;
+    const reach = Math.max(origin, n - 1 - origin);
+    const step = Number.isFinite(each) && each > 0 ? each : 0;
+    const per = reach > 0 ? Math.min(step, MAX_STAGGER_SPAN / reach) : 0;
+    return Array.from({ length: n }, (_, i) => Math.round(Math.abs(i - origin) * per * 100) / 100);
+}
+function planOf(step, options) {
+    return resolveMotion(step?.target, step?.keyframes ?? [], {
+        ...options,
+        duration: step?.duration ?? options.duration ?? 200,
+        easing: step?.easing ?? options.easing,
+        delay: 0,
+    });
+}
+/** Resolve every step, then lay the slots out with the resolved durations. */
+function schedule(entries, options) {
+    const level = options.level ?? 'full';
+    const out = [];
+    let cursor = 0;
+    const slot = (step, base) => {
+        const plan = planOf(step, options);
+        const at = motionDuration(step?.at ?? 0, level);
+        out.push({ step, start: base + at, plan });
+        return at + (plan.instant ? 0 : plan.duration);
+    };
+    for (const entry of entries) {
+        if (!entry)
+            continue;
+        if ('parallel' in entry) {
+            let longest = 0;
+            for (const step of entry.parallel ?? []) {
+                if (out.length >= MAX_TIMELINE_STEPS)
+                    return null;
+                longest = Math.max(longest, slot(step, cursor));
+            }
+            cursor += longest;
+        }
+        else {
+            if (out.length >= MAX_TIMELINE_STEPS)
+                return null;
+            cursor += slot(entry, cursor);
+        }
+    }
+    return out;
+}
+function build(entries, options, autoplay) {
+    const instant = (reason) => {
+        const run = createRun([], options.onFinish, reason);
+        return {
+            duration: 0,
+            finished: run.finished,
+            instantReason: run.instantReason,
+            animations: [],
+            play() { },
+            pause() { },
+            seek() { },
+            reverse() { },
+            cancel() { },
+            finish() { },
+        };
+    };
+    const scheduled = schedule(Array.isArray(entries) ? entries : [], options);
+    if (!scheduled)
+        return instant('limit');
+    const live = scheduled.filter((p) => !p.plan.instant);
+    if (live.length === 0) {
+        const first = scheduled.find((p) => p.plan.instant)?.plan;
+        return instant(first?.instant ? first.reason : 'zero-duration');
+    }
+    const total = Math.max(...live.map((p) => p.start + (p.plan.instant ? 0 : p.plan.duration)));
+    const animations = [];
+    for (const { step, start, plan } of live) {
+        if (plan.instant || !step.target)
+            continue;
+        const animation = startAnimation(step.target, { ...plan, delay: start }, { endDelay: Math.max(0, total - start - plan.duration) });
+        if (!animation)
+            continue;
+        if (!autoplay)
+            animation.pause();
+        animations.push(animation);
+    }
+    if (animations.length === 0)
+        return instant('error');
+    const run = createRun(animations, options.onFinish);
+    const each = (fn) => () => {
+        for (const a of animations) {
+            try {
+                fn(a);
+            }
+            catch {
+                // A finished or cancelled animation ignores the command.
+            }
+        }
+    };
+    return {
+        duration: total,
+        finished: run.finished,
+        instantReason: null,
+        animations,
+        play: each((a) => a.play()),
+        pause: each((a) => a.pause()),
+        reverse: each((a) => a.reverse()),
+        seek(ms) {
+            const t = Number.isFinite(ms) ? Math.max(0, Math.min(total, ms)) : 0;
+            each((a) => {
+                a.currentTime = t;
+            })();
+        },
+        cancel: run.cancel,
+        finish: run.finish,
+    };
+}
+/** Build a timeline, paused until `play()` unless `autoplay` is true. */
+export function timeline(entries, options = {}) {
+    return build(entries, options, options.autoplay === true);
+}
+/** Play steps now (a timeline that autoplays unless `autoplay: false`). */
+export function sequence(entries, options = {}) {
+    return build(entries, options, options.autoplay !== false);
+}

package/dist/motion/shared.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared-element transitions (ADR-013): a keyed snapshot of one element's box
+ * before a state change, played onto the element that represents the same
+ * thing after it (a thumbnail and its lightbox, a card and its detail view).
+ *
+ * The fallback everywhere is FLIP: the new element moves and scales from the
+ * captured box; when the old element is still on the page the two cross-fade.
+ * {@link startScopedViewTransition} uses an element-scoped View Transition
+ * when the browser has one and otherwise just applies the update.
+ */
+import { type MotionOutcome, type MotionRun, type MotionTiming } from './animate.js';
+export type SharedElementsOptions = MotionTiming & {
+    /** Snapshots kept at most; the oldest is dropped past it. Default 256 (clamped to [1, 4096]). */
+    maxEntries?: number;
+    onFinish?: (outcome: MotionOutcome) => void;
+};
+export type SharedElements = {
+    /** Record where `element` is now under `key`. False when it cannot be measured (detached, SSR). */
+    capture: (key: string, element: Element) => boolean;
+    /** Animate `element` from the box captured under `key`, then forget the snapshot. */
+    play: (key: string, element: Element) => MotionRun;
+    has: (key: string) => boolean;
+    release: (key: string) => void;
+    clear: () => void;
+    /** How many snapshots are held. */
+    readonly size: number;
+};
+/**
+ * Create a registry of keyed snapshots.
+ *
+ * @example
+ * const shared = createSharedElements({ duration: 250 });
+ * shared.capture('photo-3', thumbnail);
+ * openLightbox();                      // the DOM changes
+ * shared.play('photo-3', lightboxImage);
+ */
+export declare function createSharedElements(options?: SharedElementsOptions): SharedElements;
+export type ScopedViewTransitionOptions = Pick<MotionTiming, 'level' | 'reducedMotion'>;
+/**
+ * Run `update` inside an element-scoped View Transition when the browser
+ * offers `element.startViewTransition`; otherwise (no support, the server,
+ * level `none`, reduced motion) apply it at once. Resolves `"finished"` after
+ * the transition, `"instant"` when the update was applied directly.
+ */
+export declare function startScopedViewTransition(scope: Element | null | undefined, update: () => void | Promise<void>, options?: ScopedViewTransitionOptions): Promise<MotionOutcome>;

package/dist/motion/shared.js

@@ -0,0 +1,144 @@
+/**
+ * Shared-element transitions (ADR-013): a keyed snapshot of one element's box
+ * before a state change, played onto the element that represents the same
+ * thing after it (a thumbnail and its lightbox, a card and its detail view).
+ *
+ * The fallback everywhere is FLIP: the new element moves and scales from the
+ * captured box; when the old element is still on the page the two cross-fade.
+ * {@link startScopedViewTransition} uses an element-scoped View Transition
+ * when the browser has one and otherwise just applies the update.
+ */
+import { createRun, resolveMotion, startAnimation, } from "./animate.js";
+import { flipTransform } from "./flip.js";
+import { resolveMotionLevel } from "./preferences.js";
+function measure(element) {
+    if (!element?.isConnected || typeof element.getBoundingClientRect !== 'function')
+        return null;
+    const r = element.getBoundingClientRect();
+    const box = { left: r.left, top: r.top, width: r.width, height: r.height };
+    return Object.values(box).every(Number.isFinite) ? box : null;
+}
+/**
+ * Create a registry of keyed snapshots.
+ *
+ * @example
+ * const shared = createSharedElements({ duration: 250 });
+ * shared.capture('photo-3', thumbnail);
+ * openLightbox();                      // the DOM changes
+ * shared.play('photo-3', lightboxImage);
+ */
+export function createSharedElements(options = {}) {
+    const limit = Math.max(1, Math.min(4096, Math.floor(Number.isFinite(options.maxEntries) ? options.maxEntries : 256)));
+    const snapshots = new Map();
+    return {
+        capture(key, element) {
+            const box = element ? measure(element) : null;
+            const id = String(key);
+            snapshots.delete(id);
+            if (!box)
+                return false;
+            snapshots.set(id, { element, box });
+            while (snapshots.size > limit) {
+                const oldest = snapshots.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                snapshots.delete(oldest);
+            }
+            return true;
+        },
+        play(key, element) {
+            const id = String(key);
+            const snapshot = snapshots.get(id);
+            snapshots.delete(id);
+            const last = element ? measure(element) : null;
+            if (!snapshot || !last) {
+                return createRun([], options.onFinish, last ? 'no-properties' : 'detached');
+            }
+            const transform = flipTransform(snapshot.box, last, true);
+            const crossFade = snapshot.element !== element && snapshot.element.isConnected;
+            const toFrames = [
+                {
+                    transform: transform ?? 'none',
+                    transformOrigin: '0 0',
+                    ...(crossFade ? { opacity: 0 } : {}),
+                },
+                { transform: 'none', transformOrigin: '0 0', ...(crossFade ? { opacity: 1 } : {}) },
+            ];
+            if (!transform && !crossFade)
+                return createRun([], options.onFinish, 'no-properties');
+            // Read phase done; write phase.
+            const plans = [
+                [element, resolveMotion(element, toFrames, options)],
+            ];
+            if (crossFade) {
+                // The old element travels from its box onto the new one while it fades out.
+                const travel = flipTransform(last, snapshot.box, true) ?? 'none';
+                plans.push([
+                    snapshot.element,
+                    resolveMotion(snapshot.element, [
+                        { transform: 'none', transformOrigin: '0 0', opacity: 1 },
+                        { transform: travel, transformOrigin: '0 0', opacity: 0 },
+                    ], options),
+                ]);
+            }
+            const animations = [];
+            let reason = null;
+            for (const [target, plan] of plans) {
+                if (plan.instant) {
+                    reason ??= plan.reason;
+                    continue;
+                }
+                const animation = startAnimation(target, plan);
+                if (animation)
+                    animations.push(animation);
+                else
+                    reason ??= 'error';
+            }
+            return createRun(animations, options.onFinish, reason);
+        },
+        has: (key) => snapshots.has(String(key)),
+        release: (key) => {
+            snapshots.delete(String(key));
+        },
+        clear: () => snapshots.clear(),
+        get size() {
+            return snapshots.size;
+        },
+    };
+}
+/**
+ * Run `update` inside an element-scoped View Transition when the browser
+ * offers `element.startViewTransition`; otherwise (no support, the server,
+ * level `none`, reduced motion) apply it at once. Resolves `"finished"` after
+ * the transition, `"instant"` when the update was applied directly.
+ */
+export async function startScopedViewTransition(scope, update, options = {}) {
+    const host = scope;
+    // Same gates as any animation (server, detached, level, reduced motion);
+    // a missing Web Animations API does not matter here.
+    const probe = resolveMotion(host ?? null, [{ opacity: 1 }], {
+        level: resolveMotionLevel({ host: options.level }),
+        reducedMotion: options.reducedMotion,
+        duration: 1,
+    });
+    const usable = !probe.instant || probe.reason === 'no-waapi';
+    if (!host || !usable || typeof host.startViewTransition !== 'function') {
+        await update();
+        return 'instant';
+    }
+    let transition;
+    try {
+        transition = host.startViewTransition.call(host, update);
+    }
+    catch {
+        await update();
+        return 'instant';
+    }
+    try {
+        await transition.finished;
+        return 'finished';
+    }
+    catch {
+        return 'cancelled';
+    }
+}