# 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

### Base Properties

Supports [Base properties](../../BaseProperties.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:

- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
- **Flow:** `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`

### Modifiers

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

## 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](./AlertDialog.md) - Specialized component for alert scenarios
