stimulus_plumbers 0.4.9 → 0.4.10

data/docs/component/form.md

@@ -61,11 +61,11 @@ Special options on native helpers:
 
 Three methods render a complete, accessible field:
 
-| Method                                                                            | `as:` values                                                                                                                                                       |
-| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `f.field(attr, as:, **opts)`                                                      | `:text` `:email` `:number` `:url` `:tel` `:color` `:month` `:week` `:range` `:datetime_local` `:text_area` `:file` `:password` `:date` `:time` `:select` `:search` |
-| `f.collection_field(attr, as:, collection:, value_method:, text_method:, **opts)` | `:collection_select` `:grouped_collection_select`                                                                                                                  |
-| `f.choice(attr, as:, **opts)`                                                     | `:radio` `:check_box`                                                                                                                                              |
+| Method                                                                            | `as:` values                                                                                                                                                                              |
+| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `f.field(attr, as:, **opts)`                                                      | `:text` `:email` `:number` `:url` `:tel` `:color` `:month` `:week` `:range` `:datetime_local` `:text_area` `:file` `:password` `:date` `:time` `:select` `:search` `:code` `:credit_card` |
+| `f.collection_field(attr, as:, collection:, value_method:, text_method:, **opts)` | `:collection_select` `:grouped_collection_select`                                                                                                                                         |
+| `f.choice(attr, as:, **opts)`                                                     | `:radio` `:check_box`                                                                                                                                                                     |
 
 ### Shared field options
 
@@ -89,6 +89,8 @@ Three methods render a complete, accessible field:
 <%= f.field :bio,      as: :text_area, hint: "Tell us about yourself." %>
 <%= f.field :avatar,   as: :file %>
 <%= f.field :password, as: :password, revealable: true %>
+<%= f.field :verification_code, as: :code, length: 6 %>
+<%= f.field :card_number, as: :credit_card %>
 <%= f.field :email,    as: :email,    floating: :filled %>
 <%= f.field :country,  as: :select,
       choices: [["Australia", "au"], ["Canada", "ca"], ["United States", "us"]],
@@ -147,6 +149,26 @@ Use `f.search_field` for a native `<input type="search">`.
 
 Use `f.password_field` for a plain `<input type="password">` (also accepts `revealable:`).
 
+**Code** (`as: :code`) — character-cell entry backed by `input-formatter` and the `character-cells` plumber. The native input remains the accessible control; cells are decorative.
+
+| Option         | Values                                   | Default                | Description                                 |
+| -------------- | ---------------------------------------- | ---------------------- | ------------------------------------------- |
+| `length`       | positive Integer                         | required               | Number of cells and input maximum length    |
+| `charset`      | `:digits` / `:letters` / `:alphanumeric` | `:digits`              | Allowed code characters                     |
+| `groups`       | Array of positive Integers               | `[]`                   | Visual cell groups; must add up to `length` |
+| `autocomplete` | String                                   | `"one-time-code"`      | Native autocomplete value                   |
+| `inputmode`    | String                                   | `"numeric"` for digits | Native input mode                           |
+
+**Credit card** (`as: :credit_card`) — grouped card-number entry backed by `input-formatter` and the `character-cells` plumber (grouped mode). Renders one cell per group with a literal dash separator between cells; their sum sets `maxlength`.
+
+| Option         | Values                     | Default        | Description                                                                  |
+| -------------- | -------------------------- | -------------- | ---------------------------------------------------------------------------- |
+| `groups`       | Array of positive Integers | `[4, 4, 4, 4]` | Cell groups — one cell per group, dash-separated; their sum sets `maxlength` |
+| `autocomplete` | String                     | `"cc-number"`  | Native autocomplete value                                                    |
+| `inputmode`    | String                     | `"numeric"`    | Native input mode                                                            |
+
+Character-cell fields do not support `floating:` labels.
+
 ---
 
 ## f.collection_field

data/docs/guide.md

@@ -37,3 +37,12 @@ generator) inject their CSS directives into the first entry file found, in order
 4. `app/javascript/entrypoints/application.css` (`jsbundling-rails` esbuild/webpack default)
 
 Override with `STIMULUS_PLUMBERS_CSS_ENTRY=/path/to/entry.css` — used by both gems' generators.
+
+## Installed CSS files
+
+The core installer copies its token defaults to
+`app/assets/stylesheets/stimulus_plumbers/tokens.css` and imports that app-local file.
+
+This file is application-owned: later generator runs create a missing file but never overwrite an
+existing one. They also replace legacy imports that pointed into an installed gem with the new
+relative app-local import.

data/lib/generators/stimulus_plumbers/install/install_generator.rb

@@ -9,13 +9,19 @@ module StimulusPlumbers
     class InstallGenerator < Rails::Generators::Base
       include StimulusPlumbers::Generators::CssEntrypoint
 
+      TOKENS_CSS_SOURCE = File.join(
+        File.expand_path("../../../..", __dir__),
+        TokensDirective::TOKENS_CSS_PATH
+      )
+
       def install
         css_file = entry_css_file(**css_file_lookup_options)
         return warn_entry_css_not_found(label: "CSS", **css_file_lookup_options) unless css_file
+        return unless copy_asset(TOKENS_CSS_SOURCE, TokensDirective::TOKENS_CSS_PATH)
 
         apply_edit(
           css_file,
-          TokensDirective.directive(from: File.dirname(css_file)),
+          TokensDirective.directive(from: File.dirname(css_file), destination_root: destination_root),
           stale_pattern: TokensDirective.stale_pattern
         )
       end

data/lib/stimulus_plumbers/engine.rb

@@ -9,10 +9,6 @@ module StimulusPlumbers
     config.autoload_paths << File.expand_path("../stimulus-plumbers", __dir__)
     config.i18n.load_path += Dir[File.expand_path("../../config/locales/*.{rb,yml}", __dir__)]
 
-    initializer "stimulus_plumbers.assets", after: :set_default_precompile do |app|
-      app.config.assets.precompile += %w[stimulus_plumbers/tokens.css] if app.config.respond_to?(:assets)
-    end
-
     initializer "stimulus_plumbers.helpers" do
       ActiveSupport.on_load(:action_view) do
         include StimulusPlumbers::Helpers

data/lib/stimulus_plumbers/form/builder.rb

@@ -11,6 +11,8 @@ require_relative "fields/renderer"
 require_relative "fields/fieldset"
 require_relative "fields/inputs/checkbox"
 require_relative "fields/inputs/combobox"
+require_relative "fields/inputs/code"
+require_relative "fields/inputs/credit_card"
 require_relative "fields/inputs/datetime"
 require_relative "fields/inputs/radio"
 require_relative "fields/inputs/file"
@@ -30,6 +32,8 @@ module StimulusPlumbers
       include Plumber::Options::Html
       include Plumber::Options::Aria
       include Fields::Inputs::Checkbox
+      include Fields::Inputs::Code
+      include Fields::Inputs::CreditCard
       include Fields::Inputs::Datetime
       include Fields::Inputs::Radio
       include Fields::Inputs::File

data/lib/stimulus_plumbers/form/field.rb

@@ -8,7 +8,7 @@ module StimulusPlumbers
     class Field < Base
       TYPES = %i[
         text email number url tel color month week range datetime_local
-        text_area file password date time select search
+        text_area file password date time select search code credit_card
       ].freeze
       COLLECTION_TYPES = %i[radio check_box collection_select grouped_collection_select].freeze
       OPTIONS          = (Base::OPTIONS + %i[hide_label]).freeze

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Form
+    module Fields
+      module Inputs
+        module Code
+          private
+
+          def render_code_input(attribute, html_opts, opts, error, length:, charset: :digits, groups: [], **kwargs)
+            floating = kwargs.delete(:floating)
+            raise ArgumentError, "floating labels are not supported for code fields" if floating.present?
+
+            validate_code_options!(length, groups)
+            inputmode = kwargs.delete(:inputmode) || (charset.to_sym == :digits ? "numeric" : nil)
+            autocomplete = kwargs.delete(:autocomplete) || "one-time-code"
+            config = { error: error, length: length, charset: charset, groups: groups,
+                       autocomplete: autocomplete, inputmode: inputmode, kwargs: kwargs
+}
+            render_code_field(attribute, html_opts, opts, config)
+          end
+
+          def render_code_field(attribute, html_opts, opts, config)
+            @template.content_tag(:div, **code_wrapper_options(config)) do
+              @template.safe_join(
+                [render_code_cells(config), code_input(attribute, html_opts, opts, config)]
+              )
+            end
+          end
+
+          def code_wrapper_options(config)
+            merge_html_options(
+              theme.resolve(:form_field_input_code, error: config[:error]),
+              { data: {
+                controller:                    "input-formatter",
+                input_formatter_format_value:  "code",
+                input_formatter_options_value: { charset: config[:charset].to_s, length: config[:length] }.to_json,
+                input_formatter_groups_value:  config[:groups].presence
+              }
+}
+            )
+          end
+
+          def code_input(attribute, html_opts, opts, config)
+            input_options = merge_html_options(
+              theme.resolve(:form_field_input_code_overlay, error: config[:error]),
+              opts,
+              html_opts,
+              config[:kwargs],
+              { maxlength: config[:length], autocomplete: config[:autocomplete], inputmode: config[:inputmode],
+                data: { input_formatter_target: "input", action: formatter_actions }
+}
+            )
+            @template.text_field(@object_name, attribute, objectify_options(input_options))
+          end
+
+          def render_code_cells(config)
+            count = config[:groups].present? ? config[:groups].sum : config[:length]
+            cell_options = merge_html_options(
+              theme.resolve(:form_field_input_code_cell, error: config[:error]),
+              { data: { input_formatter_target: "cell" } }
+            )
+            @template.content_tag(:div, **merge_html_options(theme.resolve(:form_field_input_code_cells))) do
+              @template.safe_join(Array.new(count) { @template.content_tag(:span, nil, **cell_options) })
+            end
+          end
+
+          def validate_code_options!(length, groups)
+            raise ArgumentError, "length must be a positive integer" unless positive_integer?(length)
+            return if groups.blank?
+
+            raise ArgumentError, "groups must be an array of positive integers" unless valid_groups?(groups)
+            raise ArgumentError, "groups must add up to length" unless groups.sum == length
+          end
+
+          def valid_groups?(groups) = groups.is_a?(Array) && groups.all? { |group| positive_integer?(group) }
+          def positive_integer?(value) = value.is_a?(Integer) && value.positive?
+
+          def formatter_actions
+            "input->input-formatter#onInput focus->input-formatter#onFocus blur->input-formatter#onBlur"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Form
+    module Fields
+      module Inputs
+        module CreditCard
+          DEFAULT_GROUPS = [4, 4, 4, 4].freeze
+
+          private
+
+          def render_credit_card_input(attribute, html_opts, opts, error, groups: DEFAULT_GROUPS, floating: nil, **kwargs)
+            raise ArgumentError, "floating labels are not supported for credit card fields" if floating.present?
+
+            normalized_groups = groups.presence || DEFAULT_GROUPS
+            inputmode = kwargs.delete(:inputmode) || "numeric"
+            autocomplete = kwargs.delete(:autocomplete) || "cc-number"
+            validate_credit_card_groups!(normalized_groups)
+            length = normalized_groups.sum
+            config = { error: error, groups: normalized_groups, length: length,
+                       autocomplete: autocomplete, inputmode: inputmode, kwargs: kwargs
+}
+            render_credit_card_field(attribute, html_opts, opts, config)
+          end
+
+          def render_credit_card_field(attribute, html_opts, opts, config)
+            @template.content_tag(:div, **credit_card_wrapper_options(config)) do
+              @template.safe_join(
+                [render_credit_card_cells(config), credit_card_input(attribute, html_opts, opts, config)]
+              )
+            end
+          end
+
+          def credit_card_wrapper_options(config)
+            merge_html_options(
+              theme.resolve(:form_field_input_credit_card, error: config[:error]),
+              { data: {
+                controller:                   "input-formatter",
+                input_formatter_format_value: "creditCard",
+                input_formatter_groups_value: config[:groups]
+              }
+}
+            )
+          end
+
+          def credit_card_input(attribute, html_opts, opts, config)
+            input_options = merge_html_options(
+              theme.resolve(:form_field_input_credit_card_overlay, error: config[:error]),
+              opts,
+              html_opts,
+              config[:kwargs],
+              { maxlength: config[:length], autocomplete: config[:autocomplete], inputmode: config[:inputmode],
+                data: { input_formatter_target: "input", action: formatter_actions }
+}
+            )
+            @template.text_field(@object_name, attribute, objectify_options(input_options))
+          end
+
+          def render_credit_card_cells(config)
+            cells = config[:groups].each_index.flat_map do |index|
+              index.zero? ? [render_credit_card_cell(config)] : [render_credit_card_separator, render_credit_card_cell(config)]
+            end
+
+            @template.content_tag(:div, **merge_html_options(theme.resolve(:form_field_input_credit_card_cells))) do
+              @template.safe_join(cells)
+            end
+          end
+
+          def render_credit_card_cell(config)
+            cell_options = merge_html_options(
+              theme.resolve(:form_field_input_credit_card_cell, error: config[:error]),
+              { data: { input_formatter_target: "cell" } }
+            )
+            @template.content_tag(:span, nil, **cell_options)
+          end
+
+          def render_credit_card_separator
+            separator_options = merge_html_options(
+              theme.resolve(:form_field_input_credit_card_separator),
+              { aria: { hidden: true } }
+            )
+            @template.content_tag(:span, "-", **separator_options)
+          end
+
+          def validate_credit_card_groups!(groups)
+            return if groups.is_a?(Array) && groups.all? { |group| group.is_a?(Integer) && group.positive? }
+
+            raise ArgumentError, "groups must be an array of positive integers"
+          end
+
+          def formatter_actions
+            "input->input-formatter#onInput focus->input-formatter#onFocus blur->input-formatter#onBlur"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -18,6 +18,8 @@ module StimulusPlumbers
           text_area:      :render_text_area_input,
           file:           :render_file_input,
           password:       :render_password_input,
+          code:           :render_code_input,
+          credit_card:    :render_credit_card_input,
           date:           :render_combobox_date,
           time:           :render_combobox_time,
           select:         :render_combobox_dropdown,

data/lib/stimulus_plumbers/generators/css_entrypoint.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 module StimulusPlumbers
   module Generators
     module CssEntrypoint
@@ -48,6 +50,26 @@ module StimulusPlumbers
         say "Could not update #{relative_to_destination(css_file)}: #{e.message}. Skipping.", :yellow
       end
 
+      # CSS copied by an installer belongs to the application from this point on.
+      # Keep an existing file intact so a generator rerun never overwrites local
+      # customizations (the same policy used by tailwindcss-rails' installer).
+      def copy_asset(source, destination)
+        path = File.join(destination_root, destination)
+
+        if File.exist?(path)
+          say_status :identical, destination
+          return true
+        end
+
+        FileUtils.mkdir_p(File.dirname(path))
+        FileUtils.cp(source, path)
+        say_status :create, destination, :green
+        true
+      rescue Errno::EROFS, Errno::EACCES => e
+        say "Could not copy #{destination}: #{e.message}. Skipping.", :yellow
+        false
+      end
+
       # `stale_pattern:` is required — every call site needs stale-import detection,
       # so making it optional would leave an untested "anchor without stale" state.
       def content_edit(content, directive, stale_pattern:, anchor_pattern: nil)

data/lib/stimulus_plumbers/generators/tokens_directive.rb

@@ -5,19 +5,19 @@ require "pathname"
 module StimulusPlumbers
   module Generators
     module TokensDirective
-      GEM_ROOT            = File.expand_path("../../..", __dir__)
-      TOKENS_CSS_REL_PATH = "app/assets/stylesheets/stimulus_plumbers/tokens.css"
+      TOKENS_CSS_PATH = "app/assets/stylesheets/stimulus_plumbers/tokens.css"
 
       module_function
 
-      def directive(from:)
-        path = Pathname.new(GEM_ROOT).join(TOKENS_CSS_REL_PATH)
+      def directive(from:, destination_root:)
+        path = Pathname.new(destination_root).join(TOKENS_CSS_PATH)
         rel  = path.relative_path_from(Pathname.new(from))
+        rel  = "./#{rel}" unless rel.to_s.start_with?(".", "/")
         %(@import "#{rel}";)
       end
 
       def stale_pattern
-        %r{@import "[^"]*#{Regexp.escape(TOKENS_CSS_REL_PATH)}";}
+        %r{@import "[^"]*#{Regexp.escape(TOKENS_CSS_PATH)}";}
       end
     end
   end

data/lib/stimulus_plumbers/themes/schema.rb

@@ -119,69 +119,90 @@ module StimulusPlumbers
       }.freeze
 
       FORM = {
-        form_group:                     {
+        form_group:                             {
           layout: { default: :stacked, validate: Form::Ranges::LAYOUT },
           error:  { default: false,    validate: Ranges::BOOL }
         }.freeze,
-        form_field_label:               {
+        form_field_label:                       {
           required: { default: false, validate: Ranges::BOOL },
           hidden:   { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] },
           error:    { default: false, validate: Ranges::BOOL }
         }.freeze,
-        form_field_required_mark:       {}.freeze,
-        form_field_hint:                {}.freeze,
-        form_field_error:               {}.freeze,
-        form_field_choice_items:        {
+        form_field_required_mark:               {}.freeze,
+        form_field_hint:                        {}.freeze,
+        form_field_error:                       {}.freeze,
+        form_field_choice_items:                {
           layout: { default: :stacked, validate: Form::Ranges::LAYOUT }
         }.freeze,
-        form_field_checkbox_label:      {
+        form_field_checkbox_label:              {
           type:    { default: :default,  validate: Form::Checkbox::Ranges::TYPE },
           variant: { default: :tertiary, validate: Form::Checkbox::Ranges::VARIANT }
         }.freeze,
-        form_field_radio_label:         {
+        form_field_radio_label:                 {
           type:    { default: :default,  validate: Form::Radio::Ranges::TYPE },
           variant: { default: :tertiary, validate: Form::Radio::Ranges::VARIANT }
         }.freeze,
-        form_field_radio_item_group:    {}.freeze,
-        form_field_input:               {
+        form_field_radio_item_group:            {}.freeze,
+        form_field_input:                       {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_group:         {
+        form_field_input_group:                 {
           floating: { default: nil, validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_textarea:      {
+        form_field_input_textarea:              {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_file:          {
+        form_field_input_file:                  {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_select:        {
+        form_field_input_select:                {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_checkbox:      {
+        form_field_input_checkbox:              {
           error:   { default: false,     validate: Ranges::BOOL },
           type:    { default: :default,  validate: Form::Checkbox::Ranges::TYPE },
           variant: { default: :tertiary, validate: Form::Checkbox::Ranges::VARIANT }
         }.freeze,
-        form_field_input_radio:         {
+        form_field_input_radio:                 {
           error:   { default: false,     validate: Ranges::BOOL },
           type:    { default: :default,  validate: Form::Radio::Ranges::TYPE },
           variant: { default: :tertiary, validate: Form::Radio::Ranges::VARIANT }
         }.freeze,
-        form_field_input_combobox:      {
+        form_field_input_combobox:              {
           error:    { default: false, validate: Ranges::BOOL },
           floating: { default: nil,   validate: [nil, *Form::Floating::Ranges::TYPE] }
         }.freeze,
-        form_field_input_reveal:        { error: { default: false, validate: Ranges::BOOL } }.freeze,
-        form_field_input_clearable:     {}.freeze,
-        form_field_input_button_reveal: {}.freeze,
-        form_field_input_button_clear:  {}.freeze,
-        form_submit:                    {
+        form_field_input_reveal:                { error: { default: false, validate: Ranges::BOOL } }.freeze,
+        form_field_input_clearable:             {}.freeze,
+        form_field_input_code:                  {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_code_cells:            {}.freeze,
+        form_field_input_code_cell:             {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_code_overlay:          {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_credit_card:           {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_credit_card_cells:     {}.freeze,
+        form_field_input_credit_card_cell:      {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_credit_card_separator: {}.freeze,
+        form_field_input_credit_card_overlay:   {
+          error: { default: false, validate: Ranges::BOOL }
+        }.freeze,
+        form_field_input_button_reveal:         {}.freeze,
+        form_field_input_button_clear:          {}.freeze,
+        form_submit:                            {
           type:    { default: :default, validate: Button::Ranges::TYPE },
           variant: { default: :primary, validate: Button::Ranges::VARIANT }
         }.freeze

data/lib/stimulus_plumbers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusPlumbers
-  VERSION = "0.4.9"
+  VERSION = "0.4.10"
 end

data/vendor/ARIA.md

@@ -62,6 +62,13 @@ Two helper classes handle keyboard navigation in controllers — see [`stimulus-
 - Toggle button: `aria-label` describes action ("Show password" / "Hide password")
 - `aria-pressed` managed on toggle button, reflecting revealed state
 
+#### Code Input (`input_formatter_controller` + `character_cells`)
+
+- The real `<input>` is the entire accessible surface; cells are stamped `aria-hidden="true"` automatically.
+- The input requires a `<label>` (visually hidden allowed), `autocomplete="one-time-code"` for OTP (WCAG 1.3.5), `inputmode` matching the charset, and `maxlength` matching the code length.
+- Overlay the input with `opacity: 0` — never `display: none`/`visibility: hidden`, which remove it from the tab order (WCAG 2.1.1).
+- Focus visibility (WCAG 2.4.7): the caret cell (`data-caret`) appears only while the input has focus; style the wrapper with `:focus-within` plus `[data-caret]`.
+
 #### Input Clearable (`input_clearable_controller`)
 - Clear button: `hidden` attribute while the input is empty, removing it from the keyboard/AT tab order until there's something to clear
 - Escape inside the input clears it (keyboard equivalent to clicking the clear button, WCAG 2.1.1); default is prevented so it doesn't also close a parent overlay

data/vendor/component/manifest.json

@@ -127,6 +127,9 @@
   },
   "input-formatter": {
     "actions": [
+      "onBlur",
+      "onFocus",
+      "onInput",
       "toggle"
     ],
     "listens": [],