@viax.io/uxm 4.36.0

package/dist/ui/file-upload/file-upload.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/ui/file-upload/file-upload.tsx"],"sourcesContent":["import {\n  useCallback,\n  useId,\n  useState,\n  type ChangeEvent,\n  type CSSProperties,\n  type DragEvent,\n  type HTMLAttributes,\n  type ReactNode,\n} from 'react';\n\nimport { cn } from '@/helpers';\n\nimport { Icon } from '../icon';\n\n/**\n * Visual states the FileUpload **drop area** can be forced into via the\n * `state` prop. These describe the drop area surface only — not per-file\n * lifecycle. Per-file states (queued / uploading / done / error) live on\n * each `FileUploadFileMeta.status` and render row-by-row independently.\n *\n * `uploading` is **caller-controlled** — the atom never sets it from per-\n * file statuses. Use it for page-level signals: a batch is being prepared\n * before per-file rows exist, a chunked upload with no per-file progress,\n * or any \"the system is busy with this dropzone\" state the caller wants\n * to surface. Per-row uploading rows remain the *primary* progress signal.\n *\n * `error` means a *page-level* error (e.g. \"Connection lost\", \"Server\n * rejected the batch\") — surfaced via the `errorMessage` prop and shown\n * below the drop area. Per-file errors don't change the drop area's state.\n */\nexport type FileUploadState = 'default' | 'drag-over' | 'uploading' | 'error';\n\n/**\n * Per-file lifecycle status. The atom paints each row based on its own\n * status independently of other rows.\n *\n * - `queued`: file is added but not yet sent. Neutral row appearance.\n * - `uploading`: file is in flight. Row shows a progress strip and a\n *   verbose meta line (\"Uploading · 61% of 471.0 KB\"). Caller drives\n *   `progress` (0–1).\n * - `done`: file completed. Document icon swaps to a success check.\n * - `error`: file failed. Border + icon + meta switch to danger styling;\n *   the per-file `errorMessage` replaces the size meta.\n */\nexport type FileStatus = 'queued' | 'uploading' | 'done' | 'error';\n\nexport interface FileUploadFileMeta {\n  /** Stable id for keying + removal callbacks. */\n  id: string;\n  /** Filename to display in the row. */\n  name: string;\n  /** Size in bytes. Formatted for display by the atom. */\n  size: number;\n  /**\n   * Per-file lifecycle status. Defaults to `\"queued\"` if omitted. Drives\n   * the row's icon, meta line, border, and progress strip.\n   */\n  status?: FileStatus;\n  /**\n   * 0–1 progress fraction. Used only when `status === \"uploading\"`.\n   * If omitted during uploading, the row shows an indeterminate state\n   * (\"Uploading…\") and no fraction.\n   */\n  progress?: number;\n  /**\n   * Per-file error message. Used only when `status === \"error\"`.\n   * Replaces the size meta on the row in danger styling.\n   */\n  errorMessage?: string;\n  /**\n   * Direct URL for a stored file. On a `done` row this renders a trailing\n   * control as a real `<a href download>` — which is why it exists alongside\n   * `onOpenFile` rather than being replaced by it: only an anchor gives the\n   * browser's own affordances (⌘/middle-click to a new tab, right-click →\n   * \"Save link as\", the native download UI).\n   *\n   * ⚠️ Use this ONLY when the browser can fetch the URL unauthenticated. A\n   * plain navigation carries no `Authorization` header, so a token-protected\n   * URL returns 401 — reach for `onOpenFile` there.\n   *\n   * ⚠️ The `download` attribute is ignored CROSS-ORIGIN: if the file is\n   * served from another origin the browser navigates to it instead of saving\n   * it. Pass `downloadGlyph=\"arrow-up-right\"` so the control does not promise\n   * a save it cannot perform, or route through `onOpenFile` and a blob.\n   */\n  href?: string;\n}\n\nexport interface FileUploadProps\n  extends Omit<HTMLAttributes<HTMLDivElement>, 'onError' | 'onDragEnter' | 'onDragLeave'> {\n  /**\n   * Forced drop-area visual state — overrides internal drag detection.\n   * The workbench uses this to paint each state without real interaction.\n   * Omit in production: the atom flips to `drag-over` itself while\n   * dragging, and to `error` when `errorMessage` is set.\n   *\n   * Per-file states (uploading / done / per-file errors) are NOT atom-\n   * level — they live on each `FileUploadFileMeta.status`.\n   */\n  state?: FileUploadState;\n  /** Allow selecting more than one file. Defaults to `true`. */\n  multiple?: boolean;\n  /** Standard `<input type=\"file\" accept>` filter, e.g. `\"image/*\"` or `\".pdf,.docx\"`. */\n  accept?: string;\n  /** Disable interaction. Also disables drop and all per-row remove buttons. */\n  disabled?: boolean;\n  /** Heading text inside the drop area. */\n  titleText?: string;\n  /**\n   * Hint line below the title. Falls back to a `multiple`-aware default\n   * (\"Drop files here, or click to browse\" vs \"Drop a file here, or click\n   * to browse\"). When the caller sets `state=\"uploading\"`, the atom\n   * temporarily replaces this with \"Uploading…\" — caller's `helpText`\n   * value is restored once they flip back to default.\n   *\n   * Per-file uploading rows do NOT trigger this swap on their own — the\n   * drop-area copy reflects the caller's declared state, not aggregate\n   * row status. Rows carry their own \"Uploading · 60% of …\" indicators.\n   */\n  helpText?: string;\n  /**\n   * Optional constraint line below the help text — e.g. \"PDF, DOCX · up to\n   * 10 MB\". Caller-controlled copy describing what the page accepts, so it\n   * stays in sync with whatever `accept` filter and validation the page\n   * enforces in `onFiles`. The atom never invents this string — when\n   * omitted, no slot renders. The atom does not enforce anything in it.\n   */\n  allowedTypesText?: string;\n  /**\n   * Page-level error message to render below the drop area (e.g. \"Connection\n   * lost\", \"Server rejected the batch\"). When set, the atom paints the drop\n   * area in the `error` state automatically. Named `error` to match the rest\n   * of the input family's `error?: string`.\n   *\n   * Distinct from per-file errors — set `status: \"error\"` + `errorMessage`\n   * on a `FileUploadFileMeta` to surface a single-file failure inline on\n   * its row instead.\n   */\n  error?: string;\n  /**\n   * @deprecated Renamed to `error` (input-family convention). Still accepted\n   * as an alias for back-compat; `error` wins when both are set.\n   */\n  errorMessage?: string;\n  /**\n   * Files to display in the inline list under the drop area. Rendered\n   * automatically whenever `files.length > 0`. Each entry's `status`\n   * drives its row appearance independently. To render the list elsewhere\n   * on the page, omit `files` and manage that state yourself.\n   */\n  files?: FileUploadFileMeta[];\n  /** Fires with the selected `File[]` whether the user picked via dialog or dropped. */\n  onFiles?: (files: File[]) => void;\n  /**\n   * Fires when a row's remove button is clicked. The caller decides what\n   * \"remove\" means per status — cancel an in-flight upload, drop a queued\n   * file, delete a completed one server-side. The atom doesn't auto-disable\n   * the button during `uploading` so the user always has an escape hatch.\n   */\n  onRemove?: (id: string) => void;\n  /**\n   * Fires when a row's download control is activated. Set this when the\n   * stored file needs an auth header or a signed-URL round trip: the consumer\n   * fetches the bytes itself and saves them (typically `fetch` with the\n   * bearer, then `URL.createObjectURL` — remember to `revokeObjectURL`, and\n   * to pass the filename through, or the file lands named `blob`).\n   *\n   * Takes PRECEDENCE over `FileUploadFileMeta.href`: a consumer that supplied\n   * a handler wants control of what opening means. Set neither and no\n   * download control renders, which is how every existing consumer behaves.\n   */\n  onOpenFile?: (id: string) => void;\n  /**\n   * Glyph for the download control. Defaults to `\"arrow-down\"`. Override to\n   * `\"arrow-up-right\"` when the file opens in a tab rather than saving —\n   * cross-origin `href`, or an `onOpenFile` that previews in-app.\n   */\n  downloadGlyph?: string;\n  /**\n   * Verb in the download control's accessible name, rendered as\n   * `` `${downloadLabel} ${file.name}` ``. Defaults to `\"Download\"`.\n   *\n   * Change it together with `downloadGlyph` whenever the control opens rather\n   * than saves: the glyph alone corrects the promise for sighted users and\n   * leaves screen-reader users being told \"Download\" for a control that\n   * navigates. `downloadLabel=\"Open\"` keeps the two in step.\n   */\n  downloadLabel?: string;\n  /** Fires when a drag enters the drop area. */\n  onDragEnter?: (e: DragEvent<HTMLLabelElement>) => void;\n  /** Fires when a drag leaves the drop area. */\n  onDragLeave?: (e: DragEvent<HTMLLabelElement>) => void;\n  /** Fires when a drop is rejected (e.g. wrong type — for caller-driven validation). */\n  onError?: (reason: string) => void;\n  /** Optional override for the drop-area icon glyph. */\n  iconGlyph?: string;\n  /** Optional slot rendered above the file list (e.g. a summary line). */\n  children?: ReactNode;\n}\n\nexport function FileUpload({\n  state: forcedState,\n  multiple = true,\n  accept,\n  disabled = false,\n  titleText,\n  helpText,\n  allowedTypesText,\n  error,\n  errorMessage,\n  files = [],\n  onFiles,\n  onRemove,\n  onOpenFile,\n  downloadGlyph = 'arrow-down',\n  downloadLabel = 'Download',\n  onDragEnter,\n  onDragLeave,\n  onError: _onError,\n  className,\n  style,\n  iconGlyph = 'cloud-arrow-up',\n  children,\n  ...rest\n}: FileUploadProps) {\n  const inputId = useId();\n  const helpId = useId();\n\n  // Whether the list has a download COLUMN at all — a whole-list property, so\n  // it is computed once here rather than per row (inside the map it re-scanned\n  // `files` for every row, which is O(n²) on exactly the renders a list does\n  // most: one per progress tick during an upload).\n  //\n  // The column exists so the control can be `done`-only without the name column\n  // gaining 24px the moment an upload settles — a reflow of the row the user is\n  // watching. Rows with nothing to fetch render an inert placeholder instead.\n  const listHasDownloads = !!onOpenFile || files.some((f) => !!f.href);\n  const [internalDrag, setInternalDrag] = useState(false);\n\n  // The drop area is intentionally independent of per-file statuses. It\n  // doesn't change copy, busy-state, or cursor automatically based on\n  // whether any row is uploading — the rows speak for themselves via\n  // their own per-row meta + progress strip. The two state spaces stay\n  // orthogonal: caller declares drop-area state explicitly via the\n  // `state` prop, and sets per-file lifecycle via each `file.status`.\n  //\n  // `uploading` here is an explicit drop-area state for cases the rows\n  // can't carry: batch lockouts, pre-file validation, indeterminate\n  // chunked uploads without per-file callbacks. Caller drives it.\n  const isUploading = forcedState === 'uploading';\n\n  // Atom-level error: caller set `error` (or the deprecated `errorMessage`\n  // alias) OR forced state to \"error\". Per-file errors are NOT reflected here —\n  // they're each row's concern.\n  const pageError = error ?? errorMessage;\n  const isPageError = forcedState === 'error' || (!forcedState && !!pageError);\n\n  const dataState: FileUploadState = forcedState\n    ? forcedState\n    : internalDrag\n      ? 'drag-over'\n      : isPageError\n        ? 'error'\n        : 'default';\n\n  const handleChange = useCallback(\n    (e: ChangeEvent<HTMLInputElement>) => {\n      if (disabled) return;\n      const list = e.target.files;\n      if (!list || list.length === 0) return;\n      onFiles?.(Array.from(list));\n      // Clear so re-selecting the same file re-fires onChange.\n      e.target.value = '';\n    },\n    [disabled, onFiles],\n  );\n\n  const handleDragEnter = useCallback(\n    (e: DragEvent<HTMLLabelElement>) => {\n      if (disabled) return;\n      e.preventDefault();\n      setInternalDrag(true);\n      onDragEnter?.(e);\n    },\n    [disabled, onDragEnter],\n  );\n\n  const handleDragOver = useCallback(\n    (e: DragEvent<HTMLLabelElement>) => {\n      if (disabled) return;\n      e.preventDefault();\n    },\n    [disabled],\n  );\n\n  const handleDragLeave = useCallback(\n    (e: DragEvent<HTMLLabelElement>) => {\n      if (disabled) return;\n      e.preventDefault();\n      setInternalDrag(false);\n      onDragLeave?.(e);\n    },\n    [disabled, onDragLeave],\n  );\n\n  const handleDrop = useCallback(\n    (e: DragEvent<HTMLLabelElement>) => {\n      if (disabled) return;\n      e.preventDefault();\n      setInternalDrag(false);\n      const list = e.dataTransfer?.files;\n      if (!list || list.length === 0) return;\n      onFiles?.(Array.from(list));\n    },\n    [disabled, onFiles],\n  );\n\n  const resolvedTitle = titleText ?? 'Upload a file';\n  const baseHelp =\n    helpText ??\n    (multiple\n      ? 'Drop files here, or click to browse'\n      : 'Drop a file here, or click to browse');\n  // The uploading state owns the help slot: it swaps to \"Uploading…\" so\n  // the drop area visibly reflects the caller-declared busy phase. Falls\n  // back to the normal copy in every other state.\n  const resolvedHelp = isUploading ? 'Uploading…' : baseHelp;\n\n  return (\n    <div className={cn('uxm-file-upload-wrapper', className)} style={style} {...rest}>\n      <label\n        className=\"uxm-file-upload\"\n        htmlFor={inputId}\n        data-state={dataState}\n        data-disabled={disabled ? 'true' : undefined}\n        aria-busy={isUploading || undefined}\n        onDragEnter={handleDragEnter}\n        onDragOver={handleDragOver}\n        onDragLeave={handleDragLeave}\n        onDrop={handleDrop}\n      >\n        <input\n          id={inputId}\n          className=\"uxm-file-upload__input\"\n          type=\"file\"\n          multiple={multiple}\n          accept={accept}\n          disabled={disabled}\n          aria-invalid={isPageError || undefined}\n          aria-describedby={helpId}\n          onChange={handleChange}\n        />\n        <span className=\"uxm-file-upload__icon\" aria-hidden=\"true\">\n          <Icon glyph={iconGlyph} size={40} />\n        </span>\n        <span className=\"uxm-file-upload__title\">{resolvedTitle}</span>\n        <span id={helpId} className=\"uxm-file-upload__help\">\n          {resolvedHelp}\n        </span>\n        {allowedTypesText && !isUploading && (\n          <span className=\"uxm-file-upload__allowed-types\">{allowedTypesText}</span>\n        )}\n      </label>\n      {pageError && <span className=\"uxm-file-upload__error\">{pageError}</span>}\n      {children}\n      {files.length > 0 && (\n        <ul className=\"uxm-file-upload__list\">\n          {files.map((file) => {\n            const status: FileStatus = file.status ?? 'queued';\n            const isUploading = status === 'uploading';\n            const isDone = status === 'done';\n            const isFileError = status === 'error';\n            const pctFraction =\n              file.progress != null\n                ? Math.max(0, Math.min(1, file.progress))\n                : undefined;\n            const pctLabel =\n              pctFraction != null ? `${Math.round(pctFraction * 100)}%` : undefined;\n            const pctWidth = pctFraction != null ? `${pctFraction * 100}%` : '0%';\n\n            // Icon glyph + color come from the row's status. Default knobs\n            // (rowIconColor etc.) cover queued/uploading; done + error\n            // route through dedicated vars the CSS reads via [data-status].\n            const iconForRow = isDone\n              ? 'check-circle'\n              : isFileError\n                ? 'exclamation-circle'\n                : 'document';\n\n            // Meta line content swaps with status:\n            //   queued / done  → file size\n            //   uploading      → \"Uploading · 61% of 471.0 KB\" (or \"Uploading…\" if no progress)\n            //   error          → per-file errorMessage (or generic fallback)\n            const sizeLabel = formatBytes(file.size);\n            const metaText = isUploading\n              ? pctLabel != null\n                ? `Uploading · ${pctLabel} of ${sizeLabel}`\n                : 'Uploading…'\n              : isFileError\n                ? file.errorMessage ?? 'Upload failed'\n                : sizeLabel;\n\n            return (\n              <li\n                key={file.id}\n                className=\"uxm-file-upload__row\"\n                data-status={status}\n              >\n                <span className=\"uxm-file-upload__row-icon\" aria-hidden=\"true\">\n                  <Icon glyph={iconForRow} size={20} />\n                </span>\n                <span className=\"uxm-file-upload__row-body\">\n                  <span className=\"uxm-file-upload__row-name\">{file.name}</span>\n                  <span className=\"uxm-file-upload__row-meta\">{metaText}</span>\n                </span>\n                {/* Download / open. `done` only — there is nothing stored to\n                    fetch until the upload settles. `onOpenFile` wins over\n                    `href` so a consumer that needs an auth header or a signed\n                    URL is never silently downgraded to a bare navigation. */}\n                {listHasDownloads &&\n                  (isDone && (onOpenFile || file.href) ? (\n                    onOpenFile ? (\n                      <button\n                        type=\"button\"\n                        className=\"uxm-file-upload__row-download\"\n                        aria-label={`${downloadLabel} ${file.name}`}\n                        disabled={disabled}\n                        onClick={() => onOpenFile(file.id)}\n                      >\n                        <Icon glyph={downloadGlyph} size={16} />\n                      </button>\n                    ) : (\n                      // eslint-disable-next-line jsx-a11y/anchor-is-valid -- `href` is dropped ONLY while `disabled`, which is the point: an anchor that keeps its href stays focusable and Enter still follows it, so a disabled control would remain usable from the keyboard. The rule cannot model a conditionally-inert anchor; when enabled this always has a valid href.\n                      <a\n                        className=\"uxm-file-upload__row-download\"\n                        // DROPPED while disabled, not merely styled out. An\n                        // anchor keeps `href` in the tab order and Enter still\n                        // follows it, so `pointer-events: none` disables only\n                        // the mouse — a keyboard user could still download from\n                        // a form the consumer switched off. Without `href` the\n                        // element is neither focusable nor a link.\n                        href={disabled ? undefined : file.href}\n                        // Names the saved file: without this the browser uses\n                        // the URL's last segment, so a storage key lands on\n                        // disk as a UUID. Ignored cross-origin, along with the\n                        // download behaviour itself — see `href`'s docs.\n                        download={file.name}\n                        // Cross-origin, `download` is ignored and this becomes a\n                        // real navigation — into a NEW tab, so the user does not\n                        // lose the app and whatever is unsaved beside the list.\n                        // Same-origin the `download` attribute wins and no tab\n                        // opens, so this costs nothing there. It is also what\n                        // makes `rel=\"noopener\"` mean anything.\n                        target=\"_blank\"\n                        rel=\"noopener noreferrer\"\n                        aria-label={`${downloadLabel} ${file.name}`}\n                        aria-disabled={disabled || undefined}\n                      >\n                        <Icon glyph={downloadGlyph} size={16} />\n                      </a>\n                    )\n                  ) : (\n                    // Inert placeholder keeping the column width stable across\n                    // the uploading → done transition.\n                    <span className=\"uxm-file-upload__row-download-slot\" aria-hidden=\"true\" />\n                  ))}\n                <button\n                  type=\"button\"\n                  className=\"uxm-file-upload__row-remove\"\n                  aria-label={\n                    isUploading ? `Cancel ${file.name}` : `Remove ${file.name}`\n                  }\n                  disabled={disabled}\n                  onClick={() => onRemove?.(file.id)}\n                >\n                  <Icon glyph=\"trash\" size={16} />\n                </button>\n                {isUploading && (\n                  <span\n                    className=\"uxm-file-upload__row-progress\"\n                    style={\n                      { '--uxm-file-upload-row-progress': pctWidth } as CSSProperties\n                    }\n                    role=\"progressbar\"\n                    aria-valuenow={pctFraction != null ? Math.round(pctFraction * 100) : undefined}\n                    aria-valuemin={0}\n                    aria-valuemax={100}\n                  />\n                )}\n              </li>\n            );\n          })}\n        </ul>\n      )}\n    </div>\n  );\n}\n\nfunction formatBytes(bytes: number): string {\n  if (bytes < 1024) return `${bytes} B`;\n  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;\n  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;\n  return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;\n}\n"],"mappings":"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","names":["isUploading"]}

package/dist/ui/file-upload/file-upload.css

@@ -0,0 +1,330 @@
+@charset "UTF-8";
+/* ── File Upload ──
+   File-upload atom with two interaction modes (click anywhere on the label
+   opens the picker; drop fires onFiles). State is driven by a
+   `[data-state="…"]` attribute the component writes onto the root — the
+   workbench forces a value via the `state` prop, while production usage
+   lets the component flip itself to `drag-over` during drag.
+
+   Why data-state instead of `--state-X` modifier classes (input-text style):
+   seven states + the inner-styled file-row family read cleaner as attribute
+   selectors. CSS specificity stays predictable because every state rule
+   uses a single attribute selector, so source order resolves layering
+   (default < hover < drag-over/uploading/error < disabled).
+
+   Focus indication is wired via `:focus-within` on the label — the hidden
+   `<input type="file">` owns keyboard focus (it's visually-hidden but
+   focusable), and the visible label paints the focus ring on its behalf.
+   That's what lets Enter / Space activate the picker natively, no custom
+   key handler needed. */
+.uxm-file-upload-wrapper {
+  display: flex;
+  flex-direction: column;
+  gap: var(--uxm-file-upload-wrapper-gap, 10px);
+  width: 100%;
+}
+
+.uxm-file-upload {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  gap: var(--uxm-file-upload-gap, 8px);
+  background-color: var(--uxm-file-upload-bg, var(--color-card));
+  color: var(--uxm-file-upload-color, var(--color-text));
+  border: var(--uxm-file-upload-border-width, 1.5px) var(--uxm-file-upload-border-style, dashed) var(--uxm-file-upload-border-color, var(--color-border));
+  border-radius: var(--uxm-file-upload-border-radius, 12px);
+  padding: var(--uxm-file-upload-padding-y, 24px) var(--uxm-file-upload-padding-x, 24px);
+  min-height: var(--uxm-file-upload-min-height, 160px);
+  cursor: pointer;
+  transition: border-color 0.15s ease, background-color 0.15s ease, color 0.15s ease;
+}
+
+/* Visually-hidden but focusable file input.
+   Clip-path (not display:none) keeps Tab focus working — pressing
+   Enter/Space then dispatches a click to the surrounding <label>,
+   which opens the file picker natively. */
+.uxm-file-upload__input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+.uxm-file-upload__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--uxm-file-upload-icon-color, var(--color-accent));
+}
+
+.uxm-file-upload__icon > svg {
+  width: var(--uxm-file-upload-icon-size, 40px);
+  height: var(--uxm-file-upload-icon-size, 40px);
+}
+
+.uxm-file-upload__title {
+  font-size: calc(var(--uxm-file-upload-title-size, 15px) * var(--type-scale, 1));
+  font-weight: 600;
+  color: var(--uxm-file-upload-color, var(--color-text-strong));
+}
+
+.uxm-file-upload__help {
+  font-size: calc(var(--uxm-file-upload-help-size, 13px) * var(--type-scale, 1));
+  color: var(--uxm-file-upload-help-color, var(--color-text-muted));
+}
+
+/* Allowed-types line — caller-controlled constraint copy (e.g. "PDF,
+   DOCX · up to 10 MB"). Renders only when the caller passes a value;
+   visually subordinate to help text (smaller, muted). */
+.uxm-file-upload__allowed-types {
+  font-size: calc(var(--uxm-file-upload-allowed-types-size, 11px) * var(--type-scale, 1));
+  color: var(--uxm-file-upload-allowed-types-color, var(--color-text-subtle, var(--color-text-muted)));
+  letter-spacing: 0.01em;
+}
+
+/* Hover — paints only when not forced into a different state. The
+   `:not([data-state])` guard isn't strictly needed since forced-state
+   selectors have equal specificity and follow this rule in source
+   order, but the explicit data-state="hover" rule below covers the
+   forced case identically. */
+.uxm-file-upload:hover,
+.uxm-file-upload[data-state=hover] {
+  background-color: var(--uxm-file-upload-hover-bg, var(--color-card));
+  border-color: var(--uxm-file-upload-hover-border, var(--color-accent));
+}
+
+/* Drag-over — overlay-style override: only the surface colors change, so
+   geometry / paddings / typography don't shift when files are dragged in. */
+.uxm-file-upload[data-state=drag-over] {
+  background-color: var(--uxm-file-upload-drag-bg, color-mix(in srgb, var(--color-accent) 8%, var(--color-card)));
+  border-color: var(--uxm-file-upload-drag-border, var(--color-accent));
+  border-style: var(--uxm-file-upload-drag-border-style, solid);
+}
+
+.uxm-file-upload[data-state=drag-over] .uxm-file-upload__icon {
+  color: var(--uxm-file-upload-drag-accent, var(--color-accent));
+}
+
+/* Focus — :focus-within paints the visible label when the (hidden) input
+   takes keyboard focus. data-state="focus" mirrors it for the forced case. */
+.uxm-file-upload:focus-within,
+.uxm-file-upload[data-state=focus] {
+  border-color: var(--uxm-file-upload-focus-border, var(--color-accent));
+  outline: 2px solid var(--uxm-file-upload-focus-ring, var(--color-accent));
+  outline-offset: 2px;
+}
+
+/* Uploading — explicit caller-driven drop-area state (NOT auto-derived
+   from per-file `status`). Used for page-level signals: batch lockouts,
+   pre-file validation, indeterminate chunked uploads. The cursor change
+   is the only visual difference beyond the help-text swap done in JSX. */
+.uxm-file-upload[data-state=uploading] {
+  cursor: progress;
+}
+
+/* Error — surface tone + standalone message slot below the drop area. */
+.uxm-file-upload[data-state=error] {
+  background-color: var(--uxm-file-upload-error-bg, var(--color-card));
+  border-color: var(--uxm-file-upload-error-border, var(--color-danger-text));
+}
+
+.uxm-file-upload__error {
+  font-size: calc(var(--uxm-file-upload-error-message-size, 12px) * var(--type-scale, 1));
+  color: var(--uxm-file-upload-error-color, var(--color-danger-text));
+}
+
+/* Disabled — `data-disabled` attribute on the label, since the label
+   itself can't carry `:disabled` (that's an input pseudo). */
+.uxm-file-upload[data-disabled=true] {
+  opacity: var(--uxm-file-upload-disabled-opacity, 0.6);
+  cursor: not-allowed;
+  background-color: var(--uxm-file-upload-disabled-bg, var(--color-surface-alt));
+  border-color: var(--uxm-file-upload-disabled-border, var(--color-border));
+  color: var(--uxm-file-upload-disabled-color, var(--color-text-muted));
+}
+
+.uxm-file-upload[data-disabled=true] .uxm-file-upload__icon {
+  color: var(--uxm-file-upload-disabled-color, var(--color-text-muted));
+}
+
+/* Inline file list — rendered automatically whenever `files.length > 0`.
+   Each row paints from its own `[data-status]` attribute (queued /
+   uploading / done / error), independently of the other rows. The
+   trash button is always enabled (during uploading, the caller can treat
+   the click as a cancel signal). */
+.uxm-file-upload__list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--uxm-file-upload-row-gap, 6px);
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.uxm-file-upload__row {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  background-color: var(--uxm-file-upload-row-bg, var(--color-surface));
+  border: 1px solid var(--uxm-file-upload-row-border, var(--color-border));
+  border-radius: var(--uxm-file-upload-row-radius, 8px);
+  padding: var(--uxm-file-upload-row-padding-y, 8px) var(--uxm-file-upload-row-padding-x, 12px);
+  overflow: hidden;
+}
+
+.uxm-file-upload__row-icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  color: var(--uxm-file-upload-row-icon-color, var(--color-accent));
+}
+
+.uxm-file-upload__row-body {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.uxm-file-upload__row-name {
+  font-size: calc(13px * var(--type-scale, 1));
+  font-weight: 500;
+  color: var(--uxm-file-upload-row-name-color, var(--color-text-strong));
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.uxm-file-upload__row-meta {
+  font-size: calc(11px * var(--type-scale, 1));
+  color: var(--uxm-file-upload-row-meta-color, var(--color-text-muted));
+}
+
+.uxm-file-upload__row-remove {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  color: var(--uxm-file-upload-remove-icon-color, var(--color-text-muted));
+  cursor: pointer;
+  flex-shrink: 0;
+  transition: background-color 0.15s ease, color 0.15s ease;
+}
+
+.uxm-file-upload__row-remove:hover:not(:disabled) {
+  background-color: color-mix(in srgb, var(--color-text) 8%, transparent);
+  color: var(--uxm-file-upload-remove-icon-hover-color, var(--color-danger-text));
+}
+
+.uxm-file-upload__row-remove:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Download / open control. Same 24px box as the remove button so the two sit
+   as one control cluster, but it tints toward the accent on hover rather than
+   danger — one takes the file away, the other hands it over.
+
+   `.uxm-file-upload__row-download` is BOTH a <button> and an <a> depending on
+   whether the consumer passed `onOpenFile` or `href`, so everything here has
+   to hold for an anchor too: `text-decoration: none` (an anchor is underlined
+   by default) and an explicit `color` (an anchor would otherwise paint itself
+   the UA's link blue, ignoring the token). */
+.uxm-file-upload__row-download {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  text-decoration: none;
+  color: var(--uxm-file-upload-download-icon-color, var(--color-text-muted));
+  cursor: pointer;
+  flex-shrink: 0;
+  transition: background-color 0.15s ease, color 0.15s ease;
+}
+
+.uxm-file-upload__row-download:hover:not(:disabled):not([aria-disabled=true]) {
+  background-color: color-mix(in srgb, var(--color-text) 8%, transparent);
+  color: var(--uxm-file-upload-download-icon-hover-color, var(--color-accent));
+}
+
+/* The anchor form cannot carry `disabled`, so the disabled visual keys off
+   `aria-disabled` — which is also what tells assistive tech.
+   Disabling is NOT done here: the atom drops the anchor's `href` instead, which
+   takes it out of the tab order and stops Enter following it. CSS could only
+   ever have blocked the mouse (`pointer-events: none`), which is why that
+   declaration is gone — it also suppressed hit-testing entirely, so the
+   `cursor` below never painted. */
+.uxm-file-upload__row-download:disabled,
+.uxm-file-upload__row-download[aria-disabled=true] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Reserves the column on rows that have no file to fetch yet, so the name
+   column does not jump 24px wide when an upload settles. */
+.uxm-file-upload__row-download-slot {
+  display: inline-block;
+  width: 24px;
+  height: 24px;
+  flex-shrink: 0;
+}
+
+.uxm-file-upload__row-progress {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  height: var(--uxm-file-upload-progress-height, 2px);
+  width: var(--uxm-file-upload-row-progress, 0%);
+  background-color: var(--uxm-file-upload-progress-fill, var(--color-accent));
+  transition: width 0.2s ease;
+}
+
+/* Per-row status overrides — applied via the `[data-status]` attribute the
+   atom writes onto each <li>. Queued is the default and needs no override.
+   Done swaps the icon color to a success tint. Error flips the row's
+   border + icon + meta to danger styling. The base row geometry (radius,
+   padding, gap, name color) stays identical across statuses so the rows
+   align visually. */
+/* Done — full state-card treatment: success bg tint + success border.
+   Symmetric with error so the two "decided" statuses (done / error) get
+   the same kind of signal, just with opposite-color semantics. */
+.uxm-file-upload__row[data-status=done] {
+  background-color: var(--uxm-file-upload-row-done-bg, var(--color-success-bg));
+  border-color: var(--uxm-file-upload-row-done-border-color, var(--color-success-border));
+}
+
+.uxm-file-upload__row[data-status=done] .uxm-file-upload__row-icon {
+  color: var(--uxm-file-upload-row-done-icon-color, var(--color-success-text, var(--color-accent)));
+}
+
+/* Error — full state-card treatment: danger bg tint + danger border. */
+.uxm-file-upload__row[data-status=error] {
+  background-color: var(--uxm-file-upload-row-error-bg, var(--color-danger-bg));
+  border-color: var(--uxm-file-upload-row-error-border-color, var(--color-danger-border, var(--color-danger-text)));
+}
+
+.uxm-file-upload__row[data-status=error] .uxm-file-upload__row-icon {
+  color: var(--uxm-file-upload-row-error-icon-color, var(--color-danger-text));
+}
+
+.uxm-file-upload__row[data-status=error] .uxm-file-upload__row-meta {
+  color: var(--uxm-file-upload-row-error-meta-color, var(--color-danger-text));
+}

package/dist/ui/file-upload/file-upload.d.ts

@@ -0,0 +1,184 @@
+import { type DragEvent, type HTMLAttributes, type ReactNode } from 'react';
+/**
+ * Visual states the FileUpload **drop area** can be forced into via the
+ * `state` prop. These describe the drop area surface only — not per-file
+ * lifecycle. Per-file states (queued / uploading / done / error) live on
+ * each `FileUploadFileMeta.status` and render row-by-row independently.
+ *
+ * `uploading` is **caller-controlled** — the atom never sets it from per-
+ * file statuses. Use it for page-level signals: a batch is being prepared
+ * before per-file rows exist, a chunked upload with no per-file progress,
+ * or any "the system is busy with this dropzone" state the caller wants
+ * to surface. Per-row uploading rows remain the *primary* progress signal.
+ *
+ * `error` means a *page-level* error (e.g. "Connection lost", "Server
+ * rejected the batch") — surfaced via the `errorMessage` prop and shown
+ * below the drop area. Per-file errors don't change the drop area's state.
+ */
+export type FileUploadState = 'default' | 'drag-over' | 'uploading' | 'error';
+/**
+ * Per-file lifecycle status. The atom paints each row based on its own
+ * status independently of other rows.
+ *
+ * - `queued`: file is added but not yet sent. Neutral row appearance.
+ * - `uploading`: file is in flight. Row shows a progress strip and a
+ *   verbose meta line ("Uploading · 61% of 471.0 KB"). Caller drives
+ *   `progress` (0–1).
+ * - `done`: file completed. Document icon swaps to a success check.
+ * - `error`: file failed. Border + icon + meta switch to danger styling;
+ *   the per-file `errorMessage` replaces the size meta.
+ */
+export type FileStatus = 'queued' | 'uploading' | 'done' | 'error';
+export interface FileUploadFileMeta {
+    /** Stable id for keying + removal callbacks. */
+    id: string;
+    /** Filename to display in the row. */
+    name: string;
+    /** Size in bytes. Formatted for display by the atom. */
+    size: number;
+    /**
+     * Per-file lifecycle status. Defaults to `"queued"` if omitted. Drives
+     * the row's icon, meta line, border, and progress strip.
+     */
+    status?: FileStatus;
+    /**
+     * 0–1 progress fraction. Used only when `status === "uploading"`.
+     * If omitted during uploading, the row shows an indeterminate state
+     * ("Uploading…") and no fraction.
+     */
+    progress?: number;
+    /**
+     * Per-file error message. Used only when `status === "error"`.
+     * Replaces the size meta on the row in danger styling.
+     */
+    errorMessage?: string;
+    /**
+     * Direct URL for a stored file. On a `done` row this renders a trailing
+     * control as a real `<a href download>` — which is why it exists alongside
+     * `onOpenFile` rather than being replaced by it: only an anchor gives the
+     * browser's own affordances (⌘/middle-click to a new tab, right-click →
+     * "Save link as", the native download UI).
+     *
+     * ⚠️ Use this ONLY when the browser can fetch the URL unauthenticated. A
+     * plain navigation carries no `Authorization` header, so a token-protected
+     * URL returns 401 — reach for `onOpenFile` there.
+     *
+     * ⚠️ The `download` attribute is ignored CROSS-ORIGIN: if the file is
+     * served from another origin the browser navigates to it instead of saving
+     * it. Pass `downloadGlyph="arrow-up-right"` so the control does not promise
+     * a save it cannot perform, or route through `onOpenFile` and a blob.
+     */
+    href?: string;
+}
+export interface FileUploadProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onError' | 'onDragEnter' | 'onDragLeave'> {
+    /**
+     * Forced drop-area visual state — overrides internal drag detection.
+     * The workbench uses this to paint each state without real interaction.
+     * Omit in production: the atom flips to `drag-over` itself while
+     * dragging, and to `error` when `errorMessage` is set.
+     *
+     * Per-file states (uploading / done / per-file errors) are NOT atom-
+     * level — they live on each `FileUploadFileMeta.status`.
+     */
+    state?: FileUploadState;
+    /** Allow selecting more than one file. Defaults to `true`. */
+    multiple?: boolean;
+    /** Standard `<input type="file" accept>` filter, e.g. `"image/*"` or `".pdf,.docx"`. */
+    accept?: string;
+    /** Disable interaction. Also disables drop and all per-row remove buttons. */
+    disabled?: boolean;
+    /** Heading text inside the drop area. */
+    titleText?: string;
+    /**
+     * Hint line below the title. Falls back to a `multiple`-aware default
+     * ("Drop files here, or click to browse" vs "Drop a file here, or click
+     * to browse"). When the caller sets `state="uploading"`, the atom
+     * temporarily replaces this with "Uploading…" — caller's `helpText`
+     * value is restored once they flip back to default.
+     *
+     * Per-file uploading rows do NOT trigger this swap on their own — the
+     * drop-area copy reflects the caller's declared state, not aggregate
+     * row status. Rows carry their own "Uploading · 60% of …" indicators.
+     */
+    helpText?: string;
+    /**
+     * Optional constraint line below the help text — e.g. "PDF, DOCX · up to
+     * 10 MB". Caller-controlled copy describing what the page accepts, so it
+     * stays in sync with whatever `accept` filter and validation the page
+     * enforces in `onFiles`. The atom never invents this string — when
+     * omitted, no slot renders. The atom does not enforce anything in it.
+     */
+    allowedTypesText?: string;
+    /**
+     * Page-level error message to render below the drop area (e.g. "Connection
+     * lost", "Server rejected the batch"). When set, the atom paints the drop
+     * area in the `error` state automatically. Named `error` to match the rest
+     * of the input family's `error?: string`.
+     *
+     * Distinct from per-file errors — set `status: "error"` + `errorMessage`
+     * on a `FileUploadFileMeta` to surface a single-file failure inline on
+     * its row instead.
+     */
+    error?: string;
+    /**
+     * @deprecated Renamed to `error` (input-family convention). Still accepted
+     * as an alias for back-compat; `error` wins when both are set.
+     */
+    errorMessage?: string;
+    /**
+     * Files to display in the inline list under the drop area. Rendered
+     * automatically whenever `files.length > 0`. Each entry's `status`
+     * drives its row appearance independently. To render the list elsewhere
+     * on the page, omit `files` and manage that state yourself.
+     */
+    files?: FileUploadFileMeta[];
+    /** Fires with the selected `File[]` whether the user picked via dialog or dropped. */
+    onFiles?: (files: File[]) => void;
+    /**
+     * Fires when a row's remove button is clicked. The caller decides what
+     * "remove" means per status — cancel an in-flight upload, drop a queued
+     * file, delete a completed one server-side. The atom doesn't auto-disable
+     * the button during `uploading` so the user always has an escape hatch.
+     */
+    onRemove?: (id: string) => void;
+    /**
+     * Fires when a row's download control is activated. Set this when the
+     * stored file needs an auth header or a signed-URL round trip: the consumer
+     * fetches the bytes itself and saves them (typically `fetch` with the
+     * bearer, then `URL.createObjectURL` — remember to `revokeObjectURL`, and
+     * to pass the filename through, or the file lands named `blob`).
+     *
+     * Takes PRECEDENCE over `FileUploadFileMeta.href`: a consumer that supplied
+     * a handler wants control of what opening means. Set neither and no
+     * download control renders, which is how every existing consumer behaves.
+     */
+    onOpenFile?: (id: string) => void;
+    /**
+     * Glyph for the download control. Defaults to `"arrow-down"`. Override to
+     * `"arrow-up-right"` when the file opens in a tab rather than saving —
+     * cross-origin `href`, or an `onOpenFile` that previews in-app.
+     */
+    downloadGlyph?: string;
+    /**
+     * Verb in the download control's accessible name, rendered as
+     * `` `${downloadLabel} ${file.name}` ``. Defaults to `"Download"`.
+     *
+     * Change it together with `downloadGlyph` whenever the control opens rather
+     * than saves: the glyph alone corrects the promise for sighted users and
+     * leaves screen-reader users being told "Download" for a control that
+     * navigates. `downloadLabel="Open"` keeps the two in step.
+     */
+    downloadLabel?: string;
+    /** Fires when a drag enters the drop area. */
+    onDragEnter?: (e: DragEvent<HTMLLabelElement>) => void;
+    /** Fires when a drag leaves the drop area. */
+    onDragLeave?: (e: DragEvent<HTMLLabelElement>) => void;
+    /** Fires when a drop is rejected (e.g. wrong type — for caller-driven validation). */
+    onError?: (reason: string) => void;
+    /** Optional override for the drop-area icon glyph. */
+    iconGlyph?: string;
+    /** Optional slot rendered above the file list (e.g. a summary line). */
+    children?: ReactNode;
+}
+export declare function FileUpload({ state: forcedState, multiple, accept, disabled, titleText, helpText, allowedTypesText, error, errorMessage, files, onFiles, onRemove, onOpenFile, downloadGlyph, downloadLabel, onDragEnter, onDragLeave, onError: _onError, className, style, iconGlyph, children, ...rest }: FileUploadProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=file-upload.d.ts.map

package/dist/ui/file-upload/file-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-upload.d.ts","sourceRoot":"","sources":["../../../src/ui/file-upload/file-upload.tsx"],"names":[],"mappings":"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"}