@kahitsan/ksui 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.19.0",
+  "version": "0.20.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/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,100 @@
+// 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("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
+  });
+});

package/src/components/composite/FileField.tsx

@@ -0,0 +1,301 @@
+// U6 — FileField (Vision §11): a declarative file/media input for the spec-driven
+// form runtime. Its value is an OPAQUE asset HANDLE (`{ id, name, mime, size }`),
+// not a path or URL (§11 / Data Arch §4 opaque-id storage). The component is
+// storage-agnostic: it knows nothing about S3/MinIO/the kernel. The HOST injects
+// two callbacks:
+//   - onUpload(file) => Promise<handle>   wires to the kernel asset service
+//   - presignUrl(handle) => Promise<url>  resolves a handle to a time-limited URL
+// ksui only models the field UX + state machine (pending / uploading / done /
+// failed) and the preview. A missing/expired asset degrades gracefully — a
+// rejected presign shows a broken-thumbnail fallback + warns, never throws (§11).
+//
+// Composite because it composes the upload/preview state machine and self-injects
+// its CSS (ksui-ff-* unscoped classes + CSS custom props); no Tailwind, no
+// host-brand classes (standalone-library rule).
+
+import type { Component, JSX } from "solid-js";
+import { Match, Show, Switch, createSignal } from "solid-js";
+import UploadCloud from "lucide-solid/icons/cloud-upload";
+import FileIcon from "lucide-solid/icons/file";
+import ImageOff from "lucide-solid/icons/image-off";
+import X from "lucide-solid/icons/x";
+
+/** The opaque asset handle the field stores as its value (§11). */
+export interface AssetHandle {
+  readonly id: string;
+  readonly name: string;
+  readonly mime: string;
+  readonly size: number;
+}
+
+/** Upload/preview lifecycle (§11: pending while queued, failed on hard error). */
+export type FileFieldStatus = "empty" | "uploading" | "done" | "failed";
+
+const STYLE_ID = "ksui-file-field-style";
+
+function ensureStyle(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = `
+.ksui-ff{display:flex;flex-direction:column;gap:0.5rem;}
+.ksui-ff-drop{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:0.375rem;padding:1.25rem;border-radius:0.625rem;border:1.5px dashed var(--ksui-ff-border,rgba(255,255,255,0.2));background:var(--ksui-ff-bg,rgba(255,255,255,0.03));color:var(--ksui-ff-fg,inherit);cursor:pointer;text-align:center;font-size:0.82rem;transition:border-color .15s,background .15s;}
+.ksui-ff-drop.dragging{border-color:var(--ksui-ff-accent,#c9a961);background:var(--ksui-ff-accent-bg,rgba(201,169,97,0.08));}
+.ksui-ff-drop:disabled{opacity:0.5;cursor:not-allowed;}
+.ksui-ff-hint{font-size:0.72rem;opacity:0.6;}
+.ksui-ff-card{display:flex;align-items:center;gap:0.625rem;padding:0.5rem 0.625rem;border-radius:0.5rem;border:1px solid var(--ksui-ff-border,rgba(255,255,255,0.15));background:var(--ksui-ff-bg,rgba(255,255,255,0.03));}
+.ksui-ff-thumb{width:2.5rem;height:2.5rem;border-radius:0.375rem;object-fit:cover;flex:0 0 auto;background:rgba(255,255,255,0.06);display:flex;align-items:center;justify-content:center;}
+.ksui-ff-meta{display:flex;flex-direction:column;min-width:0;flex:1;}
+.ksui-ff-name{font-size:0.82rem;font-weight:500;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+.ksui-ff-sub{font-size:0.72rem;opacity:0.6;}
+.ksui-ff-sub.failed{color:var(--ksui-ff-danger,#f87171);}
+.ksui-ff-remove{margin-left:auto;flex:0 0 auto;display:flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;border-radius:0.375rem;border:1px solid var(--ksui-ff-border,rgba(255,255,255,0.15));background:transparent;color:inherit;cursor:pointer;}
+.ksui-ff-retry{font-size:0.72rem;text-decoration:underline;cursor:pointer;color:var(--ksui-ff-accent,#c9a961);background:none;border:none;padding:0;}
+`;
+  document.head.appendChild(style);
+}
+
+export interface FileFieldProps {
+  /** Field label. */
+  label?: string;
+  /** Current value — an asset handle, or null when empty. */
+  value?: AssetHandle | null;
+  /** Emitted when the handle changes (upload done, or cleared to null). */
+  onChange?: (handle: AssetHandle | null) => void;
+  /**
+   * HOST-injected uploader: takes the picked File, returns the asset handle once
+   * the kernel asset service has stored it. ksui stays storage-agnostic (§11).
+   */
+  onUpload: (file: File) => Promise<AssetHandle>;
+  /**
+   * HOST-injected resolver: turns a handle into a time-limited URL for preview
+   * (§11). ksui never knows about S3/kernel. A rejection degrades to a broken-
+   * thumbnail fallback — never throws.
+   */
+  presignUrl?: (handle: AssetHandle) => Promise<string>;
+  /** Accept hint (e.g. ["image/*","application/pdf"]) for the picker + filter. */
+  accept?: readonly string[];
+  /** Disable interaction. */
+  disabled?: boolean;
+  /** Optional test id prefix. */
+  testId?: string;
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export const FileField: Component<FileFieldProps> = (props) => {
+  ensureStyle();
+  const [status, setStatus] = createSignal<FileFieldStatus>(props.value ? "done" : "empty");
+  // The handle currently shown. Seeded from props.value, and updated locally on a
+  // fresh upload so the done card shows even when the parent doesn't echo onChange
+  // back into `value` (controlled and uncontrolled both work).
+  const [current, setCurrent] = createSignal<AssetHandle | null>(props.value ?? null);
+  const [dragging, setDragging] = createSignal(false);
+  const [previewUrl, setPreviewUrl] = createSignal<string | null>(null);
+  const [previewFailed, setPreviewFailed] = createSignal(false);
+  const [errorMsg, setErrorMsg] = createSignal<string | null>(null);
+  let inputEl: HTMLInputElement | undefined;
+
+  const tid = (s: string) => (props.testId ? `${props.testId}-${s}` : undefined);
+  const acceptAttr = () => props.accept?.join(",");
+
+  const isImage = (h: AssetHandle | null | undefined) => !!h && h.mime.startsWith("image/");
+
+  // Resolve a preview URL for an image handle via the injected presigner. A
+  // rejected presign (missing/expired asset, §11) sets previewFailed instead of
+  // throwing — the card then shows the broken-thumbnail fallback + a warning.
+  const loadPreview = (handle: AssetHandle) => {
+    setPreviewUrl(null);
+    setPreviewFailed(false);
+    if (!isImage(handle) || !props.presignUrl) return;
+    props
+      .presignUrl(handle)
+      .then((url) => setPreviewUrl(url))
+      .catch((e) => {
+        setPreviewFailed(true);
+        console.warn(`[ksui] FileField: preview unavailable for "${handle.name}"`, e);
+      });
+  };
+
+  // Drive the upload state machine for a picked/dropped file.
+  const upload = (file: File) => {
+    setErrorMsg(null);
+    setStatus("uploading");
+    props
+      .onUpload(file)
+      .then((handle) => {
+        setStatus("done");
+        setCurrent(handle);
+        props.onChange?.(handle);
+        loadPreview(handle);
+      })
+      .catch((e) => {
+        setStatus("failed");
+        // §11: a hard failure tells the user it couldn't upload — never throws up.
+        setErrorMsg(e instanceof Error ? e.message : "Couldn't upload to the cloud");
+        console.warn("[ksui] FileField: upload failed", e);
+      });
+  };
+
+  // If a value handle is supplied at mount, load its preview eagerly.
+  if (props.value) loadPreview(props.value);
+
+  const pick = () => {
+    if (props.disabled) return;
+    inputEl?.click();
+  };
+
+  const onPicked = (e: Event & { currentTarget: HTMLInputElement }) => {
+    const file = e.currentTarget.files?.[0];
+    if (file) upload(file);
+    e.currentTarget.value = ""; // allow re-picking the same file
+  };
+
+  const onDrop = (e: DragEvent) => {
+    e.preventDefault();
+    setDragging(false);
+    if (props.disabled) return;
+    const file = e.dataTransfer?.files?.[0];
+    if (file) upload(file);
+  };
+
+  const clear = () => {
+    setStatus("empty");
+    setCurrent(null);
+    setPreviewUrl(null);
+    setPreviewFailed(false);
+    setErrorMsg(null);
+    props.onChange?.(null);
+  };
+
+  // Prefer a controlled value when the parent supplies one; else the locally
+  // tracked handle from the last upload.
+  const handle = () => props.value ?? current();
+
+  return (
+    <div class="ksui-ff" data-testid={tid("root")}>
+      <Show when={props.label}>
+        <span class="ksui-ff-label">{props.label}</span>
+      </Show>
+
+      <input
+        ref={inputEl}
+        type="file"
+        accept={acceptAttr()}
+        style={{ display: "none" }}
+        data-testid={tid("input")}
+        onChange={onPicked}
+      />
+
+      <Switch>
+        {/* empty → the drop zone / click-to-pick affordance */}
+        <Match when={status() === "empty"}>
+          <button
+            type="button"
+            class={`ksui-ff-drop${dragging() ? " dragging" : ""}`}
+            disabled={props.disabled}
+            data-testid={tid("drop")}
+            data-dragging={dragging() ? "true" : "false"}
+            onClick={pick}
+            onDragOver={(e) => {
+              e.preventDefault();
+              setDragging(true);
+            }}
+            onDragLeave={() => setDragging(false)}
+            onDrop={onDrop}
+          >
+            <UploadCloud size={22} />
+            <span>Drop a file or click to upload</span>
+            <Show when={props.accept?.length}>
+              <span class="ksui-ff-hint">{props.accept!.join(", ")}</span>
+            </Show>
+          </button>
+        </Match>
+
+        {/* uploading → pending state (§11 pending while queued) */}
+        <Match when={status() === "uploading"}>
+          <div class="ksui-ff-card" data-testid={tid("uploading")}>
+            <span class="ksui-ff-thumb">
+              <UploadCloud size={18} />
+            </span>
+            <div class="ksui-ff-meta">
+              <span class="ksui-ff-name">Uploading…</span>
+              <span class="ksui-ff-sub">Sending to the cloud</span>
+            </div>
+          </div>
+        </Match>
+
+        {/* failed → hard-failure notice + retry (§11: tell the user, never throw) */}
+        <Match when={status() === "failed"}>
+          <div class="ksui-ff-card" data-testid={tid("failed")}>
+            <span class="ksui-ff-thumb">
+              <ImageOff size={18} />
+            </span>
+            <div class="ksui-ff-meta">
+              <span class="ksui-ff-name">Upload failed</span>
+              <span class="ksui-ff-sub failed">{errorMsg() ?? "Couldn't upload to the cloud"}</span>
+            </div>
+            <button type="button" class="ksui-ff-retry" data-testid={tid("retry")} onClick={pick}>
+              Retry
+            </button>
+          </div>
+        </Match>
+
+        {/* done → the asset card with image preview (graceful-degrade fallback) */}
+        <Match when={status() === "done" && !!handle()}>
+          {renderDoneCard(handle()!, isImage(handle()), previewUrl(), previewFailed(), () => setPreviewFailed(true), props.disabled, clear, tid)}
+        </Match>
+      </Switch>
+    </div>
+  );
+};
+
+function renderDoneCard(
+  h: AssetHandle,
+  image: boolean,
+  url: string | null,
+  failed: boolean,
+  onImgError: () => void,
+  disabled: boolean | undefined,
+  onClear: () => void,
+  tid: (s: string) => string | undefined,
+): JSX.Element {
+  return (
+    <div class="ksui-ff-card" data-testid={tid("done")}>
+      <span class="ksui-ff-thumb" data-testid={tid("thumb")}>
+        <Switch fallback={<FileIcon size={18} />}>
+          {/* image + a presigned url that loaded → real thumbnail */}
+          <Match when={image && url && !failed}>
+            <img
+              src={url!}
+              alt={h.name}
+              class="ksui-ff-thumb"
+              data-testid={tid("preview")}
+              onError={onImgError}
+            />
+          </Match>
+          {/* image but the presign rejected/expired → broken-thumbnail fallback (§11) */}
+          <Match when={image && failed}>
+            <ImageOff size={18} data-testid={tid("broken")} />
+          </Match>
+        </Switch>
+      </span>
+      <div class="ksui-ff-meta">
+        <span class="ksui-ff-name">{h.name}</span>
+        <span class="ksui-ff-sub">{formatSize(h.size)}</span>
+      </div>
+      <Show when={!disabled}>
+        <button type="button" class="ksui-ff-remove" aria-label="Remove file" data-testid={tid("remove")} onClick={onClear}>
+          <X size={14} />
+        </button>
+      </Show>
+    </div>
+  );
+}
+
+export default FileField;