stimulus_plumbers_tailwind 0.4.4 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc13ebbc0d54b3d0b83fe52d34b67c051244438358d02102cc8337d39c8a7916
-  data.tar.gz: f34456ae1ab6b932d27df84124d3c4c2e40a1bcecd42a103be8894a6983951aa
+  metadata.gz: f570868b6706fa7a6b460b6bf78361957e3ed8a7ed3592bca0a2587966efbafe
+  data.tar.gz: 3ec048b9fef9972184db57cb95a121408ef3269134c4351c7f97a808f523d24e
 SHA512:
-  metadata.gz: 071bf0b4b5d77db471480274eb802aa6cf1e429a2163393953ad94bcd4afa7d62ffc8b45b83c0ff132dd352f78e2f295990fd0d74d80c15a139369e2943557e0
-  data.tar.gz: 5e34b159bd66b6caa3307e3dd8ec3c1f7083f992c4d8c4d5100f25a8bdb62869283a75eea332878deaee07de8edcdf3a22d2b0a5cb88dfd909a5dd36a6e89189
+  metadata.gz: 822d92416d88670f4c77c802cc87bd9c16b89cd17007f14a76d122cdcd9cbe7eb8224bf10ac6fbdb8d3f5c09abd9bec627633b78e43b880b5fcbd0ddcea16422
+  data.tar.gz: 1dda3a7595075605a20dd5739d42e39a74b1a0c3535e8c7af33ba7f85ddb2b603914b13da493ad7bd4605502e4afd0ae22eff30824eb736bbbe06c075bae314b

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.4](https://github.com/ryancyq/stimulus-plumbers/compare/stimulus-plumbers-tailwind/v0.4.3..stimulus-plumbers-tailwind/v0.4.4) - 2026-06-30
+
+### Dependencies
+
+- update npm package dist to have both es + umd + source map - ([64ec309](https://github.com/ryancyq/stimulus-plumbers/commit/64ec309ca171584d1604e4e7d3d3533878ebed7a)) - Ryan Chang
+
 ---
 ## [0.4.3](https://github.com/ryancyq/stimulus-plumbers/compare/stimulus-plumbers-tailwind/v0.4.2..stimulus-plumbers-tailwind/v0.4.3) - 2026-06-30
 

data/README.md

@@ -6,6 +6,8 @@
 
 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
@@ -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,10 +33,10 @@ 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 import) into your Tailwind CSS entry file:
 
 ```bash
-bin/rails generate stimulus_plumbers_tailwind:install
+bin/rails generate stimulus_plumbers:tailwind:install
 ```
 
 The generator checks these files in order:
@@ -45,7 +47,7 @@ The generator checks these files in order:
 
 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 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:
 
 - `assets:precompile` (Sprockets and Propshaft both define this task)
 - `tailwindcss:build` (when `tailwindcss-rails` is present)
@@ -53,7 +55,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

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,22 @@
+# 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 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 — see
+[README.md](../README.md#installation) for file-detection order and the `TAILWIND_CSS_FILE`
+override.
+
+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,63 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "stimulus_plumbers/generators/css_entrypoint"
+require "stimulus_plumbers/generators/tokens_directive"
+
+module StimulusPlumbers
+  module Tailwind
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        include StimulusPlumbers::Generators::CssEntrypoint
+
+        GEM_NAME          = "stimulus_plumbers_tailwind"
+        LIB_DIR           = File.expand_path("../../../..", __dir__)
+        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(**css_file_lookup_options)
+          return warn_entry_css_not_found(label: "Tailwind CSS", **css_file_lookup_options) unless css_file
+
+          apply_edit(
+            css_file,
+            StimulusPlumbers::Generators::TokensDirective.directive,
+            stale_pattern: StimulusPlumbers::Generators::TokensDirective.stale_pattern
+          )
+          apply_edit(
+            css_file,
+            source_directive,
+            anchor_pattern: source_anchor_pattern,
+            stale_pattern:  source_stale_pattern
+          )
+        end
+
+        private
+
+        def css_file_lookup_options
+          {
+            candidates:       CSS_CANDIDATES,
+            env_var:          TAILWIND_CSS_FILE,
+            fallback_env_var: StimulusPlumbers::Generators::CssEntrypoint::STIMULUS_PLUMBERS_CSS_FILE
+          }
+        end
+
+        def source_directive
+          %(@source "#{LIB_DIR}/**/*.rb";)
+        end
+
+        def source_anchor_pattern
+          %r{@import "tailwindcss"[^;]*;}
+        end
+
+        def source_stale_pattern
+          %r{@source "[^"]*#{Regexp.escape(GEM_NAME)}[^"]*";}
+        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/version.rb

@@ -2,6 +2,6 @@
 
 module StimulusPlumbers
   module Tailwind
-    VERSION = "0.4.4"
+    VERSION = "0.4.8"
   end
 end

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.4
+  version: 0.4.8
 platform: ruby
 authors:
 - Ryan Chang
@@ -33,7 +33,10 @@ files:
 - CHANGELOG.md
 - LICENSE-DEPENDENCIES
 - README.md
-- lib/generators/stimulus_plumbers_tailwind/install/install_generator.rb
+- 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/version.rb
 - lib/stimulus_plumbers/themes/tailwind/avatar.rb
 - lib/stimulus_plumbers/themes/tailwind/button.rb
@@ -704,7 +707,6 @@ files:
 - 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