primer_view_components 0.14.0 → 0.15.1

data/app/components/primer/alpha/action_menu/action_menu_element.ts

@@ -12,6 +12,17 @@ type SelectedItem = {
 const validSelectors = ['[role="menuitem"]', '[role="menuitemcheckbox"]', '[role="menuitemradio"]']
 const menuItemSelectors = validSelectors.map(selector => `:not([hidden]) > ${selector}`)
 
+export type ItemActivatedEvent = {
+  item: Element
+  checked: boolean
+}
+
+declare global {
+  interface HTMLElementEventMap {
+    itemActivated: CustomEvent<ItemActivatedEvent>
+  }
+}
+
 @controller
 export class ActionMenuElement extends HTMLElement {
   @target
@@ -82,7 +93,7 @@ export class ActionMenuElement extends HTMLElement {
       results.push({
         label: labelEl?.textContent,
         value: selectedItem?.getAttribute('data-value'),
-        element: selectedItem
+        element: selectedItem,
       })
     }
 
@@ -102,35 +113,39 @@ export class ActionMenuElement extends HTMLElement {
 
     if (this.includeFragment) {
       this.includeFragment.addEventListener('include-fragment-replaced', this, {
-        signal
+        signal,
       })
     }
   }
 
+  disconnectedCallback() {
+    this.#abortController.abort()
+  }
+
   #softDisableItems() {
     const {signal} = this.#abortController
 
-    for (const item of this.#items) {
+    for (const item of this.querySelectorAll(validSelectors.join(','))) {
       item.addEventListener('click', this.#potentiallyDisallowActivation.bind(this), {signal})
       item.addEventListener('keydown', this.#potentiallyDisallowActivation.bind(this), {signal})
     }
   }
 
-  #potentiallyDisallowActivation(event: Event) {
-    if (!this.#isActivation(event)) return
+  // returns true if activation was prevented
+  #potentiallyDisallowActivation(event: Event): boolean {
+    if (!this.#isActivation(event)) return false
 
     const item = (event.target as HTMLElement).closest(menuItemSelectors.join(','))
-    if (!item) return
+    if (!item) return false
 
     if (item.getAttribute('aria-disabled')) {
       event.preventDefault()
       event.stopPropagation()
       event.stopImmediatePropagation()
+      return true
     }
-  }
 
-  disconnectedCallback() {
-    this.#abortController.abort()
+    return false
   }
 
   #isKeyboardActivation(event: Event): boolean {
@@ -202,6 +217,8 @@ export class ActionMenuElement extends HTMLElement {
     const targetIsItem = item !== null
 
     if (targetIsItem && eventIsActivation) {
+      if (this.#potentiallyDisallowActivation(event)) return
+
       const dialogInvoker = item.closest('[data-show-dialog-id]')
 
       if (dialogInvoker) {
@@ -214,7 +231,7 @@ export class ActionMenuElement extends HTMLElement {
       }
 
       this.#activateItem(event, item)
-      this.#handleItemActivated(event, item)
+      this.#handleItemActivated(item)
 
       // Pressing the space key on a button or link will cause the page to scroll unless preventDefault()
       // is called. While calling preventDefault() appears to have no effect on link navigation, it skips
@@ -263,7 +280,7 @@ export class ActionMenuElement extends HTMLElement {
     dialog.addEventListener('cancel', handleDialogClose, {signal})
   }
 
-  #handleItemActivated(event: Event, item: Element) {
+  #handleItemActivated(item: Element) {
     // Hide popover after current event loop to prevent changes in focus from
     // altering the target of the event. Not doing this specifically affects
     // <a> tags. It causes the event to be sent to the currently focused element
@@ -304,6 +321,11 @@ export class ActionMenuElement extends HTMLElement {
     }
 
     this.#updateInput()
+    this.dispatchEvent(
+      new CustomEvent('itemActivated', {
+        detail: {item: item.parentElement, checked: this.isItemChecked(item.parentElement)},
+      }),
+    )
   }
 
   #activateItem(event: Event, item: Element) {
@@ -410,9 +432,85 @@ export class ActionMenuElement extends HTMLElement {
     return this.querySelector(menuItemSelectors.join(','))
   }
 
-  get #items(): HTMLElement[] {
+  get items(): HTMLElement[] {
     return Array.from(this.querySelectorAll(menuItemSelectors.join(',')))
   }
+
+  getItemById(itemId: string): HTMLElement | null {
+    return this.querySelector(`li[data-item-id="${itemId}"`)
+  }
+
+  isItemDisabled(item: Element | null): boolean {
+    if (item) {
+      return item.classList.contains('ActionListItem--disabled')
+    } else {
+      return false
+    }
+  }
+
+  disableItem(item: Element | null) {
+    if (item) {
+      item.classList.add('ActionListItem--disabled')
+      item.querySelector('.ActionListContent')!.setAttribute('aria-disabled', 'true')
+    }
+  }
+
+  enableItem(item: Element | null) {
+    if (item) {
+      item.classList.remove('ActionListItem--disabled')
+      item.querySelector('.ActionListContent')!.removeAttribute('aria-disabled')
+    }
+  }
+
+  isItemHidden(item: Element | null): boolean {
+    if (item) {
+      return item.hasAttribute('hidden')
+    } else {
+      return false
+    }
+  }
+
+  hideItem(item: Element | null) {
+    if (item) {
+      item.setAttribute('hidden', 'hidden')
+    }
+  }
+
+  showItem(item: Element | null) {
+    if (item) {
+      item.removeAttribute('hidden')
+    }
+  }
+
+  isItemChecked(item: Element | null) {
+    if (item) {
+      return item.querySelector('.ActionListContent')!.getAttribute('aria-checked') === 'true'
+    } else {
+      return false
+    }
+  }
+
+  checkItem(item: Element | null) {
+    if (item && (this.selectVariant === 'single' || this.selectVariant === 'multiple')) {
+      const itemContent = item.querySelector('.ActionListContent')!
+      const ariaChecked = itemContent.getAttribute('aria-checked') === 'true'
+
+      if (!ariaChecked) {
+        this.#handleItemActivated(itemContent)
+      }
+    }
+  }
+
+  uncheckItem(item: Element | null) {
+    if (item && (this.selectVariant === 'single' || this.selectVariant === 'multiple')) {
+      const itemContent = item.querySelector('.ActionListContent')!
+      const ariaChecked = itemContent.getAttribute('aria-checked') === 'true'
+
+      if (ariaChecked) {
+        this.#handleItemActivated(itemContent)
+      }
+    }
+  }
 }
 
 if (!window.customElements.get('action-menu')) {

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

@@ -0,0 +1,23 @@
+# typed: true
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class ActionMenu
+      # This component is part of <%= link_to_component(Primer::Alpha::ActionMenu) %> and should not be
+      # used as a standalone component.
+      class Group < Primer::Alpha::ActionList
+        # Heading text rendered above the list of items.
+        #
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionMenu::Heading) %>.
+        def with_heading(**system_arguments, &block)
+          super(component_klass: Primer::Alpha::ActionMenu::Heading, **system_arguments, &block)
+        end
+
+        def with_divider
+          raise "ActionMenu groups cannot have dividers"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class ActionMenu
+      # Heading used to describe groups within an action menu.
+      class Heading < Primer::Alpha::ActionList::Heading
+        def initialize(**)
+          super
+
+          # Headings don't make sense in a menu context, so use div instead
+          @tag = :div
+        end
+      end
+    end
+  end
+end

data/app/components/primer/alpha/action_menu/list.html.erb

@@ -0,0 +1 @@
+<%= render(@list) %>

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

@@ -1,4 +1,3 @@
-# typed: true
 # frozen_string_literal: true
 
 module Primer
@@ -6,72 +5,84 @@ module Primer
     class ActionMenu
       # This component is part of <%= link_to_component(Primer::Alpha::ActionMenu) %> and should not be
       # used as a standalone component.
-      class List < Primer::Alpha::ActionList
+      class List < Primer::Component
         DEFAULT_ITEM_TAG = :button
         ITEM_TAG_OPTIONS = [:a, :"clipboard-copy", DEFAULT_ITEM_TAG].freeze
 
-        # Adds a new item to the list.
-        #
-        # @param data [Hash] When the menu is used as a form input (see the <%= link_to_component(Primer::Alpha::ActionMenu) %> docs), the label is submitted to the server by default. However, if the `data: { value: }` or `"data-value":` attribute is provided, it will be sent to the server instead.
-        # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::Alpha::ActionList::Item) %>, or whatever class is passed as the `component_klass` argument.
-        def with_item(data: {}, **system_arguments, &block)
-          system_arguments = organize_arguments(data: data, **system_arguments)
+        attr_reader :items
 
-          super(**system_arguments) do |item|
-            evaluate_block(item, &block)
-          end
-        end
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList) %>
+        def initialize(**system_arguments)
+          @items = []
+          @has_group = false
 
-        # 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. <%= one_of(Primer::Alpha::ActionList::Item::DESCRIPTION_SCHEME_OPTIONS) %>
-        # @param data [Hash] When the menu is used as a form input (see the <%= link_to_component(Primer::Alpha::ActionMenu) %> docs), the label is submitted to the server by default. However, if the `data: { value: }` or `"data-value":` attribute is provided, it will be sent to the server instead.
-        # @param avatar_arguments [Hash] Optional. The arguments accepted by <%= link_to_component(Primer::Beta::Avatar) %>.
-        # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::Alpha::ActionList::Item) %>, or whatever class is passed as the `component_klass` argument.
-        def with_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, data: {}, avatar_arguments: {}, **system_arguments, &block)
-          system_arguments = organize_arguments(data: data, **system_arguments)
-
-          super(src: src, username: username, full_name: full_name, full_name_scheme: full_name_scheme, avatar_arguments: avatar_arguments, **system_arguments) do |item|
-            evaluate_block(item, &block)
-          end
+          @list = Primer::Alpha::ActionMenu::ListWrapper.new(**system_arguments)
         end
 
-        # @param menu_id [String] ID of the parent menu.
-        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList) %>
-        def initialize(menu_id:, **system_arguments, &block)
-          @menu_id = menu_id
+        def with_group(**system_arguments, &block)
+          @has_group = true
 
-          system_arguments[:aria] = merge_aria(
-            system_arguments,
-            { aria: { labelledby: "#{@menu_id}-button" } }
-          )
+          @items << {
+            type: :group,
+            kwargs: system_arguments,
+            block: block
+          }
+        end
 
-          system_arguments[:role] = :menu
-          system_arguments[:scheme] = :inset
-          system_arguments[:id] = "#{@menu_id}-list"
+        def with_item(**system_arguments, &block)
+          @items << {
+            type: :item,
+            kwargs: organize_arguments(**system_arguments),
+            block: block
+          }
+        end
+
+        def with_avatar_item(**system_arguments, &block)
+          @items << {
+            type: :avatar_item,
+            kwargs: organize_arguments(**system_arguments),
+            block: block
+          }
+        end
 
-          super(**system_arguments, &block)
+        def with_divider(**system_arguments, &block)
+          @items << {
+            type: :divider,
+            kwargs: system_arguments,
+            block: block
+          }
         end
 
         private
 
-        def evaluate_block(*args, &block)
-          # Prevent double renders by using the capture method on the component
-          # that originally received the block.
-          #
-          # Handle blocks that originate from C code such as `&:method` by checking
-          # source_location. Such blocks don't allow access to their receiver.
-          return unless block&.source_location
+        def contains_group?
+          @has_group
+        end
 
-          block_context = block.binding.receiver
+        def before_render
+          content
+
+          @items.each do |item|
+            case item[:type]
+            when :divider, :group
+              add_item(item, to: @list)
+            else
+              if contains_group?
+                @list.with_group do |group|
+                  add_item(item, to: group)
+                end
+              else
+                add_item(item, to: @list)
+              end
+            end
+          end
+        end
 
-          if block_context.class < ActionView::Base
-            block_context.capture(*args, &block)
-          else
-            capture(*args, &block)
+        def add_item(item, to:)
+          parent = to
+          mtd = :"with_#{item[:type]}"
+          parent.send(mtd, **item[:kwargs]) do |item_instance|
+            evaluate_block(item_instance, &item[:block])
           end
         end
 

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class ActionMenu
+      # This component is part of <%= link_to_component(Primer::Alpha::ActionMenu) %> and should not be
+      # used as a standalone component.
+      class ListWrapper < Primer::Alpha::ActionList
+        add_polymorphic_slot_type(
+          slot_name: :items,
+          type: :group,
+          callable: lambda { |**system_arguments|
+            Primer::Alpha::ActionMenu::Group.new(
+              **system_arguments,
+              role: :group,
+              select_variant: @select_variant
+            )
+          }
+        )
+
+        # @param menu_id [String] ID of the parent menu.
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList) %>
+        def initialize(menu_id:, **system_arguments)
+          @menu_id = menu_id
+
+          system_arguments[:aria] = merge_aria(
+            system_arguments,
+            { aria: { labelledby: "#{@menu_id}-button" } }
+          )
+
+          system_arguments[:role] = :menu
+          system_arguments[:scheme] = :inset
+          system_arguments[:id] = "#{@menu_id}-list"
+
+          super(**system_arguments)
+        end
+      end
+    end
+  end
+end

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

@@ -128,6 +128,39 @@ module Primer
     #
     #   Additional information around the keyboard functionality and implementation can be found on the
     #   [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.2/#menu).
+    #
+    # ### JavaScript API
+    #
+    # `ActionList`s render an `<action-list>` custom element that exposes behavior to the client. For all these methods,
+    # `itemId` refers to the value of the `item_id:` argument (see below) that is used to populate the `data-item-id` HTML
+    # attribute.
+    #
+    # #### Query methods
+    #
+    # * `getItemById(itemId: string): Element`: Returns the item's HTML `<li>` element. The return value can be passed as the `item` argument to the other methods listed below.
+    # * `isItemChecked(item: Element): boolean`: Returns `true` if the item is checked, `false` otherwise.
+    # * `isItemHidden(item: Element): boolean`: Returns `true` if the item is hidden, `false` otherwise.
+    # * `isItemDisabled(item: Element): boolean`: Returns `true` if the item is disabled, `false` otherwise.
+    #
+    # #### State methods
+    #
+    # * `showItem(item: Element)`: Shows the item, i.e. makes it visible.
+    # * `hideItem(item: Element)`: Hides the item, i.e. makes it invisible.
+    # * `enableItem(item: Element)`: Enables the item, i.e. makes it clickable by the mouse and keyboard.
+    # * `disableItem(item: Element)`: Disables the item, i.e. makes it unclickable by the mouse and keyboard.
+    # * `checkItem(item: Element)`: Checks the item. Only has an effect in single- and multi-select modes.
+    # * `uncheckItem(item: Element)`: Unchecks the item. Only has an effect in multi-select mode, since items cannot be unchecked in single-select mode.
+    #
+    # #### Events
+    #
+    # The `<action-menu>` element fires an `itemActivated` event whenever an item is activated (eg. clicked) via the mouse or keyboard.
+    #
+    # ```typescript
+    # document.querySelector("action-menu").addEventListener("itemActivated", (event: ItemActivatedEvent) => {
+    #   event.item  // Element: the <li> item that was activated
+    #   event.checked  // boolean: whether or not the result of the activation checked the item
+    # })
+    # ```
     class ActionMenu < Primer::Component
       status :alpha
 
@@ -175,7 +208,7 @@ module Primer
 
         @system_arguments[:preload] = true if @src.present? && preload?
 
-        select_variant = fetch_or_fallback(SELECT_VARIANT_OPTIONS, select_variant, DEFAULT_SELECT_VARIANT)
+        @select_variant = fetch_or_fallback(SELECT_VARIANT_OPTIONS, select_variant, DEFAULT_SELECT_VARIANT)
 
         @system_arguments[:tag] = :"action-menu"
         @system_arguments[:"data-select-variant"] = select_variant
@@ -243,6 +276,10 @@ module Primer
         @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

data/app/components/primer/alpha/overlay.css

@@ -1 +1 @@
-anchored-position[popover]{background:none;border-width:0;min-width:192px;overflow:visible;padding:0;position:absolute}.Overlay{display:flex}anchored-position.not-anchored::backdrop{background-color:var(--overlay-backdrop-bgColor,var(--color-neutral-muted))}
+anchored-position[popover]{border-width:0;min-width:192px;overflow:visible;padding:0;position:absolute}anchored-position:not(.Overlay){background:none}.Overlay[popover]:not(:popover-open){display:none}anchored-position.not-anchored::backdrop{background-color:var(--overlay-backdrop-bgColor,var(--color-neutral-muted))}

data/app/components/primer/alpha/overlay.css.json

@@ -2,7 +2,8 @@
   "name": "alpha/overlay",
   "selectors": [
     "anchored-position[popover]",
-    ".Overlay",
+    "anchored-position:not(.Overlay)",
+    ".Overlay[popover]:not(:popover-open)",
     "anchored-position.not-anchored::backdrop"
   ]
 }

data/app/components/primer/alpha/overlay.css.map

@@ -1 +1 @@
-{"version":3,"sources":["overlay.pcss"],"names":[],"mappings":"AAAA,2BAME,eAAgB,CALhB,cAAe,CAGf,eAAgB,CAChB,gBAAiB,CAHjB,SAAU,CACV,iBAIF,CAEA,SACE,YACF,CAEA,yCACE,2EACF","file":"overlay.css","sourcesContent":["anchored-position[popover] {\n  border-width: 0;\n  padding: 0;\n  position: absolute;\n  min-width: 192px;\n  overflow: visible;\n  background: none;\n}\n\n.Overlay {\n  display: flex;\n}\n\nanchored-position.not-anchored::backdrop {\n  background-color: var(--overlay-backdrop-bgColor, var(--color-neutral-muted));\n}\n"]}
+{"version":3,"sources":["overlay.pcss"],"names":[],"mappings":"AAAA,2BACE,cAAe,CAGf,eAAgB,CAChB,gBAAiB,CAHjB,SAAU,CACV,iBAGF,CAEA,gCACE,eACF,CAGA,qCACE,YACF,CAEA,yCACE,2EACF","file":"overlay.css","sourcesContent":["anchored-position[popover] {\n  border-width: 0;\n  padding: 0;\n  position: absolute;\n  min-width: 192px;\n  overflow: visible;\n}\n\nanchored-position:not(.Overlay) {\n  background: none;\n}\n\n/* stylelint-disable-next-line selector-pseudo-class-no-unknown */\n.Overlay[popover]:not(:popover-open) {\n  display: none\n}\n\nanchored-position.not-anchored::backdrop {\n  background-color: var(--overlay-backdrop-bgColor, var(--color-neutral-muted));\n}\n"]}

data/app/components/primer/alpha/overlay.pcss

@@ -4,11 +4,15 @@ anchored-position[popover] {
   position: absolute;
   min-width: 192px;
   overflow: visible;
+}
+
+anchored-position:not(.Overlay) {
   background: none;
 }
 
-.Overlay {
-  display: flex;
+/* stylelint-disable-next-line selector-pseudo-class-no-unknown */
+.Overlay[popover]:not(:popover-open) {
+  display: none
 }
 
 anchored-position.not-anchored::backdrop {