@object-ui/fields 17.1.0 → 17.3.0

package/dist/widgets/types.d.ts

@@ -1,17 +1,228 @@
-import { FieldMetadata } from '@object-ui/types';
-export type FieldWidgetProps<T = any> = {
+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.
+ *
+ * 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, 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)
+ *
+ * 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.
+ *
+ * ## 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, 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;
-    [key: string]: any;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+} & FieldWidgetDomProps & 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/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.1.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.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.1.0",
-    "@object-ui/core": "17.1.0",
-    "@object-ui/i18n": "17.1.0",
-    "@object-ui/providers": "17.1.0",
-    "@object-ui/react": "17.1.0",
-    "@object-ui/types": "17.1.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": {
-    "@objectstack/spec": "^17.0.0-rc.0",
-    "@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/FieldEditWidget.tsx

@@ -7,7 +7,7 @@
  */
 
 import React from 'react';
-import type { FieldWidgetProps } from './widgets/types';
+import type { FieldWidgetComponentProps } from './widgets/types';
 
 // The SAME dedicated widgets the form renders — reused for in-place editing
 // (e.g. the data grid's inline cell editor) so a select edits as a dropdown, a
@@ -54,7 +54,7 @@ import { mapFieldTypeToFormType } from './field-type-alias';
  * Rich/heavy types (file, image, lookup, richtext, …) are intentionally absent
  * so callers fall back to their own simpler editor.
  */
-const EDIT_WIDGETS: Record<string, React.ComponentType<FieldWidgetProps<any>>> = {
+const EDIT_WIDGETS: Record<string, React.ComponentType<FieldWidgetComponentProps<any>>> = {
   text: TextField,
   textarea: TextAreaField,
   number: NumberField,
@@ -180,10 +180,12 @@ export function FieldEditWidget({
   value,
   onChange,
   readonly,
-}: FieldWidgetProps<any>): React.ReactElement | null {
+}: FieldWidgetComponentProps<any>): React.ReactElement | null {
   const resolved = field?.type ? resolveInlineEditType(field.type) : undefined;
   const Widget = resolved ? EDIT_WIDGETS[resolved] : undefined;
   if (!Widget) return null;
+  // `compact` is a declared widget prop (objectui#3221 closed this type), so
+  // the spread no longer needs an `any` escape hatch to get past it.
   const compactProps = resolved && COMPACT_EDIT_TYPES.has(resolved) ? { compact: true } : {};
-  return <Widget field={field} value={value} onChange={onChange} readonly={readonly} {...(compactProps as any)} />;
+  return <Widget field={field} value={value} onChange={onChange} readonly={readonly} {...compactProps} />;
 }

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);
+  });
+});

package/src/__tests__/field-carrier-sdui.test.tsx

@@ -0,0 +1,169 @@
+/**
+ * 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 SDUI path delivers field metadata on ONE key — objectui#3233.
+ *
+ * `SchemaRenderer` hands every registered component the authored node as
+ * `schema`. That key is the universal SDUI contract (`element:*`, `page:*`,
+ * `object-grid`, `ReportRenderer` …) and is NOT retired. What was retired is
+ * `schema` on the *field-widget* contract: a widget used to receive the node
+ * under `schema` here and the metadata under `field` from the form renderer,
+ * which is why ~30 widgets resolved their config as `field || schema`.
+ *
+ * The translation now happens once, at the registration seam
+ * (`withFieldCarrier`), so downstream `field` is the only carrier. That is only
+ * correct if the node reaches the widget UNCHANGED — "swap the key, don't drop
+ * the cargo". The first test proves it by OBJECT IDENTITY: a spy sits where the
+ * registry entry sits, records the object `SchemaRenderer` passed as `schema`,
+ * and the widget's `field` must be that exact object. (Identity against the
+ * authored literal would be wrong to assert — `SchemaRenderer` shallow-copies
+ * the node while evaluating expressions, so the object it delivers is its own.)
+ *
+ * The last test pins that the REAL registration path goes through the adapter
+ * at all: an adapter nobody applied would leave every SDUI-hosted widget
+ * reading `undefined`, which is exactly the silent failure this convergence is
+ * accused of risking.
+ *
+ * The sibling half of the invariant — the form path through
+ * `renderFieldComponent` — is pinned in `packages/components/src/renderers/
+ * form/__tests__/form-field-carrier.test.tsx`.
+ */
+
+import React, { Suspense } from 'react';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+import { ComponentRegistry } from '@object-ui/core';
+import { SchemaRenderer } from '@object-ui/react';
+
+import { withFieldCarrier } from '../withFieldCarrier';
+import { registerField } from '../index';
+// Module scope, not a hook: `registerField('boolean')` registers
+// `React.lazy(() => import('./widgets/BooleanField'))`, and under a saturated
+// transform pipeline a first `import()` can outlive RTL's 1000ms budget. The
+// specifier matches `fieldWidgetMap`'s exactly, so ESM's cache makes that
+// factory resolve immediately (AGENTS.md 测试纪律 / objectui#3010).
+import '../widgets/BooleanField';
+
+/**
+ * Capture holder, not bare module variables: `react-hooks/globals` forbids
+ * REASSIGNING an outer binding from a component body, which is what a probe
+ * has to do. Mutating a property of a stable object is the repo's usual shape
+ * for this (see plugin-detail's `RelatedList` probes).
+ */
+const captured: { props: Record<string, any> | null; node: unknown } = {
+  props: null,
+  node: null,
+};
+
+function CarrierProbe(props: any) {
+  captured.props = props;
+  return <div data-testid="carrier-probe">{props.field?.label ?? 'NO FIELD'}</div>;
+}
+
+const AdaptedProbe = withFieldCarrier(CarrierProbe);
+
+/**
+ * Sits exactly where the registry entry sits, so it sees the host's props
+ * verbatim, then forwards them to the adapter under test. This is what makes
+ * the identity assertion possible: `captured.node` and the widget's `field`
+ * are observed within a single render pass.
+ */
+function CarrierSpy(props: any) {
+  captured.node = props.schema;
+  return <AdaptedProbe {...props} />;
+}
+
+beforeEach(() => {
+  captured.props = null;
+  captured.node = null;
+  ComponentRegistry.register('carrierprobe', CarrierSpy, {
+    namespace: 'field',
+    skipFallback: true,
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('SDUI path — the authored node arrives as `field` (objectui#3233)', () => {
+  it('hands the widget the very object it used to read through `schema`', () => {
+    const node = {
+      type: 'field:carrierprobe',
+      name: 'city',
+      label: 'City',
+      placeholder: 'Where?',
+      options: [{ label: 'Beijing', value: 'bj' }],
+    };
+
+    render(<SchemaRenderer schema={node as any} />);
+
+    expect(screen.getByTestId('carrier-probe')).toHaveTextContent('City');
+    expect(captured.props).not.toBeNull();
+    expect(captured.node).toBeTruthy();
+    // The payload-equivalence proof: same object, by reference. A
+    // reconstruction would still render "City" while quietly dropping whatever
+    // the copy did not know to carry.
+    expect(captured.props!.field).toBe(captured.node);
+    // …and it really is the whole authored node, not a narrowed projection.
+    expect(captured.props!.field.name).toBe('city');
+    expect(captured.props!.field.placeholder).toBe('Where?');
+    expect(captured.props!.field.options).toEqual([{ label: 'Beijing', value: 'bj' }]);
+  });
+
+  it('consumes `schema` rather than forwarding it to the widget', () => {
+    // Key ABSENCE, not `undefined`. Two reasons it must not be forwarded: a
+    // widget could resolve `field || schema` again (the second contract
+    // survives in practice while the type claims it is gone), and widgets
+    // spread their leftover props onto DOM nodes, where an object-valued
+    // `schema` attribute is a React warning.
+    render(
+      <SchemaRenderer schema={{ type: 'field:carrierprobe', name: 'city', label: 'City' } as any} />,
+    );
+
+    expect(captured.props).not.toBeNull();
+    expect('schema' in captured.props!).toBe(false);
+  });
+
+  it('lets an explicit `field` win when a host supplies both', () => {
+    // The form renderer passes `field` (resolved metadata) and never `schema`.
+    // If some host ever passed both, the resolved metadata is the better
+    // answer — the raw node is the fallback, not the override.
+    const node = { type: 'field:carrierprobe', name: 'from-node', label: 'From node' };
+    const metadata = { name: 'from-field', label: 'From field' };
+
+    render(<AdaptedProbe schema={node} field={metadata} />);
+
+    expect(captured.props!.field).toBe(metadata);
+  });
+
+  it('applies the adapter on the REAL registration path (`registerField`)', async () => {
+    // The seam is only worth anything if `registerField` goes through it.
+    // `BooleanField` reads `widget` / `name` off its metadata carrier and
+    // nowhere else: `widget: 'checkbox'` selects the Checkbox over the Switch,
+    // and `name` becomes the control's id. Both are node keys, so seeing them
+    // honoured here proves the node reached `field` end to end — through the
+    // real registry entry, the real SchemaRenderer, and the real widget.
+    registerField('boolean');
+
+    render(
+      <Suspense fallback={<div>loading</div>}>
+        <SchemaRenderer
+          schema={
+            { type: 'field:boolean', name: 'is_active', label: 'Active', widget: 'checkbox' } as any
+          }
+        />
+      </Suspense>,
+    );
+
+    const control = await screen.findByRole('checkbox');
+    expect(control).toHaveAttribute('id', 'is_active');
+  });
+});