@celestia-island/hikari 0.55.176 → 0.55.177

package/package.json

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

package/src/components/HkDraggableList.test.tsx

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick, ref } from "vue";
 
 import HDraggableList from "./HkDraggableList";
@@ -180,3 +180,165 @@ describe("HkDraggableList locked-lane contract", () => {
     expect(root.hasAttribute("data-all-locked")).toBe(false);
   });
 });
+
+describe("HkDraggableList list semantics", () => {
+  /** A reorderable list is a list for AT users whether or not the host
+   *  names it: the root always carries role="list" and every row
+   *  role="listitem" (the vocabulary a11y rulings #736/#737 applied to
+   *  the picker surfaces — the drag list adopts the same contract). The
+   *  accessible NAME stays the host's call: aria-label renders only when
+   *  the `label` prop is passed, so an unnamed list is still structural
+   *  and never announces an empty string. */
+
+  it("announces the root and rows as a list regardless of the label", () => {
+    const root = mountList(["a", "b"], []);
+
+    expect(root.getAttribute("role")).toBe("list");
+    expect(root.hasAttribute("aria-label")).toBe(false);
+    const rows = Array.from(root.querySelectorAll(".hk-draggable-list-item"));
+    expect(rows).toHaveLength(2);
+    expect(rows.every((row) => row.getAttribute("role") === "listitem")).toBe(true);
+  });
+
+  it("names the list through the label prop", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: [{ key: "a" }], label: "Sortable accounts" },
+          {
+            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.getAttribute("role")).toBe("list");
+    expect(root.getAttribute("aria-label")).toBe("Sortable accounts");
+  });
+});
+
+describe("HkDraggableList press ergonomics (clickable rows)", () => {
+  /** Two guards make a clickable row safe inside the list (ported from
+   *  wowsp's SortableList twin, which ran them in production):
+   *
+   *    1. ARM — a press under 5px of travel never publishes drag state
+   *       (no ghost flash on a jittered tap) and keeps the tap's native
+   *       semantics: no preventDefault until the arm.
+   *    2. SWALLOW — the release of an ARMED drag lands as a click on the
+   *       row the press started from; a capture-phase guard on the root
+   *       eats it, so dropping a row onto a clickable card never also
+   *       activates that card. Time-boxed at 300ms so it can never eat
+   *       a later keyboard activation, which has no pointerdown to
+   *       reset it. */
+
+  const PointerEventCtor: typeof MouseEvent =
+    (globalThis as { PointerEvent?: typeof MouseEvent }).PointerEvent ?? MouseEvent;
+
+  const pointerInit: MouseEventInit = { bubbles: true, cancelable: true };
+
+  function fire(el: Element, type: string, x = 0, y = 0) {
+    el.dispatchEvent(new PointerEventCtor(type, {
+      ...pointerInit,
+      button: 0,
+      clientX: x,
+      clientY: y,
+    }));
+  }
+
+  function fireWin(type: string, x = 0, y = 0) {
+    window.dispatchEvent(new PointerEventCtor(type, {
+      ...pointerInit,
+      clientX: x,
+      clientY: y,
+    }));
+  }
+
+  function mountClickable(): { root: HTMLElement; clicks: () => number } {
+    let clicked = 0;
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: [{ key: "a" }, { key: "b" }] },
+          {
+            item: () =>
+              h(
+                "div",
+                { class: "row-body", onClick: () => { clicked++; } },
+                "row",
+              ),
+          },
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    const root = container.querySelector(".hk-draggable-list") as HTMLElement;
+    return { root, clicks: () => clicked };
+  }
+
+  it("keeps a plain tap a tap: no drag state, and the row's click fires", async () => {
+    const { root, clicks } = mountClickable();
+    const row = root.querySelectorAll(".hk-draggable-list-item")[0] as HTMLElement;
+
+    fire(row, "pointerdown", 10, 10);
+    // A 1px jitter stays under the arm threshold — no drag publishes.
+    fireWin("pointermove", 11, 10);
+    await nextTick();
+    expect(row.hasAttribute("data-dragging")).toBe(false);
+
+    fireWin("pointerup");
+    (row.querySelector(".row-body") as HTMLElement).dispatchEvent(
+      new MouseEvent("click", { bubbles: true, cancelable: true }),
+    );
+    expect(clicks()).toBe(1);
+  });
+
+  it("arms past the threshold, drags, and swallows the release click", async () => {
+    const { root, clicks } = mountClickable();
+    const row = root.querySelectorAll(".hk-draggable-list-item")[0] as HTMLElement;
+
+    fire(row, "pointerdown", 10, 10);
+    fireWin("pointermove", 30, 40);
+    await nextTick();
+    expect(row.getAttribute("data-dragging")).not.toBeNull();
+
+    fireWin("pointerup");
+    (row.querySelector(".row-body") as HTMLElement).dispatchEvent(
+      new MouseEvent("click", { bubbles: true, cancelable: true }),
+    );
+    expect(clicks()).toBe(0);
+  });
+
+  it("time-boxes the swallow — a click after the window passes through", async () => {
+    vi.useFakeTimers();
+    try {
+      const { root, clicks } = mountClickable();
+      const row = root.querySelectorAll(".hk-draggable-list-item")[0] as HTMLElement;
+
+      fire(row, "pointerdown", 10, 10);
+      fireWin("pointermove", 30, 40);
+      fireWin("pointerup");
+
+      (row.querySelector(".row-body") as HTMLElement).dispatchEvent(
+        new MouseEvent("click", { bubbles: true, cancelable: true }),
+      );
+      expect(clicks()).toBe(0);
+
+      vi.advanceTimersByTime(301);
+      (row.querySelector(".row-body") as HTMLElement).dispatchEvent(
+        new MouseEvent("click", { bubbles: true, cancelable: true }),
+      );
+      expect(clicks()).toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/components/HkDraggableList.tsx

@@ -1,4 +1,4 @@
-import { defineComponent, onBeforeUnmount, ref, shallowRef, type PropType } from "vue";
+import { defineComponent, onBeforeUnmount, onMounted, ref, shallowRef, type PropType } from "vue";
 import { onceFrame } from "../runtime/animationBus";
 import { useReportedTransition } from "../composables/useReportedTransition";
 import { ancestorZoom } from "../runtime/cssZoom";
@@ -14,10 +14,23 @@ interface DragState {
   fromIndex: number;
   placeholderIndex: number;
   originX: number;
+  originY: number;
   grabOffsetX: number;
   grabOffsetY: number;
 }
 
+/** Press-to-drag arm distance — a plain click on a row (or its handle)
+ *  never starts a drag: the ghost only rises once the pointer moves past
+ *  this many px, so a clickable row keeps its tap action and a jittered
+ *  tap never flashes a ghost. */
+const ARM_PX = 5;
+
+/** How long after a drop the release click is still recognized as the
+ *  drag's own click. Time-boxed (rather than a sticky flag) so a drag
+ *  released off-window can never eat a later keyboard activation,
+ *  which has no pointerdown to reset it. */
+const SWALLOW_CLICK_MS = 300;
+
 export default defineComponent({
   name: "HkDraggableList",
   props: {
@@ -27,6 +40,12 @@ export default defineComponent({
      *  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: () => [] },
+    /** Accessible name for the list (aria-label on the role="list" root).
+     *  The list semantics themselves are unconditional — a reorderable
+     *  list is a list for AT users whether or not the host names it —
+     *  mirroring the menu/vocabulary a11y rulings (#736/#737): chrome
+     *  announces structure, the host supplies the name. */
+    label: { type: String, default: undefined },
   },
   emits: {
     reorder: (_fromIndex: number, _toIndex: number) => true,
@@ -46,6 +65,38 @@ export default defineComponent({
 
     let ghostNode: HTMLElement | null = null;
 
+    /** Press bookkeeping — captured at pointerdown, never read during
+     *  render. `armed` flips only when the pointer crosses ARM_PX; until
+     *  then the press is a plain click-in-progress (no ghost, no drag
+     *  state, no preventDefault — the tap keeps its native semantics). */
+    let press: {
+      rect: DOMRect;
+      snapshot: string;
+      state: DragState;
+      armed: boolean;
+    } | null = null;
+    /** Timestamp of an armed drag's release — the capture-phase click
+     *  guard below eats the click a completed drag leaves behind (press
+     *  + release on the same element), so dropping a row onto a
+     *  clickable card never also activates that card. */
+    let swallowClickAt = 0;
+
+    const rootEl = ref<HTMLElement | null>(null);
+
+    /** Capture-phase click guard — runs before any row content's own
+     *  handlers (Vue's JSX typings have no onClickCapture attribute, so
+     *  the listener is wired imperatively in onMounted). */
+    function onRootClickCapture(e: MouseEvent) {
+      if (Date.now() - swallowClickAt > SWALLOW_CLICK_MS) return;
+      swallowClickAt = 0;
+      e.preventDefault();
+      e.stopPropagation();
+    }
+
+    onMounted(() => {
+      rootEl.value?.addEventListener("click", onRootClickCapture, true);
+    });
+
     const anim = useReportedTransition(250);
 
     function bump() { tick.value++; }
@@ -68,28 +119,29 @@ export default defineComponent({
       const row = rowEls.value[index];
       if (!row) return;
 
-      e.preventDefault();
       const rect = row.getBoundingClientRect();
 
       const snapshot = row.outerHTML
         .replace(/\sdraggable="[^"]*"/g, "")
         .replace(/\sdata-dragging="[^"]*"/g, "");
 
-      const state: DragState = {
-        fromIndex: index,
-        placeholderIndex: index,
-        originX: e.clientX,
-        grabOffsetX: e.clientX - rect.left,
-        grabOffsetY: e.clientY - rect.top,
+      // The press captures everything the arm needs. Nothing publishes
+      // yet — no preventDefault either: the handle lane carries its own
+      // touch-action:none and the rows are user-select:none, so a plain
+      // tap keeps its native click/scroll semantics untouched.
+      press = {
+        rect,
+        snapshot,
+        state: {
+          fromIndex: index,
+          placeholderIndex: index,
+          originX: e.clientX,
+          originY: e.clientY,
+          grabOffsetX: e.clientX - rect.left,
+          grabOffsetY: e.clientY - rect.top,
+        },
+        armed: false,
       };
-      drag.value = state;
-      bump();
-
-      onceFrame(() => {
-        if (!drag.value) return;
-        attachGhost(rect, snapshot);
-        anim.run();
-      });
 
       window.addEventListener("pointermove", onPointerMove, { passive: false });
       window.addEventListener("pointerup", onPointerUp, { once: true });
@@ -170,22 +222,45 @@ export default defineComponent({
     }
 
     function onPointerMove(e: PointerEvent) {
-      const s = drag.value;
-      if (!s) return;
+      const p = press;
+      if (!p) return;
+
+      if (!p.armed) {
+        // Arm past the threshold: only now does the drag publish, the
+        // ghost rise, and the gesture claim its defaults.
+        if (Math.hypot(e.clientX - p.state.originX, e.clientY - p.state.originY) <= ARM_PX) {
+          return;
+        }
+        p.armed = true;
+        drag.value = p.state;
+        bump();
+        const { rect, snapshot } = p;
+        onceFrame(() => {
+          if (!drag.value) return;
+          attachGhost(rect, snapshot);
+          anim.run();
+        });
+      }
+
       e.preventDefault();
       moveGhost(e.clientY);
       recomputePlaceholder(e.clientY);
     }
 
     function onPointerUp() {
-      const s = drag.value;
       window.removeEventListener("pointermove", onPointerMove);
 
+      const s = drag.value;
       if (s) {
+        // An armed drag's release lands as a click on the row the press
+        // started from — mark it for the capture guard or every drop
+        // onto a clickable card would also activate the card.
+        swallowClickAt = Date.now();
         if (s.placeholderIndex !== s.fromIndex) {
           emit("reorder", s.fromIndex, s.placeholderIndex);
         }
       }
+      press = null;
       anim.run();
       drag.value = null;
       bump();
@@ -193,6 +268,7 @@ export default defineComponent({
     }
 
     onBeforeUnmount(() => {
+      rootEl.value?.removeEventListener("click", onRootClickCapture, true);
       window.removeEventListener("pointermove", onPointerMove);
       detachGhost();
     });
@@ -211,7 +287,10 @@ export default defineComponent({
         props.items.length > 0 && props.items.every((item) => isLocked(item.key));
       return (
         <div
+          ref={rootEl}
           class="hk-draggable-list"
+          role="list"
+          aria-label={props.label || undefined}
           data-dragging={s ? "" : undefined}
           data-all-locked={allLocked || undefined}
         >
@@ -227,6 +306,7 @@ export default defineComponent({
                 key={item.key}
                 ref={(el) => setRowEl(index, el as Element | null)}
                 class="hk-draggable-list-item"
+                role="listitem"
                 data-locked={locked || undefined}
                 data-dragging={isSource || undefined}
                 data-placeholder={placeholderDir || undefined}

package/src/components/HkPopover.scss

@@ -165,13 +165,17 @@
   /* The sheet's bottom-edge distance itself comes from the shared
    * --hk-sheet-bottom-gap (inline in HkPopover's sheet style); here the
    * content keeps the last row clear of the home bar: the safe-area
-   * inset stacked on a 12px family base, which also restores a bottom
-   * cushion over the glass dropdown chrome (equal specificity, earlier
+   * inset stacked on the shared container-pad token, whose legacy
+   * fallback is the 12px family base (which also restores a bottom
+   * cushion over the glass dropdown chrome — equal specificity, earlier
    * in source, whose own bottom padding the sheet rule would otherwise
-   * zero out). The modal sheet footer goes further (it adds
-   * --hk-sheet-footer-gap for its action buttons); this sheet has no
-   * footer, so this is the family baseline. */
-  padding-bottom: calc(var(--space-12, 0.75rem) + env(safe-area-inset-bottom, 0px));
+   * zero out). A host that sets the `padding` prop retunes the sheet's
+   * bottom inset with the SAME step its anchored panel uses (#808
+   * completion — hosts stop hand-padding the sheet branch); the safe-
+   * area term always rides on top. The modal sheet footer goes further
+   * (it adds --hk-sheet-footer-gap for its action buttons); this sheet
+   * has no footer, so this is the family baseline. */
+  padding-bottom: calc(var(--hk-pad, var(--space-12, 0.75rem)) + env(safe-area-inset-bottom, 0px));
 
   /* Overlay scrollbar (useOverlayScrollbar, sheet mode only) — the
      native chrome is hidden, never styled. */
@@ -184,9 +188,14 @@
 
 .hk-popover-sheet-grabber {
   flex-shrink: 0;
+  // Chrome, not content: cancel the panel's shared container pad inline
+  // (see the header twin above) so the grabber zone spans the full sheet
+  // width at any `padding` step — the centered bar never drifts inward.
+  // Longhand AFTER the shorthand or `margin: 0 auto` would win the cascade.
+  margin: 0 auto;
+  margin-inline: calc(-1 * var(--hk-pad, 0px));
   // Grabber zone: tap target tall enough for a thumb, bar visually small.
   padding: 14px 0 20px;
-  margin: 0 auto;
   width: 100%;
   cursor: pointer;
   display: flex;
@@ -212,15 +221,26 @@
  * The title aligns to the CONTENT edge: the leading inset defaults to
  * --space-12, matching the padded content blocks popover sheets host
  * (e.g. the house 0.75rem popover body). Hosts tune it via
- * --hk-sheet-title-inset; the trailing inset hugs the close button. */
+ * --hk-sheet-title-inset; the trailing inset hugs the close button.
+ *
+ * Shared container pad (#808 completion): the panel's `padding` prop
+ * insets the CONTENT band, so this chrome row cancels it inline
+ * (negative margin, the valid-CSS twin of a negative padding) and
+ * keeps its own title-inset from the panel frame — the title lands on
+ * the content edge whenever the pad step matches title-inset, at any
+ * step. The trailing block gap is the CONTENT's block-start air under
+ * the header: it reads the same pad step when the prop is set (legacy
+ * 8px otherwise), so a padded host gets one uniform inset around its
+ * sheet content too — no hand-padded wrapper branch downstream. */
 .hk-popover-sheet-header {
   flex-shrink: 0;
   display: flex;
   align-items: center;
   gap: var(--space-8, 0.5rem);
+  margin-inline: calc(-1 * var(--hk-pad, 0px));
   // Logical longhand (was physical `0 x y title-inset`): the title inset is
   // the inline START edge so RTL mirrors it with the mirrored title/close.
-  padding-block: 0 var(--space-8, 0.5rem);
+  padding-block: 0 var(--hk-pad, var(--space-8, 0.5rem));
   padding-inline: var(--hk-sheet-title-inset, var(--space-12, 0.75rem))
     var(--space-8, 0.5rem);
 }

package/src/components/HkPopover.sheetdock.test.ts

@@ -28,9 +28,12 @@ describe("HkPopover mobile sheet docking contract", () => {
 
   it("keeps sheet content clear of the home bar via the safe-area inset", () => {
     const block = scss.match(/\.hk-popover-panel\.hk-is-sheet\s*{[^}]*}/)?.[0] ?? "";
-    // Stacked on the family 12px base so the glass dropdown chrome's
-    // bottom padding survives on non-notched phones too.
-    expect(block).toContain("calc(var(--space-12");
+    // Stacked on the shared container-pad token whose legacy fallback is
+    // the family 12px base, so the glass dropdown chrome's bottom padding
+    // survives on non-notched phones too — and a host's `padding` prop
+    // retunes the base on the sheet face exactly like the anchored one
+    // (#808 completion; see containerPad.styles.test.ts for the pin).
+    expect(block).toContain("calc(var(--hk-pad, var(--space-12");
     expect(block).toContain("env(safe-area-inset-bottom");
   });
 });

package/src/components/HkPopoverSheet.test.tsx

@@ -169,6 +169,32 @@ describe("HkPopover sheetOnMobile", () => {
     expect(header.querySelector(".hk-popover-sheet-close")).toBeTruthy();
   });
 
+  // #808 completion: the sheet branch consumes the same shared container
+  // pad its anchored twin does — the inline --hk-pad the `padding` prop
+  // writes on the panel reaches the sheet's content band (the scss
+  // contract in containerPad.styles.test.ts pins the consuming rules),
+  // so a host retunes ONE prop and both faces follow. No more hand-padded
+  // sheet-only wrapper branches downstream (chest's HkContextRing used
+  // to need one).
+  it("carries the padding prop's inline token onto the sheet panel too", async () => {
+    setViewport(375);
+    mountPopover({ sheetOnMobile: true, title: "Sheet", padding: "md" });
+    await nextTick();
+
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+    expect(panel.classList.contains("hk-is-sheet")).toBe(true);
+    expect(panel.style.getPropertyValue("--hk-pad")).toBe("var(--space-12, 0.75rem)");
+  });
+
+  it("keeps the sheet panel token-free when no padding prop is set", async () => {
+    setViewport(375);
+    mountPopover({ sheetOnMobile: true, title: "Sheet" });
+    await nextTick();
+
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+    expect(panel.style.getPropertyValue("--hk-pad")).toBe("");
+  });
+
   it("keeps the heading row out of anchored desktop mode", async () => {
     setViewport(1200);
     mountPopover({ sheetOnMobile: true, title: "Context usage" });

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

@@ -48,6 +48,29 @@ describe("container pad token — wired sheets", () => {
     );
   });
 
+  it("HkPopover sheet: the content band reads the token, chrome cancels it", () => {
+    // The sheet branch completes the #808 contract: a host that sets the
+    // `padding` prop gets the SAME step around its content docked as a
+    // bottom sheet (bottom = step + safe-area, block-start air under the
+    // header = step) instead of hand-padding a sheet-only wrapper — the
+    // gap chest's HkContextRing had to compensate for locally. Grabber
+    // and header are chrome: they cancel the panel's inline pad so the
+    // tap zone and title keep their own frame-relative insets.
+    const css = compileSheet("HkPopover.scss");
+    expect(css).toContain(
+      "padding-bottom: calc(var(--hk-pad, var(--space-12, 0.75rem)) + env(safe-area-inset-bottom, 0px))",
+    );
+    expect(ruleFor(css, ".hk-popover-sheet-header {")).toContain(
+      "margin-inline: calc(-1 * var(--hk-pad, 0px))",
+    );
+    expect(ruleFor(css, ".hk-popover-sheet-header {")).toContain(
+      "padding-block: 0 var(--hk-pad, var(--space-8, 0.5rem))",
+    );
+    expect(ruleFor(css, ".hk-popover-sheet-grabber {")).toContain(
+      "margin-inline: calc(-1 * var(--hk-pad, 0px))",
+    );
+  });
+
   it("HkCard: body 1rem, unpadded 0, the scrollable pad wrapper 1rem", () => {
     const css = compileSheet("HkCard.scss");
     expect(ruleFor(css, ".hk-card-body {")).toContain(