@object-ui/fields 17.5.0 → 17.6.0

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

@@ -1,230 +0,0 @@
-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

@@ -1,246 +0,0 @@
-/**
- * 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 };
-  });
-}

package/src/widgets/nativeDateValue.test.ts

@@ -1,115 +0,0 @@
-/**
- * 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.
- */
-
-import { describe, it, expect } from 'vitest';
-import { InstantValueSchema } from '@objectstack/spec/data';
-import {
-  toDateInputValue,
-  toDateTimeInputValue,
-  fromDateTimeInputValue,
-} from './nativeDateValue';
-
-/**
- * These assertions are deliberately written to hold in EVERY timezone, because
- * the bug they pin (objectui#3127) is a timezone-shaped one and a test that
- * only passes in UTC would go green on CI while the defect it guards is live
- * for every user east or west of it.
- *
- * The trick: never hardcode the expected wall clock. Assert the SHAPE the
- * native control demands, and assert that reading that shape back (as local
- * time, which is how both the browser and `new Date` read a zone-less
- * datetime) lands on the same INSTANT we started from.
- */
-
-const localInstantOf = (bare: string) => new Date(bare).getTime();
-
-describe('toDateInputValue', () => {
-  it('keeps a leading YYYY-MM-DD verbatim, in any timezone', () => {
-    // Re-parsing would read this as UTC midnight and hand back the 16th
-    // anywhere west of Greenwich. The calendar day is the value here.
-    expect(toDateInputValue('2026-06-17')).toBe('2026-06-17');
-    expect(toDateInputValue('2026-06-17T14:30:00.000Z')).toBe('2026-06-17');
-  });
-
-  it('formats a Date to the local calendar day', () => {
-    const d = new Date(2026, 5, 17, 23, 59);
-    expect(toDateInputValue(d)).toBe('2026-06-17');
-  });
-
-  it('maps empty and unparseable input to an empty control', () => {
-    expect(toDateInputValue(null)).toBe('');
-    expect(toDateInputValue(undefined)).toBe('');
-    expect(toDateInputValue('')).toBe('');
-    expect(toDateInputValue('not a date')).toBe('');
-  });
-});
-
-describe('toDateTimeInputValue', () => {
-  it('renders a UTC ISO instant as a local wall clock the control accepts', () => {
-    const iso = '2026-06-17T14:30:00.000Z';
-    const shown = toDateTimeInputValue(iso);
-
-    // 1. The shape `datetime-local` demands — the whole point of #3127.
-    expect(shown).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/);
-    // 2. …denoting the SAME instant the record holds.
-    expect(localInstantOf(shown)).toBe(new Date(iso).getTime());
-  });
-
-  it('truncates an already-local datetime to minutes without re-parsing it', () => {
-    expect(toDateTimeInputValue('2026-06-17T14:30')).toBe('2026-06-17T14:30');
-    expect(toDateTimeInputValue('2026-06-17T14:30:59')).toBe('2026-06-17T14:30');
-    expect(toDateTimeInputValue('2026-06-17T14:30:59.123')).toBe('2026-06-17T14:30');
-  });
-
-  it('maps empty and unparseable input to an empty control', () => {
-    expect(toDateTimeInputValue(null)).toBe('');
-    expect(toDateTimeInputValue(undefined)).toBe('');
-    expect(toDateTimeInputValue('')).toBe('');
-    expect(toDateTimeInputValue('not a date')).toBe('');
-  });
-});
-
-describe('fromDateTimeInputValue', () => {
-  it('reads the control back on the same basis it was written', () => {
-    const local = '2026-06-17T14:30';
-    const stored = fromDateTimeInputValue(local);
-
-    expect(stored).toMatch(/Z$/);
-    expect(new Date(stored).getTime()).toBe(localInstantOf(local));
-  });
-
-  it('round-trips an ISO instant through the control unchanged', () => {
-    // The invariant that makes the read/write pair safe: opening an editor and
-    // re-picking the same minute must not move the record.
-    const iso = '2026-06-17T14:30:00.000Z';
-    expect(fromDateTimeInputValue(toDateTimeInputValue(iso))).toBe(iso);
-  });
-
-  it('returns an unparseable value untouched rather than blanking it', () => {
-    expect(fromDateTimeInputValue('garbage')).toBe('garbage');
-    expect(fromDateTimeInputValue('')).toBe('');
-  });
-
-  /**
-   * The producer side of objectstack#5061. This function's output is not just
-   * "an ISO string" by convention — it IS the platform's `datetime` value
-   * contract, and `ActionParamDialog` now relies on that: it POSTs the widget's
-   * value with no conversion of its own, so a change here that dropped the zone
-   * (or emitted the control's naive wall clock) would make every datetime action
-   * param 400 again. Pinned against the real schema rather than a regex so the
-   * two cannot drift.
-   */
-  it('emits a value the platform datetime contract accepts (InstantValueSchema)', () => {
-    expect(InstantValueSchema.safeParse(fromDateTimeInputValue('2026-06-17T14:30')).success).toBe(true);
-    // The control may include seconds; those must survive into the instant.
-    expect(InstantValueSchema.safeParse(fromDateTimeInputValue('2026-06-17T14:30:45')).success).toBe(true);
-    // The shape the contract rejects — what the control itself hands us, and so
-    // exactly what must NOT come back out of this function.
-    expect(InstantValueSchema.safeParse('2026-06-17T14:30').success).toBe(false);
-  });
-});