view_component_css_dsl 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fcd1b87aa8e32ecd595601ffbce3015c1cd7d1119a97967fda706f859499654
-  data.tar.gz: 3b473073f9fca60d277fa0dd9700cd66b2da76a2f72222830f3a3d76bc294ce7
+  metadata.gz: eba29c79b834ffc0651fc3ff6b244e860de04218b6b29ca31df90634211fc6a6
+  data.tar.gz: fb7183fa91dc0bb773d61dc0953df0cf17fed601d39609cc1b2e2d44da725f51
 SHA512:
-  metadata.gz: f4c117c6970000983d5acbdbb2d75254ac9875b5f0faeb64e80e78e88dd8644ee5dc3a01c24dfbac1257405cac55aa92c5975c1ac639cf28b8f2632e42002eec
-  data.tar.gz: a57068184216a9c7f3d0554efa9658805749d35aa57f8d1592a1a7c3f26bb5a2b3bc0333d68e073cb4281e619cff6067c84db55118196ee227b32bdbddfbcc98
+  metadata.gz: d28bfc76e89df1e4899fa396f0d45be296bbef32bed288d4893f908ad9038f28bc3f3e444675acf1408e01859f2cd6b007cb4fc346bad8389377765768952ff9
+  data.tar.gz: 9353657fc812e95881ec400152852886d05f2292f978d590dc0475abb64cb87dfe61ba38c1cde972d8c2c6f22eb74d0e88bd2f2c632455d1caa5d368f6d230e4

data/CHANGELOG.md

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

data/README.md

@@ -237,6 +237,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.
@@ -327,6 +445,8 @@ bundle exec rspec
 bundle exec standardrb
 ```
 
+Releases are managed by [reissue](https://github.com/SOFware/reissue). When committing, add Keep-a-Changelog trailers (`Added:`, `Changed:`, `Fixed:`, etc.) and reissue will collate them into `CHANGELOG.md` at release time. To publish a new version, run the "Release gem to RubyGems.org" workflow from GitHub Actions.
+
 ## License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/view_component_css_dsl/version.rb

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

data/lib/view_component_css_dsl.rb

@@ -12,11 +12,6 @@ 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,
@@ -138,6 +133,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
@@ -203,23 +202,117 @@ 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.
+    #
+    # These can then be referenced in the component's template as `html_attrs`.
+    #
+    # Why?
+    # - DX: All components can accept arbitrary html attrs for free. Dev can pass
+    #   arbitrary html attrs in at any caller and have it output at the component's
+    #   top-level element.
+    # - Removes boilerplate of putting `**html_attrs` as the last argument in every
+    #   single component's initialize signature, and then having to set the same as an
+    #   ivar within the initialize body.
+    # - Requires following a pattern of declaring `**html_attrs` in the top level
+    #   element of every single component's template.
+    # - Example template definition:
+    #
+    #     # html_attrs contains :class, :data, etc defined either in the component
+    #     # or passed in by the caller.
+    #     <%= tag.my_component **html_attrs do %>
+    #       <%= content %>
+    #     <% end %>
+    #
+    # Example caller:
+    #
+    #   render MyComponent.new(text: "Hello", class: "custom", data: {foo: "bar"})
+    #
+    # - :text goes to component's #initialize method, as normal
+    # - :class, :data, etc are captured and merged into @html_attrs automatically
+    # - The component's initialize method will look like:
+    #
+    #     def initialize(text)
+    #       @text = text
+    #     end
+    #
+    # To opt out of this behavior, inherit from ViewComponent::Base directly instead of
+    # ApplicationComponent.
+    #
     def new(*args, **kwargs, &block)
       info = initialize_params_info
       html_attrs = {}
+
+      # Only extract HTML attrs if the component uses **html_attrs pattern.
+      # Components with other keyrest names (like **options) should receive all kwargs.
       if info[:uses_html_attrs_keyrest]
+        # Extract HTML attrs, but NOT if they're declared component params
         extractable = HTML_ATTR_KEYS.intersection(kwargs.keys) - info[:declared_kwargs]
         html_attrs = kwargs.extract!(*extractable)
       end
 
       instance = allocate
+      # Set @html_attrs BEFORE initialize so components can access it there
       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.
+      # Merge with any @html_attrs set by initialize (old pattern components).
+      # Caller-provided values (html_attrs) take precedence over component defaults.
       existing = instance.instance_variable_get(:@html_attrs) || {}
       instance.instance_variable_set(:@html_attrs, existing.merge(html_attrs))
       instance
@@ -234,12 +327,17 @@ module ViewComponentCssDsl
         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
+          when :key, :keyreq
+            declared_kwargs << name
+          when :keyrest
+            keyrest_name = name
           end
         end
-        uses_html_attrs_keyrest = keyrest_name.nil? || keyrest_name == :html_attrs
-        {declared_kwargs:, uses_html_attrs_keyrest:}
+
+        {
+          declared_kwargs:,
+          uses_html_attrs_keyrest: keyrest_name == :html_attrs || keyrest_name.nil?
+        }
       end
     end
 
@@ -361,7 +459,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
@@ -422,16 +523,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
@@ -439,14 +535,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,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: view_component_css_dsl
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Jeff Lange
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -44,6 +43,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: reissue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -95,7 +108,6 @@ 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
@@ -110,8 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Declarative CSS class DSL for ViewComponent + Tailwind
 test_files: []