plutonium 0.50.0 → 0.52.0

data/lib/plutonium/definition/{views.rb → index_views.rb}

@@ -7,17 +7,15 @@ module Plutonium
     #
     # @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]
     #     )
+    #     default_index_view :grid
     #   end
-    module Views
+    module IndexViews
       extend ActiveSupport::Concern
 
       KNOWN_VIEWS = %i[table grid].freeze
@@ -25,8 +23,8 @@ module Plutonium
       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_index_views, default: [:table], instance_accessor: false
+        class_attribute :defined_default_index_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
@@ -34,37 +32,40 @@ module Plutonium
 
       class_methods do
         # Declares the index views this resource supports.
+        # Usually unnecessary — declaring `grid_fields` auto-enables :grid
+        # alongside the default :table. Use `index_views` only to disable
+        # one (e.g. `index_views :grid` to drop the table view).
         # @param list [Array<Symbol>] one or more of {KNOWN_VIEWS}
-        def views(*list)
+        def index_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
+          raise ArgumentError, "Unknown index_views: #{invalid.inspect}. Valid: #{KNOWN_VIEWS}" if invalid.any?
+          self.defined_index_views = list.empty? ? [:table] : list
         end
 
-        # Declares the default index view. Must be one of {.views}.
+        # Declares the default index view. Must be one of {.index_views}.
         # Falls back to the first declared view if unset.
-        def default_view(name = nil)
+        def default_index_view(name = nil)
           if name.nil?
-            defined_default_view || defined_views.first
+            defined_default_index_view || defined_index_views.first
           else
             name = name.to_sym
-            unless defined_views.include?(name)
-              raise ArgumentError, "default_view #{name.inspect} not in views #{defined_views.inspect}"
+            unless defined_index_views.include?(name)
+              raise ArgumentError, "default_index_view #{name.inspect} not in index_views #{defined_index_views.inspect}"
             end
-            self.defined_default_view = name
+            self.defined_default_index_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.
+        # adds `:grid` to {.index_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)
+          self.defined_index_views = defined_index_views + [:grid] unless defined_index_views.include?(:grid)
         end
 
         # Layout shape for grid cards. :compact (default) places the image
@@ -84,8 +85,8 @@ module Plutonium
         end
       end
 
-      def defined_views = self.class.defined_views
-      def default_view = self.class.default_view
+      def defined_index_views = self.class.defined_index_views
+      def default_index_view = self.class.default_index_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

data/lib/plutonium/helpers/turbo_helper.rb

@@ -5,9 +5,39 @@ 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(Plutonium::REMOTE_MODAL_FRAME, &)
       end
+
+      # Returns a turbo-frame-scoped element id. Two identically-named forms
+      # can be on the page simultaneously (e.g. a primary modal opens a
+      # secondary modal, each rendering an `id="resource-form"`). When the
+      # server later replies with `turbo_stream.replace("resource-form", ...)`,
+      # Turbo would pick the FIRST element matching the id — which is rarely
+      # the one the user actually submitted. Append a frame suffix so each
+      # frame's form has a unique id and the controller can target precisely.
+      #
+      # @param base [String, Symbol] the base id
+      # @return [String] the scoped id (no suffix outside any modal frame)
+      def turbo_scoped_dom_id(base)
+        base = base.to_s
+        case current_turbo_frame
+        when Plutonium::REMOTE_MODAL_FRAME then "#{base}-primary"
+        when Plutonium::REMOTE_MODAL_SECONDARY_FRAME then "#{base}-secondary"
+        else base
+        end
+      end
     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/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

@@ -53,12 +53,12 @@ module Plutonium
 
           respond_to do |format|
             if params[:pre_submit]
-              format.turbo_stream { render turbo_stream: turbo_stream.replace("resource-form", view_context.render(build_form(action: :new))) }
+              format.turbo_stream { render turbo_stream: turbo_stream.replace(helpers.turbo_scoped_dom_id("resource-form"), view_context.render(build_form(action: :new))) }
               format.html { render :new, status: :unprocessable_content }
             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,
@@ -71,7 +71,7 @@ module Plutonium
                   location: redirect_url_after_submit
               end
             else
-              format.turbo_stream { render turbo_stream: turbo_stream.replace("resource-form", view_context.render(build_form(action: :new))), status: :unprocessable_content }
+              format.turbo_stream { render turbo_stream: turbo_stream.replace(helpers.turbo_scoped_dom_id("resource-form"), view_context.render(build_form(action: :new))), status: :unprocessable_content }
               format.html { render :new, status: :unprocessable_content }
               format.any do
                 @errors = resource_record!.errors
@@ -100,7 +100,7 @@ module Plutonium
 
           respond_to do |format|
             if params[:pre_submit]
-              format.turbo_stream { render turbo_stream: turbo_stream.replace("resource-form", view_context.render(build_form(action: :edit))) }
+              format.turbo_stream { render turbo_stream: turbo_stream.replace(helpers.turbo_scoped_dom_id("resource-form"), view_context.render(build_form(action: :edit))) }
               format.html { render :edit, status: :unprocessable_content }
             elsif resource_record!.save
               format.turbo_stream do
@@ -116,7 +116,7 @@ module Plutonium
                 render :show, status: :ok, location: redirect_url_after_submit
               end
             else
-              format.turbo_stream { render turbo_stream: turbo_stream.replace("resource-form", view_context.render(build_form(action: :edit))), status: :unprocessable_content }
+              format.turbo_stream { render turbo_stream: turbo_stream.replace(helpers.turbo_scoped_dom_id("resource-form"), view_context.render(build_form(action: :edit))), status: :unprocessable_content }
               format.html { render :edit, status: :unprocessable_content }
               format.any do
                 @errors = resource_record!.errors
@@ -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/interactive_actions.rb

@@ -38,7 +38,7 @@ module Plutonium
 
           if params[:pre_submit]
             respond_to do |format|
-              format.turbo_stream { render turbo_stream: turbo_stream.replace("interaction-form", view_context.render(@interaction.build_form)) }
+              format.turbo_stream { render turbo_stream: turbo_stream.replace(helpers.turbo_scoped_dom_id("interaction-form"), view_context.render(@interaction.build_form)) }
               format.html { render :interactive_record_action, formats: [:html], status: :unprocessable_content }
             end
             return
@@ -87,7 +87,7 @@ module Plutonium
 
           if params[:pre_submit]
             respond_to do |format|
-              format.turbo_stream { render turbo_stream: turbo_stream.replace("interaction-form", view_context.render(@interaction.build_form)) }
+              format.turbo_stream { render turbo_stream: turbo_stream.replace(helpers.turbo_scoped_dom_id("interaction-form"), view_context.render(@interaction.build_form)) }
               format.html { render :interactive_resource_action, status: :unprocessable_content }
             end
             return
@@ -134,7 +134,7 @@ module Plutonium
 
           if params[:pre_submit]
             respond_to do |format|
-              format.turbo_stream { render turbo_stream: turbo_stream.replace("interaction-form", view_context.render(@interaction.build_form)) }
+              format.turbo_stream { render turbo_stream: turbo_stream.replace(helpers.turbo_scoped_dom_id("interaction-form"), view_context.render(@interaction.build_form)) }
               format.html { render :interactive_bulk_action, formats: [:html], status: :unprocessable_content }
             end
             return

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/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/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/ui/component/methods.rb

@@ -40,10 +40,15 @@ module Plutonium
           :current_user,
           :current_parent,
           :current_definition,
+          :resource_definition,
           :current_query_object,
           :raw_resource_query_params,
           :current_policy,
           :current_turbo_frame,
+          :in_frame?,
+          :in_modal?,
+          :in_secondary_modal?,
+          :turbo_scoped_dom_id,
           :current_interactive_action,
           :current_engine,
           :policy_for,

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

@@ -66,6 +66,10 @@ module Plutonium
             create_component(Components::KeyValueStore, :key_value_store, **, &)
           end
 
+          def json_input_tag(**, &)
+            create_component(Components::Json, :json, **, &)
+          end
+
           def resource_select_tag(**attributes, &)
             attributes[:data_controller] = tokens(attributes[:data_controller], "slim-select")
             # class!: "" clears the underlying <select>'s themed classes
@@ -107,8 +111,8 @@ module Plutonium
           alias_method :date_tag, :flatpickr_tag
           alias_method :time_tag, :flatpickr_tag
           alias_method :rich_text_tag, :markdown_tag
-          alias_method :json_tag, :textarea_tag
-          alias_method :jsonb_tag, :textarea_tag
+          alias_method :json_tag, :json_input_tag
+          alias_method :jsonb_tag, :json_input_tag
           alias_method :hstore_tag, :key_value_store_tag
           alias_method :key_value_tag, :key_value_store_tag
           alias_method :association_tag, :secure_association_tag
@@ -145,9 +149,25 @@ module Plutonium
         def initialize_attributes
           super
 
-          attributes[:id] ||= :resource_form
+          attributes[:id] ||= "resource-form"
           attributes["data-controller"] = "form"
         end
+
+        # Scope the form id to the current turbo frame at render time (we
+        # can't do this in `initialize_attributes` — Phlex hasn't started
+        # rendering yet, so `view_context` and the request headers aren't
+        # accessible). Primary and secondary modals can each host a form
+        # without colliding on document-level turbo-stream `replace target=`
+        # lookups. See Helpers::TurboHelper#turbo_scoped_dom_id.
+        #
+        # Also force-replace the id (Phlexi's `mix` would otherwise prepend
+        # `@namespace.dom_id`, producing space-separated ids like
+        # "q filter-form" which break document.getElementById lookups).
+        def form_attributes
+          attrs = super
+          attrs[:id] = turbo_scoped_dom_id(attributes[:id]) if attributes[:id]
+          attrs
+        end
       end
     end
   end

data/lib/plutonium/ui/form/components/json.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Plutonium
+  module UI
+    module Form
+      module Components
+        # Textarea-based input for `json` / `jsonb` columns.
+        #
+        # On render, serializes Hash/Array values to pretty JSON so users see
+        # valid JSON instead of Ruby `Hash#to_s` output (e.g. `{:k=>"v"}`).
+        # Strings are pretty-formatted if parseable, passed through verbatim
+        # otherwise — preserves an in-progress edit on form re-render.
+        #
+        # On submit, accepts either a JSON string (typed input) or a raw
+        # Hash/Array (e.g. a JSON-bodied API request that Rails has already
+        # parsed into params). Unparseable strings are passed through so model
+        # validation can surface the error, rather than being silently dropped.
+        class Json < Phlexi::Form::Components::Textarea
+          def view_template
+            textarea(**attributes) { serialized_value }
+          end
+
+          protected
+
+          def serialized_value
+            case (raw = field.value)
+            when nil then ""
+            when String then format_string(raw)
+            else JSON.pretty_generate(raw)
+            end
+          end
+
+          def format_string(str)
+            JSON.pretty_generate(JSON.parse(str))
+          rescue JSON::ParserError
+            str
+          end
+
+          def normalize_input(input_value)
+            case input_value
+            when nil then nil
+            when Hash, Array then input_value
+            when "" then nil
+            else
+              begin
+                JSON.parse(input_value)
+              rescue JSON::ParserError
+                input_value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end