# 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](../../BaseProperties.md)

### Styling Properties

DialogContainer has no styling capabilities.

### 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`

## 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
