stimulus_plumbers 0.4.5 → 0.4.9

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

@@ -0,0 +1,89 @@
+# input-formatter
+
+Formats, masks, and reveals values written to an input element. Handles password reveal toggling and structured display formatting for credit cards, phone numbers, currencies, dates, and times.
+
+> When co-located with `input-combobox`, see [combobox.md](combobox.md) for the full event flow and wiring.
+
+## 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 |
+
+## 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()`  |
+
+## Methods
+
+| Method            | Wired via                | Description                                                                                    |
+| ----------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
+| `format(value)`   | —                        | Programmatic API — normalises, formats/masks, writes to `input` target, dispatches `formatted` |
+| `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)`                    |
+
+## Dispatches
+
+| Event                       | Detail      | When                                    |
+| --------------------------- | ----------- | --------------------------------------- |
+| `input-formatter:formatted` | `{ value }` | After every write to the `input` target |
+
+## 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                                           |
+
+Custom formatters can be registered at runtime:
+
+```js
+import { Formatter } from '@stimulus-plumbers/controllers';
+
+Formatter.register('iban', {
+  normalize: (raw) => raw.replace(/\s/g, '').toUpperCase(),
+  validate: (value) => /^[A-Z]{2}\d{2}[A-Z0-9]+$/.test(value),
+  format: (value) => value.replace(/(.{4})/g, '$1 ').trim(),
+});
+```
+
+## Examples
+
+### Password reveal
+
+```html
+<div data-controller="input-formatter" data-input-formatter-format-value="password">
+  <input type="password" data-input-formatter-target="input" />
+  <button
+    type="button"
+    aria-label="Show password"
+    aria-pressed="false"
+    data-input-formatter-target="toggle"
+    data-action="click->input-formatter#toggle"
+  ></button>
+</div>
+```
+
+### Credit card formatting
+
+```html
+<div data-controller="input-formatter" data-input-formatter-format-value="creditCard">
+  <input type="text" data-input-formatter-target="input" />
+</div>
+```
+
+## Accessibility
+
+- 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

@@ -0,0 +1,57 @@
+# modal
+
+Implements the [WAI-ARIA Dialog (Modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/). Supports both native `<dialog>` elements and custom overlay implementations.
+
+## Targets
+
+| Target    | Description                                                 |
+| --------- | ----------------------------------------------------------- |
+| `modal`   | The dialog element (required)                               |
+| `overlay` | Optional wrapper shown/hidden around `modal` in custom mode |
+
+## Methods
+
+| Method         | Wired via                 | Description                                                                    |
+| -------------- | ------------------------- | ------------------------------------------------------------------------------ |
+| `open(event)`  | `data-action`             | Action — opens the modal, traps focus inside                                   |
+| `close(event)` | `data-action`, Escape key | Action — closes the modal, restores focus to trigger                           |
+| `dismissed()`  | Dismisser plumber         | Plumber callback — called on click-outside (custom mode only); calls `close()` |
+
+## Native `<dialog>` usage
+
+```html
+<div data-controller="modal">
+  <button data-action="modal#open">Open</button>
+
+  <dialog data-modal-target="modal" aria-labelledby="modal-title" aria-modal="true">
+    <h2 id="modal-title">Confirm action</h2>
+    <p>Are you sure?</p>
+    <button data-action="modal#close">Cancel</button>
+    <button>Confirm</button>
+  </dialog>
+</div>
+```
+
+The browser handles backdrop rendering. Clicking outside the dialog closes it via `onBackdropClick` (an internal handler, not part of the public API).
+
+## Custom overlay usage
+
+```html
+<div data-controller="modal">
+  <button data-action="modal#open">Open</button>
+
+  <div data-modal-target="overlay" hidden>
+    <div data-modal-target="modal" role="dialog" aria-modal="true" aria-labelledby="modal-title">
+      <h2 id="modal-title">Title</h2>
+      <button data-action="modal#close">Close</button>
+    </div>
+  </div>
+</div>
+```
+
+Focus is trapped inside `modal` target using `FocusTrap`. Escape key and click-outside (via `dismissed()`) both close the modal.
+
+## Accessibility
+
+- `body` scroll is locked while open (custom mode)
+- See [ARIA.md's Modal pattern](../../../ARIA.md) for focus management and the status-announcement contract

data/vendor/controller/docs/panner.md

@@ -0,0 +1,24 @@
+# panner
+
+Keeps a content element within the viewport by applying a CSS `translate` transform when the window resizes. Backed by the `Shifter` plumber.
+
+## Targets
+
+| Target    | Description                                                                |
+| --------- | -------------------------------------------------------------------------- |
+| `content` | Element to keep in-viewport. Defaults to the controller element if absent. |
+
+## Example
+
+```html
+<div data-controller="panner">
+  <div data-panner-target="content">
+    <!-- content that must stay visible when the window resizes -->
+  </div>
+</div>
+```
+
+## Notes
+
+- Shifting is skipped when the `content` target is hidden.
+- See [docs/plumber/shifter.md](../plumber/shifter.md) for the full options API (`boundaries`, `events`, `respectMotion`).

data/vendor/controller/docs/popover.md

@@ -0,0 +1,111 @@
+# popover
+
+Shows and hides a panel with optional remote loading. Owns visibility, `aria-expanded`, outside-click dismissal, and focus management. Backed by the `Visibility`, `Dismisser`, and `ContentLoader` plumbers.
+
+This controller is also the visibility/dismissal layer for the combobox family — `input-combobox` runs alongside it and delegates open/close to `popover` (see [combobox docs](./combobox.md)).
+
+## Targets
+
+| Target     | Description                                                                |
+| ---------- | -------------------------------------------------------------------------- |
+| `trigger`  | The activator element — opens/toggles the panel and tracks `aria-expanded` |
+| `panel`    | The element to show/hide (and load remote content into)                    |
+| `template` | Optional `<template>` or element whose HTML is used as initial content     |
+| `loader`   | Optional element shown during remote load                                  |
+
+## Values
+
+| Value           | Type    | Default          | Description                                          |
+| --------------- | ------- | ---------------- | ---------------------------------------------------- |
+| `url`           | String  | —                | Remote URL to fetch content from                     |
+| `reload`        | String  | `"never"`        | When to reload: `"never"` \| `"always"` \| `"stale"` |
+| `staleAfter`    | Number  | `3600`           | Seconds after which content is considered stale      |
+| `loadedAt`      | String  | —                | ISO timestamp of last load (set automatically)       |
+| `closeOnSelect` | Boolean | `true`           | Whether a `#closeOnSelect` call dismisses the panel  |
+| `announceOpen`  | String  | `"Panel opened"` | Screen-reader announcement on panel show             |
+| `announceClose` | String  | `"Panel closed"` | Screen-reader announcement on panel hide             |
+
+## Methods
+
+| Method                       | Wired via             | Description                                                                                                 |
+| ---------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `open()`                     | `data-action`         | Action — shows the panel                                                                                    |
+| `close()`                    | `data-action`         | Action — hides the panel (used by Esc, close buttons, outside-click)                                        |
+| `toggle()`                   | `data-action`         | Action — shows when hidden, hides when visible                                                              |
+| `closeOnSelect()`            | `data-action`         | Action — hides the panel only when `closeOnSelect` value is `true`; used by selection events                |
+| `shown()`                    | Visibility plumber    | Plumber callback — triggers `load()`, then moves focus into the panel                                       |
+| `hidden()`                   | Visibility plumber    | Plumber callback — returns focus to the `trigger`                                                           |
+| `dismissed()`                | Dismisser plumber     | Plumber callback — closes the panel on outside click                                                        |
+| `canLoad()`                  | ContentLoader plumber | Plumber callback (gate) — returns `false` for `<turbo-frame>` panels (sets `src` instead); `true` otherwise |
+| `contentLoading()`           | ContentLoader plumber | Plumber callback — shows the `loader` target while fetching                                                 |
+| `contentLoaded({ content })` | ContentLoader plumber | Plumber callback — inserts fetched content into the `panel` target, hides `loader`                          |
+| `contentLoader()`            | ContentLoader plumber | Plumber callback — returns static content from `template` target (if no URL)                                |
+
+## Examples
+
+### Static popover
+
+```html
+<div data-controller="popover">
+  <button
+    data-action="click->popover#toggle keydown.esc->popover#close"
+    data-popover-target="trigger"
+    aria-haspopup="dialog"
+    aria-expanded="false"
+    aria-controls="opts"
+  >
+    Open
+  </button>
+
+  <div id="opts" data-popover-target="panel" hidden role="dialog" aria-label="Options">
+    <p>Popover content</p>
+    <button data-action="click->popover#close">Close</button>
+  </div>
+</div>
+```
+
+### Remote content (fetch on show)
+
+```html
+<div
+  data-controller="popover"
+  data-popover-url-value="/help/tooltip"
+  data-popover-reload-value="stale"
+  data-popover-stale-after-value="300"
+>
+  <button data-action="click->popover#toggle" data-popover-target="trigger">Help</button>
+
+  <div data-popover-target="panel" hidden>
+    <div data-popover-target="loader" hidden>Loading…</div>
+    <div data-popover-target="template"></div>
+  </div>
+</div>
+```
+
+### Turbo Frame (lazy load)
+
+When the `panel` target is a `<turbo-frame>`, `canLoad()` sets its `src` attribute on show rather than fetching HTML directly.
+
+```html
+<div data-controller="popover" data-popover-url-value="/preview/123">
+  <button data-action="click->popover#toggle" data-popover-target="trigger">Preview</button>
+  <turbo-frame data-popover-target="panel" hidden></turbo-frame>
+</div>
+```
+
+### Keep panel open on select
+
+Selection events (from combobox sub-controllers, menu items, etc.) can be wired to `closeOnSelect`. Set `data-popover-close-on-select-value="false"` to keep the panel open after a selection — useful for multi-step pickers (date ranges, multi-select).
+
+```html
+<div data-controller="popover" data-popover-close-on-select-value="false">
+  ...
+  <ul data-action="my-list:selected->popover#closeOnSelect">
+    …
+  </ul>
+</div>
+```
+
+## Accessibility
+
+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/timeline.md

@@ -0,0 +1,84 @@
+# Timeline
+
+Manages expandable/collapsible timeline event items with keyboard navigation and optional client-side date formatting.
+
+## Stimulus Identifier
+
+`timeline`
+
+## Targets
+
+| Name      | Element                       | Purpose                                                                                 |
+| --------- | ----------------------------- | --------------------------------------------------------------------------------------- |
+| `trigger` | `<button>` inside each `<h3>` | Controls expand/collapse of its associated detail                                       |
+| `detail`  | Collapsible region            | Content shown/hidden via `aria-controls` reference                                      |
+| `time`    | `<time datetime="…">`         | Empty `<time>` elements whose text content is set from `datetime` via `dateFormatValue` |
+
+## Values
+
+| Name         | Type   | Default | Purpose                                                                                                 |
+| ------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------- |
+| `dateFormat` | Object | `{}`    | `Intl.DateTimeFormat` options applied to empty `<time datetime>` elements on connect. No-op when empty. |
+
+## Actions
+
+| Name       | Purpose                                     |
+| ---------- | ------------------------------------------- |
+| `toggle`   | Expands if collapsed, collapses if expanded |
+| `expand`   | Expands the item                            |
+| `collapse` | Collapses the item                          |
+
+## Keyboard
+
+| Key         | Behaviour                      |
+| ----------- | ------------------------------ |
+| `ArrowDown` | Focus next trigger (wraps)     |
+| `ArrowUp`   | Focus previous trigger (wraps) |
+| `Home`      | Focus first trigger            |
+| `End`       | Focus last trigger             |
+
+## Dispatches
+
+| Event                | Detail                | When                              |
+| -------------------- | --------------------- | --------------------------------- |
+| `timeline:expand`    | `{ trigger, detail }` | When an item begins expanding     |
+| `timeline:expanded`  | `{ trigger, detail }` | After an item finishes expanding  |
+| `timeline:collapse`  | `{ trigger, detail }` | When an item begins collapsing    |
+| `timeline:collapsed` | `{ trigger, detail }` | After an item finishes collapsing |
+
+## Example HTML
+
+```html
+<!-- Static timeline with server-rendered date text -->
+<ol data-controller="timeline">
+  <li>
+    <time datetime="2024-01-15">January 2024</time>
+    <h3>Event title</h3>
+  </li>
+</ol>
+
+<!-- Static timeline with client-side date formatting -->
+<ol data-controller="timeline" data-timeline-date-format-value='{"month":"long","year":"numeric","day":"numeric"}'>
+  <li>
+    <time datetime="2024-01-15"></time>
+    <h3>Event title</h3>
+  </li>
+</ol>
+
+<!-- Interactive timeline with expandable details -->
+<ol data-controller="timeline">
+  <li>
+    <h3>
+      <button
+        data-timeline-target="trigger"
+        data-action="timeline#toggle"
+        aria-expanded="false"
+        aria-controls="detail-1"
+      >
+        Event title
+      </button>
+    </h3>
+    <div id="detail-1" data-timeline-target="detail" hidden>Detail content</div>
+  </li>
+</ol>
+```

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.

data/vendor/controller/guide.md

@@ -0,0 +1,16 @@
+# Guide
+
+For a non-Rails / plain JS consumer of `@stimulus-plumbers/controllers`. Rails apps get this wired
+automatically via the `stimulus_plumbers` gem's `sp_*` helpers — skip this guide for Rails.
+
+```bash
+npm install @stimulus-plumbers/controllers
+```
+
+Import and register each controller you use with your Stimulus application — see
+[README.md](../README.md#setup) for the full import + `application.register(...)` list and the
+[Controllers table](../README.md#controllers) for identifiers and their docs.
+
+Interactive components (combobox, popover, calendar) expect their `data-controller` attributes to
+already be present in the rendered HTML — Rails apps get these from `sp_*` helpers; a plain-JS setup
+must add them manually per each controller's doc.