view_component_css_dsl 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eba29c79b834ffc0651fc3ff6b244e860de04218b6b29ca31df90634211fc6a6
-  data.tar.gz: fb7183fa91dc0bb773d61dc0953df0cf17fed601d39609cc1b2e2d44da725f51
+  metadata.gz: 494769078a576e9a1f7d3be9b2819ed2c93bf148da58154c68356c01410d9e8f
+  data.tar.gz: 529f35969651591c73f2c21012ab828c84305f94df5317f612fc4dc13b75cc39
 SHA512:
-  metadata.gz: d28bfc76e89df1e4899fa396f0d45be296bbef32bed288d4893f908ad9038f28bc3f3e444675acf1408e01859f2cd6b007cb4fc346bad8389377765768952ff9
-  data.tar.gz: 9353657fc812e95881ec400152852886d05f2292f978d590dc0475abb64cb87dfe61ba38c1cde972d8c2c6f22eb74d0e88bd2f2c632455d1caa5d368f6d230e4
+  metadata.gz: 365ce4701b070176cfda8d7a7dcb8005011326d3b888315ce0d37ba80cd2026bc8b5e3dcf8833747911e1ad5e5ca4d752ec28cf6dfa6b058240b847950bd1ca3
+  data.tar.gz: fc2ff970cc016c1fe8c788c622af0894c8d0c701afa9861fc40bc34c7926c3d2c19912c3d51287cf43da6d68c826fb4f4163e75ccb1714b874fb7c0621ff48ac

data/CHANGELOG.md

@@ -2,15 +2,18 @@
 
 
 
-## [0.1.2] - 2026-05-15
+## [0.1.4] - 2026-06-04
 
 ### Added
 
-- data, aria, and attribute DSL declarators for first-class HTML attribute declarations (cf37050)
+- ViewComponentCssDsl::Verifier — six static checks for component declarations: Tailwind class validity (via a compiled-CSS oracle), self-conflicting declarations, method-rule resolution, axis settability, variant-matrix smoke, and template html_attrs splat coverage (4be2024)
 
-## [0.1.1] - 2026-05-15
+## [0.1.3] - 2026-05-18
 
 ### Changed
 
-- `view_component` dependency pinned to `~> 4.0` (was `>= 4.0`) — RubyGems-recommended SemVer-aware constraint
-- Minimum Ruby version raised to 3.2 (was 3.1), matching the floor for `view_component >= 4.0`
+- `smart_merge` now delegates to the `tailwind_merge` gem. The public API is unchanged, but conflict resolution now matches upstream tailwind-merge semantics across every Tailwind utility group (previously only spacing, sizing, colors, display, justify, align, font-weight, rounded, and position were handled — shadow, ring, gap, space, divide, z, opacity, leading, tracking, transition, transform, blur, etc. now merge correctly too).
+
+### Breaking
+
+- `hidden` is now treated as part of the display-class conflict group. Strings like `"flex hidden"` collapse to `"hidden"` rather than keeping both. Previous behavior was non-standard — `tailwind-merge` (JS) and `tailwind_merge` (Ruby) have always treated `hidden` as a display utility. For JS-toggle visibility patterns, use the HTML5 `hidden` attribute (e.g., `attribute hidden: -> { … }` or pass `hidden: true` as an html_attr) and toggle it with `element.toggleAttribute('hidden')` instead of relying on the class merger.

data/README.md

@@ -47,6 +47,10 @@ class ButtonComponent < ViewComponent::Base
     when :danger  then "bg-red-500 text-white"
     end
   end
+
+  def data_attrs
+    {variant: @variant, controller: "button-component"}
+  end
 end
 ```
 
@@ -59,6 +63,8 @@ class ButtonComponent < ApplicationComponent
   css variant: :danger,  style: "bg-red-500 text-white"
   css :disabled?,        style: "opacity-50"
 
+  data variant: :variant, controller: "button-component"
+
   def initialize(variant: :primary, disabled: false)
     @variant = variant
     @disabled = disabled
@@ -66,6 +72,7 @@ class ButtonComponent < ApplicationComponent
 
   private
 
+  attr_reader :variant
   def disabled? = @disabled
 end
 ```
@@ -73,6 +80,7 @@ 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.
+- Data attributes get the same declarative treatment — see [Declaring data, aria, and HTML attributes](#declaring-data-aria-and-html-attributes) below for the full pattern.
 
 ## Philosophy
 
@@ -402,7 +410,7 @@ Renders:
 
 ## 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.
+Smart-merge handles Tailwind's conventions so caller and component CSS can coexist sensibly. Under the hood it delegates to the [`tailwind_merge`](https://github.com/gjtorikian/tailwind_merge) gem, which mirrors [tailwind-merge](https://github.com/dcastil/tailwind-merge) (JS) semantics. 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 |
 | --- | --- | --- | --- |
@@ -419,6 +427,19 @@ Smart-merge handles Tailwind's conventions so caller and component CSS can coexi
 
 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`.
 
+### JS-toggle visibility — use the `hidden` attribute, not the class
+
+`hidden` is treated as part of the display group, so `"flex hidden"` collapses to `"hidden"` (the same as upstream tailwind-merge). If you need to toggle visibility from JavaScript while preserving a base display class, use the HTML5 `hidden` attribute via the `attribute` DSL:
+
+```ruby
+class PaneComponent < ApplicationComponent
+  css "block"
+  attribute hidden: -> { collapsed? }
+end
+```
+
+Then toggle from JS with `element.toggleAttribute('hidden')` or `element.hidden = true/false`. The class merger stays out of the way and the element retains its `block`/`flex`/etc. layout when shown.
+
 ## Inheritance
 
 A child component's `css "..."` declaration is smart-merged with its parent's:
@@ -437,6 +458,119 @@ end
 
 Axis, method, and proc rules are appended, not overridden.
 
+## Verifier
+
+The DSL's worst failure modes are silent: a typo'd or hallucinated Tailwind class produces no CSS at all under JIT, a self-conflicting declaration quietly drops a class, and a rule referencing a missing method only raises at render time on the code path that hits it. `ViewComponentCssDsl::Verifier` catches all of these statically — fast enough to run on every edit.
+
+`verify(component)` returns `Finding` structs (`component`, `check`, `severity`, `message`). Six checks run:
+
+| Check | Asserts | Catches |
+| --- | --- | --- |
+| `class_validity` | Every declared class exists in the compiled Tailwind output | Typos, hallucinated classes, theme values that don't exist |
+| `self_conflicts` | No declaration conflicts with itself | `css "block flex"` silently dropping `block` |
+| `method_rules` | Every Symbol in `css`/`data`/`aria`/`attribute` rules resolves to a method | Render-time `NoMethodError`s |
+| `axes_settable` | Every axis has an initialize param or `@ivar` assignment | Variant rules that can never fire |
+| `variant_matrix` | `#css` builds cleanly for every axis-value combination | Anything the static checks miss, without rendering |
+| `template_splat` | Every template references `html_attrs` | Components whose DSL output never reaches the DOM |
+
+Notes:
+
+- **Verify every class in the hierarchy**, abstract bases included. Declaration checks only inspect what each class itself declared, so a parent's mistakes are reported once — on the parent.
+- `known_classes:` is anything responding to `include?(String)`. `CompiledCssOracle` parses class selectors out of a compiled Tailwind build; since Tailwind's JIT generates a rule for every valid class found in your content globs, a declared class missing from the output is invalid. Rebuild before verifying — the oracle is only as fresh as the build. Omit `known_classes:` to skip the check.
+- `template_splat` covers sidecar files, inline templates (`erb_template "..."`), and hand-written `#call` methods.
+- The variant matrix smoke-tests on bare (`allocate`d) instances. Method and proc rules that need `initialize` state report as warnings rather than errors.
+
+### Wiring it into your app
+
+Three layers, from "can't forget" to "instant feedback". The spec is the only one you need — it makes violations fail CI with no one having to remember anything. The other two make the feedback faster.
+
+#### 1. A spec — the floor
+
+Add this once and every component, present and future, is verified on every test run. `descendants` discovers components dynamically, so new ones are covered the day they're written:
+
+```ruby
+# spec/components/css_dsl_verification_spec.rb
+require "rails_helper"
+require "view_component_css_dsl/verifier"
+
+RSpec.describe "CssDsl verification" do
+  it "has no verifier errors in any component" do
+    Rails.application.eager_load!
+
+    oracle = ViewComponentCssDsl::Verifier::CompiledCssOracle.new(
+      Rails.root.join("app/assets/builds/tailwind.css")
+    )
+    verifier = ViewComponentCssDsl::Verifier.new(known_classes: oracle)
+    findings = ApplicationComponent.descendants.flat_map { |c| verifier.verify(c) }
+
+    errors = findings.select(&:error?)
+    expect(errors).to be_empty, errors.join("\n")
+  end
+end
+```
+
+Point the oracle at your compiled Tailwind output and make sure your CI builds it before running specs.
+
+#### 2. `bin/verify-css-dsl` — the edit loop
+
+Verifies just the components you're working on (or everything, with no args) without waiting for the suite:
+
+```ruby
+#!/usr/bin/env ruby
+# Usage: bin/verify-css-dsl [path/to/component.rb ...]
+# With no args, verifies every component.
+
+require_relative "../config/environment"
+require "view_component_css_dsl/verifier"
+
+Rails.application.eager_load!
+
+components = if ARGV.any?
+  components_root = Rails.root.join("app/components")
+  ARGV.map do |path|
+    rel = Pathname.new(path).expand_path.relative_path_from(components_root)
+    rel.to_s.delete_suffix(".rb").camelize.constantize
+  end
+else
+  ApplicationComponent.descendants
+end
+
+oracle = ViewComponentCssDsl::Verifier::CompiledCssOracle.new(
+  Rails.root.join("app/assets/builds/tailwind.css")
+)
+verifier = ViewComponentCssDsl::Verifier.new(known_classes: oracle)
+
+findings = components.flat_map { |component| verifier.verify(component) }
+puts findings
+exit 1 if findings.any?(&:error?)
+```
+
+Make it executable with `chmod +x bin/verify-css-dsl`.
+
+#### 3. A Claude Code hook — the agent loop
+
+Runs the bin script automatically after Claude Code edits a component file and feeds any findings straight back to the model, so a hallucinated class is flagged the moment it's written rather than when the suite runs. In your project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=$(jq -r .tool_input.file_path); case \"$f\" in */app/components/*.rb) bin/verify-css-dsl \"$f\" >&2 || exit 2;; esac"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Exit code 2 returns the findings to Claude as feedback to act on; clean edits stay silent. Note the hook boots your Rails app on each component edit — if that's slow, bootsnap helps.
+
 ## Development
 
 ```sh

data/lib/view_component_css_dsl/verifier/compiled_css_oracle.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../verifier"
+
+# The class-validity oracle for Verifier, built from a compiled Tailwind CSS file.
+# Tailwind's JIT generates a rule for every valid class it finds in your content
+# globs — so as long as your component .rb files are in those globs, the compiled
+# output contains exactly the valid classes among those you declared. A declared
+# class missing from the output is a typo, a hallucination, or a value your theme
+# doesn't define.
+#
+#   oracle = ViewComponentCssDsl::Verifier::CompiledCssOracle.new(
+#     "app/assets/builds/tailwind.css"
+#   )
+#   oracle.include?("bg-blue-500")  # => true
+#   oracle.include?("bg-blurple")   # => false
+#
+# Caveat: the oracle is only as fresh as the build. Rebuild Tailwind before
+# verifying, or a just-added valid class will be flagged as unknown.
+class ViewComponentCssDsl::Verifier::CompiledCssOracle
+  # Class selector: a dot, then word chars / hyphens / CSS escapes. Tailwind
+  # escapes special chars with a backslash (`.hover\:bg-blue-500`) and leading
+  # digits as hex (`.\32 xl\:grid`).
+  CLASS_SELECTOR = /\.((?:\\[0-9a-fA-F]{1,6}\s?|\\.|[\w-])+)/
+
+  def initialize(css_path)
+    @classes = parse(File.read(css_path))
+  end
+
+  def include?(class_name) = @classes.include?(class_name)
+
+  def size = @classes.size
+
+  private
+
+  def parse(css)
+    css.scan(CLASS_SELECTOR).map { |(selector)| unescape(selector) }.to_set
+  end
+
+  # Hex escapes first (`\32 ` -> "2"), then simple escapes (`\:` -> ":").
+  def unescape(selector)
+    selector
+      .gsub(/\\([0-9a-fA-F]{1,6})\s?/) { $1.hex.chr(Encoding::UTF_8) }
+      .gsub(/\\(.)/, '\1')
+  end
+end

data/lib/view_component_css_dsl/verifier.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require "view_component_css_dsl"
+
+# Static checks over a component's DSL declarations. Catches the mistakes the DSL
+# itself can't surface until render time (or surfaces silently). Designed to be
+# fast enough to run on every edit.
+#
+# The six checks:
+#
+#   class_validity  - every declared class exists in the compiled Tailwind output;
+#                     catches typos, hallucinated classes, and theme values that
+#                     don't exist (requires known_classes:)
+#   self_conflicts  - no declaration conflicts with itself; catches e.g.
+#                     css "block flex" silently dropping "block"
+#   method_rules    - every Symbol in css/data/aria/attribute rules resolves to a
+#                     method; catches render-time NoMethodErrors
+#   axes_settable   - every axis has an initialize param or @ivar assignment;
+#                     catches variant rules that can never fire
+#   variant_matrix  - #css builds cleanly for every axis-value combination;
+#                     smoke-catches anything the static checks miss, no rendering
+#   template_splat  - every template (sidecar, inline erb_template, or manual
+#                     #call) references html_attrs; catches components whose DSL
+#                     output never reaches the DOM
+#
+#   verifier = ViewComponentCssDsl::Verifier.new(known_classes: oracle)
+#   findings = verifier.verify(ButtonComponent)
+#
+# Verify every class in the component hierarchy: declaration-shape checks
+# (class validity, self-conflicts) only inspect declarations the class itself
+# added, so a parent's declarations are checked on the parent, not re-reported
+# on every child.
+class ViewComponentCssDsl::Verifier
+  Finding = Struct.new(
+    :component, :check, :severity, :message, keyword_init: true
+  ) do
+    def to_s
+      "#{component.name || component.inspect} [#{check}] #{severity}: #{message}"
+    end
+
+    def error? = severity == :error
+  end
+
+  TEMPLATE_EXTENSIONS = %w[erb haml slim].freeze
+
+  # Safety cap for pathological axis cartesian products.
+  VARIANT_MATRIX_CAP = 256
+
+  # Source file of the DSL itself, for classifying smoke-test backtraces.
+  DSL_SOURCE_FILE = File.expand_path("../view_component_css_dsl.rb", __dir__)
+
+  # known_classes: anything responding to include?(String) — a Set, or a
+  # CompiledCssOracle built from your app's compiled Tailwind output. When nil,
+  # the class-validity check is skipped.
+  def initialize(known_classes: nil)
+    @known_classes = known_classes
+  end
+
+  def verify(component)
+    check_class_validity(component) +
+      check_self_conflicts(component) +
+      check_method_rules(component) +
+      check_axes_settable(component) +
+      check_variant_matrix(component) +
+      check_template_splat(component)
+  end
+
+  private
+
+  # Every statically-declared class must exist in the known-classes oracle.
+  # Hallucinated or typo'd classes produce no CSS at all under Tailwind's JIT —
+  # no error, no warning — so this is the check that catches them.
+  def check_class_validity(component)
+    return [] unless @known_classes
+
+    own_declared_styles(component).flat_map do |label, styles|
+      styles.split.reject { |cls| @known_classes.include?(cls) }.map do |cls|
+        finding(component, :class_validity, :error,
+          "#{label}: unknown class \"#{cls}\" (not in the compiled Tailwind output)")
+      end
+    end
+  end
+
+  # A single declaration whose classes conflict with each other (e.g. "block flex")
+  # is almost always a mistake — smart_merge silently keeps only the last.
+  def check_self_conflicts(component)
+    own_declared_styles(component).flat_map do |label, styles|
+      tokens = styles.split
+      survivors = component.smart_merge(styles).split
+      results = []
+
+      duplicates = tokens.tally.select { |_cls, count| count > 1 }.keys
+      if duplicates.any?
+        results << finding(component, :self_conflicts, :error,
+          "#{label}: duplicate class(es) #{quote_list(duplicates)}")
+      end
+
+      dropped = tokens.uniq - survivors
+      if dropped.any?
+        results << finding(component, :self_conflicts, :error,
+          "#{label}: #{quote_list(dropped)} conflict with later classes in the " \
+          "same declaration and would be silently dropped")
+      end
+
+      results
+    end
+  end
+
+  # Symbols in css/data/aria/attribute rules are method references; each must
+  # resolve on the component. The DSL only raises for these at render time.
+  def check_method_rules(component)
+    method_references(component).filter_map do |label, method_name|
+      next if resolves?(component, method_name)
+
+      finding(component, :method_rules, :error,
+        "#{label} references undefined method `#{method_name}`")
+    end
+  end
+
+  # Each axis with css rules must be settable: an initialize param of the same
+  # name, or an @ivar assignment somewhere in the component's source. An axis
+  # nothing sets means its rules can never fire.
+  def check_axes_settable(component)
+    component._css_defined_axes.keys.filter_map do |axis|
+      next if initialize_param?(component, axis)
+      next if ivar_assigned_in_source?(component, axis)
+
+      finding(component, :axes_settable, :error,
+        "axis :#{axis} has css rules, but initialize has no #{axis} param and " \
+        "no @#{axis} assignment was found")
+    end
+  end
+
+  # Smoke test: build the css string for every combination of axis values
+  # (including unset) on a bare instance. Exercises validate_axes!, the merge
+  # caches, and method/proc rules end-to-end without rendering.
+  def check_variant_matrix(component)
+    combos = axis_combinations(component)
+    findings = []
+
+    if combos.size > VARIANT_MATRIX_CAP
+      findings << finding(component, :variant_matrix, :warning,
+        "#{combos.size} axis combinations; only the first #{VARIANT_MATRIX_CAP} " \
+        "were smoke-tested")
+      combos = combos.first(VARIANT_MATRIX_CAP)
+    end
+
+    combos.each do |combo|
+      error = smoke_css(component, combo)
+      next unless error
+
+      findings << finding(component, :variant_matrix, smoke_severity(error),
+        "#{combo_label(combo)}: #{error.class}: #{error.message}")
+    end
+
+    findings
+  end
+
+  # Every template must reference html_attrs — that splat is what carries the
+  # DSL's classes and attributes to the DOM. Covers sidecar files, inline
+  # templates (erb_template "..."), and hand-written #call methods.
+  def check_template_splat(component)
+    sources = template_sources(component)
+    if sources.empty?
+      return [finding(component, :template_splat, :warning,
+        "no template found (no sidecar file, inline template, or #call method)")]
+    end
+
+    sources.filter_map do |label, source|
+      next if source.match?(/\bhtml_attrs\b/)
+
+      finding(component, :template_splat, :error,
+        "#{label} does not reference html_attrs; DSL classes and attributes " \
+        "will not reach the DOM")
+    end
+  end
+
+  ##################################################################################
+  # Declaration collection
+  ##################################################################################
+
+  # [label, styles] pairs for declarations this class itself added. Inherited
+  # declarations are checked on the ancestor that declared them.
+  def own_declared_styles(component)
+    parent = component.superclass
+    base = own_rules(component, parent, :_css_base_declarations)
+      .map { |styles| ["css \"#{styles}\"", styles] }
+    axis = own_rules(component, parent, :_css_axis_rules)
+      .map { |rule| [axis_label(rule[:axes]), rule[:styles]] }
+    methods = own_rules(component, parent, :_css_method_rules)
+      .map { |rule| ["css :#{rule[:method]}", rule[:styles]] }
+    base + axis + methods
+  end
+
+  def own_rules(component, parent, attr)
+    inherited = parent.respond_to?(attr) ? parent.public_send(attr) : []
+    component.public_send(attr) - inherited
+  end
+
+  def axis_label(axes) = "css #{axes.map { |k, v| "#{k}: :#{v}" }.join(", ")}"
+
+  # [label, method_name] for every Symbol the rules will send to the instance.
+  # Inherited rules are included: they run on this class, so they must resolve
+  # on this class (a child may legitimately define the method a parent's rule
+  # references).
+  def method_references(component)
+    refs = component._css_method_rules
+      .map { |rule| ["css :#{rule[:method]}", rule[:method]] }
+
+    {data: :_data_rules, aria: :_aria_rules, attribute: :_attribute_rules}
+      .each do |namespace, attr|
+        component.public_send(attr).each do |rule|
+          if rule[:predicate].is_a?(Symbol)
+            refs << ["#{namespace} :#{rule[:predicate]} predicate", rule[:predicate]]
+          end
+          rule[:attrs].each do |key, value|
+            refs << ["#{namespace} #{key}: :#{value}", value] if value.is_a?(Symbol)
+          end
+        end
+      end
+
+    refs
+  end
+
+  def resolves?(component, method_name)
+    component.method_defined?(method_name) ||
+      component.private_method_defined?(method_name)
+  end
+
+  ##################################################################################
+  # Axis settability
+  ##################################################################################
+
+  def initialize_param?(component, axis)
+    params = component.instance_method(:initialize).parameters
+    params.any? { |_type, name| name == axis }
+  end
+
+  def ivar_assigned_in_source?(component, axis)
+    source_paths(component).any? do |path|
+      File.read(path).match?(/@#{axis}\b\s*(\|\|)?=[^=~]/)
+    end
+  end
+
+  # Source files of the component and its DSL-including ancestors. Stops before
+  # ViewComponent::Base — framework internals aren't where axes get assigned.
+  def source_paths(component)
+    component.ancestors
+      .take_while { |mod| !view_component_base?(mod) }
+      .filter_map { |mod| mod.identifier if mod.respond_to?(:identifier) }
+      .uniq
+      .select { |path| File.exist?(path) }
+  end
+
+  def view_component_base?(mod)
+    defined?(ViewComponent::Base) && mod == ViewComponent::Base
+  end
+
+  ##################################################################################
+  # Variant matrix
+  ##################################################################################
+
+  # Cartesian product over defined axes, each axis taking every declared value
+  # plus nil (axis unset). [{}] when no axes — base/method/proc paths still get
+  # one smoke run.
+  def axis_combinations(component)
+    component._css_defined_axes.reduce([{}]) do |combos, (axis, values)|
+      combos.flat_map do |combo|
+        (values.to_a + [nil]).map { |value| combo.merge(axis => value) }
+      end
+    end
+  end
+
+  def smoke_css(component, combo)
+    instance = component.allocate
+    instance.instance_variable_set(:@html_attrs, {})
+    combo.each { |axis, value| instance.instance_variable_set(:"@#{axis}", value) }
+    instance.css
+    nil
+  rescue => error
+    error
+  end
+
+  # Errors raised inside the DSL are real failures. Errors raised in component
+  # code usually mean a method/proc rule needs initialize state a bare instance
+  # doesn't have — report those as warnings, not failures.
+  def smoke_severity(error)
+    first_frame = error.backtrace&.first.to_s
+    first_frame.start_with?("#{DSL_SOURCE_FILE}:") ? :error : :warning
+  end
+
+  def combo_label(combo)
+    return "with no axes set" if combo.compact.empty?
+
+    "with #{combo.compact.map { |axis, value| "#{axis}: :#{value}" }.join(", ")}"
+  end
+
+  ##################################################################################
+  # Templates
+  ##################################################################################
+
+  def template_sources(component)
+    sources = []
+
+    if component.respond_to?(:__vc_inline_template)
+      inline = component.__vc_inline_template
+      sources << ["inline template", inline.source] if inline
+    end
+
+    if component.respond_to?(:sidecar_files)
+      component.sidecar_files(TEMPLATE_EXTENSIONS).each do |path|
+        sources << [File.basename(path), File.read(path)]
+      end
+    end
+
+    if sources.empty? && (call_path = manual_call_path(component))
+      sources << ["#call (#{File.basename(call_path)})", File.read(call_path)]
+    end
+
+    sources
+  end
+
+  # Path of a hand-written #call, if the component (or a DSL ancestor) defines
+  # one. ViewComponent compiles templates into #call too, but only at render
+  # time — run the verifier in a fresh process and only manual ones exist.
+  def manual_call_path(component)
+    return nil unless component.method_defined?(:call)
+
+    owner = component.instance_method(:call).owner
+    return nil if !owner.is_a?(Class) || view_component_base?(owner)
+    return nil unless owner.respond_to?(:_css_base)
+
+    path = component.instance_method(:call).source_location&.first
+    path if path && File.exist?(path)
+  end
+
+  def finding(component, check, severity, message)
+    Finding.new(component:, check:, severity:, message:)
+  end
+
+  def quote_list(classes) = classes.map { |cls| "\"#{cls}\"" }.join(", ")
+end
+
+require_relative "verifier/compiled_css_oracle"

data/lib/view_component_css_dsl/version.rb

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

data/lib/view_component_css_dsl.rb

@@ -6,12 +6,17 @@ 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 "tailwind_merge"
 
 require_relative "view_component_css_dsl/version"
 
 module ViewComponentCssDsl
   extend ActiveSupport::Concern
 
+  # Single shared merger. tailwind_merge builds a conflict-group index on
+  # initialization, so we pay that cost once per process rather than per call.
+  MERGER = TailwindMerge::Merger.new
+
   HTML_ATTR_KEYS = Set[
     :alt, :aria, :autofocus,
     :class, :colspan, :contenteditable,
@@ -29,99 +34,11 @@ module ViewComponentCssDsl
     :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: ""
+    # Base css strings as written, before inheritance merging. The merged _css_base
+    # is conflict-free by construction; the Verifier needs the raw declarations.
+    class_attribute :_css_base_declarations, 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: []
@@ -165,6 +82,7 @@ module ViewComponentCssDsl
       when String
         if options.empty?
           # Base CSS: css "rounded p-4"
+          self._css_base_declarations = _css_base_declarations + [args.first]
           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)
@@ -341,99 +259,20 @@ module ViewComponentCssDsl
       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.
+    # Merges Tailwind utility classes, resolving conflicts so the last-declared
+    # value wins. Delegates to the `tailwind_merge` gem, which mirrors
+    # tailwind-merge (JS) semantics and tracks Tailwind utility groups upstream.
+    #
     # 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
+      input = css_strings.flat_map { |s| s.to_s.split }.reject(&:empty?).join(" ")
+      return "" if input.empty?
 
-    def known_modifier?(str)
-      return true if KNOWN_MODIFIERS.include?(str)
-      MODIFIER_PATTERNS.any? { |pattern| str.match?(pattern) }
+      MERGER.merge(input)
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: view_component_css_dsl
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Jeff Lange
@@ -29,6 +29,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
+- !ruby/object:Gem::Dependency
+  name: tailwind_merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -100,6 +114,8 @@ files:
 - LICENSE.txt
 - README.md
 - lib/view_component_css_dsl.rb
+- lib/view_component_css_dsl/verifier.rb
+- lib/view_component_css_dsl/verifier/compiled_css_oracle.rb
 - lib/view_component_css_dsl/version.rb
 homepage: https://github.com/SOFware/view_component_css_dsl
 licenses: