@celestia-island/hikari 0.40.35 → 0.40.36

package/package.json

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

package/src/DemoApp.tsx

@@ -9,6 +9,7 @@ import {
   HProgressBar, HProgressRing, HGaugeRing,
   HInput, HSearchInput, HNumberInput, HPasswordInput, HTextarea,
   HFileField,
+  HFilePickerField,
   type PickedFile, type RemoteFsAdapter,
   HCheckbox, HSwitch, HRadio, HSelect, HSelectPanel,
   HLocalizedInput,
@@ -21,7 +22,7 @@ import {
   type TrendPen, type MinimapBox,
 } from "@celestia-island/hikari";
 
-const totalComponents = 66;
+const totalComponents = 67;
 
 const icons = ["home", "settings", "user", "search", "bell", "heart", "star", "mail", "download", "upload", "trash", "edit", "plus", "check", "x"];
 
@@ -102,6 +103,12 @@ export default defineComponent({
     const form = ref({ text: "", search: "", number: 0, password: "", textarea: "" });
     const localFiles = ref<PickedFile[]>([]);
     const remoteFiles = ref<PickedFile[]>([]);
+    const hookPath = ref("");
+    const remotePath = ref("/data");
+    // Stands in for a host-opened OS dialog (the Tauri2/Electron case —
+    // the window lives outside the webview, so the field takes a hook).
+    const fakeHostPicker = async (): Promise<string | null> =>
+      Promise.resolve("/opt/acme/install");
     // In-memory remote FS so the remote picker demo browses something real.
     const demoRemoteFs: RemoteFsAdapter = (() => {
       const tree: Record<string, { name: string; kind: "file" | "dir"; size?: number }[]> = {
@@ -317,6 +324,27 @@ export default defineComponent({
           ) : null}
         </section>
 
+        <section>
+          <h2>HFilePickerField</h2>
+          <div class="form-grid">
+            <HFilePickerField
+              modelValue={hookPath.value}
+              onUpdate:modelValue={(v: string) => (hookPath.value = v)}
+              label="Install location (host hook)"
+              hint="A host-opened OS dialog — e.g. the Tauri2 dialog plugin."
+              pick={fakeHostPicker}
+            />
+            <HFilePickerField
+              modelValue={remotePath.value}
+              onUpdate:modelValue={(v: string) => (remotePath.value = v)}
+              label="Remote folder (in-app picker)"
+              backend="remote"
+              adapter={demoRemoteFs}
+              quickLinks={[{ label: "Root", path: "/" }, { label: "Data", path: "/data" }]}
+            />
+          </div>
+        </section>
+
         <section>
           <h2>HCheckbox / HSwitch / HRadio</h2>
           <div class="row">

package/src/components/HkCheckbox.tsx

@@ -52,7 +52,6 @@ export default defineComponent({
 
     return () => {
       const inputType = props.type === "radio" ? "radio" : "checkbox";
-      const isChecked = props.modelValue === true || props.modelValue === null;
 
       return (
         <label

package/src/components/HkEmptyState.test.tsx

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h } from "vue";
 
 import HkEmptyState from "./HkEmptyState";
@@ -56,6 +56,26 @@ describe("HkEmptyState", () => {
     expect(btn.textContent).toBe("Retry");
   });
 
+  it("accepts functional icon components without a prop-type warning", () => {
+    // lucide-vue-next icons are plain functions; the Object-only runtime
+    // check rejected them with a dev warning at every chest call site
+    // (fixed 2026-09-09: [Object, Function]).
+    const warnings: string[] = [];
+    const spy = vi.spyOn(console, "warn").mockImplementation((...args: unknown[]) => {
+      warnings.push(args.join(" "));
+    });
+    try {
+      // Shape-mirrors a lucide icon: a functional component accepting
+      // props (size/aria) and rendering a node.
+      const lucideLike = ((_props: unknown) => h("i", { class: "fn-icon" })) as never;
+      const c = mount(h(HkEmptyState, { title: "No items", icon: lucideLike }));
+      expect(c.querySelector(".hk-empty-icon .fn-icon")).not.toBeNull();
+      expect(warnings.filter((w) => w.includes("Invalid prop"))).toEqual([]);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
   it("renders the icon prop component in the icon well", () => {
     const c = mount(h(HkEmptyState, { title: "No items", icon: StubIcon }));
     expect(c.querySelector(".hk-empty-icon .stub-empty-icon")).not.toBeNull();

package/src/components/HkEmptyState.tsx

@@ -11,7 +11,7 @@ export default defineComponent({
     title: { type: String, default: undefined },
     description: { type: String, default: undefined },
     /** Icon component (lucide-vue-next style); rendered via h() at size 32. */
-    icon: { type: Object as PropType<Component>, default: undefined },
+    icon: { type: [Object, Function] as PropType<Component>, default: undefined },
     /** Loading variant: only a centered spinner, exposed as a status region. */
     loading: { type: Boolean, default: false },
     /** page = bounded, centered card on desktop; fill = stretch to the host. */

package/src/components/HkFileBrowserDialog.test.tsx

@@ -71,6 +71,7 @@ interface MountOptions {
   multiple?: boolean;
   quickLinks?: Array<{ label: string; path: string }>;
   initialPath?: string;
+  pickDirectory?: boolean;
 }
 
 function mountDialog(adapter: RemoteFsAdapter, opts: MountOptions = {}) {
@@ -91,6 +92,7 @@ function mountDialog(adapter: RemoteFsAdapter, opts: MountOptions = {}) {
           multiple: opts.multiple ?? false,
           quickLinks: opts.quickLinks ?? [],
           initialPath: opts.initialPath ?? "/",
+          pickDirectory: opts.pickDirectory ?? false,
           "onUpdate:modelValue": (v: boolean) => {
             openEvents.push(v);
             open.value = v;
@@ -446,3 +448,44 @@ describe("HkFileBrowserDialog load states", () => {
     expect(rowNames()).toEqual(["ok.txt"]);
   });
 });
+
+describe("HkFileBrowserDialog directory mode", () => {
+  it("confirms the listed folder without needing a selection", async () => {
+    const adapter = makeAdapter();
+    const { confirmed, openEvents } = mountDialog(adapter, { pickDirectory: true });
+    await flush();
+
+    // Nothing is selected, yet confirm is live: the current folder IS
+    // the choice.
+    const confirmBtn = q<HTMLButtonElement>(".hk-file-browser-confirm");
+    expect(confirmBtn.disabled).toBe(false);
+    expect(confirmBtn.textContent).toContain("Choose this folder");
+    confirmBtn.click();
+    await flush();
+    expect(confirmed).toEqual([[{ name: "/", path: "/" }]]);
+    expect(openEvents).toContain(false);
+  });
+
+  it("navigates into subfolders and hands back that folder's path", async () => {
+    const adapter = makeAdapter();
+    const { confirmed } = mountDialog(adapter, { pickDirectory: true });
+    await flush();
+
+    await clickRow("reports");
+    expect(adapter.list).toHaveBeenLastCalledWith("/reports");
+    const confirmBtn = q<HTMLButtonElement>(".hk-file-browser-confirm");
+    confirmBtn.click();
+    await flush();
+    expect(confirmed).toEqual([[{ name: "reports", path: "/reports" }]]);
+  });
+
+  it("never selects file rows while picking a folder", async () => {
+    const adapter = makeAdapter();
+    mountDialog(adapter, { pickDirectory: true });
+    await flush();
+
+    await clickRow("data.csv");
+    const rows = qa<HTMLButtonElement>(".hk-file-browser-row");
+    expect(rows.every((r) => r.dataset.selected === undefined)).toBe(true);
+  });
+});

package/src/components/HkFileBrowserDialog.tsx

@@ -112,6 +112,11 @@ export default defineComponent({
       type: Array as PropType<FileQuickLink[]>,
       default: () => [],
     },
+    /**
+     * Directory-picking mode: confirm chooses the folder currently
+     * listed (entries only navigate), instead of selecting files.
+     */
+    pickDirectory: { type: Boolean, default: false },
     confirmLabel: { type: String, default: undefined },
     cancelLabel: { type: String, default: undefined },
   },
@@ -290,6 +295,8 @@ export default defineComponent({
         navigate(joinPath(currentPath.value, entry.name));
         return;
       }
+      // Directory-picking mode only navigates; files are inert rows.
+      if (props.pickDirectory) return;
       const next = new Set(selected.value);
       if (props.multiple) {
         if (next.has(entry.name)) next.delete(entry.name);
@@ -306,7 +313,7 @@ export default defineComponent({
     /** Double-click activates: the file confirms immediately (and alone,
      *  even in multiple mode — a double-click names ONE file). */
     function onEntryActivate(entry: RemoteFileEntry) {
-      if (entry.kind !== "file") return;
+      if (entry.kind !== "file" || props.pickDirectory) return;
       selected.value = new Set([entry.name]);
       confirmSelection();
     }
@@ -394,6 +401,15 @@ export default defineComponent({
     }
 
     function confirmSelection() {
+      // Directory mode: the folder currently listed IS the choice —
+      // the pathbar has been showing it the whole time.
+      if (props.pickDirectory) {
+        const path = currentPath.value;
+        const name = path.replace(/\/+$/, "").split("/").filter(Boolean).pop() ?? "/";
+        emit("confirm", [{ name, path }]);
+        close();
+        return;
+      }
       if (selected.value.size === 0) return;
       const files: ConfirmedFile[] = [];
       for (const name of selected.value) {
@@ -770,10 +786,13 @@ export default defineComponent({
               variant="primary"
               size="md"
               class="hk-file-browser-confirm"
-              disabled={selected.value.size === 0}
+              disabled={!props.pickDirectory && selected.value.size === 0}
               onClick={confirmSelection}
             >
-              {props.confirmLabel ?? t("hikari::filePicker.confirm", "Confirm")}
+              {props.confirmLabel ??
+                (props.pickDirectory
+                  ? t("hikari::filePicker.chooseFolder", "Choose this folder")
+                  : t("hikari::filePicker.confirm", "Confirm"))}
             </HButton>
           </div>
         </div>
@@ -783,7 +802,12 @@ export default defineComponent({
     return () => (
       <HModal
         modelValue={props.modelValue}
-        title={props.title ?? t("hikari::filePicker.title", "Browse files")}
+        title={
+          props.title ??
+          (props.pickDirectory
+            ? t("hikari::filePicker.titleFolder", "Browse folders")
+            : t("hikari::filePicker.title", "Browse files"))
+        }
         width="56rem"
         onUpdate:modelValue={(v: boolean) => emit("update:modelValue", v)}
       >

package/src/components/HkFilePickerField.scss

@@ -0,0 +1,93 @@
+.hk-file-picker-field {
+  display: block;
+}
+
+.hk-file-picker-label {
+  display: block;
+  font-size: var(--text-xs);
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  margin-bottom: var(--space-4);
+  color: rgb(var(--color-text) / var(--hk-field-label-alpha, 72%));
+}
+
+.hk-file-picker-box {
+  display: flex;
+  align-items: center;
+  gap: var(--space-6);
+  padding: var(--space-4) var(--space-6);
+  min-height: 2.5rem;
+  background: color-mix(in srgb, rgb(var(--color-surface)) 55%, transparent);
+  border: 1px solid color-mix(in srgb, rgb(var(--color-text)) 14%, transparent);
+  border-radius: var(--radius-sm);
+  transition:
+    border-color var(--duration-normal) var(--ease-standard),
+    background-color var(--duration-normal) var(--ease-standard);
+
+  &:focus-within {
+    border-color: color-mix(in srgb, rgb(var(--color-text)) 38%, transparent);
+  }
+
+  &[data-error] {
+    border-color: var(--hi-color-danger);
+  }
+
+  &[data-disabled] {
+    opacity: 0.55;
+    pointer-events: none;
+  }
+}
+
+/* The shittim-chest file-picker badge: a primary-tinted rounded square
+   carrying the folder glyph, anchoring the field's affordance. */
+.hk-file-picker-badge {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  border-radius: var(--radius-xs);
+  background: color-mix(in srgb, var(--hi-color-primary) 14%, transparent);
+  color: var(--hi-color-primary);
+  pointer-events: none;
+}
+
+.hk-file-picker-input {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 0;
+  background: transparent;
+  border: 0;
+  outline: none;
+  color: rgb(var(--color-text));
+  font-size: var(--text-sm);
+  font-family: inherit;
+
+  &::placeholder {
+    color: rgb(var(--color-text) / 55%);
+  }
+
+  /* Paths are code — mono by default, opt out with :mono="false". */
+  .hk-file-picker-box[data-mono] & {
+    font-family: var(--font-mono, ui-monospace, monospace);
+  }
+
+  &:disabled {
+    cursor: default;
+  }
+}
+
+.hk-file-picker-browse {
+  flex-shrink: 0;
+}
+
+.hk-file-picker-hint {
+  margin: var(--space-4) 0 0;
+  font-size: var(--text-xs);
+  color: rgb(var(--color-text) / 60%);
+
+  &[data-error] {
+    color: var(--hi-color-danger);
+  }
+}

package/src/components/HkFilePickerField.test.tsx

@@ -0,0 +1,194 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkFilePickerField from "./HkFilePickerField";
+
+vi.mock("./HkFileBrowserDialog", () => {
+  return {
+    default: defineComponent({
+      name: "HkFileBrowserDialogStub",
+      props: {
+        modelValue: { type: Boolean, default: false },
+        pickDirectory: { type: Boolean, default: false },
+      },
+      emits: ["update:modelValue", "confirm"],
+      setup(props, { emit }) {
+        return () =>
+          props.modelValue
+            ? h(
+                "div",
+                { class: "picker-dialog-stub" },
+                h("button", {
+                  class: "picker-dialog-stub-confirm",
+                  onClick: () => {
+                    // Directory mode hands back the listed folder itself.
+                    emit(
+                      "confirm",
+                      props.pickDirectory
+                        ? [{ name: "data", path: "/srv/data" }]
+                        : [{ name: "a.csv", path: "/srv/data/a.csv" }],
+                    );
+                    emit("update:modelValue", false);
+                  },
+                }),
+              )
+            : null;
+      },
+    }),
+  };
+});
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+});
+
+interface FieldHandle {
+  input: HTMLInputElement;
+  browse: HTMLButtonElement;
+  model: { value: string };
+}
+
+async function mountField(props: Record<string, unknown> = {}): Promise<FieldHandle> {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const model = ref("");
+  // An initial value seeds the ref; the wrapper keeps driving the prop.
+  if (typeof props.modelValue === "string") {
+    model.value = props.modelValue;
+    delete props.modelValue;
+  }
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkFilePickerField, {
+          modelValue: model.value,
+          "onUpdate:modelValue": (v: string) => {
+            model.value = v;
+          },
+          ...props,
+        });
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  await nextTick();
+
+  return {
+    input: container.querySelector<HTMLInputElement>(".hk-file-picker-input")!,
+    browse: container.querySelector<HTMLButtonElement>(".hk-file-picker-browse")!,
+    model,
+  };
+}
+
+describe("HkFilePickerField hook backend", () => {
+  it("adopts the hook-resolved path and leaves dismissals untouched", async () => {
+    const pick = vi.fn(async () => "/opt/shun/target");
+    const field = await mountField({ pick });
+    expect(field.input.placeholder).toContain("folder");
+    await field.browse.click();
+    await nextTick();
+    expect(pick).toHaveBeenCalledTimes(1);
+    expect(field.model.value).toBe("/opt/shun/target");
+    expect(field.input.value).toBe("/opt/shun/target");
+
+    // A dismissed picker (null) keeps the current value.
+    const dismissed = vi.fn(async () => null);
+    const field2 = await mountField({ pick: dismissed, modelValue: "/keep" });
+    await field2.browse.click();
+    await nextTick();
+    expect(field2.model.value).toBe("/keep");
+  });
+
+  it("disables the browse button when the hook backend has no hook", async () => {
+    const field = await mountField({ backend: "hook" });
+    expect(field.browse.disabled).toBe(true);
+  });
+
+  it("does not offer browsing at all when disabled", async () => {
+    const pick = vi.fn(async () => "/x");
+    const field = await mountField({ pick, disabled: true });
+    expect(field.browse.disabled).toBe(true);
+    field.browse.click();
+    expect(pick).not.toHaveBeenCalled();
+  });
+});
+
+describe("HkFilePickerField remote backend", () => {
+  it("auto-selects remote from the adapter and adopts the confirmed folder", async () => {
+    const adapter = { list: vi.fn(async (path: string) => ({ path, entries: [] })) };
+    const field = await mountField({ adapter });
+    // The dialog renders inside the field's mount, not the stub's body.
+    await field.browse.click();
+    await nextTick();
+    const confirm = field.browse
+      .closest(".hk-file-picker-field")!
+      .querySelector<HTMLButtonElement>(".picker-dialog-stub-confirm")!;
+    expect(confirm).toBeTruthy();
+    await confirm.click();
+    await nextTick();
+    expect(field.model.value).toBe("/srv/data");
+    expect(
+      field.browse
+        .closest(".hk-file-picker-field")!
+        .querySelector(".picker-dialog-stub"),
+    ).toBeNull();
+  });
+});
+
+describe("HkFilePickerField native backend", () => {
+  it("resolves the leaf name through the FS Access directory picker", async () => {
+    const showDirectoryPicker = vi.fn(async () => ({ name: "chosen-dir" }));
+    Object.defineProperty(window, "showDirectoryPicker", {
+      configurable: true,
+      value: showDirectoryPicker,
+    });
+    const field = await mountField({ backend: "native" });
+    await field.browse.click();
+    await nextTick();
+    expect(field.model.value).toBe("chosen-dir");
+    Object.defineProperty(window, "showDirectoryPicker", {
+      configurable: true,
+      value: undefined,
+    });
+  });
+
+  it("swallows a cancelled native picker without touching the value", async () => {
+    const showDirectoryPicker = vi.fn(async () => {
+      throw new DOMException("cancel", "AbortError");
+    });
+    Object.defineProperty(window, "showDirectoryPicker", {
+      configurable: true,
+      value: showDirectoryPicker,
+    });
+    const field = await mountField({ backend: "native", modelValue: "/keep" });
+    await field.browse.click();
+    await nextTick();
+    expect(field.model.value).toBe("/keep");
+    Object.defineProperty(window, "showDirectoryPicker", {
+      configurable: true,
+      value: undefined,
+    });
+  });
+});
+
+describe("HkFilePickerField typing", () => {
+  it("emits update:modelValue on input", async () => {
+    const field = await mountField();
+    field.input.value = "D:\\Games\\Demo";
+    field.input.dispatchEvent(new Event("input"));
+    await nextTick();
+    expect(field.model.value).toBe("D:\\Games\\Demo");
+  });
+
+  it("shows the file placeholder when directory is off", async () => {
+    const field = await mountField({ directory: false });
+    expect(field.input.placeholder).toContain("file");
+  });
+});

package/src/components/HkFilePickerField.tsx

@@ -0,0 +1,212 @@
+import { computed, defineComponent, ref, useId, type PropType } from "vue";
+
+import { useI18n } from "../i18n/context";
+import HButton from "./HkButton";
+import HkFileBrowserDialog from "./HkFileBrowserDialog";
+import type {
+  FilePickerBackend,
+  FilePickerHook,
+  FileQuickLink,
+  RemoteFsAdapter,
+} from "./filePicker";
+import "./HkFilePickerField.scss";
+
+/**
+ * HkFilePickerField — the path-valued sibling of HkFileField. Where the
+ * file field hands back file CONTENT (File objects / remote entries),
+ * this one holds a PATH STRING the user can also type by hand: a
+ * folder badge, an editable input, and a browse button pinned right.
+ *
+ * Three picker backends, all addressable through `backend`:
+ *  - `hook`: the host opens its own picker (`pick`) and resolves the
+ *    chosen path. The canonical case is a Tauri2/Electron host whose
+ *    native dialog is a real OS window OUTSIDE the webview — neither
+ *    of the other backends can stand in for it.
+ *  - `remote`: HkFileBrowserDialog driven by the provided `adapter`
+ *    (in `directory` mode it picks the folder being listed).
+ *  - `native`: the browser's own FS Access picker
+ *    (`showDirectoryPicker` / `showOpenFilePicker`) where the platform
+ *    supplies one. Opaque handles only ever expose their leaf name —
+ *    fine for relative targets, useless for absolute ones; installers
+ *    and friends should reach for the hook instead.
+ *
+ * `auto` (default) resolves hook → remote → native from whichever
+ * props are present, degrading to a purely typed field when none are.
+ */
+export default defineComponent({
+  name: "HkFilePickerField",
+  props: {
+    modelValue: { type: String, default: "" },
+    backend: {
+      type: String as () => FilePickerBackend,
+      default: "auto",
+    },
+    /** Pick a directory (default) or a file. */
+    directory: { type: Boolean, default: true },
+    /** The `hook` backend: open a host picker, resolve the path or null. */
+    pick: { type: Function as PropType<FilePickerHook>, default: undefined },
+    // ── remote backend ──
+    adapter: { type: Object as () => RemoteFsAdapter, default: undefined },
+    quickLinks: { type: Array as () => FileQuickLink[], default: () => [] },
+    initialPath: { type: String, default: "/" },
+    dialogTitle: { type: String, default: undefined },
+    // ── field chrome ──
+    label: { type: String, default: undefined },
+    placeholder: { type: String, default: undefined },
+    hint: { type: String, default: undefined },
+    error: { type: String, default: undefined },
+    disabled: { type: Boolean, default: false },
+    /** Render the path in the mono face (the default — paths are code). */
+    mono: { type: Boolean, default: true },
+    /** Explicit input id (label `for` binding). */
+    id: { type: String, default: undefined },
+  },
+  emits: {
+    "update:modelValue": (_value: string) => true,
+  },
+  setup(props, { emit }) {
+    const { t } = useI18n();
+    const generatedId = useId();
+    const inputId = computed(() => props.id ?? `${generatedId}-input`);
+
+    const resolvedBackend = computed<"hook" | "remote" | "native">(() => {
+      if (props.backend !== "auto") return props.backend;
+      if (props.pick) return "hook";
+      if (props.adapter) return "remote";
+      return "native";
+    });
+
+    const placeholderText = computed(
+      () =>
+        props.placeholder ??
+        (props.directory
+          ? t("hikari::filePicker.fieldPickDirectory", "Choose a folder…")
+          : t("hikari::filePicker.fieldPickFile", "Choose a file…")),
+    );
+
+    // Only the remote backend mounts the dialog; every other picker
+    // opens outside the component (or nowhere, when typed by hand).
+    const dialogOpen = ref(false);
+
+    /** A backend with its required prop missing cannot open anything. */
+    const canBrowse = computed(() => {
+      const backend = resolvedBackend.value;
+      if (backend === "hook") return typeof props.pick === "function";
+      if (backend === "remote") return Boolean(props.adapter);
+      return true;
+    });
+
+    async function browse() {
+      if (props.disabled) return;
+      const backend = resolvedBackend.value;
+      if (backend === "hook" && props.pick) {
+        const picked = await props.pick();
+        if (picked) emit("update:modelValue", picked);
+        return;
+      }
+      if (backend === "remote" && props.adapter) {
+        dialogOpen.value = true;
+        return;
+      }
+      if (backend === "native") {
+        // FS Access pickers resolve to opaque handles; only the leaf
+        // name is readable. Hosts needing absolute paths use the hook.
+        const w = window as unknown as {
+          showDirectoryPicker?: () => Promise<{ name: string } | undefined>;
+          showOpenFilePicker?: () => Promise<{ name: string }[] | undefined>;
+        };
+        try {
+          if (props.directory && w.showDirectoryPicker) {
+            const handle = await w.showDirectoryPicker();
+            if (handle) emit("update:modelValue", handle.name);
+          } else if (!props.directory && w.showOpenFilePicker) {
+            const [handle] = (await w.showOpenFilePicker()) ?? [];
+            if (handle) emit("update:modelValue", handle.name);
+          }
+        } catch {
+          // A dismissed native picker is not an error worth surfacing.
+        }
+      }
+    }
+
+    function onInput(event: Event) {
+      emit("update:modelValue", (event.target as HTMLInputElement).value);
+    }
+
+    function onDialogConfirm(files: { name: string; path: string }[]) {
+      const chosen = files[0];
+      if (chosen) emit("update:modelValue", chosen.path);
+      dialogOpen.value = false;
+    }
+
+    return () => (
+      <div class="hk-file-picker-field">
+        {props.label && (
+          <label class="hk-file-picker-label" for={inputId.value}>
+            {props.label}
+          </label>
+        )}
+        <div
+          class="hk-file-picker-box"
+          data-disabled={props.disabled || undefined}
+          data-error={props.error || undefined}
+          data-mono={props.mono || undefined}
+        >
+          <span class="hk-file-picker-badge" aria-hidden="true">
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              width="18"
+              height="18"
+            >
+              {/* folder-open: the shittim-chest file-picker affordance */}
+              <path d="m6 14 1.45-2.9A2 2 0 0 1 9.24 10H20a2 2 0 0 1 1.94 2.5l-1.55 6a2 2 0 0 1-1.94 1.5H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h3.93a2 2 0 0 1 1.66.9l.82 1.2a2 2 0 0 0 1.66.9H18a2 2 0 0 1 2 2v2" />
+            </svg>
+          </span>
+          <input
+            id={inputId.value}
+            class="hk-file-picker-input"
+            type="text"
+            value={props.modelValue}
+            placeholder={placeholderText.value}
+            spellcheck={false}
+            disabled={props.disabled}
+            onInput={onInput}
+          />
+          <HButton
+            variant="ghost"
+            size="sm"
+            class="hk-file-picker-browse"
+            disabled={props.disabled || !canBrowse.value}
+            onClick={browse}
+          >
+            {t("hikari::filePicker.browse", "Browse…")}
+          </HButton>
+        </div>
+        {props.error ? (
+          <p class="hk-file-picker-hint" data-error>{props.error}</p>
+        ) : props.hint ? (
+          <p class="hk-file-picker-hint">{props.hint}</p>
+        ) : null}
+        {resolvedBackend.value === "remote" && props.adapter && (
+          <HkFileBrowserDialog
+            modelValue={dialogOpen.value}
+            onUpdate:modelValue={(v: boolean) => {
+              dialogOpen.value = v;
+            }}
+            adapter={props.adapter}
+            pickDirectory={props.directory}
+            initialPath={props.initialPath}
+            quickLinks={props.quickLinks}
+            title={props.dialogTitle}
+            onConfirm={onDialogConfirm}
+          />
+        )}
+      </div>
+    );
+  },
+});

package/src/components/HkRadio.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, type PropType } from "vue";
+import { defineComponent, type PropType } from "vue";
 import HkLabel from "./HkLabel";
 import "./HkRadio.scss";
 

package/src/components/HkSwitch.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, type PropType } from "vue";
+import { defineComponent, type PropType } from "vue";
 import HkLabel from "./HkLabel";
 import "./HkSwitch.scss";
 

package/src/components/filePicker.ts

@@ -66,3 +66,19 @@ export function acceptExtensions(accept?: string): string[] {
     .map((part) => part.trim().toLowerCase())
     .filter((part) => part.startsWith("."));
 }
+
+/**
+ * Backend selector for HkFilePickerField — the path-valued picker. All
+ * three are addressable so embedders can force one; "auto" resolves
+ * hook → remote → native from whichever props are present.
+ */
+export type FilePickerBackend = "auto" | "hook" | "remote" | "native";
+
+/**
+ * The app hook backend: the host opens its own picker and resolves the
+ * chosen path (or null for a dismissal). The canonical case is a
+ * Tauri2/Electron-style host whose native dialog is a real OS window
+ * OUTSIDE the webview — neither the browser picker nor an in-app
+ * dialog can stand in for it.
+ */
+export type FilePickerHook = () => Promise<string | null>;

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "نسخ الخطأ",
     "hikari::errorBoundary.retry": "إعادة المحاولة",
     "hikari::errorBoundary.title": "خطأ في المكوّن",
+    "hikari::filePicker.browse": "استعراض…",
     "hikari::filePicker.cancel": "إلغاء",
+    "hikari::filePicker.chooseFolder": "اختيار هذا المجلد",
     "hikari::filePicker.confirm": "اختيار",
     "hikari::filePicker.copy": "نسخ",
     "hikari::filePicker.copyPath": "نسخ المسار",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "اختر ملفات بعيدة…",
     "hikari::filePicker.fieldChooseRemoteOne": "اختر ملفًا بعيدًا…",
     "hikari::filePicker.fieldClear": "مسح التحديد",
+    "hikari::filePicker.fieldPickDirectory": "اختيار مجلد…",
+    "hikari::filePicker.fieldPickFile": "اختيار ملف…",
     "hikari::filePicker.filterAll": "كل الملفات",
     "hikari::filePicker.gridLayout": "عرض الشبكة",
     "hikari::filePicker.listError": "تعذر عرض هذا المجلد",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "إعادة المحاولة",
     "hikari::filePicker.size": "الحجم",
     "hikari::filePicker.title": "اختر الملفات",
+    "hikari::filePicker.titleFolder": "استعراض المجلدات",
     "hikari::imageLightbox.close": "إغلاق",
     "hikari::imageLightbox.title": "عارض الصور",
     "hikari::imagePreview.enlarge": "تكبير الصورة",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "Fehler kopieren",
     "hikari::errorBoundary.retry": "Erneut versuchen",
     "hikari::errorBoundary.title": "Komponentenfehler",
+    "hikari::filePicker.browse": "Durchsuchen…",
     "hikari::filePicker.cancel": "Abbrechen",
+    "hikari::filePicker.chooseFolder": "Diesen Ordner wählen",
     "hikari::filePicker.confirm": "Auswählen",
     "hikari::filePicker.copy": "Kopieren",
     "hikari::filePicker.copyPath": "Pfad kopieren",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "Remote-Dateien auswählen…",
     "hikari::filePicker.fieldChooseRemoteOne": "Remote-Datei auswählen…",
     "hikari::filePicker.fieldClear": "Auswahl löschen",
+    "hikari::filePicker.fieldPickDirectory": "Ordner auswählen…",
+    "hikari::filePicker.fieldPickFile": "Datei auswählen…",
     "hikari::filePicker.filterAll": "Alle Dateien",
     "hikari::filePicker.gridLayout": "Rasteransicht",
     "hikari::filePicker.listError": "Ordner konnte nicht gelesen werden",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "Wiederholen",
     "hikari::filePicker.size": "Größe",
     "hikari::filePicker.title": "Dateien wählen",
+    "hikari::filePicker.titleFolder": "Ordner durchsuchen",
     "hikari::imageLightbox.close": "Schließen",
     "hikari::imageLightbox.title": "Bildbetrachter",
     "hikari::imagePreview.enlarge": "Vergrößern",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "Copy Error",
     "hikari::errorBoundary.retry": "Retry",
     "hikari::errorBoundary.title": "Component Error",
+    "hikari::filePicker.browse": "Browse…",
     "hikari::filePicker.cancel": "Cancel",
+    "hikari::filePicker.chooseFolder": "Choose this folder",
     "hikari::filePicker.confirm": "Choose",
     "hikari::filePicker.copy": "Copy",
     "hikari::filePicker.copyPath": "Copy path",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "Choose remote files…",
     "hikari::filePicker.fieldChooseRemoteOne": "Choose a remote file…",
     "hikari::filePicker.fieldClear": "Clear selection",
+    "hikari::filePicker.fieldPickDirectory": "Choose a folder…",
+    "hikari::filePicker.fieldPickFile": "Choose a file…",
     "hikari::filePicker.filterAll": "All files",
     "hikari::filePicker.gridLayout": "Grid view",
     "hikari::filePicker.listError": "Couldn't list this folder",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "Retry",
     "hikari::filePicker.size": "Size",
     "hikari::filePicker.title": "Choose files",
+    "hikari::filePicker.titleFolder": "Browse folders",
     "hikari::imageLightbox.close": "Close",
     "hikari::imageLightbox.title": "Image viewer",
     "hikari::imagePreview.enlarge": "View larger",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "Copiar error",
     "hikari::errorBoundary.retry": "Reintentar",
     "hikari::errorBoundary.title": "Error del componente",
+    "hikari::filePicker.browse": "Examinar…",
     "hikari::filePicker.cancel": "Cancelar",
+    "hikari::filePicker.chooseFolder": "Elegir esta carpeta",
     "hikari::filePicker.confirm": "Elegir",
     "hikari::filePicker.copy": "Copiar",
     "hikari::filePicker.copyPath": "Copiar ruta",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "Elegir archivos remotos…",
     "hikari::filePicker.fieldChooseRemoteOne": "Elegir un archivo remoto…",
     "hikari::filePicker.fieldClear": "Borrar selección",
+    "hikari::filePicker.fieldPickDirectory": "Elegir una carpeta…",
+    "hikari::filePicker.fieldPickFile": "Elegir un archivo…",
     "hikari::filePicker.filterAll": "Todos los archivos",
     "hikari::filePicker.gridLayout": "Vista de cuadrícula",
     "hikari::filePicker.listError": "No se pudo listar esta carpeta",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "Reintentar",
     "hikari::filePicker.size": "Tamaño",
     "hikari::filePicker.title": "Elegir archivos",
+    "hikari::filePicker.titleFolder": "Examinar carpetas",
     "hikari::imageLightbox.close": "Cerrar",
     "hikari::imageLightbox.title": "Visor de imágenes",
     "hikari::imagePreview.enlarge": "Ampliar",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "Copier l'erreur",
     "hikari::errorBoundary.retry": "Réessayer",
     "hikari::errorBoundary.title": "Erreur du composant",
+    "hikari::filePicker.browse": "Parcourir…",
     "hikari::filePicker.cancel": "Annuler",
+    "hikari::filePicker.chooseFolder": "Choisir ce dossier",
     "hikari::filePicker.confirm": "Choisir",
     "hikari::filePicker.copy": "Copier",
     "hikari::filePicker.copyPath": "Copier le chemin",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "Choisir des fichiers distants…",
     "hikari::filePicker.fieldChooseRemoteOne": "Choisir un fichier distant…",
     "hikari::filePicker.fieldClear": "Effacer la sélection",
+    "hikari::filePicker.fieldPickDirectory": "Choisir un dossier…",
+    "hikari::filePicker.fieldPickFile": "Choisir un fichier…",
     "hikari::filePicker.filterAll": "Tous les fichiers",
     "hikari::filePicker.gridLayout": "Vue grille",
     "hikari::filePicker.listError": "Impossible de lister ce dossier",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "Réessayer",
     "hikari::filePicker.size": "Taille",
     "hikari::filePicker.title": "Choisir des fichiers",
+    "hikari::filePicker.titleFolder": "Parcourir les dossiers",
     "hikari::imageLightbox.close": "Fermer",
     "hikari::imageLightbox.title": "Visionneuse d'images",
     "hikari::imagePreview.enlarge": "Agrandir",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "エラーをコピー",
     "hikari::errorBoundary.retry": "再試行",
     "hikari::errorBoundary.title": "コンポーネントエラー",
+    "hikari::filePicker.browse": "参照…",
     "hikari::filePicker.cancel": "キャンセル",
+    "hikari::filePicker.chooseFolder": "このフォルダーを選択",
     "hikari::filePicker.confirm": "選択",
     "hikari::filePicker.copy": "コピー",
     "hikari::filePicker.copyPath": "パスをコピー",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "複数のリモートファイルを選択…",
     "hikari::filePicker.fieldChooseRemoteOne": "リモートファイルを選択…",
     "hikari::filePicker.fieldClear": "選択を解除",
+    "hikari::filePicker.fieldPickDirectory": "フォルダーを選択…",
+    "hikari::filePicker.fieldPickFile": "ファイルを選択…",
     "hikari::filePicker.filterAll": "すべてのファイル",
     "hikari::filePicker.gridLayout": "グリッド表示",
     "hikari::filePicker.listError": "このフォルダーを一覧できません",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "再試行",
     "hikari::filePicker.size": "サイズ",
     "hikari::filePicker.title": "ファイルを選択",
+    "hikari::filePicker.titleFolder": "フォルダーを参照",
     "hikari::imageLightbox.close": "閉じる",
     "hikari::imageLightbox.title": "画像ビューア",
     "hikari::imagePreview.enlarge": "クリックで拡大",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "오류 복사",
     "hikari::errorBoundary.retry": "재시도",
     "hikari::errorBoundary.title": "컴포넌트 오류",
+    "hikari::filePicker.browse": "찾아보기…",
     "hikari::filePicker.cancel": "취소",
+    "hikari::filePicker.chooseFolder": "이 폴더 선택",
     "hikari::filePicker.confirm": "선택",
     "hikari::filePicker.copy": "복사",
     "hikari::filePicker.copyPath": "경로 복사",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "여러 원격 파일 선택…",
     "hikari::filePicker.fieldChooseRemoteOne": "원격 파일 선택…",
     "hikari::filePicker.fieldClear": "선택 지우기",
+    "hikari::filePicker.fieldPickDirectory": "폴더 선택…",
+    "hikari::filePicker.fieldPickFile": "파일 선택…",
     "hikari::filePicker.filterAll": "모든 파일",
     "hikari::filePicker.gridLayout": "그리드 보기",
     "hikari::filePicker.listError": "이 폴더를 나열할 수 없습니다",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "다시 시도",
     "hikari::filePicker.size": "크기",
     "hikari::filePicker.title": "파일 선택",
+    "hikari::filePicker.titleFolder": "폴더 찾아보기",
     "hikari::imageLightbox.close": "닫기",
     "hikari::imageLightbox.title": "이미지 뷰어",
     "hikari::imagePreview.enlarge": "클릭하여 확대",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "Copiar erro",
     "hikari::errorBoundary.retry": "Tentar novamente",
     "hikari::errorBoundary.title": "Erro no componente",
+    "hikari::filePicker.browse": "Procurar…",
     "hikari::filePicker.cancel": "Cancelar",
+    "hikari::filePicker.chooseFolder": "Escolher esta pasta",
     "hikari::filePicker.confirm": "Escolher",
     "hikari::filePicker.copy": "Copiar",
     "hikari::filePicker.copyPath": "Copiar caminho",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "Escolher arquivos remotos…",
     "hikari::filePicker.fieldChooseRemoteOne": "Escolher um arquivo remoto…",
     "hikari::filePicker.fieldClear": "Limpar seleção",
+    "hikari::filePicker.fieldPickDirectory": "Escolher uma pasta…",
+    "hikari::filePicker.fieldPickFile": "Escolher um ficheiro…",
     "hikari::filePicker.filterAll": "Todos os arquivos",
     "hikari::filePicker.gridLayout": "Visualização em grade",
     "hikari::filePicker.listError": "Não foi possível listar esta pasta",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "Tentar novamente",
     "hikari::filePicker.size": "Tamanho",
     "hikari::filePicker.title": "Escolher arquivos",
+    "hikari::filePicker.titleFolder": "Procurar pastas",
     "hikari::imageLightbox.close": "Fechar",
     "hikari::imageLightbox.title": "Visualizador de imagens",
     "hikari::imagePreview.enlarge": "Ampliar",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "Копировать ошибку",
     "hikari::errorBoundary.retry": "Повторить",
     "hikari::errorBoundary.title": "Ошибка компонента",
+    "hikari::filePicker.browse": "Обзор…",
     "hikari::filePicker.cancel": "Отмена",
+    "hikari::filePicker.chooseFolder": "Выбрать эту папку",
     "hikari::filePicker.confirm": "Выбрать",
     "hikari::filePicker.copy": "Копировать",
     "hikari::filePicker.copyPath": "Копировать путь",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "Выбрать удалённые файлы…",
     "hikari::filePicker.fieldChooseRemoteOne": "Выбрать удалённый файл…",
     "hikari::filePicker.fieldClear": "Очистить выбор",
+    "hikari::filePicker.fieldPickDirectory": "Выбрать папку…",
+    "hikari::filePicker.fieldPickFile": "Выбрать файл…",
     "hikari::filePicker.filterAll": "Все файлы",
     "hikari::filePicker.gridLayout": "Сетка",
     "hikari::filePicker.listError": "Не удалось получить содержимое папки",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "Повторить",
     "hikari::filePicker.size": "Размер",
     "hikari::filePicker.title": "Выбор файлов",
+    "hikari::filePicker.titleFolder": "Обзор папок",
     "hikari::imageLightbox.close": "Закрыть",
     "hikari::imageLightbox.title": "Просмотр изображения",
     "hikari::imagePreview.enlarge": "Увеличить",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "复制错误",
     "hikari::errorBoundary.retry": "重试",
     "hikari::errorBoundary.title": "组件错误",
+    "hikari::filePicker.browse": "浏览…",
     "hikari::filePicker.cancel": "取消",
+    "hikari::filePicker.chooseFolder": "选择此文件夹",
     "hikari::filePicker.confirm": "选择",
     "hikari::filePicker.copy": "复制",
     "hikari::filePicker.copyPath": "复制路径",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "选择多个远程文件…",
     "hikari::filePicker.fieldChooseRemoteOne": "选择远程文件…",
     "hikari::filePicker.fieldClear": "清除所选",
+    "hikari::filePicker.fieldPickDirectory": "选择文件夹…",
+    "hikari::filePicker.fieldPickFile": "选择文件…",
     "hikari::filePicker.filterAll": "所有文件",
     "hikari::filePicker.gridLayout": "网格视图",
     "hikari::filePicker.listError": "无法列出此文件夹",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "重试",
     "hikari::filePicker.size": "大小",
     "hikari::filePicker.title": "选择文件",
+    "hikari::filePicker.titleFolder": "浏览文件夹",
     "hikari::imageLightbox.close": "关闭",
     "hikari::imageLightbox.title": "图片查看器",
     "hikari::imagePreview.enlarge": "点击放大",

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

@@ -45,7 +45,9 @@
     "hikari::errorBoundary.copyError": "複製錯誤",
     "hikari::errorBoundary.retry": "重試",
     "hikari::errorBoundary.title": "元件錯誤",
+    "hikari::filePicker.browse": "瀏覽…",
     "hikari::filePicker.cancel": "取消",
+    "hikari::filePicker.chooseFolder": "選擇此資料夾",
     "hikari::filePicker.confirm": "選擇",
     "hikari::filePicker.copy": "複製",
     "hikari::filePicker.copyPath": "複製路徑",
@@ -56,6 +58,8 @@
     "hikari::filePicker.fieldChooseRemoteMany": "選擇多個遠端檔案…",
     "hikari::filePicker.fieldChooseRemoteOne": "選擇遠端檔案…",
     "hikari::filePicker.fieldClear": "清除所選",
+    "hikari::filePicker.fieldPickDirectory": "選擇資料夾…",
+    "hikari::filePicker.fieldPickFile": "選擇檔案…",
     "hikari::filePicker.filterAll": "所有檔案",
     "hikari::filePicker.gridLayout": "網格檢視",
     "hikari::filePicker.listError": "無法列出此資料夾",
@@ -75,6 +79,7 @@
     "hikari::filePicker.retry": "重試",
     "hikari::filePicker.size": "大小",
     "hikari::filePicker.title": "選擇檔案",
+    "hikari::filePicker.titleFolder": "瀏覽資料夾",
     "hikari::imageLightbox.close": "關閉",
     "hikari::imageLightbox.title": "圖片檢視器",
     "hikari::imagePreview.enlarge": "點擊放大",

package/src/index.ts

@@ -74,12 +74,15 @@ export { default as HTag } from "./components/HkTag";
 export { default as HTextarea } from "./components/HkTextarea";
 export { default as HFileField } from "./components/HkFileField";
 export { default as HFileBrowserDialog } from "./components/HkFileBrowserDialog";
+export { default as HFilePickerField } from "./components/HkFilePickerField";
 export {
   type RemoteFileEntry,
   type RemoteDirListing,
   type RemoteFsAdapter,
   type FileQuickLink,
   type PickedFile,
+  type FilePickerBackend,
+  type FilePickerHook,
   acceptExtensions,
 } from "./components/filePicker";
 export { default as HToast } from "./components/HkToast";