feat(fields): adopt the file-as-reference value shape — ObjectStack ADR-0104 D3 wave 2 (PR-7) (#2828)

A file/image field value now reaches the UI in one of three forms, and the rules
for reading them live in one place — the new `file-value` module — instead of
being re-derived in each widget:

  1. Reference    a bare sys_file id string, what the backend stores once
                  file-as-reference is adopted
  2. Expanded     { id, name, size, mimeType, url }, what the read path returns
                  after resolving a reference
  3. Legacy blob  { file_id?, name, original_name, size, mime_type, url }, the
                  pre-reference shape this package used to build itself

The casing split is the bug this fixes. The expanded form carries `mimeType`;
the legacy blob carries `mime_type`. FileField, FileCell and ImageField all read
only `mime_type`, so the moment a backend starts returning the expanded form
they stop recognising images — thumbnails silently degrade to a generic file
icon, and nothing about the symptom points at a value shape as the cause.
readFileValue() accepts both, and every widget goes through it.

Uploads now submit the reference form — the bare id — when the upload adapter
surfaced one, and the legacy blob when it did not (the object-URL fallback
adapter, or a backend predating file-as-reference), so the same build works
against both. Action params already POSTed a bare fileId; record field values
now use the same contract, and serializeParamValues shares the fileIdOf()
extractor so the two surfaces cannot drift on what counts as an id.

Because a bare id carries no name or URL of its own, each widget remembers the
display details of files it just uploaded, keyed by id, so an upload renders
immediately instead of showing a bare token until the next read enriches it.


Claude-Session: https://claude.ai/code/session_01SHpGw3GBA9aFpfwVArRWfd

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/file-as-reference-adoption.md

@@ -0,0 +1,36 @@
+---
+"@object-ui/fields": minor
+"@object-ui/app-shell": patch
+---
+
+feat(fields): adopt the file-as-reference value shape (ObjectStack ADR-0104 D3 wave 2)
+
+A `file`/`image` field value now reaches the UI in one of three forms, and the
+rules for reading them live in one place — `@object-ui/fields`' new
+`file-value` module — instead of being re-derived in each widget:
+
+1. **Reference** — a bare `sys_file` id string, what the backend stores once
+   file-as-reference is adopted.
+2. **Expanded** — `{ id, name, size, mimeType, url }`, what the read path
+   returns after resolving a reference.
+3. **Legacy inline blob** — `{ file_id?, name, original_name, size, mime_type,
+   url }`, the pre-reference shape this package used to build itself.
+
+**The casing split is the bug this fixes.** The expanded form carries
+`mimeType`; the legacy blob carries `mime_type`. `FileField`, `FileCell` and
+`ImageField` all read only `mime_type`, so the moment a backend starts returning
+the expanded form they stop recognising images — thumbnails silently degrade to
+a generic file icon, with nothing pointing at a value shape as the cause.
+`readFileValue()` accepts both.
+
+**Uploads now submit the reference form** — the bare `sys_file` id — when the
+upload adapter surfaced one, falling back to the legacy blob when it did not
+(the object-URL fallback adapter, or a backend predating file-as-reference). The
+same build therefore works against both. Action params already POSTed a bare
+fileId; record field values now use the same contract, and
+`serializeParamValues` shares the `fileIdOf()` extractor so the two surfaces
+cannot drift on what counts as an id.
+
+Because a bare id carries no name or URL, each widget remembers the display
+details of files it just uploaded, keyed by id, so an upload renders immediately
+rather than showing a bare token until the next read enriches it.

packages/app-shell/src/views/ActionParamDialog.tsx

@@ -32,7 +32,7 @@ import { useObjectTranslation, pickLocalized } from '@object-ui/i18n';
 import type { ActionParamDef } from '@object-ui/core';
 import { ExpressionEvaluator } from '@object-ui/core';
 import { usePredicateScope } from '@object-ui/react';
-import { getLazyFieldWidget } from '@object-ui/fields';
+import { getLazyFieldWidget, fileIdOf } from '@object-ui/fields';
 import { paramToField } from '../utils/paramToField';
 
 export interface ParamDialogState {
@@ -75,12 +75,15 @@ export function filterVisibleParams(
 
 /**
  * Serialize collected values for the request body. Upload widgets (`file` /
- * `image`) hold a rich `{ file_id, name, url, … }` object — or an array of them
- * when `multiple` — but the portable API contract is the storage id(s). Map each
- * upload param to its `file_id` (a bare string passes through unchanged, and an
- * object missing `file_id` is left intact so the failure is visible rather than
- * silently POSTing `undefined`). Every non-upload value is returned as-is. Pure
- * + exported so the mapping is unit-testable without the dialog render tree.
+ * `image`) may hold a bare `sys_file` id — the reference form they now submit
+ * when the adapter surfaces one — or a rich `{ file_id, name, url, … }` object,
+ * or an array of either when `multiple`. The portable API contract is the
+ * storage id(s), so each upload param is reduced to its id via `fileIdOf`, the
+ * same extractor the field widgets use, so the two surfaces cannot drift on
+ * what counts as an id. An object carrying no id is left intact, so the failure
+ * is visible rather than silently POSTing `undefined`. Every non-upload value is
+ * returned as-is. Pure + exported so the mapping is unit-testable without the
+ * dialog render tree.
  */
 export function serializeParamValues(
   params: ActionParamDef[],
@@ -95,8 +98,7 @@ export function serializeParamValues(
       .map((p) => p.name),
   );
   if (uploadNames.size === 0) return values;
-  const toId = (item: any) =>
-    item && typeof item === 'object' ? (item.file_id ?? item.id ?? item) : item;
+  const toId = (item: any) => fileIdOf(item) ?? item;
   const out: Record<string, any> = { ...values };
   for (const name of uploadNames) {
     const v = out[name];

packages/fields/src/index.tsx

@@ -2443,6 +2443,10 @@ export function registerFields() {
 }
 
 export * from './widgets/types';
+// File field value shapes (ObjectStack ADR-0104 D3 wave 2) — the single
+// arbiter of reference vs expanded vs legacy-blob form, shared by the upload
+// widgets and by action-param serialization.
+export * from './widgets/file-value';
 export * from './FieldEditWidget';
 export * from './widgets/TextField';
 export * from './widgets/NumberField';

packages/fields/src/widgets/FileField.tsx

@@ -5,13 +5,28 @@ import { useObjectTranslation } from '@object-ui/i18n';
 import { Upload, X, File as FileIcon, ImageIcon, Camera, Loader2 } from 'lucide-react';
 import { FieldWidgetProps } from './types';
 import { useUploadingSignal } from './useUploadingSignal';
+import {
+  fileValueForSubmit,
+  readFileValues,
+  uploadResultView,
+  withRecentUploads,
+  isImageValue,
+  type FileValueView,
+} from './file-value';
 
 /**
  * Shared upload pipeline for the file widgets: validates size, uploads through
  * the configured UploadProvider adapter (with progress), and merges results
  * into the field value — append for `multiple`, replace otherwise. Extracted so
  * the full-size FileField and the compact grid-cell {@link FileCell} stay
  * behaviourally identical (same value shape, same error handling).
+ *
+ * Stores the **reference form** — a bare `sys_file` id — when the upload
+ * adapter surfaced one, and the legacy inline blob when it did not, so the same
+ * build works against a backend that has adopted file-as-reference and one that
+ * has not (see `file-value`). Because a bare id carries no name or URL, each
+ * completed upload's display details are kept in `recent`, keyed by id, so the
+ * file renders immediately instead of as a bare token until a read enriches it.
  */
 function useFileUploads(opts: {
   files: any[];
@@ -25,6 +40,7 @@ function useFileUploads(opts: {
   const [errors, setErrors] = useState<string[]>([]);
   const [uploadProgress, setUploadProgress] = useState<Record<string, number>>({});
   const [uploading, setUploading] = useState(false);
+  const [recent, setRecent] = useState<Record<string, FileValueView>>({});
 
   const processFiles = useCallback(async (selectedFiles: File[]) => {
     if (selectedFiles.length === 0) return;
@@ -47,26 +63,14 @@ function useFileUploads(opts: {
 
     setUploading(true);
     try {
-      const fileObjects = await Promise.all(
+      const uploaded = await Promise.all(
         validFiles.map(async (file) => {
           try {
             const result = await upload(file, {
               onProgress: (ratio) =>
                 setUploadProgress((prev) => ({ ...prev, [file.name]: ratio })),
             });
-            return {
-              // `file_id` is the storage id the backend keys attachments by
-              // (the adapter returns it as `meta.fileId`); surfacing it here
-              // lets callers that need the id — e.g. an action param POSTing
-              // `attachments: string[]` — recover it without a second lookup.
-              // Extra key; the record file-field value shape is unchanged.
-              file_id: (result.meta as { fileId?: string } | undefined)?.fileId,
-              name: result.name,
-              original_name: file.name,
-              size: result.size,
-              mime_type: result.mimeType,
-              url: result.url,
-            };
+            return { result, originalName: file.name };
           } catch (err) {
             newErrors.push(t('fields.file.uploadFailed', {
               defaultValue: `Failed to upload "${file.name}": ${(err as Error).message}`,
@@ -77,21 +81,33 @@ function useFileUploads(opts: {
           }
         }),
       );
-      const successful = fileObjects.filter(Boolean) as any[];
+      const successful = uploaded.filter(Boolean) as Array<{ result: any; originalName: string }>;
       if (successful.length === 0) return;
 
+      // Remember what each new id looks like so it can render before the next
+      // read expands it back into `{ id, name, size, mimeType, url }`.
+      const views: Record<string, FileValueView> = {};
+      for (const { result, originalName } of successful) {
+        const view = uploadResultView(result, originalName);
+        if (view.id) views[view.id] = view;
+      }
+      if (Object.keys(views).length > 0) setRecent((prev) => ({ ...prev, ...views }));
+
+      const nextValues = successful.map(({ result, originalName }) =>
+        fileValueForSubmit(result, originalName),
+      );
       if (multiple) {
-        onChange([...files, ...successful]);
+        onChange([...files, ...nextValues]);
       } else {
-        onChange(successful[0]);
+        onChange(nextValues[0]);
       }
     } finally {
       setUploading(false);
       setUploadProgress({});
     }
   }, [files, multiple, onChange, maxSize, upload, t]);
 
-  return { processFiles, errors, uploading, uploadProgress };
+  return { processFiles, errors, uploading, uploadProgress, recent };
 }
 
 /**
@@ -124,9 +140,13 @@ export function FileField({ value, onChange, field, readonly, onUploadingChange,
   const [isDragOver, setIsDragOver] = useState(false);
 
   const files = value ? (Array.isArray(value) ? value : [value]) : [];
-  const { processFiles, errors, uploading, uploadProgress } = useFileUploads({
+  const { processFiles, errors, uploading, uploadProgress, recent } = useFileUploads({
     files, multiple, maxSize, onChange,
   });
+  const fallbackName = t('fields.file.fileFallback', { defaultValue: 'File' });
+  // Normalised for display: accepts a bare reference id, the expanded
+  // `{ id, name, size, mimeType, url }`, or a legacy inline blob.
+  const views = withRecentUploads(readFileValues(value, fallbackName), recent);
   useUploadingSignal(uploading, onUploadingChange);
 
   const handleDragOver = useCallback((e: React.DragEvent) => {
@@ -164,13 +184,12 @@ export function FileField({ value, onChange, field, readonly, onUploadingChange,
 
   if (readonly) {
     if (!value) return <EmptyValue />;
-    
-    const readonlyFiles = Array.isArray(value) ? value : [value];
+
     return (
       <div className="flex flex-wrap gap-2">
-        {readonlyFiles.map((file: any, idx: number) => (
+        {views.map((file, idx) => (
           <span key={idx} className="text-sm truncate max-w-xs">
-            {file.name || file.original_name || t('fields.file.fileFallback', { defaultValue: 'File' })}
+            {file.name}
           </span>
         ))}
       </div>
@@ -190,11 +209,6 @@ export function FileField({ value, onChange, field, readonly, onUploadingChange,
     }
   };
 
-  const isImage = (file: any) => {
-    const mime = file.mime_type || '';
-    return mime.startsWith('image/');
-  };
-
   return (
     <div className={props.className}>
       <input
@@ -303,23 +317,23 @@ export function FileField({ value, onChange, field, readonly, onUploadingChange,
         )}
 
         {/* File list */}
-        {files.length > 0 && (
+        {views.length > 0 && (
           <div className="space-y-1">
-            {files.map((file: any, idx: number) => (
+            {views.map((file, idx) => (
               <div
                 key={idx}
                 className="flex items-center justify-between gap-2 p-2 bg-muted/50 rounded-md border"
               >
                 <div className="flex items-center gap-2 flex-1 min-w-0">
-                  {isImage(file) && file.url ? (
+                  {isImageValue(file) && file.url ? (
                     <img src={file.url} alt={file.name} className="size-8 object-cover rounded shrink-0" />
-                  ) : isImage(file) ? (
+                  ) : isImageValue(file) ? (
                     <ImageIcon className="size-4 text-muted-foreground shrink-0" />
                   ) : (
                     <FileIcon className="size-4 text-muted-foreground shrink-0" />
                   )}
                   <span className="text-sm truncate">
-                    {file.name || file.original_name || t('fields.file.fileFallback', { defaultValue: 'File' })}
+                    {file.name}
                   </span>
                   {file.size && (
                     <span className="text-xs text-muted-foreground">
@@ -382,9 +396,11 @@ export function FileCell({
   const { t } = useObjectTranslation();
   const inputRef = useRef<HTMLInputElement>(null);
   const files = value ? (Array.isArray(value) ? value : [value]) : [];
-  const { processFiles, errors, uploading } = useFileUploads({
+  const { processFiles, errors, uploading, recent } = useFileUploads({
     files, multiple: !!multiple, maxSize, onChange,
   });
+  const fallbackName = t('fields.file.fileFallback', { defaultValue: 'File' });
+  const views = withRecentUploads(readFileValues(value, fallbackName), recent);
 
   const removeAt = (index: number) => {
     if (multiple) {
@@ -395,11 +411,6 @@ export function FileCell({
     }
   };
 
-  const isImage = (file: any) => String(file?.mime_type || '').startsWith('image/');
-  const nameOf = (file: any) =>
-    typeof file === 'string'
-      ? file
-      : file?.name || file?.original_name || t('fields.file.fileFallback', { defaultValue: 'File' });
   const showUpload = !disabled && !uploading && (multiple || files.length === 0);
 
   return (
@@ -415,24 +426,24 @@ export function FileCell({
         }}
         className="hidden"
       />
-      {files.map((file: any, idx: number) => (
+      {views.map((file, idx) => (
         <span
           key={idx}
           className="inline-flex max-w-40 items-center gap-1 rounded border bg-muted/50 px-1 py-0.5 text-xs"
-          title={nameOf(file)}
+          title={file.name}
           data-testid="file-cell-chip"
         >
-          {isImage(file) && file.url ? (
-            <img src={file.url} alt={nameOf(file)} className="size-5 shrink-0 rounded object-cover" />
+          {isImageValue(file) && file.url ? (
+            <img src={file.url} alt={file.name} className="size-5 shrink-0 rounded object-cover" />
           ) : (
             <FileIcon className="size-3 shrink-0 text-muted-foreground" />
           )}
-          <span className="truncate">{nameOf(file)}</span>
+          <span className="truncate">{file.name}</span>
           {!disabled && (
             <button
               type="button"
               className="shrink-0 rounded p-0.5 text-muted-foreground hover:text-foreground"
-              aria-label={t('fields.file.remove', { defaultValue: `Remove ${nameOf(file)}`, name: nameOf(file) })}
+              aria-label={t('fields.file.remove', { defaultValue: `Remove ${file.name}`, name: file.name })}
               onClick={() => removeAt(idx)}
             >
               <X className="size-3" />