@object-ui/plugin-form 17.6.0 → 17.7.0

package/README.md

@@ -38,7 +38,7 @@ const schema = {
 ### What the side-effect import registers
 
 There is no component map to iterate: registration is a side effect of importing
-the package entry, which makes six `ComponentRegistry.register(...)` calls. These
+the package entry, which makes five `ComponentRegistry.register(...)` calls. These
 are the schema types those calls claim, read off the calls themselves in
 `src/index.tsx`:
 
@@ -47,7 +47,6 @@ are the schema types those calls claim, read off the calls themselves in
 | `plugin-form:object-form` | `object-form` | `ObjectForm` — metadata-driven form over one record |
 | `view:form` | none | the same renderer under the view protocol |
 | `plugin-form:embeddable-form` | `embeddable-form` | `EmbeddableForm` — standalone public form |
-| `plugin-form:form-analytics` | `form-analytics` | `FormAnalytics` — submission dashboard |
 | `plugin-form:object-master-detail-form` | `object-master-detail-form` | `MasterDetailForm` — parent + child line items in one submit |
 | `record:line_items` | none | `LineItemsPanel` — child grid bound to the record on the page |
 
@@ -57,10 +56,18 @@ for backwards compatibility, unless the call passes `skipFallback: true`
 stays the basic `@object-ui/components` form, and bare `line_items` is left to
 whoever else claims it.
 
+The `form-analytics` node key is RETIRED (objectui#10859 batch 8): no schema
+produced it, and `objectui validate` refused it at `type`. `FormAnalytics` is still
+exported (see below); mount the component directly.
+
 ### Public exports
 
-The package entry exports these — components, their prop/schema types, and the
-layout helpers. There is no aggregate map among them:
+The package entry exports these — components, their prop/schema types, the
+layout helpers, the two create-payload rules a second form renderer needs
+(see [`required` + a runtime default](#required-or-requiredwhen--a-runtime-default))
+and the section-group resolver a third one needs
+(see [Resolving `sections[].group` outside this package](#resolving-sectionsgroup-outside-this-package)).
+There is no aggregate map among them:
 
 ```typescript
 import {
@@ -90,6 +97,9 @@ import {
   deriveFormFields,
   findRelationshipField,
   resolveInlineMode,
+  omitServerResolvedDefaults,
+  isRequiredInForm,
+  resolveSectionGroupReferences,
 } from '@object-ui/plugin-form';
 
 import type {
@@ -118,6 +128,9 @@ import type {
   LineItemsPanelSchema,
   DerivedDetail,
   InlineMode,
+  ChildObjectSchemaLike,
+  FieldDefaultsSchemaLike,
+  ResolveSectionGroupsOptions,
 } from '@object-ui/plugin-form';
 ```
 
@@ -137,9 +150,10 @@ The renderers this package registers for itself are internal wrappers rather
 than these exported components. `SchemaRenderer` hands a registered component its
 `schema` (plus the schema's own props), but never a `dataSource` — that travels
 on `SchemaRendererContext` — so each wrapper reads it off the context first.
-`ObjectForm` takes `dataSource` as a prop, optional because inline `customFields`
-need no adapter, so a custom-key registration either supplies one or wraps the
-component the same way.
+`ObjectForm` takes `dataSource` as a prop, optional because inline fields need no
+adapter, so a custom-key registration either supplies one or wraps the component
+the same way. "Optional" is not "absent is fine for every form", though — see
+[What a form submits to](#what-a-form-submits-to).
 
 ## Schema API
 
@@ -172,7 +186,7 @@ unknown-component placeholder.
 | `columns` | `number` | grid width (1–4) |
 | `validationMode` | `'onSubmit' \| 'onBlur' \| 'onChange' \| 'onTouched' \| 'all'` | when the rules run |
 | `resetOnSubmit` / `disabled` | `boolean` | |
-| `mode` | `'edit' \| 'read' \| 'disabled'` | whole-form mode |
+| `mode` | — | **retired** (objectui#10286): nothing read it, and validation now refuses it. Use `disabled` for a read-only basic form, or `object-form` for create / edit / view |
 | `objectName` | `string` | enables metadata field locators `data-testid="field:{objectName}.{field}"` (ADR-0054 C4) |
 | `previousValues` | `Record<string, any>` | edit-mode hosts only — the persisted record, as evaluation context for `previous` / `readonlyWhen`. Never sent anywhere |
 | `fieldContainerClass` | `string` | class for the field grid inside the `<form>` |
@@ -210,13 +224,13 @@ only **required** one:
 | `hidden` | `boolean` | field is not rendered at all |
 | `options` | `SelectOption[] \| RadioOption[]` | for `select` / radio fields |
 | `validation` | `FieldValidationRules` | **an object keyed by rule name** — see below |
-| `condition` | `FieldCondition` | legacy `{ field, equals, notEquals, in, custom }` matcher |
+| `condition` | `FieldCondition` | legacy `{ field, equals, notEquals, in }` matcher (`custom` is retired, objectui#7759: nothing ran it) |
 | `visibleWhen` / `readonlyWhen` / `requiredWhen` | `string \| { dialect?, source }` | CEL predicates over the live record, evaluated by `@objectstack/formula` — the same engine and dialect the server uses. Fail open |
 | `visibleOn` | `string \| { dialect?, source }` | view-level visibility predicate (spec `FormField.visibleOn`) |
 | `dependsOn` | `DependsOnInput` | cascading parent(s): a bare name, a list of names, or `{ field, param }` entries |
 | `span` | `'auto' \| 'full'` | relative width, independent of the column count (preferred) |
 | `colSpan` | `number` | legacy column span (1–4), clamped to the current column count |
-| `field` | `Record<string, any>` | the resolved object-field **metadata object**, stashed by the object-bound paths so widgets can read `precision`, `currency`, `reference_to`, … In the *spec* form-view vocabulary `field` is a string (the referenced field name); that shape ends at `normalizeSectionField` and never reaches a runtime `FormField` |
+| `field` | `Record<string, any>` | the resolved object-field **metadata object**, stashed by the object-bound paths so widgets can read `precision`, `currency`, `reference`, … In the *spec* form-view vocabulary `field` is a string (the referenced field name); that shape ends at `normalizeSectionField` and never reaches a runtime `FormField` |
 
 `FormField` also declares `[key: string]: any`, so an invented key type-checks
 here too. Two that a reader might expect, and that are **not** declared:
@@ -224,7 +238,7 @@ here too. Two that a reader might expect, and that are **not** declared:
 | Not a `FormField` key | Write this instead |
 |---|---|
 | `defaultValue` | `FormSchema.defaultValues` at form level. An object-bound form seeds from the object field's own declared `defaultValue` — see [What a create form opens with](#what-a-create-form-opens-with) |
-| `className` | `span` / `colSpan` for width, `FormSchema.fieldContainerClass` for the grid. (An undeclared key still rides the props spread down to whichever component the field resolves to, so a field-level `className` can visibly land on a built-in control — but nothing in the contract promises that, and a registered widget honours it only if it happens to spread its leftover props. The renderer reads it *explicitly* on exactly one pseudo-field, `type: 'section-divider'`, where it styles the inline section header.) |
+| `className` | `span` / `colSpan` for width, `FormSchema.fieldContainerClass` for the grid. (An undeclared key still rides the props spread down to whichever component the field resolves to, so a field-level `className` can visibly land on a built-in control — but nothing in the contract promises that, and a registered widget honours it only if it happens to spread its leftover props. The renderer reads it *explicitly* nowhere: it used to stamp the `type: 'section-divider'` pseudo-field from an authored section's `className`, and that read was **retired** in objectstack#13626 — see [Section styling is not authorable](#section-styling-is-not-authorable).) |
 
 There is no `ValidationRule` type in this repo, under any spelling.
 
@@ -289,6 +303,8 @@ field.
 A field may declare both, and it is coherent authoring — storage-level required,
 with the value guaranteed by the producer:
 
+<!-- doc-snippet: fragment — one object-literal PROPERTY quoted out of a field map — `remind_at: Field.datetime(...)` is a key/value pair, not a statement. Measured TS1109x1. -->
+
 ```ts
 remind_at: Field.datetime({ required: true, defaultValue: 'NOW()' }),
 ```
@@ -305,6 +321,8 @@ predicate says "required in this state", but `NOW()` / `current_user` resolve
 at insert regardless of state, so the producer's guarantee covers the
 conditional claim exactly as it covers the unconditional one:
 
+<!-- doc-snippet: fragment — one object-literal PROPERTY quoted out of a field map — `remind_at: Field.datetime(...)` is a key/value pair, not a statement. Measured TS1109x1. -->
+
 ```ts
 remind_at: Field.datetime({ requiredWhen: 'record.status == "scheduled"', defaultValue: 'NOW()' }),
 ```
@@ -322,6 +340,34 @@ since one verdict drives all three — in that mode the user genuinely is not
 required to provide the value. Showing what the server *will* supply, as a
 non-authoritative preview, is a separate follow-up.
 
+The two halves of that verdict are importable, so a host with its own form
+renderer applies the same rule rather than re-deriving it (objectui#6059):
+
+```typescript
+declare const field: { required?: unknown; defaultValue?: unknown };
+declare const isCreateForm: boolean;
+declare const values: Record<string, unknown>;
+declare const objectSchema: FieldDefaultsSchemaLike;
+
+import {
+  isRequiredInForm,
+  omitServerResolvedDefaults,
+  type FieldDefaultsSchemaLike,
+} from '@object-ui/plugin-form';
+
+// Should this create form enforce `required` on the field?
+const required = isRequiredInForm(field, isCreateForm);
+
+// Drop the keys the producer must resolve, immediately before the insert.
+const payload = isCreateForm ? omitServerResolvedDefaults(values, objectSchema) : values;
+```
+
+They are published as a pair on purpose: excusing a server-owned field from
+`required` and then submitting the key anyway is not half a fix, it is no fix.
+Both are pure functions over plain data — no React, no registry — and
+`omitServerResolvedDefaults` is **create-only**, so the caller keeps the mode
+gate, as the example shows.
+
 Every consumer reads one predicate, `isRuntimeDefault` in `@object-ui/core`
 (re-exported for this package's own use by `src/schemaDefaults.ts`, not from the
 package entry listed above) — which is what keeps a form from seeding a field it
@@ -332,6 +378,60 @@ evaluator that resolves it — `resolveFieldRuleState`, reading
 `isServerOwnedValue`. Display and validation share that single verdict, so a
 field can never lose its asterisk while still refusing the submit.
 
+### Resolving `sections[].group` outside this package
+
+A form section declares its members exactly one way: it enumerates `fields`, or
+it points `group` at one of the object's declared `fieldGroups` and inherits that
+group's members **and** its presentation (objectstack#13855, ADR-0085 §5 — the
+spec range that carries it is the `@objectstack/spec` entry in this package's own
+`package.json`). `ObjectForm` resolves the reference once, above its routing
+fork, so all six layouts inherit it. `ModalForm` resolves its own `sections`
+through the same call as well, because hosts mount it directly rather than
+through `ObjectForm` — the console's record create / edit dialog and
+action-opened modals do (objectui#11542). `DrawerForm` mounted directly does
+not resolve them; reach it through `ObjectForm` with `formType: 'drawer'`.
+
+A host with its **own** section builder resolves it with the same function
+instead of deriving sections itself (objectui#8641):
+
+```typescript
+import {
+  resolveSectionGroupReferences,
+  type ResolveSectionGroupsOptions,
+} from '@object-ui/plugin-form';
+import type { ObjectFormSection } from '@object-ui/types';
+
+// What the host's own builder produced. A `{ group: 'x' }` section is still
+// unresolved here — `ObjectFormSection` declares `group` and leaves `fields`
+// optional, which is the whole shape this call takes in.
+declare const authoredSections: ObjectFormSection[];
+declare const objectDef: unknown;   // `{ fields, fieldGroups }`, or null while loading
+
+const sections = resolveSectionGroupReferences(authoredSections, {
+  objectName: 'ticket',
+  formType: 'simple',
+  objectDef,
+});
+```
+
+Every `{ group: 'x' }` section comes back as the section that group declares —
+label, members, description and collapse state — and everything else comes back
+**untouched**: with no reference in the list the input array is returned by
+identity, so the call cannot perturb an existing form and is safe inside a
+`useMemo`. A reference that resolves to nothing yields an empty section (never a
+dropped one — a `sections` array that empties out stops being a sectioned form at
+all) and is reported once, naming the object and the key.
+
+⛔ Nothing about the assembly belongs to the caller. Declared order, the
+empty-group drop, the ungrouped trailing bucket and the collapse / `visibleWhen`
+passthrough all come from `deriveFieldGroupLayout` through this package's single
+adapter onto the section shape — the same code path the no-sections field-group
+fallback uses, so a group authored by reference and one derived by the fallback
+are the same section by construction. A host reaching for `deriveFieldGroupLayout`
+directly would have to re-spell the `collapse` enum onto its own boolean pair and
+pass `visibleWhen` through by hand, which is the duplication this export exists to
+prevent.
+
 ### Column width of a sectioned form
 
 A sectioned form renders as ONE grid, and two keys decide its shape:
@@ -352,6 +452,42 @@ The grid is applied to the field container **inside** the form, never wrapped
 around the `<form>` (which would put the whole form in cell 1 and leave the other
 columns empty — #2128).
 
+### Section styling is not authorable
+
+`className` and `gridClassName` on a form-view **section** do nothing. In JSON
+metadata, authoring them is not a parse error — the renderer simply does not
+read them. In TypeScript they are a compile error: `ObjectFormSection` in
+`@object-ui/types` does not declare either key (objectui#7200), matching the
+spec's strict `FormSectionSchema`.
+
+This is deliberate. Both keys sit on the SDUI-only side of the authorable
+boundary: `@objectstack/spec` does not declare either on the form-view/section
+surface, and the authorable-surface ledger carries no entry for them. The
+renderer nevertheless reached them through `as any` at seven sites until
+objectstack#13626 (maintainer ruling 2026-09-01) retired those reads — the
+boundary had been declared on one side and crossed on the other.
+
+Declaring the keys instead was weighed and rejected: it would invite free
+Tailwind strings into authored metadata, which is the class the boundary exists
+to keep out, and per ADR-0065 / ADR-0080 utility classNames in runtime metadata
+are never scanned by the build-time Tailwind — so they silently produce no CSS
+even when they are read. If per-view styling becomes a real product need it will
+get an explicit controlled token surface rather than two leaked keys.
+
+**What still works:** the form ROOT `className` (`FormSchema.className`) is a
+different key on a different node and is unaffected; section *layout* stays
+authorable through `columns` (above); and a host application styles sections
+through its own CSS.
+
+> Note for contributors: `ObjectFormSection` in `@object-ui/types` no longer
+> declares either key (objectui#7200), so an uncast `className: s.className` fails
+> to compile — but a cast read (the shape the seven retired sites had) still
+> would, and JSON metadata carries whatever an author wrote. The non-consumption
+> is therefore pinned behaviourally, in
+> `src/__tests__/sectionStyleKeysRetired-13626.test.tsx`, across all seven arms;
+> the declaration side is pinned in `@object-ui/types`'
+> `object-form-section-style-keys-undeclared.test.ts`.
+
 ### Tabbed field layout (`fieldTabs`)
 
 A sectioned form is **one** form. Instead of rendering a form per section — which
@@ -359,6 +495,8 @@ strands every section but the first outside the submit, and (in tabs) lets the
 inactive panel unmount with its values — declare tabs on the single form and let
 the renderer distribute the fields:
 
+<!-- doc-snippet: fragment — a `fieldTabs` key list in prose notation, not a statement: the trailing `defaultFieldTab?:` / `fieldTabsPosition?:` entries mark OPTIONAL keys, which no object literal can spell. Measured TS1005x2 TS1109x3. -->
+
 ```typescript
 {
   type: 'form',
@@ -366,6 +504,7 @@ the renderer distribute the fields:
   fieldTabs: [
     { key: 'basics', label: 'Basics', fields: ['subject', 'status'] },
     { key: 'detail', label: 'Detail', description: 'Anything else', fields: ['description'] },
+    { key: 'billing', label: 'Billing', fields: ['vat_id'], visibleWhen: 'record.status == "won"' },
   ],
   defaultFieldTab?: 'basics',                    // defaults to the first tab
   fieldTabsPosition?: 'top',                     // 'top' | 'bottom' | 'left' | 'right'
@@ -381,7 +520,89 @@ the renderer distribute the fields:
 - Fields no tab claims render above the tab strip rather than disappearing.
 - Needs at least two tabs, and is ignored when the form uses `children`.
 
-`ModalForm` (`contentLayout: 'tabbed'`) and `TabbedForm` are built on this.
+`ModalForm` (`contentLayout: 'tabbed'`) and `TabbedForm` are built on this, and
+both forward a section's `visibleWhen` onto the tab they synthesise — see the
+support table below.
+
+#### Conditional tabs (`FormFieldTab.visibleWhen`)
+
+A tab may carry a `visibleWhen` predicate — the same slot, vocabulary and
+engine as the field-level rule (`string | { dialect?, source }`, a CEL
+predicate over the live record, evaluated by `@objectstack/formula` with the
+host predicate scope bound, so it can read `current_user` / `data` /
+`features` exactly as a field rule can — there is no `app` root, objectui#8155).
+Like every conditional rule in this
+system it **fails open**: a predicate that cannot be evaluated leaves the tab
+visible rather than hiding data behind a broken expression.
+
+When the predicate resolves FALSE the renderer draws **neither the tab's
+trigger nor its panel** — a hidden tab disappears from the tab strip entirely,
+it is not merely an empty panel.
+
+**Submit semantics are deliberately counter-intuitive — visibility gates
+drawing, and nothing else:**
+
+- **A hidden tab's values still submit.** Hiding a tab does not remove its
+  fields' values from the record: whatever they hold (loaded from the record,
+  seeded by defaults, or typed before the tab hid) is carried in the payload.
+  A visibility rule is not a data filter — dropping the values would turn a
+  cosmetic predicate into a silent data-loss door.
+- **A hidden tab's fields skip client-side validation.** A user is never
+  blocked by an error pointing at a control they cannot see. The flip side:
+  a *required* field on a hidden tab sails past the client — **the
+  server-side contract is the loud floor** for genuinely-required data, and a
+  submit missing it fails there, visibly.
+- **Stale errors clear.** A tab hiding mid-session (its predicate flipping on
+  a keystroke or a scope change) clears its fields' leftover validation
+  errors, the same hygiene a field's own `visibleWhen` applies.
+
+These are not tab-specific rules: they are the ruled hidden-group semantics
+every section `visibleWhen` follows, inherited through the same mechanism a
+field's own FALSE predicate uses (the fields simply stop being drawn; the form
+keeps their values and skips unmounted controls at validation).
+
+Two mechanics worth knowing:
+
+- **Selection is derived over the visible tabs.** If the predicate hides the
+  ACTIVE tab, the renderer re-selects deterministically — the user's own pick
+  if still visible, else `defaultFieldTab`, else the first visible tab — so
+  the form never shows an empty panel. The pick itself is kept: the tab the
+  user chose becomes active again the moment its predicate re-admits it.
+- **Whether the tabbed layout engages at all is judged on the DECLARED tabs**
+  (the "needs at least two tabs" rule above counts declarations, not
+  verdicts). A predicate hiding all but one tab filters what is drawn; it
+  never collapses the strip into the flat layout mid-interaction.
+
+**Where `visibleWhen` on a tab works today** — this key landed renderer-first,
+and only where the renderer actually evaluates it:
+
+| Authoring surface | Carries the predicate? |
+| --- | --- |
+| `type: 'form'` with `fieldTabs[].visibleWhen` (as above) | **Yes** — evaluated by the form renderer |
+| `ModalForm` / `formType: 'modal'` with `contentLayout: 'tabbed'` | **Yes** — the section's `visibleWhen` is copied onto its tab |
+| `TabbedForm` / `formType: 'tabbed'` sections | **Yes** — the section's `visibleWhen` is copied onto the tab `TabbedForm` synthesises; a single-section form, which draws no tab strip, gates the group through the flat layout's own section-divider mechanism instead |
+| `WizardForm` / `formType: 'wizard'` steps | **No** — steps are not tabs; nothing evaluates a step-level predicate |
+
+The remaining **No** row is deliberate, not an oversight: declaring the key on a
+surface whose renderer ignores it would make the metadata lie (#6111), so the
+key stops at the boundary until each surface enforces it.
+
+⛔ **A wizard step has no predicate slot at all, and that is enforced by the
+type.** A step predicate is not the tab predicate under another name — steps are
+mounted one at a time and keyed by index, so a step predicate would be
+step-boundary reactive where a tab's is live-record reactive, and it would need
+navigation, indicator, `isLastStep`, final-gate and re-selection semantics that
+none of the tab machinery supplies. So `WizardStepConfig` is declared
+independently of `FormSectionConfig` (maintainer ruling 2026-08-30, #6237) and
+simply does not carry the key: `visibleWhen` on a wizard step literal is a
+**compile error**, not a silently ignored key. Track #6237 for the step
+contract.
+
+That row also **reports itself** rather than failing silently. Authoring a
+section `visibleWhen` on `formType: 'wizard'` logs a console warning naming the
+layout and the sections whose predicate is being dropped — untyped JSON reaches
+the renderer too, so the compile-time half cannot be the only one. Nothing warns
+on the five arms that honour the key.
 
 ### Wizard steps and `allowSkip`
 
@@ -409,6 +630,8 @@ The same rule for side-by-side panels: the `<form>` wraps the whole panel group
 and each pane holds only fields, so one react-hook-form instance spans the
 divider.
 
+<!-- doc-snippet: fragment — a `fieldPanes` key list in prose notation, not a statement: the trailing `fieldPanesOrientation?:` / `fieldPanesResizable?:` entries mark OPTIONAL keys, which no object literal can spell. Measured TS1005x2 TS1109x3. -->
+
 ```typescript
 {
   type: 'form',
@@ -503,27 +726,31 @@ steps are its `sections` — one step per section. There is no
 unknown-component placeholder and the fields inside `steps` are never read.
 
 ```typescript
-import type { ObjectFormSchema } from '@object-ui/types';
+import type { ObjectFormBlockNode } from '@object-ui/types';
 
-const schema: ObjectFormSchema = {
+// The props go in the node's `properties` bag — the members of
+// `@objectstack/spec`'s `ComponentPropsMap['object-form']` row.
+const schema: ObjectFormBlockNode = {
   type: 'object-form',
-  objectName: 'contacts',        // required
-  mode: 'create',                // required
-  formType: 'wizard',            // routes to WizardForm — needs at least one section
-  sections: [
-    {
-      name: 'personal',
-      label: 'Personal Info',
-      fields: ['first_name', 'last_name']    // field NAMES, resolved from the object schema
-    },
-    {
-      name: 'contact',
-      label: 'Contact Info',
-      fields: ['email', 'phone']
-    }
-  ],
-  allowSkip: false,              // see "Wizard steps and allowSkip" above
-  showStepIndicator: true
+  properties: {
+    objectName: 'contacts',        // the object whose fields the steps list
+    mode: 'create',
+    formType: 'wizard',            // routes to WizardForm — needs at least one section
+    sections: [
+      {
+        name: 'personal',
+        label: 'Personal Info',
+        fields: ['first_name', 'last_name']    // field NAMES, resolved from the object schema
+      },
+      {
+        name: 'contact',
+        label: 'Contact Info',
+        fields: ['email', 'phone']
+      }
+    ],
+    allowSkip: false,              // see "Wizard steps and allowSkip" above
+    showStepIndicator: true
+  }
 };
 ```
 
@@ -532,7 +759,10 @@ A section's `fields` accepts three shapes — a field **name**, a spec
 `FormField` object. The inline shape is what lets a wizard run with no data
 source at all, which is the closest equivalent of the old snippet; note that
 `WizardForm` reports a data-source-less submit through `onSuccess` (there is no
-`onSubmit` on this schema):
+`onSubmit` on this schema). **Every** step's fields have to be the inline shape
+for that to hold — one bare name among them means the form needed object
+metadata it could not fetch, and the submit is refused rather than confirmed
+(again, [What a form submits to](#what-a-form-submits-to)):
 
 ```tsx
 import { WizardForm } from '@object-ui/plugin-form';
@@ -626,6 +856,101 @@ Each rule appears **once**, under its own name — an object, not a list. A seco
 `minLength` cannot exist, which is the point: the shape the renderer hands
 react-hook-form is one rule per kind.
 
+## What a form submits to
+
+A form has somewhere to put the values when it has **either** a `dataSource` (it
+writes through the adapter) **or** a declared `submitHandler` (the host owns the
+write and needs no adapter of its own). With neither, exactly one shape is still
+legitimate: **fields authored inline**, where the author's `onSuccess` *is* the
+write. That is
+
+- a non-empty `customFields`, or
+- `sections` whose fields are **all** inline runtime `FormField` objects.
+
+Anything else — a form naming fields the object schema would have to resolve,
+with no adapter to fetch it and no host seam to hand the values to — **refuses**
+the submit with `DataSource is required for form submission (inline mode not
+configured)`. The error reaches `schema.onError` and is rethrown.
+
+This is uniform across all six renderers (`simple`, `tabbed`, `wizard`, `split`,
+`drawer`, `modal`). It used to be uniform in the other direction: the five
+variant renderers answered an adapter-less submit by calling `onSuccess` and
+returning, which reported a save that never happened and, through
+`MasterDetailForm`, produced a success toast over a form it then cleared
+(objectui#6300). A declared `submitHandler` is consulted first, so a host that
+said it owns the write is never bypassed for want of an adapter it never needed.
+
+## What an edit save writes
+
+An `object-form` in `mode: 'edit'` with a `recordId` reads the record with
+`dataSource.findOne`, and its save writes **only the fields that differ from
+that read** (objectui#10156). Every layout does this: the simple form and the
+`tabbed`, `wizard`, `split`, `modal` and `drawer` variants (objectui#10563). So
+does a simple form whose mobile `stepper` option shows it one step at a time
+through the wizard, and the parent operation of a master-detail form, whose
+header is a simple or a `tabbed` form. A master-detail child row already worked
+this way (objectui#10108), and all of them use the same comparison.
+
+Before that comparison, every layout strips what a form never writes: the
+server-owned columns (record identity, audit provenance, ownership and tenancy
+— the roster in `sanitize.ts`, plus any field the object marks `system`),
+computed, formula and read-only columns, keys the object does not declare, and
+every field the caller's field-level security refuses. A create is stripped the
+same way. Every layout also renders a field the caller may read but not edit as
+a disabled input, so nothing is typed into a field the save would leave out.
+Every layout likewise disables every field of a managed object (ADR-0092 D4)
+whose `userActions` do not open the form's mode, `create` on a create form and
+`edit` on an edit form, and of any object whose `create` or `update` the
+server's effective API operations deny (objectui#10612). While that lock holds,
+every layout shows one notice above the fields that names the object, by its
+translated label, and the missing permission (`form.noPermissionToCreate` or
+`form.noPermissionToEdit`, objectui#11000); a field locked on its own shows none.
+The submit button of the simple, `tabbed`, `split`, `modal` and `drawer` layouts
+stays on screen and the lock does not disable it; the server's write guard is
+what refuses the save.
+A `wizard` disables Next and its final submit button, and its step indicator does
+not jump forward, while Cancel and Back stay usable.
+
+The comparison sends every field it cannot prove unchanged, because a field
+wrongly judged unchanged would lose the user's edit while the server still
+answers 200:
+
+- `null` and `undefined` count as the same value. `''` is not a blank here, so
+  `null` and `''` are different.
+- A number and a numeric string are different (`5` and `'5'`).
+- A lookup id and the expanded lookup object are different.
+- A `Date` and a date string are different. So are two date strings written in
+  different formats.
+- Objects and arrays are equal only when they serialize identically.
+  Reordering their keys or elements makes them different.
+
+A field the form changed by itself after the read is a change, so it is sent.
+That covers a cascade clear or a value cleared when its field was hidden.
+
+Some saves still send the full payload:
+
+- **A save with nothing changed.** It sends every field, as it always has.
+  That keeps it a real request, with the same concurrency guard and a real
+  server record for `onSuccess`.
+- **A form with no record read of its own.** This includes a create, a record
+  given as `initialData` or through inline `customFields`, and a save made
+  while a new record is still loading. Each of these sends every field.
+
+After a successful save, the form treats the fields it just wrote as saved. A
+form that stays open therefore compares its next save with the record as it
+stands now, not as it was first read.
+
+The concurrency guard is unchanged by this rule. The update carries
+`ifMatch` = the `updated_at` the form read. Once a form that stays open has
+saved the record, its next save carries the `updated_at` that save returned
+instead, so the form is not refused over its own earlier save. A `409` still
+offers **Keep editing** or **Overwrite**. **Overwrite** now resends only the
+changed fields, so it no longer rewrites fields this user never touched.
+
+⚠️ A host `submitHandler` gets the same payload in edit mode. Normally that is
+the changed fields; after a save with nothing changed, it is the full payload.
+A host that needs the whole record must read it itself.
+
 ## Integration with Data Sources
 
 **The adapter is not a schema key.** A schema is a serialisable document; a live
@@ -637,9 +962,13 @@ registrations.
 
 ### The metadata route — `object-form`
 
-This is the route that actually reads and writes a record. `ObjectFormSchema`
-names its object with **`objectName`** and its intent with **`mode`**, and both
-are **required** (`packages/types/src/objectql.ts`); the adapter arrives on the
+This is the route that actually reads and writes a record. An `object-form`
+node names its object with **`objectName`** and its intent with **`mode`**, both
+in its `properties` bag, whose members are `@objectstack/spec`'s
+`ComponentPropsMap['object-form']` row; `objectui validate` refuses a prop
+written flat on the node by name. `SchemaRenderer` hoists the bag onto the node,
+and `ObjectFormSchema` (`packages/types/src/objectql.ts`) is the node as
+`ObjectForm` then reads it, with both keys required. The adapter arrives on the
 context, which `ObjectFormRenderer` reads at `src/index.tsx` before handing
 `ObjectForm` its `dataSource` prop.
 
@@ -647,19 +976,21 @@ context, which `ObjectFormRenderer` reads at `src/index.tsx` before handing
 import { SchemaRendererProvider, SchemaRenderer } from '@object-ui/react';
 import { createObjectStackAdapter } from '@object-ui/data-objectstack';
 import '@object-ui/plugin-form';
-import type { ObjectFormSchema } from '@object-ui/types';
+import type { ObjectFormBlockNode } from '@object-ui/types';
 
 const dataSource = createObjectStackAdapter({
   baseUrl: 'https://api.example.com',
   token: 'your-auth-token',
 });
 
-const schema: ObjectFormSchema = {
+const schema: ObjectFormBlockNode = {
   type: 'object-form',
-  objectName: 'users',
-  mode: 'create',
-  fields: ['name', 'email'],
-  submitText: 'Create user',
+  properties: {
+    objectName: 'users',
+    mode: 'create',
+    fields: ['name', 'email'],
+    submitText: 'Create user',
+  },
 };
 
 export const App = () => (
@@ -671,8 +1002,8 @@ export const App = () => (
 
 The object comes from `objectName`; there is no `resource` key. For `mode: 'edit'`
 or `'view'`, add the `recordId` of the record being opened. Note that this
-`mode` vocabulary is `'create' | 'edit' | 'view'` — the basic form's `mode` is a
-different key with a different vocabulary (`'edit' | 'read' | 'disabled'`, see
+`mode` vocabulary is `'create' | 'edit' | 'view'` and it lives on `object-form`
+only — the basic `form` node has no `mode` (retired by objectui#10286, see
 [Schema API](#schema-api)).
 
 ### The TypeScript route — basic `form`
@@ -684,6 +1015,7 @@ and hands them to your `onSubmit`, which the renderer awaits
 whatever that function does:
 
 ```typescript
+import { createObjectStackAdapter } from '@object-ui/data-objectstack';
 import type { FormSchema } from '@object-ui/types';
 
 const dataSource = createObjectStackAdapter({
@@ -723,7 +1055,7 @@ nothing:
 | Written on a form schema | What actually happens |
 |---|---|
 | `dataSource` | **Discarded.** The basic form strips it in both directions — `dataSource: _dataSource` at `form.tsx:304` (`stripRendererOnlyProps`) and `:2168` — so it never reaches a widget and never reaches the DOM. The adapter the fields receive is the context one |
-| `resource` | **Never read.** It is not declared on `FormSchema` or `ObjectFormSchema` at all. The key exists elsewhere in the protocol — on **`CRUDSchema`** (`packages/types/src/crud.ts`, `type: 'crud'`), where `CRUDBuilder` in `@object-ui/core` sets it — but no form renderer reads it under any spelling. On a form it names nothing |
+| `resource` | **Never read.** It is not declared on `FormSchema` or `ObjectFormSchema` at all. It used to exist elsewhere in the protocol — on `CRUDSchema`, where `CRUDBuilder` set it — but objectui#5373 retired both under ADR-0049, so today the key names nothing anywhere in this package's surface, and no form renderer reads it under any spelling |
 
 Both survive compilation for the reason [Schema API](#schema-api) gives: `FormSchema`
 and `ObjectFormSchema` extend `BaseSchema`, which declares `[key: string]: any`, so an