@multiplatform.one/forms 7.4.1 → 7.6.0

package/src/fields/FileUpload/index.tsx

@@ -1,8 +1,8 @@
 import { FileIcon, UploadIcon, XIcon } from "@phosphor-icons/react";
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
-import { type DragEvent, useCallback, useEffect, useRef, useState } from "react";
+import { type DragEvent, type ReactNode, useCallback, useEffect, useRef, useState } from "react";
 import { useProps, type SizeTokens } from "tamagui";
-import { Image, isWeb, Paragraph, Text, XStack, YStack, styled } from "tamagui";
+import { Image, isWeb, Text, XStack, YStack, styled } from "tamagui";
 import { Button } from "../../Button";
 import { Field, FieldLayout } from "../../fieldLayout";
 import { Skeleton } from "../../Skeleton";
@@ -20,9 +20,36 @@ import {
   ensureKeyboardModalityTracking,
   wasKeyboardFocus,
 } from "@multiplatform.one/theme";
-import { formCommonColors, formInputColors } from "../../shared/colorRamps";
+import { formCommonColors, formDropzoneColors, formInputColors } from "../../shared/colorRamps";
 import { t } from "../../shared/t";
 import type { FieldComponentProps, Validator } from "../../types";
+import type { NativePickedFile, NativePickerMode } from "./filePickerTypes";
+// Platform-split: the web twin is inert, the `.native` twin opens
+// expo-document-picker / expo-image-picker (Geolocation map-surface pattern).
+import { pickFilesNatively } from "./nativeFilePicker";
+
+/** Structured per-file transport error (DG-VAL-04). */
+export type FileTransferError = {
+  problem: string;
+  action: string;
+  cta?: string;
+};
+
+export type FileUploadHandler = (
+  file: File,
+  ctx: { onProgress: (percent: number) => void; signal: AbortSignal },
+) => Promise<void>;
+
+type TransferStatus = "uploading" | "failed";
+
+type TransferItem = {
+  id: string;
+  file: File;
+  status: TransferStatus;
+  progress: number;
+  error?: FileTransferError;
+  controller: AbortController;
+};
 
 export type FileUploadProps<
   TParentData = any,
@@ -50,6 +77,14 @@ export type FileUploadProps<
     buttonText?: string;
     onFileSelect?: (files: FileList | null) => void;
     onFileRemove?: (file: File) => void;
+    /**
+     * Transport. When set, a chosen file enters the uploading row (name,
+     * size, progress, cancel) and only joins the committed list when this
+     * resolves. A rejection keeps the file visible with retry + remove
+     * (DG-VAL-04 / DG-VAL-05) and does not clear siblings. Omit to commit
+     * immediately — there is no transport.
+     */
+    onUpload?: FileUploadHandler;
     /**
      * Canonical change handler, consistent with the rest of the field family.
      * Fires in both standalone and form mode. Prefer this over `onValueChange`.
@@ -57,10 +92,22 @@ export type FileUploadProps<
     onChange?: (value: TData) => void;
     /** @deprecated Use `onChange` instead. */
     onValueChange?: (value: TData) => void;
+    /**
+     * Which native picker the field opens (no effect on web, which always
+     * uses `<input type="file">`). `auto` sends an image-only `accept` to the
+     * photo library and everything else to the document browser.
+     * @default "auto"
+     */
+    pickerMode?: NativePickerMode;
     /** When true, renders a skeleton placeholder instead of the file upload */
     skeleton?: boolean;
     /** When true, applies compact density (tighter layout gaps; control size unchanged) */
     compact?: boolean;
+    /**
+     * Extra controls in the CTA row (Attach "From Library"). The dropzone
+     * stays the OS-picker target (LC-23); these are the carve-out children.
+     */
+    actions?: ReactNode;
   };
 
 const UploadAreaFrame = styled(YStack, {
@@ -68,8 +115,15 @@ const UploadAreaFrame = styled(YStack, {
   position: "relative",
   overflow: "hidden",
   borderStyle: "dashed",
-  backgroundColor: formInputColors.background.base,
-  borderColor: formInputColors.border.base,
+  // BENTO-DERIVED (bento-pickers-measured.md §2/§4, MPO-57): the zone ground
+  // is TRANSPARENT — the page shows through and the dashed edge is the whole
+  // control. Only the LC-40 disabled wash paints the ground at rest; the
+  // hover/drag $color4 flood is a held mpo state, not a ground.
+  backgroundColor: "transparent",
+  // The dash is the legible $color9 step (boards media-01..04: 1px dashed
+  // rgb(77,77,77) light / rgb(133,133,133) dark) — formInputColors.border.base
+  // ($borderColor) measured near-invisible as a dashed edge.
+  borderColor: formDropzoneColors.border,
   // LC-71: kill UA :focus-visible on the dropzone. House ring is painted
   // only on keyboard-origin focus via wasKeyboardFocus() below — never the
   // 1px browser outline (forms-fileupload--standalone audit Cluster C).
@@ -77,15 +131,24 @@ const UploadAreaFrame = styled(YStack, {
   outlineStyle: "none" as any,
   focusStyle: { outlineWidth: 0, outlineStyle: "none" as any },
   focusVisibleStyle: { outlineWidth: 0, outlineStyle: "none" as any },
-  variants: {
-    outlined: {
-      true: {
-        backgroundColor: "transparent",
-      },
-    },
-  } as const,
 });
 
+/**
+ * The house ring, applied so it survives the frame's own LC-71 kill.
+ *
+ * The kill above is what suppresses the 1px UA outline on a POINTER focus,
+ * and it has to stay. But it is a `:focus-visible` rule, and a keyboard-origin
+ * focus matches `:focus-visible` too — so spreading the ring as base props
+ * only loses on specificity and the zone paints no ring at all. Restating the
+ * same fragment in `focusStyle`/`focusVisibleStyle` beats the kill in exactly
+ * the state that should carry a ring, and leaves pointer focus alone (the
+ * caller only spreads this while `kbZoneFocus` is true).
+ */
+function withZoneFocusRing() {
+  const ring = ensureFocusVisibleRing({ outlineOffset: 0 });
+  return { ...ring, focusStyle: ring, focusVisibleStyle: ring };
+}
+
 const DropOverlayFrame = styled(YStack, {
   position: "absolute",
   top: 0,
@@ -101,10 +164,14 @@ const DropOverlayFrame = styled(YStack, {
   borderColor: formInputColors.border.focus,
 });
 
+// Bento: picked files live IN the zone, parted by the SAME dashed hairline
+// as the frame edge — the solid 1px $color8 divider was the pre-Bento
+// residue (bento-pickers-measured.md §5).
 const UploadFileListFrame = styled(YStack, {
   width: "100%",
   borderTopWidth: 1,
-  borderTopColor: formCommonColors.divider,
+  borderStyle: "dashed",
+  borderTopColor: formDropzoneColors.border,
 });
 
 export function FileUpload<
@@ -122,12 +189,15 @@ export function FileUpload<
     multiple = false,
     dragDrop = true,
     showPreview = true,
-    placeholder = t("or drag and drop"),
+    // Bento caption on web; native has nothing to drag so the same slot is the tap hint.
+    placeholder = isWeb ? t("Drag a file into this area") : t("or tap to browse"),
     buttonText = t("Choose File"),
     onFileSelect,
     onFileRemove,
+    onUpload,
     onChange: onChangeProp,
     onValueChange: onValueChangeProp,
+    pickerMode = "auto",
     mode,
     name,
     preserveValue,
@@ -136,6 +206,7 @@ export function FileUpload<
     readOnly,
     skeleton,
     compact,
+    actions,
     id: idProp,
     ...fieldProps
   } = useProps(props);
@@ -165,14 +236,38 @@ export function FileUpload<
   // Intentional: extract raw radius token to pass to clampRadiusForLargeComponent utility function.
   // The utility needs the token string (e.g. "$4") to clamp it, not a fragment.
   const cappedRadius = clampRadiusForLargeComponent(knobProps.borderRadius.borderRadius);
+  // Intentional: extract the nested-chrome step (32 at medium) for the row
+  // thumb/glyph boxes — in-zone previews are nested chrome, not press
+  // targets, so they take the px without the fragment's hitSlop. LC-76 keeps
+  // compact a space-only dial, so the old `compact ? 24 : 32` size fork drops.
+  const rowMediaPx = knobProps.nestedControl.px;
+  // Intentional: extract the recipe icon step (16 at the 44 control) for the
+  // row file glyph — same held "icon 16" exception the CTA carries.
+  const rowGlyphSize = knobProps.controlIcon.width;
 
   const [selectedFiles, setSelectedFiles] = useState<File[]>([]);
+  const [transfers, setTransfers] = useState<TransferItem[]>([]);
   const [isDragOver, setIsDragOver] = useState(false);
   const [validationError, setValidationError] = useState<string | undefined>();
   const fileInputRef = useRef<HTMLInputElement>(null);
   const zoneCleanupRef = useRef<(() => void) | null>(null);
   const lastZoneInputWasKeyboardRef = useRef(false);
   const previewUrlsRef = useRef(new Map<File, string>());
+  const transferSeqRef = useRef(0);
+  const transfersRef = useRef<TransferItem[]>([]);
+  const onUploadRef = useRef(onUpload);
+  onUploadRef.current = onUpload;
+  const emitFieldRef = useRef<((nextValue: TData) => void) | undefined>(undefined);
+  const multipleRef = useRef(multiple);
+  multipleRef.current = multiple;
+
+  const setTransfersAndRef = useCallback((updater: (prev: TransferItem[]) => TransferItem[]) => {
+    setTransfers((prev) => {
+      const next = updater(prev);
+      transfersRef.current = next;
+      return next;
+    });
+  }, []);
 
   useEffect(() => {
     if (!isWeb) return;
@@ -190,6 +285,7 @@ export function FileUpload<
       document.removeEventListener("pointerdown", onPointer, true);
       previewUrlsRef.current.forEach((url) => URL.revokeObjectURL(url));
       previewUrlsRef.current.clear();
+      transfersRef.current.forEach((item) => item.controller.abort());
       zoneCleanupRef.current?.();
       zoneCleanupRef.current = null;
     };
@@ -237,6 +333,120 @@ export function FileUpload<
     [multiple],
   );
 
+  const runTransfer = useCallback(
+    async (id: string, file: File, controller: AbortController) => {
+      const upload = onUploadRef.current;
+      if (!upload) return;
+      try {
+        await upload(file, {
+          onProgress: (percent) => {
+            const n = Math.min(100, Math.max(0, Math.round(Number(percent) || 0)));
+            setTransfersAndRef((prev) =>
+              prev.map((item) => (item.id === id ? { ...item, progress: n } : item)),
+            );
+          },
+          signal: controller.signal,
+        });
+        if (controller.signal.aborted) return;
+        setTransfersAndRef((prev) => prev.filter((item) => item.id !== id));
+        setSelectedFiles((prev) => {
+          const nextFiles = multipleRef.current ? [...prev, file] : [file];
+          syncFieldValue(nextFiles, emitFieldRef.current);
+          return nextFiles;
+        });
+      } catch (err) {
+        if (
+          controller.signal.aborted ||
+          (err instanceof DOMException && err.name === "AbortError")
+        ) {
+          setTransfersAndRef((prev) => prev.filter((item) => item.id !== id));
+          return;
+        }
+        const problem = err instanceof Error && err.message ? err.message : t("Upload failed");
+        setTransfersAndRef((prev) =>
+          prev.map((item) =>
+            item.id === id
+              ? {
+                  ...item,
+                  status: "failed" as const,
+                  error: {
+                    problem,
+                    action: t("Try again or remove the file"),
+                    cta: t("Retry"),
+                  },
+                }
+              : item,
+          ),
+        );
+      }
+    },
+    [setTransfersAndRef, syncFieldValue],
+  );
+
+  const startTransfer = useCallback(
+    (file: File) => {
+      if (!multipleRef.current) {
+        transfersRef.current.forEach((item) => item.controller.abort());
+        setTransfersAndRef(() => []);
+      }
+      const id = `xfer-${++transferSeqRef.current}`;
+      const controller = new AbortController();
+      const item: TransferItem = {
+        id,
+        file,
+        status: "uploading",
+        progress: 0,
+        controller,
+      };
+      setTransfersAndRef((prev) => [...prev, item]);
+      void runTransfer(id, file, controller);
+    },
+    [runTransfer, setTransfersAndRef],
+  );
+
+  const handleCancelTransfer = useCallback(
+    (id: string) => {
+      const item = transfersRef.current.find((row) => row.id === id);
+      item?.controller.abort();
+      setTransfersAndRef((prev) => prev.filter((row) => row.id !== id));
+    },
+    [setTransfersAndRef],
+  );
+
+  const handleRetryTransfer = useCallback(
+    (id: string) => {
+      const item = transfersRef.current.find((row) => row.id === id);
+      if (!item) return;
+      item.controller.abort();
+      const controller = new AbortController();
+      setTransfersAndRef((prev) =>
+        prev.map((row) =>
+          row.id === id
+            ? { ...row, status: "uploading", progress: 0, error: undefined, controller }
+            : row,
+        ),
+      );
+      void runTransfer(id, item.file, controller);
+    },
+    [runTransfer, setTransfersAndRef],
+  );
+
+  const handleRemoveTransfer = useCallback(
+    (id: string) => {
+      const item = transfersRef.current.find((row) => row.id === id);
+      item?.controller.abort();
+      if (isWeb && item) {
+        const previewUrl = previewUrlsRef.current.get(item.file);
+        if (previewUrl) {
+          URL.revokeObjectURL(previewUrl);
+          previewUrlsRef.current.delete(item.file);
+        }
+      }
+      setTransfersAndRef((prev) => prev.filter((row) => row.id !== id));
+    },
+    [setTransfersAndRef],
+  );
+
   const handleFileSelect = useCallback(
     (
       files: FileList | File[] | null,
@@ -262,15 +472,20 @@ export function FileUpload<
       setValidationError(errors.length > 0 ? errors.join("\n") : undefined);
 
       if (validFiles.length > 0) {
-        setSelectedFiles((prev) => {
-          const nextFiles = multiple ? [...prev, ...validFiles] : validFiles.slice(0, 1);
-          syncFieldValue(nextFiles, onValueChange);
-          return nextFiles;
-        });
+        emitFieldRef.current = onValueChange;
+        if (onUploadRef.current) {
+          validFiles.forEach((file) => startTransfer(file));
+        } else {
+          setSelectedFiles((prev) => {
+            const nextFiles = multiple ? [...prev, ...validFiles] : validFiles.slice(0, 1);
+            syncFieldValue(nextFiles, onValueChange);
+            return nextFiles;
+          });
+        }
         onFileSelect?.(rawFileList ?? (Array.isArray(files) ? null : files));
       }
     },
-    [multiple, validateFile, onFileSelect, syncFieldValue],
+    [multiple, validateFile, onFileSelect, syncFieldValue, startTransfer],
   );
 
   const handleFileRemove = useCallback(
@@ -343,6 +558,39 @@ export function FileUpload<
     fileInputRef.current?.click();
   }, [disabled, readOnly]);
 
+  // Native has no <input type="file">. The same press opens the OS picker and
+  // routes its result through the identical validate → setState → field path,
+  // so `accept`, `maxSize`, `multiple` and the removal list behave as on web.
+  const nativePickInFlightRef = useRef(false);
+  const openNativePicker = useCallback(
+    async (onValueChange?: (nextValue: TData) => void, onBlurHandler?: () => void) => {
+      if (disabled || readOnly || nativePickInFlightRef.current) return;
+      nativePickInFlightRef.current = true;
+      try {
+        const outcome = await pickFilesNatively({ accept, multiple, mode: pickerMode });
+        if (outcome.unavailable) {
+          setValidationError(t("No file picker is available on this device."));
+          return;
+        }
+        if (outcome.denied) {
+          setValidationError(t("Permission to open your photo library was denied."));
+          return;
+        }
+        // A dismissed picker is not an interaction: leave the value, the error
+        // and the touched state exactly as they were (web cancels the same way).
+        if (outcome.canceled || outcome.files.length === 0) return;
+        // The picked shape is `{ uri, name, type, size }` — what React Native's
+        // FormData accepts for a multipart upload — not a DOM File. Everything
+        // downstream reads name/size/type only, so this cast is the whole bridge.
+        handleFileSelect(outcome.files as unknown as File[], onValueChange);
+        onBlurHandler?.();
+      } finally {
+        nativePickInFlightRef.current = false;
+      }
+    },
+    [accept, disabled, handleFileSelect, multiple, pickerMode, readOnly],
+  );
+
   // DROPZONE-FULL-TARGET: the whole dropzone surface opens the file chooser.
   // Interactive children (Choose File button, per-file remove buttons, links)
   // handle their own press and are excluded here so remove never opens the chooser.
@@ -401,7 +649,12 @@ export function FileUpload<
   }, []);
 
   const getFilePreview = useCallback((file: File) => {
-    if (!isWeb) return null;
+    if (!isWeb) {
+      // Native picks carry a device URI instead of a blob; tamagui's Image
+      // takes it through the same `src` prop the web preview uses.
+      const uri = (file as Partial<NativePickedFile>).uri;
+      return uri && file.type?.startsWith("image/") ? uri : null;
+    }
     if (file.type.startsWith("image/")) {
       const existingUrl = previewUrlsRef.current.get(file);
       if (existingUrl) return existingUrl;
@@ -423,49 +676,109 @@ export function FileUpload<
   }
 
   const canInteract = !disabled && !readOnly;
+  const hasRows = selectedFiles.length > 0 || transfers.length > 0;
+
+  const renderRemoveDisc = (ariaLabel: string, onPress: () => void) =>
+    canInteract ? (
+      <Button
+        // Bento remove: a filled $color12 disc with the inverse
+        // ✕ — painted at nestedControl (32) with hitSlop
+        // restoring the 44 floor via `nested` (held exception);
+        // the nested icon step lands the board's 14px ✕.
+        nested
+        circular
+        icon={XIcon}
+        aria-label={ariaLabel}
+        backgroundColor={formDropzoneColors.removeDisc.background.base}
+        color={formDropzoneColors.removeDisc.ink}
+        hoverStyle={{
+          backgroundColor: formDropzoneColors.removeDisc.background.hover,
+        }}
+        pressStyle={{
+          backgroundColor: formDropzoneColors.removeDisc.background.press,
+        }}
+        onPress={(e) => {
+          e.stopPropagation();
+          onPress();
+        }}
+      />
+    ) : null;
+
+  const renderFileMeta = (file: File, preview: string | null, extra?: ReactNode) => (
+    <XStack flex={1} gap="$2" alignItems="center">
+      {preview ? (
+        <Image
+          borderRadius={cappedRadius}
+          // src (string), not source: the RN source object leaks
+          // onto the DOM <img> as source="[object Object]" on web
+          src={preview}
+          alt={file.name}
+          width={rowMediaPx}
+          height={rowMediaPx}
+          objectFit="cover"
+        />
+      ) : (
+        <XStack width={rowMediaPx} height={rowMediaPx} justifyContent="center" alignItems="center">
+          <FileIcon size={rowGlyphSize} />
+        </XStack>
+      )}
+      <YStack flex={1} gap="$1">
+        <Text numberOfLines={1} {...knobProps.body}>
+          {file.name}
+        </Text>
+        {/* Bento (bento-pickers-measured.md §2): the size is a
+            SECOND LINE, BOLD, one type step down (the label
+            tier — 13/24 at medium). The 700 is the Bento
+            treatment, a deliberate eject over the weight knob. */}
+        <Text numberOfLines={1} color={formCommonColors.text} {...knobProps.label} fontWeight="700">
+          {formatFileSize(file.size)}
+        </Text>
+        {extra}
+      </YStack>
+    </XStack>
+  );
 
   const renderUploadArea = (
     errorProp?: string | boolean,
     onValueChange?: (nextValue: TData) => void,
     onBlurHandler?: () => void,
   ) => {
-    // Native fallback - show placeholder message
-    if (!isWeb) {
-      return (
-        <UploadAreaFrame
-          outlined={knobProps.outlined}
-          // LC-40: text-bearing chrome — surface wash, not an opacity dim
-          // (a dim here stacks with the inner Button's treatment).
-          {...(disabled ? disabledState.surfaceKnobProps : undefined)}
-          borderRadius={cappedRadius}
-          // Intentional: extract borderWidth from knobProps.borderRadius fragment
-          // to use as a fallback value, not as a style spread.
-          borderWidth={knobProps.borderRadius.borderWidth ?? 1}
-          {...(errorProp ? { borderColor: formCommonColors.error } : undefined)}
-          elevation={knobProps.elevation}
-          transition={knobProps.transition}
-          aria-required={fieldProps.required || undefined}
-          aria-invalid={!!errorProp || undefined}
-          aria-readonly={readOnly || undefined}
-        >
-          <YStack
-            {...knobProps.panelPadding}
-            minHeight={getFieldHeight((fieldProps.size || knobProps.sizeToken) as SizeTokens, 5)}
-            width="100%"
-            alignItems="center"
-            justifyContent="center"
-            {...knobProps.gap}
-          >
-            <Paragraph color={formCommonColors.text} textAlign="center">
-              {t("File upload requires a native file picker.")}
-            </Paragraph>
-            <Paragraph color={formCommonColors.muted} textAlign="center" fontSize="$2">
-              Use expo-document-picker or expo-image-picker for native support.
-            </Paragraph>
-          </YStack>
-        </UploadAreaFrame>
-      );
-    }
+    emitFieldRef.current = onValueChange;
+    // The press that opens a picker: the hidden <input> on web, the OS sheet
+    // on native. Both land in the same handleFileSelect pipeline.
+    const requestFiles = isWeb
+      ? openFileDialog
+      : () => {
+          void openNativePicker(onValueChange, onBlurHandler);
+        };
+
+    // Drag-and-drop, keyboard activation and the focus ring are DOM concerns;
+    // native gets a plain press target on the same surface instead.
+    const zoneInteractionProps = canInteract
+      ? isWeb
+        ? ({
+            // DROPZONE-FULL-TARGET: the entire surface is the click target.
+            role: "button",
+            tabIndex: 0,
+            onFocus: handleZoneFocus,
+            onBlur: handleZoneBlur,
+            cursor: "pointer",
+            onClick: handleZoneClick,
+            onKeyDown: handleZoneKeyDown,
+            ...(dragDrop
+              ? {
+                  onDragEnter: handleDragEnter,
+                  onDragOver: handleDragOver,
+                  onDragLeave: handleDragLeave,
+                  onDrop: (e: DragEvent) => {
+                    handleDrop(e, onValueChange);
+                    onBlurHandler?.();
+                  },
+                }
+              : null),
+          } as any)
+        : ({ role: "button", onPress: requestFiles } as any)
+      : { cursor: disabled ? "not-allowed" : undefined };
 
     return (
       <UploadAreaFrame
@@ -479,7 +792,8 @@ export function FileUpload<
         data-kb-ring={kbZoneFocus ? "true" : undefined}
         outlined={knobProps.outlined}
         // LC-40: text-bearing chrome — surface wash, not an opacity dim
-        // (a dim here stacks with the inner Button's treatment).
+        // (a dim here stacks with the inner Button's treatment). This is the
+        // ONLY treatment that paints the transparent zone ground at rest.
         {...(disabled ? disabledState.surfaceKnobProps : undefined)}
         borderRadius={cappedRadius}
         // Keep width stable on drag (Polaris overlay, not a 1→2 layout shift).
@@ -487,56 +801,52 @@ export function FileUpload<
         {...(errorProp ? { borderColor: formCommonColors.error } : undefined)}
         elevation={knobProps.elevation}
         transition={knobProps.transition}
+        // CONTRACT (boards media-01..03): the getFieldHeight floor sits on
+        // the FRAME, so the frame border-box measures 220 — hanging it on
+        // the inner stack painted 222, a number no token expresses.
+        minHeight={getFieldHeight((fieldProps.size || knobProps.sizeToken) as SizeTokens, 5)}
         aria-required={fieldProps.required || undefined}
         aria-invalid={!!errorProp || undefined}
         aria-readonly={readOnly || undefined}
         aria-disabled={disabled || undefined}
-        // Inset: overflow:hidden on this frame would clip an outer ring (LC-71).
-        {...(kbZoneFocus ? ensureFocusVisibleRing({ outlineOffset: -2 }) : undefined)}
+        // One family ring rule (boards media-01 dz-ring): 2px $outlineColor at
+        // offset 0. The old -2 inset was the F1 defect — an element's own
+        // outline is never clipped by its own overflow:hidden.
+        //
+        // The ring must ALSO be spread into focusStyle/focusVisibleStyle. The
+        // base props alone lose: the frame's LC-71 kill is a :focus-visible
+        // rule, the browser matches :focus-visible on a keyboard-origin focus,
+        // and a pseudo-class rule outranks the plain-class atom — the zone
+        // carried `_outlineWidth-2px` AND `_outlineWidth-0focus-visible-0px`
+        // and computed outline-width 0px. Measured on the harness, not read off
+        // the source: the pre-fix spec asserted the atom's PRESENCE, which was
+        // true while nothing painted.
+        {...(kbZoneFocus ? withZoneFocusRing() : undefined)}
         hoverStyle={
           canInteract
             ? {
                 borderColor: errorProp ? formCommonColors.error : formInputColors.border.hover,
-                ...(knobProps.outlined
-                  ? undefined
-                  : { backgroundColor: formInputColors.background.focus }),
+                // Held exception: the measured mpo $color4 hover flood stays
+                // (Bento's hover/drag states were not measurable headlessly).
+                backgroundColor: formInputColors.background.focus,
               }
             : undefined
         }
+        {...zoneInteractionProps}
         {...(canInteract
-          ? ({
-              // DROPZONE-FULL-TARGET: the entire surface is the click target.
-              role: "button",
-              tabIndex: 0,
-              onFocus: handleZoneFocus,
-              onBlur: handleZoneBlur,
-              // Labeled fields get aria-labelledby auto-wired by the
-              // FieldLayout Label (tamagui Label htmlFor → this id); the
-              // aria-label fallback covers label-less usage.
-              ...(fieldProps.label && id
-                ? null
-                : {
-                    "aria-label":
-                      typeof fieldProps.label === "string"
-                        ? t("{{label}}: choose file", { label: fieldProps.label })
-                        : t("Choose file"),
-                  }),
-              cursor: "pointer",
-              onClick: handleZoneClick,
-              onKeyDown: handleZoneKeyDown,
-              ...(dragDrop
-                ? {
-                    onDragEnter: handleDragEnter,
-                    onDragOver: handleDragOver,
-                    onDragLeave: handleDragLeave,
-                    onDrop: (e: DragEvent) => {
-                      handleDrop(e, onValueChange);
-                      onBlurHandler?.();
-                    },
-                  }
-                : null),
-            } as any)
-          : { cursor: disabled ? "not-allowed" : undefined })}
+          ? // Labeled fields get aria-labelledby auto-wired by the FieldLayout
+            // Label (tamagui Label htmlFor → this id); the aria-label fallback
+            // covers label-less usage, and is what a screen reader announces
+            // for the native press target too.
+            fieldProps.label && id
+            ? null
+            : {
+                "aria-label":
+                  typeof fieldProps.label === "string"
+                    ? t("{{label}}: choose file", { label: fieldProps.label })
+                    : t("Choose file"),
+              }
+          : null)}
       >
         {isDragOver && canInteract && dragDrop ? (
           <DropOverlayFrame
@@ -548,15 +858,15 @@ export function FileUpload<
             {...knobProps.panelPadding}
           >
             <XStack
-              width={compact ? 24 : 32}
-              height={compact ? 24 : 32}
+              width={rowMediaPx}
+              height={rowMediaPx}
               alignItems="center"
               justifyContent="center"
               // `color` tints the phosphor glyph via currentColor; Tamagui applies
               // it on web Stacks though the RN-flavored View type omits it.
               {...({ color: formCommonColors.text } as Record<string, unknown>)}
             >
-              <UploadIcon size={compact ? 24 : 32} aria-hidden />
+              <UploadIcon size={rowMediaPx} aria-hidden />
             </XStack>
             <Text color={formCommonColors.text} textAlign="center" {...knobProps.body}>
               {multiple ? t("Drop files to upload") : t("Drop a file to upload")}
@@ -566,58 +876,58 @@ export function FileUpload<
 
         <YStack
           {...knobProps.panelPadding}
-          minHeight={getFieldHeight((fieldProps.size || knobProps.sizeToken) as SizeTokens, 5)}
+          flexGrow={1}
           width="100%"
           alignItems="center"
           justifyContent="center"
           {...knobProps.gap}
         >
-          {selectedFiles.length === 0 ? (
-            <XStack
-              width={compact ? 24 : 32}
-              height={compact ? 24 : 32}
-              alignItems="center"
-              justifyContent="center"
-              // `color` tints the phosphor glyph via currentColor; Tamagui applies
-              // it on web Stacks though the RN-flavored View type omits it.
-              {...({ color: formCommonColors.muted } as Record<string, unknown>)}
+          <XStack alignItems="center" {...knobProps.gap}>
+            <Button
+              onPress={requestFiles}
+              disabled={!canInteract}
+              size={knobProps.sizeToken}
+              tabIndex={-1}
+              // BENTO-DERIVED (bento-pickers-measured.md §2/§4): NO standalone
+              // glyph exists — the upload mark rides INSIDE the CTA. Held at
+              // the house 44 control with the recipe's 16px icon (Bento draws
+              // 14 on its own 36/$3 button — ruled exception).
+              icon={UploadIcon}
             >
-              <UploadIcon size={compact ? 24 : 32} aria-hidden />
-            </XStack>
-          ) : null}
-
-          <Button
-            onPress={openFileDialog}
-            disabled={!canInteract}
-            size={knobProps.sizeToken}
-            tabIndex={-1}
-          >
-            <Button.Text {...knobProps.body}>{buttonText}</Button.Text>
-          </Button>
+              <Button.Text {...knobProps.body}>{buttonText}</Button.Text>
+            </Button>
+            {actions}
+          </XStack>
 
-          {selectedFiles.length === 0 && (
+          {selectedFiles.length === 0 && transfers.length === 0 && (
             <Text color={formCommonColors.muted} textAlign="center" {...knobProps.body}>
               {placeholder}
             </Text>
           )}
 
-          <input
-            ref={fileInputRef}
-            type="file"
-            accept={accept}
-            multiple={multiple}
-            tabIndex={-1}
-            onChange={(e) => {
-              handleFileSelect(e.target.files, onValueChange, e.target.files);
-              onBlurHandler?.();
-            }}
-            style={{ display: "none" }}
-            disabled={!canInteract}
-          />
+          {isWeb ? (
+            <input
+              ref={fileInputRef}
+              type="file"
+              accept={accept}
+              multiple={multiple}
+              tabIndex={-1}
+              onChange={(e) => {
+                handleFileSelect(e.target.files, onValueChange, e.target.files);
+                onBlurHandler?.();
+              }}
+              style={{ display: "none" }}
+              disabled={!canInteract}
+            />
+          ) : null}
         </YStack>
 
-        {selectedFiles.length > 0 && (
-          <UploadFileListFrame>
+        {hasRows && (
+          <UploadFileListFrame
+            data-file-upload="files"
+            // The hairline tracks the frame edge's knob width — one dash voice.
+            borderTopWidth={knobProps.borderRadius.borderWidth ?? 1}
+          >
             {selectedFiles.map((file, index) => {
               const preview = showPreview ? getFilePreview(file) : null;
               return (
@@ -629,52 +939,86 @@ export function FileUpload<
                   justifyContent="space-between"
                   {...knobProps.panelPadding}
                 >
-                  <XStack flex={1} gap="$2" alignItems="center">
-                    {preview ? (
-                      <Image
-                        borderRadius={cappedRadius}
-                        // src (string), not source: the RN source object leaks
-                        // onto the DOM <img> as source="[object Object]" on web
-                        src={preview}
-                        alt={file.name}
-                        width={compact ? 24 : 32}
-                        height={compact ? 24 : 32}
-                        objectFit="cover"
-                      />
-                    ) : (
-                      <XStack
-                        width={compact ? 24 : 32}
-                        height={compact ? 24 : 32}
-                        justifyContent="center"
-                        alignItems="center"
+                  {renderFileMeta(file, preview)}
+                  {renderRemoveDisc(t("Remove {{name}}", { name: file.name }), () =>
+                    handleFileRemove(file, onValueChange),
+                  )}
+                </XStack>
+              );
+            })}
+            {transfers.map((item) => {
+              const preview = showPreview ? getFilePreview(item.file) : null;
+              const isUploading = item.status === "uploading";
+              const failed = item.status === "failed" ? item.error : undefined;
+              return (
+                <XStack
+                  key={item.id}
+                  data-transfer-status={item.status}
+                  width="100%"
+                  {...knobProps.gap}
+                  alignItems="center"
+                  justifyContent="space-between"
+                  {...knobProps.panelPadding}
+                >
+                  {renderFileMeta(
+                    item.file,
+                    preview,
+                    <>
+                      {isUploading ? (
+                        <YStack
+                          data-file-upload="progress"
+                          role="progressbar"
+                          aria-label={t("Uploading {{name}}", { name: item.file.name })}
+                          aria-valuemin={0}
+                          aria-valuemax={100}
+                          aria-valuenow={item.progress}
+                          height={11}
+                          width="100%"
+                          borderRadius={1000}
+                          backgroundColor={formDropzoneColors.progress.track}
+                          overflow="hidden"
+                        >
+                          <YStack
+                            height="100%"
+                            width={`${item.progress}%`}
+                            backgroundColor={formDropzoneColors.progress.fill}
+                          />
+                        </YStack>
+                      ) : null}
+                      {failed ? (
+                        <YStack gap="$1">
+                          <Text color={formCommonColors.error} {...knobProps.label}>
+                            {failed.problem}
+                          </Text>
+                          <Text color={formCommonColors.muted} {...knobProps.label}>
+                            {failed.action}
+                          </Text>
+                        </YStack>
+                      ) : null}
+                    </>,
+                  )}
+                  <XStack {...knobProps.gap} alignItems="center">
+                    {canInteract && failed ? (
+                      <Button
+                        outlined
+                        size="$2"
+                        aria-label={t("Retry {{name}}", { name: item.file.name })}
+                        onPress={(e) => {
+                          e.stopPropagation();
+                          handleRetryTransfer(item.id);
+                        }}
                       >
-                        <FileIcon size={compact ? 14 : 16} />
-                      </XStack>
-                    )}
-                    <YStack flex={1} gap="$1">
-                      <Text numberOfLines={1} {...knobProps.body}>
-                        {file.name}
-                      </Text>
-                      <Text numberOfLines={1} color={formCommonColors.text} {...knobProps.body}>
-                        {formatFileSize(file.size)}
-                      </Text>
-                    </YStack>
+                        {failed.cta ?? t("Retry")}
+                      </Button>
+                    ) : null}
+                    {isUploading
+                      ? renderRemoveDisc(t("Cancel {{name}}", { name: item.file.name }), () =>
+                          handleCancelTransfer(item.id),
+                        )
+                      : renderRemoveDisc(t("Remove {{name}}", { name: item.file.name }), () =>
+                          handleRemoveTransfer(item.id),
+                        )}
                   </XStack>
-
-                  {canInteract && (
-                    <Button
-                      circular
-                      size={knobProps.sizeToken}
-                      onPress={(e) => {
-                        e.stopPropagation();
-                        handleFileRemove(file, onValueChange);
-                      }}
-                    >
-                      <Button.Icon>
-                        <XIcon />
-                      </Button.Icon>
-                    </Button>
-                  )}
                 </XStack>
               );
             })}
@@ -745,3 +1089,10 @@ export function FileUpload<
     </Field>
   );
 }
+
+/**
+ * The value shape a native pick binds. `{ uri, name, type, size }` is what
+ * React Native's FormData accepts for a multipart upload, so a form value can
+ * be posted straight through; on web the value stays a DOM `File`.
+ */
+export type { NativePickedFile, NativePickerMode } from "./filePickerTypes";