@object-ui/fields 17.2.0 → 17.3.0

package/dist/widgets/toDomProps.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+/**
+ * The RUNTIME EXECUTOR of the "DOM pass-through" section of
+ * {@link FieldWidgetComponentProps} (objectui#3291).
+ *
+ * ## The defect
+ *
+ * Field widgets forwarded their leftover props to a control with a bare
+ * spread — `const { inputType, ...domProps } = props as any; <Input
+ * {...domProps} />`. Whatever a host handed the widget therefore became a DOM
+ * attribute. Measured on `origin/main`, a real form + a real widget:
+ *
+ * ```
+ * <input placeholder="PH-f" zzcanary="CANARY-STR" zzcanaryobj="[object Object]"
+ *        zzcanarynum="42" id="…" type="text" value="" name="f">
+ * ```
+ *
+ * The `[object Object]` this issue is named for is an authored field-config
+ * key being `String()`-ed onto an attribute. React 19 does not warn: an
+ * all-lowercase unknown attribute is passed through in complete silence, which
+ * is why this survived so long.
+ *
+ * ## Why a whitelist, and not a list of keys to drop
+ *
+ * The biggest leak source is not any NAMED renderer prop — it is the open tail
+ * of author-supplied keys. The form renderer destructures a fixed set of known
+ * keys and forwards `...fieldProps` verbatim
+ * (`components/src/renderers/form/form.tsx`), and `SchemaRenderer` is wider
+ * still: it spreads the whole authored node as props and has no strip layer at
+ * all, so on the SDUI path a widget's own spread is the ONLY line of defence.
+ *
+ * A blacklist enumerating today's renderer-only keys (`error`, `emptyHint`,
+ * `dataSource`, `dependentValues`, `dependsOn`, `options`, `inputType`, …)
+ * would pass every one of the canaries above and would not stop the next
+ * authored key either. Only "keep the known-safe set, drop the rest" closes
+ * it, which is what this function does.
+ *
+ * ## Declared = enforced
+ *
+ * {@link FieldWidgetComponentProps} already DECLARES the closed set of keys a
+ * widget may receive, and {@link FieldWidgetDomProps} names the subset that may
+ * legitimately reach a DOM element (objectui#3221). Until now that was a
+ * type-level claim a widget could violate at runtime simply by spreading. This
+ * function is that declaration's executable form, and TWO compile-time
+ * assertions below bind them in both directions — forwarding an undeclared key
+ * and declaring an unforwarded DOM key are each a compile error. Neither
+ * direction can drift silently.
+ *
+ * ## Deliberately NOT forwarded
+ *
+ * `role` and other HTML global attributes are absent because the contract does
+ * not declare them. They reached the DOM before this change only through the
+ * open spread. If a field node should be able to author one, DECLARE it on
+ * `FieldWidgetComponentProps` first and add it here — do not reopen the spread
+ * (AGENTS.md #0.1: fix the contract, never widen the consumer).
+ */
+declare const DOM_PASS_THROUGH_KEYS: readonly ["id", "name", "autoFocus", "tabIndex", "onBlur", "onFocus", "onClick", "className", "disabled"];
+type DomPassThroughKey = (typeof DOM_PASS_THROUGH_KEYS)[number];
+/** The subset of `P` this helper forwards, with each key's declared type. */
+export type DomProps<P> = Pick<P, Extract<keyof P, DomPassThroughKey>> & {
+    [K in Extract<keyof P, `data-${string}` | `aria-${string}`>]: P[K];
+};
+/**
+ * Keep only what may legitimately become a DOM attribute, and drop everything
+ * else — renderer plumbing, and any extra key an author put on the field
+ * config or SDUI node.
+ *
+ * Replaces the bare `{...props}` spread in every field widget that renders a
+ * host element:
+ *
+ * ```tsx
+ * // before — forwards whatever it was handed
+ * const { inputType, ...domProps } = props as any;
+ * return <Input {...domProps} … />;
+ *
+ * // after
+ * return <Input {...toDomProps(props)} … />;
+ * ```
+ *
+ * Semantic props a widget INTERPRETS (`value`, `onChange`, `field`,
+ * `readonly`, `error`, …) are read from `props` as before; this function only
+ * governs what gets spread.
+ */
+export declare function toDomProps<P extends object>(props: P): DomProps<P>;
+export {};

package/dist/widgets/types.d.ts

@@ -1,5 +1,47 @@
 import { AriaAttributes, FocusEventHandler, MouseEventHandler } from 'react';
 import { DependsOnInput, FieldMetadata } from '@object-ui/types';
+/**
+ * DOM pass-through: what a widget's `...props` spread may legitimately put on
+ * the element it renders.
+ *
+ * A NAMED type rather than an inline block of {@link FieldWidgetComponentProps}
+ * so the compiler can bind it to its runtime executor in BOTH directions
+ * (objectui#3291). `toDomProps` asserts:
+ *
+ *  - every key it forwards is declared on the widget contract — deleting one
+ *    here without deleting it there is a compile error;
+ *  - every key of THIS type is one it forwards — adding one here without
+ *    adding it to `DOM_PASS_THROUGH_KEYS` is a compile error too.
+ *
+ * The second direction is the one that matters for the failure mode this repo
+ * treats as first-class: DECLARED BUT NOT DELIVERED (objectui#3290's
+ * `aria-required` that never reached a control, objectui#3222's validation slot
+ * nobody produced). Without it, a key added here would type-check, read as
+ * supported, and silently never reach the DOM — and the leak test cannot see
+ * that class of bug, because it looks for attributes that ARRIVE, not for ones
+ * that go missing.
+ *
+ * `className` and `disabled` are deliberately NOT here. They are DOM-legal and
+ * `toDomProps` does forward them, but they are declared on the controlled-input
+ * block of {@link FieldWidgetComponentProps} because widgets also INTERPRET
+ * them (className is composed with the widget's own classes; disabled is OR-ed
+ * with readonly). They are therefore bound in the forward direction only.
+ *
+ * `AriaAttributes` and the `data-${string}` family are matched by prefix at
+ * runtime rather than key-by-key, so they are intersected in separately.
+ *
+ * Adding a key here is a contract change: say who produces it and who reads it.
+ */
+export type FieldWidgetDomProps = {
+    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>;
+};
 /**
  * Props every field widget in this package receives at RUNTIME.
  *
@@ -13,13 +55,27 @@ import { DependsOnInput, FieldMetadata } from '@object-ui/types';
  * 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`.
+ * The two are NOT interchangeable, but they no longer disagree on the
+ * validation slot: this type used to call it `errorMessage` while the spec
+ * calls it `error`, so a widget written to the published contract read
+ * `undefined` forever. objectui#3222 resolved that in the direction the
+ * contract points — the slot below IS the spec's `error`, and the form
+ * renderer now produces it (see `error`'s own doc comment). Reading
+ * `props.required` off this type is still a compile error rather than a
+ * silent `any`; that key is deliberately NOT lowered here (see below).
+ *
+ * ## Why `required` is still absent, though the spec declares it
+ *
+ * The required MARKER is drawn exactly once, by the form renderer's
+ * `<FormLabel>` (the `*` with `aria-label="required"`, which the label
+ * association folds into the control's accessible name). Handing `required`
+ * to widgets would give that marker a second possible author, and the very
+ * next AI-written widget draws its own asterisk — the same double-display
+ * failure that keeps the validation TEXT out of the widget below. The a11y
+ * state a widget genuinely could carry is `aria-required` on the input, and
+ * that needs no new key at all: `AriaAttributes` is already part of this type
+ * and every widget already forwards it to its control. Tracked separately;
+ * do not add `required` here to "align" without that decision.
  *
  * ## Why there is no `[key: string]: any` (objectui#3221)
  *
@@ -39,37 +95,66 @@ import { DependsOnInput, FieldMetadata } from '@object-ui/types';
  * is expressed as a template-literal index signature, which — unlike
  * `[key: string]` — leaves `keyof` finite, so an undeclared prop still fails.
  *
+ * ## Why there is no `schema` (objectui#3233)
+ *
+ * `schema` used to be declared here as a SECOND carrier for what `field`
+ * already means — `SchemaRenderer` handed the SDUI node down as `schema`, the
+ * form renderer forwarded `schema={props.field || props.schema || props}`
+ * *alongside* `field`, and ~30 widgets resolved their config as
+ * `field || schema`. One concept, two keys, two producers: exactly the
+ * consumer-side tolerance AGENTS.md #0.1 forbids, and exactly the shape that
+ * lets an AI-written widget pick the wrong spelling and still "work" under one
+ * host while reading `undefined` under another.
+ *
+ * v17 converged it at the PRODUCERS. `field` is the only carrier a widget ever
+ * sees; the SDUI node → `field` translation happens once, in this package's
+ * registry adapter (`withFieldCarrier`), not ~30 times in the widgets. Reading
+ * `props.schema` is now a compile error rather than a silent second contract.
+ *
  * Adding a key here is a contract change: say who produces it and who reads it.
  */
 export type FieldWidgetComponentProps<T = any> = {
     value: T;
     onChange: (val: T) => void;
     /**
-     * The field's metadata. Deliberately the looser `@object-ui/types` shape
-     * rather than the spec's, to avoid a circular dependency for now.
+     * The field's metadata, and the SINGLE carrier for it (objectui#3233).
+     *
+     * Deliberately the looser `@object-ui/types` shape rather than the spec's,
+     * to avoid a circular dependency for now.
+     *
+     * Every host produces it: the form renderer's `renderFieldComponent`, the
+     * inline-edit hosts (`FieldEditWidget`), `ActionParamDialog` /
+     * `BulkActionDialog`, and — since #3233 — the registry adapter that adapts
+     * `SchemaRenderer`'s SDUI node onto this contract (`withFieldCarrier` in
+     * `packages/fields/src/withFieldCarrier.tsx`). A widget reads `props.field`
+     * and nothing else; there is no second key to check.
      */
     field: FieldMetadata;
     readonly?: boolean;
     disabled?: boolean;
     className?: string;
-    errorMessage?: string;
+    /**
+     * The active validation message for this field, named as
+     * `@objectstack/spec/ui`'s `FieldWidgetPropsSchema` names it (objectui#3222).
+     *
+     * **Producer**: the form renderer, from react-hook-form's
+     * `fieldState.error?.message` (`packages/components/src/renderers/form/
+     * form.tsx`). Before #3222 nothing in the repo produced it under EITHER
+     * spelling, so the seven widgets computing `aria-invalid={!!errorMessage}`
+     * were computing it from a permanent `undefined` — `aria-invalid` was never
+     * once set and a screen reader was never told the field had failed.
+     *
+     * **Consumer**: a widget reads this ONLY to drive `aria-invalid` on the
+     * control it renders. The message TEXT stays with the form renderer's
+     * `<FormMessage/>`; a widget that also renders it double-displays it.
+     */
+    error?: string;
     /**
      * Upload widgets (`file`/`image`) fire this when their in-progress state
      * flips, so a host can block submit until a presigned upload settles. Other
      * widgets ignore it.
      */
     onUploadingChange?: (uploading: boolean) => void;
-    /**
-     * 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
@@ -93,9 +178,27 @@ export type FieldWidgetComponentProps<T = any> = {
      */
     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.
+     * Controlling-field name → its human LABEL, for widgets that have to NAME a
+     * sibling field in user-visible copy (the dependent-lookup gate hint).
+     *
+     * Only the form renderer knows a field's label — the widget sees its own
+     * metadata and a `depends_on` list of API names. Without this map the gate
+     * sentence interpolated the raw API name into every locale, `en` included
+     * ("Select crm_account first"), which is an internal identifier leaking into
+     * the UI, not merely an untranslated word (objectstack#5407). This is the
+     * lookup-side counterpart of `emptyHint`, which the form already resolves to
+     * labels for the fixed-option widgets. A name with no entry falls back to
+     * itself, so a host that passes nothing renders exactly what it did before.
+     */
+    dependsOnLabels?: Record<string, string>;
+    /**
+     * Hint shown when an option list cannot be filled — typically a
+     * dependency-gated list still waiting on its controlling field (#2284).
+     * Forwarded by the form renderer, which resolves the controlling fields to
+     * their human LABELS. **When supplied it wins**; the option widgets fall back
+     * to their own translated copy only when a host computed none (objectui#3231
+     * — they used to discard this prop and always render their own hardcoded
+     * English). See `OptionsEmptyState`, the single consumer.
      */
     emptyHint?: string;
     /**
@@ -114,15 +217,7 @@ export type FieldWidgetComponentProps<T = any> = {
      * user had typed. Also declarable on the field metadata.
      */
     onCreateNew?: (searchQuery: string) => void;
-    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 & {
+} & FieldWidgetDomProps & AriaAttributes & {
     /**
      * Arbitrary `data-*` attributes (test ids, analytics hooks). Open by design,
      * but a template-literal key — `keyof` stays finite, so this does NOT

package/dist/withFieldCarrier.d.ts

@@ -0,0 +1,56 @@
+import { default as React } from 'react';
+/**
+ * Adapt `SchemaRenderer`'s SDUI carrier onto the field-widget contract —
+ * objectui#3233, the producer-side half of retiring `schema` from
+ * {@link import('./widgets/types').FieldWidgetComponentProps}.
+ *
+ * ## Why this exists
+ *
+ * Two kinds of host render a registered field widget, and they name the
+ * metadata differently *for good reason*:
+ *
+ *  - the **form renderer** (`renderFieldComponent` in
+ *    `@object-ui/components`), the inline-edit hosts (`FieldEditWidget`) and
+ *    the action dialogs pass **`field`** — the field metadata they already
+ *    hold;
+ *  - **`SchemaRenderer`** (`@object-ui/react`) passes **`schema`** — the
+ *    authored node. That key is the UNIVERSAL SDUI contract *every* registered
+ *    component receives (`element:*`, `page:*`, `object-grid`,
+ *    `ReportRenderer` …). It is not being retired and must not be: it is what
+ *    the renderer means by "the node you were rendered from".
+ *
+ * What WAS wrong is that both keys reached the widget, so ~30 widgets resolved
+ * their config as `field || schema` — one concept under two spellings, a second
+ * de-facto contract on the widget side (AGENTS.md #0.1) and precisely the shape
+ * that lets an AI-written widget pick one spelling and appear to work under one
+ * host while reading `undefined` under the other.
+ *
+ * The translation belongs at the seam, exactly once: here. Downstream `field`
+ * is the only carrier, and a widget reading `props.schema` no longer compiles.
+ *
+ * ## Guarantee
+ *
+ * Payload-preserving by construction: the node is forwarded **by reference**,
+ * so a widget's `field` is the very object it used to read through `schema`.
+ * `field` wins when a host supplies both (the form path always does, and it
+ * holds the resolved metadata rather than the raw node).
+ *
+ * `schema` is *consumed* here rather than forwarded — with the key gone from
+ * the contract, passing it on would only reach the DOM as a stray attribute
+ * through a widget's `...props` spread.
+ *
+ * ## For widget authors outside this repo
+ *
+ * Registering a widget raw means `SchemaRenderer` hands it `schema` and no
+ * `field`. Wrap it once at registration and the widget only ever implements
+ * `FieldWidgetComponentProps`:
+ *
+ * ```tsx
+ * import { withFieldCarrier } from '@object-ui/fields';
+ *
+ * ComponentRegistry.register('color', withFieldCarrier(ColorPickerField), {
+ *   namespace: 'field',
+ * });
+ * ```
+ */
+export declare function withFieldCarrier<P extends object>(FieldWidget: React.ComponentType<P>): React.FC<Record<string, any>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/fields",
-  "version": "17.2.0",
+  "version": "17.3.0",
   "description": "Field renderers and registry for Object UI",
   "license": "MIT",
   "type": "module",
@@ -24,30 +24,30 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/spec": "^17.0.0-rc.1",
+    "@objectstack/spec": "^17.0.0-rc.2",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.25.0",
+    "lucide-react": "^1.28.0",
     "react-markdown": "^10.1.0",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.6.0",
-    "@object-ui/components": "17.2.0",
-    "@object-ui/core": "17.2.0",
-    "@object-ui/i18n": "17.2.0",
-    "@object-ui/providers": "17.2.0",
-    "@object-ui/react": "17.2.0",
-    "@object-ui/types": "17.2.0"
+    "@object-ui/components": "17.3.0",
+    "@object-ui/core": "17.3.0",
+    "@object-ui/i18n": "17.3.0",
+    "@object-ui/providers": "17.3.0",
+    "@object-ui/react": "17.3.0",
+    "@object-ui/types": "17.3.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "19.2.17",
-    "@types/react-dom": "19.2.3",
-    "@vitejs/plugin-react": "^6.0.4",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
     "typescript": "^6.0.3",
-    "vite": "^8.1.5",
+    "vite": "^8.2.0",
     "vite-plugin-dts": "^5.0.3"
   },
   "publishConfig": {

package/src/__tests__/cell-truncation.test.tsx

@@ -0,0 +1,96 @@
+/**
+ * Regression for objectstack-ai/objectui#3466: single-line cell renderers
+ * emitted a BARE INLINE `span.truncate`. An inline box has no width box, so
+ * `overflow:hidden` / `text-overflow:ellipsis` never engage — the value
+ * rendered at full content width and its tail was silently clipped by
+ * whatever ancestor happened to clip (the record-detail card edge), with no
+ * ellipsis and no way to read the full text (the detail row's `title` is the
+ * inline-edit hint, not the value). Same mechanism as the JSON cell fix in
+ * objectui#2578.
+ *
+ * Pin: every single-line value renderer emits a BLOCK-level, `max-w-full`
+ * truncating span that carries the full text in `title` (so hovering the
+ * value shows the full text, taking precedence over any ancestor `title`).
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import React from 'react';
+
+import {
+  TextCellRenderer,
+  LookupCellRenderer,
+  UserCellRenderer,
+  FileCellRenderer,
+  SelectCellRenderer,
+} from '../index';
+import { SchemaRendererProvider } from '@object-ui/react';
+
+const LONG =
+  'A remarkably long referenced-record title that a detail card column can never fit on a single line without an ellipsis';
+
+/** The block-level truncation contract every single-line value span must meet. */
+function expectTruncating(el: HTMLElement, fullText: string) {
+  expect(el).toHaveClass('block', 'max-w-full', 'truncate');
+  expect(el).toHaveAttribute('title', fullText);
+}
+
+describe('cell renderers truncate for real and expose the full text (issue #3466)', () => {
+  it('TextCellRenderer: block-level truncating span with title fallback', () => {
+    render(<TextCellRenderer value={LONG} field={{ type: 'text' } as any} />);
+    expectTruncating(screen.getByText(LONG), LONG);
+  });
+
+  it('LookupCellRenderer: expanded record object', () => {
+    const ds = { find: vi.fn(), findOne: vi.fn() } as any;
+    render(
+      <SchemaRendererProvider dataSource={ds}>
+        <LookupCellRenderer
+          value={{ id: 'rec1', name: LONG }}
+          field={{ type: 'lookup', reference_to: 'obj_a' } as any}
+        />
+      </SchemaRendererProvider>,
+    );
+    expectTruncating(screen.getByText(LONG), LONG);
+  });
+
+  it('LookupCellRenderer: primitive non-opaque value', () => {
+    const ds = { find: vi.fn(), findOne: vi.fn() } as any;
+    render(
+      <SchemaRendererProvider dataSource={ds}>
+        <LookupCellRenderer value={LONG} field={{ type: 'lookup' } as any} />
+      </SchemaRendererProvider>,
+    );
+    expectTruncating(screen.getByText(LONG), LONG);
+  });
+
+  it('UserCellRenderer: display name beside the avatar', () => {
+    render(<UserCellRenderer value={{ name: LONG }} field={{ type: 'user' } as any} />);
+    expectTruncating(screen.getByText(LONG), LONG);
+  });
+
+  it('FileCellRenderer: single file name', () => {
+    render(<FileCellRenderer value={{ name: LONG }} field={{ type: 'file' } as any} />);
+    expectTruncating(screen.getByText(LONG), LONG);
+  });
+
+  it('SelectCellRenderer (dot): bounded container with title, shrinkable label', () => {
+    render(
+      <SelectCellRenderer
+        value="opt1"
+        field={{
+          type: 'select',
+          appearance: 'dot',
+          options: [{ value: 'opt1', label: LONG }],
+        } as any}
+      />,
+    );
+    const label = screen.getByText(LONG);
+    // The label shrinks inside the dot row; the row itself is width-bounded
+    // and carries the full text on hover.
+    expect(label).toHaveClass('min-w-0', 'truncate');
+    const row = label.parentElement!;
+    expect(row).toHaveClass('max-w-full');
+    expect(row).toHaveAttribute('title', LONG);
+  });
+});