@object-ui/fields 17.3.0 → 17.6.0

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/openNativePicker.ts

@@ -1,18 +0,0 @@
-/**
- * Open the browser's native picker (date / datetime-local / time) for an input.
- *
- * Native date/time inputs only open their picker when the user clicks the small
- * calendar/clock icon. Calling `showPicker()` on click makes the whole field
- * behave like other widgets — clicking anywhere in the box opens the picker.
- *
- * `showPicker()` can throw (unsupported browser, not user-activated, or the input
- * is disabled/hidden), so failures are swallowed and the native fallback stands.
- */
-export function openNativePicker(input: HTMLInputElement): void {
-  if (input.disabled || input.readOnly) return;
-  try {
-    (input as HTMLInputElement & { showPicker?: () => void }).showPicker?.();
-  } catch {
-    // Ignore — browsers throw when the picker can't be shown; the icon still works.
-  }
-}

package/src/widgets/personDisplay.test.ts

@@ -1,113 +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 {
-  resolvePath,
-  getPersonName,
-  getPersonInitials,
-  getPersonSubtitle,
-  getPersonAvatarUrl,
-  getPersonId,
-  matchRanges,
-} from './personDisplay';
-
-describe('personDisplay helpers', () => {
-  describe('resolvePath', () => {
-    it('reads flat and dotted paths', () => {
-      const rec = { name: 'Amy', primary_business_unit_id: { name: 'Sales' } };
-      expect(resolvePath(rec, 'name')).toBe('Amy');
-      expect(resolvePath(rec, 'primary_business_unit_id.name')).toBe('Sales');
-    });
-    it('returns undefined for missing paths or nullish records', () => {
-      expect(resolvePath({ a: {} }, 'a.b.c')).toBeUndefined();
-      expect(resolvePath(null, 'x')).toBeUndefined();
-      expect(resolvePath({ a: 1 }, '')).toBeUndefined();
-    });
-  });
-
-  describe('getPersonName', () => {
-    it('prefers the display field, then common fallbacks', () => {
-      expect(getPersonName({ name: 'Amy' })).toBe('Amy');
-      expect(getPersonName({ full_name: 'Amy Lin' }, 'full_name')).toBe('Amy Lin');
-      expect(getPersonName({ username: 'amy' })).toBe('amy');
-      expect(getPersonName('raw-id')).toBe('raw-id');
-      expect(getPersonName(null)).toBe('');
-    });
-  });
-
-  describe('getPersonInitials', () => {
-    it('takes first+last initial for multi-word latin names', () => {
-      expect(getPersonInitials('John Doe')).toBe('JD');
-      expect(getPersonInitials('mary jane watson')).toBe('MW');
-    });
-    it('takes first two letters for a single latin token', () => {
-      expect(getPersonInitials('John')).toBe('JO');
-    });
-    it('takes the given-name chars for CJK names', () => {
-      expect(getPersonInitials('张三')).toBe('张三');
-      expect(getPersonInitials('王小明')).toBe('小明');
-    });
-    it('falls back to "?" for empty', () => {
-      expect(getPersonInitials('')).toBe('?');
-      expect(getPersonInitials('   ')).toBe('?');
-    });
-  });
-
-  describe('getPersonSubtitle', () => {
-    it('joins non-empty resolved fields with a middot', () => {
-      const rec = { email: 'amy@x.io', primary_business_unit_id: { name: 'Sales' } };
-      expect(getPersonSubtitle(rec, ['primary_business_unit_id.name', 'email'])).toBe(
-        'Sales · amy@x.io',
-      );
-    });
-    it('drops empty segments and returns "" when nothing resolves', () => {
-      expect(getPersonSubtitle({ email: 'amy@x.io' }, ['primary_business_unit_id.name', 'email'])).toBe(
-        'amy@x.io',
-      );
-      expect(getPersonSubtitle({}, ['a', 'b'])).toBe('');
-      expect(getPersonSubtitle({ a: 1 }, undefined)).toBe('');
-    });
-  });
-
-  describe('getPersonAvatarUrl', () => {
-    it('reads the avatar field, undefined when absent', () => {
-      expect(getPersonAvatarUrl({ image: 'http://x/y.png' })).toBe('http://x/y.png');
-      expect(getPersonAvatarUrl({})).toBeUndefined();
-      expect(getPersonAvatarUrl({ photo: 'p' }, 'photo')).toBe('p');
-    });
-  });
-
-  describe('getPersonId', () => {
-    it('tolerates id / _id / custom / primitive', () => {
-      expect(getPersonId({ id: 1 })).toBe(1);
-      expect(getPersonId({ _id: 'a' })).toBe('a');
-      expect(getPersonId({ user_id: 9 }, 'user_id')).toBe(9);
-      expect(getPersonId('plain')).toBe('plain');
-    });
-  });
-});
-
-describe('matchRanges', () => {
-  it('returns no ranges for an empty query or empty text', () => {
-    expect(matchRanges('Amy Lin', '')).toEqual([]);
-    expect(matchRanges('', 'amy')).toEqual([]);
-  });
-
-  it('finds case-insensitive substring ranges', () => {
-    expect(matchRanges('Amy Lin', 'am')).toEqual([[0, 2]]);
-    expect(matchRanges('Sales · amy@x.io', 'amy')).toEqual([[8, 11]]);
-  });
-
-  it('finds every non-overlapping occurrence', () => {
-    expect(matchRanges('banana', 'an')).toEqual([
-      [1, 3],
-      [3, 5],
-    ]);
-  });
-});

package/src/widgets/personDisplay.ts

@@ -1,92 +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.
- */
-
-/**
- * Pure display helpers for person (sys_user) records, shared by the
- * search-first PeoplePicker's rich rows, the SelectionTray chips, and the
- * read-only user cell renderer. Kept framework-free so they're trivially
- * unit-testable and reusable by a future org-tree tier.
- */
-
-/** Resolve a possibly-dotted path (e.g. `primary_business_unit_id.name`) against a record. */
-export function resolvePath(record: any, path: string): any {
-  if (!record || !path) return undefined;
-  if (!path.includes('.')) return record[path];
-  return path.split('.').reduce((acc, key) => (acc == null ? acc : acc[key]), record);
-}
-
-/** Best display name for a person record, tolerating expanded / raw shapes. */
-export function getPersonName(record: any, nameField = 'name'): string {
-  if (record == null) return '';
-  if (typeof record !== 'object') return String(record);
-  return String(record[nameField] ?? record.name ?? record.username ?? record.label ?? '');
-}
-
-/**
- * Up-to-2-char initials for the avatar fallback.
- * - "John Doe" → "JD"; "John" → "JO"
- * - CJK single token → trailing 1–2 chars (given name): "张三" → "张三", "王小明" → "小明"
- */
-export function getPersonInitials(name: string): string {
-  const trimmed = (name || '').trim();
-  if (!trimmed) return '?';
-  const parts = trimmed.split(/\s+/).filter(Boolean);
-  if (parts.length >= 2) {
-    return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
-  }
-  const token = parts[0];
-  if (/[㐀-鿿]/.test(token)) {
-    return token.length <= 2 ? token : token.slice(-2);
-  }
-  return token.slice(0, 2).toUpperCase();
-}
-
-/** Secondary line: resolve each field path, drop empties, join with " · ". */
-export function getPersonSubtitle(record: any, fields?: string[]): string {
-  if (!record || !fields || fields.length === 0) return '';
-  return fields
-    .map(f => resolvePath(record, f))
-    .filter(v => v != null && v !== '')
-    .map(v => String(v))
-    .join(' · ');
-}
-
-/** Avatar image URL (defaults to `sys_user.image`); undefined when absent. */
-export function getPersonAvatarUrl(record: any, avatarField = 'image'): string | undefined {
-  const v = record ? resolvePath(record, avatarField) : undefined;
-  return v ? String(v) : undefined;
-}
-
-/** Record id, tolerating `id` / `_id` / a custom id field. */
-export function getPersonId(record: any, idField = 'id'): any {
-  if (!record || typeof record !== 'object') return record;
-  return record[idField] ?? record.id ?? record._id;
-}
-
-/**
- * Case-insensitive literal-substring match ranges of `query` in `text`, as
- * `[start, end)` index pairs. Used to highlight the typed term in candidate
- * rows — a strong disambiguation aid for same-named people. Pinyin matches are
- * resolved server-side and won't have client ranges; that's fine, the row still
- * shows, just without a highlight.
- */
-export function matchRanges(text: string, query: string): Array<[number, number]> {
-  const t = text ?? '';
-  const q = (query ?? '').trim().toLowerCase();
-  if (!q || !t) return [];
-  const lower = t.toLowerCase();
-  const ranges: Array<[number, number]> = [];
-  let from = 0;
-  for (;;) {
-    const idx = lower.indexOf(q, from);
-    if (idx === -1) break;
-    ranges.push([idx, idx + q.length]);
-    from = idx + q.length;
-  }
-  return ranges;
-}

package/src/widgets/recentLookups.test.ts

@@ -1,45 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { getRecentLookupIds, pushRecentLookupId } from './recentLookups';
-
-describe('recentLookups', () => {
-  beforeEach(() => localStorage.clear());
-
-  it('returns [] when nothing stored', () => {
-    expect(getRecentLookupIds('acc')).toEqual([]);
-  });
-
-  it('stores and returns ids most-recent-first', () => {
-    pushRecentLookupId('acc', 'a');
-    pushRecentLookupId('acc', 'b');
-    expect(getRecentLookupIds('acc')).toEqual(['b', 'a']);
-  });
-
-  it('de-dupes and moves a re-picked id to the front', () => {
-    pushRecentLookupId('acc', 'a');
-    pushRecentLookupId('acc', 'b');
-    pushRecentLookupId('acc', 'a');
-    expect(getRecentLookupIds('acc')).toEqual(['a', 'b']);
-  });
-
-  it('caps at 5 entries', () => {
-    for (const id of ['a', 'b', 'c', 'd', 'e', 'f', 'g']) pushRecentLookupId('acc', id);
-    const ids = getRecentLookupIds('acc');
-    expect(ids).toHaveLength(5);
-    expect(ids[0]).toBe('g');
-    expect(ids).not.toContain('a');
-  });
-
-  it('scopes per object name', () => {
-    pushRecentLookupId('acc', 'a');
-    pushRecentLookupId('prod', 'x');
-    expect(getRecentLookupIds('acc')).toEqual(['a']);
-    expect(getRecentLookupIds('prod')).toEqual(['x']);
-  });
-
-  it('ignores empty/nullish ids and object names', () => {
-    pushRecentLookupId('acc', '');
-    pushRecentLookupId('acc', null);
-    pushRecentLookupId('', 'a');
-    expect(getRecentLookupIds('acc')).toEqual([]);
-  });
-});

package/src/widgets/recentLookups.ts

@@ -1,47 +0,0 @@
-/**
- * Recently-used lookup memory.
- *
- * Mainstream record pickers (Salesforce, Dataverse, SAP, ServiceNow) surface
- * the user's recently-picked records the moment a lookup is focused — before
- * any typing. We approximate that with a small per-object ring of the last few
- * selected record ids, kept in localStorage (no backend dependency). When a
- * recent-items API later exists, this module is the single seam to swap.
- */
-
-const KEY_PREFIX = 'objectui:lookup:recent:';
-const MAX_RECENT = 5;
-
-function storage(): Storage | null {
-  try {
-    return typeof localStorage !== 'undefined' ? localStorage : null;
-  } catch {
-    // Accessing localStorage can throw in sandboxed iframes / SSR.
-    return null;
-  }
-}
-
-/** Most-recent-first list of record ids previously chosen for `objectName`. */
-export function getRecentLookupIds(objectName: string): Array<string | number> {
-  const s = storage();
-  if (!objectName || !s) return [];
-  try {
-    const raw = s.getItem(KEY_PREFIX + objectName);
-    if (!raw) return [];
-    const arr = JSON.parse(raw);
-    return Array.isArray(arr) ? arr.slice(0, MAX_RECENT) : [];
-  } catch {
-    return [];
-  }
-}
-
-/** Record that `id` was just chosen for `objectName` (moves it to the front). */
-export function pushRecentLookupId(objectName: string, id: string | number | null | undefined): void {
-  const s = storage();
-  if (!objectName || id === null || id === undefined || id === '' || !s) return;
-  try {
-    const next = [id, ...getRecentLookupIds(objectName).filter((x) => x !== id)].slice(0, MAX_RECENT);
-    s.setItem(KEY_PREFIX + objectName, JSON.stringify(next));
-  } catch {
-    // Ignore quota / serialization failures — recents are best-effort.
-  }
-}