@celestia-island/hikari 0.4.4 → 0.30.0

package/src/runtime/usePopupManager.test.ts

@@ -0,0 +1,200 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { watch } from "vue";
+
+import { POPUP_Z_BANDS, POPUP_Z_STEP, usePopupManager } from "./usePopupManager";
+
+const managers: ReturnType<typeof usePopupManager>[] = [];
+
+function freshManager() {
+  const m = usePopupManager();
+  managers.push(m);
+  return m;
+}
+
+afterEach(() => {
+  // The registry is a module singleton shared across usePopupManager()
+  // instances — unregister everything so tests do not leak z state.
+  for (const m of managers.splice(0)) {
+    for (const entry of [...m.registry.value.values()]) {
+      m.unregister(entry.id);
+    }
+  }
+  document.body.style.overflow = "";
+});
+
+describe("usePopupManager z bands", () => {
+  it("bands are ordered overlay < dropdown < tooltip < toast", () => {
+    expect(POPUP_Z_BANDS.modal).toBe(POPUP_Z_BANDS.drawer);
+    expect(POPUP_Z_BANDS.modal).toBeLessThan(POPUP_Z_BANDS.dropdown);
+    expect(POPUP_Z_BANDS.dropdown).toBeLessThan(POPUP_Z_BANDS.tooltip);
+    expect(POPUP_Z_BANDS.tooltip).toBeLessThan(POPUP_Z_BANDS.toast);
+  });
+
+  it("keeps a toast registered first above overlays opened later", () => {
+    // The mobile regression: HkToast mounts once at shell level, so the
+    // old registration-order ladder gave every later modal a higher z and
+    // buried the toast under the phone bottom sheet. Bands must hold the
+    // toast on top regardless of registration order.
+    const m = freshManager();
+    const toast = m.register("toast", false);
+    expect(toast.zIndex).toBe(POPUP_Z_BANDS.toast);
+
+    const modal = m.register("modal", true);
+    const drawer = m.register("drawer", true);
+    const dropdown = m.register("dropdown", false);
+    expect(modal.zIndex).toBeLessThan(toast.zIndex);
+    expect(drawer.zIndex).toBeLessThan(toast.zIndex);
+    expect(dropdown.zIndex).toBeLessThan(toast.zIndex);
+  });
+
+  it("stacks in open order within a band and reclaims freed slots", () => {
+    const m = freshManager();
+    const a = m.register("modal", true);
+    const b = m.register("modal", true);
+    expect(a.zIndex).toBe(POPUP_Z_BANDS.modal);
+    expect(b.zIndex).toBe(a.zIndex + POPUP_Z_STEP);
+
+    m.unregister(b.id);
+    // C must reclaim B's slot — NOT drift upward past it.
+    const c = m.register("modal", true);
+    expect(c.zIndex).toBe(b.zIndex);
+
+    m.unregister(a.id);
+    m.unregister(c.id);
+    // Band empty again → back to the band base.
+    const d = m.register("modal", true);
+    expect(d.zIndex).toBe(POPUP_Z_BANDS.modal);
+  });
+
+  it("shares the overlay band between modal and drawer in open order", () => {
+    const m = freshManager();
+    const modal = m.register("modal", true);
+    const drawer = m.register("drawer", true);
+    // Same band: the drawer opened over the modal paints above it, and a
+    // replacement drawer reclaims the freed slot instead of drifting.
+    expect(modal.zIndex).toBe(POPUP_Z_BANDS.modal);
+    expect(drawer.zIndex).toBe(modal.zIndex + POPUP_Z_STEP);
+
+    m.unregister(drawer.id);
+    const drawer2 = m.register("drawer", true);
+    expect(drawer2.zIndex).toBe(drawer.zIndex);
+  });
+
+  it("keeps a dropdown opened from within an overlay above it", () => {
+    // Select panels portal to <body>; opened from inside a modal they
+    // must paint above the modal that contains them — the whole reason
+    // the dropdown band sits above the overlay band.
+    const m = freshManager();
+    const modal = m.register("modal", true);
+    const panel = m.register("dropdown", false);
+    expect(panel.zIndex).toBeGreaterThan(modal.zIndex);
+
+    m.unregister(panel.id);
+    m.unregister(modal.id);
+
+    // Same guarantee inverted: with the dropdown registered FIRST, the
+    // later modal still lands on its own (lower) overlay band — band
+    // membership, not registration order, decides.
+    const dropdown = m.register("dropdown", false);
+    const modal2 = m.register("modal", true);
+    expect(dropdown.zIndex).toBe(POPUP_Z_BANDS.dropdown);
+    expect(modal2.zIndex).toBe(POPUP_Z_BANDS.modal);
+    expect(modal2.zIndex).toBeLessThan(dropdown.zIndex);
+  });
+
+  it("keeps tooltips above overlays and below toasts", () => {
+    const m = freshManager();
+    const modal = m.register("modal", true);
+    const tooltip = m.register("tooltip", false);
+    const toast = m.register("toast", false);
+    expect(tooltip.zIndex).toBe(POPUP_Z_BANDS.tooltip);
+    expect(tooltip.zIndex).toBeGreaterThan(modal.zIndex);
+    expect(toast.zIndex).toBeGreaterThan(tooltip.zIndex);
+  });
+
+  it("keeps the scroll lock counter balanced across register/unregister", () => {
+    const m = freshManager();
+    const modal = m.register("modal", true);
+    expect(document.body.style.overflow).toBe("hidden");
+
+    const dropdown = m.register("dropdown", false);
+    m.unregister(dropdown.id);
+    // The modal still locks scroll.
+    expect(document.body.style.overflow).toBe("hidden");
+
+    m.unregister(modal.id);
+    expect(document.body.style.overflow).toBe("");
+  });
+});
+
+describe("usePopupManager blocking flag (breadcrumb levels)", () => {
+  it("defaults to non-blocking and stores explicit blocking", () => {
+    const m = freshManager();
+    const anchored = m.register("dropdown", false);
+    const sheet = m.register("dropdown", false, "Sheet", true);
+    const modal = m.register("modal", true, "Window");
+    expect(m.registry.value.get(anchored.id)!.blocking).toBe(false);
+    expect(m.registry.value.get(sheet.id)!.blocking).toBe(true);
+    // Window kinds list by kind alone; the flag stays false.
+    expect(m.registry.value.get(modal.id)!.blocking).toBe(false);
+  });
+
+  it("setBlocking flips the flag reactively (anchor ↔ sheet morph)", () => {
+    const m = freshManager();
+    const popup = m.register("dropdown", false, "Menu");
+    // Vue reactivity: the reassigned Map must notify registry watchers.
+    const flips: boolean[] = [];
+    const stop = watch(
+      () => m.registry.value.get(popup.id)?.blocking,
+      (v) => { if (v !== undefined) flips.push(v); },
+      { flush: "sync" },
+    );
+    m.setBlocking(popup.id, true);
+    expect(m.registry.value.get(popup.id)!.blocking).toBe(true);
+    m.setBlocking(popup.id, false);
+    expect(m.registry.value.get(popup.id)!.blocking).toBe(false);
+    expect(flips).toEqual([true, false]);
+    stop();
+    // Flipping to the same value is a no-op (no map churn).
+    const before = m.registry.value;
+    m.setBlocking(popup.id, false);
+    expect(m.registry.value).toBe(before);
+  });
+
+  it("dev-warns when a breadcrumb-visible popup registers untitled", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const m = freshManager();
+      m.register("dropdown", false); // anchored popover: fine, hidden level
+      expect(warn).not.toHaveBeenCalled();
+
+      m.register("dropdown", false, undefined, true); // blocking sheet: unnamed
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0][0]).toMatch(/without a title/);
+
+      m.register("modal", true); // window kind: unnamed
+      m.register("drawer", true); // window kind: unnamed
+      expect(warn).toHaveBeenCalledTimes(3);
+
+      warn.mockClear();
+      m.register("modal", true, "Named");
+      m.register("dropdown", false, "Named sheet", true);
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("dev-warns when setBlocking promotes an untitled popup", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const m = freshManager();
+      const popup = m.register("dropdown", false);
+      expect(warn).not.toHaveBeenCalled();
+      m.setBlocking(popup.id, true);
+      expect(warn).toHaveBeenCalledTimes(1);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

package/src/runtime/usePopupManager.ts

@@ -2,16 +2,93 @@ import { readonly, ref } from "vue";
 
 export type PopupKind = "dropdown" | "modal" | "drawer" | "tooltip" | "toast";
 
-interface PopupEntry {
+/**
+ * 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:
+ *
+ *   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
+ *   tooltip  (3000)  transient annotations must stay visible above the
+ *                    surfaces they annotate
+ *   toast    (4000)  ALWAYS the topmost surface — a toast must never be
+ *                    buried under a modal/sheet, no matter which opened
+ *                    first (the long-lived HkToast stack registers once
+ *                    at shell mount and must keep its band forever)
+ *
+ * Within a band, entries stack in open order (max live slot + step), and
+ * 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
+ * overlay's +1 content/panel layer always has a free slot above its own
+ * root and below the next overlay.
+ *
+ * Keep the SCSS fallbacks (`--hi-z-*` / `--hk-z-*` in theme.scss and the
+ * component sheets) in sync with these numbers.
+ */
+export const POPUP_Z_BANDS: Record<PopupKind, number> = {
+  modal: 1000,
+  drawer: 1000,
+  dropdown: 2000,
+  tooltip: 3000,
+  toast: 4000,
+};
+
+/** 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;
+
+export interface PopupEntry {
   id: string;
   kind: PopupKind;
   locksScroll: boolean;
   zIndex: number;
   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).
+   */
+  blocking: boolean;
 }
 
-const Z_BASE = 1000;
-const Z_STEP = 2;
+/**
+ * Dev-time naming enforcement for the window-stack breadcrumb. Any popup
+ * that participates in the breadcrumb (window kinds, or a dropdown that
+ * currently blocks as a sheet) must carry a real, i18n-resolved title —
+ * a bare "Layer N" style fallback is exactly what the strip must never
+ * show. Production builds stay silent; the breadcrumb falls back to a
+ * generic localized label there.
+ */
+function warnUntitled(kind: PopupKind, blocking: boolean, title?: string): void {
+  const stacks = kind === "modal" || kind === "drawer" || blocking;
+  if (!stacks || title) return;
+  if (import.meta.env?.DEV) {
+    console.warn(
+      `[hikari] popup registered without a title (kind: ${kind}). ` +
+        "Window surfaces must pass an i18n-resolved title so the " +
+        "modal-stack breadcrumb can label their layer.",
+    );
+  }
+}
 
 function uid(): string {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
@@ -21,7 +98,6 @@ function uid(): string {
 }
 
 const registry = ref<Map<string, PopupEntry>>(new Map());
-let nextZ = Z_BASE;
 let scrollLockCount = 0;
 
 function updateBodyScroll() {
@@ -42,12 +118,21 @@ export function usePopupManager() {
     kind: PopupKind,
     locksScroll = false,
     title?: string,
+    blocking = false,
   ): PopupHandle {
     const id = uid();
-    const zIndex = nextZ;
-    nextZ += Z_STEP;
-    const entry: PopupEntry = { id, kind, locksScroll, zIndex, title };
+    const band = POPUP_Z_BANDS[kind];
+    // Next slot = one step above the highest LIVE entry of the same band.
+    let maxSlot = -1;
+    for (const entry of registry.value.values()) {
+      if (POPUP_Z_BANDS[entry.kind] !== band) continue;
+      const slot = (entry.zIndex - band) / POPUP_Z_STEP;
+      if (slot > maxSlot) maxSlot = slot;
+    }
+    const zIndex = band + (maxSlot + 1) * POPUP_Z_STEP;
+    const entry: PopupEntry = { id, kind, locksScroll, zIndex, title, blocking };
     registry.value.set(id, entry);
+    warnUntitled(kind, blocking, title);
     if (locksScroll) {
       scrollLockCount++;
       updateBodyScroll();
@@ -62,6 +147,19 @@ export function usePopupManager() {
     registry.value = new Map(registry.value);
   }
 
+  /**
+   * 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).
+   */
+  function setBlocking(id: string, blocking: boolean) {
+    const entry = registry.value.get(id);
+    if (!entry || entry.blocking === blocking) return;
+    entry.blocking = blocking;
+    registry.value = new Map(registry.value);
+    if (blocking) warnUntitled(entry.kind, true, entry.title);
+  }
+
   function unregister(id: string) {
     const entry = registry.value.get(id);
     if (!entry) return;
@@ -70,9 +168,6 @@ export function usePopupManager() {
       scrollLockCount = Math.max(0, scrollLockCount - 1);
       updateBodyScroll();
     }
-    if (registry.value.size === 0) {
-      nextZ = Z_BASE;
-    }
   }
 
   function isOpen(id: string): boolean {
@@ -83,6 +178,7 @@ export function usePopupManager() {
     registry: readonly(registry),
     register,
     setTitle,
+    setBlocking,
     unregister,
     isOpen,
   };

package/src/runtime/useToast.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  MAX_TOASTS_PER_SLOT,
+  useToast,
+} from "./useToast";
+
+function clearAll() {
+  const { toasts, remove } = useToast();
+  for (const t of [...toasts]) remove(t.id);
+}
+
+describe("useToast stacking and dedupe", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    clearAll();
+  });
+  afterEach(() => {
+    clearAll();
+    vi.useRealTimers();
+  });
+
+  it("dedupes identical consecutive messages in the same slot", () => {
+    const toast = useToast();
+    const firstId = toast.error("backend unreachable");
+    const secondId = toast.error("backend unreachable");
+
+    expect(toast.toasts).toHaveLength(1);
+    expect(toast.toasts[0]!.messages).toHaveLength(1);
+    // Replace semantics: the second push returns the existing entry id.
+    expect(secondId).toBe(firstId);
+    expect(toast.toasts[0]!.messages[0]!.text).toBe("backend unreachable");
+  });
+
+  it("keeps distinct consecutive messages", () => {
+    const toast = useToast();
+    toast.error("first");
+    toast.error("second");
+
+    expect(toast.toasts[0]!.messages.map((m) => m.text)).toEqual([
+      "first",
+      "second",
+    ]);
+  });
+
+  it("dedupes only consecutive duplicates", () => {
+    const toast = useToast();
+    toast.error("a");
+    toast.error("b");
+    toast.error("b");
+
+    expect(toast.toasts[0]!.messages.map((m) => m.text)).toEqual(["a", "b"]);
+  });
+
+  it("caps messages per slot at MAX_TOASTS_PER_SLOT, dropping the oldest", () => {
+    const toast = useToast();
+    for (let i = 0; i < MAX_TOASTS_PER_SLOT + 3; i++) {
+      toast.error(`msg-${i}`);
+    }
+
+    expect(toast.toasts[0]!.messages).toHaveLength(MAX_TOASTS_PER_SLOT);
+    const texts = toast.toasts[0]!.messages.map((m) => m.text);
+    expect(texts[0]).toBe("msg-3"); // 0..2 dropped (oldest)
+    expect(texts[texts.length - 1]).toBe(`msg-${MAX_TOASTS_PER_SLOT + 2}`);
+  });
+
+  it("caps each slot independently", () => {
+    const toast = useToast();
+    for (let i = 0; i < MAX_TOASTS_PER_SLOT + 2; i++) toast.error(`e-${i}`);
+    for (let i = 0; i < MAX_TOASTS_PER_SLOT + 2; i++) toast.success(`s-${i}`);
+
+    const errorSlot = toast.toasts.find((t) => t.type === "error")!;
+    const successSlot = toast.toasts.find((t) => t.type === "success")!;
+    expect(errorSlot.messages).toHaveLength(MAX_TOASTS_PER_SLOT);
+    expect(successSlot.messages).toHaveLength(MAX_TOASTS_PER_SLOT);
+  });
+
+  it("dedupe still restarts the auto-dismiss clock (loading never dismisses)", () => {
+    const toast = useToast();
+    toast.info("pulse");
+    const first = toast.toasts[0]!;
+    // info duration is 3000ms — after 1000ms a duplicate push keeps a
+    // single entry; the slot is still present at 2500ms (timer restarted).
+    vi.advanceTimersByTime(1000);
+    toast.info("pulse");
+    expect(toast.toasts[0]!.messages).toHaveLength(1);
+    vi.advanceTimersByTime(2499);
+    expect(toast.toasts.some((t) => t.type === "info")).toBe(true);
+  });
+});

package/src/runtime/useToast.ts

@@ -33,6 +33,11 @@ export interface ToastItem {
   copyable?: boolean;
 }
 
+/** Hard cap on stacked messages per toast slot. Beyond it the oldest
+ *  messages are dropped so a noisy caller cannot bury the surface in
+ *  unbounded history. */
+export const MAX_TOASTS_PER_SLOT = 5;
+
 const state = reactive<{ toasts: ToastItem[] }>({ toasts: [] });
 
 let nextSlotId = 0;
@@ -86,8 +91,21 @@ function push(
   } else if (options.copyable === true && !slot.copyable) {
     slot.copyable = true;
   }
-  const msgId = ++nextMsgId;
-  slot.messages.push({ id: msgId, text });
+  let msgId: number;
+  const last = slot.messages[slot.messages.length - 1];
+  if (last && last.text === text) {
+    // Dedupe: an identical consecutive message (same slot + same text in
+    // the current stack) replaces the previous entry instead of appending —
+    // the surface keeps a single entry and the auto-dismiss clock restarts.
+    msgId = last.id;
+  } else {
+    msgId = ++nextMsgId;
+    slot.messages.push({ id: msgId, text });
+  }
+  // Cap: drop the oldest messages beyond the per-slot cap.
+  while (slot.messages.length > MAX_TOASTS_PER_SLOT) {
+    slot.messages.shift();
+  }
   scheduleAutoDismiss(slot);
   return msgId;
 }