@celestia-island/hikari 0.55.260 → 0.55.262

package/package.json

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

package/src/components/HkDonutChart.test.tsx

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from "vitest";
-import { createApp, h } from "vue";
+import { createApp, h, nextTick, ref } from "vue";
 
 import HkDonutChart from "./HkDonutChart";
 import type { HkDonutEntry } from "./donutGeometry";
@@ -80,6 +80,24 @@ describe("HkDonutChart", () => {
     expect(empty.querySelector(".hk-donut--empty")).toBeTruthy();
   });
 
+  it("clears a dead hover key when the entries swap under a held pointer", async () => {
+    // The wowsp lesson: the hovered element can unmount without firing
+    // mouseleave; without the reset every surviving slice would stay
+    // stuck at is-dim under the dead key.
+    const entriesRef = ref(ENTRIES);
+    const el = mount(h(() => <HkDonutChart entries={entriesRef.value} />));
+    const slices = [...el.querySelectorAll(".hk-donut__slice")];
+    slices[0]!.dispatchEvent(new MouseEvent("mouseenter"));
+    await nextTick();
+    expect(slices[1]!.className).toContain("is-dim");
+    entriesRef.value = ENTRIES.slice(0, 1);
+    await nextTick();
+    const after = [...el.querySelectorAll(".hk-donut__slice")];
+    expect(after).toHaveLength(1);
+    expect(after[0]!.className).not.toContain("is-dim");
+    expect(after[0]!.className).not.toContain("is-hot");
+  });
+
   it("renders the legendIcon slot's glyph in place of the text label", () => {
     const el = mount(
       <HkDonutChart

package/src/components/HkDonutChart.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, ref, type PropType } from "vue";
+import { computed, defineComponent, ref, watch, type PropType } from "vue";
 
 import {
   chunkLegendItems,
@@ -67,6 +67,20 @@ export default defineComponent({
   },
   setup(props, { emit, slots }) {
     const hovered = ref<string | null>(null);
+    // A hover key lives on a DOM element; when the entries swap under a
+    // held pointer, the hovered element can unmount WITHOUT firing
+    // mouseleave (browsers skip removed nodes) — a dead key would dim
+    // the whole block until the pointer deliberately re-entered it.
+    // Resetting on every entries repaint costs nothing (a resting
+    // pointer only ever clears nulls) and can never stick. Lesson
+    // upstreamed from wowsp's ShipDistCharts, whose own test pins it.
+    watch(
+      () => props.entries,
+      () => {
+        hovered.value = null;
+      },
+      { deep: true },
+    );
 
     const slices = computed<HkDonutSlice[]>(() =>
       donutSlices(

package/src/components/HkMenu.rail.test.tsx

@@ -200,6 +200,11 @@ describe("HkMenu sidebar icon rail", () => {
 
     const children = c.querySelector(".hk-menu-sidebar-rail-children");
     expect(children, "the open group lists its children in the rail").toBeTruthy();
+    // The rail wrapper wears the SHARED children class too: the expanded
+    // sidebar's 2px margin step reaches the rail through it — that class
+    // union IS the vertical-invariance carrier (2026-10-31). A rail-only
+    // wrapper would re-introduce the per-density step.
+    expect(children!.classList.contains("hk-menu-sidebar-children")).toBe(true);
     const childRows = railRows(children!);
     expect(childRows.map((row) => row.getAttribute("aria-label"))).toEqual(["Users", "Audit log"]);
     for (const row of childRows) {
@@ -238,6 +243,15 @@ describe("HkMenu sidebar icon rail", () => {
     expect(c.querySelector(".hk-menu-sidebar-group[data-open]"), "the group is still open").toBeTruthy();
     expect(groupRows(c)[0]!.getAttribute("aria-expanded")).toBe("true");
     expect(c.textContent).toContain("Users");
+    // TWO-SIDED class-union pin: the EXPANDED wrapper must wear the
+    // shared class too. Dropping it there removes the 2px step from the
+    // expanded sidebar — rows below an open group would move on every
+    // flip, the exact drift this contract kills (a rail-only pin let
+    // that through).
+    expect(
+      c.querySelector(".hk-menu-sidebar-group[data-open] > .hk-menu-sidebar-children"),
+      "the expanded children wrapper keeps the shared step class",
+    ).toBeTruthy();
 
     // Reverse direction: collapse it from the expanded sidebar, flip
     // back into the rail — it must stay collapsed (no resurrection).
@@ -508,10 +522,65 @@ describe("HkMenu rail styles (compiled sheet contracts)", () => {
     expect(row).toContain("justify-content: center");
   });
 
-  it("keeps open group children in the same one-column rhythm (no indent step)", () => {
+  it("keeps open group children at the EXPANDED vertical step (no rail re-step)", () => {
+    // Vertical rhythm is density-invariant (2026-10-31 user direction:
+    // the collapse toggle must not move rows). The rail children wrapper
+    // therefore carries NO margin rule of its own — the expanded
+    // sidebar's 2px step from the shared .hk-menu-sidebar-children rule
+    // applies in the rail too, and the wrapper stays width-only (its
+    // selector survives only inside the comma-grouped width rule, which
+    // the exact-line ruleBody skips — the null here asserts no
+    // STANDALONE rail-children rule came back).
     const children = ruleBody(".hk-menu-sidebar[data-collapsed] .hk-menu-sidebar-rail-children");
-    expect(children, "the rail children rule exists").not.toBeNull();
-    expect(children).toContain("margin-top: 0");
+    expect(children, "a standalone rail-children rule re-stepped the margin").toBeNull();
+    const shared = ruleBody(".hk-menu-sidebar-children");
+    expect(shared, "the shared children rule exists").not.toBeNull();
+    expect(shared).toContain("margin-top: var(--space-2, 2px)");
+    // A rule whose selector is EXACTLY a rail wrapper class — top-level,
+    // outside any density dress — would restyle the rail children while
+    // evading every dress-keyed scan below (the compiled chunk then
+    // carries no carrier text). The wrappers' geometry must come from
+    // the shared rules alone.
+    expect(css.match(/^\s*\.hk-menu-sidebar-rail-(?:children|group)\s*\{/gm)).toBeNull();
+  });
+
+  it("the rail dress authors no vertical rhythm in any spelling", () => {
+    // The stronger form of the contract above, so a re-step cannot hide
+    // inside a comma-grouped selector the per-selector ruleBody skips
+    // AND cannot return through alternate spellings or sister metrics:
+    // every rule of the density dress is scanned and banned for ANY
+    // margin/padding spelling that reaches a block edge — the shorthand
+    // (it sets the block side too: the historical `margin-top: 0`
+    // regression spelled `margin: 0` evaded a longhand-only scan) and
+    // every vertical longhand, top AND bottom — plus the block-FLOW
+    // metrics that move rows just the same (gap/row-gap/height/
+    // min-height/max-height: a `gap:` inside the comma-grouped width
+    // rule once passed a margin/padding-only scan). Horizontal-only
+    // tracks (margin-inline*, padding-inline*) stay legal; absolute
+    // INSETS (the caret corner's inset-block-end) are flow-neutral
+    // decoration and stay legal. A rail band that truly needs a
+    // different block metric must move the BASE rule for BOTH densities.
+    // Keyed to BOTH carrier spellings so a future [data-rail]-keyed
+    // carrier in this sheet cannot slip the scan.
+    const dressRules = css
+      .split("}")
+      .filter(
+        (rule) =>
+          rule.includes(".hk-menu-sidebar[data-collapsed]") ||
+          rule.includes(".hk-menu-sidebar[data-rail]"),
+      );
+    expect(dressRules.length, "the rail dress rules exist").toBeGreaterThan(3);
+    for (const rule of dressRules) {
+      expect(rule, `vertical margin in the rail dress: ${rule}`).not.toMatch(
+        /\bmargin(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:/,
+      );
+      expect(rule, `vertical padding in the rail dress: ${rule}`).not.toMatch(
+        /\bpadding(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:/,
+      );
+      expect(rule, `block-flow metric in the rail dress: ${rule}`).not.toMatch(
+        /\b(?:gap|row-gap|height|min-height|max-height)\s*:/,
+      );
+    }
   });
 
   it("mirrors the rail caret in RTL with the scaleX convention, never a rotate", () => {

package/src/components/HkMenu.scss

@@ -193,18 +193,18 @@
     font-weight: 600;
   }
 
-  /* Rail groups keep the rail rhythm at every depth: the children
-   * wrapper spends the rail's own row gap, with no margin step above
-   * the first child and never an indent. */
+  /* Rail groups keep the ONE-COLUMN rhythm at every depth: width-only,
+   * never an indent. The children wrapper deliberately carries NO
+   * margin override of its own — the expanded sidebar's 2px step (the
+   * shared .hk-menu-sidebar-children rule above) applies in the rail
+   * too, because vertical rhythm is density-invariant (2026-10-31 user
+   * direction): a rail-specific step would move every row below an open
+   * group on each collapse/expand flip. */
   .hk-menu-sidebar-rail-group,
   .hk-menu-sidebar-rail-children {
     width: 100%;
   }
 
-  .hk-menu-sidebar-rail-children {
-    margin-top: 0;
-  }
-
   /* Disclosure ink, at the same secondary weight as the expanded
    * sidebar's .hk-menu-more. The placeholder form lives in the glyph
    * cell and centers like every other row icon. */

package/src/components/HkSidebar.scss

@@ -86,23 +86,27 @@
  * kit (HkSidebarRailSwap) — the generation's [data-rail] flips with the
  * swap key, so the leaving generation keeps its dress for the dissolve
  * while the entering one takes the new one. A root-level attr cannot do
- * that: it would restyle the frozen leaving copy mid-dissolve. */
+ * that: it would restyle the frozen leaving copy mid-dissolve.
+ *
+ * VERTICAL RHYTHM IS DENSITY-INVARIANT (2026-10-31 user direction: the
+ * collapse toggle must not move rows). The dress authors INLINE geometry
+ * only — the header/footer rules below narrow the horizontal padding for
+ * the rail column and recentre the header, while every BLOCK metric (the
+ * header's 16px band, the body's 20px leading air + scroll tail, the
+ * footer's 16px band) stays with the base rules alone. Shrinking the
+ * collapsed paddings used to lift the whole nav by up to two paddings'
+ * worth on every flip; a band that needs a different vertical dress in
+ * rail mode would have to move the base values for BOTH densities, never
+ * add a per-density block padding. */
 .hk-sidebar[data-collapsed],
 .hk-sidebar-rail-generation[data-rail] {
   .hk-sidebar-header {
     justify-content: center;
-    padding: var(--space-12) var(--space-8);
-  }
-
-  .hk-sidebar-body {
-    /* Same end-cap as the expanded body — collapsed rows are icon-only
-     * but the tail's job (announcing the end of the scroll range) is
-     * identical, so only the leading air shrinks here. */
-    padding-block: var(--space-12) var(--hk-sidebar-scroll-tail);
+    padding: var(--space-16) var(--space-8);
   }
 
   .hk-sidebar-footer {
-    padding: var(--space-12) var(--space-8);
+    padding: var(--space-16) var(--space-8);
   }
 }
 

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

@@ -74,16 +74,61 @@ describe("HkSidebar scroll end-cap", () => {
     expect(body).not.toMatch(/padding-block:[^;]*--space-4/);
   });
 
-  it("keeps the same tail on the collapsed body", () => {
-    // The density dress is keyed off EITHER carrier — the legacy root's
-    // [data-collapsed] or the rail swap generation's [data-rail] (the
-    // generation attr freezes on the leaving copy for the dissolve, a
-    // root attr cannot). ruleBody needs the arm its brace follows, so the
-    // legacy arm is asserted as text and the body read from the group.
-    expect(css).toContain(".hk-sidebar[data-collapsed] .hk-sidebar-body");
-    const body = ruleBody(css, ".hk-sidebar-rail-generation[data-rail] .hk-sidebar-body");
-    expect(body, "the collapsed body rule exists (grouped density carriers)").not.toBeNull();
-    expect(body).toContain("padding-block: var(--space-12) var(--hk-sidebar-scroll-tail)");
+  it("the density dress keeps every vertical metric at the expanded value", () => {
+    // Vertical rhythm is density-invariant (2026-10-31 user direction:
+    // the collapse toggle must not move rows). The body therefore has no
+    // density rule AT ALL — the leading air AND the scroll tail ride the
+    // single base rule in both densities — and the header/footer dress
+    // rules keep the expanded BLOCK padding, narrowing only the inline
+    // track for the rail column.
+    expect(css).not.toContain(".hk-sidebar[data-collapsed] .hk-sidebar-body");
+    expect(css).not.toContain(".hk-sidebar-rail-generation[data-rail] .hk-sidebar-body");
+    // The two carrier literals above are the compiled spellings; a brand
+    // NEW carrier (a third density hook) is a new dress and must re-run
+    // this contract — not mechanically foreseeable here.
+    // ruleBody needs the arm its brace follows; the dress compiles to one
+    // comma-grouped rule per band, so the generation arm is the one the
+    // helper can read (the legacy arm shares its body).
+    const header = ruleBody(css, ".hk-sidebar-rail-generation[data-rail] .hk-sidebar-header");
+    expect(header, "the collapsed header rule exists (grouped density carriers)").not.toBeNull();
+    expect(header).toContain("padding: var(--space-16) var(--space-8)");
+    const footer = ruleBody(css, ".hk-sidebar-rail-generation[data-rail] .hk-sidebar-footer");
+    expect(footer, "the collapsed footer rule exists (grouped density carriers)").not.toBeNull();
+    expect(footer).toContain("padding: var(--space-16) var(--space-8)");
+    // The stronger, spelling-proof form (whole-dress scan): EVERY
+    // padding declaration in ANY dress rule must be EXACTLY the expanded
+    // two-track shorthand — exact, not a prefix: a three-track spelling
+    // (`padding: var(--space-16) var(--space-8) var(--space-12)`) drifts
+    // the block END past a block-start-only check, and a longhand
+    // (`padding-block-start:`) hides from a shorthand-only one; both
+    // green-holed earlier rounds. Physical `bottom` longhands are banned
+    // beside the logical ones. Horizontal-only tracks (padding-inline*)
+    // cannot match the value pin and are rejected the same way; a band
+    // that truly needs different block metrics must move the BASE rule
+    // for BOTH densities. Margins are banned outright — the bands
+    // separate by their paddings alone — and so are the block-FLOW
+    // metrics that move rows just the same (gap/row-gap/height/
+    // min-height/max-height).
+    const dressRules = css
+      .split("}")
+      .filter((rule) => rule.includes("[data-collapsed]") || rule.includes("[data-rail]"));
+    expect(dressRules.length, "the density dress rules exist").toBeGreaterThan(1);
+    for (const rule of dressRules) {
+      for (const decl of rule.matchAll(
+        /\bpadding(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:[^;}]*/g,
+      )) {
+        expect(
+          decl[0].trim(),
+          `a dress padding is not the expanded two-track shorthand: ${decl[0]}`,
+        ).toBe("padding: var(--space-16) var(--space-8)");
+      }
+      expect(rule, `a margin crept into the dress: ${rule}`).not.toMatch(
+        /\bmargin(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:/,
+      );
+      expect(rule, `block-flow metric in the dress: ${rule}`).not.toMatch(
+        /\b(?:gap|row-gap|height|min-height|max-height)\s*:/,
+      );
+    }
   });
 
   it("reads the tail fallback from the scss source, not a drifted literal", () => {

package/src/components/HkSidebar.tsx

@@ -155,11 +155,12 @@ export default defineComponent({
     // dissolve), which is where the position is read from — an event-only
     // save would miss programmatic scrolls (no `scroll` event fires for
     // them), so the read happens on the ref hand-off itself and the
-    // onScroll below merely keeps the value fresh between flips. Raw
-    // scrollTop is an approximation across dresses (rail rows and full
-    // rows have different heights) — an exact restore would need an
-    // item-keyed anchor, not worth it for a nav list; the browser clamps
-    // any overshoot.
+    // onScroll below merely keeps the value fresh between flips. For
+    // library-owned rows the raw restore is EXACT since the vertical
+    // rhythm became density-invariant (2026-10-31: both dresses render
+    // the same band paddings and row heights, so y offsets match); the
+    // browser clamps any overshoot a host's density-dependent content
+    // could still produce.
     const savedScrollTop = ref(0);
     const onBodyScroll = (e: Event): void => {
       savedScrollTop.value = (e.currentTarget as HTMLElement).scrollTop;