stimulus_plumbers 0.4.14 → 0.4.16

data/lib/stimulus_plumbers/form/fields/inputs/password/revealable.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Form
+    module Fields
+      module Inputs
+        module Password
+          # Reveal toggle: input group wrapper, toggle button, and its icon pair.
+          module Revealable
+            STIMULUS_CONTROLLER = "input-revealable"
+            STIMULUS_ACTION     = "click->#{STIMULUS_CONTROLLER}#toggle".freeze
+
+            private
+
+            def render_revealable_password(error, floating: nil, &block)
+              render_input_group(
+                error:    error,
+                floating: floating,
+                trailing: method(:reveal_button),
+                **merge_html_options(
+                  theme.resolve(:form_field_input_reveal, error: error),
+                  data: reveal_data
+                )
+              ) { @template.capture(&block) }
+            end
+
+            def reveal_button
+              build_reveal_button do
+                @template.safe_join(
+                  [password_icon("reveal", "revealIcon"), password_icon("conceal", "concealIcon", hidden: true)]
+                )
+              end
+            end
+
+            def reveal_data
+              {
+                controller:                           STIMULUS_CONTROLLER,
+                input_revealable_reveal_label_value:  I18n.t("stimulus_plumbers.form.password.show", default: "Show password"),
+                input_revealable_conceal_label_value: I18n.t("stimulus_plumbers.form.password.hide", default: "Hide password")
+              }
+            end
+
+            def password_icon(name, target, hidden: false)
+              Components::Icon.new(@template).render(
+                name,
+                size:   :sm,
+                aria:   { hidden: "true" },
+                data:   { input_revealable_target: target },
+                hidden: hidden,
+                **theme.resolve(:button_icon)
+              )
+            end
+
+            def build_reveal_button(&block)
+              @template.content_tag(
+                :button,
+                **merge_html_options(
+                  theme.resolve(:form_field_input_button_reveal),
+                  {
+                    type: "button",
+                    aria: { label: I18n.t("stimulus_plumbers.form.password.show", default: "Show password") },
+                    data: { input_revealable_target: "toggle", action: STIMULUS_ACTION }
+                  }
+                )
+              ) { @template.capture(&block) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/form/fields/inputs/password/strength.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Form
+    module Fields
+      module Inputs
+        module Password
+          module Strength
+            private
+
+            def apply_strength_wiring(html_options, input_id)
+              described = [html_options.dig(:aria, :describedby), Components::PasswordStrength.rules_id_for(input_id)]
+                          .compact.join(" ")
+              merge_html_options(
+                html_options,
+                aria: { describedby: described },
+                data: {
+                  password_strength_target: "input", action: "input->password-strength#score"
+                }
+              )
+            end
+
+            def wrap_with_strength(input, input_id)
+              Components::PasswordStrength.new(@template).render(input: input, input_id: input_id, config: @password_requirements)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/form/fields/inputs/password.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "password/revealable"
+require_relative "password/strength"
+
 module StimulusPlumbers
   module Form
     module Fields
       module Inputs
         module Password
-          STIMULUS_CONTROLLER = "input-revealable"
-          STIMULUS_ACTION     = "click->#{STIMULUS_CONTROLLER}#toggle".freeze
+          include Revealable
+          include Strength
+
           DEFAULT_AUTOCOMPLETE = "current-password"
 
           def password_field(attribute, floating: nil, revealable: false, **options)
@@ -24,78 +28,43 @@ module StimulusPlumbers
             end
           end
 
-          private
+          # Requirements collected from a `field` block, held for the renderer.
+          attr_reader :password_requirements
 
-          def render_password_input(attribute, html_opts, opts, error, floating: nil, revealable: false, **kwargs)
-            html_options = merge_html_options(
-              theme.resolve(:form_field_input, floating: floating, error: error),
-              opts,
-              html_opts,
-              kwargs,
-              { autocomplete: kwargs.delete(:autocomplete) || DEFAULT_AUTOCOMPLETE }
-            )
-            if revealable
-              render_revealable_password(error, floating: floating) do
-                revealable_html_options = merge_html_options(html_options, { data: { input_revealable_target: "input" } })
-                @template.password_field(@object_name, attribute, objectify_options(revealable_html_options))
-              end
-            else
-              @template.password_field(@object_name, attribute, objectify_options(html_options))
-            end
-          end
+          private
 
-          def render_revealable_password(error, floating: nil, &block)
-            render_input_group(
-              error:    error,
-              floating: floating,
-              trailing: method(:reveal_button),
-              **merge_html_options(
-                theme.resolve(:form_field_input_reveal, error: error),
-                data: reveal_data
-              )
-            ) { @template.capture(&block) }
-          end
+          def render_password_input(attribute, html_opts, opts, error, floating: nil, revealable: false, **kwargs, &block)
+            # A shared `requirements:` object (spec Section C) takes precedence over a field block.
+            @password_requirements = kwargs.delete(:requirements) || build_password_requirements(&block)
+            input_id = html_opts[:id]
+            html_options = password_html_options(html_opts, opts, error, floating, kwargs)
+            html_options = apply_strength_wiring(html_options, input_id) if @password_requirements.active?
+            input = if revealable
+                      render_revealable_password(error, floating: floating) do
+                        revealable_html_options = merge_html_options(html_options, { data: { input_revealable_target: "input" } })
+                        @template.password_field(@object_name, attribute, objectify_options(revealable_html_options))
+                      end
+                    else
+                      @template.password_field(@object_name, attribute, objectify_options(html_options))
+                    end
+            return input unless @password_requirements.active?
 
-          def reveal_button
-            build_reveal_button do
-              @template.safe_join(
-                [password_icon("reveal", "revealIcon"), password_icon("conceal", "concealIcon", hidden: true)]
-              )
-            end
+            wrap_with_strength(input, input_id)
           end
 
-          def reveal_data
-            {
-              controller:                           STIMULUS_CONTROLLER,
-              input_revealable_reveal_label_value:  I18n.t("stimulus_plumbers.form.password.show", default: "Show password"),
-              input_revealable_conceal_label_value: I18n.t("stimulus_plumbers.form.password.hide", default: "Hide password")
-            }
+          def build_password_requirements(&block)
+            StimulusPlumbers::Password::Requirements.build(&block)
           end
 
-          def password_icon(name, target, hidden: false)
-            Components::Icon.new(@template).render(
-              name,
-              size:   :sm,
-              aria:   { hidden: "true" },
-              data:   { input_revealable_target: target },
-              hidden: hidden,
-              **theme.resolve(:button_icon)
+          def password_html_options(html_opts, opts, error, floating, kwargs)
+            merge_html_options(
+              theme.resolve(:form_field_input, floating: floating, error: error),
+              opts,
+              html_opts,
+              kwargs,
+              { autocomplete: kwargs.delete(:autocomplete) || DEFAULT_AUTOCOMPLETE }
             )
           end
-
-          def build_reveal_button(&block)
-            @template.content_tag(
-              :button,
-              **merge_html_options(
-                theme.resolve(:form_field_input_button_reveal),
-                {
-                  type: "button",
-                  aria: { label: I18n.t("stimulus_plumbers.form.password.show", default: "Show password") },
-                  data: { input_revealable_target: "toggle", action: STIMULUS_ACTION }
-                }
-              )
-            ) { @template.capture(&block) }
-          end
         end
       end
     end

data/lib/stimulus_plumbers/form/fields/inputs/progress.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Form
+    module Fields
+      module Inputs
+        module Progress
+          private
+
+          # A progressbar submits nothing and is never invalid — it reads its value from the model
+          # attribute, and `floating:` is dropped so it can't leak onto the element as an attribute.
+          def render_progress(attribute, html_opts, opts, _error, segments: nil, format: nil, readout: :inside, **kwargs)
+            html_options = merge_html_options(
+              theme.resolve(:form_field_input_progress), opts, html_opts, kwargs.except(:floating)
+            )
+            value     = object.public_send(attribute)
+            component = Components::ProgressBar.new(@template)
+            if segments
+              raise ArgumentError, "format: is not supported with segments:" unless format.nil?
+
+              component.render_segmented(value: value, segments: segments, **html_options)
+            else
+              component.render(value: value, format: format, readout: readout, **html_options)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/form/fields/inputs/range.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Form
+    module Fields
+      module Inputs
+        # A range is a track and a thumb, not a text box, so it takes none of the text input's
+        # chrome. With `format:` it grows a readout driven by the progress controller.
+        module Range
+          include Components::Progress::Shared
+
+          def range_field(attribute, **options)
+            super(attribute, merge_html_options(theme.resolve(:form_field_input_range), options.except(:floating)))
+          end
+
+          private
+
+          # `floating:` is dropped — a label can't sit inside a slider.
+          def render_range_input(attribute, html_opts, opts, _error, format: nil, min: 0, max: 100, **kwargs)
+            validate_format!(format)
+            current = clamp(numeric(object.public_send(attribute)), min, max)
+            input   = range_input(attribute, current, min, max, format, html_opts, opts, kwargs.except(:floating))
+            return input if format.nil?
+
+            range_group(input, current, min, max, format)
+          end
+
+          # No readout to contain, so the input hosts the controller itself.
+          def range_input(attribute, current, min, max, format, html_opts, opts, kwargs)
+            wired = format.nil? ? range_stimulus_data(current, min, max, format) : { data: { "progress-target": "input" } }
+            html_options = merge_html_options(
+              theme.resolve(:form_field_input_range),
+              opts,
+              html_opts,
+              kwargs,
+              wired,
+              # The input carries the track gradient, so the fill percentage lands here, not on
+              # the wrapper. Server-rendered so the fill is right before the controller connects.
+              { min: min, max: max, style: "--sp-progress-percent: #{integral(percent(current, min, max).round(2))}" }
+            )
+            @template.range_field(@object_name, attribute, objectify_options(html_options))
+          end
+
+          # A Stimulus target must be a descendant of its controller element, so a readout
+          # forces a wrapper local to the input row.
+          def range_group(input, current, min, max, format)
+            html_options = merge_html_options(
+              theme.resolve(:form_field_input_range_group),
+              range_stimulus_data(current, min, max, format)
+            )
+            body = @template.safe_join([input, range_value(format, current, min, max)])
+            @template.content_tag(:div, body, **html_options)
+          end
+
+          # aria-hidden: the native input already announces its own value.
+          def range_value(format, current, min, max)
+            @template.content_tag(
+              :span,
+              value_text(format, current, min, max),
+              **merge_html_options(
+                theme.resolve(:form_field_input_range_value),
+                { data: { "progress-target": "value" }, aria: { hidden: true } }
+              )
+            )
+          end
+
+          def range_stimulus_data(current, min, max, format)
+            progress_stimulus_data(
+              value:   current,
+              min:     min,
+              max:     max,
+              variant: "range",
+              action:  "input->progress#refresh",
+              **(format.nil? ? {} : { "progress-format-value": format })
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/form/fields/inputs/text.rb

@@ -5,6 +5,7 @@ module StimulusPlumbers
     module Fields
       module Inputs
         module Text
+          # `range` is not here — see inputs/range.rb; it shares none of the text input chrome.
           TEXT_FIELD_METHODS = {
             text:           :text_field,
             email:          :email_field,
@@ -14,7 +15,6 @@ module StimulusPlumbers
             color:          :color_field,
             month:          :month_field,
             week:           :week_field,
-            range:          :range_field,
             datetime_local: :datetime_local_field
           }.freeze
 

data/lib/stimulus_plumbers/form/fields/renderer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../field"
+
 module StimulusPlumbers
   module Form
     module Fields
@@ -18,6 +20,7 @@ module StimulusPlumbers
           text_area:      :render_text_area_input,
           file:           :render_file_input,
           password:       :render_password_input,
+          progress:       :render_progress,
           code:           :render_code_input,
           credit_card:    :render_credit_card_input,
           date:           :render_combobox_date,
@@ -26,6 +29,44 @@ module StimulusPlumbers
           search:         :render_combobox_typeahead
         }.freeze
 
+        # Require every field type to declare its caption association.
+        LABEL_MODE = {
+          text:           :native,
+          email:          :native,
+          number:         :native,
+          url:            :native,
+          tel:            :native,
+          color:          :native,
+          month:          :native,
+          week:           :native,
+          range:          :native,
+          datetime_local: :native,
+          text_area:      :native,
+          file:           :native,
+          password:       :native,
+          progress:       :aria,
+          code:           :native,
+          credit_card:    :native,
+          date:           :native,
+          time:           :native,
+          select:         :native,
+          search:         :native
+        }.freeze
+
+        missing = FIELD.keys - LABEL_MODE.keys
+        raise ArgumentError, "field types missing a label_mode: #{missing.join(", ")}" if missing.any?
+
+        extra = LABEL_MODE.keys - FIELD.keys
+        raise ArgumentError, "label_mode declared for unknown field types: #{extra.join(", ")}" if extra.any?
+
+        LABEL_MODE.each_value { |mode| Field.validate_label_mode!(mode) }
+
+        class << self
+          def label_mode(as)
+            LABEL_MODE.fetch(as)
+          end
+        end
+
         COLLECTION = {
           collection_select:         :render_collection_combobox_dropdown,
           grouped_collection_select: :render_grouped_collection_combobox_dropdown

data/lib/stimulus_plumbers/helpers/progress_helper.rb

@@ -3,12 +3,22 @@
 module StimulusPlumbers
   module Helpers
     module ProgressHelper
-      def sp_progress_bar(value:, min: 0, max: 100, indeterminate: false, **kwargs)
-        Components::ProgressBar.new(self).render(value: value, min: min, max: max, indeterminate: indeterminate, **kwargs)
+      def sp_progress_bar(value:, min: 0, max: 100, indeterminate: false, format: nil, readout: :inside, **kwargs)
+        Components::ProgressBar.new(self).render(
+          value: value, min: min, max: max, indeterminate: indeterminate, format: format, readout: readout, **kwargs
+        )
       end
 
-      def sp_progress_ring(value:, min: 0, max: 100, indeterminate: false, **kwargs)
-        Components::ProgressRing.new(self).render(value: value, min: min, max: max, indeterminate: indeterminate, **kwargs)
+      def sp_progress_segmented(value:, segments:, min: 0, max: 100, mode: :discrete, indeterminate: false, ramp: nil, **kwargs)
+        Components::ProgressBar.new(self).render_segmented(
+          value: value, segments: segments, min: min, max: max, mode: mode, indeterminate: indeterminate, ramp: ramp, **kwargs
+        )
+      end
+
+      def sp_progress_ring(value:, min: 0, max: 100, indeterminate: false, size: nil, **kwargs)
+        Components::ProgressRing.new(self).render(
+          value: value, min: min, max: max, indeterminate: indeterminate, size: size, **kwargs
+        )
       end
 
       def sp_progress_meter(value:, min: 0, max: 100, low: nil, high: nil, optimum: nil, **kwargs)

data/lib/stimulus_plumbers/password/requirements.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Password
+    # Declarative password rule set: DSL + evaluation + serialization. Consumed by
+    # the form renderer, PasswordStrengthValidator, and the JS controller (via to_stimulus).
+    class Requirements
+      LEVEL_KEYS = %i[weak fine strong].freeze
+      BUILTIN_KEYS = %i[length uppercase lowercase digit symbol].freeze
+      DEFAULT_THRESHOLDS = { low: 34, high: 100, optimum: 100 }.freeze
+
+      BUILTIN_PATTERNS = {
+        uppercase: "[A-Z]",
+        lowercase: "[a-z]",
+        digit:     "\\d",
+        symbol:    "[^A-Za-z0-9]"
+      }.freeze
+
+      class << self
+        def build
+          new.tap { |req| yield req if block_given? }
+        end
+      end
+
+      def initialize
+        @enforced_options = nil
+        @custom = {}
+        @overrides = {}
+      end
+
+      def enforce(**options)
+        @enforced_options = options
+        nil
+      end
+
+      def rule(key, label = nil, pattern: nil, min: nil, max: nil, negate: false)
+        key = key.to_sym
+        if pattern
+          if negate
+            min = 0
+            max = 0
+          end
+          @custom[key] = { pattern: source_of(pattern), min: min.nil? ? 1 : min, max: max, label: label }
+        else
+          raise ArgumentError, unknown_rule_message(key) unless BUILTIN_KEYS.include?(key)
+
+          @overrides[key] = label
+        end
+        nil
+      end
+
+      def enforced?
+        !@enforced_options.nil?
+      end
+
+      # Any rule present — built-ins (only when enforced?) or a custom rule. Drives whether
+      # the form renders the strength UI; enforced? alone misses custom-only rule sets.
+      def active?
+        descriptors.any?
+      end
+
+      def rules
+        descriptors.to_h { |descriptor| [descriptor[:key], descriptor[:label]] }
+      end
+
+      def thresholds
+        DEFAULT_THRESHOLDS.merge((@enforced_options || {}).slice(*DEFAULT_THRESHOLDS.keys))
+      end
+
+      def evaluate(password)
+        password = password.to_s
+        results = descriptors.to_h { |descriptor| [descriptor[:key], satisfies?(descriptor, password)] }
+        satisfied = results.values.count(true)
+        { rules: results, value: score(satisfied, results.size), level: level_for(satisfied, results.size) }
+      end
+
+      def valid?(password)
+        result = evaluate(password)
+        result[:rules].any? && result[:rules].values.all?
+      end
+
+      def to_stimulus
+        { rules: descriptors.map { |descriptor| serialize(descriptor) }, options: stimulus_options, labels: level_labels }
+      end
+
+      private
+
+      def descriptors
+        list = enforced? ? BUILTIN_KEYS.filter_map { |key| builtin_descriptor(key) } : []
+        @custom.each do |key, spec|
+          list << { key: key, pattern: spec[:pattern], min: spec[:min], max: spec[:max], label: spec[:label] }
+        end
+        apply_overrides(list)
+      end
+
+      def builtin_descriptor(key)
+        options = @enforced_options
+        return length_descriptor(options) if key == :length && (options.key?(:min_length) || options.key?(:max_length))
+
+        bounds = parse_count(options[key])
+        return unless bounds
+
+        label = builtin_label(key, bounds[:min])
+        { key: key, pattern: BUILTIN_PATTERNS[key], min: bounds[:min], max: bounds[:max], label: label }
+      end
+
+      def length_descriptor(options)
+        unless options.key?(:min_length) && options.key?(:max_length)
+          raise ArgumentError, "length rule requires both min_length and max_length"
+        end
+
+        label = builtin_label(:length, options[:min_length])
+        { key: :length, min: options[:min_length], max: options[:max_length], label: label }
+      end
+
+      def parse_count(value)
+        case value
+        when nil, false then nil
+        when true then { min: 1, max: nil }
+        when Integer then { min: value, max: nil }
+        when Range then { min: value.begin, max: value.end }
+        else raise ArgumentError, "invalid occurrence count #{value.inspect}"
+        end
+      end
+
+      def satisfies?(descriptor, password)
+        n = descriptor[:pattern] ? password.scan(Regexp.new(descriptor[:pattern])).size : password.length
+        min = descriptor[:min] || 0
+        max = descriptor[:max] || Float::INFINITY
+        n.between?(min, max)
+      end
+
+      def score(satisfied, total)
+        total.zero? ? 0 : (satisfied.to_f / total * 100).round
+      end
+
+      def level_for(satisfied, total)
+        return "strong" if total.positive? && satisfied == total
+
+        score(satisfied, total) < thresholds[:low] ? "weak" : "fine"
+      end
+
+      def serialize(descriptor)
+        data = { key: descriptor[:key].to_s, label: descriptor[:label], min: descriptor[:min] }
+        data[:max] = descriptor[:max] unless descriptor[:max].nil?
+        data[:pattern] = descriptor[:pattern] if descriptor[:pattern]
+        data
+      end
+
+      def stimulus_options
+        { "low" => thresholds[:low] }
+      end
+
+      def level_labels
+        LEVEL_KEYS.index_with { |key| I18n.t("stimulus_plumbers.password.levels.#{key}") }.transform_keys(&:to_s)
+      end
+
+      def apply_overrides(list)
+        return list if @overrides.empty?
+
+        list.map do |descriptor|
+          next descriptor unless @overrides.key?(descriptor[:key])
+
+          descriptor.merge(label: @overrides[descriptor[:key]])
+        end
+      end
+
+      def builtin_label(key, count)
+        I18n.t("stimulus_plumbers.password.rules.#{key}", count: count)
+      end
+
+      def source_of(pattern)
+        pattern.is_a?(Regexp) ? pattern.source : pattern.to_s
+      end
+
+      def unknown_rule_message(key)
+        known = BUILTIN_KEYS.map(&:inspect).join(", ")
+        "unknown rule key: #{key.inspect} (known keys: #{known}), or pass pattern: for a custom rule"
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/password_strength_validator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "password/requirements"
+
+# Top-level so `validates :attr, password_strength: {...}` resolves via Rails' symbol lookup.
+class PasswordStrengthValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    requirements = options[:with] || build_requirements
+    result = requirements.evaluate(value.to_s)
+    return if result[:rules].any? && result[:rules].values.all?
+
+    unmet_messages(requirements, result).each { |message| record.errors.add(attribute, message) }
+  end
+
+  private
+
+  def build_requirements
+    StimulusPlumbers::Password::Requirements.build do |req|
+      req.enforce(**options.except(:with, :message, :on, :if, :unless, :allow_nil, :allow_blank))
+    end
+  end
+
+  def unmet_messages(requirements, result)
+    return [options[:message]] if options[:message]
+
+    labels = requirements.rules
+    result[:rules].reject { |_key, ok| ok }.keys.map { |key| labels[key] }
+  end
+end