stimulus_plumbers 0.4.5 → 0.4.9

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

@@ -103,6 +103,28 @@ end
 
 ---
 
+## Plumber::Slots
+
+Base class for a component's slot DSL (e.g. `renderer.with_title(value)`, `renderer.with_content { ... }`). Used by `Card`, `Button`, `Link`, `List::Item`, `Timeline::Event`, and `Combobox::Builder`.
+
+```ruby
+class MySlots < StimulusPlumbers::Plumber::Slots
+  slot :icon, :title              # flat slots: with_icon(value) / with_title(value)
+  slot :header, by: HeaderSlots   # nested slots: with_header { |h| h.with_x(...) }
+end
+```
+
+Always construct with the view `template` — required for a slot's multi-line block form (`with_content do ... end`) to render correctly:
+
+```ruby
+slots = MySlots.new(template)
+yield slots if block_given?
+```
+
+Slots needing custom validation (e.g. a required keyword) define `with_*` manually instead of using the `slot` DSL — see `Card::Slots#with_action`.
+
+---
+
 ## Plumber::Options::Html
 
 Mixin for safely deep-merging HTML attribute hashes. Handles three concerns that a plain `Hash#merge` gets wrong:
@@ -181,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).

data/docs/component/progress.md

@@ -0,0 +1,65 @@
+# Progress
+
+Rails helpers for rendering the `progress` Stimulus controller's three variants. See [stimulus-plumbers's docs/component/progress.md](../../../stimulus-plumbers/docs/component/progress.md) for the controller's Values/Targets/Methods/Dispatches.
+
+## Helpers
+
+### `sp_progress_bar`
+
+```erb
+<%= sp_progress_bar(value: 65, max: 100, aria: { label: "Upload progress" }) %>
+```
+
+| Option           | Default | Description                                              |
+| ---------------- | ------- | -------------------------------------------------------- |
+| `value:`         | —       | Required. Current value                                  |
+| `min:`           | `0`     | Range minimum                                            |
+| `max:`           | `100`   | Range maximum                                            |
+| `indeterminate:` | `false` | Omits `aria-valuenow`; adds the indeterminate hook class |
+| `**html_options` | —       | Forwarded to the outer `<div role="progressbar">`        |
+
+When `indeterminate:` is true, the JS controller sets a fixed 25% fill
+width directly — this is the same with or without a theme. A theme may
+layer motion on top (Tailwind slides it); without one, the bar renders
+as a static partial fill.
+
+### `sp_progress_ring`
+
+```erb
+<%= sp_progress_ring(value: 60, max: 100, aria: { label: "Storage used" }) %>
+```
+
+| Option           | Default | Description                                                |
+| ---------------- | ------- | ---------------------------------------------------------- |
+| `value:`         | —       | Required. Current value                                    |
+| `min:`           | `0`     | Range minimum                                              |
+| `max:`           | `100`   | Range maximum                                              |
+| `indeterminate:` | `false` | Omits `aria-valuenow`; adds the indeterminate hook class   |
+| `**html_options` | —       | Forwarded to the rendered icon (role, aria, classes, etc.) |
+
+Renders via the theme's icon registry (icon name `"progress-ring"`), the same mechanism as `sp_icon`. Track/fill color and ring size are fixed by the icon's own SVG — resize with a `classes:`/`class:` override (e.g. `classes: "size-16"`) rather than a radius option. **Themes must register a `"progress-ring"` icon to render the ring's visual structure** — `stimulus-plumbers-tailwind` ships one; a theme without it (including the unstyled `Themes::Base`) falls back to an empty `<span role="progressbar">` with no visible ring, same as `sp_icon` for an unknown icon name.
+
+When `indeterminate:` is true (and a theme provides the ring icon), the JS
+controller sets the fill circle's `stroke-dasharray` to a fixed 25% arc
+directly, same as the bar. A theme may spin it (Tailwind's `animate-spin`);
+without one, the arc renders static.
+
+### `sp_progress_meter`
+
+```erb
+<%= sp_progress_meter(value: 6, min: 0, max: 10, low: 3, high: 8, optimum: 9, aria: { label: "Disk usage" }) %>
+```
+
+| Option           | Default | Description                                       |
+| ---------------- | ------- | ------------------------------------------------- |
+| `value:`         | —       | Required. Current value                           |
+| `min:`           | `0`     | Range minimum                                     |
+| `max:`           | `100`   | Range maximum                                     |
+| `low:`           | `nil`   | Native `<meter low>` — omitted when not given     |
+| `high:`          | `nil`   | Native `<meter high>` — omitted when not given    |
+| `optimum:`       | `nil`   | Native `<meter optimum>` — omitted when not given |
+| `**html_options` | —       | Forwarded to the `<meter>`                        |
+
+## Known limitation
+
+`<meter>` styling relies on `::-webkit-meter-*`/`::-moz-meter-*` pseudo-elements — cross-browser visual consistency is limited; this is a native-element tradeoff, not a bug.

data/docs/component/theme.md

@@ -4,14 +4,27 @@ Stimulus Plumbers uses a theme system to apply presentational CSS classes to for
 
 ## Configuration
 
+Adding the `stimulus_plumbers_tailwind` gem registers and activates the Tailwind theme automatically — no config needed. To switch to a custom theme instead:
+
 ```ruby
 # config/initializers/stimulus_plumbers.rb
 StimulusPlumbers.configure do |config|
-  config.theme.use(:tailwind)
-  # config.theme.use(MyCustomTheme.new)
+  config.theme.use(MyCustomTheme.new)
 end
 ```
 
+## Design tokens
+
+- Component classes reference CSS custom properties (e.g. `--sp-color-primary`) defined in `stimulus_plumbers/tokens.css`
+- Run `bin/rails generate stimulus_plumbers:install` once to import it — see the [README](../../README.md#installation)
+- Override tokens with your own `:root` block after the generated import — the cascade applies your values without forking the file
+
+```css
+:root {
+  --sp-color-primary: oklch(60% 0.18 260);
+}
+```
+
 ## Theme keys
 
 Each row lists the theme key, the component that uses it, and the variants it accepts.

data/docs/component/timeline.md

@@ -64,6 +64,37 @@ Rails helper for rendering a themed timeline as an ordered list with optional in
 - `e.with_detail` requires `e.with_trigger` — raises `ArgumentError` otherwise.
 - `e.with_time` requires `datetime:` on `t.event` — raises `ArgumentError` otherwise.
 
+### `sp_timeline_group`
+
+Groups events under dated sections, each with its own `<ol>` — for timelines broken up by day/month rather than one flat list.
+
+```erb
+<%= sp_timeline_group do |g| %>
+  <% g.section(date: "January 2025", datetime: "2025-01-15") do |t| %>
+    <% t.event do |e| %>
+      <% e.with_indicator %>
+      <% e.with_title { "Event title" } %>
+      <% e.with_description { "Brief text" } %>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+| Option           | Default     | Description                                                               |
+| ---------------- | ----------- | ------------------------------------------------------------------------- |
+| `orientation:`   | `:vertical` | Layout direction for each section's events — `:vertical` \| `:horizontal` |
+| `**html_options` | —           | Forwarded to the outer `<div>`                                            |
+
+`g.section` options:
+
+| Option           | Default | Description                                        |
+| ---------------- | ------- | -------------------------------------------------- |
+| `date:`          | —       | Required — text content for the section's `<time>` |
+| `datetime:`      | `nil`   | Renders `<time datetime="...">` when set           |
+| `**html_options` | —       | Forwarded to the section's outer `<div>`           |
+
+Each `g.section` block yields a `t` scoped to that section (same `t.event` API as `sp_timeline`, non-interactive, orientation inherited from `sp_timeline_group`'s `orientation:`).
+
 ---
 
 ## Rendered HTML Structure
@@ -115,24 +146,28 @@ Rails helper for rendering a themed timeline as an ordered list with optional in
 
 ## Theme keys
 
-| Key                         | Element                            | Variants              |
-| --------------------------- | ---------------------------------- | --------------------- |
-| `timeline`                  | Outer `<ol>`                       | `orientation:`        |
-| `timeline_item`             | `<li>`                             | `orientation:`        |
-| `timeline_item_indicator`   | Indicator `<div>`                  | `type: :dot \| :icon` |
-| `timeline_item_time`        | `<time>`                           | —                     |
-| `timeline_item_title`       | Static `<h3>`                      | —                     |
-| `timeline_item_heading`     | `<h3>` wrapping the trigger button | —                     |
-| `timeline_item_trigger`     | `<button>` inside the heading      | —                     |
-| `timeline_item_description` | `<p>`                              | —                     |
-| `timeline_item_detail`      | Collapsible `<div>`                | —                     |
-| `timeline_item_actions`     | Actions `<div>`                    | —                     |
+| Key                           | Element                            | Variants              |
+| ----------------------------- | ---------------------------------- | --------------------- |
+| `timeline`                    | Outer `<ol>`                       | `orientation:`        |
+| `timeline_item`               | `<li>`                             | `orientation:`        |
+| `timeline_item_indicator`     | Indicator `<div>`                  | `type: :dot \| :icon` |
+| `timeline_item_time`          | `<time>`                           | —                     |
+| `timeline_item_title`         | Static `<h3>`                      | —                     |
+| `timeline_item_heading`       | `<h3>` wrapping the trigger button | —                     |
+| `timeline_item_trigger`       | `<button>` inside the heading      | —                     |
+| `timeline_item_description`   | `<p>`                              | —                     |
+| `timeline_item_detail`        | Collapsible `<div>`                | —                     |
+| `timeline_item_actions`       | Actions `<div>`                    | —                     |
+| `timeline_group`              | `sp_timeline_group` outer `<div>`  | —                     |
+| `timeline_group_section`      | `g.section` outer `<div>`          | —                     |
+| `timeline_group_section_date` | Section `<time>`                   | —                     |
+| `timeline_group_section_list` | Section `<ol>`                     | `orientation:`        |
 
 ---
 
 ## ARIA
 
-- See [ARIA.md](../../ARIA.md) for WCAG 2.1 AA criteria and disclosure widget patterns.
+- See [ARIA.md](../../../ARIA.md) for WCAG 2.1 AA criteria and disclosure widget patterns.
 - The trigger button uses `aria-expanded` (managed by the JS controller) and `aria-controls` pointing to the detail `id`.
 - Indicator elements carry `aria-hidden="true"` to hide decorative markup from screen readers.
-- For JS controller targets, values, and actions, see the [stimulus-plumbers JS controller doc](../../stimulus-plumbers/docs/component/timeline.md).
+- For JS controller targets, values, and actions, see the [stimulus-plumbers JS controller doc](../../../stimulus-plumbers/docs/component/timeline.md).

data/docs/guide.md

@@ -0,0 +1,39 @@
+# Guide
+
+## Building forms
+
+Use `StimulusPlumbers::Form::Builder` (set `config.action_view.default_form_builder`, or pass
+`builder:` to `form_with`). Two levels:
+
+- **Level 2 — recommended.** Full accessible field (label + input + hint + error):
+  `f.field(attr, as:)`, `f.collection_field(attr, as:, collection:, ...)`, `f.choice(attr, as:)`.
+  See [docs/component/form.md](component/form.md) for valid `as:` values per builder method and
+  which ones are backed by a Stimulus controller (date/time/select/search pickers).
+- **Level 1.** Native helper overrides (`f.text_field`, `f.select`, `f.check_box`, ...) render
+  only the themed input element — use when you control the surrounding markup.
+
+Submit with `f.submit` (themed button).
+
+## Building views
+
+Render components with `sp_*` helpers (`sp_button`, `sp_button_group`, `sp_card`, `sp_list`,
+`sp_link`, `sp_avatar`, `sp_divider`, `sp_icon`, `sp_popover`, ...) — see the
+[Components table](../README.md#components) for the full helper list, and each component's
+`docs/component/<name>.md` for its keyword options, slots, and themed params.
+
+## Stimulus integration
+
+Most display components are pure markup; interactive ones (combobox, popover, calendar) emit their
+`data-controller` attributes automatically — no manual wiring needed in Rails views.
+
+## CSS entry file detection
+
+`bin/rails generate stimulus_plumbers:install` (and `stimulus_plumbers_tailwind`'s own install
+generator) inject their CSS directives into the first entry file found, in order:
+
+1. `app/assets/stylesheets/application.tailwind.css` (`tailwindcss-rails` 2.x default)
+2. `app/assets/tailwind/application.css` (`tailwindcss-rails` 3.x+ default)
+3. `app/assets/stylesheets/application.css` (Rails/Propshaft default manifest)
+4. `app/javascript/entrypoints/application.css` (`jsbundling-rails` esbuild/webpack default)
+
+Override with `STIMULUS_PLUMBERS_CSS_ENTRY=/path/to/entry.css` — used by both gems' generators.

data/lib/generators/stimulus_plumbers/install/install_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "stimulus_plumbers/generators/css_entrypoint"
+require "stimulus_plumbers/generators/tokens_directive"
+
+module StimulusPlumbers
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include StimulusPlumbers::Generators::CssEntrypoint
+
+      def install
+        css_file = entry_css_file(**css_file_lookup_options)
+        return warn_entry_css_not_found(label: "CSS", **css_file_lookup_options) unless css_file
+
+        apply_edit(
+          css_file,
+          TokensDirective.directive(from: File.dirname(css_file)),
+          stale_pattern: TokensDirective.stale_pattern
+        )
+      end
+
+      private
+
+      def css_file_lookup_options
+        {
+          candidates: CssEntrypoint::ENTRY_CANDIDATES,
+          env_var:    CssEntrypoint::STIMULUS_PLUMBERS_CSS_ENTRY
+        }
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/button.rb

@@ -4,7 +4,7 @@ module StimulusPlumbers
   module Components
     class Button < Plumber::Base
       def render(content = nil, icon_leading: nil, icon_trailing: nil, **kwargs, &block)
-        slots = Button::Slots.new
+        slots = Button::Slots.new(template)
         slots.with_icon_leading(icon_leading) if icon_leading
         slots.with_icon_trailing(icon_trailing) if icon_trailing
 
@@ -51,6 +51,7 @@ module StimulusPlumbers
 
           Components::Icon.new(template).render(
             name:    value,
+            size:    :sm,
             classes: theme.resolve(:button_icon).fetch(:classes, ""),
             aria:    { hidden: "true" }
           )

data/lib/stimulus_plumbers/components/card.rb

@@ -4,7 +4,7 @@ module StimulusPlumbers
   module Components
     class Card < Plumber::Base
       def render(variant: :tertiary, title_tag: :h2, **kwargs, &block)
-        slots = Card::Slots.new
+        slots = Card::Slots.new(template)
         yield slots if block_given?
 
         html_options = merge_html_options(theme.resolve(:card, variant: variant), kwargs)

data/lib/stimulus_plumbers/components/checklist/item/slots.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class Checklist
+      class Item
+        class Slots < Plumber::Slots
+          slot :title, :description
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/checklist/item.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class Checklist
+      class Item < Plumber::Base
+        def render(content = nil, checked: nil, readonly: false, **html_options, &block)
+          raise ArgumentError, "checked: is required" if checked.nil?
+
+          slots = build_slots(content, &block)
+
+          template.content_tag(:label, **merge_html_options(theme.resolve(:checklist_item), html_options)) do
+            template.safe_join([render_input(checked, readonly), render_content_slot(slots)].compact)
+          end
+        end
+
+        private
+
+        def build_slots(content)
+          slots = Checklist::Item::Slots.new(template)
+          slots.with_title(content) if content
+          yield slots if block_given?
+          slots
+        end
+
+        def render_input(checked, readonly)
+          template.tag.input(
+            **merge_html_options(
+              theme.resolve(:checklist_item_input),
+              {
+                type:     "checkbox",
+                checked:  (checked ? true : nil),
+                disabled: (readonly ? true : nil),
+                data:     { checklist_target: "item" }
+              }
+            )
+          )
+        end
+
+        def render_content_slot(slots)
+          title       = render_title_slot(slots)
+          description = render_description_slot(slots)
+          return unless title || description
+
+          template.content_tag(:span, **merge_html_options(theme.resolve(:checklist_item_content))) do
+            template.safe_join([title, description])
+          end
+        end
+
+        def render_title_slot(slots)
+          slots.resolve(:title) do |v|
+            template.content_tag(:span, v, **merge_html_options(theme.resolve(:checklist_item_title)))
+          end
+        end
+
+        def render_description_slot(slots)
+          slots.resolve(:description) do |v|
+            template.content_tag(:span, v, **merge_html_options(theme.resolve(:checklist_item_description)))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/checklist.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class Checklist < Plumber::Base
+      def render(label: nil, labelledby: nil, select_all: false, select_all_label: "Select all", **kwargs, &block)
+        @item_states = [] if select_all
+        captured = template.capture(self, &block)
+        master = select_all ? render_select_all(select_all_label) : nil
+        html_options = merge_html_options(
+          theme.resolve(:checklist),
+          kwargs,
+          { role: "group", aria: labelled_aria(label, labelledby: labelledby) }
+        )
+        html_options = merge_html_options(html_options, select_all_wrapper_attrs) if select_all
+        template.content_tag(:div, template.safe_join([master, captured].compact), **html_options)
+      end
+
+      def item(content = nil, **kwargs, &block)
+        @item_states << kwargs[:checked] if @item_states && !kwargs[:readonly]
+        Checklist::Item.new(template).render(content, **kwargs, &block)
+      end
+
+      private
+
+      def render_select_all(select_all_label)
+        template.content_tag(:label, **merge_html_options(theme.resolve(:checklist_item))) do
+          template.safe_join([render_master_input, template.content_tag(:span, select_all_label)])
+        end
+      end
+
+      def render_master_input
+        template.tag.input(
+          **merge_html_options(
+            theme.resolve(:checklist_item_input),
+            { type: "checkbox", checked: all_items_checked? || nil, data: { checklist_target: "master" } }
+          )
+        )
+      end
+
+      def select_all_wrapper_attrs
+        { data: { controller: "checklist", action: "change->checklist#onChange" } }
+      end
+
+      def all_items_checked?
+        @item_states.present? && @item_states.all? { |state| state == true }
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/combobox/typeahead.rb

@@ -75,6 +75,7 @@ module StimulusPlumbers
           ) do
             Components::Icon.new(template).render(
               name:    "spinner",
+              size:    :md,
               classes: theme.resolve(:combobox_typeahead_loading_icon).fetch(:classes, ""),
               aria:    { hidden: "true" }
             )

data/lib/stimulus_plumbers/components/combobox.rb

@@ -21,7 +21,7 @@ module StimulusPlumbers
       private
 
       def resolve_builder
-        builder = Combobox::Builder.new
+        builder = Combobox::Builder.new(template)
         yield builder if block_given?
         builder
       end

data/lib/stimulus_plumbers/components/icon.rb

@@ -7,9 +7,9 @@ module StimulusPlumbers
         value.is_a?(Symbol) || (value.is_a?(String) && !value.html_safe?)
       end
 
-      def render(name:, **kwargs)
+      def render(name:, size: :lg, **kwargs)
         html_options = merge_html_options(
-          theme.resolve(:icon),
+          theme.resolve(:icon, size: size),
           kwargs
         )
 

data/lib/stimulus_plumbers/components/indicator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class Indicator < Plumber::Base
+      def render(...) = render_indicator(...)
+
+      private
+
+      def render_indicator(variant: :primary, type: :dot, pulse: false, **kwargs, &block)
+        dot = render_dot(variant: variant, type: type, kwargs: kwargs, block: block)
+        return dot unless pulse
+
+        template.content_tag(
+          :span, template.safe_join([render_pulse_ring, dot]), **merge_html_options(theme.resolve(:indicator_wrapper))
+        )
+      end
+
+      def render_dot(variant:, type:, kwargs:, block:)
+        content      = block ? template.capture(&block) : nil
+        html_options = merge_html_options(theme.resolve(:indicator, type: type, variant: variant), kwargs)
+        template.content_tag(:span, content, **html_options)
+      end
+
+      def render_pulse_ring
+        template.content_tag(:span, nil, **merge_html_options(theme.resolve(:indicator_pulse), { aria: { hidden: "true" } }))
+      end
+    end
+  end
+end