@celestia-island/hikari 0.55.246 → 0.55.247

package/package.json

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

package/src/components/HkMenu.scss

@@ -23,6 +23,25 @@
   display: block;
 }
 
+/* The FOOT band is an action band, not a run of selectable rows — the
+ * "add workspace" button under the picker's options, a context menu's
+ * custom tail. It reads as its own band only when it is SEPARATED at the
+ * divider's DESKTOP grade (6px; the divider itself widens to 10px inside
+ * sheets, but this band's separation is a layout rhythm BETWEEN bands,
+ * not row geometry, so it stays 6px in both token sets), never at the
+ * 2px row gap: consumers used to hand that separation themselves as
+ * wrapper padding, which is exactly the drift that padded the wrapper's
+ * rows to a WIDER highlight than the selection rows above (2026-10-31
+ * field report: the workspace picker's 「添加工作区」 ran ~12px wider
+ * than the 「个人空间」 row). The band owns the separation now —
+ * consumers must NOT pad the wrapper (see _menu-item.scss, the band
+ * width invariant). Head/extra stay bare DOM hooks: identity blocks own
+ * their rhythm (the .s-user-header pins), and the theme menu's extra
+ * slot rides the plain row rhythm. */
+.hk-menu-slot--foot {
+  margin-block-start: var(--hk-menu-foot-gap, var(--space-6, 6px));
+}
+
 .hk-menu-flag {
   flex-shrink: 0;
   font-size: var(--text-base);

package/src/components/HkMenu.tsx

@@ -607,7 +607,16 @@ export default defineComponent({
      *  and every consumer hand-rolled its own spacing (PlatformSwitcher
      *  shipped a drifted divider that way). The wrapper renders only
      *  when the slot has content: an empty one would cost a phantom
-     *  flex gap in headerless surfaces. */
+     *  flex gap in headerless surfaces.
+     *
+     *  Band geometry lives in HkMenu.scss, never in consumers: the foot
+     *  band carries the divider-grade top separation there (`.hk-menu-slot--foot`),
+     *  so a consumer adds rows, not padding. A custom default-slot row
+     *  run CARRIES the geometry-neutral `.hk-menu-body` band class in the
+     *  HOST's own markup (this component does not wrap the slot — the
+     *  global rule lives in admin-tokens, _menu-item.scss @mixin body —
+     *  the WIDTH invariant: wrapper padding insets only its own rows and
+     *  breaks highlight parity with the foot action band). */
     function slotWrapper(kind: "head" | "foot" | "extra", nodes: VNode[]): VNode | null {
       return nodes.length ? (
         <div class={`hk-menu-slot hk-menu-slot--${kind}`}>{nodes}</div>

package/src/components/_menu-item.contract.test.ts

@@ -14,7 +14,14 @@
  *     max-width block (HkModal docks via media query, not a class);
  *   - HkMenu's header/footer slots and HkThemeToggle's menu-extra ride
  *     the .hk-menu-slot wrapper instead of splicing raw vnodes into the
- *     level (PlatformSwitcher-class drift lived exactly there).
+ *     level (PlatformSwitcher-class drift lived exactly there);
+ *   - BAND wrappers (slots, .hk-menu-body, .hk-menu-section) stay
+ *     geometry-neutral — the surface's inset is the one horizontal inset
+ *     a row receives, so every row family's highlight reads the same
+ *     width in one panel (2026-10-31: the workspace picker's padded body
+ *     wrapper made 「添加工作区」 run ~12px wider than the selected row);
+ *   - the foot action band owns its divider-grade top separation
+ *     (HkMenu.scss), consumers pad nothing.
  */
 import { describe, expect, it } from "vitest";
 import { readFileSync } from "node:fs";
@@ -24,6 +31,7 @@ import { fileURLToPath } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
 const grammar = readFileSync(join(here, "_menu-item.scss"), "utf-8");
 const menuTsx = readFileSync(join(here, "HkMenu.tsx"), "utf-8");
+const menuScss = readFileSync(join(here, "HkMenu.scss"), "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");
@@ -576,4 +584,131 @@ describe("menu-item grammar contract", () => {
       ".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);
   });
+
+  it("declares the consumer body band as exactly two neutral declarations", () => {
+    // The WIDTH invariant (2026-10-31 field report): a padded band insets
+    // only ITS rows, so their highlight stops matching the foot action
+    // band's — the workspace picker's 「添加工作区」 ran ~12px wider than
+    // the 「个人空间」 row. @mixin body is therefore pinned to EXACTLY the
+    // two neutral declarations; a padding/margin/border sneaking in fails
+    // here even though every value pin elsewhere stays green.
+    const body = mixinBody("body");
+    const decls = body
+      .split(";")
+      .map((stmt) => stmt.replace(/\s+/g, " ").trim())
+      .filter(Boolean);
+    expect(decls, "@mixin body is display:block + min-width:0, nothing else").toEqual([
+      "display: block",
+      "min-width: 0",
+    ]);
+    expect(body, "the body band never pads").not.toMatch(/\bpadding/);
+    expect(body, "the body band never margins").not.toMatch(/\bmargin/);
+    expect(body, "the body band never draws chrome").not.toMatch(/\bborder/);
+  });
+
+  it("publishes the body band globally and only binds it to the grammar", () => {
+    // Hosts render .hk-menu-body by hand beside their own class (the
+    // workspace picker does) and cannot import the scss partial — same
+    // rule shape as the section band above: the global sheet BINDS the
+    // class to @mixin body, every rule mentioning the class carries
+    // nothing but that binding.
+    const blocks = flattenBlocks(parseScss(stripScssComments(adminTokens)));
+    const bodyRules = blocks.flatMap((block) =>
+      resolvedSelectors(block)
+        .filter((selector) => selector.includes("hk-menu-body"))
+        .map((selector) => ({ selector, block })),
+    );
+    expect(
+      bodyRules.map((entry) => entry.selector),
+      "the one global body adopter",
+    ).toContain(".hk-menu-body");
+    for (const { selector, block } of bodyRules) {
+      // The binding must be TOP-LEVEL: resolvedSelectors drops at-rule
+      // preludes, so a media-scoped duplicate would resolve to the same
+      // selector string here — walk the parent chain explicitly and fail
+      // on any at-rule ancestor (the modal-sheet test sets the precedent).
+      for (let cur = block.parent; cur; cur = cur.parent) {
+        expect(
+          cur.prelude.startsWith("@"),
+          `the body binding for "${selector}" must be a top-level rule, found inside at-rule "${cur.prelude}" (a scoped binding is not the global contract)`,
+        ).toBe(false);
+      }
+      const statements = block.statements.map((stmt) => stmt.replace(/\s+/g, " ").trim());
+      expect(statements, `body rule "${selector}" binds the grammar only`).toEqual([
+        "@include mi.body",
+      ]);
+    }
+  });
+
+  it("keeps every band wrapper geometry-neutral (rows own the level width)", () => {
+    // Every rule in the sheets that style band classes today — the
+    // grammar, HkMenu.scss and admin-tokens (a repo-wide grep is the
+    // reviewer's periodic check that this list is still the whole world) —
+    // must declare NO padding for a BAND class: the slot hooks, the
+    // consumer body band, the section wrapper. The surface's inset is the
+    // one horizontal inset a row receives; a band that pads itself
+    // re-creates the field defect with its own rows reading wider than
+    // the neighbours. Comments stripped, block-parsed, resolved selectors
+    // (a context-scoped band rule fails here too).
+    const blocks = [
+      ...flattenBlocks(parseScss(stripScssComments(grammar))),
+      ...flattenBlocks(parseScss(stripScssComments(menuScss))),
+      ...flattenBlocks(parseScss(stripScssComments(adminTokens))),
+    ];
+    const isBandSelector = (selector: string) =>
+      selector.includes("hk-menu-slot") ||
+      selector.includes("hk-menu-body") ||
+      (/hk-menu-section(?!-label)/.test(selector));
+    const bandRules = blocks.flatMap((block) =>
+      resolvedSelectors(block)
+        .filter(isBandSelector)
+        .map((selector) => ({ selector, block })),
+    );
+    // Extraction sanity (never trust a 0-hit scan): the shipped bands are
+    // all found — slot hooks, the body band, the section wrapper.
+    const found = new Set(bandRules.map((entry) => entry.selector));
+    expect(found.has(".hk-menu-slot"), ".hk-menu-slot band found").toBe(true);
+    expect(found.has(".hk-menu-slot--foot"), ".hk-menu-slot--foot band found").toBe(true);
+    expect(found.has(".hk-menu-body"), ".hk-menu-body band found").toBe(true);
+    expect(found.has(".hk-menu-section"), ".hk-menu-section band found").toBe(true);
+    for (const { selector, block } of bandRules) {
+      const padding = block.statements.filter((stmt) =>
+        /(^|[\s;])padding/.test(stmt.replace(/\s+/g, " ").trim()),
+      );
+      expect(padding, `band rule "${selector}" must not pad itself`).toEqual([]);
+    }
+  });
+
+  it("separates the foot action band at the divider grade, band-owned", () => {
+    // The foot band is an ACTION band (the picker's "add workspace"), not
+    // a run of selectable rows — its separation from the list is the
+    // divider's 6px grade, owned by the band (consumers pad nothing).
+    // Pinned EXACTLY so a later restyle cannot silently retune it; head
+    // and extra stay geometry-neutral (no symmetric creep: identity
+    // blocks own their rhythm via the .s-user-header pins).
+    const blocks = flattenBlocks(parseScss(stripScssComments(menuScss)));
+    const foot = blocks.find((block) => block.prelude.trim() === ".hk-menu-slot--foot");
+    expect(foot, ".hk-menu-slot--foot rule lives in HkMenu.scss").toBeTruthy();
+    const decls = foot!.statements.map((stmt) =>
+      stmt.replace(/\s+/g, " ").trim().replace(/;$/, ""),
+    );
+    expect(decls, "the foot band carries exactly its top separation").toEqual([
+      "margin-block-start: var(--hk-menu-foot-gap, var(--space-6, 6px))",
+    ]);
+    // Head/extra stay BARE DOM hooks — no rhythm rules may exist for them
+    // at all (not merely margin-free ones): the identity blocks own their
+    // rhythm through the .s-user-header pins, and the theme menu's extra
+    // slot rides the plain row rhythm. A rule appearing here at all is
+    // the symmetric-creep attempt, so its EXISTENCE fails — a
+    // margin-free-but-present rule would still be a forked band.
+    for (const kind of ["--head", "--extra"]) {
+      const band = blocks.find((block) =>
+        resolvedSelectors(block).includes(`.hk-menu-slot${kind}`),
+      );
+      expect(
+        band,
+        `the ${kind} band must stay a bare DOM hook with no rule of its own (its rhythm is owned elsewhere by design)`,
+      ).toBeUndefined();
+    }
+  });
 });

package/src/components/_menu-item.scss

@@ -44,12 +44,34 @@
  *   section title hugging the edge rather than as an indented row. No
  *   text-transform: translators own casing (the HkTemplateField rule).
  *
+ * Band taxonomy and the WIDTH invariant (2026-10-31):
+ *   A menu level holds two kinds of children. ROWS — selectable items,
+ *   custom rich rows, action buttons — all speak @mixin item: each spans
+ *   the level's content box edge to edge, so its hover/active wash is
+ *   that full box and every highlight in one panel reads the same width.
+ *   BANDS — the wrappers around runs of rows — must stay GEOMETRY-NEUTRAL:
+ *   zero padding of their own. The surface's inset (the popout's 8px, the
+ *   sheet list's 16px, HkMenuPanel's --hk-menu-panel-inset) is the ONE
+ *   horizontal inset a row ever receives. A band that pads itself insets
+ *   only ITS rows, and they stop lining up with the rows outside it: the
+ *   foot action band's highlight then reads wider than the selection rows
+ *   above it (2026-10-31 field report: the workspace picker's
+ *   「添加工作区」 ran ~12px wider than the 「个人空间」 row because the
+ *   consumer body wrapper carried a 6px hand pad the foot slot did not).
+ *   The band homes are: .hk-menu-slot--head/--foot/--extra (HkMenu's slot
+ *   bands), .hk-menu-section (a captioned run), .hk-menu-body (a
+ *   consumer-rendered run — @mixin body). Vertical rhythm BETWEEN bands
+ *   is band-owned, never wrapper-padding-owned: the foot band carries its
+ *   divider-grade top separation in HkMenu.scss, the section grammar owns
+ *   its caption bands here.
+ *
  * 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; }
+ *   .your-body { @include mi.body; }             // custom row-run band
  * Keep the component's own class names — this file owns metrics and
  * states only, never selectors of the adopting rows.
  */
@@ -336,3 +358,24 @@
     margin-block-start: var(--hk-menu-section-stack, var(--space-6, 6px));
   }
 }
+
+/* ── Consumer body band ──────────────────────────────────────────────
+ * The wrapper for a consumer-rendered run of rows inside a menu level —
+ * the workspace picker's custom two-line rows, a menu body of rich rows
+ * the flat HkMenuItem model cannot express. The WIDTH invariant (see the
+ * header's band taxonomy) makes this band GEOMETRY-NEUTRAL: exactly two
+ * declarations, no padding, ever. The surface's inset is the one inset
+ * the rows inside receive, so they line up edge-for-edge with the foot
+ * action band and every other row family in the same panel (the
+ * 2026-10-31 field report shipped as a padded consumer wrapper whose
+ * rows ran ~12px wider than the foot band's highlight). A host keeps its
+ * own class beside .hk-menu-body for tokens and width floors (e.g. the
+ * picker's min-width + caption tokens) — those are content decisions;
+ * horizontal insets are not.
+ *
+ * Not a row: it carries no row tokens, so it needs NO entry in the
+ * sheet-context lists — the rows INSIDE it register themselves. */
+@mixin body {
+  display: block;
+  min-width: 0;
+}

package/src/styles/admin-tokens.scss

@@ -808,6 +808,19 @@
   @include mi.section-label;
 }
 
+/* The consumer body band (hikari _menu-item.scss @mixin body): the
+ * geometry-neutral wrapper for a host-rendered run of rows inside a menu
+ * level. Same hand-rendered-host reason as the section band above — the
+ * workspace picker wraps its custom rows in .hk-menu-body and cannot
+ * import the partial. The band is TWO neutral declarations by contract
+ * (the WIDTH invariant: the surface's inset is the only horizontal inset
+ * a row receives, so rows here line up edge-for-edge with the foot
+ * action band); a host's own class beside it carries the content
+ * decisions (min-width floors, caption tokens), never padding. */
+.hk-menu-body {
+  @include mi.body;
+}
+
 /* ── 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