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

package/docs/FieldProperties.md

@@ -4,6 +4,8 @@ All input components in UI Kit (`TextInput`, `Select`, `ComboBox`, `Checkbox`, `
 
 When used inside a [Form](./components/form/Form.md), these properties are automatically inherited from the form context and can be overridden at the field level.
 
+For modern forms, follow the [use-case guide](./components/form/ModernForm.md). Put binding and validation options on `form.field(path, options)` and presentation props on the input. The prop reference below also covers `name` bindings for shared controls and legacy forms; these are alternatives to the typed descriptor, not additional required setup.
+
 ## Identity & Form Integration
 
 - **`field`** `FormField<Value>` — Typed modern binding created by `form.field(path, options)`. Supports nested paths and takes precedence over `form` and `name`. Built-in bindings accept `null` and `undefined` alongside their normal model value; display fallbacks do not replace stored nulls.
@@ -72,7 +74,7 @@ When used inside a [Form](./components/form/Form.md), these properties are autom
 - **`validationDelay`** `number` — Debounce delay in milliseconds before running validation.
 - **`deps`** `readonly unknown[]` — Modern validator inputs captured from outside the form. Compared with `Object.is`; changes invalidate prior validation.
 - **`dependsOn`** `readonly FormPath[]` — Modern form paths that trigger revalidation, including conditional reads. Validator reads only cancel in-flight work.
-- **`rulesKey`** `string` — Manual modern rules revision. Skips automatic rule comparison; update when any rule changes.
+- **`rulesKey`** `string` — Manual modern function revision. Skips validator/transform source comparison; declarative constraints are always compared. Update it when a function or its captures change.
 - **`errorPolicy`** `'first' | 'all'` — Modern rule error collection policy, inherited from the controller by default.
 - **`showValid`** `boolean` — Whether to show the valid state icon after successful validation.
 - **`errorMessage`** `ReactNode` — Error message always displayed in danger state, regardless of validation state.
@@ -94,38 +96,40 @@ The `rules` prop accepts an array of rule objects. Built-in validators include:
 - **`enum`** `any[]` — Value must be one of the allowed values.
 - **`whitespace`** `boolean` — Value must contain non-whitespace characters.
 - **`message`** `string` — Custom error message for the rule.
-- **`validator`** `(rule, value) => Promise<string | void>` — Custom async validation function.
+- **`validator`** `(rule, value, context) => result` — Custom rule function. In modern forms, return an error or throw/reject to fail; `undefined`, `null`, and an empty string succeed. The context provides `signal`, `name`, `getValue`, and `getValues`. Prefer descriptor `validate(value, context)` for an ordinary custom check with an inferred value type. Legacy validators retain their existing contract.
 
-```jsx
+```tsx
 <TextInput
-  name="email"
+  field={form.field('email', {
+    rules: [{ type: 'email', message: 'Enter a valid email' }],
+  })}
   label="Email Address"
   isRequired
-  rules={[
-    { required: true, message: 'Email is required' },
-    { type: 'email', message: 'Enter a valid email' },
-  ]}
 />
 ```
 
 ## Usage Example
 
-```jsx
+```tsx
 import { Form, TextInput, Select } from '@cube-dev/ui-kit';
 
 function ExampleForm() {
+  const form = Form.useController<{
+    name: string;
+    role: 'admin' | 'member' | null;
+  }>({ defaultValues: { name: '', role: null } });
+
   return (
-    <Form defaultValues={{ name: '', role: undefined }}>
+    <Form form={form}>
       <TextInput
-        name="name"
+        field={form.field('name', { rules: [{ min: 2 }] })}
         label="Full Name"
         description="As it appears on your ID"
         isRequired
-        rules={[{ required: true, min: 2 }]}
       />
 
       <Select
-        name="role"
+        field={form.field('role')}
         label="Role"
         tooltip="Your primary role in the organization"
         necessityIndicator="label"

package/docs/Usage.md

@@ -456,46 +456,30 @@ DataTable also accepts nested column definitions for already-shaped pivot result
 
 ## Form System
 
-### Form Component
+### Modern forms
 
-`<Form>` wraps a native `<form>` and provides validation context:
+For a new modern form, create a typed controller, put defaults on the controller, and bind inputs with descriptors:
 
-```jsx
-const [form] = useForm();
-
-<Form form={form} onSubmit={(data) => save(data)}>
-  <TextInput name="email" label="Email" rules={[{ required: true }, { type: 'email' }]} />
-  <SubmitButton>Save</SubmitButton>
+```tsx
+const form = Form.useController<{ email: string | null }>({
+  defaultValues: { email: null },
+});
+
+<Form form={form} onSubmit={(values, { signal }) => save(values, signal)}>
+  <TextInput field={form.field('email')} label="Email" isRequired />
+  <Form.SubmitError />
+  <Form.Submit>Save</Form.Submit>
 </Form>
 ```
 
-### useForm Hook
-
-`Form.useController()` is the explicit modern alternative. Its creator does not subscribe; use `Form.useSelector(controller, selector, { isEqual })` or `<Form.Subscribe>` for reactive reads, and `Form.useControllerContext()` for descendant access. Named UI Kit inputs bind to modern controllers through commit-time registration and per-field subscriptions. Custom controls use `useFieldProps`; `Form.Item` remains legacy-only. Modern rules support cancellation, delayed validation, and ReactNode errors. Root callbacks and `Form.Submit`, `Form.Reset`, and `Form.SubmitError` use the modern pipeline; native action forms keep browser submission. Known keys and nested tuple commands infer their value types; dynamic paths stay supported. See the [Form documentation](./components/form/Form.md) for scope, defaults, and SSR contracts, and the [migration checklist](https://github.com/cube-js/cube-ui-kit/blob/main/docs/modern-form-migration.md) before converting an existing form.
+Inputs subscribe to their own values and errors. For other reactive UI, use `Form.useValue(form, path)` for one value, `Form.useFieldState(form, path)` for field metadata, or a selector for derived state. `<Form.Subscribe>` keeps an inline region's subscription separate from its parent. Keep imperative getters in handlers and effects.
 
-For new modern forms, prefer `<TextInput field={form.field('email', { validate, deps })} />`; descriptors check names and value types and support nested tuple paths. Built-in bindings accept nullable model values without replacing stored `null` with display fallbacks; declare `null` in the model when it can come from the API. `Form.useValue(form, path)` and `Form.useFieldState(form, path)` provide narrow reactive reads; date-control values retain their methods and types. Hook callbacks stay fresh after commit; defaults change through explicit commands. Declare sibling validation dependencies with `dependsOn` and external captures with `deps`; reads only cancel stale in-flight work. Modern Submit stays enabled after validation errors by default. Both action buttons honor `onClick` cancellation; `state.canReset` exposes reset availability. Submission failures are discriminated by `status`, and explicit-controller action/error helpers work in external footers. `<Form submitValues="all">` includes retained values while continuing to validate active fields.
+[Modern Form](./components/form/ModernForm.md) explains which API to choose for server data, nullable values, nested fields, conditional sections, cross-field and remote validation, errors, and external actions. Use that guide for implementation recipes and the [migration checklist](https://github.com/cube-js/cube-ui-kit/blob/main/docs/modern-form-migration.md) when converting an existing form.
 
-Returns a `CubeFormInstance` with:
+### Legacy forms
 
-- **Get/Set:** `getFieldValue`, `setFieldValue`, `getFieldsValue`, `setFieldsValue`, `getFormData`
-- **Validation:** `validateField`, `validateFields`, `resetFieldsValidation`
-- **State queries:** `isFieldValid`, `isFieldInvalid`, `isFieldTouched`, `isValid`, `isDirty`
-- **Errors:** `getFieldError`, `setFieldError`
-
-### Validation Rules
-
-Async rule-based system. Each rule is an object with one of these properties:
-
-| Rule | Description |
-| --- | --- |
-| `required` | Field must have a value |
-| `type` | Type check: `email`, `url`, `number`, `integer`, `date`, `hex`, etc. |
-| `pattern` | Regex pattern match |
-| `min` / `max` | Length or value constraints |
-| `enum` | List of allowed values |
-| `whitespace` | Must contain non-whitespace content |
-| `validator` | Custom async function: `(rule, value) => Promise<void>` |
+`Form.useForm()` and roots without a modern controller keep the legacy backend. `DialogForm` and `Form.Item` still use this contract. See [Form](./components/form/Form.md) and [FormInstance](./components/form/FormInstance.md) for legacy instance methods, defaults, and dot notation.
 
-### Field Integration
+### Shared field integration
 
-Fields with a `name` prop inside `<Form>` automatically register with the form instance — no `<Field>` wrapper needed. The `useFieldProps` hook handles this internally.
+Built-in inputs have field support; they do not need a `Field` wrapper. Modern descriptors and legacy `name` bindings both connect through `useFieldProps`. Custom controls use that hook and `wrapWithField`. [Field Properties](./FieldProperties.md) documents shared labels, validation, state, and presentation props.

package/docs/components/form/Field.md

@@ -1,12 +1,12 @@
 # Field
 
-The Field component is a **legacy wrapper** for form inputs that provides field-specific styling and behavior. **In modern usage, all input components have built-in field support**, so you should pass field properties directly to input components instead of using the Field wrapper.
+The Field component is a **legacy wrapper** for form inputs that provides field-specific styling and behavior. Built-in input components already provide field support on both backends, so pass field properties directly to them. For custom controls in a modern controller form, use `useFieldProps` and `wrapWithField` as described in [Modern Form](./ModernForm.md#implement-a-reusable-custom-control); `Field` / `Form.Item` does not support that backend.
 
 ## When to Use
 
 - **❌ Don't use** for regular input components (TextInput, Select, etc.) - they have built-in field support
 - **✅ Use only** when wrapping read-only content to make it appear as a form field
-- **✅ Use only** when wrapping custom components that don't have built-in field support
+- **✅ Use only** when wrapping custom components in legacy forms that don't have built-in field support
 
 ## Component
 

package/docs/components/form/Form.md

@@ -2,89 +2,29 @@
 
 Forms allow users to enter data that can be submitted while providing alignment and styling for form fields. The Form component provides structure, validation, and state management for user input through a collection of input components with built-in field support.
 
-The form system is inspired by AntD Forms and [rc-field-form](https://field-form-react-component.vercel.app/) with a similar API.
+## Choose the form API
 
-## Modern controller and subscriptions (migration preview)
-
-The [per-form migration guide](https://github.com/cube-js/cube-ui-kit/blob/main/docs/modern-form-migration.md) covers backend selection, rollback, active versus retained values, async defaults, and custom controls. Its [public API examples](https://github.com/cube-js/cube-ui-kit/blob/main/typecheck/consumer/modern-form-examples.tsx) compile against the built package declarations. Existing legacy forms need no API changes when upgrading.
-
-`Form.useForm()` and forms without an explicit modern controller continue to use the legacy backend described below. `Form.useController<T>()` creates a stable modern controller with immutable snapshots. Defaults and store policy are captured once. Business callbacks update after every committed render without resetting values. Use `reset({ values })`, `setDefaultValues()`, or `adoptDefaultValues()` for later data.
+For new modern forms, follow [Modern Form](./ModernForm.md): typed bindings, loading server data, conditional sections, validation, subscriptions, and submission. The guide recommends one starting point for each case and explains when the alternatives are useful.
 
 ```tsx
-function AmountPreview() {
-  const form = Form.useController({ defaultValues: { amount: 10 } });
+function EmailForm() {
+  const form = Form.useController<{ email: string | null }>({
+    defaultValues: { email: null },
+  });
 
   return (
-    <Form form={form}>
-      <NumberInput name="amount" label="Amount" />
-      <button type="button" onClick={() => form.setValue('amount', 20)}>
-        Set amount
-      </button>
-      <Form.Subscribe selector={(state) => state.values.amount}>
-        {(amount) => <output>{String(amount)}</output>}
-      </Form.Subscribe>
+    <Form form={form} onSubmit={(values, { signal }) => save(values, signal)}>
+      <TextInput field={form.field('email')} label="Email" isRequired />
+      <Form.SubmitError />
+      <Form.Submit>Save</Form.Submit>
     </Form>
   );
 }
 ```
 
-The creator does not subscribe its owner. `Form.useSelector(form, selector, { isEqual })` subscribes the calling component; `Form.Subscribe` subscribes only its render-prop subtree. Equality defaults to `Object.is`. Selectors and equality functions must be pure. Use an `isEqual` function when returning a fresh object and equivalent results should retain their identity. Controller, selector, and equality changes are supported without stale subscriptions.
-
-`Form.Subscribe` accepts `form`, `selector`, optional `isEqual`, and a `children(selected)` render function. Omit `form` to use the surrounding modern root; an explicit controller takes precedence, while explicit `form={undefined}` detaches and reports a missing-controller error. `Form.useControllerContext<T>()` reads a modern root explicitly. These context APIs reject legacy roots, missing roots, and `FormScopeMask`; an explicit modern controller can still be used outside a root.
-
-Use selectors for render-time state. `getValue`, `getValues`, `getActiveValues`, `getFieldSnapshot`, and `getSnapshot` are imperative reads; `subscribe` supports imperative observers. `values` contains retained data and `activeValues` contains registered fields. Commands include `setValue`, `setValues`, `batch`, `touch`, the defaults/reset commands, and explicit field/submit error setters. String paths are literal names; tuples such as `['rows', 0, 'amount']` address nested data. `setValue` accepts `{ source, touch, notify, validate }`; programmatic changes do not touch or notify `onValuesChange` unless requested, while user changes do both by default. The committed `onValuesChange(values, change)` callback receives retained values and `{ names, source, kind }`.
-
-Named UI Kit inputs bind to the modern controller automatically; `<TextInput name="email" form={form} />` also works outside a root. Inputs subscribe only to their own value, errors, and validation status. Custom controls use `useFieldProps` and `wrapWithField`; `Form.Item` stays legacy-only. Controller values and defaults win over field defaults, including explicit `undefined` and `null`. Duplicate fields share a value but receive unique accessible ids. Groups register once and keep their options detached.
-
-`getValue` and `setValue` infer value types for known literal keys, nested tuples, and array indices without enumerating every path in the model. Misspelled literal paths are rejected; widened dynamic paths remain supported; strings containing dots remain literal keys. Use an explicit `Form.useController<Model>()` model when defaults are partial or narrower than the intended values. `FormValueAtPath<Model, Path>` exports the same lookup type. The modern declaration surface requires TypeScript 5.4 or newer.
-
-Removing a field removes it from `activeValues` immediately and retains its value by default. Use `preserve={false}` to remove its retained value after cleanup; the baseline remains available to reset. Changing a name or controller releases the old registration. Explicit `form={undefined}` detaches an input. `Form.Submit`, `Form.Reset`, and `Form.SubmitError` subscribe to modern state. Modern roots reject `defaultValues`; seed the creator or use a defaults command. Legacy wrappers such as `DialogForm` keep legacy-only types.
-
-### Typed fields and focused reads
-
-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.
-
-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. Descendants can get a typed controller with `Form.useControllerContext<Model>()` instead of receiving a prop. 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.
-
-### 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. Use one owning root per controller; duplicate roots report a development error and the newest binding wins.
-
-`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.
-
-### Modern validation and submission
-
-Use `rules`, `isRequired`, `validateTrigger`, and `validationDelay` on named inputs. Modern validators receive `(rule, value, { name, signal, getValue, getValues })` and return an error message (including a ReactNode), or throw/reject; `undefined`, `null`, and an empty string mean success. The abort signal lets a validator cancel its own network work. Superseded validation settles with `stale: true` even if a validator ignores the signal, and late results cannot replace current errors.
-
-`form.validate()` validates active fields immediately; `form.validate(['email'])` selects literal names and `form.validate([['users', 0, 'email']])` selects a nested path. `{ immediate: false }` honors field delays. `form.blur(name)` touches the field and runs an on-blur rule. No-rule fields become valid synchronously. The form is valid only when at least one field is active and every active field is valid. Existing errors stay visible during revalidation; an edit that does not revalidate clears them. `setValue` and `setValues` accept `validate: 'auto' | 'always' | 'never'`: auto revalidates on-change fields or fields showing errors. Once an on-blur field becomes valid, subsequent edits await its next blur.
-
-`errorPolicy: 'first' | 'all'` controls rule-order errors (default `first`), on the creator or individual field. Equivalent inline rules do not restart validation: primitive constraints, RegExp source/flags, and function source form the signature; messages and function identity do not. Use `deps` for external captured inputs. `rulesKey` opts into manual versioning, skipping automatic rule comparison; update it when any rule changes. The latest updated duplicate registration owns its rules and trigger.
-
-`form.submit()` validates and submits `activeValues`; `form.submit({ include: 'all' })` includes retained values deliberately. `onSubmit(values, { include, signal })` may return a promise. Concurrent submissions return `{ status: 'ignored', reason: 'submitting' }`; other results are `submitted`, `invalid` with an error map, `failed` with an error, or `stale` after cancellation. Validation failures call `onSubmitFailed({ status: 'invalid', errors })` without setting `submitError`; submission failures call it with `{ status: 'failed', error }` and set the error. Submit start and reset clear `submitError`; ordinary edits keep it. Explicit error commands remain available. A modern root without `action` prevents navigation and routes submission to the controller. A native `action`/`method` form preserves browser submission and bypasses the controller pipeline.
+`Form.useForm()` and roots without a modern controller keep the legacy backend. Existing forms need no API changes when upgrading. Use the [migration checklist](https://github.com/cube-js/cube-ui-kit/blob/main/docs/modern-form-migration.md) before converting one; `DialogForm` and `Form.Item` still require legacy forms.
 
-For SSR, seed the controller with the same serializable `defaultValues` on server and client. Server rendering and initial hydration select the cached creation snapshot; after hydration, subscribers catch up to current client state. Prepare server data before creating the controller. Each mount owns a separate controller, and subscriptions clean up on unmount; Strict Mode effect replay does not dispose live controllers.
+**The reference and examples below describe the legacy backend.** Its instance methods, root `defaultValues`, and dot-separated paths do not apply to modern controllers. Shared layout and field presentation props work with both backends. See [Modern Form](./ModernForm.md) for modern defaults and commands.
 
 ## When to Use
 

package/docs/components/form/FormInstance.md

@@ -1,4 +1,6 @@
-# FormInstance
+# FormInstance (legacy)
+
+This page describes `Form.useForm()` and `CubeFormInstance`. New modern forms use `Form.useController<Model>()`; see [Modern Form](./ModernForm.md) for its commands and recipes. The methods and dot notation below are legacy-only.
 
 The `CubeFormInstance` is the core form management class that provides programmatic control over form state, validation, and data handling. It serves as the central API for interacting with form fields, managing validation states, and handling form submission workflows.
 
@@ -16,13 +18,7 @@ function MyComponent() {
 }
 ```
 
-Alternatively, you can create an instance directly:
-
-```tsx
-import { CubeFormInstance } from '@cube-dev/ui-kit';
-
-const formInstance = new CubeFormInstance();
-```
+`CubeFormInstance` is exported as a type for wrapper props and references. Use the hook to create a React form; the package does not export its constructor as a runtime API.
 
 ## Field Management
 
@@ -295,7 +291,7 @@ type CubeFieldData<Name extends string, Value> = {
 
 ## Best Practices
 
-1. **Always use the `useForm` hook** in React components rather than creating instances manually
+1. **For legacy forms, use the `useForm` hook** in React components rather than creating instances manually
 2. **Handle async validation errors** appropriately using try-catch blocks
 3. **Set initial values early** in the component lifecycle to avoid field state inconsistencies
 4. **Use dot notation** for nested object structures instead of managing complex object hierarchies manually

package/docs/components/form/ModernForm.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.