@texuli/core 0.5.0 → 0.7.0

package/dist/motion/flip.d.ts

@@ -0,0 +1,58 @@
+/**
+ * FLIP layout animation (ADR-013): measure (First), let the DOM change
+ * (Last), Invert with a transform, Play it back to identity.
+ *
+ * Reads and writes are batched: `measure` and `play` read every rectangle
+ * before they cancel or start any animation, so a list of any length lays out
+ * once per phase. A `measure` during a running play reads the in-flight
+ * (visual) positions, then interrupts the old run, so a re-reorder continues
+ * from where items are on screen.
+ *
+ * Deltas are measured in physical pixels, so reorders are correct in either
+ * direction; insert offsets are logical (`inline-start` follows `dir`).
+ * At level `subtle` moved items snap (no travel) and inserts only fade;
+ * at `none` or under reduced motion everything commits at once.
+ */
+import { type MotionKeyframes, type MotionOutcome, type MotionRun, type MotionTiming } from './animate.js';
+/** Items keyed by a stable id (a `Map` works). */
+export type FlipItems = Iterable<readonly [string, Element]>;
+/** Where an inserted item comes from: a fade, or a short slide from a logical side. */
+export type FlipEnter = false | 'fade' | 'inline-start' | 'inline-end' | 'block-start' | 'block-end' | MotionKeyframes;
+export type FlipOptions = MotionTiming & {
+    /** Animate size changes with a scale as well. Default `true`. */
+    scale?: boolean;
+    /** Inserted items (keys `measure` did not see). Default `"fade"`. */
+    enter?: FlipEnter;
+    /** Slide distance for a logical `enter`, in px (clamped to [0, 64]). Default 8. */
+    enterDistance?: number;
+    /** Above this many animated items the change commits at once. Default 500. */
+    maxItems?: number;
+    onFinish?: (outcome: MotionOutcome) => void;
+};
+export type FlipController = {
+    /** First: record where every item is now (interrupts a running play). */
+    measure: (items: FlipItems) => void;
+    /** Last, Invert, Play: animate each item from its measured box to its current one. */
+    play: (items: FlipItems) => MotionRun;
+    /** Cancel the running play. */
+    cancel: () => void;
+};
+type Box = {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+};
+/** The inverted transform from `first` to `last` (`null` when nothing moved). */
+export declare function flipTransform(first: Box, last: Box, scale?: boolean): string | null;
+/**
+ * Create a FLIP controller for one list (or any set of keyed elements).
+ *
+ * @example
+ * const flip = createFlip({ duration: 200 });
+ * flip.measure(itemsByKey);
+ * reorder(); // the DOM changes
+ * await flip.play(itemsByKey).finished;
+ */
+export declare function createFlip(options?: FlipOptions): FlipController;
+export {};

package/dist/motion/flip.js

@@ -0,0 +1,167 @@
+/**
+ * FLIP layout animation (ADR-013): measure (First), let the DOM change
+ * (Last), Invert with a transform, Play it back to identity.
+ *
+ * Reads and writes are batched: `measure` and `play` read every rectangle
+ * before they cancel or start any animation, so a list of any length lays out
+ * once per phase. A `measure` during a running play reads the in-flight
+ * (visual) positions, then interrupts the old run, so a re-reorder continues
+ * from where items are on screen.
+ *
+ * Deltas are measured in physical pixels, so reorders are correct in either
+ * direction; insert offsets are logical (`inline-start` follows `dir`).
+ * At level `subtle` moved items snap (no travel) and inserts only fade;
+ * at `none` or under reduced motion everything commits at once.
+ */
+import { getOwnerWindow } from "../env/index.js";
+import { createRun, resolveMotion, startAnimation, } from "./animate.js";
+const MAX_DELTA = 100_000;
+function boxOf(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 Number.isFinite(box.left) &&
+        Number.isFinite(box.top) &&
+        Number.isFinite(box.width) &&
+        Number.isFinite(box.height)
+        ? box
+        : null;
+}
+function num(value) {
+    const clamped = Math.max(-MAX_DELTA, Math.min(MAX_DELTA, value));
+    const r = Math.round(clamped * 1000) / 1000;
+    return String(Object.is(r, -0) ? 0 : r);
+}
+/** The inverted transform from `first` to `last` (`null` when nothing moved). */
+export function flipTransform(first, last, scale = true) {
+    const dx = first.left - last.left;
+    const dy = first.top - last.top;
+    const sx = scale && last.width > 0 && first.width > 0 ? first.width / last.width : 1;
+    const sy = scale && last.height > 0 && first.height > 0 ? first.height / last.height : 1;
+    if (Math.abs(dx) < 0.5 &&
+        Math.abs(dy) < 0.5 &&
+        Math.abs(sx - 1) < 0.001 &&
+        Math.abs(sy - 1) < 0.001) {
+        return null;
+    }
+    const move = `translate(${num(dx)}px, ${num(dy)}px)`;
+    return sx === 1 && sy === 1 ? move : `${move} scale(${num(sx)}, ${num(sy)})`;
+}
+function isRtl(element) {
+    const win = getOwnerWindow(element);
+    try {
+        return win?.getComputedStyle(element).direction === 'rtl';
+    }
+    catch {
+        return false;
+    }
+}
+function enterFrames(enter, distance, rtl) {
+    if (enter === false)
+        return null;
+    if (typeof enter === 'object')
+        return enter;
+    if (enter === 'fade')
+        return [{ opacity: 0 }, { opacity: 1 }];
+    const sign = enter === 'inline-start' || enter === 'block-start' ? -1 : 1;
+    const inline = enter.startsWith('inline');
+    const px = num(sign * distance * (inline && rtl ? -1 : 1));
+    const from = inline ? `translate(${px}px, 0px)` : `translate(0px, ${px}px)`;
+    return [
+        { opacity: 0, transform: from },
+        { opacity: 1, transform: 'none' },
+    ];
+}
+/**
+ * Create a FLIP controller for one list (or any set of keyed elements).
+ *
+ * @example
+ * const flip = createFlip({ duration: 200 });
+ * flip.measure(itemsByKey);
+ * reorder(); // the DOM changes
+ * await flip.play(itemsByKey).finished;
+ */
+export function createFlip(options = {}) {
+    const scale = options.scale !== false;
+    const enter = options.enter ?? 'fade';
+    const distance = Math.max(0, Math.min(64, Number.isFinite(options.enterDistance) ? options.enterDistance : 8));
+    const maxItems = Math.max(0, Math.floor(Number.isFinite(options.maxItems) ? options.maxItems : 500));
+    let first = new Map();
+    let running = null;
+    function interrupt() {
+        running?.interrupt();
+        running = null;
+    }
+    return {
+        measure(items) {
+            // Read phase: every box (in-flight transforms included) before any write.
+            const next = new Map();
+            for (const [key, element] of items) {
+                const box = element ? boxOf(element) : null;
+                if (box)
+                    next.set(String(key), box);
+            }
+            first = next;
+            // Write phase: stop the old run so `play` reads the new layout untransformed.
+            interrupt();
+        },
+        play(items) {
+            interrupt();
+            const before = first;
+            first = new Map();
+            const jobs = [];
+            let rtl = null;
+            for (const [rawKey, element] of items) {
+                if (!element)
+                    continue;
+                const key = String(rawKey);
+                const last = boxOf(element);
+                if (!last)
+                    continue;
+                const from = before.get(key);
+                let frames;
+                if (from) {
+                    const transform = flipTransform(from, last, scale);
+                    frames = transform
+                        ? [
+                            { transform, transformOrigin: '0 0' },
+                            { transform: 'none', transformOrigin: '0 0' },
+                        ]
+                        : null;
+                }
+                else {
+                    if (rtl === null && typeof enter === 'string' && enter.startsWith('inline'))
+                        rtl = isRtl(element);
+                    frames = enterFrames(enter, distance, rtl === true);
+                }
+                if (frames)
+                    jobs.push({ element, frames, plan: resolveMotion(element, frames, options) });
+            }
+            if (jobs.length > maxItems) {
+                return createRun([], options.onFinish, 'limit');
+            }
+            // Write phase.
+            const animations = [];
+            let reason = null;
+            for (const job of jobs) {
+                if (job.plan.instant) {
+                    reason ??= job.plan.reason;
+                    continue;
+                }
+                const animation = startAnimation(job.element, job.plan);
+                if (animation)
+                    animations.push(animation);
+                else
+                    reason ??= 'error';
+            }
+            const run = createRun(animations, options.onFinish, reason ?? 'zero-duration');
+            running = animations.length > 0 ? run : null;
+            return run;
+        },
+        cancel() {
+            running?.cancel();
+            running = null;
+        },
+    };
+}

package/dist/motion/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @texuli/core/motion: the motion runtime (ADR-013). Web Animations with an
+ * owned spring solver, reduced motion instant by construction, and the
+ * `full` / `subtle` / `none` motion levels shared with the deck.
+ *
+ * Not re-exported from the `@texuli/core` root barrel: a component that does
+ * not animate pays nothing for it.
+ */
+export { type AnimateOptions, animate, createRun, DEFAULT_MOTION_DURATION, DEFAULT_MOTION_EASING, type InstantReason, type MotionKeyframes, type MotionOutcome, type MotionRun, type MotionTiming, type ReducedMotionInput, type ResolvedMotion, resolveMotion, startAnimation, withoutTravel, } from './animate.js';
+export { createFlip, type FlipController, type FlipEnter, type FlipItems, type FlipOptions, flipTransform, } from './flip.js';
+export { createReducedMotionSource, isMotionLevel, lowerMotionLevel, MAX_MOTION_MS, MOTION_LEVELS, type MotionLevel, type MotionLevelInput, motionDuration, REDUCED_FADE_MS, type ReducedMotionPolicy, type ReducedMotionSource, type ReducedMotionSourceOptions, resolveMotionLevel, SUBTLE_DURATION_SCALE, } from './preferences.js';
+export { createMotionPresence, type MotionPresence, type MotionPresenceOptions, } from './presence.js';
+export { MAX_STAGGER_SPAN, MAX_TIMELINE_STEPS, type ParallelGroup, parallel, type StaggerOptions, sequence, stagger, type Timeline, type TimelineEntry, type TimelineOptions, type TimelineStep, timeline, } from './sequence.js';
+export { createSharedElements, type ScopedViewTransitionOptions, type SharedElements, type SharedElementsOptions, startScopedViewTransition, } from './shared.js';
+export * from './spring.js';

package/dist/motion/index.js

@@ -0,0 +1,15 @@
+/**
+ * @texuli/core/motion: the motion runtime (ADR-013). Web Animations with an
+ * owned spring solver, reduced motion instant by construction, and the
+ * `full` / `subtle` / `none` motion levels shared with the deck.
+ *
+ * Not re-exported from the `@texuli/core` root barrel: a component that does
+ * not animate pays nothing for it.
+ */
+export { animate, createRun, DEFAULT_MOTION_DURATION, DEFAULT_MOTION_EASING, resolveMotion, startAnimation, withoutTravel, } from "./animate.js";
+export { createFlip, flipTransform, } from "./flip.js";
+export { createReducedMotionSource, isMotionLevel, lowerMotionLevel, MAX_MOTION_MS, MOTION_LEVELS, motionDuration, REDUCED_FADE_MS, resolveMotionLevel, SUBTLE_DURATION_SCALE, } from "./preferences.js";
+export { createMotionPresence, } from "./presence.js";
+export { MAX_STAGGER_SPAN, MAX_TIMELINE_STEPS, parallel, sequence, stagger, timeline, } from "./sequence.js";
+export { createSharedElements, startScopedViewTransition, } from "./shared.js";
+export * from "./spring.js";

package/dist/motion/preferences.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Motion preferences: the reduced-motion source and the motion-level
+ * resolver (ADR-013). Framework-free; no module-scope browser access.
+ */
+/** Motion levels shared with `@texuli/deck`: `subtle` shortens and drops travel, `none` is instant. */
+export declare const MOTION_LEVELS: readonly ["full", "subtle", "none"];
+export type MotionLevel = (typeof MOTION_LEVELS)[number];
+/** `subtle` multiplies every duration and offset by this factor (the deck's value). */
+export declare const SUBTLE_DURATION_SCALE = 0.6;
+/** Longest duration or delay any motion texel plays, in milliseconds. */
+export declare const MAX_MOTION_MS = 1000;
+/** Duration of the opt-in `fade` reduced-motion policy (the deck stage's slide fade). */
+export declare const REDUCED_FADE_MS = 150;
+/** What reduced motion does: commit the end state at once (default), or keep an opacity-only fade. */
+export type ReducedMotionPolicy = 'instant' | 'fade';
+/** A live view of `prefers-reduced-motion` with a host override. */
+export type ReducedMotionSource = {
+    /** Current value: the override when set, else the media query, else the SSR default. */
+    get: () => boolean;
+    /** Called with the new value whenever it changes; returns an unsubscribe function. */
+    subscribe: (listener: (reduced: boolean) => void) => () => void;
+    /** Force reduced motion on or off; `null` returns to the media query. */
+    setOverride: (value: boolean | null) => void;
+    /** Stop listening to the media query and drop every listener. */
+    dispose: () => void;
+};
+export type ReducedMotionSourceOptions = {
+    /** Window to read `matchMedia` from. Omit on the server. */
+    window?: Pick<Window, 'matchMedia'> | null;
+    /** Initial host override (`null` or omitted reads the media query). */
+    override?: boolean | null;
+    /** Value without a window. Default `false` (texels do not run on the server anyway). */
+    ssrDefault?: boolean;
+};
+/**
+ * Create a reduced-motion source. It reads `(prefers-reduced-motion: reduce)`
+ * from the given window, follows its `change` events, and lets the host
+ * override it (a settings toggle, a test, a print view).
+ */
+export declare function createReducedMotionSource(options?: ReducedMotionSourceOptions): ReducedMotionSource;
+/** Whether a value is one of {@link MOTION_LEVELS}. */
+export declare function isMotionLevel(value: unknown): value is MotionLevel;
+/** The lower of two levels (`none` < `subtle` < `full`); invalid values are ignored. */
+export declare function lowerMotionLevel(a: unknown, b: unknown): MotionLevel;
+export type MotionLevelInput = {
+    /** The host's level (an app setting); wins over everything below it. */
+    host?: unknown;
+    /** The blueprint's or deck's level. */
+    document?: unknown;
+    /** The component default. */
+    component?: unknown;
+    /** The viewer's preference: can only lower the result. */
+    viewer?: unknown;
+    /** Reduced motion lowers the result to `none` (the texels commit the end state at once). */
+    reducedMotion?: boolean;
+};
+/**
+ * Resolve the motion level: host, then blueprint or deck, then the component
+ * default, then `full`; the viewer's preference and reduced motion only lower
+ * it. Invalid values are skipped.
+ */
+export declare function resolveMotionLevel(input?: MotionLevelInput): MotionLevel;
+/**
+ * Clamp a duration or delay to [0, {@link MAX_MOTION_MS}] and scale it for the
+ * level: `subtle` × {@link SUBTLE_DURATION_SCALE}, `none` → 0. NaN and
+ * negative values are 0; Infinity is the maximum.
+ */
+export declare function motionDuration(ms: unknown, level?: MotionLevel): number;

package/dist/motion/preferences.js

@@ -0,0 +1,111 @@
+/**
+ * Motion preferences: the reduced-motion source and the motion-level
+ * resolver (ADR-013). Framework-free; no module-scope browser access.
+ */
+import { REDUCED_MOTION_QUERY } from "../presence/presence.js";
+/** Motion levels shared with `@texuli/deck`: `subtle` shortens and drops travel, `none` is instant. */
+export const MOTION_LEVELS = ['full', 'subtle', 'none'];
+/** `subtle` multiplies every duration and offset by this factor (the deck's value). */
+export const SUBTLE_DURATION_SCALE = 0.6;
+/** Longest duration or delay any motion texel plays, in milliseconds. */
+export const MAX_MOTION_MS = 1000;
+/** Duration of the opt-in `fade` reduced-motion policy (the deck stage's slide fade). */
+export const REDUCED_FADE_MS = 150;
+/**
+ * Create a reduced-motion source. It reads `(prefers-reduced-motion: reduce)`
+ * from the given window, follows its `change` events, and lets the host
+ * override it (a settings toggle, a test, a print view).
+ */
+export function createReducedMotionSource(options = {}) {
+    const ssrDefault = options.ssrDefault === true;
+    let override = typeof options.override === 'boolean' ? options.override : null;
+    const listeners = new Set();
+    let query = null;
+    const win = options.window;
+    if (win && typeof win.matchMedia === 'function') {
+        try {
+            query = win.matchMedia(REDUCED_MOTION_QUERY);
+        }
+        catch {
+            query = null;
+        }
+    }
+    let last = read();
+    function read() {
+        if (override !== null)
+            return override;
+        if (query)
+            return query.matches === true;
+        return ssrDefault;
+    }
+    function notify() {
+        const next = read();
+        if (next === last)
+            return;
+        last = next;
+        for (const listener of [...listeners])
+            listener(next);
+    }
+    const onChange = () => notify();
+    if (query?.addEventListener)
+        query.addEventListener('change', onChange);
+    else
+        query?.addListener?.(onChange);
+    return {
+        get: read,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        setOverride(value) {
+            override = typeof value === 'boolean' ? value : null;
+            notify();
+        },
+        dispose() {
+            if (query?.removeEventListener)
+                query.removeEventListener('change', onChange);
+            else
+                query?.removeListener?.(onChange);
+            query = null;
+            listeners.clear();
+        },
+    };
+}
+/** Whether a value is one of {@link MOTION_LEVELS}. */
+export function isMotionLevel(value) {
+    return typeof value === 'string' && MOTION_LEVELS.includes(value);
+}
+const RANK = { full: 2, subtle: 1, none: 0 };
+/** The lower of two levels (`none` < `subtle` < `full`); invalid values are ignored. */
+export function lowerMotionLevel(a, b) {
+    const left = isMotionLevel(a) ? a : 'full';
+    const right = isMotionLevel(b) ? b : 'full';
+    return RANK[left] <= RANK[right] ? left : right;
+}
+/**
+ * Resolve the motion level: host, then blueprint or deck, then the component
+ * default, then `full`; the viewer's preference and reduced motion only lower
+ * it. Invalid values are skipped.
+ */
+export function resolveMotionLevel(input = {}) {
+    const chosen = isMotionLevel(input.host)
+        ? input.host
+        : isMotionLevel(input.document)
+            ? input.document
+            : isMotionLevel(input.component)
+                ? input.component
+                : 'full';
+    const level = lowerMotionLevel(chosen, input.viewer);
+    return input.reducedMotion === true ? 'none' : level;
+}
+/**
+ * Clamp a duration or delay to [0, {@link MAX_MOTION_MS}] and scale it for the
+ * level: `subtle` × {@link SUBTLE_DURATION_SCALE}, `none` → 0. NaN and
+ * negative values are 0; Infinity is the maximum.
+ */
+export function motionDuration(ms, level = 'full') {
+    if (typeof ms !== 'number' || Number.isNaN(ms) || ms <= 0 || level === 'none')
+        return 0;
+    const clamped = Math.min(MAX_MOTION_MS, ms);
+    return Math.round(level === 'subtle' ? clamped * SUBTLE_DURATION_SCALE : clamped);
+}

package/dist/motion/presence.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { type PresenceSnapshot } from '../presence/presence.js';
+import { type MotionKeyframes, type MotionOutcome, type MotionTiming } from './animate.js';
+export type MotionPresenceOptions = MotionTiming & {
+    /** Initial intent. Default `false`. */
+    present?: boolean;
+    /** Play the enter animation for a node that is present on first attach. Default `false`. */
+    appear?: boolean;
+    /** Keep the node mounted after exit (`data-state` still closes). Default `false`. */
+    forceMount?: boolean;
+    /** Enter keyframes (hidden → shown). Default a fade in. */
+    enter?: MotionKeyframes;
+    /** Exit keyframes (shown → hidden). Default the reverse of `enter`. */
+    exit?: MotionKeyframes;
+    /** Timing overrides for the exit (merged over the shared timing). */
+    exitTiming?: MotionTiming;
+    /** Snapshot changed. */
+    onSnapshot?: (snapshot: PresenceSnapshot) => void;
+    /** The enter path began (the node should be mounted). */
+    onEnter?: (snapshot: PresenceSnapshot) => void;
+    /** The enter animation ended (or committed instantly). */
+    onEnterComplete?: (snapshot: PresenceSnapshot) => void;
+    /** The exit ended; unmount when `snapshot.mounted` is false. */
+    onExitComplete?: (snapshot: PresenceSnapshot) => void;
+};
+export type MotionPresence = {
+    getSnapshot: () => PresenceSnapshot;
+    /** Drive the intent; resolves when this transition settles. */
+    setPresent: (present: boolean) => Promise<MotionOutcome>;
+    /** Attach (or detach with `null`) the animated element after it mounts. */
+    setNode: (node: Element | null) => void;
+    /** The current transition's outcome (resolved `"instant"` when idle). */
+    readonly finished: Promise<MotionOutcome>;
+    /** Cancel any animation and stop; pending transitions resolve `"cancelled"`. */
+    dispose: () => void;
+};
+/**
+ * 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 declare function createMotionPresence(options?: MotionPresenceOptions): MotionPresence;