@celestia-island/hikari 0.55.297 → 0.55.298

package/package.json

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