stimulus_plumbers 0.4.14 → 0.4.16

data/lib/stimulus_plumbers/components/password_strength.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class PasswordStrength < Plumber::Base
+      LEVEL_KEYS = %i[weak fine strong].freeze
+
+      class << self
+        def meter_id_for(input_id)
+          "#{input_id}_meter"
+        end
+
+        def rules_id_for(input_id)
+          "#{input_id}_rules"
+        end
+      end
+
+      def render(input:, input_id:, config:)
+        @config = config
+        template.content_tag(:div, **wrapper_options(config, input_id)) do
+          template.safe_join([input, render_meter(input_id), render_level, render_rules_heading, render_rules(input_id)])
+        end
+      end
+
+      private
+
+      def wrapper_options(config, input_id)
+        stimulus = config.to_stimulus
+        merge_html_options(
+          theme.resolve(:password_strength_wrapper),
+          data: {
+            controller:                        "password-strength",
+            password_strength_rules_value:     stimulus[:rules].to_json,
+            password_strength_options_value:   stimulus[:options].to_json,
+            password_strength_labels_value:    stimulus[:labels].to_json,
+            password_strength_progress_outlet: "##{self.class.meter_id_for(input_id)}"
+          }
+        )
+      end
+
+      def render_meter(input_id)
+        ProgressMeter.new(template).render(value: 0, id: self.class.meter_id_for(input_id), **@config.thresholds)
+      end
+
+      def render_level
+        template.content_tag(
+          :p,
+          level_labels[:weak],
+          **merge_html_options(
+            theme.resolve(:password_strength_level),
+            data: { password_strength_target: "level" },
+            aria: { live: "polite" }
+          )
+        )
+      end
+
+      def level_labels
+        LEVEL_KEYS.index_with { |key| I18n.t("stimulus_plumbers.password.levels.#{key}") }
+      end
+
+      def render_rules_heading
+        template.content_tag(
+          :p,
+          I18n.t("stimulus_plumbers.password.rules_heading"),
+          **theme.resolve(:password_strength_rules_heading)
+        )
+      end
+
+      def render_rules(input_id)
+        html_options = merge_html_options(
+          theme.resolve(:password_strength_rules),
+          id: self.class.rules_id_for(input_id)
+        )
+        template.content_tag(:ul, **html_options) do
+          template.safe_join(@config.rules.map { |key, label| render_rule(key, label) })
+        end
+      end
+
+      def render_rule(key, label)
+        template.content_tag(
+          :li,
+          **merge_html_options(
+            theme.resolve(:password_strength_rule),
+            data: {
+              password_strength_target: "rule", rule: key, satisfied: "false"
+            }
+          )
+        ) { template.safe_join([rule_icon("check", "checkIcon", hidden: true), rule_icon("close", "closeIcon"), label]) }
+      end
+
+      def rule_icon(name, target, hidden: false)
+        Icon.new(template).render(
+          name,
+          size:   :sm,
+          aria:   { hidden: "true" },
+          data:   { password_strength_target: target },
+          hidden: hidden,
+          **theme.resolve(:password_strength_rule_icon)
+        )
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/progress/shared.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    module Progress
+      # Shared stimulus/ARIA wiring and value formatting for the progress variants
+      # (bar, segmented, ring, meter) and for the range form field, which reuses the readout.
+      module Shared
+        FORMATS = %i[percent value value_max].freeze
+
+        private
+
+        def progress_stimulus_data(value:, min:, max:, variant:, **extra)
+          {
+            data: {
+              controller:               "progress",
+              "progress-variant-value": variant,
+              "progress-current-value": value,
+              "progress-min-value":     min,
+              "progress-max-value":     max,
+              **extra
+            }
+          }
+        end
+
+        def progress_aria(value:, min:, max:, indeterminate: false, valuetext: nil)
+          aria = { valuemin: min, valuemax: max }
+          aria[:valuenow]  = value unless indeterminate
+          aria[:valuetext] = valuetext if valuetext
+          aria
+        end
+
+        def validate_format!(format)
+          return if format.nil? || (format.respond_to?(:to_sym) && FORMATS.include?(format.to_sym))
+
+          raise ArgumentError, "unknown format: #{format.inspect} (expected one of #{FORMATS.join(", ")})"
+        end
+
+        # Keep in sync with the progress controller's formattedValue().
+        def value_text(format, current, min, max)
+          case format&.to_sym
+          when :percent   then "#{percent(current, min, max).round}%"
+          when :value     then integral(current).to_s
+          when :value_max then "#{integral(current)} / #{integral(max)}"
+          end
+        end
+
+        # Comparable#clamp raises when min > max; the JS returns max there, and percent() then yields 0%.
+        def clamp(value, min, max)
+          return max if max < min
+
+          value.clamp(min, max)
+        end
+
+        def percent(current, min, max)
+          range = max - min
+          range <= 0 ? 0 : (current - min).fdiv(range) * 100
+        end
+
+        # A `step: 0.1` range holds 45.5 — to_i would paint a 45 fill under a 45.5 thumb.
+        def numeric(value)
+          return value if value.is_a?(Numeric)
+
+          Float(value, exception: false) || 0
+        end
+
+        # 45.0 renders as "45" — JS has no Float/Integer distinction to mirror.
+        def integral(number)
+          (number % 1).zero? ? number.to_i : number
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/progress_bar.rb

@@ -3,47 +3,149 @@
 module StimulusPlumbers
   module Components
     class ProgressBar < Plumber::Base
+      include Progress::Shared
+
       def render(...)
         render_bar(...)
       end
 
+      def render_segmented(
+        value:,
+        segments:,
+        min: 0,
+        max: 100,
+        mode: :discrete,
+        indeterminate: false,
+        ramp: nil,
+        format: nil,
+        **kwargs
+      )
+        validate_segments!(segments, format)
+        current = clamp(value, min, max)
+        html_options = merge_html_options(
+          theme.resolve(:progress_segment_group),
+          kwargs,
+          segmented_stimulus_data(current, min, max, mode, indeterminate),
+          { role: "progressbar", aria: progress_aria(value: current, min: min, max: max, indeterminate: indeterminate) }
+        )
+        slots = ramp_intents(ramp, segments).map { |intent| render_segment(intent: intent) }
+        template.content_tag(:div, template.safe_join(slots), **html_options)
+      end
+
       private
 
-      def render_bar(value:, min: 0, max: 100, indeterminate: false, **kwargs)
-        html_options = merge_html_options(
-          theme.resolve(:progress_bar),
+      def validate_segments!(segments, format)
+        raise ArgumentError, "format: is not supported with segments:" unless format.nil?
+        raise ArgumentError, "segments must be a positive integer" unless segments.is_a?(Integer) && segments.positive?
+      end
+
+      def segmented_stimulus_data(current, min, max, mode, indeterminate)
+        progress_stimulus_data(
+          value:                          current,
+          min:                            min,
+          max:                            max,
+          variant:                        "segmented",
+          "progress-segment-mode-value":  mode,
+          "progress-indeterminate-value": indeterminate
+        )
+      end
+
+      def render_bar(value:, min: 0, max: 100, indeterminate: false, format: nil, readout: :inside, **kwargs)
+        validate_format!(format)
+        validate_readout!(readout)
+        current      = clamp(value, min, max)
+        text         = value_text(format, current, min, max) unless indeterminate
+        html_options = bar_html_options(current, min, max, indeterminate, format, readout, text, kwargs)
+        template.content_tag(:div, bar_body(format, readout, text), **html_options)
+      end
+
+      def validate_readout!(readout)
+        return if Themes::Schema::Progress::Ranges::PLACEMENT.include?(readout&.to_sym)
+
+        raise ArgumentError, "readout must be one of #{Themes::Schema::Progress::Ranges::PLACEMENT.join(", ")}"
+      end
+
+      # The track clips its overflow, so an outside readout needs the root to be a wrapper.
+      def bar_body(format, readout, text)
+        return render_fill if format.nil?
+        return template.safe_join([render_fill, render_value(text, :inside)]) if readout.to_sym == :inside
+
+        template.safe_join([render_track, render_value(text, :outside)])
+      end
+
+      def render_track
+        template.content_tag(:div, render_fill, **merge_html_options(theme.resolve(:progress_bar, labelled: false)))
+      end
+
+      def bar_html_options(current, min, max, indeterminate, format, readout, text, kwargs)
+        # `percent` omits aria-valuetext — AT derives the percentage from aria-valuenow itself.
+        valuetext = text unless format&.to_sym == :percent
+        aria      = progress_aria(value: current, min: min, max: max, indeterminate: indeterminate, valuetext: valuetext)
+        merge_html_options(
+          bar_root_theme(format, readout),
           kwargs,
-          stimulus_data(value: value, min: min, max: max, indeterminate: indeterminate),
-          { role: "progressbar", aria: progress_aria(value: value, min: min, max: max, indeterminate: indeterminate) }
+          bar_stimulus_data(current, min, max, indeterminate, format),
+          { role: "progressbar", aria: aria }
         )
-        template.content_tag(:div, render_fill, **html_options)
       end
 
-      def render_fill
+      def bar_root_theme(format, readout)
+        return theme.resolve(:progress_bar_group) if format && readout.to_sym == :outside
+
+        theme.resolve(:progress_bar, labelled: !format.nil?)
+      end
+
+      def bar_stimulus_data(current, min, max, indeterminate, format)
+        progress_stimulus_data(
+          value:                          current,
+          min:                            min,
+          max:                            max,
+          variant:                        "bar",
+          "progress-indeterminate-value": indeterminate,
+          **(format.nil? ? {} : { "progress-format-value": format })
+        )
+      end
+
+      # aria-hidden: the value reaches AT via aria-valuenow/aria-valuetext, not this span.
+      def render_value(text, placement)
+        key = placement == :outside ? :progress_bar_value_outside : :progress_bar_value
         template.content_tag(
-          :div,
-          nil,
-          **merge_html_options(theme.resolve(:progress_bar_fill), { data: { "progress-target": "fill" } })
+          :span,
+          text,
+          **merge_html_options(
+            theme.resolve(key),
+            { data: { "progress-target": "value" }, aria: { hidden: true } }
+          )
         )
       end
 
-      def progress_aria(value:, min:, max:, indeterminate:)
-        aria = { valuemin: min, valuemax: max }
-        aria[:valuenow] = value unless indeterminate
-        aria
+      # `data-intent` is a theme-independent styling hook the theme colors via attribute variants.
+      def render_fill(intent: nil, key: :progress_bar_fill)
+        data = { "progress-target": "fill" }
+        data[:intent] = intent if intent
+        template.content_tag(:div, nil, **merge_html_options(theme.resolve(key), { data: data }))
+      end
+
+      # Slots are aria-hidden — the container owns the progressbar ARIA.
+      def render_segment(intent: nil)
+        template.content_tag(
+          :div,
+          render_fill(intent: intent, key: :progress_segment_fill),
+          **merge_html_options(theme.resolve(:progress_segment), { aria: { hidden: true } })
+        )
       end
 
-      def stimulus_data(value:, min:, max:, indeterminate:)
-        {
-          data: {
-            controller:                     "progress",
-            "progress-variant-value":       "bar",
-            "progress-current-value":       value,
-            "progress-min-value":           min,
-            "progress-max-value":           max,
-            "progress-indeterminate-value": indeterminate
-          }
-        }
+      # `:strength` buckets each slot into danger/warning/success thirds by position; nil = uncolored.
+      def ramp_intents(ramp, count)
+        return Array.new(count) unless ramp == :strength
+
+        Array.new(count) do |i|
+          case (i + 1).fdiv(count)
+          when ..(1.0 / 3) then :danger
+          when ..(2.0 / 3) then :warning
+          else :success
+          end
+        end
       end
     end
   end

data/lib/stimulus_plumbers/components/progress_meter.rb

@@ -3,6 +3,8 @@
 module StimulusPlumbers
   module Components
     class ProgressMeter < Plumber::Base
+      include Progress::Shared
+
       def render(...)
         render_meter(...)
       end
@@ -14,25 +16,25 @@ module StimulusPlumbers
         html_options = merge_html_options(
           theme.resolve(:progress_meter),
           kwargs,
-          stimulus_data(value: value, min: min, max: max, low: low, high: high, optimum: optimum),
+          progress_stimulus_data(
+            value:             value,
+            min:               min,
+            max:               max,
+            variant:           "meter",
+            "progress-target": "meter",
+            **threshold_data(low: low, high: high, optimum: optimum)
+          ),
           attrs
         )
         template.content_tag(:meter, nil, **html_options)
       end
 
-      def stimulus_data(value:, min:, max:, low:, high:, optimum:)
-        data = {
-          controller:               "progress",
-          "progress-target":        "meter",
-          "progress-variant-value": "meter",
-          "progress-current-value": value,
-          "progress-min-value":     min,
-          "progress-max-value":     max
-        }
-        data["progress-low-value"]     = low if low
-        data["progress-high-value"]    = high if high
-        data["progress-optimum-value"] = optimum if optimum
-        { data: data }
+      def threshold_data(low:, high:, optimum:)
+        data = {}
+        data[:"progress-low-value"]     = low if low
+        data[:"progress-high-value"]    = high if high
+        data[:"progress-optimum-value"] = optimum if optimum
+        data
       end
     end
   end

data/lib/stimulus_plumbers/components/progress_ring.rb

@@ -3,40 +3,26 @@
 module StimulusPlumbers
   module Components
     class ProgressRing < Plumber::Base
+      include Progress::Shared
+
       def render(...)
         render_ring(...)
       end
 
       private
 
-      def render_ring(value:, max: 100, min: 0, indeterminate: false, **kwargs)
+      def render_ring(value:, max: 100, min: 0, indeterminate: false, size: nil, **kwargs)
+        current      = clamp(value, min, max)
         icon_options = merge_html_options(
-          theme.resolve(:progress_ring),
+          theme.resolve(:progress_ring, size: size),
           kwargs,
-          stimulus_data(value: value, min: min, max: max, indeterminate: indeterminate),
-          { role: "progressbar", aria: progress_aria(value: value, min: min, max: max, indeterminate: indeterminate) }
+          progress_stimulus_data(
+            value: current, min: min, max: max, variant: "ring", "progress-indeterminate-value": indeterminate
+          ),
+          { role: "progressbar", aria: progress_aria(value: current, min: min, max: max, indeterminate: indeterminate) }
         )
         Components::Icon.new(template).render("progress-ring", **icon_options)
       end
-
-      def progress_aria(value:, min:, max:, indeterminate:)
-        aria = { valuemin: min, valuemax: max }
-        aria[:valuenow] = value unless indeterminate
-        aria
-      end
-
-      def stimulus_data(value:, min:, max:, indeterminate:)
-        {
-          data: {
-            controller:                     "progress",
-            "progress-variant-value":       "ring",
-            "progress-current-value":       value,
-            "progress-min-value":           min,
-            "progress-max-value":           max,
-            "progress-indeterminate-value": indeterminate
-          }
-        }
-      end
     end
   end
 end

data/lib/stimulus_plumbers/components/timeline/event/slots.rb

@@ -9,7 +9,6 @@ module StimulusPlumbers
 
           def with_indicator(icon: nil)
             set_slot(:indicator, icon, { type: icon ? :icon : :dot, icon: icon })
-            nil
           end
         end
       end

data/lib/stimulus_plumbers/form/builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "action_view/version"
+require "action_view/helpers/tags/translator"
 
 require_relative "../plumber/options/aria"
 require_relative "../plumber/options/html"
@@ -17,6 +18,8 @@ require_relative "fields/inputs/datetime"
 require_relative "fields/inputs/radio"
 require_relative "fields/inputs/file"
 require_relative "fields/inputs/password"
+require_relative "fields/inputs/progress"
+require_relative "fields/inputs/range"
 require_relative "fields/inputs/search"
 require_relative "fields/inputs/select"
 require_relative "fields/inputs/select/grouped"
@@ -31,6 +34,7 @@ module StimulusPlumbers
     class Builder < ActionView::Helpers::FormBuilder
       include Plumber::Options::Html
       include Plumber::Options::Aria
+      include Plumber::Dispatcher::CallableInspector
       include Fields::Inputs::Checkbox
       include Fields::Inputs::Code
       include Fields::Inputs::CreditCard
@@ -38,6 +42,8 @@ module StimulusPlumbers
       include Fields::Inputs::Radio
       include Fields::Inputs::File
       include Fields::Inputs::Password
+      include Fields::Inputs::Progress
+      include Fields::Inputs::Range
       include Fields::Inputs::Search
       include Fields::Inputs::Select
       include Fields::Inputs::Select::Grouped
@@ -47,34 +53,47 @@ module StimulusPlumbers
       include Fields::Inputs::Text
       include Fields::Inputs::TextArea
 
-      def field(attribute, as:, **options)
-        field_opts = options.slice(*Field::OPTIONS)
+      def field(attribute, as:, **options, &block)
+        field_opts = field_options(attribute, options)
         input_opts = options.except(*Field::OPTIONS)
-        render_field(as, attribute, field_opts, input_opts)
+        render_field(as, attribute, field_opts, input_opts, &block)
       end
 
       def collection_field(attribute, as:, collection:, value_method:, text_method:, **options)
-        field_opts = options.slice(*Field::OPTIONS)
+        field_opts = field_options(attribute, options)
         input_opts = options.except(*Field::OPTIONS)
         render_collection_field(as, attribute, field_opts, collection, value_method, text_method, input_opts)
       end
 
       def choice(attribute, as:, collection: nil, value_method: nil, text_method: nil, **options)
-        field_opts = options.slice(*Field::OPTIONS)
+        field_opts = field_options(attribute, options)
         input_opts = options.except(*Field::OPTIONS)
         render_choice_field(as, attribute, field_opts, collection, value_method, text_method, input_opts)
       end
 
       private
 
+      def field_options(attribute, options)
+        options.slice(*Field::OPTIONS).tap { |opts| opts[:label] ||= default_label(attribute) }
+      end
+
+      # Mirrors f.label: helpers.label.* → human_attribute_name → humanize.
+      def default_label(attribute)
+        ActionView::Helpers::Tags::Translator.new(
+          object, @object_name.to_s, attribute.to_s, scope: "helpers.label"
+        ).translate.presence || attribute.to_s.humanize
+      end
+
       def theme
         StimulusPlumbers.config.theme.current
       end
 
-      def render_field(as, attribute, field_opts, input_opts)
+      def render_field(as, attribute, field_opts, input_opts, &block)
         raise ArgumentError, "unknown field type: #{as.inspect}" unless Fields::Renderer::FIELD.key?(as)
 
-        field = Field.new(@template, **field_opts)
+        validate_field_block!(as, block)
+
+        field = Field.new(@template, label_mode: Fields::Renderer.label_mode(as), **field_opts)
         field.render(object, attribute, input_id: field_id(attribute)) do |html_opts, opts, error|
           Plumber::Dispatcher.build(
             Fields::Renderer::FIELD.fetch(as),
@@ -83,11 +102,19 @@ module StimulusPlumbers
             opts,
             error,
             floating: field.floating,
-            **input_opts
+            **input_opts,
+            &block
           ).call(self)
         end
       end
 
+      def validate_field_block!(as, block)
+        return unless block
+        return if accepts_block?(method(Fields::Renderer::FIELD.fetch(as)))
+
+        raise ArgumentError, "field type #{as.inspect} does not accept a block"
+      end
+
       def render_collection_field(as, attribute, field_opts, collection, value_method, text_method, input_opts)
         raise ArgumentError, "unknown collection field type: #{as.inspect}" unless Fields::Renderer::COLLECTION.key?(as)
 

data/lib/stimulus_plumbers/form/field.rb

@@ -13,26 +13,40 @@ module StimulusPlumbers
       COLLECTION_TYPES = %i[radio check_box collection_select grouped_collection_select].freeze
       OPTIONS          = (Base::OPTIONS + %i[hide_label]).freeze
 
-      attr_reader :hide_label
+      # :aria uses aria-labelledby because non-labelable components cannot use `<label for>`.
+      LABEL_MODES = %i[native aria].freeze
+
+      attr_reader :hide_label, :label_mode
 
       class << self
         def label_id(input_id)
           [input_id, "label"].compact.join("_")
         end
+
+        def validate_label_mode!(mode)
+          return mode if LABEL_MODES.include?(mode)
+
+          raise ArgumentError, "unknown label_mode: #{mode.inspect} (expected one of #{LABEL_MODES.join(", ")})"
+        end
       end
 
-      def initialize(template, hide_label: false, **kwargs)
+      def initialize(template, hide_label: false, label_mode: :native, **kwargs)
         super(template, **kwargs)
         @hide_label = hide_label
+        @label_mode = self.class.validate_label_mode!(label_mode)
       end
 
       def label_hidden?
         @hide_label
       end
 
+      def native_label?
+        @label_mode == :native
+      end
+
       def render(object, attribute, input_id:, &block)
         @label ||= attribute.to_s.humanize
-        case @floating
+        case native_label? ? @floating : nil
         when *StimulusPlumbers::Themes::Schema::Form::Floating::Ranges::TYPE
           render_floating_field(object, attribute, input_id, &block)
         else
@@ -42,6 +56,18 @@ module StimulusPlumbers
 
       private
 
+      def build_aria(object, attribute, input_id)
+        return super if native_label?
+
+        { describedby: described_by(object, attribute, input_id), labelledby: self.class.label_id(input_id) }.compact
+      end
+
+      def build_html_options(input_id, aria)
+        return super if native_label?
+
+        { id: input_id, aria: aria }
+      end
+
       def render_default_field(object, attribute, input_id, &block)
         error_override = error?(object, attribute)
         aria           = build_aria(object, attribute, input_id)
@@ -59,13 +85,15 @@ module StimulusPlumbers
         end
       end
 
+      # hide_label is visual only; :aria fields cannot be required.
       def field_label(input_id)
         Fields::Label.new(@template).render(
           text:     @label,
-          for_id:   input_id,
+          for_id:   (input_id if native_label?),
           id:       self.class.label_id(input_id),
-          required: @required,
-          hidden:   @hide_label
+          required: native_label? && @required,
+          hidden:   @hide_label,
+          tag:      native_label? ? :label : :span
         )
       end