@cube-dev/ui-kit 0.179.0 → 0.181.0

package/dist/utils/react/nullableValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 //#region src/utils/react/nullableValue.ts
 function castNullableStringValue(props) {
 	return castNullableField(props, ["value", "defaultValue"], "string", (v) => String(v));

package/dist/utils/react/programmaticFocus.js

@@ -0,0 +1,58 @@
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
+//#region src/utils/react/programmaticFocus.ts
+/**
+* Telling focus the user moved from focus a component moved for them.
+*
+* Handing focus back to a trigger after its overlay closes is not the same
+* event as a user tabbing onto that trigger, but the DOM cannot tell them
+* apart: `.focus()` produces an ordinary focus event, and the modality is
+* still "keyboard" from whatever the user just did, so anything keyed off
+* focus-visible treats it as a deliberate arrival. A trigger's tooltip pops up
+* unasked — and then absorbs the user's next `Escape` from its own
+* document-level listener (CUB-4839).
+*
+* Two mechanisms, because restoration reaches us two ways:
+*
+* - `focusProgrammatically` for restores WE perform. `focus()` dispatches
+*   `focus`/`focusin` synchronously, so a flag set around the call is readable
+*   by every handler that runs for it and gone immediately afterwards. Exact,
+*   with no window to tune.
+*
+* - `markFocusRestoreWindow` for restores React Aria performs. A `FocusScope`
+*   restores on unmount, from inside React's own commit, and offers no hook to
+*   wrap — so an overlay that is closing declares the window instead. Coarser
+*   on purpose: it can only make a tooltip skip one arrival that lands while
+*   an overlay is going away, which is the case it exists for.
+*/
+let depth = 0;
+let restoreWindowEndsAt = 0;
+/**
+* Focus `element` without the UI reading it as the user arriving there.
+*/
+function focusProgrammatically(element, options) {
+	if (!element) return;
+	depth++;
+	try {
+		element.focus(options);
+	} finally {
+		depth--;
+	}
+}
+/**
+* Declare that focus is about to be restored by machinery we cannot wrap, for
+* roughly `duration` ms. Called by a closing overlay.
+*/
+function markFocusRestoreWindow(duration) {
+	restoreWindowEndsAt = Math.max(restoreWindowEndsAt, Date.now() + duration);
+}
+/**
+* Whether the focus being handled right now is a restoration rather than the
+* user arriving. Only meaningful inside a focus handler.
+*/
+function isFocusRestoration() {
+	return depth > 0 || Date.now() < restoreWindowEndsAt;
+}
+
+//#endregion
+export { focusProgrammatically, isFocusRestoration, markFocusRestoreWindow };
+//# sourceMappingURL=programmaticFocus.js.map

package/dist/utils/react/programmaticFocus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"programmaticFocus.js","names":[],"sources":["../../../src/utils/react/programmaticFocus.ts"],"sourcesContent":["/**\n * Telling focus the user moved from focus a component moved for them.\n *\n * Handing focus back to a trigger after its overlay closes is not the same\n * event as a user tabbing onto that trigger, but the DOM cannot tell them\n * apart: `.focus()` produces an ordinary focus event, and the modality is\n * still \"keyboard\" from whatever the user just did, so anything keyed off\n * focus-visible treats it as a deliberate arrival. A trigger's tooltip pops up\n * unasked — and then absorbs the user's next `Escape` from its own\n * document-level listener (CUB-4839).\n *\n * Two mechanisms, because restoration reaches us two ways:\n *\n * - `focusProgrammatically` for restores WE perform. `focus()` dispatches\n *   `focus`/`focusin` synchronously, so a flag set around the call is readable\n *   by every handler that runs for it and gone immediately afterwards. Exact,\n *   with no window to tune.\n *\n * - `markFocusRestoreWindow` for restores React Aria performs. A `FocusScope`\n *   restores on unmount, from inside React's own commit, and offers no hook to\n *   wrap — so an overlay that is closing declares the window instead. Coarser\n *   on purpose: it can only make a tooltip skip one arrival that lands while\n *   an overlay is going away, which is the case it exists for.\n */\nlet depth = 0;\nlet restoreWindowEndsAt = 0;\n\n/**\n * Focus `element` without the UI reading it as the user arriving there.\n */\nexport function focusProgrammatically(\n  element: HTMLElement | null | undefined,\n  options?: FocusOptions,\n) {\n  if (!element) return;\n\n  depth++;\n\n  try {\n    element.focus(options);\n  } finally {\n    depth--;\n  }\n}\n\n/**\n * Declare that focus is about to be restored by machinery we cannot wrap, for\n * roughly `duration` ms. Called by a closing overlay.\n */\nexport function markFocusRestoreWindow(duration: number) {\n  restoreWindowEndsAt = Math.max(restoreWindowEndsAt, Date.now() + duration);\n}\n\n/**\n * Whether the focus being handled right now is a restoration rather than the\n * user arriving. Only meaningful inside a focus handler.\n */\nexport function isFocusRestoration() {\n  return depth > 0 || Date.now() < restoreWindowEndsAt;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,IAAI,QAAQ;AACZ,IAAI,sBAAsB;;;;AAK1B,SAAgB,sBACd,SACA,SACA;AACA,KAAI,CAAC,QAAS;AAEd;AAEA,KAAI;AACF,UAAQ,MAAM,QAAQ;WACd;AACR;;;;;;;AAQJ,SAAgB,uBAAuB,UAAkB;AACvD,uBAAsB,KAAK,IAAI,qBAAqB,KAAK,KAAK,GAAG,SAAS;;;;;;AAO5E,SAAgB,qBAAqB;AACnC,QAAO,QAAQ,KAAK,KAAK,KAAK,GAAG"}

package/dist/utils/react/resolveIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 //#region src/utils/react/resolveIcon.ts
 /**
 * Resolves a dynamic icon prop to its content and slot state.

package/dist/utils/react/sharedStore.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { isDevEnv } from "../is-dev-env.js";
 import { useSyncExternalStore } from "react";

package/dist/utils/react/useBufferedValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useCallback, useRef, useState } from "react";
 

package/dist/utils/react/useCombinedRefs.js

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

package/dist/utils/react/useControlledFocusVisible.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { createSharedStore } from "./sharedStore.js";
 import { useEffect } from "react";
 import { useFocusVisible } from "react-aria";

package/dist/utils/react/useEventBus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 
 //#region src/utils/react/useEventBus.ts

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useEffect, useRef, useState } from "react";
 import { useSSRSafeId } from "@react-aria/ssr";

package/dist/utils/react/useIsDarwin.js

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

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { useMemo } from "react";
 

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import * as React$1 from "react";
 
 //#region src/utils/react/useLayoutEffect.tsx

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useCallback, useSyncExternalStore } from "react";
 

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/useOverlayEscapeGuard.js

@@ -0,0 +1,41 @@
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
+import { useEvent } from "../../_internal/hooks/use-event.js";
+
+//#region src/utils/react/useOverlayEscapeGuard.ts
+/**
+* Stops a CLOSED overlay from answering for `Escape` (CUB-4839).
+*
+* `useOverlay`'s `Escape` handler calls `stopPropagation()` and
+* `preventDefault()` for every `Escape` it sees, and only THEN asks whether
+* this overlay is the topmost one allowed to act on it — unlike
+* `onInteractOutside`, which it gates on `isOpen` up front. An overlay that has
+* already closed therefore consumes the key and does nothing with it, so the
+* `Escape` meant for the Dialog around it closes nothing at all.
+*
+* That is reachable here because our overlays stay mounted for their exit
+* transition while still holding DOM focus: pick an option from a list inside a
+* Dialog and the very next `Escape` lands in the closing list.
+*
+* Passing `useOverlay` an `isKeyboardDismissDisabled` of its own does NOT work,
+* and that is the reason this exists. `DisplayTransition` preserves content
+* across an exit by replaying the children it stored while the overlay was
+* open, so every value that subtree captured — `isKeyboardDismissDisabled`
+* included — stays frozen at its open-state reading for exactly the window
+* this has to guard. `useEvent` gets around it by returning a handler whose
+* identity never changes while its body always runs the latest render's
+* closure, so the frozen copy still sees the current `isOpen`.
+*/
+function useOverlayEscapeGuard(overlayProps, isOpen) {
+	const onKeyDown = useEvent((event) => {
+		if (event.key === "Escape" && !isOpen) return;
+		overlayProps.onKeyDown?.(event);
+	});
+	return {
+		...overlayProps,
+		onKeyDown
+	};
+}
+
+//#endregion
+export { useOverlayEscapeGuard };
+//# sourceMappingURL=useOverlayEscapeGuard.js.map

package/dist/utils/react/useOverlayEscapeGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOverlayEscapeGuard.js","names":[],"sources":["../../../src/utils/react/useOverlayEscapeGuard.ts"],"sourcesContent":["import { useEvent } from '../../_internal';\n\nimport type { DOMAttributes, KeyboardEvent } from 'react';\n\ntype OverlayDOMProps = DOMAttributes<any>;\n\n/**\n * Stops a CLOSED overlay from answering for `Escape` (CUB-4839).\n *\n * `useOverlay`'s `Escape` handler calls `stopPropagation()` and\n * `preventDefault()` for every `Escape` it sees, and only THEN asks whether\n * this overlay is the topmost one allowed to act on it — unlike\n * `onInteractOutside`, which it gates on `isOpen` up front. An overlay that has\n * already closed therefore consumes the key and does nothing with it, so the\n * `Escape` meant for the Dialog around it closes nothing at all.\n *\n * That is reachable here because our overlays stay mounted for their exit\n * transition while still holding DOM focus: pick an option from a list inside a\n * Dialog and the very next `Escape` lands in the closing list.\n *\n * Passing `useOverlay` an `isKeyboardDismissDisabled` of its own does NOT work,\n * and that is the reason this exists. `DisplayTransition` preserves content\n * across an exit by replaying the children it stored while the overlay was\n * open, so every value that subtree captured — `isKeyboardDismissDisabled`\n * included — stays frozen at its open-state reading for exactly the window\n * this has to guard. `useEvent` gets around it by returning a handler whose\n * identity never changes while its body always runs the latest render's\n * closure, so the frozen copy still sees the current `isOpen`.\n */\nexport function useOverlayEscapeGuard<T extends OverlayDOMProps>(\n  overlayProps: T,\n  isOpen: boolean | undefined,\n): T {\n  const onKeyDown = useEvent((event: KeyboardEvent<any>) => {\n    // Decline it, so it reaches whoever can actually act on it.\n    if (event.key === 'Escape' && !isOpen) return;\n\n    overlayProps.onKeyDown?.(event);\n  });\n\n  return { ...overlayProps, onKeyDown };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,sBACd,cACA,QACG;CACH,MAAM,YAAY,UAAU,UAA8B;AAExD,MAAI,MAAM,QAAQ,YAAY,CAAC,OAAQ;AAEvC,eAAa,YAAY,MAAM;GAC/B;AAEF,QAAO;EAAE,GAAG;EAAc;EAAW"}

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
 import { useCallback, useContext, useEffect, useRef } from "react";
 

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useScheme.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { useSyncExternalStore } from "react";
 
 //#region src/utils/react/useScheme.ts

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.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.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.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.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.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.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.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.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.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.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { isDevEnvOrTest } from "./is-dev-env.js";
 
 //#region src/utils/warnings.ts

package/dist/version.js

@@ -1,7 +1,7 @@
-/** @license MIT | @cube-dev/ui-kit v0.179.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.179.0";
-const TASTY_VERSION = "3.9.1";
+const VERSION = "0.181.0";
+const TASTY_VERSION = "3.9.2";
 if (typeof window !== "undefined") {
 	const version = VERSION;
 	const tastyVersion = TASTY_VERSION;

package/docs/CreateComponent.md

@@ -15,6 +15,10 @@ 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 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.
+
 ## Core Concepts
 
 ### 1. Base Properties with `filterBaseProps`

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,42 +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
+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/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/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,7 +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
+
+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 EmailForm() {
+  const form = Form.useController<{ email: string | null }>({
+    defaultValues: { email: null },
+  });
+
+  return (
+    <Form form={form} onSubmit={(values, { signal }) => save(values, signal)}>
+      <TextInput name="email" label="Email" isRequired />
+      <Form.SubmitError />
+      <Form.Submit>Save</Form.Submit>
+    </Form>
+  );
+}
+```
+
+`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.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.
+
+**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
 
@@ -536,7 +560,7 @@ export function ConfirmDeletionDialogForm({ name, onSubmit, onDismiss }) {
 - `defaultValues` instead of `initialValues`
 - `onSubmit` can return a promise — the form and submit button show loading state until the promise resolves
 - Arrays inside form data are not supported
-- `preserve` property is not yet implemented
+- `preserve` is supported by modern controllers; it remains unimplemented in the legacy backend
 - The `Field` component is a virtual wrapper (does not render a DOM element)
 - Nested properties are handled via field names with `.` dot notation
 - Does not support `validating` state (but validation rules can be async)

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