stimulus_plumbers 0.4.14 → 0.4.16

data/config/locales/en.yml

@@ -30,3 +30,15 @@ en:
         hide: "Hide password"
       search:
         clear: "Clear search"
+    password:
+      rules_heading: "It's better to have:"
+      rules:
+        length: "At least %{count} characters"
+        uppercase: "One uppercase letter"
+        lowercase: "One lowercase letter"
+        digit: "One number"
+        symbol: "One symbol"
+      levels:
+        weak: "Weak password"
+        fine: "Fine password"
+        strong: "Strong password"

data/docs/component/combobox.md

@@ -8,7 +8,8 @@ See [docs/component/combobox.md](../../../stimulus-plumbers/docs/component/combo
 
 ### `sp_combobox`
 
-Single entry point. The panel type is chosen by a method call on the yielded builder
+Single entry point. The panel type is chosen by a method call on the yielded
+`Combobox::Config` ([`Plumber::Config`](plumber.md#plumberconfig))
 (`c.dropdown`, `c.typeahead`, `c.date`, `c.time`) — the panel owns its `aria-haspopup`,
 popup id, trigger icon, and wrapper data. The `sp_combobox_*` helpers below are thin
 wrappers over this.
@@ -31,7 +32,7 @@ end %>
 | `close_on_select` | `false` keeps the panel open after a selection   |
 | `**html_options`  | Forwarded to the wrapper `div`                   |
 
-Builder methods: `c.dropdown(options:, value:, label:)`, `c.typeahead(options:, value:, label:, url:)`,
+Config methods: `c.dropdown(options:, value:, label:)`, `c.typeahead(options:, value:, label:, url:)`,
 `c.date(value:)`, `c.time(format:, step:, value:)`.
 
 ---

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.
 
 ---
 
@@ -108,6 +112,9 @@ Three methods render a complete, accessible field:
 <%= f.field :bio,      as: :text_area, hint: "Tell us about yourself." %>
 <%= f.field :avatar,   as: :file %>
 <%= f.field :password, as: :password, revealable: true %>
+<%= f.field :password, as: :password do |p| %>
+  <% p.enforce min_length: 12, max_length: 64 %>
+<% end %>
 <%= f.field :verification_code, as: :code, length: 6 %>
 <%= f.field :card_number, as: :credit_card %>
 <%= f.field :email,    as: :email,    floating: :filled %>
@@ -118,6 +125,8 @@ Three methods render a complete, accessible field:
       choices: ["ruby", "rails", "hotwire"], clearable: true %>
 ```
 
+`f.field` can take a block when its renderer declares `&block`; that declaration opts the renderer into the block DSL. For example, the password renderer yields a `Password::Requirements` that accepts `enforce(**options)` and `rule(...)` configuration — see **Password** below. Strength renders a `password-strength` wrapper containing the input, a native `<meter>`, a polite live level, a rules heading, and a rules list. The input references the rules list with `aria-describedby`.
+
 `choices:` takes the standard Rails shape — an array of `[label, value]` pairs (or a flat array of strings).
 
 **Floating label variants** — label starts inside the input, animates above on focus/fill. Compatible with text-like inputs only.
@@ -162,13 +171,40 @@ Use `f.search_field` for a native `<input type="search">`.
 
 **Password** (`as: :password`) — reveal-toggle wrapper backed by `input-revealable`.
 
-| Option         | Values  | Default              | Description                                 |
-| -------------- | ------- | -------------------- | ------------------------------------------- |
-| `revealable`   | Boolean | `false`              | Adds a show/hide toggle button on the input |
-| `autocomplete` | String  | `"current-password"` | Native autocomplete value                   |
+| Option         | Values                   | Default              | Description                                      |
+| -------------- | ------------------------ | -------------------- | ------------------------------------------------ |
+| `revealable`   | Boolean                  | `false`              | Adds a show/hide toggle button on the input      |
+| `autocomplete` | String                   | `"current-password"` | Native autocomplete value                        |
+| `requirements` | `Password::Requirements` | `nil`                | Prebuilt rule set that drives the strength meter |
 
 Use `f.password_field` for a plain `<input type="password">` (also accepts `revealable:`).
 
+**Strength rules.** Declare rules inline with a block, or pass a shared `requirements:` object. `enforce(min_length:, max_length:, uppercase:/lowercase:/digit:/symbol:)` enables built-ins — a character-class option takes `true` (≥1), an Integer (≥N), or a Range (`N..M` occurrences); the length rule requires **both** `min_length` and `max_length`. `rule(key, label, pattern:, min:, max:, negate:)` adds a custom rule (`negate: true` forbids matches).
+
+```erb
+<%= f.field :password, as: :password do |p| %>
+  <% p.enforce min_length: 12, max_length: 64, digit: true %>
+  <% p.rule :no_spaces, "No spaces", pattern: /\s/, negate: true %>
+<% end %>
+```
+
+**Server enforcement.** Build one `Password::Requirements` and share it between the form meter and the model validator so they cannot drift:
+
+```ruby
+PASSWORD_RULES = StimulusPlumbers::Password::Requirements.build do |r|
+  r.enforce(min_length: 12, max_length: 64, digit: true)
+end
+
+# model — PasswordStrengthValidator; valid? iff every enabled rule passes
+validates :password, password_strength: { with: PASSWORD_RULES }
+```
+
+```erb
+<%= f.field :password, as: :password, requirements: PASSWORD_RULES %>
+```
+
+The validator also accepts inline options (`password_strength: { min_length: 12, max_length: 64, digit: true }`) and a custom `message:`. For the rule-descriptor wire contract and meter behaviour, see the [JS controller doc](../../../stimulus-plumbers/docs/component/password-strength.md).
+
 **Code** (`as: :code`) — character-cell entry backed by `input-formatter` and the `character-cells` plumber. The native input remains the accessible control; cells are decorative.
 
 | Option         | Values                                   | Default                | Description                                              |
@@ -191,6 +227,37 @@ Use `f.password_field` for a plain `<input type="password">` (also accepts `reve
 
 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/plumber.md

@@ -105,7 +105,7 @@ end
 
 ## Plumber::Slots
 
-Base class for a component's slot DSL (e.g. `renderer.with_title(value)`, `renderer.with_content { ... }`). Used by `Card`, `Button`, `Link`, `List::Item`, `Timeline::Event`, and `Combobox::Builder`.
+Base class for a component's slot DSL (e.g. `renderer.with_title(value)`, `renderer.with_content { ... }`). Used by `Card`, `Button`, `Link`, `List::Item`, and `Timeline::Event`.
 
 ```ruby
 class MySlots < StimulusPlumbers::Plumber::Slots
@@ -123,6 +123,45 @@ yield slots if block_given?
 
 Slots needing custom validation (e.g. a required keyword) define `with_*` manually instead of using the `slot` DSL — see `Card::Slots#with_action`.
 
+`set_slot` is private and returns `nil`, so a `with_*` method reads as a command — hand-written setters need no trailing `nil`. Reads go through the public `resolve` / `options_for`.
+
+---
+
+## Plumber::Config
+
+Sibling of `Slots` for block DSLs whose payload is configuration rather than content. Used by `Combobox::Config`. (Password rules are **not** a `Plumber::Config` — `Password::Requirements` is a standalone model-layer object; see the password field in [form.md](form.md).)
+
+**Which one to subclass — does the block body produce markup?** Yes → `Slots`. No → `Config`.
+
+|                   | `Plumber::Slots`                                 | `Plumber::Config`                                |
+| ----------------- | ------------------------------------------------ | ------------------------------------------------ |
+| Holds             | content — blocks rendered through the view       | configuration — values, hashes, class references |
+| Template used for | `capture` (essential)                            | passing through to renderers only                |
+| Declares          | `slot :a, :b` macro, generating `with_*` setters | plain named methods                              |
+| Public read API   | `resolve` / `options_for`                        | none — subclasses expose named readers           |
+
+`Config` never captures, so it inherits no `slot` macro. Its whole store is **private**: `Slots` publishes `resolve` because its payload is uniform content a renderer reads generically, whereas a `Config`'s settings are typed, so each subclass names its own readers.
+
+```ruby
+class MyConfig < StimulusPlumbers::Plumber::Config
+  def panel(**options)
+    configure(:panel, options)        # stores, returns nil
+  end
+
+  def panel_options
+    config(:panel)                    # reads, nil when unset
+  end
+
+  def panel?
+    configured?(:panel)               # distinguishes unset from set-to-nil
+  end
+end
+```
+
+Setters return `nil` for the same reason `set_slot` does — the DSL method reads as a command.
+
+Construct with the view `template`; `Config` exposes it via `attr_reader` so subclasses can hand it to renderers (see `Combobox::Config#render_panel`).
+
 ---
 
 ## Plumber::Options::Html

data/docs/component/progress.md

@@ -1,6 +1,6 @@
 # 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.
+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,34 +10,69 @@ Rails helpers for rendering the `progress` Stimulus controller's three 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
 layer motion on top (Tailwind slides it); without one, the bar renders
 as a static partial fill.
 
+### `sp_progress_segmented`
+
+```erb
+<%= 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. 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          |
+| `ramp:`          | `nil`       | `:strength` colors slots danger → warning → success by position (strength meter); `nil` = single color |
+| `indeterminate:` | `false`     | Omits `aria-valuenow`; a single chunk relays across the slots, one at a time                           |
+| `**html_options` | —           | Forwarded to the outer `<div role="progressbar">`                                                      |
+
 ### `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.) |
+| 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                                      |
+| `size:`          | `nil`   | `:sm` \| `:md` \| `:lg` size token; `nil` uses the icon's own size (override with `classes:`) |
+| `**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.
+Renders via the theme's icon registry (icon name `"progress-ring"`), the same mechanism as `sp_icon`. Resize with the `size:` token (`:sm`/`:md`/`:lg`) or, for an exact size, a `classes:`/`class:` override (e.g. `classes: "size-16"`) — there is no 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

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/card/slots.rb

@@ -10,7 +10,6 @@ module StimulusPlumbers
           raise ArgumentError, "card.body requires a block" unless block
 
           set_slot(:body, block)
-          nil
         end
 
         # Defined manually (not via `slot` DSL) because it requires a named `url:` keyword with validation.
@@ -18,7 +17,6 @@ module StimulusPlumbers
           raise ArgumentError, "card.action requires content (string or block) when url: is given" if url && value.nil? && !block
 
           set_slot(:action, block || value, url ? { url: url } : {})
-          nil
         end
       end
     end

data/lib/stimulus_plumbers/components/combobox/{builder.rb → config.rb}

@@ -5,7 +5,7 @@ module StimulusPlumbers
     class Combobox
       # Yielded to `Combobox#render`: selects a variant renderer, then exposes its
       # `metadata` (trigger/wrapper wiring) and renders its panel body.
-      class Builder < Plumber::Slots
+      class Config < Plumber::Config
         def dropdown(**options)
           select(Dropdown, options)
         end
@@ -23,22 +23,22 @@ module StimulusPlumbers
         end
 
         def selected?
-          @slots.key?(:variant)
+          configured?(:renderer)
         end
 
         def renderer
-          selection&.fetch(:renderer)
+          config(:renderer)
         end
 
         def options
-          selection ? selection[:options] : {}
+          config(:options) || {}
         end
 
         def metadata
           renderer ? renderer::Metadata : DefaultMetadata
         end
 
-        def render_panel(template, panel_attrs:)
+        def render_panel(panel_attrs:)
           renderer&.new(template)&.render(panel_attrs: panel_attrs, **options)
         end
 
@@ -70,12 +70,8 @@ module StimulusPlumbers
         private
 
         def select(renderer, options)
-          set_slot(:variant, { renderer: renderer, options: options })
-          nil
-        end
-
-        def selection
-          resolve(:variant)
+          configure(:renderer, renderer)
+          configure(:options, options)
         end
       end
     end

data/lib/stimulus_plumbers/components/combobox.rb

@@ -9,42 +9,42 @@ module StimulusPlumbers
 
       def render(trigger: {}, input: {}, id: nil, label: nil, close_on_select: nil, **kwargs, &block)
         trigger_opts = trigger.dup
-        builder      = resolve_builder(&block)
+        config       = resolve_config(&block)
         trigger_id   = id || trigger_opts.delete(:id) || template.sp_dom_id
         panel_id     = Popover.panel_id_for(trigger_id)
 
-        template.content_tag(:div, **combobox_attrs(input, close_on_select, builder, panel_id, kwargs)) do
-          build_popover(trigger_opts, input, builder, trigger_id, panel_id, label)
+        template.content_tag(:div, **combobox_attrs(input, close_on_select, config, panel_id, kwargs)) do
+          build_popover(trigger_opts, input, config, trigger_id, panel_id, label)
         end
       end
 
       private
 
-      def resolve_builder
-        builder = Combobox::Builder.new(template)
-        yield builder if block_given?
-        builder
+      def resolve_config
+        config = Combobox::Config.new(template)
+        yield config if block_given?
+        config
       end
 
-      def build_popover(trigger, input, builder, trigger_id, panel_id, label)
-        metadata = builder.metadata
+      def build_popover(trigger, input, config, trigger_id, panel_id, label)
+        metadata = config.metadata
 
         Components::Popover.new(template).build(panel_id: panel_id) do |p|
           p.trigger(haspopup: metadata.haspopup, controls: metadata.popup_id_for(panel_id)) do |attrs|
             build_combobox_trigger(attrs, trigger, input, metadata, trigger_id, label)
           end
           p.build_panel(classes: theme.resolve(:combobox_popover).fetch(:classes, "")) do |panel_attrs|
-            builder.render_panel(template, panel_attrs: panel_attrs)
+            config.render_panel(panel_attrs: panel_attrs)
           end
         end
       end
 
-      def combobox_attrs(input, close_on_select, builder, panel_id, kwargs)
+      def combobox_attrs(input, close_on_select, config, panel_id, kwargs)
         merge_html_options(
           theme.resolve(:combobox),
           kwargs,
           { data: stimulus_data(input[:value], close_on_select) },
-          { data: builder.metadata.stimulus_data(panel_id, builder.options) }
+          { data: config.metadata.stimulus_data(panel_id, config.options) }
         )
       end