plutonium 0.62.2 → 0.64.0

data/lib/plutonium/routing/mapper_extensions.rb

@@ -5,6 +5,21 @@ module Plutonium
     # Prefix used for nested resource routes to disambiguate from user-defined routes
     NESTED_ROUTE_PREFIX = "nested_"
 
+    # Route default naming which nesting a request arrived through.
+    #
+    # The router already knows which nested route matched; without this the
+    # controller has to work it back out — reading an *_id parameter to find the
+    # parent, and scanning the path for a "nested_" segment to find the
+    # association. Neither survives a parent that contributes no id (a singular
+    # parent has none), and both are guesses about something the route could
+    # simply state.
+    #
+    # The value is the key into resource_route_config_lookup, which already
+    # holds the parent class and the association name. Carrying the key rather
+    # than the names themselves means nothing has to be looked up by string at
+    # request time.
+    NESTED_KEY_PARAM = :pu_nested_key
+
     # MapperExtensions module provides additional functionality for route mapping in Plutonium applications.
     #
     # This module extends the functionality of Rails' routing mapper to support Plutonium-specific features,
@@ -19,6 +34,10 @@ module Plutonium
       #
       # @param resource [Class] The resource class to be registered.
       # @param options [Hash] Additional options for resource registration.
+      # @option options [Array<Symbol>] :associations the associations to draw
+      #   nested routes for. Omit to draw one for every routable association, or
+      #   set +Plutonium.configuration.nested_association_routes = :declared+ to
+      #   make omitting it mean none.
       # @yield An optional block for additional resource configuration.
       # @return [void]
       def register_resource(resource, options = {}, &)
@@ -86,7 +105,7 @@ module Plutonium
         concern route_config[:concern_name] do
           send route_config[:route_type], route_config[:route_name], **route_config[:route_options] do
             instance_exec(&route_config[:block]) if route_config[:block]
-            define_nested_resource_routes(resource)
+            define_nested_resource_routes(resource, route_config[:associations])
           end
         end
       end
@@ -94,12 +113,21 @@ module Plutonium
       # Defines nested resource routes for a given resource.
       #
       # @param resource [Class] The parent resource class.
+      # @param declared [Array<Symbol>, nil] the associations named by
+      #   register_resource, or nil when it named none.
       # @return [void]
-      def define_nested_resource_routes(resource)
+      def define_nested_resource_routes(resource, declared = nil)
+        allowed = nested_route_associations(resource, declared)
+
         # has_many associations use plural routes
         resource.routable_has_many_associations.each do |assoc_info|
+          next if allowed && !allowed.include?(assoc_info[:name])
+
           base_config = route_set.resource_route_config_for(assoc_info[:plural])[0]
-          next unless base_config
+          unless base_config
+            raise_unregistered_nested_association(resource, assoc_info) if declared
+            next
+          end
 
           # Register with association-based key: "parent_plural/association_name"
           # Force route_type: :resources — has_many associations always nest as a
@@ -110,30 +138,41 @@ module Plutonium
           nested_config = base_config.merge(
             route_type: :resources,
             association_name: assoc_info[:name],
-            resource_class: assoc_info[:klass]
+            resource_class: assoc_info[:klass],
+            parent_class: resource
           )
           route_set.resource_route_config_lookup[nested_key] = nested_config
 
-          resources "#{NESTED_ROUTE_PREFIX}#{assoc_info[:name]}", **base_config[:route_options].except(:path) do
+          resources "#{NESTED_ROUTE_PREFIX}#{assoc_info[:name]}",
+            **base_config[:route_options].except(:path),
+            defaults: {NESTED_KEY_PARAM => nested_key} do
             instance_exec(&base_config[:block]) if base_config[:block]
           end
         end
 
         # has_one associations use singular routes
         resource.routable_has_one_associations.each do |assoc_info|
+          next if allowed && !allowed.include?(assoc_info[:name])
+
           base_config = route_set.resource_route_config_for(assoc_info[:plural])[0]
-          next unless base_config
+          unless base_config
+            raise_unregistered_nested_association(resource, assoc_info) if declared
+            next
+          end
 
           # Register with association-based key and singular route type
           nested_key = "#{resource.model_name.plural}/#{assoc_info[:name]}"
           nested_config = base_config.merge(
             route_type: :resource,
             association_name: assoc_info[:name],
-            resource_class: assoc_info[:klass]
+            resource_class: assoc_info[:klass],
+            parent_class: resource
           )
           route_set.resource_route_config_lookup[nested_key] = nested_config
 
-          resource "#{NESTED_ROUTE_PREFIX}#{assoc_info[:name]}", **base_config[:route_options].except(:path) do
+          resource "#{NESTED_ROUTE_PREFIX}#{assoc_info[:name]}",
+            **base_config[:route_options].except(:path),
+            defaults: {NESTED_KEY_PARAM => nested_key} do
             original_collection = method(:collection)
             define_singleton_method(:collection) { |&_| } # no-op for singular resources
             instance_exec(&base_config[:block]) if base_config[:block]
@@ -142,6 +181,51 @@ module Plutonium
         end
       end
 
+      # The associations a parent may draw nested routes for.
+      #
+      # nil means every routable association, which is what `:detected` does for
+      # a registration that named none. An array is a closed list, and an empty
+      # one is a real answer: `:declared` with nothing named draws nothing.
+      #
+      # A declared name that is not a routable association fails the boot. The
+      # whole point of naming them is to stop guessing which routes exist, so a
+      # typo that silently draws one route fewer would defeat it.
+      #
+      # @param resource [Class] The parent resource class.
+      # @param declared [Array<Symbol>, nil] the associations named at registration.
+      # @return [Array<Symbol>, nil]
+      # @raise [ArgumentError] if a declared name is not a routable association.
+      def nested_route_associations(resource, declared)
+        if declared.nil?
+          return nil if Plutonium.configuration.nested_association_routes == :detected
+
+          return []
+        end
+
+        routable = (resource.routable_has_many_associations +
+                    resource.routable_has_one_associations).map { |info| info[:name] }
+        unknown = declared - routable
+        if unknown.any?
+          raise ArgumentError,
+            "#{resource} is registered with `associations: #{declared.inspect}`, but " \
+            "#{unknown.map(&:inspect).join(", ")} #{(unknown.size == 1) ? "is not a" : "are not"} " \
+            "routable #{"association".pluralize(unknown.size)} on it. " \
+            "Available: #{routable.empty? ? "(none)" : routable.map(&:inspect).join(", ")}. " \
+            "Nested routes are drawn for has_many and has_one only."
+        end
+
+        declared
+      end
+
+      # @raise [ArgumentError] always
+      def raise_unregistered_nested_association(resource, assoc_info)
+        raise ArgumentError,
+          "#{resource} declares `associations: [:#{assoc_info[:name]}]`, but " \
+          "#{assoc_info[:klass]} is not registered in this portal, so there is no " \
+          "route to nest under it. Add `register_resource #{assoc_info[:klass]}` " \
+          "alongside it, or drop :#{assoc_info[:name]} from the list."
+      end
+
       # Defines member-level interactive actions.
       #
       # @return [void]
@@ -153,6 +237,10 @@ module Plutonium
             as: :commit_interactive_record_action
           get "kanban_move_form", action: :kanban_move_form, as: :kanban_move_form
           post "kanban_move", action: :kanban_move, as: :kanban_move
+          # Drag-reorder drop target for table/grid surfaces. Mounted on every
+          # resource (like the kanban routes above); resources whose definition
+          # declares no `position_on` answer it with a 404.
+          post "reposition", action: :reposition, as: :reposition
         end
       end
 
@@ -205,6 +293,8 @@ module Plutonium
             as: :wizard_record_action
           post "wizards/:wizard_name(/:token)/:step", action: :commit_wizard_record_action,
             as: :commit_wizard_record_action
+          delete "wizards/:wizard_name(/:token)", action: :cancel_wizard_record_action,
+            as: :cancel_wizard_record_action
         end
       end
 
@@ -225,6 +315,8 @@ module Plutonium
             as: :wizard_resource_action
           post "wizards/:wizard_name(/:token)/:step", action: :commit_wizard_resource_action,
             as: :commit_wizard_resource_action
+          delete "wizards/:wizard_name(/:token)", action: :cancel_wizard_resource_action,
+            as: :cancel_wizard_resource_action
         end
       end
 

data/lib/plutonium/routing/route_set_extensions.rb

@@ -151,8 +151,22 @@ module Plutonium
           route_type: options[:singular] ? :resource : :resources,
           route_name: route_name,
           concern_name: concern_name,
+          # The associations this resource draws nested routes for, or nil when
+          # the registration named none. nil is not "no associations": what
+          # silence means is decided by
+          # Plutonium.configuration.nested_association_routes.
+          associations: options[:associations]&.map(&:to_sym),
           route_options: {
-            controller: resource.to_s.pluralize.underscore,
+            # model_name.collection, not resource.to_s.pluralize.underscore:
+            # the latter reads the RAW class name, ignoring a model that pins
+            # its own model_name to escape it — which is exactly what
+            # Plutonium::Interaction::Async::Run does, precisely so a namespace this
+            # deep inside the gem's own module doesn't leak into every URL and
+            # controller path. For every resource that does NOT override
+            # model_name, .collection derives the identical path .pluralize.underscore
+            # would have (verified: both give "blogging/posts" for Blogging::Post).
+            # `controller:` remains available to override either way.
+            controller: options[:controller] || resource.model_name.collection,
             path: options[:singular] ? resource.model_name.singular : resource.model_name.collection,
             concerns: %i[interactive_resource_actions]
           },

data/lib/plutonium/routing/wizard_registration.rb

@@ -109,6 +109,8 @@ module Plutonium
             as: :"#{helper_name}_wizard", defaults: defaults
           post "(/:token)/:step", to: "#{WIZARD_CONTROLLER_NAME}#update",
             defaults: defaults
+          delete "(/:token)", to: "#{WIZARD_CONTROLLER_NAME}#cancel",
+            as: :"#{helper_name}_wizard_cancel", defaults: defaults
         end
       end
 
@@ -174,6 +176,8 @@ module Plutonium
               as: :"#{helper_name}_wizard", defaults: defaults
             post "(/:token)/:step", to: "public_wizards#update",
               defaults: defaults
+            delete "(/:token)", to: "public_wizards#cancel",
+              as: :"#{helper_name}_wizard_cancel", defaults: defaults
           end
         end
       end

data/lib/plutonium/testing/resource_policy.rb

@@ -24,7 +24,11 @@ module Plutonium
             matrix.each do |action, allowed_roles|
               roles.each do |role_sym, account_proc|
                 account = instance_exec(&account_proc)
-                policy = policy_klass.new(record: record, user: account, **policy_context)
+                # The record MUST be positional. ActionPolicy::Policy::Core#initialize is
+                # `def initialize(record = nil, *)`, so a `record:` keyword is swallowed by
+                # the splat and `record` stays nil — every record-dependent predicate would
+                # then be asserted against nil.
+                policy = policy_klass.new(record, user: account, **policy_context)
                 expected = allowed_roles.include?(role_sym)
                 actual = policy.public_send("#{action}?")
                 assert_equal expected, actual,
@@ -38,7 +42,7 @@ module Plutonium
             policy_klass = policy_class_for(record)
             policy_roles.each do |role_sym, account_proc|
               account = instance_exec(&account_proc)
-              policy = policy_klass.new(record: record.class, user: account, **policy_context)
+              policy = policy_klass.new(record.class, user: account, **policy_context)
               scope = policy.apply_scope(record.class.all, type: :active_record_relation)
               assert_kind_of ActiveRecord::Relation, scope, "relation_scope must return AR::Relation for #{role_sym}"
             end

data/lib/plutonium/ui/action_button.rb

@@ -49,8 +49,10 @@ module Plutonium
       def render_link
         link_to(
           url_with_return_to,
-          class: button_classes,
-          data: {turbo_frame: @action.turbo_frame(current_definition)}.merge(@extra_data)
+          @action.link_attributes({
+            class: button_classes,
+            data: {turbo_frame: @action.turbo_frame(current_definition)}.merge(@extra_data)
+          })
         ) do
           render_button_content
         end
@@ -63,13 +65,13 @@ module Plutonium
           name: :return_to, value: return_to_url,
           class: "inline-block",
           data: @extra_data,
-          form: {
+          form: @action.button_attributes({
             data: {
               turbo: @action.turbo,
               turbo_confirm: @action.confirmation.presence,
               turbo_frame: @action.turbo_frame(current_definition)
             }
-          }
+          })
         ) do
           span(class: button_classes) do
             render_button_content
@@ -94,8 +96,8 @@ module Plutonium
           link_attrs[:data][:turbo_confirm] = @action.confirmation if @action.confirmation
         end
 
-        a(**link_attrs) do
-          render @action.icon.new(class: "w-4 h-4") if @action.icon
+        a(**@action.link_attributes(link_attrs)) do
+          render @action.icon.new(class: "w-4 h-4 shrink-0") if @action.icon
           span { @action.label }
         end
       end
@@ -157,7 +159,10 @@ module Plutonium
         if current_turbo_frame && current_parent
           resource_url_for(current_parent, parent: nil)
         else
-          request.original_url
+          # current_page_url, not request.original_url: a button re-rendered by
+          # a stream-producing POST (the reposition drop) must return the user
+          # to the page they are on, never to that POST-only endpoint.
+          current_page_url
         end
       end
 

data/lib/plutonium/ui/actions_dropdown.rb

@@ -34,7 +34,7 @@ module Plutonium
 
       def render_dropdown_menu
         div(
-          class: "hidden absolute right-0 z-50 mt-2 w-48 origin-top-right bg-[var(--pu-surface)] border border-[var(--pu-border)] rounded-[var(--pu-radius-lg)] overflow-hidden",
+          class: "hidden absolute right-0 z-50 mt-2 w-max min-w-48 max-w-[min(20rem,90vw)] origin-top-right bg-[var(--pu-surface)] border border-[var(--pu-border)] rounded-[var(--pu-radius-lg)] overflow-hidden",
           style: "box-shadow: var(--pu-shadow-lg)",
           data: {resource_drop_down_target: "menu"}
         ) do

data/lib/plutonium/ui/block.rb

@@ -1,10 +1,30 @@
 module Plutonium
   module UI
+    # A plain card surface to wrap arbitrary content in.
+    #
+    # This is THE card primitive — it renders `pu-card` rather than hand-rolling
+    # a surface. It used to paint its own background, radius and
+    # `--pu-shadow-md` inline, which left it subtly out of step with every
+    # `pu-card` on the page: no border, and a heavier shadow. Anything wrapping
+    # a `pu-card` in a Block then stacked two cards and got a doubled shadow,
+    # while anything wrapping bare content got a borderless one — which is why
+    # the show page's details and its metadata rail used to sit on visibly
+    # different surfaces.
+    #
+    # It carries no outer margin: spacing between cards belongs to whatever
+    # stacks them (a `space-y-*` container), not to the card itself, so a
+    # single Block can't decide the rhythm of a list it doesn't know it's in.
+    # Extra classes may be merged in (`Block(class: "overflow-hidden")`) so a
+    # caller can adjust the card without re-declaring what a card is.
     class Block < Plutonium::UI::Component::Base
+      def initialize(**options)
+        @class = options[:class]
+      end
+
       def view_template(&)
         raise ArgumentError, "Block requires a content block" unless block_given?
 
-        div class: "relative bg-[var(--pu-surface)] rounded-[var(--pu-radius-lg)] my-3", style: "box-shadow: var(--pu-shadow-md)" do
+        div class: tokens("relative pu-card", @class) do
           yield
         end
       end

data/lib/plutonium/ui/breadcrumbs.rb

@@ -4,17 +4,35 @@ module Plutonium
       include Phlex::Rails::Helpers::ActionName
       include Phlex::Rails::Helpers::LinkTo
 
+      # Shared styling for an inline breadcrumb label.
+      LABEL_CLASSES = "ms-1 md:ms-2 flex items-center min-w-0 text-sm font-medium " \
+                      "text-[var(--pu-text-muted)] transition-colors"
+      LINK_CLASSES = "#{LABEL_CLASSES} hover:text-primary-600"
+
+      # Styling for the same label when it is rendered as a row in the overflow
+      # menu instead of inline. Full-row target, chevron-led to echo the
+      # inline separators.
+      MENU_LINK_CLASSES = "flex items-center gap-1.5 py-1.5 px-3 text-sm text-[var(--pu-text-muted)] " \
+                          "hover:text-[var(--pu-text)] hover:bg-[var(--pu-surface-alt)] transition-colors"
+
+      CHEVRON_INLINE_CLASSES = "rtl:rotate-180 block w-3 h-3 mx-1 shrink-0 text-[var(--pu-text-subtle)]"
+      CHEVRON_MENU_CLASSES = "rtl:rotate-180 block w-3 h-3 shrink-0 text-[var(--pu-text-subtle)]"
+
       def view_template
+        # `overflow-hidden` keeps the un-collapsed trail from spilling in the
+        # instant before the controller's first reflow.
         nav(
-          class: "flex py-3 mb-2",
-          aria_label: "Breadcrumb"
+          class: "flex min-w-0 py-3 mb-2 overflow-hidden",
+          aria_label: "Breadcrumb",
+          data: {controller: "breadcrumbs"}
         ) do
           ol(
-            class: "inline-flex items-center gap-1 md:gap-2"
+            class: "flex flex-nowrap w-full min-w-0 items-center gap-1 md:gap-2",
+            data: {breadcrumbs_target: "list"}
           ) do
             render_dashboard_link
-            render_parent_breadcrumbs if current_parent.present?
-            render_resource_breadcrumbs if resource_record?
+            render_overflow_menu if middle_items.any?
+            render_items
             render_trailing_separator
           end
         end
@@ -22,14 +40,43 @@ module Plutonium
 
       private
 
+      # Every segment between the dashboard link and the trailing separator, as
+      # a list of lambdas taking the CSS classes to render with. Collected up
+      # front so each one can be rendered twice — inline, and again as a row in
+      # the overflow menu that the controller reveals when it folds the inline
+      # twin away.
+      def breadcrumb_items
+        @breadcrumb_items ||= [].tap do |items|
+          collect_parent_breadcrumbs(items) if current_parent.present?
+          collect_resource_breadcrumbs(items) if resource_record?
+        end
+      end
+
+      # The segments eligible to be folded into the overflow menu. The last one
+      # is never foldable — it is the deepest thing the trail knows about, which
+      # is the record on new/edit pages but the resource index on show pages,
+      # where the record itself is not part of the trail at all.
+      def middle_items
+        breadcrumb_items[0...-1]
+      end
+
+      def render_items
+        last_index = breadcrumb_items.size - 1
+        breadcrumb_items.each_with_index do |item, index|
+          render_breadcrumb_item(foldable: index < last_index) do
+            item.call(LINK_CLASSES)
+          end
+        end
+      end
+
       def render_dashboard_link
-        li(class: "inline-flex items-center") do
+        li(class: "flex items-center shrink-0") do
           a(
             href: root_path,
             class: "inline-flex items-center text-sm font-medium text-[var(--pu-text-muted)] hover:text-primary-600 transition-colors"
           ) do
             svg(
-              class: "w-3 h-3 me-2.5",
+              class: "w-3 h-3 shrink-0 sm:me-2.5",
               aria_hidden: "true",
               xmlns: "http://www.w3.org/2000/svg",
               fill: "currentColor",
@@ -40,85 +87,170 @@ module Plutonium
                   "m19.707 9.293-2-2-7-7a1 1 0 0 0-1.414 0l-7 7-2 2a1 1 0 0 0 1.414 1.414L2 10.414V18a2 2 0 0 0 2 2h3a1 1 0 0 0 1-1v-4a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1v4a1 1 0 0 0 1 1h3a2 2 0 0 0 2-2v-7.586l.293.293a1 1 0 0 0 1.414-1.414Z"
               )
             end
-            plain " Dashboard "
+            span(class: "sr-only sm:not-sr-only") { plain "Dashboard" }
           end
         end
       end
 
-      def render_parent_breadcrumbs
-        # Parent Resource
-        render_breadcrumb_item do
-          link_to resource_name_plural(current_parent.class),
-            resource_url_for(current_parent.class, parent: nil),
-            class: "ms-1 text-sm font-medium text-[var(--pu-text-muted)] hover:text-primary-600 md:ms-2 transition-colors"
+      # Builds a segment renderer used in both places a segment can appear:
+      # inline in the trail, and — with `leading:` — as a chevron-led row in
+      # the overflow menu.
+      def segment(label, url = nil)
+        ->(classes, leading: false) {
+          if url
+            link_to(url, class: classes) do
+              render_chevron_separator(CHEVRON_MENU_CLASSES) if leading
+              span(class: "truncate min-w-0") { plain label }
+            end
+          else
+            span(class: classes) do
+              render_chevron_separator(CHEVRON_MENU_CLASSES) if leading
+              span(class: "truncate min-w-0") { plain label }
+            end
+          end
+        }
+      end
+
+      def collect_parent_breadcrumbs(items)
+        # Parent Resource — an index link, where the parent has one. A parent
+        # registered `singular: true` defines no collection route, so asking for
+        # one raises on a helper that was never generated.
+        unless singular_resource_route_for?(current_parent.class)
+          items << segment(
+            resource_name_plural(current_parent.class),
+            resource_url_for(current_parent.class, parent: nil)
+          )
         end
 
         # Parent Itself
-        render_breadcrumb_item do
-          link_to display_name_of(current_parent),
-            resource_url_for(current_parent, parent: nil),
-            class: "ms-1 text-sm font-medium text-[var(--pu-text-muted)] hover:text-primary-600 md:ms-2 transition-colors"
-        end
+        items << segment(
+          display_name_of(current_parent),
+          resource_url_for(current_parent, parent: nil)
+        )
       end
 
-      def render_resource_breadcrumbs
-        is_singular_route = current_engine.routes.resource_route_config_lookup[resource_class.model_name.plural][:route_type] == :resource
-
-        if is_singular_route
-          render_singular_resource_breadcrumb
+      def collect_resource_breadcrumbs(items)
+        # Ask the controller, not the top-level route registry: a has_one
+        # association nests as a singular route regardless of how the child was
+        # registered, and only the controller's config lookup is keyed by
+        # "parent/association" and therefore knows that.
+        if singular_resource_context?
+          collect_singular_resource_breadcrumb(items)
         else
-          render_plural_resource_breadcrumbs
+          collect_plural_resource_breadcrumbs(items)
         end
       end
 
-      def render_singular_resource_breadcrumb
-        render_breadcrumb_item do
-          if resource_record!.persisted? && action_name != "show"
-            link_to resource_name(resource_class),
-              resource_url_for(resource_record!),
-              class: "ms-1 text-sm font-medium text-[var(--pu-text-muted)] hover:text-primary-600 md:ms-2 transition-colors"
-          else
-            span(class: "ms-1 text-sm font-medium text-[var(--pu-text-muted)] md:ms-2") do
-              plain resource_name(resource_class)
-            end
-          end
-        end
+      def collect_singular_resource_breadcrumb(items)
+        # A singular resource has no index, so the only segment it can add is
+        # itself — and on `show` the page title already names it, exactly as the
+        # plural branch omits the record on its own show page.
+        return unless resource_record!.persisted? && action_name != "show"
+
+        items << segment(resource_name(resource_class), resource_url_for(resource_record!))
       end
 
-      def render_plural_resource_breadcrumbs
-        # Resource index link
-        render_breadcrumb_item do
-          link_to nestable_resource_name_plural(resource_class),
-            resource_url_for(resource_class),
-            class: "ms-1 text-sm font-medium text-[var(--pu-text-muted)] hover:text-primary-600 md:ms-2 transition-colors"
-        end
+      def collect_plural_resource_breadcrumbs(items)
+        # No `parent:` here on purpose: Resource::Controller#resource_url_args_for
+        # already defaults it to `current_parent` (and supplies
+        # `current_nested_association` with it), so both links nest themselves
+        # when the request arrived through a nesting. Passing it explicitly reads
+        # like it changes something; it doesn't. The parent segments above pass
+        # `parent: nil` precisely to opt OUT of that default.
+        items << segment(
+          nestable_resource_name_plural(resource_class),
+          resource_url_for(resource_class)
+        )
 
         # Record itself (for non-singular routes only)
         return unless resource_record!.persisted? && action_name != "show"
 
-        render_breadcrumb_item do
-          link_to display_name_of(resource_record!),
-            resource_url_for(resource_record!),
-            class: "ms-1 text-sm font-medium text-[var(--pu-text-muted)] hover:text-primary-600 md:ms-2 transition-colors"
+        items << segment(display_name_of(resource_record!), resource_url_for(resource_record!))
+      end
+
+      # Stands in for whatever the controller folded away, the way GitHub
+      # collapses a long path. Starts hidden — it only earns its place once at
+      # least one segment has actually been folded.
+      def render_overflow_menu
+        li(
+          class: "hidden items-center shrink-0",
+          data: {breadcrumbs_target: "overflow"}
+        ) do
+          render_chevron_separator
+          div(
+            class: "flex items-center",
+            data: {
+              controller: "resource-drop-down",
+              resource_drop_down_placement_value: "bottom-start"
+            }
+          ) do
+            render_overflow_trigger
+            render_overflow_items
+          end
+        end
+      end
+
+      def render_overflow_trigger
+        button(
+          type: "button",
+          aria: {label: "Show collapsed breadcrumbs", haspopup: "true", expanded: "false"},
+          data: {resource_drop_down_target: "trigger"},
+          class: "flex items-center justify-center ms-1 w-6 h-6 rounded-[var(--pu-radius-md)] " \
+                 "text-[var(--pu-text-muted)] hover:text-[var(--pu-text)] hover:bg-[var(--pu-surface-alt)] transition-colors"
+        ) do
+          render Phlex::TablerIcons::Dots.new(class: "w-4 h-4")
+        end
+      end
+
+      # One row per foldable segment. Each starts hidden; the controller reveals
+      # exactly those whose inline twin it folded away.
+      def render_overflow_items
+        div(
+          # No margin here — the dropdown controller already offsets the popper
+          # off its trigger.
+          class: "hidden z-50 py-1 min-w-40 max-w-[70vw] bg-[var(--pu-surface)] " \
+                 "border border-[var(--pu-border)] rounded-[var(--pu-radius-md)] overflow-hidden",
+          style: "box-shadow: var(--pu-shadow-lg)",
+          data: {resource_drop_down_target: "menu"}
+        ) do
+          ul(class: "list-none") do
+            middle_items.each do |item|
+              li(class: "hidden", data: {breadcrumbs_target: "menuItem"}) do
+                item.call(MENU_LINK_CLASSES, leading: true)
+              end
+            end
+          end
         end
       end
 
       def render_trailing_separator
-        li(class: "flex items-center") do
+        li(class: "flex items-center shrink-0") do
           render_chevron_separator
         end
       end
 
-      def render_breadcrumb_item(&)
-        li(class: "flex items-center") do
-          render_chevron_separator
-          yield
+      # Segments are `shrink-0` so the controller measures natural widths and
+      # can detect real overflow. The last one is additionally `min-w-0` so the
+      # controller can drop its `shrink-0` and let it ellipsize once there is
+      # nothing left to fold. Its `last` target must stay in lockstep with
+      # `middle_items` — the controller pairs inline twins to menu rows by index.
+      def render_breadcrumb_item(foldable: false, &)
+        if foldable
+          li(class: "flex items-center shrink-0", data: {breadcrumbs_target: "item"}) do
+            render_chevron_separator
+            yield
+          end
+        else
+          li(class: "flex items-center shrink-0 min-w-0", data: {breadcrumbs_target: "last"}) do
+            render_chevron_separator
+            yield
+          end
         end
       end
 
-      def render_chevron_separator
+      def render_chevron_separator(classes = CHEVRON_INLINE_CLASSES)
         svg(
-          class: "rtl:rotate-180 block w-3 h-3 mx-1 text-[var(--pu-text-subtle)]",
+          class: classes,
           aria_hidden: "true",
           xmlns: "http://www.w3.org/2000/svg",
           fill: "none",