@celestia-island/hikari 0.55.124 → 0.55.126

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.124",
+  "version": "0.55.126",
   "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

@@ -161,6 +161,28 @@
   padding: var(--space-4, 4px);
 }
 
+// The group is a role="group" WRAPPER carrying the accessible name in
+// aria-label; the visible heading text is the inner label band (hidden
+// from the a11y tree — the wrapper already announced the name).
+.hk-tpl-group {
+  // Flex like the sibling rows list, so the parent's row gap keeps
+  // applying INSIDE the wrapper (a bare block would drop it to 0).
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.hk-tpl-group-label {
+  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;
@@ -225,11 +247,23 @@
 
 // ONE scrollbar per window (family contract): the mobile sheet's panel
 // already scrolls the whole form through its own overlay scrollbar, so
-// the rows cap exists ONLY in the desktop popover (which sizes to
-// content and otherwise has no scroll region at all).
+// 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 {

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

@@ -0,0 +1,128 @@
+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 the heading band on the label class, not the group wrapper", () => {
+    // The wrapper is a bare layout box; carrying the band's chrome
+    // (padding/font-weight) there would pad every row run.
+    expect(css).toMatch(/\.hk-tpl-group-label\s*\{[^}]*font-weight:\s*600/s);
+    expect(css).not.toMatch(/\.hk-tpl-group\s*\{[^}]*font-weight/s);
+    expect(css).not.toMatch(/\.hk-tpl-group\s*\{[^}]*padding/s);
+  });
+
+  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");
+  });
+});

package/src/components/HkTemplateField.test.tsx

@@ -34,6 +34,26 @@ interface MountOpts {
   submitOnEnter?: () => void;
 }
 
+function mountWithTokens(
+  tokens: Array<{ name: string; group?: string; description?: string }>,
+  opts: MountOpts & { groupLabel?: (g: string) => string } = {},
+) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(HkTemplateField, {
+        modelValue: opts.modelValue ?? "",
+        tokens,
+        groupLabel: opts.groupLabel,
+        "onUpdate:modelValue": (v: string) => opts.onUpdate?.(v),
+      }),
+  });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
 function mount(opts: MountOpts = {}) {
   const container = document.createElement("div");
   document.body.appendChild(container);
@@ -386,3 +406,308 @@ describe("HkTemplateField vocabulary guardrails (R2 gap killers)", () => {
     expect(seen.at(-1)).toBe("a {{ md5_email }} b");
   });
 });
+
+describe("HkTemplateField grouped vocabulary", () => {
+  const GROUPED = [
+    { name: "id", group: "identity" },
+    { name: "username", group: "identity" },
+    { name: "md5_email", group: "email" },
+    { name: "sha256_email", group: "email" },
+  ];
+
+  it("renders one labeled group wrapper per run in the panel", async () => {
+    const el = mountWithTokens(GROUPED);
+    await nextTick();
+    await openTrigger(el, "{{ ");
+    const groups = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-group"));
+    // The accessible name rides on the wrapper (announced on entry);
+    // the visible text lives in the inner label band.
+    expect(groups.map((g) => g.getAttribute("aria-label"))).toEqual(["identity", "email"]);
+    expect(groups.every((g) => g.getAttribute("role") === "group")).toBe(true);
+    const labels = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-group-label"));
+    expect(labels.map((l) => l.textContent)).toEqual(["identity", "email"]);
+    // The visible band is hidden from the a11y tree — the wrapper's
+    // aria-label already announced the name (no double reading).
+    expect(labels.every((l) => l.getAttribute("aria-hidden") === "true")).toBe(true);
+    // Rows ride INSIDE their group wrapper.
+    expect(groups[0]!.querySelectorAll(".hk-tpl-row")).toHaveLength(2);
+    expect(groups[1]!.querySelectorAll(".hk-tpl-row")).toHaveLength(2);
+  });
+
+  it("maps group keys through groupLabel", async () => {
+    const el = mountWithTokens(GROUPED, { groupLabel: (g) => g.toUpperCase() });
+    await nextTick();
+    await openTrigger(el, "{{ ");
+    const groups = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-group"));
+    expect(groups.map((g) => g.getAttribute("aria-label"))).toEqual(["IDENTITY", "EMAIL"]);
+    expect(groups.map((g) => g.querySelector(".hk-tpl-group-label")?.textContent)).toEqual([
+      "IDENTITY",
+      "EMAIL",
+    ]);
+  });
+
+  it("filters groups out with their members (no stray heading)", async () => {
+    const el = mountWithTokens(GROUPED);
+    await nextTick();
+    await openTrigger(el, "{{ md5");
+    const groups = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-group"));
+    expect(groups.map((g) => g.getAttribute("aria-label"))).toEqual(["email"]);
+    expect(groups[0]!.querySelectorAll(".hk-tpl-row")).toHaveLength(1);
+  });
+
+  it("ungrouped vocabularies render exactly as before (no headings)", async () => {
+    const el = mountWithTokens([{ name: "username" }, { name: "md5_email" }]);
+    await nextTick();
+    await openTrigger(el, "{{ ");
+    expect(document.body.querySelectorAll(".hk-tpl-group")).toHaveLength(0);
+    expect(document.body.querySelectorAll(".hk-tpl-row").length).toBeGreaterThan(0);
+  });
+
+  it("groups the chip editor rows too", async () => {
+    const el = mountWithTokens(GROUPED, { modelValue: "a {{ username }} b" });
+    await nextTick();
+    editable(el).querySelector<HTMLElement>(".hk-tpl-chip")!.click();
+    await nextTick();
+    const groups = Array.from(
+      document.body.querySelectorAll<HTMLElement>(".hk-tpl-editor .hk-tpl-group"),
+    );
+    expect(groups.map((g) => g.getAttribute("aria-label"))).toEqual(["identity", "email"]);
+  });
+});
+
+describe("HkTemplateField editor scroll chrome", () => {
+  it("wraps the scrolling rows in a dedicated track host", async () => {
+    const el = mount({ modelValue: "a {{ username }} b" });
+    await nextTick();
+    editable(el).querySelector<HTMLElement>(".hk-tpl-chip")!.click();
+    await nextTick();
+    const host = document.body.querySelector<HTMLElement>(".hk-tpl-editor-scroll");
+    expect(host).not.toBeNull();
+    // The host wraps EXACTLY the scrolling viewport (rails must not
+    // span the form's other bands).
+    expect(host!.firstElementChild?.classList.contains("hk-tpl-editor-rows")).toBe(true);
+  });
+});
+
+describe("HkTemplateField editor close reclaim (closed hook)", () => {
+  it("returns focus to the field after the popover settles its leave", async () => {
+    const el = mount({ modelValue: "a {{ username }} b" });
+    await nextTick();
+    const edit = editable(el);
+    edit.querySelector<HTMLElement>(".hk-tpl-chip")!.click();
+    await nextTick();
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel");
+    expect(panel).not.toBeNull();
+    // The reclaim contract only engages when the editor HELD focus —
+    // put the caret in the search field like a real user would.
+    document.body.querySelector<HTMLInputElement>(".hk-tpl-editor-search input")!.focus();
+    await nextTick();
+    // Escape: the popover starts closing; focus sits in the search
+    // input until the leave finishes.
+    panel!.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+    await nextTick();
+    // Past the leave window the machine emits `closed`, whose handler
+    // reclaims focus from the orphaned body state.
+    await new Promise((r) => setTimeout(r, 30));
+    await nextTick();
+    expect(document.activeElement).toBe(edit);
+  });
+});
+
+describe("HkTemplateField editor focus ownership (R1 guards)", () => {
+  it("does NOT steal focus when an outside control takes it (real click path)", async () => {
+    const el = mount({ modelValue: "a {{ username }} b" });
+    await nextTick();
+    const edit = editable(el);
+    edit.querySelector<HTMLElement>(".hk-tpl-chip")!.click();
+    await nextTick();
+    document.body.querySelector<HTMLInputElement>(".hk-tpl-editor-search input")!.focus();
+    await nextTick();
+
+    // A real outside click: the popover's document-level shield closes
+    // it; the user's focus must stay where the click put it.
+    const outside = document.createElement("input");
+    document.body.appendChild(outside);
+    outside.focus();
+    outside.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 30));
+    await nextTick();
+    expect(document.activeElement).toBe(outside);
+    outside.remove();
+  });
+
+  it("still reclaims after a reopen inside the previous close's leave window", async () => {
+    // The focus latch must be re-armed on open: a programmatic reopen
+    // focuses an input that never blurred (no focusin fires), and the
+    // SECOND close would otherwise orphan focus on <body>.
+    const el = mount({ modelValue: "a {{ username }} b" });
+    await nextTick();
+    const edit = editable(el);
+    const chip = edit.querySelector<HTMLElement>(".hk-tpl-chip")!;
+
+    chip.click();
+    await nextTick();
+    document.body.querySelector<HTMLInputElement>(".hk-tpl-editor-search input")!.focus();
+    await nextTick();
+    // Close #1 via the panel's Escape path.
+    document.body
+      .querySelector<HTMLElement>(".hk-popover-panel")!
+      .dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+    await nextTick();
+    // Reopen immediately (inside the leave window — the panel may still
+    // be unmounting).
+    chip.click();
+    await nextTick();
+    // Close #2.
+    document.body
+      .querySelector<HTMLElement>(".hk-popover-panel")!
+      .dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 40));
+    await nextTick();
+    expect(document.activeElement).toBe(edit);
+  });
+
+  it("re-targeting another chip while open keeps exactly one scrollbar", async () => {
+    // Whatever interaction interleaving the user produces (here: a
+    // second chip click while the editor is open — the popover's
+    // outside-click shield closes and the click handler reopens), the
+    // rows host must never end up with more than ONE rail pair. Pins
+    // the leak invariant, not any particular detach call site.
+    const el = mount({ modelValue: "a {{ username }} b {{ md5_email }}" });
+    await nextTick();
+    const edit = editable(el);
+    const chips = [...edit.querySelectorAll<HTMLElement>(".hk-tpl-chip")];
+    expect(chips).toHaveLength(2);
+    chips[0]!.click();
+    await nextTick();
+    chips[1]!.click();
+    await nextTick();
+    const hosts = document.body.querySelectorAll(".hk-tpl-editor-scroll");
+    expect(hosts).toHaveLength(1);
+    expect(hosts[0]!.querySelectorAll(".hk-scrollbar-track")).toHaveLength(1);
+  });
+
+  it("detaches the scrollbar machinery on close (no live observer leak)", async () => {
+    // R2 M4: the close-path detach is load-bearing — without it the
+    // rows handle's ResizeObserver + scroll listeners stay attached to
+    // a viewport that has left the document until the field unmounts
+    // (~a bounded leak). Counting LIVE observers (not bare disconnect
+    // calls — sibling components have their own ROs) is the precise
+    // signal, matching R2's real-browser instrumentation.
+    const RealRO = globalThis.ResizeObserver;
+    const live = new Set<unknown>();
+    class TrackingRO extends RealRO {
+      constructor(cb: ResizeObserverCallback) {
+        super(cb);
+        live.add(this);
+      }
+      override disconnect(): void {
+        live.delete(this);
+        super.disconnect();
+      }
+    }
+    (globalThis as unknown as Record<string, unknown>).ResizeObserver = TrackingRO;
+    try {
+      const el = mount({ modelValue: "a {{ username }} b" });
+      await nextTick();
+      const base = live.size;
+      const edit = editable(el);
+      edit.querySelector<HTMLElement>(".hk-tpl-chip")!.click();
+      await nextTick();
+      expect(live.size, "scrollbar attached an observer").toBeGreaterThan(base);
+
+      document.body
+        .querySelector<HTMLElement>(".hk-popover-panel")!
+        .dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 30));
+      await nextTick();
+      expect(live.size, "close detached every observer it attached").toBe(base);
+    } finally {
+      (globalThis as unknown as Record<string, unknown>).ResizeObserver = RealRO;
+    }
+  });
+
+  it("attaches exactly one overlay scrollbar across repeated opens", async () => {
+    const el = mount({ modelValue: "a {{ username }} b" });
+    await nextTick();
+    const edit = editable(el);
+    const chip = edit.querySelector<HTMLElement>(".hk-tpl-chip")!;
+    for (let round = 0; round < 3; round++) {
+      chip.click();
+      await nextTick();
+      const host = document.body.querySelector(".hk-tpl-editor-scroll")!;
+      expect(host.querySelectorAll(".hk-scrollbar-track")).toHaveLength(1);
+      document.body
+        .querySelector<HTMLElement>(".hk-popover-panel")!
+        .dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 20));
+      await nextTick();
+    }
+  });
+});
+
+describe("HkTemplateField partially-grouped vocabulary", () => {
+  it("renders a heading only where a group starts (documented contract)", async () => {
+    const el = mountWithTokens([
+      { name: "id", group: "identity" },
+      { name: "free_a" }, // ungrouped: continues the identity band
+      { name: "free_b" },
+      { name: "md5_email", group: "email" },
+      { name: "free_c" },
+    ]);
+    await nextTick();
+    await openTrigger(el, "{{ ");
+    const groups = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-group"));
+    // Two wrappers for two group runs; the ungrouped tokens ride inside
+    // the open run (see the groupLabel prop doc) — free_a/b inside
+    // identity, free_c inside email.
+    expect(groups.map((g) => g.getAttribute("aria-label"))).toEqual(["identity", "email"]);
+    expect(groups[0]!.querySelectorAll(".hk-tpl-row")).toHaveLength(3);
+    expect(groups[1]!.querySelectorAll(".hk-tpl-row")).toHaveLength(2);
+    expect(document.body.querySelectorAll(".hk-tpl-row")).toHaveLength(5);
+  });
+});
+
+describe("HkTemplateField vocabulary semantics guards", () => {
+  it("the rows containers carry no listbox role (menu/dialog context)", async () => {
+    const el = mountWithTokens([
+      { name: "id", group: "identity" },
+      { name: "md5_email", group: "email" },
+    ]);
+    await nextTick();
+    await openTrigger(el, "{{ ");
+    const panelRows = document.body.querySelector<HTMLElement>(".hk-tpl-rows")!;
+    expect(panelRows.getAttribute("role")).toBeNull();
+
+    const el2 = mount({ modelValue: "a {{ username }} b" });
+    await nextTick();
+    editable(el2).querySelector<HTMLElement>(".hk-tpl-chip")!.click();
+    await nextTick();
+    const editorRows = document.body.querySelector<HTMLElement>(".hk-tpl-editor-rows")!;
+    expect(editorRows.getAttribute("role")).toBeNull();
+  });
+
+  it("the panel's active highlight follows the filtered index inside wrappers", async () => {
+    const el = mountWithTokens([
+      { name: "id", group: "identity" },
+      { name: "username", group: "identity" },
+      { name: "md5_email", group: "email" },
+      { name: "sha256_email", group: "email" },
+    ]);
+    await nextTick();
+    await openTrigger(el, "{{ ");
+    editable(el).dispatchEvent(
+      new KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true }),
+    );
+    await nextTick();
+    const active = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-row[data-active]"));
+    expect(active).toHaveLength(1);
+    // Index 1 across the WHOLE filtered list (username) — the highlight
+    // must not restart inside each group wrapper.
+    expect(active[0]!.textContent).toContain("username");
+  });
+});

package/src/components/HkTemplateField.tsx

@@ -2,9 +2,10 @@ import {
   computed,
   defineComponent,
   nextTick,
-  useId,
+  onBeforeUnmount,
   onMounted,
   ref,
+  useId,
   watch,
   type PropType,
 } from "vue";
@@ -12,6 +13,8 @@ import { Trash2 } from "lucide-vue-next";
 
 import HButton from "./HkButton";
 import HkInput from "./HkInput";
+import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
+import { useBreakpoint } from "../runtime/useBreakpoint";
 import HkMenu from "./HkMenu";
 import HPopover from "./HkPopover";
 import { useI18n } from "../i18n/context";
@@ -25,6 +28,12 @@ import {
 } from "./templateGrammar";
 import "./HkTemplateField.scss";
 
+/** What renderGroupedRows hands its row callback. */
+interface HkTemplateFieldRow {
+  def: HkTemplateTokenDef;
+  index: number;
+}
+
 /** Matches an UNFINISHED `{{ query` the caret is typing inside — the
  * autocomplete trigger. Identifiers only; anything else (a filter pipe,
  * a space) drops out of trigger state and closes the panel. */
@@ -84,6 +93,16 @@ export const HkTemplateField = defineComponent({
     /** Submit intent on Enter (when no suggestion row is active) —
      * same contract as HkInput. */
     submitOnEnter: { type: Function, default: undefined },
+    /** Maps a token's `group` to the heading label shown over its run
+     *  of rows (both the vocabulary panel and the chip editor). Passed
+     *  through verbatim when omitted — groups are consumer-defined
+     *  technical keys, so the library has no opinion on their wording.
+     *
+     *  Partially-grouped vocabularies: a token WITHOUT a `group` is not
+     *  a section of its own — it renders under the previous heading's
+     *  band (the heading marks where a group STARTS, not where it ends).
+     *  Give every token a group when the sections must be airtight. */
+    groupLabel: { type: Function as PropType<(group: string) => string>, default: undefined },
   },
   emits: {
     "update:modelValue": (_v: string) => true,
@@ -419,6 +438,41 @@ export const HkTemplateField = defineComponent({
 
     const editorRows = computed(() => filterTokens(props.tokens, editorQuery.value));
 
+    // The rows list scrolls through the SHARED overlay scrollbar
+    // (house chrome — a native overflow bar inside a hikari popup is
+    // the family violation this replaces). The scroll host wraps
+    // EXACTLY the scrolling rows (rails must not span the form's other
+    // bands); sheet mode attaches nothing — the docked panel owns the
+    // window's one scrollbar there.
+    const { isMobile } = useBreakpoint();
+    const editorRowsHostRef = ref<HTMLElement | null>(null);
+    const editorRowsRef = ref<HTMLElement | null>(null);
+    let editorRowsScrollbar: OverlayScrollbarHandle | null = null;
+
+    function syncEditorRowsScrollbar(): void {
+      editorRowsScrollbar?.update();
+    }
+
+    // The shared scrollbar observes the VIEWPORT box; a vocabulary edit
+    // that changes the rows' content height without resizing the viewport
+    // would leave the thumb stale until the next scroll — refresh it when
+    // the (filtered) rows change.
+    watch(editorRows, () => { nextTick(syncEditorRowsScrollbar); });
+
+    function detachEditorRowsScrollbar(): void {
+      editorRowsScrollbar?.detach();
+      editorRowsScrollbar = null;
+    }
+
+    function attachEditorRowsScrollbar(): void {
+      detachEditorRowsScrollbar();
+      if (isMobile.value) return; // sheet: the panel owns the scrollbar
+      const viewport = editorRowsRef.value;
+      const host = editorRowsHostRef.value;
+      if (!viewport || !host) return;
+      editorRowsScrollbar = attachOverlayScrollbars(viewport, { axis: "vertical", host });
+    }
+
     const editorDef = computed(() => tokenIndex.value.get(editorToken.value));
 
     function openChipEditor(chip: HTMLElement): void {
@@ -428,6 +482,10 @@ export const HkTemplateField = defineComponent({
       // panel's outside-click shield does not fire) trades it for the
       // editor instead of stacking both.
       closeSuggestions();
+      // A reopen cancels any reclaim still owed by the previous close's
+      // leave window — firing it now would steal focus from the freshly
+      // opened editor's search input.
+      pendingEditorReclaim.value = false;
       editorChip.value = chip;
       editorToken.value = chip.dataset.token ?? "";
       editorQuery.value = "";
@@ -437,6 +495,13 @@ export const HkTemplateField = defineComponent({
       // popover and the mobile sheet.
       nextTick(() => {
         editorSearchWrap.value?.querySelector("input")?.focus();
+        // Re-arm the focus latch explicitly: a reopen INSIDE the previous
+        // close's leave window focuses an input that (in programmatic
+        // flows) never blurred, so no focusin fires and the latch would
+        // stay false — the next close would then skip its reclaim and
+        // orphan focus on <body> (R1 S2 finding).
+        editorHoldsFocus.value = true;
+        attachEditorRowsScrollbar();
       });
     }
 
@@ -527,44 +592,49 @@ export const HkTemplateField = defineComponent({
       editRef.value?.focus();
     }
 
+    /** True when focus is unowned (body/nowhere) or already back on
+     * this field — the only states the editor close may reclaim it
+     * from. An outside-click close that focused another control must
+     * not have focus yanked back 3ms later (real-browser R1 finding). */
+    function editorFocusReclaimable(): boolean {
+      const active = document.activeElement;
+      return (
+        !active ||
+        active === document.body ||
+        (editRef.value ? active === editRef.value || editRef.value.contains(active) : false)
+      );
+    }
+
+    function reclaimEditorFocus(): void {
+      if (!editorFocusReclaimable()) return;
+      editRef.value?.focus();
+      // The chip may have been re-rendered away by the time this runs
+      // (a late reclaim) — a detached reference must not steer the
+      // caret (offsetAfterChip would return the full length).
+      if (editorChip.value?.isConnected) {
+        applyCaretOffset(offsetAfterChip(editorChip.value));
+      }
+    }
+
+    /** Set when a closing chip editor may still owe the field its
+     * focus back (through the leave window); cleared by the popover's
+     * settled `closed` edge or the next open. */
+    const pendingEditorReclaim = ref(false);
+
     function closeChipEditor(): void {
       if (!editorOpen.value) return;
       editorOpen.value = false;
+      detachEditorRowsScrollbar();
       if (editorHoldsFocus.value) {
         editorHoldsFocus.value = false;
-        /** True when focus is unowned (body/nowhere) or already back
-         * on this field — the only states we may reclaim it from. */
-        const reclaimable = () => {
-          const active = document.activeElement;
-          return (
-            !active ||
-            active === document.body ||
-            (editRef.value ? active === editRef.value || editRef.value.contains(active) : false)
-          );
-        };
-        const reclaim = () => {
-          if (!reclaimable()) return;
-          editRef.value?.focus();
-          // The chip may have been re-rendered away by the time this
-          // runs (late timers) — a detached reference must not steer
-          // the caret (offsetAfterChip would return the full length).
-          if (editorChip.value?.isConnected) {
-            applyCaretOffset(offsetAfterChip(editorChip.value));
-          }
-        };
-        // Return focus ONLY when it did not land on something else by
-        // user intent: an outside-click close that focused another
-        // control must not yank focus back 3ms later (real-browser R1
-        // finding — focus@t → blur@t+3ms → activeElement ended up on
-        // this field, not the clicked input).
-        nextTick(reclaim);
-        // And once more past the popover's leave window: an Escape
-        // close leaves the search input holding focus THROUGH the
-        // closing animation, so the probe above correctly declines —
-        // but when the panel finishes unmounting, focus falls to
-        // <body> and nobody reclaims it. Re-run the same ownership
-        // probe after the leave budget (R2 finding).
-        setTimeout(reclaim, 400);
+        nextTick(reclaimEditorFocus);
+        // An Escape close keeps the search input holding focus THROUGH
+        // the closing animation, so the probe above correctly declines;
+        // when the panel finishes unmounting, focus falls to <body>
+        // with nobody to reclaim it. The popover's `closed` event (the
+        // settled leave edge) re-runs the same ownership probe exactly
+        // then — no timer race with a long or short leave animation.
+        pendingEditorReclaim.value = true;
       }
     }
 
@@ -582,6 +652,10 @@ export const HkTemplateField = defineComponent({
       renderValue(props.modelValue);
     });
 
+    onBeforeUnmount(() => {
+      detachEditorRowsScrollbar();
+    });
+
     // ── Editable event wiring ───────────────────────────────────────
 
     function onInput(): void {
@@ -807,6 +881,51 @@ export const HkTemplateField = defineComponent({
       };
     }
 
+    /** Grouped rows as labeled WRAPPERS, not sibling headings: a
+     *  `role="group"` box carrying the group's name in `aria-label` is
+     *  the pattern screen readers announce on entry (a bare
+     *  role="presentation" heading band was invisible to them — the
+     *  R3 P3 finding), and it is the sanctioned way to segment choices
+     *  inside HkMenu's role="menu" surface. The visible heading text
+     *  lives in the inner .hk-tpl-group-label band. */
+    function renderGroupedRows(
+      defs: readonly HkTemplateTokenDef[],
+      renderRow: (row: HkTemplateFieldRow) => unknown,
+    ): unknown[] {
+      const out: unknown[] = [];
+      let run: { label: string; rows: unknown[] } | null = null;
+      const flush = () => {
+        if (!run) return;
+        out.push(
+          <div class="hk-tpl-group" role="group" aria-label={run.label}>
+            <div class="hk-tpl-group-label" aria-hidden="true">{run.label}</div>
+            {run.rows}
+          </div>,
+        );
+        run = null;
+      };
+      for (let i = 0; i < defs.length; i++) {
+        const def = defs[i]!;
+        if (def.group !== undefined) {
+          const label = props.groupLabel ? props.groupLabel(def.group) : def.group;
+          if (!run || run.label !== label) {
+            flush();
+            run = { label, rows: [] };
+          }
+        }
+        // Tokens without a group simply continue under the previous
+        // group's visual section — the documented contract for
+        // partially-grouped vocabularies (see the prop doc). When the
+        // run is open they ride inside it; a leading ungrouped run
+        // renders bare, exactly as an ungrouped vocabulary does.
+        const row = renderRow({ def, index: i });
+        if (run) run.rows.push(row);
+        else out.push(row);
+      }
+      flush();
+      return out;
+    }
+
     const renderTokenRow = (
       def: HkTemplateTokenDef,
       active: boolean,
@@ -882,13 +1001,13 @@ export const HkTemplateField = defineComponent({
           title={t("hikari::templateField.suggestTitle", "Placeholders")}
         >
           {filteredTokens.value.length > 0 ? (
-            <div class="hk-tpl-rows" role="listbox">
-              {filteredTokens.value.map((def, i) =>
+            <div class="hk-tpl-rows">
+              {renderGroupedRows(filteredTokens.value, ({ def, index }) =>
                 renderTokenRow(
                   def,
-                  i === Math.min(suggestActive.value, filteredTokens.value.length - 1),
+                  index === Math.min(suggestActive.value, filteredTokens.value.length - 1),
                   () => pickSuggestion(def),
-                  i,
+                  index,
                 ),
               )}
             </div>
@@ -906,6 +1025,16 @@ export const HkTemplateField = defineComponent({
           onUpdate:modelValue={(v: boolean) => {
             if (!v) closeChipEditor();
           }}
+          onClosed={() => {
+            if (!pendingEditorReclaim.value) return;
+            pendingEditorReclaim.value = false;
+            // HkPopover emits this from a nextTick AFTER the patch that
+            // removed the panel (its own doc contract, verified in a
+            // real browser: the handler sees no panel and focus already
+            // fallen to <body>) — so the ownership probe can run here
+            // directly.
+            reclaimEditorFocus();
+          }}
           anchorRef={editorChip.value}
           sheetOnMobile
           placement="bottom-start"
@@ -937,19 +1066,24 @@ export const HkTemplateField = defineComponent({
             >
               <HkInput
                 modelValue={editorQuery.value}
-                onUpdate:modelValue={(v: string) => { editorQuery.value = v; }}
+                onUpdate:modelValue={(v: string) => {
+                  editorQuery.value = v;
+                  nextTick(syncEditorRowsScrollbar);
+                }}
                 placeholder={t("hikari::templateField.chipSearch", "Search placeholders")}
               />
             </div>
-            <div class="hk-tpl-editor-rows" role="listbox">
-              {editorRows.value.map((def) =>
-                renderTokenRow(def, def.name === editorToken.value, () => applyChipToken(def.name)),
-              )}
-              {editorRows.value.length === 0 && (
-                <p class="hk-tpl-rows-empty">
-                  {t("hikari::templateField.suggestEmpty", "No matching placeholders")}
-                </p>
-              )}
+            <div ref={editorRowsHostRef} class="hk-tpl-editor-scroll">
+              <div ref={editorRowsRef} class="hk-tpl-editor-rows">
+                {renderGroupedRows(editorRows.value, ({ def }) =>
+                  renderTokenRow(def, def.name === editorToken.value, () => applyChipToken(def.name)),
+                )}
+                {editorRows.value.length === 0 && (
+                  <p class="hk-tpl-rows-empty">
+                    {t("hikari::templateField.suggestEmpty", "No matching placeholders")}
+                  </p>
+                )}
+              </div>
             </div>
             <div class="hk-tpl-editor-footer">
               <HButton