Dialog pattern
Dialog
Section titled “Dialog”Dialogs layer focus management, inert background locking, keyboard dismissal, and ARIA semantics on top of toggle. Whether you choose the context="dialog" syntax or the legacy data-automagica11y-dialog alias, you get identical behavior. The Contexts guide outlines how dialog fits into the wider roadmap and how other composites will inherit the same guarantees.
Guarantees
Section titled “Guarantees”- Applies
aria-haspopup="dialog"andaria-expandedto triggers. - Adds
role="dialog",aria-modal="true", andtabindex="-1"to the surface. - Moves focus inside on open and restores it to the trigger on close.
- Sets
inert+aria-hiddenon siblings while the dialog is active. - Emits
automagica11y:readyandautomagica11y:togglelifecycle events. - Forwards Escape presses to the owning toggle and restores focus to the opener on close.
Attribute reference
Section titled “Attribute reference”| Attribute | Type | Allowed values | Default | Description |
|---|---|---|---|---|
data-automagica11y-context="dialog" | string | `dialog` | N/A | Activates the dialog context with full semantics and behaviors. |
data-automagica11y-target | string | Selector | CSS selector or ID reference | Next sibling | Points at the dialog surface element. |
data-automagica11y-context-mode | `full` | `semantics` | `behaviors` | Mode tokens | `full` | Toggle between semantic-only, behavior-only, or full automation. |
data-automagica11y-dialog | string | Selector | CSS selector or ID reference | None | Legacy alias that maps directly to the dialog context. |
data-automagica11y-dialog-close | boolean attribute | `data-automagica11y-dialog-close` | N/A | Marks a button inside the surface that closes the dialog. |
Alias fidelity
Section titled “Alias fidelity”data-automagica11y-dialog is implemented as an alias to the dialog context. You can migrate incrementally without shipping different behavior.
Context dialog
Full-screen lock, focus trap, Escape dismissal.
Context dialog
Focus stays inside, background becomes inert, and Escape or the close button exits.
Alias dialog
Alias triggers reuse the same wiring. No behavior drift.
<button data-automagica11y-context="dialog" data-automagica11y-target="#dialog">Open</button><button data-automagica11y-dialog="#dialog-alias">Open alias</button>Coverage plan
Section titled “Coverage plan”- Add a walkthrough showing dialog +
initFocusInitialto focus the first actionable element after transitions. - Document how the animate lifecycle keeps exit animations running before
hiddentoggles. - Provide an example of nested dialogs or grouped triggers that share inert background locking.
Progress is tracked in the Focus utilities pattern and the Examples roadmap.