@object-ui/fields 17.5.0 → 17.6.0

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.
-  }
-}

package/src/widgets/toDomProps.ts

@@ -1,204 +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 {
-  pickDomProps,
-  type SduiDomPassThroughKey,
-  type DomProps as CoreDomProps,
-} from '@object-ui/core';
-import type { FieldWidgetComponentProps, FieldWidgetDomProps } from './types';
-
-/**
- * The RUNTIME EXECUTOR of the "DOM pass-through" section of
- * {@link FieldWidgetComponentProps} (objectui#3291).
- *
- * ## The defect
- *
- * Field widgets forwarded their leftover props to a control with a bare
- * spread — `const { inputType, ...domProps } = props as any; <Input
- * {...domProps} />`. Whatever a host handed the widget therefore became a DOM
- * attribute. Measured on `origin/main`, a real form + a real widget:
- *
- * ```
- * <input placeholder="PH-f" zzcanary="CANARY-STR" zzcanaryobj="[object Object]"
- *        zzcanarynum="42" id="…" type="text" value="" name="f">
- * ```
- *
- * The `[object Object]` this issue is named for is an authored field-config
- * key being `String()`-ed onto an attribute. React 19 does not warn: an
- * all-lowercase unknown attribute is passed through in complete silence, which
- * is why this survived so long.
- *
- * ## Why a whitelist, and not a list of keys to drop
- *
- * The biggest leak source is not any NAMED renderer prop — it is the open tail
- * of author-supplied keys. The form renderer destructures a fixed set of known
- * keys and forwards `...fieldProps` verbatim
- * (`components/src/renderers/form/form.tsx`), and `SchemaRenderer` is wider
- * still: it spreads the whole authored node as props and has no strip layer at
- * all, so on the SDUI path a widget's own spread is the ONLY line of defence.
- *
- * A blacklist enumerating today's renderer-only keys (`error`, `emptyHint`,
- * `dataSource`, `dependentValues`, `dependsOn`, `options`, `inputType`, …)
- * would pass every one of the canaries above and would not stop the next
- * authored key either. Only "keep the known-safe set, drop the rest" closes
- * it, which is what this function does.
- *
- * ## Declared = enforced
- *
- * {@link FieldWidgetComponentProps} already DECLARES the closed set of keys a
- * widget may receive, and {@link FieldWidgetDomProps} names the subset that may
- * legitimately reach a DOM element (objectui#3221). Until now that was a
- * type-level claim a widget could violate at runtime simply by spreading. This
- * function is that declaration's executable form, and TWO compile-time
- * assertions below bind them in both directions — forwarding an undeclared key
- * and declaring an unforwarded DOM key are each a compile error. Neither
- * direction can drift silently.
- *
- * ## Deliberately NOT forwarded
- *
- * `role` and other HTML global attributes are absent because the contract does
- * not declare them. They reached the DOM before this change only through the
- * open spread. If a field node should be able to author one, DECLARE it on
- * `FieldWidgetComponentProps` first and add it here — do not reopen the spread
- * (AGENTS.md #0.1: fix the contract, never widen the consumer).
- *
- * ## Where the mechanism lives now, and why the key list stayed here
- *
- * objectui#4425 phase 2 promoted this whitelist to the SDUI widget contract
- * generally, so the MECHANISM — filter by a declared key list plus the `aria-*`
- * / `data-*` open families — moved to `@object-ui/core`
- * (`utils/dom-props.ts`, `pickDomProps`), where every plugin package can reach
- * it without depending on `@object-ui/fields` (the objectui#4409
- * dependency-direction method: `plugin-chatbot` declares `@object-ui/core` and
- * does not declare this package).
- *
- * The KEY LIST did not move, because it is not the same list. Measured on
- * objectui#4431:
- *
- *  - `name` and `disabled` are here and NOT in the SDUI set: both are legal
- *    only on form controls, which is what every widget in this package renders
- *    and what `FieldWidgetComponentProps` declares. `name` on the `<div>` an
- *    SDUI container widget renders is a leak — one of the 14 attributes #4431
- *    closed — and two widgets here already hand-strip it when they spread onto
- *    something that is not a control (`ObjectRefField`'s trigger,
- *    `FileField`'s dropzone).
- *  - `role` is in the SDUI set and NOT here: `SchemaRenderer` resolves it for
- *    every node from `@objectstack/spec`'s `AriaPropsSchema`, while this
- *    contract deliberately does not declare it (see "Deliberately NOT
- *    forwarded" above).
- *
- * So: one mechanism, two declarations, each bound by the assertions below to
- * the contract it executes. Not two judges.
- */
-const DOM_PASS_THROUGH_KEYS = [
-  /* ── The contract's own "DOM pass-through" block, verbatim ─────────────── */
-  'id',
-  'name',
-  'autoFocus',
-  'tabIndex',
-  'onBlur',
-  'onFocus',
-  'onClick',
-
-  /* ── Two more declared keys that ARE valid DOM attributes ──────────────── */
-  //
-  // Both are declared on `FieldWidgetComponentProps` under the
-  // controlled-input contract rather than the DOM block, because widgets also
-  // INTERPRET them (`className` gets composed with the widget's own classes;
-  // `disabled` is OR-ed with `readonly`). They are still `class` and
-  // `disabled` on the element, and every widget here already forwards them.
-  //
-  // Withholding them would make this helper a silent styling- and
-  // interactivity-dropper: `<Input {...toDomProps(props)} />` — the shape this
-  // change teaches every future widget author to write — would quietly lose
-  // the host's className and disabled state. That is a NEW silent failure of
-  // exactly the kind the whitelist exists to prevent, so they are forwarded.
-  'className',
-  'disabled',
-] as const;
-
-type DomPassThroughKey = (typeof DOM_PASS_THROUGH_KEYS)[number];
-
-/**
- * Compile-time link to the declaration, direction 1 of 2: every key forwarded
- * at runtime must exist on {@link FieldWidgetComponentProps}. Deleting a key
- * from the contract without deleting it here is a compile error.
- *
- * Catches: helper forwards something the contract no longer declares.
- */
-type EveryForwardedKeyIsDeclared =
-  DomPassThroughKey extends keyof FieldWidgetComponentProps ? true : never;
-const _everyForwardedKeyIsDeclared: EveryForwardedKeyIsDeclared = true;
-void _everyForwardedKeyIsDeclared;
-
-/**
- * Direction 2 of 2: every key of {@link FieldWidgetDomProps} — the contract's
- * DOM pass-through block — must be one this helper actually forwards. Adding a
- * DOM key to the contract without adding it to `DOM_PASS_THROUGH_KEYS` is a
- * compile error.
- *
- * Catches: DECLARED BUT NOT DELIVERED — a key that type-checks, reads as
- * supported, and silently never reaches the element. That is the failure this
- * repo treats as first-class (objectui#3290's `aria-required` that never
- * reached a control; objectui#3222's validation slot nobody produced), and it
- * is the one direction the leak test structurally CANNOT see: that test looks
- * for attributes that arrive, not for ones that go missing.
- *
- * `className` / `disabled` are not part of `FieldWidgetDomProps` (they are
- * controlled-input keys this helper also forwards — see above), so they are
- * bound by direction 1 only. That is deliberate, not an oversight.
- */
-type EveryDeclaredDomKeyIsForwarded =
-  keyof FieldWidgetDomProps extends DomPassThroughKey ? true : never;
-const _everyDeclaredDomKeyIsForwarded: EveryDeclaredDomKeyIsForwarded = true;
-void _everyDeclaredDomKeyIsForwarded;
-
-/**
- * Direction 3, added with the core lift (objectui#4431): every key of the SDUI
- * contract's own whitelist that this contract also declares must be forwarded
- * here too, so the two lists cannot silently drift apart. `role` is the ONE
- * measured exception — the SDUI contract declares it, this one does not — and
- * naming it in the `Exclude` is what makes the divergence a deliberate,
- * reviewable act rather than an omission.
- *
- * Catches: a key added to the shared SDUI set that field widgets quietly stop
- * delivering.
- */
-type SharedSduiKey = Exclude<SduiDomPassThroughKey, 'role'>;
-type EverySharedSduiKeyIsForwarded = SharedSduiKey extends DomPassThroughKey ? true : never;
-const _everySharedSduiKeyIsForwarded: EverySharedSduiKeyIsForwarded = true;
-void _everySharedSduiKeyIsForwarded;
-
-/** The subset of `P` this helper forwards, with each key's declared type. */
-export type DomProps<P> = CoreDomProps<P, DomPassThroughKey>;
-
-/**
- * Keep only what may legitimately become a DOM attribute, and drop everything
- * else — renderer plumbing, and any extra key an author put on the field
- * config or SDUI node.
- *
- * Replaces the bare `{...props}` spread in every field widget that renders a
- * host element:
- *
- * ```tsx
- * // before — forwards whatever it was handed
- * const { inputType, ...domProps } = props as any;
- * return <Input {...domProps} … />;
- *
- * // after
- * return <Input {...toDomProps(props)} … />;
- * ```
- *
- * Semantic props a widget INTERPRETS (`value`, `onChange`, `field`,
- * `readonly`, `error`, …) are read from `props` as before; this function only
- * governs what gets spread.
- */
-export function toDomProps<P extends object>(props: P): DomProps<P> {
-  return pickDomProps(props, DOM_PASS_THROUGH_KEYS);
-}

package/src/widgets/toHostGroupProps.ts

@@ -1,102 +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 { toDomProps } from './toDomProps';
-
-/**
- * The props that make a group-labelled widget's rendered surface the thing its
- * host label actually NAMES, on the surfaces that are not controls
- * (objectui#3990).
- *
- * ## What it is for
- *
- * A widget declared `labelling: 'group'` (objectui#3961) is told by the form
- * renderer: your label publishes an `id` and drops its `for`, so name yourself
- * by IDREF. The renderer hands down exactly two facts that address the field as
- * a WHOLE:
- *
- *  - `id` — the host's control id (`…-form-item`), the id the label's `for`
- *    used to point at;
- *  - `aria-labelledby` — the IDREF of that visible label.
- *
- * Every editable branch already consumes them inside its wider `toDomProps`
- * spread. The branches that returned EARLY did not — a field-level
- * `readonly: true`, or an option list with zero offered options — so the label
- * published an id that no element in the document referenced. Measured on
- * `origin/main`, one field per row, reading the host label against the DOM:
- *
- * ```
- * multiselect  readonly+value   consumers=0  byLabelText=0  namedByRole=[]
- * multiselect  readonly+empty   consumers=0  byLabelText=0  namedByRole=[]
- * multiselect  zeroOptions      consumers=0  byLabelText=0  namedByRole=[]
- * multiselect  editable         consumers=1  byLabelText=1  namedByRole=[group:1]
- * ```
- *
- * All seven group-labelled types measured the same, in every readonly state.
- * This is quieter than the dangling `for` #3961 replaced: a `for` that resolves
- * to nothing can at least be swept for, while "a label published an id and
- * nobody consumed it" looks like healthy markup.
- *
- * ## Why this narrow pair, and not the whole `toDomProps` result
- *
- * Everything else in the DOM pass-through addresses a CONTROL, and a readonly
- * display has none: `aria-describedby` / `aria-required` are announced when
- * focus lands on something focusable, `disabled` / `tabIndex` / the focus
- * handlers only mean something on an interactive element, and `name` is
- * DOM-legal on form controls only — on a `div` it is exactly the leak
- * objectui#3291 sweeps for. Spreading the full result would also put the host's
- * `className` on top of the widget's own, because the widgets whose readonly
- * surface is a placeholder or a plain container (`EmptyValue`, `FileField`,
- * `AddressField`) keep `className` inside `props`.
- *
- * ## Why `role` travels with the two keys
- *
- * `aria-labelledby` on a role-less `div` / `span` names NOTHING — `generic`
- * prohibits an author name — so the pair is inert without a role that supports
- * naming. `group` is the one that fits a readonly surface: it names a set of
- * values (chips, checked labels, stars, file names, a formatted address)
- * without promising the interactivity `textbox` or `radiogroup` would. It is
- * deliberately NOT the role the same widget answers with while editable:
- * `RadioField`'s readonly branch renders the chosen label as text with no radios
- * left in it, and `FileField`'s renders file names with no dropzone button.
- *
- * The role is emitted ONLY when a host actually named the field, mirroring
- * every editable branch's `isLabelledGroup` test: standalone rendering (the
- * grid's inline cell editor, a bare SDUI node) hands down neither key, so every
- * value here is `undefined`, React emits no attribute, and that markup stays
- * byte-identical to what it was.
- */
-export interface HostGroupProps {
-  /** The host's control id — the id its label would have pointed `for` at. */
-  id?: string;
-  /** IDREF of the host's visible label. */
-  'aria-labelledby'?: string;
-  /** `'group'` when — and only when — a host named this surface. */
-  role?: 'group';
-}
-
-/**
- * Read the two whole-field keys out of a widget's leftover props, plus the role
- * that makes them mean something. See {@link HostGroupProps}.
- *
- * Routed through {@link toDomProps} rather than reading `props` directly so the
- * pair keeps ONE gate: those keys reach an element only if the DOM pass-through
- * whitelist still forwards them, and its two compile-time assertions bind that
- * whitelist to the props contract in both directions.
- */
-export function toHostGroupProps(props: {
-  id?: string;
-  'aria-labelledby'?: string;
-}): HostGroupProps {
-  const { id, 'aria-labelledby': labelledBy } = toDomProps(props);
-  return {
-    id,
-    'aria-labelledby': labelledBy,
-    ...(labelledBy != null ? { role: 'group' as const } : null),
-  };
-}