plutonium 0.67.0 → 0.68.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7285167839fdb5e60e89da076028dc08b719ec60125cb61faaeb26cd151b9140
-  data.tar.gz: 87fe956c9ab3cdcc92e7083a3c5c965c144661f530e4ce0cb609d3b0a8adfb06
+  metadata.gz: a01423b0e39c2e985ec24ea8663cf53377817ff24814c95ce89270806f51b878
+  data.tar.gz: cbe95fbf1cd307e3b07cccf24cda7db7293dc15676c0ee288fe076d37102cb15
 SHA512:
-  metadata.gz: 3cdc13417311bd847b8b721ae46da0b59b12ecb1fafe95be087e556d71ac4d053d236169f2d48fa08edf831f9d49cdfdce27c3e28229b1bf5155dafdfb30cad5
-  data.tar.gz: 539932b5d8700edf4878fde1eb3c33ed0cd518d6ebafbbcf83df92de5ff098061dabcc1c1ca1a859cdfcf1e68a3f3e6ceaa55c44499b4132f132192db5cfcd18
+  metadata.gz: a2034d1af622ec4bfbc4c6ac00c46ed63f4a7ea6ed878ebc78b9666b109cf572dff20f60da0bc9f5e5adafdb992e76deb292c4ec08146684e3828732daf2ced7
+  data.tar.gz: '09f8b0ef419d7adf5df3057a271ed4659140e4308c4b7ea5ea5965554256e2c609314ecb6cd33893629773b9fab97f735b1e16872f08bb8784445cc80049a214'

data/.claude/skills/plutonium-dashboard/SKILL.md

@@ -77,9 +77,24 @@ end
 
 ## metric
 
-Return a value, or a hash: `value` (required), `previous` (computes % change), `change` (numeric percentage points or a verbatim string), `trend` (`:up`/`:down`/`:flat`, inferred), `change_label`.
+Return a value, or a hash: `value` (required), `previous` (computes the change), `change` (a number or a verbatim string), `trend` (`:up`/`:down`/`:flat`, inferred), `change_label`.
 
-Options: `format:` (`:number` default, `:currency`, `:percentage`, `:human`, or `->(v) { ... }`), `precision:`, `unit:` (currency symbol), `prefix:`, `suffix:`, `positive:` (`:up` default, `:down` when falling is good), `change_label:`.
+Options: `format:` (`:number` default, `:currency`, `:percentage`, `:human`, or `->(v) { ... }`), `precision:`, `unit:` (currency symbol), `prefix:`, `suffix:`, `positive:` (`:up` default, `:down` when falling is good), `change_label:`, `change_unit:` (`:percent` default; `:points` for a value that is itself a percentage, so 50% to 55.6% reads `+5.6 pts`).
+
+## Filters and toolbar links
+
+```ruby
+filter :period, choices: {"7" => "Last 7 days", "30" => "Last 30 days"}, default: "30"
+link :settings, icon: Phlex::TablerIcons::Settings, href: -> { resource_url_for(Setting) }
+
+metric(:orders) { orders.where(created_at: filter_value(:period).to_i.days.ago..).count }
+```
+
+- A filter's value comes from the query string; an unknown value reads as the default. Read it with `filter_value(:key)`, never `params[:key]` directly.
+- Don't name a filter after a card-route param or `url_for` option (`card`, `format`, `anchor`, `host`, `use_route`, ...) or a path segment of the dashboard's route (entity param, `locale`); it raises.
+- To filter by a resource's scopes, use `filter :status, scopes: Post` (choices = "All" + the definition's scopes) with `filtered(Post)` in card blocks and `href: -> { filtered_url(Post) }`. Do not hand-map filter values to `where` clauses or `q[scope]` URLs; `filtered` runs the definition's scope, so the count matches the index. One scope filter per resource. The scope block runs on the dashboard's controller, so it cannot call resource-controller helpers like `current_parent`.
+- Every lazy card's frame URL carries the filter values, so lazy cards see the page's choice. Do not hand-roll query forwarding or a custom `DashboardsController` for this.
+- Filters render as segmented links and links as buttons in a toolbar above the cards; neither needs a custom page class.
 
 ## chart
 

data/.claude/skills/plutonium-resource/SKILL.md

@@ -622,8 +622,9 @@ end
 
 - `input :tag_ids` uses Rails' collection-ids setter. Permit `:tag_ids`; values are plain ids. Simplest for a scoped checkbox list.
 - `input :tags, as: :secure_association` is the native picker. It sets input_param `tag_sgids`, scopes via `choices:` (or the target policy), and validates submitted SGIDs by decoded model-id.
+- `input :tags, as: :association_checkboxes` (or `:association_toggles`) is the same picker rendered as one checkbox/switch per record. `input :category, as: :association_radio_buttons` does the same for a belongs_to/has_one. They are capped by `choice_limit:` like the select but have no typeahead, so keep them to short lists.
 
-⚠️ Do **not** hand-roll `collection_checkboxes_tag(choices: [[label, record.to_sgid.to_s]])`. SGIDs are non-deterministic (`to_sgid` embeds a timestamp), the component re-derives `choices` at submit and intersects the posted value against the freshly-minted SGIDs, so it never matches and the value is dropped. Use stable ids in custom checkboxes, or `secure_association` (which validates by model-id).
+⚠️ Do **not** hand-roll `collection_checkboxes_tag(choices: [[label, record.to_sgid.to_s]])`. SGIDs are non-deterministic (`to_sgid` embeds a timestamp), the component re-derives `choices` at submit and intersects the posted value against the freshly-minted SGIDs, so it never matches and the value is dropped. Use stable ids in custom checkboxes, or `as: :association_checkboxes` (which validates by model-id).
 
 ## Conditional Rendering
 
@@ -1116,7 +1117,7 @@ Only declare `index_views` explicitly if you want to **disable** one (e.g. `inde
 | `grid_layout :media` | `:compact` (image left) or `:media` (image on top). |
 | `grid_columns 3` | Override responsive column count. |
 
-All grid slots are optional; slots pointing at unpermitted fields collapse silently.
+All grid slots are optional; slots pointing at unpermitted 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.
 
 ---
 

data/.claude/skills/plutonium-ui/SKILL.md

@@ -324,6 +324,8 @@ render field(:title).wrapped(class: "col-span-full") { |f| f.input_tag }
 | `uppy_tag` / `file_tag` | Uppy file upload |
 | `secure_association_tag` | Association with policy-checked options |
 | `belongs_to_tag` / `has_many_tag` / `has_one_tag` | Association selects |
+| `association_checkboxes_tag` / `association_toggles_tag` | has_many / habtm as checkboxes or switches (`as: :association_checkboxes` / `:association_toggles`); same policy scoping and SGID validation as the select, capped by `choice_limit:` like the select (selected records always render), no typeahead |
+| `association_radio_buttons_tag` | belongs_to / has_one as a radio group (`as: :association_radio_buttons`); optional associations get a "None" choice |
 | `key_value_store_tag` | Key/value pairs editor |
 | `currency_tag` | Money input (number field + unit prefix) |
 | `rich_text_tag` | Action Text editor (Trix, or Lexxy once the app installs it); default for `has_rich_text` |

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.68.0] - 2026-10-14
+
+### Bug Fixes
+
+- Send card links to the whole page ([#183](https://github.com/radioactive-labs/plutonium-core/issues/183))
+- Keep the grid card cover's space when a record has no image ([#184](https://github.com/radioactive-labs/plutonium-core/issues/184))
+
+### Features
+
+- Filters carried to card frames, toolbar links, point changes ([#182](https://github.com/radioactive-labs/plutonium-core/issues/182))
+- Checkbox, toggle and radio variants of the association input ([#185](https://github.com/radioactive-labs/plutonium-core/issues/185))
+- Scope filters, plus fixes from the #182 review ([#186](https://github.com/radioactive-labs/plutonium-core/issues/186))
+
 ## [0.67.0] - 2026-10-09
 
 ### Bug Fixes

data/SECURITY.md

@@ -12,7 +12,7 @@ please upgrade before reporting an issue to confirm it still reproduces.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| Latest release (`0.67.x`) | :white_check_mark: |
+| Latest release (`0.68.x`) | :white_check_mark: |
 | Older releases | :x: |
 
 ## Reporting a Vulnerability

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/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/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.

data/lib/plutonium/dashboard/base.rb

@@ -32,7 +32,7 @@ module Plutonium
       delegate :current_user, :current_scoped_entity, :scoped_to_entity?,
         :params, :request, :controller, :current_engine,
         :resource_url_for, :authorized_resource_scope, :allowed_to?, :policy_for,
-        :registered_resources, :root_path,
+        :registered_resources, :root_path, :current_package,
         to: :view_context
 
       class << self
@@ -92,6 +92,75 @@ module Plutonium
         card
       end
 
+      # A filter's chosen value for this request, or its default.
+      # @raise [ArgumentError] when the dashboard declares no such filter
+      def filter_value(key)
+        filter_values.fetch(key.to_sym) { raise ArgumentError, "#{self.class.name} declares no filter #{key.inspect}" }
+      end
+
+      # Every filter's chosen value, keyed by filter: what the page carries
+      # onto each card's frame URL. Read once per request.
+      def filter_values
+        @filter_values ||= self.class.filters.to_h { |filter| [filter.key, filter.value_from(self)] }.freeze
+      end
+
+      # A filter's value => label pairs for this request, built once.
+      def filter_choices(filter)
+        (@filter_choices ||= {})[filter.key] ||= filter.choices_for(self)
+      end
+
+      # The resource's authorized scope with the scope chosen by its
+      # `filter ..., scopes:` applied by the index's own query object, so a
+      # card's number matches the index list {#filtered_url} opens. Without
+      # such a filter, or with "All" chosen, the authorized scope as is.
+      #
+      # The scope block runs against this dashboard's controller, so it has
+      # `current_user` and the portal's helpers, but not a resource
+      # controller's (`current_parent`, `current_definition`, ...).
+      def filtered(resource_class)
+        relation = authorized_resource_scope(resource_class)
+        name = chosen_scope(resource_class)
+        return relation unless name
+
+        scope_query_for(resource_class).scope_definitions.fetch(name).apply(relation, context: controller)
+      end
+
+      # The resource's index, on the scope chosen by its `filter ..., scopes:`.
+      # "All" is sent explicitly when the definition has a `default_scope`, or
+      # the index would apply that instead.
+      def filtered_url(resource_class)
+        name = chosen_scope(resource_class)
+        scope = name || ("" if resource_definition_for(resource_class).default_scope)
+        options = scope.nil? ? {} : {q: {scope:}}
+        resource_url_for(resource_class, parent: nil, **options)
+      end
+
+      # The resource's definition in this dashboard's portal, falling back to
+      # the base one, as a resource controller resolves it.
+      def resource_definition_for(resource_class)
+        (@resource_definitions ||= {})[resource_class] ||= begin
+          portal_definition = current_package && "#{current_package}::#{resource_class}Definition".safe_constantize
+          (portal_definition || "#{resource_class}Definition".constantize).new
+        end
+      end
+
+      # The index's query object for the resource, holding its definition's
+      # scopes: how each applies, whether it shows, and its label. It reads
+      # no params and builds no URLs here.
+      def scope_query_for(resource_class)
+        (@scope_queries ||= {})[resource_class] ||=
+          Plutonium::Resource::QueryObject.new(resource_class, {}, nil) do |query|
+            resource_definition_for(resource_class).defined_scopes.each do |name, scope|
+              query.define_scope name, scope[:block], **scope[:options]
+            end
+          end
+      end
+
+      # The toolbar links whose `condition:` passes for this request.
+      def visible_links
+        self.class.links.select { |link| link.visible?(self) }
+      end
+
       # The refresh interval for a card: its own, else the dashboard default.
       # A card declared `refresh: false` never refreshes.
       def refresh_for(card)
@@ -106,6 +175,16 @@ module Plutonium
 
       private
 
+      # The scope name a `filter ..., scopes: resource_class` has chosen, or
+      # nil for "All" or when the dashboard has no such filter.
+      def chosen_scope(resource_class)
+        filter = self.class.filters.find { |candidate| candidate.resource_class == resource_class }
+        return unless filter
+
+        value = filter_value(filter.key)
+        value unless value == Filter::ALL
+      end
+
       def t(key, **options)
         Plutonium::Translation.t(key, **options)
       end

data/lib/plutonium/dashboard/card.rb

@@ -9,6 +9,8 @@ module Plutonium
     # Built by {DSL} at class-load and frozen; everything request-dependent
     # (label translation, `condition:`, `href:`) is resolved per render.
     class Card
+      include Evaluation
+
       KINDS = %i[metric chart custom].freeze
 
       # The dashboard grid is 12 columns wide, so halves, thirds and quarters
@@ -21,11 +23,14 @@ module Plutonium
 
       METRIC_FORMATS = %i[number currency percentage human].freeze
       METRIC_POSITIVE = %i[up down].freeze
+      # How a metric's change reads: a percent of the previous value, or the
+      # difference in points (for a value that is itself a percentage).
+      METRIC_CHANGE_UNITS = %i[percent points].freeze
       CHART_TYPES = %i[line area column bar pie donut scatter].freeze
 
       # Options every kind accepts.
       COMMON_OPTIONS = %i[label description icon span lazy refresh condition href].freeze
-      METRIC_OPTIONS = %i[format precision unit prefix suffix positive change_label].freeze
+      METRIC_OPTIONS = %i[format precision unit prefix suffix positive change_label change_unit].freeze
       CHART_OPTIONS = %i[type height].freeze
 
       attr_reader :key, :kind, :icon, :span, :refresh, :condition, :href, :block, :options, :dashboard_class
@@ -87,14 +92,7 @@ module Plutonium
       # the page AND the card endpoint, so a hidden card cannot be fetched
       # directly.
       def visible?(dashboard)
-        return true if condition.nil?
-
-        result = case condition
-        when Symbol then dashboard.send(condition)
-        when Proc then evaluate_on(dashboard, condition)
-        else condition
-        end
-        result ? true : false
+        condition_passes?(dashboard, condition)
       end
 
       # The card's link target for this request, if any.
@@ -135,10 +133,6 @@ module Plutonium
 
       private
 
-      def evaluate_on(dashboard, callable)
-        callable.arity.zero? ? dashboard.instance_exec(&callable) : dashboard.instance_exec(dashboard, &callable)
-      end
-
       def validate_span!(span)
         return GRID_COLUMNS if span == :full
         return span if span.is_a?(Integer) && span.between?(1, GRID_COLUMNS)
@@ -178,6 +172,11 @@ module Plutonium
           raise ArgumentError, "metric #{key.inspect}: positive must be :up or :down, got #{positive.inspect}"
         end
 
+        change_unit = specific.fetch(:change_unit, :percent)
+        unless METRIC_CHANGE_UNITS.include?(change_unit)
+          raise ArgumentError, "metric #{key.inspect}: change_unit must be one of #{METRIC_CHANGE_UNITS.inspect}, got #{change_unit.inspect}"
+        end
+
         specific.merge(positive:)
       end
 

data/lib/plutonium/dashboard/controller.rb

@@ -31,6 +31,7 @@ module Plutonium
       # GET the mount — the full page.
       def show
         authorize_dashboard!
+        ensure_filters_clear_of_path_params!
         set_page_title(current_dashboard_class.label)
         render Plutonium::UI::Page::Dashboard.new(dashboard: current_dashboard)
       end
@@ -38,6 +39,7 @@ module Plutonium
       # GET <mount>/cards/:card — one card, wrapped in its turbo frame.
       def card
         authorize_dashboard!
+        ensure_filters_clear_of_path_params!
         card = current_dashboard.visible_card!(params[:card])
         render Plutonium::UI::Dashboard::Frame.new(dashboard: current_dashboard, card:)
       end
@@ -77,24 +79,40 @@ module Plutonium
         )
       end
 
+      # A path segment of the mount (the tenant on a path-scoped portal, a
+      # `(:locale)` scope) belongs to the route, so it cannot be refused when
+      # the filter is declared. A filter under that key would read the
+      # segment's value and overwrite it on every card's frame URL. The card
+      # route's own segments count even when optional and absent from this
+      # request, since its URL helper would fill them.
+      def ensure_filters_clear_of_path_params!
+        segments = (request.path_parameters.keys.map(&:to_sym) | dashboard_card_route.parts) - %i[controller action]
+        collision = current_dashboard_class.filters.map(&:key) & segments
+        return if collision.empty?
+
+        raise ArgumentError,
+          "#{current_dashboard_class.name} filter #{collision.first.inspect} collides with a path segment of the dashboard's route, pick another name"
+      end
+
       # The card endpoint's path, threading the entity scope segment through so
-      # the frame stays inside the tenant. Resolved by the route's
-      # `dashboard_class` default, so `at:` / `as:` and a scope prefix are honoured.
+      # the frame stays inside the tenant, and the dashboard's filter values
+      # through as query parameters so the card reads what the page read.
+      # Resolved by the route's `dashboard_class` default, so `at:` / `as:` and
+      # a scope prefix are honoured.
       def dashboard_card_path(card)
-        options = {card: card.key}
+        options = current_dashboard.filter_values.merge(card: card.key)
         options[scoped_entity_param_key] = params[scoped_entity_param_key] if scoped_to_entity?
         current_engine.routes.url_helpers.public_send(dashboard_card_route_helper, **options)
       end
 
       def dashboard_card_route_helper
-        @dashboard_card_route_helper ||= begin
-          name = Plutonium::Dashboard::RouteResolution.route_name(
-            current_engine.routes, current_dashboard_class, action: "card"
-          )
-          raise "no register_dashboard route found for #{current_dashboard_class.name}" unless name
+        :"#{dashboard_card_route.name}_path"
+      end
 
-          :"#{name}_path"
-        end
+      def dashboard_card_route
+        @dashboard_card_route ||=
+          Plutonium::Dashboard::RouteResolution.route(current_engine.routes, current_dashboard_class, action: "card") ||
+          raise("no register_dashboard route found for #{current_dashboard_class.name}")
       end
     end
   end

data/lib/plutonium/dashboard/dsl.rb

@@ -2,8 +2,8 @@
 
 module Plutonium
   module Dashboard
-    # The author-facing class macros: `metric`, `chart`, `card`, `refresh`
-    # and `width`. Mixed into {Base}.
+    # The author-facing class macros: `metric`, `chart`, `card`, `filter`,
+    # `link`, `refresh` and `width`. Mixed into {Base}.
     module DSL
       extend ActiveSupport::Concern
 
@@ -47,6 +47,61 @@ module Plutonium
           add_card(key, kind: :custom, options:, block:)
         end
 
+        # The declared filters, in declaration order.
+        def filters
+          @filters ||= []
+        end
+
+        # The declared toolbar links, in declaration order.
+        def links
+          @links ||= []
+        end
+
+        # A page-level control every card reads, such as a period or a region.
+        # The chosen value comes from the query string, is carried onto every
+        # lazy card's frame URL so each card sees what the page saw, and is
+        # read in a card block with `filter_value(key)`. The page renders the
+        # filters as a segmented control above the cards.
+        #
+        #   filter :period, choices: {"7" => "Last 7 days", "30" => "Last 30 days"}, default: "30"
+        #   metric(:orders) { orders.where(created_at: filter_value(:period).to_i.days.ago..).count }
+        #
+        # `scopes:` takes a resource instead of choices: "All" plus the scopes
+        # its definition declares. `filtered(Post)` then counts what the index
+        # would list, and `filtered_url(Post)` opens that list.
+        #
+        #   filter :status, scopes: Post
+        #   metric(:posts, href: -> { filtered_url(Post) }) { filtered(Post).count }
+        def filter(key, choices: nil, scopes: nil, default: nil, label: nil)
+          key = key.to_sym
+          raise ArgumentError, "#{name || "dashboard"} already declares a filter #{key.inspect}" if find_filter(key)
+          if scopes && filters.any? { |filter| filter.resource_class == scopes }
+            raise ArgumentError, "#{name || "dashboard"} already declares a scope filter for #{scopes}"
+          end
+
+          filters << Filter.new(key, choices:, scopes:, default:, label:)
+          filters.last
+        end
+
+        # A link in the toolbar above the cards, such as the dashboard's
+        # settings or a full report. `href:` and `condition:` are evaluated on
+        # the dashboard instance, like a card's.
+        #
+        #   link :settings, href: -> { resource_url_for(Setting) }, icon: Phlex::TablerIcons::Settings
+        def link(key, href:, label: nil, icon: nil, condition: nil)
+          key = key.to_sym
+          raise ArgumentError, "#{name || "dashboard"} already declares a link #{key.inspect}" if links.any? { |link| link.key == key }
+
+          links << Link.new(key, href:, label:, icon:, condition:)
+          links.last
+        end
+
+        # @return [Filter, nil]
+        def find_filter(key)
+          key = key.to_sym
+          filters.find { |filter| filter.key == key }
+        end
+
         # Default refresh interval (seconds) for every lazy card. A card's own
         # `refresh:` overrides it; `refresh: false` on a card opts out.
         def refresh(seconds = UNSET)
@@ -95,6 +150,8 @@ module Plutonium
         def inherited(subclass)
           super
           subclass.instance_variable_set(:@cards, cards.dup)
+          subclass.instance_variable_set(:@filters, filters.dup)
+          subclass.instance_variable_set(:@links, links.dup)
           subclass.instance_variable_set(:@refresh, @refresh)
           subclass.instance_variable_set(:@width, @width)
         end

data/lib/plutonium/dashboard/evaluation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Dashboard
+    # How a card or toolbar link runs its author-supplied procs and
+    # `condition:` against the dashboard instance, so both accept the same
+    # forms.
+    module Evaluation
+      private
+
+      # A zero-arity proc runs on the dashboard instance; a proc taking an
+      # argument also receives the dashboard.
+      def evaluate_on(dashboard, callable)
+        callable.arity.zero? ? dashboard.instance_exec(&callable) : dashboard.instance_exec(dashboard, &callable)
+      end
+
+      # `condition:` is nil (always), a proc (see {#evaluate_on}), a symbol
+      # naming a dashboard method, or a plain value.
+      def condition_passes?(dashboard, condition)
+        result = case condition
+        when nil then true
+        when Symbol then dashboard.send(condition)
+        when Proc then evaluate_on(dashboard, condition)
+        else condition
+        end
+        result ? true : false
+      end
+    end
+  end
+end