plutonium 0.67.0 → 0.69.0

data/config/locales/en/async.yml

@@ -7,8 +7,11 @@ en:
     async:
       run:
         label: "%{name} #%{id}"
+        interaction: "Action"
+        progress: "%{done} / %{total}"
         target_type: "Target type"
         enqueue_failed: "could not be enqueued for execution"
+        reject_outside_pre_check: "%{run_class}#reject is only available inside pre_check"
       executor:
         target_missing: "Target %{id} is no longer available"
         target_unauthorized: "Target %{id} is no longer permitted by %{action}"
@@ -17,6 +20,12 @@ en:
           one: "stopped at the first target failure (%{policy} policy); %{count} target was not attempted"
           other: "stopped at the first target failure (%{policy} policy); %{count} targets were not attempted"
         partial_batch_refused: "%{unresolved} of %{total} targets could not be resolved; a %{policy} run does not apply a partial batch"
+        pre_check_arity:
+          targeted: "%{run_class}#pre_check must take the records: define pre_check(records) on a run with perform_on"
+          opaque: "%{run_class}#pre_check must take no arguments: define pre_check on a run with perform"
+        rejections_truncated:
+          one: "and %{count} more problem was found"
+          other: "and %{count} more problems were found"
       context:
         initiator_missing: "run %{run} has no initiator (%{type}#%{id} no longer exists)"
         tenant_missing: "run %{run} was scoped to %{type}#%{id}, which no longer exists; refusing to resolve targets without a tenant"
@@ -25,10 +34,11 @@ en:
         targets: "%{done} of %{total} targets (%{percent}%)"
         working: "Working…"
         no_total: "No progress total was recorded"
-        failures: "Failures"
         error_count:
           one: "%{count} error"
           other: "%{count} errors"
         target_failure: "#%{target_id}: %{message}"
+        rejected: "Nothing was processed"
       banner:
         view_progress: "View progress"
+        view_run: "View run"

data/config/locales/en/dashboard.yml

@@ -23,3 +23,4 @@ en:
         increase: "Up %{change}"
         decrease: "Down %{change}"
         unchanged: "No change"
+        points: "%{change} pts"

data/config/locales/en/ui.yml

@@ -94,6 +94,9 @@ en:
           delete: "Delete"
         rating:
           clear: "Clear"
+        association_choices:
+          none: "None"
+          empty: "No options available"
         binary:
           replace_hint: "Stored: %{size}. Choose a file to replace it."
       display:

data/docs/reference/behavior/async-interactions.md

@@ -26,6 +26,8 @@ Plutonium.configure do |config|
   config.async_interactions.enabled = true
   config.async_interactions.queue = :default        # ActiveJob queue for run jobs
   config.async_interactions.stall_after = 1.hour     # see Stalled runs, below
+  config.async_interactions.max_rejections = 100     # pre_check problems stored per run
+  config.async_interactions.recent_runs_window = 10.minutes  # finished runs stay in your banner this long
 end
 ```
 
@@ -123,6 +125,58 @@ Validating means staging first, since Shrine validates an assigned cached file,
 
 Where no `backend:` is declared: `config.async_interactions.attachment_backend`, then `config.attachment_backend`, then auto-detection (active_shrine loaded → Shrine, else ActiveStorage). Same layering wizards use.
 
+### Checking input before processing
+
+Validations on the interaction run in the request, so they suit cheap checks (an uploader's size and type rules already fail the form there). A check too slow for a request, like reading every row of a large file, goes in the run's `pre_check`. It runs in the job, before any work, and refuses the input with `reject`:
+
+```ruby
+require "csv"
+
+class ImportTasks < ResourceInteraction
+  attribute :import_file
+  input :import_file, as: :file
+
+  async do
+    def pre_check
+      each_row do |row, line|
+        reject "line #{line}: title is missing" if row["title"].blank?
+      end
+    rescue CSV::MalformedCSVError => e
+      reject "the file is not valid CSV: #{e.message}"
+    end
+
+    # One transaction: an opaque run restarts from scratch after a reap, so a
+    # partial import would otherwise be imported twice.
+    def perform
+      Task.transaction { each_row { |row, _line| Task.create!(title: row["title"]) } }
+    end
+
+    private
+
+    # Read whole, as UTF-8 without Excel's byte-order mark: the stored file
+    # comes back as binary, and a BOM would become part of the first header.
+    def each_row
+      text = attachment(:import_file).download.force_encoding(Encoding::UTF_8).delete_prefix("\uFEFF")
+      CSV.parse(text, headers: true).each.with_index(2) do |row, line|
+        yield row, line unless row.fields.all?(&:blank?)
+      end
+    end
+  end
+end
+```
+
+Rows are numbered from 2 so a message matches the line a spreadsheet shows (the header is line 1), and blank lines are skipped without shifting the numbers after them. The dummy app's `ImportTasksInteraction` is the full version, with a column check, an empty-file check and status validation.
+
+- `reject` records a problem and returns, so one pass reports every bad row. It does not stop the check: `return` explicitly where nothing after it would make sense, such as a missing column.
+- If anything was rejected, the run ends `failed` with `outcome == "rejected"`, the problems listed on its progress page, and `perform` / `perform_on` never runs. The page shows a warning "Rejected" badge and "Nothing was processed". On a `:continue` run, targets that had gone missing or lost permission are recorded before the check runs, so they still appear in the list (and count toward `progress_done`) even though nothing was performed.
+- A run with `perform_on` declares `pre_check(records)` and receives the resolved, authorized records the loop is about to process. A `pre_check` with the wrong arity fails the run with a message naming the signature it expects.
+- An exception raised inside `pre_check` fails the run the ordinary way (`outcome == "failed"`): the check broke, the input was not judged.
+- `reject` called outside `pre_check` raises.
+- Only the first `config.async_interactions.max_rejections` problems (default 100) are stored, followed by one "and N more problems were found" entry.
+- The check runs again when a stalled run is resumed, so it must only read. An opaque run always re-checks. A resumed targeted run checks the records it has left, unless an earlier pass already applied a target (that pass's check passed, so it is not repeated).
+- A targeted check receives the records as loaded when the run resolved its targets. `perform_on` gets each record re-read just before it runs, so a verdict based on record state can be stale by then; re-check anything that must hold at the moment of the work inside `perform_on`.
+- A long check must call `heartbeat!` (see [Long work must say it is alive](#long-work-must-say-it-is-alive)).
+
 ### Sharing one run across interactions
 
 Pass a class instead of a block when several interactions do the same kind of work:
@@ -175,7 +229,9 @@ run.state    # "completed"
 run.outcome  # "completed_with_errors"   (state == "completed" && errors_log.any?)
 ```
 
-The progress page, the table's `outcome` column, and the running banner all render `outcome`, never bare `state`.
+A run whose `pre_check` rejected its input reads `outcome == "rejected"` (its `state` is `"failed"`, and nothing was processed). A run that failed while working reads `"failed"`.
+
+The progress page, the table's `outcome` column, and the running banner's entries for finished runs render `outcome`, never bare `state`.
 
 ## Registering the Run resource
 
@@ -207,17 +263,18 @@ A registered run resource gets, for free:
 
 - **A progress page.** The show page IS the progress page. It self-refreshes via polling (not ActionCable) while `state` is `pending`/`running`, and stops carrying the poll once the run settles, so a finished run is a static page, not a background request per viewer.
 - **A self-refreshing index.** The runs index polls on the same terms as the progress page: one frame around the whole collection, armed only while some run is still working, disarmed the moment none is. One request per interval regardless of page size, and it re-fetches the URL you are on, so filters, sort and page survive the refresh. A frame per row is not an option: `turbo-frame` is not in the content model of `tr`, so the parser hoists it out of the table before Turbo sees it.
-- **A running banner.** Any OTHER resource's index page lists runs currently in progress against it, above the collection, so a user who dispatched a bulk action and navigated away can find it again. Scoped through the same `authorized_resource_scope` every cross-resource read goes through, so a run in another tenant can never surface. If a resource_class is registered in a portal that never registered `Run`, the banner is skipped there instead of raising while trying to build a link to a route that doesn't exist.
+- **A running banner.** Any OTHER resource's index page lists runs currently in progress against it, above the collection, so a user who dispatched a bulk action and navigated away can find it again. It also lists the viewer's own runs that finished within `config.async_interactions.recent_runs_window` (default 10 minutes, newest first, at most 5), with their outcome and a "View run" link. A dispatch sends the user back to this index, and a short run, or one its `pre_check` rejected, has often finished before the page renders. Scoped through the same `authorized_resource_scope` every cross-resource read goes through, so a run in another tenant can never surface. If a resource_class is registered in a portal that never registered `Run`, the banner is skipped there instead of raising while trying to build a link to a route that doesn't exist.
 - **Tenant scoping.** A run's `associated_with` scope filters on the tenant it was dispatched in (recorded on the row), not on walking the object graph, since the two polymorphic tenant columns make the generic scope unusable.
+- **Runs named by their interaction.** A run declared with an `async` block is titled by its interaction's label ("Archive all (async) #19"), from `presents label:` or, without one, the class name minus its `Interaction` suffix. A standalone run class passed to `async` can be shared by several interactions, so it is named after its own class. Only `presents label:` reaches the run: a `label:` on the `action` declaration, or a `plutonium.actions.<model>.<action>` translation, renames the button but not the runs it starts, so put the label on the interaction when both should match.
 - **A humanized target label.** `run.target_label` reads the target class through `model_name.human` ("Post", not "Blogging::Post"), falling back to the raw string if that class has since been renamed or removed.
 
 The progress page, mid-run:
 
-![A run's progress page showing a Running badge, a progress bar at 27 of 50 targets, and the run's type, target type, initiator and timestamps](/images/reference/async-progress-page.png)
+![A run's progress page showing a Running badge, a progress bar at 27 of 50 targets, and the run's action, target type, initiator and timestamps](/images/reference/async-progress-page.png)
 
 And the banner it leaves on the target resource's index while it is still going:
 
-![A Task index with a banner above the collection reading "Archive Tasks Async Interaction Run #19 Running", with a View progress link](/images/reference/async-running-banner.png)
+![A Task index with a banner above the collection reading "Archive all (async) #19 Running", with a View progress link](/images/reference/async-running-banner.png)
 
 ## Stalled runs and ReapJob
 
@@ -255,7 +312,7 @@ What bounds that is `lock_version`. Both the reaper's resume and the executor's
 
 `stall_after` is a **silence** threshold, not a runtime limit. Every write the executor makes refreshes the clock, so a targeted run with quick targets heartbeats once per target for free. Two shapes get nothing, and both are exactly the "long-running task" case:
 
-- **Opaque work.** Between the claim and `finish!` the executor writes nothing, because there is nothing to count. A `perform` that outlives `stall_after` is reaped mid-flight and, having no `handled_target_ids` to resume from, re-runs **from scratch**.
+- **Opaque work, and any `pre_check`.** Between the claim and `finish!` the executor writes nothing, because there is nothing to count. A `perform` that outlives `stall_after` is reaped mid-flight and, having no `handled_target_ids` to resume from, re-runs **from scratch**.
 - **A single `perform_on`** that outlives `stall_after` on its own.
 
 Call `heartbeat!` from inside such work:

data/docs/reference/dashboard/dsl.md

@@ -30,6 +30,49 @@ Default reload interval for every lazy card. `nil` (the default) disables it.
 
 Page width, one of `:sm`, `:md`, `:lg`, `:xl`, `:full`. Default `:full`.
 
+### filter(key, choices: nil, scopes: nil, default: nil, label: nil)
+
+A page-level control every card reads, such as a period or a region.
+
+```ruby
+filter :period, choices: {"7" => "Last 7 days", "30" => "Last 30 days", "90" => "Last 90 days"}, default: "30"
+
+metric(:orders) { orders.where(created_at: filter_value(:period).to_i.days.ago..).count }
+```
+
+- `choices:` maps each value to its label (a string or a lazy `t` proc), in display order. `default:` must be one of the values and is the first when omitted.
+- The key cannot be one the card route or `url_for` uses (`card`, `format`, `anchor`, `host`, `use_route`, ...), which raises when declared, or a path segment of the dashboard's route (the entity param on a path-scoped portal, a `(:locale)` scope), which raises on the request.
+- The value comes from the query string under the filter's key. A value that is not one of the choices reads as the default.
+- Every lazy card's frame URL carries every filter's value, so a card's own request reads what the page read.
+- The page renders each filter as a segmented row of links above the cards, so a choice is a URL that survives a reload and can be shared. Other query parameters on the page are kept.
+- A card's `href:` is not rewritten with the filter values. Use a scope filter (below) to link a card to the matching list.
+
+#### Scope filters
+
+`scopes:` takes a resource instead of `choices:`. The choices are "All" plus the scopes the resource's definition declares, labelled and gated (`condition:`) the way the index's scope pills are. The default is `default:`, else the definition's `default_scope`, else "All". A default whose `condition:` hides it from the current user reads as "All" for that user.
+
+```ruby
+filter :status, scopes: Post
+
+metric(:posts, href: -> { filtered_url(Post) }) { filtered(Post).count }
+chart(:by_author) { filtered(Post).group(:author_name).count }
+```
+
+- `filtered(Post)` is `authorized_resource_scope(Post)` with the chosen scope applied through the definition's own scope, the same code the index runs, so the card's number matches the list.
+- `filtered_url(Post)` is the Post index on that scope (`q[scope]=...`). With "All" chosen and a `default_scope` on the definition, it sends an explicit blank scope so the index shows everything.
+- Without a scope filter for the resource, `filtered` is the authorized scope as is and `filtered_url` the plain index.
+- A scope's block runs against the dashboard's controller. `current_user`, `current_scoped_entity` and the portal's helpers work there; resource-controller helpers such as `current_parent` do not.
+- One scope filter per resource; a second raises when declared. A `default:` that is not one of the definition's scopes, or a definition scope named `:all` (the "All" choice's value), raises on the request.
+
+### link(key, href:, label: nil, icon: nil, condition: nil)
+
+A button in the toolbar above the cards, such as the dashboard's settings or a full report. `href:` and `condition:` take the same forms as a card's and are evaluated on the dashboard instance. A link whose `href:` resolves to nil is left out.
+
+```ruby
+link :settings, icon: Phlex::TablerIcons::Settings, href: -> { resource_url_for(Setting) },
+  condition: -> { allowed_to?(:update?, Setting) }
+```
+
 ## Cards
 
 ```ruby
@@ -70,8 +113,8 @@ The block returns a value or a hash.
 | Hash key | Meaning |
 |---|---|
 | `value` | The number or string. `nil` renders `plutonium.dashboard.metric.empty` |
-| `previous` | Computes `change` as a percentage from this value; a zero previous yields no percentage |
-| `change` | Numeric percentage points (`2.5` → `+2.5%`) or a string shown as-is |
+| `previous` | Computes `change` from this value: a percentage of it, or the difference with `change_unit: :points`. A zero previous yields no percentage (a neutral dash when there is a caption); with `:points` the difference still shows. The change is rounded to one decimal before its trend is read |
+| `change` | A number (`2.5` → `+2.5%`, or `+2.5 pts` with `change_unit: :points`) or a string shown as-is |
 | `trend` | `:up`, `:down`, `:flat`; inferred from the sign of `change` |
 | `change_label` | Caption after the change |
 
@@ -83,6 +126,7 @@ The block returns a value or a hash.
 | `prefix:` / `suffix:` | String | Wrapped around the formatted value |
 | `positive:` | `:up` (default), `:down` | Which direction is good; drives the change colour |
 | `change_label:` | String | Same as the hash key |
+| `change_unit:` | `:percent` (default), `:points` | How the change reads. Use `:points` for a value that is itself a percentage: 50% to 55.6% reads `+5.6 pts`, not `+11.2%` |
 
 ### chart
 
@@ -106,6 +150,11 @@ No kind-specific options. The block is `instance_exec`ed in `Plutonium::UI::Dash
 |---|---|
 | `authorize?` | Override to gate the page and every card. Default `true` |
 | `visible_cards` | Cards whose `condition:` passes |
+| `filter_value(key)` | The filter's value for this request, or its default |
+| `filter_values` | `{key => value}` for every filter; what each card's frame URL carries |
+| `filtered(resource_class)` | The authorized scope with the resource's scope filter applied |
+| `filtered_url(resource_class)` | The resource's index on the scope that filter has chosen |
+| `visible_links` | Toolbar links whose `condition:` passes |
 | `visible_card!(key)` | The card, or `Plutonium::Dashboard::UnknownCardError` (404) |
 | `refresh_for(card)` | The card's interval, else the dashboard's; `nil` for a card declared `refresh: false` |
 | `view_context` / `helpers` | The Rails view context |
@@ -117,7 +166,9 @@ No kind-specific options. The block is `instance_exec`ed in `Plutonium::UI::Dash
 |---|---|
 | `cards` | All declared cards, in order |
 | `find_card(key)` / `find_card!(key)` | Lookup by key |
+| `filters` / `find_filter(key)` | Declared filters |
+| `links` | Declared toolbar links |
 | `label`, `description`, `icon` | Resolved presentation |
 | `i18n_key`, `route_name` | `admin_portal/sales`, `sales` |
 
-Subclasses inherit the parent's cards and options by copy, so a portal-specific subclass can add cards without touching the parent.
+Subclasses inherit the parent's cards, filters, links and options by copy, so a portal-specific subclass can add cards without touching the parent.

data/docs/reference/generators/lite.md

@@ -36,19 +36,43 @@ another environment is left untouched.
 
 ## `pu:lite:maintenance`
 
-Installs `app/jobs/sqlite_maintenance_job.rb` and (when `solid_queue` is present)
-schedules it in `config/recurring.yml`.
+Installs `app/jobs/sqlite_maintenance_job.rb` and, when `solid_queue` is present,
+schedules it in `config/recurring.yml` along with SolidQueue's finished-job cleanup.
 
 ```bash
 rails g pu:lite:maintenance
-# custom schedule:
-rails g pu:lite:maintenance --schedule="every day at 4am"
+# custom schedules:
+rails g pu:lite:maintenance --schedule="every day at 4am" \
+  --clear-finished-schedule="every 30 minutes"
 ```
 
 The job runs `PRAGMA optimize` on every configured SQLite database and `VACUUM`
 only on databases without live 24/7 writers (`primary`, `errors`, `rails_pulse`
 by default; edit `VACUUM_DBS` in the generated job to suit your app).
 
+Even on those databases, `VACUUM` is skipped unless at least 10% of the file's
+pages are free (`VACUUM_MIN_FREE_RATIO`). The rewrite holds its exclusive lock for
+as long as it takes, which on a large `primary` can be long enough for requests to
+time out, and WAL reuses free pages anyway. In practice it runs after a bulk delete
+and is skipped (with a log line) the rest of the time.
+
+### Clearing finished SolidQueue jobs
+
+SolidQueue keeps finished jobs by default (`preserve_finished_jobs`) and never
+deletes them on its own, so the queue database grows without bound. The generator
+adds this task:
+
+```yaml
+clear_solid_queue_finished_jobs:
+  command: "SolidQueue::Job.clear_finished_in_batches(sleep_between_batches: 0.3)"
+  schedule: "every hour at minute 12"
+```
+
+It deletes jobs finished longer ago than `clear_finished_jobs_after` (one day by
+default) in batches, sleeping between them so the scheduler and workers keep their
+turn at the write lock. New Rails 8 apps already ship this task; the generator
+detects any existing `clear_finished_in_batches` entry and skips.
+
 **Why VACUUM only some databases?** SolidQueue, Solid Cache and Solid Cable write
 to their databases constantly. `VACUUM` takes a global *exclusive* lock for its
 whole duration, which stalls and errors those processes (e.g. SolidQueue process
@@ -61,5 +85,5 @@ Databases listed in the job that don't exist in `config/database.yml` are skippe
 at runtime, so the same job is safe regardless of which `pu:lite:*` generators you
 have run.
 
-If `solid_queue` is not installed, the job file is still created but not scheduled:
-add a `sqlite_maintenance` entry to whatever scheduler you use.
+If `solid_queue` is not installed, the job file is still created but nothing is
+scheduled: add a `sqlite_maintenance` entry to whatever scheduler you use.

data/docs/reference/i18n.md

@@ -145,7 +145,7 @@ end
 
 ## Derived labels
 
-Actions, scopes, filters, kanban columns and wizard steps default to a humanized version of their key. Each has a convention key that takes precedence over that fallback, and a `label:` option that takes precedence over both. For an action backed by an interaction, the interaction's explicit `presents label:` also counts as declared and wins over the convention; only the class-name default yields to it.
+Scopes, filters, kanban columns and wizard steps default to a humanized version of their key. An action backed by an interaction defaults to the interaction's class name without its `Interaction` suffix (`ArchivePostsInteraction` reads "Archive Posts"). Each has a convention key that takes precedence over that fallback, and a `label:` option that takes precedence over both. For an action backed by an interaction, the interaction's explicit `presents label:` also counts as declared and wins over the convention; only the class-name default yields to it.
 
 ```yaml
 en:

data/docs/reference/resource/definition.md

@@ -1011,6 +1011,8 @@ end
 
 Grid slots, `:image`, `:header`, `:subheader`, `:body`, `:meta`, `:footer`, are all optional. `:meta` accepts an array; the rest are single fields. Slots pointing at policy-blocked fields collapse silently.
 
+In the `:media` layout a record whose image does not resolve keeps the cover's space, with a neutral icon, so cards in a row stay one height. An image may be an attachment, an `http` or root-relative URL, or a `data:image/` URI.
+
 Only declare `index_views` explicitly to **disable** one (e.g. `index_views :grid` to drop the table view).
 
 ## Custom page classes

data/docs/reference/ui/forms.md

@@ -171,6 +171,8 @@ render field(:title).wrapped(class: "col-span-full") { |f| f.input_tag }
 | `rating_tag` | Star picker (radio buttons, no JS); an optional rating gets a Clear option |
 | `secure_association_tag` | Association with policy-checked options (inline `+` add, typeahead) |
 | `belongs_to_tag` / `has_many_tag` / `has_one_tag` | Association selects |
+| `association_checkboxes_tag` / `association_toggles_tag` | has_many / habtm as a list of checkboxes or switches (see [Association inputs](#association-inputs)) |
+| `association_radio_buttons_tag` | belongs_to / has_one as a radio group |
 | `key_value_store_tag` | Key/value pairs editor |
 
 ```ruby
@@ -333,6 +335,27 @@ input :author, label_method: :email
 For large target tables, write an explicit `search` block on the target resource definition; the fallback's leading-wildcard `LIKE` can't use a b-tree index.
 :::
 
+### List variants: checkboxes, toggles, radio buttons
+
+For a short list of options, render one control per record instead of a dropdown:
+
+```ruby
+input :tags, as: :association_checkboxes      # has_many / habtm
+input :tags, as: :association_toggles         # same, styled as switches
+input :category, as: :association_radio_buttons # belongs_to / has_one
+```
+
+The variants share the select's security: options come from the target's policy scope (or `choices:`), values are signed global ids, and submitted ids are checked against the authorized relation. Like the select, they always render the records the field holds now, even past `choice_limit:` or outside the viewer's scope, and accept them back on submit, so saving a form never drops a value the viewer did not touch. The inline `+` add button renders next to the list, and `add_action:`, `skip_authorization:`, `choices:` and `label_method:` work the same way.
+
+How they differ from the select:
+
+- **The list is capped like the select.** `choice_limit:` defaults to the select's cap. There is no typeahead, so a record past the cap can't be picked: use them for short lists, or raise `choice_limit:`.
+- **Unchecking everything clears the association.** The checkbox list submits a blank value, so an empty selection saves as no records.
+- **Optional radio groups get a "None" choice.** A radio group can't be cleared otherwise. Picking it clears the association. On a has_one, Active Record detaches the old record (or destroys it, with `dependent: :destroy`) as soon as the value is assigned, before the form validates, the same as picking a different record. It is left out when the field is required (a checked "None" would satisfy the browser's `required`), and `include_blank: false` drops it on an optional one. Its label is the field's `placeholder:` if set.
+- **The macro has to fit.** Checkboxes and toggles take a has_many or habtm; radio buttons take a belongs_to or has_one. A mismatch raises `ArgumentError` when the input is built, on render and on submit, as do a polymorphic association and `group_method:`.
+
+The list and its controls are themed by `association_checkboxes`, `association_toggles`, `association_radio_buttons` (the list), `association_checkbox`, `association_toggle`, `association_radio_button` (each control) and `association_choice_label`.
+
 ## Submit buttons
 
 Default `render_actions` produces the primary submit, plus an optional "Save and add another" / "Update and continue editing" secondary button.