plutonium 0.60.5 → 0.61.0

data/docs/reference/kanban/dsl.md

@@ -0,0 +1,293 @@
+# Kanban DSL Reference
+
+::: warning Experimental
+Kanban boards are experimental — the DSL and behavior may change in a future release.
+:::
+
+Complete reference for the `kanban do…end` block declared inside a resource Definition.
+
+## Entry point
+
+```ruby
+class PostDefinition < ResourceDefinition
+  kanban do
+    # board-level options + column declarations
+  end
+end
+```
+
+Calling `kanban` automatically adds `:kanban` to `defined_index_views`. To set it as the default view:
+
+```ruby
+default_index_view :kanban
+```
+
+To make it the only view:
+
+```ruby
+index_views :kanban
+kanban do ... end
+```
+
+---
+
+## Board-level options
+
+### `per_column(n)`
+
+```ruby
+per_column 25
+```
+
+Maximum cards rendered per column. When the column total exceeds `n`, a `+N more` footer appears. Column actions with `on: :all` still operate against the full column set; `on: :visible` is capped to the rendered subset.
+
+Default: `nil` (unlimited).
+
+---
+
+### `position_on`
+
+Controls how card positions are persisted after a drag-and-drop. Three modes:
+
+#### Mode A — delegate to `Plutonium::Positioning` (default)
+
+```ruby
+# Default: uses :position attribute
+# (no explicit call needed if the model includes Plutonium::Positioning)
+
+# Custom attribute name:
+position_on :sort_order
+```
+
+Requires the model to:
+1. `include Plutonium::Positioning`
+2. Call `positioned_on :position, scope: :grouping_attribute`
+3. Have a `decimal` column for the position attribute — add it with the `t.position` migration helper (a tuned `decimal(16,8)`) — see [Positioning › Migration](/reference/kanban/positioning#migration)
+
+On drop, calls `record.reposition!(prev_record:, next_record:)` which computes the decimal midpoint and updates the record.
+
+#### Mode B — BYO block
+
+```ruby
+position_on :sort_order do |move|
+  # move is a Plutonium::Kanban::Positioning::Move value object:
+  #   move.record  — the dropped ActiveRecord record
+  #   move.column  — destination column key (Symbol)
+  #   move.prev    — record immediately before the insertion slot, or nil
+  #   move.next    — record immediately after the insertion slot, or nil
+  #   move.index   — 0-based insertion index within the destination column
+  move.record.update!(sort_order: compute_position(move.prev, move.next))
+end
+```
+
+The block is evaluated via `call` (not `instance_exec`) — it is a plain Ruby proc/lambda.
+
+Plutonium still orders column cards by `sort_order` (the first argument); your block is responsible only for persisting the new value.
+
+#### Mode C — disabled
+
+```ruby
+position_on false
+```
+
+No ordering is applied. Cards render in the relation's natural order. On drop, only `on_drop` fires (if set); the position attribute is never touched.
+
+---
+
+### `realtime(v = true)` {#realtime}
+
+```ruby
+realtime true
+```
+
+Enables ActionCable broadcasting after every successful move. After a drop, Plutonium pushes the refreshed column frames to all viewers subscribed to this board's stream.
+
+**Stream name format:**
+
+```
+["kanban", "<tenant_gid_or_global>", "<ResourceClass.name>"]
+```
+
+- Tenant-scoped portals use the entity's Global ID parameter as the second segment.
+- Portals without entity scoping use the literal string `"global"`.
+
+Two viewers share a stream only if they have the same resource class **and** the same scoped entity — cross-tenant leakage is impossible by construction.
+
+Requires `turbo-rails` + ActionCable (gems), a cable adapter in `config/cable.yml` (Redis/Solid Cable in multi-process production), ActionCable mounted at `/cable`, **and** an ActionCable client loaded in your app's JavaScript. Plutonium's bundle ships `@hotwired/turbo` only — without `@hotwired/turbo-rails` (or `@rails/actioncable`) in your pack, the `<turbo-cable-stream-source>` never connects and other viewers won't update. Server-side broadcasting works regardless; this is purely the client subscription. See the [guide's Realtime setup](/guides/kanban#setup-required-for-realtime-to-actually-update-other-viewers).
+
+Default: `false`.
+
+---
+
+### `lazy(v = true)`
+
+```ruby
+lazy false   # eager-load all columns on initial page request
+```
+
+When `true` (the default), each column is a Turbo Frame that loads its card list on demand (lazy loading). The frame loads when it enters the viewport.
+
+When `false`, all column frames are loaded in the initial page request (one HTTP request per column).
+
+---
+
+### `show_in(mode)` {#show_in}
+
+```ruby
+show_in :modal   # open a card's show page in a centered modal dialog
+show_in :page    # navigate the whole page to the show route
+```
+
+Overrides — **for this board** — where clicking a card opens the record's show page:
+
+- `:modal` — the card's show link targets the layout's `remote_modal` frame, so the show page renders in a **centered** dialog. (Show is always centered — deliberately not the definition's `modal_mode`, which styles `new`/`edit`.)
+- `:page` — the card's show link targets `_top`, navigating the whole page to the show route.
+
+When `show_in` is **not** set on the board, the board inherits the definition's [`show_in`](/reference/resource/definition#show_in) (which itself defaults to `:page`). So to open cards in a modal you can set it on the board, or once on the definition (which also covers the table and grid views).
+
+Either mode escapes the column's lazy turbo-frame — `:page` replaces the whole page, and the `remote_modal` frame lives in the layout (resolved document-wide), so it opens outside the column. No per-card configuration is needed; the show page detects the modal frame (`in_modal?`) and wraps its details in the centered modal chrome. From inside the modal, an expand icon (or ⌘/Ctrl-click on the card) opens the full page in a new tab.
+
+An unknown mode raises `ArgumentError`.
+
+---
+
+### `card_fields(**slots)`
+
+```ruby
+card_fields(
+  header: :title,
+  subheader: :assignee,
+  meta: [:due_date, :priority]
+)
+```
+
+Overrides the slot layout for every kanban card on this board, using the same slot names as `grid_fields` (`:image`, `:header`, `:subheader`, `:body`, `:meta`, `:footer`). The kanban card renderer resolves its slots as `card_fields || definition.grid_fields`, so a board-level `card_fields` takes precedence over the resource's `grid_fields`.
+
+When `card_fields` is not set, cards fall back to the resource definition's `grid_fields`. If neither is declared, the card renders the default header-only layout.
+
+---
+
+## Static columns
+
+Declare columns at class-load time:
+
+```ruby
+kanban do
+  column :todo,
+    label: "To Do",
+    color: :blue,
+    scope: -> { where(status: "todo") },
+    on_drop: ->(r) { r.update!(status: "todo") },
+    role: :backlog
+
+  column :done,
+    scope: -> { where(status: "done") },
+    on_drop: :mark_done!,
+    accepts: [:doing],
+    role: :done do
+    action :archive_all, interaction: ArchiveTasksInteraction, on: :all
+  end
+end
+```
+
+### Column options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `label:` | String | `key.to_s.titleize` | Column header label |
+| `color:` | Symbol or String | `nil` | Header color dot. Named colors: `:red`, `:orange`, `:amber`, `:yellow`, `:green`, `:blue`, `:purple`, `:pink`, `:gray`. Raw CSS string also accepted |
+| `scope:` | Symbol or Proc | `nil` | Relation filter for this column. **Symbol** → `relation.public_send(sym)` (named AR scope). **Proc** → 0-arg lambda called via `instance_exec` on the relation, e.g. `-> { where(status: "todo") }` |
+| `on_drop:` | Symbol or Proc | `nil` | Fired when a card is dropped into this column. **Symbol** → `record.public_send(sym)`. **Proc** → 1-arg lambda `->(record) { … }` where `self` inside the block is the view context (giving access to `current_user`, helpers, etc.). The callback may assign attributes in memory (`r.status = :done`) or call `update!` directly; if the record has unsaved changes after `on_drop` returns the controller saves it automatically. |
+| `role:` | `:backlog`, `:done` | `nil` | Applies a preset (see below) |
+| `collapsed:` | Boolean | `false` | Column starts collapsed (a thin strip with the label rotated). The Stimulus controller persists the toggled state to `localStorage` (key: `pu-kanban:<path>:<column-key>:collapsed`) so the user preference survives page reloads; this DSL value sets the server-rendered initial state only. |
+| `add:` | Boolean | `false` | Show a `+ Add` quick-add button |
+| `accepts:` | `true`, `false`, Array, or Proc | `true` | Drop policy. `true` accepts any source column. `false` rejects all drops (display-only column). An Array of column key symbols accepts only those sources. A 1-arg Proc `->(record) { … }` is evaluated **per-card on the server** at drop time (via `accepts_record?`) and returns a boolean — e.g. `->(task) { task.status == "doing" }`. The client-side drag hint treats a Proc column as permissive (`data-kanban-accepts="all"`) since the browser can't run the Proc; the server enforces it precisely on every move |
+| `locked:` | Boolean | `false` | Prevent dragging cards **out of** this column |
+| `wip:` | Integer | `nil` | WIP limit. Reject cross-column drops when `dest_count + 1 > wip`. Has no effect on same-column reordering |
+
+### Role presets
+
+| Role | Equivalent options |
+|------|--------------------|
+| `:backlog` | `add: true` |
+| `:done` | `color: :green, collapsed: true` |
+
+Explicitly passed options override the preset. Unknown role values raise `ArgumentError`.
+
+---
+
+## Dynamic columns
+
+Use `columns do…end` when the column list depends on the current request:
+
+```ruby
+kanban do
+  columns do
+    # `self` is the view context — current_user, params, and helpers all work.
+    current_user.visible_statuses.map do |status|
+      Plutonium::Kanban::Column.new(
+        :"status_#{status.id}",
+        label: status.name,
+        color: status.color_symbol,
+        scope: -> { where(status_id: status.id) },
+        on_drop: ->(r) { r.update!(status_id: status.id) }
+      )
+    end
+  end
+end
+```
+
+The block is evaluated at request time. You can mix static pre-declared columns with a dynamic block: if both are present, the `columns` block takes precedence (the board is considered dynamic).
+
+::: warning Column action registration for dynamic boards
+Column actions declared inside a `columns do…end` block **cannot be auto-registered** at class-load time. Register the interaction as a top-level definition `action` as well:
+
+```ruby
+class TaskDefinition < ResourceDefinition
+  action :archive_column_tasks, interaction: ArchiveTasksInteraction
+
+  kanban do
+    columns do
+      build_status_columns.each do |col|
+        col.action :archive_column_tasks, interaction: ArchiveTasksInteraction, on: :all
+        col
+      end
+    end
+  end
+end
+```
+:::
+
+---
+
+## Column actions
+
+Declare actions inside a column `do…end` block:
+
+```ruby
+column :done,
+  scope: -> { where(status: "done") },
+  on_drop: :mark_done! do
+
+  action :archive_all,
+    interaction: ArchiveTasksInteraction,
+    on: :all,
+    label: "Archive all",
+    icon: Phlex::TablerIcons::Archive,
+    confirmation: "Archive all done tasks?"
+end
+```
+
+### Action options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `interaction:` | Class | Yes | An interaction class. Must have `attribute :resources` (plural) — it runs as a bulk action |
+| `on:` | `:all` or `:visible` | No (default `:all`) | `:all` passes IDs of all column cards (ignoring `per_column`). `:visible` passes only the rendered, capped subset |
+| `label:` | String | No | Button text. Defaults to `key.to_s.humanize` |
+| `icon:` | Phlex icon class | No | Icon rendered before the label |
+| `confirmation:` | String | No | Browser `confirm()` message shown before the action fires |
+
+Column actions are rendered as small buttons in the column header. They open the standard interactive-action modal with full authorization, form rendering, and success/failure handling.
+
+**Auto-registration:** For static columns, the `kanban` DSL automatically calls `action(key, interaction:, …)` at definition class-load time so the bulk route resolves. For dynamic `columns do…end` boards you must register the interaction manually (see warning above).

data/docs/reference/kanban/index.md

@@ -0,0 +1,40 @@
+# Kanban Reference
+
+Reference documentation for the Plutonium kanban board feature.
+
+## In this section
+
+| Page | What it covers |
+|------|---------------|
+| [DSL](/reference/kanban/dsl) | Complete `kanban do…end` DSL — board options, columns, column actions, static vs. dynamic, lazy loading, realtime |
+| [Positioning](/reference/kanban/positioning) | `Plutonium::Positioning` concern, `positioned_on`, `position_on` modes, `reposition!`, rebalancing |
+| [Authorization](/reference/kanban/authorization) | `kanban_move?` policy predicate, read-only fallback, separating move rights from edit rights |
+
+## Quick start
+
+```ruby
+# app/definitions/task_definition.rb
+class TaskDefinition < ResourceDefinition
+  kanban do
+    per_column 25
+
+    column :todo,
+      scope:   -> { where(status: "todo") },
+      on_drop: ->(r) { r.update!(status: "todo") },
+      role: :backlog
+
+    column :doing,
+      scope:   -> { where(status: "doing") },
+      on_drop: ->(r) { r.update!(status: "doing") },
+      wip: 3
+
+    column :done,
+      scope:   -> { where(status: "done") },
+      on_drop: :mark_done!,
+      accepts: [:doing],
+      role: :done
+  end
+end
+```
+
+See the [Kanban guide](/guides/kanban) for a full walkthrough including model setup and migrations.

data/docs/reference/kanban/positioning.md

@@ -0,0 +1,162 @@
+# Kanban Positioning
+
+Plutonium uses **decimal fractional positioning** for kanban card ordering. A drop writes a single decimal position (the midpoint between its neighbors), so the common case touches exactly one row — no bulk renumbering. The one exception is rare **rebalancing**: when the same slot has been subdivided ~20 times and the gap between two neighbors shrinks below `1e-6`, Plutonium renumbers that one scope group back to clean integers before inserting (see [Gap exhaustion](#rebalancing)).
+
+## `Plutonium::Positioning` concern
+
+Include this concern in any model you want to position:
+
+```ruby
+class Task < ApplicationRecord
+  include Plutonium::Positioning
+
+  positioned_on :position, scope: :status
+end
+```
+
+### `positioned_on(column = :position, scope: nil)`
+
+Configures positional ordering for the model.
+
+| Argument | Description |
+|----------|-------------|
+| `column` | The `decimal` database column that stores positions. Default: `:position` |
+| `scope:` | Group positions by this attribute. Records with different scope values are ordered independently. `nil` = single global ordering across all rows |
+
+After calling `positioned_on`, the model gets:
+- A `before_create` callback that assigns the next position in the scope group (appends to end).
+- A `reposition!(prev_record:, next_record:)` instance method.
+- A `backfill_positions!(order: :created_at)` class method.
+
+### Migration
+
+Use the **`t.position`** helper — it adds a `decimal` column already tuned for fractional ordering (`precision: 16, scale: 8`), so you can't get the scale wrong:
+
+```ruby
+create_table :tasks do |t|
+  t.string :status, null: false, default: "todo"
+  t.position                 # decimal :position, precision: 16, scale: 8
+  t.timestamps
+end
+add_index :tasks, [:status, :position]   # match your scope attribute
+```
+
+Adding the column to an existing table works the same way in a `change_table` block:
+
+```ruby
+class AddPositionToTasks < ActiveRecord::Migration[8.1]
+  def change
+    change_table(:tasks) { |t| t.position }
+    add_index :tasks, [:status, :position]
+  end
+end
+```
+
+`t.position` accepts a custom column name and any `column` options:
+
+```ruby
+t.position :sort_order               # custom name
+t.position :position, index: true    # also add a single-column index
+t.position :position, scale: 10      # override precision/scale
+```
+
+::: tip Why the helper picks `scale: 8`
+If you write the column by hand, give it at least **two more decimal places than `EPSILON` (`1e-6`)** — i.e. `scale: 8` or higher. Rebalancing triggers when a gap drops below `1e-6`, so a column that can store smaller values still has room to write the final midpoint cleanly. A `scale: 6` column has no headroom: the last subdivision before a rebalance can round to a neighbor and momentarily collide. `t.position` defaults to `scale: 8`, which is safe.
+:::
+
+---
+
+## `reposition!(prev_record:, next_record:)`
+
+Moves a record so it sits between `prev_record` and `next_record` in its scope group. Pass `nil` for an end to prepend or append.
+
+```ruby
+task.reposition!(prev_record: card_a, next_record: card_b)
+task.reposition!(prev_record: nil, next_record: first_card)  # prepend
+task.reposition!(prev_record: last_card, next_record: nil)   # append
+```
+
+**Arithmetic:**
+- Both nil → `0.0` (first item in empty group)
+- Only `prev_record` → `prev.position + 1` (append)
+- Only `next_record` → `next.position - 1` (prepend)
+- Both present → `(prev.position + next.position) / 2.0` (midpoint)
+
+### Gap exhaustion (rebalancing) {#rebalancing}
+
+Each midpoint insert into the *same* slot halves the gap (`1.0 → 0.5 → 0.25 → …`), so after roughly 20 consecutive insertions the gap drops below `EPSILON` (`1e-6`). At that point `reposition!` rebalances **only that scope group** — renumbering every row in the group to fresh integers (`1.0, 2.0, 3.0, …`) in current-position order, inside a transaction — then reloads the two neighbors and writes the new midpoint. Other scope groups are untouched. End moves (a `nil` neighbor) never rebalance: they always have integer room via `prev ± 1`.
+
+---
+
+## `backfill_positions!(order: :created_at)`
+
+Numbers all existing rows per scope group as `1.0, 2.0, 3.0, …` sorted by `order`. Safe to run on an empty table. Use this in a migration or seed task to initialize positions on existing data:
+
+```ruby
+# In a migration after adding the column:
+Task.backfill_positions!(order: :created_at)
+```
+
+---
+
+## `position_on` DSL modes
+
+The `position_on` call inside `kanban do…end` controls how Plutonium persists positions after a drag-and-drop. Three modes are available:
+
+### Mode A — delegate (default)
+
+```ruby
+kanban do
+  # Implicit: position_on :position
+  # Explicit with custom attribute:
+  position_on :sort_order
+end
+```
+
+On drop, Plutonium calls `record.reposition!(prev_record:, next_record:)`. Requires the model to include `Plutonium::Positioning` and call `positioned_on`.
+
+### Mode B — BYO block
+
+```ruby
+kanban do
+  position_on :sort_order do |move|
+    # move.record — the dropped record
+    # move.column — destination column key (Symbol)
+    # move.prev   — record immediately before the slot (or nil)
+    # move.next   — record immediately after the slot (or nil)
+    # move.index  — 0-based insertion index within the destination column
+    move.record.update!(sort_order: my_position(move.prev, move.next))
+  end
+end
+```
+
+Plutonium orders the column by `sort_order` for display; your block is responsible only for persisting the new value. The block is called with a single `Plutonium::Kanban::Positioning::Move` argument — it is NOT `instance_exec`'d, so `self` is the proc's original binding.
+
+### Mode C — disabled
+
+```ruby
+kanban do
+  position_on false
+end
+```
+
+No ordering is applied (relation is returned unchanged). On drop, `on_drop` still fires; the position attribute is never touched. Cards render in the relation's default order.
+
+---
+
+## Pure math helpers
+
+Available as module-level methods without an AR instance:
+
+```ruby
+Plutonium::Positioning.position_between(1.0, 3.0)    # => 2.0
+Plutonium::Positioning.position_between(nil, 5.0)    # => 4.0  (prepend)
+Plutonium::Positioning.position_between(5.0, nil)    # => 6.0  (append)
+Plutonium::Positioning.position_between(nil, nil)    # => 0.0  (first item)
+
+Plutonium::Positioning.gap_exhausted?(1.0, 1.0)      # => true
+Plutonium::Positioning.gap_exhausted?(1.0, 3.0)      # => false
+Plutonium::Positioning.gap_exhausted?(nil, 5.0)      # => false
+```
+
+`EPSILON = 1e-6` is the minimum gap before `gap_exhausted?` returns `true`.

data/docs/reference/resource/definition.md

@@ -681,6 +681,22 @@ end
 
 `modal:` is the default for framework `:new`/`:edit` *and* every interactive action on this definition. Per-action `modal:` / `size:` overrides win — see [Actions](./actions).
 
+### `show_in` {#show_in}
+
+```ruby
+class PostDefinition < ResourceDefinition
+  show_in :modal   # open the show page in a centered modal from table & grid links
+  # show_in :page  # (default) full-page navigation to the show route
+end
+```
+
+Controls how the **show page** opens when a record is clicked in the table or grid (and serves as the default for a [kanban board](/reference/kanban/dsl#show_in), which can override it per-board):
+
+- `:page` (default) — full-page navigation to the show route.
+- `:modal` — the show page opens in a **centered** dialog. This is deliberately independent of `modal:`/`modal_mode` above (which styles `:new`/`:edit`) — show is always centered, never a slideover. From inside the modal an expand icon opens the full page in a new tab; ⌘/Ctrl-click (or middle-click) on the row/card does the same directly.
+
+An unknown mode raises `ArgumentError`.
+
 ## Metadata panel (show page)
 
 A right-side aside on the show page rendering label/value rows. Keeps the main card focused on substance; chrome (timestamps, ownership, system flags) lives in the aside.

data/docs/reference/ui/forms.md

@@ -175,6 +175,42 @@ render field(:avatar).wrapped do |f|
 end
 ```
 
+### Password & secret fields {#password-fields}
+
+`password_tag` renders a masking input that **never emits the stored value** into the DOM. A stored secret renders a fixed sentinel (masking both the value and its length); on submit:
+
+| field state | result |
+|---|---|
+| untouched (sentinel) | kept — the stored secret is left unchanged |
+| edited to a new value, then failed re-render | comes back **blank + `required`** so the user re-types it (a submitted secret is never echoed back) |
+| cleared, then failed re-render | comes back blank, **not** `required` — the clear may be intentional, so it's allowed to stand |
+| emptied | explicit clear (clear-by-blank) — the `required` guard only prevents an *accidental* blank submit |
+| typed | set as the new value |
+
+The sentinel is guarded client-side by the `password-sentinel` Stimulus controller: the first edit (a keystroke, paste, or **backspace**) wipes the whole field, so a partial edit can't corrupt the sentinel into a literal new password. New records and interaction forms (set-password, reset-password) render an honest empty field.
+
+**Automatic detection.** A field is masked automatically when its name:
+
+- equals `password`, `token`, or `salt`;
+- starts with `encrypted_`;
+- ends with `_password`, `_digest`, `_hash`, `_token`, `_key`, or `_salt`;
+- contains `secret`.
+
+This is a naming convenience, **not** a security guarantee — tune it per field:
+
+```ruby
+# Opt OUT: render the value as a normal, readable text input
+field :api_token,   as: :string      # a token the admin needs to copy
+field :content_hash, as: :string     # a checksum, not a secret
+field :public_key,  as: :string      # *_key matches, but a public key is not secret
+
+# Opt IN: mask a secret the heuristic still misses (e.g. no telltale name)
+field :recovery_phrase, as: :password
+```
+
+> [!WARNING]
+> The heuristic is name-based and best-effort. A secret column with an unconventional name (e.g. `recovery_phrase`, `pin`) still renders its value into the page unless you set `as: :password`. Audit secret-bearing columns explicitly.
+
 ### Wrapped vs unwrapped
 
 - `wrapped` — includes label, hint, and error rendering. Use for normal form fields.

data/docs/reference/ui/pages.md

@@ -150,6 +150,8 @@ end
 
 Show pages with `permitted_associations` (see [Behavior › Policy](/reference/behavior/policies#association-permissions)) render a tablist: **Details** tab first, then one tab per association. The active tab is reflected in the URL hash (`#products`, `#refund-requests`) so the page deep-links and the active state survives reload / back navigation. Tab rows scroll horizontally on narrow viewports — they don't wrap.
 
+If the policy permits **no fields**, the empty Details tab is dropped and the first association tab leads instead.
+
 ## Portal-specific overrides
 
 Each portal can override page classes independently. The portal definition inherits from the base definition, and its nested classes inherit from the base's nested classes: