stimulus_plumbers 0.4.8 → 0.4.10

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

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/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,18 +146,22 @@ 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:`        |
 
 ---
 

data/docs/guide.md

@@ -25,3 +25,24 @@ Render components with `sp_*` helpers (`sp_button`, `sp_button_group`, `sp_card`
 
 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.
+
+## Installed CSS files
+
+The core installer copies its token defaults to
+`app/assets/stylesheets/stimulus_plumbers/tokens.css` and imports that app-local file.
+
+This file is application-owned: later generator runs create a missing file but never overwrite an
+existing one. They also replace legacy imports that pointed into an installed gem with the new
+relative app-local import.

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

@@ -9,20 +9,30 @@ module StimulusPlumbers
     class InstallGenerator < Rails::Generators::Base
       include StimulusPlumbers::Generators::CssEntrypoint
 
-      STIMULUS_PLUMBERS_CSS_FILE = CssEntrypoint::STIMULUS_PLUMBERS_CSS_FILE
-      CSS_CANDIDATES             = %w[
-        app/assets/stylesheets/application.tailwind.css
-        app/assets/stylesheets/application.css
-        app/javascript/entrypoints/application.css
-      ].freeze
+      TOKENS_CSS_SOURCE = File.join(
+        File.expand_path("../../../..", __dir__),
+        TokensDirective::TOKENS_CSS_PATH
+      )
 
       def install
-        css_file = entry_css_file(candidates: CSS_CANDIDATES, env_var: STIMULUS_PLUMBERS_CSS_FILE)
-        unless css_file
-          return warn_entry_css_not_found(candidates: CSS_CANDIDATES, env_var: STIMULUS_PLUMBERS_CSS_FILE, label: "CSS")
-        end
+        css_file = entry_css_file(**css_file_lookup_options)
+        return warn_entry_css_not_found(label: "CSS", **css_file_lookup_options) unless css_file
+        return unless copy_asset(TOKENS_CSS_SOURCE, TokensDirective::TOKENS_CSS_PATH)
 
-        apply_edit(css_file, TokensDirective.directive, stale_pattern: TokensDirective.stale_pattern)
+        apply_edit(
+          css_file,
+          TokensDirective.directive(from: File.dirname(css_file), destination_root: destination_root),
+          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

data/lib/stimulus_plumbers/components/button.rb

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

data/lib/stimulus_plumbers/components/link.rb

@@ -45,6 +45,7 @@ module StimulusPlumbers
 
           Components::Icon.new(template).render(
             name:    value,
+            size:    :sm,
             classes: theme.resolve(:link_icon).fetch(:classes, ""),
             aria:    { hidden: "true" }
           )

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

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

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class OrderedList
+      class Item < Plumber::Base
+        HANDLE_ACTION = "pointerdown->reorderable#onPointerDown pointermove->reorderable#onPointerMove " \
+                        "pointerup->reorderable#onPointerUp"
+
+        def render(content = nil, id:, handle: :item, url: nil, target: nil, active: false, **html_options, &block)
+          validate_options!(id, url, html_options)
+
+          slots = build_slots(content, &block)
+
+          build(id: id, handle: handle) do |attrs|
+            template.content_tag(:li, **attrs) do
+              template.safe_join(
+                [
+                  render_icon_position(slots, :leading),
+                  render_body(slots, url: url, target: target, active: active, **html_options),
+                  render_icon_position(slots, :trailing)
+                ]
+              )
+            end
+          end
+        end
+
+        def build(id:, handle: :item, &block)
+          @handle = handle
+          html_options = merge_html_options(theme.resolve(:ordered_list_item), { id: id }, item_target_attrs)
+          template.capture(html_options, &block)
+        end
+
+        private
+
+        def validate_options!(id, url, html_options)
+          raise ArgumentError, "id: is required so the item appears in reorderable:reordered's itemIds" if id.blank?
+          return unless url.blank? && html_options.present?
+
+          raise ArgumentError, "html_options are only applied to the <a> rendered when url: is set"
+        end
+
+        def build_slots(content, &block)
+          slots = OrderedList::Item::Slots.new(template)
+          slots.with_title(content) if content
+          yield slots if block_given?
+          slots
+        end
+
+        def item_target_attrs
+          if @handle == :item
+            { data: { "reorderable-target": "item handle", action: HANDLE_ACTION } }
+          else
+            { data: { "reorderable-target": "item" } }
+          end
+        end
+
+        def render_body(slots, url:, target:, active:, **html_options)
+          content = render_content_slot(slots)
+          return content unless url.present?
+
+          aria  = active ? { aria: { current: "page" } } : {}
+          attrs = merge_html_options(html_options, { data: { "reorderable-target": "trigger" } }, aria)
+          template.content_tag(:a, content, href: url, target: target, **attrs)
+        end
+
+        def render_icon_position(slots, position)
+          slot_name   = position == :leading ? :icon_leading : :icon_trailing
+          is_handle   = @handle == position
+          custom_icon = render_icon_slot(slots, slot_name)
+          return unless custom_icon || is_handle
+
+          html_options = merge_html_options(theme.resolve(:ordered_list_item_handle), handle_target_attrs(is_handle))
+          template.content_tag(:span, custom_icon || default_handle_icon, **html_options)
+        end
+
+        def handle_target_attrs(is_handle)
+          return {} unless is_handle
+
+          { data: { "reorderable-target": "handle", action: HANDLE_ACTION } }
+        end
+
+        def render_icon_slot(slots, name)
+          slots.resolve(name) do |value|
+            next value unless Components::Icon.icon_name?(value)
+
+            Components::Icon.new(template).render(
+              name:    value,
+              size:    :sm,
+              classes: theme.resolve(:ordered_list_item_handle).fetch(:classes, ""),
+              aria:    { hidden: "true" }
+            )
+          end
+        end
+
+        def default_handle_icon
+          Components::Icon.new(template).render(
+            name:    "grip-vertical",
+            size:    :sm,
+            classes: theme.resolve(:ordered_list_item_handle).fetch(:classes, ""),
+            aria:    { hidden: "true" }
+          )
+        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(:ordered_list_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(:ordered_list_item_title)))
+          end
+        end
+
+        def render_description_slot(slots)
+          slots.resolve(:description) do |v|
+            template.content_tag(:span, v, **merge_html_options(theme.resolve(:ordered_list_item_description)))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/ordered_list.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class OrderedList < Plumber::Base
+      def render(move_key: "Alt", editing: false, orientation: nil, role: "list", **kwargs, &block)
+        stimulus = {
+          data: {
+            controller:                      "reorderable",
+            "reorderable-move-key-value":    move_key,
+            "reorderable-editing-value":     editing,
+            "reorderable-orientation-value": orientation
+          }.compact
+        }
+        html_options = merge_html_options(theme.resolve(:ordered_list), kwargs, stimulus)
+        template.content_tag(:ol, template.capture(self, &block), **html_options, role: role)
+      end
+
+      def item(content = nil, **kwargs, &block)
+        OrderedList::Item.new(template).render(content, **kwargs, &block)
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/progress_bar.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class ProgressBar < Plumber::Base
+      def render(...) = render_bar(...)
+
+      private
+
+      def render_bar(value:, min: 0, max: 100, indeterminate: false, **kwargs)
+        html_options = merge_html_options(
+          theme.resolve(:progress_bar),
+          kwargs,
+          stimulus_data(value: value, min: min, max: max, indeterminate: indeterminate),
+          { role: "progressbar", aria: progress_aria(value: value, min: min, max: max, indeterminate: indeterminate) }
+        )
+        template.content_tag(:div, render_fill, **html_options)
+      end
+
+      def render_fill
+        template.content_tag(
+          :div,
+          nil,
+          **merge_html_options(theme.resolve(:progress_bar_fill), { data: { "progress-target": "fill" } })
+        )
+      end
+
+      def progress_aria(value:, min:, max:, indeterminate:)
+        aria = { valuemin: min, valuemax: max }
+        aria[:valuenow] = value unless indeterminate
+        aria
+      end
+
+      def stimulus_data(value:, min:, max:, indeterminate:)
+        {
+          data: {
+            controller:                     "progress",
+            "progress-variant-value":       "bar",
+            "progress-current-value":       value,
+            "progress-min-value":           min,
+            "progress-max-value":           max,
+            "progress-indeterminate-value": indeterminate
+          }
+        }
+      end
+    end
+  end
+end