stimulus_plumbers 0.4.8 → 0.4.9

data/app/assets/stylesheets/stimulus_plumbers/tokens.css

@@ -8,52 +8,52 @@
 
 :root {
   /* ── Semantic colors ─────────────────────────────────────────────────── */
-  --sp-color-primary:        oklch(55% 0.2 250);
-  --sp-color-primary-fg:     oklch(98% 0.01 250);
-  --sp-color-primary-border: oklch(65% 0.2 250);
-  --sp-color-primary-ring:   oklch(75% 0.15 250);
-
-  --sp-color-secondary:        oklch(55% 0.05 250);
-  --sp-color-secondary-fg:     oklch(98% 0.01 250);
-  --sp-color-secondary-border: oklch(65% 0.05 250);
-  --sp-color-secondary-ring:   oklch(75% 0.05 250);
-
-  --sp-color-destructive:        oklch(55% 0.22 25);
-  --sp-color-destructive-fg:     oklch(98% 0.01 25);
-  --sp-color-destructive-border: oklch(65% 0.22 25);
-  --sp-color-destructive-ring:   oklch(75% 0.18 25);
-
-  --sp-color-success:        oklch(52% 0.18 145);
-  --sp-color-success-fg:     oklch(98% 0.01 145);
-  --sp-color-success-border: oklch(62% 0.18 145);
-  --sp-color-success-ring:   oklch(72% 0.12 145);
-
-  --sp-color-warning:        oklch(68% 0.17 65);
-  --sp-color-warning-fg:     oklch(98% 0.01 65);
-  --sp-color-warning-border: oklch(78% 0.17 65);
-  --sp-color-warning-ring:   oklch(88% 0.10 65);
-
-  --sp-color-info:        oklch(55% 0.18 220);
-  --sp-color-info-fg:     oklch(98% 0.01 220);
-  --sp-color-info-border: oklch(65% 0.18 220);
-  --sp-color-info-ring:   oklch(75% 0.12 220);
-
-  --sp-color-error:          oklch(40% 0.20 25);
-
-  --sp-color-muted:        oklch(96% 0.02 250);
-  --sp-color-muted-fg:     oklch(45% 0.05 250);
-  --sp-color-muted-border: oklch(88% 0.02 250);
-  --sp-color-muted-ring:   oklch(82% 0.02 250);
-
-  --sp-color-border:         oklch(90% 0.02 250);
-  --sp-color-border-strong:  oklch(75% 0.03 250);
-  --sp-color-bg:             oklch(100% 0 0);
-  --sp-color-bg-muted:       oklch(96% 0.02 250);
-  --sp-color-fg:             oklch(10% 0.02 250);
+  --sp-color-primary:        oklch(50% 0.11 140);
+  --sp-color-primary-fg:     oklch(98% 0.01 140);
+  --sp-color-primary-border: oklch(60% 0.11 140);
+  --sp-color-primary-ring:   oklch(58% 0.15 140);
+
+  --sp-color-secondary:        oklch(50% 0.03 140);
+  --sp-color-secondary-fg:     oklch(98% 0.01 140);
+  --sp-color-secondary-border: oklch(60% 0.03 140);
+  --sp-color-secondary-ring:   oklch(70% 0.02 140);
+
+  --sp-color-destructive:        oklch(55% 0.13 30);
+  --sp-color-destructive-fg:     oklch(98% 0.01 30);
+  --sp-color-destructive-border: oklch(65% 0.13 30);
+  --sp-color-destructive-ring:   oklch(76% 0.09 30);
+
+  --sp-color-success:        oklch(46% 0.13 165);
+  --sp-color-success-fg:     oklch(98% 0.01 165);
+  --sp-color-success-border: oklch(56% 0.13 165);
+  --sp-color-success-ring:   oklch(66% 0.09 165);
+
+  --sp-color-warning:        oklch(68% 0.11 85);
+  --sp-color-warning-fg:     oklch(20% 0.02 85);
+  --sp-color-warning-border: oklch(78% 0.11 85);
+  --sp-color-warning-ring:   oklch(88% 0.07 85);
+
+  --sp-color-info:        oklch(55% 0.10 210);
+  --sp-color-info-fg:     oklch(98% 0.01 210);
+  --sp-color-info-border: oklch(65% 0.10 210);
+  --sp-color-info-ring:   oklch(75% 0.07 210);
+
+  --sp-color-error:          oklch(38% 0.16 25);
+
+  --sp-color-muted:        oklch(95% 0.018 68);
+  --sp-color-muted-fg:     oklch(45% 0.05 68);
+  --sp-color-muted-border: oklch(88% 0.015 68);
+  --sp-color-muted-ring:   oklch(82% 0.015 68);
+
+  --sp-color-border:         oklch(88% 0.012 68);
+  --sp-color-border-strong:  oklch(75% 0.02 68);
+  --sp-color-bg:             oklch(99% 0.005 68);
+  --sp-color-bg-muted:       oklch(95% 0.015 68);
+  --sp-color-fg:             oklch(22% 0.02 68);
 
 
   /* ── Component tokens ───────────────────────────────────────────────── */
-  --sp-color-indicator: oklch(75% 0.02 250); /* timeline dot fill */
+  --sp-color-indicator: oklch(78% 0.015 68); /* timeline dot fill */
 
 
   /* ── Focus ring ──────────────────────────────────────────────────────── */
@@ -63,16 +63,16 @@
 
 
   /* ── Avatar palette (10 slots, index chosen by name hash) ────────────── */
-  --sp-avatar-color-1:  oklch(55% 0.15 58);
-  --sp-avatar-color-2:  oklch(54% 0.16 129);
-  --sp-avatar-color-3:  oklch(51% 0.13 233);
-  --sp-avatar-color-4:  oklch(53% 0.10 209);
-  --sp-avatar-color-5:  oklch(53% 0.09 186);
-  --sp-avatar-color-6:  oklch(51% 0.13 161);
-  --sp-avatar-color-7:  oklch(46% 0.22 277);
-  --sp-avatar-color-8:  oklch(49% 0.23 316);
-  --sp-avatar-color-9:  oklch(44% 0.21 16);
-  --sp-avatar-color-10: oklch(48% 0.22 348);
+  --sp-avatar-color-1:  oklch(55% 0.13 40);
+  --sp-avatar-color-2:  oklch(58% 0.12 85);
+  --sp-avatar-color-3:  oklch(52% 0.10 125);
+  --sp-avatar-color-4:  oklch(55% 0.08 150);
+  --sp-avatar-color-5:  oklch(52% 0.09 195);
+  --sp-avatar-color-6:  oklch(50% 0.08 230);
+  --sp-avatar-color-7:  oklch(48% 0.09 320);
+  --sp-avatar-color-8:  oklch(38% 0.15 8);
+  --sp-avatar-color-9:  oklch(45% 0.09 55);
+  --sp-avatar-color-10: oklch(58% 0.10 10);
   --sp-avatar-fg:       oklch(100% 0 0);
 
 
@@ -128,3 +128,8 @@
   /* ── Z-index ─────────────────────────────────────────────────────────── */
   --sp-z-popover: 50;
 }
+
+/* Smooth width changes on the progress bar fill — renders with or without a theme. */
+[data-progress-target="fill"] {
+  transition: width 0.3s ease;
+}

data/docs/architecture.md

@@ -9,8 +9,6 @@ Validation ranges for theme schema params live under `lib/stimulus_plumbers/them
 - If a component branches on the values internally (e.g. `when *FLOATING_TYPES`), the component owns the constant (`Form::Field::FLOATING_TYPES`). The schema references it directly — no alias.
 - If the component only passes the value through to the theme, the schema owns the range (e.g. `Schema::Button::Ranges::TYPE`).
 
-**Namespace rules:**
-
 **Namespaces:**
 
 - `Schema::Ranges` — cross-cutting constants (e.g. `BOOL`)

data/docs/component/avatar.md

@@ -82,3 +82,4 @@ Rails helper for rendering a user avatar — image, initials, or fallback silhou
 - Always renders `role="img"` with `aria-label` set to `name` (when provided).
 - Image `alt` is set to `"[name]'s avatar"`; for anonymous avatars `alt=""` is used.
 - `onerror` on `<img>` clears the `src` to prevent broken-image icons.
+- See [ARIA.md's Avatar / Card / Icon pattern](../../../ARIA.md) for the decorative-vs-meaningful image rule this follows.

data/docs/component/button.md

@@ -133,3 +133,4 @@ When no text is provided, no `<span>` is rendered, and the button becomes square
 - `<button>` always has `type="button"` to prevent accidental form submission.
 - Icon-only buttons must supply an accessible label via `aria: { label: "..." }` in `html_options`.
 - For navigation actions (links), use `sp_link` instead — it renders an `<a>` element.
+- See [ARIA.md's Button pattern](../../../ARIA.md) for the `disabled` attribute requirement.

data/docs/component/calendar.md

@@ -33,10 +33,10 @@ end
 </div>
 ```
 
-| Option           | Description                                                                          |
-| ---------------- | ------------------------------------------------------------------------------------ |
-| `date`           | `Date` — sets `year-value`, `month-value` (0-indexed), `day-value` on the controller |
-| `**html_options` | Forwarded to the `calendar-month` controller root element                            |
+| Option           | Description                                                             |
+| ---------------- | ----------------------------------------------------------------------- |
+| `date`           | `Date` — sets `year-value`, `month-value` (0-indexed) on the controller |
+| `**html_options` | Forwarded to the `calendar-month` controller root element               |
 
 For the JS controller API (targets, values, keyboard behaviour), see the [JS package docs](../../../stimulus-plumbers/docs/component/calendar.md).
 
@@ -50,7 +50,6 @@ For the JS controller API (targets, values, keyboard behaviour), see the [JS pac
   data-controller="calendar-month"
   data-calendar-month-year-value="2024"
   data-calendar-month-month-value="1"
-  data-calendar-month-day-value="15"
   role="grid"
 >
   <!-- days-of-week header row (JS-populated) -->
@@ -206,25 +205,17 @@ Renders all three frames. Used inside a `combobox-date` controller for drill-dow
 
 ```html
 <!-- month view frame — visible by default -->
-<turbo-frame id="calendar-month-frame" data-combobox-date-target="monthView">
+<turbo-frame id="calendar-month-frame">
   <!-- sp_calendar_turbo_month output -->
 </turbo-frame>
 
 <!-- year view frame — hidden until drill-up -->
-<turbo-frame
-  id="calendar-year-frame"
-  hidden
-  data-combobox-date-target="yearView"
->
+<turbo-frame id="calendar-year-frame" hidden>
   <!-- sp_calendar_turbo_year output -->
 </turbo-frame>
 
 <!-- decade view frame — hidden until drill-up twice -->
-<turbo-frame
-  id="calendar-decade-frame"
-  hidden
-  data-combobox-date-target="decadeView"
->
+<turbo-frame id="calendar-decade-frame" hidden>
   <!-- sp_calendar_turbo_decade output -->
 </turbo-frame>
 ```

data/docs/component/checklist.md

@@ -0,0 +1,153 @@
+# Checklist
+
+Rails helper for rendering an accessible group of checkbox-style items. Items render as native `<label><input type="checkbox"></label>` pairs, no `<li>` wrapper — see [ARIA.md's Checklist pattern](../../../ARIA.md) for why.
+
+## Helper
+
+### `sp_checklist`
+
+```erb
+<%= sp_checklist(label: "Groceries") do |checklist| %>
+  <%= checklist.item("Buy milk", checked: true) %>
+  <%= checklist.item("Walk the dog", checked: false) %>
+<% end %>
+
+<%# With a description %>
+<%= sp_checklist(label: "Onboarding") do |checklist| %>
+  <%= checklist.item("Verify email", checked: true) do |item| %>
+    <% item.with_description("Sent to you at signup") %>
+  <% end %>
+<% end %>
+
+<%# Read-only summary (e.g. an activity feed) %>
+<%= sp_checklist(label: "Completed steps") do |checklist| %>
+  <%= checklist.item("Account created", checked: true, readonly: true) %>
+<% end %>
+```
+
+| Option              | Default        | Description                                                                                                      |
+| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `label:`            | `nil`          | Sets `aria-label` on the group wrapper                                                                           |
+| `labelledby:`       | `nil`          | Sets `aria-labelledby`; takes precedence over `label:` when both given                                           |
+| `select_all:`       | `false`        | `true` renders a master "select all" toggle wired to the group's items                                           |
+| `select_all_label:` | `"Select all"` | Label text for the master toggle (used as both `aria-label` and visible text); ignored unless `select_all: true` |
+| `**html_options`    | —              | Forwarded to the `<div role="group">`                                                                            |
+
+### `select_all:`
+
+```erb
+<%= sp_checklist(label: "Groceries", select_all: true, select_all_label: "Select all items") do |checklist| %>
+  <%= checklist.item("Buy milk", checked: true) %>
+  <%= checklist.item("Walk the dog", checked: false) %>
+<% end %>
+```
+
+Renders a master `<label><input type="checkbox"></label>` before the items, wired to the `checklist` Stimulus controller. See [stimulus-plumbers's docs/component/checklist.md](../../../stimulus-plumbers/docs/component/checklist.md) for the controller's targets and actions.
+
+Read-only items (`readonly: true`) are excluded from the master's aggregate state — see [ARIA.md's Checklist pattern](../../../ARIA.md) for why.
+
+### `checklist.item(content, checked:, readonly:, **html_options, &block)`
+
+Renders a `<label>` wrapping a native `<input type="checkbox">`.
+
+| Option           | Default | Description                                                                          |
+| ---------------- | ------- | ------------------------------------------------------------------------------------ |
+| `content`        | `nil`   | Item label — positional arg or via `item.with_title`                                 |
+| `checked:`       | —       | **Required.** Sets `checked`                                                         |
+| `readonly:`      | `false` | `true` renders **disabled** on the input — removed from the tab order, no controller |
+| `**html_options` | —       | Forwarded to the `<label>`                                                           |
+
+### Item slot methods (yielded as `item`)
+
+| Slot method                   | Description                                                   |
+| ----------------------------- | ------------------------------------------------------------- |
+| `item.with_title(text)`       | Title text (pre-populated when positional `content` is given) |
+| `item.with_description(text)` | Secondary text below the title                                |
+
+---
+
+## Rendered HTML Structure
+
+```html
+<div role="group" aria-label="Groceries" class="[checklist theme classes]">
+  <label class="[checklist_item theme classes]">
+    <input
+      type="checkbox"
+      checked
+      data-checklist-target="item"
+      class="[checklist_item_input theme classes]"
+    />
+    <span class="[checklist_item_content theme classes]">
+      <span class="[checklist_item_title theme classes]">Buy milk</span>
+    </span>
+  </label>
+</div>
+```
+
+### `select_all: true`
+
+```html
+<div
+  role="group"
+  aria-label="Groceries"
+  data-controller="checklist"
+  data-action="change->checklist#onChange"
+  class="[checklist theme classes]"
+>
+  <label class="[checklist_item theme classes]">
+    <input
+      type="checkbox"
+      data-checklist-target="master"
+      class="[checklist_item_input theme classes]"
+    />
+    Select all
+  </label>
+
+  <label class="[checklist_item theme classes]">
+    <input
+      type="checkbox"
+      checked
+      data-checklist-target="item"
+      class="[checklist_item_input theme classes]"
+    />
+    ...
+  </label>
+</div>
+```
+
+The master's `checked` state is computed from the items' `checked:` values at render time (all-true renders `checked`; every other case, including mixed, renders unchecked) — the `checklist` controller corrects it to `indeterminate` client-side once connected. See [ARIA.md's Checklist pattern](../../../ARIA.md) for the accepted flash this tradeoff causes in the mixed case.
+
+### Read-only item (`readonly: true`)
+
+```html
+<label class="[checklist_item theme classes]">
+  <input
+    type="checkbox"
+    checked
+    disabled
+    class="[checklist_item_input theme classes]"
+  />
+  ...
+</label>
+```
+
+---
+
+## Theme keys
+
+| Key                          | Element                                        | Variants |
+| ---------------------------- | ---------------------------------------------- | -------- |
+| `checklist`                  | Outer `<div role="group">`                     | —        |
+| `checklist_item`             | Item `<label>`                                 | —        |
+| `checklist_item_input`       | Item/master checkbox `<input>`                 | —        |
+| `checklist_item_content`     | Content wrapper `<span>` (title + description) | —        |
+| `checklist_item_title`       | Title `<span>`                                 | —        |
+| `checklist_item_description` | Description `<span>`                           | —        |
+
+Checked-state styling (strikethrough title) reads the sibling `<input>`'s `:checked` state via Tailwind's `:has()`-based `group-has-checked/checklist-item:` variant — there is no `aria-checked` or `checked:` theme-resolver kwarg to pass.
+
+---
+
+## ARIA
+
+See [ARIA.md's Checklist pattern](../../../ARIA.md) for why items use native `<input type="checkbox">` with no ARIA attributes, the `disabled` read-only behavior, and the `indeterminate` tradeoff for the master toggle.

data/docs/component/icon.md

@@ -10,12 +10,14 @@ Rails helper for rendering a named icon from the active theme's icon registry.
 <%= sp_icon name: "check" %>
 <%= sp_icon name: "spinner", aria: { label: "Loading" }, role: "img" %>
 <%= sp_icon name: "unknown-icon" %>
+<%= sp_icon name: "check", size: :sm %>
 ```
 
-| Option           | Default    | Description                                 |
-| ---------------- | ---------- | ------------------------------------------- |
-| `name`           | (required) | Icon name — looked up in the theme registry |
-| `**html_options` | —          | Forwarded to the root element               |
+| Option           | Default    | Description                                         |
+| ---------------- | ---------- | --------------------------------------------------- |
+| `name`           | (required) | Icon name — looked up in the theme registry         |
+| `size`           | `:lg`      | `:sm` \| `:md` \| `:lg` — theme-resolved size class |
+| `**html_options` | —          | Forwarded to the root element                       |
 
 ---
 
@@ -39,6 +41,6 @@ Rails helper for rendering a named icon from the active theme's icon registry.
 
 ## ARIA
 
-- Icons are **decorative by default** — the theme applies `aria-hidden="true"` so they are invisible to screen readers.
+- The theme applies `aria-hidden="true"` by default (see [ARIA.md's Avatar / Card / Icon pattern](../../../ARIA.md)).
 - For meaningful icons (standalone, no adjacent label), pass `aria: { label: "..." }` and `role: "img"` to override.
 - Button and link icons are rendered internally with `aria-hidden="true"`; callers do not need to set this manually.

data/docs/component/indicator.md

@@ -0,0 +1,55 @@
+# Indicator
+
+Presentational status marker — a colored dot, an animated "pulse" ring, or a numeric badge. No Stimulus controller.
+
+## Helper
+
+### `sp_indicator`
+
+```erb
+<%# Dot — must be paired with an accessible name %>
+<span>
+  <%= sp_indicator(variant: :success) %>
+  <span class="sr-only">Online</span>
+</span>
+
+<%# Pulse %>
+<span>
+  <%= sp_indicator(type: :pulse, variant: :destructive, pulse: true) %>
+  <span class="sr-only">Live</span>
+</span>
+
+<%# Badge %>
+<span>
+  <%= sp_indicator(type: :badge, variant: :primary) { "5" } %>
+  <span class="sr-only">5 unread notifications</span>
+</span>
+```
+
+| Option           | Default    | Description                                                                                                               |
+| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `type:`          | `:dot`     | `:dot` \| `:pulse` \| `:badge` — `:badge` renders the given block as content                                              |
+| `variant:`       | `:primary` | Semantic color token — `:primary` \| `:secondary` \| `:tertiary` \| `:success` \| `:destructive` \| `:warning` \| `:info` |
+| `pulse:`         | `false`    | Adds an animated ring element (`prefers-reduced-motion` suppresses the animation)                                         |
+| `**html_options` | —          | Forwarded to the dot `<span>`                                                                                             |
+
+When `pulse: true`, the dot is wrapped in an extra `<span>` (`indicator_wrapper` theme key) that positions the ring behind the dot — no margin offsets involved.
+
+**Every indicator must be paired with an accessible name** — a visible label or `aria-label`/adjacent `sr-only` text. The component itself renders no text and cannot know the right label; this is enforced by an accessibility test (see `test/accessibility/components/indicator_accessibility_test.rb`), not by the component.
+
+## Legend pattern
+
+To explain what each indicator color means (e.g. a status legend), pair indicators with visible text inside a list — do not rely on color alone:
+
+```erb
+<%= sp_list do |list| %>
+  <%= list.item do |item| %>
+    <% item.with_icon_leading { sp_indicator(variant: :success) } %>
+    <% item.with_title("Online") %>
+  <% end %>
+  <%= list.item do |item| %>
+    <% item.with_icon_leading { sp_indicator(variant: :warning) } %>
+    <% item.with_title("Away") %>
+  <% end %>
+<% end %>
+```

data/docs/component/list.md

@@ -1,6 +1,6 @@
 # List
 
-Rails helper for rendering an accessible list of links, buttons, or grouped sections.
+Rails helper for rendering an accessible list of links, buttons, or grouped sections. For a flat, drag/keyboard-reorderable list, see [`OrderedList`](ordered_list.md) instead.
 
 ## Helper
 
@@ -154,8 +154,7 @@ When `url:` is present and `target: "_blank"` is set, `icon_trailing: "external-
 
 ## ARIA
 
-- Default `role="list"` is appropriate for navigation or command lists.
 - Use `role="menu"` + `role="menuitem"` (via `html_options`) only when items form a widget menu — arrow key navigation must then be wired via a Stimulus controller.
-- `active: true` adds `aria-current="page"` on links and `aria-current="true"` on buttons; pair this with a visual style change so the state is not communicated by color alone.
 - Section titles without `heading_level` use `aria-hidden="true"` on the `<span>` and set `aria-label` on the nested `<ul>` to avoid double-announcing.
 - Nested sections increment the heading level automatically (clamped at `h6`).
+- See [ARIA.md's List pattern](../../../ARIA.md) for the default `role="list"`/`role="listitem"` and `active:` → `aria-current` mapping (pair it with a visual style change so the state isn't communicated by color alone).

data/docs/component/ordered_list.md

@@ -0,0 +1,118 @@
+# OrderedList
+
+Rails helper for a flat, reorderable list — pointer-drag and keyboard reorder via the [`reorderable`](../../../stimulus-plumbers/docs/component/reorderable.md) JS controller. Unlike [`List`](list.md), item order is semantic content (`<ol>`, not `<ul>`), there are no sections, and every item has a pointer drag surface.
+
+## Helper
+
+### `sp_ordered_list`
+
+```erb
+<%# Whole-item handle (default), content-only rows %>
+<%= sp_ordered_list do |list| %>
+  <%= list.item("First", id: "item-1") %>
+  <%= list.item("Second", id: "item-2") %>
+<% end %>
+
+<%# Links + a dedicated leading-icon handle, editing enabled %>
+<%= sp_ordered_list(editing: true) do |list| %>
+  <%= list.item(id: "link-1", url: "/", handle: :leading) do |item| %>
+    <% item.with_title("Dashboard") %>
+  <% end %>
+<% end %>
+```
+
+| Option           | Default  | Description                                                                                                                                                                                                                                                 |
+| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `move_key:`      | `"Alt"`  | Maps to `data-reorderable-move-key-value`. One of `Alt`, `Control`, `Shift`, `Meta`.                                                                                                                                                                        |
+| `editing:`       | `false`  | Initial render-time state, maps to `data-reorderable-editing-value`.                                                                                                                                                                                        |
+| `orientation:`   | `nil`    | Maps to `data-reorderable-orientation-value` when set; omitted entirely otherwise (JS controller defaults to `"vertical"`). See the [reorderable JS controller doc](../../../stimulus-plumbers/docs/component/reorderable.md) for `"horizontal"` semantics. |
+| `role:`          | `"list"` | ARIA role on the `<ol>` — preserves list semantics when consumer CSS resets `list-style`.                                                                                                                                                                   |
+| `**html_options` | —        | Forwarded to the outer `<ol>`.                                                                                                                                                                                                                              |
+
+### `list.item(content, id:, handle:, url:, target:, active:, **html_options, &block)`
+
+| Option           | Default | Description                                                                                                                                                          |
+| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `content`        | `nil`   | Item label — positional arg or via `item.with_title`.                                                                                                                |
+| `id:`            | —       | **Required.** Raises `ArgumentError` if missing.                                                                                                                     |
+| `handle:`        | `:item` | `:item` (whole `<li>` is the drag surface) \| `:leading` \| `:trailing` (that icon position is).                                                                     |
+| `url:`           | `nil`   | Renders `<a href>` around the title/description. Without it, content renders with no wrapper (no click target at all — no `<button>` fallback, unlike `List::Item`). |
+| `target:`        | `nil`   | Forwarded to the `<a>` (e.g. `"_blank"`), only used when `url:` is set.                                                                                              |
+| `active:`        | `false` | Adds `aria-current="page"`, only used when `url:` is set.                                                                                                            |
+| `**html_options` | —       | Forwarded to the `<a>` when `url:` is set. Raises `ArgumentError` if given without `url:` — there is no element for them to land on.                                 |
+
+### Item slot methods (yielded as `item`)
+
+| Slot method                     | Description                                                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `item.with_icon_leading(name)`  | Icon at the leading position. Becomes the drag handle if `handle: :leading`; otherwise purely decorative.   |
+| `item.with_title(text)`         | Title text (pre-populated when positional `content` is given).                                              |
+| `item.with_description(text)`   | Secondary text below the title.                                                                             |
+| `item.with_icon_trailing(name)` | Icon at the trailing position. Becomes the drag handle if `handle: :trailing`; otherwise purely decorative. |
+
+If `handle: :leading`/`:trailing` is set and the corresponding icon slot isn't, a default `grip-vertical` glyph renders there instead.
+
+---
+
+## Rendered HTML Structure
+
+### `handle: :item` (default), no link
+
+```html
+<ol
+  role="list"
+  data-controller="reorderable"
+  data-reorderable-move-key-value="Alt"
+  data-reorderable-editing-value="false"
+>
+  <li
+    id="item-1"
+    data-reorderable-target="item handle"
+    data-action="pointerdown->reorderable#onPointerDown pointermove->reorderable#onPointerMove pointerup->reorderable#onPointerUp"
+  >
+    First
+  </li>
+</ol>
+```
+
+### `handle: :leading`, with a link
+
+```html
+<li id="link-1" data-reorderable-target="item">
+  <span
+    data-reorderable-target="handle"
+    data-action="pointerdown->reorderable#onPointerDown ..."
+  >
+    <svg aria-hidden="true">...</svg>
+    <!-- grip-vertical, or a custom icon if item.with_icon_leading was set -->
+  </span>
+  <a href="/" data-reorderable-target="trigger">
+    <span>
+      <span>Dashboard</span>
+      <span>Overview</span>
+    </span>
+  </a>
+</li>
+```
+
+Icon positions (leading/trailing) are always siblings of the `<a>`, never nested inside it — this is what lets a real link coexist with drag reordering without one accidentally triggering the other. See [reorderable's editing mode](../../../stimulus-plumbers/docs/component/reorderable.md) for how the link itself is neutralized while editing.
+
+---
+
+## Theme keys
+
+| Key                             | Element                                          | Variants |
+| ------------------------------- | ------------------------------------------------ | -------- |
+| `ordered_list`                  | Outer `<ol>`                                     | —        |
+| `ordered_list_item`             | `<li>`                                           | —        |
+| `ordered_list_item_handle`      | Leading/trailing `<span>` (decorative-or-handle) | —        |
+| `ordered_list_item_content`     | Content wrapper `<span>` inside `<a>` (or bare)  | —        |
+| `ordered_list_item_title`       | Title `<span>`                                   | —        |
+| `ordered_list_item_description` | Description `<span>`                             | —        |
+
+---
+
+## ARIA
+
+- See [ARIA.md](../../../ARIA.md) for WCAG 2.1 AA criteria.
+- For the `reorderable` JS controller's targets, values, and actions (including `editingValue`/`trigger`/`toggleEditing`), see the [stimulus-plumbers JS controller doc](../../../stimulus-plumbers/docs/component/reorderable.md).

data/docs/component/plumber.md

@@ -203,3 +203,24 @@ def merge_html_options(*hashes)
   end
 end
 ```
+
+---
+
+## PlumberHelper
+
+### `sp_dom_id(record = nil, prefix: nil, suffix: nil)`
+
+Generates an `"sp_"`-prefixed DOM id for wiring `aria-controls`/`id` pairs between a trigger and its target. Not a component renderer — an internal id-generation utility used by `Combobox`, `Popover`, and `Timeline::Event` when the caller doesn't supply an explicit `id:`.
+
+| Param     | Description                                                                                                            |
+| --------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `record`  | ActiveRecord-like object — delegates to Rails' `dom_id(record, prefix)`. Omit for a random id (`SecureRandom.hex(8)`). |
+| `prefix:` | Forwarded to `dom_id` when `record` is given.                                                                          |
+| `suffix:` | Appended after an underscore, regardless of whether `record` is given.                                                 |
+
+```ruby
+sp_dom_id                                    # => "sp_3f9a1b2c4d5e6f70"
+sp_dom_id(suffix: "panel")                   # => "sp_3f9a1b2c4d5e6f70_panel"
+sp_dom_id(post)                              # => "sp_post_1"
+sp_dom_id(post, prefix: :edit, suffix: :form) # => "sp_edit_post_1_form"
+```

data/docs/component/popover.md

@@ -130,9 +130,8 @@ end
 
 ## ARIA
 
-- Default trigger button has `aria-haspopup="dialog"`, `aria-expanded="false"`, and `aria-controls` pointing to the panel.
-- `aria-expanded` is toggled to `"true"` / `"false"` by the Stimulus controller.
 - Pass `role: "dialog"` or `role: "tooltip"` on `p.panel` based on whether the content is interactive.
 - `aria: { label: }` or `aria: { labelledby: }` on `p.panel` provides the accessible name.
+- See [ARIA.md's Popover pattern](../../../ARIA.md) for the trigger's `aria-haspopup`/`aria-expanded`/`aria-controls` wiring.
 
 For the JS controller API (targets, values, keyboard behaviour), see the [JS package docs](../../../stimulus-plumbers/docs/component/popover.md).