@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/src/Pagination/Pagination.test.tsx

@@ -9,10 +9,26 @@
  * SYNC: When Pagination.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, within, fireEvent, act} from '@testing-library/react';
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {
+  render,
+  screen,
+  within,
+  fireEvent,
+  act,
+  waitFor,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Pagination, generatePageRange} from './Pagination';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
 
 // =============================================================================
 // generatePageRange helper
@@ -239,6 +255,65 @@ describe('Pagination', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // pageSize guarding
+  // ---------------------------------------------------------------------------
+
+  describe('pageSize guarding', () => {
+    it('does not crash the dots variant when pageSize is 0', () => {
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          totalItems={5}
+          pageSize={0}
+          variant="dots"
+        />,
+      );
+      const group = screen.getByRole('group', {name: 'Page indicators'});
+      expect(within(group).getAllByRole('button')).toHaveLength(5);
+    });
+
+    it('treats NaN pageSize as the default', () => {
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          totalItems={50}
+          pageSize={NaN}
+          variant="compact"
+        />,
+      );
+      expect(screen.getByText('Page 1 of 5')).toBeInTheDocument();
+    });
+
+    it('clamps negative pageSize to 1', () => {
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          totalItems={5}
+          pageSize={-10}
+          variant="compact"
+        />,
+      );
+      expect(screen.getByText('Page 1 of 5')).toBeInTheDocument();
+    });
+
+    it('floors fractional pageSize', () => {
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          totalItems={50}
+          pageSize={2.5}
+          variant="compact"
+        />,
+      );
+      expect(screen.getByText('Page 1 of 25')).toBeInTheDocument();
+    });
+  });
+
   // ---------------------------------------------------------------------------
   // Variant: dots
   // ---------------------------------------------------------------------------
@@ -304,6 +379,38 @@ describe('Pagination', () => {
   // ---------------------------------------------------------------------------
 
   describe('page change callbacks', () => {
+    it('does not announce on initial mount', () => {
+      render(<Pagination page={1} onChange={() => {}} totalPages={10} />);
+      expect(politeRegion()).toBeNull();
+    });
+
+    it('announces the new page politely when navigating', async () => {
+      const user = userEvent.setup();
+      render(<Pagination page={2} onChange={() => {}} totalPages={10} />);
+      await user.click(screen.getByRole('button', {name: 'Go to page 3'}));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Page 3 of 10');
+      });
+    });
+
+    it('announces the next page when clicking next', async () => {
+      const user = userEvent.setup();
+      render(<Pagination page={2} onChange={() => {}} totalPages={5} />);
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Page 3 of 5');
+      });
+    });
+
+    it('announces without a total when only hasMore is known', async () => {
+      const user = userEvent.setup();
+      render(<Pagination page={1} onChange={() => {}} hasMore />);
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Page 2');
+      });
+    });
+
     it('calls onChange when clicking a page button', async () => {
       const user = userEvent.setup();
       const onChange = vi.fn();
@@ -395,7 +502,9 @@ describe('Pagination', () => {
       // reflects the page being navigated to.
       await user.click(screen.getByRole('button', {name: 'Go to next page'}));
       expect(changeAction).toHaveBeenCalledWith(2);
-      expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();
+      expect(
+        within(screen.getByRole('navigation')).getByText('Page 2 of 5'),
+      ).toBeInTheDocument();
 
       await act(async () => {
         resolveAction?.();
@@ -425,14 +534,17 @@ describe('Pagination', () => {
       );
 
       const next = screen.getByRole('button', {name: 'Go to next page'});
+      const nav = screen.getByRole('navigation');
       await act(async () => {
         fireEvent.click(next);
       });
-      expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();
+      // Scope to the nav landmark: the live region on document.body also
+      // carries the announced page text.
+      expect(within(nav).getByText('Page 2 of 5')).toBeInTheDocument();
       await act(async () => {
         fireEvent.click(next);
       });
-      expect(screen.getByText('Page 3 of 5')).toBeInTheDocument();
+      expect(within(nav).getByText('Page 3 of 5')).toBeInTheDocument();
 
       expect(changeAction).toHaveBeenCalledTimes(2);
       expect(changeAction).toHaveBeenNthCalledWith(1, 2);

package/src/Pagination/Pagination.tsx

@@ -34,6 +34,7 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {Selector} from '../Selector';
 import {Text} from '../Text';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -335,7 +336,7 @@ export function Pagination({
   totalItems,
   totalPages: totalPagesProp,
   hasMore,
-  pageSize = 10,
+  pageSize: pageSizeProp = 10,
   pageSizeOptions,
   onPageSizeChange,
   variant = 'pages',
@@ -351,6 +352,20 @@ export function Pagination({
 }: PaginationProps) {
   const [, startTransition] = useTransition();
 
+  // pageSize is typed as number, so 0, NaN, and negatives are valid at the
+  // type level but yield Infinity/NaN page counts, and
+  // Array.from({length: Infinity}) crashes the dots variant. Coerce to a
+  // positive integer; non-finite values fall back to the default.
+  const pageSize = Number.isFinite(pageSizeProp)
+    ? Math.max(1, Math.floor(pageSizeProp))
+    : 10;
+
+  // Announce page changes politely (navigation-10). The controls carry no
+  // live region, so page transitions were previously silent to screen readers.
+  // Only user-driven changes go through handlePageChange, so initial mount is
+  // never announced.
+  const announce = useAnnounce();
+
   // Track the page optimistically so rapid prev/next clicks advance from the
   // in-flight target instead of stalling on the last committed page.
   const [optimisticPage, setOptimisticPage] = useOptimistic(page);
@@ -384,6 +399,11 @@ export function Pagination({
     // Keep onChange urgent so controlled page state updates in the same commit
     // as the click; only the optimistic indicator and changeAction defer.
     onChange(newPage);
+    announce(
+      computedTotalPages != null
+        ? `Page ${newPage} of ${computedTotalPages}`
+        : `Page ${newPage}`,
+    );
     startTransition(async () => {
       setOptimisticPage(newPage);
       await changeAction?.(newPage);

package/src/Popover/Popover.doc.mjs

@@ -90,6 +90,18 @@ export const docs = {
           description: 'Whether to auto-focus the first focusable element when the popover opens. Set to false for inline showcases or documentation previews.',
           default: 'true',
         },
+        {
+          name: 'hasLightDismiss',
+          type: 'boolean',
+          description: 'Whether clicking outside dismisses the popover. Set to false for surfaces that stay open until explicitly dismissed, like onboarding coachmarks.',
+          default: 'true',
+        },
+        {
+          name: 'hasEscapeDismiss',
+          type: 'boolean',
+          description: 'Whether pressing Escape dismisses the popover. Only takes full effect together with hasLightDismiss={false}, since native light dismiss also closes on Escape.',
+          default: 'true',
+        },
         {
           name: 'xstyle',
           type: 'StyleXStyles',
@@ -219,6 +231,18 @@ export const docsZh = {
           description: '弹出框打开时是否自动聚焦第一个可聚焦元素。内联展示或文档预览设为 false。',
           default: 'true',
         },
+        {
+          name: 'hasLightDismiss',
+          type: 'boolean',
+          description: '点击外部是否关闭弹出框。需要显式关闭的界面（如新手引导提示）设为 false。',
+          default: 'true',
+        },
+        {
+          name: 'hasEscapeDismiss',
+          type: 'boolean',
+          description: '按 Escape 是否关闭弹出框。仅在 hasLightDismiss={false} 时生效，因为原生 light dismiss 行为同样响应 Escape。',
+          default: 'true',
+        },
       ],
     },
   ],
@@ -291,6 +315,8 @@ export const docsDense = {
         hasCloseButton: 'Whether to include hidden close button for accessibility.',
         closeButtonLabel: 'Label for hidden close button.',
         hasAutoFocus: 'Auto-focus first element on open; false for showcases.',
+        hasLightDismiss: 'Outside click dismisses; false for explicit-dismiss surfaces (coachmarks).',
+        hasEscapeDismiss: 'Escape dismisses; full effect only with hasLightDismiss=false.',
       },
     },
   ],

package/src/Popover/Popover.test.tsx

@@ -13,6 +13,7 @@ import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import React, {useRef} from 'react';
 import {Popover} from './Popover';
+import {Dialog} from '../Dialog';
 
 // Store original matches to restore later
 const originalMatches = HTMLElement.prototype.matches;
@@ -233,4 +234,124 @@ describe('Popover', () => {
     );
     warnSpy.mockRestore();
   });
+
+  describe('dismiss controls', () => {
+    // jsdom does not implement <dialog> showModal/close, needed by the
+    // host-Dialog fall-through test below.
+    beforeAll(() => {
+      HTMLDialogElement.prototype.showModal = vi.fn(function (
+        this: HTMLDialogElement,
+      ) {
+        this.setAttribute('open', '');
+      });
+      HTMLDialogElement.prototype.close = vi.fn(function (
+        this: HTMLDialogElement,
+      ) {
+        this.removeAttribute('open');
+      });
+    });
+
+    it('dismisses on Escape by default', () => {
+      render(
+        <Popover content={<span>Content</span>} label="Test">
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open'});
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      fireEvent.keyDown(document, {key: 'Escape'});
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('stays open on Escape when hasEscapeDismiss is false', () => {
+      render(
+        <Popover
+          content={<span>Content</span>}
+          label="Test"
+          hasLightDismiss={false}
+          hasEscapeDismiss={false}>
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open'});
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      fireEvent.keyDown(document, {key: 'Escape'});
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('still dismisses on Escape when only light dismiss is off', () => {
+      render(
+        <Popover
+          content={<span>Content</span>}
+          label="Test"
+          hasLightDismiss={false}>
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open'});
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      fireEvent.keyDown(document, {key: 'Escape'});
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('switches to popover="manual" when hasLightDismiss is false', () => {
+      const {unmount} = render(
+        <Popover content={<span>Content</span>} label="Test">
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      fireEvent.click(screen.getByRole('button', {name: 'Open'}));
+      expect(document.querySelector('[popover]')).toHaveAttribute(
+        'popover',
+        'auto',
+      );
+      unmount();
+
+      render(
+        <Popover
+          content={<span>Content</span>}
+          label="Test"
+          hasLightDismiss={false}>
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      fireEvent.click(screen.getByRole('button', {name: 'Open'}));
+      expect(document.querySelector('[popover]')).toHaveAttribute(
+        'popover',
+        'manual',
+      );
+    });
+
+    it('lets Escape fall through to a host Dialog when fully opted out', () => {
+      const onDialogOpenChange = vi.fn();
+      render(
+        <Dialog isOpen={true} onOpenChange={onDialogOpenChange} purpose="info">
+          <Popover
+            content={<span>Coachmark</span>}
+            label="Tip"
+            hasLightDismiss={false}
+            hasEscapeDismiss={false}>
+            <button type="button">Open tip</button>
+          </Popover>
+        </Dialog>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open tip'});
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      // The Dialog listens for Escape on the dialog element, so fire from a
+      // node inside it. The popover registers no Escape handler, so
+      // hasActiveFocusTrapEscape() is false and the Dialog handles the press
+      // while the popover itself stays open.
+      fireEvent.keyDown(trigger, {key: 'Escape'});
+      expect(onDialogOpenChange).toHaveBeenCalledWith(false);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    });
+  });
 });

package/src/Popover/Popover.tsx

@@ -186,6 +186,24 @@ export interface PopoverProps extends Pick<
    */
   hasAutoFocus?: boolean;
 
+  /**
+   * Whether clicking outside dismisses the popover.
+   * Set to `false` for surfaces that should stay open until explicitly
+   * dismissed, like onboarding coachmarks or multi-step flows.
+   * @default true
+   */
+  hasLightDismiss?: boolean;
+
+  /**
+   * Whether pressing Escape dismisses the popover.
+   *
+   * Only takes full effect together with `hasLightDismiss={false}`: with
+   * light dismiss on, the browser's native light dismiss also closes on
+   * Escape. Set both to `false` for explicit-dismiss-only surfaces.
+   * @default true
+   */
+  hasEscapeDismiss?: boolean;
+
   /**
    * Test ID for the popover container.
    */
@@ -239,7 +257,7 @@ const styles = stylex.create({
  * (immune to pressed-state transforms like `:active { scale(0.98) }`).
  *
  * Focus is trapped inside the popover when open.
- * Supports light dismiss (click outside or Escape to close).
+ * Supports light dismiss by default (click outside or Escape to close).
  *
  * For hover-triggered overlays, use {@link HoverCard} instead.
  *
@@ -277,6 +295,8 @@ export function Popover({
   hasCloseButton,
   closeButtonLabel,
   hasAutoFocus,
+  hasLightDismiss = true,
+  hasEscapeDismiss = true,
   xstyle,
   className,
   style,
@@ -299,7 +319,8 @@ export function Popover({
 
   const popover = usePopover({
     dialogLabel: label,
-    hasLightDismiss: true,
+    hasLightDismiss,
+    hasEscapeDismiss,
     hasCloseButton,
     closeButtonLabel,
     hasAutoFocus,

package/src/Popover/usePopover.doc.mjs

@@ -11,10 +11,13 @@ export const docs = {
     {name: 'onHide', type: '() => void', description: 'Callback fired when the popover is hidden. Use this to return focus to the trigger when needed.'},
     {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles applied to the popover content wrapper, after the default surface styles.'},
     {name: 'hasLightDismiss', type: 'boolean', description: 'Whether clicking outside dismisses the popover.', default: 'true'},
+    {name: 'hasEscapeDismiss', type: 'boolean', description: 'Whether pressing Escape dismisses the popover. Only takes full effect together with hasLightDismiss: false, since native light dismiss also closes on Escape.', default: 'true'},
     {name: 'hasAutoFocus', type: 'boolean', description: 'Whether to automatically focus the first focusable element when opened.', default: 'true'},
     {name: 'hasCloseButton', type: 'boolean', description: 'Whether to include a hidden close button that appears for keyboard users.', default: 'true'},
     {name: 'closeButtonLabel', type: 'string', description: 'Accessible label for the hidden close button.', default: "'Close popover'"},
-    {name: 'dialogLabel', type: 'string', description: 'Accessible label for the popover dialog. Provide one when there is no visible title.'},
+    {name: 'dialogLabel', type: 'string', description: 'Accessible label for the popover dialog (only applies when role is "dialog"). Provide one when there is no visible title.'},
+    {name: 'role', type: "'dialog' | 'none'", description: 'ARIA role on the content wrapper. Use "dialog" for genuine dialog content; use "none" for listbox/menu popups whose own content role should be exposed and whose trigger keeps DOM focus.', default: "'dialog'"},
+    {name: 'isModal', type: 'boolean', description: 'Whether a dialog-role popover is modal (aria-modal). Only applies when role is "dialog".', default: 'true'},
     {name: 'hasSurface', type: 'boolean', description: 'Whether to apply the default popover surface background, radius, and shadow.', default: 'true'},
   ],
   returns: [
@@ -27,7 +30,7 @@ export const docs = {
     {name: 'isOpen', type: 'boolean', description: 'Whether the popover is currently open.'},
     {name: 'id', type: 'string', description: 'Unique ID for aria-describedby or aria-controls.'},
     {name: 'render', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for anchor-positioned popover content. Pass placement and alignment here.'},
-    {name: 'triggerProps', type: '{aria-haspopup: "dialog"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element.'},
+    {name: 'triggerProps', type: '{aria-haspopup: "dialog" | "true"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element. aria-haspopup reflects the popover role.'},
   ],
   usage: {
     description: 'Headless hook for click-triggered popovers with focus trapping. Combines useLayer with useFocusTrap, auto-focus, light dismiss, Escape handling, and an optional hidden close button for accessible dialog-like popover behavior. Use for custom interactive floating content that needs keyboard navigation.',
@@ -51,10 +54,13 @@ export const docsDense = {
     onHide: 'fires when popover hides; use to return focus when needed.',
     xstyle: 'StyleX styles for content wrapper, after default surface.',
     hasLightDismiss: 'whether outside click dismisses popover.',
+    hasEscapeDismiss: 'whether Escape dismisses; full effect only w/ hasLightDismiss false.',
     hasAutoFocus: 'whether first focusable element receives focus on open.',
     hasCloseButton: 'whether hidden keyboard close button is included.',
     closeButtonLabel: 'label for hidden close button.',
-    dialogLabel: 'accessible label for popover dialog.',
+    dialogLabel: 'accessible label for popover dialog (role="dialog" only).',
+    role: 'content wrapper ARIA role; "none" for listbox/menu popups.',
+    isModal: 'whether a dialog-role popover is modal (aria-modal).',
     hasSurface: 'apply default surface background/radius/shadow.',
   },
   returnDescriptions: {

package/src/Popover/usePopover.tsx

@@ -109,6 +109,19 @@ export interface UsePopoverOptions {
    */
   hasLightDismiss?: boolean;
 
+  /**
+   * Whether pressing Escape dismisses the popover.
+   *
+   * Takes effect together with `hasLightDismiss: false`: with light dismiss
+   * on, the native popover uses `popover="auto"`, whose browser-level light
+   * dismiss also closes on Escape, so Escape handling stays registered to
+   * keep topmost-only dismissal intact. Set both to `false` for
+   * explicit-dismiss-only surfaces like onboarding coachmarks.
+   *
+   * @default true
+   */
+  hasEscapeDismiss?: boolean;
+
   /**
    * Whether to automatically focus the first focusable element when opened.
    * @default true
@@ -130,10 +143,35 @@ export interface UsePopoverOptions {
 
   /**
    * Accessible label for the dialog.
-   * Required for screen readers to announce the dialog purpose.
+   * Required for screen readers to announce the dialog purpose
+   * (only applies when `role` is `'dialog'`).
    */
   dialogLabel?: string;
 
+  /**
+   * ARIA role stamped on the popover content wrapper.
+   *
+   * - `'dialog'` (default): the wrapper is a `role="dialog"` and, when
+   *   `isModal` is true, carries `aria-modal`. Use for genuine dialog content.
+   * - `'none'`: the wrapper carries no role or `aria-modal`, so the popup's own
+   *   content role (e.g. a child `role="listbox"` or `role="menu"`) is the
+   *   exposed semantics. Use for comboboxes, listboxes, and menus — their
+   *   trigger keeps DOM focus, so announcing an unnamed modal dialog around
+   *   them is incorrect.
+   *
+   * @default 'dialog'
+   */
+  role?: 'dialog' | 'none';
+
+  /**
+   * Whether the dialog is modal (`aria-modal`). Only applies when `role` is
+   * `'dialog'`. Set to `false` for non-modal dialogs that do not inert the rest
+   * of the page.
+   *
+   * @default true
+   */
+  isModal?: boolean;
+
   /**
    * Whether to apply the default popover surface (background, border-radius,
    * box-shadow) to the content wrapper.
@@ -215,7 +253,7 @@ export interface UsePopoverReturn {
    * ARIA attributes to spread on the trigger element
    */
   triggerProps: {
-    'aria-haspopup': 'dialog';
+    'aria-haspopup': 'dialog' | 'true';
     'aria-expanded': boolean;
     'aria-controls': string;
   };
@@ -228,7 +266,7 @@ export interface UsePopoverReturn {
  * - `useLayer` for popover positioning using CSS anchor positioning
  * - `useFocusTrap` for trapping focus within the popover content
  * - Auto-focus first element on open
- * - Escape key to close
+ * - Escape key to close (configurable via hasEscapeDismiss)
  * - Hidden close button that reveals on focus for accessibility
  *
  * The render function automatically wraps your content in a focus trap container
@@ -261,19 +299,20 @@ export interface UsePopoverReturn {
  * }
  * ```
  */
-export function usePopover(
-  options: UsePopoverOptions = {},
-): UsePopoverReturn {
+export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
   const {
     onShow,
     onHide,
     xstyle,
     hasLightDismiss = true,
+    hasEscapeDismiss = true,
     hasAutoFocus = true,
     hasSurface = true,
     hasCloseButton = true,
     closeButtonLabel = 'Close popover',
     dialogLabel,
+    role = 'dialog',
+    isModal = true,
   } = options;
 
   // Track the trigger element for returning focus
@@ -290,10 +329,12 @@ export function usePopover(
     onHide,
   });
 
-  // Focus trap for the popover content
+  // Focus trap for the popover content. Escape stays registered while light
+  // dismiss is on (native popover="auto" closes on Escape regardless), so a
+  // host Dialog keeps deferring to this trap instead of double-dismissing.
   const {containerRef: contentRef, focusFirst} = useFocusTrap<HTMLDivElement>({
     isActive: layer.isOpen,
-    onEscape: layer.hide,
+    onEscape: hasEscapeDismiss || hasLightDismiss ? layer.hide : undefined,
   });
 
   // Auto-focus first element when popover opens (unless skipped)
@@ -339,20 +380,35 @@ export function usePopover(
 
   // ARIA attributes for the trigger
   const triggerProps = {
-    'aria-haspopup': 'dialog' as const,
+    'aria-haspopup':
+      role === 'dialog' ? ('dialog' as const) : ('true' as const),
     'aria-expanded': layer.isOpen,
     'aria-controls': layer.id,
   };
 
+  // Dev-time guardrail: a dialog popover should always be labeled. Warn once
+  // per hook instance (in an effect) rather than on every render.
+  const warnedUnnamedDialogRef = useRef(false);
+  useEffect(() => {
+    if (role === 'dialog' && !dialogLabel && !warnedUnnamedDialogRef.current) {
+      warnedUnnamedDialogRef.current = true;
+      console.warn(
+        'usePopover: role="dialog" without a `dialogLabel` renders an unnamed ' +
+          'dialog. Pass `dialogLabel`, or use `role: "none"` for listbox/menu ' +
+          'popups whose content already carries its own role.',
+      );
+    }
+  }, [role, dialogLabel]);
+
   // Wrapped render function that includes surface styles and optional hidden close button
   const render = useCallback(
     (children: ReactNode, props?: ContextRenderProps): ReactNode => {
       return layer.render(
         <div
           ref={contentRef}
-          role="dialog"
-          aria-modal="true"
-          aria-label={dialogLabel}
+          role={role === 'dialog' ? 'dialog' : undefined}
+          aria-modal={role === 'dialog' && isModal ? true : undefined}
+          aria-label={role === 'dialog' ? dialogLabel : undefined}
           {...stylex.props(
             styles.contentWrapper,
             hasSurface && styles.surface,
@@ -379,6 +435,8 @@ export function usePopover(
       closeButtonLabel,
       contentRef,
       dialogLabel,
+      role,
+      isModal,
       xstyle,
     ],
   );