@celestia-island/hikari 0.55.170 → 0.55.172

package/package.json

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

package/src/components/HkHeaderPicker.scss

@@ -0,0 +1,56 @@
+/* HkHeaderPicker — the header-centre selector. The trigger reuses the
+ * family's dropdown chrome (.hk-select-trigger) but adapts to the
+ * header band: self-sized (the centre slot hugs its content, unlike a
+ * form field that fills its row) and band-height compact. The panel
+ * geometry/behaviour is HkSelectPanel's, unchanged. */
+
+.hk-header-picker {
+  display: inline-flex;
+  min-width: 0;
+}
+
+.hk-header-picker-trigger {
+  width: auto;
+  /* Header-band compact: the button group beside it runs ~28px; the
+   * trigger stays a touch taller for its label but must not drive the
+   * header's own height. */
+  min-height: var(--space-32);
+  padding-block: var(--space-4);
+  padding-inline: var(--space-12) var(--space-28);
+  font-size: var(--text-sm);
+  font-weight: 600;
+  max-width: 16rem;
+}
+
+.hk-header-picker-trigger .hk-select-value {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-header-picker-trigger .hk-select-arrow {
+  position: absolute;
+  inset-inline-end: var(--space-8);
+}
+
+/* ── Standardized rows (label + row verbs) ────────────────────────── */
+
+.hk-header-picker-option {
+  display: flex;
+  align-items: center;
+  gap: var(--space-8);
+  justify-content: space-between;
+}
+
+.hk-header-picker-option-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-header-picker-option-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  flex: none;
+}

package/src/components/HkHeaderPicker.test.tsx

@@ -0,0 +1,140 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, ref } from "vue";
+
+import HkHeaderPicker, { type HkPickerOption } from "./HkHeaderPicker";
+
+/**
+ * HkHeaderPicker — the header-centre selector (the button group's
+ * sibling). These pins hold the standardized contract: trigger chrome,
+ * selection, and the per-row verbs (rename / delete / reorder) that
+ * "manage a dynamic set" pages hang on this one component. (Repo test
+ * convention: raw createApp + container queries; the panel teleports
+ * to body, so row queries go through document.)
+ */
+
+const OPTIONS: HkPickerOption[] = [
+  { value: "hub-1", label: "Hub One", editable: true, removable: true },
+  { value: "hub-2", label: "Hub Two", removable: true, locked: true },
+  { value: "hub-3", label: "Hub Three" },
+];
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountPicker(overrides: Record<string, unknown>, handlers: Record<string, unknown> = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const Host = defineComponent({
+    setup() {
+      const model = ref((overrides.modelValue as string) ?? "hub-1");
+      return () =>
+        h(HkHeaderPicker, {
+          modelValue: model.value,
+          "onUpdate:modelValue": (v: string) => {
+            model.value = v;
+            (handlers.onUpdateModelValue as ((v: string) => void) | undefined)?.(v);
+          },
+          options: OPTIONS,
+          panelTitle: "Pick a hub",
+          ariaLabel: "Hub picker",
+          ...overrides,
+          ...handlers,
+        });
+    },
+  });
+  const app = createApp({ render: () => h(Host) });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts) {
+    app.unmount();
+    container.remove();
+  }
+  mounts.length = 0;
+});
+
+describe("HkHeaderPicker", () => {
+  it("renders the family dropdown trigger reading the current choice", () => {
+    const c = mountPicker({}, {});
+    const trigger = c.querySelector("button.hk-select-trigger")!;
+    expect(trigger, "family trigger chrome must render").not.toBeNull();
+    expect(trigger.className).toContain("hk-header-picker-trigger");
+    expect(trigger.textContent).toContain("Hub One");
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("opens the panel on trigger click and selects a row", async () => {
+    const selected: string[] = [];
+    const c = mountPicker({}, { onUpdateModelValue: (v: string) => selected.push(v) });
+    (c.querySelector("button.hk-select-trigger") as HTMLElement).click();
+    await vi.waitFor(() => {
+      expect(document.querySelectorAll(".hk-header-picker-option").length).toBe(3);
+    });
+    const rows = Array.from(document.querySelectorAll(".hk-header-picker-option"));
+    (rows[2] as HTMLElement).click();
+    expect(selected).toEqual(["hub-3"]);
+  });
+
+  it("emits edit and remove for the standardized row verbs without selecting", async () => {
+    const onEdit = vi.fn();
+    const onRemove = vi.fn();
+    const selected: string[] = [];
+    const c = mountPicker({}, {
+      onEdit,
+      onRemove,
+      onUpdateModelValue: (v: string) => selected.push(v),
+    });
+    (c.querySelector("button.hk-select-trigger") as HTMLElement).click();
+    await vi.waitFor(() => {
+      expect(document.querySelectorAll(".hk-header-picker-option").length).toBe(3);
+    });
+    const rows = Array.from(document.querySelectorAll(".hk-header-picker-option"));
+    // Row 0 carries BOTH verbs (editable + removable); row 1 only remove;
+    // row 2 declares neither flag — no verbs at all.
+    const editBtn = rows[0].querySelector('button[aria-label="Rename"]');
+    const removeBtn0 = rows[0].querySelector('button[aria-label="Delete"]');
+    const removeBtn1 = rows[1].querySelector('button[aria-label="Delete"]');
+    expect(editBtn).not.toBeNull();
+    expect(removeBtn0).not.toBeNull();
+    expect(removeBtn1).not.toBeNull();
+    expect(rows[2].querySelector('button[aria-label="Delete"]')).toBeNull();
+    (editBtn as HTMLElement).click();
+    (removeBtn1 as HTMLElement).click();
+    expect(onEdit).toHaveBeenCalledWith("hub-1");
+    expect(onRemove).toHaveBeenCalledWith("hub-2");
+    // A verb press must NOT double as a row selection.
+    expect(selected).toEqual([]);
+  });
+
+  it("mounts the rows on a draggable list when reorderable", async () => {
+    const onReorder = vi.fn();
+    const c = mountPicker({ reorderable: true }, { onReorder });
+    (c.querySelector("button.hk-select-trigger") as HTMLElement).click();
+    await vi.waitFor(() => {
+      expect(document.querySelector(".hk-draggable-list")).not.toBeNull();
+    });
+    // The locked row (hub-2) marks its grip data-hidden (lane reserved)
+    // while the other two rows keep draggable grips.
+    const grips = document.querySelectorAll(".hk-draggable-list-handle");
+    expect(grips.length).toBe(3);
+    expect(document.querySelectorAll('.hk-draggable-list-handle[data-hidden]').length).toBe(1);
+  });
+
+  it("declares the placement prop with the top-down default (mirror-of-bottom contract)", () => {
+    // The panel is teleported to body, so the through-wiring is pinned at
+    // the contract level: the prop exists, defaults to the header's
+    // downward growth, and the render passes it straight through
+    // (`placement={props.placement}` in HkHeaderPicker.tsx).
+    expect(HkHeaderPicker.props!.placement).toBeDefined();
+    expect((HkHeaderPicker.props!.placement as { default: string }).default).toBe("bottom-start");
+  });
+
+  it("disables the trigger when disabled", () => {
+    const c = mountPicker({ disabled: true }, {});
+    expect(
+      (c.querySelector("button.hk-select-trigger") as HTMLButtonElement).disabled,
+    ).toBe(true);
+  });
+});

package/src/components/HkHeaderPicker.tsx

@@ -0,0 +1,313 @@
+import {
+  computed,
+  defineComponent,
+  nextTick,
+  ref,
+  watch,
+  type PropType,
+} from "vue";
+
+import { ChevronDown, Pencil, Trash2 } from "lucide-vue-next";
+
+import { useBreakpoint } from "../runtime/useBreakpoint";
+import HkDraggableList from "./HkDraggableList";
+import HkIconButton from "./HkIconButton";
+import HkSelectPanel, { type SelectPanelPlacement } from "./HkSelectPanel";
+import "./HkHeaderPicker.scss";
+
+/** One choice of a header picker. The selection surface is the same
+ *  model as a select's; the three extra flags light the STANDARDIZED
+ *  per-row affordances (R: 2026-10-15 header-picker direction) — a row
+ *  may be renamed, deleted, or (when the whole picker is `reorderable`)
+ *  dragged into a new order, so "manage the dynamic set" pages — flash
+ *  hubs, office documents, tag rosters — hang their maintenance verbs
+ *  on the SAME component instead of one bespoke menu each. */
+export interface HkPickerOption {
+  value: string;
+  label: string;
+  disabled?: boolean;
+  /** Hidden grip: the row never drags (a pinned default), but the
+   *  handle lane stays reserved so the column does not jump. */
+  locked?: boolean;
+  /** Show the standardized rename action (emits `edit`). */
+  editable?: boolean;
+  /** Show the standardized delete action (emits `remove`). The picker
+   *  itself never confirms — removal is the HOST's decision; this just
+   *  makes the affordance uniform. */
+  removable?: boolean;
+}
+
+/**
+ * HkHeaderPicker — the header-centre SELECTOR, the button group's
+ * sibling facility. Where `HkTabs` (segmented) serves a small closed
+ * enum, this serves an OPEN or machine-managed set (hubs, documents,
+ * tags): a dropdown-style trigger reading the current choice, and an
+ * opened panel that mirrors the bottom-centre pickers symmetrically —
+ *
+ * - phone: the same bottom sheet they use, sliding up from the bottom
+ *   edge (an edge gesture, identical muscle memory);
+ * - desktop: a popout anchored at the trigger growing DOWNWARD from
+ *   the header band — the mirror of a bottom-pinned picker growing up.
+ *
+ * The panel is HkSelectPanel (popup-manager, z-bands, scrim/grabber),
+ * so the surface behaves like every other dropdown in the family; this
+ * component owns the header-band trigger chrome, the keyboard model,
+ * and the standardized row verbs (rename / delete / drag-reorder).
+ * Removing/renaming emits to the host — this component never mutates
+ * the set, never confirms — the host decides the policy, the family
+ * keeps the look.
+ */
+export default defineComponent({
+  name: "HkHeaderPicker",
+  props: {
+    modelValue: { type: String, default: "" },
+    options: {
+      type: Array as PropType<HkPickerOption[]>,
+      default: () => [] as HkPickerOption[],
+    },
+    /** Placeholder when nothing is selected yet. */
+    placeholder: { type: String, default: "" },
+    /** Title for the OPENED surface only (sheet header / popout a11y). */
+    panelTitle: { type: String, default: undefined },
+    disabled: { type: Boolean, default: false },
+    /** Show drag grips and emit `reorder` (host owns the new order). */
+    reorderable: { type: Boolean, default: false },
+    /** Desktop-popout side relative to the trigger. The header sits at
+     *  the viewport's top, so the popout grows DOWNWARD (bottom-*) —
+     *  the mirror of bottom-pinned pickers; auto-flip still rescues a
+     *  viewport that cannot fit it. */
+    placement: {
+      type: String as PropType<SelectPanelPlacement>,
+      default: "bottom-start",
+    },
+    /** Accessible name of the trigger itself. */
+    ariaLabel: { type: String, default: undefined },
+  },
+  emits: {
+    "update:modelValue": (_value: string) => true,
+    /** A row's standardized rename action was pressed. */
+    edit: (_value: string) => true,
+    /** A row's standardized delete action was pressed. */
+    remove: (_value: string) => true,
+    /** Drag-reorder finished (reorderable): host reorders the array. */
+    reorder: (_fromIndex: number, _toIndex: number) => true,
+  },
+  setup(props, { emit }) {
+    const isOpen = ref(false);
+    const triggerRef = ref<HTMLElement>();
+    const panelExpose = ref<{ panelEl: () => HTMLElement | null }>();
+    const highlightedIndex = ref(-1);
+
+    // Pointer-hover highlighting only applies to the desktop popout —
+    // the mobile sheet rows never had it (spurious tap-highlight).
+    const { isMobile } = useBreakpoint();
+    const sheetMode = computed(() => isMobile.value);
+
+    const options = computed(() => props.options ?? []);
+
+    const displayLabel = computed(() => {
+      if (!props.modelValue) return props.placeholder || "";
+      return (
+        options.value.find((o) => o.value === props.modelValue)?.label ??
+        props.modelValue
+      );
+    });
+
+    function toggle() {
+      if (props.disabled) return;
+      isOpen.value = !isOpen.value;
+    }
+
+    function select(value: string) {
+      emit("update:modelValue", value);
+      isOpen.value = false;
+    }
+
+    function onEdit(e: MouseEvent, value: string) {
+      // The row's verb must not double as a row selection.
+      e.stopPropagation();
+      emit("edit", value);
+    }
+
+    function onRemove(e: MouseEvent, value: string) {
+      e.stopPropagation();
+      emit("remove", value);
+    }
+
+    function onReorder(from: number, to: number) {
+      emit("reorder", from, to);
+    }
+
+    function onTriggerKeydown(e: KeyboardEvent) {
+      if (props.disabled) return;
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        toggle();
+      } else if (e.key === "ArrowDown") {
+        e.preventDefault();
+        if (!isOpen.value) {
+          isOpen.value = true;
+          highlightedIndex.value = 0;
+        } else {
+          highlightedIndex.value =
+            (highlightedIndex.value + 1) % options.value.length;
+        }
+      } else if (e.key === "ArrowUp") {
+        e.preventDefault();
+        if (!isOpen.value) {
+          isOpen.value = true;
+        } else {
+          highlightedIndex.value =
+            (highlightedIndex.value - 1 + options.value.length) %
+            options.value.length;
+        }
+      } else if (e.key === "Escape") {
+        // Consume ONLY when it closed something — the trigger may sit
+        // inside a dialog surface whose own Escape must survive.
+        if (isOpen.value) {
+          e.preventDefault();
+          e.stopPropagation();
+        }
+        isOpen.value = false;
+      }
+    }
+
+    function onPopoutKeydown(e: KeyboardEvent) {
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        highlightedIndex.value =
+          (highlightedIndex.value + 1) % options.value.length;
+      } else if (e.key === "ArrowUp") {
+        e.preventDefault();
+        highlightedIndex.value =
+          (highlightedIndex.value - 1 + options.value.length) %
+          options.value.length;
+      } else if (e.key === "Enter") {
+        e.preventDefault();
+        const opt = options.value[highlightedIndex.value];
+        if (opt && !opt.disabled) select(opt.value);
+      } else if (e.key === "Escape") {
+        e.preventDefault();
+        isOpen.value = false;
+      }
+    }
+
+    function scrollToHighlighted() {
+      const root = panelExpose.value?.panelEl();
+      const el = root?.querySelector(`[data-select-index="${highlightedIndex.value}"]`);
+      el?.scrollIntoView({ block: "nearest" });
+    }
+
+    watch(isOpen, (open) => {
+      if (open) {
+        const idx = options.value.findIndex((o) => o.value === props.modelValue);
+        highlightedIndex.value = idx;
+        nextTick(() => scrollToHighlighted());
+      } else {
+        highlightedIndex.value = -1;
+      }
+    });
+
+    watch(highlightedIndex, () => scrollToHighlighted());
+
+    /** One standardized row: label + the affordances its flags light.
+     *  Selecting the row picks it; the verb buttons stop propagation so
+     *  a rename/delete never doubles as a selection. */
+    const renderRow = (opt: HkPickerOption, i: number) => (
+      <div
+        key={opt.value}
+        class="hk-select-option hk-header-picker-option"
+        data-highlighted={highlightedIndex.value === i || undefined}
+        data-select-index={i}
+        data-checked={opt.value === props.modelValue || undefined}
+        data-disabled={opt.disabled || undefined}
+        onClick={() => {
+          if (!opt.disabled) select(opt.value);
+        }}
+        {...(isOpen.value && !sheetMode.value
+          ? { onPointerenter: () => { highlightedIndex.value = i; } }
+          : {})}
+      >
+        <span class="hk-header-picker-option-label">{opt.label}</span>
+        <span class="hk-header-picker-option-actions">
+          {opt.editable && (
+            <HkIconButton
+              variant="ghost"
+              size={24}
+              aria-label="Rename"
+              onClick={(e: MouseEvent) => onEdit(e, opt.value)}
+            >
+              {{
+                icon: () => <Pencil size={14} />,
+              }}
+            </HkIconButton>
+          )}
+          {opt.removable && (
+            <HkIconButton
+              variant="ghost"
+              size={24}
+              aria-label="Delete"
+              onClick={(e: MouseEvent) => onRemove(e, opt.value)}
+            >
+              {{
+                icon: () => <Trash2 size={14} />,
+              }}
+            </HkIconButton>
+          )}
+        </span>
+      </div>
+    );
+
+    const renderRows = () => {
+      if (props.reorderable) {
+        return (
+          <HkDraggableList
+            items={options.value.map((o) => ({ ...o, key: o.value }))}
+            lockedKeys={options.value.filter((o) => o.locked).map((o) => o.value)}
+            onReorder={onReorder}
+          >
+            {{
+              item: ({ item, index }: { item: HkPickerOption; index: number }) =>
+                renderRow(options.value[index] ?? item, index),
+            }}
+          </HkDraggableList>
+        );
+      }
+      return options.value.map((opt, i) => renderRow(opt, i));
+    };
+
+    return () => (
+      <div class="hk-header-picker">
+        <button
+          ref={triggerRef}
+          type="button"
+          class="hk-select-trigger hk-header-picker-trigger"
+          data-state={isOpen.value ? "open" : "closed"}
+          data-disabled={props.disabled || undefined}
+          disabled={props.disabled}
+          aria-haspopup="listbox"
+          aria-expanded={isOpen.value}
+          aria-label={props.ariaLabel ?? props.panelTitle}
+          onClick={toggle}
+          onKeydown={onTriggerKeydown}
+        >
+          <span class="hk-select-value">{displayLabel.value || props.placeholder}</span>
+          <ChevronDown size={16} class="hk-select-arrow" />
+        </button>
+        <HkSelectPanel
+          ref={panelExpose}
+          open={isOpen.value}
+          onUpdate:open={(v: boolean) => { isOpen.value = v; }}
+          anchorRef={triggerRef.value ?? null}
+          title={props.panelTitle ?? ""}
+          placement={props.placement}
+          offset={4}
+          sheetOnMobile
+          onKeydown={onPopoutKeydown}
+        >
+          {renderRows()}
+        </HkSelectPanel>
+      </div>
+    );
+  },
+});

package/src/components/HkSelect.test.tsx

@@ -22,7 +22,7 @@ function setViewportWidth(px: number) {
   });
 }
 
-async function mountSelect() {
+async function mountSelect(props: Record<string, unknown> = {}) {
   const el = document.createElement("div");
   document.body.appendChild(el);
   const app = createApp({
@@ -34,6 +34,7 @@ async function mountSelect() {
           { value: "a", label: "Option A" },
           { value: "b", label: "Option B" },
         ],
+        ...props,
       }),
   });
   app.mount(el);
@@ -178,3 +179,24 @@ describe("HSelect mobile sheet", () => {
     el.remove();
   });
 });
+
+describe("HSelect desktop popout placement", () => {
+  afterEach(() => {
+    for (const el of Array.from(document.body.children)) {
+      if (el.className === "" || el.id === "") el.remove();
+    }
+  });
+
+  it("defaults to the form field's drop-down (bottom-start)", () => {
+    const vnode = h(HSelect, { modelValue: "", options: [] });
+    expect(vnode.props?.placement).toBeUndefined();
+  });
+
+  it("declares the placement prop (a bottom-pinned surface passes top-*)", () => {
+    // Through-wiring is pinned at the contract level: the prop exists
+    // with the historic default, and HkSelect's render forwards
+    // `placement={props.placement}` into HkSelectPanel.
+    expect(HSelect.props!.placement).toBeDefined();
+    expect((HSelect.props!.placement as { default: string }).default).toBe("bottom-start");
+  });
+});

package/src/components/HkSelect.tsx

@@ -10,7 +10,7 @@ import {
 
 import { ChevronDown } from "lucide-vue-next";
 import { useBreakpoint } from "../runtime/useBreakpoint";
-import HkSelectPanel from "./HkSelectPanel";
+import HkSelectPanel, { type SelectPanelPlacement } from "./HkSelectPanel";
 import "./HkSelect.scss";
 
 export interface HkSelectOption {
@@ -47,6 +47,19 @@ export default defineComponent({
       type: Array as PropType<HkSelectOption[]>,
       default: () => [] as HkSelectOption[],
     },
+    /**
+     * Desktop-popout side relative to the trigger (auto-flips when the
+     * viewport edge would clip it). The historic default — the form
+     * field's drop-DOWN — stays "bottom-start"; a surface pinned to the
+     * viewport's bottom band (a dock or a bar) passes "top-*" so the
+     * list grows UPWARD, the mirror image of a top-pinned surface
+     * growing downward. The mobile sheet always slides from the bottom
+     * edge regardless (it is an edge gesture, not an anchored popup).
+     */
+    placement: {
+      type: String as PropType<SelectPanelPlacement>,
+      default: "bottom-start",
+    },
   },
   emits: {
     "update:modelValue": (_value: string) => true,
@@ -204,7 +217,7 @@ export default defineComponent({
           onUpdate:open={(v: boolean) => { isOpen.value = v; }}
           anchorRef={triggerRef.value ?? null}
           title={props.panelTitle ?? props.label ?? ""}
-          placement="bottom-start"
+          placement={props.placement}
           offset={4}
           onKeydown={onPopoutKeydown}
         >