stimulus_plumbers 0.4.5 → 0.4.8

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,46 @@
+# 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.
+- 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.
+
+## 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.

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

@@ -0,0 +1,90 @@
+# 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
+
+- 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.

data/vendor/controller/docs/modal.md

@@ -0,0 +1,60 @@
+# 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
+
+- 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

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,113 @@
+# 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
+
+- `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.

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_plumbers
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.8
 platform: ruby
 authors:
 - Ryan Chang
@@ -64,6 +64,8 @@ files:
 - docs/component/popover.md
 - docs/component/theme.md
 - docs/component/timeline.md
+- docs/guide.md
+- lib/generators/stimulus_plumbers/install/install_generator.rb
 - lib/stimulus_plumbers.rb
 - lib/stimulus_plumbers/components/avatar.rb
 - lib/stimulus_plumbers/components/button.rb
@@ -131,6 +133,8 @@ files:
 - lib/stimulus_plumbers/form/fields/label.rb
 - lib/stimulus_plumbers/form/fields/label/floating.rb
 - lib/stimulus_plumbers/form/fields/renderer.rb
+- lib/stimulus_plumbers/generators/css_entrypoint.rb
+- lib/stimulus_plumbers/generators/tokens_directive.rb
 - lib/stimulus_plumbers/helpers.rb
 - lib/stimulus_plumbers/helpers/avatar_helper.rb
 - lib/stimulus_plumbers/helpers/button_helper.rb
@@ -175,7 +179,21 @@ files:
 - lib/stimulus_plumbers/themes/schema/link/ranges.rb
 - lib/stimulus_plumbers/themes/schema/ranges.rb
 - lib/stimulus_plumbers/version.rb
-- vendor/controllers.manifest.json
+- lib/tasks/stimulus_plumbers.rake
+- vendor/ARIA.md
+- vendor/controller/docs/calendar.md
+- vendor/controller/docs/clipboard.md
+- vendor/controller/docs/combobox.md
+- vendor/controller/docs/dismisser.md
+- vendor/controller/docs/flipper.md
+- vendor/controller/docs/input-clearable.md
+- vendor/controller/docs/input-formatter.md
+- vendor/controller/docs/modal.md
+- vendor/controller/docs/panner.md
+- vendor/controller/docs/popover.md
+- vendor/controller/docs/timeline.md
+- vendor/controller/guide.md
+- vendor/controller/manifest.json
 homepage: https://github.com/ryancyq/stimulus-plumbers
 licenses:
 - MIT