plutonium 0.33.1 → 0.34.0

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

@@ -0,0 +1,218 @@
+---
+name: definition
+description: Overview of Plutonium resource definitions - structure, inheritance, and best practices
+---
+
+# Definition Overview
+
+Resource definitions configure **HOW** resources are rendered and interacted with. They are the central configuration point for UI behavior in Plutonium applications.
+
+## Key Principle
+
+**All model attributes are auto-detected** - you only declare when overriding defaults.
+
+## File Location
+
+- Main app: `app/definitions/model_name_definition.rb`
+- Packages: `packages/pkg_name/app/definitions/pkg_name/model_name_definition.rb`
+
+## Definition Structure
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Fields, inputs, displays, columns (see definition-fields skill)
+  field :content, as: :rich_text
+  input :title, hint: "Be descriptive"
+  display :content, as: :markdown
+  column :title, align: :center
+
+  # Search, filters, scopes, sorting (see definition-query skill)
+  search { |scope, q| scope.where("title ILIKE ?", "%#{q}%") }
+  filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
+  scope :published
+  sort :created_at
+
+  # Actions (see definition-actions skill)
+  action :publish, interaction: PublishInteraction
+end
+```
+
+## Definition Hierarchy
+
+Definitions exist at multiple levels:
+
+### Main App (created by generators)
+
+```ruby
+# app/definitions/resource_definition.rb (base - created during install)
+class ResourceDefinition < Plutonium::Resource::Definition
+  action :archive, interaction: ArchiveInteraction, color: :danger, position: 1000
+end
+
+# app/definitions/post_definition.rb (resource-specific - created by scaffold)
+class PostDefinition < ResourceDefinition
+  scope :published
+  input :content, as: :rich_text
+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 |
+|-------|---------|---------|
+| **Definition** | HOW fields render | `input :content, as: :rich_text` |
+| **Policy** | WHAT is visible/editable | `permitted_attributes_for_read` |
+| **Interaction** | Business logic | `resource.update!(state: :archived)` |
+
+## Auto-Detection
+
+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.**
+
+## When to Declare
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # 1. Override auto-detected type
+  field :content, as: :rich_text      # 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
+```
+
+## Minimal Definition Example
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # No field declarations needed - all auto-detected!
+
+  # Only customize what you need:
+  input :content, as: :rich_text
+  display :content, as: :markdown
+
+  scope :published
+  scope :draft
+end
+```
+
+## Runtime Customization Hooks
+
+Override these methods for dynamic behavior:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  def customize_fields
+    field :debug_info if Rails.env.development?
+  end
+
+  def customize_inputs
+    # Add/modify inputs at runtime
+  end
+
+  def customize_displays
+    # Add/modify displays at runtime
+  end
+
+  def customize_filters
+    # Add/modify filters at runtime
+  end
+
+  def customize_actions
+    # Add/modify actions at runtime
+  end
+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 |
+
+## Page Customization
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Titles (static or dynamic)
+  index_page_title "All Posts"
+  show_page_title -> { "#{current_record!.title} - Details" }
+
+  # Breadcrumbs
+  breadcrumbs true
+  show_page_breadcrumbs false
+
+  # Custom page classes (inherit from parent's nested class)
+  class IndexPage < IndexPage
+    def view_template(&block)
+      div(class: "custom-header") { h1 { "Custom" } }
+      super(&block)
+    end
+  end
+
+  class Form < Form
+    def form_template
+      div(class: "grid grid-cols-2") do
+        render field(:title).input_tag
+        render field(:content).easymde_tag
+      end
+      render_actions
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Let auto-detection work** - Don't declare unless overriding
+2. **Use portal-specific definitions** - Override per-portal when needed
+3. **Keep definitions focused** - Configuration only, no business logic
+4. **Use policies for authorization** - Not `condition` procs
+5. **Group related declarations** - Use comments to organize sections
+
+## Related Skills
+
+- `definition-fields` - Fields, inputs, displays, columns
+- `definition-actions` - Actions and interactions
+- `definition-query` - Search, filters, scopes, sorting
+- `views` - Custom page, form, display, and table classes

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

@@ -0,0 +1,386 @@
+---
+name: definition-actions
+description: Add custom actions and interactions to Plutonium resources
+---
+
+# Definition Actions
+
+Actions define custom operations that can be performed on resources. They can be simple (navigation) or interactive (with business logic via Interactions).
+
+## Action Types
+
+| Type | Shows In | Use Case |
+|------|----------|----------|
+| `resource_action` | Index page | Import, Export, Create |
+| `record_action` | Show page | Edit, Delete, Archive |
+| `collection_record_action` | Table rows | Quick actions per row |
+| `bulk_action` | Selected records | Bulk operations |
+
+## Simple Actions (Navigation)
+
+Simple actions link to existing routes. **The target route must already exist** - these don't create new functionality, just navigation links.
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Link to external URL
+  action :documentation,
+    label: "Documentation",
+    route_options: {url: "https://docs.example.com"},
+    icon: Phlex::TablerIcons::Book,
+    resource_action: true
+
+  # Link to custom controller action (you must add the action + route yourself)
+  action :reports,
+    route_options: {action: :reports},
+    icon: Phlex::TablerIcons::ChartBar,
+    resource_action: true
+end
+```
+
+**Note:** For custom operations with business logic, use **Interactive Actions** with an Interaction class instead. That's the recommended approach for most custom actions.
+
+## Interactive Actions (with Interaction)
+
+```ruby
+class PostDefinition < ResourceDefinition
+  action :publish,
+    interaction: PublishInteraction,
+    icon: Phlex::TablerIcons::Send
+
+  action :archive,
+    interaction: ArchiveInteraction,
+    color: :danger,
+    category: :danger,
+    position: 1000,
+    confirmation: "Are you sure?"
+end
+```
+
+## Action Options
+
+```ruby
+action :name,
+  # Display
+  label: "Custom Label",           # Button text (default: name.titleize)
+  description: "What it does",     # Tooltip/description
+  icon: Phlex::TablerIcons::Star,  # Icon component
+  color: :danger,                  # :primary, :secondary, :danger
+
+  # Visibility
+  resource_action: true,           # Show on index page
+  record_action: true,             # Show on show page
+  collection_record_action: true,  # Show in table rows
+  bulk_action: true,               # For selected records
+
+  # Grouping
+  category: :primary,              # :primary, :secondary, :danger
+  position: 50,                    # Order (lower = first)
+
+  # Behavior
+  confirmation: "Are you sure?",   # Confirmation dialog
+  turbo_frame: "_top",             # Turbo frame target
+  route_options: {action: :foo}    # Route configuration
+```
+
+## Creating an Interaction
+
+### Basic Structure
+
+```ruby
+# app/interactions/resource_interaction.rb (generated during install)
+class ResourceInteraction < Plutonium::Resource::Interaction
+end
+
+# app/interactions/archive_interaction.rb
+class ArchiveInteraction < ResourceInteraction
+  presents label: "Archive",
+           icon: Phlex::TablerIcons::Archive,
+           description: "Archive this record"
+
+  attribute :resource  # The record being acted on
+
+  def execute
+    resource.archived!
+    succeed(resource).with_message("Record archived successfully.")
+  rescue ActiveRecord::RecordInvalid => e
+    failed(e.record.errors)
+  rescue => error
+    failed("Archive failed. Please try again.")
+  end
+end
+```
+
+### With Additional Inputs
+
+```ruby
+# app/interactions/company/invite_user_interaction.rb
+class Company::InviteUserInteraction < Plutonium::Resource::Interaction
+  presents label: "Invite User", icon: Phlex::TablerIcons::Mail
+
+  attribute :resource  # The company
+  attribute :email
+  attribute :role
+
+  # Configure form inputs
+  input :email, as: :email, hint: "User's email address"
+  input :role, as: :select, choices: %w[admin member viewer]
+
+  # Validations
+  validates :email, presence: true, format: {with: URI::MailTo::EMAIL_REGEXP}
+  validates :role, presence: true, inclusion: {in: %w[admin member viewer]}
+
+  def execute
+    UserInvite.create!(
+      company: resource,
+      email: email,
+      role: role,
+      invited_by: current_user
+    )
+    succeed(resource).with_message("Invitation sent to #{email}.")
+  rescue ActiveRecord::RecordInvalid => e
+    failed(e.record.errors)
+  end
+end
+```
+
+### Bulk Action (Multiple Records)
+
+```ruby
+class BulkArchiveInteraction < Plutonium::Resource::Interaction
+  presents label: "Archive Selected", icon: Phlex::TablerIcons::Archive
+
+  attribute :resources  # Array of records (note: plural)
+
+  def execute
+    count = 0
+    resources.each do |record|
+      record.archived!
+      count += 1
+    end
+    succeed(resources).with_message("#{count} records archived.")
+  rescue => error
+    failed("Bulk archive failed: #{error.message}")
+  end
+end
+```
+
+### Resource Action (No Record)
+
+```ruby
+class ImportInteraction < Plutonium::Resource::Interaction
+  presents label: "Import CSV", icon: Phlex::TablerIcons::Upload
+
+  # No :resource or :resources attribute = resource action
+  attribute :file
+
+  input :file, as: :file
+
+  validates :file, presence: true
+
+  def execute
+    # Import logic...
+    succeed(nil).with_message("Import completed.")
+  end
+end
+```
+
+## Interaction Responses
+
+```ruby
+def execute
+  # Success with message
+  succeed(resource).with_message("Done!")
+
+  # Success with redirect
+  succeed(resource)
+    .with_redirect_response(resource_url_for(resource))
+    .with_message("Redirecting...")
+
+  # Failure with field errors
+  failed(resource.errors)
+
+  # Failure with custom message
+  failed("Something went wrong")
+
+  # Failure with specific field
+  failed("Invalid value", :email)
+end
+```
+
+## Interaction Context
+
+Inside an interaction:
+- `current_user` - The authenticated user
+- `view_context` - Access to helpers and view methods
+
+```ruby
+def execute
+  resource.update!(
+    archived_by: current_user,
+    archived_at: Time.current
+  )
+  succeed(resource)
+end
+```
+
+## Defining in Definition
+
+### Basic
+
+```ruby
+class PostDefinition < ResourceDefinition
+  action :publish, interaction: PublishInteraction
+  action :archive, interaction: ArchiveInteraction
+end
+```
+
+### With Overrides
+
+```ruby
+class PostDefinition < ResourceDefinition
+  action :archive,
+    interaction: ArchiveInteraction,
+    collection_record_action: false,  # Don't show in table
+    color: :danger,
+    position: 1000                    # Show last
+end
+```
+
+### Inherited Actions
+
+Actions defined in `ResourceDefinition` (created during install) are inherited by all definitions:
+
+```ruby
+# app/definitions/resource_definition.rb (created during install)
+class ResourceDefinition < Plutonium::Resource::Definition
+  action :archive, interaction: ArchiveInteraction, color: :danger, position: 1000
+end
+
+# All definitions inherit the archive action automatically
+class PostDefinition < ResourceDefinition
+end
+```
+
+### Portal-Specific Actions
+
+Override actions for a specific portal:
+
+```ruby
+# packages/admin_portal/app/definitions/admin_portal/post_definition.rb
+class AdminPortal::PostDefinition < ::PostDefinition
+  # Add admin-only actions
+  action :feature, interaction: FeaturePostInteraction
+  action :bulk_publish, interaction: BulkPublishInteraction
+end
+```
+
+## Default CRUD Actions
+
+Plutonium provides these by default:
+
+```ruby
+action :new,     resource_action: true,           position: 10
+action :show,    collection_record_action: true,  position: 10
+action :edit,    record_action: true,             position: 20
+action :destroy, record_action: true,             position: 100, category: :danger
+```
+
+## Authorization
+
+Actions are authorized via policies:
+
+```ruby
+# app/policies/post_policy.rb
+class PostPolicy < ResourcePolicy
+  def publish?
+    user.admin? || record.author == user
+  end
+
+  def archive?
+    user.admin?
+  end
+end
+```
+
+The action only appears if the policy method returns `true`.
+
+## Immediate vs Form Actions
+
+**Immediate** - Executes without showing a form (when interaction has no extra inputs):
+
+```ruby
+class ArchiveInteraction < Plutonium::Resource::Interaction
+  attribute :resource  # Only resource, no other inputs
+  # No input declarations
+
+  def execute
+    resource.archived!
+    succeed(resource)
+  end
+end
+```
+
+**Form** - Shows a form first (when interaction has additional inputs):
+
+```ruby
+class InviteUserInteraction < Plutonium::Resource::Interaction
+  attribute :resource
+  attribute :email
+  attribute :role
+
+  input :email
+  input :role, as: :select, choices: %w[admin member]
+  # Has inputs = shows form first
+end
+```
+
+## Common Patterns
+
+### Archive/Restore
+
+```ruby
+class ArchiveInteraction < Plutonium::Resource::Interaction
+  presents label: "Archive", icon: Phlex::TablerIcons::Archive
+  attribute :resource
+
+  def execute
+    resource.archived!
+    succeed(resource).with_message("Archived.")
+  end
+end
+
+class RestoreInteraction < Plutonium::Resource::Interaction
+  presents label: "Restore", icon: Phlex::TablerIcons::Refresh
+  attribute :resource
+
+  def execute
+    resource.active!
+    succeed(resource).with_message("Restored.")
+  end
+end
+```
+
+### Send Notification
+
+```ruby
+class SendReminderInteraction < Plutonium::Resource::Interaction
+  presents label: "Send Reminder", icon: Phlex::TablerIcons::Bell
+  attribute :resource
+  attribute :message
+
+  input :message, as: :text, hint: "Custom message (optional)"
+
+  def execute
+    ReminderMailer.with(record: resource, message: message).deliver_later
+    succeed(resource).with_message("Reminder sent.")
+  end
+end
+```
+
+## Related Skills
+
+- `definition` - Overview and structure
+- `definition-fields` - Fields, inputs, displays
+- `definition-query` - Search, filters, scopes
+- `interaction` - Writing interaction classes
+- `policy` - Controlling action access