@poetry/controllers API

@poetry/controllers - poetry's Stimulus controllers + DOM helpers, one source shipped over two channels: importmap-first (the engine pins this tree; zero build) and this same tree as the npm package for esbuild / Vite / jsbundling hosts. Never requires a bundler.

The controllable-state controller: seeds the data-open/ data-closed pair from a Value default when no other layer owns it, and exposes toggle/open/close actions. "Controlled vs uncontrolled" is just which layer wrote the attribute - a server re-render, the URL, an Outlet, or this default - the controller code is identical either way.

Optional reflection targets (the Collapsible contract): a trigger target mirrors aria-expanded; a content target rides the presence helper (the pair flip deferred through animationend, hidden applied only after the exit animation finishes).

Targets: content, trigger

Values: state (String, default: "closed")

The native-dialog primitive: borrow the PLATFORM overlay - showModal() gives the focus trap, Esc handling, top-layer stacking, and focus return for free; this controller adds what the platform doesn't: the data-open/data-closed pair for CSS variants, backdrop-click dismissal, a body scroll-lock, and the presence-hold close - exit flips the pair to data-closed and HOLDS the dialog through its CSS exit animation before the native close() (synchronous when no exit animation applies, so reduced-motion and unthemed hosts close instantly). Consumed by Dialog (and AlertDialog / CommandDialog / Sheet).

Targets: dialog

Values: dismissible (Boolean, default: true); hotkey (String, default: "")

The anchored-positioning primitive: one controller over the VENDORED @floating-ui/dom. A fixed middleware pipeline - offset -> shift -> flip (both gated on avoidCollisions) -> size -> arrow (when an arrow target exists) -> hide - and a fixed output contract: data-side / data-align mirror the RESOLVED placement (after flip), and the content gets the sizing CSS vars (--transform-origin / -available-width / -available-height / -anchor-width / -anchor-height) so ported Tailwind classes like data-[side=top]:slide-in-from-bottom-2 and max-h-[var(--available-height)] work unchanged.

The Arrow stays a markup primitive: any [data-slot=popper-arrow] marked as the arrow target is positioned + given data-side here; the SVG itself is poetry-ui's business.

VIRTUAL-ANCHOR mode (the ContextMenu contract): a non-empty anchorPoint value - canonically the data-poetry--core--popper-anchor-point="x,y" attribute on the controller root (the DOM is the store) - floats against a floating-ui VirtualElement: a zero-size rect at (x,y) client coords. The resolved ELEMENT anchor rides along as contextElement so autoUpdate still tracks ancestor scroll/resize. setAnchor(x, y) is the ergonomics wrapper ContextMenu calls from its contextmenu / long-press handlers; clearing the value returns to plain element anchoring.

Consumers: Popover, Dropdown/Context Menu, Tooltip, HoverCard, Select, Combobox, Menubar.

Targets: anchor, arrow, content

Values: anchor (String, default: ""); anchorPoint (String, default: ""); side (String, default: "bottom"); align (String, default: "center"); sideOffset (Number, default: 0); alignOffset (Number, default: 0); avoidCollisions (Boolean, default: true); strategy (String, default: "fixed")

The dismissal layer: Escape + pointerdown-outside for every overlay. This controller NEVER removes DOM - it dispatches "dismiss" and the consumer closes itself (removes the node, collapses a disclosure, navigates a frame). The class-level stack makes Esc topmost-only, so stacked overlays peel one at a time.

Values: disableOutsidePointerEvents (Boolean, default: false)

Events: poetry--core--dismissable:dismiss, poetry--core--dismissable:interact-outside

The overlay focus scope: traps Tab/Shift+Tab within the subtree, loops at the edges, and - the part to get exact - snapshots document.activeElement on connect and RESTORES it on disconnect (focus return). Backs Dialog-family overlays, Popover, Menus, Select, Command.

Listeners are wired here, not as data-actions: pause/resume must attach and detach them dynamically as scopes stack, which data-action cannot do.

Values: trapped (Boolean, default: true); loop (Boolean, default: true)

Events: poetry--core--focus-scope:mount-auto-focus, poetry--core--focus-scope:unmount-auto-focus

The roving-tabindex engine: the group is ONE Tab stop - exactly one item holds tabindex=0, the rest -1, and arrow keys move focus among the collection items in DOM order. Orientation gates which arrows are live (horizontal flips Left/Right under RTL via the direction helper); Home/End jump to the edges; loop wraps. Backs Tabs, Toolbar, RadioGroup, Menus, ToggleGroup, and the Select/Command list.

Dynamic items: NAVIGATION recomputes the collection on every keydown (the DOM is the registry - always fresh, zero bookkeeping), but that alone is not correct: an item appended between keystrokes would sit at its natural tabindex and grow the group a SECOND Tab stop before any arrow is pressed. The MutationObserver exists for that one job - re-stamping the roving tabindex the moment items enter or leave.

Values: orientation (String, default: "vertical"); loop (Boolean, default: true); manageTabindex (Boolean, default: true)

Events: poetry--core--roving-focus:entry

The controllable-state convention (the DOM is the store): runtime state is a set of presence-boolean data attributes - written here, styled by CSS variants (data-open:..., via the vendored bridge variants that also match the older data-state="open|closed" value form), owned by whichever layer set it (a Stimulus Value default, the DOM, the URL, or a server re-render).

Keys are PAIRS (or triples): setting one member writes its attribute and removes its counterparts. The negative popup/panel/pressed/selected keys only remove, deliberately: there is no data-popup-closed - absence IS the state.

Presence: the mount/unmount animation convention - a helper, not a controller (no element ownership here). Exit flips the pair to data-closed and HOLDS the node in the DOM until its CSS exit animation / transition finishes, then hands removal back to the caller via onRemove (this module never removes DOM); enter just flips the pair to data-open so the data-open: animation runs. State writes go through setState so poetry:state-change fires like every other state flip.

The portal-on-open mechanism: move popper content to a stable container (body by default) while open so it can position absolute - static under compositor scroll, immune to transformed ancestors - and return it HOME on close, exactly where a placeholder comment marks the origin.

THE EVENT BRIDGE (the logical-tree trap): a component-tree portal re-bubbles events from its logical position; a DOM portal does not. A host's data-action on the component ROOT would go deaf to events rising out of portaled content. The bridge restores logical-tree bubbling for poetry's OWN

The announce SINGLETON: shared screen-reader live regions - a plain module, not a controller. Injecting a node that IS a live region is unreliably announced across SR/browser pairs (the region must exist BEFORE its text changes), so consumers keep their own nodes aria-live=off and route announcements through here: TWO lazily-created sr-only regions on body (polite + assertive), refcounted via acquire()/release() (regions removed when the last consumer releases; consumers: Toast, async form status, Combobox result counts - API changes after Toast ships are breaking, so the surface stays exactly this).

Announcement mechanics: clear-then-set on a microtask (identical consecutive messages re-announce), a per-region message queue with a small gap between messages, textContent ONLY (live-region injection is a real sink - never innerHTML).

Tab-visibility muting: while the tab is hidden both regions flip aria-live=off (muted); announcements made while hidden keep at most the LAST message, flushed on return (no backlog flood).

The mobile breakpoint: matchMedia below Tailwind's md (768px), with a change listener. The first poetry consumer is the Sidebar's mobile-Sheet mode. Environments without matchMedia (the dommy QuickJS engine, bare jsdom) report DESKTOP - the server-rendered desktop shell is the safe default.

The DOM is the registry: collection items are read from the document in DOM order - no client-side bookkeeping, no registration step; a membership question is always a fresh query.

Reading direction: the platform mechanism - the closest [dir] ancestor - consumed by roving-focus (Left/Right flip) and popper (side flip).

Capture-phase Escape handling: the primitive under dismissable's topmost-only Esc behavior.

The Command filter spec: deterministic substring + a 5-band rank - deliberately NOT a fuzzy command-score. Pure string functions so the CI spec table pins the contract: any scoring change is a reviewed table change, never a silent reorder of every palette. The score's ONLY job is picking the auto-highlighted first match - the controller hides score-0 items and NEVER reorders the DOM (DOM order is the ranking authority within a band).

Bands: prefix 4 > word-boundary 3 > substring 2 > keyword 1 > hidden 0; an empty query scores 1 (everything visible). Matching is diacritic-folded ("creme" matches "Crème") and case-insensitive.

Focus guards: two visually-hidden tabindex=0 sentinels at the body edges so focusin/focusout fire predictably at the document boundary while any trapped overlay is open - a Tab out of the last real element lands on a guard (which focus-scope yanks back), never on nothing. Refcounted module state: one pair per page no matter how many overlays.

The hotkey descriptor grammar, extracted from the dialog controller so any surface can speak it (the generic hotkey controller, future data-hotkey affordances). "meta+k" / "ctrl+shift+p": '+'-separated modifiers plus one final key token, matched exactly - unlisted modifiers must be UP, so plain typing never triggers. "meta" matches metaKey OR ctrlKey (⌘K on mac, ^K elsewhere - the command-palette convention).

The composed-DOM duplicate-id tripwire: the ONLY check that sees the page as actually composed - static lints can't see across templates, frames, streams, or cached fragments, so this scans the live document for duplicate [id] values after every composition event and reports what it finds. Development tooling: install via poetry_id_integrity_script (dev layouts); never wired in production.

Duplicate ids are always a bug regardless of source (ARIA IDREFs resolve to the first match only), and under StableId they are the signature of the two documented hazards: the same key rendered twice, or sequence-mode collisions across frames/cached fragments.

The nullable-segment date/time value (the IncompleteDate model, adapted from an Apache-2.0-licensed source - source and license in THIRD_PARTY_NOTICES.md): segments are stored RAW so a user can edit day before month - the object can hold February 31st and only commit constrains. Hour is stored in the LOCALE'S HOUR CYCLE with a separate dayPeriod bit (0 = AM, 1 = PM), so am/pm edits are independent and "12 means 0" lives in exactly one place. Gregorian-only by design (the calendar seam is clean if that ever changes - limits() is the only calendar knowledge).

The mask engine, adapted from an MIT-licensed source (source and license in THIRD_PARTY_NOTICES.md). Pure functions over a parsed slot list, zero DOM. A mask is a sequence of slots: token slots validate ONE character against a pattern, literal slots are fixed chrome ("/", "-", " ") the engine inserts and the user never types. Every value decision lives here so it stays exhaustively unit-testable; the caret math and events live in mask_controller.js.

The registration guard: Stimulus never errors on a data-controller identifier nothing registered - the element simply stays inert - and one failed import in the host's controllers graph silently takes every poetry controller down with it. After the page is ready (and again on every Turbo navigation) this compares the poetry-prefixed identifiers on the page with the application's registry and warns ONCE per identifier. Host controllers are never inspected (they may lazy-load); poetry's cannot.

Body scroll-lock with scrollbar-width compensation: bare overflow: hidden shifts the whole layout by the scrollbar width the moment an overlay opens on a scrollable page. The gap is measured BEFORE locking and paid back as body padding-right. Refcounted so stacked overlays (a dialog opened from a sheet) lock once and restore only when the LAST one closes - per-instance saved values break on out-of-order closes.

Why not scrollbar-gutter: stable (this helper's original primary)? Measured live with classic scrollbars: Chrome drops the viewport's rail AND its reserved gutter the moment the viewport's used overflow computes to hidden - whether the pair sits on the root, propagates from body, or the gutter was set permanently - so the page shifted by the scrollbar width anyway (the exact wiggle the strategy existed to stop). The body-padding payback is the only compensation the viewport honors; its known cost is that position:fixed elements aren't compensated - accepted deliberately, not an oversight.

Scroll geometry for the message-scroller, adapted from an MIT-licensed source (source and license in THIRD_PARTY_NOTICES.md): pure functions of {viewport, content, spacer, rects} - no Stimulus, no state. This is the jsdom-testable half; the controller owns the policy that decides when to call these. The constants encode deliberate fixes - treat them as pinned values, not tunables.

Tabbable-candidate walk: the shared filter behind focus-scope and the Dialog trap. Candidates in DOM order, minus disabled / hidden / tabindex=-1 / inert-subtree elements.

Turbo snapshots the page BEFORE caching it (turbo:before-cache), and an overlay still open at that moment serializes INTO the snapshot: the restoration visit then renders a de-modalized zombie dialog (the open attribute survives HTML serialization, top-layer/modal state does not) over a body whose inline scroll-lock / pointer-events-scrim styles came back frozen - a page that can never scroll, or never be clicked, again (both reproduced live against the docs app). Overlay controllers subscribe their synchronous teardown here; no-op when Turbo is absent.

The APG typeahead buffer, shared: printable keys accumulate into a search buffer that resets after a timeout (1s default), matching wraps from the current item, and a repeated same-letter buffer cycles matches. Extracted VERBATIM from menu_controller.js so the menu family and the Select listbox run the identical algorithm - the buffer/timer state lives in the instance this factory returns, one per consuming controller.

A date/time value whose segments may each be null (the module header holds the storage rules). One instance backs one date-field.

Exported from @poetry/controllers/helpers/incomplete_date.

The accordion open-set machine: single (optionally collapsible) or multiple. Composes with poetry--core--roving-focus (manageTabindex: false - APG keeps every trigger tabbable) attached separately on the same root. Panels ride the presence helper; the measured --accordion-panel-height var feeds the vendored accordion-down/up keyframes.

Values: type (String, default: "single"); collapsible (Boolean, default: false)

Events: poetry:accordion:change

The floating bulk-actions bar (the ActionBar contract): shows while its table's selection is non-empty, and holds the contract rules - focus NEVER moves in on show; if focus was inside when the bar hides, it returns to where it was before entering (the FocusScope restoreFocus equivalent, scoped small); "Actions available." is announced ONCE per appearance; the visible count RETAINS its last non-zero value while the bar animates out (never a "None selected" flash); Escape anywhere inside clears the selection (the table's engine listens for

Targets: count

Values: label (String, default: "%{count} selected")

Events: poetry:data-table:clear-selection

The Autocomplete: a REAL text input that IS the form value, suggesting from a server-rendered list that filters as you type. This is the input-is-the-value semantic - the sibling of Combobox, whose value is a SELECTED ITEM behind a native <select>. Selecting a suggestion writes the input and closes; the text always submits as ordinary params.

The contract's fixed behaviors: locale-aware filtering (toLocaleLowerCase), list scroll reset on every filter pass, and change-reason details on the commit event (item-press | enter-key). Positioning rides the shared popper controller (input = anchor).

Targets: content, empty, input, list

Values: open (Boolean, default: false); openOnFocus (Boolean, default: true)

Events: poetry:autocomplete:closed, poetry:autocomplete:commit, poetry:autocomplete:open

The Calendar engine, decided OWN-THE-ENGINE: no date-picker library (a heavy JS dep). The month grid is SERVER-RENDERED (Ruby Date math) so a no-JS page shows a valid calendar; this controller adds month navigation (regenerating the 42-cell grid from plain Date math - reusing the day button DOM, no innerHTML churn), single-date selection (writing the hidden input + the data-selected/aria vocabulary), and roving arrow-key focus over the days. Selection is a real form value; the DatePicker composes this inside a Popover.

Range mode: mode="range" swaps the click path for a transcription of an MIT-licensed range-selection algorithm (source and license in THIRD_PARTY_NOTICES.md) and the reflection for the range vocabulary (data-range-start/middle/end - dictionary classes that shipped inert until range mode). The form value is TWO hidden inputs (name[start]/name[end] - the wire shape is poetry's). The transcribed semantics hold exactly: an incomplete start-only pick renders as a plain selected single day; the range vocabulary appears only once the range completes.

Dropdown caption (caption_layout: :dropdown), the invisible-select overlay pattern: each [data-calendar-unit=month|year] wrapper holds a visible text label (calendar-dropdown-value) with the real select stretched invisibly over it - #jump reads the selects, #render reflects navigation back into both select values AND label text (no caption target in that mode). Week numbers: one role=rowheader per week; each row's Thursday decides the ISO number (matches Ruby Date#cweek under any week_start).

Still deferred: multiple months.

Targets: caption, day, endInput, grid, input, startInput

Values: month (String); selected (String); mode (String, default: "single"); rangeStart (String); rangeEnd (String); weekStart (Number, default: 0); min (String); max (String); monthNames (Array, default: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"])

Events: poetry:calendar:change

The Carousel engine, decided NATIVE: no carousel library - the platform's scroll-snap owns the physics (touch, momentum, snapping, overscroll), and this controller adds only what CSS can't: prev/next paging, button state, and arrow keys. Navigation scrolls the VIEWPORT by a bounding- rect delta (RTL- and transform-safe: never scrollLeft sign conventions) - not scrollIntoView, whose alignment bubbles to scrollable ancestors and whose "nearest" no-ops when several slides fit the viewport at once (the vertical stack). Deferred with the library-grade machinery: loop (it clones slides), autoplay, and a plugin API.

Targets: next, previous, viewport

Values: orientation (String, default: "horizontal")

Events: poetry:carousel:select

The select-all recipe (a parent checkbox running the APG mixed-state pattern) over the checked family. Wrap the parent and its rows, route the bubbling per-checkbox observe event at #changed, and mark the parent (target: all) plus each row (target: item):

<div data-controller="poetry--core--checkbox-group" data-action="poetry:checkbox:change->poetry--core--checkbox-group#changed">

A parent toggle fans its new state out to every enabled row; a row toggle re-derives the parent (all -> checked, none -> unchecked, some -> indeterminate, re-entered via the checked controller's set() - the only path back to mixed). Every state write goes THROUGH each box's checked controller (input first, real change event, aria-checked + the checked triple together) - this controller never touches attributes itself. Disabled rows are skipped by fan-out and excluded from the derivation (the DataTable disabledBehavior 'selection' doctrine; table_selection_controller is this same recipe for NATIVE checkboxes).

Targets: all, item

Events: poetry:checkbox-group:change

The toggle family's checked-state owner (Checkbox introduces it; Switch reuses it VERBATIM - zero fork, CI-asserted). The architecture is the STORE INVERSION: the hidden native <input type=checkbox> is the form participant AND the store - the visual button[role=checkbox|switch] only REFLECTS it (aria-checked incl. "mixed" + the data-checked/data-unchecked/ data-indeterminate attributes on the control and every part that carries them: the checkbox indicator, the switch thumb). Every transition writes the input FIRST, dispatches a REAL bubbling change event (no synthetic prototype-setter dance - the input LEADS and the visual follows), then reflects attributes.

The three states: checked / unchecked / indeterminate. Indeterminate is server/programmatic only (aria-checked=mixed, input.indeterminate - a JS-only property re-derived from the checked attributes on connect); the first user toggle resolves it to CHECKED - contractual, do not loosen. A Switch never renders it (the Ruby component raises), so that branch is simply dormant there.

Enter is suppressed on role=checkbox ONLY (WAI-ARIA: checkboxes activate on Space alone); role=switch has no keydown handler, so Enter toggles via the native button click (a deliberate asymmetry, keyed off the role - no controller fork).

No inputId value -> pure visual mode: state lives on the button's checked attributes alone (controlled-UI cases like DataTable row selection). The component-flavored prefixes the dynamic dispatch below emits under (data-component on the host: checkbox / switch, with the bare fallback) - the events declaration, the portal bridge, and the manifest enumerate these REAL names; the identifier-default name never fires here.

Values: inputId (String, default: "")

Events: poetry:checkbox:change, poetry:checked:change, poetry:switch:change

ClipboardText, adapted from an MIT-licensed source (source and license in THIRD_PARTY_NOTICES.md): a read-only value with one copy affordance. navigator.clipboard is the primary path; the execCommand fallback SAVES AND RESTORES the user's own selection and focus (copying a field must never eat a selection made elsewhere on the page). Success stamps data-copied on the root for a beat (CSS swaps the copy/check glyphs off it), announces through the live-region singleton, and dispatches the copied event.

Targets: input, source

Values: text (String); message (String)

Events: poetry:clipboard-text:copied

The Combobox ORCHESTRATOR: Select's shell x Command's engine, composed VIA THE EVENT CONTRACT ONLY - this thin controller owns open/close + the commit pipeline + autofill adoption and listens for the embedded engine's poetry:command:select; it contains NO filter/highlight/scoring code (Command owns those) and Command gained no combobox code (engine purity, fenced both directions by the conformance greps). Zero code is shared with SelectController - the PATTERNS are (the layer mechanism, the native-first 5-step pipeline, the adoption path), re-instantiated here because a facade extraction was explicitly declined (the Select contract's open question, answered by this build).

THE THREE DELIBERATE DELTAS vs Select, each pinned by tests so neither sibling's rules leak:

• open focuses the COMMAND INPUT for every reason (a combobox session is

a TYPING session - APG editable combobox); the selected option gets the HIGHLIGHT (activedescendant, via the Command controller) + scroll, not DOM focus;

• Tab while open CLOSES WITHOUT COMMIT and lets focus proceed (Popover

semantics, modal:false default; modal:true restores the trap) - Select is Tab-inert;

• a printable key on the CLOSED trigger OPENS and SEEDS the filter

(typing filters, never blind-commits) - Select's closed-trigger typeahead-commit does NOT port.

TWO MEANINGS, TWO ATTRIBUTES, ONE LIST: data-highlighted + aria-activedescendant = position (Command's, never aria-selected); aria-selected + data-selected + the indicator = the COMMITTED value (Select's twin-write, written only here, in the pipeline).

THE SYNC INVARIANT (Select's, inherited): native_select.value, the value Value, the twin-write, and the display never diverge - every write path funnels through #apply, NATIVE FIRST (serialization truth is never behind the facade), with real bubbling change/input on the native so Turbo auto-submit and form listeners work unmodified.

MULTIPLE (the input-inside layout): the value is a LIST (the value Value carries a JSON array over the same String seam), the native is a <select multiple> posting name[], and the trigger is replaced by the chips FIELD - one chip per committed value IN VALUE ORDER with the filter input inline after them (data-slot=combobox-chip-input, which the engine resolves too; the engine itself rides the ROOT). Selection TOGGLES and the popup STAYS OPEN; chips take REAL DOM focus (:focus-visible styles it - never data-highlighted) and focusing a chip closes the popup; Backspace on the empty input removes the last chip; Escape on the CLOSED popup clears the query and wipes the selection. The input NEVER mirrors selection text; single-mode paths are behavior-identical.

Values: open (Boolean, default: false); value (String, default: ""); modal (Boolean, default: false); multiple (Boolean, default: false)

Events: poetry:combobox:change, poetry:combobox:closed, poetry:combobox:open, poetry:combobox:select

The Command palette engine - the suite's first ACTIVEDESCENDANT component (the APG editable-combobox pattern, the deliberate delta vs the menus/Select family's roving focus): real DOM focus stays pinned to the input for the whole session; the highlighted option carries data-highlighted + its server-stable id in the input's aria-activedescendant (the twin-write, activedescendant-flavored). Options never get tabindex; roving-focus is NOT attached; aria-selected is NEVER written here (reserved for committed values - Combobox's twin-write; a bare palette has no committed value).

THE FILTER is the deterministic helpers/filter_rank spec (prefix 4 > word-boundary 3 > substring 2 > keyword 1 > hidden 0, diacritic-folded) and it is HIDE-ONLY: score-0 items get hidden + data-hidden, matches get both removed, and children are NEVER reordered - DOM order is the ranking authority within a band; the score's only job is seating the auto-highlight. filter:false is the server-driven mode: steps 1-2 (hiding) are skipped entirely and only highlight/activation/announcement run over whatever the server rendered

• the Turbo-frame async seam Combobox's recipe plugs into.

ACTIVATION IS AN EVENT, NOT AN ACTION: Enter/click dispatches cancelable poetry:command:select and this controller does nothing further - no navigation, no close, no value write. The listener (host data-action, Combobox's commit pipeline) owns the consequences - the engine-purity Combobox's composition depends on (no popper/commit/native-select code lives here, fenced by the conformance greps).

The DOM is the store, filtering included: query in the input, visibility as hidden + data-hidden, highlight as data-highlighted + aria-activedescendant, group visibility derived - a Turbo Stream can append items mid-session and the next keystroke ranks them. Each part matches both families' vocabularies: Command's own names and the combobox's (two names for the same parts; the engine rides both).

Values: filter (Boolean, default: true); loop (Boolean, default: false); debounce (Number, default: 0)

Events: poetry:command:filter, poetry:command:highlight, poetry:command:select

The ContextMenu DELTA layer: trigger acquisition + pointer-point capture ONLY. Everything menu-shaped (open state machine, items, typeahead, submenus, dismissal, the layer stack) stays with poetry--core--menu on the same root; positioning stays with poetry--core--popper, driven here through its VIRTUAL-ANCHOR attribute (data-poetry--core--popper-anchor-point-value="x,y" - the DOM is the store, so the write works whether or not popper has connected yet).

Input paths (all contractual):

• contextmenu (mouse right-click, or Shift+F10 / the ContextMenu key on a

focused surface): preventDefault, capture the point, open. A keyboard-synthesized event carries no usable point (0,0) - the anchor attribute is CLEARED so popper falls back to the trigger surface rect (deliberately better than a 0,0 fallback).

• long-press (touch/pen ONLY - mouse never long-presses): pointerdown

starts a longPressDelay timer (700ms default, exposed as a Value); ANY pointermove/pointerup/pointercancel cancels (no slop radius

• the platform's own touch slop absorbs jitter); a second pointerdown

restarts (multi-touch guard); the contextmenu handler itself clears the timer (Android synthesizes contextmenu from long-press - clearing there prevents double-open). data-pressing on the surface is the styleable long-press feedback window (poetry addition).

• disabled STANDS THE HANDLERS DOWN (no preventDefault): the

browser-native context menu returns - never a dead right-click.

Values: longPressDelay (Number, default: 700); disabled (Boolean, default: false)

Events: poetry:context-menu:open

The segmented date/time editor. The component renders a real native <input type=date|time> that IS the form value (no JS = native pickers; its ISO value format is exactly the wire contract), plus an empty group. This controller builds per-segment role=spinbutton spans from Intl.DateTimeFormat.formatToParts - so the LOCALE decides segment order and literals - and syncs segments -> native input eagerly whenever the value is complete and valid, constraining on blur (February 31st is representable mid-edit; commit clamps).

Hour is stored in the locale's hour cycle with a separate dayPeriod segment; the cycle itself is INFERRED by formatting (two Intl bugs make resolvedOptions() untrustworthy - helpers/incomplete_date.js).

Latin-digit typing only (the NumberField documented divergence); the DISPLAY uses Intl.NumberFormat, so locales that render non-latin digits still see their own numerals.

Targets: group, input

Values: locale (String, default: ""); hourCycle (String, default: ""); seconds (Boolean, default: false); placeholder (String, default: ""); labels (Object, default: {}); placeholders (Object, default: {})

Events: poetry:date-field:change

The DatePicker glue: the thin coordinator between a Popover and the Calendar it wraps. The Calendar owns selection + the form value (its name: hidden input); this controller only reacts to the calendar's change event to (a) write the human-formatted date into the trigger label and (b) close the popover so the pick feels complete. Everything hard is already done by poetry--core--calendar and poetry--core--popover.

Targets: input, label

Values: placeholder (String, default: "Pick a date"); mode (String, default: "single"); locale (String, default: "en-US")

Error isolation for deferred turbo-frames. Turbo owns the loading physics (loading="lazy" fetches on visibility, "eager" after paint) but leaves failure INVISIBLE: a missing frame logs "Content missing" or - Turbo 8 - promotes the error response to a full-page visit, and a network error leaves the placeholder spinning forever. This controller makes failure a state: data-error reflected on the frame (a bespoke boolean, deliberately not the shared open/closed vocabulary), the placeholder hidden, and the slotted <template> error content stamped so the region shows a real, retryable message.

THE BOOT CONTRACT: the frame renders with NO src - the URL rides srcValue and connect() arms it. A visible lazy frame with src in markup can complete its fetch before the controllers module graph finishes loading (caught live: a local 404 beat Stimulus and Turbo 8 navigated the whole page to the error response); with src armed at connect, no fetch - and so no failure - can predate the instance.

retry() prefers Turbo's FrameElement#reload(); environments without the Turbo runtime (jsdom, dommy) fall back to re-setting src, the same signal Turbo reacts to.

Targets: error, placeholder

Values: src (String)

The Drawer: the dialog machinery + the swipe-to-dismiss gesture. Everything hard about the OVERLAY is inherited (native <dialog> platform trap, backdrop-click discrimination, scroll lock, hotkey); this subclass adds the two things a drawer is:

* ANIMATED presence - the first consumer of the presence helpers: enter rides the data-starting-style two-frame trick (a transition from --closed-transform), exit HOLDS the dialog through the data-ending-style transition before the native close() (the presence-hold close the sheet styling depends on). * The SWIPE - pointer-captured drag along the dismiss direction, writing the swipe CSS-var contract onto the <dialog> (::backdrop inherits from its originating element, so the overlay fade rides the same vars): --drawer-swipe-movement-x/y (px toward dismissal), --drawer-swipe-progress (0..1), data-swiping while tracking (duration-0 - the drawer follows the finger), and on release either a snap-back or a dismissal whose exit duration scales with --drawer-swipe-strength (mostly-swiped closes fast).

Deferred with the rest of the stack machinery (see the Drawer style): snap points, nested-drawer stacking, and bleed.

Targets: dialog

Values: dismissible (Boolean, default: true); hotkey (String, default: ""); direction (String, default: "down"); modal (Boolean, default: true); snapPoints (Array, default: [])

The FileInput dropzone engine: the component renders a <label> wrapping a visually-hidden native <input type=file>, so click-to-browse and keyboard access are the PLATFORM's - this controller adds only what HTML cannot: drag-and-drop onto the label, the selected-file list, and the clear affordance. The native input stays the single source of truth (its FileList is the form value; ActiveStorage direct upload rides it untouched).

Drag state uses an enter/leave COUNTER: dragenter/dragleave fire per descendant crossed, so a boolean flickers over child elements - the counter nets out to zero only when the pointer truly leaves the zone.

Targets: clear, input, list

Values: multiple (Boolean, default: false)

Events: poetry:file-input:change

Declarative global shortcut: put the controller on any clickable element and declare the descriptor -

<a href="/inbox" data-controller="poetry--core--hotkey" data-poetry--core--hotkey-keys-value="g+i">

On match the controller dispatches a cancelable poetry--core--hotkey:pressed event, then clicks the host element (buttons, links, summary - anything click-activatable). Unmodified single-key descriptors stay inert while the user is typing in an input/textarea/select/contentEditable; combos carrying meta/ctrl/alt fire everywhere (the ⌘K convention).

Values: keys (String, default: "")

Events: poetry--core--hotkey:pressed

The HoverCard controller (the popper-consumer trio's thinnest machine): pointer-only enrichment behind a LINK. Two timers (open 600 / close 300, over the trigger+content pair, re-enter cancels - the grace window, no polygon), the touch double-guard (pointerType 'touch' no-ops AND touchstart preventDefaults so a tap can never synthesize a focus-open - a tap just navigates the link), the focus mirror (trigger focus opens immediately / blur closes - a keyboard user SEES the card), the per-open TABINDEX STRIP (every tabbable inside is forced tabindex=-1: keyboard and touch users never reach inside, intentional and contractual - the reachable-elsewhere rule), and the SELECTION HOLD (text selection started in the card keeps it open and suppresses body user-select while dragging, so previews are copyable).

NO focus-scope anywhere in the lifecycle: focus never moves in, so there is nothing to trap or restore - the trio's simplest teardown. The token-activated dismissable delivers Esc (topmost-only) + outside press while open. No aria surface is added (no haspopup/expanded/describedby): advertising a keyboard-unreachable surface to AT is worse than silence.

Values: open (Boolean, default: false); openDelay (Number, default: 600); closeDelay (Number, default: 300)

Events: poetry:hover-card:closed, poetry:hover-card:open

The input-mask machine (the engine is adapted from an MIT-licensed source - source and license in THIRD_PARTY_NOTICES.md) on a bare native <input> - this.element IS the input. Three layers:

1. THE PRIMARY PATH is keydown with preventDefault: a printable char skips forward over literals from the caret and pattern-tests (a failing char is a NO-OP, it never reaches the field), a selection is replaced via a raw rebuild, and the caret lands past the next literal run. Backspace scans BACKWARD over literals (the caret lands at the deleted token), Delete scans FORWARD (the caret stays), Cmd/Ctrl+Backspace kills to start, arrows hop literal runs. Because preventDefault kills the native undo stack, a custom {raw, selectionStart} history (max 100, deduped) backs Cmd/Ctrl+Z / Shift+Cmd/Ctrl+Z / Ctrl+Y.

2. THE FALLBACK is the input-event diff (IME, mobile keyboards, autofill, password managers - paths that never emit clean keydowns): the longest common prefix+suffix against the previous display isolates the inserted text and the removed span, the value is rebuilt from raw pieces, re-masked, and the caret lands after the insertion.

3. THE DISPLAY: skeleton padding ("__/__") shows on focus (showMaskOnFocus, default) or permanently (alwaysShowMask); blur strips it back to the filled region - or clears the field entirely when autoClear is set and the mask is incomplete. A COLLAPSED caret is clamped into [first token, end of filled region] on focus (rAF), mousedown (rAF) and mouseup; selections are never touched.

A deliberate divergence from the adapted source: every programmatic value write dispatches a native bubbling input event (#painting guards the controller against its own echo) so Rails/Turbo listeners stay live. The raw value mirrors to data-raw after every change; pattern is set on connect from generatePattern("full-inexact") unless the input already carries one.

Values: mask (String); slotChar (String, default: "_"); alwaysShowMask (Boolean); showMaskOnFocus (Boolean, default: true); autoClear (Boolean); upcase (Boolean)

Events: poetry:mask:change, poetry:mask:complete

The menus-family controller (the DropdownMenu contract's ANCHOR - ONE menu engine behind DropdownMenu / ContextMenu / Menubar). This owns ONLY what is menu-specific: open/close with the data-open-reason initial-focus contract, item activation (the cancelable poetry:menu:select), checkbox/radio state (poetry:menu:change), the APG typeahead buffer, submenu open/close with hover intent + sibling exclusivity, and the cancelable poetry:menu:edge-navigate seam a Menubar coordinator consumes. Everything else is composed BY REFERENCE: focus-scope (trap + focus return to the trigger), dismissable (topmost-only Esc + outside press, arriving here as its "dismiss" event), roving-focus (arrows/Home/End per menu level), popper (positioning - markup-owned, untouched here), presence (data-open/data-closed flip -> animationend -> hidden).

STRUCTURAL RESOLUTION, no targets: the content is found via the trigger's aria-controls id (portal-safe - a Stimulus target cannot cross a portal move), items via the collection helper over the family's data-slot suffix selectors ([data-slot$=menu-item] etc., so dropdown-menu-*, context-menu-* and menubar-* anatomies all resolve), subs via their own aria-controls pairs. Content-level listeners are wired programmatically in connect for the same portal-safety reason.

The layer stack is ACTIVATED on open: the focus-scope / dismissable / roving-focus identifiers are appended to the content's data-controller (a statically-connected trap or dismiss layer on a hidden menu would steal focus at page load and swallow topmost-Esc). Close reverses: presence exit -> hidden -> tokens removed -> focus-scope's disconnect restores focus to the trigger. Each open sub level adds its own dismissable layer (the close-one-level-at-a-time Esc chain for free) + its own roving group; subs join the ROOT focus scope (no nested traps, contractual). Both family spellings resolve: dropdown-menu-* / context-menu-* share the "menu-" suffix; menubar-* is its own word (menubar-item does NOT end with "menu-item"), so every part selector carries the pair.

Values: open (Boolean, default: false); modal (Boolean, default: true); loop (Boolean, default: false); typeaheadTimeout (Number, default: 1000); closeOnSelect (Boolean, default: true)

Events: poetry:menu:change, poetry:menu:closed, poetry:menu:edge-navigate, poetry:menu:open, poetry:menu:select

The Menubar cross-menu COORDINATOR - kept deliberately anorexic: ONE piece of state (value, which menu is open) plus the three behaviors no other layer can own. The ownership split:

• roving-focus (horizontal, manageTabindex TRUE) owns which trigger is

tabbable/focused on the bar - it knows nothing about menus.

• poetry--core--menu (one instance per menu, modal: false) owns

everything inside an open menu - it knows nothing about siblings.

• this controller owns:

1. TOGGLE - pointerdown opens (closing any sibling) / closes the open menu. Keyboard open (ArrowDown/Enter/Space -> first item; ArrowUp -> last item) rides the family's open-reason contract; pointer-open leaves focus on the trigger (pointer users keep their context). 2. HOVER-SLIDE - pointerenter on a sibling trigger is a no-op from cold; once ANY menu is open it swaps to the hovered menu (the gated-hover rule) and focus moves to the new trigger. 3. EDGE-NAVIGATE - the family menu controller fires a cancelable poetry:menu:edge-navigate when ArrowLeft/Right has no submenu meaning; this coordinator consumes it (loop-aware, RTL-aware, disabled-skipping) and opens the adjacent menu with its FIRST item focused (both directions - APG menubar). Standalone DropdownMenu leaves the event unconsumed. Dismiss (Esc/outside) and select arrive as the family's poetry:menu:closed

• the coordinator nulls value; focus return to the trigger is the family

focus-scope's job (its connect snapshot IS the trigger, because every open path here puts focus there first).

A press on a sibling trigger must be TOGGLE's, not the open menu's dismissable layer's: the coordinator vetoes interact-outside for presses landing on this bar's triggers (otherwise dismiss-then-toggle would close-and-reopen in the same pointerdown).

Values: value (String, default: ""); loop (Boolean, default: false)

Events: poetry:menubar:value-changed

How long (ms) data-autoscrolling stays set during a programmatic scroll before clearing. While set, the follow-bottom RELEASE is suppressed so the auto-scroll animation cannot release itself.

Targets: button, content, spacer, viewport

Values: autoScroll (Boolean, default: false); defaultScrollPosition (String, default: "end"); preserveScrollOnPrepend (Boolean, default: true); trackVisibility (Boolean, default: false); scrollEdgeThreshold (Number, default: 8); scrollPreviousItemPeek (Number, default: 64); scrollMargin (Number, default: 0)

Events: poetry:message-scroller:mode, poetry:message-scroller:pinned, poetry:message-scroller:scrollable, poetry:message-scroller:unpinned, poetry:message-scroller:visibility

The NavigationMenu coordinator (the viewport=false mode): a DISCLOSURE BAR, not a menu - Tab moves through triggers and links normally, arrows are convenience navigation, nothing traps. Each item's panel is its own popup positioned under the item; this controller owns what per-item popovers can't: ONE panel open at a time, hover intent (open/close delays so diagonal travel into a panel doesn't flicker), Esc + focus-out + outside-press closing, and the vocabulary writes (data-popup-open on the trigger - the chevron's rotation hook - and the presence-driven open/closed pair on the panel).

THE VIEWPORT MODE: when the markup ships the shared positioner > popup > viewport shell (viewport: true), panels are lazily ADOPTED into the viewport on first activation (the Rails stand-in for a portal - server-rendered content stays in place until JS activates) and the composite MORPHS: the popper re-anchors to the active trigger (full floating-ui) while CSS transitions the positioner's insets, the popup's --popup-width/height pin old -> new across two frames so width/height transition, panels slide by data-activation-direction (new trigger vs old - travel direction drives the slide), and data-instant suppresses transitions on cold opens. Vars reset to auto after the animations finish (the auto-size reset via getAnimations().finished).

Values: openDelay (Number, default: 50); closeDelay (Number, default: 150)

NumberField: a formatted visible <input type=text> over a hidden <input type=number> that is the form/validation truth - the spinbutton ARIA pattern is deliberately not used. The controller owns stepping (arrows, steppers with press-and-hold, opt-in wheel), parse/clamp/format, and the two-input sync. Number | null value model: empty is null, never NaN.

Deliberate v1 boundaries (documented in the component): no scrub area, Latin-digit parsing only (locale separators and currency/percent symbols ARE handled via Intl.formatToParts), and the server renders the raw number - the display formats on connect.

Targets: decrement, hidden, increment, input

Values: min (Number); max (Number); step (Number, default: 1); largeStep (Number, default: 10); smallStep (Number, default: 0.1); snap (Boolean); wheel (Boolean); format (Object); locale (String)

Events: poetry:number-field:change, poetry:number-field:commit

Optimistic UI for Turbo forms, adapted from an MIT-licensed source (source and license in THIRD_PARTY_NOTICES.md). The optimistic update is AUTHORED AS A TURBO STREAM inside a <template> target - the same vocabulary the server answers in, so prediction and truth share one mental model and there is no bespoke DOM patching. On turbo:submit-start the template contents are cloned into the document and Turbo paints the predicted state immediately; on turbo:submit-end the controller reconciles ONLY when the submission failed, by appending <turbo-stream action="refresh"> - which must morph (the helper documents the turbo-refresh-method=morph meta) so the correction is seamless.

THE SERVER CONTRACT (enforced nowhere, so stated everywhere): success answers 204 (or a targeted stream for authoritative correction under contention) - NEVER a redirect, because a redirect under morph refreshes is itself a full reload and defeats the optimism. Failure answers 4xx so event.detail.success is false and the refresh restores authoritative truth. Full story: the Optimistic Forms guide on the poetry docs site.

Targets: template

The InputOTP projection (the single-input architecture, poetry's own build - no npm dependency): ONE real native <input> holds the whole value, stretched invisibly over the slot row, so paste, SMS autofill, IME, constraint validation and form serialization are all native and AT sees ONE text field. The n slot cells are an aria-hidden MIRROR painted here - this controller contains ZERO editing logic:

• #sync filters input.value per-character through the pattern + truncates

to length (writing back only when filtering changed it - that one line IS paste splitting: "123-456" under digits becomes "123456"), paints slot[i] with value[i], and projects the caret: the active cell is min(selectionStart, length - 1) while focused (data-active), with the fake blinking caret element visible only on the active EMPTY cell.

• Auto-advance and backspace-retreat are not features: typing moves the

native caret forward, Backspace moves it back - the active cell is a PROJECTION of selectionStart. Arrows/Home/End/IME: native, re-projected via the document-level selectionchange listener (bound on focus, unbound on blur - n OTP fields must not all re-project on every caret move anywhere).

• poetry:otp:change fires per accepted mutation; poetry:otp:complete

fires once when the value reaches length and re-arms below it (the enable-the-submit-button hook - it never submits).

Targets: input, slot

Values: length (Number, default: 6); pattern (String, default: "\\d")

Events: poetry:otp:change, poetry:otp:complete

The Popover controller (the popper-consumer trio's click-open member): the menu controller's #show/#hide + token-activated layer skeleton with ALL item machinery deleted - no typeahead, no roving, no subs, no collection. What remains is exactly the APG dialog-pattern-lite: the trigger toggles a role=dialog panel, focus MOVES INTO the content on open (focus-scope's mount default - deliberately NOT vetoed, the contrast with the menu family's data-open-reason contract) and RETURNS to the trigger on close; the trap is enforced only when modal (the default is modal: FALSE - the deliberate contrast with the menu family's true).

STRUCTURAL RESOLUTION, no targets: the content is found via the trigger's aria-controls id (portal-safe - the menu-controller pattern verbatim); content-level listeners are wired programmatically in connect for the same reason.

The layer stack is ACTIVATED on open: focus-scope + dismissable are appended to the content's data-controller (a statically-connected trap on hidden content would steal focus at page load; a static dismissable would swallow topmost-Esc), with trapped / disable-outside-pointer-events both set from modal. Close reverses: presence exit -> hidden -> tokens removed -> focus-scope's disconnect restores focus to the trigger (suppressed for outside-press when non-modal: focus follows the click).

Values: open (Boolean, default: false); modal (Boolean, default: false)

Events: poetry:popover:closed, poetry:popover:open

The Toggle micro-machine (the smallest controller in the suite): flip aria-pressed and mirror the bare data-pressed presence boolean - WRITTEN TOGETHER, never separately. The DOM is the store: no Values, no internal state. This is deliberately NOT poetry--core--checked (different ARIA vocabulary, no input to sync) and not poetry--core--state (that owns aria-expanded disclosure) - three micro-controllers, three vocabularies.

No keydown code: Space AND Enter both activate a native button (click) - the platform already implements the keyboard.

poetry:toggle:change is CANCELABLE and fires BEFORE the flip renders: preventDefault vetoes it (hosts that must confirm). The pressed value in the detail is the state the toggle is ABOUT to enter.

Events: poetry:toggle:change

The Questionnaire machine, adapted from an MIT-licensed source (source and license in THIRD_PARTY_NOTICES.md): a native <form> of fieldset items shown ONE at a time. The server renders the complete initial state (active item, statuses, shortcuts, button visibility); this controller owns the runtime transitions - navigation (validate-gated Next, Skip for optional items, submit validates every item and jumps to the first invalid), answer tracking (choice change / text input -> status), the keyboard map (Cmd/Ctrl+Enter confirm, ArrowUp/Down answer focus, ArrowLeft/Right item navigation, Enter-on-filled-answer confirm, letter/number shortcuts), and the data-attribute stamps the styling contract reads. Answers are native radio/checkbox/text inputs - the form serializes with zero JS.

Targets: next, previous, progress, skip, submit

Values: shortcuts (String, default: "")

Events: poetry:questionnaire:item-change, poetry:questionnaire:status-change

The RadioGroup checked-value machine (the Accordion composition shape): this controller owns ONLY the value + attribute/input writes - ZERO keyboard code. The shared poetry--core--roving-focus runs on the same root in its DEFAULT tabindex-managing mode (one Tab stop) with the orientation: "both" extension (all four arrows, APG radio), and this controller consumes its cancelable entry event to implement SELECTION FOLLOWS FOCUS: entry fires only on arrow/Home/End navigation - never on Tab or click-focus - so checking on entry is exactly the APG contract (Tab into the group never changes the value; contractual).

The form story is the hidden-native-input rule: one <input type=radio> per item, shared name (aria-hidden, tabindex=-1) - native radio serialization, byte-identical to collection_radio_buttons. check() writes every item's aria-checked/checked pair/indicator, sets the hidden input's .checked (the native group unchecks siblings; written explicitly anyway - belt and braces), moves the roving tab stop to the checked item, and dispatches poetry:radio-group:change + native input/change on the newly checked hidden input (Rails autosave/change-tracking listeners fire).

Targets: input

Values: value (String, default: "")

Events: poetry:radio-group:change

The Resizable engine, decided NATIVE: no panel library - panels are flex children whose flex-grow IS the percentage, and this controller implements the APG window-splitter on the handles: pointer drag redistributes the two adjacent panels (clamped to each panel's min/max), arrows step, Home/End jump the range, and every move writes aria-valuenow (the preceding panel's size). Deferred with the library's machinery: persistence (autoSaveId), collapsible panels, and the imperative API.

Values: orientation (String, default: "horizontal")

Events: poetry:resizable:resize

Scroll-spy: marks the nav link whose section is currently active while the page scrolls - the docs-TOC pattern. Put the controller on the nav; every link target's href="#id" names its section:

<nav data-controller="poetry--core--scroll-spy"> <a href="#usage" data-poetry--core--scroll-spy-target="link">Usage</a>

The active section is the LAST one whose top sits above the offset line (a closest-heading reduce); its link gains data-active and a poetry--core--scroll-spy:changed event carries the id. rAF-coalesced passive scroll + resize listeners; call refresh() after content changes.

The SearchField seams: Escape CLEARS a non-empty field and is consumed - the NEXT press reaches the dismissal layer and closes a parent overlay; an already-empty field lets Escape propagate untouched. Emptiness is checked against the RAW input value (autofill and scripts poke the DOM directly). The clear button keeps focus in the input by preventing the press's focus steal at pointerdown - on mobile that is what keeps the virtual keyboard up. Enter is never intercepted: native form submission is the Rails path.

Targets: clear, input

Events: poetry:search-field:clear

The Select listbox controller - the APG select-only combobox on the menus MACHINERY (popper markup-owned + focus-scope/dismissable/roving-focus activated as layers + the shared typeahead helper) but deliberately NOT a mode of poetry--core--menu: everything menu-specific (submenus, close_on_select, checkbox/radio aria-checked, edge-navigate, Tab-closes, pointer-open-no-focus) is wrong for a listbox, and everything here is dead weight for menus.

THE SYNC INVARIANT (the component): native_select.value, the value Value, aria-selected/data-selected on options, and the display text never diverge - every write path (commit, closed-trigger typeahead, autofill adoption, programmatic setValue) funnels through #apply, which writes the NATIVE SELECT FIRST (serialization truth is never behind the facade), dispatches real bubbling change/input on it (Turbo auto-submit and friends work unmodified), flips aria-selected + data-selected TOGETHER on every option, syncs the value display from the option's item-text (data-text-value override), toggles trigger[data-placeholder], then fires poetry:select:change.

Three deltas vs the menu family, all deliberate and contractual:

• Tab while open is INERT (a value picker resolves by commit or Esc);
• open focuses the SELECTED option for EVERY reason, pointer included;
• typeahead on the CLOSED trigger COMMITS the match without opening

(native <select> behavior), while open typeahead only moves focus.

Values: open (Boolean, default: false); value (String, default: ""); modal (Boolean, default: true); loop (Boolean, default: false); typeaheadTimeout (Number, default: 1000); alignItemWithTrigger (Boolean, default: false)

Events: poetry:select:change, poetry:select:closed, poetry:select:open, poetry:select:select

The SensitiveInput machine, adapted from an MIT-licensed source (source and license in THIRD_PARTY_NOTICES.md): a secret field in three states - masked | revealed | empty - where data-state on the root carries the truth and CSS renders it. Masked-with-value turns the MASK OVERLAY into the reveal affordance (role=button + label + sr-hint; only text spans inside - a role on the surrounding group would trip axe nested-interactive around the inert input) while the real input stays rendered for layout but goes inert (aria-hidden, tabindex -1, readonly, transparent). Reveal: click anywhere on the group (mask clicks bubble) or Enter/Space on the mask, focus moves into the input. Re-mask: Escape (focus returns to the mask

• the input just lost its tab stop), leaving the component, or the eye.

Typing into an empty field auto-reveals so composition happens in type=text. The no-JS story is a plain password input.

Targets: hint, input, mask, toggle

Values: maskedLabel (String); hiddenMessage (String); readOnly (Boolean)

Events: poetry:sensitive-input:mask, poetry:sensitive-input:reveal

The Sheet: the dialog machinery, animated end to end. Everything hard about the overlay is inherited (native <dialog> platform trap, backdrop-click discrimination, scroll lock, hotkey) - including the presence-hold close, which the base controller owns (exit flips the pair to data-closed and holds the dialog through the slide-out before the native close()). This subclass only upgrades the ENTER: open rides enterPresence so the data-starting-style hook fires like every other presence consumer.

Targets: dialog

Values: dismissible (Boolean, default: true); hotkey (String, default: "")

The Sidebar state machine (desktop plus the mobile mode): expand/collapse coordination for the app shell. The COLLAPSE itself is pure CSS - the peer sidebar carries data-state=expanded|collapsed and the dictionary's group-data-[state=collapsed] classes do all the width/transform work; this controller only flips that attribute (plus data-collapsible, which the source sets to the mode WHILE collapsed and "" while expanded), persists the choice to a cookie (so the SERVER can read it and render the right initial state - poetry's server-first angle), and binds the Cmd/Ctrl+B shortcut.

MOBILE (DOM-move): below md the trigger routes to a separate never-persisted openMobile state (only desktop toggles write the cookie). Opening ADOPTS the server-rendered nav children from the desktop inner into the mobile <dialog> (one render, no duplicate ids - the render-twice rejection) and shows it through the sheet presence path; closing holds through the slide-out, then moves the children back. Crossing to desktop while open restores INSTANTLY. The component-facing event namespace (the poetry:<component> rule).

Targets: inner, mobileDialog, mobileInner, sidebar

Values: open (Boolean, default: true); collapsible (String, default: "offcanvas"); cookieName (String, default: "sidebar_state"); cookieMaxAge (Number, default: 604800); shortcut (String, default: "b")

Events: poetry:sidebar:mobile-toggle, poetry:sidebar:toggle

The Slider machine - the only form control with real math. Three concerns, nothing else:

1. THE VALUE MATH (the pure core, unit-tested exhaustively): snap to the step grid with decimal-precision rounding (a 0.1 grid lands on 0.3, never 0.30000000000000004), clamp to [min, max], and clamp against neighbor thumbs +- the min gap (minStepsBetweenThumbs * step) so range thumbs can never cross.

2. TWO INPUT PATHS feeding it: the APG keyboard map per thumb (arrows +-step, Shift+Arrow / PageUp / PageDown +-step*10, Home/End to the thumb's EFFECTIVE min/max) with the orientation x RTL x inverted resolution - horizontal RTL swaps Left/Right only, inverted flips the whole axis, both compose (rtl + inverted = ltr math); and pointer capture on the root - pointerdown jumps the NEAREST thumb (ties to the later index, so stacked thumbs stay separable), the track box is read ONCE at pointerdown (no per-frame layout), pointermove projects the value ABSOLUTELY from the pointer position (overshoot past a neighbor clamps, never swaps), pointerup commits.

3. THE DOM PROJECTION: aria-valuemin/max/now per role=slider thumb - the range bounds are DYNAMIC (neighbor-clamped, rewritten on every neighbor move: APG multithumb), the --slider-start/--slider-end geometry vars consumed by the calc() rules, and one hidden native input per thumb. poetry:slider:change fires per mutation; commit (pointerup / each keydown) syncs the hidden inputs + dispatches native input/change so Rails listeners get one event per gesture, not per frame.

Targets: input, range, thumb, track

Values: min (Number, default: 0); max (Number, default: 100); step (Number, default: 1); value (Array, default: []); minStepsBetweenThumbs (Number, default: 0); orientation (String, default: "horizontal"); inverted (Boolean, default: false)

Events: poetry:slider:change, poetry:slider:commit

The table row-selection engine (the SelectionManager contract, checkbox-flavored): per-row checkboxes are the form value (selected_ids[] - no JS means plain checkboxes in a form, the honest fallback), this controller adds what HTML cannot:

• select-all with a real INDETERMINATE middle state (a JS property,

never an attribute), computed over ENABLED rows only (disabled rows are skipped by select-all and ranges - disabledBehavior 'selection').

• Shift-click range selection off the ANCHOR model: the

anchor is the last plainly-toggled row; Shift sets every row in anchor..target to the ANCHOR row's state (the checkbox idiom).

• aria-selected + data-selected mirrored onto rows, count announcements

through the announce singleton, and a bubbling selection-change event the ActionBar block feeds on.

• poetry:data-table:clear-selection (dispatched by the ActionBar's

Escape) clears everything from anywhere inside the wrapper.

Targets: all

Values: label (String, default: "%{count} selected")

Events: poetry:data-table:selection-change

The Tabs activation machine: this controller owns ONLY the active-value state + attribute writes; the shared poetry--core--roving-focus on the tablist owns the keyboard (default tabindex-managing mode - one Tab stop). Triggers are DUMB buttons (click -> tabs#activate; with automatic activation - the APG default for tabs - focusin activates too, so arrow keys both move focus AND switch panels).

The state vocabulary: the active trigger carries data-active (the styled token) + aria-selected; inactive panels carry the hidden property + data-hidden. data-activation-direction is deliberately NOT emitted - no shipped class consumes it (add it with the animated indicator, when something does).

Panels are scoped to THIS root (a nested Tabs inside a panel owns its own triggers/panels - the DOM is the registry, same rule as roving-focus).

Values: activateOnFocus (Boolean, default: true)

Events: poetry:tabs:change

The TagGroup removal engine (the tag-group contract): navigation itself rides the roving-focus controller (the toolbar precedent) - this controller owns what tags add on top:

• Delete/Backspace on a focused tag removes it (row-origin keys only;

keys from a tag's inner remove button must not drive the grid).

• The remove button removes exactly its own tag.
• Focus recovery after removal is the reference walk: FORWARD through

the pre-removal order to the first surviving enabled tag, then backward; when the last tag goes, the CONTAINER takes focus, flips role grid->group, and becomes the tab stop.

• The container is a live region ONLY while focus is within (polite,

additions) - SRs hear tags added while working in the group without spam from elsewhere.

Removal is CANCELABLE (poetry:tag-group:remove): a Turbo-driven host preventDefault()s and re-renders; otherwise this controller removes the row (and the hidden input riding it - form mode serializes name[] per tag).

Events: poetry:tag-group:remove

One toast item (poetry's own Toast - the stacked-toaster genre with strict a11y semantics). The item is role=status aria-live=off: it never announces itself - on connect it speaks ONCE through the announce singleton at its politeness (destructive -> assertive, wired server-side via the politeness value). The auto-dismiss timer follows APG/WCAG 2.2.1 timing: it PAUSES on hover, focus-within, window blur and tab-hidden (reasons are refcounted so overlapping pauses cannot resume early), and duration <= 0 means persistent (required for undo/action toasts). Dismiss flips data-open -> data-closed, dispatches poetry:toast:dismiss {id, reason} (the toaster's reflow + focus-return seam), then presence holds the node until its exit animation finishes before removal.

Swipe-to-dismiss is a browser-verification-GATED enhancement (contract) - it does not ship in this pass; the swipe reason is reserved.

Targets: action, close

Values: duration (Number, default: 5000); politeness (String, default: "polite")

Events: poetry:toast:dismiss, poetry:toast:show

The client-side toast delivery trigger (poetry's no-round-trip path - what a toast() JS factory does elsewhere, done with server-rendered markup): press -> dispatch poetry:toaster:stamp, and the toaster clones the addressed <template>'s toast into its region. The toast inside the template is byte-for-byte what a Turbo Stream would deliver.

Values: template (String); toaster (String)

Events: poetry:toaster:stamp

The toast viewport (one per page): the labeled role=region <ol> that is the Turbo Stream append target (id=poetry-toaster, data-turbo-permanent). It ACQUIRES the announce singleton for its lifetime (items announce through it on connect), owns the F8 hotkey (focus moves to the most recent toast; the prior focus is remembered so dismissal returns it), enforces the visible LIMIT (default 3 - the oldest overflow toasts queue hidden with their timers held, promoted as newer ones dismiss), and owns the stack reflow (--poetry-toast-index, newest = 0, for the offset/scale stack styling).

Items arrive by server render, Turbo Stream append, or a stamp (the poetry:toaster:stamp window event - poetry_toast_trigger's no-round-trip path, cloning a <template> toast into the region); a childList MutationObserver reconciles limit + reflow on every change, so no append path needs to know about the toaster.

Targets: item

Values: hotkey (String, default: "F8"); limit (Number, default: 3); position (String)

The ToggleGroup value-set machine (the Accordion composition, second consumer): this controller owns ONLY the pressed-values set + attribute writes; the shared poetry--core--roving-focus on the same root owns the keyboard (default tabindex-managing mode - one Tab stop). Items are DUMB buttons (data-action -> group#toggle; poetry--core--pressed is NOT attached in group context - one owner, no event soup).

The role/vocabulary split, enforced here: type=single is RADIO semantics - items carry aria-checked (aria-pressed stripped) and re-pressing the sole pressed item deselects to EMPTY; type=multiple is toolbar semantics - independent aria-pressed items. The controller reads type once and never mixes vocabularies; the bare data-pressed presence boolean styles both types identically (Toggle's classes just work).

After every transition the PRESSED item becomes the roving tab stop (re-entering the group lands on the selection) - written directly as the tabindex stamp roving-focus adopts.

Values: type (String, default: "single")

Events: poetry:toggle-group:change

The Tooltip controller (the popper-consumer trio's timing machine): open DELAYS (provider delay_duration, default 0), the provider-scoped WARM grace (one tooltip open - or closed less than skip_delay_duration ms ago - lets siblings in the same provider scope open instantly), ONE OPEN GLOBALLY (the document-level will-open event), close-on-scroll, and the pointer-vs-focus open paths with their latches.

A11y is the strictest of the trio: the content is role=tooltip and the trigger's aria-describedby is set on open and REMOVED on close (describedby must never reference hidden content); focus-scope is NOT composed at all - focus never enters a tooltip; touch NEVER opens one (no long-press path, deliberately). Esc rides a token-activated dismissable layer while open, so a tooltip above a Dialog peels first.

THE WARM REGISTRY (the provider mechanism): a module-level WeakMap keyed by the [data-slot=tooltip-provider] ancestor (document fallback) holding {openCount, warmUntil}. The DOM ancestor IS the provider scope; the WeakMap lets morphed/replaced providers garbage-collect (no Turbo leaks).

Values: open (Boolean, default: false); delayDuration (Number, default: -1); disableHoverableContent (Boolean, default: false)

Events: poetry:tooltip:closed, poetry:tooltip:open

The Tree engine (the flat-treegrid contract): the server renders a FLAT list of role=row siblings - hierarchy lives entirely in aria-level/posinset/setsize (static per render) - so this controller owns only what HTML cannot: roving focus over VISIBLE rows, the four-branch ArrowLeft/Right expansion logic (including focus-to-parent), Enter-toggles-expandable (the no-action default), typeahead, and subtree show/hide that preserves nested collapsed state (a row is visible iff every ancestor is expanded).

Expansion state IS the DOM (aria-expanded + hidden); the host persists it by listening for poetry:tree:toggle. Selection modes are deferred (the TagGroup reasoning).

Events: poetry:tree:toggle