pom-component 1.0.0

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+# Add a convenient test task alias
+task test: "app:test"
+task default: :test

data/lib/pom/component.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pom
+  # Base Rails ViewComponent class with DSL for options, enum validation, extra options capture, and required options enforcement
+  class Component < ViewComponent::Base
+    include Pom::OptionDsl
+    include Pom::Styleable
+    include Pom::Helpers::OptionHelper
+    include Pom::Helpers::ViewHelper
+    include Pom::Helpers::StimulusHelper
+
+    # Initialize component with options, applying defaults, validation, capturing extra options, and enforcing required options
+    def initialize(**kwargs)
+      super()
+      initialize_options(**kwargs)
+    end
+
+    def component_name
+      self.class.name.demodulize.chomp("Component").underscore.dasherize
+    end
+
+    def auto_id
+      [component_name, uid].compact_blank.join("-")
+    end
+
+    def uid
+      @uid ||= SecureRandom.hex(8 / 2)
+    end
+  end
+end

data/lib/pom/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Pom
+  class Configuration
+    attr_accessor :component_prefixes
+
+    def initialize
+      @component_prefixes = ["pom"]
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/pom/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pom
+  class Engine < ::Rails::Engine
+    isolate_namespace Pom
+
+    initializer "pom.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper Pom::Helpers::OptionHelper
+        helper Pom::Helpers::ViewHelper
+        helper Pom::Helpers::StimulusHelper
+      end
+    end
+  end
+end

data/lib/pom/helpers/option_helper.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Pom
+  module Helpers
+    module OptionHelper
+      # Merges multiple option hashes from right to left, handling CSS classes and data attributes.
+      # @param options [Array<Hash>] List of option hashes to merge
+      # @return [Hash] Merged options hash
+      def merge_options(*options)
+        options.reduce({}) do |merged, opts|
+          next merged if opts.nil? || opts.empty?
+
+          merged.merge(opts) do |key, old_val, new_val|
+            case key
+            when :class
+              merge_classes(old_val, new_val)
+            when :data
+              merge_data(old_val, new_val)
+            else
+              new_val
+            end
+          end
+        end
+      end
+
+      private
+
+      # Merges CSS classes using tailwind_merge gem, handling strings, arrays, or nil.
+      # @param old_val [String, Array, nil] Existing class value
+      # @param new_val [String, Array, nil] New class value
+      # @return [String] Merged class string
+      def merge_classes(old_val, new_val)
+        old_classes = normalize_classes(old_val)
+        new_classes = normalize_classes(new_val)
+        TailwindMerge::Merger.new.merge([old_classes, new_classes].join(" "))
+      end
+
+      # Normalizes class values to a string, handling strings, arrays, or nil.
+      # @param value [String, Array, nil] Class value
+      # @return [String] Normalized class string
+      def normalize_classes(value)
+        case value
+        when String
+          value.strip
+        when Array
+          value.flatten.map(&:to_s).reject(&:empty?).join(" ").strip
+        else
+          ""
+        end
+      end
+
+      # Merges data attribute hashes, with special handling for data-action and data-controller.
+      # @param old_val [Hash, nil] Existing data hash
+      # @param new_val [Hash, nil] New data hash
+      # @return [Hash] Merged data hash
+      def merge_data(old_val, new_val)
+        old_data = old_val || {}
+        new_data = new_val || {}
+
+        old_data.merge(new_data) do |key, old_data_val, new_data_val|
+          if ["action", "controller"].include?(key.to_s)
+            [old_data_val, new_data_val].uniq.compact.join(" ").strip
+          else
+            new_data_val
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pom/helpers/stimulus_helper.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module Pom
+  module Helpers
+    # Provides helper methods for generating Stimulus.js data attributes in Rails views or ViewComponents.
+    module StimulusHelper
+      # Generates a Stimulus data value attribute.
+      # @param name [Symbol, String] The name of the value.
+      # @param value [Object] The value to assign. Complex objects (Array, Hash) are JSON-encoded.
+      # @param stimulus [String, Symbol, nil] The Stimulus controller name (defaults to `stimulus_controller`).
+      # @return [Hash] A hash with the attribute key and value.
+      def stimulus_value(name, value, stimulus: nil)
+        raise ArgumentError, "Name cannot be blank" if name.to_s.strip.empty?
+
+        controller_name = stimulus ? stimulus.to_s.underscore.dasherize : stimulus_controller
+        key = "data-#{controller_name}-#{name.to_s.underscore.dasherize}-value"
+
+        # Stimulus expects JSON for complex values (arrays, hashes)
+        serialized_value = case value
+        when Array, Hash
+          value.to_json
+        else
+          value
+        end
+
+        { key => serialized_value }
+      end
+
+      # Generates a Stimulus target attribute.
+      # @param name [Symbol, String, Array] The target name(s). Can be a single target or array of targets.
+      # @param stimulus [String, Symbol, nil] The Stimulus controller name (defaults to `stimulus_controller`).
+      # @return [Hash] A hash with the attribute key and target name(s).
+      #
+      # @example Single target
+      #   stimulus_target(:menu)
+      #   # => { "data-dropdown-target" => "menu" }
+      #
+      # @example Multiple targets
+      #   stimulus_target([:menu, :button])
+      #   # => { "data-dropdown-target" => "menu button" }
+      def stimulus_target(name, stimulus: nil)
+        names = Array(name)
+        raise ArgumentError, "Name cannot be blank" if names.empty? || names.any? { |n| n.to_s.strip.empty? }
+
+        controller_name = stimulus ? stimulus.to_s.underscore.dasherize : stimulus_controller
+        key = "data-#{controller_name}-target"
+        target_value = names.map(&:to_s).join(" ")
+
+        { key => target_value }
+      end
+
+      # Generates a Stimulus class attribute.
+      # @param name [Symbol, String] The class name.
+      # @param value [String] The CSS class value.
+      # @param stimulus [String, Symbol, nil] The Stimulus controller name (defaults to `stimulus_controller`).
+      # @return [Hash] A hash with the attribute key and class value.
+      def stimulus_class(name, value, stimulus: nil)
+        raise ArgumentError, "Name cannot be blank" if name.to_s.strip.empty?
+
+        controller_name = stimulus ? stimulus.to_s.underscore.dasherize : stimulus_controller
+        key = "data-#{controller_name}-#{name.to_s.underscore.dasherize}-class"
+        { key => value }
+      end
+
+      # Generates a Stimulus action attribute.
+      # @param action_map [Hash, Symbol, String] The action definition (e.g., `{ click: :toggle }` or `:toggle`).
+      # @param stimulus [String, Symbol, nil] The Stimulus controller name (defaults to `stimulus_controller`).
+      # @return [Hash] A hash with the action attribute key and value.
+      #
+      # @example Hash format with multiple events
+      #   stimulus_action({ click: :toggle, mouseenter: :show })
+      #   # => { "data-action" => "click->dropdown#toggle mouseenter->dropdown#show" }
+      #
+      # @example Symbol/String format
+      #   stimulus_action(:toggle)
+      #   # => { "data-action" => "dropdown#toggle" }
+      def stimulus_action(action_map, stimulus: nil)
+        controller_name = stimulus ? stimulus.to_s.underscore.dasherize : stimulus_controller
+
+        action_string = case action_map
+        when Hash
+          return { "data-action" => "" } if action_map.empty?
+
+          action_map.map { |event, method| "#{event}->#{controller_name}##{method}" }.join(" ")
+        when Symbol, String
+          str = action_map.to_s
+          if str.include?("->")
+            raise ArgumentError,
+              "Do not include controller name manually. Use `stimulus:` or `stimulus_controller` to set the controller."
+          end
+          "#{controller_name}##{str}"
+        else
+          raise ArgumentError, "Invalid format for stimulus_action: must be a Hash, Symbol, or String"
+        end
+
+        { "data-action" => action_string }
+      end
+
+      # Retrieves the Stimulus controller name in dasherized style.
+      # @return [String] The controller name.
+      # @raise [ArgumentError] If no controller is defined or if the controller name is blank.
+      def stimulus_controller
+        controller = respond_to?(:stimulus) ? stimulus : nil
+        controller ||= raise ArgumentError,
+          "No Stimulus controller available. Provide one explicitly via `stimulus:` or define a `stimulus` method."
+        raise ArgumentError, "Stimulus controller cannot be blank" if controller.to_s.strip.empty?
+
+        controller.to_s.underscore.dasherize
+      end
+    end
+  end
+end

data/lib/pom/helpers/view_helper.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Pom
+  module Helpers
+    module ViewHelper
+      class UndefinedComponentError < StandardError; end
+
+      def method_missing(method_name, *args, **kwargs, &block)
+        prefix_match = component_prefixes.find { |prefix| method_name.to_s.start_with?("#{prefix}_") }
+
+        if prefix_match
+          class_name = component_class_name(method_name, prefix_match)
+
+          begin
+            component_class = class_name.constantize
+          rescue NameError => e
+            if e.message.include?(class_name)
+              raise UndefinedComponentError, "Component class '#{class_name}' is not defined"
+            else
+              raise e
+            end
+          end
+
+          render(component_class.new(*args, **kwargs), &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        prefix_match = component_prefixes.find { |prefix| method_name.to_s.start_with?("#{prefix}_") }
+
+        if prefix_match
+          class_name = component_class_name(method_name, prefix_match)
+          # Check if the constant exists by attempting to constantize it
+          begin
+            class_name.constantize
+            true
+          rescue NameError
+            false
+          end
+        else
+          super
+        end
+      end
+
+      private
+
+      def component_prefixes
+        Pom.configuration.component_prefixes
+      end
+
+      def component_class_name(method_name, prefix)
+        component_name = method_name.to_s.sub(/^#{prefix}_/, "").camelize
+        "#{prefix.camelize}::#{component_name}Component"
+      end
+    end
+  end
+end

data/lib/pom/option_dsl.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Pom
+  module OptionDsl
+    # Sentinel object to distinguish between nil and no default
+    NO_DEFAULT = Object.new.freeze
+    private_constant :NO_DEFAULT
+
+    class << self
+      def included(base)
+        base.extend(ClassMethods)
+        base.class_eval do
+          # Instance variable to store extra options that aren't defined
+          attr_reader(:extra_options)
+        end
+      end
+    end
+
+    module ClassMethods
+      attr_reader :options
+
+      # Helper methods for accessing option metadata
+      def enum_values_for(option_name)
+        meta = @options&.[](option_name.to_sym)
+        meta&.dig(:enums)
+      end
+
+      def default_value_for(option_name)
+        meta = @options&.[](option_name.to_sym)
+        return unless meta
+
+        default_val = meta[:default]
+        return if default_val.equal?(NO_DEFAULT)
+
+        default_val.respond_to?(:call) ? default_val.call : default_val
+      end
+
+      def required_options
+        return [] unless @options
+
+        @options.filter_map do |name, config|
+          name if config[:required] && config[:default].equal?(NO_DEFAULT)
+        end
+      end
+
+      def optional_options
+        return [] unless @options
+
+        @options.filter_map do |name, config|
+          name unless config[:required] && config[:default].equal?(NO_DEFAULT)
+        end
+      end
+
+      private
+
+      # Initialize options hash for the class, inheriting from parent if applicable
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@options, (@options || {}).dup)
+      end
+
+      # DSL for defining options with enums, defaults, and required flag
+      def option(name, enums: nil, default: NO_DEFAULT, required: false)
+        @options ||= {}
+        @options[name.to_sym] = {
+          enums: enums&.map(&:to_sym),
+          default: default,
+          required: required,
+        }
+
+        # Define getter method for the option
+        define_method(name) do
+          value = instance_variable_get(:"@#{name}")
+          return value unless value.nil?
+
+          default_val = self.class.options[name.to_sym][:default]
+          return if default_val.equal?(NO_DEFAULT)
+
+          default_val.respond_to?(:call) ? default_val.call : default_val
+        end
+
+        # Define setter method with validation for enums
+        define_method(:"#{name}=") do |value|
+          option_config = self.class.options[name.to_sym]
+          enums = option_config[:enums]
+
+          if enums && !value.nil?
+            # Convert value to symbol if it's a string for comparison
+            sym_value = value.is_a?(String) ? value.to_sym : value
+
+            # Validate against enums
+            if enums.exclude?(sym_value)
+              raise ArgumentError, "Invalid value for #{name}: #{value}. Must be one of #{enums.join(", ")}"
+            end
+
+            # Store the converted symbol value for consistency
+            value = sym_value
+          end
+
+          instance_variable_set(:"@#{name}", value)
+        end
+
+        # Define predicate method for boolean-style checking
+        define_method(:"#{name}?") do
+          send(name).present?
+        end
+      end
+    end
+
+    # Initialize options processing - call this from your initialize method
+    def initialize_options(**kwargs)
+      @extra_options = {}
+      defined_options = self.class.options || {}
+
+      # Validate required options first
+      validate_required_options!(defined_options, kwargs)
+
+      # Process provided options
+      process_provided_options!(defined_options, kwargs)
+
+      # Set defaults for options not provided in kwargs
+      set_default_values!(defined_options, kwargs)
+    end
+
+    # Utility method to get all option values as a hash
+    def option_values
+      return {} unless self.class.options
+
+      self.class.options.keys.index_with do |name|
+        send(name)
+      end
+    end
+
+    # Check if an option is set (not nil and not default)
+    def option_set?(name)
+      return false unless self.class.options&.key?(name.to_sym)
+
+      value = instance_variable_get(:"@#{name}")
+      !value.nil?
+    end
+
+    # Reset an option to its default value
+    def reset_option(name)
+      name = name.to_sym
+      return unless self.class.options&.key?(name)
+
+      remove_instance_variable(:"@#{name}") if instance_variable_defined?(:"@#{name}")
+    end
+
+    private
+
+    def validate_required_options!(defined_options, kwargs)
+      defined_options.each do |name, config|
+        next unless config[:required]
+        next unless config[:default].equal?(NO_DEFAULT)
+        next if kwargs.key?(name) || kwargs.key?(name.to_s)
+
+        raise ArgumentError, "Missing required option: #{name}"
+      end
+    end
+
+    def process_provided_options!(defined_options, kwargs)
+      kwargs.each do |name, value|
+        sym_name = name.to_sym
+
+        if defined_options.key?(sym_name)
+          send(:"#{sym_name}=", value)
+        else
+          @extra_options[sym_name] = value
+        end
+      end
+    end
+
+    def set_default_values!(defined_options, kwargs)
+      defined_options.each do |name, config|
+        next if kwargs.key?(name) || kwargs.key?(name.to_s)
+        next if config[:default].equal?(NO_DEFAULT)
+
+        send(:"#{name}=", config[:default])
+      end
+    end
+  end
+end

data/lib/pom/styleable.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Pom
+  module Styleable
+    class << self
+      def included(base)
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      # Define styles for a component
+      # @param group [Symbol] The style group name (defaults to :default)
+      # @param styles [Hash] The styles definition
+      #
+      # Examples:
+      #   define_styles(base: "btn")
+      #   define_styles(:root, base: "container")
+      #   define_styles(
+      #     base: { default: "btn", hover: "hover:opacity-80" },
+      #     variant: { solid: "bg-blue-500", outline: "border" }
+      #   )
+      def define_styles(group = :default, **styles)
+        # If first argument is a hash, it's actually the styles with default group
+        if group.is_a?(Hash)
+          styles = group
+          group = :default
+        end
+
+        @style_definitions ||= {}
+        @style_definitions[group] ||= {}
+
+        # Merge with existing styles for this group (supports inheritance)
+        styles.each do |style_key, style_value|
+          @style_definitions[group][style_key] = if @style_definitions[group][style_key].is_a?(Hash) && style_value.is_a?(Hash)
+            @style_definitions[group][style_key].merge(style_value)
+          else
+            style_value
+          end
+        end
+      end
+
+      # Get style definitions for this class and its ancestors
+      def style_definitions
+        definitions = {}
+
+        # Collect style definitions from ancestors (inheritance support)
+        ancestors.reverse.each do |ancestor|
+          next unless ancestor.respond_to?(:style_definitions_without_inheritance, true)
+
+          ancestor_defs = ancestor.send(:style_definitions_without_inheritance)
+          ancestor_defs&.each do |group, styles|
+            definitions[group] ||= {}
+            styles.each do |style_key, style_value|
+              definitions[group][style_key] = if definitions[group][style_key].is_a?(Hash) && style_value.is_a?(Hash)
+                definitions[group][style_key].merge(style_value)
+              else
+                style_value
+              end
+            end
+          end
+        end
+
+        definitions
+      end
+
+      private
+
+      def style_definitions_without_inheritance
+        @style_definitions
+      end
+    end
+
+    # Compose styles based on provided keys and values
+    # @param group [Symbol] The style group to use (defaults to :default)
+    # @param options [Hash] Style keys and their values, plus any extra params
+    # @return [String] The composed Tailwind class string merged using TailwindMerge
+    #
+    # Examples:
+    #   styles_for(variant: :solid, color: :red)
+    #   styles_for(:root, variant: :outline)
+    #   styles_for(variant: :solid, custom: true)
+    def styles_for(group = :default, **options)
+      # If first argument is a hash, it's actually the options with default group
+      if group.is_a?(Hash)
+        options = group
+        group = :default
+      end
+
+      definitions = self.class.style_definitions[group]
+      return "" unless definitions
+
+      result_classes = []
+
+      # Process base styles first
+      if definitions[:base]
+        base_styles = resolve_style_value(definitions[:base], options)
+        result_classes << base_styles if base_styles
+      end
+
+      # Process other style keys
+      definitions.each do |style_key, style_config|
+        next if style_key == :base # Already processed
+        next unless options.key?(style_key) # Only process if key is provided
+
+        option_value = options[style_key]
+        next if option_value.nil? # Skip nil values
+
+        if style_config.is_a?(Hash)
+          # Style config is a hash of variant values
+          # Support boolean values, symbol values, and string values
+          style_value = if option_value.is_a?(TrueClass) || option_value.is_a?(FalseClass)
+            # For boolean values, convert to symbol (:true or :false)
+            # because { true: "..." } in Ruby creates a symbol key :true, not boolean key true
+            style_config[option_value.to_s.to_sym]
+          else
+            # For other values, try symbol and string conversions
+            style_config[option_value.to_sym] || style_config[option_value.to_s]
+          end
+          resolved = resolve_style_value(style_value, options)
+        else
+          # Style config is a direct value (string or lambda)
+          resolved = resolve_style_value(style_config, options)
+        end
+        result_classes << resolved if resolved
+      end
+
+      # Use TailwindMerge to merge classes and resolve conflicts
+      merged_classes = result_classes.compact.join(" ")
+      merged_classes.empty? ? "" : TailwindMerge::Merger.new.merge(merged_classes)
+    end
+
+    private
+
+    # Resolve a style value to a string
+    # Handles strings, hashes, and lambdas
+    def resolve_style_value(value, options)
+      case value
+      when String
+        value
+      when Hash
+        # Hash of sub-styles (like { default: "...", hover: "..." })
+        value.values.map { |v| resolve_style_value(v, options) }.compact.join(" ")
+      when Proc
+        # Lambda that receives all options for dynamic computation
+        result = value.call(**options)
+        result.is_a?(String) ? result : result.to_s
+      else
+        value&.to_s
+      end
+    end
+  end
+end

data/lib/pom/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pom
+  VERSION = "1.0.0"
+end

data/lib/pom-component.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "pom"