@cfast/ui 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Schmidt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/{client-CIx8_tmv.d.ts → client-C0K-7jLA.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.
  *
@@ -1881,4 +2005,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 FormStatusProps 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, DetailView as G, type DetailViewProps as H, type ImageFieldProps as I, type JsonFieldProps as J, DropZone as K, type DropZoneProps as L, type DropZoneSlotProps as M, type NumberFieldProps as N, FileList$1 as O, type FileListFile as P, type FileListProps as Q, type RelationFieldProps as R, FilterBar as S, type TextFieldProps as T, type UrlFieldProps as U, type FilterBarProps as V, type FilterDef as W, type FilterOption as X, type FilterType as Y, FormStatus as Z, type FormStatusData as _, type UploadFieldProps as a, ImagePreview as a0, type ImagePreviewProps as a1, ImpersonationBanner as a2, type ImpersonationBannerProps as a3, ListView as a4, type ListViewProps as a5, type PageContainerSlotProps as a6, PermissionGate as a7, type PermissionGateProps as a8, RoleBadge as a9, type RoleBadgeProps as aa, type SidebarSlotProps as ab, type TableCellSlotProps as ac, type TableRowSlotProps as ad, type TableSectionSlotProps as ae, type TableSlotProps as af, type ToastApi as ag, ToastContext as ah, type ToastOptions as ai, type ToastSlotProps as aj, type ToastType as ak, type TooltipSlotProps as al, type UIPlugin as am, type UIPluginComponents as an, UIPluginProvider as ao, type UploadFieldFile as ap, type UserMenuLink as aq, type WhenForbidden as ar, createUIPlugin as as, getInitials as at, useActionToast as au, useColumnInference as av, useComponent as aw, useConfirm as ax, useToast as ay, useUIPlugin 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, type ConfirmDialogSlotProps as v, type ConfirmOptions as w, ConfirmProvider as x, DataTable as y, type DataTableProps 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, x as ConfirmProvider, y as DataTable, G as DetailView, K as DropZone, O as FileList, S as FilterBar, Z as FormStatus, a0 as ImagePreview, a2 as ImpersonationBanner, a4 as ListView, a7 as PermissionGate, a9 as RoleBadge, ao as UIPluginProvider, as as createUIPlugin, at as getInitials, au as useActionToast, av as useColumnInference, aw as useComponent, ax as useConfirm, ay as useToast, az as useUIPlugin } from './client-C0K-7jLA.js';
 import 'react/jsx-runtime';
 import 'react';
 import '@cfast/actions/client';

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-C0K-7jLA.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 ConfirmDialogSlotProps, w as ConfirmOptions, x as ConfirmProvider, y as DataTable, z as DataTableProps, G as DetailView, H as DetailViewProps, K as DropZone, L as DropZoneProps, M as DropZoneSlotProps, O as FileList, P as FileListFile, Q as FileListProps, S as FilterBar, V as FilterBarProps, W as FilterDef, X as FilterOption, Y as FilterType, Z as FormStatus, _ as FormStatusData, $ as FormStatusProps, a0 as ImagePreview, a1 as ImagePreviewProps, a2 as ImpersonationBanner, a3 as ImpersonationBannerProps, a4 as ListView, a5 as ListViewProps, a6 as PageContainerSlotProps, a7 as PermissionGate, a8 as PermissionGateProps, a9 as RoleBadge, aa as RoleBadgeProps, ab as SidebarSlotProps, ac as TableCellSlotProps, ad as TableRowSlotProps, ae as TableSectionSlotProps, af as TableSlotProps, ag as ToastApi, ah as ToastContext, ai as ToastOptions, aj as ToastSlotProps, ak as ToastType, al as TooltipSlotProps, am as UIPlugin, an as UIPluginComponents, ao as UIPluginProvider, ap as UploadFieldFile, aq as UserMenuLink, ar as WhenForbidden, as as createUIPlugin, at as getInitials, au as useActionToast, av as useColumnInference, aw as useComponent, ax as useConfirm, ay as useToast, az as useUIPlugin } from './client-C0K-7jLA.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

@@ -125,9 +125,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 +555,7 @@ function NavigationProgress({
   if (!isNavigating) {
     return null;
   }
-  return /* @__PURE__ */ jsx5(
+  return /* @__PURE__ */ jsx6(
     "div",
     {
       role: "progressbar",
@@ -156,32 +575,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 +611,7 @@ function AppShellHeader({
         borderBottom: "1px solid #ddd"
       },
       children: [
-        children ?? /* @__PURE__ */ jsx6(Fragment, {}),
+        children ?? /* @__PURE__ */ jsx7(Fragment, {}),
         userMenu ?? null
       ]
     }
@@ -203,7 +622,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 +631,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 +640,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 +666,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,
@@ -282,6 +701,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
@@ -157,3 +189,8 @@ useActionToast(composed.client, {
 - Forgetting `<ConfirmProvider>` -- `useConfirm()` and `ActionButton` with `confirmation` need it.
 - Passing raw data arrays to `DataTable` instead of a pagination result from `usePagination()`.
 - Using `whenForbidden="show"` on `ActionButton` when you mean `"disable"` -- `"show"` renders even when forbidden with no visual indicator.
+
+## See Also
+
+- `@cfast/joy` -- Drop-in MUI Joy plugin that styles `@cfast/ui` headless components.
+- `@cfast/actions` -- Provides the action descriptors consumed by `ActionButton`/`ActionForm`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Permission-aware React components with UI library plugins",
   "keywords": [
     "cfast",
@@ -36,25 +36,36 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup src/index.ts src/client.ts --format esm --dts",
-    "dev": "tsup src/index.ts src/client.ts --format esm --dts --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "test": "vitest run"
-  },
   "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.5.0",
+    "@cfast/storage": ">=0.1.0 <0.3.0",
     "react": ">=19",
     "react-dom": ">=19",
     "react-router": ">=7"
   },
-  "dependencies": {
-    "@cfast/actions": "workspace:*",
-    "@cfast/auth": "workspace:*",
-    "@cfast/db": "workspace:*",
-    "@cfast/pagination": "workspace:*",
-    "@cfast/permissions": "workspace:*",
-    "@cfast/storage": "workspace:*"
+  "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",
@@ -67,6 +78,19 @@
     "react-router": "^7.12.0",
     "tsup": "^8",
     "typescript": "^5.7",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "@cfast/actions": "0.1.2",
+    "@cfast/auth": "0.4.0",
+    "@cfast/pagination": "0.2.0",
+    "@cfast/permissions": "0.4.0",
+    "@cfast/storage": "0.2.0",
+    "@cfast/db": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/client.ts --format esm --dts",
+    "dev": "tsup src/index.ts src/client.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run"
   }
-}
+}