Contexts
Contexts
Section titled “Contexts”Contexts sit on top of the toggle foundation and orchestrate everything a composite pattern needs: ARIA semantics, behavioral wiring, and alias normalization. Attach a single data-automagica11y-context attribute to a toggle trigger and the registry keeps the trigger, target, and any aliases in sync.
How contexts compose with toggle
Section titled “How contexts compose with toggle”- Start with a toggle. Every context begins as a
data-automagica11y-toggletrigger connected to a target surface. - Opt into shared semantics. Add
data-automagica11y-context="dialog"(or any alias) and the registry applies the appropriate roles and ARIA attributes. - Layer behaviors on demand. Context modes decide whether to hydrate focus traps, hover intent, inert locking, and other helpers. Behaviors always piggyback on the same toggle lifecycle events that plugins use.
- Compose freely. Multiple contexts can coexist on a page. They emit namespaced events (
automagica11y:dialog:*,automagica11y:tooltip:*) so plugins and analytics stay coordinated.
Because contexts reuse toggle internally, everything you learn in the Toggle pattern applies here too: truthiness aliases, grouped triggers, and lifecycle events all behave identically.
Attribute API
Section titled “Attribute API”| Attribute | Description |
|---|---|
data-automagica11y-context | Names the context to activate (for example dialog, tooltip, menu). |
data-automagica11y-target | Selector for the managed surface. Defaults to the next sibling or the resolved ID. |
data-automagica11y-context-mode | Controls automation depth. Accepts all (default), semantics-only, or behaviors-only. |
data-automagica11y-context-alias | Override the alias mapping for bespoke vocabulary. |
all– semantics + behaviors (default).semantics-only– apply ARIA/role defaults only; wire your own behaviors.behaviors-only– reuse dismissal, focus traps, and state syncing without altering existing semantics.
Capability matrix
Section titled “Capability matrix”| Context | Semantics | Behaviors | Examples | Pattern docs |
|---|---|---|---|---|
dialog | role="dialog", aria-modal, trigger linking | Focus trap, inert siblings, Escape to close, restore focus | Context dialog | Dialog pattern |
tooltip | role="tooltip", aria-describedby wiring | Hover intent, long-press, anchor follow | Context tooltip | Tooltip pattern |
menu | role="menu" scaffolding | Behaviors planned (roving tabindex, typeahead) | Roadmap | Toggle pattern |
accordion | role="region" scaffolding | Behaviors planned | Roadmap | Toggle pattern |
disclosure | role="region" scaffolding | Behaviors planned | Roadmap | Toggle pattern |
listbox | role="listbox" scaffolding | Behaviors planned | Roadmap | Toggle pattern |
tablist | role="tablist" scaffolding | Behaviors planned | Roadmap | Toggle pattern |
tree | role="tree" scaffolding | Behaviors planned | Roadmap | Toggle pattern |
Use the matrix to decide whether a context already automates the behaviors you need or whether you should augment it with plugins today. The @core/context/registry.ts reference page lists the same capabilities at the source level.
Alias map
Section titled “Alias map”| Alias | Canonical context |
|---|---|
dropdown, kebab, meatball | menu |
modal, dialog, sheet | dialog |
details, expander, disclosure | toggle |
tooltip, hint, label | tooltip |
Aliases keep older attribute names and regional terminology working while still running through the same context pipeline.
Examples & recipes
Section titled “Examples & recipes”- Dialog quickstart – builds a dialog with context mode
all. - Context dialog example – focus trap, inert siblings, Escape dismissal.
- Context tooltip example – hover, focus, and long-press interactions.
- Truthiness aliases guide – shows how contexts share the same vocabulary.
Alias parity demos
Section titled “Alias parity demos”The legacy data-automagica11y-dialog attribute maps directly to the dialog context.
Context vs. alias
Two ways to activate the same dialog wiring.
Context dialog
Focus trapping, inert background, and Escape dismissal are included.
Alias dialog
The alias uses the same context internally, guaranteeing parity.
<button data-automagica11y-context="dialog" data-automagica11y-target="#context-dialog">Open via context</button><button data-automagica11y-dialog="#alias-dialog">Open via alias</button>Tooltips share the same alias wiring.
Context vs. tooltip alias
Context and alias both hydrate tooltip behavior.
<button data-automagica11y-context="tooltip" data-automagica11y-target="#context-tooltip">Hover me</button><button data-automagica11y-tooltip="#alias-tooltip">Alias trigger</button>Roadmap
Section titled “Roadmap”The context registry evolves alongside the core patterns. Track progress in the Examples roadmap and the Core reference:
- Menu context behaviors – roving tabindex, typeahead search, and dismissible submenus.
- Accordion & disclosure parity – share toggle grouping logic, add
aria-disabledand single-open coordination. - Listbox, tablist, and tree – mirror WAI-ARIA Authoring Practices with arrow key navigation and typeahead.
- Context capability lab – interactive demo that lets you toggle focus trap, inert siblings, hover intent, and anchor follow helpers individually.
As each milestone lands, the matrix above and the associated pattern pages will note the new capabilities.
Continue exploring
Section titled “Continue exploring”- Dive into the Dialog pattern and Tooltip pattern for behavior deep dives.
- Pair contexts with plugins like Announce to broadcast state changes to screen readers.
- Explore imperative helpers in
@core/context/helperswhen you need bespoke orchestration.