plutonium 0.50.0 → 0.51.0

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

@@ -1,1223 +0,0 @@
----
-name: plutonium-definition
-description: Use BEFORE editing a resource definition — adding fields, inputs, displays, columns, metadata, index views (table/grid), search, filters, scopes, custom actions, modal/slideover behavior, 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
-- `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`
-- Packages: `packages/pkg_name/app/definitions/pkg_name/model_name_definition.rb`
-
-## Definition Structure
-
-```ruby
-class PostDefinition < Plutonium::Resource::Definition
-  # Fields, inputs, displays, columns
-  field :content, as: :markdown
-  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: :markdown
-end
-```
-
-### Portal-Specific Overrides
-
-```ruby
-# packages/admin_portal/app/definitions/admin_portal/post_definition.rb
-class AdminPortal::PostDefinition < ::PostDefinition
-  input :internal_notes, as: :text  # Only admins see this field
-  scope :pending_review             # Admin-specific scope
-end
-```
-
-## Separation of Concerns
-
-| Layer | Purpose | Example |
-|-------|---------|---------|
-| **Definition** | HOW fields render | `input :content, as: :markdown` |
-| **Policy** | WHAT is visible/editable | `permitted_attributes_for_read` |
-| **Interaction** | Business logic | `resource.update!(state: :archived)` |
-
-## Core Methods
-
-| 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 |
-
-## Basic Usage
-
-```ruby
-class PostDefinition < ResourceDefinition
-  # field - changes type everywhere
-  field :content, as: :markdown
-
-  # 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
-```
-
-## Available Field Types
-
-### 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? }
-
-  # 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
-```
-
-### 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
-  # Block syntax
-  nested_input :comments do |n|
-    n.input :body, as: :text
-    n.input :author_name
-  end
-
-  # Using another definition
-  nested_input :metadata, using: PostMetadataDefinition, fields: %i[seo_title seo_description]
-end
-```
-
-### 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`.
-- 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
-
-```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:
-
-```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
-```
-
-## Form Configuration
-
-```ruby
-class PostDefinition < ResourceDefinition
-  # Controls "Save and add another" / "Update and continue editing" buttons
-  # nil (default) = auto-detect (hidden for singular resources, shown for plural)
-  # true = always show
-  # false = always hide
-  submit_and_continue false
-
-  # How `:new` / `:edit` render. Default is :slideover.
-  #   :slideover — slide-in panel from the right (default)
-  #   :centered  — centered dialog
-  #   false      — full standalone pages (no modal)
-  modal :centered
-end
-```
-
-The `modal` setting only affects the framework-provided `:new` / `:edit`
-actions. Custom actions render in their own dialog, controlled by the
-per-action `modal:` option (`:centered` default, or `:slideover`).
-
-## 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
-```
-
-## Metadata Panel (Show Page)
-
-The `metadata` DSL declares a list of fields rendered in the show page's
-right-side aside as label/value rows. The main details card and the
-metadata aside share the same field-rendering machinery, so labels and
-formatting come from your existing `field` / `display` declarations.
-
-```ruby
-class PostDefinition < ResourceDefinition
-  metadata :author, :state, :created_at, :updated_at
-end
-```
-
-Behavior:
-
-- **Opt-in.** No `metadata` call → the show page renders full-width with
-  no aside.
-- **Policy-aware.** Metadata fields are intersected with the policy's
-  permitted attributes. Fields the user can't see disappear from the
-  panel; the panel auto-hides when nothing is permitted.
-- **Deduplicated.** Fields listed in `metadata` are removed from the main
-  details card so the same value never appears twice.
-- **Responsive.** Side-by-side at `lg+`, stacked single-column below.
-
-Use it for chrome that's not the focus of the record — timestamps,
-ownership, system flags — keeping the main card focused on the record's
-substance.
-
-## Index Views (Table & Grid)
-
-Resources can opt into a card-based **Grid** view alongside the default
-**Table** view. Users can switch between the two and the choice is
-persisted per-resource via cookie.
-
-```ruby
-class UserDefinition < ResourceDefinition
-  views :table, :grid       # enable both; user can switch
-  default_view :grid        # initial view if no cookie
-
-  grid_fields(
-    image:     :avatar,     # ActiveStorage attachment, Shrine, or URL
-    header:    :name,       # falls back to record.to_label
-    subheader: :email,
-    body:      :bio,
-    meta:      [:role, :status],   # rendered as small pills
-    footer:    :last_seen_at       # falls back to :created_at
-  )
-
-  grid_layout :media        # :compact (default) or :media
-  grid_columns 3            # pin to 3 cols on lg+; default is 1/2/3/4 responsive
-end
-```
-
-DSL surface:
-
-| Method | Purpose |
-|--------|---------|
-| `views :table, :grid` | Which views are available. Default `[:table]`. |
-| `default_view :grid` | Initial view when no cookie. Falls back to first view in `views`. |
-| `grid_fields(...)` | Maps card slots to fields. **Implicitly enables `:grid`** if not already in `views`. |
-| `grid_layout :media` | `:compact` (image left of content) or `:media` (full-width image on top). |
-| `grid_columns 3` | Override responsive column count on lg+. |
-
-Grid slots are all optional — `:image`, `:header`, `:subheader`, `:body`,
-`:meta`, `:footer`. `:meta` accepts an array; the rest are single
-fields. Slots that point at fields not permitted by the user's policy
-collapse silently.
-
-## 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
-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
-
----
-
-# 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},
-  modal: :slideover                # :centered (default) or :slideover —
-                                    # how the action's interaction form renders
-```
-
-**`Action#with(...)`** — actions are frozen value objects. To derive a
-variant (typically inside `customize_actions`) call
-`existing_action.with(turbo_frame: nil)` for a new copy with the
-overrides applied.
-
-### 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-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