tailmix 0.2.0 → 0.4.5

data/lib/tailmix/definition/context_builder.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "contexts/action_builder"
+require_relative "contexts/element_builder"
+
+module Tailmix
+  module Definition
+    class ContextBuilder
+      attr_reader :elements, :actions
+
+      def initialize
+        @elements = {}
+        @actions = {}
+      end
+
+      def element(name, base_classes = "", &block)
+        builder = Contexts::ElementBuilder.new(name)
+        builder.attributes.classes(base_classes.split)
+
+        builder.instance_eval(&block) if block
+
+        @elements[name.to_sym] = builder
+      end
+
+      def action(name, method:, &block)
+        builder = Contexts::ActionBuilder.new(method)
+        builder.instance_eval(&block) if block
+        @actions[name.to_sym] = builder
+      end
+
+      def build_definition
+        Definition::Result::Context.new(
+          elements: @elements.transform_values(&:build_definition).freeze,
+          actions: @actions.transform_values(&:build_definition).freeze
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# 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/actions/element_builder.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module Definition
+    module Contexts
+      module Actions
+        class ElementBuilder
+          def initialize(default_method)
+            @default_method = default_method
+            @commands = []
+          end
+
+          def classes(classes_string, 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
+
+          def build_commands
+            @commands
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module Definition
+    module Contexts
+      class AttributeBuilder
+        def initialize
+          @classes = []
+        end
+
+        def classes(*list)
+          @classes.concat(list.flatten.map(&:to_s))
+        end
+
+        def build_definition
+          Definition::Result::Attributes.new(classes: @classes.freeze)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class DimensionBuilder
+  attr_reader :options
+
+  def initialize(default: nil)
+    @options = { options: {}, default: default }
+  end
+
+  def option(value, classes, default: false)
+    @options[:options][value] = classes.split
+    if default && @options[:default].nil?
+      @options[:default] = value
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "attribute_builder"
+require_relative "stimulus_builder"
+require_relative "dimension_builder"
+
+module Tailmix
+  module Definition
+    module Contexts
+      class ElementBuilder
+        def initialize(name)
+          @name = name
+          @dimensions = {}
+        end
+
+        def attributes
+          @attributes_builder ||= AttributeBuilder.new
+        end
+
+        def stimulus
+          @stimulus_builder ||= StimulusBuilder.new
+        end
+
+        def dimension(name, default: nil, &block)
+          dimension = DimensionBuilder.new(default: default)
+          dimension.instance_eval(&block)
+          @dimensions[name.to_sym] = dimension.options
+        end
+
+        def build_definition
+          Definition::Result::Element.new(
+            name: @name,
+            attributes: attributes.build_definition,
+            stimulus: stimulus.build_definition,
+            dimensions: @dimensions.freeze
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# 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/definition/merger.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module Definition
+    # A service object responsible for deep-merging two tailmix definitions.
+    class Merger
+      def self.call(parent_def, child_def)
+        new(parent_def, child_def).merge
+      end
+
+      def initialize(parent_def, child_def)
+        @parent_def = parent_def
+        @child_def = child_def
+      end
+
+      def merge
+        Result::Context.new(
+          elements: merged_elements,
+          actions: merged_actions
+        )
+      end
+
+      private
+
+      def merged_actions
+        # For actions, child definitions completely override parent definitions.
+        @parent_def.actions.merge(@child_def.actions)
+      end
+
+      def merged_elements
+        all_element_keys = (@parent_def.elements.keys | @child_def.elements.keys)
+
+        all_element_keys.each_with_object({}) do |key, h|
+          parent_element = @parent_def.elements[key]
+          child_element = @child_def.elements[key]
+
+          h[key] = if parent_element && child_element
+            merge_element(parent_element, child_element)
+          else
+            child_element || parent_element
+          end
+        end
+      end
+
+      def merge_element(parent_el, child_el)
+        Result::Element.new(
+          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)
+        )
+      end
+
+      def merge_attributes(parent_attrs, child_attrs)
+        # Combine base classes, ensuring no duplicates.
+        combined_classes = (parent_attrs.classes + child_attrs.classes).uniq
+        Result::Attributes.new(classes: combined_classes)
+      end
+
+      def merge_stimulus(parent_stimulus, child_stimulus)
+        # Combine stimulus definitions.
+        combined_definitions = parent_stimulus.definitions + child_stimulus.definitions
+        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
+
+      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]
+
+          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)
+          else
+            child_val
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tailmix/definition/result.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module Definition
+    module Result
+      Context = Struct.new(:elements, :actions, keyword_init: true) do
+        def to_h
+          {
+            elements: elements.transform_values(&:to_h),
+            actions: actions.transform_values(&:to_h)
+          }
+        end
+      end
+
+      Element = Struct.new(:name, :attributes, :dimensions, :stimulus, keyword_init: true) do
+        def to_h
+          {
+            name: name,
+            attributes: attributes.to_h,
+            dimensions: dimensions,
+            stimulus: stimulus.to_h
+          }
+        end
+      end
+
+      Attributes = Struct.new(:classes, keyword_init: true)
+      Stimulus = Struct.new(:definitions, keyword_init: true)
+      Action = Struct.new(:action, :mutations, keyword_init: true)
+    end
+  end
+end

data/lib/tailmix/definition.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "definition/result"
+require_relative "definition/merger"
+require_relative "definition/context_builder"
+
+module Tailmix
+  module Definition
+
+  end
+end

data/lib/tailmix/dev/docs.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Tailmix
+  module Dev
+    class Docs
+
+      def initialize(tools)
+        @tools = tools
+        @definition = tools.definition
+        @component_class_name = tools.component_class
+      end
+
+      def generate
+        output = ["== Tailmix Docs for #{@component_class_name} =="]
+
+        signature = generate_signature
+        output << "Signature: `initialize(#{signature})`" unless signature.empty?
+        output << ""
+
+        output << generate_dimensions_docs
+        output << ""
+        output << generate_actions_docs
+        output << ""
+        output << generate_stimulus_docs
+
+        output.join("\n")
+      end
+
+      private
+
+      def generate_signature
+        all_dimensions
+          .map { |name, config| "#{name}: #{config[:default].inspect}" if config.key?(:default) }
+          .compact
+          .join(", ")
+      end
+
+      def generate_dimensions_docs
+        output = []
+
+        if all_dimensions.any?
+          output << "Dimensions:"
+          all_dimensions.each do |dim_name, config|
+            default_info = config[:default] ? "(default: #{config[:default].inspect})" : ""
+            output << "  - #{dim_name} #{default_info}"
+            config[:options].each do |option_key, option_value|
+              output << "    - #{option_key.inspect}: \"#{option_value.join(' ')}\""
+            end
+          end
+        else
+          output << "No dimensions defined."
+        end
+
+        output.join("\n")
+      end
+
+      def generate_actions_docs
+        output = []
+        actions = @definition.actions
+
+        if actions.any?
+          output << "Actions:"
+          actions.keys.each do |action_name|
+            output << "  - :#{action_name}"
+          end
+        else
+          output << "No actions defined."
+        end
+
+        output.join("\n")
+      end
+
+      def generate_stimulus_docs
+        @tools.stimulus.scaffold(show_docs: true)
+      end
+
+      def all_dimensions
+        @_all_dimensions ||= @definition.elements.values.flat_map(&:dimensions).reduce({}, :merge)
+      end
+    end
+  end
+end

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,26 @@
+# 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
+    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