plutonium 0.44.1 → 0.45.0

data/.claude/skills/plutonium-definition/SKILL.md

@@ -1,16 +1,29 @@
 ---
 name: plutonium-definition
-description: Overview of Plutonium resource definitions - structure, inheritance, and best practices
+description: Use when configuring resource definitions - field types, inputs, displays, columns, conditional rendering, nested inputs, or definition structure
 ---
 
-# Definition Overview
+# Plutonium Resource Definitions
 
-Resource definitions configure **HOW** resources are rendered and interacted with. They are the central configuration point for UI behavior in Plutonium applications.
+**Definitions are generated automatically** - never create them manually:
+- `rails g pu:res:scaffold` creates the base definition
+- `rails g pu:res:conn` creates portal-specific definitions
+- `rails g pu:field:input NAME` creates custom field input components
+- `rails g pu:field:renderer NAME` creates custom field display components
+
+Resource definitions configure **HOW** resources are rendered and interacted with. They are the central configuration point for UI behavior.
 
 ## Key Principle
 
 **All model attributes are auto-detected** - you only declare when overriding defaults.
 
+Plutonium automatically detects from your model:
+- Database columns (string, text, integer, boolean, datetime, etc.)
+- Associations (belongs_to, has_many, has_one)
+- Active Storage attachments (has_one_attached, has_many_attached)
+- Enums
+- Virtual attributes (with accessor methods)
+
 ## File Location
 
 - Main app: `app/definitions/model_name_definition.rb`
@@ -20,7 +33,7 @@ Resource definitions configure **HOW** resources are rendered and interacted wit
 
 ```ruby
 class PostDefinition < Plutonium::Resource::Definition
-  # Fields, inputs, displays, columns (see definition-fields skill)
+  # Fields, inputs, displays, columns
   field :content, as: :markdown
   input :title, hint: "Be descriptive"
   display :content, as: :markdown
@@ -58,23 +71,14 @@ end
 
 ### Portal-Specific Overrides
 
-After connecting a resource to a portal, you can create a portal-specific definition to override defaults for that portal only:
-
 ```ruby
 # packages/admin_portal/app/definitions/admin_portal/post_definition.rb
 class AdminPortal::PostDefinition < ::PostDefinition
-  # Override or extend for admin portal only
   input :internal_notes, as: :text  # Only admins see this field
   scope :pending_review             # Admin-specific scope
 end
 ```
 
-This lets you:
-- Show different fields per portal
-- Add portal-specific actions
-- Customize search/filters per context
-- Keep main app definition clean
-
 ## Separation of Concerns
 
 | Layer | Purpose | Example |
@@ -83,56 +87,422 @@ This lets you:
 | **Policy** | WHAT is visible/editable | `permitted_attributes_for_read` |
 | **Interaction** | Business logic | `resource.update!(state: :archived)` |
 
-## Auto-Detection
+## Core Methods
 
-Plutonium automatically detects from your model:
-- Database columns (string, text, integer, boolean, datetime, etc.)
-- Associations (belongs_to, has_many, has_one)
-- Active Storage/Active Shrine attachments (has_one_attached, has_many_attached)
-- Enums
-- Virtual attributes (with accessor methods)
-
-**Only declare fields when you need to override the auto-detected behavior.**
+| Method | Applies To | Use When |
+|--------|-----------|----------|
+| `field` | Forms + Show + Table | Universal type override |
+| `input` | Forms only | Form-specific options |
+| `display` | Show page only | Display-specific options |
+| `column` | Table only | Table-specific options |
 
-## When to Declare
+## Basic Usage
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  # 1. Override auto-detected type
-  field :content, as: :markdown      # text -> rich_text
-  input :published_at, as: :date      # datetime -> date only
+  # field - changes type everywhere
+  field :content, as: :markdown
 
-  # 2. Add custom options
-  input :title, hint: "Be descriptive", placeholder: "Enter title"
+  # input - form-specific
+  input :title,
+    label: "Article Title",
+    hint: "Enter a descriptive title",
+    placeholder: "e.g. Getting Started"
+
+  # display - show page specific
+  display :content,
+    as: :markdown,
+    description: "Published content",
+    wrapper: {class: "col-span-full"}
+
+  # column - table specific
+  column :title, label: "Article", align: :center
+  column :view_count, align: :end
+end
+```
 
-  # 3. Configure select choices
-  input :category, as: :select, choices: %w[Tech Business]
+## Available Field Types
 
-  # 4. Add conditional logic
+### Input Types (Forms)
+
+| Category | Types |
+|----------|-------|
+| **Text** | `:string`, `:text`, `:email`, `:url`, `:tel`, `:password` |
+| **Rich Text** | `:markdown` (EasyMDE editor) |
+| **Numeric** | `:number`, `:integer`, `:decimal`, `:range` |
+| **Boolean** | `:boolean` |
+| **Date/Time** | `:date`, `:time`, `:datetime` |
+| **Selection** | `:select`, `:slim_select`, `:radio_buttons`, `:check_boxes` |
+| **Files** | `:file`, `:uppy`, `:attachment` |
+| **Associations** | `:association`, `:secure_association`, `:belongs_to`, `:has_many`, `:has_one` |
+| **Special** | `:hidden`, `:color`, `:phone` |
+
+### Display Types (Show/Index)
+
+`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`
+
+## Field Options
+
+### Field-Level Options (wrapper)
+
+```ruby
+input :title,
+  label: "Custom Label",           # Custom label text
+  hint: "Help text for forms",     # Form help text
+  placeholder: "Enter value",      # Input placeholder
+  description: "For displays"      # Display description
+```
+
+### Tag-Level Options (HTML element)
+
+```ruby
+input :title,
+  class: "custom-class",           # CSS class
+  data: {controller: "custom"},    # Data attributes
+  required: true,                  # HTML required
+  readonly: true,                  # HTML readonly
+  disabled: true                   # HTML disabled
+```
+
+### Wrapper Options
+
+```ruby
+display :content, wrapper: {class: "col-span-full"}
+input :notes, wrapper: {class: "bg-gray-50"}
+```
+
+## Select/Choices
+
+### Static Choices
+
+```ruby
+input :category, as: :select, choices: %w[Tech Business Lifestyle]
+input :status, as: :select, choices: Post.statuses.keys
+```
+
+### Dynamic Choices (requires block)
+
+```ruby
+# Basic dynamic
+input :author do |f|
+  choices = User.active.pluck(:name, :id)
+  f.select_tag choices: choices
+end
+
+# With context access
+input :team_members do |f|
+  choices = current_user.organization.users.pluck(:name, :id)
+  f.select_tag choices: choices
+end
+
+# Based on object state
+input :related_posts do |f|
+  choices = if object.persisted?
+    Post.where.not(id: object.id).published.pluck(:title, :id)
+  else
+    []
+  end
+  f.select_tag choices: choices
+end
+```
+
+## Conditional Rendering
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Show based on object state
   display :published_at, condition: -> { object.published? }
+  display :rejection_reason, condition: -> { object.rejected? }
 
-  # 5. Custom rendering
-  display :status do |field|
-    StatusBadgeComponent.new(value: field.value)
+  # Show based on environment
+  field :debug_info, condition: -> { Rails.env.development? }
+end
+```
+
+**Note:** Use `condition` for UI state logic. Use **policies** for authorization.
+
+## Dynamic Forms (pre_submit)
+
+Use `pre_submit: true` to create forms that dynamically show/hide fields based on other field values. When a `pre_submit` field changes, the form re-renders server-side and conditions are re-evaluated.
+
+### Basic Pattern
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Trigger field - causes form to re-render on change
+  input :send_notifications, pre_submit: true
+
+  # Dependent field - only shown when condition is true
+  input :notification_channel,
+    as: :select,
+    choices: %w[Email SMS],
+    condition: -> { object.send_notifications? }
+end
+```
+
+### How It Works
+
+1. User changes a `pre_submit: true` field
+2. Form submits via Turbo (no page reload)
+3. Server re-renders the form with updated `object` state
+4. Fields with `condition` procs are re-evaluated
+5. Newly visible fields appear, hidden fields disappear
+
+### Multiple Dependent Fields
+
+```ruby
+class QuestionDefinition < ResourceDefinition
+  # Primary selector
+  input :question_type, as: :select,
+    choices: %w[text choice scale date boolean],
+    pre_submit: true
+
+  # Conditional fields based on question_type
+  input :max_length,
+    as: :integer,
+    condition: -> { object.question_type == "text" }
+
+  input :choices,
+    as: :text,
+    hint: "One choice per line",
+    condition: -> { object.question_type == "choice" }
+
+  input :min_value,
+    as: :integer,
+    condition: -> { object.question_type == "scale" }
+
+  input :max_value,
+    as: :integer,
+    condition: -> { object.question_type == "scale" }
+end
+```
+
+### Cascading Dependencies
+
+```ruby
+class PropertyDefinition < ResourceDefinition
+  input :property_type, as: :select,
+    choices: %w[residential commercial],
+    pre_submit: true
+
+  input :residential_type, as: :select,
+    choices: %w[apartment house condo],
+    condition: -> { object.property_type == "residential" },
+    pre_submit: true
+
+  input :commercial_type, as: :select,
+    choices: %w[office retail warehouse],
+    condition: -> { object.property_type == "commercial" },
+    pre_submit: true
+
+  input :apartment_floor,
+    as: :integer,
+    condition: -> { object.residential_type == "apartment" }
+end
+```
+
+### Dynamic Choices with pre_submit
+
+```ruby
+class SurveyResponseDefinition < ResourceDefinition
+  input :category, as: :select,
+    choices: Category.pluck(:name, :id),
+    pre_submit: true
+
+  input :subcategory do |f|
+    choices = if object.category.present?
+      Category.find(object.category).subcategories.pluck(:name, :id)
+    else
+      []
+    end
+    f.select_tag choices: choices
   end
 end
 ```
 
-## Minimal Definition Example
+### Tips
+
+- Only add `pre_submit: true` to fields that control visibility of other fields
+- Keep dependencies simple - deeply nested conditions are hard to debug
+- The form submits on change, so avoid `pre_submit` on frequently-changed fields
+
+## Custom Rendering
+
+### Block Syntax
+
+**For Display (can return any component):**
+```ruby
+display :status do |field|
+  StatusBadgeComponent.new(value: field.value, class: field.dom.css_class)
+end
+
+display :metrics do |field|
+  if field.value.present?
+    MetricsChartComponent.new(data: field.value)
+  else
+    EmptyStateComponent.new(message: "No metrics")
+  end
+end
+```
+
+**For Input (must use form builder methods):**
+```ruby
+input :birth_date do |f|
+  case object.age_category
+  when 'adult'
+    f.date_tag(min: 18.years.ago.to_date)
+  when 'minor'
+    f.date_tag(max: 18.years.ago.to_date)
+  else
+    f.date_tag
+  end
+end
+```
+
+### phlexi_tag (Advanced Display)
+
+```ruby
+# With component class
+display :status, as: :phlexi_tag, with: StatusBadgeComponent
+
+# With inline proc
+display :priority, as: :phlexi_tag, with: ->(value, attrs) {
+  case value
+  when 'high'
+    span(class: "badge badge-danger") { "High" }
+  when 'medium'
+    span(class: "badge badge-warning") { "Medium" }
+  else
+    span(class: "badge badge-info") { "Low" }
+  end
+}
+```
+
+### Custom Component Class
+
+```ruby
+input :color_picker, as: ColorPickerComponent
+display :chart, as: ChartComponent
+```
+
+## Column Options
+
+### Alignment
+
+```ruby
+column :title, align: :start    # Left (default)
+column :status, align: :center  # Center
+column :amount, align: :end     # Right
+```
+
+### Value Formatting
+
+```ruby
+# Truncate long text
+column :description, formatter: ->(value) { value&.truncate(30) }
+
+# Format numbers
+column :price, formatter: ->(value) { "$%.2f" % value if value }
+
+# Transform values
+column :status, formatter: ->(value) { value&.humanize&.upcase }
+```
+
+**formatter vs block:** Use `formatter` when you only need the value. Use a block when you need the full record:
+
+```ruby
+# formatter - receives just the value
+column :name, formatter: ->(value) { value&.titleize }
+
+# block - receives the full record
+column :full_name do |record|
+  "#{record.first_name} #{record.last_name}"
+end
+```
+
+## Nested Inputs
+
+Render inline forms for associated records. Requires `accepts_nested_attributes_for` on the model.
+
+### Model Setup
+
+```ruby
+class Post < ResourceRecord
+  has_many :comments
+  has_one :metadata
+
+  accepts_nested_attributes_for :comments, allow_destroy: true, limit: 10
+  accepts_nested_attributes_for :metadata, update_only: true
+end
+```
+
+### Basic Declaration
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  # No field declarations needed - all auto-detected!
+  # Block syntax
+  nested_input :comments do |n|
+    n.input :body, as: :text
+    n.input :author_name
+  end
 
-  # Only customize what you need:
-  input :content, as: :markdown
-  display :content, as: :markdown
+  # Using another definition
+  nested_input :metadata, using: PostMetadataDefinition, fields: %i[seo_title seo_description]
+end
+```
 
-  scope :published
-  scope :draft
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `limit` | Max records (auto-detected from model, default: 10) |
+| `allow_destroy` | Show delete checkbox (auto-detected from model) |
+| `update_only` | Hide "Add" button, only edit existing |
+| `description` | Help text above the section |
+| `condition` | Proc to show/hide section |
+| `using` | Reference another Definition class |
+| `fields` | Which fields to render from the definition |
+
+```ruby
+nested_input :amenities,
+  allow_destroy: true,
+  limit: 20,
+  description: "Add property amenities" do |n|
+    n.input :name
+    n.input :icon, as: :select, choices: ICONS
+  end
+```
+
+### Singular Associations
+
+For `has_one` and `belongs_to`, limit is automatically 1:
+
+```ruby
+nested_input :profile do |n|  # has_one
+  n.input :bio
+  n.input :website
 end
 ```
 
+### Gotchas
+
+- Model must have `accepts_nested_attributes_for`
+- For custom class names, use `class_name:` in both model and `using:` in definition
+- `update_only: true` hides the Add button
+- Limit is enforced in UI (Add button hidden when reached)
+
+## File Uploads
+
+```ruby
+input :avatar, as: :file
+input :avatar, as: :uppy
+
+input :documents, as: :file, multiple: true
+input :documents, as: :uppy,
+  allowed_file_types: ['.pdf', '.doc'],
+  max_file_size: 5.megabytes
+```
+
 ## Runtime Customization Hooks
 
 Override these methods for dynamic behavior:
@@ -161,15 +531,6 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-## Context Availability
-
-| Context | current_user | object | current_parent |
-|---------|-------------|--------|----------------|
-| Definition file (class level) | No | No | No |
-| `condition` procs | Yes | Yes | Yes |
-| `input` blocks | Yes | Yes | Yes |
-| Page title procs | Yes | Yes (current_record!) | Yes |
-
 ## Form Configuration
 
 ```ruby
@@ -182,8 +543,6 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
-Singular resources (e.g., `resource :profile` routes or `has_one` nested) auto-hide this button since creating "another" doesn't make sense.
-
 ## Page Customization
 
 ```ruby
@@ -216,6 +575,39 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
+## Context in Blocks
+
+Inside `condition` procs and `input` blocks:
+- `object` - The record being edited/displayed
+- `current_user` - The authenticated user
+- `current_parent` - Parent record for nested resources
+- `request`, `params` - Request information
+- All helper methods
+
+## When to Declare
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # 1. Override auto-detected type
+  field :content, as: :markdown      # text -> rich_text
+  input :published_at, as: :date      # datetime -> date only
+
+  # 2. Add custom options
+  input :title, hint: "Be descriptive", placeholder: "Enter title"
+
+  # 3. Configure select choices
+  input :category, as: :select, choices: %w[Tech Business]
+
+  # 4. Add conditional logic
+  display :published_at, condition: -> { object.published? }
+
+  # 5. Custom rendering
+  display :status do |field|
+    StatusBadgeComponent.new(value: field.value)
+  end
+end
+```
+
 ## Best Practices
 
 1. **Let auto-detection work** - Don't declare unless overriding
@@ -226,7 +618,7 @@ end
 
 ## Related Skills
 
-- `plutonium-definition-fields` - Fields, inputs, displays, columns
 - `plutonium-definition-actions` - Actions and interactions
 - `plutonium-definition-query` - Search, filters, scopes, sorting
 - `plutonium-views` - Custom page, form, display, and table classes
+- `plutonium-forms` - Custom form templates and field builders

data/.claude/skills/plutonium-definition-actions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plutonium-definition-actions
-description: Add custom actions and interactions to Plutonium resources
+description: Use when adding custom actions, bulk operations, or wiring interactions into Plutonium resource definitions
 ---
 
 # Definition Actions
@@ -418,7 +418,7 @@ end
 ## Related Skills
 
 - `plutonium-definition` - Overview and structure
-- `plutonium-definition-fields` - Fields, inputs, displays
+- `plutonium-definition` - Fields, inputs, displays
 - `plutonium-definition-query` - Search, filters, scopes
 - `plutonium-interaction` - Writing interaction classes
 - `plutonium-policy` - Controlling action access

data/.claude/skills/plutonium-definition-query/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plutonium-definition-query
-description: Configure search, filters, scopes, and sorting for Plutonium resources
+description: Use when adding search, filters, named scopes, or sorting to a Plutonium resource definition
 ---
 
 # Definition Query
@@ -360,5 +360,5 @@ end
 ## Related Skills
 
 - `plutonium-definition` - Overview and structure
-- `plutonium-definition-fields` - Fields, inputs, displays
+- `plutonium-definition` - Fields, inputs, displays
 - `plutonium-definition-actions` - Actions and interactions

data/.claude/skills/plutonium-forms/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: plutonium-forms
-description: Plutonium forms - custom templates, Phlex form components, field builders, and theming
+description: Use when building custom form templates, overriding field builders, or theming form components in Plutonium
 ---
 
 # Plutonium Forms
 
+**Use generators for custom field types:**
+- `rails g pu:field:input NAME` creates a custom form input component
+- `rails g pu:field:renderer NAME` creates a custom display renderer
+
 Plutonium forms are built on [Phlexi::Form](https://github.com/radioactive-labs/phlexi-form), providing a Ruby-first approach to form building with Phlex components.
 
 ## Form Class Hierarchy
@@ -447,7 +451,7 @@ end
 
 ## Related Skills
 
-- `plutonium-definition-fields` - Input configuration (as:, hint:, condition:)
+- `plutonium-definition` - Input configuration (as:, hint:, condition:)
 - `plutonium-views` - Custom page classes
 - `plutonium-assets` - TailwindCSS and component theming
 - `plutonium-interaction` - Interactive action forms

data/.claude/skills/plutonium-installation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plutonium-installation
-description: Installing Plutonium in a Rails application - setup, generators, and configuration
+description: Use when installing Plutonium in a new or existing Rails app - generators, configuration, and initial setup
 ---
 
 # Plutonium Installation
@@ -292,11 +292,11 @@ For models that already exist in your app:
 
 ## Related Skills
 
-- `plutonium-resource` - Resource architecture overview
+- `plutonium` - Resource architecture overview
 - `plutonium-rodauth` - Authentication setup and configuration
 - `plutonium-package` - Feature and portal packages
 - `plutonium-portal` - Portal configuration
 - `plutonium-views` - Custom pages, layouts, and Phlex components
 - `plutonium-assets` - TailwindCSS and custom styling
 - `plutonium-create-resource` - Resource scaffold options
-- `plutonium-connect-resource` - Portal connection
+- `plutonium-portal` - Portal connection

data/.claude/skills/plutonium-interaction/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plutonium-interaction
-description: Plutonium interactions - encapsulated business logic for custom actions
+description: Use when writing interaction classes for custom business logic, multi-step operations, or actions beyond basic CRUD
 ---
 
 # Plutonium Interactions
@@ -68,7 +68,7 @@ input :content, as: :text
 input :date, as: :date
 ```
 
-See `plutonium-definition-fields` skill for all input types and options.
+See `plutonium-definition` skill for all input types and options.
 
 ## Presentation
 
@@ -380,4 +380,4 @@ end
 - `plutonium-definition-actions` - Declaring actions in definitions
 - `plutonium-forms` - Custom interaction form templates
 - `plutonium-policy` - Controlling access to actions
-- `plutonium-resource` - How interactions fit in the architecture
+- `plutonium` - How interactions fit in the architecture

data/.claude/skills/plutonium-invites/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plutonium-invites
-description: Plutonium user invites - invitation system for multi-tenant apps with entity memberships
+description: Use when setting up user invitations with entity membership in a multi-tenant Plutonium app
 ---
 
 # Plutonium User Invites