shadcn-phlex 0.1.0

data/lib/shadcn.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "phlex"
+require "class_variants"
+require "tailwind_merge"
+
+require_relative "shadcn/version"
+require_relative "shadcn/base"
+
+# UI Components
+require_relative "shadcn/ui/accordion"
+require_relative "shadcn/ui/alert"
+require_relative "shadcn/ui/alert_dialog"
+require_relative "shadcn/ui/aspect_ratio"
+require_relative "shadcn/ui/avatar"
+require_relative "shadcn/ui/badge"
+require_relative "shadcn/ui/breadcrumb"
+require_relative "shadcn/ui/button"
+require_relative "shadcn/ui/button_group"
+require_relative "shadcn/ui/card"
+require_relative "shadcn/ui/checkbox"
+require_relative "shadcn/ui/collapsible"
+require_relative "shadcn/ui/command"
+require_relative "shadcn/ui/combobox"
+require_relative "shadcn/ui/context_menu"
+require_relative "shadcn/ui/dialog"
+require_relative "shadcn/ui/direction"
+require_relative "shadcn/ui/drawer"
+require_relative "shadcn/ui/dropdown_menu"
+require_relative "shadcn/ui/empty"
+require_relative "shadcn/ui/field"
+require_relative "shadcn/ui/hover_card"
+require_relative "shadcn/ui/input"
+require_relative "shadcn/ui/input_group"
+require_relative "shadcn/ui/input_otp"
+require_relative "shadcn/ui/item"
+require_relative "shadcn/ui/kbd"
+require_relative "shadcn/ui/label"
+require_relative "shadcn/ui/menubar"
+require_relative "shadcn/ui/native_select"
+require_relative "shadcn/ui/navigation_menu"
+require_relative "shadcn/ui/pagination"
+require_relative "shadcn/ui/popover"
+require_relative "shadcn/ui/progress"
+require_relative "shadcn/ui/radio_group"
+require_relative "shadcn/ui/resizable"
+require_relative "shadcn/ui/scroll_area"
+require_relative "shadcn/ui/select"
+require_relative "shadcn/ui/separator"
+require_relative "shadcn/ui/sheet"
+require_relative "shadcn/ui/sidebar"
+require_relative "shadcn/ui/skeleton"
+require_relative "shadcn/ui/slider"
+require_relative "shadcn/ui/sonner"
+require_relative "shadcn/ui/spinner"
+require_relative "shadcn/ui/switch"
+require_relative "shadcn/ui/table"
+require_relative "shadcn/ui/tabs"
+require_relative "shadcn/ui/textarea"
+require_relative "shadcn/ui/toggle"
+require_relative "shadcn/ui/toggle_group"
+require_relative "shadcn/ui/tooltip"
+require_relative "shadcn/ui/typography"
+require_relative "shadcn/ui/theme_toggle"
+require_relative "shadcn/ui/text_field"
+
+# Kit module (short helpers)
+require_relative "shadcn/kit"
+
+# Theme system
+require_relative "shadcn/themes/base_colors"
+require_relative "shadcn/themes/accent_colors"
+
+# Rails engine (loaded conditionally)
+require_relative "shadcn/engine" if defined?(Rails::Engine)
+
+module Shadcn
+  module UI
+  end
+end

data/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "shadcn-phlex",
+  "version": "0.1.0",
+  "description": "Complete shadcn/ui component library for Phlex Rails with Stimulus controllers",
+  "type": "module",
+  "main": "js/controllers/index.js",
+  "exports": {
+    ".": "./js/controllers/index.js",
+    "./controllers/*": "./js/controllers/*"
+  },
+  "dependencies": {
+    "@hotwired/stimulus": "^3.2.0"
+  }
+}

data/skills/shadcn-phlex/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: shadcn-phlex
+description: Build UIs with shadcn-phlex — the complete shadcn/ui component library for Phlex Rails. Provides component APIs, composition patterns, form integration, theming, Stimulus controller wiring, and best practices for building Rails views with Phlex components that match shadcn/ui exactly. Applies when working with Phlex views, shadcn-phlex components, or any project with shadcn-phlex in the Gemfile.
+user-invocable: false
+license: MIT
+compatibility: Claude Code 1.0+, Cursor, Windsurf, Cline, Copilot
+allowed-tools: Bash(bundle *) Bash(ruby *) Read Write Edit Glob Grep
+metadata:
+  author: shadcn-phlex
+  version: "0.1.0"
+---
+
+# shadcn-phlex
+
+A complete port of shadcn/ui to Phlex for Ruby on Rails. Components are used directly from the gem or copied into the project via generators. All interactive components include Stimulus controllers that replicate Radix UI behavior.
+
+> **IMPORTANT:** All components use `ui_*` Kit helper methods when `Shadcn::Kit` is included. Examples below use Kit helpers. Without Kit, use `render Shadcn::UI::ComponentName.new(**attrs) { block }`.
+
+## Current Project Context
+
+```bash
+# Check installation and configuration
+grep "shadcn-phlex" Gemfile
+ls app/components/shadcn/ui/ 2>/dev/null || echo "Using gem directly"
+cat app/assets/stylesheets/shadcn-theme.css 2>/dev/null
+grep "Shadcn::Kit" app/views/application_view.rb app/components/application_component.rb 2>/dev/null
+```
+
+## Principles
+
+1. **Use existing components first.** Check the component catalog below before writing custom markup. Use `Separator` not `<hr>`, `Skeleton` not manual pulse divs, `Badge` not styled spans.
+2. **Compose, don't reinvent.** Settings page = Tabs + Card + TextField. Dashboard = Sidebar + Card + Table.
+3. **Use built-in variants before custom classes.** `variant: :outline`, `size: :sm`, etc.
+4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
+5. **Kit helpers always.** `ui_button { "Click" }` not `render Shadcn::UI::Button.new { "Click" }`.
+
+## Critical Rules
+
+These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
+
+### Styling & Tailwind → [styling.md](./rules/styling.md)
+
+- **`class:` for layout, not styling.** Never override component colors or typography.
+- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `div(class: "flex flex-col gap-4")`.
+- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
+- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
+- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
+- **Use `cn()` in custom components.** Inherit from `Shadcn::Base` to get the `cn()` helper for conditional classes.
+- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.
+
+### Forms & Inputs → [forms.md](./rules/forms.md)
+
+- **Use `TextField`/`TextareaField` for common fields.** One-liner instead of manual Field + Label + Input + FieldError.
+- **Form controls need `name:` for submission.** Checkbox, Switch, Select, RadioGroup, Slider, Combobox are purely visual without it.
+- **`Fieldset` + `FieldsetLegend` for grouping related checkboxes/radios.** Not a div with a heading.
+- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
+- **Validation: pass `error:` to TextField** or set `aria_invalid: true` on the control + `data_disabled: true` on Field.
+
+### Component Structure → [composition.md](./rules/composition.md)
+
+- **Items always inside their parent.** `SelectItem` inside `SelectContent`. `DropdownMenuItem` inside `DropdownMenuContent`. `CommandItem` inside `CommandGroup`.
+- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `class: "sr-only"` if visually hidden.
+- **Use components instead of custom markup.** `Alert` for callouts, `Empty` for blank states, `Separator` instead of `hr`, `Skeleton` for loading, `Badge` not styled spans.
+- **Button has no loading prop.** Compose with `Spinner` and `disabled:`.
+
+### Stimulus → [stimulus.md](./rules/stimulus.md)
+
+- **Never manually add `data-controller`, `data-action`, or `data-*-target`.** Components wire Stimulus automatically.
+- **All 24 interactive components are pre-wired.** Just use the components.
+
+## Component Selection
+
+| Need | Components |
+|------|-----------|
+| **Button/Action** | `Button`, `ButtonGroup`, `Toggle`, `ToggleGroup` |
+| **Form field** | `TextField` / `TextareaField` (compound), or `Field` + `Label` + `Input`/`Textarea` + `FieldError` (manual) |
+| **Selection** | `Checkbox`, `Switch`, `RadioGroup`, `Select`, `Combobox` |
+| **Toggle between few options** | `ToggleGroup` + `ToggleGroupItem` |
+| **Card/Container** | `Card` + `CardHeader`/`CardTitle`/`CardContent`/`CardFooter` |
+| **Dialog/Modal** | `Dialog` (closes on overlay click) or `AlertDialog` (does not) |
+| **Slide panel** | `Sheet` + `SheetContent(side: :right)` |
+| **Bottom drawer** | `Drawer` + `DrawerContent` |
+| **Dropdown** | `DropdownMenu` + trigger + content + items |
+| **Right-click** | `ContextMenu` + trigger + content + items |
+| **Tabs** | `Tabs` + `TabsList` + `TabsTrigger` + `TabsContent` |
+| **Accordion** | `Accordion` + `AccordionItem` + trigger + content |
+| **Feedback** | `Alert`, `Badge`, `Progress`, `Skeleton`, `Spinner`, `Toaster`/`Toast` |
+| **Tooltip** | `Tooltip` + `TooltipTrigger` + `TooltipContent` |
+| **Popover** | `Popover` + `PopoverTrigger` + `PopoverContent` |
+| **Hover info** | `HoverCard` + `HoverCardTrigger` + `HoverCardContent` |
+| **Table** | `Table` + `TableHeader`/`TableBody`/`TableRow`/`TableHead`/`TableCell` |
+| **Navigation** | `Breadcrumb`, `Pagination`, `NavigationMenu`, `Menubar`, `Sidebar` |
+| **Data display** | `Avatar`, `Kbd`, `Empty`, `Item`, `Separator` |
+| **Theme** | `ThemeToggle` for dark mode |
+| **Command palette** | `Command` + `CommandDialog` + `CommandInput` + `CommandList` + `CommandGroup` + `CommandItem` |
+| **Loading state** | Use `Skeleton` for content placeholders, `Spinner` for inline loading |
+| **Callout/Banner** | `Alert` + `AlertTitle` + `AlertDescription` (not a custom div) |
+| **Empty state** | `Empty` + `EmptyMedia` + `EmptyTitle` + `EmptyDescription` + `EmptyActions` |
+| **Typography** | `TypographyH1`..`H4`, `TypographyP`, `TypographyLead`, `TypographyMuted` |
+
+### Choosing overlays
+
+| Situation | Component |
+|-----------|-----------|
+| Needs user decision, blocks interaction | `AlertDialog` |
+| Form or content, closeable | `Dialog` |
+| Side panel (settings, details) | `Sheet` |
+| Mobile-friendly bottom panel | `Drawer` |
+| Small interactive content on click | `Popover` |
+| Rich preview on hover | `HoverCard` |
+| Short text hint on hover | `Tooltip` |
+
+### Choosing form controls
+
+| Situation | Component |
+|-----------|-----------|
+| Simple text input | `Input` (or `TextField` compound) |
+| Dropdown with options | `Select` |
+| Searchable dropdown | `Combobox` |
+| Native HTML select | `NativeSelect` |
+| Boolean toggle (settings) | `Switch` |
+| Boolean toggle (forms/T&C) | `Checkbox` |
+| Single choice from few options | `RadioGroup` |
+| Toggle between 2-5 options | `ToggleGroup` |
+| OTP/verification code | `InputOTP` |
+| Multi-line text | `Textarea` (or `TextareaField` compound) |
+| Numeric range | `Slider` |
+
+## Workflow
+
+When asked to build UI with Phlex:
+
+1. **Check context** — is shadcn-phlex in Gemfile? Is `Shadcn::Kit` included in the base view?
+2. **Select components** — use the tables above to pick the right components for each need
+3. **Compose** — build the UI using Kit helpers, nesting compound components correctly
+4. **Wire forms** — add `name:` to all form controls, use `TextField`/`TextareaField` for common patterns
+5. **Review** — check composition rules (titles required, items in parents, semantic colors)
+
+## Component API Quick Reference
+
+See [references/component-catalog.md](references/component-catalog.md) for the full API of every component.
+
+### Most-used patterns:
+
+```ruby
+# Simple form
+ui_card do
+  ui_card_header { ui_card_title { "Profile" } }
+  ui_card_content do
+    ui_text_field(label: "Name", name: "user[name]", error: @user.errors[:name]&.first)
+    ui_text_field(label: "Email", name: "user[email]", type: "email")
+  end
+  ui_card_footer do
+    ui_button { "Save" }
+  end
+end
+
+# Confirmation dialog
+ui_alert_dialog do
+  ui_alert_dialog_trigger { ui_button(variant: :destructive) { "Delete" } }
+  ui_alert_dialog_content do
+    ui_alert_dialog_header do
+      ui_alert_dialog_title { "Are you sure?" }
+      ui_alert_dialog_description { "This action cannot be undone." }
+    end
+    ui_alert_dialog_footer do
+      ui_alert_dialog_cancel { "Cancel" }
+      ui_alert_dialog_action { "Delete" }
+    end
+  end
+end
+
+# Data table
+ui_table do
+  ui_table_header do
+    ui_table_row do
+      ui_table_head { "Name" }
+      ui_table_head { "Email" }
+    end
+  end
+  ui_table_body do
+    @users.each do |user|
+      ui_table_row do
+        ui_table_cell { user.name }
+        ui_table_cell { user.email }
+      end
+    end
+  end
+end
+```

data/skills/shadcn-phlex/evals/evals.json

@@ -0,0 +1,90 @@
+[
+  {
+    "prompt": "Create a settings page with a name field, email field, and save button using shadcn-phlex",
+    "expected_behaviors": [
+      "Uses ui_card or ui_card_content for layout",
+      "Uses ui_text_field for form fields (not raw ui_field + ui_label + ui_input)",
+      "Includes name: parameter on form controls",
+      "Uses ui_button for the save button",
+      "Does not hardcode colors (uses semantic tokens)"
+    ]
+  },
+  {
+    "prompt": "Add a confirmation dialog that asks 'Are you sure?' before deleting an item",
+    "expected_behaviors": [
+      "Uses ui_alert_dialog (not ui_dialog) since overlay click should not close",
+      "Includes ui_alert_dialog_trigger with a destructive button",
+      "Uses ui_alert_dialog_header with title and description",
+      "Uses ui_alert_dialog_footer with cancel and action buttons",
+      "Cancel uses ui_alert_dialog_cancel, action uses ui_alert_dialog_action"
+    ]
+  },
+  {
+    "prompt": "Create a tabs component with Account and Password tabs",
+    "expected_behaviors": [
+      "Uses ui_tabs with an initial value",
+      "Each ui_tabs_trigger has a value: parameter",
+      "Each ui_tabs_content has a matching value: parameter",
+      "Trigger values match content values exactly"
+    ]
+  },
+  {
+    "prompt": "Build a form with checkboxes for Terms and Marketing opt-in",
+    "expected_behaviors": [
+      "Uses ui_checkbox with name: parameter for form submission",
+      "Associates each checkbox with a label",
+      "Does not manually add data-controller or data-action attributes"
+    ]
+  },
+  {
+    "prompt": "Create a dropdown menu with Edit, Duplicate, and Delete options",
+    "expected_behaviors": [
+      "Uses ui_dropdown_menu with trigger and content",
+      "Delete item uses variant: :destructive",
+      "Uses ui_dropdown_menu_separator between groups",
+      "Does not manually wire Stimulus controllers"
+    ]
+  },
+  {
+    "prompt": "Add a select dropdown for choosing a country in a form",
+    "expected_behaviors": [
+      "Uses ui_select with name: parameter",
+      "Includes ui_select_trigger wrapping ui_select_value with placeholder",
+      "Uses ui_select_content wrapping ui_select_item components",
+      "Each ui_select_item has a value: parameter"
+    ]
+  },
+  {
+    "prompt": "Create an accordion FAQ section",
+    "expected_behaviors": [
+      "Uses ui_accordion with type and collapsible options",
+      "Each item has ui_accordion_item wrapping trigger + content",
+      "Uses ui_accordion_trigger for the question",
+      "Uses ui_accordion_content for the answer"
+    ]
+  },
+  {
+    "prompt": "Show a loading skeleton for a card",
+    "expected_behaviors": [
+      "Uses ui_card for the container",
+      "Uses ui_skeleton for placeholder elements",
+      "Applies appropriate width/height classes to skeletons"
+    ]
+  },
+  {
+    "prompt": "Add a dark mode toggle to the navbar",
+    "expected_behaviors": [
+      "Uses ui_theme_toggle component",
+      "Does not manually implement dark mode logic"
+    ]
+  },
+  {
+    "prompt": "Create a data table showing users with name, email, and role columns",
+    "expected_behaviors": [
+      "Uses ui_table with header and body",
+      "Uses ui_table_header, ui_table_body, ui_table_row",
+      "Uses ui_table_head for header cells, ui_table_cell for body cells",
+      "Iterates over data collection for rows"
+    ]
+  }
+]