@celestia-island/hikari 0.55.112 → 0.55.114

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.112",
+  "version": "0.55.114",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkFloatingLayer.test.tsx

@@ -143,3 +143,24 @@ describe("HkFloatingLayer", () => {
     expect(m.root()!.querySelector(".probe")).not.toBeNull();
   });
 });
+
+describe("HkFloatingLayer yieldToWindows", () => {
+  it("hides while any window is open and returns when the last window closes", async () => {
+    const manager = usePopupManager();
+    const win = manager.register("modal", true, "Blocking");
+    const m = mountLayer({ yieldToWindows: true });
+    expect(m.root()).toBeNull();
+    manager.unregister(win.id);
+    await nextTick();
+    expect(m.root()).not.toBeNull();
+  });
+
+  it("default layers keep floating over windows (opt-in only)", async () => {
+    const manager = usePopupManager();
+    const win = manager.register("modal", true, "Blocking");
+    const m = mountLayer({});
+    expect(m.root()).not.toBeNull();
+    manager.unregister(win.id);
+    await nextTick();
+  });
+});

package/src/components/HkFloatingLayer.tsx

@@ -7,7 +7,7 @@ import {
   type PropType,
 } from "vue";
 
-import { usePopupManager } from "../runtime/usePopupManager";
+import { hasLiveWindow, usePopupManager } from "../runtime/usePopupManager";
 import "./HkFloatingLayer.scss";
 
 type FloatCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
@@ -63,6 +63,11 @@ export default defineComponent({
     offsetY: { type: String, default: undefined },
     /** Accessible group name for the chrome (e.g. "Date dial"). */
     ariaLabel: { type: String, default: "" },
+    /** Stack priority (user direction 2026-10-04): when true the layer
+     *  yields the screen while ANY window is open - page-level dial
+     *  chrome disappears under the top window instead of floating over
+     *  it, and returns when the last window closes. */
+    yieldToWindows: { type: Boolean, default: false },
   },
   setup(props, { slots }) {
     const { register, unregister } = usePopupManager();
@@ -71,7 +76,10 @@ export default defineComponent({
     // Annotation-band chrome, not a breadcrumb level: non-blocking,
     // untitled, no scroll lock, no outside-dismiss channel. Registered
     // exactly while shown (immediate, so the first paint already
-    // carries the band z); a hidden layer holds no slot.
+    // carries the band z); a hidden layer holds no slot. (A
+    // yielded layer keeps its slot held while hidden — constant chrome
+    // flipping a registered slot on every window open/close would churn
+    // the band for no visual effect.)
     watch(
       () => props.open,
       (show) => {
@@ -89,7 +97,7 @@ export default defineComponent({
     });
 
     return () => {
-      if (!props.open) return null;
+      if (!props.open || (props.yieldToWindows && hasLiveWindow.value)) return null;
       return (
         <Teleport to="body">
           <div

package/src/components/HkModal.test.tsx

@@ -415,3 +415,64 @@ describe("HkModal autoFollow", () => {
     expect(s.jump()).toBeNull();
   });
 });
+
+// Stack-priority dial slot (user direction 2026-10-04): the window owns
+// its dial while it is the topmost window, yields while another window
+// stacks above, and the page dial returns on close. The surface machine
+// runs on macrotask timers, so every stack transition below is staged
+// through vi.waitFor, never bare ticks.
+describe("HkModal dial slot (stack priority)", () => {
+  async function mountDialModal(withDial: boolean) {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const open = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkModal, {
+            modelValue: open.value,
+            title: "Window",
+            "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+          }, withDial
+            ? {
+                default: () => h("div", "body content"),
+                dial: () => h("button", { class: "dial-probe" }, "dial"),
+              }
+            : { default: () => h("div", "body content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    return { open };
+  }
+  const dialLayer = () => document.body.querySelector(".hk-floating-layer");
+
+  it("mounts its dial slot on the top layer while the window is topmost", async () => {
+    await mountDialModal(true);
+    await vi.waitFor(() => {
+      const layer = dialLayer();
+      expect(layer).not.toBeNull();
+      expect(layer!.querySelector(".dial-probe")).not.toBeNull();
+    });
+  });
+
+  it("yields while another window stacks above and returns when it closes", async () => {
+    const m = await mountDialModal(true);
+    await vi.waitFor(() => expect(dialLayer()).not.toBeNull());
+    const { register, unregister } = usePopupManager();
+    const above = register("modal", true, "Above");
+    await vi.waitFor(() => expect(dialLayer()).toBeNull());
+    unregister(above.id);
+    await vi.waitFor(() => expect(dialLayer()).not.toBeNull());
+    m.open.value = false;
+    await vi.waitFor(() => expect(dialLayer()).toBeNull());
+  });
+
+  it("renders no dial layer when the window declares none", async () => {
+    await mountDialModal(false);
+    await vi.waitFor(() => expect(document.body.querySelector(".hk-modal-root")).not.toBeNull());
+    expect(dialLayer()).toBeNull();
+  });
+});

package/src/components/HkModal.tsx

@@ -2,9 +2,10 @@ import { computed, defineComponent, nextTick, onBeforeUnmount, onMounted, ref, s
 
 import { useI18n } from "../i18n/context";
 import "./HkModal.scss";
+import HkFloatingLayer from "./HkFloatingLayer";
 import { focusFirst, trapFocus } from "../utils/dom";
 import { useOverlay } from "../runtime/useOverlay";
-import { usePopupManager } from "../runtime/usePopupManager";
+import { topWindowZ, usePopupManager } from "../runtime/usePopupManager";
 import { createBackGuard } from "../runtime/backStack";
 import { scheduleFrame, type AnimationHandle } from "../runtime/animationBus";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
@@ -936,12 +937,24 @@ export default defineComponent({
 
     const contentHold = useSurfaceContentHold(machine.phase);
 
+    // Stack-priority dial chrome (user direction 2026-10-04): the
+    // window's own dial replaces the page's while this window is the
+    // topmost one, yields while another window stacks above it (dial
+    // or not), and the page dial returns when the last window closes.
+    const dialVisible = computed(() =>
+      Boolean(
+        machine.mounted.value &&
+          handle.value &&
+          (topWindowZ.value === null || topWindowZ.value <= handle.value.zIndex),
+      ),
+    );
+
     return () => {
       if (!machine.mounted.value) return null;
 
       const headerShown = props.title || props.closable || slots.header || slots.headerLead;
 
-      return (
+      const windowSurface = (
         <Teleport to="body">
           <div
             class="hk-modal-root"
@@ -1066,6 +1079,19 @@ export default defineComponent({
           </div>
         </Teleport>
       );
+
+      // The dial rides the top layer beside its window (stack
+      // priority): mounted with the window, yielded above, retired
+      // when the window closes so the page dial can return.
+      if (!slots.dial) return windowSurface;
+      return (
+        <>
+          {windowSurface}
+          <HkFloatingLayer open={dialVisible.value} corner="bottom-right">
+            {slots.dial()}
+          </HkFloatingLayer>
+        </>
+      );
     };
 
     function renderWindowedBody() {

package/src/components/HkModalBreadcrumb.test.tsx

@@ -640,7 +640,9 @@ describe("HkModalBreadcrumb overflow fold", () => {
     // The strip is teleported into the host's zoomed root: the header's
     // rect is VISUAL px while the inline top it writes is LOCAL px, so the
     // height is divided by the zoom. Forgetting the division drifts the
-    // strip (zoom − 1) · height / 2 down its window.
+    // strip (zoom − 1) · height / 2 down its window. The strip's OWN height
+    // rides the same conversion (clearance branch), so it is mocked here
+    // too: 88 visual px = 44 local at zoom 2.
     const app = document.createElement("div");
     app.id = "app";
     app.style.top = "10px";
@@ -665,21 +667,91 @@ describe("HkModalBreadcrumb overflow fold", () => {
     const rect = (height: number): DOMRect =>
       ({ x: 0, y: 0, width: 200, height, top: 0, left: 0, right: 200, bottom: height, toJSON: () => ({}) }) as DOMRect;
     vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function (this: HTMLElement) {
-      return this === header ? rect(96) : rect(0);
+      if (this === header) return rect(96);
+      if (this.classList.contains("hk-modal-breadcrumb")) return rect(88);
+      return rect(0);
     });
     try {
       setViewport(1200);
       manager.register("modal", true, "第一层");
       manager.register("modal", true, "第二层");
       await mountStrip();
-      // 10 (app top, local) + (96 visual / 2 zoom) / 2
-      expect(strip()!.style.top).toBe("34px");
+      // 10 (app top, local) + the lower of: header centre (96 visual / 2
+      // zoom) / 2 = 24, and the clearance 12 + (88 visual / 2 zoom) / 2 =
+      // 34 — the clearance sits lower and wins.
+      expect(strip()!.style.top).toBe("44px");
     } finally {
       vi.restoreAllMocks();
       app.remove();
     }
   });
 
+  it("keeps daylight between the app's top edge and the strip", async () => {
+    // Centred on a standard short header, the strip's own upper half used
+    // to kiss the very top edge (2026-10-05 user report): a ~24px centre
+    // line is less than the strip's half height. The top is now the LOWER
+    // of "header centre" and the topGap clearance; the boxless test DOM
+    // exercises the rule on the two layout fallbacks (48px header, 43px
+    // strip). The app top is deliberately non-zero (5px) so NO expectation
+    // coincides with the pre-resync initial ref — each leg proves resyncTop
+    // actually wrote: 5 + max(48/2, gap + 43/2).
+    const app = document.createElement("div");
+    app.id = "app";
+    app.style.top = "5px";
+    document.body.appendChild(app);
+    const unmountAll = () => {
+      for (const a of mounts.splice(0)) a.unmount();
+    };
+    try {
+      setViewport(1200);
+      manager.register("modal", true, "第一层");
+      manager.register("modal", true, "第二层");
+      await mountStrip();
+      expect(strip()!.style.top).toBe("38.5px");
+      unmountAll();
+
+      // A host pinning the legacy, header-centred position passes 0:
+      // 5 + max(24, 0 + 21.5) — the centre branch wins again.
+      await mountStrip({ topGap: 0 });
+      expect(strip()!.style.top).toBe("29px");
+      unmountAll();
+
+      // And a host wanting more air simply raises the gap.
+      await mountStrip({ topGap: 40 });
+      expect(strip()!.style.top).toBe("66.5px");
+      unmountAll();
+
+      // A NaN gap is host junk: it falls back to the default instead of
+      // poisoning Math.max into `top: NaNpx` (which the browser drops).
+      await mountStrip({ topGap: Number.NaN });
+      expect(strip()!.style.top).toBe("38.5px");
+    } finally {
+      unmountAll();
+      app.remove();
+    }
+  });
+
+  it("paints the fallback position before any resync can run", async () => {
+    // A host whose app root id never resolves leaves resyncTop at its
+    // early-return, so the strip paints the INITIAL ref: that line must
+    // already encode the clearance rule on the two layout fallbacks
+    // (48px header, 43px strip), not a legacy literal. Every other
+    // style.top assertion lives in tests that create #app, where the
+    // pre-mount resync overwrites the init before the first render
+    // (mutation round M5: reverting the init to a bare 24 passed
+    // everything else green).
+    setViewport(1200);
+    manager.register("modal", true, "第一层");
+    manager.register("modal", true, "第二层");
+    await mountStrip({ appRootId: "no-such-root" });
+    expect(strip()!.style.top).toBe("33.5px");
+    for (const a of mounts.splice(0)) a.unmount();
+
+    // The init follows the prop the same way the resync does.
+    await mountStrip({ appRootId: "no-such-root", topGap: 0 });
+    expect(strip()!.style.top).toBe("21.5px");
+  });
+
   it("writes the viewport fence in the strip's own px", async () => {
     // A vw-authored cap would be scaled by a host root zoom at paint, so the
     // fence is re-derived from the live viewport (minus the shared gutter)

package/src/components/HkModalBreadcrumb.tsx

@@ -36,6 +36,13 @@ const GAP_PX = 8;
 const SIDE_PADDING_PX = 32;
 const BORDER_PX = 1;
 const MORE_PX = 24;
+/** The strip's own height for the moments no box can be measured (first
+ *  resync, unit DOM): the stylesheet declares 12px vertical padding, a
+ *  ~17px label line and a 1px border — 12·2 + 17 + 1·2 ≈ 43. Models the
+ *  UNFOLDED strip; a folded one is ~50px (the 24px trigger line) — the
+ *  fallback only serves boxless DOMs, a real browser measures the live
+ *  nav and the slow tick re-derives from it. */
+const STRIP_HEIGHT_PX = 43;
 
 interface Crumb {
   /** Popup-registry id this crumb can navigate back to. */
@@ -66,12 +73,33 @@ export default defineComponent({
      * hidden-layers menu.
      */
     maxLabelUnits: { type: Number, default: 10 },
+    /**
+     * Least daylight, in px, between the app's top edge and the strip's own
+     * top edge. The strip is centred on the app header, and on the standard
+     * short header that centre line sits ~24px from the top — less than the
+     * strip's half height, so its upper half used to kiss the very top edge
+     * (2026-10-05 user report). The top is now the lower of "centred on the
+     * header" and "this clearance"; a header whose centre already sits at
+     * least this far down keeps the strip centred on it. Authored in the
+     * strip's LOCAL px like every length here — a host root zoom scales it
+     * at paint, so it can only over-deliver daylight. Below 8 the entrance
+     * keyframe's own 8px slide transiently pokes back above the app top.
+     */
+    topGap: { type: Number, default: 12 },
   },
   setup(props) {
     const manager = usePopupManager();
     const { t } = useI18n();
     const { isMobile } = useBreakpoint();
 
+    /** Sanitized once: a host passing NaN would otherwise poison both the
+     *  pre-resync ref and every resync (Math.max(x, NaN) is NaN, and the
+     *  browser drops `top: NaNpx`, parking the strip at its static
+     *  position). A NEGATIVE gap stays the host's choice: it lowers the
+     *  clearance candidate below the centre line, which then wins — i.e.
+     *  "I don't care about daylight". */
+    const topGapPx = computed(() => (Number.isFinite(props.topGap) ? props.topGap : 12));
+
     /** Which entries the strip navigates. Windows (modal/drawer) always;
      *  dropdown-kind surfaces only while they BLOCK like a window — the
      *  mobile bottom sheet a menu/popover becomes when viewport space
@@ -375,7 +403,10 @@ export default defineComponent({
     });
     onBeforeUnmount(() => document.removeEventListener("keydown", onSurfaceKeydown));
 
-    const topPx = ref(24);
+    /** Pre-resync paint position: the clearance rule evaluated on the two
+     *  layout fallbacks (48px header, 43px strip). The first nextTick
+     *  resync replaces it with measured numbers. */
+    const topPx = ref(topGapPx.value + STRIP_HEIGHT_PX / 2);
     function resyncTop() {
       const app = document.getElementById(props.appRootId);
       if (!app) return;
@@ -397,7 +428,20 @@ export default defineComponent({
       const headerH = header
         ? header.getBoundingClientRect().height / z
         : props.headerFallbackHeight;
-      topPx.value = appTop + headerH / 2;
+      // The strip's own height comes back in the same VISUAL px the
+      // header's rect does (it teleports into the same zoomed subtree), so
+      // it divides by the zoom read at the strip itself. No box (first
+      // resync, unit DOM) falls back to the stylesheet-declared height.
+      let stripH = STRIP_HEIGHT_PX;
+      if (navRef.value) {
+        const navH = navRef.value.getBoundingClientRect().height;
+        if (navH > 0) stripH = navH / ancestorZoom(navRef.value);
+      }
+      // Centre on the header, but keep the promised daylight: whichever
+      // candidate parks the strip LOWER wins, so a centre line near the
+      // viewport top can no longer push the strip's upper half against
+      // (or past) the top edge.
+      topPx.value = appTop + Math.max(headerH / 2, topGapPx.value + stripH / 2);
     }
 
     /** Viewport fence, in the strip's OWN px. The stylesheet cap is
@@ -463,6 +507,9 @@ export default defineComponent({
           if (!handle) handle = scheduleEvery(onSlowTick, 1000);
           window.addEventListener("resize", onViewportChange);
           void nextTick(() => {
+            // The strip's own box exists only now: re-derive the top with
+            // a measured height (the pre-mount resync ran on fallbacks).
+            resyncBox();
             measureStrip();
             observeClone();
           });
@@ -495,7 +542,9 @@ export default defineComponent({
       if (!visible.value) return;
       // Synchronous first measure: the collapsed shape is committed in the
       // same task as the mount, so the strip never paints one frame wide
-      // enough to spill before folding.
+      // enough to spill before folding. The top is re-derived with the
+      // strip's now-measurable height for the same reason.
+      resyncBox();
       measureStrip();
       observeClone();
     });

package/src/index.ts

@@ -348,6 +348,9 @@ export {
   setReducedMotion,
   notifyScrollStart,
   useOverlay,
+  hasLiveWindow,
+  isWindowEntry,
+  topWindowZ,
   usePopupManager,
   POPUP_Z_BANDS,
   POPUP_Z_STEP,

package/src/runtime/index.ts

@@ -56,7 +56,16 @@ export {
 } from "./backStack";
 export { useMediaQuery, releaseMediaQuery } from "./useMediaQuery";
 export { useOverlay, closeAll, isOverlayOpen, type OverlayHandle, type UseOverlayOptions } from "./useOverlay";
-export { usePopupManager, POPUP_Z_BANDS, POPUP_Z_STEP, type PopupHandle, type PopupKind } from "./usePopupManager";
+export {
+  hasLiveWindow,
+  isWindowEntry,
+  topWindowZ,
+  usePopupManager,
+  POPUP_Z_BANDS,
+  POPUP_Z_STEP,
+  type PopupHandle,
+  type PopupKind,
+} from "./usePopupManager";
 export { useToast, TOAST_DURATION, type ToastItem, type ToastMessage, type ToastType } from "./useToast";
 export { useConfirm } from "./useConfirm";
 export { useBlockingToast, showBlockingToast, resolveBlockingToast, clearBlockingToasts, type BlockingToastItem, type BlockingToastOptions, type BlockingToastVariant } from "./useBlockingToast";

package/src/runtime/usePopupManager.test.ts

@@ -1,7 +1,13 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { watch } from "vue";
 
-import { POPUP_Z_BANDS, POPUP_Z_STEP, usePopupManager } from "./usePopupManager";
+import {
+  hasLiveWindow,
+  POPUP_Z_BANDS,
+  POPUP_Z_STEP,
+  topWindowZ,
+  usePopupManager,
+} from "./usePopupManager";
 
 const managers: ReturnType<typeof usePopupManager>[] = [];
 
@@ -338,3 +344,43 @@ describe("usePopupManager closeAbove", () => {
     }
   });
 });
+
+describe("usePopupManager window-stack signals", () => {
+  it("derived signals track the live window band (page chrome's yield rule)", () => {
+    const m = usePopupManager();
+    const win = m.register("modal", true, "Window");
+    expect(hasLiveWindow.value).toBe(true);
+    expect(topWindowZ.value).toBe(win.zIndex);
+    // Tooltip-band entries are not windows: they must not flip the signals.
+    const tip = m.register("tooltip", false);
+    expect(hasLiveWindow.value).toBe(true);
+    expect(topWindowZ.value).toBe(win.zIndex);
+    m.unregister(tip.id);
+    m.unregister(win.id);
+    expect(hasLiveWindow.value).toBe(false);
+    expect(topWindowZ.value).toBeNull();
+  });
+
+  it("only window-band entries count: anchored dropdowns no, docked sheets yes", () => {
+    const m = usePopupManager();
+    const dd = m.register("dropdown", false);
+    expect(hasLiveWindow.value).toBe(false);
+    m.unregister(dd.id);
+    const sheet = m.register("dropdown", true, "Sheet", true);
+    expect(hasLiveWindow.value).toBe(true);
+    expect(topWindowZ.value).toBe(sheet.zIndex);
+    m.unregister(sheet.id);
+    expect(hasLiveWindow.value).toBe(false);
+  });
+
+  it("topWindowZ follows the topmost of stacked windows", () => {
+    const m = usePopupManager();
+    const low = m.register("modal", true, "Low");
+    const high = m.register("modal", true, "High");
+    expect(topWindowZ.value).toBe(high.zIndex);
+    expect(topWindowZ.value).toBeGreaterThan(low.zIndex);
+    m.unregister(high.id);
+    expect(topWindowZ.value).toBe(low.zIndex);
+    m.unregister(low.id);
+  });
+});

package/src/runtime/usePopupManager.ts

@@ -1,4 +1,4 @@
-import { readonly, ref } from "vue";
+import { computed, readonly, ref } from "vue";
 
 import { reportHkRuntime, type HkRuntimeHandle } from "./registry";
 
@@ -70,6 +70,14 @@ function effectiveBand(kind: PopupKind, blocking: boolean): number {
   return POPUP_Z_BANDS[kind];
 }
 
+/** True when a live entry is a WINDOW (blocks the page like one):
+ *  modal/drawer by kind, or a dropdown-kind surface docked as a
+ *  blocking mobile sheet. Page chrome (dials, floating pads) uses
+ *  this to yield the screen to whatever window is on top. */
+export function isWindowEntry(kind: PopupKind, blocking: boolean): boolean {
+  return effectiveBand(kind, blocking) === POPUP_Z_BANDS.modal;
+}
+
 /** In-band stacking step. Even numbers leave the odd slot free for the
  * +1 content/panel layer each overlay puts above its own root. */
 export const POPUP_Z_STEP = 2;
@@ -132,6 +140,27 @@ function uid(): string {
 }
 
 const registry = ref<Map<string, PopupEntry>>(new Map());
+
+// Derived window-stack signals (reactive over the live registry):
+// whether ANY window is open, and the topmost window's z slot. Stack
+// priority for dial chrome rides these — a window's own dial replaces
+// the page's while it is topmost; close the window and the page's
+// dial returns.
+export const hasLiveWindow = computed<boolean>(() => {
+  for (const entry of registry.value.values()) {
+    if (isWindowEntry(entry.kind, entry.blocking)) return true;
+  }
+  return false;
+});
+
+export const topWindowZ = computed<number | null>(() => {
+  let top: number | null = null;
+  for (const entry of registry.value.values()) {
+    if (!isWindowEntry(entry.kind, entry.blocking)) continue;
+    if (top === null || entry.zIndex > top) top = entry.zIndex;
+  }
+  return top;
+});
 let scrollLockCount = 0;
 
 // Runtime-registry reporting (the "context of contexts"). Lazy: the