fancy-ui-react 0.2.0

package/dist/internals/menu.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Menu keyboard-navigation core: which item holds **real DOM focus** as arrow
+ * keys, Home/End and typeahead move through a `role="menu"` surface.
+ *
+ * This is the counterpart to `listbox.ts`, and the difference between the two
+ * is the whole reason both exist. A listbox keeps focus on its input or
+ * trigger and points at the active row with `aria-activedescendant`; a menu
+ * moves focus onto the item itself. That is the WAI-ARIA menu pattern, and it
+ * is what assistive technology expects when it meets `role="menu"` — so a menu
+ * built on `aria-activedescendant` reads as broken even though nothing about
+ * it looks wrong. Consumers must not add `aria-activedescendant` to a surface
+ * driven by this module.
+ *
+ * Three guarantees, so `DropdownMenu`, `ContextMenu` and every submenu get
+ * them once rather than three times:
+ *
+ * - **Items navigate in DOM order, not registration order.** Mount order and
+ *   document order diverge routinely — a conditional block, a list that
+ *   reorders, a submenu that mounts before the item above it. Ordering is
+ *   therefore resolved by `compareDocumentPosition` at navigation time, not
+ *   by the order `register` happened to be called in. This is also what makes
+ *   the promise survive React's child-before-parent effect ordering for free.
+ * - **Disabled items are skipped**, a consecutive run of them as a block, and
+ *   movement terminates rather than spinning when every item is disabled.
+ * - **Typeahead** accumulates characters within a short window and resets
+ *   after it, with a repeated character cycling through its matches — the
+ *   same semantics as the listbox core, so the two feel identical to use.
+ *
+ * The focused item is tracked as an *element*, not an index: menus mutate
+ * their item list while open (a filtered list, a submenu opening), and an
+ * index captured before that mutation silently points at a different item
+ * afterwards. `focusedIndex` is derived from the element on read.
+ */
+import type { RefCallback } from "react";
+export interface MenuFocusOptions {
+    /** Whether arrow navigation wraps at the ends. Defaults to true. */
+    loop?: boolean;
+    /** Called when focus moves to an item, with the item's index and element. */
+    onFocusChange?: (index: number, element: HTMLElement) => void;
+}
+export interface MenuFocusState {
+    /**
+     * Index of the focused item in DOM order, or -1 when focus is not on an item.
+     *
+     * Computed on read from the live ordered list, exactly like the Svelte
+     * getter — so the value is correct on a fresh read and `document.activeElement`
+     * is never wrong. It is deliberately NOT React state: nothing re-renders when
+     * focus moves, because real DOM focus does the rendering through `:focus` /
+     * `:focus-visible`. Use `onFocusChange`, or opt into `useMenuFocusedIndex`
+     * when a component genuinely must render off the number.
+     */
+    readonly focusedIndex: number;
+    /** Registers an item element. Returns an unregister function; call it on destroy. */
+    register(element: HTMLElement): () => void;
+    /** Moves focus by delta, skipping disabled items. `delta === 0` is a no-op. */
+    move(delta: number): void;
+    /** Moves focus to the first or last enabled item. */
+    moveToEdge(edge: "first" | "last"): void;
+    /** Focuses a specific element, if it is registered and enabled. */
+    focusItem(element: HTMLElement): void;
+    /** Clears the focused item without moving DOM focus. */
+    clear(): void;
+    /**
+     * Advances typeahead with a printable character and focuses the match.
+     *
+     * Matches against the item's `data-typeahead-label` when it has one, and
+     * otherwise against its visible text — decorative `aria-hidden` content
+     * (icon glyphs, `<kbd>` shortcuts) is excluded either way. Set the
+     * attribute whenever the item knows its own label as a string; it is
+     * cheaper and more reliable than making this reconstruct it from the DOM.
+     */
+    typeahead(char: string): void;
+    /** Clears the typeahead buffer and any pending timer. Call from teardown. */
+    destroy(): void;
+    /**
+     * Added for React. Notifies on every `focusedElement` change, so
+     * `useMenuFocusedIndex` can read the index through `useSyncExternalStore`.
+     * The mutation source is outside React's knowledge — a `focusItem` from a
+     * `pointerenter`, a `typeahead` from a document keydown — which is exactly
+     * the case that API exists for.
+     */
+    subscribe(listener: () => void): () => void;
+}
+export declare function createMenuFocus(options?: MenuFocusOptions): MenuFocusState;
+/**
+ * One store per mount, torn down on unmount.
+ *
+ * The options are handed to the factory as a getter object over live refs, so
+ * passing `loop` as a PLAIN VALUE behaves identically to the Svelte call sites'
+ * `get loop() { … }` — the factory reads it lazily at navigation time, and a
+ * re-render that changes it is honoured without rebuilding anything.
+ *
+ * The returned handle's identity NEVER changes, so it goes straight into a
+ * context value with no memo dance, and no item re-renders when focus moves.
+ * `destroy()` is still on the handle, but a consumer never has to call it: the
+ * unmount cleanup below closes the typeahead timer that the Svelte side's
+ * `DropdownMenuContent` forgets (divergence D-5).
+ */
+export declare function useMenuFocus(options?: MenuFocusOptions): MenuFocusState;
+/**
+ * A per-item callback ref — one line in each item component, replacing the
+ * Svelte side's per-item registration effect.
+ *
+ * Registration happens in the ref callback (commit phase) rather than an
+ * effect, so it survives React's detach-then-attach protocol: the previous
+ * registration is released before the new node registers. React 18 ref
+ * callbacks cannot return a cleanup — that is 19-only — so the unregister is
+ * held locally instead.
+ *
+ * Registration order is irrelevant: `orderedItems()` sorts by
+ * `compareDocumentPosition` at navigation time.
+ */
+export declare function useMenuItemRef(menu: MenuFocusState): RefCallback<HTMLElement>;
+/**
+ * Subscribes to the focused index so a component can render off it.
+ *
+ * Opt-in, and discouraged for the reason `focusedIndex`'s own doc comment
+ * gives: real DOM focus is what should drive rendering, through `:focus` /
+ * `:focus-visible`. Reach for this only when a component genuinely cannot.
+ */
+export declare function useMenuFocusedIndex(menu: MenuFocusState): number;

package/dist/internals/menu.js

@@ -0,0 +1,217 @@
+"use client";
+import { useEffect, useRef, useCallback } from "react";
+import { useConstant } from "./dom/ssr.js";
+import { useEventCallback } from "./dom/use-event-callback.js";
+import { useLiveRef } from "./dom/use-live-ref.js";
+const TYPEAHEAD_TIMEOUT_MS = 500;
+function compareDocumentOrder(a, b) {
+  if (a === b) return 0;
+  return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+}
+function visibleTextOf(node) {
+  if (node.nodeType === Node.TEXT_NODE) return node.textContent ?? "";
+  if (node.nodeType !== Node.ELEMENT_NODE) return "";
+  const element = node;
+  if (element.getAttribute("aria-hidden") === "true") return "";
+  let text = "";
+  for (const child of Array.from(element.childNodes)) text += visibleTextOf(child);
+  return text;
+}
+function isDisabled(element) {
+  if (element.getAttribute("aria-disabled") === "true") return true;
+  return "disabled" in element && element.disabled === true;
+}
+function createMenuFocus(options = {}) {
+  const registered = [];
+  let focusedElement = null;
+  let buffer = "";
+  let timer = null;
+  const listeners = /* @__PURE__ */ new Set();
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+  function orderedItems() {
+    return registered.filter((element) => element.isConnected).sort(compareDocumentOrder);
+  }
+  function focusAt(items, index) {
+    const element = items[index];
+    if (!element) return;
+    focusedElement = element;
+    notify();
+    element.focus();
+    options.onFocusChange?.(index, element);
+  }
+  function findNext(items, from, direction, loop) {
+    const count = items.length;
+    let idx = from;
+    for (let attempts = 0; attempts < count; attempts++) {
+      idx += direction;
+      if (loop) {
+        idx = (idx % count + count) % count;
+      } else if (idx < 0 || idx >= count) {
+        return null;
+      }
+      const element = items[idx];
+      if (element && !isDisabled(element)) return idx;
+    }
+    return null;
+  }
+  function indexOfFocused(items) {
+    return focusedElement ? items.indexOf(focusedElement) : -1;
+  }
+  function register(element) {
+    if (!registered.includes(element)) registered.push(element);
+    return () => {
+      const at = registered.indexOf(element);
+      if (at !== -1) registered.splice(at, 1);
+      if (focusedElement === element) {
+        focusedElement = null;
+        notify();
+      }
+    };
+  }
+  function move(delta) {
+    if (delta === 0) return;
+    const items = orderedItems();
+    if (items.length === 0) return;
+    const loop = options.loop ?? true;
+    const direction = delta >= 0 ? 1 : -1;
+    const steps = Math.abs(delta);
+    const current = indexOfFocused(items);
+    const from = current === -1 ? direction === 1 ? -1 : items.length : current;
+    let found = null;
+    for (let i = 0; i < steps; i++) {
+      const next = findNext(items, found ?? from, direction, loop);
+      if (next === null) break;
+      found = next;
+    }
+    if (found !== null) focusAt(items, found);
+  }
+  function moveToEdge(edge) {
+    const items = orderedItems();
+    if (items.length === 0) return;
+    if (edge === "first") {
+      for (let i = 0; i < items.length; i++) {
+        if (!isDisabled(items[i])) {
+          focusAt(items, i);
+          return;
+        }
+      }
+      return;
+    }
+    for (let i = items.length - 1; i >= 0; i--) {
+      if (!isDisabled(items[i])) {
+        focusAt(items, i);
+        return;
+      }
+    }
+  }
+  function focusItem(element) {
+    const items = orderedItems();
+    const index = items.indexOf(element);
+    if (index === -1 || isDisabled(element)) return;
+    focusAt(items, index);
+  }
+  function clear() {
+    focusedElement = null;
+    notify();
+  }
+  function clearBuffer() {
+    buffer = "";
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+  function labelOf(element) {
+    const explicit = element.dataset.typeaheadLabel;
+    return (explicit ?? visibleTextOf(element)).trim().toLowerCase();
+  }
+  function typeahead(char) {
+    const items = orderedItems();
+    if (items.length === 0) return;
+    const lower = char.toLowerCase();
+    const isRepeatChar = buffer.length > 0 && [...buffer].every((c) => c === lower);
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(clearBuffer, TYPEAHEAD_TIMEOUT_MS);
+    if (isRepeatChar) {
+      buffer = lower;
+      const from = indexOfFocused(items);
+      for (let i = 1; i <= items.length; i++) {
+        const candidate = (from + i + items.length) % items.length;
+        const element = items[candidate];
+        if (isDisabled(element)) continue;
+        if (labelOf(element).startsWith(lower)) {
+          focusAt(items, candidate);
+          return;
+        }
+      }
+      return;
+    }
+    buffer += lower;
+    const query = buffer;
+    for (let i = 0; i < items.length; i++) {
+      const element = items[i];
+      if (isDisabled(element)) continue;
+      if (labelOf(element).startsWith(query)) {
+        focusAt(items, i);
+        return;
+      }
+    }
+  }
+  function destroy() {
+    clearBuffer();
+  }
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+  return {
+    get focusedIndex() {
+      return indexOfFocused(orderedItems());
+    },
+    register,
+    move,
+    moveToEdge,
+    focusItem,
+    clear,
+    typeahead,
+    destroy,
+    subscribe
+  };
+}
+function useMenuFocus(options = {}) {
+  const loop = useLiveRef(options.loop);
+  const onFocusChange = useEventCallback(options.onFocusChange);
+  const menu = useConstant(
+    () => createMenuFocus({
+      get loop() {
+        return loop.current;
+      },
+      onFocusChange
+    })
+  );
+  useEffect(() => {
+    return () => {
+      menu.destroy();
+    };
+  }, [menu]);
+  return menu;
+}
+function useMenuItemRef(menu) {
+  const unregister = useRef(null);
+  return useCallback(
+    (node) => {
+      unregister.current?.();
+      unregister.current = node ? menu.register(node) : null;
+    },
+    [menu]
+  );
+}
+export {
+  createMenuFocus,
+  useMenuFocus,
+  useMenuItemRef
+};

package/dist/internals/motion/anchored.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The shared scale+opacity transition for floating surfaces — menus, selects,
+ * pickers, popovers, tooltips, hover cards. One rung, one curve, one
+ * geometry, so twelve panels stop each inventing their own.
+ *
+ * The name is a slight misnomer for the modal rung: a centred dialog is
+ * anchored to nothing, and spends this same function with its own two
+ * durations (`DURATIONS.base` in, `DURATIONS.exit` out) rather than the
+ * anchored defaults. One geometry in one place was worth more than a synonym,
+ * so the modal surfaces call `anchored` too and spell their rung at the call
+ * site where the diff can see it.
+ *
+ * Two pieces that are deliberately kept separate:
+ *
+ * 1. `anchored()` — a css-only transition (scale + opacity, nothing else). It
+ *    never emits `transform-origin`.
+ * 2. `originFor()` — a pure lookup the CALLER writes as a static inline
+ *    `style={{ transformOrigin }}`. Keeping the origin out of `css()` means it
+ *    is inspectable in DevTools, survives a future exit transition, and is
+ *    available to any CSS that wants to key off it — none of which is true
+ *    of a value smuggled into a per-frame transition string.
+ *
+ * Why scale + opacity and nothing else: a panel that also translated would
+ * fight `anchor-position.ts`'s `position: fixed; left/top` writes on the same
+ * element (that module owns those three properties and touches neither
+ * `transform` nor `transform-origin`, so the two never collide as written).
+ * The travel is not lost, it moves into the origin: growing from the panel
+ * edge nearest the trigger reads as "this came out of that button" far more
+ * clearly than four pixels of slide ever did.
+ *
+ * SSR: nothing here touches `window` at module scope. `prefersReducedMotion()`
+ * does, but a transition body only ever runs in the browser.
+ */
+import type { Side, Align } from "../anchor-position.js";
+import type { TransitionSpec, TransitionDirection } from "./transitions.js";
+/** Params for `anchored`. Every field is optional; the defaults ARE the
+ * anchored rung, so `anchored(node, { side: resolvedSide })` is the whole
+ * call site for eleven of the twelve panels. */
+export interface AnchoredParams {
+    /** The RESOLVED side the surface was placed on — `useAnchorPosition`'s
+     * `onPlacement` value, never the requested one. Drives nothing but the
+     * caller's own `transform-origin`; kept here so one params object feeds
+     * both. Defaults to `"bottom"`, but callers always pass their own
+     * requested side as the seed. */
+    side?: Side;
+    /** Entrance duration (ms). Defaults to `DURATIONS.fast`. */
+    duration?: number;
+    /** Exit duration (ms). Defaults to `DURATIONS.fast`. */
+    exitDuration?: number;
+    /** Delay (ms), entrance only — an exit never waits. Defaults to 0. */
+    delay?: number;
+    /** `false` drops the scale term, leaving an opacity-only fade (Tooltip).
+     * Defaults to `true`. */
+    scale?: boolean;
+    /** Direction override, read fresh on every call, for a caller driving ONE
+     * bidirectional transition instance (which reports `direction: "both"`,
+     * and cannot distinguish enter from leave). Unset, direction comes from
+     * `options.direction`. */
+    entering?: boolean;
+}
+/**
+ * One-shot read of the user's motion preference.
+ *
+ * Browser-only, and safe because of where it is called from: a transition body
+ * never runs during SSR. NEVER call it at module scope, in a render path, or
+ * inside a memo — for a live, reactive answer use `useReducedMotion()` from
+ * `media-query.ts` instead. A listener would be pointless here: the value only
+ * matters at the instant a one-shot transition starts, and a preference that
+ * flips mid-flight should not retro-cancel an animation already on screen.
+ *
+ * `window.matchMedia` is resolved FRESH on every call, never memoised, for
+ * the same reason `media-query.ts` documents at length: a test that overrides
+ * `window.matchMedia` wholesale must be visible to the next call.
+ */
+export declare function prefersReducedMotion(): boolean;
+export declare function originFor(side: Side, align?: Align): string;
+/**
+ * A css-only, direction-aware transition for an anchored floating surface.
+ * Entrance: `JS_EASINGS.out` over `DURATIONS.fast`, growing from the scale
+ * floor. Exit: `JS_EASINGS.in`, half the depth, and never delayed — a
+ * dismissal that waits before starting reads as an unresponsive UI.
+ *
+ * Reduced motion collapses `duration` (and `delay`) to 0, which makes
+ * `runTransition` skip `element.animate()` entirely rather than running a
+ * zero-length animation — the same fast path `animate.test.ts` pins down.
+ */
+export declare function anchored(_node: Element, params?: AnchoredParams, options?: {
+    direction: TransitionDirection;
+}): TransitionSpec;
+/** The `data-state` values a transitioning surface reports. There is no
+ *  "closed": a closed surface is not in the DOM. Deliberately two values, not
+ *  three — a 150–300 ms entrance has nothing that needs to key off "opening",
+ *  and two values means one static attribute plus two one-line handlers
+ *  instead of four.
+ *
+ *  The Svelte side pairs this type with a `markSurfaceState(event, state)`
+ *  helper that writes `data-state` IMPERATIVELY from a transition event
+ *  handler. That helper is NOT ported (divergence D-2): it exists solely
+ *  because Svelte marks a closing `{#if}` branch inert and its scheduler skips
+ *  inert effects, so a reactive attribute inside a closing block never reaches
+ *  the DOM. React re-renders an exiting surface normally, so a port writes
+ *  `data-state={presence.surfaceState}` as an ordinary attribute — same DOM,
+ *  same CSS hooks, same two values. */
+export type SurfaceState = "open" | "closing";

package/dist/internals/motion/anchored.js

@@ -0,0 +1,44 @@
+"use client";
+import { DURATIONS, JS_EASINGS } from "./tokens.js";
+import { PRESETS } from "./presets.js";
+import { REDUCED_MOTION_QUERY } from "./media-query.js";
+function prefersReducedMotion() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+  return window.matchMedia(REDUCED_MOTION_QUERY).matches;
+}
+const ORIGINS = {
+  bottom: { start: "left top", center: "center top", end: "right top" },
+  top: { start: "left bottom", center: "center bottom", end: "right bottom" },
+  left: { start: "right top", center: "right center", end: "right bottom" },
+  right: { start: "left top", center: "left center", end: "left bottom" }
+};
+function originFor(side, align = "center") {
+  return ORIGINS[side][align];
+}
+const ENTER_FLOOR = PRESETS.scale.scale;
+const EXIT_FLOOR = 1 - (1 - ENTER_FLOOR) / 2;
+function anchored(_node, params = {}, options) {
+  const entering = params.entering ?? options?.direction !== "out";
+  const reduced = prefersReducedMotion();
+  const duration = reduced ? 0 : entering ? params.duration ?? DURATIONS.fast : params.exitDuration ?? DURATIONS.fast;
+  const delay = reduced ? 0 : entering ? params.delay ?? 0 : 0;
+  const easing = entering ? JS_EASINGS.out : JS_EASINGS.in;
+  const floor = params.scale === false ? 1 : entering ? ENTER_FLOOR : EXIT_FLOOR;
+  return {
+    delay,
+    duration,
+    easing,
+    // `t` arrives ALREADY eased (the sampler evaluates `easing(i / n)`
+    // before calling `css`), so this interpolates linearly in `t` exactly
+    // like `transitions.ts` does. A floor of 1 emits no `transform` at all
+    // rather than a no-op `scale(1)`, which keeps an opacity-only panel
+    // from acquiring a compositing layer and a stacking context it never
+    // asked for.
+    css: (t) => floor === 1 ? `opacity: ${t}` : `opacity: ${t}; transform: scale(${floor + (1 - floor) * t})`
+  };
+}
+export {
+  anchored,
+  originFor,
+  prefersReducedMotion
+};

package/dist/internals/motion/animate.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The transition sampler — the one mechanism every `transition:`-driven
+ * component in this library runs through, reproduced from the framework's own
+ * `animate()` so the React port animates the SAME curve rather than a
+ * hand-matched approximation of it.
+ *
+ * The decisive fact behind the whole design: a css-only transition is already
+ * WAAPI. The framework samples `css(t, 1 - t)` at
+ * `n = Math.ceil(duration / (1000 / 60))` points, converts each string to a
+ * keyframe object and hands the array to `element.animate()`. Running that same
+ * algorithm against the same `css()` produces a byte-identical keyframe array
+ * and therefore a pixel-identical animation — fidelity is structural here, not
+ * aspirational. It also inherits, free: the `duration: 0` fast path reduced
+ * motion relies on, reversal from an in-flight position rather than a full
+ * restart, and testability through an `Element.prototype.animate` stub.
+ *
+ * The curve lives entirely in the SAMPLE POSITIONS (`t = t1 + delta *
+ * easing(i / n)`), never in a WAAPI `easing` option — which is exactly why
+ * every `css(t, u)` in `transitions.ts` and `anchored.ts` interpolates
+ * linearly in `t`: by the time `css` is called, `t` has already been eased.
+ *
+ * Two things the source has and this does not, both deliberate:
+ *
+ * - `tick`. `TransitionSpec` has no `tick` field (nothing in this library uses
+ *   one), so the per-frame JS loop and the `reset()` handle it exists for are
+ *   both gone with it.
+ * - The `overflow: hidden` inline-style workaround for a Safari < 18 bug. It
+ *   triggers only when a sampled keyframe declares `overflow: hidden`, and no
+ *   `css()` in this package emits `overflow` at all — porting it would ship a
+ *   branch no test can reach.
+ *
+ * There is deliberately NO "the host cannot animate" `setTimeout` fallback:
+ * the source has none, and inventing one would put an untested code path into
+ * production. jsdom is handled by the `Element.prototype.animate` stub in
+ * `test-setup.ts`, which is a hard requirement of this module's suite.
+ *
+ * SSR: nothing here touches a browser global at module scope. `runTransition`
+ * itself is only ever called from a layout effect.
+ */
+import type { TransitionSpec } from "./transitions.js";
+/**
+ * One `css(t, u)` declaration string → one WAAPI keyframe object.
+ *
+ * Split on `;`, split each part at the FIRST `:`, and **break** — not
+ * `continue` — on a malformed part: a declaration missing its value ends the
+ * parse rather than being skipped, which is the source's behaviour and is what
+ * keeps a trailing `;` harmless.
+ */
+export declare function cssToKeyframe(css: string): Keyframe;
+/** The handle one transition leg hands back. The counterpart of a running leg
+ * is read (`t()`) and then torn down (`abort()`) by the leg that replaces it. */
+export interface TransitionRun {
+    /** Current eased position in `css()`'s own `t` space: `1 - to` before the
+     * delay elapses, the interpolated position while the main animation runs,
+     * and `to` once it has finished. Read by a reversing counterpart so a
+     * reopen mid-close starts from where the close actually got to. */
+    t(): number;
+    /** Cancel without finishing. Also nulls the animation's `effect` (a
+     * Chromium leak) and replaces `onfinish` with a no-op, because a cancelled
+     * animation can still fire `onfinish` in rare cases. */
+    abort(): void;
+    /** Silence this run's `onFinish` without stopping it. Called on the
+     * counterpart the instant a new leg starts, so a superseded leg cannot
+     * unmount the node the new leg is animating back in. */
+    deactivate(): void;
+}
+/**
+ * Runs one transition leg on `element`, from its current position to `to`
+ * (`1` = visible, `0` = hidden), and calls `onFinish` when it lands.
+ *
+ * Order matters in five places, and every one of them is visible if broken:
+ *
+ * 1. `counterpart?.deactivate()` runs FIRST, before anything else.
+ * 2. A falsy `spec.duration` finishes SYNCHRONOUSLY and never calls
+ *    `element.animate()` — the reduced-motion fast path, and the reason a
+ *    reduced-motion close completes inside the same layout effect, before
+ *    paint.
+ * 3. A leading dummy animation is ALWAYS created, even at `delay: 0`. Its
+ *    keyframes pin the hidden state (`css(0, 1)`, twice) only for a fresh
+ *    intro, and are empty otherwise. Pinning is what stops a DELAYED entrance
+ *    painting one frame at rest first; keeping the dummy at `delay: 0` is what
+ *    defers the real keyframes until the DOM has updated. The consequence for
+ *    every caller: the main animation always starts ASYNCHRONOUSLY, in the
+ *    dummy's `onfinish`.
+ * 4. Inside that `onfinish`: cancel the dummy, then READ `counterpart.t()`,
+ *    then abort the counterpart — the read strictly before the abort, or a
+ *    reversal restarts from the far end instead of from the in-flight
+ *    position.
+ * 5. The sample loop runs `i = 0` to `i <= n` INCLUSIVE (n + 1 keyframes);
+ *    `n` must be an integer or the `to` value is missed entirely.
+ */
+export declare function runTransition(element: Element, spec: TransitionSpec, to: 0 | 1, counterpart: TransitionRun | undefined, onFinish: () => void): TransitionRun;

package/dist/internals/motion/animate.js

@@ -0,0 +1,84 @@
+"use client";
+import { linear } from "./easing.js";
+function noop() {
+}
+function cssPropertyToCamelcase(style) {
+  if (style === "float") return "cssFloat";
+  if (style === "offset") return "cssOffset";
+  if (style.startsWith("--")) return style;
+  const parts = style.split("-");
+  if (parts.length === 1) return parts[0] ?? style;
+  return (parts[0] ?? "") + parts.slice(1).map((word) => (word[0] ?? "").toUpperCase() + word.slice(1)).join("");
+}
+function cssToKeyframe(css) {
+  const keyframe = {};
+  const parts = css.split(";");
+  for (const part of parts) {
+    const [property, value] = part.split(":");
+    if (!property || value === void 0) break;
+    const formattedProperty = cssPropertyToCamelcase(property.trim());
+    keyframe[formattedProperty] = value.trim();
+  }
+  return keyframe;
+}
+function runTransition(element, spec, to, counterpart, onFinish) {
+  const isIntro = to === 1;
+  counterpart?.deactivate();
+  if (!spec.duration) {
+    onFinish();
+    return {
+      abort: noop,
+      deactivate: noop,
+      t: () => to
+    };
+  }
+  const { delay = 0, css, easing = linear } = spec;
+  const dummyKeyframes = [];
+  if (isIntro && counterpart === void 0) {
+    const styles = cssToKeyframe(css(0, 1));
+    dummyKeyframes.push(styles, styles);
+  }
+  let getT = () => 1 - to;
+  let finish = onFinish;
+  let animation = element.animate(dummyKeyframes, { duration: delay, fill: "forwards" });
+  animation.onfinish = () => {
+    animation.cancel();
+    const t1 = counterpart?.t() ?? 1 - to;
+    counterpart?.abort();
+    const delta = to - t1;
+    const duration = spec.duration * Math.abs(delta);
+    const keyframes = [];
+    if (duration > 0) {
+      const n = Math.ceil(duration / (1e3 / 60));
+      for (let i = 0; i <= n; i += 1) {
+        const t = t1 + delta * easing(i / n);
+        keyframes.push(cssToKeyframe(css(t, 1 - t)));
+      }
+      getT = () => {
+        const time = animation.currentTime;
+        if (typeof time !== "number" || !Number.isFinite(time)) return t1;
+        return t1 + delta * easing(time / duration);
+      };
+    }
+    animation = element.animate(keyframes, { duration, fill: "forwards" });
+    animation.onfinish = () => {
+      getT = () => to;
+      finish();
+    };
+  };
+  return {
+    abort: () => {
+      animation.cancel();
+      animation.effect = null;
+      animation.onfinish = noop;
+    },
+    deactivate: () => {
+      finish = noop;
+    },
+    t: () => getT()
+  };
+}
+export {
+  cssToKeyframe,
+  runTransition
+};

package/dist/internals/motion/easing.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The two curves `JS_EASINGS` names, inlined because the framework's easing
+ * module cannot become a runtime dependency of this package (divergence D-7 in
+ * the internals contract). Closed forms, copied byte-for-byte — do NOT "clean
+ * up" the endpoint guards; they are the shape of the curve at exactly the
+ * points `css()` is sampled at.
+ *
+ * Pure data-shaped functions: no side effects, no browser globals, safe to
+ * import at module scope during SSR.
+ */
+/** Departure curve. `t === 0` is guarded so the curve starts at exactly 0
+ * rather than at `2 ** -10`. */
+export declare function expoIn(t: number): number;
+/** Arrival curve. `t === 1` is guarded so the curve ends at exactly 1 rather
+ * than at `1 - 2 ** -10`. */
+export declare function expoOut(t: number): number;
+/** The identity curve. Not referenced by `JS_EASINGS`; exported for a caller
+ * that wants to opt a single transition out of easing entirely without
+ * hand-rolling `(t) => t` at the call site. */
+export declare const linear: (t: number) => number;