@celestia-island/hikari 0.40.18 → 0.40.21

package/src/composables/useSurfaceMachine.test.ts

@@ -0,0 +1,259 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import { useSurfaceMachine } from "./useSurfaceMachine";
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  document.body.innerHTML = "";
+});
+
+interface Rig {
+  phase: () => string;
+  mounted: () => boolean;
+  classesFor: (prefix: string) => string[];
+  send: (e: "OPEN" | "CLOSE" | "FLIP" | "DEADLINE" | "TEND" | "UNMOUNT") => void;
+  edges: Array<[string, string, string]>;
+  unmount: () => void;
+}
+
+/** Mount a machine with two test layers (like a modal's scrim+panel)
+ *  and capture every phase edge it walks. `probed` wires live element
+ *  accessors — in happy-dom the probe reads a 0 duration, which selects
+ *  the no-transition fast path; without probes the machine runs on the
+ *  configured fallback budgets (the starvation-era behavior). */
+function mountRig(probed = false): Rig {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const edges: Array<[string, string, string]> = [];
+  const machineRef: { current: ReturnType<typeof useSurfaceMachine> | null } = { current: null };
+  const app = createApp(defineComponent({
+    setup() {
+      machineRef.current = useSurfaceMachine({
+        layers: [
+          {
+            prefix: "rig-scrim",
+            ...(probed ? { el: () => document.querySelector<HTMLElement>(".scrim") } : {}),
+            enterMs: () => 300,
+            leaveMs: () => 300,
+          },
+          {
+            prefix: "rig-panel",
+            ...(probed ? { el: () => document.querySelector<HTMLElement>(".panel") } : {}),
+            enterMs: () => 300,
+            leaveMs: () => 250,
+          },
+        ],
+        onPhase: (from, to, event) => { edges.push([from, to, event]); },
+      });
+      const m = machineRef.current;
+      return () =>
+        h("div", [
+          m.mounted.value ? h("div", { class: ["scrim", ...m.classesFor("rig-scrim")] }) : null,
+          m.mounted.value ? h("div", { class: ["panel", ...m.classesFor("rig-panel")] }) : null,
+        ]);
+    },
+  }));
+  app.mount(container);
+  const m = machineRef.current!;
+  return {
+    phase: () => m.phase.value,
+    mounted: () => m.mounted.value,
+    classesFor: m.classesFor,
+    send: m.send,
+    edges,
+    unmount: () => app.unmount(),
+  };
+}
+
+function scrimClasses(rig: Rig): string[] {
+  return Array.from(document.querySelector<HTMLElement>(".scrim")?.classList ?? [])
+    .filter((c) => c.startsWith("rig-scrim-"));
+}
+
+async function flush(): Promise<void> {
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await nextTick();
+}
+
+describe("useSurfaceMachine driver", () => {
+  it("renders mounted with enter-from classes on OPEN, flips on rAF, rests on deadline", async () => {
+    vi.useFakeTimers();
+    const rig = mountRig();
+    rig.send("OPEN");
+    await nextTick();
+    expect(rig.mounted()).toBe(true);
+    expect(rig.phase()).toBe("openingFrom");
+    expect(scrimClasses(rig)).toEqual(["rig-scrim-enter-from", "rig-scrim-enter-active"]);
+
+    // Frame flip: the clock drives the (faked) rAF frames — well before
+    // the flip timer's own budget, so this exercises the frame path.
+    await vi.advanceTimersByTimeAsync(40);
+    expect(rig.phase()).toBe("openingTo");
+    expect(scrimClasses(rig)).toEqual(["rig-scrim-enter-to", "rig-scrim-enter-active"]);
+
+    // Deadline settles the surface at rest with no transition classes.
+    await vi.advanceTimersByTimeAsync(600);
+    expect(rig.phase()).toBe("open");
+    expect(scrimClasses(rig)).toEqual([]);
+    // No late events: nothing fires into the resting surface.
+    const edgesAtRest = rig.edges.length;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(rig.phase()).toBe("open");
+    expect(scrimClasses(rig)).toEqual([]);
+    expect(rig.edges.length).toBe(edgesAtRest);
+  });
+
+  it("settles open under total rAF starvation (flip timer + deadline only)", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("requestAnimationFrame", () => 0 as unknown as number);
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    const rig = mountRig();
+    rig.send("OPEN");
+    await nextTick();
+    expect(rig.phase()).toBe("openingFrom");
+    // No frames ever arrive; the flip timer forces FLIP…
+    await vi.advanceTimersByTimeAsync(120);
+    expect(rig.phase()).toBe("openingTo");
+    // …and the deadline walks to rest. Bounded, no watchdogs.
+    await vi.advanceTimersByTimeAsync(600);
+    expect(rig.phase()).toBe("open");
+    expect(scrimClasses(rig)).toEqual([]);
+  });
+
+  it("close → deadline finalizes to closed and unmounts the DOM", async () => {
+    vi.useFakeTimers();
+    const rig = mountRig();
+    rig.send("OPEN");
+    await vi.advanceTimersByTimeAsync(800);
+    expect(rig.phase()).toBe("open");
+
+    rig.send("CLOSE");
+    await nextTick();
+    expect(rig.phase()).toBe("closingFrom");
+    rig.send("FLIP");
+    await nextTick();
+    expect(rig.phase()).toBe("closingTo");
+    expect(scrimClasses(rig)).toEqual(["rig-scrim-leave-to", "rig-scrim-leave-active"]);
+
+    await vi.advanceTimersByTimeAsync(600);
+    expect(rig.phase()).toBe("closed");
+    expect(rig.mounted()).toBe(false);
+    expect(document.querySelector(".panel")).toBeNull();
+    // No late events resurrect anything.
+    const edgesAtRest = rig.edges.length;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(rig.phase()).toBe("closed");
+    expect(rig.edges.length).toBe(edgesAtRest);
+  });
+
+  it("a reopen during the closing window reverses on the same element", async () => {
+    vi.useFakeTimers();
+    const rig = mountRig();
+    rig.send("OPEN");
+    await vi.advanceTimersByTimeAsync(800);
+    rig.send("CLOSE");
+    await vi.advanceTimersByTimeAsync(50); // mid-flight (still *.from window)
+    expect(["closingFrom", "closingTo"]).toContain(rig.phase());
+
+    rig.send("OPEN");
+    await nextTick();
+    expect(rig.phase()).toBe("openingFrom");
+    // Element identity preserved across the reversal.
+    const panel = document.querySelector(".panel")!;
+    expect(panel).not.toBeNull();
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(rig.phase()).toBe("open");
+    expect(document.querySelector(".panel")).toBe(panel);
+    // The close never finalized — exactly one open edge, no ghost edges.
+    const closes = rig.edges.filter(([, to]) => to === "closed");
+    expect(closes).toHaveLength(0);
+  });
+
+  it("honors a measured CSS duration: settles only after duration+slack", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("requestAnimationFrame", () => 0 as unknown as number);
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    // Real-browser shape: computed transition-duration of 0.3s. The
+    // probe tightens the deadline to flip(120)+300+slack(80)=500 for the
+    // from-phase and 300+slack for the to-phase — never the configured
+    // fallback, never the zero-duration fast path.
+    const realGCS = window.getComputedStyle.bind(window);
+    vi.stubGlobal("getComputedStyle", (el: Element, ...rest: unknown[]) => {
+      const style = realGCS(el as Element, ...(rest as []));
+      return { ...style, transitionDuration: "0.3s" } as CSSStyleDeclaration;
+    });
+    const rig = mountRig(true);
+    rig.send("OPEN");
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(130); // flip timer forced the FLIP
+    expect(rig.phase()).toBe("openingTo");
+    // Inside duration+slack (380ms from the flip) nothing settles…
+    await vi.advanceTimersByTimeAsync(300);
+    expect(rig.phase()).toBe("openingTo");
+    // …past it, the deadline completes the open.
+    await vi.advanceTimersByTimeAsync(120);
+    expect(rig.phase()).toBe("open");
+    expect(scrimClasses(rig)).toEqual([]);
+  });
+
+  it("TEND: a matching transitionend completes the phase early", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("requestAnimationFrame", () => 0 as unknown as number);
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    const realGCS = window.getComputedStyle.bind(window);
+    vi.stubGlobal("getComputedStyle", (el: Element, ...rest: unknown[]) => {
+      const style = realGCS(el as Element, ...(rest as []));
+      return { ...style, transitionDuration: "0.3s" } as CSSStyleDeclaration;
+    });
+    const rig = mountRig(true);
+    rig.send("OPEN");
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(130); // flip forced → openingTo
+    expect(rig.phase()).toBe("openingTo");
+    const panel = document.querySelector<HTMLElement>(".panel")!;
+
+    // happy-dom's TransitionEvent ignores its init dict — synthesize
+    // the event and stamp elapsedTime on the instance.
+    const endEvent = (elapsedSeconds: number): Event => {
+      const ev = new Event("transitionend");
+      Object.defineProperty(ev, "elapsedTime", { value: elapsedSeconds });
+      return ev;
+    };
+
+    // A fast property's end event (elapsed < measured budget) is ignored…
+    panel.dispatchEvent(endEvent(0.1));
+    expect(rig.phase()).toBe("openingTo");
+
+    // …the slowest property's end event lands → the surface settles open
+    // immediately, ahead of the deadline timer.
+    panel.dispatchEvent(endEvent(0.3));
+    expect(rig.phase()).toBe("open");
+    await nextTick();
+    expect(scrimClasses(rig)).toEqual([]);
+    // No late deadline fires afterwards.
+    const edgesAtRest = rig.edges.length;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(rig.phase()).toBe("open");
+    expect(rig.edges.length).toBe(edgesAtRest);
+  });
+
+  it("UNMOUNT from any phase clears every clock and walks to closed", async () => {
+    vi.useFakeTimers();
+    const rig = mountRig();
+    rig.send("OPEN");
+    await vi.advanceTimersByTimeAsync(50); // mid opening
+    expect(rig.phase()).not.toBe("closed");
+    rig.unmount();
+    expect(vi.getTimerCount()).toBe(0);
+    // Nothing fires after teardown (no late timers).
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(rig.edges.at(-1)).toEqual([
+      expect.any(String),
+      "closed",
+      "UNMOUNT",
+    ]);
+  });
+});

package/src/composables/useSurfaceMachine.ts

@@ -0,0 +1,289 @@
+import { computed, nextTick, onBeforeUnmount, shallowRef, type ComputedRef } from "vue";
+
+import {
+  classPairOf,
+  classesForPair,
+  isMounted,
+  surfaceTransition,
+  type SurfaceEventType,
+  type SurfacePhase,
+} from "../runtime/surfaceMachine";
+
+export interface SurfaceMachineLayer {
+  /** Vue-style transition-name prefix (e.g. "hk-modal-overlay"). */
+  prefix: string;
+  /** Live element accessor — lets the driver read the layer's EFFECTIVE
+   *  CSS duration (themes, reduced-motion, `data-css-animations="0"`). */
+  el?: () => HTMLElement | null | undefined;
+  /** Fallback enter budget, ms — the A2 bound when the element (or its
+   *  computed style) cannot be read. */
+  enterMs: () => number;
+  /** Fallback leave budget, ms. */
+  leaveMs: () => number;
+}
+
+export interface SurfaceMachineOptions {
+  layers: SurfaceMachineLayer[];
+  /**
+   * How long a `.from` phase waits for a frame flip before the timer
+   * forces it (ms). Under A2 (rAF starved) this bounds the from-pair's
+   * lifetime; the forced flip snaps (nothing is painting anyway).
+   */
+  flipBudgetMs?: number;
+  /** Extra ms on top of the CSS duration before a deadline fires. */
+  deadlineSlackMs?: number;
+  /** Phase-edge side effects (registration, focus, morph, reports). */
+  onPhase?: (from: SurfacePhase, to: SurfacePhase, event: SurfaceEventType) => void;
+}
+
+export interface SurfaceMachine {
+  /** Current phase (reactive — render-time reads track it). */
+  phase: ComputedRef<SurfacePhase>;
+  /** Whether the surface DOM should render (v-if anchor). */
+  mounted: ComputedRef<boolean>;
+  /** Reactive transition classes for one layer's prefix. */
+  classesFor: (prefix: string) => string[];
+  /** Dispatch an event through the total transition table. */
+  send: (event: SurfaceEventType) => void;
+}
+
+/**
+ * useSurfaceMachine — the Vue driver for the pure surface lifecycle
+ * machine (runtime/surfaceMachine.ts).
+ *
+ * Ownership rules that make the machine's proofs carry over:
+ * - Classes are bound REACTIVELY from the phase (render reads
+ *   `classesFor`), so the initial mount paints with its from-pair — no
+ *   write-after-mount race, no Vue `<Transition>` engine to diverge.
+ * - The ONLY correctness clock is setTimeout: every animation phase arms
+ *   exactly one deadline timer; the frame flip is double-rAF (smooth)
+ *   with a flip timer as the starved fallback. Duplicate FLIPs are
+ *   absorbed by the table (idempotent self-loops).
+ * - Phase changes clear every pending timer/rAF before arming the next
+ *   phase's — at most one flip + one deadline exist at any moment, so
+ *   timers cannot leak or fire stale (the machine has no "late
+ *   completion" callbacks at all).
+ */
+export function useSurfaceMachine(options: SurfaceMachineOptions): SurfaceMachine {
+  const flipBudget = options.flipBudgetMs ?? 120;
+  const slack = options.deadlineSlackMs ?? 80;
+
+  const phase = shallowRef<SurfacePhase>("closed");
+  const mounted = computed(() => isMounted(phase.value));
+
+  let flipTimer: ReturnType<typeof setTimeout> | null = null;
+  let deadlineTimer: ReturnType<typeof setTimeout> | null = null;
+  let raf1 = 0;
+  let raf2 = 0;
+
+  /** transitionend listeners for the TEND early completion (see
+   *  armTend) — cleared with every clock reset so a phase change can
+   *  never inherit the previous phase's listeners. */
+  let tendCleanups: Array<() => void> = [];
+
+  function clearClock(): void {
+    if (flipTimer !== null) {
+      clearTimeout(flipTimer);
+      flipTimer = null;
+    }
+    if (deadlineTimer !== null) {
+      clearTimeout(deadlineTimer);
+      deadlineTimer = null;
+    }
+    for (const off of tendCleanups) off();
+    tendCleanups = [];
+    if (raf1) cancelAnimationFrame(raf1);
+    if (raf2) cancelAnimationFrame(raf2);
+    raf1 = 0;
+    raf2 = 0;
+  }
+
+  /** TEND wiring — the advisory early-completion event. Real browsers
+   *  fire transitionend when the slowest property lands; the deadline
+   *  timer stays armed as the bound (starved or cancelled transitions
+   *  never fire it — the machine stays correct either way, TEND only
+   *  shortens the settle latency). Filter rules:
+   *  - e.target must be the layer element itself (child bubbles — the
+   *    content's own transitions — must not complete the surface);
+   *  - elapsedTime must match the measured budget (the SLOWEST
+   *    property's end event; faster properties of the same element are
+   *    ignored). The table absorbs a TEND in any phase, so a late or
+   *    duplicated event is a no-op. */
+  function armTend(expectedMs: number): void {
+    // Several layers may share one element (drawer sides, popover
+    // branches) — one listener per ELEMENT, not per layer.
+    const seen = new Set<HTMLElement>();
+    for (const layer of options.layers) {
+      const el = layer.el?.();
+      if (!el || !el.isConnected || seen.has(el)) continue;
+      seen.add(el);
+      const onEnd = (e: TransitionEvent) => {
+        if (e.target !== el) return;
+        // An event without a numeric elapsedTime cannot be validated
+        // against the budget — ignore it (the deadline stays the bound;
+        // TEND is strictly an optimization).
+        if (typeof e.elapsedTime !== "number") return;
+        const elapsedMs = e.elapsedTime * 1000;
+        // Two-sided epsilon: only the SLOWEST property's end event — the
+        // one landing at the measured budget — completes the surface.
+        // Faster properties are below the window; an unrelated LONGER
+        // transition on the element (consumer classes ride the panel)
+        // is above it and must not fire the surface's completion.
+        if (elapsedMs + 60 < expectedMs || elapsedMs - 60 > expectedMs) return;
+        send("TEND");
+      };
+      el.addEventListener("transitionend", onEnd);
+      tendCleanups.push(() => el.removeEventListener("transitionend", onEnd));
+    }
+  }
+
+  /** Worst-case deadline for the phase being entered, from the CONFIGURED
+   *  budgets (the A2 bound when the live CSS cannot be read). */
+  function budgetFor(next: SurfacePhase): number {
+    switch (next) {
+      case "openingFrom":
+        return flipBudget + Math.max(...options.layers.map((l) => l.enterMs())) + slack;
+      case "openingTo":
+        return Math.max(...options.layers.map((l) => l.enterMs())) + slack;
+      case "closingFrom":
+        return flipBudget + Math.max(...options.layers.map((l) => l.leaveMs())) + slack;
+      case "closingTo":
+        return Math.max(...options.layers.map((l) => l.leaveMs())) + slack;
+      default:
+        return 0;
+    }
+  }
+
+  /** Effective CSS transition duration of one layer, ms — the maximum
+   *  across the comma-separated duration list ("0.3s, 0.25s"). Reduced
+   *  motion and `html[data-css-animations="0"]` both collapse this to 0,
+   *  which is exactly the fast-path signal.
+   *  Caveat: `transition-delay` is deliberately ignored (no current
+   *  surface staggers its layers) — a future adopter adding delays must
+   *  fold them into the layer's enter/leave fallback budgets. */
+  function cssDurationMs(el: HTMLElement): number {
+    const raw = window.getComputedStyle(el).transitionDuration;
+    if (!raw) return 0;
+    let max = 0;
+    for (const part of raw.split(",")) {
+      const value = parseFloat(part);
+      if (!Number.isFinite(value)) continue;
+      max = Math.max(max, part.includes("ms") ? value : value * 1000);
+    }
+    return max;
+  }
+
+  /** Max effective CSS duration across layers, or null when no layer
+   *  element is readable (surface mid-mount) — the caller falls back to
+   *  the configured budget. */
+  function measuredBudget(): number | null {
+    let max: number | null = null;
+    for (const layer of options.layers) {
+      const el = layer.el?.();
+      if (!el || !el.isConnected) continue;
+      max = Math.max(max ?? 0, cssDurationMs(el));
+    }
+    return max;
+  }
+
+  function rearmDeadline(ms: number): void {
+    if (deadlineTimer !== null) clearTimeout(deadlineTimer);
+    deadlineTimer = setTimeout(() => {
+      deadlineTimer = null;
+      send("DEADLINE");
+    }, Math.max(0, ms));
+  }
+
+  /** Zero-duration completion: no CSS transitions are running, so the
+   *  surface's logical open/close can settle on the MICROtask queue —
+   *  ahead of every macrotask (a 0ms timer loses macrotask-order races
+   *  against caller setTimeout(0)s, e.g. test harnesses; real browsers
+   *  never take this path). The table absorbs a DEADLINE in any phase,
+   *  so a microtask that lands after an unrelated phase change is a
+   *  no-op. */
+  function completeNow(): void {
+    if (deadlineTimer !== null) {
+      clearTimeout(deadlineTimer);
+      deadlineTimer = null;
+    }
+    queueMicrotask(() => { send("DEADLINE"); });
+  }
+
+  function armClock(next: SurfacePhase): void {
+    clearClock();
+    if (next === "closed" || next === "open") return;
+    // Frame flip: double-rAF guarantees a style recalc between the
+    // from-pair and the to-pair (a same-recalc flip would coalesce into
+    // an instant jump); the flip timer forces the same event when rAF
+    // starves. Both may fire — the table absorbs the duplicate.
+    if (next === "openingFrom" || next === "closingFrom") {
+      raf1 = requestAnimationFrame(() => {
+        raf1 = 0;
+        raf2 = requestAnimationFrame(() => {
+          raf2 = 0;
+          send("FLIP");
+        });
+      });
+      flipTimer = setTimeout(() => {
+        flipTimer = null;
+        send("FLIP");
+      }, flipBudget);
+    }
+    deadlineTimer = setTimeout(() => {
+      deadlineTimer = null;
+      send("DEADLINE");
+    }, budgetFor(next));
+
+    // Effective-duration probe: once the layer elements are live (one
+    // microtask after the mounting patch), replace the configured bound
+    // with what the CSS actually says. A zero duration (no transitions
+    // — happy-dom, reduced motion, the global animation switch) makes
+    // the deadline fire on the next macrotask, restoring the legacy
+    // instant-completion semantics; a long theme gets its real budget.
+    // The phase guard makes a late probe a no-op.
+    if (next === "openingFrom" || next === "closingFrom") {
+      const phaseAtArm = next;
+      void nextTick(() => {
+        if (phase.value !== phaseAtArm) return;
+        const measured = measuredBudget();
+        if (measured === null) return;
+        if (measured > 0) rearmDeadline(flipBudget + measured + slack);
+        else completeNow();
+      });
+    } else {
+      // *.to phases: the elements exist and styles settled at the flip.
+      const measured = measuredBudget();
+      if (measured !== null) {
+        if (measured > 0) {
+          rearmDeadline(measured + slack);
+          armTend(measured);
+        } else {
+          completeNow();
+        }
+      }
+    }
+  }
+
+  function send(event: SurfaceEventType): void {
+    const from = phase.value;
+    const to = surfaceTransition(from, event);
+    if (to === from) return; // table-idempotent absorb (no effects)
+    phase.value = to;
+    armClock(to);
+    options.onPhase?.(from, to, event);
+  }
+
+  onBeforeUnmount(() => {
+    clearClock();
+    // UNMOUNT walks any phase to `closed` so onPhase observers see a
+    // consistent final state even mid-animation.
+    send("UNMOUNT");
+    clearClock();
+  });
+
+  function classesFor(prefix: string): string[] {
+    return classesForPair(prefix, classPairOf(phase.value));
+  }
+
+  return { phase: computed(() => phase.value), mounted, classesFor, send };
+}