hakumi_components 0.1.17.pre → 0.1.19.pre

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

@@ -0,0 +1,393 @@
+# typed: strict
+# frozen_string_literal: true
+
+module HakumiComponents
+  module Progress
+    class Component < HakumiComponents::BaseComponent
+      extend T::Sig
+
+      ProgressValue = T.type_alias { Numeric }
+      ProgressOption = T.type_alias { Types::HtmlKey }
+      InfoTooltipInput = T.type_alias { T.nilable(T.any(Types::HtmlKey, T::Boolean)) }
+      DisplaySize = T.type_alias { T.nilable(BaseComponent::SizeValue) }
+      StrokeGradient = T.type_alias { T::Hash[String, String] }
+      StrokeColorInput = T.type_alias { T.nilable(T.any(String, Types::DataAttributes, StrokeGradient)) }
+      StrokeColor = T.type_alias { T.nilable(T.any(String, StrokeGradient)) }
+      FormatProc = T.type_alias do
+        T.proc.params(
+          percent: ProgressValue,
+          success_percent: T.nilable(ProgressValue)
+        ).returns(String)
+      end
+      FormatValue = T.type_alias { T.nilable(T.any(Types::Renderable, FormatProc)) }
+      TooltipMode = T.type_alias { T.nilable(Symbol) }
+      TooltipOptionsMap = T.type_alias { T::Hash[Types::HtmlKey, Types::HtmlPrimitive] }
+      StepStateValue = T.type_alias { Types::HtmlPrimitive }
+      StepState = T.type_alias { T::Hash[Symbol, StepStateValue] }
+      SizeInput = T.type_alias { DisplaySize }
+      TYPES = T.let(%i[line circle dashboard].freeze, T::Array[Symbol])
+      STATUSES = T.let(%i[normal success exception active].freeze, T::Array[Symbol])
+      LINE_SIZES = T.let(%i[small default].freeze, T::Array[Symbol])
+      LINECAPS = T.let(%i[round square butt].freeze, T::Array[Symbol])
+
+      sig do
+        params(
+          params: BaseComponent::ControllerOptions
+        ).returns(Types::HtmlAttributes)
+      end
+      def self.extract_controller_locals(params)
+        ControllerLocalsParser.call(params)
+      end
+
+      sig do
+        params(
+          percent: ProgressValue,
+          success_percent: T.nilable(ProgressValue),
+          type: ProgressOption,
+          status: T.nilable(ProgressOption),
+          show_info: T::Boolean,
+          size: DisplaySize,
+          stroke_width: T.nilable(ProgressValue),
+          stroke_color: StrokeColorInput,
+          trail_color: T.nilable(String),
+          stroke_linecap: ProgressOption,
+          steps: T.nilable(Integer),
+          gap_degree: T.nilable(ProgressValue),
+          gap_position: T.nilable(ProgressOption),
+          format: FormatValue,
+          info_tooltip: InfoTooltipInput,
+          info_tooltip_threshold: ProgressValue,
+          info_tooltip_options: T.nilable(TooltipOptionsMap),
+          html_options: Types::HtmlAttributeValue
+        ).void
+      end
+      def initialize(
+        percent: 0,
+        success_percent: nil,
+        type: :line,
+        status: nil,
+        show_info: true,
+        size: nil,
+        stroke_width: nil,
+        stroke_color: nil,
+        trail_color: nil,
+        stroke_linecap: :round,
+        steps: nil,
+        gap_degree: nil,
+        gap_position: nil,
+        format: nil,
+        info_tooltip: :auto,
+        info_tooltip_threshold: 20,
+        info_tooltip_options: nil,
+        **html_options
+      )
+        @type = T.let(type.to_sym, Symbol)
+        @status = T.let(status&.to_sym, T.nilable(Symbol))
+        @show_info = T.let(cast_boolean(show_info) != false, T::Boolean)
+        @size = T.let(normalize_size(size), DisplaySize)
+        @stroke_width = T.let(stroke_width&.to_f, T.nilable(Float))
+        @stroke_color = T.let(normalize_stroke_color(stroke_color), StrokeColor)
+        @trail_color = T.let(trail_color&.strip&.presence, T.nilable(String))
+        @stroke_linecap = T.let(stroke_linecap.to_sym, Symbol)
+        @steps = T.let(steps, T.nilable(Integer))
+        @gap_degree = T.let(gap_degree&.to_f, T.nilable(Float))
+        @gap_position = T.let(gap_position&.to_sym, T.nilable(Symbol))
+        @format = T.let(format, FormatValue)
+        @html_options = T.let(html_options, Types::HtmlAttributes)
+        @info_tooltip_mode = T.let(normalize_info_tooltip(info_tooltip), TooltipMode)
+        @info_tooltip_threshold = T.let(info_tooltip_threshold.to_f, Float)
+        @info_tooltip_options = T.let(normalize_tooltip_options(info_tooltip_options), Types::HtmlAttributes)
+        @percent = T.let(clamp_percent(percent), ProgressValue)
+        @success_percent = T.let(success_percent.nil? ? nil : clamp_percent(success_percent), T.nilable(ProgressValue))
+        @info_tooltip_policy = T.let(nil, T.nilable(Progress::InfoTooltipPolicy))
+        @status_state = T.let(nil, T.nilable(Progress::StatusState))
+        @attribute_renderer = T.let(nil, T.nilable(Progress::AttributeRenderer))
+
+        validate_props!
+      end
+
+      sig { returns(Types::HtmlAttributes) }
+      def wrapper_attributes
+        merge_attributes(
+          {
+            class: wrapper_classes,
+            role: "progressbar",
+            "aria-valuenow": @percent,
+            "aria-valuemin": 0,
+            "aria-valuemax": 100,
+            "aria-label": accessibility_label,
+            data: data_attributes
+          },
+          @html_options
+        )
+      end
+
+      sig { returns(Types::RenderedContent) }
+      def formatted_info
+        return nil unless show_info?
+
+        info_text
+      end
+
+      sig { returns(T::Boolean) }
+      def show_info?
+        @show_info
+      end
+
+      sig { returns(T::Boolean) }
+      def inline_info?
+        show_info? && !wrap_with_tooltip?
+      end
+
+      sig { returns(T::Boolean) }
+      def wrap_with_tooltip?
+        info_tooltip_policy.wrap?
+      end
+
+      sig { returns(Types::HtmlAttributes) }
+      def tooltip_component_options
+        options = T.let(@info_tooltip_options.dup, Types::HtmlAttributes)
+        options[:title] = tooltip_label unless options.key?(:title)
+        options
+      end
+
+      sig { returns(Integer) }
+      def info_tooltip_threshold_value
+        @info_tooltip_threshold.to_i
+      end
+
+      sig { returns(String) }
+      def tooltip_label
+        info_value.tooltip_label
+      end
+
+      sig { returns(T::Boolean) }
+      def tooltip_enabled?
+        info_tooltip_policy.enabled?
+      end
+
+      sig { returns(T::Boolean) }
+      def line?
+        @type == :line
+      end
+
+      sig { returns(T::Boolean) }
+      def circle?
+        @type == :circle
+      end
+
+      sig { returns(T::Boolean) }
+      def dashboard?
+        @type == :dashboard
+      end
+
+      sig { returns(T::Boolean) }
+      def steps?
+        !@steps.nil? && @steps.positive?
+      end
+
+      sig { returns(Symbol) }
+      def status
+        status_state.value
+      end
+
+      sig { returns(Types::DataAttributes) }
+      def data_attributes
+        {
+          controller: "hakumi--progress",
+          "hakumi--progress-type-value": @type,
+          "hakumi--progress-percent-value": @percent,
+          "hakumi--progress-success-percent-value": @success_percent,
+          "hakumi--progress-status-value": status,
+          "hakumi--progress-status-explicit-value": status_state.explicit?,
+          "hakumi--progress-steps-value": @steps,
+          "hakumi--progress-gap-degree-value": @gap_degree,
+          "hakumi--progress-gap-position-value": attribute_renderer.circle_gap_position,
+          "hakumi--progress-stroke-width-value": attribute_renderer.stroke_width_value,
+          "hakumi--progress-show-info-value": show_info?,
+          "hakumi--progress-custom-info-value": custom_info?
+        }.compact
+      end
+
+      sig { returns(T::Boolean) }
+      def success_segment?
+        success = @success_percent
+        !success.nil? && success.positive?
+      end
+
+      private
+
+      sig { returns(Types::RenderedContent) }
+      def info_text
+        info_value.text
+      end
+
+      sig { returns(Progress::InfoTooltipPolicy) }
+      def info_tooltip_policy
+        policy = @info_tooltip_policy
+        return policy unless policy.nil?
+
+        policy = Progress::InfoTooltipPolicy.new(
+          mode: @info_tooltip_mode,
+          type: @type,
+          circle_size: attribute_renderer.circle_size,
+          threshold: info_tooltip_threshold_value
+        )
+        @info_tooltip_policy = policy
+      end
+
+      sig { returns(Progress::InfoValue) }
+      def info_value
+        Progress::InfoValue.new(
+          percent: @percent,
+          success_percent: @success_percent,
+          content: content,
+          format_value: @format,
+          rendered_format: rendered_info_format
+        )
+      end
+
+      sig { returns(T.untyped) }
+      def rendered_info_format
+        return nil if @format.nil? || @format.is_a?(Proc)
+
+        render_value(@format)
+      end
+
+      sig { returns(Progress::StatusState) }
+      def status_state
+        state = @status_state
+        return state unless state.nil?
+
+        state = Progress::StatusState.new(percent: @percent, explicit_status: @status)
+        @status_state = state
+      end
+
+      sig { void }
+      def validate_props!
+        validate_inclusion!(:type, TYPES)
+        validate_inclusion!(:status, STATUSES)
+        validate_inclusion!(:stroke_linecap, LINECAPS)
+
+        if line? && @size.is_a?(Symbol)
+          validate_inclusion!(:size, LINE_SIZES)
+        end
+
+        if (circle? || dashboard?) && @size.is_a?(Symbol)
+          raise ArgumentError, "size must be numeric for circle or dashboard"
+        end
+      end
+
+      sig { returns(String) }
+      def wrapper_classes
+        modifiers = T.let(
+          {
+            @type => true,
+            "status-#{status}" => true,
+            "show-info" => show_info?,
+            "linecap-#{@stroke_linecap}" => true,
+            small: line? && @size == :small,
+            steps: steps?
+          },
+          Types::ClassModifiers
+        )
+
+        component_classes("progress", modifiers, @html_options)
+      end
+
+      sig { returns(String) }
+      def accessibility_label
+        "Progress #{percent_label}"
+      end
+
+      sig { params(value: ProgressValue).returns(ProgressValue) }
+      def clamp_percent(value)
+        numeric = value.to_f
+        return 0 if numeric.nan?
+
+        clamped = numeric.clamp(0, 100)
+        whole_number?(clamped) ? clamped.to_i : clamped
+      end
+
+      sig { returns(T::Boolean) }
+      def custom_info?
+        info_value.custom?
+      end
+
+      sig { params(value: InfoTooltipInput).returns(TooltipMode) }
+      def normalize_info_tooltip(value)
+        string_value = value.is_a?(String) ? value.strip.downcase : value
+
+        return :always if string_value == :always || string_value == "always"
+        return :auto if string_value == :auto || string_value.nil?
+
+        cast_boolean(value) ? :auto : nil
+      end
+
+      sig { params(value: T.nilable(TooltipOptionsMap)).returns(Types::HtmlAttributes) }
+      def normalize_tooltip_options(value)
+        options = T.let({}, Types::HtmlAttributes)
+        return options if value.nil?
+
+        value.each do |key, entry_value|
+          options[key.to_sym] = entry_value
+        end
+        options
+      end
+
+      sig { params(value: SizeInput).returns(DisplaySize) }
+      def normalize_size(value)
+        return value if value.nil? || value.is_a?(Integer)
+        return value.to_sym if value.is_a?(String) && LINE_SIZES.include?(value.to_sym)
+        return value if value.is_a?(Symbol) && LINE_SIZES.include?(value)
+
+        raise ArgumentError, "size must be one of #{LINE_SIZES.inspect} or a numeric value"
+      end
+
+      sig { params(value: StrokeColorInput).returns(StrokeColor) }
+      def normalize_stroke_color(value)
+        return nil if value.nil?
+        return value.strip.presence if value.is_a?(String)
+
+        Progress::StrokeGradientValue.normalize(value)
+      end
+
+      sig { returns(Progress::AttributeRenderer) }
+      def attribute_renderer
+        renderer = @attribute_renderer
+        return renderer unless renderer.nil?
+
+        style_builder = T.let(
+          ->(styles) { build_inline_style(styles) },
+          Progress::AttributeRenderer::StyleBuilder
+        )
+        renderer = Progress::AttributeRenderer.new(
+          type: @type,
+          percent: @percent,
+          success_percent: @success_percent,
+          size: @size,
+          stroke_width: @stroke_width,
+          stroke_color: @stroke_color,
+          trail_color: @trail_color,
+          stroke_linecap: @stroke_linecap,
+          steps: @steps,
+          gap_degree: @gap_degree,
+          gap_position: @gap_position,
+          gradient_id: generate_id("hakumi-progress-gradient"),
+          style_builder: style_builder
+        )
+        @attribute_renderer = renderer
+      end
+
+      sig { returns(String) }
+      def percent_label
+        info_value.percent_label
+      end
+
+      sig { params(value: ProgressValue).returns(T::Boolean) }
+      def whole_number?(value)
+        (value.to_f % 1.0).zero?
+      end
+    end
+  end
+end

data/app/components/hakumi_components/progress/controller_locals_parser.rb

@@ -0,0 +1,130 @@
+# typed: strict
+# frozen_string_literal: true
+
+module HakumiComponents
+  module Progress
+    class ControllerLocalsParser
+      extend T::Sig
+
+      DisplaySize = T.type_alias { T.nilable(BaseComponent::SizeValue) }
+      StrokeGradient = T.type_alias { T::Hash[String, String] }
+      StrokeColor = T.type_alias { T.nilable(T.any(String, StrokeGradient)) }
+      TooltipOptionsMap = T.type_alias { T::Hash[Types::HtmlKey, Types::HtmlPrimitive] }
+
+      class << self
+        extend T::Sig
+
+        sig { params(params: BaseComponent::ControllerOptions).returns(Types::HtmlAttributes) }
+        def call(params)
+          {
+            percent: parse_number(html_param(params, :percent)),
+            success_percent: parse_number(html_param(params, :success_percent)),
+            type: symbol_html_param(html_param(params, :type)),
+            status: symbol_html_param(html_param(params, :status)),
+            show_info: boolean_html_param(html_param(params, :show_info)),
+            size: parse_size(html_param(params, :size)),
+            stroke_width: parse_number(html_param(params, :stroke_width)),
+            stroke_color: parse_stroke_color(html_param(params, :stroke_color)),
+            trail_color: string_html_param(html_param(params, :trail_color)),
+            stroke_linecap: symbol_html_param(html_param(params, :stroke_linecap)),
+            steps: integer_html_param(html_param(params, :steps)),
+            gap_degree: parse_number(html_param(params, :gap_degree)),
+            gap_position: symbol_html_param(html_param(params, :gap_position)),
+            format: string_html_param(html_param(params, :format)),
+            info_tooltip: html_primitive_param(html_param(params, :info_tooltip)),
+            info_tooltip_threshold: parse_number(html_param(params, :info_tooltip_threshold)),
+            info_tooltip_options: parse_tooltip_options(html_param(params, :info_tooltip_options))
+          }.compact
+        end
+
+        private
+
+        sig { params(params: BaseComponent::ControllerOptions, key: Symbol).returns(Types::HtmlAttributeValue) }
+        def html_param(params, key)
+          BaseComponent.html_param(params, key)
+        end
+
+        sig { params(value: Types::HtmlAttributeValue).returns(Types::HtmlPrimitive) }
+        def html_primitive_param(value)
+          BaseComponent.html_primitive_param(value)
+        end
+
+        sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(T::Boolean)) }
+        def boolean_html_param(value)
+          BaseComponent.boolean_html_param(value)
+        end
+
+        sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(Symbol)) }
+        def symbol_html_param(value)
+          BaseComponent.symbol_html_param(value)
+        end
+
+        sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(Integer)) }
+        def integer_html_param(value)
+          BaseComponent.integer_html_param(value)
+        end
+
+        sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(String)) }
+        def string_html_param(value)
+          BaseComponent.string_html_param(value)
+        end
+
+        sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(Float)) }
+        def parse_number(value)
+          return nil if value.nil?
+          return value.to_f if value.is_a?(Numeric)
+          return nil unless value.is_a?(String)
+
+          stripped = value.strip
+          return nil if stripped.empty?
+
+          Float(stripped)
+        rescue ArgumentError
+          nil
+        end
+
+        sig { params(value: Types::HtmlAttributeValue).returns(DisplaySize) }
+        def parse_size(value)
+          return nil if value.nil?
+          return value if value.is_a?(Integer)
+          return value.to_i if value.is_a?(Float)
+
+          if value.is_a?(String)
+            stripped = value.strip
+            return nil if stripped.empty?
+
+            size_name = stripped.to_sym
+            return size_name if Component::LINE_SIZES.include?(size_name)
+
+            return stripped.to_i
+          end
+
+          nil
+        end
+
+        sig { params(value: Types::HtmlAttributeValue).returns(StrokeColor) }
+        def parse_stroke_color(value)
+          return nil if value.nil?
+          return value if value.is_a?(String) && value.present?
+          return value.to_s if value.is_a?(Symbol)
+
+          return StrokeGradientValue.normalize(value, compact_blank: false) if value.is_a?(Hash)
+
+          nil
+        end
+
+        sig { params(value: Types::HtmlAttributeValue).returns(T.nilable(TooltipOptionsMap)) }
+        def parse_tooltip_options(value)
+          return nil unless value.is_a?(Hash)
+
+          options = T.let({}, TooltipOptionsMap)
+          value.each do |key, entry_value|
+            primitive = html_primitive_param(entry_value)
+            options[key] = primitive
+          end
+          options
+        end
+      end
+    end
+  end
+end

data/app/components/hakumi_components/progress/info_tooltip_policy.rb

@@ -0,0 +1,39 @@
+# typed: strict
+# frozen_string_literal: true
+
+module HakumiComponents
+  module Progress
+    class InfoTooltipPolicy
+      extend T::Sig
+
+      TooltipMode = T.type_alias { T.nilable(Symbol) }
+
+      sig { params(mode: TooltipMode, type: Symbol, circle_size: Integer, threshold: Integer).void }
+      def initialize(mode:, type:, circle_size:, threshold:)
+        @mode = T.let(mode, TooltipMode)
+        @type = T.let(type, Symbol)
+        @circle_size = T.let(circle_size, Integer)
+        @threshold = T.let(threshold, Integer)
+      end
+
+      sig { returns(T::Boolean) }
+      def enabled?
+        !@mode.nil?
+      end
+
+      sig { returns(T::Boolean) }
+      def wrap?
+        return false unless enabled?
+
+        case @mode
+        when :always
+          true
+        when :auto
+          @type == :circle && @circle_size <= @threshold
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/app/components/hakumi_components/progress/info_value.rb

@@ -0,0 +1,75 @@
+# typed: strict
+# frozen_string_literal: true
+
+module HakumiComponents
+  module Progress
+    class InfoValue
+      extend T::Sig
+
+      ProgressValue = T.type_alias { Numeric }
+      FormatProc = T.type_alias do
+        T.proc.params(
+          percent: ProgressValue,
+          success_percent: T.nilable(ProgressValue)
+        ).returns(String)
+      end
+      FormatValue = T.type_alias { T.nilable(T.any(Types::Renderable, FormatProc)) }
+
+      sig do
+        params(
+          percent: ProgressValue,
+          success_percent: T.nilable(ProgressValue),
+          content: T.untyped,
+          format_value: FormatValue,
+          rendered_format: T.untyped
+        ).void
+      end
+      def initialize(percent:, success_percent:, content:, format_value:, rendered_format:)
+        @percent = T.let(percent, ProgressValue)
+        @success_percent = T.let(success_percent, T.nilable(ProgressValue))
+        @content = T.let(content, T.untyped)
+        @format_value = T.let(format_value, FormatValue)
+        @rendered_format = T.let(rendered_format, T.untyped)
+      end
+
+      sig { returns(T.untyped) }
+      def text
+        return @content if present?(@content)
+
+        format_value = @format_value
+        return format_value.call(@percent, @success_percent) if format_value.is_a?(Proc)
+        return @rendered_format if present?(@rendered_format)
+
+        percent_label
+      end
+
+      sig { returns(String) }
+      def tooltip_label
+        value = text
+        present?(value) ? value.to_s : percent_label
+      end
+
+      sig { returns(T::Boolean) }
+      def custom?
+        present?(@content) || !@format_value.nil?
+      end
+
+      sig { returns(String) }
+      def percent_label
+        whole_number?(@percent.to_f) ? "#{@percent.to_i}%" : "#{@percent}%"
+      end
+
+      private
+
+      sig { params(value: T.untyped).returns(T::Boolean) }
+      def present?(value)
+        value.respond_to?(:present?) ? value.present? : !value.nil?
+      end
+
+      sig { params(value: ProgressValue).returns(T::Boolean) }
+      def whole_number?(value)
+        (value.to_f % 1.0).zero?
+      end
+    end
+  end
+end

data/app/components/hakumi_components/progress/status_state.rb

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+module HakumiComponents
+  module Progress
+    class StatusState
+      extend T::Sig
+
+      ProgressValue = T.type_alias { Numeric }
+
+      sig { params(percent: ProgressValue, explicit_status: T.nilable(Symbol)).void }
+      def initialize(percent:, explicit_status:)
+        @percent = T.let(percent, ProgressValue)
+        @explicit_status = T.let(explicit_status, T.nilable(Symbol))
+      end
+
+      sig { returns(Symbol) }
+      def value
+        status = @explicit_status
+        return status unless status.nil?
+
+        @percent.to_f >= 100 ? :success : :normal
+      end
+
+      sig { returns(T::Boolean) }
+      def explicit?
+        !@explicit_status.nil?
+      end
+    end
+  end
+end