hakumi_components 0.1.16.pre → 0.1.17.pre

data/lib/hakumi_components/rails/validation_introspection.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module HakumiComponents
+module Hakumi
   module Rails
     # Introspects ActiveModel/ActiveRecord validations to automatically
     # configure form field HTML attributes and client-side validation
@@ -77,8 +77,8 @@ module HakumiComponents
           return nil unless regex.is_a?(Regexp)
 
           # Convert Ruby regex to JavaScript-compatible pattern
-          # Remove anchors ^$ as HTML pattern attribute adds them implicitly
-          regex.source.gsub(/\A\^|\$\z/, "")
+          # Remove anchors (both Ruby \A\z and PCRE ^$) as HTML pattern adds them implicitly
+          regex.source.gsub(/\A(\\A|\^)|(\$|\\z)\z/, "")
         end
 
         # Get min/max values from numericality validation
@@ -96,7 +96,7 @@ module HakumiComponents
           return {} unless numericality_validator
 
           # @type var constraints: Hash[Symbol, Object]
-          constraints = {}
+          constraints = Hash.new
           opts = validator_options(numericality_validator)
 
           min_inclusive = opts[:greater_than_or_equal_to]
@@ -182,7 +182,7 @@ module HakumiComponents
 
         def validator_options(validator)
           # @type var opts: Hash[Symbol, Object]
-          opts = validator.respond_to?(:options) ? validator.public_send(:options) : {}
+          opts = validator.respond_to?(:options) ? validator.public_send(:options) : Hash.new
           opts = opts.to_h if opts.respond_to?(:to_h)
           opts.is_a?(Hash) ? opts : {}
         end

data/lib/hakumi_components/rails/validation_mapper.rb

@@ -0,0 +1,484 @@
+# frozen_string_literal: true
+
+module Hakumi
+  module Rails
+    # Maps Rails ActiveModel validations to frontend validation rules
+    # compatible with Hakumi's ValidationManager (JavaScript)
+    #
+    # @example
+    #   class User < ApplicationRecord
+    #     validates :email, presence: true, length: { maximum: 255 }
+    #   end
+    #
+    #   ValidationMapper.to_frontend_rules(user, :email)
+    #   # => [
+    #   #   { required: true, message: "Email can't be blank" },
+    #   #   { maxLength: { value: 255 }, message: "Email is too long (maximum is 255 characters)" }
+    #   # ]
+    class ValidationMapper
+      class << self
+        # Convert Rails validations to frontend validation rules
+        #
+        # @param object [ActiveModel::Model, ActiveRecord::Base]
+        # @param attribute [Symbol] Attribute name
+        # @return [Array<Hash>] Array of validation rules for frontend
+        def to_frontend_rules(object, attribute)
+          return [] unless object
+          return [] unless object.class.respond_to?(:validators_on)
+
+          validators = object.class.validators_on(attribute)
+          return [] if validators.empty?
+
+          rules = Array.new
+
+          validators.each do |validator|
+            mapped_rules = map_validator(validator, object, attribute)
+            rules.concat(mapped_rules) if mapped_rules
+          end
+
+          rules.compact
+        end
+
+        # Merge manual rules with auto-detected rules
+        # Manual rules take priority over auto-detected ones for the same validation type
+        #
+        # @param manual_rules [Array<Hash>, nil] User-provided rules
+        # @param auto_rules [Array<Hash>] Auto-detected rules from validators
+        # @return [Array<Hash>] Merged rules with manual rules taking priority
+        def merge_rules(manual_rules, auto_rules)
+          return auto_rules if manual_rules.nil? || manual_rules.empty?
+          return manual_rules if auto_rules.nil? || auto_rules.empty?
+
+          # Get rule types from manual rules
+          manual_types = manual_rules.map { |rule| extract_rule_type(rule) }.compact
+
+          # Filter out auto-detected rules that have the same type as manual rules
+          merged = manual_rules.dup
+          auto_rules.each do |auto_rule|
+            type = extract_rule_type(auto_rule)
+            merged << auto_rule unless type && manual_types.include?(type)
+          end
+
+          merged
+        end
+
+        private
+
+        # Extract the validation type from a rule
+        # Rules have format: { required: true, message: "..." }
+        # or { minLength: { value: 3 }, message: "..." }
+        def extract_rule_type(rule)
+          # The first key that isn't :message is the rule type
+          (rule.keys - [ :message ]).first
+        end
+
+        # Map a single validator to frontend rule(s)
+        def map_validator(validator, object, attribute)
+          case validator
+          when ActiveModel::Validations::PresenceValidator
+            map_presence(validator, object, attribute)
+          when ActiveModel::Validations::LengthValidator
+            map_length(validator, object, attribute)
+          when ActiveModel::Validations::NumericalityValidator
+            map_numericality(validator, object, attribute)
+          when ActiveModel::Validations::FormatValidator
+            map_format(validator, object, attribute)
+          when ActiveModel::Validations::ConfirmationValidator
+            map_confirmation(validator, object, attribute)
+          when ActiveModel::Validations::ComparisonValidator
+            map_comparison(validator, object, attribute)
+          when ActiveModel::Validations::InclusionValidator
+            map_inclusion(validator, object, attribute)
+          when ActiveModel::Validations::ExclusionValidator
+            map_exclusion(validator, object, attribute)
+          when ActiveModel::Validations::AcceptanceValidator
+            map_acceptance(validator, object, attribute)
+          when ActiveModel::Validations::AbsenceValidator
+            map_absence(validator, object, attribute)
+          when defined?(ActiveRecord) && ActiveRecord::Validations::PresenceValidator
+            map_presence(validator, object, attribute)
+          else
+            # Unknown validator type - skip for now
+            # Can be extended by adding more cases
+            nil
+          end
+        end
+
+        # Map presence validation to required rule
+        def map_presence(validator, object, attribute)
+          [ {
+            required: true,
+            message: validation_message(object, attribute, :blank, {}, validator.options)
+          } ]
+        end
+
+        # Map length validation to minLength/maxLength rules
+        def map_length(validator, object, attribute)
+          rules = Array.new
+          options = validator.options
+
+          # Exact length
+          exact = options[:is]
+          if exact
+            rules << {
+              minLength: { value: exact },
+              maxLength: { value: exact },
+              message: validation_message(object, attribute, :wrong_length, { count: exact }, options)
+            }
+
+            return rules
+          end
+
+          # Minimum length
+          min = options[:minimum] || (options[:in]&.min if options[:in].respond_to?(:min))
+          if min
+            rules << {
+              minLength: { value: min },
+              message: validation_message(object, attribute, :too_short, { count: min }, options)
+            }
+          end
+
+          # Maximum length
+          max = options[:maximum] || options[:is] || (options[:in]&.max if options[:in].respond_to?(:max))
+          if max
+            rules << {
+              maxLength: { value: max },
+              message: validation_message(object, attribute, :too_long, { count: max }, options)
+            }
+          end
+
+          rules
+        end
+
+        # Map numericality validation to min/max rules
+        def map_numericality(validator, object, attribute)
+          rules = Array.new
+          options = validator.options
+
+          # Minimum value (inclusive)
+          if options[:greater_than_or_equal_to]
+            rules << {
+              min: { value: options[:greater_than_or_equal_to] },
+              message: validation_message(
+                object,
+                attribute,
+                :greater_than_or_equal_to,
+                { count: options[:greater_than_or_equal_to] },
+                options
+              )
+            }
+          end
+
+          # Minimum value (exclusive) - add 1 for frontend
+          if options[:greater_than]
+            min_value = options[:greater_than] + 1
+            rules << {
+              min: { value: min_value },
+              message: validation_message(
+                object,
+                attribute,
+                :greater_than,
+                { count: options[:greater_than] },
+                options
+              )
+            }
+          end
+
+          # Maximum value (inclusive)
+          if options[:less_than_or_equal_to]
+            rules << {
+              max: { value: options[:less_than_or_equal_to] },
+              message: validation_message(
+                object,
+                attribute,
+                :less_than_or_equal_to,
+                { count: options[:less_than_or_equal_to] },
+                options
+              )
+            }
+          end
+
+          # Maximum value (exclusive) - subtract 1 for frontend
+          if options[:less_than]
+            max_value = options[:less_than] - 1
+            rules << {
+              max: { value: max_value },
+              message: validation_message(
+                object,
+                attribute,
+                :less_than,
+                { count: options[:less_than] },
+                options
+              )
+            }
+          end
+
+          rules
+        end
+
+        # Map format validation to pattern/email/url rule
+        def map_format(validator, object, attribute)
+          options = validator.options
+          regex = options[:with]
+          return [] unless regex.is_a?(Regexp)
+
+          regex_source = regex.source
+
+          # Detect email pattern
+          if email_regex?(regex_source) || attribute.to_s.match?(/email/i)
+            return [ {
+              email: true,
+              message: validation_message(object, attribute, :invalid, {}, options)
+            } ]
+          end
+
+          # Detect URL pattern
+          if url_regex?(regex_source) || attribute.to_s.match?(/url|website|link/i)
+            return [ {
+              url: true,
+              message: validation_message(object, attribute, :invalid, {}, options)
+            } ]
+          end
+
+          # Generic pattern rule
+          # Remove anchors (\A, \z, ^, $) as HTML pattern adds them implicitly
+          pattern = regex_source.gsub(/\A(\\A|\^)|(\$|\\z)\z/, "")
+
+          [ {
+            pattern: { value: pattern },
+            message: validation_message(object, attribute, :invalid, {}, options)
+          } ]
+        end
+
+        # Map confirmation validation to match rule
+        def map_confirmation(validator, object, attribute)
+          [ {
+            match: { field: "#{attribute}_confirmation" },
+            message: validation_message(object, attribute, :confirmation, {}, validator.options)
+          } ]
+        end
+
+        # Map comparison validation to comparison rule
+        def map_comparison(validator, object, attribute)
+          options = validator.options
+          rules = Array.new
+
+          comparison_keys = %i[
+            greater_than
+            greater_than_or_equal_to
+            equal_to
+            less_than
+            less_than_or_equal_to
+            other_than
+          ]
+
+          comparison_keys.each do |key|
+            next unless options.key?(key)
+
+            target = options[key]
+            comparison = build_comparison_target(target, object)
+            next unless comparison
+
+            message_options = comparison_message_options(target, object, comparison)
+            rules << {
+              comparison: comparison.merge(operator: key),
+              message: validation_message(object, attribute, key, message_options, options)
+            }
+          end
+
+          rules
+        end
+
+        # Map inclusion validation to enum rule
+        def map_inclusion(validator, object, attribute)
+          options = validator.options
+          values = options[:in] || options[:within]
+
+          return [] unless values
+
+          [ {
+            enum: { values: values.to_a },
+            message: validation_message(object, attribute, :inclusion, {}, options)
+          } ]
+        end
+
+        # Map exclusion validation to forbidden values rule
+        def map_exclusion(validator, object, attribute)
+          options = validator.options
+          values = options[:in] || options[:within]
+
+          return [] unless values
+
+          [ {
+            exclusion: { values: values.to_a },
+            message: validation_message(object, attribute, :exclusion, {}, options)
+          } ]
+        end
+
+        # Map acceptance validation to required rule
+        def map_acceptance(validator, object, attribute)
+          [ {
+            required: true,
+            message: validation_message(object, attribute, :accepted, {}, validator.options)
+          } ]
+        end
+
+        # Map absence validation to absent rule (field must be blank)
+        def map_absence(validator, object, attribute)
+          [ {
+            absent: true,
+            message: validation_message(object, attribute, :present, {}, validator.options)
+          } ]
+        end
+
+        # Check if regex matches email pattern
+        def email_regex?(regex_source)
+          # Common email regex patterns
+          regex_source.match?(/@.*\./) || regex_source.include?("EMAIL")
+        end
+
+        # Check if regex matches URL pattern
+        def url_regex?(regex_source)
+          # Common URL regex patterns
+          regex_source.match?(/https?|:\/\//) || regex_source.include?("URL")
+        end
+
+        # Humanize attribute name
+        def humanize(attribute)
+          attribute.to_s.humanize
+        end
+
+        # Use Rails' error message generation to honor I18n and custom messages
+        def validation_message(object, attribute, type, options, validator_options)
+          return fallback_message(attribute, type, options, validator_options) unless object&.respond_to?(:errors)
+          return fallback_message(attribute, type, options, validator_options) if anonymous_class?(object)
+
+          value = object.respond_to?(attribute) ? object.public_send(attribute) : nil
+          message = object.errors.generate_message(
+            attribute,
+            type,
+            options.merge(value: value, message: validator_options[:message])
+          )
+
+          if object.errors.respond_to?(:full_message) && object.class.name && !object.class.name.empty?
+            object.errors.full_message(attribute, message)
+          else
+            message
+          end
+        end
+
+        def anonymous_class?(object)
+          class_name = object.class.name
+          class_name.nil? || class_name.empty?
+        end
+
+        # Build comparison target from validator option value
+        #
+        # @param target [Symbol, String, Proc, Object] The comparison target value
+        # @param _object [Object] The model object (unused, Procs are not evaluated)
+        # @return [Hash, nil] Hash with :field or :value key, or nil if cannot be used client-side
+        #
+        # @note Procs are always ignored (return nil) because they cannot be reliably
+        #   evaluated on the client-side. For field comparisons, use Symbol references:
+        #   `comparison: { greater_than: :start_date }` instead of Procs.
+        def build_comparison_target(target, _object)
+          case target
+          when Symbol, String
+            { field: target.to_s }
+          when Proc
+            # Procs cannot be evaluated reliably on client-side
+            # Skip this validation rule for frontend
+            nil
+          else
+            { value: target }
+          end
+        end
+
+        def comparison_message_options(target, object, comparison)
+          if comparison[:field]
+            {
+              count: humanize(comparison[:field])
+            }
+          else
+            resolved = resolve_comparison_value(target, object)
+            {
+              count: resolved
+            }
+          end
+        end
+
+        def resolve_comparison_value(target, object)
+          return object.public_send(target) if target.is_a?(Symbol) && object&.respond_to?(target)
+          return target.call(object) if target.respond_to?(:call)
+
+          target
+        rescue StandardError
+          nil
+        end
+
+        # Fallback for standalone objects or anonymous classes where Rails can't build model-based messages.
+        # This keeps validations usable without requiring ActiveRecord models.
+        def fallback_message(attribute, type, options, validator_options)
+          message = validator_options[:message]
+          return message if message.is_a?(String)
+
+          local_options = options.dup
+          if type == :confirmation && !local_options.key?(:attribute)
+            local_options[:attribute] = humanize(:"#{attribute}_confirmation")
+          end
+
+          default_text = fallback_message_text(type, local_options)
+          return "#{humanize(attribute)} #{default_text}" unless defined?(I18n) && I18n.respond_to?(:t)
+
+          translated = I18n.t(
+            :"errors.messages.#{type}",
+            **local_options,
+            default: default_text
+          )
+
+          "#{humanize(attribute)} #{translated}"
+        end
+
+        def fallback_message_text(type, options)
+          count = options[:count]
+          case type
+          when :blank
+            "can't be blank"
+          when :too_short
+            "is too short (minimum is #{count} characters)"
+          when :too_long
+            "is too long (maximum is #{count} characters)"
+          when :wrong_length
+            "is the wrong length (should be #{count} characters)"
+          when :greater_than_or_equal_to
+            "must be greater than or equal to #{count}"
+          when :greater_than
+            "must be greater than #{count}"
+          when :less_than_or_equal_to
+            "must be less than or equal to #{count}"
+          when :less_than
+            "must be less than #{count}"
+          when :equal_to
+            "must be equal to #{count}"
+          when :other_than
+            "must be other than #{count}"
+          when :confirmation
+            "doesn't match #{options[:attribute]}"
+          when :inclusion
+            "is not included in the list"
+          when :exclusion
+            "is reserved"
+          when :accepted
+            "must be accepted"
+          when :present
+            "must be blank"
+          when :invalid
+            "is invalid"
+          else
+            type.to_s.tr("_", " ")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hakumi_components/rails.rb

@@ -2,8 +2,9 @@
 
 require_relative "rails/validation_introspection"
 require_relative "rails/attribute_introspection"
+require_relative "rails/validation_mapper"
 
-module HakumiComponents
+module Hakumi
   module Rails
   end
 end

data/lib/hakumi_components/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module HakumiComponents
-  VERSION = "0.1.16.pre"
+module Hakumi
+  VERSION = "0.1.17.pre"
 end

data/lib/hakumi_components.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
+require "view_component"
 require "hakumi_components/version"
 require "hakumi_components/engine"
 require "hakumi_components/rails"
+require "hakumi_components/documentation"
 
-module HakumiComponents
+module Hakumi
   class << self
     def configure
       yield configuration

data/lib/tasks/coverage.rake

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+namespace :coverage do
+  desc "Run tests with coverage report (no parallel)"
+  task :report do
+    puts "🔍 Running tests with coverage (no parallelization)..."
+    puts ""
+
+    # Set environment variables
+    ENV["COVERAGE"] = "1"
+    ENV["PARALLEL"] = "0"
+
+    # Clean previous coverage
+    sh "rm -rf coverage" rescue nil
+
+    # Run tests
+    Rake::Task["test"].invoke
+
+    puts ""
+    puts "✅ Coverage report generated at: coverage/index.html"
+    puts ""
+    puts "To view the report:"
+    puts "  - macOS:  open coverage/index.html"
+    puts "  - Linux:  xdg-open coverage/index.html"
+    puts ""
+  end
+
+  desc "Run tests with coverage and console output"
+  task :console do
+    ENV["COVERAGE_CONSOLE"] = "1"
+    Rake::Task["coverage:report"].invoke
+  end
+end
+
+# Alias for convenience
+desc "Run tests with coverage (alias for coverage:report)"
+task coverage: "coverage:report"

data/sig/hakumi/base_component.rbs

@@ -65,6 +65,11 @@ module Hakumi
     # @return [String, nil] CSS dimension string
     def dimension_to_css: ((Numeric | String | nil) value) -> String?
 
+    # Cast a value to boolean using ActiveModel::Type::Boolean
+    # @param value [untyped] Value to cast
+    # @return [Boolean] Casted boolean value
+    def cast_boolean: (untyped value) -> bool
+
     # Build inline style string from array or hash
     # @param styles [Array<String>, Hash] Styles as array of CSS strings or hash of property => value
     # @return [String, nil] Combined style string

data/sig/hakumi/checkbox/component.rbs

@@ -3,6 +3,8 @@
 module Hakumi
   module Checkbox
     class Component < Hakumi::BaseComponent
+      include Hakumi::Concerns::FormField
+
       @checked: bool
       @disabled: bool
       @indeterminate: bool
@@ -11,6 +13,10 @@ module Hakumi
       @id: String
       @auto_focus: bool
       @label: String?
+      @caption: String?
+      @standalone: bool
+      @required: bool
+      @errors: Array[String]
       @wrapper_id: String
       @html_options: hakumi_html_options
 
@@ -23,6 +29,10 @@ module Hakumi
         ?id: String?,
         ?auto_focus: bool,
         ?label: String?,
+        ?caption: String?,
+        ?standalone: bool,
+        ?required: bool,
+        ?errors: Array[String],
         **hakumi_html_options html_options
       ) -> void
 

data/sig/hakumi/color_picker/component.rbs

@@ -75,7 +75,6 @@ module Hakumi
       def component_classes: () -> String
       def data_value: (String? value) -> String?
       def normalize_presets: (preset_input? presets) -> Array[preset_group]
-      def cast_boolean: (untyped value) -> bool
     end
   end
 end

data/sig/hakumi/form_builder.rbs

@@ -16,13 +16,21 @@ module Hakumi
     def mentions_field: (Symbol method, **untyped options) -> String
     def slider_field: (Symbol method, **untyped options) -> String
     def rate_field: (Symbol method, **untyped options) -> String
+    def autocomplete_field: (Symbol method, untyped? choices, **untyped options) -> String
+    def cascader_field: (Symbol method, untyped? choices, **untyped options) -> String
+    def checkbox_field: (Symbol method, **untyped options) -> String
+    def color_picker_field: (Symbol method, **untyped options) -> String
+    def time_picker_field: (Symbol method, **untyped options) -> String
+    def transfer_field: (Symbol method, untyped? data_source, **untyped options) -> String
+    def upload_field: (Symbol method, **untyped options) -> String
     def submit: (String? value, **untyped options) -> String
 
     private
 
     # Private helper methods
+    def field_configuration: (Symbol method, Hash[Symbol, untyped] options, ?id_suffix: String?) -> Hash[Symbol, untyped]
     def enhance_options_with_introspection!: (Symbol method, Hash[Symbol, untyped] options) -> (Hash[Symbol, untyped] | nil)
-    def render_form_field: (Class component_class, Symbol method, **untyped options) -> String
+    def render_form_field: (Class component_class, Symbol method, ?config_overrides: Hash[Symbol, untyped], **untyped options) -> String
     def object_value: (Symbol method) -> untyped
     def object_errors: (Symbol method) -> Array[String]
   end

data/sig/{hakumi_components → hakumi}/rails/attribute_introspection.rbs

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module HakumiComponents
+module Hakumi
   module Rails
     class AttributeIntrospection
       def self.human_attribute_name: (Object object, Symbol attribute) -> String?

data/sig/{hakumi_components → hakumi}/rails/validation_introspection.rbs

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module HakumiComponents
+module Hakumi
   module Rails
     class ValidationIntrospection
       def self.required?: (Object object, Symbol attribute) -> bool