@cube-dev/ui-kit 0.0.0-canary-c2f337e → 0.0.0-canary-36c17b9

package/docs/modern-form-guide.md

@@ -0,0 +1,268 @@
+# Modern Form: choose the API for the job
+
+For a new modern form, start with `Form.useController<Model>()`, bind inputs with `field={form.field(path)}`, and submit through `<Form onSubmit={...}>` and `<Form.Submit>`. Add subscriptions only where other UI needs to read form state. The input components already subscribe to their own values and errors.
+
+Existing `Form.useForm()` forms and roots without a modern controller use the legacy backend. Follow the [migration checklist](https://github.com/cube-js/cube-ui-kit/blob/main/docs/modern-form-migration.md) when converting one. `DialogForm` still requires a legacy instance; do not pass a modern controller through a cast.
+
+Recipes: [API choices](#pick-one-binding-and-one-owner-for-each-concern), [reactive UI](#read-a-value-show-status-or-reveal-a-section), [server data](#load-server-data-refresh-defaults-or-discard-edits), [programmatic edits](#edit-values-from-an-event-handler), [validation](#validate-simple-rules-sibling-fields-or-an-api-response), [conditional fields and wizards](#hide-fields-use-nested-data-or-build-a-wizard), [submission](#submit-display-server-errors-and-reset), and [custom controls](#implement-a-reusable-custom-control).
+
+## Start with an ordinary edit form
+
+```tsx
+import { Form, Switch, TextInput } from '@cube-dev/ui-kit';
+import type { FormValues } from '@cube-dev/ui-kit';
+
+interface Profile {
+  email: string | null;
+  notifications: boolean | null;
+}
+
+function ProfileForm({
+  initialProfile,
+  save,
+}: {
+  initialProfile: Profile;
+  save: (values: FormValues<Profile>, signal: AbortSignal) => Promise<void>;
+}) {
+  const form = Form.useController<Profile>({ defaultValues: initialProfile });
+
+  return (
+    <Form form={form} onSubmit={(values, { signal }) => save(values, signal)}>
+      <TextInput
+        field={form.field('email', {
+          rules: [{ type: 'email', message: 'Enter a valid email' }],
+        })}
+        label="Email"
+        isRequired
+      />
+      <Switch field={form.field('notifications')} label="Notifications" />
+      <Form.SubmitError />
+      <Form.Submit>Save</Form.Submit>
+      <Form.Reset>Reset</Form.Reset>
+    </Form>
+  );
+}
+```
+
+The model describes possible values, including API `null`s. A text input displays `null` as empty and a switch displays it as unchecked; neither writes that display fallback into the form. Editing uses the control's normal change payload, and reset restores the nullable default. `FormValues<Model>` describes readonly, potentially incomplete data: registration and validation do not prove that every model property is present. Map to your API's request type explicitly where it requires complete data.
+
+`defaultValues` initializes this controller once. A later `initialProfile` prop does not overwrite edits. Use the loading commands below, or remount the form with a record key when switching records should start a new editing session. Modern roots do not accept `defaultValues`.
+
+## Pick one binding and one owner for each concern
+
+| Concern | Start here | Use the alternative when… |
+| --- | --- | --- |
+| Connect an input | `field={form.field(path, options)}` | `name="email"` keeps a shared legacy/modern wrapper working. Names are not checked against the controller's model. |
+| Locate the controller | Use the controller you created, or pass it as a prop | `Form.useControllerContext<Model>()` avoids prop threading in a descendant. It reads context without subscribing. |
+| Configure a field | Put `rules`, `validate`, dependencies, and retention on the descriptor | Input-level registration props support reusable controls with their own defaults and legacy callers. Avoid configuring the same option in both places. |
+| Present a field | Input props such as `label`, `description`, `isRequired` | `rules: [{ required: true }]` is useful when required validation needs a custom message or no visible required marker. |
+| Handle submit/change/failure | Callbacks on the owning `<Form>` | Hook callbacks let a controller own behavior independently of a root, or provide defaults to a wrapper. Choose one location per callback. |
+| Initialize values | Controller `defaultValues` | Field `defaultValue` supplies a fallback for a reusable field missing from the controller's data. |
+
+`Form.Submit`, `Form.Reset`, and `Form.SubmitError` are aliases of the exported `SubmitButton`, `ResetButton`, and `SubmitError` components. This guide uses the `Form.*` names consistently; importing a standalone name does not select a different implementation.
+
+A descriptor is pure configuration, so creating it inline is expected. It neither reads state nor registers a field; the mounted input registers after commit. It supplies the controller and path even outside the root, so adding `form` or `name` to the same input is unnecessary. If both are present, the descriptor wins. Descriptor options override only matching options they supply. In particular, descriptor `rules` or `validate` replaces input-level `rules`; put built-in rules and a custom validator together on the descriptor to run both.
+
+Controller values and defaults take precedence over field defaults, including explicit `null` and `undefined`. Root callbacks override the corresponding hook callback while mounted; omitted or undefined root callbacks fall back to the hook callback. Business callbacks update after every committed render. Defaults, `errorPolicy`, and diagnostic handlers are creation options; update values through commands and override error policy per field when needed.
+
+Use one owning root per controller. Omitted `form` props use context; explicitly passing `form={undefined}` detaches an input. Legacy roots and `FormScopeMask` hide the surrounding modern context.
+
+## Read a value, show status, or reveal a section
+
+| UI needs | Use | Why it exists |
+| --- | --- | --- |
+| One field's value | `Form.useValue(form, path)` | Checked path and inferred value without writing a selector. |
+| A field's value, errors, or metadata | `Form.useFieldState(form, path)` | Checked path with typed value/default, errors, status, dirty, touched, and active state. |
+| A derived result or form-wide flag | `Form.useSelector(form, selector)` | General selection, such as `state.isDirty` or `state.canReset`. |
+| A small inline region that reacts independently | `<Form.Subscribe form={form} selector={...}>` | Keeps the subscription in that subtree without extracting a component. |
+| A value in an event handler or effect | `form.getValue(path)` / `form.getValues()` | One-time imperative read; it does not subscribe React. |
+
+The value and field-state hooks are conveniences over selectors. The choice between a hook and `Subscribe` is where rerenders should happen: hooks rerender their component, while `Subscribe` rerenders its children region. Creating a controller does not subscribe its owner. Prefer a leaf component for reusable reactive UI:
+
+```tsx
+function EmailPreview() {
+  const form = Form.useControllerContext<Profile>();
+  const email = Form.useValue(form, 'email');
+  return <output>{email ?? 'No email set'}</output>;
+}
+```
+
+Use `Subscribe` for a conditional section directly inside the form:
+
+```tsx
+<Form.Subscribe form={form} selector={(state) => state.values.notifications}>
+  {(enabled) =>
+    enabled ? <TextInput field={form.field('email')} label="Email" /> : null
+  }
+</Form.Subscribe>
+```
+
+These are alternative placements of the email input, not an instruction to mount it twice. Pass `form` to `Subscribe` for inferred model types. It can also use modern context when `form` is omitted, but React context cannot infer the ancestor's model. The generic on `useControllerContext<Profile>()` is your assertion that the ancestor uses `Profile`.
+
+Selectors and equality functions must be pure. Select a primitive or a stable snapshot branch; allocating a fresh object compares unequal under the default `Object.is`. Supply `isEqual` when such an object should compare by its contents. `useFieldState` can return `undefined` before a path is tracked. Getter reads in JSX will not stay current. Plain objects and arrays in snapshots are deeply readonly and potentially incomplete; use commands for writes. Date-control values retain their methods; treat them and other non-plain values as immutable.
+
+## Load server data, refresh defaults, or discard edits
+
+Most forms need only initialization, adoption for incoming data, and reset for a new editing session. The other modes let integrations change the reset baseline independently of user interaction.
+
+| Situation | Command | Effect |
+| --- | --- | --- |
+| Data is available before mounting | `Form.useController({ defaultValues })` | Seeds values and the reset baseline once. |
+| A response arrives while the user may be typing | `adoptDefaultValues(response, { when: 'untouched' })` | Replaces the baseline and adopts untouched fields, preserving touched values. This is the default adoption policy. |
+| Refresh fields that still match their previous defaults | `adoptDefaultValues(response, { when: 'clean' })` | Preserves dirty values, including programmatic edits; touched-but-clean fields can refresh. |
+| Discard edits and start from a different record | `reset({ values: response })` | Replaces baseline and values, clears interaction/errors, and cancels pending submission. |
+| Discard edits using the existing baseline | `reset()` / `<Form.Reset>` | Restores defaults and clears interaction/errors. |
+| Change what Reset will restore without changing the draft | `setDefaultValues(response)` | Replaces only the baseline; dirtiness is recomputed against it. |
+
+All defaults commands replace the baseline object; omitted keys are removed from it. Adoption also starts from the incoming object, then restores protected paths. It is not a partial patch. Use `setValue` or `setValues` for edits to current data.
+
+### Advanced defaults policies
+
+Use these only when the ordinary adoption or reset behavior above does not fit the interaction:
+
+| Situation | Command | Effect |
+| --- | --- | --- |
+| Protect both touched and dirty fields | `adoptDefaultValues(response, { when: 'untouched', preserveDirty: true })` | Adds dirty-value protection to the touched check. |
+| Replace values but keep touched state and submission state | `adoptDefaultValues(response, { when: 'always' })` | Replaces values and baseline; invalidates affected field validation. |
+| Replace values and clear field interaction, keeping submission state | `setDefaultValues(response, { currentValues: 'replace' })` | Replaces values and baseline; clears touched/field validation, but does not cancel submission or clear its error. |
+
+### Asynchronous loading
+
+For asynchronous loading, protect both user edits and request ordering:
+
+```tsx
+useEffect(() => {
+  const request = new AbortController();
+  void load(request.signal)
+    .then((profile) => {
+      if (!request.signal.aborted) {
+        setLoadError(undefined);
+        form.adoptDefaultValues(profile, { when: 'untouched' });
+      }
+    })
+    .catch((error: unknown) => {
+      if (!request.signal.aborted) setLoadError(error);
+    });
+  return () => request.abort();
+}, [form, load]);
+```
+
+Here `load` is a stable loader for the current record and `setLoadError` is local UI state; import `useEffect` from React. Gate editing on loading if a partially loaded record must never be submitted. When switching records, remount or reset the editing session: adopting an unrelated record while preserving old edits would mix the two.
+
+## Edit values from an event handler
+
+Use `setValue(path, value)` for one path and `setValues(partial)` for several top-level keys. Nested objects supplied to `setValues` replace those objects; use tuple paths to update an individual nested leaf. Neither command changes the reset baseline.
+
+```tsx
+<button
+  type="button"
+  onClick={() => form.setValue('notifications', true, { source: 'user' })}
+>
+  Enable notifications
+</button>
+```
+
+`source: 'user'` defaults to touching the field and notifying `onValuesChange` when values change. Programmatic writes default to neither; override `touch` and `notify` explicitly when needed. `validate` defaults to `auto`; use `always` to force validation or `never` to invalidate without revalidating. `onValuesChange(values, change)` receives retained values and `{ names, source, kind }`. Use it for user-edit integrations such as a debounced draft saver; decide separately whether programmatic writes should trigger that saver. Defaults adoption, value replacement, and reset also notify this callback when they report changed paths; filter `change.kind` or `change.source` if only direct edits should be saved.
+
+`batch(() => { ... })` combines synchronous commands into one publication. It is useful for several tuple writes; it is not a rollback transaction and must not wrap async work. `subscribe(listener)` is for imperative integrations that need every publication; React UI should use the hooks above and observers must call the returned unsubscribe function.
+
+## Validate simple rules, sibling fields, or an API response
+
+| Validation case | Start here |
+| --- | --- |
+| Required field with a visible marker | Input `isRequired`; it adds required validation too. |
+| Email, length, range, pattern, or enum | Descriptor `rules` using the built-in constraints. |
+| Custom domain check | Descriptor `validate(value, context)` for an inferred field value and checked reads. |
+| Several custom rules or existing shared rule objects | `rules: [{ validator(rule, value, context) { ... } }]`; use `ModernValidationRule` for strict modern rule typing. |
+| Validation depends on another form value | `dependsOn: ['password']`, or nested tuples such as `dependsOn: [['account', 'password']]`. |
+| Validation captures props or other external values | `deps: [organizationId, checkName]`. Include changing functions too. |
+| An integration explicitly versions function behavior | `rulesKey: revision`; ordinary forms can leave it out. |
+
+`deps` and `dependsOn` deliberately have separate jobs. A string in `deps` is an external value; the same string in `dependsOn` names a form field. Use both when a validator reads both sources. `rulesKey` is an advanced function revision, not another place to list ordinary dependencies.
+
+A password confirmation can declare its sibling dependency even when an early return skips the read:
+
+```tsx
+<TextInput
+  field={form.field('confirmation', {
+    dependsOn: ['password'],
+    validate: (value, { getValue }) => {
+      if (!value) return;
+      return value === getValue('password') ? undefined : 'Passwords must match';
+    },
+  })}
+  label="Confirm password"
+  type="password"
+  isRequired
+/>
+```
+
+This example uses a controller whose model contains `password` and `confirmation`. A declared dependency change revalidates fields that were already validated or validating, unless the write requests `validate: 'never'`. Reads through validator `getValue`/`getValues` use one captured snapshot and cancel in-flight work if that data changes; reads alone do not schedule another run.
+
+For a remote check, pass the cancellation signal and declare captured inputs:
+
+```tsx
+<TextInput
+  field={form.field('name', {
+    deps: [organizationId, checkName],
+    validateTrigger: 'onChange',
+    validationDelay: 200,
+    validate: async (value, { signal }) => {
+      if (!value) return;
+      const available = await checkName(organizationId, value, signal);
+      return available ? undefined : 'Name is already in use';
+    },
+  })}
+  label="Name"
+  isRequired
+/>
+```
+
+Here the model contains a string `name`, and `checkName` returns `Promise<boolean>`. A validator succeeds by returning `undefined`, `null`, or an empty string. Return a ReactNode error, or throw/reject, to fail. Adapt legacy validators that resolve data objects; those are failures in the modern contract. Superseded results cannot overwrite current errors even if the validator ignores its signal.
+
+Automatic validation honors `validateTrigger` and `validationDelay`. An `auto` write revalidates on-change fields and fields already showing errors; otherwise on-blur fields wait for blur. Explicit `form.validate()` and submission validate immediately; `form.validate(['email'])` selects a literal path, and `form.validate([['rows', 0, 'email']])` selects a nested path. Inspect `{ isValid, stale, fields }` before advancing a wizard step. Validation covers active fields only. `errorPolicy: 'first' | 'all'` controls rule-error collection, with `first` as the default.
+
+Rule constraints and function source are compared automatically so equivalent inline validators do not restart pending work. Captures require `deps`; different functions with identical source, including bound/native functions, also need an explicit dependency or revision. `rulesKey` skips function-source comparison only; constraints such as `min`, `pattern`, and `required` are still compared. Update the key or dependencies when function behavior changes. `deps` alone retains source comparison.
+
+## Hide fields, use nested data, or build a wizard
+
+Unmounting the last input at a path removes it from `activeValues` immediately and retains its draft by default. Remounting restores that draft. Use `field={form.field('details', { preserve: false })}` when leaving a section should discard its current value. Cleanup removes the value, but its default baseline remains available to reset. Visually hiding an input while leaving it mounted does not unregister it.
+
+| Payload | How to choose it | Validation |
+| --- | --- | --- |
+| Mounted fields | `<Form>` / `form.submit()` defaults | Active registered fields only. |
+| All retained data, including hidden sections | `<Form submitValues="all">` or `form.submit({ include: 'all' })` | Still only active registered fields. |
+
+For a wizard, validate a step before unmounting it and choose `submitValues="all"` if previous steps belong in the final payload. That does not revalidate unmounted steps. If final submission must validate every step against the latest data, keep the relevant inputs mounted or perform whole-payload validation explicitly. A form with no active fields is invalid.
+
+Bind nested leaves with tuples: `field={form.field(['rows', index, 'email'])}`. A string such as `'user.email'` is one literal key, not dot notation. Numeric indices and numeric string segments address the same path. Removing an array path does not shift the other indices. Registering a parent object makes its complete value active; register leaf paths when only selected children belong in the active payload. Known literal paths are typechecked; widened dynamic paths are supported. The declaration surface requires TypeScript 5.4 or newer.
+
+`getValues()` / `state.values` contains all retained data; `getActiveValues()` / `state.activeValues` contains registered paths. Dirty/touched metadata includes retained fields, while validity concerns active fields.
+
+## Submit, display server errors, and reset
+
+Use `<Form.Submit>` for normal submission, including Enter in the form. It handles loading and stays enabled after validation errors so users can request feedback again. `disableOnInvalid` opts into disabling it on invalid state. Use `form.submit()` for a workflow controlled from an event handler; inspect its result (`submitted`, `invalid`, `failed`, `ignored`, or `stale`) before continuing. Choose the payload independently for each call: imperative `submit()` defaults to active values even if the root has `submitValues="all"`.
+
+To place actions or errors outside the root, pass the controller:
+
+```tsx
+<Form.Submit form={form}>Save</Form.Submit>
+<Form.Reset form={form}>Reset</Form.Reset>
+<Form.SubmitError form={form} />
+```
+
+An explicit-controller Submit targets that controller's owning form even inside another DOM form. Return or await the request in `onSubmit(values, { signal, include })`; concurrent submissions are ignored. Throwing or rejecting sets `submitError`, which `Form.SubmitError` displays with a safe generic fallback. Supply `renderError` to format application errors. Ordinary edits keep that error; another submit or reset clears it.
+
+Use `setFieldErrors('email', ['Email is already registered'])` for a server error attached to an input and `clearFieldErrors('email')` to clear it. `setSubmitError` / `clearSubmitError` manage a form-level failure. `onSubmitFailed` receives `{ status: 'invalid', errors }` for field validation or `{ status: 'failed', error }` for a rejected submit callback; field validation does not set `submitError`.
+
+`Form.Reset` is enabled when `state.canReset` is true: edits, touched/validation state, or a submit error can be cleared, and no submission is running. Use that selector for a custom reset UI. Direct `form.reset()` can also cancel an active submission; unmounting the owning root cancels it too. Action buttons preserve `onPress`; use `onClick` and `event.preventDefault()` to cancel their action. Root `onReset` can cancel before reset runs; `onResetCapture` is reserved for internal reset handling.
+
+Native forms with `action`/`method` use browser submission and bypass the controller's submit pipeline. Use that path only when the browser should own the request.
+
+## Implement a reusable custom control
+
+Use the same field integration as built-in inputs: `FieldBaseProps<Value>`, `useFieldProps`, then `wrapWithField`. Map the control's value/event API and forward the generated id, blur, disabled, read-only, and invalid state to the interactive element. Include `null | undefined` in the accepted model type when empty values are supported and normalize only for display. Do not spread controller props onto a DOM element.
+
+The [compiled CustomControl example](https://github.com/cube-js/cube-ui-kit/blob/main/typecheck/consumer/modern-form-examples.tsx) shows the complete pattern. The [component creation guide](https://cube-ui-kit.vercel.app/?path=/docs/getting-started-create-component--docs) explains the shared field wrapper. `Form.Item` / `Field` belongs to the legacy backend; it is not a second way to connect a modern custom input.
+
+For SSR, seed the controller with the same serializable defaults on server and client. Initial hydration uses the creation snapshot before subscribers catch up with client state. Each mounted creator owns its controller; no manual disposal is needed.

package/docs/modern-form-migration.md

@@ -23,7 +23,7 @@ The following API mapping describes migration choices; names are not mechanicall
 | `const [form] = Form.useForm()` | `const form = Form.useController<T>()` |
 | `form.isDirty` in JSX | `Form.useSelector(form, state => state.isDirty)` |
 | `getFieldValue(name)` / `getFieldsValue()` | Imperative `getValue(path)` / `getValues()` |
-| Read a value during render | `Form.useSelector` or `Form.Subscribe` |
+| Read a value during render | `Form.useValue(form, path)`; selectors / `Subscribe` for derived or inline UI |
 | `setFieldsValue(values)` | `setValues(values)`; review touch/notification/validation options |
 | `setInitialFieldsValue(values)` | `setDefaultValues(values)` to change the baseline; `adoptDefaultValues` to load data into eligible fields |
 | `resetFields()` | `reset()`; `reset({ values })` replaces baseline and current values |
@@ -31,108 +31,25 @@ The following API mapping describes migration choices; names are not mechanicall
 | `submit()` | `submit()` returns a tagged result such as `submitted`, `invalid`, or `failed` |
 | `Form.Item` wrapping a custom control | `useFieldProps` plus `wrapWithField` inside that control |
 
-`DialogForm` and Cloud's `NarrowForm` / `SaveableCard` currently expose legacy instance contracts. Keep their callers legacy until the wrapper itself is migrated and verified. Passing a modern controller through a cast does not migrate the wrapper. `Form.Item`, legacy mutable flags, and the legacy `Form.Context` instance shape remain compatibility APIs.
+`DialogForm` and Cloud's `NarrowForm` / `SaveableCard` currently expose legacy instance contracts. Keep their callers legacy until the wrapper itself is migrated and verified. Passing a modern controller through a cast does not migrate the wrapper. `Form.Item`, legacy mutable flags, and the legacy `FormContext` instance shape remain compatibility APIs.
 
-## Typed fields and focused reads
+## Review the behavior changes
 
-Prefer typed descriptors for new modern forms. `form.field(path, options)` is pure configuration: it does not read current values, register a field, or subscribe the owner. Inputs register after commit and infer their allowed value type from `FieldBaseProps<Value>`. A descriptor takes precedence over `form`/`name`; only options it supplies override matching input options. Put `rules` and `validate` together on the descriptor: supplying either replaces input-level `rules`, while a descriptor with neither preserves them. Keep presentation such as labels and `isRequired` on the input. Existing `name` bindings remain available for legacy-compatible controls.
+The [Modern Form guide](modern-form-guide.md) is the reference for implementing forms. Start there for [API choices](modern-form-guide.md#pick-one-binding-and-one-owner-for-each-concern), [reactive reads](modern-form-guide.md#read-a-value-show-status-or-reveal-a-section), [incoming data](modern-form-guide.md#load-server-data-refresh-defaults-or-discard-edits), [validation](modern-form-guide.md#validate-simple-rules-sibling-fields-or-an-api-response), and [submission](modern-form-guide.md#submit-display-server-errors-and-reset). The following differences need particular attention during migration:
 
-Typed built-in field bindings accept `null` and `undefined` alongside their normal model value, so nullable API responses can be used directly. Display normalization does not change the stored value: a switch displays `null` as unchecked and a text input displays it as empty, while the form retains `null` until an edit or explicit command changes it. Controls keep their existing change payloads (for example, switches emit booleans), and reset restores nullable defaults. Declare nullable fields in the model so validators and value selectors also include `null`.
-
-```tsx
-const form = Form.useController<Profile>({
-  defaultValues: initialProfile,
-  onSubmit: (values, { signal }) => save(accountId, values, signal),
-});
-
-<TextInput field={form.field(['profile', 'name'])} label="Name" />;
-<TextInput
-  field={form.field('email', {
-    deps: [organizationId],
-    validate: (value, { signal }) => checkEmail(organizationId, value, signal),
-  })}
-  label="Email"
-/>;
-```
-
-`validate(value, context)` infers the field value and checked paths in `context.getValue(path)`. Use `deps` for external inputs, compared by `Object.is`, and `dependsOn` for form paths that should trigger revalidation. Declare conditional reads too: `dependsOn: ['password']` reruns confirmation validation when the password changes, even if the previous run stopped at an empty confirmation. Each run reads one captured snapshot. Reads through `getValue`/`getValues` cancel in-flight work if those values change, but do not schedule another run; revalidation requires `dependsOn`. Declared dependency changes revalidate previously validated or validating fields unless a value command requests `validate: 'never'`. Rule/dependency changes preserve visible errors while the replacement run is pending. Equivalent inline functions do not restart validation. Function source detects replacements; use `deps` for captures and distinct functions with identical source (including bound/native functions).
-
-Use `Form.useValue(form, path)` for a reactive value and `Form.useFieldState(form, path)` for typed value/defaults, errors, status, dirty/touched, and active state. Both support nested tuples and subscribe only to their selection; place them in leaf components when the form owner should not rerender. State may be `undefined` before a field has registered. Plain objects and arrays have deeply readonly, potentially incomplete read types; use controller commands for writes. Platform values and date-control values (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`, and `Time`) retain their types and methods.
-
-## Subscribe where the UI reads state
-
-Creation does not subscribe the component. A selector subscribes its caller; a `Form.Subscribe` render function subscribes only that subtree. A colocated selector is valid when the whole creator should render on that selection. Otherwise place the selector in a child or use `Subscribe`.
-
-```tsx
-<Form.Subscribe form={form} selector={state => state.values.name}>
-  {name => <output>{name}</output>}
-</Form.Subscribe>
-```
-
-Selectors and equality functions must be pure. Select a primitive or a stable snapshot branch. A newly allocated object compares unequal with the default `Object.is`; supply `isEqual` when selecting several values into a fresh object. `Form.useControllerContext<T>()` gives a descendant the controller without subscribing it. The generic describes that root's values; it cannot verify an ancestor's type.
-
-A leaf component can get its controller from context without prop threading, while retaining checked paths and inferred values:
-
-```tsx
-function EmailPreview() {
-  const form = Form.useControllerContext<Profile>();
-  const email = Form.useValue(form, 'email');
-  return <output>{email}</output>;
-}
-```
-
-`getValue`, `getValues`, `getActiveValues`, `getFieldSnapshot`, and `getSnapshot` are imperative reads for handlers and effects. They do not make JSX reactive. `subscribe(listener)` supports imperative observers and returns an unsubscribe function. `batch(fn)` groups synchronous commands into one publication; it is not a rollback transaction, and the callback must not be async.
-
-Omitted `form` props use context. Explicit `form={undefined}` detaches an input. `Form.Subscribe` and `useControllerContext` require modern context; legacy roots and `FormScopeMask` mask it. An explicit modern controller can be used outside a root. Use only one owning root for each controller.
-
-## Retained data and active fields
-
-| View | Contents | Typical use |
-| --- | --- | --- |
-| `state.values` / `getValues()` | All retained values, including defaults for unmounted fields | Draft previews, autosave, restoring hidden sections |
-| `state.activeValues` / `getActiveValues()` | Values at registered field paths | The default validated submission payload |
-
-Hiding a field unregisters it immediately. Its value stays retained by default, so showing it again restores the draft. `preserve={false}` removes that value after cleanup; the default baseline remains, so reset can restore it. An intervening update or Strict Mode reconnection prevents stale cleanup from removing a live value. Removing an array path keeps other indices stable.
-
-`submit()` validates active fields and submits active values. Use `submit({ include: 'all' })` only when retained fields belong in the payload; validation still covers active fields only. Registering a parent object includes its complete object; register leaf paths instead when only selected children should be active. A form with no active fields is invalid. Dirty/touched metadata includes retained fields; validity considers active fields.
-
-Named UI Kit inputs accept literal string names. Prefer `field={form.field(path)}` for checked field names, inferred validator values, and nested tuple bindings. Controller commands accept the same paths. `'user.email'` is one literal key, while `['user', 'email']` addresses an object. Numeric array indices and numeric string segments address the same path. Known keys and tuples infer values; misspelled literal paths are rejected. Widened string/tuple paths remain dynamic; open `Record` models retain typed values. Declare an explicit model with `Form.useController<Model>()` when defaults omit fields or contain values narrower than the intended model. The declaration surface requires TypeScript 5.4 or newer.
-
-```tsx
-form.setValue('name', 'New name');
-form.setValue(['rows', 0, 'email'], 'person@example.com');
-// Static keys and tuple leaves reject values of the wrong type.
-```
-
-Snapshots own copies of plain objects and arrays. Public `FormValues<T>` / `FormReadValue<T>` types reflect readonly, potentially incomplete nested data. Treat dates, files, other non-plain objects, and error payloads as immutable. Defaults and values on the controller take precedence over field defaults, including explicit null and undefined. Reusing a mutated input object does not replace its previously captured snapshot; send a new object.
-
-## Load defaults without erasing edits
-
-Use `adoptDefaultValues(response, { when: 'untouched' })` for a response that may arrive after typing. It replaces the baseline and adopts values at eligible paths, preserving touched edits. `when: 'clean'` protects dirty fields, while `when: 'always'` deliberately replaces them. Abort or ignore obsolete requests; the complete `AsyncDefaults` example demonstrates both request cleanup and a stale-response guard.
-
-Use `setDefaultValues(response)` when only the baseline should change. `{ currentValues: 'replace' }` replaces current values too. `reset({ values: response })` replaces baseline and values and clears interaction, validation, and submission error state. Defaults commands replace the baseline object, so omitted keys are removed from it.
-
-Programmatic writes do not touch fields or invoke `onValuesChange` unless requested. User writes do both by default. Review `{ source, touch, notify, validate }` for each imperative write. `onValuesChange` receives retained values and metadata describing the changed paths/source/kind.
-
-## Validation, custom controls, and submission
-
-Built-in named inputs register after commit and select only their value, errors, and validation status. Custom controls call `useFieldProps`, map their event/value API, then give the resolved props to `wrapWithField`. Forward the generated id, blur, disabled, read-only, and invalid state to the actual control; do not spread a controller onto a DOM element. The `CustomControl` example is typechecked against the public API.
-
-For modern custom validators, return an error (including a ReactNode), or throw/reject it. Return undefined, null, or an empty string on success. A legacy validator that resolves a data object must be adapted: a modern validator treats that result as an error. Use `ModernValidationRule` to check authored modern rules strictly; shared input props remain permissive enough for existing legacy rules. Legacy forms keep their existing validator behavior.
-
-Validators receive `{ signal, name, getValue, getValues }` as the third argument. Pass the signal to network requests. Superseded work settles as stale even if the validator ignores cancellation. List external captured inputs in `deps` (for example, `deps: [organizationId, checkEmail]`). Use `dependsOn` for field-triggered revalidation; read tracking only cancels in-flight work. Rule constraints and function source are compared automatically. `rulesKey` opts into manual versioning and skips that comparison; update it when any rule changes. Prefer `deps` for ordinary captured inputs, including string IDs: strings in `deps` are values, while strings in `dependsOn` are field paths.
-
-`validationDelay` coalesces automatic validation; explicit validation and submission run immediately by default. Auto writes revalidate on-change fields and fields already showing errors. On-blur fields otherwise wait for blur. `errorPolicy` chooses first/all rule errors. Errors remain visible while revalidating and clear on nonvalidating edits.
-
-Root `onSubmit` receives the selected payload and an abort signal; `onSubmitFailed` receives `{ status: 'invalid', errors }` or `{ status: 'failed', error }`. Concurrent submits are ignored. Reset and owning-root release cancel pending submission. Submit start and reset clear `submitError`; ordinary edits keep it. `Form.Submit`, `Form.Reset`, and `Form.SubmitError` subscribe to the modern state. Native `action`/`method` forms continue browser navigation and bypass this pipeline.
-
-## Modern actions and errors
-
-`<Form submitValues="all">` includes retained values for native Enter and button submission; the default is `active`. Validation still targets active registrations. Explicit-controller Submit buttons target that controller even in an external footer or another DOM form, preserve native action forms, and submit once. Modern Submit stays enabled while validation errors are visible, so another submission can display feedback; opt into disabling with `disableOnInvalid`. Legacy Submit keeps its existing default. `state.canReset` enables Reset when edits, touched/validation state, or submit errors can be cleared, and is false during submission. Both buttons preserve `onPress`; use `onClick` with `event.preventDefault()` to cancel the action. A controller root's `onReset` runs before reset and can cancel with `preventDefault()`. Reset interception also prevents nested controls from restoring their own mount-time defaults, including when reset is cancelled; `onResetCapture` is reserved for this interception. Native `action` forms retain browser reset behavior.
-
-Root business callbacks override hook callbacks while mounted. Omitted or undefined root callbacks restore the latest committed hook callback. Changing defaults remains an explicit command. Unmounting the owning root cancels pending submission.
-
-`onSubmitFailed` receives `{ status: 'invalid', errors }` for validation failures and `{ status: 'failed', error }` for submission exceptions. `<Form.SubmitError form={form} renderError={error => ...} />` supports external placement and application-specific formatting. Omit `renderError` for the existing safe generic fallback.
+| Area | Migration decision |
+| --- | --- |
+| Field bindings and paths | Prefer `field={form.field(path, options)}`. Strings are literal keys; convert legacy dot notation to tuples for nested data. Do not configure the same binding through `field`, `name`, and `form`. |
+| Empty API values | Include `null` in the model where the API returns it. Built-in typed bindings display an empty state without rewriting the stored null. |
+| Render-time reads | Use `useValue`, `useFieldState`, or selectors. Imperative getters and the controller creator do not subscribe React. |
+| Late defaults | Defaults initialize once. Choose adoption to preserve edits, reset for a new editing session, or baseline-only updates deliberately. |
+| Programmatic writes | `setValue` / `setValues` do not touch or invoke `onValuesChange` by default. Review `source`, `touch`, `notify`, and `validate` options. |
+| Validator result | `undefined`, `null`, and an empty string succeed. Return an error or throw/reject to fail. Adapt validators that resolve a data object. |
+| Validator dependencies | `deps` contains external captures; `dependsOn` contains form paths for revalidation. Reads only cancel stale in-flight work. Ordinary validators do not need `rulesKey`. |
+| Hidden fields and payload | Unmounted fields retain drafts by default but leave the default active submission payload. `submitValues="all"` includes retained values and still validates only active fields. |
+| Actions | Modern Submit remains enabled after errors by default. Opt into `disableOnInvalid` if required. Reset follows `state.canReset`, which includes touched/validation/error state. |
+| Errors and cancellation | `onSubmitFailed` distinguishes `invalid` from `failed`. Reset and root unmount cancel submission; ordinary edits retain submit errors. |
+| Custom controls | Use `useFieldProps` and `wrapWithField`; `Form.Item` remains legacy-only. |
 
 ## Per-form migration checklist
 
@@ -142,7 +59,7 @@ Root business callbacks override hook callbacks while mounted. Omitted or undefi
 4. Replace render-time getters and flags with narrow selectors or `Subscribe`. Update custom controls through `useFieldProps`.
 5. Adapt validators' success values and cancellation. Declare external captured inputs in `deps` and sibling form paths in `dependsOn`.
 6. Decide whether hidden fields are retained and whether submission uses active or all values. Verify the actual payload with conditional sections both visible and hidden.
-7. Test required/async errors, double submit, server failure, reset, unmount during requests, keyboard focus, and navigation guards. Confirm unaffected fields and the creator do not rerender on each keystroke.
+7. Test required/async errors, double submit, server failure, reset, unmount during requests, keyboard focus, and navigation guards. Modern Submit stays enabled after validation errors; pass `disableOnInvalid` to retain the legacy disabled-button behavior. Verify this visible change with QA. Confirm unaffected fields and the creator do not rerender on each keystroke.
 8. Run source and built-consumer type checks, the frozen legacy contract suite, React 18/19 compiler checks, and relevant browser checks. Review visual changes before merging.
 
 To revert a migrated form, render the preserved legacy component again and restore its legacy defaults/callback/validator contracts. Remount the boundary and deliberately transfer serializable draft values if needed. Do not cast the modern controller to a legacy instance or toggle hook implementations in place.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.0.0-canary-c2f337e",
+  "version": "0.0.0-canary-36c17b9",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {