plutonium 0.66.0 → 0.68.0

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

data/lib/plutonium/dashboard/filter.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Dashboard
+    # A page-level control every card reads, declared with `filter`. Its value
+    # comes from the request's query string under the filter's key, and a value
+    # that is not one of the choices reads as the default, so a hand-edited URL
+    # can never reach a card block.
+    #
+    # The choices are either given (`choices:`) or are a resource's scopes
+    # (`scopes: Post`): "All" plus every scope the resource's definition
+    # declares, labelled and gated the way the index's scope pills are.
+    class Filter
+      # Keys a filter cannot take: the card route's own params and the options
+      # `url_for` reads, all of which the filter values are merged into when
+      # building each card's frame URL. A key that is a path segment of the
+      # mount (an entity scope, a `(:locale)` scope) is refused per request,
+      # since only the route knows it.
+      RESERVED_KEYS = %i[
+        card dashboard_class controller action format anchor params path_params
+        host protocol port subdomain domain tld_length user password
+        script_name original_script_name only_path trailing_slash
+        use_route _recall
+      ].freeze
+
+      # The value of a scope filter's "All" choice.
+      ALL = "all"
+
+      attr_reader :key, :resource_class
+
+      # @param choices [Hash{#to_s => String, Proc}, nil] value => label, in display order
+      # @param scopes [Class, nil] a resource whose definition's scopes are the choices
+      # @param default [#to_s, nil] one of the choices; the first (or, for
+      #   scopes, the definition's `default_scope`, else "All") when nil
+      def initialize(key, choices: nil, scopes: nil, default: nil, label: nil)
+        @key = key.to_sym
+        if RESERVED_KEYS.include?(@key)
+          raise ArgumentError, "filter #{@key.inspect}: the name is reserved by the card route, pick another"
+        end
+        unless choices.nil? ^ scopes.nil?
+          raise ArgumentError, "filter #{@key.inspect}: pass exactly one of choices: or scopes:"
+        end
+
+        @label = label
+        @default = default&.to_s
+
+        if scopes
+          raise ArgumentError, "filter #{@key.inspect}: scopes: takes a resource class, got #{scopes.inspect}" unless scopes.is_a?(Class)
+
+          @resource_class = scopes
+        else
+          @choices = choices.to_h.transform_keys(&:to_s).freeze
+          raise ArgumentError, "filter #{@key.inspect}: choices must not be empty" if @choices.empty?
+
+          @default ||= @choices.keys.first
+          validate_default!
+        end
+      end
+
+      def scopes? = !@resource_class.nil?
+
+      # The control's accessible name.
+      def label
+        Plutonium::Translation.resolve(@label) || key.to_s.humanize
+      end
+
+      # value => label for this request. Labels may be lazy `t` procs. Read it
+      # through {Base#filter_choices}, which builds it once per request.
+      def choices_for(dashboard)
+        scopes? ? scope_choices(dashboard) : @choices
+      end
+
+      # An explicit `default:` must be one of the definition's scopes. A
+      # default (explicit or the definition's `default_scope`) whose
+      # `condition:` hides it from this user reads as "All", as does a
+      # `default_scope` the definition never declares as a scope.
+      def default_for(dashboard)
+        return @default unless scopes?
+
+        if @default && !dashboard.scope_query_for(resource_class).scope_definitions.key?(@default)
+          raise ArgumentError, "filter #{key.inspect}: default #{@default.inspect} is not a scope of #{resource_class}'s definition"
+        end
+
+        default = @default || dashboard.resource_definition_for(resource_class).default_scope&.to_s
+        dashboard.filter_choices(self).key?(default) ? default : ALL
+      end
+
+      # The chosen value for this request.
+      def value_from(dashboard)
+        value = dashboard.params[key].to_s
+        dashboard.filter_choices(self).key?(value) ? value : default_for(dashboard)
+      end
+
+      private
+
+      def scope_choices(dashboard)
+        query = dashboard.scope_query_for(resource_class)
+        if query.scope_definitions.key?(ALL)
+          raise ArgumentError, "filter #{key.inspect}: #{resource_class}'s definition declares a scope named :#{ALL}, which is the filter's \"All\" choice"
+        end
+
+        visible = query.scope_definitions.keys.select { |name| query.scope_visible?(name, dashboard.view_context) }
+        {ALL => -> { Plutonium::Translation.t("plutonium.ui.table.all") }}
+          .merge(visible.to_h { |name| [name, query.scope_label(name)] })
+      end
+
+      def validate_default!
+        return if @choices.key?(@default)
+
+        raise ArgumentError, "filter #{key.inspect}: default #{@default.inspect} is not one of #{@choices.keys.inspect}"
+      end
+    end
+  end
+end

data/lib/plutonium/dashboard/link.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Dashboard
+    # A link in the dashboard's toolbar, declared with `link`: the way to a
+    # related page such as the dashboard's settings or a full report.
+    class Link
+      include Evaluation
+
+      attr_reader :key, :icon
+
+      def initialize(key, href:, label: nil, icon: nil, condition: nil)
+        @key = key.to_sym
+        @href = href
+        @label = label
+        @icon = icon
+        @condition = condition
+      end
+
+      def label
+        Plutonium::Translation.resolve(@label) || key.to_s.humanize
+      end
+
+      # Evaluated like a card's `href:`.
+      def href_for(dashboard)
+        @href.is_a?(Proc) ? evaluate_on(dashboard, @href) : @href
+      end
+
+      # Evaluated like a card's `condition:`.
+      def visible?(dashboard)
+        condition_passes?(dashboard, @condition)
+      end
+    end
+  end
+end

data/lib/plutonium/dashboard/route_resolution.rb

@@ -17,13 +17,17 @@ module Plutonium
       # @param action [String, Symbol] "show" or "card"
       # @return [Symbol, nil] the route name (e.g. :sales_dashboard_card)
       def route_name(route_set, dashboard_class, action:)
-        route = route_set.routes.find do |r|
+        route(route_set, dashboard_class, action:)&.name&.to_sym
+      end
+
+      # @return [ActionDispatch::Journey::Route, nil] the named route itself
+      def route(route_set, dashboard_class, action:)
+        route_set.routes.find do |r|
           d = r.defaults
           r.name.present? &&
             d[:action].to_s == action.to_s &&
             d[:dashboard_class].to_s == dashboard_class.name
         end
-        route&.name&.to_sym
       end
     end
   end

data/lib/plutonium/helpers/content_helper.rb

@@ -10,9 +10,6 @@ module Plutonium
           title: content,
           data: {
             controller: "timeago",
-            timeago_refresh_interval_value: 1000,
-            timeago_include_seconds_value: true,
-            timeago_add_suffix_value: true,
             timeago_datetime_value: date.iso8601
           }
         )

data/lib/plutonium/query/filter.rb

@@ -10,7 +10,8 @@ module Plutonium
         def lookup(type)
           return type if type.is_a?(Class) && type < Filter
 
-          class_name = "Plutonium::Query::Filters::#{type.to_s.classify}"
+          # camelize, not classify: classify singularizes (`:tags` -> `Tag`).
+          class_name = "Plutonium::Query::Filters::#{type.to_s.camelize}"
           class_name.constantize
         rescue NameError
           raise ArgumentError, "Unknown filter type: #{type}. Expected #{class_name} to exist."

data/lib/plutonium/query/filters/tags.rb

@@ -0,0 +1,36 @@
+module Plutonium
+  module Query
+    module Filters
+      # Filter by a no_fly_list `has_tags` context, through the gem's own
+      # query scopes.
+      #
+      # @example Records with any of the chosen tags
+      #   filter :labels, with: :tags
+      #
+      # @example Records with every chosen tag
+      #   filter :labels, with: :tags, match: :all
+      #
+      class Tags < Filter
+        def initialize(match: :any, **)
+          super(**)
+          @match = match
+        end
+
+        def apply(scope, value:)
+          tags = Array(value).compact_blank
+          return scope if tags.empty?
+
+          scope.public_send(:"with_#{@match}_#{key}", tags)
+        end
+
+        def humanize_value(value)
+          Array(value).compact_blank.join(", ")
+        end
+
+        def customize_inputs
+          input :value, as: Plutonium::UI::Form::Components::TagsFilter, context: key
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/resource/query_object.rb

@@ -36,6 +36,12 @@ module Plutonium
         Plutonium::Translation.label_for(:filter, resource_class, name) || name.to_s.humanize
       end
 
+      # Display label for a scope: the plutonium.scopes.<model>.<name>
+      # convention, else the humanized name.
+      def scope_label(name)
+        Plutonium::Translation.label_for(:scope, resource_class, name) || name.to_s.humanize
+      end
+
       def initialize(resource_class, params, request_path, &)
         @resource_class = resource_class
         @params = params

data/lib/plutonium/routing/dashboard_registration.rb

@@ -114,6 +114,11 @@ module Plutonium
         # the portal's again, last, so bare helpers (`root_path` in the
         # sidebar) resolve against the engine like a source-defined controller.
         klass.include(namespace.railtie_routes_url_helpers) if namespace != Object
+        # The same anonymous `inherited` hook boots the controller before it
+        # has a name, so it never prepends the portal's views and a portal's
+        # own partials (an ejected sidebar) lose to the gem's. Boot it again
+        # now that it is named.
+        klass.boot
 
         if concern_name && (concern = concern_name.safe_constantize)
           klass.include concern

data/lib/plutonium/ui/avatar.rb

@@ -56,7 +56,7 @@ module Plutonium
           value.attached? ? value.url : nil
         elsif value.respond_to?(:url)     # bare Shrine::UploadedFile, CarrierWave, ...
           value.url
-        elsif value.is_a?(String) && value.start_with?("http", "/")
+        elsif value.is_a?(String) && value.start_with?("http", "/", "data:image/")
           value
         end
       rescue ArgumentError, URI::InvalidURIError
@@ -72,7 +72,7 @@ module Plutonium
         # A URL-shaped positional subject is really an image, not an identity:
         # route it to src so Avatar("https://…/p.png") shows the image rather
         # than hashing the URL into a seed.
-        if src.nil? && subject.is_a?(String) && subject.start_with?("http", "/")
+        if src.nil? && subject.is_a?(String) && subject.start_with?("http", "/", "data:image/")
           src = subject
           subject = nil
         end

data/lib/plutonium/ui/component/resolves_tags.rb

@@ -34,9 +34,22 @@ module Plutonium
           tag ||= inferred_field_component
           return create_component(tag, component_theme_key(tag), **attributes, &) if tag.is_a?(Class)
 
+          # `field :x, as:` reaches every surface, but some aliases exist on
+          # only one (`:toggle` is form-only, `:badge` display-only). Those
+          # surfaces render what they would have inferred instead of raising.
+          # A tag NO surface defines is a typo and still raises below.
+          tag = inferred_field_component if !respond_to?(:"#{tag}_tag") && ResolvesTags.surface_tag?(tag)
+
           send(:"#{tag}_tag", **attributes, &)
         end
 
+        # Whether any field surface (form or display; the table renders through
+        # a display builder) defines `tag`.
+        def self.surface_tag?(tag)
+          [Plutonium::UI::Form::Base::Builder, Plutonium::UI::Display::Base::Builder]
+            .any? { |builder| builder.method_defined?(:"#{tag}_tag") }
+        end
+
         private
 
         # Theme key for a directly-rendered component class:

data/lib/plutonium/ui/dashboard/board.rb

@@ -6,7 +6,9 @@ module Plutonium
       # The card grid. Every lazy card is a `<turbo-frame src loading="lazy">`
       # holding a skeleton of its own shape, so the page paints at once and
       # each card's queries run in a separate request as it scrolls into
-      # view. A card declared `lazy: false` renders inline.
+      # view. A card declared `lazy: false` renders inline. Frames carry
+      # `target="_top"` so a link inside a card navigates the page, not the
+      # card's frame.
       class Board < Plutonium::UI::Component::Base
         include Phlex::Rails::Helpers::TurboFrameTag
 
@@ -54,6 +56,7 @@ module Plutonium
               src: dashboard_card_path(card),
               loading: "lazy",
               refresh: "morph",
+              target: "_top",
               class: tokens("block", span_classes(card)),
               **refresh_attributes(card)
             ) { render Skeleton.new(card:) }

data/lib/plutonium/ui/dashboard/frame.rb

@@ -15,7 +15,7 @@ module Plutonium
         end
 
         def view_template
-          turbo_frame_tag(@card.frame_id, class: "block") do
+          turbo_frame_tag(@card.frame_id, target: "_top", class: "block") do
             render Card.for(dashboard: @dashboard, card: @card)
           end
         end