hakumi_components 0.1.17.pre → 0.1.19.pre

data/app/components/{hakumi → hakumi_components}/time_picker/component.rb

@@ -1,15 +1,38 @@
+# typed: strict
 # frozen_string_literal: true
 
-module Hakumi
+module HakumiComponents
   module TimePicker
-    # Hakumi TimePicker component
-    # A time selection input with dropdown panels for hours, minutes, seconds, and period.
-    class Component < Hakumi::BaseComponent
-      include Hakumi::Concerns::FormField
-
-      SIZES = [ :small, :middle, :large ].freeze
-      VARIANTS = [ :default, :borderless, :filled ].freeze
-
+    class Component < HakumiComponents::BaseComponent
+      extend T::Sig
+
+      include HakumiComponents::Concerns::FormField
+
+      VARIANTS = T.let([ :default, :borderless, :filled ].freeze, T::Array[Symbol])
+
+      sig do
+        params(
+          name: T.nilable(Types::FormFieldName),
+          label: T.nilable(String),
+          caption: T.nilable(String),
+          value: Types::FormFieldScalar,
+          default_value: Types::FormFieldScalar,
+          format: String,
+          hour_step: Integer,
+          minute_step: Integer,
+          second_step: Integer,
+          use_12_hours: T::Boolean,
+          show_now: T::Boolean,
+          disabled: T::Boolean,
+          allow_clear: T::Boolean,
+          placeholder: T.nilable(String),
+          size: Symbol,
+          variant: Symbol,
+          errors: Types::FormFieldErrors,
+          standalone: T::Boolean,
+          html_options: Types::HtmlAttributeValue
+        ).void
+      end
       def initialize(
         name: nil,
         label: nil,
@@ -25,13 +48,13 @@ module Hakumi
         disabled: false,
         allow_clear: false,
         placeholder: nil,
-        size: :middle,
+        size: :default,
         variant: :default,
         errors: [],
         standalone: true,
         **html_options
       )
-        @name = name || generate_id("time_picker")
+        @name = T.let(name || generate_id("time_picker"), Types::FormFieldName)
         @label = label
         @caption = caption
         @value = value
@@ -47,29 +70,42 @@ module Hakumi
         @placeholder = placeholder
         @size = size
         @variant = variant
-        @errors = Array(errors)
+        @errors = T.let(errors, Types::FormFieldErrors)
         @standalone = standalone
-        @html_options = html_options
-        @required = false
+        @html_options = T.let(html_options, Types::HtmlAttributes)
+        @required = T.let(false, T::Boolean)
+        initialize_form_field_contract!(
+          name: @name,
+          label: @label,
+          caption: @caption,
+          errors: @errors,
+          standalone: @standalone,
+          required: @required,
+          html_options: @html_options
+        )
 
         validate_props!
       end
 
       private
 
+      sig { void }
       def validate_props!
         validate_inclusion!(:size, SIZES)
         validate_inclusion!(:variant, VARIANTS)
       end
 
+      sig { returns(Types::FormFieldScalar) }
       def current_value
         @value.presence || @default_value
       end
 
+      sig { returns(T::Boolean) }
       def show_seconds?
         @format.to_s.include?("ss")
       end
 
+      sig { returns(String) }
       def wrapper_classes
         class_names(
           "time-picker",
@@ -83,40 +119,42 @@ module Hakumi
             "use-12-hours": @use_12_hours,
             "has-value": current_value.present?
           },
-          [ @html_options[:class] ]
+          [ html_class_name ]
         )
       end
 
+      sig { returns(Types::HtmlAttributes) }
       def wrapper_attributes
         base_attrs = {
           class: wrapper_classes,
           data: {
             controller: "hakumi--time-picker",
-            hakumi__time_picker_allow_clear_value: @allow_clear ? "true" : "false",
-            hakumi__time_picker_disabled_value: @disabled ? "true" : "false",
-            hakumi__time_picker_use_twelve_hours_value: @use_12_hours ? "true" : "false",
+            hakumi__time_picker_allow_clear_value: @allow_clear,
+            hakumi__time_picker_disabled_value: @disabled,
+            hakumi__time_picker_use_twelve_hours_value: @use_12_hours,
             hakumi__time_picker_format_value: @format,
             hakumi__time_picker_hour_step_value: @hour_step,
             hakumi__time_picker_minute_step_value: @minute_step,
             hakumi__time_picker_second_step_value: @second_step,
-            hakumi__time_picker_show_now_value: @show_now ? "true" : "false"
+            hakumi__time_picker_show_now_value: @show_now
           }
         }
 
         merge_attributes(base_attrs, @html_options.except(:class))
       end
 
+      sig { returns(Types::HtmlAttributes) }
       def input_attributes
         {
           type: "text",
-          name: @name,
+          name: form_field_name,
           id: input_id,
           value: current_value,
           placeholder: @placeholder,
           class: "hakumi-time-picker-input",
           disabled: @disabled ? true : nil,
           readonly: true,
-          "aria-invalid": has_error? ? "true" : nil,
+          "aria-invalid": error? ? "true" : nil,
           "aria-describedby": describedby_ids,
           data: {
             action: "click->hakumi--time-picker#toggle",
@@ -125,11 +163,13 @@ module Hakumi
         }.compact
       end
 
+      sig { params(value: Integer).returns(Integer) }
       def step_value(value)
         value = value.to_i
         value.positive? ? value : 1
       end
 
+      sig { returns(T::Array[String]) }
       def formatted_hours
         step = step_value(@hour_step)
         hours = if @use_12_hours
@@ -141,19 +181,33 @@ module Hakumi
         hours.map { |hour| format("%02d", hour) }
       end
 
+      sig { returns(T::Array[String]) }
       def formatted_minutes
         step = step_value(@minute_step)
         (0..59).step(step).to_a.map { |minute| format("%02d", minute) }
       end
 
+      sig { returns(T::Array[String]) }
       def formatted_seconds
         step = step_value(@second_step)
         (0..59).step(step).to_a.map { |second| format("%02d", second) }
       end
 
+      sig { returns(T::Array[String]) }
       def period_options
         [ "AM", "PM" ]
       end
+
+      sig { returns(T::Boolean) }
+      def use_12_hours?
+        @use_12_hours
+      end
+
+      sig { returns(T.nilable(String)) }
+      def html_class_name
+        css_class = @html_options[:class]
+        css_class.is_a?(String) ? css_class : nil
+      end
     end
   end
 end

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

@@ -0,0 +1,8 @@
+<%= tag.div(**wrapper_attributes) do %>
+  <div class="hakumi-timeline-items">
+    <% items = timeline_items %>
+    <% items.each_with_index do |item, index| %>
+      <%= render contextualized_item(item, index, items.length) %>
+    <% end %>
+  </div>
+<% end %>

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

@@ -0,0 +1,301 @@
+# typed: strict
+# frozen_string_literal: true
+
+module HakumiComponents
+  module Timeline
+    class Component < HakumiComponents::BaseComponent
+      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,
+        body: nil,
+        color: :blue,
+        dot: nil,
+        position: nil,
+        loading: false,
+        **options,
+        &block
+      ) do
+        HakumiComponents::Timeline::Item::Component.new(
+          title: title,
+          body: body,
+          color: color,
+          dot: dot,
+          position: position,
+          loading: loading,
+          parent: self,
+          **options,
+          &block
+        )
+      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,
+        reverse: false,
+        pending: nil,
+        pending_dot: nil,
+        title_span: nil,
+        variant: :filled,
+        items: [],
+        **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
+
+      sig do
+        params(
+          params: ControllerOptions
+        ).returns(T::Hash[Symbol, ControllerValue])
+      end
+      def self.extract_controller_locals(params)
+        {
+          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
+
+      sig { returns(Symbol) }
+      attr_reader :direction, :mode, :variant
+
+      sig { returns(T::Boolean) }
+      attr_reader :reverse
+
+      sig { returns(Types::Renderable) }
+      attr_reader :pending, :pending_dot
+
+      sig { returns(TitleSpan) }
+      attr_reader :title_span
+
+      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 = T.let(programmatic_items + items.dup, T::Array[TimelineItem])
+        pending = pending_item
+        base_items << pending if pending
+
+        reverse ? base_items.reverse : base_items
+      end
+
+      sig { params(index: Integer, item: TimelineItem).returns(Symbol) }
+      def item_position(index, item)
+        existing_position = slot_position(item)
+        return existing_position unless existing_position.nil?
+
+        case mode
+        when :right
+          :right
+        when :alternate
+          index.even? ? :left : :right
+        else
+          :left
+        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 nil if pending.nil?
+
+        HakumiComponents::Timeline::Item::Component.new(
+          title: nil,
+          body: pending,
+          loading: true,
+          dot: pending_dot,
+          parent: self,
+          pending: true
+        )
+      end
+
+      private
+
+      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
+
+      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
+        component_classes(
+          "timeline",
+          {
+            direction => true,
+            mode => mode != :left,
+            reverse: reverse,
+            outlined: variant == :outlined
+          },
+          @html_options
+        )
+      end
+
+      sig { returns(T.nilable(String)) }
+      def timeline_style
+        span = normalized_title_span
+        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
+    end
+  end
+end

data/app/components/{hakumi → 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 %>