# Dialog

Enhance an authored native dialog with focus management. (Custom element.)

Reference: https://timeless.build/docs/components/dialog/

> **Markup you author.** The trigger and the close buttons carry `command` and `commandfor`, so the dialog opens, closes, and reports a `returnValue` before any script runs. Those attributes are yours to write: Timeless reads them and leaves the invocation to the platform, because a generated `commandfor` would only work once the bundle had loaded. Give the `<dialog>` an explicit `id` for them to name — an invoker cannot reference a generated one. Where [Invoker Commands](/docs/reference/browser-support/) are missing, the component falls back to a click listener that does the same work, so the same markup is correct in every browser.

## Markup

```html
<ui-dialog>
  <button class="ui-button" data-ui-part="trigger" type="button" command="show-modal" commandfor="release-dialog">Open dialog</button>
  <dialog id="release-dialog" aria-labelledby="release-dialog-title" aria-describedby="release-dialog-description">
    <header>
      <h2 data-ui-part="title" id="release-dialog-title">Publish release?</h2>
      <p data-ui-part="description" id="release-dialog-description">Confirm the public package.</p>
    </header>
    <section>
      <p>Package checks have passed.</p>
    </section>
    <footer>
      <button class="ui-button" data-ui-variant="secondary" data-ui-part="close" type="button" command="close" commandfor="release-dialog" value="cancel">Cancel</button>
      <button class="ui-button" data-ui-part="close" type="button" command="close" commandfor="release-dialog" value="confirm">Confirm</button>
    </footer>
  </dialog>
</ui-dialog>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/dialog.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/dialog.css'
import '@timelessui/components/register/ui-dialog'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineDialogElement } from '@timelessui/components/define/ui-dialog'
defineDialogElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Native button that opens the dialog. Add `command="show-modal"` and `commandfor` naming the panel id to open it from markup, before any script runs. Timeless reads those attributes and stands down; it never writes them, because a generated attribute would only work once the bundle had loaded. |
| `panel` | Yes | `dialog` | The native `<dialog>` element. Author it, do not generate it. Give it an explicit `id` when a trigger or close button invokes it, since an invoker can only name an id the author wrote. |
| `close` | No | `[data-ui-part~='close']` | Optional explicit close button inside the panel. Add `command="close"` and `commandfor` to close it from markup; the platform then also copies the button `value` into `returnValue`. |
| `title` | No | `[data-ui-part~='title'], header > :where(h1, h2, h3)` | Names the dialog. Timeless points the panel's `aria-labelledby` at it, generating an id only if you left one off. A heading in the panel `<header>` counts without the token. An `aria-labelledby` you author always wins. |
| `description` | No | `[data-ui-part~='description'], header > p` | Supporting line under the title, wired with `aria-describedby` the same way. A `<p>` in the panel `<header>` counts without the token. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `kind` | `dialog` · `alert` | `dialog` | Whether the panel is a regular dialog or an alert dialog. `alert` resolves to `role="alertdialog"`, for a destructive confirmation the user must answer. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-dialog>`

| Property | Type | Notes |
| --- | --- | --- |
| `kind` | `'dialog' | 'alert'` | Reflects the `kind` attribute |

This element dispatches no component events.

## Styling

Root identity: `ui-dialog`.
Required stylesheets: `tokens.css`, `core/dialog.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/dialog.css`.

This component adds no custom properties of its own. Restyle it through the design tokens at https://timeless.build/docs/styling/theming/ or your own CSS.

Design tokens this component reads (30), global and set at the theme level: `--ui-accent`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-subtle`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4`, `--ui-space-5`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Modal Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Escape` | Close the dialog. Handled by the native `<dialog>` element, not by Timeless. |

Focus trapping, the backdrop, and the top layer all come from `showModal()`. Timeless moves initial focus into the panel and returns it to the trigger on close, and names the panel from its `title` and `description` parts. A dialog invoker gets no implicit `aria-expanded` from the platform, so Timeless keeps writing it on both the authored-command and click paths.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.