@object-ui/fields 17.6.0 → 18.0.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,14 +40,33 @@ 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);
-  return <Renderer field={field} value={value} />;
+import { getCellRenderer, resolveCellRendererType, type CellRendererProps } from '@object-ui/fields';
+
+const MyGridCell = ({ field, value, row }: CellRendererProps & { row: Record<string, unknown> }) => {
+  // 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, and one declaring a widget with a read cell of its own
+  // (`widget: 'object-ref'`, `widget: 'recipient-picker'`) resolves to that
+  // cell. Passing `field.type` raw skips that mapping and draws such a
+  // column as bare text, silently. Resolving first is never worse: with no
+  // hint the resolver returns the declared `type` unchanged.
+  const Renderer = getCellRenderer(resolveCellRendererType(field));
+  // `dependentValues` is the row, for a cell whose value only means something
+  // beside a sibling column: a `recipient-picker` face reads the row's
+  // `recipient_type` from it. Without it, that face draws the stored text.
+  return <Renderer field={field} value={value} dependentValues={row} />;
 };
 ```
 
+This package registers the `object-ref` and `recipient-picker` keys with the stored
+text as their default face. A host that can read the referenced lists registers faces
+that name the value under the same keys (`registerFieldRenderer`); the console's live in
+`@object-ui/app-shell`. They name a value as the edit widgets do, through the kind table
+and the spellings this package publishes for it: `RECIPIENT_RECORD_KINDS`,
+`RECIPIENT_REGISTRY_KINDS`, `FIELD_RECIPIENT_TYPE`, `recipientCandidateLabel`,
+`objectRefOptionLabel` and the shared `UnresolvedReferenceMark` drawing.
+
 ## Standard Field Types
 
 Supported types out of the box:
@@ -55,6 +79,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 +123,178 @@ 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.
 
+### Resolving declared action params
+
+An action param is declared either inline (`name` + `type`) or field-backed
+(`field`, plus `objectOverride` when the field lives on another object). Before
+a dialog can render one, it has to be resolved against the object's field
+definitions. This package holds the one resolver for that, shared by the
+record page's action dialog (`@object-ui/app-shell`) and the selection bar's
+bulk dialog (`@object-ui/plugin-grid`):
+
+```ts
+import {
+  resolveActionParams,
+  withKnownObjects,
+  type RawActionParam,
+  type ResolveActionParamsContext,
+} from '@object-ui/fields';
+
+type KnownObject = ResolveActionParamsContext['objects'][number];
+
+// The object definitions the caller renders, and the ones the session's
+// metadata store holds (`useMetadata().objects` from `@object-ui/react`).
+declare const callerObjects: KnownObject[];
+declare const storeObjects: KnownObject[];
+
+const params: RawActionParam[] = [
+  { field: 'crm_campaign', objectOverride: 'crm_campaign_member' }, // field-backed
+  { name: 'note', type: 'textarea', label: 'Note' }, // inline
+];
+
+const resolved = resolveActionParams(params, {
+  objectName: 'crm_lead', // the owner when a param names no objectOverride
+  objects: withKnownObjects(callerObjects, storeObjects), // the caller's defs win by name
+  fieldLabel: (_objectName, _fieldName, fallback) => fallback,
+  locale: 'en',
+});
+// resolved[0] takes its type, label and `referenceTo` from the
+// `crm_campaign_member.crm_campaign` field definition; resolved[1] is as declared.
+```
+
+- `resolveActionParam(param, ctx)` / `resolveActionParams(params, ctx)` — a
+  field-backed param inherits the field's type, label, options, placeholder,
+  help text, default and picker config. Inline keys on the param override the
+  field. A param whose field is not in `ctx.objects` comes back with
+  `unresolvedField: '<object>.<field>'`, and both dialogs refuse it rather than
+  drawing an input.
+- `withKnownObjects(supplied, stored)` — unions two object lists by `name`,
+  the caller's first.
+- `resolveParamWidgetType(type)` — the param-type fold (`checkbox`,
+  `reference`, `datetime-local` aliases) onto `resolveFormWidgetType`.
+- `RESOLVED_ONLY_PARAM_KEYS` — keys of the resolved shape an author may not
+  write on a param (`referenceTo`, `displayField`, …), each with the fix the
+  resolver's dev warning prints.
+- Types: `RawActionParam`, `RawActionParamOption`, `ResolveActionParamsContext`.
+
+### A field's help line
+
+`fieldHelpText(field)` is the one read of the help line a field draws under its
+control. The record form (`@object-ui/plugin-form`) and a field-backed action
+param both use it, so the two cannot disagree:
+
+```ts
+import { fieldHelpText } from '@object-ui/fields';
+
+fieldHelpText({ inlineHelpText: 'Shown under the control', description: 'About the field' });
+// → 'Shown under the control'
+fieldHelpText({ inlineHelpText: '', description: 'About the field' });
+// → 'About the field' (an empty string reads as absent)
+```
+
+It reads `@objectstack/spec`'s `inlineHelpText`, then `description`. It does
+not read `help`: the spec refuses that key on a field, and an objectstack
+server on spec 17.7.0 or later serves a field's translated help text on
+`description`.
+
+### 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} />;
+```
+
+### Polymorphic pointer pairs (`referenceVia`)
+
+A `text` field that declares `@objectstack/spec`'s `referenceVia` is the id half
+of a two-column pointer pair: its value is a record id of the object that the
+sibling column it names holds, on the same row (`sys_approval_request.record_id`
+with `referenceVia: 'object_name'`, or `sys_activity.source_id` with
+`referenceVia: 'source_object'`). The target changes per row, and a cell
+renderer gets one value and no row, so the pair is resolved by the caller that
+holds the row (objectui#12045):
+
+- `resolveRecordPointer(field, row, optionsOf?)` is the one place the rule
+  lives. It returns `{ objectName, recordId }` (a `RecordPointer`) for a `text`
+  field with a non-empty `referenceVia` whose row fills both halves, and `null`
+  otherwise.
+- When the field also declares `referenceDeletedWhen: { field, value }` (the
+  platform's assertion that it deleted the target, objectui#12489) and the row's
+  sibling `field` holds `value`, the pair carries `deletedLabel`: that option's
+  label from `optionsOf(field)`, the options the caller draws `select` cells
+  with. A face draws it as a tombstone and reads and links nothing; the default
+  face draws it in place of the record id.
+- `RECORD_POINTER_CARD_TYPE` is the registry key a resolved pair is drawn with,
+  the pair as the renderer's `value`. This package registers a default under it
+  that draws the record id as text, so nothing changes for a host that does not
+  register a face. `@object-ui/app-shell` registers its record preview card
+  there.
+
+The record details grid in `@object-ui/plugin-detail` is the call site today;
+list cells are not one yet.
+
+```tsx
+import { getCellRenderer, resolveRecordPointer, RECORD_POINTER_CARD_TYPE } from '@object-ui/fields';
+
+function PointerValue({ field, row }: { field: { name: string; type: string; referenceVia?: string }; row: Record<string, unknown> }) {
+  const pointer = resolveRecordPointer(field, row);
+  if (!pointer) return <>{String(row[field.name] ?? '')}</>;
+  const Face = getCellRenderer(RECORD_POINTER_CARD_TYPE);
+  return <Face value={pointer} field={{ name: field.name, type: 'text' }} />;
+}
+```
+
 ### File uploads in line-item grids
 
 `GridField` (the master-detail line-items grid) supports `type: 'file'` columns:
@@ -83,6 +306,21 @@ or photo per row without opening the row form (objectui#2360). Columns accept
 exported as `FileCell`). Auto-derived subform columns map `file`/`image`/
 `avatar` fields to file columns instead of dropping them.
 
+### Registry-name pickers (`position-ref`, `permission-ref`)
+
+A `text` field that stores the machine name of one registry item declares
+`widget: 'position-ref'` or `widget: 'permission-ref'` (resolved as
+`field:<widget>`). The widget lists that registry through the data source's
+`listMetadataItems(type)`, shows each item's label beside its name, and writes
+the name only. A stored name the loaded registry lacks stays, flagged *not
+found*. `position-ref` leaves out the audience anchors (the spec's
+`AUDIENCE_ANCHOR_POSITIONS`: `everyone`, `guest`), because the server refuses
+an anchor as a grant target; a stored anchor still shows as its own option.
+When the adapter cannot list a registry, the list is empty, or the
+load fails, it is a text box that takes the typed name (a failure is shown with
+its cause). See
+[`content/docs/guide/fields.md`](../../content/docs/guide/fields.md).
+
 ### Multi-value selects
 
 A `select` field declared `multiple: true` selects zero-or-more values (spec
@@ -111,6 +349,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

@@ -39,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/fieldHelpText.d.ts

@@ -0,0 +1,41 @@
+import { BaseFieldMetadata } from '@object-ui/types';
+/**
+ * The help line a field draws under its control: the ONE read of a field
+ * definition's help text (objectui#12213). The order lives here and nowhere
+ * else, and both of its readers call this function:
+ *
+ *   - `@object-ui/plugin-form`, for the record form's help line. `ObjectForm`'s
+ *     field builder and `fromObjectSchema` both call it, so the flat, sectioned
+ *     and tabbed forms cannot drift apart.
+ *   - `resolveActionParam` in this package, for a field-backed action param
+ *     that declares no `helpText` of its own.
+ *
+ * First non-empty value wins:
+ *
+ *   1. `inlineHelpText`, `@objectstack/spec`'s `FieldSchema.inlineHelpText`
+ *      ("Help text displayed below the field in forms"). Studio's object field
+ *      inspector writes it, and flow screens draw it in the same place.
+ *   2. `description`, the fallback the form always had. An objectstack server
+ *      on `@objectstack/spec` 17.7.0 or later serves a field's translated help
+ *      text here.
+ *
+ * ## `||`, not `??`
+ *
+ * An empty string reads as absent, so `inlineHelpText: ''` falls back to the
+ * description instead of hiding it. The spec declares no setting that hides
+ * the help line, and Studio's inspector stores a cleared box as no key at all
+ * (`inlineHelpText: v || undefined`). With `??`, an empty string would become
+ * a second, undeclared way to suppress the description.
+ *
+ * ## `help` is not read
+ *
+ * `FieldSchema` refuses `help` by name and suggests `inlineHelpText`, so no
+ * document that passes the write door carries it. Its one producer was an
+ * objectstack server older than `@objectstack/spec` 17.7.0, whose translator
+ * put a field's translated description on the served field's `help` key;
+ * 17.7.0 serves that text on `description`. The read of that served leg is
+ * retired (the ruling on objectui#12213): translated field help needs an
+ * objectstack server on spec 17.7.0 or later. A definition that still carries
+ * `help` draws its `inlineHelpText`, else its `description`, else nothing.
+ */
+export declare function fieldHelpText(field: Pick<BaseFieldMetadata, 'inlineHelpText' | 'description'>): string | undefined;