plutonium 0.50.0 → 0.52.0

data/docs/guides/search-filtering.md

@@ -1,198 +1,130 @@
 # Search and Filtering
 
-This guide covers implementing search, filters, scopes, and sorting.
+Add a search box, sidebar filters, quick-scope buttons, and sortable columns to a resource's index page. All in the definition.
 
-## Overview
+## Goal
 
-Plutonium provides built-in support for:
-- **Search** - Full-text search across fields
-- **Filters** - Input filters for specific fields (dropdown panel)
-- **Scopes** - Predefined query shortcuts (quick filter buttons)
-- **Sorting** - Column-based ordering
+Users can:
 
-## Search
+- Type into a search box to narrow the index list.
+- Click sidebar filters to narrow by status / category / date / etc.
+- Click scope buttons (top-of-list quick filters) for common queries like "Published" or "My posts".
+- Click column headers to sort.
+
+![Search box, scope tabs, filter button, sortable columns](/images/guides/search-filtering-index.png)
+
+## The four pieces
+
+| DSL | Purpose |
+|---|---|
+| `search` | The top-level search box. ONE block, queries you define. |
+| `filter` | Sidebar filter inputs. One per filterable attribute. |
+| `scope` | Quick-filter buttons across the top. References model scopes (or inline blocks). |
+| `sort` / `default_sort` | Sortable columns. |
 
-Define global search in the definition:
+All declared in the definition.
+
+## Quick recipe
 
 ```ruby
 class PostDefinition < ResourceDefinition
+  # Search box — searches title and body
   search do |scope, query|
-    scope.where("title ILIKE ?", "%#{query}%")
+    scope.where("title ILIKE :q OR body ILIKE :q", q: "%#{query}%")
   end
-end
-```
 
-### Multi-Field Search
+  # Sidebar filters
+  filter :status,     with: :select, choices: %w[draft published archived]
+  filter :title,      with: :text,   predicate: :contains
+  filter :created_at, with: :date_range
 
-```ruby
-search do |scope, query|
-  scope.where(
-    "title ILIKE :q OR content ILIKE :q OR author_name ILIKE :q",
-    q: "%#{query}%"
-  )
-end
-```
+  # Quick-filter buttons
+  scope :published   # uses Post.published
+  scope :draft
 
-### Search with Associations
+  # Default scope (the "Published" button is highlighted on initial load)
+  default_scope :published
 
-```ruby
-search do |scope, query|
-  scope.joins(:author).where(
-    "posts.title ILIKE :q OR users.name ILIKE :q",
-    q: "%#{query}%"
-  ).distinct
+  # Sortable columns
+  sort :title
+  sort :created_at
+  default_sort :created_at, :desc
 end
 ```
 
-### Split Search Terms
+## Search
 
 ```ruby
+# Single field
 search do |scope, query|
-  terms = query.split(/\s+/)
-  terms.reduce(scope) do |current_scope, term|
-    current_scope.where("title ILIKE ?", "%#{term}%")
-  end
+  scope.where("title ILIKE ?", "%#{query}%")
 end
-```
-
-### Full-Text Search (PostgreSQL)
 
-```ruby
+# Multiple fields
 search do |scope, query|
   scope.where(
-    "to_tsvector('english', title || ' ' || body) @@ plainto_tsquery('english', ?)",
-    query
+    "title ILIKE :q OR content ILIKE :q OR author_name ILIKE :q",
+    q: "%#{query}%"
   )
 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
-class PostDefinition < ResourceDefinition
-  # Shorthand (recommended)
-  filter :title, with: :text, predicate: :contains
-  filter :status, with: :text, predicate: :eq
-
-  # Full class name also works
-  filter :slug, with: Plutonium::Query::Filters::Text, predicate: :starts_with
+# Across associations
+search do |scope, query|
+  scope.joins(:author).where(
+    "posts.title ILIKE :q OR users.name ILIKE :q",
+    q: "%#{query}%"
+  ).distinct
 end
 ```
 
-#### Available Predicates
-
-| Predicate | SQL | Description |
-|-----------|-----|-------------|
-| `:eq` | `= value` | Exact match (default) |
-| `:not_eq` | `!= value` | Not equal |
-| `:contains` | `LIKE %value%` | Contains text |
-| `: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
-```
-
-#### Available Predicates
+### The `search` block also powers typeahead
 
-| 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 |
+When an association input targets this resource, the dropdown's autocomplete calls the resource's `search` block. Same code, two surfaces.
 
-### Date Range Filter
+### Without a `search` block — typeahead fallback
 
-Filter between two dates (from/to):
+The framework falls back to a case-insensitive `LIKE` on the first column it finds, in priority order:
 
-```ruby
-# Basic
-filter :created_at, with: :date_range
+1. The input's `label_method:` option, if it's a real column.
+2. Otherwise the first match from `[name, title, label, slug, display_name, email]`.
+3. Otherwise the relation is returned unfiltered (capped).
 
-# Custom labels
-filter :published_at, with: :date_range,
-  from_label: "Published from",
-  to_label: "Published to"
-```
+For large tables, write an explicit `search` block — the leading-wildcard `LIKE` can't use a b-tree index. See [Reference › Resource › Query › Search](/reference/resource/query#search).
 
-Renders two date pickers. Both are optional - users can filter with just "from" or just "to".
+## Filters
 
-### Select Filter
+Six built-in types. Use shorthand symbols:
 
-Filter from predefined choices:
+| Type | Symbol | URL 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:` |
 
 ```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
+filter :title,        with: :text,        predicate: :contains
+filter :active,       with: :boolean
+filter :due_date,     with: :date,        predicate: :lt
+filter :created_at,   with: :date_range
+filter :status,       with: :select,      choices: %w[draft published]
+filter :category,     with: :select,      choices: -> { Category.pluck(:name) }
+filter :author,       with: :association, class_name: User
 ```
 
-### Association Filter
-
-Filter by associated record:
+### Custom filter (lambda)
 
 ```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
+filter :published, with: ->(scope, value) {
+  value == "true" ? scope.where.not(published_at: nil) : scope.where(published_at: nil)
+}
 ```
 
-Renders a resource select dropdown. Converts filter key to foreign key (`:category` -> `:category_id`).
-
-### 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:` |
+### Custom filter class
 
-### Custom Filter Class
+For reusable filters with multiple inputs:
 
 ```ruby
 class PriceRangeFilter < Plutonium::Query::Filter
@@ -205,99 +137,62 @@ class PriceRangeFilter < Plutonium::Query::Filter
   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
+Clicking **Filter** opens a slideover with one input per declared filter:
 
-Scopes appear as quick filter buttons. They reference model scopes or use inline blocks.
+![Filter slideover](/images/guides/search-filtering-panel.png)
 
-### Basic Scopes
-
-Reference existing model scopes:
+## Scopes (quick-filter buttons)
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  scope :published    # Uses Post.published
-  scope :draft        # Uses Post.draft
-  scope :featured     # Uses Post.featured
-end
-```
-
-### Inline Scopes
-
-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
+  scope :published    # uses Post.published
+  scope :draft        # uses Post.draft
 
-Inline scopes have access to controller context like `current_user`:
+  # Inline scope — block runs with scope as argument
+  scope(:recent) { |s| s.where('created_at > ?', 1.week.ago) }
 
-```ruby
-scope(:mine) { |scope| scope.where(author: current_user) }
-scope(:my_team) { |scope| scope.where(team: current_user.team) }
+  # Scope with controller context
+  scope(:mine) { |s| s.where(author: current_user) }
+end
 ```
 
-### Default Scope
+Named scopes reference a model scope. Inline scopes have access to `current_user`, `current_parent`, `current_scoped_entity`.
 
-Set a scope as default:
+### Default scope
 
 ```ruby
-class PostDefinition < ResourceDefinition
-  scope :published
-  scope :draft
-  scope :archived
-
-  default_scope :published
-end
+default_scope :published
 ```
 
-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
+- Applied on initial page load.
+- The default scope button is highlighted (not "All").
+- Clicking "All" shows the unscoped collection.
 
 ## Sorting
 
-### Define Sortable Fields
-
 ```ruby
-class PostDefinition < ResourceDefinition
-  sort :title
-  sort :created_at
-  sort :view_count
-
-  # Multiple at once
-  sorts :title, :created_at, :view_count
-end
-```
+sort :title
+sort :created_at
 
-### Default Sort Order
+sorts :title, :created_at, :view_count    # shorthand
 
-```ruby
-# Field and direction
 default_sort :created_at, :desc
-default_sort :title, :asc
 
-# Complex sorting with block
+# Complex with a block
 default_sort { |scope| scope.order(featured: :desc, created_at: :desc) }
 ```
 
-**Note:** Default sort only applies when no sort params are provided. The system default is `:id, :desc`.
+Framework default (nothing declared, no user sort): `id DESC`.
 
-## URL Parameters
+## URL parameters
 
-Query parameters are structured under `q`:
+Query params are namespaced under `q`:
 
 ```
 /posts?q[search]=rails
@@ -308,43 +203,37 @@ Query parameters are structured under `q`:
 /posts?q[sort_fields][]=created_at&q[sort_directions][created_at]=desc
 ```
 
-## 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
+## Performance tips
 
-  # Quick scopes (reference model scopes)
-  scope :active
-  scope :featured
-  scope(:recent) { |scope| scope.where("created_at > ?", 1.week.ago) }
+- **Add indexes** for filtered and sorted columns.
+- **Use `.distinct`** when joining associations in search — duplicate rows otherwise.
+- **Prefer scopes over filters** for queries used often (no input parsing).
+- **`LIKE '%q%'` can't use a b-tree index** — for large tables, use `pg_search` or a trigram/GIN/full-text index.
 
-  # Default scope
-  default_scope :active
+## Full-text search with `pg_search`
 
-  # Sortable columns
-  sorts :name, :price, :created_at
+```ruby
+# Model
+class Post < ResourceRecord
+  include PgSearch::Model
+  pg_search_scope :search_content, against: %i[title content]
+end
 
-  # Default sort: newest first
-  default_sort :created_at, :desc
+# Definition
+search do |scope, query|
+  scope.search_content(query)
 end
 ```
 
+## Common issues
+
+- **Filter not showing up** — make sure the attribute is in `permitted_attributes_for_index` on the policy.
+- **Slow search on large tables** — `LIKE '%q%'` can't be indexed by a b-tree. Switch to FTS or trigram.
+- **Duplicate rows in results** — add `.distinct` when joining associations.
+- **Typeahead works on small dev tables but slows in production** — same b-tree issue. Write an explicit `search` block backed by a proper index.
+
 ## Related
 
-- [Custom Actions](./custom-actions)
-- [Authorization](./authorization)
+- [Reference › Resource › Query](/reference/resource/query) — full surface
+- [Adding resources](./adding-resources) — basic resource setup
+- [Authorization](./authorization) — `permitted_attributes_for_index` gates which fields can be filtered

data/docs/guides/testing.md

@@ -101,7 +101,11 @@ current_account                       # uses portal from DSL
 with_portal(:org) { ... }            # scoped portal switch
 ```
 
-### Non-Rodauth auth
+::: info Default Rodauth login expects password `"password123"`
+`login_as` posts to `/<account_table>/login` with `password: "password123"` by default. Either create test accounts with that password (e.g. in fixtures or factories), or override the auth flow via `sign_in_for_tests` below.
+:::
+
+### Non-Rodauth auth (or skipping Rodauth in tests)
 
 Define `sign_in_for_tests(account, portal:)` in your test class (or in `test/support/plutonium_testing.rb` for project-wide use):
 
@@ -147,8 +151,9 @@ Output: `test/integration/<portal>_portal/<resource>_test.rb`.
 - **Nested resources need `parent:` in the DSL AND a parent record** from `parent_record!`. Both are required for path interpolation.
 - **`PortalAccess` uses `portal_access_for`**, not `resource_tests_for`. Don't mix them on the same class.
 
-## See also
+## Related
 
-- [Authorization](/guides/authorization) — write the policy this concern verifies
-- [Multi-tenancy](/guides/multi-tenancy) — entity scoping that drives nested-resource tests
-- [Authentication](/guides/authentication) — Rodauth setup behind the default login flow
+- [Reference › Testing](/reference/testing/) — full DSL reference, all concern stubs, override hooks
+- [Authorization](./authorization) — write the policy this concern verifies
+- [Multi-tenancy](./multi-tenancy) — entity scoping that drives nested-resource tests
+- [Authentication](./authentication) — Rodauth setup behind the default login flow