# Dialog

> Overlay for tasks or information requiring focused attention

- Tier: composition
- Storybook: `Components/Dialog`
- Import: `import { Dialog } from '@amezquita/design-system/components/composition/Dialog'`

## Props

| Prop | Type | Description |
|---|---|---|
| `open?` | `boolean \| never` |  |
| `onOpenChange?` | `(open: boolean) => void \| never` |  |
| `defaultOpen?` | `never \| boolean` |  |
| `trigger?` | `React.ReactElement` | Must be a single DOM element — React.Fragment is not supported (Radix asChild). |
| `triggerRef?` | `React.Ref<HTMLButtonElement>` | Optional external ref onto the trigger's DOM node, merged with Dialog's own internal one. Useful when a consumer needs the trigger element for something beyond this Dialog's own lifecycle — e.g. restoring focus there after a separate follow-up AlertDialog (opened once this Dialog has already closed) finishes. Dialog's own focus-restore-on-close (modal={false} case) keeps working unaffected either way. |
| `title` | `string` |  |
| `description?` | `string` |  |
| `children` | `React.ReactNode` |  |
| `footer?` | `React.ReactNode` |  |
| `size?` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  |
| `scrollable?` | `boolean` |  |
| `modal?` | `boolean` |  |
| `onPointerDownOutside?` | `(e: Event) => void` | Call e.preventDefault() to prevent the dialog from closing on outside click. |
| `onEscapeKeyDown?` | `(e: KeyboardEvent) => void` | Call e.preventDefault() to prevent the dialog from closing on Escape key. |

## Tokens

| Token | Type | Value |
|---|---|---|
| `--dialog-close-size` | dimension | `28px` |
| `--dialog-entrance-offset` | dimension | `8px` |
| `--dialog-max-width` | dimension | `560px` |
| `--dialog-max-width-lg` | dimension | `720px` |
| `--dialog-max-width-sm` | dimension | `480px` |
| `--dialog-max-width-xl` | dimension | `1024px` |

## Usage example

```tsx
<Dialog
  trigger={<Button>Open dialog</Button>}
  title="Confirm action"
  description="This action cannot be undone. Are you sure you want to continue?"
  footer={
    <>
      <Button variant="ghost">Cancel</Button>
      <Button variant="primary">Confirm</Button>
    </>
  }
>
  <p style={{ margin: 0, fontSize: 'var(--font-size-body)', color: 'var(--color-text-secondary)', lineHeight: 'var(--line-height-body)' }}>
    Proceeding will permanently delete the selected items from your account.
  </p>
</Dialog>
```

## Accessibility

- Built on `@radix-ui/react-dialog` — do not replace the Radix primitive
- Focus trap: Radix handles this; do not disable it
- `Escape` closes the dialog; do not override
- `RadixDialog.Title` provides the accessible name automatically — always pass `title` prop
- Return focus to the trigger element on close (Radix default behaviour)