@webjsdev/ui 0.3.9 → 0.3.11

package/packages/registry/components/dropdown-menu.ts

@@ -41,7 +41,12 @@
  *
  * Events:
  *   `ui-open-change` on <ui-dropdown-menu>: `{ detail: { open } }` after a transition.
- *   `ui-item-select` bubbled by an item: `{ detail: { value, item } }` on activation.
+ *   `ui-item-select` bubbled by an item on activation, CANCELABLE:
+ *     `{ detail: { value, item, type, checked } }`. `checked` is the state the
+ *     item has settled on, so a checkbox / radio listener reads it directly.
+ *     Calling `preventDefault()` keeps the menu OPEN (the parity shape for
+ *     shadcn's `onSelect={e => e.preventDefault()}`), which is what a
+ *     multi-select checkbox menu wants.
  *
  * Programmatic API on <ui-dropdown-menu>: `.show()` · `.hide()` · `.toggle()`.
  *
@@ -51,9 +56,27 @@
  *   ArrowLeft             inside a submenu: close it, refocus the sub-trigger
  *   Home / End            first / last item
  *   Enter / Space         activate focused item
- *   Escape                close menu (or close current submenu first)
+ *   Escape                close the menu that holds focus (a submenu first,
+ *                         refocusing its sub-trigger) and refocus the trigger
  *   Tab                   close menu and proceed with normal tab order
  *
+ * A11y (owned by the element, nothing to supply):
+ *   The trigger gets `aria-haspopup` / `aria-expanded` / `aria-controls`, the
+ *   panel is a `role="menu"` labelled back by the trigger, and a disabled item
+ *   reflects `aria-disabled`. EVERY close path leaves focus somewhere sensible
+ *   rather than dropping it to `<body>`: Escape, Tab, and item activation
+ *   return focus to the trigger, and so does an outside click that did not put
+ *   focus anywhere itself. An outside click ON another control leaves focus on
+ *   that control, since the user chose it.
+ *   A `type="checkbox"` / `type="radio"` item carries
+ *   `role="menuitemcheckbox"` / `role="menuitemradio"` plus `aria-checked`.
+ *   What you DO supply: a name for a radio set, as `aria-label` on the
+ *   enclosing `<ui-dropdown-menu-group>` (APG asks a menuitemradio set to sit
+ *   in a labelled group; the group forwards the name onto its `role="group"`).
+ *   Put it in the MARKUP. The group declares no reactive props, so it renders
+ *   once and its `aria-label` / `aria-labelledby` are not observed attributes: a
+ *   name set on the host after mount is never picked up.
+ *
  * Design tokens used: --popover, --popover-foreground, --accent,
  * --accent-foreground, --destructive, --muted-foreground, --border.
  *
@@ -77,6 +100,38 @@
  *     <ui-dropdown-menu-item variant="destructive">Sign out</ui-dropdown-menu-item>
  *   </ui-dropdown-menu-content>
  * </ui-dropdown-menu>
+ *
+ * <!-- Checkbox items. Read the new state off the event's detail.checked. -->
+ * <ui-dropdown-menu @ui-item-select=${onSelect}>
+ *   <ui-dropdown-menu-trigger>
+ *     <button class=${buttonClass({ variant: 'outline' })}>View</button>
+ *   </ui-dropdown-menu-trigger>
+ *   <ui-dropdown-menu-content>
+ *     <ui-dropdown-menu-item type="checkbox" value="status" checked>
+ *       Status bar
+ *     </ui-dropdown-menu-item>
+ *     <ui-dropdown-menu-item type="checkbox" value="activity">
+ *       Activity bar
+ *     </ui-dropdown-menu-item>
+ *   </ui-dropdown-menu-content>
+ * </ui-dropdown-menu>
+ *
+ * <!-- A multi-select menu cancels the event so the menu stays open:
+ *      const onSelect = (e) => { e.preventDefault(); save(e.detail); };  -->
+ *
+ * <!-- Radio items: one checked per group. Name the set on the group. -->
+ * <ui-dropdown-menu>
+ *   <ui-dropdown-menu-trigger>
+ *     <button class=${buttonClass({ variant: 'outline' })}>Panel</button>
+ *   </ui-dropdown-menu-trigger>
+ *   <ui-dropdown-menu-content>
+ *     <ui-dropdown-menu-group aria-label="Panel position">
+ *       <ui-dropdown-menu-item type="radio" value="top" checked>Top</ui-dropdown-menu-item>
+ *       <ui-dropdown-menu-item type="radio" value="bottom">Bottom</ui-dropdown-menu-item>
+ *       <ui-dropdown-menu-item type="radio" value="right">Right</ui-dropdown-menu-item>
+ *     </ui-dropdown-menu-group>
+ *   </ui-dropdown-menu-content>
+ * </ui-dropdown-menu>
  * ```
  */
 import { WebComponent, html, unsafeHTML, signal, prop } from '@webjsdev/core';
@@ -117,8 +172,22 @@ export const dropdownMenuSubContentClass = (): string =>
 const CHEVRON_RIGHT_SVG =
   '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="ml-auto size-4" aria-hidden="true"><polyline points="9 18 15 12 9 6"></polyline></svg>';
 
+// Checked-state indicators for a checkbox / radio item. Decorative: the state
+// they draw is announced from aria-checked, so both are aria-hidden.
+const CHECK_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4" aria-hidden="true"><polyline points="20 6 9 17 4 12"></polyline></svg>';
+
+const RADIO_DOT_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" class="size-2" aria-hidden="true"><circle cx="12" cy="12" r="12"></circle></svg>';
+
 const SUB_CLOSE_DELAY = 200;
 
+// Every role a focusable menu item can carry. A checkbox / radio item is NOT
+// role="menuitem", so a bare [role="menuitem"] query silently skips it and the
+// item drops out of arrow nav, typeahead, and the focus-first-item-on-open.
+const MENU_ITEM = ':is([role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"])';
+const ENABLED_MENU_ITEM = `${MENU_ITEM}:not([data-disabled])`;
+
 // --------------------------------------------------------------------------
 // <ui-dropdown-menu>
 // --------------------------------------------------------------------------
@@ -130,6 +199,7 @@ export class UiDropdownMenu extends WebComponent({
   _typeBufferTimer: number | undefined;
 
   _docClickHandler = (e: MouseEvent): void => this._onDocClick(e);
+  _docPointerDownHandler = (e: Event): void => this._onDocPointerDown(e);
   _keyHandler = (e: KeyboardEvent): void => this._onKeyDown(e);
   _resizeHandler = (): void => this._reposition();
 
@@ -150,6 +220,30 @@ export class UiDropdownMenu extends WebComponent({
   show(): void { this.open = true; }
   hide(): void { this.open = false; }
 
+  // APG Menu Button requires Escape, Tab, item activation, AND an outside-click
+  // dismiss to close the menu without stranding focus. Without this, focus is
+  // sitting on an item inside a popover="manual" panel, so hiding the panel
+  // drops focus to <body> and a keyboard user loses their place entirely.
+  //
+  // The restore is GUARDED, because an outside click that deliberately moved
+  // focus to another control must not have focus yanked back to the trigger.
+  //
+  // Focus moves BEFORE the panel hides. Hiding a popover whose descendant
+  // holds focus makes the engine run its own focus fixup, and moving out
+  // first means the trigger is the final focus rather than a target the
+  // fixup then overrides.
+  _closeAndRestoreFocus(): void {
+    if (this._focusIsInside()) this._triggerControl()?.focus();
+    this.hide();
+  }
+
+  _focusIsInside(): boolean {
+    if (typeof document === 'undefined') return false;
+    const active = document.activeElement;
+    if (!active || active === document.body) return false;
+    return this.contains(active);
+  }
+
   render() {
     return html`<div data-slot="dropdown-menu" data-state=${this.open ? 'open' : 'closed'}>
       <slot></slot>
@@ -216,6 +310,32 @@ export class UiDropdownMenu extends WebComponent({
     if (!menu.hasAttribute('aria-label') && !menu.hasAttribute('aria-labelledby')) {
       menu.setAttribute('aria-labelledby', ensureId(control, 'ui-menu-trigger'));
     }
+    this._wireSubmenuAria();
+  }
+
+  // A SUBMENU is a role="menu" too, and APG asks for it to be labelled by the
+  // menuitem that opens it, with that menuitem pointing back via aria-controls.
+  // Only the root panel was wired, so every submenu shipped as an unnamed menu.
+  _wireSubmenuAria(): void {
+    this.querySelectorAll<HTMLElement>('ui-dropdown-menu-sub').forEach((sub) => {
+      // NOT `:scope >`: the sub renders its own wrapper div with a <slot>, so the
+      // trigger and content are grandchildren, not direct children. Match on the
+      // nearest enclosing sub instead, which also keeps a NESTED submenu's nodes
+      // from being wired to its outer sub.
+      const owns = (el: Element | null): boolean =>
+        !!el && el.closest('ui-dropdown-menu-sub') === sub;
+      const trigger = Array.from(
+        sub.querySelectorAll<HTMLElement>(`ui-dropdown-menu-sub-trigger ${MENU_ITEM}`),
+      ).find((el) => owns(el.closest('ui-dropdown-menu-sub-trigger')));
+      const panel = Array.from(
+        sub.querySelectorAll<HTMLElement>('ui-dropdown-menu-sub-content [role="menu"]'),
+      ).find((el) => owns(el.closest('ui-dropdown-menu-sub-content')));
+      if (!trigger || !panel) return;
+      trigger.setAttribute('aria-controls', ensureId(panel, 'ui-submenu'));
+      if (!panel.hasAttribute('aria-label') && !panel.hasAttribute('aria-labelledby')) {
+        panel.setAttribute('aria-labelledby', ensureId(trigger, 'ui-submenu-trigger'));
+      }
+    });
   }
 
   _content(): HTMLElement | null {
@@ -248,21 +368,24 @@ export class UiDropdownMenu extends WebComponent({
 
   _setup(): void {
     this._reposition();
+    document.addEventListener('pointerdown', this._docPointerDownHandler, true);
     document.addEventListener('click', this._docClickHandler);
     document.addEventListener('keydown', this._keyHandler);
     window.addEventListener('resize', this._resizeHandler);
     window.addEventListener('scroll', this._resizeHandler, true);
     queueMicrotask(() => {
       const first = this.querySelector<HTMLElement>(
-        'ui-dropdown-menu-item:not([data-disabled]) [role="menuitem"]',
+        `ui-dropdown-menu-item:not([data-disabled]) ${MENU_ITEM}`,
       );
       first?.focus();
     });
   }
 
   _teardown(): void {
+    document.removeEventListener('pointerdown', this._docPointerDownHandler, true);
     document.removeEventListener('click', this._docClickHandler);
     document.removeEventListener('keydown', this._keyHandler);
+    this._focusWasInsideAtPointerDown = false;
     window.removeEventListener('resize', this._resizeHandler);
     window.removeEventListener('scroll', this._resizeHandler, true);
     this.querySelectorAll<UiDropdownMenuSub>('ui-dropdown-menu-sub[open]').forEach(
@@ -270,28 +393,80 @@ export class UiDropdownMenu extends WebComponent({
     );
   }
 
+  // Sampled on POINTERDOWN, before the browser moves focus for the click. By
+  // the time the click handler runs, a click on a non-focusable area has often
+  // already blurred the focused menu item to <body>, so a check made there
+  // cannot tell "clicked away from everything" (focus should go back to the
+  // trigger) from "clicked another control" (leave focus where the user put it).
+  _focusWasInsideAtPointerDown = false;
+
+  _onDocPointerDown(e: Event): void {
+    if (!this.open) return;
+    if (e.composedPath().some((n) => n === this)) return;
+    this._focusWasInsideAtPointerDown = this._focusIsInside();
+  }
+
   _onDocClick(e: MouseEvent): void {
     if (!this.open) return;
     if (e.composedPath().some((n) => n === this)) return;
+    // An outside click dismisses the menu, and it is still a close of a
+    // popover="manual" panel, so it owes the same focus care as Escape: leaving
+    // focus on an item that is about to become display:none drops it to <body>.
+    // Restore only when the click did not land focus somewhere itself.
+    const active = typeof document !== 'undefined' ? document.activeElement : null;
+    const clickTookFocus = !!active && active !== document.body && !this.contains(active);
+    if (this._focusWasInsideAtPointerDown && !clickTookFocus) {
+      this._triggerControl()?.focus();
+    }
+    this._focusWasInsideAtPointerDown = false;
     this.hide();
   }
 
   _onKeyDown(e: KeyboardEvent): void {
     if (!this.open) return;
-    if (e.key === 'Escape') {
-      e.preventDefault();
-      this.hide();
-      return;
-    }
 
     // Active context = nearest content / sub-content panel owning focus.
     // Scoping arrow nav avoids walking into siblings of a different submenu.
+    // Computed before Escape / Tab because both need to know which panel holds
+    // focus, and neither may bail when focus is outside the menu entirely.
     const active = document.activeElement as HTMLElement | null;
     const context = active?.closest('[role="menu"]') as HTMLElement | null;
+
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      // APG: Escape closes the menu that CONTAINS focus and returns focus to
+      // whatever opened it. Inside a submenu panel that is the submenu and its
+      // sub-trigger, so the root menu stays open (the JSDoc's "close current
+      // submenu first"). Focus on the sub-trigger itself is focus in the ROOT
+      // panel, so that case closes the whole menu, which is why this reads the
+      // panel rather than walking up to any open <ui-dropdown-menu-sub>.
+      const subContent = context?.closest('ui-dropdown-menu-sub-content');
+      const sub = subContent?.closest('ui-dropdown-menu-sub') as UiDropdownMenuSub | null;
+      if (sub) {
+        sub.querySelector<HTMLElement>(`ui-dropdown-menu-sub-trigger ${MENU_ITEM}`)?.focus();
+        sub.hide();
+        return;
+      }
+      this._closeAndRestoreFocus();
+      return;
+    }
+
+    if (e.key === 'Tab') {
+      // JSDoc contract: Tab closes the menu and proceeds with the normal tab
+      // order, so the default is deliberately NOT prevented. Focus is restored
+      // to the trigger first because the items are tabindex="-1" inside a
+      // top-layer panel that is about to be display:none, so tabbing onward
+      // from there has no sensible next element. Moving to the trigger (which
+      // IS in the tab sequence) means the browser's own Tab then advances to
+      // the element after it, which is what APG asks for.
+      this._closeAndRestoreFocus();
+      return;
+    }
+
     if (!context) return;
 
     const items = Array.from(
-      context.querySelectorAll<HTMLElement>('[role="menuitem"]:not([data-disabled])'),
+      context.querySelectorAll<HTMLElement>(ENABLED_MENU_ITEM),
     ).filter((it) => it.closest('[role="menu"]') === context);
     if (items.length === 0) return;
     const idx = active ? items.indexOf(active) : -1;
@@ -314,15 +489,10 @@ export class UiDropdownMenu extends WebComponent({
       if (subTrigger) {
         e.preventDefault();
         const sub = subTrigger.closest('ui-dropdown-menu-sub') as UiDropdownMenuSub | null;
-        if (sub) {
-          sub.show();
-          queueMicrotask(() => {
-            const firstSubItem = sub.querySelector<HTMLElement>(
-              'ui-dropdown-menu-sub-content [role="menuitem"]:not([data-disabled])',
-            );
-            firstSubItem?.focus();
-          });
-        }
+        // The sub owns the open-then-focus sequencing: its panel is
+        // popover="manual" and only becomes visible a microtask later, so
+        // focusing from here races the reveal and loses (see the method).
+        sub?.openAndFocusFirstItem();
       }
     } else if (e.key === 'ArrowLeft') {
       // Inside a sub-content: close the submenu and refocus its trigger.
@@ -330,11 +500,45 @@ export class UiDropdownMenu extends WebComponent({
         e.preventDefault();
         const sub = context.closest('ui-dropdown-menu-sub') as UiDropdownMenuSub | null;
         const trigger = sub?.querySelector<HTMLElement>(
-          'ui-dropdown-menu-sub-trigger [role="menuitem"]',
+          `ui-dropdown-menu-sub-trigger ${MENU_ITEM}`,
         );
-        sub?.hide();
         trigger?.focus();
+        sub?.hide();
+      }
+    } else if (e.key === 'Enter' || e.key === ' ') {
+      // A menu item is a <div role="menuitem">, and a div gets NO native
+      // activation, so Enter / Space have to be synthesized here. Without this
+      // the keyboard cannot activate any item at all, and a checkable item,
+      // whose ONLY state transition is activation, cannot be toggled.
+      //
+      // Activation applies to a MENU ITEM only. A control the author slotted
+      // into the panel (a filter input, a plain button) is inside [role="menu"]
+      // too, so preventing Space unconditionally would swallow it there with
+      // nothing to handle it, and the user could not type a space into their own
+      // input. Bail before touching the event when the focus is not an item.
+      const subTrigger = active?.closest('ui-dropdown-menu-sub-trigger');
+      const activeItem = active?.closest('ui-dropdown-menu-item') as UiDropdownMenuItem | null;
+      if (!subTrigger && !activeItem) return;
+      // Space while a typeahead search is in flight belongs to the SEARCH, or a
+      // multi-word item is unreachable past its first word ("Status bar" could
+      // never be disambiguated from "Status line"). Radix draws the same line.
+      // Enter always activates.
+      if (e.key === ' ' && this._typeBuffer) {
+        this._typeahead(e, items);
+        return;
+      }
+      // Space otherwise MUST be prevented, or it falls through to typeahead,
+      // matches nothing, and scrolls the page underneath the open menu.
+      e.preventDefault();
+      if (subTrigger) {
+        // Same as ArrowRight on a sub-trigger: open it and move focus in.
+        if (!subTrigger.hasAttribute('data-disabled')) {
+          const sub = subTrigger.closest('ui-dropdown-menu-sub') as UiDropdownMenuSub | null;
+          sub?.openAndFocusFirstItem();
+        }
+        return;
       }
+      if (activeItem && !activeItem.hasAttribute('data-disabled')) activeItem._select();
     } else if (e.key.length === 1 && !e.metaKey && !e.ctrlKey && !e.altKey) {
       this._typeahead(e, items);
     }
@@ -397,6 +601,13 @@ UiDropdownMenuContent.register('ui-dropdown-menu-content');
 export class UiDropdownMenuItem extends WebComponent({
   variant: prop<'default' | 'destructive'>(String, { reflect: true }),
   inset: Boolean,
+  // `type` is read from the authored attribute and never written back: an
+  // unreflected default keeps a plain item's markup free of a type="" that
+  // means nothing. `checked` reflects so the state is readable and settable
+  // as an attribute, the same contract <ui-toggle>'s `pressed` has.
+  type: prop<'' | 'checkbox' | 'radio'>(String),
+  checked: prop(Boolean, { reflect: true }),
+  value: prop(String, { reflect: true }),
 }) {
   // Keyboard / pointer highlight state for the own-rendered menuitem. A
   // local signal bound with ?data-highlighted keeps the highlight in the
@@ -408,6 +619,9 @@ export class UiDropdownMenuItem extends WebComponent({
     super();
     this.variant = 'default';
     this.inset = false;
+    this.type = '';
+    this.checked = false;
+    this.value = '';
   }
 
   render() {
@@ -416,6 +630,40 @@ export class UiDropdownMenuItem extends WebComponent({
     // inner menuitem as both data-disabled (CSS) and aria-disabled, so the
     // state also reaches assistive tech.
     const disabled = typeof this.hasAttribute === 'function' && this.hasAttribute('data-disabled');
+    const checkbox = this.type === 'checkbox';
+    const radio = this.type === 'radio';
+    // The role is what tells a screen reader this is a checkable control at
+    // all, and aria-checked is what carries the state. Neither belongs on a
+    // plain item, where aria-checked is not an allowed attribute.
+    //
+    // Hence TWO templates rather than one with conditional holes: a null hole
+    // does NOT omit an attribute on the server (the server renderer
+    // stringifies the value), so a single template would ship every plain item
+    // as `role="menuitem" aria-checked="" data-state=""`, carrying the exact
+    // disallowed attribute this branch exists to keep off it, and disagreeing
+    // with the hydrated DOM where the client renderer removes it. The two
+    // shapes differ by the indicator anyway.
+    if (checkbox || radio) {
+      return html`<div
+        data-slot=${`dropdown-menu-${this.type}-item`}
+        role=${checkbox ? 'menuitemcheckbox' : 'menuitemradio'}
+        tabindex="-1"
+        data-variant=${this.variant}
+        ?data-inset=${this.inset}
+        ?data-disabled=${disabled}
+        aria-disabled=${disabled ? 'true' : 'false'}
+        aria-checked=${String(this.checked)}
+        data-state=${this.checked ? 'checked' : 'unchecked'}
+        ?data-highlighted=${this.#highlighted.get()}
+        class=${checkbox ? dropdownMenuCheckboxItemClass() : dropdownMenuRadioItemClass()}
+        @click=${this._onClick}
+        @pointerenter=${this._onPointerEnter}
+        @focus=${this._onFocus}
+        @blur=${this._onBlur}
+      ><span
+        class="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center"
+      >${this.checked ? unsafeHTML(radio ? RADIO_DOT_SVG : CHECK_SVG) : ''}</span><slot></slot></div>`;
+    }
     return html`<div
       data-slot="dropdown-menu-item"
       role="menuitem"
@@ -436,9 +684,56 @@ export class UiDropdownMenuItem extends WebComponent({
   _onClick = (e: Event): void => {
     const el = e.currentTarget as HTMLElement;
     if (el.hasAttribute('data-disabled')) return;
-    (this.closest('ui-dropdown-menu') as UiDropdownMenu | null)?.hide();
+    this._select();
   };
 
+  // Activation: flip checkbox / radio state, announce the selection, then
+  // close. The event is cancelable, so a listener calling preventDefault()
+  // keeps the menu open, which is the parity shape for Radix's
+  // onSelect(e => e.preventDefault()) that a multi-select menu relies on.
+  _select(): void {
+    if (this.type === 'checkbox') this.checked = !this.checked;
+    else if (this.type === 'radio') this._selectRadio();
+    const proceed = this.dispatchEvent(
+      new CustomEvent('ui-item-select', {
+        detail: { value: this.value, item: this, type: this.type, checked: this.checked },
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+    if (!proceed) return;
+    (this.closest('ui-dropdown-menu') as UiDropdownMenu | null)?._closeAndRestoreFocus();
+  }
+
+  // The radio set is the nearest <ui-dropdown-menu-group>, which is the APG
+  // grouping element for menuitemradio, falling back to the panel so an
+  // ungrouped set still behaves like one set rather than N independent items.
+  _radioScope(): Element | null {
+    if (typeof this.closest !== 'function') return null;
+    return (
+      this.closest('ui-dropdown-menu-group') ??
+      this.closest('ui-dropdown-menu-sub-content') ??
+      this.closest('ui-dropdown-menu-content')
+    );
+  }
+
+  _selectRadio(): void {
+    const scope = this._radioScope();
+    if (!scope) {
+      this.checked = true;
+      return;
+    }
+    // Filter on the PROPERTY, not a [type="radio"] attribute selector: `type`
+    // is unreflected, so an item configured through the property alone would
+    // be invisible to an attribute query and survive as a second checked item.
+    // The scope re-check keeps a nested group's items out of this set.
+    Array.from(scope.querySelectorAll<UiDropdownMenuItem>('ui-dropdown-menu-item'))
+      .filter((it) => it.type === 'radio' && it._radioScope() === scope)
+      .forEach((it) => {
+        it.checked = it === this;
+      });
+  }
+
   _onPointerEnter = (e: Event): void => {
     const el = e.currentTarget as HTMLElement;
     if (el.hasAttribute('data-disabled')) return;
@@ -509,7 +804,36 @@ UiDropdownMenuShortcut.register('ui-dropdown-menu-shortcut');
 // --------------------------------------------------------------------------
 
 export class UiDropdownMenuGroup extends WebComponent {
+  // role="group", NOT role="radiogroup". radiogroup is the grouping role for
+  // role="radio"; the grouping role ARIA specifies for menuitemradio is plain
+  // group, so a radio set inside this element is already correctly grouped.
   render() {
+    // The group carries the name of the set ("Sort by", "Panel position"), and
+    // the name has to be on the element that holds role="group" to be exposed.
+    // Forward it off the host so an author writes it where the tag is.
+    //
+    // Branched, not held in a null hole: a null hole does NOT omit an attribute
+    // on the server, so an unnamed group would ship
+    // `role="group" aria-label="" aria-labelledby=""`, an empty IDREF list and
+    // an empty name on an element that simply has no name.
+    const attr = (n: string): string | null =>
+      typeof this.getAttribute === 'function' ? this.getAttribute(n) : null;
+    const labelledBy = attr('aria-labelledby');
+    const label = attr('aria-label');
+    if (labelledBy) {
+      return html`<div
+        data-slot="dropdown-menu-group"
+        role="group"
+        aria-labelledby=${labelledBy}
+      ><slot></slot></div>`;
+    }
+    if (label) {
+      return html`<div
+        data-slot="dropdown-menu-group"
+        role="group"
+        aria-label=${label}
+      ><slot></slot></div>`;
+    }
     return html`<div
       data-slot="dropdown-menu-group"
       role="group"
@@ -541,6 +865,43 @@ export class UiDropdownMenuSub extends WebComponent({
   hide(): void { this._cancelClose(); this.open = false; }
   toggle(): void { if (this.open) this.hide(); else this.show(); }
 
+  // ArrowRight on a sub-trigger must open the submenu AND move focus to its
+  // first item (APG, and what this component's JSDoc promises). The focus
+  // cannot simply be queued next to show(): the panel is popover="manual" and
+  // only becomes visible in _afterRender one microtask later, and focus() on a
+  // still-display:none element is silently a no-op that nothing retries. So
+  // record the intent and consume it once the panel is genuinely up.
+  _focusFirstOnOpen = false;
+
+  openAndFocusFirstItem(): void {
+    this._focusFirstOnOpen = true;
+    this.show();
+    // Hover already opened it, so there is no open-change to ride on and
+    // _afterRender will not run. The panel is up, so consume the intent now.
+    if (this._panelIsOpen()) this._consumeFocusFirst();
+  }
+
+  _panelIsOpen(): boolean {
+    const panel = this.querySelector<HTMLElement & { showPopover?: () => void }>(
+      'ui-dropdown-menu-sub-content [popover]',
+    );
+    // Gate on showPopover, not just on matches, like the two sibling call sites.
+    // `:popover-open` is an unknown pseudo-class where the Popover API is
+    // absent, so matches() THROWS SyntaxError there. This runs synchronously
+    // from the document keydown handler, so the throw would escape _onKeyDown
+    // and take out all submenu keyboard handling on such an engine.
+    if (!panel || typeof panel.showPopover !== 'function') return false;
+    return typeof panel.matches === 'function' && panel.matches(':popover-open');
+  }
+
+  _consumeFocusFirst(): void {
+    if (!this._focusFirstOnOpen) return;
+    this._focusFirstOnOpen = false;
+    this.querySelector<HTMLElement>(
+      `ui-dropdown-menu-sub-content ${ENABLED_MENU_ITEM}`,
+    )?.focus();
+  }
+
   render() {
     return html`<div
       data-slot="dropdown-menu-sub"
@@ -569,7 +930,14 @@ export class UiDropdownMenuSub extends WebComponent({
         else if (!this.open && p.matches(':popover-open')) p.hidePopover();
       }
     }
-    if (this.open) this._position();
+    if (this.open) {
+      this._position();
+      this._consumeFocusFirst();
+    } else {
+      // Closed before the intent was consumed (a hover-close raced the key).
+      // Dropping it keeps a later hover-open from stealing focus into the panel.
+      this._focusFirstOnOpen = false;
+    }
   }
 
   _cancelCloseHandler = (): void => this._cancelClose();