@object-ui/fields 17.5.0 → 17.7.0

package/README.md

@@ -5,7 +5,7 @@ The standard field library and registry for Object UI.
 ## Features
 
 - 📚 **Standard Fields** - Implementation of all ObjectStack protocol fields (Text, Number, Date, Lookup, etc.)
-- 🔌 **Plugin System** - `FieldRegistry` allows registering custom renderers or overriding standard ones.
+- 🔌 **Plugin System** - `registerFieldRenderer` registers custom renderers, or overrides standard ones.
 - 🛠 **Helpers** - Utilities for schema mapping, validation, and expression evaluation.
 
 ## Installation
@@ -23,10 +23,15 @@ The Field Registry is the core mechanism that allows decoupling view components
 You can override standard fields or add new ones:
 
 ```tsx
-import { registerFieldRenderer } from '@object-ui/fields';
-import { MyCustomColorPicker } from './MyCustomColorPicker';
+import { registerFieldRenderer, type CellRendererProps } from '@object-ui/fields';
+import type { FC } from 'react';
 
-// Register a new 'color' field type
+// Your own renderer — anywhere in your app; it takes the standard props bag.
+declare const MyCustomColorPicker: FC<CellRendererProps>;
+
+// ⚠️ `color` is a SHIPPED type (`ColorSwatchCellRenderer`), and `getCellRenderer`
+// reads the registry BEFORE the standard map — so this call OVERRIDES the
+// built-in renderer. To ADD a type instead, register a name nothing ships.
 registerFieldRenderer('color', MyCustomColorPicker);
 ```
 
@@ -35,10 +40,16 @@ registerFieldRenderer('color', MyCustomColorPicker);
 View components use `getCellRenderer` to resolve the correct component for a field type.
 
 ```tsx
-import { getCellRenderer } from '@object-ui/fields';
-
-const MyGridCell = ({ field, value }) => {
-  const Renderer = getCellRenderer(field.type);
+import { getCellRenderer, resolveCellRendererType, type CellRendererProps } from '@object-ui/fields';
+
+const MyGridCell = ({ field, value }: CellRendererProps) => {
+  // Resolve the renderer KEY first, then the renderer. A field's declared
+  // `type` is not always the renderer's key: a textual field carrying a
+  // format hint (`Field.text({ format: 'phone' })`) resolves to the richer
+  // renderer. Passing `field.type` raw skips that mapping and draws such a
+  // column as bare text, silently. Resolving first is never worse: with no
+  // format hint the resolver returns the declared `type` unchanged.
+  const Renderer = getCellRenderer(resolveCellRendererType(field));
   return <Renderer field={field} value={value} />;
 };
 ```
@@ -55,6 +66,33 @@ Supported types out of the box:
 - **Media**: `file`, `image`
 - **System**: `formula`, `summary`, `auto_number`
 
+### `type="number"` widgets: what is announced and what is not
+
+`NumberField`, `CurrencyField`, `PercentField` and `GeolocationField` all render
+a native `type="number"` input, so the **browser** decides what the box accepts.
+They share one reading of that, in `widgets/numberBadInput.tsx`:
+
+- **Announced.** When the browser reports `validity.badInput` — the box is
+  holding text it cannot convert, e.g. a typed `1e`, which Chromium keeps
+  DISPLAYING while `.value` reads `''` — the control is marked `aria-invalid`
+  and draws a `Not saved: …` message, reusing objectui#6716's refusal shape.
+  Both a change arm and a blur arm are wired, because pasting into an empty box
+  never moves `.value` and so fires no React change event at all. The sentence
+  resolves through the `fields.number.badInput` locale key (objectui#8148), so
+  it follows the reader's language; the example numeral each box quotes is the
+  widget's own and is interpolated rather than translated.
+- ⚠️ **Not announced, and not announceable.** Entries the browser silently
+  **truncates**: `1.2.3` stores `1.23`, `0x10` stores `10`. The characters are
+  discarded as they arrive, before any handler here runs, so no widget-side
+  guard can refuse them. Recovering them would mean abandoning `type="number"`
+  and with it the mobile numeric keyboard and the `min`/`max`/`step` spinner
+  (objectui#2572).
+
+⛔ Silence therefore means "the browser read *something*", never "the value is
+correct". User-facing wording lives in
+[the fields guide](../../content/docs/guide/fields.md). The measured browser vs
+happy-dom matrix is in `src/__tests__/numberInputBrowserReadings.ts`.
+
 ### Rendering form field widgets outside the form
 
 The full widget surface is exported for consumers that render field widgets
@@ -72,6 +110,64 @@ The app-shell `ActionParamDialog` uses these to render declared action params
 through the exact same widgets as the object form — with a drift test pinning
 param support ⊇ form support.
 
+### Enumerating the CELL renderer registry
+
+`listCellRendererTypes()` is the read-side twin of `FORM_FIELD_TYPES`: every
+field type `getCellRenderer` resolves to a renderer **of its own**, as opposed
+to the `TextCellRenderer` fallback every other spelling lands on.
+
+⚠️ It is a **function**, not a frozen constant, and the difference is
+load-bearing. `registerFieldRenderer` is published, so the cell registry can
+grow after this module is evaluated; a constant would be a snapshot taken at
+import time. Consumers that reason about "all registered cell types" — the two
+censuses in `@object-ui/fields` and `@object-ui/plugin-detail` that measure what
+every type draws — reconcile their tables against this reading so a newly
+registered type fails them by name instead of slipping past a frozen
+population (objectui#8734).
+
+### Asking whether a cell is masked
+
+`isMaskedFieldType(type)` answers whether a cell of that field type is drawn
+as a mask (`••••••`) instead of its value. It is the read-side twin of
+`isInlineExcludedFieldType()`, and a consumer that acts on a cell's value asks
+it rather than keeping its own list. The detail page's copy affordance in
+`@object-ui/plugin-detail` is one such consumer: it refuses to copy a masked
+row (objectui#8686). `MASKED_FIELD_TYPES` is the declared set behind it,
+`password` and `secret`. The standard cell of each member draws the mask, and
+the predicate answers `true` for it. Like `listCellRendererTypes()`, the
+answer is a live reading of the cell registry taken when you call it, and,
+with nothing overridden at runtime, it agrees with what `getCellRenderer`
+resolves for every type that function lists. To add a masked type, register
+the package's own mask under it with
+`registerFieldRenderer('api_token', getCellRenderer('password'))`, while
+`password` still resolves to the shipped mask. The predicate then answers
+`true` with no change to the declared set, and the detail page refuses to copy
+that row. Overriding a declared type with one of this package's own renderers
+makes the predicate answer `false`, since none of them is the mask, and the
+cell draws what that renderer draws: after
+`registerFieldRenderer('password', TextCellRenderer)` the cell shows the value
+and the detail row copies again. Overriding a declared type with a component
+of your own keeps the declared answer, `true`, because the package cannot
+tell whether an opaque component hides the value, so it errs toward
+withholding it. Your own component under an undeclared type answers `false`.
+Spellings are matched raw, the way `getCellRenderer` looks them up:
+`field:password` renders in the clear and is not masked.
+
+The mask itself is exported as `MaskedCellRenderer` (objectui#10657). A table
+that cannot type a column yet, because its object's field types are still
+loading or their read failed, draws that column WITHHELD with it rather than as
+text: `object-grid`, the related list and `object-data-table` do. It is the
+shipped mask, not whatever is registered for `password` at the time, and its
+`field` prop is optional because it reads only whether a value is present.
+`registerFieldRenderer('api_token', MaskedCellRenderer)` masks a type the same
+way the `getCellRenderer('password')` form above does.
+
+```tsx
+import { MaskedCellRenderer } from '@object-ui/fields';
+
+const withheldCell = (value: unknown) => <MaskedCellRenderer value={value} />;
+```
+
 ### File uploads in line-item grids
 
 `GridField` (the master-detail line-items grid) supports `type: 'file'` columns:
@@ -111,6 +207,10 @@ never drift). While a `dependsOn` parent is empty the control is gated; a parent
 change re-filters the list and clears a now-invalid value (scalar `select` /
 `radio` drop the value; multi-value `multiselect` / `checkboxes` prune just the
 offered-out entries).
+An option whose `label` is blank (the empty string is a legal label; an absent one is
+not) displays its `value` instead of an empty row, on the editable and the read-only
+path alike — all eight read sites across the four widgets share the one
+`optionDisplayLabel` helper in `@object-ui/core` (objectui#9230).
 Client-side hiding is UX only — gate authorization-sensitive values on the
 server too. See
 [`content/docs/fields/select.mdx`](../../content/docs/fields/select.mdx).

package/dist/FieldEditWidget.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { FieldWidgetComponentProps } from './widgets/types';
+import { FieldWidgetComponentProps } from './widgets/types.js';
 /**
  * Form field types that are deliberately NOT given an inline editor — every
  * other form widget type must be in {@link EDIT_WIDGETS}. This pairing is
@@ -10,7 +10,21 @@ import { FieldWidgetComponentProps } from './widgets/types';
 export declare const INLINE_EXCLUDED_FIELD_TYPES: Set<string>;
 /** Field types whose value is chosen in one discrete gesture (no free typing). */
 export declare const DISCRETE_EDIT_TYPES: Set<string>;
-/** True when a field type has a dedicated in-place edit widget. */
+/**
+ * True when a field type has a dedicated in-place edit widget.
+ *
+ * A RETIRED spelling answers `false` unconditionally, ahead of every table
+ * lookup (objectui#4931). This is the gate the retirement was missing: hosts
+ * ask this question to decide whether to hand a cell to {@link FieldEditWidget},
+ * and while it answered `true` for a retired spelling the whole tombstone was
+ * bypassable by delegation — the grid's inline cell editor rendered a working
+ * person picker for a field the record form refuses.
+ *
+ * Keyed on the retirement TABLE rather than on the raw `type`, and checked
+ * BEFORE `resolveInlineEditType`, so it holds even if a future retired spelling
+ * is still (or again) a key of {@link EDIT_WIDGETS} — closing the class, not
+ * one spelling.
+ */
 export declare function hasFieldEditWidget(type: string | undefined): boolean;
 /**
  * True when a field type is deliberately NOT inline-editable (alias-aware:
@@ -25,10 +39,58 @@ export declare function isInlineExcludedFieldType(type: string | undefined): boo
  * `null` for types without a registered widget so the caller can fall back to
  * a plain editor.
  *
- * `autoFocus` is forwarded because an inline-edit host enters edit mode ON a
- * field and expects the caret to land there (objectui#4220 — the detail page's
- * delegation): each widget's own `toDomProps` whitelist already carries it onto
- * the real focusable control, so nothing here needs to know which element that
- * is. A host that passes nothing is unaffected.
+ * The host's DOM pass-through set is forwarded WHOLE (objectui#6909). This
+ * component's props are `FieldWidgetComponentProps`, so a caller may already
+ * pass `id`, `name`, `autoFocus`, `tabIndex`, `onBlur`, `onFocus`, `onClick`,
+ * any `aria-*` and any `data-*` with no type error — but the body used to
+ * destructure five keys and render the widget with those, so `autoFocus` was
+ * the ONLY survivor of the whole block and everything else was silently
+ * dropped. That is this package's own first-class defect class, named in
+ * `widgets/toDomProps.ts`: a key that type-checks, reads as supported, and
+ * silently never reaches the element (objectui#3290's `aria-required`,
+ * objectui#3222's validation slot). Forwarding is not a widening: the keys were
+ * already declared, and each widget still re-filters through its own
+ * `toDomProps` before anything reaches a DOM element.
+ *
+ * `autoFocus`' original reason survives inside that set — an inline-edit host
+ * enters edit mode ON a field and expects the caret to land there
+ * (objectui#4220, the detail page's delegation) — and so does its property:
+ * each widget's own whitelist carries these onto the real focusable control, so
+ * nothing here needs to know which element that is. A host that passes nothing
+ * is unaffected.
+ *
+ * The host's NON-DOM set is forwarded WHOLE too (`f08bcd9af`), through the
+ * sibling executor `toHostProps`. The DOM fix left the other half of the
+ * contract undelivered: `error`, `onUploadingChange` and the "Host plumbing"
+ * block (`dataSource`, `dependentValues`, `dependsOn`, `dependsOnLabels`,
+ * `emptyHint`, `onSelectRecord`, `onCreateNew`) still type-checked, read as
+ * supported, and never reached the widget. `error` was the live one:
+ * `InlineFieldInput` has passed `error={error}` since PR #7109 and this factory
+ * dropped it, so a control that had failed validation never reported
+ * `aria-invalid`. Forwarding is not a widening — every one of those keys is
+ * already declared on `FieldWidgetComponentProps`, the same argument #7009
+ * landed on in this file.
+ *
+ * ⛔ They do NOT go through `toDomProps`. None of them is DOM-legal, and that
+ * whitelist is closed for exactly this reason — a `dataSource` adapter routed
+ * there becomes `dataSource="[object Object]"` on an `<input>`, the leak the
+ * helper exists to prevent. `toHostProps`' direction-3 assertion makes the two
+ * sets provably disjoint, so the order of the two spreads below is not a
+ * question anyone has to answer again.
+ *
+ * ## `dataSource` precedence: the explicit prop WINS
+ *
+ * Delivering `dataSource` can change behaviour where before it could not
+ * arrive, because the relational widgets fall back to `SchemaRendererContext`
+ * (which the grid already provides). The precedence is therefore STATED rather
+ * than left to emerge: **a host's explicit `dataSource` prop wins over the
+ * context**. That is not a new decision — `LookupField` already resolves
+ * `props.dataSource ?? lookupField?.dataSource ?? fieldMeta?.dataSource ??
+ * contextDataSource` and documents that order on the line that does it. This
+ * factory is a CONDUIT and resolves nothing: adding a resolution here would
+ * give `dataSource` a second author, the `field || schema` shape objectui#3233
+ * removed. A host that passes no `dataSource` keeps reading the context exactly
+ * as before, so no in-repo host changes behaviour. The full per-key precedence
+ * table lives on `toHostProps`, next to the list it governs.
  */
-export declare function FieldEditWidget({ field, value, onChange, readonly, autoFocus, }: FieldWidgetComponentProps<any>): React.ReactElement | null;
+export declare function FieldEditWidget(props: FieldWidgetComponentProps<any>): React.ReactElement | null;

package/dist/coerceToSafeValue.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+/**
+ * `coerceToSafeValue` — the one answer this package has to "what text does a
+ * string-typed cell draw for a value that is not a string?".
+ *
+ * ## Why this is its own module (objectui#8580)
+ *
+ * It used to be defined in `./index.tsx`, the barrel, and every text-like cell
+ * renderer there reaches it. The rich-content renderers in
+ * `./widgets/richTextDisplay.tsx` need the SAME answer — `@objectstack/spec`
+ * places `markdown` / `html` / `richtext` in the same value class as `text` /
+ * `textarea` / `code` (`STRING_VALUE_TYPES`, "Value is a plain string"), and
+ * before objectui#8580 they had a private one: `String(value)`, which drew a
+ * childless container for `[]` and the literal `[object Object]` for `{}`
+ * where `text` draws the No-value affordance and `[Object]`. That module is
+ * imported BY the barrel (`4bb940b6e` extracted it so `RichTextField` could
+ * reach the display pipelines without importing the barrel back), so it
+ * cannot import the barrel to borrow this helper without re-creating exactly
+ * the cycle that extraction removed. The helper therefore lives below both
+ * consumers. The barrel re-exports it unchanged; it is part of this package's
+ * published surface and nothing about its contract moved.
+ */
+/**
+ * Coerce a value to a safe primitive for rendering.
+ * Handles MongoDB wrapper types ($numberDecimal, $oid, $date), expanded
+ * reference objects, and arrays so that no raw object is ever passed as
+ * a React child — preventing React error #310.
+ *
+ * A STRING is returned verbatim, whatever its shape. This helper is reached by
+ * every text-like cell (`text`, `textarea`, `code`, `time`, `auto_number`,
+ * `qrcode` all register to `TextCellRenderer`), so it may not classify a value
+ * by looking at its characters. It used to: any string starting `{`/`[` and
+ * ending `}`/`]` was `JSON.parse`d and the result run through the
+ * reference-label extraction below, which answers `[Object]` for an object
+ * carrying no name/label/externalId/id. That turned the showcase Field Zoo's
+ * `code` value `{"ok": true}` into the literal `[Object]`, and `[1, 2, 3]` in a
+ * text field into `1, 2, 3` (objectui#7246).
+ *
+ * Shape is not a type. The reference case the parse was written for
+ * (objectui#1426 — an unresolved external-id ref arriving as
+ * '{"externalId":"Website Relaunch"}') belongs to reference-TYPED columns and
+ * is handled there: `LookupCellRenderer` carries its own JSON-string branch,
+ * which resolves the label through the referenced object's schema and links to
+ * the record — neither of which this type-blind helper could ever do. Scoped,
+ * not dropped; both halves are pinned in
+ * `__tests__/textCellJsonText-7246.test.tsx`.
+ */
+export declare function coerceToSafeValue(value: unknown): string | number | boolean | null | undefined;

package/dist/currency.d.ts

@@ -44,7 +44,7 @@ export declare function currencyFractionDigits(currency: string): number;
  * Falls back to `currency` itself — the code as given — in the three cases
  * where ICU cannot answer, because a bare code is a legitimate adornment (it is
  * what ICU itself returns for KWD/BHD/CHF/ISK, and what
- * `formatAmount`'s own bad-code branch renders beside it):
+ * `formatCurrency`'s own bad-code branch renders beside it):
  *
  *  1. an invalid currency code — `Intl` throws `RangeError: Invalid currency
  *     code`;

package/dist/field-type-alias.d.ts

@@ -19,6 +19,22 @@ export interface FieldTypeMappingConfig {
     /** `FieldSchema.multiple` — the field holds zero-or-more values. */
     multiple?: boolean | null;
 }
+/**
+ * The retirement half of this module — the TOMBSTONE table
+ * {@link RETIRED_FIELD_TYPES}, the {@link isRetiredFieldType} gate, and the
+ * once-per-spelling reporter — now lives in `@object-ui/core`
+ * (`utils/retired-field-types.ts`), hoisted there by objectui#4914 so that
+ * `@object-ui/components`' filter builder can read the SAME table: `fields`
+ * depends on `components`, so the six ruled predicate faces could not all
+ * reach a table that lived here. The module's docblock carries the full
+ * reasoning, including why a second copy in `components` would have broken the
+ * ruling's "fires once" clause on day one.
+ *
+ * Re-exported from here, and from the `./index` barrel, so `@object-ui/fields`'
+ * published surface is exactly what it was plus the newly ruled gate. This file
+ * remains the retirement table's first consumer (the `field:text` tail below).
+ */
+export { RETIRED_FIELD_TYPES, isRetiredFieldType, reportRetiredFieldType, resetRetiredFieldTypeReports, } from '@object-ui/core';
 /**
  * Map field type to form component type
  *