stimulus_plumbers 0.4.8 → 0.4.10

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/combobox.md

@@ -53,37 +53,7 @@ Owns the trigger input, popover visibility, and hidden value. Always co-located
 
 ## 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 |
+Formats and displays values. Always co-located with `input-combobox`. See [input-formatter.md](input-formatter.md) for targets, values, methods, and dispatches.
 
 ---
 

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

@@ -34,10 +34,7 @@ Shows a clear button when an input has a value, hides it when empty, and clears
 ## Accessibility
 
 - The clear button must carry `aria-label="Clear search"` — the controller never overrides it.
-- The clear button is hidden (`hidden` attribute) while the input is empty, so keyboard users only reach it when there is something to clear.
-- After clearing, focus returns to the input so the user can type immediately (WCAG 2.4.3 Focus Order).
-- Pressing Escape inside the input clears it when the field has a value; the event's default is prevented to avoid closing parent overlays unintentionally.
-- No `aria-live` region is needed — clearing is user-initiated and the button's disappearance is self-explanatory.
+- See [ARIA.md's Input Clearable pattern](../../../ARIA.md) for the clear-button tab-order, Escape-key, and focus-return contract.
 
 ## Notes
 

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

@@ -6,18 +6,20 @@ Formats, masks, and reveals values written to an input element. Handles password
 
 ## Targets
 
-| Target   | Element                  | Description                                                                 |
-| -------- | ------------------------ | --------------------------------------------------------------------------- |
-| `input`  | `<input>` or any element | Write destination — sets `.value` for `<input>`, `.textContent` otherwise   |
-| `toggle` | `<button>`               | Reveal/conceal button; hidden at connect when the formatter is not maskable |
+| Target   | Element                  | Description                                                                                                                                                                                                                                |
+| -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `input`  | `<input>` or any element | Write destination — sets `.value` for `<input>`, `.textContent` otherwise                                                                                                                                                                  |
+| `toggle` | `<button>`               | Reveal/conceal button; hidden at connect when the formatter is not maskable                                                                                                                                                                |
+| `cell`   | `<div>` (any element)    | Optional character cells; when present, the canonical value is painted one character per cell, or (grouped mode — cell count equals `groups.length`) one group-sized slice per cell — see [character-cells](../plumber/character-cells.md) |
 
 ## Values
 
-| Value      | Type    | Default   | Description                                                          |
-| ---------- | ------- | --------- | -------------------------------------------------------------------- |
-| `format`   | String  | `"plain"` | Formatter type — see [Formatters](#formatters) for valid identifiers |
-| `options`  | Object  | `{}`      | Formatter-specific options (e.g. `{ locale: "en-US" }` for currency) |
-| `revealed` | Boolean | `false`   | Whether a masked value is currently revealed; managed by `toggle()`  |
+| Value      | Type    | Default   | Description                                                                       |
+| ---------- | ------- | --------- | --------------------------------------------------------------------------------- |
+| `format`   | String  | `"plain"` | Formatter type — see [Formatters](#formatters) for valid identifiers              |
+| `options`  | Object  | `{}`      | Formatter-specific options (e.g. `{ locale: "en-US" }` for currency)              |
+| `revealed` | Boolean | `false`   | Whether a masked value is currently revealed; managed by `toggle()`               |
+| `groups`   | Array   | `[]`      | Cell group widths (e.g. `[4,4,4,4]`); overrides the formatter's own grouping hint |
 
 ## Methods
 
@@ -27,24 +29,29 @@ Formats, masks, and reveals values written to an input element. Handles password
 | `toggle()`        | `data-action`            | Action — flips `revealedValue`; no-op unless `format` is `"password"` or formatter is maskable |
 | `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)`                    |
+| `onInput(event)`  | `input` DOM event        | Event adapter — re-formats from the input's current value                                      |
+| `onFocus(event)`  | `focus` DOM event        | Event adapter — redraws cells so the caret cell appears                                        |
+| `onBlur(event)`   | `blur` DOM event         | Event adapter — redraws cells so the caret cell clears                                         |
 
 ## Dispatches
 
-| Event                       | Detail      | When                                    |
-| --------------------------- | ----------- | --------------------------------------- |
-| `input-formatter:formatted` | `{ value }` | After every write to the `input` target |
+| Event                       | Detail      | When                                                                                                                                                                                             |
+| --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `input-formatter:formatted` | `{ value }` | After every write to the `input` target                                                                                                                                                          |
+| `input-formatter:filled`    | `{ value }` | When a valid, cell-capable formatter's value reaches its expected cell length — auto-submit hook. Fires once per fill, on the transition into "full"; not on connect with an already-full value. |
 
 ## Formatters
 
-| `type`         | Description                                                        |
-| -------------- | ------------------------------------------------------------------ |
-| `"plain"`      | No-op — passes the value through unchanged                         |
-| `"password"`   | Switches `input[type]` between `"password"` and `"text"` on reveal |
-| `"creditCard"` | Groups digits as `#### #### #### ####`                             |
-| `"phone"`      | Formats as a local phone number                                    |
-| `"currency"`   | Locale-aware thousands separator and decimal places                |
-| `"date"`       | Locale-aware date string                                           |
-| `"time"`       | Locale-aware time string                                           |
+| `type`         | Description                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `"plain"`      | No-op — passes the value through unchanged                                                                         |
+| `"password"`   | Switches `input[type]` between `"password"` and `"text"` on reveal                                                 |
+| `"creditCard"` | Groups digits as `#### #### #### ####`                                                                             |
+| `"phone"`      | Formats as a local phone number                                                                                    |
+| `"currency"`   | Locale-aware thousands separator and decimal places                                                                |
+| `"date"`       | Locale-aware date string                                                                                           |
+| `"time"`       | Locale-aware time string                                                                                           |
+| `"code"`       | Charset-filtered fixed-length codes (OTP, PIN); options `{ charset: "digits"\|"letters"\|"alphanumeric", length }` |
 
 Custom formatters can be registered at runtime:
 
@@ -83,8 +90,66 @@ Formatter.register('iban', {
 </div>
 ```
 
+### One-time code entry (cells)
+
+```html
+<div
+  data-controller="input-formatter"
+  data-input-formatter-format-value="code"
+  data-input-formatter-options-value='{"charset":"digits","length":6}'
+>
+  <label for="otp" class="sr-only">Verification code</label>
+  <div class="cells-row">
+    <div data-input-formatter-target="cell"></div>
+    <div data-input-formatter-target="cell"></div>
+    <div data-input-formatter-target="cell"></div>
+    <div data-input-formatter-target="cell"></div>
+    <div data-input-formatter-target="cell"></div>
+    <div data-input-formatter-target="cell"></div>
+  </div>
+  <input
+    id="otp"
+    data-input-formatter-target="input"
+    autocomplete="one-time-code"
+    inputmode="numeric"
+    maxlength="6"
+    data-action="input->input-formatter#onInput focus->input-formatter#onFocus blur->input-formatter#onBlur"
+  />
+</div>
+```
+
+Cells are decoration; style them via `[data-filled]`, `[data-caret]`, `[data-group-end]`, `[data-inactive]`. See [ARIA.md's Code Input pattern](../../../ARIA.md) for the overlay/labeling requirements.
+
+### Credit card formatting (grouped cells)
+
+Rendering exactly `groups.length` cells (instead of one cell per digit) puts the plumber into
+grouped mode: each cell displays its whole group of digits. Separators between cells (e.g. a
+dash) are authored HTML, never inserted by the plumber — see
+[character-cells](../plumber/character-cells.md#grouped-mode).
+
+```html
+<div data-controller="input-formatter" data-input-formatter-format-value="creditCard">
+  <div class="cells-row">
+    <span data-input-formatter-target="cell"></span>
+    <span aria-hidden="true">-</span>
+    <span data-input-formatter-target="cell"></span>
+    <span aria-hidden="true">-</span>
+    <span data-input-formatter-target="cell"></span>
+    <span aria-hidden="true">-</span>
+    <span data-input-formatter-target="cell"></span>
+  </div>
+  <input
+    data-input-formatter-target="input"
+    autocomplete="cc-number"
+    inputmode="numeric"
+    maxlength="16"
+    data-action="input->input-formatter#onInput focus->input-formatter#onFocus blur->input-formatter#onBlur"
+  />
+</div>
+```
+
 ## Accessibility
 
-- The `toggle` button must carry `aria-label` describing the action: `"Show password"` / `"Hide password"`.
-- `aria-pressed` is managed automatically — initialised to `"false"`, flipped to `"true"` when the value is revealed.
 - Password `type` attribute switches between `"password"` (masked) and `"text"` (revealed), so screen readers announce the field type correctly.
+- See [ARIA.md's Password Reveal pattern](../../../ARIA.md) for the `toggle` button's `aria-label`/`aria-pressed` requirements.
+- Cell display: see [ARIA.md's Code Input pattern](../../../ARIA.md).

data/vendor/controller/docs/modal.md

@@ -53,8 +53,5 @@ Focus is trapped inside `modal` target using `FocusTrap`. Escape key and click-o
 
 ## Accessibility
 
-- Focus moves into the modal on open; returns to the trigger on close
-- Focus is trapped — Tab/Shift+Tab cycle within the modal
-- Escape closes the modal
 - `body` scroll is locked while open (custom mode)
-- Status announcements via `aria-live` on open/close
+- See [ARIA.md's Modal pattern](../../../ARIA.md) for focus management and the status-announcement contract

data/vendor/controller/docs/popover.md

@@ -108,6 +108,4 @@ Selection events (from combobox sub-controllers, menu items, etc.) can be wired
 
 ## Accessibility
 
-- `trigger` should have `aria-haspopup` describing the popup type; `aria-expanded` is toggled automatically.
-- `panel` should have an appropriate `role` (`dialog`, `tooltip`, `listbox`, etc.).
-- Esc and outside-click both close the panel; focus returns to the `trigger` on close.
+See [ARIA.md's Popover pattern](../../../ARIA.md) for role, `aria-haspopup`/`aria-expanded`, and focus-return requirements.

data/vendor/controller/docs/progress.md

@@ -0,0 +1,82 @@
+# Progress
+
+Value-driven progress indicator supporting three render variants: a linear bar, an SVG ring, and a native `<meter>`.
+
+## Stimulus Identifier
+
+`progress`
+
+## Targets
+
+| Name    | Element                           | Purpose                                                                             |
+| ------- | --------------------------------- | ----------------------------------------------------------------------------------- |
+| `fill`  | `<div>` (bar) / `<circle>` (ring) | Element whose `width` (bar) or `stroke-dasharray`/`stroke-dashoffset` (ring) is set |
+| `meter` | `<meter>`                         | Present only for `variant: "meter"` — native element, attributes synced directly    |
+
+## Values
+
+| Name                    | Type    | Default | Purpose                                                                   |
+| ----------------------- | ------- | ------- | ------------------------------------------------------------------------- |
+| `variant`               | String  | `"bar"` | `"bar"` \| `"ring"` \| `"meter"`                                          |
+| `current`               | Number  | `0`     | Current value                                                             |
+| `min`                   | Number  | `0`     | Range minimum                                                             |
+| `max`                   | Number  | `100`   | Range maximum                                                             |
+| `optimum`               | Number  | —       | Meter-only; maps to native `<meter optimum>`                              |
+| `low`                   | Number  | —       | Meter-only; maps to native `<meter low>`                                  |
+| `high`                  | Number  | —       | Meter-only; maps to native `<meter high>`                                 |
+| `indeterminate`         | Boolean | `false` | Suppresses `aria-valuenow`; toggles the `sp-progress-indeterminate` class |
+| `indeterminateFraction` | Number  | `0.25`  | Static bar width / ring arc fraction rendered while indeterminate         |
+
+## Methods
+
+| Method                       | Wired via               | Purpose                                                                                                   |
+| ---------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| `setValue(value)`            | —                       | Programmatic API — clamps to `[min, max]`, updates `currentValue`, dispatches `progress:changed`          |
+| `currentValueChanged(value)` | Stimulus value callback | Recalculates fill/meter attrs whenever `current` changes (covers `setValue()` and direct attribute edits) |
+
+## Dispatches
+
+| Event              | Detail                | When                                 |
+| ------------------ | --------------------- | ------------------------------------ |
+| `progress:changed` | `{ value, min, max }` | After `setValue()` updates the value |
+
+## Example HTML
+
+```html
+<!-- Bar -->
+<div
+  role="progressbar"
+  data-controller="progress"
+  data-progress-current-value="30"
+  data-progress-min-value="0"
+  data-progress-max-value="100"
+>
+  <div data-progress-target="fill"></div>
+</div>
+
+<!-- Ring -->
+<svg
+  role="progressbar"
+  data-controller="progress"
+  data-progress-variant-value="ring"
+  data-progress-current-value="25"
+  data-progress-max-value="100"
+>
+  <circle data-progress-target="fill" r="40"></circle>
+</svg>
+
+<!-- Meter -->
+<meter
+  data-controller="progress"
+  data-progress-variant-value="meter"
+  data-progress-target="meter"
+  data-progress-current-value="40"
+  data-progress-min-value="0"
+  data-progress-max-value="100"
+></meter>
+
+<!-- Indeterminate -->
+<div role="progressbar" data-controller="progress" data-progress-indeterminate-value="true">
+  <div data-progress-target="fill"></div>
+</div>
+```

data/vendor/controller/docs/reorderable.md

@@ -0,0 +1,82 @@
+# Reorderable
+
+Reorders a vertical or horizontal list of items via pointer drag (a dedicated handle) or keyboard (`Alt+Arrow`, axis depends on `orientation`). No third-party drag library — built on the native Pointer Events API, backed by the [`Reorderable` plumber](../plumber/reorderable.md). Plain Arrow/Home/End keys move focus only, via [`RovingTabIndex`](../utility/accessibility.md).
+
+## Stimulus Identifier
+
+`reorderable`
+
+## Targets
+
+| Name      | Element                                     | Purpose                                                                            |
+| --------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `item`    | Each reorderable row (`<li>`, `<tr>`, etc.) | Must have a stable `id` to appear in the `reorderable:reordered` event's `itemIds` |
+| `handle`  | Drag grip within each `item`                | The only pointer-drag surface — wire `pointerdown`/`pointermove`/`pointerup` to it |
+| `trigger` | The `<a>`/`<button>` inside an item, if any | Neutralized (via `aria-disabled`/`tabindex`) while `editingValue` is `true`        |
+
+## Values
+
+| Name          | Type    | Default      | Purpose                                                                                                                                                                                                                                                      |
+| ------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `moveKey`     | String  | `"Alt"`      | Modifier key that, combined with the move keys below on a focused item, moves it. One of `Alt`, `Control`, `Shift`, `Meta`.                                                                                                                                  |
+| `editing`     | Boolean | `false`      | While `true`, pointer drag and `Alt+Arrow` move are active and every `trigger` target is neutralized. While `false`, drag/keyboard-move are inert no-ops and every `trigger` behaves normally. Plain Arrow/Home/End focus movement is unaffected either way. |
+| `orientation` | String  | `"vertical"` | Reorder axis: `"vertical"` or `"horizontal"`. Also passed through to [`RovingTabIndex`](../utility/accessibility.md).                                                                                                                                        |
+
+## Actions
+
+| Name            | Purpose                                                                                                    |
+| --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `onPointerDown` | Wire to `pointerdown` on the `handle` target — starts a drag (no-op unless `editingValue`)                 |
+| `onPointerMove` | Wire to `pointermove` on the `handle` target — live-reorders while dragging (no-op unless `editingValue`)  |
+| `onPointerUp`   | Wire to `pointerup` on the `handle` target — ends the drag (no-op unless `editingValue`)                   |
+| `toggleEditing` | Flips `editingValue` — wire to e.g. `click->reorderable#toggleEditing` on an app-provided Edit/Done button |
+| `enterEditing`  | Sets `editingValue` to `true` explicitly                                                                   |
+| `exitEditing`   | Sets `editingValue` to `false` explicitly                                                                  |
+
+## Keyboard
+
+| Key                                                                                  | Behaviour                                                              |
+| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| `ArrowDown`/`ArrowUp` (vertical) or `ArrowLeft`/`ArrowRight` (horizontal)            | Focus next/previous item (wraps) — unchanged `RovingTabIndex` behavior |
+| `Home` / `End`                                                                       | Focus first/last item                                                  |
+| `Alt+ArrowDown` (vertical) / `Alt+ArrowRight` (horizontal, `Left` under `dir="rtl"`) | Move the focused item forward one position, keeps focus on it          |
+| `Alt+ArrowUp` (vertical) / `Alt+ArrowLeft` (horizontal, `Right` under `dir="rtl"`)   | Move the focused item back one position, keeps focus on it             |
+
+## Dispatches
+
+| Event                   | Detail                  | When                                                                                              |
+| ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------- |
+| `reorderable:reordered` | `{ itemIds: string[] }` | After a drag ends or a keyboard move completes. Items without an `id` are omitted from `itemIds`. |
+
+## Example HTML
+
+```html
+<ul data-controller="reorderable">
+  <li id="row-1" data-reorderable-target="item" tabindex="0">
+    <span
+      data-reorderable-target="handle"
+      data-action="pointerdown->reorderable#onPointerDown pointermove->reorderable#onPointerMove pointerup->reorderable#onPointerUp"
+    >
+      ::
+    </span>
+    First item
+  </li>
+  <li id="row-2" data-reorderable-target="item" tabindex="-1">
+    <span
+      data-reorderable-target="handle"
+      data-action="pointerdown->reorderable#onPointerDown pointermove->reorderable#onPointerMove pointerup->reorderable#onPointerUp"
+    >
+      ::
+    </span>
+    Second item
+  </li>
+</ul>
+```
+
+## Notes
+
+- Persistence is not built in — listen for `reorderable:reordered` and send `event.detail.itemIds` to your backend.
+- Single-list only. Grid orientation and cross-list drag are not supported.
+- The dragged/moved item is repositioned live in the DOM — there is no placeholder or ghost element.
+- See [ARIA.md's Reorderable pattern](../../../ARIA.md) for the drag/keyboard-move focus-and-announcement contract and the `trigger` neutralization rules.
+- Pointer clicks on a `trigger` are not blocked by JS. Apps/themes must add their own CSS rule to block them while editing, e.g. `[data-reorderable-editing-value="true"] [data-reorderable-target="trigger"] { pointer-events: none }` — keeps the controller content-agnostic about link/button internals.

data/vendor/controller/docs/visibility.md

@@ -0,0 +1,31 @@
+# visibility
+
+Shows/hides a `content` element, keeping it within the viewport and dismissing it on click-outside. Backed by the `Visibility`, `Shifter`, and `Dismisser` plumbers.
+
+## Targets
+
+| Target    | Description                                                                       |
+| --------- | --------------------------------------------------------------------------------- |
+| `content` | Element to show/hide. Optional — `toggle()`/`dismissed()` are no-ops when absent. |
+
+## Methods
+
+| Method        | Wired via         | Description                                                                |
+| ------------- | ----------------- | -------------------------------------------------------------------------- |
+| `toggle()`    | `data-action`     | Shows `content` if hidden (shifting it into viewport), hides it if visible |
+| `dismissed()` | Dismisser plumber | Plumber callback — hides `content` on click-outside                        |
+
+## Example
+
+```html
+<div data-controller="visibility">
+  <button data-action="visibility#toggle">Toggle</button>
+  <div data-visibility-target="content" hidden>Content</div>
+</div>
+```
+
+## Notes
+
+- See [docs/plumber/visibility.md](../plumber/visibility.md) for the show/hide API and dispatched events.
+- See [docs/plumber/shifter.md](../plumber/shifter.md) for the viewport-shifting behavior applied to `content` on show.
+- See [docs/component/dismisser.md](dismisser.md) for click-outside-to-dismiss behavior.