@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Dialog/Dialog.doc.mjs

@@ -7,7 +7,19 @@ export const docs = {
   displayName: 'Dialog',
   group: 'Dialog',
   category: 'Overlay',
-  keywords: ["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap","imperative"],
+  keywords: [
+    'dialog',
+    'modal',
+    'popup',
+    'overlay',
+    'lightbox',
+    'alert',
+    'confirm',
+    'prompt',
+    'backdrop',
+    'focus trap',
+    'imperative',
+  ],
   // Intentionally a contained isInline preview, not playground.overlay: the
   // component stays visible on load and knobs stay live, whereas a real
   // showModal() overlay makes the page inert — see ComponentPlaygroundConfig.overlay
@@ -19,9 +31,16 @@ export const docs = {
       onOpenChange: undefined,
       width: 400,
       children: {
-        __element: 'VStack', props: {gap: 2}, children: [
+        __element: 'VStack',
+        props: {gap: 2},
+        children: [
           {__element: 'Heading', props: {level: 3}, children: 'Dialog Title'},
-          {__element: 'Text', props: {type: 'body'}, children: 'Are you sure you want to proceed? This action can be undone later from settings.'},
+          {
+            __element: 'Text',
+            props: {type: 'body'},
+            children:
+              'Are you sure you want to proceed? This action can be undone later from settings.',
+          },
         ],
       },
     },
@@ -37,7 +56,12 @@ export const docs = {
       {className: 'astryx-dialog-header-close-icon'},
     ],
     vars: [
-      {name: '--_dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)', private: true},
+      {
+        name: '--_dialog-radius',
+        description: 'Border radius of the dialog',
+        default: 'var(--radius-container)',
+        private: true,
+      },
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_dialog-radius']},
@@ -45,7 +69,7 @@ export const docs = {
     ],
   },
   description:
-    'Modal dialog using the native <dialog> element. Modal and inline content starts with theme body text defaults. Ancestor surface/group membership ends as a whole, including group-owned state. Explicit props and unrelated contexts remain unchanged. Place intentional groups and complete required providers inside the dialog.',
+    'Modal dialog using the native <dialog> element. Modal and inline content starts with theme body text defaults. Ancestor surface/group membership ends as a whole, including group-owned state. Explicit props and unrelated contexts remain unchanged. Place intentional groups and complete required providers inside the dialog. With reduced motion the dialog never slides or scales in: on a touch screen it fades in, in 200 ms or less, and with a mouse it appears at once.',
   props: [
     {
       name: 'isOpen',
@@ -68,13 +92,15 @@ export const docs = {
     {
       name: 'width',
       type: 'number | string',
-      description: 'Preferred width of the dialog in pixels or any CSS value. Standard dialogs clamp to their container and the dynamic viewport with spacing-token gutters so narrow viewports keep content on screen.',
+      description:
+        'Preferred width of the dialog in pixels or any CSS value. Standard dialogs clamp to their container and the dynamic viewport with spacing-token gutters so narrow viewports keep content on screen.',
       default: '400',
     },
     {
       name: 'maxHeight',
       type: 'number | string',
-      description: 'Maximum height of the dialog. Defaults to a dynamic viewport value so browser UI changes are reflected where supported.',
+      description:
+        'Maximum height of the dialog. Defaults to a dynamic viewport value so browser UI changes are reflected where supported.',
       default: "'75dvh'",
     },
     {
@@ -87,47 +113,97 @@ export const docs = {
     {
       name: 'variant',
       type: "'standard' | 'fullscreen'",
-      description: 'Dialog variant: fullscreen expands to fill the entire viewport.',
+      description:
+        'Dialog variant: fullscreen expands to fill the entire viewport.',
       default: "'standard'",
     },
     {
       name: 'purpose',
       type: "'required' | 'form' | 'info'",
-      description: 'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',
+      description:
+        'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',
       default: "'info'",
     },
     {
       name: 'padding',
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-      description: 'Internal padding of the dialog using the spacing scale step.',
+      description:
+        'Internal padding of the dialog using the spacing scale step.',
     },
     {
       name: 'isInline',
       type: 'boolean',
-      description: 'Renders dialog content inline without the <dialog> element, backdrop, or modal behavior. For documentation previews and showcases only.',
+      description:
+        'Renders dialog content inline without the <dialog> element, backdrop, or modal behavior. For documentation previews and showcases only.',
       default: 'false',
     },
   ],
-  components: [
-    {name: 'DialogHeader'},
-    {name: 'useImperativeDialog'},
-  ],
+  components: [{name: 'DialogHeader'}, {name: 'useImperativeDialog'}],
   usage: {
-    description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.\n\nFor cases where you want to show a dialog without managing open state, use the `useImperativeDialog` hook: call `dialog.show(content)` and render `dialog.element` in your tree.',
+    description:
+      'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.\n\nFor cases where you want to show a dialog without managing open state, use the `useImperativeDialog` hook: call `dialog.show(content)` and render `dialog.element` in your tree.',
     bestPractices: [
-      { guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.' },
-      { guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },
-      { guidance: true, description: 'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.' },
-      { guidance: true, description: 'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.' },
-      { guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },
-      { guidance: false, description: 'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.' },
-      { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },
+      {
+        guidance: true,
+        description:
+          'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.',
+      },
+      {
+        guidance: true,
+        description:
+          'Include a clear title in the header so users immediately understand what the dialog is asking.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a dialog for simple messages that could be shown inline or as a toast notification.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.',
+      },
+      {
+        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 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.'},
+      {
+        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.',
+      },
     ],
   },
 };
@@ -135,39 +211,117 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
-    description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.',
+    description:
+      'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.',
     bestPractices: [
-      { guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.' },
-      { guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },
-      { guidance: true, description: 'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.' },
-      { guidance: true, description: 'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.' },
-      { guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },
-      { guidance: false, description: 'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.' },
-      { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },
+      {
+        guidance: true,
+        description:
+          'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.',
+      },
+      {
+        guidance: true,
+        description:
+          'Include a clear title in the header so users immediately understand what the dialog is asking.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a dialog for simple messages that could be shown inline or as a toast notification.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.',
+      },
+      {
+        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 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.'},
+      {
+        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.',
+      },
     ],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'modal overlay that blocks page interaction until the user responds',
+  description:
+    'modal overlay that blocks page interaction until the user responds',
   usage: {
     description:
       'Dialog displays a modal overlay that blocks page interaction. Use for delete confirmations, edit forms, terms acceptance. Modal and inline content uses theme body defaults and exits ancestor surface/group membership as a whole; explicit props and unrelated contexts remain unchanged. Provide intentional groups and complete required providers inside the dialog.',
     bestPractices: [
-      { guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when user must respond.' },
-      { guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },
-      { guidance: true, description: 'Use purpose="form" for dialogs with inputs so user can\'t accidentally lose data by clicking the backdrop.' },
-      { guidance: true, description: 'Keep dialogs focused on a single task; if content grows beyond what fits, consider a full page instead.' },
-      { guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },
-      { guidance: false, description: 'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.' },
-      { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it\'s meant for complex content like editors or long forms.' },
+      {
+        guidance: true,
+        description:
+          'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when user must respond.',
+      },
+      {
+        guidance: true,
+        description:
+          'Include a clear title in the header so users immediately understand what the dialog is asking.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use purpose="form" for dialogs with inputs so user can\'t accidentally lose data by clicking the backdrop.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep dialogs focused on a single task; if content grows beyond what fits, consider a full page instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a dialog for simple messages that could be shown inline or as a toast notification.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use the fullscreen variant for simple confirmations; it's meant for complex content like editors or long forms.",
+      },
     ],
   },
 };

package/src/Dialog/Dialog.spec.md

@@ -89,6 +89,7 @@ current family and architecture owners.
 | FR4 | Closing a native Dialog MUST return focus to the still-connected external element that invoked the modal when that element can receive focus. Descendant mount focus MUST NOT replace that return owner.                                                                                                                                                                                                  | shipped trigger-return intent and regression history         | settled            |
 | FR5 | Inline rendering MUST NOT open a modal, apply modal initial focus, trap focus, or return focus as if a modal had closed.                                                                                                                                                                                                                                                                                  | documented `isInline` preview behavior                       | settled            |
 | FR6 | Initial-focus selection MUST follow the rendered eligible descendants, not a private component type or source-only assumption.                                                                                                                                                                                                                                                                            | composable descendant contract                               | settled            |
+| FR7 | A native modal Dialog MUST be a focus region through Core's shared focus-region module: Tab from its last tabbable control moves focus to its first, and Shift+Tab from its first moves focus to its last, so focus never leaves the modal for the browser's own interface. When a Dialog opens from a Dialog, the innermost one holding focus answers Tab.                                               | owner decision DEC-2                                         | settled            |
 
 ### Allowed variation
 
@@ -110,6 +111,7 @@ current family and architecture owners.
 | native modal with explicit descendant request | requested eligible descendant receives focus                | descendant type and location               |
 | native modal without request                  | focus remains within valid native modal behavior            | browser-selected eligible descendant       |
 | modal close                                   | connected invoking element regains focus                    | no restoration when invoker is unavailable |
+| Tab or Shift+Tab at the modal's edge          | focus wraps to the other end inside the modal               | which controls are tabbable                |
 | inline preview                                | surrounding page focus remains unchanged                    | inline content and layout                  |
 
 ## Accessibility contract
@@ -147,6 +149,7 @@ component design and theming owners.
 | FR4, AR2     | shared modal-dialog browser binding plus the local unavailable-invoker close test                                        | external trigger, descendant mount focus, removed trigger | the shared contract records an exact current failure when descendant focus replaces the return owner; the local test keeps close safe after invoker removal | audit:Dialog/behavior      |
 | FR5          | inline Dialog tests                                                                                                      | DialogHeader and focusable children                       | inline preview steals focus or invokes native modal methods                                                                                                 | audit:Dialog/behavior      |
 | FR6, AR3     | shared modal-dialog binding plus the local composed-action focus fixture                                                 | DialogHeader heading, TextInput, action button            | focus depends on a private React child type or strips semantics from the target                                                                             | audit:Dialog/public-api    |
+| FR7          | `Dialog.test.tsx`, `AlertDialog.test.tsx` and `CommandPalette.test.tsx` focus-region suites                              | last and first tabbable control, Dialog in Dialog, inline | Tab from the last control leaves the modal, or an outer Dialog answers an inner one's Tab                                                                   | audit:Dialog/accessibility |
 
 ## Decision log
 
@@ -159,12 +162,25 @@ Dialog waits until native modal presentation before applying the selected reques
 Descendant components own their supported focus intent; the DOM marker used today is
 implementation evidence, not a permanent or newly admitted public API.
 
+### DEC-2 — Every modal presentation is a focus region through one module
+
+**Reference:** `component:Dialog/DEC-2`
+**Decider:** `cixzhang`, `2026-10-28`
+
+A modal surface contains Tab the way the APG modal dialog pattern describes:
+Tab and Shift+Tab move through the modal's controls and wrap at either end.
+Core's shared focus-region module provides that containment: the Tab
+containment `useFocusTrap` applies for Drawer and Popover. Each modal
+presentation applies the same module instead of
+leaving Tab to the browser: Dialog, and AlertDialog and CommandPalette through
+it, a modal BottomSheet, Lightbox, and a modal Drawer. A fault in the wrapping
+is fixed in that module, not worked around in a component.
+
+Rejected: leaving Tab to native `showModal()`, which sends focus to the browser's own interface from inside a modal.
+
 ## Open questions
 
-- **Dialog focus containment.** Should native modal Dialog adopt APG forward and
-  reverse Tab wrapping as a required public behavior? Current authority owns focus
-  entry and return but does not settle this containment mechanic, so the shared
-  contract does not gate it.
+None. DEC-2 settles focus containment.
 
 ## Content boundary
 

package/src/Dialog/Dialog.tsx

@@ -16,6 +16,10 @@
  * while preserving explicit prop/theme padding overrides, and fade in without
  * the centered-dialog translate/scale motion.
  *
+ * Under reduced motion the entrance never travels or scales
+ * (docs/design/reduced-motion.md): on a touch screen the dialog fades in
+ * where it lands, in 200 ms or less; with a mouse it appears at once.
+ *
  * Initial focus and the focus returned on close follow the last input
  * (docs/architecture/interaction-modality.md INV1): the shared focus indicator
  * is hidden after a pointer press and shown after a key press.
@@ -74,6 +78,7 @@ import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {focusForLastInput} from '../utils/focusReturn';
+import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 /**
@@ -186,8 +191,19 @@ const styles = stylex.create({
     height: 'fit-content',
     overscrollBehavior: 'contain',
     opacity: 0,
-    animationDuration: durationVars['--duration-medium-max'],
-    animationTimingFunction: easeVars['--ease-standard'],
+    // Under reduced motion on a touch screen the entrance is the shared
+    // reduced-motion cross-fade, 200 ms on easeInOut whatever the theme's
+    // duration (design:reduced-motion DR2, DR4). Moves to
+    // reducedMotionFadeConsts once that is on main.
+    animationDuration: {
+      default: durationVars['--duration-medium-max'],
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': '200ms',
+    },
+    animationTimingFunction: {
+      default: easeVars['--ease-standard'],
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+        'cubic-bezier(0.42, 0, 0.58, 1)',
+    },
     animationFillMode: 'backwards' as const,
   },
   // Applied via isOpen prop — avoids :where([open]) attribute selectors
@@ -196,12 +212,15 @@ const styles = stylex.create({
   open: {
     display: 'flex',
     opacity: 1,
-    // Disable the entry keyframe animation under
-    // `prefers-reduced-motion: reduce` so the dialog appears instantly
-    // instead of translating/scaling in (same pattern as layerAnimations).
+    // Under `prefers-reduced-motion: reduce` the dialog never travels or
+    // scales in (design:reduced-motion DR1): on a touch screen it fades in
+    // where it lands (DR2), and with a mouse it appears at once (DR3).
     animationName: {
       default: enterDirectional,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+        enterFullscreen,
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
     },
   },
   // Backdrop using ::backdrop pseudo-element
@@ -223,7 +242,10 @@ const styles = stylex.create({
   fullscreenOpen: {
     animationName: {
       default: enterFullscreen,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+        enterFullscreen,
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
     },
   },
   fullscreenSafeArea: {
@@ -602,6 +624,9 @@ export function Dialog({
     onDismiss: () => {
       onOpenChange(false);
     },
+    // The dialog's document is this layer's: rendered into an iframe or a
+    // Picture-in-Picture window, it ranks with the layers opened inside it.
+    getContainer: () => dialogRef.current,
   });
 
   // Dev-time guardrail: an open modal should always have an accessible name.
@@ -796,9 +821,11 @@ export function Dialog({
       // imperatively in `attachDialog`; a consumer-provided aria-labelledby
       // flows through {...safeProps} above and wins.
       {...(purpose === 'required' ? {role: 'alertdialog'} : undefined)}>
-      <LayerDepthProvider>
-        <LayerContentBoundary>{innerContent}</LayerContentBoundary>
-      </LayerDepthProvider>
+      <ModalAnnounceProvider dialogRef={dialogRef} isOpen={isOpen}>
+        <LayerDepthProvider>
+          <LayerContentBoundary>{innerContent}</LayerContentBoundary>
+        </LayerDepthProvider>
+      </ModalAnnounceProvider>
     </dialog>
   );
 }

package/src/Dialog/__tests__/Dialog.a11y.browser.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file Dialog.a11y.browser.spec.ts

package/src/Dialog/__tests__/Dialog.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file Dialog.a11y.chromium.spec.ts