@celestia-island/hikari 0.55.239 → 0.55.240

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.239",
+  "version": "0.55.240",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkMenuPanel.scss

@@ -13,6 +13,10 @@
   display: flex;
   flex-direction: column;
   gap: var(--space-4, 4px);
+  /* This list's own row rhythm is 4px, so a captioned run moved into a
+     group box must match it (the section grammar defaults to the level's
+     2px). */
+  --hk-menu-section-gap: var(--space-4, 4px);
   /* Inset matches .hk-sidebar-body's inline padding so items share the
      nav text edge; override --hk-menu-panel-inset to re-anchor. */
   padding: var(--space-8, 8px) var(--hk-menu-panel-inset, var(--space-12, 12px));

package/src/components/HkMenuSection.test.tsx

@@ -0,0 +1,191 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  Fragment,
+  createApp,
+  createCommentVNode,
+  createTextVNode,
+  h,
+  nextTick,
+  ref,
+} from "vue";
+
+import HkMenuSection from "./HkMenuSection";
+
+/**
+ * HkMenuSection contract tests:
+ *
+ * - GROUP: the wrapper is `role="group"` named by the `label` prop (the
+ *   HkTemplateField a11y precedent), so a captioned row run is announced
+ *   as one named group inside a menu surface.
+ * - CAPTION: the visible band carries the label text, is `aria-hidden`
+ *   (the wrapper already announced the name) and uses the grammar's
+ *   class names — the global adopter rules in styles/admin-tokens style
+ *   them, the component imports no scss.
+ * - SLOT OVERRIDE: the `label` slot replaces the visible text while the
+ *   accessible name stays the `label` prop; an EMPTY slot result (an empty
+ *   array, a comment vnode from a compiled `v-if`, blank strings / TEXT
+ *   vnodes) falls back to the prop text (never an empty padded band).
+ * - ROWS: the default slot renders inside the group, after the caption.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(render: () => unknown): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts) {
+    app.unmount();
+    container.remove();
+  }
+  mounts.length = 0;
+});
+
+describe("HkMenuSection", () => {
+  it("renders a role=group named by label, with a visible aria-hidden caption", () => {
+    const c = mount(() => h(HkMenuSection, { label: "Temp spaces" }));
+
+    const group = c.querySelector<HTMLElement>(".hk-menu-section");
+    expect(group, ".hk-menu-section renders").toBeTruthy();
+    expect(group!.getAttribute("role")).toBe("group");
+    expect(group!.getAttribute("aria-label")).toBe("Temp spaces");
+
+    const caption = group!.querySelector<HTMLElement>(".hk-menu-section-label");
+    expect(caption, "the visible caption band renders").toBeTruthy();
+    expect(caption!.textContent).toBe("Temp spaces");
+    // The band repeats the wrapper's accessible name visually only.
+    expect(caption!.getAttribute("aria-hidden")).toBe("true");
+    // It is the group's first child: caption above the rows.
+    expect(group!.firstElementChild).toBe(caption);
+  });
+
+  it("keeps the accessible name on the label prop when the label slot overrides the band", () => {
+    const c = mount(() =>
+      h(
+        HkMenuSection,
+        { label: "Temp spaces" },
+        {
+          label: () => [h("span", { class: "section-count" }, "3")],
+          default: () => [
+            h("button", { type: "button", class: "hk-menu-action-item" }, "Scratch"),
+          ],
+        },
+      ),
+    );
+
+    const group = c.querySelector<HTMLElement>(".hk-menu-section")!;
+    // Rich visible content never changes the announced group name.
+    expect(group.getAttribute("aria-label")).toBe("Temp spaces");
+    const caption = group.querySelector<HTMLElement>(".hk-menu-section-label")!;
+    expect(caption.textContent).toBe("3");
+    expect(caption.querySelector(".section-count")).toBeTruthy();
+    expect(caption.getAttribute("aria-hidden")).toBe("true");
+  });
+
+  it("falls back to the label prop when the label slot renders nothing", () => {
+    // `[]` is not nullish: a naive `slots.label?.() ?? props.label` keeps
+    // the empty band (padded dead space above the rows).
+    const c = mount(() =>
+      h(HkMenuSection, { label: "Temp spaces" }, { label: () => [] }),
+    );
+
+    const caption = c.querySelector<HTMLElement>(".hk-menu-section-label")!;
+    expect(caption.textContent).toBe("Temp spaces");
+    expect(caption.getAttribute("aria-hidden")).toBe("true");
+  });
+
+  it("falls back to the label prop when the label slot renders only a comment vnode", () => {
+    // A compiled `v-if` slot root is a COMMENT vnode (length 1, not nullish):
+    // it must count as no caption or the aria-hidden band stays padded and
+    // empty.
+    const c = mount(() =>
+      h(HkMenuSection, { label: "Temp spaces" }, {
+        label: () => [createCommentVNode("v-if", true)],
+      }),
+    );
+
+    const caption = c.querySelector<HTMLElement>(".hk-menu-section-label")!;
+    expect(caption.textContent).toBe("Temp spaces");
+    expect(caption.getAttribute("aria-hidden")).toBe("true");
+  });
+
+  it("looks through a fragment that wraps only comments and blank strings", () => {
+    const c = mount(() =>
+      h(HkMenuSection, { label: "Temp spaces" }, {
+        label: () => [
+          h(Fragment, null, [createCommentVNode("v-if", true), "   "]),
+        ],
+      }),
+    );
+
+    const caption = c.querySelector<HTMLElement>(".hk-menu-section-label")!;
+    expect(caption.textContent).toBe("Temp spaces");
+  });
+
+  it("falls back for top-level blank and empty slot strings", () => {
+    for (const blank of ["   ", ""]) {
+      const c = mount(() =>
+        h(HkMenuSection, { label: "Temp spaces" }, { label: () => [blank] }),
+      );
+      const caption = c.querySelector<HTMLElement>(".hk-menu-section-label")!;
+      expect(caption.textContent, `slot ${JSON.stringify(blank)}`).toBe("Temp spaces");
+    }
+  });
+
+  it("falls back for a TEXT vnode inside a fragment", () => {
+    // Vue normalizes text children into TEXT vnodes (and a compiled slot's
+    // whitespace root becomes one directly) — blank text must be absent.
+    const c = mount(() =>
+      h(HkMenuSection, { label: "Temp spaces" }, {
+        label: () => [h(Fragment, null, [createTextVNode("   "), createTextVNode("")])],
+      }),
+    );
+
+    const caption = c.querySelector<HTMLElement>(".hk-menu-section-label")!;
+    expect(caption.textContent).toBe("Temp spaces");
+  });
+
+  it("updates the visible caption when the label prop changes", async () => {
+    // Fences the render-function caption resolution: a cached computed
+    // would keep the first nodes.
+    const label = ref("Temp spaces");
+    const c = mount(() => h(HkMenuSection, { label: label.value }));
+    expect(c.querySelector(".hk-menu-section-label")!.textContent).toBe("Temp spaces");
+
+    label.value = "Permanent spaces";
+    await nextTick();
+    expect(c.querySelector(".hk-menu-section-label")!.textContent).toBe("Permanent spaces");
+    expect(c.querySelector(".hk-menu-section")!.getAttribute("aria-label")).toBe(
+      "Permanent spaces",
+    );
+  });
+
+  it("renders the default slot's rows inside the group, after the caption", () => {
+    const c = mount(() =>
+      h(
+        HkMenuSection,
+        { label: "Temp spaces" },
+        {
+          default: () => [
+            h("button", { type: "button", class: "hk-menu-action-item" }, "Scratch"),
+            h("button", { type: "button", class: "hk-menu-action-item" }, "Long-term"),
+          ],
+        },
+      ),
+    );
+
+    const group = c.querySelector<HTMLElement>(".hk-menu-section")!;
+    const rows = group.querySelectorAll(".hk-menu-action-item");
+    expect(Array.from(rows).map((row) => row.textContent)).toEqual(["Scratch", "Long-term"]);
+    // caption + the two rows, in that ORDER (rows must never precede the
+    // band that names them).
+    expect(group.children).toHaveLength(3);
+    expect(group.querySelector(".hk-menu-section-label")!.nextElementSibling).toBe(rows[0]);
+  });
+});

package/src/components/HkMenuSection.tsx

@@ -0,0 +1,95 @@
+import { Comment, Fragment, Text, defineComponent } from "vue";
+
+/** True when slot content carries something visible. A compiled `v-if`
+ *  root is a COMMENT vnode (not an empty array), a text slot child may be
+ *  normalized into a TEXT vnode, a fragment may wrap only comments/blank
+ *  text, and whitespace-only strings are not a caption — none of them may
+ *  leave a padded, empty aria-hidden band. */
+function hasVisibleContent(nodes: readonly unknown[]): boolean {
+  for (const node of nodes) {
+    if (typeof node === "string") {
+      if (node.trim() !== "") return true;
+      continue;
+    }
+    if (typeof node === "number") return true;
+    if (node && typeof node === "object") {
+      const vnode = node as { type?: unknown; children?: unknown };
+      if (vnode.type === Comment) continue;
+      if (vnode.type === Text) {
+        if (typeof vnode.children === "string" && vnode.children.trim() !== "") return true;
+        continue;
+      }
+      if (vnode.type === Fragment) {
+        if (typeof vnode.children === "string") {
+          if (vnode.children.trim() !== "") return true;
+        } else if (Array.isArray(vnode.children)) {
+          if (hasVisibleContent(vnode.children)) return true;
+        }
+        continue;
+      }
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * HkMenuSection — a captioned run of menu rows.
+ *
+ * The small caption ABOVE a run of rows is part of the menu-item grammar
+ * (see _menu-item.scss, @mixin section / @mixin section-label), but it is
+ * hand-rolled at call sites across this library and its consumer's popup
+ * menus, with vertical insets from 0 to 6px and no shared token. This
+ * component is the ONE markup for it:
+ *
+ *   <HkMenuSection label="Temp spaces">
+ *     <HkMenuActionItem … />
+ *   </HkMenuSection>
+ *
+ * Accessibility follows the HkTemplateField precedent: grouping is a
+ * `role="group"` wrapper carrying the group's name in `aria-label`, and
+ * the visible caption band inside is `aria-hidden="true"`. The wrapper
+ * already announces the name, so leaving the visible band in the a11y
+ * tree would double-announce it (and a bare heading band was invisible to
+ * screen readers before that wave).
+ *
+ * `label` is both the accessible group name and the default visible
+ * caption text; the optional `label` slot supplies richer visible content
+ * (a badge, a count) while `aria-label` keeps the prop's plain string.
+ * The slot must be NON-INTERACTIVE content: it renders inside the
+ * aria-hidden band, so a focusable node there would be an axe
+ * `aria-hidden-focus` violation, and its visible text must not contradict
+ * the accessible name (keep the prop as the plain group name). The
+ * default slot is the rows.
+ *
+ * Metrics come from the global adopter rules in styles/admin-tokens
+ * (`@include mi.section` / `@include mi.section-label`), loaded by the
+ * canonical styles entry — deliberately NO local scss import, so hosts
+ * that render the classes by hand and this component share one
+ * declaration (the HkAvatarButton precedent).
+ */
+export default defineComponent({
+  name: "HkMenuSection",
+  props: {
+    /** Accessible group name AND the default visible caption text. */
+    label: { type: String, required: true },
+  },
+  setup(props, { slots }) {
+    // Resolve the caption INSIDE the render function: a computed caches
+    // the slot's vnodes and a pre-built-node slot goes stale when the
+    // parent re-renders. An empty result ([] / comment vnodes / blank
+    // strings) falls back to the prop text instead of leaving a padded,
+    // empty aria-hidden band.
+    return () => {
+      const caption = slots.label?.();
+      return (
+        <div class="hk-menu-section" role="group" aria-label={props.label}>
+          <div class="hk-menu-section-label" aria-hidden="true">
+            {caption && hasVisibleContent(caption) ? caption : props.label}
+          </div>
+          {slots.default?.()}
+        </div>
+      );
+    };
+  },
+});

package/src/components/HkTemplateField.scss

@@ -1,3 +1,5 @@
+@use "./menu-item" as mi;
+
 // 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
@@ -185,14 +187,26 @@
 }
 
 .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;
+  // The menu grammar's shared section-caption band (_menu-item.scss
+  // @mixin section-label), same as HkMenuSection's
+  // .hk-menu-section-label — the hand-rolled bands across this library
+  // and its consumer's popup menus (0–6px vertical insets) converge here.
+  // hikari's theme-menu caption (.s-theme-menu-label) stays hand-rolled
+  // on purpose: its 4/6/4 band sits ~8px clear of its rows, so it never
+  // exhibited the glued-to-the-first-row defect this grammar fixes.
+  // This adopter inherits the grammar's shift too, it is not a band-only
+  // change: vertical rhythm 6/8/2 → 4/6/8 (up, bottom-heavy) AND the
+  // inline inset 8 → 6px, i.e. the caption steps 2px LEFT toward
+  // .hk-tpl-row's content edge — the requested 偏左 direction.
+  @include mi.section-label;
+  // The local alias is this adopter's default: hosts scope
+  // --hi-color-muted for this panel and the rest of this sheet sources
+  // muted through the same alias. The grammar's
+  // --hk-menu-section-label-color still overrides it for a host that
+  // themes captions as a family.
+  color: var(--hk-menu-section-label-color, var(--hi-color-muted));
   // 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 {

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

@@ -41,6 +41,7 @@ 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 scss = readFileSync(resolve(componentDir, "HkTemplateField.scss"), "utf8");
   const css = compile(resolve(componentDir, "HkTemplateField.scss"), {
     style: "expanded",
   }).css;
@@ -99,12 +100,59 @@ 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);
+    // (padding/font-weight) there would pad every row run. The band is an
+    // ADOPTER of the menu grammar's section-caption mixin, and the pins
+    // below are satisfied ONLY by the grammar's token form: a restored
+    // hand-rolled band (literal padding / a bare `font-weight: 600` /
+    // `@include` removed) must fail. R2 proved an optional-group regex
+    // matched both spellings, so the previous pin was vacuous.
+    expect(
+      css,
+      ".hk-tpl-group-label must take its bottom band from the grammar's token",
+    ).toMatch(
+      /\.hk-tpl-group-label\s*\{[^}]*padding-block-end:\s*var\(--hk-menu-section-label-pad-bottom,/s,
+    );
+    expect(
+      css,
+      ".hk-tpl-group-label must take its weight from the grammar's token with 600 as the fallback",
+    ).toMatch(
+      /\.hk-tpl-group-label\s*\{[^}]*font-weight:\s*var\(--hk-menu-section-label-weight,\s*600\)/s,
+    );
+    expect(
+      scss,
+      "the source must ADOPT the grammar (@include mi.section-label), not restate its values",
+    ).toMatch(/\.hk-tpl-group-label\s*\{[^}]*@include mi\.section-label;/s);
     expect(css).not.toMatch(/\.hk-tpl-group\s*\{[^}]*font-weight/s);
     expect(css).not.toMatch(/\.hk-tpl-group\s*\{[^}]*padding/s);
   });
 
+  it("keeps the label band's declarations to the grammar binding plus the colour hook", () => {
+    // R4 appended `padding: 2px 16px;` after the @include and all five
+    // shipped pins stayed green. EVERY rule whose selector mentions the band
+    // must be EXACTLY the grammar binding plus the one colour line — any
+    // later padding / font-size / font-weight / letter-spacing /
+    // text-transform, and any SECOND .hk-tpl-group-label rule (R5: the old
+    // pin read only the first match), fails.
+    const code = scss
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/^[ \t]*\/\/.*$/gm, "");
+    const rules = [...code.matchAll(/([^{}]*\.hk-tpl-group-label[^{}]*)\{([^{}]*)\}/g)];
+    expect(rules.length, ".hk-tpl-group-label rule(s) found").toBeGreaterThan(0);
+    for (const [, selector, body] of rules) {
+      const declarations = (body ?? "")
+        .split(";")
+        .map((statement) => statement.replace(/\s+/g, " ").trim())
+        .filter(Boolean);
+      expect(
+        declarations,
+        `every .hk-tpl-group-label rule must stay the grammar binding + colour hook (${(selector ?? "").trim()})`,
+      ).toEqual([
+        "@include mi.section-label",
+        "color: var(--hk-menu-section-label-color, var(--hi-color-muted))",
+      ]);
+    }
+  });
+
   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/_menu-item.contract.test.ts

@@ -26,6 +26,127 @@ const grammar = readFileSync(join(here, "_menu-item.scss"), "utf-8");
 const menuTsx = readFileSync(join(here, "HkMenu.tsx"), "utf-8");
 const themeTsx = readFileSync(join(here, "HkThemePanelContent.tsx"), "utf8");
 const adminTokens = readFileSync(join(here, "../styles/admin-tokens.scss"), "utf-8");
+const panelScss = readFileSync(join(here, "HkMenuPanel.scss"), "utf-8");
+
+/** One node of a parsed SCSS tree: a rule/at-rule block, the
+ *  statements directly in its body, and its nested blocks. */
+interface ScssBlock {
+  prelude: string;
+  statements: string[];
+  children: ScssBlock[];
+  parent: ScssBlock | null;
+}
+
+/** Remove comments so the block parser only sees code. */
+function stripScssComments(source: string): string {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/^[ \t]*\/\/.*$/gm, "");
+}
+
+/** Parse an SCSS sheet into its block tree. At-rules are blocks like any
+ *  other (their prelude starts with "@" and is not a selector). */
+function parseScss(source: string): ScssBlock[] {
+  const root: ScssBlock = { prelude: "", statements: [], children: [], parent: null };
+  const stack: ScssBlock[] = [root];
+  let buf = "";
+  for (const ch of source) {
+    if (ch === "{") {
+      const parent = stack[stack.length - 1]!;
+      const block: ScssBlock = { prelude: buf.trim(), statements: [], children: [], parent };
+      parent.children.push(block);
+      stack.push(block);
+      buf = "";
+    } else if (ch === "}") {
+      const block = stack.pop()!;
+      if (buf.trim()) block.statements.push(buf.trim());
+      buf = "";
+    } else if (ch === ";") {
+      if (buf.trim()) stack[stack.length - 1]!.statements.push(buf.trim());
+      buf = "";
+    } else {
+      buf += ch;
+    }
+  }
+  return root.children;
+}
+
+/** Split a selector list on the commas that are NOT inside parentheses. */
+function splitSelectors(prelude: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of prelude) {
+    if (ch === "(") depth += 1;
+    else if (ch === ")") depth = Math.max(0, depth - 1);
+    if (ch === "," && depth === 0) {
+      out.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  out.push(current.trim());
+  return out.filter(Boolean);
+}
+
+/** Resolved selector list of a block: its ancestor chain joined with
+ *  spaces, comma lists expanded (at-rules are not selectors). */
+function resolvedSelectors(block: ScssBlock): string[] {
+  const groups: string[][] = [];
+  for (let cur: ScssBlock | null = block; cur; cur = cur.parent) {
+    if (!cur.prelude || cur.prelude.startsWith("@")) continue;
+    groups.unshift(splitSelectors(cur.prelude));
+  }
+  let resolved = [""];
+  for (const group of groups) {
+    resolved = resolved.flatMap((prefix) =>
+      group.map((sel) => (prefix ? `${prefix} ${sel}` : sel)),
+    );
+  }
+  return resolved;
+}
+
+/** Resolved PARENT-selector prefixes of a block (ancestors only). */
+function parentPrefixes(block: ScssBlock): string[] {
+  const groups: string[][] = [];
+  for (let cur = block.parent; cur; cur = cur.parent) {
+    if (!cur.prelude || cur.prelude.startsWith("@")) continue;
+    groups.unshift(splitSelectors(cur.prelude));
+  }
+  let resolved = [""];
+  for (const group of groups) {
+    resolved = resolved.flatMap((prefix) =>
+      group.map((sel) => (prefix ? `${prefix} ${sel}` : sel)),
+    );
+  }
+  return resolved;
+}
+
+/** Depth-first flatten of a block tree. */
+function flattenBlocks(blocks: ScssBlock[]): ScssBlock[] {
+  return blocks.flatMap((block) => [block, ...flattenBlocks(block.children)]);
+}
+
+/** The px fallback a grammar custom property carries through the shared
+ *  scale: the `4px` in `var(--token, var(--space-4, 4px))`. */
+function pxFallback(body: string, token: string): number {
+  const match = body.match(
+    new RegExp(`var\\(${token},\\s*var\\(--space-\\d+,\\s*(\\d+)px\\)\\)`),
+  );
+  expect(
+    match,
+    `${token} must fall back through a shared --space-* token to px`,
+  ).toBeTruthy();
+  return Number(match![1]);
+}
+
+/** The body of `@mixin <name> { ... }` (single level, mixes are flat). */
+function mixinBody(name: string): string {
+  const match = grammar.match(new RegExp(`@mixin ${name} \\{([^}]*)\\}`));
+  expect(match, `@mixin ${name} must exist in _menu-item.scss`).toBeTruthy();
+  return match![1]!;
+}
 
 describe("menu-item grammar contract", () => {
   it("declares the divider row as a mixin reading the grammar tokens", () => {
@@ -126,4 +247,331 @@ describe("menu-item grammar contract", () => {
     );
     expect(grammar.match(/var\(--hk-menu-item-label-cushion\)/g)?.length).toBe(1);
   });
+
+  it("gives the section caption a bottom-heavy band (never glued to the first row)", () => {
+    // Field report: the caption above a run of rows sat almost flush
+    // against the first row (four hand-rolled bands, 2/4/6/8px, no shared
+    // token). The rhythm is pinned EXACTLY, not merely ordered: a bare
+    // `bottom > top` check lets a top revert (4px → 6px) pass — and the
+    // top band moving back down is the "move UP" half of the user
+    // direction. Pin both numbers, then pin the order.
+    const body = mixinBody("section-label");
+    const top = pxFallback(body, "--hk-menu-section-label-pad-top");
+    const bottom = pxFallback(body, "--hk-menu-section-label-pad-bottom");
+    expect(
+      top,
+      `caption top band is ${top}px; the shipped value is 4px (the band must sit tight/UP under the panel inset)`,
+    ).toBe(4);
+    expect(
+      bottom,
+      `caption bottom band is ${bottom}px; the shipped value is 8px (the clear gap under the caption)`,
+    ).toBe(8);
+    expect(
+      bottom,
+      `caption bottom band (${bottom}px) must be strictly larger than its top band (${top}px) — bottom-heavy rhythm`,
+    ).toBeGreaterThan(top);
+  });
+
+  it("declares the caption's bands as exactly three token declarations", () => {
+    // Presence-based pins survive a LATER override (R3 P7: appending
+    // `padding-inline: 16px; padding-block-end: 2px;` after the tokens
+    // re-created the field defect 4/16/2 while every value pin stayed
+    // green). The padding set must be EXACTLY the three grammar
+    // declarations — a fourth declaration, a bare shorthand or a literal
+    // added later fails here.
+    const body = mixinBody("section-label");
+    const paddingDecls = [...body.matchAll(/\bpadding[\w-]*\s*:[^;]+;/g)].map((match) =>
+      match[0].replace(/\s+/g, " ").trim(),
+    );
+    expect(paddingDecls, "exactly the three grammar padding declarations").toEqual([
+      "padding-block-start: var(--hk-menu-section-label-pad-top, var(--space-4, 4px));",
+      "padding-inline: var(--hk-menu-section-label-pad-x, var(--space-6, 6px));",
+      "padding-block-end: var(--hk-menu-section-label-pad-bottom, var(--space-8, 8px));",
+    ]);
+    expect(
+      body,
+      "no bare padding shorthand (it would override the token bands)",
+    ).not.toMatch(/(^|[;{\s])padding\s*:/);
+    expect(body, "capitalization stays the translator's").not.toContain("text-transform");
+  });
+
+  it("keeps the caption's desktop typography on the grammar tokens", () => {
+    const body = mixinBody("section-label");
+    expect(body).toMatch(
+      /font-size:\s*var\(--hk-menu-section-label-font,\s*var\(--text-2xs,\s*0\.625rem\)\)/,
+    );
+    expect(body).toMatch(
+      /letter-spacing:\s*var\(--hk-menu-section-label-tracking,\s*0\.02em\)/,
+    );
+    expect(body).toMatch(/user-select:\s*none/);
+  });
+
+  it("hangs the caption's inline inset just left of the row content edge", () => {
+    // The caption must NOT read as an indented row: its inline inset is a
+    // hair smaller than the row grammar's --hk-menu-item-pad-x, so it
+    // hugs the section edge slightly left of the leading icon column.
+    // SCOPE of that guarantee: the menu row grammar and HkMenuSection —
+    // a one-off adopter with its own smaller padding (HkTemplateField's
+    // .hk-tpl-row is 4px 8px) lands only a couple of px left, so the
+    // shared token keeps the two bands related, not pixel-identical
+    // everywhere.
+    const body = mixinBody("section-label");
+    expect(
+      body,
+      "caption inline inset must follow the shared --space-6 scale token",
+    ).toMatch(/var\(--hk-menu-section-label-pad-x,\s*var\(--space-6,\s*6px\)\)/);
+    const inline = pxFallback(body, "--hk-menu-section-label-pad-x");
+    const rowPadX = Number(
+      grammar.match(/@mixin item-tokens[\s\S]*?--hk-menu-item-pad-x:\s*(\d+)px/)?.[1],
+    );
+    expect(rowPadX, "row grammar pad-x parsed from item-tokens").toBeGreaterThan(0);
+    expect(
+      inline,
+      `caption inline inset (${inline}px) must stay smaller than the row pad-x (${rowPadX}px)`,
+    ).toBeLessThan(rowPadX);
+  });
+
+  it("registers the caption in every sheet-context list that registers the row band", () => {
+    // Resolved-selector scan, not a top-level block count: for every block
+    // that swaps the ROW sheet tokens we resolve its parent selector
+    // prefix and require an exactly matching caption block that swaps the
+    // CAPTION sheet tokens. A sheet-context list nested inside an existing
+    // block (a third context added under the panel list) therefore fails
+    // even though a depth-0 scan would never see it.
+    const blocks = flattenBlocks(parseScss(stripScssComments(grammar)));
+    const ruleIndex = blocks.flatMap((block) =>
+      resolvedSelectors(block).map((selector) => ({ selector, block })),
+    );
+    const rowSwaps = blocks.filter((block) =>
+      block.statements.some((stmt) => stmt.includes("@include item-sheet-tokens")),
+    );
+    // Extraction sanity (never trust a 0-hit scan): the shipped sheet
+    // lists do swap row tokens somewhere.
+    expect(rowSwaps.length, "row sheet-token swaps found").toBeGreaterThan(0);
+
+    const contexts = new Set<string>();
+    for (const rowSwap of rowSwaps) {
+      const prefixes = parentPrefixes(rowSwap);
+      expect(prefixes.length, "a row token swap has a selector ancestor").toBeGreaterThan(0);
+      for (const prefix of prefixes) {
+        contexts.add(prefix);
+        const captionSelector = `${prefix} .hk-menu-section-label`;
+        const captionBlock = ruleIndex.find(
+          (entry) => entry.selector === captionSelector,
+        )?.block;
+        expect(
+          captionBlock,
+          `sheet context "${prefix}" widens the rows but has no "${captionSelector}" caption block`,
+        ).toBeTruthy();
+        expect(
+          captionBlock!.statements.some((stmt) =>
+            stmt.includes("@include section-label-sheet-tokens"),
+          ),
+          `sheet context "${prefix}" must swap the caption's sheet tokens`,
+        ).toBe(true);
+      }
+    }
+
+    // The shipped sheet surfaces are all covered (dropping one from a
+    // context list fails here, not just for the panel-shaped ones).
+    for (const context of [
+      ".hk-select-sheet-panel",
+      ".hk-popover-panel.hk-is-sheet",
+      ".hk-drawer-panel",
+      ".hk-modal-content",
+    ]) {
+      expect(
+        [...contexts],
+        `sheet surface ${context} must widen the rows (and therefore be checked for a caption)`,
+      ).toContain(context);
+    }
+  });
+
+  it("widens the caption to the touch geometry inside sheets", () => {
+    // Sheet values are the touch band: 6px top / 8px inline / 12px bottom
+    // and the 12px caption font. A drifted sheet entry would leave the
+    // caption at desktop rhythm inside a bottom sheet.
+    const body = mixinBody("section-label-sheet-tokens");
+    expect(body).toMatch(/--hk-menu-section-label-pad-top:\s*var\(--space-6,\s*6px\)/);
+    expect(body).toMatch(/--hk-menu-section-label-pad-x:\s*var\(--space-8,\s*8px\)/);
+    expect(body).toMatch(/--hk-menu-section-label-pad-bottom:\s*var\(--space-12,\s*12px\)/);
+    expect(body).toMatch(/--hk-menu-section-label-font:\s*var\(--text-xs,\s*0\.75rem\)/);
+  });
+
+  it("never uppercases the caption (translators own casing)", () => {
+    // The HkTemplateField rule: caption strings are host i18n strings;
+    // text-transform would fight locales whose casing rules differ.
+    expect(mixinBody("section-label")).not.toContain("text-transform");
+  });
+
+  it("publishes the section caption globally and only binds it to the grammar", () => {
+    // Hosts render .hk-menu-section / .hk-menu-section-label by hand (the
+    // workspace picker does) and cannot import the scss partial, so the
+    // global sheet binds the classes to the grammar mixins. EVERY rule
+    // whose selector mentions the section classes may contain NOTHING but
+    // that binding: an adopter that adds a later padding declaration
+    // (R3 P5) or a scoped duplicate that restates the band (R3 P8) must
+    // fail — a "one global rule" count missed both.
+    const blocks = flattenBlocks(parseScss(stripScssComments(adminTokens)));
+    const sectionRules = blocks.flatMap((block) =>
+      resolvedSelectors(block)
+        .filter((selector) => selector.includes("hk-menu-section"))
+        .map((selector) => ({ selector, block })),
+    );
+    // Extraction sanity (never trust a 0-hit scan): the two global
+    // adopters are found.
+    expect(
+      sectionRules.map((entry) => entry.selector),
+      "the two global section adopters",
+    ).toEqual(expect.arrayContaining([".hk-menu-section", ".hk-menu-section-label"]));
+
+    for (const { selector, block } of sectionRules) {
+      const statements = block.statements.map((stmt) => stmt.replace(/\s+/g, " ").trim());
+      expect(
+        statements,
+        `section rule "${selector}" must bind the grammar only, got: ${statements.join("; ")}`,
+      ).toHaveLength(1);
+      expect(
+        statements[0],
+        `section rule "${selector}" must be an @include of the grammar mixin`,
+      ).toMatch(/^@include mi\.(?:section|section-label)$/);
+      expect(
+        statements.join("; "),
+        `section rule "${selector}" must not declare padding`,
+      ).not.toMatch(/\bpadding/);
+    }
+
+    // The exact binding per class (nothing else, no later override).
+    const statementsFor = (selector: string) => {
+      const block = sectionRules.find((entry) => entry.selector === selector)?.block;
+      expect(block, `the global ${selector} adopter rule`).toBeTruthy();
+      return block!.statements.map((stmt) => stmt.replace(/\s+/g, " ").trim());
+    };
+    expect(statementsFor(".hk-menu-section")).toEqual(["@include mi.section"]);
+    expect(statementsFor(".hk-menu-section-label")).toEqual(["@include mi.section-label"]);
+  });
+
+  it("keeps the grammar's own section rules to the sheet token swap only", () => {
+    // The grammar must not style the band directly: @mixin section-label
+    // owns the metrics (pinned separately), and a direct
+    // .hk-menu-section-label rule is ONLY the sheet-context token swap.
+    // R4 appended (a) an unconditional
+    //   .hk-menu-section-label { @include section-label-sheet-tokens; }
+    // — touch geometry on desktop — and (b) a later
+    //   .hk-menu-section-label { padding-block-end: 2px; }
+    // and every pin stayed green.
+    const blocks = flattenBlocks(parseScss(stripScssComments(grammar)));
+    // Derive the allowlist from the registration lists themselves: only a
+    // context that swaps the ROW sheet tokens may scope a caption rule
+    // (.hk-select-sheet-panel / .hk-popover-panel.hk-is-sheet /
+    // .hk-drawer-panel, plus the narrow mobile .hk-modal-content band).
+    const rowSwaps = blocks.filter((block) =>
+      block.statements.some((stmt) => stmt.includes("@include item-sheet-tokens")),
+    );
+    expect(rowSwaps.length, "row sheet-token swaps found").toBeGreaterThan(0);
+    const sheetContexts = new Set(rowSwaps.flatMap((rowSwap) => parentPrefixes(rowSwap)));
+
+    const sectionBlocks = blocks.flatMap((block) =>
+      resolvedSelectors(block)
+        .filter((selector) => selector.includes(".hk-menu-section"))
+        .map((selector) => ({ selector, block })),
+    );
+    // Extraction sanity (never trust a 0-hit scan): the shipped sheet
+    // entries are found.
+    expect(sectionBlocks.length, "grammar caption sheet-token entries found").toBeGreaterThan(0);
+    for (const { selector, block } of sectionBlocks) {
+      // A grammar rule for the band may only be scoped by a REGISTERED
+      // sheet context: an unconditional rule puts the sheet geometry on
+      // desktop, and any other ancestor (.hk-menu-level, .hk-menu-list)
+      // would be a stray desktop restyle.
+      const scoped = selector.match(/^(.+) \.hk-menu-section-label$/);
+      expect(
+        scoped,
+        `grammar section rule "${selector}" must be sheet-scoped, not unconditional`,
+      ).toBeTruthy();
+      const context = scoped![1]!;
+      expect(
+        [...sheetContexts],
+        `grammar section rule "${selector}" is scoped by "${context}", which is not a registered sheet context`,
+      ).toContain(context);
+      if (context === ".hk-modal-content") {
+        // .hk-modal-content exists at EVERY viewport (HkModal docks via a
+        // media query — the element itself is always there): a sheet swap
+        // scoped by it OUTSIDE the narrow band puts touch geometry on
+        // DESKTOP modals. The legitimate rule is nested in the band, and
+        // resolvedSelectors drops at-rule preludes, so walk the parent
+        // chain for the @media (max-width: 767px) ancestor explicitly.
+        let mobileBand = false;
+        for (let ancestor = block.parent; ancestor; ancestor = ancestor.parent) {
+          if (/^@media\s*\(max-width:\s*767px\)$/.test(ancestor.prelude.trim())) {
+            mobileBand = true;
+            break;
+          }
+        }
+        expect(
+          mobileBand,
+          `grammar section rule "${selector}" scopes .hk-modal-content OUTSIDE the @media (max-width: 767px) band — its sheet geometry would land on desktop modals`,
+        ).toBe(true);
+      }
+      for (const statement of block.statements) {
+        const normalized = statement.replace(/\s+/g, " ").trim();
+        expect(
+          normalized,
+          `grammar section rule "${selector}" may only swap the caption's sheet tokens, got: ${normalized}`,
+        ).toMatch(
+          /^(?:@include section-label-sheet-tokens|--hk-menu-section-label-[\w-]+\s*:\s*[^;]+)$/,
+        );
+      }
+    }
+  });
+
+  it("pins the wrapper to the level rhythm and publishes the list's own rhythm", () => {
+    // Rows declare no margins: the inter-row rhythm IS the parent's flex
+    // gap (.hk-menu-level 2px, .hk-menu-list 4px). A group box therefore
+    // takes over that rhythm, its default must mirror the level's 2px,
+    // and .hk-menu-list must publish its own 4px. The declarations are
+    // collected through the block parser (including the nested `& + &`
+    // block): a regex over the raw mixin text stopped at the first `}`,
+    // so a later `gap: 0;` after the stack rule re-introduced the S1
+    // defect with every pin green (R5 mutation A).
+    const sectionMixin = flattenBlocks(parseScss(stripScssComments(grammar))).find(
+      (block) => block.prelude === "@mixin section",
+    );
+    expect(sectionMixin, "@mixin section must exist").toBeTruthy();
+    const declarations = flattenBlocks([sectionMixin!]).flatMap((block) =>
+      block.statements.map((statement) => statement.replace(/\s+/g, " ").trim()),
+    );
+    expect(
+      declarations,
+      "the wrapper must be a flex box (the gap is inert otherwise)",
+    ).toContain("display: flex");
+    expect(
+      declarations,
+      "the wrapper's children must stack vertically, never in a row",
+    ).toContain("flex-direction: column");
+    // The 6px stack margin belongs to the SIBLING rule (`& + &`), so only
+    // the SECOND and later sections are separated. Moving it into the mixin
+    // body would push 6px above the very first section too.
+    const stackOwners = flattenBlocks([sectionMixin!]).filter((block) =>
+      block.statements.some((statement) =>
+        statement.replace(/\s+/g, " ").trim().startsWith("margin-block-start:"),
+      ),
+    );
+    expect(
+      stackOwners.map((block) => block.prelude),
+      "the stack margin must live in the `& + &` block only",
+    ).toEqual(["& + &"]);
+    const spacingDecls = declarations.filter((declaration) =>
+      /^(?:gap|margin[\w-]*)\s*:/.test(declaration),
+    );
+    expect(spacingDecls, "exactly the wrapper's two spacing declarations").toEqual([
+      "gap: var(--hk-menu-section-gap, var(--space-2, 2px))",
+      "margin-block-start: var(--hk-menu-section-stack, var(--space-6, 6px))",
+    ]);
+    // The one shipped surface with a different row rhythm publishes it.
+    expect(
+      panelScss,
+      ".hk-menu-list must publish its 4px row rhythm for a captioned run",
+    ).toMatch(/\.hk-menu-list\s*\{[^}]*--hk-menu-section-gap:\s*var\(--space-4,\s*4px\)/s);
+  });
 });

package/src/components/_menu-item.scss

@@ -28,10 +28,28 @@
  *     glyph ink high against box-centered icons; a half-pixel down
  *     nudge re-centers the perceived mass (tunable per host).
  *
+ * Section caption (a captioned run of rows):
+ *   The caption band ABOVE a run of rows is its own band, never a row.
+ *   Its block rhythm is deliberately BOTTOM-HEAVY (desktop 4px above /
+ *   8px below, sheets 6/12): the panel already insets the surface above
+ *   the caption, so the caption's own top band stays tight, while the
+ *   bottom band is the separation that must read as "this caption heads
+ *   the rows below, it is not one of them". The section wrapper is where
+ *   the parent's row rhythm moves when rows go behind a group box, so its
+ *   default gap MIRRORS the level rhythm (2px, --hk-menu-section-gap);
+ *   a surface whose rhythm differs publishes that token (HkMenuPanel's
+ *   4px list; a margin-separated consumer list sets 0). Its inline inset
+ *   is a hair SMALLER than the row's --hk-menu-item-pad-x, so the caption
+ *   hangs just left of the rows' leading icon column and reads as a
+ *   section title hugging the edge rather than as an indented row. No
+ *   text-transform: translators own casing (the HkTemplateField rule).
+ *
  * Adoption: `@use "./menu-item" as mi;` then
  *   .your-row { @include mi.item; }
  *   .your-row .your-icon { @include mi.icon; }   // wrap TSX side!
  *   .your-row .your-label { @include mi.label; }
+ *   .your-section { @include mi.section; }
+ *   .your-section-label { @include mi.section-label; }
  * Keep the component's own class names — this file owns metrics and
  * states only, never selectors of the adopting rows.
  */
@@ -65,6 +83,18 @@
   --hk-menu-item-icon-box: 20px;
 }
 
+/* Mobile bottom-sheet geometry for the section caption. The caption is a
+ * sibling BAND, not a row, so it carries its own token names: the
+ * sheet-context lists below register .hk-menu-section-label separately
+ * (rows pick up item-sheet-tokens; a caption inside the same panel must
+ * not be widened by the row mixin's token names). */
+@mixin section-label-sheet-tokens {
+  --hk-menu-section-label-pad-top: var(--space-6, 6px);
+  --hk-menu-section-label-pad-x: var(--space-8, 8px);
+  --hk-menu-section-label-pad-bottom: var(--space-12, 12px);
+  --hk-menu-section-label-font: var(--text-xs, 0.75rem);
+}
+
 /* Sheet context. The tokens are re-declared ON each adopting row, not
  * merely on the panel: a custom property declared on an element always
  * beats an inherited value, and @mixin item declares the desktop set at
@@ -73,8 +103,9 @@
  * Therefore every adopter MUST @include mi.item at a TOP-LEVEL (0,1,0)
  * rule — a nested include (e.g. inside its parent menu selector)
  * compiles to a higher specificity and silently defeats this binding
- * (HkBreadcrumb was caught exactly this way). New row families must
- * also register their class in this list. */
+ * (HkBreadcrumb was caught exactly this way). New row families and band
+ * elements (the divider, the section caption) must also register their
+ * class in this list. */
 .hk-select-sheet-panel,
 .hk-popover-panel.hk-is-sheet,
 .hk-drawer-panel {
@@ -94,6 +125,12 @@
   .hk-tag-dot {
     @include item-sheet-tokens;
   }
+
+  /* The caption band's own sheet entry — same parent list, so every sheet
+   * surface that widens its rows widens their caption too. */
+  .hk-menu-section-label {
+    @include section-label-sheet-tokens;
+  }
 }
 
 /* Modal-hosted rows ride the sheet geometry too: unlike the three
@@ -115,6 +152,12 @@
     .hk-tag-dot {
       @include item-sheet-tokens;
     }
+
+    /* Same registration rule as the panel list above: the caption rides
+     * the modal's sheet geometry without its own media query. */
+    .hk-menu-section-label {
+      @include section-label-sheet-tokens;
+    }
   }
 }
 
@@ -242,3 +285,53 @@
   background: rgb(var(--color-border, 100 100 100) / 18%);
   border: none;
 }
+
+/* ── Section caption band ────────────────────────────────────────────
+ * The small caption ABOVE a run of rows (the workspace picker's
+ * 「临时空间」 band is the field case). Every value is a custom property
+ * with a grammar fallback, exactly like the row tokens, so a host can
+ * restyle one surface without forking the band. The bottom band is the
+ * separation from the first row (bottom-heavy on purpose — see the
+ * header comment); the inline inset hangs just left of the rows' icon
+ * column. The 8px band is NOT the whole caption→row gap: the wrapper's
+ * own gap adds 2px on the level default (4px in .hk-menu-list), so the
+ * rendered separation is 10/12px on desktop and 14px in sheets. Sheet
+ * geometry arrives through the sheet-context lists above, never through
+ * a per-component media query. NO text-transform: translators own
+ * casing (the HkTemplateField rule). */
+@mixin section-label {
+  padding-block-start: var(--hk-menu-section-label-pad-top, var(--space-4, 4px));
+  padding-inline: var(--hk-menu-section-label-pad-x, var(--space-6, 6px));
+  padding-block-end: var(--hk-menu-section-label-pad-bottom, var(--space-8, 8px));
+  font-size: var(--hk-menu-section-label-font, var(--text-2xs, 0.625rem));
+  font-weight: var(--hk-menu-section-label-weight, 600);
+  letter-spacing: var(--hk-menu-section-label-tracking, 0.02em);
+  color: var(--hk-menu-section-label-color, rgb(var(--color-muted)));
+  user-select: none;
+}
+
+/* ── Section wrapper ─────────────────────────────────────────────────
+ * The role="group" box HkMenuSection renders: one caption plus its rows.
+ * Rows declare no margins — the inter-row rhythm is the parent's flex gap
+ * (.hk-menu-level 2px, .hk-menu-list 4px) — so a group box is where that
+ * rhythm must move. The default --hk-menu-section-gap therefore MIRRORS
+ * the level rhythm (2px), which keeps an unconfigured surface correct;
+ * every surface whose rhythm differs publishes the token: .hk-menu-list
+ * sets 4px, and a consumer list that separates rows with margins instead
+ * sets 0 and keeps its margins (those still apply inside the wrapper).
+ * Stacked sections take a 6px stack margin so two captioned runs read as
+ * two groups, not one long list. The wrapper stays chrome-free — the
+ * caption owns the band.
+ *
+ * MUST be included at a TOP-LEVEL (0,1,0) rule, like @mixin item: the
+ * `& + &` stack rule compiles to a broken descendant selector when the
+ * mixin is nested inside a parent menu selector. */
+@mixin section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--hk-menu-section-gap, var(--space-2, 2px));
+
+  & + & {
+    margin-block-start: var(--hk-menu-section-stack, var(--space-6, 6px));
+  }
+}

package/src/index.ts

@@ -718,6 +718,7 @@ export { default as HkContextMenuProvider } from "./components/HkContextMenuProv
 export { default as HkMenuPanel } from "./components/HkMenuPanel";
 export { default as HkMenuActionItem } from "./components/HkMenuActionItem";
 export { default as HkMenuIdentityItem } from "./components/HkMenuIdentityItem";
+export { default as HkMenuSection } from "./components/HkMenuSection";
 export { default as HkTagDotRow } from "./components/HkTagDotRow";
 export { default as HkRowActions } from "./components/HkRowActions";
 export { default as HkPopupSelect } from "./components/HkPopupSelect";

package/src/styles/admin-tokens.scss

@@ -790,6 +790,23 @@
   }
 }
 
+/* The section caption and its group wrapper (hikari _menu-item.scss
+ * @mixin section / @mixin section-label): the small band above a run of
+ * rows, e.g. 「临时空间」 in the workspace picker, plus the role="group"
+ * wrapper HkMenuSection renders. Declared globally here because host apps
+ * render these classes by HAND (the workspace picker's own markup) and
+ * cannot import the scss partial — the grammar (and every metric
+ * fallback) lives in _menu-item.scss. The caption's SHEET geometry rides
+ * the grammar's sheet-context lists, so it must NOT be re-declared here;
+ * this file only binds the class names to the grammar. */
+.hk-menu-section {
+  @include mi.section;
+}
+
+.hk-menu-section-label {
+  @include mi.section-label;
+}
+
 /* ── User identity header (shared) ─ */
 /* One identity block for every account surface — the admin user
    dropdown's header, a mobile drawer's user panel footer — so all