stimulus_plumbers 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9de763c041b8b091739e3130ac1b831a6819ca250c1068f91e9bad332892d37b
-  data.tar.gz: fca860e3e80a04d86b381e3c5e6c38ae791f59195b3a776f6e0c07a1a1ee5db7
+  metadata.gz: 76a3529b969c106cec1fef750f3a76a5c05782f31b56e29c8c4640cd105d7dd7
+  data.tar.gz: 118813bf270d4eed2901da381d4effa1b663a5558e9c97b6041850ddeb63e572
 SHA512:
-  metadata.gz: f279e071f01f01b98b097bb73f906f2b12c7e48bae08af840a25f1324be412b9e120799d9c384c025c7bcda9aba07c088a45efd829ed8de2cd5ac6d4f097fefd
-  data.tar.gz: 12c31f2d9a804ddadee35f241806f1301f9211f3fa9ab2d2abe03d98b42d7ea1e92ef39f00a739d2fc7f58348efb52194a8ccba099e15ce38786d9cc16028327
+  metadata.gz: fccd6c0b45374752edd4583acb07d099668dcbdf3e745165775e86bd2b19603680f55b6641c37dbebe529b317772eceba6e1dc47bcc8b2637ae574009f6bc2b6
+  data.tar.gz: e7fe95f7e5f38a551a95cd27ac69466a73602603b6eac243e8469d59ea20e0f96cd9fcad8189742555ac6ba72f071ab92eadc2a9243e686258f6473d12416559

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [conventional commits](https://www.conventionalcommits.org/) for commit guidelines.
 
+---
+## [0.4.4](https://github.com/ryancyq/stimulus-plumbers/compare/stimulus-plumbers-rails/v0.4.3..stimulus-plumbers-rails/v0.4.4) - 2026-06-30
+
+### Dependencies
+
+- update npm package dist to have both es + umd + source map - ([64ec309](https://github.com/ryancyq/stimulus-plumbers/commit/64ec309ca171584d1604e4e7d3d3533878ebed7a)) - Ryan Chang
+
 ---
 ## [0.4.3](https://github.com/ryancyq/stimulus-plumbers/compare/stimulus-plumbers-rails/v0.4.2..stimulus-plumbers-rails/v0.4.3) - 2026-06-30
 

data/docs/architecture.md

@@ -0,0 +1,33 @@
+# Rails Package Architecture
+
+## Schema Ranges Convention
+
+Validation ranges for theme schema params live under `lib/stimulus_plumbers/themes/schema/`.
+
+**Where ranges live — the branching rule:**
+
+- If a component branches on the values internally (e.g. `when *FLOATING_TYPES`), the component owns the constant (`Form::Field::FLOATING_TYPES`). The schema references it directly — no alias.
+- If the component only passes the value through to the theme, the schema owns the range (e.g. `Schema::Button::Ranges::TYPE`).
+
+**Namespace rules:**
+
+**Namespaces:**
+
+- `Schema::Ranges` — cross-cutting constants (e.g. `BOOL`)
+- `Schema::<Component>::Ranges` — per-component constants
+- `Schema::Link::Ranges` — link-specific; uses `:default` as base instead of `:primary`
+- `Schema::Form::<Input>::Ranges` — per-input-type constants
+- `Schema::Form::Ranges` — form-level ranges (`LAYOUT`, `VARIANT`)
+
+**Guidelines:**
+
+- **No local aliases** — never re-export another module's constant inside a `Ranges` module.
+- **Remove unused constants** — don't keep range constants with no call sites in `schema.rb`.
+
+## Icon-Only Detection Contract (Button + Link)
+
+`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.
+
+**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/avatar.md

@@ -0,0 +1,84 @@
+# Avatar
+
+Rails helper for rendering a user avatar — image, initials, or fallback silhouette.
+
+## Helper
+
+### `sp_avatar`
+
+```erb
+<%# Image from URL %>
+<%= sp_avatar url: user.avatar_url, name: user.name %>
+
+<%# Initials (SVG text) %>
+<%= sp_avatar initials: "RC", name: "Ryan Chang" %>
+
+<%# Named variant + size %>
+<%= sp_avatar initials: "AB", name: "Alice B", variant: :purple, size: :lg %>
+
+<%# Auto-selected variant (hashed from name) %>
+<%= sp_avatar name: "Ryan Chang" %>
+
+<%# Custom content block %>
+<%= sp_avatar(name: "Ryan") { image_tag "custom.png" } %>
+```
+
+| Option           | Default | Description                                                                                |
+| ---------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `name`           | `nil`   | Used for `aria-label` and auto-variant selection                                           |
+| `initials`       | `nil`   | Renders an SVG with the initials text; used when no `url` or block is given                |
+| `url`            | `nil`   | Image source; renders `<img>` with `alt="[name]'s avatar"` and `onerror` fallback          |
+| `variant`        | `nil`   | Color variant for the avatar background — auto-selected from theme range if omitted        |
+| `size`           | `:md`   | Size — values defined by the active theme (e.g. `:xs` \| `:sm` \| `:md` \| `:lg` \| `:xl`) |
+| `**html_options` | —       | Forwarded to the `<span>` wrapper                                                          |
+
+**Render modes (in priority order):**
+
+| Condition            | Output                         |
+| -------------------- | ------------------------------ |
+| Block given          | Custom content inside `<span>` |
+| `url:` provided      | `<img>` inside `<span>`        |
+| `initials:` provided | SVG with initials text         |
+| None of the above    | SVG fallback silhouette        |
+
+---
+
+## Rendered HTML Structure
+
+```html
+<span role="img" aria-label="Ryan Chang" class="[avatar theme classes]">
+  <!-- image mode -->
+  <img
+    src="[url]"
+    alt="Ryan Chang's avatar"
+    class="[avatar_image theme classes]"
+  />
+
+  <!-- initials mode -->
+  <svg viewBox="0 0 40 40">
+    <text
+      x="50%"
+      y="50%"
+      dy="0.35em"
+      text-anchor="middle"
+      fill="currentColor"
+      font-size="20"
+    >
+      RC
+    </text>
+  </svg>
+
+  <!-- fallback mode -->
+  <svg viewBox="0 0 40 40">
+    <path fill="currentColor" d="..." />
+  </svg>
+</span>
+```
+
+---
+
+## ARIA
+
+- Always renders `role="img"` with `aria-label` set to `name` (when provided).
+- Image `alt` is set to `"[name]'s avatar"`; for anonymous avatars `alt=""` is used.
+- `onerror` on `<img>` clears the `src` to prevent broken-image icons.

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).