@astryxdesign/core 0.7.2-canary.fdd384f → 0.7.2

package/src/DropdownMenu/DropdownMenu.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file DropdownMenu.tsx
- * @input Uses React, StyleX, usePopover, MenuBottomSheet, Button, List,
+ * @input Uses React, StyleX, usePopover, MenuBottomSheet (lazy), Button, List,
  *   useListFocus, and the shared viewport-safe menu-width resolver
  * @output Exports DropdownMenu with caller-selected popover or bottom-sheet
  *   presentation
@@ -72,7 +72,7 @@ import {useFocusReturnVisibility} from '../hooks/useFocusReturnVisibility';
 import {focusForLastInput} from '../utils/focusReturn';
 import {useMenuOverflow} from './useMenuOverflow';
 import {MenuRegionsContext} from './menuRegionsContext';
-import {getFocusableElements} from '../hooks/useFocusTrap';
+import {moveRegionsTab} from './menuRegionStops';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {useMenuDrillIn} from './useMenuDrillIn';
 import {resolveMenuWidth} from './menuWidth';
@@ -81,8 +81,11 @@ import {
   useAdaptivePresentation,
   type AdaptivePresentation,
 } from '../hooks/useAdaptivePresentation';
-import {MenuBottomSheet} from './MenuBottomSheet';
-import {MenuBottomSheetActionList} from './MenuBottomSheetActionList';
+// Loaded on demand: only the bottom-sheet presentation renders the sheet.
+import {
+  MenuBottomSheet,
+  MenuBottomSheetActionList,
+} from './lazyMenuBottomSheet';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {
@@ -109,102 +112,6 @@ const MENU_MAX_BLOCK_SIZE = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBloc
 const MENU_MAX_BLOCK_SIZE_FALLBACK = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBlockSizeFallback})`;
 const MENU_TRIGGER_OPEN_BACKGROUND = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`;
 
-/**
- * The elements Tab reaches inside a header or footer region, in order. Hidden
- * controls (`hidden`, `display: none`, `visibility: hidden`, inert or
- * aria-hidden subtrees) are not reachable, judged by the popover focus trap's
- * own test so the two never disagree about where Tab can go.
- */
-/**
- * Collapse each named radio group to the one Tab stop a browser gives it: the
- * focused radio, else the checked one, else the first radio moving forward or
- * the last moving backward. The stop takes the group's first position.
- */
-function collapseRadioGroups(
-  elements: HTMLElement[],
-  active: Element | null,
-  isBackward: boolean,
-): HTMLElement[] {
-  const groups = new Map<string, HTMLInputElement[]>();
-  const groupKey = (el: HTMLElement): string | null =>
-    el instanceof HTMLInputElement &&
-    el.getAttribute('type') === 'radio' &&
-    el.name !== ''
-      ? `${el.form?.id ?? ''}\u0000${el.name}`
-      : null;
-  for (const el of elements) {
-    const key = groupKey(el);
-    if (key != null) {
-      const members = groups.get(key) ?? [];
-      members.push(el as HTMLInputElement);
-      groups.set(key, members);
-    }
-  }
-  const placed = new Set<string>();
-  const result: HTMLElement[] = [];
-  for (const el of elements) {
-    const key = groupKey(el);
-    if (key == null) {
-      result.push(el);
-      continue;
-    }
-    if (placed.has(key)) {
-      continue;
-    }
-    placed.add(key);
-    const members = groups.get(key) ?? [];
-    const stop =
-      members.find(radio => radio === active) ??
-      members.find(radio => radio.checked) ??
-      (isBackward ? members[members.length - 1] : members[0]);
-    result.push(stop);
-  }
-  return result;
-}
-
-function tabbablesIn(region: HTMLElement | null): HTMLElement[] {
-  if (region == null) {
-    return [];
-  }
-  return getFocusableElements(region).filter(
-    element => element.tabIndex >= 0 && !isInsideHiddenWrapper(element, region),
-  );
-}
-
-/**
- * Whether a `display: none` ancestor between the element and its region hides
- * it — a control in a wrapper hidden at some widths, say. The trap's test reads
- * only the element's own display.
- */
-function isInsideHiddenWrapper(
-  element: HTMLElement,
-  region: HTMLElement,
-): boolean {
-  if (typeof window === 'undefined' || !window.getComputedStyle) {
-    return false;
-  }
-  for (
-    let node = element.parentElement;
-    node != null && node !== region.parentElement;
-    node = node.parentElement
-  ) {
-    if (window.getComputedStyle(node).display === 'none') {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Move focus to a Tab stop in the dialog. Reports whether focus actually
- * arrived, so a caller can fall back to the menu instead of stranding focus on
- * the page.
- */
-function focusRegionControl(element: HTMLElement): boolean {
-  element.focus();
-  return element.ownerDocument.activeElement === element;
-}
-
 const styles = stylex.create({
   triggerOpen: {
     backgroundImage: MENU_TRIGGER_OPEN_BACKGROUND,
@@ -759,12 +666,37 @@ function DropdownMenuBottomSheet({
     if (!isOpen || openModalityRef.current !== 'keyboard') {
       return;
     }
-    const frame = requestAnimationFrame(() => {
-      actionListRef.current
-        ?.querySelector<HTMLElement>('button:not(:disabled), a[href]')
-        ?.focus({preventScroll: true});
+    const findFirstAction = () =>
+      actionListRef.current?.querySelector<HTMLElement>(
+        'button:not(:disabled), a[href]',
+      ) ?? null;
+    let observer: MutationObserver | null = null;
+    let frame = requestAnimationFrame(() => {
+      const action = findFirstAction();
+      if (action != null) {
+        action.focus({preventScroll: true});
+        return;
+      }
+      // The sheet loads on demand, so a keyboard open can arrive before its
+      // rows exist. Wait for them, then focus a frame later so the sheet's
+      // own open-focus has already run.
+      observer = new MutationObserver(() => {
+        const loaded = findFirstAction();
+        if (loaded == null) {
+          return;
+        }
+        observer?.disconnect();
+        observer = null;
+        frame = requestAnimationFrame(() => {
+          loaded.focus({preventScroll: true});
+        });
+      });
+      observer.observe(document.body, {childList: true, subtree: true});
     });
-    return () => cancelAnimationFrame(frame);
+    return () => {
+      cancelAnimationFrame(frame);
+      observer?.disconnect();
+    };
   }, [currentItems, isOpen]);
 
   useEffect(() => {
@@ -1243,44 +1175,13 @@ function DropdownMenuPopover({
   // second time.
   const moveDialogTab = useCallback(
     (e: React.KeyboardEvent, isFromFlyout = false) => {
-      const menu = listRef.current;
-      if (menu == null) {
-        return;
-      }
-      e.preventDefault();
-      e.stopPropagation();
-      // A named radio group is one stop, as the browser's own Tab order has it.
-      const cycle = collapseRadioGroups(
-        [
-          ...tabbablesIn(headerRef.current),
-          menu,
-          ...tabbablesIn(footerRef.current),
-        ],
-        document.activeElement,
-        e.shiftKey,
+      moveRegionsTab(
+        e,
+        listRef.current,
+        headerRef.current,
+        footerRef.current,
+        isFromFlyout,
       );
-      if (cycle.length === 1) {
-        // Nothing else to reach: focus stays in the menu. From a flyout that
-        // has just closed itself, that is the menu's own stop.
-        if (isFromFlyout) {
-          menu.focus();
-        }
-        return;
-      }
-      const active = document.activeElement;
-      const menuIndex = cycle.indexOf(menu);
-      // A row, or a row of an open flyout, counts as the menu's stop.
-      let index = menu.contains(active)
-        ? menuIndex
-        : cycle.findIndex(el => el === active || el.contains(active));
-      if (index < 0) {
-        index = menuIndex;
-      }
-      const step = e.shiftKey ? -1 : 1;
-      const next = cycle[(index + step + cycle.length) % cycle.length];
-      if (!focusRegionControl(next)) {
-        menu.focus();
-      }
     },
     [listRef],
   );

package/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
       name: 'icon',
       type: 'IconType',
       description:
-        'Icon to display before the label. See `npx @astryxdesign/cli docs icons` for valid semantic names.',
+        'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'value',

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -98,7 +98,7 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
   description?: ReactNode;
   /**
    * Icon to display before the label. Accepts a semantic icon name (see
-   * `npx @astryxdesign/cli docs icons`) or a rendered node.
+   * `astryx docs icons`) or a rendered node.
    */
   icon?: ReactNode | IconType;
   /**

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/DropdownMenuRadioItem.doc.mjs

@@ -43,7 +43,7 @@ export const docs = {
       name: 'icon',
       type: 'IconType',
       description:
-        'Icon to display before the label. See `npx @astryxdesign/cli docs icons` for valid semantic names.',
+        'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'isDisabled',

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -93,7 +93,7 @@ export interface DropdownMenuRadioItemProps extends Omit<
   description?: ReactNode;
   /**
    * Icon to display before the label. Accepts a semantic icon name (see
-   * `npx @astryxdesign/cli docs icons`) or a rendered node.
+   * `astryx docs icons`) or a rendered node.
    */
   icon?: ReactNode | IconType;
   /**