@kahitsan/ksui 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "ksui is a standalone set of SolidJS UI components for KahitSan/Hilinga and any SolidJS app. Published to the public npm registry and consumed as a normal dependency. Ships source under a `solid` export condition so the consumer's vite-plugin-solid compiles it with only solid-js externalized; it depends on nothing but solid-js + lucide-solid and injects its own CSS.",
   "type": "module",
   "main": "./src/index.ts",

package/src/components/base/BadgeSelect.test.tsx

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, fireEvent, screen } from "@solidjs/testing-library";
+import BadgeSelect, { type BadgeSelectOption } from "./BadgeSelect";
+
+// BadgeSelect is the generic, domain-free inline picker lifted from kserp's
+// RoleBadgeSelect (U1). The caller injects options, the value↔label mapping,
+// and (optionally) the badge tone; nothing here is role-specific. The popup
+// renders into a Portal (document.body), so popup assertions use `screen`.
+
+const OPTIONS: BadgeSelectOption[] = [
+  { value: "admin", label: "Admin", description: "Full access" },
+  { value: "member", label: "Member" },
+];
+
+describe("BadgeSelect", () => {
+  it("renders the selected option's label on the trigger", () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} onChange={() => {}} />
+    ));
+    expect(getByRole("button").textContent).toContain("Admin");
+  });
+
+  it("falls back to the raw value when no option matches", () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect value="ghost" options={OPTIONS} onChange={() => {}} />
+    ));
+    expect(getByRole("button").textContent).toContain("ghost");
+  });
+
+  it("opens the popup and emits the chosen value on select", async () => {
+    const onChange = vi.fn();
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} onChange={onChange} />
+    ));
+    fireEvent.click(getByRole("button"));
+    const memberOpt = await screen.findByText("Member");
+    fireEvent.click(memberOpt);
+    expect(onChange).toHaveBeenCalledWith("member");
+  });
+
+  it("does not emit when re-selecting the current value", async () => {
+    const onChange = vi.fn();
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} onChange={onChange} />
+    ));
+    fireEvent.click(getByRole("button"));
+    // Wait for the popup, then click the option row for the active value.
+    await screen.findByText("Member");
+    const adminRows = screen.getAllByText("Admin");
+    fireEvent.click(adminRows[adminRows.length - 1]);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("applies the injected badgeClass to the trigger (DI tone)", () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect
+        value="admin"
+        options={OPTIONS}
+        onChange={() => {}}
+        badgeClass={(v) => (v === "admin" ? "tone-special" : "tone-default")}
+      />
+    ));
+    expect(getByRole("button").className).toContain("tone-special");
+  });
+
+  it("disables the trigger when disabled", () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} disabled onChange={() => {}} />
+    ));
+    expect((getByRole("button") as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it("exposes listbox/option ARIA semantics when open", async () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} onChange={() => {}} />
+    ));
+    const trigger = getByRole("button");
+    expect(trigger.getAttribute("aria-haspopup")).toBe("listbox");
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+    fireEvent.click(trigger);
+    const listbox = await screen.findByRole("listbox");
+    expect(listbox).toBeTruthy();
+    expect(trigger.getAttribute("aria-expanded")).toBe("true");
+    // The active option advertises its selected state to assistive tech.
+    const selected = screen.getAllByRole("option").find((o) => o.getAttribute("aria-selected") === "true");
+    expect(selected?.textContent).toContain("Admin");
+  });
+});

package/src/components/base/BadgeSelect.tsx

@@ -0,0 +1,229 @@
+import { createEffect, createMemo, createSignal, For, onCleanup, Show, type JSX } from "solid-js";
+import { Portal } from "solid-js/web";
+
+export interface BadgeSelectOption {
+  /** Stable identity of the option (what `value` matches and `onChange` emits). */
+  value: string;
+  label: string;
+  description?: string;
+}
+
+export interface BadgeSelectProps {
+  /** Currently-selected option value. */
+  value: string;
+  options: BadgeSelectOption[];
+  disabled?: boolean;
+  loading?: boolean;
+  /** Map the selected value to the trigger badge's classes (DI). Defaults to a
+   *  neutral zinc chip — the caller injects its own tone mapping. */
+  badgeClass?: (value: string) => string;
+  onChange: (next: string) => void | Promise<void>;
+  /** Show the inline search box when options exceed this count. Default 5. */
+  searchThreshold?: number;
+  searchPlaceholder?: string;
+  /** Tooltip on the trigger when enabled. Default "Click to change". */
+  title?: string;
+  /** Empty-state copy when there are no options at all. Default "No options". */
+  emptyLabel?: string;
+  /** Empty-state copy when a search filters everything out. Default "No matching options". */
+  emptyFilteredLabel?: string;
+  /** Copy shown while `loading`. Default "Loading…". */
+  loadingLabel?: string;
+  testId?: string;
+}
+
+const POPUP_MIN_WIDTH = 200;
+const POPUP_MAX_HEIGHT = 320;
+const DEFAULT_SEARCH_THRESHOLD = 5;
+
+// Inline, click-to-edit badge picker. Renders as a clickable badge; clicking
+// opens a dropdown anchored to the badge with all options. When more than
+// `searchThreshold` options are present an inline search box auto-appears so a
+// long list stays scannable. Selecting commits immediately via onChange.
+//
+// The popup is rendered into a Portal with `position: fixed`, so it escapes
+// ancestors that have `overflow: hidden` (e.g. rounded card containers) and
+// flips above the trigger when there isn't enough room below it.
+//
+// Domain-free: the caller supplies the options, the value↔label mapping, and
+// (optionally) the badge tone via `badgeClass`. Nothing here knows what the
+// values mean.
+//
+// Intentionally distinct from SearchableSelect: this is a badge-scoped single
+// select — a compact inline chip trigger plus per-value tone DI (`badgeClass`),
+// not a form-control picker. Kept separate so neither component grows a
+// trigger-shape/styling switch; do not merge them.
+export default function BadgeSelect(props: BadgeSelectProps): JSX.Element {
+  const [open, setOpen] = createSignal(false);
+  const [busy, setBusy] = createSignal(false);
+  const [query, setQuery] = createSignal("");
+  const [popupStyle, setPopupStyle] = createSignal<JSX.CSSProperties>({});
+  let triggerRef: HTMLButtonElement | undefined;
+  let popupRef: HTMLDivElement | undefined;
+  let searchRef: HTMLInputElement | undefined;
+
+  const threshold = () => props.searchThreshold ?? DEFAULT_SEARCH_THRESHOLD;
+  const showSearch = () => (props.options?.length ?? 0) > threshold();
+
+  const filtered = createMemo(() => {
+    const q = query().trim().toLowerCase();
+    if (!q) return props.options;
+    return props.options.filter(
+      (o) =>
+        o.label.toLowerCase().includes(q) ||
+        o.value.toLowerCase().includes(q) ||
+        (o.description?.toLowerCase().includes(q) ?? false),
+    );
+  });
+
+  const defaultBadge = () => "bg-zinc-800 text-zinc-400 border border-transparent";
+  const badgeClass = () => props.badgeClass?.(props.value) ?? defaultBadge();
+
+  const emptyStateMessage = () => {
+    if (props.loading) return props.loadingLabel ?? "Loading…";
+    return query() ? (props.emptyFilteredLabel ?? "No matching options") : (props.emptyLabel ?? "No options");
+  };
+
+  const updatePosition = () => {
+    if (!triggerRef) return;
+    const rect = triggerRef.getBoundingClientRect();
+    const vpHeight = window.innerHeight;
+    const vpWidth = window.innerWidth;
+    const width = Math.max(POPUP_MIN_WIDTH, rect.width);
+    const spaceBelow = vpHeight - rect.bottom;
+    const spaceAbove = rect.top;
+    const flipUp = spaceBelow < POPUP_MAX_HEIGHT && spaceAbove > spaceBelow;
+    const top = flipUp ? Math.max(8, rect.top - POPUP_MAX_HEIGHT - 4) : rect.bottom + 4;
+    const maxHeight = Math.max(
+      160,
+      Math.min(POPUP_MAX_HEIGHT, flipUp ? spaceAbove - 12 : spaceBelow - 12),
+    );
+    const left = Math.min(Math.max(8, rect.left), vpWidth - width - 8);
+    setPopupStyle({
+      position: "fixed",
+      top: `${top}px`,
+      left: `${left}px`,
+      width: `${width}px`,
+      "max-height": `${maxHeight}px`,
+    });
+  };
+
+  createEffect(() => {
+    if (!open()) return;
+    setQuery("");
+    updatePosition();
+    if (showSearch()) queueMicrotask(() => searchRef?.focus());
+
+    const onDocClick = (e: MouseEvent) => {
+      const target = e.target as Node;
+      if (triggerRef?.contains(target)) return;
+      if (popupRef?.contains(target)) return;
+      setOpen(false);
+    };
+    const onEsc = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    const onReflow = () => updatePosition();
+
+    document.addEventListener("mousedown", onDocClick);
+    document.addEventListener("keydown", onEsc);
+    window.addEventListener("resize", onReflow);
+    window.addEventListener("scroll", onReflow, true);
+    onCleanup(() => {
+      document.removeEventListener("mousedown", onDocClick);
+      document.removeEventListener("keydown", onEsc);
+      window.removeEventListener("resize", onReflow);
+      window.removeEventListener("scroll", onReflow, true);
+    });
+  });
+
+  const handleSelect = async (next: string) => {
+    if (next === props.value) {
+      setOpen(false);
+      return;
+    }
+    setBusy(true);
+    try {
+      await props.onChange(next);
+    } finally {
+      setBusy(false);
+      setOpen(false);
+    }
+  };
+
+  const currentLabel = () =>
+    props.options.find((o) => o.value === props.value)?.label ?? props.value;
+
+  return (
+    <div class="relative inline-block">
+      <button
+        ref={triggerRef}
+        type="button"
+        data-testid={props.testId}
+        aria-haspopup="listbox"
+        aria-expanded={open()}
+        disabled={props.disabled || busy()}
+        onClick={() => !props.disabled && setOpen((o) => !o)}
+        class={`text-xs font-medium px-1.5 py-0.5 rounded cursor-pointer transition-colors hover:ring-1 hover:ring-amber-500/40 ${badgeClass()} ${
+          props.disabled ? "cursor-not-allowed opacity-60" : ""
+        }`}
+        title={props.disabled ? "" : (props.title ?? "Click to change")}
+      >
+        {busy() ? "…" : currentLabel()}
+      </button>
+      <Show when={open()}>
+        <Portal>
+          <div
+            ref={popupRef}
+            role="listbox"
+            class="z-[100] rounded-md border border-zinc-700 bg-zinc-900/95 backdrop-blur shadow-xl overflow-hidden flex flex-col"
+            style={popupStyle()}
+          >
+            <Show when={showSearch()}>
+              <div class="px-2 py-1.5 border-b border-zinc-800">
+                <input
+                  ref={searchRef}
+                  type="text"
+                  value={query()}
+                  onInput={(e) => setQuery(e.currentTarget.value)}
+                  placeholder={props.searchPlaceholder ?? "Search…"}
+                  class="w-full px-2 py-1 text-xs bg-zinc-950 border border-zinc-800 rounded text-zinc-200 placeholder:text-zinc-600 focus:outline-none focus:border-amber-500/50"
+                />
+              </div>
+            </Show>
+            <div class="flex-1 overflow-y-auto">
+              <Show
+                when={!props.loading && filtered().length > 0}
+                fallback={<div class="px-3 py-2 text-xs text-zinc-500">{emptyStateMessage()}</div>}
+              >
+                <For each={filtered()}>
+                  {(opt) => (
+                    <button
+                      type="button"
+                      role="option"
+                      aria-selected={opt.value === props.value}
+                      onClick={() => handleSelect(opt.value)}
+                      class={`w-full text-left px-3 py-2 text-xs hover:bg-amber-500/10 transition-colors flex items-center justify-between gap-2 ${
+                        opt.value === props.value ? "text-amber-400" : "text-zinc-200"
+                      }`}
+                    >
+                      <span class="flex flex-col">
+                        <span class="font-medium">{opt.label}</span>
+                        <Show when={opt.description}>
+                          <span class="text-[10px] text-zinc-500">{opt.description}</span>
+                        </Show>
+                      </span>
+                      <Show when={opt.value === props.value}>
+                        <span class="text-amber-400" aria-hidden="true">✓</span>
+                      </Show>
+                    </button>
+                  )}
+                </For>
+              </Show>
+            </div>
+          </div>
+        </Portal>
+      </Show>
+    </div>
+  );
+}

package/src/components/composite/CustomRenderer.test.tsx

@@ -0,0 +1,86 @@
+// U8 — CustomRenderer component tests: registered renders, unknown id falls back,
+// mismatched props fall back, undeclared emit is dropped.
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { render, fireEvent } from "@solidjs/testing-library";
+import CustomRenderer from "./CustomRenderer";
+import { clearRenderers, registerRenderer, type RendererProps } from "../../utils/renderers";
+
+afterEach(() => {
+  clearRenderers();
+  vi.restoreAllMocks();
+});
+
+function Card(props: RendererProps) {
+  return (
+    <div data-testid="card">
+      <span>{String(props.item.customer)}</span>
+      <button data-testid="emit-pay" onClick={() => props.emit("pay", { amount: 1 })}>
+        pay
+      </button>
+      <button data-testid="emit-bogus" onClick={() => props.emit("bogus")}>
+        bogus
+      </button>
+    </div>
+  );
+}
+
+describe("CustomRenderer", () => {
+  it("renders a registered renderer with valid props", () => {
+    registerRenderer({ id: "card", consumes: { customer: "string" }, emits: ["pay"], render: Card });
+    const { getByTestId } = render(() => <CustomRenderer id="card" item={{ customer: "Acme" }} />);
+    expect(getByTestId("card").textContent).toContain("Acme");
+  });
+
+  it("falls back when the id is unregistered", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { getByTestId, queryByTestId } = render(() => (
+      <CustomRenderer id="missing" item={{ customer: "Acme" }} />
+    ));
+    expect(getByTestId("ksui-cr-fallback")).toBeTruthy();
+    expect(queryByTestId("card")).toBeNull();
+  });
+
+  it("falls back when props don't match the consumes contract", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    registerRenderer({ id: "card", consumes: { customer: "string" }, emits: ["pay"], render: Card });
+    const { getByTestId, queryByTestId } = render(() => (
+      <CustomRenderer id="card" item={{ customer: 123 as unknown as string }} />
+    ));
+    expect(getByTestId("ksui-cr-fallback")).toBeTruthy();
+    expect(queryByTestId("card")).toBeNull();
+  });
+
+  it("forwards a declared emit to onEmit", () => {
+    registerRenderer({ id: "card", consumes: { customer: "string" }, emits: ["pay"], render: Card });
+    const onEmit = vi.fn();
+    const { getByTestId } = render(() => (
+      <CustomRenderer id="card" item={{ customer: "Acme" }} onEmit={onEmit} />
+    ));
+    fireEvent.click(getByTestId("emit-pay"));
+    expect(onEmit).toHaveBeenCalledWith("pay", { amount: 1 });
+  });
+
+  it("drops an undeclared emit (cannot forge an interaction)", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    registerRenderer({ id: "card", consumes: { customer: "string" }, emits: ["pay"], render: Card });
+    const onEmit = vi.fn();
+    const { getByTestId } = render(() => (
+      <CustomRenderer id="card" item={{ customer: "Acme" }} onEmit={onEmit} />
+    ));
+    fireEvent.click(getByTestId("emit-bogus"));
+    expect(onEmit).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it("renders a custom fallback when provided", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { getByTestId } = render(() => (
+      <CustomRenderer
+        id="missing"
+        item={{}}
+        fallback={(p) => <div data-testid="my-fallback">{p.id}</div>}
+      />
+    ));
+    expect(getByTestId("my-fallback").textContent).toBe("missing");
+  });
+});

package/src/components/composite/CustomRenderer.tsx

@@ -0,0 +1,114 @@
+// U8 — CustomRenderer (Vision §8): renders a registered, schema-bound custom
+// renderer by id, with a SAFE fallback when the id is unregistered or the props
+// don't satisfy the renderer's declared `consumes` contract.
+//
+// It is a composite because it reads the in-process renderer registry
+// (utils/renderers) and wires the `emit` guard. The registry holds only
+// build-time, in-process components — no eval, no remote code (see renderers.ts
+// for the supply-chain-trust rationale).
+
+import type { Component } from "solid-js";
+import { Show, createMemo } from "solid-js";
+import { Dynamic } from "solid-js/web";
+import AlertTriangle from "lucide-solid/icons/triangle-alert";
+import {
+  getRenderer,
+  validateConsumes,
+  type RendererProps,
+} from "../../utils/renderers";
+
+const STYLE_ID = "ksui-custom-renderer-style";
+
+function ensureStyle(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  // Unscoped ksui-* classes + CSS custom properties so a host can retint without
+  // forking; no Tailwind, no host-brand classes (standalone-library rule).
+  style.textContent = `
+.ksui-cr-fallback{display:flex;align-items:center;gap:0.5rem;padding:0.625rem 0.75rem;border-radius:0.5rem;font-size:0.8125rem;background:var(--ksui-cr-fallback-bg,rgba(245,158,11,0.08));border:1px solid var(--ksui-cr-fallback-border,rgba(245,158,11,0.25));color:var(--ksui-cr-fallback-fg,#fbbf24);}
+.ksui-cr-fallback svg{flex:0 0 auto;}
+`;
+  document.head.appendChild(style);
+}
+
+export interface CustomRendererProps {
+  /** Registered renderer id to look up (§8). */
+  id: string;
+  /** The data object to render; validated against the renderer's `consumes`. */
+  item: Record<string, unknown>;
+  /**
+   * Fire one of the renderer's declared `emits`. An undeclared emit is dropped
+   * with a console.warn — a renderer cannot forge an interaction it never
+   * declared (§8: it can misbehave on screen but never escalate authority).
+   */
+  onEmit?: (event: string, payload?: unknown) => void;
+  /**
+   * Optional custom fallback when the id is unknown or props don't match. When
+   * omitted a built-in warning chip renders (never throws — §8 graceful degrade).
+   */
+  fallback?: Component<{ id: string; reason: string }>;
+}
+
+const DefaultFallback: Component<{ id: string; reason: string }> = (props) => {
+  ensureStyle();
+  return (
+    <div class="ksui-cr-fallback" role="status" data-testid="ksui-cr-fallback">
+      <AlertTriangle size={14} />
+      <span>Renderer "{props.id}" unavailable</span>
+    </div>
+  );
+};
+
+export const CustomRenderer: Component<CustomRendererProps> = (props) => {
+  // Resolve id → definition + validate props on every change. A miss (unknown id
+  // OR schema mismatch) yields a reason string and the fallback renders.
+  const resolved = createMemo<
+    | { kind: "ok"; render: Component<RendererProps>; emits: readonly string[] }
+    | { kind: "fallback"; reason: string }
+  >(() => {
+    const def = getRenderer(props.id);
+    if (!def) return { kind: "fallback", reason: `unregistered id "${props.id}"` };
+    const v = validateConsumes(def.consumes, props.item);
+    if (!v.ok) return { kind: "fallback", reason: v.errors.join("; ") };
+    return { kind: "ok", render: def.render, emits: def.emits };
+  });
+
+  // Guard emits: only declared interaction points pass through (§8). An
+  // undeclared name is dropped + warned, never forwarded to the host.
+  const emit = (event: string, payload?: unknown) => {
+    const r = resolved();
+    if (r.kind !== "ok") return;
+    if (!r.emits.includes(event)) {
+      console.warn(
+        `[ksui] CustomRenderer "${props.id}": ignored undeclared emit "${event}" (declared: ${r.emits.join(", ") || "none"})`,
+      );
+      return;
+    }
+    props.onEmit?.(event, payload);
+  };
+
+  return (
+    <Show
+      when={resolved().kind === "ok"}
+      fallback={(() => {
+        const r = resolved();
+        const reason = r.kind === "fallback" ? r.reason : "";
+        // WHY warn here: a fallback means a spec referenced a renderer the bundle
+        // doesn't satisfy — a build/config drift the developer must see (§8).
+        console.warn(`[ksui] CustomRenderer falling back for "${props.id}": ${reason}`);
+        const Fallback = props.fallback ?? DefaultFallback;
+        return <Fallback id={props.id} reason={reason} />;
+      })()}
+    >
+      <Dynamic
+        component={(resolved() as { render: Component<RendererProps> }).render}
+        item={props.item}
+        emit={emit}
+      />
+    </Show>
+  );
+};
+
+export default CustomRenderer;

package/src/components/composite/FileField.test.tsx

@@ -0,0 +1,112 @@
+// U6 — FileField tests: state transitions, injected uploader/resolver called,
+// graceful degrade on a rejected presign + a rejected upload.
+import { describe, expect, it, vi } from "vitest";
+import { render, fireEvent, waitFor } from "@solidjs/testing-library";
+import FileField, { type AssetHandle } from "./FileField";
+
+const imageHandle: AssetHandle = { id: "a1", name: "receipt.png", mime: "image/png", size: 2048 };
+
+function pngFile(): File {
+  return new File([new Uint8Array([1, 2, 3])], "receipt.png", { type: "image/png" });
+}
+
+describe("FileField", () => {
+  it("starts empty with a drop zone", () => {
+    const { getByTestId } = render(() => (
+      <FileField testId="ff" onUpload={vi.fn(async () => imageHandle)} />
+    ));
+    expect(getByTestId("ff-drop")).toBeTruthy();
+  });
+
+  it("calls the injected uploader on pick and transitions to done", async () => {
+    const onUpload = vi.fn(async () => imageHandle);
+    const onChange = vi.fn();
+    const presignUrl = vi.fn(async () => "https://signed/url.png");
+    const { getByTestId, queryByTestId } = render(() => (
+      <FileField testId="ff" onUpload={onUpload} onChange={onChange} presignUrl={presignUrl} />
+    ));
+    const input = getByTestId("ff-input") as HTMLInputElement;
+    Object.defineProperty(input, "files", { value: [pngFile()], configurable: true });
+    fireEvent.change(input);
+
+    await waitFor(() => expect(onUpload).toHaveBeenCalled());
+    await waitFor(() => expect(getByTestId("ff-done")).toBeTruthy());
+    expect(onChange).toHaveBeenCalledWith(imageHandle);
+    // image handle → presign called for preview
+    await waitFor(() => expect(presignUrl).toHaveBeenCalledWith(imageHandle));
+    await waitFor(() => expect(getByTestId("ff-preview")).toBeTruthy());
+    expect(queryByTestId("ff-drop")).toBeNull();
+  });
+
+  it("degrades gracefully (broken thumb, no throw) when presign rejects", async () => {
+    const onUpload = vi.fn(async () => imageHandle);
+    const presignUrl = vi.fn(async () => {
+      throw new Error("expired");
+    });
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { getByTestId } = render(() => (
+      <FileField testId="ff" onUpload={onUpload} presignUrl={presignUrl} />
+    ));
+    const input = getByTestId("ff-input") as HTMLInputElement;
+    Object.defineProperty(input, "files", { value: [pngFile()], configurable: true });
+    fireEvent.change(input);
+
+    await waitFor(() => expect(getByTestId("ff-broken")).toBeTruthy());
+  });
+
+  it("shows a failed state when the uploader rejects (never throws)", async () => {
+    const onUpload = vi.fn(async () => {
+      throw new Error("offline");
+    });
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { getByTestId } = render(() => <FileField testId="ff" onUpload={onUpload} />);
+    const input = getByTestId("ff-input") as HTMLInputElement;
+    Object.defineProperty(input, "files", { value: [pngFile()], configurable: true });
+    fireEvent.change(input);
+
+    await waitFor(() => expect(getByTestId("ff-failed").textContent).toContain("offline"));
+    expect(getByTestId("ff-retry")).toBeTruthy();
+  });
+
+  it("clears the handle when removed", async () => {
+    const onChange = vi.fn();
+    const { getByTestId } = render(() => (
+      <FileField
+        testId="ff"
+        value={{ id: "x", name: "doc.pdf", mime: "application/pdf", size: 100 }}
+        onUpload={vi.fn(async () => imageHandle)}
+        onChange={onChange}
+      />
+    ));
+    expect(getByTestId("ff-done")).toBeTruthy();
+    fireEvent.click(getByTestId("ff-remove"));
+    await waitFor(() => expect(onChange).toHaveBeenCalledWith(null));
+    expect(getByTestId("ff-drop")).toBeTruthy();
+  });
+
+  it("loads a pre-seeded image value via the presigned (https) URL into the preview", async () => {
+    const presignUrl = vi.fn(async () => "https://signed.example/preview.png?sig=abc");
+    const { getByTestId } = render(() => (
+      <FileField testId="ff" value={imageHandle} onUpload={vi.fn(async () => imageHandle)} presignUrl={presignUrl} />
+    ));
+    // A value handle present at mount presigns eagerly and shows the done card.
+    expect(getByTestId("ff-done")).toBeTruthy();
+    await waitFor(() => expect(presignUrl).toHaveBeenCalledWith(imageHandle));
+    const img = (await waitFor(() => getByTestId("ff-preview"))) as HTMLImageElement;
+    expect(img.getAttribute("src")).toBe("https://signed.example/preview.png?sig=abc");
+  });
+
+  it("renders a non-image handle with a file icon (no presign)", () => {
+    const presignUrl = vi.fn(async () => "x");
+    const { getByTestId } = render(() => (
+      <FileField
+        testId="ff"
+        value={{ id: "x", name: "doc.pdf", mime: "application/pdf", size: 100 }}
+        onUpload={vi.fn(async () => imageHandle)}
+        presignUrl={presignUrl}
+      />
+    ));
+    expect(getByTestId("ff-done")).toBeTruthy();
+    expect(presignUrl).not.toHaveBeenCalled(); // only images presign
+  });
+});