@celestia-island/hikari 0.54.4 → 0.54.8

package/package.json

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

package/src/components/HkBlankCanvas.scss

@@ -0,0 +1,29 @@
+.hk-blank-canvas {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+}
+
+/* The mount is absolute so the host's renderer can size itself from the
+   element's box without this component ever contributing layout of its own
+   (a padded or scrolling parent would make the renderer's own measurements
+   disagree with the surface it draws on). */
+.hk-blank-canvas-mount {
+  position: absolute;
+  inset: 0;
+}
+
+/* Overlay chrome (device cards, leader lines, HUD) sits above the surface.
+   Pointer events pass through the layer and are re-enabled per child, so the
+   canvas keeps receiving gestures between the cards. */
+.hk-blank-canvas-overlay {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+.hk-blank-canvas-overlay > * {
+  pointer-events: auto;
+}

package/src/components/HkBlankCanvas.test.tsx

@@ -0,0 +1,147 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, type App } from "vue";
+
+import HkBlankCanvas from "./HkBlankCanvas";
+
+/**
+ * HkBlankCanvas tests — the size-ready gate, the resize/teardown signals and
+ * the overlay layer. The gate is the part worth pinning: initialising a
+ * renderer against a 0 × 0 element is what makes a 3D view flash a wrong
+ * first frame.
+ */
+
+const apps: App[] = [];
+let originalRect: typeof HTMLElement.prototype.getBoundingClientRect;
+let nextSize = { width: 0, height: 0 };
+/** Captured by the ResizeObserver stub so a test can drive a resize. */
+let observed: (() => void) | null = null;
+
+beforeEach(() => {
+  observed = null;
+  originalRect = HTMLElement.prototype.getBoundingClientRect;
+  HTMLElement.prototype.getBoundingClientRect = function (this: HTMLElement) {
+    if (this.classList?.contains("hk-blank-canvas-mount")) {
+      return {
+        width: nextSize.width,
+        height: nextSize.height,
+        top: 0,
+        left: 0,
+        right: nextSize.width,
+        bottom: nextSize.height,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      } as DOMRect;
+    }
+    return originalRect.call(this);
+  };
+  (globalThis as { ResizeObserver?: unknown }).ResizeObserver = class {
+    constructor(callback: () => void) {
+      observed = callback;
+    }
+    observe(): void {}
+    disconnect(): void {}
+    unobserve(): void {}
+  };
+});
+
+afterEach(() => {
+  for (const app of apps.splice(0)) app.unmount();
+  HTMLElement.prototype.getBoundingClientRect = originalRect;
+});
+
+/** The component measures inside a rAF, so tests wait one. */
+const oneFrame = () => new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+
+function mount(props: Record<string, unknown>, slots: Record<string, unknown> = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const Root = defineComponent({
+    setup() {
+      return () => h(HkBlankCanvas, props as never, slots);
+    },
+  });
+  const app = createApp(Root);
+  app.mount(container);
+  apps.push(app);
+  return container;
+}
+
+describe("HkBlankCanvas", () => {
+  it("does not mount while the element measures 0x0", async () => {
+    const onMount = vi.fn();
+    nextSize = { width: 0, height: 0 };
+    const root = mount({ onMount });
+    await nextTick();
+    await oneFrame();
+    expect(onMount).not.toHaveBeenCalled();
+    expect(root.querySelector(".hk-blank-canvas")?.hasAttribute("data-ready")).toBe(false);
+  });
+
+  it("mounts once the element has a size, and reports it", async () => {
+    const onMount = vi.fn();
+    nextSize = { width: 800, height: 600 };
+    const root = mount({ onMount });
+    await nextTick();
+    await oneFrame();
+    expect(onMount).toHaveBeenCalledTimes(1);
+    const [el, size] = onMount.mock.calls[0];
+    expect((el as HTMLElement).classList.contains("hk-blank-canvas-mount")).toBe(true);
+    expect(size).toEqual({ width: 800, height: 600 });
+    await nextTick();
+    expect(root.querySelector(".hk-blank-canvas")?.hasAttribute("data-ready")).toBe(true);
+  });
+
+  it("reports a later size change as a resize, never as a second mount", async () => {
+    const onMount = vi.fn();
+    const onResize = vi.fn();
+    nextSize = { width: 800, height: 600 };
+    mount({ onMount, onResize });
+    await nextTick();
+    await oneFrame();
+    expect(onMount).toHaveBeenCalledTimes(1);
+
+    nextSize = { width: 1024, height: 768 };
+    observed?.();
+    await nextTick();
+    expect(onMount).toHaveBeenCalledTimes(1);
+    expect(onResize).toHaveBeenCalledWith({ width: 1024, height: 768 });
+  });
+
+  it("does not report a resize when the box did not change", async () => {
+    const onResize = vi.fn();
+    nextSize = { width: 800, height: 600 };
+    mount({ onResize });
+    await nextTick();
+    await oneFrame();
+    observed?.();
+    await nextTick();
+    expect(onResize).not.toHaveBeenCalled();
+  });
+
+  it("signals teardown only after a successful mount", async () => {
+    const onUnmount = vi.fn();
+    nextSize = { width: 0, height: 0 };
+    mount({ onUnmount });
+    await nextTick();
+    await oneFrame();
+    for (const app of apps.splice(0)) app.unmount();
+    expect(onUnmount).not.toHaveBeenCalled();
+
+    // The same teardown after a real mount does fire.
+    nextSize = { width: 640, height: 480 };
+    mount({ onUnmount });
+    await nextTick();
+    await oneFrame();
+    for (const app of apps.splice(0)) app.unmount();
+    expect(onUnmount).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders the overlay above the mount", async () => {
+    nextSize = { width: 10, height: 10 };
+    const root = mount({}, { overlay: () => h("div", { class: "hud" }, "hud") });
+    await nextTick();
+    const overlay = root.querySelector(".hk-blank-canvas-overlay");
+    expect(overlay?.querySelector(".hud")?.textContent).toBe("hud");
+  });
+});

package/src/components/HkBlankCanvas.tsx

@@ -0,0 +1,125 @@
+import {
+  defineComponent,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  shallowRef,
+  type PropType,
+} from "vue";
+
+import "./HkBlankCanvas.scss";
+
+/** The size the host's renderer gets told about, in CSS pixels. */
+export interface BlankCanvasSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * HkBlankCanvas — the base view for a full-bleed mount.
+ *
+ * Some views are a canvas and nothing else: the 3D twin hands the whole
+ * surface to a three.js renderer, an embedded editor hands it to whatever
+ * the host embeds. Their shape is not a layout this library should model, so
+ * this component owns only the parts every one of them needs:
+ *
+ *   - **a 100% × 100% host** — the mount element fills its parent, and the
+ *     component imposes no padding, scroll container or chrome of its own;
+ *   - **a size-ready gate** — `onMount` is not called until the host has a
+ *     non-zero size. Initialising a WebGL context (or an editor) against a
+ *     0 × 0 element is the cause of the "first frame is wrong, then it
+ *     settles" flicker; waiting one frame for layout is cheaper than
+ *     rebuilding the surface;
+ *   - **resize and teardown signals** — `onResize` on every observed size
+ *     change, `onUnmount` before the element goes away, so a renderer can
+ *     dispose its GPU resources;
+ *   - **an overlay slot** — DOM drawn ABOVE the mount (device cards, leader
+ *     lines, HUD), which is what the 3D views put over their canvas.
+ *
+ * The component draws nothing itself: no background, no placeholder, no
+ * error state. A host that needs those renders them in the default slot or
+ * the overlay.
+ */
+export default defineComponent({
+  name: "HkBlankCanvas",
+  props: {
+    /** Called once, when the mount element first has a non-zero size. */
+    onMount: {
+      type: Function as PropType<((el: HTMLElement, size: BlankCanvasSize) => void) | undefined>,
+      default: undefined,
+    },
+    /** Called on every later size change (rounded to whole pixels). */
+    onResize: {
+      type: Function as PropType<((size: BlankCanvasSize) => void) | undefined>,
+      default: undefined,
+    },
+    /** Called before the mount element is removed. */
+    onUnmount: {
+      type: Function as PropType<(() => void) | undefined>,
+      default: undefined,
+    },
+    /** Accessible label for the mount region. */
+    ariaLabel: { type: String, default: undefined },
+  },
+  setup(props, { slots, expose }) {
+    const mountEl = shallowRef<HTMLElement | null>(null);
+    const size = ref<BlankCanvasSize>({ width: 0, height: 0 });
+    /** Whether `onMount` has fired — the gate that keeps a renderer from
+     *  initialising against a 0 × 0 element. */
+    const ready = ref(false);
+    let ro: ResizeObserver | null = null;
+
+    function measure(): BlankCanvasSize {
+      const el = mountEl.value;
+      if (!el) return { width: 0, height: 0 };
+      const rect = el.getBoundingClientRect();
+      return { width: Math.round(rect.width), height: Math.round(rect.height) };
+    }
+
+    function publish() {
+      const next = measure();
+      const changed = next.width !== size.value.width || next.height !== size.value.height;
+      if (changed) size.value = next;
+      if (!ready.value) {
+        if (next.width === 0 || next.height === 0) return;
+        ready.value = true;
+        props.onMount?.(mountEl.value as HTMLElement, next);
+        return;
+      }
+      if (changed) props.onResize?.(next);
+    }
+
+    onMounted(() => {
+      // One frame first: the element exists but its parent may not have been
+      // laid out yet, and the whole point of the gate is not to initialise
+      // against the pre-layout box.
+      requestAnimationFrame(publish);
+      if (typeof ResizeObserver !== "undefined" && mountEl.value) {
+        ro = new ResizeObserver(publish);
+        ro.observe(mountEl.value);
+      }
+    });
+
+    onBeforeUnmount(() => {
+      ro?.disconnect();
+      ro = null;
+      if (ready.value) props.onUnmount?.();
+      ready.value = false;
+    });
+
+    expose({ size, ready, measure });
+
+    return () => (
+      <div
+        class="hk-blank-canvas"
+        aria-label={props.ariaLabel}
+        data-ready={ready.value ? "" : undefined}
+      >
+        <div ref={mountEl} class="hk-blank-canvas-mount">
+          {slots.default?.()}
+        </div>
+        <div class="hk-blank-canvas-overlay">{slots.overlay?.()}</div>
+      </div>
+    );
+  },
+});

package/src/components/HkWaterfall.animate.test.tsx

@@ -0,0 +1,63 @@
+import { describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+/**
+ * `animate` is a pass-through: the waterfall hands it to the list
+ * transition as `disabled`. The main suite cannot see that — the transition
+ * only names its classes during an enter frame — so this file stubs the
+ * transition and asserts the flag it receives, which is what a host that
+ * suppresses animation during a bulk hydration actually depends on.
+ */
+const received: boolean[] = [];
+
+vi.mock("./HkListTransition", () => ({
+  default: defineComponent({
+    name: "HkListTransition",
+    props: { disabled: { type: Boolean, default: false } },
+    setup(props, { slots }) {
+      return () => {
+        received.push(props.disabled);
+        return h("div", { class: "stub-list" }, slots.default?.());
+      };
+    },
+  }),
+}));
+
+import HkWaterfall from "./HkWaterfall";
+
+async function mountWith(animate: boolean) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const Root = defineComponent({
+    setup() {
+      return () =>
+        h(
+          HkWaterfall,
+          { items: ["a1"], animate },
+          { card: ({ item }: { item: unknown }) => h("div", { class: "card" }, String(item)) },
+        );
+    },
+  });
+  const app = createApp(Root);
+  app.mount(container);
+  await nextTick();
+  return { app, container };
+}
+
+describe("HkWaterfall animate", () => {
+  it("leaves the transition enabled by default", async () => {
+    received.length = 0;
+    const mounted = await mountWith(true);
+    expect(received.length).toBeGreaterThan(0);
+    expect(received.every((disabled) => disabled === false)).toBe(true);
+    mounted.app.unmount();
+  });
+
+  it("disables the transition when animate is false", async () => {
+    received.length = 0;
+    const mounted = await mountWith(false);
+    expect(received.length).toBeGreaterThan(0);
+    expect(received.every((disabled) => disabled === true)).toBe(true);
+    mounted.app.unmount();
+  });
+});

package/src/components/HkWaterfall.scss

@@ -0,0 +1,43 @@
+.hk-waterfall {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  height: 100%;
+}
+
+.hk-waterfall-scroll {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+/* Section rhythm: the day buckets of the chat waterfalls read as separate
+   groups, so adjacent buckets get the same gutter as the cards inside them
+   (twice the card gap would over-separate the newest sections). */
+.hk-waterfall-bucket + .hk-waterfall-bucket {
+  margin-top: var(--space-12);
+}
+
+.hk-waterfall-columns {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-12);
+}
+
+/* Independent columns (not CSS columns): each keeps its own transition
+   group, so a card arriving in one column never reflows the other. */
+.hk-waterfall-column {
+  flex: 1 1 0;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-12);
+}
+
+/* A bucket with fewer cards than columns leaves an empty column behind.
+   Without this it keeps its `flex: 1 1 0` share of the row and the
+   surviving card renders at half width beside a ghost; collapsed, the card
+   takes the full width until the bucket grows a card for that column. */
+.hk-waterfall-column[data-empty] {
+  flex: 0 0 0;
+}