@celestia-island/hikari 0.55.125 → 0.55.126

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.125",
+  "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/HkTemplateField.scss

@@ -161,7 +161,18 @@
   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;

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

@@ -92,6 +92,14 @@ describe("HkTemplateField stylesheet contract", () => {
     }
   });
 
+  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);

package/src/components/HkTemplateField.test.tsx

@@ -415,30 +415,44 @@ describe("HkTemplateField grouped vocabulary", () => {
     { name: "sha256_email", group: "email" },
   ];
 
-  it("renders one heading per group run in the panel", async () => {
+  it("renders one labeled group wrapper per run in the panel", async () => {
     const el = mountWithTokens(GROUPED);
     await nextTick();
     await openTrigger(el, "{{ ");
-    const headings = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-group"));
-    expect(headings.map((h) => h.textContent)).toEqual(["identity", "email"]);
-    // Headings are presentational, not options.
-    expect(headings.every((h) => h.getAttribute("role") === "presentation")).toBe(true);
+    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 headings = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-group"));
-    expect(headings.map((h) => h.textContent)).toEqual(["IDENTITY", "EMAIL"]);
+    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 headings = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-group"));
-    expect(headings.map((h) => h.textContent)).toEqual(["email"]);
+    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 () => {
@@ -454,10 +468,10 @@ describe("HkTemplateField grouped vocabulary", () => {
     await nextTick();
     editable(el).querySelector<HTMLElement>(".hk-tpl-chip")!.click();
     await nextTick();
-    const headings = Array.from(
+    const groups = Array.from(
       document.body.querySelectorAll<HTMLElement>(".hk-tpl-editor .hk-tpl-group"),
     );
-    expect(headings.map((h) => h.textContent)).toEqual(["identity", "email"]);
+    expect(groups.map((g) => g.getAttribute("aria-label"))).toEqual(["identity", "email"]);
   });
 });
 
@@ -647,10 +661,53 @@ describe("HkTemplateField partially-grouped vocabulary", () => {
     ]);
     await nextTick();
     await openTrigger(el, "{{ ");
-    const headings = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-group"));
-    // Two headings for two group STARTS; the trailing ungrouped tokens
-    // stay under the last heading (see the groupLabel prop doc).
-    expect(headings.map((h) => h.textContent)).toEqual(["identity", "email"]);
+    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

@@ -28,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. */
@@ -875,34 +881,48 @@ export const HkTemplateField = defineComponent({
       };
     }
 
-    /** Rows with non-interactive group headings: a heading lands
-     * wherever the (filtered) vocabulary's group changes, so a family
-     * whose every member was filtered out never shows a stray header.
-     * Vocabulary order is the contract — consumers list each group's
-     * tokens contiguously. */
+    /** 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: (def: HkTemplateTokenDef, index: number) => unknown,
+      renderRow: (row: HkTemplateFieldRow) => unknown,
     ): unknown[] {
       const out: unknown[] = [];
-      let lastGroup: string | undefined;
+      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) {
-          if (def.group !== lastGroup) {
-            out.push(
-              <div class="hk-tpl-group" role="presentation">
-                {props.groupLabel ? props.groupLabel(def.group) : def.group}
-              </div>,
-            );
+          const label = props.groupLabel ? props.groupLabel(def.group) : def.group;
+          if (!run || run.label !== label) {
+            flush();
+            run = { label, rows: [] };
           }
-          lastGroup = def.group;
         }
         // Tokens without a group simply continue under the previous
-        // heading's visual section — the documented contract for
-        // partially-grouped vocabularies (see the prop doc).
-        out.push(renderRow(def, i));
+        // 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;
     }
 
@@ -981,13 +1001,13 @@ export const HkTemplateField = defineComponent({
           title={t("hikari::templateField.suggestTitle", "Placeholders")}
         >
           {filteredTokens.value.length > 0 ? (
-            <div class="hk-tpl-rows" role="listbox">
-              {renderGroupedRows(filteredTokens.value, (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>
@@ -1054,8 +1074,8 @@ export const HkTemplateField = defineComponent({
               />
             </div>
             <div ref={editorRowsHostRef} class="hk-tpl-editor-scroll">
-              <div ref={editorRowsRef} class="hk-tpl-editor-rows" role="listbox">
-                {renderGroupedRows(editorRows.value, (def) =>
+              <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 && (