stimulus_plumbers 0.4.11 → 0.4.13

data/config/locales/en.yml

@@ -27,5 +27,6 @@ en:
     form:
       password:
         show: "Show password"
+        hide: "Hide password"
       search:
         clear: "Clear search"

data/docs/architecture.md

@@ -26,6 +26,6 @@ Validation ranges for theme schema params live under `lib/stimulus_plumbers/them
 
 `Button#build_button` and `Link#build_content` always wrap non-nil text/block content in `<span>`. When content is nil and no block is given (icon-only), no `<span>` is rendered.
 
-The active theme uses `:has(> span)` / `:not(:has(> span))` CSS to distinguish icon-only from text buttons without any Ruby flag.
+The active theme uses `:has(> span)` / `:not(:has(> span))` CSS to distinguish icon-only from text buttons without any Ruby flag. Submit buttons with visually hidden text additionally use `:has(> span[data-sp-label-hidden])` so they retain the icon-only square layout while keeping an accessible name.
 
 **Do not change this contract** without updating `stimulus-plumbers-tailwind`'s `Button::LAYOUT` and `Link::BUTTON` constants accordingly. See [tailwind architecture doc](../../stimulus-plumbers-tailwind/docs/architecture.md#icon-only-square-pattern).

data/docs/component/form.md

@@ -52,9 +52,28 @@ Special options on native helpers:
 
 | Helper           | Option             | Effect                                                             |
 | ---------------- | ------------------ | ------------------------------------------------------------------ |
-| `password_field` | `revealable: true` | Wraps input in an `input-formatter` reveal controller              |
+| `password_field` | `revealable: true` | Wraps input in an `input-revealable` controller                    |
 | `search_field`   | `clearable: true`  | Wraps input in an `input-clearable` controller with a clear button |
 
+### f.submit
+
+`f.submit` renders a themed `<button type="submit">` without a field wrapper.
+
+```erb
+<%= f.submit "Save" %>
+<%= f.submit "Save", icon_leading: "save" %>
+<%= f.submit "Continue", icon_trailing: "arrow-right" %>
+<%= f.submit "Save", icon_leading: "save", hide_label: true %>
+```
+
+| Option                             | Description                                                                                                                                                                      |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type:` / `variant:`               | Button theme type and variant.                                                                                                                                                   |
+| `icon_leading:` / `icon_trailing:` | Decorative icon name placed before or after the submit text.                                                                                                                     |
+| `hide_label: true`                 | Visually hides the button's own text span while keeping it available to screen readers. This differs from `Form::Field#hide_label`, which hides an associated `<label>` element. |
+
+Submit buttons need an accessible name: pass non-blank text, or an `aria` label such as `aria: { label: "Save changes" }`.
+
 ---
 
 ## Level 2 — Full-field helpers
@@ -141,31 +160,34 @@ Use `f.select` for a native `<select>`.
 
 Use `f.search_field` for a native `<input type="search">`.
 
-**Password** (`as: :password`) — reveal-toggle wrapper backed by `input-formatter`.
+**Password** (`as: :password`) — reveal-toggle wrapper backed by `input-revealable`.
 
-| Option       | Values  | Default | Description                                 |
-| ------------ | ------- | ------- | ------------------------------------------- |
-| `revealable` | Boolean | `false` | Adds a show/hide toggle button on the input |
+| Option         | Values  | Default              | Description                                 |
+| -------------- | ------- | -------------------- | ------------------------------------------- |
+| `revealable`   | Boolean | `false`              | Adds a show/hide toggle button on the input |
+| `autocomplete` | String  | `"current-password"` | Native autocomplete value                   |
 
 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                                                            |
+| 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`              |
+| `separator`    | String / `nil`                           | `nil`                  | Character between groups; `nil` shows the break as a gap |
+| `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; their sum sets `maxlength`.
+
+| Option         | Values                     | Default        | Description                                                  |
+| -------------- | -------------------------- | -------------- | ------------------------------------------------------------ |
+| `groups`       | Array of positive Integers | `[4, 4, 4, 4]` | Cell groups — one cell per group; their sum sets `maxlength` |
+| `separator`    | String / `nil`             | `nil`          | Character between cells; `nil` renders none                  |
+| `autocomplete` | String                     | `"cc-number"`  | Native autocomplete value                                    |
+| `inputmode`    | String                     | `"numeric"`    | Native input mode                                            |
 
 Character-cell fields do not support `floating:` labels.
 

data/docs/component/icon.md

@@ -7,17 +7,17 @@ Rails helper for rendering a named icon from the active theme's icon registry.
 ### `sp_icon`
 
 ```erb
-<%= sp_icon name: "check" %>
-<%= sp_icon name: "spinner", aria: { label: "Loading" }, role: "img" %>
-<%= sp_icon name: "unknown-icon" %>
-<%= sp_icon name: "check", size: :sm %>
+<%= sp_icon "check" %>
+<%= sp_icon "spinner", aria: { label: "Loading" }, role: "img" %>
+<%= sp_icon "unknown-icon" %>
+<%= sp_icon "check", size: :sm %>
 ```
 
-| Option           | Default    | Description                                         |
-| ---------------- | ---------- | --------------------------------------------------- |
-| `name`           | (required) | Icon name — looked up in the theme registry         |
-| `size`           | `:lg`      | `:sm` \| `:md` \| `:lg` — theme-resolved size class |
-| `**html_options` | —          | Forwarded to the root element                       |
+| Option           | Default    | Description                                                            |
+| ---------------- | ---------- | ---------------------------------------------------------------------- |
+| `name`           | (required) | Positional (1st argument). Icon name — looked up in the theme registry |
+| `size`           | `:lg`      | `:sm` \| `:md` \| `:lg` — theme-resolved size class                    |
+| `**html_options` | —          | Forwarded to the root element                                          |
 
 ---
 

data/docs/guide.md

@@ -12,7 +12,8 @@ Use `StimulusPlumbers::Form::Builder` (set `config.action_view.default_form_buil
 - **Level 1.** Native helper overrides (`f.text_field`, `f.select`, `f.check_box`, ...) render
   only the themed input element — use when you control the surrounding markup.
 
-Submit with `f.submit` (themed button).
+Submit with `f.submit` (themed button; supports `icon_leading:`/`icon_trailing:` and
+`hide_label:` for an icon-only button — see [docs/component/form.md](component/form.md)).
 
 ## Building views
 

data/lib/stimulus_plumbers/components/button/icon_layout.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module Components
+    class Button < Plumber::Base
+      module IconLayout
+        private
+
+        def build_layout(slots, &block)
+          @template.safe_join(
+            [
+              render_icon_slot(slots, :icon_leading),
+              @template.capture(&block),
+              render_icon_slot(slots, :icon_trailing)
+            ]
+          )
+        end
+
+        def render_icon_slot(slots, name)
+          slots.resolve(name) do |value|
+            next value unless Components::Icon.icon_name?(value)
+
+            Components::Icon.new(@template).render(
+              value,
+              size:    :sm,
+              classes: theme.resolve(:button_icon).fetch(:classes, ""),
+              aria:    { hidden: "true" }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/components/button.rb

@@ -3,6 +3,8 @@
 module StimulusPlumbers
   module Components
     class Button < Plumber::Base
+      include IconLayout
+
       def render(content = nil, icon_leading: nil, icon_trailing: nil, **kwargs, &block)
         slots = Button::Slots.new(template)
         slots.with_icon_leading(icon_leading) if icon_leading
@@ -34,29 +36,6 @@ module StimulusPlumbers
           template.content_tag(:span, content)
         end
       end
-
-      def build_layout(slots, &block)
-        template.safe_join(
-          [
-            render_icon_slot(slots, :icon_leading),
-            template.capture(&block),
-            render_icon_slot(slots, :icon_trailing)
-          ]
-        )
-      end
-
-      def render_icon_slot(slots, name)
-        slots.resolve(name) do |value|
-          next value unless Components::Icon.icon_name?(value)
-
-          Components::Icon.new(template).render(
-            name:    value,
-            size:    :sm,
-            classes: theme.resolve(:button_icon).fetch(:classes, ""),
-            aria:    { hidden: "true" }
-          )
-        end
-      end
     end
   end
 end

data/lib/stimulus_plumbers/components/card.rb

@@ -49,7 +49,7 @@ module StimulusPlumbers
         return value unless value.is_a?(Symbol) || (value.is_a?(String) && !value.html_safe?)
 
         Components::Icon.new(template).render(
-          name:    value,
+          value,
           classes: theme.resolve(:card_icon).fetch(:classes, ""),
           aria:    { hidden: "true" }
         )

data/lib/stimulus_plumbers/components/combobox/builder.rb

@@ -6,15 +6,37 @@ module StimulusPlumbers
       # Yielded to `Combobox#render`: selects a variant renderer, then exposes its
       # `metadata` (trigger/wrapper wiring) and renders its panel body.
       class Builder < Plumber::Slots
-        def dropdown(**options)  = select(Dropdown, options)
-        def typeahead(**options) = select(Typeahead, options)
-        def date(**options)      = select(Date, options)
-        def time(**options)      = select(Time, options)
+        def dropdown(**options)
+          select(Dropdown, options)
+        end
+
+        def typeahead(**options)
+          select(Typeahead, options)
+        end
+
+        def date(**options)
+          select(Date, options)
+        end
 
-        def selected? = @slots.key?(:variant)
-        def renderer  = selection&.fetch(:renderer)
-        def options   = selection ? selection[:options] : {}
-        def metadata  = renderer ? renderer::Metadata : DefaultMetadata
+        def time(**options)
+          select(Time, options)
+        end
+
+        def selected?
+          @slots.key?(:variant)
+        end
+
+        def renderer
+          selection&.fetch(:renderer)
+        end
+
+        def options
+          selection ? selection[:options] : {}
+        end
+
+        def metadata
+          renderer ? renderer::Metadata : DefaultMetadata
+        end
 
         def render_panel(template, panel_attrs:)
           renderer&.new(template)&.render(panel_attrs: panel_attrs, **options)
@@ -24,11 +46,25 @@ module StimulusPlumbers
         module DefaultMetadata
           module_function
 
-          def haspopup = "dialog"
-          def popup_id_for(panel_id) = panel_id
-          def trigger_icon = nil
-          def trigger_options = {}
-          def stimulus_data(_panel_id, _options) = {}
+          def haspopup
+            "dialog"
+          end
+
+          def popup_id_for(panel_id)
+            panel_id
+          end
+
+          def trigger_icon
+            nil
+          end
+
+          def trigger_options
+            {}
+          end
+
+          def stimulus_data(_panel_id, _options)
+            {}
+          end
         end
 
         private
@@ -38,7 +74,9 @@ module StimulusPlumbers
           nil
         end
 
-        def selection = resolve(:variant)
+        def selection
+          resolve(:variant)
+        end
       end
     end
   end

data/lib/stimulus_plumbers/components/combobox/date.rb

@@ -16,21 +16,47 @@ module StimulusPlumbers
           "#{STIMULUS_CONTROLLER}:selected->#{Components::Popover::STIMULUS_CONTROLLER}#closeOnSelect"
         ].join(" ").freeze
 
-        def self.month_id_for(panel_id)   = [panel_id, "calendar_month"].compact.join("_")
-        def self.year_id_for(panel_id)    = [panel_id, "calendar_year"].compact.join("_")
-        def self.decade_id_for(panel_id)  = [panel_id, "calendar_decade"].compact.join("_")
+        class << self
+          def month_id_for(panel_id)
+            [panel_id, "calendar_month"].compact.join("_")
+          end
+
+          def year_id_for(panel_id)
+            [panel_id, "calendar_year"].compact.join("_")
+          end
+
+          def decade_id_for(panel_id)
+            [panel_id, "calendar_decade"].compact.join("_")
+          end
+        end
 
         module Metadata
           module_function
 
-          def haspopup = "dialog"
-          def popup_id_for(panel_id) = panel_id
-          def trigger_icon = "calendar"
-          def trigger_options = {}
-          def stimulus_data(_panel_id, _options) = { input_formatter_format_value: "date" }
+          def haspopup
+            "dialog"
+          end
+
+          def popup_id_for(panel_id)
+            panel_id
+          end
+
+          def trigger_icon
+            "calendar"
+          end
+
+          def trigger_options
+            {}
+          end
+
+          def stimulus_data(_panel_id, _options)
+            { input_formatter_format_value: "date" }
+          end
         end
 
-        def render(...) = render_date(...)
+        def render(...)
+          render_date(...)
+        end
 
         private
 

data/lib/stimulus_plumbers/components/combobox/dropdown.rb

@@ -15,14 +15,30 @@ module StimulusPlumbers
         module Metadata
           module_function
 
-          def haspopup = "listbox"
-          def popup_id_for(panel_id) = panel_id
-          def trigger_icon = "chevron-down"
-          def trigger_options = {}
-          def stimulus_data(_panel_id, _options) = {}
+          def haspopup
+            "listbox"
+          end
+
+          def popup_id_for(panel_id)
+            panel_id
+          end
+
+          def trigger_icon
+            "chevron-down"
+          end
+
+          def trigger_options
+            {}
+          end
+
+          def stimulus_data(_panel_id, _options)
+            {}
+          end
         end
 
-        def render(...) = render_dropdown(...)
+        def render(...)
+          render_dropdown(...)
+        end
 
         private
 

data/lib/stimulus_plumbers/components/combobox/time.rb

@@ -13,10 +13,21 @@ module StimulusPlumbers
         module Metadata
           module_function
 
-          def haspopup = "dialog"
-          def popup_id_for(panel_id) = panel_id
-          def trigger_icon = "clock"
-          def trigger_options = {}
+          def haspopup
+            "dialog"
+          end
+
+          def popup_id_for(panel_id)
+            panel_id
+          end
+
+          def trigger_icon
+            "clock"
+          end
+
+          def trigger_options
+            {}
+          end
 
           def stimulus_data(_panel_id, options)
             {
@@ -26,7 +37,9 @@ module StimulusPlumbers
           end
         end
 
-        def render(...) = render_time(...)
+        def render(...)
+          render_time(...)
+        end
 
         private
 

data/lib/stimulus_plumbers/components/combobox/trigger.rb

@@ -84,7 +84,7 @@ module StimulusPlumbers
 
         def render_trigger_icon(name)
           Components::Icon.new(template).render(
-            name:    name,
+            name,
             classes: theme.resolve(:combobox_trigger_icon).fetch(:classes, ""),
             aria:    { hidden: "true" }
           )

data/lib/stimulus_plumbers/components/combobox/typeahead.rb

@@ -4,17 +4,30 @@ module StimulusPlumbers
   module Components
     class Combobox
       class Typeahead < Plumber::Base
-        def self.listbox_id_for(panel_id)
-          [panel_id, "listbox"].compact.join("_")
+        class << self
+          def listbox_id_for(panel_id)
+            [panel_id, "listbox"].compact.join("_")
+          end
         end
 
         module Metadata
           module_function
 
-          def haspopup = "listbox"
-          def popup_id_for(panel_id) = Typeahead.listbox_id_for(panel_id)
-          def trigger_icon = nil
-          def trigger_options = { readonly: false, aria: { autocomplete: "list" } }
+          def haspopup
+            "listbox"
+          end
+
+          def popup_id_for(panel_id)
+            Typeahead.listbox_id_for(panel_id)
+          end
+
+          def trigger_icon
+            nil
+          end
+
+          def trigger_options
+            { readonly: false, aria: { autocomplete: "list" } }
+          end
 
           def stimulus_data(panel_id, _options)
             {
@@ -24,7 +37,9 @@ module StimulusPlumbers
           end
         end
 
-        def render(...) = render_typeahead(...)
+        def render(...)
+          render_typeahead(...)
+        end
 
         private
 
@@ -74,7 +89,7 @@ module StimulusPlumbers
             )
           ) do
             Components::Icon.new(template).render(
-              name:    "spinner",
+              "spinner",
               size:    :md,
               classes: theme.resolve(:combobox_typeahead_loading_icon).fetch(:classes, ""),
               aria:    { hidden: "true" }

data/lib/stimulus_plumbers/components/icon.rb

@@ -3,11 +3,13 @@
 module StimulusPlumbers
   module Components
     class Icon < Plumber::Base
-      def self.icon_name?(value)
-        value.is_a?(Symbol) || (value.is_a?(String) && !value.html_safe?)
+      class << self
+        def icon_name?(value)
+          value.is_a?(Symbol) || (value.is_a?(String) && !value.html_safe?)
+        end
       end
 
-      def render(name:, size: :lg, **kwargs)
+      def render(name, size: :lg, **kwargs)
         html_options = merge_html_options(
           theme.resolve(:icon, size: size),
           kwargs

data/lib/stimulus_plumbers/components/indicator.rb

@@ -3,7 +3,9 @@
 module StimulusPlumbers
   module Components
     class Indicator < Plumber::Base
-      def render(...) = render_indicator(...)
+      def render(...)
+        render_indicator(...)
+      end
 
       private
 

data/lib/stimulus_plumbers/components/link.rb

@@ -44,7 +44,7 @@ module StimulusPlumbers
           next value unless Components::Icon.icon_name?(value)
 
           Components::Icon.new(template).render(
-            name:    value,
+            value,
             size:    :sm,
             classes: theme.resolve(:link_icon).fetch(:classes, ""),
             aria:    { hidden: "true" }

data/lib/stimulus_plumbers/components/list/item.rb

@@ -43,7 +43,7 @@ module StimulusPlumbers
             next value unless Components::Icon.icon_name?(value)
 
             Components::Icon.new(template).render(
-              name:    value,
+              value,
               classes: theme.resolve(:list_item_icon).fetch(:classes, ""),
               aria:    { hidden: "true" }
             )

data/lib/stimulus_plumbers/components/ordered_list/item.rb

@@ -85,7 +85,7 @@ module StimulusPlumbers
             next value unless Components::Icon.icon_name?(value)
 
             Components::Icon.new(template).render(
-              name:    value,
+              value,
               size:    :sm,
               classes: theme.resolve(:ordered_list_item_handle).fetch(:classes, ""),
               aria:    { hidden: "true" }
@@ -95,7 +95,7 @@ module StimulusPlumbers
 
         def default_handle_icon
           Components::Icon.new(template).render(
-            name:    "grip-vertical",
+            "grip-vertical",
             size:    :sm,
             classes: theme.resolve(:ordered_list_item_handle).fetch(:classes, ""),
             aria:    { hidden: "true" }

data/lib/stimulus_plumbers/components/popover.rb

@@ -5,11 +5,15 @@ module StimulusPlumbers
     class Popover < Plumber::Base
       STIMULUS_CONTROLLER = "popover"
 
-      def self.panel_id_for(trigger_id)
-        [trigger_id, "popover"].compact.join("_")
+      class << self
+        def panel_id_for(trigger_id)
+          [trigger_id, "popover"].compact.join("_")
+        end
       end
 
-      def render(...) = render_popover(...)
+      def render(...)
+        render_popover(...)
+      end
 
       def build(panel_id: nil, &block)
         @panel_id     = panel_id || self.class.panel_id_for(template.sp_dom_id)

data/lib/stimulus_plumbers/components/progress_bar.rb

@@ -3,7 +3,9 @@
 module StimulusPlumbers
   module Components
     class ProgressBar < Plumber::Base
-      def render(...) = render_bar(...)
+      def render(...)
+        render_bar(...)
+      end
 
       private
 

data/lib/stimulus_plumbers/components/progress_meter.rb

@@ -3,7 +3,9 @@
 module StimulusPlumbers
   module Components
     class ProgressMeter < Plumber::Base
-      def render(...) = render_meter(...)
+      def render(...)
+        render_meter(...)
+      end
 
       private
 

data/lib/stimulus_plumbers/components/progress_ring.rb

@@ -3,7 +3,9 @@
 module StimulusPlumbers
   module Components
     class ProgressRing < Plumber::Base
-      def render(...) = render_ring(...)
+      def render(...)
+        render_ring(...)
+      end
 
       private
 
@@ -14,7 +16,7 @@ module StimulusPlumbers
           stimulus_data(value: value, min: min, max: max, indeterminate: indeterminate),
           { role: "progressbar", aria: progress_aria(value: value, min: min, max: max, indeterminate: indeterminate) }
         )
-        Components::Icon.new(template).render(name: "progress-ring", **icon_options)
+        Components::Icon.new(template).render("progress-ring", **icon_options)
       end
 
       def progress_aria(value:, min:, max:, indeterminate:)