@celestia-island/hikari 0.55.212 → 0.55.214

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.212",
+  "version": "0.55.214",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",
@@ -37,6 +37,10 @@
     "./plugins": {
       "import": "./src/plugins/index.ts",
       "types": "./src/plugins/index.ts"
+    },
+    "./plugins/boot-chrome": {
+      "import": "./src/plugins/boot-chrome.mjs",
+      "types": "./src/plugins/boot-chrome.d.mts"
     }
   },
   "files": [

package/src/components/HkContextMenuProvider.content.test.tsx

@@ -0,0 +1,222 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, nextTick, ref } from "vue";
+
+import HkContextMenuProvider from "./HkContextMenuProvider";
+import HkTagDotRow from "./HkTagDotRow";
+import {
+  useContextMenu,
+  type ContextMenuApi,
+} from "../composables/useContextMenu";
+
+/** Mount into a detached div appended to the body (the menu panels
+ *  teleport; assertions see them through document.querySelectorAll). */
+function mountToDom(component: ReturnType<typeof defineComponent>): HTMLElement {
+  const el = document.createElement("div");
+  document.body.appendChild(el);
+  createApp(component).mount(el);
+  return el;
+}
+
+const popouts = () =>
+  Array.from(document.querySelectorAll(".hk-select-popout")) as HTMLElement[];
+
+const menuRows = () =>
+  Array.from(document.querySelectorAll(".hk-menu-row")) as HTMLButtonElement[];
+
+const headSlot = () => document.querySelector(".hk-menu-slot--head");
+const footSlot = () => document.querySelector(".hk-menu-slot--foot");
+
+/** The provider host, exposing the injected API to the test. */
+function makeHost(): { Component: ReturnType<typeof defineComponent>; api: () => ContextMenuApi } {
+  let held: ContextMenuApi | null = null;
+  const Inner = defineComponent({
+    name: "ContentInner",
+    setup() {
+      held = useContextMenu();
+      return () => <button class="open-btn">open</button>;
+    },
+  });
+  const Component = defineComponent({
+    name: "ContentHost",
+    setup() {
+      return () => (
+        <HkContextMenuProvider>
+          <Inner />
+        </HkContextMenuProvider>
+      );
+    },
+  });
+  return { Component, api: () => held! };
+}
+
+afterEach(() => {
+  document
+    .querySelectorAll(
+      ".hk-select-popout, .hk-select-sheet-panel, .hk-select-sheet-scrim, .open-btn",
+    )
+    .forEach((el) => el.remove());
+  window.history.replaceState(null, "");
+});
+
+/** nextTick + a macrotask + nextTick — panels mount/unmount through
+ *  transitions and history, so a single nextTick races them. */
+async function settle(): Promise<void> {
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await nextTick();
+}
+
+/** Wait until pred() holds (panel teardown settles asynchronously). */
+async function until(pred: () => boolean, ms = 500): Promise<void> {
+  const deadline = Date.now() + ms;
+  while (!pred() && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    await nextTick();
+  }
+}
+
+describe("HkContextMenuProvider — custom content regions", () => {
+  it("renders header and footer regions around the item rows", async () => {
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    api().open({
+      x: 100,
+      y: 80,
+      title: "Menu",
+      items: [{ key: "copy", label: "Copy" }],
+      header: () => (
+        <HkTagDotRow
+          tags={[{ key: "red", color: "#e5484d", label: "Red", active: true }]}
+          label="tags"
+          onToggle={() => {}}
+        />
+      ),
+      footer: () => <div class="content-foot">F</div>,
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    expect(popouts()).toHaveLength(1);
+
+    // The header hosts the tag strip; the footer its own node.
+    expect(headSlot()?.querySelector(".hk-tag-dot")).toBeTruthy();
+    expect(footSlot()?.querySelector(".content-foot")).toBeTruthy();
+
+    // Band order: header region → item rows → footer region.
+    const level = document.querySelector(".hk-menu-level")!;
+    const kinds = Array.from(level.children).map((el) =>
+      el.classList.contains("hk-menu-slot") && el.classList.contains("hk-menu-slot--head")
+        ? "head"
+        : el.classList.contains("hk-menu-slot") && el.classList.contains("hk-menu-slot--foot")
+          ? "foot"
+          : "row",
+    );
+    expect(kinds).toEqual(["head", "row", "foot"]);
+  });
+
+  it("keeps the menu open across clicks inside the header region", async () => {
+    const picked: string[] = [];
+    const closed = vi.fn();
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    api().open({
+      x: 100,
+      y: 80,
+      title: "Menu",
+      items: [{ key: "copy", label: "Copy" }],
+      header: () => (
+        <HkTagDotRow
+          tags={[
+            { key: "red", color: "#e5484d", label: "Red" },
+            { key: "yellow", color: "#ffd400", label: "Yellow" },
+          ]}
+          label="tags"
+          onToggle={() => {}}
+        />
+      ),
+      onSelect: (key) => picked.push(key),
+      onClose: closed,
+    });
+    await settle();
+    const dot = document.querySelector(".hk-tag-dot") as HTMLButtonElement;
+    dot.click();
+    await settle();
+    // An inside-region click toggles, it never dismisses…
+    expect(popouts()).toHaveLength(1);
+    expect(picked).toEqual([]);
+    expect(closed).not.toHaveBeenCalled();
+    // …and an item pick after it still resolves normally.
+    menuRows()[0].click();
+    await settle();
+    expect(picked).toEqual(["copy"]);
+    await until(() => popouts().length === 0);
+  });
+
+  it("keeps the header region live while the menu is open", async () => {
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    const count = ref(0);
+    api().open({
+      x: 100,
+      y: 80,
+      items: [{ key: "copy", label: "Copy" }],
+      header: () => <div class="content-hdr">n{count.value}</div>,
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    expect(headSlot()?.textContent).toContain("n0");
+    count.value = 3;
+    await settle();
+    expect(headSlot()?.textContent).toContain("n3");
+  });
+
+  it("renders no region wrappers when the request carries none", async () => {
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    api().open({
+      x: 100,
+      y: 80,
+      items: [{ key: "copy", label: "Copy" }],
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    expect(popouts()).toHaveLength(1);
+    expect(headSlot()).toBeNull();
+    expect(footSlot()).toBeNull();
+    expect(menuRows()).toHaveLength(1);
+    api().close();
+    await until(() => popouts().length === 0);
+  });
+
+  it("swaps the regions when a second open replaces the menu", async () => {
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    api().open({
+      x: 100,
+      y: 80,
+      items: [{ key: "a", label: "A" }],
+      header: () => <div class="content-a">A</div>,
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    expect(headSlot()?.querySelector(".content-a")).toBeTruthy();
+    api().open({
+      x: 120,
+      y: 90,
+      items: [{ key: "b", label: "B" }],
+      header: () => <div class="content-b">B</div>,
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    // The epoch remount drops the stale region and its rows wholesale.
+    expect(headSlot()?.querySelector(".content-a")).toBeNull();
+    expect(headSlot()?.querySelector(".content-b")).toBeTruthy();
+    expect(menuRows().map((r) => r.textContent)).toEqual(["B"]);
+    api().close();
+    await until(() => popouts().length === 0);
+  });
+});

package/src/components/HkContextMenuProvider.tsx

@@ -110,6 +110,22 @@ export default defineComponent({
       quadrantPlacement(request.value?.x ?? 0, request.value?.y ?? 0),
     );
 
+    /** The request's custom regions become HkMenu's level-0 header/
+     *  footer slots (object children = slots in Vue JSX). Only the
+     *  keys that exist are handed over, so a request without custom
+     *  content renders exactly as before. The slot closures re-read
+     *  the CURRENT request through the shallowRef, and each open
+     *  bumps menuEpoch — a fresh HkMenu mounts with fresh slots, and
+     *  the region's own reactive reads (host state) keep it live
+     *  while the menu stays open. */
+    const menuSlots = () => {
+      const req = request.value;
+      return {
+        ...(req?.header ? { header: () => req.header!() } : {}),
+        ...(req?.footer ? { footer: () => req.footer!() } : {}),
+      };
+    };
+
     return () => (
       <>
         {slots.default?.()}
@@ -136,7 +152,9 @@ export default defineComponent({
           anchorRef={anchor.value}
           placement={placement.value}
           title={request.value?.title ?? ""}
-        />
+        >
+          {menuSlots()}
+        </HkMenu>
       </>
     );
   },

package/src/components/HkTagDotRow.scss

@@ -0,0 +1,64 @@
+/* ── HkTagDotRow — the Finder-style tag strip ────────────────────
+ * A horizontal row of toggleable colored dots with captions beneath
+ * (the macOS file-tag picker pattern): one dot per tag, a click
+ * toggles, several tags flip in one visit. Metrics and states come
+ * from the unified menu-item spec (see ./_menu-item.scss), so the
+ * strip keeps menu rhythm inside HkMenu header/footer slots,
+ * HkMenuPanel or any popover, and grows with the sheet tokens inside
+ * mobile sheets (registered in the spec's sheet-context list). This
+ * sheet owns only what is the strip's own: the even column layout,
+ * the dot itself, and the caption rhythm. */
+
+@use "./menu-item" as mi;
+
+.hk-tag-dot-row {
+  @include mi.item-tokens;
+  display: flex;
+  flex-direction: row;
+  align-items: stretch;
+  gap: var(--hk-menu-item-gap);
+  /* A band of its own inside the slot wrapper: rows above and below
+   * keep their rhythm, the strip reads as one control. */
+  padding-block: var(--hk-menu-item-pad-y);
+}
+
+.hk-tag-dot {
+  @include mi.item;
+  flex: 1 1 0;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  gap: calc(var(--hk-menu-item-gap) / 2);
+  min-width: 0;
+  text-align: center;
+}
+
+.hk-tag-dot__dot {
+  flex: none;
+  width: calc(var(--hk-menu-item-icon-box) * 0.65);
+  height: calc(var(--hk-menu-item-icon-box) * 0.65);
+  border-radius: var(--radius-full, 9999px);
+  background: var(--hk-tag-color, rgb(var(--color-primary)));
+  transition: box-shadow 0.12s ease, opacity 0.12s ease;
+}
+
+/* Unapplied tags recede; the applied dot carries a soft ring of its
+ * own ink so the COLOR — not just the button wash — reads as on. */
+.hk-tag-dot:not([data-active]) .hk-tag-dot__dot {
+  opacity: 0.4;
+}
+
+.hk-tag-dot[data-active] .hk-tag-dot__dot {
+  box-shadow: 0 0 0 2px
+    color-mix(in srgb, var(--hk-tag-color, rgb(var(--color-primary))) 30%, transparent);
+}
+
+/* The caption is secondary to the dot: the row grammar above sets
+ * size/weight; captions only keep their own line rhythm and may wrap
+ * (three short columns, never a wide table). */
+.hk-tag-dot__label {
+  min-width: 0;
+  max-width: 100%;
+  overflow-wrap: anywhere;
+  line-height: var(--hk-menu-item-lh);
+}

package/src/components/HkTagDotRow.test.tsx

@@ -0,0 +1,95 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent } from "vue";
+
+import HkTagDotRow, { type HkTagDot } from "./HkTagDotRow";
+
+/** Mount into a detached div appended to the body — the family's
+ *  mount pattern (assertions go through document.querySelectorAll). */
+function mountRow(tags: HkTagDot[], onToggle: (key: string) => void, label?: string): void {
+  const el = document.createElement("div");
+  document.body.appendChild(el);
+  createApp(
+    defineComponent({
+      name: "TagDotRowHost",
+      setup() {
+        return () => <HkTagDotRow tags={tags} label={label} onToggle={onToggle} />;
+      },
+    }),
+  ).mount(el);
+}
+
+const dots = () =>
+  Array.from(document.querySelectorAll(".hk-tag-dot")) as HTMLButtonElement[];
+
+const dotByAria = (name: string) =>
+  dots().find((b) => b.getAttribute("aria-label") === name);
+
+afterEach(() => {
+  dots().forEach((b) => b.remove());
+  document.querySelectorAll(".hk-tag-dot-row").forEach((el) => el.remove());
+});
+
+describe("HkTagDotRow", () => {
+  it("renders one toggle per tag: dot ink, caption, pressed state", () => {
+    mountRow(
+      [
+        { key: "red", color: "#e5484d", label: "Red" },
+        { key: "yellow", color: "#ffd400", active: true },
+        { key: "purple", color: "#a855f7" },
+      ],
+      () => {},
+      "Tags",
+    );
+    const row = document.querySelector(".hk-tag-dot-row")!;
+    expect(row.getAttribute("role")).toBe("group");
+    expect(row.getAttribute("aria-label")).toBe("Tags");
+
+    expect(dots()).toHaveLength(3);
+    // Dot ink rides the per-tag custom property on the dot itself…
+    const red = dotByAria("Red")!;
+    const redDot = red.querySelector(".hk-tag-dot__dot") as HTMLElement;
+    expect(redDot.style.getPropertyValue("--hk-tag-color")).toBe("#e5484d");
+    expect(red.querySelector(".hk-tag-dot__label")?.textContent).toBe("Red");
+    expect(red.getAttribute("aria-pressed")).toBe("false");
+    expect(red.hasAttribute("data-active")).toBe(false);
+
+    // …the applied tag carries the selected face and pressed state.
+    const yellow = dotByAria("yellow")!;
+    expect(yellow.getAttribute("aria-pressed")).toBe("true");
+    expect(yellow.hasAttribute("data-active")).toBe(true);
+    // A labelless tag falls back to its key for the accessible name
+    // and renders no caption span.
+    expect(yellow.querySelector(".hk-tag-dot__label")).toBeNull();
+  });
+
+  it("emits toggle with the tag key on click", () => {
+    const toggled: string[] = [];
+    mountRow(
+      [
+        { key: "red", color: "#e5484d", label: "Red" },
+        { key: "purple", color: "#a855f7", label: "Purple" },
+      ],
+      (key) => toggled.push(key),
+    );
+    dotByAria("Red")!.click();
+    dotByAria("Purple")!.click();
+    expect(toggled).toEqual(["red", "purple"]);
+  });
+
+  it("keeps a disabled tag inert", () => {
+    const toggled = vi.fn();
+    mountRow(
+      [
+        { key: "red", color: "#e5484d", label: "Red", disabled: true },
+        { key: "purple", color: "#a855f7", label: "Purple" },
+      ],
+      toggled,
+    );
+    const red = dotByAria("Red")!;
+    expect(red.disabled).toBe(true);
+    red.click(); // happy-dom honors disabled on click dispatch
+    expect(toggled).not.toHaveBeenCalled();
+    dotByAria("Purple")!.click();
+    expect(toggled).toHaveBeenCalledWith("purple");
+  });
+});

package/src/components/HkTagDotRow.tsx

@@ -0,0 +1,65 @@
+import { defineComponent, type PropType } from "vue";
+
+import "./HkTagDotRow.scss";
+
+/** One toggleable tag of a HkTagDotRow. */
+export interface HkTagDot {
+  /** Stable identity emitted by `toggle`. */
+  key: string;
+  /** Dot color — any CSS color (hex, rgb(), a var() reference…). */
+  color: string;
+  /** Caption under the dot; the host i18n's it. */
+  label?: string;
+  /** Whether the tag is currently applied (the row's selected face). */
+  active?: boolean;
+  /** Inert: rendered dimmed, clicks never toggle it. */
+  disabled?: boolean;
+}
+
+/**
+ * HkTagDotRow — a horizontal strip of toggleable colored dots, the
+ * macOS Finder tag-editor pattern: one dot per tag, the caption
+ * beneath it, one click toggles. Tags are domain-free {key, color,
+ * label} triples — the host owns the vocabulary (and its i18n), the
+ * row owns only the geometry and states.
+ *
+ * Speaks the unified menu-item spec (see ./_menu-item.scss), so it
+ * drops straight into menu surfaces — HkMenu's header/footer slots,
+ * HkMenuPanel, a popover — and keeps menu rhythm there, growing with
+ * the sheet tokens inside mobile sheets; it works anywhere else a
+ * compact tag picker belongs (settings rows, card footers). Clicking
+ * a dot never closes a surrounding menu: it emits `toggle` only, and
+ * the host decides what to do (menus stay open across toggles so
+ * several tags can be flipped in one visit).
+ */
+export default defineComponent({
+  name: "HkTagDotRow",
+  props: {
+    tags: { type: Array as PropType<HkTagDot[]>, required: true },
+    /** Accessible name for the whole group (aria-label). */
+    label: { type: String, default: undefined },
+  },
+  emits: ["toggle"],
+  setup(props, { emit }) {
+    return () => (
+      <div class="hk-tag-dot-row" role="group" aria-label={props.label}>
+        {props.tags.map((tag) => (
+          <button
+            key={tag.key}
+            type="button"
+            class="hk-tag-dot"
+            data-active={tag.active || undefined}
+            disabled={tag.disabled}
+            aria-pressed={tag.active ? "true" : "false"}
+            aria-label={tag.label ?? tag.key}
+            title={tag.label}
+            onClick={() => emit("toggle", tag.key)}
+          >
+            <span class="hk-tag-dot__dot" style={{ "--hk-tag-color": tag.color }} />
+            {tag.label ? <span class="hk-tag-dot__label">{tag.label}</span> : null}
+          </button>
+        ))}
+      </div>
+    );
+  },
+});

package/src/components/HkTitleBar.test.tsx

@@ -109,6 +109,74 @@ describe("HkTitleBar", () => {
   });
 });
 
+describe("HkTitleBar window-chrome claim", () => {
+  // The bar IS the app's title bar, so mounting it must stand hikari's boot bar
+  // (boot-chrome.js) down — otherwise two caption bars overlap for the rest of
+  // the session. Tests use a raw window listener: that is the whole contract.
+  function collect(): { claims: Array<{ by?: string }>; stop: () => void } {
+    const claims: Array<{ by?: string }> = [];
+    const listener = (event: Event) => {
+      claims.push((event as CustomEvent<{ by?: string }>).detail ?? {});
+    };
+    window.addEventListener("hk:chrome-claim", listener);
+    return {
+      claims,
+      stop: () => window.removeEventListener("hk:chrome-claim", listener),
+    };
+  }
+
+  function cleanup(): void {
+    document.documentElement.removeAttribute("data-hk-chrome");
+  }
+
+  it("claims the window on mount and marks the app as the chrome owner", () => {
+    const { claims, stop } = collect();
+    try {
+      mount(h(HkTitleBar, { title: "App" }));
+
+      expect(claims).toHaveLength(1);
+      expect(claims[0]?.by).toBe("HkTitleBar");
+      expect(document.documentElement.getAttribute("data-hk-chrome")).toBe("app");
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+
+  it("never claims twice for one mount (a re-render is not a new takeover)", async () => {
+    const { claims, stop } = collect();
+    try {
+      const maximized = ref(false);
+      mount(h(() => h(HkTitleBar, { title: "App", maximized: maximized.value })));
+      expect(claims).toHaveLength(1);
+
+      maximized.value = true;
+      await nextTick();
+      maximized.value = false;
+      await nextTick();
+
+      expect(claims).toHaveLength(1);
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+
+  it("leaves the existing props/emits contract untouched", () => {
+    const emitted: string[] = [];
+    const host = mount(
+      h(HkTitleBar, {
+        title: "App",
+        onMinimize: () => emitted.push("minimize"),
+        onClose: () => emitted.push("close"),
+      }),
+    );
+    host.querySelector<HTMLButtonElement>('[title="Minimize"]')!.click();
+    host.querySelector<HTMLButtonElement>('[title="Close"]')!.click();
+    expect(emitted).toEqual(["minimize", "close"]);
+  });
+});
+
 describe("HkTitleBar stylesheet contract", () => {
   const css = compile(resolve(componentDir, "HkTitleBar.scss"), {
     style: "expanded",

package/src/components/HkTitleBar.tsx

@@ -1,5 +1,6 @@
 import { defineComponent, onBeforeUnmount, onMounted, ref } from "vue";
 import { useI18n } from "../i18n/context";
+import { claimWindowChrome } from "../runtime/windowChrome";
 
 import "./HkTitleBar.scss";
 
@@ -60,6 +61,16 @@ export default defineComponent({
   },
   setup(props, { emit, slots }) {
     const { t } = useI18n();
+    // The bar IS the app's window chrome, so mounting it means the boot chrome
+    // (boot-chrome.js, drawn before the bundle exists) must hand the window
+    // over: dispatch `hk:chrome-claim` once per mount, never revoked. See
+    // runtime/windowChrome for the contract; hydration/SSR never reaches here.
+    let claimed = false;
+    onMounted(() => {
+      if (claimed) return;
+      claimed = true;
+      claimWindowChrome("HkTitleBar");
+    });
     return () => (
       <div
         class="hk-titlebar"