plutonium 0.49.1 → 0.51.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/helpers/turbo_helper.rb

@@ -5,8 +5,19 @@ module Plutonium
         request.headers["Turbo-Frame"]
       end
 
+      # True when the request is rendered inside any turbo frame.
+      def in_frame? = current_turbo_frame.present?
+
+      # True when the request is rendered inside either modal frame
+      # (primary or secondary).
+      def in_modal? = Plutonium::MODAL_FRAMES.include?(current_turbo_frame)
+
+      # True when the request is rendered inside the secondary (stacked)
+      # modal frame specifically.
+      def in_secondary_modal? = current_turbo_frame == Plutonium::REMOTE_MODAL_SECONDARY_FRAME
+
       def remote_modal_frame_tag(&)
-        turbo_frame_tag("remote_modal", &)
+        turbo_frame_tag(Plutonium::REMOTE_MODAL_FRAME, &)
       end
     end
   end

data/lib/plutonium/helpers/turbo_stream_actions_helper.rb

@@ -9,6 +9,20 @@ module Plutonium
         end
       end
 
+      # Closes the <dialog> inside the targeted frame and empties the
+      # frame. Used to dismiss a stacked modal without affecting the
+      # rest of the page.
+      def turbo_stream_close_frame(frame_id)
+        turbo_stream_action_tag :close_frame, target: frame_id
+      end
+
+      # Reloads the targeted frame from its current src. Used to refresh
+      # the primary modal after a secondary-modal action mutates data
+      # the primary depends on.
+      def turbo_stream_reload_frame(frame_id)
+        turbo_stream_action_tag :reload_frame, target: frame_id
+      end
+
       private
 
       def turbo_stream_redirect_same_page?(url)

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

@@ -15,6 +15,7 @@ module Plutonium
       include Plutonium::Resource::Controllers::Queryable
       include Plutonium::Resource::Controllers::CrudActions
       include Plutonium::Resource::Controllers::InteractiveActions
+      include Plutonium::Resource::Controllers::Typeahead
 
       included do
         after_action { response.headers.merge!(@pagy.headers_hash) if @pagy }

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

@@ -58,7 +58,7 @@ module Plutonium
             elsif resource_record!.save
               format.turbo_stream do
                 flash.notice = "#{resource_class.model_name.human} was successfully created."
-                render turbo_stream: helpers.turbo_stream_redirect(redirect_url_after_submit)
+                render turbo_stream: stacked_modal_create_streams
               end
               format.html do
                 redirect_to redirect_url_after_submit,
@@ -164,6 +164,24 @@ module Plutonium
 
         private
 
+        # When the create came in through the secondary (stacked) modal
+        # frame — i.e. the user clicked "+" next to an association field
+        # while the parent form was already in a modal — we don't want to
+        # navigate anywhere. Close the secondary dialog and reload the
+        # primary modal frame so the just-created record appears in the
+        # association select. Outside that case fall back to the normal
+        # post-submit redirect.
+        def stacked_modal_create_streams
+          if helpers.in_secondary_modal?
+            [
+              helpers.turbo_stream_close_frame(Plutonium::REMOTE_MODAL_SECONDARY_FRAME),
+              helpers.turbo_stream_reload_frame(Plutonium::REMOTE_MODAL_FRAME)
+            ]
+          else
+            helpers.turbo_stream_redirect(redirect_url_after_submit)
+          end
+        end
+
         def redirect_url_after_submit
           if (return_to = url_from(params[:return_to]))
             return return_to

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/controllers/typeahead.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Resource
+    module Controllers
+      # Backend dispatch for typeahead/autocomplete queries against
+      # resource form inputs and index filter inputs. Auto-mounted on
+      # every Plutonium resource via the `interactive_resource_actions`
+      # routing concern (see Plutonium::Routing::MapperExtensions).
+      #
+      # The controller resolves what to query directly from the input
+      # definition + the model's association reflection — no widget
+      # indirection. Two source kinds are supported:
+      #
+      #   1. Static `choices: [...]` — case-insensitive substring filter.
+      #   2. Association — either `association_class:` set on the input,
+      #      or inferred from `resource_class.reflect_on_association(name)`.
+      #
+      # Association queries route through the associated resource's
+      # `policy.relation_scope` so users only see records they can read.
+      module Typeahead
+        extend ActiveSupport::Concern
+
+        TYPEAHEAD_LIMIT = 50
+
+        # Priority list tried when the input doesn't tell us which
+        # column carries its label. Aligns with what `to_label` usually
+        # wraps. Used only as a last resort.
+        FALLBACK_SEARCH_COLUMNS = %w[name title label slug display_name email].freeze
+
+        # Returns the column to LIKE against when no `search` block is
+        # defined. Used by both the server (to build the WHERE clause)
+        # and the input component (to decide whether to attach the
+        # typeahead URL).
+        #
+        # Resolution order:
+        # 1. The input's `label_method` if it names a real column (so
+        #    `input :user, label_method: :email` just works).
+        # 2. The first match from FALLBACK_SEARCH_COLUMNS.
+        # 3. nil — no usable column, server returns unfiltered.
+        #
+        # The fallback is fine for moderate tables but uses a leading-
+        # wildcard LIKE which can't be served by a b-tree index. For
+        # large tables, declare a `search` block that uses a trigram or
+        # full-text index instead.
+        def self.searchable_column_for(klass, label_method: nil)
+          cols = klass.column_names
+          if label_method && cols.include?(label_method.to_s)
+            return label_method.to_s
+          end
+          FALLBACK_SEARCH_COLUMNS.find { |c| cols.include?(c) }
+        end
+
+        # Escapes the SQL LIKE wildcards `%` and `_` (plus the escape
+        # char itself) so a user searching for "100%" doesn't match
+        # everything. The literal `!` is used as the ESCAPE character —
+        # unambiguous across sqlite/postgres/mysql, no backslash-quoting
+        # surprises.
+        LIKE_ESCAPE_CHAR = "!"
+        def self.escape_like(value)
+          value.to_s.gsub(/[!%_]/) { |c| "#{LIKE_ESCAPE_CHAR}#{c}" }
+        end
+
+        included do
+          before_action :authorize_typeahead!, only: %i[typeahead_input typeahead_filter]
+          # Read-only JSON; row-level auth is enforced inline through
+          # authorized_resource_scope, so the after_action verifier is
+          # redundant.
+          skip_verify_current_authorized_scope only: %i[typeahead_input typeahead_filter]
+        end
+
+        # GET /<resource>/typeahead/input/:name?q=...
+        def typeahead_input
+          field_name = params[:name].to_sym
+          defn = current_definition.defined_inputs[field_name]
+          # Inputs are often inferred from the model (no explicit
+          # `input :foo` in the definition). Accept the request when the
+          # field name maps to a real association even without an entry.
+          unless defn || resource_class.reflect_on_association(field_name)
+            return head(:not_found)
+          end
+
+          render_typeahead_response(defn || {}, field_name)
+        end
+
+        # GET /<resource>/typeahead/filter/:name?q=...
+        def typeahead_filter
+          filter = current_query_object.filter_definitions[params[:name].to_sym]
+          return head(:not_found) unless filter
+
+          defn = filter.defined_inputs[:value]
+          return head(:not_found) unless defn
+
+          render_typeahead_response(defn, params[:name].to_sym)
+        end
+
+        private
+
+        def render_typeahead_response(defn, field_name)
+          options = defn[:options] || {}
+          query = params[:q].to_s
+          candidates = collect_typeahead_candidates(options, field_name, query)
+
+          if candidates.nil?
+            return render(json: {error: "input has no typeahead source"}, status: :bad_request)
+          end
+
+          has_more = candidates.length > TYPEAHEAD_LIMIT
+          results = candidates.first(TYPEAHEAD_LIMIT).map { |row| serialize_typeahead_row(row) }
+          render json: {results: results, has_more: has_more}
+        end
+
+        # Returns the candidate list, or nil if the input has neither
+        # static choices nor a resolvable association class.
+        def collect_typeahead_candidates(options, field_name, query)
+          if options[:choices]
+            filter_static_choices(options[:choices], query)
+          elsif (klass = typeahead_association_class(options, field_name))
+            filter_association(klass, query, options)
+          end
+        end
+
+        def typeahead_association_class(options, field_name)
+          options[:association_class] ||
+            resource_class.reflect_on_association(field_name)&.klass
+        end
+
+        def filter_static_choices(choices, query)
+          return choices if query.blank?
+          q = query.downcase
+          choices.select { |label, _| label.to_s.downcase.include?(q) }
+        end
+
+        # Routes through the associated resource's policy.relation_scope
+        # so typeahead never surfaces records the user can't read, then
+        # narrows via the associated resource definition's `search` block
+        # when present. Without a search block, fall back to a case-
+        # insensitive LIKE on the first column in FALLBACK_SEARCH_COLUMNS
+        # that exists on the model (so a resource with a `name` column
+        # gets useful typeahead without declaring `search`). If neither
+        # search block nor fallback column is available, the relation is
+        # returned unfiltered (capped).
+        def filter_association(klass, query, options)
+          relation = options[:skip_authorization] ? klass.all : authorized_resource_scope(klass)
+          if query.present?
+            if (search_block = associated_definition_search_block(klass))
+              relation = search_block.call(relation, query)
+            elsif (col = Typeahead.searchable_column_for(klass, label_method: options[:label_method]))
+              quoted = klass.connection.quote_column_name(col)
+              pattern = "%#{Typeahead.escape_like(query.downcase)}%"
+              relation = relation.where("LOWER(#{quoted}) LIKE ? ESCAPE '#{Typeahead::LIKE_ESCAPE_CHAR}'", pattern)
+            end
+          end
+          relation.limit(Typeahead::TYPEAHEAD_LIMIT + 1).to_a
+        end
+
+        # Resolves the associated resource's `search` block, if declared.
+        # Goes through `resource_definition` so portal/package namespacing
+        # is honored (same fallback chain as the rest of the controller).
+        def associated_definition_search_block(klass)
+          resource_definition(klass).class._search_definition
+        rescue NameError
+          nil
+        end
+
+        def serialize_typeahead_row(row)
+          if row.is_a?(Array)
+            {value: row[1].to_s, label: row[0].to_s}
+          else
+            {value: row.to_signed_global_id.to_s, label: row.to_label}
+          end
+        end
+
+        def authorize_typeahead!
+          authorize_current! resource_class, to: :typeahead?
+        end
+      end
+    end
+  end
+end

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

@@ -179,6 +179,13 @@ module Plutonium
         index?
       end
 
+      # Checks if typeahead/autocomplete queries are permitted.
+      #
+      # @return [Boolean] Delegates to index?.
+      def typeahead?
+        index?
+      end
+
       # Core attributes
 
       # Returns the permitted attributes for the create action.

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/routing/mapper_extensions.rb

@@ -41,6 +41,7 @@ module Plutonium
         concern :interactive_resource_actions do
           define_member_interactive_actions
           define_collection_interactive_actions
+          define_collection_typeahead_actions
         end
       end
 
@@ -161,6 +162,20 @@ module Plutonium
             as: :commit_interactive_resource_action
         end
       end
+
+      # Defines collection-level typeahead actions for resource form inputs
+      # and index filter inputs. Auto-mounted alongside record_actions and
+      # bulk_actions on every Plutonium resource.
+      #
+      # @return [void]
+      def define_collection_typeahead_actions
+        collection do
+          get "typeahead/input/:name", action: :typeahead_input,
+            as: :typeahead_input
+          get "typeahead/filter/:name", action: :typeahead_filter,
+            as: :typeahead_filter
+        end
+      end
     end
   end
 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,