RubyGems - shadcn-rails - Versions diffs - 0.2.0 → 0.2.1 - Mend

shadcn-rails 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (152) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +66 -2
data/README.md +21 -8
data/__mocks__/@floating-ui/dom.js +67 -0
data/app/assets/javascripts/shadcn/controllers/combobox_controller.js +23 -2
data/app/assets/javascripts/shadcn/controllers/context_menu_controller.js +4 -31
data/app/assets/javascripts/shadcn/controllers/dropdown_controller.js +32 -41
data/app/assets/javascripts/shadcn/controllers/hover_card_controller.js +29 -55
data/app/assets/javascripts/shadcn/controllers/popover_controller.js +29 -54
data/app/assets/javascripts/shadcn/controllers/select_controller.js +26 -8
data/app/assets/javascripts/shadcn/controllers/tooltip_controller.js +28 -59
data/app/assets/javascripts/shadcn/index.js +7 -1
data/app/assets/javascripts/shadcn/utils/floating.js +179 -0
data/app/assets/stylesheets/shadcn/base.css +32 -0
data/app/components/shadcn/accordion_component.html.erb +8 -0
data/app/components/shadcn/accordion_component.rb +6 -15
data/app/components/shadcn/alert_component.html.erb +6 -0
data/app/components/shadcn/alert_component.rb +0 -18
data/app/components/shadcn/alert_dialog_component.html.erb +12 -0
data/app/components/shadcn/alert_dialog_component.rb +7 -27
data/app/components/shadcn/aspect_ratio_component.html.erb +7 -0
data/app/components/shadcn/aspect_ratio_component.rb +4 -19
data/app/components/shadcn/avatar_component.html.erb +20 -0
data/app/components/shadcn/avatar_component.rb +8 -36
data/app/components/shadcn/badge_component.html.erb +1 -0
data/app/components/shadcn/badge_component.rb +0 -11
data/app/components/shadcn/base_component.rb +15 -2
data/app/components/shadcn/breadcrumb_component.html.erb +5 -0
data/app/components/shadcn/breadcrumb_component.rb +6 -16
data/app/components/shadcn/button_component.html.erb +18 -0
data/app/components/shadcn/button_component.rb +1 -41
data/app/components/shadcn/card_component.html.erb +8 -0
data/app/components/shadcn/card_component.rb +2 -6
data/app/components/shadcn/checkbox_component.html.erb +32 -0
data/app/components/shadcn/checkbox_component.rb +4 -43
data/app/components/shadcn/collapsible_component.html.erb +8 -0
data/app/components/shadcn/collapsible_component.rb +6 -15
data/app/components/shadcn/context_menu_component.html.erb +11 -0
data/app/components/shadcn/context_menu_component.rb +6 -26
data/app/components/shadcn/dialog_component.html.erb +14 -0
data/app/components/shadcn/dialog_component.rb +8 -29
data/app/components/shadcn/drawer_component.html.erb +12 -0
data/app/components/shadcn/drawer_component.rb +7 -27
data/app/components/shadcn/dropdown_menu_component.html.erb +14 -0
data/app/components/shadcn/dropdown_menu_component.rb +9 -29
data/app/components/shadcn/field_component.rb +7 -8
data/app/components/shadcn/hover_card_component.html.erb +12 -0
data/app/components/shadcn/hover_card_component.rb +7 -26
data/app/components/shadcn/input_component.html.erb +18 -0
data/app/components/shadcn/input_component.rb +2 -27
data/app/components/shadcn/input_otp_component.rb +3 -3
data/app/components/shadcn/kbd_component.html.erb +1 -0
data/app/components/shadcn/kbd_component.rb +3 -10
data/app/components/shadcn/label_component.html.erb +3 -0
data/app/components/shadcn/label_component.rb +2 -18
data/app/components/shadcn/menubar_component.html.erb +6 -0
data/app/components/shadcn/menubar_component.rb +4 -15
data/app/components/shadcn/native_select_component.html.erb +22 -0
data/app/components/shadcn/native_select_component.rb +9 -39
data/app/components/shadcn/navigation_menu_component.html.erb +6 -0
data/app/components/shadcn/navigation_menu_component.rb +4 -15
data/app/components/shadcn/pagination_component.html.erb +5 -0
data/app/components/shadcn/pagination_component.rb +11 -15
data/app/components/shadcn/popover_component.html.erb +15 -0
data/app/components/shadcn/popover_component.rb +10 -30
data/app/components/shadcn/progress_component.html.erb +13 -0
data/app/components/shadcn/progress_component.rb +6 -26
data/app/components/shadcn/radio_group_component.html.erb +8 -0
data/app/components/shadcn/radio_group_component.rb +12 -26
data/app/components/shadcn/scroll_area_component.html.erb +7 -0
data/app/components/shadcn/scroll_area_component.rb +4 -16
data/app/components/shadcn/select_component.html.erb +46 -0
data/app/components/shadcn/select_component.rb +6 -80
data/app/components/shadcn/separator_component.html.erb +5 -0
data/app/components/shadcn/separator_component.rb +6 -14
data/app/components/shadcn/sheet_component.html.erb +12 -0
data/app/components/shadcn/sheet_component.rb +7 -27
data/app/components/shadcn/sidebar_component.rb +2 -2
data/app/components/shadcn/skeleton_component.html.erb +1 -0
data/app/components/shadcn/skeleton_component.rb +4 -2
data/app/components/shadcn/slider_component.html.erb +12 -0
data/app/components/shadcn/slider_component.rb +2 -21
data/app/components/shadcn/spinner_component.html.erb +18 -0
data/app/components/shadcn/spinner_component.rb +2 -30
data/app/components/shadcn/switch_component.html.erb +72 -0
data/app/components/shadcn/switch_component.rb +4 -82
data/app/components/shadcn/table_component.html.erb +9 -0
data/app/components/shadcn/table_component.rb +2 -10
data/app/components/shadcn/tabs_component.html.erb +8 -0
data/app/components/shadcn/tabs_component.rb +4 -17
data/app/components/shadcn/textarea_component.html.erb +13 -0
data/app/components/shadcn/textarea_component.rb +6 -22
data/app/components/shadcn/toast_component.html.erb +36 -0
data/app/components/shadcn/toast_component.rb +6 -54
data/app/components/shadcn/toggle_component.html.erb +12 -0
data/app/components/shadcn/toggle_component.rb +6 -21
data/app/components/shadcn/toggle_group_component.html.erb +14 -0
data/app/components/shadcn/toggle_group_component.rb +6 -29
data/app/components/shadcn/tooltip_component.html.erb +20 -0
data/app/components/shadcn/tooltip_component.rb +13 -38
data/lib/generators/shadcn/add/USAGE +24 -0
data/lib/generators/shadcn/add/add_generator.rb +279 -0
data/lib/generators/shadcn/install/USAGE +22 -0
data/lib/generators/shadcn/install/install_generator.rb +8 -3
data/lib/generators/shadcn/install/templates/initializer.rb.tt +7 -27
data/lib/generators/shadcn/install/templates/shadcn.yml.tt +15 -31
data/lib/shadcn/rails/version.rb +1 -1
metadata +47 -45
data/.dockerignore +0 -40
data/CLAUDE.md +0 -612
data/PROGRESS.md +0 -495
data/Rakefile +0 -95
data/__tests__/controllers/__snapshots__/calendar_controller.test.js.snap +0 -13
data/__tests__/controllers/__snapshots__/popover_controller.test.js.snap +0 -46
data/__tests__/controllers/__snapshots__/sheet_controller.test.js.snap +0 -111
data/__tests__/controllers/__snapshots__/tabs_controller.test.js.snap +0 -27
data/__tests__/controllers/accordion_controller.test.js +0 -904
data/__tests__/controllers/calendar_controller.test.js +0 -1370
data/__tests__/controllers/carousel_controller.test.js +0 -912
data/__tests__/controllers/checkbox_controller.test.js +0 -454
data/__tests__/controllers/collapsible_controller.test.js +0 -407
data/__tests__/controllers/combobox_controller.test.js +0 -971
data/__tests__/controllers/context_menu_controller.test.js +0 -905
data/__tests__/controllers/date_picker_controller.test.js +0 -636
data/__tests__/controllers/dialog_controller.test.js +0 -878
data/__tests__/controllers/drawer_controller.test.js +0 -995
data/__tests__/controllers/menubar_controller.test.js +0 -737
data/__tests__/controllers/navigation_menu_controller.test.js +0 -599
data/__tests__/controllers/popover_controller.test.js +0 -982
data/__tests__/controllers/radio_group_controller.test.js +0 -640
data/__tests__/controllers/resizable_controller.test.js +0 -680
data/__tests__/controllers/select_controller.test.js +0 -678
data/__tests__/controllers/sheet_controller.test.js +0 -986
data/__tests__/controllers/slider_controller.test.js +0 -1036
data/__tests__/controllers/switch_controller.test.js +0 -424
data/__tests__/controllers/tabs_controller.test.js +0 -907
data/__tests__/controllers/toggle_group_controller.test.js +0 -839
data/__tests__/controllers/tooltip_controller.test.js +0 -808
data/__tests__/helpers/stimulus-test-helper.js +0 -203
data/babel.config.cjs +0 -5
data/bin/bump +0 -321
data/bin/console +0 -11
data/bin/release +0 -205
data/bin/setup +0 -8
data/bin/test +0 -75
data/jest.config.js +0 -19
data/jest.setup.js +0 -8
data/lib/generators/shadcn/component/component_generator.rb +0 -188
data/lib/generators/shadcn/theme/theme_generator.rb +0 -128
data/package-lock.json +0 -7438
data/package.json +0 -71
data/rollup.config.js +0 -29

data/CLAUDE.md DELETED Viewed

@@ -1,612 +0,0 @@
-# CLAUDE.md - Development Guide for shadcn-rails
-This document contains learnings, patterns, and guidelines for future development sessions on this project.
-## Project Overview
-shadcn-rails is a Ruby port of [shadcn/ui](https://ui.shadcn.com) for Rails applications. It uses:
-- **ViewComponent** for Ruby-based component architecture
-- **Stimulus** for JavaScript interactivity
-- **Tailwind CSS** for styling
-- **CSS Custom Properties** for theming
-## Architecture Patterns
-### Component Structure
-All components inherit from `Shadcn::BaseComponent` which provides:
-- `cn(*classes)` - Class name merging utility (like clsx + tailwind-merge)
-- `stimulus_data(controller, values, actions)` - Stimulus data attribute builder
-- `build_html_attributes(**attrs)` - HTML attribute builder with class merging
-```ruby
-# app/components/shadcn/base_component.rb
-class Shadcn::BaseComponent < ViewComponent::Base
-  include Shadcn::Rails::Helpers::ClassNameHelper
-  def cn(*classes)
-    Shadcn::Rails.cn(*classes)
-  end
-end
-```
-### Component Location
-Components are located in `app/components/shadcn/`:
-- Each component is a single Ruby file (e.g., `button_component.rb`)
-- Complex components use ViewComponent slots for composition
-- ERB templates are inline using `erb_template` when simple, or separate `.html.erb` files when complex
-### Stimulus Controllers
-Controllers are in `app/assets/javascripts/shadcn/controllers/`:
-- Named `{component}_controller.js`
-- Use Stimulus naming convention: `shadcn--{component}`
-- Handle interactivity: open/close states, keyboard navigation, focus management
-```javascript
-// Example controller pattern
-import { Controller } from "@hotwired/stimulus"
-export default class extends Controller {
-  static targets = ["trigger", "content"]
-  static values = { open: Boolean }
-  toggle() {
-    this.openValue = !this.openValue
-  }
-  openValueChanged() {
-    // React to state changes
-  }
-}
-```
-### CSS Theming
-CSS variables are defined in `app/assets/stylesheets/shadcn/base.css`:
-- All colors use HSL format without `hsl()` wrapper: `--primary: 0 0% 9%;`
-- Components use: `hsl(var(--primary))`
-- Dark mode uses `.dark` class on `<html>` element
-Theme presets are in `lib/shadcn/rails/configuration.rb` with full HSL values for:
-- neutral, slate, stone, zinc, gray
-## Key Files
-### Core Library
-- `lib/shadcn/rails.rb` - Main module, configuration, `cn()` helper
-- `lib/shadcn/rails/engine.rb` - Rails engine setup
-- `lib/shadcn/rails/configuration.rb` - Theme configuration with CSS variables
-- `lib/shadcn/rails/class_merger.rb` - Tailwind class conflict resolution
-### Components (app/components/shadcn/)
-The library includes 47 components organized by category:
-**Buttons & Actions**
-| File | Description |
-|------|-------------|
-| `button_component.rb` | 6 variants (default, secondary, destructive, outline, ghost, link), 6 sizes |
-| `toggle_component.rb` | Two-state button with pressed/unpressed states |
-| `toggle_group_component.rb` | Group of toggle buttons (single/multiple selection) |
-| `button_group_component.rb` | Group of related buttons |
-**Form Inputs**
-| File | Description |
-|------|-------------|
-| `input_component.rb` | Text input with various types |
-| `textarea_component.rb` | Multi-line text input |
-| `label_component.rb` | Form label element |
-| `checkbox_component.rb` | Checkbox with indeterminate state support |
-| `switch_component.rb` | Toggle switch control |
-| `slider_component.rb` | Range slider input |
-| `select_component.rb` | Custom styled select dropdown |
-| `native_select_component.rb` | Native HTML select with styling |
-| `radio_group_component.rb` | Radio button group |
-| `field_component.rb` | Form field wrapper with label/error slots |
-| `input_group_component.rb` | Input with prefix/suffix addons |
-| `input_otp_component.rb` | One-time password input |
-**Data Display**
-| File | Description |
-|------|-------------|
-| `badge_component.rb` | Labels with variants (default, secondary, destructive, outline) |
-| `avatar_component.rb` | User avatar with image/fallback |
-| `card_component.rb` | Header, content, footer slots |
-| `table_component.rb` | Styled table with header/body/footer |
-| `progress_component.rb` | Progress bar indicator |
-| `skeleton_component.rb` | Loading placeholder |
-| `spinner_component.rb` | Loading spinner animation |
-| `kbd_component.rb` | Keyboard key display |
-| `typography_component.rb` | Text styling utilities |
-| `aspect_ratio_component.rb` | Maintains aspect ratio for media content |
-| `scroll_area_component.rb` | Custom scrollbar container |
-**Feedback**
-| File | Description |
-|------|-------------|
-| `alert_component.rb` | Callout/notification with variants (default, destructive) |
-| `tooltip_component.rb` | Hover tooltip popup |
-| `toast_component.rb` | Temporary notification messages |
-**Overlays**
-| File | Description |
-|------|-------------|
-| `dialog_component.rb` | Modal with portal, focus trap |
-| `alert_dialog_component.rb` | Confirmation dialog with cancel/confirm actions |
-| `sheet_component.rb` | Slide-out panel from any edge |
-| `drawer_component.rb` | Bottom sheet drawer |
-| `popover_component.rb` | Floating content panel |
-| `hover_card_component.rb` | Card that appears on hover |
-| `dropdown_menu_component.rb` | Dropdown menu with items, separators, keyboard shortcuts |
-**Navigation**
-| File | Description |
-|------|-------------|
-| `tabs_component.rb` | Tabbed interface with URL sync support |
-| `accordion_component.rb` | Collapsible sections (single/multiple mode) |
-| `breadcrumb_component.rb` | Navigation breadcrumb trail |
-| `pagination_component.rb` | Page navigation with Kaminari/Pagy/WillPaginate support |
-| `collapsible_component.rb` | Show/hide content section |
-| `separator_component.rb` | Visual divider line |
-| `context_menu_component.rb` | Right-click context menu |
-| `menubar_component.rb` | Horizontal menu bar with dropdowns |
-| `navigation_menu_component.rb` | Navigation with dropdown content |
-| `resizable_component.rb` | Resizable panel groups |
-### Generators (lib/generators/shadcn/)
-- `install/` - Initial setup generator
-- `component/` - Add individual components
-- `theme/` - Switch color themes
-### Tests
-- `test/components/` - Component unit tests
-- `test/components/previews/` - Lookbook previews
-- `test/dummy/` - Rails dummy app for integration testing
-## Development Commands
-```bash
-# Install dependencies
-bundle install
-# Run tests
-bundle exec rake test
-# Run component tests only
-bundle exec rake test_components
-# Build JavaScript (from project root)
-npm run build
-# Start dummy app for local development (RECOMMENDED)
-cd test/dummy && bin/dev
-# Start Lookbook previews
-cd test/dummy && rails lookbook:preview
-```
-## Local Testing with bin/dev
-**IMPORTANT**: Always use `bin/dev` instead of `rails server` when testing locally. This ensures:
-1. JavaScript is automatically rebuilt when files change (via esbuild watch mode)
-2. CSS is automatically rebuilt when Tailwind classes change
-3. Changes to Stimulus controllers are immediately available
-```bash
-# Start the development server (from test/dummy)
-cd test/dummy && bin/dev
-# If port 3000 is in use, kill existing processes first:
-lsof -ti:3000 | xargs kill -9 2>/dev/null
-rm -f tmp/pids/server.pid
-bin/dev
-```
-The development server runs:
-- Rails server on port 3000
-- esbuild in watch mode for JavaScript bundling
-- Tailwind CSS in watch mode
-**Note**: After modifying Stimulus controllers in `app/assets/javascripts/shadcn/controllers/`, you must also run `npm run build` from the project root to update the npm package distribution files.
-## Regression Testing
-When making changes to interactive components, always verify:
-### Context Menu
-1. **Open/Close**: Right-click to open, click outside or press Escape to close
-2. **Double right-click**: Right-clicking twice in quick succession should reposition the menu
-3. **Keyboard navigation**: Arrow keys, Home/End, Enter/Space for selection
-4. **Scroll lock**: Background should not scroll when menu is open
-5. **Animation**: Smooth fade-in/out animation (100ms)
-6. **Positioning**: Menu stays within viewport bounds
-### Radio Group
-1. **Labels are clickable**: Clicking the label should select the radio
-2. **Descriptions render**: Items with descriptions show them below the label
-3. **Keyboard navigation**: Tab to focus, arrow keys to move between items
-4. **Single selection**: Only one item can be selected at a time
-### Dropdown Menu
-1. **All item types**: Test items, checkboxes, radio groups, separators, labels
-2. **Keyboard shortcuts**: Display correctly with proper styling
-3. **Submenus**: Open on hover, close when moving away
-### Dialog/Sheet/Drawer
-1. **Focus trap**: Tab should cycle within the modal
-2. **Escape closes**: Pressing Escape should close the modal
-3. **Overlay click**: Clicking the overlay should close (unless modal)
-4. **Body scroll lock**: Background should not scroll when open
-### Testing with Playwright
-Use the MCP Playwright tools for automated testing:
-```javascript
-// Navigate to docs page
-mcp__playwright__browser_navigate({ url: "http://localhost:3000/docs/context-menu" })
-// Take a snapshot to see the page state
-mcp__playwright__browser_snapshot()
-// Right-click to open context menu (use browser_run_code for context menu)
-mcp__playwright__browser_run_code({
-  code: `await page.locator('[data-shadcn--context-menu-target="trigger"]').click({ button: 'right' })`
-})
-// Press Escape to close
-mcp__playwright__browser_press_key({ key: "Escape" })
-```
-### Bug-Fixing Workflow
-**IMPORTANT**: When fixing reported bugs, follow this workflow:
-1. **Reproduce via Playwright** - Use MCP Playwright tools to confirm the bug exists
-2. **Write a failing Jest test** - Create a test in `__tests__/controllers/` that captures the bug
-3. **Fix the bug** - Update the controller/component code
-4. **Verify Jest test passes** - Run `npm test` to confirm the fix
-5. **Verify via Playwright** - Use MCP Playwright again to confirm the bug is fixed
-This ensures:
-- Bugs are properly understood before fixing
-- Regression tests prevent the bug from returning
-- Fixes are verified both in isolation (Jest) and integration (Playwright)
-```bash
-# Run Jest tests
-npm test
-# Run specific test file
-npm test -- context_menu_controller.test.js
-# Run tests with coverage
-npm test -- --coverage
-```
-## Test-First Development
-**IMPORTANT**: Always run tests for files you modify to ensure they still pass.
-### Testing Guidelines
-1. **Before making changes**: Run relevant tests to understand current behavior
-2. **After making changes**: Run all affected tests to ensure nothing breaks
-3. **When fixing bugs**: Write a failing test first, then fix the bug
-4. **When adding features**: Write tests alongside the new code
-### Running Tests
-```bash
-# Run all Ruby tests
-bundle exec rake test
-# Run specific component test
-bundle exec ruby -Ilib:test test/components/context_menu_component_test.rb
-# Run all Jest tests
-npm test
-# Run specific Jest test file
-npm test -- context_menu_controller.test.js
-# Run tests with coverage
-npm test -- --coverage
-```
-### Test Coverage Expectations
-- **Ruby Components**: Each component should have tests for:
-  - Default rendering
-  - All variants and sizes
-  - Slot rendering
-  - Accessibility attributes (ARIA)
-  - Custom class names and HTML options
-- **JavaScript Controllers**: Each Stimulus controller should have tests for:
-  - Initialization and connect
-  - Value changes
-  - Target interactions
-  - Event handling (click, keyboard, etc.)
-  - Edge cases and error handling
-  - Cleanup on disconnect
-## Patterns to Follow
-### 1. Component Variants
-Use symbols for variant options and define them as constants:
-```ruby
-VARIANTS = {
-  default: "bg-primary text-primary-foreground",
-  destructive: "bg-destructive text-destructive-foreground",
-  outline: "border border-input bg-background",
-  secondary: "bg-secondary text-secondary-foreground",
-  ghost: "hover:bg-accent hover:text-accent-foreground",
-  link: "text-primary underline-offset-4 hover:underline"
-}
-def initialize(variant: :default, **attrs)
-  @variant = variant.to_sym
-end
-```
-### 2. Compound Components with Slots
-Use ViewComponent's `renders_one` and `renders_many` for composition:
-```ruby
-renders_one :header, "HeaderComponent"
-renders_many :items, "ItemComponent"
-class HeaderComponent < ViewComponent::Base
-  renders_one :title
-  renders_one :description
-end
-```
-### 3. Stimulus Integration
-Components that need JavaScript should:
-1. Define a Stimulus controller
-2. Use `stimulus_data()` helper in the component
-3. Follow the `shadcn--{name}` naming convention
-```ruby
-def stimulus_attributes
-  stimulus_data(
-    "shadcn--dialog",
-    { open: @open },
-    { "trigger->click": "toggle" }
-  )
-end
-```
-### 4. Accessibility (ARIA)
-All interactive components must include proper ARIA attributes:
-- `role` attributes where needed
-- `aria-expanded`, `aria-hidden`, `aria-controls`
-- `aria-labelledby`, `aria-describedby` for relationships
-- Keyboard navigation support
-### 5. CSS Class Merging
-Always use `cn()` for class composition to handle Tailwind conflicts:
-```ruby
-def classes
-  cn(
-    "base-classes here",
-    VARIANTS[@variant],
-    SIZES[@size],
-    @class_name
-  )
-end
-```
-### 6. Test Coverage
-For each component, create tests in `test/components/`:
-- Test default rendering
-- Test all variants
-- Test all sizes (if applicable)
-- Test slot rendering
-- Test accessibility attributes
-```ruby
-class ButtonComponentTest < ViewComponent::TestCase
-  def test_renders_button
-    render_inline(Shadcn::ButtonComponent.new) { "Click" }
-    assert_selector "button", text: "Click"
-  end
-  def test_renders_variants
-    Shadcn::ButtonComponent::VARIANTS.keys.each do |variant|
-      render_inline(Shadcn::ButtonComponent.new(variant: variant)) { "Test" }
-      assert_selector "button"
-    end
-  end
-end
-```
-## Adding New Components
-1. Create component file in `app/components/shadcn/{name}_component.rb`
-2. Inherit from `Shadcn::BaseComponent`
-3. If interactive, create Stimulus controller in `app/assets/javascripts/shadcn/controllers/{name}_controller.js`
-4. Add controller export to `app/assets/javascripts/shadcn/index.js`
-5. Create test in `test/components/{name}_component_test.rb`
-6. Create Lookbook preview in `test/components/previews/{name}_component_preview.rb`
-7. Add example to dummy app views
-## Common Issues & Solutions
-### ViewComponent Preview Nested Render Issue
-**Problem**: When using nested `render()` calls inside ViewComponent preview slots, the output is a hash like `{args: {}, block: #<Proc:...>, component: #<...>}` instead of rendered HTML.
-**Solution**: Use raw HTML strings instead of nested render calls in previews:
-```ruby
-# BAD - nested render returns hash, not HTML
-def default
-  render(Shadcn::DialogComponent.new) do |dialog|
-    dialog.with_trigger do
-      render(Shadcn::ButtonComponent.new(variant: :outline)) { "Open" }  # Returns hash!
-    end
-  end
-end
-# GOOD - use raw HTML strings or helper methods
-def default
-  render(Shadcn::DialogComponent.new) do |dialog|
-    dialog.with_trigger do
-      button_html(:outline, "Open")  # Returns HTML string
-    end
-  end
-end
-private
-def button_html(variant, text, extra_class = nil)
-  # Generate HTML string directly
-  %(<button class="#{classes}">#{text}</button>).html_safe
-end
-```
-### Superclass Mismatch Error
-**Problem**: Rails throws "superclass mismatch for class X" error for nested component classes (e.g., `DialogContentComponent`).
-**Cause**: Rails Zeitwerk autoloading gets confused when nested classes are reloaded and the parent class definition has changed.
-**Solution**: Restart the Rails server to clear cached class definitions. This commonly happens when modifying component files with nested classes.
-### Tailwind Class Conflicts
-The `ClassMerger` utility handles conflicts like `p-2 p-4` (p-4 wins). If you encounter unresolved conflicts, add the pattern to `CLASS_GROUPS` or `CONFLICT_PATTERNS` in `lib/shadcn/rails/class_merger.rb`.
-**Pattern Ordering Issue**: When adding regex patterns to `CONFLICT_PATTERNS`, be careful of pattern matching order. The `find_conflict_group` method returns on the first match, so patterns must use negative lookaheads to exclude overlapping cases.
-Example fix for border classes:
-```ruby
-# PROBLEM: border-0 was matching border_color before border_width
-/^border-(?!solid|dashed|dotted|double|none)/ => :border_color,
-# SOLUTION: Add [0-9] to the negative lookahead to exclude border widths
-/^border-(?!solid|dashed|dotted|double|none|[0-9])/ => :border_color,
-```
-This ensures `border-0`, `border-2`, etc. are categorized as `:border_width` (not `:border_color`) so they properly conflict with and override `border`.
-### Stimulus Controller Not Loading
-Ensure:
-1. Controller is exported in `index.js`
-2. Controller name matches: `shadcn--{name}`
-3. User has called `registerShadcnControllers(application)` or manually registered
-### Preview Layout Requirements
-The `component_preview.html.erb` layout must include:
-1. **Tailwind CSS** via CDN with custom shadcn color tokens
-2. **Stimulus application** initialized and connected
-3. **Inline Stimulus controllers** for all interactive components (Dialog, Sheet, Tabs, Accordion, Checkbox, Switch, Popover, Tooltip)
-4. **CSS animations** for transitions (dialog fade-in, sheet slide-in, etc.)
-For previews, Stimulus controllers are inlined directly in the layout since the JavaScript bundling isn't available. This is different from production where controllers come from the npm package.
-### Tabs Controller Method Names
-The Tabs Stimulus controller uses `selectTab` for the click action, not `select`:
-```javascript
-// In tabs_controller.js
-selectTab(event) {
-  const trigger = event.currentTarget
-  const value = trigger.dataset.value
-  this.valueValue = value
-}
-```
-Ensure your triggers use: `data-action="click->shadcn--tabs#selectTab"`
-### Dark Mode Not Working
-Check:
-1. CSS variables are loaded
-2. `.dark` class is on `<html>` element (not `<body>`)
-3. Tailwind dark mode is configured as `class` strategy
-## Documentation Site
-The `test/dummy` app serves as both a testing environment and documentation site. It includes:
-- Full documentation for all 47 components at `/docs`
-- Live interactive examples that demonstrate each component
-- Code examples stored in `app/code_examples/{component}/` as `.txt` files
-- `erb_example` helper to display code examples with syntax highlighting
-- Showcase page at `/showcase`
-### Documentation Structure
-```
-test/dummy/
-├── app/
-│   ├── views/docs/           # Component documentation pages
-│   │   ├── button.html.erb
-│   │   ├── dialog.html.erb
-│   │   └── ...
-│   ├── code_examples/        # Code examples displayed in docs
-│   │   ├── button/
-│   │   │   └── default.txt
-│   │   └── pagination/
-│   │       ├── kaminari_view.txt
-│   │       └── pagy_view.txt
-│   └── helpers/
-│       └── docs_helper.rb    # erb_example helper method
-```
-## Future Improvements
-**Missing Components** (from shadcn/ui):
-- [ ] Command palette
-- [ ] Combobox
-- [ ] Date Picker
-- [ ] Calendar
-- [ ] Sonner (toast alternative)
-- [ ] Carousel
-- [ ] Chart
-- [ ] Data Table
-- [ ] Sidebar
-**Enhancements**:
-- [ ] Form builder integration (Rails form helpers)
-- [ ] Hotwire/Turbo Stream integration helpers
-- [ ] RTL support
-- [ ] Visual regression tests with Percy or similar
-- [ ] Dropdown Menu submenus and checkbox/radio items
-- [ ] Drawer gesture support (touch drag to dismiss)
-**Completed**:
-- [x] 47 core components implemented
-- [x] Full documentation site with live examples
-- [x] Stimulus controllers for all interactive components
-- [x] Pagination with Kaminari/Pagy/WillPaginate adapters
-- [x] CSS animations for dialogs, sheets, toasts, accordions
-- [x] Context Menu component
-- [x] Menubar component
-- [x] Navigation Menu component
-- [x] Resizable panels component
-- [x] Input OTP with group separators
-## Resources
-- [shadcn/ui Documentation](https://ui.shadcn.com)
-- [ViewComponent Guide](https://viewcomponent.org)
-- [Stimulus Handbook](https://stimulus.hotwired.dev/handbook/introduction)
-- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
-- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)