@cube-dev/ui-kit 0.181.0 → 0.183.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/overlays/Dialog.md

@@ -55,6 +55,32 @@ These properties allow direct style application without using the `styles` prop:
 - **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
 - **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
+### Padding Tokens
+
+`Dialog` declares its own gutters as custom properties on the dialog root, so every slot inside it — `Header`, `Content`, `Footer` — resolves the same values. They are part of the public contract and safe to read from a consumer's own styles:
+
+| Token | Default | `type="popover"` | What it measures |
+| --- | --- | --- | --- |
+| `$dialog-padding-h` | `1.5x` | `1x` | Horizontal gutter on every slot |
+| `$dialog-content-padding-v` | `1.5x` | `1x` | `Content`'s vertical padding |
+| `$dialog-title-padding-v` | `1.5x` | `1x` | `Header`'s vertical padding |
+| `$dialog-footer-v` | `1.5x` | `1x` | `Footer`'s vertical padding |
+
+The case this exists for is a child that should span the full dialog width — an edge-to-edge table or divider — while its siblings keep the gutter. Take `Content`'s horizontal padding back and hand the same value to the siblings:
+
+```jsx
+<Dialog>
+  <Content styles={{ padding: '$dialog-content-padding-v 0' }}>
+    <Paragraph styles={{ padding: '0 $dialog-padding-h' }}>
+      Keeps the dialog's gutter.
+    </Paragraph>
+    <FullWidthTable />
+  </Content>
+</Dialog>
+```
+
+A `styles` override on a slot is merged into the slot's own styles rather than replacing them, so `Content` keeps its `flexGrow`, `overflow` and height rules while only the padding changes. In plain CSS the same values are readable as `var(--dialog-padding-h)` and `var(--dialog-content-padding-v)`.
+
 ### Modifiers
 
 The `mods` property accepts the following modifiers you can override:

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,110 @@ 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
+- 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()

package/docs/modern-form-guide.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/modern-form-migration.md

@@ -31,7 +31,7 @@ The following API mapping describes migration choices; names are not mechanicall
 | `submit()` | `submit()` returns a tagged result such as `submitted`, `invalid`, or `failed` |
 | `Form.Item` wrapping a custom control | `useFieldProps` plus `wrapWithField` inside that control |
 
-`DialogForm` and Cloud's `NarrowForm` / `SaveableCard` currently expose legacy instance contracts. Keep their callers legacy until the wrapper itself is migrated and verified. Passing a modern controller through a cast does not migrate the wrapper. `Form.Item`, legacy mutable flags, and the legacy `FormContext` instance shape remain compatibility APIs.
+`DialogForm` supports both implementations. Pass a modern controller, move defaults to its creation options, and review dismissal/reset behavior: modern dialogs cancel pending submission and reset when the editing session ends unless `preserve` is set. Keep the controller outside the dialog when preserving drafts across unmounts. Cloud's `NarrowForm` / `SaveableCard` still expose legacy instance contracts; keep their callers legacy until those wrappers are migrated and verified. Passing a modern controller through a cast does not migrate the wrapper. `Form.Item`, legacy mutable flags, and the legacy `FormContext` instance shape remain compatibility APIs.
 
 ## Review the behavior changes