import {
  Canvas,
  Controls,
  Meta,
  Subtitle,
  Title,
} from '@storybook/addon-docs/blocks'
import * as ModalStories from './Modal.stories'
import { LifecycleTag, SourceLinks } from '../../docs/components'

<Meta of={ModalStories} />

<Title>Modal</Title>
<Subtitle>
  Dialog window that overlays the page and renders all content underneath inert
  until dismissed.
</Subtitle>
<SourceLinks
  links={[
    {
      label: 'Radix UI',
      href: 'https://www.radix-ui.com/primitives/docs/components/dialog',
    },
    {
      label: 'shadcn/ui',
      href: 'https://ui.shadcn.com/docs/components/dialog',
    },
  ]}
/>
<LifecycleTag variant="In Development" />
**Component type:** Primitive

<Canvas of={ModalStories.Default} sourceState="shown" />
<Controls of={ModalStories.Default} />

## When to use

Use `Modal` for actions that require the user's full attention before proceeding — confirmations, destructive actions, and multi-step flows. Use a `Drawer` or `SidePanel` when the content is supplementary and the user should still see the page. Use inline feedback (error messages, banners) for recoverable errors that don't need to block the user.

## Import

```tsx
import {
  Modal,
  ModalTrigger,
  ModalContent,
  ModalHeader,
  ModalTitle,
  ModalDescription,
  ModalBody,
  ModalFooter,
  ModalClose,
  ModalCloseButton,
} from '@chainlink/blocks'
```

## Anatomy

```tsx
<Modal>
  <ModalTrigger asChild>
    <Button>Open modal</Button>
  </ModalTrigger>
  <ModalContent>
    <ModalHeader>
      <ModalTitle>Confirm action</ModalTitle>
      <ModalDescription>This action cannot be undone.</ModalDescription>
    </ModalHeader>
    <ModalBody>Are you sure you want to continue?</ModalBody>
    <ModalFooter>
      <ModalClose asChild>
        <Button variant="secondary">Cancel</Button>
      </ModalClose>
      <Button variant="destructive">Delete</Button>
    </ModalFooter>
  </ModalContent>
</Modal>
```

## Subcomponents

- `Modal`: Root state container. Manages open/closed state.
- `ModalTrigger`: Element that opens the modal. Use `asChild` to make a `Button` the trigger.
- `ModalContent`: Main container rendered in a portal. Accepts `size` (`sm` | `default` | `lg`) and `showCloseButton` (default `true`).
- `ModalHeader`: Container for title and description. Accepts `showDivider` to add a bottom border.
- `ModalTitle`: Primary heading of the modal.
- `ModalDescription`: Supporting text below the title.
- `ModalBody`: Main scrollable content area.
- `ModalFooter`: Bottom section for action buttons. Accepts `showDivider` to add a top border.
- `ModalClose`: Primitive close element. Use `asChild` to make any element close the modal.
- `ModalCloseButton`: Styled close button. Use when `showCloseButton={false}` is set on `ModalContent` but you still want a standard close button in a custom layout.

## Examples

### Sizes

<Canvas of={ModalStories.SmallModal} sourceState="shown" />
<Canvas of={ModalStories.LargeModal} sourceState="shown" />

### With dividers

<Canvas of={ModalStories.WithDividers} sourceState="shown" />

### With description

<Canvas of={ModalStories.WithDescription} sourceState="shown" />

### Without close button

<Canvas of={ModalStories.WithoutCloseButton} sourceState="shown" />

## Related components

- `Drawer` for a panel that slides up from the bottom (swipeable on mobile)
- `Sheet` for a panel that slides in from any edge (left, right, top, bottom)
- `SidePanel` for a panel that opens from the right alongside the main content
- `Popover` for small non-blocking floating content