stimulus_plumbers_tailwind 0.4.5 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff605a8bd2767e0f3eff46c53f3e644041ace037687a66042b3d2eb6bf3cf7f8
-  data.tar.gz: 9cc8d80f88fb2ddc41c8dbd2e7a5cc9507a48987211501abf457f0318e4fb2e2
+  metadata.gz: e7a0a4078d4282a62d21ebdb421fd18c446fe69031dac6ed8f9be663c91957d2
+  data.tar.gz: 234ae70da55a34c9be1c655fa40c5d7e9536d6c99c7a75f5f5724df662fc63d8
 SHA512:
-  metadata.gz: 8d74cf1b92f2ef08e823e60415b83ef8f737bfac9bfac2203d52e0383c9152958150137cdd52c23ca9c08d3fdea58282b88e135f8bfff962c2f187e4c6137cdb
-  data.tar.gz: 48b048561bfe8ea18473122b340ce3a801dc9fb08b316c851b9d72d0b1460b580247e705fd0c272aed2f0f7196281d50162fbe4c40de4b5ae256bfe37f800f5a
+  metadata.gz: c608f0a0f0513903e3f6224c8750935deee7ccf736791eee048a54dcb421a5a345c7efec685046bd2027a75756ce2b3e3801fdffdc570f71aca9c05e3e86e92a
+  data.tar.gz: c1db6f8eb3034534ed893ada8507866529bfe654fd059fb26f22d17ee49951fbd7b4b218f5f121eb47ad4959cdda40185bc3b560b1aa2f80fb1c806d6877a154

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file. See [conventional commits](https://www.conventionalcommits.org/) for commit guidelines.
 
+---
+## [0.4.8](https://github.com/ryancyq/stimulus-plumbers/compare/stimulus-plumbers-tailwind/v0.4.5..stimulus-plumbers-tailwind/v0.4.8) - 2026-07-03
+
+### Bug Fixes
+
+- tailwind install generator ([#154](https://github.com/ryancyq/stimulus-plumbers/issues/154)) - ([db4bda0](https://github.com/ryancyq/stimulus-plumbers/commit/db4bda0b899a463e0608229927c65326233dd3a4)) - Ryan Chang
+- tailwind theme registration + activation (rails only) ([#157](https://github.com/ryancyq/stimulus-plumbers/issues/157)) - ([5998854](https://github.com/ryancyq/stimulus-plumbers/commit/5998854ed2a6ca9c67aa225f3c397e4f7bca7a51)) - Ryan Chang
+- mcp doc update + new tools validations ([#162](https://github.com/ryancyq/stimulus-plumbers/issues/162)) - ([beed1bb](https://github.com/ryancyq/stimulus-plumbers/commit/beed1bb14cbfcb8ec6f757145dc6a461d357c060)) - Ryan Chang
+
 ---
 ## [0.4.4](https://github.com/ryancyq/stimulus-plumbers/compare/stimulus-plumbers-tailwind/v0.4.3..stimulus-plumbers-tailwind/v0.4.4) - 2026-06-30
 

data/README.md

@@ -6,10 +6,12 @@
 
 Tailwind CSS v4 theme for [`stimulus_plumbers`](../stimulus-plumbers-rails). Extends the base theme with utility classes for all components.
 
+See [docs/guide.md](docs/guide.md) for a quick setup/theming guide.
+
 ## Requirements
 
 - Ruby >= 3.0
-- `stimulus_plumbers` >= 0.2.9
+- `stimulus_plumbers` >= 0.3.1
 - Tailwind CSS v4 in your build toolchain
 
 ## Installation
@@ -23,7 +25,7 @@ gem "stimulus_plumbers_tailwind"
 bundle install
 ```
 
-Activate the theme in an initializer or `config/application.rb`:
+In a Rails app, the theme registers and activates automatically — no config needed. Outside Rails, it only registers; activate it explicitly:
 
 ```ruby
 StimulusPlumbers.configure do |config|
@@ -31,21 +33,13 @@ StimulusPlumbers.configure do |config|
 end
 ```
 
-Run the install generator once to inject the required `@source` directive into your Tailwind CSS entry file:
+Run the install generator once to inject the required `@source` directive (and the `stimulus_plumbers` tokens.css + `animations.css` imports) into your Tailwind CSS entry file — see [docs/guide.md](docs/guide.md) for file-detection/override details:
 
 ```bash
-bin/rails generate stimulus_plumbers_tailwind:install
+bin/rails generate stimulus_plumbers:tailwind: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 for both the generator and rake task with `TAILWIND_CSS_FILE=/path/to/entry.css`.
-
-After the initial install, the `@source` path is kept current automatically — no manual re-run needed after `bundle update`. The engine hooks `stimulus_plumbers_tailwind:install` as a prerequisite of:
+After that, the `@source` path is kept current automatically — no manual re-run needed after `bundle update`. The engine hooks `stimulus_plumbers:tailwind:install` as a prerequisite of:
 
 - `assets:precompile` (Sprockets and Propshaft both define this task)
 - `tailwindcss:build` (when `tailwindcss-rails` is present)
@@ -53,7 +47,7 @@ After the initial install, the `@source` path is kept current automatically —
 To trigger an update manually without a full compile (useful for debugging or after `bundle update`):
 
 ```bash
-bin/rails stimulus_plumbers_tailwind:install
+bin/rails stimulus_plumbers:tailwind:install
 ```
 
 ## Theming
@@ -69,9 +63,12 @@ bin/rails stimulus_plumbers_tailwind:install
 | `Tailwind::Combobox` | Combobox (date, time, dropdown, typeahead) |
 | `Tailwind::Form` | Form fields, labels, errors |
 | `Tailwind::Icon` | Icon (SVG rendering, icon registry) |
+| `Tailwind::Indicator` | Indicator (dot, pulse, badge) |
 | `Tailwind::Layout` | Layout primitives |
 | `Tailwind::Link` | Link |
 | `Tailwind::List` | List |
+| `Tailwind::OrderedList` | Reorderable list (drag handle, item styling) |
+| `Tailwind::Progress` | Progress bar, progress ring, meter |
 | `Tailwind::Timeline` | Timeline |
 
 Custom themes can subclass `TailwindTheme` to override individual methods, or subclass `StimulusPlumbers::Themes::Base` directly.
@@ -92,7 +89,7 @@ Icons render as inline `<svg>` with `size-6` by default. Override with `class:`:
 <%= sp_icon "arrow-left", class: "size-4 text-gray-500" %>
 ```
 
-**Built-in aliases:** `"close"` → `"x-mark"`, `"calendar"` → `"calendar-days"`.
+**Built-in aliases:** `"close"` → `"x-mark"`, `"download"` → `"arrow-down-tray"`, `"book"` → `"book-open"`, `"edit"` → `"pencil"`, `"email"` → `"envelope"`, `"calendar"` → `"calendar-days"`, `"external-link"` → `"arrow-top-right-on-square"`, `"reveal"` → `"eye"`, `"grip-vertical"` → `"bars-3"`.
 
 **Optional `heroicons` gem:** add `gem "heroicons"` to your `Gemfile` to load icons from the gem instead of the bundled files. The theme detects it automatically.
 

data/app/assets/stylesheets/stimulus_plumbers/tailwind/animations.css

@@ -0,0 +1,18 @@
+@theme {
+  --animate-progress-slide: sp-progress-slide 1.5s ease-in-out infinite;
+}
+
+@keyframes sp-progress-slide {
+  0%   { transform: translateX(-100%); }
+  100% { transform: translateX(300%); }
+}
+
+/* Ring-only; core's transition covers width, not stroke-dashoffset. */
+[data-progress-target="fill"] {
+  transition: stroke-dashoffset 0.3s ease;
+}
+
+/* Track color — kept out of the SVG so consumers can retheme it via CSS. */
+svg[role="progressbar"] .track {
+  stroke: var(--sp-color-muted);
+}

data/docs/architecture.md

@@ -0,0 +1,50 @@
+# Tailwind Theme Architecture
+
+## Module Layout
+
+`TailwindTheme` extends `Base` and is split into concern modules under `StimulusPlumbers::Themes::Tailwind::*`. Each module provides CSS class resolution for one component family. The `Icon` module also owns the icon registry (`icons/`).
+
+## Constant Ownership Rules
+
+- **No local aliases** — never re-export another module's constant (e.g. `MY_CONST = Other::CONST`). Reference the constant directly at the call site.
+- **No prefix redundancy** — name constants after what they represent, not where they live. `Button::VARIANTS` not `Button::BUTTON_VARIANTS`; `Card::VARIANTS` not `Card::CARD_VARIANTS`.
+- **Remove unused constants** — if a constant has no call sites in `schema.rb`, delete it.
+
+## Shared Interactive Foundation — `Control::BASE`
+
+`Control::BASE` holds CSS shared by all focusable, disableable controls: font weight, transition, focus ring tokens, `disabled:*` states. Components include it via array splat and add their own ring color variable on top.
+
+```ruby
+# Composition — correct
+[*Control::BASE, *Button::BASE, "extra-class"].freeze
+
+# Duplication — wrong
+["font-medium", "transition-colors", "extra-class"].freeze
+```
+
+`Control::BASE` is always included first; never duplicate its classes in component constants.
+
+## Icon-Only Square Pattern
+
+The core gem wraps button/link text in `<span>`. Icon-only renders no `<span>`. The theme detects this via CSS:
+
+- `Button::LAYOUT` carries `[&:not(:has(>span))]:aspect-square [&:not(:has(>span))]:px-0`
+- `Link::BUTTON` carries the same two classes
+- `fab`/`fab_outline` types become circles via this mechanism
+
+**Do not change the Ruby renderer's `<span>` wrapping contract without updating these theme constants.**
+
+## Card Style Pattern
+
+Button, Link, Checkbox, and Radio all share a unified card style via the `--card-ring` CSS variable.
+
+- `Card::VARIANTS` maps `:default/:success/:destructive/:warning/:info` to `--sp-color-*` values
+- All card-type components reference `Card::VARIANTS.fetch(variant, Card::VARIANTS[:default])`
+- **Button card** (`type: :card`) — `Button::BASE + Button::CARD + Button::TYPES[:card]`; `size:` ignored
+- **Link card** — `Link::CARD` composes `Control::BASE + Card::BASE + Button::CARD`
+- **Checkbox card** — input visible; label uses `has-[:checked]:border-(--card-ring)`
+- **Radio card/button** — input is `hidden peer`; label uses `peer-checked:border-(--card-ring)`
+
+## Floating Field Key Ownership
+
+Floating-label theme keys (`form_field_floating`, `form_field_floating_group`, `form_field_floating_label`) and their constants (`FLOATING_INPUT_*`, `FLOATING_GROUP_TYPES`, `FLOATING_LABEL_*`) live in `Form::Field` (`form/field.rb`), **not** `Form::Input`. Floating is a field-layout concern, not an input-element concern.

data/docs/guide.md

@@ -0,0 +1,23 @@
+# Guide
+
+Adding this gem registers and activates the Tailwind theme automatically in Rails — no config
+needed. Outside Rails, activate it explicitly with `config.theme.use(:tailwind)`.
+
+Run the install generator once to wire the required `@source` directive and the `animations.css`
+import (registers the indeterminate progress bar's slide keyframe via `@theme`) into your Tailwind
+CSS entry file:
+
+```bash
+bin/rails generate stimulus_plumbers:tailwind:install
+```
+
+It re-runs automatically on `assets:precompile`/`tailwindcss:build` after that. File detection and
+the `STIMULUS_PLUMBERS_CSS_ENTRY` override are shared with the core gem — see
+[stimulus-plumbers-rails/docs/guide.md#css-entry-file-detection](../../stimulus-plumbers-rails/docs/guide.md#css-entry-file-detection).
+
+Icons: pass a kebab-case name to `sp_icon` or any `icon_leading:`/`icon_trailing:` option (append
+`/solid` for the filled variant) — see [README.md](../README.md#icons) for aliases and the
+optional `heroicons` gem.
+
+To implement a custom theme instead of/alongside Tailwind, see
+[stimulus-plumbers-rails/docs/component/theme.md](../../stimulus-plumbers-rails/docs/component/theme.md).

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "stimulus_plumbers/generators/css_entrypoint"
+require "stimulus_plumbers/generators/tokens_directive"
+require "stimulus_plumbers/tailwind/generators/animations_directive"
+require "stimulus_plumbers/tailwind/generators/sources_directive"
+
+module StimulusPlumbers
+  module Tailwind
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        include StimulusPlumbers::Generators::CssEntrypoint
+
+        def install
+          css_file = entry_css_file(**css_file_lookup_options)
+          return warn_entry_css_not_found(label: "Tailwind CSS", **css_file_lookup_options) unless css_file
+
+          apply_tokens_directive(css_file)
+          apply_animations_directive(css_file)
+          apply_sources_directive(css_file)
+        end
+
+        private
+
+        def css_file_lookup_options
+          {
+            candidates: StimulusPlumbers::Generators::CssEntrypoint::ENTRY_CANDIDATES,
+            env_var:    StimulusPlumbers::Generators::CssEntrypoint::STIMULUS_PLUMBERS_CSS_ENTRY
+          }
+        end
+
+        def apply_tokens_directive(css_file)
+          apply_edit(
+            css_file,
+            StimulusPlumbers::Generators::TokensDirective.directive(from: File.dirname(css_file)),
+            stale_pattern: StimulusPlumbers::Generators::TokensDirective.stale_pattern
+          )
+        end
+
+        def apply_animations_directive(css_file)
+          apply_edit(
+            css_file,
+            AnimationsDirective.directive(from: File.dirname(css_file)),
+            anchor_pattern: AnimationsDirective.anchor_pattern,
+            stale_pattern:  AnimationsDirective.stale_pattern
+          )
+        end
+
+        def apply_sources_directive(css_file)
+          apply_edit(
+            css_file,
+            SourcesDirective.directive(from: File.dirname(css_file)),
+            anchor_pattern: SourcesDirective.anchor_pattern,
+            stale_pattern:  SourcesDirective.stale_pattern
+          )
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/tailwind/engine.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Tailwind
+    class Engine < ::Rails::Engine
+      initializer "stimulus_plumbers_tailwind.register_theme" do
+        StimulusPlumbers.configure do |c|
+          c.theme.register(:tailwind, StimulusPlumbers::Themes::TailwindTheme)
+          c.theme.use(:tailwind)
+        end
+      end
+
+      rake_tasks do
+        load File.join(__dir__, "../../tasks/stimulus_plumbers_tailwind.rake")
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/tailwind/generators/animations_directive.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module StimulusPlumbers
+  module Tailwind
+    module Generators
+      module AnimationsDirective
+        GEM_ROOT                = File.expand_path("../../../..", __dir__)
+        ANIMATIONS_CSS_REL_PATH = "app/assets/stylesheets/stimulus_plumbers/tailwind/animations.css"
+
+        module_function
+
+        def directive(from:)
+          path = Pathname.new(GEM_ROOT).join(ANIMATIONS_CSS_REL_PATH)
+          rel  = path.relative_path_from(Pathname.new(from))
+          %(@import "#{rel}";)
+        end
+
+        # Anchors right after the core tokens.css import so the two asset
+        # imports stay grouped, ahead of the tailwindcss import and @source lines.
+        def anchor_pattern
+          %r{@import "[^"]*tokens\.css";}
+        end
+
+        def stale_pattern
+          %r{@import "[^"]*#{Regexp.escape(ANIMATIONS_CSS_REL_PATH)}";}
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/tailwind/generators/sources_directive.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module StimulusPlumbers
+  module Tailwind
+    module Generators
+      module SourcesDirective
+        GEM_NAME = "stimulus_plumbers_tailwind"
+        LIB_DIR  = File.expand_path("../../..", __dir__)
+
+        module_function
+
+        def directive(from:)
+          rel = Pathname.new(LIB_DIR).relative_path_from(Pathname.new(from))
+          %(@source "#{rel}/**/*.rb";)
+        end
+
+        def anchor_pattern
+          %r{@import "tailwindcss"[^;]*;}
+        end
+
+        def stale_pattern
+          %r{@source "[^"]*#{Regexp.escape(GEM_NAME)}[^"]*";}
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/tailwind/version.rb

@@ -2,6 +2,6 @@
 
 module StimulusPlumbers
   module Tailwind
-    VERSION = "0.4.5"
+    VERSION = "0.4.9"
   end
 end

data/lib/stimulus_plumbers/themes/tailwind/button.rb

@@ -147,7 +147,7 @@ module StimulusPlumbers
         end
 
         def button_icon_classes
-          { classes: klasses("size-(--sp-icon-size-sm)", "stroke-current") }
+          { classes: klasses("stroke-current") }
         end
       end
     end

data/lib/stimulus_plumbers/themes/tailwind/card.rb

@@ -26,7 +26,7 @@ module StimulusPlumbers
         ].freeze
 
         ICON_BASE = %w[
-          size-(--sp-space-6) shrink-0 stroke-current text-(--sp-color-muted-fg)
+          shrink-0 stroke-current text-(--sp-color-muted-fg)
         ].freeze
 
         TITLE_BASE = %w[

data/lib/stimulus_plumbers/themes/tailwind/checklist.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Themes
+    module Tailwind
+      module Checklist
+        WRAPPER_BASE = %w[flex flex-col gap-(--sp-space-1)].freeze
+
+        ITEM_BASE = [
+          *Control::BASE,
+          "group/checklist-item flex items-center gap-(--sp-space-2) w-full text-start",
+          "px-(--sp-space-2) py-(--sp-space-1)",
+          "rounded-(--sp-radius-sm) text-(length:--sp-text-sm)",
+          "cursor-pointer select-none text-(--sp-color-fg)",
+          "hover:bg-(--sp-color-muted)",
+          "has-disabled:cursor-default has-disabled:hover:bg-transparent"
+        ].freeze
+
+        INPUT_BASE = [
+          *Control::ACCENT,
+          "size-(--sp-control-size) rounded-(--sp-radius-sm) shrink-0",
+          "border border-(--sp-color-border) bg-(--sp-color-muted)",
+          "focus:ring-(length:--sp-focus-ring-width) focus:ring-(--sp-focus-ring-color) focus:outline-none",
+          "disabled:opacity-50 disabled:cursor-not-allowed cursor-pointer"
+        ].freeze
+
+        CONTENT_BASE = %w[flex flex-col flex-1 min-w-0].freeze
+
+        TITLE_BASE = %w[
+          text-(length:--sp-text-sm) font-medium text-(--sp-color-fg)
+          group-has-checked/checklist-item:line-through
+          group-has-checked/checklist-item:text-(--sp-color-muted-fg)
+        ].freeze
+
+        DESCRIPTION_BASE = %w[text-(length:--sp-text-xs) text-(--sp-color-muted-fg)].freeze
+
+        private
+
+        def checklist_classes
+          { classes: klasses(*WRAPPER_BASE) }
+        end
+
+        def checklist_item_classes
+          { classes: klasses(*ITEM_BASE) }
+        end
+
+        def checklist_item_input_classes
+          { classes: klasses(*INPUT_BASE) }
+        end
+
+        def checklist_item_content_classes
+          { classes: klasses(*CONTENT_BASE) }
+        end
+
+        def checklist_item_title_classes
+          { classes: klasses(*TITLE_BASE) }
+        end
+
+        def checklist_item_description_classes
+          { classes: klasses(*DESCRIPTION_BASE) }
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/themes/tailwind/combobox.rb

@@ -112,7 +112,7 @@ module StimulusPlumbers
         end
 
         def combobox_typeahead_loading_icon_classes
-          { classes: klasses("size-(--sp-icon-size-md)", "animate-spin") }
+          { classes: klasses("animate-spin") }
         end
 
         def combobox_typeahead_empty_classes

data/lib/stimulus_plumbers/themes/tailwind/control.rb

@@ -11,6 +11,8 @@ module StimulusPlumbers
           focus-visible:ring-offset-(length:--sp-focus-ring-offset)
           disabled:pointer-events-none disabled:opacity-50
         ].freeze
+
+        ACCENT = %w[[accent-color:var(--sp-color-primary)] cursor-pointer].freeze
       end
     end
   end

data/lib/stimulus_plumbers/themes/tailwind/form/input.rb

@@ -80,21 +80,24 @@ module StimulusPlumbers
 
           # ── Choice inputs ─────────────────────────────────────────────────────
           CHECKBOX_TYPES = {
-            default: %w[
-              size-(--sp-control-size) rounded-(--sp-radius-sm) shrink-0
-              border border-(--sp-color-border) bg-(--sp-color-muted)
-              focus:ring-(length:--sp-focus-ring-width) focus:ring-(--sp-focus-ring-color) focus:outline-none
-              disabled:opacity-50 disabled:cursor-not-allowed cursor-pointer
+            default: [
+              *Control::ACCENT,
+              "size-(--sp-control-size) rounded-(--sp-radius-sm) shrink-0",
+              "border border-(--sp-color-border) bg-(--sp-color-muted)",
+              "focus:ring-(length:--sp-focus-ring-width) focus:ring-(--sp-focus-ring-color) focus:outline-none",
+              "disabled:opacity-50 disabled:cursor-not-allowed cursor-pointer"
             ].freeze,
-            button:  %w[
-              size-(--sp-control-size) rounded-(--sp-radius-sm) shrink-0
-              border border-(--sp-color-border) bg-(--sp-color-muted)
-              focus:ring-(length:--sp-focus-ring-width) focus:ring-(--sp-focus-ring-color) focus:outline-none
-              disabled:opacity-50 disabled:cursor-not-allowed cursor-pointer
+            button:  [
+              *Control::ACCENT,
+              "size-(--sp-control-size) rounded-(--sp-radius-sm) shrink-0",
+              "border border-(--sp-color-border) bg-(--sp-color-muted)",
+              "focus:ring-(length:--sp-focus-ring-width) focus:ring-(--sp-focus-ring-color) focus:outline-none",
+              "disabled:opacity-50 disabled:cursor-not-allowed cursor-pointer"
             ].freeze,
             card:    %w[
               size-(--sp-control-size) rounded-(--sp-radius-sm) shrink-0
               border border-(--sp-color-border) bg-(--sp-color-muted)
+              [accent-color:var(--card-ring)] cursor-pointer
               checked:border-(--card-ring)
               focus:ring-(length:--sp-focus-ring-width) focus:ring-(--card-ring) focus:outline-none
               disabled:opacity-50 disabled:cursor-not-allowed cursor-pointer
@@ -102,11 +105,11 @@ module StimulusPlumbers
           }.freeze
 
           RADIO_TYPES = {
-            default: %w[
-              size-(--sp-control-size) rounded-full shrink-0
-              [accent-color:var(--sp-color-primary)] cursor-pointer
-              focus:ring-(length:--sp-focus-ring-width) focus:ring-(--sp-focus-ring-color) focus:outline-none
-              disabled:opacity-50 disabled:cursor-not-allowed
+            default: [
+              *Control::ACCENT,
+              "size-(--sp-control-size) rounded-full shrink-0",
+              "focus:ring-(length:--sp-focus-ring-width) focus:ring-(--sp-focus-ring-color) focus:outline-none",
+              "disabled:opacity-50 disabled:cursor-not-allowed"
             ].freeze,
             button:  %w[hidden].freeze,
             card:    %w[hidden].freeze

data/lib/stimulus_plumbers/themes/tailwind/icon.rb

@@ -16,7 +16,8 @@ module StimulusPlumbers
           "email"         => "envelope",
           "calendar"      => "calendar-days",
           "external-link" => "arrow-top-right-on-square",
-          "reveal"        => "eye"
+          "reveal"        => "eye",
+          "grip-vertical" => "bars-3"
         }.freeze
 
         ICONS = StimulusPlumbers::Themes::Icons::Registry.new(
@@ -24,14 +25,20 @@ module StimulusPlumbers
           aliases: ALIASES
         )
 
+        SIZES = {
+          sm: "size-(--sp-icon-size-sm)",
+          md: "size-(--sp-icon-size-md)",
+          lg: "size-(--sp-icon-size-lg)"
+        }.freeze
+
         def icons
           ICONS
         end
 
         private
 
-        def icon_classes
-          { classes: "size-(--sp-icon-size-lg)" }
+        def icon_classes(size: :lg)
+          { classes: SIZES.fetch(size, SIZES[:lg]) }
         end
       end
     end

data/lib/stimulus_plumbers/themes/tailwind/icons/customs/progress-ring.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 44 44" width="44" height="44" fill="none">
+  <circle cx="22" cy="22" r="18" stroke-width="3" class="track"></circle>
+  <circle
+    cx="22"
+    cy="22"
+    r="18"
+    stroke="currentColor"
+    stroke-width="3"
+    stroke-linecap="round"
+    data-progress-target="fill"
+  ></circle>
+</svg>

data/lib/stimulus_plumbers/themes/tailwind/indicator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Themes
+    module Tailwind
+      module Indicator
+        VARIANTS = {
+          primary:     "bg-(--sp-color-primary)",
+          secondary:   "bg-(--sp-color-secondary)",
+          tertiary:    "bg-(--sp-color-muted-fg)",
+          success:     "bg-(--sp-color-success)",
+          destructive: "bg-(--sp-color-destructive)",
+          warning:     "bg-(--sp-color-warning)",
+          info:        "bg-(--sp-color-info)"
+        }.freeze
+
+        DOT   = %w[inline-flex size-2.5 rounded-full].freeze
+        BADGE = %w[
+          inline-flex items-center justify-center
+          min-w-5 h-5 px-1
+          rounded-full text-(length:--sp-text-xs) font-medium text-white
+        ].freeze
+
+        # Establishes the positioning context the pulse ring overlays onto — no margin needed.
+        WRAPPER = %w[relative inline-flex items-center justify-center].freeze
+
+        PULSE_RING = %w[
+          absolute inset-0 rounded-full
+          bg-(--sp-color-indicator) opacity-75
+          animate-ping motion-reduce:animate-none
+        ].freeze
+
+        private
+
+        def indicator_classes(type: :dot, variant: nil)
+          { classes: klasses(*(type.to_sym == :badge ? BADGE : DOT), VARIANTS.fetch(variant, nil)) }
+        end
+
+        def indicator_wrapper_classes
+          { classes: klasses(*WRAPPER) }
+        end
+
+        def indicator_pulse_classes
+          { classes: klasses(*PULSE_RING) }
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/themes/tailwind/link.rb

@@ -79,7 +79,7 @@ module StimulusPlumbers
         end
 
         def link_icon_classes
-          { classes: klasses("size-(--sp-icon-size-sm)", "stroke-current") }
+          { classes: klasses("stroke-current") }
         end
       end
     end

data/lib/stimulus_plumbers/themes/tailwind/list.rb

@@ -64,7 +64,7 @@ module StimulusPlumbers
         end
 
         def list_item_icon_classes
-          { classes: klasses("size-(--sp-icon-size-sm)", "stroke-current") }
+          { classes: klasses("stroke-current") }
         end
 
         def list_item_content_classes

data/lib/stimulus_plumbers/themes/tailwind/ordered_list.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Themes
+    module Tailwind
+      module OrderedList
+        # ── Item ──────────────────────────────────────────────────────────────
+        ITEM_BASE = [
+          *Control::BASE,
+          "flex items-center gap-(--sp-space-2) w-full",
+          "px-(--sp-space-2) py-(--sp-space-1)",
+          "rounded-(--sp-radius-sm) text-(length:--sp-text-sm)",
+          "text-(--sp-color-fg)",
+          "focus-visible:ring-(--sp-color-primary-ring)",
+          "aria-[current]:bg-(--sp-color-primary)/10 aria-[current]:text-(--sp-color-primary)"
+        ].freeze
+
+        HANDLE_BASE = %w[
+          flex items-center justify-center shrink-0
+          stroke-current
+          text-(--sp-color-muted-fg)
+          cursor-grab active:cursor-grabbing
+          touch-none
+        ].freeze
+
+        CONTENT_BASE = %w[
+          flex flex-col flex-1 min-w-0
+        ].freeze
+
+        TITLE_BASE = %w[
+          text-(length:--sp-text-sm) font-medium text-(--sp-color-fg)
+        ].freeze
+
+        DESCRIPTION_BASE = %w[
+          text-(length:--sp-text-xs) text-(--sp-color-muted-fg)
+        ].freeze
+
+        private
+
+        def ordered_list_classes
+          { classes: klasses("flex flex-col gap-(--sp-space-1) py-(--sp-space-1)") }
+        end
+
+        def ordered_list_item_classes
+          { classes: klasses(*ITEM_BASE) }
+        end
+
+        def ordered_list_item_handle_classes
+          { classes: klasses(*HANDLE_BASE) }
+        end
+
+        def ordered_list_item_content_classes
+          { classes: klasses(*CONTENT_BASE) }
+        end
+
+        def ordered_list_item_title_classes
+          { classes: klasses(*TITLE_BASE) }
+        end
+
+        def ordered_list_item_description_classes
+          { classes: klasses(*DESCRIPTION_BASE) }
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/themes/tailwind/progress.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Themes
+    module Tailwind
+      module Progress
+        BAR = %w[
+          relative w-full h-2 overflow-hidden rounded-full
+          bg-(--sp-color-muted)
+        ].freeze
+
+        BAR_FILL = %w[
+          h-full rounded-full bg-(--sp-color-primary)
+          [.sp-progress-indeterminate_&]:animate-progress-slide
+          [.sp-progress-indeterminate_&]:motion-reduce:animate-none
+        ].freeze
+
+        # Circle stroke/fill live in icons/customs/progress-ring.svg — @source never scans
+        # .svg files, so Tailwind classes there are inert.
+        # Indeterminate class and utility land on this same svg, so this needs the compound
+        # [&.foo] form, not BAR_FILL's [.foo_&] descendant form.
+        RING = %w[
+          -rotate-90 text-(--sp-color-primary)
+          [&.sp-progress-indeterminate]:animate-spin
+        ].freeze
+
+        METER = %w[
+          w-full h-2 rounded-full
+          [&::-webkit-meter-bar]:rounded-full [&::-webkit-meter-bar]:bg-(--sp-color-muted)
+          [&::-webkit-meter-optimum-value]:bg-(--sp-color-success)
+          [&::-webkit-meter-suboptimum-value]:bg-(--sp-color-warning)
+          [&::-webkit-meter-even-less-good-value]:bg-(--sp-color-destructive)
+          [&::-moz-meter-bar]:bg-(--sp-color-success)
+        ].freeze
+
+        private
+
+        def progress_bar_classes      = { classes: klasses(*BAR) }
+        def progress_bar_fill_classes = { classes: klasses(*BAR_FILL) }
+        def progress_ring_classes     = { classes: klasses(*RING) }
+        def progress_meter_classes    = { classes: klasses(*METER) }
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/themes/tailwind/timeline/group.rb

@@ -5,22 +5,31 @@ module StimulusPlumbers
     module Tailwind
       module Timeline
         module Group
-          WRAPPER  = %w[space-y-4].freeze
-          SECTION  = %w[
+          WRAPPER         = %w[flex flex-col gap-y-4].freeze
+          SECTION         = %w[
             p-4
             bg-(--sp-color-bg-muted)
             border border-(--sp-color-border)
             rounded-lg
           ].freeze
-          DATE     = %w[text-base font-semibold text-(--sp-color-fg)].freeze
-          LIST     = %w[mt-3 divide-y divide-(--sp-color-border)].freeze
+          DATE            = %w[text-base font-semibold text-(--sp-color-fg)].freeze
+          LIST_VERTICAL   = %w[
+            pt-3 flex flex-col
+            divide-y divide-(--sp-color-border)
+            [&>li]:py-2 [&>li]:first:pt-0 [&>li]:last:pb-0
+          ].freeze
+          LIST_HORIZONTAL = %w[pt-3 flex gap-x-4].freeze
 
           private
 
           def timeline_group_classes              = { classes: klasses(WRAPPER) }
           def timeline_group_section_classes      = { classes: klasses(SECTION) }
           def timeline_group_section_date_classes = { classes: klasses(DATE) }
-          def timeline_group_section_list_classes = { classes: klasses(LIST) }
+
+          def timeline_group_section_list_classes(orientation: :vertical)
+            list = orientation.to_sym == :horizontal ? LIST_HORIZONTAL : LIST_VERTICAL
+            { classes: klasses(list) }
+          end
         end
       end
     end

data/lib/stimulus_plumbers/themes/tailwind/timeline.rb

@@ -18,7 +18,6 @@ module StimulusPlumbers
           mt-1 flex shrink-0 size-6 items-center justify-center rounded-full z-10
           bg-(--sp-color-bg) ring-4 ring-(--sp-color-bg)
         ].freeze
-        ITEM_INDICATOR_DOT_MARK = %w[size-3 rounded-full bg-(--sp-color-indicator)].freeze
 
         ITEM_INDICATOR_ICON = %w[
           mt-1 flex shrink-0 size-6 items-center justify-center rounded-full z-10
@@ -26,7 +25,7 @@ module StimulusPlumbers
           ring-4 ring-(--sp-color-bg)
         ].freeze
 
-        ITEM_INDICATOR_ICON_SLOT = %w[size-(--sp-icon-size-sm) stroke-current].freeze
+        ITEM_INDICATOR_ICON_SLOT = %w[stroke-current].freeze
 
         ITEM_INDICATOR_DOT_HORIZONTAL = %w[
           z-10 flex shrink-0 size-6 items-center justify-center rounded-full
@@ -50,12 +49,12 @@ module StimulusPlumbers
         ].freeze
         ITEM_TITLE       = %w[mb-1 text-base font-semibold text-(--sp-color-fg)].freeze
         ITEM_HEADING     = %w[mb-1].freeze
-        ITEM_TRIGGER     = %w[
-          w-full text-left text-base font-semibold
-          text-(--sp-color-fg)
-          hover:text-(--sp-color-primary)
-          focus-visible:outline-none focus-visible:ring-2
-          focus-visible:ring-(--sp-color-primary) focus-visible:rounded-sm
+        ITEM_TRIGGER     = [
+          *Control::BASE,
+          "w-full text-left text-base font-semibold",
+          "text-(--sp-color-fg)",
+          "hover:text-(--sp-color-primary)",
+          "focus-visible:ring-(--sp-color-primary-ring) focus-visible:rounded-sm"
         ].freeze
         ITEM_DESCRIPTION = %w[text-sm text-(--sp-color-muted-fg)].freeze
         ITEM_DETAIL      = %w[mt-2 text-sm text-(--sp-color-muted-fg)].freeze
@@ -93,7 +92,6 @@ module StimulusPlumbers
         def timeline_item_description_classes = { classes: klasses(ITEM_DESCRIPTION) }
         def timeline_item_detail_classes      = { classes: klasses(ITEM_DETAIL) }
         def timeline_item_actions_classes     = { classes: klasses(ITEM_ACTIONS) }
-        def timeline_item_indicator_dot_classes = { classes: klasses(ITEM_INDICATOR_DOT_MARK) }
         def timeline_item_connector_classes       = { classes: klasses(ITEM_CONNECTOR_HORIZONTAL) }
         def timeline_item_content_classes         = { classes: klasses(ITEM_CONTENT_HORIZONTAL) }
         def timeline_track_line_classes                = { classes: klasses(TRACK_LINE_VERTICAL) }

data/lib/stimulus_plumbers/themes/tailwind_theme.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "tailwind/control"
+require_relative "tailwind/checklist"
 require_relative "tailwind/list"
+require_relative "tailwind/ordered_list"
 require_relative "tailwind/avatar"
 require_relative "tailwind/button"
 require_relative "tailwind/button/group"
@@ -12,14 +14,18 @@ require_relative "tailwind/form"
 require_relative "tailwind/form/field"
 require_relative "tailwind/form/input"
 require_relative "tailwind/icon"
+require_relative "tailwind/indicator"
 require_relative "tailwind/layout"
 require_relative "tailwind/link"
+require_relative "tailwind/progress"
 require_relative "tailwind/timeline"
 
 module StimulusPlumbers
   module Themes
     class TailwindTheme < Base
+      include Tailwind::Checklist
       include Tailwind::List
+      include Tailwind::OrderedList
       include Tailwind::Combobox
       include Tailwind::Avatar
       include Tailwind::Button
@@ -30,8 +36,10 @@ module StimulusPlumbers
       include Tailwind::Form::Field
       include Tailwind::Form::Input
       include Tailwind::Icon
+      include Tailwind::Indicator
       include Tailwind::Layout
       include Tailwind::Link
+      include Tailwind::Progress
       include Tailwind::Timeline
       include Tailwind::Timeline::Group
 

data/lib/stimulus_plumbers_tailwind.rb

@@ -6,7 +6,7 @@ require_relative "stimulus_plumbers/tailwind/version"
 require_relative "stimulus_plumbers/themes/tailwind_theme"
 
 if defined?(Rails::Engine)
-  require_relative "stimulus_plumbers_tailwind/engine"
+  require_relative "stimulus_plumbers/tailwind/engine"
 else
   StimulusPlumbers.configure do |c|
     c.theme.register(:tailwind, StimulusPlumbers::Themes::TailwindTheme)

data/lib/tasks/stimulus_plumbers_tailwind.rake

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
-namespace :stimulus_plumbers_tailwind do
-  desc "Add @source directive for stimulus_plumbers_tailwind into Tailwind CSS entry file"
-  task install: :environment do
-    require "generators/stimulus_plumbers_tailwind/install/install_generator"
-    StimulusPlumbersTailwind::Generators::InstallGenerator.new(
-      [], {}, { destination_root: Rails.root.to_s }
-    ).invoke_all
+namespace :stimulus_plumbers do
+  namespace :tailwind do
+    desc "Add @source directive for stimulus_plumbers_tailwind into Tailwind CSS entry file"
+    task(:install) do
+      unless ENV["STIMULUS_PLUMBERS_SKIP_INSTALL"]
+        require "generators/stimulus_plumbers/tailwind/install/install_generator"
+        StimulusPlumbers::Tailwind::Generators::InstallGenerator.new(
+          [], {}, { destination_root: Rails.root.to_s }
+        ).invoke_all
+      end
+    end
   end
 end
 
-Rake::Task["assets:precompile"].enhance(["stimulus_plumbers_tailwind:install"]) if Rake::Task.task_defined?("assets:precompile")
+Rake::Task["stimulus_plumbers:tailwind:install"].enhance(["environment"]) unless ENV["STIMULUS_PLUMBERS_SKIP_INSTALL"]
 
-Rake::Task["tailwindcss:build"].enhance(["stimulus_plumbers_tailwind:install"]) if Rake::Task.task_defined?("tailwindcss:build")
+# Hooks into these tasks as a prerequisite; Rake merges rather than overwrites, so order-independent.
+task "assets:precompile" => ["stimulus_plumbers:tailwind:install"]
+task "tailwindcss:build" => ["stimulus_plumbers:tailwind:install"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_plumbers_tailwind
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.9
 platform: ruby
 authors:
 - Ryan Chang
@@ -33,13 +33,20 @@ files:
 - CHANGELOG.md
 - LICENSE-DEPENDENCIES
 - README.md
-- lib/generators/stimulus_plumbers_tailwind/install/install_generator.rb
+- app/assets/stylesheets/stimulus_plumbers/tailwind/animations.css
+- docs/architecture.md
+- docs/guide.md
+- lib/generators/stimulus_plumbers/tailwind/install/install_generator.rb
+- lib/stimulus_plumbers/tailwind/engine.rb
+- lib/stimulus_plumbers/tailwind/generators/animations_directive.rb
+- lib/stimulus_plumbers/tailwind/generators/sources_directive.rb
 - lib/stimulus_plumbers/tailwind/version.rb
 - lib/stimulus_plumbers/themes/tailwind/avatar.rb
 - lib/stimulus_plumbers/themes/tailwind/button.rb
 - lib/stimulus_plumbers/themes/tailwind/button/group.rb
 - lib/stimulus_plumbers/themes/tailwind/calendar.rb
 - lib/stimulus_plumbers/themes/tailwind/card.rb
+- lib/stimulus_plumbers/themes/tailwind/checklist.rb
 - lib/stimulus_plumbers/themes/tailwind/combobox.rb
 - lib/stimulus_plumbers/themes/tailwind/control.rb
 - lib/stimulus_plumbers/themes/tailwind/form.rb
@@ -47,6 +54,7 @@ files:
 - lib/stimulus_plumbers/themes/tailwind/form/input.rb
 - lib/stimulus_plumbers/themes/tailwind/icon.rb
 - lib/stimulus_plumbers/themes/tailwind/icons/custom.rb
+- lib/stimulus_plumbers/themes/tailwind/icons/customs/progress-ring.svg
 - lib/stimulus_plumbers/themes/tailwind/icons/customs/spinner.svg
 - lib/stimulus_plumbers/themes/tailwind/icons/heroicon.rb
 - lib/stimulus_plumbers/themes/tailwind/icons/heroicons/outline/academic-cap.svg
@@ -697,14 +705,16 @@ files:
 - lib/stimulus_plumbers/themes/tailwind/icons/heroicons/solid/wrench.svg
 - lib/stimulus_plumbers/themes/tailwind/icons/heroicons/solid/x-circle.svg
 - lib/stimulus_plumbers/themes/tailwind/icons/heroicons/solid/x-mark.svg
+- lib/stimulus_plumbers/themes/tailwind/indicator.rb
 - lib/stimulus_plumbers/themes/tailwind/layout.rb
 - lib/stimulus_plumbers/themes/tailwind/link.rb
 - lib/stimulus_plumbers/themes/tailwind/list.rb
+- lib/stimulus_plumbers/themes/tailwind/ordered_list.rb
+- lib/stimulus_plumbers/themes/tailwind/progress.rb
 - lib/stimulus_plumbers/themes/tailwind/timeline.rb
 - lib/stimulus_plumbers/themes/tailwind/timeline/group.rb
 - lib/stimulus_plumbers/themes/tailwind_theme.rb
 - lib/stimulus_plumbers_tailwind.rb
-- lib/stimulus_plumbers_tailwind/engine.rb
 - lib/tasks/stimulus_plumbers_tailwind.rake
 homepage: https://github.com/ryancyq/stimulus-plumbers
 licenses:

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

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-require "rails/generators"
-
-module StimulusPlumbersTailwind
-  module Generators
-    class InstallGenerator < Rails::Generators::Base
-      GEM_NAME          = "stimulus_plumbers_tailwind"
-      TAILWIND_CSS_FILE = "TAILWIND_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
-        return warn_entry_css_not_found unless css_file
-
-        apply_edit(css_file)
-      end
-
-      private
-
-      def warn_entry_css_not_found
-        tried = CSS_CANDIDATES.map { |c| File.join(destination_root, c) }
-        tried.unshift(File.expand_path(ENV[TAILWIND_CSS_FILE])) if ENV[TAILWIND_CSS_FILE]
-        say "Could not find a Tailwind CSS entry file. Tried: #{tried.join(", ")}. " \
-            "Set #{TAILWIND_CSS_FILE}=/path/to/entry.css and re-run.",
-            :red
-      end
-
-      def apply_edit(css_file)
-        content              = File.read(css_file)
-        new_content, status  = content_edit(content, source_directive)
-
-        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
-      end
-
-      def content_edit(content, source_line)
-        if content.include?(source_line)
-          nil
-        elsif (existing = content.match(%r{@source "[^"]*#{Regexp.escape(GEM_NAME)}[^"]*";}))
-          [content.sub(existing[0], source_line), :update]
-        elsif (import_line = content.match(%r{@import "tailwindcss"[^;]*;}))
-          [content.sub(import_line[0], "#{import_line[0]}\n#{source_line}"), :insert]
-        else
-          ["#{content.rstrip}\n#{source_line}\n", :append]
-        end
-      end
-
-      def source_directive
-        spec = Gem.loaded_specs[GEM_NAME]
-        %(@source "#{spec.gem_dir}/lib/**/*.rb";)
-      end
-
-      def entry_css_file
-        if ENV[TAILWIND_CSS_FILE]
-          path = File.expand_path(ENV[TAILWIND_CSS_FILE])
-          return path if File.exist?(path)
-        end
-
-        CSS_CANDIDATES
-          .map { |c| File.join(destination_root, c) }
-          .find { |f| File.exist?(f) }
-      end
-
-      def relative_to_destination(path)
-        path.delete_prefix("#{destination_root}/")
-      end
-    end
-  end
-end

data/lib/stimulus_plumbers_tailwind/engine.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module StimulusPlumbersTailwind
-  class Engine < ::Rails::Engine
-    initializer "stimulus_plumbers_tailwind.register_theme" do
-      StimulusPlumbers.configure do |c|
-        c.theme.register(:tailwind, StimulusPlumbers::Themes::TailwindTheme)
-      end
-    end
-
-    rake_tasks do
-      load File.join(__dir__, "../tasks/stimulus_plumbers_tailwind.rake")
-    end
-  end
-end