plutonium 0.64.0 → 0.66.0

data/docs/reference/resource/export.md

@@ -1,7 +1,7 @@
 # CSV Export
 
 Every resource ships with a streamed CSV export, **disabled by default**. It is *not* an
-[action](./actions.md) — it streams a file and opens in a new tab — so it is enabled
+[action](./actions.md) (it streams a file and opens in a new tab), so it is enabled
 through the policy rather than declared with `action :export_csv`. The route
 (`GET /<resources>/export_csv`) is auto-mounted on every resource; a split "Export"
 button appears on the index page once the policy permits it.
@@ -25,8 +25,8 @@ The control is a split button with two behaviours:
 
 | | Source | Filename |
 |---|---|---|
-| **Export** (primary) | The current view — selected scope + filters + search (the index's `?q`), **all** matching rows (not just the visible page) | `posts_<date>.csv` |
-| **Export all** (dropdown) | The entire authorized scope — ignores scope, filters, search, and default scope | `posts_all_<date>.csv` |
+| **Export** (primary) | The current view: selected scope + filters + search (the index's `?q`), **all** matching rows (not just the visible page) | `posts_<date>.csv` |
+| **Export all** (dropdown) | The entire authorized scope: ignores scope, filters, search, and default scope | `posts_all_<date>.csv` |
 
 "Export all" always exports everything the user is authorized to read, regardless of the
 current scope/filters.
@@ -73,12 +73,12 @@ For a column **without** an `export` block, the value is read straight off the r
 (`record.public_send(name)`):
 
 - **Scalars** (strings, numbers, booleans, dates) are written as-is.
-- **Associations** render as their display label — the same `display_name_of` the index
-  uses (e.g. `User #5`, or the record's `to_label`/`name`/`title` if defined) — never
+- **Associations** render as their display label: the same `display_name_of` the index
+  uses (e.g. `User #5`, or the record's `to_label`/`name`/`title` if defined), never
   `#<User:0x…>`. Add an `export` block to export a specific field instead (e.g. the email).
 - A name that is **neither** an `export` block **nor** a real method on the record renders
   the placeholder `<<invalid column>>` rather than aborting the (already-streaming) download.
-  To export a computed or virtual column, give it an `export` block — a `label:`-only
+  To export a computed or virtual column, give it an `export` block: a `label:`-only
   `export` does **not** supply a value, so it too renders the placeholder.
 
 ## Notes & limits
@@ -90,5 +90,9 @@ For a column **without** an `export` block, the value is read straight off the r
   intercepting the streamed download.
 - **CSV/formula injection** is neutralized: any cell whose value begins with `=`, `+`,
   `-`, `@`, or a leading tab/CR is prefixed with a single quote so spreadsheet apps import
-  it as literal text instead of executing it as a formula.
+  it as literal text instead of executing it as a formula. The check is run against the
+  NFKC-normalized value, so full-width (double-byte) variants (`＝`, `＋`, `－`, `＠`) that
+  East Asian locales treat as formula initiators are neutralized too; the original
+  (un-normalized) value is what gets the quote prefix, so legitimate full-width content
+  is preserved verbatim.
 - `csv` is a runtime dependency of Plutonium (it is no longer a Ruby default gem on 3.4+).

data/docs/reference/resource/index.md

@@ -1,14 +1,14 @@
 # Resource Reference
 
-A **resource** is the unit Plutonium gives you full CRUD for — list, show, create, edit, delete — automatically. It's four cooperating layers, plus an optional fifth for business logic.
+A **resource** is the unit Plutonium gives you full CRUD for (list, show, create, edit, delete) automatically. It's four cooperating layers, plus an optional fifth for business logic.
 
 | Layer | File | What it controls |
 |---|---|---|
 | [Model](./model) | `app/models/post.rb` | Data, validations, associations |
-| [Definition](./definition) | `app/definitions/post_definition.rb` | UI — which fields, how they render, what actions exist |
-| Policy | `app/policies/post_policy.rb` | Authorization — see [Behavior › Policy](/reference/behavior/policies) |
-| Controller | `app/controllers/posts_controller.rb` | Request handling — see [Behavior › Controller](/reference/behavior/controllers) |
-| Interaction *(optional)* | `app/interactions/publish_post_interaction.rb` | Business logic for custom actions — see [Behavior › Interaction](/reference/behavior/interactions) |
+| [Definition](./definition) | `app/definitions/post_definition.rb` | UI: which fields, how they render, what actions exist |
+| Policy | `app/policies/post_policy.rb` | Authorization: see [Behavior › Policy](/reference/behavior/policies) |
+| Controller | `app/controllers/posts_controller.rb` | Request handling: see [Behavior › Controller](/reference/behavior/controllers) |
+| Interaction *(optional)* | `app/interactions/publish_post_interaction.rb` | Business logic for custom actions, see [Behavior › Interaction](/reference/behavior/interactions) |
 
 ## How a resource is born
 
@@ -22,7 +22,7 @@ That single scaffold gives you a working model + migration + controller + policy
 
 ## Auto-detection is the default
 
-Plutonium reads your model and renders every attribute automatically — type, label, form widget, display formatter, table column. You only declare overrides:
+Plutonium reads your model and renders every attribute automatically: type, label, form widget, display formatter, table column. You only declare overrides:
 
 ```ruby
 class PostDefinition < Plutonium::Resource::Definition
@@ -33,18 +33,20 @@ end
 ```
 
 ::: warning Don't declare for completeness
-A `field :title` with no options that matches what Plutonium would auto-detect is **dead code** — it does nothing and clutters the file. Declare ONLY when you need a different type, an option, a `condition:`, a block, or a custom component.
+A `field :title` with no options that matches what Plutonium would auto-detect is **dead code**; it does nothing and clutters the file. Declare ONLY when you need a different type, an option, a `condition:`, a block, or a custom component.
 :::
 
 ## Sub-pages
 
-- [Model](./model) — `Plutonium::Resource::Record`, `has_cents`, SGID, custom routing, labeling
-- [Definition](./definition) — fields, inputs, displays, columns, page chrome, metadata panel, index views
-- [Query](./query) — search, filters, scopes, sorting
-- [Actions](./actions) — custom actions, bulk actions, interaction integration
+- [Model](./model): `Plutonium::Resource::Record`, `has_cents`, SGID, custom routing, labeling
+- [Definition](./definition): fields, inputs, displays, columns, page chrome, metadata panel, index views
+- [Query](./query): search, filters, scopes, sorting
+- [Actions](./actions): custom actions, bulk actions, interaction integration
+- [Positioning & drag-to-reorder](./positioning): `positioned_on`, `position_on`, the drag grip, `reposition?`
+- [CSV Export](./export): streamed export, opt-in through the policy
 
 ## Related
 
-- [Guides › Adding Resources](/guides/adding-resources) — task recipe
-- [App › Generators](/reference/app/generators) — `pu:res:scaffold` / `pu:res:conn` reference
-- [Tenancy](/reference/tenancy/) — multi-tenant scoping
+- [Guides › Adding Resources](/guides/adding-resources): task recipe
+- [App › Generators](/reference/app/generators): `pu:res:scaffold` / `pu:res:conn` reference
+- [Tenancy](/reference/tenancy/): multi-tenant scoping

data/docs/reference/resource/model.md

@@ -11,25 +11,25 @@ All resource models inherit from `ResourceRecord` (created by `pu:core:install`)
 class Post < ResourceRecord
 end
 
-# Inside a feature package — uses the package's ResourceRecord
+# 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.
+`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) |
+| `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) |
+| `AssociatedWith` | Multi-tenant scoping: `Model.associated_with(entity)` | [Tenancy](/reference/tenancy/entity-scoping) |
 
 ## Section layout
 
@@ -89,7 +89,7 @@ end
 
 ## `has_cents`
 
-Stores monetary values as integer cents and exposes a decimal virtual accessor. Use this for money — never store decimals directly.
+Stores monetary values as integer cents and exposes a decimal virtual accessor. Use this for money; never store decimals directly.
 
 ```ruby
 class Product < ResourceRecord
@@ -112,16 +112,16 @@ product.price = 10.999
 product.price_cents  # => 1099
 ```
 
-**Currency symbol (`unit:`)** — a `String` is used verbatim (`unit: "£"`); a `Symbol`
+**Currency symbol (`unit:`).** A `String` is used verbatim (`unit: "£"`); a `Symbol`
 names a method read off the record for per-row currencies (`unit: :currency_symbol`
 → `record.currency_symbol`); `false` explicitly renders no symbol. This unit is picked
-up automatically anywhere the value renders as currency — show pages, tables, and
-grid/kanban cards — so you configure it once on the model. A per-display
+up automatically anywhere the value renders as currency (show pages, tables, and
+grid/kanban cards), so you configure it once on the model. A per-display
 `display :price, as: :currency, unit: …` overrides it for that display.
 
 A `has_cents` field also **infers the currency input** on forms: a bare `input :price`
 renders the [currency input](../ui/forms#currency-fields) (number field + unit prefix),
-no `as: :currency` needed — matching the display side.
+no `as: :currency` needed, matching the display side.
 
 Resolution is `display unit → has_cents unit → config default`, where `nil` means
 "not set, keep looking" and `false` means "stop, no symbol". When nothing is set, it
@@ -148,7 +148,7 @@ end
 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).
+Generators sometimes emit the `_cents` name in the policy; fix by hand (and verify `has_cents` is declared on the model).
 :::
 
 ### Options
@@ -176,7 +176,7 @@ 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.
+The framework adds an `after_validation` hook that copies `:invalid` from `price_cents` → `price` automatically, no manual wiring needed.
 
 ### Introspection
 
@@ -196,7 +196,7 @@ post.to_param  # => "1"      (numeric id)
 # URL: /posts/1
 ```
 
-### `path_parameter` — use a stable column
+### `path_parameter`: use a stable column
 
 Use a column that's unique and human-readable instead of the numeric id:
 
@@ -212,9 +212,9 @@ user.to_param  # => "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.
+`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
+### `dynamic_path_parameter`: SEO-friendly id + slug
 
 Combines the id (for stable lookup) with a slug from another column (for SEO):
 
@@ -230,7 +230,7 @@ article.to_param  # => "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.
+The slug is informational: only the id portion is used for lookup, so changing the title doesn't break old URLs.
 
 ## Labeling
 
@@ -262,7 +262,7 @@ 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.
+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`)
 
@@ -292,7 +292,7 @@ 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).
+These are what `secure_association_tag` uses in forms; see [UI › Forms](/reference/ui/forms).
 
 ## Field introspection
 
@@ -335,11 +335,11 @@ Resolution order, association path requirements, three model shapes, and custom
 
 ## 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:
+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.
+- **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
 
@@ -369,6 +369,6 @@ 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
+- [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