stimulus_plumbers 0.4.15 → 0.4.17

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
 

data/lib/stimulus_plumbers/form/fields/inputs/progress.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Form
+    module Fields
+      module Inputs
+        module Progress
+          private
+
+          # A progressbar submits nothing and is never invalid — it reads its value from the model
+          # attribute, and `floating:` is dropped so it can't leak onto the element as an attribute.
+          def render_progress(attribute, html_opts, opts, _error, segments: nil, format: nil, readout: :inside, **kwargs)
+            html_options = merge_html_options(
+              theme.resolve(:form_field_input_progress), opts, html_opts, kwargs.except(:floating)
+            )
+            value     = object.public_send(attribute)
+            component = Components::ProgressBar.new(@template)
+            if segments
+              raise ArgumentError, "format: is not supported with segments:" unless format.nil?
+
+              component.render_segmented(value: value, segments: segments, **html_options)
+            else
+              component.render(value: value, format: format, readout: readout, **html_options)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/form/fields/inputs/range.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Form
+    module Fields
+      module Inputs
+        # A range is a track and a thumb, not a text box, so it takes none of the text input's
+        # chrome. With `format:` it grows a readout driven by the progress controller.
+        module Range
+          include Components::Progress::Shared
+
+          def range_field(attribute, **options)
+            super(attribute, merge_html_options(theme.resolve(:form_field_input_range), options.except(:floating)))
+          end
+
+          private
+
+          # `floating:` is dropped — a label can't sit inside a slider.
+          def render_range_input(attribute, html_opts, opts, _error, format: nil, min: 0, max: 100, **kwargs)
+            validate_format!(format)
+            current = clamp(numeric(object.public_send(attribute)), min, max)
+            input   = range_input(attribute, current, min, max, format, html_opts, opts, kwargs.except(:floating))
+            return input if format.nil?
+
+            range_group(input, current, min, max, format)
+          end
+
+          # No readout to contain, so the input hosts the controller itself.
+          def range_input(attribute, current, min, max, format, html_opts, opts, kwargs)
+            wired = format.nil? ? range_stimulus_data(current, min, max, format) : { data: { "progress-target": "input" } }
+            html_options = merge_html_options(
+              theme.resolve(:form_field_input_range),
+              opts,
+              html_opts,
+              kwargs,
+              wired,
+              # The input carries the track gradient, so the fill percentage lands here, not on
+              # the wrapper. Server-rendered so the fill is right before the controller connects.
+              { min: min, max: max, style: "--sp-progress-percent: #{integral(percent(current, min, max).round(2))}" }
+            )
+            @template.range_field(@object_name, attribute, objectify_options(html_options))
+          end
+
+          # A Stimulus target must be a descendant of its controller element, so a readout
+          # forces a wrapper local to the input row.
+          def range_group(input, current, min, max, format)
+            html_options = merge_html_options(
+              theme.resolve(:form_field_input_range_group),
+              range_stimulus_data(current, min, max, format)
+            )
+            body = @template.safe_join([input, range_value(format, current, min, max)])
+            @template.content_tag(:div, body, **html_options)
+          end
+
+          # aria-hidden: the native input already announces its own value.
+          def range_value(format, current, min, max)
+            @template.content_tag(
+              :span,
+              value_text(format, current, min, max),
+              **merge_html_options(
+                theme.resolve(:form_field_input_range_value),
+                { data: { "progress-target": "value" }, aria: { hidden: true } }
+              )
+            )
+          end
+
+          def range_stimulus_data(current, min, max, format)
+            progress_stimulus_data(
+              value:   current,
+              min:     min,
+              max:     max,
+              variant: "range",
+              action:  "input->progress#refresh",
+              **(format.nil? ? {} : { "progress-format-value": format })
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/form/fields/inputs/text.rb

@@ -5,6 +5,7 @@ module StimulusPlumbers
     module Fields
       module Inputs
         module Text
+          # `range` is not here — see inputs/range.rb; it shares none of the text input chrome.
           TEXT_FIELD_METHODS = {
             text:           :text_field,
             email:          :email_field,
@@ -14,7 +15,6 @@ module StimulusPlumbers
             color:          :color_field,
             month:          :month_field,
             week:           :week_field,
-            range:          :range_field,
             datetime_local: :datetime_local_field
           }.freeze
 

data/lib/stimulus_plumbers/form/fields/renderer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../field"
+
 module StimulusPlumbers
   module Form
     module Fields
@@ -18,6 +20,7 @@ module StimulusPlumbers
           text_area:      :render_text_area_input,
           file:           :render_file_input,
           password:       :render_password_input,
+          progress:       :render_progress,
           code:           :render_code_input,
           credit_card:    :render_credit_card_input,
           date:           :render_combobox_date,
@@ -26,6 +29,44 @@ module StimulusPlumbers
           search:         :render_combobox_typeahead
         }.freeze
 
+        # Require every field type to declare its caption association.
+        LABEL_MODE = {
+          text:           :native,
+          email:          :native,
+          number:         :native,
+          url:            :native,
+          tel:            :native,
+          color:          :native,
+          month:          :native,
+          week:           :native,
+          range:          :native,
+          datetime_local: :native,
+          text_area:      :native,
+          file:           :native,
+          password:       :native,
+          progress:       :aria,
+          code:           :native,
+          credit_card:    :native,
+          date:           :native,
+          time:           :native,
+          select:         :native,
+          search:         :native
+        }.freeze
+
+        missing = FIELD.keys - LABEL_MODE.keys
+        raise ArgumentError, "field types missing a label_mode: #{missing.join(", ")}" if missing.any?
+
+        extra = LABEL_MODE.keys - FIELD.keys
+        raise ArgumentError, "label_mode declared for unknown field types: #{extra.join(", ")}" if extra.any?
+
+        LABEL_MODE.each_value { |mode| Field.validate_label_mode!(mode) }
+
+        class << self
+          def label_mode(as)
+            LABEL_MODE.fetch(as)
+          end
+        end
+
         COLLECTION = {
           collection_select:         :render_collection_combobox_dropdown,
           grouped_collection_select: :render_grouped_collection_combobox_dropdown

data/lib/stimulus_plumbers/helpers/progress_helper.rb

@@ -3,8 +3,10 @@
 module StimulusPlumbers
   module Helpers
     module ProgressHelper
-      def sp_progress_bar(value:, min: 0, max: 100, indeterminate: false, **kwargs)
-        Components::ProgressBar.new(self).render(value: value, min: min, max: max, indeterminate: indeterminate, **kwargs)
+      def sp_progress_bar(value:, min: 0, max: 100, indeterminate: false, format: nil, readout: :inside, **kwargs)
+        Components::ProgressBar.new(self).render(
+          value: value, min: min, max: max, indeterminate: indeterminate, format: format, readout: readout, **kwargs
+        )
       end
 
       def sp_progress_segmented(value:, segments:, min: 0, max: 100, mode: :discrete, indeterminate: false, ramp: nil, **kwargs)

data/lib/stimulus_plumbers/themes/schema/progress/ranges.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Themes
+    module Schema
+      module Progress
+        module Ranges
+          PLACEMENT = %i[inside outside].freeze
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/themes/schema.rb

@@ -11,6 +11,7 @@ require_relative "schema/form/ranges"
 require_relative "schema/form/checkbox/ranges"
 require_relative "schema/form/floating/ranges"
 require_relative "schema/form/radio/ranges"
+require_relative "schema/progress/ranges"
 require_relative "schema/icon"
 
 module StimulusPlumbers
@@ -179,6 +180,10 @@ module StimulusPlumbers
           type:    { default: :default,  validate: Form::Radio::Ranges::TYPE },
           variant: { default: :tertiary, validate: Form::Radio::Ranges::VARIANT }
         }.freeze,
+        form_field_input_progress:              {}.freeze,
+        form_field_input_range:                 {}.freeze,
+        form_field_input_range_group:           {}.freeze,
+        form_field_input_range_value:           {}.freeze,
         form_field_input_combobox:              {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
@@ -255,13 +260,19 @@ module StimulusPlumbers
         popover:           {}.freeze
       }.freeze
 
+      # The outside readout gets its own keys, not parameters on existing ones — a theme method
+      # written before them has no keyword to accept.
       PROGRESS = {
-        progress_bar:       {}.freeze,
-        progress_bar_fill:  {}.freeze,
-        progress_segmented: {}.freeze,
-        progress_segment:   {}.freeze,
-        progress_ring:      { size: { default: nil, validate: %i[sm md lg] } }.freeze,
-        progress_meter:     {}.freeze
+        progress_bar:               { labelled: { default: false, validate: Ranges::BOOL } }.freeze,
+        progress_bar_group:         {}.freeze,
+        progress_bar_fill:          {}.freeze,
+        progress_bar_value:         {}.freeze,
+        progress_bar_value_outside: {}.freeze,
+        progress_segment_group:     {}.freeze,
+        progress_segment:           {}.freeze,
+        progress_segment_fill:      {}.freeze,
+        progress_ring:              { size: { default: nil, validate: %i[sm md lg] } }.freeze,
+        progress_meter:             {}.freeze
       }.freeze
 
       TIMELINE = {

data/lib/stimulus_plumbers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusPlumbers
-  VERSION = "0.4.15"
+  VERSION = "0.4.17"
 end

data/vendor/ARIA.md

@@ -97,6 +97,16 @@ Two helper classes handle keyboard navigation in controllers — see [`stimulus-
 - Accepted tradeoff: because `indeterminate` has no HTML attribute, the server can only render the master's initial `checked` state for the all-true case; every other case (including mixed) renders unchecked and is corrected to `indeterminate` once the `checklist` controller connects — a brief, accepted flash for the mixed case only.
 - Disabled (readonly) items are excluded from the master's aggregate and from bulk toggling — the `checklist` controller filters them out via their own `.disabled` property, mirroring their exclusion from tab order and AT interaction.
 
+#### Progress (`progress_controller`, `sp_progress_*`)
+- `role="progressbar"` is read-only and never focusable — it reports a value, it does not accept one. An interactive equivalent is a native `<input type="range">` (or `role="slider"`), not a progressbar with `tabindex`
+- Value: `aria-valuemin`/`aria-valuemax` always; `aria-valuenow` omitted while indeterminate (an omitted `valuenow` is what signals "unknown progress" to AT)
+- `aria-valuetext` only when the readout text is not derivable from `aria-valuenow` — set for the `value`/`value_max` formats, deliberately **not** for `percent`, where AT already computes the percentage and a duplicate would be announced twice
+- On-screen readout is `aria-hidden="true"` — the value reaches AT through `aria-valuenow`/`aria-valuetext`, so exposing the span too would double-announce it
+- Name: `aria-label` standalone, or `aria-labelledby` → a visible caption. `<label for>` cannot name a progressbar — `for=` is only valid against a labelable element (`button`, `input`, `meter`, `output`, `progress`, `select`, `textarea`), so a `<div role="progressbar">` targeted by one is silently left unnamed (WCAG 4.1.2). Form fields rendering a progressbar therefore emit a `<span>` caption, not a `<label>`
+- No `aria-invalid`/`aria-required` on a progressbar — neither is supported on the role, and it submits nothing that could be invalid. Errors still attach via `aria-describedby`
+- Segment slots are decorative (`aria-hidden="true"`) — the value is announced once, by the container
+- The `range` variant drives a native `<input type="range">` and writes **no** ARIA: the native control already exposes slider role, value, and keyboard operation, and duplicating them announces worse than leaving them alone. It keeps an ordinary `<label for>` because an `input` is labelable
+
 #### Avatar / Card / Icon
 - Decorative images/icons: `aria-hidden="true"` or `alt=""`
 - Meaningful images: descriptive `alt` text

data/vendor/component/manifest.json

@@ -66,7 +66,11 @@
     "values": []
   },
   "combobox-date": {
-    "actions": [],
+    "actions": [
+      "onDaySelect",
+      "onMonthSelect",
+      "onYearSelect"
+    ],
     "listens": [
       "selected"
     ],
@@ -76,7 +80,7 @@
   "combobox-dropdown": {
     "actions": [
       "onNavigate",
-      "select"
+      "onSelect"
     ],
     "listens": [
       "selected"
@@ -87,7 +91,7 @@
   "combobox-time": {
     "actions": [
       "onNavigate",
-      "select"
+      "onSelect"
     ],
     "listens": [
       "selected"
@@ -117,7 +121,8 @@
   },
   "input-combobox": {
     "actions": [
-      "onInput"
+      "onInput",
+      "onSelect"
     ],
     "listens": [
       "changed"
@@ -128,6 +133,7 @@
   "input-formatter": {
     "actions": [
       "onBlur",
+      "onChange",
       "onFocus",
       "onInput"
     ],
@@ -166,6 +172,7 @@
   "popover": {
     "actions": [
       "close",
+      "closeOnSelect",
       "open",
       "toggle"
     ],
@@ -174,14 +181,19 @@
     "values": []
   },
   "progress": {
-    "actions": [],
+    "actions": [
+      "refresh"
+    ],
     "listens": [],
     "targets": [
       "fill",
-      "meter"
+      "input",
+      "meter",
+      "value"
     ],
     "values": [
       "current",
+      "format",
       "high",
       "indeterminate",
       "low",

data/vendor/controller/docs/progress.md

@@ -1,6 +1,6 @@
 # Progress
 
-Value-driven progress indicator supporting four render variants: a linear bar, a segmented bar, an SVG ring, and a native `<meter>`.
+Value-driven progress indicator supporting five render variants: a linear bar, a segmented bar, an SVG ring, a native `<meter>`, and a native `<input type="range">`.
 
 ## Stimulus Identifier
 
@@ -12,12 +12,14 @@ Value-driven progress indicator supporting four render variants: a linear bar, a
 | ------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `fill`  | `<div>` (bar) / `<circle>` (ring) | Element whose `width` (bar) or `stroke-dasharray`/`stroke-dashoffset` (ring) is set. Segmented renders **one `fill` per segment**; the controller distributes the value across them |
 | `meter` | `<meter>`                         | Present only for `variant: "meter"` — native element, attributes synced directly                                                                                                    |
+| `value` | `<span>`                          | Optional on-screen readout; its `textContent` is set from `format`. Bar and range variants                                                                                          |
+| `input` | `<input type="range">`            | Range-only, and only when a readout is present — the controller then sits on a wrapper containing both                                                                              |
 
 ## Values
 
 | Name                    | Type    | Default      | Purpose                                                                                                                                |
 | ----------------------- | ------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `variant`               | String  | `"bar"`      | `"bar"` \| `"segmented"` \| `"ring"` \| `"meter"`                                                                                      |
+| `variant`               | String  | `"bar"`      | `"bar"` \| `"segmented"` \| `"ring"` \| `"meter"` \| `"range"`                                                                         |
 | `current`               | Number  | `0`          | Current value                                                                                                                          |
 | `min`                   | Number  | `0`          | Range minimum                                                                                                                          |
 | `max`                   | Number  | `100`        | Range maximum                                                                                                                          |
@@ -27,19 +29,37 @@ Value-driven progress indicator supporting four render variants: a linear bar, a
 | `indeterminate`         | Boolean | `false`      | Suppresses `aria-valuenow`; toggles the `sp-progress-indeterminate` class                                                              |
 | `indeterminateFraction` | Number  | `0.25`       | Bar width / ring arc / segment chunk-width fraction rendered while indeterminate                                                       |
 | `segmentMode`           | String  | `"discrete"` | Segmented-only. `"discrete"` lights a whole segment once progress reaches into it; `"continuous"` partially fills the boundary segment |
+| `format`                | String  | `""`         | Readout text for the `value` target: `"percent"` \| `"value"` \| `"value_max"`. Empty or unrecognized renders nothing                  |
+
+### Readout formats
+
+| `format`      | Renders   | `aria-valuetext` |
+| ------------- | --------- | ---------------- |
+| `"percent"`   | `45%`     | not set          |
+| `"value"`     | `45`      | `45`             |
+| `"value_max"` | `45 / 60` | `45 / 60`        |
+
+`percent` omits `aria-valuetext` — assistive technology derives the percentage from `aria-valuenow` itself, so setting it would only duplicate what AT already announces. The readout element is decorative (`aria-hidden`); the value reaches AT through `aria-valuenow`/`aria-valuetext`.
+
+The `range` variant writes no `aria-value*` at all — a native `<input type="range">` already exposes its own slider semantics — and sets `--sp-progress-percent` on the input so a theme can paint the filled portion of the track.
+
+The `bar` variant sets `--sp-progress-percent` too, on the controller element, alongside the fill target's width. A theme can use it to split the readout's color at the fill edge. It is unset until the controller connects, so read it as `var(--sp-progress-percent, 0)` to match the server-rendered (empty) fill.
+
+The rendered number is the value clamped to `[min, max]`, so an out-of-range `current` reads as the nearest bound rather than an impossible percentage. An empty or inverted range (`max <= min`) renders `0%`. While `indeterminate`, the readout is blank and `aria-valuetext` is removed.
 
 ## Methods
 
-| Method                       | Wired via               | Purpose                                                                                                   |
-| ---------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
-| `setValue(value)`            | —                       | Programmatic API — clamps to `[min, max]`, updates `currentValue`, dispatches `progress:changed`          |
-| `currentValueChanged(value)` | Stimulus value callback | Recalculates fill/meter attrs whenever `current` changes (covers `setValue()` and direct attribute edits) |
+| Method                       | Wired via                 | Purpose                                                                                                   |
+| ---------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `setValue(value)`            | —                         | Programmatic API — clamps to `[min, max]`, updates `currentValue`, dispatches `progress:changed`          |
+| `currentValueChanged(value)` | Stimulus value callback   | Recalculates fill/meter attrs whenever `current` changes (covers `setValue()` and direct attribute edits) |
+| `refresh()`                  | `input->progress#refresh` | Range-only. Reads the native input's value and passes it to `setValue()`                                  |
 
 ## Dispatches
 
-| Event              | Detail                | When                                 |
-| ------------------ | --------------------- | ------------------------------------ |
-| `progress:changed` | `{ value, min, max }` | After `setValue()` updates the value |
+| Event              | Detail                | When                                                                                   |
+| ------------------ | --------------------- | -------------------------------------------------------------------------------------- |
+| `progress:changed` | `{ value, min, max }` | After `setValue()` updates the value — including a range drag, which routes through it |
 
 ## Example HTML
 
@@ -55,6 +75,18 @@ Value-driven progress indicator supporting four render variants: a linear bar, a
   <div data-progress-target="fill"></div>
 </div>
 
+<!-- Bar with an on-screen readout -->
+<div
+  role="progressbar"
+  data-controller="progress"
+  data-progress-current-value="45"
+  data-progress-max-value="100"
+  data-progress-format-value="percent"
+>
+  <div data-progress-target="fill"></div>
+  <span data-progress-target="value" aria-hidden="true">45%</span>
+</div>
+
 <!-- Segmented — one fill per segment; number of segments = number of fill targets -->
 <div
   role="progressbar"
@@ -92,6 +124,34 @@ Value-driven progress indicator supporting four render variants: a linear bar, a
   data-progress-max-value="100"
 ></meter>
 
+<!-- Range — no readout, so the controller sits on the input itself -->
+<input
+  type="range"
+  min="0"
+  max="100"
+  value="45"
+  style="--sp-progress-percent: 45"
+  data-controller="progress"
+  data-progress-variant-value="range"
+  data-progress-current-value="45"
+  data-progress-min-value="0"
+  data-progress-max-value="100"
+  data-action="input->progress#refresh"
+/>
+
+<!-- Range with a readout — a target must be a descendant, so a wrapper hosts the controller -->
+<div
+  data-controller="progress"
+  data-progress-variant-value="range"
+  data-progress-current-value="45"
+  data-progress-max-value="100"
+  data-progress-format-value="percent"
+  data-action="input->progress#refresh"
+>
+  <input type="range" min="0" max="100" value="45" style="--sp-progress-percent: 45" data-progress-target="input" />
+  <span data-progress-target="value" aria-hidden="true">45%</span>
+</div>
+
 <!-- Indeterminate -->
 <div role="progressbar" data-controller="progress" data-progress-indeterminate-value="true">
   <div data-progress-target="fill"></div>

data/vendor/controller/guide.md

@@ -3,14 +3,68 @@
 For a non-Rails / plain JS consumer of `@stimulus-plumbers/controllers`. Rails apps get this wired
 automatically via the `stimulus_plumbers` gem's `sp_*` helpers — skip this guide for Rails.
 
+## Install
+
 ```bash
-npm install @stimulus-plumbers/controllers
+npm install @hotwired/stimulus @stimulus-plumbers/controllers
+```
+
+## Register
+
+Every controller is a named export. Import the ones you use and register each under its identifier:
+
+```javascript
+import { Application } from '@hotwired/stimulus';
+import { PopoverController, ProgressController, ComboboxDateController } from '@stimulus-plumbers/controllers';
+
+const application = Application.start();
+
+application.register('popover', PopoverController);
+application.register('progress', ProgressController);
+application.register('combobox-date', ComboboxDateController);
+```
+
+The export name is the identifier in PascalCase plus `Controller` — `combobox-date` →
+`ComboboxDateController`. For the full identifier list ask `list_controllers` / read
+`controller://index`; each one's targets, values, classes, outlets, and events are in
+`get_controller_schema(name: identifier)` — `name:` is the identifier (`combobox-date`), not the
+export name. Narrative docs come from `get_controller_docs(name: family)`, which takes the family
+(`combobox`) rather than the identifier; `list_controller_docs` lists the families. Outside MCP, the
+[Controllers table](https://github.com/ryancyq/stimulus-plumbers/blob/main/stimulus-plumbers/README.md#controllers)
+lists the same identifiers.
+
+Registering a controller the page never uses is harmless — Stimulus only instantiates on a matching
+`data-controller`.
+
+## Wire the markup
+
+Interactive components (combobox, popover, calendar) expect their `data-controller`, target, and
+value attributes to already be present in the rendered HTML. Rails apps get these from `sp_*`
+helpers; a plain-JS setup writes them by hand, following the HTML structure in each controller's
+doc:
+
+```html
+<div
+  role="progressbar"
+  data-controller="progress"
+  data-progress-current-value="30"
+  data-progress-min-value="0"
+  data-progress-max-value="100"
+>
+  <div data-progress-target="fill"></div>
+</div>
 ```
 
-Import and register each controller you use with your Stimulus application — see
-[README.md](../README.md#setup) for the full import + `application.register(...)` list and the
-[Controllers table](../README.md#controllers) for identifiers and their docs.
+Markup shape is per-controller — take the authoritative structure from `get_controller_docs(name:)`
+rather than adapting this example.
+
+## Styling
+
+Controllers ship no CSS; they toggle classes and attributes only. Bring your own styles, or use the
+`stimulus_plumbers_tailwind` gem's token set (`guide://tailwind`).
+
+## Accessibility
 
-Interactive components (combobox, popover, calendar) expect their `data-controller` attributes to
-already be present in the rendered HTML — Rails apps get these from `sp_*` helpers; a plain-JS setup
-must add them manually per each controller's doc.
+Keyboard, focus, and ARIA behaviour per component is in `aria://reference` — read it before
+hand-writing markup, since the controllers assume the documented roles and relationships are
+present.