plutonium 0.34.1 → 0.35.0

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

@@ -0,0 +1,356 @@
+---
+name: plutonium-definition-query
+description: Configure search, filters, scopes, and sorting for Plutonium resources
+---
+
+# Definition Query
+
+Configure how users can search, filter, and sort resource collections.
+
+## Overview
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Search - global text search
+  search do |scope, query|
+    scope.where("title ILIKE ?", "%#{query}%")
+  end
+
+  # Filters - dropdown filter panel
+  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
+
+  # Scopes - quick filter buttons
+  scope :published
+  scope :draft
+
+  # Sorting - sortable columns
+  sort :title
+  sort :created_at
+
+  # Default sort
+  default_sort :created_at, :desc
+end
+```
+
+## Search
+
+Define global search across fields:
+
+```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
+
+# Split search terms
+search do |scope, query|
+  terms = query.split(/\s+/)
+  terms.reduce(scope) do |current_scope, term|
+    current_scope.where("title ILIKE ?", "%#{term}%")
+  end
+end
+```
+
+## Filters
+
+Plutonium provides **6 built-in filter types**. Use shorthand symbols or full class names.
+
+### Text Filter
+
+String/text filtering with pattern matching.
+
+```ruby
+# Shorthand (recommended)
+filter :title, with: :text, predicate: :contains
+filter :status, with: :text, predicate: :eq
+
+# Full class name
+filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
+```
+
+**Predicates:**
+
+| Predicate | SQL | Description |
+|-----------|-----|-------------|
+| `:eq` | `= value` | Exact match (default) |
+| `:not_eq` | `!= value` | Not equal |
+| `:contains` | `LIKE %value%` | Contains substring |
+| `:not_contains` | `NOT LIKE %value%` | Does not contain |
+| `:starts_with` | `LIKE value%` | Starts with |
+| `:ends_with` | `LIKE %value` | Ends with |
+| `:matches` | `LIKE value` | Pattern match (`*` becomes `%`) |
+| `:not_matches` | `NOT LIKE value` | Does not match pattern |
+
+### Boolean Filter
+
+True/false filtering for boolean columns.
+
+```ruby
+# Basic
+filter :active, with: :boolean
+
+# Custom labels
+filter :published, with: :boolean, true_label: "Published", false_label: "Draft"
+```
+
+Renders a select dropdown with "All", true label ("Yes"), and false label ("No").
+
+### Date Filter
+
+Single date filtering with comparison predicates.
+
+```ruby
+filter :created_at, with: :date, predicate: :gteq  # On or after
+filter :due_date, with: :date, predicate: :lt      # Before
+filter :published_at, with: :date, predicate: :eq  # On exact date
+```
+
+**Predicates:**
+
+| Predicate | Description |
+|-----------|-------------|
+| `:eq` | On this date (default) |
+| `:not_eq` | Not on this date |
+| `:lt` | Before date |
+| `:lteq` | On or before date |
+| `:gt` | After date |
+| `:gteq` | On or after date |
+
+### Date Range Filter
+
+Filter between two dates (from/to).
+
+```ruby
+# Basic
+filter :created_at, with: :date_range
+
+# Custom labels
+filter :published_at, with: :date_range,
+  from_label: "Published from",
+  to_label: "Published to"
+```
+
+Renders two date pickers. Both are optional - users can filter with just "from" or just "to".
+
+### Select Filter
+
+Filter from predefined choices.
+
+```ruby
+# Static choices (array)
+filter :status, with: :select, choices: %w[draft published archived]
+
+# Dynamic choices (proc)
+filter :category, with: :select, choices: -> { Category.pluck(:name) }
+
+# Multiple selection
+filter :tags, with: :select, choices: %w[ruby rails js], multiple: true
+```
+
+### Association Filter
+
+Filter by associated record.
+
+```ruby
+# Basic - infers Category class from :category key
+filter :category, with: :association
+
+# Explicit class
+filter :author, with: :association, class_name: User
+
+# Multiple selection
+filter :tags, with: :association, class_name: Tag, multiple: true
+```
+
+Renders a resource select dropdown. Converts filter key to foreign key (`:category` -> `:category_id`).
+
+## Custom Filters
+
+### 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
+
+# Use in definition
+filter :price, with: PriceRangeFilter
+```
+
+## Scopes
+
+Scopes appear as quick filter buttons. They reference model scopes.
+
+### Basic Usage
+
+```ruby
+class PostDefinition < ResourceDefinition
+  scope :published    # Uses Post.published
+  scope :draft        # Uses Post.draft
+  scope :featured     # Uses Post.featured
+end
+```
+
+### Inline Scope
+
+Use block syntax with the scope passed as an argument:
+
+```ruby
+scope(:recent) { |scope| scope.where('created_at > ?', 1.week.ago) }
+scope(:this_month) { |scope| scope.where(created_at: Time.current.all_month) }
+```
+
+### With Controller Context
+
+Inline scopes have access to controller context like `current_user`:
+
+```ruby
+scope(:mine) { |scope| scope.where(author: current_user) }
+scope(:my_team) { |scope| scope.where(team: current_user.team) }
+```
+
+### Default Scope
+
+Set a scope as default to apply it when no scope is explicitly selected:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  scope :published, default: true  # Applied by default
+  scope :draft
+  scope :archived
+end
+```
+
+When a default scope is set:
+- The default scope is applied on initial page load
+- The default scope button is highlighted (not "All")
+- Clicking "All" shows all records without any scope filter
+- URL without scope param uses the default; URL with `?q[scope]=` uses "All"
+
+## Sorting
+
+### Basic Sorting
+
+```ruby
+sort :title
+sort :created_at
+sort :view_count
+
+# Multiple at once
+sorts :title, :created_at, :view_count
+```
+
+### Default Sort
+
+```ruby
+# Field and direction
+default_sort :created_at, :desc
+default_sort :title, :asc
+
+# Complex sorting with block
+default_sort { |scope| scope.order(featured: :desc, created_at: :desc) }
+```
+
+**Note:** Default sort only applies when no sort params are provided.
+
+## URL Parameters
+
+Query parameters are structured under `q`:
+
+```
+/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:` |
+
+## Complete Example
+
+```ruby
+class ProductDefinition < ResourceDefinition
+  # Full-text search
+  search do |scope, query|
+    scope.where(
+      "name ILIKE :q OR description ILIKE :q",
+      q: "%#{query}%"
+    )
+  end
+
+  # Filters
+  filter :name, with: :text, predicate: :contains
+  filter :status, with: :select, choices: %w[draft active discontinued]
+  filter :featured, with: :boolean
+  filter :created_at, with: :date_range
+  filter :price, with: :date, predicate: :gteq
+  filter :category, with: :association
+
+  # Quick scopes
+  scope :active, default: true
+  scope :featured
+  scope(:recent) { |scope| scope.where('created_at > ?', 1.week.ago) }
+
+  # Sortable columns
+  sorts :name, :price, :created_at
+
+  # Default sort
+  default_sort :created_at, :desc
+end
+```
+
+## 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
+
+## Related Skills
+
+- `plutonium-definition` - Overview and structure
+- `plutonium-definition-fields` - Fields, inputs, displays
+- `plutonium-definition-actions` - Actions and interactions

data/.claude/skills/{forms → plutonium-forms}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: forms
+name: plutonium-forms
 description: Plutonium forms - custom templates, Phlex form components, field builders, and theming
 ---
 
@@ -432,8 +432,8 @@ end
 
 ## Related Skills
 
-- `definition-fields` - Input configuration (as:, hint:, condition:)
-- `views` - Custom page classes
-- `assets` - TailwindCSS and component theming
-- `interaction` - Interactive action forms
-- `nested-resources` - Parent/child forms
+- `plutonium-definition-fields` - Input configuration (as:, hint:, condition:)
+- `plutonium-views` - Custom page classes
+- `plutonium-assets` - TailwindCSS and component theming
+- `plutonium-interaction` - Interactive action forms
+- `plutonium-nested-resources` - Parent/child forms

data/.claude/skills/{installation → plutonium-installation}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: installation
+name: plutonium-installation
 description: Installing Plutonium in a Rails application - setup, generators, and configuration
 ---
 
@@ -290,11 +290,11 @@ For models that already exist in your app:
 
 ## Related Skills
 
-- `resource` - Resource architecture overview
-- `rodauth` - Authentication setup and configuration
-- `package` - Feature and portal packages
-- `portal` - Portal configuration
-- `views` - Custom pages, layouts, and Phlex components
-- `assets` - TailwindCSS and custom styling
-- `create-resource` - Resource scaffold options
-- `connect-resource` - Portal connection
+- `plutonium-resource` - 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

data/.claude/skills/{interaction → plutonium-interaction}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: interaction
+name: plutonium-interaction
 description: Plutonium interactions - encapsulated business logic for custom actions
 ---
 
@@ -68,7 +68,7 @@ input :content, as: :text
 input :date, as: :date
 ```
 
-See `definition-fields` skill for all input types and options.
+See `plutonium-definition-fields` skill for all input types and options.
 
 ## Presentation
 
@@ -103,25 +103,22 @@ end
 ### Success Outcomes
 
 ```ruby
-# Basic success
+# Basic success (redirects automatically to resource)
 succeed(resource)
 
 # With message
 succeed(resource).with_message("Done!")
 succeed(resource).with_message("Warning!", :alert)
 
-# With redirect
-succeed(resource).with_redirect_response(posts_path)
+# With custom redirect (only if different from default)
+succeed(resource).with_redirect_response(custom_path)
 
 # With file download
 succeed(resource).with_file_response(file_path, filename: "report.pdf")
-
-# Chaining
-succeed(resource)
-  .with_message("Created!")
-  .with_redirect_response(resource_path(resource))
 ```
 
+**Note:** Redirect is automatic on success - the controller redirects to the resource by default. Only use `with_redirect_response` if you need a different destination.
+
 ### Failure Outcomes
 
 ```ruby
@@ -183,10 +180,14 @@ class ArchiveInteraction < Plutonium::Resource::Interaction
   def execute
     resource.update!(archived: true)
     succeed(resource)
+  rescue ActiveRecord::RecordInvalid => e
+    failed(e.record.errors)
   end
 end
 ```
 
+**Note:** `ActiveRecord::RecordInvalid` is NOT rescued automatically. Always rescue it when using bang methods (`create!`, `update!`, `save!`).
+
 ### Resource Actions
 
 Act at the collection/class level (no specific record):
@@ -208,11 +209,11 @@ end
 
 ### Bulk Actions (Multiple Records)
 
-Act on multiple selected records:
+Act on multiple selected records. When registered, the table shows checkboxes and a toolbar appears when records are selected.
 
 ```ruby
 class BulkArchiveInteraction < Plutonium::Resource::Interaction
-  attribute :resources  # Collection of records
+  attribute :resources  # Collection of records (note: plural)
 
   def execute
     resources.update_all(archived: true)
@@ -221,6 +222,8 @@ class BulkArchiveInteraction < Plutonium::Resource::Interaction
 end
 ```
 
+**Authorization:** Bulk actions use per-record authorization. The policy method is checked for each selected record - if any fails, the entire request is rejected. The UI only shows actions that all selected records support.
+
 ## Connecting to Definitions
 
 Register interactions as actions:
@@ -344,9 +347,7 @@ class Company::InviteUserInteraction < Plutonium::Resource::Interaction
     )
     UserInviteMailer.invitation(invite).deliver_later
 
-    succeed(resource)
-      .with_message("Invitation sent to #{email}")
-      .with_redirect_response(resource)
+    succeed(resource).with_message("Invitation sent to #{email}")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
   end
@@ -376,7 +377,7 @@ end
 
 ## Related Skills
 
-- `definition-actions` - Declaring actions in definitions
-- `forms` - Custom interaction form templates
-- `policy` - Controlling access to actions
-- `resource` - How interactions fit in the architecture
+- `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

data/.claude/skills/{model → plutonium-model}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: model
+name: plutonium-model
 description: Overview of Plutonium resource models - structure, setup, and best practices
 ---
 
@@ -263,5 +263,5 @@ Models integrate with:
 
 ## Related Skills
 
-- `model-features` - has_cents, associations, scopes, routes
-- `create-resource` - Scaffold generator for new resources
+- `plutonium-model-features` - has_cents, associations, scopes, routes
+- `plutonium-create-resource` - Scaffold generator for new resources

data/.claude/skills/{model-features → plutonium-model-features}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: model-features
+name: plutonium-model-features
 description: Plutonium model features - has_cents, associations, scopes, and routing
 ---
 
@@ -282,5 +282,5 @@ sgid_array.each { |sgid| user.add_post_sgid(sgid) }
 
 ## Related Skills
 
-- `model` - Model overview and structure
-- `create-resource` - Scaffold generator
+- `plutonium-model` - Model overview and structure
+- `plutonium-create-resource` - Scaffold generator

data/.claude/skills/{nested-resources → plutonium-nested-resources}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: nested-resources
+name: plutonium-nested-resources
 description: Plutonium nested resources - parent/child routes, scoping, and URL generation
 ---
 
@@ -268,7 +268,7 @@ Generates nested routes:
 
 ## Related Skills
 
-- `portal` - Route registration
-- `policy` - Authorization and scoping
-- `controller` - Presentation hooks
-- `model-features` - associated_with scope
+- `plutonium-portal` - Route registration
+- `plutonium-policy` - Authorization and scoping
+- `plutonium-controller` - Presentation hooks
+- `plutonium-model-features` - associated_with scope

data/.claude/skills/{package → plutonium-package}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: package
+name: plutonium-package
 description: Plutonium packages - modular Rails engines for organizing features and portals
 ---
 
@@ -74,8 +74,7 @@ packages/admin_portal/
 │   ├── controllers/admin_portal/
 │   │   ├── concerns/controller.rb
 │   │   ├── dashboard_controller.rb
-│   │   ├── plutonium_controller.rb
-│   │   └── resource_controller.rb
+│   │   └── plutonium_controller.rb
 │   ├── definitions/admin_portal/     # Portal-specific overrides
 │   ├── policies/admin_portal/        # Portal-specific overrides
 │   └── views/
@@ -101,7 +100,7 @@ module AdminPortal
 end
 ```
 
-See `portal` skill for portal-specific features.
+See `plutonium-portal` skill for portal-specific features.
 
 ## Package Loading
 
@@ -185,7 +184,7 @@ rails db:migrate  # Runs migrations from all packages
 
 ## Related Skills
 
-- `portal` - Portal-specific features (auth, entity scoping, routes)
-- `resource` - Resource architecture overview
-- `connect-resource` - Connecting resources to portals
-- `create-resource` - Creating resources
+- `plutonium-portal` - Portal-specific features (auth, entity scoping, routes)
+- `plutonium-resource` - Resource architecture overview
+- `plutonium-connect-resource` - Connecting resources to portals
+- `plutonium-create-resource` - Creating resources

data/.claude/skills/{policy → plutonium-policy}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: policy
+name: plutonium-policy
 description: Plutonium resource policies - authorization, attribute permissions, and scoping
 ---
 
@@ -87,6 +87,28 @@ end
 
 Actions are secure by default - undefined methods return `false`.
 
+### Bulk Action Authorization
+
+Bulk actions (operating on multiple selected records) support **per-record authorization**:
+
+```ruby
+def bulk_archive?
+  create? && !record.locked?  # Per-record check
+end
+
+def bulk_publish?
+  user.admin? || record.author == user
+end
+```
+
+**How bulk authorization works:**
+1. Policy method (e.g., `bulk_archive?`) is checked **per record** in the selection
+2. **Backend:** If any selected record fails authorization, the entire request is rejected
+3. **UI:** Only actions that **all** selected records support are shown (intersection)
+4. Records are fetched via `current_authorized_scope` - only accessible records can be selected
+
+This provides full per-record authorization while keeping the UI clean - users only see actions they can actually perform on their entire selection.
+
 ## Attribute Permissions
 
 ### Core Methods (Must Override for Production)
@@ -347,6 +369,6 @@ end
 
 ## Related Skills
 
-- `resource` - How policies fit in the resource architecture
-- `definition-actions` - Actions that need policy methods
-- `controller` - How controllers use policies
+- `plutonium-resource` - How policies fit in the resource architecture
+- `plutonium-definition-actions` - Actions that need policy methods
+- `plutonium-controller` - How controllers use policies