@celestia-island/hikari 0.55.110 → 0.55.111

package/package.json

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

package/src/components/HkFab.test.tsx

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vitest } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
 
 import HkFab from "./HkFab";
+import { POPUP_Z_BANDS } from "../runtime/usePopupManager";
 
 const mounts: ReturnType<typeof createApp>[] = [];
 const containers: HTMLElement[] = [];
@@ -41,8 +42,14 @@ function mountFab(props: Record<string, unknown> = {}): Harness {
   mounts.push(app);
   app.mount(container);
 
-  const root = container.querySelector<HTMLElement>(".hk-fab");
-  const button = container.querySelector<HTMLButtonElement>(".hk-fab-button");
+  // A layer="top" fab teleports into the floating layer on <body>;
+  // fall back to the document scope so both modes resolve.
+  const root =
+    container.querySelector<HTMLElement>(".hk-fab") ??
+    document.body.querySelector<HTMLElement>(".hk-fab");
+  const button =
+    container.querySelector<HTMLButtonElement>(".hk-fab-button") ??
+    document.body.querySelector<HTMLButtonElement>(".hk-fab-button");
   if (!root || !button) throw new Error("HkFab did not render its shell");
   harness.root = root;
   harness.button = button;
@@ -215,3 +222,28 @@ describe("HkFab speed dial", () => {
     expect(toggles).toEqual([true, false, true, false]);
   });
 });
+
+describe("HkFab layer", () => {
+  it("host (default) keeps the fab anchored in the host tree", () => {
+    const m = mountFab({ ariaLabel: "Host", positioning: "fixed" });
+    expect(document.body.querySelector(".hk-floating-layer")).toBeNull();
+    expect(m.root.getAttribute("data-positioning")).toBe("fixed");
+  });
+
+  it("top wraps the fab in an HkFloatingLayer above the window band", () => {
+    const m = mountFab({ ariaLabel: "Float", layer: "top", corner: "bottom-right" });
+    const layer = document.body.querySelector<HTMLElement>(".hk-floating-layer");
+    expect(layer).not.toBeNull();
+    expect(layer!.contains(m.root)).toBe(true);
+    // Geometry is owned by the layer alone once floated.
+    expect(m.root.getAttribute("data-positioning")).toBeNull();
+    expect(m.root.getAttribute("data-corner")).toBeNull();
+    // Offset vars hand off to the layer as well — the fab keeps none.
+    expect(m.root.style.getPropertyValue("--hk-fab-offset-x")).toBe("");
+    expect(m.root.style.getPropertyValue("--hk-fab-offset-y")).toBe("");
+    expect(layer!.getAttribute("data-corner")).toBe("bottom-right");
+    const z = Number(layer!.style.getPropertyValue("--hk-float-z"));
+    expect(z).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+    expect(z).toBeLessThan(POPUP_Z_BANDS.toast);
+  });
+});

package/src/components/HkFab.tsx

@@ -6,6 +6,7 @@ import {
 } from "vue";
 
 import { iconByName } from "../composables/iconRegistry";
+import HkFloatingLayer from "./HkFloatingLayer";
 import "./HkFab.scss";
 
 /** One entry of the HkFab speed dial. */
@@ -21,6 +22,7 @@ type FabCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
 type FabSize = "sm" | "md" | "lg";
 type FabVariant = "primary" | "glass";
 type FabExpandDirection = "up" | "down" | "left" | "right";
+type FabLayer = "host" | "top";
 
 /**
  * Material-design-style floating action button with an optional
@@ -46,6 +48,13 @@ export default defineComponent({
     disabled: { type: Boolean, default: false },
     actions: { type: Array as PropType<HFabAction[]>, default: undefined },
     expandDirection: { type: String as PropType<FabExpandDirection>, default: "up" },
+    /** "top" floats the fab above every window (HkFloatingLayer — the
+     *  popup manager's tooltip band, teleported to <body>): dials stay
+     *  reachable no matter which modal/sheet opens over them. The layer
+     *  owns the geometry when floated — `positioning` is ignored, the
+     *  corner/offset props hand off to it. "host" keeps the classic
+     *  in-tree anchoring (the historical default, byte-identical). */
+    layer: { type: String as PropType<FabLayer>, default: "host" },
   },
   emits: {
     click: (_e: MouseEvent) => true,
@@ -116,6 +125,8 @@ export default defineComponent({
     }
 
     return () => {
+      const floated = props.layer === "top";
+
       // Icon precedence: slot > registry > inline chevron-down fallback.
       // `as any` matches HkIcon — the registry returns a loose Component.
       const RegistryIcon = props.icon ? (iconByName(props.icon) as any) : null;
@@ -144,19 +155,19 @@ export default defineComponent({
         </span>
       );
 
-      return (
+      const fab = (
         <div
           ref={rootRef}
           class="hk-fab"
-          data-positioning={props.positioning}
-          data-corner={props.corner}
+          data-positioning={floated ? undefined : props.positioning}
+          data-corner={floated ? undefined : props.corner}
           data-size={props.size}
           data-variant={props.variant}
           data-expand={props.expandDirection}
           data-expanded={isOpen.value ? "true" : undefined}
           style={{
-            "--hk-fab-offset-x": props.offsetX,
-            "--hk-fab-offset-y": props.offsetY,
+            "--hk-fab-offset-x": floated ? undefined : props.offsetX,
+            "--hk-fab-offset-y": floated ? undefined : props.offsetY,
           }}
         >
           {(props.actions?.length ?? 0) > 0 && (
@@ -196,6 +207,23 @@ export default defineComponent({
           </button>
         </div>
       );
+
+      // Floated: the HkFloatingLayer owns viewport anchoring (corner +
+      // safe-area + tooltip-band z); the fab itself renders bare inside
+      // it (data-positioning/corner stripped above so the geometry is
+      // owned by exactly one layer).
+      if (floated) {
+        return (
+          <HkFloatingLayer
+            corner={props.corner}
+            offsetX={props.offsetX}
+            offsetY={props.offsetY}
+          >
+            {fab}
+          </HkFloatingLayer>
+        );
+      }
+      return fab;
     };
   },
 });

package/src/components/HkFloatingLayer.scss

@@ -0,0 +1,58 @@
+// HkFloatingLayer.scss — top-layer floating chrome.
+//
+// Anchoring mirrors HkFab's safe-area-aware corner insets, extended per
+// instance by --hk-float-offset-*. The z rides the popup manager's
+// tooltip band via --hk-float-z (inline from the component once the
+// registration resolves); the fallback must stay in sync with
+// POPUP_Z_BANDS.tooltip in runtime/usePopupManager.ts.
+.hk-floating-layer {
+  position: fixed;
+  z-index: var(--hk-float-z, 3000);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 0.5rem);
+  pointer-events: none;
+
+  --hk-float-inset-x: max(var(--space-14, 0.875rem), env(safe-area-inset-left, 0px));
+  --hk-float-inset-y: max(var(--space-14, 0.875rem), env(safe-area-inset-bottom, 0px));
+
+  &[data-corner$="-right"] {
+    --hk-float-inset-x: max(var(--space-14, 0.875rem), env(safe-area-inset-right, 0px));
+    right: calc(var(--hk-float-inset-x) + var(--hk-float-offset-x, 0px));
+  }
+
+  &[data-corner$="-left"] {
+    --hk-float-inset-x: max(var(--space-14, 0.875rem), env(safe-area-inset-left, 0px));
+    left: calc(var(--hk-float-inset-x) + var(--hk-float-offset-x, 0px));
+  }
+
+  &[data-corner^="top"] {
+    --hk-float-inset-y: max(var(--space-14, 0.875rem), env(safe-area-inset-top, 0px));
+    top: calc(var(--hk-float-inset-y) + var(--hk-float-offset-y, 0px));
+  }
+
+  &[data-corner^="bottom"] {
+    --hk-float-inset-y: max(var(--space-14, 0.875rem), env(safe-area-inset-bottom, 0px));
+    bottom: calc(var(--hk-float-inset-y) + var(--hk-float-offset-y, 0px));
+  }
+
+  // The layer never eats gestures; the widgets inside do. NOTE: for a
+  // floated HkFab this rule must LOSE to HkFab's own
+  // `.hk-fab { pointer-events: none }` (equal specificity — later sheet
+  // wins — and HkFab.tsx imports this component before its own sheet),
+  // so the fab root stays transparent while its button re-enables.
+  // Do not strengthen this selector or reorder those imports: the
+  // layer's gap boxes would start eating clicks.
+  > * {
+    pointer-events: auto;
+  }
+
+  // A floated HkFab (layer="top") hands viewport anchoring to this
+  // layer entirely: drop its own positioning so its corner lands in
+  // the layer's flow instead of double-resolving the insets.
+  > .hk-fab {
+    position: static;
+    inset: auto;
+    z-index: auto;
+  }
+}

package/src/components/HkFloatingLayer.styles.test.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Compiled-stylesheet contract for HkFloatingLayer. The layer IS its
+ * CSS (fixed positioning, gesture transparency, the > .hk-fab
+ * positioning hand-off), none of which the runtime suite can see —
+ * vitest stubs CSS — so the sheet is compiled and asserted here.
+ */
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+describe("HkFloatingLayer stylesheet contract", () => {
+  const tsx = readFileSync(resolve(componentDir, "HkFloatingLayer.tsx"), "utf8");
+  const css = compile(resolve(componentDir, "HkFloatingLayer.scss"), {
+    style: "expanded",
+  }).css;
+
+  it("compiles the fixed, gesture-transparent top-layer shell", () => {
+    expect(css).toContain(".hk-floating-layer {");
+    expect(css).toContain("position: fixed;");
+    expect(css).toContain("z-index: var(--hk-float-z, 3000);");
+    // The layer never eats gestures; the widgets inside do.
+    expect(css).toContain("pointer-events: none;");
+    expect(css).toContain(".hk-floating-layer > * {");
+    expect(css).toContain("pointer-events: auto;");
+  });
+
+  it("anchors all four corners with safe-area-aware insets", () => {
+    expect(css).toContain('[data-corner$=-right]');
+    expect(css).toContain('[data-corner$=-left]');
+    expect(css).toContain('[data-corner^=top]');
+    expect(css).toContain('[data-corner^=bottom]');
+    for (const side of ["right: calc", "left: calc", "top: calc", "bottom: calc"]) {
+      expect(css).toContain(side);
+    }
+    expect(css).toContain("env(safe-area-inset-left, 0px)");
+    expect(css).toContain("env(safe-area-inset-right, 0px)");
+    expect(css).toContain("env(safe-area-inset-top, 0px)");
+    expect(css).toContain("env(safe-area-inset-bottom, 0px)");
+  });
+
+  it("takes over a floated HkFab's positioning entirely", () => {
+    expect(css).toContain(".hk-floating-layer > .hk-fab {");
+    expect(css).toContain("position: static;");
+    expect(css).toContain("inset: auto;");
+    expect(css).toContain("z-index: auto;");
+  });
+
+  it("has no dead selectors: every rule the sheet emits is rendered", () => {
+    // The TSX must reference every state the sheet styles.
+    expect(tsx).toContain('class="hk-floating-layer"');
+    expect(tsx).toContain("data-corner={props.corner}");
+  });
+});

package/src/components/HkFloatingLayer.test.tsx

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkFloatingLayer from "./HkFloatingLayer";
+import { POPUP_Z_BANDS, usePopupManager } from "../runtime/usePopupManager";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+/** Mount an HkFloatingLayer through a wrapper app (mirrors the
+ *  HkFab.test.tsx harness). The layer teleports its node to <body>,
+ *  so queries go through document.body, not the host container. */
+function mountLayer(props: Record<string, unknown> = {}, slot?: () => unknown) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const Wrapper = defineComponent({
+    setup() {
+      return () => h(HkFloatingLayer, props, slot ? { default: slot } : undefined);
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+
+  return {
+    app,
+    root: () => document.body.querySelector<HTMLElement>(".hk-floating-layer"),
+  };
+}
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  document.body.innerHTML = "";
+});
+
+describe("HkFloatingLayer", () => {
+  it("teleports the corner layer to body with a tooltip-band z slot", () => {
+    const m = mountLayer({ ariaLabel: "Date dial" });
+    const root = m.root();
+    expect(root).not.toBeNull();
+    // Teleported: outside the wrapper's host subtree.
+    expect(containers[0].contains(root!)).toBe(false);
+    expect(root!.getAttribute("data-corner")).toBe("bottom-right");
+    expect(root!.getAttribute("role")).toBe("group");
+    expect(root!.getAttribute("aria-label")).toBe("Date dial");
+    // Inline z from the popup manager registration — inside the
+    // tooltip band, strictly below the toast band.
+    const z = Number(root!.style.getPropertyValue("--hk-float-z"));
+    expect(z).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+    expect(z).toBeLessThan(POPUP_Z_BANDS.toast);
+  });
+
+  it("open=false renders nothing at all", () => {
+    const m = mountLayer({ open: false });
+    expect(m.root()).toBeNull();
+  });
+
+  it("registers exactly one tooltip entry and releases it on unmount", () => {
+    const manager = usePopupManager();
+    const tooltipCount = () => {
+      let n = 0;
+      for (const entry of manager.registry.value.values()) {
+        if (entry.kind === "tooltip") n++;
+      }
+      return n;
+    };
+    const before = tooltipCount();
+    // Non-blocking, untitled chrome must stay silent (a future
+    // warnUntitled change folding tooltip into the naming rule would
+    // dev-warn on every mount — that regression goes red here).
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const m = mountLayer();
+    expect(tooltipCount()).toBe(before + 1);
+    m.app.unmount();
+    mounts.splice(mounts.indexOf(m.app), 1);
+    expect(tooltipCount()).toBe(before);
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("hide releases the slot; re-show re-registers with a fresh band z", async () => {
+    const manager = usePopupManager();
+    const tooltipCount = () => {
+      let n = 0;
+      for (const entry of manager.registry.value.values()) {
+        if (entry.kind === "tooltip") n++;
+      }
+      return n;
+    };
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const visible = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(HkFloatingLayer, { open: visible.value });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+
+    const layer = () => document.body.querySelector<HTMLElement>(".hk-floating-layer");
+    const before = tooltipCount();
+    expect(before).toBeGreaterThanOrEqual(1);
+    const z1 = Number(layer()!.style.getPropertyValue("--hk-float-z"));
+    expect(z1).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+
+    // Hide: the node leaves AND the band slot is released — the
+    // count test above cannot catch this branch on its own (unmount
+    // cleanup would mask it).
+    visible.value = false;
+    await nextTick();
+    expect(tooltipCount()).toBe(before - 1);
+    expect(layer()).toBeNull();
+
+    // Re-show: registered again, first paint already carries the z.
+    visible.value = true;
+    await nextTick();
+    expect(tooltipCount()).toBe(before);
+    const z2 = Number(layer()!.style.getPropertyValue("--hk-float-z"));
+    expect(z2).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+
+    app.unmount();
+    mounts.splice(mounts.indexOf(app), 1);
+    expect(tooltipCount()).toBe(before - 1);
+  });
+
+  it("honours the corner and offset props", () => {
+    const m = mountLayer({ corner: "top-left", offsetX: "1rem", offsetY: "2rem" });
+    const root = m.root()!;
+    expect(root.getAttribute("data-corner")).toBe("top-left");
+    expect(root.style.getPropertyValue("--hk-float-offset-x")).toBe("1rem");
+    expect(root.style.getPropertyValue("--hk-float-offset-y")).toBe("2rem");
+  });
+
+  it("keeps slot content mounted inside the layer", () => {
+    const m = mountLayer({}, () => h("button", { class: "probe" }, "go"));
+    expect(m.root()!.querySelector(".probe")).not.toBeNull();
+  });
+});

package/src/components/HkFloatingLayer.tsx

@@ -0,0 +1,112 @@
+import {
+  defineComponent,
+  onBeforeUnmount,
+  ref,
+  Teleport,
+  watch,
+  type PropType,
+} from "vue";
+
+import { usePopupManager } from "../runtime/usePopupManager";
+import "./HkFloatingLayer.scss";
+
+type FloatCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
+/**
+ * HkFloatingLayer — viewport-fixed chrome that floats at the TOP layer.
+ *
+ * The dial/FAB problem this solves: always-reachable chrome anchored to
+ * a page (or a window) dies the moment a real window opens over it —
+ * either it is buried under the modal overlay (page pads), or it gets
+ * re-rendered as an in-window copy that no longer shares the page's
+ * geometry (the per-modal dial copies this layer replaces). Floating at
+ * the popup manager's tooltip band makes the chrome independent of the
+ * window stack, exactly like a tooltip: above every modal/drawer
+ * overlay, below toasts, present on its own merits.
+ *
+ * Mechanics:
+ *   - Teleported to <body>, so no transformed ancestor (morph tabs,
+ *     modal content frames) can re-anchor or clip a `position: fixed`
+ *     child, and the layer resolves against the viewport full stop.
+ *   - Registered with the popup manager (kind "tooltip", non-blocking,
+ *     no scroll lock, no breadcrumb title): the z slot derives from the
+ *     live registry instead of a magic constant, and the layer shows up
+ *     in `readHkRuntime("popupManager")` like every other surface.
+ *   - The layer itself is gesture-transparent (pointer-events: none);
+ *     the widgets inside catch their own pointers.
+ *   - Corner insets mirror HkFab's safe-area-aware math, extended per
+ *     instance by the offset props.
+ *
+ *   - Within the tooltip band, stacking is open-order (the manager's
+ *     rule): a tooltip that registered later paints above this chrome
+ *     near the corner, and a layer mounted after a live tooltip paints
+ *     above it — transient vs persistent chrome trades locally. Do not
+ *     "fix" this with a magic z. Two layers at one corner overlap;
+ *     pass offsets to stack them deliberately.
+ *   - While a modal is open, the modal's focus trap keeps this chrome
+ *     pointer-reachable but NOT keyboard-reachable — the standing
+ *     tradeoff for floating chrome; a focus relay is out of scope.
+ *
+ * Consumers: the shell's quick-action pad, a modal's detached date dial
+ * (via `HkFab layer="top"` or direct use) — anything that must survive
+ * the next window opening on top of it.
+ */
+export default defineComponent({
+  name: "HkFloatingLayer",
+  props: {
+    /** False unmounts the teleported layer and releases its band slot
+     *  (true = always shown). House `open` convention, like every other
+     *  hikari surface. */
+    open: { type: Boolean, default: true },
+    corner: { type: String as PropType<FloatCorner>, default: "bottom-right" },
+    offsetX: { type: String, default: undefined },
+    offsetY: { type: String, default: undefined },
+    /** Accessible group name for the chrome (e.g. "Date dial"). */
+    ariaLabel: { type: String, default: "" },
+  },
+  setup(props, { slots }) {
+    const { register, unregister } = usePopupManager();
+    const handle = ref<{ id: string; zIndex: number } | null>(null);
+
+    // 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.
+    watch(
+      () => props.open,
+      (show) => {
+        if (show && !handle.value) handle.value = register("tooltip", false);
+        else if (!show && handle.value) {
+          unregister(handle.value.id);
+          handle.value = null;
+        }
+      },
+      { immediate: true },
+    );
+    onBeforeUnmount(() => {
+      if (handle.value) unregister(handle.value.id);
+      handle.value = null;
+    });
+
+    return () => {
+      if (!props.open) return null;
+      return (
+        <Teleport to="body">
+          <div
+            class="hk-floating-layer"
+            data-corner={props.corner}
+            role={props.ariaLabel ? "group" : undefined}
+            aria-label={props.ariaLabel || undefined}
+            style={{
+              "--hk-float-z": handle.value ? String(handle.value.zIndex) : undefined,
+              "--hk-float-offset-x": props.offsetX,
+              "--hk-float-offset-y": props.offsetY,
+            }}
+          >
+            {slots.default?.()}
+          </div>
+        </Teleport>
+      );
+    };
+  },
+});

package/src/index.ts

@@ -689,6 +689,7 @@ export { default as HkDrawer } from "./components/HkDrawer";
 export { default as HkEmptyState } from "./components/HkEmptyState";
 export { default as HkExpansionPanel } from "./components/HkExpansionPanel";
 export { default as HkFab } from "./components/HkFab";
+export { default as HkFloatingLayer } from "./components/HkFloatingLayer";
 export { default as HkIcon } from "./components/HkIcon";
 export { default as HkIconButton } from "./components/HkIconButton";
 export { default as HkIconButtonGroup } from "./components/HkIconButtonGroup";