@celestia-island/hikari 0.55.125 → 0.55.127

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.125",
+  "version": "0.55.127",
   "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,116 @@ 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("container roles split by context: panel bare in the menu, editor a labeled listbox", async () => {
+    const el = mountWithTokens([
+      { name: "id", group: "identity" },
+      { name: "md5_email", group: "email" },
+    ]);
+    await nextTick();
+    await openTrigger(el, "{{ ");
+    // The panel surface is HkMenu's role="menu" — the rows container
+    // must not re-role it (listbox-in-menu was the illegal nesting).
+    const panelRows = document.body.querySelector<HTMLElement>(".hk-tpl-rows")!;
+    expect(panelRows.getAttribute("role")).toBeNull();
+
+    // The editor surface is a DIALOG — a listbox is the correct list
+    // semantics there (restored deliberately, with an accessible name).
+    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")).toBe("listbox");
+    expect(editorRows.getAttribute("aria-label")).toBeTruthy();
+  });
+
+  it("panel rows are menuitems and the editable announces the active one", async () => {
+    const el = mountWithTokens([
+      { name: "id", group: "identity" },
+      { name: "username", group: "identity" },
+    ]);
+    await nextTick();
+    const edit = editable(el);
+    await openTrigger(el, "{{ ");
+    // Combobox wiring on the editable: expanded + owns the rows.
+    expect(edit.getAttribute("aria-haspopup")).toBe("menu");
+    expect(edit.getAttribute("aria-expanded")).toBe("true");
+    const rowsId = edit.getAttribute("aria-owns")!;
+    expect(rowsId).toBeTruthy();
+    expect(document.getElementById(rowsId)?.classList.contains("hk-tpl-rows")).toBe(true);
+    // Rows are menuitems with stable ids.
+    const rows = Array.from(document.body.querySelectorAll<HTMLElement>(".hk-tpl-rows .hk-tpl-row"));
+    expect(rows.every((r) => r.getAttribute("role") === "menuitem")).toBe(true);
+    expect(rows[0]!.id).toBe(`${rowsId}-row-0`);
+    // The activedescendant starts at the first row and follows ArrowDown.
+    expect(edit.getAttribute("aria-activedescendant")).toBe(`${rowsId}-row-0`);
+    edit.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true }),
+    );
+    await nextTick();
+    expect(edit.getAttribute("aria-activedescendant")).toBe(`${rowsId}-row-1`);
+
+    // Zero matches while the panel is open: the rows container does
+    // not render, so aria-owns must not dangle (R1 finding).
+    await openTrigger(el, "{{ idzzz");
+    expect(edit.getAttribute("aria-owns")).toBeNull();
+    expect(edit.getAttribute("aria-activedescendant")).toBeNull();
+    expect(edit.getAttribute("aria-expanded")).toBe("true");
+
+    // Collapsed state: no expansion attributes dangle.
+    edit.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true }),
+    );
+    await nextTick();
+    expect(edit.getAttribute("aria-expanded")).toBeNull();
+    expect(edit.getAttribute("aria-owns")).toBeNull();
+    expect(edit.getAttribute("aria-activedescendant")).toBeNull();
+  });
+
+  it("editor rows are options with the current token selected", async () => {
+    const el = mount({ modelValue: "a {{ username }} b" });
+    await nextTick();
+    editable(el).querySelector<HTMLElement>(".hk-tpl-chip")!.click();
+    await nextTick();
+    const options = Array.from(
+      document.body.querySelectorAll<HTMLElement>(".hk-tpl-editor-rows .hk-tpl-row"),
+    );
+    expect(options.length).toBeGreaterThan(1);
+    expect(options.every((o) => o.getAttribute("role") === "option")).toBe(true);
+    const selected = options.filter((o) => o.getAttribute("aria-selected") === "true");
+    expect(selected).toHaveLength(1);
+    expect(selected[0]!.textContent).toContain("username");
+  });
+
+  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. */
@@ -108,6 +114,9 @@ export const HkTemplateField = defineComponent({
     // association HkInput gives a bare `label` prop — label clicks
     // focus, screen readers announce the field by name).
     const fieldId = useId();
+    /** Stable id for the panel rows container + its row ids (combobox
+     *  aria-owns/activedescendant targets). */
+    const panelRowsId = `hk-tpl-panel-${fieldId}`;
 
     const editRef = ref<HTMLElement | null>(null);
     /** The value the DOM currently represents. Authoritative while the
@@ -875,49 +884,76 @@ 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;
     }
 
+    /** Row chrome shared by both surfaces. The ROLE rides the surface:
+     *  the panel lives inside HkMenu's role="menu" (menuitem — the
+     *  HkMenuActionItem family pattern), the editor lives in a dialog
+     *  and is a proper listbox (option + aria-selected on the token
+     *  being edited). */
     const renderTokenRow = (
       def: HkTemplateTokenDef,
       active: boolean,
       onPick: () => void,
-      i?: number,
+      opts: {
+        i?: number;
+        role: "menuitem" | "option";
+        selected?: boolean;
+        id?: string;
+      },
     ) => (
       <button
         key={def.name}
         type="button"
         class="hk-tpl-row"
+        role={opts.role}
+        id={opts.id}
+        aria-selected={opts.role === "option" ? (opts.selected || false) : undefined}
         data-active={active || undefined}
-        ref={i !== undefined ? setRowRef(i) : undefined}
+        ref={opts.i !== undefined ? setRowRef(opts.i) : undefined}
         onMousedown={(e: MouseEvent) => e.preventDefault()}
         onClick={(e: MouseEvent) => {
           e.stopPropagation();
@@ -946,6 +982,21 @@ export const HkTemplateField = defineComponent({
             contenteditable={!props.disabled}
             role="textbox"
             aria-multiline="false"
+            // Combobox announcement wiring: the editable OWNS the popup
+            // (aria-owns makes the teleported rows virtual descendants)
+            // and points aria-activedescendant at the highlighted row,
+            // so arrow-key navigation is announced without moving DOM
+            // focus out of the field.
+            aria-haspopup="menu"
+            aria-expanded={suggestOpen.value || undefined}
+            aria-owns={
+              suggestOpen.value && filteredTokens.value.length > 0 ? panelRowsId : undefined
+            }
+            aria-activedescendant={
+              suggestOpen.value && filteredTokens.value.length > 0
+                ? `${panelRowsId}-row-${Math.min(suggestActive.value, filteredTokens.value.length - 1)}`
+                : undefined
+            }
             id={fieldId}
             spellcheck={false}
             data-ph={props.placeholder}
@@ -981,13 +1032,17 @@ 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" id={panelRowsId}>
+              {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,
+                  {
+                    i: index,
+                    role: "menuitem",
+                    id: `${panelRowsId}-row-${index}`,
+                  },
                 ),
               )}
             </div>
@@ -1054,9 +1109,17 @@ 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) =>
-                  renderTokenRow(def, def.name === editorToken.value, () => applyChipToken(def.name)),
+              <div
+                ref={editorRowsRef}
+                class="hk-tpl-editor-rows"
+                role="listbox"
+                aria-label={t("hikari::templateField.chipEditorTitle", "Edit placeholder")}
+              >
+                {renderGroupedRows(editorRows.value, ({ def }) =>
+                  renderTokenRow(def, def.name === editorToken.value, () => applyChipToken(def.name), {
+                    role: "option",
+                    selected: def.name === editorToken.value,
+                  }),
                 )}
                 {editorRows.value.length === 0 && (
                   <p class="hk-tpl-rows-empty">