@cube-dev/ui-kit 0.182.0 → 0.184.0

package/docs/components/form/ModernForm.md

@@ -2,7 +2,7 @@
 
 For a new modern form, start with `Form.useController<Model>()`, bind inputs with `name="email"` or a nested tuple such as `name={['user', 'email']}`, and submit through `<Form onSubmit={...}>` and `<Form.Submit>`. Add subscriptions only where other UI needs to read form state. The input components already subscribe to their own values and errors. `field={form.field(path)}` is an optional alternative when you want model-checked paths, input value compatibility checks, or inferred custom-validator types.
 
-Existing `Form.useForm()` forms and roots without a modern controller use the legacy backend. Follow the [migration checklist](https://github.com/cube-js/cube-ui-kit/blob/main/docs/modern-form-migration.md) when converting one. `DialogForm` still requires a legacy instance; do not pass a modern controller through a cast.
+**The modern implementation is recommended for new forms.** UI Kit also ships a legacy implementation for compatibility. Existing `Form.useForm()` forms and roots without a modern controller use the legacy backend. Follow the [migration checklist](https://github.com/cube-js/cube-ui-kit/blob/main/docs/modern-form-migration.md) when converting one. `DialogForm` also accepts a modern controller and is recommended for new dialog forms; it preserves the legacy implementation when no modern controller is supplied.
 
 Recipes: [API choices](#pick-one-binding-and-one-owner-for-each-concern), [reactive UI](#read-a-value-show-status-or-reveal-a-section), [server data](#load-server-data-refresh-defaults-or-discard-edits), [programmatic edits](#edit-values-from-an-event-handler), [validation](#validate-simple-rules-sibling-fields-or-an-api-response), [conditional fields and wizards](#hide-fields-use-nested-data-or-build-a-wizard), [submission](#submit-display-server-errors-and-reset), and [custom controls](#implement-a-reusable-custom-control).
 
@@ -267,3 +267,24 @@ Use the same field integration as built-in inputs: `FieldBaseProps<Value>`, `use
 The [compiled CustomControl example](https://github.com/cube-js/cube-ui-kit/blob/main/typecheck/consumer/modern-form-examples.tsx) shows the complete pattern. The [component creation guide](https://cube-ui-kit.vercel.app/?path=/docs/getting-started-create-component--docs) explains the shared field wrapper. `Form.Item` / `Field` belongs to the legacy backend; it is not a second way to connect a modern custom input.
 
 For SSR, seed the controller with the same serializable defaults on server and client. Initial hydration uses the creation snapshot before subscribers catch up with client state. Each mounted creator owns its controller; no manual disposal is needed.
+
+## Use a form in a dialog
+
+`DialogForm` selects the same implementation as `Form`: pass a modern controller for new dialogs. Create the controller above the dialog when its draft should survive unmounts, seed defaults in the creation hook, and put save callbacks on the root.
+
+```tsx
+function EditProfileDialog({ initialProfile, save }) {
+  const form = Form.useController<{ email: string | null }>({ defaultValues: initialProfile });
+  return (
+    <DialogTrigger>
+      <Button>Edit profile</Button>
+      <DialogForm form={form} title="Edit profile" onSubmit={(values, { signal }) => save(values, signal)}>
+        <TextInput name="email" label="Email" isRequired />
+        <Form.SubmitError />
+      </DialogForm>
+    </DialogTrigger>
+  );
+}
+```
+
+The dialog closes only after successful submission, including `form.submit()` and controller-configured callbacks. Validation or save errors keep it open. Closing cancels pending submission; late responses cannot close a reopened session. By default, ending the session resets values. Use `preserve` to retain the draft in a controller owned outside the dialog. `preserve` does not keep an unmounted controller alive. See the [DialogForm reference](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogform--docs) for custom actions, container lifecycle, and legacy behavior.

package/docs/components/navigation/Tabs.md

@@ -41,7 +41,7 @@ An accessible tabbed interface for organizing content into multiple panels, show
 - **`isReorderable`** `boolean` (default: `false`) — Enable drag-and-drop tab reordering. When a tab picker is shown, reordering is automatically enabled in the picker dropdown as well
 - **`keyOrder`** `string[]` — Controlled tab display order
 - **`onReorder`** `(newOrder: string[]) => void` — Callback when tabs are reordered
-- **`showTabPicker`** `boolean | 'auto'` (default: `false`) — Show dropdown tab picker
+- **`showTabPicker`** `boolean | 'auto'` (default: `false`) — Show dropdown tab picker. Each entry carries its tab's `icon` and `tooltip`
 - **`showScrollArrows`** `boolean | 'auto'` (default: `false`) — Show scroll navigation arrows
 - **`tabPickerPosition`** `'prefix' | 'suffix'` (default: `suffix`) — Position of the tab picker
 - **`scrollArrowsPosition`** `'prefix' | 'suffix'` (default: `suffix`) — Position of the scroll arrows
@@ -121,7 +121,7 @@ For individual tabs:
 - `medium` - Default size with t3m typography
 - `large` - Larger tabs with t3m typography
 
-**Note:** Radio type supports `large` (default, 40px total) and `medium` (32px total) sizes, mapped to Item button sizes `medium` (32px) and `xsmall` (24px) respectively.
+**Note:** Radio type supports `large` (default, 40px total) and `medium` (32px total) sizes, mapped to Item button sizes `medium` (32px) and `xsmall` (24px) respectively. A radio tab given less room than its title (an explicit `width`, say) truncates the title and shows it in a tooltip.
 
 ### Placement / Vertical Tabs
 
@@ -409,7 +409,7 @@ Add dropdown menus to tabs using the `menu` prop. This replaces the need for man
 
 Combine editable tabs with a menu for rename, duplicate, and delete actions. The inline editing UI is provided by [InlineInput](../content/InlineInput.md), which can also be used standalone elsewhere.
 
-> For editable tabs the `tooltip` prop is rendered by `InlineInput` rather than by the surrounding tab button. This keeps the tooltip in sync with the editing UI (and avoids a double tooltip) — the trigger area is the title content, not the entire tab button. Long titles also get an automatic ellipsis + overflow tooltip without any extra configuration.
+> For editable tabs with a string title the `tooltip` prop is rendered by `InlineInput` rather than by the surrounding tab button. This keeps the tooltip in sync with the editing UI (and avoids a double tooltip) — the trigger area is the title content, not the entire tab button. Long titles also get an automatic ellipsis + overflow tooltip without any extra configuration. An editable tab whose `title` is a ReactNode shows its `tooltip` on the tab button instead, hidden while the title is being edited.
 
 ```jsx
 <Tabs

package/docs/components/overlays/Dialog.md

@@ -87,6 +87,17 @@ The `mods` property accepts the following modifiers you can override:
 
 - **`dismissable`** `boolean` — Applied when the dialog can be dismissed with close button or Escape key
 
+`Footer` inside a dialog carries one modifier of its own:
+
+- **`content-overflow`** `boolean` — Applied while the dialog's `Content` is taller than the room it has, i.e. while it scrolls. The footer draws its top border only then, so the line separates the actions from a body that continues beneath them and is absent under a body that fits.
+
+The body is the `Content` that is a direct child of the dialog or of a direct-child `<form>`. A `border` in the footer's own styles replaces the default, so a footer can keep the line always or never draw it:
+
+```jsx
+<Footer styles={{ border: 'top' }}>{/* line always */}</Footer>
+<Footer styles={{ border: false }}>{/* line never */}</Footer>
+```
+
 ## Variants
 
 ### Types
@@ -213,9 +224,25 @@ The `mods` property accepts the following modifiers you can override:
    </Dialog>
    ```
 
-3. **Accessibility**: Always provide a meaningful title for screen readers
-4. **Dismissal**: Use `isDismissable` for dialogs that users can close voluntarily
-5. **Focus Management**: Ensure focus moves to the most important action when dialog opens
+3. **Wrapping the slots in a form**: A `Form` may sit directly between `Dialog` and its slots, so the submit button is inside it. A `Form` placed there lays itself out as the dialog's slot column, so `Content` still scrolls and `Footer` still pins with no styles of your own:
+
+   ```jsx
+   <Dialog>
+     <Header><Title>Edit</Title></Header>
+     <Form>
+       <Content>{/* long body, scrolls */}</Content>
+       <Footer>
+         <Button type="primary" htmlType="submit">Save</Button>
+       </Footer>
+     </Form>
+   </Dialog>
+   ```
+
+   Only a **direct child** `Form` is treated this way. A form nested deeper, or a plain `<form>` element, is your own layout and is left alone. The layout is the form's own state rather than a rule in `Dialog`, so `styles` on the form still win: `<Form styles={{ gap: '1x' }}>` puts `1x` between the slots.
+
+4. **Accessibility**: Always provide a meaningful title for screen readers
+5. **Dismissal**: Use `isDismissable` for dialogs that users can close voluntarily
+6. **Focus Management**: Ensure focus moves to the most important action when dialog opens
 
 ## Integration with Overlays
 

package/docs/components/overlays/DialogForm.md

@@ -1,54 +1,55 @@
 # DialogForm
 
-DialogForm combines [Dialog](./Dialog.md) and [Form](../form/Form.md) functionality into a single component for collecting user input in a modal context. It provides automatic form submission handling, dialog closing, and default action buttons.
+DialogForm combines a dialog, a form, and submit/cancel actions. It closes after a successful submission and keeps the dialog open when validation or saving fails.
 
-**Recommended Usage:** Use the [`useDialogContainer`](./UseDialogContainer.md) hook for programmatic control over DialogForm. This provides a cleaner API and better state management compared to `DialogTrigger`.
+## Choose the implementation
+
+UI Kit has two form implementations. **Use the modern controller API for new forms.** Pass `form={Form.useController<Model>()}` to select it. `DialogForm` without a modern controller continues to use the legacy implementation, including existing `Form.useForm()` callers. The same input components work with either implementation.
+
+The examples below use modern controllers. See [Modern Form](../form/ModernForm.md) for defaults, nullable API values, subscriptions, validation, and submission recipes. The [migration guide](https://github.com/cube-js/cube-ui-kit/blob/main/docs/modern-form-migration.md) explains differences from legacy forms.
 
 ## When to Use
 
-- Collect user input in a focused modal interface
-- Create forms that require user attention and confirmation
-- Build edit dialogs, creation modals, or settings forms
-- Handle form submission with automatic dialog closing
+- Collect input in a focused dialog, such as creating or editing a record
+- Confirm an operation that needs validated input
+- Close automatically after saving, with built-in loading and cancel actions
 
 ## Component
 
----
-
-### Properties
-
-- **`title`** `string` — The title of the dialog
-- **`danger`** `boolean` — Whether the submit button has a danger theme
-- **`submitProps`** `CubeButtonProps` — Properties for submit button (use `label` to change text)
-- **`cancelProps`** `CubeButtonProps` — Properties for cancel button (use `label` to change text)
-- **`preserve`** `boolean` (default: `false`) — Preserve form values after submission/dismissal
-- **`noActions`** `boolean` — Hide default action buttons to manually specify them
-- **`size`** `'S' | 'M' | 'L' | 'small' | 'medium' | 'large'` — The size of the dialog
-- **`isDismissable`** `boolean` — Whether the dialog is dismissable
-- **`closeIcon`** `ReactElement` — Custom close icon element
-- **`closeButtonStyles`** `Styles` — Custom styles for the close button
-- **`name`** `string` — Form name
-- **`form`** `CubeFormInstance` — Form instance created by `useForm`
-- **`defaultValues`** `object` — Default field values
-- **`onSubmit`** `(data) => void | Promise` — Callback on form submit and success
-- **`onSubmitFailed`** `(error?) => void | Promise` — Callback on form submit and failure
-- **`onValuesChange`** `function` — Callback when any field value changes
-- **`orientation`** `'vertical' | 'horizontal'` — Layout orientation of the form
-- **`labelWidth`** `string` — The size of the side area with labels (only for `labelPosition="side"`)
-- **`labelPosition`** `'top' | 'side'` — Where to place labels relative to inputs
-- **`labelStyles`** `Styles` — Styles for the label
-- **`requiredMark`** `boolean` — Whether the field presents required mark
-- **`necessityIndicator`** `NecessityIndicator` — The type of necessity indicator
-- **`isReadOnly`** `boolean` — Whether the form is read only
-- **`isInvalid`** `boolean` — Invalid state for all fields in the form
-- **`isValid`** `boolean` — Valid state for all fields in the form
-- **`validationState`** `'valid' | 'invalid'` — _(deprecated)_ Use `isInvalid` / `isValid` instead
-- **`validateTrigger`** `ValidateTrigger` — On which event to perform validation
-- **`showValid`** `boolean` — Whether to show valid state
-
-### Base Properties
-
-Supports [Base properties](../../BaseProperties.md)
+## Properties
+
+- **`form`** `FormController<T> | CubeFormInstance<T>` — Modern controller (recommended) or legacy instance. Omitting it selects legacy behavior.
+- **`title`** `string` — Dialog title
+- **`danger`** `boolean` — Give the submit button the danger theme
+- **`submitProps`** `CubeButtonProps` (legacy) / `Omit<CubeSubmitButtonProps<T>, 'form'>` (modern) — Customize the submit button, including its label and modern `disableOnInvalid`
+- **`cancelProps`** `CubeButtonProps` — Customize the cancel button, including its label
+- **`preserve`** `boolean` (default: `false`) — Retain values when the editing session ends. Keep the controller mounted above the dialog to retain a draft across dialog unmounts.
+- **`noActions`** `boolean` — Hide the default submit/cancel buttons
+- **`children`** `ReactNode | ((dismiss: () => void) => ReactNode)` — Fields, or a render function for custom actions
+- **`onDismiss`** `() => void` — Called by the built-in Cancel/close button or the render function's `dismiss`. Handle Escape, outside clicks, and externally controlled closing on `DialogTrigger` or `DialogContainer`.
+- **`onSubmit`** `(values: FormValues<T>, context: ModernSubmitContext) => void | Promise<void>` — Modern submit callback. Resolve to close; throw/reject to keep the dialog open. The context supplies an `AbortSignal`.
+- **`onSubmitFailed`** `(failure: ModernSubmitFailure) => void | Promise<void>` — Distinguishes invalid fields from a failed save
+- **`onValuesChange`** `(values: FormValues<T>, change: FormChange) => void | Promise<void>` — Modern value-change callback
+- **`submitValues`** `'active' | 'all'` (default: `'active'`) — Modern native submission payload, including Enter. `'all'` includes retained values; validation still checks active fields.
+- **`onReset`** `(event: FormEvent<HTMLFormElement>) => void` — Modern native reset interception; `preventDefault()` cancels it
+- **`defaultValues`** `Partial<T>` — Legacy only. Seed modern defaults in `Form.useController()`.
+- **`size`** `'S' | 'M' | 'L' | 'small' | 'medium' | 'large'` — Dialog size
+- **`isDismissable`** `boolean` — Show the dialog's close affordance; configure Escape/outside-click dismissal on the container
+- **`closeIcon`** `ReactElement` — Custom close icon
+- **`closeButtonStyles`** `Styles` — Close button styles
+
+Supports shared [Form presentation properties](../form/Form.md#properties), [Dialog styles](./Dialog.md), and [Base properties](../../BaseProperties.md). Layout/style props style the dialog; label and form configuration props configure its inner form.
+
+### Form presentation properties
+
+- **`labelPosition`** `'top' | 'side' | 'split'` — Position field labels
+- **`labelStyles`** `Styles` — Field label styles
+- **`labelWidth`** `Styles['width']` — Modern inner form label width
+- **`orientation`** `'vertical' | 'horizontal'` — Modern inner form orientation
+- **`necessityIndicator`** `'icon' | 'label' | null` — Required/optional indicator style
+- **`isReadOnly`** `boolean` — Make fields read-only
+- **`isValid`** `boolean` — Show valid field styling
+- **`validationState`** `'valid' | 'invalid'` — Deprecated; use `isInvalid` / `isValid`
 
 ### Style Properties
 
@@ -61,253 +62,111 @@ These properties allow direct style application without using the `styles` prop:
 
 ## Examples
 
-### Basic DialogForm (Recommended)
-
-Using `useDialogContainer` for programmatic control:
+### Open a form with DialogTrigger
 
-```jsx
-import { useDialogContainer, DialogForm, Input, Button } from '@cube-dev/ui-kit';
+Create the controller above the dialog. Put callbacks on `DialogForm` and bind inputs with `name`.
 
-function UserFormDialog({ onSubmit, initialData }) {
-  return (
-    <DialogForm
-      title="User Information"
-      defaultValues={initialData}
-      onSubmit={onSubmit}
-    >
-      <Input.Text
-        name="name"
-        label="Name"
-        rules={[{ required: true, message: 'Name is required' }]}
-        placeholder="Enter your name"
-      />
-      <Input.Text
-        name="email"
-        label="Email"
-        type="email"
-        rules={[
-          { required: true, message: 'Email is required' },
-          { type: 'email', message: 'Please enter a valid email' }
-        ]}
-        placeholder="Enter your email"
-      />
-    </DialogForm>
-  );
-}
+```tsx
+import { Button, DialogForm, DialogTrigger, Form, TextInput } from '@cube-dev/ui-kit';
 
-function App() {
-  const userDialog = useDialogContainer(UserFormDialog);
-
-  const openDialog = () => {
-    userDialog.open({
-      initialData: { name: '', email: '' },
-      onSubmit: async (data) => {
-        await saveUser(data);
-        userDialog.close();
-      }
-    });
-  };
+function EditProfile({ initialProfile, save }) {
+  const form = Form.useController<{ name: string | null; email: string | null }>({
+    defaultValues: initialProfile,
+  });
 
   return (
-    <>
-      <Button onPress={openDialog}>Add User</Button>
-      {userDialog.rendered}
-    </>
+    <DialogTrigger>
+      <Button>Edit profile</Button>
+      <DialogForm
+        form={form}
+        title="Edit profile"
+        submitProps={{ label: 'Save' }}
+        onSubmit={(values, { signal }) => save(values, signal)}
+      >
+        <TextInput name="name" label="Name" isRequired />
+        <TextInput name="email" label="Email" rules={[{ type: 'email' }]} />
+        <Form.SubmitError />
+      </DialogForm>
+    </DialogTrigger>
   );
 }
 ```
 
-### With DialogTrigger (Alternative)
-
-For simpler use cases, you can use `DialogTrigger`:
-
-```jsx
-<DialogTrigger>
-  <Button>Open Form</Button>
-  <DialogForm
-    title="User Information"
-    onSubmit={async (data) => {
-      await saveUser(data);
-    }}
-  >
-    <Input.Text
-      name="name"
-      label="Name"
-      rules={[{ required: true }]}
-      placeholder="Enter your name"
-    />
-    <Input.Text
-      name="email"
-      label="Email"
-      type="email"
-      rules={[
-        { required: true },
-        { type: 'email', message: 'Please enter a valid email' }
-      ]}
-      placeholder="Enter your email"
-    />
-  </DialogForm>
-</DialogTrigger>
-```
+`defaultValues` is read once. For later API data, choose `adoptDefaultValues` to preserve edits or `reset({ values })` to start a new editing session. See [loading server data](../form/ModernForm.md#load-server-data-refresh-defaults-or-discard-edits).
 
-### Danger DialogForm
-
-```jsx
-<DialogForm
-  title="Delete Account"
-  danger
-  submitProps={{ label: 'Delete' }}
-  cancelProps={{ label: 'Keep Account' }}
-  onSubmit={async (data) => {
-    await deleteAccount(data.confirmation);
-  }}
->
-  <Input.Text
-    name="confirmation"
-    label="Type DELETE to confirm"
-    rules={[
-      { required: true },
-      { pattern: /^DELETE$/, message: 'Please type DELETE' }
-    ]}
-  />
-</DialogForm>
-```
+### Programmatic opening
 
-### Custom Actions with Access to Dismiss
+Use [useDialogContainer](./UseDialogContainer.md) when there is no persistent trigger. Its content component can own a fresh controller for each mount.
 
-When you need custom action buttons, use `noActions` prop and the render function pattern:
+```tsx
+function UserFormDialog({ initialData, save }) {
+  const form = Form.useController({ defaultValues: initialData });
+  return (
+    <DialogForm form={form} title="User information" onSubmit={save}>
+      <TextInput name="name" label="Name" isRequired />
+      <Form.SubmitError />
+    </DialogForm>
+  );
+}
 
-```jsx
-<DialogForm
-  title="Advanced Form"
-  noActions
-  onSubmit={handleSubmit}
->
-  {(dismiss) => (
+function App() {
+  const dialog = useDialogContainer(UserFormDialog);
+  return (
     <>
-      <Input.Text name="field1" label="Field 1" />
-      <Input.Text name="field2" label="Field 2" />
-
-      <ButtonGroup>
-        <SubmitButton>Save</SubmitButton>
-        <Button onPress={() => {
-          saveAsDraft();
-          dismiss();
-        }}>
-          Save as Draft
-        </Button>
-        <Button onPress={dismiss}>Cancel</Button>
-      </ButtonGroup>
+      <Button onPress={() => dialog.open({ initialData: { name: '' }, save: saveUser })}>
+        Add user
+      </Button>
+      {dialog.rendered}
     </>
-  )}
-</DialogForm>
+  );
+}
 ```
 
-### Preserving Form Values
+Do not call `dialog.close()` from the submit callback: `DialogForm` already closes on success. If reusing a mounted content component for another record, remount it with a record key or explicitly reset its controller.
 
-Use `preserve` prop to keep form values when reopening the dialog:
+### Custom actions and drafts
 
-```jsx
-<DialogForm
-  title="Edit Draft"
-  preserve
-  defaultValues={draftData}
-  onSubmit={saveDraft}
->
-  <Input.Text name="title" label="Title" />
-  <TextArea name="content" label="Content" />
-</DialogForm>
+```tsx
+function DraftDialog({ form, save }) {
+  return (
+    <DialogForm form={form} title="Edit draft" preserve noActions onSubmit={save}>
+      {(dismiss) => (
+        <>
+          <TextInput name="title" label="Title" />
+          <Form.SubmitError />
+          <ButtonGroup>
+            <Form.Submit>Publish</Form.Submit>
+            <Button onPress={dismiss}>Keep draft and close</Button>
+          </ButtonGroup>
+        </>
+      )}
+    </DialogForm>
+  );
+}
 ```
 
-## Behavior
-
-### Form Submission
-
-- On successful submission (`onSubmit`), the dialog automatically closes
-- Form fields are automatically reset after closing (unless `preserve` is true)
-- Reset happens after a 250ms delay to allow exit animations to complete
+The parent owns `form` in this example. `preserve` keeps its draft on dismissal and success; it cannot preserve a controller whose owning component is itself destroyed. It is separate from a field's `preserve` option, which controls retained values when that individual input unmounts.
 
-### Dialog Dismissal
-
-- When dismissed via cancel button or Escape key, form fields are reset (unless `preserve` is true)
-- Both `onClose` (from dialog context) and `onDismiss` callbacks are triggered
-
-### Default Buttons
+## Behavior
 
-- **Submit Button**: Labeled "Submit" by default, automatically handles form submission and loading states
-- **Cancel Button**: Labeled "Cancel" by default, dismisses the dialog and resets the form
-- Both buttons can be customized via `submitProps` and `cancelProps`
-- Hide default buttons with `noActions={true}` to provide custom actions
+- Actions render in a pinned `Footer` beside the scrolling `Content`, so a long form scrolls its body while Submit and Cancel stay visible. The `<form>` wraps both slots, so the buttons are still inside it and native submit works. The footer draws a top line only while the body scrolls; a form that fits has none. Set `noActions` to supply your own.
+- Modern forms use the same callback precedence as `Form`: root callbacks override controller callbacks; omitted callbacks fall back to the controller's latest committed callbacks. Automatic closing works for both, including imperative `form.submit()`.
+- Invalid fields and rejected saves leave the dialog open. Include `Form.SubmitError` to display save failures. Submit stays enabled after validation errors by default so the user can retry.
+- In a popover, modern form actions keep the dialog open while validating or saving. This also covers custom actions inside the form; successful submission and explicit dismissal control when it closes.
+- Explicit Submit/Cancel actions can close a dialog even when its trigger disables passive dismissal with `isDismissable={false}`. Escape and outside-click dismissal remain disabled.
+- Modern dismissal cancels pending submission even with `preserve`. The submitted callback receives an aborted signal; a late completion cannot close a reopened dialog. Pass the signal to abortable API work.
+- Modern values reset when the editing session ends unless `preserve` is set. This includes Cancel, the close button, Escape/outside closing, and removal of the dialog. Hidden dialogs also end the session when closed. A close followed by an immediate reopen has no delayed reset that can erase new edits.
+- Replacing the modern controller ends the detached controller's session using its last committed `preserve` setting. The new controller keeps its own values and editing session.
+- Legacy callers retain their existing callback and reset contracts, including the delayed reset after built-in Cancel and successful submit. Refer to [FormInstance (legacy)](../form/FormInstance.md) for its methods.
 
 ## Accessibility
 
-DialogForm combines accessibility features from both Dialog and Form:
-
-### Keyboard Navigation
-
-- `Tab` / `Shift + Tab` - Navigate through form fields and buttons
-- `Enter` - Submit the form (when on submit button)
-- `Escape` - Dismiss the dialog (if `isDismissable` is true)
-
-### Screen Reader Support
-
-- Dialog announces with proper title
-- Form fields have proper label associations
-- Validation errors are announced
-- Submit/cancel actions are clearly communicated
-- Focus management handles transitions between dialog open/close
-
-See [Dialog Accessibility](./Dialog.md#accessibility) and [Form Accessibility](../form/Form.md#accessibility) for complete details.
-
-## Best Practices
-
-1. **Use useDialogContainer for programmatic control**: Preferred method for better state management
-
-   ```jsx
-   const dialog = useDialogContainer(MyFormDialog);
-   dialog.open({ initialData, onSubmit: handleSubmit });
-   ```
-
-2. **Provide clear titles**: Always set a descriptive `title` for context
-
-   ```jsx
-   <DialogForm title="Edit User Profile" onSubmit={save}>
-   ```
-
-3. **Use danger theme for destructive actions**: Apply `danger` for delete/remove operations
-
-   ```jsx
-   <DialogForm title="Delete Item" danger submitProps={{ label: 'Delete' }}>
-   ```
-
-4. **Customize button labels**: Make action buttons specific to the task
-
-   ```jsx
-   <DialogForm
-     title="Create Project"
-     submitProps={{ label: 'Create' }}
-     cancelProps={{ label: 'Discard' }}
-   >
-   ```
-
-5. **Handle submission errors**: Implement `onSubmitFailed` for error handling
-
-   ```jsx
-   <DialogForm
-     onSubmit={save}
-     onSubmitFailed={(error) => notify.error(error.message)}
-   >
-   ```
-
-6. **Use preserve for drafts**: Enable `preserve` when working with draft content
-   ```jsx
-   <DialogForm preserve title="Edit Draft" defaultValues={draft}>
-   ```
+Provide a descriptive title and visible input labels. Tab and Shift+Tab navigate controls, Enter submits using native form behavior, and Escape dismisses when allowed by the container. Dialog manages focus containment and restoration. See [Dialog accessibility](./Dialog.md#accessibility).
 
 ## Related Components
 
-- [useDialogContainer](./UseDialogContainer.md) - **Recommended hook for programmatic dialog control**
-- [Dialog](./Dialog.md) - Base dialog component
-- [Form](../form/Form.md) - Form component with validation
-- [DialogTrigger](./DialogTrigger.md) - Alternative: manages dialog open/close state
-- [AlertDialog](./AlertDialog.md) - For simple confirmations without forms
+- [Form](../form/Form.md) — Shared form root and API selection
+- [Modern Form](../form/ModernForm.md) — Recommended implementation recipes
+- [DialogTrigger](./DialogTrigger.md) — Open from a persistent trigger
+- [useDialogContainer](./UseDialogContainer.md) — Programmatic dialog control
+- [AlertDialog](./AlertDialog.md) — Confirmations without form fields

package/docs/components/overlays/DialogTrigger.md

@@ -21,7 +21,7 @@ DialogTrigger serves as a wrapper around a Dialog and its associated trigger, li
 - **`placement`** `'top' | 'bottom' | 'left' | 'right' | 'top start' | 'top end' | 'bottom start' | 'bottom end' | 'left top' | 'left bottom' | 'right top' | 'right bottom'` — The placement of the dialog relative to its trigger
 - **`hideArrow`** `boolean` (default: `false`) — Whether a popover type Dialog's arrow should be hidden
 - **`mobileViewport`** `number` (default: `700`) — The screen breakpoint for the mobile type
-- **`isDismissable`** `boolean` (default: `true`) — Whether a modal type Dialog should be dismissable
+- **`isDismissable`** `boolean` (default: `true`) — Whether passive dismissal (Escape or an outside click) can close the dialog. Explicit dialog actions, such as Submit and Cancel, can still close it.
 - **`isKeyboardDismissDisabled`** `boolean` (default: `false`) — Whether pressing the escape key to close the dialog should be disabled
 - **`isOpen`** `boolean` — Whether the dialog is open (controlled)
 - **`defaultOpen`** `boolean` (default: `false`) — Whether the dialog is open by default (uncontrolled)

package/docs/components/overlays/UseDialogContainer.md

@@ -173,13 +173,14 @@ function App() {
 ### Form Dialog with Validation
 
 ```tsx
-import { useDialogContainer, DialogForm } from '@cube-dev/ui-kit';
+import { useDialogContainer, DialogForm, Form, TextInput } from '@cube-dev/ui-kit';
 
 function UserFormDialog({ onSubmit, initialData, onCancel }) {
+  const form = Form.useController({ defaultValues: initialData });
   return (
     <DialogForm
       title="User Information"
-      defaultValues={initialData}
+      form={form}
       onSubmit={onSubmit}
       onDismiss={onCancel}
       submitProps={{
@@ -189,21 +190,19 @@ function UserFormDialog({ onSubmit, initialData, onCancel }) {
         label: 'Cancel'
       }}
     >
-      <Form.Item
+      <TextInput
+        label="Name"
         name="name"
         rules={[{ required: true, message: 'Name is required' }]}
-      >
-        <TextInput label="Name" />
-      </Form.Item>
-      <Form.Item
+      />
+      <TextInput
+        label="Email"
         name="email"
         rules={[
           { required: true, message: 'Email is required' },
           { type: 'email', message: 'Please enter a valid email' }
         ]}
-      >
-        <TextInput label="Email" />
-      </Form.Item>
+      />
     </DialogForm>
   );
 }
@@ -219,11 +218,10 @@ function App() {
       onSubmit: async (values) => {
         try {
           await saveUser(values);
-          userDialog.close();
           // Show success message
         } catch (error) {
           console.error('Failed to save user:', error);
-          // Handle error - form will stay open
+          throw error; // Keep the form open and show the error
         }
       },
       onCancel: () => userDialog.close()
@@ -236,9 +234,9 @@ function App() {
       onSubmit: async (values) => {
         try {
           await createUser(values);
-          userDialog.close();
         } catch (error) {
           console.error('Failed to create user:', error);
+          throw error;
         }
       },
       onCancel: () => userDialog.close()