@celestia-island/hikari 0.55.135 → 0.55.137

package/package.json

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

package/src/components/HkDraggableList.scss

@@ -71,6 +71,18 @@
   }
 }
 
+/* A list where every row is locked can never reorder, so the handle lane
+ * has nothing to offer — collapse it instead of reserving an empty gutter
+ * that reads as "missing grips" (user report 2026-10-11: chest's 2FA
+ * factors list). Mixed lists are unaffected: they keep the lane on every
+ * row (locked ones render it hidden via [data-hidden]) so the grip column
+ * stays aligned. */
+.hk-draggable-list[data-all-locked] {
+  .hk-draggable-list-handle {
+    display: none;
+  }
+}
+
 .hk-draggable-list-content {
   flex: 1;
   min-width: 0;

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

@@ -0,0 +1,64 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Sheet contract for the locked-row handle lane (DOM twin:
+ * HkDraggableList.test.tsx).
+ *
+ * - a locked row HIDES its grip but keeps the 20px lane reserved
+ *   (`visibility: hidden` under [data-hidden]) — mixed lists keep the
+ *   grip column aligned;
+ * - a list whose every row is locked (root [data-all-locked]) can never
+ *   reorder, so the lane collapses outright (`display: none`) instead of
+ *   reserving an empty gutter that reads as "missing grips" (user report
+ *   2026-10-11 on chest's 2FA factors list).
+ *
+ * Assertions run on the COMPILED sheet, not the source text, so a
+ * declaration cannot hide behind SCSS nesting, and comments are stripped
+ * first so a commented-out guard cannot keep a hollow test green.
+ */
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+function listCss(): string {
+  const file = resolve(componentDir, "HkDraggableList.scss");
+  return compile(file, { style: "expanded", loadPaths: [componentDir] }).css.replace(
+    /\/\*[\s\S]*?\*\//g,
+    "",
+  );
+}
+
+function ruleBody(css: string, selector: string): string | null {
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const m = css.match(new RegExp(`${escaped}\\s*\\{([^}]*)\\}`));
+  return m ? m[1]! : null;
+}
+
+describe("HkDraggableList handle-lane sheet", () => {
+  const css = listCss();
+
+  it("compiles", () => {
+    expect(css.length).toBeGreaterThan(0);
+    // Sanity anchors so a renamed file cannot hollow this guard.
+    expect(css).toContain(".hk-draggable-list-item");
+    expect(css).toContain(".hk-draggable-list-handle");
+  });
+
+  it("keeps a locked row's lane reserved — hidden, not removed", () => {
+    const body = ruleBody(css, ".hk-draggable-list-handle[data-hidden]");
+    expect(body, "the [data-hidden] rule must exist").not.toBeNull();
+    expect(body).toContain("visibility: hidden");
+    expect(body).not.toContain("display: none");
+  });
+
+  it("collapses the lane entirely when every row is locked", () => {
+    const body = ruleBody(
+      css,
+      ".hk-draggable-list[data-all-locked] .hk-draggable-list-handle",
+    );
+    expect(body, "the [data-all-locked] collapse rule must exist").not.toBeNull();
+    expect(body).toContain("display: none");
+  });
+});

package/src/components/HkDraggableList.test.tsx

@@ -0,0 +1,182 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick, ref } from "vue";
+
+import HDraggableList from "./HkDraggableList";
+
+/**
+ * DOM contract for the locked-row handle lane.
+ *
+ * Every row renders a 20px handle lane so the grip column stays aligned
+ * across draggable and locked rows; a locked row hides its grip
+ * (`data-hidden` → visibility: hidden — reserved, not removed). When
+ * EVERY row is locked the list can never reorder at all, and an
+ * all-hidden lane reads as "missing grips" rather than "locked" (user
+ * report 2026-10-11 on chest's 2FA factors list): the root then carries
+ * `data-all-locked` and the sheet collapses the lane entirely (the sheet
+ * twin of this contract: HkDraggableList.styles.test.ts). A custom
+ * `handle` slot rides the same lane, so it collapses with it.
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils.)
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  while (mounts.length) {
+    const { app, container } = mounts.pop()!;
+    app.unmount();
+    container.remove();
+  }
+});
+
+function mountList(items: string[], lockedKeys: string[]): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(
+        HDraggableList,
+        { items: items.map((key) => ({ key })), lockedKeys },
+        {
+          item: ({ item }: { item: { key: string } }) =>
+            h("span", { class: "row-body" }, item.key),
+        },
+      ),
+  });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container.querySelector(".hk-draggable-list") as HTMLElement;
+}
+
+function handlesOf(root: HTMLElement): HTMLElement[] {
+  return Array.from(root.querySelectorAll(".hk-draggable-list-handle"));
+}
+
+describe("HkDraggableList locked-lane contract", () => {
+  it("hides a locked row's grip but keeps the lane in mixed lists", () => {
+    const root = mountList(["a", "b"], ["b"]);
+
+    expect(root.hasAttribute("data-all-locked")).toBe(false);
+    const handles = handlesOf(root);
+    expect(handles).toHaveLength(2);
+    expect(handles[0]!.hasAttribute("data-hidden")).toBe(false);
+    expect(handles[1]!.hasAttribute("data-hidden")).toBe(true);
+  });
+
+  it("marks an all-locked list so the sheet can collapse the lane", () => {
+    const root = mountList(["a", "b"], ["a", "b"]);
+
+    expect(root.hasAttribute("data-all-locked")).toBe(true);
+    // Handles stay in the DOM (consumers count them — chest's 2FA
+    // contract test does); the collapse is presentational, carried by
+    // the sheet, so the marker is the load-bearing part here.
+    const handles = handlesOf(root);
+    expect(handles).toHaveLength(2);
+    expect(handles.every((handle) => handle.hasAttribute("data-hidden"))).toBe(true);
+  });
+
+  it("flips the marker reactively as the last draggable row locks", async () => {
+    const lockedKeys = ref<string[]>([]);
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: [{ key: "a" }, { key: "b" }], lockedKeys: lockedKeys.value },
+          {
+            item: ({ item }: { item: { key: string } }) =>
+              h("span", { class: "row-body" }, item.key),
+          },
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    const root = container.querySelector(".hk-draggable-list") as HTMLElement;
+
+    expect(root.hasAttribute("data-all-locked")).toBe(false);
+
+    lockedKeys.value = ["a", "b"];
+    await nextTick();
+
+    expect(root.hasAttribute("data-all-locked")).toBe(true);
+  });
+
+  it("collapses a custom handle slot with the lane in an all-locked list", () => {
+    // The handle slot renders INSIDE the lane span, so the collapse rule
+    // hides custom grips the same as the default six-dot svg.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: [{ key: "a" }], lockedKeys: ["a"] },
+          {
+            item: ({ item }: { item: { key: string } }) =>
+              h("span", { class: "row-body" }, item.key),
+            handle: () => h("span", { class: "custom-grip" }, "≡"),
+          },
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+
+    const grip = container.querySelector(".custom-grip") as HTMLElement;
+    expect(grip).not.toBeNull();
+    // The custom grip rides the lane span that the sheet display:nones.
+    expect(grip.closest(".hk-draggable-list-handle")).not.toBeNull();
+    expect(grip.closest(".hk-draggable-list")).not.toBeNull();
+    expect(
+      (grip.closest(".hk-draggable-list") as HTMLElement).hasAttribute("data-all-locked"),
+    ).toBe(true);
+  });
+
+  it("carries no marker on an empty list", () => {
+    const root = mountList([], []);
+
+    expect(root.hasAttribute("data-all-locked")).toBe(false);
+    expect(handlesOf(root)).toHaveLength(0);
+  });
+
+  it("ignores locked keys that match no row — membership, not counts", () => {
+    // Guards against a length-arithmetic refactor
+    // (lockedKeys.length >= items.length): TWO phantom keys vs two rows
+    // satisfy the count yet lock nothing — the list stays draggable and
+    // the lane must stay.
+    const phantomOnly = mountList(["a", "b"], ["zzz", "yyy"]);
+    expect(phantomOnly.hasAttribute("data-all-locked")).toBe(false);
+
+    // A superset still marks: every real row IS locked.
+    const superset = mountList(["a", "b"], ["zzz", "a", "b"]);
+    expect(superset.hasAttribute("data-all-locked")).toBe(true);
+  });
+
+  it("flips the marker reactively as rows are added around a locked one", async () => {
+    const items = ref<{ key: string }[]>([{ key: "a" }]);
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: items.value, lockedKeys: ["a"] },
+          {
+            item: ({ item }: { item: { key: string } }) =>
+              h("span", { class: "row-body" }, item.key),
+          },
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    const root = container.querySelector(".hk-draggable-list") as HTMLElement;
+
+    expect(root.hasAttribute("data-all-locked")).toBe(true);
+
+    items.value = [{ key: "a" }, { key: "b" }];
+    await nextTick();
+
+    expect(root.hasAttribute("data-all-locked")).toBe(false);
+  });
+});

package/src/components/HkDraggableList.tsx

@@ -22,6 +22,10 @@ export default defineComponent({
   name: "HkDraggableList",
   props: {
     items: { type: Array as PropType<DragListItem[]>, required: true },
+    /** Row keys that may not be dragged. A locked row hides its grip but
+     *  keeps the handle lane reserved ([data-hidden]); when EVERY row is
+     *  locked the root carries data-all-locked and the sheet collapses
+     *  the lane entirely — the list cannot reorder at all. */
     lockedKeys: { type: Array as PropType<string[]>, default: () => [] },
   },
   emits: {
@@ -198,8 +202,19 @@ export default defineComponent({
     return () => {
       void tick.value;
       const s = drag.value;
+      // A list whose every row is locked can never reorder (chest's 2FA
+      // factor list is the all-locked case), and an all-hidden lane reads
+      // as "missing grips" rather than "locked" (user report 2026-10-11).
+      // Mark the root so the sheet can collapse the lane outright; mixed
+      // lists keep it on every row for grip-column alignment.
+      const allLocked =
+        props.items.length > 0 && props.items.every((item) => isLocked(item.key));
       return (
-        <div class="hk-draggable-list" data-dragging={s ? "" : undefined}>
+        <div
+          class="hk-draggable-list"
+          data-dragging={s ? "" : undefined}
+          data-all-locked={allLocked || undefined}
+        >
           {props.items.map((item, index) => {
             const locked = isLocked(item.key);
             const isSource = s != null && s.fromIndex === index;

package/src/components/HkSelect.test.tsx

@@ -85,4 +85,96 @@ describe("HSelect mobile sheet", () => {
 
     app.unmount();
   });
+
+  it("consumes Escape while the panel is open so hosting dialogs stay put", async () => {
+    // The trigger commonly renders inside a dialog that closes on
+    // bubbled Escape (HkModal/HkDrawer). One press must close ONLY the
+    // dropdown; with the dropdown already closed the key bubbles on so
+    // the dialog's own Escape semantics are untouched.
+    setViewportWidth(1280);
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const dialogKeydowns: KeyboardEvent[] = [];
+    host.addEventListener("keydown", (ev) => dialogKeydowns.push(ev as KeyboardEvent));
+
+    const app = createApp({
+      render: () =>
+        h("div", { onKeydown: () => {} }, [
+          h(HSelect, {
+            modelValue: "",
+            "onUpdate:modelValue": () => {},
+            options: [
+              { value: "a", label: "Option A" },
+              { value: "b", label: "Option B" },
+            ],
+          }),
+        ]),
+    });
+    app.mount(host);
+    await nextTick();
+
+    const trigger = host.querySelector<HTMLButtonElement>(".hk-select-trigger")!;
+
+    // Panel open: Escape closes it AND is consumed.
+    trigger.click();
+    await nextTick();
+    const escapeOpen = new KeyboardEvent("keydown", {
+      key: "Escape", bubbles: true, cancelable: true,
+    });
+    trigger.dispatchEvent(escapeOpen);
+    await nextTick();
+    expect(escapeOpen.defaultPrevented).toBe(true);
+    expect(dialogKeydowns).toHaveLength(0);
+
+    // Panel closed: the same key bubbles to the hosting dialog.
+    const escapeClosed = new KeyboardEvent("keydown", {
+      key: "Escape", bubbles: true, cancelable: true,
+    });
+    trigger.dispatchEvent(escapeClosed);
+    await nextTick();
+    expect(escapeClosed.defaultPrevented).toBe(false);
+    expect(dialogKeydowns).toHaveLength(1);
+
+    app.unmount();
+    host.remove();
+  });
+
+  it("titles the opened surface from panelTitle without a visible label", async () => {
+    // Consumers whose visible label lives outside the field (a titled
+    // row) still need the mobile sheet header / popout a11y name; an
+    // untitled surface registers an unnamed blocking layer on phones.
+    setViewportWidth(375);
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    const app = createApp({
+      render: () =>
+        h(HSelect, {
+          modelValue: "",
+          "onUpdate:modelValue": () => {},
+          panelTitle: "What this screen shows",
+          options: [
+            { value: "a", label: "Option A" },
+            { value: "b", label: "Option B" },
+          ],
+        }),
+    });
+    app.mount(el);
+    await nextTick();
+
+    // No visible field label rendered above the trigger.
+    expect(document.querySelector(".hk-select-label")).toBeNull();
+
+    const trigger = document.querySelector<HTMLButtonElement>(".hk-select-trigger")!;
+    trigger.click();
+    await nextTick();
+
+    const title = document.querySelector<HTMLElement>(".hk-select-sheet-title");
+    expect(title?.textContent?.trim()).toBe("What this screen shows");
+    // The sheet panel is the a11y-named dialog for the surface.
+    const panel = document.querySelector<HTMLElement>(".hk-select-sheet-panel");
+    expect(panel?.getAttribute("aria-label")).toBe("What this screen shows");
+
+    app.unmount();
+    el.remove();
+  });
 });

package/src/components/HkSelect.tsx

@@ -30,6 +30,15 @@ export default defineComponent({
   props: {
     modelValue: { type: String, default: "" },
     label: { type: String, default: undefined },
+    /**
+     * Title for the OPENED surface only (mobile sheet header, desktop
+     * popout's a11y name, popup-manager breadcrumb layer) — without
+     * rendering the visible field `label`. Consumers whose visible label
+     * lives elsewhere (a titled row around the field) pass this so the
+     * surface is not registered untitled; resolution order is
+     * panelTitle, then `label`, then empty (the historic behaviour).
+     */
+    panelTitle: { type: String, default: undefined },
     placeholder: { type: String, default: "" },
     error: { type: String, default: undefined },
     disabled: { type: Boolean, default: false },
@@ -100,6 +109,18 @@ export default defineComponent({
             normalizedOptions.value.length;
         }
       } else if (e.key === "Escape") {
+        // Consume the key ONLY when it actually closed something: the
+        // trigger commonly renders inside a dialog surface (HkModal and
+        // HkDrawer close on bubbled Escape), and one press must mean one
+        // thing — close the dropdown, not the dropdown AND the hosting
+        // dialog. The panel surface itself stops propagation for the
+        // same reason (HkSelectPanel's onSurfaceEscape); with the panel
+        // closed the key bubbles on as before, so the hosting dialog's
+        // own Escape semantics are untouched.
+        if (isOpen.value) {
+          e.preventDefault();
+          e.stopPropagation();
+        }
         isOpen.value = false;
       }
     }
@@ -182,7 +203,7 @@ export default defineComponent({
           open={isOpen.value}
           onUpdate:open={(v: boolean) => { isOpen.value = v; }}
           anchorRef={triggerRef.value ?? null}
-          title={props.label ?? ""}
+          title={props.panelTitle ?? props.label ?? ""}
           placement="bottom-start"
           offset={4}
           onKeydown={onPopoutKeydown}