class_list_op 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d357785ffdda8c49dadf2b3220b8359ed4255ab79a95e4397787d8b9f8693909
-  data.tar.gz: 3c3c1b9f81125e785106fb069a2a5da4bb282fdea1de8edf2eb1429f8d44ff1e
+  metadata.gz: 95eb998447cdebbc43f709828a8dd56adce85b0196feaf3c21e66871065c6455
+  data.tar.gz: 4eaf7e232a663048fdc285cafb9074817484cde5f91b720ac2d263214cdcac60
 SHA512:
-  metadata.gz: 60936a499d423937b8f4ab088619500362f2c693f8d91632f6e7bd239db8e0a5aef2f8c9ec31155bce37f0d3a6749eb09eebacd0774af77a7411de4798fea943
-  data.tar.gz: '0641594aaa67ad7fab30707d306c9eef87dd78c03d452a018e159c6c5b60c06a2f8ef767fa779f59a09c26001e706c20b6a2d4342fffd9d2735c81b89d99f2cf'
+  metadata.gz: 994795cc106ffd72a6c934d0cb4b71fd211f34a485755c1dcffb180c668668fca3e3200ac2821e55c67a1b9ce309719aeaf83f70b0fa7132aa73de5a51d051d7
+  data.tar.gz: faf7a8bead2bafedc1aef0836196f1142a2ac2f2e6e588724b3d28ac18c705d1234b2bd8cb4e252b46ec4501628aa6a02f8f49b72feb564ff3cc1d6f833543ec

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-05
+
+- Add `ClassList::Variants` for Tailwind-safe variant assembly from plain hashes
+- Add `ClassList.resolve_attributes` as the preferred attribute operations API
+- Keep `ClassList.merge_attributes` as a compatibility alias
+
 ## [0.1.0] - 2026-04-05
 
 - Initial release

data/README.md

@@ -56,6 +56,35 @@ list.to_s
 
 updated.tokens
 # => ["flex", "mb-4"]
+
+defaults = { class: "flex gap-4", id: "main" }
+overrides = { class: { add: "mb-4", remove: "gap-4" } }
+
+ClassList.resolve_attributes(defaults, overrides)
+# => { class: "flex mb-4", id: "main" }
+
+button = ClassList.variants(
+  base: {
+    container: "font-medium whitespace-nowrap inline-flex items-center"
+  },
+  defaults: {
+    size: :md,
+    tone: :default
+  },
+  dimensions: {
+    size: {
+      xs: { container: "px-1.5 py-1 rounded-md text-xs" },
+      md: { container: "px-3 py-2 rounded-lg text-sm" }
+    },
+    tone: {
+      default: { container: "text-white bg-blue-600 hover:bg-blue-700" },
+      red: { container: "text-white bg-red-600 hover:bg-red-700" }
+    }
+  }
+)
+
+button.attributes(:container, tone: :red, class: { add: "w-full" })
+# => { class: "font-medium whitespace-nowrap inline-flex items-center px-3 py-2 rounded-lg text-sm text-white bg-red-600 hover:bg-red-700 w-full" }
 ```
 
 ### Supported inputs
@@ -101,6 +130,145 @@ ClassList.resolve(defaults, remove: "md:space-x-4", add: "md:space-x-6")
 # => "cols w-full md:flex md:flex-row md:space-x-6"
 ```
 
+### Attribute adapter
+
+`ClassList.resolve_attributes` is a thin adapter for component-style attribute hashes.
+
+- non-`class` attributes use normal hash merge semantics
+- `class: "..."` still fully overrides defaults
+- `class: { add:, remove:, replace: }` applies class operations against the default class value
+
+`ClassList.merge_attributes` remains available as a compatibility alias.
+
+Arbre-style example:
+
+```ruby
+class Cols < BaseComponent
+  builder_method :cols
+
+  def build(attributes = {})
+    attributes = { breakpoint: :md }.merge(attributes)
+
+    direction = attributes.delete(:direction) || :row
+    space = attributes.delete(:space) || 4
+    breakpoint = attributes.delete(:breakpoint)
+
+    defaults = { class: cols_classes(direction:, space:, breakpoint:) }
+
+    super(ClassList.resolve_attributes(defaults, attributes))
+  end
+
+  def columns
+    children.grep(Col)
+  end
+
+  private
+
+  def cols_classes(direction:, space:, breakpoint:)
+    [
+      "cols w-full",
+      "#{breakpoint}:flex",
+      direction_variant(direction, space:, breakpoint:)
+    ]
+  end
+
+  def direction_variant(direction, space:, breakpoint:)
+    space_axis = direction.to_s.include?("row") ? "x" : "y"
+
+    [
+      "#{breakpoint}:flex-#{direction}",
+      "#{breakpoint}:space-#{space_axis}-#{space}"
+    ]
+  end
+end
+
+cols class: { add: "mb-4", remove: "md:space-x-4" } do
+  # ...
+end
+```
+
+### Variants
+
+`ClassList::Variants` automates the repetitive `base + selected variants + class operations` assembly without introducing a DSL.
+
+- config is just a Ruby hash and can come from YAML
+- all Tailwind classes stay as literal strings for extractor safety
+- dimensions are selected by key and merged in order
+- any non-dimension options are treated as final attribute overrides
+
+```ruby
+button = ClassList.variants(
+  base: {
+    container: "font-medium whitespace-nowrap text-center inline-flex items-center cursor-pointer",
+    icon: "shrink-0"
+  },
+  defaults: {
+    size: :md,
+    tone: :default
+  },
+  dimensions: {
+    size: {
+      xs: {
+        container: "px-1.5 py-1 rounded-md text-xs",
+        icon: "size-3"
+      },
+      md: {
+        container: "px-3 py-2 rounded-lg text-sm",
+        icon: "size-4"
+      }
+    },
+    tone: {
+      default: {
+        container: "text-white bg-blue-600 hover:bg-blue-700 focus:ring-blue-800"
+      },
+      red: {
+        container: "text-white bg-red-600 hover:bg-red-700 focus:ring-red-800"
+      }
+    }
+  }
+)
+
+button.attributes(:container, size: :xs, tone: :red)
+# => { class: "font-medium whitespace-nowrap text-center inline-flex items-center cursor-pointer px-1.5 py-1 rounded-md text-xs text-white bg-red-600 hover:bg-red-700 focus:ring-red-800" }
+
+button.attributes(:container, tone: :red, class: { add: "w-full" })
+# => { class: "... w-full" }
+
+button.attributes(:icon, size: :xs)
+# => { class: "shrink-0 size-3" }
+```
+
+`Col` can follow the same pattern:
+
+```ruby
+class Col < BaseComponent
+  builder_method :col
+
+  def build(size_or_options = "1/2", options = {})
+    options = { breakpoint: :md }.merge(options)
+    breakpoint = options.delete(:breakpoint)
+
+    defaults = { class: col_classes(size_or_options, breakpoint:) }
+
+    super(ClassList.merge_attributes(defaults, options))
+  end
+
+  private
+
+  def col_classes(size_or_options, breakpoint:)
+    case size_or_options
+    when Hash
+      size_or_options.map { |bp, size| "#{bp}:w-#{size}" }
+    else
+      ["#{breakpoint}:w-#{size_or_options}"]
+    end
+  end
+end
+
+col "1/2", class: { add: "mb-4" }
+col({ md: "1/2", xl: "1/3" }, class: { add: "self-start" })
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/class_list/attribute_merger.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ClassList
+  module AttributeMerger
+    module_function
+
+    def call(base = nil, overrides = nil, class_key: :class)
+      base_attributes = normalize_attributes(base)
+      override_attributes = normalize_attributes(overrides)
+
+      return base_attributes.merge(override_attributes) unless override_attributes.key?(class_key)
+
+      merged_attributes = base_attributes.merge(override_attributes)
+      merged_attributes[class_key] = resolve_class_value(base_attributes[class_key], override_attributes[class_key])
+      merged_attributes
+    end
+
+    def normalize_attributes(value)
+      case value
+      when nil
+        {}
+      when Hash
+        value.dup
+      else
+        raise InvalidInputError, "unsupported attribute input: #{value.class}"
+      end
+    end
+
+    def resolve_class_value(base_value, override_value)
+      return override_value unless override_value.is_a?(Hash)
+
+      operations = override_value.each_with_object({}) do |(key, value), result|
+        result[key.to_sym] = value
+      end
+
+      ClassList.resolve(base_value, **operations)
+    end
+  end
+end

data/lib/class_list/errors.rb

@@ -4,4 +4,5 @@ module ClassList
   Error = Class.new(StandardError)
   InvalidInputError = Class.new(Error)
   InvalidOperationError = Class.new(Error)
+  InvalidVariantError = Class.new(Error)
 end

data/lib/class_list/variants.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module ClassList
+  class Variants
+    CLASS_KEY = :class
+
+    def initialize(config)
+      @config = normalize_config(config)
+    end
+
+    def tokens(slot = :container, **options)
+      ClassList.normalize(attributes(slot, **options)[CLASS_KEY])
+    end
+
+    def resolve(slot = :container, **options)
+      attributes(slot, **options)[CLASS_KEY].to_s
+    end
+
+    def attributes(slot = :container, **options)
+      slot_name = slot.to_sym
+      dimension_names = config.fetch(:dimensions, {}).keys
+      dimension_options = {}
+      overrides = {}
+
+      options.each do |key, value|
+        normalized_key = key.to_sym
+
+        if dimension_names.include?(normalized_key)
+          dimension_options[normalized_key] = value
+        else
+          overrides[normalized_key] = value
+        end
+      end
+
+      selections = config.fetch(:defaults, {}).merge(dimension_options)
+
+      base_attributes = attributes_for_slot(config.fetch(:base, {}), slot_name)
+      variant_attributes = selections.reduce(base_attributes) do |result, (dimension_name, option_name)|
+        selected = config.fetch(:dimensions, {}).fetch(dimension_name).fetch(option_name.to_sym) do
+          raise InvalidVariantError, "unknown option #{option_name.inspect} for dimension #{dimension_name.inspect}"
+        end
+
+        merge_variant_attributes(result, attributes_for_slot(selected, slot_name))
+      end
+
+      ClassList.resolve_attributes(variant_attributes, normalize_attributes(overrides))
+    end
+
+    def slots(**options)
+      slot_names = [
+        config.fetch(:base, {}).keys,
+        config.fetch(:dimensions, {}).values.flat_map(&:values).flat_map(&:keys)
+      ].flatten.compact.uniq
+
+      slot_names.each_with_object({}) do |slot_name, result|
+        result[slot_name] = attributes(slot_name, **options)
+      end
+    end
+
+    private
+
+    attr_reader :config
+
+    def normalize_config(value)
+      unless value.is_a?(Hash)
+        raise InvalidInputError, "unsupported variants config: #{value.class}"
+      end
+
+      deep_symbolize(value)
+    end
+
+    def deep_symbolize(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested_value), result|
+          result[key.to_sym] = deep_symbolize(nested_value)
+        end
+      when Array
+        value.map { |item| deep_symbolize(item) }
+      else
+        value
+      end
+    end
+
+    def attributes_for_slot(source, slot_name)
+      normalize_attributes(source[slot_name])
+    end
+
+    def normalize_attributes(value)
+      case value
+      when nil
+        {}
+      when String, Symbol, Array
+        { CLASS_KEY => value }
+      when Hash
+        value.dup
+      else
+        raise InvalidInputError, "unsupported variant attributes: #{value.class}"
+      end
+    end
+
+    def merge_variant_attributes(base_attributes, layer_attributes)
+      merged = base_attributes.merge(layer_attributes)
+
+      merged[CLASS_KEY] = ClassList.resolve(base_attributes[CLASS_KEY], add: layer_attributes[CLASS_KEY])
+      merged
+    end
+  end
+end

data/lib/class_list/version.rb

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

data/lib/class_list_op.rb

@@ -5,6 +5,8 @@ require_relative "class_list/errors"
 require_relative "class_list/tokenizer"
 require_relative "class_list/resolver"
 require_relative "class_list/list"
+require_relative "class_list/attribute_merger"
+require_relative "class_list/variants"
 
 module ClassList
   class << self
@@ -27,5 +29,15 @@ module ClassList
     def list(base = nil)
       List.new(base)
     end
+
+    def resolve_attributes(base = nil, overrides = nil, class_key: :class)
+      AttributeMerger.call(base, overrides, class_key: class_key)
+    end
+
+    alias_method :merge_attributes, :resolve_attributes
+
+    def variants(config)
+      Variants.new(config)
+    end
   end
 end

data/sig/class_list_op.rbs

@@ -6,6 +6,9 @@ module ClassList
   def self.resolve: (?untyped base, **untyped operations) -> String
   def self.call: (?untyped base, **untyped operations) -> String
   def self.list: (?untyped base) -> List
+  def self.resolve_attributes: (?Hash[untyped, untyped] base, ?Hash[untyped, untyped] overrides, ?class_key: Symbol) -> Hash[untyped, untyped]
+  def self.merge_attributes: (?Hash[untyped, untyped] base, ?Hash[untyped, untyped] overrides, ?class_key: Symbol) -> Hash[untyped, untyped]
+  def self.variants: (Hash[untyped, untyped] config) -> Variants
 end
 
 module ClassList::Tokenizer
@@ -17,6 +20,18 @@ module ClassList::Resolver
   def self.call: (?untyped base, **untyped operations) -> Array[String]
 end
 
+module ClassList::AttributeMerger
+  def self.call: (?Hash[untyped, untyped] base, ?Hash[untyped, untyped] overrides, ?class_key: Symbol) -> Hash[untyped, untyped]
+end
+
+class ClassList::Variants
+  def initialize: (Hash[untyped, untyped] config) -> void
+  def tokens: (?Symbol slot, **untyped options) -> Array[String]
+  def resolve: (?Symbol slot, **untyped options) -> String
+  def attributes: (?Symbol slot, **untyped options) -> Hash[untyped, untyped]
+  def slots: (**untyped options) -> Hash[Symbol, Hash[untyped, untyped]]
+end
+
 class ClassList::List
   @tokens: Array[String]
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: class_list_op
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alexander
@@ -22,10 +22,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- lib/class_list/attribute_merger.rb
 - lib/class_list/errors.rb
 - lib/class_list/list.rb
 - lib/class_list/resolver.rb
 - lib/class_list/tokenizer.rb
+- lib/class_list/variants.rb
 - lib/class_list/version.rb
 - lib/class_list_op.rb
 - sig/class_list_op.rbs