@cube-dev/ui-kit 0.0.0-canary-1672a95 → 0.0.0-canary-448aeb3

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`, `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. Extend `FieldBaseProps<Value>` to constrain typed modern descriptors to the control’s actual value API; `useFieldProps` resolves descriptors and strips them before DOM forwarding. 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. 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

@@ -6,9 +6,12 @@ When used inside a [Form](./components/form/Form.md), these properties are autom
 
 ## 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` — Field name for form data binding when a descriptor is not supplied.
+- **`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 +70,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[]` — Explicit modern field dependencies. Validator reads also track dependencies automatically.
+- **`rulesKey`** `string` — Explicit modern validator revision, checked alongside structural rule constraints.
+- **`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.

package/docs/Usage.md

@@ -473,7 +473,7 @@ const [form] = useForm();
 
 `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.
 
-For new modern forms, prefer `<TextInput field={form.field('email', { validate, deps })} />`; descriptors check names and value types and support nested tuple paths. `Form.useValue(form, path)` and `Form.useFieldState(form, path)` provide narrow reactive reads. Hook callbacks stay fresh after commit; defaults change through explicit commands. Validator field reads track dependencies automatically; external captures belong in `deps`. 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.
+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. Validator field reads track dependencies automatically; external captures belong in `deps`. 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.
 
 Returns a `CubeFormInstance` with:
 

package/docs/components/form/Form.md

@@ -42,7 +42,9 @@ Removing a field removes it from `activeValues` immediately and retains its valu
 
 ### 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`; its options take precedence over matching input validation/default options. Keep presentation such as labels and `isRequired` on the input. Existing `name` bindings remain available for legacy-compatible controls.
+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>({
@@ -62,13 +64,13 @@ const form = Form.useController<Profile>({
 
 `validate(value, context)` infers the field value and checked paths in `context.getValue(path)`. Declare external inputs with `deps`, compared by `Object.is`. Field reads through `getValue` automatically become dependencies; `getValues()` depends on the whole values object. `dependsOn` can declare paths before the validator reads them. Each run reads one captured snapshot. Changes abort obsolete work, invalidate the dependent result, and 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. Inline function identity does not restart validation, so change `deps` when captured inputs change.
 
-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. Snapshot read types are deeply readonly and potentially incomplete; use controller commands for writes.
+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.
 
 ### 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. `disableOnInvalid={false}` allows a modern Submit button to run validation while errors are visible; the default remains `true`. Reset is enabled when values, interaction state, validation state, or submit errors can be reset; root reset cancellation is honored.
 
-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.
+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.
 
@@ -80,8 +82,6 @@ Use `rules`, `isRequired`, `validateTrigger`, and `validationDelay` on named inp
 
 `errorPolicy: 'first' | 'all'` controls rule-order errors (default `first`), on the creator or individual field. Equivalent inline rules do not restart validation: primitive constraints and RegExp source/flags form the signature; messages and function identity/source do not. Use `deps` for external captured inputs. `rulesKey` remains an additional revision key and never suppresses structural constraint checks. 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.
-
 `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.
 
 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.

package/docs/modern-form-migration.md

@@ -33,6 +33,32 @@ The following API mapping describes migration choices; names are not mechanicall
 
 `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.
 
+## 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)`. Declare external inputs with `deps`, compared by `Object.is`. Field reads through `getValue` automatically become dependencies; `getValues()` depends on the whole values object. `dependsOn` can declare paths before the validator reads them. Each run reads one captured snapshot. Changes abort obsolete work, invalidate the dependent result, and 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. Inline function identity does not restart validation, so change `deps` when captured inputs change.
+
+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`.
@@ -84,53 +110,29 @@ Built-in named inputs register after commit and select only their value, errors,
 
 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. Use `rulesKey` for dependencies captured by a validator whose function source stays the same (for example, an organization id). Keep service callbacks stable or include their revision in that key too. Equivalent rule signatures do not restart pending validation.
+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]`). Field reads track dependencies automatically; use `dependsOn` to declare them before an asynchronous validator reads them. `rulesKey` is an optional explicit revision. Function identity and source text do not restart validation; structural rule changes, changed `deps`, and changed `rulesKey` do.
 
 `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. `disableOnInvalid={false}` allows a modern Submit button to run validation while errors are visible; the default remains `true`. Reset is enabled when values, interaction state, validation state, or submit errors can be reset; root reset cancellation is honored.
+
+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.
+
 ## Per-form migration checklist
 
 1. Record existing defaults, validation timing, dynamic names, conditionally mounted fields, and submitted payloads. Keep the legacy form available for a rollback.
 2. Check surrounding wrappers. Migrate a wrapper explicitly or choose a form that does not rely on its legacy instance API.
 3. Create a typed controller and move initial defaults into its creation options. Choose adoption/reset semantics for later data.
 4. Replace render-time getters and flags with narrow selectors or `Subscribe`. Update custom controls through `useFieldProps`.
-5. Adapt validators' success values and cancellation, and version captured dependencies with `rulesKey`.
+5. Adapt validators' success values and cancellation, and declare external captured inputs in `deps`.
 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.
 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.
-
-### 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`; its options take precedence over matching input validation/default options. Keep presentation such as labels and `isRequired` on the input. Existing `name` bindings remain available for legacy-compatible controls.
-
-```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)`. Declare external inputs with `deps`, compared by `Object.is`. Field reads through `getValue` automatically become dependencies; `getValues()` depends on the whole values object. `dependsOn` can declare paths before the validator reads them. Each run reads one captured snapshot. Changes abort obsolete work, invalidate the dependent result, and 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. Inline function identity does not restart validation, so change `deps` when captured inputs change.
-
-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. Snapshot read types are deeply readonly and potentially incomplete; use controller commands for writes.
-
-### 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. `disableOnInvalid={false}` allows a modern Submit button to run validation while errors are visible; the default remains `true`. Reset is enabled when values, interaction state, validation state, or submit errors can be reset; root reset cancellation is honored.
-
-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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.0.0-canary-1672a95",
+  "version": "0.0.0-canary-448aeb3",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {