stimulus_plumbers 0.4.15 → 0.4.16

data/docs/component/form.md

@@ -44,6 +44,7 @@ Standard Rails helpers are overridden to apply theme CSS classes. All native HTM
 <%= f.time_zone_select  :timezone %>
 <%= f.weekday_select    :weekday %>
 <%= f.search_field   :query %>
+<%= f.range_field    :volume %>
 <%= f.check_box      :agree %>
 <%= f.radio_button   :plan, "basic" %>
 ```
@@ -54,6 +55,7 @@ Special options on native helpers:
 | ---------------- | ------------------ | ------------------------------------------------------------------ |
 | `password_field` | `revealable: true` | Wraps input in an `input-revealable` controller                    |
 | `search_field`   | `clearable: true`  | Wraps input in an `input-clearable` controller with a clear button |
+| `range_field`    | —                  | Themed track and thumb; no controller wiring, readout, or fill     |
 
 ### f.submit
 
@@ -80,23 +82,25 @@ Submit buttons need an accessible name: pass non-blank text, or an `aria` label
 
 Three methods render a complete, accessible field:
 
-| Method                                                                            | `as:` values                                                                                                                                                                              |
-| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `f.field(attr, as:, **opts)`                                                      | `:text` `:email` `:number` `:url` `:tel` `:color` `:month` `:week` `:range` `:datetime_local` `:text_area` `:file` `:password` `:date` `:time` `:select` `:search` `:code` `:credit_card` |
-| `f.collection_field(attr, as:, collection:, value_method:, text_method:, **opts)` | `:collection_select` `:grouped_collection_select`                                                                                                                                         |
-| `f.choice(attr, as:, **opts)`                                                     | `:radio` `:check_box`                                                                                                                                                                     |
+| Method                                                                            | `as:` values                                                                                                                                                                                          |
+| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `f.field(attr, as:, **opts)`                                                      | `:text` `:email` `:number` `:url` `:tel` `:color` `:month` `:week` `:range` `:datetime_local` `:text_area` `:file` `:password` `:date` `:time` `:select` `:search` `:code` `:credit_card` `:progress` |
+| `f.collection_field(attr, as:, collection:, value_method:, text_method:, **opts)` | `:collection_select` `:grouped_collection_select`                                                                                                                                                     |
+| `f.choice(attr, as:, **opts)`                                                     | `:radio` `:check_box`                                                                                                                                                                                 |
 
 ### Shared field options
 
-| Option       | Type                                  | Default                  | Description                                                                |
-| ------------ | ------------------------------------- | ------------------------ | -------------------------------------------------------------------------- |
-| `label`      | String                                | humanised attribute name | Override label / legend text                                               |
-| `hint`       | String                                | `nil`                    | Hint text rendered below the field                                         |
-| `error`      | String / Array                        | `nil`                    | Override error message(s); suppresses `model.errors[attribute]`            |
-| `required`   | Boolean                               | `false`                  | Adds `required` + `aria-required="true"`                                   |
-| `hide_label` | Boolean                               | `false`                  | Renders label visually hidden (screen-reader accessible)                   |
-| `layout`     | `:stacked` / `:inline`                | `:stacked`               | Label above input vs beside it                                             |
-| `floating`   | `:filled` / `:outlined` / `:standard` | `nil`                    | Floating-label style (text-like inputs only; `nil` = standard label above) |
+| Option       | Type                                  | Default                   | Description                                                                |
+| ------------ | ------------------------------------- | ------------------------- | -------------------------------------------------------------------------- |
+| `label`      | String                                | translated attribute name | Override label / legend text                                               |
+| `hint`       | String                                | `nil`                     | Hint text rendered below the field                                         |
+| `error`      | String / Array                        | `nil`                     | Override error message(s); suppresses `model.errors[attribute]`            |
+| `required`   | Boolean                               | `false`                   | Adds `required` + `aria-required="true"`                                   |
+| `hide_label` | Boolean                               | `false`                   | Renders label visually hidden (screen-reader accessible)                   |
+| `layout`     | `:stacked` / `:inline`                | `:stacked`                | Label above input vs beside it                                             |
+| `floating`   | `:filled` / `:outlined` / `:standard` | `nil`                     | Floating-label style (text-like inputs only; `nil` = standard label above) |
+
+Labels and legends default to the text `f.label` renders: `helpers.label.<object_name>.<attribute>`, then the model's `human_attribute_name` (`activerecord.attributes.*` / `activemodel.attributes.*`), then the humanized attribute name when the form has no model. In `fields_for`, the nested object supplies the name.
 
 ---
 
@@ -223,6 +227,37 @@ The validator also accepts inline options (`password_strength: { min_length: 12,
 
 Character-cell fields do not support `floating:` labels.
 
+**Range** (`as: :range`) — native `<input type="range">` styled as a progress track with a thumb. Unlike the progress field it is a real control, so it keeps an ordinary `<label for>`.
+
+| Option          | Values                               | Default     | Description                          |
+| --------------- | ------------------------------------ | ----------- | ------------------------------------ |
+| `format:`       | `:percent` / `:value` / `:value_max` | `nil`       | Adds a live readout beside the track |
+| `min:` / `max:` | Number                               | `0` / `100` | Range bounds                         |
+
+```erb
+<%= f.field :volume, as: :range, format: :percent %>
+```
+
+The controller writes no `aria-*` — a native range already exposes its own slider semantics, and the readout is `aria-hidden` so the value isn't announced twice. The fill percentage is server-rendered onto the input, so it is correct before the controller connects.
+
+Cross-browser caveat: WebKit has no filled-track pseudo-element, so the fill is a gradient driven by `--sp-progress-percent`; Firefox uses its native `::-moz-range-progress`. Use `f.range_field` for the same themed slider without the controller wiring, readout, or server-rendered fill.
+
+**Progress** (`as: :progress`) — read-only indicator for a model attribute, rendered by [`sp_progress_bar`](progress.md#sp_progress_bar). It submits nothing and is never invalid.
+
+| Option          | Values                               | Default     | Description                                                                                         |
+| --------------- | ------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------- |
+| `format:`       | `:percent` / `:value` / `:value_max` | `nil`       | On-screen readout of the value                                                                      |
+| `readout:`      | `:inside` / `:outside`               | `:inside`   | Readout placement — see [`sp_progress_bar`](progress.md#sp_progress_bar)                            |
+| `segments:`     | positive Integer                     | `nil`       | Renders segmented instead of a single bar; excludes `format:`. Anything else raises `ArgumentError` |
+| `min:` / `max:` | Number                               | `0` / `100` | Range bounds                                                                                        |
+
+```erb
+<%= f.field :completion, as: :progress, format: :percent %>
+<%= f.field :profile_strength, as: :progress, segments: 5, max: 5 %>
+```
+
+Its label renders as a `<span>`, not a `<label>`, and names the bar via `aria-labelledby`. `<label for>` is only valid against a labelable element (`button`, `input`, `meter`, `output`, `progress`, `select`, `textarea`), and a `div[role="progressbar"]` is none of those — a `for=` pointing at it would silently leave the bar unnamed. For the same reason it takes no `required` or `aria-invalid`; `hint:` and `error:` still describe it via `aria-describedby`.
+
 ---
 
 ## f.collection_field

data/docs/component/indicator.md

@@ -35,7 +35,7 @@ Presentational status marker — a colored dot, an animated "pulse" ring, or a n
 
 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.
+**Every indicator must be paired with an accessible name** — a visible label or `aria-label`/adjacent `sr-only` text. The component renders no text and cannot infer the right label, so the caller must supply one.
 
 ## Legend pattern
 

data/docs/component/progress.md

@@ -1,6 +1,6 @@
 # Progress
 
-Rails helpers for rendering the `progress` Stimulus controller's four variants. See [stimulus-plumbers's docs/component/progress.md](../../../stimulus-plumbers/docs/component/progress.md) for the controller's Values/Targets/Methods/Dispatches.
+Rails helpers for rendering the four standalone `progress` variants. The controller also has a `range` variant, which has no `sp_*` helper — it is a form control, reached through [`f.field(as: :range)`](form.md). See [stimulus-plumbers's docs/component/progress.md](../../../stimulus-plumbers/docs/component/progress.md) for the controller's Values/Targets/Methods/Dispatches.
 
 ## Helpers
 
@@ -10,13 +10,26 @@ Rails helpers for rendering the `progress` Stimulus controller's four variants.
 <%= 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">`        |
+| 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                                                                     |
+| `format:`        | `nil`     | Renders an on-screen readout: `:percent` \| `:value` \| `:value_max`. Any other value raises `ArgumentError`                 |
+| `readout:`       | `:inside` | Where that readout sits: `:inside` (over the track) \| `:outside` (beside it). Always validated; no effect without `format:` |
+| `**html_options` | —         | Forwarded to the outer `<div role="progressbar">`                                                                            |
+
+`format:` renders the readout server-side, so it is correct before the controller connects. The text and its `aria-valuetext` behaviour are the same as the controller's — see [Readout formats](../../../stimulus-plumbers/docs/component/progress.md#readout-formats). The theme is told whether a readout is present, so it can give the track room for the text.
+
+```erb
+<%= sp_progress_bar(value: 45, format: :percent, aria: { label: "Upload progress" }) %>
+<%= sp_progress_bar(value: 45, format: :percent, readout: :outside, aria: { label: "Upload progress" }) %>
+```
+
+`:outside` wraps the root around a track element plus the readout, since the track clips its overflow. Role, ARIA, and `data-controller` stay on the root in both.
+
+Theme keys: `progress_bar_value` (inside), `progress_bar_value_outside` + `progress_bar_group` (outside). A theme without the latter two renders `:outside` unstyled, not broken.
 
 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
@@ -29,12 +42,14 @@ as a static partial fill.
 <%= sp_progress_segmented(value: 6, segments: 5, max: 10, aria: { label: "Password strength" }) %>
 ```
 
+`format:` is not supported here (it raises `ArgumentError`) — there is no single track to center a readout over.
+
 Splits the track into `segments:` equal slots and distributes the value across them (max 10 with `segments: 5` → each slot spans 2 units). Renders one `fill` target per slot; the JS controller fills them.
 
 | Option           | Default     | Description                                                                                            |
 | ---------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
 | `value:`         | —           | Required. Current value                                                                                |
-| `segments:`      | —           | Required. Number of equal slots                                                                        |
+| `segments:`      | —           | Required. Positive Integer; anything else raises `ArgumentError`                                       |
 | `min:`           | `0`         | Range minimum                                                                                          |
 | `max:`           | `100`       | Range maximum                                                                                          |
 | `mode:`          | `:discrete` | `:discrete` lights a whole slot once reached; `:continuous` partially fills the boundary slot          |

data/docs/guide.md

@@ -1,5 +1,62 @@
 # Guide
 
+## Quickstart
+
+Requires Ruby >= 3.0 and Rails >= 6.1.
+
+1. Add the gem and install:
+
+   ```ruby
+   # Gemfile
+   gem "stimulus_plumbers"
+   ```
+
+   ```bash
+   bundle install
+   ```
+
+2. Run the install generator — it copies `tokens.css` into your app and injects the import into your
+   CSS entry file (see [CSS entry file detection](#css-entry-file-detection)):
+
+   ```bash
+   bin/rails generate stimulus_plumbers:install
+   ```
+
+3. Register the Stimulus controllers that back the interactive components. The gem renders the
+   `data-controller` attributes; the JS package supplies the controllers themselves:
+
+   ```bash
+   npm install @stimulus-plumbers/controllers
+   ```
+
+   Register them as `guide://controller` describes — identifiers must match what the helpers emit.
+
+4. Make the form builder the default (or pass `builder:` per `form_with`):
+
+   ```ruby
+   # config/application.rb
+   config.action_view.default_form_builder = StimulusPlumbers::Form::Builder
+   ```
+
+5. Render a first form:
+
+   ```erb
+   <%= form_with model: @user do |f| %>
+     <%= f.field :email, as: :email, hint: "We never share it" %>
+     <%= f.field :password, as: :password, revealable: true %>
+     <%= f.field :country, as: :select, choices: ["Australia", "Canada"] %>
+     <%= f.submit "Create account" %>
+   <% end %>
+   ```
+
+   Each `f.field` renders the label, input, hint, and error with their ARIA wiring already
+   associated — no `label`/`aria-describedby` by hand.
+
+For view components outside a form, include the helper modules you use in `ApplicationHelper` (see
+the gem's
+[README](https://github.com/ryancyq/stimulus-plumbers/blob/main/stimulus-plumbers-rails/README.md#installation))
+and call the `sp_*` helpers described under [Building views](#building-views).
+
 ## Building forms
 
 Use `StimulusPlumbers::Form::Builder` (set `config.action_view.default_form_builder`, or pass
@@ -7,20 +64,22 @@ Use `StimulusPlumbers::Form::Builder` (set `config.action_view.default_form_buil
 
 - **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
+  See `component://form/docs` ([form.md](https://github.com/ryancyq/stimulus-plumbers/blob/main/stimulus-plumbers-rails/docs/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; supports `icon_leading:`/`icon_trailing:` and
-`hide_label:` for an icon-only button — see [docs/component/form.md](component/form.md)).
+`hide_label:` for an icon-only button — see `component://form/docs`).
 
 ## 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.
+[Components table](https://github.com/ryancyq/stimulus-plumbers/blob/main/stimulus-plumbers-rails/README.md#components)
+for the full helper list (`list_components` / `list_component_docs` over MCP), and each component's
+`component://{name}/docs` for its keyword options, slots, and themed params.
 
 ## Stimulus integration
 

data/lib/stimulus_plumbers/components/progress/shared.rb

@@ -3,8 +3,11 @@
 module StimulusPlumbers
   module Components
     module Progress
-      # Shared stimulus/ARIA wiring for the progress variants (bar, segmented, ring, meter).
+      # Shared stimulus/ARIA wiring and value formatting for the progress variants
+      # (bar, segmented, ring, meter) and for the range form field, which reuses the readout.
       module Shared
+        FORMATS = %i[percent value value_max].freeze
+
         private
 
         def progress_stimulus_data(value:, min:, max:, variant:, **extra)
@@ -20,11 +23,51 @@ module StimulusPlumbers
           }
         end
 
-        def progress_aria(value:, min:, max:, indeterminate: false)
+        def progress_aria(value:, min:, max:, indeterminate: false, valuetext: nil)
           aria = { valuemin: min, valuemax: max }
-          aria[:valuenow] = value unless indeterminate
+          aria[:valuenow]  = value unless indeterminate
+          aria[:valuetext] = valuetext if valuetext
           aria
         end
+
+        def validate_format!(format)
+          return if format.nil? || (format.respond_to?(:to_sym) && FORMATS.include?(format.to_sym))
+
+          raise ArgumentError, "unknown format: #{format.inspect} (expected one of #{FORMATS.join(", ")})"
+        end
+
+        # Keep in sync with the progress controller's formattedValue().
+        def value_text(format, current, min, max)
+          case format&.to_sym
+          when :percent   then "#{percent(current, min, max).round}%"
+          when :value     then integral(current).to_s
+          when :value_max then "#{integral(current)} / #{integral(max)}"
+          end
+        end
+
+        # Comparable#clamp raises when min > max; the JS returns max there, and percent() then yields 0%.
+        def clamp(value, min, max)
+          return max if max < min
+
+          value.clamp(min, max)
+        end
+
+        def percent(current, min, max)
+          range = max - min
+          range <= 0 ? 0 : (current - min).fdiv(range) * 100
+        end
+
+        # A `step: 0.1` range holds 45.5 — to_i would paint a 45 fill under a 45.5 thumb.
+        def numeric(value)
+          return value if value.is_a?(Numeric)
+
+          Float(value, exception: false) || 0
+        end
+
+        # 45.0 renders as "45" — JS has no Float/Integer distinction to mirror.
+        def integral(number)
+          (number % 1).zero? ? number.to_i : number
+        end
       end
     end
   end

data/lib/stimulus_plumbers/components/progress_bar.rb

@@ -9,19 +9,24 @@ module StimulusPlumbers
         render_bar(...)
       end
 
-      def render_segmented(value:, segments:, min: 0, max: 100, mode: :discrete, indeterminate: false, ramp: nil, **kwargs)
+      def render_segmented(
+        value:,
+        segments:,
+        min: 0,
+        max: 100,
+        mode: :discrete,
+        indeterminate: false,
+        ramp: nil,
+        format: nil,
+        **kwargs
+      )
+        validate_segments!(segments, format)
+        current = clamp(value, min, max)
         html_options = merge_html_options(
-          theme.resolve(:progress_segmented),
+          theme.resolve(:progress_segment_group),
           kwargs,
-          progress_stimulus_data(
-            value:                          value,
-            min:                            min,
-            max:                            max,
-            variant:                        "segmented",
-            "progress-segment-mode-value":  mode,
-            "progress-indeterminate-value": indeterminate
-          ),
-          { role: "progressbar", aria: progress_aria(value: value, min: min, max: max, indeterminate: indeterminate) }
+          segmented_stimulus_data(current, min, max, mode, indeterminate),
+          { role: "progressbar", aria: progress_aria(value: current, min: min, max: max, indeterminate: indeterminate) }
         )
         slots = ramp_intents(ramp, segments).map { |intent| render_segment(intent: intent) }
         template.content_tag(:div, template.safe_join(slots), **html_options)
@@ -29,30 +34,103 @@ module StimulusPlumbers
 
       private
 
-      def render_bar(value:, min: 0, max: 100, indeterminate: false, **kwargs)
-        html_options = merge_html_options(
-          theme.resolve(:progress_bar),
+      def validate_segments!(segments, format)
+        raise ArgumentError, "format: is not supported with segments:" unless format.nil?
+        raise ArgumentError, "segments must be a positive integer" unless segments.is_a?(Integer) && segments.positive?
+      end
+
+      def segmented_stimulus_data(current, min, max, mode, indeterminate)
+        progress_stimulus_data(
+          value:                          current,
+          min:                            min,
+          max:                            max,
+          variant:                        "segmented",
+          "progress-segment-mode-value":  mode,
+          "progress-indeterminate-value": indeterminate
+        )
+      end
+
+      def render_bar(value:, min: 0, max: 100, indeterminate: false, format: nil, readout: :inside, **kwargs)
+        validate_format!(format)
+        validate_readout!(readout)
+        current      = clamp(value, min, max)
+        text         = value_text(format, current, min, max) unless indeterminate
+        html_options = bar_html_options(current, min, max, indeterminate, format, readout, text, kwargs)
+        template.content_tag(:div, bar_body(format, readout, text), **html_options)
+      end
+
+      def validate_readout!(readout)
+        return if Themes::Schema::Progress::Ranges::PLACEMENT.include?(readout&.to_sym)
+
+        raise ArgumentError, "readout must be one of #{Themes::Schema::Progress::Ranges::PLACEMENT.join(", ")}"
+      end
+
+      # The track clips its overflow, so an outside readout needs the root to be a wrapper.
+      def bar_body(format, readout, text)
+        return render_fill if format.nil?
+        return template.safe_join([render_fill, render_value(text, :inside)]) if readout.to_sym == :inside
+
+        template.safe_join([render_track, render_value(text, :outside)])
+      end
+
+      def render_track
+        template.content_tag(:div, render_fill, **merge_html_options(theme.resolve(:progress_bar, labelled: false)))
+      end
+
+      def bar_html_options(current, min, max, indeterminate, format, readout, text, kwargs)
+        # `percent` omits aria-valuetext — AT derives the percentage from aria-valuenow itself.
+        valuetext = text unless format&.to_sym == :percent
+        aria      = progress_aria(value: current, min: min, max: max, indeterminate: indeterminate, valuetext: valuetext)
+        merge_html_options(
+          bar_root_theme(format, readout),
           kwargs,
-          progress_stimulus_data(
-            value: value, min: min, max: max, variant: "bar", "progress-indeterminate-value": indeterminate
-          ),
-          { role: "progressbar", aria: progress_aria(value: value, min: min, max: max, indeterminate: indeterminate) }
+          bar_stimulus_data(current, min, max, indeterminate, format),
+          { role: "progressbar", aria: aria }
+        )
+      end
+
+      def bar_root_theme(format, readout)
+        return theme.resolve(:progress_bar_group) if format && readout.to_sym == :outside
+
+        theme.resolve(:progress_bar, labelled: !format.nil?)
+      end
+
+      def bar_stimulus_data(current, min, max, indeterminate, format)
+        progress_stimulus_data(
+          value:                          current,
+          min:                            min,
+          max:                            max,
+          variant:                        "bar",
+          "progress-indeterminate-value": indeterminate,
+          **(format.nil? ? {} : { "progress-format-value": format })
+        )
+      end
+
+      # aria-hidden: the value reaches AT via aria-valuenow/aria-valuetext, not this span.
+      def render_value(text, placement)
+        key = placement == :outside ? :progress_bar_value_outside : :progress_bar_value
+        template.content_tag(
+          :span,
+          text,
+          **merge_html_options(
+            theme.resolve(key),
+            { data: { "progress-target": "value" }, aria: { hidden: true } }
+          )
         )
-        template.content_tag(:div, render_fill, **html_options)
       end
 
       # `data-intent` is a theme-independent styling hook the theme colors via attribute variants.
-      def render_fill(intent: nil)
+      def render_fill(intent: nil, key: :progress_bar_fill)
         data = { "progress-target": "fill" }
         data[:intent] = intent if intent
-        template.content_tag(:div, nil, **merge_html_options(theme.resolve(:progress_bar_fill), { data: data }))
+        template.content_tag(:div, nil, **merge_html_options(theme.resolve(key), { data: data }))
       end
 
       # Slots are aria-hidden — the container owns the progressbar ARIA.
       def render_segment(intent: nil)
         template.content_tag(
           :div,
-          render_fill(intent: intent),
+          render_fill(intent: intent, key: :progress_segment_fill),
           **merge_html_options(theme.resolve(:progress_segment), { aria: { hidden: true } })
         )
       end

data/lib/stimulus_plumbers/components/progress_ring.rb

@@ -12,13 +12,14 @@ module StimulusPlumbers
       private
 
       def render_ring(value:, max: 100, min: 0, indeterminate: false, size: nil, **kwargs)
+        current      = clamp(value, min, max)
         icon_options = merge_html_options(
           theme.resolve(:progress_ring, size: size),
           kwargs,
           progress_stimulus_data(
-            value: value, min: min, max: max, variant: "ring", "progress-indeterminate-value": indeterminate
+            value: current, min: min, max: max, variant: "ring", "progress-indeterminate-value": indeterminate
           ),
-          { role: "progressbar", aria: progress_aria(value: value, min: min, max: max, indeterminate: indeterminate) }
+          { role: "progressbar", aria: progress_aria(value: current, min: min, max: max, indeterminate: indeterminate) }
         )
         Components::Icon.new(template).render("progress-ring", **icon_options)
       end

data/lib/stimulus_plumbers/form/builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "action_view/version"
+require "action_view/helpers/tags/translator"
 
 require_relative "../plumber/options/aria"
 require_relative "../plumber/options/html"
@@ -17,6 +18,8 @@ require_relative "fields/inputs/datetime"
 require_relative "fields/inputs/radio"
 require_relative "fields/inputs/file"
 require_relative "fields/inputs/password"
+require_relative "fields/inputs/progress"
+require_relative "fields/inputs/range"
 require_relative "fields/inputs/search"
 require_relative "fields/inputs/select"
 require_relative "fields/inputs/select/grouped"
@@ -39,6 +42,8 @@ module StimulusPlumbers
       include Fields::Inputs::Radio
       include Fields::Inputs::File
       include Fields::Inputs::Password
+      include Fields::Inputs::Progress
+      include Fields::Inputs::Range
       include Fields::Inputs::Search
       include Fields::Inputs::Select
       include Fields::Inputs::Select::Grouped
@@ -49,25 +54,36 @@ module StimulusPlumbers
       include Fields::Inputs::TextArea
 
       def field(attribute, as:, **options, &block)
-        field_opts = options.slice(*Field::OPTIONS)
+        field_opts = field_options(attribute, options)
         input_opts = options.except(*Field::OPTIONS)
         render_field(as, attribute, field_opts, input_opts, &block)
       end
 
       def collection_field(attribute, as:, collection:, value_method:, text_method:, **options)
-        field_opts = options.slice(*Field::OPTIONS)
+        field_opts = field_options(attribute, options)
         input_opts = options.except(*Field::OPTIONS)
         render_collection_field(as, attribute, field_opts, collection, value_method, text_method, input_opts)
       end
 
       def choice(attribute, as:, collection: nil, value_method: nil, text_method: nil, **options)
-        field_opts = options.slice(*Field::OPTIONS)
+        field_opts = field_options(attribute, options)
         input_opts = options.except(*Field::OPTIONS)
         render_choice_field(as, attribute, field_opts, collection, value_method, text_method, input_opts)
       end
 
       private
 
+      def field_options(attribute, options)
+        options.slice(*Field::OPTIONS).tap { |opts| opts[:label] ||= default_label(attribute) }
+      end
+
+      # Mirrors f.label: helpers.label.* → human_attribute_name → humanize.
+      def default_label(attribute)
+        ActionView::Helpers::Tags::Translator.new(
+          object, @object_name.to_s, attribute.to_s, scope: "helpers.label"
+        ).translate.presence || attribute.to_s.humanize
+      end
+
       def theme
         StimulusPlumbers.config.theme.current
       end
@@ -77,7 +93,7 @@ module StimulusPlumbers
 
         validate_field_block!(as, block)
 
-        field = Field.new(@template, **field_opts)
+        field = Field.new(@template, label_mode: Fields::Renderer.label_mode(as), **field_opts)
         field.render(object, attribute, input_id: field_id(attribute)) do |html_opts, opts, error|
           Plumber::Dispatcher.build(
             Fields::Renderer::FIELD.fetch(as),

data/lib/stimulus_plumbers/form/field.rb

@@ -13,26 +13,40 @@ module StimulusPlumbers
       COLLECTION_TYPES = %i[radio check_box collection_select grouped_collection_select].freeze
       OPTIONS          = (Base::OPTIONS + %i[hide_label]).freeze
 
-      attr_reader :hide_label
+      # :aria uses aria-labelledby because non-labelable components cannot use `<label for>`.
+      LABEL_MODES = %i[native aria].freeze
+
+      attr_reader :hide_label, :label_mode
 
       class << self
         def label_id(input_id)
           [input_id, "label"].compact.join("_")
         end
+
+        def validate_label_mode!(mode)
+          return mode if LABEL_MODES.include?(mode)
+
+          raise ArgumentError, "unknown label_mode: #{mode.inspect} (expected one of #{LABEL_MODES.join(", ")})"
+        end
       end
 
-      def initialize(template, hide_label: false, **kwargs)
+      def initialize(template, hide_label: false, label_mode: :native, **kwargs)
         super(template, **kwargs)
         @hide_label = hide_label
+        @label_mode = self.class.validate_label_mode!(label_mode)
       end
 
       def label_hidden?
         @hide_label
       end
 
+      def native_label?
+        @label_mode == :native
+      end
+
       def render(object, attribute, input_id:, &block)
         @label ||= attribute.to_s.humanize
-        case @floating
+        case native_label? ? @floating : nil
         when *StimulusPlumbers::Themes::Schema::Form::Floating::Ranges::TYPE
           render_floating_field(object, attribute, input_id, &block)
         else
@@ -42,6 +56,18 @@ module StimulusPlumbers
 
       private
 
+      def build_aria(object, attribute, input_id)
+        return super if native_label?
+
+        { describedby: described_by(object, attribute, input_id), labelledby: self.class.label_id(input_id) }.compact
+      end
+
+      def build_html_options(input_id, aria)
+        return super if native_label?
+
+        { id: input_id, aria: aria }
+      end
+
       def render_default_field(object, attribute, input_id, &block)
         error_override = error?(object, attribute)
         aria           = build_aria(object, attribute, input_id)
@@ -59,13 +85,15 @@ module StimulusPlumbers
         end
       end
 
+      # hide_label is visual only; :aria fields cannot be required.
       def field_label(input_id)
         Fields::Label.new(@template).render(
           text:     @label,
-          for_id:   input_id,
+          for_id:   (input_id if native_label?),
           id:       self.class.label_id(input_id),
-          required: @required,
-          hidden:   @hide_label
+          required: native_label? && @required,
+          hidden:   @hide_label,
+          tag:      native_label? ? :label : :span
         )
       end