tailmix 0.4.6 → 0.4.7

data/docs/05_cookbook.md

@@ -0,0 +1,249 @@
+# Cookbook
+
+This document contains practical recipes for building common UI components with Tailmix.
+
+## Alert Component
+
+Alerts are used to communicate a state that affects the entire system, feature, or page.
+
+### 1. Component Definition
+
+Here's the Ruby code for a flexible `AlertComponent`.
+
+```ruby
+# app/components/alert_component.rb
+class AlertComponent
+  include Tailmix
+  attr_reader :ui, :icon_svg, :message
+
+  def initialize(intent: :info, message:)
+    @ui = tailmix(intent: intent)
+    @message = message
+    @icon_svg = fetch_icon(intent) # Logic to get the correct SVG icon
+  end
+
+  private
+
+  def fetch_icon(intent)
+    # ...
+  end
+
+  tailmix do
+    element :wrapper, "flex items-center p-4 text-sm border rounded-lg" do
+      dimension :intent, default: :info do
+        variant :info,    "text-blue-800 bg-blue-50 border-blue-300"
+        variant :success, "text-green-800 bg-green-50 border-green-300"
+        variant :warning, "text-yellow-800 bg-yellow-50 border-yellow-300"
+        variant :danger,  "text-red-800 bg-red-50 border-red-300"
+      end
+    end
+
+    element :icon, "flex-shrink-0 w-5 h-5"
+    element :message_area, "ml-3"
+  end
+end
+```
+
+#### View Usage (ERB)
+Instantiate the component in your controller or view and use the ui helper to render the elements.
+
+```html
+<%# Success Alert %>
+<% success_alert = AlertComponent.new(intent: :success, message: "Your profile has been updated.") %>
+
+<div <%= tag.attributes **success_alert.ui.wrapper %>>
+  <div <%= tag.attributes **success_alert.ui.icon %>>
+    <%= success_alert.icon_svg.html_safe %>
+  </div>
+  <div <%= tag.attributes **success_alert.ui.message_area %>>
+    <%= success_alert.message %>
+  </div>
+</div>
+
+
+<%# Danger Alert %>
+<% danger_alert = AlertComponent.new(intent: :danger, message: "Failed to delete the record.") %>
+
+<div <%= tag.attributes **danger_alert.ui.wrapper %>>
+  <div <%= tag.attributes **danger_alert.ui.icon %>>
+    <%= danger_alert.icon_svg.html_safe %>
+  </div>
+  <div <%= tag.attributes **danger_alert.ui.message_area %>>
+    <%= danger_alert.message %>
+  </div>
+</div>
+```
+
+#### View Usage .arb (Ruby Arbre)
+
+```ruby
+# Success Alert
+success_alert = AlertComponent.new(intent: :success, message: "Your profile has been updated.")
+ui = success_alert.ui
+
+div ui.wrapper do
+  div ui.icon do
+    success_alert.icon_svg.html_safe
+  end
+  div ui.message_area do
+    success_alert.message
+  end
+end
+
+# Danger Alert
+danger_alert = AlertComponent.new(intent: :danger, message: "Failed to delete the record.")
+ui = danger_alert.ui
+
+div ui.wrapper do
+  div ui.icon do
+    danger_alert.icon_svg.html_safe
+  end
+  div ui.message_area do
+    danger_alert.message
+  end
+end
+```
+
+## Badge Component
+
+Badges are used for labeling, categorization, or highlighting small pieces of information. This recipe shows how to combine multiple dimensions like `size` and `color`.
+
+### 1. Component Definition
+
+```ruby
+# app/components/badge_component.rb
+class BadgeComponent
+  include Tailmix
+  attr_reader :ui, :text
+
+  def initialize(text, color: :gray, size: :sm)
+    @ui = tailmix(color: color, size: size)
+    @text = text
+  end
+
+  tailmix do
+    element :badge, "inline-flex items-center font-medium rounded-full" do
+      dimension :color, default: :gray do
+        variant :gray,    "bg-gray-100 text-gray-600"
+        variant :success, "bg-green-100 text-green-700"
+        variant :warning, "bg-yellow-100 text-yellow-700"
+        variant :danger,  "bg-red-100 text-red-700"
+      end
+
+      dimension :size, default: :sm do
+        variant :sm, "px-2.5 py-0.5 text-xs"
+        variant :md, "px-3 py-1 text-sm"
+      end
+    end
+  end
+end
+```
+
+#### View Usage (ERB)
+
+```html
+<%# A medium-sized success badge %>
+<% success_badge = BadgeComponent.new("Active", color: :success, size: :md) %>
+<span <%= tag.attributes **success_badge.ui.badge %>>
+  <%= success_badge.text %>
+</span>
+
+<%# A small danger badge %>
+<% danger_badge = BadgeComponent.new("Inactive", color: :danger, size: :sm) %>
+<span <%= tag.attributes **danger_badge.ui.badge %>>
+  <%= danger_badge.text %>
+</span>
+```
+
+#### View Usage .arb (Ruby Arbre)
+
+```ruby
+# A medium-sized success badge
+success_badge = BadgeComponent.new("Active", color: :success, size: :md)
+ui = success_badge.ui
+
+span ui.badge do
+  success_badge.text
+end
+
+# A small danger badge
+danger_badge = BadgeComponent.new("Inactive", color: :danger, size: :sm)
+ui = danger_badge.ui
+
+span ui.badge do
+  danger_badge.text
+end
+```
+
+## Card Component
+
+Cards are flexible containers for content. This recipe shows how to build a component with multiple parts (`header`, `body`, `footer`) using multiple `element` definitions.
+
+### 1. Component Definition
+
+```ruby
+# app/components/card_component.rb
+class CardComponent
+  include Tailmix
+  attr_reader :ui
+
+  # We can control the footer's top border with an option
+  def initialize(with_divider: true)
+    @ui = tailmix(with_divider: with_divider)
+  end
+
+  tailmix do
+    element :wrapper, "bg-white border rounded-lg shadow-sm"
+    element :header, "p-4 border-b"
+    element :body, "p-4"
+    element :footer, "p-4 bg-gray-50 rounded-b-lg" do
+      dimension :with_divider, default: true do
+        variant true, "border-t"
+        variant false, "" # No border
+      end
+    end
+  end
+end
+```
+
+#### View Usage (ERB)
+
+```html
+<% card = CardComponent.new %>
+
+<div <%= tag.attributes **card.ui.wrapper %>>
+  <div <%= tag.attributes **card.ui.header %>>
+    <h3 class="text-lg font-medium">Card Title</h3>
+  </div>
+
+  <div <%= tag.attributes **card.ui.body %>>
+    <p>This is the main content of the card. It can contain any information you need to display.</p>
+  </div>
+
+  <div <%= tag.attributes **card.ui.footer %>>
+    <button type="button">Action Button</button>
+  </div>
+</div>
+```
+
+#### View Usage .arb (Ruby Arbre)
+
+```ruby
+# Card
+card = CardComponent.new
+ui = card.ui
+
+div ui.wrapper do
+  div ui.header do
+    h3 "Card Title"
+  end
+
+  div ui.body do
+    para "This is the main content of the card. It can contain any information you need to display."
+  end
+  
+  div ui.footer do
+    button "Action Button"
+  end
+end
+```

data/examples/button.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../lib/tailmix"
+require_relative "helpers"
+
+class Button
+  include Tailmix
+
+  tailmix do
+    element :button do
+      dimension :intent, default: :primary do
+        variant :primary, "bg-blue-500"
+        variant :danger, "bg-red-500"
+      end
+
+      dimension :size, default: :medium do
+        variant :medium, "p-4"
+        variant :small, "p-2"
+      end
+
+      compound_variant on: { intent: :danger, size: :small } do
+        classes "font-bold"
+        data special: "true"
+      end
+    end
+  end
+
+  attr_reader :ui
+  def initialize(intent: :primary, size: :medium)
+    @ui = tailmix(intent: intent, size: size)
+  end
+end
+
+
+puts "-" * 100
+puts Button.dev.docs
+
+# == Tailmix Docs for Button ==
+# Signature: `initialize(intent: :primary, size: :medium)`
+#
+# Dimensions:
+#   - intent (default: :primary)
+#     - :primary:
+#       - classes : "bg-blue-500"
+#     - :danger:
+#       - classes : "bg-red-500"
+#   - size (default: :medium)
+#     - :medium:
+#       - classes : "p-4"
+#     - :small:
+#       - classes : "p-2"
+#
+# Compound Variants:
+#   - on element `:button`:
+#     - on: { intent: :danger, size: :small }
+#       - classes : "font-bold"
+#       - data: {:special=>"true"}
+#
+# No actions defined.
+#
+# button
+#     classes :-> bg-red-500 p-4
+#     data :-> {}
+#     aria :-> {}
+#     tailmix :-> {"data-tailmix-button"=>"intent:danger,size:medium"}
+
+not_compound_component = Button.new(intent: :danger, size: :medium)
+print_component_ui(not_compound_component)
+# button
+#     classes :-> bg-red-500 p-4
+#     data :-> {}
+#     aria :-> {}
+#     tailmix :-> {"data-tailmix-button"=>"intent:danger,size:medium"}
+
+compound_component = Button.new(intent: :danger, size: :small)
+print_component_ui(compound_component)
+# button
+#     classes :-> bg-red-500 p-2 font-bold
+#     data :-> {"data-special"=>"true"}
+#     aria :-> {}
+#     tailmix :-> {"data-tailmix-button"=>"intent:danger,size:small"}

data/examples/helpers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+def stringify_keys(obj)
+  case obj
+  when Hash
+    obj.transform_keys(&:to_s).transform_values { |v| stringify_keys(v) }
+  when Array
+    obj.map { |v| stringify_keys(v) }
+  else
+    obj
+  end
+end
+
+def print_component_ui(component_instance)
+  component_instance.class.dev.elements.each do |element_name|
+    element = component_instance.ui.send(element_name)
+    puts element_name
+    element.each_attribute do |attribute|
+      attribute.each do |key, value|
+        puts "    #{key} :-> #{value}"
+      end
+      puts ""
+    end
+  end
+end

data/examples/modal_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../lib/tailmix"
+require_relative "helpers"
 
 class ModalComponent
   include Tailmix
@@ -182,16 +183,7 @@ modal = ModalComponent.new(size: :lg, open: true)
 ui = modal.ui
 
 
-def stringify_keys(obj)
-  case obj
-  when Hash
-    obj.transform_keys(&:to_s).transform_values { |v| stringify_keys(v) }
-  when Array
-    obj.map { |v| stringify_keys(v) }
-  else
-    obj
-  end
-end
+
 
 # puts "Definition:"
 # puts JSON.pretty_generate(stringify_keys(ModalComponent.tailmix_definition.to_h))

data/lib/tailmix/definition/context_builder.rb

@@ -2,6 +2,7 @@
 
 require_relative "contexts/action_builder"
 require_relative "contexts/element_builder"
+require_relative "contexts/variant_builder"
 
 module Tailmix
   module Definition
@@ -31,9 +32,9 @@ module Tailmix
       def build_definition
         Definition::Result::Context.new(
           elements: @elements.transform_values(&:build_definition).freeze,
-          actions: @actions.transform_values(&:build_definition).freeze
+          actions: @actions.transform_values(&:build_definition).freeze,
         )
       end
     end
   end
-end
+end

data/lib/tailmix/definition/contexts/element_builder.rb

@@ -3,6 +3,7 @@
 require_relative "attribute_builder"
 require_relative "stimulus_builder"
 require_relative "dimension_builder"
+require_relative "variant_builder"
 
 module Tailmix
   module Definition
@@ -11,6 +12,7 @@ module Tailmix
         def initialize(name)
           @name = name
           @dimensions = {}
+          @compound_variants = []
         end
 
         def attributes
@@ -27,12 +29,24 @@ module Tailmix
           @dimensions[name.to_sym] = builder.build_dimension
         end
 
+        def compound_variant(on:, &block)
+          builder = VariantBuilder.new
+          builder.instance_eval(&block)
+
+          @compound_variants << {
+            on: on,
+            modifications: builder.build_variant
+          }
+        end
+
+
         def build_definition
           Definition::Result::Element.new(
             name: @name,
             attributes: attributes.build_definition,
             stimulus: stimulus.build_definition,
-            dimensions: @dimensions.freeze
+            dimensions: @dimensions.freeze,
+            compound_variants: @compound_variants.freeze
           )
         end
       end

data/lib/tailmix/definition/merger.rb

@@ -47,7 +47,8 @@ module Tailmix
           name: parent_el.name,
           attributes: merge_attributes(parent_el.attributes, child_el.attributes),
           dimensions: merge_dimensions(parent_el.dimensions, child_el.dimensions),
-          stimulus: merge_stimulus(parent_el.stimulus, child_el.stimulus)
+          stimulus: merge_stimulus(parent_el.stimulus, child_el.stimulus),
+          compound_variants: parent_el.compound_variants + child_el.compound_variants
         )
       end
 

data/lib/tailmix/definition/result.rb

@@ -7,12 +7,12 @@ module Tailmix
         def to_h
           {
             elements: elements.transform_values(&:to_h),
-            actions: actions.transform_values(&:to_h)
+            actions: actions.transform_values(&:to_h),
           }
         end
       end
 
-      Element = Struct.new(:name, :attributes, :dimensions, :stimulus, keyword_init: true) do
+      Element = Struct.new(:name, :attributes, :dimensions, :stimulus, :compound_variants, keyword_init: true) do
         def to_h
           {
             name: name,
@@ -29,7 +29,8 @@ module Tailmix
                 end
               end
             end,
-            stimulus: stimulus.to_h
+            stimulus: stimulus.to_h,
+            compound_variants: compound_variants
           }
         end
       end

data/lib/tailmix/dev/docs.rb

@@ -19,6 +19,8 @@ module Tailmix
 
         output << generate_dimensions_docs
         output << ""
+        output << generate_compound_variants_docs # <-- Наш новый метод
+        output << ""
         output << generate_actions_docs
         output << ""
         output << generate_stimulus_docs
@@ -60,6 +62,35 @@ module Tailmix
         output.join("\n")
       end
 
+      def generate_compound_variants_docs
+        output = []
+
+        compound_variants_by_element = @definition.elements.values.select do |el|
+          el.compound_variants.any?
+        end
+
+        if compound_variants_by_element.any?
+          output << "Compound Variants:"
+          compound_variants_by_element.each do |element|
+            output << "  - on element `:#{element.name}`:"
+            element.compound_variants.each do |cv|
+              conditions = cv[:on].map { |k, v| "#{k}: :#{v}" }.join(", ")
+              output << "    - on: { #{conditions} }"
+
+              modifications = cv[:modifications]
+              modifications.class_groups.each do |group|
+                label = group[:options][:group] ? "(group: :#{group[:options][:group]})" : ""
+                output << "      - classes #{label}: \"#{group[:classes].join(' ')}\""
+              end
+              output << "      - data: #{modifications.data.inspect}" if modifications.data.any?
+              output << "      - aria: #{modifications.aria.inspect}" if modifications.aria.any?
+            end
+          end
+        end
+
+        output.join("\n")
+      end
+
       def generate_actions_docs
         output = []
         actions = @definition.actions

data/lib/tailmix/runtime/context.rb

@@ -46,7 +46,7 @@ module Tailmix
           { class: element_def.attributes.classes },
           element_name: element_def.name,
           variant_string: variant_string,
-        )
+          )
 
         element_def.dimensions.each do |name, dim_def|
           value = dimensions.fetch(name, dim_def[:default])
@@ -60,6 +60,21 @@ module Tailmix
           attributes.aria.merge!(variant_def.aria)
         end
 
+        element_def.compound_variants.each do |cv|
+          conditions = cv[:on]
+          modifications = cv[:modifications]
+
+          match = conditions.all? do |key, value|
+            dimensions[key] == value
+          end
+
+          if match
+            attributes.classes.add(modifications.classes)
+            attributes.data.merge!(modifications.data)
+            attributes.aria.merge!(modifications.aria)
+          end
+        end
+
         Stimulus::Compiler.call(
           definition: element_def.stimulus,
           data_map: attributes.data,

data/lib/tailmix/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tailmix
-  VERSION = "0.4.6"
+  VERSION = "0.4.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tailmix
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.4.7
 platform: ruby
 authors:
 - Alexander Fokin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-25 00:00:00.000000000 Z
+date: 2025-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,10 +52,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Tailmix provides a powerful DSL to define component style schemas, including
-  variants and parts. It enables clean, co-located style management and offers a rich
-  runtime API for dynamic class manipulation, perfect for Hotwire/Turbo and utility-first
-  CSS.
+description: Tailmix provides a powerful DSL to define component attribute schemas,
+  including variants, compound variants, and states. It enables clean, co-located
+  presentational logic (CSS classes, data attributes, ARIA roles) and offers a rich
+  runtime API for dynamic manipulation, perfect for Hotwire/Turbo.
 email:
 - alexander.s.fokin@gmail.com
 executables: []
@@ -73,7 +73,14 @@ files:
 - app/javascript/tailmix/mutator.js
 - app/javascript/tailmix/runner.js
 - app/javascript/tailmix/stimulus_adapter.js
+- docs/01_getting_started.md
+- docs/02_dsl_reference.md
+- docs/03_advanced_usage.md
+- docs/04_client_side_bridge.md
+- docs/05_cookbook.md
 - examples/_modal_component.arb
+- examples/button.rb
+- examples/helpers.rb
 - examples/modal_component.rb
 - lib/generators/tailmix/install_generator.rb
 - lib/tailmix.rb
@@ -132,5 +139,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: A declarative class manager for Ruby UI components.
+summary: A declarative, state-driven attribute manager for Ruby UI components.
 test_files: []