view_component_css_dsl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9fcd1b87aa8e32ecd595601ffbce3015c1cd7d1119a97967fda706f859499654
+  data.tar.gz: 3b473073f9fca60d277fa0dd9700cd66b2da76a2f72222830f3a3d76bc294ce7
+SHA512:
+  metadata.gz: f4c117c6970000983d5acbdbb2d75254ac9875b5f0faeb64e80e78e88dd8644ee5dc3a01c24dfbac1257405cac55aa92c5975c1ac639cf28b8f2632e42002eec
+  data.tar.gz: a57068184216a9c7f3d0554efa9658805749d35aa57f8d1592a1a7c3f26bb5a2b3bc0333d68e073cb4281e619cff6067c84db55118196ee227b32bdbddfbcc98

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0]
+- Initial release. Extracted from SOFware/forge.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Lange
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,332 @@
+# view_component_css_dsl
+
+[![CI](https://github.com/SOFware/view_component_css_dsl/actions/workflows/ci.yml/badge.svg)](https://github.com/SOFware/view_component_css_dsl/actions/workflows/ci.yml)
+
+A declarative DSL for styling [ViewComponent](https://viewcomponent.org/) components with [Tailwind CSS](https://tailwindcss.com/).
+
+```ruby
+class ButtonComponent < ApplicationComponent
+  css "inline-flex rounded px-4 py-2"
+  css variant: :primary, style: "bg-blue-500 text-white"
+  css variant: :danger,  style: "bg-red-500 text-white"
+  css :disabled?,        style: "opacity-50"
+end
+```
+
+Replaces hand-rolled styling boilerplate with declarative one-liners for base styles, variants, and conditionals. Callers override per-instance via `class:` — smart-merge handles the rest.
+
+## Why
+
+Without this DSL, a ViewComponent with a few variants and a disabled state usually looks something like:
+
+```ruby
+class ButtonComponent < ViewComponent::Base
+  VARIANTS = %i[primary danger].freeze
+
+  def initialize(variant: :primary, disabled: false, extra_class: nil)
+    raise ArgumentError, "invalid variant" unless VARIANTS.include?(variant)
+    @variant = variant
+    @disabled = disabled
+    @extra_class = extra_class
+  end
+
+  private
+
+  def css_class
+    [
+      "inline-flex rounded px-4 py-2",
+      variant_class,
+      ("opacity-50" if @disabled),
+      @extra_class
+    ].compact.join(" ")
+  end
+
+  def variant_class
+    case @variant
+    when :primary then "bg-blue-500 text-white"
+    when :danger  then "bg-red-500 text-white"
+    end
+  end
+end
+```
+
+With the DSL:
+
+```ruby
+class ButtonComponent < ApplicationComponent
+  css "inline-flex rounded px-4 py-2"
+  css variant: :primary, style: "bg-blue-500 text-white"
+  css variant: :danger,  style: "bg-red-500 text-white"
+  css :disabled?,        style: "opacity-50"
+
+  def initialize(variant: :primary, disabled: false)
+    @variant = variant
+    @disabled = disabled
+  end
+
+  private
+
+  def disabled? = @disabled
+end
+```
+
+- Variant validation is automatic; passing `:unknown` raises an `ArgumentError`.
+- Declarations are easy to scan, easy to extend.
+- A caller's `class: "..."` is smart-merged with the component's defaults: `bg-black` from the caller wins over the component's `bg-blue-500`, but `rounded` and `px-4` stick.
+
+## Philosophy
+
+A handful of opinions are baked into this DSL. It still works if you ignore them, but it's a lot nicer if you don't.
+
+### Styling lives with the component
+
+Not in external stylesheets. Open the component file and you see exactly what it looks like. No grepping for selectors. No cascade surprises.
+
+### Significant styling lives on the top-level element
+
+A component renders one semantic block; that block is where its appearance lives. The DSL's `css` declarations describe that block.
+
+### Caller customization targets the top-level element
+
+When a caller passes `class: "..."`, the DSL smart-merges those classes onto the top-level element. Predictable surface, predictable override.
+
+### Sub-element styling = sub-component
+
+When a piece of your component needs its own styling decisions, promote it to its own ViewComponent (typically as a slot). Pass the shared semantic prop down; each component owns its own style table:
+
+```ruby
+class CardComponent < ApplicationComponent
+  css "rounded border p-4"
+  css type: :success, style: "border-green-200 bg-green-50 text-green-900"
+  css type: :danger,  style: "border-red-200 bg-red-50 text-red-900"
+
+  renders_one :card_header, ->(**html_attrs, &block) {
+    Card::HeaderComponent.new(type:, **html_attrs, &block)
+  }
+
+  def initialize(type:)
+    @type = type
+  end
+
+  private
+
+  attr_reader :type
+end
+
+class Card::HeaderComponent < ApplicationComponent
+  css "font-medium"
+  css type: :success, style: "text-sm"
+  css type: :danger,  style: "text-lg font-bold"
+
+  def initialize(type:)
+    @type = type
+  end
+end
+```
+
+The card renders the header as a slot, passing `type:` through. Without the DSL, this is typically a `case` statement or `class_names` block in both components — duplicated logic, more places for the style decision to drift. With it, each component reacts declaratively to the same shared prop.
+
+If you find yourself reaching inside a component to customize a sub-element, especially with dynamic styling, the sub-element wants to be its own component.
+
+## Requirements
+
+- Ruby 3.2+ (matches the floor for `view_component >= 4.0`)
+- [`view_component`](https://github.com/ViewComponent/view_component) `>= 4.0`
+- [Tailwind CSS](https://tailwindcss.com/) `>= 3.0` (the merge logic targets Tailwind's class-name syntax; v4 works — the syntax is compatible)
+
+## Installation
+
+```sh
+bundle add view_component_css_dsl
+```
+
+## Setup
+
+Include the concern in your base class, and inherit your components from it.
+
+`html_attrs` is automatically passed to all components; no declaration needed.
+
+The one piece of boilerplate: you must splat `**html_attrs` onto the top-level element of each component template.
+
+Main setup:
+```ruby
+# app/components/application_component.rb
+class ApplicationComponent < ViewComponent::Base
+  include ViewComponentCssDsl
+end
+```
+
+Component inherits from ApplicationComponent, gaining access to CssDsl
+```ruby
+# app/components/button_component.rb
+class ButtonComponent < ApplicationComponent
+  css "rounded px-4 py-2 bg-blue-500 text-white"
+
+  css variant: :success, style: "text-green-600"
+  css variant: :danger,  style: "text-lg font-bold text-red-600"
+
+  def initialize(variant: :primary)
+    @variant = variant
+  end
+end
+```
+
+Splat `**html_attrs` onto the top-level element.
+```erb
+<%# app/components/button_component.html.erb %>
+<%= tag.button **html_attrs do %>
+  <%= content %>
+<% end %>
+```
+
+Two conventions to follow:
+
+1. **`include ViewComponentCssDsl`** in your base component class. To opt out for one component, inherit from `ViewComponent::Base` directly.
+2. **Splat `**html_attrs`** onto the top-level element. This is what makes caller-passed attributes (`class:`, `data:`, `id:`, `aria:`, etc.) reach the DOM. A future version may automate this away.
+
+## The four `css` patterns
+
+### Base CSS
+
+Always applied. Inherited and smart-merged into child components.
+
+```ruby
+css "rounded border shadow p-4 bg-white"
+```
+
+### Axis-based variants
+
+Applied when the named instance variable matches. The DSL reads `@<axis>` from the instance.
+
+```ruby
+css variant: :primary, style: "bg-blue-500 text-white"
+css variant: :danger,  style: "bg-red-500 text-white"
+
+css size: :sm, style: "px-2 py-1 text-sm"
+css size: :lg, style: "px-6 py-3 text-lg"
+
+# Multi-axis rule — applied only when ALL axes match
+css variant: :primary, size: :lg, style: "font-bold ring-2"
+```
+
+Passing an axis value with no matching rule raises `ArgumentError`:
+
+```ruby
+MyComponent.new(variant: :unknown).css
+# => ArgumentError: Unknown variant :unknown for MyComponent.
+#    Valid values: :primary, :danger
+```
+
+### Method-based conditionals
+
+Applied when the method returns truthy on the instance.
+
+```ruby
+css :disabled?, style: "opacity-50 cursor-not-allowed"
+css :active?,   style: "ring-2 ring-blue-500"
+```
+
+### Proc-based dynamic CSS
+
+Evaluated at render time in the instance's context. Use when the class can't be known statically.
+
+```ruby
+css "base"
+css -> { "pl-#{@indent * 4}" }
+```
+
+Procs returning `nil` are dropped. Procs participate in smart_merge.
+
+## Caller customization
+
+Callers can pass `class:` (smart-merged with the component's defaults), plus any other HTML attribute (`data:`, `id:`, `aria:`, etc.) — they all land on the top-level element without the component having to opt each one in.
+
+### Vanilla call
+
+```ruby
+class ButtonComponent < ApplicationComponent
+  css "rounded px-4 py-2 bg-blue-500 text-white"
+end
+
+render ButtonComponent.new
+```
+
+Renders:
+
+```html
+<button class="rounded px-4 py-2 bg-blue-500 text-white"></button>
+```
+
+### Call with overrides
+
+```ruby
+render ButtonComponent.new(
+  class: "mt-4 bg-red-500",
+  data: {id: "submit-btn"},
+  aria: {label: "Submit form"}
+)
+```
+
+Renders:
+
+```html
+<button
+  class="rounded px-4 py-2 mt-4 bg-red-500 text-white"
+  data-id="submit-btn"
+  aria-label="Submit form">
+</button>
+```
+
+- `bg-red-500` from the caller replaced `bg-blue-500` from the component (same category).
+- `mt-4` was added (no margin in the base).
+- `rounded`, `px-4`, `py-2`, `text-white` retained from the base.
+- `data-id` and `aria-label` flow through to the DOM untouched.
+
+## Smart merge behavior
+
+Smart-merge handles Tailwind's conventions so caller and component CSS can coexist sensibly. In every row below, the **Component** column is what the component declared via `css`, and the **Caller** column is what was passed in `class:` at the call site.
+
+| Component | Caller | Final classes | Why |
+| --- | --- | --- | --- |
+| `bg-white` | `bg-blue-500` | `bg-blue-500` | Same category (background) — caller wins |
+| `p-4` | `p-8` | `p-8` | All-padding overrides all-padding |
+| `px-4` | `py-2` | `px-4 py-2` | Different spacing axes — both kept |
+| `p-4` | `pb-6` | `p-4 pb-6` | Specific side extends the all-side base |
+| `pl-2` | `px-5` | `px-5` | Broader axis (`x`) absorbs the narrower (`l`) |
+| `border-t` | `border-t-2` | `border-t-2` | Same side, more specific width — caller wins |
+| `border-2` | `border-red-600` | `border-2 border-red-600` | Width and color are independent |
+| `bg-white` | `hover:bg-blue-500` | `bg-white hover:bg-blue-500` | Modifier prefix is its own namespace |
+| `hover:bg-blue-500` | `hover:bg-red-500` | `hover:bg-red-500` | Caller wins within the modifier namespace |
+| `bg-white` | `data-[open]:bg-gray-100` | `bg-white data-[open]:bg-gray-100` | Arbitrary modifier is its own namespace |
+
+Modifier prefixes (`hover:`, `md:`, `dark:`, `group/`, `peer-checked:`, `aria-*`, arbitrary `[…]` values, etc.) form their own merge namespace, so `hover:bg-blue-500` never conflicts with a base `bg-white`.
+
+## Inheritance
+
+A child component's `css "..."` declaration is smart-merged with its parent's:
+
+```ruby
+class CardComponent < ApplicationComponent
+  css "rounded shadow p-4 bg-white"
+end
+
+class HighlightedCardComponent < CardComponent
+  css "bg-yellow-50 ring-2 ring-yellow-200"
+  # Final base CSS:
+  # "rounded shadow p-4 bg-yellow-50 ring-2 ring-yellow-200"
+end
+```
+
+Axis, method, and proc rules are appended, not overridden.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec standardrb
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/view_component_css_dsl/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ViewComponentCssDsl
+  VERSION = "0.1.0"
+end

data/lib/view_component_css_dsl.rb

@@ -0,0 +1,545 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/hash/except"
+require "active_support/core_ext/hash/slice"
+require "active_support/core_ext/object/inclusion"
+
+require_relative "view_component_css_dsl/version"
+
+module ViewComponentCssDsl
+  extend ActiveSupport::Concern
+
+  # HTML attributes auto-extracted from kwargs at construction time. Anything in
+  # this set is captured into @html_attrs instead of being passed to initialize,
+  # so callers can pass `class:`, `data:`, `aria:`, etc. without the component
+  # declaring them. To opt out, accept a kwarg with the same name in initialize
+  # (e.g. `def initialize(class:)`) or use a keyrest name other than html_attrs.
+  HTML_ATTR_KEYS = Set[
+    :alt, :aria, :autofocus,
+    :class, :colspan, :contenteditable,
+    :data, :dir, :disabled, :download, :draggable,
+    :enterkeyhint,
+    :formaction,
+    :headers, :hidden, :href,
+    :id, :inputmode,
+    :lang, :loading, :low,
+    :media,
+    :onclick, :open, :optimum,
+    :popover, :popovertarget, :popovertargetaction, :preload,
+    :readonly, :rel, :role, :rowspan,
+    :spellcheck, :src, :srcset, :style,
+    :tabindex, :target, :title, :type, :value
+  ].freeze
+
+  # Single combined regex for padding/margin spacing (replaces 14 separate patterns)
+  # Captures: type (p/m), axis (x/y/t/r/b/l or nil for all), value
+  SPACING_REGEX = /\b(p|m)(x|y|t|r|b|l)?-(\d+)\b/
+
+  # Maps axis character to Set of affected sides
+  SPACING_AXIS_MAP = {
+    nil => Set[:t, :r, :b, :l],  # p-4, m-4 = all sides
+    "x" => Set[:l, :r],
+    "y" => Set[:t, :b],
+    "t" => Set[:t],
+    "r" => Set[:r],
+    "b" => Set[:b],
+    "l" => Set[:l]
+  }.freeze
+
+  # Border width patterns (kept separate due to anchoring requirements)
+  BORDER_REGEX = /^border(?:-(x|y|t|r|b|l))?(?:-\d+)?$/
+
+  # Other category patterns (non-spacing, simple override by category)
+  # IMPORTANT: Use anchored patterns (^/$) to avoid matching substrings within
+  # compound classes (e.g., `h-8` within `min-h-8`, `flex` within `inline-flex`)
+  CATEGORIES = {
+    background: /^bg-/,
+    text_color: /^text-((\w+-\d+)|white|black|transparent|current|inherit|action|success|danger|warning|brand)(\/\d+)?$/,
+    text_size: /^text-(xs|sm|base|lg|xl|\d*xl)$/,
+    border_color: /^border-(?!t|r|b|l|x|y|\d)(\w+-\d+|\w+)(\/\d+)?$/,
+    width: /^w-/,
+    height: /^h-/,
+    min_width: /^min-w-/,
+    min_height: /^min-h-/,
+    max_width: /^max-w-/,
+    max_height: /^max-h-/,
+    # Display classes - note: `hidden` is intentionally excluded because it's
+    # commonly used as a visibility toggle alongside other display classes
+    # (e.g., "inline-flex hidden" where JS removes "hidden" to show element)
+    display: /^(block|inline-block|inline-flex|inline-grid|inline|flex|grid|table-cell|table-row|table|contents|flow-root|list-item)$/,
+    justify: /^justify-/,
+    align: /^items-/,
+    font_weight: /^font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)$/,
+    rounded: /^rounded(-none|-sm|-md|-lg|-xl|-2xl|-3xl|-full)?$/,
+    position: /^(static|relative|absolute|fixed|sticky)$/
+  }.freeze
+
+  # Known Tailwind modifiers (prefixes like hover:, md:, first:, etc.)
+  # Classes with different modifiers should NOT conflict with each other
+  KNOWN_MODIFIERS = Set[
+    # Responsive
+    "sm", "md", "lg", "xl", "2xl",
+    "max-sm", "max-md", "max-lg", "max-xl", "max-2xl",
+    # Interactive state
+    "hover", "focus", "focus-within", "focus-visible", "active", "visited", "target",
+    # Structural
+    "first", "last", "only", "odd", "even",
+    "first-of-type", "last-of-type", "only-of-type", "empty",
+    # Form state
+    "disabled", "enabled", "checked", "indeterminate", "default",
+    "required", "valid", "invalid", "in-range", "out-of-range",
+    "placeholder-shown", "autofill", "read-only",
+    # Pseudo-elements
+    "before", "after", "first-letter", "first-line",
+    "marker", "selection", "file", "backdrop", "placeholder",
+    # Media/Preference
+    "dark", "print", "portrait", "landscape",
+    "motion-safe", "motion-reduce", "contrast-more", "contrast-less",
+    "forced-colors",
+    # Direction
+    "rtl", "ltr",
+    # Attribute
+    "open",
+    # Direct children
+    "*"
+  ].freeze
+
+  # Patterns that match dynamic modifiers (with optional names/arbitrary values)
+  # These use flexible regex to match ANY valid Tailwind modifier syntax
+  MODIFIER_PATTERNS = [
+    /^group(?:\/\w+)?$/,                    # group, group/<any-name>
+    /^group-\w+(?:\/\w+)?$/,                # group-hover, group-<state>/<any-name>
+    /^peer(?:\/\w+)?$/,                     # peer, peer/<any-name>
+    /^peer-\w+(?:\/\w+)?$/,                 # peer-checked, peer-<state>/<any-name>
+    /^aria-\w+$/,                           # aria-checked, aria-<any-attr>
+    /^aria-\[.+\]$/,                        # aria-[<arbitrary>]
+    /^data-\[.+\]$/,                        # data-[<arbitrary>]
+    /^supports-\[.+\]$/,                    # supports-[<arbitrary>]
+    /^has-\[.+\]$/,                         # has-[<arbitrary>]
+    /^group-has-\[.+\]$/,                   # group-has-[<arbitrary>]
+    /^peer-has-\[.+\]$/,                    # peer-has-[<arbitrary>]
+    /^min-\[.+\]$/,                         # min-[<arbitrary>]
+    /^max-\[.+\]$/                          # max-[<arbitrary>]
+  ].freeze
+
+  included do
+    class_attribute :_css_base, instance_writer: false, default: ""
+    class_attribute :_css_axis_rules, instance_writer: false, default: []
+    class_attribute :_css_method_rules, instance_writer: false, default: []
+    class_attribute :_css_proc_rules, instance_writer: false, default: []
+    # Track which axis names are used in rules (for cache key generation)
+    class_attribute :_css_axis_names, instance_writer: false, default: Set.new
+    # Precomputed map of axis -> valid values for validation (built at class definition time)
+    class_attribute :_css_defined_axes, instance_writer: false, default: {}
+    # Lazy cache for precomputed base + axis CSS combinations
+    class_attribute :_css_cache, instance_writer: false, default: nil
+    # Memoization cache for smart_merge results (axis + method + proc combinations)
+    class_attribute :_css_merge_cache, instance_writer: false, default: nil
+  end
+
+  class_methods do
+    # Unified css class method supporting multiple patterns:
+    # - css "string"                           -> base CSS, always applied
+    # - css :method?, style: "string"          -> applied when method? returns truthy
+    # - css axis: :value, style: "string"      -> applied when @axis == :value
+    # - css axis: :val, other: :val, style: "string" -> applied when ALL axes match
+    # - css -> { dynamic_css }                 -> proc evaluated at render time
+    def css(*args, **options)
+      case args.first
+      when Proc
+        # Proc-based: css -> { "pl-#{@indent * 4}" }
+        self._css_proc_rules = _css_proc_rules.dup
+        _css_proc_rules << args.first
+        self._css_merge_cache = nil
+      when Symbol
+        # Method-based: css :disabled?, style: "opacity-50"
+        method_name = args.first
+        styles = options[:style]
+        raise ArgumentError, "css :#{method_name} requires style: keyword" unless styles
+
+        self._css_method_rules = _css_method_rules.dup
+        _css_method_rules << {method: method_name, styles: styles}
+        self._css_merge_cache = nil
+      when String
+        if options.empty?
+          # Base CSS: css "rounded p-4"
+          parent_base_css = superclass.respond_to?(:_css_base) ? superclass._css_base : ""
+          self._css_base = if parent_base_css.present?
+            smart_merge(parent_base_css, args.first)
+          else
+            args.first
+          end
+          # Invalidate caches when base changes
+          self._css_cache = nil
+          self._css_merge_cache = nil
+        else
+          raise ArgumentError, "css with String and options not supported. " \
+                               "Use: css variant: :name, style: \"classes\""
+        end
+      when nil
+        if (styles = options[:style])
+          # Axis-based: css variant: :primary, style: "bg-blue-500"
+          axes = options.except(:style)
+          self._css_axis_rules = _css_axis_rules.dup
+          _css_axis_rules << {axes:, styles:}
+          # Track axis names for cache key generation
+          self._css_axis_names = _css_axis_names.dup.merge(axes.keys)
+          # Precompute valid values per axis for validation
+          self._css_defined_axes = _css_defined_axes.transform_values(&:dup)
+          axes.each do |axis, value|
+            (_css_defined_axes[axis] ||= Set.new) << value
+          end
+          # Invalidate caches when rules change
+          self._css_cache = nil
+          self._css_merge_cache = nil
+        else
+          raise ArgumentError, "css requires style: when using axis conditions"
+        end
+      else
+        raise ArgumentError, "Unknown css argument type: #{args.first.class}"
+      end
+    end
+
+    # Override `new` to auto-extract HTML attributes from kwargs into @html_attrs,
+    # so components don't need to declare **html_attrs in their initialize signature.
+    # Anything in HTML_ATTR_KEYS that wasn't declared as a kwarg is captured.
+    def new(*args, **kwargs, &block)
+      info = initialize_params_info
+      html_attrs = {}
+      if info[:uses_html_attrs_keyrest]
+        extractable = HTML_ATTR_KEYS.intersection(kwargs.keys) - info[:declared_kwargs]
+        html_attrs = kwargs.extract!(*extractable)
+      end
+
+      instance = allocate
+      instance.instance_variable_set(:@html_attrs, html_attrs)
+      instance.send(:initialize, *args, **kwargs, &block)
+
+      # Merge with any @html_attrs the component set inside initialize (older
+      # components that still declare **html_attrs). Caller-provided values win.
+      existing = instance.instance_variable_get(:@html_attrs) || {}
+      instance.instance_variable_set(:@html_attrs, existing.merge(html_attrs))
+      instance
+    end
+
+    # Analyzes the initialize signature once and caches the result. Auto-extraction
+    # happens unless the component declares a non-html_attrs keyrest (like **options),
+    # in which case the component wants to receive everything itself.
+    def initialize_params_info
+      @initialize_params_info ||= begin
+        declared_kwargs = Set.new
+        keyrest_name = nil
+        instance_method(:initialize).parameters.each do |type, name|
+          case type
+          when :key, :keyreq then declared_kwargs << name
+          when :keyrest then keyrest_name = name
+          end
+        end
+        uses_html_attrs_keyrest = keyrest_name.nil? || keyrest_name == :html_attrs
+        {declared_kwargs:, uses_html_attrs_keyrest:}
+      end
+    end
+
+    # Overwrites base css with custom css from the caller, but only if they actually
+    # interfere with each other. Modifier prefixes (hover:, md:, first:, etc.) create
+    # separate "namespaces" so they don't conflict with base classes.
+    # Examples:
+    # - base: "pt-2", custom: "pt-4", result => "pt-4"
+    # - base: "pb-2", custom: "pt-4", result => "pb-2 pt-4"
+    # - base: "pb-2", custom: "p-4", result => "p-4"
+    # - base: "block", custom: "first:hidden", result => "block first:hidden"
+    def smart_merge(*css_strings)
+      categorized = {}
+      uncategorized = []
+      # Store spacing classes grouped by modifier prefix
+      # {prefix => [{class: "p-4", info: {type: :padding, axes: Set[:t,:r,:b,:l]}}, ...]}
+      spacing_by_prefix = Hash.new { |h, k| h[k] = [] }
+
+      css_strings.compact.each do |str|
+        str.to_s.split.each do |cls|
+          prefix, base_class = extract_modifier_prefix(cls)
+
+          spacing = spacing_info(base_class)
+          if spacing
+            # Remove any existing spacing classes that overlap on same type and axes
+            # within the same modifier prefix
+            spacing_by_prefix[prefix].reject! do |existing|
+              existing[:info][:type] == spacing[:type] &&
+                existing[:info][:axes].subset?(spacing[:axes])
+            end
+            spacing_by_prefix[prefix] << {class: cls, info: spacing}
+          else
+            category = detect_category(base_class)
+            if category
+              key = "#{prefix}:#{category}"
+              categorized[key] = cls
+            else
+              uncategorized << cls unless uncategorized.include?(cls)
+            end
+          end
+        end
+      end
+
+      spacing_classes = spacing_by_prefix.values.flatten.map { |s| s[:class] }
+      (uncategorized + spacing_classes + categorized.values).join(" ")
+    end
+
+    def spacing_info(css_class)
+      # Check padding/margin with single regex (replaces 14 pattern checks)
+      if (match = css_class.match(SPACING_REGEX))
+        type = (match[1] == "p") ? :padding : :margin
+        axes = SPACING_AXIS_MAP[match[2]]
+        return {type:, axes:}
+      end
+
+      # Check border width (needs separate handling due to anchoring)
+      if (match = css_class.match(BORDER_REGEX))
+        axes = SPACING_AXIS_MAP[match[1]]
+        return {type: :border, axes:}
+      end
+
+      nil
+    end
+
+    def detect_category(css_class)
+      CATEGORIES.find { |_name, pattern| css_class.match?(pattern) }&.first
+    end
+
+    # Extracts the modifier prefix from a Tailwind class
+    # e.g., "md:hover:bg-blue-500" → ["md:hover", "bg-blue-500"]
+    # e.g., "bg-white" → ["", "bg-white"]
+    def extract_modifier_prefix(css_class)
+      # Fast path: most classes don't have modifiers
+      return ["", css_class] unless css_class.include?(":")
+
+      parts = css_class.split(":")
+      return ["", css_class] if parts.size == 1
+
+      # Find where modifiers end and the actual class begins
+      modifier_parts = []
+      parts.each_with_index do |part, i|
+        if known_modifier?(part) && i < parts.size - 1
+          modifier_parts << part
+        else
+          base_class = parts[i..].join(":")
+          return [modifier_parts.join(":"), base_class]
+        end
+      end
+
+      # Fallback (shouldn't reach here)
+      ["", css_class]
+    end
+
+    def known_modifier?(str)
+      return true if KNOWN_MODIFIERS.include?(str)
+      MODIFIER_PATTERNS.any? { |pattern| str.match?(pattern) }
+    end
+  end
+
+  # Instance method: generates final CSS string
+  def css
+    build_classes
+  end
+
+  # Returns caller's custom classes from html_attrs
+  def custom_css
+    return "" unless @html_attrs
+
+    @html_attrs.fetch(:class, "")
+  end
+
+  # Returns the hash to splat onto the top-level element of a component template:
+  #
+  #   <%= tag.div **html_attrs do %> ... <% end %>
+  #
+  # Includes the smart-merged `:class`, merged `:data` and `:aria` (from any
+  # component-defined defaults + caller overrides), and every other caller-passed
+  # HTML attribute (`id:`, `role:`, etc.) forwarded to the rendered element.
+  def html_attrs
+    return {} unless @html_attrs
+
+    result = @html_attrs.except(:aria, :class, :data)
+
+    # Only include aria/data if they have content, otherwise they'd override
+    # inline attrs in templates like: tag.div data: {foo: "bar"}, **html_attrs
+    aria = final_aria_attrs
+    data = final_data_attrs
+    result[:aria] = aria if aria.present?
+    result[:data] = data if data.present?
+
+    css_value = css
+    result[:class] = css_value if css_value.present?
+    result
+  end
+
+  # Overwrite in component subclass to set default data-attrs. They will be merged
+  # into html_attrs.
+  #
+  # Example:
+  #
+  # def data_attrs
+  #   {
+  #     controller: "some-stimulus-controller",
+  #     action: "click->some-stimulus-controller#someAction",
+  #     active: active?
+  #   }
+  # end
+  #
+  def data_attrs
+    {}
+  end
+
+  DATA_MERGE_KEYS = %i[controller action].freeze
+
+  # Loop through data-attrs and merge values from DATA_MERGE_KEYS. Overwrite any
+  # others.
+  #
+  # Ensures the caller doesn't wipe out e.g. data-controller or data-action values
+  # defined by the dev in #data_attrs
+  #
+  # Example:
+  #
+  # Assuming MyComponent with #data_attrs defined as:
+  #
+  # def data_attrs
+  #   {
+  #     controller: "foo",
+  #     label: "Hello world"
+  #   }
+  # end
+  #
+  # MyComponent.new(data: {controller: "bar", label: "Goodbye"})
+  #
+  # Will output the following data-attrs:
+  #
+  # <div data-controller="foo bar" data-label="Goodbye">
+  #
+  # Notice:
+  # - data-controller from the caller is set alongside "foo" instead of overwriting
+  # - In contrast, data-label from the caller overwrites the default
+  #
+  def final_data_attrs
+    incoming_data = @html_attrs.fetch(:data, {})
+    incoming_data.each_with_object(data_attrs) do |(key, value), final_data|
+      final_value = if key.in?(DATA_MERGE_KEYS)
+        [data_attrs[key], value].compact.join(" ")
+      else
+        value
+      end
+
+      final_data[key] = final_value
+    end
+  end
+
+  # Overwrite in subclass to define default aria-attrs
+  def aria_attrs
+    {}
+  end
+
+  # Using merge allows for default value #aria_attrs, but also for dev to override
+  # that value per-instance as needed
+  def final_aria_attrs
+    aria_attrs.merge(@html_attrs.fetch(:aria, {}))
+  end
+
+  private
+
+  def build_classes
+    validate_axes!
+
+    # Get cached base + axis CSS (computed once per axis combination)
+    base_with_axes = cached_base_axis_css
+
+    # Check for dynamic elements that require runtime smart_merge
+    method_css = collect_matching_method_css
+    proc_css = collect_proc_css
+    custom = custom_css
+
+    # Fast path: no dynamic elements, return cached result directly
+    if method_css.blank? && proc_css.blank? && custom.blank?
+      return base_with_axes
+    end
+
+    # Memoize smart_merge results when no custom CSS (bounded cache)
+    # Custom CSS from callers would create unbounded cache entries
+    if custom.blank?
+      cache = self.class._css_merge_cache ||= {}
+      cache_key = [current_axis_key, method_css, proc_css].join("|")
+      return cache[cache_key] ||= self.class.smart_merge(base_with_axes, method_css, proc_css)
+    end
+
+    # Custom CSS present - can't memoize, run full smart_merge
+    self.class.smart_merge(base_with_axes, method_css, proc_css, custom)
+  end
+
+  # Returns cached CSS for base + current axis values
+  # Lazy-computes and caches on first access for each axis combination
+  def cached_base_axis_css
+    cache = self.class._css_cache ||= {}
+    axis_key = current_axis_key
+
+    cache[axis_key] ||= compute_base_axis_css
+  end
+
+  # Builds a cache key from current axis instance variable values
+  def current_axis_key
+    self.class._css_axis_names.map { |name| instance_variable_get(:"@#{name}") }
+  end
+
+  # Computes smart_merge of base + matching axis rules (no caching)
+  def compute_base_axis_css
+    base = self.class._css_base
+    axis_css = collect_matching_axis_css
+    return base if axis_css.blank?
+
+    self.class.smart_merge(base, axis_css)
+  end
+
+  def collect_matching_axis_css
+    self.class._css_axis_rules.filter_map do |rule|
+      matches = rule[:axes].all? do |axis, expected_value|
+        actual = instance_variable_get(:"@#{axis}")
+        actual == expected_value
+      end
+      rule[:styles] if matches
+    end.join(" ")
+  end
+
+  def validate_axes!
+    defined_axes = self.class._css_defined_axes
+    return if defined_axes.empty?
+
+    # Check each axis has a matching rule for its current value
+    defined_axes.each do |axis, valid_values|
+      current = instance_variable_get(:"@#{axis}")
+      next if current.nil? # Axis not set, skip validation
+
+      unless valid_values.include?(current)
+        valid_list = valid_values.map { |v| ":#{v}" }.join(", ")
+        raise ArgumentError,
+          "Unknown #{axis} :#{current} for #{self.class.name}. Valid values: #{valid_list}"
+      end
+    end
+  end
+
+  def collect_matching_method_css
+    self.class._css_method_rules.filter_map do |rule|
+      method_name = rule[:method]
+      unless respond_to?(method_name, true)
+        raise NoMethodError,
+          "ViewComponentCssDsl method rule references undefined method `#{method_name}` in #{self.class.name}"
+      end
+      result = send(method_name)
+      rule[:styles] if result
+    end.join(" ")
+  end
+
+  def collect_proc_css
+    self.class._css_proc_rules.filter_map do |proc|
+      instance_exec(&proc)
+    end.join(" ")
+  end
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: view_component_css_dsl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeff Lange
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  A small concern you mix into your base ViewComponent class to declare
+  base styles, variants, and conditional CSS classes declaratively.
+  Smart-merges Tailwind utility classes (spacing, modifier prefixes,
+  arbitrary values) so callers can safely override per-instance styles.
+email:
+- jeff.lange@sofwarellc.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/view_component_css_dsl.rb
+- lib/view_component_css_dsl/version.rb
+homepage: https://github.com/SOFware/view_component_css_dsl
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/SOFware/view_component_css_dsl
+  changelog_uri: https://github.com/SOFware/view_component_css_dsl/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Declarative CSS class DSL for ViewComponent + Tailwind
+test_files: []