@celestia-island/hikari 0.45.8 → 0.45.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.45.8",
+  "version": "0.45.9",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkCrossfade.scss

@@ -0,0 +1,61 @@
+/* HkCrossfade — same-position simultaneous dissolve host.
+ *
+ * Geometry: the host is a one-cell grid and every item occupies THAT cell
+ * (grid-area: 1/1). During a swap the leaving item keeps the cell, so old
+ * and new stack in the SAME box: no exit blank phase, no side-by-side
+ * reflow, and the host stays as tall as the taller of the two items until
+ * the leave completes — variable-height content never collapses mid-
+ * dissolve. This is the height-safe generalization of HkPickerPane's fixed
+ * stage + absolute leave (no known stage size needed, so whole pages can
+ * swap through it).
+ *
+ * Consumers size the host from the outside (width/height/flex are theirs);
+ * the component only guarantees the stacking geometry and the dissolve.
+ */
+.hk-crossfade {
+  display: grid;
+
+  > .hk-crossfade-item {
+    grid-area: 1 / 1;
+    width: 100%;
+    min-width: 0;
+  }
+}
+
+/* Dissolve curves: BOTH sides run --duration-normal so the exchange is a
+ * true cross-fade (not a fade-out-then-in), and both ease OUT (fast
+ * start) — midway through the swap the incoming layer already carries most
+ * of the opacity while the outgoing one has already shed most of its, so
+ * the composite never dips toward the background (the classic
+ * double-exposure artifact of symmetric linear fades). The leaving item
+ * also drops pointer events: it is dead content and must not intercept
+ * clicks while it dissolves under the incoming one. */
+.hk-crossfade-enter-active {
+  transition:
+    opacity
+    var(--duration-normal, 0.3s)
+    var(--ease-out-expo, cubic-bezier(0.19, 1, 0.22, 1));
+}
+
+.hk-crossfade-leave-active {
+  transition: opacity var(--duration-normal, 0.3s) ease-out;
+  pointer-events: none;
+}
+
+.hk-crossfade-enter-from,
+.hk-crossfade-leave-to {
+  opacity: 0;
+}
+
+/* Reduced motion: keep the opacity exchange (a fade carries no movement —
+ * HkPhaseTransition precedent), just shorter. Hosts driving the global
+ * animation switch (`html[data-css-animations="0"]`) already pin every
+ * transition via theme.scss's global rule, so no extra variant is needed
+ * here (that variant exists for ANIMATIONS, which the global rule pauses
+ * per-play-state; transitions die through its transition-duration clamp). */
+@media (prefers-reduced-motion: reduce) {
+  .hk-crossfade-enter-active,
+  .hk-crossfade-leave-active {
+    transition: opacity var(--duration-fast, 0.15s) ease;
+  }
+}

package/src/components/HkCrossfade.test.tsx

@@ -0,0 +1,270 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref, type App } from "vue";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as sass from "sass";
+
+import HkCrossfade, { CROSSFADE_WATCHDOG_MS } from "./HkCrossfade";
+
+/**
+ * HkCrossfade contract tests. House style: no @vue/test-utils dependency —
+ * raw createApp mounts on shared containers torn down after each case.
+ *
+ * Timing model (mirrors ModeMorphTabs.test): happy-dom resolves no CSS
+ * transition durations, so with a working (timer-driven) rAF the swap
+ * completes inside fake-timer advances. Freezing rAF via stubGlobal holds
+ * both transition generations in the DOM — which is exactly the state the
+ * simultaneous dissolve and the watchdog are about.
+ */
+
+const mounts: App[] = [];
+const containers: HTMLElement[] = [];
+
+interface Harness {
+  container: HTMLElement;
+  set: (key: string) => Promise<void>;
+}
+
+function mountCrossfade(opts: {
+  initial?: string;
+  appear?: boolean;
+  disabled?: boolean;
+} = {}): Harness {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const current = ref(opts.initial ?? "a");
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(
+          HkCrossfade,
+          {
+            swapKey: current.value,
+            appear: opts.appear ?? false,
+            disabled: opts.disabled ?? false,
+          },
+          {
+            default: () => h("p", { class: "body" }, `body-${current.value}`),
+          },
+        );
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  return {
+    container,
+    set: async (key: string) => {
+      current.value = key;
+      await nextTick();
+    },
+  };
+}
+
+function items(host: HTMLElement): HTMLElement[] {
+  // The mount container holds the .hk-crossfade host; items are the HOST's
+  // direct children (Transition renders no DOM of its own).
+  return Array.from(
+    host.querySelectorAll<HTMLElement>(":scope > .hk-crossfade > .hk-crossfade-item"),
+  );
+}
+
+function keys(host: HTMLElement): Array<string | undefined> {
+  return items(host).map((el) => el.dataset.crossfadeKey);
+}
+
+function assertNoFrozenClasses(el: HTMLElement): void {
+  for (const cls of Array.from(el.classList)) {
+    expect(cls.startsWith("hk-crossfade-enter") || cls.startsWith("hk-crossfade-leave")).toBe(false);
+  }
+}
+
+function freezeRaf(): void {
+  vi.stubGlobal("requestAnimationFrame", (_cb: FrameRequestCallback) => 0 as unknown as number);
+  vi.stubGlobal("cancelAnimationFrame", () => {});
+}
+
+afterEach(() => {
+  for (const app of mounts) app.unmount();
+  mounts.length = 0;
+  document.body.innerHTML = "";
+  containers.length = 0;
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe("HkCrossfade — DOM contract", () => {
+  it("renders the active item silently on first paint (appear off)", () => {
+    vi.useFakeTimers();
+    const { container } = mountCrossfade({ initial: "a" });
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("a");
+    expect(list[0]!.textContent).toContain("body-a");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("healthy swap completes through the Transition and settles on the new item", async () => {
+    vi.useFakeTimers();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    // Past the watchdog budget: the swap completed through the Transition
+    // long before, and the watchdog fired into a settled DOM as a no-op.
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS + 100);
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("b");
+    expect(list[0]!.textContent).toContain("body-b");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("dissolves SIMULTANEOUSLY: old and new share the same host mid-swap (no out-in gap)", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    await vi.advanceTimersByTimeAsync(200); // inside the watchdog budget
+    const list = items(container);
+    // Both generations mounted at once — the default-mode contract. With
+    // `mode="out-in"` the old item would already be gone here (blank phase);
+    // with a bare default Transition they would sit side by side instead of
+    // stacked in one host cell.
+    expect(keys(container)).toEqual(["a", "b"]);
+    expect(list[0]!.classList.contains("hk-crossfade-leave-active")).toBe(true);
+    expect(list[1]!.classList.contains("hk-crossfade-enter-from")).toBe(true);
+  });
+
+  it("watchdog completes a stalled swap: sweeps frozen classes, drops the stale item", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS - 100); // still wedged
+    expect(keys(container)).toEqual(["a", "b"]);
+    await vi.advanceTimersByTimeAsync(200); // past the budget
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("b");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("re-arms a fresh Transition on the next swap after a wedged one (dissolves resume)", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS + 100); // recovered once
+    expect(keys(container)).toEqual(["b"]);
+    // The next swap restores the Transition. The swept DOM left no previous
+    // child inside the fresh instance, so that one swap lands as a
+    // synchronous hard cut (the one-time cost of a stall) — settled and
+    // correct, no wedge loop.
+    await set("c");
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("c");
+    assertNoFrozenClasses(list[0]!);
+    // From there on, swaps run the dissolve again: with a previous child
+    // in the fresh Transition, the still-frozen rAF wedges this one, and
+    // the budget recovers it — every swap lands correct, at most one
+    // budget late.
+    await set("d");
+    await vi.advanceTimersByTimeAsync(200); // mid-swap: both generations
+    expect(keys(container)).toEqual(["c", "d"]);
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS); // recovered
+    const settled = items(container);
+    expect(settled).toHaveLength(1);
+    expect(settled[0]!.dataset.crossfadeKey).toBe("d");
+    assertNoFrozenClasses(settled[0]!);
+  });
+
+  it("appear dissolves the first item in; the watchdog un-freezes it under rAF starvation", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container } = mountCrossfade({ initial: "a", appear: true });
+    await vi.advanceTimersByTimeAsync(50);
+    expect(items(container)[0]!.classList.contains("hk-crossfade-enter-from")).toBe(true);
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS + 100);
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("a");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("disabled swaps synchronously with zero transition classes", async () => {
+    vi.useFakeTimers();
+    const { container, set } = mountCrossfade({ disabled: true });
+    await set("b");
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("b");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("re-rendering with the same swapKey swaps nothing", async () => {
+    vi.useFakeTimers();
+    const { container, set } = mountCrossfade({ initial: "a" });
+    await set("a");
+    await vi.advanceTimersByTimeAsync(100);
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    assertNoFrozenClasses(list[0]!);
+  });
+});
+
+describe("HkCrossfade — stylesheet contract", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+
+  it("stacks both generations in one grid cell — the same-position guarantee", () => {
+    const css = sass.compile(join(here, "HkCrossfade.scss")).css;
+    expect(css).toMatch(/\.hk-crossfade\s*\{[^}]*display:\s*grid/);
+    const item = css.match(/\.hk-crossfade-item[^{]*\{[^}]*\}/)?.[0] ?? "";
+    expect(item).toContain("grid-area: 1/1");
+  });
+
+  it("dissolves opacity only — no transform anywhere, dead layer drops pointer events", () => {
+    const css = sass.compile(join(here, "HkCrossfade.scss")).css;
+    expect(css).not.toContain("transform");
+    const leave = css.match(/\.hk-crossfade-leave-active[^{]*\{[^}]*\}/)?.[0] ?? "";
+    expect(leave).toContain("transition: opacity");
+    expect(leave).toContain("pointer-events: none");
+    expect(leave).toContain("var(--duration-normal, 0.3s)");
+    const enter = css.match(/\.hk-crossfade-enter-active[^{]*\{[^}]*\}/)?.[0] ?? "";
+    expect(enter).toContain("transition: opacity");
+    expect(enter).toContain("var(--duration-normal, 0.3s)");
+    for (const phase of ["enter-from", "leave-to"]) {
+      const block = css.match(new RegExp(`\\.hk-crossfade-${phase}[^{]*\\{[^}]*\\}`))?.[0] ?? "";
+      expect(block, `hk-crossfade-${phase} rule missing`).toContain("opacity: 0");
+    }
+  });
+
+  it("reduced motion keeps the opacity exchange, just shorter (fade survives, motion dies)", () => {
+    const css = sass.compile(join(here, "HkCrossfade.scss")).css;
+    const media = css.match(/@media \(prefers-reduced-motion: reduce\)\s*\{[\s\S]*\}\s*$/)?.[0] ?? "";
+    expect(media).toContain(".hk-crossfade-enter-active");
+    expect(media).toContain(".hk-crossfade-leave-active");
+    expect(media).toContain("var(--duration-fast, 0.15s)");
+  });
+});
+
+describe("HkCrossfade — wiring contract", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const src = readFileSync(join(here, "HkCrossfade.tsx"), "utf-8");
+
+  it("runs the Transition in default (simultaneous) mode and never overrides its duration", () => {
+    expect(src).toContain('<Transition\n            name="hk-crossfade"');
+    expect(src).not.toMatch(/<Transition[^>]*\bmode=/);
+    expect(src).not.toContain("duration={{");
+  });
+
+  it("pins the watchdog wiring and the animation-bus report", () => {
+    expect(src).toContain("export const CROSSFADE_WATCHDOG_MS = 450;");
+    expect(src).toContain("suppress.value = true;");
+    expect(src).toContain("el.remove();");
+    expect(src).toContain("useReportedTransition(REPORT_MS)");
+    expect(src).toContain("armReport(); armWatchdog();");
+  });
+});

package/src/components/HkCrossfade.tsx

@@ -0,0 +1,197 @@
+import { defineComponent, onBeforeUnmount, ref, Transition, watch, type PropType } from "vue";
+
+import { useReportedTransition } from "../composables/useReportedTransition";
+
+import "./HkCrossfade.scss";
+
+/** Swap-stall watchdog budget. Must sit above ANY healthy completion of the
+ *  dissolve (--duration-normal 0.3s; 0s under reduced motion or the global
+ *  animation switch) so the sweep only ever bites a genuinely stalled swap.
+ *  Exported for tests and budget-pinning. */
+export const CROSSFADE_WATCHDOG_MS = 450;
+
+/** Animation-bus report window — covers the watchdog budget so JS
+ *  choreography reacting to a swap outlives the CSS work under every
+ *  timing, including a stalled one. */
+const REPORT_MS = CROSSFADE_WATCHDOG_MS;
+
+/**
+ * HkCrossfade — same-position simultaneous dissolve for view/mode swaps.
+ *
+ * The library-level primitive for "the old content fades out WHILE the new
+ * content fades in, in place": a default-mode (NO `mode` prop) `<Transition>`
+ * whose enter and leave items share ONE grid cell, so the two generations
+ * stack at the same geometry for the duration of the dissolve — no exit
+ * blank phase (the `out-in` gap of HkPhaseTransition/HkStepFlow), no
+ * side-by-side reflow (a bare default-mode Transition), and no height
+ * collapse while both are mounted (the host stays as tall as the taller
+ * item until the leave completes). This is the height-safe generalization
+ * of HkPickerPane's fixed stage + absolute leave: it needs no known stage
+ * size, so whole pages (admin views, auth cards) can swap through it.
+ *
+ * Contract:
+ * - `swapKey` is the identity of the content on stage. The component owns
+ *   the keyed item wrapper (like HkPhaseTransition owns its key) so the
+ *   watchdog can tell stale items from the active one; rendering with the
+ *   same value swaps nothing.
+ * - Pure opacity — no transform, ever. Same-position means same-position.
+ *   Both sides run `--duration-normal` so the exchange is a true dissolve;
+ *   both ease out (fast start), which keeps the incoming (top) layer's
+ *   opacity ahead of the outgoing one's decay and stops the composite from
+ *   dipping toward the background mid-swap.
+ * - The leaving item drops pointer events: it is dead content and must not
+ *   intercept clicks while it dissolves under the incoming one.
+ * - `appear` dissolves the initially rendered item in; off by default —
+ *   first paint should never animate (view shells, restored state).
+ * - `disabled` renders the active item bare (synchronous swap, no watchdog):
+ *   the test escape hatch and the watchdog's degraded render path.
+ * - Reduced motion keeps the opacity exchange at `--duration-fast` (a fade
+ *   carries no movement — HkPhaseTransition precedent); hosts driving the
+ *   global animation switch (`html[data-css-animations="0"]`) already pin
+ *   these transitions via theme.scss.
+ * - Every swap is REPORTED to the runtime animation bus
+ *   (`useReportedTransition`, refcounted across the concurrent enter+leave)
+ *   so JS choreography reacting to the swap is not cut short by the CSS
+ *   work ending early.
+ * - The swap-stall watchdog bounds the rAF-starvation wedge (occluded or
+ *   backgrounded webview): Vue's Transition engine is rAF-gated, so a
+ *   starved swap freezes the leaving item on top of the new one (field
+ *   report 2026-09 in chest's ModeMorphTabs — the design this watchdog
+ *   inherits, alongside the surfaceMachine AXIOM A2 deadline rule). The
+ *   450ms budget sits above ANY healthy completion, so on healthy surfaces
+ *   the sweep fires into an already-settled DOM and is a no-op. After a
+ *   real stall it strips the frozen transition classes, removes the stale
+ *   item Vue can no longer unmount, and degrades to synchronous rendering
+ *   until the next `swapKey` change re-arms the Transition fresh.
+ */
+export default defineComponent({
+  name: "HkCrossfade",
+  props: {
+    swapKey: { type: [String, Number] as PropType<string | number>, required: true },
+    tag: { type: String, default: "div" },
+    appear: { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+  },
+  setup(props, { slots }) {
+    const hostRef = ref<HTMLElement | null>(null);
+    // Set after a watchdog sweep proved the Transition engine wedged; the
+    // render drops the Transition wrapper so keys apply synchronously until
+    // the next swap re-arms it (a one-tick toggle re-enters the wedged
+    // internal state otherwise — ModeMorphTabs lesson).
+    const suppress = ref(false);
+
+    // ── Animation-bus participation ──────────────────────────────────
+    // One swap runs an enter AND a leave concurrently; refcount them so
+    // the shared track stays armed until BOTH settle (HkListTransition
+    // pattern).
+    const report = useReportedTransition(REPORT_MS);
+    let pending = 0;
+    const armReport = () => {
+      pending++;
+      report.run();
+    };
+    const settleReport = () => {
+      pending = Math.max(0, pending - 1);
+      if (pending === 0) report.cancel();
+    };
+
+    // ── Swap-stall watchdog ──────────────────────────────────────────
+    let watchdog: ReturnType<typeof setTimeout> | null = null;
+
+    function armWatchdog(): void {
+      // Re-arm per swap event (enter or leave start); a healthy swap lets
+      // the timer fire into a settled DOM, where the sweep is a no-op.
+      if (watchdog !== null) clearTimeout(watchdog);
+      watchdog = setTimeout(onWatchdog, CROSSFADE_WATCHDOG_MS);
+    }
+
+    function sweepFrozenClasses(el: Element): boolean {
+      const frozenLeave = el.classList.contains("hk-crossfade-leave-active")
+        || el.classList.contains("hk-crossfade-leave-from");
+      el.classList.remove(
+        "hk-crossfade-enter-active",
+        "hk-crossfade-enter-from",
+        "hk-crossfade-enter-to",
+        "hk-crossfade-leave-active",
+        "hk-crossfade-leave-from",
+        "hk-crossfade-leave-to",
+      );
+      return frozenLeave;
+    }
+
+    function onWatchdog(): void {
+      watchdog = null;
+      const host = hostRef.value;
+      if (!host) return;
+      let wedged = false;
+      for (const el of Array.from(host.querySelectorAll<HTMLElement>(":scope > .hk-crossfade-item"))) {
+        const frozenLeave = sweepFrozenClasses(el);
+        // A stale item still holding a leave class is one Vue's rAF-gated
+        // engine can never unmount — remove it by hand and mark the engine
+        // wedged so this and future swaps render synchronously.
+        if (frozenLeave && el.dataset.crossfadeKey !== String(props.swapKey)) {
+          el.remove();
+          wedged = true;
+        }
+      }
+      if (wedged) suppress.value = true;
+    }
+
+    watch(() => props.swapKey, () => {
+      // Fresh swap: restore the Transition (the wedged one was discarded
+      // with the suppressed render). The watchdog re-arms from the
+      // beforeEnter/beforeLeave hooks of the new Transition instance.
+      suppress.value = false;
+    });
+    onBeforeUnmount(() => {
+      if (watchdog !== null) {
+        clearTimeout(watchdog);
+        watchdog = null;
+      }
+    });
+
+    return () => {
+      const Tag = props.tag as "div" | "section" | "main" | "aside";
+      const item = () => (
+        <div
+          key={props.swapKey}
+          class="hk-crossfade-item"
+          data-crossfade-key={String(props.swapKey)}
+        >
+          {slots.default?.()}
+        </div>
+      );
+
+      if (props.disabled || suppress.value) {
+        // Watchdog recovery / explicit opt-out: no Transition wrapper, so
+        // the key swap applies synchronously even with rAF frozen.
+        return (
+          <Tag ref={hostRef} class="hk-crossfade">
+            {item()}
+          </Tag>
+        );
+      }
+
+      return (
+        <Tag ref={hostRef} class="hk-crossfade">
+          {/* Deliberately NO `mode`: enter and leave run CONCURRENTLY in
+            the same grid cell — that is the whole point of this component.
+            A `mode="out-in"` here would reintroduce the exit blank phase;
+            `mode="in-out"` would double-stack full-opacity content. */}
+          <Transition
+            name="hk-crossfade"
+            appear={props.appear}
+            onBeforeEnter={() => { armReport(); armWatchdog(); }}
+            onAfterEnter={settleReport}
+            onEnterCancelled={settleReport}
+            onBeforeLeave={() => { armReport(); armWatchdog(); }}
+            onAfterLeave={settleReport}
+            onLeaveCancelled={settleReport}
+          >
+            {item()}
+          </Transition>
+        </Tag>
+      );
+    };
+  },
+});

package/src/index.ts

@@ -16,6 +16,7 @@ export { default as HColorPicker } from "./components/HkColorPicker";
 export { HColorSchemeDialog, type HCustomTheme } from "./components/HkColorSchemeDialog";
 export { HkColorSchemeEditor } from "./components/HkColorSchemeEditor";
 export { default as HConfirmDialog } from "./components/HkConfirmDialog";
+export { default as HCrossfade } from "./components/HkCrossfade";
 export { default as HDivider } from "./components/HkDivider";
 export { default as HDrawer } from "./components/HkDrawer";
 export { default as HEmptyState } from "./components/HkEmptyState";