@celestia-island/hikari 0.55.195 → 0.55.196

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.195",
+  "version": "0.55.196",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkTransitionContainer.scss

@@ -0,0 +1,13 @@
+// HkTransitionContainer — the state-keyed morph container. The host
+// carries the inline size (transitioned by the component); the stage
+// is the measured content. Overflow hides DURING the morph only (the
+// host is `overflow: clip` while a pinned size is active — applied via
+// the inline width/height, the clip rides along) so shortened content
+// never spills past the animating box.
+.hk-tc {
+  overflow: clip;
+}
+
+.hk-tc-stage {
+  width: 100%;
+}

package/src/components/HkTransitionContainer.test.tsx

@@ -0,0 +1,127 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, ref, type App } from "vue";
+
+import HkTransitionContainer from "./HkTransitionContainer";
+import {
+  DEFAULT_ANIMATION_DURATION_MS,
+  animationLoopArmedCount,
+  onAnimationFrame,
+} from "../composables/useAnimationLoop";
+
+/** Shared-container discipline (HkCrossfade.test precedent): every
+ *  case appends its own container; afterEach tears them all down. */
+const containers: HTMLElement[] = [];
+
+interface Harness {
+  app: App;
+  container: HTMLElement;
+  key: { value: string };
+  swaps: Array<{ key: string | number; previous: string | number; durationMs: number }>;
+}
+
+function mountContainer(initial = "a"): Harness {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+  const key = ref(initial);
+  const swaps: Harness["swaps"] = [];
+  const Wrapper = defineComponent({
+    setup() {
+      return () => (
+        <HkTransitionContainer
+          swapKey={key.value}
+          onSwap={(e: { key: string | number; previous: string | number; durationMs: number }) => {
+            swaps.push(e);
+          }}
+        >
+          <p>{`panel-${key.value}`}</p>
+        </HkTransitionContainer>
+      );
+    },
+  });
+  const app = createApp(Wrapper);
+  app.mount(container);
+  return { app, container, key, swaps };
+}
+
+afterEach(() => {
+  for (const c of containers.splice(0)) c.remove();
+});
+
+describe("HkTransitionContainer", () => {
+  it("renders the slot inside the morph host", () => {
+    const t = mountContainer("a");
+    const host = t.container.querySelector<HTMLElement>(".hk-tc");
+    const stage = t.container.querySelector<HTMLElement>(".hk-tc-stage");
+    expect(host).not.toBeNull();
+    expect(stage).not.toBeNull();
+    expect(t.container.textContent).toContain("panel-a");
+    t.app.unmount();
+  });
+
+  it("defaults to the 300ms family duration on the host transition", () => {
+    const t = mountContainer("a");
+    const host = t.container.querySelector<HTMLElement>(".hk-tc");
+    expect(host?.style.transitionDuration).toBe(`${DEFAULT_ANIMATION_DURATION_MS}ms`);
+    expect(DEFAULT_ANIMATION_DURATION_MS).toBe(300);
+    t.app.unmount();
+  });
+
+  it("axis=width transitions only the width property", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const app = createApp({
+      render: () => (
+        <HkTransitionContainer swapKey="a" axis="width">
+          <p>x</p>
+        </HkTransitionContainer>
+      ),
+    });
+    app.mount(container);
+    const host = container.querySelector<HTMLElement>(".hk-tc");
+    expect(host?.style.transitionProperty).toBe("width");
+    app.unmount();
+  });
+
+  it("survives a swapKey change without ResizeObserver (degraded path, no NaN)", async () => {
+    const t = mountContainer("login");
+    t.key.value = "org";
+    await new Promise((r) => setTimeout(r, DEFAULT_ANIMATION_DURATION_MS + 120));
+    // jsdom has no ResizeObserver and zero offsets: no morph, no crash,
+    // and any pinned inline size is well-formed (never NaNpx).
+    const host = t.container.querySelector<HTMLElement>(".hk-tc");
+    expect(host?.style.width).not.toContain("NaN");
+    expect(host?.style.height).not.toContain("NaN");
+    t.app.unmount();
+  });
+});
+
+describe("useAnimationLoop (shared rAF context)", () => {
+  it("registers and unregisters; the loop idles at zero", () => {
+    const cb = vi.fn();
+    const off = onAnimationFrame(cb);
+    expect(animationLoopArmedCount()).toBe(1);
+    off();
+    expect(animationLoopArmedCount()).toBe(0);
+  });
+
+  it("dedupes the same callback registration", () => {
+    const cb = vi.fn();
+    const off1 = onAnimationFrame(cb);
+    const off2 = onAnimationFrame(cb);
+    expect(animationLoopArmedCount()).toBe(1);
+    off1();
+    expect(animationLoopArmedCount()).toBe(0);
+    off2();
+    expect(animationLoopArmedCount()).toBe(0);
+  });
+
+  it("unregister is idempotent", () => {
+    const cb = vi.fn();
+    const off = onAnimationFrame(cb);
+    off();
+    off();
+    expect(animationLoopArmedCount()).toBe(0);
+  });
+});

package/src/components/HkTransitionContainer.tsx

@@ -0,0 +1,154 @@
+import { defineComponent, nextTick, onBeforeUnmount, ref, watch, type PropType } from "vue";
+
+import { DEFAULT_ANIMATION_DURATION_MS } from "../composables/useAnimationLoop";
+import HkCrossfade from "./HkCrossfade";
+
+import "./HkTransitionContainer.scss";
+
+/**
+ * HkTransitionContainer — the state-keyed morph container.
+ *
+ * HkCrossfade's height-safe dissolve, PLUS the size choreography the
+ * user direction (2026-10-22) asks of every swap surface: when the
+ * bound state key changes, the OLD content fades out, the container's
+ * width/height smoothly animate to the incoming content's natural
+ * size, and the NEW content fades in — one 300ms default, CSS-driven
+ * (transition on inline size), with the animation-loop registration
+ * kept for the choreography CSS cannot express.
+ *
+ * Binding: `swapKey` is the identity of the content on stage — the same
+ * contract HkCrossfade owns (same value ⇒ no swap). Tabs, segmented
+ * controls, editor mode switches, chat-node state labels all reduce to
+ * "a key changed; morph to the new panel".
+ *
+ * Scroll handoff (loose coupling, per the user's spec): the container
+ * never touches any scroller itself. Each swap emits a `swap` event
+ * carrying `{ key, previous, durationMs }`; the HOST forwards that to
+ * its scroll container's PUBLIC interface — the same scrollTo API used
+ * for back-to-top and jump-to-line — so the scrollbar adapts to the
+ * size change and the caret/anchor coordinate glides instead of
+ * teleporting. The scroll container needs zero knowledge of this
+ * component.
+ *
+ * Sizing: a ResizeObserver on the inner stage feeds the container's
+ * inline width/height; the CSS transition on those properties does the
+ * actual morph (off-thread, cancellable, respects the global animation
+ * switch via the duration override to 0s). When the observer is
+ * unavailable (older webview, SSR, jsdom) the container degrades to
+ * plain auto sizing — a dissolve without the morph, never a broken
+ * layout.
+ */
+export default defineComponent({
+  name: "HkTransitionContainer",
+  props: {
+    /** Identity of the content on stage; changing it starts the morph. */
+    swapKey: { type: [String, Number] as PropType<string | number>, required: true },
+    /** Which axes morph. `height` is the default (most swap surfaces);
+     * `width` for horizontal morphs (segmented panels); `both` for
+     * free-floating cards. */
+    axis: {
+      type: String as PropType<"height" | "width" | "both">,
+      default: "height",
+    },
+    /** Morph + dissolve duration, ms. Family default 300. */
+    duration: { type: Number, default: DEFAULT_ANIMATION_DURATION_MS },
+    tag: { type: String, default: "div" },
+  },
+  emits: {
+    /** Fired when a swap settles: the host forwards this to its scroll
+     * container's public scrollTo interface. */
+    swap: (payload: { key: string | number; previous: string | number; durationMs: number }) => true,
+  },
+  setup(props, { slots, emit }) {
+    const hostRef = ref<HTMLElement | null>(null);
+    const stageRef = ref<HTMLElement | null>(null);
+    // Pinned inline size: `{ w, h }` while morphing, `null` = auto.
+    const pinned = ref<{ w: number; h: number } | null>(null);
+
+    let observer: ResizeObserver | null = null;
+    let pendingKey: string | number | null = null;
+    let settleTimer: ReturnType<typeof setTimeout> | null = null;
+
+    function readStage(): { w: number; h: number } {
+      const el = stageRef.value;
+      if (!el) return { w: 0, h: 0 };
+      return { w: el.offsetWidth, h: el.offsetHeight };
+    }
+
+    function applyPinned(): void {
+      const el = hostRef.value;
+      if (!el) return;
+      const p = pinned.value;
+      el.style.width = p && props.axis !== "height" ? `${p.w}px` : "";
+      el.style.height = p && props.axis !== "width" ? `${p.h}px` : "";
+    }
+
+    function observe(): void {
+      if (typeof ResizeObserver === "undefined" || !stageRef.value) return;
+      observer?.disconnect();
+      observer = new ResizeObserver((entries) => {
+        const rect = entries[0]?.contentRect;
+        if (!rect || pendingKey === null) return;
+        // Stage settled at the incoming content's natural size: pin to
+        // it (from the outgoing size) → next frame the CSS transition
+        // morphs the container; after the duration, release to auto.
+        pinned.value = { w: Math.ceil(rect.width), h: Math.ceil(rect.height) };
+        applyPinned();
+        if (settleTimer !== null) clearTimeout(settleTimer);
+        settleTimer = setTimeout(() => {
+          pinned.value = null;
+          applyPinned();
+          const key = pendingKey;
+          pendingKey = null;
+          if (key !== null) {
+            emit("swap", { key, previous: previousKey, durationMs: props.duration });
+          }
+        }, props.duration + 40);
+      });
+      observer.observe(stageRef.value);
+    }
+
+    let previousKey: string | number = props.swapKey;
+
+    watch(() => props.swapKey, (next) => {
+      // Pin the OUTGOING size first so the container never collapses
+      // through zero while the content swaps underneath.
+      pendingKey = next;
+      pinned.value = readStage();
+      applyPinned();
+      void nextTick(() => observe());
+    });
+
+    onBeforeUnmount(() => {
+      observer?.disconnect();
+      observer = null;
+      if (settleTimer !== null) clearTimeout(settleTimer);
+    });
+
+    return () => {
+      const Tag = props.tag as "div" | "section" | "main" | "aside";
+      const d = `${props.duration}ms`;
+      return (
+        <Tag
+          ref={hostRef}
+          class="hk-tc"
+          style={{
+            transitionProperty:
+              props.axis === "both" ? "width, height" : props.axis === "width" ? "width" : "height",
+            transitionDuration: d,
+          }}
+        >
+          {/* The stage is HkCrossfade: it owns the opacity dissolve
+            (both generations stacked in one grid cell — no exit blank,
+            no collapse flash) and the swap-stall watchdog; THIS
+            component owns the measured size morph around it. */}
+          <div ref={stageRef} class="hk-tc-stage">
+            <HkCrossfade swapKey={props.swapKey}>
+              {slots.default?.()}
+            </HkCrossfade>
+          </div>
+        </Tag>
+      );
+    };
+  },
+});

package/src/composables/useAnimationLoop.ts

@@ -0,0 +1,95 @@
+/**
+ * useAnimationLoop — the family's ONE shared requestAnimationFrame loop.
+ *
+ * Every JS-driven animation in the library registers a callback here
+ * instead of opening its own rAF chain: the context owns a single loop
+ * that runs ONLY while at least one callback is registered, and each
+ * frame dispatches `(now, deltaMs)` to every callback that was armed at
+ * frame start (a callback that registers/unregisters mid-frame takes
+ * effect next frame — the iteration walks a snapshot). CSS transitions
+ * remain the preferred vehicle (the browser composites them
+ * off-thread); this loop is for the choreography CSS cannot express —
+ * measured size morphs, staged state sequences, scroll handshakes
+ * (user direction 2026-10-22).
+ *
+ * The family-wide default duration for BOTH CSS and loop-driven
+ * animation is 300ms (`DEFAULT_ANIMATION_DURATION_MS`), matching the
+ * design system's `--duration-normal` token — one number, everywhere.
+ */
+
+/** The family-wide animation default: 300ms (== `--duration-normal`). */
+export const DEFAULT_ANIMATION_DURATION_MS = 300;
+
+/** First-frame delta stand-in: one 60Hz frame. */
+const DEFAULT_FRAME_DELTA_MS = 1000 / 60;
+
+/** A per-frame callback: absolute rAF timestamp + ms since last frame. */
+export type AnimationFrameCallback = (nowMs: number, deltaMs: number) => void;
+
+interface LoopState {
+  callbacks: Set<AnimationFrameCallback>;
+  handle: number | null;
+  last: number | null;
+}
+
+// Module-level singleton: one loop per document, however many consumers.
+const state: LoopState = { callbacks: new Set(), handle: null, last: null };
+
+function engine(nowMs: number): void {
+  // Snapshot BEFORE mutating state: mid-frame (un)registrations land
+  // next frame, and a callback never runs twice inside one frame.
+  const armed = Array.from(state.callbacks);
+  const prev = state.last;
+  if (armed.length > 0) {
+    state.handle = requestAnimationFrame(engine);
+    state.last = nowMs;
+  } else {
+    state.handle = null;
+    state.last = null;
+  }
+  const delta = prev === null ? DEFAULT_FRAME_DELTA_MS : Math.max(0, nowMs - prev);
+  for (const cb of armed) cb(nowMs, delta);
+}
+
+/**
+ * Register a per-frame callback. Returns the unregister function; call
+ * it when the animation settles (or the component unmounts). Registering
+ * the SAME function twice is idempotent (Set semantics). The loop is
+ * lazily started by the first registration and stops itself the moment
+ * the last callback unregisters — idle pages pay zero rAF churn.
+ */
+export function onAnimationFrame(cb: AnimationFrameCallback): () => void {
+  state.callbacks.add(cb);
+  if (state.handle === null) {
+    state.last = null;
+    state.handle = requestAnimationFrame(engine);
+  }
+  return () => {
+    state.callbacks.delete(cb);
+    if (state.callbacks.size === 0 && state.handle !== null) {
+      cancelAnimationFrame(state.handle);
+      state.handle = null;
+      state.last = null;
+    }
+  };
+}
+
+/** Test/introspection hook: how many callbacks are armed right now. */
+export function animationLoopArmedCount(): number {
+  return state.callbacks.size;
+}
+
+/**
+ * Component-facing wrapper: one registration bound to one callback
+ * (register on creation, `dispose()` when the owner unmounts). The
+ * callback receives `(nowMs, deltaMs)` every frame while armed.
+ */
+export function useAnimationLoop(cb: AnimationFrameCallback): { dispose: () => void } {
+  let off: (() => void) | null = onAnimationFrame(cb);
+  return {
+    dispose(): void {
+      off?.();
+      off = null;
+    },
+  };
+}

package/src/index.ts

@@ -613,6 +613,7 @@ export { default as HkColorPicker } from "./components/HkColorPicker";
 export { default as HkCopyBadge } from "./components/HkCopyBadge";
 export { default as HkConfirmDialog } from "./components/HkConfirmDialog";
 export { default as HkCrossfade } from "./components/HkCrossfade";
+export { default as HkTransitionContainer } from "./components/HkTransitionContainer";
 export { default as HkDivider } from "./components/HkDivider";
 export { default as HkDiffViewer } from "./components/HkDiffViewer";
 export { parseUnifiedDiff, computeGaps } from "./components/diffParse";