openproject-primer_view_components 0.67.0 → 0.69.0

data/app/components/primer/alpha/action_menu.rb

@@ -171,143 +171,69 @@ module Primer
     class ActionMenu < Primer::Component
       status :alpha
 
-      DEFAULT_PRELOAD = false
+      delegate :preload, :preload?, :list, to: :@primary_menu
+      delegate :with_show_button, :with_item, :items, :with_divider, :with_avatar_item, :with_group, :with_sub_menu_item, to: :@primary_menu
 
-      DEFAULT_SELECT_VARIANT = :none
-      SELECT_VARIANT_OPTIONS = [
-        :single,
-        :multiple,
-        DEFAULT_SELECT_VARIANT
-      ].freeze
-
-      attr_reader :list, :preload
-
-      alias preload? preload
-
-      # @param menu_id [String] Id of the menu.
-      # @param anchor_align [Symbol] <%= one_of(Primer::Alpha::Overlay::ANCHOR_ALIGN_OPTIONS) %>.
-      # @param anchor_side [Symbol] <%= one_of(Primer::Alpha::Overlay::ANCHOR_SIDE_OPTIONS) %>.
-      # @param size [Symbol] <%= one_of(Primer::Alpha::Overlay::SIZE_OPTIONS) %>.
-      # @param src [String] Used with an `include-fragment` element to load menu content from the given source URL.
-      # @param preload [Boolean] When true, and src is present, loads the `include-fragment` on trigger hover.
-      # @param dynamic_label [Boolean] Whether or not to display the text of the currently selected item in the show button.
-      # @param dynamic_label_prefix [String] If provided, the prefix is prepended to the dynamic label and displayed in the show button.
-      # @param select_variant [Symbol] <%= one_of(Primer::Alpha::ActionMenu::SELECT_VARIANT_OPTIONS) %>
-      # @param form_arguments [Hash] Allows an `ActionMenu` to act as a select list in multi- and single-select modes. Pass the `builder:` and `name:` options to this hash. `builder:` should be an instance of `ActionView::Helpers::FormBuilder`, which are created by the standard Rails `#form_with` and `#form_for` helpers. The `name:` option is the desired name of the field that will be included in the params sent to the server on form submission.
-      # @param overlay_arguments [Hash] Arguments to pass to the underlying <%= link_to_component(Primer::Alpha::Overlay) %>
-      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>.
-      def initialize(
-        menu_id: self.class.generate_id,
-        anchor_align: Primer::Alpha::Overlay::DEFAULT_ANCHOR_ALIGN,
-        anchor_side: Primer::Alpha::Overlay::DEFAULT_ANCHOR_SIDE,
-        size: Primer::Alpha::Overlay::DEFAULT_SIZE,
-        src: nil,
-        preload: DEFAULT_PRELOAD,
-        dynamic_label: false,
-        dynamic_label_prefix: nil,
-        select_variant: DEFAULT_SELECT_VARIANT,
-        form_arguments: {},
-        overlay_arguments: {},
-        **system_arguments
-      )
-        @menu_id = menu_id
-        @src = src
-        @preload = fetch_or_fallback_boolean(preload, DEFAULT_PRELOAD)
-        @system_arguments = deny_tag_argument(**system_arguments)
-
-        @system_arguments[:preload] = true if @src.present? && preload?
+      # @!parse
+      #   # Adds an item to the menu.
+      #   #
+      #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList) %>'s `item` slot.
+      #   def with_item(**system_arguments)
+      #   end
+      #
+      #   # Adds an avatar item to the menu.
+      #   #
+      #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList) %>'s `item` slot.
+      #   def with_avatar_item(**system_arguments)
+      #   end
+      #
+      #   # Adds a divider to the list. Dividers visually separate items.
+      #   #
+      #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList::Divider) %>.
+      #   def with_divider(**system_arguments)
+      #   end
+      #
+      #   # Adds a group to the menu. Groups are a logical set of items with a header.
+      #   #
+      #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionMenu::Group) %>.
+      #   def with_group(**system_arguments)
+      #   end
+      #
+      #   # Gets the list of configured menu items, which includes regular items, avatar items, groups, and dividers.
+      #   #
+      #   # @return [Array<ViewComponent::Slot>]
+      #   def items
+      #   end
 
-        @select_variant = fetch_or_fallback(SELECT_VARIANT_OPTIONS, select_variant, DEFAULT_SELECT_VARIANT)
+      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionMenu::PrimaryMenu) %>.
+      def initialize(**system_arguments)
+        @primary_menu = PrimaryMenu.allocate
+        @system_arguments = @primary_menu.send(:initialize, **system_arguments)
 
         @system_arguments[:tag] = :"action-menu"
-        @system_arguments[:"data-select-variant"] = select_variant
-        @system_arguments[:"data-dynamic-label"] = "" if dynamic_label
-        @system_arguments[:"data-dynamic-label-prefix"] = dynamic_label_prefix if dynamic_label_prefix.present?
+        @system_arguments[:preload] = true if @primary_menu.preload?
 
-        overlay_arguments[:data] = merge_data(
-          overlay_arguments, data: {
-            target: "action-menu.overlay"
+        @system_arguments[:data] = merge_data(
+          @system_arguments, {
+            data: { "select-variant": @primary_menu.select_variant }
           }
         )
 
-        @overlay = Primer::Alpha::Overlay.new(
-          id: "#{@menu_id}-overlay",
-          title: "Menu",
-          visually_hide_title: true,
-          anchor_align: anchor_align,
-          anchor_side: anchor_side,
-          size: size,
-          **overlay_arguments
-        )
+        @system_arguments[:"data-dynamic-label"] = "" if @primary_menu.dynamic_label
 
-        @list = Primer::Alpha::ActionMenu::List.new(
-          menu_id: @menu_id,
-          select_variant: select_variant,
-          form_arguments: form_arguments
-        )
-      end
-
-      # @!parse
-      #   # Button to activate the menu.
-      #   #
-      #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::Overlay) %>'s `show_button` slot.
-      #   renders_one(:show_button)
-
-      # Button to activate the menu.
-      #
-      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::Overlay) %>'s `show_button` slot.
-      def with_show_button(**system_arguments, &block)
-        @overlay.with_show_button(**system_arguments, id: "#{@menu_id}-button", controls: "#{@menu_id}-list") do |button|
-          evaluate_block(button, &block)
+        if @primary_menu.dynamic_label_prefix.present?
+          @system_arguments[:"data-dynamic-label-prefix"] = @primary_menu.dynamic_label_prefix
         end
       end
 
-      # @!parse
-      #   # Adds a new item to the list.
-      #   #
-      #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList::Item) %>.
-      #   renders_many(:items)
-
-      # Adds a new item to the list.
-      #
-      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList::Item) %>.
-      def with_item(**system_arguments, &block)
-        @list.with_item(**system_arguments, &block)
-      end
-
-      # Adds a divider to the list.
-      #
-      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList) %>'s `divider` slot.
-      def with_divider(**system_arguments, &block)
-        @list.with_divider(**system_arguments, &block)
-      end
-
-      # Adds an avatar item to the list. Avatar items are a convenient way to accessibly add an item with a leading avatar image.
-      #
-      # @param src [String] The source url of the avatar image.
-      # @param username [String] The username associated with the avatar.
-      # @param full_name [String] Optional. The user's full name.
-      # @param full_name_scheme [Symbol] Optional. How to display the user's full name.
-      # @param avatar_arguments [Hash] Optional. The arguments accepted by <%= link_to_component(Primer::Beta::Avatar) %>.
-      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList::Item) %>.
-      def with_avatar_item(**system_arguments, &block)
-        @list.with_avatar_item(**system_arguments, &block)
-      end
-
-      def with_group(**system_arguments, &block)
-        @list.with_group(**system_arguments, &block)
-      end
-
       private
 
       def before_render
         content
-
-        raise ArgumentError, "`items` cannot be set when `src` is specified" if @src.present? && @list.items.any?
       end
 
       def render?
-        @list.items.any? || @src.present?
+        @primary_menu.items.any? || @primary_menu.src.present?
       end
     end
   end

data/app/components/primer/alpha/select_panel.rb

@@ -312,7 +312,7 @@ module Primer
       # @return [String]
       attr_reader :body_id
 
-      # <%= one_of(Primer::Alpha::ActionMenu::SELECT_VARIANT_OPTIONS) %>
+      # <%= one_of(Primer::Alpha::ActionMenu::Menu::SELECT_VARIANT_OPTIONS) %>
       #
       # @return [Symbol]
       attr_reader :select_variant
@@ -461,7 +461,7 @@ module Primer
 
         @list = Primer::Alpha::SelectPanel::ItemList.new(
           **list_arguments,
-          form_arguments: @list_form_arguments, 
+          form_arguments: @list_form_arguments,
           id: "#{@panel_id}-list",
           select_variant: @select_variant,
           aria: {
@@ -546,4 +546,4 @@ module Primer
       end
     end
   end
-end
+end

data/app/components/primer/open_project/border_box/collapsible_header.rb

@@ -12,8 +12,6 @@ module Primer
         #
         # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
         renders_one :title, lambda { |**system_arguments, &block|
-          raise ArgumentError, "Title must be a string" unless block.call.is_a?(String)
-
           system_arguments[:mr] ||= 2
 
           Primer::Beta::Text.new(**system_arguments, &block)
@@ -33,7 +31,6 @@ module Primer
         #
         # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
         renders_one :description, lambda { |**system_arguments, &block|
-          raise ArgumentError, "Description must be a string" unless block.call.is_a?(String)
           system_arguments[:color] ||= :subtle
           system_arguments[:hidden] = @collapsed
 

data/app/components/primer/open_project/collapsible_section.rb

@@ -15,8 +15,6 @@ module Primer
       # @param tag [Symbol] Customize the element type of the rendered title container.
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
       renders_one :title, lambda { |tag: TITLE_TAG_FALLBACK, **system_arguments, &block|
-        raise ArgumentError, "Title must be a string" unless block.call.is_a?(String)
-
         system_arguments[:tag] = fetch_or_fallback(TITLE_TAG_OPTIONS, tag, TITLE_TAG_FALLBACK)
         system_arguments[:font_size] ||= 3
         system_arguments[:mr] ||= 2
@@ -28,8 +26,6 @@ module Primer
       #
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
       renders_one :caption, lambda { |**system_arguments, &block|
-        raise ArgumentError, "Caption must be a string" unless block.call.is_a?(String)
-
         system_arguments[:color] ||= :subtle
         system_arguments[:mr] ||= 2
         system_arguments[:display] ||= [:none, :block]
@@ -40,9 +36,7 @@ module Primer
       # Optional right-side content
       #
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-      renders_one :additional_information, lambda { |**system_arguments, &block|
-        raise ArgumentError, "The additional information must be a string" unless block.call.is_a?(String)
-
+      renders_one :additional_information, lambda { |**system_arguments|
         Primer::BaseComponent.new(tag: :div, **system_arguments)
       }
 

data/app/components/primer/open_project/page_header/title.rb

@@ -9,7 +9,7 @@ module Primer
         status :open_project
 
         HEADING_TAG_OPTIONS = [:h1, :h2, :h3, :h4, :h5, :h6].freeze
-        HEADING_TAG_FALLBACK = :h1
+        HEADING_TAG_FALLBACK = :h2
 
         renders_one :editable_form, lambda { |model: false, update_path:, cancel_path:, input_name: :title, method: :put, label: I18n.t(:label_title), placeholder: I18n.t(:label_title), **system_arguments|
           primer_form_with(

data/app/components/primer/open_project/tree_view/tree_view.d.ts

@@ -22,6 +22,7 @@ export declare class TreeViewElement extends HTMLElement {
     getNodeCheckedValue(node: Element): TreeViewCheckedValue;
     nodeHasCheckBox(node: Element): boolean;
     nodeHasNativeAction(node: Element): boolean;
+    expandAncestorsForNode(node: HTMLElement): void;
     infoFromNode(node: Element, newCheckedValue?: TreeViewCheckedValue): TreeViewNodeInfo | null;
 }
 declare global {

data/app/components/primer/open_project/tree_view/tree_view.js

@@ -15,7 +15,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _TreeViewElement_instances, _TreeViewElement_abortController, _TreeViewElement_eventIsActivation, _TreeViewElement_nodeForEvent, _TreeViewElement_handleNodeEvent, _TreeViewElement_eventIsCheckboxToggle, _TreeViewElement_handleCheckboxToggle, _TreeViewElement_handleNodeActivated, _TreeViewElement_handleNodeFocused, _TreeViewElement_handleNodeKeyboardEvent, _TreeViewElement_setNodeCheckedValue;
+var _TreeViewElement_instances, _TreeViewElement_abortController, _TreeViewElement_autoExpandFrom, _TreeViewElement_eventIsActivation, _TreeViewElement_nodeForEvent, _TreeViewElement_handleNodeEvent, _TreeViewElement_eventIsCheckboxToggle, _TreeViewElement_handleCheckboxToggle, _TreeViewElement_handleNodeActivated, _TreeViewElement_handleNodeFocused, _TreeViewElement_handleNodeKeyboardEvent, _TreeViewElement_setNodeCheckedValue;
 import { controller } from '@github/catalyst';
 import { useRovingTabIndex } from './tree_view_roving_tab_index';
 let TreeViewElement = class TreeViewElement extends HTMLElement {
@@ -30,6 +30,24 @@ let TreeViewElement = class TreeViewElement extends HTMLElement {
         this.addEventListener('focusin', this, { signal });
         this.addEventListener('keydown', this, { signal });
         useRovingTabIndex(this);
+        // catch-all for any straggler nodes that aren't available when connectedCallback runs
+        new MutationObserver(mutations => {
+            for (const mutation of mutations) {
+                for (const addedNode of mutation.addedNodes) {
+                    if (!(addedNode instanceof HTMLElement))
+                        continue;
+                    // eslint-disable-next-line custom-elements/no-dom-traversal-in-connectedcallback
+                    if (addedNode.querySelector('[aria-expanded=true]')) {
+                        __classPrivateFieldGet(this, _TreeViewElement_instances, "m", _TreeViewElement_autoExpandFrom).call(this, addedNode);
+                    }
+                }
+            }
+        }).observe(this, { childList: true, subtree: true });
+        // eslint-disable-next-line github/no-then -- We don't want to wait for this to resolve, just get on with it
+        customElements.whenDefined('tree-view-sub-tree-node').then(() => {
+            // depends on TreeViewSubTreeNodeElement#eachAncestorSubTreeNode, which may not be defined yet
+            __classPrivateFieldGet(this, _TreeViewElement_instances, "m", _TreeViewElement_autoExpandFrom).call(this, this);
+        });
     }
     disconnectedCallback() {
         __classPrivateFieldGet(this, _TreeViewElement_abortController, "f").abort();
@@ -132,6 +150,16 @@ let TreeViewElement = class TreeViewElement extends HTMLElement {
     nodeHasNativeAction(node) {
         return node instanceof HTMLAnchorElement || node instanceof HTMLButtonElement;
     }
+    expandAncestorsForNode(node) {
+        const subTreeNode = node.closest('tree-view-sub-tree-node');
+        if (!subTreeNode)
+            return;
+        for (const ancestor of subTreeNode.eachAncestorSubTreeNode()) {
+            if (!ancestor.expanded) {
+                ancestor.expand();
+            }
+        }
+    }
     // PRIVATE API METHOD
     //
     // This would normally be marked private, but it's called by TreeViewSubTreeNodes
@@ -152,6 +180,11 @@ let TreeViewElement = class TreeViewElement extends HTMLElement {
 };
 _TreeViewElement_abortController = new WeakMap();
 _TreeViewElement_instances = new WeakSet();
+_TreeViewElement_autoExpandFrom = function _TreeViewElement_autoExpandFrom(root) {
+    for (const element of root.querySelectorAll('[aria-expanded=true]')) {
+        this.expandAncestorsForNode(element);
+    }
+};
 _TreeViewElement_eventIsActivation = function _TreeViewElement_eventIsActivation(event) {
     return event.type === 'click';
 };

data/app/components/primer/open_project/tree_view/tree_view.ts

@@ -14,6 +14,32 @@ export class TreeViewElement extends HTMLElement {
     this.addEventListener('keydown', this, {signal})
 
     useRovingTabIndex(this)
+
+    // catch-all for any straggler nodes that aren't available when connectedCallback runs
+    new MutationObserver(mutations => {
+      for (const mutation of mutations) {
+        for (const addedNode of mutation.addedNodes) {
+          if (!(addedNode instanceof HTMLElement)) continue
+
+          // eslint-disable-next-line custom-elements/no-dom-traversal-in-connectedcallback
+          if (addedNode.querySelector('[aria-expanded=true]')) {
+            this.#autoExpandFrom(addedNode)
+          }
+        }
+      }
+    }).observe(this, {childList: true, subtree: true})
+
+    // eslint-disable-next-line github/no-then -- We don't want to wait for this to resolve, just get on with it
+    customElements.whenDefined('tree-view-sub-tree-node').then(() => {
+      // depends on TreeViewSubTreeNodeElement#eachAncestorSubTreeNode, which may not be defined yet
+      this.#autoExpandFrom(this)
+    })
+  }
+
+  #autoExpandFrom(root: HTMLElement) {
+    for (const element of root.querySelectorAll('[aria-expanded=true]')) {
+      this.expandAncestorsForNode(element as HTMLElement)
+    }
   }
 
   disconnectedCallback() {
@@ -246,6 +272,17 @@ export class TreeViewElement extends HTMLElement {
     return node instanceof HTMLAnchorElement || node instanceof HTMLButtonElement
   }
 
+  expandAncestorsForNode(node: HTMLElement) {
+    const subTreeNode = node.closest('tree-view-sub-tree-node') as TreeViewSubTreeNodeElement
+    if (!subTreeNode) return
+
+    for (const ancestor of subTreeNode.eachAncestorSubTreeNode()) {
+      if (!ancestor.expanded) {
+        ancestor.expand()
+      }
+    }
+  }
+
   // PRIVATE API METHOD
   //
   // This would normally be marked private, but it's called by TreeViewSubTreeNodes

data/app/components/primer/open_project/tree_view/tree_view_sub_tree_node_element.d.ts

@@ -28,6 +28,7 @@ export declare class TreeViewSubTreeNodeElement extends HTMLElement {
     get nodes(): NodeListOf<Element>;
     eachDirectDescendantNode(): Generator<Element>;
     eachDescendantNode(): Generator<Element>;
+    eachAncestorSubTreeNode(): Generator<TreeViewSubTreeNodeElement>;
     get isEmpty(): boolean;
     get treeView(): TreeViewElement | null;
     toggleChecked(): void;

data/app/components/primer/open_project/tree_view/tree_view_sub_tree_node_element.js

@@ -165,6 +165,16 @@ let TreeViewSubTreeNodeElement = class TreeViewSubTreeNodeElement extends HTMLEl
             yield node;
         }
     }
+    *eachAncestorSubTreeNode() {
+        if (!this.treeView)
+            return;
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let current = this;
+        while (current && this.treeView.contains(current)) {
+            yield current;
+            current = current.parentElement?.closest('tree-view-sub-tree-node');
+        }
+    }
     get isEmpty() {
         return this.nodes.length === 0;
     }
@@ -230,6 +240,9 @@ _TreeViewSubTreeNodeElement_handleIncludeFragmentEvent = function _TreeViewSubTr
             this.loadingState = 'success';
             break;
         case 'include-fragment-replaced':
+            // Make sure to expand the new sub-tree, otherwise it looks like nothing happened. This prevents
+            // having to remember to pass `SubTree.new(expanded: true)` in the controller.
+            this.expanded = true;
             if (__classPrivateFieldGet(this, _TreeViewSubTreeNodeElement_activeElementIsLoader, "f")) {
                 const firstItem = this.querySelector('[role=group] > :first-child');
                 if (!firstItem)
@@ -308,6 +321,7 @@ _TreeViewSubTreeNodeElement_update = function _TreeViewSubTreeNodeElement_update
         if (this.subTree)
             this.subTree.hidden = false;
         this.node.setAttribute('aria-expanded', 'true');
+        this.treeView?.expandAncestorsForNode(this);
         if (this.iconPair) {
             this.iconPair.showExpanded();
         }

data/app/components/primer/open_project/tree_view/tree_view_sub_tree_node_element.ts

@@ -217,6 +217,19 @@ export class TreeViewSubTreeNodeElement extends HTMLElement {
     }
   }
 
+  *eachAncestorSubTreeNode(): Generator<TreeViewSubTreeNodeElement> {
+    if (!this.treeView) return
+
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let current: TreeViewSubTreeNodeElement | null = this
+
+    while (current && this.treeView.contains(current)) {
+      yield current
+
+      current = current.parentElement?.closest('tree-view-sub-tree-node') as TreeViewSubTreeNodeElement | null
+    }
+  }
+
   get isEmpty(): boolean {
     return this.nodes.length === 0
   }
@@ -252,6 +265,10 @@ export class TreeViewSubTreeNodeElement extends HTMLElement {
         break
 
       case 'include-fragment-replaced':
+        // Make sure to expand the new sub-tree, otherwise it looks like nothing happened. This prevents
+        // having to remember to pass `SubTree.new(expanded: true)` in the controller.
+        this.expanded = true
+
         if (this.#activeElementIsLoader) {
           const firstItem = this.querySelector('[role=group] > :first-child') as HTMLElement | null
           if (!firstItem) return
@@ -377,6 +394,7 @@ export class TreeViewSubTreeNodeElement extends HTMLElement {
     if (this.expanded) {
       if (this.subTree) this.subTree.hidden = false
       this.node.setAttribute('aria-expanded', 'true')
+      this.treeView?.expandAncestorsForNode(this)
 
       if (this.iconPair) {
         this.iconPair.showExpanded()

data/lib/primer/view_components/version.rb

@@ -5,7 +5,7 @@ module Primer
   module ViewComponents
     module VERSION
       MAJOR = 0
-      MINOR = 67
+      MINOR = 69
       PATCH = 0
 
       STRING = [MAJOR, MINOR, PATCH].join(".")

data/previews/primer/alpha/action_menu_preview/multiple_select_form.html.erb

@@ -1,10 +1,19 @@
 <%= form_with(url: action_menu_form_action_path(format: route_format)) do |f| %>
+  <% content = -> (base) do %>
+    <% base.with_item(label: "Fast forward", data: { value: "fast_forward" }) %>
+    <% base.with_item(label: "Recursive", data: { value: "recursive" }) %>
+    <% base.with_item(label: "Ours", data: { value: "ours" }, active: true) %>
+    <% base.with_item(label: "Resolve") %>
+  <% end %>
   <%= render(Primer::Alpha::ActionMenu.new(select_variant: :multiple, dynamic_label: true, dynamic_label_prefix: "Strategy", form_arguments: { builder: f, name: "foo" })) do |menu| %>
     <% menu.with_show_button { "Strategy" } %>
-    <% menu.with_item(label: "Fast forward", data: { value: "fast_forward" }) %>
-    <% menu.with_item(label: "Recursive", data: { value: "recursive" }) %>
-    <% menu.with_item(label: "Ours", data: { value: "ours" }, active: true) %>
-    <% menu.with_item(label: "Resolve") %>
+    <% if nest_in_sub_menu %>
+      <% menu.with_sub_menu_item(label: "Sub-menu") do |sub_menu| %>
+        <% content.call(sub_menu) %>
+      <% end %>
+    <% else %>
+      <% content.call(menu) %>
+    <% end %>
   <% end %>
   <hr>
   <div>

data/previews/primer/alpha/action_menu_preview/opens_dialog.html.erb

@@ -1,20 +1,29 @@
 <%= render(Primer::Alpha::ActionMenu.new) do |component| %>
   <% component.with_show_button { "Menu" } %>
-  <% component.with_item(label: "Item", tag: :button, value: "") %>
-  <% component.with_item(
-    label: "Show dialog",
-    tag: :button,
-    content_arguments: { "data-show-dialog-id": "my-dialog" },
-    value: "",
-    scheme: :danger
-  ) %>
+  <% contents = -> (base) do %>
+    <% base.with_item(label: "Item", tag: :button, value: "") %>
+    <% base.with_item(
+      label: "Show dialog",
+      tag: :button,
+      content_arguments: { "data-show-dialog-id": "my-dialog" },
+      value: "",
+      scheme: :danger
+    ) %>
+  <% end %>
+  <% if nest_in_sub_menu %>
+    <% component.with_sub_menu_item(label: "Sub-menu") do |sub_menu_item| %>
+      <% contents.call(sub_menu_item) %>
+    <% end %>
+  <% else %>
+    <% contents.call(component) %>
+  <% end %>
 <% end %>
 
-<%= render(Primer::Alpha::Dialog.new(id: "my-dialog", title: "Confirm deletion")) do |d| %>
-  <%= render(Primer::Alpha::Dialog::Body.new()) do %>
+<%= render(Primer::Alpha::Dialog.new(id: "my-dialog", title: "Confirm deletion")) do |dialog| %>
+  <% dialog.with_body do %>
     Are you sure you want to delete this?
   <% end %>
-  <%= render(Primer::Alpha::Dialog::Footer.new()) do %>
+  <% dialog.with_footer do %>
     <%= render(Primer::Beta::Button.new(data: { "close-dialog-id": "my-dialog" })) { "Cancel" } %>
     <%= render(Primer::Beta::Button.new(scheme: :danger)) { "Delete" } %>
   <% end %>

data/previews/primer/alpha/action_menu_preview/single_select_form_items.html.erb

@@ -1,5 +1,4 @@
-<%= render(Primer::Alpha::ActionMenu.new(select_variant: :single)) do |menu| %>
-  <% menu.with_show_button { "Group By" } %>
+<% contents = -> (menu) do %>
   <% menu.with_item(
     label: "Repository",
     href: action_menu_form_action_path(format: route_format),
@@ -29,3 +28,15 @@
     }
   ) %>
 <% end %>
+
+<%= render(Primer::Alpha::ActionMenu.new(select_variant: :single)) do |menu| %>
+  <% menu.with_show_button { "Group By" } %>
+
+  <% if nest_in_sub_menu %>
+    <% menu.with_sub_menu_item(label: "Sub-menu") do |sub_menu_item| %>
+      <% contents.call(sub_menu_item) %>
+    <% end %>
+  <% else %>
+    <% contents.call(menu) %>
+  <% end %>
+<% end %>

data/previews/primer/alpha/action_menu_preview/sub_menus.html.erb

@@ -0,0 +1,19 @@
+<%# Center the invoker button to give left-appearing sub-menus enough space %>
+<div style="<%= sub_menu_anchor_side.to_s.include?("left") ? "text-align: center" : "" %>">
+  <%= render(Primer::Alpha::ActionMenu.new(anchor_align: anchor_align, anchor_side: anchor_side)) do |menu| %>
+    <% menu.with_show_button { "Edit" } %>
+    <% menu.with_item(label: "Cut") %>
+    <% menu.with_item(label: "Copy") %>
+    <% menu.with_sub_menu_item(label: "Paste special", anchor_align: sub_menu_anchor_align, anchor_side: sub_menu_anchor_side) do |sub_menu| %>
+      <% sub_menu.with_leading_visual_icon(icon: :"sparkle-fill") %>
+      <% sub_menu.with_item(label: "Paste plain text") %>
+      <% sub_menu.with_item(label: "Paste formulas") %>
+      <% sub_menu.with_item(label: "Paste with formatting") %>
+      <% sub_menu.with_sub_menu_item(label: "Paste from") do |sub_menu| %>
+        <% sub_menu.with_item(label: "Current clipboard") %>
+        <% sub_menu.with_item(label: "History") %>
+        <% sub_menu.with_item(label: "Another device") %>
+      <% end %>
+    <% end %>
+  <% end %>
+</div>

data/previews/primer/alpha/action_menu_preview/with_actions.html.erb

@@ -8,15 +8,24 @@
 
 <%= render(Primer::Alpha::ActionMenu.new) do |component| %>
   <% component.with_show_button { "Trigger" } %>
-  <% component.with_item(label: "Alert", tag: :button, id: "alert-item", disabled: disable_items) %>
-  <% component.with_item(label: "Navigate", tag: :a, content_arguments: { href: action_menu_landing_path }, disabled: disable_items) %>
-  <% component.with_item(label: "Copy text", tag: :"clipboard-copy", content_arguments: { value: "Text to copy" }, disabled: disable_items) %>
-  <% component.with_item(
-    label: "Submit form",
-    href: action_menu_form_action_path(format: route_format),
-    form_arguments: {
-      name: "foo", value: "bar", method: :post
-    },
-    disabled: disable_items
-  ) %>
+  <% contents = -> (base) do %>
+    <% base.with_item(label: "Alert", tag: :button, id: "alert-item", disabled: disable_items) %>
+    <% base.with_item(label: "Navigate", tag: :a, content_arguments: { href: action_menu_landing_path }, disabled: disable_items) %>
+    <% base.with_item(label: "Copy text", tag: :"clipboard-copy", content_arguments: { value: "Text to copy" }, disabled: disable_items) %>
+    <% base.with_item(
+      label: "Submit form",
+      href: action_menu_form_action_path(format: route_format),
+      form_arguments: {
+        name: "foo", value: "bar", method: :post
+      },
+      disabled: disable_items
+    ) %>
+  <% end %>
+  <% if nest_in_sub_menu %>
+    <% component.with_sub_menu_item(label: "Sub-menu") do |sub_menu_item| %>
+      <% contents.call(sub_menu_item) %>
+    <% end %>
+  <% else %>
+    <% contents.call(component) %>
+  <% end %>
 <% end %>