@celestia-island/hikari 0.55.243 → 0.55.245

package/package.json

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

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

@@ -33,6 +33,7 @@ vi.mock("@celestia-island/hikari", async (importOriginal) => {
 
 import { HkFaceShell } from "./HkFaceShell";
 import { HkAdminShell } from "./HkAdminShell";
+import { provideMenuGroupState } from "../composables/useMenuGroupState";
 import HkMenu, { type HkMenuItem } from "./HkMenu";
 
 /**
@@ -722,6 +723,73 @@ async function settle(container: HTMLElement, key: "rail" | "full"): Promise<HTM
   return generation(container, key);
 }
 
+describe("rail group fold — a host that OWNS the slot provides the store", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("carries the fold through a rail -> peek flip (chest's AdminLayout shape)", async () => {
+    // chest defines the shell's sidebar slot from AdminLayout, so the slot
+    // content's component PARENT is AdminLayout — not the shell. A provide
+    // inside HkFaceShell therefore cannot reach it (measured on chest:
+    // 0.55.240 lost the fold there while the shell's own slot kept it).
+    // The fix for that shape is the host starting the chain itself:
+    // provideMenuGroupState() in ITS setup, above the swap. This test is
+    // that shape, and it goes red if the export stops reaching slot
+    // content or if HkMenu stops injecting.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const Wrapper = defineComponent({
+      name: "SlotOwnerHarness",
+      setup() {
+        provideMenuGroupState();
+        const railStyle = ref<"expanded" | "rail">("rail");
+        return () =>
+          h(HkFaceShell, {
+            navTitle: "Navigation",
+            sidebarCollapsible: true,
+            sidebarRailStyle: railStyle.value,
+            "onUpdate:sidebarRailStyle": (v: string) => {
+              railStyle.value = v as "expanded" | "rail";
+            },
+          }, {
+            header: () => null,
+            sidebar: (params: { collapsed: boolean }) =>
+              h(HkMenu, {
+                variant: "sidebar",
+                items: GROUP_ITEMS,
+                open: false,
+                defaultExpandGroups: true,
+                collapsed: params.collapsed,
+              }),
+            content: () => h("div", { class: "content-mock" }, "CONTENT"),
+          });
+      },
+    });
+    const app = createApp(Wrapper);
+    app.mount(container);
+    mounts.push({ app, container });
+
+    const railGen = await settle(container, "rail");
+    expect(groupToggle(railGen).getAttribute("aria-expanded")).toBe("true");
+    groupToggle(railGen).click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(groupToggle(railGen).getAttribute("aria-expanded")).toBe("false");
+
+    // Peek: the slot is handed full rows — a brand-new HkMenu instance.
+    container
+      .querySelector<HTMLElement>(".hk-sidebar-rail-host")!
+      .dispatchEvent(POINTER_ENTER());
+    await vi.advanceTimersByTimeAsync(400);
+    const peekGen = await settle(container, "full");
+    expect(
+      groupToggle(peekGen).getAttribute("aria-expanded"),
+      "the host-provided store crosses into the peek's fresh generation",
+    ).toBe("false");
+    expect(peekGen.textContent, "and the peek lists no children").not.toContain("Audit log");
+  });
+});
+
 describe("rail group fold survives the crossfade generations (#43)", () => {
   beforeEach(() => {
     vi.useFakeTimers();

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

@@ -542,4 +542,36 @@ describe("HkSidebar standalone rail: the menu group fold survives its own swap",
       "the expanded sidebar inherits the closed group",
     ).toBe("false");
   });
+
+  it("keeps the scroll position across density flips (the #44 P3 audit finding)", async () => {
+    vi.useFakeTimers();
+    const c = mountSidebar({ width: "240px", collapsible: true, collapsedWidth: "64px" });
+
+    // Collapse to the rail and settle the dissolve.
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(500);
+    const bodies = () => c.container.querySelectorAll<HTMLElement>(".hk-sidebar-body");
+    const active = () => bodies()[bodies().length - 1]!;
+    expect(bodies().length, "one settled generation").toBe(1);
+
+    // The user scrolls the rail partway down…
+    active().scrollTop = 120;
+
+    // …then a peek flips the density (the shell keys the swap on
+    // `railActive && !peeking`, so every peek open/close is a flip).
+    c.aside().dispatchEvent(new Event("pointerenter"));
+    await vi.advanceTimersByTimeAsync(900);
+    expect(active().scrollTop, "the peek's full generation resumes the scroll").toBe(120);
+
+    // Leaving the peek flips back to the rail dress; the position must
+    // survive that remount too.
+    c.aside().dispatchEvent(new Event("pointerleave"));
+    await vi.advanceTimersByTimeAsync(900);
+    expect(active().scrollTop, "the rail generation resumes the scroll").toBe(120);
+
+    // And a full expand is the same crossing.
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(900);
+    expect(active().scrollTop, "the expanded body resumes the scroll").toBe(120);
+  });
 });

package/src/components/HkSidebar.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, onBeforeUnmount, onMounted, ref, watch } from "vue";
+import { computed, defineComponent, onBeforeUnmount, onMounted, ref, watch, nextTick } from "vue";
 
 import "./HkSidebar.scss";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
@@ -143,6 +143,34 @@ export default defineComponent({
     onMounted(attachBodyScrollbar);
     watch([bodyRef, bodyWrapRef], attachBodyScrollbar);
 
+    // Density flips remount the body band (the rail swap renders each
+    // generation's body FRESH), which used to snap the scroll back to the
+    // top on every flip — including each hover-peek open/close, because
+    // the shell keys the swap on `railActive && !peeking` (the #44 P3
+    // audit finding; probed: scrollTop 120 -> peek -> 0 -> back -> 0).
+    // The sidebar's own instance SURVIVES the flip (the swap lives inside
+    // it), so the position only needs to cross the remount. A flip patches
+    // the shared ref old -> null -> new: the null step still sees the
+    // LEAVING element as the old value (its DOM is alive for the
+    // 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.
+    const savedScrollTop = ref(0);
+    const onBodyScroll = (e: Event): void => {
+      savedScrollTop.value = (e.currentTarget as HTMLElement).scrollTop;
+    };
+    watch(bodyRef, async (body, leaving) => {
+      if (leaving) savedScrollTop.value = leaving.scrollTop;
+      if (!body) return;
+      await nextTick();
+      body.scrollTop = savedScrollTop.value;
+    });
+
     onBeforeUnmount(() => {
       bodyScrollbar?.detach();
       bodyScrollbar = null;
@@ -199,7 +227,7 @@ export default defineComponent({
           <header class="hk-sidebar-header">{slots.header()}</header>
         ) : null}
         <div ref={bodyWrapRef} class="hk-sidebar-body-wrap">
-          <div ref={bodyRef} class="hk-sidebar-body">
+          <div ref={bodyRef} class="hk-sidebar-body" onScroll={onBodyScroll}>
             {/* Scoped params (ignored by plain slots): the density that
                 owns THIS generation so a host renders icon-only rows
                 while collapsed and full rows during a peek, plus the

package/src/composables/useMenuGroupState.ts

@@ -41,6 +41,17 @@ import { inject, provide, shallowRef, type InjectionKey } from "vue";
  * menus mounted in the same shell share one key space — name their group
  * keys distinctly (they already name destinations, so this is the
  * natural convention).
+ *
+ * HOSTS THAT OWN THE SLOT THEMSELVES (chest's console, 2026-10-31): a
+ * slot's component parent is the component that DEFINED it, so a
+ * provide inside HkFaceShell does NOT reach content the host writes for
+ * the shell's sidebar slot — the host is that content's parent and the
+ * shell is only its DOM/CSS host (measured: chest's grouped nav lost the
+ * fold on 0.55.240 while the shell's own slot content kept it). Such a
+ * host starts the chain at its own setup level with
+ * provideMenuGroupState (one call, ABOVE the swap — the page component
+ * survives a density flip). HkMenu's inject then finds it through the
+ * host, and every generation the swap mounts shares it.
  */
 
 /** The fold store a shell provides above its sidebar swap. */

package/src/index.ts

@@ -481,8 +481,25 @@ export {
   SIDEBAR_RAIL_PEEK_DELAY,
   SIDEBAR_RAIL_PEEK_GRACE,
   SIDEBAR_RAIL_PIN_FALLBACK,
+  SIDEBAR_RAIL_CLIP_SELECTOR,
+  SIDEBAR_RAIL_TOGGLE_BUTTON_SELECTOR,
 } from "./composables/useSidebarRail";
 export type { SidebarRailOptions, SidebarRailHandle } from "./composables/useSidebarRail";
+// The sidebar GROUP FOLD store (known-live-issues #43). HkFaceShell and
+// HkSidebar provide one above their rail swap, so slot content THEY own
+// shares the fold across density generations. A host that defines the
+// shell's sidebar slot ITSELF (chest's AdminLayout) owns the slot's
+// component parent — a provide from inside the shell cannot reach it —
+// and must start the chain at its own setup level:
+//
+//   setup() { provideMenuGroupState(); return () => h(HkFaceShell, …) }
+//
+// Call it ABOVE the swap (i.e. in the component that survives a flip).
+export {
+  provideMenuGroupState,
+  useMenuGroupState,
+} from "./composables/useMenuGroupState";
+export type { MenuGroupState } from "./composables/useMenuGroupState";
 export {
   drawnScale,
   frameMetrics,