loco_motion-rails 0.0.6

data/lib/loco_motion/base_component.rb

@@ -0,0 +1,371 @@
+class LocoMotion::BaseComponent < ViewComponent::Base
+
+  SELF_CLOSING_TAGS = %i[area base br col embed hr img input keygen link meta param source track wbr].freeze
+
+  include Heroicons::IconsHelper
+
+  class_attribute :component_name
+  class_attribute :component_parts, default: { component: {} }
+  class_attribute :valid_modifiers, default: []
+  class_attribute :valid_sizes, default: []
+
+  #
+  # Return the current configruation of this component.
+  #
+  # @return LocoMotion::ComponentConfig
+  #
+  attr_reader :config
+
+  #
+  # Allow users to alter the config through the component itself
+  #
+  delegate :set_tag_name, :add_css, :add_html, :add_stimulus_controller, :modifiers,
+    to: :config
+
+  #
+  # Create a new instance of a component.
+  #
+  def initialize(*args, **kws, &block)
+    super
+
+    # Create our config object
+    @config = LocoMotion::ComponentConfig.new(self, **kws, &block)
+  end
+
+  #
+  # Override the default slot to render the BasicComponent if no component is
+  # provided.
+  #
+  def self.renders_one(*args)
+    # If they don't pass extra options, default to BasicComponent
+    args&.size == 1 ?  super(*args + [LocoMotion::BasicComponent]) : super
+  end
+
+  #
+  # Override the default many slot to render the BasicComponent if no component
+  # is provided.
+  #
+  def self.renders_many(*args)
+    # If they don't pass extra options, default to BasicComponent
+    args&.size == 1 ?  super(*args + [LocoMotion::BasicComponent]) : super
+  end
+
+  #
+  # Sets the component name used in CSS generation.
+  #
+  # @param component_name [Symbol,String] The name of the component.
+  #
+  def self.set_component_name(component_name)
+    self.component_name = component_name
+  end
+
+  #
+  # Defines a new part of this component which can customize CSS, HTML and more.
+  #
+  # @param part_name [Symbol] The name of the part.
+  # @param part_defaults [Hash] Any default config options such as `tag_name`.
+  #
+  def self.define_part(part_name, part_defaults = {})
+    # Note that since we're using Rails' class_attribute method for these, we
+    # must take care not to alter the original object but rather use a setter
+    # (the `=` in this case) to set the new value so Rails knows not to override
+    # the parent value.
+    #
+    # For example, we cannot use `merge!` or `[part_name] = ` here.
+    self.component_parts = component_parts.merge({ part_name => part_defaults })
+  end
+
+  #
+  # Convenience method for defining multiple parts at once with no defaults.
+  #
+  # @param part_names [Array<Symbol>] The names of the parts you wish to define.
+  #
+  def self.define_parts(*part_names)
+    (part_names || []).each do |part_name|
+      define_part(part_name)
+    end
+  end
+
+  #
+  # Defines a single modifier of this component. Modifiers control certain
+  # rendering aspects of the component.
+  #
+  # @param modifier_name [Symbol] The name of the modifier.
+  #
+  def self.define_modifier(modifier_name)
+    define_modifiers(modifier_name)
+  end
+
+  #
+  # Define multiple modifiers for this component. Modifiers control certain
+  # rendering aspects of the component.
+  #
+  # @param modifier_names [Array[Symbol]] An array of the modifier names you wish
+  #   to define.
+  #
+  def self.define_modifiers(*modifier_names)
+    # Note that since we're using Rails' class_attribute method for these, we
+    # must take care not to alter the original object but rather use a setter
+    # (the `+=` in this case) to set the new value so Rails knows not to
+    # override the parent value.
+    #
+    # For example, we cannot use `<<` or `concat` here.
+    self.valid_modifiers ||= []
+    self.valid_modifiers += modifier_names
+  end
+
+  #
+  # Define a single size of this component. Sizes control how big or small this
+  # component will render.
+  #
+  # @param size_name [Symbol] The name of the size you wish to define.
+  #
+  def self.define_size(size_name)
+    define_sizes(size_name)
+  end
+
+  #
+  # Define multiple sizes for this component. Sizes control how big or small
+  # this component will render.
+  #
+  # @param size_names [Array[Symbol]] An array of the sizes you wish to define.
+  #
+  def self.define_sizes(*size_names)
+    # Note that since we're using Rails' class_attribute method for these, we
+    # must take care not to alter the original object but rather use a setter
+    # (the `+=` in this case) to set the new value so Rails knows not to
+    # override the parent value.
+    #
+    # For example, we cannot use `<<` or `concat` here.
+    self.valid_sizes ||= []
+    self.valid_sizes += size_names
+  end
+
+  #
+  # Allows you to bulid a customized version of this component without having to
+  # define a new class.
+  #
+  def self.build(*build_args, **build_kws, &build_block)
+    klass = Class.new(self)
+
+    # Unless already defined, delegate the name method to the superclass so
+    # ViewComponent can find the sidecar partials and render them when no call
+    # method is defined.
+    unless klass.method_defined?(:name)
+      klass.instance_eval do
+        def name
+          superclass.name
+        end
+      end
+    end
+
+    # Override the initialize method to combine the build and instance args
+    klass.class_eval do
+      original_initialize = method_defined?(:initialize) ? instance_method(:initialize) : nil
+
+      define_method(:initialize) do |*instance_args, **instance_kws, &instance_block|
+        if original_initialize
+          original_initialize.bind(self).call
+        else
+          super(*instance_args, **instance_kws, &instance_block)
+        end
+
+        @config.smart_merge!(**build_kws)
+      end
+    end
+
+    # Finally, execute any block they passed in to allow for customizations
+    klass.class_eval(&build_block) if block_given?
+
+    klass
+  end
+
+  #
+  # Returns a reference to this component. Useful for passing a parent component
+  # into child components.
+  #
+  # @return [BaseComponent] A reference to this component.
+  #
+  def component_ref
+    self
+  end
+
+
+  #
+  # Sets the parent component of this component. Enables child components to ask
+  # questions of their parent and access parent config.
+  #
+  def set_loco_parent(parent)
+    @loco_parent = parent
+  end
+  attr_reader :loco_parent
+
+  #
+  # Renders the given part.
+  #
+  def part(part_name, &block)
+
+    # Validate the part_name
+    @config.validate_part(part_name)
+
+    # Grab the rendered tag name
+    tag_name = rendered_tag_name(part_name)
+
+    if block_given?
+      content_tag(tag_name, **rendered_html(part_name), &block)
+    else
+      # The `tag()` helper will allow you to pass any tag without a block, but
+      # this isn't valid HTML. In particular, it will render a "self-closing"
+      # <div /> tag which doesn't actually close the div.
+      #
+      # Therefore, we need to pass some kind of block to ensure it closes. We've
+      # choosen a comment to keep the output as clean as possible while still
+      # informing a developer what is happening.
+      if SELF_CLOSING_TAGS.include?(tag_name.to_sym)
+        tag(tag_name, **rendered_html(part_name))
+      else
+        content_tag(tag_name, **rendered_html(part_name)) do
+          "<!-- Empty Part Block //-->".html_safe
+        end
+      end
+    end
+  end
+
+  #
+  # Returns the user-provided or component-default HTML tag-name.
+  #
+  # @param part_name [Symbol] The part whose tag-name you desire.
+  #
+  # @return [Symbol,String] The HTML tag-name for the requested comopnent part.
+  #
+  def rendered_tag_name(part_name)
+    part = @config.get_part(part_name)
+
+    part[:user_tag_name] || part[:default_tag_name]
+  end
+
+  #
+  # Builds a string suitable for the HTML element's `class` attribute for the
+  # requested component part.
+  #
+  # @param part_name [Symbol] The component part whose CSS you desire.
+  #
+  # @return [String] A string of CSS names.
+  #
+  def rendered_css(part_name)
+    default_css = @config.get_part(part_name)[:default_css]
+    user_css = @config.get_part(part_name)[:user_css]
+
+    cssify([default_css, user_css])
+  end
+
+  #
+  # Builds a Hash of all of the HTML attributes for the requested component
+  # part.
+  #
+  # @param part_name [Symbol] The component part whose HTML you desire.
+  #
+  # @return [Hash] A combination of all generated, component default, and
+  #   user-specified HTML attributes for the part.
+  #
+  def rendered_html(part_name)
+    default_html = @config.get_part(part_name)[:default_html] || {}
+    user_html = @config.get_part(part_name)[:user_html] || {}
+
+    generated_html = {
+      class: rendered_css(part_name),
+      data: rendered_data(part_name)
+    }.deep_merge(default_html).deep_merge(user_html)
+  end
+
+  #
+  # Builds the HTML `data` attribute.
+  #
+  # @param part_name [Symbol] The component part whose HTML `data` attribute
+  #   you desire.
+  #
+  # @return [Hash] A hash of objects to be rendered in the `data` attribute.
+  #
+  def rendered_data(part_name)
+    generated_data = {}
+
+    stimulus_controllers = rendered_stimulus_controllers(part_name)
+
+    generated_data[:controller] = stimulus_controllers if stimulus_controllers.present?
+
+    generated_data
+  end
+
+  #
+  # Builds a list of Stimulus controllers for the HTML `data-controller`
+  # attribute.
+  #
+  # @param part_name [Symbol] The component part whose Stimulus controllers you
+  #   desire.
+  #
+  # @ return [String] A space-separated list of Stimulus controllers.
+  #
+  def rendered_stimulus_controllers(part_name)
+    default_controllers = @config.get_part(part_name)[:default_stimulus_controllers]
+    user_controllers = @config.get_part(part_name)[:user_stimulus_controllers]
+
+    strip_spaces([default_controllers, user_controllers].join(" "))
+  end
+
+  #
+  # Convert strings, symbols, and arrays of those into a single CSS-like string.
+  #
+  def cssify(content)
+    css = [content].flatten.compact
+
+    strip_spaces(css.join(" "))
+  end
+
+  #
+  # Strip extra whitespace from a given string.
+  #
+  # @param str [String] The string you wish to strip.
+  #
+  # @return [String] A string with minimal possible whitespace.
+  #
+  def strip_spaces(str)
+    str.gsub(/ +/, " ").strip
+  end
+
+  #
+  # Retrieve the requested component option, or the desired default if no option
+  # was provided.
+  #
+  # @param key [Symbol] The name of the keyword argument option you wish to
+  #   retrieve.
+  # @param default [Object] Any value that you wish to use as a default should
+  #   the option be undefined. Defaults to `nil`.
+  #
+  def config_option(key, default = nil)
+    value = @config.options[key]
+
+    value.nil? ? default : value
+  end
+
+  # Provide some nice output for debugging or other purposes.
+  #
+  def inspect
+    parts = component_parts.map do |part_name, part_defaults|
+      {
+        part_name: part_name,
+        tag_name: rendered_tag_name(part_name),
+        css: rendered_css(part_name),
+        html: rendered_html(part_name)
+      }
+    end
+
+    [
+      "#<#{self.class.name}",
+      "@component_name=#{(component_name || :unnamed).inspect}",
+      "@valid_modifiers=#{valid_modifiers.inspect}",
+      "@valid_sizes=#{valid_sizes.inspect}",
+      "@config=#{@config.inspect}",
+      "@component_parts=#{parts.inspect}",
+    ].join(" ") + ">"
+  end
+end

data/lib/loco_motion/basic_component.rb

@@ -0,0 +1,18 @@
+#
+# The BasicComponent class is used for all slots that don't provide a component
+# so that users can pass in all of the same CSS and HTML options that a standard
+# component would have.
+#
+class LocoMotion::BasicComponent < LocoMotion.configuration.base_component_class
+
+  def call
+    part(:component) do
+      content
+    end
+  end
+
+  def self.name
+    "BasicComponent"
+  end
+
+end

data/lib/loco_motion/component_config.rb

@@ -0,0 +1,165 @@
+class LocoMotion::ComponentConfig
+  attr_reader :component, :parts, :options, :modifiers, :size
+
+  def initialize(component, **kws, &block)
+    @component = component
+    @options = kws
+
+    @parts = {}
+    @modifiers = (kws[:modifiers] || [kws[:modifier]]).compact
+    @size = kws[:size]
+
+    build
+    validate
+  end
+
+  def build
+    # Allow users to pass css/html for a specific part (i.e. modal_dialog)
+    @component.component_parts.each do |part, defaults|
+      @parts[part] = {
+        default_css: [],
+        default_html: {},
+        default_tag_name: defaults[:tag_name] || :div,
+        default_stimulus_controllers: [],
+
+        user_css: @options["#{part}_css".to_sym] || [],
+        user_html: @options["#{part}_html".to_sym] || {},
+        user_tag_name: @options["#{part}_tag_name".to_sym],
+        user_stimulus_controllers: @options["#{part}_controllers".to_sym] || [],
+      }
+    end
+
+    # Allow useres to pass some shortened attributes for the component part
+    merge_user_options!(**@options)
+  end
+
+  #
+  # Add specific component user options if they pass shortened attributes.
+  #
+  def merge_user_options!(**kws)
+    @parts[:component][:user_tag_name] = kws[:tag_name] if kws[:tag_name]
+    @parts[:component][:user_css].push(kws[:css]) if kws[:css]
+    @parts[:component][:user_html].deep_merge!(kws[:html]) if kws[:html]
+    @parts[:component][:user_stimulus_controllers].push(kws[:controllers]) if kws[:controllers]
+  end
+
+  #
+  # Merge additional options into the defaults config by combining the new
+  # options with the existing options, rather than overwriting (where possible).
+  #
+  # HTML will be deep merged, CSS will be appended, and tag_name will be
+  # overwritten.
+  #
+  def smart_merge!(**kws)
+    @component.component_parts.each do |part, defaults|
+      set_tag_name(part, kws["#{part}_tag_name".to_sym])
+      add_css(part, kws["#{part}_css".to_sym])
+      add_html(part, kws["#{part}_html".to_sym])
+
+      controllers = kws["#{part}_controllers".to_sym] || []
+
+      controllers.each do |controller_name|
+        add_stimulus_controller(part, controller_name)
+      end
+    end
+
+    # Make sure to merge any user-provided options as well
+    merge_user_options!(**kws)
+  end
+
+  #
+  # Returns the part for the reqeust part name or an empty hash if none was
+  # found.
+  #
+  def get_part(part_name)
+    @parts[part_name] || {}
+  end
+
+  #
+  # Sets the default tag name for the requested component part.
+  #
+  def set_tag_name(part_name, tag_name)
+    @parts[part_name][:default_tag_name] = tag_name if tag_name
+  end
+
+  #
+  # Adds default CSS to the requested component part.
+  #
+  def add_css(part_name, css)
+    @parts[part_name][:default_css] << css if css
+  end
+
+  #
+  # Adds default HTML to the requested component part.
+  #
+  def add_html(part_name, html)
+    @parts[part_name][:default_html] = @parts[part_name][:default_html].deep_merge(html) if html
+  end
+
+  #
+  # Add a default Stimulus (Javascript) controller to the requested component part.
+  #
+  def add_stimulus_controller(part_name, controller_name)
+    @parts[part_name] ||= {}
+    @parts[part_name][:default_stimulus_controllers] ||= []
+    @parts[part_name][:default_stimulus_controllers] << controller_name
+  end
+
+  #
+  # Validate the component config and throw errors if there are issues.
+  #
+  def validate
+    validate_modifiers
+  end
+
+  #
+  # Validate that all of the modifiers are correct.
+  #
+  def validate_modifiers
+    # Check to make sure they have passed a valid / defined modifier
+    (@modifiers || []).each do |modifier|
+      if modifier.present? && !@component.valid_modifiers.include?(modifier)
+        raise LocoMotion::InvalidModifierError.new(modifier, @component)
+      end
+    end
+  end
+
+  #
+  # Validates that the requested part is valid for the component.
+  #
+  def validate_part(part_name)
+    raise LocoMotion::UnknownPartError.new(part_name, @component) unless valid_parts.include?(part_name)
+  end
+
+  #
+  # Return a list of valid parts for the component.
+  #
+  def valid_parts
+    @parts.keys
+  end
+
+  #
+  # Render a Hash version of the config.
+  #
+  def to_h
+    {
+      options: @options,
+      parts: @parts,
+      modifiers: @modifiers,
+      size: @size
+    }
+  end
+
+  #
+  # For now, just return the Hash version for inspect.
+  #
+  def inspect
+    [
+      "#<#{self.class.name}",
+      "@options=#{@options.inspect}",
+      "@parts=#{@parts.inspect}",
+      "@modifiers=#{@modifiers.inspect}",
+      "@size=#{@size.inspect}",
+    ].join(" ") + ">"
+  end
+end

data/lib/loco_motion/engine.rb

@@ -0,0 +1,8 @@
+module LocoMotion
+  class Engine < ::Rails::Engine
+    isolate_namespace LocoMotion
+
+    config.autoload_paths << "#{root}/app"
+    config.autoload_paths << "#{root}/lib"
+  end
+end

data/lib/loco_motion/errors.rb

@@ -0,0 +1,33 @@
+module LocoMotion
+  class UnknownPartError < StandardError
+    def initialize(part, component, custom_message = nil)
+      no_parts_explanation = "No parts are defined on the component."
+      default_explanation = "Valid parts are #{component.config.valid_parts.map(&:inspect).to_sentence}."
+
+      has_parts = component.config.valid_parts.present?
+
+      default_message = [
+        "Unknown part #{part.inspect}.",
+        "#{has_parts ? default_explanation : no_parts_explanation}"
+      ].join(' ')
+
+      super(custom_message || default_message)
+    end
+  end
+
+  class InvalidModifierError < StandardError
+    def initialize(modifier, component, custom_message = nil)
+      no_modifiers_explanation = "No modifiers are defined on the component."
+      default_explanation = "Valid modifiers are #{component.valid_modifiers.map(&:inspect).to_sentence}."
+
+      has_modifiers = component.valid_modifiers.present?
+
+      default_message = [
+        "Unknown modifier #{modifier.inspect}.",
+        "#{has_modifiers ? default_explanation : no_modifiers_explanation}"
+      ].join(' ')
+
+      super(custom_message || default_message)
+    end
+  end
+end

data/lib/loco_motion.rb

@@ -0,0 +1,48 @@
+require "rails"
+require "haml-rails"
+require "heroicons-rails"
+
+require Gem::Specification.find_by_name("heroicons-rails").gem_dir + "/app/helpers/heroicons/icons_helper.rb"
+
+require "view_component"
+require "loco_motion/engine"
+require "loco_motion/errors"
+require "loco_motion/component_config"
+require "loco_motion/base_component"
+
+require "daisy"
+
+#
+# Module containing all features related to the LocoMotion gem.
+#
+module LocoMotion
+
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Mostly used for internal testing; not needed in Rails
+    def require_components
+      Dir.glob(File.dirname(__FILE__) + '/../app/components/**/*.rb').each do |file|
+        require file
+      end
+    end
+
+    def define_render_helper(name, component)
+    end
+  end
+
+  class Configuration
+    attr_accessor :base_component_class
+
+    def initialize
+      @base_component_class = LocoMotion::BaseComponent
+    end
+  end
+
+end