@cube-dev/ui-kit 0.0.0-canary-c210a8c → 0.0.0-canary-60981ef

package/docs/components/overlays/Dialog.md

@@ -0,0 +1,202 @@
+# Dialog
+
+Dialogs are windows containing contextual information, tasks, or workflows that appear over the user interface. Depending on the kind of Dialog, further interactions may be blocked until the Dialog is acknowledged.
+
+## When to Use
+
+- Display important information or actions that require user attention
+- Confirm or cancel user actions before proceeding
+- Collect user input in a focused, contextual interface
+- Show complex workflows or forms that need dedicated space
+- Present alerts or notifications that require user acknowledgment
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** — Dialog content (Header, Content, Footer, etc.)
+- **`size`** `'small' | 'medium' | 'large' | 'S' | 'M' | 'L'` (default: `S`) — Dialog size
+- **`styles`** — Custom styles for the dialog root
+- **`closeButtonStyles`** — Custom styles for the close button
+- **`isDismissable`** `boolean` (default: `false`) — Whether the dialog is dismissable (shows close button, allows Escape key)
+- **`onDismiss`** `function` — Callback fired when the dialog is dismissed
+- **`closeIcon`** — Custom close icon element
+- **`role`** `'dialog' | 'alertdialog'` (default: `dialog`) — ARIA role for the dialog
+- **`onBlur`** `function` — Callback fired when the dialog loses focus
+- **`onFocus`** `function` — Callback fired when the dialog receives focus
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the dialog.
+
+**Sub-elements:**
+- `Dialog` - The main dialog container
+- `Content` - The content area wrapper
+- `Header` - The header section wrapper
+- `Footer` - The footer section wrapper
+
+#### closeButtonStyles
+
+Customizes the close button appearance.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop: `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `reset`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `opacity`, `overflow`, `scrollbar`, `hide`, `outline`, `textAlign`, `resize`.
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| dismissable | `boolean` | Applied when the dialog can be dismissed with close button or Escape key |
+
+## Variants
+
+### Types
+
+- `dialog` - Standard dialog for general content (default)
+- `alertdialog` - Alert dialog for critical notifications or confirmations
+
+### Sizes
+
+- `small` / `S` - Compact dialog for simple content (360px width)
+- `medium` / `M` - Standard dialog for moderate content (479px width)
+- `large` / `L` - Large dialog for complex content (798px width)
+
+## Examples
+
+### Basic Dialog
+
+```jsx
+<Dialog>
+  <Header>
+    <Title>Dialog Title</Title>
+  </Header>
+  <Content>
+    <Paragraph>Dialog content goes here.</Paragraph>
+  </Content>
+  <Footer>
+    <Button onPress={close}>Close</Button>
+  </Footer>
+</Dialog>
+```
+
+### Dismissable Dialog
+
+```jsx
+<Dialog isDismissable onDismiss={close}>
+  <Header>
+    <Title>Dismissable Dialog</Title>
+  </Header>
+  <Content>
+    <Paragraph>You can close this dialog with the close button or Escape key.</Paragraph>
+  </Content>
+</Dialog>
+```
+
+### Custom Size Dialog
+
+```jsx
+<Dialog size="large">
+  <Header>
+    <Title>Large Dialog</Title>
+  </Header>
+  <Content>
+    <Paragraph>This dialog uses the large size variant.</Paragraph>
+  </Content>
+</Dialog>
+```
+
+### Alert Dialog
+
+```jsx
+<Dialog role="alertdialog">
+  <Header>
+    <Title>Confirm Action</Title>
+  </Header>
+  <Content>
+    <Paragraph>Are you sure you want to delete this item? This action cannot be undone.</Paragraph>
+  </Content>
+  <Footer>
+    <Button type="danger" onPress={confirmDelete}>Delete</Button>
+    <Button onPress={close}>Cancel</Button>
+  </Footer>
+</Dialog>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus between interactive elements within the dialog
+- `Shift + Tab` - Moves focus backward between interactive elements
+- `Escape` - Dismisses the dialog if `isDismissable` is true
+- `Enter/Space` - Activates focused buttons or interactive elements
+
+### Screen Reader Support
+
+- Dialog announces as "dialog" or "alertdialog" based on role
+- Focus is trapped within the dialog when open
+- Focus returns to the trigger element when dialog closes
+- Dialog title and content are properly announced
+- State changes and actions are communicated to screen readers
+
+### ARIA Properties
+
+- `aria-labelledby` - Links dialog to its title element automatically
+- `aria-describedby` - Links dialog to its description content
+- `aria-modal` - Set to true for modal dialogs to indicate exclusive interaction
+- `role` - Set to "dialog" or "alertdialog" based on content type
+
+## Best Practices
+
+1. **Do**: Provide clear titles and actionable buttons
+   ```jsx
+   <Dialog>
+     <Header>
+       <Title>Save Changes</Title>
+     </Header>
+     <Content>
+       <Paragraph>Your changes will be saved to the document.</Paragraph>
+     </Content>
+     <Footer>
+       <Button type="primary" onPress={save}>Save</Button>
+       <Button onPress={close}>Cancel</Button>
+     </Footer>
+   </Dialog>
+   ```
+
+2. **Don't**: Use dialogs for trivial notifications
+   ```jsx
+   {/* Avoid using dialogs for simple success messages */}
+   <Dialog>
+     <Content>Item saved!</Content>
+   </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
+
+## Integration with Overlays
+
+Dialog is typically used within `DialogTrigger` or `Modal` components for proper overlay management and positioning. It should not be rendered directly without an overlay container.
+
+## Suggested Improvements
+
+- Enhancement 1: Add support for custom dialog animations and transitions
+- Enhancement 2: Implement automatic focus management for complex form scenarios
+
+## Related Components
+
+- [DialogTrigger](./DialogTrigger.md) - Manages dialog open/close state and positioning
+- AlertDialog - Specialized component for alert scenarios

package/docs/components/overlays/DialogContainer.md

@@ -0,0 +1,201 @@
+# DialogContainer
+
+A DialogContainer accepts a single Dialog as a child, and manages to show and hide it in a modal. Useful in cases where there is no trigger element or when the trigger unmounts while the dialog is open.
+
+## When to Use
+
+- When you need to display a dialog without a specific trigger element
+- To prevent dialog closure when the trigger component unmounts
+- For programmatically controlled dialogs in complex application flows
+- When managing dialog state externally from the component hierarchy
+- For dialogs that need to persist across route changes or component updates
+
+## Component
+
+---
+
+### Properties
+
+- **`children`** — The Dialog to display, if any
+- **`type`** `'modal' | 'fullscreen' | 'fullscreenTakeover' | 'panel'` (default: `modal`) — The type of Dialog that should be rendered
+- **`isDismissable`** `boolean` (default: `false`) — Whether the Dialog is dismissible
+- **`isKeyboardDismissDisabled`** `boolean` (default: `false`) — Whether pressing the escape key to close the dialog should be disabled
+- **`isOpen`** `boolean` — Whether the modal is open or not
+- **`onDismiss`** `function` — Handler called when the x button of a dismissible Dialog is clicked
+- **`hideOnClose`** `boolean` (default: `false`) — Whether the dialog should be hidden when closed
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.md)
+
+### Styling Properties
+
+DialogContainer has no styling capabilities.
+
+## Variants
+
+### Types
+
+- `modal` - Standard modal dialog with backdrop (default)
+- `fullscreen` - Takes up entire screen with padding
+- `fullscreenTakeover` - Fullscreen without padding
+- `panel` - Side panel overlay
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<DialogContainer isOpen={isDialogOpen} onDismiss={() => setIsDialogOpen(false)}>
+  <Dialog>
+    <Header>
+      <Title>Dialog Title</Title>
+    </Header>
+    <Content>
+      <Paragraph>Dialog content goes here.</Paragraph>
+    </Content>
+  </Dialog>
+</DialogContainer>
+```
+
+### Controlled Dialog
+
+```jsx
+function ControlledDialogExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button onPress={() => setIsOpen(true)}>Open Dialog</Button>
+      <DialogContainer
+        isOpen={isOpen}
+        isDismissable
+        onDismiss={() => setIsOpen(false)}
+      >
+        <Dialog>
+          <Header>
+            <Title>Controlled Dialog</Title>
+          </Header>
+          <Content>
+            <Paragraph>This dialog is controlled externally.</Paragraph>
+          </Content>
+          <Footer>
+            <Button onPress={() => setIsOpen(false)}>Close</Button>
+          </Footer>
+        </Dialog>
+      </DialogContainer>
+    </>
+  );
+}
+```
+
+### Conditional Dialog
+
+```jsx
+function ConditionalDialog() {
+  const [showDialog, setShowDialog] = useState(false);
+  const [dialogContent, setDialogContent] = useState(null);
+
+  const openDialog = (content) => {
+    setDialogContent(content);
+    setShowDialog(true);
+  };
+
+  return (
+    <DialogContainer isOpen={showDialog} onDismiss={() => setShowDialog(false)}>
+      {dialogContent && (
+        <Dialog>
+          <Header>
+            <Title>Dynamic Dialog</Title>
+          </Header>
+          <Content>
+            {dialogContent}
+          </Content>
+        </Dialog>
+      )}
+    </DialogContainer>
+  );
+}
+```
+
+### Non-dismissable Dialog
+
+```jsx
+<DialogContainer isOpen={isOpen} isDismissable={false}>
+  <Dialog>
+    <Header>
+      <Title>Important Notice</Title>
+    </Header>
+    <Content>
+      <Paragraph>This dialog requires user action to close.</Paragraph>
+    </Content>
+    <Footer>
+      <Button type="primary" onPress={handleAction}>
+        Take Action
+      </Button>
+    </Footer>
+  </Dialog>
+</DialogContainer>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus between interactive elements within the dialog
+- `Shift + Tab` - Moves focus backward between interactive elements
+- `Escape` - Closes the dialog if `isDismissable` is true and `isKeyboardDismissDisabled` is false
+
+### Screen Reader Support
+
+- Dialog announces as "dialog" to screen readers
+- Focus is trapped within the dialog when open
+- Focus management is handled automatically
+- Modal state is properly communicated to assistive technologies
+
+### ARIA Properties
+
+- `aria-modal` - Set to true to indicate modal behavior
+- `aria-labelledby` - Links dialog to its title automatically
+- `aria-describedby` - Links dialog to its description content
+- `role` - Set to "dialog" for proper semantic meaning
+
+## Best Practices
+
+1. **Do**: Use DialogContainer for dialogs without specific triggers
+   ```jsx
+   <DialogContainer isOpen={showErrorDialog} onDismiss={clearError}>
+     <Dialog>
+       <Header>
+         <Title>Error</Title>
+       </Header>
+       <Content>
+         <Paragraph>{errorMessage}</Paragraph>
+       </Content>
+     </Dialog>
+   </DialogContainer>
+   ```
+
+2. **Don't**: Use DialogContainer when DialogTrigger is more appropriate
+   ```jsx
+   {/* Prefer DialogTrigger when you have a specific trigger */}
+   <DialogContainer isOpen={buttonPressed}>
+     <Dialog>...</Dialog>
+   </DialogContainer>
+   ```
+
+3. **State Management**: Always control the `isOpen` state externally
+4. **Single Child**: Only pass one Dialog as a child to DialogContainer
+5. **Cleanup**: Ensure proper cleanup of dialog state when component unmounts
+
+## Suggested Improvements
+
+- Enhancement 1: Add support for dialog stacking and z-index management
+- Enhancement 2: Implement automatic focus restoration after dialog closes
+- Enhancement 3: Add support for custom backdrop click behavior
+
+## Related Components
+
+- [DialogTrigger](./DialogTrigger.md) - Use when you have a specific trigger element
+- [Dialog](./Dialog.md) - The content component used within DialogContainer
+- [Button](../actions/Button.md) - Common element for dialog actions

package/docs/components/overlays/DialogForm.md

@@ -0,0 +1,290 @@
+# 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.
+
+**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`.
+
+## 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
+
+## Component
+
+---
+
+### Properties
+
+### DialogForm-specific Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `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` | Preserve form values after submission/dismissal (default: false) |
+| `noActions` | `boolean` | Hide default action buttons to manually specify them |
+
+### Inherited Properties
+
+DialogForm inherits all properties from:
+- **[Dialog](./Dialog.md)**: `size`, `isDismissable`, `closeIcon`, styling properties, etc.
+- **[Form](../form/Form.md)**: `name`, `defaultValues`, `onSubmit`, `onSubmitFailed`, `onValuesChange`, `labelPosition`, `requiredMark`, validation properties, etc.
+
+See the respective component documentation for complete property lists.
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.md)
+
+## Examples
+
+### Basic DialogForm (Recommended)
+
+Using `useDialogContainer` for programmatic control:
+
+```jsx
+import { useDialogContainer, DialogForm, Input, Button } from '@cube-dev/ui-kit';
+
+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>
+  );
+}
+
+function App() {
+  const userDialog = useDialogContainer(UserFormDialog);
+
+  const openDialog = () => {
+    userDialog.open({
+      initialData: { name: '', email: '' },
+      onSubmit: async (data) => {
+        await saveUser(data);
+        userDialog.close();
+      }
+    });
+  };
+
+  return (
+    <>
+      <Button onPress={openDialog}>Add User</Button>
+      {userDialog.rendered}
+    </>
+  );
+}
+```
+
+### 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>
+```
+
+### 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>
+```
+
+### Custom Actions with Access to Dismiss
+
+When you need custom action buttons, use `noActions` prop and the render function pattern:
+
+```jsx
+<DialogForm
+  title="Advanced Form"
+  noActions
+  onSubmit={handleSubmit}
+>
+  {(dismiss) => (
+    <>
+      <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>
+    </>
+  )}
+</DialogForm>
+```
+
+### Preserving Form Values
+
+Use `preserve` prop to keep form values when reopening the dialog:
+
+```jsx
+<DialogForm
+  title="Edit Draft"
+  preserve
+  defaultValues={draftData}
+  onSubmit={saveDraft}
+>
+  <Input.Text name="title" label="Title" />
+  <TextArea name="content" label="Content" />
+</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
+
+### 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
+
+- **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
+
+## 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}>
+   ```
+
+## 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 - For simple confirmations without forms
+