@object-ui/fields 17.7.0 → 18.0.0

package/dist/index.css

@@ -119,6 +119,9 @@
   .cursor-zoom-in {
     cursor: zoom-in;
   }
+  .grid-cols-\[auto_minmax\(0\,max-content\)\] {
+    grid-template-columns: auto minmax(0,max-content);
+  }
   .gap-x-3 {
     column-gap: calc(var(--spacing, 0.25rem) * 3);
   }
@@ -307,12 +310,24 @@
   .pr-8 {
     padding-right: calc(var(--spacing, 0.25rem) * 8);
   }
+  .pr-9 {
+    padding-right: calc(var(--spacing, 0.25rem) * 9);
+  }
+  .pr-16 {
+    padding-right: calc(var(--spacing, 0.25rem) * 16);
+  }
   .pl-0\.5 {
     padding-left: calc(var(--spacing, 0.25rem) * 0.5);
   }
   .pl-9 {
     padding-left: calc(var(--spacing, 0.25rem) * 9);
   }
+  .align-top {
+    vertical-align: top;
+  }
+  .text-\[9px\] {
+    font-size: 9px;
+  }
   .text-\[color\:var\(--os-badge-fg\)\] {
     color: var(--os-badge-fg);
   }
@@ -358,9 +373,6 @@
   .text-yellow-800 {
     color: var(--color-yellow-800, oklch(47.6% 0.114 61.907));
   }
-  .underline-offset-2 {
-    text-underline-offset: 2px;
-  }
   .opacity-30 {
     opacity: 30%;
   }
@@ -379,6 +391,10 @@
       --tw-ring-color: color-mix(in oklab, var(--color-destructive, hsl(var(--destructive))) 50%, transparent);
     }
   }
+  .invert {
+    --tw-invert: invert(100%);
+    filter: var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,);
+  }
   .duration-150 {
     --tw-duration: 150ms;
     transition-duration: 150ms;
@@ -509,14 +525,28 @@
     }
   }
   @media (width >= 40rem) {
+    .sm\:ml-auto {
+      margin-left: auto;
+    }
     .sm\:max-w-4xl {
       max-width: var(--container-4xl, 56rem);
     }
+    .sm\:max-w-xl {
+      max-width: var(--container-xl, 36rem);
+    }
     .sm\:justify-between {
       justify-content: space-between;
     }
+    :where(.sm\:space-x-0 > :not(:last-child)) {
+      --tw-space-x-reverse: 0;
+      margin-inline-start: 0;
+      margin-inline-end: 0;
+    }
   }
   @media (width >= 64rem) {
+    .lg\:max-w-4xl {
+      max-width: var(--container-4xl, 56rem);
+    }
     .lg\:max-w-5xl {
       max-width: var(--container-5xl, 64rem);
     }
@@ -524,6 +554,9 @@
   .dark\:border-\[color\:var\(--os-badge-border-dark\)\]:where(.dark, .dark *) {
     border-color: var(--os-badge-border-dark);
   }
+  .dark\:border-amber-700:where(.dark, .dark *) {
+    border-color: var(--color-amber-700, oklch(55.5% 0.163 48.998));
+  }
   .dark\:border-blue-900\/60:where(.dark, .dark *) {
     border-color: color-mix(in srgb, oklch(37.9% 0.146 265.522) 60%, transparent);
     @supports (color: color-mix(in lab, red, red)) {
@@ -584,6 +617,9 @@
   .dark\:bg-\[color\:var\(--os-dot-bg-dark\)\]:where(.dark, .dark *) {
     background-color: var(--os-dot-bg-dark);
   }
+  .dark\:bg-amber-950:where(.dark, .dark *) {
+    background-color: var(--color-amber-950, oklch(27.9% 0.077 45.635));
+  }
   .dark\:bg-blue-950\/40:where(.dark, .dark *) {
     background-color: color-mix(in srgb, oklch(28.2% 0.091 267.935) 40%, transparent);
     @supports (color: color-mix(in lab, red, red)) {
@@ -644,6 +680,9 @@
   .dark\:text-\[color\:var\(--os-badge-fg-dark\)\]:where(.dark, .dark *) {
     color: var(--os-badge-fg-dark);
   }
+  .dark\:text-amber-100:where(.dark, .dark *) {
+    color: var(--color-amber-100, oklch(96.2% 0.059 95.617));
+  }
   .dark\:text-blue-300:where(.dark, .dark *) {
     color: var(--color-blue-300, oklch(80.9% 0.105 251.813));
   }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { default as React } from 'react';
 import { FieldMetadata } from '@object-ui/types';
-import { PercentScale, humanizeLabel, formatDate, formatDateTime, formatDateTimeCompactParts, formatRelativeDate, ComponentMeta, DateDisplayOptions } from '@object-ui/core';
+import { PercentScale, humanizeLabel, formatDate, formatDateTime, formatDateTimeCompactParts, formatRelativeDate, RegistryComponentMeta, DateDisplayOptions } from '@object-ui/core';
 import { formatCurrency, percentCellScale } from './widgets/number-format.js';
 import { coerceToSafeValue } from './coerceToSafeValue.js';
 import { resolveFieldCurrency } from './currency.js';
@@ -33,6 +33,29 @@ export interface CellRendererProps {
     field: FieldMetadata;
     isEditing?: boolean;
     onChange?: (value: any) => void;
+    /**
+     * The row's values, for a renderer whose value only means something next to
+     * a sibling column — the cell-side counterpart of the edit widget's
+     * `FieldWidgetComponentProps.dependentValues` (objectui#12613). The console's
+     * `recipient-picker` face reads the row's `recipient_type` from it, as the
+     * picker reads the form record's.
+     *
+     * A call site that holds the row passes it; a renderer that needs a sibling
+     * and gets none draws the stored value as the text cell does, so a call site
+     * that does not pass it changes nothing.
+     */
+    dependentValues?: Record<string, unknown>;
+    /**
+     * The host's answer to "is this declared deadline settled for this row?"
+     * (objectui#11815) — `isDeadlineSettled` from `@object-ui/core`, which
+     * evaluates the field's `settledWhen` against the row the host holds. A cell
+     * cannot evaluate a predicate, so the host hands it the verdict.
+     *
+     * While it is `true` the `date` and `datetime` cells paint no overdue wording
+     * and no overdue colour: the relative wording falls back to the neutral
+     * phrase a non-deadline reads. Absent or `false` changes nothing.
+     */
+    deadlineSettled?: boolean;
 }
 export { coerceToSafeValue };
 export { resolveFieldCurrency };
@@ -148,11 +171,11 @@ export declare function BooleanCellRenderer({ value, field }: CellRendererProps)
 /**
  * Date field cell renderer
  */
-export declare function DateCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+export declare function DateCellRenderer({ value, field, deadlineSettled }: CellRendererProps): React.ReactElement;
 /**
  * DateTime field cell renderer (Airtable-style with date and time visually separated)
  */
-export declare function DateTimeCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+export declare function DateTimeCellRenderer({ value, field, deadlineSettled }: CellRendererProps): React.ReactElement;
 /** The six pill colors plus the two dot colors derived from one declared hex. */
 export interface HexBadgePalette {
     bg: string;
@@ -273,9 +296,47 @@ export declare function ImageCellRenderer({ value }: CellRendererProps): React.R
  */
 export declare function LookupCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
 /**
- * Formula field cell renderer (read-only)
+ * Formula field cell renderer (read-only). `summary` is registered to it too.
+ *
+ * The TABLE face of a formula; `FormulaField`'s read-only branch is its FORM
+ * face, and the two read one rule (objectui#11748): the declared `returnType`,
+ * or, with none, a JS number as a number and anything else as text. Each type
+ * is then drawn through the calls the matching field type's faces make, so
+ * one stored value reads the same in the form and in the table. The rule is
+ * spelled in both modules because this barrel and the lazily loaded widget may
+ * not import each other; `__tests__/formulaFaces.returnType-11748.test.tsx`
+ * compares the two faces' text for every declared type.
  */
-export declare function FormulaCellRenderer({ value }: CellRendererProps): React.ReactElement;
+export declare function FormulaCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * The shipped PRESENTATION of an unresolved reference, shared by the two
+ * renderers that state one (objectui#8434 for `user`, objectui#8695 for
+ * `lookup` / `master_detail` / `tree`), and published for the host faces of the
+ * widget-hinted reference keys (objectui#12613), which draw the same state.
+ *
+ * Only the drawing is shared. Each caller keeps its own literal i18n key and
+ * its own English fallback, because a key reaching this component as a prop
+ * would be a key `check:i18n-keys` can no longer judge — and because the two
+ * sentences are genuinely different claims: one is about a person, the other
+ * about a record of whatever object the lookup points at.
+ *
+ * ⚠️ No `pointer-events-none` here, unlike `EmptyValue`: that utility stops the
+ * span being a hit target, so a `title` on it never renders a tooltip
+ * (objectui#8506). The stated sentence has to be reachable by hovering.
+ *
+ * ⚠️ `truncate` on the inner span rather than the outer one, and the outer is
+ * `inline-flex`: `overflow: hidden` gives a flex item an automatic minimum
+ * size of zero, so the text shrinks and ellipsises instead of forcing the row
+ * wider. The full value stays reachable through the `title` sentence, which
+ * names it — that is how this shape meets objectui#3466's truncation contract
+ * (a single-line value must never expand its column and must expose its full
+ * text) with an icon in front of the text.
+ */
+export declare function UnresolvedReferenceMark({ raw, hint, className, }: {
+    raw: string;
+    hint: string;
+    className?: string;
+}): React.ReactElement;
 /**
  * User/Owner field cell renderer (with avatars)
  *
@@ -294,20 +355,126 @@ export declare function UserCellRenderer({ value, field }: CellRendererProps): R
  * @param renderer React component to render the field
  */
 export declare function registerFieldRenderer(type: string, renderer: React.FC<CellRendererProps>): void;
+/**
+ * ## Polymorphic pointer pairs: `referenceVia` (objectui#12045)
+ *
+ * `@objectstack/spec`'s `FieldSchema.referenceVia` declares a `text` field as
+ * the ID HALF of a two-column pointer pair (ADR-0052 §5): its value is a
+ * record id of the object that the SIBLING column names, on the same row.
+ * `sys_approval_request.record_id` with `referenceVia: 'object_name'` is one;
+ * `sys_activity.source_id` with `referenceVia: 'source_object'` is another.
+ *
+ * The target object varies per ROW, so the pair is resolved where the row is
+ * in hand, at the call site. {@link CellRendererProps} carries one value and no
+ * row, which is why this is a function a call site asks and not a branch inside
+ * {@link getCellRenderer}, whose dispatch stays on the field type alone.
+ *
+ * ⭐ This is the one place the rule lives. A call site that holds the row asks
+ * `resolveRecordPointer(field, row, optionsOf)`, and draws a pair it gets back
+ * with the renderer registered under {@link RECORD_POINTER_CARD_TYPE}, passing
+ * the pair as that renderer's `value`. The same call answers whether the
+ * platform asserted the target deleted on this row (`referenceDeletedWhen`,
+ * objectui#12489), so no face and no call site evaluates that predicate. This package registers a default under that key
+ * which draws the record id as text, exactly as the field drew before its pair
+ * was read, so a host with nothing better changes nothing. A host that can read
+ * records registers a richer face under the same key with
+ * {@link registerFieldRenderer}: `@object-ui/app-shell` registers its record
+ * preview card there.
+ *
+ * Two call sites ask it. The record details grid (`DetailSection` in
+ * `@object-ui/plugin-detail`) draws the pair with the renderer registered under
+ * {@link RECORD_POINTER_CARD_TYPE}. The list grid (`ObjectGrid` in
+ * `@object-ui/plugin-grid`, objectui#12608) draws it with its own cell face,
+ * not with that renderer: a face that reads its target one record at a time
+ * costs one request per row in a list, so the list face batches the page's
+ * targets into one read per object.
+ */
+export declare const RECORD_POINTER_CARD_TYPE = "record_pointer_card";
+/** One resolved pointer pair: the record a `referenceVia` field points at. */
+export interface RecordPointer {
+    /** The target's object machine name: the sibling column's value. */
+    objectName: string;
+    /** The target's record id: the pointer field's own value. */
+    recordId: string;
+    /**
+     * Present only when the platform asserted, on this row, that the target was
+     * deleted (the field's `referenceDeletedWhen` predicate holds, objectui#12489):
+     * the label of the declared option that says so, as the call site's option
+     * labels spell it. A face that receives it draws the tombstone in this text,
+     * reads nothing and links nothing. Absent on every other row, and a face
+     * then draws the pair as before.
+     */
+    deletedLabel?: string;
+}
+/**
+ * `@objectstack/spec`'s `FieldSchema.referenceDeletedWhen`: the sibling
+ * `select` field, and the one option of it, that the platform writes on a row
+ * whose pointed-at record it deleted. The spec refuses it at parse unless the
+ * field declares `referenceVia`, `field` is a single-value `select` of the same
+ * object declaring inline `options`, and `value` is one of those options.
+ */
+type ReferenceDeletedWhen = {
+    readonly field: string;
+    readonly value: string;
+};
+/** The call site's option list for one field: what `select` cells draw with. */
+type OptionsOf = (fieldName: string) => ReadonlyArray<{
+    readonly value?: unknown;
+    readonly label?: unknown;
+}> | null | undefined;
+/**
+ * Resolve the record a `referenceVia` pointer field points at on one row, or
+ * `null` when the field is not a pointer or the row does not address a record.
+ *
+ * - `field` must be a `text` field declaring a non-empty `referenceVia`; the
+ *   spec refuses the key on every other type, so nothing else qualifies here.
+ * - The pair is read from `row`: the id under the field's own name, the object
+ *   name under the sibling column the field names.
+ * - Both halves must be non-blank strings. A half-addressed row is not a
+ *   pointer this can draw, and the caller falls back to the field's ordinary
+ *   face (the stored text).
+ *
+ * ## A deletion the platform asserts: `referenceDeletedWhen` (objectui#12489)
+ *
+ * When the field also declares `referenceDeletedWhen: { field, value }` and
+ * this row's sibling `field` holds exactly `value`, the pair comes back with
+ * `deletedLabel`: the label of that declared option, looked up in
+ * `optionsOf(field)`. The call site supplies `optionsOf` because it holds the
+ * object definition and the option labels the rest of its grid draws with
+ * (localized ones included), so the tombstone and the sibling `select`'s own
+ * cell say the same thing.
+ *
+ * - Only the declared assertion marks a target deleted. A target read that
+ *   fails or answers no record says nothing about why: the platform answers a
+ *   deleted record and one outside the reader's row set alike, on purpose.
+ * - No `optionsOf`, or no option with that value among the sibling's options,
+ *   means no label to draw, and the pair comes back without `deletedLabel`.
+ *   The spec refuses a predicate whose value is not a declared option, so the
+ *   second case is not reachable from spec-valid metadata. ⛔ Never the raw
+ *   option value as the text: the tombstone is the option's own label.
+ */
+export declare function resolveRecordPointer(field: {
+    readonly name: string;
+    readonly type?: string | null;
+    readonly referenceVia?: string | null;
+    readonly referenceDeletedWhen?: ReferenceDeletedWhen | null;
+} | null | undefined, row: Readonly<Record<string, unknown>> | null | undefined, optionsOf?: OptionsOf): RecordPointer | null;
 /**
  * Resolve the canonical cell-renderer key for a field. Accepts either a
  * raw type string (back-compat) or a field-metadata object so that
  * format hints (`format: 'phone'` etc.) can promote a plain `text`
- * field to its richer renderer counterpart.
+ * field to its richer renderer counterpart, and a declared `widget` with
+ * a read cell of its own (`WIDGET_CELL_RENDERER_TYPES`) to that cell.
  */
 export declare function resolveCellRendererType(fieldOrType: string | {
     type?: string;
     format?: string;
+    widget?: string;
 } | null | undefined): string;
 /**
- * Renders structured/embedded values (json, object, composite, record,
- * address, geolocation) as compact, readable JSON. Objects and arrays are
- * stringified; primitives fall through to their string form.
+ * Renders a free-form JSON value (`json`, `object`) as compact, readable JSON,
+ * and is the fallback face for a shape a structured renderer cannot recognize
+ * (`location` / `geolocation`, `address`, `composite` / `record`).
  */
 export declare function JsonCellRenderer({ value }: CellRendererProps): React.ReactElement;
 /**
@@ -497,6 +664,14 @@ export declare function formatFileSize(bytes: number): string;
  * Build validation rules from field metadata
  * @param field - Field metadata from ObjectStack
  * @returns Validation rule object compatible with react-hook-form
+ *
+ * ⛔ No field-level `pattern` / `pattern_message` / `validate` (objectui#12242,
+ * maintainer ruling A). `@objectstack/spec`'s `FieldSchema` refuses all three
+ * by name, so no published object carries them, and the field metadata types
+ * retire them as `never`. A regex check is the OBJECT's `format` validation
+ * rule (`validations[]`), which the server runs on every write that touches
+ * the field and refuses with the rule's message; this function adds no client
+ * pre-check of it.
  */
 export declare function buildValidationRules(field: any): any;
 /**
@@ -535,12 +710,12 @@ declare const fieldWidgetMap: {
     date: () => Promise<{
         default: React.ComponentType<any>;
     } | {
-        default: typeof import('./widgets/DateField.js').DateField;
+        default: typeof import('./widgets/date-picker/DatePickerField.js').DatePickerField;
     }>;
     datetime: () => Promise<{
         default: React.ComponentType<any>;
     } | {
-        default: typeof import('./widgets/DateTimeField.js').DateTimeField;
+        default: typeof import('./widgets/date-picker/DatePickerField.js').DateTimePickerField;
     }>;
     time: () => Promise<{
         default: React.ComponentType<any>;
@@ -732,6 +907,16 @@ declare const fieldWidgetMap: {
     } | {
         default: typeof import('./widgets/RecipientPickerField.js').RecipientPickerField;
     }>;
+    'position-ref': () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RegistryRefField.js').PositionRefField;
+    }>;
+    'permission-ref': () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RegistryRefField.js').PermissionRefField;
+    }>;
 };
 /** The registered field widget keys, as a literal union (objectui#4857). */
 export type RegisteredFieldWidgetType = keyof typeof fieldWidgetMap;
@@ -766,6 +951,23 @@ export declare function resolveFormWidgetType(fieldType: string): string;
  * which converged the three private copies that preceded it).
  */
 export { CASCADE_OPTION_WIDGET_TYPES } from '@object-ui/core';
+/**
+ * The ONE action-param resolver (objectui#12105): a declared action param —
+ * inline, or field-backed via `{ field, objectOverride }` — resolved against
+ * the object's field definitions into the `ActionParamDef` a param dialog
+ * renders. Exported from here because this is the package both of its callers
+ * depend on: app-shell's single-record `ActionParamDialog` and plugin-grid's
+ * selection-bar bulk dialog (a promoted action's params). See the module.
+ */
+export { resolveActionParam, resolveActionParams, resolveParamWidgetType, withKnownObjects, RESOLVED_ONLY_PARAM_KEYS, } from './resolveActionParams.js';
+export type { RawActionParam, RawActionParamOption, ResolveActionParamsContext, } from './resolveActionParams.js';
+/**
+ * The ONE read of a field definition's help line (objectui#12213):
+ * `inlineHelpText`, else `description`. Exported from here because both of its
+ * readers can reach this package: `@object-ui/plugin-form`'s record form and
+ * this package's own `resolveActionParam`. See the module.
+ */
+export { fieldHelpText } from './fieldHelpText.js';
 /**
  * Lazily-loaded form field widget for a field type. Shares the exact loaders
  * of {@link fieldWidgetMap} (the same components `registerField` registers for
@@ -777,7 +979,7 @@ export { CASCADE_OPTION_WIDGET_TYPES } from '@object-ui/core';
 export declare function getLazyFieldWidget(fieldType: string): React.ComponentType<any>;
 /**
  * The labelling declaration of EVERY registered field widget
- * (`ComponentMeta.labelling` — the closed `'control' | 'group' | 'display'`
+ * (`RegistryComponentMeta.labelling` — the closed `'control' | 'group' | 'display'`
  * vocabulary, objectui#3961 extended by objectui#4857). This `Record` is keyed
  * by the widget map's own literal key union, so it is exhaustive BY
  * CONSTRUCTION: registering a widget without deciding how a host's label
@@ -827,7 +1029,7 @@ export declare function getLazyFieldWidget(fieldType: string): React.ComponentTy
  * out-of-registry widgets alike; the entry here is still mandatory, because
  * "defaulted by omission" and "decided to be the default" are different facts.
  */
-export declare const FIELD_WIDGET_LABELLING: Record<RegisteredFieldWidgetType, NonNullable<ComponentMeta['labelling']>>;
+export declare const FIELD_WIDGET_LABELLING: Record<RegisteredFieldWidgetType, NonNullable<RegistryComponentMeta['labelling']>>;
 export declare function registerField(fieldType: string): void;
 /**
  * Register all field types (for backward compatibility)
@@ -870,6 +1072,7 @@ export * from './FieldEditWidget.js';
 export * from './widgets/TextField.js';
 export * from './widgets/NumberField.js';
 export * from './widgets/BooleanField.js';
+export { useBooleanValueLabel, type BooleanValueLabel } from './widgets/booleanValueLabel.js';
 export * from './widgets/SelectField.js';
 export * from './widgets/DateField.js';
 export * from './widgets/DateTimeField.js';
@@ -887,6 +1090,8 @@ export * from './widgets/CapabilityMultiSelectField.js';
 export * from './widgets/ObjectRefField.js';
 export * from './widgets/FilterConditionField.js';
 export * from './widgets/RecipientPickerField.js';
+export { objectRefOptionLabel } from './widgets/objectRefLabel.js';
+export { RECIPIENT_RECORD_KINDS, RECIPIENT_REGISTRY_KINDS, FIELD_RECIPIENT_TYPE, recipientCandidateLabel, } from './widgets/recipientKinds.js';
 export * from './widgets/RecordPickerDialog.js';
 export * from './widgets/deriveLookupColumns.js';
 export * from './widgets/FileField.js';
@@ -917,7 +1122,7 @@ export * from './widgets/CheckboxesField.js';
 export * from './widgets/TagsField.js';
 export { withFieldCarrier } from './withFieldCarrier.js';
 export { toDomProps } from './widgets/toDomProps.js';
-export type { DomProps } from './widgets/toDomProps.js';
+export type { FieldDomProps } from './widgets/toDomProps.js';
 export { toHostProps } from './widgets/toHostProps.js';
 export type { HostProps } from './widgets/toHostProps.js';
 export { toDateInputValue, toDateTimeInputValue, fromDateTimeInputValue, } from './widgets/nativeDateValue.js';