@astryxdesign/core 0.7.1 → 0.7.2-canary.020e1fe

package/src/DropdownMenu/DropdownMenuGroup.doc.mjs

@@ -13,25 +13,86 @@ export const docs = {
     defaults: {title: 'Version history'},
   },
   description:
-    'A titled group of rows in a compound menu. Renders role="group" named by its heading; the heading is plain text, not a menuitem, so arrow keys and typeahead skip it. The data-driven equivalent is the `{type: "section", title, items}` entry in `items`; the heading shares its typography and theme target.',
+    'A group of rows in a compound menu. A visible title names role="group" through aria-labelledby; an omitted title leaves the group unnamed. The heading is not a menuitem, so arrow keys and typeahead skip it. Keep title content non-interactive and place controls in DropdownMenu header or footer. The data-driven equivalent is the `{type: "section", title, items}` entry in `items`; both forms share the heading treatment and theme target.',
+  usage: {
+    description:
+      'Use DropdownMenuGroup to give related compound-menu rows one visible and programmatic name. Use an untitled group only when a separate name would not help people understand the rows.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use short, descriptive title content that explains what the grouped rows have in common.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep the title non-interactive so every available action remains in the menu arrow-key order.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place buttons, links, fields, or other controls in title. Put them in DropdownMenu header or footer instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap rows that do not form a meaningful set; a group adds structure only when its relationship helps users.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Group',
+        required: true,
+        description:
+          'The role="group" wrapper containing the heading and menu rows.',
+      },
+      {
+        name: 'Heading',
+        required: false,
+        description:
+          'Visible non-interactive title content that names the group and carries the dropdown-menu-section-heading theme target.',
+      },
+      {
+        name: 'Rows',
+        required: false,
+        description:
+          'Menu items, selectable items, radio groups, or submenus owned by DropdownMenu.',
+      },
+    ],
+  },
   props: [
     {
       name: 'title',
       type: 'ReactNode',
       description:
-        "Heading shown above the rows and used as the group's accessible name. Omit for an unnamed group.",
+        "Non-interactive heading content shown above the rows and used as the group's accessible name. Omit for an unnamed group; place controls in DropdownMenu header or footer.",
     },
     {
       name: 'children',
       type: 'ReactNode',
       description:
-        'The rows of the group: DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuSubMenu.',
+        'The grouped rows: DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, or DropdownMenuSubMenu.',
     },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
-        'StyleX styles applied to the group wrapper. Must be a stylex.create() value: not an inline style object like style={{}}.',
+        'StyleX styles applied to the role="group" wrapper. Must be a stylex.create() value, not an inline style object.',
+    },
+    {
+      name: 'className',
+      type: 'string',
+      description: 'CSS class name applied to the role="group" wrapper.',
+    },
+    {
+      name: 'style',
+      type: 'React.CSSProperties',
+      description: 'Inline styles applied to the role="group" wrapper.',
+    },
+    {
+      name: 'ref',
+      type: 'React.Ref<HTMLDivElement>',
+      description: 'Ref forwarded to the role="group" wrapper.',
     },
   ],
   theming: {
@@ -39,15 +100,113 @@ export const docs = {
   },
 };
 
-export const docsDense = {
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docsZh = {
   name: 'DropdownMenuGroup',
-  isHiddenFromOverview: true,
+  subComponentOf: 'DropdownMenu',
   displayName: 'Dropdown Menu Group',
+  isHiddenFromOverview: true,
+  description:
+    '复合菜单中的一组菜单行。可见标题通过 aria-labelledby 为 role="group" 命名；省略标题时该组没有名称。标题不是 menuitem，因此方向键和预输入会跳过它。标题内容应保持非交互；控件应放在 DropdownMenu 的 header 或 footer 中。',
+  usage: {
+    description:
+      '使用 DropdownMenuGroup 为相关的复合菜单行提供同一个可见名称和无障碍名称。只有当名称能帮助理解这些菜单行时才使用分组。',
+    bestPractices: [
+      {guidance: true, description: '使用简短且能说明菜单行关系的标题。'},
+      {
+        guidance: true,
+        description: '保持标题非交互，让所有操作都位于菜单的方向键顺序中。',
+      },
+      {
+        guidance: false,
+        description:
+          '在标题中放置按钮、链接或输入控件；应改用 DropdownMenu 的 header 或 footer。',
+      },
+      {guidance: false, description: '对没有共同含义的菜单行进行分组。'},
+    ],
+    anatomy: [
+      {
+        name: '组',
+        required: true,
+        description: '包含标题和菜单行的 role="group" 包装元素。',
+      },
+      {
+        name: '标题',
+        required: false,
+        description: '用于命名分组的可见非交互标题内容。',
+      },
+      {
+        name: '菜单行',
+        required: false,
+        description: '由 DropdownMenu 持有的菜单项、可选项、单选组或子菜单。',
+      },
+    ],
+  },
+  props: [
+    {
+      name: 'title',
+      type: 'ReactNode',
+      description:
+        '显示在菜单行上方并作为分组无障碍名称的非交互标题内容。省略时分组无名称；控件应放在 DropdownMenu 的 header 或 footer 中。',
+    },
+    {name: 'children', type: 'ReactNode', description: '该分组中的菜单行。'},
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: '应用于 role="group" 包装元素的 StyleX 样式。',
+    },
+    {
+      name: 'className',
+      type: 'string',
+      description: '应用于 role="group" 包装元素的 CSS 类名。',
+    },
+    {
+      name: 'style',
+      type: 'React.CSSProperties',
+      description: '应用于 role="group" 包装元素的内联样式。',
+    },
+    {
+      name: 'ref',
+      type: 'React.Ref<HTMLDivElement>',
+      description: '转发到 role="group" 包装元素的 ref。',
+    },
+  ],
+  theming: {
+    targets: [{className: 'astryx-dropdown-menu-section-heading'}],
+  },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
   description:
-    'titled role="group" of rows for compound menus; compound peer of the data API\'s {type: "section"}',
+    'named role="group" of compound-menu rows; compound peer of the data API\'s {type: "section"}',
+  usage: {
+    description:
+      'Use to give related compound-menu rows one visible and programmatic name.',
+    bestPractices: [
+      {
+        guidance: true,
+        description: "Short title that explains the rows' relationship.",
+      },
+      {
+        guidance: true,
+        description:
+          'Non-interactive title keeps every action in menu arrow navigation.',
+      },
+      {
+        guidance: false,
+        description:
+          'Controls in title. Put them in DropdownMenu header or footer instead.',
+      },
+      {guidance: false, description: 'Group unrelated rows.'},
+    ],
+  },
   propDescriptions: {
-    title: 'heading above the rows; names the group',
-    children: 'the rows of the group',
-    xstyle: 'StyleX styles applied to the group wrapper',
+    title: 'non-interactive heading above the rows; names the group',
+    children: 'the grouped menu rows',
+    xstyle: 'StyleX styles on the role="group" wrapper',
+    className: 'CSS class on the role="group" wrapper',
+    style: 'inline styles on the role="group" wrapper',
+    ref: 'ref forwarded to the role="group" wrapper',
   },
 };

package/src/DropdownMenu/DropdownMenuGroup.tsx

@@ -53,7 +53,8 @@ export interface DropdownMenuGroupProps extends Pick<
 > {
   /**
    * Heading shown above the group's rows and used as the group's accessible
-   * name (`aria-labelledby`). Omit it for an unnamed group.
+   * name (`aria-labelledby`). Omit it for an unnamed group. Keep this content
+   * non-interactive; controls belong in DropdownMenu's `header` or `footer`.
    */
   title?: ReactNode;
   /** The rows of the group: menu items, selectable items, sub-menus. */
@@ -65,9 +66,10 @@ export interface DropdownMenuGroupProps extends Pick<
 /**
  * A titled group of menu rows.
  *
- * Renders `role="group"` named by its heading. The heading is plain text, not
- * a `menuitem`, so it is never a stop in the menu's arrow-key order and
- * typeahead never lands on it. The compound peer of
+ * Renders `role="group"` named by its heading. The heading is not a
+ * `menuitem`, so arrow-key navigation and typeahead skip it. Keep heading
+ * content non-interactive; place controls in DropdownMenu's `header` or
+ * `footer`. The compound peer of
  * `{type: 'section', title, items}` in the `items` data API.
  *
  * @example

package/src/DropdownMenu/DropdownMenuLazySheet.test.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuLazySheet.test.tsx
+ * @input Uses DropdownMenu, Testing Library, and a held module load
+ * @output Tests DropdownMenu while its on-demand touch sheet is still loading
+ * @position Test file for DropdownMenu
+ *
+ * This file never warms the sheet, and it checks that a popover menu never
+ * requests it: each test holds the sheet modules until it
+ * releases them, so it exercises the path a real page takes while the sheet's
+ * code is still downloading.
+ */
+
+import {describe, it, expect, vi, beforeAll, beforeEach} from 'vitest';
+import {render, screen, waitFor, act} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type {DropdownMenu as DropdownMenuComponent} from './DropdownMenu';
+
+const sheetLoad = vi.hoisted(() => {
+  let release: () => void = () => {};
+  const gate = new Promise<void>(resolve => {
+    release = resolve;
+  });
+  return {gate, release: () => release(), requested: [] as string[]};
+});
+
+vi.mock('./MenuBottomSheet', async importOriginal => {
+  sheetLoad.requested.push('MenuBottomSheet');
+  await sheetLoad.gate;
+  return importOriginal();
+});
+
+vi.mock('./MenuBottomSheetActionList', async importOriginal => {
+  sheetLoad.requested.push('MenuBottomSheetActionList');
+  await sheetLoad.gate;
+  return importOriginal();
+});
+
+let DropdownMenu: typeof DropdownMenuComponent;
+
+// If any module the dropdown loads imported the sheet eagerly, this import
+// would wait on the held sheet and the hook would time out.
+beforeAll(async () => {
+  ({DropdownMenu} = await import('./DropdownMenu'));
+}, 10000);
+
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+});
+
+describe('DropdownMenu touch sheet loaded on demand', () => {
+  // Runs first: nothing in this file has rendered a sheet yet.
+  it('never loads the sheet for a popover menu', async () => {
+    const user = userEvent.setup();
+    HTMLElement.prototype.showPopover = vi.fn();
+    HTMLElement.prototype.hidePopover = vi.fn();
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        items={[{label: 'Edit project'}, {label: 'Delete'}]}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 50));
+    });
+
+    // Importing DropdownMenu and opening a popover menu requested neither
+    // sheet module, so no other module the dropdown loads imports it eagerly.
+    expect(sheetLoad.requested).toEqual([]);
+  });
+
+  it('focuses the first action when a keyboard open beats the sheet load', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        presentation="bottom-sheet"
+        items={[{label: 'Edit project'}, {label: 'Delete'}]}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: /Actions/});
+    trigger.focus();
+    await user.keyboard('{Enter}');
+    // The open has committed, but the sheet's code has not arrived yet.
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 50));
+    });
+    expect(screen.queryByRole('button', {name: 'Edit project'})).toBeNull();
+
+    await act(async () => {
+      sheetLoad.release();
+    });
+
+    await waitFor(
+      () =>
+        expect(
+          screen.getByRole('button', {name: 'Edit project'}),
+        ).toHaveFocus(),
+      {timeout: 15000},
+    );
+  }, 20000);
+});

package/src/DropdownMenu/DropdownMenuSubMenu.test.tsx

@@ -1494,3 +1494,188 @@ describe('DropdownMenuSubMenu drill-in on a phone', () => {
       screen.getAllByRole('menu', {name, ...h}).find(isShown);
   });
 });
+
+describe('DropdownMenuSubMenu light dismiss of the root menu (#6893)', () => {
+  // The browser closes the root `popover=\"auto\"` element itself on an outside
+  // tap; that path never reaches the submenu, whose flyout is
+  // `popover=\"manual\"`. Simulate it by hiding the root popover element
+  // directly, exactly what light dismiss does to it.
+  function lightDismissRootMenu() {
+    const menu = screen.getByRole('menu', {name: /Actions/, hidden: true});
+    const rootPopover = menu.closest<HTMLElement>('[popover]');
+    expect(rootPopover).not.toBeNull();
+    act(() => {
+      rootPopover!.hidePopover();
+    });
+  }
+
+  function getFlyoutPopover(name: RegExp) {
+    const flyout = screen.getByRole('menu', {name, hidden: true});
+    return flyout.closest<HTMLElement>('[popover]');
+  }
+
+  it('closes an open flyout when the root menu is light-dismissed', async () => {
+    const user = userEvent.setup();
+    render(<MoveMenu />);
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const trigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+    await user.click(trigger);
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    });
+    const flyoutPopover = getFlyoutPopover(/Move to/);
+    expect(flyoutPopover).toHaveAttribute('popover-open', '');
+
+    lightDismissRootMenu();
+
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+    expect(flyoutPopover).not.toHaveAttribute('popover-open');
+  });
+
+  it('leaves the submenu collapsed when the menu reopens after a light dismiss', async () => {
+    const user = userEvent.setup();
+    render(<MoveMenu />);
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const trigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+    await user.click(trigger);
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    lightDismissRootMenu();
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+    expect(getFlyoutPopover(/Move to/)).not.toHaveAttribute('popover-open');
+  });
+
+  it('closes an open flyout when the root menu closes via controlled isMenuOpen', async () => {
+    const user = userEvent.setup();
+    function ControlledMenu() {
+      const [open, setOpen] = useState(true);
+      return (
+        <>
+          <DropdownMenu
+            button={{label: 'Actions'}}
+            isMenuOpen={open}
+            onOpenChange={setOpen}>
+            <DropdownMenuSubMenu label="Move to">
+              <DropdownMenuItem label="Folder A" onClick={() => {}} />
+            </DropdownMenuSubMenu>
+          </DropdownMenu>
+          <button type="button" onClick={() => setOpen(false)}>
+            close it
+          </button>
+        </>
+      );
+    }
+    render(<ControlledMenu />);
+    const trigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+    await user.click(trigger);
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    });
+    const flyoutPopover = getFlyoutPopover(/Move to/);
+
+    await user.click(screen.getByRole('button', {name: /close it/}));
+
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+    expect(flyoutPopover).not.toHaveAttribute('popover-open');
+  });
+
+  it('closes flyouts nested two levels deep on light dismiss', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}}>
+        <DropdownMenuSubMenu label="Move to">
+          <DropdownMenuSubMenu label="Deeper">
+            <DropdownMenuItem label="Leaf" onClick={() => {}} />
+          </DropdownMenuSubMenu>
+        </DropdownMenuSubMenu>
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const first = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+    await user.click(first);
+    await waitFor(() => {
+      expect(first).toHaveAttribute('aria-expanded', 'true');
+    });
+    const deeper = screen.getByRole('menuitem', {
+      name: /Deeper/,
+      hidden: true,
+    });
+    await user.click(deeper);
+    await waitFor(() => {
+      expect(deeper).toHaveAttribute('aria-expanded', 'true');
+    });
+    const firstPopover = getFlyoutPopover(/Move to/);
+    const deeperPopover = getFlyoutPopover(/Deeper/);
+
+    lightDismissRootMenu();
+
+    await waitFor(() => {
+      expect(first).toHaveAttribute('aria-expanded', 'false');
+    });
+    await waitFor(() => {
+      expect(deeper).toHaveAttribute('aria-expanded', 'false');
+    });
+    expect(firstPopover).not.toHaveAttribute('popover-open');
+    expect(deeperPopover).not.toHaveAttribute('popover-open');
+  });
+
+  // Regression for the stale hover timer: a hover over the submenu trigger
+  // schedules an open after the show delay. A press on the same trigger
+  // cancels its own scheduled hover-open (that is the click guard), so the
+  // way a timer is still pending at close time is a close that comes from
+  // elsewhere — here the root menu's light dismiss, the #6893 case. The
+  // close must cancel the scheduled hover-open: once the delay elapses the
+  // flyout stays closed instead of reopening behind the dismissed menu.
+  // Time is driven manually so the dismiss lands inside the show delay;
+  // auto-advancing timers would let the hover-open fire before it.
+  it('cancels a hover-open scheduled before the menu was closed from elsewhere', async () => {
+    vi.useFakeTimers();
+    try {
+      render(<MoveMenu />);
+      fireEvent.click(screen.getByRole('button', {name: /Actions/}));
+      const trigger = screen.getByRole('menuitem', {
+        name: /Move to/,
+        hidden: true,
+      });
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+      // Schedules the hover-open (default show delay 150ms).
+      fireEvent.mouseEnter(trigger);
+
+      // Close from elsewhere while the hover-open is still pending.
+      lightDismissRootMenu();
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+      // The scheduled delay passes; the flyout must stay closed.
+      await act(async () => {
+        vi.advanceTimersByTime(300);
+      });
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      expect(getFlyoutPopover(/Move to/)).not.toHaveAttribute('popover-open');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -97,7 +97,9 @@ import {
 } from './menuItemRoles';
 import {
   DropdownMenuContext,
+  DropdownMenuRootOpenContext,
   useDropdownMenuContext,
+  useDropdownMenuRootOpen,
   type DropdownMenuContextValue,
 } from './DropdownMenuContext';
 import {focusMenuItemOnHover} from './menuItemHover';
@@ -166,8 +168,8 @@ const flyoutStyles = stylex.create({
     flexDirection: 'column',
     gap: spacingVars['--spacing-0-5'],
     maxInlineSize: stylex.firstThatWorks(
-      layerViewportInset.maxInlineSize,
-      layerViewportInset.maxInlineSizeFallback,
+      `calc(${layerViewportInset.maxInlineSize})`,
+      `calc(${layerViewportInset.maxInlineSizeFallback})`,
     ),
     maxHeight: stylex.firstThatWorks(
       MENU_MAX_BLOCK_SIZE,
@@ -451,13 +453,17 @@ export function DropdownMenuSubMenu(
   // Hover intent and the shared hover→click guard only: this level owns its own
   // click handling, roving focus and typeahead. popover="manual", so the
   // invoker wiring other consumers need does not apply. A drill-in row has no
-  // hover: a finger drives it, and a press opens it.
+  // hover: a finger drives it, and a press opens it. Hover is also gated on
+  // the root menu being open, so a hover-open scheduled before the menu
+  // closed from elsewhere is cancelled instead of firing into the hidden
+  // menu (#6893).
+  const isRootMenuOpen = useDropdownMenuRootOpen();
   const {triggerProps, contentProps, confirmHoverOpen} =
     useMenuHover<HTMLDivElement>({
       show: showLayer,
       hide: hideLayer,
       isOpen: isFlyoutOpen,
-      isEnabled: canOpen && !isDrillIn,
+      isEnabled: canOpen && !isDrillIn && isRootMenuOpen,
       // The safe triangle toward the flyout's near edge is built from the
       // flyout this component renders, not the hook's own list ref.
       flyoutRef: menuRef,
@@ -770,7 +776,7 @@ export function DropdownMenuSubMenu(
       : flyoutStyles.popoverCustomWidth(resolvedMenuWidth.value)
     : flyoutStyles.popover;
 
-  const nestedContent = (
+  const nestedRows = (
     <DropdownMenuContext value={nestedMenuContext}>
       {isDrillIn && (
         <DropdownMenuItem
@@ -790,6 +796,14 @@ export function DropdownMenuSubMenu(
       {children}
     </DropdownMenuContext>
   );
+  // Nested rows live in this level's flyout, a layer of their own where the
+  // layer-scoped signal resets; re-provide it so their pending hover intent
+  // dies with the root menu too.
+  const nestedContent = (
+    <DropdownMenuRootOpenContext value={isRootMenuOpen}>
+      {nestedRows}
+    </DropdownMenuRootOpenContext>
+  );
 
   return (
     <>