hakumi_components 0.1.18.pre → 0.1.19.pre

data/app/components/hakumi_components/form/item/component.rb

@@ -1,25 +1,22 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
   module Form
     module Item
-      # Hakumi Form Item component
-      # Wrapper component for form fields that handles labels, errors, and help text
-      # This is the central component that all form inputs should use or delegate to
-      #
-      # @example Basic usage
-      #   <%= render HakumiComponents::Form::Item::Component.new(label: "Email") do %>
-      #     <%= render HakumiComponents::Input::Component.new(name: "email", standalone: true) %>
-      #   <% end %>
-      #
-      # @example With error
-      #   <%= render HakumiComponents::Form::Item::Component.new(
-      #     label: "Email",
-      #     errors: ["can't be blank"]
-      #   ) do %>
-      #     <%= render HakumiComponents::Input::Component.new(name: "email", standalone: true) %>
-      #   <% end %>
       class Component < HakumiComponents::BaseComponent
+        extend T::Sig
+
+        sig do
+          params(
+            label: T.nilable(String),
+            caption: T.nilable(String),
+            errors: T.any(String, T::Array[String]),
+            required: T::Boolean,
+            field_id: T.nilable(String),
+            html_options: Types::HtmlAttributeValue
+          ).void
+        end
         def initialize(
           label: nil,
           caption: nil,
@@ -28,28 +25,31 @@ module HakumiComponents
           field_id: nil,
           **html_options
         )
-          @label = label
-          @caption = caption
-          @errors = Array(errors)
-          @required = required
-          @field_id = field_id
-          @html_options = html_options
+          @label = T.let(label, T.nilable(String))
+          @caption = T.let(caption, T.nilable(String))
+          @errors = T.let(Array(errors), T::Array[String])
+          @required = T.let(required, T::Boolean)
+          @field_id = T.let(field_id, T.nilable(String))
+          @html_options = T.let(html_options, Types::HtmlAttributes)
         end
 
+        sig { returns(ActiveSupport::SafeBuffer) }
         def call
           content_tag(:div, wrapper_content, wrapper_attributes)
         end
 
         private
 
-        def has_error?
+        sig { returns(T::Boolean) }
+        def error?
           @errors.any?
         end
 
+        sig { returns(Types::HtmlAttributes) }
         def wrapper_attributes
           classes = [ "hakumi-form-item" ]
-          classes << "hakumi-form-item-has-error" if has_error?
-          classes << "hakumi-form-item-with-help" if has_error? || @caption
+          classes << "hakumi-form-item-has-error" if error?
+          classes << "hakumi-form-item-with-help" if error? || @caption
 
           merge_attributes(
             { class: classes.join(" ") },
@@ -57,6 +57,7 @@ module HakumiComponents
           )
         end
 
+        sig { returns(ActiveSupport::SafeBuffer) }
         def wrapper_content
           safe_join([
             label_content,
@@ -64,6 +65,7 @@ module HakumiComponents
           ].compact)
         end
 
+        sig { returns(T.nilable(ActiveSupport::SafeBuffer)) }
         def label_content
           return nil if @label.blank?
 
@@ -77,6 +79,7 @@ module HakumiComponents
           end
         end
 
+        sig { returns(ActiveSupport::SafeBuffer) }
         def control_content
           content_tag(:div, class: "hakumi-form-item-control") do
             safe_join([
@@ -86,18 +89,21 @@ module HakumiComponents
           end
         end
 
+        sig { returns(ActiveSupport::SafeBuffer) }
         def control_input_content
           content_tag(:div, content, class: "hakumi-form-item-control-input")
         end
 
+        sig { returns(T.nilable(ActiveSupport::SafeBuffer)) }
         def explain_content
-          return nil unless @caption || has_error?
+          return nil unless @caption || error?
 
           content_tag(:div, class: "hakumi-form-item-explain") do
-            has_error? ? error_content : caption_content
+            error? ? error_content : caption_content
           end
         end
 
+        sig { returns(ActiveSupport::SafeBuffer) }
         def error_content
           content_tag(:div, @errors.first,
             class: "hakumi-form-item-explain-error",
@@ -105,6 +111,7 @@ module HakumiComponents
           )
         end
 
+        sig { returns(ActiveSupport::SafeBuffer) }
         def caption_content
           content_tag(:div, @caption, class: "hakumi-form-item-extra")
         end

data/app/components/hakumi_components/grid/col/component.rb

@@ -1,9 +1,36 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
   module Grid
     module Col
       class Component < HakumiComponents::BaseComponent
+        extend T::Sig
+
+        GRID_RANGE = T.let((0..24).to_a.freeze, T::Array[Integer])
+        RESPONSIVE_PROPS = T.let(%i[span offset order pull push].freeze, T::Array[Symbol])
+        BreakpointSettings = T.type_alias { T::Hash[Symbol, Integer] }
+        BreakpointValue = T.type_alias { T.any(Integer, BreakpointSettings) }
+        BreakpointInputs = T.type_alias { T::Hash[Symbol, T.nilable(BreakpointValue)] }
+
+        sig do
+          params(
+            span: T.nilable(Integer),
+            offset: T.nilable(Integer),
+            order: T.nilable(Integer),
+            pull: T.nilable(Integer),
+            push: T.nilable(Integer),
+            flex: BaseComponent::DimensionInput,
+            xs: T.nilable(BreakpointValue),
+            sm: T.nilable(BreakpointValue),
+            md: T.nilable(BreakpointValue),
+            lg: T.nilable(BreakpointValue),
+            xl: T.nilable(BreakpointValue),
+            xxl: T.nilable(BreakpointValue),
+            component: Symbol,
+            html_options: HakumiComponents::Types::HtmlAttributeValue
+          ).void
+        end
         def initialize(
           span: nil,
           offset: nil,
@@ -20,23 +47,66 @@ module HakumiComponents
           component: :div,
           **html_options
         )
-          @span = span
-          @offset = offset
-          @order = order
-          @pull = pull
-          @push = push
-          @flex = flex
-          @breakpoints = { xs: xs, sm: sm, md: md, lg: lg, xl: xl, xxl: xxl }
-          @component = component
-          @html_options = html_options
+          @span = T.let(span, T.nilable(Integer))
+          @offset = T.let(offset, T.nilable(Integer))
+          @order = T.let(order, T.nilable(Integer))
+          @pull = T.let(pull, T.nilable(Integer))
+          @push = T.let(push, T.nilable(Integer))
+          @flex = T.let(flex, BaseComponent::DimensionInput)
+          @breakpoints = T.let(
+            { xs: xs, sm: sm, md: md, lg: lg, xl: xl, xxl: xxl },
+            BreakpointInputs
+          )
+          @component = T.let(component, Symbol)
+          @html_options = T.let(html_options, HakumiComponents::Types::HtmlAttributes)
+
+          validate_props!
         end
 
+        sig { returns(ActiveSupport::SafeBuffer) }
         def call
           content_tag(@component, content, wrapper_attributes)
         end
 
         private
 
+        sig { void }
+        def validate_props!
+          validate_grid_value!(:span, @span)
+          validate_grid_value!(:offset, @offset)
+          validate_grid_value!(:order, @order)
+          validate_grid_value!(:pull, @pull)
+          validate_grid_value!(:push, @push)
+          validate_breakpoints!
+        end
+
+        sig { params(prop: Symbol, value: T.nilable(Integer)).void }
+        def validate_grid_value!(prop, value)
+          return if value.nil?
+          return if GRID_RANGE.include?(value)
+
+          raise ArgumentError, "#{prop} must be between 0 and 24, got #{value.inspect}"
+        end
+
+        sig { void }
+        def validate_breakpoints!
+          @breakpoints.each do |size, value|
+            next if value.nil?
+
+            if value.is_a?(Integer)
+              validate_grid_value!(size, value)
+            elsif value.is_a?(Hash)
+              value.each do |prop, val|
+                unless RESPONSIVE_PROPS.include?(prop)
+                  raise ArgumentError, "#{size} responsive prop must be one of #{RESPONSIVE_PROPS.inspect}, got #{prop.inspect}"
+                end
+                validate_grid_value!(:"#{size}.#{prop}", val)
+              end
+            end
+          end
+        end
+
+        sig { returns(String) }
         def wrapper_classes
           classes = [ "hakumi-col" ]
 
@@ -51,7 +121,7 @@ module HakumiComponents
           @breakpoints.each do |size, value|
             next if value.nil?
 
-            if value.is_a?(Numeric)
+            if value.is_a?(Integer)
               classes << "hakumi-col-#{size}-#{value}"
             elsif value.is_a?(Hash)
               value.each do |prop, val|
@@ -61,11 +131,13 @@ module HakumiComponents
             end
           end
 
-          class_names(nil, {}, [ classes, @html_options[:class] ])
+          classes.concat(Array(html_classes(@html_options)).compact)
+          classes.compact.join(" ")
         end
 
+        sig { returns(HakumiComponents::Types::HtmlAttributes) }
         def wrapper_attributes
-          combined_style = [ @html_options[:style], flex_style ].compact.join(";")
+          combined_style = [ html_style(@html_options), flex_style ].compact.join(";")
           attrs = {
             class: wrapper_classes
           }
@@ -74,11 +146,12 @@ module HakumiComponents
           merge_attributes(attrs, @html_options.except(:class, :style))
         end
 
+        sig { returns(T.nilable(String)) }
         def flex_style
           return nil unless @flex
 
-          style = []
-          if @flex.is_a?(Numeric)
+          style = T.let([], T::Array[String])
+          if @flex.is_a?(Integer)
             style << "flex: #{@flex} #{@flex} auto"
           elsif @flex == "auto"
             style << "flex: 1 1 auto"
@@ -88,9 +161,7 @@ module HakumiComponents
             style << "flex: #{@flex}"
           end
 
-          # Merge with existing style
-          existing_style = @html_options[:style]
-          [ existing_style, style.join(";") ].compact.join(";")
+          style.join(";")
         end
       end
     end

data/app/components/hakumi_components/grid/row/component.rb

@@ -1,12 +1,25 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
   module Grid
     module Row
       class Component < HakumiComponents::BaseComponent
-        JUSTIFY_OPTIONS = [ :start, :end, :center, :"space-around", :"space-between" ].freeze
-        ALIGN_OPTIONS = [ :top, :middle, :bottom ].freeze
+        extend T::Sig
 
+        JUSTIFY_VALUES = T.let([ :start, :end, :center, :"space-around", :"space-between" ].freeze, T::Array[Symbol])
+        ALIGN_VALUES = T.let([ :top, :middle, :bottom ].freeze, T::Array[Symbol])
+
+        sig do
+          params(
+            gutter: T.nilable(T.any(Integer, [ Integer, Integer ])),
+            justify: Symbol,
+            align: Symbol,
+            wrap: T::Boolean,
+            component: Symbol,
+            html_options: HakumiComponents::Types::HtmlAttributeValue
+          ).void
+        end
         def initialize(
           gutter: 0,
           justify: :start,
@@ -15,34 +28,38 @@ module HakumiComponents
           component: :div,
           **html_options
         )
-          @gutter = normalize_gutter(gutter)
-          @justify = justify
-          @align = align
-          @wrap = wrap
-          @component = component
-          @html_options = html_options
+          @gutter = T.let(normalize_gutter(gutter), [ Integer, Integer ])
+          @justify = T.let(justify, Symbol)
+          @align = T.let(align, Symbol)
+          @wrap = T.let(wrap, T::Boolean)
+          @component = T.let(component, Symbol)
+          @html_options = T.let(html_options, HakumiComponents::Types::HtmlAttributes)
 
           validate_props!
         end
 
+        sig { returns(ActiveSupport::SafeBuffer) }
         def call
           content_tag(@component, content, wrapper_attributes)
         end
 
         private
 
+        sig { void }
         def validate_props!
-          validate_inclusion!(:justify, JUSTIFY_OPTIONS)
-          validate_inclusion!(:align, ALIGN_OPTIONS)
+          validate_inclusion!(:justify, JUSTIFY_VALUES)
+          validate_inclusion!(:align, ALIGN_VALUES)
         end
 
+        sig { params(gutter: T.nilable(T.any(Integer, [ Integer, Integer ]))).returns([ Integer, Integer ]) }
         def normalize_gutter(gutter)
           return [ 0, 0 ] if gutter.nil?
-          return [ gutter, gutter ] if gutter.is_a?(Numeric)
-          return gutter if gutter.is_a?(Array) && gutter.size == 2
-          [ 0, 0 ]
+          return [ gutter, gutter ] if gutter.is_a?(Integer)
+
+          gutter
         end
 
+        sig { returns(String) }
         def wrapper_classes
           class_names(
             "row",
@@ -51,10 +68,11 @@ module HakumiComponents
               "justify-#{@justify}": @justify != :start,
               "align-#{@align}": @align != :top
             },
-            [ @html_options[:class] ]
+            html_classes(@html_options)
           )
         end
 
+        sig { returns(HakumiComponents::Types::HtmlAttributes) }
         def wrapper_attributes
           attrs = {
             class: wrapper_classes,
@@ -63,14 +81,14 @@ module HakumiComponents
           merge_attributes(attrs, @html_options.except(:class, :style))
         end
 
+        sig { returns(String) }
         def gutter_styles
           x, y = @gutter
-          styles = []
+          styles = T.let([], T::Array[String])
           styles << "--row-gutter-x: #{x}px" if x > 0
           styles << "--row-gutter-y: #{y}px" if y > 0
 
-          # Merge with existing style if present
-          existing_style = @html_options[:style]
+          existing_style = html_style(@html_options)
           [ existing_style, styles.join(";") ].compact.join(";")
         end
       end

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

@@ -1,38 +1,28 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
   module Icon
-    # Icon component for rendering Ant Design icons
-    #
-    # Supports:
-    # - Ant Design icons (via name)
-    # - Custom SVG (via svg parameter)
-    # - Three themes: outlined (default), filled, two-tone
-    #
-    # @example Basic usage
-    #   <%= render HakumiComponents::Icon::Component.new(name: "user") %>
-    #
-    # @example With size
-    #   <%= render HakumiComponents::Icon::Component.new(name: "home", size: 24) %>
-    #
-    # @example Filled variant
-    #   <%= render HakumiComponents::Icon::Component.new(name: "heart", theme: :filled) %>
-    #
-    # @example Custom SVG
-    #   <%= render HakumiComponents::Icon::Component.new(svg: "<svg>...</svg>") %>
     class Component < HakumiComponents::BaseComponent
-      THEMES = [ :outlined, :filled, :two_tone ].freeze
-      DEFAULT_SIZE = 16
-      DEFAULT_COLOR = "currentColor"
-
-      # @param name [String, Symbol] Icon name (e.g., :user, :home, :settings)
-      # @param theme [Symbol] Icon theme (:outlined, :filled, :two_tone)
-      # @param size [Integer] Icon size in pixels
-      # @param svg [String] Custom SVG content (overrides name)
-      # @param color [String] Icon color (CSS color value)
-      # @param spin [Boolean] Whether the icon should spin
-      # @param rotate [Integer] Rotation in degrees (0, 90, 180, 270)
-      # @param html_options [Hash] Additional HTML attributes
+      extend T::Sig
+
+      THEMES = T.let([ :outlined, :filled, :two_tone ].freeze, T::Array[Symbol])
+      DEFAULT_SIZE = T.let(16, Integer)
+      DEFAULT_COLOR = T.let("currentColor", String)
+
+      sig do
+        params(
+          name: T.nilable(Types::StringOrSymbol),
+          theme: Symbol,
+          size: T.nilable(Integer),
+          svg: T.nilable(String),
+          color: T.nilable(String),
+          spin: T::Boolean,
+          rotate: T.nilable(Integer),
+          fallback_to_outlined: T::Boolean,
+          html_options: Types::HtmlAttributeValue
+        ).void
+      end
       def initialize(
         name: nil,
         theme: :outlined,
@@ -46,54 +36,55 @@ module HakumiComponents
       )
         @name = name
         @theme = theme
-        @size = size
+        @size = T.let(size, T.nilable(Integer))
         @svg = svg
-        @color = color || DEFAULT_COLOR
-        @spin = spin
+        @color = T.let(color || DEFAULT_COLOR, String)
+        @spin = T.let(spin, T::Boolean)
         @rotate = rotate
-        @fallback_to_outlined = fallback_to_outlined
-        @html_options = html_options
+        @fallback_to_outlined = T.let(fallback_to_outlined, T::Boolean)
+        @html_options = T.let(html_options, Types::HtmlAttributes)
 
         validate_props!
       end
 
       private
 
+      sig { void }
       def validate_props!
-        # Either name or svg must be provided
         unless @name || @svg
           raise ArgumentError, "Either name or svg must be provided"
         end
 
-        # Validate theme
         validate_inclusion!(:theme, THEMES)
 
-        # Validate rotate if present
         if @rotate && ![ 0, 90, 180, 270 ].include?(@rotate)
           raise ArgumentError, "rotate must be one of [0, 90, 180, 270]"
         end
       end
 
+      sig { returns(String) }
       def wrapper_classes
         class_names(
           "icon",
           { spin: @spin },
-          [ @html_options[:class] ]
+          [ html_class_name ]
         )
       end
 
+      sig { returns(T.nilable(String)) }
       def wrapper_styles
-        styles = []
+        styles = T.let([], T::Array[String])
         styles << "font-size: #{@size}px" if @size
         styles << "color: #{@color}" if @color
         styles << "transform: rotate(#{@rotate}deg)" if @rotate
 
-        custom_style = @html_options[:style]
+        custom_style = html_style_value
         styles << custom_style if custom_style
 
         styles.join("; ") if styles.any?
       end
 
+      sig { returns(Types::HtmlAttributes) }
       def wrapper_attributes
         attrs = {
           class: wrapper_classes,
@@ -106,39 +97,34 @@ module HakumiComponents
         merge_attributes(attrs, @html_options.except(:class, :style))
       end
 
+      sig { returns(ActiveSupport::SafeBuffer) }
       def svg_content
         if @svg
-          # Use custom SVG with sanitization
           sanitize_svg(@svg).html_safe
         else
-          # Load SVG from icons directory
           icon_svg
         end
       end
 
-      # Sanitize SVG content to prevent XSS attacks
-      # Removes dangerous elements (script, iframe) and event handlers
-      # This is a blacklist approach that preserves SVG functionality while preventing XSS
+      sig { params(svg_string: String).returns(String) }
       def sanitize_svg(svg_string)
         return "" if svg_string.blank?
 
-        # Remove dangerous tags
         sanitized = svg_string.dup
         sanitized.gsub!(/<script[^>]*>.*?<\/script>/mi, "")
         sanitized.gsub!(/<iframe[^>]*>.*?<\/iframe>/mi, "")
         sanitized.gsub!(/<object[^>]*>.*?<\/object>/mi, "")
         sanitized.gsub!(/<embed[^>]*>/i, "")
 
-        # Remove event handler attributes (onclick, onerror, onload, etc.)
         sanitized.gsub!(/\s+on\w+\s*=\s*["'][^"']*["']/i, "")
         sanitized.gsub!(/\s+on\w+\s*=\s*[^\s>]+/i, "")
 
-        # Remove javascript: protocol in href and other URL attributes
         sanitized.gsub!(/\s+(href|src|xlink:href)\s*=\s*["']javascript:[^"']*["']/i, "")
 
         sanitized
       end
 
+      sig { returns(ActiveSupport::SafeBuffer) }
       def icon_svg
         svg = HakumiComponents::Icon::Loader.load(@name, @theme)
         if svg.blank? && fallback_enabled?
@@ -150,6 +136,7 @@ module HakumiComponents
         placeholder_icon_svg
       end
 
+      sig { returns(ActiveSupport::SafeBuffer) }
       def placeholder_icon_svg
         <<~SVG.html_safe
           <svg viewBox="0 0 24 24" focusable="false" width="1em" height="1em" fill="currentColor">
@@ -159,9 +146,22 @@ module HakumiComponents
         SVG
       end
 
+      sig { returns(T::Boolean) }
       def fallback_enabled?
         @fallback_to_outlined && @theme != :outlined
       end
+
+      sig { returns(T.nilable(String)) }
+      def html_class_name
+        css_class = @html_options[:class]
+        css_class.is_a?(String) ? css_class : nil
+      end
+
+      sig { returns(T.nilable(String)) }
+      def html_style_value
+        style = @html_options[:style]
+        style.is_a?(String) ? style : nil
+      end
     end
   end
 end

data/app/components/hakumi_components/image/component.html.erb

@@ -22,7 +22,7 @@
       <% else %>
         <div class="hakumi-image-mask-info">
           <%= render HakumiComponents::Icon::Component.new(name: :eye, size: 16) %>
-          <span>Preview</span>
+          <span><%= preview_text %></span>
         </div>
       <% end %>
     </div>
@@ -42,34 +42,34 @@
           </span>
         </button>
         <div class="hakumi-image-preview-operations">
-          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleFlipY" title="Flip Vertical">
+          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleFlipY" title="<%= flip_vertical_title %>">
             <span class="hakumi-icon" style="transform: rotate(90deg)">
               <%= render HakumiComponents::Icon::Component.new(name: 'swap', theme: :outlined) %>
             </span>
           </button>
-          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleFlipX" title="Flip Horizontal">
+          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleFlipX" title="<%= flip_horizontal_title %>">
             <span class="hakumi-icon">
               <%= render HakumiComponents::Icon::Component.new(name: 'swap', theme: :outlined) %>
             </span>
           </button>
           <span class="hakumi-image-preview-operations-divider"></span>
-          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleRotateLeft" title="Rotate Left">
+          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleRotateLeft" title="<%= rotate_left_title %>">
             <span class="hakumi-icon">
               <%= render HakumiComponents::Icon::Component.new(name: 'rotate-left', theme: :outlined) %>
             </span>
           </button>
-          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleRotateRight" title="Rotate Right">
+          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleRotateRight" title="<%= rotate_right_title %>">
             <span class="hakumi-icon">
               <%= render HakumiComponents::Icon::Component.new(name: 'rotate-right', theme: :outlined) %>
             </span>
           </button>
           <span class="hakumi-image-preview-operations-divider"></span>
-          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleZoomOut" title="Zoom Out">
+          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleZoomOut" title="<%= zoom_out_title %>">
             <span class="hakumi-icon">
               <%= render HakumiComponents::Icon::Component.new(name: 'zoom-out', theme: :outlined) %>
             </span>
           </button>
-          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleZoomIn" title="Zoom In">
+          <button class="hakumi-image-preview-operations-operation" data-action="click->hakumi--image#handleZoomIn" title="<%= zoom_in_title %>">
             <span class="hakumi-icon">
               <%= render HakumiComponents::Icon::Component.new(name: 'zoom-in', theme: :outlined) %>
             </span>