@celestia-island/hikari 0.55.112 → 0.55.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.112",
+  "version": "0.55.113",
   "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/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