@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/Dialog/DialogHeader.tsx

@@ -65,7 +65,9 @@ export interface DialogHeaderProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   /**
    * The title of the dialog.
-   * This title receives focus when the dialog opens for screen reader accessibility.
+   * This title receives focus when the dialog opens for screen reader
+   * accessibility, and names the parent Dialog via aria-labelledby unless the
+   * consumer passes an explicit aria-label/aria-labelledby to the Dialog.
    */
   title: string;
 
@@ -105,7 +107,8 @@ export interface DialogHeaderProps extends BaseProps<HTMLDivElement> {
  * Renders a title that receives focus when a modal dialog opens (for screen reader accessibility)
  * and an optional close button. Inline documentation previews suppress this autofocus.
  * The title is an h2 element with tabIndex={-1} so it can be programmatically focused but
- * doesn't appear in the tab order.
+ * doesn't appear in the tab order. The title also names the parent Dialog via
+ * aria-labelledby (unless the Dialog receives an explicit aria-label/aria-labelledby).
  *
  * Uses LayoutHeader internally for consistent styling with other layout headers.
  *
@@ -137,10 +140,13 @@ export function DialogHeader({
   const titleRef = useRef<HTMLHeadingElement>(null);
   const dialogContext = useDialogContext();
   const shouldAutoFocus = dialogContext?.isInline !== true;
+  const titleId = dialogContext?.titleId;
 
   // Auto-focus the title when mounted for screen reader accessibility.
   // Inline dialogs are documentation/showcase previews, so suppress focus to
   // avoid stealing scroll position from the surrounding page.
+  // The parent Dialog detects this title (by `titleId`) via a callback ref to
+  // set its default aria-labelledby — no registration handshake needed here.
   useEffect(() => {
     if (shouldAutoFocus && titleRef.current) {
       titleRef.current.focus();
@@ -162,6 +168,7 @@ export function DialogHeader({
         <div {...stylex.props(styles.titleWrapper)}>
           <Heading
             ref={titleRef}
+            id={titleId}
             level={2}
             tabIndex={-1}
             xstyle={styles.titleFocusable}>

package/src/Divider/Divider.tsx

@@ -172,6 +172,7 @@ export function Divider({
   return (
     <div
       ref={ref}
+      {...props}
       role="separator"
       aria-orientation={orientation}
       {...mergeProps(
@@ -186,8 +187,7 @@ export function Divider({
         ),
         className,
         style,
-      )}
-      {...props}>
+      )}>
       <div
         {...stylex.props(
           isHorizontal ? lineStyles.horizontalLine : lineStyles.verticalLine,

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -613,3 +613,232 @@ describe('DropdownMenu compound mode', () => {
     ).toBeInTheDocument();
   });
 });
+
+describe('DropdownMenu keyboard access for menuitemradio/menuitemcheckbox (#3829)', () => {
+  it('arrow navigation reaches consumer-rendered menuitemradio and menuitemcheckbox items', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+          Archived
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    screen.getByRole('menuitem', {name: 'Edit', hidden: true}).focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('activates a focused menuitemradio with Enter and a menuitemcheckbox with Space', async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    const onToggle = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div
+          role="menuitemradio"
+          tabIndex={-1}
+          aria-checked="false"
+          onClick={onSelect}>
+          Newest
+        </div>
+        <div
+          role="menuitemcheckbox"
+          tabIndex={-1}
+          aria-checked="false"
+          onClick={onToggle}>
+          Archived
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}).focus();
+    fireEvent.keyDown(menu, {key: 'Enter'});
+    expect(onSelect).toHaveBeenCalledTimes(1);
+
+    screen
+      .getByRole('menuitemcheckbox', {name: 'Archived', hidden: true})
+      .focus();
+    fireEvent.keyDown(menu, {key: ' '});
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('typeahead matches a menuitemradio label', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+          Archived
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('typeahead matches a menuitemcheckbox label', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+          Archived
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'a'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('typeahead skips an aria-disabled item and matches the next enabled label', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-disabled="true">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+          Nightly
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    // Anchor the search on 'Edit' so typeahead scans forward and meets the
+    // disabled 'Newest' (also an 'n' match) before the enabled 'Nightly'.
+    // This pins the `:not([aria-disabled="true"])` in MENU_ITEM_SELECTOR: the
+    // menus never pass useTypeahead's `isDisabled` option, so that clause is
+    // the only thing keeping disabled rows out of the typeahead list. An
+    // arrow-key test cannot cover it — useListFocus re-filters disabled items
+    // independently, so arrow navigation is guarded twice over.
+    // The disabled row keeps tabIndex={-1} on purpose: it stays focusable, so
+    // the selector clause is the sole reason focus skips it.
+    screen.getByRole('menuitem', {name: 'Edit', hidden: true}).focus();
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Nightly', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Sort'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <div role="menuitemradio" tabIndex={-1} aria-disabled="true">
+          Newest
+        </div>
+        <div role="menuitemcheckbox" tabIndex={-1} aria-disabled="true">
+          Archived
+        </div>
+        <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+          Oldest
+        </div>
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    screen.getByRole('menuitem', {name: 'Edit', hidden: true}).focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('moves focus to the item the mouse hovers, keeping a single highlight', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <DropdownMenuItem label="Duplicate" onClick={() => {}} />
+        <DropdownMenuItem label="Delete" onClick={() => {}} />
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    // Keyboard focus starts on the first item.
+    const edit = screen.getByRole('menuitem', {name: 'Edit', hidden: true});
+    const del = screen.getByRole('menuitem', {name: 'Delete', hidden: true});
+    edit.focus();
+    expect(edit).toHaveFocus();
+
+    // A mouse hover over another item moves focus to it, so the single
+    // focus-driven highlight follows the pointer instead of leaving two.
+    fireEvent.pointerMove(del, {pointerType: 'mouse'});
+    expect(del).toHaveFocus();
+    expect(edit).not.toHaveFocus();
+  });
+
+  it('does not move focus on hover for a disabled item', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <DropdownMenuItem label="Delete" isDisabled onClick={() => {}} />
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const edit = screen.getByRole('menuitem', {name: 'Edit', hidden: true});
+    const del = screen.getByRole('menuitem', {name: 'Delete', hidden: true});
+    edit.focus();
+
+    fireEvent.pointerMove(del, {pointerType: 'mouse'});
+    expect(edit).toHaveFocus();
+  });
+
+  it('does not move focus for a non-mouse (touch) pointer', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <DropdownMenuItem label="Delete" onClick={() => {}} />
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const edit = screen.getByRole('menuitem', {name: 'Edit', hidden: true});
+    const del = screen.getByRole('menuitem', {name: 'Delete', hidden: true});
+    edit.focus();
+
+    fireEvent.pointerMove(del, {pointerType: 'touch'});
+    expect(edit).toHaveFocus();
+  });
+});

package/src/DropdownMenu/DropdownMenu.tsx

@@ -38,7 +38,11 @@ import {Icon} from '../Icon';
 import type {IconType} from '../Icon';
 
 import {renderDropdownItems} from './renderDropdownItems';
-import {MENU_ITEM_ROLES, MENU_ITEM_SELECTOR} from './menuItemRoles';
+import {
+  MENU_ITEM_ROLES,
+  MENU_ITEM_SELECTOR,
+  MENU_BOUNDARY_SELECTOR,
+} from './menuItemRoles';
 import {
   DropdownMenuContext,
   type DropdownMenuContextValue,
@@ -100,6 +104,12 @@ export interface DropdownMenuItemData {
   onClick?: () => void;
   isDisabled?: boolean;
   icon?: ReactNode | IconType;
+  /**
+   * Nested submenu entries. When present, this row becomes a submenu (a
+   * flyout revealing `items`) instead of a leaf action — no separate item
+   * "type" is needed. Data-mode parity for the compound DropdownMenuSubMenu API.
+   */
+  items?: DropdownMenuOption[];
 }
 
 export interface DropdownMenuDivider {
@@ -200,6 +210,14 @@ export function DropdownMenu({
   const items = ('items' in props ? props.items : undefined) ?? [];
   const children = props.children;
 
+  // Extract BaseProps pass-throughs (aria-*, id, event handlers) from the
+  // discriminated-union rest bag so they can be forwarded to the menu element.
+  const {
+    items: _items,
+    children: _children,
+    ...rest
+  } = props as Record<string, unknown>;
+
   const menuId = useId();
   const menuSize = button.size ?? 'md';
   const buttonRef = useRef<HTMLButtonElement>(null);
@@ -265,23 +283,18 @@ export function DropdownMenu({
     handleKeyDown: listNavKeyDown,
     focusFirst,
     focusItem,
+    ownsEvent,
+    getItems: getMenuItems,
   } = useListFocus<HTMLDivElement>({
     itemSelector: MENU_ITEM_SELECTOR,
+    boundarySelector: MENU_BOUNDARY_SELECTOR,
     wrap: false,
     onEscape: closeMenu,
   });
 
   // First-character typeahead over the (enabled) menu items — jump to the next
-  // item whose label starts with the typed text (menus-11).
-  const getMenuItems = useCallback(
-    (): HTMLElement[] =>
-      listRef.current
-        ? Array.from(
-            listRef.current.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR),
-          )
-        : [],
-    [listRef],
-  );
+  // item whose label starts with the typed text (menus-11). Reuses the hook's
+  // scoped item collection so an inline submenu flyout's items aren't swept in.
   const typeahead = useTypeahead({
     getItemLabels: () => getMenuItems().map(el => el.textContent),
     onMatch: focusItem,
@@ -307,6 +320,11 @@ export function DropdownMenu({
   // Extend useListFocus with Enter/Space activation + typeahead
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      // A submenu flyout renders inline inside this menu; its key events bubble
+      // up here. Let that level own them — only handle events from this level.
+      if (!ownsEvent(e)) {
+        return;
+      }
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();
         const focused = document.activeElement as HTMLElement | null;
@@ -334,7 +352,7 @@ export function DropdownMenu({
       }
       listNavKeyDown(e);
     },
-    [listNavKeyDown, closeMenu, typeahead],
+    [listNavKeyDown, closeMenu, typeahead, ownsEvent],
   );
 
   const openAndFocus = useCallback(() => {
@@ -435,6 +453,7 @@ export function DropdownMenu({
 
       {popover.render(
         <div
+          {...rest}
           ref={listRef}
           id={menuId}
           role="menu"

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -23,11 +23,12 @@
  * checkmark uses the `check` icon from the active theme's icon registry.
  */
 
-import {useCallback, type ReactNode} from 'react';
+import {useCallback, type PointerEvent, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Item} from '../Item';
 import {useDropdownMenuContext} from './DropdownMenuContext';
+import {focusMenuItemOnHover} from './menuItemHover';
 import {
   colorVars,
   spacingVars,
@@ -47,7 +48,6 @@ const styles = stylex.create({
     backgroundColor: {
       default: 'transparent',
       ':focus': colorVars['--color-overlay-hover'],
-      ':hover': colorVars['--color-overlay-hover'],
     },
     cursor: 'pointer',
     outline: 'none',
@@ -152,8 +152,7 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
  *
  * @example
  * ```
- *  * import {DropdownMenuCheckboxItem} from '@astryxdesign/core/DropdownMenu';
- *
+ * import {DropdownMenuCheckboxItem} from '@astryxdesign/core/DropdownMenu';
  * <DropdownMenu button={{label: 'View'}}>
  *   <DropdownMenuCheckboxItem
  *     label="Show archived"
@@ -191,12 +190,18 @@ export function DropdownMenuCheckboxItem({
     }
   }, [isDisabled, onChange, value, hasCloseOnSelect, ctx]);
 
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
+    [isDisabled],
+  );
+
   return (
     <Item
       {...rest}
       role="menuitemcheckbox"
       aria-checked={value}
       tabIndex={isDisabled ? undefined : -1}
+      onPointerMove={handlePointerMove}
       marker={
         <span
           aria-hidden="true"

package/src/DropdownMenu/DropdownMenuItem.tsx

@@ -23,7 +23,7 @@
  * - /packages/cli/templates/blocks/components/DropdownMenu/ (showcase blocks)
  */
 
-import {useCallback, type ReactNode} from 'react';
+import {useCallback, type PointerEvent, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {renderIconSlot, type IconType} from '../Icon';
 import {Item} from '../Item';
@@ -36,6 +36,7 @@ import {
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useDropdownMenuContext} from './DropdownMenuContext';
+import {focusMenuItemOnHover} from './menuItemHover';
 import {themeProps} from '../utils/themeProps';
 
 const menuItemStyles = stylex.create({
@@ -51,11 +52,10 @@ const menuItemStyles = stylex.create({
     backgroundColor: {
       default: 'transparent',
       ':focus': colorVars['--color-overlay-hover'],
-      ':hover': colorVars['--color-overlay-hover'],
     },
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left',
+    textAlign: 'start',
     outline: 'none',
   },
   disabled: {
@@ -129,10 +129,16 @@ export function DropdownMenuItem({
     ctx?.closeMenu();
   }, [isDisabled, onClick, ctx]);
 
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
+    [isDisabled],
+  );
+
   return (
     <Item
       role="menuitem"
       tabIndex={isDisabled ? undefined : -1}
+      onPointerMove={handlePointerMove}
       startContent={
         icon
           ? renderIconSlot(icon, {size: 'sm', color: 'secondary'})

package/src/DropdownMenu/DropdownMenuRadioGroup.tsx

@@ -77,11 +77,10 @@ export interface DropdownMenuRadioGroupProps extends Omit<
  *
  * @example
  * ```
- *  * import {
+ * import {
  *   DropdownMenuRadioGroup,
  *   DropdownMenuRadioItem,
  * } from '@astryxdesign/core/DropdownMenu';
- *
  * <DropdownMenu button={{label: 'Sort'}}>
  *   <DropdownMenuRadioGroup value={sort} onChange={setSort} aria-label="Sort by">
  *     <DropdownMenuRadioItem value="newest" label="Newest" />

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -21,11 +21,12 @@
  * has no registry glyph).
  */
 
-import {useCallback, type ReactNode} from 'react';
+import {useCallback, type PointerEvent, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {renderIconSlot, type IconType} from '../Icon';
 import {Item} from '../Item';
 import {useDropdownMenuContext} from './DropdownMenuContext';
+import {focusMenuItemOnHover} from './menuItemHover';
 import {
   colorVars,
   spacingVars,
@@ -45,7 +46,6 @@ const styles = stylex.create({
     backgroundColor: {
       default: 'transparent',
       ':focus': colorVars['--color-overlay-hover'],
-      ':hover': colorVars['--color-overlay-hover'],
     },
     cursor: 'pointer',
     outline: 'none',
@@ -184,12 +184,18 @@ export function DropdownMenuRadioItem({
     }
   }, [isDisabled, groupCtx, value, menuCtx]);
 
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
+    [isDisabled],
+  );
+
   return (
     <Item
       {...rest}
       role="menuitemradio"
       aria-checked={isChecked}
       tabIndex={isDisabled ? undefined : -1}
+      onPointerMove={handlePointerMove}
       marker={
         <span
           aria-hidden="true"

package/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'DropdownMenuSubMenu',
+  subComponentOf: 'DropdownMenu',
+  displayName: 'Dropdown Menu Submenu',
+  isHiddenFromOverview: true,
+  description:
+    'A single menu row that reveals a nested flyout of its own items. The row adopts DropdownMenuItem semantics (label / icon / description / isDisabled); its children become the flyout content. Opens inline-end with viewport auto-flip; Right/Enter/Space opens and focuses the first item, Left/Escape closes and returns focus to the trigger (Right/Left swap in RTL). For data-driven menus, give a menu item a nested `items` array instead of using this component directly.',
+  playground: {
+    defaults: {label: 'Move to'},
+  },
+  props: [
+    {
+      name: 'label',
+      type: 'ReactNode',
+      description: 'Primary label text for the trigger row.',
+    },
+    {
+      name: 'icon',
+      type: 'IconType',
+      description:
+        'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
+    },
+    {
+      name: 'description',
+      type: 'ReactNode',
+      description: 'Secondary description text displayed below the label.',
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description:
+        'The flyout menu items — the same components used at the top level (DropdownMenuItem, nested DropdownMenuSubMenu, selectable items).',
+    },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      default: 'false',
+      description:
+        'A disabled submenu renders its trigger row but never opens the flyout.',
+    },
+    {
+      name: 'hasSpinner',
+      type: 'boolean',
+      default: 'false',
+      description:
+        'Show a spinner in place of the caret, e.g. while a lazy submenu’s children are loading.',
+    },
+    {
+      name: 'menuWidth',
+      type: 'number | string',
+      description: 'Fixed flyout width. Defaults to sizing to its content (min 160px).',
+    },
+    {
+      name: 'onOpenChange',
+      type: '(isOpen: boolean) => void',
+      description: 'Called when the flyout opens or closes.',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for the trigger row. Must be a stylex.create() value: not an inline style object like style={{}}.',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'DropdownMenuSubMenu',
+  isHiddenFromOverview: true,
+  displayName: 'Dropdown Menu Submenu',
+  description:
+    'menu row that reveals a nested flyout of its own children/items (single component, not Sub/SubTrigger/SubContent)',
+  propDescriptions: {
+    label: 'primary label text for the trigger row',
+    icon: 'icon before label',
+    description: 'secondary text below label',
+    children: 'flyout menu items (same components as top level)',
+    isDisabled: 'renders trigger but never opens',
+    hasSpinner: 'spinner instead of caret for async children',
+    menuWidth: 'fixed flyout width (default: content, min 160px)',
+    onOpenChange: 'called when flyout opens/closes',
+    xstyle: 'StyleX styles for the trigger row',
+  },
+};