@object-ui/fields 17.7.0 → 18.0.0

package/README.md

@@ -42,18 +42,31 @@ View components use `getCellRenderer` to resolve the correct component for a fie
 ```tsx
 import { getCellRenderer, resolveCellRendererType, type CellRendererProps } from '@object-ui/fields';
 
-const MyGridCell = ({ field, value }: CellRendererProps) => {
+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. Passing `field.type` raw skips that mapping and draws such a
+  // 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
-  // format hint the resolver returns the declared `type` unchanged.
+  // hint the resolver returns the declared `type` unchanged.
   const Renderer = getCellRenderer(resolveCellRendererType(field));
-  return <Renderer field={field} value={value} />;
+  // `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:
@@ -110,6 +123,80 @@ 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
@@ -168,6 +255,46 @@ 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:
@@ -179,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

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;