railsui 3.2.7 → 3.3.0

data/app/views/railsui/themes/shepherd/authentication/static/_overview.html.erb

@@ -18,7 +18,6 @@
   </div>
 </div>
 
-
 <div id="auth-global-layout" class="py-6">
 
   <div class="prose prose-neutral dark:prose-invert my-6">
@@ -188,17 +187,18 @@
   </div>
 <%% end %>
 <% end %>
-
+<%= render_snippet active_tab: :erb %>
 <% end %>
 </div>
 
 <%= system_pagination(prev_path: systems_authentication_devise_unlocks_path, prev_text: "Devise: Unlocks", next_path: systems_authentication_static_signup_path, next_text: "Sign up") %>
 
 <%= content_for :component_nav do %>
-<%= render layout: "railsui/shared/component_nav", locals: { title: "On this page" } do %>
-<%= component_link "Prerequisites", "#auth-prerequisites" %>
-<%= component_link "Layout", "#auth-global-layout" %>
-<%= component_link "OmniAuth", "#auth-omniauth-ui" %>
-<%= component_link "Error messages", "#auth-error-messages" %>
-<% end %>
+  <%= render layout: "railsui/shared/component_nav", locals: { title: "On this page" } do %>
+    <%= component_link "Prerequisites", "#auth-prerequisites" %>
+    <%= component_link "Layout", "#auth-global-layout" %>
+    <%= component_link "OmniAuth", "#auth-omniauth-ui" %>
+    <%= component_link "Error messages", "#auth-error-messages" %>
+    <% end %>
+  <% end %>
 <% end %>

data/app/views/railsui/themes/shepherd/content/typography/_headings.html.erb

@@ -43,42 +43,44 @@
     <% end %>
   </div>
 
-
-<% content_for :example do %>
-<%# snippet content :html %>
-<% content_for :html, flush: true do %>
+  <% content_for :example do %>
+    <%# snippet content :html %>
+    <% content_for :html, flush: true do %>
 <h1 class="h1">A quick brown fox jumps over the lazy dog.</h1>
 <h2 class="h2">A quick brown fox jumps over the lazy dog.</h2>
 <h3 class="h3">A quick brown fox jumps over the lazy dog.</h3>
 <h4 class="h4">A quick brown fox jumps over the lazy dog.</h4>
 <h5 class="h5">A quick brown fox jumps over the lazy dog.</h5>
 <h6 class="h6">A quick brown fox jumps over the lazy dog.</h6>
-<% end %>
-<%# snippet content :erb %>
-  <% content_for :erb, flush: true do %>
-<%%= content_tag :h1, "A quick brown fox jumps over the lazy dog.", class: "text-5xl font-semibold font-heading text-zinc-900 dark:text-zinc-100 -tracking-[0.03em]" %>
-<%%= content_tag :h2, "A quick brown fox jumps over the lazy dog.", class: "text-4xl font-semibold font-heading text-zinc-900 dark:text-zinc-100 tracking-tight" %>
+    <% end %>
+    <%# snippet content :erb %>
+    <% content_for :erb, flush: true do %>
+<%%= content_tag :h1, "A quick brown fox jumps over the lazy dog.", class: "h1" %>
+<%%= content_tag :h2, "A quick brown fox jumps over the lazy dog.", class: "h2" %>
 <%%= content_tag :h3, "A quick brown fox jumps over the lazy dog.", class: "h3" %>
 <%%= content_tag :h4, "A quick brown fox jumps over the lazy dog.", class: "h4" %>
 <%%= content_tag :h5, "A quick brown fox jumps over the lazy dog.", class: "h5" %>
 <%%= content_tag :h6, "A quick brown fox jumps over the lazy dog.", class: "h6" %>
+    <% end %>
   <% end %>
-</div>
-
-<div id="typography-responsive" class="prose prose-netural dark:prose-invert max-w-full prose-headings:tracking-tight">
-<h3>Responsive heading design</h3>
-<p>Change heading sizes relative to viewports with Tailwind CSS responsive utilities.</p>
 
-<div class="not-prose">
-<% content_for :html, flush: true do %>
-  <h1 class="md:h1 h2">My sample title</h1>
+  <%= render_snippet %>
 <% end %>
+</div>
 
+<div id="typography-responsive" class="prose prose-netural dark:prose-invert max-w-full prose-headings:tracking-tight">
+  <h3>Responsive heading design</h3>
+  <p>Change heading sizes relative to viewports with Tailwind CSS responsive utilities.</p>
 
-<% content_for :erb, flush: true do %>
+  <div class="not-prose">
+    <% content_for :html, flush: true do %>
+      <h1 class="md:h1 h2">My sample title</h1>
+    <% end %>
 
-<% end %>
+    <% content_for :erb, flush: true do %>
+      <%%= content_tag :h1, "My sample title", class: "md:h1 h2" %>
+    <% end %>
 
-<%= render_snippet %>
-</div>
+    <%= render_snippet %>
+  </div>
 </div>

data/app/views/railsui/themes/shepherd/forms/_input.html.erb

@@ -434,10 +434,10 @@ application.register('railsui-date-range-picker', RailsuiDateRangePicker)
 <% end %>
 <% end %>
 </div>
+</div>
 
 <%= system_pagination(prev_path: systems_forms_path, prev_text: "Forms", next_path: systems_forms_input_group_path, next_text: "Input Group") %>
 
-
 <%= content_for :component_nav do %>
   <%= render layout: "railsui/shared/component_nav", locals: { title: "On this page" } do %>
     <%= component_link "Input", "#input-input" %>

data/guides/CONFIGURATION.md

@@ -0,0 +1,199 @@
+# Configuration guide
+
+This guide covers configuring Rails UI for your application, including build modes, themes, and customization options.
+
+## Table of Contents
+
+- [Configuration file](#configuration-file)
+- [Build mode configuration](#build-mode-configuration)
+- [Color and theme customization](#color-and-theme-customization)
+
+---
+
+## Configuration file
+
+Rails UI stores its configuration in:
+
+```
+config/railsui.yml
+```
+
+This file is automatically created during installation and can be edited manually or via the admin UI at `/railsui`.
+
+---
+
+## Build mode configuration
+
+Rails UI supports two JavaScript build modes. This setting determines how JavaScript is loaded and processed.
+
+### Build mode options
+
+#### Option 1: No-build mode (importmap) - default
+
+Nobuild mode is the default for Rails UI v3.3+. Simply running the installer `rails railsui:install` after adding the `railsui_pro` gem to your app's Gemfile gets everything set up using importmaps.
+
+**Best for**: Simple apps, prototypes, apps without complex JS requirements
+
+```yaml
+# config/railsui.yml
+application_name: My App
+support_email: support@example.com
+theme: hound
+build_mode: nobuild
+pages:
+  - dashboard
+  - pricing
+  - ...
+```
+
+**Characteristics:**
+- ✅ Zero build step for JavaScript
+- ✅ No Node.js required
+- ✅ JavaScript loaded from CDN via importmap
+- ✅ Fast refresh during development
+- ✅ Simpler deployment
+- ⚠️ Less control over JS bundling
+- ⚠️ Requires internet for CDN dependencies (dev mode)
+
+**Development server:**
+```bash
+bin/dev
+# Runs: Rails server + Tailwind CSS watcher only
+```
+
+#### Option 2: Build Mode
+
+**Best for**: Production apps, TypeScript projects, complex JS requirements
+
+To install, run the installer with the `--build` flag:
+
+`rails railsui:install --build`
+
+If already installed you may modify your `railsui.yml` file.
+
+```yaml
+# config/railsui.yml
+application_name: My App
+support_email: support@example.com
+theme: hound
+build_mode: build
+pages:
+  - dashboard
+  - pricing
+  - ...
+```
+
+**Characteristics:**
+- ✅ Full control over JavaScript bundling
+- ✅ Supports TypeScript, JSX, advanced tooling
+- ✅ Tree-shaking and optimization
+- ✅ Works offline
+- ⚠️ Requires Node.js and package manager
+- ⚠️ Additional build step
+- ⚠️ Slightly more complex deployment
+
+**Development server:**
+```bash
+bin/dev
+# Runs: Rails server + Tailwind CSS watcher + JS bundler watcher
+```
+
+**Supported JS bundlers:**
+- Bun
+- esbuild
+- Rollup
+- Webpack
+---
+
+## Color and theme customization
+
+Most themes include primary and secondary color palettes in addition to Tailwind CSS v4 defaults. Colors are defined in CSS using Tailwind CSS v4.
+
+
+**Step 1**: Edit `app/assets/stylesheets/railsui/theme.css`
+
+**Step 2**: Update color or utility values based on Tailwind CSS:
+
+For colors, we like using a tool like [Tailwind Color Generator](https://uicolors.app/create) to generate a complete color palette or [https://www.tints.dev/](https://www.tints.dev/) to generate oklch colors which have a wider gamut.
+
+```css
+@theme {
+  /* Your brand colors */
+  --color-primary-500: #3b82f6;
+  --color-primary-600: #2563eb;
+  /* ... update other shades ... */
+}
+```
+
+**Step 3**: Rebuild CSS or reboot server:
+
+```bash
+rails tailwindcss:build
+```
+
+### Using Colors in Templates
+
+Colors are available via Tailwind utility classes:
+
+```html
+<!-- Primary colors -->
+<button class="bg-primary-600 hover:bg-primary-700 text-white">
+  Click me
+</button>
+
+<!-- Secondary colors -->
+<div class="border-secondary-200 bg-secondary-50">
+  Content
+</div>
+```
+
+### Validating Configuration
+
+Rails UI validates configuration on save. Invalid config will raise errors:
+
+**Valid values:**
+- `application_name`: Non-empty string
+- `support_email`: Valid email format
+- `theme`: One of: `hound`, `shepherd`, `corgie`
+- `build_mode`: One of: `build`, `nobuild`
+- `pages`: Array of strings
+
+**Example validation error:**
+```
+❌ Configuration validation failed:
+  - Invalid theme: 'custom'. Available themes: hound, shepherd, corgie, ...
+  - Invalid email format for support_email: 'not-an-email'
+```
+
+### Loading configuration programmatically
+
+While you can do this, it's likely easier to visit `/railsui` locally to update these values in the form and click `Save Changes`. 
+
+```ruby
+# Load current configuration
+config = Railsui::Configuration.load!
+
+# Access values
+puts config.theme          # => "hound"
+puts config.build_mode     # => "nobuild"
+puts config.nobuild?       # => true
+puts config.build?         # => false
+
+# Update configuration
+config.theme = "shepherd"
+config.save
+
+# Update with hash
+Railsui::Configuration.update(
+  theme: "shepherd",
+  application_name: "New Name"
+)
+```
+
+---
+
+## Getting Help
+
+- **Documentation**: https://railsui.com/docs
+- **Discussions**: https://github.com/getrailsui/railsui/discussions
+- **Issues**: https://github.com/getrailsui/railsui/issues

data/guides/MIGRATION_GUIDE.md

@@ -0,0 +1,220 @@
+# Rails UI Migration Guide
+
+Covers migrating existing installations and common upgrade scenarios.
+
+## Table of Contents
+
+- [Migrating from cssbundling-rails to tailwindcss-rails](#migrating-from-cssbundling-rails-to-tailwindcss-rails)
+- [Upgrading from v3.2 and Earlier](#upgrading-from-v32-and-earlier)
+- [Switching Between Build Modes](#switching-between-build-modes)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Migrating from cssbundling-rails to tailwindcss-rails
+
+Rails UI v3.3+ uses `tailwindcss-rails` to support #nobuild, faster builds, and requires fewer dependencies.
+
+### Automatic Migration (easy mode)
+
+If you app previously used `cssbundling-rails`, you can migrate to `tailwindcss-rails` with the following command:
+
+```bash
+rails railsui:migrate_to_tailwindcss_rails
+```
+
+This will:
+- Install tailwindcss-rails gem
+- Remove Tailwind packages from package.json
+- Update your Procfile.dev
+- Create new CSS file at `app/assets/tailwind/application.css`
+- **Preserve your old CSS file** for manual migration
+
+**Important**: Your existing `app/assets/stylesheets/application.tailwind.css` is preserved. Manually copy any custom CSS, `@import` statements, or legacy styles to `app/assets/tailwind/application.css`.
+
+### Migrating Custom CSS
+
+Copy your customizations from the old file to the new one:
+
+```css
+/* Old: app/assets/stylesheets/application.tailwind.css Tailwind v3 */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@import "custom/buttons";
+.my-custom-component { /* ... */ }
+```
+
+```css
+/* New: app/assets/tailwind/application.css */
+@import "tailwindcss";
+
+@import "custom/buttons";
+.my-custom-component { /* ... */ }
+```
+
+The `@import "tailwindcss";` directive replaces the three separate `@tailwind` directives (Tailwind v4 syntax).
+
+---
+
+## Upgrading from v3.2 and Earlier
+
+### Quick Upgrade
+
+```bash
+bundle update railsui
+rails railsui:migrate_to_tailwindcss_rails
+rails generate railsui:update
+bin/dev
+```
+
+### What Changed
+
+- **CSS**: Now uses `tailwindcss-rails` instead of `cssbundling-rails`
+- **Default mode**: No-build (importmap), like Rails 8
+- **Installation**: Use `--build` flag to opt into build mode for JS bundling.
+
+### New installation workflow
+
+```bash
+# nobuild mode (default)
+rails new myapp
+bundle add railsui
+rails railsui:install
+
+# build mode (with JS bundler)
+rails new myapp -j [bun|esbuild|rollup|webpack]
+bundle add railsui
+rails railsui:install --build
+```
+
+The TL;DR;: No need to use `-c tailwind` anymore - Rails UI handles CSS via the tailwindcss-rails gem.
+
+---
+
+## Switching between build modes
+
+You can switch between nobuild (importmaps) and build (JS bundler) modes anytime though we'd suggest picking one path and sticking to it for less complexity.
+
+### Switch to nobuild mode
+
+```bash
+# 1. Install importmap-rails if needed
+bundle add importmap-rails
+rails importmap:install
+
+# 2. Update config/railsui.yml
+# Change: build_mode: nobuild
+
+# 3. Regenerate Rails UI assets
+rails generate railsui:update
+
+# 4. Update Procfile.dev (remove js line):
+# web: bin/rails server
+# css: bin/rails tailwindcss:watch
+
+# 5. Restart server
+bin/dev
+```
+
+### Switch to build mode
+
+```bash
+# 1. Install jsbundling-rails and a bundler
+bundle add jsbundling-rails
+rails javascript:install:[bun|esbuild|rollup|webpack]
+
+# 2. Update config/railsui.yml
+# Change: build_mode: build
+
+# 3. Regenerate Rails UI assets
+rails generate railsui:update
+
+# 4. Install JS dependencies
+yarn install
+
+# 5. Update Procfile.dev (add js line):
+# web: bin/rails server
+# css: bin/rails tailwindcss:watch
+# js: yarn build:js --watch
+
+# 6. Restart server
+bin/dev
+```
+
+## Troubleshooting
+
+### CSS not compiling
+
+```bash
+rails tailwindcss:build
+rails tmp:clear
+bin/dev
+```
+
+Check that `Procfile.dev` includes `css: bin/rails tailwindcss:watch`.
+
+### JavaScript not loading (no-build mode)
+
+Check `config/importmap.rb` for required pins:
+```bash
+cat config/importmap.rb
+```
+
+Should include: `@hotwired/stimulus`, `railsui-stimulus`, `stimulus-use`, `tippy.js`, and theme dependencies.
+
+If missing:
+```bash
+bundle add importmap-rails
+rails importmap:install
+```
+
+### JavaScript not loading (build mode)
+
+Ensure JS bundler is running in `Procfile.dev`:
+```
+js: yarn build:js --watch
+```
+
+Install dependencies:
+```bash
+yarn install
+yarn build:js
+```
+
+### Conflicting Tailwind versions
+
+Remove Tailwind from package.json:
+```bash
+yarn remove tailwindcss @tailwindcss/cli @tailwindcss/typography
+rails tailwindcss:build
+```
+
+Verify only the gem is installed:
+```bash
+ls node_modules | grep tailwind  # Should be empty
+bundle list | grep tailwindcss   # Should show tailwindcss-rails
+```
+
+### Getting Help
+
+- Documentation: https://railsui.com/docs
+- Issues: https://github.com/getrailsui/railsui/issues
+- Discussions: https://github.com/getrailsui/railsui/discussions
+
+---
+
+## Quick Reference
+
+```bash
+# Migration
+rails railsui:migrate_to_tailwindcss_rails
+
+# Rebuild assets
+rails tailwindcss:build
+yarn build:js  # (build mode only)
+
+# Update Rails UI (regenerates assets for current build mode)
+rails generate railsui:update
+```