stimulus_plumbers 0.4.5 → 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

@@ -107,7 +107,7 @@ Icons are rendered **inside** the `<button>`, before or after the label `<span>`
 
 ### Icon only
 
-When no text is provided, no `<span>` is rendered. The theme uses `:has(> span)` to detect this and applies `aspect-square` + `px-0`, making the button square (or a circle for `type: :fab` / `:fab_outline`):
+When no text is provided, no `<span>` is rendered, and the button becomes square (or a circle for `type: :fab` / `:fab_outline`):
 
 ```html
 <button type="button" aria-label="Add" class="[theme classes]">
@@ -133,3 +133,4 @@ When no text is provided, no `<span>` is rendered. The theme uses `:has(> span)`
 - `<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) -->
@@ -94,10 +93,17 @@ Individual view helpers render a single view (used for Turbo Frame responses). T
 <%= sp_calendar_turbo_decade(date: @date, today: @today) %>
 ```
 
-| Helper                    | Extra option     | Description                                                        |
-| ------------------------- | ---------------- | ------------------------------------------------------------------ |
-| `sp_calendar_turbo_month` | `weekday_format` | `:short` (default) \| `:long` \| `:narrow` — weekday header format |
-| `sp_calendar_turbo_year`  | `month_format`   | `:short` (default) \| `:long` \| `:narrow` — month button format   |
+**`sp_calendar_turbo_month`** — extra option:
+
+| Option           | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `weekday_format` | `:short` (default) \| `:long` \| `:narrow` — weekday header format |
+
+**`sp_calendar_turbo_year`** — extra option:
+
+| Option         | Description                                                      |
+| -------------- | ---------------------------------------------------------------- |
+| `month_format` | `:short` (default) \| `:long` \| `:narrow` — month button format |
 
 **Common options** (all helpers and `sp_calendar_turbo`):
 
@@ -199,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/card.md

@@ -63,10 +63,12 @@ Rails helper for rendering a themed card with optional icon, title, body, and ac
   <!-- body -->
   <div class="[card_body theme classes]">Your account is active.</div>
 
-  <!-- action -->
-  <div class="[card_action theme classes]">
-    <a href="/settings">Manage</a>
-  </div>
+  <!-- action: a ghost/tertiary sp_button, with card_action classes merged directly onto it (no wrapping div) -->
+  <a
+    href="/settings"
+    class="[button ghost/tertiary + card_action theme classes]"
+    ><span>Manage</span></a
+  >
 </div>
 ```
 
@@ -74,14 +76,14 @@ Rails helper for rendering a themed card with optional icon, title, body, and ac
 
 ## Theme keys
 
-| Key           | Element                             | Variants                                      |
-| ------------- | ----------------------------------- | --------------------------------------------- |
-| `card`        | Outer `<div>`                       | `variant: :primary\|:secondary\|:tertiary\|…` |
-| `card_header` | Header wrapper `<div>` (icon+title) | —                                             |
-| `card_icon`   | Icon inside the header              | —                                             |
-| `card_title`  | Title element (`h2` etc.)           | —                                             |
-| `card_body`   | Body `<div>`                        | —                                             |
-| `card_action` | Action `<div>`                      | —                                             |
+| Key           | Element                                                       | Variants                                      |
+| ------------- | ------------------------------------------------------------- | --------------------------------------------- |
+| `card`        | Outer `<div>`                                                 | `variant: :primary\|:secondary\|:tertiary\|…` |
+| `card_header` | Header wrapper `<div>` (icon+title)                           | —                                             |
+| `card_icon`   | Icon inside the header                                        | —                                             |
+| `card_title`  | Title element (`h2` etc.)                                     | —                                             |
+| `card_body`   | Body `<div>`                                                  | —                                             |
+| `card_action` | Merged onto the action `<a>`/`<button>` (no wrapping element) | —                                             |
 
 ---
 

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

@@ -2,7 +2,7 @@
 
 Rails helpers that render fully-wired combobox components. Each variant shares the same wrapper structure (`input-combobox` + `input-formatter`) and differs only in its popover body.
 
-See [docs/component/combobox.md](../../stimulus-plumbers/docs/component/combobox.md) in the JS package for the underlying controller API.
+See [docs/component/combobox.md](../../../stimulus-plumbers/docs/component/combobox.md) in the JS package for the underlying controller API.
 
 ## Helpers
 
@@ -127,7 +127,7 @@ iOS-style drum/scroll-wheel time picker.
 
 ## Form Builder
 
-`StimulusPlumbers::Form::Builder` exposes combobox-backed fields through purpose-specific methods rather than a single generic helper. See [form_builder.md](form_builder.md) for the full API.
+`StimulusPlumbers::Form::Builder` exposes combobox-backed fields through purpose-specific methods rather than a single generic helper. See [form.md](form.md) for the full API.
 
 ```erb
 <%= form_with model: @user, builder: StimulusPlumbers::Form::Builder do |f| %>

data/docs/component/form.md

@@ -118,9 +118,34 @@ Three methods render a complete, accessible field:
 
 Use `f.time_field` for a plain `<input type="time">`.
 
-**Select** (`as: :select`) — read-only listbox backed by `combobox-dropdown`. Accepts `choices:`, `include_blank:`, `prompt:`, `selected:`. Use `f.select` for a native `<select>`.
+**Select** (`as: :select`) — read-only listbox backed by `combobox-dropdown`.
 
-**Search** (`as: :search`) — editable typeahead backed by `combobox-dropdown`. Accepts `choices:`, `url:`, `clearable:`. Use `f.search_field` for a native `<input type="search">`.
+| Option          | Values         | Default | Description                                                   |
+| --------------- | -------------- | ------- | ------------------------------------------------------------- |
+| `choices`       | Array          | `[]`    | `[label, value]` pairs, or a flat array of strings            |
+| `include_blank` | Boolean/String | `nil`   | Prepends a blank option; String overrides its label           |
+| `prompt`        | Boolean/String | `nil`   | Prepends a disabled placeholder option                        |
+| `selected`      | Value          | `nil`   | Pre-selected value; defaults to the attribute's current value |
+
+Use `f.select` for a native `<select>`.
+
+**Search** (`as: :search`) — editable typeahead backed by `combobox-dropdown`.
+
+| Option      | Values  | Default | Description                                                                         |
+| ----------- | ------- | ------- | ----------------------------------------------------------------------------------- |
+| `choices`   | Array   | `[]`    | Client-side options to filter; omit when using `url:`                               |
+| `url`       | String  | `nil`   | Server-side endpoint, receives `?q=<query>`, returns `<li role="option">` fragments |
+| `clearable` | Boolean | `false` | Adds a clear button that resets the input                                           |
+
+Use `f.search_field` for a native `<input type="search">`.
+
+**Password** (`as: :password`) — reveal-toggle wrapper backed by `input-formatter`.
+
+| Option       | Values  | Default | Description                                 |
+| ------------ | ------- | ------- | ------------------------------------------- |
+| `revealable` | Boolean | `false` | Adds a show/hide toggle button on the input |
+
+Use `f.password_field` for a plain `<input type="password">` (also accepts `revealable:`).
 
 ---
 
@@ -169,9 +194,9 @@ Renders a `<fieldset>` / `<legend>` for accessible grouping, or a single checkbo
 
 **Card / button behaviour:**
 
-- **Checkbox card** — input visible on right; card border changes on check via `has-[:checked]:`
-- **Radio card** — input hidden (`hidden peer`); entire card is the clickable area via `peer-checked:`
-- **Radio button** — input hidden (`hidden peer`); inline pill style via `peer-checked:`
+- **Checkbox card** — input visible on the right; the card border highlights when checked
+- **Radio card** — input visually hidden; the whole card is the clickable target and highlights when selected
+- **Radio button** — input visually hidden; renders as an inline pill that highlights when selected
 
 ---
 
@@ -185,7 +210,8 @@ Renders a `<fieldset>` / `<legend>` for accessible grouping, or a single checkbo
   <input
     id="user_email"
     type="email"
-    aria-describedby="user_email_hint"
+    aria-describedby="user_email_hint user_email_error"
+    aria-invalid="true"
     required
     aria-required="true"
   />

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
 
@@ -39,7 +39,7 @@ Rails helper for rendering an accessible list of links, buttons, or grouped sect
 | `role:`          | `"list"` | ARIA role on the `<ul>` — use `"menu"` for interactive menus                             |
 | `**html_options` | —        | Forwarded to the `<ul>`                                                                  |
 
-### `list.section(title:, description:, **html_options)`
+### `list.section(title:, description:, **html_options, &block)`
 
 Renders a `<li>` with an optional heading/description and a nested `<ul>`.
 
@@ -60,7 +60,7 @@ Renders a `<li>` containing an `<a>` (when `url:` present) or `<button>`.
 | `target:`        | `nil`   | Forwarded to the `<a>` (e.g. `"_blank"`)                            |
 | `**html_options` | —       | Forwarded to the inner `<a>` or `<button>`                          |
 
-When `target: "_blank"` is set, `icon_trailing: "external-link"` is added automatically.
+When `url:` is present and `target: "_blank"` is set, `icon_trailing: "external-link"` is added automatically.
 
 ### Item slot methods (yielded as `item`)
 
@@ -154,8 +154,7 @@ When `target: "_blank"` is set, `icon_trailing: "external-link"` is added automa
 
 ## 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).