tailmix 0.4.5 → 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
@@ -9,8 +10,8 @@ class ModalComponent
   tailmix do
     element :base, "fixed inset-0 z-50 flex items-center justify-center" do
       dimension :open, default: true do
-        option true, "visible opacity-100"
-        option false, "invisible opacity-0"
+        variant true, "visible opacity-100"
+        variant false, "invisible opacity-0"
       end
       stimulus.controller("modal").action_payload(:toggle, as: :toggle_data)
     end
@@ -21,9 +22,12 @@ class ModalComponent
 
     element :panel, "relative bg-white rounded-lg shadow-xl transition-transform transform" do
       dimension :size, default: :md do
-        option :sm, "w-full max-w-sm p-4"
-        option :md, "w-full max-w-md p-6"
-        option :lg, "w-full max-w-lg p-8"
+        variant :sm, "w-full max-w-sm p-4" do
+          classes "dark:text-slate-400", group: :dark_mode
+          classes "one two"
+        end
+        variant :md, "w-full max-w-md p-6"
+        variant :lg, "w-full max-w-lg p-8"
       end
       stimulus.context("modal").target("panel")
     end
@@ -81,12 +85,12 @@ class ModalComponent
 end
 
 puts "-" * 100
-puts ModalComponent.dev.docs
-puts ""
-puts "Scaffolds:"
-puts ""
-puts ModalComponent.dev.stimulus.scaffold
-puts ""
+# puts ModalComponent.dev.docs
+# puts ""
+# puts "Scaffolds:"
+# puts ""
+# puts ModalComponent.dev.stimulus.scaffold
+# puts ""
 
 # >>>
 #
@@ -95,12 +99,19 @@ puts ""
 #
 # Dimensions:
 #   - open (default: true)
-#     - true: "visible opacity-100"
-#     - false: "invisible opacity-0"
+#     - true:
+#       - classes : "visible opacity-100"
+#     - false:
+#       - classes : "invisible opacity-0"
 #   - size (default: :md)
-#     - :sm: "w-full max-w-sm p-4"
-#     - :md: "w-full max-w-md p-6"
-#     - :lg: "w-full max-w-lg p-8"
+#     - :sm:
+#       - classes : "w-full max-w-sm p-4"
+#       - classes (group: :dark_mode): "dark:text-slate-400"
+#       - classes : "one two"
+#     - :md:
+#       - classes : "w-full max-w-md p-6"
+#     - :lg:
+#       - classes : "w-full max-w-lg p-8"
 #
 # Actions:
 #   - :toggle
@@ -167,14 +178,24 @@ puts ""
 
 
 
-# modal = ModalComponent.new(size: :lg, open: true)
+modal = ModalComponent.new(size: :lg, open: true)
 # modal.lock!
-# ui = modal.ui
+ui = modal.ui
+
+
+
 
 # puts "Definition:"
-# pp ModalComponent.tailmix_definition
-# pp ModalComponent.tailmix_definition.to_h
-# ui.overlay.each do |key, value|
-#   puts "#{key} :-> #{value.inspect.to_s[0, 75]}..."
-# end
+# puts JSON.pretty_generate(stringify_keys(ModalComponent.tailmix_definition.to_h))
 # ui.action(:lock).apply!
+
+ModalComponent.dev.elements.each do |element_name|
+  element = ui.send(element_name)
+  puts element_name
+  element.each_attribute do |attribute|
+    attribute.each do |key, value|
+      puts "    #{key} :-> #{value}"
+    end
+    puts ""
+  end
+end

data/lib/tailmix/configuration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tailmix
+  # Stores the configuration for the Tailmix gem.
+  class Configuration
+    attr_accessor :element_selector_attribute, :dev_mode_attributes
+
+    def initialize
+      @element_selector_attribute = nil
+      @dev_mode_attributes = defined?(Rails) && Rails.env.development?
+    end
+  end
+end

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/actions/element_builder.rb

@@ -10,13 +10,13 @@ module Tailmix
             @commands = []
           end
 
-          def classes(classes_string, method: @default_method)
+          def classes(classes_string, options = {})
+            method = options.fetch(:method, @default_method)
             @commands << { field: :classes, method: method, payload: classes_string }
           end
 
           def data(data_hash)
             operation = data_hash.delete(:method) || @default_method
-
             @commands << { field: :data, method: operation, payload: data_hash }
           end
 

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

@@ -1,16 +1,34 @@
 # frozen_string_literal: true
 
-class DimensionBuilder
-  attr_reader :options
+require_relative "variant_builder"
 
-  def initialize(default: nil)
-    @options = { options: {}, default: default }
-  end
+module Tailmix
+  module Definition
+    module Contexts
+      class DimensionBuilder
+        def initialize(default: nil)
+          @variants = {}
+          @default = default
+        end
+
+        def variant(name, classes = "", data: {}, aria: {}, &block)
+          builder = VariantBuilder.new
+          builder.classes(classes) if classes && !classes.empty?
+          builder.data(data)
+          builder.aria(aria)
+
+          builder.instance_eval(&block) if block
+
+          @variants[name] = builder.build_variant
+        end
 
-  def option(value, classes, default: false)
-    @options[:options][value] = classes.split
-    if default && @options[:default].nil?
-      @options[:default] = value
+        def build_dimension
+          {
+            default: @default,
+            variants: @variants.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
@@ -22,17 +24,29 @@ module Tailmix
         end
 
         def dimension(name, default: nil, &block)
-          dimension = DimensionBuilder.new(default: default)
-          dimension.instance_eval(&block)
-          @dimensions[name.to_sym] = dimension.options
+          builder = Contexts::DimensionBuilder.new(default: default)
+          builder.instance_eval(&block)
+          @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/contexts/variant_builder.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module Definition
+    module Contexts
+      class VariantBuilder
+        def initialize
+          @class_groups = []
+          @data = {}
+          @aria = {}
+        end
+
+        def classes(class_string, options = {})
+          @class_groups << { classes: class_string.to_s.split, options: options }
+        end
+
+        def data(hash)
+          @data.merge!(hash)
+        end
+
+        def aria(hash)
+          @aria.merge!(hash)
+        end
+
+        def build_variant
+          Definition::Result::Variant.new(
+            class_groups: @class_groups.freeze,
+            data: @data.freeze,
+            aria: @aria.freeze
+          )
+        end
+      end
+    end
+  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
 
@@ -63,28 +64,21 @@ module Tailmix
         Result::Stimulus.new(definitions: combined_definitions)
       end
 
-      private
-
       def merge_dimensions(parent_dims, child_dims)
-        deep_merge(parent_dims, child_dims) do |key, parent_val, child_val|
-          if key == :options && parent_val.is_a?(Hash) && child_val.is_a?(Hash)
-            parent_val.merge(child_val)
-          else
-            child_val
-          end
-        end
-      end
+        all_keys = parent_dims.keys | child_dims.keys
+
+        all_keys.each_with_object({}) do |key, merged|
+          parent_val = parent_dims[key]
+          child_val = child_dims[key]
+
+          if parent_val && child_val
+            merged_variants = parent_val.fetch(:variants, {}).merge(child_val.fetch(:variants, {}))
 
-      def deep_merge(parent_hash, child_hash, &block)
-        child_hash.each_with_object(parent_hash.dup) do |(key, child_val), new_hash|
-          parent_val = new_hash[key]
+            default = child_val.key?(:default) ? child_val[:default] : parent_val[:default]
 
-          new_hash[key] = if parent_val.is_a?(Hash) && child_val.is_a?(Hash)
-            deep_merge(parent_val, child_val, &block)
-          elsif block_given? && new_hash.key?(key)
-            block.call(key, parent_val, child_val)
+            merged[key] = { default: default, variants: merged_variants }
           else
-            child_val
+            merged[key] = parent_val || child_val
           end
         end
       end