@celestia-island/hikari 0.55.233 → 0.55.234

package/package.json

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

package/src/components/HkAdminShell.tsx

@@ -39,8 +39,10 @@ export const HkAdminShell = defineComponent({
     sidebarWidth: { type: String, default: "224px" },
     /** Desktop icon-rail capability, forwarded to HkFaceShell (see its
      *  prop doc): opt in here and the admin sidebar gains the circular
-     *  hover-reveal toggle, the one-icon rail and the overlay peek
-     *  drawer. Declared on the wrapper on purpose — the same
+     *  hover-reveal toggle STRADDLING the sidebar's content-facing border,
+     *  the one-icon rail and the overlay peek drawer (with the peek
+     *  suppressed while the pointer rests on the toggle, and a pinned
+     *  panel on expand). Declared on the wrapper on purpose — the same
      *  honest-forwarding rule as contentMode (a stray attr must not
      *  reach the inner shell's declared prop through fallthrough). */
     sidebarCollapsible: { type: Boolean, default: false },

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

@@ -368,3 +368,211 @@ describe("HkAdminShell forwarding (source pin)", () => {
     expect(container.querySelector(".hk-sidebar-rail-toggle button")).toBeTruthy();
   });
 });
+/** A pointermove with explicit viewport coordinates (the suppression
+ *  wiring is purely geometric — see HkSidebarRailToggle's helper). */
+function pointerMove(x: number, y: number): MouseEvent {
+  const e = new MouseEvent("pointermove", { bubbles: true });
+  Object.defineProperty(e, "clientX", { value: x });
+  Object.defineProperty(e, "clientY", { value: y });
+  return e;
+}
+
+/** A pointerenter carrying viewport coordinates — the host evaluates the
+ *  toggle containment on ENTER, before it arms the dwell. */
+function pointerEnterAt(x: number, y: number): MouseEvent {
+  const e = new MouseEvent("pointerenter", { bubbles: true });
+  Object.defineProperty(e, "clientX", { value: x });
+  Object.defineProperty(e, "clientY", { value: y });
+  return e;
+}
+
+/** A transitionend carrying the property name (happy-dom has no
+ *  TransitionEvent; the host handler filters on `width`). */
+function widthTransitionEnd(): Event {
+  const e = new Event("transitionend");
+  Object.defineProperty(e, "propertyName", { value: "width" });
+  return e;
+}
+
+/** Pin the toggle wrapper's box — happy-dom lays nothing out. */
+function stubToggleRect(container: HTMLElement, left: number, top: number, size = 24) {
+  const el = container.querySelector(".hk-sidebar-rail-toggle") as HTMLElement;
+  el.getBoundingClientRect = () =>
+    ({
+      left,
+      top,
+      right: left + size,
+      bottom: top + size,
+      width: size,
+      height: size,
+      x: left,
+      y: top,
+      toJSON: () => ({}),
+    }) as DOMRect;
+}
+
+describe("HkFaceShell rail chrome: toggle placement and the clip wrapper", () => {
+  it("keeps the toggle a DIRECT child of the panel and the slot inside the clip", () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    const panel = c.panel();
+    const clip = panel.querySelector(":scope > .hk-sidebar-rail-clip") as HTMLElement | null;
+    const toggle = panel.querySelector(":scope > .hk-sidebar-rail-toggle") as HTMLElement | null;
+
+    expect(clip, "the slot's content clips inside the wrapper").toBeTruthy();
+    expect(toggle, "the toggle is a direct child of the panel").toBeTruthy();
+    expect(clip!.contains(toggle!), "the toggle is never inside the clip").toBe(false);
+    expect(clip!.querySelector(".sidebar-mock"), "the sidebar slot renders in the clip").toBeTruthy();
+  });
+
+  it("does not touch the legacy sidebar path (no clip wrapper, no rail classes)", () => {
+    const c = mountShell();
+    expect(c.container.querySelector(".hk-sidebar-rail-clip")).toBeFalsy();
+    expect(c.container.querySelector(".hk-sidebar-rail-panel")).toBeFalsy();
+    expect(c.container.querySelector(".sidebar-mock")).toBeTruthy();
+  });
+});
+
+describe("HkFaceShell pin window: expand must not replay the slide", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("pins on a rail -> expanded flip and clears on the host width transition", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning"), "collapsing never pins").toBe(false);
+
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning"), "the expand window is pinned").toBe(true);
+    // The panel is already at its final width — only the host animates.
+    expect(c.panel().style.width).toBe("224px");
+    expect(c.aside().style.width).toBe("224px");
+
+    c.aside().dispatchEvent(widthTransitionEnd());
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(false);
+  });
+
+  it("clears the pin window by the fallback when no transition fires", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(false);
+  });
+
+  it("collapsing closes an open pin window immediately", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(true);
+
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(false);
+    expect(c.aside().style.width).toBe("56px");
+  });
+
+  it("a child transitionend never ends the window (filtered to the host's width)", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+
+    c.panel().dispatchEvent(widthTransitionEnd());
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(true);
+  });
+});
+
+describe("HkFaceShell hover suppression: a pointer on the toggle never peeks", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("suppresses the dwell while the pointer rests on the toggle, re-arms when it moves off", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    stubToggleRect(c.container, 100, 200);
+
+    c.aside().dispatchEvent(POINTER_ENTER());
+    c.aside().dispatchEvent(pointerMove(110, 210));
+    await vi.advanceTimersByTimeAsync(400 * 4);
+    expect(c.aside().hasAttribute("data-peeking"), "parked on the toggle: no peek").toBe(false);
+    expect(c.slotParams[c.slotParams.length - 1]!.collapsed).toBe(true);
+
+    c.aside().dispatchEvent(pointerMove(400, 500));
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-peeking"), "off the toggle the peek arms normally").toBe(true);
+    expect(c.slotParams[c.slotParams.length - 1]!.peeking).toBe(true);
+  });
+
+  it("evaluates suppression on ENTER: crossing the boundary onto the toggle arms nothing", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    stubToggleRect(c.container, 100, 200);
+
+    c.aside().dispatchEvent(pointerEnterAt(110, 210));
+    await vi.advanceTimersByTimeAsync(400 * 4);
+    expect(c.aside().hasAttribute("data-peeking"), "enter on the toggle arms nothing").toBe(false);
+    expect(c.slotParams[c.slotParams.length - 1]!.collapsed).toBe(true);
+  });
+
+  it("evaluates suppression on ENTER: entering elsewhere on the rail still peeks", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    stubToggleRect(c.container, 100, 200);
+
+    c.aside().dispatchEvent(pointerEnterAt(400, 500));
+    await vi.advanceTimersByTimeAsync(399);
+    expect(c.aside().hasAttribute("data-peeking"), "one tick before the dwell").toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(c.aside().hasAttribute("data-peeking"), "off the toggle the enter arms the dwell").toBe(true);
+  });
+
+  it("ignores a pointerleave whose relatedTarget is still inside the host", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.aside().dispatchEvent(POINTER_ENTER());
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(true);
+
+    const churn = POINTER_LEAVE();
+    Object.defineProperty(churn, "relatedTarget", { value: c.container.querySelector(".sidebar-mock") });
+    c.aside().dispatchEvent(churn);
+    await vi.advanceTimersByTimeAsync(150 * 4);
+    expect(c.aside().hasAttribute("data-peeking"), "DOM churn is not a leave").toBe(true);
+
+    c.aside().dispatchEvent(POINTER_LEAVE());
+    await vi.advanceTimersByTimeAsync(150);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(false);
+  });
+
+  it("clicking the toggle during an open peek still pins the sidebar expanded", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.aside().dispatchEvent(POINTER_ENTER());
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(true);
+
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(false);
+    expect(c.aside().style.width).toBe("224px");
+    expect(c.aside().hasAttribute("data-pinning"), "the peek pin is a rail -> expanded flip").toBe(true);
+  });
+});

package/src/components/HkFaceShell.tsx

@@ -2,7 +2,7 @@ import { computed, defineComponent, ref, watch, type PropType } from "vue";
 import { HkCrossfade, HDrawer, HScrollContainer, useBreakpoint } from "@celestia-island/hikari";
 import { useI18n } from "../i18n/context";
 import { useSidebarRail } from "../composables/useSidebarRail";
-import HkSidebarRailToggle from "./HkSidebarRailToggle";
+import HkSidebarRailToggle, { isPointerOverRailToggle } from "./HkSidebarRailToggle";
 
 /** CSS-wide keywords. A shorthand rebuilt from one of them is NOT a
  * padding (`inherit 0 inherit` is rejected by every engine, measured in
@@ -171,13 +171,22 @@ export const HkFaceShell = defineComponent({
     sidebarCollapsed: { type: Boolean, default: false },
     sidebarWidth: { type: String, default: "224px" },
     /** OPT-IN icon-rail capability for the desktop sidebar (2026-10-30):
-     *  mounts the hover-reveal circular chevron toggle on the sidebar's
-     *  content-facing edge, lets a click collapse the sidebar to a one-
-     *  icon rail, and — while collapsed — opens a hover-peek drawer that
-     *  slides the full sidebar OVER the content as an overlay (the
-     *  layout keeps the rail width; the content area never shifts).
-     *  Timing lives in useSidebarRail (dwell, grace, Escape); geometry in
-     *  HkSidebarRail.scss (.hk-sidebar-rail-host/-panel/-toggle).
+     *  mounts the hover-reveal circular chevron toggle STRADDLING the
+     *  sidebar's content-facing border (its center on the border line,
+     *  half the circle over the content), lets a click collapse the
+     *  sidebar to a one-icon rail, and — while collapsed — opens a
+     *  hover-peek drawer that slides the full sidebar OVER the content as
+     *  an overlay (the layout keeps the rail width; the content area never
+     *  shifts).
+     *
+     *  Two behaviors ride the same opt-in: a pointer resting on the toggle
+     *  SUPPRESSES the peek dwell (it sits on the rail's hover surface and
+     *  would otherwise open the drawer out from under the cursor), and a
+     *  rail -> expanded flip PINNS the panel at its final width for the
+     *  transition window, so only the content area animates instead of the
+     *  sidebar re-sliding. Timing lives in useSidebarRail (dwell, grace,
+     *  suppression, Escape, pinning); geometry in HkSidebarRail.scss
+     *  (.hk-sidebar-rail-host/-panel/-clip/-toggle).
      *  False (default) renders the sidebar exactly as before. Below
      *  mobileBreakpoint nothing changes — the mobile drawer stays the
      *  only nav surface. */
@@ -291,10 +300,15 @@ export const HkFaceShell = defineComponent({
         emit("update:sidebarRailStyle", v ? "rail" : "expanded");
       },
     });
+    // The host REGION element (the rail <aside>) — the machine uses it to
+    // tell a real pointerleave from DOM churn during the peek/width
+    // transitions.
+    const railHostRef = ref<HTMLElement>();
     const rail = useSidebarRail({
       collapsed: railCollapsed,
       peekDelay: () => props.sidebarPeekDelay,
       peekGrace: () => props.sidebarPeekGrace,
+      host: () => railHostRef.value,
     });
     const railActive = computed(() => props.sidebarCollapsible && railCollapsed.value);
     // The LAYOUT width — the core contract of the peek: rail width while
@@ -327,6 +341,33 @@ export const HkFaceShell = defineComponent({
       if (rail.onKeydown(e)) e.stopPropagation();
     };
 
+    /** A pointer parked on the toggle must NOT arm the peek dwell — the
+     *  toggle straddles the rail's hover surface, so the drawer would open
+     *  under the resting cursor and jump the button away from it (the
+     *  reported twitch). Containment is GEOMETRIC: before the reveal the
+     *  toggle is opacity:0 / pointer-events:none, so event.target cannot
+     *  report it.
+     *
+     *  ENTER evaluates it too, and BEFORE the arm: a pointer that crosses
+     *  the boundary and stops exactly on the toggle (or a synthetic enter
+     *  with no following move) must not arm the dwell. */
+    const onSidebarHostPointerEnter = (e: PointerEvent) => {
+      rail.setPeekSuppressed(isPointerOverRailToggle(railHostRef.value, e.clientX, e.clientY));
+      rail.onPointerEnter();
+    };
+    const onSidebarHostPointerMove = (e: PointerEvent) => {
+      rail.setPeekSuppressed(isPointerOverRailToggle(railHostRef.value, e.clientX, e.clientY));
+    };
+
+    /** The pin window ends with the HOST's own width transition; child
+     *  transitionend events (the panel, a nested HkSidebar) bubble here
+     *  too, so filter to this element's width. */
+    const onSidebarHostTransitionEnd = (e: TransitionEvent) => {
+      if (e.target !== e.currentTarget) return;
+      if (e.propertyName !== "width") return;
+      rail.endPinning();
+    };
+
     const contentStyle = computed(() => ({
       padding: isDesktop.value || !props.contentBleedOnMobile
         ? props.contentPadding
@@ -392,12 +433,20 @@ export const HkFaceShell = defineComponent({
           {isDesktop.value && !props.sidebarCollapsed && slots.sidebar && (
             props.sidebarCollapsible ? (
               <aside
+                ref={railHostRef}
                 class="hk-sidebar-rail-host"
                 data-rail={railActive.value || undefined}
                 data-peeking={rail.peeking.value || undefined}
+                // Transient rail -> expanded window (useSidebarRail.pinning):
+                // the panel and any nested sidebar snap to their final width
+                // while THIS host's width transition plays — expanding must
+                // not replay the sidebar slide.
+                data-pinning={rail.pinning.value || undefined}
                 style={{ width: hostSidebarWidth.value, flexShrink: 0 }}
-                onPointerenter={rail.onPointerEnter}
+                onPointerenter={onSidebarHostPointerEnter}
                 onPointerleave={rail.onPointerLeave}
+                onPointermove={onSidebarHostPointerMove}
+                onTransitionend={onSidebarHostTransitionEnd}
                 onKeydown={onSidebarHostKeydown}
               >
                 {/* The visual panel — absolutely positioned over the host
@@ -413,11 +462,18 @@ export const HkFaceShell = defineComponent({
                     background: "rgb(var(--color-surface))",
                   }}
                 >
-                  {slots.sidebar({
-                    collapsed: railActive.value && !rail.peeking.value,
-                    onNavigate: onSidebarNavigate,
-                    peeking: rail.peeking.value,
-                  })}
+                  {/* The panel no longer clips (the toggle straddles its
+                      border), so the slot's content clips inside this
+                      wrapper — full rows stay inside rail width while the
+                      panel width animates. The toggle stays a DIRECT child
+                      of the panel: it must never be clipped. */}
+                  <div class="hk-sidebar-rail-clip">
+                    {slots.sidebar({
+                      collapsed: railActive.value && !rail.peeking.value,
+                      onNavigate: onSidebarNavigate,
+                      peeking: rail.peeking.value,
+                    })}
+                  </div>
                   <HkSidebarRailToggle expanded={!railActive.value} onToggle={rail.toggle} />
                 </div>
               </aside>