stimulus_plumbers 0.4.8 → 0.4.9

data/vendor/component/manifest.json

@@ -0,0 +1,212 @@
+{
+  "calendar-decade": {
+    "actions": [],
+    "listens": [
+      "selected"
+    ],
+    "targets": [
+      "grid"
+    ],
+    "values": []
+  },
+  "calendar-decade-selector": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "calendar-month": {
+    "actions": [],
+    "listens": [
+      "selected"
+    ],
+    "targets": [
+      "daysOfMonth",
+      "daysOfWeek"
+    ],
+    "values": [
+      "month",
+      "year"
+    ]
+  },
+  "calendar-month-selector": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "calendar-year": {
+    "actions": [],
+    "listens": [
+      "selected"
+    ],
+    "targets": [
+      "grid"
+    ],
+    "values": []
+  },
+  "calendar-year-selector": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "checklist": {
+    "actions": [
+      "onChange"
+    ],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "clipboard": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "combobox-date": {
+    "actions": [],
+    "listens": [
+      "selected"
+    ],
+    "targets": [],
+    "values": []
+  },
+  "combobox-dropdown": {
+    "actions": [
+      "onNavigate",
+      "select"
+    ],
+    "listens": [
+      "selected"
+    ],
+    "targets": [],
+    "values": []
+  },
+  "combobox-time": {
+    "actions": [
+      "onNavigate",
+      "select"
+    ],
+    "listens": [
+      "selected"
+    ],
+    "targets": [],
+    "values": []
+  },
+  "dismisser": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "flipper": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "input-clearable": {
+    "actions": [
+      "clear"
+    ],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "input-combobox": {
+    "actions": [
+      "onInput"
+    ],
+    "listens": [
+      "changed"
+    ],
+    "targets": [],
+    "values": []
+  },
+  "input-formatter": {
+    "actions": [
+      "toggle"
+    ],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "modal": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "panner": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "popover": {
+    "actions": [
+      "close",
+      "open",
+      "toggle"
+    ],
+    "listens": [],
+    "targets": [],
+    "values": []
+  },
+  "progress": {
+    "actions": [],
+    "listens": [],
+    "targets": [
+      "fill",
+      "meter"
+    ],
+    "values": [
+      "current",
+      "high",
+      "indeterminate",
+      "low",
+      "max",
+      "min",
+      "optimum",
+      "variant"
+    ]
+  },
+  "reorderable": {
+    "actions": [
+      "onPointerDown",
+      "onPointerMove",
+      "onPointerUp"
+    ],
+    "listens": [],
+    "targets": [
+      "handle",
+      "item",
+      "trigger"
+    ],
+    "values": [
+      "editing",
+      "moveKey",
+      "orientation"
+    ]
+  },
+  "timeline": {
+    "actions": [
+      "toggle"
+    ],
+    "listens": [],
+    "targets": [
+      "detail",
+      "time",
+      "trigger"
+    ],
+    "values": []
+  },
+  "visibility": {
+    "actions": [],
+    "listens": [],
+    "targets": [],
+    "values": []
+  }
+}

data/vendor/controller/docs/calendar.md

@@ -100,11 +100,8 @@ Click-handling is wired internally — `calendar-month` handles clicks on its ow
 
 ## 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"`
+- See [ARIA.md's Calendar / Date Picker pattern](../../../ARIA.md) for grid roles, selection/disabled state, and keyboard navigation
 
 ---
 
@@ -196,7 +193,7 @@ Decade-view grid controller — renders a 12-year grid and dispatches a `calenda
 
 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`.
+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.
 
 ---
 
@@ -204,7 +201,7 @@ Used with `sp_calendar_turbo_month` (Rails). Pair with `combobox-date` exactly a
 
 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).
+Used with `sp_calendar_turbo_year` (Rails). See [docs/plumber/calendar-selector.md](../plumber/calendar-selector.md) for the underlying plumber.
 
 ---
 
@@ -212,4 +209,4 @@ Used with `sp_calendar_turbo_year` (Rails).
 
 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).
+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/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

@@ -85,6 +85,5 @@ Formatter.register('iban', {
 
 ## 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.

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.