stimulus_plumbers 0.4.4 → 0.4.5

data/docs/component/combobox.md

@@ -0,0 +1,254 @@
+# Combobox
+
+Rails helpers that render fully-wired combobox components. Each variant shares the same wrapper structure (`input-combobox` + `input-formatter`) and differs only in its popover body.
+
+See [docs/component/combobox.md](../../stimulus-plumbers/docs/component/combobox.md) in the JS package for the underlying controller API.
+
+## Helpers
+
+### `sp_combobox`
+
+Single entry point. The panel type is chosen by a method call on the yielded builder
+(`c.dropdown`, `c.typeahead`, `c.date`, `c.time`) — the panel owns its `aria-haspopup`,
+popup id, trigger icon, and wrapper data. The `sp_combobox_*` helpers below are thin
+wrappers over this.
+
+```erb
+<%= sp_combobox(value: "us", label: "Country") do |c|
+  c.dropdown(options: [["United States", "us"], ["Canada", "ca"]], value: "us")
+end %>
+
+<%= sp_combobox(label: "Meeting time") do |c|
+  c.time(format: :h24, step: 15)
+end %>
+```
+
+| Option            | Description                                      |
+| ----------------- | ------------------------------------------------ |
+| `value`           | Initial value (hidden input + trigger)           |
+| `label`           | `aria-label` on the trigger input                |
+| `id`              | Trigger id (defaults to a generated `sp_dom_id`) |
+| `close_on_select` | `false` keeps the panel open after a selection   |
+| `**html_options`  | Forwarded to the wrapper `div`                   |
+
+Builder methods: `c.dropdown(options:, value:, label:)`, `c.typeahead(options:, value:, label:, url:)`,
+`c.date(value:)`, `c.time(format:, step:, value:)`.
+
+---
+
+### `sp_combobox_date`
+
+Date picker backed by a calendar grid.
+
+```erb
+<%= sp_combobox_date %>
+<%= sp_combobox_date(value: "2024-03-15", label: "Date of birth", class: "w-full") %>
+```
+
+| Option           | Description                                                 |
+| ---------------- | ----------------------------------------------------------- |
+| `value`          | ISO 8601 date string — pre-fills and navigates the calendar |
+| `label`          | `aria-label` on the trigger input                           |
+| `**html_options` | Forwarded to the wrapper `div`                              |
+
+---
+
+### `sp_combobox_dropdown`
+
+Read-only combobox with a static listbox popover.
+
+```erb
+<%= sp_combobox_dropdown(options: [["United States", "us"], ["Canada", "ca"]], value: "us") %>
+```
+
+**Option formats:**
+
+```ruby
+# Flat
+[["Label", "value"], ...]
+
+# Grouped
+[{ label: "Americas", options: [["United States", "us"], ...] }, ...]
+
+# With description or disabled flag
+[["United States", "us", { description: "North America" }], ...]
+[["Unavailable",   "x",  { disabled: true }], ...]
+```
+
+| Option           | Description                                             |
+| ---------------- | ------------------------------------------------------- |
+| `options`        | Option rows (see formats above)                         |
+| `value`          | Pre-selected value                                      |
+| `label`          | `aria-label` on the trigger input and the listbox panel |
+| `**html_options` | Forwarded to the wrapper `div`                          |
+
+---
+
+### `sp_combobox_typeahead`
+
+Editable trigger that filters options as the user types. Supports client-side fuzzy matching and server-side fetch.
+
+```erb
+<%# Client-side fuzzy filter %>
+<%= sp_combobox_typeahead(options: [["London", "london"], ["Paris", "paris"]]) %>
+
+<%# Server-side — receives ?q=<query>, must return <li role="option"> HTML fragments %>
+<%= sp_combobox_typeahead(url: cities_path, label: "City") %>
+```
+
+| Option           | Description                                                      |
+| ---------------- | ---------------------------------------------------------------- |
+| `options`        | Initial options rendered on page load (same formats as dropdown) |
+| `value`          | Pre-selected value                                               |
+| `url`            | URL for server-side filtering                                    |
+| `label`          | `aria-label` on the trigger input and the listbox panel          |
+| `**html_options` | Forwarded to the wrapper `div`                                   |
+
+---
+
+### `sp_combobox_time`
+
+iOS-style drum/scroll-wheel time picker.
+
+```erb
+<%= sp_combobox_time %>
+<%= sp_combobox_time(format: :h24, step: 15, value: "14:30", label: "Meeting time") %>
+```
+
+| Option           | Default | Description                                   |
+| ---------------- | ------- | --------------------------------------------- |
+| `format`         | `:h12`  | `:h12` (1–12 + AM/PM) or `:h24` (00–23)       |
+| `step`           | `1`     | Minute increment — `15` yields 00, 15, 30, 45 |
+| `value`          | `nil`   | Pre-selected time as `"HH:MM"`                |
+| `label`          | `nil`   | `aria-label` on the trigger input             |
+| `**html_options` | —       | Forwarded to the wrapper `div`                |
+
+---
+
+## Form Builder
+
+`StimulusPlumbers::Form::Builder` exposes combobox-backed fields through purpose-specific methods rather than a single generic helper. See [form_builder.md](form_builder.md) for the full API.
+
+```erb
+<%= form_with model: @user, builder: StimulusPlumbers::Form::Builder do |f| %>
+  <%= f.date_field   :birthday %>
+  <%= f.time_field   :meeting_time, format: :h24, step: 15 %>
+  <%= f.select       :country, country_options %>
+  <%= f.search_field :city, url: cities_path %>
+<% end %>
+```
+
+All form field methods accept `label:`, `hint:`, `error:`, `required:`, and `hide_label:` in addition to their own options.
+
+---
+
+## Rendered HTML Structure
+
+All variants share the same wrapper pattern. The `popover` controller owns panel
+visibility, `aria-expanded`, outside-click dismissal, and focus; `input-combobox`
+owns value/selection/filtering; `input-formatter` formats the displayed value.
+
+```html
+<div
+  data-controller="popover input-combobox input-formatter"
+  data-action="input-combobox:changed->input-formatter#format"
+  data-input-combobox-value-value="[initial-value]"
+>
+  <input
+    type="text"
+    role="combobox"
+    aria-haspopup="dialog|listbox"
+    aria-expanded="false"
+    aria-controls="[popup-id]"
+    data-popover-target="trigger"
+    data-input-combobox-target="trigger"
+    data-input-formatter-target="input"
+    data-action="focus->popover#open keydown.esc->popover#close"
+  />
+
+  <input type="hidden" name="[name]" data-input-combobox-target="input" />
+
+  <!-- variant-specific popover body (see below) -->
+</div>
+```
+
+`aria-haspopup` is `"listbox"` for dropdown/typeahead, `"dialog"` for date/time. The
+`[popup-id]` is `[id]_popover` for dropdown/date/time and `[id]_popover_listbox` for typeahead.
+
+Pass `close_on_select: false` to any `sp_combobox_*` helper to keep the panel open
+after a selection (renders `data-popover-close-on-select-value="false"` on the wrapper).
+
+### Popover body by variant
+
+Each variant builds its own panel root via `Popover::Builder#build_panel` (see
+[popover.md](popover.md)), adding its controller and role to the panel wiring. The
+trigger's `aria-controls` points at the popup — the panel for dropdown/date/time, the
+nested `<ul role="listbox">` for typeahead.
+
+**date / time** — the panel IS the `role="dialog"` element and hosts the picker controller:
+
+```html
+<div
+  id="[id]_popover"
+  role="dialog"
+  aria-label="[label]"
+  hidden
+  data-popover-target="panel"
+  data-controller="combobox-date"
+  data-action="combobox-date:selected->input-combobox#onSelect combobox-date:selected->popover#closeOnSelect ..."
+>
+  <!-- calendar grid (date) or drum columns (time) -->
+</div>
+```
+
+**dropdown** — the panel IS the `<ul role="listbox">`; options are its only children:
+
+```html
+<ul
+  id="[id]_popover"
+  hidden
+  role="listbox"
+  aria-label="[label]"
+  data-popover-target="panel"
+  data-controller="combobox-dropdown"
+  data-action="click->combobox-dropdown#select keydown->combobox-dropdown#onNavigate combobox-dropdown:selected->input-combobox#onSelect combobox-dropdown:selected->popover#closeOnSelect"
+  data-combobox-dropdown-target="listbox"
+>
+  <li role="option" data-value="us" aria-selected="false">United States</li>
+  <li role="option" data-value="ca" aria-selected="false">Canada</li>
+</ul>
+```
+
+**typeahead** — the panel is a wrapper holding the controller. The `<ul role="listbox">`
+holds only options; the `loading`/`empty` status regions are siblings beside it, since
+`role="listbox"` permits only `option`/`group` children. Status regions stay
+non-focusable (the popover focuses the first focusable element in the panel on open).
+
+```html
+<div
+  id="[id]_popover"
+  hidden
+  data-popover-target="panel"
+  data-controller="combobox-dropdown"
+  data-action="click->combobox-dropdown#select keydown->combobox-dropdown#onNavigate combobox-dropdown:selected->input-combobox#onSelect combobox-dropdown:selected->popover#closeOnSelect"
+  data-combobox-dropdown-url-value="[url]"
+>
+  <ul
+    id="[id]_popover_listbox"
+    role="listbox"
+    aria-labelledby="[label-id]"
+    data-combobox-dropdown-target="listbox"
+  >
+    <li role="option" ...>Paris</li>
+  </ul>
+  <div hidden aria-live="polite" data-combobox-dropdown-target="loading">
+    <!-- spinner -->
+  </div>
+  <div hidden role="status" data-combobox-dropdown-target="empty">
+    No results
+  </div>
+</div>
+```
+
+The remote `url` endpoint returns options-only HTML — it replaces the listbox's
+`innerHTML`, while the `loading`/`empty` siblings persist.

data/docs/component/dispatcher.md

@@ -0,0 +1,76 @@
+# Plumber::Dispatcher
+
+Strategy factory that dispatches a callable against a target object. Used internally by `Form::Builder` to route `f.field` calls to the correct input renderer.
+
+## Factory
+
+```ruby
+Dispatcher.build(callable, *args, **kwargs, &block)
+```
+
+| `callable` type    | Strategy       | Behaviour                                                    |
+| ------------------ | -------------- | ------------------------------------------------------------ |
+| `Symbol`           | `MethodCall`   | Calls the named method on `target`                           |
+| `Proc`             | `InstanceExec` | Executes the proc via `instance_exec` on `target`            |
+| `Module` / `Class` | `KlassProxy`   | Instantiates the class, calls `method_name:` on the instance |
+| `String`           | `KlassProxy`   | Resolved via `safe_constantize`, then same as `Module`       |
+
+All dispatchers share one interface: `dispatcher.call(target)`.
+
+## Strategies
+
+### MethodCall
+
+Calls a named method on `target`. Positional args beyond the method's arity are dropped; kwargs are forwarded only when the method declares keyword parameters. Private methods are reachable.
+
+```ruby
+Dispatcher.build(:render_input, attribute).call(form_builder)
+Dispatcher.build(:render_input, attribute, html_opts, as: :text).call(form_builder)
+
+# block forwarded to the method
+Dispatcher.build(:render_input, attribute) { |html| tag.div(html) }.call(form_builder)
+```
+
+### InstanceExec
+
+Executes a `Proc` via `instance_exec` on `target`. The proc body has full access to `target`'s instance methods and instance variables.
+
+```ruby
+renderer = proc { |attribute, opts| @template.text_field(@object_name, attribute, opts) }
+Dispatcher.build(renderer, attribute, html_opts).call(form_builder)
+```
+
+The `Proc` itself is the block — any `&block` passed to `build` is ignored. To compose a secondary callable, pass it as a positional argument:
+
+```ruby
+wrapper  = ->(html) { tag.div(html, class: "wrapper") }
+renderer = proc { |attribute, opts, wrap| wrap.call(@template.text_field(@object_name, attribute, opts)) }
+Dispatcher.build(renderer, attribute, html_opts, wrapper).call(form_builder)
+```
+
+### KlassProxy
+
+Instantiates `callable` with `init_args:` / `init_kwargs:`, then calls `method_name:` on the instance. `target` is ignored. A `String` callable is resolved via `safe_constantize` at build time.
+
+```ruby
+Dispatcher.build(
+  MyRenderer,
+  attribute, html_opts,
+  method_name: :render,
+  init_args:   [@template]
+).call(anything)
+
+# block forwarded to the method
+Dispatcher.build(
+  MyRenderer,
+  attribute,
+  method_name: :render,
+  init_args:   [@template]
+) { |html| tag.div(html) }.call(anything)
+```
+
+## Block forwarding
+
+`MethodCall` and `KlassProxy` capture a block at build time and forward it to the dispatched method. `dispatcher.block` returns `nil` when no block is given.
+
+`InstanceExec` does not participate — the `Proc` is the block. Compose further callables as positional arguments instead.

data/docs/component/divider.md

@@ -0,0 +1,47 @@
+# Divider
+
+Rails helper for rendering a horizontal rule, optionally labelled.
+
+## Helper
+
+### `sp_divider`
+
+```erb
+<%= sp_divider %>
+<%= sp_divider "or" %>
+<%= sp_divider "Section title", class: "my-4" %>
+```
+
+| Option           | Default | Description                                                                 |
+| ---------------- | ------- | --------------------------------------------------------------------------- |
+| `label`          | `nil`   | Positional arg. When present, the label is centred between two `<hr>` lines |
+| `**html_options` | —       | Forwarded to the outer `<div role="separator">`                             |
+
+---
+
+## Rendered HTML Structure
+
+### Without label
+
+```html
+<div role="separator" class="[divider theme classes]">
+  <hr class="[divider_separator theme classes]" />
+</div>
+```
+
+### With label
+
+```html
+<div role="separator" class="[divider theme classes]">
+  <hr class="[divider_separator theme classes]" />
+  <span class="[divider_label theme classes]">or</span>
+  <hr class="[divider_separator theme classes]" />
+</div>
+```
+
+---
+
+## ARIA
+
+- The outer `<div>` always carries `role="separator"`.
+- The label `<span>` is visible text — no additional ARIA needed.

data/docs/component/form.md

@@ -0,0 +1,238 @@
+# Form
+
+`StimulusPlumbers::Form::Builder` extends Rails' `ActionView::Helpers::FormBuilder` with accessible, themed form fields.
+
+## Setup
+
+```ruby
+# config/application.rb — use globally
+config.action_view.default_form_builder = StimulusPlumbers::Form::Builder
+```
+
+```erb
+<%# or per form %>
+<%= form_with model: @user, builder: StimulusPlumbers::Form::Builder do |f| %>
+  …
+<% end %>
+```
+
+---
+
+## Two-level API
+
+| Level                                 | What it renders                                                 | When to use                                  |
+| ------------------------------------- | --------------------------------------------------------------- | -------------------------------------------- |
+| **Level 1** — native helper overrides | Input element only (theme classes, no label/hint/error wrapper) | When you control surrounding markup manually |
+| **Level 2** — full-field helpers      | Label + input + hint + error, fully wired for accessibility     | Default choice                               |
+
+---
+
+## Level 1 — Native helpers
+
+Standard Rails helpers are overridden to apply theme CSS classes. All native HTML options (`placeholder:`, `autocomplete:`, `class:`, `data:`, etc.) are forwarded.
+
+```erb
+<%= f.text_field     :name %>
+<%= f.email_field    :email %>
+<%= f.number_field   :age %>
+<%= f.text_area      :bio %>
+<%= f.file_field     :avatar %>
+<%= f.date_field     :birthday %>
+<%= f.time_field     :meeting_time %>
+<%= f.select         :country, country_options %>
+<%= f.collection_select :country, Country.all, :code, :name %>
+<%= f.time_zone_select  :timezone %>
+<%= f.weekday_select    :weekday %>
+<%= f.search_field   :query %>
+<%= f.check_box      :agree %>
+<%= f.radio_button   :plan, "basic" %>
+```
+
+Special options on native helpers:
+
+| Helper           | Option             | Effect                                                             |
+| ---------------- | ------------------ | ------------------------------------------------------------------ |
+| `password_field` | `revealable: true` | Wraps input in an `input-formatter` reveal controller              |
+| `search_field`   | `clearable: true`  | Wraps input in an `input-clearable` controller with a clear button |
+
+---
+
+## Level 2 — Full-field 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`                                                                                                                                              |
+
+### Shared field options
+
+| Option       | Type                                  | Default                  | Description                                                                |
+| ------------ | ------------------------------------- | ------------------------ | -------------------------------------------------------------------------- |
+| `label`      | String                                | humanised attribute name | Override label / legend text                                               |
+| `hint`       | String                                | `nil`                    | Hint text rendered below the field                                         |
+| `error`      | String / Array                        | `nil`                    | Override error message(s); suppresses `model.errors[attribute]`            |
+| `required`   | Boolean                               | `false`                  | Adds `required` + `aria-required="true"`                                   |
+| `hide_label` | Boolean                               | `false`                  | Renders label visually hidden (screen-reader accessible)                   |
+| `layout`     | `:stacked` / `:inline`                | `:stacked`               | Label above input vs beside it                                             |
+| `floating`   | `:filled` / `:outlined` / `:standard` | `nil`                    | Floating-label style (text-like inputs only; `nil` = standard label above) |
+
+---
+
+## f.field
+
+```erb
+<%= f.field :name,     as: :text %>
+<%= f.field :email,    as: :email,    label: "E-mail", required: true %>
+<%= 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 :email,    as: :email,    floating: :filled %>
+<%= f.field :country,  as: :select,
+      choices: [["Australia", "au"], ["Canada", "ca"], ["United States", "us"]],
+      include_blank: "Select a country" %>
+<%= f.field :tags,     as: :search,
+      choices: ["ruby", "rails", "hotwire"], clearable: true %>
+```
+
+`choices:` takes the standard Rails shape — an array of `[label, value]` pairs (or a flat array of strings).
+
+**Floating label variants** — label starts inside the input, animates above on focus/fill. Compatible with text-like inputs only.
+
+| `floating:` value | Style                                     |
+| ----------------- | ----------------------------------------- |
+| `:filled`         | Filled background, bottom border only     |
+| `:outlined`       | Full border, label clips through on float |
+| `:standard`       | Bottom border only, no background         |
+
+**Date** (`as: :date`) — calendar-grid picker backed by `combobox-date`. Use `f.date_field` for a plain `<input type="date">`.
+
+**Time** (`as: :time`) — drum/scroll-wheel picker backed by `combobox-time`.
+
+| Option   | Values          | Default | Description     |
+| -------- | --------------- | ------- | --------------- |
+| `format` | `:h12` / `:h24` | `:h12`  | Clock format    |
+| `step`   | Integer         | `1`     | Minute interval |
+
+Use `f.time_field` for a plain `<input type="time">`.
+
+**Select** (`as: :select`) — read-only listbox backed by `combobox-dropdown`. Accepts `choices:`, `include_blank:`, `prompt:`, `selected:`. Use `f.select` for a native `<select>`.
+
+**Search** (`as: :search`) — editable typeahead backed by `combobox-dropdown`. Accepts `choices:`, `url:`, `clearable:`. Use `f.search_field` for a native `<input type="search">`.
+
+---
+
+## f.collection_field
+
+```erb
+<%= f.collection_field :country, as: :collection_select,
+      collection: Country.all, value_method: :code, text_method: :name %>
+
+<%= f.collection_field :country, as: :grouped_collection_select,
+      collection:         Continent.all,
+      value_method:       :code,
+      text_method:        :name,
+      group_method:       :countries,
+      group_label_method: :name %>
+```
+
+Groups render with `role="group"` and `aria-label` on each group. Use native `f.collection_select` / `f.grouped_collection_select` to skip the field wrapper.
+
+---
+
+## f.choice
+
+Renders a `<fieldset>` / `<legend>` for accessible grouping, or a single checkbox with an explicit label.
+
+```erb
+<%# Single checkbox %>
+<%= f.choice :agree, as: :check_box, required: true, hint: "You must accept the terms." %>
+
+<%# Radio group %>
+<%= f.choice :plan, as: :radio,
+      collection: Plan.all, value_method: :id, text_method: :name %>
+
+<%# Checkbox group %>
+<%= f.choice :roles, as: :check_box,
+      collection: Role.all, value_method: :id, text_method: :name %>
+```
+
+**Collection-only options:**
+
+| Option    | Values                                                              | Default    | Description                           |
+| --------- | ------------------------------------------------------------------- | ---------- | ------------------------------------- |
+| `type`    | `:default` \| `:button` \| `:card`                                  | `:default` | Input/label presentation style        |
+| `variant` | `:default` \| `:success` \| `:destructive` \| `:warning` \| `:info` | `:default` | Accent color for selected state       |
+| `layout`  | `:stacked` \| `:inline`                                             | `:inline`  | Stack cards vertically or wrap inline |
+
+**Card / button behaviour:**
+
+- **Checkbox card** — input visible on right; card border changes on check via `has-[:checked]:`
+- **Radio card** — input hidden (`hidden peer`); entire card is the clickable area via `peer-checked:`
+- **Radio button** — input hidden (`hidden peer`); inline pill style via `peer-checked:`
+
+---
+
+## Rendered HTML Structure
+
+### Full field (Level 2)
+
+```html
+<div>
+  <label for="user_email" id="user_email_label">E-mail</label>
+  <input
+    id="user_email"
+    type="email"
+    aria-describedby="user_email_hint"
+    required
+    aria-required="true"
+  />
+  <p id="user_email_hint">We'll never share your email.</p>
+  <p id="user_email_error" role="alert">can't be blank</p>
+</div>
+```
+
+### Floating label field
+
+```html
+<div>
+  <div>
+    <input id="user_email" placeholder=" " />
+    <label for="user_email" id="user_email_label">Email</label>
+  </div>
+</div>
+```
+
+### Choice fieldset
+
+```html
+<fieldset aria-describedby="user_plan_hint">
+  <legend>Plan <span aria-hidden="true">*</span></legend>
+  <div>
+    <p id="user_plan_hint">Choose the plan that fits your needs.</p>
+    <label
+      ><input type="radio" name="user[plan]" value="1" aria-required="true" />
+      Basic</label
+    >
+    <label
+      ><input type="radio" name="user[plan]" value="2" aria-required="true" />
+      Pro</label
+    >
+  </div>
+</fieldset>
+```
+
+---
+
+## ARIA
+
+Every full-field helper automatically:
+
+- Links `<label for="…">` to the input `id` (or `<fieldset>` / `<legend>` for collections)
+- Adds `aria-describedby` pointing to hint and/or error elements when present
+- Sets `aria-invalid="true"` when the model has errors for the attribute
+- Renders errors as `<p role="alert">` for screen reader announcement
+- Adds `required` + `aria-required="true"` when `required: true`; collection fields set `aria-required="true"` on each individual input (not the `<fieldset>`)
+- Renders a required mark (`*`, `aria-hidden="true"`) in the `<label>` or `<legend>`

data/docs/component/icon.md

@@ -0,0 +1,44 @@
+# Icon
+
+Rails helper for rendering a named icon from the active theme's icon registry.
+
+## Helper
+
+### `sp_icon`
+
+```erb
+<%= sp_icon name: "check" %>
+<%= sp_icon name: "spinner", aria: { label: "Loading" }, role: "img" %>
+<%= sp_icon name: "unknown-icon" %>
+```
+
+| Option           | Default    | Description                                 |
+| ---------------- | ---------- | ------------------------------------------- |
+| `name`           | (required) | Icon name — looked up in the theme registry |
+| `**html_options` | —          | Forwarded to the root element               |
+
+---
+
+## Rendered HTML Structure
+
+### Registered icon (SVG rendered)
+
+```html
+<svg aria-hidden="true" class="[icon theme classes]">
+  <path d="..." />
+</svg>
+```
+
+### Unregistered name (span fallback)
+
+```html
+<span class="[icon theme classes]"></span>
+```
+
+---
+
+## ARIA
+
+- Icons are **decorative by default** — the theme applies `aria-hidden="true"` so they are invisible to screen readers.
+- For meaningful icons (standalone, no adjacent label), pass `aria: { label: "..." }` and `role: "img"` to override.
+- Button and link icons are rendered internally with `aria-hidden="true"`; callers do not need to set this manually.