plutonium 0.45.3 → 0.46.0

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

@@ -1,10 +1,50 @@
 ---
 name: plutonium-definition
-description: Use when configuring resource definitions - field types, inputs, displays, columns, conditional rendering, nested inputs, or definition structure
+description: Use BEFORE editing a resource definition — adding fields, inputs, displays, columns, search, filters, scopes, custom actions, or bulk actions.
 ---
 
 # Plutonium Resource Definitions
 
+## 🚨 Critical (read first)
+- **Use generators.** `pu:res:scaffold` creates the base definition, `pu:res:conn` creates portal-specific overrides, `pu:field:input` / `pu:field:renderer` create custom components.
+- **Let auto-detection work.** Only declare fields/inputs/displays/columns when overriding defaults — Plutonium reads your model.
+- **Authorization goes in policies, not `condition:` procs.** Use `condition` for UI state logic (e.g. "only show `published_at` when published"). Use **policy** `permitted_attributes_for_*` for "who can see this field".
+- **Custom actions require a policy method** — `action :publish` requires `def publish?` on the policy.
+- **Related skills:** `plutonium-policy` (permitted attributes, action permissions), `plutonium-interaction` (business logic for actions), `plutonium-forms` (custom form templates), `plutonium-views` (custom page classes).
+
+## Quick checklist
+
+Editing / extending a definition:
+
+1. Confirm the definition was generated by `pu:res:scaffold` or `pu:res:conn`.
+2. Let auto-detection handle fields; only `field`/`input`/`display`/`column` when overriding defaults.
+3. For search/filter/sort, add `search`, `filter :name, with: :text/:select/:date/...`, `scope :name`, `sort :name`.
+4. For custom actions, define an interaction class and register it: `action :name, interaction: MyInteraction`.
+5. For bulk actions, make the interaction accept `attribute :resources` (plural).
+6. Add policy methods matching each custom action (`def publish?`, `def archive?`, etc.).
+7. For per-portal overrides, edit `packages/<portal>/app/definitions/<portal>/<resource>_definition.rb`.
+8. Test the index page, show page, new/edit form, and any actions in the browser.
+
+## Contents
+
+This skill covers three concerns. Jump to the section you need:
+
+**Fields, inputs, displays, columns** (this top section)
+- [Definition Structure](#definition-structure) · [Definition Hierarchy](#definition-hierarchy) · [Core Methods](#core-methods)
+- [Available Field Types](#available-field-types) · [Field Options](#field-options) · [Select/Choices](#selectchoices)
+- [Conditional Rendering](#conditional-rendering) · [Dynamic Forms (pre_submit)](#dynamic-forms-pre_submit)
+- [Custom Rendering](#custom-rendering) · [Column Options](#column-options) · [Nested Inputs](#nested-inputs)
+- [File Uploads](#file-uploads) · [Runtime Customization Hooks](#runtime-customization-hooks)
+- [Form Configuration](#form-configuration) · [Page Customization](#page-customization)
+
+**[Query: Search, Filters, Scopes, Sorting](#query-search-filters-scopes-sorting)**
+- Search · Filters (text, boolean, date, date_range, select, association) · Custom Filters · Scopes · Sorting · URL Parameters
+
+**[Actions: Custom and Bulk](#actions-custom-and-bulk)**
+- Action Types · Simple Actions · Interactive Actions · Action Options
+- Creating an Interaction · Bulk Actions · Resource Actions
+- Interaction Responses · Default CRUD Actions · Authorization · Immediate vs Form Actions
+
 **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
@@ -486,10 +526,12 @@ 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)
+- Model must have `accepts_nested_attributes_for`.
+- The `belongs_to` on the child model **must** declare `inverse_of: :parent_assoc`. Without it, in-memory validation of nested children fails with "Parent must exist" because the parent isn't yet saved.
+- **Don't put `*_attributes` hashes in the policy's `permitted_attributes_for_*`.** Plutonium extracts nested params via the form definition (`build_form(...).extract_input(...)`), not the policy. Hash entries like `{variants_attributes: [:id, :name, :_destroy]}` get rendered as literal text inputs. The policy should permit just the association name (e.g. `:variants`); the `nested_input :variants` declaration in the definition handles the rest.
+- 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
 
@@ -616,9 +658,481 @@ end
 4. **Use policies for authorization** - Not `condition` procs
 5. **Group related declarations** - Use comments to organize sections
 
+---
+
+# Query: Search, Filters, Scopes, Sorting
+
+Configure how users can search, filter, and sort resource collections.
+
+### Query Overview
+
+```ruby
+class PostDefinition < ResourceDefinition
+  search do |scope, query|
+    scope.where("title ILIKE ?", "%#{query}%")
+  end
+
+  filter :title, with: :text, predicate: :contains
+  filter :status, with: :select, choices: %w[draft published archived]
+  filter :published, with: :boolean
+  filter :created_at, with: :date_range
+  filter :category, with: :association
+
+  scope :published
+  scope :draft
+  default_scope :published
+
+  sort :title
+  sort :created_at
+  default_sort :created_at, :desc
+end
+```
+
+### Search
+
+```ruby
+# Single field
+search do |scope, query|
+  scope.where("title ILIKE ?", "%#{query}%")
+end
+
+# Multiple fields
+search do |scope, query|
+  scope.where(
+    "title ILIKE :q OR content ILIKE :q OR author_name ILIKE :q",
+    q: "%#{query}%"
+  )
+end
+
+# With associations
+search do |scope, query|
+  scope.joins(:author).where(
+    "posts.title ILIKE :q OR users.name ILIKE :q",
+    q: "%#{query}%"
+  ).distinct
+end
+```
+
+### Filters
+
+Plutonium provides **6 built-in filter types**. Use shorthand symbols or full class names.
+
+#### Text Filter
+
+```ruby
+filter :title, with: :text, predicate: :contains
+filter :status, with: :text, predicate: :eq
+filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
+```
+
+**Predicates:** `:eq`, `:not_eq`, `:contains`, `:not_contains`, `:starts_with`, `:ends_with`, `:matches`, `:not_matches`
+
+#### Boolean Filter
+
+```ruby
+filter :active, with: :boolean
+filter :published, with: :boolean, true_label: "Published", false_label: "Draft"
+```
+
+#### Date Filter
+
+```ruby
+filter :created_at, with: :date, predicate: :gteq
+filter :due_date, with: :date, predicate: :lt
+filter :published_at, with: :date, predicate: :eq
+```
+
+**Predicates:** `:eq`, `:not_eq`, `:lt`, `:lteq`, `:gt`, `:gteq`
+
+#### Date Range Filter
+
+```ruby
+filter :created_at, with: :date_range
+filter :published_at, with: :date_range,
+  from_label: "Published from",
+  to_label: "Published to"
+```
+
+#### Select Filter
+
+```ruby
+filter :status, with: :select, choices: %w[draft published archived]
+filter :category, with: :select, choices: -> { Category.pluck(:name) }
+filter :tags, with: :select, choices: %w[ruby rails js], multiple: true
+```
+
+#### Association Filter
+
+```ruby
+filter :category, with: :association
+filter :author, with: :association, class_name: User
+filter :tags, with: :association, class_name: Tag, multiple: true
+```
+
+#### Custom Filter Class
+
+```ruby
+class PriceRangeFilter < Plutonium::Query::Filter
+  def apply(scope, min: nil, max: nil)
+    scope = scope.where("price >= ?", min) if min.present?
+    scope = scope.where("price <= ?", max) if max.present?
+    scope
+  end
+
+  def customize_inputs
+    input :min, as: :number
+    input :max, as: :number
+    field :min, placeholder: "Min price..."
+    field :max, placeholder: "Max price..."
+  end
+end
+
+filter :price, with: PriceRangeFilter
+```
+
+### Scopes
+
+Scopes appear as quick filter buttons.
+
+```ruby
+class PostDefinition < ResourceDefinition
+  scope :published    # Uses Post.published
+  scope :draft        # Uses Post.draft
+
+  # Inline scopes
+  scope(:recent) { |scope| scope.where('created_at > ?', 1.week.ago) }
+  scope(:mine) { |scope| scope.where(author: current_user) }
+
+  default_scope :published  # Applied by default
+end
+```
+
+When a default scope is set:
+- Applied on initial page load
+- Default scope button is highlighted (not "All")
+- Clicking "All" shows all records without any scope filter
+
+### Sorting
+
+```ruby
+sort :title
+sort :created_at
+sorts :title, :created_at, :view_count  # multiple at once
+
+default_sort :created_at, :desc
+default_sort { |scope| scope.order(featured: :desc, created_at: :desc) }
+```
+
+### URL Parameters
+
+```
+/posts?q[search]=rails
+/posts?q[title][query]=widget
+/posts?q[status][value]=published
+/posts?q[created_at][from]=2024-01-01&q[created_at][to]=2024-12-31
+/posts?q[scope]=recent
+/posts?q[sort_fields][]=created_at&q[sort_directions][created_at]=desc
+```
+
+### Filter Summary Table
+
+| Type | Symbol | Input Params | Options |
+|------|--------|--------------|---------|
+| Text | `:text` | `query` | `predicate:` |
+| Boolean | `:boolean` | `value` | `true_label:`, `false_label:` |
+| Date | `:date` | `value` | `predicate:` |
+| Date Range | `:date_range` | `from`, `to` | `from_label:`, `to_label:` |
+| Select | `:select` | `value` | `choices:`, `multiple:` |
+| Association | `:association` | `value` | `class_name:`, `multiple:` |
+
+### Query Performance Tips
+
+1. Add indexes for filtered/sorted columns
+2. Use `.distinct` when joining associations in search
+3. Consider `pg_search` for complex full-text search
+4. Limit search fields to indexed columns
+5. Use scopes instead of filters for common queries
+
+---
+
+# Actions: Custom and Bulk
+
+Actions define custom operations 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.**
+
+```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
+  action :reports,
+    route_options: {action: :reports},
+    icon: Phlex::TablerIcons::ChartBar,
+    resource_action: true
+end
+```
+
+**Important:** When adding custom routes for actions, always use the `as:` option to name them:
+
+```ruby
+resources :posts do
+  collection do
+    get :reports, as: :reports  # Named route required!
+  end
+end
+```
+
+**Note:** For custom operations with business logic, use **Interactive Actions** with an Interaction class instead.
+
+### 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",
+  description: "What it does",
+  icon: Phlex::TablerIcons::Star,
+  color: :danger,                  # :primary, :secondary, :danger
+
+  # Visibility
+  resource_action: true,
+  record_action: true,
+  collection_record_action: true,
+  bulk_action: true,
+
+  # Grouping
+  category: :primary,              # :primary, :secondary, :danger
+  position: 50,
+
+  # Behavior
+  confirmation: "Are you sure?",
+  turbo_frame: "_top",
+  route_options: {action: :foo}
+```
+
+### 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
+
+  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
+class Company::InviteUserInteraction < Plutonium::Resource::Interaction
+  presents label: "Invite User", icon: Phlex::TablerIcons::Mail
+
+  attribute :resource
+  attribute :email
+  attribute :role
+
+  input :email, as: :email, hint: "User's email address"
+  input :role, as: :select, choices: %w[admin member viewer]
+
+  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)
+
+Bulk actions operate on multiple selected records at once. The resource table automatically shows selection checkboxes and a bulk actions toolbar.
+
+```ruby
+# 1. Create the interaction (note: plural `resources` attribute)
+class BulkArchiveInteraction < Plutonium::Resource::Interaction
+  presents label: "Archive Selected", icon: Phlex::TablerIcons::Archive
+
+  attribute :resources  # Array of records (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
+
+# 2. Register the action in the definition
+class PostDefinition < ResourceDefinition
+  action :bulk_archive, interaction: BulkArchiveInteraction
+  # bulk_action: true is automatically inferred from `resources` attribute
+end
+
+# 3. Add policy method
+class PostPolicy < ResourcePolicy
+  def bulk_archive?
+    create?
+  end
+end
+```
+
+**Authorization for bulk actions:**
+- Policy method is checked **per record** — fails the entire request if any record is not authorized
+- Records are fetched via `current_authorized_scope`
+- The UI only shows action buttons that **all** selected records support
+
+#### 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
+    succeed(nil).with_message("Import completed.")
+  end
+end
+```
+
+### Interaction Responses
+
+```ruby
+def execute
+  succeed(resource).with_message("Done!")
+  succeed(resource)
+    .with_redirect_response(custom_dashboard_path)
+    .with_message("Redirecting...")
+  failed(resource.errors)
+  failed("Something went wrong")
+  failed("Invalid value", :email)
+end
+```
+
+**Note:** Redirect is automatic on success. Only use `with_redirect_response` for a different destination.
+
+### Default CRUD Actions
+
+```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
+```
+
+### Action Authorization
+
+```ruby
+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 beyond `resource`):
+
+```ruby
+class ArchiveInteraction < Plutonium::Resource::Interaction
+  attribute :resource
+  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
+  input :email
+  # Has inputs = shows form first
+end
+```
+
+---
+
 ## Related Skills
 
-- `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
+- `plutonium-interaction` - Writing interaction classes
+- `plutonium-policy` - Controlling action access