@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

package/src/Dialog/Dialog.doc.mjs

@@ -111,7 +111,7 @@ export const docs = {
       { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },
     ],
     anatomy: [
-      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open for accessibility.'},
+      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby.'},
       {name: 'Body', required: true, description: 'The main content area: text, forms, lists, or any layout.'},
       {name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},
       {name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},
@@ -133,7 +133,7 @@ export const docsZh = {
       { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },
     ],
     anatomy: [
-      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open for accessibility.'},
+      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby.'},
       {name: 'Body', required: true, description: 'The main content area: text, forms, lists, or any layout.'},
       {name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},
       {name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},

package/src/Dialog/Dialog.test.tsx

@@ -212,10 +212,7 @@ describe('Dialog', () => {
 
   it('forwards additional props to dialog element', () => {
     render(
-      <Dialog
-        isOpen={true}
-        onOpenChange={() => {}}
-        data-testid="custom-dialog">
+      <Dialog isOpen={true} onOpenChange={() => {}} data-testid="custom-dialog">
         Content
       </Dialog>,
     );
@@ -267,6 +264,82 @@ describe('Dialog', () => {
     });
   });
 
+  describe('accessible name', () => {
+    it('is labelled by the DialogHeader title by default', () => {
+      render(
+        <Dialog isOpen={true} onOpenChange={() => {}}>
+          <DialogHeader title="Dialog title" />
+        </Dialog>,
+      );
+      const dialog = screen.getByRole('dialog');
+      const heading = screen.getByRole('heading', {name: 'Dialog title'});
+      expect(heading.id).not.toBe('');
+      expect(dialog).toHaveAttribute('aria-labelledby', heading.id);
+      expect(dialog).toHaveAccessibleName('Dialog title');
+    });
+
+    it('prefers a consumer-provided aria-label over the header title', () => {
+      render(
+        <Dialog isOpen={true} onOpenChange={() => {}} aria-label="Custom name">
+          <DialogHeader title="Dialog title" />
+        </Dialog>,
+      );
+      const dialog = screen.getByRole('dialog');
+      expect(dialog).not.toHaveAttribute('aria-labelledby');
+      expect(dialog).toHaveAccessibleName('Custom name');
+    });
+
+    it('prefers a consumer-provided aria-labelledby over the header title', () => {
+      render(
+        <>
+          <span id="external-label">External name</span>
+          <Dialog
+            isOpen={true}
+            onOpenChange={() => {}}
+            aria-labelledby="external-label">
+            <DialogHeader title="Dialog title" />
+          </Dialog>
+        </>,
+      );
+      const dialog = screen.getByRole('dialog');
+      expect(dialog).toHaveAttribute('aria-labelledby', 'external-label');
+      expect(dialog).toHaveAccessibleName('External name');
+    });
+
+    it('omits aria-labelledby and warns when open with no name source', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        render(
+          <Dialog isOpen={true} onOpenChange={() => {}}>
+            Content
+          </Dialog>,
+        );
+        const dialog = screen.getByRole('dialog');
+        expect(dialog).not.toHaveAttribute('aria-labelledby');
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('accessible name'),
+        );
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    it('does not warn when the header provides a title', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      try {
+        render(
+          <Dialog isOpen={true} onOpenChange={() => {}}>
+            <DialogHeader title="Dialog title" />
+          </Dialog>,
+        );
+        expect(warnSpy).not.toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+  });
+
   describe('inner flex wrapper', () => {
     it('wraps children in a flex container for scroll support', () => {
       render(

package/src/Dialog/Dialog.tsx

@@ -16,7 +16,14 @@
  * - /packages/cli/templates/blocks/components/Dialog/ (showcase blocks)
  */
 
-import {useEffect, useMemo, useRef, type ReactNode} from 'react';
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {useScrollLock} from '../hooks/useScrollLock';
@@ -39,6 +46,7 @@ import {
 } from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
+import {devWarn} from '../utils/devWarning';
 import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
 
@@ -152,7 +160,13 @@ const styles = stylex.create({
   open: {
     display: 'flex',
     opacity: 1,
-    animationName: enterDirectional,
+    // Disable the entry keyframe animation under
+    // `prefers-reduced-motion: reduce` so the dialog appears instantly
+    // instead of translating/scaling in (same pattern as layerAnimations).
+    animationName: {
+      default: enterDirectional,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
   },
   // Backdrop using ::backdrop pseudo-element
   backdrop: {
@@ -312,6 +326,9 @@ export interface DialogProps extends BaseProps<HTMLDialogElement> {
  *
  * Designed to be used with Layout as its child for structured content.
  * Uses the browser's built-in modal behavior for optimal accessibility.
+ * When a DialogHeader is rendered inside, its title automatically names the
+ * dialog via aria-labelledby; pass `aria-label` or `aria-labelledby` to
+ * override.
  *
  * @example
  * ```
@@ -348,10 +365,47 @@ export function Dialog({
   const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
 
   const isFullscreen = variant === 'fullscreen';
-  const dialogContextValue = useMemo(() => ({isInline}), [isInline]);
+
+  // Default accessible name: publish a title id through DialogContext so a
+  // DialogHeader applies it to its heading (mirrors AlertDialog's explicit
+  // useId wiring). Whether to emit the default aria-labelledby is decided
+  // imperatively in the callback ref below by checking whether the title
+  // element actually rendered — so a dialog with no header never points at a
+  // missing id, and we avoid the extra render a registration-via-state effect
+  // would cost at the dialog level.
+  const titleId = useId();
+
+  const dialogContextValue = useMemo(
+    () => ({isInline, titleId}),
+    [isInline, titleId],
+  );
+
+  // Consumer-provided labels always win over the DialogHeader default.
+  const hasConsumerName =
+    props['aria-label'] != null || props['aria-labelledby'] != null;
 
   const dialogRef = useRef<HTMLDialogElement>(null);
 
+  // Callback ref on the <dialog>: sync the default aria-labelledby from the
+  // DialogHeader title (if one rendered) in the same commit, with no second
+  // render. Consumer aria-label/aria-labelledby win — when present we leave
+  // the attribute to the {...safeProps} spread and never touch it here.
+  const attachDialog = useCallback(
+    (node: HTMLDialogElement | null) => {
+      dialogRef.current = node;
+      if (!node || hasConsumerName) {
+        return;
+      }
+      const hasTitle = node.querySelector(`#${CSS.escape(titleId)}`) != null;
+      if (hasTitle) {
+        node.setAttribute('aria-labelledby', titleId);
+      } else {
+        node.removeAttribute('aria-labelledby');
+      }
+    },
+    [titleId, hasConsumerName],
+  );
+
   // Capture the element that was focused when the dialog opened,
   // for directional animation origin and focus restoration on close.
   const triggerElementRef = useRef<HTMLElement | null>(null);
@@ -440,6 +494,29 @@ export function Dialog({
     return () => dialog.removeEventListener('keydown', handleKeyDown);
   }, [isOpen, isInline, allowEscape, onOpenChange]);
 
+  // Dev-time guardrail: an open modal should always have an accessible name.
+  // The header-title check reads the DOM, so this stays in an effect; the ref
+  // keeps it to one warning per component instance.
+  const warnedUnnamedDialogRef = useRef(false);
+  useEffect(() => {
+    const hasHeaderTitle =
+      dialogRef.current?.querySelector(`#${CSS.escape(titleId)}`) != null;
+    if (
+      isOpen &&
+      !isInline &&
+      !hasConsumerName &&
+      !hasHeaderTitle &&
+      !warnedUnnamedDialogRef.current
+    ) {
+      warnedUnnamedDialogRef.current = true;
+      devWarn(
+        'Dialog',
+        'open dialog has no accessible name. Add a DialogHeader ' +
+          'with a `title`, or pass `aria-label`/`aria-labelledby`.',
+      );
+    }
+  }, [isOpen, isInline, hasConsumerName, titleId]);
+
   // Handle backdrop click — when the user clicks the ::backdrop pseudo-element,
   // the event target is the <dialog> element itself; clicks on child content
   // always target the child. This avoids false positives from native browser
@@ -531,7 +608,11 @@ export function Dialog({
           ),
           className,
           style,
-        )}>
+        )}
+        data-testid={
+          (props as Record<string, unknown>)['data-testid'] as
+            string | undefined
+        }>
         {innerContent}
       </div>
     );
@@ -541,7 +622,7 @@ export function Dialog({
 
   return (
     <dialog
-      ref={mergeRefs(ref, dialogRef)}
+      ref={mergeRefs(ref, attachDialog)}
       {...safeProps}
       {...mergeProps(
         themeProps('dialog', {variant}),
@@ -566,6 +647,9 @@ export function Dialog({
       onClick={handleClick}
       onCancel={handleCancel}
       aria-modal="true"
+      // The default aria-labelledby (from a DialogHeader title) is set
+      // imperatively in `attachDialog`; a consumer-provided aria-labelledby
+      // flows through {...safeProps} above and wins.
       {...(purpose === 'required' ? {role: 'alertdialog'} : undefined)}>
       {innerContent}
     </dialog>

package/src/Dialog/DialogContext.ts

@@ -5,8 +5,8 @@
 /**
  * @file DialogContext.ts
  * @input React context
- * @output Internal dialog context for child focus behavior
- * @position Dialog internals; consumed by focus-managing children
+ * @output Internal dialog context for child focus behavior and default labelling
+ * @position Dialog internals; consumed by focus-managing children and DialogHeader
  */
 
 import {createContext, use} from 'react';
@@ -14,6 +14,13 @@ import {createContext, use} from 'react';
 export interface DialogContextValue {
   /** Whether the dialog is rendered inline for docs/showcases. */
   isInline: boolean;
+  /**
+   * Id the DialogHeader title should render with so the dialog can name
+   * itself via aria-labelledby. The dialog detects the title element's
+   * presence directly (via a callback ref), so it only emits aria-labelledby
+   * when the title actually rendered — never pointing at a nonexistent id.
+   */
+  titleId?: string;
 }
 
 export const DialogContext = createContext<DialogContextValue | null>(null);

package/src/Dialog/DialogHeader.doc.mjs

@@ -12,7 +12,7 @@ export const docs = {
     {
       name: 'title',
       type: 'string',
-      description: 'Dialog title (receives focus on open).',
+      description: 'Dialog title (receives focus on open and labels the dialog via aria-labelledby).',
     },
     {
       name: 'subtitle',
@@ -158,7 +158,7 @@ export const docsDense = {
   displayName: 'Dialog Header',
   description: 'dialog header w/ title, optional subtitle, close button, start/end content slots',
   propDescriptions: {
-    title: 'dialog title (receives focus on open)',
+    title: 'dialog title (focused on open; labels dialog via aria-labelledby)',
     subtitle: 'subtitle below title',
     onOpenChange: 'close button callback (omit=no button)',
     startContent: 'content before title (e.g. back button)',

package/src/Dialog/DialogHeader.tsx

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

package/src/Divider/Divider.tsx

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

package/src/DropdownMenu/DropdownMenu.test.tsx

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

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -152,8 +152,7 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
  *
  * @example
  * ```
- *  * import {DropdownMenuCheckboxItem} from '@astryxdesign/core/DropdownMenu';
- *
+ * import {DropdownMenuCheckboxItem} from '@astryxdesign/core/DropdownMenu';
  * <DropdownMenu button={{label: 'View'}}>
  *   <DropdownMenuCheckboxItem
  *     label="Show archived"

package/src/DropdownMenu/DropdownMenuItem.tsx

@@ -55,7 +55,7 @@ const menuItemStyles = stylex.create({
     },
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left',
+    textAlign: 'start',
     outline: 'none',
   },
   disabled: {

package/src/DropdownMenu/DropdownMenuRadioGroup.tsx

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