stimulus_plumbers 0.4.4 → 0.4.5

data/docs/component/link.md

@@ -0,0 +1,90 @@
+# Link
+
+Rails helper for rendering themed, accessible links and link-styled buttons.
+
+## Helper
+
+### `sp_link`
+
+```erb
+<%= sp_link "Home", url: root_path %>
+<%= sp_link "Docs", url: docs_path, type: :button %>
+<%= sp_link "Delete", url: item_path(@item), type: :card, variant: :destructive %>
+<%= sp_link(icon_leading: "arrow-left", url: back_path) { "Back" } %>
+<%= sp_link "GitHub", url: "https://github.com", target: "_blank" %>
+```
+
+| Option           | Default    | Description                                                                        |
+| ---------------- | ---------- | ---------------------------------------------------------------------------------- |
+| `content`        | `nil`      | Link text — positional arg or block                                                |
+| `url`            | (required) | `href` value                                                                       |
+| `type`           | `:default` | Visual style — `:default` \| `:button` \| `:card`                                  |
+| `variant`        | `:default` | Color source — `:default` \| `:success` \| `:destructive` \| `:warning` \| `:info` |
+| `icon_leading`   | `nil`      | Icon rendered **before** the label — icon name (string or symbol) or callable      |
+| `icon_trailing`  | `nil`      | Icon rendered **after** the label — icon name (string or symbol) or callable       |
+| `target`         | `nil`      | Forwarded to `<a target>`. `"_blank"` auto-sets `icon_trailing: "external-link"`   |
+| `**html_options` | —          | Forwarded to the `<a>` element                                                     |
+
+**`type:` — visual style**
+
+| Value      | Appearance                                                                 |
+| ---------- | -------------------------------------------------------------------------- |
+| `:default` | Inline text link — colored, underlines on hover                            |
+| `:button`  | Outlined button shape — border + surface background, no fill               |
+| `:card`    | Full-padding card — `flex-1`, `justify-start`; border + surface background |
+
+**`variant:` — color source**
+
+Unlike `sp_button`, link variants use `--link-color` / `--link-ring` / `--link-bg` tokens. `:default` maps to `--sp-color-primary`.
+
+---
+
+## Rendered HTML Structure
+
+Text content is always wrapped in a `<span>`:
+
+```html
+<a href="/path" class="[theme classes]"><span>Home</span></a>
+```
+
+### With icons
+
+```html
+<a href="/path" class="[theme classes]">
+  <svg aria-hidden="true" class="[link_icon theme classes]">
+    <!-- icon svg -->
+  </svg>
+  <span>Back</span>
+</a>
+```
+
+### External link (auto trailing icon)
+
+```html
+<a href="https://github.com" target="_blank" class="[theme classes]">
+  <span>GitHub</span>
+  <svg aria-hidden="true" class="[link_icon theme classes]">
+    <!-- external-link icon -->
+  </svg>
+</a>
+```
+
+### Icon only (`type: :button`)
+
+When no text is provided, `type: :button` links become square (same mechanism as `sp_button`):
+
+```html
+<a href="/path" aria-label="Add" class="[theme classes]">
+  <svg aria-hidden="true" class="[link_icon theme classes]">
+    <!-- icon svg -->
+  </svg>
+</a>
+```
+
+---
+
+## ARIA
+
+- Renders an `<a>` element — use `sp_button` for actions without a URL destination.
+- `target="_blank"` automatically appends an external-link icon (`aria-hidden="true"`); add a visually-hidden description if the context requires it.
+- Icon-only links must supply an accessible label via `aria: { label: "..." }` in `html_options`.

data/docs/component/list.md

@@ -0,0 +1,161 @@
+# List
+
+Rails helper for rendering an accessible list of links, buttons, or grouped sections.
+
+## Helper
+
+### `sp_list`
+
+```erb
+<%# Flat list %>
+<%= sp_list do |list| %>
+  <%= list.item("Dashboard", url: root_path) %>
+  <%= list.item("Settings", url: settings_path) %>
+  <%= list.item("Sign out") %>
+<% end %>
+
+<%# With icons %>
+<%= sp_list do |list| %>
+  <%= list.item("Dashboard", url: root_path) do |item| %>
+    <% item.with_icon_leading("home") %>
+  <% end %>
+<% end %>
+
+<%# Grouped sections %>
+<%= sp_list(heading_level: 2) do |list| %>
+  <%= list.section(title: "Account") do |section| %>
+    <%= section.item("Profile", url: profile_path) %>
+    <%= section.item("Billing", url: billing_path) %>
+  <% end %>
+  <%= list.section(title: "Danger zone") do |section| %>
+    <%= section.item("Delete account") %>
+  <% end %>
+<% end %>
+```
+
+| Option           | Default  | Description                                                                              |
+| ---------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `heading_level:` | `nil`    | When set, section titles render as `<h{n}>`; nested sections increment and clamp at `h6` |
+| `role:`          | `"list"` | ARIA role on the `<ul>` — use `"menu"` for interactive menus                             |
+| `**html_options` | —        | Forwarded to the `<ul>`                                                                  |
+
+### `list.section(title:, description:, **html_options)`
+
+Renders a `<li>` with an optional heading/description and a nested `<ul>`.
+
+| Option         | Default | Description                                                                                          |
+| -------------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `title:`       | `nil`   | Without `heading_level`: renders `<span aria-hidden="true">`; with `heading_level`: renders `<h{n}>` |
+| `description:` | `nil`   | Rendered as a `<span>` beside the title                                                              |
+
+### `list.item(content, url:, active:, target:, **html_options, &block)`
+
+Renders a `<li>` containing an `<a>` (when `url:` present) or `<button>`.
+
+| Option           | Default | Description                                                         |
+| ---------------- | ------- | ------------------------------------------------------------------- |
+| `content`        | `nil`   | Item label — positional arg or via `item.with_title`                |
+| `url:`           | `nil`   | Renders `<a href>` inside the `<li>`                                |
+| `active:`        | `false` | Adds `aria-current="page"` (link) or `aria-current="true"` (button) |
+| `target:`        | `nil`   | Forwarded to the `<a>` (e.g. `"_blank"`)                            |
+| `**html_options` | —       | Forwarded to the inner `<a>` or `<button>`                          |
+
+When `target: "_blank"` is set, `icon_trailing: "external-link"` is added automatically.
+
+### Item slot methods (yielded as `item`)
+
+| Slot method                     | Description                                                   |
+| ------------------------------- | ------------------------------------------------------------- |
+| `item.with_icon_leading(name)`  | Icon before the content — string/symbol resolves via `Icon`   |
+| `item.with_title(text)`         | Title text (pre-populated when positional `content` is given) |
+| `item.with_description(text)`   | Secondary text below the title                                |
+| `item.with_icon_trailing(name)` | Icon after the content — string/symbol resolves via `Icon`    |
+
+---
+
+## Rendered HTML Structure
+
+### Flat list
+
+```html
+<ul role="list" class="[list theme classes]">
+  <li class="[list_item theme classes]">
+    <a href="/dashboard" class="...">
+      <span class="[list_item_content theme classes]">
+        <span class="[list_item_title theme classes]">Dashboard</span>
+      </span>
+    </a>
+  </li>
+</ul>
+```
+
+### Item with icons
+
+```html
+<li class="[list_item theme classes]">
+  <a href="/profile" class="...">
+    <svg aria-hidden="true" class="[list_item_icon theme classes]">...</svg>
+    <span class="[list_item_content theme classes]">
+      <span class="[list_item_title theme classes]">Profile</span>
+      <span class="[list_item_description theme classes]"
+        >Manage your account</span
+      >
+    </span>
+    <svg aria-hidden="true" class="[list_item_icon theme classes]">...</svg>
+  </a>
+</li>
+```
+
+### Sectioned list (no heading_level)
+
+```html
+<ul role="list" class="[list theme classes]">
+  <li class="[list_section theme classes]">
+    <span aria-hidden="true" class="[list_section_title theme classes]"
+      >Account</span
+    >
+    <ul aria-label="Account">
+      <li class="[list_item theme classes]">...</li>
+    </ul>
+  </li>
+</ul>
+```
+
+### Sectioned list (heading_level: 2)
+
+```html
+<ul role="list" class="[list theme classes]">
+  <li class="[list_section theme classes]">
+    <h2 class="[list_section_title theme classes]">Account</h2>
+    <ul aria-label="Account">
+      <li class="[list_item theme classes]">...</li>
+    </ul>
+  </li>
+</ul>
+```
+
+---
+
+## Theme keys
+
+| Key                        | Element                                               | Variants |
+| -------------------------- | ----------------------------------------------------- | -------- |
+| `list`                     | Outer `<ul>`                                          | —        |
+| `list_section`             | Section wrapper `<li>`                                | —        |
+| `list_section_title`       | Section title `<span>` or `<h{n}>`                    | —        |
+| `list_section_description` | Section description `<span>`                          | —        |
+| `list_item`                | Item `<li>` (theme applied to inner `<a>`/`<button>`) | —        |
+| `list_item_icon`           | Leading and trailing icon elements                    | —        |
+| `list_item_content`        | Content wrapper `<span>` (title + description)        | —        |
+| `list_item_title`          | Title `<span>`                                        | —        |
+| `list_item_description`    | Description `<span>`                                  | —        |
+
+---
+
+## ARIA
+
+- Default `role="list"` is appropriate for navigation or command lists.
+- Use `role="menu"` + `role="menuitem"` (via `html_options`) only when items form a widget menu — arrow key navigation must then be wired via a Stimulus controller.
+- `active: true` adds `aria-current="page"` on links and `aria-current="true"` on buttons; pair this with a visual style change so the state is not communicated by color alone.
+- Section titles without `heading_level` use `aria-hidden="true"` on the `<span>` and set `aria-label` on the nested `<ul>` to avoid double-announcing.
+- Nested sections increment the heading level automatically (clamped at `h6`).

data/docs/component/modal.md

@@ -0,0 +1,19 @@
+# Modal
+
+The `modal` controller is used directly in HTML — there is no Rails helper. See the [JS controller docs](../../../stimulus-plumbers/docs/component/modal.md) for targets, methods, and usage examples.
+
+## Quick example (ERB)
+
+```erb
+<div data-controller="modal">
+  <%= tag.button "Open", data: { action: "modal#open" } %>
+
+  <%= tag.dialog data: { modal_target: "modal" },
+                 aria: { labelledby: "modal-title", modal: true } do %>
+    <h2 id="modal-title">Confirm action</h2>
+    <p>Are you sure?</p>
+    <%= tag.button "Cancel",  data: { action: "modal#close" } %>
+    <%= tag.button "Confirm" %>
+  <% end %>
+</div>
+```

data/docs/component/plumber.md

@@ -0,0 +1,183 @@
+# Plumber Internals
+
+The `Plumber` namespace provides the shared infrastructure that all renderers and the form builder are built on: a base class, a renderer declaration macro, and an HTML option merge utility.
+
+See [dispatcher.md](dispatcher.md) for the `Plumber::Dispatcher` strategy factory.
+
+---
+
+## Plumber::Base
+
+The foundation class for all component renderers. Inherit from it to get `template`, `theme`, `merge_html_options`, and the `renders` macro in one shot.
+
+```ruby
+class MyRenderer < StimulusPlumbers::Plumber::Base
+  renders :my_component, with: MyComponent
+
+  def render(...)
+    my_component(...)
+  end
+end
+```
+
+### Included modules
+
+| Module                   | What it adds                                                    |
+| ------------------------ | --------------------------------------------------------------- |
+| `Plumber::Options::Html` | `merge_html_options`, `merge_stimulus_data`, `merge_token_list` |
+| `Plumber::Renderer`      | `renders` class macro; `renderers` class attribute              |
+
+### Instance interface
+
+```ruby
+renderer = MyRenderer.new(view_context)
+renderer.template  # => the ActionView template / view context
+renderer.theme     # => StimulusPlumbers.config.theme.current
+```
+
+`theme` delegates to the global configuration so renderers always read the active theme at call time — no need to pass it in.
+
+---
+
+## Plumber::Renderer
+
+`ActiveSupport::Concern` that adds the `renders` class macro. Included by `Plumber::Base`; can also be included standalone.
+
+### `renders`
+
+Declares a public method on the class and wires it to a callable via `Plumber::Dispatcher`.
+
+```ruby
+renders :method_name, with: callable
+renders :method_name { |*args| ... }    # block form — Proc/InstanceExec strategy
+```
+
+`callable` follows the same type rules as `Dispatcher.build` (Symbol, Proc, Class/Module, String). A block is sugar for `with: proc { ... }`.
+
+When the generated method is called, it:
+
+1. Looks up `renderers.fetch(:method_name)` for the registered callable.
+2. Builds a dispatcher via `Dispatcher.build(callable, *args, method_name: :method_name, init_args: [template], **kwargs)`.
+3. Calls `dispatcher.call(self)`.
+
+The `method_name:` and `init_args: [template]` are injected automatically — you never pass them when calling the generated method.
+
+### Strategy mapping
+
+| `with:` type       | Dispatcher strategy | Effective call                                      |
+| ------------------ | ------------------- | --------------------------------------------------- |
+| `Symbol`           | `MethodCall`        | `self.send(symbol, *args, **kwargs)`                |
+| `Proc` / block     | `InstanceExec`      | `self.instance_exec(*args, **kwargs, &proc)`        |
+| `Class` / `Module` | `KlassProxy`        | `Class.new(template).method_name(*args, **kwargs)`  |
+| `String`           | `KlassProxy`        | Resolved via `safe_constantize`, then same as Class |
+
+### Example
+
+```ruby
+class ComboboxHelper
+  include StimulusPlumbers::Plumber::Renderer
+  include StimulusPlumbers::Plumber::Options::Html
+
+  attr_reader :template
+
+  def initialize(template)
+    @template = template
+  end
+
+  renders :sp_combobox_dropdown, with: Components::Combobox::Dropdown
+  renders :sp_combobox_date,     with: Components::Combobox::Date
+end
+```
+
+Calling `helper.sp_combobox_dropdown(*args, **opts)` instantiates `Components::Combobox::Dropdown.new(template)` and calls `.sp_combobox_dropdown(*args, **opts)` on it.
+
+### `renderers` class attribute
+
+`renderers` is an inheritable `class_attribute` (hash). Subclasses inherit the parent's renderers and can extend or override them without affecting the parent.
+
+```ruby
+class MyHelper < ComboboxHelper
+  renders :sp_combobox_dropdown, with: MyCustomDropdown  # overrides parent's entry
+end
+```
+
+---
+
+## Plumber::Options::Html
+
+Mixin for safely deep-merging HTML attribute hashes. Handles three concerns that a plain `Hash#merge` gets wrong:
+
+1. **`class:` accumulation** — theme classes and caller-supplied classes must both appear, not overwrite each other.
+2. **Stimulus space-joining** — `data-controller` and `data-action` are additive; multiple controllers/actions must be space-joined, not replaced.
+3. **`classes:` key** — theme resolution returns `{ classes: "..." }` rather than `{ class: "..." }` to avoid conflicts; `merge_html_options` unifies both keys.
+
+### `merge_html_options(*hashes)`
+
+Merges any number of HTML option hashes into one. Order matters — later hashes win on plain key conflicts, but `class`/`classes`/`data-controller`/`data-action` are always accumulated.
+
+```ruby
+merge_html_options(
+  { class: "text-sm",   data: { controller: "toggle" } },
+  { classes: "border",  data: { controller: "flip", action: "click->flip#run" } },
+  { class: "font-bold", data: { action: "keydown->flip#key" } }
+)
+# => {
+#   class: "text-sm border font-bold",
+#   data: {
+#     controller: "toggle flip",
+#     action: "click->flip#run keydown->flip#key"
+#   }
+# }
+```
+
+Typical call site in an input renderer:
+
+```ruby
+html_options = merge_html_options(caller_opts, field_theme(:form_input, error: error))
+```
+
+`field_theme` returns `{ class: theme_classes }` (via `{ classes: ... }` internally); `merge_html_options` folds both into a single `class:` value.
+
+### `merge_token_list(*parts, delimiter: " ")`
+
+Joins string-like values into a single space-separated string, deduplicating tokens. Accepts heterogeneous inputs:
+
+| Input type    | Behaviour                                                            |
+| ------------- | -------------------------------------------------------------------- |
+| `String`      | Split by delimiter, each token kept                                  |
+| `Hash`        | Keys whose value is truthy become tokens (conditional class pattern) |
+| `Array`       | Recursively merged                                                   |
+| anything else | Ignored                                                              |
+
+```ruby
+merge_token_list("btn",  "btn-sm", "btn")         # => "btn btn-sm"
+merge_token_list({ "hidden" => false, "active" => true })  # => "active"
+merge_token_list(["flex", "items-center"], "gap-2")        # => "flex items-center gap-2"
+```
+
+### `merge_stimulus_data(*hashes, spacejoin:)`
+
+Deep-merges `data:` sub-hashes. Keys listed in `spacejoin:` (default: `[:controller, :action]`) are space-joined when they conflict; all other keys use last-wins semantics.
+
+```ruby
+merge_stimulus_data(
+  { controller: "toggle", value: "1" },
+  { controller: "flip",   value: "2" }
+)
+# => { controller: "toggle flip", value: "2" }
+```
+
+Pass `spacejoin: []` to disable space-joining entirely (plain deep merge).
+
+### Extending the space-join set
+
+If a Stimulus controller uses a custom multi-valued data key (e.g. `data-targets`), override `merge_stimulus_data` with an extended `spacejoin:` list:
+
+```ruby
+def merge_html_options(*hashes)
+  super.tap do |result|
+    result[:data] = merge_stimulus_data(*hashes.map { |h| h[:data] || {} },
+                                        spacejoin: STIMULUS_SPACEJOIN_KEYS + %i[targets])
+  end
+end
+```

data/docs/component/popover.md

@@ -0,0 +1,138 @@
+# Popover
+
+Rails helper for rendering an accessible popover with a trigger and panel slot.
+
+## Helper
+
+```erb
+<%# Default button trigger %>
+<%= sp_popover do |p| %>
+  <% p.trigger { "Open" } %>
+  <% p.panel(role: "dialog", aria: { label: "Options" }) do %>
+    <p>Popover content</p>
+  <% end %>
+<% end %>
+
+<%# Custom trigger element — one-arity block receives wiring attrs %>
+<%= sp_popover do |p| %>
+  <% p.trigger do |attrs| %>
+    <button type="button"
+            aria-haspopup="<%= attrs[:aria][:haspopup] %>"
+            aria-expanded="<%= attrs[:aria][:expanded] %>"
+            aria-controls="<%= attrs[:panel_id] %>"
+            data-popover-target="trigger"
+            data-action="<%= attrs[:data][:action] %>">
+      <%= image_tag "avatar.png", alt: "My account" %>
+    </button>
+  <% end %>
+  <% p.panel(role: "menu", aria: { label: "Account" }) do %>
+    ...
+  <% end %>
+<% end %>
+```
+
+| Option             | Default | Description                                                                                     |
+| ------------------ | ------- | ----------------------------------------------------------------------------------------------- |
+| `panel_id:`        | auto    | Override the generated panel `id`                                                               |
+| `close_on_select:` | —       | When `false`, sets `data-popover-close-on-select-value="false"` (panel stays open on selection) |
+| `**html_options`   | —       | Forwarded to the outer wrapper `div`                                                            |
+
+### `p.trigger`
+
+Zero-arity block — renders a wired `<button>`; block content becomes the button label:
+
+```erb
+<% p.trigger { "Open" } %>
+<% p.trigger(haspopup: "listbox") { "Choose" } %>
+```
+
+One-arity block — yields `{ panel_id:, aria:, data: }` for caller-defined elements:
+
+```erb
+<% p.trigger do |attrs| %>
+  <input type="text" role="combobox"
+         aria-controls="<%= attrs[:panel_id] %>"
+         data-action="<%= attrs[:data][:action] %>">
+<% end %>
+```
+
+### `p.panel` / `p.build_panel`
+
+Two panel slots mirror the `render` / `build` split (and the 0-/1-arity `trigger`):
+
+`p.panel` — the builder renders the wired panel element; all kwargs are forwarded as
+HTML attributes. The panel is hidden by default and revealed by the Stimulus controller.
+
+```erb
+<% p.panel(tag: :ul, role: "listbox", aria: { labelledby: "my-label" }) do %>
+  ...
+<% end %>
+```
+
+`p.build_panel` — the **caller** renders the element; the block receives `panel_attrs`
+(including the panel `id`) to spread onto its own root. Use it when the panel needs a
+structure of its own (e.g. combobox typeahead: a wrapper around a listbox plus sibling
+status regions).
+
+```ruby
+p.build_panel(classes: "...") do |panel_attrs|
+  content_tag(:div, **panel_attrs) { safe_join([listbox_html, status_html]) }
+end
+```
+
+---
+
+## `build` — for component authors
+
+When a component owns its outer wrapper, call `build` instead of `render` to get trigger + panel without the extra div or `data-controller="popover"`:
+
+```ruby
+Components::Popover.new(template).build(panel_id: "my-panel") do |p|
+  p.trigger(haspopup: "listbox") { |attrs| render_my_trigger(attrs) }
+  p.panel(tag: :ul, role: "listbox") { options_html }
+end
+```
+
+`Popover::Panel` exposes the same pair: `#render` (builds the wired element) and `#build`
+(yields `panel_attrs` for the caller to wire).
+
+---
+
+## Rendered HTML Structure
+
+```html
+<div data-controller="popover" class="[popover_wrapper]">
+  <button
+    type="button"
+    aria-haspopup="dialog"
+    aria-expanded="false"
+    aria-controls="[panel_id]"
+    data-popover-target="trigger"
+    data-action="click->popover#toggle keydown.esc->popover#close"
+    class="[popover_trigger]"
+  >
+    Open
+  </button>
+  <div
+    id="[panel_id]"
+    hidden
+    class="[popover]"
+    role="dialog"
+    aria-label="Options"
+    data-popover-target="panel"
+  >
+    Popover content
+  </div>
+</div>
+```
+
+---
+
+## ARIA
+
+- Default trigger button has `aria-haspopup="dialog"`, `aria-expanded="false"`, and `aria-controls` pointing to the panel.
+- `aria-expanded` is toggled to `"true"` / `"false"` by the Stimulus controller.
+- Pass `role: "dialog"` or `role: "tooltip"` on `p.panel` based on whether the content is interactive.
+- `aria: { label: }` or `aria: { labelledby: }` on `p.panel` provides the accessible name.
+
+For the JS controller API (targets, values, keyboard behaviour), see the [JS package docs](../../../stimulus-plumbers/docs/component/popover.md).