@cfast/ui 0.2.1 → 0.3.1

package/dist/{chunk-PWBG6CGF.js → chunk-TLLCSKE5.js}

@@ -1363,6 +1363,7 @@ export {
   UIPluginProvider,
   useUIPlugin,
   useComponent,
+  ConfirmContext,
   useConfirm,
   ToastContext,
   useToast,

package/dist/{client-CIx8_tmv.d.ts → client-DcCN1BR-.d.ts}

@@ -788,6 +788,130 @@ type JsonFieldProps = BaseFieldProps & {
     /** Whether to initially show a collapsed preview. */
     collapsed?: boolean;
 };
+/**
+ * Per-file upload state tracked internally by {@link UploadFieldProps}.
+ *
+ * Each entry corresponds to a file the user selected (or dropped) into the
+ * field. Once a file finishes uploading successfully its `key` is appended
+ * to the controlled `value` array and the entry can be removed from this
+ * tracker. Failed uploads stay in the tracker so the user can see (and
+ * dismiss) the error inline without losing previously uploaded files.
+ */
+type UploadFieldFile = {
+    /** Stable id for React keying / tracking across renders. */
+    id: string;
+    /** Display name (taken from `File.name`). */
+    name: string;
+    /** File size in bytes. */
+    size: number;
+    /** MIME type as reported by the browser. */
+    type: string;
+    /** Current upload progress as a 0-100 percentage. */
+    progress: number;
+    /** Lifecycle status. */
+    status: "pending" | "uploading" | "success" | "error";
+    /** Server-side R2 key, only set after a successful upload. */
+    key?: string;
+    /** Inline error message if `status === "error"`. */
+    error?: string;
+};
+/**
+ * Props for the headless {@link UploadField} component.
+ *
+ * `UploadField` is a controlled, multi-file upload widget built on the
+ * opinionated `POST /uploads/:filetype` route exposed by `@cfast/storage`.
+ * Unlike {@link DropZoneProps} (which only wraps a single `useUpload`
+ * result), `UploadField` is the form-friendly variant: it owns its own
+ * upload state, integrates with `react-hook-form` via the controlled
+ * `value`/`onChange` pair, enforces `maxFiles`, and surfaces per-file
+ * progress + per-file error reporting.
+ *
+ * The field reports its current value as `string[]` of R2 keys — exactly
+ * the shape you would store on a Drizzle column like `text("image_key")`.
+ *
+ * @see {@link DropZoneProps} for the lower-level single-upload primitive.
+ * @see {@link UploadFieldFile} for the per-file tracker entries.
+ */
+type UploadFieldProps = BaseFieldProps & {
+    /**
+     * The filetype name registered in `defineStorage`. Used as the last
+     * segment of the upload POST URL — `${basePath}/${filetype}`.
+     */
+    filetype: string;
+    /**
+     * Mount path of the storage routes from `@cfast/storage/plugin`.
+     * Defaults to `"/uploads"`. Must match the `basePath` used in
+     * `storageRoutes()` / `createStorageRouteHandlers`.
+     */
+    basePath?: string;
+    /**
+     * Whether the field accepts multiple files. When `false` (default), the
+     * controlled value still flows through as `string[]` but only ever
+     * contains zero or one entries.
+     */
+    multiple?: boolean;
+    /**
+     * Hard cap on the number of files the user is allowed to upload through
+     * this field. Files dropped or selected past the cap are rejected with
+     * an inline error and never start uploading. Defaults to `1` when
+     * `multiple` is `false`, otherwise unlimited.
+     */
+    maxFiles?: number;
+    /**
+     * The HTML `accept` string passed to the underlying `<input type="file">`
+     * (e.g. `"image/*"` or `"image/png,image/webp"`). This should match the
+     * MIME types declared on the corresponding storage filetype so the
+     * browser-side picker can pre-filter selections.
+     */
+    accept?: string;
+    /**
+     * Optional client-side max size in bytes. Files larger than this are
+     * rejected before any bytes are sent. Server-side validation is still
+     * the source of truth — this is only a hint to the user.
+     */
+    maxSize?: number;
+    /**
+     * Controlled array of R2 keys. When `multiple` is `false`, treat this
+     * as a single-element array (the first entry is the active value).
+     */
+    value?: string[];
+    /**
+     * Called with the new array of keys whenever the set of successfully
+     * uploaded files changes — after a successful upload, after a removal,
+     * etc. Wire this to your `react-hook-form` `setValue` callback or to
+     * a controlled component's local state.
+     */
+    onChange?: (keys: string[]) => void;
+    /**
+     * Called whenever a per-file upload fails (network error, validation
+     * error, server-side rejection). Receives the file tracker entry — the
+     * `error` field on the entry is the rendered message.
+     */
+    onError?: (file: UploadFieldFile) => void;
+    /**
+     * Whether the field is disabled. Disabled fields render their existing
+     * value but don't accept new files and don't render the drop zone in
+     * an interactive state.
+     */
+    disabled?: boolean;
+    /**
+     * Custom uploader implementation. Defaults to a built-in `XMLHttpRequest`
+     * uploader that hits `${basePath}/${filetype}`. Override this in tests
+     * (or in apps that wrap the upload in extra logic) — both `@cfast/ui`'s
+     * own tests and the Joy variant's tests pass a mock through this prop
+     * instead of stubbing `XMLHttpRequest` globally.
+     */
+    uploader?: (file: File, options: {
+        url: string;
+        onProgress: (percent: number) => void;
+        signal?: AbortSignal;
+    }) => Promise<{
+        key: string;
+        size: number;
+        type: string;
+        url?: string;
+    }>;
+};
 /**
  * Toast notification severity levels.
  *
@@ -1355,6 +1479,10 @@ declare function useComponent<K extends keyof UIPluginComponents>(slot: K): UIPl
  * the user confirms, or `false` if they cancel or dismiss.
  */
 type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;
+type ConfirmContextValue = {
+    confirm: ConfirmFn;
+};
+declare const ConfirmContext: react.Context<ConfirmContextValue | null>;
 /**
  * Returns an imperative {@link ConfirmFn} that opens a confirmation dialog
  * and resolves to `true` (confirmed) or `false` (cancelled/dismissed).
@@ -1881,4 +2009,4 @@ declare function ListView<T = unknown>({ title, data, table: _table, columns, ac
  */
 declare function DetailView<T = unknown>({ title, table, record, fields: fieldsProp, exclude, breadcrumb, }: DetailViewProps<T>): react_jsx_runtime.JSX.Element;
 
-export { ImagePreview as $, type AppShellProps as A, type BooleanFieldProps as B, type ChipSlotProps as C, type DateFieldProps as D, type EmailFieldProps as E, type FileFieldProps as F, type DetailViewProps as G, DropZone as H, type ImageFieldProps as I, type JsonFieldProps as J, type DropZoneProps as K, type DropZoneSlotProps as L, FileList$1 as M, type NumberFieldProps as N, type FileListFile as O, type FileListProps as P, FilterBar as Q, type RelationFieldProps as R, type FilterBarProps as S, type TextFieldProps as T, type UrlFieldProps as U, type FilterDef as V, type FilterOption as W, type FilterType as X, FormStatus as Y, type FormStatusData as Z, type FormStatusProps as _, type FieldComponent as a, type ImagePreviewProps as a0, ImpersonationBanner as a1, type ImpersonationBannerProps as a2, ListView as a3, type ListViewProps as a4, type PageContainerSlotProps as a5, PermissionGate as a6, type PermissionGateProps as a7, RoleBadge as a8, type RoleBadgeProps as a9, type SidebarSlotProps as aa, type TableCellSlotProps as ab, type TableRowSlotProps as ac, type TableSectionSlotProps as ad, type TableSlotProps as ae, type ToastApi as af, ToastContext as ag, type ToastOptions as ah, type ToastSlotProps as ai, type ToastType as aj, type TooltipSlotProps as ak, type UIPlugin as al, type UIPluginComponents as am, UIPluginProvider as an, type UserMenuLink as ao, type WhenForbidden as ap, createUIPlugin as aq, getInitials as ar, useActionToast as as, useColumnInference as at, useComponent as au, useConfirm as av, useToast as aw, useUIPlugin as ax, type EmptyStateProps as b, type NavigationProgressProps as c, type BreadcrumbItem as d, type TabItem as e, type NavigationItem as f, type UserMenuProps as g, ActionButton as h, type ActionButtonProps as i, type AlertSlotProps as j, type AppShellSlotProps as k, AvatarWithInitials as l, type AvatarWithInitialsProps as m, type BaseFieldProps as n, type BreadcrumbSlotProps as o, type BulkAction as p, BulkActionBar as q, type ButtonSlotProps as r, type ColumnDef as s, type ColumnShorthand as t, type ConfirmDialogSlotProps as u, type ConfirmOptions as v, ConfirmProvider as w, DataTable as x, type DataTableProps as y, DetailView as z };
+export { type FormStatusData as $, type AppShellProps as A, type BooleanFieldProps as B, type ChipSlotProps as C, type DateFieldProps as D, type EmailFieldProps as E, type FileFieldProps as F, type DataTableProps as G, DetailView as H, type ImageFieldProps as I, type JsonFieldProps as J, type DetailViewProps as K, DropZone as L, type DropZoneProps as M, type NumberFieldProps as N, type DropZoneSlotProps as O, FileList$1 as P, type FileListFile as Q, type RelationFieldProps as R, type FileListProps as S, type TextFieldProps as T, type UrlFieldProps as U, FilterBar as V, type FilterBarProps as W, type FilterDef as X, type FilterOption as Y, type FilterType as Z, FormStatus as _, type UploadFieldProps as a, type FormStatusProps as a0, ImagePreview as a1, type ImagePreviewProps as a2, ImpersonationBanner as a3, type ImpersonationBannerProps as a4, ListView as a5, type ListViewProps as a6, type PageContainerSlotProps as a7, PermissionGate as a8, type PermissionGateProps as a9, useUIPlugin as aA, RoleBadge as aa, type RoleBadgeProps as ab, type SidebarSlotProps as ac, type TableCellSlotProps as ad, type TableRowSlotProps as ae, type TableSectionSlotProps as af, type TableSlotProps as ag, type ToastApi as ah, ToastContext as ai, type ToastOptions as aj, type ToastSlotProps as ak, type ToastType as al, type TooltipSlotProps as am, type UIPlugin as an, type UIPluginComponents as ao, UIPluginProvider as ap, type UploadFieldFile as aq, type UserMenuLink as ar, type WhenForbidden as as, createUIPlugin as at, getInitials as au, useActionToast as av, useColumnInference as aw, useComponent as ax, useConfirm as ay, useToast as az, type FieldComponent as b, type EmptyStateProps as c, type NavigationProgressProps as d, type BreadcrumbItem as e, type TabItem as f, type NavigationItem as g, type UserMenuProps as h, ActionButton as i, type ActionButtonProps as j, type AlertSlotProps as k, type AppShellSlotProps as l, AvatarWithInitials as m, type AvatarWithInitialsProps as n, type BaseFieldProps as o, type BreadcrumbSlotProps as p, type BulkAction as q, BulkActionBar as r, type ButtonSlotProps as s, type ColumnDef as t, type ColumnShorthand as u, ConfirmContext as v, type ConfirmDialogSlotProps as w, type ConfirmOptions as x, ConfirmProvider as y, DataTable as z };

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-export { h as ActionButton, l as AvatarWithInitials, q as BulkActionBar, w as ConfirmProvider, x as DataTable, z as DetailView, H as DropZone, M as FileList, Q as FilterBar, Y as FormStatus, $ as ImagePreview, a1 as ImpersonationBanner, a3 as ListView, a6 as PermissionGate, a8 as RoleBadge, an as UIPluginProvider, aq as createUIPlugin, ar as getInitials, as as useActionToast, at as useColumnInference, au as useComponent, av as useConfirm, aw as useToast, ax as useUIPlugin } from './client-CIx8_tmv.js';
+export { i as ActionButton, m as AvatarWithInitials, r as BulkActionBar, y as ConfirmProvider, z as DataTable, H as DetailView, L as DropZone, P as FileList, V as FilterBar, _ as FormStatus, a1 as ImagePreview, a3 as ImpersonationBanner, a5 as ListView, a8 as PermissionGate, aa as RoleBadge, ap as UIPluginProvider, at as createUIPlugin, au as getInitials, av as useActionToast, aw as useColumnInference, ax as useComponent, ay as useConfirm, az as useToast, aA as useUIPlugin } from './client-DcCN1BR-.js';
 import 'react/jsx-runtime';
 import 'react';
 import '@cfast/actions/client';

package/dist/client.js

@@ -23,7 +23,7 @@ import {
   useConfirm,
   useToast,
   useUIPlugin
-} from "./chunk-PWBG6CGF.js";
+} from "./chunk-TLLCSKE5.js";
 export {
   ActionButton,
   AvatarWithInitials,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { D as DateFieldProps, B as BooleanFieldProps, N as NumberFieldProps, T as TextFieldProps, E as EmailFieldProps, U as UrlFieldProps, I as ImageFieldProps, F as FileFieldProps, R as RelationFieldProps, J as JsonFieldProps, a as FieldComponent, b as EmptyStateProps, c as NavigationProgressProps, d as BreadcrumbItem, e as TabItem, A as AppShellProps, f as NavigationItem, g as UserMenuProps } from './client-CIx8_tmv.js';
-export { h as ActionButton, i as ActionButtonProps, j as AlertSlotProps, k as AppShellSlotProps, l as AvatarWithInitials, m as AvatarWithInitialsProps, n as BaseFieldProps, o as BreadcrumbSlotProps, p as BulkAction, q as BulkActionBar, r as ButtonSlotProps, C as ChipSlotProps, s as ColumnDef, t as ColumnShorthand, u as ConfirmDialogSlotProps, v as ConfirmOptions, w as ConfirmProvider, x as DataTable, y as DataTableProps, z as DetailView, G as DetailViewProps, H as DropZone, K as DropZoneProps, L as DropZoneSlotProps, M as FileList, O as FileListFile, P as FileListProps, Q as FilterBar, S as FilterBarProps, V as FilterDef, W as FilterOption, X as FilterType, Y as FormStatus, Z as FormStatusData, _ as FormStatusProps, $ as ImagePreview, a0 as ImagePreviewProps, a1 as ImpersonationBanner, a2 as ImpersonationBannerProps, a3 as ListView, a4 as ListViewProps, a5 as PageContainerSlotProps, a6 as PermissionGate, a7 as PermissionGateProps, a8 as RoleBadge, a9 as RoleBadgeProps, aa as SidebarSlotProps, ab as TableCellSlotProps, ac as TableRowSlotProps, ad as TableSectionSlotProps, ae as TableSlotProps, af as ToastApi, ag as ToastContext, ah as ToastOptions, ai as ToastSlotProps, aj as ToastType, ak as TooltipSlotProps, al as UIPlugin, am as UIPluginComponents, an as UIPluginProvider, ao as UserMenuLink, ap as WhenForbidden, aq as createUIPlugin, ar as getInitials, as as useActionToast, at as useColumnInference, au as useComponent, av as useConfirm, aw as useToast, ax as useUIPlugin } from './client-CIx8_tmv.js';
+import { D as DateFieldProps, B as BooleanFieldProps, N as NumberFieldProps, T as TextFieldProps, E as EmailFieldProps, U as UrlFieldProps, I as ImageFieldProps, F as FileFieldProps, R as RelationFieldProps, J as JsonFieldProps, a as UploadFieldProps, b as FieldComponent, c as EmptyStateProps, d as NavigationProgressProps, e as BreadcrumbItem, f as TabItem, A as AppShellProps, g as NavigationItem, h as UserMenuProps } from './client-DcCN1BR-.js';
+export { i as ActionButton, j as ActionButtonProps, k as AlertSlotProps, l as AppShellSlotProps, m as AvatarWithInitials, n as AvatarWithInitialsProps, o as BaseFieldProps, p as BreadcrumbSlotProps, q as BulkAction, r as BulkActionBar, s as ButtonSlotProps, C as ChipSlotProps, t as ColumnDef, u as ColumnShorthand, v as ConfirmContext, w as ConfirmDialogSlotProps, x as ConfirmOptions, y as ConfirmProvider, z as DataTable, G as DataTableProps, H as DetailView, K as DetailViewProps, L as DropZone, M as DropZoneProps, O as DropZoneSlotProps, P as FileList, Q as FileListFile, S as FileListProps, V as FilterBar, W as FilterBarProps, X as FilterDef, Y as FilterOption, Z as FilterType, _ as FormStatus, $ as FormStatusData, a0 as FormStatusProps, a1 as ImagePreview, a2 as ImagePreviewProps, a3 as ImpersonationBanner, a4 as ImpersonationBannerProps, a5 as ListView, a6 as ListViewProps, a7 as PageContainerSlotProps, a8 as PermissionGate, a9 as PermissionGateProps, aa as RoleBadge, ab as RoleBadgeProps, ac as SidebarSlotProps, ad as TableCellSlotProps, ae as TableRowSlotProps, af as TableSectionSlotProps, ag as TableSlotProps, ah as ToastApi, ai as ToastContext, aj as ToastOptions, ak as ToastSlotProps, al as ToastType, am as TooltipSlotProps, an as UIPlugin, ao as UIPluginComponents, ap as UIPluginProvider, aq as UploadFieldFile, ar as UserMenuLink, as as WhenForbidden, at as createUIPlugin, au as getInitials, av as useActionToast, aw as useColumnInference, ax as useComponent, ay as useConfirm, az as useToast, aA as useUIPlugin } from './client-DcCN1BR-.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import { ClientDescriptor, ActionHookResult } from '@cfast/actions/client';
@@ -188,6 +188,39 @@ declare function RelationField({ value, display, linkTo, }: RelationFieldProps):
  */
 declare function JsonField({ value, collapsed, }: JsonFieldProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Headless multi-file upload field for cfast forms.
+ *
+ * `UploadField` is a controlled, form-friendly component that uploads files
+ * through `@cfast/storage`'s opinionated `POST /uploads/:filetype` route
+ * and surfaces the resulting R2 keys via the `value` / `onChange` pair.
+ *
+ * It is intentionally headless: the markup is plain HTML so consumers can
+ * style it directly, and the Joy UI variant lives in `@cfast/joy`. The
+ * component handles:
+ *
+ * - Drag-and-drop and click-to-browse selection.
+ * - Per-file upload progress (via the configurable {@link UploadFieldProps.uploader}).
+ * - Per-file inline error reporting (server, network, or validation).
+ * - `accept` / `maxSize` / `maxFiles` enforcement before bytes leave the browser.
+ * - Controlled `value` round-tripping for `react-hook-form` and other state libs.
+ *
+ * @example
+ * ```tsx
+ * <UploadField
+ *   filetype="productImages"
+ *   basePath="/uploads"
+ *   multiple
+ *   maxFiles={10}
+ *   accept="image/*"
+ *   value={imageKeys}
+ *   onChange={setImageKeys}
+ *   onError={(file) => console.warn(file.error)}
+ * />
+ * ```
+ */
+declare function UploadField({ label, className, filetype, basePath, multiple, maxFiles, accept, maxSize, value, onChange, onError, disabled, uploader, }: UploadFieldProps): react_jsx_runtime.JSX.Element;
+
 type ColumnMeta = {
     dataType: string;
     name: string;
@@ -459,4 +492,4 @@ declare function getRecordId(obj: unknown): string | number;
  */
 declare function useActionStatus(descriptor: ClientDescriptor): ActionHookResult;
 
-export { AppShell, AppShellHeader, AppShellProps, AppShellSidebar, BooleanField, BooleanFieldProps, BreadcrumbItem, DateField, DateFieldProps, EmailField, EmailFieldProps, EmptyState, EmptyStateProps, FileField, FileFieldProps, ImageField, ImageFieldProps, JsonField, JsonFieldProps, NavigationItem, NavigationProgress, NavigationProgressProps, NumberField, NumberFieldProps, PageContainer, RelationField, RelationFieldProps, TabItem, TextField, TextFieldProps, UrlField, UrlFieldProps, UserMenu, UserMenuProps, fieldForColumn, fieldsForTable, getField, getRecordId, useActionStatus };
+export { AppShell, AppShellHeader, AppShellProps, AppShellSidebar, BooleanField, BooleanFieldProps, BreadcrumbItem, DateField, DateFieldProps, EmailField, EmailFieldProps, EmptyState, EmptyStateProps, FileField, FileFieldProps, ImageField, ImageFieldProps, JsonField, JsonFieldProps, NavigationItem, NavigationProgress, NavigationProgressProps, NumberField, NumberFieldProps, PageContainer, RelationField, RelationFieldProps, TabItem, TextField, TextFieldProps, UploadField, UploadFieldProps, UrlField, UrlFieldProps, UserMenu, UserMenuProps, fieldForColumn, fieldsForTable, getField, getRecordId, useActionStatus };

package/dist/index.js

@@ -3,6 +3,7 @@ import {
   AvatarWithInitials,
   BooleanField,
   BulkActionBar,
+  ConfirmContext,
   ConfirmProvider,
   DataTable,
   DateField,
@@ -37,7 +38,7 @@ import {
   useConfirm,
   useToast,
   useUIPlugin
-} from "./chunk-PWBG6CGF.js";
+} from "./chunk-TLLCSKE5.js";
 
 // src/fields/url-field.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -125,9 +126,428 @@ function RelationField({
   return /* @__PURE__ */ jsx4("span", { children: displayValue });
 }
 
+// src/fields/upload-field.tsx
+import { useCallback, useId, useRef, useState } from "react";
+import { jsx as jsx5, jsxs as jsxs2 } from "react/jsx-runtime";
+function defaultUploader(file, options) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open("POST", options.url);
+    xhr.upload.addEventListener("progress", (event) => {
+      if (event.lengthComputable) {
+        options.onProgress(Math.round(event.loaded / event.total * 100));
+      }
+    });
+    xhr.addEventListener("load", () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        try {
+          const parsed = JSON.parse(xhr.responseText);
+          if (typeof parsed.key === "string" && typeof parsed.size === "number" && typeof parsed.type === "string") {
+            resolve({
+              key: parsed.key,
+              size: parsed.size,
+              type: parsed.type,
+              url: typeof parsed.url === "string" ? parsed.url : void 0
+            });
+            return;
+          }
+          reject(new Error("Invalid response from server"));
+        } catch {
+          reject(new Error("Invalid response from server"));
+        }
+      } else {
+        try {
+          const parsed = JSON.parse(xhr.responseText);
+          const detail = typeof parsed.detail === "string" ? parsed.detail : typeof parsed.message === "string" ? parsed.message : `Upload failed (${xhr.status})`;
+          reject(new Error(detail));
+        } catch {
+          reject(new Error(`Upload failed (${xhr.status})`));
+        }
+      }
+    });
+    xhr.addEventListener("error", () => {
+      reject(new Error("Network error during upload"));
+    });
+    if (options.signal) {
+      options.signal.addEventListener("abort", () => {
+        xhr.abort();
+        reject(new Error("Upload cancelled"));
+      });
+    }
+    const formData = new FormData();
+    formData.append("file", file);
+    xhr.send(formData);
+  });
+}
+function matchesAccept(file, accept) {
+  if (!accept) return true;
+  const tokens = accept.split(",").map((t) => t.trim().toLowerCase()).filter(Boolean);
+  if (tokens.length === 0) return true;
+  const fileType = (file.type || "").toLowerCase();
+  const fileName = file.name.toLowerCase();
+  for (const token of tokens) {
+    if (token.startsWith(".")) {
+      if (fileName.endsWith(token)) return true;
+    } else if (token.endsWith("/*")) {
+      const prefix = token.slice(0, -1);
+      if (fileType.startsWith(prefix)) return true;
+    } else if (token === fileType) {
+      return true;
+    }
+  }
+  return false;
+}
+function formatBytes2(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function UploadField({
+  label,
+  className,
+  filetype,
+  basePath = "/uploads",
+  multiple = false,
+  maxFiles,
+  accept,
+  maxSize,
+  value,
+  onChange,
+  onError,
+  disabled = false,
+  uploader = defaultUploader
+}) {
+  const [files, setFiles] = useState([]);
+  const [isDragOver, setIsDragOver] = useState(false);
+  const [globalError, setGlobalError] = useState(null);
+  const inputRef = useRef(null);
+  const reactId = useId();
+  const normalizedBase = `/${basePath.replace(/^\/+|\/+$/g, "")}`;
+  const uploadUrl = `${normalizedBase}/${filetype}`;
+  const effectiveMax = maxFiles ?? (multiple ? Number.POSITIVE_INFINITY : 1);
+  const currentValue = value ?? [];
+  const appendKey = useCallback(
+    (key) => {
+      const next = [...currentValue, key];
+      onChange?.(next);
+    },
+    [currentValue, onChange]
+  );
+  const removeKey = useCallback(
+    (key) => {
+      const next = currentValue.filter((k) => k !== key);
+      onChange?.(next);
+    },
+    [currentValue, onChange]
+  );
+  const removeTrackerEntry = useCallback((id) => {
+    setFiles((prev) => prev.filter((f) => f.id !== id));
+  }, []);
+  const handleFiles = useCallback(
+    async (incoming) => {
+      if (disabled) return;
+      setGlobalError(null);
+      const list = Array.from(incoming);
+      if (list.length === 0) return;
+      const inFlight = files.filter((f) => f.status !== "error").length;
+      const remainingSlots = effectiveMax - currentValue.length - inFlight;
+      if (remainingSlots <= 0) {
+        setGlobalError(
+          `Maximum of ${effectiveMax} file${effectiveMax === 1 ? "" : "s"} reached`
+        );
+        return;
+      }
+      if (list.length > remainingSlots) {
+        setGlobalError(
+          `Only ${remainingSlots} more file${remainingSlots === 1 ? "" : "s"} allowed`
+        );
+        list.length = remainingSlots;
+      }
+      const accepted = [];
+      for (const file of list) {
+        const id = `${reactId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        if (!matchesAccept(file, accept)) {
+          const errEntry = {
+            id,
+            name: file.name,
+            size: file.size,
+            type: file.type,
+            progress: 0,
+            status: "error",
+            error: `${file.type || "file"} is not an accepted type`
+          };
+          accepted.push({ entry: errEntry, file });
+          onError?.(errEntry);
+          continue;
+        }
+        if (maxSize != null && file.size > maxSize) {
+          const errEntry = {
+            id,
+            name: file.name,
+            size: file.size,
+            type: file.type,
+            progress: 0,
+            status: "error",
+            error: `File is ${formatBytes2(file.size)} but max is ${formatBytes2(maxSize)}`
+          };
+          accepted.push({ entry: errEntry, file });
+          onError?.(errEntry);
+          continue;
+        }
+        accepted.push({
+          entry: {
+            id,
+            name: file.name,
+            size: file.size,
+            type: file.type,
+            progress: 0,
+            status: "pending"
+          },
+          file
+        });
+      }
+      setFiles((prev) => [...prev, ...accepted.map((a) => a.entry)]);
+      for (const { entry, file } of accepted) {
+        if (entry.status === "error") continue;
+        setFiles(
+          (prev) => prev.map(
+            (f) => f.id === entry.id ? { ...f, status: "uploading" } : f
+          )
+        );
+        try {
+          const result = await uploader(file, {
+            url: uploadUrl,
+            onProgress: (percent) => {
+              setFiles(
+                (prev) => prev.map(
+                  (f) => f.id === entry.id ? { ...f, progress: percent } : f
+                )
+              );
+            }
+          });
+          setFiles(
+            (prev) => prev.map(
+              (f) => f.id === entry.id ? { ...f, status: "success", progress: 100, key: result.key } : f
+            )
+          );
+          appendKey(result.key);
+          setFiles((prev) => prev.filter((f) => f.id !== entry.id));
+        } catch (e) {
+          const message = e instanceof Error ? e.message : String(e);
+          const errEntry = {
+            ...entry,
+            status: "error",
+            error: message
+          };
+          setFiles(
+            (prev) => prev.map((f) => f.id === entry.id ? errEntry : f)
+          );
+          onError?.(errEntry);
+        }
+      }
+    },
+    [
+      accept,
+      appendKey,
+      currentValue.length,
+      disabled,
+      effectiveMax,
+      files,
+      maxSize,
+      onError,
+      reactId,
+      uploadUrl,
+      uploader
+    ]
+  );
+  const handleDrop = useCallback(
+    (e) => {
+      e.preventDefault();
+      setIsDragOver(false);
+      void handleFiles(e.dataTransfer.files);
+    },
+    [handleFiles]
+  );
+  const handleDragOver = useCallback(
+    (e) => {
+      e.preventDefault();
+      if (!disabled) setIsDragOver(true);
+    },
+    [disabled]
+  );
+  const handleDragLeave = useCallback(() => {
+    setIsDragOver(false);
+  }, []);
+  const handleClick = useCallback(() => {
+    if (disabled) return;
+    inputRef.current?.click();
+  }, [disabled]);
+  const handleInputChange = useCallback(
+    (e) => {
+      void handleFiles(e.target.files ?? []);
+      e.target.value = "";
+    },
+    [handleFiles]
+  );
+  return /* @__PURE__ */ jsxs2("div", { className, "data-cfast-upload-field": filetype, children: [
+    label != null ? /* @__PURE__ */ jsx5(
+      "label",
+      {
+        htmlFor: `${reactId}-input`,
+        style: { display: "block", marginBottom: 4 },
+        children: label
+      }
+    ) : null,
+    /* @__PURE__ */ jsx5(
+      "div",
+      {
+        role: "button",
+        tabIndex: disabled ? -1 : 0,
+        "aria-disabled": disabled,
+        "data-drag-over": isDragOver,
+        "data-testid": "upload-field-drop-zone",
+        onClick: handleClick,
+        onDrop: handleDrop,
+        onDragOver: handleDragOver,
+        onDragLeave: handleDragLeave,
+        onKeyDown: (e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            handleClick();
+          }
+        },
+        style: {
+          border: "2px dashed",
+          borderColor: isDragOver ? "#1976d2" : "#ccc",
+          borderRadius: 4,
+          padding: 16,
+          textAlign: "center",
+          cursor: disabled ? "not-allowed" : "pointer",
+          opacity: disabled ? 0.6 : 1
+        },
+        children: multiple ? "Drop files here or click to browse" : "Drop a file here or click to browse"
+      }
+    ),
+    /* @__PURE__ */ jsx5(
+      "input",
+      {
+        ref: inputRef,
+        id: `${reactId}-input`,
+        type: "file",
+        accept,
+        multiple,
+        disabled,
+        style: { display: "none" },
+        onChange: handleInputChange,
+        "data-testid": "upload-field-input"
+      }
+    ),
+    globalError != null ? /* @__PURE__ */ jsx5("div", { role: "alert", "data-testid": "upload-field-global-error", style: { color: "#d32f2f", marginTop: 8 }, children: globalError }) : null,
+    currentValue.length > 0 ? /* @__PURE__ */ jsx5(
+      "ul",
+      {
+        "data-testid": "upload-field-value-list",
+        style: { listStyle: "none", padding: 0, margin: "8px 0 0 0" },
+        children: currentValue.map((key) => /* @__PURE__ */ jsxs2(
+          "li",
+          {
+            "data-testid": "upload-field-value-item",
+            style: {
+              display: "flex",
+              alignItems: "center",
+              gap: 8,
+              padding: "4px 0"
+            },
+            children: [
+              /* @__PURE__ */ jsx5("span", { style: { flex: 1, fontSize: "0.85em" }, children: key }),
+              /* @__PURE__ */ jsx5(
+                "button",
+                {
+                  type: "button",
+                  onClick: () => removeKey(key),
+                  disabled,
+                  "aria-label": `Remove ${key}`,
+                  style: {
+                    background: "none",
+                    border: "none",
+                    cursor: disabled ? "not-allowed" : "pointer",
+                    color: "#d32f2f"
+                  },
+                  children: "\xD7"
+                }
+              )
+            ]
+          },
+          key
+        ))
+      }
+    ) : null,
+    files.length > 0 ? /* @__PURE__ */ jsx5(
+      "ul",
+      {
+        "data-testid": "upload-field-tracker",
+        style: { listStyle: "none", padding: 0, margin: "8px 0 0 0" },
+        children: files.map((file) => /* @__PURE__ */ jsxs2(
+          "li",
+          {
+            "data-testid": "upload-field-tracker-item",
+            "data-status": file.status,
+            style: {
+              display: "flex",
+              flexDirection: "column",
+              gap: 4,
+              padding: "4px 0"
+            },
+            children: [
+              /* @__PURE__ */ jsxs2("div", { style: { display: "flex", alignItems: "center", gap: 8 }, children: [
+                /* @__PURE__ */ jsx5("span", { style: { flex: 1 }, children: file.name }),
+                /* @__PURE__ */ jsx5("span", { style: { color: "#666", fontSize: "0.85em" }, children: formatBytes2(file.size) }),
+                /* @__PURE__ */ jsx5(
+                  "button",
+                  {
+                    type: "button",
+                    onClick: () => removeTrackerEntry(file.id),
+                    "aria-label": `Dismiss ${file.name}`,
+                    style: {
+                      background: "none",
+                      border: "none",
+                      cursor: "pointer",
+                      color: "#666"
+                    },
+                    children: "\xD7"
+                  }
+                )
+              ] }),
+              file.status === "uploading" ? /* @__PURE__ */ jsx5(
+                "progress",
+                {
+                  "data-testid": "upload-field-progress",
+                  value: file.progress,
+                  max: 100,
+                  style: { width: "100%" }
+                }
+              ) : null,
+              file.status === "error" && file.error != null ? /* @__PURE__ */ jsx5(
+                "div",
+                {
+                  role: "alert",
+                  "data-testid": "upload-field-file-error",
+                  style: { color: "#d32f2f", fontSize: "0.85em" },
+                  children: file.error
+                }
+              ) : null
+            ]
+          },
+          file.id
+        ))
+      }
+    ) : null
+  ] });
+}
+
 // src/components/navigation-progress.tsx
 import { useNavigation } from "react-router";
-import { jsx as jsx5 } from "react/jsx-runtime";
+import { jsx as jsx6 } from "react/jsx-runtime";
 function NavigationProgress({
   color = "#1976d2"
 }) {
@@ -136,7 +556,7 @@ function NavigationProgress({
   if (!isNavigating) {
     return null;
   }
-  return /* @__PURE__ */ jsx5(
+  return /* @__PURE__ */ jsx6(
     "div",
     {
       role: "progressbar",
@@ -156,32 +576,32 @@ function NavigationProgress({
 }
 
 // src/components/app-shell.tsx
-import { Fragment, jsx as jsx6, jsxs as jsxs2 } from "react/jsx-runtime";
+import { Fragment, jsx as jsx7, jsxs as jsxs3 } from "react/jsx-runtime";
 function AppShell({ children, sidebar, header }) {
   const Shell = useComponent("appShell");
-  return /* @__PURE__ */ jsx6(Shell, { sidebar, header, children });
+  return /* @__PURE__ */ jsx7(Shell, { sidebar, header, children });
 }
 function AppShellSidebar({ items }) {
-  return /* @__PURE__ */ jsx6("nav", { children: /* @__PURE__ */ jsx6("ul", { style: { listStyle: "none", padding: 0, margin: 0 }, children: items.map((item) => /* @__PURE__ */ jsx6(SidebarItem, { item }, item.to)) }) });
+  return /* @__PURE__ */ jsx7("nav", { children: /* @__PURE__ */ jsx7("ul", { style: { listStyle: "none", padding: 0, margin: 0 }, children: items.map((item) => /* @__PURE__ */ jsx7(SidebarItem, { item }, item.to)) }) });
 }
 function SidebarItem({ item }) {
   if (item.action) {
-    return /* @__PURE__ */ jsx6(PermissionFilteredItem, { item });
+    return /* @__PURE__ */ jsx7(PermissionFilteredItem, { item });
   }
-  return /* @__PURE__ */ jsx6("li", { children: /* @__PURE__ */ jsx6("a", { href: item.to, children: item.label }) });
+  return /* @__PURE__ */ jsx7("li", { children: /* @__PURE__ */ jsx7("a", { href: item.to, children: item.label }) });
 }
 function PermissionFilteredItem({ item }) {
   const status = useActionStatus(item.action);
   if (status.invisible || !status.permitted) {
     return null;
   }
-  return /* @__PURE__ */ jsx6("li", { children: /* @__PURE__ */ jsx6("a", { href: item.to, children: item.label }) });
+  return /* @__PURE__ */ jsx7("li", { children: /* @__PURE__ */ jsx7("a", { href: item.to, children: item.label }) });
 }
 function AppShellHeader({
   children,
   userMenu
 }) {
-  return /* @__PURE__ */ jsxs2(
+  return /* @__PURE__ */ jsxs3(
     "header",
     {
       style: {
@@ -192,7 +612,7 @@ function AppShellHeader({
         borderBottom: "1px solid #ddd"
       },
       children: [
-        children ?? /* @__PURE__ */ jsx6(Fragment, {}),
+        children ?? /* @__PURE__ */ jsx7(Fragment, {}),
         userMenu ?? null
       ]
     }
@@ -203,7 +623,7 @@ AppShell.Header = AppShellHeader;
 
 // src/components/user-menu.tsx
 import { useCurrentUser } from "@cfast/auth/client";
-import { jsx as jsx7, jsxs as jsxs3 } from "react/jsx-runtime";
+import { jsx as jsx8, jsxs as jsxs4 } from "react/jsx-runtime";
 function UserMenu({
   links = [],
   onSignOut
@@ -212,8 +632,8 @@ function UserMenu({
   if (!user) {
     return null;
   }
-  return /* @__PURE__ */ jsxs3("div", { style: { position: "relative" }, children: [
-    /* @__PURE__ */ jsx7(
+  return /* @__PURE__ */ jsxs4("div", { style: { position: "relative" }, children: [
+    /* @__PURE__ */ jsx8(
       AvatarWithInitials,
       {
         src: user.avatarUrl,
@@ -221,17 +641,17 @@ function UserMenu({
         size: "sm"
       }
     ),
-    /* @__PURE__ */ jsxs3("div", { className: "user-menu-dropdown", children: [
-      /* @__PURE__ */ jsxs3("div", { children: [
-        /* @__PURE__ */ jsx7("strong", { children: user.name }),
-        /* @__PURE__ */ jsx7("br", {}),
-        /* @__PURE__ */ jsx7("small", { children: user.email })
+    /* @__PURE__ */ jsxs4("div", { className: "user-menu-dropdown", children: [
+      /* @__PURE__ */ jsxs4("div", { children: [
+        /* @__PURE__ */ jsx8("strong", { children: user.name }),
+        /* @__PURE__ */ jsx8("br", {}),
+        /* @__PURE__ */ jsx8("small", { children: user.email })
       ] }),
-      user.roles.length > 0 ? /* @__PURE__ */ jsx7("div", { style: { display: "flex", gap: "4px", marginTop: "4px" }, children: user.roles.map((role) => /* @__PURE__ */ jsx7(RoleBadge, { role }, role)) }) : null,
+      user.roles.length > 0 ? /* @__PURE__ */ jsx8("div", { style: { display: "flex", gap: "4px", marginTop: "4px" }, children: user.roles.map((role) => /* @__PURE__ */ jsx8(RoleBadge, { role }, role)) }) : null,
       links.map(
-        (link) => link.action ? /* @__PURE__ */ jsx7(PermissionFilteredLink, { link }, link.to) : /* @__PURE__ */ jsx7("a", { href: link.to, children: link.label }, link.to)
+        (link) => link.action ? /* @__PURE__ */ jsx8(PermissionFilteredLink, { link }, link.to) : /* @__PURE__ */ jsx8("a", { href: link.to, children: link.label }, link.to)
       ),
-      onSignOut ? /* @__PURE__ */ jsx7(
+      onSignOut ? /* @__PURE__ */ jsx8(
         "button",
         {
           onClick: onSignOut,
@@ -247,7 +667,7 @@ function PermissionFilteredLink({ link }) {
   if (status.invisible || !status.permitted) {
     return null;
   }
-  return /* @__PURE__ */ jsx7("a", { href: link.to, children: link.label });
+  return /* @__PURE__ */ jsx8("a", { href: link.to, children: link.label });
 }
 export {
   ActionButton,
@@ -257,6 +677,7 @@ export {
   AvatarWithInitials,
   BooleanField,
   BulkActionBar,
+  ConfirmContext,
   ConfirmProvider,
   DataTable,
   DateField,
@@ -282,6 +703,7 @@ export {
   TextField,
   ToastContext,
   UIPluginProvider,
+  UploadField,
   UrlField,
   UserMenu,
   createUIPlugin,

package/llms.txt

@@ -74,11 +74,43 @@ useColumnInference(table: Record<string, unknown> | undefined, columns?: string[
 ```typescript
 DateField, BooleanField, NumberField, TextField,
 EmailField, UrlField, ImageField, FileField,
-RelationField, JsonField
+RelationField, JsonField, UploadField
 fieldForColumn(columnMeta): ComponentType  // maps Drizzle column type to field
 fieldsForTable(table): Record<string, ComponentType>  // field map for whole table
 ```
 
+### UploadField (headless)
+
+Controlled multi-file upload field built on `@cfast/storage`'s `POST
+/uploads/:filetype` route. Unlike `DropZone` (which wraps a single
+`useUpload` call), `UploadField` is form-friendly: it owns its own upload
+state, enforces `maxFiles`, and reports successful uploads through the
+controlled `value` / `onChange` pair.
+
+```tsx
+import { UploadField } from "@cfast/ui";
+
+<UploadField
+  filetype="productImages"       // matches defineStorage key
+  basePath="/uploads"             // matches storageRoutes() mount path
+  multiple                        // allow multiple files
+  maxFiles={10}                   // hard cap (default 1 when !multiple)
+  accept="image/*"                // forwarded to <input accept>
+  maxSize={5 * 1024 * 1024}       // optional client-side byte cap
+  value={keys}                    // string[] of R2 keys (controlled)
+  onChange={setKeys}              // fires with updated keys
+  onError={(file) => ...}          // per-file upload error callback
+/>
+```
+
+Tests mock the POST endpoint by passing a custom `uploader` prop instead
+of stubbing `XMLHttpRequest` globally. The `uploader` signature is:
+
+```ts
+(file: File, opts: { url: string; onProgress: (pct: number) => void }) =>
+  Promise<{ key: string; size: number; type: string; url?: string }>
+```
+
 ### Plugin API
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/ui",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Permission-aware React components with UI library plugins",
   "keywords": [
     "cfast",
@@ -37,17 +37,35 @@
     "access": "public"
   },
   "peerDependencies": {
+    "@cfast/actions": ">=0.1.0 <0.3.0",
+    "@cfast/auth": ">=0.3.0 <0.5.0",
+    "@cfast/db": ">=0.3.0 <0.5.0",
+    "@cfast/pagination": ">=0.2.0 <0.4.0",
+    "@cfast/permissions": ">=0.3.0 <0.6.0",
+    "@cfast/storage": ">=0.1.0 <0.3.0",
     "react": ">=19",
     "react-dom": ">=19",
     "react-router": ">=7"
   },
-  "dependencies": {
-    "@cfast/actions": "0.1.1",
-    "@cfast/db": "0.1.1",
-    "@cfast/auth": "0.2.2",
-    "@cfast/pagination": "0.1.0",
-    "@cfast/permissions": "0.1.0",
-    "@cfast/storage": "0.1.0"
+  "peerDependenciesMeta": {
+    "@cfast/actions": {
+      "optional": false
+    },
+    "@cfast/auth": {
+      "optional": false
+    },
+    "@cfast/db": {
+      "optional": false
+    },
+    "@cfast/pagination": {
+      "optional": false
+    },
+    "@cfast/permissions": {
+      "optional": false
+    },
+    "@cfast/storage": {
+      "optional": false
+    }
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",
@@ -60,7 +78,13 @@
     "react-router": "^7.12.0",
     "tsup": "^8",
     "typescript": "^5.7",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "@cfast/actions": "0.1.3",
+    "@cfast/auth": "0.4.2",
+    "@cfast/db": "0.4.1",
+    "@cfast/pagination": "0.2.0",
+    "@cfast/permissions": "0.5.1",
+    "@cfast/storage": "0.2.1"
   },
   "scripts": {
     "build": "tsup src/index.ts src/client.ts --format esm --dts",