stimulus_plumbers 0.4.3 → 0.4.5

data/docs/component/button.md

@@ -0,0 +1,135 @@
+# Button
+
+Rails helpers for rendering themed, accessible buttons and links.
+
+## Helpers
+
+### `sp_button`
+
+```erb
+<%= sp_button "Save" %>
+<%= sp_button(icon_leading: "check") { "Confirm" } %>
+<%= sp_button "Delete", type: :default, variant: :destructive, size: :sm %>
+```
+
+| Option           | Default    | Description                                                                                                       |
+| ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------- |
+| `content`        | `nil`      | Button label — positional arg or block                                                                            |
+| `type`           | `:default` | Visual style — `:default` \| `:outline` \| `:ghost` \| `:fab` \| `:fab_outline` \| `:dashed` \| `:card`           |
+| `variant`        | `:primary` | Color source — `:primary` \| `:secondary` \| `:tertiary` \| `:success` \| `:destructive` \| `:warning` \| `:info` |
+| `size`           | `:md`      | Size — `:xs` \| `:sm` \| `:md` \| `:lg` \| `:xl` (ignored when `type: :card`)                                     |
+| `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                                      |
+| `**html_options` | —          | Forwarded to the `<button>` element                                                                               |
+
+**`type:` — visual style**
+
+| Value          | Appearance                                                                     |
+| -------------- | ------------------------------------------------------------------------------ |
+| `:default`     | Filled — solid background from `variant` color                                 |
+| `:outline`     | Surface background, colored border and text; subtle tint on hover              |
+| `:ghost`       | Transparent, no border; subtle tint on hover                                   |
+| `:fab`         | Floating action button — `rounded-full`, elevated shadow, filled               |
+| `:fab_outline` | Floating action button — `rounded-full`, elevated shadow, fills solid on hover |
+| `:dashed`      | Dashed border, surface background                                              |
+| `:card`        | Full-padding card — `flex-1`, `justify-start`; `size:` ignored                 |
+
+**`variant:` — color source**
+
+| Value          | Color tokens used              |
+| -------------- | ------------------------------ |
+| `:primary`     | `--sp-color-primary-*`         |
+| `:secondary`   | `--sp-color-secondary-*`       |
+| `:tertiary`    | `--sp-color-muted-*` (neutral) |
+| `:success`     | `--sp-color-success-*`         |
+| `:destructive` | `--sp-color-destructive-*`     |
+| `:warning`     | `--sp-color-warning-*`         |
+| `:info`        | `--sp-color-info-*`            |
+
+**Icon values:**
+
+- String or symbol — resolved by name through the active theme's icon registry, rendered via `sp_icon` with `button_icon` theme classes applied
+- Callable (e.g. `-> { tag.span "★" }`) — rendered as-is, no theme applied
+
+### `sp_button_group`
+
+Wraps buttons in a themed container `<div>`.
+
+```erb
+<%= sp_button_group do %>
+  <%= sp_button "Cancel", type: :outline %>
+  <%= sp_button "Save" %>
+<% end %>
+
+<%= sp_button_group(layout: :stacked) do %>
+  ...
+<% end %>
+```
+
+| Option           | Default   | Description                                |
+| ---------------- | --------- | ------------------------------------------ |
+| `layout`         | `:inline` | Layout direction — `:inline` \| `:stacked` |
+| `**html_options` | —         | Forwarded to the wrapper `<div>`           |
+
+---
+
+## Rendered HTML Structure
+
+### Button (action)
+
+Text content is always wrapped in a `<span>`:
+
+```html
+<button type="button" class="[theme classes]"><span>Save</span></button>
+```
+
+### With icons
+
+Icons are rendered **inside** the `<button>`, before or after the label `<span>`:
+
+```html
+<button type="button" class="[theme classes]">
+  <svg aria-hidden="true" class="[button_icon theme classes]">
+    <!-- icon svg -->
+  </svg>
+  <span>Confirm</span>
+</button>
+```
+
+```html
+<button type="button" class="[theme classes]">
+  <span>Next</span>
+  <svg aria-hidden="true" class="[button_icon theme classes]">
+    <!-- icon svg -->
+  </svg>
+</button>
+```
+
+### Icon only
+
+When no text is provided, no `<span>` is rendered. The theme uses `:has(> span)` to detect this and applies `aspect-square` + `px-0`, making the button square (or a circle for `type: :fab` / `:fab_outline`):
+
+```html
+<button type="button" aria-label="Add" class="[theme classes]">
+  <svg aria-hidden="true" class="[button_icon theme classes]">
+    <!-- icon svg -->
+  </svg>
+</button>
+```
+
+### Button group
+
+```html
+<div role="group" class="[button_group theme classes]">
+  <button type="button">Cancel</button>
+  <button type="button">Save</button>
+</div>
+```
+
+---
+
+## ARIA
+
+- `<button>` always has `type="button"` to prevent accidental form submission.
+- Icon-only buttons must supply an accessible label via `aria: { label: "..." }` in `html_options`.
+- For navigation actions (links), use `sp_link` instead — it renders an `<a>` element.

data/docs/component/calendar.md

@@ -0,0 +1,223 @@
+# Calendar
+
+Rails helpers for rendering calendar grids. Two rendering modes are supported:
+
+- **CSR (Stimulus)** — JS controller renders the month grid client-side; drill-down (year/decade views) driven by `combobox-date`.
+- **SSR (Turbo)** — Server renders each view as a Turbo Frame; controller handles navigation via Turbo Drive.
+
+---
+
+## CSR — Stimulus calendar
+
+### Setup
+
+```ruby
+module ApplicationHelper
+  include StimulusPlumbers::Helpers::CalendarHelper
+end
+```
+
+### Usage
+
+```erb
+<%# Current month (defaults to today) %>
+<%= sp_calendar_month %>
+
+<%# Navigate to a specific month %>
+<%= sp_calendar_month(date: Date.new(2024, 2, 1)) %>
+
+<%# Inside a combobox-date wrapper for drill-down navigation %>
+<div data-controller="combobox-date"
+     data-combobox-date-calendar-month-outlet="[data-controller~='calendar-month']">
+  <%= sp_calendar_month(date: @date) %>
+</div>
+```
+
+| Option           | Description                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------ |
+| `date`           | `Date` — sets `year-value`, `month-value` (0-indexed), `day-value` on the controller |
+| `**html_options` | Forwarded to the `calendar-month` controller root element                            |
+
+For the JS controller API (targets, values, keyboard behaviour), see the [JS package docs](../../../stimulus-plumbers/docs/component/calendar.md).
+
+### Rendered HTML structure
+
+`sp_calendar_month` renders a `calendar-month` controller shell. The JS controller populates the day/week grids on connect and on each navigation. Year/decade drill-down views are separate controllers wired by `combobox-date` — see the [JS package docs](../../../stimulus-plumbers/docs/component/calendar.md).
+
+```html
+<!-- sp_calendar_month(date: Date.new(2024, 2, 15)) -->
+<div
+  data-controller="calendar-month"
+  data-calendar-month-year-value="2024"
+  data-calendar-month-month-value="1"
+  data-calendar-month-day-value="15"
+  role="grid"
+>
+  <!-- days-of-week header row (JS-populated) -->
+  <div data-calendar-month-target="daysOfWeek"></div>
+
+  <!-- days-of-month body (JS-populated) -->
+  <div role="rowgroup" data-calendar-month-target="daysOfMonth"></div>
+</div>
+```
+
+---
+
+## SSR — Turbo calendar
+
+### Setup
+
+```ruby
+module ApplicationHelper
+  include StimulusPlumbers::Helpers::CalendarTurboHelper
+end
+```
+
+### Usage
+
+`sp_calendar_turbo` renders all three view frames at once (month visible, year/decade hidden). Each frame is a `<turbo-frame>` targeted by `combobox-date`.
+
+```erb
+<%= sp_calendar_turbo(date: @date, today: @today, selectable: true) %>
+```
+
+Individual view helpers render a single view (used for Turbo Frame responses). They accept the same common options plus extras:
+
+```erb
+<%# Month view (days grid) %>
+<%= sp_calendar_turbo_month(date: @date, today: @today, weekday_format: :narrow) %>
+
+<%# Year view (months grid) %>
+<%= sp_calendar_turbo_year(date: @date, today: @today, month_format: :long) %>
+
+<%# Decade view (years grid) %>
+<%= sp_calendar_turbo_decade(date: @date, today: @today) %>
+```
+
+| Helper                    | Extra option     | Description                                                        |
+| ------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `sp_calendar_turbo_month` | `weekday_format` | `:short` (default) \| `:long` \| `:narrow` — weekday header format |
+| `sp_calendar_turbo_year`  | `month_format`   | `:short` (default) \| `:long` \| `:narrow` — month button format   |
+
+**Common options** (all helpers and `sp_calendar_turbo`):
+
+| Option              | Description                                              |
+| ------------------- | -------------------------------------------------------- |
+| `date`              | `Date` — the month/year being displayed                  |
+| `today`             | `Date` — used to mark today and aria-current             |
+| `selectable`        | `true` renders day cells as `<button>` (month only)      |
+| `selected_date`     | `Date` — marks the selected cell with aria-selected      |
+| `show_other_months` | `true` shows padding days from adjacent months           |
+| `since`             | `Date` — minimum selectable date (disables earlier days) |
+| `till`              | `Date` — maximum selectable date (disables later days)   |
+| `disabled_months`   | Array — month numbers/names to disable in the year view  |
+| `disabled_years`    | Array — years to disable in the decade view              |
+
+### Rendered HTML structure
+
+#### Month view (`sp_calendar_turbo_month`)
+
+```html
+<!-- sp_calendar_turbo_month(date: @date, today: @today, selectable: true) -->
+<div role="grid" data-controller="calendar-month-selector">
+  <!-- weekday column headers -->
+  <div role="row">
+    <span role="columnheader">Su</span>
+    <!-- … -->
+  </div>
+
+  <!-- day cells -->
+  <div role="rowgroup">
+    <div role="row">
+      <!-- selectable: true → <button>; selectable: false → <span> -->
+      <button role="gridcell" tabindex="0" aria-selected="false">
+        <time datetime="2024-02-01">1</time>
+      </button>
+      <!-- … -->
+    </div>
+  </div>
+</div>
+```
+
+#### Year view (`sp_calendar_turbo_year`)
+
+Displays 12 month buttons in a 4-column grid. Used when drilling up from the month view.
+
+```html
+<!-- sp_calendar_turbo_year(date: @date, today: @today) -->
+<div
+  role="grid"
+  aria-label="Year view"
+  data-controller="calendar-year-selector"
+>
+  <div role="rowgroup">
+    <div role="row">
+      <button
+        role="gridcell"
+        data-month="1"
+        aria-current="month"
+        aria-selected="false"
+      >
+        Jan
+      </button>
+      <!-- … 11 more months … -->
+    </div>
+  </div>
+</div>
+```
+
+#### Decade view (`sp_calendar_turbo_decade`)
+
+Displays 10 year buttons in a 4-column grid (plus 2 buffer cells, disabled). Used when drilling up from the year view.
+
+```html
+<!-- sp_calendar_turbo_decade(date: @date, today: @today) -->
+<div
+  role="grid"
+  aria-label="Decade view"
+  data-controller="calendar-decade-selector"
+>
+  <div role="rowgroup">
+    <div role="row">
+      <button
+        role="gridcell"
+        data-year="2020"
+        aria-current="year"
+        aria-selected="false"
+      >
+        2020
+      </button>
+      <!-- … 9 more years … -->
+    </div>
+  </div>
+</div>
+```
+
+#### Full Turbo setup (`sp_calendar_turbo`)
+
+Renders all three frames. Used inside a `combobox-date` controller for drill-down navigation.
+
+```html
+<!-- month view frame — visible by default -->
+<turbo-frame id="calendar-month-frame" data-combobox-date-target="monthView">
+  <!-- sp_calendar_turbo_month output -->
+</turbo-frame>
+
+<!-- year view frame — hidden until drill-up -->
+<turbo-frame
+  id="calendar-year-frame"
+  hidden
+  data-combobox-date-target="yearView"
+>
+  <!-- sp_calendar_turbo_year output -->
+</turbo-frame>
+
+<!-- decade view frame — hidden until drill-up twice -->
+<turbo-frame
+  id="calendar-decade-frame"
+  hidden
+  data-combobox-date-target="decadeView"
+>
+  <!-- sp_calendar_turbo_decade output -->
+</turbo-frame>
+```

data/docs/component/card.md

@@ -0,0 +1,92 @@
+# Card
+
+Rails helper for rendering a themed card with optional icon, title, body, and action slots.
+
+## Helper
+
+### `sp_card`
+
+```erb
+<%# Minimal %>
+<%= sp_card do |card| %>
+  <% card.with_body { "Simple content." } %>
+<% end %>
+
+<%# With title and icon %>
+<%= sp_card(title_tag: :h3) do |card| %>
+  <% card.with_icon("user") %>
+  <% card.with_title("Account") %>
+  <% card.with_body { "Your account is active." } %>
+<% end %>
+
+<%# With action link %>
+<%= sp_card do |card| %>
+  <% card.with_title("Settings") %>
+  <% card.with_action("Manage", url: settings_path) %>
+<% end %>
+
+<%# With action button (no url) %>
+<%= sp_card do |card| %>
+  <% card.with_action("Open") %>
+<% end %>
+```
+
+| Option           | Default     | Description                                                                                                        |
+| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
+| `variant:`       | `:tertiary` | Theme variant — `:primary` \| `:secondary` \| `:tertiary` \| `:success` \| `:destructive` \| `:warning` \| `:info` |
+| `title_tag:`     | `:h2`       | HTML tag used by `with_title`                                                                                      |
+| `**html_options` | —           | Forwarded to the outer `<div>`                                                                                     |
+
+### Slot methods (yielded as `card`)
+
+| Slot method                        | Description                                                                  |
+| ---------------------------------- | ---------------------------------------------------------------------------- |
+| `card.with_icon(name_or_html)`     | Icon before the title — string/symbol resolves via `Icon`; HTML passed as-is |
+| `card.with_title(text)`            | Title text rendered as `title_tag`                                           |
+| `card.with_body { content }`       | Body content — block required                                                |
+| `card.with_action(text, url: nil)` | Action link (`<a>`) when `url:` present; `<button>` otherwise                |
+
+`with_action` raises `ArgumentError` when `url:` is given but no content (text or block).
+
+---
+
+## Rendered HTML Structure
+
+```html
+<div class="[card theme classes]">
+  <!-- header: rendered when icon or title is present -->
+  <div class="[card_header theme classes]">
+    <svg aria-hidden="true" class="[card_icon theme classes]">...</svg>
+    <h2 class="[card_title theme classes]">Account</h2>
+  </div>
+
+  <!-- body -->
+  <div class="[card_body theme classes]">Your account is active.</div>
+
+  <!-- action -->
+  <div class="[card_action theme classes]">
+    <a href="/settings">Manage</a>
+  </div>
+</div>
+```
+
+---
+
+## Theme keys
+
+| Key           | Element                             | Variants                                      |
+| ------------- | ----------------------------------- | --------------------------------------------- |
+| `card`        | Outer `<div>`                       | `variant: :primary\|:secondary\|:tertiary\|…` |
+| `card_header` | Header wrapper `<div>` (icon+title) | —                                             |
+| `card_icon`   | Icon inside the header              | —                                             |
+| `card_title`  | Title element (`h2` etc.)           | —                                             |
+| `card_body`   | Body `<div>`                        | —                                             |
+| `card_action` | Action `<div>`                      | —                                             |
+
+---
+
+## ARIA
+
+- `sp_card` is a layout container — no ARIA roles are added automatically.
+- Supply `role:` or `aria:` via `html_options` when the card plays a semantic role (e.g. `role: "region"`, `aria: { label: "..." }`).
+- For interactive card-style inputs (radio/checkbox), see `f.choice` with `type: :card` in the [form doc](form.md).