stimulus_plumbers 0.4.5 → 0.4.8

data/vendor/ARIA.md

@@ -0,0 +1,88 @@
+# WCAG 2.1 AA / ARIA Reference
+
+## Core Criteria (all components)
+
+| Criterion | Level | Rule |
+|-----------|-------|------|
+| 1.3.1 Info & Relationships | A | Convey structure via semantic HTML or ARIA roles, not visual styling alone |
+| 1.4.1 Use of Color | A | Never use color as the only means to convey information |
+| 1.4.3 Contrast (text) | AA | 4.5:1 normal text, 3:1 large text (18pt / 14pt bold) |
+| 1.4.11 Non-text Contrast | AA | 3:1 for UI component boundaries and state indicators |
+| 2.1.1 Keyboard | A | All functionality operable via keyboard; no mouse-only interactions |
+| 2.1.2 No Keyboard Trap | A | Focus must be escapable from any component (Escape or documented key) |
+| 2.4.3 Focus Order | A | Focus sequence must be logical and predictable |
+| 2.4.7 Focus Visible | AA | Keyboard focus indicator must be visible |
+| 4.1.2 Name, Role, Value | A | All UI components must have accessible name, role, and state via ARIA or native semantics; state must stay in sync dynamically (e.g. `aria-expanded`, `aria-selected`, `aria-checked`) |
+| 4.1.3 Status Messages | AA | Status/error messages announced via `role="status"` or `aria-live` without focus move |
+
+## JS Keyboard Navigation Patterns
+
+Two helper classes handle keyboard navigation in controllers — see [`stimulus-plumbers/docs/accessibility/design.md`](stimulus-plumbers/docs/accessibility/design.md) for full API.
+
+| Pattern | Class | When to use |
+| --- | --- | --- |
+| Roving tabindex | `RovingTabIndex` | Disclosure widgets, trees, toolbars — focus moves between items |
+| Managed focus / listbox | `ListboxNavigation` | Combobox listbox, `role="listbox"` — input keeps focus, `aria-selected` moves |
+
+## Component-Specific Patterns (APG)
+
+#### Modal (`modal_controller`)
+- `role="dialog"`, `aria-modal="true"`, `aria-labelledby` pointing to heading
+- Focus moves into dialog on open; returns to trigger on close
+- Focus trapped inside — Tab/Shift+Tab cycle within; Escape closes
+
+#### Popover (`popover_controller`)
+- `role="dialog"` or `role="tooltip"` depending on interactivity
+- Trigger: `<button>` with `aria-haspopup="dialog"` and `aria-expanded="false"` initially
+- `aria-expanded` toggled to `"true"` / `"false"` by the controller via the `trigger` Stimulus target
+- `aria-controls` linking trigger to panel id is recommended but optional
+- Escape closes and returns focus to trigger
+
+#### Combobox (`input_combobox_controller`, `combobox/`)
+- Trigger: `<input role="combobox">` with `aria-haspopup` (`listbox`/`dialog`) and `aria-controls` referencing the **popup element** (the `role="listbox"`/`role="dialog"`)
+- `role="listbox"` permits only `option`/`group` children (`aria-required-children`, WCAG 1.3.1). Status messages (loading, "No results") must be `role="status"`/`aria-live` **siblings of the listbox, never children of it** — for typeahead the listbox is nested in a wrapper panel so the status regions can sit beside it
+- Status/loading regions inside the popover panel must stay **non-focusable** (the popover moves focus into the panel on open)
+
+#### Calendar / Date Picker (`calendar-month`, `combobox-date`)
+- Grid: `role="grid"`, `role="row"`, `role="gridcell"`
+- Navigation buttons: `aria-label="Previous Month"` / `"Next Month"` (via `Combobox::Date::Navigation`)
+- Selected date: `aria-selected="true"`; today: `aria-current="date"`
+- Disabled dates: `aria-disabled="true"`, `tabindex="-1"`
+- Three views: month (days grid), year (months grid), decade (years grid); zoom out via `combobox-date#zoomOut`
+- Arrow keys navigate cells; Enter/Space select; Escape closes picker
+
+#### Form Fields (`form/`, `form-field_controller`)
+- Every input must have a visible `<label>` via `for`/`id` or `aria-labelledby`
+- Required fields: `required` attribute + `aria-required="true"`
+- Invalid fields: `aria-invalid="true"` + `aria-describedby` pointing to error message
+- Error message element: `role="alert"` or `aria-live="polite"` so it's announced
+
+#### Password Reveal (`password_reveal_controller`)
+- Toggle button: `aria-label` describes action ("Show password" / "Hide password")
+- Or: `aria-pressed` on toggle button
+
+#### Flipper / Visibility / Dismisser
+- Trigger: `aria-expanded="true/false"` when toggling a region
+- Controlled region: `aria-hidden="true"` when collapsed (or removed from DOM)
+- `aria-controls` links trigger to region id
+
+#### Button (`button/renderer`)
+- Use `<button>` (not `<div>` / `<a>`) for actions
+- Icon-only buttons must have `aria-label` or visually-hidden text
+- Disabled: `disabled` attribute (not `aria-disabled` alone) unless intentionally focusable
+
+#### List (`sp_list`, `sp_list_item`)
+- Static list: `role="list"` + `role="listitem"` (explicitly set to preserve semantics when CSS resets strip list role)
+- Active item: `aria-current="page"` on `<a>` links; `aria-current="true"` on `<button>` items — the value differs by element type per the ARIA spec
+
+#### Avatar / Card / Icon
+- Decorative images/icons: `aria-hidden="true"` or `alt=""`
+- Meaningful images: descriptive `alt` text
+
+#### Timeline (`timeline_controller`)
+- List: `<ol>` (ordered) for chronological events; static timelines need no ARIA additions beyond semantic HTML
+- Each item: `<li>`; timestamp displayed via `<time datetime="YYYY-MM-DD">`
+- Indicators (dots, icons, avatars): decorative — always `aria-hidden="true"`
+- Expandable items: trigger `<button>` with `aria-expanded="false/true"` + `aria-controls` → detail element id; detail has `hidden` attribute toggled by controller
+- Trigger lives inside `<h3>` (`<h3><button aria-expanded>Title</button></h3>`) — WAI-ARIA Accordion pattern
+- Keyboard (interactive): Up/Down arrows move focus between item triggers; Home/End jump to first/last trigger; Enter/Space toggle expansion (native button behaviour)

data/vendor/controller/docs/calendar.md

@@ -0,0 +1,215 @@
+# calendar-month
+
+Renders an accessible calendar grid for a given month. Driven by the `Calendar` plumber, which provides navigation, disabled dates, and range constraints.
+
+## Targets
+
+| Target        | Description                          |
+| ------------- | ------------------------------------ |
+| `daysOfWeek`  | Container for the weekday header row |
+| `daysOfMonth` | Container for the day grid rows      |
+
+## Classes
+
+| Class             | Description                               |
+| ----------------- | ----------------------------------------- |
+| `dayOfWeek`       | Applied to each weekday header cell       |
+| `dayOfMonth`      | Applied to each day cell                  |
+| `dayOfOtherMonth` | Applied to day cells from adjacent months |
+| `row`             | Applied to each week row                  |
+
+## Values
+
+| Value              | Type    | Default       | Description                                                                            |
+| ------------------ | ------- | ------------- | -------------------------------------------------------------------------------------- |
+| `year`             | Number  | —             | Year being displayed                                                                   |
+| `month`            | Number  | —             | Month being displayed (0-indexed)                                                      |
+| `since`            | String  | `""`          | Earliest selectable date (ISO string)                                                  |
+| `till`             | String  | `""`          | Latest selectable date (ISO string)                                                    |
+| `locales`          | Array   | `["default"]` | `Intl.DateTimeFormat` locale(s)                                                        |
+| `weekdayFormat`    | String  | `"short"`     | Weekday header format: `"short"` \| `"long"` \| `"narrow"`                             |
+| `dayFormat`        | String  | `"numeric"`   | Day number format                                                                      |
+| `daysOfOtherMonth` | Boolean | `false`       | Show overflow days from adjacent months                                                |
+| `today`            | String  | `""`          | Override the "today" marker (ISO date string); defaults to system date                 |
+| `selected`         | String  | `""`          | Currently selected date (ISO string); sets `aria-selected="true"` on the matching cell |
+
+## Calendar plumber options (programmatic only)
+
+These options are not exposed as Stimulus values and must be passed via a subclass or custom controller:
+
+| Option             | Description                                  |
+| ------------------ | -------------------------------------------- |
+| `firstDayOfWeek`   | `0` = Sunday, `1` = Monday, … (default `0`)  |
+| `disabledDates`    | Array of ISO date strings to disable         |
+| `disabledWeekdays` | Array of weekday names or numbers to disable |
+| `disabledDays`     | Array of day-of-month numbers to disable     |
+| `disabledMonths`   | Array of month names or numbers to disable   |
+
+## Standalone usage
+
+```html
+<div
+  data-controller="calendar-month"
+  data-calendar-month-year-value="2024"
+  data-calendar-month-month-value="1"
+  data-calendar-month-locales-value='["en-US"]'
+  role="grid"
+>
+  <div data-calendar-month-target="daysOfWeek"></div>
+  <div role="rowgroup" data-calendar-month-target="daysOfMonth"></div>
+</div>
+```
+
+## Rails helper
+
+```ruby
+module ApplicationHelper
+  include StimulusPlumbers::Helpers::CalendarHelper
+end
+```
+
+```erb
+<%# Current month %>
+<%= sp_calendar_month %>
+
+<%# Navigate to a specific date %>
+<%= sp_calendar_month(date: Date.new(2024, 3, 15)) %>
+
+<%# With custom classes %>
+<%= sp_calendar_month(class: "my-calendar") %>
+```
+
+## Actions
+
+| Method            | Description                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `select(iso)`     | Selects a date by ISO string — sets `selectedValue`, updates `aria-selected`, dispatches `calendar-month:selected` |
+| `navigate(date)`  | Navigates to the given `Date` — updates `yearValue`/`monthValue` and re-renders the grid                           |
+| `step(unit, dir)` | Steps the calendar by `unit` (`'day'`/`'month'`/`'year'`) in `dir` (`1`/`-1`)                                      |
+
+Click-handling is wired internally — `calendar-month` handles clicks on its own grid and dispatches `calendar-month:selected` automatically.
+
+**Dispatches**
+
+| Event                      | Detail           | When                                                |
+| -------------------------- | ---------------- | --------------------------------------------------- |
+| `calendar-month:selecting` | —                | On every valid cell click, before date is confirmed |
+| `calendar-month:selected`  | `{ epoch, iso }` | After a valid date is parsed from the clicked cell  |
+| `calendar-month:navigate`  | `{ from, to }`   | Before navigation begins (ISO strings)              |
+| `calendar-month:navigated` | `{ from, to }`   | After navigation completes (ISO strings)            |
+
+## Accessibility
+
+- Grid uses `role="grid"` → `role="row"` → `role="gridcell"`
+- Weekday headers use `role="columnheader"` with `title` for the long name
+- Today is marked with `aria-current="date"`
+- Disabled dates use `disabled` (buttons) or `aria-disabled="true"` (non-interactive)
+- Selected dates use `aria-selected="true"`
+
+---
+
+## calendar-year
+
+Year-view grid controller — renders a 12-month grid and dispatches a `calendar-year:selected` event when a month button is clicked. Pair with `combobox-date` via `data-action` on the orchestrator element.
+
+**Targets**
+
+| Target | Description                                             |
+| ------ | ------------------------------------------------------- |
+| `grid` | `role="rowgroup"` container the controller renders into |
+
+**Values**
+
+| Value         | Type   | Default       | Description                                                    |
+| ------------- | ------ | ------------- | -------------------------------------------------------------- |
+| `current`     | Number | —             | Year being displayed                                           |
+| `today`       | String | `""`          | ISO date string for today marker                               |
+| `selected`    | String | `""`          | ISO date string for selected marker                            |
+| `since`       | String | `""`          | Earliest selectable date (ISO string)                          |
+| `till`        | String | `""`          | Latest selectable date (ISO string)                            |
+| `locales`     | Array  | `["default"]` | `Intl.DateTimeFormat` locale(s)                                |
+| `monthFormat` | String | `"short"`     | Month button label format: `"short"` \| `"long"` \| `"narrow"` |
+
+**Dispatches**
+
+| Event                    | Detail      | When                                              |
+| ------------------------ | ----------- | ------------------------------------------------- |
+| `calendar-year:selected` | `{ month }` | After a valid month button is clicked (1-indexed) |
+
+```html
+<!-- action wired on the combobox-date element -->
+<div
+  data-controller="combobox-date"
+  data-action="calendar-year:selected->combobox-date#onMonthSelect"
+  data-combobox-date-calendar-year-outlet="#year_view"
+>
+  <div id="year_view" hidden data-controller="calendar-year" role="grid" aria-label="Year view">
+    <div data-calendar-year-target="grid" role="rowgroup"></div>
+  </div>
+</div>
+```
+
+---
+
+## calendar-decade
+
+Decade-view grid controller — renders a 12-year grid and dispatches a `calendar-decade:selected` event when a year button is clicked. Pair with `combobox-date` via `data-action` on the orchestrator element.
+
+**Targets**
+
+| Target | Description                                             |
+| ------ | ------------------------------------------------------- |
+| `grid` | `role="rowgroup"` container the controller renders into |
+
+**Values**
+
+| Value      | Type   | Default | Description                            |
+| ---------- | ------ | ------- | -------------------------------------- |
+| `current`  | Number | —       | Year within the decade being displayed |
+| `today`    | String | `""`    | ISO date string for today marker       |
+| `selected` | String | `""`    | ISO date string for selected marker    |
+| `since`    | String | `""`    | Earliest selectable date (ISO string)  |
+| `till`     | String | `""`    | Latest selectable date (ISO string)    |
+
+**Dispatches**
+
+| Event                      | Detail     | When                                 |
+| -------------------------- | ---------- | ------------------------------------ |
+| `calendar-decade:selected` | `{ year }` | After a valid year button is clicked |
+
+```html
+<!-- action wired on the combobox-date element -->
+<div
+  data-controller="combobox-date"
+  data-action="calendar-decade:selected->combobox-date#onYearSelect"
+  data-combobox-date-calendar-decade-outlet="#decade_view"
+>
+  <div id="decade_view" hidden data-controller="calendar-decade" role="grid" aria-label="Decade view">
+    <div data-calendar-decade-target="grid" role="rowgroup"></div>
+  </div>
+</div>
+```
+
+---
+
+## calendar-month-selector
+
+Thin SSR/Turbo adapter for server-rendered month grids. Attaches click-to-select behaviour to a server-rendered day grid — no targets or values. The server renders each view as a `<turbo-frame>`; this controller handles day selection and emits the same `calendar-month:selected` event as `calendar-month`.
+
+Used with `sp_calendar_turbo_month` (Rails). Pair with `combobox-date` exactly as you would `calendar-month`.
+
+---
+
+## calendar-year-selector
+
+Thin SSR/Turbo adapter for server-rendered year (month-grid) views. Attaches click-to-select behaviour — no targets or values. Emits `calendar-year:selected` on month click.
+
+Used with `sp_calendar_turbo_year` (Rails).
+
+---
+
+## calendar-decade-selector
+
+Thin SSR/Turbo adapter for server-rendered decade (year-grid) views. Attaches click-to-select behaviour — no targets or values. Emits `calendar-decade:selected` on year click.
+
+Used with `sp_calendar_turbo_decade` (Rails).

data/vendor/controller/docs/clipboard.md

@@ -0,0 +1,61 @@
+# clipboard
+
+Intercepts native paste events and re-dispatches them as Stimulus events. Also provides a copy action that writes text to the clipboard via the Clipboard API.
+
+## Targets
+
+| Target   | Description                                                                         |
+| -------- | ----------------------------------------------------------------------------------- |
+| `source` | Element whose `.value` or `.textContent` is copied when no `text` param is provided |
+
+## Values
+
+| Value         | Type   | Default        | Description                                                                                                      |
+| ------------- | ------ | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `contentType` | String | `"text/plain"` | MIME type to extract from `clipboardData` on paste. Common: `"text/plain"` \| `"text/html"` \| `"text/uri-list"` |
+
+## Methods
+
+| Method           | Wired via         | Description                                                      |
+| ---------------- | ----------------- | ---------------------------------------------------------------- |
+| `onPaste(event)` | `paste` DOM event | Event adapter — intercepts paste, dispatches `clipboard:pasted`  |
+| `copy(event)`    | `data-action`     | Action — writes text to clipboard, dispatches `clipboard:copied` |
+
+## Dispatches
+
+| Event                   | Detail            | When                             |
+| ----------------------- | ----------------- | -------------------------------- |
+| `clipboard:pasted`      | `{ text, types }` | On successful paste interception |
+| `clipboard:copied`      | `{ text }`        | On successful clipboard write    |
+| `clipboard:copy-failed` | `{ error }`       | On clipboard write failure       |
+
+## Paste example
+
+```html
+<%# Intercept paste, forward to input-formatter for normalisation %>
+<input
+  data-controller="clipboard"
+  data-action="paste->clipboard#onPaste clipboard:pasted->input-formatter#onPaste"
+  data-clipboard-content-type-value="text/plain"
+/>
+```
+
+## Copy examples
+
+```html
+<%# Copy from a source target %>
+<div data-controller="clipboard">
+  <input data-clipboard-target="source" value="text to copy" readonly />
+  <button data-action="click->clipboard#copy">Copy</button>
+</div>
+
+<%# Copy hardcoded text via param %>
+<button data-controller="clipboard" data-action="click->clipboard#copy" data-clipboard-text-param="https://example.com">
+  Copy link
+</button>
+```
+
+## Notes
+
+- `paste` calls `event.preventDefault()` — the original paste is suppressed
+- Use `clipboard:pasted->input-formatter#onPaste` to forward pasted content for formatting

data/vendor/controller/docs/combobox.md

@@ -0,0 +1,242 @@
+# Combobox Controllers
+
+The combobox family uses a layered design. `input-combobox` and `input-formatter` live on the wrapper; a picker sub-controller lives inside the popover.
+
+```
+input-combobox + input-formatter   ← wrapper
+└── [popover]
+      └── combobox-date         ← date picker (calendar grid)
+      └── combobox-time         ← time picker (drum/scroll-wheel)
+      └── combobox-dropdown     ← listbox (dropdown & typeahead)
+```
+
+---
+
+## input-combobox
+
+Owns the trigger input, popover visibility, and hidden value. Always co-located with `input-formatter`.
+
+**Targets**
+
+| Target    | Element              | Description                                     |
+| --------- | -------------------- | ----------------------------------------------- |
+| `trigger` | `input[type=text]`   | The combobox input (display + focus management) |
+| `input`   | `input[type=hidden]` | Holds the submitted value                       |
+
+**Values**
+
+| Value       | Type   | Default | Description                                                            |
+| ----------- | ------ | ------- | ---------------------------------------------------------------------- |
+| `value`     | String | `""`    | Current selected value; setting it triggers `valueValueChanged`        |
+| `minLength` | Number | `1`     | Min query length before typeahead relays to `combobox-dropdown` outlet |
+
+**Outlets**
+
+| Outlet              | Description                         |
+| ------------------- | ----------------------------------- |
+| `combobox-dropdown` | Optional; present in typeahead mode |
+
+**Methods**
+
+| Method            | Wired via             | Description                                                                        |
+| ----------------- | --------------------- | ---------------------------------------------------------------------------------- |
+| `onSelect(event)` | `combobox-*:selected` | Event adapter — writes `event.detail.value` to `valueValue`; popover handles close |
+| `onInput(event)`  | `input` on trigger    | Event adapter — extracts query, relays to `comboboxDropdownOutlet.filter(query)`   |
+
+**Dispatches**
+
+| Event                    | Detail      | When                                              |
+| ------------------------ | ----------- | ------------------------------------------------- |
+| `input-combobox:changed` | `{ value }` | After `valueValue` changes (including on connect) |
+
+---
+
+## input-formatter
+
+Formats and displays values. Always co-located with `input-combobox`.
+
+**Targets**
+
+| Target   | Element                  | Description                                                               |
+| -------- | ------------------------ | ------------------------------------------------------------------------- |
+| `input`  | `<input>` or any element | Write destination — sets `.value` for `<input>`, `.textContent` otherwise |
+| `toggle` | `<button>`               | Reveal/conceal button (maskable/password types only)                      |
+
+**Values**
+
+| Value      | Type    | Default   | Description                                               |
+| ---------- | ------- | --------- | --------------------------------------------------------- |
+| `format`   | String  | `"plain"` | `plain` \| `password` \| `creditCard` \| `date` \| `time` |
+| `options`  | Object  | `{}`      | Formatter options (e.g. `{ format: "h12" }` for time)     |
+| `revealed` | Boolean | `false`   | Whether a masked value is currently revealed              |
+
+**Methods**
+
+| Method            | Wired via                | Description                                                                      |
+| ----------------- | ------------------------ | -------------------------------------------------------------------------------- |
+| `format(value)`   | —                        | Programmatic API — normalises, formats, writes to target, dispatches `formatted` |
+| `onChange(event)` | `input-combobox:changed` | Event adapter — extracts `event.detail.value`, calls `format(value)`             |
+| `onPaste(event)`  | `clipboard:pasted`       | Event adapter — normalises and validates pasted text, calls `format(value)`      |
+| `toggle()`        | `data-action`            | Action — flips `revealedValue` (maskable / password types only)                  |
+
+**Dispatches**
+
+| Event                       | Detail      | When                                    |
+| --------------------------- | ----------- | --------------------------------------- |
+| `input-formatter:formatted` | `{ value }` | After every write to the `input` target |
+
+---
+
+## combobox-date
+
+Navigates a calendar grid with month, year, and decade views. Requires a `calendar-month` outlet; `calendar-year` and `calendar-decade` are optional for drill-down. View switching hides/shows outlet elements directly — no named targets for view containers.
+
+**Targets**
+
+| Target      | Description                                                            |
+| ----------- | ---------------------------------------------------------------------- |
+| `previous`  | Button that steps backward (one month / one year / one decade by view) |
+| `next`      | Button that steps forward (one month / one year / one decade by view)  |
+| `viewTitle` | Button showing the current view label (e.g. "June 2025" / "2025")      |
+| `day`       | Rendered day label element (display only)                              |
+| `month`     | Rendered month label element (display only)                            |
+| `year`      | Rendered year label element (display only)                             |
+
+**Outlets**
+
+| Outlet            | Description                                                  |
+| ----------------- | ------------------------------------------------------------ |
+| `calendar-month`  | Required — provides the day grid and calendar navigation API |
+| `calendar-year`   | Optional — year view grid; shown when `view` is `"year"`     |
+| `calendar-decade` | Optional — decade view grid; shown when `view` is `"decade"` |
+
+**Values**
+
+| Value         | Type   | Default       | Description                                                 |
+| ------------- | ------ | ------------- | ----------------------------------------------------------- |
+| `date`        | String | `""`          | ISO 8601 initial date; navigates calendar on outlet connect |
+| `view`        | String | `"month"`     | Current view — `"month"` \| `"year"` \| `"decade"`          |
+| `locales`     | Array  | `["default"]` | `Intl.DateTimeFormat` locales                               |
+| `dayFormat`   | String | `"numeric"`   | Day label format                                            |
+| `monthFormat` | String | `"long"`      | Month label format                                          |
+| `yearFormat`  | String | `"numeric"`   | Year label format                                           |
+
+**Methods**
+
+| Method                 | Wired via                   | Description                                                                              |
+| ---------------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
+| `previous()`           | click on `previous` target  | Steps back: one month (month view), one year (year view), one decade (decade view)       |
+| `next()`               | click on `next` target      | Steps forward: one month (month view), one year (year view), one decade (decade view)    |
+| `zoomOut()`            | click on `viewTitle` target | Zooms out: month → year → decade view                                                    |
+| `onDaySelect(event)`   | `calendar-month:selected`   | Event adapter — updates `dateValue`, redraws labels, dispatches `combobox-date:selected` |
+| `onMonthSelect(event)` | `calendar-year:selected`    | Event adapter — navigates calendar to selected month, switches to month view             |
+| `onYearSelect(event)`  | `calendar-decade:selected`  | Event adapter — navigates calendar to selected year, switches to year view               |
+
+**Dispatches**
+
+| Event                    | Detail                 | When                      |
+| ------------------------ | ---------------------- | ------------------------- |
+| `combobox-date:selected` | `{ value }` (ISO 8601) | After a date is confirmed |
+
+---
+
+## combobox-time
+
+Drum/scroll-wheel time picker. Each drum is a `ul[role=listbox]`.
+
+**Targets:** `hour`, `minute`, `period` (period only present in h12 mode)
+
+**Methods**
+
+| Method              | Wired via                | Description                                                                         |
+| ------------------- | ------------------------ | ----------------------------------------------------------------------------------- |
+| `select(value)`     | —                        | Programmatic API — dispatches `combobox-time:selected` with the given 24-hour value |
+| `onSelect(event)`   | `click` on a drum option | Event adapter — marks clicked option `aria-selected="true"`, calls `select(value)`  |
+| `onNavigate(event)` | `keydown` on a drum      | Event adapter — ArrowUp/ArrowDown call `step(drum, delta)`                          |
+| `step(drum, delta)` | —                        | Programmatic API — moves selection by `delta` steps in the given drum element       |
+
+**Dispatches**
+
+| Event                    | Detail                          | When                                                          |
+| ------------------------ | ------------------------------- | ------------------------------------------------------------- |
+| `combobox-time:selected` | `{ value }` (`"HH:MM"` 24-hour) | On connect (if pre-selected) and after every user interaction |
+
+---
+
+## combobox-dropdown
+
+Listbox with client-side fuzzy filter or server-side fetch. Used by both dropdown and typeahead variants.
+
+**Targets**
+
+| Target    | Description                               |
+| --------- | ----------------------------------------- |
+| `listbox` | `ul[role=listbox]` containing the options |
+| `loading` | Shown during server fetch                 |
+| `empty`   | Shown when no options match               |
+
+**Values**
+
+| Value   | Type   | Default | Description                                                 |
+| ------- | ------ | ------- | ----------------------------------------------------------- |
+| `url`   | String | `""`    | Fetch URL — empty string activates client-side fuzzy filter |
+| `field` | String | `"q"`   | Query parameter name appended to `url`                      |
+| `delay` | Number | `300`   | Debounce delay in ms before issuing a server fetch          |
+
+**Methods**
+
+| Method              | Wired via                | Description                                                                                   |
+| ------------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
+| `select(value)`     | —                        | Programmatic API — sets `aria-selected` on matching option, dispatches `selected`             |
+| `onSelect(event)`   | `click` on an option     | Event adapter — extracts value from click target, calls `select(value)`                       |
+| `onNavigate(event)` | `keydown` on listbox     | Event adapter — ArrowUp/ArrowDown call `step(delta)`; Enter/Space activates current selection |
+| `step(delta)`       | —                        | Programmatic API — moves `aria-selected` by `delta` steps (+1 down, -1 up)                    |
+| `filter(query)`     | `input-combobox` outlet  | Programmatic API — routes to fuzzy filter (client) or debounced fetch (server)                |
+| `showAll()`         | `input-combobox#onInput` | Programmatic API — unhides all options when query drops below `minLength`                     |
+
+**Dispatches**
+
+| Event                        | Detail      | When                        |
+| ---------------------------- | ----------- | --------------------------- |
+| `combobox-dropdown:selected` | `{ value }` | After an option is selected |
+
+**Filter implementation**
+
+`combobox-dropdown` uses two standalone utilities internally:
+
+- **Client-side** (`url` is empty): calls `filterOptions(listboxTarget, query)` from `researcher.js` — hides non-matching `[role="option"]` elements using fuzzy matching by default. See [Researcher docs](../utility/researcher.md) for strategy and field options.
+- **Server-side** (`url` is set): debounces requests via `Requestor` from `requestor.js`, then issues `GET {url}?{field}={query}`. See [Requestor docs](../utility/requestor.md) for abort and debounce behaviour.
+
+**Server fetch contract**
+
+`GET {url}?{field}={query}` — expected response: an HTML fragment of `<li role="option" data-value="...">` elements, which replaces the inner HTML of the `listbox` target.
+
+---
+
+## Event flow
+
+```
+user picks value
+  └─ combobox-*:selected { value }
+       └─ input-combobox#onSelect       ← event adapter
+            └─ valueValue = value        → valueValueChanged
+                 ├─ inputTarget.value = value
+                 └─ dispatch input-combobox:changed { value }
+                      └─ input-formatter#onChange  ← event adapter
+                           └─ format(value)       ← programmatic API
+                                ├─ formats value
+                                ├─ writes to inputTarget
+                                └─ dispatch input-formatter:formatted { value }
+
+(popover closes separately via popover#closeOnSelect)
+```
+
+---
+
+## Naming convention
+
+| Pattern      | Wired via             | Role                                                       | Example                                                                                       |
+| ------------ | --------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `onX(event)` | DOM or Stimulus event | Event adapter — extracts payload, calls programmatic API   | `onSelect(event)`, `onChange(event)`, `onPaste(event)`, `onInput(event)`, `onNavigate(event)` |
+| `x(value)`   | — (called directly)   | Programmatic API — pure logic, no event awareness          | `select('us')`, `format('4242…')`, `step(1)`, `filter('query')`                               |
+| `past()`     | Plumber               | Plumber callback — called by plumber after async operation | `shown()`, `dismissed()`, `contentLoaded()`                                                   |

data/vendor/controller/docs/dismisser.md

@@ -0,0 +1,39 @@
+# dismisser
+
+Closes/hides an element when the user clicks outside it. Backed by the `Dismisser` plumber.
+
+## Targets
+
+| Target    | Description                                                                                                                                                   |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `trigger` | Optional — passed as `{ target }` context to the `dismissed()` callback. Does not change the click-outside boundary (which is always the controller element). |
+
+## Methods
+
+| Method        | Wired via         | Description                                                                                          |
+| ------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `dismissed()` | Dismisser plumber | Plumber callback — called when a click-outside is detected. Implement in your controller to respond. |
+
+## Example
+
+```html
+<div data-controller="dismisser">
+  <div data-dismisser-target="trigger">
+    <p>Click outside this box to dismiss it.</p>
+  </div>
+</div>
+```
+
+Implement `dismissed()` on your controller to act on the dismissal:
+
+```javascript
+async dismissed() {
+  await this.collapse()
+}
+```
+
+## Notes
+
+- The Dismisser plumber attaches a document-level `mousedown` listener. When a click lands outside the **controller element**, it calls `dismissed()`. If a `trigger` target is present, it is passed to `dismissed()` as `{ target }` context — it does not change the boundary.
+- Used internally by `modal` (custom overlay mode) and `form-field` to handle click-outside-to-close.
+- `dismissed()` is not called when clicking on the trigger element itself.