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

package/src/DateTimeInput/DateTimeInput.test.tsx

@@ -9,8 +9,9 @@
  * SYNC: When DateTimeInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {DateTimeInput} from './DateTimeInput';
 import type {ISODateTimeString} from './DateTimeInput';
 
@@ -20,6 +21,25 @@ describe('DateTimeInput', () => {
     expect(screen.getByLabelText('Meeting time')).toBeInTheDocument();
   });
 
+  it('derives the time input label from the field label (forms-15)', () => {
+    render(<DateTimeInput label="Meeting time" onChange={() => {}} />);
+    // Not a hardcoded "Time" — tied to the field label so it is localizable
+    // and unambiguous when multiple date-time fields share a page.
+    expect(screen.getByLabelText('Meeting time time')).toBeInTheDocument();
+    expect(screen.queryByLabelText('Time')).not.toBeInTheDocument();
+  });
+
+  it('uses an explicit timeLabel when provided', () => {
+    render(
+      <DateTimeInput
+        label="Meeting time"
+        timeLabel="Start time"
+        onChange={() => {}}
+      />,
+    );
+    expect(screen.getByLabelText('Start time')).toBeInTheDocument();
+  });
+
   it('renders with placeholder', () => {
     render(
       <DateTimeInput
@@ -31,10 +51,32 @@ describe('DateTimeInput', () => {
     expect(screen.getByPlaceholderText('Pick a date')).toBeInTheDocument();
   });
 
+  it('defaults the time portion placeholder to "Select a time"', () => {
+    render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+    expect(screen.getByPlaceholderText('Select a time')).toBeInTheDocument();
+  });
+
+  it('applies a custom timePlaceholder to the time portion', () => {
+    render(
+      <DateTimeInput
+        label="Meeting"
+        onChange={() => {}}
+        placeholder="Pick a date"
+        timePlaceholder="Pick a time"
+      />,
+    );
+    // Time portion uses the override; date portion keeps its own placeholder.
+    expect(screen.getByPlaceholderText('Pick a time')).toBeInTheDocument();
+    expect(screen.getByPlaceholderText('Pick a date')).toBeInTheDocument();
+    expect(
+      screen.queryByPlaceholderText('Select a time'),
+    ).not.toBeInTheDocument();
+  });
+
   it('renders both date and time inputs', () => {
     render(<DateTimeInput label="Meeting" onChange={() => {}} />);
     expect(screen.getByRole('combobox')).toBeInTheDocument();
-    expect(screen.getByLabelText('Time')).toBeInTheDocument();
+    expect(screen.getByLabelText('Meeting time')).toBeInTheDocument();
   });
 
   it('displays formatted date in date input when value is provided', () => {
@@ -90,9 +132,7 @@ describe('DateTimeInput', () => {
   });
 
   it('visually hides label when isLabelHidden is true', () => {
-    render(
-      <DateTimeInput label="Meeting" isLabelHidden onChange={() => {}} />,
-    );
+    render(<DateTimeInput label="Meeting" isLabelHidden onChange={() => {}} />);
     const label = screen.getByText('Meeting');
     expect(label).toBeInTheDocument();
     expect(screen.getByLabelText('Meeting')).toBeInTheDocument();
@@ -114,13 +154,13 @@ describe('DateTimeInput', () => {
   it('sets disabled on both inputs when isDisabled is true', () => {
     render(<DateTimeInput label="Meeting" isDisabled onChange={() => {}} />);
     expect(screen.getByRole('combobox')).toBeDisabled();
-    expect(screen.getByLabelText('Time')).toBeDisabled();
+    expect(screen.getByLabelText('Meeting time')).toBeDisabled();
   });
 
   it('is not disabled by default', () => {
     render(<DateTimeInput label="Meeting" onChange={() => {}} />);
     expect(screen.getByRole('combobox')).not.toBeDisabled();
-    expect(screen.getByLabelText('Time')).not.toBeDisabled();
+    expect(screen.getByLabelText('Meeting time')).not.toBeDisabled();
   });
 
   it('date input has role="combobox"', () => {
@@ -160,7 +200,7 @@ describe('DateTimeInput', () => {
   it('disables inputs and button when isLoading is true', () => {
     render(<DateTimeInput label="Meeting" isLoading onChange={() => {}} />);
     expect(screen.getByRole('combobox')).toBeDisabled();
-    expect(screen.getByLabelText('Time')).toBeDisabled();
+    expect(screen.getByLabelText('Meeting time')).toBeDisabled();
     expect(screen.getByRole('button', {name: 'Open calendar'})).toBeDisabled();
   });
 
@@ -284,7 +324,7 @@ describe('DateTimeInput', () => {
     const onChange = vi.fn();
     render(<DateTimeInput label="Meeting" onChange={onChange} />);
 
-    const timeInput = screen.getByLabelText('Time');
+    const timeInput = screen.getByLabelText('Meeting time');
     fireEvent.change(timeInput, {target: {value: '3:45 pm'}});
 
     expect(onChange).not.toHaveBeenCalled();
@@ -300,7 +340,7 @@ describe('DateTimeInput', () => {
       />,
     );
 
-    const timeInput = screen.getByLabelText('Time');
+    const timeInput = screen.getByLabelText('Meeting time');
     fireEvent.change(timeInput, {target: {value: '3:45 pm'}});
 
     expect(onChange).toHaveBeenCalledWith('2026-03-15T15:45');
@@ -409,4 +449,232 @@ describe('DateTimeInput', () => {
       expect(dateInput).toHaveValue('March 20, 2026');
     });
   });
+
+  describe('invalid typed input feedback (WCAG 3.3.1)', () => {
+    it('sets aria-invalid="true" on the date input when typed date is unparseable', () => {
+      render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+
+      const dateInput = screen.getByRole('combobox');
+      fireEvent.change(dateInput, {target: {value: '13/45/2024'}});
+
+      expect(dateInput).toHaveAttribute('aria-invalid', 'true');
+    });
+
+    it('does not set aria-invalid on the date input when typed date is valid', () => {
+      render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+
+      const dateInput = screen.getByRole('combobox');
+      fireEvent.change(dateInput, {target: {value: '03/15/2026'}});
+
+      expect(dateInput).not.toHaveAttribute('aria-invalid');
+    });
+
+    it('announces an alert message when the typed date is invalid', () => {
+      render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+
+      const dateInput = screen.getByRole('combobox');
+      fireEvent.change(dateInput, {target: {value: '13/45/2024'}});
+
+      expect(screen.getByText('Invalid date')).toBeInTheDocument();
+    });
+
+    it('sets aria-invalid="true" on the time input when typed time is unparseable', () => {
+      render(
+        <DateTimeInput
+          label="Meeting"
+          value={'2026-03-15T10:00' as ISODateTimeString}
+          onChange={() => {}}
+        />,
+      );
+
+      const timeInput = screen.getByLabelText('Meeting time');
+      fireEvent.change(timeInput, {target: {value: '99:99 zz'}});
+
+      expect(timeInput).toHaveAttribute('aria-invalid', 'true');
+    });
+
+    it('does not set aria-invalid on the time input when typed time is valid', () => {
+      render(
+        <DateTimeInput
+          label="Meeting"
+          value={'2026-03-15T10:00' as ISODateTimeString}
+          onChange={() => {}}
+        />,
+      );
+
+      const timeInput = screen.getByLabelText('Meeting time');
+      fireEvent.change(timeInput, {target: {value: '3:45 pm'}});
+
+      expect(timeInput).not.toHaveAttribute('aria-invalid');
+    });
+
+    it('announces an alert message when the typed time is invalid', () => {
+      render(
+        <DateTimeInput
+          label="Meeting"
+          value={'2026-03-15T10:00' as ISODateTimeString}
+          onChange={() => {}}
+        />,
+      );
+
+      const timeInput = screen.getByLabelText('Meeting time');
+      fireEvent.change(timeInput, {target: {value: '99:99 zz'}});
+
+      expect(screen.getByText('Invalid time')).toBeInTheDocument();
+    });
+  });
+  describe('disabledMessage', () => {
+    // jsdom does not implement the Popover API used by the tooltip, so mock
+    // showPopover/hidePopover to toggle a `popover-open` attribute the tests
+    // can assert on.
+    beforeEach(() => {
+      HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+        this.setAttribute('popover-open', '');
+      });
+      HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+        this.removeAttribute('popover-open');
+      });
+    });
+
+    // jsdom popover content is in the DOM but not "visible" in the
+    // accessibility tree; use hidden: true to find it.
+    const h = {hidden: true} as const;
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <DateTimeInput
+          label="When"
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      // The tooltip anchors on the outer row that wraps both inputs.
+      const dateInput = screen.getByRole('combobox');
+      const row = dateInput.parentElement?.parentElement as HTMLElement;
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('You need the Editor role');
+
+      fireEvent.mouseEnter(row);
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+
+      fireEvent.mouseLeave(row);
+      await waitFor(() => {
+        expect(tooltip).not.toHaveAttribute('popover-open');
+      });
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <DateTimeInput
+          label="When"
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('combobox')).toHaveFocus();
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <DateTimeInput
+          label="When"
+          onChange={() => {}}
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(<DateTimeInput label="When" onChange={() => {}} isDisabled />);
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps both inputs focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <DateTimeInput
+          label="When"
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const dateInput = screen.getByRole('combobox');
+      const timeInput = screen.getByLabelText('When time');
+      expect(dateInput).not.toBeDisabled();
+      expect(dateInput).toHaveAttribute('aria-disabled', 'true');
+      expect(dateInput).toHaveAttribute('readonly');
+      expect(timeInput).not.toBeDisabled();
+      expect(timeInput).toHaveAttribute('aria-disabled', 'true');
+      expect(timeInput).toHaveAttribute('readonly');
+    });
+
+    it('links the reason tooltip from the date input via aria-describedby', () => {
+      render(
+        <DateTimeInput
+          label="When"
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const dateInput = screen.getByRole('combobox');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(dateInput.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks value changes and opening while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <DateTimeInput
+          label="When"
+          onChange={onChange}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const dateInput = screen.getByRole('combobox');
+      await user.click(dateInput);
+      await user.type(dateInput, '2026-03-15');
+      expect(dateInput).toHaveValue('');
+      expect(dateInput).toHaveAttribute('aria-expanded', 'false');
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      render(<DateTimeInput label="When" onChange={() => {}} isDisabled />);
+      const dateInput = screen.getByRole('combobox');
+      expect(dateInput).toBeDisabled();
+      expect(dateInput).not.toHaveAttribute('aria-disabled');
+    });
+
+    it('does not swap in the time format-hint placeholder on focus while disabled', () => {
+      render(
+        <DateTimeInput
+          label="When"
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const timeInput = screen.getByLabelText('When time');
+      timeInput.focus();
+      fireEvent.focus(timeInput);
+      expect(timeInput).toHaveAttribute('placeholder', 'Select a time');
+    });
+  });
 });

package/src/DateTimeInput/DateTimeInput.tsx

@@ -47,14 +47,12 @@ import {
   inputStatusFocusWithinStyles,
 } from '../Field';
 import {Icon} from '../Icon';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {Spinner} from '../Spinner';
-import {
-  Calendar,
-  type ISODateString,
-  type CalendarHandle,
-} from '../Calendar';
+import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';
 import {useCalendarConstraints} from '../Calendar/hooks';
 import {usePopover} from '../Popover';
+import {useTooltip} from '../Tooltip';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {
   type ISOTimeString,
@@ -213,6 +211,29 @@ export interface DateTimeInputProps extends Omit<
    */
   isDisabled?: boolean;
 
+  /**
+   * Explains why the input is disabled. When set together with
+   * `isDisabled`, the input shows a tooltip with this text on hover and
+   * keyboard focus, and the date and time fields stay focusable (via
+   * `aria-disabled`) so the reason is discoverable by keyboard and assistive
+   * technology. Typing and calendar activation stay blocked.
+   *
+   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <DateTimeInput
+   *   label="Meeting time"
+   *   value={dateTime}
+   *   onChange={setDateTime}
+   *   isDisabled
+   *   disabledMessage="You need the Editor role to change this"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
+
   /**
    * The selected datetime in ISO 8601 format ("YYYY-MM-DDTHH:MM" or "YYYY-MM-DDTHH:MM:SS").
    */
@@ -278,11 +299,24 @@ export interface DateTimeInputProps extends Omit<
   hasClear?: boolean;
 
   /**
-   * Placeholder text shown when no date is selected.
+   * Placeholder text shown in the date portion when no date is selected.
    * @default "Select a date"
    */
   placeholder?: string;
 
+  /**
+   * Placeholder text shown in the time portion when no time is selected.
+   * @default "Select a time"
+   */
+  timePlaceholder?: string;
+
+  /**
+   * Accessible label for the time portion of the field. Defaults to
+   * `"{label} time"` so it is tied to the field's own label and localizable,
+   * rather than a hardcoded English "Time".
+   */
+  timeLabel?: string;
+
   /**
    * The size of the inputs.
    * @default 'md'
@@ -373,6 +407,7 @@ export function DateTimeInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   value,
   onChange,
   changeAction,
@@ -385,6 +420,8 @@ export function DateTimeInput({
   timeIncrement = 1,
   hasClear = false,
   placeholder = 'Select a date',
+  timePlaceholder = 'Select a time',
+  timeLabel,
   size: sizeProp,
   status,
   labelTooltip,
@@ -412,6 +449,22 @@ export function DateTimeInput({
   const isBusy = isLoading || optimisticValue !== value;
   const isEffectivelyDisabled = isDisabled || isBusy;
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the outer row container (which already exists)
+  // and both the date and time inputs stay perceivable via aria-disabled
+  // instead of the disabled attribute. Typing is blocked with readOnly and the
+  // value mutation guards; calendar activation is blocked by the
+  // isEffectivelyDisabled guards. Only the persistent isDisabled state (not the
+  // transient busy state) surfaces a reason.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the inputs, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   const statusIconMap: Record<InputStatusType, IconName> = {
     warning: 'warning',
     error: 'error',
@@ -431,6 +484,7 @@ export function DateTimeInput({
     [
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
@@ -520,12 +574,12 @@ export function DateTimeInput({
     return isTimeInRange(parsed, timeMin, timeMax);
   }, [timePendingInput, hasSeconds, timeMin, timeMax]);
 
-  const timePlaceholder = useMemo(() => {
+  const resolvedTimePlaceholder = useMemo(() => {
     if (isTimeFocused && !timeDisplayValue) {
       return hourFormat === '12h' ? 'e.g., 2:30 PM' : 'e.g., 14:30';
     }
-    return 'Select a time';
-  }, [isTimeFocused, timeDisplayValue, hourFormat]);
+    return timePlaceholder;
+  }, [isTimeFocused, timeDisplayValue, hourFormat, timePlaceholder]);
 
   // --- Unified change handler ---
   const fireChange = useCallback(
@@ -598,6 +652,11 @@ export function DateTimeInput({
 
   const handleDateInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
+      // With a disabledMessage the input drops `disabled` for focusability, so
+      // guard value mutation explicitly (readOnly also blocks typing).
+      if (isEffectivelyDisabled) {
+        return;
+      }
       const text = e.target.value;
       setDatePendingInput(text);
 
@@ -613,7 +672,7 @@ export function DateTimeInput({
         calendarRef.current?.navigateTo(parsedISO);
       }
     },
-    [valueParts.date, isDateDisabled, handleDateChange],
+    [valueParts.date, isDateDisabled, handleDateChange, isEffectivelyDisabled],
   );
 
   const commitDatePendingInput = useCallback(() => {
@@ -666,6 +725,11 @@ export function DateTimeInput({
   // --- Time handlers ---
   const handleTimeInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
+      // With a disabledMessage the input drops `disabled` for focusability, so
+      // guard value mutation explicitly (readOnly also blocks typing).
+      if (isEffectivelyDisabled) {
+        return;
+      }
       const text = e.target.value;
       setTimePendingInput(text);
 
@@ -690,10 +754,19 @@ export function DateTimeInput({
       valueParts.time,
       valueParts.date,
       fireChange,
+      isEffectivelyDisabled,
     ],
   );
 
-  const handleTimeFocus = useCallback(() => setIsTimeFocused(true), []);
+  const handleTimeFocus = useCallback(() => {
+    // A disabled/busy input stays focusable (via aria-disabled) so its reason
+    // is discoverable, but it must not present editing affordances — keep the
+    // static placeholder rather than swapping in the format hint.
+    if (isEffectivelyDisabled) {
+      return;
+    }
+    setIsTimeFocused(true);
+  }, [isEffectivelyDisabled]);
 
   const handleTimeBlur = useCallback(() => {
     setIsTimeFocused(false);
@@ -788,6 +861,7 @@ export function DateTimeInput({
       statusVariant="detached"
       width={width}>
       <div
+        ref={disabledMessageTooltip.ref}
         {...rest}
         {...mergeProps(
           themeProps('date-time-input', {
@@ -832,10 +906,18 @@ export function DateTimeInput({
             onClick={handleDateInputClick}
             onKeyDown={handleDateKeyDown}
             placeholder={placeholder}
-            disabled={isEffectivelyDisabled}
+            // With a disabledMessage the input keeps focusability via
+            // aria-disabled so the reason is focus-discoverable; typing is
+            // blocked with readOnly and the mutation guards, and calendar
+            // activation is blocked by the isEffectivelyDisabled guards.
+            disabled={isEffectivelyDisabled && !showsDisabledMessage}
+            aria-disabled={showsDisabledMessage ? 'true' : undefined}
+            readOnly={showsDisabledMessage || undefined}
             aria-describedby={ariaDescribedBy}
             aria-required={isRequired === true ? 'true' : undefined}
-            aria-invalid={status?.type === 'error' ? 'true' : undefined}
+            aria-invalid={
+              status?.type === 'error' || !isDateInputValid ? 'true' : undefined
+            }
             aria-busy={isBusy || undefined}
             aria-expanded={popover.isOpen}
             aria-haspopup="dialog"
@@ -848,6 +930,15 @@ export function DateTimeInput({
               !isDateInputValid && styles.inputInvalid,
             )}
           />
+          {/*
+            Live region announcing invalid typed date input to assistive
+            technology. The value silently reverts on blur, so without this a
+            screen-reader user would get no feedback that their entry was
+            rejected (WCAG 3.3.1).
+          */}
+          <VisuallyHidden as="div" role="alert" aria-live="assertive">
+            {!isDateInputValid ? 'Invalid date' : ''}
+          </VisuallyHidden>
           {hasClear && value !== undefined && !isEffectivelyDisabled && (
             <button
               type="button"
@@ -893,17 +984,31 @@ export function DateTimeInput({
             onFocus={handleTimeFocus}
             onBlur={handleTimeBlur}
             onKeyDown={handleTimeKeyDown}
-            placeholder={timePlaceholder}
-            disabled={isEffectivelyDisabled}
-            aria-label="Time"
+            placeholder={resolvedTimePlaceholder}
+            // With a disabledMessage the input keeps focusability via
+            // aria-disabled so the reason is focus-discoverable; typing is
+            // blocked with readOnly and the mutation guards.
+            disabled={isEffectivelyDisabled && !showsDisabledMessage}
+            aria-disabled={showsDisabledMessage ? 'true' : undefined}
+            readOnly={showsDisabledMessage || undefined}
+            aria-label={timeLabel ?? `${label} time`}
             aria-required={isRequired === true ? 'true' : undefined}
-            aria-invalid={status?.type === 'error' ? 'true' : undefined}
+            aria-invalid={
+              status?.type === 'error' || !isTimeInputValid ? 'true' : undefined
+            }
             {...stylex.props(
               styles.input,
               isEffectivelyDisabled && styles.inputDisabled,
               !isTimeInputValid && styles.inputInvalid,
             )}
           />
+          {/*
+            Live region announcing invalid typed time input to assistive
+            technology (WCAG 3.3.1).
+          */}
+          <VisuallyHidden as="div" role="alert" aria-live="assertive">
+            {!isTimeInputValid ? 'Invalid time' : ''}
+          </VisuallyHidden>
         </div>
       </div>
 
@@ -920,6 +1025,9 @@ export function DateTimeInput({
         />,
         {placement: 'below', alignment: 'start'},
       )}
+
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/Dialog/Dialog.doc.mjs

@@ -40,13 +40,13 @@ export const docs = {
     {
       name: 'isOpen',
       type: 'boolean',
-      description: 'Whether the dialog is open (required).',
+      description: 'Whether the dialog is open.',
       required: true,
     },
     {
       name: 'onOpenChange',
       type: '(isOpen: boolean) => unknown',
-      description: 'Callback when dialog visibility changes (required).',
+      description: 'Callback when dialog visibility changes.',
       required: true,
     },
     {

package/src/Dialog/Dialog.tsx

@@ -20,6 +20,7 @@ import {useEffect, useMemo, useRef, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {useScrollLock} from '../hooks/useScrollLock';
+import {hasActiveFocusTrapEscape, isImeKeyEvent} from '../hooks/useFocusTrap';
 import {
   colorVars,
   radiusVars,
@@ -422,6 +423,12 @@ export function Dialog({
 
     const handleKeyDown = (event: KeyboardEvent) => {
       if (event.key === 'Escape') {
+        // Ignore IME composition-cancel, and defer to any popover/menu layered
+        // on top of this dialog so a single Escape closes only the top-most
+        // layer (the popover's own focus trap handles it and stops propagation).
+        if (isImeKeyEvent(event) || hasActiveFocusTrapEscape()) {
+          return;
+        }
         event.preventDefault();
         if (allowEscape) {
           onOpenChange(false);
@@ -447,6 +454,11 @@ export function Dialog({
   // Handle native cancel event (browser Escape handling)
   const handleCancel = (event: React.SyntheticEvent<HTMLDialogElement>) => {
     event.preventDefault();
+    // Defer to a popover/menu layered on top of this dialog; it will dismiss
+    // itself on the same Escape press.
+    if (hasActiveFocusTrapEscape()) {
+      return;
+    }
     if (allowEscape) {
       onOpenChange(false);
     }