shadcn-phlex 0.1.0

data/skills/shadcn-phlex/rules/forms.md

@@ -0,0 +1,151 @@
+# Forms & Inputs
+
+## Use TextField / TextareaField for common fields
+
+Always use compound field helpers for standard labeled inputs — never manual Field + Label + Input + FieldError.
+
+### Incorrect
+
+```ruby
+ui_field do
+  ui_label(for: "email") { "Email" }
+  ui_input(name: "user[email]", id: "email", type: "email",
+           aria_invalid: @user.errors[:email].any? ? "true" : nil)
+  if @user.errors[:email].any?
+    ui_field_error { @user.errors[:email].first }
+  end
+end
+```
+
+### Correct
+
+```ruby
+ui_text_field(
+  label: "Email",
+  name: "user[email]",
+  type: "email",
+  error: @user.errors[:email]&.first
+)
+```
+
+---
+
+## Form controls need `name:` for submission
+
+Custom controls are **purely visual** without `name:`. The hidden `<input>` is only rendered when `name:` is provided.
+
+### Incorrect — data won't submit
+
+```ruby
+ui_checkbox(checked: @user.terms_accepted)
+ui_switch(checked: @user.notifications)
+ui_select do
+  ui_select_trigger { ui_select_value(placeholder: "Role") }
+  ui_select_content { ui_select_item(value: "admin") { "Admin" } }
+end
+```
+
+### Correct — data submits
+
+```ruby
+ui_checkbox(name: "user[terms_accepted]", checked: @user.terms_accepted)
+ui_switch(name: "user[notifications]", checked: @user.notifications)
+ui_select(name: "user[role]") do
+  ui_select_trigger { ui_select_value(placeholder: "Role") }
+  ui_select_content { ui_select_item(value: "admin") { "Admin" } }
+end
+```
+
+---
+
+## Choosing form controls
+
+| Situation | Component |
+|-----------|-----------|
+| Simple text input | `TextField` (compound) or `Input` |
+| Dropdown with predefined options | `Select` |
+| Searchable dropdown | `Combobox` |
+| Native HTML select (no JS) | `NativeSelect` |
+| Boolean toggle (settings page) | `Switch` |
+| Boolean agree/accept (forms, T&C) | `Checkbox` |
+| Single choice from few options | `RadioGroup` |
+| Toggle between 2–5 options | `ToggleGroup` |
+| OTP/verification code | `InputOTP` |
+| Multi-line text | `TextareaField` (compound) or `Textarea` |
+| Numeric range | `Slider` |
+
+---
+
+## Option sets (2–7 choices) use ToggleGroup
+
+Don't loop Button with manual active state.
+
+### Incorrect
+
+```ruby
+%w[daily weekly monthly].each do |option|
+  ui_button(variant: @selected == option ? :default : :outline) { option }
+end
+```
+
+### Correct
+
+```ruby
+ui_toggle_group do
+  ui_toggle_group_item(value: "daily") { "Daily" }
+  ui_toggle_group_item(value: "weekly") { "Weekly" }
+  ui_toggle_group_item(value: "monthly") { "Monthly" }
+end
+```
+
+---
+
+## Fieldset + FieldsetLegend for grouping related fields
+
+Use `Fieldset` + `FieldsetLegend` for related checkboxes, radios, or switches — not a div with a heading.
+
+### Incorrect
+
+```ruby
+div do
+  h3(class: "text-sm font-medium") { "Preferences" }
+  ui_checkbox(name: "prefs[dark]")
+  ui_label { "Dark mode" }
+end
+```
+
+### Correct
+
+```ruby
+ui_fieldset do
+  ui_fieldset_legend { "Preferences" }
+  ui_field do
+    ui_checkbox(name: "prefs[dark]")
+    ui_label { "Dark mode" }
+  end
+end
+```
+
+---
+
+## Validation
+
+Pass `error:` to compound fields, or use `aria_invalid:` on controls directly.
+
+```ruby
+# Compound (recommended)
+ui_text_field(label: "Email", name: "email", error: @errors[:email]&.first)
+
+# Manual
+ui_field do
+  ui_label { "Email" }
+  ui_input(name: "email", aria_invalid: @errors[:email] ? "true" : nil)
+  ui_field_error { @errors[:email].first } if @errors[:email]
+end
+```
+
+## Checkbox / Switch values
+
+- `checked: true` → hidden input `value="1"`
+- `checked: false` → hidden input `value="0"`
+- The Stimulus controller updates the value on toggle

data/skills/shadcn-phlex/rules/helpers.md

@@ -0,0 +1,54 @@
+# Kit Helper Rules
+
+When `Shadcn::Kit` is included in a Phlex view, always use the `ui_*` helper methods. They are shorter, compose naturally, and are the idiomatic way to use shadcn-phlex.
+
+## Incorrect
+
+```ruby
+class MyView < ApplicationView
+  include Shadcn::Kit
+
+  def view_template
+    # Don't use render with Kit included
+    render Shadcn::UI::Card.new do
+      render Shadcn::UI::CardHeader.new do
+        render Shadcn::UI::CardTitle.new { "Title" }
+      end
+      render Shadcn::UI::CardContent.new do
+        render Shadcn::UI::Button.new(variant: :default) { "Click" }
+      end
+    end
+  end
+end
+```
+
+## Correct
+
+```ruby
+class MyView < ApplicationView
+  include Shadcn::Kit
+
+  def view_template
+    ui_card do
+      ui_card_header do
+        ui_card_title { "Title" }
+      end
+      ui_card_content do
+        ui_button { "Click" }
+      end
+    end
+  end
+end
+```
+
+## Helper Naming Convention
+
+Every component has a `ui_` prefixed snake_case helper:
+
+- `Shadcn::UI::Button` → `ui_button`
+- `Shadcn::UI::CardHeader` → `ui_card_header`
+- `Shadcn::UI::DialogContent` → `ui_dialog_content`
+- `Shadcn::UI::DropdownMenuItem` → `ui_dropdown_menu_item`
+- `Shadcn::UI::TextField` → `ui_text_field`
+
+The `ui_` prefix exists to avoid collisions with Phlex's built-in HTML methods (`label`, `input`, `button`, `select`, `table`, `p`).

data/skills/shadcn-phlex/rules/stimulus.md

@@ -0,0 +1,61 @@
+# Stimulus Controller Rules
+
+All interactive components are **pre-wired** with Stimulus controllers. Never manually add `data-controller`, `data-action`, or `data-*-target` attributes — the Phlex components handle this automatically.
+
+## Incorrect — manually adding Stimulus attributes
+
+```ruby
+div(data_controller: "shadcn--dialog", data_shadcn__dialog_open_value: false) do
+  button(data_action: "click->shadcn--dialog#show") { "Open" }
+  div(data_shadcn__dialog_target: "content") { "Content" }
+end
+```
+
+## Correct — use the components, they wire everything
+
+```ruby
+ui_dialog do
+  ui_dialog_trigger { "Open" }
+  ui_dialog_content do
+    ui_dialog_title { "Title" }
+    # ...
+  end
+end
+```
+
+## Pre-wired components
+
+These components automatically include Stimulus controller wiring:
+
+| Component | Controller | Behavior |
+|-----------|-----------|----------|
+| `Accordion` | `shadcn--accordion` | Expand/collapse, keyboard nav |
+| `Checkbox` | `shadcn--checkbox` | Toggle checked state |
+| `Collapsible` | `shadcn--collapsible` | Animated open/close |
+| `Combobox` | `shadcn--combobox` | Search, filter, select |
+| `Command` | `shadcn--command` | Cmd+K palette, search |
+| `ContextMenu` | `shadcn--context-menu` | Right-click menu |
+| `Dialog` | `shadcn--dialog` | Focus trap, scroll lock, escape |
+| `Drawer` | `shadcn--drawer` | Swipe to dismiss |
+| `DropdownMenu` | `shadcn--dropdown-menu` | Click toggle, keyboard nav |
+| `HoverCard` | `shadcn--hover-card` | Delayed hover show/hide |
+| `Menubar` | `shadcn--menubar` | Horizontal menu, arrow keys |
+| `NavigationMenu` | `shadcn--navigation-menu` | Hover submenus |
+| `Popover` | `shadcn--popover` | Click toggle, positioning |
+| `RadioGroup` | `shadcn--radio-group` | Single selection, arrows |
+| `ScrollArea` | `shadcn--scroll-area` | Custom scrollbar |
+| `Select` | `shadcn--select` | Custom dropdown, keyboard |
+| `Sheet` | `shadcn--sheet` | Slide panel, focus trap |
+| `Slider` | `shadcn--slider` | Drag, arrow keys |
+| `Switch` | `shadcn--switch` | Toggle on/off |
+| `Tabs` | `shadcn--tabs` | Tab switching, arrow keys |
+| `Toggle` | `shadcn--toggle` | Pressed state |
+| `ToggleGroup` | `shadcn--toggle-group` | Single/multi selection |
+| `Tooltip` | `shadcn--tooltip` | Hover with delay |
+| `ThemeToggle` | `shadcn--dark-mode` | Light/dark/system toggle |
+
+## Static components (no controller needed)
+
+These render pure HTML/CSS with no JavaScript behavior:
+
+`Alert`, `Avatar`, `Badge`, `Breadcrumb`, `Button`, `Card`, `Empty`, `Field`, `Input`, `InputGroup`, `Item`, `Kbd`, `Label`, `NativeSelect`, `Pagination`, `Progress`, `Separator`, `Skeleton`, `Spinner`, `Table`, `Textarea`, `Typography*`

data/skills/shadcn-phlex/rules/styling.md

@@ -0,0 +1,177 @@
+# Styling & Tailwind
+
+## Semantic colors
+
+### Incorrect
+
+```ruby
+div(class: "bg-blue-500 text-white") do
+  p(class: "text-gray-600") { "Secondary text" }
+end
+```
+
+### Correct
+
+```ruby
+div(class: "bg-primary text-primary-foreground") do
+  p(class: "text-muted-foreground") { "Secondary text" }
+end
+```
+
+---
+
+## No raw color values for status indicators
+
+Use Badge variants or semantic tokens — don't reach for raw Tailwind colors.
+
+### Incorrect
+
+```ruby
+span(class: "text-emerald-600") { "+20.1%" }
+span(class: "text-red-600") { "-3.2%" }
+```
+
+### Correct
+
+```ruby
+ui_badge(variant: :secondary) { "+20.1%" }
+span(class: "text-destructive") { "-3.2%" }
+```
+
+---
+
+## Built-in variants first
+
+### Incorrect
+
+```ruby
+ui_button(class: "border border-input bg-transparent hover:bg-accent") { "Click" }
+```
+
+### Correct
+
+```ruby
+ui_button(variant: :outline) { "Click" }
+```
+
+---
+
+## `class:` for layout, not styling
+
+Use `class:` for layout (`max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography.
+
+### Incorrect
+
+```ruby
+ui_card(class: "bg-blue-100 text-blue-900 font-bold") do
+  ui_card_content { "Dashboard" }
+end
+```
+
+### Correct
+
+```ruby
+ui_card(class: "max-w-md mx-auto") do
+  ui_card_content { "Dashboard" }
+end
+```
+
+---
+
+## No `space-x-*` / `space-y-*`
+
+Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
+
+### Incorrect
+
+```ruby
+div(class: "space-y-4") do
+  ui_input(name: "email")
+  ui_input(name: "password")
+  ui_button { "Submit" }
+end
+```
+
+### Correct
+
+```ruby
+div(class: "flex flex-col gap-4") do
+  ui_input(name: "email")
+  ui_input(name: "password")
+  ui_button { "Submit" }
+end
+```
+
+---
+
+## Prefer `size-*` over `w-* h-*` when equal
+
+`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
+
+---
+
+## Prefer `truncate` shorthand
+
+`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
+
+---
+
+## No manual `dark:` color overrides
+
+Use semantic tokens — they handle light/dark via CSS variables.
+
+### Incorrect
+
+```ruby
+div(class: "bg-white dark:bg-gray-950 text-black dark:text-white") { "Content" }
+```
+
+### Correct
+
+```ruby
+div(class: "bg-background text-foreground") { "Content" }
+```
+
+---
+
+## Use `cn()` in custom components
+
+When building custom Phlex components that extend shadcn-phlex, inherit from `Shadcn::Base` to get the `cn()` helper for intelligent Tailwind class merging.
+
+### Incorrect
+
+```ruby
+class MyComponent < Phlex::HTML
+  def view_template
+    div(class: "#{@base_classes} #{@extra_classes}") { "content" }
+  end
+end
+```
+
+### Correct
+
+```ruby
+class MyComponent < Shadcn::Base
+  def view_template
+    div(class: cn("rounded-md border p-4", @attrs.delete(:class))) { "content" }
+  end
+end
+```
+
+---
+
+## No manual `z-index` on overlay components
+
+Dialog, Sheet, Drawer, AlertDialog, DropdownMenu, Popover, Tooltip, HoverCard handle their own stacking. Never add `z-50` or `z-[999]`.
+
+---
+
+## Class merging
+
+All components support a `class:` attribute that merges with defaults using `tailwind_merge`. Conflicting classes are resolved — user classes win:
+
+```ruby
+ui_button(class: "w-full")         # adds w-full to button classes
+ui_button(class: "rounded-none")   # overrides default rounded-md
+ui_card(class: "max-w-sm")         # adds width constraint
+```

metadata

@@ -0,0 +1,209 @@
+--- !ruby/object:Gem::Specification
+name: shadcn-phlex
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- cole-robertson
+bindir: bin
+cert_chain: []
+date: 2026-03-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: phlex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: phlex-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: class_variants
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: tailwind_merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: All shadcn/ui v4 components ported to Phlex with Stimulus controllers,
+  7 base color themes, 17 accent colors, and Rails generators.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- app.css
+- css/shadcn-source.css
+- css/shadcn-tailwind.css
+- css/themes/mauve.css
+- css/themes/mist.css
+- css/themes/neutral.css
+- css/themes/olive.css
+- css/themes/stone.css
+- css/themes/taupe.css
+- css/themes/zinc.css
+- js/controllers/accordion_controller.js
+- js/controllers/checkbox_controller.js
+- js/controllers/collapsible_controller.js
+- js/controllers/combobox_controller.js
+- js/controllers/command_controller.js
+- js/controllers/context_menu_controller.js
+- js/controllers/dark_mode_controller.js
+- js/controllers/dialog_controller.js
+- js/controllers/drawer_controller.js
+- js/controllers/dropdown_menu_controller.js
+- js/controllers/hover_card_controller.js
+- js/controllers/index.js
+- js/controllers/menubar_controller.js
+- js/controllers/navigation_menu_controller.js
+- js/controllers/popover_controller.js
+- js/controllers/radio_group_controller.js
+- js/controllers/scroll_area_controller.js
+- js/controllers/select_controller.js
+- js/controllers/sheet_controller.js
+- js/controllers/slider_controller.js
+- js/controllers/switch_controller.js
+- js/controllers/tabs_controller.js
+- js/controllers/toast_controller.js
+- js/controllers/toggle_controller.js
+- js/controllers/toggle_group_controller.js
+- js/controllers/tooltip_controller.js
+- lib/generators/shadcn_phlex/component_generator.rb
+- lib/generators/shadcn_phlex/install_generator.rb
+- lib/shadcn-phlex.rb
+- lib/shadcn.rb
+- lib/shadcn/base.rb
+- lib/shadcn/engine.rb
+- lib/shadcn/kit.rb
+- lib/shadcn/themes/accent_colors.rb
+- lib/shadcn/themes/base_colors.rb
+- lib/shadcn/ui/accordion.rb
+- lib/shadcn/ui/alert.rb
+- lib/shadcn/ui/alert_dialog.rb
+- lib/shadcn/ui/aspect_ratio.rb
+- lib/shadcn/ui/avatar.rb
+- lib/shadcn/ui/badge.rb
+- lib/shadcn/ui/breadcrumb.rb
+- lib/shadcn/ui/button.rb
+- lib/shadcn/ui/button_group.rb
+- lib/shadcn/ui/card.rb
+- lib/shadcn/ui/checkbox.rb
+- lib/shadcn/ui/collapsible.rb
+- lib/shadcn/ui/combobox.rb
+- lib/shadcn/ui/command.rb
+- lib/shadcn/ui/context_menu.rb
+- lib/shadcn/ui/dialog.rb
+- lib/shadcn/ui/direction.rb
+- lib/shadcn/ui/drawer.rb
+- lib/shadcn/ui/dropdown_menu.rb
+- lib/shadcn/ui/empty.rb
+- lib/shadcn/ui/field.rb
+- lib/shadcn/ui/hover_card.rb
+- lib/shadcn/ui/input.rb
+- lib/shadcn/ui/input_group.rb
+- lib/shadcn/ui/input_otp.rb
+- lib/shadcn/ui/item.rb
+- lib/shadcn/ui/kbd.rb
+- lib/shadcn/ui/label.rb
+- lib/shadcn/ui/menubar.rb
+- lib/shadcn/ui/native_select.rb
+- lib/shadcn/ui/navigation_menu.rb
+- lib/shadcn/ui/pagination.rb
+- lib/shadcn/ui/popover.rb
+- lib/shadcn/ui/progress.rb
+- lib/shadcn/ui/radio_group.rb
+- lib/shadcn/ui/resizable.rb
+- lib/shadcn/ui/scroll_area.rb
+- lib/shadcn/ui/select.rb
+- lib/shadcn/ui/separator.rb
+- lib/shadcn/ui/sheet.rb
+- lib/shadcn/ui/sidebar.rb
+- lib/shadcn/ui/skeleton.rb
+- lib/shadcn/ui/slider.rb
+- lib/shadcn/ui/sonner.rb
+- lib/shadcn/ui/spinner.rb
+- lib/shadcn/ui/switch.rb
+- lib/shadcn/ui/table.rb
+- lib/shadcn/ui/tabs.rb
+- lib/shadcn/ui/text_field.rb
+- lib/shadcn/ui/textarea.rb
+- lib/shadcn/ui/theme_toggle.rb
+- lib/shadcn/ui/toggle.rb
+- lib/shadcn/ui/toggle_group.rb
+- lib/shadcn/ui/tooltip.rb
+- lib/shadcn/ui/typography.rb
+- lib/shadcn/version.rb
+- package.json
+- skills/shadcn-phlex/SKILL.md
+- skills/shadcn-phlex/evals/evals.json
+- skills/shadcn-phlex/references/component-catalog.md
+- skills/shadcn-phlex/rules/composition.md
+- skills/shadcn-phlex/rules/forms.md
+- skills/shadcn-phlex/rules/helpers.md
+- skills/shadcn-phlex/rules/stimulus.md
+- skills/shadcn-phlex/rules/styling.md
+homepage: https://github.com/cole-robertson/shadcn-phlex
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/cole-robertson/shadcn-phlex
+  source_code_uri: https://github.com/cole-robertson/shadcn-phlex
+  changelog_uri: https://github.com/cole-robertson/shadcn-phlex/commits/master
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Complete shadcn/ui component library for Phlex Rails
+test_files: []