tailmix 0.2.0 → 0.4.6

data/lib/generators/tailmix/install_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Tailmix
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      def add_javascript
+        say "Pinning Tailmix JavaScript", :green
+        append_to_file "config/importmap.rb", <<~RUBY
+          pin "tailmix", to: "tailmix/index.js"
+        RUBY
+
+        say "Adding Tailmix to asset manifest", :green
+        append_to_file "app/assets/config/manifest.js", "\n//= link tailmix/index.js.js\n"
+      end
+    end
+  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

@@ -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, 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
+
+          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,34 @@
+# frozen_string_literal: true
+
+require_relative "variant_builder"
+
+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 build_dimension
+          {
+            default: @default,
+            variants: @variants.freeze
+          }
+        end
+      end
+    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)
+          builder = Contexts::DimensionBuilder.new(default: default)
+          builder.instance_eval(&block)
+          @dimensions[name.to_sym] = builder.build_dimension
+        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/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

@@ -0,0 +1,86 @@
+# 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
+
+      def merge_dimensions(parent_dims, child_dims)
+        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, {}))
+
+            default = child_val.key?(:default) ? child_val[:default] : parent_val[:default]
+
+            merged[key] = { default: default, variants: merged_variants }
+          else
+            merged[key] = parent_val || child_val
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tailmix/definition/result.rb

@@ -0,0 +1,78 @@
+# 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.transform_values do |dimension|
+              dimension.transform_values do |value|
+                case value
+                when Variant
+                  value.to_h
+                when Hash
+                  value.transform_values { |v| v.respond_to?(:to_h) ? v.to_h : v }
+                else
+                  value
+                end
+              end
+            end,
+            stimulus: stimulus.to_h
+          }
+        end
+      end
+
+      Variant = Struct.new(:class_groups, :data, :aria, keyword_init: true) do
+        def classes
+          class_groups.flat_map { |group| group[:classes] }
+        end
+
+        def to_h
+          {
+            classes: classes,
+            class_groups: class_groups,
+            data: data,
+            aria: aria
+          }
+        end
+      end
+
+      Attributes = Struct.new(:classes, keyword_init: true) do
+        def to_h
+          {
+            classes: classes
+          }
+        end
+      end
+
+      Stimulus = Struct.new(:definitions, keyword_init: true) do
+        def to_h
+          {
+            definitions: definitions
+          }
+        end
+      end
+
+      Action = Struct.new(:action, :mutations, keyword_init: true) do
+        def to_h
+          {
+            action: action,
+            mutations: mutations
+          }
+        end
+      end
+    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,88 @@
+# 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[:variants].each do |variant_name, variant_def|
+              output << "    - #{variant_name.inspect}:"
+              variant_def.class_groups.each do |group|
+                label = group[:options][:group] ? "(group: :#{group[:options][:group]})" : ""
+                output << "      - classes #{label}: \"#{group[:classes].join(' ')}\""
+              end
+              output << "      - data: #{variant_def.data.inspect}" if variant_def.data.any?
+              output << "      - aria: #{variant_def.aria.inspect}" if variant_def.aria.any?
+            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