@celestia-island/hikari 0.55.113 → 0.55.114

package/package.json

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