hakumi_components 0.1.18.pre → 0.1.19.pre

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

@@ -1,11 +1,22 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
   module Timeline
     class Component < HakumiComponents::BaseComponent
-      DIRECTIONS = %i[vertical horizontal].freeze
-      MODES = %i[left right alternate].freeze
-      VARIANTS = %i[filled outlined].freeze
+      extend T::Sig
+
+      TitleSpan = T.type_alias { T.nilable(BaseComponent::DimensionInput) }
+      ItemPayload = T.type_alias { T::Hash[String, T.nilable(String)] }
+      ParsedItems = T.type_alias { T::Array[ItemPayload] }
+      ControllerOptions = T.type_alias { T.any(ActionController::Parameters, Types::HtmlAttributes) }
+      ControllerValue = T.type_alias { T.any(Types::HtmlAttributeValue, ParsedItems) }
+      TimelineItem = T.type_alias { T.any(HakumiComponents::Timeline::Item::Component, ViewComponent::Slot) }
+      ItemInput = T.type_alias { T.untyped }
+
+      DIRECTIONS = T.let(%i[vertical horizontal].freeze, T::Array[Symbol])
+      MODES = T.let(%i[left right alternate].freeze, T::Array[Symbol])
+      VARIANTS = T.let(%i[filled outlined].freeze, T::Array[Symbol])
 
       renders_many :items, ->(
         title: nil,
@@ -17,7 +28,6 @@ module HakumiComponents
         **options,
         &block
       ) do
-
         HakumiComponents::Timeline::Item::Component.new(
           title: title,
           body: body,
@@ -31,6 +41,19 @@ module HakumiComponents
         )
       end
 
+      sig do
+        params(
+          direction: Symbol,
+          mode: Symbol,
+          reverse: T::Boolean,
+          pending: Types::Renderable,
+          pending_dot: Types::Renderable,
+          title_span: TitleSpan,
+          variant: Symbol,
+          items: ItemInput,
+          html_options: Types::HtmlAttributeValue
+        ).void
+      end
       def initialize(
         direction: :vertical,
         mode: :left,
@@ -39,64 +62,77 @@ module HakumiComponents
         pending_dot: nil,
         title_span: nil,
         variant: :filled,
+        items: [],
         **html_options
       )
-        @direction = direction
-        @mode = mode
-        @reverse = reverse
-        @pending = pending
-        @pending_dot = pending_dot
-        @title_span = title_span
-        @variant = variant
-        @html_options = html_options
+        @direction = T.let(direction.to_sym, Symbol)
+        @mode = T.let(mode.to_sym, Symbol)
+        @reverse = T.let(cast_boolean(reverse) ? true : false, T::Boolean)
+        @pending = T.let(pending, Types::Renderable)
+        @pending_dot = T.let(pending_dot, Types::Renderable)
+        @title_span = T.let(title_span, TitleSpan)
+        @variant = T.let(variant.to_sym, Symbol)
+        @item_definitions = T.let(normalize_item_definitions(items), ParsedItems)
+        @html_options = T.let(html_options, Types::HtmlAttributes)
 
         validate_props!
       end
 
-      attr_reader :direction, :mode, :reverse, :pending, :pending_dot, :title_span, :variant
-
+      sig do
+        params(
+          params: ControllerOptions
+        ).returns(T::Hash[Symbol, ControllerValue])
+      end
       def self.extract_controller_locals(params)
         {
-          direction: params[:direction],
-          mode: params[:mode],
-          reverse: params[:reverse],
-          pending: params[:pending],
-          pending_dot: params[:pending_dot],
-          title_span: params[:title_span],
-          variant: params[:variant],
-          items: parse_json_param(params[:items])
+          direction: symbol_html_param(html_param(params, :direction)),
+          mode: symbol_html_param(html_param(params, :mode)),
+          reverse: boolean_html_param(html_param(params, :reverse)),
+          pending: string_html_param(html_param(params, :pending)),
+          pending_dot: string_html_param(html_param(params, :pending_dot)),
+          title_span: html_primitive_param(html_param(params, :title_span)),
+          variant: symbol_html_param(html_param(params, :variant)),
+          items: parse_json_param(html_param(params, :items)) || []
         }
       end
 
-      def self.parse_json_param(value)
-        return value unless value.is_a?(String)
+      sig { returns(Symbol) }
+      attr_reader :direction, :mode, :variant
 
-        JSON.parse(value)
-      rescue JSON::ParserError
-        value
-      end
+      sig { returns(T::Boolean) }
+      attr_reader :reverse
 
-      def wrapper_attributes
-        base_attrs = {
-          class: timeline_classes,
-          style: timeline_style,
-          data: stimulus_data
-        }
+      sig { returns(Types::Renderable) }
+      attr_reader :pending, :pending_dot
+
+      sig { returns(TitleSpan) }
+      attr_reader :title_span
 
-        merge_attributes(base_attrs, @html_options.except(:class))
+      sig { returns(Types::HtmlAttributes) }
+      def wrapper_attributes
+        merge_attributes(
+          {
+            class: timeline_classes,
+            style: timeline_style,
+            data: stimulus_attrs("hakumi--timeline", { reverse: reverse })
+          },
+          @html_options.except(:class)
+        )
       end
 
+      sig { returns(T::Array[TimelineItem]) }
       def timeline_items
-        base_items = items.dup
-        base_items << pending_item if pending_item
+        base_items = T.let(programmatic_items + items.dup, T::Array[TimelineItem])
+        pending = pending_item
+        base_items << pending if pending
 
-        return base_items.reverse if reverse
-
-        base_items
+        reverse ? base_items.reverse : base_items
       end
 
+      sig { params(index: Integer, item: TimelineItem).returns(Symbol) }
       def item_position(index, item)
-        return item.position if item.position
+        existing_position = slot_position(item)
+        return existing_position unless existing_position.nil?
 
         case mode
         when :right
@@ -108,12 +144,39 @@ module HakumiComponents
         end
       end
 
+      sig do
+        params(
+          item: TimelineItem,
+          index: Integer,
+          total: Integer
+        ).returns(TimelineItem)
+      end
+      def contextualized_item(item, index, total)
+        if item.is_a?(HakumiComponents::Timeline::Item::Component)
+          return item.with_context(index: index, total: total, position: item_position(index, item), reverse: reverse)
+        end
+
+        raw_item = item.public_send(
+          :with_context,
+          index: index,
+          total: total,
+          position: item_position(index, item),
+          reverse: reverse
+        )
+
+        return raw_item if raw_item.is_a?(ViewComponent::Slot)
+        return raw_item if raw_item.is_a?(HakumiComponents::Timeline::Item::Component)
+
+        item
+      end
+
+      sig { returns(T.nilable(HakumiComponents::Timeline::Item::Component)) }
       def pending_item
-        return if pending.nil?
+        return nil if pending.nil?
 
         HakumiComponents::Timeline::Item::Component.new(
           title: nil,
-          body: pending.is_a?(String) ? pending : nil,
+          body: pending,
           loading: true,
           dot: pending_dot,
           parent: self,
@@ -123,43 +186,113 @@ module HakumiComponents
 
       private
 
-      def stimulus_controller
-        "hakumi--timeline"
+      sig { returns(T::Array[HakumiComponents::Timeline::Item::Component]) }
+      def programmatic_items
+        @item_definitions.map do |item|
+          HakumiComponents::Timeline::Item::Component.new(
+            title: item["title"],
+            body: item["body"] || item["content"],
+            color: item_color(item["color"]),
+            dot: item["dot"],
+            position: item_position_value(item["position"]),
+            loading: cast_boolean(item["loading"]) ? true : false,
+            parent: self
+          )
+        end
       end
 
-      def stimulus_data
-        {
-          controller: stimulus_controller,
-          "#{stimulus_controller}-reverse-value" => reverse
-        }
+      sig { params(value: ItemInput).returns(ParsedItems) }
+      def normalize_item_definitions(value)
+        return [] unless value.is_a?(Array)
+
+        value.filter_map do |entry|
+          next unless entry.is_a?(Hash)
+
+          item = T.let({}, ItemPayload)
+          entry.each do |key, raw_value|
+            item[key.to_s] = raw_value&.to_s
+          end
+          item
+        end
+      end
+
+      sig { params(value: T.nilable(String)).returns(Types::HtmlKey) }
+      def item_color(value)
+        return :blue if value.blank?
+
+        symbol = value.to_sym
+        return symbol if HakumiComponents::Timeline::Item::Component::COLORS.key?(symbol)
+
+        value
+      end
+
+      sig { params(value: T.nilable(String)).returns(T.nilable(Symbol)) }
+      def item_position_value(value)
+        return nil if value.blank?
+
+        value.to_sym
+      end
+
+      sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(ParsedItems)) }
+      def self.parse_json_param(value)
+        return nil unless value.is_a?(String) && value.present?
+
+        parsed = JSON.parse(value)
+        return nil unless parsed.is_a?(Array)
+
+        items = T.let([], ParsedItems)
+        parsed.each do |entry|
+          next unless entry.is_a?(Hash)
+
+          item = T.let({}, T::Hash[String, T.nilable(String)])
+          entry.each do |key, raw_value|
+            item[key.to_s] = raw_value&.to_s
+          end
+          items << item
+        end
+        items
+      rescue JSON::ParserError
+        nil
+      end
+
+      sig { params(item: TimelineItem).returns(T.nilable(Symbol)) }
+      def slot_position(item)
+        return item.position if item.is_a?(HakumiComponents::Timeline::Item::Component)
+
+        raw_position = item.public_send(:position)
+        raw_position.is_a?(Symbol) ? raw_position : nil
       end
 
+      sig { returns(String) }
       def timeline_classes
-        class_names(
+        component_classes(
           "timeline",
           {
             direction => true,
             mode => mode != :left,
-            "reverse" => reverse,
-            "outlined" => variant == :outlined
+            reverse: reverse,
+            outlined: variant == :outlined
           },
-          [ @html_options[:class] ]
+          @html_options
         )
       end
 
+      sig { returns(T.nilable(String)) }
       def timeline_style
         span = normalized_title_span
-        return if span.blank?
+        return nil if span.blank?
 
         "--hakumi-timeline-title-span: #{span};"
       end
 
+      sig { void }
       def validate_props!
         validate_inclusion!(:direction, DIRECTIONS)
         validate_inclusion!(:mode, MODES)
         validate_inclusion!(:variant, VARIANTS)
       end
 
+      sig { returns(T.nilable(String)) }
       def normalized_title_span
         dimension_to_css(title_span)
       end

data/app/components/hakumi_components/timeline/item/component.html.erb

@@ -1,6 +1,6 @@
 <%= tag.div(**wrapper_attributes) do %>
-  <% if title.present? %>
-    <div class="hakumi-timeline-item-title"><%= title %></div>
+  <% if title_content.present? %>
+    <div class="hakumi-timeline-item-title"><%= title_content %></div>
   <% else %>
     <div class="hakumi-timeline-item-title hakumi-timeline-item-title-empty"></div>
   <% end %>

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

@@ -1,17 +1,40 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
   module Timeline
     module Item
       class Component < HakumiComponents::BaseComponent
-        COLORS = {
-          blue: "var(--color-primary)",
-          red: "var(--color-error)",
-          green: "var(--color-success)",
-          gray: "var(--color-text-secondary)"
-        }.freeze
-        POSITIONS = %i[left right].freeze
-
+        extend T::Sig
+
+        ColorValue = T.type_alias { Types::HtmlKey }
+        ContentBlock = T.type_alias { T.nilable(T.proc.returns(Types::RenderedContent)) }
+
+        COLORS = T.let(
+          {
+            blue: "var(--color-primary)",
+            red: "var(--color-error)",
+            green: "var(--color-success)",
+            gray: "var(--color-text-secondary)"
+          }.freeze,
+          T::Hash[Symbol, String]
+        )
+        POSITIONS = T.let(%i[left right].freeze, T::Array[Symbol])
+
+        sig do
+          params(
+            title: Types::Renderable,
+            body: Types::Renderable,
+            color: ColorValue,
+            dot: Types::Renderable,
+            position: T.nilable(Symbol),
+            loading: T::Boolean,
+            parent: T.nilable(HakumiComponents::Timeline::Component),
+            pending: T::Boolean,
+            html_options: Types::HtmlAttributeValue,
+            block: ContentBlock
+          ).void
+        end
         def initialize(
           title: nil,
           body: nil,
@@ -24,22 +47,47 @@ module HakumiComponents
           **html_options,
           &block
         )
-          @title = title
-          @body = body
-          @color = color
-          @dot = dot
-          @position = position
-          @loading = loading
-          @parent = parent
-          @pending = pending
-          @html_options = html_options
-          @content_block = block
+          @title = T.let(title, Types::Renderable)
+          @body = T.let(body, Types::Renderable)
+          @color = T.let(color.is_a?(String) ? color : color.to_sym, ColorValue)
+          @dot = T.let(dot, Types::Renderable)
+          @position = T.let(position, T.nilable(Symbol))
+          @loading = T.let(cast_boolean(loading) ? true : false, T::Boolean)
+          @parent = T.let(parent, T.nilable(HakumiComponents::Timeline::Component))
+          @pending = T.let(cast_boolean(pending) ? true : false, T::Boolean)
+          @html_options = T.let(html_options, Types::HtmlAttributes)
+          @content_block = T.let(block, ContentBlock)
+          @index = T.let(nil, T.nilable(Integer))
+          @total = T.let(nil, T.nilable(Integer))
+          @resolved_position = T.let(nil, T.nilable(Symbol))
+          @reverse = T.let(false, T::Boolean)
           validate_props!
         end
 
-        attr_reader :title, :body, :color, :dot, :position, :loading, :parent, :pending
+        sig { returns(Types::Renderable) }
+        attr_reader :title, :body, :dot
+
+        sig { returns(ColorValue) }
+        attr_reader :color
+
+        sig { returns(T.nilable(Symbol)) }
+        attr_reader :position
 
-        def with_context(index:, total:, position: nil, reverse: false)
+        sig { returns(T::Boolean) }
+        attr_reader :loading, :pending
+
+        sig { returns(T.nilable(HakumiComponents::Timeline::Component)) }
+        attr_reader :parent
+
+        sig do
+          params(
+            index: Integer,
+            total: Integer,
+            position: Symbol,
+            reverse: T::Boolean
+          ).returns(HakumiComponents::Timeline::Item::Component)
+        end
+        def with_context(index:, total:, position:, reverse: false)
           @index = index
           @total = total
           @resolved_position = position
@@ -47,88 +95,101 @@ module HakumiComponents
           self
         end
 
+        sig { returns(Types::HtmlAttributes) }
         def wrapper_attributes
-          base_attrs = {
-            class: item_classes,
-            data: item_data,
-            style: dot_style
-          }
+          merge_attributes(
+            {
+              class: item_classes,
+              data: item_data,
+              style: dot_style
+            },
+            @html_options
+          )
+        end
 
-          merge_attributes(base_attrs, @html_options)
+        sig { returns(Types::RenderedContent) }
+        def title_content
+          render_value(@title)
         end
 
+        sig { returns(Types::RenderedContent) }
         def item_content
-          return @body if @body.present?
+          rendered_body = render_value(@body)
+          return rendered_body if rendered_body.present?
           return content if content.present?
-          return view_context.capture(&@content_block) if @content_block && view_context
+
+          if @content_block && view_context
+            captured = view_context.capture(&@content_block)
+            return captured if captured.present?
+          end
 
           nil
         end
 
+        sig { returns(Symbol) }
         def resolved_position
-          @resolved_position || @position
+          @resolved_position || @position || :left
         end
 
+        sig { returns(T::Boolean) }
         def last_item?
-          # When reversed, the first item in the array (index 0) is the last visual item
-          # When not reversed, the last item in the array is the last visual item
-          if @reverse
-            @index == 0
-          else
-            @index == (@total.to_i - 1)
-          end
-        end
+          index = @index
+          total = @total
+          return false if index.nil? || total.nil?
 
-        def dot_component?
-          dot.respond_to?(:render_in)
+          @reverse ? index.zero? : index == (total - 1)
         end
 
+        sig { returns(Types::RenderedContent) }
         def dot_content
-          @dot_content ||= begin
-            if dot_component?
-              render(dot)
-            elsif dot.present?
-              dot
-            elsif loading
-              render(HakumiComponents::Icon::Component.new(name: :loading, spin: true, size: 12))
-            end
-          end
+          rendered_dot = render_value(@dot)
+          return rendered_dot if rendered_dot.present?
+          return render(HakumiComponents::Icon::Component.new(name: :loading, spin: true, size: 12)) if loading
+
+          nil
         end
 
         private
 
+        sig { returns(String) }
         def item_classes
-          classes = [ "hakumi-timeline-item" ]
-          classes << "hakumi-timeline-item-#{resolved_position}" if resolved_position
-          classes << "hakumi-timeline-item-last" if last_item?
-          classes << "hakumi-timeline-item-loading" if loading
-          classes << "hakumi-timeline-item-pending" if pending
-          classes << "hakumi-timeline-item-custom" if dot.present?
-          classes.join(" ")
+          component_classes(
+            "timeline-item",
+            {
+              resolved_position => true,
+              last: last_item?,
+              loading: loading,
+              pending: pending,
+              custom: value_present?(@dot)
+            },
+            @html_options
+          )
         end
 
+        sig { returns(Types::DataAttributes) }
         def item_data
           { timeline_index: @index || 0 }
         end
 
+        sig { returns(T.nilable(String)) }
         def dot_style
-          return unless color
-
           color_value = color_value_for(color)
-          return unless color_value
+          return nil if color_value.nil?
 
           "--hakumi-timeline-dot-color: #{color_value};"
         end
 
+        sig { params(value: ColorValue).returns(T.nilable(String)) }
         def color_value_for(value)
-          return COLORS[value.to_sym] if value.is_a?(Symbol) && COLORS.key?(value.to_sym)
+          return COLORS[value] if value.is_a?(Symbol) && COLORS.key?(value)
           return value if value.is_a?(String)
 
           nil
         end
 
+        sig { void }
         def validate_props!
-          validate_inclusion!(:position, POSITIONS) if @position
+          validate_inclusion!(:position, POSITIONS) unless @position.nil?
           validate_inclusion!(:color, COLORS.keys) if @color.is_a?(Symbol)
         end
       end

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

@@ -4,7 +4,7 @@
     data-<%= stimulus_controller %>-target="trigger">
     <%= content %>
   </div>
-  <% if has_tooltip_content? %>
+  <% if tooltip_content? %>
     <div
       class="<%= tooltip_classes %>"
       role="tooltip"