## dialog (`poetry_dialog`)

A window overlaid on the page for content that requires attention.

Class: Poetry::Ui::Dialog::Component - BEM block `poetry-ui-dialog`.
Slot REQUIRED: with_title (the accessible name) - a call without it raises.
- `content_class:` (string) - Extra classes merged onto the <dialog> panel (e.g. "max-h-[50vh]" caps a top/bottom sheet).
- `dismissible:` (boolean) - default true - Backdrop clicks close the dialog; false keeps confirmations from being dismissed accidentally (Esc still closes).
- `show_close_button:` (boolean) - default true - Renders the corner X; false forces a deliberate footer choice (footer actions and Esc remain). Sheet inherits this.
Slots: trigger (The trigger is a poetry Button wired to open the dialog - agents pass Button props: with_trigger(variant: :outline) { "Open" }.; takes poetry_button props, not a block; with_trigger yields NOTHING to the block - no |param|, write content directly), title (The heading - the dialog's accessible name; required.), description (Muted copy under the title, wired to aria-describedby.), footer (The action row at the bottom of the panel.).
- PART `dialog` - Root wrapper around the trigger and the <dialog> element
- PART `dialog-content` - The <dialog> panel - positioning, animation, and the open state ride here | states: data-open (panel is open (the controller flips the pair at runtime)); data-closed (panel is closed or animating out (the server-rendered state))
- PART `dialog-header` - Title block at the top of the panel
- PART `dialog-title` - The heading - the dialog's accessible name (required slot)
- PART `dialog-description` - Muted copy under the title, wired to aria-describedby
- PART `dialog-footer` - Action row at the bottom of the panel
- WIRING root: `poetry--core--dialog` registers; values dismissible
- WIRING content: `poetry--core--dialog` actions close on cancel, backdropClose on click; targets dialog
- WIRING trigger: `poetry--core--dialog` actions open
- WIRING close: `poetry--core--dialog` actions close
- tool open (mutating) - Open the dialog. [opt in with webmcp: "name" on the call; dispatches poetry--core--dialog#open]
- tool close (mutating) - Close the dialog. [opt in with webmcp: "name" on the call; dispatches poetry--core--dialog#close]
- RULE: with_trigger(compose: true) { |wiring| ... } composes YOUR control as the trigger: the block is yielded the trigger wiring (the Stimulus behavior the overlay needs; poppers add id/aria and their trigger slot, modals hand only the open action) - splat it onto a wiring-free control (poetry_sidebar_menu_button, a plain tag); without compose: the classic composed Button renders.
- RULE: Open dialogs with with_trigger(...) - never a hand-wired button.
- RULE: with_title is REQUIRED (the accessible name); with_description when the purpose needs explaining.
- RULE: Confirmations that must not be lost use dismissible: false (backdrop clicks stop closing).
- RULE: show_close_button: false removes the corner X - keep a footer action (Esc still closes).
- RULE: Destructive confirmations pair a destructive Button in the footer - never auto-submit.