hakumi_components 0.1.18.pre → 0.1.19.pre

data/app/components/hakumi_components/badge/component.rb

@@ -1,31 +1,47 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
   module Badge
     class Component < HakumiComponents::BaseComponent
+      extend T::Sig
+
+      Status = T.type_alias { T.nilable(T.any(Symbol, String)) }
+      Count = T.type_alias { T.nilable(T.any(Integer, Float, String)) }
+      IconName = T.type_alias { T.nilable(T.any(Symbol, String)) }
+
+      STATUSES = T.let(%i[success processing default error warning].freeze, T::Array[Symbol])
+
+      sig do
+        params(
+          count: Count,
+          dot: T::Boolean,
+          overflow_count: Integer,
+          status: Status,
+          text: T.nilable(String),
+          color: T.nilable(String),
+          show_zero: T::Boolean,
+          icon: IconName,
+          html_options: Types::HtmlAttributeValue
+        ).void
+      end
       def initialize(count: nil, dot: false, overflow_count: 99, status: nil, text: nil, color: nil, show_zero: false, icon: nil, **html_options)
-        @count = count
-        @dot = dot
-        @overflow_count = overflow_count
-        @status = status
-        @text = text
-        @color = color
-        @show_zero = show_zero
-        @icon = icon
-        @html_options = html_options
+        @count = T.let(count, Count)
+        @dot = T.let(cast_boolean(dot) ? true : false, T::Boolean)
+        @overflow_count = T.let(overflow_count, Integer)
+        @status = T.let(status&.to_sym, T.nilable(Symbol))
+        @text = T.let(text, T.nilable(String))
+        @color = T.let(color, T.nilable(String))
+        @show_zero = T.let(cast_boolean(show_zero) ? true : false, T::Boolean)
+        @icon = T.let(icon, IconName)
+        @html_options = T.let(html_options, Types::HtmlAttributes)
+
+        validate_props!
       end
 
+      sig { returns(ActiveSupport::SafeBuffer) }
       def call
-        # Direct rendering to ensure class is present
-        classes = [ "hakumi-badge", @html_options[:class] ].compact.join(" ")
-
-        if @status || @text
-          classes += " hakumi-badge-status"
-        elsif content.blank?
-          classes += " hakumi-badge-not-a-wrapper"
-        end
-
-        content_tag(:span, class: classes, **@html_options.except(:class)) do
+        content_tag(:span, wrapper_attributes) do
           safe_join([
             content,
             badge_element,
@@ -34,49 +50,87 @@ module HakumiComponents
         end
       end
 
+      sig { returns(Types::HtmlAttributes) }
+      def wrapper_attributes
+        merge_attributes({ class: wrapper_classes }, @html_options.except(:class))
+      end
+
       private
 
-      def badge_element
-        if @status || @text
-          styles = []
-          styles << "background: #{@color}" if @color
+      sig { void }
+      def validate_props!
+        validate_inclusion!(:status, STATUSES)
+      end
 
-          classes = [ "hakumi-badge-status-dot" ]
-          classes << "hakumi-badge-status-#{@status}" if @status
+      sig { returns(String) }
+      def wrapper_classes
+        modifiers = {
+          status: (@status || @text).present?,
+          "not-a-wrapper": content.blank? && !(@status || @text)
+        }
+        component_classes("badge", modifiers, @html_options)
+      end
 
-          tag.span(class: classes.join(" "), style: (styles.join(";") if styles.any?))
+      sig { returns(T.nilable(ActiveSupport::SafeBuffer)) }
+      def badge_element
+        if @status || @text
+          status_dot_element
         elsif @dot
-          tag.sup(class: "hakumi-badge-dot", style: ("background: #{@color}" if @color))
+          dot_element
         elsif @count || @icon || @show_zero
-          # Show if count is present (and valid) OR icon is present OR show_zero is true
-          should_show = @icon.present? || @show_zero || (@count && (@count.is_a?(String) || @count > 0))
-
-          if should_show
-            classes = [ "hakumi-badge-count" ]
-            classes << "hakumi-badge-custom-component" if @icon
-
-            styles = []
-            styles << "background: #{@color}" if @color && !@icon
-            styles << "color: #{@color}" if @color && @icon
-
-            tag.sup(class: classes.join(" "), title: @count, style: (styles.join("; ") if styles.any?)) do
-              if @icon
-                render HakumiComponents::Icon::Component.new(name: @icon)
-              else
-                display_count.to_s
-              end
-            end
+          count_element
+        end
+      end
+
+      sig { returns(ActiveSupport::SafeBuffer) }
+      def status_dot_element
+        styles = T.let([], T::Array[String])
+        styles << "background: #{@color}" if @color
+
+        extras = @status ? [ "hakumi-badge-status-#{@status}" ] : []
+        dot_classes = class_names("badge-status-dot", {}, extras)
+
+        tag.span(class: dot_classes, style: (styles.join(";") if styles.any?))
+      end
+
+      sig { returns(ActiveSupport::SafeBuffer) }
+      def dot_element
+        tag.sup(class: "hakumi-badge-dot", style: ("background: #{@color}" if @color))
+      end
+
+      sig { returns(T.nilable(ActiveSupport::SafeBuffer)) }
+      def count_element
+        # Show if count is present (and valid) OR icon is present OR show_zero is true
+        should_show = @icon.present? || @show_zero || (@count && (@count.is_a?(String) || @count > 0))
+
+        return unless should_show
+
+        extras = @icon ? [ "hakumi-badge-custom-component" ] : []
+        count_classes = class_names("badge-count", {}, extras)
+
+        styles = T.let([], T::Array[String])
+        styles << "background: #{@color}" if @color && !@icon
+        styles << "color: #{@color}" if @color && @icon
+
+        tag.sup(class: count_classes, title: @count, style: (styles.join("; ") if styles.any?)) do
+          if @icon
+            render HakumiComponents::Icon::Component.new(name: @icon)
+          else
+            display_count.to_s
           end
         end
       end
 
+      sig { returns(T.nilable(ActiveSupport::SafeBuffer)) }
       def status_text_element
         return unless @text
         tag.span(@text, class: "hakumi-badge-status-text")
       end
 
+      sig { returns(T.any(Integer, Float, String)) }
       def display_count
         return @count if @count.is_a?(String)
+        return 0 if @count.nil?
         return "#{@overflow_count}+" if @count > @overflow_count
         @count
       end

data/app/components/hakumi_components/base_component.rb

@@ -1,18 +1,37 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
-  # Base class for all Hakumi components
-  # Provides shared utilities and helpers
   class BaseComponent < ViewComponent::Base
-    # Generate class names with the hakumi- prefix
-    # @param base [String] Base class name (e.g., 'btn', 'icon')
-    # @param modifiers [Hash] Hash of modifier keys and their values
-    # @param extras [Array<String>] Additional classes to append
-    # @return [String] Combined class string
-    #
-    # Example:
-    #   class_names('button', { type: :primary, size: :large }, ['custom-class'])
-    #   # => "hakumi-button hakumi-button-primary hakumi-button-large custom-class"
+    extend T::Sig
+
+    SizeValue = T.type_alias { T.any(Types::HtmlKey, Integer) }
+    DimensionInput = T.type_alias { T.nilable(T.any(Numeric, String)) }
+    I18nOptionValue = T.type_alias { Types::ValidationComparable }
+    DateLikeValue = T.type_alias { T.any(Date, Time, DateTime, ActiveSupport::TimeWithZone) }
+    DateInput = T.type_alias { T.nilable(T.any(DateLikeValue, Types::HtmlKey)) }
+    SymbolInput = T.type_alias { T.nilable(Types::HtmlKey) }
+    PresenceArray = T.type_alias { T::Array[HakumiComponents::Types::FormFieldScalar] }
+    ControllerOptions = T.type_alias { T.any(ActionController::Parameters, Types::HtmlAttributes) }
+    PresenceScalar = T.type_alias { T.any(Types::ValidationPrimitive, DateLikeValue) }
+    HtmlPayloadInput = T.type_alias { T.any(ActionController::Parameters, Types::DataAttributes, Types::HtmlClassList) }
+    PresenceValue = T.type_alias do
+      T.nilable(T.any(
+        Types::Renderable,
+        PresenceScalar,
+        PresenceArray
+      ))
+    end
+    RawHtmlInput = T.type_alias do
+      T.nilable(T.any(
+        Types::HtmlPrimitive,
+        HtmlPayloadInput
+      ))
+    end
+
+    SIZES = T.let(%i[small default large].freeze, T::Array[Symbol])
+
+    sig { params(base: String, modifiers: Types::ClassModifiers, extras: Types::CssClasses).returns(String) }
     def class_names(base, modifiers = {}, extras = [])
       classes = [ "hakumi-#{base}" ]
 
@@ -30,52 +49,45 @@ module HakumiComponents
       classes.join(" ")
     end
 
-    # Merge HTML attributes with defaults
-    # @param defaults [Hash] Default attributes
-    # @param overrides [Hash] User-provided attributes
-    # @return [Hash] Merged attributes
+    sig { params(defaults: Types::HtmlAttributes, overrides: Types::HtmlAttributes).returns(Types::HtmlAttributes) }
     def merge_attributes(defaults = {}, overrides = {})
-      merged = defaults.deep_dup
+      merged = T.let(defaults.deep_dup, Types::HtmlAttributes)
 
-      # Special handling for class attribute
       if defaults[:class] && overrides[:class]
         merged[:class] = [ defaults[:class], overrides[:class] ].join(" ")
       elsif overrides[:class]
         merged[:class] = overrides[:class]
       end
 
-      # Special handling for style attribute
       if defaults[:style] && overrides[:style]
         merged[:style] = [ defaults[:style].to_s.chomp(";"), overrides[:style] ].join("; ")
       elsif overrides[:style]
         merged[:style] = overrides[:style]
       end
 
-      # Merge data attributes
-      if overrides[:data]
-        merged[:data] = (defaults[:data] || {}).merge(overrides[:data])
-      elsif defaults[:data]
-        merged[:data] = defaults[:data]
-      end
+      merged_data = merge_attribute_hash(defaults[:data], overrides[:data])
+      merged[:data] = merged_data if merged_data
 
-      # Merge other attributes
-      merged.merge!(overrides.except(:class, :data, :style))
+      merged_aria = merge_attribute_hash(defaults[:aria], overrides[:aria])
+      merged[:aria] = merged_aria if merged_aria
+
+      merged.merge!(overrides.except(:aria, :class, :data, :style))
 
       ensure_dom_id!(merged)
 
       merged
     end
 
-    # Internal helper to check presence without clobbering ActiveSupport#present?
-    # @param value [Object] Value to check
-    # @return [Boolean]
+    sig { params(value: PresenceValue).returns(T::Boolean) }
     def value_present?(value)
-      !value.nil? && value != false && (value.respond_to?(:empty?) ? !value.empty? : true)
+      return false if value.nil? || value == false
+      return !value.empty? if value.is_a?(String)
+      return !value.empty? if value.is_a?(Array)
+
+      true
     end
 
-    # Validate required props
-    # @param props [Array<Symbol>] List of required prop names
-    # @raise [ArgumentError] if any prop is missing
+    sig { params(props: Symbol).void }
     def validate_required!(*props)
       props.each do |prop|
         value = instance_variable_get("@#{prop}")
@@ -83,10 +95,7 @@ module HakumiComponents
       end
     end
 
-    # Validate prop is one of allowed values
-    # @param prop [Symbol] Prop name
-    # @param allowed [Array] Allowed values
-    # @raise [ArgumentError] if value is not allowed
+    sig { params(prop: Symbol, allowed: T::Array[T.nilable(SizeValue)]).void }
     def validate_inclusion!(prop, allowed)
       value = instance_variable_get("@#{prop}")
       return if value.nil?
@@ -95,56 +104,40 @@ module HakumiComponents
       raise ArgumentError, "#{prop} must be one of #{allowed.inspect}, got #{value.inspect}"
     end
 
+    sig { params(attrs: Types::HtmlAttributes).void }
     def ensure_dom_id!(attrs)
-      controllers = attrs.dig(:data, :controller)
-      return unless value_present?(controllers)
-      return if value_present?(attrs[:id])
+      data = attrs[:data]
+      controllers = data.is_a?(Hash) ? data[:controller] : nil
+      return unless controllers.is_a?(String) && !controllers.empty?
+
+      id = attrs[:id]
+      return if id.is_a?(String) && !id.empty?
 
       attrs[:id] = generate_id("hakumi-component")
     end
 
-    # Generate a unique ID with a prefix
-    # @param prefix [String] Prefix for the ID
-    # @param length [Integer] Length of the random hex (default: 4)
-    # @return [String] Generated ID
-    #
-    # Example:
-    #   generate_id("radio") # => "radio_a3f8"
-    #   generate_id("select", 6) # => "select_a3f8b2"
+    sig { params(prefix: String, length: Integer).returns(String) }
     def generate_id(prefix, length: 4)
       "#{prefix}_#{SecureRandom.hex(length)}"
     end
 
-    # Render a value that can be a String, ViewComponent, or other object
-    # @param value [Object] Value to render
-    # @return [String, nil] Rendered value
+    sig { params(value: Types::Renderable).returns(Types::RenderedContent) }
     def render_value(value)
       return nil unless value.present?
       return value if value.is_a?(String) || value.is_a?(ActiveSupport::SafeBuffer)
+      return value.to_s if value.is_a?(ViewComponent::Slot)
       return render(value) if value.respond_to?(:render_in)
 
-      value
+      nil
     end
 
-    # Convert size string/symbol to integer pixels
-    # Useful for components that accept both symbolic (:small, :large) and numeric sizes
-    # @param size [Symbol, Integer] Size value
-    # @param mapping [Hash] Size to pixel mapping
-    # @return [Integer] Size in pixels
+    sig { params(size: SizeValue, mapping: T::Hash[Symbol, Integer]).returns(SizeValue) }
     def size_to_pixels(size, mapping = {})
       return size if size.is_a?(Integer)
-      mapping[size] || size
-    end
-
-    # Convert dimension value to CSS string
-    # @param value [Numeric, String, nil] Dimension value
-    # @return [String, nil] CSS dimension string
-    #
-    # Examples:
-    #   dimension_to_css(100) # => "100px"
-    #   dimension_to_css("50%") # => "50%"
-    #   dimension_to_css("2rem") # => "2rem"
-    #   dimension_to_css(nil) # => nil
+      mapping[size.to_sym] || size
+    end
+
+    sig { params(value: DimensionInput).returns(T.nilable(String)) }
     def dimension_to_css(value)
       return nil if value.nil?
       return value if value.is_a?(String) && value.strip.present?
@@ -154,30 +147,174 @@ module HakumiComponents
       string.empty? ? nil : string
     end
 
-    # Cast a value to boolean using ActiveModel::Type::Boolean
-    # @param value [Object] Value to cast
-    # @return [Boolean] Casted boolean value
-    #
-    # Example:
-    #   cast_boolean("true") # => true
-    #   cast_boolean("1") # => true
-    #   cast_boolean(0) # => false
-    #   cast_boolean(nil) # => nil
+    sig { params(controller: String, values: Types::StimulusValues).returns(Types::StimulusData) }
+    def stimulus_attrs(controller, values = {})
+      data = T.let({ "controller" => controller }, Types::StimulusData)
+      values.each do |key, value|
+        next if value.nil?
+
+        serialized = value.is_a?(Array) || value.is_a?(Hash) ? value.to_json : value
+        data["#{controller}-#{key.to_s.underscore.dasherize}-value"] = serialized
+      end
+      data
+    end
+
+    sig { params(value: Types::HtmlAttributeValue).returns(Types::DataAttributes) }
+    def data_attributes_from(value)
+      attrs = T.let({}, Types::DataAttributes)
+      return attrs unless value.is_a?(Hash)
+
+      value.each do |key, entry|
+        attrs[key] = entry
+      end
+      attrs
+    end
+
+    sig { params(existing: Types::HtmlAttributeValue, token: String).returns(String) }
+    def append_data_token(existing, token)
+      return token unless existing.is_a?(String) && existing.present?
+
+      [ existing, token ].join(" ")
+    end
+
+    BOOLEAN_CASTER = T.let(ActiveModel::Type::Boolean.new.freeze, ActiveModel::Type::Boolean)
+    private_constant :BOOLEAN_CASTER
+
+    sig { params(value: Types::HtmlPrimitive).returns(T.nilable(T::Boolean)) }
+    def self.cast_boolean(value)
+      BOOLEAN_CASTER.cast(value)
+    end
+
+    sig { params(value: Types::HtmlAttributeValue).returns(Types::HtmlPrimitive) }
+    def self.html_primitive_param(value)
+      return value if value.is_a?(String)
+      return value if value.is_a?(Symbol)
+      return value if value.is_a?(TrueClass)
+      return value if value.is_a?(FalseClass)
+      return value if value.is_a?(Numeric)
+
+      nil
+    end
+
+      sig do
+      params(
+        params: ControllerOptions,
+        key: Symbol
+      ).returns(Types::HtmlAttributeValue)
+    end
+    def self.html_param(params, key)
+      coerce_html_attribute_value(params[key])
+    end
+
+    sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(T::Boolean)) }
+    def self.boolean_html_param(value)
+      scalar = html_primitive_param(value)
+      return nil if scalar.nil?
+
+      cast_boolean(scalar)
+    end
+
+    sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(Symbol)) }
+    def self.symbol_html_param(value)
+      return value.to_sym if value.is_a?(String) || value.is_a?(Symbol)
+
+      nil
+    end
+
+    sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(Integer)) }
+    def self.integer_html_param(value)
+      return value if value.is_a?(Integer)
+      return value.to_i if value.is_a?(String)
+
+      nil
+    end
+
+    sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(Float)) }
+    def self.float_html_param(value)
+      return value.to_f if value.is_a?(String)
+      return value.to_f if value.is_a?(Numeric)
+
+      nil
+    end
+
+    sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(String)) }
+    def self.string_html_param(value)
+      return nil if value.nil?
+      return value if value.is_a?(String)
+      return value.to_s if value.is_a?(Symbol) || value.is_a?(Numeric)
+
+      nil
+    end
+
+    sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(Types::StringOrSymbolArray)) }
+    def self.string_or_symbol_array_html_param(value)
+      return nil unless value.is_a?(Array)
+
+      entries = T.let([], Types::StringOrSymbolArray)
+      value.each do |entry|
+        next if entry.nil?
+
+        entries << entry
+      end
+      entries
+    end
+
+    class << self
+      extend T::Sig
+
+      private
+
+      sig { params(value: RawHtmlInput).returns(Types::HtmlPrimitive) }
+      def coerce_html_primitive(value)
+        return value if value.is_a?(String)
+        return value if value.is_a?(Symbol)
+        return value if value.is_a?(TrueClass)
+        return value if value.is_a?(FalseClass)
+        return value if value.is_a?(Numeric)
+
+        nil
+      end
+
+      sig { params(value: RawHtmlInput).returns(Types::HtmlAttributeValue) }
+      def coerce_html_attribute_value(value)
+        primitive = coerce_html_primitive(value)
+        return primitive unless primitive.nil?
+
+        if value.is_a?(Array)
+          entries = T.let([], T::Array[T.nilable(String)])
+          value.each do |entry|
+            entries << entry if entry.nil? || entry.is_a?(String)
+          end
+          return entries
+        end
+
+        source_hash = if value.is_a?(ActionController::Parameters)
+          value.to_unsafe_h
+        elsif value.is_a?(Hash)
+          value
+        end
+
+        if source_hash
+          attrs = T.let({}, Types::DataAttributes)
+          source_hash.each do |entry_key, entry_value|
+            entry_primitive = coerce_html_primitive(entry_value)
+            attrs[entry_key] = entry_primitive
+          end
+          return attrs
+        end
+
+        nil
+      end
+    end
+
+    sig { params(value: Types::HtmlPrimitive).returns(T.nilable(T::Boolean)) }
     def cast_boolean(value)
-      ActiveModel::Type::Boolean.new.cast(value)
-    end
-
-    # 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
-    #
-    # Example with array:
-    #   build_inline_style(["color: red", "font-size: 14px"]) # => "color: red; font-size: 14px"
-    #
-    # Example with hash:
-    #   build_inline_style(color: "red", "font-size": "14px") # => "color: red; font-size: 14px"
+      self.class.cast_boolean(value)
+    end
+
+    sig { params(styles: T.nilable(Types::StyleValue)).returns(T.nilable(String)) }
     def build_inline_style(styles)
-      return nil if styles.blank?
+      return nil if styles.respond_to?(:blank?) && styles.blank?
 
       style_array = if styles.is_a?(Hash)
         styles.compact.map { |key, value| "#{key}: #{value}" }
@@ -188,5 +325,67 @@ module HakumiComponents
       return nil if style_array.empty?
       style_array.join("; ")
     end
+
+    sig { params(attributes: Types::HtmlAttributes).returns(Types::CssClasses) }
+    def html_classes(attributes)
+      value = attributes[:class]
+      return value if value.is_a?(String) || value.is_a?(Array)
+
+      nil
+    end
+
+    sig { params(base: String, modifiers: Types::ClassModifiers, attributes: Types::HtmlAttributes).returns(String) }
+    def component_classes(base, modifiers = {}, attributes = {})
+      class_names(base, modifiers, html_classes(attributes))
+    end
+
+    sig { params(attributes: Types::HtmlAttributes).returns(T.nilable(String)) }
+    def html_style(attributes)
+      value = attributes[:style]
+      value.is_a?(String) ? value : nil
+    end
+
+    sig { params(key: Types::HtmlKey, default: String, options: I18nOptionValue).returns(String) }
+    def translate_with_default(key, default:, **options)
+      I18n.t(key, scope: i18n_scope, default: default, **options)
+    end
+
+    sig { params(key: Types::HtmlKey, default: String, options: I18nOptionValue).returns(String) }
+    def t_default(key, default:, **options)
+      I18n.t(key, scope: i18n_scope, default: default, **options)
+    end
+
+    sig { returns(String) }
+    def i18n_scope
+      @i18n_scope = T.let(@i18n_scope, T.nilable(String)) unless instance_variable_defined?(:@i18n_scope)
+      @i18n_scope ||= begin
+        class_name = self.class.name
+        raise "#{self.class} must have a name for i18n scope" if class_name.nil?
+
+        class_name
+        .delete_suffix("::Component")
+        .underscore
+        .tr("/", ".")
+      end
+    end
+
+    private
+
+    sig do
+      params(
+        defaults: Types::HtmlAttributeValue,
+        overrides: Types::HtmlAttributeValue
+      ).returns(T.nilable(Types::DataAttributes))
+    end
+    def merge_attribute_hash(defaults, overrides)
+      return defaults if defaults.is_a?(Hash) && !overrides.is_a?(Hash)
+      return overrides if overrides.is_a?(Hash) && !defaults.is_a?(Hash)
+      return nil unless defaults.is_a?(Hash) && overrides.is_a?(Hash)
+
+      merged = T.let({}, Types::DataAttributes)
+      defaults.each { |key, value| merged[key] = value }
+      overrides.each { |key, value| merged[key] = value }
+      merged
+    end
   end
 end