plutonium 0.49.1 → 0.50.0

data/lib/plutonium/definition/metadata.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Definition
+    # Adds the `metadata` DSL — a list of field names rendered in the
+    # show page's right-side panel as label/value rows. Opt-in: when no
+    # `metadata` call is made, the show page stays full-width with no
+    # aside.
+    #
+    # @example
+    #   class PostDefinition < Plutonium::Definition::Base
+    #     metadata :created_at, :updated_at, :author, :state
+    #   end
+    module Metadata
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :defined_metadata_fields, default: [], instance_accessor: false
+      end
+
+      class_methods do
+        # Declares the fields rendered in the show page metadata panel.
+        # Each name is looked up in `defined_fields` for display config
+        # (label/format), so a field can have custom formatting in the
+        # main show body and the panel without redeclaring.
+        #
+        # @param names [Array<Symbol>]
+        def metadata(*names)
+          self.defined_metadata_fields = names.flatten.map(&:to_sym)
+        end
+      end
+
+      # class_attribute is declared with instance_accessor: false; expose
+      # an instance reader that delegates so callers with a definition
+      # instance (e.g. `current_definition`) can ask without poking the
+      # class directly. Mirrors Definition::Views.
+      def defined_metadata_fields = self.class.defined_metadata_fields
+    end
+  end
+end

data/lib/plutonium/definition/views.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Definition
+    # DSL for declaring which index views a resource supports and how
+    # they're configured.
+    #
+    # @example Enable both views, default to Grid
+    #   class UserDefinition < Plutonium::Resource::Definition
+    #     views :table, :grid
+    #     default_view :grid
+    #
+    #     grid_fields(
+    #       image:     :avatar,
+    #       header:    :name,
+    #       subheader: :email,
+    #       meta:      [:role, :status]
+    #     )
+    #   end
+    module Views
+      extend ActiveSupport::Concern
+
+      KNOWN_VIEWS = %i[table grid].freeze
+      GRID_SLOTS = %i[image header subheader body meta footer].freeze
+      GRID_LAYOUTS = %i[compact media].freeze
+
+      included do
+        class_attribute :defined_views, default: [:table], instance_accessor: false
+        class_attribute :defined_default_view, default: nil, instance_accessor: false
+        class_attribute :defined_grid_fields, default: {}, instance_accessor: false
+        class_attribute :defined_grid_layout, default: :compact, instance_accessor: false
+        class_attribute :defined_grid_columns, default: nil, instance_accessor: false
+      end
+
+      class_methods do
+        # Declares the index views this resource supports.
+        # @param list [Array<Symbol>] one or more of {KNOWN_VIEWS}
+        def views(*list)
+          list = list.flatten.map(&:to_sym)
+          invalid = list - KNOWN_VIEWS
+          raise ArgumentError, "Unknown views: #{invalid.inspect}. Valid: #{KNOWN_VIEWS}" if invalid.any?
+          self.defined_views = list.empty? ? [:table] : list
+        end
+
+        # Declares the default index view. Must be one of {.views}.
+        # Falls back to the first declared view if unset.
+        def default_view(name = nil)
+          if name.nil?
+            defined_default_view || defined_views.first
+          else
+            name = name.to_sym
+            unless defined_views.include?(name)
+              raise ArgumentError, "default_view #{name.inspect} not in views #{defined_views.inspect}"
+            end
+            self.defined_default_view = name
+          end
+        end
+
+        # Maps grid slots to fields. Each slot is optional. Implicitly
+        # adds `:grid` to {.views} so a resource can opt into the Grid
+        # view simply by declaring its slots.
+        # @param slots [Hash{Symbol => Symbol, Array<Symbol>}]
+        def grid_fields(**slots)
+          invalid = slots.keys - GRID_SLOTS
+          raise ArgumentError, "Unknown grid slots: #{invalid.inspect}. Valid: #{GRID_SLOTS}" if invalid.any?
+          self.defined_grid_fields = slots
+          self.defined_views = defined_views + [:grid] unless defined_views.include?(:grid)
+        end
+
+        # Layout shape for grid cards. :compact (default) places the image
+        # left of the content; :media stacks the image full-width on top.
+        def grid_layout(value)
+          value = value.to_sym
+          unless GRID_LAYOUTS.include?(value)
+            raise ArgumentError, "grid_layout must be one of #{GRID_LAYOUTS}, got #{value.inspect}"
+          end
+          self.defined_grid_layout = value
+        end
+
+        # Override responsive column count. Default is 1 / 2 / 3 / 4 at
+        # sm / md / lg / xl.
+        def grid_columns(value)
+          self.defined_grid_columns = Integer(value)
+        end
+      end
+
+      def defined_views = self.class.defined_views
+      def default_view = self.class.default_view
+      def defined_grid_fields = self.class.defined_grid_fields
+      def defined_grid_layout = self.class.defined_grid_layout
+      def defined_grid_columns = self.class.defined_grid_columns
+    end
+  end
+end

data/lib/plutonium/helpers/turbo_helper.rb

@@ -6,7 +6,7 @@ module Plutonium
       end
 
       def remote_modal_frame_tag(&)
-        turbo_frame_tag("remote_modal", &)
+        turbo_frame_tag(Plutonium::REMOTE_MODAL_FRAME, &)
       end
     end
   end

data/lib/plutonium/interaction/response/redirect.rb

@@ -29,7 +29,7 @@ module Plutonium
 
             respond_to do |format|
               format.turbo_stream do
-                if helpers.current_turbo_frame == "remote_modal"
+                if helpers.current_turbo_frame == Plutonium::REMOTE_MODAL_FRAME
                   render turbo_stream: [
                     helpers.turbo_stream_redirect(url)
                   ]

data/lib/plutonium/query/base.rb

@@ -24,6 +24,14 @@ module Plutonium
       def apply(scope, **params)
         raise NotImplementedError, "#{self.class}#apply(scope, **params)"
       end
+
+      # Human-readable rendering of a single filter value for the active
+      # filter pill row. Defaults to `value.to_s`. Subclasses
+      # (Filters::Association, Filters::Boolean) override to translate
+      # raw param values (SGIDs, "true"/"false") into recognisable text.
+      def humanize_value(value)
+        value.to_s
+      end
     end
   end
 end

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

@@ -16,7 +16,7 @@ module Plutonium
       #   filter :user, with: :association, class_name: User, scope: ->(s) { s.active }
       #
       class Association < Filter
-        def initialize(class_name: nil, resource_class: nil, scope: nil, multiple: false, **)
+        def initialize(class_name: nil, resource_class: nil, scope: nil, multiple: true, **)
           super(**)
           @class_name = class_name
           @resource_class = resource_class
@@ -24,15 +24,21 @@ module Plutonium
           @multiple = multiple
         end
 
+        def humanize_value(value)
+          return "" if value.blank?
+          ids = decode_ids(value)
+          return "" if ids.empty?
+          records = association_class.where(id: ids)
+          records.map { |r| r.respond_to?(:to_label) ? r.to_label : r.to_s }.join(", ")
+        rescue
+          Array(value).reject(&:blank?).join(", ")
+        end
+
         def apply(scope, value:)
           return scope if value.blank?
-
-          foreign_key = :"#{key}_id"
-          if @multiple && value.is_a?(Array)
-            scope.where(foreign_key => value.reject(&:blank?))
-          else
-            scope.where(foreign_key => value)
-          end
+          ids = decode_ids(value)
+          return scope if ids.empty?
+          scope.where("#{key}_id": ids)
         end
 
         def customize_inputs
@@ -45,6 +51,22 @@ module Plutonium
 
         private
 
+        # Accepts either an SGID (the new default sent by ResourceSelect)
+        # or a raw id (legacy URLs). Returns the underlying record ids.
+        def decode_ids(value)
+          Array(value).reject(&:blank?).filter_map { |v| decode_id(v) }
+        end
+
+        def decode_id(value)
+          gid = SignedGlobalID.parse(value)
+          return gid.model_id if gid
+          value
+        rescue
+          value
+        end
+
+        private
+
         def association_class
           @association_class ||= resolve_class_name || detect_class_from_reflection || infer_class_from_key
         end

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

@@ -16,6 +16,11 @@ module Plutonium
           @false_label = false_label
         end
 
+        def humanize_value(value)
+          return "" if value.blank?
+          ActiveModel::Type::Boolean.new.cast(value) ? @true_label : @false_label
+        end
+
         def apply(scope, value:)
           return scope if value.blank?
 

data/lib/plutonium/resource/controllers/presentable.rb

@@ -5,7 +5,7 @@ module Plutonium
         extend ActiveSupport::Concern
 
         included do
-          helper_method :build_form, :build_detail, :build_collection
+          helper_method :build_form, :build_detail, :build_collection, :build_grid_collection
         end
 
         private
@@ -82,8 +82,17 @@ module Plutonium
           current_definition.collection_class.new(@resource_records, resource_fields: presentable_attributes, resource_definition: current_definition)
         end
 
+        def build_grid_collection
+          current_definition.grid_class.new(@resource_records, resource_fields: presentable_attributes, resource_definition: current_definition)
+        end
+
         def build_detail
-          current_definition.detail_class.new(resource_record!, resource_fields: presentable_attributes, resource_associations: permitted_associations, resource_definition: current_definition)
+          current_definition.detail_class.new(
+            resource_record!,
+            resource_fields: presentable_attributes,
+            resource_associations: permitted_associations,
+            resource_definition: current_definition
+          )
         end
 
         def build_form(record = resource_record!, action: action_name, form_action: nil, **)

data/lib/plutonium/resource/definition.rb

@@ -1,6 +1,48 @@
 module Plutonium
   module Resource
     class Definition < Plutonium::Definition::Base
+      class_attribute :modal_mode, default: :slideover, instance_accessor: false
+
+      VALID_MODAL_MODES = [:centered, :slideover, false].freeze
+
+      # Sets how :new / :edit actions render.
+      # - :slideover (default) — slide-in panel from the right
+      # - :centered — centered dialog
+      # - false — no modal; new/edit are full standalone pages
+      def self.modal(mode)
+        unless VALID_MODAL_MODES.include?(mode)
+          raise ArgumentError, "modal must be one of #{VALID_MODAL_MODES.inspect}, got #{mode.inspect}"
+        end
+        self.modal_mode = mode
+        configure_crud_modal_targets!
+      end
+
+      # Re-derives the default :new / :edit actions so their turbo_frame
+      # matches the current `modal_mode`. Called when `.modal` is set
+      # and once at Resource::Definition load (so the default
+      # :slideover state propagates to the action records). Subclasses
+      # inherit those records via DefineableProps#inherited (deep_dup);
+      # calling `.modal` on a subclass re-runs this method locally.
+      def self.configure_crud_modal_targets!
+        target = (modal_mode == false) ? nil : Plutonium::REMOTE_MODAL_FRAME
+        [:new, :edit].each do |name|
+          action = defined_actions[name]
+          next unless action
+          next if action.turbo_frame == target
+          defined_actions[name] = action.with(turbo_frame: target)
+        end
+      end
+
+      def modal
+        self.class.modal_mode
+      end
+
+      # Apply the default modal target ("remote_modal") to :new / :edit
+      # so resources that never call `.modal` still get the slideover
+      # behavior. Subclasses inherit the configured actions via
+      # DefineableProps' deep_dup; calling `.modal` on a subclass
+      # re-runs the configuration locally.
+      configure_crud_modal_targets!
     end
   end
 end

data/lib/plutonium/resource/query_object.rb

@@ -63,6 +63,7 @@ module Plutonium
       # Builds a URL with the given options for search and sorting.
       #
       # @param options [Hash] The options for building the URL.
+      # @option options [Boolean] :replace When true, clears all existing sorts before applying the new one
       # @return [String] The constructed URL with query parameters.
       def build_url(**options)
         q = {}
@@ -74,11 +75,19 @@ module Plutonium
           selected_scope_filter
         end
 
-        q[:sort_directions] = selected_sort_directions.dup
-        q[:sort_fields] = selected_sort_fields.dup
+        if options.delete(:replace)
+          q[:sort_directions] = {}
+          q[:sort_fields] = []
+        else
+          q[:sort_directions] = selected_sort_directions.dup
+          q[:sort_fields] = selected_sort_fields.dup
+        end
         handle_sort_options!(q, options)
 
-        q.merge! params.slice(*filter_definitions.keys)
+        filter_keys = filter_definitions.keys.map(&:to_sym)
+        filter_overrides = options.slice(*filter_keys).stringify_keys
+        q.merge! params.with_indifferent_access.slice(*filter_definitions.keys)
+        q.merge!(filter_overrides)
         compacted = deep_compact({q: q})
 
         # Preserve explicit "All" selection (scope: nil in options means show all)
@@ -119,18 +128,67 @@ module Plutonium
 
       def sort_definitions = @sort_definitions ||= {}.with_indifferent_access
 
+      # Returns an array of hashes describing each currently active filter.
+      # Each hash has: name, label, value_label, clear_url
+      def active_filter_descriptions
+        filter_definitions.filter_map do |name, filter|
+          name = name.to_sym
+          filter_params = params[name]
+          next unless filter_params.present?
+
+          value_label = case filter_params
+          when Hash, ActionController::Parameters
+            entries = filter_params.to_h.reject { |_, v| v.blank? }
+            next if entries.empty?
+            # Single-input filters defer to the filter's `humanize_value`
+            # (e.g. Association resolves ids to labels, Boolean translates
+            # "true" -> "Yes"). Multi-input filters keep input-name
+            # qualifiers (e.g. "from 2024, to 2025").
+            if entries.size == 1
+              humanized = filter.humanize_value(entries.values.first)
+              next if humanized.blank?
+              humanized
+            else
+              entries.map { |k, v| "#{k.to_s.humanize.downcase} #{v}" }.join(", ")
+            end
+          when Array
+            entries = filter_params.reject(&:blank?)
+            next if entries.empty?
+            humanized = filter.humanize_value(entries)
+            next if humanized.blank?
+            humanized
+          else
+            next if filter_params.to_s.blank?
+            humanized = filter.humanize_value(filter_params)
+            next if humanized.blank?
+            humanized
+          end
+
+          {
+            name: name,
+            label: name.to_s.humanize,
+            value_label: value_label,
+            clear_url: build_url(name => nil)
+          }
+        end
+      end
+
       # Provides sorting parameters for the given field name.
       #
       # @param name [Symbol, String] The name of the field to sort.
-      # @return [Hash, nil] The sorting parameters including URL and direction.
+      # @return [Hash, nil] The sorting parameters including URL, multi_url, direction, position and multi flag.
       def sort_params_for(name)
         return unless sort_definitions[name]
 
+        multi = selected_sort_fields.size > 1 && selected_sort_fields.include?(name.to_s)
+
         {
-          url: build_url(sort: name),
+          url: build_url(sort: name, replace: true),
+          multi_url: build_url(sort: name),
           reset_url: build_url(sort: name, reset: true),
           position: selected_sort_fields.index(name.to_s),
-          direction: selected_sort_directions[name]
+          direction: selected_sort_directions[name],
+          multi: multi
         }
       end
 

data/lib/plutonium/testing/resource_definition.rb

@@ -33,8 +33,8 @@ module Plutonium
             klass.defined_fields.each_key do |field_name|
               next if field_name == :id
               assert resource_class.column_names.include?(field_name.to_s) ||
-                     resource_class.method_defined?(field_name) ||
-                     resource_class.reflect_on_association(field_name),
+                resource_class.method_defined?(field_name) ||
+                resource_class.reflect_on_association(field_name),
                 "Field :#{field_name} declared in #{klass} but not defined on #{resource_class}"
             end
           end

data/lib/plutonium/ui/action_button.rb

@@ -24,10 +24,11 @@ module Plutonium
 
       DROPDOWN_DEFAULT_COLOR = "text-[var(--pu-text)] hover:bg-[var(--pu-surface-alt)]"
 
-      def initialize(action, url:, variant: :default)
+      def initialize(action, url:, variant: :default, data: {})
         @action = action
         @url = url
         @variant = variant
+        @extra_data = data
       end
 
       def view_template
@@ -49,7 +50,7 @@ module Plutonium
         link_to(
           url_with_return_to,
           class: button_classes,
-          data: {turbo_frame: @action.turbo_frame}
+          data: {turbo_frame: @action.turbo_frame}.merge(@extra_data)
         ) do
           render_button_content
         end
@@ -61,6 +62,7 @@ module Plutonium
           method: @action.route_options.method,
           name: :return_to, value: return_to_url,
           class: "inline-block",
+          data: @extra_data,
           form: {
             data: {
               turbo: @action.turbo,

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

@@ -78,6 +78,8 @@ module Plutonium
 
         def BuildTableScopesBar(...) = Plutonium::UI::Table::Components::ScopesBar.new(...)
 
+        def BuildTableScopesPills(...) = Plutonium::UI::Table::Components::ScopesPills.new(...)
+
         def BuildTableInfo(...) = Plutonium::UI::Table::Components::PagyInfo.new(...)
 
         def BuildTablePagination(...) = Plutonium::UI::Table::Components::PagyPagination.new(...)
@@ -86,7 +88,17 @@ module Plutonium
 
         def BuildBulkActionsToolbar(...) = Plutonium::UI::Table::Components::BulkActionsToolbar.new(...)
 
+        def BuildTableToolbar(...) = Plutonium::UI::Table::Components::Toolbar.new(...)
+
+        def BuildTableFilterPills(...) = Plutonium::UI::Table::Components::FilterPills.new(...)
+
+        def BuildTableViewSwitcher(...) = Plutonium::UI::Table::Components::ViewSwitcher.new(...)
+
         def BuildColorModeSelector(...) = Plutonium::UI::ColorModeSelector.new(...)
+
+        def BuildModalCentered(...) = Plutonium::UI::Modal::Centered.new(...)
+
+        def BuildModalSlideover(...) = Plutonium::UI::Modal::Slideover.new(...)
       end
     end
   end

data/lib/plutonium/ui/display/base.rb

@@ -46,7 +46,9 @@ module Plutonium
 
         def fields_wrapper(&)
           div(class: themed(:fields_wrapper)) {
-            yield
+            div(class: themed(:fields_inner)) {
+              yield
+            }
           }
         end
       end

data/lib/plutonium/ui/display/resource.rb

@@ -13,56 +13,93 @@ module Plutonium
           @resource_definition = resource_definition
         end
 
+        # Metadata fields the user is permitted to see — intersection of
+        # the definition's declared metadata with the policy-filtered
+        # `resource_fields`. Computed lazily so we don't run the
+        # intersection when the resource doesn't declare any metadata.
+        def metadata_fields
+          @metadata_fields ||= resource_definition.defined_metadata_fields & resource_fields
+        end
+
         def display_template
-          render_fields
-          render_associations if present_associations?
+          if associations_present?
+            render_tablist_with_details
+          else
+            render_fields
+          end
         end
 
         private
 
+        def associations_present?
+          present_associations? && resource_associations.present?
+        end
+
         def render_fields
+          if metadata_fields.any?
+            div(class: "grid grid-cols-1 lg:grid-cols-[minmax(0,1fr)_320px] gap-6 items-start") do
+              div { render_main_field_card }
+              aside { render_metadata_panel }
+            end
+          else
+            render_main_field_card
+          end
+        end
+
+        def render_main_field_card
           Block do
             fields_wrapper do
-              resource_fields.each do |name|
+              # Skip fields claimed by the metadata panel — rendering
+              # them in both places duplicates information.
+              (resource_fields - metadata_fields).each do |name|
                 render_resource_field name
               end
             end
           end
         end
 
-        def render_associations
-          return unless resource_associations.present?
+        # Renders the declared metadata fields as a vertical stack beside
+        # the main field card. Reuses render_resource_field (same path
+        # the main details use) so labels/values match in style; the
+        # only difference from the main card is the wrapper — a single
+        # column of fields instead of the form's multi-column grid.
+        def render_metadata_panel
+          Block do
+            div(class: "pu-card-body flex flex-col gap-6") do
+              metadata_fields.each { |name| render_resource_field(name) }
+            end
+          end
+        end
 
+        def render_tablist_with_details
           tablist = BuildTabList()
 
+          # Build an inner display component for the Details tab.
+          # It must be a standalone Phlex component so that TabList can call
+          # `render(details_display)` from within its own context. Phlex propagates
+          # @_state through render calls, so the inner component writes to the same
+          # buffer as the outer Resource display even though self changes.
+          details_display = build_details_display
+
+          tablist.with_tab(
+            identifier: "details",
+            title: -> { plain "Details" }
+          ) do
+            render details_display
+          end
+
           resource_associations.each do |name|
             reflection = object.class.reflect_on_association name
-
-            if !reflection
-              raise ArgumentError,
-                "unknown association #{object.class}##{name} defined in #permitted_associations"
-            elsif !registered_resources.include?(reflection.klass)
-              raise ArgumentError,
-                "#{object.class}##{name} defined in #permitted_associations, but #{reflection.klass} is not a registered resource"
-            end
+            raise_unknown_association(name) unless reflection
+            raise_unregistered_association(name, reflection) unless registered_resources.include?(reflection.klass)
 
             title = object.class.human_attribute_name(name)
-            src = case reflection.macro
-            when :belongs_to
-              associated = object.public_send name
-              resource_url_for(associated, parent: nil) if associated
-            when :has_one
-              associated = object.public_send name
-              resource_url_for(associated, parent: object, association: name)
-            when :has_many
-              resource_url_for(reflection.klass, parent: object, association: name)
-            end
-
+            src = association_src(name, reflection)
             next unless src
 
             tablist.with_tab(
               identifier: title.parameterize,
-              title: -> { h5(class: "text-2xl font-bold tracking-tight text-[var(--pu-text)]") { title } }
+              title: -> { plain title }
             ) do
               FrameNavigatorPanel(title: "", src:, panel_id: "association-panel-#{title.parameterize}")
             end
@@ -71,6 +108,53 @@ module Plutonium
           render tablist
         end
 
+        # Builds a standalone Phlex component whose sole job is to render the
+        # resource fields. Having a distinct component lets TabList call
+        # `render(details_display)` so that Phlex propagates its @_state correctly,
+        # while avoiding the `instance_exec` context-switch problem that would
+        # occur if we put `render_fields` directly inside the `with_tab` block.
+        #
+        # The anonymous subclass overrides `view_template` to skip the outer
+        # `display_wrapper` div (which would duplicate the dom id already emitted
+        # by the parent Resource display) and renders just the fields content.
+        def build_details_display
+          resource = self
+
+          klass = Class.new(self.class) do
+            define_method(:view_template) do
+              resource.send(:render_fields)
+            end
+          end
+
+          klass.new(
+            object,
+            resource_fields: resource_fields,
+            resource_associations: [],
+            resource_definition: resource_definition
+          )
+        end
+
+        def association_src(name, reflection)
+          case reflection.macro
+          when :belongs_to
+            associated = object.public_send name
+            resource_url_for(associated, parent: nil) if associated
+          when :has_one
+            associated = object.public_send name
+            resource_url_for(associated, parent: object, association: name)
+          when :has_many
+            resource_url_for(reflection.klass, parent: object, association: name)
+          end
+        end
+
+        def raise_unknown_association(name)
+          raise ArgumentError, "unknown association #{object.class}##{name} defined in #permitted_associations"
+        end
+
+        def raise_unregistered_association(name, reflection)
+          raise ArgumentError, "#{object.class}##{name} defined in #permitted_associations, but #{reflection.klass} is not a registered resource"
+        end
+
         def render_resource_field(name)
           when_permitted(name) do
             # field :name, as: :string