@object-ui/plugin-form 17.3.0 → 17.6.0

package/README.md

@@ -35,54 +35,303 @@ const schema = {
 };
 ```
 
-### Manual Registration
+### 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
+are the schema types those calls claim, read off the calls themselves in
+`src/index.tsx`:
+
+| Namespaced type | Bare-name fallback | Component behind it |
+|---|---|---|
+| `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 |
+
+`ComponentRegistry.register` also registers a namespaced type under its bare name
+for backwards compatibility, unless the call passes `skipFallback: true`
+(`@object-ui/core`, `src/registry/Registry.ts`). Two calls here do: bare `form`
+stays the basic `@object-ui/components` form, and bare `line_items` is left to
+whoever else claims it.
+
+### Public exports
+
+The package entry exports these — components, their prop/schema types, and the
+layout helpers. There is no aggregate map among them:
+
+```typescript
+import {
+  ObjectForm,
+  TabbedForm,
+  WizardForm,
+  SplitForm,
+  DrawerForm,
+  ModalForm,
+  EmbeddableForm,
+  MasterDetailForm,
+  LineItemsPanel,
+  FormAnalytics,
+  FormSectionContainer,
+  applyAutoLayout,
+  applyAutoColSpan,
+  inferColumns,
+  inferModalSize,
+  isWideFieldType,
+  isAutoGeneratedFieldType,
+  containerGridColsFor,
+  filterCreateModeFields,
+  filterSystemFields,
+  filterAutoGeneratedFields,
+  deriveDetail,
+  deriveColumns,
+  deriveFormFields,
+  findRelationshipField,
+  resolveInlineMode,
+} from '@object-ui/plugin-form';
+
+import type {
+  ObjectFormComponentProps,
+  ObjectFormProps,              // deprecated alias of ObjectFormComponentProps
+  FormSectionContainerProps,
+  TabbedFormProps,
+  TabbedFormSchema,
+  FormSectionConfig,
+  WizardFormProps,
+  WizardFormSchema,
+  SplitFormProps,
+  SplitFormSchema,
+  DrawerFormProps,
+  DrawerFormSchema,
+  ModalFormProps,
+  ModalFormSchema,
+  EmbeddableFormProps,
+  EmbeddableFormConfig,
+  EmbeddableFormTexts,
+  FormAnalyticsProps,
+  FormSubmissionMetric,
+  MasterDetailFormProps,
+  MasterDetailFormSchema,
+  MasterDetailDetailConfig,
+  LineItemsPanelSchema,
+  DerivedDetail,
+  InlineMode,
+} from '@object-ui/plugin-form';
+```
+
+### Registering a component under your own key
+
+To put one of these components on a schema type of your own, register the
+exported component:
 
 ```typescript
-import { formComponents } from '@object-ui/plugin-form';
 import { ComponentRegistry } from '@object-ui/core';
+import { ObjectForm } from '@object-ui/plugin-form';
 
-// Register form components
-Object.entries(formComponents).forEach(([type, component]) => {
-  ComponentRegistry.register(type, component);
-});
+ComponentRegistry.register('my-form', ObjectForm, { namespace: 'my-app' });
 ```
 
+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.
+
 ## Schema API
 
-### Form
+Two form schemas reach a renderer, and **both are declared in
+`@object-ui/types`** — this package imports them and declares neither. The
+tables below name the keys and point at the declaration; the declaration is the
+contract. (Restating an interface inside this README is what let this section
+drift away from the code in the first place — objectui#5075.)
+
+| Schema | `type` | Declared in | Rendered by |
+|---|---|---|---|
+| `FormSchema` | `'form'` | `packages/types/src/form.ts` | the basic form in `@object-ui/components` — bare `form` is deliberately **not** claimed by this plugin (`skipFallback: true`, see the table above) |
+| `ObjectFormSchema` | `'object-form'` | `packages/types/src/objectql.ts` | `ObjectForm` here, through `plugin-form:object-form` / `object-form` |
+
+Both `type` slots are string **literals**. A schema whose `type` names something
+no registration claims does not fall back to a form — it renders the
+unknown-component placeholder.
+
+### Form (`type: 'form'`)
+
+| Key | Type | Notes |
+|---|---|---|
+| `type` | `'form'` | literal, not a free string |
+| `fields` | `FormField[]` | **optional** — a form may render `children` instead |
+| `defaultValues` | `Record<string, any>` | form-level initial values. There is no field-level `defaultValue` |
+| `submitLabel` / `cancelLabel` | `string` | button text |
+| `showCancel` / `showActions` | `boolean` | action-row composition |
+| `mobileStickyActions` | `boolean` | pin the action row on small viewports |
+| `layout` | `'vertical' \| 'horizontal'` | label placement |
+| `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 |
+| `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>` |
+| `fieldTabs` / `defaultFieldTab` / `fieldTabsPosition` | see [Tabbed field layout](#tabbed-field-layout-fieldtabs) | |
+| `fieldPanes` / `fieldPanesOrientation` / `fieldPanesResizable` | see [Split field layout](#split-field-layout-fieldpanes) | |
+| `actions` | `SchemaNode[]` | extra nodes in the action row |
+| `children` | `SchemaNode \| SchemaNode[]` | custom body instead of `fields` |
+| `onSubmit` / `onChange` / `onDirtyChange` / `onCancel` | callbacks | **TypeScript-authored schemas only** — a JSON metadata document cannot carry a function. Metadata pages go through the object-form route instead |
+| `className`, `id`, `hidden`, … | — | inherited from `BaseSchema` |
+
+⚠️ `FormSchema` extends `BaseSchema`, which declares `[key: string]: any`
+(`packages/types/src/base.ts`), so an invented or misspelled key on a form schema
+is **not** a compile error — it is simply never read. That is why every example
+below is annotated with its real type *and* checked against these key tables:
+an un-annotated `const schema = { … }` type-checks whatever is written in it.
 
-Complete form with fields and validation:
+### Form Field
 
-```typescript
-{
-  type: 'form',
-  fields: FormField[],
-  submitLabel?: string,
-  cancelLabel?: string,
-  onSubmit?: (data) => void,
-  onCancel?: () => void,
-  className?: string
-}
+`FormField` (`packages/types/src/form.ts`) declares 23 keys, and `name` is the
+only **required** one:
+
+| Key | Type | What it does |
+|---|---|---|
+| `name` | `string` | **required** — the submit key |
+| `id` | `string` | stable render key; falls back to `name` |
+| `label` | `string` | optional — with none, no label element is rendered at all (validation messages fall back to `name`). The object-bound paths always fill it from the object field |
+| `description` | `string` | help text under the control |
+| `type` | `string` | optional, defaults to `'input'`. Built-ins: `input`, `textarea`, `checkbox`, `switch`, `select`; any other value resolves through the registry (`field:<type>` first, then the bare name) |
+| `inputType` | `string` | HTML input type for `type: 'input'` — `'email'`, `'password'`, `'tel'`, … |
+| `widget` | `string` | widget override; wins over `type` (spec `FormField.widget`) |
+| `placeholder` | `string` | |
+| `required` | `boolean` | the presence rule. `validation.required` does **not** make a field required — see below |
+| `disabled` | `boolean` | not interactive, muted |
+| `readonly` | `boolean` | shown plainly, not editable — deliberately distinct from `disabled` |
+| `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 |
+| `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` |
+
+`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:
+
+| 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.) |
+
+There is no `ValidationRule` type in this repo, under any spelling.
+
+#### `validation` is an object keyed by rule name
+
+`FieldValidationRules` (`packages/types/src/form.ts`) is **not** an array of
+`{ type, value, message }` entries:
+
+| Rule | Type | Notes |
+|---|---|---|
+| `required` | `string \| boolean` | supplies the required **message** only. Whether the field is required is decided by `required` / `requiredWhen` **on the field** |
+| `minLength` / `maxLength` | `{ value: number; message: string }` | `message` is not optional when you author the rule by hand |
+| `min` / `max` | `{ value: number; message: string }` | numeric range |
+| `pattern` | `{ value: string \| RegExp; message: string }` | pass a **RegExp** in a hand-authored schema: react-hook-form only applies a pattern whose value `instanceof RegExp`, and it is the object-metadata path (`buildValidationRules` in `@object-ui/fields`) that compiles a declared string into one |
+| `validate` | `(value) => boolean \| string \| Promise<boolean \| string>` | custom check; TypeScript-authored schemas only |
+
+There is no `email` rule name — an email check is a `pattern`, which is exactly
+what `buildValidationRules` emits for an object field of type `email`.
+
+**Why the array spelling fails silently.** The only reader of this key is the
+basic form renderer, which spreads it into the rule object handed to
+react-hook-form — `const rules: any = { ...validation }`
+(`packages/components/src/renderers/form/form.tsx:1652`). Spreading an **array**
+into an object literal produces numeric keys (`{ '0': …, '1': … }`), which
+react-hook-form does not recognise: every rule is dropped, nothing throws, and
+the form looks validated while validating nothing.
+
+### What a create form opens with
+
+A create form has no persisted record, so its opening values come from the
+object schema's declared field `defaultValue`s. Every object-form container
+(`ObjectForm`, `ModalForm`, `DrawerForm`, `TabbedForm`, `SplitForm`,
+`WizardForm`) resolves them the same way, through `schemaDefaults`:
+
+| Declared | Create form opens with | Why |
+|---|---|---|
+| `defaultValue: 'draft'` (any static literal) | `draft`, preselected and submittable | the value is known; making the user pick it is busywork, and on a status-like field every wrong option is one click away |
+| `defaultValue: 'NOW()'` / `'current_user'` (a runtime token) | empty | the token is an *instruction*, not a value. The server resolves it at insert — but only for fields that arrive empty, so seeding the literal text would suppress it |
+| `defaultValue: cel\`today()\`` (an Expression envelope) | empty | same reason: the server evaluates it per insert |
+| an option's `default: true` | empty | see below |
+| nothing | empty | no default is invented |
+
+`initialData` / `initialValues` passed by the caller always outrank a schema
+default — a lookup prefill or a "duplicate this record" seed is the more
+specific instruction.
+
+Only the **field-level** `defaultValue` is read, never a select option's
+`default: true`, even though `@objectstack/spec`'s `SelectOptionSchema` declares
+that key. The server's insert path resolves `defaultValue` and nothing else, so
+a form that also seeded from option-level `default` would preselect values the
+server would never have applied on its own — a renderer-side second default
+contract (AGENTS.md #0.1). If option-level `default` is meant to mean "the
+initial value", that belongs at the producer.
+
+**Edit forms are never seeded.** An edit form shows the row as the server holds
+it; folding a default in over a column the record leaves unset would arm a
+silent write of a value the user never chose, on the next save of any other
+field.
+
+#### `required` (or `requiredWhen`) + a runtime default
+
+A field may declare both, and it is coherent authoring — storage-level required,
+with the value guaranteed by the producer:
+
+```ts
+remind_at: Field.datetime({ required: true, defaultValue: 'NOW()' }),
 ```
 
-### Form Field
+But the control opens empty (see the table), so enforcing `required` on it
+refused the submit with nothing sensible for the user to type. In **create**
+mode a runtime `defaultValue` therefore suppresses the client-side `required`
+rule, and the field is **omitted from the payload** — omitted, not sent empty,
+because `applyFieldDefaults` resolves the declaration only for a field that
+arrives absent or null, and a blank string is neither.
 
-Individual form field configuration:
+The **conditional** spelling reaches the same verdict. A `requiredWhen`
+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:
 
-```typescript
-interface FormField {
-  name: string;
-  type: string;                   // 'input', 'select', 'checkbox', etc.
-  label: string;
-  placeholder?: string;
-  required?: boolean;
-  validation?: ValidationRule[];
-  defaultValue?: any;
-  disabled?: boolean;
-  className?: string;
-}
+```ts
+remind_at: Field.datetime({ requiredWhen: 'record.status == "scheduled"', defaultValue: 'NOW()' }),
 ```
 
+| Mode | Declared | Left empty | Effect |
+|---|---|---|---|
+| create | `required` / `requiredWhen` TRUE + a runtime default | yes | submits; the key is absent, and the server resolves it |
+| create | `required` / `requiredWhen` TRUE + a runtime default | no (user typed) | submits the typed value — it outranks the default |
+| create | `required` / `requiredWhen` TRUE + a static literal | user cleared the seeded control | refused: they removed a value that was really there |
+| create | `requiredWhen` TRUE, no default | yes | refused: nobody else supplies this value |
+| edit | `required` / `requiredWhen` TRUE, anything | user blanked it | refused: the token was resolved at insert, so this is a real removal |
+
+The required marker and `aria-required` go with the rule in the create case,
+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.
+
+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
+also refuses to submit. The static half is decided at the producer, in
+`isRequiredInForm`; the conditional half cannot be, because `requiredWhen` is
+resolved downstream against the live record, so it is suppressed inside the one
+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.
+
 ### Column width of a sectioned form
 
 A sectioned form renders as ONE grid, and two keys decide its shape:
@@ -194,7 +443,9 @@ primary pane, the rest stack in the secondary one behind inline section headers.
 ### Basic Form
 
 ```typescript
-const schema = {
+import type { FormSchema } from '@object-ui/types';
+
+const schema: FormSchema = {
   type: 'form',
   fields: [
     {
@@ -210,9 +461,15 @@ const schema = {
       inputType: 'email',
       label: 'Email Address',
       required: true,
-      validation: [
-        { type: 'email', message: 'Invalid email format' }
-      ]
+      // Rule name → rule. Not an array (see Schema API above), and there is no
+      // 'email' rule: the email check is the pattern the metadata path builds
+      // for a field of type `email`.
+      validation: {
+        pattern: {
+          value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+          message: 'Invalid email format'
+        }
+      }
     },
     {
       name: 'country',
@@ -239,51 +496,111 @@ const schema = {
 
 ### Multi-Step Form
 
+A multi-step form is an **`object-form` with `formType: 'wizard'`**, and its
+steps are its `sections` — one step per section. There is no
+`multi-step-form` schema type (no registration anywhere claims that name) and no
+`steps` key on any form schema, so a schema written that way renders the
+unknown-component placeholder and the fields inside `steps` are never read.
+
 ```typescript
-const schema = {
-  type: 'multi-step-form',
-  steps: [
+import type { ObjectFormSchema } from '@object-ui/types';
+
+const schema: ObjectFormSchema = {
+  type: 'object-form',
+  objectName: 'contacts',        // required
+  mode: 'create',                // required
+  formType: 'wizard',            // routes to WizardForm — needs at least one section
+  sections: [
     {
-      title: 'Personal Info',
+      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
+};
+```
+
+A section's `fields` accepts three shapes — a field **name**, a spec
+`FormFieldSchema` object (whose identity key is `field`), or an inline runtime
+`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):
+
+```tsx
+import { WizardForm } from '@object-ui/plugin-form';
+import type { WizardFormSchema } from '@object-ui/plugin-form';
+
+const wizard: WizardFormSchema = {
+  type: 'object-form',
+  formType: 'wizard',
+  objectName: 'contacts',
+  mode: 'create',
+  sections: [
+    {
+      name: 'personal',
+      label: 'Personal Info',
       fields: [
         { name: 'firstName', type: 'input', label: 'First Name', required: true },
         { name: 'lastName', type: 'input', label: 'Last Name', required: true }
       ]
     },
     {
-      title: 'Contact Info',
+      name: 'contact',
+      label: 'Contact Info',
       fields: [
         { name: 'email', type: 'input', inputType: 'email', label: 'Email', required: true },
         { name: 'phone', type: 'input', inputType: 'tel', label: 'Phone' }
       ]
-    },
-    {
-      title: 'Review',
-      fields: []
     }
   ],
-  onSubmit: (data) => {
+  onSuccess: (data) => {
     console.log('Multi-step form completed:', data);
   }
 };
+
+<WizardForm schema={wizard} />   // dataSource omitted: every step lists inline fields
 ```
 
+`WizardFormSchema` declares no index signature, so an invented key on *this*
+type is a real compile error — unlike `ObjectFormSchema`, which inherits
+`BaseSchema`'s `[key: string]: any`.
+
+One more route exists and is worth knowing about rather than reinventing: a flat
+`object-form` can be turned into a stepper on small viewports with
+`mobile: { stepper: true | 'auto', stepperFieldsPerStep, stepperMinFields }`,
+which feeds the same `WizardForm`.
+
 ### Form with Validation
 
 ```typescript
-const schema = {
+import type { FormSchema } from '@object-ui/types';
+
+const schema: FormSchema = {
   type: 'form',
+  validationMode: 'onBlur',
   fields: [
     {
       name: 'username',
       type: 'input',
       label: 'Username',
-      required: true,
-      validation: [
-        { type: 'minLength', value: 3, message: 'Username must be at least 3 characters' },
-        { type: 'maxLength', value: 20, message: 'Username must be less than 20 characters' },
-        { type: 'pattern', value: '^[a-zA-Z0-9_]+$', message: 'Only letters, numbers, and underscores' }
-      ]
+      required: true,                 // presence: this is the key that decides it
+      validation: {
+        required: 'Pick a username',   // the MESSAGE for the rule above, nothing more
+        minLength: { value: 3, message: 'Username must be at least 3 characters' },
+        maxLength: { value: 20, message: 'Username must be less than 20 characters' },
+        pattern: {
+          value: /^[a-zA-Z0-9_]+$/,    // a RegExp, not a string
+          message: 'Only letters, numbers, and underscores'
+        }
+      }
     },
     {
       name: 'password',
@@ -291,42 +608,153 @@ const schema = {
       inputType: 'password',
       label: 'Password',
       required: true,
-      validation: [
-        { type: 'minLength', value: 8, message: 'Password must be at least 8 characters' },
-        { type: 'pattern', value: '(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9])', message: 'Must contain uppercase, lowercase, and number' }
-      ]
+      validation: {
+        minLength: { value: 8, message: 'Password must be at least 8 characters' },
+        pattern: {
+          value: /(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9])/,
+          message: 'Must contain uppercase, lowercase, and number'
+        },
+        validate: (value) =>
+          String(value).toLowerCase() !== 'password' || 'Pick something less guessable'
+      }
     }
   ]
 };
 ```
 
+Each rule appears **once**, under its own name — an object, not a list. A second
+`minLength` cannot exist, which is the point: the shape the renderer hands
+react-hook-form is one rule per kind.
+
 ## Integration with Data Sources
 
-Connect forms to backend APIs:
+**The adapter is not a schema key.** A schema is a serialisable document; a live
+adapter is an object with methods, so it cannot travel in one. Both form routes
+read the adapter from React context, which the host installs once above the whole
+tree — the same rule [Registering a component under your own
+key](#registering-a-component-under-your-own-key) states for custom
+registrations.
 
-```typescript
+### 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
+context, which `ObjectFormRenderer` reads at `src/index.tsx` before handing
+`ObjectForm` its `dataSource` prop.
+
+```tsx
+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';
 
 const dataSource = createObjectStackAdapter({
   baseUrl: 'https://api.example.com',
-  token: 'your-auth-token'
+  token: 'your-auth-token',
 });
 
-const schema = {
+const schema: ObjectFormSchema = {
+  type: 'object-form',
+  objectName: 'users',
+  mode: 'create',
+  fields: ['name', 'email'],
+  submitText: 'Create user',
+};
+
+export const App = () => (
+  <SchemaRendererProvider dataSource={dataSource}>
+    <SchemaRenderer schema={schema} />
+  </SchemaRendererProvider>
+);
+```
+
+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
+[Schema API](#schema-api)).
+
+### The TypeScript route — basic `form`
+
+A bare `form` never fetches or saves by itself: it has no object name and no
+query, so there is nothing for it to call an adapter *with*. It collects values
+and hands them to your `onSubmit`, which the renderer awaits
+(`packages/components/src/renderers/form/form.tsx:1428`). Any persistence is
+whatever that function does:
+
+```typescript
+import type { FormSchema } from '@object-ui/types';
+
+const dataSource = createObjectStackAdapter({
+  baseUrl: 'https://api.example.com',
+  token: 'your-auth-token',
+});
+
+const schema: FormSchema = {
   type: 'form',
-  dataSource,
-  resource: 'users',
-  fields: [/* fields */],
+  fields: [
+    { name: 'name', type: 'input', label: 'Full Name', required: true },
+    { name: 'email', type: 'input', inputType: 'email', label: 'Email', required: true },
+  ],
+  submitLabel: 'Create user',
+  // The adapter reaches this call through the CLOSURE, not through the schema.
   onSubmit: async (data) => {
     await dataSource.create('users', data);
-  }
+  },
 };
 ```
 
+`onSubmit` is a function, so this route is **TypeScript-authored schemas only** —
+a JSON metadata document cannot carry one. Metadata pages take the `object-form`
+route above.
+
+What the adapter on the context still does for a bare `form` is supply the
+**field widgets**: the renderer reads it at `form.tsx:1004`
+(`const contextDataSource = schemaCtx?.dataSource ?? null`) and passes it down
+per field at `:2061`, which is how a lookup or cascading select loads its
+options. Nothing else about the form is wired to it.
+
+### Keys that look like wiring but are not
+
+Neither of these is a key of either form schema, and writing them changes
+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 |
+
+Both survive compilation for the reason [Schema API](#schema-api) gives: `FormSchema`
+and `ObjectFormSchema` extend `BaseSchema`, which declares `[key: string]: any`, so an
+invented key is not a type error — it is simply never read. That is also why the
+older version of this section looked like it worked: its `onSubmit` genuinely ran
+and genuinely saved, but through the adapter its closure captured. The `dataSource`
+and `resource` keys sitting beside it in the same object were inert. Delete them and
+that example behaves identically — which is the test for whether a key is doing
+anything.
+
+> A top-level `dataSource` **does** mean something on a schema node, but it is not
+> an adapter: it is the spec's element **binding** (`PageComponentSchema.dataSource`,
+> objectstack#6953) — a descriptor such as `{ object: 'users' }` — resolved by
+> `useElementDataSource` (`packages/react/src/hooks/useElementDataSource.ts:139`).
+> `object-form` passes through that gate, and honours the binding's `object` key
+> only. Handing that slot a live adapter is rejected on purpose: the predicate
+> refuses any value carrying a `find` method
+> (`packages/core/src/data-scope/element-data-source.ts:131`), so an adapter written
+> there is ignored rather than mistaken for a binding. Pass adapters through the
+> provider above.
+
 ## TypeScript Support
 
+`FormSchema` and `FormField` are protocol types, so they live in
+`@object-ui/types` alongside the rest of the JSON contract. This package imports
+them and does not re-export them — the form types on its own entry are the
+per-container ones (`TabbedFormSchema`, `WizardFormSchema`, `ModalFormSchema`, …)
+listed under [Public exports](#public-exports).
+
 ```typescript
-import type { FormSchema, FormField } from '@object-ui/plugin-form';
+import type { FormSchema, FormField } from '@object-ui/types';
 
 const emailField: FormField = {
   name: 'email',
@@ -357,17 +785,6 @@ The plugin includes these field components:
 - Date picker
 - File upload
 
-<!-- release-metadata:v3.3.0 -->
-
-## Compatibility
-
-- **React:** 18.x or 19.x
-- **Node.js:** ≥ 18
-- **TypeScript:** ≥ 5.0 (strict mode)
-- **`@objectstack/spec`:** ^3.3.0
-- **`@objectstack/client`:** ^3.3.0
-- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
-
 ## Links
 
 - 📚 [Documentation](https://www.objectui.org/docs/plugins/plugin-form)