@celestia-island/hikari 0.55.123 → 0.55.125

package/package.json

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

package/src/components/HkPopover.closed.test.tsx

@@ -0,0 +1,86 @@
+/**
+ * HkPopover `closed` contract: the settled-leave edge hosts reclaim
+ * focus from (the template field's Escape path). Pins:
+ *
+ *   - a close emits `closed` exactly once, AFTER the panel has left
+ *     the DOM (that ordering is the whole point — focus is only
+ *     orphaned once the panel is gone);
+ *   - opening emits nothing;
+ *   - unmounting while open does NOT emit (`closed` means "closed",
+ *     not "disposed" — the UNMOUNT phase skips the after-leave hook).
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick, ref } from "vue";
+
+import HkPopover from "./HkPopover";
+
+const apps: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  for (const { app, container } of apps.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  document.body
+    .querySelectorAll(".hk-popover-panel, .hk-popover-scrim")
+    .forEach((el) => el.remove());
+});
+
+function mountPopover() {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const open = ref(false);
+  const closedCalls: boolean[] = [];
+  const app = createApp({
+    render: () =>
+      h(
+        HkPopover as never,
+        {
+          modelValue: open.value,
+          title: "probe",
+          "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+          onClosed: () => closedCalls.push(!!document.body.querySelector(".hk-popover-panel")),
+        },
+        () => h("div", { class: "probe-body" }, "content"),
+      ),
+  });
+  app.mount(container);
+  apps.push({ app, container });
+  return { open, closedCalls };
+}
+
+describe("HkPopover closed event", () => {
+  it("fires once on a settled close, with the panel already gone", async () => {
+    const { open, closedCalls } = mountPopover();
+    await nextTick();
+    expect(closedCalls).toHaveLength(0); // opening emits nothing
+
+    open.value = true;
+    await nextTick();
+    expect(document.body.querySelector(".hk-popover-panel")).not.toBeNull();
+
+    open.value = false;
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 30));
+    await nextTick();
+
+    expect(closedCalls).toHaveLength(1);
+    // The edge that matters: by the time `closed` ran, the panel had
+    // left the DOM (focus orphaned), not merely started leaving.
+    expect(closedCalls[0]).toBe(false);
+  });
+
+  it("does not emit on unmount-while-open", async () => {
+    const { open, closedCalls } = mountPopover();
+    await nextTick();
+    open.value = true;
+    await nextTick();
+    expect(document.body.querySelector(".hk-popover-panel")).not.toBeNull();
+
+    apps.pop()!.app.unmount();
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 30));
+    await nextTick();
+    expect(closedCalls).toHaveLength(0);
+  });
+});

package/src/components/HkPopover.tsx

@@ -76,6 +76,18 @@ export default defineComponent({
   },
   emits: {
     "update:modelValue": (_v: boolean) => true,
+    /** Fired once the close has fully settled (the leave transition
+     * completed and the panel left the DOM) — the moment focus that
+     * lived inside the closing panel falls back to <body>. Hosts that
+     * reclaim focus after an Escape-style close want THIS edge, not a
+     * timer: a fixed delay either races a long leave animation or
+     * waits past a short one.
+     *
+     *  The emit rides a nextTick after the machine's closed phase, so a
+     *  component UNMOUNTED in that same window drops it (Vue skips
+     *  emits on unmounted instances) — a host that itself is going away
+     *  has nothing to reclaim anyway. */
+    closed: () => true,
   },
   setup(props, { emit, slots }) {
     const attrs = useAttrs();
@@ -450,6 +462,14 @@ export default defineComponent({
 
     function onPopupAfterLeave() {
       fullCleanup();
+      // Emit AFTER the patch that removes the panel: the machine's
+      // closed phase triggers the re-render, so emitting inline would
+      // run hosts' handlers while the panel is still in the DOM (and
+      // focus still sits inside it) — the literal meaning of "closed"
+      // is only true once the vnode has been patched away.
+      nextTick(() => {
+        emit("closed");
+      });
     }
 
     // Overlay scrollbar (shared chrome) — only the mobile sheet scrolls

package/src/components/HkTemplateField.scss

@@ -0,0 +1,261 @@
+// HkTemplateField / HkTemplateText — the fill-template surfaces.
+// Self-sufficient styling (house rule): the field box, label, hint and
+// error rows live here rather than borrowing HkInput's sheet, and the
+// chip is THE shared token visual — the editor's chips and the
+// read-only renderer's chips are the same class, so a stored template
+// reads identically wherever it appears.
+
+.hk-template-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4, 4px);
+  width: 100%;
+
+  &[data-disabled] {
+    opacity: 0.55;
+    pointer-events: none;
+  }
+}
+
+.hk-template-field-label {
+  font-size: var(--text-xs, 0.75rem);
+  font-weight: 500;
+  color: var(--hi-color-text-primary);
+}
+
+.hk-template-field-hint,
+.hk-template-field-error {
+  margin: 0;
+  font-size: var(--text-2xs, 0.625rem);
+  line-height: 1.4;
+}
+
+.hk-template-field-hint {
+  color: var(--hi-color-muted);
+}
+
+.hk-template-field-error {
+  color: var(--hi-color-danger);
+}
+
+.hk-template-field-box {
+  box-sizing: border-box;
+  display: block;
+  width: 100%;
+  padding: var(--space-6, 0.375rem) var(--space-10, 0.625rem);
+  background: var(--hi-color-surface);
+  border: 1px solid var(--hi-color-border);
+  border-radius: 6px;
+  transition:
+    border-color var(--hi-transition-base, 200ms cubic-bezier(0.4, 0, 0.2, 1)),
+    box-shadow var(--hi-transition-base, 200ms cubic-bezier(0.4, 0, 0.2, 1));
+
+  &:hover {
+    border-color: var(--hi-color-primary);
+  }
+
+  &:focus-within {
+    border-color: var(--hi-color-primary);
+    box-shadow: 0 0 0 3px color-mix(in srgb, var(--hi-color-primary) 18%, transparent);
+  }
+}
+
+.hk-template-field-box-error {
+  border-color: var(--hi-color-danger);
+
+  &:focus-within {
+    border-color: var(--hi-color-danger);
+    box-shadow: 0 0 0 3px color-mix(in srgb, var(--hi-color-danger) 15%, transparent);
+  }
+}
+
+.hk-template-field-edit {
+  // Slightly tighter than a plain input: chips carry their own padding,
+  // and the field must not read taller than the HkInput beside it.
+  min-height: calc(1.5rem + var(--space-4, 4px));
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 2px 3px;
+  font-size: var(--text-base, 0.875rem);
+  line-height: 1.5;
+  color: var(--hi-color-text-primary);
+  outline: none;
+  word-break: break-all;
+  cursor: text;
+
+  &:empty::before {
+    content: attr(data-ph);
+    color: var(--hi-color-muted);
+    opacity: 0.6;
+  }
+}
+
+// ── The chip ─────────────────────────────────────────────────────────
+// Monospace (it IS code — the exact text the host fills), primary
+// tinted, unbreakable. Editable context adds the click affordance and
+// the unknown marker both surfaces share.
+
+.hk-tpl-chip {
+  display: inline-flex;
+  align-items: center;
+  padding: 0 var(--space-6, 6px);
+  border-radius: var(--radius-sm, 4px);
+  border: 1px solid color-mix(in srgb, var(--hi-color-primary) 32%, transparent);
+  background: color-mix(in srgb, var(--hi-color-primary) 12%, transparent);
+  color: color-mix(in srgb, var(--hi-color-primary) 70%, rgb(0 0 0));
+  font-family: var(--font-mono, monospace);
+  font-size: 0.8em;
+  line-height: 1.5;
+  white-space: nowrap;
+  user-select: none;
+
+  [data-theme="dark"] & {
+    color: color-mix(in srgb, var(--hi-color-primary) 60%, rgb(255 255 255));
+  }
+
+  &[data-unknown] {
+    border-color: var(--hi-color-border);
+    background: color-mix(in srgb, var(--hi-color-warning) 12%, transparent);
+    color: var(--hi-color-muted);
+    font-style: italic;
+  }
+}
+
+.hk-template-field-edit .hk-tpl-chip {
+  cursor: pointer;
+
+  &:hover {
+    border-color: var(--hi-color-primary);
+    background: color-mix(in srgb, var(--hi-color-primary) 20%, transparent);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--hi-color-primary);
+    outline-offset: 1px;
+  }
+}
+
+.hk-template-text {
+  display: inline;
+  max-width: 100%;
+
+  &[data-multiline] {
+    display: block;
+    overflow-wrap: anywhere;
+  }
+}
+
+.hk-template-text-run {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+// ── Vocabulary rows (panel + chip editor share them) ────────────────
+
+.hk-tpl-rows,
+.hk-tpl-editor-rows {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: var(--space-4, 4px);
+}
+
+.hk-tpl-group {
+  padding: var(--space-6, 6px) var(--space-8, 8px) var(--space-2, 2px);
+  font-size: var(--text-2xs, 0.625rem);
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  // No text-transform: labels arrive from the host (usually i18n
+  // strings) and the translator owns the casing.
+  color: var(--hi-color-muted);
+  user-select: none;
+}
+
+.hk-tpl-row {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 1px;
+  padding: var(--space-4, 4px) var(--space-8, 8px);
+  border: none;
+  border-radius: var(--radius-sm, 4px);
+  background: transparent;
+  color: var(--hi-color-text-primary);
+  text-align: start;
+  cursor: pointer;
+
+  &:hover,
+  &[data-active] {
+    background: color-mix(in srgb, var(--hi-color-primary) 10%, transparent);
+  }
+}
+
+.hk-tpl-row-name {
+  font-family: var(--font-mono, monospace);
+  font-size: var(--text-xs, 0.75rem);
+}
+
+.hk-tpl-row-desc {
+  font-size: var(--text-2xs, 0.625rem);
+  color: var(--hi-color-muted);
+  line-height: 1.4;
+}
+
+.hk-tpl-rows-empty {
+  padding: var(--space-8, 8px) var(--space-12, 12px);
+  margin: 0;
+  font-size: var(--text-xs, 0.75rem);
+  color: var(--hi-color-muted);
+}
+
+// ── Chip editor form ────────────────────────────────────────────────
+
+.hk-tpl-editor {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 8px);
+  min-width: 16rem;
+  max-width: min(22rem, 90vw);
+  padding: var(--space-8, 8px);
+}
+
+.hk-tpl-editor-current {
+  display: flex;
+  align-items: baseline;
+  gap: var(--space-8, 8px);
+  flex-wrap: wrap;
+}
+
+.hk-tpl-editor-desc {
+  font-size: var(--text-2xs, 0.625rem);
+  color: var(--hi-color-muted);
+  line-height: 1.4;
+  flex: 1 1 10rem;
+}
+
+// ONE scrollbar per window (family contract): the mobile sheet's panel
+// already scrolls the whole form through its own overlay scrollbar, so
+// the rows viewport exists ONLY in the desktop popover (which sizes to
+// content and otherwise has no scroll region at all). The viewport
+// keeps native overflow MECHANICS but hides the native bar — the shared
+// overlay scrollbar (attachOverlayScrollbars) draws the house chrome
+// onto the dedicated host wrapper, which wraps exactly this viewport.
+.hk-tpl-editor-scroll {
+  position: relative;
+}
+
+.hk-popover-panel:not(.hk-is-sheet) .hk-tpl-editor-rows {
+  max-height: min(16rem, 40dvh);
+  overflow-y: auto;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+.hk-tpl-editor-footer {
+  display: flex;
+  justify-content: flex-end;
+}

package/src/components/HkTemplateField.styles.test.ts

@@ -0,0 +1,120 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Compiled-stylesheet guard for the template surfaces. Vitest stubs CSS,
+ * so the runtime suite can never catch a lost rule — this test compiles
+ * the sheet directly and pins the pieces the runtime tests cannot see:
+ *
+ *   1. the editor rows' native scrollbar is HIDDEN inside the DESKTOP
+ *      branch only (`scrollbar-width: none` + `::-webkit-scrollbar {
+ *      display: none }` under `.hk-popover-panel:not(.hk-is-sheet)`) —
+ *      the family draws its shared overlay chrome instead, and the
+ *      mobile sheet must keep the panel as the ONE scroll region;
+ *   2. the scroll host is a positioning context (`position: relative`)
+ *      for the overlay rails;
+ *   3. a curated class list checks TSX→CSS (no unstyled element) and a
+ *      reverse scan flags any `hk-tpl-*`/`hk-template-*` selector in the
+ *      sheet that no source file renders (no dead rule).
+ */
+
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+function classTokensFrom(source: string): Set<string> {
+  const found = new Set<string>();
+  for (const match of source.matchAll(/\b(?:hk|s)-[\w-]+/g)) {
+    found.add(match[0]);
+  }
+  return found;
+}
+
+describe("HkTemplateField stylesheet contract", () => {
+  const tsx = readFileSync(resolve(componentDir, "HkTemplateField.tsx"), "utf8");
+  const rendererTsx = readFileSync(resolve(componentDir, "HkTemplateText.tsx"), "utf8");
+  const grammars = readFileSync(resolve(componentDir, "templateGrammar.ts"), "utf8");
+  const css = compile(resolve(componentDir, "HkTemplateField.scss"), {
+    style: "expanded",
+  }).css;
+
+  it("hides the native scrollbar of the editor rows viewport (desktop branch only)", () => {
+    // Both spellings: standard property + the WebKit pseudo-element,
+    // and both under the `:not(.hk-is-sheet)` scoping — a bare rule
+    // would also strip the sheet's native bar while no overlay is
+    // attached there (sheet attaches none; the panel owns its scroll).
+    expect(css).toMatch(
+      /\.hk-popover-panel:not\(\.hk-is-sheet\)[^{]*\.hk-tpl-editor-rows[^{]*\{[^}]*scrollbar-width:\s*none/s,
+    );
+    // The WebKit spelling gets the SAME desktop scoping (R2 M8c: the
+    // unscoped form of this rule survived every assertion).
+    expect(css).toMatch(
+      /\.hk-popover-panel:not\(\.hk-is-sheet\)[^{]*hk-tpl-editor-rows[^{]*::-webkit-scrollbar[^{]*\{[^}]*display:\s*none/s,
+    );
+    // EVERY rule that hides a native bar must carry the desktop scoping
+    // — regardless of how its selector is spelled. Two spellings hide a
+    // bar: `scrollbar-width: none` (a declaration, body) and a
+    // `::-webkit-scrollbar` marker (a SELECTOR, not a declaration — the
+    // R3 P3-1 correction). At-rule preludes (`@media …`) are skipped:
+    // the naive block splitter attributes an at-rule's inner rules to
+    // its prelude, which would false-positive on any future media query.
+    const rules = [...css.matchAll(/([^{}]+)\{([^}]*)\}/gs)];
+    let barHiding = 0;
+    for (const [, selector, body] of rules) {
+      const sel = selector ?? "";
+      if (sel.trimStart().startsWith("@")) continue;
+      const hidesBar = (body ?? "").includes("scrollbar-width: none") || sel.includes("::-webkit-scrollbar");
+      if (!hidesBar) continue;
+      barHiding += 1;
+      expect(sel, `bar-hiding rule must be sheet-scoped: ${sel}`).toContain(
+        ":not(.hk-is-sheet)",
+      );
+    }
+    // Extraction sanity (verification-loop rule: a 0-hit scan is a
+    // pattern bug until proven otherwise) — the sheet does hide the bar
+    // somewhere, so the loop above must have inspected at least one rule.
+    expect(barHiding).toBeGreaterThan(0);
+  });
+
+  it("has no dead template selector in the sheet", () => {
+    // Reverse direction: every `hk-tpl-*` / `hk-template-*` selector in
+    // the compiled CSS must appear in one of the two source files.
+    const sources = tsx + rendererTsx + grammars;
+    const selectors = new Set<string>();
+    for (const m of css.matchAll(/\.((?:hk-tpl|hk-template)[\w-]*)/g)) {
+      selectors.add(m[1]!);
+    }
+    expect(selectors.size).toBeGreaterThan(5); // extraction sanity (R1: never trust a 0-hit)
+    for (const sel of selectors) {
+      expect(sources.includes(sel), `no source renders ${sel}`).toBe(true);
+    }
+  });
+
+  it("keeps group headings free of text-transform (the host owns casing)", () => {
+    // R2 M13: re-adding `text-transform: uppercase` used to stay green.
+    expect(css).not.toMatch(/\.hk-tpl-group[^{]*\{[^}]*text-transform/s);
+  });
+
+  it("gives the scroll host a positioning context for the overlay rails", () => {
+    expect(css).toMatch(/\.hk-tpl-editor-scroll\s*\{[^}]*position:\s*relative/s);
+  });
+
+  it("styles every editor class the TSX renders", () => {
+    const emitted = classTokensFrom(tsx);
+    for (const cls of ["hk-template-field", "hk-template-field-edit", "hk-template-field-box",
+      "hk-template-field-label", "hk-tpl-chip", "hk-tpl-row", "hk-tpl-rows", "hk-tpl-group",
+      "hk-tpl-editor", "hk-tpl-editor-rows", "hk-tpl-editor-scroll"]) {
+      expect(emitted.has(cls), `TSX renders ${cls}`).toBe(true);
+      expect(css.includes(`.${cls}`), `sheet styles ${cls}`).toBe(true);
+    }
+  });
+
+  it("keeps the read-only renderer's classes styled by the shared sheet", () => {
+    expect(rendererTsx).toContain("hk-template-text");
+    expect(css.includes(".hk-template-text")).toBe(true);
+    // The read-only chips ride the SAME chip class as the editor's.
+    expect(rendererTsx).toContain("hk-tpl-chip");
+  });
+});