plutonium 0.34.1 → 0.35.0

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

@@ -1,334 +0,0 @@
----
-name: 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 - sidebar filter inputs
-  filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
-
-  # 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
-
-Currently Plutonium provides the **Text filter** with various predicates.
-
-### Text Filter Predicates
-
-```ruby
-# Exact match
-filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
-
-# Not equal
-filter :status, with: Plutonium::Query::Filters::Text, predicate: :not_eq
-
-# Contains (LIKE %value%)
-filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
-
-# Not contains
-filter :title, with: Plutonium::Query::Filters::Text, predicate: :not_contains
-
-# Starts with (LIKE value%)
-filter :slug, with: Plutonium::Query::Filters::Text, predicate: :starts_with
-
-# Ends with (LIKE %value)
-filter :email, with: Plutonium::Query::Filters::Text, predicate: :ends_with
-
-# Pattern match (* becomes %)
-filter :title, with: Plutonium::Query::Filters::Text, predicate: :matches
-
-# Not matching pattern
-filter :title, with: Plutonium::Query::Filters::Text, predicate: :not_matches
-```
-
-### Custom Filter with Lambda
-
-```ruby
-filter :published, with: ->(scope, value) {
-  value == "true" ? scope.where.not(published_at: nil) : scope.where(published_at: nil)
-}
-```
-
-### Custom Filter Class
-
-```ruby
-# Define custom filter
-class DateRangeFilter < Plutonium::Query::Filter
-  def apply(scope, start_date: nil, end_date: nil)
-    scope = scope.where("#{key} >= ?", start_date.beginning_of_day) if start_date.present?
-    scope = scope.where("#{key} <= ?", end_date.end_of_day) if end_date.present?
-    scope
-  end
-
-  def customize_inputs
-    input :start_date, as: :date
-    input :end_date, as: :date
-  end
-end
-
-# Use in definition
-filter :created_at, with: DateRangeFilter
-```
-
-## 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[status][query]=published
-/posts?q[scope]=recent
-/posts?q[sort_fields][]=created_at&q[sort_directions][created_at]=desc
-```
-
-Combined:
-```
-/posts?q[search]=rails&q[scope]=published&q[sort_fields][]=created_at&q[sort_directions][created_at]=desc
-```
-
-## Common Patterns
-
-### Status Filter
-
-```ruby
-class PostDefinition < ResourceDefinition
-  filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
-
-  scope :draft
-  scope :published
-  scope :archived
-end
-```
-
-### Date-Based Scopes
-
-```ruby
-class PostDefinition < ResourceDefinition
-  scope(:today) { |scope| scope.where(created_at: Time.current.all_day) }
-  scope(:this_week) { |scope| scope.where(created_at: Time.current.all_week) }
-  scope(:this_month) { |scope| scope.where(created_at: Time.current.all_month) }
-end
-```
-
-### Archive State Scopes
-
-```ruby
-class PostDefinition < ResourceDefinition
-  scope :active
-  scope :archived
-
-  # Default to showing only active
-  default_sort { |scope| scope.active.order(created_at: :desc) }
-end
-```
-
-### Full-Text Search with pg_search
-
-```ruby
-# Model
-class Post < ApplicationRecord
-  include PgSearch::Model
-  pg_search_scope :search_content, against: [:title, :content]
-end
-
-# Definition
-class PostDefinition < ResourceDefinition
-  search do |scope, query|
-    scope.search_content(query)
-  end
-end
-```
-
-### Association Filtering
-
-```ruby
-class PostDefinition < ResourceDefinition
-  filter :author_name, with: Plutonium::Query::Filters::Text, predicate: :contains
-
-  search do |scope, query|
-    scope.joins(:author).where(
-      "posts.title ILIKE :q OR users.name ILIKE :q",
-      q: "%#{query}%"
-    ).distinct
-  end
-end
-```
-
-## Complete Example
-
-```ruby
-class PostDefinition < ResourceDefinition
-  # Full-text search
-  search do |scope, query|
-    scope.where(
-      "title ILIKE :q OR content ILIKE :q",
-      q: "%#{query}%"
-    )
-  end
-
-  # Filters
-  filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
-  filter :category, with: Plutonium::Query::Filters::Text, predicate: :eq
-  filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
-
-  # Quick scopes (reference model scopes)
-  scope :published
-  scope :draft
-  scope :featured
-  scope(:recent) { |scope| scope.where('created_at > ?', 1.week.ago) }
-
-  # Sortable columns
-  sorts :title, :created_at, :view_count, :published_at
-
-  # Default: newest first
-  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
-
-- `definition` - Overview and structure
-- `definition-fields` - Fields, inputs, displays
-- `definition-actions` - Actions and interactions

data/docs/concepts/architecture.md

@@ -1,226 +0,0 @@
-# Architecture
-
-Plutonium follows a layered architecture where each layer has a specific responsibility. This separation makes applications easier to understand, test, and maintain.
-
-## The Four Layers
-
-### 1. Model Layer
-
-The Model layer handles **data and business rules**.
-
-```ruby
-class Post < ResourceRecord
-  belongs_to :user
-  has_many :comments
-
-  validates :title, presence: true
-  validates :body, presence: true
-
-  scope :published, -> { where(published: true) }
-end
-```
-
-Responsibilities:
-- Database schema and migrations
-- Validations
-- Associations
-- Scopes and queries
-- Core business logic
-
-### 2. Definition Layer
-
-The Definition layer controls **how resources render**.
-
-```ruby
-class PostDefinition < Plutonium::Resource::Definition
-  # Fields shown in forms
-  field :title
-  field :body, as: :rich_text
-  field :published, as: :switch
-
-  # Columns shown in tables
-  column :title, sortable: true
-  column :published
-  column :created_at
-
-  # Custom actions
-  action :publish, interaction: PublishPost
-end
-```
-
-Responsibilities:
-- Which fields appear in forms
-- How fields are rendered (input types)
-- Table column configuration
-- Search and filtering
-- Custom actions
-- Field groups and layout
-
-### 3. Policy Layer
-
-The Policy layer controls **authorization**.
-
-```ruby
-class PostPolicy < Plutonium::Resource::Policy
-  def read?
-    record.published? || owner?
-  end
-
-  def update?
-    owner?
-  end
-
-  def permitted_attributes_for_update
-    [:title, :body, :published]
-  end
-
-  def relation_scope(relation)
-    relation.where(published: true).or(relation.where(user: user))
-  end
-end
-```
-
-Responsibilities:
-- Action permissions (can user perform action?)
-- Attribute permissions (which fields can user see/modify?)
-- Collection scoping (which records can user access?)
-- Multi-tenancy isolation
-
-### 4. Controller Layer
-
-The Controller layer handles **HTTP requests**.
-
-```ruby
-class PostsController < Plutonium::Resource::Controller
-  private
-
-  def build_resource
-    super.tap do |post|
-      post.user = current_user
-    end
-  end
-
-  def after_create_success
-    notify_subscribers(@resource)
-    super
-  end
-end
-```
-
-Responsibilities:
-- CRUD actions
-- Request/response handling
-- Resource building hooks
-- Redirects and rendering
-- Format handling (HTML, JSON, etc.)
-
-## Request Flow
-
-When a request comes in, it flows through the layers:
-
-```
-1. REQUEST arrives at Portal
-   ↓
-2. CONTROLLER receives request
-   ↓
-3. POLICY checks authorization
-   ↓
-4. DEFINITION determines rendering
-   ↓
-5. MODEL provides data
-   ↓
-6. RESPONSE rendered and returned
-```
-
-### Example: Viewing a Post
-
-```
-GET /admin/posts/1
-
-1. AdminPortal routes to PostsController#show
-2. PostsController loads Post.find(1)
-3. PostPolicy#read? checks if user can view
-4. PostDefinition provides field configuration
-5. UI renders the post display
-6. HTML response returned
-```
-
-### Example: Creating a Post
-
-```
-POST /admin/posts
-
-1. AdminPortal routes to PostsController#create
-2. PostsController builds new Post
-3. PostPolicy#create? checks if user can create
-4. PostPolicy#permitted_attributes_for_create filters params
-5. Post validates and saves
-6. Redirect to show page
-```
-
-## Layer Interaction
-
-Layers communicate through well-defined interfaces:
-
-```ruby
-# Controller asks Policy
-policy = policy_for(resource)
-policy.authorize!(:update)
-
-# Controller uses Definition
-definition = definition_for(resource)
-definition.fields_for(:form)
-
-# Policy uses Model
-def owner?
-  record.user_id == user.id
-end
-```
-
-## Customization Points
-
-Each layer provides hooks for customization:
-
-### Model Hooks
-- Callbacks (before_save, after_create, etc.)
-- Custom methods
-- Scopes
-
-### Definition Hooks
-- Field configuration
-- Custom renderers
-- Conditional display
-
-### Policy Hooks
-- Custom permission methods
-- Attribute filtering
-- Scope customization
-
-### Controller Hooks
-- `build_resource` - Customize resource initialization
-- `before_action` - Standard Rails callbacks
-- `after_*_success/failure` - Action result hooks
-
-## Why This Architecture?
-
-### 1. Separation of Concerns
-Each layer has one job. Forms don't know about authorization. Policies don't know about rendering.
-
-### 2. Testability
-Each layer can be tested in isolation:
-- Model specs test validations and queries
-- Policy specs test authorization
-- Definition specs test field configuration
-- Controller specs test request handling
-
-### 3. Reusability
-Definitions and policies can be shared across portals. Models are independent of the UI.
-
-### 4. Maintainability
-Changes to authorization don't affect forms. UI changes don't affect data logic.
-
-## Related Topics
-
-- [Resources](./resources) - Understanding resource classes
-- [Packages and Portals](./packages-portals) - Organizing your application
-- [Auto-Detection](./auto-detection) - How defaults are determined