tailmix 0.2.0 → 0.4.6

data/lib/tailmix/dev/stimulus_generator.rb

@@ -0,0 +1,124 @@
+# 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/dev/tools.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "stimulus_generator"
+require_relative "docs"
+
+module Tailmix
+  module Dev
+    class Tools
+      attr_reader :definition, :component_class
+
+      def initialize(component_class)
+        @component_class = component_class
+        @definition = component_class.tailmix_definition
+      end
+
+      def docs
+        Dev::Docs.new(self).generate
+      end
+      alias_method :help, :docs
+
+      def stimulus
+        StimulusGenerator.new(@definition, @component_class.name)
+      end
+
+      def elements
+        @definition.elements.values.map(&:name)
+      end
+    end
+  end
+end

data/lib/tailmix/dsl.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "definition/context_builder"
+require_relative "definition/merger"
+require_relative "dev/tools"
+
+module Tailmix
+  # The main DSL for defining component styles and behaviors.
+  # This module is extended into any class that includes Tailmix.
+  module DSL
+    def tailmix(&block)
+      child_context = Definition::ContextBuilder.new
+      child_context.instance_eval(&block)
+      child_definition = child_context.build_definition
+
+      if superclass.respond_to?(:tailmix_definition) && (parent_definition = superclass.tailmix_definition)
+        @tailmix_definition = Definition::Merger.call(parent_definition, child_definition)
+      else
+        @tailmix_definition = child_definition
+      end
+    end
+
+    def tailmix_definition
+      @tailmix_definition || raise(Error, "Tailmix definition not found in #{name}")
+    end
+
+    def tailmix_facade_class
+      @_tailmix_facade_class ||= Runtime::FacadeBuilder.build(tailmix_definition)
+    end
+
+    def dev
+      Dev::Tools.new(self)
+    end
+  end
+end

data/lib/tailmix/engine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Tailmix
+  class Engine < ::Rails::Engine
+    config.before_initialize do
+      Rails.application.config.assets.paths << Engine.root.join("app/javascript")
+    end
+
+    PRECOMPILE_ASSETS = %w[ index.js runner.js finder.js mutator.js stimulus_adapter.js ]
+
+    initializer "tailmix.assets" do
+      if Rails.application.config.respond_to?(:assets)
+        Rails.application.config.assets.precompile += PRECOMPILE_ASSETS
+      end
+    end
+  end
+end

data/lib/tailmix/html/attributes.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "erb"
+require_relative "class_list"
+require_relative "data_map"
+require_relative "selector"
+
+module Tailmix
+  module HTML
+    class Attributes < Hash
+      attr_reader :element_name, :variant_string
+
+      def initialize(initial_hash = {}, element_name: nil, variant_string: "")
+        @element_name = element_name
+        @variant_string = variant_string
+        super()
+
+        attrs_to_merge = initial_hash.dup
+
+        initial_classes = attrs_to_merge.delete(:class)
+        initial_data = attrs_to_merge.delete(:data)
+        initial_aria = attrs_to_merge.delete(:aria)
+
+        self[:class] = ClassList.new(initial_classes)
+        self[:data]  = DataMap.new("data", initial_data || {})
+        self[:aria]  = DataMap.new("aria", initial_aria || {})
+        self[:tailmix] = Selector.new(element_name, variant_string)
+
+        merge!(attrs_to_merge)
+      end
+
+      def each(&block)
+        to_h.each(&block)
+      end
+
+      def to_h
+        final_attrs = select { |k, _| !%i[class data aria tailmix].include?(k.to_sym) }
+
+        class_string = self[:class].to_s
+        final_attrs[:class] = class_string unless class_string.empty?
+
+        final_attrs.merge!(self[:data].to_h)
+        final_attrs.merge!(self[:aria].to_h)
+        final_attrs.merge!(self[:tailmix].to_h)
+
+        final_attrs
+      end
+      alias_method :to_hash, :to_h
+
+      def to_s
+        classes.to_s
+      end
+
+      def classes
+        self[:class]
+      end
+
+      def data
+        self[:data]
+      end
+
+      def aria
+        self[:aria]
+      end
+
+      def stimulus
+        data.stimulus
+      end
+
+      def tailmix
+        self[:tailmix]
+      end
+
+      def toggle(class_names)
+        classes.toggle(class_names)
+        self
+      end
+
+      def add(class_names)
+        classes.add(class_names)
+        self
+      end
+
+      def remove(class_names)
+        classes.remove(class_names)
+        self
+      end
+
+      def each_attribute(&block)
+        [ classes: classes, data: data.to_h, aria: aria.to_h, tailmix: tailmix.to_h ].each(&block)
+      end
+    end
+  end
+end

data/lib/tailmix/html/class_list.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Tailmix
+  module HTML
+    # Manages a set of CSS classes with a fluent, chainable API.
+    # Inherits from Set to ensure uniqueness and leverage its performance.
+    class ClassList < Set
+      # Initializes a new ClassList.
+      # @param initial_classes [String, Array, Set, nil] The initial classes to add.
+      def initialize(initial_classes = nil)
+        super()
+        add(initial_classes) if initial_classes
+      end
+
+      # Adds one or more classes. Handles strings, arrays, or other sets.
+      # This method is MUTABLE and chainable.
+      # @param class_names [String, Array, Set, nil]
+      # @return [self]
+      def add(class_names)
+        each_token(class_names) { |token| super(token) }
+        self
+      end
+      alias << add
+
+      # Removes one or more classes.
+      # This method is MUTABLE and chainable.
+      # @param class_names [String, Array, Set, nil]
+      # @return [self]
+      def remove(class_names)
+        each_token(class_names) { |token| delete(token) }
+        self
+      end
+
+      # Toggles one or more classes.
+      # This method is MUTABLE and chainable.
+      # @param class_names [String, Array, Set, nil]
+      # @return [self]
+      def toggle(class_names)
+        each_token(class_names) { |token| include?(token) ? delete(token) : add(token) }
+        self
+      end
+
+      # Returns a new ClassList with the given classes added. IMMUTABLE.
+      def added(class_names)
+        dup.add(class_names)
+      end
+
+      # Returns a new ClassList with the given classes removed. IMMUTABLE.
+      def removed(class_names)
+        dup.remove(class_names)
+      end
+
+      # Returns a new ClassList with the given classes toggled. IMMUTABLE.
+      def toggled(class_names)
+        dup.toggle(class_names)
+      end
+
+      # Renders the set of classes to a space-separated string for HTML.
+      # @return [String]
+      def to_s
+        to_a.join(" ")
+      end
+
+      private
+
+      # A robust way to iterate over tokens from various input types.
+      def each_token(input)
+        return unless input
+        # Convert Set/ClassList to array before splitting strings inside
+        items = input.is_a?(Set) ? input.to_a : Array(input)
+        items.each do |item|
+          item.to_s.split.each { |token| yield token unless token.empty? }
+        end
+      end
+    end
+  end
+end

data/lib/tailmix/html/data_map.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+require_relative "stimulus_builder"
+
+module Tailmix
+  module HTML
+    class DataMap
+      MERGEABLE_LIST_ATTRIBUTES = %i[controller action target].freeze
+
+      def initialize(prefix, initial_data = {})
+        @prefix = prefix
+        @data = {}
+        merge!(initial_data)
+      end
+
+      def stimulus
+        raise "Stimulus builder is only available for data attributes" unless @prefix == "data"
+        StimulusBuilder.new(self)
+      end
+
+      def merge!(other_data)
+        return self unless other_data
+        data_to_merge = other_data.is_a?(DataMap) ? other_data.instance_variable_get(:@data) : other_data
+
+        (data_to_merge || {}).each do |key, value|
+          key = key.to_sym
+          if value.is_a?(Hash) && @data[key].is_a?(Hash)
+            @data[key].merge!(value)
+          elsif @prefix == "data" && MERGEABLE_LIST_ATTRIBUTES.include?(key)
+            add_to_set(key, value)
+          else
+            @data[key] = value
+          end
+        end
+        self
+      end
+      alias_method :add, :merge!
+
+      def merge(other_data)
+        dup.merge!(other_data)
+      end
+
+      def add_to_set(key, value)
+        @data[key] ||= Set.new
+        return unless value
+        items_to_process = value.is_a?(Set) ? value.to_a : Array(value)
+        items_to_process.each do |item|
+          item.to_s.split.each do |token|
+            @data[key].add(token) unless token.empty?
+          end
+        end
+      end
+
+      def remove(other_data)
+        (other_data || {}).each do |key, _|
+          @data.delete(key.to_sym)
+        end
+        self
+      end
+
+      def toggle(other_data)
+        (other_data || {}).each do |key, value|
+          key = key.to_sym
+          @data[key] == value ? @data.delete(key) : @data[key] = value
+        end
+        self
+      end
+
+      def to_h
+        flatten_data_hash(@data, @prefix)
+      end
+
+      private
+
+      def flatten_data_hash(hash, prefix, accumulator = {})
+        hash.each do |key, value|
+          current_key = "#{prefix}-#{key.to_s.tr('_', '-')}"
+          if @prefix == "data" && key.to_s.end_with?("_value")
+            serialized_value = case value
+            when Hash, Array then value.to_json
+            else value
+            end
+            accumulator[current_key] = serialized_value
+          elsif value.is_a?(Hash)
+            flatten_data_hash(value, current_key, accumulator)
+          else
+            serialized_value = value.is_a?(Set) ? value.to_a.join(" ") : value
+            accumulator[current_key] = serialized_value unless serialized_value.to_s.empty?
+          end
+        end
+        accumulator
+      end
+    end
+  end
+end

data/lib/tailmix/html/selector.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module HTML
+    class Selector
+      def initialize(element_name, variant_string)
+        @element_name = element_name
+        @variant_string = variant_string
+      end
+
+      def to_h
+        return {} unless @element_name
+
+        key = "data-tailmix-#{@element_name}"
+        { key => @variant_string }
+      end
+    end
+  end
+end

data/lib/tailmix/html/stimulus_builder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module HTML
+    # A fluent DSL (builder) for constructing Stimulus data attributes.
+    # It acts as a proxy, modifying a DataMap instance directly.
+    class StimulusBuilder
+      def initialize(data_map)
+        @data_map = data_map
+        @context = nil # For context-aware attributes like targets and values
+      end
+
+      # Defines a controller and sets it as the current context.
+      # @return [self] for chaining.
+      def controller(controller_name)
+        @data_map.add_to_set(:controller, controller_name)
+        @context = controller_name.to_s
+        self
+      end
+
+      # Sets the controller context for subsequent calls.
+      def context(controller_name)
+        @context = controller_name.to_s
+        self
+      end
+
+      # Adds an action.
+      # @example
+      #   .action("click->modal#open")
+      # @return [self]
+      def action(action_string)
+        @data_map.add_to_set(:action, action_string)
+        self
+      end
+
+      # Adds a target, scoped to the current controller context.
+      # @return [self]
+      def target(target_name)
+        ensure_context!
+        # `target` is a shared attribute, but names are scoped to a controller.
+        # So we add to the common `target` set.
+        @data_map.add_to_set(:"#{@context}-target", target_name)
+        self
+      end
+
+      # Adds a value, scoped to the current controller context.
+      # @return [self]
+      def value(value_name, value)
+        ensure_context!
+        @data_map.merge!("#{context_key(value_name)}_value" => value)
+        self
+      end
+
+      private
+
+      def ensure_context!
+        raise "A controller context must be set via .controller() or .context() before this call." unless @context
+      end
+
+      def context_key(name)
+        "#{@context}-#{name.to_s.tr('_', '-')}"
+      end
+    end
+  end
+end

data/lib/tailmix/runtime/action.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module Runtime
+    # Represents a callable action at runtime that can apply a set of
+    # predefined mutations to its context.
+    class Action
+      attr_reader :context, :definition
+
+      def initialize(context, action_name)
+        @context = context
+        @action_name = action_name.to_sym
+        @definition = context.definition.actions[@action_name]
+        raise Error, "Action `#{@action_name}` not found." unless @definition
+      end
+
+      # Applies the mutations to the context immutably, returning a new context.
+      # @return [Context] A new, modified context instance.
+      def apply
+        new_context = context.dup
+
+        action_on_clone = self.class.new(new_context, @action_name)
+
+        action_on_clone.apply!
+      end
+
+      def apply!
+        # `definition.mutations`  { element_name => [commands] }
+        definition.mutations.each do |element_name, commands|
+          attributes_object = context.live_attributes_for(element_name)
+          next unless attributes_object
+
+          commands.each do |command|
+            target_field = attributes_object.public_send(command[:field])
+            target_field.public_send(command[:method], command[:payload])
+          end
+        end
+        context
+      end
+
+      # Serializes the action's definition into a hash for the JS bridge.
+      # @return [Hash]
+      def to_h
+        {
+          method: definition.action,
+          mutations: definition.mutations
+        }
+      end
+    end
+  end
+end

data/lib/tailmix/runtime/context.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module Runtime
+    class Context
+      attr_reader :component_instance, :definition, :dimensions
+
+      def initialize(component_instance, definition, dimensions)
+        @component_instance = component_instance
+        @definition = definition
+        @dimensions = dimensions
+        @attributes_cache = {}
+      end
+
+      def initialize_copy(source)
+        super
+        @attributes_cache = source.instance_variable_get(:@attributes_cache).transform_values(&:dup)
+      end
+
+      def live_attributes_for(element_name)
+        @attributes_cache[element_name] ||= build_attributes_for(element_name, @dimensions)
+      end
+
+      def attributes_for(element_name, runtime_dimensions = {})
+        merged_dimensions = @dimensions.merge(runtime_dimensions)
+        return @attributes_cache[element_name] if merged_dimensions == @dimensions && @attributes_cache[element_name]
+
+        attributes_object = build_attributes_for(element_name, merged_dimensions)
+        @attributes_cache[element_name] = attributes_object if merged_dimensions == @dimensions
+        attributes_object
+      end
+
+      def action(name)
+        Action.new(self, name)
+      end
+
+      private
+
+      def build_attributes_for(element_name, dimensions)
+        element_def = @definition.elements.fetch(element_name)
+
+        active_dimensions = dimensions.slice(*element_def.dimensions.keys)
+        variant_string = active_dimensions.map { |k, v| "#{k}:#{v}" }.join(",")
+
+        attributes = HTML::Attributes.new(
+          { 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])
+          next if value.nil?
+
+          variant_def = dim_def.fetch(:variants, {}).fetch(value, nil)
+          next unless variant_def
+
+          attributes.classes.add(variant_def.classes)
+          attributes.data.merge!(variant_def.data)
+          attributes.aria.merge!(variant_def.aria)
+        end
+
+        Stimulus::Compiler.call(
+          definition: element_def.stimulus,
+          data_map: attributes.data,
+          root_definition: @definition,
+          component: @component_instance
+        )
+
+        attributes
+      end
+    end
+  end
+end