`+`

## Installation & Setup

Current gem version: 0.55.0. See the full getting started guide: https://rapidrails.cc/docs/getting_started

### Quick Start
```ruby
# Gemfile
gem "rapid_rails_ui"
```

```bash
bundle install
bundle exec rails generate rapid_rails_ui:install
```

Want the optional dark-mode toggle widget? It's a separate opt-in generator as of v0.54.0:
```bash
bundle exec rails generate rapid_rails_ui:theme_toggle
```

## Documentation

Full documentation with interactive examples, API reference, and best practices: https://rapidrails.cc/docs

### Getting Started
- [Installation](https://rapidrails.cc/docs/getting_started/installation)
- [Dark Mode](https://rapidrails.cc/docs/getting_started/dark_mode)
- [Colors & Theming](https://rapidrails.cc/docs/getting_started/colors)
- [Customization](https://rapidrails.cc/docs/getting_started/customization)

### Advanced Guides
- [Turbo Integration](https://rapidrails.cc/docs/guides/turbo-integration)
- [Form Builder API](https://rapidrails.cc/docs/guides/form-builder)
- [Stimulus Controller Patterns](https://rapidrails.cc/docs/guides/stimulus-patterns)

## Source Code & Contributing

GitHub Repository: https://github.com/Rapid-Rails/rapid_rails_ui

**Framework**: Ruby on Rails 7+
**Styling**: Tailwind CSS 3+
**Components**: 37 production-ready ViewComponents
**License**: MIT

- [Contributing Guide](https://github.com/Rapid-Rails/rapid_rails_ui/blob/main/CONTRIBUTING.md)
- [Changelog](https://github.com/Rapid-Rails/rapid_rails_ui/blob/main/CHANGELOG.md)

## Component Styling API for Design Customization

When users request design improvements, use component params FIRST. Every RUI component accepts `class:` for Tailwind overrides (processed by TailwindMerge), but prefer built-in params when available.

### Shared Styling Pattern

Most RUI components accept these params:

**color:** — Semantic: :primary, :secondary, :tertiary, :accent, :success, :danger, :warning, :info, :muted, :default. Tailwind: :red, :blue, :green, :amber, :indigo, :violet, :pink, :zinc, :gray, :slate, :rose, :orange, :emerald, :teal, :cyan, :sky, :purple, :fuchsia.

**variant:** — Component-specific. Common patterns: :solid/:outline/:ghost/:soft/:link (button, badge), :default/:filled/:outline (input, textarea).

**size:** — :xs, :sm, :base, :lg, :xl. Some components extend further (badge to :xl2, text to :xl6, avatar to :xl6).

**shape:** — :square, :rounded (default), :pill (fully rounded), :circle (badge/avatar only).

**class:** — Tailwind CSS classes merged with defaults via TailwindMerge. Use for spacing/shadows/layout/effects. Do NOT use for colors/backgrounds — use color:/variant: params instead.

### Design Rules for Code Generators

1. **Always use RUI components** — never replace with plain HTML for styling.
2. **Params over class:** — `rui_button("Go", size: :lg, color: :indigo)` not `rui_button("Go", class: "px-6 bg-indigo-600")`.
3. **class: for layout only** — spacing, shadows, borders, effects. Not colors or sizing.
4. **Use rui_card for card/panel layouts** — it exists (`rui_card`, Starter tier). Never hand-roll a `<div class="bg-white ... rounded-xl shadow-sm p-6">` card wrapper.
5. **Full API reference** — https://rapidrails.cc/docs and each component's own USAGE.md/`llms-full.txt` section.

### WRONG/RIGHT Examples

```erb
<%# WRONG: Replacing RUI component with plain HTML for styling %>
<button class="px-6 py-3 bg-indigo-600 text-white rounded-lg hover:bg-indigo-700">Go</button>

<%# RIGHT: Use component params %>
<%= rui_button("Go", size: :lg, color: :indigo, shape: :rounded) %>
```

```erb
<%# WRONG: Hand-rolled card div — rui_card already exists, don't reinvent it %>
<div class="bg-white dark:bg-zinc-800 rounded-xl shadow-sm p-6">
  <%= rui_text("Stats", as: :h3, weight: :semibold) %>
</div>

<%# RIGHT %>
<%= rui_card(title: "Stats", description: "Key metrics for this period.", icon: "bar-chart") %>
```

# Component Usage Guides

Full USAGE.md content for every component, verbatim from the gem source.

---

## Accordion (`rui_accordion`)

# Accordion Component

The Accordion component creates collapsible content sections, perfect for FAQs, settings panels, navigation menus, and organizing content into expandable sections.

## Basic Usage

```erb
<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "What is RapidRailsUI?") do %>
    RapidRailsUI is a ViewComponent-based UI library for Rails with full Tailwind CSS integration.
  <% end %>
  <% accordion.with_item(title: "How do I install it?") do %>
    Add the gem to your Gemfile and run the install generator.
  <% end %>
  <% accordion.with_item(title: "Is it free?") do %>
    RapidRailsUI requires a commercial license for production use.
  <% end %>
<% end %>
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `color` | Symbol | `:zinc` | Color theme (`:zinc`, `:gray`, `:slate`, `:primary`, `:secondary`, `:success`, `:warning`, `:danger`, `:info`) |
| `size` | Symbol | `:base` | Size (`:xs`, `:sm`, `:base`, `:lg`, `:xl`) |
| `variant` | Symbol | `:default` | Visual style (`:default`, `:bordered`, `:separated`, `:flush`, `:ghost`) |
| `shape` | Symbol | `:rounded` | Border radius (`:none`, `:rounded`, `:square`, `:pill`) |
| `spacing` | Symbol | `:base` | Space between items (`:none`, `:xs`, `:sm`, `:base`, `:lg`, `:xl`) - used when `dividers: false` or `variant: :separated` |
| `exclusive` | Boolean | `true` | Only allow one item open at a time |
| `single_open` | Boolean | — | Alias for `exclusive:` — provided for readability |
| `animate` | Boolean | `true` | Enable smooth expand/collapse animations |
| `expand_icon` | Symbol | `:chevron_down` | Icon for collapsed state |
| `collapse_icon` | Symbol | `nil` | Icon for expanded state (if nil, expand_icon rotates 180°) |
| `show_chevron` | Boolean | `true` | Show/hide the expand/collapse icon |
| `chevron_position` | Symbol | `:right` | Position of chevron (`:left`, `:right`) |
| `dividers` | Boolean | `true` | Show dividers between items |

### Item Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `title` | String | **required** | Header text for the item |
| `icon` | Symbol | `nil` | Lucide icon name for the header (leading) |
| `icon_trailing` | Symbol | `nil` | Lucide icon name for trailing position |
| `subtitle` | String | `nil` | Secondary text below the title |
| `expanded` | Boolean | `false` | Start with item expanded |
| `disabled` | Boolean | `false` | Disable the item (cannot be toggled) |
| `collapsible` | Boolean | `true` | Whether item can be collapsed (false = always open) |
| `src` | String | `nil` | URL for Turbo Frame lazy loading |
| `loading` | Symbol | `:lazy` | Loading strategy for Turbo Frame (`:lazy`, `:eager`) |

## Variants

### Default
Standard accordion with borders and background.

```erb
<%= rui_accordion(variant: :default) do |accordion| %>
  <% accordion.with_item(title: "Section 1") { "Content 1" } %>
  <% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```

### Bordered
Thicker borders for more visual emphasis.

```erb
<%= rui_accordion(variant: :bordered) do |accordion| %>
  <% accordion.with_item(title: "Section 1") { "Content 1" } %>
  <% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```

### Separated
Card-style items with shadows and spacing.

```erb
<%= rui_accordion(variant: :separated, spacing: :lg) do |accordion| %>
  <% accordion.with_item(title: "Card 1") { "Content 1" } %>
  <% accordion.with_item(title: "Card 2") { "Content 2" } %>
<% end %>
```

### Flush
Minimal style with only bottom borders, no rounded corners.

```erb
<%= rui_accordion(variant: :flush) do |accordion| %>
  <% accordion.with_item(title: "Section 1") { "Content 1" } %>
  <% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```

### Ghost
No borders or background, just the content.

```erb
<%= rui_accordion(variant: :ghost) do |accordion| %>
  <% accordion.with_item(title: "Section 1") { "Content 1" } %>
  <% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```

## Colors

### Semantic Colors

```erb
<%# Primary - Blue %>
<%= rui_accordion(color: :primary) do |accordion| %>
  <% accordion.with_item(title: "Primary Section") { "Content" } %>
<% end %>

<%# Success - Green %>
<%= rui_accordion(color: :success) do |accordion| %>
  <% accordion.with_item(title: "Success Section") { "Content" } %>
<% end %>

<%# Warning - Amber %>
<%= rui_accordion(color: :warning) do |accordion| %>
  <% accordion.with_item(title: "Warning Section") { "Content" } %>
<% end %>

<%# Danger - Red %>
<%= rui_accordion(color: :danger) do |accordion| %>
  <% accordion.with_item(title: "Danger Section") { "Content" } %>
<% end %>

<%# Info - Sky %>
<%= rui_accordion(color: :info) do |accordion| %>
  <% accordion.with_item(title: "Info Section") { "Content" } %>
<% end %>
```

### Neutral Colors

```erb
<%= rui_accordion(color: :zinc) do |accordion| %>
  <% accordion.with_item(title: "Zinc Section") { "Content" } %>
<% end %>

<%= rui_accordion(color: :gray) do |accordion| %>
  <% accordion.with_item(title: "Gray Section") { "Content" } %>
<% end %>

<%= rui_accordion(color: :slate) do |accordion| %>
  <% accordion.with_item(title: "Slate Section") { "Content" } %>
<% end %>
```

## Sizes

```erb
<%# Extra Small %>
<%= rui_accordion(size: :xs) do |accordion| %>
  <% accordion.with_item(title: "XS Item") { "Compact content" } %>
<% end %>

<%# Small %>
<%= rui_accordion(size: :sm) do |accordion| %>
  <% accordion.with_item(title: "Small Item") { "Small content" } %>
<% end %>

<%# Base (Default) %>
<%= rui_accordion(size: :base) do |accordion| %>
  <% accordion.with_item(title: "Base Item") { "Standard content" } %>
<% end %>

<%# Large %>
<%= rui_accordion(size: :lg) do |accordion| %>
  <% accordion.with_item(title: "Large Item") { "Larger content" } %>
<% end %>

<%# Extra Large %>
<%= rui_accordion(size: :xl) do |accordion| %>
  <% accordion.with_item(title: "XL Item") { "Extra large content" } %>
<% end %>
```

## Icons

Add icons to accordion headers for better visual context.

```erb
<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Profile Settings", icon: :user) do %>
    Manage your profile information, avatar, and display name.
  <% end %>
  <% accordion.with_item(title: "Security", icon: :shield) do %>
    Update your password and enable two-factor authentication.
  <% end %>
  <% accordion.with_item(title: "Notifications", icon: :bell) do %>
    Configure email and push notification preferences.
  <% end %>
  <% accordion.with_item(title: "Billing", icon: :credit_card) do %>
    View invoices and manage payment methods.
  <% end %>
<% end %>
```

### Trailing Icons

Add icons after the title for status indicators or badges.

```erb
<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Pro Feature", icon: :star, icon_trailing: :lock) do %>
    Upgrade to Pro to unlock this feature.
  <% end %>
  <% accordion.with_item(title: "Completed", icon: :check_circle, icon_trailing: :badge_check) do %>
    This task has been completed.
  <% end %>
<% end %>
```

## Subtitles

Add secondary text below the title for additional context.

```erb
<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Account Settings", subtitle: "Manage your profile and preferences", icon: :user) do %>
    Configure your account details, change email, and update your password.
  <% end %>
  <% accordion.with_item(title: "Billing", subtitle: "View invoices and payment methods", icon: :credit_card) do %>
    Manage your subscription, update payment details, and download invoices.
  <% end %>
  <% accordion.with_item(title: "Notifications", subtitle: "Control what alerts you receive", icon: :bell) do %>
    Choose which notifications to receive via email, SMS, or push.
  <% end %>
<% end %>
```

## Chevron Position

Control where the expand/collapse indicator appears.

### Right Position (Default)

```erb
<%= rui_accordion(chevron_position: :right) do |accordion| %>
  <% accordion.with_item(title: "Chevron on Right") { "Content" } %>
<% end %>
```

### Left Position

```erb
<%= rui_accordion(chevron_position: :left) do |accordion| %>
  <% accordion.with_item(title: "Chevron on Left") { "Content" } %>
<% end %>
```

## Custom Expand/Collapse Icons

Use custom icons instead of the default chevron.

### Plus/Minus Style

```erb
<%= rui_accordion(expand_icon: :plus, collapse_icon: :minus) do |accordion| %>
  <% accordion.with_item(title: "Click to Expand") { "Content revealed!" } %>
<% end %>
```

### Circle Plus/Minus Style

```erb
<%= rui_accordion(expand_icon: :circle_plus, collapse_icon: :circle_minus) do |accordion| %>
  <% accordion.with_item(title: "Toggle Content") { "Hidden content here." } %>
<% end %>
```

### Rotating Icon (Default Behavior)

When `collapse_icon` is not set, the `expand_icon` rotates 180° when expanded.

```erb
<%= rui_accordion(expand_icon: :chevron_down) do |accordion| %>
  <% accordion.with_item(title: "Rotating Chevron") { "Content" } %>
<% end %>
```

## Hide Chevron

Remove the expand/collapse icon entirely.

```erb
<%= rui_accordion(show_chevron: false) do |accordion| %>
  <% accordion.with_item(title: "No Chevron", icon: :info) do %>
    Click anywhere on the header to toggle.
  <% end %>
<% end %>
```

## Dividers

Control the visual separator between items.

### With Dividers (Default)

```erb
<%= rui_accordion(dividers: true) do |accordion| %>
  <% accordion.with_item(title: "Section 1") { "Content 1" } %>
  <% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```

### Without Dividers (Uses Spacing)

```erb
<%= rui_accordion(dividers: false, spacing: :sm) do |accordion| %>
  <% accordion.with_item(title: "Section 1") { "Content 1" } %>
  <% accordion.with_item(title: "Section 2") { "Content 2" } %>
<% end %>
```

## Always-Open Items (Non-Collapsible)

Create items that cannot be collapsed - useful for static headers or pinned content.

```erb
<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Important Notice", collapsible: false, icon: :alert_circle) do %>
    This section is always visible and cannot be collapsed.
  <% end %>
  <% accordion.with_item(title: "Collapsible Section") do %>
    This section can be toggled open and closed.
  <% end %>
<% end %>
```

## Turbo Frame Support (Lazy Loading)

Load content on-demand using Turbo Frames for better performance.

```erb
<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Comments", src: comments_path) do %>
    <%# Loading placeholder is shown automatically %>
  <% end %>
  <% accordion.with_item(title: "Activity Log", src: activity_log_path, loading: :lazy) do %>
    <%# Content loads when expanded %>
  <% end %>
  <% accordion.with_item(title: "Preloaded Data", src: data_path, loading: :eager, expanded: true) do %>
    <%# Content loads immediately because expanded: true %>
  <% end %>
<% end %>
```

### Server-Side Setup

```ruby
# app/controllers/comments_controller.rb
def index
  @comments = @post.comments
  render partial: "comments/list", locals: { comments: @comments }
end
```

```erb
<%# app/views/comments/_list.html.erb %>
<turbo-frame id="accordion-frame-...">
  <ul class="space-y-2">
    <% comments.each do |comment| %>
      <li><%= comment.body %></li>
    <% end %>
  </ul>
</turbo-frame>
```

## Expanded State

Set items to be expanded by default.

```erb
<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Expanded by Default", expanded: true) do %>
    This section is open when the page loads.
  <% end %>
  <% accordion.with_item(title: "Collapsed") do %>
    This section starts closed.
  <% end %>
<% end %>
```

## Multiple Open Items

Allow multiple items to be open simultaneously by setting `exclusive: false`.

```erb
<%= rui_accordion(exclusive: false) do |accordion| %>
  <% accordion.with_item(title: "Section 1", expanded: true) do %>
    This can be open...
  <% end %>
  <% accordion.with_item(title: "Section 2", expanded: true) do %>
    ...at the same time as this!
  <% end %>
  <% accordion.with_item(title: "Section 3") do %>
    And this one too.
  <% end %>
<% end %>
```

## Disabled Items

Prevent specific items from being toggled.

```erb
<%= rui_accordion do |accordion| %>
  <% accordion.with_item(title: "Active Section") do %>
    This section can be toggled.
  <% end %>
  <% accordion.with_item(title: "Disabled Section", disabled: true) do %>
    This section cannot be opened.
  <% end %>
<% end %>
```

## Without Animation

Disable smooth transitions for instant expand/collapse.

```erb
<%= rui_accordion(animate: false) do |accordion| %>
  <% accordion.with_item(title: "Instant Toggle") do %>
    No animation delay.
  <% end %>
<% end %>
```

## Shapes

### Rounded (Default)

```erb
<%= rui_accordion(shape: :rounded) do |accordion| %>
  <% accordion.with_item(title: "Rounded Corners") { "Content" } %>
<% end %>
```

### Square

```erb
<%= rui_accordion(shape: :square) do |accordion| %>
  <% accordion.with_item(title: "Sharp Corners") { "Content" } %>
<% end %>
```

### Pill

```erb
<%= rui_accordion(shape: :pill) do |accordion| %>
  <% accordion.with_item(title: "Extra Rounded") { "Content" } %>
<% end %>
```

## Spacing

Control the gap between accordion items (used when `dividers: false` or `variant: :separated`).

```erb
<%# No spacing %>
<%= rui_accordion(spacing: :none, dividers: false) do |accordion| %>
  <% accordion.with_item(title: "Item 1") { "Content" } %>
  <% accordion.with_item(title: "Item 2") { "Content" } %>
<% end %>

<%# Large spacing %>
<%= rui_accordion(spacing: :lg, dividers: false) do |accordion| %>
  <% accordion.with_item(title: "Item 1") { "Content" } %>
  <% accordion.with_item(title: "Item 2") { "Content" } %>
<% end %>
```

## Real-World Examples

### FAQ Section

```erb
<div class="max-w-2xl mx-auto">
  <%= rui_text("Frequently Asked Questions", element: :h2, size: :"2xl", weight: :bold, class: "mb-6") %>

<%= rui_accordion(color: :primary, variant: :separated, spacing: :base) do |accordion| %>
    <% accordion.with_item(title: "How do I get started?", icon: :rocket, subtitle: "Quick setup guide") do %>
      <%= rui_text("Getting started is easy:", class: "mb-2") %>
      <ol class="list-decimal list-inside space-y-1">
        <li><%= rui_text("Add the gem to your Gemfile") %></li>
        <li><%= rui_text("Run bundle install") %></li>
        <li><%= rui_text("Run rails g rapid_rails_ui:install") %></li>
        <li><%= rui_text("Start using components in your views") %></li>
      </ol>
    <% end %>

<% accordion.with_item(title: "What Rails versions are supported?", icon: :layers, subtitle: "Compatibility info") do %>
      <%= rui_text("RapidRailsUI supports Rails 7.0 and above, with full compatibility for Rails 7.1 and 7.2. We recommend using the latest stable Rails release.") %>
    <% end %>

<% accordion.with_item(title: "Is Tailwind CSS required?", icon: :palette, subtitle: "Dependencies") do %>
      <%= rui_text("Yes, RapidRailsUI is built on Tailwind CSS v4. The install generator will set up Tailwind automatically if it's not already configured.") %>
    <% end %>

<% accordion.with_item(title: "Can I customize the components?", icon: :settings, subtitle: "Customization options") do %>
      <%= rui_text("Absolutely! You can customize components in several ways:", class: "mb-2") %>
      <ul class="list-disc list-inside space-y-1">
        <li><%= rui_text("Pass custom CSS classes via the class: option") %></li>
        <li><%= rui_text("Override default colors in your Tailwind config") %></li>
        <li><%= rui_text("Use the configuration initializer for global defaults") %></li>
      </ul>
    <% end %>
  <% end %>
</div>
```

### Settings Panel

```erb
<%= rui_accordion(exclusive: false, variant: :bordered) do |accordion| %>
  <% accordion.with_item(title: "Account Settings", subtitle: "Manage your profile", icon: :user, expanded: true) do %>
    <div class="space-y-4">
      <div>
        <%= rui_text("Display Name", size: :sm, weight: :medium) %>
        <input type="text" class="mt-1 w-full rounded border px-3 py-2" value="John Doe">
      </div>
      <div>
        <%= rui_text("Email", size: :sm, weight: :medium) %>
        <input type="email" class="mt-1 w-full rounded border px-3 py-2" value="john@example.com">
      </div>
    </div>
  <% end %>

<% accordion.with_item(title: "Privacy", subtitle: "Control your visibility", icon: :eye_off) do %>
    <div class="space-y-3">
      <label class="flex items-center gap-2">
        <input type="checkbox" checked>
        <%= rui_text("Make profile public", size: :sm) %>
      </label>
      <label class="flex items-center gap-2">
        <input type="checkbox">
        <%= rui_text("Show online status", size: :sm) %>
      </label>
    </div>
  <% end %>

<% accordion.with_item(title: "Notifications", subtitle: "Email and push alerts", icon: :bell) do %>
    <div class="space-y-3">
      <label class="flex items-center gap-2">
        <input type="checkbox" checked>
        <%= rui_text("Email notifications", size: :sm) %>
      </label>
      <label class="flex items-center gap-2">
        <input type="checkbox" checked>
        <%= rui_text("Push notifications", size: :sm) %>
      </label>
    </div>
  <% end %>
<% end %>
```

### Product Details with Lazy Loading

```erb
<%= rui_accordion(variant: :flush, color: :zinc) do |accordion| %>
  <% accordion.with_item(title: "Description", expanded: true) do %>
    <%= rui_text("Premium quality product crafted with attention to detail. Made from sustainable materials and designed to last.") %>
  <% end %>

<% accordion.with_item(title: "Specifications") do %>
    <dl class="grid grid-cols-2 gap-2 text-sm">
      <dt class="font-medium">Material</dt>
      <dd>100% Organic Cotton</dd>
      <dt class="font-medium">Weight</dt>
      <dd>180 GSM</dd>
      <dt class="font-medium">Care</dt>
      <dd>Machine wash cold</dd>
    </dl>
  <% end %>

<% accordion.with_item(title: "Shipping & Returns") do %>
    <ul class="space-y-2">
      <li><%= rui_text("Free shipping on orders over $50") %></li>
      <li><%= rui_text("30-day return policy") %></li>
      <li><%= rui_text("Ships within 2-3 business days") %></li>
    </ul>
  <% end %>

<%# Lazy load reviews %>
  <% accordion.with_item(title: "Reviews (24)", src: product_reviews_path(@product), icon: :star) do %>
    <%# Loading spinner shown automatically %>
  <% end %>
<% end %>
```

### Navigation Menu with Non-Collapsible Header

```erb
<nav class="w-64">
  <%= rui_accordion(variant: :ghost, spacing: :xs, exclusive: false, chevron_position: :left) do |accordion| %>
    <%# Always visible header %>
    <% accordion.with_item(title: "Quick Links", icon: :bookmark, collapsible: false) do %>
      <div class="space-y-1 pl-6">
        <%= rui_link("Home", href: "/", size: :sm, variant: :nav) %>
        <%= rui_link("Search", href: "/search", size: :sm, variant: :nav) %>
      </div>
    <% end %>

<% accordion.with_item(title: "Dashboard", icon: :layout_dashboard, expanded: true) do %>
      <div class="space-y-1 pl-6">
        <%= rui_link("Overview", href: "/dashboard", size: :sm, variant: :nav) %>
        <%= rui_link("Analytics", href: "/dashboard/analytics", size: :sm, variant: :nav) %>
        <%= rui_link("Reports", href: "/dashboard/reports", size: :sm, variant: :nav) %>
      </div>
    <% end %>

<% accordion.with_item(title: "Users", icon: :users) do %>
      <div class="space-y-1 pl-6">
        <%= rui_link("All Users", href: "/users", size: :sm, variant: :nav) %>
        <%= rui_link("Add User", href: "/users/new", size: :sm, variant: :nav) %>
        <%= rui_link("Roles", href: "/roles", size: :sm, variant: :nav) %>
      </div>
    <% end %>

<% accordion.with_item(title: "Settings", icon: :settings) do %>
      <div class="space-y-1 pl-6">
        <%= rui_link("General", href: "/settings", size: :sm, variant: :nav) %>
        <%= rui_link("Security", href: "/settings/security", size: :sm, variant: :nav) %>
        <%= rui_link("API Keys", href: "/settings/api", size: :sm, variant: :nav) %>
      </div>
    <% end %>
  <% end %>
</nav>
```

### Team Directory with Avatars

```erb
<%= rui_accordion(variant: :separated, spacing: :sm, exclusive: false) do |accordion| %>
  <% @teams.each do |team| %>
    <% accordion.with_item(
      title: team.name,
      subtitle: "#{team.members.count} members",
      icon: :users
    ) do %>
      <div class="space-y-3">
        <% team.members.each do |member| %>
          <div class="flex items-center gap-3">
            <%= rui_avatar(src: member.avatar_url, alt: member.name, size: :sm) %>
            <div>
              <%= rui_text(member.name, weight: :medium) %>
              <%= rui_text(member.role, size: :sm, color: :muted) %>
            </div>
            <%= rui_badge(member.status, color: member.active? ? :success : :secondary, size: :sm) %>
          </div>
        <% end %>
      </div>
    <% end %>
  <% end %>
<% end %>
```

## Stimulus Controller

The accordion uses a Stimulus controller for interactivity. Make sure to register it:

```javascript
// app/javascript/controllers/index.js
import AccordionController from "rapid_rails_ui/accordion/accordion_controller"
application.register("accordion", AccordionController)
```

### JavaScript API

The controller exposes methods for programmatic control:

```javascript
// Get the controller
const accordion = document.querySelector('[data-controller="accordion"]')
const controller = application.getControllerForElementAndIdentifier(accordion, 'accordion')

// Open item by index
controller.open(0)

// Close item by index
controller.close(0)

// Toggle item by index
controller.toggleItem(1)

// Expand all (only works when exclusive: false)
controller.expandAll()

// Collapse all
controller.collapseAll()
```

### Custom Events

The accordion dispatches events you can listen to:

```javascript
document.addEventListener('accordion:expanded', (event) => {
  console.log('Item expanded:', event.detail.index)
})

document.addEventListener('accordion:collapsed', (event) => {
  console.log('Item collapsed:', event.detail.index)
})
```

## Accessibility

The accordion follows WAI-ARIA best practices:

- Uses `role="region"` for the accordion container
- Header buttons have `aria-expanded` and `aria-controls` attributes
- Content regions have `aria-labelledby` pointing to their headers
- Non-collapsible items use `<div>` instead of `<button>` for semantics
- Disabled items have the `disabled` attribute and reduced opacity
- Focus states are clearly visible with ring styles
- Full keyboard navigation support (Enter/Space to toggle)

## Dark Mode

The accordion fully supports dark mode with appropriate color adjustments for all variants and colors. Colors automatically adapt when the `dark` class is present on `<html>`.

---

## Alert (`rui_alert`)

# Alert Component

Contextual feedback messages for user actions and system notifications.

## Basic Usage

```erb
<%# Positional type argument (recommended) %>
<%= rui_alert(:info) do %>
  This is an informational message.
<% end %>

<%# With title %>
<%= rui_alert(:success, title: "Success!") do %>
  Your changes have been saved.
<% end %>

<%# Keyword argument (also supported) %>
<%= rui_alert(type: :info, title: "Note") do %>
  This works too.
<% end %>
```

**Note:** Both positional and keyword argument styles are supported. The positional style is recommended as it's more concise.

## Alert Types

```erb
<%# Default (gray) %>
<%= rui_alert(:default, title: "Note") do %>
  This is a default alert.
<% end %>

<%# Info (sky blue) %>
<%= rui_alert(:info, title: "Information") do %>
  Here's some helpful information.
<% end %>

<%# Success (green) %>
<%= rui_alert(:success, title: "Success!") do %>
  Operation completed successfully.
<% end %>

<%# Warning (amber) %>
<%= rui_alert(:warning, title: "Warning") do %>
  Please review before proceeding.
<% end %>

<%# Danger (red) %>
<%= rui_alert(:danger, title: "Error") do %>
  Something went wrong.
<% end %>

<%# Primary (indigo) %>
<%= rui_alert(:primary, title: "New Feature") do %>
  Check out our latest update!
<% end %>
```

## Variants

```erb
<%# Solid (filled background) %>
<%= rui_alert(:success, variant: :solid, title: "Solid") do %>
  High contrast alert.
<% end %>

<%# Soft (light background) - default %>
<%= rui_alert(:success, variant: :soft, title: "Soft") do %>
  Subtle background alert.
<% end %>

<%# Outline (border only) %>
<%= rui_alert(:success, variant: :outline, title: "Outline") do %>
  Border-focused alert.
<% end %>
```

## Sizes

```erb
<%= rui_alert(:info, size: :xs) { "Extra small alert" } %>
<%= rui_alert(:info, size: :sm) { "Small alert" } %>
<%= rui_alert(:info, size: :base) { "Base size alert (default)" } %>
<%= rui_alert(:info, size: :lg) { "Large alert" } %>
<%= rui_alert(:info, size: :xl) { "Extra large alert" } %>
```

## Shapes

```erb
<%= rui_alert(:info, shape: :square) { "Square corners" } %>
<%= rui_alert(:info, shape: :rounded) { "Rounded corners (default)" } %>
<%= rui_alert(:info, shape: :pill) { "Pill shape" } %>
```

## Border Accent

```erb
<%# Left border accent %>
<%= rui_alert(:warning, border_position: :left, title: "Warning") do %>
  Left border accent for emphasis.
<% end %>

<%# Top border accent %>
<%= rui_alert(:danger, border_position: :top, title: "Error") do %>
  Top border accent.
<% end %>

<%# Bottom border accent %>
<%= rui_alert(:success, border_position: :bottom, title: "Success") do %>
  Bottom border accent.
<% end %>
```

## Multiple Messages

```erb
<%# Single message %>
<%= rui_alert(:danger, title: "Validation Error", messages: "Email is required") %>

<%# Multiple messages as list %>
<%= rui_alert(:danger, title: "Please fix the following:", messages: [
  "Email is required",
  "Password must be at least 8 characters",
  "Username is already taken"
]) %>
```

## Dismissible Alerts

```erb
<%# With dismiss button %>
<%= rui_alert(:info, dismissible: true, title: "Heads up!") do %>
  Click the X to dismiss this alert.
<% end %>

<%# Auto-dismiss after 5 seconds with progress bar %>
<%= rui_alert(:success, auto_dismiss: true, dismiss_after: 5, title: "Saved!") do %>
  This alert will disappear in 5 seconds.
<% end %>

<%# Auto-dismiss with dismiss button (user can dismiss early) %>
<%= rui_alert(:info, auto_dismiss: true, dismiss_after: 10, dismissible: true) do %>
  Auto-dismisses in 10 seconds, or click X to dismiss now.
<% end %>

<%# Without progress bar %>
<%= rui_alert(:success, auto_dismiss: true, show_progress_bar: false) do %>
  Auto-dismisses without visual progress indicator.
<% end %>
```

**Features:**
- Visual **progress bar** shows time remaining (enabled by default with `auto_dismiss`)
- Countdown **pauses on hover** so users can read the message
- Smooth **enter/exit animations** (fade + scale)

## Custom Icon

```erb
<%# Replace default icon %>
<%= rui_alert(:info, title: "Notification") do |alert| %>
  <% alert.with_icon(:bell) %>
  You have new messages.
<% end %>

<%# Hide icon entirely %>
<%= rui_alert(:warning, show_icon: false, title: "No Icon") do %>
  This alert has no icon.
<% end %>
```

## Action Buttons

```erb
<%= rui_alert(:info, title: "Update Available") do |alert| %>
  <% alert.with_action("Update Now", color: :primary, variant: :solid) %>
  <% alert.with_action("Later", color: :zinc) %>
  A new version is available.
<% end %>

<%# Danger alert with actions %>
<%= rui_alert(:danger, title: "Delete Account?") do |alert| %>
  <% alert.with_action("Delete", color: :danger, variant: :solid) %>
  <% alert.with_action("Cancel") %>
  This action cannot be undone.
<% end %>
```

## Undo Action (SaaS Pattern)

Built-in undo support for destructive operations (like Gmail, Slack, etc.):

```erb
<%# Basic undo - automatically adds Undo button %>
<%= rui_alert(:warning,
      title: "Post Deleted",
      undo_url: undo_post_path(@post),
      auto_dismiss: true,
      dismiss_after: 10) do %>
  Your post has been moved to trash.
<% end %>

<%# With custom HTTP method %>
<%= rui_alert(:warning,
      title: "Comment Removed",
      undo_url: restore_comment_path(@comment),
      undo_method: :patch) do %>
  Click Undo to restore.
<% end %>
```

The undo button:
- Automatically appears when `undo_url` is set
- Makes a Turbo-compatible request to the undo URL
- Dismisses the alert after undo is clicked
- Dispatches `alert:undo` JavaScript event

**Controller Example:**

```ruby
# posts_controller.rb
def destroy
  @post.update!(deleted_at: Time.current)
  flash[:warning] = "Post deleted."
  redirect_to posts_path
end

def undo_destroy
  @post.update!(deleted_at: nil)
  respond_to do |format|
    format.turbo_stream {
      render turbo_stream: turbo_stream.prepend("posts", @post)
    }
    format.html { redirect_to @post, notice: "Post restored!" }
  end
end
```

## Clickable Alerts

Make alerts clickable for notifications that navigate somewhere:

```erb
<%# Click anywhere to navigate (uses Turbo) %>
<%= rui_alert(:info,
      title: "New Comment",
      href: post_path(@post, anchor: "comments")) do %>
  John replied to your post. Click to view.
<% end %>

<%# Target a Turbo Frame %>
<%= rui_alert(:info,
      title: "New Message",
      href: message_path(@message),
      turbo_frame: "message-panel") do %>
  You have a new message.
<% end %>
```

**Features:**
- Uses Turbo for smooth navigation (no full page reload)
- Cursor changes to pointer on hover
- Clicking buttons/links inside alert won't navigate
- Dispatches `alert:dismissed` event when clicked

## Animations

Alerts have smooth enter/exit animations by default:

```erb
<%# Animations enabled by default for dismissible alerts %>
<%= rui_alert(:success, dismissible: true) do %>
  Animates in and out.
<% end %>

<%# Disable animations %>
<%= rui_alert(:info, animate: false, dismissible: true) do %>
  No animation.
<% end %>

<%# Force animations on static alerts %>
<%= rui_alert(:info, animate: true) do %>
  This static alert will animate in.
<% end %>
```

**Animation behavior:**
- **Enter:** Fades in and scales up (300ms ease-out)
- **Exit:** Fades out and scales down (200ms ease-in)
- Auto-enabled when `dismissible`, `auto_dismiss`, `href`, or `undo_url` is set

## Smart Flash Helper

One line renders all flash messages with context-aware styling:

```erb
<%# That's it! One line does everything. %>
<%= rui_flash %>
```

The component automatically:
- Maps flash keys to alert types (success → green, warning → amber, etc.)
- **Sorts by severity** (danger → warning → info → success)
- Auto-dismisses success/info alerts after 5 seconds
- Keeps warning/danger alerts visible until dismissed
- Shows countdown timer and close button

### Flash Key Mapping

| Flash Key | Alert Type | Color | Priority |
|-----------|------------|-------|----------|
| `:danger`, `:error`, `:alert` | `:danger` | Red | 1 (highest) |
| `:warning` | `:warning` | Amber | 2 |
| `:info` | `:info` | Blue | 3 |
| `:success`, `:notice` | `:success` | Green | 4 (lowest) |

### Options

```erb
<%# Basic usage %>
<%= rui_flash %>

<%# With custom wrapper class %>
<%= rui_flash(class: "max-w-2xl mx-auto") %>

<%# Disable auto-dismiss for all %>
<%= rui_flash(auto_dismiss: false) %>

<%# Custom dismiss timing %>
<%= rui_flash(dismiss_after: 10) %>

<%# With custom variant %>
<%= rui_flash(variant: :outline) %>

<%# Limit max visible messages (shows "and X more") %>
<%= rui_flash(max: 3) %>
```

### Toast-Style Positioning

Display flash messages as floating toast notifications:

```erb
<%# Top positions %>
<%= rui_flash(position: :top_left) %>
<%= rui_flash(position: :top_center) %>
<%= rui_flash(position: :top_right) %>

<%# Bottom positions %>
<%= rui_flash(position: :bottom_left) %>
<%= rui_flash(position: :bottom_center) %>
<%= rui_flash(position: :bottom_right) %>

<%# Inline (default - no fixed positioning) %>
<%= rui_flash(position: :inline) %>
```

**Position Options:**

| Position | Description |
|----------|-------------|
| `:inline` | Default, renders in document flow |
| `:top_left` | Fixed top-left corner |
| `:top_center` | Fixed top-center |
| `:top_right` | Fixed top-right corner |
| `:bottom_left` | Fixed bottom-left corner |
| `:bottom_center` | Fixed bottom-center |
| `:bottom_right` | Fixed bottom-right corner |

### Controller Examples

```ruby
# posts_controller.rb
def create
  if @post.save
    if @post.status == "published"
      flash[:success] = "Post published!"        # Green
    else
      flash[:info] = "Post saved as draft."     # Blue
    end
    redirect_to @post
  end
end

def destroy
  @post.destroy
  flash[:warning] = "Post was deleted."          # Amber
  redirect_to posts_path
end
```

## Smart Model Errors Helper

One line renders model validation errors:

```erb
<%# That's it! One line does everything. %>
<%= rui_errors(@post) %>
```

The component automatically:
- Returns nothing if model has no errors
- Generates title like "2 errors prohibited this post from being saved:"
- Renders all error messages as a list
- Uses danger (red) styling

### Options

```erb
<%# With custom title %>
<%= rui_errors(@user, title: "Please fix these issues:") %>

<%# With custom styling %>
<%= rui_errors(@post, variant: :outline, border_position: :left) %>
```

### Full Form Example

```erb
<%= form_with model: @user do |form| %>
  <%= rui_errors(@user) %>

<%# form fields... %>

<%= form.rui_button(color: :success) %>
<% end %>
```

## Turbo Stream Integration

Native Turbo Stream support for real-time notifications:

### Flash Container (Recommended for Turbo Apps)

Place in your layout for Turbo Stream flash updates:

```erb
<%# app/views/layouts/application.html.erb %>
<body>
  <%= rui_flash_container(position: :top_right) %>

<%= yield %>
</body>
```

The container:
- Has a stable ID (`rui-flash-container`) for Turbo Stream targeting
- Renders any existing flash messages
- Accepts position option for toast-style notifications

### Sending Alerts via Turbo Stream

```erb
<%# In a turbo_stream.erb view %>
<%= turbo_stream.prepend "rui-flash-container" do %>
  <%= rui_alert_turbo(:success, title: "Saved!", messages: "Your changes have been saved.") %>
<% end %>
```

### Controller Examples

```ruby
# Standard flash (works with rui_flash_container)
def create
  @post.save!
  flash[:success] = "Post created!"
  redirect_to @post
end

# Turbo Stream response with alert
def update
  @post.update!(post_params)

respond_to do |format|
    format.turbo_stream do
      render turbo_stream: [
        turbo_stream.replace(@post),
        turbo_stream.prepend("rui-flash-container",
          helpers.rui_alert_turbo(:success, messages: "Post updated!"))
      ]
    end
    format.html { redirect_to @post }
  end
end

# Real-time notification (via ActionCable)
def notify_user(user, message)
  Turbo::StreamsChannel.broadcast_prepend_to(
    user,
    target: "rui-flash-container",
    html: helpers.rui_alert_turbo(:info, title: "Notification", messages: message)
  )
end
```

### rui_alert_turbo Helper

Smart defaults for Turbo Stream alerts:

```erb
<%# Basic - auto-dismiss enabled for success/info %>
<%= rui_alert_turbo(:success, messages: "Done!") %>

<%# With title %>
<%= rui_alert_turbo(:warning, title: "Warning", messages: "Check your input.") %>

<%# With undo %>
<%= rui_alert_turbo(:warning,
      title: "Deleted",
      messages: "Item removed.",
      undo_url: undo_item_path(@item)) %>

<%# Clickable notification %>
<%= rui_alert_turbo(:info,
      title: "New Message",
      messages: "You have a new message.",
      href: messages_path) %>
```

### JavaScript Events

Listen for alert events in your Stimulus controllers:

```javascript
// In any Stimulus controller
this.element.addEventListener("alert:dismissed", (event) => {
  console.log("Alert dismissed:", event.detail.element)
})

this.element.addEventListener("alert:undo", (event) => {
  console.log("Undo clicked:", event.detail.element)
})
```

## API Reference

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `type` | Symbol | `:info` | **Positional or keyword.** Alert type: `:default`, `:info`, `:success`, `:warning`, `:danger`, `:error`, `:primary` |
| `title` | String | `nil` | Alert title (bold text) |
| `variant` | Symbol | `:soft` | Visual style: `:solid`, `:soft`, `:outline` |
| `size` | Symbol | `:base` | Size: `:xs`, `:sm`, `:base`, `:lg`, `:xl` |
| `shape` | Symbol | `:rounded` | Shape: `:square`, `:rounded`, `:pill` |
| `border_position` | Symbol | `:none` | Border accent: `:none`, `:left`, `:top`, `:bottom`, `:all` |
| `dismissible` | Boolean | `false` | Show dismiss (X) button |
| `auto_dismiss` | Boolean | `false` | Auto-dismiss after timeout |
| `dismiss_after` | Integer | `5` | Seconds before auto-dismiss |
| `show_progress_bar` | Boolean | auto* | Show progress bar countdown (* true when `auto_dismiss` is enabled) |
| `messages` | String/Array | `nil` | Message(s) to display (alternative to block content) |
| `show_icon` | Boolean | `true` | Show type icon |
| `animate` | Boolean | auto* | Enable enter/exit animations (* true when dismissible/auto_dismiss/href/undo_url is set) |
| `href` | String | `nil` | URL for clickable alert (uses Turbo navigation) |
| `turbo_frame` | String | `nil` | Turbo Frame ID to target for navigation |
| `undo_url` | String | `nil` | URL to call when undo is clicked |
| `undo_method` | Symbol | `:post` | HTTP method for undo request (`:post`, `:patch`, `:put`, `:delete`) |

### Slots

| Slot | Description |
|------|-------------|
| `icon` | Custom icon (replaces default type icon) |
| `actions` | Action buttons (multiple allowed) |

### rui_flash Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `position` | Symbol | `:inline` | Position: `:inline`, `:top_left`, `:top_center`, `:top_right`, `:bottom_left`, `:bottom_center`, `:bottom_right` |
| `max` | Integer | `nil` | Max messages to show (displays "and X more" for overflow) |
| `class` | String | `nil` | Custom CSS classes for wrapper |
| `auto_dismiss` | Boolean | smart* | Override auto-dismiss for all (* default: true for success/info, false for warning/danger) |
| `dismiss_after` | Integer | 5/8* | Seconds before auto-dismiss (* 5 for success, 8 for others) |
| `variant` | Symbol | `:soft` | Visual variant for all alerts: `:solid`, `:soft`, `:outline` |

**Note:** Messages are automatically sorted by severity: danger → warning → info → success

### rui_errors Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `model` | ActiveModel | required | Model with errors (positional argument) |
| `title` | String | auto* | Custom title (* auto-generates "X errors prohibited this model from being saved:") |
| `variant` | Symbol | `:soft` | Visual variant: `:solid`, `:soft`, `:outline` |
| `border_position` | Symbol | `:none` | Border accent: `:none`, `:left`, `:top`, `:bottom`, `:all` |
| `**options` | Hash | `{}` | Any other rui_alert options (size, shape, etc.) |

### rui_flash_container Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id` | String | `"rui-flash-container"` | Container ID for Turbo Stream targeting |
| `position` | Symbol | `:top_right` | Position: `:inline`, `:top_left`, `:top_center`, `:top_right`, `:bottom_left`, `:bottom_center`, `:bottom_right` |
| `class` | String | `nil` | Custom CSS classes for container |
| `**options` | Hash | `{}` | Passed to rui_flash for rendering existing messages |

### rui_alert_turbo Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `type` | Symbol | required | Alert type (positional): `:success`, `:info`, `:warning`, `:danger` |
| `title` | String | `nil` | Alert title |
| `messages` | String/Array | `nil` | Message(s) to display |
| `auto_dismiss` | Boolean | smart* | Auto-dismiss (* true for success/info, false for warning/danger) |
| `dismiss_after` | Integer | 5/8* | Seconds before dismiss (* 5 for success, 8 for others) |
| `**options` | Hash | `{}` | Any other rui_alert options (href, undo_url, etc.) |

### Usage Patterns

```erb
<%# Positional type (recommended) %>
<%= rui_alert(:success, title: "Saved!") { "Changes saved." } %>

<%# Keyword type (also supported) %>
<%= rui_alert(type: :success, title: "Saved!") { "Changes saved." } %>

<%# With messages parameter %>
<%= rui_alert(:danger, title: "Errors", messages: @model.errors.full_messages) %>

<%# With block content %>
<%= rui_alert(:info) do %>
  Custom content here.
<% end %>

<%# With slots %>
<%= rui_alert(:warning, title: "Warning") do |alert| %>
  <% alert.with_icon(:alert_triangle) %>
  <% alert.with_action("Confirm", color: :warning) %>
  Please review this action.
<% end %>
```

## Accessibility

- Uses `role="alert"` for screen reader announcements
- `aria-live="polite"` for info/success/warning
- `aria-live="assertive"` for danger/error (immediate announcement)
- `aria-atomic="true"` ensures entire alert is read
- Dismiss button has `aria-label="Dismiss alert"`

## Stimulus Controller

The alert uses a Stimulus controller for all interactive features:

```javascript
// Register in your application
import AlertController from "rapid_rails_ui/alert/alert_controller"
Stimulus.register("alert", AlertController)
```

### Actions

| Action | Description |
|--------|-------------|
| `alert#dismiss` | Dismisses the alert with fade animation |
| `alert#undo` | Triggers undo action and dismisses |
| `alert#pause` | Pauses auto-dismiss countdown (on hover) |
| `alert#resume` | Resumes auto-dismiss countdown (on hover out) |

### Values

| Value | Type | Default | Description |
|-------|------|---------|-------------|
| `autoDismiss` | Boolean | `false` | Enable auto-dismiss countdown |
| `dismissAfter` | Number | `5` | Seconds before auto-dismiss |
| `animate` | Boolean | `true` | Enable enter/exit animations |
| `href` | String | `""` | URL for clickable alerts |
| `turboFrame` | String | `""` | Turbo Frame ID to target |
| `undoUrl` | String | `""` | URL for undo request |
| `undoMethod` | String | `"post"` | HTTP method for undo |

### Targets

| Target | Description |
|--------|-------------|
| `countdown` | Element displaying countdown number |
| `progressBar` | Progress bar element for visual countdown |

### Events

| Event | Description |
|-------|-------------|
| `alert:dismissed` | Fired when alert is dismissed |
| `alert:undo` | Fired when undo button is clicked |

```javascript
// Listen for events
document.addEventListener("alert:dismissed", (event) => {
  console.log("Alert dismissed:", event.detail.element)
})

document.addEventListener("alert:undo", (event) => {
  console.log("Undo clicked:", event.detail.element)
})
```

---

## Avatar (`rui_avatar`)

# Avatar Component

The Avatar component provides a flexible system for displaying user profile images, initials, or placeholder icons with support for status indicators, social media platform sizes, and group stacking.

## Table of Contents

- [Basic Usage](#basic-usage)
- [API Reference](#api-reference)
- [Content Types](#content-types)
- [Sizes](#sizes)
- [Social Media Platform Sizes](#social-media-platform-sizes)
- [Shapes](#shapes)
- [Ring Styles](#ring-styles)
- [Status Indicators](#status-indicators)
- [Clickable Avatars](#clickable-avatars)
- [Avatar Groups](#avatar-groups)
- [Accessibility](#accessibility)
- [Best Practices](#best-practices)

---

## Basic Usage

```erb
<%# Avatar with image %>
<%= rui_avatar(src: user.avatar_url, alt: user.name) %>

<%# Avatar with name (auto-generates initials) %>
<%= rui_avatar(name: "John Doe") %>

<%# Avatar with custom initials %>
<%= rui_avatar(initials: "JD", size: :lg) %>

<%# Avatar with size and ring %>
<%= rui_avatar(src: avatar_url, size: :xl, ring: :primary) %>
```

---

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `src` | String | `nil` | Image source URL |
| `alt` | String | Name or "Avatar" | Alt text for image (accessibility) |
| `name` | String | `nil` | Full name (used to generate initials if no src) |
| `initials` | String | `nil` | Custom initials (overrides name-derived initials) |
| `size` | Symbol | `:md` | Size (`:xs`, `:sm`, `:md`, `:lg`, `:xl`, `:xl2`-`:xl6`, or platform preset) |
| `shape` | Symbol | `:circle` | Shape (`:circle`, `:rounded`, `:square`) |
| `ring` | Symbol | `:none` | Ring style. Brand colors `:primary`, `:secondary`, `:tertiary`, `:accent` resolve via `config.colors`; fixed values: `:none`, `:white`, `:gray`, `:black`, `:success`, `:warning`, `:danger`, `:ig_story`, `:ig_live` |
| `status` | Symbol | `nil` | Status indicator (`:online`, `:offline`, `:busy`, `:away`, `:dnd`, `:streaming`, `:idle`, `:invisible`) |
| `url` | String | `nil` | Makes avatar clickable with this URL |
| `group_position` | Integer | `nil` | Position in avatar group (1, 2, 3, etc.) for proper z-index stacking |
| `**options` | Hash | `{}` | Additional HTML attributes |

---

## Content Types

Avatar supports three content types with automatic fallback:

### Image Avatar

Displays an image when `src` is provided:

```erb
<%= rui_avatar(src: "https://example.com/avatar.jpg", alt: "John Doe") %>
```

### Initials Avatar

Shows initials when no image is available:

```erb
<%# Auto-generate from name (first letters of first and last name) %>
<%= rui_avatar(name: "John Doe") %>
<%# Displays: "JD" %>

<%# Single name (first two letters) %>
<%= rui_avatar(name: "John") %>
<%# Displays: "JO" %>

<%# Custom initials %>
<%= rui_avatar(initials: "ABC") %>
<%# Displays: "ABC" %>
```

### Fallback Icon

When neither image nor name/initials are provided, displays a user icon:

```erb
<%= rui_avatar %>
<%# Displays default user icon %>
```

---

## Sizes

### Standard UI Sizes

From extra small to extra extra large:

```erb
<%= rui_avatar(name: "JD", size: :xs) %>   
<%= rui_avatar(name: "JD", size: :sm) %>   
<%= rui_avatar(name: "JD", size: :md) %>   
<%= rui_avatar(name: "JD", size: :lg) %>   
<%= rui_avatar(name: "JD", size: :xl) %>   
<%= rui_avatar(name: "JD", size: :xl2) %>  
<%= rui_avatar(name: "JD", size: :xl3) %>  
<%= rui_avatar(name: "JD", size: :xl4) %>  
<%= rui_avatar(name: "JD", size: :xl5) %>  
<%= rui_avatar(name: "JD", size: :xl6) %>  
```

**Size Characteristics:**
- **xs** - 24px, compact UI elements
- **sm** - 32px, comments, small lists
- **md** - 40px, default for most uses
- **lg** - 48px, emphasized avatars
- **xl** - 64px, profile sections
- **xl2-xl6** - 80px-192px, hero sections, profile headers

---

## Social Media Platform Sizes

Use semantic size names that match exactly what you're building:

### Instagram

```erb
<%= rui_avatar(src: url, size: :ig_story) %>    
<%= rui_avatar(src: url, size: :ig_profile) %>  
<%= rui_avatar(src: url, size: :ig_post) %>     
<%= rui_avatar(src: url, size: :ig_comment) %>  
```

### YouTube

```erb
<%= rui_avatar(src: url, size: :yt_channel) %>   
<%= rui_avatar(src: url, size: :yt_comment) %>   
<%= rui_avatar(src: url, size: :yt_thumbnail) %> 
```

### LinkedIn

```erb
<%= rui_avatar(src: url, size: :linkedin_profile) %> 
<%= rui_avatar(src: url, size: :linkedin_post) %>    
<%= rui_avatar(src: url, size: :linkedin_comment) %> 
<%= rui_avatar(src: url, size: :linkedin_message) %> 
```

### X (Twitter)

```erb
<%= rui_avatar(src: url, size: :x_profile) %> 
<%= rui_avatar(src: url, size: :x_tweet) %>   
<%= rui_avatar(src: url, size: :x_reply) %>   
```

### Facebook

```erb
<%= rui_avatar(src: url, size: :fb_profile) %> 
<%= rui_avatar(src: url, size: :fb_post) %>    
<%= rui_avatar(src: url, size: :fb_comment) %> 
<%= rui_avatar(src: url, size: :fb_story) %>   
```

### TikTok

```erb
<%= rui_avatar(src: url, size: :tiktok_profile) %> 
<%= rui_avatar(src: url, size: :tiktok_comment) %> 
<%= rui_avatar(src: url, size: :tiktok_for_you) %> 
```

### Discord

```erb
<%= rui_avatar(src: url, size: :discord_avatar) %>  
<%= rui_avatar(src: url, size: :discord_profile) %> 
<%= rui_avatar(src: url, size: :discord_server) %>  
```

### Slack

```erb
<%= rui_avatar(src: url, size: :slack_avatar) %>  
<%= rui_avatar(src: url, size: :slack_profile) %> 
<%= rui_avatar(src: url, size: :slack_sidebar) %> 
```

### Twitch

```erb
<%= rui_avatar(src: url, size: :twitch_avatar) %>    
<%= rui_avatar(src: url, size: :twitch_channel) %>   
<%= rui_avatar(src: url, size: :twitch_thumbnail) %> 
```

### WhatsApp

```erb
<%= rui_avatar(src: url, size: :whatsapp_chat) %>    
<%= rui_avatar(src: url, size: :whatsapp_profile) %> 
<%= rui_avatar(src: url, size: :whatsapp_group) %>   
```

### GitHub

```erb
<%= rui_avatar(src: url, size: :github_avatar) %>  
<%= rui_avatar(src: url, size: :github_profile) %> 
<%= rui_avatar(src: url, size: :github_contrib) %> 
```

### Others

```erb
<%# Telegram %>
<%= rui_avatar(src: url, size: :telegram_chat) %>    
<%= rui_avatar(src: url, size: :telegram_profile) %>

<%# Dribbble %>
<%= rui_avatar(src: url, size: :dribbble_shot) %>    
<%= rui_avatar(src: url, size: :dribbble_profile) %>

<%# Behance %>
<%= rui_avatar(src: url, size: :behance_profile) %> 
<%= rui_avatar(src: url, size: :behance_project) %>

<%# Pinterest %>
<%= rui_avatar(src: url, size: :pinterest_pin) %>     
<%= rui_avatar(src: url, size: :pinterest_profile) %> 
```

---

## Shapes

Three distinct shape options:

```erb
<%# Circle (default) - rounded-full %>
<%= rui_avatar(name: "JD", shape: :circle) %>

<%# Rounded - rounded-lg %>
<%= rui_avatar(name: "JD", shape: :rounded) %>

<%# Square - no rounding %>
<%= rui_avatar(name: "JD", shape: :square) %>
```

**Shape Use Cases:**
- **circle** - Default, works for user avatars
- **rounded** - Modern UI, less formal
- **square** - Technical aesthetic, app icons

---

## Ring Styles

Add emphasis with visible borders (ring parameter creates CSS borders):

```erb
<%# No border (default) %>
<%= rui_avatar(src: url, ring: :none) %>

<%# Basic borders %>
<%= rui_avatar(src: url, ring: :white) %>   
<%= rui_avatar(src: url, ring: :gray) %>    
<%= rui_avatar(src: url, ring: :black) %>

<%# Brand color borders — resolve via config.colors %>
<%= rui_avatar(src: url, ring: :primary) %>   
<%= rui_avatar(src: url, ring: :secondary) %> 
<%= rui_avatar(src: url, ring: :tertiary) %>  
<%= rui_avatar(src: url, ring: :accent) %>

<%# Fixed status color borders %>
<%= rui_avatar(src: url, ring: :success) %> 
<%= rui_avatar(src: url, ring: :warning) %> 
<%= rui_avatar(src: url, ring: :danger) %>

<%# Instagram-specific borders %>
<%= rui_avatar(src: url, ring: :ig_story) %> 
<%= rui_avatar(src: url, ring: :ig_live) %>  
```

**Best Use Cases:**

- **Avatar Groups** - Use `ring: :white` to separate overlapping avatars (see [Avatar Groups](#avatar-groups))
- **Status Indicators** - Use semantic colors to show verification or special status
- **Emphasis** - Add borders to highlight important profiles

**Instagram Story Example:**

```erb
<%# Story bubble with pink border %>
<%= rui_avatar(src: user.avatar_url, size: :ig_story, ring: :ig_story) %>
```

---

## Status Indicators

Show user availability with status indicators:

```erb
<%# Availability statuses %>
<%= rui_avatar(src: url, status: :online) %>    
<%= rui_avatar(src: url, status: :offline) %>   
<%= rui_avatar(src: url, status: :busy) %>      
<%= rui_avatar(src: url, status: :away) %>      
<%= rui_avatar(src: url, status: :dnd) %>       
<%= rui_avatar(src: url, status: :idle) %>

<%# Platform-specific statuses %>
<%= rui_avatar(src: url, status: :streaming) %> 
<%= rui_avatar(src: url, status: :invisible) %> 
```

**Status dot sizes scale with avatar size automatically.**

---

## Clickable Avatars

Make avatars link to user profiles:

```erb
<%# Link to user profile %>
<%= rui_avatar(src: user.avatar_url, url: user_path(user)) %>

<%# External profile link %>
<%= rui_avatar(src: avatar_url, url: "https://twitter.com/username") %>
```

Clickable avatars get:
- Hover effect (scale animation)
- Cursor pointer
- Title attribute from alt text

---

## Avatar Groups

Create overlapping avatar stacks using Flexbox with Tailwind's space utilities (Flowbite-style approach):

### Basic Stacked Group

```erb
<%# Stacked avatars with white borders %>
<div class="flex -space-x-4 rtl:space-x-reverse">
  <%= rui_avatar(src: url1, alt: "User 1", size: :md, ring: :white) %>
  <%= rui_avatar(src: url2, alt: "User 2", size: :md, ring: :white) %>
  <%= rui_avatar(src: url3, alt: "User 3", size: :md, ring: :white) %>
  <%= rui_avatar(src: url4, alt: "User 4", size: :md, ring: :white) %>
</div>
```

### With Count Badge

```erb
<%# Show count of additional users %>
<div class="flex -space-x-4 rtl:space-x-reverse">
  <%= rui_avatar(src: url1, alt: "User 1", size: :md, ring: :white) %>
  <%= rui_avatar(src: url2, alt: "User 2", size: :md, ring: :white) %>
  <%= rui_avatar(src: url3, alt: "User 3", size: :md, ring: :white) %>
  <div class="relative z-10 flex items-center justify-center w-10 h-10 text-xs font-medium text-white bg-gray-800 dark:bg-gray-900 border-2 border-white dark:border-gray-900 rounded-full flex-shrink-0">
    +99
  </div>
</div>
```

**Container Classes:**
- `flex` - Flexbox container for proper alignment
- `-space-x-4` - Negative horizontal spacing (16px overlap) for stacking
- `rtl:space-x-reverse` - RTL support for right-to-left languages
- `ring: :white` - White border on each avatar for visual separation

**Badge Classes (for count display):**
- `relative z-10` - Ensures badge appears on top of overlapping avatars
- `border-2 border-white dark:border-gray-900` - Matches avatar border style

### Real-World Example - Contributor List

```erb
<div class="flex items-center gap-4">
  <div>
    <h3 class="text-sm font-semibold mb-2">Contributors</h3>
    <div class="flex -space-x-4 rtl:space-x-reverse">
      <% @contributors.first(4).each do |user| %>
        <%= rui_avatar(
          src: user.avatar_url,
          alt: user.name,
          size: :sm,
          ring: :white,
          url: user_path(user)
        ) %>
      <% end %>
      <% if @contributors.count > 4 %>
        <div class="relative z-10 flex items-center justify-center w-8 h-8 text-xs font-medium text-white bg-gray-800 dark:bg-gray-900 border-2 border-white dark:border-gray-900 rounded-full flex-shrink-0">
          +<%= @contributors.count - 4 %>
        </div>
      <% end %>
    </div>
  </div>
</div>
```

### Reverse Stacked Order

```erb
<%# Reverse order for right-aligned stacks %>
<div class="flex -space-x-4 rtl:space-x-reverse">
  <%= rui_avatar(src: url4, alt: "User 4", size: :md, ring: :white) %>
  <%= rui_avatar(src: url3, alt: "User 3", size: :md, ring: :white) %>
  <%= rui_avatar(src: url2, alt: "User 2", size: :md, ring: :white) %>
  <%= rui_avatar(src: url1, alt: "User 1", size: :md, ring: :white) %>
</div>
```

**Backward Compatibility Note:** The older `group_position` parameter still works for legacy code but is deprecated. Use the Flexbox container approach above for new implementations.

---

## Accessibility

The Avatar component follows accessibility best practices:

### ARIA Roles and Labels

```erb
<%# Static avatar - role="img" with aria-label %>
<%= rui_avatar(src: url, alt: "John Doe") %>

<%# Clickable avatar - no role="img" (link handles it) %>
<%= rui_avatar(src: url, url: "/profile") %>

```

### Image Alt Text

Always provide meaningful alt text:

```erb
<%# Good - descriptive alt text %>
<%= rui_avatar(src: url, alt: "Profile photo of John Doe") %>
<%= rui_avatar(src: url, name: "John Doe") %> <%# alt defaults to name %>

<%# Avoid - generic alt text %>
<%= rui_avatar(src: url) %> <%# alt defaults to "Avatar" %>
```

### Status Indicator Titles

Status indicators have title attributes for hover info:

```erb
<%= rui_avatar(src: url, status: :online) %>

```

---

## Best Practices

### 1. Always Provide Alt Text

```erb
<%# Good - meaningful identification %>
<%= rui_avatar(src: user.avatar_url, alt: user.name) %>
<%= rui_avatar(name: user.name) %>

<%# Avoid - missing context %>
<%= rui_avatar(src: url) %>
```

### 2. Use Semantic Platform Sizes

```erb
<%# Good - clear intent %>
<%= rui_avatar(src: url, size: :ig_profile) %>
<%= rui_avatar(src: url, size: :slack_avatar) %>

<%# Less clear - what's this for? %>
<%= rui_avatar(src: url, size: :xl3) %>
```

### 3. Consistent Sizing in Lists

```erb
<%# Good - same size throughout %>
<% @users.each do |user| %>
  <%= rui_avatar(src: user.avatar_url, size: :sm) %>
<% end %>
```

### 4. Use Status Indicators Meaningfully

```erb
<%# Good - real-time status %>
<%= rui_avatar(src: url, status: user.online? ? :online : :offline) %>

<%# Avoid - static status that isn't maintained %>
<%= rui_avatar(src: url, status: :online) %>
```

### 5. Ring Colors for Context

```erb
<%# Good - ring indicates special status %>
<%= rui_avatar(src: url, ring: :ig_story) %> <%# Has unviewed story %>
<%= rui_avatar(src: url, ring: :success) %> <%# Verified user %>

<%# Avoid - decorative rings without meaning %>
```

---

## Real-World Examples

### User Profile Header

```erb
<div class="flex items-center gap-4">
  <%= rui_avatar(
    src: @user.avatar_url,
    alt: @user.name,
    size: :xl4,
    ring: @user.verified? ? :success : :none,
    status: @user.status
  ) %>
  <div>
    <h1 class="text-2xl font-bold"><%= @user.name %></h1>
    <p class="text-gray-500">@<%= @user.username %></p>
  </div>
</div>
```

### Comment Thread

```erb
<div class="flex gap-3">
  <%= rui_avatar(
    src: comment.user.avatar_url,
    name: comment.user.name,
    size: :sm,
    url: user_path(comment.user)
  ) %>
  <div>
    <p class="font-medium"><%= comment.user.name %></p>
    <p><%= comment.body %></p>
  </div>
</div>
```

### Social Media Feed Post

```erb
<%# Instagram-style post header %>
<div class="flex items-center gap-3 p-3">
  <%= rui_avatar(
    src: @post.user.avatar_url,
    size: :ig_post,
    ring: @post.user.has_story? ? :ig_story : :none,
    url: user_path(@post.user)
  ) %>
  <span class="font-semibold"><%= @post.user.username %></span>
</div>
```

### Chat/Messaging Interface

```erb
<% @messages.each do |message| %>
  <div class="flex items-start gap-2 <%= message.mine? ? 'flex-row-reverse' : '' %>">
    <%= rui_avatar(
      src: message.sender.avatar_url,
      name: message.sender.name,
      size: :discord_avatar,
      status: message.sender.online_status
    ) %>
    <div class="bg-gray-100 rounded-lg p-3">
      <%= message.body %>
    </div>
  </div>
<% end %>
```

### Team/Contributor Display

```erb
<div class="flex items-center gap-2">
  <span class="text-sm text-gray-500">Team:</span>
  <div class="flex">
    <% @team.members.each_with_index do |member, i| %>
      <%= rui_avatar(
        src: member.avatar_url,
        alt: member.name,
        size: :xs,
        ring: :white,
        group_position: i + 1,
        url: user_path(member)
      ) %>
    <% end %>
  </div>
</div>
```

---

## Related Components

- **Badge** - Can be combined with avatars for status labels
- **Link** - Wrap avatars for navigation
- **Icon** - Used internally for fallback avatar

---

## Component Architecture

The Avatar component is built with:
- **Tailwind CSS** for styling
- **ViewComponent** architecture
- **Lucide Icons** for fallback user icon
- Automatic initials generation from names
- Responsive status indicator sizing
- Accessibility-first with ARIA attributes

For more information, see the [RapidRailsUI documentation](https://rapidrailsui.com).

---

## Badge (`rui_badge`)

# Badge Component

The Badge component provides a lightweight labeling system for highlighting status, metadata, or categorization in your application.

## Table of Contents

- [Basic Usage](#basic-usage)
- [API Reference](#api-reference)
- [Colors](#colors)
- [Sizes](#sizes)
- [Shapes](#shapes)
- [Variants](#variants)
- [Badges with Icons](#badges-with-icons)
- [Interactive Badges](#interactive-badges)
- [Counter Badges](#counter-badges)
- [GitHub-Style Badges](#github-style-badges)
- [Accessibility](#accessibility)
- [Best Practices](#best-practices)

---

## Basic Usage

```erb
<%# Simple badge %>
<%= rui_badge(text: "New") %>

<%# Badge with color %>
<%= rui_badge(text: "Success", color: :success) %>

<%# Badge with size and shape %>
<%= rui_badge(text: "Important", color: :danger, size: :lg, shape: :pill) %>
```

---

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `text` | String | `nil` | Badge text content |
| `color` | Symbol | `:primary` | Color theme (`:primary`, `:secondary`, `:success`, `:warning`, `:danger`, `:info`, etc.) |
| `size` | Symbol | `:xs` | Size variant (`:xs`, `:sm`, `:base`, `:md`, `:lg`, `:xl`, `:xl2`) |
| `variant` | Symbol | `:solid` | Visual style (`:solid`, `:outline`, `:ghost`, `:soft`, `:link`) |
| `shape` | Symbol | `:pill` | Border shape (`:rounded`, `:pill`, `:square`, `:circle`) |
| `url` | String | `nil` | Makes badge clickable (renders as `<a>`) |
| `close_button` | Boolean | `false` | Shows close button with X icon |
| `dismissible` | Boolean | `false` | Makes badge dismissible on click |
| `counter` | Integer | `nil` | Shows numerical counter |
| `pulsing` | Boolean | `false` | Adds pulsing animation |
| `status` | Symbol | `nil` | **Legacy:** Use `color` instead |
| `class` | String | `nil` | Additional CSS classes |
| `**options` | Hash | `{}` | Additional HTML attributes |

### Icon Slot

Badges support an icon slot for adding visual indicators:

```erb
<%= rui_badge(text: "Warning", color: :warning) do |badge|
  badge.with_icon(name: "alert-triangle", position: :leading)
end %>
```

**Icon Parameters:**
- `name` (required) - Lucide icon name (e.g., `:star`, `:heart`, `"check-circle"`)
- `position` - `:leading` (default) or `:trailing`
- `color` - Override icon color (inherits badge color by default)
- `size` - Override icon size

---

## Colors

The Badge component supports all RapidRailsUI semantic colors and Tailwind color palette:

### Semantic Colors

```erb
<%= rui_badge(text: "Primary", color: :primary) %>
<%= rui_badge(text: "Secondary", color: :secondary) %>
<%= rui_badge(text: "Success", color: :success) %>
<%= rui_badge(text: "Warning", color: :warning) %>
<%= rui_badge(text: "Danger", color: :danger) %>
<%= rui_badge(text: "Info", color: :info) %>
```

### Tailwind Colors

```erb
<%= rui_badge(text: "Red", color: :red) %>
<%= rui_badge(text: "Blue", color: :blue) %>
<%= rui_badge(text: "Green", color: :green) %>
<%= rui_badge(text: "Yellow", color: :yellow) %>
<%= rui_badge(text: "Purple", color: :purple) %>
<%= rui_badge(text: "Pink", color: :pink) %>
<%= rui_badge(text: "Indigo", color: :indigo) %>
```

### Legacy Status Parameter

For backward compatibility, `status:` is supported but `color:` is recommended:

```erb
<%# Legacy (still works) %>
<%= rui_badge(text: "Active", status: :success) %>

<%# Recommended %>
<%= rui_badge(text: "Active", color: :success) %>
```

---

## Sizes

Badge sizes range from extra small to 2x large:

```erb
<%= rui_badge(text: "XS", size: :xs) %>       
<%= rui_badge(text: "Small", size: :sm) %>    
<%= rui_badge(text: "Base", size: :base) %>   
<%= rui_badge(text: "Medium", size: :md) %>   
<%= rui_badge(text: "Large", size: :lg) %>    
<%= rui_badge(text: "XL", size: :xl) %>       
<%= rui_badge(text: "2XL", size: :xl2) %>     
```

**Size Characteristics:**
- **xs** - 12px text, minimal padding (default for most badges)
- **sm** - 12px text, slightly more padding
- **base** - 14px text, standard padding
- **md** - 14px text, comfortable padding
- **lg** - 14px text, generous padding
- **xl** - 16px text, large padding
- **xl2** - 18px text, maximum padding

---

## Shapes

Four distinct shape options for different visual styles:

```erb
<%# Rounded corners (slightly rounded) %>
<%= rui_badge(text: "Rounded", shape: :rounded) %>

<%# Pill (fully rounded ends - default) %>
<%= rui_badge(text: "Pill", shape: :pill) %>

<%# Square (no rounding) %>
<%= rui_badge(text: "Square", shape: :square) %>

<%# Circle (perfect circle - best for icon-only badges) %>
<%= rui_badge(text: "A", shape: :circle) %>
```

**Shape Use Cases:**
- **pill** - Default, works well for most text badges
- **rounded** - Softer look, modern UI
- **square** - Technical/minimal aesthetic
- **circle** - Icon-only badges, avatars, status indicators

---

## Variants

Five visual variants for different emphasis levels:

### Solid (Default)

Filled background with contrasting text:

```erb
<%= rui_badge(text: "Solid", variant: :solid, color: :primary) %>
```

### Outline

Border with transparent background:

```erb
<%= rui_badge(text: "Outline", variant: :outline, color: :primary) %>
```

### Ghost

Minimal styling, transparent background:

```erb
<%= rui_badge(text: "Ghost", variant: :ghost, color: :primary) %>
```

### Soft

Subtle colored background with colored text:

```erb
<%= rui_badge(text: "Soft", variant: :soft, color: :primary) %>
```

### Link

Underlined text style:

```erb
<%= rui_badge(text: "Link", variant: :link, color: :primary) %>
```

---

## Badges with Icons

Icons can be positioned before (leading) or after (trailing) the text:

### Leading Icon (Default)

```erb
<%= rui_badge(text: "Warning", color: :warning) do |badge|
  badge.with_icon(name: "alert-triangle")
end %>
```

### Trailing Icon

```erb
<%= rui_badge(text: "Next", color: :primary) do |badge|
  badge.with_icon(name: "arrow-right", position: :trailing)
end %>
```

### Icon-Only Badge

For compact status indicators:

```erb
<%= rui_badge(color: :success, shape: :circle) do |badge|
  badge.with_icon(name: "check")
end %>
```

### Icon Color Inheritance

Icons automatically inherit the badge color:

```erb
<%# Icon inherits success color %>
<%= rui_badge(text: "Paid", color: :success) do |badge|
  badge.with_icon(name: "circle-check")
end %>
```

### Icon Color Override

Provide explicit color for custom icon styling:

```erb
<%# Blue badge with yellow star %>
<%= rui_badge(text: "Featured", color: :primary) do |badge|
  badge.with_icon(name: "star", color: :yellow)
end %>
```

### Real-World Examples

**Status Indicators:**

```erb
<%# Payment status %>
<%= rui_badge(text: "Paid", color: :success) do |badge|
  badge.with_icon(name: "circle-check")
end %>

<%# Processing %>
<%= rui_badge(text: "Processing", color: :warning) do |badge|
  badge.with_icon(name: "loader", position: :leading)
end %>

<%# Failed %>
<%= rui_badge(text: "Failed", color: :danger) do |badge|
  badge.with_icon(name: "alert-circle")
end %>
```

**Navigation:**

```erb
<%# New feature indicator %>
<%= rui_badge(text: "New Feature", color: :info) do |badge|
  badge.with_icon(name: "sparkles", position: :trailing)
end %>
```

---

## Interactive Badges

### Clickable Badges

Add `url:` to make badges clickable (renders as `<a>` tag):

```erb
<%# Internal link %>
<%= rui_badge(text: "Documentation", color: :info, url: "/docs") %>

<%# External link (automatic security attributes) %>
<%= rui_badge(text: "GitHub", color: :primary, url: "https://github.com") %>
```

Clickable badges automatically get:
- `role="link"` for accessibility
- `rel="noopener noreferrer"` for security

### Dismissible Badges

Click to dismiss with fade-out effect:

```erb
<%= rui_badge(text: "Dismissible Alert", color: :warning, dismissible: true) %>
```

**Requires JavaScript:**
```javascript
// Stimulus controller handles dismiss action
data-controller="utilities"
data-action="click->utilities#dismiss"
```

### Close Button

Shows an X button for manual dismissal:

```erb
<%= rui_badge(text: "Close Me", color: :info, close_button: true) %>
```

**Real-World Example - Filter Tags:**

```erb
<div class="flex gap-2">
  <%= rui_badge(text: "Category: Rails", color: :blue, close_button: true) %>
  <%= rui_badge(text: "Status: Published", color: :green, close_button: true) %>
  <%= rui_badge(text: "Author: John", color: :purple, close_button: true) %>
</div>
```

---

## Counter Badges

Display numerical indicators for notifications, messages, etc:

```erb
<%# Notification counter %>
<%= rui_badge(text: "Messages", counter: 5, color: :primary) %>

<%# Large counter %>
<%= rui_badge(text: "Notifications", counter: 99, color: :danger) %>

<%# With icon %>
<%= rui_badge(text: "Inbox", counter: 12, color: :info) do |badge|
  badge.with_icon(name: "mail")
end %>
```

**Real-World Example - Notification Center:**

```erb
<nav>
  <%= rui_badge(text: "Messages", counter: 5, size: :sm) %>
  <%= rui_badge(text: "Alerts", counter: 2, color: :warning, size: :sm) %>
  <%= rui_badge(text: "Updates", counter: 15, color: :info, size: :sm) %>
</nav>
```

---

## Pulsing Animation

Draw attention with a subtle pulse:

```erb
<%= rui_badge(text: "New", color: :success, pulsing: true) %>

<%# Live indicator %>
<%= rui_badge(text: "Live", color: :danger, pulsing: true) do |badge|
  badge.with_icon(name: "circle")
end %>
```

**Use Cases:**
- Live streaming indicators
- Real-time notifications
- Important updates
- Active processes

---

## GitHub-Style Badges

Special badge styles matching GitHub's design:

### Topic Tags

```erb
<%= rui_badge(text: "rails", color: :gh_topic) %>
<%= rui_badge(text: "ruby", color: :gh_topic) %>
<%= rui_badge(text: "viewcomponent", color: :gh_topic) %>
```

### Labels

```erb
<%= rui_badge(text: "Public", color: :gh_label) %>
<%= rui_badge(text: "Archived", color: :gh_label_archive) %>
<%= rui_badge(text: "Beta", color: :gh_label_beta) %>
<%= rui_badge(text: "PRO", color: :gh_label_pro) %>
```

### Language Tags

```erb
<%= rui_badge(color: :danger, text: "Ruby") do |badge|
  badge.with_icon(name: "circle-full", size: :xs)
end %>

<%= rui_badge(color: :warning, text: "JavaScript") do |badge|
  badge.with_icon(name: "circle-full", size: :xs)
end %>

<%= rui_badge(color: :info, text: "TypeScript") do |badge|
  badge.with_icon(name: "circle-full", size: :xs)
end %>
```

---

## Accessibility

The Badge component follows accessibility best practices:

### ARIA Roles

```erb
<%# Static badge - role="status" %>
<%= rui_badge(text: "Active") %>

<%# Clickable badge - role="link" %>
<%= rui_badge(text: "Docs", url: "/docs") %>

```

### ARIA Labels

Badges automatically generate appropriate ARIA labels:

```erb
<%# Text becomes aria-label %>
<%= rui_badge(text: "Important") %>

<%# Color-based labels for icon-only badges %>
<%= rui_badge(color: :success) do |badge|
  badge.with_icon(name: "check")
end %>

<%# Custom aria-label %>
<%= rui_badge(color: :warning, title: "Pending Approval") do |badge|
  badge.with_icon(name: "clock")
end %>

```

**Color-based ARIA Labels:**
- `:success` → "Success"
- `:warning` → "Warning"
- `:danger` → "Danger"
- `:error` → "Error"
- `:info` → "Information"
- Default → "Badge"

### Keyboard Navigation

Clickable badges are fully keyboard accessible:

```erb
<%# Can be focused and activated with Enter/Space %>
<%= rui_badge(text: "View Details", url: "/details", color: :primary) %>
```

### Screen Reader Support

- Semantic HTML (`<span>` for static, `<a>` for links)
- Proper ARIA roles and labels
- Meaningful text content
- Icon titles for context

---

## Best Practices

### 1. Keep Text Concise

Badges work best with short, clear text:

```erb
<%# Good - concise %>
<%= rui_badge(text: "New") %>
<%= rui_badge(text: "Beta") %>
<%= rui_badge(text: "PRO") %>

<%# Avoid - too long %>
<%= rui_badge(text: "This is a very long badge text that should be shortened") %>
```

### 2. Use Color Semantically

Choose colors that match the meaning:

```erb
<%# Good - semantic colors %>
<%= rui_badge(text: "Active", color: :success) %>
<%= rui_badge(text: "Warning", color: :warning) %>
<%= rui_badge(text: "Error", color: :danger) %>
<%= rui_badge(text: "Info", color: :info) %>
```

### 3. Don't Overuse

Too many badges create visual noise:

```erb
<%# Good - selective use %>
<h2>
  Important Document
  <%= rui_badge(text: "New", color: :success, size: :sm) %>
</h2>

<%# Avoid - badge overload %>
<h2>
  <%= rui_badge(text: "New") %>
  <%= rui_badge(text: "Featured") %>
  <%= rui_badge(text: "Popular") %>
  <%= rui_badge(text: "Trending") %>
  Important Document
</h2>
```

### 4. Consistent Sizing

Use consistent sizes within the same context:

```erb
<%# Good - consistent sizing %>
<div class="status-badges">
  <%= rui_badge(text: "Active", size: :sm, color: :success) %>
  <%= rui_badge(text: "Verified", size: :sm, color: :info) %>
  <%= rui_badge(text: "Premium", size: :sm, color: :primary) %>
</div>
```

### 5. Icon + Text Clarity

When combining icons and text, ensure they complement each other:

```erb
<%# Good - icon reinforces meaning %>
<%= rui_badge(text: "Verified", color: :success) do |badge|
  badge.with_icon(name: "shield-check")
end %>

<%= rui_badge(text: "Warning", color: :warning) do |badge|
  badge.with_icon(name: "alert-triangle")
end %>
```

### 6. Interactive Badges Should Look Clickable

When using URLs, consider using the link variant:

```erb
<%# Clear clickable appearance %>
<%= rui_badge(text: "View Docs", url: "/docs", variant: :link, color: :blue) %>

<%# Or add an icon to indicate action %>
<%= rui_badge(text: "Learn More", url: "/guide", color: :primary) do |badge|
  badge.with_icon(name: "arrow-right", position: :trailing)
end %>
```

### 7. Counter Badges for Quantities

Use counters for numeric data:

```erb
<%# Good - clear numeric indicator %>
<%= rui_badge(text: "Unread", counter: 5, color: :primary) %>

<%# Avoid - number in text %>
<%= rui_badge(text: "5 Unread Messages", color: :primary) %>
```

---

## Real-World Examples

### E-commerce Product Badges

```erb
<%# New arrival %>
<%= rui_badge(text: "New Arrival", color: :success, size: :sm) %>

<%# Sale indicator %>
<%= rui_badge(text: "50% OFF", color: :danger, size: :md, pulsing: true) %>

<%# Stock status %>
<%= rui_badge(text: "In Stock", color: :success) do |badge|
  badge.with_icon(name: "check-circle")
end %>

<%= rui_badge(text: "Low Stock", color: :warning) do |badge|
  badge.with_icon(name: "alert-triangle")
end %>
```

### User Dashboard

```erb
<%# Account status %>
<%= rui_badge(text: "Verified", color: :success) do |badge|
  badge.with_icon(name: "shield-check")
end %>

<%# Subscription tier %>
<%= rui_badge(text: "PRO", color: :purple, size: :sm, shape: :rounded) %>

<%# Notifications %>
<%= rui_badge(text: "Notifications", counter: 12, color: :danger) do |badge|
  badge.with_icon(name: "bell")
end %>
```

### Content Management

```erb
<%# Post status %>
<%= rui_badge(text: "Published", color: :success, variant: :soft) %>
<%= rui_badge(text: "Draft", color: :gray, variant: :soft) %>
<%= rui_badge(text: "Pending Review", color: :warning, variant: :soft) %>

<%# Content tags (dismissible) %>
<%= rui_badge(text: "Tutorial", color: :blue, close_button: true) %>
<%= rui_badge(text: "Rails", color: :red, close_button: true) %>
<%= rui_badge(text: "Advanced", color: :purple, close_button: true) %>
```

### Repository Information (GitHub-style)

```erb
<div class="repo-meta">
  <%# Topics %>
  <div class="topics">
    <%= rui_badge(text: "rails", color: :gh_topic) %>
    <%= rui_badge(text: "ruby", color: :gh_topic) %>
    <%= rui_badge(text: "viewcomponent", color: :gh_topic) %>
  </div>

<%# Language %>
  <%= rui_badge(text: "Ruby", color: :danger) do |badge|
    badge.with_icon(name: "circle-full", size: :xs)
  end %>

<%# Visibility %>
  <%= rui_badge(text: "Public", color: :gh_label) %>
</div>
```

---

## Related Components

- **Button** - For actionable UI elements
- **Link** - For navigation with styling
- **Icon** - Used within badges for visual indicators
- **SocialButton** - Platform-specific action buttons

---

## Component Architecture

The Badge component is built with:
- **Tailwind CSS** for styling
- **ViewComponent** architecture
- **ColorBuilderHelper** for dynamic color generation
- **Icon Component** integration for visual indicators
- **Lucide Icons** via icon slot
- Full accessibility compliance (WCAG AA)

For more information, see the [RapidRailsUI documentation](https://rapidrailsui.com).

---

## Button (`rui_button`)

# RapidRailsUI Button Component Usage

The `Button` component renders a `<button>` element with automatic context detection. It supports Rails form integration with auto-labeling, multiple variants, colors, sizes, shapes, and states.

**Note:** For navigation, use Rails `link_to`. For RESTful actions (POST/PATCH/PUT/DELETE), use `rui_button_to`.

---

## Basic Usage

```erb

<%= rui_button("Click Me") %>

<%= rui_button(text: "Click Me") %>

<%= rui_button(color: :primary) %>
```

**Note:** Both positional and keyword argument styles are supported for backward compatibility. The positional style is recommended as it's more concise and Rails-like.

## Variants

```erb
<%= rui_button("Solid", variant: :solid) %>
<%= rui_button("Outline", variant: :outline) %>
<%= rui_button("Ghost", variant: :ghost) %>
<%= rui_button("Soft", variant: :soft) %>
<%= rui_button("Link", variant: :link) %>
```

## Colors

### Semantic Colors (Configurable)

These colors are configurable via `config/initializers/rapidrailsui.rb`:

```erb
<%= rui_button("Primary", color: :primary) %>   
<%= rui_button("Secondary", color: :secondary) %> 
<%= rui_button("Accent", color: :accent) %>     
```

### Standard UI Colors

```erb
<%= rui_button("Success", color: :success) %>   
<%= rui_button("Danger", color: :danger) %>     
<%= rui_button("Warning", color: :warning) %>   
<%= rui_button("Info", color: :info) %>        
```

### Custom Colors

You can use any RapidCascade color palette defined in your system:

```erb

<%= rui_button("Indigo", color: :indigo) %>
<%= rui_button("Emerald", color: :emerald) %>
<%= rui_button("Purple", color: :purple) %>

<%= rui_button("Boulder", color: :boulder) %>
<%= rui_button("Tradewind", color: :tradewind) %>
<%= rui_button("Punch", color: :punch) %>
```

## Sizes

```erb
<%= rui_button("Extra Small", size: :xs) %>
<%= rui_button("Small", size: :sm) %>
<%= rui_button("Base", size: :base) %>
<%= rui_button("Medium", size: :md) %>
<%= rui_button("Large", size: :lg) %>
<%= rui_button("Extra Large", size: :xl) %>
```

## Shapes

```erb
<%= rui_button("Rounded", shape: :rounded) %>
<%= rui_button("Pill", shape: :pill) %>
<%= rui_button("Square", shape: :square) %>
<%= rui_button("Circle", shape: :circle) %>
```

## Full Width

```erb
<%= rui_button("Full Width", full_width: true) %>
```

## Loading and Disabled States

```erb
<%= rui_button("Loading...", loading: true) %>
<%= rui_button("Disabled", disabled: true) %>
```

## With Icons

Add icons to buttons using the icon slot. Icons automatically inherit the button's color.

**Requires:** The `lucide-rails` gem must be installed to use icons. See [Icon Component](../icon/USAGE.md) for details.

### Leading Icons (Default)

Icons appear before the text by default:

```erb
<%# Icon with text - leading position (default) %>
<%= rui_button("Add to Cart", color: :primary) do |button| %>
  <% button.with_icon(name: "shopping-cart") %>
<% end %>

<%# Explicit leading position %>
<%= rui_button("Save Changes", color: :success) do |button| %>
  <% button.with_icon(name: "save", position: :leading) %>
<% end %>

<%# Download button %>
<%= rui_button("Download", variant: :outline) do |button| %>
  <% button.with_icon(name: "download") %>
<% end %>
```

### Trailing Icons

Icons appear after the text when using `position: :trailing`:

```erb
<%# Arrow pointing right (common for "next" buttons) %>
<%= rui_button("Continue", color: :primary) do |button| %>
  <% button.with_icon(name: "arrow-right", position: :trailing) %>
<% end %>

<%# External link indicator %>
<%= rui_button("Open Link", variant: :ghost) do |button| %>
  <% button.with_icon(name: "external-link", position: :trailing) %>
<% end %>

<%# Chevron for dropdowns %>
<%= rui_button("Options", variant: :outline) do |button| %>
  <% button.with_icon(name: "chevron-down", position: :trailing) %>
<% end %>
```

### Icon Sizes

Icons automatically scale with button size:

```erb
<%# Small button with icon %>
<%= rui_button("Small", size: :sm, variant: :outline) do |button| %>
  <% button.with_icon(name: "check") %>
<% end %>

<%# Large button with icon %>
<%= rui_button("Large", size: :lg, color: :success) do |button| %>
  <% button.with_icon(name: "check", size: :lg) %>
<% end %>

<%# Extra large button %>
<%= rui_button("Extra Large", size: :xl, color: :primary) do |button| %>
  <% button.with_icon(name: "rocket", size: :xl) %>
<% end %>
```

### Icon Color Override

Icons automatically inherit the button's color, but you can override with a custom color:

```erb
<%# Icon inherits button color (default behavior) %>
<%= rui_button("Save", color: :blue) do |button| %>
  <% button.with_icon(:bookmark) %>
  <%# Icon will be blue %>
<% end %>

<%# Icon with custom color (overrides inheritance) %>
<%= rui_button("Delete", color: :danger) do |button| %>
  <% button.with_icon(:trash_2, color: :red) %>
  <%# Button is danger color, but icon is specifically red %>
<% end %>

<%# Useful for accent icons %>
<%= rui_button("Premium Feature", color: :primary) do |button| %>
  <% button.with_icon(:star, color: :yellow) %>
  <%# Primary button with yellow star icon %>
<% end %>
```

**Note:** When you provide an explicit `color:` parameter to the icon, it uses standalone mode and renders with its own color instead of inheriting from the button.

### Common Icon Patterns

```erb
<%# Delete action %>
<%= rui_button("Delete", color: :danger, variant: :outline) do |button| %>
  <% button.with_icon(name: "trash-2") %>
<% end %>

<%# Edit action %>
<%= rui_button("Edit", variant: :ghost) do |button| %>
  <% button.with_icon(name: "pencil") %>
<% end %>

<%# Create/Add action %>
<%= rui_button("New Post", color: :success) do |button| %>
  <% button.with_icon(name: "plus") %>
<% end %>

<%# Search %>
<%= rui_button("Search", variant: :outline) do |button| %>
  <% button.with_icon(name: "search") %>
<% end %>

<%# Settings %>
<%= rui_button("Settings", variant: :ghost) do |button| %>
  <% button.with_icon(name: "settings") %>
<% end %>

<%# Upload %>
<%= rui_button("Upload Files", color: :primary) do |button| %>
  <% button.with_icon(name: "upload") %>
<% end %>
```

### In Forms

Use icons with form submit buttons:

```erb
<%= form_with model: @post do |f| %>
  <%= f.text_field :title %>
  <%= f.text_area :content %>

<%# Submit button with icon %>
  <%= f.rui_button("Publish Post", color: :success) do |button| %>
    <% button.with_icon(name: "send", position: :trailing) %>
  <% end %>

<%# Draft button with icon %>
  <%= f.rui_button("Save Draft", variant: :outline) do |button| %>
    <% button.with_icon(name: "save") %>
  <% end %>
<% end %>
```

**Note:** Icons inherit the button's color automatically. Browse 1500+ available icons at [https://lucide.dev/icons](https://lucide.dev/icons).

## In Rails Forms

The button automatically detects form context and sets `type="submit"` with auto-generated labels:

```erb
<%= form_with model: @user do |f| %>
  <%# Auto-labeled: generates "Create User" or "Update User" %>
  <%= f.rui_button %>

<%# Custom text (positional argument) %>
  <%= f.rui_button("Save Changes", color: :success) %>

<%# Multiple submit buttons with formmethod %>
  <%= f.rui_button("Save Draft", formmethod: :post) %>
  <%= f.rui_button("Publish", formmethod: :patch, color: :success) %>
<% end %>
```

**Note:** For RESTful actions outside forms (DELETE, PATCH, etc.), use `rui_button_to` instead.

---

## Multiple Submit Buttons

Use `name` and `value` attributes to identify which button was clicked in your controller:

```erb
<%= form_with model: @post do |f| %>
  <%= f.text_field :title %>
  <%= f.text_area :content %>

<%= f.rui_button("Save Draft",
                   name: :commit,
                   value: "draft",
                   variant: :outline) %>

<%= f.rui_button("Publish",
                   name: :commit,
                   value: "publish",
                   color: :success) %>
<% end %>
```

**In your controller:**

```ruby
def create
  @post = Post.new(post_params)

case params[:commit]
  when "publish"
    @post.published = true
    @post.published_at = Time.current
  when "draft"
    @post.published = false
  end

if @post.save
    redirect_to @post
  else
    render :new
  end
end
```

**Why this works:**
- Each button sends `params[:commit]` with its `value`
- Controller logic branches based on which button was clicked
- Standard Rails pattern for multiple submit buttons

---

## Advanced Form Features

### Skip Validation (Save Draft Pattern)

Use `formnovalidate` to skip HTML5 validation for specific buttons:

```erb
<%= form_with model: @post do |f| %>
  <%= f.text_field :title, required: true %>
  <%= f.text_field :author, required: true %>

<%# Skips validation - allows saving with empty fields %>
  <%= f.rui_button("Save Draft",
                   name: :commit,
                   value: "draft",
                   formnovalidate: true,
                   variant: :outline) %>

<%# Normal validation applies %>
  <%= f.rui_button("Publish",
                   name: :commit,
                   value: "publish",
                   color: :success) %>
<% end %>
```

**How it works:** The browser automatically skips HTML5 validation (required, pattern, etc.) when clicking the button with `formnovalidate`. No JavaScript needed!

---

### Override Form Action (Multiple Endpoints)

Submit to different URLs from the same form:

```erb
<%= form_with model: @post do |f| %>
  <%= f.text_field :title %>

<%= f.rui_button("Save") %>

<%= f.rui_button("Preview",
                   formaction: preview_post_path(@post),
                   variant: :outline) %>

<%= f.rui_button("Email Preview",
                   formaction: email_preview_post_path(@post),
                   formtarget: "_blank",
                   variant: :ghost) %>
<% end %>
```

**Use cases:**
- Save vs Preview
- Generate PDF in new tab
- Send test email
- Export data

---

### Open in New Window

Use `formtarget` to control where form response opens:

```erb
<%= f.rui_button("Generate PDF",
                formaction: pdf_post_path(@post),
                formtarget: "_blank") %>

<%= f.rui_button("Print Preview",
                formaction: print_path,
                formtarget: "_blank",
                variant: :outline) %>
```

**Options:**
- `_blank` - New window/tab
- `_self` - Same window (default)
- `_parent` - Parent frame
- `_top` - Top-level frame
- Custom iframe name

---

### Associate Button with External Form

Use HTML5 `form_id` to associate a button with a form anywhere on the page:

```erb
<%# Button at top of page %>
<div class="sticky top-0 bg-white border-b p-4">
  <%= rui_button("Save Changes",
                form_id: "post-form",
                color: :success) %>
</div>

<%# Form further down the page %>
<%= form_with model: @post, id: "post-form" do |f| %>
  <%= f.text_field :title %>
  <%= f.text_area :content, rows: 20 %>
  
<% end %>
```

**Use cases:**
- Sticky headers with save button
- Split layouts
- Multi-column forms
- Floating action buttons

---

### Override Form Encoding

```erb
<%= f.rui_button("Upload Files",
                formenctype: "multipart/form-data") %>
```

**Note:** Rarely needed - forms usually handle this automatically with `file_field`.

---

## Block Content (Custom Layouts)

Use block syntax for complex button content:

```erb
<%# Icon + text %>
<%= rui_button(color: :primary) do %>
  <svg class="w-4 h-4 mr-2 inline-block">
    <path d="M5 13l4 4L19 7"/>
  </svg>
  <span>Save Changes</span>
<% end %>

<%# Multi-line button %>
<%= rui_button(size: :lg) do %>
  <span class="block text-xs text-zinc-400">Step 3 of 5</span>
  <span class="block font-semibold text-lg">Complete Setup</span>
<% end %>

<%# Badge + text %>
<%= rui_button(variant: :ghost) do %>
  <span>Messages</span>
  <span class="ml-2 px-2 py-0.5 bg-red-500 text-white text-xs rounded-full">
    3
  </span>
<% end %>

<%# Loading state (custom) %>
<%= rui_button(color: :success, data: { controller: "async-button" }) do %>
  <span data-async-button-target="icon" class="hidden">
    <svg class="animate-spin w-4 h-4">...</svg>
  </span>
  <span data-async-button-target="text">Submit</span>
<% end %>
```

**Note:** When using block content, `text` parameter is ignored.

---

## API Reference

| Option          | Type         | Description                                         | Default       |
|---------------- | ------------|-----------------------------------------------------|---------------|
| **Content** |
| `text`          | String       | Button label text. **Supports both positional (`rui_button("Text")`) and keyword (`text: "Text"`) styles.** Auto-generated in forms if not provided. | `nil` |
| **Styling** |
| `variant`       | Symbol       | `:solid`, `:outline`, `:ghost`, `:soft`, `:link`    | `:solid`      |
| `color`         | Symbol       | Any color in `COLOR_MAPPINGS` (e.g., `:primary`)    | `:primary`    |
| `size`          | Symbol       | `:xs`, `:sm`, `:base`, `:md`, `:lg`, `:xl`          | `:sm`         |
| `shape`         | Symbol       | `:rounded`, `:pill`, `:square`, `:circle`           | `:rounded`    |
| `full_width`    | Boolean      | Makes button take full container width              | `false`       |
| **States** |
| `loading`       | Boolean      | Shows loading spinner and disables interaction      | `false`       |
| `disabled`      | Boolean      | Disables the button                                 | `false`       |
| **Form Context** (Internal - passed by FormBuilder) |
| `form`          | FormBuilder  | Form builder context (automatically passed by `f.rui_button`) | `nil` |
| `object`        | ActiveRecord | Model object for auto-labeling                      | `nil`         |
| **Form Attributes** (Phase 1 - Multiple Submit Buttons) |
| `name`          | String/Symbol | Button name attribute (sent in params when clicked) | `nil`         |
| `value`         | String       | Button value (sent with name in params)              | `nil`         |
| **Form Attributes** (Phase 2 - Advanced Features) |
| `formmethod`    | Symbol       | Override form HTTP method: `:get`, `:post`, `:patch`, `:put`, `:delete` | `nil` |
| `formaction`    | String       | Override form action URL for this button            | `nil`         |
| `formtarget`    | String       | Where to open form response: `_blank`, `_self`, `_parent`, `_top` | `nil` |
| `form_id`       | String       | Associate button with form by ID (HTML5)            | `nil`         |
| `formnovalidate` | Boolean     | Skip HTML5 form validation when this button is clicked | `false`   |
| `formenctype`   | String       | Override form encoding: `multipart/form-data`, etc. | `nil`         |

---

## CSS Architecture

RapidRailsUI Button component uses RapidCascade (RC) CSS variables with data attributes for colors:

```html

<button class="rui-btn rui-btn--solid rui-btn--md rui-btn--rounded" data-color="primary">
  <span class="rui-btn__text">Primary Button</span>
</button>

<button class="rui-btn rui-btn--solid rui-btn--md rui-btn--rounded rui-btn--primary">
  <span class="rui-btn__text">Primary Button</span>
</button>
```

### Color System Architecture

The color system is organized into three layers:

1. **Color Palettes** (`app/assets/stylesheets/rapidrailsui/utilities/colors-palettes.css`)
   - Defines all available colors (Tailwind colors + custom palettes)
   - Example: `--color-boulder-500`, `--color-blue-700`

2. **Semantic Mappings** (`app/assets/stylesheets/rapidrailsui/utilities/colors-semantic.css`)
   - Maps semantic names to actual colors based on configuration
   - Example: `--color-primary-500: var(--color-boulder-500)`
   - Auto-generated by `rails rapidrailsui:update_colors`

3. **Component Colors** (`app/assets/stylesheets/rapidrailsui/utilities/colors-components.css`)
   - UI-specific colors for backgrounds, borders, etc.

### Changing Colors

To change your app's colors:

1. **Edit configuration** in `config/initializers/rapidrailsui.rb`:
   ```ruby
   config.colors = {
     primary: 'blue',    # Change from default
     secondary: 'rose',  # Change from default
     accent: 'amber'     # Change from default
   }
   ```

2. **Run the rake task**:
   ```bash
   rails rapidrailsui:update_colors
   ```

3. **Restart your server** and all components will use the new colors!

### Available Color Palettes

**RapidCascade (RC) Colors:**
slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose

**Custom Brand Palettes:**
boulder, tradewind, punch, light-orchid, dust-storm, butterfly-bush

---

## Accessibility
- Uses appropriate ARIA roles and keyboard navigation
- Automatically handles aria-busy for loading states
- Proper disabled state handling with aria-disabled
- External links include proper security attributes

---

## Customization
- You can extend or override styles using the `classes` option.
- Customize colors by defining CSS variables in your theme.
- All styles are customizable by defining CSS variables.

---

## See Also
- [Button Styles](./styles.rb)
- [Button Component](./component.rb)
- [CSS Variables](../../assets/stylesheets/rapidrailsui/utilities/colors.css)

---

For more examples, see the component previews and test files.

---

## Button To (`rui_button_to`)

# RapidRailsUI ButtonTo Component Usage

The `ButtonTo` component renders a `<form><button></form>` wrapper for RESTful actions. It works exactly like Rails' `button_to` helper but with full RapidRailsUI styling.

**Use this for:** POST, PATCH, PUT, DELETE requests
**For navigation:** Use Rails `link_to`
**For form submissions:** Use `f.rui_button` within `form_with`

---

## Basic Usage

The `method:` parameter is **required** for clarity:

```erb

<%= rui_button_to("Delete Post", post_path(@post), method: :delete) %>
<%= rui_button_to("Publish", publish_post_path(@post), method: :patch) %>

<%= rui_button_to(text: "Delete Post", url: post_path(@post), method: :delete) %>
```

**Note:** Both positional and keyword argument styles are supported. The positional style is recommended as it's more concise and Rails-like.

---

## With Confirmation

Use Turbo's `data-turbo-confirm` for confirmation dialogs:

```erb
<%# Keyword style (recommended) %>
<%= rui_button_to("Delete Account",
      user_path(@user),
      method: :delete,
      turbo_confirm: "Are you sure? This cannot be undone.") %>

<%# Data hash style (also supported) %>
<%= rui_button_to("Delete Account",
      user_path(@user),
      method: :delete,
      data: { turbo_confirm: "Are you sure? This cannot be undone." }) %>
```

Both styles place `data-turbo-confirm` on the `<form>` element where Turbo expects it.

---

## Styling Options

All button styling options are supported:

### Variants & Colors

```erb
<%= rui_button_to("Delete", post_path(@post),
      method: :delete,
      variant: :solid,
      color: :danger) %>

<%= rui_button_to("Archive", archive_path(@post),
      method: :patch,
      variant: :outline,
      color: :secondary) %>
```

### Sizes & Shapes

```erb

<%= rui_button_to("Remove", item_path(@item),
      method: :delete,
      size: :sm,
      color: :danger) %>

<%= rui_button_to("Subscribe", subscribe_path,
      method: :post,
      shape: :pill,
      color: :success) %>
```

---

## Common Patterns

### Delete Actions

```erb
<%= rui_button_to("Delete", post_path(@post),
      method: :delete,
      color: :danger,
      size: :sm,
      data: { turbo_confirm: "Are you sure?" }) %>
```

### Publish/Archive Actions

```erb
<div class="flex gap-2">
  <%= rui_button_to("Publish", publish_post_path(@post),
        method: :patch,
        color: :success) %>

<%= rui_button_to("Archive", archive_post_path(@post),
        method: :patch,
        variant: :outline,
        color: :secondary) %>
</div>
```

### With Additional Parameters

```erb
<%= rui_button_to("Approve", approve_path(@request),
      method: :post,
      params: { status: "approved", notify: true },
      color: :success) %>
```

---

## Loading & Disabled States

```erb
<%= rui_button_to("Processing...", process_path,
      method: :post,
      loading: true) %>

<%= rui_button_to("Delete", post_path(@post),
      method: :delete,
      disabled: true) %>
```

---

## Full Width

```erb
<%= rui_button_to("Delete Account", user_path(@user),
      method: :delete,
      full_width: true,
      color: :danger) %>
```

---

## Form Options

### Custom Form Class

```erb
<%= rui_button_to("Delete", post_path(@post),
      method: :delete,
      form_class: "inline-block") %>
```

### Turbo/AJAX Support

```erb
<%= rui_button_to("Like", like_post_path(@post),
      method: :post,
      remote: true) %>
```

### CSRF Token Control

```erb

<%= rui_button_to("Public Action", public_path,
      method: :post,
      authenticity_token: false) %>
```

---

## With Icons

Add icons to buttons using the icon slot. Icons automatically inherit the button's color.

**Requires:** The `lucide-rails` gem must be installed to use icons. See [Icon Component](../icon/USAGE.md) for details.

### Common RESTful Action Icons

```erb
<%# Delete action with trash icon %>
<%= rui_button_to("Delete Post", post_path(@post),
      method: :delete,
      color: :danger) do |button| %>
  <% button.with_icon(name: "trash-2") %>
<% end %>

<%# Publish action with send icon %>
<%= rui_button_to("Publish", publish_post_path(@post),
      method: :patch,
      color: :success) do |button| %>
  <% button.with_icon(name: "send", position: :trailing) %>
<% end %>

<%# Archive action with archive icon %>
<%= rui_button_to("Archive", archive_post_path(@post),
      method: :patch,
      variant: :outline) do |button| %>
  <% button.with_icon(name: "archive") %>
<% end %>
```

### Leading Icons (Default)

Icons appear before the text by default:

```erb
<%# Add/Create actions %>
<%= rui_button_to("Add to Cart", add_to_cart_path(@product),
      method: :post,
      color: :primary) do |button| %>
  <% button.with_icon(name: "shopping-cart") %>
<% end %>

<%# Download action %>
<%= rui_button_to("Download", download_path(@file),
      method: :post,
      variant: :outline) do |button| %>
  <% button.with_icon(name: "download") %>
<% end %>

<%# Lock action %>
<%= rui_button_to("Lock Account", lock_user_path(@user),
      method: :patch,
      variant: :outline,
      color: :warning) do |button| %>
  <% button.with_icon(name: "lock") %>
<% end %>
```

### Trailing Icons

Icons appear after the text when using `position: :trailing`:

```erb
<%# Logout with trailing icon %>
<%= rui_button_to("Sign Out", logout_path,
      method: :delete,
      variant: :ghost) do |button| %>
  <% button.with_icon(name: "log-out", position: :trailing) %>
<% end %>

<%# External link indicator %>
<%= rui_button_to("Open External", external_path,
      method: :post,
      variant: :link) do |button| %>
  <% button.with_icon(name: "external-link", position: :trailing) %>
<% end %>

<%# Next action %>
<%= rui_button_to("Continue", next_step_path,
      method: :post,
      color: :primary) do |button| %>
  <% button.with_icon(name: "arrow-right", position: :trailing) %>
<% end %>
```

### Icon Color Override

Icons automatically inherit the button's color, but you can override with a custom color:

```erb
<%# Icon inherits button color (default behavior) %>
<%= rui_button_to("Delete", post_path(@post),
      method: :delete,
      color: :danger) do |button| %>
  <% button.with_icon(:trash_2) %>
  <%# Icon will be danger color %>
<% end %>

<%# Icon with custom color (overrides inheritance) %>
<%= rui_button_to("Archive", archive_path(@post),
      method: :patch,
      color: :primary) do |button| %>
  <% button.with_icon(:archive, color: :yellow) %>
  <%# Primary button with yellow archive icon %>
<% end %>

<%# Useful for warning actions %>
<%= rui_button_to("Mark as Spam", spam_path(@comment),
      method: :patch,
      variant: :outline) do |button| %>
  <% button.with_icon(:alert_triangle, color: :red) %>
  <%# Outlined button with red warning icon %>
<% end %>
```

**Note:** When you provide an explicit `color:` parameter to the icon, it uses standalone mode and renders with its own color instead of inheriting from the button.

### Common Action Patterns

```erb
<%# Approve/Reject %>
<div class="flex gap-2">
  <%= rui_button_to("Approve", approve_path(@request),
        method: :patch,
        color: :success,
        size: :sm) do |button| %>
    <% button.with_icon(name: "check") %>
  <% end %>

<%= rui_button_to("Reject", reject_path(@request),
        method: :patch,
        color: :danger,
        size: :sm,
        variant: :outline) do |button| %>
    <% button.with_icon(name: "x") %>
  <% end %>
</div>

<%# Like/Unlike %>
<%= rui_button_to("Like", like_post_path(@post),
      method: :post,
      variant: :ghost,
      color: :danger) do |button| %>
  <% button.with_icon(name: "heart") %>
<% end %>

<%# Share %>
<%= rui_button_to("Share", share_path(@post),
      method: :post,
      variant: :outline) do |button| %>
  <% button.with_icon(name: "share-2") %>
<% end %>

<%# Star/Favorite %>
<%= rui_button_to("Favorite", favorite_path(@item),
      method: :post,
      variant: :ghost,
      color: :warning) do |button| %>
  <% button.with_icon(name: "star") %>
<% end %>
```

### With Confirmation

Combine icons with confirmation dialogs:

```erb
<%= rui_button_to("Delete Account", user_path(@user),
      method: :delete,
      color: :danger,
      turbo_confirm: "Are you sure? This cannot be undone.") do |button| %>
  <% button.with_icon(name: "trash-2") %>
<% end %>
```

**Note:** Icons inherit the button's color automatically. Browse 1500+ available icons at [https://lucide.dev/icons](https://lucide.dev/icons).

---

## Block Content (Custom Layouts)

Use block syntax for badges or any custom HTML inside the button:

### Badge + Text

```erb
<%= rui_button_to(archive_posts_path, method: :post, variant: :outline) do %>
  <span>Archive All</span>
  <span class="ml-2 px-2 py-0.5 bg-zinc-500 text-white text-xs rounded-full">
    <%= @posts.count %>
  </span>
<% end %>
```

### Status Indicator

```erb
<%= rui_button_to(approve_path(@request), method: :patch, color: :success, variant: :soft) do %>
  <span class="inline-block w-2 h-2 bg-green-500 rounded-full mr-2 animate-pulse"></span>
  <span>Approve</span>
<% end %>
```

**Note:** When using block content, the `text` parameter is ignored. The block content becomes the button's inner HTML.

---

## API Reference

| Option                | Type         | Required | Description                                         | Default       |
|---------------------- | ------------ | -------- | --------------------------------------------------- | ------------- |
| `text`                | String       | *        | Button label text. **Supports both positional (`rui_button_to("Text", url)`) and keyword (`text: "Text"`) styles.** Optional when using block content. | "Submit"      |
| `url`                 | String/Path  | ✓        | URL or Rails path helper. **Supports both positional (2nd argument) and keyword (`url: path`) styles.** | -             |
| `method`              | Symbol       | ✓        | **Required keyword.** HTTP method: `:get`, `:post`, `:patch`, `:put`, `:delete` | - |
| `variant`             | Symbol       |          | `:solid`, `:outline`, `:ghost`, `:soft`, `:link`    | `:solid`      |
| `color`               | Symbol       |          | Any color (e.g., `:primary`, `:danger`, `:success`) | `:primary`    |
| `size`                | Symbol       |          | `:xs`, `:sm`, `:base`, `:md`, `:lg`, `:xl`          | `:sm`         |
| `shape`               | Symbol       |          | `:rounded`, `:pill`, `:square`, `:circle`           | `:rounded`    |
| `full_width`          | Boolean      |          | Makes button take full container width              | `false`       |
| `loading`             | Boolean      |          | Shows loading state                                 | `false`       |
| `disabled`            | Boolean      |          | Disables the button                                 | `false`       |
| `form_class`          | String       |          | CSS class for the `<form>` wrapper                  | `"button_to"` |
| `params`              | Hash         |          | Additional hidden form parameters                   | `nil`         |
| `remote`              | Boolean      |          | Submit via Turbo/AJAX                               | `false`       |
| `authenticity_token`  | Boolean/String |        | CSRF token control (`false` to skip, string for custom) | `nil`     |
| `turbo_confirm`       | String         |        | Confirmation message (placed on `<form>` for Turbo)     | `nil`     |
| `turbo_frame`         | String         |        | Target Turbo Frame ID                                   | `nil`     |
| `turbo_stream`        | Boolean        |        | Request Turbo Stream response                           | `nil`     |
| `turbo_action`        | String         |        | Turbo navigation action (`"advance"`, `"replace"`)      | `nil`     |

---

## How It Works

Under the hood, `rui_button_to` generates:

```html
<form class="button_to" action="/posts/1" method="post"
      data-turbo-confirm="Are you sure?" data-turbo-frame="_top">
  <input type="hidden" name="authenticity_token" value="...">
  <input type="hidden" name="_method" value="delete">
  <button type="submit" class="..." data-turbo-submits-with="Deleting...">Delete</button>
</form>
```

Turbo attributes (`turbo_confirm`, `turbo_frame`, `turbo_stream`, `turbo_action`) are placed on the `<form>` element where Turbo expects them. Button-level attributes like `loading_text` (`data-turbo-submits-with`) stay on the `<button>`.

This allows:
- RESTful DELETE/PATCH/PUT via POST forms (Rails method spoofing)
- Single-click actions without writing form boilerplate
- CSRF protection
- Turbo/AJAX support with correct attribute placement

---

## See Also

- [Button Component](../button/USAGE.md) - For `<button>` elements and form submissions
- [ButtonTo Styles](../button/styles.rb) - Shared styling with button component
- [Rails button_to Guide](https://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-button_to)

---

For more examples, see the component previews and test files.

---

## Card (`rui_card`)

# Card Component

A flexible, plug-and-play card system. Every slot is optional and every
piece is removable — the card still looks right with any subset gone.

**Tier:** Starter

## Basic usage

```erb
<%= rui_card do |c| %>
  <% c.with_icon(name: "clock") %>
  <% c.with_header(title: "Timed Online") %>
  <% c.with_body do %>
    A flexible online sale format that allows buyers more time to review and bid.
  <% end %>
<% end %>
```

Slots render in a fixed order: `media` → `icon`/`header` → `body` → divider
→ `list` → `footer`. Skip any slot you don't need.

## Reference recipes

These four cover the common StockLive card shapes.

### Full card

Icon tile → heading → muted description → divider → checklist → footer bar.

```erb
<%= rui_card(variant: :elevated, color: :accent) do |c| %>
  <% c.with_icon(name: "clock") %>
  <% c.with_header(title: "Timed Online") %>
  <% c.with_body do %>
    A flexible online sale format that allows buyers more time to review and bid.
  <% end %>
  <% c.with_list do |l| %>
    <% l.with_item(text: "Keeps buyers active with outbid alerts") %>
    <% l.with_item(text: "Set and forget max bid functionality") %>
  <% end %>
  <% c.with_footer(text: "Enquire now", href: "/enquire", arrow: :right) %>
<% end %>
```

### Compact horizontal

Icon tile on the left, title + description beside it. No divider, no footer.

```erb
<%= rui_card do |c| %>
  <% c.with_icon(name: "headphones", color: :warning, placement: :inline) %>
  <% c.with_header(title: "Strong sale-day support", subtitle: "Dedicated support from listing to final result.") %>
<% end %>
```

### Simple

Icon tile → heading → description. Nothing else — no list, no footer, no
divider.

```erb
<%# Shortcut API — no block needed for the common case %>
<%= rui_card(title: "Advertise with Us", description: "Reach the people driving Australian agriculture", icon: "megaphone") %>
```

### Service CTA card

Header + body + highlights list + CTA footer — no icon tile. This is the
`rui_card` equivalent of a hand-rolled `_service_cta_card` partial.

```erb
<%= rui_card do |c| %>
  <% c.with_header(title: "Livestock Selling") %>
  <% c.with_body(text: "Full-service selling for producers, from listing to settlement.") %>
  <% c.with_list do |l| %>
    <% l.with_item(text: "National buyer network") %>
    <% l.with_item(text: "Weekly market reports") %>
  <% end %>
  <% c.with_footer(text: "Get started", href: "/start") %>
<% end %>
```

## Slots

All slots are optional. Order is fixed regardless of the order you call
`with_*` in.

### `icon`

A tinted rounded-square tile. Accepts a lucide `name:` or a content block for
custom markup.

```erb
<% c.with_icon(name: "clock") %>
<% c.with_icon(name: "headphones", color: :warning, placement: :inline) %>
<% c.with_icon do %>
  <span class="text-2xl font-bold">42</span>
<% end %>
```

| Param | Type | Default | Notes |
|---|---|---|---|
| `name:` | String/Symbol | `nil` | Lucide icon name. Omit to use the block instead. |
| `color:` | Symbol | card's `color:` | Semantic color — tinted 100 bg / 900 icon (light), 900 bg / 300 icon (dark). |
| `placement:` | Symbol | `:top` | `:top` (own row above the header) or `:inline` (flex row beside the header). |

### `header`

```erb
<% c.with_header(title: "Timed Online") %>
<% c.with_header(title: "Support", subtitle: "Dedicated support from listing to final result.") %>
<% c.with_header(title: "Section", as: :h2) %>
```

| Param | Type | Default | Notes |
|---|---|---|---|
| `title:` | String | — | Required in-slot. |
| `subtitle:` | String | `nil` | Muted text under the title. |
| `as:` | Symbol | `:h3` | Heading tag (`:h1`–`:h6`). Adjust to fit the page's document outline. |

### `body`

Muted description text. `text:` param or block content — same
block-or-text pattern as Alert's message slot.

```erb
<% c.with_body(text: "A flexible online sale format.") %>
<% c.with_body do %>
  A flexible online sale format that allows buyers more time to review and bid.
<% end %>
```

### `list`

Checklist rows with circled-icon tiles. `list` yields *itself* to the block
(not content) so you can call `with_item` repeatedly — same pattern as
`rui_kanban`'s `with_column`.

```erb
<% c.with_list do |l| %>
  <% l.with_item(text: "Keeps buyers active with outbid alerts") %>
  <% l.with_item(text: "Set and forget max bid functionality") %>
  <% l.with_item(text: "Custom icon per item", icon: "star", color: :warning) %>
<% end %>
```

| Param (`with_item`) | Type | Default | Notes |
|---|---|---|---|
| `text:` | String | — | Required. |
| `icon:` | String/Symbol | `"check"` | Lucide icon name for the tile. |
| `color:` | Symbol | list/card `color:` | Overrides the tile tint for this one item. |

A divider renders above the list automatically when a `header` or `body`
precedes it — nothing to divide from otherwise. Pass `divider: false` on the
card to suppress it entirely:

```erb
<%= rui_card(divider: false) do |c| %>
  <% c.with_header(title: "T") %>
  <% c.with_list { |l| l.with_item(text: "No divider above this list") } %>
<% end %>
```

### `media`

An image flush to the card's top edge. Corners follow the card's own
`shape:` (clipped via `overflow-hidden` on the root — no per-slot rounding
needed).

```erb
<% c.with_media(src: "/sales/olive-grove.jpg", alt: "Olive Grove yards", aspect: :video) %>
```

| Param | Type | Default | Notes |
|---|---|---|---|
| `src:` | String | — | Required. |
| `alt:` | String | `""` | Empty string for decorative images. |
| `aspect:` | Symbol | `:video` | `:video` (16:9), `:square`, `:wide` (21:9), or `:none`. |

### `footer`

A full-width bar: muted background, top border, semibold link with an arrow.
`text:`/`href:`/`arrow:` params, or a block to override the content entirely
(the bar wrapper itself always renders).

```erb
<% c.with_footer(text: "Enquire now", href: "/enquire", arrow: :right) %>
<% c.with_footer(text: "Back", href: "/back", arrow: :left) %>
<% c.with_footer(text: "Learn more") %>              <%# no href = plain text, no link %>
<% c.with_footer do %>
  <%= rui_button("Enquire now", href: "/enquire", size: :sm) %>
<% end %>
```

| Param | Type | Default | Notes |
|---|---|---|---|
| `text:` | String | `nil` | Omit when using a block. |
| `href:` | String | `nil` | Renders a link. Omit for plain styled text. |
| `arrow:` | Symbol | `:right` | `:right`, `:left` (flips which side the arrow renders on), or `:none`. |
| `color:` | Symbol | card `color:` | Link color. |

**Whole-card link + footer interaction:** when the card itself is a link
(`href:` on `rui_card`), the footer never nests a second `<a>` — invalid
HTML, and unusable for assistive tech. It automatically degrades to styled
text with the same arrow icon instead.

## Card options

```ruby
rui_card(
  variant: :elevated,   # :elevated (default, white bg + border + shadow) | :outline | :flat | :soft (tinted bg from color)
  shape: :rounded,      # :rounded (default) | :square | :pill — same vocabulary as carousel
  padding: :md,         # :none | :sm | :md (default) | :lg
  color: :primary,      # semantic color for icon tile / soft variant / footer link / list tiles
  href: nil,            # wraps the whole card in a single <a>
  divider: true,        # show the divider above the list slot
  class: nil            # merged with the root classes via tailwind_merge
) do |c|
  # ...slots
end
```

### `variant:`

| Variant | Look |
|---|---|
| `:elevated` (default) | White background, subtle border, `shadow-sm`. |
| `:outline` | Transparent background, visible border, no shadow. |
| `:flat` | Solid muted background (`zinc-50`/`zinc-800`), no shadow. |
| `:soft` | Background tinted from `color:` (e.g. `color: :success` → pale green card). |

### `href:` — whole-card link mode

```erb
<%= rui_card(href: "/lots/482", title: "Lot 482 — Angus Steers") do |c| %>
  <% c.with_body(text: "45 head, 380-420kg, Wagga Wagga NSW.") %>
<% end %>
```

- Root element becomes `<a href="...">` instead of `<div>`.
- Hover gets a shadow lift (`hover:shadow-lg`).
- `aria-label` is set from the header's `title:` (or the shortcut `title:`
  param) — without it, a screen reader would read the *entire* card's text
  (heading, description, every list item, footer) as one link name.
- Any `footer` slot degrades to styled text (see above) — never a nested `<a>`.

## Shortcut API

For the common icon + heading + description case, skip the block entirely:

```erb
<%= rui_card(title: "Advertise with Us", description: "Reach the people driving Australian agriculture", icon: "megaphone") %>
```

Equivalent to:

```erb
<%= rui_card do |c| %>
  <% c.with_icon(name: "megaphone") %>
  <% c.with_header(title: "Advertise with Us") %>
  <% c.with_body(text: "Reach the people driving Australian agriculture") %>
<% end %>
```

`href:` combines with the shortcut API too — the whole card becomes a link
and `aria-label` is set from `title:` automatically. Explicit `with_icon` /
`with_header` / `with_body` calls in a block always win over the shortcut
params if you use both (unlikely, but the shortcut never overwrites a slot
you set explicitly).

## Behaviour notes

- **No JS controller.** Pure server-rendered, including dark mode — nothing
  to hydrate, no Stimulus identifier.
- **Semantic colors resolve through `ColorBuilderHelper`.** `color: :accent`
  follows `RapidRailsUI.config.colors[:accent]` if your app remaps it (e.g.
  StockLive's `primary` → `midnight`, `accent` → `brand_sky`), same as every
  other RUI component.
- **Borders always pair `border` + `border-solid` + a color class.** Never
  a width-only utility — see the combobox lesson in this repo's `dev_docs`:
  width-only border utilities die under a host's `button, a { border: 0 }`
  reset because that shorthand also zeroes `border-style`. This matters here
  because the card renders as `<a>` when `href:` is set.
- **List items inherit color from the list, which inherits from the card**,
  unless you override per-item. All three checklist icons in the full-card
  recipe above share the card's `color: :accent` tint without repeating it.

## Common pitfalls

1. **Forgetting `alt:` on `media`.** Defaults to `""` (decorative). Set a
   real `alt:` for images that convey information the surrounding text
   doesn't already state.
2. **Passing `href:` on both the card and the footer and expecting two
   links.** The footer intentionally degrades to plain text in this case —
   nested `<a>` elements are invalid HTML.
3. **Expecting a divider above a `list` with nothing before it.** By design,
   a divider only renders when there's a `header` or `body` above the list
   to separate it from. A card with only a list slot has no divider.
4. **Custom `variant:` styling.** Variants only set the background/border
   look. To change the icon tile or footer link color, pass `color:` — don't
   fork the variant.

## Out of scope (v0.51)

- Multi-image media (carousel inside a card — compose `rui_carousel` +
  `rui_card` manually if you need this).
- Collapsible/expandable card bodies.
- Card-level loading/skeleton state.

---

## Carousel (`rui_carousel`)

# Carousel Component

A flexible, accessible slide carousel built on CSS scroll-snap and a single
Stimulus controller. One component, six variants, fully responsive.

**Tier:** Pro

## Basic usage

```erb
<%= rui_carousel(id: "promo") do |c| %>
  <% c.with_slide(label: "First") do %>
    <img src="/banners/1.jpg" alt="First slide" loading="lazy" />
  <% end %>
  <% c.with_slide(label: "Second") do %>
    <img src="/banners/2.jpg" alt="Second slide" loading="lazy" />
  <% end %>
<% end %>
```

`id:` is required. Arrows and indicators are auto-suppressed when fewer than
two slides are present.

## Variants

| Variant | Use case | Default `items_per_view` | Arrows | Arrow position | Indicator position |
|---|---|---|---|---|---|
| `:default` | Generic 1-up | `1` | yes | `:sides` | `:outside` |
| `:banner` | Full-bleed promo | `1` | no | `:overlay` | `:overlay_bottom_right` |
| `:hero` | Full-bleed marketing | `1` | no | `:overlay` | `:overlay_bottom_right` |
| `:cards` | Multi-card slider | `{ base: 1, sm: 2, md: 3 }` | yes | `:outside` | `:outside` |
| `:testimonials` | Quote cards | `{ base: 1, md: 3 }` | yes | `:outside` | `:outside` |
| `:fullscreen` | 100vh marketing splash | `1` | yes | `:overlay` | `:overlay_bottom` |

Every variant default is overridable by passing the corresponding kwarg.

### Banner (full-bleed promo)

```erb
<%= rui_carousel(id: "olive-grove", variant: :banner, auto_rotate: true, interval: 6000) do |c| %>
  <% c.with_slide(label: "Olive Grove 2026 Bull Sale") do %>
    <div class="relative">
      <img src="/sales/olive-grove.jpg" alt="" class="w-full h-[480px] object-cover" loading="lazy" />
      <div class="absolute bottom-12 left-12 text-white">
        <h2 class="text-4xl font-bold">Olive Grove</h2>
        <p class="text-xl">2026 Bull Sale — May 14</p>
      </div>
    </div>
  <% end %>
<% end %>
```

### Hero (cattle hero pattern)

```erb
<%= rui_carousel(id: "hero", variant: :hero, auto_rotate: true) do |c| %>
  <% c.with_slide(label: "Premium genetics") do %>
    <div class="relative h-[600px]">
      <img src="/hero/cattle.jpg" alt="" class="w-full h-full object-cover" loading="eager" />
      <div class="absolute inset-0 bg-black/40"></div>
      <div class="absolute inset-0 flex items-center justify-center text-center text-white px-8">
        <div>
          <h1 class="text-5xl font-bold">Premium genetics, proven performance</h1>
          <p class="mt-4 text-xl">Australia’s most trusted bull network</p>
          <%= rui_button("Browse Bulls", color: :primary, size: :lg, class: "mt-6") %>
        </div>
      </div>
    </div>
  <% end %>
<% end %>
```

### Testimonials (3-up on `md+`)

```erb
<%= rui_carousel(id: "quotes", variant: :testimonials, color: :emerald) do |c| %>
  <% @testimonials.each do |t| %>
    <% c.with_slide(label: t.author) do %>
      <article class="p-6 bg-white dark:bg-zinc-900 rounded-xl border">
        <div class="flex gap-1 text-amber-500"><%= "★" * t.rating %></div>
        <p class="mt-3 text-zinc-700 dark:text-zinc-300"><%= t.body %></p>
        <p class="mt-4 font-medium"><%= t.author %></p>
      </article>
    <% end %>
  <% end %>
<% end %>
```

### Cards (responsive multi-card)

```erb
<%= rui_carousel(id: "products", variant: :cards, items_per_view: { base: 1, sm: 2, lg: 4 }) do |c| %>
  <% @products.each do |p| %>
    <% c.with_slide(label: p.name) do %>
      <%= render p %>
    <% end %>
  <% end %>
<% end %>
```

### Fullscreen marketing splash

```erb
<%= rui_carousel(id: "splash", variant: :fullscreen, loop: false) do |c| %>
  <% c.with_slide { render "splash/intro" } %>
  <% c.with_slide { render "splash/features" } %>
  <% c.with_slide { render "splash/cta" } %>
<% end %>
```

## API

```ruby
rui_carousel(
  id:,                              # required
  auto_rotate: false,
  interval: 5000,
  show_arrows: nil,                 # nil = use variant default
  show_indicators: true,
  loop: true,
  pause_on_hover: true,
  respect_reduced_motion: true,
  items_per_view: nil,              # nil = use variant default
  gap: :base,                       # :none | :sm | :base | :lg
  variant: :default,
  color: :primary,
  size: :base,                      # :sm | :base | :lg
  shape: :rounded,                  # :none | :rounded | :square | :pill
  indicator_position: nil,          # nil = use variant default
  arrow_position: nil,              # nil = use variant default
  aria_label: nil                   # defaults to "Carousel"
) do |c|
  c.with_slide(label: "Optional aria label for this slide") do
    # arbitrary block content
  end
end
```

## Behaviour notes

- **Auto-rotate** runs on a `setInterval`. It pauses on hover (when
  `pause_on_hover: true`), when the tab is hidden, and at boot when the OS
  prefers reduced motion (when `respect_reduced_motion: true`). Once
  paused for reduced-motion reasons, it stays paused across hover-leave and
  visibility events too — see the Reduced motion section below.
- **Loop** wraps the scroll position when reaching either boundary. With
  `loop: false`, the prev/next buttons are `aria-disabled="true"` and the
  HTML `disabled` attribute is set at the boundary.
- **Active slide detection** uses an `IntersectionObserver` on the track, so
  it works for click navigation, programmatic `goTo()`, native touch swipe,
  and trackpad scroll alike.
- **Touch swipe** is free via native scroll-snap. No JS gesture handling.
- **Keyboard nav**: focus the carousel region (`tabindex="0"`), then
  Arrow Left/Right to move slides, Home/End to jump.
- **Live region**: announces `Slide N of M` on every slide change via
  `aria-live="polite"`.
- **Lazy loading**: the carousel does NOT lazy-load slide content. Set
  `loading="lazy"` on your `<img>` tags yourself. The first slide should
  usually be `loading="eager"` to avoid LCP regressions.

## Reduced motion

When the user's OS sets `prefers-reduced-motion: reduce` AND
`respect_reduced_motion: true` (default), the carousel suppresses motion
**consistently across every state transition**:

- Auto-rotate does not start at boot.
- Auto-rotate does not resume after a hover-leave (`pause_on_hover: true`).
- Auto-rotate does not resume after the browser tab regains visibility.
- `scrollTo()` (arrow clicks, indicator clicks, keyboard nav, programmatic
  `goTo`) falls back from `behavior: "smooth"` to `behavior: "auto"`.

### Opting out (`respect_reduced_motion: false`)

Pass `respect_reduced_motion: false` when the carousel's motion is a
designed-and-approved part of the surface (e.g. a marketing hero with an
intentional auto-rotating splash) and you accept the accessibility
responsibility of overriding the OS preference. When this flag is `false`,
**every** motion gate above is bypassed: auto-rotate runs, resumes after
hover and visibility events, and slide transitions stay smooth, regardless of
the OS setting.

This is a per-instance opt-out. Use it sparingly — users set
`prefers-reduced-motion: reduce` for real reasons (vestibular disorders,
seizure triggers, attention-related conditions). If the carousel content is
informational rather than decorative, leave the default.

> Prior to v0.50.4, `respect_reduced_motion: false` only worked on initial
> connect; auto-rotate was silently re-suppressed after hover and tab-visibility
> events. Fixed in 0.50.4 — gate now consults
> `respect_reduced_motion` consistently in every state transition.

## Common pitfalls

1. **`id:` collisions.** Each carousel needs a unique DOM id; the indicator
   `aria-controls` and the focus ring rely on it.
2. **Forgetting `loading="lazy"` on images.** Slides outside the viewport are
   still in the DOM. Without `loading="lazy"` (or eager for the first slide),
   you'll fetch every image up front.
3. **Wrong breakpoint key.** `items_per_view: { md: 3 }` with no `base:` will
   still work (falls back to `1`), but be explicit: `{ base: 1, md: 3 }`.
4. **Custom `variant:` styling.** Variants only set defaults. To change e.g.
   the indicator dot colour on `:banner`, pass `color: :emerald` —
   don't fork the variant.

## Out of scope (v0.50)

- Vertical orientation.
- URL deep-linking (`#slide-3`).
- Video slide play/pause coordination.
- Per-slide analytics events — planned follow-up.

---

## Checkbox (`rui_checkbox`)

# Checkbox Component

## Overview
The Checkbox component provides flexible checkbox functionality for forms, supporting single checkboxes, checkbox collections, and multiple visual variants. It's designed to be **smart by default** — in form mode it auto-derives labels, generates unique IDs, and can auto-submit the form on change.

## Features
- Single checkbox with label and description
- Collection checkboxes from arrays or ActiveRecord relations
- **Five variants**: checkbox, switch, card, pill, button
- **Icon support** with `with_icon` slot
- Form builder integration (`f.rui_checkbox`)
- **Smart default labels** — auto-derived from model attribute name in form mode
- **Unique IDs** — includes record ID for persisted objects (prevents collisions in lists)
- **Auto-submit** — CSP-safe form submission on change via Stimulus
- **`input_html:`** — pass attributes directly to the `<input>` element
- **`label: false`** — suppress label rendering entirely
- Select all functionality with indeterminate state
- **All Tailwind colors** — semantic (primary, success, danger) + any Tailwind color (indigo, pink, violet, etc.)
- Five sizes (xs, sm, base, lg, xl)
- Two shapes (square, rounded)
- Vertical and horizontal layouts for collections
- Required field indicator
- Help text and error message display
- Full accessibility support (ARIA attributes, keyboard navigation)
- Dark mode support

## Variants

| Variant | Description | Best For |
|---------|-------------|----------|
| `:checkbox` | Standard checkbox with checkmark | Forms, agreements, settings |
| `:switch` | Toggle switch | On/off settings, feature toggles |
| `:card` | Bordered card with full-width click target | Pricing plans, feature selection |
| `:pill` | Compact, tag-like rounded selections | Filters, tags, categories |
| `:button` | Toolbar-style toggle controls | Formatting toolbars, view toggles |

## Basic Usage

### Single Checkbox

```ruby
# Standalone checkbox
<%= rui_checkbox(:terms, label: "I accept the terms and conditions") %>

# With form builder
<%= form_with(model: @user) do |f| %>
  <%= f.rui_checkbox(:terms_accepted, label: "I accept the terms") %>
<% end %>
```

### Smart Form Mode (Minimal API)

In form mode, the checkbox is smart enough to derive everything it needs from the model:

```ruby
<%= form_with(model: @user) do |f| %>
  <%# Label auto-derived from human_attribute_name ("Terms accepted") %>
  <%= f.rui_checkbox(:terms_accepted) %>

<%# Explicit label overrides the smart default %>
  <%= f.rui_checkbox(:terms_accepted, label: "I agree to the terms") %>

<%# Suppress the label entirely %>
  <%= f.rui_checkbox(:terms_accepted, label: false) %>
<% end %>
```

### Auto-Submit

Auto-submit the parent form when checkbox state changes. Uses Stimulus (`data-action="change->checkbox#submitForm"`) — CSP-safe, no inline JavaScript.

```ruby
<%# Inline todo toggle — one line, fully encapsulated %>
<%= form_with(model: todo) do |f| %>
  <%= f.rui_checkbox(:completed, label: todo.title, auto_submit: true) %>
<% end %>

<%# Settings toggle %>
<%= form_with(model: @user) do |f| %>
  <%= f.rui_checkbox(:notifications, variant: :switch, auto_submit: true) %>
<% end %>
```

### Unique IDs

When the object is persisted (has an `id`), the checkbox input ID automatically includes the record ID. This prevents ID collisions when rendering multiple forms on the same page (e.g. a todo list).

```ruby
<%# Generates id="todo_1_completed", id="todo_2_completed", etc. %>
<% @todos.each do |todo| %>
  <%= form_with(model: todo) do |f| %>
    <%= f.rui_checkbox(:completed, label: todo.title, auto_submit: true) %>
  <% end %>
<% end %>
```

### Collection Checkboxes

```ruby
# From ActiveRecord collection
<%= form_with(model: @user) do |f| %>
  <%= f.rui_checkbox(:category_ids, collection: Category.all, label: "Select categories") %>
<% end %>

# With select all
<%= form_with(model: @user) do |f| %>
  <%= f.rui_checkbox(:interest_ids,
    collection: Interest.all,
    label: "Your interests",
    select_all: true) %>
<% end %>
```

### Switch Variant

```ruby
<%= rui_checkbox(:notifications, label: "Enable notifications", variant: :switch) %>
```

## Rails-Compatible API

`rui_checkbox` also accepts standard Rails positional argument patterns for collection checkboxes.

### Positional choices

```ruby
<%= f.rui_checkbox(:category_ids, [["Tech", 1], ["Design", 2], ["Business", 3]]) %>
<%= f.rui_checkbox(:category_ids, ["Tech", "Design", "Business"]) %>
```

### collection_select style

```ruby
<%= f.rui_checkbox(:category_ids, Category.all, :id, :name) %>
<%= f.rui_checkbox(:category_ids, Category.all, :id, :name, label: "Categories") %>
```

### Standalone with positional args

```ruby
<%= rui_checkbox(:category_ids, Category.all, :id, :name, label: "Categories") %>
```

**Note:** When both positional choices and `collection:` keyword are provided, the keyword always wins. The keyword API remains fully backward-compatible.

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `form` | FormBuilder | nil | Form builder instance (auto-passed by f.rui_checkbox) |
| `object` | Object/Symbol | nil | Object to bind checkbox to |
| `method` | Symbol/String | nil | Attribute name |
| `collection` | Array/Relation | nil | Collection for multiple checkboxes |
| `value_method` | Symbol | :id | Method to get value from collection items |
| `text_method` | Symbol | :name | Method to get label text from collection items |
| `description_method` | Symbol | nil | Method to get description from collection items |
| `label` | String/false | nil | Label text. `nil` = smart default in form mode. `false` = no label. |
| `description` | String | nil | Description text for single checkbox |
| `help_text` | String | nil | Help text displayed below checkbox/group |
| `required` | Boolean | false | Show required indicator (*) |
| `disabled` | Boolean | false | Disable checkbox(es) |
| `checked` | Boolean | nil | Checked state for standalone checkbox |
| `value` | String | "1" | Value when checked |
| `unchecked_value` | String | "0" | Value when unchecked |
| `variant` | Symbol | :checkbox | Visual variant (:checkbox, :switch, :card, :pill, :button) |
| `color` | Symbol | :primary | Any color: semantic or Tailwind (:primary, :success, :indigo, :pink, etc.) |
| `size` | Symbol | :base | Size (:xs, :sm, :base, :lg, :xl) |
| `shape` | Symbol | :rounded | Shape (:square, :rounded) |
| `layout` | Symbol | :vertical | Layout for collections (:vertical, :horizontal) |
| `select_all` | Boolean | false | Show select all for collections |
| `auto_submit` | Boolean | false | Auto-submit parent form on change (CSP-safe via Stimulus) |
| `strikethrough` | Boolean | false | Adds line-through + muted color to label when checked (checkbox variant only) |
| `label_class` | String | nil | Custom CSS classes appended to the label element |
| `input_html` | Hash | {} | Attributes passed directly to the `<input>` element |

## Strikethrough

Adds line-through and muted color to the label when the checkbox is checked. Useful for todo/task list patterns where completed items should be visually de-emphasized.

```ruby
<%# Todo list — completed items get line-through + muted color %>
<%= form_with(model: todo) do |f| %>
  <%= f.rui_checkbox(:completed, label: todo.title, auto_submit: true, strikethrough: true) %>
<% end %>
```

Uses pure CSS (`group-has-[:checked]`) — no JavaScript required. The color fade is animated via `transition-all duration-300`; line-through appears instantly (not animatable via CSS).

Only applies to the `:checkbox` variant (switch/card/pill/button have their own label rendering).

## Label Class

Append custom CSS classes to the label element. Accepts a string of class names.

```ruby
<%# Custom label styling %>
<%= rui_checkbox(:terms, label: "I agree", label_class: "text-lg italic") %>

<%# Combined with strikethrough %>
<%= f.rui_checkbox(:completed, label: todo.title, strikethrough: true, label_class: "font-bold") %>
```

## input_html

By default, `**options` (extra keyword args) are applied to the **wrapper `<div>`**, not the `<input>`. Use `input_html:` to pass attributes directly to the checkbox input.

```ruby
<%# Add data attributes to the input %>
<%= f.rui_checkbox(:completed,
  input_html: { data: { turbo_permanent: true } }) %>

<%# Add custom CSS class to the input %>
<%= f.rui_checkbox(:featured,
  input_html: { class: "custom-input" }) %>

<%# Add aria attributes to the input %>
<%= f.rui_checkbox(:terms,
  input_html: { aria: { label: "Accept terms" } }) %>

<%# Combine with auto_submit — data attributes are merged, not overwritten %>
<%= f.rui_checkbox(:completed,
  auto_submit: true,
  input_html: { data: { custom: "value" } }) %>
```

**Merge behavior:**
- `data:` — Stimulus action/controller strings are **concatenated** (space-separated), other data attrs merge normally
- `aria:` — merged with component-generated aria attrs
- `class:` — appended after variant-specific classes
- Other keys — set directly on the input

## Examples

### With Description

```ruby
<%= rui_checkbox(:marketing_emails,
  label: "Marketing emails",
  description: "Receive updates about new features and promotions") %>
```

### With Help Text

```ruby
<%= rui_checkbox(:terms,
  label: "I agree to the terms",
  help_text: "Please read our terms and conditions before accepting",
  required: true) %>
```

### Disabled State

```ruby
<%= rui_checkbox(:locked, label: "Account locked", disabled: true) %>
```

### Color Variants

The checkbox supports ALL Tailwind colors via `ColorBuilderHelper`:

```ruby
# Semantic colors
<%= rui_checkbox(:verified, color: :success, label: "Verified", checked: true) %>
<%= rui_checkbox(:pending, color: :warning, label: "Pending review", checked: true) %>
<%= rui_checkbox(:flagged, color: :danger, label: "Flagged", checked: true) %>

# Any Tailwind color
<%= rui_checkbox(:opt1, color: :indigo, label: "Indigo", checked: true) %>
<%= rui_checkbox(:opt2, color: :pink, label: "Pink", checked: true) %>
<%= rui_checkbox(:opt3, color: :teal, label: "Teal", checked: true) %>
```

### Size Variants

```ruby
<%= rui_checkbox(:xs, size: :xs, label: "Extra Small", checked: true) %>
<%= rui_checkbox(:sm, size: :sm, label: "Small", checked: true) %>
<%= rui_checkbox(:base, size: :base, label: "Base (default)", checked: true) %>
<%= rui_checkbox(:lg, size: :lg, label: "Large", checked: true) %>
<%= rui_checkbox(:xl, size: :xl, label: "Extra Large", checked: true) %>
```

### Shape Variants

```ruby
<%= rui_checkbox(:rounded, shape: :rounded, label: "Rounded (default)", checked: true) %>
<%= rui_checkbox(:square, shape: :square, label: "Square", checked: true) %>
```

### Horizontal Layout

```ruby
<%= f.rui_checkbox(:role_ids,
  collection: Role.all,
  layout: :horizontal,
  label: "Select roles") %>
```

### Collection with Descriptions

```ruby
<%= f.rui_checkbox(:feature_ids,
  collection: Feature.all,
  value_method: :id,
  text_method: :name,
  description_method: :description,
  label: "Enable features") %>
```

### Simple Array Collection

```ruby
<%= rui_checkbox(:notifications,
  collection: [
    ["Email notifications", "email"],
    ["SMS notifications", "sms"],
    ["Push notifications", "push"]
  ],
  label: "Notification preferences") %>
```

### Switch Variant with Colors

```ruby
<%= rui_checkbox(:dark_mode, label: "Dark mode", variant: :switch, color: :primary) %>
<%= rui_checkbox(:enabled, label: "Feature enabled", variant: :switch, color: :success) %>
```

### Card Variant

Bordered cards with full-width click targets. Perfect for feature selection, pricing plans, or settings pages.

```ruby
# Single card checkbox
<%= rui_checkbox(:premium,
  label: "Premium Plan",
  description: "Unlimited access to all features",
  variant: :card,
  color: :primary) %>

# Card with icon
<%= rui_checkbox(:analytics,
  label: "Analytics",
  description: "Track performance metrics",
  variant: :card,
  color: :indigo) do |cb|
  cb.with_icon(:chart_bar)
end %>
```

### Pill Variant

Compact, tag-like selections. Perfect for filters, categories, or tags.

```ruby
# Pill group for tags/filters
<div class="flex flex-wrap gap-2">
  <%= rui_checkbox(:ruby, variant: :pill, label: "Ruby", color: :red, checked: true) %>
  <%= rui_checkbox(:rails, variant: :pill, label: "Rails", color: :rose) %>
  <%= rui_checkbox(:js, variant: :pill, label: "JavaScript", color: :yellow) %>
</div>

# Pill with icon
<%= rui_checkbox(:favorites, variant: :pill, label: "Favorites", color: :pink) do |cb|
  cb.with_icon(:heart)
end %>
```

### Button Variant

Toolbar-style toggle controls. Perfect for formatting toolbars, view toggles, or option selection.

```ruby
# Text formatting toolbar
<div class="flex gap-1">
  <%= rui_checkbox(:bold, variant: :button, label: "Bold", color: :zinc) do |cb|
    cb.with_icon(:bold)
  end %>
  <%= rui_checkbox(:italic, variant: :button, label: "Italic", color: :zinc) do |cb|
    cb.with_icon(:italic)
  end %>
</div>

# Icon-only buttons (no label)
<div class="flex gap-1">
  <%= rui_checkbox(:list, variant: :button, color: :primary) do |cb|
    cb.with_icon(:list_bullet)
  end %>
  <%= rui_checkbox(:grid, variant: :button, color: :primary, checked: true) do |cb|
    cb.with_icon(:table_cells)
  end %>
</div>
```

### Icon Support

All variants support icons via the `with_icon` slot:

```ruby
# Standard checkbox with icon
<%= rui_checkbox(:email, label: "Send email", color: :primary) do |cb|
  cb.with_icon(:envelope)
end %>

# Card with icon (icon shows above content)
<%= rui_checkbox(:security, variant: :card, label: "Security",
  description: "Two-factor auth", color: :indigo) do |cb|
  cb.with_icon(:shield_check)
end %>
```

## Form Builder Integration

```ruby
<%= form_with(model: @user) do |f| %>
  <%# Smart label from attribute name %>
  <%= f.rui_checkbox(:terms_accepted) %>

<%# Explicit label %>
  <%= f.rui_checkbox(:terms_accepted, label: "I agree to the terms") %>

<%# Collection with select all %>
  <%= f.rui_checkbox(:category_ids,
    collection: Category.all,
    select_all: true,
    label: "Categories") %>

<%# Auto-submit toggle %>
  <%= f.rui_checkbox(:notifications, variant: :switch, auto_submit: true) %>

<%= f.rui_button %>
<% end %>
```

## Smart Label Resolution

In form mode (when `form:` is provided), the label is auto-derived if not explicitly set:

1. **`label: "Custom"`** — explicit label used as-is
2. **`label: false`** — no label rendered
3. **`label: nil` (default)** — derived from `human_attribute_name` if available, otherwise `method.to_s.humanize`
4. **Standalone mode** — falls back to `"Checkbox"` if no label provided

```ruby
# Model has human_attribute_name(:terms_accepted) => "Terms accepted"
<%= f.rui_checkbox(:terms_accepted) %>
# Renders label: "Terms accepted"

# Override with explicit label
<%= f.rui_checkbox(:terms_accepted, label: "I agree") %>
# Renders label: "I agree"

# Suppress label
<%= f.rui_checkbox(:terms_accepted, label: false) %>
# No label element rendered
```

## Unique ID Generation

When the bound object is persisted (responds to `id` with a non-nil value), the generated input ID includes the record ID:

| Scenario | Generated ID |
|----------|-------------|
| `user.id = 42`, method `:completed` | `user_42_completed` |
| `user.id = nil`, method `:completed` | `user_completed` |
| Collection item, `user.id = 5`, value `1` | `user_5_category_ids_1` |
| Standalone `:terms` | `terms` |

This prevents duplicate ID collisions when rendering multiple forms on the same page, such as a list of todos with inline toggle checkboxes.

## Accessibility

The component includes comprehensive accessibility support:

- Proper `<label>` elements with `for` attributes matching unique input IDs
- `aria-labelledby` for collection groups
- `aria-describedby` for help text
- `aria-required` for required fields
- `aria-invalid` for validation errors
- Indeterminate state for select all
- Keyboard navigation support
- Focus visible states
- Screen reader friendly
- CSP-safe auto-submit (Stimulus, no inline JavaScript)

## Checked State Detection

The component automatically detects checked state from the bound object:

```ruby
# Boolean attribute
@user.terms_accepted = true
f.rui_checkbox(:terms_accepted) # Checked

# Array attribute (for collections)
@user.category_ids = [1, 3, 5]
f.rui_checkbox(:category_ids, collection: Category.all)
# Categories with IDs 1, 3, 5 will be checked
```

## Select All Functionality

When `select_all: true`, the component adds a "Select All" checkbox with intelligent state:

- **Checked**: All items are selected
- **Indeterminate**: Some items are selected
- **Unchecked**: No items are selected

The state updates automatically via Stimulus controller when individual checkboxes change.

## Error Handling

The component automatically displays validation errors from ActiveRecord:

```ruby
# In model
class User < ApplicationRecord
  validates :terms_accepted, acceptance: true
end

# In view — error displayed with aria-invalid
<%= form_with(model: @user) do |f| %>
  <%= f.rui_checkbox(:terms_accepted, label: "I accept") %>
<% end %>
```

## Styling

All styles are defined in `styles.rb` using Tailwind CSS classes with dark mode support. Custom classes can be added via the `class` option (applied to wrapper) or `input_html: { class: "..." }` (applied to input).

## Implementation Notes

- All variants use a real checkbox input for accessibility (not custom elements)
- `**options` go to the wrapper `<div>`, use `input_html:` for the `<input>` element
- `input_html` data/aria attributes are **merged** (not overwritten) with component-generated attributes
- Stimulus action strings are **concatenated** (space-separated) when merging, so `auto_submit` + `select_all` + `input_html` all coexist
- Switch variant uses CSS to hide the checkbox and style a custom toggle track/thumb with `peer-checked:` classes
- Card variant uses `peer-checked:` CSS for dynamic border/background changes
- Pill and button variants use `peer-checked:` CSS for state changes
- Icons supported via `with_icon` slot using the Icon component
- Select all and auto-submit use Stimulus controller (`data-controller="checkbox"`)
- Auto-submit uses `data-action="change->checkbox#submitForm"` — CSP-safe, no inline JavaScript
- Form builder support follows Rails conventions for naming and values
- Collections use array notation for name attributes (`user[category_ids][]`)
- Colors generated dynamically via ColorBuilderHelper (supports all Tailwind colors)

---

## Clipboard (`rui_clipboard`)

# Clipboard Component

The Clipboard component provides a button that copies text from a target element to the user's clipboard with visual feedback.

## Features

- **Copy from target element** - Specify any element ID to copy its content
- **Auto-detect content type** - Works with input.value, textarea.value, or element.textContent
- **Visual feedback** - Icon swap (clipboard → check) and text swap ("Copy" → "Copied!")
- **Multiple variants** - default, minimal, github, toolbar, code
- **GitHub-style variant** - Perfect for code blocks, minimal and compact
- **Toolbar variant** - Shows label + icon, turns green on success (GitHub PR-style)
- **Code variant** - Flowbite-style icon + text button that turns blue on success
- **Tooltip support** - Shows tooltip on hover, changes to "Copied!" on success
- **All semantic colors** - primary, success, danger, warning, info, zinc, etc.
- **Size variants** - xs, sm, base, lg, xl
- **Disabled state** - Prevent copying when needed
- **Accessibility** - ARIA labels, live regions, keyboard support

## Basic Usage

```erb

<div id="text-to-copy">This is the text that will be copied</div>
<%= rui_clipboard(target: "text-to-copy") %>

<input type="text" id="api-key" value="sk_live_abc123xyz">
<%= rui_clipboard(target: "api-key", text: "Copy API Key") %>

<pre><code id="code-snippet">console.log("Hello World")</code></pre>
<%= rui_clipboard(target: "code-snippet", variant: :github) %>
```

## Variants

### Default Variant (Solid)
Standard button with bold styling, icon + text.

```erb
<%= rui_clipboard(target: "content-1", text: "Copy") %>
<%= rui_clipboard(target: "content-1", text: "Copy", color: :primary) %>
```

### Minimal Variant (Ghost/Subtle)
Subtle styling with transparent background, perfect for inline use.

```erb
<%= rui_clipboard(target: "content-2", variant: :minimal) %>
<%= rui_clipboard(target: "content-2", variant: :minimal, color: :success) %>
```

### GitHub Variant (Icon-Only)
Compact, icon-only button with minimal border. Perfect for code blocks.

```erb

<%= rui_clipboard(target: "code-1", variant: :github) %>

<%= rui_clipboard(target: "code-1", variant: :github, text: "Copy") %>

<%= rui_clipboard(target: "code-1", variant: :github, size: :xs) %>
<%= rui_clipboard(target: "code-1", variant: :github, size: :sm) %>
```

### Toolbar Variant (GitHub PR-style)
Shows label + icon, turns green checkmark + "Copied!" on success. Perfect for PR diffs, file lists.

```erb

<%= rui_clipboard(target: "sha", variant: :toolbar, label: "Copy SHA") %>

<%= rui_clipboard(target: "changes", variant: :toolbar, label: "1 file changed") %>

<%= rui_clipboard(target: "branch", variant: :toolbar, label: "Copy branch") %>
```

### Code Variant (Flowbite-style)
Icon + text button with border. Text turns blue on success. Perfect for code blocks with visible button.

```erb
<%= rui_clipboard(target: "code-block", variant: :code) %>
<%= rui_clipboard(target: "code-block", variant: :code, text: "Copy Code") %>
```

## Tooltip Support

Add a tooltip that appears on hover and changes to "Copied!" on success.

```erb

<%= rui_clipboard(target: "cmd", variant: :github, tooltip: "Copy command") %>

<%= rui_clipboard(target: "url", variant: :minimal, tooltip: "Copy link") %>
```

## Sizes

All variants support 5 sizes:

```erb
<%= rui_clipboard(target: "content", size: :xs) %>  
<%= rui_clipboard(target: "content", size: :sm) %>  
<%= rui_clipboard(target: "content", size: :base) %>  
<%= rui_clipboard(target: "content", size: :lg) %>  
<%= rui_clipboard(target: "content", size: :xl) %>  
```

## Colors

Supports all semantic and Tailwind colors:

```erb

<%= rui_clipboard(target: "content", color: :primary) %>
<%= rui_clipboard(target: "content", color: :success) %>
<%= rui_clipboard(target: "content", color: :danger) %>
<%= rui_clipboard(target: "content", color: :warning) %>
<%= rui_clipboard(target: "content", color: :info) %>

<%= rui_clipboard(target: "content", color: :zinc) %>
<%= rui_clipboard(target: "content", color: :blue) %>
<%= rui_clipboard(target: "content", color: :red) %>
```

## States

### Disabled State

```erb
<%= rui_clipboard(target: "content", disabled: true) %>
```

When disabled:
- Button is visually dimmed (opacity-60)
- Click events are prevented
- Cursor shows not-allowed
- ARIA attributes indicate disabled state

## Real-World Examples

### Code Block with GitHub-Style Button

```erb
<div class="relative">
  <pre class="bg-zinc-900 text-white p-4 rounded-lg"><code id="bash-code">npm install rapid_rails_ui</code></pre>

<div class="absolute top-2 right-2">
    <%= rui_clipboard(target: "bash-code", variant: :github, size: :sm) %>
  </div>
</div>
```

### API Key Copy

```erb
<div class="flex items-center gap-2">
  <input
    type="text"
    id="api-key-input"
    value="sk_live_abc123xyz789"
    class="flex-1 px-3 py-2 border rounded"
    readonly
  >
  <%= rui_clipboard(
    target: "api-key-input",
    text: "Copy Key",
    variant: :minimal,
    color: :primary
  ) %>
</div>
```

### Share URL

```erb
<div class="flex items-center gap-2">
  <span id="share-url" class="text-sm text-zinc-600">
    https://example.com/posts/123
  </span>
  <%= rui_clipboard(
    target: "share-url",
    text: "Copy Link",
    size: :sm,
    color: :success
  ) %>
</div>
```

## Custom HTML Attributes

Pass any HTML attributes via the options hash:

```erb
<%= rui_clipboard(
  target: "content",
  id: "custom-id",
  class: "custom-class",
  data: { action: "clipboard->custom#log" }
) %>
```

## Accessibility

The component includes full accessibility support:

- **Semantic HTML** - Uses `<button type="button">`
- **ARIA labels** - Icon-only buttons get automatic aria-label
- **ARIA live region** - Success feedback announced to screen readers
- **ARIA disabled** - Disabled state properly indicated
- **Keyboard support** - Native button keyboard behavior (Space, Enter)
- **Focus visible** - Ring appears on keyboard focus

## Browser Support

- **Modern browsers** - Uses Clipboard API (Chrome 66+, Firefox 63+, Safari 13.1+, Edge 79+)
- **Requires HTTPS** - Clipboard API only works on secure origins (except localhost)

## Common Patterns

### Inline with Text

```erb
<p>
  Share this code: <code id="code-inline">git clone ...</code>
  <%= rui_clipboard(target: "code-inline", variant: :minimal, size: :sm) %>
</p>
```

### Multiple Copy Buttons

```erb
<div id="snippet-1">Code snippet 1</div>
<%= rui_clipboard(target: "snippet-1", text: "Copy Snippet 1") %>

<div id="snippet-2">Code snippet 2</div>
<%= rui_clipboard(target: "snippet-2", text: "Copy Snippet 2") %>
```

Each button independently tracks its own success state.

## Implementation Notes

### Target Element Requirements
- Target element MUST have an `id` attribute
- Element can be anywhere in the DOM (not required to be sibling)
- For inputs/textareas, copies `.value`
- For other elements, copies `.textContent`

### Success Feedback Timing
- Success message displays for 2 seconds
- Auto-resets to default state
- Multiple clicks reset the timer

### Security
- Uses `textContent` (auto-escaped) for safety
- No XSS risk - we copy, never insert HTML
- Clipboard API requires user gesture (click)

## Component Structure

```
RapidRailsUI::Clipboard::Component
├── Button element
├── Default message (clipboard icon + text)
│   ├── Clipboard icon
│   └── "Copy" text (or custom)
└── Success message (check icon + "Copied!")
    ├── Check icon (green)
    └── "Copied!" text

Stimulus Controller: clipboard
├── Targets: defaultMessage, successMessage
├── Values: target (element ID)
├── Actions: copy (on click)
└── Auto-reset after 2 seconds
```

## Styling

All styling uses Tailwind CSS utility classes:
- No custom CSS required
- Dark mode support built-in
- Responsive by default
- Follows RapidRailsUI design system

## Related Components

- **Button** - For general button needs
- **Icon** - Used internally for clipboard/check icons
- **Badge** - For displaying copied status persistently

---

## Code Block (`rui_code_block`)

# CodeBlock Component

Display code snippets with a language badge and copy button. Also supports inline code mentions within text.

## Features

- Dark theme styling
- Language badge in header
- Copy-to-clipboard button
- Horizontal scroll for long lines
- XSS-safe (all code is HTML-escaped)
- Whitespace preservation
- Inline mode for code mentions within paragraphs

## Basic Usage

### Block Syntax (Recommended)

Use blocks for displaying any code - it works for all languages:

```erb
<%= rui_code_block(language: :ruby, title: "Ruby Example") do %>
class User < ApplicationRecord
  has_many :posts
  validates :email, presence: true
end
<% end %>

<%= rui_code_block(language: :css) do %>
.container {
  display: flex;
  gap: 1rem;
}
<% end %>
```

### Displaying ERB Code

To show ERB code without it being executed, escape the ERB tags with an extra `%`:

- Use `<%%=` instead of `<%=`
- Use `<%%` instead of `<%`

```erb
<%= rui_code_block(language: :erb, title: "ERB Example") do %>
<%%= rui_table do |table| %>
  <%% table.with_column(key: :name, label: "Name") %>
<%% end %>
<% end %>
```

The escaped tags will display as regular ERB syntax in the rendered output.

### String Argument

For simple one-liners or code in variables:

```erb
<%= rui_code_block("puts 'Hello'", language: :ruby) %>

<%= rui_code_block("def hello\n  puts 'world'\nend", language: :ruby, title: "Multi-line") %>

<%= rui_code_block(code: @snippet.content, language: :ruby) %>
```

### Inline Code (for mentions within text)

Use inline mode to display code mentions within paragraphs or sentences:

```erb
Use the <%= rui_code_block("<a>", inline: true) %> tag to create links.

The <%= rui_code_block(".map()", inline: true) %> method transforms arrays.

To define a function, use <%= rui_code_block("def", inline: true) %> keyword.
```

Inline code has:
- No header or copy button
- Light background with border
- Minimal padding
- Works inline with text
- Automatically escapes HTML

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `code` | String | nil | Code (positional or keyword) |
| `language` | Symbol | :plain | Language identifier |
| `title` | String | nil | Header title (defaults to language) |
| `copy` | Boolean | true | Show copy button |
| `inline` | Boolean | false | Inline mode (no header, copy button, or syntax highlight) |
| `**options` | Hash | {} | HTML attributes for wrapper |

## Supported Languages

| Symbol | Display Name |
|--------|--------------|
| `:plain` | Plain Text |
| `:erb` | ERB |
| `:ruby` | Ruby |
| `:javascript` / `:js` | JavaScript |
| `:typescript` / `:ts` | TypeScript |
| `:html` | HTML |
| `:css` | CSS |
| `:scss` | SCSS |
| `:json` | JSON |
| `:yaml` / `:yml` | YAML |
| `:bash` / `:shell` / `:sh` | Shell |
| `:sql` | SQL |
| `:go` | Go |
| `:python` / `:py` | Python |
| `:rust` | Rust |
| `:elixir` | Elixir |
| `:markdown` / `:md` | Markdown |

Unknown languages display in uppercase (e.g., `:kotlin` -> "KOTLIN").

## Examples

### Ruby Code

```erb
<%= rui_code_block(language: :ruby, title: "User Model") do %>
class User < ApplicationRecord
  has_many :posts
  validates :email, presence: true
end
<% end %>
```

### JavaScript

```erb
<%= rui_code_block(language: :js) do %>
function greet(name) {
  console.log(`Hello, ${name}!`);
}
<% end %>
```

### Without Copy Button

```erb
<%= rui_code_block("bundle install", language: :bash, copy: false) %>
```

### Custom Title

```erb
<%= rui_code_block(language: :bash, title: "Install Dependencies") do %>
bundle install
yarn install
<% end %>
```

### With Custom Attributes

```erb
<%= rui_code_block(
  "puts 'test'",
  language: :ruby,
  id: "example-1",
  class: "my-custom-class",
  data: { testid: "code-example" }
) %>
```

## Displaying ERB Code Examples

When you need to show ERB code in documentation or tutorials:

```erb
<%= rui_code_block(language: :erb, title: "Button Example") do %>
<%%= rui_button("Click me", color: :primary) %>
<% end %>
```

This renders as:
```erb
<%= rui_button("Click me", color: :primary) %>
```

### Multiple ERB Tags

```erb
<%= rui_code_block(language: :erb, title: "Form Example") do %>
<%%= form_with model: @user do |f| %>
  <%%= f.rui_input :name, label: "Name" %>
  <%%= f.rui_button "Save" %>
<%% end %>
<% end %>
```

## Styling

- Background: `zinc-900` (light) / `zinc-950` (dark)
- Text: `zinc-100` / `zinc-200`
- Border: `zinc-800` / `zinc-700`
- Font: monospace, `text-sm`
- Rounded corners, horizontal scroll

## Note on Heredocs

Heredocs (`<<~CODE`) work in pure Ruby contexts (controllers, helpers, tests) but **do not work reliably inside ERB templates** due to how ERB compiles templates. Use block syntax with escaped tags instead.

## Related Components

- **Clipboard** - Powers the copy button

---

## Combobox (`rui_combobox`)

# Combobox Component

## Overview

The Combobox component provides a searchable, custom-styled dropdown selection with JavaScript interactivity. It is a feature-rich alternative to the native Select component, offering enhanced UX with search filtering, icons, multi-select with badges, and keyboard navigation.

## When to Use Combobox vs Select

**Use Combobox for:**
- Enhanced UX with search functionality
- Display icons alongside options
- Multi-select with visual badge display
- Custom styling and interactions
- Rich form controls where JavaScript is acceptable

**Use Select for:**
- Simple native selection
- Mobile-first applications (native picker)
- Forms where JavaScript overhead should be avoided
- Situations requiring native browser behavior

## Features

- **Searchable Dropdown**: Real-time filtering of options as user types
- **Single & Multi-Select**: Support for both selection modes
- **Badge Display**: Visual badges for selected items in multi-select
- **Icons in Options**: Display icons alongside option text
- **Keyboard Navigation**: Full keyboard support (arrows, Enter, Esc)
- **Max Selections**: Limit maximum selections in multi-select mode
- **Form Integration**: Works seamlessly with Rails form helpers
- **Collection Support**: Arrays, Hashes, and ActiveRecord relations
- **Accessibility**: ARIA attributes and screen reader support
- **Dark Mode**: Full dark mode styling

## Basic Usage

### Standalone Single-Select

```ruby
<%= rui_combobox(
  :category_id,
  collection: Category.all,
  label: "Category",
  placeholder: "Select a category"
) %>
```

### Standalone Multi-Select

```ruby
<%= rui_combobox(
  :tag_ids,
  collection: Tag.all,
  multiple: true,
  label: "Tags",
  placeholder: "Select tags"
) %>
```

### With Form Builder

```ruby
<%= form_with(model: @post) do |f| %>
  <%= f.rui_combobox(:category_id, collection: Category.all, label: "Category") %>
  <%= f.rui_combobox(:tag_ids, collection: Tag.all, multiple: true, label: "Tags") %>
<% end %>
```

## Rails-Compatible API

`rui_combobox` also accepts standard Rails positional argument patterns, so AI-generated code and Rails muscle-memory work out of the box.

### f.select style (positional choices)

```ruby
<%= f.rui_combobox(:status, ["Draft", "Published"]) %>
<%= f.rui_combobox(:status, ["Draft", "Published"], include_blank: true) %>
```

### collection_select style (positional value/text methods)

```ruby
<%= f.rui_combobox(:category_id, Category.all, :id, :name) %>
<%= f.rui_combobox(:category_id, Category.all, :id, :name, prompt: "Choose") %>
```

### Standalone with positional args

```ruby
<%= rui_combobox(:status, ["Draft", "Published"], label: "Status") %>
```

**Note:** When both positional choices and `collection:` keyword are provided, the keyword always wins. The keyword API remains fully backward-compatible.

## Collection Formats

### Array of Objects (ActiveRecord)

```ruby
<%= rui_combobox(
  :category_id,
  collection: Category.all,
  value_method: :id,
  text_method: :name
) %>
```

### Array of Arrays

```ruby
<%= rui_combobox(
  :status,
  collection: [["Draft", "draft"], ["Published", "published"]],
  label: "Status"
) %>
```

### Hash

```ruby
<%= rui_combobox(
  :role,
  collection: { "Admin" => "admin", "Editor" => "editor", "Viewer" => "viewer" },
  label: "Role"
) %>
```

### Grouped Options

Pass an array of `{group:, items:}` hashes to render labelled sections in the popover. Items use any of the supported item shapes (Hash, Array, String). Search and keyboard navigation respect groups; headers auto-hide when all their items are filtered out.

```erb
<%= rui_combobox(
  :breed,
  collection: [
    { group: "Cattle", items: [
        { value: "angus",    text: "Angus" },
        { value: "hereford", text: "Hereford" }
      ]
    },
    { group: "Sheep", items: [
        { value: "merino", text: "Merino" },
        { value: "dorset", text: "Dorset" }
      ]
    }
  ],
  label: "Breed"
) %>
```

Group headers render with `role="presentation"`, options keep `role="option"`, so arrow-key navigation skips headers.

**Constraint: values must be unique across ALL groups, not just within one.**
Selection state (server-side `find_item_by_value`, and
`combobox_controller.js`'s `optionTargets.find(opt => opt.dataset.value ===
value)`) is looked up by value alone - group membership isn't part of the
lookup key. If two items in *different* groups share the same `value` (e.g.
grouping records from two tables whose primary keys both start at 1), only
the first match resolves, and selecting the second one's option is
indistinguishable from re-selecting the first. Namespace values yourself if
your groups can't guarantee cross-group uniqueness, e.g. `value:
"#{category.id}-#{item.id}"`.

### Per-Item Disabled Flag

Hash-shaped items accept `disabled: true` to render an individual option as un-selectable (`aria-disabled="true"`, pointer-events disabled).

```erb
<%= rui_combobox(
  :plan,
  collection: [
    { value: "free",    text: "Free" },
    { value: "pro",     text: "Pro" },
    { value: "premium", text: "Premium (sold out)", disabled: true }
  ]
) %>
```

## Icons in Options

To display icons alongside option text, provide an `icon_method` parameter that points to a method/attribute on your collection items:

```ruby
# Assuming Role model has icon_name attribute
<%= rui_combobox(
  :role_id,
  collection: Role.all,
  icon_method: :icon_name,
  label: "Select Role"
) %>
```

## Multi-Select Options

### With Badge Display (default)

```ruby
<%= rui_combobox(
  :tag_ids,
  collection: Tag.all,
  multiple: true,
  show_badges: true,  # default
  label: "Tags"
) %>
```

### With Summary Display

```ruby
<%= rui_combobox(
  :tag_ids,
  collection: Tag.all,
  multiple: true,
  show_badges: false,  # Shows "X items selected"
  label: "Tags"
) %>
```

### Max Selections Limit

```ruby
<%= rui_combobox(
  :tag_ids,
  collection: Tag.all,
  multiple: true,
  max_selections: 3,  # Limit to 3 selections
  label: "Tags (max 3)"
) %>
```

## Sizes

Combobox supports 5 sizes matching the Select component:

```ruby
<%= rui_combobox(:category_id, collection: Category.all, size: :xs) %>
<%= rui_combobox(:category_id, collection: Category.all, size: :sm) %>
<%= rui_combobox(:category_id, collection: Category.all, size: :base) %>  # default
<%= rui_combobox(:category_id, collection: Category.all, size: :lg) %>
<%= rui_combobox(:category_id, collection: Category.all, size: :xl) %>
```

## Colors

Focus ring and border colors (semantic colors):

```ruby
<%= rui_combobox(:category_id, collection: Category.all, color: :zinc) %>      # default
<%= rui_combobox(:category_id, collection: Category.all, color: :primary) %>
<%= rui_combobox(:category_id, collection: Category.all, color: :success) %>
<%= rui_combobox(:category_id, collection: Category.all, color: :warning) %>
<%= rui_combobox(:category_id, collection: Category.all, color: :danger) %>
```

## Shapes

```ruby
<%= rui_combobox(:category_id, collection: Category.all, shape: :square) %>
<%= rui_combobox(:category_id, collection: Category.all, shape: :rounded) %>  # default
<%= rui_combobox(:category_id, collection: Category.all, shape: :pill) %>
```

## Variants

```ruby
<%= rui_combobox(:category_id, collection: Category.all, variant: :default) %>    # default
<%= rui_combobox(:category_id, collection: Category.all, variant: :underline) %>
```

## Width

Control the horizontal width of the combobox wrapper. By default, combobox uses `inline-flex` (content-sized). Use the `width` attribute for consistent sizing:

### Dynamic Widths

```ruby
<%= rui_combobox(:category_id, collection: Category.all, width: :auto) %>    # Content-sized (default)
<%= rui_combobox(:category_id, collection: Category.all, width: :full) %>    # Full width (100%)
<%= rui_combobox(:category_id, collection: Category.all, width: :fit) %>     # Fit content
<%= rui_combobox(:category_id, collection: Category.all, width: :screen) %>  # Full viewport width
<%= rui_combobox(:category_id, collection: Category.all, width: :min) %>     # Min content
<%= rui_combobox(:category_id, collection: Category.all, width: :max) %>     # Max content
```

### Fixed Widths

```ruby
<%= rui_combobox(:category_id, collection: Category.all, width: :xs) %>   # 12rem / 192px
<%= rui_combobox(:category_id, collection: Category.all, width: :sm) %>   # 14rem / 224px
<%= rui_combobox(:category_id, collection: Category.all, width: :md) %>   # 16rem / 256px
<%= rui_combobox(:category_id, collection: Category.all, width: :lg) %>   # 18rem / 288px
<%= rui_combobox(:category_id, collection: Category.all, width: :xl) %>   # 20rem / 320px
<%= rui_combobox(:category_id, collection: Category.all, width: :"2xl") %> # 24rem / 384px
```

### Common Use Cases

```ruby
# Full-width combobox in a form
<%= rui_combobox(:sale_id, collection: Sale.all, width: :full, label: "Sale") %>

# Fixed-width combobox for consistent layouts
<%= rui_combobox(:status, collection: statuses, width: :lg, label: "Status") %>

# In a grid layout - both comboboxes same width
<div class="grid grid-cols-2 gap-4">
  <%= rui_combobox(:country, collection: countries, width: :full) %>
  <%= rui_combobox(:state, collection: states, width: :full) %>
</div>
```

## Search Behavior

### Enable/Disable Search

```ruby
<%= rui_combobox(:category_id, collection: Category.all, searchable: true) %>   # default
<%= rui_combobox(:category_id, collection: Category.all, searchable: false) %>
```

### Clear Search After Selection

```ruby
<%= rui_combobox(
  :category_id,
  collection: Category.all,
  clear_on_select: true   # Clear search input after selecting
) %>
```

### Close Menu After Selection

The default is `:auto` — the menu closes after selection in single-select mode and stays open in multi-select mode. Override with `true` or `false`:

```ruby
# Default :auto behavior (close when single, stay open when multiple)
<%= rui_combobox(:category_id, collection: Category.all) %>
<%= rui_combobox(:tag_ids, collection: Tag.all, multiple: true) %>

# Force close after selection even in multi-select
<%= rui_combobox(:tag_ids, collection: Tag.all, multiple: true, close_on_select: true) %>

# Force stay open even in single-select
<%= rui_combobox(:category_id, collection: Category.all, close_on_select: false) %>
```

## Form Labels & Help Text

```ruby
<%= rui_combobox(
  :category_id,
  collection: Category.all,
  label: "Category",
  help_text: "Choose the most relevant category",
  required: true
) %>
```

## Error States

Combobox automatically displays validation errors when integrated with Rails forms:

```ruby
<%= form_with(model: @post) do |f| %>
  <%= f.rui_combobox(:category_id, collection: Category.all, label: "Category") %>
<% end %>

# If @post.errors[:category_id] exists, error styling and message will be displayed
```

## Pre-selected Values

### Single-Select

```ruby
<%= rui_combobox(
  :category_id,
  collection: Category.all,
  selected: "123",  # Pre-select category with id 123
  label: "Category"
) %>
```

### Multi-Select

```ruby
<%= rui_combobox(
  :tag_ids,
  collection: Tag.all,
  multiple: true,
  selected: ["1", "2", "3"],  # Pre-select multiple tags
  label: "Tags"
) %>
```

### With Form Builder (auto-selected from object)

```ruby
<%= form_with(model: @post) do |f| %>
  <%# Automatically uses @post.category_id %>
  <%= f.rui_combobox(:category_id, collection: Category.all) %>

<%# Automatically uses @post.tag_ids %>
  <%= f.rui_combobox(:tag_ids, collection: Tag.all, multiple: true) %>
<% end %>
```

## Custom HTML Attributes

Pass additional HTML attributes via the options hash:

```ruby
<%= rui_combobox(
  :category_id,
  collection: Category.all,
  data: { custom: "value" },
  class: "my-custom-class",
  id: "custom-combobox-id"
) %>
```

## Keyboard Navigation

- **Arrow Down**: Highlight next option
- **Arrow Up**: Highlight previous option
- **Enter**: Select highlighted option (or open menu if closed)
- **Escape**: Close menu and return focus to trigger
- **Tab**: Close menu and move to next form field
- **Type to search**: Automatically filters options (when searchable)

## JavaScript Events

The combobox dispatches custom events you can listen to:

```javascript
document.addEventListener("combobox:change", (event) => {
  console.log("Selected values:", event.detail.values)
})
```

## Accessibility

The Combobox component includes:

- **ARIA roles**: `role="listbox"`, `role="option"`
- **ARIA attributes**: `aria-expanded`, `aria-selected`, `aria-disabled`
- **ARIA labels**: Proper labeling for screen readers
- **Keyboard navigation**: Full keyboard support
- **Focus management**: Proper focus handling on open/close

## Implementation Notes

- **JavaScript Required**: This component requires Stimulus JS (unlike Select which is native)
- **Mobile Considerations**: Consider using Select component for mobile-first applications
- **Performance**: Client-side filtering works well for up to 100-200 items; for larger datasets, consider server-side filtering
- **Styling**: Trigger button matches Select component for visual consistency
- **Form Submission**: Uses hidden inputs for seamless Rails form integration

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `method` | Symbol/String | nil | Attribute name (required) |
| `form` | FormBuilder | nil | Form builder instance |
| `collection` | Array/Hash/Relation | [] | Options collection (required) |
| `value_method` | Symbol | :id | Method to get value from items |
| `text_method` | Symbol | :name | Method to get text from items |
| `icon_method` | Symbol | nil | Method to get icon from items |
| `label` | String | nil | Label text |
| `placeholder` | String | "Select an option" | Placeholder text |
| `help_text` | String | nil | Help text below combobox |
| `required` | Boolean | false | Show required indicator |
| `disabled` | Boolean | false | Disable combobox |
| `multiple` | Boolean | false | Allow multiple selection |
| `selected` | Object/Array | nil | Pre-selected value(s) |
| `size` | Symbol | :base | Size (:xs, :sm, :base, :lg, :xl) |
| `color` | Symbol | :zinc | Color theme |
| `shape` | Symbol | :rounded | Shape (:square, :rounded, :pill) |
| `variant` | Symbol | :default | Variant (:default, :underline) |
| `width` | Symbol | nil | Width (:auto, :full, :fit, :xs, :sm, :md, :lg, :xl, :"2xl") |
| `searchable` | Boolean | true | Enable search input |
| `clear_on_select` | Boolean | false | Clear search after selection |
| `close_on_select` | Symbol/Boolean | `:auto` | Close menu after selection. `:auto` = `true` for single-select, `false` for `multiple: true`. Pass `true`/`false` to override. |
| `max_selections` | Integer | nil | Max selections (multi-select) |
| `show_badges` | Boolean | true | Show badges (multi-select) |
| `options` | Hash | {} | Additional HTML attributes |

---

## Date (`rui_date`)

# Date Component

A flexible date/time input component with multiple variants for different use cases.

## Features

- **Three variants**: Native browser picker, custom calendar popup, Rails select dropdowns
- **Three types**: Date, datetime, time
- **Form builder integration**: Works seamlessly with Rails forms
- **Full styling options**: Colors, sizes, shapes
- **Accessibility**: ARIA attributes, keyboard navigation
- **Dark mode support**: Built-in dark mode styling
- **Constraints**: Min/max date limits
- **Validation**: Error messages, required indicator

## Basic Usage

### Default (Picker)

`variant:` defaults to `:picker` — the custom calendar popup described below.
Omitting `variant:` entirely renders the picker, not a native `<input type="date">`.

```erb
<%= rui_date(name: :birthday) %>
```

### With Label and Help Text

```erb
<%= rui_date(
  name: :event_date,
  label: "Event Date",
  help_text: "Select when the event will occur"
) %>
```

### Form Builder Integration

```erb
<%= form_with(model: @event) do |f| %>
  <%= f.rui_date(:start_date, label: "Start Date") %>
  <%= f.rui_date(:end_date, label: "End Date") %>
  <%= f.rui_button("Save Event") %>
<% end %>
```

## Variants

### Native

Uses the browser's native date picker. Best for modern browsers. Must be
requested explicitly with `variant: :native` — it is not the default.

```erb
<%= rui_date(name: :date, variant: :native) %>
```

### Select

Wraps Rails' `date_select` helper. Renders as three dropdown menus (year, month, day).

```erb
<%= rui_date(
  name: :birth_date,
  variant: :select,
  start_year: 1950,
  end_year: Time.current.year
) %>
```

### Picker (Default)

Custom JavaScript-powered calendar popup with month navigation, today/clear buttons.

```erb
<%= rui_date(name: :event_date, variant: :picker) %>
```

#### With initial value

```erb
<%= rui_date(
  name: :event_date,
  variant: :picker,
  value: Date.today + 7.days
) %>
```

#### With min/max constraints

```erb
<%= rui_date(
  name: :booking_date,
  variant: :picker,
  min: Date.today,
  max: Date.today + 90.days
) %>
```

#### In a form

```erb
<%= form_with(model: @event) do |f| %>
  <%= f.rui_date(:start_date, variant: :picker, label: "Start Date") %>
<% end %>
```

**Features:**
- Click to open calendar dropdown
- Previous/next month navigation
- Today button to jump to current date
- Clear button to reset selection
- Click outside or press Escape to close
- Keyboard navigation (Alt+arrows for month/year)
- Min/max date constraints
- Full accessibility support

## Input Type

### Date (Default)

```erb
<%= rui_date(name: :date, input_type: :date) %>

```

### DateTime

```erb
<%= rui_date(name: :meeting, input_type: :datetime) %>

```

### Time

```erb
<%= rui_date(name: :alarm, input_type: :time) %>

```

> **Note:** The `type:` param is deprecated — use `input_type:` instead. `type:` still works but emits a deprecation warning.

## Styling Options

### Sizes

```erb
<%= rui_date(name: :date, size: :xs) %>
<%= rui_date(name: :date, size: :sm) %>
<%= rui_date(name: :date, size: :base) %>  
<%= rui_date(name: :date, size: :lg) %>
<%= rui_date(name: :date, size: :xl) %>
```

### Colors

Color sets the input border and focus ring (and the calendar highlight). Brand
colors (`:primary`, `:secondary`, `:tertiary`, `:accent`) resolve via
`config.colors`; status colors are fixed.

```erb
<%= rui_date(name: :date, color: :default) %>   
<%= rui_date(name: :date, color: :primary) %>   
<%= rui_date(name: :date, color: :secondary) %> 
<%= rui_date(name: :date, color: :accent) %>    
<%= rui_date(name: :date, color: :success) %>
<%= rui_date(name: :date, color: :warning) %>
<%= rui_date(name: :date, color: :danger) %>
<%= rui_date(name: :date, color: :info) %>
```

### Shapes

```erb
<%= rui_date(name: :date, shape: :square) %>
<%= rui_date(name: :date, shape: :rounded) %>  
<%= rui_date(name: :date, shape: :pill) %>
```

## Constraints

### Min/Max Dates

```erb
<%= rui_date(
  name: :check_in,
  min: Date.today,
  max: Date.today + 30.days
) %>
```

### Step for Time

```erb
<%= rui_date(
  name: :appointment,
  input_type: :time,
  step: 900  # 15 minutes (in seconds)
) %>
```

## States

### Required

```erb
<%= rui_date(
  name: :deadline,
  label: "Deadline",
  required: true
) %>
```

### Disabled

```erb
<%= rui_date(name: :date, disabled: true) %>
```

### Read-only

```erb
<%= rui_date(name: :date, readonly: true) %>
```

## Error Handling

### Explicit Error Message

```erb
<%= rui_date(
  name: :date,
  error_message: "Please select a valid date"
) %>
```

### With Form Object Errors

```erb
<%= form_with(model: @event) do |f| %>
  <%= f.rui_date(:start_date, label: "Start Date") %>
  
<% end %>
```

## Select Variant Options

```erb
<%= rui_date(
  name: :birth_date,
  variant: :select,
  start_year: 1950,
  end_year: Time.current.year,
  order: [:year, :month, :day],
  include_blank: "Select..."
) %>
```

## Parameters Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | Symbol/String | nil | Input name (for standalone usage) |
| `variant` | Symbol | `:picker` | `:native`, `:picker`, `:select` |
| `input_type` | Symbol | `:date` | Input type: `:date`, `:datetime`, `:time` |
| `type` | Symbol | — | **Deprecated** — use `input_type:` instead |
| `value` | Date/String | nil | Initial value |
| `label` | String | nil | Label text |
| `help_text` | String | nil | Help text below input |
| `error_message` | String | nil | Error message (overrides form errors) |
| `min` | Date/String | nil | Minimum date constraint |
| `max` | Date/String | nil | Maximum date constraint |
| `step` | Integer | nil | Step for time inputs (seconds) |
| `required` | Boolean | false | Required field |
| `disabled` | Boolean | false | Disabled state |
| `readonly` | Boolean | false | Read-only state |
| `placeholder` | String | nil | Placeholder text |
| `color` | Symbol | `:default` | Color theme |
| `size` | Symbol | `:base` | Size variant |
| `shape` | Symbol | `:rounded` | Shape variant |
| `start_year` | Integer | nil | Start year for select variant |
| `end_year` | Integer | nil | End year for select variant |
| `order` | Array | nil | Order of selects `[:year, :month, :day]` |
| `include_blank` | Bool/String | false | Include blank option in select |

## Form Builder Parameters

When using `f.rui_date`, the following are automatically handled:

| Parameter | Description |
|-----------|-------------|
| `form` | Form builder instance (automatic) |
| `method` | Attribute name on the model (first argument) |
| `object` | Model object (from form) |

```erb
<%= f.rui_date(:start_date,
  label: "Start Date",
  help_text: "When does the event begin?",
  required: true,
  min: Date.today
) %>
```

## Accessibility

The component includes:

- `aria-required="true"` when required
- `aria-invalid="true"` when errors present
- `aria-describedby` linking to help text
- Proper label `for` attribute matching input `id`
- Error messages with `role="alert"`

## Migration from Rails Helpers

| Rails Helper | RapidRailsUI Equivalent |
|--------------|-------------------------|
| `f.date_field` | `f.rui_date(:method)` |
| `f.datetime_field` | `f.rui_date(:method, input_type: :datetime)` |
| `f.time_field` | `f.rui_date(:method, input_type: :time)` |
| `f.date_select` | `f.rui_date(:method, variant: :select)` |
| `f.datetime_select` | `f.rui_date(:method, variant: :select, input_type: :datetime)` |
| `f.time_select` | `f.rui_date(:method, variant: :select, input_type: :time)` |

---

## Dialog (`rui_dialog`)

# Dialog Component

The Dialog component creates modal dialogs and drawer panels using the native HTML `<dialog>` element. It provides a unified API for both centered modals and edge-positioned drawers, with full Turbo Frame integration.

## Basic Usage

### Simple Modal

```erb
<%= rui_dialog(title: "Edit Profile") do %>
  <p>Update your profile information below.</p>
  <%= render "form", user: @user %>
<% end %>
```

### With Slots

```erb
<%= rui_dialog(title: "Confirm Delete") do |d| %>
  <% d.with_body do %>
    Are you sure you want to delete this item? This action cannot be undone.
  <% end %>
  <% d.with_footer do %>
    <%= rui_button("Cancel", variant: :outline, data: { action: "dialog#close" }) %>
    <%= rui_button("Delete", color: :danger) %>
  <% end %>
<% end %>
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id` | String | auto-generated | Unique ID for the dialog |
| `title` | String | `nil` | Title text for the header |
| `trigger` | String/HTML | `nil` | Trigger button/element to open dialog (alternative to slot) |
| `description` | String | `nil` | Description text below the title |
| `position` | Symbol | `:center` | Position (`:center`, `:right`, `:left`, `:top`, `:bottom`) |
| `size` | Symbol | `:md` | Size variant (`:xs`, `:sm`, `:md`, `:lg`, `:xl`, `:2xl`, `:full`) |
| `closable` | Boolean | `true` | Show close button in header |
| `backdrop_close` | Boolean | `true` | Close on backdrop click |
| `dismissible` | Boolean | — | **Deprecated** — use `backdrop_close:` instead |
| `static_backdrop` | Boolean | `false` | Prevent Escape key from closing |
| `turbo_frame` | String | `nil` | Turbo Frame ID for dynamic loading |
| `backdrop` | Symbol | `:default` | Backdrop style (`:default`, `:dark`, `:blur`, `:light`) |
| `autofocus_selector` | String | `nil` | CSS selector for element to focus on open |
| `description_id` | String | `nil` | ID of element describing the dialog (for aria-describedby) |
| `open` | Boolean | `false` | Whether dialog starts open |
| `responsive` | Boolean | `false` | Enable responsive position switching |
| `responsive_breakpoint` | Integer | `768` | Breakpoint in pixels for responsive switch |
| `mobile_position` | Symbol | auto | Position on mobile (auto-determined if not set) |

### Slots

| Slot | Description |
|------|-------------|
| `trigger` | Trigger button to open dialog (slot-based alternative to parameter) |
| `header` | Custom header content (replaces default title) |
| `body` | Main content area |
| `footer` | Action buttons area |

## Trigger Parameter vs Slot

You can provide a trigger button either as a parameter or as a slot:

### Trigger Parameter (Inline)

Useful when rendering inside tables or other components:

```erb
<%= rui_dialog(
  title: "Edit Record",
  description: "Update the record details below.",
  trigger: rui_button("Edit", variant: :ghost, size: :sm)
) do |d| %>
  <% d.with_body do %>
    <%= render "form" %>
  <% end %>
<% end %>
```

### Trigger Slot

When you need more control over the trigger button:

```erb
<%= rui_dialog(title: "Settings") do |d| %>
  <% d.with_trigger(color: :primary, size: :lg) do %>
    Open Settings
  <% end %>
  <% d.with_body do %>
    Settings content here
  <% end %>
<% end %>
```

## Title with Description

Add a subtitle/description below the dialog title:

```erb
<%= rui_dialog(
  title: "Confirm Delete",
  description: "This action cannot be undone."
) do |d| %>
  <% d.with_body do %>
    Are you sure you want to delete this item?
  <% end %>
  <% d.with_footer do %>
    <%= rui_button("Cancel", variant: :outline, data: { action: "dialog#close" }) %>
    <%= rui_button("Delete", color: :danger) %>
  <% end %>
<% end %>
```

## Positions

The `position` parameter determines whether the dialog renders as a modal (centered) or drawer (edge-positioned).

### Center (Modal)

```erb
<%= rui_dialog(position: :center, title: "Modal Dialog") do %>
  This is a centered modal dialog.
<% end %>
```

### Right Drawer

```erb
<%= rui_dialog(position: :right, title: "Settings") do %>
  <p>Configure your settings in this drawer panel.</p>
<% end %>
```

### Left Drawer

```erb
<%= rui_dialog(position: :left, title: "Navigation") do %>
  <%= render "navigation_menu" %>
<% end %>
```

### Top Sheet

```erb
<%= rui_dialog(position: :top, title: "Notifications") do %>
  <%= render "notifications_list" %>
<% end %>
```

### Bottom Sheet

```erb
<%= rui_dialog(position: :bottom, title: "Quick Actions") do %>
  <%= render "action_sheet" %>
<% end %>
```

## Sizes

### Modal Sizes (Centered Position)

| Size | Width |
|------|-------|
| `:xs` | max-w-xs (320px) |
| `:sm` | max-w-sm (384px) |
| `:md` | max-w-md (448px) |
| `:lg` | max-w-lg (512px) |
| `:xl` | max-w-xl (576px) |
| `:2xl` | max-w-2xl (672px) |
| `:full` | Full screen |

```erb
<%= rui_dialog(size: :lg, title: "Large Modal") do %>
  This modal has more room for content.
<% end %>
```

### Drawer Sizes (Edge Positions)

| Size | Width |
|------|-------|
| `:sm` | w-72 (288px) |
| `:md` | w-80 (320px) |
| `:lg` | w-96 (384px) |
| `:xl` | w-[28rem] (448px) |
| `:2xl` | w-[32rem] (512px) |
| `:full` | Full width |

```erb
<%= rui_dialog(position: :right, size: :lg, title: "Wide Drawer") do %>
  This drawer is wider for more complex content.
<% end %>
```

## Responsive Behavior

The Dialog component supports automatic responsive transformation. When `responsive: true`, dialogs automatically switch from their desktop position to a mobile-friendly bottom sheet on smaller viewports.

### Basic Responsive Dialog

```erb
<%# Modal becomes bottom sheet on mobile %>
<%= rui_dialog(title: "Edit Profile", responsive: true) do %>
  <p>This is a centered modal on desktop, but slides up as a sheet on mobile.</p>
  <%= render "profile_form" %>
<% end %>
```

### Responsive Drawer

```erb
<%# Right drawer becomes bottom sheet on mobile %>
<%= rui_dialog(position: :right, title: "Settings", responsive: true) do %>
  <%= render "settings_panel" %>
<% end %>
```

### Responsive Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `responsive` | Boolean | `false` | Enable responsive position switching |
| `responsive_breakpoint` | Integer | `768` | Breakpoint in pixels for responsive switch |
| `mobile_position` | Symbol | auto-determined | Position on mobile (`:bottom`, `:top`, `:center`) |

### Position Mapping

When `responsive: true`, positions automatically map on mobile:

| Desktop Position | Mobile Position |
|-----------------|-----------------|
| `:center` | `:bottom` (sheet) |
| `:right` | `:bottom` (sheet) |
| `:left` | `:bottom` (sheet) |
| `:top` | `:top` (stays) |
| `:bottom` | `:bottom` (stays) |

### Custom Breakpoint

```erb
<%# Switch at tablet size (640px) instead of default 768px %>
<%= rui_dialog(
  title: "Confirm Action",
  responsive: true,
  responsive_breakpoint: 640
) do %>
  Are you sure?
<% end %>
```

### Custom Mobile Position

Override the automatic mobile position mapping:

```erb
<%# Keep as centered modal on mobile instead of sheet %>
<%= rui_dialog(
  title: "Important Notice",
  responsive: true,
  mobile_position: :center
) do %>
  This stays centered even on mobile.
<% end %>
```

### Responsive Event

Listen for viewport changes:

```javascript
document.addEventListener('dialog:responsive', (event) => {
  const { isDesktop, position } = event.detail
  console.log(`Now in ${isDesktop ? 'desktop' : 'mobile'} mode, position: ${position}`)
})
```

### Why Responsive?

- **Mobile UX**: Bottom sheets are more thumb-friendly on mobile devices
- **Touch Interaction**: Slide-up animation feels natural on touch screens
- **Screen Real Estate**: Full-width sheets make better use of narrow screens
- **Native Feel**: Matches platform conventions (iOS/Android action sheets)

## Turbo Frame Integration

The Dialog component integrates seamlessly with Turbo for dynamic content loading.

### Layout-Level Dialog Frame

Add a dialog container to your layout to enable Turbo-powered dialogs:

```erb
<%# app/views/layouts/application.html.erb %>
<body>
  <%= yield %>

<%# Add at the end of the body %>
  <%= rui_dialog(id: "dialog", turbo_frame: "dialog") %>
</body>
```

### Opening Dialog via Link

```erb
<%# Any link can open content in the dialog %>
<%= link_to "Edit Post", edit_post_path(@post), data: { turbo_frame: "dialog" } %>
```

### Dialog Content View

```erb
<%# app/views/posts/edit.html.erb %>
<%= rui_dialog(title: "Edit Post", turbo_frame: "dialog") do %>
  <%= render "form", post: @post %>
<% end %>
```

### Auto-Close on Form Success

Forms inside Turbo-powered dialogs automatically close on successful submission:

```ruby
# app/controllers/posts_controller.rb
def update
  @post = Post.find(params[:id])
  if @post.update(post_params)
    respond_to do |format|
      format.turbo_stream
      format.html { redirect_to posts_path }
    end
  else
    # Re-renders in dialog with errors
    render :edit, status: :unprocessable_entity
  end
end
```

## Static Dialogs

For dialogs that don't use Turbo Frames, you can create static in-page dialogs:

### Trigger Button

```erb
<%# Button that opens the dialog %>
<button data-action="click->dialog#open" data-dialog-target="trigger">
  Open Dialog
</button>

<%# The dialog itself %>
<%= rui_dialog(id: "confirm-delete", title: "Confirm Delete") do |d| %>
  <% d.with_body do %>
    Are you sure?
  <% end %>
  <% d.with_footer do %>
    <%= rui_button("Cancel", data: { action: "dialog#close" }) %>
    <%= rui_button("Delete", color: :danger) %>
  <% end %>
<% end %>
```

### Pre-Opened Dialog

```erb
<%= rui_dialog(id: "welcome", title: "Welcome!", open: true) do %>
  Welcome to our application!
<% end %>
```

## Backdrop Options

### Default Backdrop

```erb
<%= rui_dialog(backdrop: :default, title: "Default") do %>
  Standard semi-transparent backdrop.
<% end %>
```

### Dark Backdrop

```erb
<%= rui_dialog(backdrop: :dark, title: "Dark Backdrop") do %>
  Darker backdrop for more focus.
<% end %>
```

### Blur Backdrop

```erb
<%= rui_dialog(backdrop: :blur, title: "Blur Backdrop") do %>
  Blurred backdrop effect.
<% end %>
```

### Light Backdrop

```erb
<%= rui_dialog(backdrop: :light, title: "Light Backdrop") do %>
  Lighter, more subtle backdrop.
<% end %>
```

## Behavior Options

### Backdrop Close (Non-Dismissible)

Prevent closing when clicking the backdrop:

```erb
<%= rui_dialog(backdrop_close: false, title: "Complete This Form") do %>
  <p>Please fill out all required fields before closing.</p>
  <%= render "required_form" %>
<% end %>
```

> **Note:** The `dismissible:` param is deprecated — use `backdrop_close:` instead. `dismissible:` still works but emits a deprecation warning.

### Static Backdrop (Prevent Escape)

Prevent closing with the Escape key (not recommended for most cases):

```erb
<%= rui_dialog(static_backdrop: true, title: "Critical Action") do %>
  <p>This requires your explicit confirmation.</p>
<% end %>
```

### No Close Button

Hide the X button in the header:

```erb
<%= rui_dialog(closable: false, title: "Required Action") do |d| %>
  <% d.with_body do %>
    Complete this action to continue.
  <% end %>
  <% d.with_footer do %>
    <%= rui_button("Complete", data: { action: "dialog#close" }) %>
  <% end %>
<% end %>
```

## Custom Header

Replace the default header with custom content:

```erb
<%= rui_dialog do |d| %>
  <% d.with_header do %>
    <div class="flex items-center gap-4">
      <%= rui_avatar(src: @user.avatar_url, size: :sm) %>
      <div>
        <h2 class="font-semibold"><%= @user.name %></h2>
        <p class="text-sm text-zinc-500">Edit Profile</p>
      </div>
    </div>
  <% end %>
  <% d.with_body do %>
    <%= render "profile_form", user: @user %>
  <% end %>
<% end %>
```

## Real-World Examples

### Confirmation Dialog

```erb
<%= rui_dialog(id: "confirm-action", title: "Confirm Action", size: :sm) do |d| %>
  <% d.with_body do %>
    <p class="text-zinc-600 dark:text-zinc-400">
      Are you sure you want to proceed? This action cannot be undone.
    </p>
  <% end %>
  <% d.with_footer do %>
    <%= rui_button("Cancel", variant: :outline, data: { action: "dialog#close" }) %>
    <%= rui_button("Confirm", color: :primary) %>
  <% end %>
<% end %>
```

### Settings Drawer

```erb
<%= rui_dialog(position: :right, size: :lg, title: "Settings") do |d| %>
  <% d.with_body do %>
    <div class="space-y-6">
      <div>
        <h3 class="font-medium mb-2">Appearance</h3>
        <label class="flex items-center gap-2">
          <input type="checkbox" name="dark_mode">
          <span>Dark mode</span>
        </label>
      </div>

<div>
        <h3 class="font-medium mb-2">Notifications</h3>
        <label class="flex items-center gap-2">
          <input type="checkbox" name="email_notifications" checked>
          <span>Email notifications</span>
        </label>
      </div>
    </div>
  <% end %>
  <% d.with_footer do %>
    <%= rui_button("Save Changes", color: :primary) %>
  <% end %>
<% end %>
```

### Image Preview Modal

```erb
<%= rui_dialog(size: :xl, closable: true) do %>
  <img src="<%= @image.url %>" alt="<%= @image.alt %>" class="w-full h-auto">
<% end %>
```

### Mobile Navigation Drawer

```erb
<%= rui_dialog(position: :left, size: :md, title: "Menu") do |d| %>
  <% d.with_body do %>
    <nav class="space-y-2">
      <%= rui_link("Home", href: root_path, class: "block py-2") %>
      <%= rui_link("Products", href: products_path, class: "block py-2") %>
      <%= rui_link("About", href: about_path, class: "block py-2") %>
      <%= rui_link("Contact", href: contact_path, class: "block py-2") %>
    </nav>
  <% end %>
<% end %>
```

### Form in Dialog with Turbo

```erb
<%# app/views/posts/new.html.erb %>
<%= rui_dialog(title: "New Post", turbo_frame: "dialog") do |d| %>
  <% d.with_body do %>
    <%= form_with model: @post do |f| %>
      <div class="space-y-4">
        <div>
          <%= f.label :title, class: "block font-medium mb-1" %>
          <%= f.text_field :title, class: "w-full rounded border px-3 py-2" %>
        </div>
        <div>
          <%= f.label :content, class: "block font-medium mb-1" %>
          <%= f.text_area :content, class: "w-full rounded border px-3 py-2", rows: 4 %>
        </div>
      </div>
    <% end %>
  <% end %>
  <% d.with_footer do %>
    <%= rui_button("Cancel", variant: :outline, data: { action: "dialog#close" }) %>
    <%= rui_button("Create Post", color: :primary, type: :submit, form: "new_post") %>
  <% end %>
<% end %>
```

## Stimulus Controller

The dialog uses a Stimulus controller for JavaScript interactivity. The controller is automatically registered when using the component.

### JavaScript API

```javascript
// Get the controller
const wrapper = document.querySelector('[data-controller="dialog"]')
const controller = application.getControllerForElementAndIdentifier(wrapper, 'dialog')

// Open the dialog
controller.open()

// Close the dialog
controller.close()

// Toggle open/close
controller.toggle()
```

### Custom Events

The dialog dispatches custom events:

```javascript
document.addEventListener('dialog:open', (event) => {
  console.log('Dialog opened:', event.detail.dialog)
})

document.addEventListener('dialog:closed', (event) => {
  console.log('Dialog closed:', event.detail.returnValue)
})

document.addEventListener('dialog:backdropClick', (event) => {
  console.log('Backdrop was clicked')
})

document.addEventListener('dialog:cancel', (event) => {
  console.log('Escape key was pressed')
})
```

### Data Attributes

| Attribute | Description |
|-----------|-------------|
| `data-dialog-backdrop-close-value` | Whether backdrop click closes dialog |
| `data-dialog-position-value` | Position of the dialog |
| `data-dialog-static-backdrop-value` | Whether Escape is prevented |
| `data-dialog-autofocus-value` | CSS selector for autofocus element |

## Accessibility

The Dialog component leverages native `<dialog>` element accessibility features:

- **Focus Trapping**: `showModal()` automatically traps focus inside the dialog
- **Escape Key**: Native handling to close the dialog (can be prevented with `static_backdrop`)
- **ARIA Attributes**: `aria-modal="true"` and `aria-labelledby` are set automatically
- **Inert Background**: The rest of the page becomes inert when dialog is open
- **Focus Restoration**: Focus returns to the trigger element when closed

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Escape` | Closes the dialog (unless `static_backdrop: true`) |
| `Tab` | Cycles through focusable elements within the dialog |

## Dark Mode

The dialog fully supports dark mode with appropriate color adjustments:

- Background: `bg-white dark:bg-zinc-900`
- Border colors: `border-zinc-200 dark:border-zinc-700`
- Text colors: Automatically adapt for readability
- Backdrop: Works with all backdrop variants

Colors automatically adapt when the `dark` class is present on `<html>`.

## Animations

The dialog uses CSS-only animations with `@starting-style` for smooth entry/exit:

- **Center (Modal)**: Scale from 95% to 100% with fade
- **Right/Left (Drawer)**: Slide in from edge with fade
- **Top/Bottom (Sheet)**: Slide in from edge with fade
- **Backdrop**: Smooth fade in/out

Animation classes are defined in the safelist.css and require no JavaScript.

---

## Dropdown (`rui_dropdown`)

# Dropdown Component Usage

The Dropdown component provides a versatile menu system for navigation, selection, or actions.

## Features

- **Two Modes**: Action dropdowns (navigation/menu) and Selection dropdowns (form integration)
- **Multiple Variants**: solid, outline, ghost, soft
- **Semantic Colors**: zinc, primary, success, warning, danger, info
- **Various Sizes**: xs, sm, base, lg, xl
- **Multiple Shapes**: square, rounded, pill
- **Collection Support**: Hash, Array, ActiveRecord::Relation
- **Keyboard Navigation**: Arrow keys, Escape, Enter
- **Accessibility**: Full ARIA support
- **Slots**: items, headers, dividers, icons
- **Form Builder Integration**: f.rui_dropdown
- **Placement Options**: top, right, bottom, left
- **Trigger Options**: click, hover
- **Full Dark Mode Support**

## Basic Usage

### Action Dropdown (Navigation/Menu)

```erb
<%# Simple action dropdown %>
<%= rui_dropdown(text: "Options") do |dropdown| %>
  <% dropdown.with_item(text: "Edit", href: edit_path) %>
  <% dropdown.with_item(text: "Delete", href: delete_path) %>
<% end %>

<%# With header and divider %>
<%= rui_dropdown(text: "Menu", color: :primary) do |dropdown| %>
  <% dropdown.with_header(text: "Actions") %>
  <% dropdown.with_item(text: "Edit", href: edit_path, icon: :edit) %>
  <% dropdown.with_item(text: "Duplicate", href: duplicate_path, icon: :copy) %>

<% dropdown.with_divider %>

<% dropdown.with_header(text: "Dangerous") %>
  <% dropdown.with_item(text: "Delete", href: delete_path, icon: :trash_2) %>
<% end %>
```

### Selection Dropdown (Form Integration)

```erb
<%# Standalone with collection %>
<%= rui_dropdown(:category, collection: Category.all, label: "Category") %>

<%# With Hash collection %>
<%= rui_dropdown(
  :status,
  collection: { "Draft" => "draft", "Published" => "published" },
  label: "Status",
  color: :primary
) %>

<%# Form builder %>
<%= form_with(model: @post) do |f| %>
  <%= f.rui_dropdown(
    :category_id,
    collection: Category.all,
    label: "Category",
    help_text: "Choose a category for your post"
  ) %>

<%= f.rui_dropdown(
    :status,
    collection: Post.statuses,
    label: "Status",
    required: true
  ) %>
<% end %>
```

## Parameters

### Required (for selection mode)
- `method` - Symbol, the model attribute name (when using with form or collection)
- `collection` - Array/Hash/ActiveRecord::Relation, the collection of options (for selection mode)

### Required (for action mode)
- `text` - String, button text for action dropdowns

### Optional Styling
- `variant` - Symbol, visual style (:solid, :outline, :ghost, :soft) - default: :solid
- `color` - Symbol, color theme (:zinc, :primary, :success, :warning, :danger, :info) - default: :zinc. Brand colors (`:primary`, `:secondary`, `:tertiary`, `:accent`) resolve via `config.colors`, including the trigger's focus ring; status colors are fixed.
- `size` - Symbol, button size (:xs, :sm, :base, :lg, :xl) - default: :base
- `shape` - Symbol, button shape (:square, :rounded, :pill) - default: :rounded
- `width` - Symbol, menu width (:sm, :base, :lg, :xl, :full) - default: :base

### Optional Configuration
- `placement` - Symbol, menu position (:top, :right, :bottom, :left) - default: :bottom
- `trigger` - Symbol, how to open (:click, :hover) - default: :click
- `disabled` - Boolean, disable the dropdown - default: false
- `required` - Boolean, show required indicator - default: false

### Form Integration
- `label` - String, label text
- `help_text` - String, help text below dropdown
- `prompt_text` - String, text when no option selected - default: "Select an option"
- `include_prompt` - Boolean, include prompt as selectable option - default: true

### Collection Processing
- `value_method` - Symbol, method to get value from items - default: :id
- `text_method` - Symbol, method to get label from items - default: :name

### HTML Attributes
- Any additional HTML attributes are passed to the wrapper div

### Item Parameters (for `with_item`)

When adding items to the dropdown using `dropdown.with_item()`, these parameters are available:

- `text` - String, the item text (required)
- `href` - String, link URL (optional, renders as link if present, button otherwise)
- `value` - String, value for selection mode (optional)
- `icon` - Symbol, icon name to display (optional)
- `disabled` - Boolean, disable the item - default: false
- `danger` - Boolean, apply destructive/warning styling - default: false
- `active` - Boolean, mark item as current/active page - default: false
- `active_class` - String, custom classes to apply ONLY when active is true (optional)
- `class` - String, custom classes to apply to ALL states (optional)
- `data` - Hash, custom data attributes (optional)

**Key Differences:**
- `active_class:` → Only applies when `active: true` (recommended for current page styling)
- `class:` → Always applies regardless of active state (use for consistent styling)

## Examples

### With All Variants

```erb
<%= rui_dropdown(text: "Solid", variant: :solid, color: :primary) do |d| %>
  <% d.with_item(text: "Action", href: "#") %>
<% end %>

<%= rui_dropdown(text: "Outline", variant: :outline, color: :primary) do |d| %>
  <% d.with_item(text: "Action", href: "#") %>
<% end %>

<%= rui_dropdown(text: "Ghost", variant: :ghost, color: :primary) do |d| %>
  <% d.with_item(text: "Action", href: "#") %>
<% end %>

<%= rui_dropdown(text: "Soft", variant: :soft, color: :primary) do |d| %>
  <% d.with_item(text: "Action", href: "#") %>
<% end %>
```

### With All Sizes

```erb
<%= rui_dropdown(text: "XS", size: :xs) { ... } %>
<%= rui_dropdown(text: "SM", size: :sm) { ... } %>
<%= rui_dropdown(text: "Base", size: :base) { ... } %>
<%= rui_dropdown(text: "LG", size: :lg) { ... } %>
<%= rui_dropdown(text: "XL", size: :xl) { ... } %>
```

### With All Shapes

```erb
<%= rui_dropdown(text: "Square", shape: :square) { ... } %>
<%= rui_dropdown(text: "Rounded", shape: :rounded) { ... } %>
<%= rui_dropdown(text: "Pill", shape: :pill) { ... } %>
```

### With All Placements

```erb
<%= rui_dropdown(text: "Top", placement: :top) { ... } %>
<%= rui_dropdown(text: "Right", placement: :right) { ... } %>
<%= rui_dropdown(text: "Bottom", placement: :bottom) { ... } %>
<%= rui_dropdown(text: "Left", placement: :left) { ... } %>
```

### With Icon

```erb
<%= rui_dropdown(text: "Actions", color: :primary) do |dropdown| %>
  <% dropdown.with_icon(:menu) %>
  <% dropdown.with_item(text: "Edit", href: edit_path, icon: :edit) %>
  <% dropdown.with_item(text: "Delete", href: delete_path, icon: :trash_2) %>
<% end %>
```

### With Hover Trigger

```erb
<%= rui_dropdown(text: "Hover Me", trigger: :hover) do |dropdown| %>
  <% dropdown.with_item(text: "Action 1", href: "#") %>
  <% dropdown.with_item(text: "Action 2", href: "#") %>
<% end %>
```

### With Disabled Items

```erb
<%= rui_dropdown(text: "Options") do |dropdown| %>
  <% dropdown.with_item(text: "Enabled", href: "#") %>
  <% dropdown.with_item(text: "Disabled", href: "#", disabled: true) %>
  <% dropdown.with_item(text: "Enabled", href: "#") %>
<% end %>
```

### With ActiveRecord Collection

```erb
<%# Basic ActiveRecord collection %>
<%= rui_dropdown(:author_id, collection: User.all, label: "Author") %>

<%# Custom methods %>
<%= rui_dropdown(
  :author_id,
  collection: User.all,
  value_method: :id,
  text_method: :full_name,
  label: "Author"
) %>
```

### With Array of Pairs

```erb
<%= rui_dropdown(
  :language,
  collection: [["Ruby", "rb"], ["JavaScript", "js"], ["Python", "py"]],
  label: "Language"
) %>
```

### With Custom HTML Attributes

```erb
<%= rui_dropdown(
  text: "Options",
  id: "custom-dropdown",
  class: "my-custom-class",
  data: { custom: "value" }
) do |dropdown| %>
  <% dropdown.with_item(text: "Action", href: "#") %>
<% end %>
```

## Slots

### Items Slot

Add individual menu items:

```erb
<%= rui_dropdown(text: "Options") do |dropdown| %>
  <% dropdown.with_item(
    text: "Edit",
    href: edit_path,
    icon: :edit,
    disabled: false
  ) %>
<% end %>
```

### Headers Slot

Add section headers:

```erb
<%= rui_dropdown(text: "Menu") do |dropdown| %>
  <% dropdown.with_header(text: "Section 1") %>
  <% dropdown.with_item(text: "Action 1", href: "#") %>

<% dropdown.with_header(text: "Section 2") %>
  <% dropdown.with_item(text: "Action 2", href: "#") %>
<% end %>
```

### Dividers Slot

Add visual separators:

```erb
<%= rui_dropdown(text: "Options") do |dropdown| %>
  <% dropdown.with_item(text: "Edit", href: "#") %>
  <% dropdown.with_divider %>
  <% dropdown.with_item(text: "Delete", href: "#") %>
<% end %>
```

### Icon Slot

Add an icon to the trigger button:

```erb
<%= rui_dropdown(text: "Actions") do |dropdown| %>
  <% dropdown.with_icon(:menu) %>
  <% dropdown.with_item(text: "Action", href: "#") %>
<% end %>
```

### Active/Current State

Mark navigation items as active/current to highlight the current page:

```erb
<%= rui_dropdown(text: "Navigation") do |dropdown| %>
  <% dropdown.with_item(
    text: "Dashboard",
    href: dashboard_path,
    icon: :home,
    active: request.path == dashboard_path
  ) %>

<% dropdown.with_item(
    text: "Settings",
    href: settings_path,
    icon: :settings,
    active: request.path.start_with?(settings_path)
  ) %>

<% dropdown.with_item(
    text: "Reports",
    href: reports_path,
    icon: :chart_bar,
    active: current_page?(reports_path)
  ) %>
<% end %>
```

**Features:**
- Active items styled with primary color and medium font weight (default)
- Use `active_class:` to customize active styling (only applies when active)
- Developer controls matching logic (exact path, prefix, etc.)
- Active state takes precedence over danger state

**Custom Active Styling with `active_class:`**

The `active_class:` parameter ONLY applies when `active: true`. This is the recommended way to customize active item styling:

```erb
<%# Custom active styling - only applies to current page %>
<%= rui_dropdown(text: "Navigation") do |dropdown| %>
  <% dropdown.with_item(
    text: "Dashboard",
    href: dashboard_path,
    active: current_page?(dashboard_path),
    active_class: "bg-blue-50 text-blue-900 font-bold border-l-4 border-blue-600"
  ) %>

<% dropdown.with_item(
    text: "Reports",
    href: reports_path,
    active: current_page?(reports_path),
    active_class: "bg-emerald-50 text-emerald-900 font-semibold"
  ) %>
<% end %>
```

**Using `class:` parameter (applies to ALL states)**

The `class:` parameter applies to both active and inactive states:

```erb
<%# This border applies to BOTH active and inactive states %>
<% dropdown.with_item(
  text: "Dashboard",
  href: dashboard_path,
  active: current_page?(dashboard_path),
  class: "border-l-2"  # Always has left border
) %>
```

**Combining both parameters:**

```erb
<%# Border always present, custom colors only when active %>
<% dropdown.with_item(
  text: "Dashboard",
  href: dashboard_path,
  active: current_page?(dashboard_path),
  active_class: "bg-blue-50 text-blue-900",
  class: "border-l-2"
) %>

## Keyboard Navigation

- **Arrow Down** - Focus next item
- **Arrow Up** - Focus previous item
- **Escape** - Close menu and return focus to trigger
- **Enter** - Select focused item (or open/close dropdown)
- **Tab** - No special handling. The menu does NOT auto-close on Tab -
  focus simply moves to whatever is next in the document's natural tab
  order (which may still be inside the open menu, depending on layout).
  Close the menu yourself first (Escape, or click/select an item) if you
  need it closed before tabbing away.

## Accessibility

The component includes full ARIA support:
- `role="menu"` on dropdown menu
- `role="menuitem"` on dropdown items
- `aria-expanded` on trigger button
- `aria-haspopup="true"` on trigger button
- `aria-controls` linking trigger to menu
- `aria-labelledby` linking menu to trigger
- `aria-required` when required
- `aria-invalid` when errors present
- `aria-describedby` for help text and errors

## Form Integration Notes

### Selection Mode vs Action Mode

The component automatically detects the mode:

- **Selection Mode**: When `collection` AND (`form` OR `method`) are present
  - Creates hidden input for form submission
  - Updates button text on selection
  - Includes prompt option

- **Action Mode**: Otherwise
  - No hidden input
  - Button text stays unchanged
  - No prompt option

### With Form Builder

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_dropdown(:status, collection: Post.statuses) %>
<% end %>
```

This generates:
- Correct name attribute: `post[status]`
- Correct ID: `post_status`
- Auto-retrieves value from `@post.status`
- Shows errors from `@post.errors[:status]`

## Customization

The component uses Tailwind CSS classes defined in `dropdown/styles.rb`. All styling is controlled via Ruby constants and can be customized by modifying the styles module.

## Dark Mode

All variants automatically include dark mode support via Tailwind's `dark:` variants.

---

## Editable (`rui_editable`)

# Editable Component

Inline editing component - click to edit text, blur or Enter to save, Escape to cancel.

## Basic Usage

```erb
<%# Basic inline editing %>
<%= rui_editable @post, :title, url: post_path(@post) %>

<%# With placeholder %>
<%= rui_editable @post, :subtitle,
      url: post_path(@post),
      placeholder: "Add a subtitle..." %>
```

## Input Types

```erb
<%# Text (default) %>
<%= rui_editable @post, :title, url: post_path(@post), input_type: :text %>

<%# Textarea %>
<%= rui_editable @post, :body,
      url: post_path(@post),
      input_type: :textarea,
      rows: 4 %>

<%# Number %>
<%= rui_editable @product, :price,
      url: product_path(@product),
      input_type: :number,
      min: 0,
      max: 10000 %>
```

## Semantic Elements

```erb
<%# As heading %>
<%= rui_editable @post, :title,
      url: post_path(@post),
      as: :h1,
      class: "text-3xl font-bold" %>

<%# As paragraph %>
<%= rui_editable @post, :excerpt,
      url: post_path(@post),
      as: :p %>
```

## Validation

```erb
<%# Required field %>
<%= rui_editable @user, :name,
      url: user_path(@user),
      required: true %>

<%# Character limits %>
<%= rui_editable @post, :title,
      url: post_path(@post),
      minlength: 3,
      maxlength: 100 %>

<%# Number constraints %>
<%= rui_editable @product, :quantity,
      url: product_path(@product),
      input_type: :number,
      min: 0,
      max: 999 %>
```

## Controller Setup

```ruby
class PostsController < ApplicationController
  def update
    @post = Post.find(params[:id])

if @post.update(post_params)
      respond_to do |format|
        format.turbo_stream { head :ok }
        format.html { redirect_to @post }
      end
    else
      respond_to do |format|
        format.turbo_stream {
          render turbo_stream: turbo_stream.replace(
            "editable_post_#{@post.id}_title",
            partial: "posts/title_error",
            locals: { post: @post }
          )
        }
        format.json {
          render json: { errors: @post.errors.full_messages },
          status: :unprocessable_entity
        }
      end
    end
  end

private

def post_params
    params.require(:post).permit(:title, :body)
  end
end
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `model` | ActiveRecord::Base | required | The model object to edit |
| `attribute` | Symbol | required | The attribute name to edit |
| `url` | String | nil | PATCH endpoint URL |
| `as` | Symbol | :span | Semantic HTML element (:h1, :h2, :p, :span, :div, etc.) |
| `placeholder` | String | "Click to edit" | Text when empty |
| `input_type` | Symbol | :text | Input type (:text, :textarea, :number) |
| `required` | Boolean | false | Whether field is required |
| `maxlength` | Integer | nil | Maximum character length |
| `minlength` | Integer | nil | Minimum character length |
| `min` | Integer | nil | Minimum value (number type) |
| `max` | Integer | nil | Maximum value (number type) |
| `rows` | Integer | 3 | Rows (textarea type) |
| `id` | String | auto | Custom ID |
| `class` | String | nil | Custom CSS classes |

## Keyboard Shortcuts

- **Enter** - Save changes (text/number input)
- **Cmd/Ctrl+Enter** - Save changes (textarea)
- **Escape** - Cancel edits, revert to original value
- **Tab** - Move to next element (triggers save)

## Stimulus Controller

The component uses the `editable` Stimulus controller with:

### Values
- `url` - PATCH endpoint
- `field` - Form field name
- `current` - Current value
- `inputType` - Input type
- `placeholder` - Placeholder text

### Targets
- `display` - Text display element
- `input` - Input/textarea element
- `saving` - Saving indicator
- `error` - Error message

### Actions
- `edit` - Switch to edit mode
- `save` - Save to server
- `cancel` - Cancel edits

---

## Icon (`rui_icon`)

# Icon Component

Use a beautiful set of 1500+ open-source SVG icons powered by the excellent Lucide icon library.

## Requirements

The Icon component requires the `lucide-rails` gem to be installed:

```ruby
# Gemfile
gem 'lucide-rails'
```

```bash
bundle install
```

Browse available icons at: **https://lucide.dev/icons**

---

## Basic Usage

### Standalone Icon

```erb
<%= rui_icon :heart %>
<%= rui_icon :check, color: :success %>
<%= rui_icon :x_circle, color: :danger, size: :lg %>
```

### Common Icons

```erb

<%= rui_icon :menu %>
<%= rui_icon :x %>
<%= rui_icon :search %>
<%= rui_icon :settings %>

<%= rui_icon :check, color: :success %>
<%= rui_icon :alert_circle, color: :warning %>
<%= rui_icon :x_circle, color: :danger %>
<%= rui_icon :info, color: :info %>

<%= rui_icon :arrow_right %>
<%= rui_icon :chevron_down %>
<%= rui_icon :external_link %>
```

---

## Sizes

Icon sizes range from `xs` (12px) to `xl6` (80px):

```erb
<%= rui_icon :heart, size: :xs %>    
<%= rui_icon :heart, size: :sm %>    
<%= rui_icon :heart, size: :base %>  
<%= rui_icon :heart, size: :lg %>    
<%= rui_icon :heart, size: :xl %>    
<%= rui_icon :heart, size: :xl2 %>   
<%= rui_icon :heart, size: :xl3 %>   
<%= rui_icon :heart, size: :xl4 %>   
<%= rui_icon :heart, size: :xl5 %>   
<%= rui_icon :heart, size: :xl6 %>   
```

---

## Colors

### Semantic Colors

```erb
<%= rui_icon :check, color: :primary %>
<%= rui_icon :check, color: :secondary %>
<%= rui_icon :check, color: :success %>
<%= rui_icon :alert_triangle, color: :warning %>
<%= rui_icon :x_circle, color: :danger %>
<%= rui_icon :info, color: :info %>
```

### Tailwind Colors

```erb
<%= rui_icon :heart, color: :red %>
<%= rui_icon :star, color: :yellow %>
<%= rui_icon :circle, color: :blue %>
<%= rui_icon :square, color: :'purple-500' %>
```

### Inherit Parent Color

Use `standalone: false` to inherit color from the parent element:

```erb
<div class="text-blue-600">
  <%= rui_icon :check, standalone: false %>
  This text and icon share the same color
</div>
```

---

## Usage with Buttons

Icons work great inside buttons:

```erb

<%= rui_button color: :primary do %>
  <%= rui_icon :save, size: :sm, standalone: false %>
  Save
<% end %>

<%= rui_button color: :success do %>
  <%= rui_icon :check, size: :sm, standalone: false, class: "mr-2" %>
  Confirm
<% end %>

<%= rui_button color: :danger do %>
  Delete
  <%= rui_icon :trash_2, size: :sm, standalone: false, class: "ml-2" %>
<% end %>

<%= rui_button color: :primary, class: "px-3" do %>
  <%= rui_icon :settings, size: :base, standalone: false %>
<% end %>
```

---

## Accessibility

### Decorative Icons

Icons that are purely decorative (next to text) should be hidden from screen readers:

```erb
<%= rui_button do %>
  <%= rui_icon :save, size: :sm, standalone: false, aria_hidden: true %>
  Save Post
<% end %>
```

### Semantic Icons

Icons conveying meaning should have labels:

```erb

<%= rui_icon :x, aria_label: "Close modal", class: "cursor-pointer" %>

<%= rui_icon :heart %>  
```

### Icon-Only Buttons

When buttons contain only an icon, provide an accessible label:

```erb
<%= rui_button color: :primary, aria_label: "Close" do %>
  <%= rui_icon :x, standalone: false, aria_hidden: true %>
<% end %>
```

---

## Common Patterns

### Status Indicators

```erb
<% if @post.published? %>
  <%= rui_icon :check_circle, color: :success, size: :sm %>
  Published
<% else %>
  <%= rui_icon :circle, color: :secondary, size: :sm %>
  Draft
<% end %>
```

### Loading State

```erb
<% if @loading %>
  <%= rui_icon :loader_2, class: "animate-spin" %>
  Loading...
<% else %>
  <%= rui_icon :check, color: :success %>
  Complete
<% end %>
```

### Navigation

```erb
<%= link_to posts_path, class: "flex items-center gap-2" do %>
  <%= rui_icon :arrow_left, size: :sm, standalone: false %>
  Back to Posts
<% end %>

<%= link_to post_path(@post), class: "flex items-center gap-2" do %>
  View Post
  <%= rui_icon :external_link, size: :sm, standalone: false %>
<% end %>
```

### Form Fields

```erb
<div class="relative">
  <%= form.text_field :email, class: "pl-10" %>
  <div class="absolute left-3 top-1/2 -translate-y-1/2 text-gray-400">
    <%= rui_icon :mail, size: :sm %>
  </div>
</div>
```

### Alerts

```erb
<div class="flex items-start gap-3 p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
  <%= rui_icon :check_circle, color: :success %>
  <div>
    <h4 class="font-semibold">Success!</h4>
    <p>Your post has been published.</p>
  </div>
</div>
```

---

## Dark Mode

All icon colors support dark mode automatically:

```erb
<%= rui_icon :sun, color: :primary %>

```

Use `standalone: false` for icons that should match surrounding text:

```erb
<p class="text-gray-900 dark:text-gray-100">
  <%= rui_icon :info, size: :sm, standalone: false %>
  This icon matches the text color in both modes
</p>
```

---

## Icon Name Formats

Icon names are automatically converted from snake_case to kebab-case:

```erb
<%= rui_icon :alert_circle %>   
<%= rui_icon :x_circle %>        
<%= rui_icon :chevron_down %>    
```

Both formats work:

```erb
<%= rui_icon :arrow_right %>     
<%= rui_icon "arrow-right" %>    
```

---

## Custom Attributes

Add any HTML attributes:

```erb
<%= rui_icon :heart,
  class: "hover:scale-110 transition-transform cursor-pointer",
  data: { action: "click->heart#toggle" },
  id: "favorite-icon" %>
```

---

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | Symbol/String | **required** | Lucide icon name |
| `size` | Symbol | `:base` | Icon size (`:xs` to `:xl6`) |
| `color` | Symbol | `:inherit` | Icon color (semantic or Tailwind) |
| `standalone` | Boolean | `true` | If false, inherits parent color |
| `aria_label` | String | `nil` | Accessible label for icon |
| `aria_hidden` | Boolean | `false` | Hide from screen readers |
| `**options` | Hash | `{}` | Additional HTML attributes |

---

## Examples in Posts

### Index Page

```erb

<h1 class="flex items-center gap-3">
  <%= rui_icon :file_text, size: :lg, color: :primary %>
  All Posts
</h1>

<%= link_to new_post_path, class: "inline-flex items-center gap-2" do %>
  <%= rui_icon :plus, size: :sm, standalone: false %>
  New Post
<% end %>

<% @posts.each do |post| %>
  <div class="flex items-center justify-between">
    <h3 class="flex items-center gap-2">
      <% if post.published? %>
        <%= rui_icon :check_circle, color: :success, size: :sm %>
      <% else %>
        <%= rui_icon :circle, color: :secondary, size: :sm %>
      <% end %>
      <%= post.title %>
    </h3>

<div class="flex gap-2">
      <%= link_to edit_post_path(post) do %>
        <%= rui_icon :edit, size: :sm, class: "text-blue-600" %>
      <% end %>
      <%= rui_button_to post_path(post), method: :delete,
          data: { turbo_confirm: "Delete this post?" } do %>
        <%= rui_icon :trash_2, size: :sm, standalone: false %>
      <% end %>
    </div>
  </div>
<% end %>
```

### Show Page

```erb

<div class="flex items-center gap-4 mb-6">
  <%= link_to posts_path, class: "inline-flex items-center gap-2 text-blue-600" do %>
    <%= rui_icon :arrow_left, size: :sm, standalone: false %>
    Back
  <% end %>
</div>

<%= rui_button_to post_path(@post), method: :delete, color: :danger do %>
    <%= rui_icon :trash_2, size: :sm, standalone: false, class: "mr-2" %>
    Delete
  <% end %>
end
```

---

## Tips

1. **Use `standalone: false`** when icons are inside colored containers or buttons
2. **Set `aria_hidden: true`** for decorative icons next to text
3. **Use semantic sizes** - `:sm` for inline text, `:base` for buttons, `:lg` for headings
4. **Browse icons at** https://lucide.dev/icons to find the perfect icon
5. **Icon names use kebab-case** - `arrow-right`, `check-circle`, `x-mark`

---

## See Also

- Button Component - Combine icons with buttons
- Lucide Icon Library - https://lucide.dev/icons
- lucide-rails gem - https://github.com/heyvito/lucide-rails

---

## Image (`rui_image`)

# Image Component

A semantic HTML image component for displaying content images with captions, links, and visual effects.

## Features

- **Semantic HTML**: Uses `<figure>` and `<figcaption>` when caption is present
- **Picture Element**: Art direction and format fallback with `<picture>` and `<source>` elements
- **Performance**: Built-in lazy loading, async decoding, and fetchpriority
- **Responsive**: Support for srcset and sizes attributes
- **Visual Effects**: Grayscale, blur, sepia, zoom, shine, and overlay effects
- **Flexible Layout**: Multiple sizes, shapes, aspect ratios, and alignments
- **Linkable**: Wrap images in links with proper styling
- **Social Media Sizes**: Built-in presets for Instagram, Facebook, X, LinkedIn, Pinterest, TikTok, and YouTube

## Basic Usage

```erb
<%# Simple image (positional src argument) %>
<%= rui_image("photo.jpg", alt: "A beautiful sunset") %>

<%# Alternative: keyword argument for src %>
<%= rui_image(src: "photo.jpg", alt: "A beautiful sunset") %>

<%# Image with caption (uses figure/figcaption) %>
<%= rui_image(
  "landscape.jpg",
  alt: "Mountain vista",
  caption: "View from the summit at sunrise"
) %>

<%# Linked image %>
<%= rui_image(
  "product.jpg",
  alt: "Product name",
  url: product_path(@product)
) %>
```

## Parameters

### Required

| Parameter | Type | Description |
|-----------|------|-------------|
| `src` | String | Image source URL (can be passed as first positional argument) |
| `alt` | String | Alt text for accessibility |

### Optional - Content

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `caption` | String | nil | Image caption (triggers figure/figcaption) |
| `url` | String | nil | Link URL (makes image clickable) |
| `sources` | Array | nil | Picture element sources for art direction/format fallback (see Picture Element section) |

### Optional - Size & Shape

| Parameter | Type | Default | Options |
|-----------|------|---------|---------|
| `size` | Symbol | `:auto` | `:auto`, `:full`, `:xs`, `:sm`, `:md`, `:lg`, `:xl`, `:xl2`, `:xl3`, or platform presets (see below) |
| `shape` | Symbol | `:default` | `:default`, `:rounded`, `:circle`, `:square` |
| `ratio` | Symbol | `:auto` | `:auto`, `:square`, `:video`, `:portrait`, `:landscape`, `:wide`, `:ultrawide` |
| `fit` | Symbol | `:cover` | `:cover`, `:contain`, `:fill`, `:none`, `:scale_down` |
| `position` | Symbol | `:center` | `:center`, `:top`, `:bottom`, `:left`, `:right`, `:left_top`, `:left_bottom`, `:right_top`, `:right_bottom` |
| `alignment` | Symbol | `:left` | `:left`, `:center`, `:right` (figure alignment) |

**Note:** When using platform preset sizes, the aspect ratio is automatically applied. The `ratio` parameter is ignored for platform sizes.

### Optional - Performance

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `loading` | Symbol | `:lazy` | `:lazy` or `:eager` |
| `decoding` | Symbol | `:async` | `:async`, `:sync`, or `:auto` |
| `fetchpriority` | Symbol | `:auto` | `:high`, `:low`, or `:auto` |
| `srcset` | String | nil | Responsive image sources |
| `sizes` | String | nil | Responsive image sizes |
| `width` | Integer | nil | Image width (prevents layout shift) |
| `height` | Integer | nil | Image height (prevents layout shift) |

### Optional - Security

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `crossorigin` | String | nil | CORS setting (`anonymous`, `use-credentials`) |
| `referrerpolicy` | String | nil | Referrer policy for the request |

### Optional - Visual Effects

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `grayscale` | Boolean | false | Apply grayscale effect (restores on hover) |
| `blur` | Boolean | false | Apply blur effect (restores on hover) |
| `sepia` | Boolean | false | Apply sepia effect (restores on hover) |
| `zoom` | Boolean | false | Apply zoom effect on hover |
| `shine` | Boolean | false | Apply shine effect on hover |
| `overlay` | Boolean | false | Apply dark overlay on hover |

## Size Reference

| Size | Dimensions |
|------|------------|
| `:auto` | Natural size with max-w-full |
| `:full` | 100% width |
| `:xs` | 64px (w-16 h-16) |
| `:sm` | 96px (w-24 h-24) |
| `:md` | 128px (w-32 h-32) |
| `:lg` | 192px (w-48 h-48) |
| `:xl` | 256px (w-64 h-64) |
| `:xl2` | 320px (w-80 h-80) |
| `:xl3` | 384px (w-96 h-96) |

## Aspect Ratio Reference

| Ratio | Value |
|-------|-------|
| `:auto` | Natural aspect ratio |
| `:square` | 1:1 |
| `:video` | 16:9 |
| `:portrait` | 3:4 |
| `:landscape` | 4:3 |
| `:wide` | 16:9 |
| `:ultrawide` | 21:9 |

## Social Media Platform Sizes

Built-in presets for common social media image dimensions (based on 2025 guidelines). These presets include the correct aspect ratio automatically.

### Instagram

| Size | Aspect Ratio | Original Dimensions | Description |
|------|--------------|---------------------|-------------|
| `:ig_post` | 1:1 | 1080×1080 | Standard feed post |
| `:ig_post_square` | 1:1 | 1080×1080 | Square feed post |
| `:ig_post_portrait` | 4:5 | 1080×1350 | Portrait feed post |
| `:ig_post_landscape` | 1.91:1 | 1080×566 | Landscape feed post |
| `:ig_carousel` | 4:5 | 1080×1350 | Carousel post |
| `:ig_story` | 9:16 | 1080×1920 | Story |
| `:ig_reel` | 9:16 | 1080×1920 | Reel |

### Facebook

| Size | Aspect Ratio | Original Dimensions | Description |
|------|--------------|---------------------|-------------|
| `:fb_post` | 1:1 | 1080×1080 | Standard post |
| `:fb_post_square` | 1:1 | 1080×1080 | Square post |
| `:fb_post_portrait` | 4:5 | 1080×1350 | Portrait post |
| `:fb_post_landscape` | 1.91:1 | 1080×566 | Landscape post |
| `:fb_story` | 9:16 | 1080×1920 | Story |
| `:fb_cover` | 2.7:1 | 851×315 | Cover photo |

### X (Twitter)

| Size | Aspect Ratio | Original Dimensions | Description |
|------|--------------|---------------------|-------------|
| `:x_post` | 16:9 | 1280×720 | Standard post |
| `:x_post_square` | 1:1 | 720×720 | Square post |
| `:x_post_portrait` | 9:16 | 720×1280 | Portrait post |
| `:x_header` | 3:1 | 1500×500 | Header/banner |
| `:x_banner` | 3:1 | 1500×500 | Banner (alias) |

### LinkedIn

| Size | Aspect Ratio | Original Dimensions | Description |
|------|--------------|---------------------|-------------|
| `:linkedin_post` | 1.91:1 | 1200×627 | Standard post |
| `:linkedin_post_square` | 1:1 | 1200×1200 | Square post |
| `:linkedin_post_portrait` | 4:5 | 720×900 | Portrait post |
| `:linkedin_cover` | 5.9:1 | 1128×191 | Cover image |
| `:linkedin_banner` | 5.9:1 | 1128×191 | Banner (alias) |

### Pinterest

| Size | Aspect Ratio | Original Dimensions | Description |
|------|--------------|---------------------|-------------|
| `:pin` | 2:3 | 1000×1500 | Standard pin |
| `:pin_square` | 1:1 | 1000×1000 | Square pin |

### TikTok

| Size | Aspect Ratio | Original Dimensions | Description |
|------|--------------|---------------------|-------------|
| `:tiktok_post` | 9:16 | 1080×1920 | Post/video |
| `:tiktok_video` | 9:16 | 1080×1920 | Video (alias) |

### YouTube

| Size | Aspect Ratio | Original Dimensions | Description |
|------|--------------|---------------------|-------------|
| `:yt_thumbnail` | 16:9 | 1280×720 | Video thumbnail |
| `:yt_banner` | 16:9 | 2560×1440 | Channel banner |

### Platform Size Examples

```erb
<%# Instagram feed post %>
<%= rui_image("social/campaign.jpg", alt: "Summer campaign", size: :ig_post) %>

<%# Instagram story %>
<%= rui_image("social/story.jpg", alt: "New product", size: :ig_story) %>

<%# Facebook cover %>
<%= rui_image("social/cover.jpg", alt: "Company cover", size: :fb_cover) %>

<%# X (Twitter) post %>
<%= rui_image("social/announcement.jpg", alt: "Big news", size: :x_post) %>

<%# LinkedIn article image %>
<%= rui_image("social/article.jpg", alt: "Industry insights", size: :linkedin_post) %>

<%# Pinterest pin %>
<%= rui_image("social/pin.jpg", alt: "Recipe idea", size: :pin) %>

<%# YouTube thumbnail %>
<%= rui_image("social/thumb.jpg", alt: "Video title", size: :yt_thumbnail) %>
```

## Examples

### Gallery Image with Caption

```erb
<%= rui_image(
  "gallery/sunset.jpg",
  alt: "Sunset over the Pacific Ocean",
  caption: "Malibu, California - Summer 2024",
  shape: :rounded,
  alignment: :center
) %>
```

### Product Image with Link

```erb
<%= rui_image(
  @product.image_url,
  alt: @product.name,
  url: product_path(@product),
  size: :lg,
  shape: :rounded,
  zoom: true
) %>
```

### Hero Image (Above the Fold)

```erb
<%= rui_image(
  "hero-banner.jpg",
  alt: "Welcome to our store",
  size: :full,
  ratio: :wide,
  loading: :eager,
  fetchpriority: :high,
  decoding: :sync
) %>
```

### Responsive Image

```erb
<%= rui_image(
  "photo.jpg",
  alt: "Responsive photo",
  srcset: "photo-320.jpg 320w, photo-640.jpg 640w, photo-1280.jpg 1280w",
  sizes: "(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw",
  width: 1280,
  height: 960
) %>
```

### Team Member Photo

```erb
<%= rui_image(
  team_member.photo_url,
  alt: "#{team_member.name}, #{team_member.role}",
  caption: "#{team_member.name} - #{team_member.role}",
  size: :md,
  shape: :circle,
  grayscale: true
) %>
```

### Image with Visual Effects

```erb
<%# Grayscale that restores color on hover %>
<%= rui_image(
  "portfolio/project1.jpg",
  alt: "Project screenshot",
  grayscale: true,
  zoom: true
) %>

<%# Blurred image with hover reveal %>
<%= rui_image("preview.jpg", alt: "Preview", blur: true) %>

<%# Multiple effects %>
<%= rui_image(
  "featured.jpg",
  alt: "Featured image",
  sepia: true,
  zoom: true,
  shine: true
) %>
```

**Technical Note**: The `shine` and `overlay` effects use CSS pseudo-elements (`::before`/`::after`) which don't work on `<img>` elements directly. When these effects are enabled, the component automatically wraps the image in a `<span>` element to properly render the effects.

### Cross-Origin Image

```erb
<%= rui_image(
  "https://cdn.example.com/image.jpg",
  alt: "CDN hosted image",
  crossorigin: "anonymous",
  referrerpolicy: "no-referrer"
) %>
```

## Picture Element

The `<picture>` element provides advanced image handling for two main use cases:

1. **Art Direction**: Show different images for different viewports (e.g., cropped mobile vs wide desktop)
2. **Format Fallback**: Serve modern formats (AVIF, WebP) with fallback to JPEG/PNG

### When to Use Picture vs srcset

| Use Case | Solution |
|----------|----------|
| Same image, different sizes | Use `srcset` and `sizes` on regular image |
| Different images for different viewports | Use `<picture>` with `sources` |
| Modern format with fallback | Use `<picture>` with `sources` |
| Dark mode alternative image | Use `<picture>` with `sources` |

### Source Options

Each source in the `sources` array accepts:

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `srcset` | String | Yes | Image source(s) for this source element |
| `media` | String | No | Media query (e.g., "(min-width: 1024px)") |
| `type` | String | No | MIME type (e.g., "image/avif", "image/webp") |
| `sizes` | String | No | Responsive sizes for this source |
| `width` | Integer | No | Width hint for browser |
| `height` | Integer | No | Height hint for browser |

### Art Direction Example

Show different image crops based on viewport:

```erb
<%# Different images for mobile vs desktop %>
<%= rui_image(
  "hero-fallback.jpg",
  alt: "Product showcase",
  sources: [
    { srcset: "hero-wide.jpg", media: "(min-width: 1024px)" },
    { srcset: "hero-square.jpg", media: "(min-width: 640px)" },
    { srcset: "hero-portrait.jpg", media: "(max-width: 639px)" }
  ]
) %>
```

**Real-world use case**: E-commerce hero banner that shows a wide landscape shot on desktop but a tightly cropped product focus on mobile.

### Format Fallback Example

Serve modern formats with automatic fallback:

```erb
<%# AVIF → WebP → JPEG fallback chain %>
<%= rui_image(
  "photo.jpg",
  alt: "High quality photo",
  sources: [
    { srcset: "photo.avif", type: "image/avif" },
    { srcset: "photo.webp", type: "image/webp" }
  ]
) %>
```

**Real-world use case**: Serve AVIF (50-90% smaller) to supported browsers, WebP to others, and JPEG as final fallback.

### Dark Mode Example

Show different images based on color scheme preference:

```erb
<%# Different images for light/dark mode %>
<%= rui_image(
  "logo-light.png",
  alt: "Company logo",
  sources: [
    { srcset: "logo-dark.png", media: "(prefers-color-scheme: dark)" }
  ]
) %>
```

**Real-world use case**: Logo that inverts colors or uses different contrast for dark mode.

### Combined Art Direction + Format Fallback

```erb
<%# Art direction with format optimization %>
<%= rui_image(
  "product-fallback.jpg",
  alt: "Product image",
  sources: [
    # Desktop: wide format with modern formats
    { srcset: "product-wide.avif", media: "(min-width: 1024px)", type: "image/avif" },
    { srcset: "product-wide.webp", media: "(min-width: 1024px)", type: "image/webp" },
    { srcset: "product-wide.jpg", media: "(min-width: 1024px)" },
    # Mobile: square format with modern formats
    { srcset: "product-square.avif", media: "(max-width: 1023px)", type: "image/avif" },
    { srcset: "product-square.webp", media: "(max-width: 1023px)", type: "image/webp" },
    { srcset: "product-square.jpg", media: "(max-width: 1023px)" }
  ]
) %>
```

### Picture Element with Caption

```erb
<%= rui_image(
  "artwork-fallback.jpg",
  alt: "Digital artwork",
  caption: "Created by Artist Name, 2024",
  sources: [
    { srcset: "artwork.avif", type: "image/avif" },
    { srcset: "artwork.webp", type: "image/webp" }
  ],
  shape: :rounded,
  alignment: :center
) %>
```

### Picture Element with Link

```erb
<%= rui_image(
  product.image_url,
  alt: product.name,
  url: product_path(product),
  sources: [
    { srcset: product.avif_url, type: "image/avif" },
    { srcset: product.webp_url, type: "image/webp" }
  ],
  zoom: true
) %>
```

## Semantic HTML Output

### Without Caption
```html
<img src="photo.jpg" alt="Description" loading="lazy" decoding="async" class="max-w-full object-cover">
```

### With Caption
```html
<figure class="inline-block">
  <img src="photo.jpg" alt="Description" loading="lazy" decoding="async" class="max-w-full object-cover">
  <figcaption class="mt-2 text-sm text-zinc-600 dark:text-zinc-400">Caption text</figcaption>
</figure>
```

### With Link
```html
<a href="/path" class="block overflow-hidden">
  <img src="photo.jpg" alt="Description" loading="lazy" decoding="async" class="max-w-full object-cover">
</a>
```

### With Caption and Link
```html
<figure class="inline-block">
  <a href="/path" class="block overflow-hidden">
    <img src="photo.jpg" alt="Description" loading="lazy" decoding="async" class="max-w-full object-cover">
  </a>
  <figcaption class="mt-2 text-sm text-zinc-600 dark:text-zinc-400">Caption text</figcaption>
</figure>
```

### With Picture Element (Format Fallback)
```html
<picture>
  <source srcset="photo.avif" type="image/avif">
  <source srcset="photo.webp" type="image/webp">
  <img src="photo.jpg" alt="Description" loading="lazy" decoding="async" class="max-w-full object-cover">
</picture>
```

### With Picture Element (Art Direction)
```html
<picture>
  <source srcset="hero-wide.jpg" media="(min-width: 1024px)">
  <source srcset="hero-mobile.jpg" media="(max-width: 1023px)">
  <img src="hero-fallback.jpg" alt="Description" loading="lazy" decoding="async" class="max-w-full object-cover">
</picture>
```

### Picture Element with Caption
```html
<figure class="inline-block">
  <picture>
    <source srcset="photo.avif" type="image/avif">
    <source srcset="photo.webp" type="image/webp">
    <img src="photo.jpg" alt="Description" loading="lazy" decoding="async" class="max-w-full object-cover">
  </picture>
  <figcaption class="mt-2 text-sm text-zinc-600 dark:text-zinc-400">Caption text</figcaption>
</figure>
```

### With Shine/Overlay Effects (Wrapper Element)
```html
<span class="relative inline-block overflow-hidden rounded-lg before:absolute before:inset-0 before:bg-gradient-to-r before:from-transparent before:via-white/30 before:to-transparent before:-translate-x-full hover:before:translate-x-full before:transition-transform before:duration-700 before:z-10">
  <img src="photo.jpg" alt="Description" loading="lazy" decoding="async" class="max-w-full rounded-lg object-cover">
</span>
```

## Accessibility

- Always provide meaningful `alt` text describing the image content
- Use `caption` for additional context (renders as `<figcaption>`)
- Images are lazy loaded by default to improve page performance
- Use `loading: :eager` and `fetchpriority: :high` for above-the-fold images

## Performance Tips

1. **Above the fold**: Use `loading: :eager`, `fetchpriority: :high`, `decoding: :sync`
2. **Below the fold**: Use defaults (`loading: :lazy`, `decoding: :async`)
3. **Prevent layout shift**: Always provide `width` and `height` attributes
4. **Responsive images**: Use `srcset` and `sizes` for optimal image delivery

## Image vs Avatar

Use **Image** for:
- Content images (photos, illustrations, diagrams)
- Images with captions
- Gallery images
- Product images
- Hero banners

Use **Avatar** for:
- User profile pictures
- Team member photos (without captions)
- Status indicators (online/offline)
- Grouped/stacked avatars
- Fallback to initials or icon

---

## Input (`rui_input`)

# Input Component

Text-based form input with ViewComponent + Tailwind CSS styling.

## Overview

The Input component handles text-based input types only:
- `text` - Standard text input (default)
- `email` - Email address with browser validation
- `password` - Obscured text with optional show/hide toggle
- `number` - Numeric input with min/max/step support
- `tel` - Phone number (displays phone keypad on mobile)
- `url` - URL with browser validation
- `search` - Search input with native clear button

For file uploads, use the `Upload` component (future).
For multi-line text, use the `Textarea` component (future).

## Basic Usage

### Standalone

```erb
<%= rui_input(name: :search, type: :search, placeholder: "Search...") %>
```

### In Form

```erb
<%= form_with(model: @user) do |f| %>
  <%= f.rui_input(:email, type: :email, label: "Email Address") %>
  <%= f.rui_input(:password, type: :password, label: "Password") %>
  <%= f.rui_button %>
<% end %>
```

## Variants

```erb
<%# Default - white background with border %>
<%= rui_input(name: :name, label: "Name", variant: :default) %>

<%# Filled - gray background %>
<%= rui_input(name: :name, label: "Name", variant: :filled) %>

<%# Outline - transparent background %>
<%= rui_input(name: :name, label: "Name", variant: :outline) %>
```

## Sizes

```erb
<%= rui_input(name: :name, size: :xs) %>  <%# Extra small %>
<%= rui_input(name: :name, size: :sm) %>  <%# Small %>
<%= rui_input(name: :name, size: :base) %> <%# Default %>
<%= rui_input(name: :name, size: :lg) %>  <%# Large %>
<%= rui_input(name: :name, size: :xl) %>  <%# Extra large %>
```

## Shapes

```erb
<%= rui_input(name: :name, shape: :square) %>  <%# No rounding %>
<%= rui_input(name: :name, shape: :rounded) %> <%# Default rounded %>
<%= rui_input(name: :name, shape: :pill) %>    <%# Fully rounded %>
```

## Input Types

### Text (default)

```erb
<%= f.rui_input(:name, label: "Full Name", required: true) %>
```

### Email

```erb
<%= f.rui_input(:email, type: :email, label: "Email", autocomplete: "email") %>
```

### Password with Show/Hide Toggle

Password inputs automatically get a show/hide toggle button:

```erb
<%= f.rui_input(:password, type: :password, label: "Password") %>
```

To disable the toggle, provide a custom suffix slot.

### Number with Range

```erb
<%= f.rui_input(:quantity,
  type: :number,
  label: "Quantity",
  min: 1,
  max: 100,
  step: 1
) %>

<%# For decimals, use step: "any" %>
<%= f.rui_input(:price,
  type: :number,
  label: "Price",
  min: 0,
  step: "any"
) %>
```

### Telephone

```erb
<%= f.rui_input(:phone,
  type: :tel,
  label: "Phone Number",
  placeholder: "(555) 123-4567",
  autocomplete: "tel"
) %>
```

**International numbers**: `type: :tel` auto-formats as North American
10-digit `(XXX) XXX-XXXX` while typing (`input_validation_controller.js`'s
`formatPhoneNumber`, hardcoded to NANP). For any non-NANP number this
strips/reflows digits into the wrong shape and rejects the field as
incomplete. Pass `autoformat: false` to disable it (and the `type: :url`
`https://` auto-prefixer, which `autoformat` also gates) and get a plain,
unformatted `tel` input:

```erb
<%= f.rui_input(:phone, type: :tel, autoformat: false, label: "Phone Number") %>
```

### URL

```erb
<%= f.rui_input(:website,
  type: :url,
  label: "Website",
  placeholder: "https://example.com"
) %>
```

### Search

```erb
<%= rui_input(
  name: :query,
  type: :search,
  placeholder: "Search...",
  size: :lg
) %>
```

## Prefix & Suffix Slots

### Text Prefix/Suffix

```erb
<%= rui_input(name: :price, type: :number, label: "Price") do |input| %>
  <% input.with_prefix do %>$<% end %>
  <% input.with_suffix do %>.00<% end %>
<% end %>
```

### Icon Prefix

```erb
<%= rui_input(name: :email, type: :email, label: "Email") do |input| %>
  <% input.with_prefix do %>
    <%= rui_icon(:mail, size: :sm, standalone: false) %>
  <% end %>
<% end %>
```

### Icon Suffix

```erb
<%= rui_input(name: :search, type: :search, placeholder: "Search") do |input| %>
  <% input.with_suffix do %>
    <%= rui_icon(:search, size: :sm, standalone: false) %>
  <% end %>
<% end %>
```

## Validation Attributes

```erb
<%= f.rui_input(:username,
  label: "Username",
  required: true,
  minlength: 3,
  maxlength: 20,
  pattern: "[a-zA-Z0-9_]+",
  help_text: "3-20 characters, letters, numbers, underscores only"
) %>
```

## Help Text

```erb
<%= f.rui_input(:email,
  type: :email,
  label: "Email",
  help_text: "We'll never share your email with anyone."
) %>
```

## Error State

When used through the form builder (`f.rui_input`), errors are detected
automatically from `@user.errors[:email]` - no extra options needed. This
only works via `f.rui_input`; standalone `rui_input(object: @user, method:
:email)` does not check model errors.

```erb
<%# If @user.errors[:email] has errors, the input shows error styling
    (red border) and the error message text automatically. %>
<%= f.rui_input(:email, type: :email, label: "Email") %>
```

The error message renders inside the *same* validation-message element the
`input-validation` Stimulus controller uses for real-time feedback - not a
second element - so there's no double-rendering. On first paint (e.g. a 422
re-render after a failed `create`/`update`), the server-rendered error wins;
once the user edits the field, client-side validation takes back over.

### 422 re-render example

```ruby
# app/controllers/users_controller.rb
def create
  @user = User.new(user_params)
  if @user.save
    redirect_to @user
  else
    render :new, status: :unprocessable_entity
  end
end
```

```erb
<%# app/views/users/new.html.erb %>
<%= form_with model: @user do |f| %>
  <%= f.rui_input(:email, type: :email, label: "Email") %>
  <%# @user.errors[:email] renders inline automatically if #create failed %>
<% end %>
```

## Colors

The color option controls the focus ring color:

```erb
<%# Semantic colors %>
<%= rui_input(name: :field, color: :primary) %>
<%= rui_input(name: :field, color: :success) %>
<%= rui_input(name: :field, color: :warning) %>
<%= rui_input(name: :field, color: :danger) %>
<%= rui_input(name: :field, color: :info) %>

<%# Any Tailwind color %>
<%= rui_input(name: :field, color: :indigo) %>
<%= rui_input(name: :field, color: :pink) %>
<%= rui_input(name: :field, color: :emerald) %>
```

## States

### Disabled

```erb
<%= f.rui_input(:name, label: "Name", disabled: true) %>
```

### Readonly

```erb
<%= f.rui_input(:api_key, label: "API Key", readonly: true) %>
```

## Autocomplete

```erb
<%# Common autocomplete values %>
<%= f.rui_input(:name, autocomplete: "name") %>
<%= f.rui_input(:email, type: :email, autocomplete: "email") %>
<%= f.rui_input(:password, type: :password, autocomplete: "current-password") %>
<%= f.rui_input(:new_password, type: :password, autocomplete: "new-password") %>
<%= f.rui_input(:phone, type: :tel, autocomplete: "tel") %>

<%# Disable autocomplete %>
<%= f.rui_input(:otp, autocomplete: "off") %>
```

## Input Mode

Control virtual keyboard on mobile:

```erb
<%# Numeric keyboard for PIN %>
<%= f.rui_input(:pin, inputmode: "numeric", pattern: "[0-9]*") %>

<%# Email keyboard %>
<%= f.rui_input(:email, type: :email, inputmode: "email") %>

<%# URL keyboard %>
<%= f.rui_input(:website, type: :url, inputmode: "url") %>
```

## Datalist (Autocomplete Suggestions)

```erb
<%= f.rui_input(:browser, list: "browsers") %>
<datalist id="browsers">
  <option value="Chrome">
  <option value="Firefox">
  <option value="Safari">
  <option value="Edge">
</datalist>
```

## Hiding Validation Placeholder

By default, inputs render a validation message placeholder that reserves space for error messages. When using inputs in filter bars or search forms where validation isn't needed, disable this to remove the gap:

```erb
<%# In a filter bar - no validation placeholder %>
<%= rui_input(
  name: :search,
  type: :search,
  placeholder: "Search...",
  validation: false
) %>
```

## Custom Styling

RapidRailsUI uses `tailwind_merge` to intelligently merge custom classes with defaults. Custom classes override conflicting default classes rather than being ignored.

### Input Element (class:)

Override the main input element styling:

```erb
<%# Custom border color %>
<%= rui_input(name: :field, class: "border-purple-500 focus:ring-purple-500") %>

<%# Custom background %>
<%= rui_input(name: :field, class: "bg-yellow-50") %>

<%# Multiple overrides %>
<%= rui_input(name: :field, class: "border-2 border-indigo-500 rounded-none") %>
```

### Wrapper (wrapper_class:)

Override the outer container:

```erb
<%# Fixed width %>
<%= rui_input(name: :field, wrapper_class: "w-64") %>

<%# Max width %>
<%= rui_input(name: :field, wrapper_class: "max-w-xs") %>

<%# Custom spacing %>
<%= rui_input(name: :field, wrapper_class: "gap-3") %>
```

### Label (label_class:)

Override the label styling:

```erb
<%# Custom label color %>
<%= rui_input(name: :field, label: "Field", label_class: "text-indigo-600") %>

<%# Larger label %>
<%= rui_input(name: :field, label: "Field", label_class: "text-base font-bold") %>
```

### Prefix/Suffix (prefix_class:, suffix_class:)

Override prefix and suffix containers:

```erb
<%# Custom prefix background %>
<%= rui_input(name: :price, prefix_class: "bg-zinc-100") do |input| %>
  <% input.with_prefix do %>$<% end %>
<% end %>

<%# Custom suffix color %>
<%= rui_input(name: :email, suffix_class: "text-indigo-500") do |input| %>
  <% input.with_suffix do %>
    <%= rui_icon(:mail, size: :sm) %>
  <% end %>
<% end %>
```

### Input Container (container_class:)

Override the container that wraps input + prefix/suffix:

```erb
<%# Custom container background %>
<%= rui_input(name: :search, container_class: "bg-zinc-50 rounded-lg") do |input| %>
  <% input.with_prefix do %>
    <%= rui_icon(:search, size: :sm) %>
  <% end %>
<% end %>
```

### Help Text (help_text_class:)

Override the help text styling:

```erb
<%# Custom help text color %>
<%= rui_input(name: :field, help_text: "Helper info", help_text_class: "text-indigo-500") %>

<%# Larger help text %>
<%= rui_input(name: :field, help_text: "Important note", help_text_class: "text-sm font-medium") %>
```

### Combined Example

```erb
<%= rui_input(
  name: :email,
  type: :email,
  label: "Email Address",
  help_text: "We'll never share your email",
  class: "border-indigo-300 focus:ring-indigo-500",
  wrapper_class: "max-w-md",
  label_class: "text-indigo-700 font-semibold",
  help_text_class: "text-indigo-400 italic"
) %>
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `form` | FormBuilder | nil | Form builder instance (auto-set by f.rui_input) |
| `object` | Object/Symbol | nil | Object to bind to |
| `method` | Symbol | nil | Attribute name |
| `type` | Symbol | :text | Input type (text, email, password, number, tel, url, search) |
| `name` | String | auto | Input name attribute |
| `value` | String | auto | Input value |
| `placeholder` | String | nil | Placeholder text |
| `required` | Boolean | false | Show required indicator |
| `readonly` | Boolean | false | Make input readonly |
| `disabled` | Boolean | false | Disable input |
| `pattern` | String | nil | Validation regex pattern |
| `maxlength` | Integer | nil | Maximum character length |
| `minlength` | Integer | nil | Minimum character length |
| `min` | Numeric | nil | Minimum value (number) |
| `max` | Numeric | nil | Maximum value (number) |
| `step` | Numeric/String | nil | Step value (number, "any" for decimals) |
| `autocomplete` | String/Symbol | nil | Autocomplete hint |
| `inputmode` | String/Symbol | nil | Virtual keyboard hint |
| `list` | String | nil | Datalist ID |
| `label` | String | nil | Label text |
| `help_text` | String | nil | Help text below input |
| `validation` | Boolean | true | Show validation message placeholder (set false for filter inputs) |
| `variant` | Symbol | :default | Visual variant (default, filled, outline) |
| `color` | Symbol | :default | Focus ring color |
| `autoformat` | Boolean | true | Auto-format `type: :tel`/`:url` input as the user types (see Telephone section below for the international-number caveat). `false` disables both formatters entirely. |
| `size` | Symbol | :base | Size (xs, sm, base, lg, xl) |
| `shape` | Symbol | :rounded | Shape (square, rounded, pill) |
| `class` | String | nil | Custom classes for input element (overrides defaults) |
| `wrapper_class` | String | nil | Custom classes for outer wrapper |
| `label_class` | String | nil | Custom classes for label element |
| `prefix_class` | String | nil | Custom classes for prefix container |
| `suffix_class` | String | nil | Custom classes for suffix container |
| `container_class` | String | nil | Custom classes for input container (with prefix/suffix) |
| `help_text_class` | String | nil | Custom classes for help text |

## Slots

| Slot | Description |
|------|-------------|
| `prefix` | Leading content (icon or text) |
| `suffix` | Trailing content (icon or text) |

Note: Password inputs automatically use the suffix slot for the show/hide toggle.

## Accessibility

- Labels are associated with inputs via `for`/`id`
- `aria-required` added when required
- `aria-invalid` added when errors present
- `aria-describedby` links to help text and error messages
- Error messages have `role="alert"`
- Password toggle has `aria-label`

---

## Kanban (`rui_kanban`)

# Kanban Board

Drag-and-drop kanban board for organizing content into columns. Columns hold
arbitrary cards — tickets, deals, profiles, contacts, anything.

Uses HTML5 native Drag and Drop API + Stimulus.js. No external JS libraries.

## Basic Usage

```erb
<%= rui_kanban do |board| %>
  <% board.with_column(title: "To Do", id: "todo") do |col| %>
    <% col.with_card(id: "card-1") do %>
      <p class="font-medium">Fix login bug</p>
      <p class="text-xs text-zinc-500">Priority: High</p>
    <% end %>
  <% end %>

<% board.with_column(title: "In Progress", id: "wip") do |col| %>
    <% col.with_card(id: "card-2") do %>
      <p class="font-medium">Design new dashboard</p>
    <% end %>
  <% end %>

<% board.with_column(title: "Done", id: "done") do |col| %>
    <% col.with_card(id: "card-3") do %>
      <p class="font-medium">Deploy v2.0</p>
    <% end %>
  <% end %>
<% end %>
```

## Board Parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | String | auto | Board HTML id |
| `color` | Symbol | `:zinc` | Default column accent color |
| `size` | Symbol | `:base` | `:sm`, `:base`, `:lg` |
| `shape` | Symbol | `:rounded` | `:rounded`, `:square` |
| `column_width` | String | `"320px"` | CSS width per column |
| `max_height` | String | `nil` | Max height for card area (scrollable) |
| `draggable` | Boolean | `true` | Enable drag-and-drop |
| `move_url` | String | `nil` | URL for auto-PATCH on card move |

## Column Parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | String | required | Column identifier |
| `title` | String | required | Header text |
| `color` | Symbol | inherits | Column accent color (top border) |
| `badge_count` | Integer | `nil` | Card count in header |
| `max_cards` | Integer | `nil` | Disable drops when full |
| `droppable` | Boolean | `true` | Accept card drops |

## Card Parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | String | required | Card identifier |
| `color` | Symbol | `nil` | Left-border accent color |
| `draggable` | Boolean | inherits | Can this card be dragged |
| `title` | String | `nil` | Optional card title (renders header section) |
| `subtitle` | String | `nil` | Optional card subtitle (rendered under title) |

## Card Title & Subtitle

Quickly render structured cards without a custom layout block. Pass `title:` and/or `subtitle:` and the card renders a header section above the block content (or in place of it).

```erb
<%= rui_kanban do |board| %>
  <% board.with_column(title: "Inventory", id: "inv") do |col| %>
    <%# No block: title + subtitle only %>
    <% col.with_card(id: "lot-1", title: "Lot 001", subtitle: "Black Angus, 6 head") %>

<%# With block: title renders above custom body %>
    <% col.with_card(id: "lot-2", title: "Lot 002", subtitle: "Hereford") do %>
      <div class="mt-1 flex gap-1">
        <%= rui_badge("Open", color: :success) %>
      </div>
    <% end %>
  <% end %>
<% end %>
```

## Colors

```erb
<%# Board default color applies to all columns %>
<%= rui_kanban(color: :info) do |board| %>
  <%# Column overrides board default %>
  <% board.with_column(title: "Urgent", id: "urgent", color: :danger) do |col| %>
    <%# Card has its own accent color (left border) %>
    <% col.with_card(id: "c1", color: :warning) do %>
      High priority task
    <% end %>
  <% end %>
<% end %>
```

## Column Footer

```erb
<%= rui_kanban do |board| %>
  <% board.with_column(title: "Backlog", id: "backlog") do |col| %>
    <% col.with_card(id: "c1") { "Task" } %>
    <% col.with_footer do %>
      <button class="text-sm text-zinc-500 hover:text-zinc-700">+ Add Card</button>
    <% end %>
  <% end %>
<% end %>
```

## Custom Column Header

```erb
<%= rui_kanban do |board| %>
  <% board.with_column(title: "ignored", id: "col") do |col| %>
    <% col.with_header do %>
      <div class="flex items-center gap-2">
        <span class="font-bold">Custom</span>
        <span class="text-xs bg-red-100 text-red-600 px-1 rounded">3</span>
      </div>
    <% end %>
  <% end %>
<% end %>
```

## Server Persistence (auto-PATCH)

```erb
<%= rui_kanban(move_url: kanban_move_path) do |board| %>
  <% board.with_column(title: "To Do", id: "todo") do |col| %>
    <% col.with_card(id: "card-1") { "Task" } %>
  <% end %>
<% end %>
```

When a card is dropped, the controller sends:

```json
PATCH /kanban/move
{ "card_id": "card-1", "column_id": "done", "position": 0 }
```

Accepts Turbo Stream responses for server-driven UI updates.

## Event Handling (manual)

```javascript
// Listen for card moves without auto-PATCH
document.addEventListener("kanban:move", (event) => {
  const { cardId, fromColumnId, toColumnId, position } = event.detail
  // Handle the move manually
})
```

| Event | Detail | When |
|-------|--------|------|
| `kanban:move` | `{ cardId, fromColumnId, toColumnId, position }` | Card dropped |
| `kanban:move-failed` | `{ cardId, error }` | Server persist failed |
| `kanban:grab` | `{ cardId }` | Keyboard grab |
| `kanban:cancel` | `{ cardId }` | Grab cancelled |

## Keyboard Navigation

| Key | Action |
|-----|--------|
| Space | Grab / drop card |
| Arrow Up/Down | Move within column |
| Arrow Left/Right | Move to adjacent column |
| Escape | Cancel move |

## Sizes

```erb
<%= rui_kanban(size: :sm) do |board| %>
  <%# Compact board %>
<% end %>

<%= rui_kanban(size: :lg) do |board| %>
  <%# Spacious board %>
<% end %>
```

## Scrollable Columns

```erb
<%= rui_kanban(max_height: "400px") do |board| %>
  <%# Card lists scroll when they exceed 400px %>
<% end %>
```

## WIP Limits

```erb
<%= rui_kanban do |board| %>
  <% board.with_column(title: "In Progress", id: "wip", max_cards: 3, badge_count: 2) do |col| %>
    <%# Drops are rejected when column has 3+ cards %>
  <% end %>
<% end %>
```

## Static Board (no drag)

```erb
<%= rui_kanban(draggable: false) do |board| %>
  <%# Read-only board %>
<% end %>
```

## Accessibility

- Board: `role="region"` with `aria-label="Kanban board"`
- Card lists: `role="list"` with `aria-label="{column title} cards"`
- Cards: `role="listitem"`, `aria-roledescription="draggable card"`
- Screen reader: ARIA live region announces all moves
- Keyboard: Full grab/move/drop/cancel via Space, Arrows, Escape

---

## Link (`rui_link`)

# RapidRailsUI Link Component Usage

The `Link` component renders an `<a>` element with conditional rendering support and full Turbo integration. It provides Rails-style syntax, underline variants, and context-aware behavior.

**Default behavior:** Links are blue and show an underline on hover for clear visual feedback.

---

## Key Features

- **Conditional Rendering**, Support for `if:`, `unless:`, and `unless_current:`
- **Turbo Integration**, Full support for Turbo Frame, Stream, Method, and Prefetch
- **External Links**, Automatic security attributes for external URLs
- **Icon Support**, Leading and trailing icons with color override
- **Underline Variants**, Four different underline styles
- **Active State**, Highlight navigation/tabs with active styling
- **Text Truncation**, Auto-truncate long text with tooltips
- **SEO Features**, Enhanced rel attributes (sponsored, ugc, nofollow)
- **Communication Links**, Shortcuts for email, phone, and SMS links
- **Accessibility**, HrefLang, tooltips, and referrer policy support

---

## Basic Usage

```erb

<%= rui_link("View Posts", "/posts") %>

<%= rui_link("View Posts", "/posts", color: :primary) %>

<%= rui_link("/posts") do %>
  View Posts
<% end %>

<%= rui_link(post_path(@post), class: "custom-class") do %>
  Read Full Post
<% end %>

<%= rui_link(url: "/posts", text: "View Posts", color: :primary) %>
```

**Signature matches Rails `link_to`:**
- **Positional (text first):** `rui_link("text", "/url", options)`
- **Block (URL first):** `rui_link("/url", options) { "text from block" }`

## Underline Variants

Links have four underline styles optimized for different use cases:

```erb

<%= rui_link("Hover Underline", "#", variant: :hover_underline) %>

<%= rui_link("Underline", "#", variant: :underline) %>

<%= rui_link("No Underline", "#", variant: :no_underline) %>

<%= rui_link("Animated", "#", variant: :animated_underline) %>
```

**Default:** `:hover_underline` - Shows underline on hover, providing clear visual feedback.

## Colors

### Semantic Colors (Configurable)

These colors are configurable via `config/initializers/rapidrailsui.rb`:

```erb
<%= rui_link("Primary", "#", color: :primary) %>     
<%= rui_link("Secondary", "#", color: :secondary) %>  
<%= rui_link("Accent", "#", color: :accent) %>       
```

### Standard UI Colors

```erb
<%= rui_link("Success", "#", color: :success) %>   
<%= rui_link("Danger", "#", color: :danger) %>     
<%= rui_link("Warning", "#", color: :warning) %>   
<%= rui_link("Info", "#", color: :info) %>         
```

### Tailwind Palette Colors

All 22 Tailwind color families supported:

```erb
<%= rui_link("Blue", "#", color: :blue) %>     
<%= rui_link("Red", "#", color: :red) %>
<%= rui_link("Emerald", "#", color: :emerald) %>
<%= rui_link("Purple", "#", color: :purple) %>

```

**Default:** `:blue` - Standard web link color.

## Sizes

Five text size options:

```erb
<%= rui_link("Extra Small", "#", size: :xs) %>
<%= rui_link("Small", "#", size: :sm) %>
<%= rui_link("Base", "#", size: :base) %>          
<%= rui_link("Large", "#", size: :lg) %>
<%= rui_link("Extra Large", "#", size: :xl) %>
```

## With Icons

Icons automatically inherit the link color. Supports both leading and trailing positions:

```erb

<%= rui_link("Download", "#") do |link| %>
  <% link.with_icon(:download) %>
<% end %>

<%= rui_link("Next Page", "#") do |link| %>
  <% link.with_icon(:arrow_right, position: :trailing) %>
<% end %>

<% link.with_icon(:heart) %>                        
<% link.with_icon(name: :heart) %>                  
<% link.with_icon(:arrow_right, position: :trailing) %>
```

**Note:** Uses Lucide icons (1500+ available). Requires `lucide-rails` gem.

### Icon Color Override

Icons automatically inherit the link's color, but you can override with a custom color:

```erb
<%# Icon inherits link color (default behavior) %>
<%= rui_link("Posts", "/posts", color: :blue) do |link| %>
  <% link.with_icon(:heart) %>
  <%# Icon will be blue %>
<% end %>

<%# Icon with custom color (overrides inheritance) %>
<%= rui_link("Posts", "/posts", color: :blue) do |link| %>
  <% link.with_icon(:heart, color: :red) %>
  <%# Blue link with red heart icon %>
<% end %>

<%# Useful for status indicators %>
<%= rui_link("Notifications", "/notifications") do |link| %>
  <% link.with_icon(:bell, color: :red) %>
  <%# Default link color with red notification icon %>
<% end %>
```

**Note:** When you provide an explicit `color:` parameter to the icon, it uses standalone mode and renders with its own color instead of inheriting from the link.

## States

### Disabled State

```erb
<%= rui_link("Disabled Link", "#", disabled: true) %>

```

### Loading State

```erb
<%= rui_link("Loading", "#", loading: true) %>

```

## Conditional Rendering

Links can conditionally render as text based on logic:

### If/Unless Conditions

```erb

<%= rui_link("Admin Panel", "/admin", if: current_user.admin?) %>

<%= rui_link("Posts", "/posts", unless: read_only_mode?) %>

<%= rui_link("Feature", "#", if: false) %>
```

### Unless Current (Navigation)

Perfect for navigation menus - renders as text when on current page:

```erb
<nav>
  <%= rui_link("Home", "/", unless_current: true) %>
  <%= rui_link("About", "/about", unless_current: true) %>
  <%= rui_link("Blog", "/blog", unless_current: true) %>
</nav>
```

When on the current page, the link renders as muted text instead of a clickable link.

### Real-Life Examples: Post Management

```erb
<%# Show different actions based on post state and user permissions %>
<div class="post-actions flex gap-2">
  <%# Edit link - only for post owner or admin %>
  <%= rui_link(edit_post_path(@post), "Edit",
    if: current_user.can_edit?(@post),
    color: :primary) do |link|
    link.with_icon(:edit)
  end %>

<%# Publish link - only for unpublished posts %>
  <%= rui_link(publish_post_path(@post), "Publish",
    if: !@post.published?,
    color: :success,
    turbo_method: :patch) do |link|
    link.with_icon(:send)
  end %>

<%# View link - renders as text when on current post page %>
  <%= rui_link(post_path(@post), "View",
    unless_current: true,
    color: :blue) %>

<%# Premium feature - only for premium users %>
  <%= rui_link(analytics_post_path(@post), "Analytics",
    if: current_user.premium?,
    color: :purple) do |link|
    link.with_icon(:bar_chart)
  end %>
</div>
```

## External Links

Automatically adds security attributes for external URLs:

```erb
<%= rui_link("Visit GitHub", "https://github.com", external: true) %>

<%= rui_link("External", "https://example.com", target: "_blank") %>
```

External links automatically show a small icon indicator.

## HTTP Methods

For non-GET requests, links automatically wrap in a form:

```erb

<%= rui_link("Delete", "/posts/1", method: :delete, color: :danger) %>

<%= rui_link("Subscribe", "/subscribe", method: :post, color: :primary) %>
```

**Note:** For RESTful actions, consider using `rui_button_to` instead for better semantics.

## Turbo Integration

Full support for Hotwire Turbo features:

### Turbo Methods

```erb

<%= rui_link("Delete", "/posts/1", turbo_method: :delete) %>

<%= rui_link("Delete", "/posts/1",
  turbo_method: :delete,
  turbo_confirm: "Are you sure?") %>
```

### Turbo Frames

```erb

<%= rui_link("New Post", "/posts/new", turbo_frame: "modal") %>

<%= rui_link("All Posts", "/posts", turbo_frame: "_top") %>
```

### Turbo Streams

```erb

<%= rui_link("Load More", "/posts", turbo_stream: true) %>
```

### Turbo Actions

```erb

<%= rui_link("Refresh", "/posts", turbo_action: :replace) %>
```

### Turbo Prefetch

Prefetch pages on hover for instant navigation (Turbo 8+ feature):

```erb

<%= rui_link("Posts", "/posts", turbo_prefetch: true) %>

<nav>
  <%= rui_link("Home", "/", turbo_prefetch: true) %>
  <%= rui_link("About", "/about", turbo_prefetch: true) %>
  <%= rui_link("Blog", "/blog", turbo_prefetch: true) %>
</nav>
```

**How it works:** When a user hovers over the link, Turbo prefetches the page in the background. When they click, the page loads instantly from cache.

**Note:** Only use for navigation links, not for forms or actions that change data.

### Real-Life Examples: Post Actions with Turbo

```erb
<%# Post index page with Turbo Frames %>
<turbo-frame id="posts-list">
  <% @posts.each do |post| %>
    <div class="post-card">
      <h3><%= post.title %></h3>

<%# Quick publish/unpublish with Turbo method %>
        <% if post.published? %>
          <%= rui_link(unpublish_post_path(post), "Unpublish",
            turbo_method: :patch,
            turbo_confirm: "Unpublish this post?",
            color: :warning) do |link|
            link.with_icon(:eye_off)
          end %>
        <% else %>
          <%= rui_link(publish_post_path(post), "Publish",
            turbo_method: :patch,
            color: :success) do |link|
            link.with_icon(:send)
          end %>
        <% end %>

<%# Delete with confirmation %>
        <%= rui_link(post_path(post), "Delete",
          turbo_method: :delete,
          turbo_confirm: "Are you sure? This cannot be undone.",
          color: :danger) do |link|
          link.with_icon(:trash_2)
        end %>
      </div>
    </div>
  <% end %>

<%# Load more posts with Turbo Stream %>
  <%= rui_link(posts_path(page: @next_page), "Load More Posts",
    turbo_stream: true,
    variant: :outline) if @next_page %>
</turbo-frame>

<%# Modal frame for editing %>
<turbo-frame id="modal">
  <%# Content loads here when clicking Edit %>
</turbo-frame>

<%# Post detail page with instant navigation %>
<div class="post-detail">
  <h1><%= @post.title %></h1>

<%= rui_link("All Posts", posts_path,
      turbo_prefetch: true,
      turbo_action: :replace,
      variant: :hover_underline) %>

<%= rui_link(post_path(@post.next), "Next Post →",
      turbo_prefetch: true,
      variant: :hover_underline) if @post.next %>
  </nav>

<%# Author card that loads in sidebar frame %>
  <%= rui_link(user_path(@post.author), "View Author Profile",
    turbo_frame: "sidebar",
    color: :blue) %>
</div>
```

## Advanced Features

### Active State

Highlight the current/active link in navigation or tabs:

```erb

<%= rui_link("Posts", "/posts", active: true) %>

<nav>
  <%= rui_link("Home", "/", active: current_page?("/")) %>
  <%= rui_link("Posts", "/posts", active: current_page?("/posts")) %>
  <%= rui_link("About", "/about", active: current_page?("/about")) %>
</nav>

```

**Styling:** Active links are always underlined, font-semibold, and use a darker shade of the color.

### Navigation Variant

The `:nav` variant is specifically designed for sidebar and navigation menus. It automatically detects the current page and applies appropriate styling without manual `current_page?` checks:

```erb

<nav class="space-y-1">
  <%= rui_link("Button", docs_button_path, variant: :nav) %>
  <%= rui_link("Link", docs_link_path, variant: :nav) %>
  <%= rui_link("Icon", docs_icon_path, variant: :nav) %>
</nav>

<nav class="space-y-1">
  <%= rui_link("Button", docs_button_path, variant: :nav, color: :sky) %>
  <%= rui_link("Link", docs_link_path, variant: :nav, color: :sky) %>
</nav>
```

**Features:**
- **Auto-detection**: Automatically detects current page (no need for `current_page?` checks)
- **Default color**: Uses `:neutral` (gray) by default for standard navigation
- **Color theming**: Can use any color for color-coded navigation sections
- **Active state**: Shows background color when active, subtle text color when inactive
- **Block-level**: Renders as block with padding, suitable for vertical navigation

**Styling:**
- **Active**: Background color with white text (e.g., `bg-neutral-600 text-white`)
- **Inactive**: Subtle text color with hover background (e.g., `text-neutral-700 hover:bg-neutral-100`)

**Real-world example - Sidebar navigation:**

```erb
<aside class="w-64 space-y-6">
  <%# Getting Started Section %>
  <div>
    <h3 class="text-xs font-semibold text-zinc-500 uppercase tracking-wider mb-3">
      Getting Started
    </h3>
    <nav class="space-y-1">
      <%= rui_link("Introduction", docs_introduction_path, variant: :nav) %>
      <%= rui_link("Installation", docs_installation_path, variant: :nav) %>
      <%= rui_link("Quickstart", docs_quickstart_path, variant: :nav) %>
    </nav>
  </div>

<%# Components Section - Color themed %>
  <div>
    <h3 class="text-xs font-semibold text-zinc-500 uppercase tracking-wider mb-3">
      Components
    </h3>
    <nav class="space-y-1">
      <%= rui_link("Button", docs_button_path, variant: :nav, color: :sky) %>
      <%= rui_link("Link", docs_link_path, variant: :nav, color: :sky) %>
      <%= rui_link("Badge", docs_badge_path, variant: :nav, color: :sky) %>
    </nav>
  </div>
</aside>
```

**Comparison with other approaches:**

```erb
<%# ❌ Old way - Manual current_page? check with CSS classes %>
<%= link_to "Button", docs_button_path,
  class: "block px-3 py-2 text-sm font-medium #{current_page?(docs_button_path) ? 'bg-zinc-500 text-white' : 'text-zinc-700 hover:bg-zinc-100'} rounded-lg" %>

<%# ❌ Using unless_current - Hides link when active %>
<%= rui_link("Button", docs_button_path, unless_current: true) %>

<%# ✅ Navigation variant - Clean, automatic, and styled for navigation %>
<%= rui_link("Button", docs_button_path, variant: :nav) %>
```

**When to use:**
- Sidebar navigation menus
- Vertical navigation lists
- Documentation table of contents
- Admin panel navigation
- Dashboard sidebars

**When NOT to use:**
- Horizontal navigation bars (use `active: current_page?(path)` instead)
- Inline text links (use `:hover_underline` variant)
- Button-style navigation (use button component)

### Tooltips

Add tooltips (title attribute) to links:

```erb

<%= rui_link("API", "/docs", title: "View API Documentation") %>

<%= rui_link("API", "/docs", tooltip: "View API Documentation") %>

```

**Accessibility:** Tooltips provide additional context for screen readers and visual users.

### Text Truncation

Automatically truncate long text with automatic title tooltip:

```erb

<%= rui_link("/posts/123", @post.very_long_title, truncate: true) %>

<%= rui_link("/posts/123", @post.very_long_title, truncate: 50) %>

```

**Auto-tooltip:** When truncated, the full text is automatically shown in a tooltip on hover.

### Enhanced Rel Attributes

Full control over link relationships for SEO and security:

```erb

<%= rui_link("Sponsor", "https://example.com", rel: "sponsored", external: true) %>

<%= rui_link(@comment.website, @comment.author, rel: "ugc nofollow", external: true) %>

<%= rui_link("Link", "#", rel: "nofollow sponsored") %>
<%= rui_link("Link", "#", rel: ["nofollow", "sponsored"]) %>

<%= rui_link("External", "https://example.com", external: true) %>

```

**Common rel values:**
- `noopener noreferrer` - Security for external links (automatic with external: true)
- `sponsored` - Paid/affiliate links
- `ugc` - User-generated content
- `nofollow` - Don't follow for SEO

### Scroll Behavior

Control scroll behavior for anchor links:

```erb

<%= rui_link("Features", "#features", scroll: :smooth) %>

<%= rui_link("Back to Top", "#top", scroll: :instant) %>

<%= rui_link("Section", "#section", scroll: :auto) %>
```

**Note:** Works with anchor links (href="#section"). Requires modern browser support.

### Multilingual Links (HrefLang)

Indicate the language of the linked resource:

```erb

<%= rui_link("À propos", "/fr/about", hreflang: "fr") %>

<%= rui_link("Acerca de", "/es/about", hreflang: "es") %>

<div class="language-switcher">
  <%= rui_link("English", "/en/page", hreflang: "en") %>
  <%= rui_link("Français", "/fr/page", hreflang: "fr") %>
  <%= rui_link("Español", "/es/page", hreflang: "es") %>
</div>
```

**SEO Benefit:** Helps search engines understand language variations of your content.

### Referrer Policy

Control what referrer information is sent with the link:

```erb

<%= rui_link("Private Link", "https://example.com",
  referrerpolicy: "no-referrer", external: true) %>

<%= rui_link("Analytics", "https://analytics.example.com",
  referrerpolicy: "origin", external: true) %>

<%= rui_link("Secure Link", "https://example.com",
  referrerpolicy: "strict-origin-when-cross-origin", external: true) %>
```

**Common policies:**
- `no-referrer` - Don't send any referrer (maximum privacy)
- `origin` - Send only origin (https://example.com), not full URL
- `strict-origin-when-cross-origin` - Full URL for same-origin, origin for cross-origin

## URL Options

### Query Parameters

```erb
<%= rui_link("Search", "/search", params: { q: "rails", sort: "recent" }) %>

```

### Anchors

```erb
<%= rui_link("Features", "/docs", anchor: "features") %>

```

### Download Attribute

```erb
<%= rui_link("Download Report", "/files/report.pdf", download: "report.pdf") %>
```

### Communication Links

Three dedicated helpers provide `mail_to`, `phone_to`, and `sms_to` equivalent functionality with full RapidRailsUI styling:

- `rui_mailto(text, address, **options)` — email links
- `rui_tel(text, number, **options)` — phone links
- `rui_sms(text, number, **options)` — SMS links

All three accept the same styling params as `rui_link` (`variant:`, `color:`, `size:`, `shape:`, etc.) and support icon slots.

#### `rui_mailto` — Email Links

```erb
<%# Basic %>
<%= rui_mailto("Email Us", "contact@example.com") %>

<%# With subject and body %>
<%= rui_mailto("Send Feedback", "feedback@example.com",
  subject: "Product Feedback",
  body: "I love your product!") %>

<%# With CC/BCC/reply-to %>
<%= rui_mailto("Email Team", "team@example.com",
  cc: "manager@example.com",
  bcc: ["archive@example.com", "log@example.com"],
  reply_to: "support@example.com") %>

<%# With styling and icon %>
<%= rui_mailto("Contact Sales", "sales@example.com",
  subject: "Sales Inquiry from #{current_user.name}",
  color: :primary) do |link|
  link.with_icon(:mail)
end %>
```

**Parameters:** `subject:`, `body:`, `cc:`, `bcc:`, `reply_to:` + all `rui_link` styling params.

#### `rui_tel` — Phone Links

```erb
<%# Basic %>
<%= rui_tel("Call Us", "555-1234") %>

<%# With country code (+ is optional, auto-normalized) %>
<%= rui_tel("Call US", "555-1234", country_code: "1") %>
<%= rui_tel("Call UK", "20 7946 0958", country_code: "+44") %>

<%# With styling and icon %>
<%= rui_tel("Emergency Support", "911", color: :danger, size: :lg) do |link|
  link.with_icon(:phone_call)
end %>
```

**Parameters:** `country_code:` + all `rui_link` styling params.

#### `rui_sms` — SMS Links

```erb
<%# Basic %>
<%= rui_sms("Text Us", "555-1234") %>

<%# With pre-filled body %>
<%= rui_sms("Confirm Appointment", "555-DOCTOR",
  body: "CONFIRM appointment for #{@appointment.date}") %>

<%# With country code %>
<%= rui_sms("Text Support", "555-SUPPORT",
  country_code: "1",
  body: "Order ##{@order.id} - ") %>
```

**Parameters:** `body:`, `country_code:` + all `rui_link` styling params.

**Platform compatibility:**

- **Email**: `subject`, `body`, `cc`, `bcc`, `reply-to` work in all major email clients
- **Phone**: Country codes work universally with `tel:` protocol
- **SMS**: `body` parameter support varies — ✅ iOS (full), ⚠️ Android (partial), ❌ Desktop (unsupported)

**Direct URL alternative:**

```erb
<%= rui_link("Email Us", "mailto:contact@example.com") %>
<%= rui_link("Call Us", "tel:+1-555-1234") %>
<%= rui_link("Text Us", "sms:+1-555-1234") %>
```

> **Deprecated:** The `email:`, `phone:`, and `sms:` params on `rui_link` are deprecated and emit a deprecation warning. Use the dedicated helpers above instead.

## Full Width

```erb
<%= rui_link("Full Width Link", "#", full_width: true) %>

```

## Data Attributes

```erb
<%= rui_link("Analytics Link", "#",
  data: {
    controller: "analytics",
    action: "click->analytics#track",
    category: "navigation"
  }) %>
```

## Real-World Examples

### Link in Paragraph

```erb
<p class="text-zinc-700 dark:text-zinc-300">
  RapidRailsUI is a ViewComponent-based UI library. Learn more in our
  <%= rui_link("documentation", "/docs") %> or check out the
  <%= rui_link("source code", "https://github.com", external: true) %> on GitHub.
</p>
```

### Icon Links for Actions

```erb
<div class="flex gap-4">
  <%= rui_link("#") do |link| %>
    <% link.with_icon(:download) %>
    Download PDF
  <% end %>

<%= rui_link("#") do |link| %>
    <% link.with_icon(:share_2) %>
    Share
  <% end %>
</div>
```

### Call-to-Action Links

```erb
<%= rui_link("/signup", size: :lg, color: :primary) do |link| %>
  Get Started
  <% link.with_icon(:arrow_right, position: :trailing) %>
<% end %>
```

### Card with Action Link

```erb
<div class="bg-white dark:bg-zinc-800 p-6 rounded-lg border">
  <h4 class="text-lg font-semibold mb-2">Featured Post</h4>
  <p class="text-sm text-zinc-600 dark:text-zinc-400 mb-4">
    Learn how to build amazing Rails applications with our latest tutorial.
  </p>
  <%= rui_link("/posts/1", color: :primary) do |link| %>
    Read more
    <% link.with_icon(:arrow_right, position: :trailing) %>
  <% end %>
</div>
```

### Navigation with Active States

```erb
<nav class="flex gap-6">
  <%= rui_link("Home", "/", unless_current: true) %>
  <%= rui_link("About", "/about", unless_current: true) %>
  <%= rui_link("Blog", "/blog", unless_current: true) %>
  <%= rui_link("Contact", "/contact", unless_current: true) %>
</nav>
```

### List of Related Links

```erb
<ul class="space-y-2">
  <li>
    <%= rui_link("/docs/button", variant: :hover_underline) do |link| %>
      <% link.with_icon(:circle) %>
      Button Component
    <% end %>
  </li>
  <li>
    <%= rui_link("/docs/icon", variant: :hover_underline) do |link| %>
      <% link.with_icon(:circle) %>
      Icon Component
    <% end %>
  </li>
</ul>
```

### Footer Links

```erb
<footer class="bg-zinc-100 dark:bg-zinc-800 p-6">
  <div class="grid grid-cols-3 gap-6">
    <div>
      <h5 class="text-sm font-semibold mb-3">Product</h5>
      <ul class="space-y-2 text-sm">
        <li><%= rui_link("Features", "/features", variant: :hover_underline, color: :zinc) %></li>
        <li><%= rui_link("Pricing", "/pricing", variant: :hover_underline, color: :zinc) %></li>
      </ul>
    </div>
  </div>
</footer>
```

## Combining Text Parameter with Block (Icon Slot)

You can pass text as a parameter and use the block for the icon slot:

```erb
<%= rui_link("Get Started!", "/signup", size: :lg, color: :primary) do |link| %>
  <% link.with_icon(:arrow_right, position: :trailing) %>
<% end %>
```

This pattern is useful when you want cleaner inline syntax while still adding icons.

## Custom Classes

```erb
<%= rui_link("Custom", "#", class: "my-custom-class another-class") %>

```

## Component Architecture

The Link component:
- Renders `<a>` elements by default
- Conditionally renders as `<span>` when conditions fail (if/unless/unless_current)
- Wraps in `<form>` for non-GET HTTP methods
- Inherits color context when used in slots (standalone: false)
- Supports dark mode automatically
- WCAG AA accessible with proper ARIA attributes

## Tips

1. **Use `unless_current: true` for navigation** to automatically highlight the current page
2. **Prefer `:hover_underline` variant** (default) for better UX - users expect hover feedback
3. **Use `external: true`** for external links to add security attributes automatically
4. **Consider `rui_button_to` for actions** (DELETE/POST) instead of links with methods
5. **Icons inherit link color** automatically when used in slots
6. **Loading state** is useful for async actions or when navigating to slow pages
7. **Enable `turbo_prefetch: true` for navigation** to make page loads feel instant
8. **Use `active: true` with `current_page?`** for dynamic navigation highlighting
9. **Truncate long titles** with `truncate: 50` - automatically adds tooltip with full text
10. **Add `rel: "sponsored"` for affiliate links** to comply with SEO best practices
11. **Use `scroll: :smooth` for anchor links** to create smooth scrolling effects
12. **Set `referrerpolicy` for external links** when privacy is a concern

---

## Live Search (`rui_live_search`)

# LiveSearch Component

Live search input that queries server as you type (debounced). Results update via Turbo Frame, proving Rails can do what React does, but simpler.

---

## Table of Contents

- [Basic Usage](#basic-usage)
- [Parameters Reference](#parameters-reference)
- [Required Parameters](#required-parameters)
- [Size Options](#size-options)
- [Shape Options](#shape-options)
- [Placeholder](#placeholder)
- [Debounce](#debounce)
- [Minimum Length](#minimum-length)
- [Parameter Name](#parameter-name)
- [Clear Button](#clear-button)
- [Loading Indicator](#loading-indicator)
- [Autofocus](#autofocus)
- [Disabled State](#disabled-state)
- [Search Button](#search-button)
- [Keyboard Shortcut](#keyboard-shortcut)
- [Voice Search](#voice-search)
- [Scope/Category Dropdown](#scopecategory-dropdown)
- [Recent Searches](#recent-searches)
- [Modal Mode](#modal-mode)
- [Modal Branding](#modal-branding)
- [Keyboard Navigation](#keyboard-navigation)
- [Slots](#slots)
- [Custom Styling](#custom-styling)
- [Controller Setup](#controller-setup)
- [Stimulus Controller Reference](#stimulus-controller-reference)
- [Accessibility](#accessibility)
- [All Features Combined](#all-features-combined)

---

## Basic Usage

```erb
<%= rui_live_search url: search_posts_path, turbo_frame: "search_results" %>

<turbo-frame id="search_results">
  <%= render @posts %>
</turbo-frame>
```

---

## Parameters Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | String | **required** | Search endpoint URL |
| `turbo_frame` | String | **required** | Target Turbo Frame ID for results |
| `placeholder` | String | nil | Placeholder text for the input |
| `debounce` | Integer | 300 | Debounce delay in milliseconds |
| `min_length` | Integer | 1 | Minimum characters before search triggers |
| `param_name` | Symbol | :q | Query parameter name |
| `size` | Symbol | :base | Size variant (:sm, :base, :lg) |
| `shape` | Symbol | :rounded | Shape variant (:square, :rounded, :pill) |
| `clear_button` | Boolean | false | Show clear button when input has value |
| `loading_indicator` | Boolean | false | Show loading spinner during request |
| `autofocus` | Boolean | false | Focus input on page load |
| `disabled` | Boolean | false | Disable the search input |
| `search_button` | Boolean | false | Show search submit button |
| `search_button_text` | String | "Search" | Text for search button |
| `shortcut` | String | nil | Global keyboard shortcut key (e.g., "k" for ⌘K/Ctrl+K) |
| `shortcut_hint` | Boolean | true (when shortcut set) | Show shortcut hint badge inside input |
| `voice_search` | Boolean | false | Show voice search microphone button |
| `scope` | Array | [] | Array of {value:, label:} hashes for scope dropdown |
| `scope_param` | Symbol | :scope | Query parameter name for scope |
| `scope_default` | String | nil | Default selected scope value |
| `recent_searches` | Boolean | false | Enable recent searches dropdown |
| `recent_searches_limit` | Integer | 5 | Max recent searches to store |
| `recent_searches_key` | String | 'rui_recent_searches' | LocalStorage key for recent searches |
| `modal` | Boolean | false | Enable modal mode - search opens in dialog |
| `modal_size` | Symbol | :lg | Modal dialog size (:sm, :md, :lg, :xl) |
| `show_branding` | Boolean | true | Show "Search by RapidRailsUI" branding in modal footer |
| `brand_name` | String | "RapidRailsUI" | Brand name to display in footer |
| `brand_logo` | String | nil | Path to brand logo image (defaults to gem's built-in logo) |
| `name` | String | nil | HTML name attribute (defaults to param_name) |
| `id` | String | nil | HTML id attribute for the input |
| `aria_label` | String | nil | Accessible label for screen readers |

---

## Required Parameters

### `url` (required)

The search endpoint URL that receives GET requests with the search query.

```erb
<%# Using a named route %>
<%= rui_live_search url: search_posts_path, turbo_frame: "results" %>

<%# Using a string path %>
<%= rui_live_search url: "/api/search", turbo_frame: "results" %>

<%# Using a route with parameters %>
<%= rui_live_search url: search_posts_path(category: "tech"), turbo_frame: "results" %>
```

### `turbo_frame` (required)

The ID of the Turbo Frame that will receive the search results.

```erb
<%= rui_live_search url: search_path, turbo_frame: "search_results" %>

<%# The Turbo Frame must exist on the page %>
<turbo-frame id="search_results">
  <%= render @results %>
</turbo-frame>
```

---

## Size Options

Three sizes available: `:sm`, `:base` (default), `:lg`

| Size | Height | Use Case |
|------|--------|----------|
| `:sm` | h-8 (32px) | Compact layouts, inline search, sidebars |
| `:base` | h-10 (40px) | Default, most use cases |
| `:lg` | h-11 (44px) | Prominent search, hero sections, landing pages |

```erb
<%# Small - compact search %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      size: :sm,
      placeholder: "Quick search..." %>

<%# Base (default) - standard search %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      size: :base,
      placeholder: "Search..." %>

<%# Large - prominent search %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      size: :lg,
      placeholder: "What are you looking for?" %>
```

---

## Shape Options

Three shapes available: `:square`, `:rounded` (default), `:pill`

| Shape | Border Radius | Use Case |
|-------|---------------|----------|
| `:square` | 0 | Sharp corners, minimal design |
| `:rounded` | rounded-lg | Default, balanced look |
| `:pill` | rounded-full | Soft, modern look |

```erb
<%# Square - sharp corners %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      shape: :square %>

<%# Rounded (default) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      shape: :rounded %>

<%# Pill - fully rounded %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      shape: :pill %>
```

**Combined with size:**

```erb
<%# Large pill-shaped search %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      size: :lg,
      shape: :pill,
      placeholder: "Search everything..." %>
```

---

## Placeholder

Custom placeholder text displayed when input is empty.

```erb
<%# Default (no placeholder) %>
<%= rui_live_search url: search_path, turbo_frame: "results" %>

<%# Custom placeholder %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      placeholder: "Search posts, users, tags..." %>

<%# Contextual placeholder %>
<%= rui_live_search url: search_products_path,
      turbo_frame: "products",
      placeholder: "Search by name, SKU, or category" %>
```

---

## Debounce

Delay (in milliseconds) before search triggers after user stops typing. Prevents excessive server requests.

```erb
<%# Default: 300ms %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      debounce: 300 %>

<%# Fast response: 150ms %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      debounce: 150 %>

<%# Slower for expensive queries: 500ms %>
<%= rui_live_search url: heavy_search_path,
      turbo_frame: "results",
      debounce: 500 %>

<%# Instant (no debounce): 0ms %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      debounce: 0 %>
```

---

## Minimum Length

Minimum characters required before search triggers. Useful to prevent searches on single characters.

```erb
<%# Default: 1 character %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      min_length: 1 %>

<%# Require at least 2 characters %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      min_length: 2 %>

<%# Require at least 3 characters (for large datasets) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      min_length: 3,
      placeholder: "Enter 3+ characters to search..." %>
```

---

## Parameter Name

The query parameter name sent to the server. Default is `:q`.

```erb
<%# Default: params[:q] %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      param_name: :q %>
<%# Server receives: /search?q=hello %>

<%# Custom: params[:query] %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      param_name: :query %>
<%# Server receives: /search?query=hello %>

<%# Custom: params[:search_term] %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      param_name: :search_term %>
<%# Server receives: /search?search_term=hello %>
```

---

## Clear Button

Show an X button to clear the search input. Appears only when input has a value.

```erb
<%# Without clear button (default) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      clear_button: false %>

<%# With clear button %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      clear_button: true %>
```

**Behavior:**
- Hidden when input is empty
- Shown when input has value
- Click to clear input and reset results
- Keyboard: Escape key also clears input

---

## Loading Indicator

Show a spinning loader while search request is in progress.

```erb
<%# Without loading indicator (default) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      loading_indicator: false %>

<%# With loading indicator %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      loading_indicator: true %>

<%# Combined with clear button %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      clear_button: true,
      loading_indicator: true %>
```

**Behavior:**
- Hidden by default
- Shows when search request starts
- Hides when Turbo Frame loads
- Temporarily hides clear button while loading

---

## Autofocus

Automatically focus the search input when page loads.

```erb
<%# Without autofocus (default) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      autofocus: false %>

<%# With autofocus %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      autofocus: true %>
```

**Use cases:**
- Search-focused pages where search is the primary action
- Modal search dialogs
- Landing pages with prominent search

---

## Disabled State

Disable the search input to prevent user interaction.

```erb
<%# Enabled (default) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      disabled: false %>

<%# Disabled %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      disabled: true %>

<%# Conditionally disabled %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      disabled: !current_user.can_search? %>
```

**When disabled:**
- Input cannot be focused or edited
- Search will not trigger
- Clear button will not respond
- Visual styling shows disabled state (opacity)
- Keyboard shortcuts are ignored

---

## Search Button

Add a submit button attached to the right of the input.

```erb
<%# Without search button (default) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      search_button: false %>

<%# With search button (default text "Search") %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      search_button: true %>

<%# With custom button text %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      search_button: true,
      search_button_text: "Find" %>

<%# With custom button text - Go %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      search_button: true,
      search_button_text: "Go" %>

<%# With icon-like text %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      search_button: true,
      search_button_text: "→" %>
```

**Behavior:**
- Button inherits component's shape (rounded, pill, square)
- Clicking submits the search immediately (bypasses debounce)
- Disabled when component is disabled

---

## Keyboard Shortcut

Enable global keyboard shortcut to focus/open search.

```erb
<%# No shortcut (default) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      shortcut: nil %>

<%# ⌘K / Ctrl+K shortcut %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      shortcut: "k" %>

<%# ⌘/ / Ctrl+/ shortcut %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      shortcut: "/" %>

<%# With shortcut hint hidden %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      shortcut: "k",
      shortcut_hint: false %>
```

**Behavior:**
- **Inline mode:** Shortcut focuses and selects input text
- **Modal mode:** Shortcut opens the modal dialog
- Hint badge shows ⌘K (Mac) or Ctrl+K (Windows/Linux)
- Hint hides when user starts typing
- Works from anywhere on the page

**Note:** Shortcut only works in modal mode to avoid conflicts with multiple inline searches.

---

## Voice Search

Enable microphone button for voice-to-text search using Web Speech API.

```erb
<%# Without voice search (default) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      voice_search: false %>

<%# With voice search %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      voice_search: true %>

<%# Combined with other features %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      voice_search: true,
      clear_button: true,
      loading_indicator: true %>
```

**How it works:**
1. Click microphone button to start voice recognition
2. Button shows red pulse animation while listening
3. Spoken text automatically fills the input
4. Search triggers when voice recognition ends

**Browser support:**
- Chrome, Edge, Safari (desktop and mobile)
- Firefox requires flag (`media.webspeech.recognition.enable`)
- Graceful fallback if unsupported

**Events:**
- `live-search:voice-started` - Recognition started
- `live-search:voice-ended` - Recognition ended
- `live-search:voice-unsupported` - Browser doesn't support Speech API

---

## Scope/Category Dropdown

Add a filter dropdown before the search input to search within categories.

```erb
<%# Basic scope dropdown %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      scope: [
        { value: "all", label: "All" },
        { value: "posts", label: "Posts" },
        { value: "users", label: "Users" }
      ] %>

<%# With default selection %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      scope: [
        { value: "all", label: "All" },
        { value: "posts", label: "Posts" },
        { value: "users", label: "Users" },
        { value: "comments", label: "Comments" }
      ],
      scope_default: "posts" %>

<%# With custom parameter name %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      scope: [
        { value: "all", label: "All Categories" },
        { value: "tech", label: "Technology" },
        { value: "design", label: "Design" },
        { value: "business", label: "Business" }
      ],
      scope_param: :category,
      scope_default: "all" %>
```

**Server receives:** `/search?q=hello&category=tech`

**Controller example:**

```ruby
def index
  @results = case params[:category]
             when "posts" then Post.search(params[:q])
             when "users" then User.search(params[:q])
             when "comments" then Comment.search(params[:q])
             else search_all(params[:q])
             end
end
```

**Behavior:**
- Changing scope immediately triggers new search
- Scope inherits component's shape styling

---

## Recent Searches

Enable dropdown showing recent search history stored in browser's LocalStorage.

```erb
<%# Without recent searches (default) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      recent_searches: false %>

<%# With recent searches (default limit: 5) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      recent_searches: true %>

<%# With custom limit %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      recent_searches: true,
      recent_searches_limit: 10 %>

<%# With custom storage key %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      recent_searches: true,
      recent_searches_key: "my_app_searches" %>

<%# Full configuration %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      recent_searches: true,
      recent_searches_limit: 8,
      recent_searches_key: "blog_searches" %>
```

**How it works:**
1. Open modal (or focus empty inline input) → recent searches dropdown appears
2. Click a recent search → fills input and triggers search
3. New searches automatically saved on form submit
4. "Clear recent searches" button removes all history

**Multiple search boxes with separate histories:**

```erb
<%# Global search %>
<%= rui_live_search url: search_path,
      turbo_frame: "global_results",
      recent_searches: true,
      recent_searches_key: "global_searches" %>

<%# Product search %>
<%= rui_live_search url: products_search_path,
      turbo_frame: "product_results",
      recent_searches: true,
      recent_searches_key: "product_searches" %>

<%# User search %>
<%= rui_live_search url: users_search_path,
      turbo_frame: "user_results",
      recent_searches: true,
      recent_searches_key: "user_searches" %>
```

**Events:**
- `live-search:recent-selected` - Recent search item clicked
- `live-search:recent-cleared` - History cleared

---

## Modal Mode

Enable modal mode to show search in a centered dialog (command palette / spotlight search UX).

```erb
<%# Without modal (default - inline mode) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: false %>

<%# With modal %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true %>

<%# Modal with keyboard shortcut %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      shortcut: "k" %>

<%# Modal with custom size %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      modal_size: :xl %>
```

**Modal sizes:**

| Size | Width | Use Case |
|------|-------|----------|
| `:sm` | max-w-md | Compact modal |
| `:md` | max-w-lg | Medium modal |
| `:lg` | max-w-2xl | Default, most use cases |
| `:xl` | max-w-4xl | Large results display |

```erb
<%# Small modal %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      modal_size: :sm %>

<%# Large modal %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      modal_size: :lg %>

<%# Extra large modal %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      modal_size: :xl %>
```

**How it works:**
1. Trigger button appears showing "Search..." and shortcut hint
2. Click button or press ⌘K to open modal
3. Input is auto-focused when modal opens
4. If recent searches exist and input is empty → recent searches shown
5. As user types → recent hides, results show
6. Press Escape or click backdrop to close

**Full modal example:**

```erb
<%= rui_live_search url: docs_search_path,
      turbo_frame: "docs_results",
      modal: true,
      modal_size: :lg,
      shortcut: "k",
      placeholder: "Search documentation...",
      debounce: 150,
      min_length: 2,
      clear_button: true,
      loading_indicator: true,
      recent_searches: true,
      recent_searches_limit: 5,
      aria_label: "Search documentation" %>
```

---

## Modal Branding

In modal mode, "Search by LOGO RapidRailsUI" branding appears in the footer.

```erb
<%# Default branding (shows RapidRailsUI) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true %>

<%# Custom brand name %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      brand_name: "MyApp" %>

<%# Custom brand logo %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      brand_logo: "myapp/logo.png" %>

<%# Custom brand name and logo %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      brand_name: "Acme Search",
      brand_logo: "acme/search-logo.svg" %>

<%# Hide branding completely %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      show_branding: false %>
```

**Note:** Branding only appears in modal mode. Inline mode never shows branding.

---

## Keyboard Navigation

Full keyboard navigation support for both recent searches and search results.

**Navigation keys:**
| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate through items |
| `Enter` | Select highlighted item |
| `Escape` | Clear input (inline) or close modal |
| `⌘K` / `Ctrl+K` | Open modal (when shortcut configured) |

**Navigation behavior:**
- **Input empty + recent searches visible:** Arrow keys navigate recent items
- **Input has value + results visible:** Arrow keys navigate search results
- **Enter:** Selects highlighted item (triggers click)
- Highlighted items scroll into view automatically

**Example with full keyboard support:**

```erb
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      shortcut: "k",
      recent_searches: true,
      clear_button: true %>
```

---

## Slots

### Empty State Slot

Render custom content when no results are found.

```erb
<%# Basic empty state %>
<%= rui_live_search url: search_path, turbo_frame: "results" do |search| %>
  <% search.with_empty_state do %>
    <p class="text-zinc-500 text-center py-4">No results found</p>
  <% end %>
<% end %>

<%# Detailed empty state %>
<%= rui_live_search url: search_path, turbo_frame: "results" do |search| %>
  <% search.with_empty_state do %>
    <div class="text-center py-8">
      <svg class="mx-auto h-12 w-12 text-zinc-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
      </svg>
      <h3 class="mt-2 text-sm font-medium text-zinc-900 dark:text-zinc-100">No results found</h3>
      <p class="mt-1 text-sm text-zinc-500">Try adjusting your search or filter to find what you're looking for.</p>
    </div>
  <% end %>
<% end %>
```

### Trigger Slot (Modal Mode)

Customize the modal trigger button content.

```erb
<%# Default trigger (shows "Search..." with shortcut hint) %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      shortcut: "k" %>

<%# Custom trigger %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true,
      shortcut: "k" do |search| %>
  <% search.with_trigger do %>
    <div class="flex items-center gap-2 px-4 py-2 bg-zinc-100 dark:bg-zinc-800 rounded-lg">
      <%= rui_icon :search, size: :sm, class: "text-zinc-400" %>
      <span class="text-zinc-500">Search documentation...</span>
      <kbd class="ml-auto text-xs font-mono text-zinc-400 bg-white dark:bg-zinc-700 px-1.5 py-0.5 rounded border border-zinc-200 dark:border-zinc-600">⌘K</kbd>
    </div>
  <% end %>
<% end %>

<%# Minimal trigger %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      modal: true do |search| %>
  <% search.with_trigger do %>
    <%= rui_icon :search, size: :base, class: "text-zinc-500 hover:text-zinc-700" %>
  <% end %>
<% end %>
```

---

## Custom Styling

Add custom CSS classes to the component wrapper.

```erb
<%# Custom width %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      class: "max-w-md" %>

<%# Centered %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      class: "max-w-lg mx-auto" %>

<%# Full width %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      class: "w-full" %>

<%# With margin %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      class: "max-w-xl mx-auto my-8" %>
```

**HTML attributes:**

```erb
<%# Custom ID %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      id: "main-search" %>

<%# Custom name %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      name: "search_query" %>

<%# ARIA label for accessibility %>
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      aria_label: "Search blog posts" %>
```

---

## Controller Setup

The search endpoint should respond to GET requests and render results in a Turbo Frame.

**Basic controller:**

```ruby
# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def index
    @posts = Post.all

if params[:q].present?
      @posts = @posts.where("title ILIKE ?", "%#{params[:q]}%")
    end

# Turbo automatically excludes layout for frame requests
  end
end
```

**With scope/category:**

```ruby
# app/controllers/search_controller.rb
class SearchController < ApplicationController
  def index
    query = params[:q]

@results = case params[:scope]
               when "posts"
                 Post.search(query)
               when "users"
                 User.search(query)
               when "comments"
                 Comment.search(query)
               else
                 search_all(query)
               end
  end

private

def search_all(query)
    {
      posts: Post.search(query).limit(5),
      users: User.search(query).limit(5),
      comments: Comment.search(query).limit(5)
    }
  end
end
```

**View with Turbo Frame:**

```erb
<%# app/views/posts/index.html.erb %>

<%= rui_live_search url: posts_path,
      turbo_frame: "posts_list",
      placeholder: "Search posts...",
      clear_button: true,
      loading_indicator: true %>

<turbo-frame id="posts_list">
  <% if @posts.any? %>
    <% @posts.each do |post| %>
      <%= render post %>
    <% end %>
  <% else %>
    <p class="text-zinc-500 text-center py-4">No posts found</p>
  <% end %>
</turbo-frame>
```

---

## Stimulus Controller Reference

The component uses `live-search` Stimulus controller.

### Targets

| Target | Description |
|--------|-------------|
| `form` | The form element |
| `input` | The search input |
| `clearButton` | Clear button (X) |
| `loadingIndicator` | Loading spinner |
| `searchButton` | Submit button |
| `shortcutHint` | Shortcut badge container |
| `shortcutText` | Shortcut text element |
| `emptyState` | Empty state slot container |
| `voiceButton` | Voice search button |
| `scopeSelect` | Scope dropdown |
| `recentDropdown` | Recent searches dropdown |
| `recentList` | Recent searches list |
| `recentClear` | Clear recent button |
| `dialog` | Modal dialog element |
| `modalTrigger` | Modal trigger button |
| `resultsContainer` | Results container (modal) |
| `modalEmptyState` | Modal empty state |

### Values

| Value | Type | Default | Description |
|-------|------|---------|-------------|
| `debounce` | Number | 300 | Debounce delay in ms |
| `minLength` | Number | 1 | Min characters to trigger |
| `disabled` | Boolean | false | Disabled state |
| `shortcut` | String | "" | Keyboard shortcut key |
| `recentSearches` | Boolean | false | Enable recent searches |
| `recentLimit` | Number | 5 | Max recent searches |
| `recentKey` | String | "rui_recent_searches" | LocalStorage key |
| `modal` | Boolean | false | Enable modal mode |

### Events

| Event | Description |
|-------|-------------|
| `live-search:before-search` | Before form submits (cancelable) |
| `live-search:after-search` | After form submitted |
| `live-search:cleared` | After input cleared |
| `live-search:voice-started` | Voice recognition started |
| `live-search:voice-ended` | Voice recognition ended |
| `live-search:voice-unsupported` | Browser doesn't support Speech API |
| `live-search:recent-selected` | Recent search item clicked |
| `live-search:recent-cleared` | History cleared |
| `live-search:modal-opened` | Modal opened |
| `live-search:modal-closed` | Modal closed |
| `live-search:shortcut-triggered` | Keyboard shortcut pressed |

**Listening to events:**

```javascript
// Listen for search events
document.addEventListener("live-search:before-search", (event) => {
  console.log("Searching for:", event.detail.query)
})

document.addEventListener("live-search:after-search", (event) => {
  console.log("Search completed:", event.detail.query)
})

// Cancel a search
document.addEventListener("live-search:before-search", (event) => {
  if (event.detail.query.length < 3) {
    event.preventDefault() // Cancels the search
  }
})
```

---

## Accessibility

The component follows WAI-ARIA best practices.

### ARIA Attributes

- `role="search"` - Landmark for screen reader navigation (inline mode)
- `aria-label` - Custom accessible name
- `aria-controls` - Points to the target Turbo Frame
- `aria-autocomplete="list"` - Indicates search suggests results
- `aria-live="polite"` - Announces loading state and results

### Semantic HTML

- Uses native `<input type="search">`
- Form uses GET method for bookmarkable URLs
- Native `<dialog>` element for modal

### Keyboard Support

- Full keyboard navigation (arrows, enter, escape)
- Focus trapping in modal mode
- Escape closes modal or clears input

### Recommended Results Markup

```erb
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      aria_label: "Search posts" %>

<turbo-frame id="results"
             role="region"
             aria-label="Search results"
             aria-live="polite">
  <%= render @results %>
</turbo-frame>
```

---

## All Features Combined

```erb
<%= rui_live_search url: search_path,
      turbo_frame: "results",
      placeholder: "Search everything...",
      debounce: 200,
      min_length: 2,
      param_name: :q,
      size: :lg,
      shape: :rounded,
      clear_button: true,
      loading_indicator: true,
      autofocus: false,
      disabled: false,
      search_button: false,
      shortcut: "k",
      shortcut_hint: true,
      voice_search: true,
      scope: [
        { value: "all", label: "All" },
        { value: "posts", label: "Posts" },
        { value: "users", label: "Users" },
        { value: "comments", label: "Comments" }
      ],
      scope_param: :category,
      scope_default: "all",
      recent_searches: true,
      recent_searches_limit: 8,
      recent_searches_key: "app_searches",
      modal: true,
      modal_size: :lg,
      show_branding: true,
      brand_name: "RapidRailsUI",
      brand_logo: nil,
      id: "main-search",
      aria_label: "Search" do |search| %>
  <% search.with_empty_state do %>
    <div class="text-center py-8">
      <p class="text-zinc-500">No results found</p>
      <p class="text-sm text-zinc-400 mt-1">Try different keywords</p>
    </div>
  <% end %>
  <% search.with_trigger do %>
    <div class="flex items-center gap-2 px-3 py-2 bg-zinc-100 dark:bg-zinc-800 rounded-lg hover:bg-zinc-200 dark:hover:bg-zinc-700 transition-colors">
      <%= rui_icon :search, size: :sm, class: "text-zinc-400" %>
      <span class="text-zinc-500">Search...</span>
      <kbd class="ml-2 text-xs font-mono text-zinc-400">⌘K</kbd>
    </div>
  <% end %>
<% end %>

<turbo-frame id="results" role="region" aria-label="Search results" aria-live="polite">
  <%= render @results %>
</turbo-frame>
```

---

## Pagination (`rui_pagination`)

# Pagination Component

A flexible pagination component with built-in controller integration via `rui_paginate`, plus standalone usage.

## Basic Usage

The simplest way to use pagination is with `rui_paginate` in your controller:

```erb
<%# Controller: @pagy, @posts = rui_paginate(Post.all) %>
<%= rui_pagination(pagy: @pagy) %>
```

## Standalone Usage

For custom pagination without a controller:

```erb
<%= rui_pagination(
  current_page: 5,
  total_pages: 20,
  total_count: 200,
  base_url: posts_path
) %>
```

> **Note:** Do not mix `pagy:` with manual params (`current_page:`, `total_pages:`, `total_count:`). When both are present, `pagy:` always wins and a dev/test warning is emitted. Use one or the other.

## Variants

### Simple (Previous/Next Only)

Minimal pagination with just previous and next buttons:

```erb
<%= rui_pagination(pagy: @pagy, variant: :simple) %>
```

### Numbered (Default)

Shows page numbers with previous/next:

```erb
<%= rui_pagination(pagy: @pagy, variant: :numbered) %>
```

### Full (First/Last Included)

Complete navigation with first, previous, pages, next, and last:

```erb
<%= rui_pagination(pagy: @pagy, variant: :full) %>
```

### Compact (Minimal)

Minimal "Page X of Y" display with prev/next buttons:

```erb
<%= rui_pagination(pagy: @pagy, variant: :compact) %>
```

## Icon-Only Mode

Hide button text, show only chevron icons:

```erb
<%= rui_pagination(pagy: @pagy, icon_only: true) %>
<%= rui_pagination(pagy: @pagy, variant: :simple, icon_only: true) %>
```

## Alignment

Control horizontal alignment of pagination:

```erb
<%= rui_pagination(pagy: @pagy, align: :left) %>
<%= rui_pagination(pagy: @pagy, align: :center) %>
<%= rui_pagination(pagy: @pagy, align: :right) %>
<%= rui_pagination(pagy: @pagy, align: :between) %> <%# Default %>
```

## Page Jumper

Add go-to-page input field:

```erb
<%= rui_pagination(pagy: @pagy, show_jumper: true) %>

<%# Compact with jumper - minimal but powerful %>
<%= rui_pagination(pagy: @pagy, variant: :compact, show_jumper: true) %>
```

## With Turbo Frame (AJAX Pagination)

Enable AJAX pagination with Turbo Frame:

```erb
<%= turbo_frame_tag "posts" do %>
  <div class="space-y-4">
    <%= render @posts %>
  </div>

<%= rui_pagination(
    pagy: @pagy,
    turbo_frame: "posts"
  ) %>
<% end %>
```

## With Per-Page Selector

Allow users to choose how many items per page:

```erb
<%= rui_pagination(
  pagy: @pagy,
  show_per_page: true,
  per_page_options: [10, 25, 50, 100]
) %>
```

```ruby
# Controller
def index
  items = params[:per_page]&.to_i || 25
  @pagy, @posts = rui_paginate(Post.all, limit: items)
end
```

## Without Info Text

Hide the "Showing X-Y of Z" info:

```erb
<%= rui_pagination(pagy: @pagy, show_info: false) %>
```

## Sizes

```erb
<%= rui_pagination(pagy: @pagy, size: :xs) %>
<%= rui_pagination(pagy: @pagy, size: :sm) %>
<%= rui_pagination(pagy: @pagy, size: :base) %> <%# Default %>
<%= rui_pagination(pagy: @pagy, size: :lg) %>
<%= rui_pagination(pagy: @pagy, size: :xl) %>
```

## Shapes

```erb
<%= rui_pagination(pagy: @pagy, shape: :rounded) %> <%# Default %>
<%= rui_pagination(pagy: @pagy, shape: :square) %>
<%= rui_pagination(pagy: @pagy, shape: :pill) %>
```

## Colors

The active page button can be styled with any color:

```erb
<%= rui_pagination(pagy: @pagy, color: :primary) %> <%# Default %>
<%= rui_pagination(pagy: @pagy, color: :blue) %>
<%= rui_pagination(pagy: @pagy, color: :emerald) %>
<%= rui_pagination(pagy: @pagy, color: :purple) %>
```

## Custom Window Sizes

Control how many page links appear:

```erb
<%# Show 3 pages on each side of current %>
<%= rui_pagination(pagy: @pagy, window: 3) %>

<%# Show 2 pages at edges (first/last) %>
<%= rui_pagination(pagy: @pagy, outer_window: 2) %>
```

## Custom Button Text

Customize navigation button labels:

```erb
<%= rui_pagination(
  pagy: @pagy,
  prev_text: "← Back",
  next_text: "Forward →",
  first_text: "Start",
  last_text: "End"
) %>
```

## In Table Component

Pagination integrates directly with the Table component:

```erb
<%= rui_table(pagy: @pagy, turbo_frame: "users") do |table| %>
  <% table.with_column(key: :name, label: "Name") %>
  <% table.with_column(key: :email, label: "Email") %>

<% @users.each do |user| %>
    <% table.with_row(id: user.id) do |row| %>
      <% row.with_cell { user.name } %>
      <% row.with_cell { user.email } %>
    <% end %>
  <% end %>
<% end %>
```

## Complete Example

Full-featured pagination with all options:

```erb
<%= rui_pagination(
  pagy: @pagy,
  variant: :full,
  size: :base,
  shape: :rounded,
  color: :primary,
  turbo_frame: "content",
  show_info: true,
  show_per_page: true,
  per_page_options: [10, 25, 50, 100],
  window: 2,
  outer_window: 1
) %>
```

## Props Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `pagy` | PageInfo | nil | PageInfo from rui_paginate for automatic configuration |
| `current_page` | Integer | 1 | Current page (standalone mode) |
| `total_pages` | Integer | 1 | Total pages (standalone mode) |
| `total_count` | Integer | nil | Total items (for info display) |
| `variant` | Symbol | :numbered | Display variant (:simple, :numbered, :full, :compact) |
| `size` | Symbol | :base | Size variant (:xs, :sm, :base, :lg, :xl) |
| `shape` | Symbol | :rounded | Button shape (:rounded, :square, :pill) |
| `color` | Symbol | :primary | Active page color |
| `align` | Symbol | :between | Alignment (:left, :center, :right, :between) |
| `icon_only` | Boolean | false | Show only icons on prev/next buttons |
| `show_jumper` | Boolean | false | Show go-to-page input field |
| `base_url` | String | nil | Base URL for links |
| `page_param` | Symbol | :page | URL parameter name for page |
| `turbo_frame` | String | nil | Turbo Frame ID for AJAX |
| `turbo_action` | Symbol | :replace | Turbo action (:replace, :advance) |
| `show_info` | Boolean | true | Show "Showing X-Y of Z" |
| `show_per_page` | Boolean | false | Show per-page selector |
| `per_page_options` | Array | [10,25,50,100] | Per-page dropdown options |
| `items_per_page` | Integer | nil | Current items per page |
| `window` | Integer | 2 | Pages around current |
| `outer_window` | Integer | 1 | Pages at edges |
| `prev_text` | String | "Previous" | Previous button text |
| `next_text` | String | "Next" | Next button text |
| `first_text` | String | "First" | First button text |
| `last_text` | String | "Last" | Last button text |

## Accessibility

- Uses semantic `<nav>` element with `role="navigation"`
- `aria-label` on navigation container
- `aria-current="page"` on current page
- `aria-disabled="true"` on disabled buttons
- `aria-label` on navigation buttons
- Screen reader text for icon-only buttons
- Keyboard navigable links

## Responsive Behavior

On mobile devices:
- Page numbers are hidden
- Shows "Page X of Y" text instead
- Previous/Next buttons remain visible
- Info text wraps appropriately

---

## Popover (`rui_popover`)

# Popover Component

Popovers display rich, interactive content on hover or click. Unlike tooltips (text-only),
popovers support complex layouts with headers, bodies, footers, and interactive elements
like buttons and links. Perfect for user cards, previews, and contextual information panels.

## Basic Usage

```erb
<%= rui_popover do |p| %>
  <% p.with_trigger do %>
    <span>Hover over me</span>
  <% end %>
  <% p.with_body do %>
    <p>This is the popover content.</p>
  <% end %>
<% end %>
```

## Structured Content (Header, Body, Footer)

Use structured slots for consistent layouts.

```erb
<%= rui_popover do |p| %>
  <% p.with_trigger do %>
    <%= link_to "@username", "#" %>
  <% end %>
  <% p.with_header do %>
    <div class="flex items-center gap-3">
      <%= rui_avatar(src: user.avatar_url, size: :md) %>
      <div>
        <div class="font-semibold">Jane Doe</div>
        <div class="text-sm text-zinc-500">@janedoe</div>
      </div>
    </div>
  <% end %>
  <% p.with_body do %>
    <p class="text-sm">Software engineer passionate about Ruby and Rails.</p>
    <div class="flex gap-4 mt-2 text-sm text-zinc-500">
      <span><strong>128</strong> Following</span>
      <span><strong>1.2K</strong> Followers</span>
    </div>
  <% end %>
  <% p.with_footer do %>
    <%= rui_button("Follow", size: :sm, color: :primary, full: true) %>
  <% end %>
<% end %>
```

## Custom Content

For full control over the layout, use the custom_content slot.

```erb
<%= rui_popover(width: :lg) do |p| %>
  <% p.with_trigger do %>
    <span>Hover me</span>
  <% end %>
  <% p.with_custom_content do %>
    <div class="grid grid-cols-2 gap-4 p-4">
      <div class="space-y-2">
        <h4 class="font-semibold">Column 1</h4>
        <p class="text-sm">Custom layout content</p>
      </div>
      <div class="space-y-2">
        <h4 class="font-semibold">Column 2</h4>
        <p class="text-sm">More custom content</p>
      </div>
    </div>
  <% end %>
<% end %>
```

## Position

Popovers can appear on any side of the trigger element.

```erb
<%# Bottom (default) %>
<%= rui_popover(position: :bottom) do |p| %>
  <% p.with_trigger do %>Hover me<% end %>
  <% p.with_body do %>Bottom popover<% end %>
<% end %>

<%# Top %>
<%= rui_popover(position: :top) do |p| %>
  <% p.with_trigger do %>Hover me<% end %>
  <% p.with_body do %>Top popover<% end %>
<% end %>

<%# Right %>
<%= rui_popover(position: :right) do |p| %>
  <% p.with_trigger do %>Hover me<% end %>
  <% p.with_body do %>Right popover<% end %>
<% end %>

<%# Left %>
<%= rui_popover(position: :left) do |p| %>
  <% p.with_trigger do %>Hover me<% end %>
  <% p.with_body do %>Left popover<% end %>
<% end %>
```

## Width Variants

Four fixed width variants are available.

```erb
<%# Small (200px) %>
<%= rui_popover(width: :sm) do |p| %>
  <% p.with_trigger do %>Small<% end %>
  <% p.with_body do %>Compact popover<% end %>
<% end %>

<%# Base (280px - default) %>
<%= rui_popover(width: :base) do |p| %>
  <% p.with_trigger do %>Base<% end %>
  <% p.with_body do %>Standard popover<% end %>
<% end %>

<%# Large (320px) %>
<%= rui_popover(width: :lg) do |p| %>
  <% p.with_trigger do %>Large<% end %>
  <% p.with_body do %>Wider popover<% end %>
<% end %>

<%# Extra Large (400px) %>
<%= rui_popover(width: :xl) do |p| %>
  <% p.with_trigger do %>XL<% end %>
  <% p.with_body do %>Extra wide popover<% end %>
<% end %>
```

## Custom Max Width

Override the width with a custom max-width value.

```erb
<%= rui_popover(max_width: "350px") do |p| %>
  <% p.with_trigger do %>Custom width<% end %>
  <% p.with_body do %>
    This popover has a custom max-width of 350px.
  <% end %>
<% end %>
```

## Colors

Popovers support multiple color schemes.

### Default and Dark

```erb
<%# Default (white background) %>
<%= rui_popover(color: :default) do |p| %>
  <% p.with_trigger do %>Default<% end %>
  <% p.with_body do %>Light popover<% end %>
<% end %>

<%# Dark %>
<%= rui_popover(color: :dark) do |p| %>
  <% p.with_trigger do %>Dark<% end %>
  <% p.with_body do %>Dark popover<% end %>
<% end %>
```

### Semantic Colors

```erb
<%= rui_popover(color: :primary) do |p| %>
  <% p.with_trigger do %>Primary<% end %>
  <% p.with_body do %>Primary popover<% end %>
<% end %>

<%= rui_popover(color: :success) do |p| %>
  <% p.with_trigger do %>Success<% end %>
  <% p.with_body do %>Success popover<% end %>
<% end %>

<%= rui_popover(color: :warning) do |p| %>
  <% p.with_trigger do %>Warning<% end %>
  <% p.with_body do %>Warning popover<% end %>
<% end %>

<%= rui_popover(color: :danger) do |p| %>
  <% p.with_trigger do %>Danger<% end %>
  <% p.with_body do %>Danger popover<% end %>
<% end %>
```

### All Tailwind Colors

Use any Tailwind color name directly.

```erb
<%= rui_popover(color: :blue) do |p| %>
  <% p.with_trigger do %>Blue<% end %>
  <% p.with_body do %>Blue popover<% end %>
<% end %>

<%= rui_popover(color: :purple) do |p| %>
  <% p.with_trigger do %>Purple<% end %>
  <% p.with_body do %>Purple popover<% end %>
<% end %>
```

## Arrow

Popovers can optionally show an arrow pointing to the trigger (disabled by default).

```erb
<%# Without arrow (default) %>
<%= rui_popover do |p| %>
  <% p.with_trigger do %>No arrow<% end %>
  <% p.with_body do %>Popover content<% end %>
<% end %>

<%# With arrow %>
<%= rui_popover(arrow: true) do |p| %>
  <% p.with_trigger do %>With arrow<% end %>
  <% p.with_body do %>Popover content<% end %>
<% end %>
```

## Trigger Mode

Popovers can be triggered by hover (default) or click.

```erb
<%# Hover (default) %>
<%= rui_popover(trigger: :hover) do |p| %>
  <% p.with_trigger do %>Hover me<% end %>
  <% p.with_body do %>Appears on hover<% end %>
<% end %>

<%# Click %>
<%= rui_popover(trigger: :click) do |p| %>
  <% p.with_trigger do %>Click me<% end %>
  <% p.with_body do %>
    Click outside or press Escape to close.
  <% end %>
<% end %>
```

## Show Delay

Add a delay before the popover appears (in milliseconds).

```erb
<%= rui_popover(delay: 300) do |p| %>
  <% p.with_trigger do %>Wait 300ms...<% end %>
  <% p.with_body do %>Delayed popover<% end %>
<% end %>
```

## Hide Delay

Add a delay before the popover disappears (in milliseconds). Essential for popovers
since users need time to move their cursor into the popover to interact with it.

```erb
<%# Default hide delay (100ms) %>
<%= rui_popover do |p| %>
  <% p.with_trigger do %>Default delay<% end %>
  <% p.with_body do %>Interactive content here<% end %>
<% end %>

<%# Custom hide delay %>
<%= rui_popover(hide_delay: 300) do |p| %>
  <% p.with_trigger do %>Stays longer<% end %>
  <% p.with_body do %>More time to interact<% end %>
<% end %>
```

## Hover Interaction

For hover-triggered popovers, hovering over the popover content keeps it open.
This allows users to interact with buttons, links, and other elements inside.

```erb
<%= rui_popover do |p| %>
  <% p.with_trigger do %>
    Hover over me
  <% end %>
  <% p.with_body do %>
    <p class="mb-3">This popover stays open while you hover over it.</p>
    <%= rui_button("Click me", size: :sm) %>
  <% end %>
<% end %>
```

## With Other Components

Popovers work great with other RapidRailsUI components.

```erb
<%# User profile popover %>
<%= rui_popover(width: :lg) do |p| %>
  <% p.with_trigger do %>
    <%= rui_avatar(src: user.avatar_url, size: :sm) %>
  <% end %>
  <% p.with_header do %>
    <div class="flex items-center gap-3">
      <%= rui_avatar(src: user.avatar_url, size: :lg) %>
      <div>
        <div class="font-semibold"><%= user.name %></div>
        <%= rui_badge(text: "Pro", color: :primary, size: :sm) %>
      </div>
    </div>
  <% end %>
  <% p.with_body do %>
    <p class="text-sm"><%= user.bio %></p>
  <% end %>
  <% p.with_footer do %>
    <div class="flex gap-2">
      <%= rui_button("Message", size: :sm, variant: :outline) %>
      <%= rui_button("Follow", size: :sm, color: :primary) %>
    </div>
  <% end %>
<% end %>
```

## Custom ID

Provide a custom ID if needed.

```erb
<%= rui_popover(id: "my-popover") do |p| %>
  <% p.with_trigger do %>Custom ID<% end %>
  <% p.with_body do %>Popover content<% end %>
<% end %>
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `position` | Symbol | `:bottom` | Position: `:top`, `:right`, `:bottom`, `:left` |
| `width` | Symbol | `:base` | Width: `:sm` (200px), `:base` (280px), `:lg` (320px), `:xl` (400px) |
| `max_width` | String | `nil` | Custom max-width (e.g., "350px") |
| `color` | Symbol | `:default` | Color: `:default`, `:dark`, semantic colors, or any Tailwind color |
| `arrow` | Boolean | `false` | Show arrow pointing to trigger |
| `trigger` | Symbol | `:hover` | Trigger mode: `:hover`, `:click` |
| `delay` | Integer | `200` | Show delay in milliseconds |
| `hide_delay` | Integer | `100` | Hide delay in milliseconds |
| `id` | String | auto | Custom ID for popover |

## Slots

| Slot | Required | Description |
|------|----------|-------------|
| `trigger` | Yes | The element that activates the popover |
| `header` | No | Header section (structured content) |
| `body` | No | Body section (structured content) |
| `footer` | No | Footer section with border-top (structured content) |
| `custom_content` | No | Flexible content (use instead of header/body/footer) |

## Popover vs Tooltip

| Feature | Tooltip | Popover |
|---------|---------|---------|
| Content | Text only | Rich HTML, slots |
| Width | Auto (with optional max) | Fixed variants |
| Arrow | On by default | Off by default |
| Delay defaults | 0ms show, 0ms hide | 200ms show, 100ms hide |
| Interaction | Not interactive | Stays open on hover |
| Use case | Simple hints | Cards, previews, forms |

## Accessibility

- Trigger elements have `aria-describedby` linking to the popover
- Popovers have `role="dialog"` and `aria-hidden` managed by JavaScript
- Trigger elements are focusable (`tabindex="0"`)
- Focus events show/hide popovers for keyboard users
- Click-triggered popovers can be closed with Escape key
- Click outside closes click-triggered popovers

## Dark Mode

All color variants include dark mode support. The default color scheme uses
appropriate backgrounds for both light and dark modes.

---

## Progress (`rui_progress`)

# Progress Component

A lightweight, accessible progress bar for displaying completion, usage, or status.

## Basic Usage

```erb
<%= rui_progress(75) %>
```

Value is positional and clamped to `0–100` automatically.

## With Label and Value

```erb
<%# Label only %>
<%= rui_progress(60, label: "Storage used") %>

<%# Percentage value only %>
<%= rui_progress(60, show_value: true) %>

<%# Both label and value — shown in a header row above the bar %>
<%= rui_progress(60, label: "Open tickets", show_value: true) %>
```

## Colors

Any semantic or Tailwind color is accepted:

```erb
<%= rui_progress(75, color: :primary) %>   <%# default %>
<%= rui_progress(75, color: :success) %>
<%= rui_progress(75, color: :warning) %>
<%= rui_progress(75, color: :danger) %>
<%= rui_progress(75, color: :info) %>
<%= rui_progress(75, color: :emerald) %>
<%= rui_progress(75, color: :blue) %>
<%= rui_progress(75, color: :purple) %>
<%= rui_progress(75, color: :amber) %>
```

## Sizes

Controls the track height:

```erb
<%= rui_progress(75, size: :xs) %>    <%# 4px %>
<%= rui_progress(75, size: :sm) %>    <%# 6px %>
<%= rui_progress(75, size: :base) %>  <%# 8px — default %>
<%= rui_progress(75, size: :md) %>    <%# 12px %>
<%= rui_progress(75, size: :lg) %>    <%# 16px %>
```

## Variants

```erb
<%= rui_progress(75, variant: :solid) %>  <%# Default — full opacity %>
<%= rui_progress(75, variant: :soft) %>   <%# 60% opacity — muted look %>
```

## Animated

Adds a CSS width transition (500ms ease-out) when the value changes:

```erb
<%= rui_progress(75, animated: true) %>
```

Useful when value is set via Turbo Stream updates or page load.

## Value Clamping

Values outside `0–100` are automatically clamped:

```erb
<%= rui_progress(150) %>   <%# Renders 100% %>
<%= rui_progress(-10) %>   <%# Renders 0% %>
<%= rui_progress(nil) %>   <%# Renders 0% %>
```

## Custom HTML Attributes

Pass any HTML attributes to the outer `<div>`:

```erb
<%= rui_progress(75, id: "storage-bar", class: "my-4", data: { user_id: 42 }) %>
```

Classes are merged with the component's own wrapper classes.

## In a Dashboard / Card

```erb
<div class="bg-white dark:bg-zinc-800 rounded-xl shadow-sm p-5 space-y-4">
  <div>
    <%= rui_text("Storage", size: :sm, color: :muted, inline: true) %>
    <%= rui_progress(68, label: "Storage", show_value: true, color: :primary, size: :sm) %>
  </div>
  <div>
    <%= rui_progress(42, label: "CPU", show_value: true, color: :warning, size: :sm) %>
  </div>
  <div>
    <%= rui_progress(91, label: "Memory", show_value: true, color: :danger, size: :sm) %>
  </div>
</div>
```

## Inside a Stat Card

Progress integrates directly with the Stat component:

```erb
<%= rui_stat("Retention", "95%", progress: 95, color: :emerald) %>
```

## Multiple Bars (Skills / Proficiency)

```erb
<div class="space-y-3">
  <% skills.each do |skill| %>
    <%= rui_progress(skill.score,
      label: skill.name,
      show_value: true,
      color: :primary,
      size: :sm
    ) %>
  <% end %>
</div>
```

## Accessibility

- Uses semantic `role="progressbar"` on the outer wrapper
- `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax="100"` set automatically
- `aria-label` auto-generated:
  - With label: `"Storage used: 60%"`
  - Without label: `"60% complete"`
- Zero JavaScript — pure CSS and ERB

## Props Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | Integer | `0` | Progress value (0–100, clamped) |
| `color` | Symbol | `:primary` | Bar color (semantic or Tailwind) |
| `size` | Symbol | `:base` | Track height (`:xs`, `:sm`, `:base`, `:md`, `:lg`) |
| `variant` | Symbol | `:solid` | Visual style (`:solid`, `:soft`) |
| `label` | String | `nil` | Label text shown above bar |
| `show_value` | Boolean | `false` | Show `"75%"` percentage text |
| `animated` | Boolean | `false` | CSS transition on width change |
| `**options` | Hash | — | Additional HTML attributes on outer wrapper |

---

## Radio Button (`rui_radio_button`)

# RadioButton Component Usage

Radio button groups for selecting one option from a collection.

## Features

- Multiple variants: radio, card, pill, button
- Form builder integration (`f.rui_radio_button`)
- Icon support for card/pill/button variants
- Vertical and horizontal layouts
- All semantic colors + all Tailwind colors
- Full accessibility support
- Error handling and validation
- Required field indicator

## Variants

### :radio (default)
Standard circular radio button with label.

### :card
Bordered card with full-width click target. Ideal for feature selection or plan tiers.

### :pill
Compact, tag-like rounded selections. Good for filters or categories.

### :button
Toolbar-style toggle controls (segmented buttons). Perfect for view mode switchers.

## Basic Usage

### Simple Array Collection

```erb
<%= rui_radio_button(
  object: :post,
  method: :status,
  collection: [["Draft", "draft"], ["Published", "published"]],
  label: "Post Status"
) %>
```

### ActiveRecord Enum

```erb
<%= rui_radio_button(
  object: @post,
  method: :status,
  collection: Post.statuses,
  label: "Status",
  help_text: "Choose the post visibility"
) %>
```

### ActiveRecord Collection

```erb
<%= rui_radio_button(
  object: @subscription,
  method: :plan_id,
  collection: Plan.all,
  value_method: :id,
  text_method: :name,
  label: "Choose Plan"
) %>
```

## Rails-Compatible API

`rui_radio_button` also accepts standard Rails positional argument patterns.

### Positional choices

```erb
<%= f.rui_radio_button(:status, ["Draft", "Published"]) %>
<%= f.rui_radio_button(:status, [["Draft", "draft"], ["Published", "published"]]) %>
```

### collection_select style

```erb
<%= f.rui_radio_button(:plan_id, Plan.all, :id, :name) %>
<%= f.rui_radio_button(:plan_id, Plan.all, :id, :name, label: "Plan") %>
```

### Standalone with positional args

```erb
<%= rui_radio_button(:status, ["Draft", "Published"], label: "Status") %>
```

**Note:** When both positional choices and `collection:` keyword are provided, the keyword always wins. The keyword API remains fully backward-compatible.

## Form Builder Integration

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_radio_button(:status,
    collection: Post.statuses,
    label: "Status",
    help_text: "Select the post status"
  ) %>
<% end %>
```

## Variants

### Card Variant

Perfect for selecting plans, features, or options with descriptions:

```erb
<%= f.rui_radio_button(:plan_id,
  collection: Plan.all,
  variant: :card,
  description_method: :description,
  label: "Select Plan",
  size: :lg
) %>
```

With array collections and descriptions:

```erb
<%= rui_radio_button(
  object: @post,
  method: :priority,
  collection: [
    ["Low Priority", "low", "For tasks that can wait"],
    ["Medium Priority", "medium", "Standard importance"],
    ["High Priority", "high", "Needs immediate attention"]
  ],
  variant: :card,
  description_method: 2,  # Use index 2 for description
  label: "Priority Level"
) %>
```

### Pill Variant

Compact tag-like selections:

```erb
<%= f.rui_radio_button(:category,
  collection: ["Technology", "Design", "Business"],
  variant: :pill,
  layout: :horizontal
) %>
```

### Button Variant

Toolbar-style toggle controls:

```erb
<%= f.rui_radio_button(:view_mode,
  collection: [["List", "list"], ["Grid", "grid"], ["Map", "map"]],
  variant: :button,
  layout: :horizontal,
  size: :sm
) %>
```

## Layouts

### Vertical (default)

```erb
<%= f.rui_radio_button(:priority,
  collection: [["Low", 1], ["Medium", 2], ["High", 3]],
  layout: :vertical
) %>
```

### Horizontal

```erb
<%= f.rui_radio_button(:priority,
  collection: [["Low", 1], ["Medium", 2], ["High", 3]],
  layout: :horizontal
) %>
```

## Colors

All semantic colors plus all Tailwind colors are supported:

```erb
<%# Semantic colors %>
<%= f.rui_radio_button(:status, collection: statuses, color: :primary) %>
<%= f.rui_radio_button(:status, collection: statuses, color: :success) %>
<%= f.rui_radio_button(:status, collection: statuses, color: :danger) %>

<%# Tailwind colors %>
<%= f.rui_radio_button(:status, collection: statuses, color: :indigo) %>
<%= f.rui_radio_button(:status, collection: statuses, color: :pink) %>
<%= f.rui_radio_button(:status, collection: statuses, color: :emerald) %>
```

## Sizes

Available sizes: `:xs`, `:sm`, `:base` (default), `:lg`, `:xl`

```erb
<%= f.rui_radio_button(:status, collection: statuses, size: :xs) %>
<%= f.rui_radio_button(:status, collection: statuses, size: :sm) %>
<%= f.rui_radio_button(:status, collection: statuses, size: :base) %>
<%= f.rui_radio_button(:status, collection: statuses, size: :lg) %>
<%= f.rui_radio_button(:status, collection: statuses, size: :xl) %>
```

## States

### Required

```erb
<%= f.rui_radio_button(:status,
  collection: statuses,
  label: "Status",
  required: true
) %>
```

### Disabled

```erb
<%= f.rui_radio_button(:status,
  collection: statuses,
  disabled: true
) %>
```

### Pre-selected

```erb
<%= rui_radio_button(
  object: :post,
  method: :status,
  collection: statuses,
  selected: "draft"
) %>
```

## Help Text

```erb
<%= f.rui_radio_button(:status,
  collection: statuses,
  label: "Status",
  help_text: "Select the current status of the post"
) %>
```

## Error Handling

Errors are automatically displayed when present on the model:

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_radio_button(:status,
    collection: Post.statuses,
    label: "Status"
  ) %>
  <%# If @post.errors[:status] is present, error message shows automatically %>
<% end %>
```

## Icon Support

Icons are supported in card, pill, and button variants:

```erb
<%= f.rui_radio_button(:view_mode,
  collection: [["List", "list"], ["Grid", "grid"]],
  variant: :button,
  layout: :horizontal
) do |rb|
  rb.with_icon(:list)
end %>
```

## Collection Formats

### Array of Arrays

```erb
collection: [["Text", "value"], ["Text 2", "value2"]]
```

### Array of Arrays with Descriptions

```erb
collection: [
  ["Text", "value", "Description"],
  ["Text 2", "value2", "Description 2"]
]
```

### ActiveRecord Collection

```erb
collection: Plan.all
# Uses :id for value, :name for text by default
```

### Custom Methods

```erb
collection: Plan.all,
value_method: :slug,
text_method: :title,
description_method: :description
```

### Hash (Enums)

```erb
collection: Post.statuses
# { draft: 0, published: 1 } => [["Draft", "draft"], ["Published", "published"]]
```

### Simple Array

```erb
collection: ["Option 1", "Option 2", "Option 3"]
# Value and text are the same
```

## Accessibility

The component includes full accessibility support:

- `role="radiogroup"` on wrapper
- `aria-labelledby` pointing to legend
- `aria-describedby` for help text
- `aria-required` when required
- `aria-invalid` when errors present
- Proper `for`/`id` associations for all labels
- Keyboard navigation support

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `form` | FormBuilder | nil | Form builder instance (auto-passed by `f.rui_radio_button`) |
| `object` | Object/Symbol | nil | Object to bind radio buttons to |
| `method` | Symbol | required | Attribute name on the object |
| `collection` | Enumerable | `[]` | Collection of options to choose from |
| `value_method` | Symbol | `:id` or `:last` | Method to get value from collection items |
| `text_method` | Symbol | `:name` or `:first` | Method to get label text from collection items |
| `description_method` | Symbol/Integer | nil | Method or array index to get description |
| `label` | String | nil | Legend text for the radio group |
| `description` | String | nil | Description for single radio (rarely used) |
| `help_text` | String | nil | Help text displayed below the group |
| `required` | Boolean | `false` | Show required indicator |
| `disabled` | Boolean | `false` | Disable all radio buttons |
| `selected` | Any | nil | Pre-selected value |
| `variant` | Symbol | `:radio` | Visual variant (`:radio`, `:card`, `:pill`, `:button`) |
| `color` | Symbol | `:primary` | Color theme (all semantic + Tailwind colors) |
| `size` | Symbol | `:base` | Size (`:xs`, `:sm`, `:base`, `:lg`, `:xl`) |
| `layout` | Symbol | `:vertical` | Layout direction (`:vertical`, `:horizontal`) |
| `**options` | Hash | `{}` | Additional HTML attributes |

## Examples

### Subscription Plan Selection

```erb
<%= form_with(model: @subscription) do |f| %>
  <%= f.rui_radio_button(:plan_id,
    collection: Plan.all,
    variant: :card,
    description_method: :description,
    label: "Choose Your Plan",
    help_text: "You can change your plan at any time",
    color: :indigo,
    size: :lg
  ) %>
<% end %>
```

### Content Status

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_radio_button(:status,
    collection: Post.statuses,
    label: "Post Status",
    help_text: "Draft posts are not visible to the public",
    required: true,
    color: :primary
  ) %>
<% end %>
```

### View Mode Switcher

```erb
<%= form_with(url: posts_path, method: :get) do |f| %>
  <%= f.rui_radio_button(:view,
    collection: [["List", "list"], ["Grid", "grid"], ["Map", "map"]],
    variant: :button,
    layout: :horizontal,
    size: :sm,
    color: :zinc
  ) %>
<% end %>
```

### Priority Selection

```erb
<%= f.rui_radio_button(:priority,
  collection: [
    ["Low", 1, "Standard priority"],
    ["Medium", 2, "Moderate attention"],
    ["High", 3, "Urgent attention"]
  ],
  variant: :card,
  description_method: 2,
  label: "Task Priority",
  color: :amber
) %>
```

---

## Select (`rui_select`)

# Select Component Usage

The Select component provides native HTML `<select>` elements with ViewComponent + Tailwind CSS styling. This is a lightweight, JavaScript-free alternative to the Dropdown component for form submissions.

## When to Use: Select vs Dropdown

### Use Select When:
- **Form submission** is the primary goal
- **Simple value selection** is needed
- **Native mobile picker** is desired (provides OS-native experience)
- **No JavaScript** requirement
- **Performance** is critical (lightweight, no JS overhead)

### Use Dropdown When:
- **Navigation or actions** are needed
- **Complex menu items** with icons, avatars, checkboxes
- **Custom styling** requirements
- **Rich interactions** like search, submenus, toggles

## Basic Usage

### Form Builder (Recommended)

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_select(:status, collection: Post::STATUSES, label: "Status") %>
<% end %>
```

### Standalone

```erb
<%= rui_select(:status, collection: ["Draft", "Published"], label: "Status") %>
```

## Rails-Compatible API

`rui_select` also accepts the standard Rails `f.select` and `collection_select` positional argument patterns. This means you can use the same syntax you're already familiar with from Rails:

### f.select style (positional choices)

```erb
<%# Positional array of choices %>
<%= f.rui_select(:status, ["Draft", "Published"]) %>

<%# With Rails options hash %>
<%= f.rui_select(:status, ["Draft", "Published"], { include_blank: true }) %>

<%# With Rails options hash + HTML options hash %>
<%= f.rui_select(:status, ["Draft", "Published"], { include_blank: true }, { class: "custom" }) %>

<%# Trailing keyword args work too %>
<%= f.rui_select(:status, ["Draft", "Published"], include_blank: true) %>
```

### collection_select style (positional value/text methods)

```erb
<%# ActiveRecord collection with value and text methods %>
<%= f.rui_select(:category_id, Category.all, :id, :name) %>

<%# With additional options %>
<%= f.rui_select(:category_id, Category.all, :id, :name, prompt: "Choose") %>
```

### Standalone with positional args

```erb
<%= rui_select(:status, ["Draft", "Published"], label: "Status") %>
```

**Note:** When both positional choices and `collection:` keyword are provided, the keyword always wins.

## Collection Formats

The Select component supports multiple collection formats:

### 1. Simple Array (text = value)

```erb
<%= f.rui_select(:status, collection: ["Draft", "Published", "Archived"]) %>
```

### 2. Array of [text, value] Pairs

```erb
<%= f.rui_select(:status, collection: [
  ["Draft", "draft"],
  ["Published", "published"],
  ["Archived", "archived"]
]) %>
```

### 3. ActiveRecord Relation

```erb
<%= f.rui_select(:category_id, collection: Category.all) %>
# Uses :id for value and :name for text by default
```

### 4. Custom Value/Text Methods

```erb
<%= f.rui_select(:author_id,
  collection: User.all,
  value_method: :id,
  text_method: :full_name,
  label: "Author"
) %>
```

### 5. Optgroups (Grouped Options)

```erb
<%= f.rui_select(:language, collection: {
  "Popular" => [["English", "en"], ["Spanish", "es"]],
  "Other" => [["French", "fr"], ["German", "de"]]
}) %>
```

## Parameters

### Required
- `method` (Symbol) - Attribute name (for form builder)
- `collection` (Array/Hash/Relation) - Options to display

### Optional
- `label` (String) - Label text above select
- `help_text` (String) - Helper text below select
- `selected` (Object/Array) - Pre-selected value(s) (auto-detected from model)
- `include_blank` (Boolean/String) - Include blank option (true, false, or custom text)
- `prompt` (String) - Prompt text for blank option
- `disabled` (Boolean) - Disable the select (default: false)
- `required` (Boolean) - Show required indicator (default: false)
- `multiple` (Boolean) - Allow multiple selection (default: false)
- `rows` (Integer) - Number of visible rows (for multiple selects)
- `variant` (Symbol) - :default (bordered) or :underline (default: :default)
- `color` (Symbol) - Focus ring color (default: :zinc)
- `size` (Symbol) - :xs, :sm, :base, :lg, :xl (default: :base)
- `shape` (Symbol) - :square, :rounded, :pill (default: :rounded)

## Variants

### Default (Bordered)

Standard select with border all around:

```erb
<%= f.rui_select(:status, collection: statuses, variant: :default) %>
```

### Underline

Minimal design with bottom border only:

```erb
<%= f.rui_select(:status, collection: statuses, variant: :underline) %>
```

## Sizes

Matches Dropdown component sizing for consistency:

```erb
<%= f.rui_select(:status, collection: statuses, size: :xs) %>  # Extra small
<%= f.rui_select(:status, collection: statuses, size: :sm) %>  # Small
<%= f.rui_select(:status, collection: statuses, size: :base) %> # Default
<%= f.rui_select(:status, collection: statuses, size: :lg) %>  # Large
<%= f.rui_select(:status, collection: statuses, size: :xl) %>  # Extra large
```

## Colors

Colors apply to focus ring only (not background like Dropdown):

```erb
# Semantic colors
<%= f.rui_select(:priority, collection: priorities, color: :primary) %>
<%= f.rui_select(:priority, collection: priorities, color: :success) %>
<%= f.rui_select(:priority, collection: priorities, color: :warning) %>
<%= f.rui_select(:priority, collection: priorities, color: :danger) %>

# Any Tailwind color
<%= f.rui_select(:tag, collection: tags, color: :indigo) %>
<%= f.rui_select(:tag, collection: tags, color: :purple) %>
```

## Prompt & Blank Option

### Prompt (blank option with text)

```erb
<%= f.rui_select(:country,
  collection: Country.all,
  prompt: "Select a country",
  required: true
) %>
```

### Include Blank (empty option)

```erb
<%= f.rui_select(:category_id,
  collection: Category.all,
  include_blank: true
) %>
```

### Custom Blank Text

```erb
<%= f.rui_select(:category_id,
  collection: Category.all,
  include_blank: "-- Choose a category --"
) %>
```

## Multiple Selection

Allow selecting multiple options with `Cmd/Ctrl + Click`:

```erb
<%= f.rui_select(:tag_ids,
  collection: Tag.all,
  multiple: true,
  rows: 5,
  label: "Tags"
) %>
```

The `rows` parameter controls how many options are visible without scrolling.

## Form Integration

The component automatically integrates with Rails forms:

### Auto-Detects Selected Value

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_select(:status, collection: Post::STATUSES) %>
  <%# @post.status is automatically selected %>
<% end %>
```

### Auto-Displays Errors

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_select(:category_id, collection: Category.all, required: true) %>
  <%# Errors from @post.errors[:category_id] are displayed automatically %>
<% end %>
```

## Complete Examples

### Basic Form Select

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_select(:status,
    collection: [["Draft", "draft"], ["Published", "published"]],
    label: "Post Status",
    required: true
  ) %>

<%= f.rui_button("Save") %>
<% end %>
```

### With ActiveRecord Collection

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_select(:category_id,
    collection: Category.all,
    prompt: "Choose a category",
    label: "Category",
    help_text: "Select the primary category for this post",
    color: :primary,
    size: :lg
  ) %>
<% end %>
```

### Multiple Selection with Tags

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_select(:tag_ids,
    collection: Tag.all,
    multiple: true,
    rows: 6,
    label: "Tags",
    help_text: "Hold Cmd/Ctrl to select multiple tags"
  ) %>
<% end %>
```

### Grouped Options (Optgroups)

```erb
<%= form_with(model: @user) do |f| %>
  <%= f.rui_select(:timezone, collection: {
    "US Timezones" => [
      ["Eastern Time", "America/New_York"],
      ["Central Time", "America/Chicago"],
      ["Pacific Time", "America/Los_Angeles"]
    ],
    "European Timezones" => [
      ["London", "Europe/London"],
      ["Paris", "Europe/Paris"],
      ["Berlin", "Europe/Berlin"]
    ]
  }, label: "Timezone", prompt: "Select your timezone") %>
<% end %>
```

### Underline Variant

```erb
<%= form_with(model: @user) do |f| %>
  <%= f.rui_select(:role,
    collection: { "Administrator" => "admin", "Editor" => "editor", "Viewer" => "viewer" },
    variant: :underline,
    color: :indigo,
    label: "User Role"
  ) %>
<% end %>
```

## Accessibility

The Select component provides full accessibility through native browser support:

- **Native keyboard navigation** (Arrow keys, Enter, Space, type-to-search)
- **Screen reader support** (built-in ARIA roles and attributes)
- **Label association** (automatic for/id linking)
- **Error announcement** (aria-invalid when errors present, plus
  aria-describedby pointing at the rendered error message's id)
- **Required field indicator** (visual * and aria-required)
- **Help text association** (aria-describedby, error id takes precedence
  over the help text id when both are present)

## Legacy select enhancers (Materialize, Select2, Chosen)

Every `<select>` the component renders carries a `data-rui="select"` marker.
This is aimed at apps migrating off (or running alongside) a legacy jQuery
`<select>` enhancer - Materialize's `FormSelect`, Select2, Chosen, etc.

Those libraries typically initialize by scanning the whole document for
`select` elements, and most re-run that scan on every Turbo navigation
(`turbo:load`, `turbo:frame-load`) since they have no idea Turbo swapped the
DOM out from under them. If that scan is unscoped, it will pick up RRUI's
native `<select>` too, wrapping it in the legacy library's own markup and
breaking RRUI's styling and the value/`aria-*` wiring this component sets up.

Exclude RRUI's selects from that scan with `:not([data-rui])`:

```js
// Materialize example - initialize only non-RRUI selects, and re-run
// the same scoped query on every Turbo navigation instead of a global one.
function initLegacySelects() {
  const elements = document.querySelectorAll("select:not([data-rui])")
  M.FormSelect.init(elements)
}

document.addEventListener("turbo:load", initLegacySelects)
document.addEventListener("turbo:frame-load", initLegacySelects)
```

The same `select:not([data-rui])` pattern works for Select2
(`$("select:not([data-rui])").select2()`) and Chosen
(`$("select:not([data-rui])").chosen()`).

If you're migrating a form wholesale to `f.rui_select`, this lets the
migration happen field-by-field: converted fields carry the marker and are
automatically skipped, unconverted `f.select` fields have no marker and keep
being enhanced exactly as before.

## Styling

The Select component uses Tailwind CSS classes defined in `styles.rb`:

- Matches Dropdown sizing for consistency
- Custom dropdown arrow (SVG data URI)
- Dark mode support throughout
- Focus ring with configurable colors
- Error state styling

## Implementation Notes

- **No JavaScript**: Pure HTML/CSS, no Stimulus controller needed
- **Native behavior**: Browser handles all interaction (opens OS-native picker on mobile)
- **Lightweight**: Minimal HTML output, no event listeners
- **Form-focused**: Designed primarily for form submissions
- **Collection processing**: Handles Arrays, Hashes, and ActiveRecord relations
- **Optgroup support**: Native `<optgroup>` for grouped options

---

## Social Button (`rui_social_button`)

# RapidRailsUI Social Button Component

The Social Button component provides beautifully designed, platform-branded buttons for social authentication and payment integrations. Each button uses official brand colors and styling to maintain consistency with user expectations.

## Basic Usage

The simplest usage requires only a platform (positional argument):

```erb
<%= rui_social_button(:google) %>
```

This renders a Google button with the default text "Sign in with Google" and official Google blue branding.

### Syntax Options

The component supports flexible syntax (positional or keyword arguments):

```erb
<%# Just platform (recommended) %>
<%= rui_social_button(:google) %>

<%# Platform + text (positional, recommended) %>
<%= rui_social_button(:google, "Continue with Google") %>

<%# Mixed positional + keyword %>
<%= rui_social_button(:google, "Continue with Google", size: :lg) %>

<%# All keyword arguments (backward compatible) %>
<%= rui_social_button(platform: :google, text: "Continue with Google") %>
```

**Recommended:** Use positional arguments for cleaner, more concise code.

## Supported Platforms

### Social Platforms

- **`:google`** - Google Sign-In (blue)
- **`:github`** - GitHub authentication (dark)
- **`:facebook`** - Facebook Login (blue)
- **`:apple`** - Apple Sign In (black)
- **`:microsoft`** - Microsoft Account (blue)
- **`:linkedin`** - LinkedIn authentication (blue)
- **`:discord`** - Discord OAuth (purple)
- **`:twitter`** - Twitter (classic blue)
- **`:x`** - X (formerly Twitter, black)

### Payment Platforms

- **`:paypal`** - PayPal checkout (blue)
- **`:stripe`** - Stripe payment (purple)
- **`:apple_pay`** - Apple Pay (black)
- **`:google_pay`** - Google Pay (blue)
- **`:bitcoin`** - Bitcoin payment (orange)
- **`:ethereum`** - Ethereum payment (purple)
- **`:visa`** - Visa card payment (blue)
- **`:mastercard`** - Mastercard payment (red)
- **`:amex`** - American Express (blue)

Each platform automatically uses its official brand colors, appropriate icons, and default text.

## Custom Text

Override the default platform-specific text using the second positional argument:

```erb
<%# Positional (recommended) %>
<%= rui_social_button(:google, "Continue with Google") %>
<%= rui_social_button(:github, "Connect GitHub Account") %>
<%= rui_social_button(:paypal, "Checkout with PayPal") %>

<%# Keyword (also works) %>
<%= rui_social_button(:google, text: "Continue with Google") %>
```

## Custom Icons

Some platforms use generic Lucide icons as placeholders. You can easily override them with custom brand logos:

### Using Icon Slot (Recommended)

```erb
<%# Override with custom SVG or icon component %>
<%= rui_social_button(:google) do |button| %>
  <% button.with_icon(name: "your-custom-google-logo") %>
<% end %>

<%# Using a different Lucide icon %>
<%= rui_social_button(:discord) do |button| %>
  <% button.with_icon(name: "message-square") %>
<% end %>
```

### Default Icons Used

The component uses Lucide icons by default. Some platforms have exact matches, others use generic fallbacks:

- ✅ **Exact matches:** GitHub, Facebook, Apple, LinkedIn, Twitter, Bitcoin
- 🔄 **Generic fallbacks:**
  - Google → `chrome` (Lucide's Chrome icon, similar)
  - Microsoft → `square` (generic)
  - Discord → `message-circle` (chat-related)
  - PayPal → `wallet` (payment-related)
  - Stripe → `credit-card`
  - Google Pay → `smartphone`
  - Ethereum → `hexagon`
  - Visa/Mastercard/Amex → `credit-card`

**For production apps**, consider:
1. Adding official brand icon SVGs to your project
2. Using the icon slot to override defaults with official logos
3. Installing additional icon libraries (e.g., `simple-icons`)

### Icon Color Override

Icons automatically inherit the button's brand color, but you can override with a custom color:

```erb
<%# Icon inherits brand color (default behavior) %>
<%= rui_social_button(:google) do |button| %>
  <% button.with_icon(name: "mail") %>
  <%# Icon will be Google blue %>
<% end %>

<%# Icon with custom color (overrides inheritance) %>
<%= rui_social_button(:github) do |button| %>
  <% button.with_icon(name: "star", color: :yellow) %>
  <%# GitHub button with yellow star icon %>
<% end %>

<%# Useful for special indicators %>
<%= rui_social_button(:stripe, "Premium Payment") do |button| %>
  <% button.with_icon(name: "crown", color: :yellow) %>
  <%# Stripe button with yellow crown icon for premium %>
<% end %>
```

**Note:** When you provide an explicit `color:` parameter to the icon, it uses standalone mode and renders with its own color instead of inheriting from the social button's brand color.

## Sizes

Social buttons support six standard sizes:

```erb
<%= rui_social_button(:google, size: :xs) %>   # Extra small
<%= rui_social_button(:google, size: :sm) %>   # Small
<%= rui_social_button(:google, size: :base) %> # Base (default)
<%= rui_social_button(:google, size: :md) %>   # Medium
<%= rui_social_button(:google, size: :lg) %>   # Large
<%= rui_social_button(:google, size: :xl) %>   # Extra large
```

## Shapes

Choose from different button shapes:

```erb
<%= rui_social_button(:github, shape: :rounded) %>  # Default rounded corners
<%= rui_social_button(:github, shape: :pill) %>     # Fully rounded
<%= rui_social_button(:github, shape: :square) %>   # Square corners
<%= rui_social_button(:github, shape: :circle, icon_only: true) %>  # Perfect circle (requires icon_only)
```

## Icon Only Mode

Display only the platform icon without text (perfect for compact layouts):

```erb
<%= rui_social_button(:twitter, icon_only: true) %>
<%= rui_social_button(:facebook, icon_only: true, size: :lg) %>
<%= rui_social_button(:github, icon_only: true, shape: :circle) %>
```

Icon-only buttons automatically adjust to square dimensions and include proper `aria-label` attributes for accessibility.

## Full Width

Make buttons span their container width:

```erb
<div class="max-w-md">
  <%= rui_social_button(:google, full_width: true) %>
  <%= rui_social_button(:apple, full_width: true) %>
  <%= rui_social_button(:github, full_width: true) %>
</div>
```

Perfect for authentication pages with stacked sign-in options.

## Links and OAuth Flows

Use social buttons as links for OAuth authentication:

```erb
<%# Simple GET link %>
<%= rui_social_button(:google, path: "/auth/google") %>

<%# External link (opens in new tab) %>
<%= rui_social_button(:github, path: "https://github.com/login/oauth/authorize?...", external: true) %>

<%# With Rails route helpers %>
<%= rui_social_button(:twitter, path: auth_twitter_path) %>

<%# POST method for OAuth callbacks (uses button_to) %>
<%= rui_social_button(:facebook, path: "/auth/facebook/callback", method: :post) %>
```

The component automatically:
- Renders as `<a>` for GET requests
- Renders as `<form><button>` for POST/PATCH/PUT/DELETE
- Adds `target="_blank"` and `rel="noopener noreferrer"` for external links
- Maintains brand styling across all rendering modes

## Payment Integration Examples

### Checkout Buttons

```erb
<%# PayPal checkout %>
<%= rui_social_button(:paypal, "Pay with PayPal", path: checkout_paypal_path, method: :post, full_width: true) %>

<%# Stripe checkout %>
<%= rui_social_button(:stripe, "Checkout with Stripe", path: checkout_stripe_path, full_width: true) %>

<%# Apple Pay (quick pay button) %>
<%= rui_social_button(:apple_pay, path: checkout_apple_pay_path, method: :post) %>
```

### Cryptocurrency Payments

```erb
<%= rui_social_button(:bitcoin, "Pay with Bitcoin", path: checkout_bitcoin_path) %>
<%= rui_social_button(:ethereum, "Pay with Ethereum", path: checkout_ethereum_path) %>
```

### Payment Method Selection

```erb
<div class="grid grid-cols-3 gap-4">
  <%= rui_social_button(:visa, icon_only: true) %>
  <%= rui_social_button(:mastercard, icon_only: true) %>
  <%= rui_social_button(:amex, icon_only: true) %>
</div>
```

## States

### Disabled State

```erb
<%= rui_social_button(:google, disabled: true) %>
<%= rui_social_button(:github, "Already Connected", disabled: true) %>
```

Disabled buttons have reduced opacity and cannot be clicked. Proper ARIA attributes are automatically added.

### Loading State

```erb
<%= rui_social_button(:apple, loading: true) %>
<%= rui_social_button(:google, "Connecting...", loading: true) %>
```

Loading buttons display an animated spinner and include `aria-busy="true"` for screen readers.

## Common Patterns

### Social Authentication Page

```erb
<div class="max-w-sm mx-auto space-y-4">
  <h2 class="text-2xl font-bold text-center mb-6">Sign in to your account</h2>

<%= rui_social_button(:google, path: "/auth/google", full_width: true) %>
  <%= rui_social_button(:github, path: "/auth/github", full_width: true) %>
  <%= rui_social_button(:apple, path: "/auth/apple", full_width: true) %>

<div class="relative py-4">
    <div class="absolute inset-0 flex items-center">
      <div class="w-full border-t border-zinc-300"></div>
    </div>
    <div class="relative flex justify-center text-sm">
      <span class="px-2 bg-white text-zinc-500">Or continue with email</span>
    </div>
  </div>

<%# Email form here %>
</div>
```

### Social Sharing Buttons

```erb
<div class="flex gap-3 items-center">
  <span class="text-sm font-medium text-zinc-700">Share:</span>

<%= rui_social_button(:twitter, "Share on X",
    path: "https://twitter.com/intent/tweet?text=#{CGI.escape(@post.title)}&url=#{CGI.escape(post_url(@post))}",
    external: true,
    size: :sm) %>

<%= rui_social_button(:facebook, "Share",
    path: "https://www.facebook.com/sharer/sharer.php?u=#{CGI.escape(post_url(@post))}",
    external: true,
    size: :sm) %>

<%= rui_social_button(:linkedin,
    icon_only: true,
    path: "https://www.linkedin.com/sharing/share-offsite/?url=#{CGI.escape(post_url(@post))}",
    external: true) %>
</div>
```

### Account Connections

```erb
<div class="space-y-3">
  <h3 class="text-lg font-semibold">Connected Accounts</h3>

<div class="flex items-center justify-between p-4 border rounded-lg">
    <div class="flex items-center gap-3">
      <%= rui_social_button(:github, icon_only: true, disabled: true) %>
      <div>
        <p class="font-medium">GitHub</p>
        <p class="text-sm text-zinc-600">@<%= current_user.github_username %></p>
      </div>
    </div>
    <%= link_to "Disconnect", disconnect_github_path,
        method: :delete,
        class: "text-sm text-danger-600 hover:text-danger-700" %>
  </div>

<div class="flex items-center justify-between p-4 border rounded-lg border-dashed">
    <%= rui_social_button(:twitter, "Connect Twitter", path: "/auth/twitter", size: :sm) %>
  </div>
</div>
```

### Payment Methods Grid

```erb
<div class="space-y-4">
  <h3 class="text-lg font-semibold">Choose payment method</h3>

<div class="text-center">
    <p class="text-sm text-zinc-600">Or pay with card</p>
    <div class="flex justify-center gap-2 mt-2">
      <%= rui_social_button(:visa, icon_only: true, size: :sm) %>
      <%= rui_social_button(:mastercard, icon_only: true, size: :sm) %>
      <%= rui_social_button(:amex, icon_only: true, size: :sm) %>
    </div>
  </div>
</div>
```

### Conditional Rendering Based on Connection Status

```erb
<% if current_user.github_connected? %>
  <%= rui_social_button(:github, "GitHub Connected", disabled: true) %>
<% else %>
  <%= rui_social_button(:github, "Connect GitHub", path: connect_github_path) %>
<% end %>
```

## Accessibility

The Social Button component includes comprehensive accessibility features:

- **ARIA labels**: `aria-label` automatically added for icon-only buttons
- **Role attributes**: `role="button"` for link-based buttons
- **Loading state**: `aria-busy="true"` during loading
- **Disabled state**: `aria-disabled="true"` and `tabindex="-1"` when disabled
- **Focus management**: Clear focus rings with platform-specific colors
- **External links**: Proper `rel="noopener noreferrer"` for security
- **Keyboard navigation**: Full keyboard support for all button states

## Additional HTML Attributes

Pass any additional HTML attributes:

```erb
<%= rui_social_button(:google,
  id: "google-signin",
  class: "my-custom-class",
  data: {
    controller: "oauth",
    action: "click->oauth#track",
    analytics: "google-signin-clicked"
  }) %>
```

## Integration with Omniauth

Perfect for Rails OAuth flows with Omniauth:

```ruby
# config/routes.rb
get "/auth/:provider/callback", to: "sessions#create"
get "/auth/failure", to: "sessions#failure"
```

```erb
# app/views/sessions/new.html.erb
<div class="space-y-3">
  <%= rui_social_button(:google, path: "/auth/google", full_width: true) %>
  <%= rui_social_button(:github, path: "/auth/github", full_width: true) %>
</div>
```

## Styling with Tailwind

The component uses Tailwind CSS with platform-specific brand colors via arbitrary values (`bg-[#hex]`). All official brand colors are pre-configured, ensuring visual consistency.

The component automatically handles:
- Proper text contrast (white text on dark backgrounds)
- Hover state darkening
- Focus ring colors matching the brand
- Responsive touch targets
- Smooth transitions

## Browser Support

- All modern browsers (Chrome, Firefox, Safari, Edge)
- Tailwind CSS v3.0+ required for arbitrary value support (`bg-[#hex]`)
- Graceful degradation for older browsers

## Platform Brand Guidelines

All platform colors and styling follow official brand guidelines:
- Google: Material Design Blue (#4285F4)
- GitHub: GitHub Dark (#24292e)
- Facebook: Facebook Blue (#1877f2)
- Apple: Apple Black (#000000)
- PayPal: PayPal Blue (#0070ba)
- Stripe: Stripe Purple (#635bff)
- Bitcoin: Bitcoin Orange (#f7931a)

## Icon Customization for Production

For pixel-perfect branding in production apps, consider these approaches:

### 1. Using Official Brand Assets

Download official brand assets and add them to your project:

```erb
<%# Create a custom icon helper or partial %>
<%= rui_social_button(:google) do |button| %>
  <% button.with_icon do %>
    <%= image_tag "brands/google-logo.svg", class: "w-5 h-5" %>
  <% end %>
<% end %>
```

### 2. Using Simple Icons Library

Install [simple-icons](https://simpleicons.org/) for official brand SVGs:

```bash
npm install simple-icons
```

Then create custom icon components or helpers to use them with the social button.

### 3. Using SVG Sprites

Create an SVG sprite with all brand logos:

```erb
<%= rui_social_button(:google) do |button| %>
  <% button.with_icon do %>
    <svg class="w-5 h-5"><use href="#google-logo"></use></svg>
  <% end %>
<% end %>
```

The icon slot provides maximum flexibility for your preferred icon solution!

---

## Stat (`rui_stat`)

# Stat Component

A metric card component for displaying key numbers with optional change indicators, progress bars, and composable slots. Composes `rui_text`, `rui_badge`, and `rui_progress` internally.

## Basic Usage

```erb
<%= rui_stat("Leads", "129") %>
```

`label` and `value` are both positional and required.

## With Change Indicator

```erb
<%# Auto-detects direction from +/- prefix %>
<%= rui_stat("Leads", "129", change: "+8%") %>
<%= rui_stat("Churn", "12%", change: "-3%") %>

<%# Custom badge color %>
<%= rui_stat("Revenue", "$32,209", change: "+24% vs last month", change_color: :emerald) %>
<%= rui_stat("Errors", "14", change: "+5", change_color: :red) %>
```

`change_direction` is auto-detected from the string: `+` → `:up`, `-` → `:down`. Override explicitly if needed:

```erb
<%= rui_stat("Refunds", "7", change: "7 new", change_direction: :down, change_color: :red) %>
```

## With Progress Bar

Renders an `rui_progress` bar below the metric:

```erb
<%= rui_stat("Retention", "95%", progress: 95) %>

<%# Custom progress color (defaults to color:) %>
<%= rui_stat("Storage", "68%", progress: 68, color: :primary, progress_color: :warning) %>
```

## Sizes

Controls card padding:

```erb
<%= rui_stat("Leads", "129", size: :sm) %>    <%# p-4 %>
<%= rui_stat("Leads", "129", size: :base) %>  <%# p-5 — default %>
<%= rui_stat("Leads", "129", size: :lg) %>    <%# p-6 %>
```

## With Icon Slot

The icon appears at the top-right of the card:

```erb
<%= rui_stat("Leads", "129") do |s|
  s.with_icon(:trending_up)
end %>

<%# With custom icon options %>
<%= rui_stat("Revenue", "$32,209") do |s|
  s.with_icon(:dollar_sign, class: "text-emerald-500")
end %>
```

## With Footer Slot

Arbitrary content below the metric area:

```erb
<%= rui_stat("Conversion", "3.2%") do |s|
  s.with_footer do
    rui_link("View report →", analytics_path, variant: :no_underline, size: :xs)
  end
end %>
```

## With Sparkline Slot

Arbitrary content alongside the value (e.g. a mini chart placeholder):

```erb
<%= rui_stat("Signups", "1,204") do |s|
  s.with_sparkline do
    content_tag(:div, nil, class: "w-16 h-8 bg-emerald-100 dark:bg-emerald-900 rounded")
  end
end %>
```

## Full-Featured Example

```erb
<%= rui_stat("Monthly Revenue",
  "$32,209",
  change: "+24% vs last month",
  change_color: :emerald,
  progress: 78,
  color: :primary,
  size: :base
) do |s|
  s.with_icon(:trending_up)
  s.with_footer do
    rui_link("View breakdown →", revenue_path, size: :xs)
  end
end %>
```

## Dashboard Grid

```erb
<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
  <%= rui_stat("Total Users", "12,847",
    change: "+12%",
    change_color: :emerald,
    progress: 72
  ) do |s|
    s.with_icon(:users)
  end %>

<%= rui_stat("Revenue", "$94,200",
    change: "+8% vs last month",
    change_color: :emerald
  ) do |s|
    s.with_icon(:dollar_sign)
  end %>

<%= rui_stat("Active Sessions", "3,421",
    change: "-2%",
    change_color: :red
  ) do |s|
    s.with_icon(:activity)
  end %>

<%= rui_stat("Conversion", "3.2%",
    change: "+0.4%",
    change_color: :emerald,
    progress: 32,
    progress_color: :primary
  ) do |s|
    s.with_icon(:target)
  end %>
</div>
```

## Dynamic Values from a Model

```erb
<%= rui_stat(
  "Open Tickets",
  @tickets.open.count.to_s,
  change: trend_for(@tickets),
  change_color: @tickets.trending_up? ? :emerald : :red,
  progress: @tickets.open_percentage
) %>
```

## Accessibility

- Uses `rui_text` for label/value — proper semantic markup
- Change badge uses `rui_badge` — screen-reader friendly text
- Progress bar uses `rui_progress` — `role="progressbar"` with ARIA values
- No JS — pure server-rendered HTML

## Props Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | String | required | Metric name (e.g. "Leads", "Revenue") |
| `value` | String/Integer | required | Metric value (e.g. "129", "$32,209") |
| `change` | String | `nil` | Change text (e.g. "+8%", "-3 vs yesterday") |
| `change_color` | Symbol | `:emerald` | Badge color for change indicator |
| `change_direction` | Symbol | auto | `:up` or `:down` (auto-detected from `+`/`-` prefix) |
| `progress` | Integer | `nil` | 0–100; renders `rui_progress` when present |
| `progress_color` | Symbol | `color:` | Progress bar color (defaults to `color:`) |
| `color` | Symbol | `:primary` | Accent color for the card |
| `size` | Symbol | `:base` | Card padding (`:sm`, `:base`, `:lg`) |
| `**options` | Hash | — | Additional HTML attributes on card wrapper |

## Slots

| Slot | Description |
|------|-------------|
| `with_icon(name, **options)` | Lucide icon at top-right. Accepts icon name + any `rui_icon` options. |
| `with_sparkline { }` | Arbitrary content next to the value (mini chart, etc.) |
| `with_footer { }` | Arbitrary content below the metric area |

---

## Steps (`rui_steps`)

# Steps Component

Multi-step wizard with Turbo Frame integration for smooth step transitions. Supports 7 layout variants, 3 navigation modes, flexible layout slots, and full accessibility.

---

## Table of Contents

- [Quick Start](#quick-start)
- [API Reference](#api-reference)
  - [Component Parameters](#component-parameters)
  - [Step Parameters](#step-parameters)
  - [Layout Slots](#layout-slots)
- [Layout Slots (Header/Footer)](#layout-slots-headerfooter)
  - [Header Slot](#header-slot)
  - [Footer Slot](#footer-slot)
  - [Custom Navigation](#custom-navigation)
  - [Combining Slots](#combining-slots)
  - [Real-World Slot Patterns](#real-world-slot-patterns)
- [Variants](#variants)
  - [Horizontal (Default)](#horizontal-default)
  - [Vertical](#vertical)
  - [Minimal](#minimal)
  - [Progress](#progress)
  - [Breadcrumb](#breadcrumb)
  - [Timeline](#timeline)
  - [Vertical Cards](#vertical-cards)
- [Sizes](#sizes)
- [Colors](#colors)
- [Navigation Modes](#navigation-modes)
- [Position Options](#position-options)
- [Icons](#icons)
- [Custom Button Text](#custom-button-text)
- [Error Handling](#error-handling)
- [Caching & Validation](#caching--validation)
- [Controller Setup](#controller-setup)
- [Stimulus Controller](#stimulus-controller)
- [Accessibility](#accessibility)
- [Common Patterns](#common-patterns)
- [Troubleshooting](#troubleshooting)

---

## Quick Start

A simple 3-step wizard using the view helper:

```erb
<%= rui_steps(
  id: "registration",
  url: registration_path,
  current_step: @current_step
) do |steps| %>
  <%# Positional title syntax (recommended) %>
  <% steps.with_step("Account") do %>
    <div class="space-y-4">
      <div>
        <label class="block text-sm font-medium">Email</label>
        <input type="email" name="email" required class="mt-1 block w-full rounded-md border-zinc-300" />
      </div>
      <div>
        <label class="block text-sm font-medium">Password</label>
        <input type="password" name="password" required class="mt-1 block w-full rounded-md border-zinc-300" />
      </div>
    </div>
  <% end %>

<% steps.with_step("Profile") do %>
    <div class="space-y-4">
      <div>
        <label class="block text-sm font-medium">Full Name</label>
        <input type="text" name="name" required class="mt-1 block w-full rounded-md border-zinc-300" />
      </div>
    </div>
  <% end %>

<% steps.with_step("Confirm") do %>
    <div class="text-center py-8">
      <p class="text-zinc-600">Review and click Submit to complete.</p>
    </div>
  <% end %>
<% end %>
```

---

## API Reference

### Component Parameters

#### Required

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | String | Unique identifier for the wizard (used for DOM ids, storage keys) |
| `url` | String | Form submission URL for step navigation |

#### Optional

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `current_step` | Integer | `0` | Current step index (0-based) |
| `variant` | Symbol | `:horizontal` | Layout variant (see [Variants](#variants)) |
| `navigation` | Symbol | `:linear` | Navigation mode (see [Navigation Modes](#navigation-modes)) |
| `size` | Symbol | `:md` | Indicator size: `:sm`, `:md`, `:lg` |
| `color` | Symbol | `:primary` | Theme color for active step |
| `indicators_position` | Symbol | `:top` | Position: `:top`, `:bottom`, `:none` |
| `buttons_position` | Symbol | `:bottom` | Position: `:top`, `:bottom`, `:none` |
| `cache_locally` | Boolean | `true` | Cache current step in LocalStorage |
| `client_validation` | Boolean | `true` | Run HTML5 validation before next |
| `error_step` | Integer | `nil` | Step index with error (shows red) |
| `back_text` | String | `"Back"` | Back button label |
| `next_text` | String | `"Next"` | Next button label |
| `submit_text` | String | `"Submit"` | Submit button label (last step) |
| `loading_text` | String | `"Saving..."` | Loading state text |
| `turbo_frame_id` | String | `nil` | Custom turbo frame ID |

#### Parameter Values Reference

| Parameter | Valid Values |
|-----------|-------------|
| `variant` | `:horizontal`, `:vertical`, `:minimal`, `:progress`, `:breadcrumb`, `:timeline`, `:vertical_cards` |
| `navigation` | `:linear`, `:free`, `:completed_only` |
| `size` | `:sm`, `:md`, `:lg` |
| `color` | `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:blue`, `:purple`, `:pink`, `:amber`, `:cyan`, `:indigo`, `:teal`, `:orange`, `:rose`, `:violet`, `:emerald`, `:sky`, `:lime`, `:fuchsia` |
| `indicators_position` | `:top`, `:bottom`, `:none` |
| `buttons_position` | `:top`, `:bottom`, `:none` |

---

### Step Parameters

Each step is defined using `steps.with_step`. The title can be passed as a positional argument or keyword.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `title` | String | **Yes** | - | Step title (positional or keyword) |
| `description` | String | No | `nil` | Subtitle text (vertical/timeline variants) |
| `icon` | Symbol | No | `nil` | Icon name instead of step number |
| `optional` | Boolean | No | `false` | Mark step as skippable |

**Positional title (cleaner):**
```erb
<% steps.with_step("Account") do %>
  Content here
<% end %>
```

**Keyword title (explicit):**
```erb
<% steps.with_step(title: "Account") do %>
  Content here
<% end %>
```

**With all options:**
```erb
<% steps.with_step("Payment", description: "Enter card details", icon: :credit_card, optional: false) do %>
  Content here
<% end %>
```

---

### Layout Slots

Two slots allow layout customization for additional content:

| Slot | Method | Position | Description |
|------|--------|----------|-------------|
| **Header** | `with_header` | Above everything | Custom content at the top |
| **Footer** | `with_footer` | Below everything | Custom content at the bottom |

```erb
<%= rui_steps(id: "wizard", url: path) do |steps| %>
  <% steps.with_header do %>
    
  <% end %>

<% steps.with_step("Step 1") { "content" } %>

<% steps.with_footer do %>
    
  <% end %>
<% end %>
```

**Position Controls** (for built-in elements):
- `indicators_position: :top` (default), `:bottom`, `:none`
- `buttons_position: :top`, `:bottom` (default), `:none`

---

## Step Title Syntax

The Steps component supports two equivalent syntaxes for step titles. Both produce identical results.

### Positional Title (Recommended)

Pass the title as the first argument. This is cleaner and more readable:

```erb
<%# Simple step %>
<% steps.with_step("Account") do %>
  <p>Step content here</p>
<% end %>

<%# With icon %>
<% steps.with_step("Payment", icon: :credit_card) do %>
  <p>Payment form here</p>
<% end %>

<%# With description (vertical/timeline variants) %>
<% steps.with_step("Shipping", description: "Enter delivery address") do %>
  <p>Address form here</p>
<% end %>

<%# With all options %>
<% steps.with_step("Extras", description: "Optional add-ons", icon: :sparkles, optional: true) do %>
  <p>Optional content</p>
<% end %>
```

### Keyword Title (Explicit)

Pass the title as a keyword argument. Useful when you prefer explicit naming:

```erb
<% steps.with_step(title: "Account") do %>
  <p>Step content here</p>
<% end %>

<% steps.with_step(title: "Payment", icon: :credit_card) do %>
  <p>Payment form here</p>
<% end %>
```

### Mixing Syntaxes

You can mix both syntaxes in the same wizard:

```erb
<%= rui_steps(id: "wizard", url: path) do |steps| %>
  <% steps.with_step("Account") do %>
    <p>Positional title</p>
  <% end %>

<% steps.with_step(title: "Profile", description: "About you") do %>
    <p>Keyword title with description</p>
  <% end %>

<% steps.with_step("Confirm", icon: :check_circle) do %>
    <p>Positional title with icon</p>
  <% end %>
<% end %>
```

### Title is Required

A step without a title raises `ArgumentError`:

```erb
<%# This will raise an error! %>
<% steps.with_step(icon: :user) do %>
  <p>Missing title</p>
<% end %>
```

Error: `ArgumentError: Step requires a title`

---

## Layout Slots (Header/Footer)

Layout slots let you add custom content above and below the wizard. The built-in elements (indicators and buttons) are controlled via position params.

### Visual Layout (Default: indicators_position: :top, buttons_position: :bottom)

```
+--------------------------------------------------+
| HEADER SLOT (with_header)                        |
|   Custom content (title, description, cancel)    |
+--------------------------------------------------+
| STEP INDICATORS (indicators_position: :top)      |
|   [1] ─── [2] ─── [3] ─── [4]                   |
+--------------------------------------------------+
| STEP CONTENT                                     |
|   Current step's content area                    |
+--------------------------------------------------+
| NAV BUTTONS (buttons_position: :bottom)          |
|   [ Back ]                        [ Next ]       |
+--------------------------------------------------+
| FOOTER SLOT (with_footer)                        |
|   Custom content (help links, terms, progress)   |
+--------------------------------------------------+
```

### Position Params

| Param | Options | Default | Description |
|-------|---------|---------|-------------|
| `indicators_position` | `:top`, `:bottom`, `:none` | `:top` | Where step indicators appear |
| `buttons_position` | `:top`, `:bottom`, `:none` | `:bottom` | Where nav buttons appear |

**Swapped Layout** (indicators_position: :bottom, buttons_position: :top):

```
+--------------------------------------------------+
| HEADER SLOT (with_header)                        |
+--------------------------------------------------+
| NAV BUTTONS (buttons_position: :top)             |
|   [ Back ]                        [ Next ]       |
+--------------------------------------------------+
| STEP CONTENT                                     |
|   Current step's content area                    |
+--------------------------------------------------+
| STEP INDICATORS (indicators_position: :bottom)   |
|   [1] ─── [2] ─── [3] ─── [4]                   |
+--------------------------------------------------+
| FOOTER SLOT (with_footer)                        |
+--------------------------------------------------+
```

---

### Header Slot

Add custom content above the step indicators. Great for:
- Wizard title and description
- Cancel/Close buttons
- Progress summary
- Breadcrumbs

```erb
<%= rui_steps(id: "wizard", url: wizard_path) do |steps| %>
  <% steps.with_header do %>
    <div class="flex justify-between items-center">
      <div>
        <h2 class="text-xl font-semibold text-zinc-900 dark:text-zinc-100">
          Account Setup
        </h2>
        <p class="text-sm text-zinc-500 dark:text-zinc-400">
          Complete these steps to activate your account
        </p>
      </div>
      <button type="button" class="text-zinc-400 hover:text-zinc-600">
        <svg class="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
        </svg>
      </button>
    </div>
  <% end %>

<% steps.with_step("Account") { "..." } %>
  <% steps.with_step("Profile") { "..." } %>
  <% steps.with_step("Done") { "..." } %>
<% end %>
```

**Header with Cancel Button:**

```erb
<% steps.with_header do %>
  <div class="flex justify-between items-center pb-4 border-b border-zinc-200 dark:border-zinc-700">
    <h2 class="text-lg font-medium">New Project Wizard</h2>
    <%= rui_button("Cancel", variant: :ghost, size: :sm, href: projects_path) %>
  </div>
<% end %>
```

---

### Footer Slot

Add custom content below everything (after navigation buttons). Great for:
- Help links
- Terms and conditions
- Progress saved indicator
- Additional context

```erb
<%= rui_steps(id: "wizard", url: wizard_path) do |steps| %>
  <% steps.with_step("Account") { "..." } %>
  <% steps.with_step("Profile") { "..." } %>

<% steps.with_footer do %>
    <div class="flex justify-between items-center text-sm text-zinc-500 dark:text-zinc-400">
      <span>Your progress is saved automatically</span>
      <a href="/help" class="text-blue-600 hover:underline dark:text-blue-400">
        Need help?
      </a>
    </div>
  <% end %>
<% end %>
```

**Footer with Terms:**

```erb
<% steps.with_footer do %>
  <p class="text-xs text-zinc-400 text-center mt-4">
    By continuing, you agree to our
    <a href="/terms" class="underline">Terms of Service</a> and
    <a href="/privacy" class="underline">Privacy Policy</a>.
  </p>
<% end %>
```

---

### Custom Navigation

To add custom navigation, hide the default buttons and add your own in the header or footer slot.

```erb
<%= rui_steps(
  id: "wizard",
  url: wizard_path,
  buttons_position: :none  <%# Hide default buttons %>
) do |steps| %>
  <% steps.with_header do %>
    <div class="flex justify-between items-center">
      <span class="font-medium">Setup Progress</span>
      <div class="flex gap-2">
        <%= rui_button("Back", size: :sm, variant: :outline, data: { action: "rapid-rails-ui--steps#back" }) %>
        <%= rui_button("Skip", size: :sm, variant: :ghost, data: { action: "rapid-rails-ui--steps#next" }) %>
        <%= rui_button("Next", size: :sm, data: { action: "rapid-rails-ui--steps#next" }) %>
      </div>
    </div>
  <% end %>

<% steps.with_step("Account") { "..." } %>
  <% steps.with_step("Profile") { "..." } %>
<% end %>
```

#### Stimulus Actions for Custom Buttons

Use these `data-action` values to trigger navigation:

| Action | Stimulus Target | Description |
|--------|-----------------|-------------|
| `rapid-rails-ui--steps#back` | Back button | Go to previous step |
| `rapid-rails-ui--steps#next` | Next button | Go to next step (validates first) |
| `rapid-rails-ui--steps#goToStep` | Jump to step | Requires `data-step` attribute |

```erb
<%# Go to specific step %>
<%= rui_button("Go to Step 2", data: { action: "rapid-rails-ui--steps#goToStep", step: 1 }) %>
```

---

### Combining Slots

Use all three slots together for complete layout control:

```erb
<%= rui_steps(
  id: "onboarding",
  url: onboarding_path,
  current_step: @current_step,
  color: :blue
) do |steps| %>

<%# ========== HEADER ========== %>
  <% steps.with_header do %>
    <div class="flex justify-between items-center pb-4 border-b border-zinc-200 dark:border-zinc-700">
      <div>
        <h2 class="text-xl font-bold text-zinc-900 dark:text-zinc-100">Welcome to Acme</h2>
        <p class="text-sm text-zinc-500">Let's get you set up in just a few steps</p>
      </div>
      <a href="/" class="text-zinc-400 hover:text-zinc-600">
        <svg class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
        </svg>
      </a>
    </div>
  <% end %>

<%# ========== STEPS ========== %>
  <% steps.with_step("Account", icon: :user) do %>
    <div class="py-6 space-y-4">
      <h3 class="text-lg font-medium">Create your account</h3>
      <div>
        <label class="block text-sm font-medium mb-1">Email Address</label>
        <input type="email" name="email" required
               class="block w-full rounded-lg border-zinc-300 shadow-sm" />
      </div>
      <div>
        <label class="block text-sm font-medium mb-1">Password</label>
        <input type="password" name="password" required minlength="8"
               class="block w-full rounded-lg border-zinc-300 shadow-sm" />
      </div>
    </div>
  <% end %>

<% steps.with_step("Profile", icon: :identification) do %>
    <div class="py-6 space-y-4">
      <h3 class="text-lg font-medium">Tell us about yourself</h3>
      <div class="grid grid-cols-2 gap-4">
        <div>
          <label class="block text-sm font-medium mb-1">First Name</label>
          <input type="text" name="first_name" required
                 class="block w-full rounded-lg border-zinc-300 shadow-sm" />
        </div>
        <div>
          <label class="block text-sm font-medium mb-1">Last Name</label>
          <input type="text" name="last_name" required
                 class="block w-full rounded-lg border-zinc-300 shadow-sm" />
        </div>
      </div>
      <div>
        <label class="block text-sm font-medium mb-1">Company (optional)</label>
        <input type="text" name="company"
               class="block w-full rounded-lg border-zinc-300 shadow-sm" />
      </div>
    </div>
  <% end %>

<% steps.with_step("Preferences", icon: :cog_6_tooth) do %>
    <div class="py-6 space-y-4">
      <h3 class="text-lg font-medium">Customize your experience</h3>
      <div class="space-y-3">
        <label class="flex items-center gap-3">
          <input type="checkbox" name="email_updates" checked class="rounded border-zinc-300" />
          <span class="text-sm">Send me product updates via email</span>
        </label>
        <label class="flex items-center gap-3">
          <input type="checkbox" name="tips" checked class="rounded border-zinc-300" />
          <span class="text-sm">Show helpful tips in the app</span>
        </label>
      </div>
    </div>
  <% end %>

<% steps.with_step("Done", icon: :check_circle) do %>
    <div class="py-8 text-center">
      <div class="mx-auto w-16 h-16 bg-green-100 dark:bg-green-900 rounded-full flex items-center justify-center mb-4">
        <svg class="w-8 h-8 text-green-600 dark:text-green-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
        </svg>
      </div>
      <h3 class="text-xl font-semibold text-zinc-900 dark:text-zinc-100">You're all set!</h3>
      <p class="text-zinc-500 dark:text-zinc-400 mt-2">Click "Get Started" to begin using Acme.</p>
    </div>
  <% end %>

<%# ========== FOOTER ========== %>
  <% steps.with_footer do %>
    <div class="flex justify-between items-center text-sm text-zinc-400 pt-4 border-t border-zinc-100 dark:border-zinc-800">
      <span>Your progress is saved automatically</span>
      <a href="/help" class="text-blue-500 hover:underline">Need help?</a>
    </div>
  <% end %>

<% end %>
```

---

### Real-World Slot Patterns

#### Pattern 1: Header with Inline Navigation

Put navigation in the header, hide default buttons:

```erb
<%= rui_steps(
  id: "compact-wizard",
  url: wizard_path,
  buttons_position: :none  <%# Hide default buttons %>
) do |steps| %>
  <% steps.with_header do %>
    <div class="flex justify-between items-center">
      <span class="font-medium text-zinc-700 dark:text-zinc-300">Setup Progress</span>
      <div class="flex gap-2">
        <%= rui_button("Back", size: :sm, variant: :outline, data: { action: "rapid-rails-ui--steps#back" }) %>
        <%= rui_button("Next", size: :sm, data: { action: "rapid-rails-ui--steps#next" }) %>
      </div>
    </div>
  <% end %>

<% steps.with_step("Step 1") { "Content..." } %>
  <% steps.with_step("Step 2") { "Content..." } %>
  <% steps.with_step("Step 3") { "Content..." } %>
<% end %>
```

#### Pattern 2: Wizard in a Modal

Minimal variant with custom footer for modal context:

```erb
<%= rui_dialog(id: "setup-modal", size: :lg) do |dialog| %>
  <% dialog.with_body do %>
    <%= rui_steps(
      id: "modal-wizard",
      url: setup_path,
      variant: :minimal,
      current_step: @step
    ) do |steps| %>
      <% steps.with_step("Connect") do %>
        <div class="py-4">
          <p class="text-zinc-600 mb-4">Connect your account to continue.</p>
          <%= rui_button("Connect with Google", variant: :outline, class: "w-full") %>
        </div>
      <% end %>

<% steps.with_step("Import") do %>
        <div class="py-4">
          <div class="border-2 border-dashed border-zinc-300 rounded-lg p-8 text-center">
            <p class="text-zinc-500">Drag files here or click to browse</p>
          </div>
        </div>
      <% end %>

<% steps.with_step("Done") do %>
        <div class="py-4 text-center">
          <p class="text-green-600 font-medium">Setup complete!</p>
        </div>
      <% end %>

<% steps.with_footer do %>
        <p class="text-xs text-zinc-400 text-center">
          You can always change these settings later.
        </p>
      <% end %>
    <% end %>
  <% end %>
<% end %>
```

#### Pattern 3: Checkout Flow with Custom Actions

E-commerce checkout with contextual buttons:

```erb
<%= rui_steps(
  id: "checkout",
  url: checkout_path,
  variant: :progress,
  color: :emerald
) do |steps| %>
  <% steps.with_header do %>
    <div class="flex justify-between items-center">
      <h2 class="text-lg font-semibold">Checkout</h2>
      <span class="text-sm text-zinc-500">Order #<%= @order.number %></span>
    </div>
  <% end %>

<% steps.with_step("Cart", icon: :shopping_cart) do %>
    <%= render "checkout/cart_summary" %>
  <% end %>

<% steps.with_step("Shipping", icon: :truck) do %>
    <%= render "checkout/shipping_form" %>
  <% end %>

<% steps.with_step("Payment", icon: :credit_card) do %>
    <%= render "checkout/payment_form" %>
  <% end %>

<% steps.with_step("Confirm", icon: :check) do %>
    <%= render "checkout/confirmation" %>
  <% end %>

<% steps.with_footer do %>
    <div class="flex items-center justify-center gap-4 text-sm text-zinc-400">
      <span class="flex items-center gap-1">
        <svg class="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
        </svg>
        Secure checkout
      </span>
      <span>|</span>
      <a href="/help" class="hover:underline">Need help?</a>
    </div>
  <% end %>
<% end %>
```

#### Pattern 4: Registration with Social Login in Footer

```erb
<%= rui_steps(id: "register", url: register_path) do |steps| %>
  <% steps.with_step("Account") do %>
    <div class="space-y-4">
      <div>
        <label class="block text-sm font-medium mb-1">Email</label>
        <input type="email" name="email" required class="w-full rounded-lg border-zinc-300" />
      </div>
      <div>
        <label class="block text-sm font-medium mb-1">Password</label>
        <input type="password" name="password" required class="w-full rounded-lg border-zinc-300" />
      </div>
    </div>
  <% end %>

<% steps.with_step("Verify") do %>
    <div class="text-center py-6">
      <p class="text-zinc-600 mb-4">Enter the code sent to your email</p>
      <input type="text" name="code" maxlength="6" class="w-32 text-center text-2xl tracking-widest rounded-lg border-zinc-300" />
    </div>
  <% end %>

<% steps.with_step("Welcome") do %>
    <div class="text-center py-6">
      <h3 class="text-lg font-medium">Welcome aboard!</h3>
      <p class="text-zinc-500 mt-2">Your account is ready.</p>
    </div>
  <% end %>

<% steps.with_footer do %>
    <div class="pt-6 border-t border-zinc-200 dark:border-zinc-700">
      <p class="text-center text-sm text-zinc-500 mb-4">Or continue with</p>
      <div class="flex justify-center gap-3">
        <%= rui_button("Google", variant: :outline, size: :sm) %>
        <%= rui_button("GitHub", variant: :outline, size: :sm) %>
        <%= rui_button("Apple", variant: :outline, size: :sm) %>
      </div>
    </div>
  <% end %>
<% end %>
```

---

## Variants

### Horizontal (Default)

Inline layout with circles, titles, and connectors in a row. Best for 3-5 steps.

```erb
<%= rui_steps(
  id: "horizontal-demo",
  url: wizard_path,
  variant: :horizontal,
  current_step: 1
) do |steps| %>
  <% steps.with_step("Account") do %>
    <h3 class="text-lg font-medium">Create Your Account</h3>
    <p class="text-zinc-500 mt-2">Enter your email and password.</p>
  <% end %>

<% steps.with_step("Profile") do %>
    <h3 class="text-lg font-medium">Set Up Your Profile</h3>
    <p class="text-zinc-500 mt-2">Tell us about yourself.</p>
  <% end %>

<% steps.with_step("Settings") do %>
    <h3 class="text-lg font-medium">Configure Settings</h3>
    <p class="text-zinc-500 mt-2">Customize your experience.</p>
  <% end %>

<% steps.with_step("Confirm") do %>
    <h3 class="text-lg font-medium">Review & Submit</h3>
    <p class="text-zinc-500 mt-2">Confirm your information.</p>
  <% end %>
<% end %>
```

### Vertical

Sidebar navigation on left, content on right. Best for complex wizards with descriptions.

```erb
<%= rui_steps(
  id: "vertical-demo",
  url: wizard_path,
  variant: :vertical,
  current_step: 0
) do |steps| %>
  <% steps.with_step("Personal Info", description: "Your basic details") do %>
    <h3 class="text-xl font-semibold">Personal Information</h3>
    <div class="grid grid-cols-2 gap-4 mt-4">
      <div>
        <label class="block text-sm font-medium">First Name</label>
        <input type="text" name="first_name" class="mt-1 block w-full rounded-md border-zinc-300" />
      </div>
      <div>
        <label class="block text-sm font-medium">Last Name</label>
        <input type="text" name="last_name" class="mt-1 block w-full rounded-md border-zinc-300" />
      </div>
    </div>
  <% end %>

<% steps.with_step("Contact", description: "How to reach you") do %>
    <h3 class="text-xl font-semibold">Contact Information</h3>
    
  <% end %>

<% steps.with_step("Address", description: "Where you live") do %>
    <h3 class="text-xl font-semibold">Address</h3>
    
  <% end %>

<% steps.with_step("Review", description: "Confirm details") do %>
    <h3 class="text-xl font-semibold">Review Your Information</h3>
  <% end %>
<% end %>
```

### Minimal

Simple "Step X of Y: Title" header. Best for dialogs and modals.

```erb
<%= rui_steps(
  id: "minimal-demo",
  url: wizard_path,
  variant: :minimal,
  current_step: 0
) do |steps| %>
  <% steps.with_step("Connect Account") do %>
    <p class="text-zinc-600">Connect your account to get started.</p>
    <button type="button" class="mt-4 px-4 py-2 bg-blue-600 text-white rounded-md">
      Connect with Google
    </button>
  <% end %>

<% steps.with_step("Import Data") do %>
    <div class="border-2 border-dashed border-zinc-300 rounded-lg p-8 text-center">
      <p>Drag and drop files here</p>
    </div>
  <% end %>

<% steps.with_step("Finish") do %>
    <div class="text-center">
      <h3 class="text-lg font-medium">All Done!</h3>
    </div>
  <% end %>
<% end %>
```

### Progress

Icon-only circles with thick connectors. Compact design for headers.

```erb
<%= rui_steps(
  id: "progress-demo",
  url: checkout_path,
  variant: :progress,
  current_step: 1
) do |steps| %>
  <% steps.with_step("Cart", icon: :shopping_cart) do %>
    <h3 class="text-xl font-semibold">Your Cart</h3>
  <% end %>

<% steps.with_step("Shipping", icon: :truck) do %>
    <h3 class="text-xl font-semibold">Shipping Address</h3>
  <% end %>

<% steps.with_step("Payment", icon: :credit_card) do %>
    <h3 class="text-xl font-semibold">Payment Method</h3>
  <% end %>

<% steps.with_step("Confirm", icon: :check) do %>
    <h3 class="text-xl font-semibold">Order Confirmed!</h3>
  <% end %>
<% end %>
```

### Breadcrumb

Compact chevron-separated badges. Best for navigation-style progress.

```erb
<%= rui_steps(
  id: "breadcrumb-demo",
  url: onboarding_path,
  variant: :breadcrumb,
  navigation: :free,
  current_step: 1
) do |steps| %>
  <% steps.with_step("Account") { "Account setup content" } %>
  <% steps.with_step("Preferences") { "Preferences content" } %>
  <% steps.with_step("Theme") { "Theme selection" } %>
  <% steps.with_step("Complete") { "Setup complete!" } %>
<% end %>
```

### Timeline

Vertical timeline with left border spine. Best for process flows.

```erb
<%= rui_steps(
  id: "timeline-demo",
  url: application_path,
  variant: :timeline,
  current_step: 2
) do |steps| %>
  <% steps.with_step("Application Submitted", description: "Jan 15, 2024") do %>
    <p class="text-zinc-600">Your application has been received.</p>
  <% end %>

<% steps.with_step("Documents Reviewed", description: "Jan 18, 2024") do %>
    <p class="text-zinc-600">All required documents verified.</p>
  <% end %>

<% steps.with_step("Interview Scheduled", description: "Jan 22, 2024") do %>
    <p class="text-zinc-600">Your interview is scheduled.</p>
  <% end %>

<% steps.with_step("Decision Pending", description: "Estimated: Jan 30") do %>
    <p class="text-zinc-500">Awaiting final decision.</p>
  <% end %>
<% end %>
```

### Vertical Cards

Alert-style bordered cards stacked vertically. Best for clickable step selection.

```erb
<%= rui_steps(
  id: "cards-demo",
  url: setup_path,
  variant: :vertical_cards,
  navigation: :free,
  current_step: 0,
  color: :purple
) do |steps| %>
  <% steps.with_step("Connect Account", description: "Link your existing account", icon: :link) do %>
    <h3 class="text-lg font-medium">Connect Account</h3>
    <div class="mt-4 grid grid-cols-2 gap-4">
      <button type="button" class="p-4 border rounded-lg text-left hover:bg-zinc-50">
        <strong>Google</strong>
        <p class="text-sm text-zinc-500">Connect with Google</p>
      </button>
      <button type="button" class="p-4 border rounded-lg text-left hover:bg-zinc-50">
        <strong>GitHub</strong>
        <p class="text-sm text-zinc-500">Connect with GitHub</p>
      </button>
    </div>
  <% end %>

<% steps.with_step("Import Data", description: "Bring in your content", icon: :arrow_down_tray) do %>
    <div class="border-2 border-dashed border-zinc-300 rounded-lg p-8 text-center">
      <p class="text-zinc-500">Drag and drop files here</p>
    </div>
  <% end %>

<% steps.with_step("All Done!", description: "You're ready to go") do %>
    <div class="text-center">
      <h3 class="text-lg font-medium">Setup Complete!</h3>
    </div>
  <% end %>
<% end %>
```

---

## Sizes

Control the size of step indicators.

| Size | Circle | Description |
|------|--------|-------------|
| `:sm` | 32px (w-8) | Compact, small text |
| `:md` | 40px (w-10) | Default size |
| `:lg` | 48px (w-12) | Large, prominent |

```erb
<%# Small %>
<%= rui_steps(id: "sm", url: path, size: :sm) do |steps| %>
  <% steps.with_step("Step 1") { "Small indicators" } %>
  <% steps.with_step("Step 2") { "Compact design" } %>
<% end %>

<%# Medium (default) %>
<%= rui_steps(id: "md", url: path, size: :md) do |steps| %>
  <% steps.with_step("Step 1") { "Default size" } %>
  <% steps.with_step("Step 2") { "Balanced appearance" } %>
<% end %>

<%# Large %>
<%= rui_steps(id: "lg", url: path, size: :lg) do |steps| %>
  <% steps.with_step("Step 1") { "Large indicators" } %>
  <% steps.with_step("Step 2") { "Maximum visibility" } %>
<% end %>
```

---

## Colors

Customize the theme color for active steps. Completed steps always use green. Error steps always use red.

| Category | Colors |
|----------|--------|
| Semantic | `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info` |
| Tailwind | `:blue`, `:green`, `:red`, `:purple`, `:pink`, `:amber`, `:cyan`, `:indigo`, `:teal`, `:orange`, `:rose`, `:violet`, `:emerald`, `:sky`, `:lime`, `:fuchsia` |

```erb
<%# Blue theme %>
<%= rui_steps(id: "blue", url: path, color: :blue) do |steps| %>
  <% steps.with_step("Account") { "Blue theme" } %>
  <% steps.with_step("Profile") { "Active step is blue" } %>
<% end %>

<%# Purple theme %>
<%= rui_steps(id: "purple", url: path, color: :purple) do |steps| %>
  <% steps.with_step("Start") { "Purple theme" } %>
  <% steps.with_step("Finish") { "Elegant purple" } %>
<% end %>

<%# Danger theme (for destructive flows) %>
<%= rui_steps(id: "danger", url: path, color: :danger) do |steps| %>
  <% steps.with_step("Warning") { "Danger/red theme" } %>
  <% steps.with_step("Confirm") { "Deletion wizard" } %>
<% end %>
```

---

## Navigation Modes

| Mode | Description |
|------|-------------|
| `:linear` | Only Back/Next buttons work. Indicators not clickable. |
| `:free` | All step indicators are clickable. Jump to any step. |
| `:completed_only` | Can click completed steps and current+1. Cannot skip ahead. |

```erb
<%# Linear (default) - must use buttons %>
<%= rui_steps(id: "linear", url: path, navigation: :linear) do |steps| %>
  <% steps.with_step("Step 1") { "Must complete in order" } %>
  <% steps.with_step("Step 2") { "Use Back/Next only" } %>
<% end %>

<%# Free - click any step %>
<%= rui_steps(id: "free", url: path, navigation: :free) do |steps| %>
  <% steps.with_step("Step 1") { "Click any step to jump" } %>
  <% steps.with_step("Step 2") { "Full freedom" } %>
<% end %>

<%# Completed only - can go back, not skip ahead %>
<%= rui_steps(id: "completed", url: path, navigation: :completed_only) do |steps| %>
  <% steps.with_step("Step 1") { "Can revisit completed steps" } %>
  <% steps.with_step("Step 2") { "Cannot skip ahead" } %>
<% end %>
```

---

## Position Options

Control placement of indicators and buttons (horizontal variant).

```erb
<%# Default: indicators top, buttons bottom %>
<%= rui_steps(id: "default", url: path, indicators_position: :top, buttons_position: :bottom) do |steps| %>
  <% steps.with_step("Step 1") { "Default layout" } %>
<% end %>

<%# Flipped: buttons top, indicators bottom %>
<%= rui_steps(id: "flipped", url: path, indicators_position: :bottom, buttons_position: :top) do |steps| %>
  <% steps.with_step("Step 1") { "Flipped layout" } %>
<% end %>

<%# Hide indicators %>
<%= rui_steps(id: "no-ind", url: path, indicators_position: :none) do |steps| %>
  <% steps.with_step("Step 1") { "No indicators" } %>
<% end %>

<%# Hide buttons (use with navigation: :free) %>
<%= rui_steps(id: "no-btn", url: path, buttons_position: :none, navigation: :free) do |steps| %>
  <% steps.with_step("Step 1") { "Click indicators to navigate" } %>
<% end %>

<%# Hide both (provide your own UI) %>
<%= rui_steps(id: "none", url: path, indicators_position: :none, buttons_position: :none) do |steps| %>
  <% steps.with_step("Step 1") do %>
    <p>Provide your own navigation</p>
    <button type="submit">Custom Button</button>
  <% end %>
<% end %>
```

---

## Icons

Use icons instead of step numbers. Common icons:

```erb
<%# Account/User steps %>
<% steps.with_step("Account", icon: :user) { "..." } %>
<% steps.with_step("Profile", icon: :user_circle) { "..." } %>
<% steps.with_step("Identity", icon: :identification) { "..." } %>

<%# Shopping/Checkout %>
<% steps.with_step("Cart", icon: :shopping_cart) { "..." } %>
<% steps.with_step("Payment", icon: :credit_card) { "..." } %>
<% steps.with_step("Shipping", icon: :truck) { "..." } %>

<%# Settings %>
<% steps.with_step("Settings", icon: :cog_6_tooth) { "..." } %>
<% steps.with_step("Preferences", icon: :adjustments_horizontal) { "..." } %>

<%# Documents %>
<% steps.with_step("Upload", icon: :arrow_up_tray) { "..." } %>
<% steps.with_step("Download", icon: :arrow_down_tray) { "..." } %>
<% steps.with_step("Review", icon: :document_text) { "..." } %>

<%# Security %>
<% steps.with_step("Security", icon: :shield_check) { "..." } %>
<% steps.with_step("Lock", icon: :lock_closed) { "..." } %>

<%# Confirmation %>
<% steps.with_step("Confirm", icon: :check) { "..." } %>
<% steps.with_step("Complete", icon: :check_circle) { "..." } %>
```

---

## Custom Button Text

```erb
<%= rui_steps(
  id: "custom",
  url: path,
  back_text: "Previous",
  next_text: "Continue",
  submit_text: "Finish Setup",
  loading_text: "Processing..."
) do |steps| %>
  <% steps.with_step("Step 1") { "Back shows 'Previous'" } %>
  <% steps.with_step("Step 2") { "Next shows 'Continue'" } %>
  <% steps.with_step("Step 3") { "Last step shows 'Finish Setup'" } %>
<% end %>
```

### Localization

```erb
<%= rui_steps(
  id: "i18n",
  url: path,
  back_text: t("wizard.back"),
  next_text: t("wizard.next"),
  submit_text: t("wizard.submit"),
  loading_text: t("wizard.loading")
) do |steps| %>
  <% steps.with_step(t("wizard.step1")) { "..." } %>
  <% steps.with_step(t("wizard.step2")) { "..." } %>
<% end %>
```

---

## Error Handling

```erb
<%= rui_steps(
  id: "errors",
  url: path,
  current_step: @current_step,
  error_step: @error_step  <%# Pass step index with error %>
) do |steps| %>
  <% steps.with_step("Account") do %>
    <% if @error_step == 0 %>
      <div class="p-4 bg-red-50 border border-red-200 rounded-lg mb-4">
        <p class="text-red-600">Please fix the errors below.</p>
      </div>
    <% end %>
    <div>
      <label class="block text-sm font-medium">Email</label>
      <input type="email" name="email" value="<%= @user.email %>"
             class="<%= @user.errors[:email].any? ? 'border-red-500' : 'border-zinc-300' %>" />
      <% if @user.errors[:email].any? %>
        <p class="text-sm text-red-600"><%= @user.errors[:email].first %></p>
      <% end %>
    </div>
  <% end %>
<% end %>
```

### Controller Pattern

```ruby
def update
  case params[:direction]
  when "next"
    if @wizard.valid_for_step?(@wizard.current_step)
      @wizard.increment!(:current_step)
      @error_step = nil
    else
      @error_step = @wizard.current_step
    end
  when "back"
    @wizard.decrement!(:current_step)
    @error_step = nil
  end

render :show
end
```

---

## Caching & Validation

### LocalStorage Caching

```erb
<%# Enable (default) %>
<%= rui_steps(id: "cached", url: path, cache_locally: true) do |steps| %>
  <% steps.with_step("Step 1") { "Progress saved in LocalStorage" } %>
<% end %>

<%# Disable %>
<%= rui_steps(id: "no-cache", url: path, cache_locally: false) do |steps| %>
  <% steps.with_step("Step 1") { "Always uses server state" } %>
<% end %>
```

Storage key: `rui_steps_{id}_current`

### Client Validation

```erb
<%# Enable (default) - HTML5 validation before next %>
<%= rui_steps(id: "validated", url: path, client_validation: true) do |steps| %>
  <% steps.with_step("Step 1") do %>
    <input type="email" name="email" required />
    <%# Must be valid to proceed %>
  <% end %>
<% end %>

<%# Disable %>
<%= rui_steps(id: "no-val", url: path, client_validation: false) do |steps| %>
  <% steps.with_step("Step 1") do %>
    <input type="email" name="email" required />
    <%# Can proceed without validation %>
  <% end %>
<% end %>
```

---

## Controller Setup

### Basic Controller

```ruby
class WizardsController < ApplicationController
  before_action :set_wizard

def show
    @current_step = @wizard.current_step
  end

def update
    case params[:direction]
    when "next"
      handle_next_step
    when "back"
      @wizard.decrement!(:current_step) if @wizard.current_step > 0
    when /^goto:(\d+)$/
      handle_goto_step($1.to_i)
    end

respond_to do |format|
      format.turbo_stream
      format.html { render :show }
    end
  end

private

def set_wizard
    @wizard = Wizard.find_or_create_by(session_id: session.id)
    @current_step = @wizard.current_step
  end

def handle_next_step
    if @wizard.valid_for_step?(@wizard.current_step)
      if @wizard.current_step == @wizard.total_steps - 1
        @wizard.complete!
        redirect_to wizard_complete_path
      else
        @wizard.increment!(:current_step)
      end
    else
      @error_step = @wizard.current_step
    end
  end

def handle_goto_step(target)
    @wizard.update!(current_step: target) if can_navigate_to?(target)
  end

def can_navigate_to?(step)
    case @wizard.navigation_mode
    when "free" then true
    when "completed_only" then step <= @wizard.current_step + 1
    else false
    end
  end
end
```

### Turbo Stream Response

```erb
<%# app/views/wizards/update.turbo_stream.erb %>
<%= turbo_stream.replace "wizard-step-content" do %>
  <%= render partial: "step_#{@current_step}" %>
<% end %>
```

---

## Stimulus Controller

### Values

| Value | Type | Description |
|-------|------|-------------|
| `current` | Number | Current step index |
| `total` | Number | Total number of steps |
| `navigation` | String | Navigation mode |
| `cacheLocally` | Boolean | Cache in LocalStorage |
| `storageKey` | String | LocalStorage key |
| `clientValidation` | Boolean | Validate before transitions |
| `errorStep` | Number | Step with error (-1 if none) |

### Actions

| Action | Description |
|--------|-------------|
| `next` | Go to next step (validates first) |
| `back` | Go to previous step |
| `goToStep` | Jump to specific step |
| `handleKeydown` | Keyboard navigation |

### Public Methods

```javascript
// Get controller reference
const controller = this.application.getControllerForElementAndIdentifier(
  document.getElementById("wizard-id"),
  "rapid-rails-ui--steps"
);

// Error management
controller.setError(2);      // Mark step 2 as error
controller.clearError(2);    // Clear error from step 2
controller.clearAllErrors(); // Clear all errors

// Storage
controller.clearStorage();   // Clear LocalStorage cache
```

### Events

| Event | Description |
|-------|-------------|
| `before-navigate` | Before step transition |
| `after-navigate` | After step transition |
| `step-changed` | When step changes |
| `validation-failed` | When validation fails |
| `error-set` | When error state is set |
| `error-cleared` | When error is cleared |

```javascript
// Listen for events
element.addEventListener("step-changed", (event) => {
  console.log("Step changed to:", event.detail.step);
});
```

---

## Accessibility

### ARIA Attributes

- `<nav aria-label="Progress">` for step navigation
- `<ol role="list">` for semantic step list
- `aria-current="step"` on active step indicator
- `aria-disabled="true"` on locked steps
- `aria-labelledby` on content referencing step title
- `aria-hidden="true"` on decorative SVG icons

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus between elements |
| `Enter` / `Space` | Activate focused step indicator |
| `Arrow Left/Up` | Focus previous step |
| `Arrow Right/Down` | Focus next step |
| `Home` | Focus first step |
| `End` | Focus last step |

---

## Common Patterns

### Multi-page Wizard with Partials

```erb
<%# app/views/wizards/show.html.erb %>
<%= rui_steps(
  id: "wizard",
  url: wizard_path,
  current_step: @current_step
) do |steps| %>
  <% steps.with_step("Account") do %>
    <%= render "wizards/steps/account" %>
  <% end %>

<% steps.with_step("Profile") do %>
    <%= render "wizards/steps/profile" %>
  <% end %>

<% steps.with_step("Confirm") do %>
    <%= render "wizards/steps/confirm" %>
  <% end %>
<% end %>
```

### Wizard with Form Object

```ruby
# app/forms/registration_form.rb
class RegistrationForm
  include ActiveModel::Model

attr_accessor :email, :password, :name, :bio

validates :email, :password, presence: true, on: :step_0
  validates :name, presence: true, on: :step_1

def valid_for_step?(step)
    valid?(:"step_#{step}")
  end
end
```

### Wizard with Turbo Frames

```erb
<%= rui_steps(
  id: "ajax-wizard",
  url: wizard_path,
  turbo_frame_id: "wizard-content"
) do |steps| %>
  <% steps.with_step("Step 1") do %>
    <%= turbo_frame_tag "wizard-content" do %>
      <%= render "step_1_content" %>
    <% end %>
  <% end %>
<% end %>
```

---

## Troubleshooting

### Step title is required error

```erb
<%# Wrong - missing title %>
<% steps.with_step(icon: :user) { "Content" } %>

<%# Correct - include title %>
<% steps.with_step("Account", icon: :user) { "Content" } %>
```

### Custom navigation buttons not working

Ensure you include the correct Stimulus action:

```erb
<%# Wrong - missing data-action %>
<%= rui_button("Next") %>

<%# Correct - include Stimulus action %>
<%= rui_button("Next", data: { action: "rapid-rails-ui--steps#next" }) %>
```

### Slots not rendering

Slots must be called within the block:

```erb
<%# Wrong - outside block %>
<% steps.with_header { "Header" } %>
<%= rui_steps(id: "w", url: path) do |steps| %>
  ...
<% end %>

<%# Correct - inside block %>
<%= rui_steps(id: "w", url: path) do |steps| %>
  <% steps.with_header { "Header" } %>
  ...
<% end %>
```

### Description not showing

Descriptions only render in `vertical`, `timeline`, and `vertical_cards` variants:

```erb
<%# Description won't show (horizontal variant) %>
<%= rui_steps(id: "w", url: path, variant: :horizontal) do |steps| %>
  <% steps.with_step("Step", description: "Won't show") { "..." } %>
<% end %>

<%# Description will show (vertical variant) %>
<%= rui_steps(id: "w", url: path, variant: :vertical) do |steps| %>
  <% steps.with_step("Step", description: "Will show") { "..." } %>
<% end %>
```

### Indicators not clickable

Set `navigation: :free` or `:completed_only`:

```erb
<%# Indicators not clickable (linear mode) %>
<%= rui_steps(id: "w", url: path, navigation: :linear) do |steps| %>

<%# Indicators clickable %>
<%= rui_steps(id: "w", url: path, navigation: :free) do |steps| %>
```

---

## Table (`rui_table`)

# Table Component

A flexible data table component with sorting, selection, pagination, and responsive behavior.

## Collection Mode (Recommended)

Pass a collection as the first argument. The table iterates internally — no manual `each` loop needed.

### Basic

```erb
<%= rui_table(@users) do |table| %>
  <% table.column(:name) %>
  <% table.column(:email) %>
<% end %>
```

### Custom Cell Content

Use a block to customize how a column renders. The block receives the record.

```erb
<%= rui_table(@users) do |table| %>
  <% table.column(:name) %>
  <% table.column(:role) { |user| rui_badge(text: user.role, color: :primary) } %>
  <% table.column(:actions, label: "Actions") do |user| %>
    <%= link_to "Edit", edit_user_path(user) %>
  <% end %>
<% end %>
```

### With Formatters

```erb
<%= rui_table(@users) do |table| %>
  <% table.column(:name) %>
  <% table.column(:balance, formatter: :currency) %>
  <% table.column(:created_at, formatter: :date) %>
<% end %>
```

### With Features

```erb
<%= rui_table(@users, striped: true, selectable: true, id_method: :uuid) do |table| %>
  <% table.column(:name, sortable: true) %>
  <% table.column(:email) %>
  <% table.column(:balance, formatter: :currency) %>
<% end %>
```

### Row Colors

Apply conditional colors per row using a Proc:

```erb
<%= rui_table(@users, row_color: ->(u) { :danger if u.archived? }) do |table| %>
  <% table.column(:name) %>
  <% table.column(:email) %>
<% end %>
```

Or apply a static color to all rows:

```erb
<%= rui_table(@users, row_color: :success) do |table| %>
  <% table.column(:name) %>
<% end %>
```

### With Pagination

```erb
<%# Controller: @page_info, @users = rui_paginate(User.all) %>
<%= rui_table(@users, pagy: @page_info, turbo_frame: "users_table") do |table| %>
  <% table.column(:name, sortable: true) %>
  <% table.column(:email) %>
<% end %>
```

---

## Slot Mode (Manual Iteration)

For full control, use the slot-based API with `with_column`, `with_row`, and `with_cell`.

### Basic Usage

```erb
<%= rui_table(striped: true, hoverable: true) do |table| %>
  <% table.with_column(key: :name, label: "Name") %>
  <% table.with_column(key: :email, label: "Email") %>
  <% table.with_column(key: :role, label: "Role") %>

<% @users.each do |user| %>
    <% table.with_row(id: user.id) do |row| %>
      <% row.with_cell { user.name } %>
      <% row.with_cell { user.email } %>
      <% row.with_cell { rui_badge(text: user.role) } %>
    <% end %>
  <% end %>
<% end %>
```

## With Sorting

### Client-Side Sorting (Default)

Clicking column headers sorts rows in the browser without a server request:

```erb
<%= rui_table(sortable: true) do |table| %>
  <% table.with_column(key: :name, label: "Name", sortable: true) %>
  <% table.with_column(key: :email, label: "Email", sortable: true) %>
  <% table.with_column(key: :created_at, label: "Created", sortable: true) %>

<% @users.each do |user| %>
    <% table.with_row(id: user.id) do |row| %>
      <% row.with_cell { user.name } %>
      <% row.with_cell { user.email } %>
      <% row.with_cell { user.created_at.strftime("%b %d, %Y") } %>
    <% end %>
  <% end %>
<% end %>
```

### Server-Side Sorting with Turbo Frame

For larger datasets, sort on the server with Turbo Frame updates:

```erb
<%= turbo_frame_tag "users_table" do %>
  <%= rui_table(
    sortable: true,
    turbo_frame: "users_table",
    sort_column: params[:sort],
    sort_direction: params[:direction]
  ) do |table| %>
    <% table.with_column(key: :name, label: "Name", sortable: true) %>
    <% table.with_column(key: :email, label: "Email", sortable: true) %>

<% @users.each do |user| %>
      <% table.with_row(id: user.id) do |row| %>
        <% row.with_cell { user.name } %>
        <% row.with_cell { user.email } %>
      <% end %>
    <% end %>
  <% end %>
<% end %>
```

### Server-Side Sorting with Custom URL

Use `sort_url` to specify a different endpoint for sorting:

```erb
<%= rui_table(
  sortable: true,
  sort_url: users_path,
  sort_column: params[:sort],
  sort_direction: params[:direction]
) do |table| %>
  <% table.with_column(key: :name, label: "Name", sortable: true) %>
  <% table.with_column(key: :email, label: "Email", sortable: true) %>

<% @users.each do |user| %>
    <% table.with_row(id: user.id) do |row| %>
      <% row.with_cell { user.name } %>
      <% row.with_cell { user.email } %>
    <% end %>
  <% end %>
<% end %>
```

```ruby
# Controller
def index
  @users = User.all
  @users = @users.order("#{params[:sort]} #{params[:direction]}") if params[:sort].present?
end
```

## With Row Selection

```erb
<%= rui_table(selectable: true) do |table| %>
  <% table.with_column(key: :name, label: "Name") %>
  <% table.with_column(key: :email, label: "Email") %>

<% table.with_bulk_actions do %>
    <%= rui_button("Delete Selected", color: :danger, size: :sm) %>
    <%= rui_button("Export", variant: :outline, size: :sm) %>
  <% end %>

<% @users.each do |user| %>
    <% table.with_row(id: user.id) do |row| %>
      <% row.with_cell { user.name } %>
      <% row.with_cell { user.email } %>
    <% end %>
  <% end %>
<% end %>
```

## With Toolbar

Add search, filters, and action buttons above the table:

```erb
<%= rui_table do |table| %>
  <% table.with_toolbar do %>
    <%= rui_input(
      name: :search,
      type: :search,
      placeholder: "Search users...",
      validation: false,
      class: "w-64"
    ) %>
    <%= rui_dropdown(label: "Status") do |d| %>
      <% d.with_item { "Active" } %>
      <% d.with_item { "Inactive" } %>
      <% d.with_item { "All" } %>
    <% end %>
    <div class="ml-auto">
      <%= rui_button("Add User", color: :primary) %>
    </div>
  <% end %>

<% table.with_column(key: :name, label: "Name") %>
  <% table.with_column(key: :email, label: "Email") %>
  <% table.with_column(key: :status, label: "Status") %>

## With Pagination

The Table component integrates with the Pagination component for full-featured pagination:

```erb
<%= turbo_frame_tag "users_table" do %>
  <%= rui_table(pagy: @pagy, turbo_frame: "users_table") do |table| %>
    <% table.with_column(key: :name, label: "Name") %>
    <% table.with_column(key: :email, label: "Email") %>

```ruby
# Controller
def index
  @pagy, @users = rui_paginate(User.all)
end
```

The pagination displays:
- "Showing X-Y of Z" info text
- Previous/Next navigation buttons
- Page number links with ellipsis for large page counts
- Turbo Frame support for AJAX pagination

### Standalone Pagination

For more control, use the Pagination component directly:

```erb
<%= rui_table do |table| %>
  <%# ... columns and rows ... %>
<% end %>

<%= rui_pagination(
  pagy: @pagy,
  turbo_frame: "users_table",
  variant: :full,        # Show first/last buttons
  show_per_page: true,   # Show per-page selector
  per_page_options: [10, 25, 50, 100]
) %>
```

## Loading State

```erb
<%= rui_table(loading: true, loading_rows: 5) do |table| %>
  <% table.with_column(key: :name, label: "Name") %>
  <% table.with_column(key: :email, label: "Email") %>
  <% table.with_column(key: :role, label: "Role") %>
<% end %>
```

## Custom Empty State

```erb
<%= rui_table do |table| %>
  <% table.with_column(key: :name, label: "Name") %>

<% table.with_empty_state do %>
    <%= rui_empty_state(
      title: "No users found",
      description: "Try adjusting your search filters"
    ) %>
  <% end %>
<% end %>
```

## Responsive Modes

```erb
<%# Cards view on mobile %>
<%= rui_table(responsive_mode: :cards) do |table| %>
  <%# ... %>
<% end %>

<%# Stacked view on mobile %>
<%= rui_table(responsive_mode: :stack) do |table| %>
  <%# ... %>
<% end %>

<%# Horizontal scroll (default) %>
<%= rui_table(responsive_mode: :scroll) do |table| %>
  <%# ... %>
<% end %>
```

## Variants

```erb
<%# Striped rows %>
<%= rui_table(striped: true) %>

<%# With borders %>
<%= rui_table(bordered: true) %>

<%# Sticky header %>
<%= rui_table(sticky_header: true) %>

<%# Combined %>
<%= rui_table(striped: true, bordered: true, hoverable: true, sticky_header: true) %>
```

## Sizes

```erb
<%= rui_table(size: :xs) %>  <%# Extra small %>
<%= rui_table(size: :sm) %>  <%# Small %>
<%= rui_table(size: :base) %> <%# Default %>
<%= rui_table(size: :lg) %>  <%# Large %>
<%= rui_table(size: :xl) %>  <%# Extra large %>
```

## Column Alignment

```erb
<%= rui_table do |table| %>
  <% table.with_column(key: :name, label: "Name", align: :left) %>
  <% table.with_column(key: :status, label: "Status", align: :center) %>
  <% table.with_column(key: :amount, label: "Amount", align: :right) %>
<% end %>
```

## Column Width

```erb
<%= rui_table do |table| %>
  <% table.with_column(key: :name, label: "Name", width: "200px") %>
  <% table.with_column(key: :description, label: "Description", width: "50%") %>
  <% table.with_column(key: :actions, label: "", width: "100px") %>
<% end %>
```

## Column Formatters

Formatters automatically transform cell values for display. Available built-in formatters:

| Formatter | Description | Example Output |
|-----------|-------------|----------------|
| `:date` | Format Date/DateTime | "Jan 05, 2026" |
| `:datetime` | Format with time | "Jan 05, 2026 02:30 PM" |
| `:time` | Time only | "02:30 PM" |
| `:relative_time` | Relative time | "2 hours ago" |
| `:currency` | Currency formatting | "$1,234.56" |
| `:number` | Number with delimiter | "1,234,567" |
| `:percentage` | Percentage | "75.5%" |
| `:boolean` | True/false icons | ✓ / ✗ |
| `:truncate` | Truncate long text | "Lorem ipsum..." |
| `:badge` | Wrap in badge | Badge component |

### Using Formatters on Columns (Data-Driven)

When using `data:` on rows, cells are auto-generated with formatters applied:

```erb
<%= rui_table do |table| %>
  <% table.with_column(key: :name, label: "Name") %>
  <% table.with_column(key: :created_at, label: "Created", formatter: :date) %>
  <% table.with_column(key: :balance, label: "Balance", formatter: :currency) %>
  <% table.with_column(key: :active, label: "Active", formatter: :boolean) %>

<% @users.each do |user| %>
    <% table.with_row(data: user) %>
  <% end %>
<% end %>
```

### Using Formatters with Options

```erb
<% table.with_column(key: :bio, label: "Bio", formatter: { type: :truncate, length: 50 }) %>
<% table.with_column(key: :price, label: "Price", formatter: { type: :currency, unit: "€" }) %>
<% table.with_column(key: :date, label: "Date", formatter: { type: :date, format: :short }) %>
```

### Using format_value Helper in Blocks

For manual cell content with formatting:

```erb
<%= rui_table do |table| %>
  <% table.with_column(key: :name, label: "Name") %>
  <% table.with_column(key: :amount, label: "Amount") %>
  <% table.with_column(key: :created, label: "Created") %>

<% @users.each do |user| %>
    <% table.with_row(id: user.id) do |row| %>
      <% row.with_cell { user.name } %>
      <% row.with_cell { row.format_value(user.amount, :currency) } %>
      <% row.with_cell { row.format_value(user.created_at, :date) } %>
    <% end %>
  <% end %>
<% end %>
```

### Custom Formatters with Proc

```erb
<% table.with_column(
  key: :status,
  label: "Status",
  formatter: ->(val) { val.titleize }
) %>
```

## Row Colors

```erb
<%= rui_table do |table| %>
  <% @items.each do |item| %>
    <% table.with_row(id: item.id, color: item.urgent? ? :danger : nil) do |row| %>
      <% row.with_cell { item.name } %>
    <% end %>
  <% end %>
<% end %>
```

## JavaScript Events

The table controller dispatches these events:

```javascript
// Selection changed
document.addEventListener("table:selection", (event) => {
  console.log("Selected IDs:", event.detail.selectedIds)
  console.log("Count:", event.detail.count)
})

// Sort changed
document.addEventListener("table:sort", (event) => {
  console.log("Column:", event.detail.column)
  console.log("Direction:", event.detail.direction)
})
```

## Props Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `collection` | Array/Relation | nil | First positional arg — enables collection mode |
| `id` | String | auto | Unique identifier for the table |
| `id_method` | Symbol | :id | Method/key to extract row ID from each record |
| `row_color` | Proc/Symbol | nil | Row color — Proc receives record, returns color Symbol or nil |
| `sortable` | Boolean | false | Enable column sorting |
| `selectable` | Boolean | false | Enable row selection |
| `striped` | Boolean | false | Alternate row backgrounds |
| `striped_columns` | Boolean | false | Alternate column backgrounds |
| `hoverable` | Boolean | true | Highlight rows on hover |
| `bordered` | Boolean | true | Add outer border and vertical borders between cells |
| `headless` | Boolean | false | Hide the table header (thead) |
| `size` | Symbol | :base | Size variant (:xs, :sm, :base, :lg, :xl) |
| `shape` | Symbol | :rounded | Corner shape (:rounded, :square) |
| `sticky_header` | Boolean | false | Make header sticky when scrolling |
| `sticky_max_height` | String | "24rem" | Max height for sticky scrollable area |
| `pagy` | PageInfo | nil | PageInfo from rui_paginate for pagination info |
| `responsive` | Boolean | true | Enable responsive behavior |
| `responsive_mode` | Symbol | :scroll | Mobile display mode (:scroll, :cards, :stack) |
| `loading` | Boolean | false | Show skeleton loading state |
| `loading_rows` | Integer | 5 | Number of skeleton rows |
| `empty_message` | String | "No data found" | Default empty state message |
| `turbo_frame` | String | nil | Turbo Frame ID for AJAX updates |
| `sort_column` | String | nil | Current sort column key |
| `sort_direction` | String | nil | Current sort direction (asc/desc) |
| `sort_url` | String | nil | Base URL for server-side sorting (appends ?sort=&direction=) |
| `client_sort` | Boolean | auto | Enable client-side sorting (default: true unless sort_url or turbo_frame set) |
| `title` | String | nil | Visible caption title above table |
| `description` | String | nil | Visible caption description below title |

### Column Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `key` | Symbol | required | Column identifier (used for sorting and data extraction) |
| `label` | String | titleized key | Header text |
| `sortable` | Boolean | false | Enable sorting for this column |
| `width` | String | nil | CSS width (e.g., "200px", "25%") |
| `align` | Symbol | :left | Text alignment (:left, :center, :right) |
| `formatter` | Symbol/Hash/Proc | nil | Value formatter for auto-generated cells |

### Row Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | Object | nil | Row identifier (for selection) |
| `data` | Object | nil | Data object for auto-generating cells |
| `color` | Symbol | nil | Row background color (:success, :warning, :danger) |

## Accessibility

- Uses semantic HTML table elements (`<table>`, `<thead>`, `<tbody>`, `<th>`, `<td>`)
- Header cells include `scope="col"` for screen readers
- Sortable columns include `aria-sort` attribute
- Checkboxes include `aria-label` for screen readers
- Optional caption slot for table description
- Keyboard navigation for interactive elements

---

## Tabs (`rui_tabs`)

# Tabs Component

A WAI-ARIA APG-compliant tabs component. Selecting a tab shows its panel.

**Tier:** Pro

## Basic usage

```erb
<%= rui_tabs(id: "pricing") do |t| %>
  <% t.with_tab(id: "overview", label: "Overview") do %>
    Overview panel content
  <% end %>
  <% t.with_tab(id: "fees", label: "Fees") do %>
    Fees panel content
  <% end %>
<% end %>
```

The first tab is active by default. Mark a different one with `active: true`
on `with_tab` to change the initial selection.

## The flagship `:spaced` variant (Hugh's StockLive design)

```erb
<%= rui_tabs(id: "listing-type", variant: :spaced, color: :primary) do |t| %>
  <% t.with_tab(id: "overview", label: "Overview", icon: "layout-grid") do %>
    Overview panel content
  <% end %>
  <% t.with_tab(id: "sale-dates", label: "Sale Dates", icon: "calendar") do %>
    Sale Dates panel content
  <% end %>
  <% t.with_tab(id: "become-a-user", label: "Become a User", icon: "user-plus") do %>
    <%# Nested subtabs — smaller, different color, same API %>
    <%= rui_tabs(id: "become-a-user-role", variant: :spaced, size: :sm, color: :secondary) do |st| %>
      <% st.with_tab(id: "vendor", label: "Vendor") { "Vendor content" } %>
      <% st.with_tab(id: "buyer", label: "Buyer") { "Buyer content" } %>
      <% st.with_tab(id: "agency", label: "Agency") { "Agency content" } %>
    <% end %>
  <% end %>
  <% t.with_tab(id: "fees", label: "Fees", icon: "coins") do %>
    Fees panel content
  <% end %>
<% end %>
```

Standalone rounded blocks (not connected) — active tab is a solid, dark
`color:` block with white text; inactive tabs are a soft tint of the same
color. A hairline divider under the row is on by default for this variant
(off by default for the other three).

### StockLive commercial page recipe — `active_shade:` + `active_icon_color:` (v0.55.0)

```erb
<%= rui_tabs(id: "commercial", variant: :spaced, color: :primary, active_shade: 600, active_icon_color: :sky, full_width: true) do |t| %>
  <% t.with_tab(id: "overview", label: "Overview", icon: "layout-grid", active: true) do %>
    Overview panel content
  <% end %>
  <% t.with_tab(id: "sale-dates", label: "Sale Dates", icon: "calendar") do %>
    Sale Dates panel content
  <% end %>
  <% t.with_tab(id: "fees", label: "Fees", icon: "coins") do %>
    Fees panel content
  <% end %>
<% end %>
```

`active_shade: 600` overrides the active tab's solid background from the
default 900 down to 600 (e.g. `:primary` configured to a custom midnight
palette — `bg-midnight-600` instead of `bg-midnight-900`). `active_icon_color:
:sky` tints ONLY the active tab's icon a light accent (`sky-300` by default,
via `active_icon_shade:`) while its label stays white — inactive tabs and
every label are unaffected either way.

## Slots

### `with_tab`

```erb
<% t.with_tab(
     id: "overview",         # required — DOM ids become "#{tabs_id}-tab-#{id}" / "#{tabs_id}-panel-#{id}"
     label: "Overview",      # required
     icon: "layout-grid",    # optional lucide icon name
     icon_position: :start,  # :start (default) | :end — :left/:right accepted as aliases, normalized
     active: false,          # exactly one tab ends up active; first `active: true` wins, else the first tab
     disabled: false,        # aria-disabled + skipped by arrow-key nav
     color: nil,             # per-tab override of the tabs-level color:
     badge: nil,             # shortcut — a single trailing counter badge
     badge_color: :muted     # color for the shortcut badge
   ) do %>
  Panel content — arbitrary HTML/ERB/components, nested rui_tabs allowed.
<% end %>
```

### Multiple badges per tab

`with_tab`'s block already captures the panel content, so a nested
`renders_many :badges` slot (à la `Card::List#with_item`, which yields
*itself* to the block) isn't available here without conflict — the block
would have to double as both "yield the Tab instance" and "capture panel
content," and ViewComponent slot blocks only do the latter. The `badges:`
array is the documented fallback for more than one badge:

```erb
<% t.with_tab(
     id: "inbox",
     label: "Inbox",
     badges: [
       {text: "New", color: :accent, position: :leading},
       {text: 5, color: :danger}                 # position: defaults to :trailing
     ]
   ) do %>
  Inbox panel content
<% end %>
```

Render order: leading badges → icon (if `icon_position: :start`) → label →
icon (if `icon_position: :end`) → trailing badges → the `badge:` shortcut
(always last, if given).

## Tabs options

```ruby
rui_tabs(
  id:,                          # required — prefix for every tab/panel DOM id
  variant: :underline,          # :underline (default) | :pills | :boxed | :spaced
  color: :primary,              # semantic color, resolved via ColorBuilderHelper
  size: :base,                  # :sm | :base (default) | :lg
  orientation: :horizontal,     # :horizontal (default) | :vertical
  tablist_position: :start,     # vertical only — :start (default, left) | :end (right)
  divider: nil,                 # nil = variant default (:spaced -> true, others -> false)
  mobile_layout: :row,          # horizontal only — :row (default) | :grid (2-col grid below md)
  full_width: false,            # horizontal only — tabs stretch equally (flex-1)
  activation: :automatic,       # :automatic (default, arrow focus selects) | :manual (Enter/Space selects)
  deep_link: false,             # read/write location.hash on switch
  animation: :fade,             # :fade (default) | :none — suppressed under prefers-reduced-motion
  panels: true,                 # false renders the tablist only (wire your own external panels)
  panel_gap: :sm,                # :sm (default) | :none | :md | :lg — space around divider/panels
  active_shade: nil,            # :pills/:spaced only — 500/600/700/800/900/950, nil = each color's own default
  active_icon_color: nil,       # tint the ACTIVE tab's icon (nil = matches label, unchanged)
  active_icon_shade: 300        # 100/200/300/400/500 — ignored unless active_icon_color: is set
) do |t|
  # ...tabs
end
```

### `variant:`

| Variant | Look |
|---|---|
| `:underline` (default) | Connected row, transparent bg. Active tab gets a 2px bottom border + colored text. |
| `:pills` | Rounded-full triggers. Active gets a solid `color:` bg + white text (`ColorBuilderHelper` `:solid`). Inactive is muted/transparent. |
| `:boxed` | Tablist has a bottom border; the active tab is a bordered box that visually merges into the panel below it. |
| `:spaced` | Standalone rounded blocks with a gap between them (not connected). Active = solid dark `color:` bg + white text (`:solid`); inactive = soft tinted `color:` bg (`:soft`). Divider on by default. |

### `active_shade:` — override the active `:pills`/`:spaced` shade (v0.55.0)

```erb
<%= rui_tabs(id: "pricing", variant: :spaced, color: :primary, active_shade: 600) do |t| %>
  ...
<% end %>
```

Without `active_shade:` (the default, `nil`), the active trigger's solid
bg/hover/border/focus-ring shade comes from `ColorBuilderHelper`'s own fixed
per-color-category table — 900 for `:primary`-style colors, 700 for
standard colors, 400 for the bright/`:warning` family. `active_shade:` lets
ONE tabs instance override that shade instead, to one of `500`/`600`/`700`/
`800`/`900`/`950` — an invalid value warns (dev/test) and falls back to
`900`. Hover derives as one step darker automatically, except right at the
edges of that set (900 keeps its historical 900→800 pairing; 950 falls back
one step lighter since nothing darker exists). Only affects `:pills`/
`:spaced` (the other two variants don't render a solid active background).
Dark mode is unaffected — it keeps using each color's own category dark
shades regardless of `active_shade:`.

### `active_icon_color:` / `active_icon_shade:` — tint the active icon (v0.55.0)

```erb
<%= rui_tabs(id: "pricing", variant: :spaced, color: :primary, active_icon_color: :sky, active_icon_shade: 300) do |t| %>
  <% t.with_tab(id: "overview", label: "Overview", icon: "layout-grid", active: true) { "..." } %>
<% end %>
```

Gives the ACTIVE tab's icon a different color than its (unchanged) label
text — e.g. a light accent on a dark `:spaced` solid background. `nil`
(the default) means the icon matches the label, same as every version
before 0.55.0. `active_icon_shade:` (default `300`, one of `100`/`200`/
`300`/`400`/`500`) is ignored unless `active_icon_color:` is set. Inactive
tabs are never affected — the tint only ever applies to whichever tab is
currently active.

### `orientation: :vertical`

```erb
<%= rui_tabs(id: "settings", orientation: :vertical, tablist_position: :start) do |t| %>
  ...
<% end %>
```

Tablist becomes a column (`shrink-0`); panels take the remaining width
(`flex-1`). `tablist_position: :end` flips the visual side with
`flex-row-reverse` rather than reordering the tablist/panels in the DOM, so
keyboard focus order always matches DOM order regardless of which side the
tablist visually sits on. The gap between the tablist column and the panel
content is controlled by `panel_gap:` below (v0.51.x/early v0.52.0 had zero
gap here — panel content rendered flush against the tablist column).

### `panel_gap:`

Space between the tablist, the divider (if rendered), and the panels —
applied as a flex `gap` on the tabs root, so it's consistent whether or not
`divider:` is on. In `:horizontal` orientation this is vertical space
(`gap-y-*`) between the stacked tablist/divider/panels; in `:vertical`
orientation it's the horizontal gutter (`gap-x-*`) between the tablist
column and the panel content.

| Value | Horizontal | Vertical |
|---|---|---|
| `:none` | no gap | no gap |
| `:sm` (default) | `gap-y-3` | `gap-x-3` |
| `:md` | `gap-y-4` | `gap-x-4` |
| `:lg` | `gap-y-6` | `gap-x-6` |

```erb
<%= rui_tabs(id: "settings", orientation: :vertical, panel_gap: :lg) do |t| %>
  ...
<% end %>
```

Before v0.54.0, variants without a divider (`:underline`/`:boxed`/`:pills`,
or `:spaced` with `divider: false`) rendered the panels touching the
tablist — there was no spacing mechanism at all outside the divider's own
margin. `panel_gap:` now owns that spacing for every variant; the divider
itself carries no margin of its own, so turning `divider: true` on/off
never changes the amount of space around it.

### `deep_link: true`

```erb
<%= rui_tabs(id: "pricing", deep_link: true) do |t| %>
  <% t.with_tab(id: "overview", label: "Overview") { "..." } %>
  <% t.with_tab(id: "fees", label: "Fees") { "..." } %>
<% end %>
```

On connect, the `rui--tabs` controller reads `location.hash` (e.g.
`#fees`) and activates the matching tab if the raw `id:` matches. On every
switch it writes the hash back via `history.replaceState` (no extra
back-button history entries, no browser auto-scroll-to-anchor since no
element literally carries that bare id). Listens for `hashchange` too, so
external links into a specific tab work both on load and while the page is
already open.

### `panels: false` — external panels recipe

`panels: false` renders the tablist only, and nothing else — the
component doesn't emit `aria-controls` on the tabs at all
(`component.rb`'s `"aria-controls": (panels? ? panel_dom_id(tab) : nil)`),
so the Stimulus controller has no panel id to look up and never toggles
anything for you, no matter what id an external panel uses. Matching an
external panel's id to the built-in `"#{id}-panel-#{tab_id}"` pattern does
**nothing** on its own — you own showing/hiding external panels entirely
yourself. Listen for the tab-change event the controller dispatches on
every activation (`rui--tabs:change` if this app uses the default
`config.stimulus_namespace = "rui"` from `rapid_rails_ui.rb`, or `tabs:change`
if the namespace was left unset) and toggle your panels from its
`detail.tab` (the activated tab's `id:`):

```erb
<%= rui_tabs(id: "wizard", panels: false) do |t| %>
  <% t.with_tab(id: "step-1", label: "Step 1") %>
  <% t.with_tab(id: "step-2", label: "Step 2") %>
<% end %>

<div id="wizard-panel-step-1" role="tabpanel" aria-labelledby="wizard-tab-step-1" tabindex="0"
     data-controller="wizard-panels" data-wizard-panels-tab-id-value="step-1">
  Step 1 content, wired up by hand.
</div>
<div id="wizard-panel-step-2" role="tabpanel" aria-labelledby="wizard-tab-step-2" tabindex="0" hidden
     data-controller="wizard-panels" data-wizard-panels-tab-id-value="step-2">
  Step 2 content.
</div>
```

```js
// app/javascript/controllers/wizard_panels_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = { tabId: String }

connect() {
    // Listen on the document since the tabs controller and this panel
    // aren't nested inside each other - `panels: false` panels live
    // wherever you put them in the page.
    this._onChange = (event) => {
      this.element.hidden = event.detail.tab !== this.tabIdValue
    }
    document.addEventListener("rui--tabs:change", this._onChange)
  }

disconnect() {
    document.removeEventListener("rui--tabs:change", this._onChange)
  }
}
```

### Lazy panel content

No dedicated lazy-mount API. Put a `turbo_frame_tag` inside the panel block:

```erb
<% t.with_tab(id: "activity", label: "Activity") do %>
  <%= turbo_frame_tag "activity-frame", src: activity_path, loading: :lazy do %>
    Loading…
  <% end %>
<% end %>
```

## Behaviour notes

- **Selection identity is the tab's `id:` (a string), never its index.**
  Reordering tabs never changes which one is selected.
- **Colors resolve through `ColorBuilderHelper`.** `color:` on `rui_tabs`
  sets the default for every tab; `color:` on an individual `with_tab`
  overrides it for that one tab only.
- **Focus ring is always visible on triggers** — `ring-2`/`ring-offset-0`
  at 700 (light) / 400 (dark), the same recipe Combobox/Select use.
- **Reduced motion.** `animation: :fade`'s opacity transition is fully
  skipped under `prefers-reduced-motion: reduce` — the panel still shows
  instantly, just without the fade.
- **No JS controller registration needed beyond the standard install** —
  `rui--tabs` is picked up automatically the same way every other RRUI
  Stimulus controller is (see the root `CLAUDE.md`/README Stimulus section).

## Out of scope (v0.52.0)

- **No overflow management** (scroll buttons / overflow dropdown / native
  `<select>` fallback for many tabs). Intended use is ≤5 tabs; a later
  release can add this. `TABLIST_ORIENTATION_CLASSES[:horizontal]` sets
  `flex-wrap` on the tablist itself, so by default a horizontal tablist
  wraps to a second line rather than overflowing — but it can still
  overflow the width of a narrow PARENT container (a sidebar, a modal, a
  flex row) if that parent doesn't give the tablist room to shrink or wrap.
  If you see that, it's almost always a min-width/flex-basis issue on an
  ANCESTOR, not on `rui_tabs` itself. Two consumer-side fixes:
  - **Flex/grid ancestor clipping or pushing siblings**: add `min-w-0` to
    the flex/grid item that contains the tabs (the tablist's own
    `flex flex-wrap` can't do anything if its parent is a non-wrapping flex
    item with the default `min-width: auto`, which refuses to shrink below
    its content's natural width).
  - **Fixed-width/narrow container where you'd rather wrap than shrink**:
    `rui_tabs(id: "x", class: "flex-wrap")` — the tablist already wraps
    once given room; this just confirms it for callers who overrode
    `full_width:`/custom flex classes upstream.
- No link-navigation tabs (`href:` triggers with `aria-current`). That's a
  nav pattern, not the tablist/tabpanel pattern — a separate component if
  ever needed.
- No closable tabs (APG Delete key).

---

## Text (`rui_text`)

# RapidRailsUI Text Component Usage Guide

The Text component (`rui_text`) provides complete typography control with semantic HTML, full styling options, and accessibility-first design.

## Table of Contents
- [Quick Start](#quick-start)
- [HTML Tags](#html-tags)
- [Text Styling](#text-styling)
- [Variants](#variants)
- [Icons and Badges](#icons-and-badges)
- [Special Features](#special-features)
- [Accessibility](#accessibility)
- [Examples](#examples)

---

## Quick Start

```erb
<%# Simple paragraph %>
<%= rui_text("Hello World") %>

<%# Heading %>
<%= rui_text("Page Title", as: :h1, color: :primary) %>

<%# Styled text %>
<%= rui_text("Important", size: :lg, weight: :bold, color: :danger) %>

<%# With block %>
<%= rui_text(as: :h2, weight: :semibold) do %>
  Section Heading
<% end %>
```

---

## HTML Tags

Use the `as:` parameter to control the HTML element:

### Headings

```erb
<%= rui_text("H1 Heading", as: :h1) %>
<%= rui_text("H2 Heading", as: :h2) %>
<%= rui_text("H3 Heading", as: :h3) %>
<%= rui_text("H4 Heading", as: :h4) %>
<%= rui_text("H5 Heading", as: :h5) %>
<%= rui_text("H6 Heading", as: :h6) %>
```

**Output:**
- H1: `text-5xl font-extrabold` (responsive: `md:text-6xl`)
- H2: `text-4xl font-bold` (responsive: `md:text-5xl`)
- H3: `text-3xl font-bold` (responsive: `md:text-4xl`)
- H4: `text-2xl font-semibold` (responsive: `md:text-3xl`)
- H5: `text-xl font-semibold` (responsive: `md:text-2xl`)
- H6: `text-lg font-semibold` (responsive: `md:text-xl`)

### Paragraphs

```erb
<%# Default paragraph %>
<%= rui_text("This is a paragraph.") %>

<%# Explicit paragraph tag %>
<%= rui_text("Lorem ipsum", as: :p) %>
```

### Blockquotes

```erb
<%# Simple blockquote %>
<%= rui_text(as: :blockquote) do %>
  To be or not to be, that is the question.
<% end %>

<%# With citation %>
<%= rui_text(as: :blockquote, cite: "William Shakespeare") do %>
  To be or not to be, that is the question.
<% end %>
```

### Inline Text

```erb
<%# Span element %>
<%= rui_text("Inline text", as: :span) %>

<%# Force inline rendering %>
<%= rui_text("Small detail", inline: true, size: :sm) %>
```

### Semantic Elements

```erb
<%= rui_text(as: :div) { "Div content" } %>
<%= rui_text(as: :section) { "Section content" } %>
<%= rui_text(as: :article) { "Article content" } %>
```

---

## Text Styling

### Size

Available sizes: `:xs`, `:sm`, `:base`, `:md`, `:lg`, `:xl`, `:xl2`, `:xl3`, `:xl4`, `:xl5`, `:xl6`

```erb
<%= rui_text("Extra small", size: :xs) %>
<%= rui_text("Small", size: :sm) %>
<%= rui_text("Base (default)", size: :base) %>
<%= rui_text("Medium", size: :md) %>
<%= rui_text("Large", size: :lg) %>
<%= rui_text("Extra large", size: :xl) %>
<%= rui_text("2XL", size: :xl2) %>
<%= rui_text("3XL", size: :xl3) %>
<%= rui_text("4XL", size: :xl4) %>
<%= rui_text("5XL", size: :xl5) %>
<%= rui_text("6XL", size: :xl6) %>
```

### Weight

Available weights: `:thin`, `:light`, `:normal`, `:medium`, `:semibold`, `:bold`, `:extrabold`, `:black`

```erb
<%= rui_text("Thin text", weight: :thin) %>
<%= rui_text("Light text", weight: :light) %>
<%= rui_text("Normal text", weight: :normal) %>
<%= rui_text("Medium text", weight: :medium) %>
<%= rui_text("Semibold text", weight: :semibold) %>
<%= rui_text("Bold text", weight: :bold) %>
<%= rui_text("Extrabold text", weight: :extrabold) %>
<%= rui_text("Black text", weight: :black) %>
```

### Color

All semantic colors supported via ColorBuilderHelper. The brand colors
(`:primary`, `:secondary`, `:tertiary`, `:accent`, `:muted`) resolve through
your app's `config.colors`, so text follows your palette. Status colors
(`:success`, `:danger`, `:warning`, `:info`) are fixed by convention.

```erb
<%= rui_text("Primary",   color: :primary) %>   <%# config.colors[:primary] %>
<%= rui_text("Secondary", color: :secondary) %> <%# config.colors[:secondary] %>
<%= rui_text("Tertiary",  color: :tertiary) %>  <%# config.colors[:tertiary] %>
<%= rui_text("Accent",    color: :accent) %>    <%# config.colors[:accent] %>
<%= rui_text("Muted",     color: :muted) %>     <%# config.colors[:muted], defaults to "gray" %>
<%= rui_text("Success",   color: :success) %>
<%= rui_text("Danger",    color: :danger) %>
<%= rui_text("Warning",   color: :warning) %>
<%= rui_text("Info",      color: :info) %>
<%= rui_text("Neutral",   color: :neutral) %>
```

Tailwind colors also supported:

```erb
<%= rui_text("Blue text", color: :blue) %>
<%= rui_text("Red text", color: :red) %>
<%= rui_text("Green text", color: :green) %>
```

### Alignment

```erb
<%= rui_text("Left aligned", align: :left) %>
<%= rui_text("Centered", align: :center) %>
<%= rui_text("Right aligned", align: :right) %>
<%= rui_text("Justified text goes here...", align: :justify) %>
```

### Font Family

```erb
<%= rui_text("Sans-serif font", font: :sans) %>
<%= rui_text("Serif font", font: :serif) %>
<%= rui_text("Monospace font", font: :mono) %>
```

### Line Height

```erb
<%= rui_text("No line height", line_height: :none) %>
<%= rui_text("Tight", line_height: :tight) %>
<%= rui_text("Snug", line_height: :snug) %>
<%= rui_text("Normal", line_height: :normal) %>
<%= rui_text("Relaxed", line_height: :relaxed) %>
<%= rui_text("Loose", line_height: :loose) %>
```

### Letter Spacing

```erb
<%= rui_text("Tighter", letter_spacing: :tighter) %>
<%= rui_text("Tight", letter_spacing: :tight) %>
<%= rui_text("Normal", letter_spacing: :normal) %>
<%= rui_text("Wide", letter_spacing: :wide) %>
<%= rui_text("Wider", letter_spacing: :wider) %>
<%= rui_text("Widest", letter_spacing: :widest) %>
```

---

## Variants

The Text component supports visual variants powered by ColorBuilderHelper:

### Solid Variant

```erb
<%= rui_text("Solid text", variant: :solid, color: :primary) %>
<%= rui_text("Success message", variant: :solid, color: :success) %>
```

**Renders:** Background color with contrasting text (like a badge/pill)

### Outline Variant

```erb
<%= rui_text("Outlined text", variant: :outline, color: :primary) %>
```

**Renders:** Border with colored text, transparent background

### Ghost Variant

```erb
<%= rui_text("Ghost text", variant: :ghost, color: :info) %>
```

**Renders:** Subtle background with colored text

### Soft Variant

```erb
<%= rui_text("Soft variant", variant: :soft, color: :warning) %>
```

**Renders:** Light background with colored text

### Link Variant

```erb
<%= rui_text("Link style", variant: :link, color: :primary) %>
```

**Renders:** Underlined, link-like appearance

### Strong Variant

```erb
<%= rui_text("Strong emphasis", variant: :strong) %>
```

**Renders:** Bold weight (no color change)

### Subtle Variant

```erb
<%= rui_text("Subtle text", variant: :subtle) %>
```

**Renders:** Reduced opacity (70%)

---

## Icons and Badges

### With Icon

```erb
<%# Leading icon (default) %>
<%= rui_text("Featured Content", color: :info) do |text|
  text.with_icon(name: :star, position: :leading)
end %>

<%# Trailing icon %>
<%= rui_text("Learn More", color: :primary) do |text|
  text.with_icon(name: :arrow_right, position: :trailing)
end %>

<%# Custom icon color %>
<%= rui_text("Warning", color: :neutral) do |text|
  text.with_icon(name: :alert_triangle, color: :warning)
end %>
```

### With Badge

```erb
<%= rui_text("New Feature", as: :h3) do |text|
  text.with_badge(text: "Beta", color: :info)
end %>
```

---

## Special Features

### Gradient Text

Apply beautiful gradient effects to your text with multiple color schemes.

**Available Gradient Styles:**
- **`:sunset`** - Purple to pink (default)
- **`:ocean`** - Yellow → blue → indigo
- **`:forest`** - Blue → teal → green
- **`:sunrise`** - Purple → orange → yellow
- **`:aurora`** - Purple → teal → red

```erb
<%# Apply gradient style to entire text %>
<%= rui_text("Beautiful Gradient", gradient: :ocean, size: :xl3, weight: :bold) %>
<%= rui_text("Forest Vibes", gradient: :forest, size: :xl2) %>
<%= rui_text("Aurora Magic", gradient: :aurora, size: :xl2) %>

<%# Apply default sunset gradient to specific word %>
<%= rui_text("Make it gradient shine", gradient: "gradient", size: :xl2) %>

<%# Apply specific gradient style to specific word %>
<%= rui_text("Make it ocean today", gradient: { text: "ocean", style: :ocean }, size: :xl2) %>
<%= rui_text("Feel the sunrise vibes", gradient: { text: "sunrise", style: :sunrise }, size: :xl) %>
```

### Accent Styling

```erb
<%= rui_text("Subtle accent", accent: true) %>
```

**Renders:** Slightly transparent (opacity-80)

### Prose Mode

Perfect for long-form articles and blog posts:

```erb
<%= rui_text(prose: true) do %>
  <h2>Article Title</h2>
  <p>First paragraph with automatic prose styling...</p>
  <p>Second paragraph...</p>
  <ul>
    <li>List item 1</li>
    <li>List item 2</li>
  </ul>
<% end %>
```

**Renders:** Adds `prose prose-neutral dark:prose-invert max-w-none` classes for optimal readability

---

## Accessibility

The Text component follows WCAG guidelines and includes proper ARIA attributes:

### Headings with ARIA

```erb
<%= rui_text("Accessible Heading", as: :h2) %>
```

**Renders:**
```html
<h2 role="heading" aria-level="2">Accessible Heading</h2>
```

### Blockquotes with Citations

```erb
<%= rui_text(as: :blockquote, cite: "Author Name") do %>
  Quote text here
<% end %>
```

**Renders:**
```html
<blockquote role="blockquote" aria-describedby="cite-abc123">
  Quote text here
  <cite id="cite-abc123">Author Name</cite>
</blockquote>
```

---

## Examples

### Hero Heading

```erb
<%= rui_text("Build Faster with RapidRailsUI", as: :h1, align: :center) %>
<%= rui_text("Beautiful components for Ruby on Rails", 
             size: :xl, 
             weight: :medium, 
             color: :neutral, 
             align: :center) %>
```

### Feature Highlight

```erb
<%= rui_text(variant: :solid, color: :success, size: :lg) do |text|
  text.with_icon(name: :check_circle, position: :leading)
  "Feature Activated!"
end %>
```

### Error Message

```erb
<%= rui_text("Please fix the errors below", 
             variant: :outline, 
             color: :danger,
             weight: :semibold) do |text|
  text.with_icon(name: :alert_triangle)
end %>
```

### Styled Blockquote

```erb
<%= rui_text(as: :blockquote, 
             color: :primary, 
             font: :serif, 
             size: :lg,
             cite: "Steve Jobs") do %>
  Innovation distinguishes between a leader and a follower.
<% end %>
```

### Article Content

```erb
<%= rui_text(prose: true, as: :article) do %>
  <%= render "article_content" %>
<% end %>
```

### Status Indicators

```erb
<%= rui_text("Active", variant: :solid, color: :success, size: :sm) %>
<%= rui_text("Pending", variant: :soft, color: :warning, size: :sm) %>
<%= rui_text("Inactive", variant: :ghost, color: :neutral, size: :sm) %>
```

---

## Component Options Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `text` | String | `nil` | Text content (can be positional) |
| `as` | Symbol | `:p` | HTML tag (h1-h6, p, span, div, section, article, blockquote) |
| `color` | Symbol | `:primary` | Color theme |
| `size` | Symbol | `:base` | Text size (xs, sm, base, md, lg, xl, xl2-xl6) |
| `weight` | Symbol | `:normal` | Font weight (thin, light, normal, medium, semibold, bold, extrabold, black) |
| `align` | Symbol | `:left` | Text alignment (left, center, right, justify) |
| `font` | Symbol | `:sans` | Font family (sans, serif, mono) |
| `line_height` | Symbol | `:normal` | Line height (none, tight, snug, normal, relaxed, loose) |
| `letter_spacing` | Symbol | `:normal` | Letter spacing (tighter, tight, normal, wide, wider, widest) |
| `variant` | Symbol | `:default` | Visual style (default, solid, outline, ghost, soft, link, strong, subtle) |
| `gradient` | String | `nil` | Text to apply gradient effect |
| `cite` | String | `nil` | Citation (for blockquotes) |
| `accent` | Boolean | `false` | Apply accent styling (lighter opacity) |
| `inline` | Boolean | `false` | Force inline rendering (span) |
| `prose` | Boolean | `false` | Enable prose mode for articles |

---

## Slots

| Slot | Description |
|------|-------------|
| `icon` | Add icon (auto-inherits color unless overridden) |
| `badge` | Add badge to text |

---

## Related Components

- **TextFmt (`rui_text_fmt`)** - Text with Rails formatting helpers (truncate, highlight, number formatting, etc.)
- **Badge (`rui_badge`)** - Can be used inside Text component
- **Icon (`rui_icon`)** - Can be used inside Text component
- **Link (`rui_link`)** - For clickable text

---

## Best Practices

1. **Use semantic HTML**: Choose appropriate `as:` tags (h1-h6 for headings, p for paragraphs)
2. **Heading hierarchy**: Don't skip heading levels (h1 → h2 → h3, not h1 → h3)
3. **Accessibility**: Use proper heading levels and ARIA attributes (automatically added)
4. **Responsive headings**: Headings automatically scale on larger screens
5. **Prose mode**: Use for long-form content to get optimal typography
6. **Color contrast**: Ensure sufficient contrast for readability
7. **Icon sizing**: Icons automatically inherit text size when used in Text component

---

## Need Text Formatting?

For text transformations like truncation, highlighting, number formatting, and more, use the **TextFmt component** (`rui_text_fmt`):

```erb
<%# See TextFmt USAGE.md for details %>
<%= rui_text_fmt(@post.body, truncate: 100) %>
<%= rui_text_fmt(@price, number_format: :currency) %>
<%= rui_text_fmt(@article, highlight: "Rails", sanitize: true) %>
```

---

## Text Fmt (`rui_text_fmt`)

# RapidRailsUI TextFmt Component Usage Guide

The TextFmt component (`rui_text_fmt`) wraps the Text component with powerful Rails text formatting helpers. Think of it as "button_to" is to "button" - same styling capabilities, plus text transformations.

## Table of Contents
- [Quick Start](#quick-start)
- [Text Truncation](#text-truncation)
- [Text Highlighting](#text-highlighting)
- [Sanitization](#sanitization)
- [Pluralization](#pluralization)
- [Number Formatting](#number-formatting)
- [Time Formatting](#time-formatting)
- [Text Transformations](#text-transformations)
- [Auto-Linkify](#auto-linkify)
- [Combining Features](#combining-features)

---

## Quick Start

```erb
<%# Truncate long text %>
<%= rui_text_fmt(@post.body, truncate: 100) %>

<%# Format as currency %>
<%= rui_text_fmt(@product.price, number_format: :currency) %>

<%# Highlight search term %>
<%= rui_text_fmt(@article, highlight: params[:query]) %>

<%# Time ago %>
<%= rui_text_fmt(@post.created_at, time_ago: true) %>
```

**All Text component styling works:**

```erb
<%= rui_text_fmt(@post.body, 
                 truncate: 150,
                 as: :p,
                 size: :lg,
                 color: :neutral) %>
```

---

## Text Truncation

Truncate long text to a specific length:

```erb
<%# Basic truncation %>
<%= rui_text_fmt(@long_text, truncate: 100) %>

<%# With styling %>
<%= rui_text_fmt(@post.body, 
                 truncate: 200,
                 size: :base,
                 color: :neutral) %>
```

**Output:**
```
"This is a very long text that will be truncated after 100 characters and will show..."
```

---

## Text Highlighting

Highlight search terms or keywords:

```erb
<%# Highlight single word %>
<%= rui_text_fmt(@article, highlight: "Rails") %>

<%# Highlight search query %>
<%= rui_text_fmt(@content, 
                 highlight: params[:query],
                 sanitize: true) %>

<%# With color %>
<%= rui_text_fmt(@text, 
                 highlight: "important",
                 color: :warning) %>
```

**Output:**
```html
This is an <mark class="bg-yellow-200 dark:bg-yellow-900 px-1 rounded">important</mark> message
```

---

## Sanitization

Remove dangerous HTML tags and attributes:

```erb
<%# Basic sanitization %>
<%= rui_text_fmt(@user_input, sanitize: true) %>

<%# Custom sanitization options %>
<%= rui_text_fmt(@html_content, 
                 sanitize: true,
                 sanitize_options: { 
                   tags: %w[p br strong em],
                   attributes: %w[href class]
                 }) %>
```

**Use case:** User-generated content, imported HTML, etc.

---

## Pluralization

Automatically pluralize words based on count:

```erb
<%# Pluralize with count %>
<%= rui_text_fmt("comment", pluralize: true, count: 0) %>
<%= rui_text_fmt("comment", pluralize: true, count: 1) %>
<%= rui_text_fmt("comment", pluralize: true, count: 5) %>
```

**Output:**
```
0 comments
1 comment
5 comments
```

**With styling:**

```erb
<%= rui_text_fmt("notification", 
                 pluralize: true,
                 count: @notifications.count,
                 variant: :solid,
                 color: :info,
                 size: :sm) %>
```

---

## Number Formatting

Format numbers as currency, percentages, human-readable, or phone numbers:

### Currency

```erb
<%= rui_text_fmt(1234.56, number_format: :currency) %>
<%# Output: $1,234.56 %>

<%# With options %>
<%= rui_text_fmt(1234.56, 
                 number_format: :currency,
                 number_options: { unit: "€", precision: 2 }) %>
<%# Output: €1,234.56 %>
```

### Percentage

```erb
<%= rui_text_fmt(75.5, number_format: :percentage) %>
<%# Output: 75.5% %>

<%# With precision %>
<%= rui_text_fmt(75.5231, 
                 number_format: :percentage,
                 number_options: { precision: 1 }) %>
<%# Output: 75.5% %>
```

### Human-Readable

```erb
<%= rui_text_fmt(1234567, number_format: :human) %>
<%# Output: 1.23 Million %>

<%= rui_text_fmt(1234567890, number_format: :human) %>
<%# Output: 1.23 Billion %>
```

### Phone Number

```erb
<%= rui_text_fmt("5551234567", number_format: :phone) %>
<%# Output: 555-123-4567 %>

<%# With options %>
<%= rui_text_fmt("5551234567", 
                 number_format: :phone,
                 number_options: { area_code: true }) %>
<%# Output: (555) 123-4567 %>
```

---

## Time Formatting

Convert timestamps to human-friendly "time ago" format:

```erb
<%= rui_text_fmt(@post.created_at, time_ago: true) %>
<%# Output: "3 hours ago" %>

<%= rui_text_fmt(@comment.updated_at, time_ago: true) %>
<%# Output: "2 days ago" %>

<%# With styling %>
<%= rui_text_fmt(@notification.created_at, 
                 time_ago: true,
                 size: :sm,
                 color: :neutral) %>
```

---

## Text Transformations

### Titleize

Capitalize each word:

```erb
<%= rui_text_fmt("hello world from rails", titleize: true) %>
<%# Output: "Hello World From Rails" %>
```

### Excerpt

Extract text around a specific phrase:

```erb
<%# Extract 100 characters around "Ruby" %>
<%= rui_text_fmt(@article, excerpt: "Ruby", radius: 100) %>

<%# With highlighting %>
<%= rui_text_fmt(@article, 
                 excerpt: params[:query],
                 radius: 150,
                 highlight: params[:query]) %>
```

### Simple Format

Convert line breaks to paragraphs:

```erb
<%= rui_text_fmt(@plain_text, simple_format: true) %>
```

**Input:**
```
Line 1
Line 2

New paragraph
```

**Output:**
```html
<p>Line 1<br/>Line 2</p>
<p>New paragraph</p>
```

---

## Auto-Linkify

Automatically convert URLs and emails to clickable links:

```erb
<%= rui_text_fmt(@bio, linkify: true) %>
```

**Input:**
```
Check out https://example.com or email me at user@example.com
```

**Output:**
```html
Check out <a href="https://example.com" target="_blank" rel="noopener noreferrer">https://example.com</a> 
or email me at <a href="mailto:user@example.com">user@example.com</a>
```

**With simple_format:**

```erb
<%= rui_text_fmt(@bio, linkify: true, simple_format: true) %>
```

---

## Prefix and Suffix

Add text before or after content:

```erb
<%# Prefix only %>
<%= rui_text_fmt(@username, prefix: "Hello, ") %>
<%# Output: "Hello, John" %>

<%# Suffix only %>
<%= rui_text_fmt(@username, suffix: "!") %>
<%# Output: "John!" %>

<%# Both %>
<%= rui_text_fmt(@username, prefix: "Welcome, ", suffix: "!") %>
<%# Output: "Welcome, John!" %>
```

**With styling:**

```erb
<%= rui_text_fmt(@username, 
                 prefix: "Hello, ",
                 suffix: "!",
                 weight: :bold,
                 color: :primary) %>
```

---

## Default Fallback

Show default text when content is blank:

```erb
<%= rui_text_fmt(@user.bio, default: "No bio provided") %>
```

**If @user.bio is blank:**
```
No bio provided
```

---

## Combining Features

You can combine multiple formatting features:

### Blog Post Excerpt

```erb
<%= rui_text_fmt(@post.body,
                 sanitize: true,
                 truncate: 300,
                 linkify: true,
                 size: :base,
                 color: :neutral) %>
```

### Search Result

```erb
<%= rui_text_fmt(@result.content,
                 highlight: params[:query],
                 excerpt: params[:query],
                 radius: 200,
                 sanitize: true,
                 as: :p,
                 size: :sm) %>
```

### User Comment

```erb
<%= rui_text_fmt(@comment.body,
                 sanitize: true,
                 simple_format: true,
                 linkify: true,
                 size: :base,
                 color: :neutral) %>
```

### Price Display

```erb
<%= rui_text_fmt(@product.price,
                 number_format: :currency,
                 number_options: { precision: 2 },
                 variant: :solid,
                 color: :success,
                 weight: :bold,
                 size: :xl) %>
```

### Stats Display

```erb
<div class="flex gap-4">
  <%= rui_text_fmt("user", 
                   pluralize: true,
                   count: @users_count,
                   variant: :soft,
                   color: :primary) %>
  
  <%= rui_text_fmt(@total_revenue,
                   number_format: :currency,
                   variant: :solid,
                   color: :success) %>
</div>
```

---

## Component Options Reference

### Formatting Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `text` | String | `nil` | Text content to format (positional parameter) |
| `truncate` | Integer | `nil` | Truncate text to this length |
| `highlight` | String | `nil` | Phrase to highlight |
| `sanitize` | Boolean | `false` | Remove dangerous HTML |
| `sanitize_options` | Hash | `{}` | Options for sanitize helper |
| `pluralize` | Boolean | `false` | Enable pluralization |
| `count` | Integer | `nil` | Count for pluralization |
| `excerpt` | String | `nil` | Extract excerpt around phrase |
| `radius` | Integer | `100` | Characters around excerpt phrase |
| `simple_format` | Boolean | `false` | Convert line breaks to <p> tags |
| `time_ago` | Boolean | `false` | Format as "X ago" |
| `titleize` | Boolean | `false` | Capitalize each word |
| `number_format` | Symbol | `nil` | `:currency`, `:percentage`, `:human`, `:phone` |
| `number_options` | Hash | `{}` | Options for number formatting |
| `linkify` | Boolean | `false` | Convert URLs/emails to links |
| `default` | String | `nil` | Fallback text if text is blank |
| `prefix` | String | `nil` | Text to prepend |
| `suffix` | String | `nil` | Text to append |

### All Text Component Options

All Text component options are supported:

- `as` - HTML tag (h1-h6, p, span, etc.)
- `color` - Color theme
- `size` - Text size
- `weight` - Font weight
- `align` - Text alignment
- `font` - Font family
- `line_height` - Line height
- `letter_spacing` - Letter spacing
- `variant` - Visual style
- `gradient` - Gradient effect
- `cite` - Citation (blockquotes)
- `accent` - Accent styling
- `inline` - Inline rendering
- `prose` - Prose mode

See [Text component USAGE.md](../text/USAGE.md) for full details.

---

## Use Cases

### User-Generated Content

```erb
<%# Sanitize and linkify user bio %>
<%= rui_text_fmt(@user.bio,
                 sanitize: true,
                 simple_format: true,
                 linkify: true) %>
```

### E-commerce Product

```erb
<%# Price with currency %>
<%= rui_text_fmt(@product.price,
                 number_format: :currency,
                 weight: :bold,
                 size: :xl2) %>

<%# Stock count %>
<%= rui_text_fmt("item",
                 pluralize: true,
                 count: @product.stock,
                 prefix: "Only ",
                 suffix: " left!",
                 color: :warning) %>
```

### Blog/Articles

```erb
<%# Article excerpt for listing %>
<%= rui_text_fmt(@article.body,
                 truncate: 200,
                 sanitize: true) %>

<%# Reading time %>
<%= rui_text_fmt(@article.created_at,
                 time_ago: true,
                 size: :sm,
                 color: :neutral) %>
```

### Search Results

```erb
<%# Highlight search terms in excerpt %>
<%= rui_text_fmt(@result.body,
                 excerpt: params[:query],
                 radius: 150,
                 highlight: params[:query],
                 sanitize: true) %>
```

---

## Related Components

- **Text (`rui_text`)** - Pure typography component (this wraps it)
- **Link (`rui_link`)** - For clickable text
- **Badge (`rui_badge`)** - For labels and tags

---

## Best Practices

1. **Always sanitize user input** when displaying HTML from users
2. **Combine linkify + simple_format** for user bios and comments
3. **Use excerpt + highlight** together for search results
4. **Truncate before highlighting** for better performance
5. **Test number formatting** with your locale settings
6. **Use default fallback** for optional fields
7. **Sanitize before linkify** to prevent XSS attacks

---

## Performance Tips

1. **Order matters**: Apply expensive operations last (highlight, linkify)
2. **Sanitize early**: Reduces the text size for subsequent operations
3. **Use excerpt before truncate**: More semantic for search results
4. **Cache formatted content**: If content doesn't change often

```erb
<%# Good: sanitize → truncate → highlight %>
<%= rui_text_fmt(@content, sanitize: true, truncate: 100, highlight: "term") %>

<%# Less efficient: highlight → sanitize → truncate %>
<%# (highlighting gets removed by sanitize) %>
```

---

## Textarea (`rui_textarea`)

# Textarea Component

Multi-line text input component with character counting, auto-resize, and real-time validation.

## Features

- **Multi-line input** - 3 variants, 5 sizes, 3 shapes, all semantic colors
- **Character counter** - Real-time character count with maxlength enforcement
- **Auto-resize** - Grows/shrinks with content (respects min/max rows)
- **Real-time validation** - Visual feedback with border colors and messages
- **Form builder integration** - Works seamlessly with Rails forms (`f.rui_textarea`)
- **Accessibility** - ARIA attributes, keyboard support, proper labeling
- **Dark mode** - Full dark mode support with Tailwind dark: variants

## Basic Usage

### Standalone (Positional or Keyword)

```erb
<%# Positional first argument (recommended) %>
<%= rui_textarea(:description, label: "Description", rows: 6) %>

<%# Keyword argument (also supported) %>
<%= rui_textarea(name: :description, label: "Description", rows: 6) %>
```

### Form Builder

```erb
<%= form_with(model: @post) do |f| %>
  <%= f.rui_textarea(:body, label: "Content", rows: 8) %>
<% end %>
```

## Parameters

### Positional Argument

The first positional argument can be used instead of `name:` or `method:`:

```erb
<%# These are equivalent for standalone usage: %>
<%= rui_textarea(:notes, label: "Notes") %>
<%= rui_textarea(name: :notes, label: "Notes") %>

<%# For form builder, first arg is the method: %>
<%= f.rui_textarea(:body, label: "Content") %>
```

### Content & Binding

- `name_or_method` - First positional argument: name for standalone, method for form builder
- `form` - FormBuilder instance (auto-passed by `f.rui_textarea`)
- `object` - Object to bind to (auto-detected from form)
- `method` - Attribute name keyword (alternative to positional)
- `name` - HTML name attribute keyword (alternative to positional)
- `value` - Textarea content (auto-retrieved from model if bound)

### Display Options

- `rows` - Number of visible text lines (Integer, default: 4)
- `cols` - Visible width in average character widths (Integer, optional)
- `placeholder` - Placeholder text (String)
- `label` - Label text (String)
- `help_text` - Help text shown below textarea (String)

### Validation & Requirements

- `required` - Show required indicator (Boolean, default: false)
- `disabled` - Disable textarea (Boolean, default: false)
- `readonly` - Make textarea readonly (Boolean, default: false)
- `maxlength` - Maximum character length (Integer)
- `minlength` - Minimum character length (Integer)

### Advanced Features

- `show_count` - Show character counter (Boolean, default: false)
- `auto_resize` - Enable auto-resize (Boolean, default: false)
- `max_rows` - Maximum rows when auto_resize enabled (Integer)
- `wrap` - Line break handling (Symbol: `:soft`, `:hard`, `:off`, default: `:soft`)
- `resize` - Manual resize behavior (Symbol: `:none`, `:vertical`, `:horizontal`, `:both`, default: `:vertical`)

### Styling

- `variant` - Visual variant (Symbol: `:default`, `:filled`, `:outline`, default: `:default`)
- `color` - Focus ring color (Symbol: `:default`, `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`)
- `size` - Size (Symbol: `:xs`, `:sm`, `:base`, `:lg`, `:xl`, default: `:base`)
- `shape` - Shape (Symbol: `:square`, `:rounded`, `:pill`, default: `:rounded`)

### Additional Options

- `**options` - Any additional HTML attributes (e.g., `id`, `class`, `data`, `aria`)

## Examples

### Character Counter

```erb
<%= f.rui_textarea(:bio,
  label: "Biography",
  rows: 6,
  maxlength: 500,
  show_count: true,
  help_text: "Tell us about yourself"
) %>
```

Shows: "0 / 500 characters" that updates in real-time.

### Auto-resize

```erb
<%= f.rui_textarea(:content,
  label: "Content",
  rows: 4,
  auto_resize: true,
  max_rows: 20,
  help_text: "Expands as you type"
) %>
```

Grows with content, minimum 4 rows, maximum 20 rows.

### With Styling

```erb
<%= f.rui_textarea(:notes,
  label: "Notes",
  variant: :filled,
  size: :lg,
  color: :primary,
  shape: :rounded
) %>
```

### Disabled Resize

```erb
<%= f.rui_textarea(:description,
  label: "Description",
  resize: :none,
  rows: 6
) %>
```

Users cannot manually resize the textarea.

### Wrap Attribute

```erb
<%# Soft wrap (default) - line breaks only on submit %>
<%= f.rui_textarea(:content, wrap: :soft) %>

<%# Hard wrap - line breaks included in submitted value %>
<%= f.rui_textarea(:content, wrap: :hard) %>

<%# No wrap - no line breaks, horizontal scrolling %>
<%= f.rui_textarea(:content, wrap: :off) %>
```

## Variants

### Default

Standard textarea with white background and border.

```erb
<%= rui_textarea(name: :description, variant: :default) %>
```

### Filled

Textarea with filled gray background.

```erb
<%= rui_textarea(name: :description, variant: :filled) %>
```

### Outline

Transparent background with border.

```erb
<%= rui_textarea(name: :description, variant: :outline) %>
```

## Sizes

- `:xs` - Extra small (min-height: 4rem)
- `:sm` - Small (min-height: 5rem)
- `:base` - Base (min-height: 6rem, default)
- `:lg` - Large (min-height: 7rem)
- `:xl` - Extra large (min-height: 8rem)

## Colors

Focus ring colors:

- `:default` - Zinc focus ring
- `:primary` - Neutral focus ring with background tint
- `:secondary` - Sky focus ring with background tint
- `:success` - Green focus ring with background tint
- `:danger` - Red focus ring with background tint
- `:warning` - Yellow focus ring with background tint
- `:info` - Blue focus ring with background tint

## Accessibility

The component includes:

- Proper `<label>` association via `for` and `id`
- `aria-required` for required fields
- `aria-describedby` linking to help text, validation message, and counter
- `role="alert"` and `aria-live="assertive"` for validation messages
- `aria-live="polite"` for character counter updates
- Required indicator (*) with `aria-label="required"`

## Error State

When used through the form builder (`f.rui_textarea`), errors are detected
automatically from Rails model errors - no extra options needed. This only
works via `f.rui_textarea`; standalone `rui_textarea(object: @post, method:
:body)` does not check model errors.

```erb
<%# If @post.errors[:body] has errors, the textarea shows error styling
    (red border) and the error message text automatically. %>
<%= f.rui_textarea(:body, label: "Content") %>
```

The error message renders inside the *same* validation-message element the
`textarea-validation` Stimulus controller uses for real-time feedback below -
not a second element - so there's no double-rendering. On first paint (e.g. a
422 re-render after a failed `create`/`update`), the server-rendered error
wins; once the user edits the field, client-side validation takes back over.

### 422 re-render example

```ruby
# app/controllers/posts_controller.rb
def create
  @post = Post.new(post_params)
  if @post.save
    redirect_to @post
  else
    render :new, status: :unprocessable_entity
  end
end
```

```erb
<%# app/views/posts/new.html.erb %>
<%= form_with model: @post do |f| %>
  <%= f.rui_textarea(:body, label: "Content", rows: 8) %>
  <%# @post.errors[:body] renders inline automatically if #create failed %>
<% end %>
```

## Real-time Validation

Validation triggers on:

- `input` event (as user types)
- `blur` event (when field loses focus)

Validation feedback:

- **Valid** - Green border, "✓ Valid [field name]" message
- **Invalid** - Red border, specific error message
- **Neutral** - Default border, no message (before user interaction)

Validation uses HTML5 Constraint Validation API:

- `required` - "Field is required"
- `minlength` - "Must be at least X characters"
- `maxlength` - "Must be no more than X characters"

## Auto-resize Behavior

When `auto_resize: true`:

1. Textarea grows as user types
2. Textarea shrinks when content is deleted
3. Never shrinks below `rows` (minimum height)
4. Never grows beyond `max_rows` (if set)
5. Manual `resize` is automatically disabled (set to `:none`)
6. Scrollbar appears only if content exceeds `max_rows`

## Character Counter Behavior

When `show_count: true`:

1. Shows current character count
2. If `maxlength` set, shows "X / Y characters"
3. If no `maxlength`, shows "X characters"
4. Updates in real-time as user types
5. Turns red when over `maxlength`
6. Positioned right-aligned below textarea
7. If `help_text` present, shares row (help text left, counter right)

## Implementation Notes

### Content Between Tags

Unlike input elements, textarea content goes **between tags**, not in a `value` attribute:

```erb

<textarea>Content here

``` The component handles this automatically. ### Auto-resize and Manual Resize When `auto_resize: true`, the component automatically sets `resize: :none` to prevent conflicts between auto-sizing and manual drag-resizing. ### Wrap Attribute - `:soft` (default) - Line breaks appear on screen but not in submitted value - `:hard` - Line breaks included in submitted value (requires `cols` attribute) - `:off` - No line wrapping, horizontal scrolling instead ## Stimulus Controller The component uses `textarea-validation` Stimulus controller for: - Real-time validation with HTML5 Constraint Validation API - Character counter updates - Auto-resize calculations - Visual feedback (border colors, messages) No manual JavaScript needed - everything is handled declaratively via data attributes. --- ## Tooltip (`rui_tooltip`) # Tooltip Component Tooltips display contextual information on hover or focus. They provide supplementary information about an element without cluttering the interface. ## Basic Usage ```erb <%= rui_tooltip(text: "This is a tooltip") do %> Hover over me <% end %> ``` ## Position Tooltips can appear on any side of the trigger element. ```erb <%# Top (default) %> <%= rui_tooltip(text: "Top tooltip", position: :top) do %> Hover me <% end %> <%# Right %> <%= rui_tooltip(text: "Right tooltip", position: :right) do %> Hover me <% end %> <%# Bottom %> <%= rui_tooltip(text: "Bottom tooltip", position: :bottom) do %> Hover me <% end %> <%# Left %> <%= rui_tooltip(text: "Left tooltip", position: :left) do %> Hover me <% end %> ``` ## Colors Tooltip supports ALL Tailwind colors via ColorBuilderHelper, plus special tooltip-specific colors. ### Special Tooltip Colors ```erb <%# Dark (default) - inverts in dark mode %> <%= rui_tooltip(text: "Dark tooltip", color: :dark) do %> Dark <% end %> <%# Light - white background with border %> <%= rui_tooltip(text: "Light tooltip", color: :light) do %> Light <% end %> ``` ### Semantic Colors ```erb <%= rui_tooltip(text: "Primary tooltip", color: :primary) do %> Primary <% end %> <%= rui_tooltip(text: "Success tooltip", color: :success) do %> Success <% end %> <%= rui_tooltip(text: "Warning tooltip", color: :warning) do %> Warning <% end %> <%= rui_tooltip(text: "Danger tooltip", color: :danger) do %> Danger <% end %> <%= rui_tooltip(text: "Info tooltip", color: :info) do %> Info <% end %> ``` ### All Tailwind Colors Use any Tailwind color name directly: ```erb <%# Standard colors %> <%= rui_tooltip(text: "Red tooltip", color: :red) do %> Red <% end %> <%= rui_tooltip(text: "Blue tooltip", color: :blue) do %> Blue <% end %> <%= rui_tooltip(text: "Purple tooltip", color: :purple) do %> Purple <% end %> <%= rui_tooltip(text: "Pink tooltip", color: :pink) do %> Pink <% end %> <%= rui_tooltip(text: "Indigo tooltip", color: :indigo) do %> Indigo <% end %> <%= rui_tooltip(text: "Teal tooltip", color: :teal) do %> Teal <% end %> <%# Bright colors (use darker text for readability) %> <%= rui_tooltip(text: "Amber tooltip", color: :amber) do %> Amber <% end %> <%= rui_tooltip(text: "Lime tooltip", color: :lime) do %> Lime <% end %> <%= rui_tooltip(text: "Yellow tooltip", color: :yellow) do %> Yellow <% end %> ``` ## Sizes Three size variants are available. ```erb <%# Small %> <%= rui_tooltip(text: "Small tooltip", size: :sm) do %> Small <% end %> <%# Base (default) %> <%= rui_tooltip(text: "Base tooltip", size: :base) do %> Base <% end %> <%# Large %> <%= rui_tooltip(text: "Large tooltip", size: :lg) do %> Large <% end %> ``` ## Arrow By default, tooltips show an arrow pointing to the trigger. You can disable it. ```erb <%# With arrow (default) %> <%= rui_tooltip(text: "With arrow", arrow: true) do %> With arrow <% end %> <%# Without arrow %> <%= rui_tooltip(text: "No arrow", arrow: false) do %> No arrow <% end %> ``` ## Trigger Mode Tooltips can be triggered by hover (default) or click. ```erb <%# Hover (default) %> <%= rui_tooltip(text: "Hover tooltip", trigger: :hover) do %> Hover me <% end %> <%# Click %> <%= rui_tooltip(text: "Click tooltip", trigger: :click) do %> Click me <% end %> ``` ## Show Delay Add a delay before the tooltip appears (in milliseconds). ```erb <%= rui_tooltip(text: "Delayed tooltip", delay: 300) do %> Wait 300ms... <% end %> ``` ## Hide Delay Add a delay before the tooltip disappears (in milliseconds). This prevents flickering when moving between adjacent elements. ```erb <%# Tooltip stays visible for 200ms after mouse leaves %> <%= rui_tooltip(text: "Stays a bit longer", hide_delay: 200) do %> Hover me <% end %> <%# Combine both delays %> <%= rui_tooltip(text: "Smooth experience", delay: 100, hide_delay: 300) do %> Hover me <% end %> ``` ## Max Width By default, tooltips don't wrap. Use `max_width` for longer content. ```erb <%= rui_tooltip( text: "This is a longer tooltip that will wrap to multiple lines", max_width: "200px" ) do %> Hover for long tooltip <% end %> ``` ## Subtitle (visible secondary line) Use `subtitle:` when a single line of tooltip text isn't enough context, e.g. icon-only buttons where the icon alone is ambiguous. The subtitle renders below the main text in a smaller, low-emphasis style. Unrelated to `description:`, which is sr-only. ```erb <%= rui_tooltip( text: "Archive lot", subtitle: "Hides from active list; restorable for 30 days" ) do %> <%= rui_icon_button(:archive, "aria-label": "Archive lot") %> <% end %> ``` `subtitle:` and `description:` can be combined (visible second line + sr-only context). ## Screen Reader Description Add extra context for screen readers with `description`. ```erb <%= rui_tooltip( text: "Settings", description: "Opens the application settings panel" ) do %> <%= rui_icon(:settings) %> <% end %> ``` ## With Other Components Tooltips work great with other RapidRailsUI components. ```erb <%# With Button %> <%= rui_tooltip(text: "Save your changes", position: :bottom) do %> <%= rui_button("Save", color: :primary) %> <% end %> <%# With Icon %> <%= rui_tooltip(text: "Help") do %> <%= rui_icon(:help_circle, size: :lg) %> <% end %> <%# With Badge %> <%= rui_tooltip(text: "3 new messages", position: :right) do %> <%= rui_badge(text: "New", color: :primary) %> <% end %> ``` ## Custom ID Provide a custom ID if needed. ```erb <%= rui_tooltip(text: "Custom ID tooltip", id: "my-tooltip") do %> Custom ID <% end %> ``` ## Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `text` | String | **required** | The tooltip text content | | `position` | Symbol | `:top` | Position: `:top`, `:right`, `:bottom`, `:left` | | `description` | String | `nil` | Screen reader description (sr-only, not visible) | | `subtitle` | String | `nil` | Visible secondary line rendered below main text | | `color` | Symbol | `:dark` | Color: Special (`:dark`, `:light`), Semantic (`:primary`, `:success`, `:warning`, `:danger`, `:info`), or any Tailwind color (`:red`, `:blue`, `:purple`, `:pink`, `:amber`, etc.) | | `size` | Symbol | `:base` | Size: `:sm`, `:base`, `:lg` | | `arrow` | Boolean | `true` | Show arrow pointing to trigger | | `trigger` | Symbol | `:hover` | Trigger: `:hover`, `:click` | | `delay` | Integer | `0` | Show delay in milliseconds | | `hide_delay` | Integer | `0` | Hide delay in milliseconds (prevents flickering) | | `max_width` | String | `nil` | Max width (e.g., "200px") | | `id` | String | auto | Custom ID for tooltip | ## Accessibility - Trigger elements have `aria-describedby` linking to the tooltip - Tooltips have `role="tooltip"` and `aria-hidden` managed by JavaScript - Trigger elements are focusable (tabindex="0") - Screen reader descriptions can be added via `description` parameter - Focus events show/hide tooltips for keyboard users ## Dark Mode All color variants include dark mode support. The `dark` color scheme inverts in dark mode (dark background becomes light). --- ## Upload (`rui_upload`) # Upload Component File upload component with two modes: default (styled native input) and dropzone (drag & drop area). ## Features - **Two Modes**: Default styled file input or dropzone with drag & drop - **File Type Restrictions**: Accept parameter with MIME type shortcuts (`:image`, `:pdf`, `:document`, etc.) - **File Size Validation**: Client-side max file size validation - **File Count Limits**: Restrict number of files in multiple mode - **File Preview**: Image thumbnails or file icons with names and sizes - **Remove Files**: Remove files from preview before upload - **Real-time Validation**: Instant feedback for file type, size, and count violations - **Form Integration**: Works with Rails form builders (`f.rui_upload`) - **Accessibility**: Full ARIA support, keyboard navigation - **Dark Mode**: Complete dark mode support ## Basic Usage ### Standalone - Default Mode ```erb <%= rui_upload( name: :avatar, accept: [:image], label: "Profile Picture", help_text: "Upload a profile picture" ) %> ``` ### Standalone - Dropzone Mode ```erb <%= rui_upload( name: :documents, accept: [:pdf, :document], multiple: true, dropzone: true, max_files: 5, max_file_size_bytes: 10.megabytes, label: "Upload Documents" ) %> ``` ### Form Builder Integration ```erb <%= form_with(model: @post) do |f| %> <%= f.rui_upload(:images, accept: [:image], multiple: true, dropzone: true, max_files: 5, max_file_size_bytes: 5.megabytes, label: "Product Images", help_text: "Upload up to 5 product images (JPG, PNG, max 5MB each)" ) %> <% end %> ``` ## Parameters ### Required - `name` or `method` (Symbol/String) - Input name attribute (standalone) or model attribute (form builder) ### File Upload Options - `accept` (Array, String, nil) - Accepted file types - Shortcuts: `:image`, `:video`, `:audio`, `:pdf`, `:document`, `:spreadsheet`, `:presentation`, `:text`, `:archive`, `:font`, `:json`, `:xml` - Custom MIME: `"image/png,image/jpeg,application/pdf"` - Default: nil (all files accepted) - `multiple` (Boolean) - Allow multiple file selection - Default: `false` - `max_files` (Integer) - Maximum TOTAL number of files across all selections/drops combined (when `multiple: true`) - cumulative, not a per-event cap. Selecting 6 files, then dropping 6 more with `max_files: 10` rejects the second drop (it would bring the running total to 12). - Default: `10` - `max_file_size_bytes` (Integer) - Maximum file size in bytes - Default: `nil` (component uses 10MB internally when nil) - Example: `5.megabytes`, `1.gigabyte`, `500.kilobytes` - `max_file_size` (Integer) - **Deprecated** — use `max_file_size_bytes:` instead - `dropzone` (Boolean) - Use dropzone mode with drag & drop - Default: `false` ### Styling Options - `variant` (Symbol) - Visual variant - Options: `:default`, `:filled`, `:outline` - Default: `:default` - `size` (Symbol) - Component size - Options: `:xs`, `:sm`, `:base`, `:lg`, `:xl` - Default: `:base` - `shape` (Symbol) - Border radius - Options: `:square`, `:rounded`, `:pill` - Default: `:rounded` - `color` (Symbol) - Focus ring color - Options: `:default`, `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info` - Default: `:default` ### Form Options - `label` (String, nil) - Label text - `help_text` (String, nil) - Help text below upload - `error` (String, nil) - Error message - `required` (Boolean) - Show required indicator - `disabled` (Boolean) - Disable upload ### HTML Attributes - `**options` (Hash) - Any additional HTML attributes (id, class, data attributes, etc.) ## MIME Type Shortcuts The component provides convenient shortcuts for common file types: ```ruby MIME_TYPES = { image: "image/png,image/jpeg,image/jpg,image/gif,image/webp,image/svg+xml,image/avif", video: "video/mp4,video/webm,video/quicktime,video/mpeg,video/mov", audio: "audio/mpeg,audio/wav,audio/webm,audio/aac,audio/m4a,audio/flac", pdf: "application/pdf", document: "application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document", spreadsheet: "application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", presentation: "application/vnd.ms-powerpoint,application/vnd.openxmlformats-officedocument.presentationml.presentation", text: "text/plain,text/csv,text/html,text/xml,text/css,text/javascript,text/markdown,text/rtf", archive: "application/zip,application/x-rar-compressed,application/x-tar,application/gzip", font: "font/woff,font/woff2,font/ttf,font/otf", json: "application/json", xml: "application/xml,text/xml" } ``` ### Example Usage ```erb <%# Accept only images %> <%= rui_upload(:avatar, accept: [:image]) %> <%# Accept PDFs and Word documents %> <%= rui_upload(:resume, accept: [:pdf, :document]) %> <%# Accept images and videos %> <%= rui_upload(:media, accept: [:image, :video], multiple: true) %> <%# Custom MIME types %> <%= rui_upload(:file, accept: "image/png,image/jpeg") %> ``` ## Examples ### Single Image Upload (Avatar) ```erb <%= form_with(model: @user) do |f| %> <%= f.rui_upload(:avatar, accept: [:image], max_file_size_bytes: 2.megabytes, label: "Profile Picture", help_text: "Upload a JPG or PNG (max 2MB)" ) %> <% end %> ``` ### Multiple Images with Dropzone (Gallery) ```erb <%= form_with(model: @post) do |f| %> <%= f.rui_upload(:images, accept: [:image], multiple: true, max_files: 10, max_file_size_bytes: 5.megabytes, dropzone: true, size: :lg, label: "Product Gallery", help_text: "Drag and drop up to 10 images" ) %> <% end %> ``` ### Document Upload with Mixed Types ```erb <%= rui_upload( name: :attachments, accept: [:pdf, :document, :spreadsheet], multiple: true, max_files: 5, max_file_size_bytes: 10.megabytes, dropzone: true, label: "Upload Documents", help_text: "Accepted: PDF, Word, Excel (max 10MB each)" ) %> ``` ### Styled Upload with Color ```erb <%= f.rui_upload(:resume, accept: [:pdf], variant: :filled, color: :primary, size: :lg, shape: :rounded, label: "Resume/CV", required: true ) %> ``` ## Accessibility The component includes: - Proper `` association with input - ARIA attributes (`aria-required`, `aria-describedby`) - Error messages linked to input - Keyboard navigation support - Screen reader friendly ## Client-Side Validation The component validates: 1. **File Type**: Checked against `accept` MIME types 2. **File Size**: Checked against `max_file_size_bytes` 3. **File Count**: Checked against `max_files` (when `multiple: true`) - cumulative across selections/drops, not per event **Important**: Client-side validation is for UX only. Always validate files on the server. ## Server-Side Integration The component renders a standard file input that works with Rails forms and ActiveStorage: ```ruby # Controller def create @post = Post.new(post_params) if @post.save redirect_to @post else render :new end end private def post_params params.require(:post).permit(:title, :body, images: []) end ``` ## Security Notes - **XSS Prevention**: File names displayed using `textContent` (no HTML injection) - **MIME Type Validation**: Client-side only - always validate on server - **File Size Limits**: Client-side only - always validate on server - **Direct Uploads**: Not implemented in v1 - files sent with form submission ## Implementation Notes - Preview uses `FileReader` API for image thumbnails - Non-image files show extension with generic file icon - Drag & drop only works in dropzone mode - Multiple file selection works in both modes - File preview shows after selection, hidden when empty - Remove file button appears on hover (desktop) or always (mobile)