stimulus_plumbers 0.4.5 → 0.4.9

data/vendor/controller/docs/calendar.md

@@ -0,0 +1,212 @@
+# 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
+
+- Weekday headers use `role="columnheader"` with `title` for the long name
+- See [ARIA.md's Calendar / Date Picker pattern](../../../ARIA.md) for grid roles, selection/disabled state, and keyboard navigation
+
+---
+
+## 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`. See [docs/plumber/calendar-selector.md](../plumber/calendar-selector.md) for the underlying plumber.
+
+---
+
+## 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). See [docs/plumber/calendar-selector.md](../plumber/calendar-selector.md) for the underlying plumber.
+
+---
+
+## 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). See [docs/plumber/calendar-selector.md](../plumber/calendar-selector.md) for the underlying plumber.

data/vendor/controller/docs/checklist.md

@@ -0,0 +1,45 @@
+# Checklist
+
+Master "select all" toggle for a group of native `<input type="checkbox">` checklist items. Aggregates their `.checked` state onto a master checkbox's `checked`/`indeterminate` properties and toggles them all at once. See [stimulus-plumbers-rails's docs/component/checklist.md](../../../stimulus-plumbers-rails/docs/component/checklist.md) for the Rails render options.
+
+## Stimulus Identifier
+
+`checklist`
+
+## Targets
+
+| Name     | Purpose                                                               |
+| -------- | --------------------------------------------------------------------- |
+| `master` | The "select all" `<input type="checkbox">` — receives aggregate state |
+| `item`   | Each checklist item `<input type="checkbox">`                         |
+
+## Actions
+
+| Name        | Purpose                                                                                                                          |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `onChange`  | Wired to `change` on the wrapper — event adapter: if the event came from the master, calls `toggleAll`; always calls `recompute` |
+| `toggleAll` | Programmatic API — sets every enabled item's `.checked` to the given value                                                       |
+| `recompute` | Programmatic API — writes the master's `.checked`/`.indeterminate` from the enabled items' aggregate state                       |
+
+## Example HTML
+
+```html
+<div data-controller="checklist" data-action="change->checklist#onChange">
+  <label>
+    <input type="checkbox" data-checklist-target="master" />
+    Select all
+  </label>
+
+  <label>
+    <input type="checkbox" data-checklist-target="item" checked />
+    Buy milk
+  </label>
+
+  <label>
+    <input type="checkbox" data-checklist-target="item" />
+    Walk the dog
+  </label>
+</div>
+```
+
+Disabled items (`disabled` attribute) are excluded from both aggregation and bulk toggling — the controller filters them out via `enabledItems()`. `indeterminate` is a JS-only property with no HTML attribute; it is set on connect and after every change, never rendered server-side.

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,212 @@
+# 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`. See [input-formatter.md](input-formatter.md) for targets, values, methods, and dispatches.
+
+---
+
+## 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.

data/vendor/controller/docs/flipper.md

@@ -0,0 +1,46 @@
+# flipper
+
+Positions a floating element (`reference`) relative to an anchor using the `Flipper` plumber. Useful for tooltips, dropdowns, and popovers that need smart placement.
+
+## Targets
+
+| Target      | Description                                         |
+| ----------- | --------------------------------------------------- |
+| `anchor`    | The element to position relative to (e.g. a button) |
+| `reference` | The floating element to position (e.g. a tooltip)   |
+
+## Values
+
+| Value       | Type   | Default     | Description                                                         |
+| ----------- | ------ | ----------- | ------------------------------------------------------------------- |
+| `placement` | String | `"bottom"`  | Preferred placement: `"top"` \| `"bottom"` \| `"left"` \| `"right"` |
+| `alignment` | String | `"start"`   | Alignment along the cross axis: `"start"` \| `"center"` \| `"end"`  |
+| `role`      | String | `"tooltip"` | ARIA role applied to the `reference` element                        |
+
+## Methods
+
+| Method      | Wired via                                  | Description                                                                                         |
+| ----------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `flip()`    | Flipper plumber (enhanced onto controller) | Programmatic API — recalculates and applies position; called automatically on `click` events        |
+| `flipped()` | Flipper plumber                            | Plumber callback — called after every position calculation. Override to react to placement changes. |
+
+## Example
+
+```html
+<div
+  data-controller="flipper"
+  data-flipper-placement-value="bottom"
+  data-flipper-alignment-value="start"
+  data-flipper-role-value="tooltip"
+>
+  <button data-flipper-target="anchor" aria-describedby="my-tooltip">Hover me</button>
+
+  <div id="my-tooltip" data-flipper-target="reference" hidden>Tooltip text</div>
+</div>
+```
+
+## Notes
+
+- The Flipper plumber calculates available space and flips placement to the opposite side if the preferred side is out of viewport.
+- `role` is set on the `reference` element at connect time via `aria-describedby` / `aria-controls` wiring.
+- `flip()` is triggered automatically on `click` events; call it manually after programmatically showing the `reference` element.

data/vendor/controller/docs/input-clearable.md

@@ -0,0 +1,43 @@
+# input-clearable
+
+Shows a clear button when an input has a value, hides it when empty, and clears the input on demand. Keyboard users can also press Escape inside the input to clear it.
+
+## Targets
+
+| Target  | Element                 | Description                           |
+| ------- | ----------------------- | ------------------------------------- |
+| `input` | `<input type="search">` | The search input to monitor and clear |
+| `clear` | `<button>`              | The button that triggers clearing     |
+
+## Methods
+
+| Method    | Wired via     | Description                                                                                     |
+| --------- | ------------- | ----------------------------------------------------------------------------------------------- |
+| `clear()` | `data-action` | Empties the input, hides the clear button, returns focus to the input, dispatches `input` event |
+
+> `draw()` is called automatically by the controller whenever the input value changes. It does not need to be wired via `data-action`.
+
+## Example
+
+```html
+<div data-controller="input-clearable">
+  <input type="search" data-input-clearable-target="input" />
+  <button
+    type="button"
+    aria-label="Clear search"
+    data-input-clearable-target="clear"
+    data-action="click->input-clearable#clear"
+  ></button>
+</div>
+```
+
+## Accessibility
+
+- The clear button must carry `aria-label="Clear search"` — the controller never overrides it.
+- See [ARIA.md's Input Clearable pattern](../../../ARIA.md) for the clear-button tab-order, Escape-key, and focus-return contract.
+
+## Notes
+
+- Suppress the native WebKit clear button via CSS to avoid visual duplication: `input[type="search"]::-webkit-search-cancel-button { appearance: none }`.
+- `clear()` dispatches a native `input` event with `bubbles: true` so upstream listeners (e.g. live search) react to the cleared value.
+- The controller is standalone — it has no dependency on `input-formatter` or any other plumber.