# <aihio-dialog>

A modal dialog for a focused task or a confirmation before an irreversible action, such as deleting a project. Opens and closes from markup: commandfor plus command="--open" or command="--close".

Intents: `overlay`, `modal`, `dismissible`.

## Attributes

- `open` (boolean): Whether the dialog is open. Default: `false`.

## Methods

- `open()`: Opens the dialog modally in the browser top layer.
- `close()`: Requests that the dialog close.

## Events

- `aihio-open`: Fired after the dialog opens.
- `aihio-close` (detail: reason: string): Fired after the dialog closes.
- `aihio-before-close` (detail: reason: string): Cancelable request fired before the dialog closes.

## Commands

- `--open`: Opens the dialog modally. Focus returns to the invoking button when it closes.
- `--close`: Requests that the dialog close, with reason "command"; aihio-before-close can still cancel it.
- `--toggle`: Opens the dialog when it is closed and closes it when it is open.

## <aihio-dialog-header>

Dialog header container.

## <aihio-dialog-title>

Dialog title text.

## <aihio-dialog-description>

Dialog description text.

## <aihio-dialog-footer>

Dialog footer with actions.

## Accessibility obligations

- (error, dialog-accessible-name) When dialog has no aihio-dialog-title: Provide aria-label on aihio-dialog describing the dialog's purpose; otherwise screen readers announce an unnamed dialog.
- (warn) When dialog confirms a destructive action: Label the confirming button with variant="destructive" and keep Cancel as the first focusable control.

## Examples

### Confirm a destructive action

Opened and closed from markup. Submitting the form closes it.

```html
<aihio-button commandfor="confirm-delete" command="--open" variant="destructive">Delete project</aihio-button>

<aihio-dialog id="confirm-delete">
  <aihio-dialog-header>
    <aihio-dialog-title>Are you sure?</aihio-dialog-title>
    <aihio-dialog-description>This action cannot be undone.</aihio-dialog-description>
  </aihio-dialog-header>
  <form method="post">
    <aihio-dialog-footer>
      <aihio-button commandfor="confirm-delete" command="--close" variant="outline">Cancel</aihio-button>
      <aihio-button type="submit" variant="destructive">Delete</aihio-button>
    </aihio-dialog-footer>
  </form>
</aihio-dialog>
```

## Mistakes

### Missing header and footer. Provide aihio-dialog-title for a name and aihio-dialog-footer for actions.

Don't (aihio lint: dialog-accessible-name):

```html
<aihio-dialog open><p>Delete?</p></aihio-dialog>
```

Do:

```html
<aihio-dialog id="delete-project-dialog">
  <aihio-dialog-header>
    <aihio-dialog-title>Delete project?</aihio-dialog-title>
  </aihio-dialog-header>
  <aihio-dialog-footer>
    <aihio-button commandfor="delete-project-dialog" command="--close" variant="outline">Cancel</aihio-button>
    <aihio-button variant="destructive">Delete</aihio-button>
  </aihio-dialog-footer>
</aihio-dialog>
```

### Dialogs must not be nested. Close the current dialog before opening another.

Don't (aihio lint: invalid-child):

```html
<aihio-dialog><aihio-dialog><p>Nested</p></aihio-dialog></aihio-dialog>
```

Do:

```html
<aihio-dialog id="first-step" aria-label="Step 1"><p>Step 1</p></aihio-dialog>
<aihio-dialog id="second-step" aria-label="Step 2"><p>Step 2</p></aihio-dialog>
```

### Built-in commands such as show-modal only act on a native <dialog>, and this one is inside the component's shadow root, so nothing happens. Use command="--open".

Don't (aihio lint: invalid-command):

```html
<aihio-button commandfor="confirm" command="show-modal">Delete</aihio-button>
<aihio-dialog id="confirm" aria-label="Confirm delete"></aihio-dialog>
```

Do:

```html
<aihio-button commandfor="confirm" command="--open">Delete</aihio-button>
<aihio-dialog id="confirm" aria-label="Confirm delete"><p>Delete this project?</p></aihio-dialog>
```