plutonium 0.50.0 → 0.51.0

data/docs/reference/resource/model.md

@@ -0,0 +1,348 @@
+# Model
+
+The model layer of a resource. Includes the `Plutonium::Resource::Record` module (via inheritance from `ResourceRecord`) on top of standard `ApplicationRecord`.
+
+## Base class
+
+All resource models inherit from `ResourceRecord` (created by `pu:core:install`):
+
+```ruby
+# Main app
+class Post < ResourceRecord
+end
+
+# Inside a feature package — uses the package's ResourceRecord
+module Blogging
+  class Post < Blogging::ResourceRecord
+  end
+end
+```
+
+`ResourceRecord` is abstract and inherits from `ApplicationRecord`. Standard ActiveRecord features (associations, validations, scopes, callbacks, attribute macros) all work — Plutonium adds capabilities on top.
+
+## What `Plutonium::Resource::Record` adds
+
+| Module | Purpose | Section |
+|---|---|---|
+| `HasCents` | Money handling — cents column ↔ decimal accessor | [has_cents](#has-cents) |
+| `Routes` | URL parameter customization (slugs, dynamic params) | [URL routing](#url-routing) |
+| `Labeling` | `to_label` for human-readable record names | [Labeling](#labeling) |
+| `FieldNames` | Field introspection by category | [Field introspection](#field-introspection) |
+| `Associations` | Auto-generated SGID accessors on every association | [SGID accessors](#sgid-accessors) |
+| `AssociatedWith` | Multi-tenant scoping — `Model.associated_with(entity)` | [Tenancy](/reference/tenancy/entity-scoping) |
+
+## Section layout
+
+Scaffolded models follow a strict ordering. Keep new code in the right section so files stay scannable:
+
+1. Concerns (`include`)
+2. Constants (`TYPES = {...}.freeze`)
+3. Enums
+4. Model configurations (`has_cents`)
+5. `belongs_to`
+6. `has_one`
+7. `has_many`
+8. Attachments (`has_one_attached`, `has_many_attached`)
+9. Scopes
+10. Validations
+11. Callbacks
+12. Delegations
+13. Misc macros (`has_rich_text`, `has_secure_token`, `has_secure_password`)
+14. Public methods, then `private`, then private methods
+
+Example:
+
+```ruby
+class Property < ResourceRecord
+  TYPES = {apartment: "Apartment", house: "House"}.freeze
+
+  enum :state, archived: 0, active: 1
+
+  has_cents :market_value_cents
+
+  belongs_to :company
+  has_one :address
+  has_many :units
+
+  has_one_attached :photo
+
+  scope :active, -> { where(state: :active) }
+
+  validates :name, presence: true
+  validates :property_code, presence: true, uniqueness: {scope: :company_id}
+
+  before_validation :generate_code, on: :create
+
+  has_rich_text :description
+
+  def full_address
+    address&.to_s
+  end
+
+  private
+
+  def generate_code
+    self.property_code ||= SecureRandom.hex(4).upcase
+  end
+end
+```
+
+## `has_cents`
+
+Stores monetary values as integer cents and exposes a decimal virtual accessor. Use this for money — never store decimals directly.
+
+```ruby
+class Product < ResourceRecord
+  has_cents :price_cents                    # column: price_cents (integer); accessor: price (decimal)
+  has_cents :cost_cents, name: :wholesale   # custom accessor name
+  has_cents :tax_cents, rate: 1000          # 3 decimal places (e.g. for fractional currencies)
+  has_cents :amount_yen, rate: 1            # currencies with no subunit (JPY)
+end
+
+product = Product.new
+product.price = 19.99
+product.price_cents  # => 1999
+product.price        # => 19.99
+
+# Truncates, never rounds
+product.price = 10.999
+product.price_cents  # => 1099
+```
+
+::: danger Use the virtual accessor in policies and definitions
+Reference `:price`, NOT `:price_cents`:
+
+```ruby
+# Policy
+def permitted_attributes_for_create
+  %i[name price]   # ✅ virtual name
+end
+
+# Definition
+field :price, as: :decimal   # ✅ virtual name
+```
+
+Generators sometimes emit the `_cents` name in the policy — fix by hand (and verify `has_cents` is declared on the model).
+:::
+
+### Options
+
+```ruby
+has_cents :field_cents,
+  name: :custom_name,     # accessor name (default: field with _cents stripped)
+  rate: 100,              # conversion rate (default: 100 for 2 decimal places)
+  suffix: "amount"        # suffix for generated name when name pattern matches
+```
+
+### Validation propagation
+
+Validations on the cents column automatically mark the virtual accessor invalid too:
+
+```ruby
+class Product < ResourceRecord
+  has_cents :price_cents
+  validates :price_cents, numericality: {greater_than: 0}
+end
+
+product = Product.new(price: -10)
+product.valid?              # => false
+product.errors[:price_cents] # => ["must be greater than 0"]
+product.errors[:price]       # => ["is invalid"]
+```
+
+The framework adds an `after_validation` hook that copies `:invalid` from `price_cents` → `price` automatically — no manual wiring needed.
+
+### Introspection
+
+```ruby
+Product.has_cents_attributes
+# => { price_cents: { name: :price, rate: 100 } }
+
+Product.has_cents_attribute?(:price_cents)  # => true
+```
+
+## URL routing
+
+### Default
+
+```ruby
+post.to_param  # => "1"      (numeric id)
+# URL: /posts/1
+```
+
+### `path_parameter` — use a stable column
+
+Use a column that's unique and human-readable instead of the numeric id:
+
+```ruby
+class User < ResourceRecord
+  path_parameter :username
+end
+
+user = User.create(username: "john_doe")
+user.to_param  # => "john_doe"
+# URL: /users/john_doe
+
+User.from_path_param("john_doe")   # finds by username
+```
+
+`path_parameter` is a class-level macro (private class method). The column you pass MUST be unique — Plutonium uses it for lookup.
+
+### `dynamic_path_parameter` — SEO-friendly id + slug
+
+Combines the id (for stable lookup) with a slug from another column (for SEO):
+
+```ruby
+class Article < ResourceRecord
+  dynamic_path_parameter :title
+end
+
+article = Article.create(id: 42, title: "Hello World")
+article.to_param  # => "42-hello-world"
+# URL: /articles/42-hello-world
+
+Article.from_path_param("42-hello-world")  # extracts "42", finds by id
+```
+
+The slug is informational — only the id portion is used for lookup, so changing the title doesn't break old URLs.
+
+## Labeling
+
+`to_label` provides a human-readable name for dropdowns, breadcrumbs, and display fallbacks.
+
+### Default resolution
+
+1. Returns `name` if the model has a `name` attribute.
+2. Returns `title` if the model has a `title` attribute.
+3. Falls back to `"ModelName #id"` (e.g. `"Post #42"`).
+
+```ruby
+post = Post.new(title: "Hello World")
+post.to_label  # => "Hello World"
+
+post.title = nil
+post.to_label  # => "Post #42"
+```
+
+### Override
+
+```ruby
+class Product < ResourceRecord
+  def to_label
+    "#{name} (#{sku})"
+  end
+end
+```
+
+## SGID accessors
+
+Every association on a resource model gets Signed Global ID accessors automatically — for secure form submission, API payloads, and hidden fields without exposing database ids.
+
+### Singular associations (`belongs_to`, `has_one`)
+
+```ruby
+class Post < ResourceRecord
+  belongs_to :user
+  has_one :featured_image
+end
+
+post.user_sgid               # get SGID
+post.user_sgid = "BAh7..."   # set: locates and assigns user from SGID
+
+post.featured_image_sgid
+post.featured_image_sgid = "..."
+```
+
+### Collection associations (`has_many`, `has_and_belongs_to_many`)
+
+```ruby
+class User < ResourceRecord
+  has_many :posts
+end
+
+user.post_sgids                   # => ["...", "..."]
+user.post_sgids = [sgid1, sgid2]  # bulk replace
+user.add_post_sgid(sgid)          # append
+user.remove_post_sgid(sgid)       # remove
+```
+
+These are what `secure_association_tag` uses in forms — see [UI › Forms](/reference/ui/forms).
+
+## Field introspection
+
+```ruby
+User.resource_field_names           # all fields suitable for UI
+User.content_column_field_names     # database columns
+User.belongs_to_association_field_names
+User.has_one_association_field_names      # excludes attachments
+User.has_many_association_field_names     # excludes attachments
+User.has_one_attached_field_names         # ActiveStorage single
+User.has_many_attached_field_names        # ActiveStorage multiple
+```
+
+Used internally by definitions for auto-detection. You rarely call these directly, but they're useful when writing dynamic UI in `customize_fields` / custom Phlex pages.
+
+Results are cached outside development (so changing the schema in dev hot-reloads correctly).
+
+## Nested attributes introspection
+
+```ruby
+Post.all_nested_attributes_options
+# => {
+#   comments: { allow_destroy: true, limit: 10, macro: :has_many, class: Comment },
+#   metadata: { update_only: true, macro: :has_one, class: PostMetadata }
+# }
+```
+
+Returns the configuration for all associations declared with `accepts_nested_attributes_for`. Used internally by `nested_input` in the definition.
+
+## Multi-tenancy: `associated_with`
+
+`Plutonium::Resource::Record` provides `Model.associated_with(entity)` for multi-tenant queries:
+
+```ruby
+Comment.associated_with(post)
+# => Comment.where(post: post)
+```
+
+Resolution order, association path requirements, three model shapes, and custom scopes are all covered in [Tenancy › Entity scoping](/reference/tenancy/entity-scoping).
+
+## Standard ActiveRecord features
+
+Everything you'd expect works — associations, validations, scopes, callbacks, delegations, `has_rich_text`, `has_secure_token`, `has_one_attached`, etc. Where Plutonium adds twists:
+
+- **Section ordering** is by convention, not enforcement — pick the right slot in the [layout above](#section-layout) so the file stays scannable.
+- **Compound uniqueness for tenant-scoped resources:** `validates :code, uniqueness: {scope: :organization_id}` — without the scope, uniqueness leaks across tenants.
+- **Keep models thin** — business logic that touches multiple records or has multi-step state changes belongs in [interactions](/reference/behavior/interactions), not model methods.
+
+## Nested resources
+
+Plutonium auto-generates nested routes from `has_many` and `has_one` associations. No model-side change needed beyond the association itself:
+
+```ruby
+class Comment < ResourceRecord
+  belongs_to :post
+end
+```
+
+When both `Post` and `Comment` are registered in a portal, `/posts/:post_id/nested_comments` exists automatically. See [Tenancy › Nested resources](/reference/tenancy/nested-resources).
+
+## Table naming in packages
+
+Namespaced models use prefixed tables by default:
+
+```ruby
+module Blogging
+  class Post < ResourceRecord
+    # table: blogging_posts
+  end
+end
+```
+
+Override with `self.table_name = "posts"` if you need a shared table.
+
+## Related
+
+- [Definition](./definition) — controls how the model's fields render
+- [Tenancy › Entity scoping](/reference/tenancy/entity-scoping) — `associated_with`, three model shapes
+- [App › Generators](/reference/app/generators) — `pu:res:scaffold` field syntax

data/docs/reference/resource/query.md

@@ -0,0 +1,305 @@
+# Query
+
+Search, filters, scopes, and sorting for a resource's index page. All declared in the definition.
+
+## Overview
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  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
+
+  scope :published
+  default_scope :published
+
+  sort :title
+  sort :created_at
+  default_sort :created_at, :desc
+end
+```
+
+## Search
+
+`search` defines global free-text search. The block receives the scope and the query string; return a filtered relation.
+
+```ruby
+search do |scope, query|
+  scope.where("title ILIKE ?", "%#{query}%")
+end
+```
+
+### Multi-field
+
+```ruby
+search do |scope, query|
+  scope.where(
+    "title ILIKE :q OR content ILIKE :q OR author_name ILIKE :q",
+    q: "%#{query}%"
+  )
+end
+```
+
+### Across associations
+
+```ruby
+search do |scope, query|
+  scope.joins(:author).where(
+    "posts.title ILIKE :q OR users.name ILIKE :q",
+    q: "%#{query}%"
+  ).distinct
+end
+```
+
+### Split terms
+
+```ruby
+search do |scope, query|
+  query.split(/\s+/).reduce(scope) do |s, term|
+    s.where("title ILIKE ?", "%#{term}%")
+  end
+end
+```
+
+### Search powers typeahead too
+
+The same `search` block drives **typeahead lookups** on association inputs that target this resource — when you write `input :author, …` for an association, the dropdown's autocomplete calls the target resource's `search` block.
+
+::: tip Typeahead fallback when there's no search block
+A resource without a `search` block still gets typeahead — the framework runs a case-insensitive `LIKE` against the first column that exists, in priority order:
+
+1. The input's `label_method:` option, if it names a real column on the model.
+2. Otherwise the first match from `[name, title, label, slug, display_name, email]`.
+3. If none exist, the relation is returned unfiltered (capped).
+
+For large tables, write an explicit `search` block backed by a trigram or full-text index. The fallback's leading-wildcard `LIKE '%q%'` can't use a b-tree index and gets slow past a few thousand rows.
+:::
+
+## Filters
+
+Six built-in filter types. Use the shorthand symbol or the full class name.
+
+| Type | Symbol | Params in URL | 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:` |
+
+### Text predicates
+
+`:eq`, `:not_eq`, `:contains`, `:not_contains`, `:starts_with`, `:ends_with`, `:matches`, `:not_matches`
+
+```ruby
+filter :title,  with: :text, predicate: :contains
+filter :status, with: :text, predicate: :eq
+filter :title,  with: Plutonium::Query::Filters::Text, predicate: :contains   # full class form
+```
+
+### Boolean
+
+```ruby
+filter :active,    with: :boolean
+filter :published, with: :boolean, true_label: "Published", false_label: "Draft"
+```
+
+### Date
+
+Predicates: `:eq`, `:not_eq`, `:lt`, `:lteq`, `:gt`, `:gteq`.
+
+```ruby
+filter :created_at,   with: :date, predicate: :gteq
+filter :due_date,     with: :date, predicate: :lt
+filter :published_at, with: :date, predicate: :eq
+```
+
+### Date range
+
+Two inputs (`from` + `to`):
+
+```ruby
+filter :created_at,   with: :date_range
+filter :published_at, with: :date_range,
+  from_label: "Published from",
+  to_label:   "Published to"
+```
+
+### Select
+
+```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
+
+```ruby
+filter :category, with: :association
+filter :author,   with: :association, class_name: User
+filter :tags,     with: :association, class_name: Tag, multiple: true
+```
+
+### Custom filter (lambda)
+
+For simple one-offs:
+
+```ruby
+filter :published, with: ->(scope, value) {
+  value == "true" ? scope.where.not(published_at: nil) : scope.where(published_at: nil)
+}
+```
+
+### Custom filter class
+
+For anything reusable or with multiple inputs:
+
+```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 across the top of the table.
+
+```ruby
+class PostDefinition < ResourceDefinition
+  scope :published    # uses Post.published
+  scope :draft        # uses Post.draft
+
+  # Inline scope — block runs with the scope as argument
+  scope(:recent)   { |s| s.where('created_at > ?', 1.week.ago) }
+  scope(:this_month) { |s| s.where(created_at: Time.current.all_month) }
+end
+```
+
+Named scopes reference a model scope of the same name. Inline (block) scopes have access to controller context (`current_user`, `current_parent`, etc.):
+
+```ruby
+scope(:mine)    { |s| s.where(author: current_user) }
+scope(:my_team) { |s| s.where(team: current_user.team) }
+```
+
+### Default scope
+
+```ruby
+default_scope :published
+```
+
+When a default is set:
+
+- It applies on initial page load.
+- The default scope button is highlighted (not "All").
+- Clicking "All" shows the unscoped collection.
+
+## Sorting
+
+```ruby
+sort :title
+sort :created_at
+
+sorts :title, :created_at, :view_count    # shorthand for several at once
+
+default_sort :created_at, :desc
+
+# Complex default sort with a block
+default_sort { |scope| scope.order(featured: :desc, created_at: :desc) }
+```
+
+The framework default (no `default_sort` declared, no user sort) is `id DESC`.
+
+## URL parameters
+
+Query parameters are namespaced 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
+```
+
+Combined:
+
+```
+/posts?q[search]=rails&q[scope]=published&q[sort_fields][]=created_at&q[sort_directions][created_at]=desc
+```
+
+## Common patterns
+
+### Full-text search with `pg_search`
+
+```ruby
+# Model
+class Post < ResourceRecord
+  include PgSearch::Model
+  pg_search_scope :search_content, against: %i[title content]
+end
+
+# Definition
+search do |scope, query|
+  scope.search_content(query)
+end
+```
+
+### Status filter + scopes
+
+```ruby
+filter :status, with: :select, choices: %w[draft published archived]
+scope :draft
+scope :published
+scope :archived
+```
+
+### Date-based scopes
+
+```ruby
+# Model
+scope :today,      -> { where(created_at: Time.current.all_day) }
+scope :this_week,  -> { where(created_at: Time.current.all_week) }
+scope :this_month, -> { where(created_at: Time.current.all_month) }
+
+# Definition
+scope :today
+scope :this_week
+scope :this_month
+```
+
+## Performance
+
+- **Add indexes** for filtered and sorted columns.
+- **Use `.distinct`** when joining associations in search to avoid duplicate rows.
+- **Prefer scopes over filters** for queries used often (faster, no input parsing).
+- **`pg_search` / FTS** for complex search — write an explicit `search` block.
+- **`LIKE '%q%'` can't use a b-tree index** — the typeahead fallback and naive search blocks get slow on large tables. Plan a trigram or full-text index when scaling.
+
+## Related
+
+- [Definition](./definition) — field/input/display configuration
+- [Actions](./actions) — custom and bulk actions
+- [Behavior › Policy](/reference/behavior/policies) — `relation_scope` (filters records to what the user can see)
+- [Tenancy › Entity scoping](/reference/tenancy/entity-scoping) — multi-tenant filtering