@cube-dev/ui-kit 0.180.0 → 0.181.0

package/dist/utils/react/forwardRefWithGenerics.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 //#region src/utils/react/forwardRefWithGenerics.tsx
 /**
 * A helper for creating forwardRef components with generic types.

package/dist/utils/react/index.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { getDisabledElementProps, omitActivationEventProps } from "./disabledProps.js";
 import { forwardRefWithGenerics } from "./forwardRefWithGenerics.js";

package/dist/utils/react/interactions.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { useState } from "react";
 import { useFocus, useFocusVisible } from "react-aria";
 

package/dist/utils/react/isTextOnly.js

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

package/dist/utils/react/mapProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 //#region src/utils/react/mapProps.ts
 /** Converts AriaButtonProps to CubeButtonProps */
 function ariaToCubeButtonProps(props) {

package/dist/utils/react/mergeProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { mergeIds } from "./useId.js";
 import { mergeStyles } from "@tenphi/tasty";

package/dist/utils/react/nullableValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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.180.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,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.180.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.181.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.180.0";
+const VERSION = "0.181.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/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,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