@cube-dev/ui-kit 0.180.0 → 0.182.0

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.182.0 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.182.0 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";
 

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.182.0 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.182.0 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.182.0 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.182.0 | Cube Dev Team */
 import { isDevEnvOrTest } from "./is-dev-env.js";
 
 //#region src/utils/warnings.ts

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.182.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.180.0";
+const VERSION = "0.182.0";
 const TASTY_VERSION = "3.9.2";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/CreateComponent.md

@@ -15,7 +15,7 @@ Creating a component involves several optional but recommended elements:
 
 Everything is optional - you can create simplified components without all features, but exported UI Kit components should be feature-rich and consistent.
 
-Form-aware inputs use `useFieldProps` for both legacy instances and modern controllers. Map the control’s value API with `valuePropsMapper` and pass the resolved props to `wrapWithField`. The hook owns modern registration after commit, narrow subscriptions, cleanup, and unique accessible ids. Do not register during render, call the legacy adapter directly, or wrap a modern control in `Form.Item`. Modern validation options (`rules`, `rulesKey`, `validationDelay`, `validateTrigger`, `errorPolicy`) flow through the same hook. Validators receive an AbortSignal and return or reject with a message; use `rulesKey` for changed closure dependencies. See [Form](./components/form/Form.md) for the integration contract.
+Form-aware inputs use `useFieldProps` for both legacy instances and modern controllers. Map the control’s value API with `valuePropsMapper` and pass the resolved props to `wrapWithField`. The hook owns modern registration after commit, narrow subscriptions, cleanup, and unique accessible ids. Do not register during render, call the legacy adapter directly, or wrap a modern control in `Form.Item`. Modern validation options (`rules`, `deps`, `dependsOn`, `rulesKey`, `validationDelay`, `validateTrigger`, `errorPolicy`) flow through the same hook. Validators receive an AbortSignal and return or reject with a message; use `deps` for external closure inputs and `dependsOn` for form paths that trigger revalidation. `rulesKey` explicitly versions functions and skips source comparison while declarative constraints remain reactive. Extend `FieldBaseProps<Value>` to constrain typed modern descriptors to accepted model values, including `null | undefined` when supported even if change callbacks emit only non-null values; `useFieldProps` resolves descriptors and strips them before DOM forwarding. Descriptor options override only the input options they explicitly supply; put custom validation and structural rules together on the descriptor. See [Form](./components/form/Form.md) for the integration contract.
 
 The [compiled custom-control example](https://github.com/cube-js/cube-ui-kit/blob/main/typecheck/consumer/modern-form-examples.tsx) shows explicit DOM forwarding, async validation, and default adoption. Shared input rule props accept existing legacy validators; use `ModernValidationRule` for strict modern success/error return types, and adapt legacy validators that resolve data before migrating them.
 

package/docs/FieldProperties.md

@@ -4,11 +4,16 @@ 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). Bind with `name` and put validation options on the input, or choose `field={form.field(path, options)}` for model-aware type checking and validator inference. Keep presentation props on the input. These binding styles are alternatives; descriptors are not required for nested data.
+
 ## Identity & Form Integration
 
-- **`name`** `string` — Field name for form data binding. Required when used within a Form.
-- **`form`** `CubeFormInstance` — Form instance. Automatically provided when inside a Form context. Pass it explicitly to link an input to a form it is not nested in, or to override the surrounding form.
-- **`defaultValue`** `any` — Default value for the field in uncontrolled mode.
+- **`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.
+- **`name`** `string | readonly (string | number)[]` — Field name when a descriptor is not supplied. Modern forms accept literal strings or nested tuple paths, such as `['users', 0, 'email']`. Legacy forms accept strings only and retain dot notation.
+- **`form`** `CubeFormInstance | FormController<T>` — Legacy instance or modern controller. Automatically provided when inside a Form context. Pass it explicitly to link an input to a form it is not nested in, or to override the surrounding form.
+- **`defaultValue`** `any` — Initial field value. Modern controller values/defaults take precedence, including explicit `null` and `undefined`.
+- **`preserve`** `boolean` (modern default: `true`) — Retain the value after the last input for this field unmounts.
+- **`isEqual`** `(previous, next) => boolean` — Modern field dirty-value comparator.
 - **`id`** `string` — Unique ID for the field element.
 - **`idPrefix`** `string` — ID prefix to avoid collisions between multiple forms.
 
@@ -67,6 +72,10 @@ When used inside a [Form](./components/form/Form.md), these properties are autom
 - **`rules`** `ValidationRule[]` — Array of validation rules for the field.
 - **`validateTrigger`** `'onBlur' | 'onChange' | 'onSubmit'` — When to trigger validation.
 - **`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 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.
 - **`message`** `ReactNode` — _(deprecated)_ Use `errorMessage` for errors and `description` for help text.
@@ -87,34 +96,37 @@ 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"
+        rules={[{ min: 2 }]}
         label="Full Name"
         description="As it appears on your ID"
         isRequired
-        rules={[{ required: true, min: 2 }]}
       />
 
       <Select

package/docs/Usage.md

@@ -456,44 +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 `name`. Modern names accept strings and nested tuples; `field` is an optional typed binding:
 
-```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 name="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.
 
-Returns a `CubeFormInstance` with:
+[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.
 
-- **Get/Set:** `getFieldValue`, `setFieldValue`, `getFieldsValue`, `setFieldsValue`, `getFormData`
-- **Validation:** `validateField`, `validateFields`, `resetFieldsValidation`
-- **State queries:** `isFieldValid`, `isFieldInvalid`, `isFieldTouched`, `isValid`, `isDirty`
-- **Errors:** `getFieldError`, `setFieldError`
+### Legacy forms
 
-### 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 `name` and `field` bindings, and legacy string `name` bindings, 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/actions/Button.md

@@ -227,7 +227,7 @@ A disabled button keeps showing its tooltip. Browsers stop dispatching mouse eve
 ### ARIA Properties
 
 - `aria-label`, `aria-labelledby` – Accessible name.
-- `aria-pressed` – Managed automatically when `isSelected` is used.
+- `aria-pressed` – Derived from `isSelected`. Not emitted when the button renders as a link (`to`) or when the call site sets its own `role` — a button acting as a tab or an option wants `aria-selected` / `aria-current` instead. An explicit `aria-pressed` always wins.
 - `aria-disabled` – Announces the disabled state whenever the native `disabled` attribute cannot be used: on links, and on buttons that carry a tooltip.
 - Additional ARIA attributes supported by React Aria's `useButton`.
 

package/docs/components/content/Item.md

@@ -70,6 +70,25 @@ These properties allow direct style application without using the `styles` prop:
 - **Color:** `color`, `fill`, `fade`, `image`
 - **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
+### Spacing Tokens
+
+`Item` lays its slots out on a grid with no gap, and `Label` drops its own inline padding whenever there is start or end content. A `prefix` or `suffix` therefore renders flush against the label by default, which is what most content wants — a checkbox, a kbd chip, a badge and a count are all boxes that already carry their own presence, and a gap on top of one reads as too much.
+
+A **bare glyph** is the case that needs spacing: it sits flush, while the same glyph in the `icon` slot looks spaced because that slot centres it inside a `$size`-wide square. Two tokens control it, both `0` by default:
+
+| Token         | Controls                                        |
+| ------------- | ----------------------------------------------- |
+| `$prefix-gap` | Space between the `Prefix` slot and the `Label` |
+| `$suffix-gap` | Space between the `Label` and the `Suffix` slot |
+
+```jsx
+<Item styles={{ '$prefix-gap': '1x' }} prefix={<MemberIcon />}>
+  Revenue
+</Item>
+```
+
+Set them on the item rather than overriding `Prefix` / `Suffix` padding directly — those slots carry state maps that drop the outer gutter next to an icon or an actions run, and a flat `padding` override silently replaces them.
+
 ### Modifiers
 
 The `mods` property accepts the following modifiers:

package/docs/components/fields/CommandTextArea.md

@@ -25,7 +25,9 @@ Choose a different component when the interaction has another outcome:
 - **`items`** `Iterable<T>` — Data-driven option source (alternative to JSX children).
 - **`children`** `ReactNode | ((item) => ReactElement)` — Static items or a render function (same shape as `ComboBox` / `ListBox`).
 - **`filter`** `(textValue, query) => boolean | false` — Custom filter. Pass `false` to disable internal filtering (e.g. server-side).
-- **`onCommand`** `(key, item) => void` — Fired when the user picks a command. The option's `textValue` is inserted into the textarea regardless.
+- **`onCommand`** `(key, item) => void` — Fired when the user picks a command. The option's `textValue` is inserted into the textarea regardless. `item.start` / `item.end` locate the insertion in the value passed to `onChange`, so a consumer can anchor its own record to the pick instead of searching the new value for the inserted text.
+- **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the suggestion popover opens or closes. Use it when the field needs its own `Enter` behaviour: `onKeyDown` runs before the component's own handling, so this is how you tell "pick the focused option" from "submit".
+- **`onActiveTokenChange`** `(token: ActiveToken | null) => void` — Fired when the active trigger token changes, with the component's own caret-aware scan result. `null` once the caret leaves a token.
 - **`insertSpaceAfter`** `boolean` (default: `true`) — Insert a trailing space after the chosen command.
 - **`disabledKeys`** `Iterable<Key>` — Keys of disabled options.
 - **`direction`** `'top' | 'bottom'` (default: `'top'`) — Popover placement. Chat inputs usually want `top`.

package/docs/components/fields/FileInput.md

@@ -87,6 +87,10 @@ The `mods` property accepts the following modifiers you can override:
 />
 ```
 
+### Form Values and Resets
+
+When bound to a legacy or modern form, resetting updates the displayed filename and clears any obsolete native file selection. This also allows choosing the same file again. A nonempty string value can display a filename, but it cannot restore file bytes; the user must select the file again. With `type="text"`, the form stores the file's text content.
+
 ### With Validation
 
 Pass `isValid` or `isInvalid` to tint the border and show the matching state icon.

package/docs/components/fields/FilterPicker.md

@@ -31,6 +31,7 @@ Choose a different component when the interaction has another shape:
 - **`selectionMode`** `'single' | 'multiple'` (default: `single`) — Selection mode for the picker
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether to allow entering custom values that are not present in the predefined options
 - **`isClearable`** `boolean` (default: `false`) — Whether the filter picker is clearable using a clear button in the rightIcon slot
+- **`clearLabel`** `string` — Accessible name for the built-in clear button. Defaults to a localized "Clear value".
 - **`isLoadingItems`** `boolean` (default: `false`) — Whether items are currently loading. Shows a loading spinner in the search input suffix inside the popover. Unlike `isLoading`, does not disable the trigger.
 - **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection. In single selection mode, re-selecting the current item becomes a no-op: `onSelectionChange` is not fired and the popover closes
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items

package/docs/components/fields/Picker.md

@@ -48,6 +48,7 @@ Choose a different component when the interaction has another shape:
 - **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection. In single selection mode, re-selecting the current item becomes a no-op: `onSelectionChange` is not fired and the popover closes
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`isClearable`** `boolean` (default: `false`) — Whether the picker shows a clear button when a selection is made
+- **`clearLabel`** `string` — Accessible name for the built-in clear button. Defaults to a localized "Clear value".
 - **`onClear`** `() => void` — Callback called when the clear button is pressed
 - **`actions`** `ReactNode` — Custom actions rendered inside the trigger, to the left of the built-in clear button and dropdown caret
 - **`sortSelectedToTop`** `boolean` — Sort selected items to the top when the popover opens (only works with `items` prop)

package/docs/components/fields/Select.md

@@ -38,6 +38,7 @@ Choose a different component when the interaction has another shape:
 - **`size`** `string` (default: `medium`) — Size of the select component
 - **`direction`** `string` (default: `bottom`) — Preferred direction for the dropdown menu
 - **`isClearable`** `boolean` (default: `false`) — Whether the select is clearable using a clear button in the rightIcon slot
+- **`clearLabel`** `string` — Accessible name for the built-in clear button. Defaults to a localized "Clear value".
 - **`actions`** `ReactNode` — Custom actions rendered inside the trigger, to the left of the built-in clear button and dropdown caret
 - **`shouldFlip`** `boolean` (default: `true`) — Whether dropdown should flip to fit in viewport
 - **`overlayOffset`** `number` (default: `8`) — Distance between select and dropdown in pixels

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,57 +2,31 @@
 
 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. Its initial options are captured once: changing `defaultValues` or callbacks in a later options object does not reconfigure it. 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 name="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 creation-time `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. Unknown or dynamic paths use `unknown`; 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.
-
-### 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 rule values, RegExp source/flags, and function source text form the signature; messages do not. Supply a changing `rulesKey` when a validator captures a dependency that changes without changing its source text. The latest updated duplicate registration owns its rules and trigger.
-
-`<Form onSubmit={save} onSubmitFailed={report} onValuesChange={changed}>` binds the current callbacks after commit. A callback changed to `undefined` falls back to the creator's initial callback. Unmount releases only that root's binding and cancels its pending submission. Use one owning root per controller; duplicate roots report a development error and the newest binding wins.
+`name` is sufficient to bind an input. Modern forms also accept `name={['user', 'email']}` for nested data; `field={form.field(path)}` is optional and adds model-aware type checking and validator inference.
 
-`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` without setting `submitError`; submission failures set it. 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