@object-ui/fields 16.1.0 → 17.2.0

package/src/widgets/__tests__/FilterConditionField.matchAll.test.ts

@@ -0,0 +1,66 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Empty-criteria guard for the sharing-rule criteria builder
+ * (objectstack#3896).
+ *
+ * This widget used to tell an admin that an empty criteria meant "All
+ * records" — the most dangerous thing it could say, because it was describing
+ * a bug as a feature. A sharing rule with no predicate was stored as
+ * `criteria_json: null` and then evaluated as `find(object, { filter: {} })`,
+ * i.e. every record of the object granted to the recipient. `SharingRuleSchema`
+ * had always forbidden that shape ("never seeded as a permissive match-all",
+ * ADR-0049); the REST and data-API entries just never checked.
+ *
+ * The server now refuses to save such a rule and shares nothing for one
+ * already stored. These tests pin the client-side mirror of that predicate, so
+ * the widget warns while the admin is still looking at the empty builder
+ * rather than after a rejected save.
+ */
+import { describe, it, expect } from 'vitest';
+import { isMatchAllCriteria } from '../FilterConditionField';
+
+describe('isMatchAllCriteria — shapes that would share every record', () => {
+  it('flags the empty and vacuous shapes', () => {
+    for (const shape of [
+      undefined,
+      null,
+      {},           // what a blank builder / blank textarea parses to
+      [],
+      true,
+      42,
+      { $and: [] },
+      { $or: [] },
+      { $and: [{}] },
+      { $or: [{ stage: 'won' }, {}] }, // one unconstrained branch opens the OR
+    ]) {
+      expect(isMatchAllCriteria(shape), `${JSON.stringify(shape) ?? String(shape)}`).toBe(true);
+    }
+  });
+
+  it('passes anything that actually narrows the result set', () => {
+    for (const shape of [
+      { stage: 'won' },
+      { amount: { $gte: 100000 } },
+      [{ stage: 'won' }],
+      { $and: [{ stage: 'won' }] },
+      { $or: [{ a: 1 }, { b: 2 }] },
+      { health: 'red', budget: { $gt: 1 } },
+    ]) {
+      expect(isMatchAllCriteria(shape), JSON.stringify(shape)).toBe(false);
+    }
+  });
+
+  it('agrees with the server on the reported case: a rule saved with no criteria', () => {
+    // The builder emits '' for an empty group, which the widget parses to {}.
+    expect(isMatchAllCriteria({})).toBe(true);
+    // …and one real condition is enough to clear the gate.
+    expect(isMatchAllCriteria({ health: 'red' })).toBe(false);
+  });
+});

package/src/widgets/__tests__/FilterConditionField.operators.test.ts

@@ -0,0 +1,142 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Operator spelling guard for the sharing-rule criteria builder (#2901).
+ *
+ * `condToMongo` emitted `$ncontains` — a token that appears nowhere in
+ * `@objectstack/spec` and that objectui's own `convertFiltersToAST` throws on,
+ * naming the correct spelling (`$notContains`) in its error message. So every
+ * "does not contain" rule authored here validated in the UI and was then
+ * rejected downstream. Nothing caught it because the builder's operator list is
+ * hand-written and never compared against the spec vocabulary.
+ *
+ * These tests pin the emitted spellings against `FieldOperatorsSchema`'s keys
+ * and pin the round-trip, including the pre-fix spelling that stored criteria
+ * still carry.
+ */
+import { describe, it, expect } from 'vitest';
+import { FieldOperatorsSchema } from '@objectstack/spec/data';
+import { condToMongo, kvToCondition } from '../FilterConditionField';
+
+/**
+ * The `$`-prefixed operator keys of the spec's `FieldOperatorsSchema` —
+ * DERIVED from the schema (#2942), so a 16th operator landing in the spec
+ * fails the reachability test below instead of drifting unnoticed.
+ */
+const SPEC_OPERATORS = new Set(
+  Object.keys((FieldOperatorsSchema as unknown as { shape?: Record<string, unknown> }).shape ?? {}),
+);
+
+const noTypes = () => undefined;
+
+/** Pull the operator keys out of a `{ field: { $op: v } }` fragment. */
+function operatorsOf(frag: Record<string, any> | null): string[] {
+  if (!frag) return [];
+  return Object.values(frag).flatMap((v) =>
+    v !== null && typeof v === 'object' && !Array.isArray(v) ? Object.keys(v) : [],
+  );
+}
+
+describe('condToMongo emits only spec operator spellings', () => {
+  const builderOperators = [
+    'equals', 'notEquals', 'contains', 'notContains', 'isEmpty', 'isNotEmpty',
+    'greaterThan', 'lessThan', 'greaterOrEqual', 'lessOrEqual', 'in', 'notIn',
+    'before', 'after',
+    'startsWith', 'endsWith', 'isNull', 'isNotNull', 'exists', 'notExists',
+  ];
+
+  it.each(builderOperators)('%s emits a spec-defined operator', (operator) => {
+    const frag = condToMongo(
+      { id: 'c1', field: 'name', operator, value: operator === 'in' || operator === 'notIn' ? ['a'] : 'a' } as any,
+      noTypes,
+    );
+    const unknown = operatorsOf(frag).filter((op) => !SPEC_OPERATORS.has(op));
+    expect(unknown, `${operator} emits an operator @objectstack/spec does not define`).toEqual([]);
+  });
+
+  it('notContains emits $notContains, not the pre-fix $ncontains', () => {
+    const frag = condToMongo({ id: 'c1', field: 'name', operator: 'notContains', value: 'x' } as any, noTypes);
+    expect(frag).toEqual({ name: { $notContains: 'x' } });
+  });
+
+  it('between emits a range the spec defines', () => {
+    const frag = condToMongo({ id: 'c1', field: 'age', operator: 'between', value: [1, 5] } as any, noTypes);
+    expect(operatorsOf(frag).every((op) => SPEC_OPERATORS.has(op))).toBe(true);
+  });
+});
+
+describe('every spec field operator is reachable from the builder (#2942)', () => {
+  it('reads a non-empty operator vocabulary from the spec', () => {
+    expect([...SPEC_OPERATORS].length, 'could not read FieldOperatorsSchema.shape').toBeGreaterThan(0);
+  });
+
+  it('some builder operator emits every spec $-token', () => {
+    const builderOperators = [
+      'equals', 'notEquals', 'contains', 'notContains', 'isEmpty', 'isNotEmpty',
+      'greaterThan', 'lessThan', 'greaterOrEqual', 'lessOrEqual', 'in', 'notIn',
+      'before', 'after', 'between',
+      'startsWith', 'endsWith', 'isNull', 'isNotNull', 'exists', 'notExists',
+    ];
+    const emitted = new Set<string>();
+    for (const operator of builderOperators) {
+      const value = operator === 'in' || operator === 'notIn' ? ['a'] : operator === 'between' ? [1, 5] : 'a';
+      const frag = condToMongo({ id: 'c1', field: 'f', operator, value } as any, noTypes);
+      for (const op of operatorsOf(frag)) emitted.add(op);
+    }
+    // `$eq` is the spec's IMPLICIT equality form — `equals` deliberately
+    // emits the bare `{ field: value }` shape, never an explicit `$eq`.
+    // `$between` stays covered by the `$gte`+`$lte` pair `between` emits
+    // (kvToCondition reads that pair back as `between`).
+    const unreachable = [...SPEC_OPERATORS].filter(
+      (op) => op !== '$eq' && op !== '$between' && !emitted.has(op),
+    );
+    expect(
+      unreachable,
+      'FieldOperatorsSchema accepts these but no builder operator can author them',
+    ).toEqual([]);
+  });
+});
+
+describe('kvToCondition round-trips what condToMongo writes', () => {
+  const cases: Array<[string, unknown]> = [
+    ['notEquals', 'a'],
+    ['contains', 'a'],
+    ['notContains', 'a'],
+    ['greaterThan', 1],
+    ['lessThan', 1],
+    ['greaterOrEqual', 1],
+    ['lessOrEqual', 1],
+    ['startsWith', 'a'],
+    ['endsWith', 'a'],
+    ['isNull', ''],
+    ['isNotNull', ''],
+    ['exists', ''],
+    ['notExists', ''],
+  ];
+
+  it.each(cases)('%s survives the round trip', (operator, value) => {
+    const frag = condToMongo({ id: 'c1', field: 'f', operator, value } as any, noTypes)!;
+    const [[field, v]] = Object.entries(frag);
+    expect(kvToCondition(field, v, 0)).toMatchObject({ field: 'f', operator });
+  });
+
+  it('still reads the pre-fix $ncontains so stored criteria keep loading', () => {
+    // Dropping this would make rules saved before the fix fail to load entirely
+    // ("criteria can't be represented") rather than migrate.
+    expect(kvToCondition('name', { $ncontains: 'x' }, 0)).toMatchObject({
+      field: 'name',
+      operator: 'notContains',
+      value: 'x',
+    });
+  });
+
+  it('rejects an operator it cannot represent rather than guessing', () => {
+    expect(kvToCondition('name', { $nope: 'x' }, 0)).toBeNull();
+  });
+});

package/src/widgets/file-value.test.ts

@@ -0,0 +1,230 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isFileIdToken,
+  fileIdOf,
+  readFileValue,
+  readFileValues,
+  isImageValue,
+  fileValueForSubmit,
+  uploadResultView,
+  withRecentUploads,
+} from './file-value';
+
+const uploadResult = (over: Record<string, unknown> = {}) => ({
+  url: 'https://app.example.com/api/v1/storage/files/file_a',
+  name: 'a.png',
+  size: 1024,
+  mimeType: 'image/png',
+  ...over,
+});
+
+describe('isFileIdToken', () => {
+  it.each(['file_a', 'abc123', '0e2f4c1a-9b7d-4e3f-8a1b-2c3d4e5f6a7b', 'A-_9'])(
+    'accepts the minted id %s',
+    (v) => expect(isFileIdToken(v)).toBe(true),
+  );
+
+  it.each([
+    'https://cdn.example.com/a.png',
+    '/api/v1/storage/files/file_a',
+    'data:image/png;base64,aGk=',
+    'blob:http://localhost/abc',
+    'a.png',
+    '',
+  ])('rejects the URL-shaped or dotted value %s', (v) => expect(isFileIdToken(v)).toBe(false));
+
+  it('rejects non-strings and over-long values', () => {
+    expect(isFileIdToken(null)).toBe(false);
+    expect(isFileIdToken(42)).toBe(false);
+    expect(isFileIdToken('a'.repeat(65))).toBe(false);
+  });
+});
+
+describe('fileIdOf', () => {
+  it('reads a bare reference', () => {
+    expect(fileIdOf('file_a')).toBe('file_a');
+  });
+
+  it('prefers file_id, then id', () => {
+    expect(fileIdOf({ file_id: 'legacy', id: 'expanded' })).toBe('legacy');
+    expect(fileIdOf({ id: 'expanded' })).toBe('expanded');
+  });
+
+  it('returns undefined when there is no id to read', () => {
+    expect(fileIdOf({ url: 'https://cdn.example.com/a.png', name: 'a.png' })).toBeUndefined();
+    expect(fileIdOf('https://cdn.example.com/a.png')).toBeUndefined();
+    expect(fileIdOf(null)).toBeUndefined();
+  });
+});
+
+describe('readFileValue', () => {
+  /**
+   * The casing split is the reason this module exists: the platform's expanded
+   * form is camelCase `mimeType`, the legacy inline blob is snake_case
+   * `mime_type`. A widget reading only one silently stops recognising images
+   * the moment the backend switches form.
+   */
+  it('reads the expanded form (camelCase mimeType)', () => {
+    const view = readFileValue({
+      id: 'file_a',
+      name: 'a.png',
+      size: 1024,
+      mimeType: 'image/png',
+      url: '/api/v1/storage/files/file_a',
+    });
+
+    expect(view).toMatchObject({
+      id: 'file_a',
+      name: 'a.png',
+      size: 1024,
+      mimeType: 'image/png',
+      url: '/api/v1/storage/files/file_a',
+    });
+    expect(isImageValue(view)).toBe(true);
+  });
+
+  it('reads the legacy inline blob (snake_case mime_type)', () => {
+    const view = readFileValue({
+      file_id: 'file_a',
+      name: 'a.png',
+      original_name: 'original.png',
+      size: 1024,
+      mime_type: 'image/png',
+      url: 'https://cdn.example.com/a.png',
+    });
+
+    expect(view).toMatchObject({ id: 'file_a', name: 'a.png', mimeType: 'image/png' });
+    expect(isImageValue(view)).toBe(true);
+  });
+
+  it('falls back to original_name when name is absent', () => {
+    expect(readFileValue({ original_name: 'orig.pdf' }).name).toBe('orig.pdf');
+  });
+
+  it('derives a name from the URL when the value carries none', () => {
+    expect(readFileValue({ url: 'https://cdn.example.com/docs/report%20v2.pdf' }).name).toBe(
+      'report v2.pdf',
+    );
+    expect(readFileValue('https://cdn.example.com/a.png').name).toBe('a.png');
+  });
+
+  it('resolves a bare reference to the stable download URL', () => {
+    const view = readFileValue('file_a', 'File');
+
+    // The read path may leave a value in its bare-reference form (seen on the
+    // edit-form data path); the stable endpoint is derivable from the id, so a
+    // thumbnail still renders instead of a broken `<img src="">`.
+    expect(view).toMatchObject({ id: 'file_a', name: 'File' });
+    expect(view.url).toBe('/api/v1/storage/files/file_a');
+  });
+
+  it('derives the URL of an object that carries an id but no url', () => {
+    const view = readFileValue({ id: 'file_b', name: 'b.png' });
+    expect(view.url).toBe('/api/v1/storage/files/file_b');
+  });
+
+  it('treats a URL string as a URL, never as a reference', () => {
+    const view = readFileValue('/api/v1/storage/files/file_a');
+    expect(view.id).toBeUndefined();
+    expect(view.url).toBe('/api/v1/storage/files/file_a');
+  });
+
+  it('uses the supplied fallback name so widgets stay localised', () => {
+    expect(readFileValue({}, '文件').name).toBe('文件');
+    expect(readFileValue(null, '文件').name).toBe('文件');
+  });
+
+  it('is not an image when the MIME type says otherwise or is missing', () => {
+    expect(isImageValue(readFileValue({ mimeType: 'application/pdf' }))).toBe(false);
+    expect(isImageValue(readFileValue({ name: 'a.png' }))).toBe(false);
+  });
+});
+
+describe('readFileValues', () => {
+  it('normalises single, array and empty values', () => {
+    expect(readFileValues(null)).toEqual([]);
+    expect(readFileValues([])).toEqual([]);
+    expect(readFileValues('file_a')).toHaveLength(1);
+    expect(readFileValues(['file_a', 'file_b'])).toHaveLength(2);
+  });
+
+  it('drops null entries inside an array', () => {
+    expect(readFileValues(['file_a', null, 'file_b'])).toHaveLength(2);
+  });
+
+  it('handles a mixed-form array during the transition', () => {
+    const views = readFileValues([
+      'file_a',
+      { id: 'file_b', name: 'b.png', mimeType: 'image/png' },
+      { name: 'c.png', mime_type: 'image/png', url: 'https://cdn.example.com/c.png' },
+    ]);
+
+    expect(views.map((v) => v.id)).toEqual(['file_a', 'file_b', undefined]);
+    expect(views.map(isImageValue)).toEqual([false, true, true]);
+  });
+});
+
+describe('fileValueForSubmit', () => {
+  it('submits the bare reference when the adapter surfaced a fileId', () => {
+    expect(fileValueForSubmit(uploadResult({ meta: { fileId: 'file_a' } }), 'orig.png')).toBe(
+      'file_a',
+    );
+  });
+
+  /**
+   * Back-compat: the object-URL fallback adapter, or a backend predating
+   * file-as-reference, surfaces no fileId. The same build must keep working
+   * there, so it submits the legacy blob unchanged.
+   */
+  it('falls back to the legacy inline blob when there is no fileId', () => {
+    expect(fileValueForSubmit(uploadResult(), 'orig.png')).toEqual({
+      name: 'a.png',
+      original_name: 'orig.png',
+      size: 1024,
+      mime_type: 'image/png',
+      url: 'https://app.example.com/api/v1/storage/files/file_a',
+    });
+  });
+
+  it('ignores a meta.fileId that is not id-shaped', () => {
+    const v = fileValueForSubmit(uploadResult({ meta: { fileId: 'https://evil.example/x' } }));
+    expect(typeof v).toBe('object');
+  });
+
+  it('round-trips through readFileValue in both modes', () => {
+    const asRef = fileValueForSubmit(uploadResult({ meta: { fileId: 'file_a' } }));
+    const asBlob = fileValueForSubmit(uploadResult(), 'orig.png');
+
+    expect(readFileValue(asRef).id).toBe('file_a');
+    expect(readFileValue(asBlob).mimeType).toBe('image/png');
+  });
+});
+
+describe('withRecentUploads', () => {
+  it('fills in display details for a bare reference just uploaded', () => {
+    const view = uploadResultView(uploadResult({ meta: { fileId: 'file_a' } }), 'orig.png');
+    const merged = withRecentUploads(readFileValues('file_a'), { file_a: view });
+
+    expect(merged[0]).toMatchObject({
+      id: 'file_a',
+      name: 'a.png',
+      mimeType: 'image/png',
+      url: 'https://app.example.com/api/v1/storage/files/file_a',
+    });
+    // The raw value stays the reference — display enrichment must not change
+    // what the field submits.
+    expect(merged[0].raw).toBe('file_a');
+  });
+
+  it('leaves a value the backend already expanded alone', () => {
+    const stale = uploadResultView(uploadResult({ name: 'stale.png', meta: { fileId: 'file_a' } }));
+    const expanded = readFileValues([{ id: 'file_a', name: 'fresh.png', url: '/u', mimeType: 'image/png' }]);
+
+    expect(withRecentUploads(expanded, { file_a: stale })[0].name).toBe('fresh.png');
+  });
+
+  it('is a no-op with nothing remembered', () => {
+    const views = readFileValues('file_a');
+    expect(withRecentUploads(views, {})).toBe(views);
+  });
+});

package/src/widgets/file-value.ts

@@ -0,0 +1,246 @@
+/**
+ * File field value shapes (ObjectStack ADR-0104 D3 wave 2).
+ *
+ * A `file`/`image`/`avatar`/`video`/`audio` field value reaches the UI in one
+ * of three forms, and every widget that renders one has to cope with all
+ * three — so the rules live here once rather than being re-derived per widget.
+ *
+ *  1. **Reference** — a bare `sys_file` id string. The form the backend stores
+ *     once file-as-reference is adopted.
+ *  2. **Expanded** — `{ id, name, size, mimeType, url }`, what the read path
+ *     returns after resolving a stored reference. Note `mimeType`: this comes
+ *     from the platform's spec-owned `FileValueSchema` and is **camelCase**.
+ *  3. **Legacy inline blob** — `{ file_id?, name, original_name, size,
+ *     mime_type, url }`, the pre-reference shape this package used to build
+ *     itself, with **snake_case** `mime_type`.
+ *
+ * That casing split is the whole reason this module exists: a widget reading
+ * only `mime_type` silently stops recognising images the moment the backend
+ * starts returning the expanded form, and the failure looks like "thumbnails
+ * disappeared" rather than anything pointing at a value shape.
+ *
+ * ## Submitting
+ *
+ * When the upload adapter surfaced a `fileId`, the widget submits the **bare
+ * id** — the reference form. When it did not (the object-URL fallback adapter,
+ * an older backend), it submits the legacy blob unchanged. So the same build
+ * works against a backend that has adopted references and one that has not.
+ * Action params already POST a bare fileId; this brings record field values
+ * onto the same contract.
+ */
+
+import { isFileIdToken } from '@objectstack/spec/data';
+
+/** A file value normalised for rendering, whatever form it arrived in. */
+export interface FileValueView {
+  /** `sys_file` id, when the value carries one. */
+  id?: string;
+  /** Best available display name. Never empty. */
+  name: string;
+  /** Resolvable URL, when the value carries one. A bare reference does not. */
+  url?: string;
+  size?: number;
+  mimeType?: string;
+  /** The value as it arrived, so callers can pass it through untouched. */
+  raw: unknown;
+}
+
+/**
+ * A minted file id: uuid/nanoid-shaped, and crucially not a URL — a URL always
+ * carries `:`, `/` or `.`, so it can never match.
+ *
+ * This IS the platform's arbiter now, not a mirror of it (objectui#3161,
+ * objectstack#4115 ledger batch 7). The declaration that stood here said it
+ * "mirrors the platform's `isFileIdToken`" while being a character-for-character
+ * copy of that function's body under that function's own name — the shape
+ * objectui#3003 argued about and objectui#3169 caught again in
+ * `isAggregatedViewContainer`: every value test and every behaviour test passes
+ * against a faithful copy, so reference identity is the only check that can tell
+ * a re-export from a fork. It is asserted in
+ * `__tests__/spec-symbol-batch7.test.ts`.
+ *
+ * Why it matters that this one is shared rather than duplicated: the regex is a
+ * WIRE decision. Widening it server-side (say, ids grow past 64 chars) while a
+ * copy here keeps the old bound turns every new id into "not a reference", and
+ * the widget then submits the legacy inline blob against a backend that expects
+ * a reference. That failure surfaces as a broken thumbnail, nowhere near a
+ * regex.
+ */
+export { isFileIdToken };
+
+/**
+ * The `sys_file` id a value refers to, or `undefined`.
+ *
+ * `file_id ?? id` matches the rule `serializeParamValues` already applies to
+ * action params — one extraction rule for both surfaces.
+ */
+export function fileIdOf(value: unknown): string | undefined {
+  if (isFileIdToken(value)) return value;
+  if (value && typeof value === 'object') {
+    const o = value as Record<string, unknown>;
+    const id = o.file_id ?? o.id;
+    if (typeof id === 'string' && id) return id;
+  }
+  return undefined;
+}
+
+/**
+ * The stable download endpoint a bare `sys_file` id resolves to.
+ *
+ * `createObjectStackUploadAdapter` stores exactly this URL (`${basePath}/files/
+ * :id`, default base `/api/v1/storage`) as a completed upload's value, and the
+ * endpoint 302-redirects to a freshly-signed short-lived URL on every request —
+ * so it can be used directly as an `<img src>`. Building it here means a value
+ * still in its bare-reference form (the backend read path didn't expand it —
+ * seen on the edit-form data path, objectui image thumbnails rendering broken)
+ * resolves to a real URL instead of an empty `src`.
+ */
+export const FILE_STORAGE_BASE_PATH = '/api/v1/storage';
+
+/** The stable download URL for a `sys_file` id. */
+export function fileUrlFromId(id: string): string {
+  return `${FILE_STORAGE_BASE_PATH}/files/${encodeURIComponent(id)}`;
+}
+
+/** Last path segment of a URL, used as a display name of last resort. */
+function nameFromUrl(url: string): string {
+  const path = url.split(/[?#]/)[0] ?? url;
+  const seg = path.split('/').filter(Boolean).pop();
+  return seg ? decodeURIComponent(seg) : url;
+}
+
+/**
+ * Normalise one file value for display.
+ *
+ * @param fallbackName shown when the value carries no usable name — pass a
+ *   translated string so the widget stays localised.
+ */
+export function readFileValue(value: unknown, fallbackName = 'File'): FileValueView {
+  if (value == null) return { name: fallbackName, raw: value };
+
+  if (typeof value === 'string') {
+    // A bare id carries no name of its own (the backend expands it on read),
+    // but its URL is derivable from the stable download endpoint — so a value
+    // the read path left as a bare reference still renders a thumbnail instead
+    // of a broken `<img src="">`.
+    if (isFileIdToken(value)) return { id: value, name: fallbackName, url: fileUrlFromId(value), raw: value };
+    // Otherwise it is a URL (legacy external link, data:, blob:).
+    return { url: value, name: nameFromUrl(value), raw: value };
+  }
+
+  if (typeof value === 'object') {
+    const o = value as Record<string, unknown>;
+    const str = (v: unknown) => (typeof v === 'string' && v ? v : undefined);
+    const id = fileIdOf(o);
+    // An object shape that carries an id but not its URL (a partially-expanded
+    // reference) still resolves to the stable endpoint, same as a bare id.
+    const url = str(o.url) ?? (id ? fileUrlFromId(id) : undefined);
+    const name =
+      str(o.name) ??
+      str(o.original_name) ??
+      (str(o.url) ? nameFromUrl(str(o.url) as string) : undefined) ??
+      fallbackName;
+    return {
+      id,
+      name,
+      url,
+      size: typeof o.size === 'number' ? o.size : undefined,
+      // Expanded form is camelCase, legacy blob is snake_case — accept both.
+      mimeType: str(o.mimeType) ?? str(o.mime_type),
+      raw: value,
+    };
+  }
+
+  return { name: fallbackName, raw: value };
+}
+
+/** Normalise a field value (single or `multiple`) to an array of views. */
+export function readFileValues(value: unknown, fallbackName = 'File'): FileValueView[] {
+  if (value == null) return [];
+  const items = Array.isArray(value) ? value : [value];
+  return items.filter((v) => v != null).map((v) => readFileValue(v, fallbackName));
+}
+
+/** Does this value look like an image, by MIME type? */
+export function isImageValue(view: FileValueView): boolean {
+  return (view.mimeType ?? '').startsWith('image/');
+}
+
+/** The subset of an upload result these helpers read. */
+export interface UploadResultLike {
+  url: string;
+  name: string;
+  size: number;
+  mimeType: string;
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * What to store in the field for a completed upload.
+ *
+ * Returns the bare `sys_file` id when the adapter surfaced one — the reference
+ * form — and the legacy inline blob when it did not, so a deployment whose
+ * upload adapter or backend predates file-as-reference keeps working unchanged.
+ */
+export function fileValueForSubmit(
+  result: UploadResultLike,
+  originalName?: string,
+): string | Record<string, unknown> {
+  const fileId = (result.meta as { fileId?: unknown } | undefined)?.fileId;
+  if (isFileIdToken(fileId)) return fileId;
+  return {
+    name: result.name,
+    original_name: originalName ?? result.name,
+    size: result.size,
+    mime_type: result.mimeType,
+    url: result.url,
+  };
+}
+
+/**
+ * The display view of a just-completed upload.
+ *
+ * Submitting a bare id means the field value no longer carries the name, size
+ * or URL needed to render it, and the enriched form only comes back on the next
+ * read. Widgets keep these views keyed by id so an upload appears immediately
+ * instead of showing a bare token until a refetch.
+ */
+export function uploadResultView(result: UploadResultLike, originalName?: string): FileValueView {
+  const id = isFileIdToken((result.meta as { fileId?: unknown } | undefined)?.fileId)
+    ? ((result.meta as { fileId?: string }).fileId as string)
+    : undefined;
+  return {
+    id,
+    name: result.name || originalName || 'File',
+    url: result.url,
+    size: result.size,
+    mimeType: result.mimeType,
+    raw: result,
+  };
+}
+
+/**
+ * Merge locally-known upload views over a field value's own views, matched by
+ * id. A value that is still a bare reference picks up the name/URL captured at
+ * upload time; anything already enriched by the backend is left alone.
+ */
+export function withRecentUploads(
+  views: FileValueView[],
+  recent: Record<string, FileValueView>,
+): FileValueView[] {
+  if (Object.keys(recent).length === 0) return views;
+  return views.map((v) => {
+    const known = v.id ? recent[v.id] : undefined;
+    if (!known) return v;
+    // A value the backend already expanded carries its own URL on the raw
+    // object — leave that alone. A bare reference (string id, or an id-only
+    // object) has only the synthetic download URL `readFileValue` derived, so
+    // the just-uploaded name/mimeType still fills in.
+    const rawHasOwnUrl =
+      !!v.raw &&
+      typeof v.raw === 'object' &&
+      typeof (v.raw as Record<string, unknown>).url === 'string' &&
+      !!(v.raw as Record<string, unknown>).url;
+    return rawHasOwnUrl ? v : { ...known, raw: v.raw };
+  });
+}