@object-ui/fields 16.1.0 → 17.2.0

package/src/widgets/types.ts

@@ -1,10 +1,57 @@
-import { FieldMetadata } from '@object-ui/types';
+import type { AriaAttributes, FocusEventHandler, MouseEventHandler } from 'react';
+import type { DependsOnInput, FieldMetadata } from '@object-ui/types';
+
+/**
+ * Props every field widget in this package receives at RUNTIME.
+ *
+ * Named `FieldWidgetComponentProps`, not `FieldWidgetProps` (objectui#3161,
+ * objectstack#4115 ledger batch 7), adopting the name `@object-ui/app-shell`
+ * settled on for the same split in objectui#3169: `@objectstack/spec/ui` owns
+ * `FieldWidgetProps` for the DECLARED widget-plugin contract — a zod object
+ * (`FieldWidgetPropsSchema`) a plugin manifest is validated against, with
+ * `field` narrowed to `{ name?, label?, type: <the FieldType enum> }` and
+ * `readonly` / `required` carrying `.default()`s. This is the React interface
+ * the widgets in this directory actually implement, against
+ * `@object-ui/types`'s much richer `FieldMetadata`.
+ *
+ * The two are NOT interchangeable, and the divergence is not cosmetic: the
+ * spec's contract names the error slot `error`, this one names it
+ * `errorMessage`, so a widget written to the spec's declared props renders no
+ * validation message here. That divergence is tracked in objectui#3222 and is
+ * deliberately NOT resolved here — but it is now *visible*: reading
+ * `props.error` or `props.required` off this type is a compile error rather
+ * than a silent `any`.
+ *
+ * ## Why there is no `[key: string]: any` (objectui#3221)
+ *
+ * This type used to end in an index signature, "load-bearing" for the widgets'
+ * `...props` spreads. It was also why every drift above was invisible: **a type
+ * that claims to have every key can never be reported as missing one** (the
+ * objectstack#4075 mechanism). `props.required` and `props.error` were legal
+ * reads typed `any` and always `undefined` at runtime; a misspelled prop
+ * (`readOnly` for `readonly`, `onchange` for `onChange`) compiled; and any
+ * structural/parity comparison against the type was useless *in principle*,
+ * which is why the batch-7 symbol guard was the only detector that could see
+ * the collision at all.
+ *
+ * It is replaced by the CLOSED set below: the controlled-input contract, the
+ * host plumbing the form renderer genuinely forwards, and a DOM pass-through
+ * allowance. `data-*` is an open family by design (it is open in HTML too) and
+ * is expressed as a template-literal index signature, which — unlike
+ * `[key: string]` — leaves `keyof` finite, so an undeclared prop still fails.
+ *
+ * Adding a key here is a contract change: say who produces it and who reads it.
+ */
+export type FieldWidgetComponentProps<T = any> = {
+  /* ── The controlled-input contract every widget implements ─────────────── */
 
-export type FieldWidgetProps<T = any> = {
   value: T;
   onChange: (val: T) => void;
-  // Use a looser type for field to avoid complex circular dependencies for now
-  field: FieldMetadata; 
+  /**
+   * The field's metadata. Deliberately the looser `@object-ui/types` shape
+   * rather than the spec's, to avoid a circular dependency for now.
+   */
+  field: FieldMetadata;
   readonly?: boolean;
   disabled?: boolean;
   className?: string;
@@ -15,5 +62,81 @@ export type FieldWidgetProps<T = any> = {
    * widgets ignore it.
    */
   onUploadingChange?: (uploading: boolean) => void;
-  [key: string]: any;
-}
+
+  /* ── Host plumbing: what a rendering host actually forwards ─────────────── */
+
+  /**
+   * The raw authored node the widget was rendered from. Two hosts supply it:
+   * `SchemaRenderer` (`<Component schema={schema} {...schema} />`) and the
+   * form renderer's `renderFieldComponent` (`schema={props.field || ...}`),
+   * which is why ~25 widgets read `field || schema` for their config.
+   *
+   * This is a second carrier for what `field` already means, i.e. a de-facto
+   * second contract (AGENTS.md #0.1) — declared here so it is at least
+   * visible; converging the two is tracked separately.
+   */
+  schema?: FieldMetadata | Record<string, unknown>;
+  /**
+   * DataSource for widgets that query records (lookup / user / object-ref /
+   * recipient-picker / grid). Injected by the form renderer for the field
+   * types that need it, and passed directly by inline-edit hosts. Option
+   * widgets destructure it purely to keep it off their DOM spread.
+   *
+   * Left structural (`unknown`): `@object-ui/fields` must not depend on a
+   * concrete adapter — every consumer narrows it itself.
+   */
+  dataSource?: unknown;
+  /**
+   * Live sibling-field values driving cascading / role-gated options and
+   * dependent lookups (ADR-0058, #2215/#2284). The form renderer passes the
+   * in-progress record; widgets fall back to `SchemaRendererContext`.
+   */
+  dependentValues?: Record<string, unknown>;
+  /**
+   * Controlling field(s) that gate this field's option list. Normally declared
+   * on the field metadata; accepted as a prop so a host can drive the gate for
+   * a field it synthesised. Field metadata wins when both are present.
+   */
+  dependsOn?: DependsOnInput;
+  /**
+   * Hint shown when a dependency-gated option list is still waiting on its
+   * controlling field. Forwarded by the form renderer; the option widgets in
+   * this package currently discard it and render their own message instead.
+   */
+  emptyHint?: string;
+  /**
+   * Render as a single-line, borderless control for a grid cell (the inline
+   * editor and the line-item grid set it) instead of the full form layout.
+   */
+  compact?: boolean;
+  /**
+   * Receive the FULL selected record rather than just its id, so a host can
+   * auto-fill sibling fields from it (a line-item grid copying a product's
+   * price). When provided, the host owns the resulting value change.
+   */
+  onSelectRecord?: (record: Record<string, any>) => void;
+  /**
+   * Offer a "create new" affordance in a record picker, carrying whatever the
+   * user had typed. Also declarable on the field metadata.
+   */
+  onCreateNew?: (searchQuery: string) => void;
+
+  /* ── DOM pass-through: what `...props` may legitimately reach an input ──── */
+
+  id?: string;
+  /** react-hook-form's field name, spread in by the form renderer. */
+  name?: string;
+  autoFocus?: boolean;
+  tabIndex?: number;
+  onBlur?: FocusEventHandler<HTMLElement>;
+  onFocus?: FocusEventHandler<HTMLElement>;
+  onClick?: MouseEventHandler<HTMLElement>;
+} & AriaAttributes & {
+  /**
+   * Arbitrary `data-*` attributes (test ids, analytics hooks). Open by design,
+   * but a template-literal key — `keyof` stays finite, so this does NOT
+   * reintroduce the index signature objectui#3221 removed: `props.required`
+   * is still an error, `props['data-testid']` is still fine.
+   */
+  [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+};

package/src/widgets/useFieldTranslation.ts

@@ -39,6 +39,36 @@ const FIELD_DEFAULTS: Record<string, string> = {
   'lookup.nextPage': 'Next page',
   'lookup.jumpToPage': 'Jump to page',
   'lookup.retry': 'Retry',
+  // objectstack#3821 — sharing-rule authoring widgets (object-ref /
+  // recipient-picker / filter-condition). The recipient placeholder is keyed
+  // PER TYPE rather than interpolating the enum value into an English
+  // sentence, which no locale could translate.
+  'fields.objectRef.loading': 'Loading objects…',
+  'fields.objectRef.placeholder': 'Select an object',
+  'fields.objectRef.search': 'Search objects…',
+  'fields.objectRef.empty': 'No objects found',
+  'fields.recipient.selectTypeFirst': 'Select a recipient type first.',
+  'fields.recipient.loading': 'Loading…',
+  'fields.recipient.search': 'Search…',
+  'fields.recipient.empty': 'No matches',
+  'fields.recipient.select': 'Select a recipient',
+  'fields.recipient.selectUser': 'Select a user',
+  'fields.recipient.selectTeam': 'Select a team',
+  'fields.recipient.selectBusinessUnit': 'Select a business unit',
+  'fields.recipient.selectPosition': 'Select a position',
+  'fields.recipient.selectUnitAndSubordinates': 'Select a business unit',
+  'fields.filterCondition.selectObjectFirst': 'Select an object first.',
+  // objectstack#3896 — this used to be 'All records'. An empty criteria never
+  // meant "share everything"; it meant the predicate was missing, and the
+  // sharing evaluator failed open on it. Such a rule is now refused on save
+  // and shares nothing, so say that rather than advertise the old bug.
+  'fields.filterCondition.noCriteria': 'No criteria — this rule shares nothing',
+  'fields.filterCondition.criteriaRequired':
+    'Add at least one condition. A rule with no criteria would share every record, so it cannot be saved.',
+  'fields.filterCondition.invalidJson': 'Invalid JSON — the rule will match no records until fixed.',
+  'fields.filterCondition.jsonOnly': 'This criteria can only be edited as JSON',
+  'fields.filterCondition.editAsJson': 'Edit as JSON',
+  'fields.filterCondition.useVisualBuilder': 'Use visual builder',
   // objectui#2600 B5 — capability picker scope group headers.
   'capability.group.platform': 'Platform',
   'capability.group.org': 'Organization',