stimulus_plumbers 0.4.4 → 0.4.8

data/docs/component/theme.md

@@ -0,0 +1,201 @@
+# Theming
+
+Stimulus Plumbers uses a theme system to apply presentational CSS classes to form fields and components. The default theme is Tailwind CSS. Custom themes can be created by subclassing `Themes::Base`.
+
+## 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(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.
+
+### Form fields
+
+| Key                              | Component                                                  | Variants                                                    |
+| -------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------- |
+| `form_group`                     | `Fields::Group` (wrapper div)                              | `layout: :stacked\|:inline`, `error: bool`                  |
+| `form_field_label`               | `Fields::Label`, `Fields::Fieldset` (`<legend>`)           | `required: bool`, `hidden: bool`                            |
+| `form_field_required_mark`       | Required `*` span in label/legend                          | —                                                           |
+| `form_field_hint`                | `Fields::Hint`                                             | —                                                           |
+| `form_field_error`               | `Fields::Error`                                            | —                                                           |
+| `form_field_choice_items`        | Collection wrapper (the items container inside a fieldset) | `layout: :stacked\|:inline`                                 |
+| `form_field_checkbox_label`      | `<label>` wrapping each checkbox in a collection           | `type: :default\|:button\|:card`, `variant:`                |
+| `form_field_radio_label`         | `<label>` for each radio button in a collection            | `type: :default\|:button\|:card`, `variant:`                |
+| `form_field_input`               | Text-like `<input>` (text, email, number, url, tel, …)     | `error: bool`                                               |
+| `form_field_floating`            | `<input>` inside a floating-label field                    | `type: :filled\|:outlined\|:standard`, `error: bool`        |
+| `form_field_floating_group`      | Wrapper `<div>` that groups floating input + label         | `type: :filled\|:outlined\|:standard`                       |
+| `form_field_floating_label`      | Animated `<label>` that floats above the input             | `type: :filled\|:outlined\|:standard`, `error: bool`        |
+| `form_field_input_textarea`      | `<textarea>`                                               | `error: bool`                                               |
+| `form_field_input_file`          | `<input type="file">`                                      | `error: bool`                                               |
+| `form_field_input_select`        | Native `<select>`                                          | `error: bool`                                               |
+| `form_field_input_checkbox`      | `<input type="checkbox">` element in a collection          | `type: :default\|:button\|:card`, `variant:`, `error: bool` |
+| `form_field_input_radio`         | `<input type="radio">` element in a collection             | `type: :default\|:button\|:card`, `variant:`, `error: bool` |
+| `form_field_input_combobox`      | Combobox wrapper input (resets child input/trigger styles) | `error: bool`                                               |
+| `form_field_input_reveal`        | Password reveal wrapper (resets child input styles)        | `error: bool`                                               |
+| `form_field_input_clearable`     | Clearable wrapper (resets child input styles)              | —                                                           |
+| `form_field_input_button_reveal` | Show/hide toggle button inside a password field            | —                                                           |
+| `form_field_input_button_clear`  | Clear button inside a search/clearable field               | —                                                           |
+| `form_submit`                    | Submit button (`Builder#submit`)                           | `type: :link\|:default\|…`, `variant:`                      |
+| `input_group`                    | `Fields::InputGroup` (input + adornment wrapper)           | `error: bool`                                               |
+
+### Calendar
+
+| Key                        | Component                                               | Variants        |
+| -------------------------- | ------------------------------------------------------- | --------------- |
+| `calendar`                 | `Calendar`, `Calendar::Turbo`                           | —               |
+| `calendar_days_of_week`    | `Calendar::Turbo::DaysOfWeek`                           | —               |
+| `calendar_days_of_month`   | `Calendar::Turbo::DaysOfMonth`                          | —               |
+| `calendar_row`             | `Calendar::Turbo::DaysOfMonth` (each week row)          | —               |
+| `calendar_day`             | `Calendar::Turbo::DaysOfMonth` (each day cell)          | `outside: bool` |
+| `calendar_months_of_year`  | `Calendar::Turbo::MonthsOfYear` (rowgroup wrapper)      | —               |
+| `calendar_month`           | `Calendar::Turbo::MonthsOfYear` (each month cell)       | —               |
+| `calendar_years_of_decade` | `Calendar::Turbo::YearsOfDecade` (rowgroup wrapper)     | —               |
+| `calendar_year`            | `Calendar::Turbo::YearsOfDecade` (each year cell)       | —               |
+| `calendar_quarter_grid`    | `Calendar::Turbo` year/decade grid wrapper (4-col grid) | —               |
+
+### Combobox
+
+| Key                                  | Component                                                                        | Variants                           |
+| ------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------- |
+| `combobox_listbox`                   | `Combobox::Dropdown`, `Combobox::Typeahead`, `Combobox::Time::Drum` (the `<ul>`) | —                                  |
+| `combobox_option`                    | `Combobox::Options::Option`                                                      | `selected: bool`, `disabled: bool` |
+| `combobox_option_group`              | `Combobox::Options::OptionGroup`                                                 | —                                  |
+| `combobox_typeahead_loading`         | `Combobox::Typeahead` (loading indicator)                                        | —                                  |
+| `combobox_typeahead_empty`           | `Combobox::Typeahead` (no-results message)                                       | —                                  |
+| `combobox_time`                      | `Combobox::Time` (drum wrapper)                                                  | —                                  |
+| `combobox_date_navigation`           | `Combobox::Date::Navigation` (nav bar)                                           | —                                  |
+| `combobox_date_navigation_navigator` | `Combobox::Date::Navigator` (each prev/next/title button)                        | —                                  |
+
+### Other components
+
+| Key                        | Component                                                       | Variants                                                                                                                                                                                     |
+| -------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `button`                   | `Button`                                                        | `type: :default\|:outline\|:ghost\|:fab\|:fab_outline\|:dashed\|:card`, `variant: :primary\|:secondary\|:tertiary\|:success\|:destructive\|:warning\|:info`, `size: :xs\|:sm\|:md\|:lg\|:xl` |
+| `button_group`             | `Button::Group`                                                 | `layout: :inline\|:stacked`                                                                                                                                                                  |
+| `button_icon`              | `Button` (icon rendered via `icon_leading:` / `icon_trailing:`) | —                                                                                                                                                                                            |
+| `link`                     | `Link`                                                          | `type: :default\|:button\|:card`, `variant: :default\|:success\|:destructive\|:warning\|:info`                                                                                               |
+| `link_icon`                | `Link` (icon rendered via `icon_leading:` / `icon_trailing:`)   | —                                                                                                                                                                                            |
+| `list`                     | `List` outer `<ul>`                                             | —                                                                                                                                                                                            |
+| `list_section`             | `List::Section` wrapper `<li>`                                  | —                                                                                                                                                                                            |
+| `list_section_title`       | Section title `<span>` or `<h{n}>`                              | —                                                                                                                                                                                            |
+| `list_section_description` | Section description `<span>`                                    | —                                                                                                                                                                                            |
+| `list_item`                | `List::Item` — applied to inner `<a>` or `<button>`             | —                                                                                                                                                                                            |
+| `list_item_icon`           | Leading and trailing icons inside a list item                   | —                                                                                                                                                                                            |
+| `list_item_content`        | Content wrapper `<span>` (title + description)                  | —                                                                                                                                                                                            |
+| `list_item_title`          | Title `<span>` inside a list item                               | —                                                                                                                                                                                            |
+| `list_item_description`    | Description `<span>` inside a list item                         | —                                                                                                                                                                                            |
+| `avatar`                   | `Avatar`                                                        | `size:`                                                                                                                                                                                      |
+| `card`                     | `Card` outer `<div>`                                            | `variant: :primary\|:secondary\|:tertiary\|…`                                                                                                                                                |
+| `card_header`              | Card header wrapper `<div>` (icon + title)                      | —                                                                                                                                                                                            |
+| `card_icon`                | Icon inside the card header                                     | —                                                                                                                                                                                            |
+| `card_title`               | Card title element (`h2` etc.)                                  | —                                                                                                                                                                                            |
+| `card_body`                | Card body `<div>`                                               | —                                                                                                                                                                                            |
+| `card_action`              | Card action `<div>`                                             | —                                                                                                                                                                                            |
+| `icon`                     | `Icon`                                                          | —                                                                                                                                                                                            |
+| `popover`                  | `Popover`                                                       | —                                                                                                                                                                                            |
+
+## Custom theme
+
+Subclass `Themes::Base` and implement private `*_classes` methods for the keys you want to override. Return `{ classes: "…" }`.
+
+```ruby
+class MyTheme < StimulusPlumbers::Themes::Base
+  private
+
+  def form_label_classes(hidden: false, **)
+    { classes: hidden ? "sr-only label" : "label" }
+  end
+
+  def form_group_classes(layout: :stacked, **)
+    { classes: layout == :inline ? "field-row" : "field" }
+  end
+end
+
+StimulusPlumbers.configure do |c|
+  c.theme.register(:my_theme, MyTheme)
+  c.theme.use(:my_theme)
+end
+```
+
+### Providing icons
+
+Override `icons` to supply icons to the `Icon` component. The return value must respond to `[]` and `key?`:
+
+```ruby
+class MyTheme < StimulusPlumbers::Themes::Base
+  def icons
+    @icons ||= {
+      "check" => {
+        elements: [{ tag: :path, d: "M5 13l4 4L19 7", stroke_linecap: :round, stroke_linejoin: :round }]
+      }
+    }
+  end
+end
+```
+
+Each icon is a hash with optional SVG-level keys (`fill:`, `stroke:`, `view_box:`, `stroke_width:`, `width:`, `height:`) and a required `elements:` array. Each element needs a `tag:` (`:path`, `:circle`, `:rect`, etc.) and its attributes (`d:`, `fill:`, `opacity:`, `stroke_linecap:`, etc.). Unknown keys are ignored; missing SVG keys fall back to defaults (`fill: "none"`, `stroke: "currentColor"`, `view_box: "0 0 24 24"`, `stroke_width: 1.5`).
+
+If `icons[name]` returns `nil`, `Icon` renders an empty `<span>` fallback.
+
+#### File-based icon sources
+
+For SVG-file-backed icon sources, the core gem provides two utilities in `StimulusPlumbers::Themes::Icons`:
+
+**`Icons::External`** — a module that parses SVG files into icon hashes. Include it into any module that implements `svg_path(key)`:
+
+```ruby
+module MyIcons
+  include StimulusPlumbers::Themes::Icons::External
+  extend self
+
+  private
+
+  def svg_path(key)
+    File.expand_path("#{key}.svg", __dir__)
+  end
+end
+```
+
+`External` exposes `include?(key)` and `fetch(key)`, where `fetch` returns the parsed icon hash or `nil` if the file doesn't exist. Override `svg_defaults(key)` to inject source-specific SVG attribute defaults.
+
+**`Icons::Registry`** — a lazy-loading `SimpleDelegator` wrapping a `Hash`. Results are memoized on first access. Takes `sources:` (array of icon source modules) and optional `aliases:`:
+
+```ruby
+ICONS = StimulusPlumbers::Themes::Icons::Registry.new(
+  sources: [MyIcons],
+  aliases: { "close" => "x-mark" }
+)
+```
+
+Sources are tried in order; the first non-nil result wins. Aliases are resolved before querying sources, so `icons["close"]` fetches `"x-mark"` from the sources.
+
+### Schema validators
+
+When defining a custom schema (advanced), the `validate:` key accepts:
+
+| Type          | Behaviour                                                                        |
+| ------------- | -------------------------------------------------------------------------------- |
+| Array / Range | Value must be `include?`-d                                                       |
+| Symbol        | Method called on the theme; return must respond to `include?` or be truthy/falsy |
+| Proc          | Called via `instance_exec`; same return conventions                              |
+| `nil`         | No validation — any value accepted                                               |

data/docs/component/timeline.md

@@ -0,0 +1,138 @@
+# Timeline
+
+Rails helper for rendering a themed timeline as an ordered list with optional interactive (expandable) events.
+
+## Helper
+
+### `sp_timeline`
+
+```erb
+<%# Static — server-rendered date text %>
+<%= sp_timeline do |t| %>
+  <% t.event(datetime: "2024-01-15") do |e| %>
+    <% e.with_indicator %>
+    <% e.with_time { "January 2024" } %>
+    <% e.with_title { "Event title" } %>
+    <% e.with_description { "Brief text" } %>
+    <% e.with_actions { sp_link("Read more", url: "/") } %>
+  <% end %>
+<% end %>
+
+<%# Interactive (expandable) — client-formatted date %>
+<%= sp_timeline(interactive: true,
+                data: { "timeline-date-format-value": { month: "long", year: "numeric", day: "numeric" }.to_json }) do |t| %>
+  <% t.event(id: "event-1", datetime: "2024-01-15") do |e| %>
+    <% e.with_indicator %>
+    <% e.with_trigger { "Event title" } %>
+    <% e.with_description { "Brief text" } %>
+    <% e.with_detail { "Expanded content" } %>
+    <% e.with_actions { sp_link("Read more", url: "/") } %>
+  <% end %>
+<% end %>
+```
+
+| Option           | Default     | Description                                                                                                  |
+| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
+| `orientation:`   | `:vertical` | Layout direction — `:vertical` \| `:horizontal`. Passed to theme as `theme.resolve(:timeline, orientation:)` |
+| `interactive:`   | `false`     | Adds `data-controller="timeline"` to `<ol>`                                                                  |
+| `**html_options` | —           | Forwarded to the outer `<ol>`                                                                                |
+
+### `t.event` options
+
+| Option           | Default | Description                                                      |
+| ---------------- | ------- | ---------------------------------------------------------------- |
+| `datetime:`      | `nil`   | Renders `<time datetime="...">` — required when `e.time {}` used |
+| `id:`            | `nil`   | Stable base ID; derives detail element id via `detail_id_for`    |
+| `**html_options` | —       | Forwarded to the `<li>`                                          |
+
+### Event slot methods (yielded as `e`)
+
+| Slot method                      | Description                                                                                             |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `e.with_indicator`               | Dot indicator `<div aria-hidden="true">`                                                                |
+| `e.with_indicator(icon: "name")` | Icon indicator — renders `Icon` component inside the wrapper                                            |
+| `e.with_time { text }`           | Text content for `<time>`; requires `datetime:` on `t.event`                                            |
+| `e.with_title { text }`          | Static `<h3>` — mutually exclusive with `e.with_trigger`                                                |
+| `e.with_trigger { text }`        | `<h3><button>` — mutually exclusive with `e.with_title`; button has `aria-expanded` and `aria-controls` |
+| `e.with_description { text }`    | `<p>` element                                                                                           |
+| `e.with_detail { text }`         | Collapsible `<div hidden>` — requires `e.with_trigger`; id linked to trigger's `aria-controls`          |
+| `e.with_actions { content }`     | Actions wrapper `<div>` — suppressed when block yields nil/empty                                        |
+
+**Constraints:**
+
+- `e.with_title` and `e.with_trigger` are mutually exclusive — raises `ArgumentError` if both set.
+- `e.with_detail` requires `e.with_trigger` — raises `ArgumentError` otherwise.
+- `e.with_time` requires `datetime:` on `t.event` — raises `ArgumentError` otherwise.
+
+---
+
+## Rendered HTML Structure
+
+### Static
+
+```html
+<ol>
+  <li>
+    <div aria-hidden="true"></div>
+    <!-- indicator dot -->
+    <time datetime="2024-01-15">January 2024</time>
+    <h3>Event title</h3>
+    <p>Brief text</p>
+    <div><!-- actions --></div>
+  </li>
+</ol>
+```
+
+### Interactive
+
+```html
+<ol data-controller="timeline">
+  <li>
+    <div aria-hidden="true"></div>
+    <time datetime="2024-01-15"></time>
+    <!-- filled by JS dateFormatValue -->
+    <h3>
+      <button
+        type="button"
+        aria-expanded="false"
+        aria-controls="event-1_detail"
+        data-timeline-target="trigger"
+        data-action="timeline#toggle"
+      >
+        Event title
+      </button>
+    </h3>
+    <p>Brief text</p>
+    <div id="event-1_detail" hidden data-timeline-target="detail">
+      Expanded content
+    </div>
+    <div><!-- actions --></div>
+  </li>
+</ol>
+```
+
+---
+
+## Theme keys
+
+| Key                         | Element                            | Variants              |
+| --------------------------- | ---------------------------------- | --------------------- |
+| `timeline`                  | Outer `<ol>`                       | `orientation:`        |
+| `timeline_item`             | `<li>`                             | `orientation:`        |
+| `timeline_item_indicator`   | Indicator `<div>`                  | `type: :dot \| :icon` |
+| `timeline_item_time`        | `<time>`                           | —                     |
+| `timeline_item_title`       | Static `<h3>`                      | —                     |
+| `timeline_item_heading`     | `<h3>` wrapping the trigger button | —                     |
+| `timeline_item_trigger`     | `<button>` inside the heading      | —                     |
+| `timeline_item_description` | `<p>`                              | —                     |
+| `timeline_item_detail`      | Collapsible `<div>`                | —                     |
+| `timeline_item_actions`     | Actions `<div>`                    | —                     |
+
+---
+
+## ARIA
+
+- 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).

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.4"
+  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"]