stimulus_plumbers 0.4.5 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76a3529b969c106cec1fef750f3a76a5c05782f31b56e29c8c4640cd105d7dd7
-  data.tar.gz: 118813bf270d4eed2901da381d4effa1b663a5558e9c97b6041850ddeb63e572
+  metadata.gz: b138245a7a9711414d5c7bf052dbd55d42006f5e785626fd94bce96ffab6281d
+  data.tar.gz: e2e15e550f5678eecbfc7310628759590212fae21aa42c7eab60d7c049f2a47f
 SHA512:
-  metadata.gz: fccd6c0b45374752edd4583acb07d099668dcbdf3e745165775e86bd2b19603680f55b6641c37dbebe529b317772eceba6e1dc47bcc8b2637ae574009f6bc2b6
-  data.tar.gz: e7fe95f7e5f38a551a95cd27ac69466a73602603b6eac243e8469d59ea20e0f96cd9fcad8189742555ac6ba72f071ab92eadc2a9243e686258f6473d12416559
+  metadata.gz: 624a411ff21cb32deebdde9a3c68c0d0c43fed7ade306cc7299fdaadca7604a3053a2f9251df1608af393fc0129bffd75b6e244b9fd9e0477a4df72f859e0ddb
+  data.tar.gz: 8176752b32e5e730e7c8a47ba5aa44d96b591a38c44d0a71ad6d2d147404227b02aa581b00db36711da357cda872b96260187b62749e74f652acb2bd1a26a970

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [conventional commits](https://www.conventionalcommits.org/) for commit guidelines.
 
+---
+## [0.4.5](https://github.com/ryancyq/stimulus-plumbers/compare/stimulus-plumbers-rails/v0.4.4..stimulus-plumbers-rails/v0.4.5) - 2026-07-01
+
+### Bug Fixes
+
+- mcp executable ([#151](https://github.com/ryancyq/stimulus-plumbers/issues/151)) - ([5e772ce](https://github.com/ryancyq/stimulus-plumbers/commit/5e772ce2d8ceb7c517c2e7fdd44d3438b1e38139)) - Ryan Chang
+
 ---
 ## [0.4.4](https://github.com/ryancyq/stimulus-plumbers/compare/stimulus-plumbers-rails/v0.4.3..stimulus-plumbers-rails/v0.4.4) - 2026-06-30
 

data/README.md

@@ -6,6 +6,8 @@
 
 Rails helpers for accessible, WCAG 2.1 AA compliant UI components built on [Stimulus](https://stimulus.hotwired.dev/). Pairs with the [`@stimulus-plumbers/controllers`](../stimulus-plumbers) npm package.
 
+See [docs/guide.md](docs/guide.md) for a quick guide to building forms and views with this gem.
+
 ## Requirements
 
 - Ruby >= 3.0
@@ -40,6 +42,20 @@ Or use the form builder globally:
 config.action_view.default_form_builder = StimulusPlumbers::Form::Builder
 ```
 
+Run the install generator once to inject the `tokens.css` import into your CSS entry file:
+
+```bash
+bin/rails generate stimulus_plumbers:install
+```
+
+The generator checks these files in order:
+
+- `app/assets/stylesheets/application.tailwind.css`
+- `app/assets/stylesheets/application.css`
+- `app/javascript/entrypoints/application.css`
+
+Override the detected file with `STIMULUS_PLUMBERS_CSS_FILE=/path/to/entry.css`. After the initial install, the import stays current automatically — the engine hooks `stimulus_plumbers:install` as a prerequisite of `assets:precompile`.
+
 ## Components
 
 | Component | Helper(s) | Docs |

data/docs/component/button.md

@@ -107,7 +107,7 @@ Icons are rendered **inside** the `<button>`, before or after the label `<span>`
 
 ### Icon only
 
-When no text is provided, no `<span>` is rendered. The theme uses `:has(> span)` to detect this and applies `aspect-square` + `px-0`, making the button square (or a circle for `type: :fab` / `:fab_outline`):
+When no text is provided, no `<span>` is rendered, and the button becomes square (or a circle for `type: :fab` / `:fab_outline`):
 
 ```html
 <button type="button" aria-label="Add" class="[theme classes]">

data/docs/component/calendar.md

@@ -94,10 +94,17 @@ Individual view helpers render a single view (used for Turbo Frame responses). T
 <%= sp_calendar_turbo_decade(date: @date, today: @today) %>
 ```
 
-| Helper                    | Extra option     | Description                                                        |
-| ------------------------- | ---------------- | ------------------------------------------------------------------ |
-| `sp_calendar_turbo_month` | `weekday_format` | `:short` (default) \| `:long` \| `:narrow` — weekday header format |
-| `sp_calendar_turbo_year`  | `month_format`   | `:short` (default) \| `:long` \| `:narrow` — month button format   |
+**`sp_calendar_turbo_month`** — extra option:
+
+| Option           | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `weekday_format` | `:short` (default) \| `:long` \| `:narrow` — weekday header format |
+
+**`sp_calendar_turbo_year`** — extra option:
+
+| Option         | Description                                                      |
+| -------------- | ---------------------------------------------------------------- |
+| `month_format` | `:short` (default) \| `:long` \| `:narrow` — month button format |
 
 **Common options** (all helpers and `sp_calendar_turbo`):
 

data/docs/component/card.md

@@ -63,10 +63,12 @@ Rails helper for rendering a themed card with optional icon, title, body, and ac
   <!-- body -->
   <div class="[card_body theme classes]">Your account is active.</div>
 
-  <!-- action -->
-  <div class="[card_action theme classes]">
-    <a href="/settings">Manage</a>
-  </div>
+  <!-- action: a ghost/tertiary sp_button, with card_action classes merged directly onto it (no wrapping div) -->
+  <a
+    href="/settings"
+    class="[button ghost/tertiary + card_action theme classes]"
+    ><span>Manage</span></a
+  >
 </div>
 ```
 
@@ -74,14 +76,14 @@ Rails helper for rendering a themed card with optional icon, title, body, and ac
 
 ## Theme keys
 
-| Key           | Element                             | Variants                                      |
-| ------------- | ----------------------------------- | --------------------------------------------- |
-| `card`        | Outer `<div>`                       | `variant: :primary\|:secondary\|:tertiary\|…` |
-| `card_header` | Header wrapper `<div>` (icon+title) | —                                             |
-| `card_icon`   | Icon inside the header              | —                                             |
-| `card_title`  | Title element (`h2` etc.)           | —                                             |
-| `card_body`   | Body `<div>`                        | —                                             |
-| `card_action` | Action `<div>`                      | —                                             |
+| Key           | Element                                                       | Variants                                      |
+| ------------- | ------------------------------------------------------------- | --------------------------------------------- |
+| `card`        | Outer `<div>`                                                 | `variant: :primary\|:secondary\|:tertiary\|…` |
+| `card_header` | Header wrapper `<div>` (icon+title)                           | —                                             |
+| `card_icon`   | Icon inside the header                                        | —                                             |
+| `card_title`  | Title element (`h2` etc.)                                     | —                                             |
+| `card_body`   | Body `<div>`                                                  | —                                             |
+| `card_action` | Merged onto the action `<a>`/`<button>` (no wrapping element) | —                                             |
 
 ---
 

data/docs/component/combobox.md

@@ -2,7 +2,7 @@
 
 Rails helpers that render fully-wired combobox components. Each variant shares the same wrapper structure (`input-combobox` + `input-formatter`) and differs only in its popover body.
 
-See [docs/component/combobox.md](../../stimulus-plumbers/docs/component/combobox.md) in the JS package for the underlying controller API.
+See [docs/component/combobox.md](../../../stimulus-plumbers/docs/component/combobox.md) in the JS package for the underlying controller API.
 
 ## Helpers
 
@@ -127,7 +127,7 @@ iOS-style drum/scroll-wheel time picker.
 
 ## Form Builder
 
-`StimulusPlumbers::Form::Builder` exposes combobox-backed fields through purpose-specific methods rather than a single generic helper. See [form_builder.md](form_builder.md) for the full API.
+`StimulusPlumbers::Form::Builder` exposes combobox-backed fields through purpose-specific methods rather than a single generic helper. See [form.md](form.md) for the full API.
 
 ```erb
 <%= form_with model: @user, builder: StimulusPlumbers::Form::Builder do |f| %>

data/docs/component/form.md

@@ -118,9 +118,34 @@ Three methods render a complete, accessible field:
 
 Use `f.time_field` for a plain `<input type="time">`.
 
-**Select** (`as: :select`) — read-only listbox backed by `combobox-dropdown`. Accepts `choices:`, `include_blank:`, `prompt:`, `selected:`. Use `f.select` for a native `<select>`.
+**Select** (`as: :select`) — read-only listbox backed by `combobox-dropdown`.
 
-**Search** (`as: :search`) — editable typeahead backed by `combobox-dropdown`. Accepts `choices:`, `url:`, `clearable:`. Use `f.search_field` for a native `<input type="search">`.
+| Option          | Values         | Default | Description                                                   |
+| --------------- | -------------- | ------- | ------------------------------------------------------------- |
+| `choices`       | Array          | `[]`    | `[label, value]` pairs, or a flat array of strings            |
+| `include_blank` | Boolean/String | `nil`   | Prepends a blank option; String overrides its label           |
+| `prompt`        | Boolean/String | `nil`   | Prepends a disabled placeholder option                        |
+| `selected`      | Value          | `nil`   | Pre-selected value; defaults to the attribute's current value |
+
+Use `f.select` for a native `<select>`.
+
+**Search** (`as: :search`) — editable typeahead backed by `combobox-dropdown`.
+
+| Option      | Values  | Default | Description                                                                         |
+| ----------- | ------- | ------- | ----------------------------------------------------------------------------------- |
+| `choices`   | Array   | `[]`    | Client-side options to filter; omit when using `url:`                               |
+| `url`       | String  | `nil`   | Server-side endpoint, receives `?q=<query>`, returns `<li role="option">` fragments |
+| `clearable` | Boolean | `false` | Adds a clear button that resets the input                                           |
+
+Use `f.search_field` for a native `<input type="search">`.
+
+**Password** (`as: :password`) — reveal-toggle wrapper backed by `input-formatter`.
+
+| Option       | Values  | Default | Description                                 |
+| ------------ | ------- | ------- | ------------------------------------------- |
+| `revealable` | Boolean | `false` | Adds a show/hide toggle button on the input |
+
+Use `f.password_field` for a plain `<input type="password">` (also accepts `revealable:`).
 
 ---
 
@@ -169,9 +194,9 @@ Renders a `<fieldset>` / `<legend>` for accessible grouping, or a single checkbo
 
 **Card / button behaviour:**
 
-- **Checkbox card** — input visible on right; card border changes on check via `has-[:checked]:`
-- **Radio card** — input hidden (`hidden peer`); entire card is the clickable area via `peer-checked:`
-- **Radio button** — input hidden (`hidden peer`); inline pill style via `peer-checked:`
+- **Checkbox card** — input visible on the right; the card border highlights when checked
+- **Radio card** — input visually hidden; the whole card is the clickable target and highlights when selected
+- **Radio button** — input visually hidden; renders as an inline pill that highlights when selected
 
 ---
 
@@ -185,7 +210,8 @@ Renders a `<fieldset>` / `<legend>` for accessible grouping, or a single checkbo
   <input
     id="user_email"
     type="email"
-    aria-describedby="user_email_hint"
+    aria-describedby="user_email_hint user_email_error"
+    aria-invalid="true"
     required
     aria-required="true"
   />

data/docs/component/list.md

@@ -39,7 +39,7 @@ Rails helper for rendering an accessible list of links, buttons, or grouped sect
 | `role:`          | `"list"` | ARIA role on the `<ul>` — use `"menu"` for interactive menus                             |
 | `**html_options` | —        | Forwarded to the `<ul>`                                                                  |
 
-### `list.section(title:, description:, **html_options)`
+### `list.section(title:, description:, **html_options, &block)`
 
 Renders a `<li>` with an optional heading/description and a nested `<ul>`.
 
@@ -60,7 +60,7 @@ Renders a `<li>` containing an `<a>` (when `url:` present) or `<button>`.
 | `target:`        | `nil`   | Forwarded to the `<a>` (e.g. `"_blank"`)                            |
 | `**html_options` | —       | Forwarded to the inner `<a>` or `<button>`                          |
 
-When `target: "_blank"` is set, `icon_trailing: "external-link"` is added automatically.
+When `url:` is present and `target: "_blank"` is set, `icon_trailing: "external-link"` is added automatically.
 
 ### Item slot methods (yielded as `item`)
 

data/docs/component/plumber.md

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

data/docs/component/theme.md

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

data/docs/component/timeline.md

@@ -132,7 +132,7 @@ Rails helper for rendering a themed timeline as an ordered list with optional in
 
 ## ARIA
 
-- See [ARIA.md](../../ARIA.md) for WCAG 2.1 AA criteria and disclosure widget patterns.
+- See [ARIA.md](../../../ARIA.md) for WCAG 2.1 AA criteria and disclosure widget patterns.
 - The trigger button uses `aria-expanded` (managed by the JS controller) and `aria-controls` pointing to the detail `id`.
 - Indicator elements carry `aria-hidden="true"` to hide decorative markup from screen readers.
-- For JS controller targets, values, and actions, see the [stimulus-plumbers JS controller doc](../../stimulus-plumbers/docs/component/timeline.md).
+- For JS controller targets, values, and actions, see the [stimulus-plumbers JS controller doc](../../../stimulus-plumbers/docs/component/timeline.md).

data/docs/guide.md

@@ -0,0 +1,27 @@
+# Guide
+
+## Building forms
+
+Use `StimulusPlumbers::Form::Builder` (set `config.action_view.default_form_builder`, or pass
+`builder:` to `form_with`). Two levels:
+
+- **Level 2 — recommended.** Full accessible field (label + input + hint + error):
+  `f.field(attr, as:)`, `f.collection_field(attr, as:, collection:, ...)`, `f.choice(attr, as:)`.
+  See [docs/component/form.md](component/form.md) for valid `as:` values per builder method and
+  which ones are backed by a Stimulus controller (date/time/select/search pickers).
+- **Level 1.** Native helper overrides (`f.text_field`, `f.select`, `f.check_box`, ...) render
+  only the themed input element — use when you control the surrounding markup.
+
+Submit with `f.submit` (themed button).
+
+## Building views
+
+Render components with `sp_*` helpers (`sp_button`, `sp_button_group`, `sp_card`, `sp_list`,
+`sp_link`, `sp_avatar`, `sp_divider`, `sp_icon`, `sp_popover`, ...) — see the
+[Components table](../README.md#components) for the full helper list, and each component's
+`docs/component/<name>.md` for its keyword options, slots, and themed params.
+
+## Stimulus integration
+
+Most display components are pure markup; interactive ones (combobox, popover, calendar) emit their
+`data-controller` attributes automatically — no manual wiring needed in Rails views.

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "stimulus_plumbers/generators/css_entrypoint"
+require "stimulus_plumbers/generators/tokens_directive"
+
+module StimulusPlumbers
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include StimulusPlumbers::Generators::CssEntrypoint
+
+      STIMULUS_PLUMBERS_CSS_FILE = CssEntrypoint::STIMULUS_PLUMBERS_CSS_FILE
+      CSS_CANDIDATES             = %w[
+        app/assets/stylesheets/application.tailwind.css
+        app/assets/stylesheets/application.css
+        app/javascript/entrypoints/application.css
+      ].freeze
+
+      def install
+        css_file = entry_css_file(candidates: CSS_CANDIDATES, env_var: STIMULUS_PLUMBERS_CSS_FILE)
+        unless css_file
+          return warn_entry_css_not_found(candidates: CSS_CANDIDATES, env_var: STIMULUS_PLUMBERS_CSS_FILE, label: "CSS")
+        end
+
+        apply_edit(css_file, TokensDirective.directive, stale_pattern: TokensDirective.stale_pattern)
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/button.rb

@@ -4,7 +4,7 @@ module StimulusPlumbers
   module Components
     class Button < Plumber::Base
       def render(content = nil, icon_leading: nil, icon_trailing: nil, **kwargs, &block)
-        slots = Button::Slots.new
+        slots = Button::Slots.new(template)
         slots.with_icon_leading(icon_leading) if icon_leading
         slots.with_icon_trailing(icon_trailing) if icon_trailing
 

data/lib/stimulus_plumbers/components/card.rb

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

data/lib/stimulus_plumbers/components/combobox.rb

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

data/lib/stimulus_plumbers/components/link.rb

@@ -6,7 +6,7 @@ module StimulusPlumbers
       def render(content = nil, url:, icon_leading: nil, icon_trailing: nil, **kwargs, &block)
         icon_trailing ||= "external-link" if kwargs[:target] == "_blank"
 
-        slots = Link::Slots.new
+        slots = Link::Slots.new(template)
         slots.with_icon_leading(icon_leading) if icon_leading
         slots.with_icon_trailing(icon_trailing) if icon_trailing
 

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

@@ -5,7 +5,7 @@ module StimulusPlumbers
     class List
       class Item < Plumber::Base
         def render(content = nil, **kwargs, &block)
-          slots = List::Item::Slots.new
+          slots = List::Item::Slots.new(template)
           slots.with_title(content) if content
           slots.with_icon_trailing("external-link") if kwargs[:url].present? && kwargs[:target] == "_blank"
           yield slots if block_given?

data/lib/stimulus_plumbers/components/timeline/event.rb

@@ -13,7 +13,7 @@ module StimulusPlumbers
         def render(datetime: nil, id: nil, interactive: false, orientation: :vertical, **kwargs, &block)
           @detail_id = self.class.detail_id_for(id || template.sp_dom_id)
 
-          slots = Timeline::Event::Slots.new
+          slots = Timeline::Event::Slots.new(template)
           yield slots if block_given?
 
           validate_slots!(slots, datetime: datetime)

data/lib/stimulus_plumbers/engine.rb

@@ -18,5 +18,9 @@ module StimulusPlumbers
         include StimulusPlumbers::Helpers
       end
     end
+
+    rake_tasks do
+      load File.join(__dir__, "../tasks/stimulus_plumbers.rake")
+    end
   end
 end

data/lib/stimulus_plumbers/generators/css_entrypoint.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Generators
+    module CssEntrypoint
+      STIMULUS_PLUMBERS_CSS_FILE = "STIMULUS_PLUMBERS_CSS_FILE"
+
+      def entry_css_file(candidates:, env_var:, fallback_env_var: nil)
+        [env_var, fallback_env_var].compact.each do |var|
+          next unless ENV[var]
+
+          path = File.expand_path(ENV.fetch(var, nil))
+          return path if File.exist?(path)
+        end
+
+        candidates
+          .map { |c| File.join(destination_root, c) }
+          .find { |f| File.exist?(f) }
+      end
+
+      def warn_entry_css_not_found(candidates:, env_var:, label:, fallback_env_var: nil)
+        tried = candidates.map { |c| File.join(destination_root, c) }
+        [env_var, fallback_env_var].compact.each do |var|
+          tried.unshift(File.expand_path(ENV[var])) if ENV[var]
+        end
+        say "Could not find a #{label} entry file. Tried: #{tried.join(", ")}. " \
+            "Set #{env_var}=/path/to/entry.css and re-run.",
+            :red
+      end
+
+      def apply_edit(css_file, directive, stale_pattern:, anchor_pattern: nil)
+        content              = File.read(css_file)
+        new_content, status  = content_edit(content, directive, stale_pattern: stale_pattern, anchor_pattern: anchor_pattern)
+
+        if new_content
+          File.write(css_file, new_content)
+          say_status status, relative_to_destination(css_file), :green
+        else
+          say_status :identical, relative_to_destination(css_file)
+        end
+      rescue Errno::EROFS, Errno::EACCES => e
+        say "Could not update #{relative_to_destination(css_file)}: #{e.message}. Skipping.", :yellow
+      end
+
+      # `stale_pattern:` is required — every call site needs stale-import detection,
+      # so making it optional would leave an untested "anchor without stale" state.
+      def content_edit(content, directive, stale_pattern:, anchor_pattern: nil)
+        return nil if content.include?(directive)
+
+        if (existing = content.match(stale_pattern))
+          return [content.sub(existing[0], directive), :update]
+        end
+
+        anchor_pattern ? insert_near_anchor(content, directive, anchor_pattern) : prepend(content, directive)
+      end
+
+      def prepend(content, directive)
+        ["#{directive}\n#{content}", :prepend]
+      end
+
+      def insert_near_anchor(content, directive, anchor_pattern)
+        if (anchor = content.match(anchor_pattern))
+          [content.sub(anchor[0], "#{anchor[0]}\n#{directive}"), :insert]
+        else
+          ["#{content.rstrip}\n#{directive}\n", :append]
+        end
+      end
+
+      def relative_to_destination(path)
+        path.delete_prefix("#{destination_root}/")
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/generators/tokens_directive.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Generators
+    module TokensDirective
+      GEM_ROOT            = File.expand_path("../../..", __dir__)
+      TOKENS_CSS_REL_PATH = "app/assets/stylesheets/stimulus_plumbers/tokens.css"
+
+      module_function
+
+      def directive
+        %(@import "#{GEM_ROOT}/#{TOKENS_CSS_REL_PATH}";)
+      end
+
+      def stale_pattern
+        %r{@import "[^"]*#{Regexp.escape(TOKENS_CSS_REL_PATH)}";}
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/plumber/slots.rb

@@ -11,8 +11,9 @@ module StimulusPlumbers
         end
       end
 
-      def initialize
+      def initialize(template = nil)
         @slots = {}
+        @template = template
       end
 
       def resolve(name)
@@ -20,7 +21,7 @@ module StimulusPlumbers
         return unless entry
 
         value = entry[:value]
-        value = value.call if value.is_a?(Proc)
+        value = capture_block(value) if value.is_a?(Proc)
         block_given? ? yield(value) : value
       end
 
@@ -38,6 +39,12 @@ module StimulusPlumbers
 
       private
 
+      # Runs the slot block through the view so its ERB output is returned,
+      # not written to whatever buffer happens to be active.
+      def capture_block(block)
+        @template ? @template.capture(&block) : block.call
+      end
+
       def set_slot(name, value, options = {})
         @slots[name] = { value: value, options: options }
       end
@@ -54,7 +61,7 @@ module StimulusPlumbers
 
         def define_by_slot(name, by)
           define_method(:"with_#{name}") do |&block|
-            sub = by.new
+            sub = by.new(@template)
             block&.call(sub)
             set_slot(name, sub)
             nil

data/lib/stimulus_plumbers/version.rb

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

data/lib/tasks/stimulus_plumbers.rake

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+namespace :stimulus_plumbers do
+  desc "Add the tokens.css @import into the CSS entry file"
+  task(:install) do
+    unless ENV["STIMULUS_PLUMBERS_SKIP_INSTALL"]
+      require "generators/stimulus_plumbers/install/install_generator"
+      StimulusPlumbers::Generators::InstallGenerator.new(
+        [], {}, { destination_root: Rails.root.to_s }
+      ).invoke_all
+    end
+  end
+end
+
+Rake::Task["stimulus_plumbers:install"].enhance(["environment"]) unless ENV["STIMULUS_PLUMBERS_SKIP_INSTALL"]
+
+# Hooks into "assets:precompile" as a prerequisite; Rake merges rather than overwrites, so order-independent.
+task "assets:precompile" => ["stimulus_plumbers:install"]