@celestia-island/hikari 0.55.118 → 0.55.121

package/package.json

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

package/src/components/HkCopyBadge.tsx

@@ -1,7 +1,7 @@
 import { computed, defineComponent, ref, type PropType } from "vue";
 
 import HBadge, { type BadgeVariant } from "./HkBadge";
-import HTooltip from "./HkTooltip";
+import HTooltip, { type HkTooltipSlotProps } from "./HkTooltip";
 import { useI18n } from "../i18n/context";
 import { useClipboardWithToast } from "../runtime/useClipboard";
 import { useToast } from "../runtime/useToast";
@@ -140,7 +140,7 @@ export default defineComponent({
       if (props.disabled) return buildBadge();
       return (
         <HTooltip text={tooltipText.value}>
-          {(tip: { popupId: string; visible: boolean }) =>
+          {(tip?: HkTooltipSlotProps) =>
             buildBadge(tip?.visible ? tip.popupId : undefined)}
         </HTooltip>
       );

package/src/components/HkModal.scss

@@ -434,7 +434,10 @@
 //     detail sheet never carries a screenful of dead body)
 //   - never grows past the top band reserved for the secondary-window
 //     breadcrumb strip (--hk-sheet-top-inset; default 4.25rem keeps the
-//     floating breadcrumb visible above a full-height sheet)
+//     floating breadcrumb visible above a full-height sheet, and the
+//     strip itself PUBLISHES this property on <body> while it is up —
+//     its live "own height + one gap above + one gap below" — so the
+//     band tracks the real chrome instead of a static guess)
 //   - rounded top corners only, full width
 // ------
 @media (max-width: 767px) {
@@ -536,12 +539,16 @@
     // inside once the cap is hit); they no longer stretch it.
     // Plain-vh fallback first: dvh-less engines (older Android WebView /
     // Tauri) would drop the whole dvh calc and leave the sheet uncapped.
+    // !important on BOTH: an inline max-height (a host's `style` pass, a
+    // size prop's own cap) must lose to the family band — the strip's
+    // daylight is a guarantee, not a default (HkDrawer parity, 2026-10-05
+    // mobile report: a tall sheet covered the strip's band).
     max-height: calc(
       100vh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0px)
-    );
+    ) !important;
     max-height: calc(
       100dvh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0px)
-    );
+    ) !important;
   }
 
   // Sheet slide reveal replaces the height-clip reveal on mobile.

package/src/components/HkModal.sheetgap.test.ts

@@ -74,6 +74,21 @@ describe("HkModal mobile sheet spacing contract", () => {
       expect(content).not.toMatch(/max-height:\s*none/);
     });
 
+    // 2026-10-05 mobile report: a tall sheet covered the breadcrumb's band.
+    // The drawer cap has carried !important for exactly this reason (the
+    // inline maxHeight from a `size` prop must lose to the family band —
+    // HkDrawer.sheetfamily pins its side); the modal cap must not be the
+    // weak sibling. Any host style/prop pass writing max-height inline
+    // would silently uncap the sheet and swallow the strip's band.
+    it("beats inline max-heights with !important on both caps", () => {
+      // [^;]+ runs to the declaration's own semicolon, so the assertion
+      // sees whatever sits between the closing paren and it.
+      const vh = content.match(/max-height: calc\(\s*100vh - var\(--hk-sheet-top-inset[^;]+/)?.[0] ?? "";
+      const dvh = content.match(/max-height: calc\(\s*100dvh - var\(--hk-sheet-top-inset[^;]+/)?.[0] ?? "";
+      expect(vh, "plain-vh fallback cap").toContain("!important");
+      expect(dvh, "dvh cap").toContain("!important");
+    });
+
     // 2026-09-21 phone-sheet transition contract (two Xiaomi WebView
     // chest reports the same day): the mobile list carries ONLY the
     // clip-path reveal.

package/src/components/HkModalBreadcrumb.test.tsx

@@ -18,6 +18,9 @@ afterEach(async () => {
     manager.unregister(entry.id);
   }
   document.body.style.overflow = "";
+  // The strip publishes its sheet top band on <body> inline while up —
+  // strip it here too, or one test's band leaks into the next.
+  document.body.style.removeProperty("--hk-sheet-top-inset");
   window.innerWidth = originalWidth;
   // happy-dom never fires transitionend, so a popover's leave never settles
   // and its teleported panel lingers on <body> — strip it, or the next
@@ -680,6 +683,11 @@ describe("HkModalBreadcrumb overflow fold", () => {
       // 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");
+      // The published sheet band rides the same conversions: strip centre
+      // 44 + its local half-height (88 visual / 2 zoom) / 2 = 22 + one gap
+      // 12 — a zoom-blind band would read 78 ± (zoom−1)·Δ and drift the
+      // sheet cap against the strip on zoomed hosts.
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("78px");
     } finally {
       vi.restoreAllMocks();
       app.remove();
@@ -731,6 +739,51 @@ describe("HkModalBreadcrumb overflow fold", () => {
     }
   });
 
+  it("publishes the sheet top band while up and clears it with the strip", async () => {
+    // The strip is the authority on its own band: while it is up, mobile
+    // bottom sheets must stop below "strip bottom edge + one more gap" —
+    // the sheet family consumes --hk-sheet-top-inset as exactly that
+    // line, so the strip PUBLISHES it on <body> (inline beats a host's
+    // :root token while up) and withdraws it when the strip goes away.
+    // Boxless DOM → fallback geometry: band = topPx + 43/2 + gap.
+    const app = document.createElement("div");
+    app.id = "app";
+    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();
+      // 0 (app top) + max(24, 12 + 21.5) + 21.5 + 12.
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("67px");
+
+      // Unmounting a visible strip withdraws the band synchronously
+      // (onBeforeUnmount) — a stale band must not outlive its publisher
+      // (mutation round M5: removing the unmount clear passed everything
+      // else green).
+      unmountAll();
+      await nextTick();
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("");
+
+      // A host wanting more air raises the gap; the band follows it.
+      await mountStrip({ topGap: 40 });
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("123px");
+
+      // The promise lives with the strip: drop back to a single layer and
+      // the property is withdrawn — the host token rules again.
+      const entries = [...manager.registry.value.values()];
+      manager.unregister(entries[entries.length - 1].id);
+      await until(() => strip() === null);
+      expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("");
+    } 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
@@ -745,11 +798,16 @@ describe("HkModalBreadcrumb overflow fold", () => {
     manager.register("modal", true, "第二层");
     await mountStrip({ appRootId: "no-such-root" });
     expect(strip()!.style.top).toBe("33.5px");
+    // The band promise holds on the fallbacks too (no app root is no
+    // excuse for going quiet while the sheets are watching):
+    // 33.5 + 43/2 + 12.
+    expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("67px");
     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");
+    expect(document.body.style.getPropertyValue("--hk-sheet-top-inset")).toBe("43px");
   });
 
   it("writes the viewport fence in the strip's own px", async () => {

package/src/components/HkModalBreadcrumb.tsx

@@ -407,9 +407,32 @@ export default defineComponent({
      *  layout fallbacks (48px header, 43px strip). The first nextTick
      *  resync replaces it with measured numbers. */
     const topPx = ref(topGapPx.value + STRIP_HEIGHT_PX / 2);
+
+    /** Publish the sheet top band: while the strip is up, mobile bottom
+     *  sheets must stop BELOW the strip's bottom edge plus one more gap —
+     *  "the strip's own height, with one gap above and one below". The
+     *  sheet family consumes this exact custom property as its mobile
+     *  max-height inset (--hk-sheet-top-inset), so publishing it here
+     *  turns every host's static guess into the strip's live geometry.
+     *  Written on <body> inline (beats a host's :root token while up;
+     *  removed when the strip goes away so the host token rules again),
+     *  in the strip's LOCAL px — the sheets teleport into the same zoomed
+     *  subtree, so one px space is shared. */
+    function publishBand(bandPx: number | null): void {
+      if (typeof document === "undefined") return;
+      if (bandPx == null) document.body.style.removeProperty("--hk-sheet-top-inset");
+      else document.body.style.setProperty("--hk-sheet-top-inset", `${bandPx}px`);
+    }
+
     function resyncTop() {
       const app = document.getElementById(props.appRootId);
-      if (!app) return;
+      if (!app) {
+        // No app root to measure: the strip still paints on the fallback
+        // geometry (the init ref), so keep the band promise on those same
+        // fallbacks instead of going quiet while the sheets are watching.
+        publishBand(topPx.value + STRIP_HEIGHT_PX / 2 + topGapPx.value);
+        return;
+      }
       // The strip teleports to <body> — inside any root CSS zoom subtree
       // — so its inline top is LOCAL px. Keep every term in that local
       // space: the app root's computed top is already local, while the
@@ -442,6 +465,9 @@ export default defineComponent({
       // 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);
+      // The band: strip bottom edge plus one more gap — the lowest line a
+      // bottom sheet may reach while the strip is up.
+      publishBand(topPx.value + stripH / 2 + topGapPx.value);
     }
 
     /** Viewport fence, in the strip's OWN px. The stylesheet cap is
@@ -524,6 +550,9 @@ export default defineComponent({
           menuOpen.value = false;
           revealed.value = null;
           hiddenCount.value = 0;
+          // The band is the strip's live promise to the sheet family: with
+          // the strip gone the host's own static token rules again.
+          publishBand(null);
         }
       },
       { immediate: true },
@@ -553,6 +582,9 @@ export default defineComponent({
       if (handle) handle.disconnect();
       window.removeEventListener("resize", onViewportChange);
       releaseClone();
+      // A mounted-but-gone strip must not leave its band behind: the host's
+      // static token rules again (same contract as the visible flip).
+      publishBand(null);
     });
 
     const itemClass = (crumb: Crumb) =>

package/src/components/HkTooltip.test.tsx

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick } from "vue";
 
-import HkTooltip from "./HkTooltip";
+import HkTooltip, { type HkTooltipSlotProps } from "./HkTooltip";
 import { POPUP_Z_BANDS, POPUP_Z_STEP, usePopupManager } from "../runtime/usePopupManager";
 
 /**
@@ -176,18 +176,19 @@ describe("HkTooltip show/hide", () => {
   it("hands { popupId, visible } to the default slot for focus-target wiring", async () => {
     const container = document.createElement("div");
     document.body.appendChild(container);
-    let seen: { popupId?: string; visible?: boolean } = {};
+    let seen: Partial<HkTooltipSlotProps> = {};
     const app = createApp({
       render: () =>
         h(
           HkTooltip,
-          { text: "slot props", delay: 0 } as never,
-          // The scoped-slot child needs a cast: HkTooltip does not declare
-          // slot prop types, so h() types the default slot as no-arg.
-          ((slotProps: { popupId: string; visible: boolean }) => {
+          { text: "slot props", delay: 0 },
+          // Object-form scoped slot; the arg type comes from the local
+          // annotation against the exported contract (h()'s RawSlots has
+          // no SlotsType-aware overload), not from the slots declaration.
+          { default: (slotProps: HkTooltipSlotProps) => {
             seen = slotProps;
             return h("span", { class: "anchor-probe" }, "anchor");
-          }) as never,
+          } },
         ),
     });
     app.mount(container);

package/src/components/HkTooltip.tsx

@@ -1,8 +1,20 @@
-import { computed, defineComponent, onBeforeUnmount, ref, Teleport, type CSSProperties, type PropType } from "vue";
+import { computed, defineComponent, onBeforeUnmount, ref, Teleport, type CSSProperties, type PropType, type SlotsType } from "vue";
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { applyTooltipPosition, type TooltipPlacement } from "../runtime/tooltipPosition";
 import "./HkTooltip.scss";
 
+/**
+ * The default-slot payload, handed to every render of the trigger. An
+ * interactive trigger should bind `popupId` onto itself via
+ * aria-describedby while `visible` is true — the focus target is the
+ * trigger element, not this component's wrapper (HkCopyBadge is the
+ * reference consumer).
+ */
+export interface HkTooltipSlotProps {
+  popupId: string;
+  visible: boolean;
+}
+
 let popupSeq = 0;
 
 export default defineComponent({
@@ -13,6 +25,9 @@ export default defineComponent({
     delay: { type: Number, default: 300 },
     maxWidth: { type: String, default: undefined },
   },
+  slots: Object as SlotsType<{
+    default?: (props: HkTooltipSlotProps) => unknown;
+  }>,
   setup(props, { slots }) {
     const visible = ref(false);
     // Stable id for the aria-describedby link from the trigger wrapper to

package/src/index.ts

@@ -752,6 +752,7 @@ export { default as HkFileBrowserDialog } from "./components/HkFileBrowserDialog
 export { default as HkFilePickerField } from "./components/HkFilePickerField";
 export { default as HkToast } from "./components/HkToast";
 export { default as HkTooltip } from "./components/HkTooltip";
+export { type HkTooltipSlotProps } from "./components/HkTooltip";
 export { default as HkTree } from "./components/HkTree";
 export { default as HkWindowedItem } from "./components/HkWindowedItem";
 export { default as HkWaterfall } from "./components/HkWaterfall";