@celestia-island/hikari 0.55.295 → 0.55.298

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.295",
+  "version": "0.55.298",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkAdminTablePage.tsx

@@ -1,16 +1,7 @@
-import {
-  defineComponent,
-  inject,
-  onMounted,
-  onUnmounted,
-  ref,
-  type Component,
-  type PropType,
-} from "vue";
+import { defineComponent, type Component, type PropType } from "vue";
 import { HAlert, HCard, HEmptyState, HSpinner, HTable, useI18n } from "@celestia-island/hikari";
 import HkCrossfade from "./HkCrossfade";
 import { HkPageHeader } from "./HkPageHeader";
-import { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressHandle } from "./HkScrollProgress";
 import type { HkRowManageGate } from "./HkTable";
 
 
@@ -76,9 +67,9 @@ export const HkAdminTablePage = defineComponent({
     },
     /** Authoritative row total the scroll-progress pill uses as its
      *  denominator (the server count behind a paged list — chest's
-     *  usePagedTableFetch total). Omitted: the pill falls back to
-     *  counting the delivered DOM rows. Registration into the
-     *  enclosing shell viewport is automatic (see setup). */
+     *  usePagedTableFetch total). Forwarded to HTable, which
+     *  self-registers with the enclosing shell viewport's registrar.
+     *  Omitted: the pill falls back to counting the delivered DOM rows. */
     total: { type: Number, default: undefined },
   },
   emits: {
@@ -86,28 +77,6 @@ export const HkAdminTablePage = defineComponent({
     manage: (_row: Record<string, unknown>, _opener: HTMLElement) => true,
   },
   setup(props, { emit, slots }) {
-    // Scroll-progress registration: the nearest enclosing HkScrollContainer
-    // with `scrollProgress` on provides the registrar (provide/inject
-    // scoping resolves the shell viewport for admin pages and keeps an
-    // inner container's lists out of the shell). The handle exposes the
-    // table card as the row root plus the `total` prop live — the pill's
-    // denominator follows it as pages load.
-    const registrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
-    const tableCardRef = ref<HTMLElement | null>(null);
-    let handle: HkScrollProgressHandle | null = null;
-    onMounted(() => {
-      if (!registrar) return;
-      handle = {
-        getRoot: () => tableCardRef.value,
-        getTotal: () => props.total,
-      };
-      registrar.register(handle);
-    });
-    onUnmounted(() => {
-      if (registrar && handle) registrar.unregister(handle);
-      handle = null;
-    });
-
     return () => {
       const { t } = useI18n();
       const emptyTitle = props.emptyTitle || t("hikari::tablePage.emptyTitle", "No data");
@@ -165,23 +134,22 @@ export const HkAdminTablePage = defineComponent({
             ) : slots.body ? (
               <div class="hk-admin-table-page-body">{slots.body()}</div>
             ) : (
-              <div ref={tableCardRef} class="hk-admin-table-page-tablecard">
-                <HCard padded={false}>
-                  <HTable
-                    columns={props.columns}
-                    rows={props.rows}
-                    rowKey={props.rowKey}
-                    draggable={props.draggable}
-                    manageable={props.manageable}
-                    onReorder={(from: number, to: number) => emit("reorder", from, to)}
-                    onManage={(row: Record<string, unknown>, opener: HTMLElement) =>
-                      emit("manage", row, opener)
-                    }
-                  >
-                    {slots}
-                  </HTable>
-                </HCard>
-              </div>
+              <HCard padded={false}>
+                <HTable
+                  columns={props.columns}
+                  rows={props.rows}
+                  rowKey={props.rowKey}
+                  total={props.total}
+                  draggable={props.draggable}
+                  manageable={props.manageable}
+                  onReorder={(from: number, to: number) => emit("reorder", from, to)}
+                  onManage={(row: Record<string, unknown>, opener: HTMLElement) =>
+                    emit("manage", row, opener)
+                  }
+                >
+                  {slots}
+                </HTable>
+              </HCard>
             )}
           </HkCrossfade>
           {slots["create-modal"]?.()}

package/src/components/HkDrawer.test.tsx

@@ -146,3 +146,60 @@ describe("HkDrawer window-stack close channel", () => {
     }
   });
 });
+
+describe("HkDrawer Escape precedence", () => {
+  async function settle(): Promise<void> {
+    await nextTick();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await nextTick();
+  }
+
+  it("lets a nested control own Escape while a bare Escape still closes", async () => {
+    const open = ref(true);
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkDrawer, {
+            modelValue: open.value,
+            closable: true,
+            title: "Inspector",
+            "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+          }, {
+            default: () => h("div", {
+              class: "escape-owner",
+              onKeydown: (e: KeyboardEvent) => {
+                if (e.key === "Escape") e.preventDefault();
+              },
+            }, "nested control"),
+          });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    await settle();
+
+    const owner = document.body.querySelector<HTMLElement>(".hk-drawer-panel .escape-owner");
+    expect(owner, "the slot content renders inside the panel").not.toBeNull();
+
+    // `cancelable: true` is load-bearing: preventDefault() on a non-cancelable
+    // synthetic event is a no-op, and the drawer would then close as if
+    // nothing had consumed the key.
+    owner!.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true }),
+    );
+    await settle();
+    expect(open.value, "a consumed Escape must not close the drawer").toBe(true);
+
+    // A bare Escape (nothing below consumed it) still closes.
+    const panel = document.body.querySelector<HTMLElement>(".hk-drawer-panel")!;
+    panel.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true }),
+    );
+    await settle();
+    expect(open.value).toBe(false);
+  });
+});

package/src/components/HkDrawer.tsx

@@ -211,7 +211,12 @@ export default defineComponent({
       if (props.closable && props.overlay) close();
     }
 
-    function onEscape() {
+    function onEscape(e: KeyboardEvent) {
+      // Precedence (the same class as HkModal's 0.55.295 fix): a nested
+      // control that already consumed Escape owns the key, so the drawer
+      // must not close underneath it. Precedence only — this surface has
+      // never preventDefault'd/stopPropagation'd Escape, and still does not.
+      if (e.defaultPrevented) return;
       if (props.closable) close();
     }
 
@@ -300,7 +305,7 @@ export default defineComponent({
               aria-modal={props.overlay}
               tabindex={-1}
               onKeydown={(e: KeyboardEvent) => {
-                if (e.key === "Escape") onEscape();
+                if (e.key === "Escape") onEscape(e);
                 else if (e.key === "Tab" && panelRef.value) trapFocus(panelRef.value, e);
               }}
             >

package/src/components/HkImageLightbox.test.tsx

@@ -90,6 +90,29 @@ describe("HkImageLightbox", () => {
     expect(s.emitted).toEqual([false]);
   });
 
+  it("a nested consumed Escape does not close the lightbox", async () => {
+    const s = mountLightbox(true);
+    const dialog = s.dialog()!;
+    const owner = dialog.querySelector<HTMLElement>(".hk-image-viewer-img")!;
+    // Model a nested control that owns Escape. `cancelable: true` is
+    // load-bearing: preventDefault() on a non-cancelable event is a no-op.
+    owner.addEventListener("keydown", (e) => {
+      if (e.key === "Escape") e.preventDefault();
+    }, { once: true });
+
+    owner.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true }),
+    );
+    await nextTick();
+    expect(s.emitted, "a consumed Escape must not close the lightbox").toEqual([]);
+    expect(s.dialog()).not.toBeNull();
+
+    // A bare Escape (nothing below consumed it) still closes.
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", cancelable: true }));
+    await nextTick();
+    expect(s.emitted).toEqual([false]);
+  });
+
   it("the Escape listener is removed once closed (no stray closes)", async () => {
     const s = mountLightbox(true);
 

package/src/components/HkImageLightbox.tsx

@@ -37,7 +37,12 @@ export default defineComponent({
     }
 
     function onWindowKeydown(e: KeyboardEvent) {
-      if (e.key === "Escape") close();
+      // A nested control that consumed Escape owns the key. This listener
+      // sits on `window`, i.e. LAST in the bubble path, so
+      // `event.defaultPrevented` is the cross-component signal (same
+      // precedence rule as HkModal's 0.55.295 fix).
+      if (e.key !== "Escape" || e.defaultPrevented) return;
+      close();
     }
 
     watch(

package/src/components/HkPopover.escape.test.tsx

@@ -0,0 +1,155 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref, type Ref } from "vue";
+
+import HkPopover from "./HkPopover";
+
+/**
+ * HkPopover Escape precedence (the same class as HkModal 0.55.295 and the
+ * HkDrawer / HkImageLightbox siblings).
+ *
+ * The popover panel hosts the consumer's DEFAULT SLOT, so it is a
+ * composition surface: a control inside it may consume Escape first
+ * (HkRangeRibbon resetting a brushed range, a date-picker trigger, a tag
+ * search). The popover must honour that consumption instead of closing the
+ * panel underneath the control. Its own consumption is unchanged — when it
+ * does close it still preventDefaults and still does not stopPropagation.
+ */
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  document.body
+    .querySelectorAll(".hk-popover-panel, .hk-popover-scrim")
+    .forEach((el) => el.remove());
+});
+
+async function settle(): Promise<void> {
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await nextTick();
+}
+
+interface Setup {
+  open: Ref<boolean>;
+  emitted: boolean[];
+  panel: () => HTMLElement | null;
+  owner: () => HTMLElement | null;
+}
+
+function mountPopover(options: { closeOnEscape?: boolean } = {}): Setup {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const open = ref(true);
+  const emitted: boolean[] = [];
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkPopover as never, {
+          modelValue: open.value,
+          title: "probe",
+          closeOnEscape: options.closeOnEscape ?? true,
+          "onUpdate:modelValue": (v: boolean) => { emitted.push(v); open.value = v; },
+        }, {
+          default: () => h("div", {
+            class: "escape-owner",
+            onKeydown: (e: KeyboardEvent) => {
+              if (e.key === "Escape") e.preventDefault();
+            },
+          }, "nested control"),
+        });
+    },
+  });
+  const app = createApp(Wrapper);
+  app.mount(container);
+  mounts.push({ app, container });
+  return {
+    open,
+    emitted,
+    panel: () => document.body.querySelector<HTMLElement>(".hk-popover-panel"),
+    owner: () => document.body.querySelector<HTMLElement>(".hk-popover-panel .escape-owner"),
+  };
+}
+
+describe("HkPopover Escape precedence", () => {
+  it("lets a nested slot control own Escape", async () => {
+    const s = mountPopover();
+    await settle();
+    const owner = s.owner();
+    expect(owner, "the slot control renders inside the panel").not.toBeNull();
+
+    // `cancelable: true` is load-bearing: preventDefault() on a
+    // non-cancelable synthetic event is a no-op, and the popover would then
+    // close as if nothing had consumed the key.
+    owner!.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true }),
+    );
+    await settle();
+
+    expect(s.emitted, "a consumed Escape must not close the popover").toEqual([]);
+    expect(s.open.value).toBe(true);
+    expect(s.panel(), "the panel stays mounted").not.toBeNull();
+  });
+
+  it("a bare Escape still closes, is consumed, and is not stopPropagation'd", async () => {
+    const s = mountPopover();
+    await settle();
+    const panel = s.panel();
+    expect(panel, "the panel renders").not.toBeNull();
+
+    const bare = new KeyboardEvent("keydown", {
+      key: "Escape",
+      bubbles: true,
+      cancelable: true,
+    });
+    let propagatedToDocument = false;
+    const onDocumentKeydown = () => {
+      propagatedToDocument = true;
+    };
+    document.addEventListener("keydown", onDocumentKeydown);
+    try {
+      panel!.dispatchEvent(bare);
+    } finally {
+      document.removeEventListener("keydown", onDocumentKeydown);
+    }
+    await settle();
+
+    expect(s.emitted).toEqual([false]);
+    expect(s.open.value).toBe(false);
+    // The popover's own consumption, unchanged by the precedence guard.
+    expect(bare.defaultPrevented, "the popover still consumes the key it acts on").toBe(true);
+    expect(propagatedToDocument, "the popover still does not stopPropagation").toBe(true);
+  });
+
+  it("closeOnEscape=false never closes, bare or consumed", async () => {
+    const s = mountPopover({ closeOnEscape: false });
+    await settle();
+    const owner = s.owner();
+    const panel = s.panel();
+    expect(owner, "the slot control renders inside the panel").not.toBeNull();
+    expect(panel, "the panel renders").not.toBeNull();
+
+    // A consumed Escape changes nothing either way. This also pins the
+    // invariant that lets a future refactor hoist the defaultPrevented
+    // guard above the closeOnEscape check safely: close() must stay gated
+    // on the prop, and this case proves that gate is load-bearing.
+    owner!.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true }),
+    );
+    await settle();
+
+    const bare = new KeyboardEvent("keydown", {
+      key: "Escape",
+      bubbles: true,
+      cancelable: true,
+    });
+    panel!.dispatchEvent(bare);
+    await settle();
+
+    expect(s.emitted).toEqual([]);
+    expect(s.open.value).toBe(true);
+    expect(bare.defaultPrevented, "no close => no consumption").toBe(false);
+  });
+});

package/src/components/HkPopover.tsx

@@ -627,6 +627,14 @@ export default defineComponent({
 
     function onPanelKeydown(e: KeyboardEvent) {
       if (e.key === "Escape" && props.closeOnEscape) {
+        // Precedence (the same class as HkModal 0.55.295 and the
+        // HkDrawer / HkImageLightbox siblings): the panel hosts the
+        // consumer's default slot, so a control inside it that already
+        // consumed Escape (preventDefault) owns the key — the popover must
+        // not close underneath it. The popover's own consumption is
+        // unchanged: it still preventDefaults when it closes, and it has
+        // never stopped propagation.
+        if (e.defaultPrevented) return;
         e.preventDefault();
         close();
       }

package/src/components/HkRangeRibbon.test.tsx

@@ -1149,6 +1149,23 @@ describe("HkRangeRibbon a11y and i18n", () => {
     expect(host.windowChange).not.toHaveBeenCalled();
     expect(laneSegments(host.root)).toHaveLength(4);
   });
+
+  it("does not advertise the range affordance when the window is disabled", () => {
+    const disabled = mountRibbon({ windowEnabled: false, window: null });
+    const disabledStrip = disabled.querySelector<HTMLElement>(".hk-range-ribbon-strip")!;
+    expect(disabledStrip.hasAttribute("title"), "no drag hint on a disabled strip").toBe(false);
+    expect(disabledStrip.hasAttribute("aria-describedby"), "nothing to describe").toBe(false);
+    expect(disabled.querySelector(".hk-range-ribbon-hint"), "no sr-only hint").toBeNull();
+
+    // The enabled ribbon still carries all three.
+    const enabled = mountRibbon({ window: null });
+    const enabledStrip = enabled.querySelector<HTMLElement>(".hk-range-ribbon-strip")!;
+    expect(enabledStrip.getAttribute("title")).toContain("Drag to select a range");
+    const describedBy = enabledStrip.getAttribute("aria-describedby");
+    expect(describedBy, "the enabled strip describes its keyboard contract").toBeTruthy();
+    expect(document.getElementById(describedBy!), "the hint element exists").toBeTruthy();
+    expect(enabled.querySelector(".hk-range-ribbon-hint")).toBeTruthy();
+  });
 });
 
 // ── Controlled / uncontrolled switch ────────────────────────────────────

package/src/components/HkRangeRibbon.tsx

@@ -578,7 +578,7 @@ export default defineComponent({
           aria-orientation="horizontal"
           tabindex={props.windowEnabled ? 0 : -1}
           aria-label={t("hikari::ribbon.rangeAria", "Observation range")}
-          aria-describedby={hintId}
+          aria-describedby={props.windowEnabled ? hintId : undefined}
           aria-disabled={props.windowEnabled ? undefined : "true"}
           aria-valuemin={0}
           aria-valuemax={100}
@@ -586,10 +586,14 @@ export default defineComponent({
           aria-valuetext={`${Math.round((win ? win[0] : 0) * 100)}% – ${Math.round(
             (win ? win[1] : 1) * 100,
           )}%`}
-          title={t(
-            "hikari::ribbon.dragHint",
-            "Drag to select a range; double-click, Escape or Home resets",
-          )}
+          title={
+            props.windowEnabled
+              ? t(
+                  "hikari::ribbon.dragHint",
+                  "Drag to select a range; double-click, Escape or Home resets",
+                )
+              : undefined
+          }
           onPointerdown={onStripPointerDown}
           onDblclick={(event: MouseEvent) => {
             // Same rule as Escape/Home: only a double-click that actually
@@ -701,18 +705,20 @@ export default defineComponent({
                 </>
               )}
             </div>
-            <span id={hintId} class="hk-range-ribbon-hint">
-              {`${t(
-                "hikari::ribbon.moveWindow",
-                "Move window",
-              )}: ←/→ · ${t(
-                "hikari::ribbon.resizeWindow",
-                "Resize window",
-              )}: ⇧+←/→ · ${t(
-                "hikari::ribbon.dragHint",
-                "Drag to select a range; double-click, Escape or Home resets",
-              )}`}
-            </span>
+            {props.windowEnabled && (
+              <span id={hintId} class="hk-range-ribbon-hint">
+                {`${t(
+                  "hikari::ribbon.moveWindow",
+                  "Move window",
+                )}: ←/→ · ${t(
+                  "hikari::ribbon.resizeWindow",
+                  "Resize window",
+                )}: ⇧+←/→ · ${t(
+                  "hikari::ribbon.dragHint",
+                  "Drag to select a range; double-click, Escape or Home resets",
+                )}`}
+              </span>
+            )}
           </div>
           <div class="hk-range-ribbon-lanes">
             {lanes.value.map((lane) => (

package/src/components/HkScrollProgress.test.tsx

@@ -439,11 +439,11 @@ describe("HkAdminTablePage scroll-progress registration", () => {
     rects.push(vi.spyOn(viewport, "getBoundingClientRect").mockReturnValue({
       left: 0, top: 0, right: 300, bottom: 400, width: 300, height: 400, x: 0, y: 0,
     } as DOMRect));
-    // The list root is AdminTablePage's table-card wrapper (the anchor
-    // class the page ships for exactly this geometry contract).
+    // The list root is HkTable's own host element — the table
+    // self-registers (the page only forwards the total).
     const card = container.querySelector("table");
     expect(card).not.toBeNull();
-    const cardHost = container.querySelector<HTMLElement>(".hk-admin-table-page-tablecard")!;
+    const cardHost = container.querySelector<HTMLElement>(".hk-table-host")!;
     expect(cardHost.contains(card!)).toBe(true);
     rects.push(vi.spyOn(cardHost, "getBoundingClientRect").mockReturnValue({
       left: 0, top: -200, right: 300, bottom: 3800, width: 300, height: 4000, x: 0, y: -200,

package/src/components/HkTable.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, onBeforeUnmount, onMounted, ref, watch, type PropType } from "vue";
+import { computed, defineComponent, inject, onBeforeUnmount, onMounted, ref, watch, type PropType } from "vue";
 
 import { useI18n } from "../i18n/context";
 import { usePointerReorder } from "../composables/usePointerReorder";
@@ -10,6 +10,7 @@ import { ancestorZoom } from "../runtime/cssZoom";
 import { useClipboardWithToast } from "../runtime/useClipboard";
 import { useToast } from "../runtime/useToast";
 import HkRowActions from "./HkRowActions";
+import { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressHandle } from "./HkScrollProgress";
 import "./HkTable.scss";
 
 interface Column {
@@ -91,6 +92,14 @@ export default defineComponent({
       default: false,
     },
     emptyText: { type: String, default: "" },
+    /** Authoritative row total the scroll-progress pill uses as its
+     *  denominator (the server count behind a paged list). Omitted: the
+     *  pill falls back to counting the delivered DOM rows. Every HkTable
+     *  self-registers with the nearest enclosing HkScrollContainer that
+     *  has `scrollProgress` on — no wrapper needed (2026-11-06: moved
+     *  here from HkAdminTablePage so the 17 bare-HkTable views inherit
+     *  the pill too). */
+    total: { type: Number, default: undefined },
   },
   emits: {
     "update:selectedRows": (_rows: Record<string, unknown>[]) => true,
@@ -195,6 +204,24 @@ export default defineComponent({
       wrapperScrollbar = null;
     });
 
+    // Scroll-progress registration: the nearest enclosing HkScrollContainer
+    // with `scrollProgress` on provides the registrar (provide/inject
+    // scoping resolves the shell viewport for admin pages and keeps an
+    // inner container's lists out of the shell). The handle exposes the
+    // table host as the row root plus the `total` prop live — the pill's
+    // denominator follows it as pages load.
+    const progressRegistrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+    const progressHandle: HkScrollProgressHandle = {
+      getRoot: () => wrapperHostRef.value ?? null,
+      getTotal: () => props.total,
+    };
+    onMounted(() => {
+      progressRegistrar?.register(progressHandle);
+    });
+    onBeforeUnmount(() => {
+      progressRegistrar?.unregister(progressHandle);
+    });
+
     function getRowKey(row: Record<string, unknown>, index: number): string {
       if (props.rowKey && row[props.rowKey] != null) return String(row[props.rowKey]);
       return String(index);