@celestia-island/hikari 0.55.131 → 0.55.132

package/package.json

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

package/src/components/HkUserPicker.scss

@@ -0,0 +1,184 @@
+// HkUserPicker (components/HkUserPicker.tsx) — the tag field + search
+// dialog pair. Tokens follow the house scale (--space-*, --radius-*,
+// rgb(var(--color-*)) — the HkKeywordSearchModal.scss conventions).
+
+.hk-user-picker {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 0.5rem);
+
+  &.is-disabled {
+    opacity: 0.55;
+    pointer-events: none;
+  }
+}
+
+.hk-user-picker-label {
+  font-size: 0.75rem;
+  color: rgb(var(--color-text) / 70%);
+}
+
+.hk-user-picker-field {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+  min-height: 2.5rem;
+  padding: var(--space-8, 0.5rem) var(--space-12, 0.75rem);
+  background: var(--hi-color-surface, rgba(240, 244, 248, 0.95));
+  border: 1px solid var(--hk-kw-border, rgb(var(--color-border) / 8%));
+  border-radius: var(--radius-lg, 0.75rem);
+  cursor: pointer;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+
+  &:focus-visible {
+    outline: none;
+    border-color: var(--hi-color-primary, #7aa2f7);
+    box-shadow: 0 0 0 3px color-mix(in srgb, var(--hi-color-primary, #7aa2f7) 12%, transparent);
+  }
+}
+
+.hk-user-picker-tag {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-4, 0.25rem);
+  max-width: 100%;
+  padding: var(--space-4, 0.25rem) var(--space-8, 0.5rem);
+  border-radius: var(--radius-md, 0.5rem);
+  background: rgb(var(--color-primary) / 12%);
+  border: 1px solid rgb(var(--color-primary) / 20%);
+}
+
+.hk-user-picker-tag-body {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.hk-user-picker-tag-name {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: rgb(var(--color-text));
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.hk-user-picker-tag-email {
+  font-size: 0.625rem;
+  color: rgb(var(--color-text) / 60%);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.hk-user-picker-tag-x {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1rem;
+  height: 1rem;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: rgb(var(--color-text) / 60%);
+  font-size: 0.875rem;
+  line-height: 1;
+  cursor: pointer;
+
+  &:hover {
+    background: rgb(var(--color-text) / 10%);
+    color: rgb(var(--color-text));
+  }
+}
+
+.hk-user-picker-add {
+  font-size: 0.75rem;
+  color: rgb(var(--color-text) / 60%);
+
+  &.is-placeholder {
+    color: rgb(var(--color-text) / 45%);
+  }
+}
+
+.hk-user-picker-dialog {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-12, 0.75rem);
+  padding: var(--space-4, 0.25rem) 0;
+}
+
+.hk-user-picker-rows {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4, 0.25rem);
+  min-height: 6rem;
+}
+
+.hk-user-picker-note {
+  margin: 0;
+  padding: var(--space-12, 0.75rem) 0;
+  font-size: 0.75rem;
+  color: rgb(var(--color-text) / 55%);
+  text-align: center;
+}
+
+.hk-user-picker-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-8, 0.5rem);
+  width: 100%;
+  padding: var(--space-8, 0.5rem) var(--space-12, 0.75rem);
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--radius-md, 0.5rem);
+  text-align: left;
+  cursor: pointer;
+
+  &:hover {
+    background: rgb(var(--color-text) / 6%);
+  }
+
+  &.is-selected {
+    background: rgb(var(--color-primary) / 12%);
+    border-color: rgb(var(--color-primary) / 25%);
+  }
+}
+
+.hk-user-picker-row-main {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.hk-user-picker-row-name {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: rgb(var(--color-text));
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.hk-user-picker-row-email {
+  font-size: 0.6875rem;
+  color: rgb(var(--color-text) / 60%);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.hk-user-picker-row-check {
+  flex: none;
+  color: var(--hi-color-primary, #7aa2f7);
+  font-weight: 700;
+}
+
+.hk-user-picker-count {
+  margin: 0;
+  font-size: 0.6875rem;
+  color: rgb(var(--color-text) / 55%);
+  text-align: right;
+}

package/src/components/HkUserPicker.test.tsx

@@ -0,0 +1,208 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, h, nextTick } from "vue";
+
+import HkUserPicker, { type HkUserOption } from "./HkUserPicker";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(renderNode: () => ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: renderNode });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+const alice: HkUserOption = { uid: "u-1", username: "alice", email: "alice@example.com", displayName: "Alice" };
+const bob: HkUserOption = { uid: "u-2", username: "bob", email: "bob@example.com" };
+const carol: HkUserOption = { uid: "u-3", username: "carol", email: "carol@example.com", displayName: "Carol" };
+
+function rows() {
+  return [...document.body.querySelectorAll<HTMLElement>(".hk-user-picker-row")];
+}
+
+describe("HkUserPicker", () => {
+  it("renders the value as tags showing the display name and email", () => {
+    mount(() => h(HkUserPicker, { modelValue: [alice, bob], search: async () => [] }));
+    const tags = [...document.body.querySelectorAll(".hk-user-picker-tag")];
+    expect(tags).toHaveLength(2);
+    expect(tags[0].textContent).toContain("Alice");
+    expect(tags[0].textContent).toContain("alice@example.com");
+    // No display name → the username is the tag title.
+    expect(tags[1].textContent).toContain("bob");
+  });
+
+  it("removing a tag emits the value without that user", async () => {
+    const onUpdate = vi.fn();
+    mount(() => h(HkUserPicker, {
+      modelValue: [alice, bob],
+      search: async () => [],
+      "onUpdate:modelValue": (users: HkUserOption[]) => onUpdate(users),
+    }));
+    const x = document.body.querySelector<HTMLButtonElement>(".hk-user-picker-tag-x");
+    x!.click();
+    await nextTick();
+    expect(onUpdate).toHaveBeenCalledWith([bob]);
+  });
+
+  it("opening the dialog runs the injected search with the empty query", async () => {
+    const search = vi.fn(async () => [alice, bob]);
+    mount(() => h(HkUserPicker, { modelValue: [], search }));
+    document.body.querySelector<HTMLElement>(".hk-user-picker-field")!.click();
+    await nextTick();
+    await nextTick();
+    expect(search).toHaveBeenCalledWith("");
+    expect(rows()).toHaveLength(2);
+  });
+
+  it("single mode emits one user on pick", async () => {
+    const onUpdate = vi.fn();
+    mount(() => h(HkUserPicker, {
+      modelValue: [],
+      search: async () => [alice, bob],
+      "onUpdate:modelValue": (users: HkUserOption[]) => onUpdate(users),
+    }));
+    document.body.querySelector<HTMLElement>(".hk-user-picker-field")!.click();
+    await nextTick();
+    await nextTick();
+    rows()[1].click();
+    await nextTick();
+    expect(onUpdate).toHaveBeenCalledWith([bob]);
+  });
+
+  it("multi mode accumulates picks and commits on confirm", async () => {
+    const onUpdate = vi.fn();
+    mount(() => h(HkUserPicker, {
+      modelValue: [],
+      mode: "multi",
+      search: async () => [alice, bob, carol],
+      "onUpdate:modelValue": (users: HkUserOption[]) => onUpdate(users),
+    }));
+    document.body.querySelector<HTMLElement>(".hk-user-picker-field")!.click();
+    await nextTick();
+    await nextTick();
+    rows()[0].click();
+    rows()[2].click();
+    // Re-picking a drafted row toggles it OUT again — the de-dup half of
+    // pickRow (pinned after the R2 mutation round caught it untested).
+    rows()[0].click();
+    await nextTick();
+    expect(onUpdate).not.toHaveBeenCalled();
+    const confirm = [...document.body.querySelectorAll<HTMLButtonElement>(".hk-modal-footer button")]
+      .find((b) => b.textContent === "Confirm")!;
+    confirm.click();
+    await nextTick();
+    expect(onUpdate).toHaveBeenCalledWith([carol]);
+  });
+
+  it("a stale search resolving late cannot clobber the newer results", async () => {
+    let releaseFirst: ((value: HkUserOption[]) => void) | null = null;
+    const first = new Promise<HkUserOption[]>((resolve) => { releaseFirst = resolve; });
+    const search = vi.fn()
+      .mockImplementationOnce(() => first)
+      .mockImplementationOnce(async () => [bob]);
+    mount(() => h(HkUserPicker, { modelValue: [], search }));
+    document.body.querySelector<HTMLElement>(".hk-user-picker-field")!.click();
+    await nextTick();
+    // Second query (the component's race token advances)…
+    // Reach runSearch directly through the input's search event wiring:
+    // HkSearchInput debounces at 250ms; fake timers advance past it.
+    vi.useFakeTimers();
+    const input = document.body.querySelector<HTMLInputElement>(".hk-user-picker-dialog input");
+    input!.value = "bob";
+    input!.dispatchEvent(new Event("input"));
+    // Flush the modelValue watch so HkSearchInput schedules its debounce
+    // timer on the fake clock BEFORE time advances past it.
+    await nextTick();
+    vi.advanceTimersByTime(300);
+    await Promise.resolve();
+    await Promise.resolve();
+    await nextTick();
+    // …then the stale first answer lands LAST — it must not win.
+    releaseFirst!([alice]);
+    await Promise.resolve();
+    await Promise.resolve();
+    await nextTick();
+    vi.useRealTimers();
+    const names = rows().map((r) => r.querySelector(".hk-user-picker-row-name")!.textContent);
+    expect(names).toEqual(["bob"]);
+  });
+
+  it("searches again on reopen after a full close (non-empty prior query)", async () => {
+    const search = vi.fn(async (q: string) => (q ? [bob] : [alice, bob]));
+    mount(() => h(HkUserPicker, { modelValue: [], search }));
+    const field = () => document.body.querySelector<HTMLElement>(".hk-user-picker-field")!;
+
+    // Session 1: open (search #1, ""), type "bob" (search #2), pick — single
+    // mode closes the dialog.
+    field().click();
+    await nextTick(); await nextTick();
+    const input = document.body.querySelector<HTMLInputElement>(".hk-user-picker-dialog input")!;
+    input.value = "bob";
+    input.dispatchEvent(new Event("input"));
+    await new Promise((r) => setTimeout(r, 300));
+    await nextTick();
+    rows()[0].click();
+    await nextTick();
+
+    // FULL close: wait past HkModal's leave window so the dialog content
+    // actually unmounts (the precondition of the R3 finding — while still
+    // mounted, the input's watcher masked the bug).
+    await new Promise((r) => setTimeout(r, 700));
+    expect(document.body.querySelector(".hk-user-picker-dialog")).toBeNull();
+
+    // Session 2: reopen MUST fire the initial-batch search("") again.
+    field().click();
+    await nextTick(); await nextTick();
+    expect(search).toHaveBeenLastCalledWith("");
+    expect(search.mock.calls.filter((c) => c[0] === "").length).toBe(2);
+    expect(rows()).toHaveLength(2);
+  });
+
+  it("fires exactly one search per open within the modal leave window", async () => {
+    const search = vi.fn(async (q: string) => (q ? [bob] : [alice, bob]));
+    mount(() => h(HkUserPicker, { modelValue: [], mode: "multi", search }));
+    const field = () => document.body.querySelector<HTMLElement>(".hk-user-picker-field")!;
+
+    // Session 1: open + type.
+    field().click();
+    await nextTick(); await nextTick();
+    const input = document.body.querySelector<HTMLInputElement>(".hk-user-picker-dialog input")!;
+    input.value = "bob";
+    input.dispatchEvent(new Event("input"));
+    await new Promise((r) => setTimeout(r, 300));
+    await nextTick();
+
+    // Close WITHOUT picking: the modal header's own × button.
+    const closeBtn = document.body.querySelector<HTMLButtonElement>(".hk-modal-close");
+    expect(closeBtn, "modal close button").toBeDefined();
+    closeBtn!.click();
+    await nextTick();
+    // Reopen IMMEDIATELY (inside the leave window — the input may still be
+    // mounted): the session-key remount + explicit search("") must yield
+    // exactly ONE new empty-query search, no watcher-originated duplicate.
+    field().click();
+    await nextTick(); await nextTick();
+    await new Promise((r) => setTimeout(r, 320));
+    const empties = search.mock.calls.filter((c) => c[0] === "");
+    expect(empties.length).toBe(2);
+    expect(search.mock.calls.filter((c) => c[0] === "bob").length).toBe(1);
+  });
+
+  it("a rejecting search renders the failure note instead of throwing", async () => {
+    mount(() => h(HkUserPicker, { modelValue: [], search: async () => { throw new Error("down"); } }));
+    document.body.querySelector<HTMLElement>(".hk-user-picker-field")!.click();
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".hk-user-picker-rows")!.getAttribute("data-state")).toBe("failed");
+    expect(rows()).toHaveLength(0);
+  });
+});

package/src/components/HkUserPicker.tsx

@@ -0,0 +1,267 @@
+// 2026-10-10 user direction — the ONE user-selection business component.
+//
+// Every surface that needs "pick one or more users" renders this field:
+// selected members travel as tags (display name + email), and picking
+// happens through a search dialog — type a nickname, username or email,
+// the injected `search` callback answers from the backend, click a row.
+// The dialog is HkModal (a centered window on desktop, the bottom sheet
+// on mobile — HkModal's own responsive treatment) with an HkSearchInput
+// as its box. Hosts inject the search itself, so the component carries
+// zero transport: the panel wires its user-list RPC, another host could
+// wire anything that resolves a query to user options.
+//
+// Semantics (the HkAffixPicker vocabulary): "single" closes on pick and
+// replaces the selection; "multi" toggles rows in a working copy and
+// commits on Confirm. The field's tag × removes directly — no dialog.
+import { computed, defineComponent, ref, watch, type PropType } from "vue";
+
+import { useI18n } from "../i18n/context";
+import HkModal, { type ModalAction } from "./HkModal";
+import HkSearchInput from "./HkSearchInput";
+import "./HkUserPicker.scss";
+
+/** One pickable user. `uid` is the stable identity (what the host stores);
+ *  `username`/`email`/`displayName`/`avatarUrl` are display baggage the
+ *  field keeps inside its value so hosts never re-fetch to re-render. */
+export interface HkUserOption {
+  uid: string;
+  username: string;
+  email?: string;
+  displayName?: string;
+  avatarUrl?: string;
+}
+
+/** Primary tag label: the display name when the deployment has one, the
+ *  username otherwise — never both stacked (the email line follows). */
+function tagTitle(user: HkUserOption): string {
+  return user.displayName?.trim() || user.username;
+}
+
+export default defineComponent({
+  name: "HkUserPicker",
+  props: {
+    modelValue: { type: Array as PropType<HkUserOption[]>, required: true },
+    /** "single" replaces the selection on pick; "multi" accumulates (the
+ *  HkAffixPicker mode vocabulary). */
+    mode: { type: String as PropType<"single" | "multi">, default: "single" },
+    /** Backend search: resolve a query (may be empty — the initial batch)
+     *  to user options. Rejections render as a retry hint, never a throw. */
+    search: { type: Function as PropType<(query: string) => Promise<HkUserOption[]>>, required: true },
+    label: { type: String, default: undefined },
+    placeholder: { type: String, default: undefined },
+    disabled: { type: Boolean, default: false },
+    /** Rows rendered per query — a runaway backend answer cannot turn the
+     *  dialog into a thousand-row scroll. */
+    maxResults: { type: Number, default: 50 },
+  },
+  emits: {
+    "update:modelValue": (_users: HkUserOption[]) => true,
+  },
+  setup(props, { emit }) {
+    const { t } = useI18n();
+
+    const open = ref(false);
+    const query = ref("");
+    const results = ref<HkUserOption[]>([]);
+    const loading = ref(false);
+    const failed = ref(false);
+    /** Multi-mode working copy — committed only on Confirm. */
+    const draft = ref<HkUserOption[]>([]);
+    /** Race guard: only the newest in-flight search may write results. */
+    let searchToken = 0;
+
+    async function runSearch(q: string) {
+      const token = ++searchToken;
+      loading.value = true;
+      failed.value = false;
+      try {
+        const found = await props.search(q);
+        if (token !== searchToken) return;
+        results.value = (found ?? []).slice(0, props.maxResults);
+      } catch {
+        if (token !== searchToken) return;
+        results.value = [];
+        failed.value = true;
+      } finally {
+        if (token === searchToken) loading.value = false;
+      }
+    }
+
+    const openDialog = () => {
+      if (props.disabled) return;
+      open.value = true;
+    };
+
+    // One search per open, always: the input is keyed per session, so it
+    // REMOUNTS on every open (a fresh mount receives modelValue "" and
+    // its no-immediate watch fires nothing; the remounted instance also
+    // drops any in-flight debounce from the previous session), and the
+    // explicit runSearch("") below is the one initial batch. Reopening
+    // after a full close MUST search too — HkModal unmounts its content
+    // when closed, so no watcher would ever fire (the R3 finding).
+    const sessionSeq = ref(0);
+    watch(open, (now) => {
+      if (!now) return;
+      sessionSeq.value += 1;
+      query.value = "";
+      results.value = [];
+      draft.value = [...props.modelValue];
+      void runSearch("");
+    });
+
+    const onSearch = (q: string) => {
+      void runSearch(q);
+    };
+
+    const inDraft = (uid: string) => draft.value.some((u) => u.uid === uid);
+
+    const pickRow = (user: HkUserOption) => {
+      if (props.mode === "single") {
+        open.value = false;
+        emit("update:modelValue", [user]);
+        return;
+      }
+      draft.value = inDraft(user.uid)
+        ? draft.value.filter((u) => u.uid !== user.uid)
+        : [...draft.value, user];
+    };
+
+    const confirmDraft = () => {
+      open.value = false;
+      emit("update:modelValue", draft.value);
+    };
+
+    const removeTag = (uid: string) => {
+      if (props.disabled) return;
+      emit(
+        "update:modelValue",
+        props.modelValue.filter((u) => u.uid !== uid),
+      );
+    };
+
+    const dialogTitle = computed(
+      () => props.label ?? t("hikari::userPicker.title", "Select users"),
+    );
+
+    const dialogActions = computed<ModalAction[] | undefined>(() =>
+      props.mode === "multi"
+        ? [
+            {
+              label: t("hikari::messageBox.cancel", "Cancel"),
+              variant: "secondary",
+              onClick: () => { open.value = false; },
+            },
+            {
+              label: t("hikari::userPicker.confirm", "Confirm"),
+              variant: "primary",
+              disabled: draft.value.length === 0,
+              onClick: confirmDraft,
+            },
+          ]
+        : undefined,
+    );
+
+    return () => (
+      <div class={{ "hk-user-picker": true, "is-disabled": props.disabled }}>
+        {props.label && <div class="hk-user-picker-label">{props.label}</div>}
+        <div
+          class="hk-user-picker-field"
+          role="button"
+          tabindex={props.disabled ? -1 : 0}
+          aria-disabled={props.disabled}
+          aria-label={props.label ?? t("hikari::userPicker.title", "Select users")}
+          onClick={openDialog}
+          onKeydown={(e: KeyboardEvent) => {
+            if (props.disabled) return;
+            if (e.key === "Enter" || e.key === " ") {
+              e.preventDefault();
+              openDialog();
+            }
+          }}
+        >
+          {props.modelValue.map((user) => (
+            <span key={user.uid} class="hk-user-picker-tag" title={`${tagTitle(user)} ${user.email ?? ""}`.trim()}>
+              <span class="hk-user-picker-tag-body">
+                <span class="hk-user-picker-tag-name">{tagTitle(user)}</span>
+                {user.email && <span class="hk-user-picker-tag-email">{user.email}</span>}
+              </span>
+              {!props.disabled && (
+                <button
+                  type="button"
+                  class="hk-user-picker-tag-x"
+                  aria-label={`${t("hikari::userPicker.remove", "Remove")} ${tagTitle(user)}`}
+                  onClick={(e: MouseEvent) => {
+                    e.stopPropagation();
+                    removeTag(user.uid);
+                  }}
+                >
+                  ×
+                </button>
+              )}
+            </span>
+          ))}
+          <span class={{ "hk-user-picker-add": true, "is-placeholder": props.modelValue.length === 0 }}>
+            {props.modelValue.length === 0
+              ? (props.placeholder ?? t("hikari::userPicker.add", "Select users…"))
+              : t("hikari::userPicker.add", "Select users…")}
+          </span>
+        </div>
+
+        <HkModal
+          modelValue={open.value}
+          onUpdate:modelValue={(v: boolean) => { open.value = v; }}
+          title={dialogTitle.value}
+          width="30rem"
+          footerActions={dialogActions.value}
+        >
+          <div class="hk-user-picker-dialog">
+            <HkSearchInput
+              key={sessionSeq.value}
+              modelValue={query.value}
+              onUpdate:modelValue={(v: string) => { query.value = v; }}
+              onSearch={onSearch}
+              debounce={250}
+              placeholder={t("hikari::userPicker.searchPlaceholder", "Nickname, username or email")}
+            />
+            <div class="hk-user-picker-rows" data-state={loading.value ? "loading" : failed.value ? "failed" : results.value.length === 0 ? "empty" : "ready"}>
+              {loading.value && (
+                <p class="hk-user-picker-note">{t("hikari::userPicker.searching", "Searching…")}</p>
+              )}
+              {!loading.value && failed.value && (
+                <p class="hk-user-picker-note">{t("hikari::userPicker.searchFailed", "The search failed; try again.")}</p>
+              )}
+              {!loading.value && !failed.value && results.value.length === 0 && (
+                <p class="hk-user-picker-note">
+                  {query.value.trim()
+                    ? t("hikari::userPicker.empty", "No users match this search.")
+                    : t("hikari::userPicker.emptyInitial", "Type a nickname, username or email to search.")}
+                </p>
+              )}
+              {!loading.value && results.value.map((user) => (
+                <button
+                  key={user.uid}
+                  type="button"
+                  class={{ "hk-user-picker-row": true, "is-selected": props.mode === "multi" && inDraft(user.uid) }}
+                  onClick={() => pickRow(user)}
+                >
+                  <span class="hk-user-picker-row-main">
+                    <span class="hk-user-picker-row-name">{tagTitle(user)}</span>
+                    {user.email && <span class="hk-user-picker-row-email">{user.email}</span>}
+                  </span>
+                  {props.mode === "multi" && inDraft(user.uid) && (
+                    <span class="hk-user-picker-row-check" aria-hidden>✓</span>
+                  )}
+                </button>
+              ))}
+            </div>
+            {props.mode === "multi" && draft.value.length > 0 && (
+              <p class="hk-user-picker-count">
+                {t("hikari::userPicker.selectedCount", "{count} selected").replace("{count}", String(draft.value.length))}
+              </p>
+            )}
+          </div>
+        </HkModal>
+      </div>
+    );
+  },
+});

package/src/i18n/locales/ar/components.json

@@ -262,5 +262,15 @@
   "hikari::mfaVerify.back": "العودة لتسجيل الدخول",
   "hikari::mfaVerify.loading": "جارٍ التحميل...",
   "hikari::board3d.resetView": "إعادة تعيين العرض",
-  "hikari::board3d.unavailable": "العرض ثلاثي الأبعاد غير متوفر على هذا الجهاز"
+  "hikari::board3d.unavailable": "العرض ثلاثي الأبعاد غير متوفر على هذا الجهاز",
+  "hikari::userPicker.title": "اختيار المستخدمين",
+  "hikari::userPicker.searchPlaceholder": "الاسم المستعار أو اسم المستخدم أو البريد الإلكتروني",
+  "hikari::userPicker.searching": "جارٍ البحث…",
+  "hikari::userPicker.emptyInitial": "اكتب اسمًا مستعارًا أو اسم مستخدم أو بريدًا إلكترونيًا للبحث.",
+  "hikari::userPicker.empty": "لا يوجد مستخدمون مطابقون لهذا البحث.",
+  "hikari::userPicker.searchFailed": "فشل البحث؛ حاول مرة أخرى.",
+  "hikari::userPicker.add": "اختيار المستخدمين…",
+  "hikari::userPicker.remove": "إزالة",
+  "hikari::userPicker.confirm": "تأكيد",
+  "hikari::userPicker.selectedCount": "تم اختيار {count}"
 }

package/src/i18n/locales/de/components.json

@@ -262,5 +262,15 @@
   "hikari::mfaVerify.back": "Zurück zur Anmeldung",
   "hikari::mfaVerify.loading": "Laden...",
   "hikari::board3d.resetView": "Ansicht zurücksetzen",
-  "hikari::board3d.unavailable": "3D ist auf diesem Gerät nicht verfügbar"
+  "hikari::board3d.unavailable": "3D ist auf diesem Gerät nicht verfügbar",
+  "hikari::userPicker.title": "Benutzer auswählen",
+  "hikari::userPicker.searchPlaceholder": "Spitzname, Benutzername oder E-Mail",
+  "hikari::userPicker.searching": "Suche…",
+  "hikari::userPicker.emptyInitial": "Gib einen Spitznamen, Benutzernamen oder eine E-Mail ein, um zu suchen.",
+  "hikari::userPicker.empty": "Keine Benutzer entsprechen dieser Suche.",
+  "hikari::userPicker.searchFailed": "Die Suche ist fehlgeschlagen; versuche es erneut.",
+  "hikari::userPicker.add": "Benutzer auswählen…",
+  "hikari::userPicker.remove": "Entfernen",
+  "hikari::userPicker.confirm": "Bestätigen",
+  "hikari::userPicker.selectedCount": "{count} ausgewählt"
 }

package/src/i18n/locales/en/components.json

@@ -262,5 +262,15 @@
   "hikari::mfaVerify.back": "Back to sign in",
   "hikari::mfaVerify.loading": "Loading...",
   "hikari::board3d.resetView": "Reset view",
-  "hikari::board3d.unavailable": "3D is unavailable on this device"
+  "hikari::board3d.unavailable": "3D is unavailable on this device",
+  "hikari::userPicker.title": "Select users",
+  "hikari::userPicker.searchPlaceholder": "Nickname, username or email",
+  "hikari::userPicker.searching": "Searching…",
+  "hikari::userPicker.emptyInitial": "Type a nickname, username or email to search.",
+  "hikari::userPicker.empty": "No users match this search.",
+  "hikari::userPicker.searchFailed": "The search failed; try again.",
+  "hikari::userPicker.add": "Select users…",
+  "hikari::userPicker.remove": "Remove",
+  "hikari::userPicker.confirm": "Confirm",
+  "hikari::userPicker.selectedCount": "{count} selected"
 }

package/src/i18n/locales/es/components.json

@@ -262,5 +262,15 @@
   "hikari::mfaVerify.back": "Volver al inicio de sesión",
   "hikari::mfaVerify.loading": "Cargando...",
   "hikari::board3d.resetView": "Restablecer vista",
-  "hikari::board3d.unavailable": "El 3D no está disponible en este dispositivo"
+  "hikari::board3d.unavailable": "El 3D no está disponible en este dispositivo",
+  "hikari::userPicker.title": "Seleccionar usuarios",
+  "hikari::userPicker.searchPlaceholder": "Apodo, nombre de usuario o correo",
+  "hikari::userPicker.searching": "Buscando…",
+  "hikari::userPicker.emptyInitial": "Escribe un apodo, nombre de usuario o correo para buscar.",
+  "hikari::userPicker.empty": "Ningún usuario coincide con esta búsqueda.",
+  "hikari::userPicker.searchFailed": "La búsqueda falló; inténtalo de nuevo.",
+  "hikari::userPicker.add": "Seleccionar usuarios…",
+  "hikari::userPicker.remove": "Quitar",
+  "hikari::userPicker.confirm": "Confirmar",
+  "hikari::userPicker.selectedCount": "{count} seleccionados"
 }

package/src/i18n/locales/fr/components.json

@@ -262,5 +262,15 @@
   "hikari::mfaVerify.back": "Retour à la connexion",
   "hikari::mfaVerify.loading": "Chargement...",
   "hikari::board3d.resetView": "Réinitialiser la vue",
-  "hikari::board3d.unavailable": "La 3D n'est pas disponible sur cet appareil"
+  "hikari::board3d.unavailable": "La 3D n'est pas disponible sur cet appareil",
+  "hikari::userPicker.title": "Sélectionner des utilisateurs",
+  "hikari::userPicker.searchPlaceholder": "Pseudo, nom d'utilisateur ou e-mail",
+  "hikari::userPicker.searching": "Recherche…",
+  "hikari::userPicker.emptyInitial": "Saisissez un pseudo, un nom d'utilisateur ou un e-mail pour rechercher.",
+  "hikari::userPicker.empty": "Aucun utilisateur ne correspond à cette recherche.",
+  "hikari::userPicker.searchFailed": "La recherche a échoué ; réessayez.",
+  "hikari::userPicker.add": "Sélectionner des utilisateurs…",
+  "hikari::userPicker.remove": "Retirer",
+  "hikari::userPicker.confirm": "Confirmer",
+  "hikari::userPicker.selectedCount": "{count} sélectionnés"
 }

package/src/i18n/locales/ja/components.json

@@ -262,5 +262,15 @@
   "hikari::mfaVerify.back": "ログインに戻る",
   "hikari::mfaVerify.loading": "読み込み中...",
   "hikari::board3d.resetView": "視点をリセット",
-  "hikari::board3d.unavailable": "このデバイスでは 3D を利用できません"
+  "hikari::board3d.unavailable": "このデバイスでは 3D を利用できません",
+  "hikari::userPicker.title": "ユーザーを選択",
+  "hikari::userPicker.searchPlaceholder": "ニックネーム、ユーザー名またはメールアドレス",
+  "hikari::userPicker.searching": "検索中…",
+  "hikari::userPicker.emptyInitial": "ニックネーム、ユーザー名またはメールアドレスを入力して検索してください。",
+  "hikari::userPicker.empty": "この検索に一致するユーザーはいません。",
+  "hikari::userPicker.searchFailed": "検索に失敗しました。もう一度お試しください。",
+  "hikari::userPicker.add": "ユーザーを選択…",
+  "hikari::userPicker.remove": "削除",
+  "hikari::userPicker.confirm": "確認",
+  "hikari::userPicker.selectedCount": "{count} 件選択中"
 }

package/src/i18n/locales/ko/components.json

@@ -262,5 +262,15 @@
   "hikari::mfaVerify.back": "로그인으로 돌아가기",
   "hikari::mfaVerify.loading": "로딩 중...",
   "hikari::board3d.resetView": "시점 재설정",
-  "hikari::board3d.unavailable": "이 기기에서는 3D를 사용할 수 없습니다"
+  "hikari::board3d.unavailable": "이 기기에서는 3D를 사용할 수 없습니다",
+  "hikari::userPicker.title": "사용자 선택",
+  "hikari::userPicker.searchPlaceholder": "닉네임, 사용자 이름 또는 이메일",
+  "hikari::userPicker.searching": "검색 중…",
+  "hikari::userPicker.emptyInitial": "닉네임, 사용자 이름 또는 이메일을 입력해 검색하세요.",
+  "hikari::userPicker.empty": "이 검색과 일치하는 사용자가 없습니다.",
+  "hikari::userPicker.searchFailed": "검색에 실패했습니다. 다시 시도하세요.",
+  "hikari::userPicker.add": "사용자 선택…",
+  "hikari::userPicker.remove": "제거",
+  "hikari::userPicker.confirm": "확인",
+  "hikari::userPicker.selectedCount": "{count}명 선택됨"
 }

package/src/i18n/locales/pt/components.json

@@ -262,5 +262,15 @@
   "hikari::mfaVerify.back": "Voltar ao login",
   "hikari::mfaVerify.loading": "Carregando...",
   "hikari::board3d.resetView": "Redefinir visualização",
-  "hikari::board3d.unavailable": "O 3D não está disponível neste dispositivo"
+  "hikari::board3d.unavailable": "O 3D não está disponível neste dispositivo",
+  "hikari::userPicker.title": "Selecionar usuários",
+  "hikari::userPicker.searchPlaceholder": "Apelido, nome de usuário ou e-mail",
+  "hikari::userPicker.searching": "Pesquisando…",
+  "hikari::userPicker.emptyInitial": "Digite um apelido, nome de usuário ou e-mail para pesquisar.",
+  "hikari::userPicker.empty": "Nenhum usuário corresponde a esta pesquisa.",
+  "hikari::userPicker.searchFailed": "A pesquisa falhou; tente novamente.",
+  "hikari::userPicker.add": "Selecionar usuários…",
+  "hikari::userPicker.remove": "Remover",
+  "hikari::userPicker.confirm": "Confirmar",
+  "hikari::userPicker.selectedCount": "{count} selecionados"
 }

package/src/i18n/locales/ru/components.json

@@ -262,5 +262,15 @@
   "hikari::mfaVerify.back": "Вернуться к входу",
   "hikari::mfaVerify.loading": "Загрузка...",
   "hikari::board3d.resetView": "Сбросить вид",
-  "hikari::board3d.unavailable": "3D недоступно на этом устройстве"
+  "hikari::board3d.unavailable": "3D недоступно на этом устройстве",
+  "hikari::userPicker.title": "Выбрать пользователей",
+  "hikari::userPicker.searchPlaceholder": "Ник, имя пользователя или эл. почта",
+  "hikari::userPicker.searching": "Поиск…",
+  "hikari::userPicker.emptyInitial": "Введите ник, имя пользователя или эл. почту для поиска.",
+  "hikari::userPicker.empty": "Нет пользователей, соответствующих этому запросу.",
+  "hikari::userPicker.searchFailed": "Поиск не удался; попробуйте ещё раз.",
+  "hikari::userPicker.add": "Выбрать пользователей…",
+  "hikari::userPicker.remove": "Убрать",
+  "hikari::userPicker.confirm": "Подтвердить",
+  "hikari::userPicker.selectedCount": "Выбрано: {count}"
 }

package/src/i18n/locales/zh-Hans/components.json

@@ -266,5 +266,15 @@
   "hikari::mfaVerify.back": "返回重新登录",
   "hikari::mfaVerify.loading": "加载中...",
   "hikari::board3d.resetView": "重置视角",
-  "hikari::board3d.unavailable": "此设备不支持 3D 显示"
+  "hikari::board3d.unavailable": "此设备不支持 3D 显示",
+  "hikari::userPicker.title": "选择用户",
+  "hikari::userPicker.searchPlaceholder": "昵称、用户名或邮箱",
+  "hikari::userPicker.searching": "搜索中…",
+  "hikari::userPicker.emptyInitial": "输入昵称、用户名或邮箱开始搜索。",
+  "hikari::userPicker.empty": "没有符合搜索的用户。",
+  "hikari::userPicker.searchFailed": "搜索失败，请重试。",
+  "hikari::userPicker.add": "选择用户…",
+  "hikari::userPicker.remove": "移除",
+  "hikari::userPicker.confirm": "确认",
+  "hikari::userPicker.selectedCount": "已选 {count} 人"
 }

package/src/i18n/locales/zh-Hant/components.json

@@ -266,5 +266,15 @@
   "hikari::mfaVerify.back": "返回重新登入",
   "hikari::mfaVerify.loading": "加載中...",
   "hikari::board3d.resetView": "重設視角",
-  "hikari::board3d.unavailable": "此裝置不支援 3D 顯示"
+  "hikari::board3d.unavailable": "此裝置不支援 3D 顯示",
+  "hikari::userPicker.title": "選擇使用者",
+  "hikari::userPicker.searchPlaceholder": "暱稱、使用者名稱或電子郵件",
+  "hikari::userPicker.searching": "搜尋中…",
+  "hikari::userPicker.emptyInitial": "輸入暱稱、使用者名稱或電子郵件開始搜尋。",
+  "hikari::userPicker.empty": "沒有符合搜尋的使用者。",
+  "hikari::userPicker.searchFailed": "搜尋失敗，請重試。",
+  "hikari::userPicker.add": "選擇使用者…",
+  "hikari::userPicker.remove": "移除",
+  "hikari::userPicker.confirm": "確認",
+  "hikari::userPicker.selectedCount": "已選 {count} 人"
 }

package/src/index.ts

@@ -715,6 +715,7 @@ export { default as HkNavItem } from "./components/HkNavItem";
 export { default as HkNumberInput } from "./components/HkNumberInput";
 export { default as HkPhoneInput } from "./components/HkPhoneInput";
 export { default as HkAffixPicker } from "./components/HkAffixPicker";
+export { default as HkUserPicker, type HkUserOption } from "./components/HkUserPicker";
 export { default as HkPhaseTransition } from "./components/HkPhaseTransition";
 export { default as HkGaugeRing } from "./components/HkGaugeRing";
 export { default as HkProgressRing } from "./components/HkProgressRing";