@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e4f8e4e

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -32,7 +32,7 @@ export const docs = {
     {
       name: 'items',
       type: 'ContextMenuOption[]',
-      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?}` (variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
+      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?, items?}` (nested `items` open a flyout in popover presentation and drill into a new view in bottom-sheet presentation; variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
       required: true,
     },
     {
@@ -63,6 +63,12 @@ export const docs = {
       type: '(isOpen: boolean) => void',
       description: 'Callback fired when the menu opens or closes.',
     },
+    {
+      name: 'presentation',
+      type: "'popover' | 'bottom-sheet' | 'adaptive'",
+      description: 'Presentation policy. `popover` opens at the pointer position, `bottom-sheet` always uses an action sheet, and `adaptive` uses the BottomSheet at 768px and below when the primary pointer is coarse.',
+      default: "'popover'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -78,7 +84,9 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Keep menu items concise and action-oriented; users expect quick access to contextual actions.' },
       { guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },
+      { guidance: true, description: 'Use `presentation="adaptive"` when right-click should remain cursor-positioned on desktop while long-press opens a reachable BottomSheet on compact touch devices.' },
       { guidance: true, description: 'Ensure all context menu actions are also accessible via other UI elements for keyboard-only users.' },
+      { guidance: true, description: 'Keep a visible MoreMenu or equivalent trigger for important mobile actions; long-press must not be the only route.' },
       { guidance: false, description: 'Use a ContextMenu as the only way to access important actions; not all users know to right-click.' },
       { guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },
     ],
@@ -107,7 +115,9 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: '保持菜单项简洁和面向操作。' },
       { guidance: true, description: '有很多项时使用分组和分隔线。' },
+      { guidance: true, description: '在桌面端需要光标定位、紧凑触控设备上需要 BottomSheet 时，使用 `presentation="adaptive"`。' },
       { guidance: true, description: '确保所有上下文菜单操作也可通过其他 UI 元素访问。' },
+      { guidance: true, description: '重要的移动端操作还应提供可见的 MoreMenu 或同等入口，不要只依赖长按。' },
       { guidance: false, description: '将上下文菜单作为访问重要操作的唯一方式。' },
       { guidance: false, description: '在单个菜单中放置超过 10-12 个项而不分组。' },
     ],
@@ -122,7 +132,9 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Keep items concise and action-oriented.' },
       { guidance: true, description: 'Group related actions with sections and dividers.' },
+      { guidance: true, description: 'Use adaptive presentation for cursor popover on desktop and BottomSheet on compact touch.' },
       { guidance: true, description: 'Ensure actions are also accessible via other UI elements.' },
+      { guidance: true, description: 'Keep a visible mobile entry point for important actions.' },
       { guidance: false, description: 'Use as the only way to access important actions.' },
       { guidance: false, description: 'Place more than 10–12 items without grouping.' },
     ],

package/src/ContextMenu/ContextMenu.test.tsx

@@ -9,8 +9,9 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {readFileSync} from 'node:fs';
 import {ContextMenu} from './ContextMenu';
 import {
   ContextMenuItem,
@@ -23,6 +24,30 @@ import {DropdownMenuItem} from '../DropdownMenu/DropdownMenuItem';
 import {Divider} from '../Divider';
 
 beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = 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(),
+    })),
+  );
   HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
     this.setAttribute('popover-open', '');
     const event = new Event('toggle', {bubbles: false});
@@ -123,6 +148,100 @@ describe('ContextMenu', () => {
     expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
   });
 
+  it('opens the real menu content in a BottomSheet when requested', async () => {
+    render(
+      <ContextMenu
+        presentation="bottom-sheet"
+        label="Row actions"
+        items={[{label: 'Edit'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    await waitFor(() =>
+      expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalledOnce(),
+    );
+    const dialog = screen.getByRole('dialog', {name: 'Row actions'});
+    const actionList = dialog.querySelector('[data-autofocus]');
+    expect(actionList).not.toBeNull();
+    await waitFor(() => expect(actionList).toHaveFocus());
+    expect(screen.getByRole('button', {name: 'Edit'})).not.toHaveFocus();
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+  });
+
+  it('drills into nested data items inside the BottomSheet', async () => {
+    const user = userEvent.setup();
+    const onMove = vi.fn();
+
+    render(
+      <ContextMenu
+        presentation="bottom-sheet"
+        label="Row actions"
+        items={[
+          {
+            label: 'Move to project',
+            items: [{label: 'Apollo launch', onClick: onMove}],
+          },
+        ]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    await user.click(screen.getByRole('button', {name: 'Move to project'}));
+
+    const submenuHeading = screen.getByRole('heading', {
+      name: 'Move to project',
+    });
+    expect(submenuHeading).toBeInTheDocument();
+    await waitFor(() => expect(submenuHeading).toHaveFocus());
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole('button', {name: 'Apollo launch'}));
+    expect(onMove).toHaveBeenCalledOnce();
+    await waitFor(() =>
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument(),
+    );
+  });
+
+  it('keeps only the top content padding in a menu BottomSheet', () => {
+    const source = readFileSync(
+      'packages/core/src/DropdownMenu/MenuBottomSheet.tsx',
+      'utf8',
+    );
+
+    expect(source).toContain('paddingBlockStart={4}');
+    expect(source).toContain('paddingBlockEnd={0}');
+  });
+
+  it('uses the BottomSheet for adaptive presentation on compact touch', async () => {
+    vi.stubGlobal(
+      'matchMedia',
+      vi.fn().mockImplementation((query: string) => ({
+        matches: query === '(max-width: 768px) and (pointer: coarse)',
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    );
+    render(
+      <ContextMenu presentation="adaptive" items={[{label: 'Edit'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    await waitFor(() =>
+      expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalledOnce(),
+    );
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+  });
+
   it('closes on Escape even when opened without auto-focus', () => {
     render(
       <ContextMenu items={[{label: 'Item 1'}]}>
@@ -273,6 +392,17 @@ describe('ContextMenu', () => {
     }
   });
 
+  it('suppresses native text selection on the long-press trigger', () => {
+    const source = readFileSync(
+      'packages/core/src/ContextMenu/ContextMenu.tsx',
+      'utf8',
+    );
+
+    expect(source).toMatch(
+      /trigger:[\s\S]*?WebkitTouchCallout: 'none',[\s\S]*?WebkitUserSelect: 'none',[\s\S]*?userSelect: 'none'/,
+    );
+  });
+
   it('cancels the long-press when the finger moves past the threshold', () => {
     vi.useFakeTimers();
     try {

package/src/ContextMenu/ContextMenu.tsx

@@ -3,8 +3,9 @@
 
 /**
  * @file ContextMenu.tsx
- * @input Uses React, StyleX, useLayer (context mode), useListFocus
- * @output Exports ContextMenu component
+ * @input Uses React, StyleX, useLayer, BottomSheet, useListFocus, and the
+ *   shared menu-presentation resolver
+ * @output Exports ContextMenu with cursor-popover and touch-sheet presentations
  * @position Core implementation; consumed by index.ts
  *
  * Right-click context menu positioned at the cursor. The cursor point is
@@ -34,13 +35,19 @@ import React, {
   useCallback,
   useEffect,
   useId,
+  lazy,
   useMemo,
   useRef,
   useState,
+  Suspense,
 } from 'react';
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {Button} from '../Button';
+import {Heading} from '../Heading';
+import {Icon} from '../Icon';
 import {useLayer} from '../Layer/useLayer';
+import {MenuBottomSheetActionList} from '../DropdownMenu/MenuBottomSheetActionList';
 import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
 import {
   DropdownMenuContext,
@@ -63,7 +70,7 @@ import {
   easeVars,
   shadowVars,
 } from '../theme/tokens.stylex';
-import {mergeProps, isImeKeyEvent} from '../utils';
+import {mergeProps, isImeKeyEvent, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {StyleXStyles} from '../theme/types';
 import {themeProps} from '../utils/themeProps';
@@ -76,6 +83,16 @@ import type {
 } from '../DropdownMenu/DropdownMenu';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {
+  useAdaptivePresentation,
+  type AdaptivePresentation,
+} from '../hooks/useAdaptivePresentation';
+
+const LazyMenuBottomSheet = lazy(async () =>
+  import('../DropdownMenu/MenuBottomSheet').then(module => ({
+    default: module.MenuBottomSheet,
+  })),
+);
 const styles = stylex.create({
   // Trigger wrapper: suppress the iOS long-press callout/selection so the
   // long-press opens our context menu instead of the native text/callout UI.
@@ -85,6 +102,8 @@ const styles = stylex.create({
   trigger: {
     position: 'relative',
     WebkitTouchCallout: 'none',
+    WebkitUserSelect: 'none',
+    userSelect: 'none',
   },
   // Zero-size anchor placed at the cursor point within the trigger. The menu
   // is anchored to this element, so it sits under the cursor yet is positioned
@@ -121,6 +140,33 @@ const styles = stylex.create({
   popoverCustomWidth: (width: string | number) => ({
     minWidth: typeof width === 'number' ? `${width}px` : width,
   }),
+  sheetMenu: {
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacingVars['--spacing-0-5'],
+    width: '100%',
+    '--_dropdown-menu-radius': radiusVars['--radius-container'],
+    '--_dropdown-menu-padding': spacingVars['--spacing-1'],
+    padding: spacingVars['--spacing-1'],
+    borderRadius: 'var(--_dropdown-menu-radius)',
+    backgroundColor: colorVars['--color-background-surface'],
+    outline: 'none',
+    userSelect: 'none',
+  },
+  sheetHeader: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+    marginBottom: spacingVars['--spacing-2'],
+  },
+  sheetRootHeading: {
+    marginInlineStart: spacingVars['--spacing-3'],
+  },
+  sheetViewHeading: {
+    outline: 'none',
+  },
 });
 
 // =============================================================================
@@ -164,6 +210,15 @@ interface ContextMenuBaseProps extends BaseProps {
   isDisabled?: boolean;
   /** Called when the menu opens or closes. */
   onOpenChange?: (isOpen: boolean) => void;
+  /**
+   * Presentation policy for the menu.
+   * - `popover`: open beside the pointer position.
+   * - `bottom-sheet`: open as an action sheet.
+   * - `adaptive`: use a BottomSheet on compact coarse-pointer viewports and
+   *   the cursor-positioned popover elsewhere.
+   * @default 'popover'
+   */
+  presentation?: AdaptivePresentation;
   'data-testid'?: string;
 }
 
@@ -215,6 +270,7 @@ export function ContextMenu({
   label: labelFromProps,
   isDisabled = false,
   onOpenChange,
+  presentation = 'popover',
   ref,
   className,
   style,
@@ -225,6 +281,9 @@ export function ContextMenu({
 }: ContextMenuProps) {
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.contextMenu.label');
+  const backLabel = t('@astryx.dropdownMenu.back');
+  const resolvedPresentation = useAdaptivePresentation(presentation);
+  const usesBottomSheet = resolvedPresentation === 'bottom-sheet';
   // Separate content props (union discriminant) from DOM pass-through attrs.
   // The union means exactly one of items/menuContent exists in rest; destructure
   // both so triggerProps contains only DOM-safe attributes.
@@ -250,8 +309,25 @@ export function ContextMenu({
   // Element focused before the menu opened, restored when it closes so focus
   // does not fall to <body> after Escape or outside-click dismissal.
   const triggerFocusRef = useRef<HTMLElement | null>(null);
+  const sheetHeadingRef = useRef<HTMLHeadingElement>(null);
 
   const [isOpen, setIsOpen] = useState(false);
+  const [submenuPath, setSubmenuPath] = useState<ContextMenuItemData[]>([]);
+  const currentSubmenu = submenuPath.at(-1);
+  const currentItems = currentSubmenu?.items ?? items;
+  const currentTitle = currentSubmenu?.label ?? label;
+  const sheetLabel = typeof currentTitle === 'string' ? currentTitle : label;
+
+  const updateOpenState = useCallback(
+    (nextIsOpen: boolean) => {
+      if (!nextIsOpen) {
+        setSubmenuPath([]);
+      }
+      setIsOpen(nextIsOpen);
+      onOpenChange?.(nextIsOpen);
+    },
+    [onOpenChange],
+  );
 
   const layer = useLayer({
     mode: 'context',
@@ -273,8 +349,35 @@ export function ContextMenu({
   });
 
   const closeMenu = useCallback(() => {
-    layer.hide();
-  }, [layer]);
+    if (usesBottomSheet) {
+      updateOpenState(false);
+    } else {
+      layer.hide();
+    }
+  }, [layer, updateOpenState, usesBottomSheet]);
+
+  const handleBottomSheetSelect = useCallback(
+    (item: ContextMenuItemData) => {
+      if (item.isDisabled) {
+        return;
+      }
+      item.onClick?.();
+      if (item.hasCloseOnSelect !== false) {
+        closeMenu();
+      }
+    },
+    [closeMenu],
+  );
+
+  useEffect(() => {
+    if (!isOpen || submenuPath.length === 0) {
+      return;
+    }
+    const frame = requestAnimationFrame(() => {
+      sheetHeadingRef.current?.focus({preventScroll: true});
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [isOpen, submenuPath.length]);
 
   const {
     listRef,
@@ -308,7 +411,7 @@ export function ContextMenu({
   // opening right-click as a dismiss event. Handling it ourselves via
   // mousedown avoids that race.
   useEffect(() => {
-    if (!isOpen) {
+    if (!isOpen || usesBottomSheet) {
       return;
     }
     const handleClickOutside = (e: MouseEvent) => {
@@ -321,14 +424,14 @@ export function ContextMenu({
     return () => {
       document.removeEventListener('mousedown', handleClickOutside);
     };
-  }, [isOpen, closeMenu, listRef]);
+  }, [isOpen, closeMenu, listRef, usesBottomSheet]);
 
   // Dismiss on Escape from anywhere while open. The menu div's own onKeyDown
   // only fires when focus is inside the menu; a document-level listener is
   // kept as a reliable fallback Escape path (e.g. if focus has moved out of
   // the menu). Guards against IME composition-cancel.
   useEffect(() => {
-    if (!isOpen) {
+    if (!isOpen || usesBottomSheet) {
       return;
     }
     const handleEscape = (e: KeyboardEvent) => {
@@ -347,7 +450,7 @@ export function ContextMenu({
     return () => {
       document.removeEventListener('keydown', handleEscape);
     };
-  }, [isOpen, closeMenu]);
+  }, [isOpen, closeMenu, usesBottomSheet]);
 
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -404,10 +507,14 @@ export function ContextMenu({
         document.activeElement instanceof HTMLElement
           ? document.activeElement
           : focusEl;
-      layer.show();
-      requestAnimationFrame(() => focusFirst());
+      if (usesBottomSheet) {
+        updateOpenState(true);
+      } else {
+        layer.show();
+        requestAnimationFrame(() => focusFirst());
+      }
     },
-    [layer, focusFirst],
+    [layer, focusFirst, updateOpenState, usesBottomSheet],
   );
 
   const handleContextMenu = useCallback(
@@ -465,6 +572,74 @@ export function ContextMenu({
   const resolvedMenuContent =
     itemsProp !== undefined ? renderDropdownItems(items) : menuContent;
 
+  const renderedMenu = (
+    <div
+      ref={listRef}
+      id={menuId}
+      role="menu"
+      data-autofocus={usesBottomSheet ? '' : undefined}
+      tabIndex={usesBottomSheet ? 0 : -1}
+      aria-label={label}
+      onKeyDown={listKeyDown}
+      onContextMenu={e => e.preventDefault()}
+      {...mergeProps(
+        themeProps('context-menu'),
+        stylex.props(usesBottomSheet ? styles.sheetMenu : styles.menu, xstyle),
+        className,
+        style,
+      )}>
+      <DropdownMenuContext value={contextValue}>
+        {resolvedMenuContent}
+      </DropdownMenuContext>
+    </div>
+  );
+
+  const renderedBottomSheetContent =
+    itemsProp !== undefined ? (
+      <div
+        ref={listRef}
+        data-autofocus=""
+        tabIndex={0}
+        {...mergeProps(
+          themeProps('context-menu'),
+          stylex.props(styles.sheetMenu, xstyle),
+          className,
+          style,
+        )}>
+        <div {...stylex.props(styles.sheetHeader)}>
+          {submenuPath.length > 0 && (
+            <Button
+              label={backLabel}
+              variant="ghost"
+              size="sm"
+              icon={
+                <Icon icon="chevronLeft" size="sm" xstyle={rtlStyles.mirror} />
+              }
+              isIconOnly
+              onClick={() => setSubmenuPath(path => path.slice(0, -1))}
+            />
+          )}
+          <Heading
+            ref={sheetHeadingRef}
+            level={3}
+            tabIndex={-1}
+            xstyle={[
+              styles.sheetViewHeading,
+              submenuPath.length === 0 && styles.sheetRootHeading,
+            ]}>
+            {currentTitle}
+          </Heading>
+        </div>
+        <MenuBottomSheetActionList
+          items={currentItems}
+          onSelect={handleBottomSheetSelect}
+          onOpenSubmenu={item => setSubmenuPath(path => [...path, item])}
+        />
+      </div>
+    ) : (
+      renderedMenu
+    );
+
   return (
     <>
       <div
@@ -494,29 +669,21 @@ export function ContextMenu({
         />
       </div>
 
-      {layer.render(
-        <div
-          ref={listRef}
-          id={menuId}
-          role="menu"
-          aria-label={label}
-          onKeyDown={listKeyDown}
-          onContextMenu={e => e.preventDefault()}
-          {...mergeProps(
-            themeProps('context-menu'),
-            stylex.props(styles.menu, xstyle),
-            className,
-            style,
-          )}>
-          <DropdownMenuContext value={contextValue}>
-            {resolvedMenuContent}
-          </DropdownMenuContext>
-        </div>,
-        {
+      {usesBottomSheet ? (
+        <Suspense fallback={null}>
+          <LazyMenuBottomSheet
+            isOpen={isOpen}
+            onOpenChange={updateOpenState}
+            label={sheetLabel}>
+            {renderedBottomSheetContent}
+          </LazyMenuBottomSheet>
+        </Suspense>
+      ) : (
+        layer.render(renderedMenu, {
           placement: 'below',
           alignment: 'start',
           xstyle: [popoverXstyle, layerAnimations.below],
-        },
+        })
       )}
     </>
   );

package/src/ContextMenu/index.ts

@@ -15,6 +15,7 @@ export {
   type ContextMenuSection,
   type ContextMenuOption,
 } from './ContextMenu';
+export type {AdaptivePresentation as MenuPresentation} from '../hooks/useAdaptivePresentation';
 
 export {
   DropdownMenuItem as ContextMenuItem,