tailmix 0.4.7 → 0.4.8

data/docs/05_cookbook.md

@@ -1,249 +0,0 @@
-# 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/lib/tailmix/definition/contexts/action_builder.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "actions/element_builder"
-
-module Tailmix
-  module Definition
-    module Contexts
-      class ActionBuilder
-        def initialize(method)
-          @method = method
-          @mutations = {}
-        end
-
-        def element(name, &block)
-          builder = Actions::ElementBuilder.new(@method)
-          builder.instance_eval(&block)
-
-          commands = builder.build_commands
-          @mutations[name.to_sym] = commands unless commands.empty?
-        end
-
-        def build_definition
-          Definition::Result::Action.new(
-            action: @method,
-            mutations: @mutations.freeze
-          )
-        end
-      end
-    end
-  end
-end

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

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "attribute_builder"
-require_relative "stimulus_builder"
-require_relative "dimension_builder"
-require_relative "variant_builder"
-
-module Tailmix
-  module Definition
-    module Contexts
-      class ElementBuilder
-        def initialize(name)
-          @name = name
-          @dimensions = {}
-          @compound_variants = []
-        end
-
-        def attributes
-          @attributes_builder ||= AttributeBuilder.new
-        end
-
-        def stimulus
-          @stimulus_builder ||= StimulusBuilder.new
-        end
-
-        def dimension(name, default: nil, &block)
-          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,
-            compound_variants: @compound_variants.freeze
-          )
-        end
-      end
-    end
-  end
-end

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

@@ -1,101 +0,0 @@
-# frozen_string_literal: true
-
-module Tailmix
-  module Definition
-    module Contexts
-      class StimulusBuilder
-        attr_reader :definitions
-
-        def initialize
-          @definitions = []
-          @current_context = nil
-        end
-
-        def controller(name)
-          @definitions << { type: :controller, name: name }
-          context(name)
-        end
-        alias_method :ctr, :controller
-
-        def context(name)
-          @current_context = name.to_s
-          self
-        end
-        alias_method :ctx, :context
-
-        def target(target_name)
-          raise "A controller context must be set..." unless @current_context
-          @definitions << { type: :target, controller: @current_context, name: target_name }
-          self
-        end
-
-        def action(*args)
-          ensure_context!
-
-          action_data = case args.first
-          when String
-            { type: :raw, content: args.first }
-          when Hash
-            { type: :hash, content: args.first }
-          else
-            { type: :tuple, content: args }
-          end
-
-          @definitions << { type: :action, controller: @current_context, data: action_data }
-          self
-        end
-
-        def value(value_name, value: nil, call: nil, method: nil)
-          ensure_context!
-
-          source = if !value.nil?
-            { type: :literal, content: value }
-          elsif call.is_a?(Proc)
-            { type: :proc, content: call }
-          elsif method.is_a?(Symbol) || method.is_a?(String)
-            { type: :method, content: method.to_sym }
-          else
-            raise ArgumentError, "You must provide one of value:, call:, or method: keyword arguments."
-          end
-
-          @definitions << {
-            type: :value,
-            controller: @current_context,
-            name: value_name,
-            source: source
-          }
-          self
-        end
-
-        def action_payload(action_name, as: nil)
-          ensure_context!
-          value_name = as || "#{action_name}_action"
-
-          @definitions << {
-            type: :action_payload,
-            controller: @current_context,
-            action_name: action_name.to_sym,
-            value_name: value_name.to_sym
-          }
-          self
-        end
-
-        def param(params_hash)
-          ensure_context!
-          @definitions << { type: :param, controller: @current_context, params: params_hash }
-          self
-        end
-
-        def build_definition
-          Definition::Result::Stimulus.new(definitions: @definitions.freeze)
-        end
-
-        private
-
-        def ensure_context!
-          raise "A controller context must be set via .controller() or .context() before this call." unless @current_context
-        end
-      end
-    end
-  end
-end

data/lib/tailmix/dev/stimulus_generator.rb

@@ -1,124 +0,0 @@
-# frozen_string_literal: true
-
-module Tailmix
-  module Dev
-    class StimulusGenerator
-      def initialize(definition, component_name)
-        @definition = definition
-        @component_name = component_name
-        @stimulus_defs = definition.elements.values.flat_map(&:stimulus).flat_map(&:definitions)
-      end
-
-      def scaffold(controller_name = nil, show_docs: false)
-        controllers_to_generate = controller_name ? [ controller_name.to_s ] : all_controllers
-
-        output = controllers_to_generate.map do |name|
-          defs = @stimulus_defs.select { |d| d[:controller] == name }
-
-          show_docs ? generate_docs_for(name, defs) + "\n" : generate_js_for(name, defs) + ("-" * 60) + "\n"
-        end
-        output.join("\n")
-      end
-
-      private
-
-      def generate_docs_for(controller_name, defs)
-        output = [ "Stimulus:" ]
-        output << "  - on `#{controller_name}` controller:"
-        targets = defs.select { |d| d[:type] == :target }.map { |d| d[:name] }
-        output << "    - Targets: #{targets.join(', ')}" if targets.any?
-
-        actions = action_methods(defs)
-        output << "    - Actions: #{actions.join(', ')}" if actions.any?
-
-        values = defs.select { |d| d[:type] == :value }.map { |d| d[:name] }
-        output << "    - Values: #{values.join(', ')}" if values.any?
-
-        output.join("\n")
-      end
-
-      def generate_js_for(controller_name, defs)
-        targets = defs.select { |d| d[:type] == :target }.map { |d| "'#{d[:name]}'" }.uniq.join(", ")
-
-        payload_actions = defs.select { |d| d[:type] == :action_payload }
-        simple_values = defs.select { |d| d[:type] == :value }
-
-        value_names = (payload_actions.map { |d| d[:value_name] } + simple_values.map { |d| d[:name] })
-          .uniq.map { |name| "#{snake_to_camel(name.to_s)}: Object" }.join(", ")
-
-        isomorphic_methods = payload_actions.map do |payload_def|
-          action_name_camel = snake_to_camel(payload_def[:action_name].to_s)
-          value_name_camel = snake_to_camel(payload_def[:value_name].to_s)
-
-          "  #{action_name_camel}(event) {\n     if (event) event.preventDefault();\n     Tailmix.run({ config: this.#{value_name_camel}Value, controller: this });\n  }"
-        end.join.strip
-
-        standard_action_names = defs.select { |d| d[:type] == :action }
-                                    .flat_map { |d| extract_action_methods(d[:data]) }
-                                    .uniq
-
-        implemented_action_names = payload_actions.map { |d| d[:action_name].to_s }
-        stub_methods = (standard_action_names - implemented_action_names).map do |method_name|
-          method_name_camel = snake_to_camel(method_name)
-          "  #{method_name_camel}() {\n    console.log('#{controller_name}##{method_name_camel} fired');\n  }"
-        end.join("\n\n")
-
-        js_methods = [isomorphic_methods, stub_methods].reject(&:empty?).join("\n\n")
-
-        <<~JAVASCRIPT
-          // Generated by Tailmix for the "#{controller_name}" controller
-          // Path: app/javascript/controllers/#{controller_name.tr('_', '-')}_controller.js
-          import { Controller } from "@hotwired/stimulus"
-          import Tailmix from "tailmix"
-
-          export default class extends Controller {
-            static targets = [#{targets}]
-            static values = { #{value_names} }
-
-            connect() {
-              console.log("#{controller_name} controller connected to", this.element);
-            }
-            #{js_methods}
-          }
-        JAVASCRIPT
-      end
-
-      def extract_action_methods(action_data)
-        case action_data[:type]
-        when :raw
-          action_data[:content].to_s.scan(/#(\w+)/).flatten
-        when :hash
-          action_data[:content].values.map(&:to_s)
-        when :tuple
-          [action_data[:content][1].to_s]
-        else
-          []
-        end
-      end
-
-      def all_controllers
-        @stimulus_defs.map { |d| d[:controller] }.compact.uniq
-      end
-
-      def action_methods(defs)
-        defs.select { |d| d[:type] == :action }.flat_map do |action_definition|
-          data = action_definition[:data]
-          case data[:type]
-          when :raw
-            data[:content].to_s.scan(/#(\w+)/).flatten
-          when :hash
-            data[:content].values.map(&:to_s)
-          when :tuple
-            [ data[:content][1].to_s ]
-          else
-            []
-          end
-        end.uniq
-      end
-
-      def snake_to_camel(str)
-        str.split("_").map.with_index { |word, i| i.zero? ? word : word.capitalize }.join
-      end
-    end
-  end
-end

data/lib/tailmix/runtime/stimulus/compiler.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-module Tailmix
-  module Runtime
-    module Stimulus
-      class Compiler
-
-        def self.call(definition:, data_map:, root_definition:, component:)
-          (definition.definitions || []).each do |rule|
-            builder = data_map.stimulus
-
-            case rule[:type]
-            when :controller
-              builder.controller(rule[:name])
-            when :action
-              action_data = rule[:data]
-              controller_name = rule[:controller]
-
-              action_string = case action_data[:type]
-              when :raw
-                action_data[:content]
-              when :hash
-                action_data[:content].map { |event, method| "#{event}->#{controller_name}##{method}" }.join(" ")
-              when :tuple
-                event, method = action_data[:content]
-                "#{event}->#{controller_name}##{method}"
-              end
-
-              builder.context(controller_name).action(action_string)
-            when :target
-              builder.context(rule[:controller]).target(rule[:name])
-            when :value
-              source = rule[:source]
-
-              resolved_value = case source[:type]
-              when :literal
-                source[:content]
-              when :proc
-                source[:content].call
-              when :method
-                component.public_send(source[:content])
-              else
-                # type code here
-              end
-
-              builder.context(rule[:controller]).value(rule[:name], resolved_value)
-
-            when :param
-              builder.context(rule[:controller]).param(rule[:params])
-            when :action_payload
-              action = root_definition.actions.fetch(rule[:action_name])
-              builder.context(rule[:controller]).value(rule[:value_name], action.to_h)
-            end
-          end
-        end
-      end
-    end
-  end
-end