view_component_css_dsl 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49d5390931f1620f410e179868a1ab08cfcf4a0fa05164c8b4e7e7ba860fa1b2
-  data.tar.gz: 1f51a210129bd2ee1cfd414697e923c60e5be7c0c8870788e193482aacfda6ee
+  metadata.gz: a27107bec7822ef21cc584498087a8d9cdf1ecf044bc5123754f05d5833dd869
+  data.tar.gz: 38f741bebdd9e6768008eaa64dfdb9b1bb9b07be4d2acdb038d3f79348a91d40
 SHA512:
-  metadata.gz: '0086317b10dbb3b32225d9b7eb9b1695d176c40ea6adad370ca6259366edbb1952038170fa4499ecaa2ad5edfff2af7c2459214140bc2be8dd61b6441fac7e05'
-  data.tar.gz: f2286966bae1f1c1b12b2f10e09f58d983281cbfdf0d96c863d98f28b3b7feefae85229d17a440f19d156a51ff7d0dbd2d525660186cb310d6273f15bce4d112
+  metadata.gz: d263fbe75515058bf95d6f3286dc9a59df3112b3c61008a7c44dc3e5ffc0c80bc23b7986801fc2abef88457aa36607689bef05643094c00d199ad28dfd94a8cc
+  data.tar.gz: ffe238ba9cbb6e398001a36fa533ead12f15e1244d9596481356b0d3e478ed8844b2768eadca5be96a90e4677b538e3f46919ef359d7efc6fad93aaf25d076f6

data/CHANGELOG.md

@@ -2,15 +2,18 @@
 
 
 
-## [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).
 
-## [0.1.0] - 2026-05-15
+### 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.
+
+## [0.1.2] - 2026-05-15
 
 ### Added
 
-- Initial release. Extracted from SOFware/forge.
+- data, aria, and attribute DSL declarators for first-class HTML attribute declarations (cf37050)

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
 
@@ -237,6 +245,124 @@ css -> { "pl-#{@indent * 4}" }
 
 Procs returning `nil` are dropped. Procs participate in smart_merge.
 
+## Declaring `data`, `aria`, and HTML attributes
+
+The gem provides three sibling declarators that mirror `css`'s shape: `data`, `aria`, and `attribute`. Use them to declare attributes alongside your styles instead of overriding methods.
+
+```ruby
+class ButtonComponent < ApplicationComponent
+  css "rounded px-4 py-2 bg-blue-500 text-white"
+
+  data variant: :variant, size: :size
+  aria label: "Submit"
+  attribute target: "_blank"
+
+  def initialize(variant: :primary, size: :default)
+    @variant = variant
+    @size = size
+  end
+
+  attr_reader :variant, :size
+end
+```
+
+All three declarators share the same patterns. The only difference is *where* the attribute lands in the rendered HTML — `data` produces `data-*`, `aria` produces `aria-*`, and `attribute` produces a top-level attribute.
+
+### Static values
+
+Always emitted. Stringified at render time (booleans, integers, etc. all become strings; `nil` drops the attribute).
+
+```ruby
+data controller: "modal"
+aria label: "Close dialog"
+attribute target: "_blank"
+```
+
+### Symbol values — call an instance method
+
+When the value is a Symbol, the DSL calls that instance method at render time and uses the result. Standard pattern for streaming an ivar or computed value into a data attribute.
+
+```ruby
+data variant: :variant       # calls #variant; renders as data-variant="<value>"
+attribute tabindex: :tab_index
+
+def tab_index
+  focusable? ? 0 : -1
+end
+```
+
+If the method returns `nil`, the attribute is dropped.
+
+### Proc values — inline computation
+
+For one-off computed values that don't deserve a named method:
+
+```ruby
+aria label: -> { "#{@variant} Notification".titleize }
+data turbo_permanent: -> { true if turbo_permanent? }
+```
+
+Procs are `instance_exec`'d at render time, so they see instance state. Procs returning `nil` drop the attribute.
+
+### Conditional inclusion via positional predicate
+
+Mirrors the `css :method?, style: "..."` pattern — a positional Symbol or Proc as the first argument acts as a predicate. When truthy, the declaration applies; when falsy, it's skipped entirely.
+
+```ruby
+data :auto_dismiss?, timeout: "5000", animation: "fade"
+aria :loud?, label: "Important"
+attribute -> { @disabled }, disabled: true
+```
+
+The Symbol form calls the named instance method; the Proc form is `instance_exec`'d.
+
+### Multiple attributes per declaration
+
+Each declaration accepts a hash of attributes. All share the same predicate (if any).
+
+```ruby
+data controller: "modal",
+     modal_dismiss_action: "click->modal#dismiss"
+```
+
+### Multiple declarations: how they compose
+
+For `aria` and `attribute`, repeated keys across declarations *replace* — the last declaration wins.
+
+For `data`, **the keys `:controller` and `:action` accumulate** (they're space-separated lists in HTML), and everything else replaces. This matches how the gem already merges component defaults with caller-passed values.
+
+```ruby
+data :modal?,        controller: "modal"
+data :trap_focus?,   controller: "trap-focus"
+# Both predicates true → data-controller="modal trap-focus"
+# Only :modal? true   → data-controller="modal"
+# Neither true        → data-controller attribute is omitted
+```
+
+### Caller customization
+
+Whatever a caller passes for `class:`, `data:`, `aria:`, or any HTML attribute layers on top of your declarations using the same rules:
+
+- `class:` smart-merged (see Smart merge behavior below)
+- `data:` controller/action keys concatenate, others replace
+- `aria:` and other attrs: caller wins
+
+### Inheritance
+
+Subclass declarations stack on top of parent declarations using the same rules. `data controller:` declarations in a child class concatenate with the parent's; `data role:` in a child class replaces the parent's. `aria` and `attribute` keys in a child class replace the parent's.
+
+```ruby
+class CardComponent < ApplicationComponent
+  data controller: "card"
+  data role: "region"
+end
+
+class HighlightedCardComponent < CardComponent
+  data controller: "highlighted"   # appends → data-controller="card highlighted"
+  data role: "alert"                # replaces → data-role="alert"
+end
+```
+
 ## 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.
@@ -284,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 |
 | --- | --- | --- | --- |
@@ -301,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:

data/lib/view_component_css_dsl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ViewComponentCssDsl
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 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,97 +34,6 @@ 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: ""
     class_attribute :_css_axis_rules, instance_writer: false, default: []
@@ -133,6 +47,10 @@ module ViewComponentCssDsl
     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
+    # Rules for the data/aria/attribute DSLs. Each entry: {predicate:, attrs:}
+    class_attribute :_data_rules, instance_writer: false, default: []
+    class_attribute :_aria_rules, instance_writer: false, default: []
+    class_attribute :_attribute_rules, instance_writer: false, default: []
   end
 
   class_methods do
@@ -198,6 +116,60 @@ module ViewComponentCssDsl
       end
     end
 
+    # Declares one or more `data-*` attributes on the top-level element.
+    #
+    #   data controller: "modal"                      # static
+    #   data variant: :variant                        # Symbol value -> calls instance method
+    #   data foo: -> { computed_value }               # Proc value -> instance_exec'd
+    #   data :auto_dismiss?, timeout_value: "5000"    # Symbol predicate
+    #   data -> { complex_check? }, foo: "bar"        # Proc predicate
+    def data(*args, **kwargs)
+      self._data_rules = _data_rules.dup
+      _data_rules << _build_attr_rule(:data, *args, **kwargs)
+    end
+
+    # Declares one or more `aria-*` attributes on the top-level element.
+    # See `data` for the full pattern.
+    def aria(*args, **kwargs)
+      self._aria_rules = _aria_rules.dup
+      _aria_rules << _build_attr_rule(:aria, *args, **kwargs)
+    end
+
+    # Declares one or more top-level HTML attributes (`target`, `role`, `tabindex`,
+    # etc.) on the rendered element. See `data` for the full pattern.
+    def attribute(*args, **kwargs)
+      self._attribute_rules = _attribute_rules.dup
+      _attribute_rules << _build_attr_rule(:attribute, *args, **kwargs)
+    end
+
+    private
+
+    # Builds the rule entry used by `data`, `aria`, and `attribute`.
+    # Returns {predicate:, attrs:} where predicate is nil, Symbol, or Proc and
+    # attrs is the hash of attribute key -> (literal | Symbol | Proc).
+    def _build_attr_rule(namespace, *args, **kwargs)
+      if args.size > 1
+        raise ArgumentError,
+          "#{namespace} accepts at most one positional arg (a predicate Symbol or Proc)"
+      end
+
+      predicate = args.first
+      if predicate && !predicate.is_a?(Symbol) && !predicate.is_a?(Proc)
+        raise ArgumentError,
+          "#{namespace} positional predicate must be a Symbol or Proc " \
+          "(got #{predicate.class})"
+      end
+
+      if kwargs.empty?
+        raise ArgumentError,
+          "#{namespace} requires at least one attribute kwarg"
+      end
+
+      {predicate:, attrs: kwargs}
+    end
+
+    public
+
     # 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.
@@ -283,99 +255,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
+      input = css_strings.flat_map { |s| s.to_s.split }.reject(&:empty?).join(" ")
+      return "" if input.empty?
 
-      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) }
+      MERGER.merge(input)
     end
   end
 
@@ -401,7 +294,10 @@ module ViewComponentCssDsl
   def html_attrs
     return {} unless @html_attrs
 
-    result = @html_attrs.except(:aria, :class, :data)
+    # Start with DSL-declared top-level attrs; caller's html_attrs layer on top
+    # (caller wins on collision, mirroring the css behavior).
+    dsl_attrs = resolved_attr_rules(:attribute)
+    result = dsl_attrs.merge(@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
@@ -462,16 +358,11 @@ module ViewComponentCssDsl
   # - 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
+    # Merge in order: DSL declarations -> method override -> caller's :data.
+    # Each layer uses DATA_MERGE_KEYS semantics (controller/action concatenate,
+    # everything else replaces).
+    combined = merge_data_layer(resolved_attr_rules(:data), data_attrs)
+    merge_data_layer(combined, @html_attrs.fetch(:data, {}))
   end
 
   # Overwrite in subclass to define default aria-attrs
@@ -479,14 +370,75 @@ module ViewComponentCssDsl
     {}
   end
 
-  # Using merge allows for default value #aria_attrs, but also for dev to override
-  # that value per-instance as needed
+  # Merge in order: DSL declarations -> method override -> caller's :aria.
+  # Hash#merge throughout — caller wins on collision (no additive semantics).
   def final_aria_attrs
-    aria_attrs.merge(@html_attrs.fetch(:aria, {}))
+    resolved_attr_rules(:aria).merge(aria_attrs).merge(@html_attrs.fetch(:aria, {}))
   end
 
   private
 
+  # Walks the DSL rules for the given namespace (:data, :aria, :attribute),
+  # evaluates each predicate, resolves each value, and returns a hash. For
+  # the :data namespace, DATA_MERGE_KEYS keys accumulate space-separated when
+  # the same key appears in multiple included rules.
+  def resolved_attr_rules(namespace)
+    rules = case namespace
+    when :data then self.class._data_rules
+    when :aria then self.class._aria_rules
+    when :attribute then self.class._attribute_rules
+    end
+
+    rules.each_with_object({}) do |rule, result|
+      next unless predicate_met?(rule[:predicate])
+
+      rule[:attrs].each do |key, value|
+        resolved = resolve_attr_value(value)
+        next if resolved.nil?
+
+        result[key] = if namespace == :data && DATA_MERGE_KEYS.include?(key) && result.key?(key)
+          "#{result[key]} #{resolved}"
+        else
+          resolved
+        end
+      end
+    end
+  end
+
+  # Layers `addition` on top of `base` using DATA_MERGE_KEYS semantics: keys
+  # in DATA_MERGE_KEYS concatenate space-separated, every other key replaces.
+  def merge_data_layer(base, addition)
+    addition.each_with_object(base.dup) do |(key, value), result|
+      result[key] = if DATA_MERGE_KEYS.include?(key)
+        [result[key], value].compact.join(" ")
+      else
+        value
+      end
+    end
+  end
+
+  # Resolves a predicate. nil predicate -> always true. Symbol -> call instance
+  # method. Proc -> instance_exec.
+  def predicate_met?(predicate)
+    case predicate
+    when nil then true
+    when Symbol then send(predicate)
+    when Proc then instance_exec(&predicate)
+    end
+  end
+
+  # Resolves a value for a DSL-declared attribute. Symbols become method calls
+  # on the instance; Procs are instance_exec'd; literals pass through. Result
+  # is stringified unless nil (which drops the attribute).
+  def resolve_attr_value(value)
+    resolved = case value
+    when Symbol then send(value)
+    when Proc then instance_exec(&value)
+    else value
+    end
+    resolved&.to_s
+  end
+
   def build_classes
     validate_axes!
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: view_component_css_dsl
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 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