@celestia-island/hikari 0.40.25 → 0.40.26

package/package.json

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

package/src/runtime/usePopupManager.test.ts

@@ -198,3 +198,83 @@ describe("usePopupManager blocking flag (breadcrumb levels)", () => {
     }
   });
 });
+
+describe("usePopupManager window stack (blocking sheets reband)", () => {
+  it("stacks a blocking sheet with windows in open order — a window opened from inside the sheet paints above it", () => {
+    // The chest mobile regression: the theme menu docks as a bottom
+    // sheet, its row's edit affordance opens a MODAL — kind bands put
+    // the sheet (dropdown, 2000) above the modal (1000) and the editor
+    // rendered BEHIND its own opener. A blocking sheet is a window: it
+    // must share the window band and lose to windows pushed after it.
+    const m = freshManager();
+    const sheet = m.register("dropdown", false, "Themes", true);
+    expect(sheet.zIndex).toBe(POPUP_Z_BANDS.modal);
+
+    const editor = m.register("modal", true, "Edit theme");
+    expect(editor.zIndex).toBe(sheet.zIndex + POPUP_Z_STEP);
+
+    // A sheet opened from INSIDE that modal pushes on top of it.
+    const innerSheet = m.register("dropdown", false, "Picker", true);
+    expect(innerSheet.zIndex).toBe(editor.zIndex + POPUP_Z_STEP);
+  });
+
+  it("keeps an ANCHORED dropdown above the whole window stack, blocking sheets included", () => {
+    // The in-modal select flow: anchored panels stay in the dropdown
+    // band so they paint above whichever window (modal OR blocking
+    // sheet) contains them.
+    const m = freshManager();
+    const sheet = m.register("dropdown", false, "Themes", true);
+    const modal = m.register("modal", true, "Edit");
+    const panel = m.register("dropdown", false);
+    expect(panel.zIndex).toBe(POPUP_Z_BANDS.dropdown);
+    expect(panel.zIndex).toBeGreaterThan(sheet.zIndex);
+    expect(panel.zIndex).toBeGreaterThan(modal.zIndex);
+  });
+
+  it("reclaims window-band slots across mixed windows and sheets", () => {
+    const m = freshManager();
+    const sheet = m.register("dropdown", false, "Themes", true);
+    const modal = m.register("modal", true, "Edit");
+    expect(modal.zIndex).toBe(sheet.zIndex + POPUP_Z_STEP);
+
+    m.unregister(modal.id);
+    const drawer = m.register("drawer", true, "Details");
+    // The drawer reclaims the modal's slot, not a third one.
+    expect(drawer.zIndex).toBe(modal.zIndex);
+  });
+
+  it("setBlocking promotion pushes onto the top of the window band, demotion returns to the anchored band", () => {
+    const m = freshManager();
+    const modal = m.register("modal", true, "Edit");
+    // Anchored first: above every window while non-blocking.
+    const popup = m.register("dropdown", false, "Menu");
+    expect(popup.zIndex).toBe(POPUP_Z_BANDS.dropdown);
+
+    // Viewport crosses the mobile breakpoint: the popover docks as a
+    // sheet — becoming a window is a PUSH, so it lands above the modal.
+    m.setBlocking(popup.id, true);
+    expect(m.registry.value.get(popup.id)!.zIndex).toBe(modal.zIndex + POPUP_Z_STEP);
+
+    // Back to desktop: an anchored attachment again — top of the
+    // anchored band, above the whole window stack.
+    m.setBlocking(popup.id, false);
+    const entry = m.registry.value.get(popup.id)!;
+    expect(entry.zIndex).toBe(POPUP_Z_BANDS.dropdown);
+    expect(entry.zIndex).toBeGreaterThan(modal.zIndex);
+  });
+
+  it("orders the breadcrumb window stack by push order (sheet → editor)", () => {
+    // HkModalBreadcrumb sorts by zIndex; with blocking sheets sharing
+    // the window band, the strip reads in navigation order: the sheet
+    // that opened the editor, then the editor as the current level.
+    const m = freshManager();
+    const sheet = m.register("dropdown", false, "Themes", true);
+    const editor = m.register("modal", true, "Edit theme");
+    const levels = [...m.registry.value.values()]
+      .filter((e) => e.kind === "modal" || e.kind === "drawer" || e.blocking)
+      .sort((a, b) => a.zIndex - b.zIndex)
+      .map((e) => e.title);
+    expect(levels).toEqual(["Themes", "Edit theme"]);
+    expect(editor.zIndex).toBeGreaterThan(sheet.zIndex);
+  });
+});

package/src/runtime/usePopupManager.ts

@@ -5,23 +5,28 @@ export type PopupKind = "dropdown" | "modal" | "drawer" | "tooltip" | "toast";
 /**
  * Kind-priority z bands — the single source of truth for popup stacking.
  *
- * Every registered popup lands in its kind's band, so layering is decided
- * by WHAT a surface is, never by WHEN it happened to register. Bands are
- * ordered low → high:
+ * Layering is decided by WHAT a surface IS — window or attachment — never
+ * by WHEN it happened to register:
  *
- *   modal    (1000)  centered dialogs + phone bottom sheets
- *   drawer   (1000)  edge drawers share the overlay band with modals —
- *                    inside the band they stack in open order, so a
- *                    drawer opened over a modal still paints above it
- *   dropdown (2000)  anchor-attached popovers, select panels, menus —
- *                    ABOVE the overlay band on purpose: a select panel
- *                    opened from inside a modal portals to <body> and
- *                    must paint above the modal that contains it (the
- *                    common in-modal form flow). A page-level dropdown
- *                    can only coexist with a modal programmatically (the
- *                    modal overlay intercepts pointers), so the rare
- *                    stale-dropdown-over-modal case is accepted, matching
- *                    Ant Design
+ *   modal    (1000)  the WINDOW band: centered dialogs + phone bottom
+ *   drawer   (1000)  sheets + edge drawers. Anything that BLOCKS the page
+ *                    like a window is a window: modals and drawers by
+ *                    kind, and a dropdown-kind surface while it is docked
+ *                    as a mobile bottom sheet (`blocking`). Within the
+ *                    band surfaces stack purely in open order (push/pop
+ *                    stack semantics), so a window opened FROM inside a
+ *                    sheet always paints above it — the sheet keeps no
+ *                    kind-priority claim over windows opened later.
+ *   dropdown (2000)  ANCHORED popovers, select panels, menus — surfaces
+ *                    attached to an anchor on whatever window is on top,
+ *                    not windows themselves. ABOVE the window band on
+ *                    purpose: a select panel opened from inside a modal
+ *                    portals to <body> and must paint above the modal
+ *                    that contains it (the common in-modal form flow). A
+ *                    page-level anchored dropdown can only coexist with a
+ *                    modal programmatically (the modal overlay intercepts
+ *                    pointers), so the rare stale-dropdown-over-modal case
+ *                    is accepted, matching Ant Design
  *   tooltip  (3000)  transient annotations must stay visible above the
  *                    surfaces they annotate
  *   toast    (4000)  ALWAYS the topmost surface — a toast must never be
@@ -33,8 +38,11 @@ export type PopupKind = "dropdown" | "modal" | "drawer" | "tooltip" | "toast";
  * freed slots are reclaimed automatically because the next z derives from
  * the CURRENT live entries of that band only — no monotonic counter, no
  * cross-band coupling (a persistent toast/tooltip registration can no
- * longer push later modals up the ladder; that ordering bug is what this
- * band scheme replaces). Overlay roots are spaced one Z_STEP apart so each
+ * longer push later modals up the ladder). A dropdown flipping its
+ * blocking flag (anchored popover docking as a sheet, or the reverse)
+ * REBANDS in place: promotion pushes onto the top of the window band
+ * (becoming a window IS a push), demotion lands on the top of the
+ * anchored band. Overlay roots are spaced one Z_STEP apart so each
  * overlay's +1 content/panel layer always has a free slot above its own
  * root and below the next overlay.
  *
@@ -49,6 +57,17 @@ export const POPUP_Z_BANDS: Record<PopupKind, number> = {
   toast: 4000,
 };
 
+/**
+ * The band a popup CURRENTLY stacks in. Dropdown-kind surfaces have two:
+ * the anchored band while attached to an anchor, the WINDOW band
+ * (shared with modals/drawers) while docked as a blocking bottom sheet.
+ * Window kinds always live in the window band.
+ */
+function effectiveBand(kind: PopupKind, blocking: boolean): number {
+  if (kind === "dropdown") return blocking ? POPUP_Z_BANDS.modal : POPUP_Z_BANDS.dropdown;
+  return POPUP_Z_BANDS[kind];
+}
+
 /** 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;
@@ -61,11 +80,15 @@ export interface PopupEntry {
   title?: string;
   /**
    * True while the popup is a blocking window the user "navigates" —
-   * a mobile bottom sheet that rose from a dropdown-kind surface. The
-   * modal-stack breadcrumb lists window kinds (modal/drawer) always and
-   * dropdown kinds only while they block like this; an anchored desktop
-   * popover stays a hidden level. Named surfaces only: a blocking popup
-   * without a title is a naming bug (dev warn at registration).
+   * a mobile bottom sheet that rose from a dropdown-kind surface. This
+   * flag is window-stack MEMBERSHIP: it lists the popup in the
+   * modal-stack breadcrumb AND moves it into the window z band (see
+   * effectiveBand) — a blocking sheet is a window in every sense, so
+   * windows opened from inside it stack above it. Window kinds
+   * (modal/drawer) are windows by kind and always listed; an anchored
+   * desktop popover stays a hidden level. Named surfaces only: a
+   * blocking popup without a title is a naming bug (dev warn at
+   * registration).
    */
   blocking: boolean;
 }
@@ -121,11 +144,14 @@ export function usePopupManager() {
     blocking = false,
   ): PopupHandle {
     const id = uid();
-    const band = POPUP_Z_BANDS[kind];
+    const band = effectiveBand(kind, blocking);
     // Next slot = one step above the highest LIVE entry of the same band.
+    // Band membership follows the entry's CURRENT shape (see
+    // effectiveBand): a blocking sheet scans the window band, so it lands
+    // above every window opened before it.
     let maxSlot = -1;
     for (const entry of registry.value.values()) {
-      if (POPUP_Z_BANDS[entry.kind] !== band) continue;
+      if (effectiveBand(entry.kind, entry.blocking) !== band) continue;
       const slot = (entry.zIndex - band) / POPUP_Z_STEP;
       if (slot > maxSlot) maxSlot = slot;
     }
@@ -151,11 +177,26 @@ export function usePopupManager() {
    * Flip the blocking flag while the popup stays open — a dropdown that
    * docks as a bottom sheet when the viewport crosses the mobile
    * breakpoint becomes a breadcrumb level mid-flight (and back).
+   *
+   * The flip also REBANDS the z: promotion pushes the sheet onto the top
+   * of the window band (becoming a window is a push — it must cover the
+   * page), demotion lands it on the top of the anchored band. The freed
+   * slot in the old band reclaims lazily via the usual max-live-slot
+   * derivation.
    */
   function setBlocking(id: string, blocking: boolean) {
     const entry = registry.value.get(id);
     if (!entry || entry.blocking === blocking) return;
     entry.blocking = blocking;
+    const band = effectiveBand(entry.kind, entry.blocking);
+    let maxSlot = -1;
+    for (const other of registry.value.values()) {
+      if (other === entry) continue;
+      if (effectiveBand(other.kind, other.blocking) !== band) continue;
+      const slot = (other.zIndex - band) / POPUP_Z_STEP;
+      if (slot > maxSlot) maxSlot = slot;
+    }
+    entry.zIndex = band + (maxSlot + 1) * POPUP_Z_STEP;
     registry.value = new Map(registry.value);
     if (blocking) warnUntitled(entry.kind, true, entry.title);
   }