@workday/canvas-kit-docs 14.3.9 → 14.3.11

package/dist/es6/lib/stackblitzFiles/packageJSONFile.js

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "14.3.9",
-    "@workday/canvas-kit-preview-react": "14.3.9",
-    "@workday/canvas-kit-react": "14.3.9",
-    "@workday/canvas-kit-react-fonts": "^14.3.9",
-    "@workday/canvas-kit-styling": "14.3.9",
+    "@workday/canvas-kit-labs-react": "14.3.11",
+    "@workday/canvas-kit-preview-react": "14.3.11",
+    "@workday/canvas-kit-react": "14.3.11",
+    "@workday/canvas-kit-react-fonts": "^14.3.11",
+    "@workday/canvas-kit-styling": "14.3.11",
     "@workday/canvas-system-icons-web": "3.0.36",
     "@workday/canvas-tokens-web": "3.1.2"
   },

package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "14.3.9",
-    "@workday/canvas-kit-preview-react": "14.3.9",
-    "@workday/canvas-kit-react": "14.3.9",
-    "@workday/canvas-kit-react-fonts": "^14.3.9",
-    "@workday/canvas-kit-styling": "14.3.9",
+    "@workday/canvas-kit-labs-react": "14.3.11",
+    "@workday/canvas-kit-preview-react": "14.3.11",
+    "@workday/canvas-kit-react": "14.3.11",
+    "@workday/canvas-kit-react-fonts": "^14.3.11",
+    "@workday/canvas-kit-styling": "14.3.11",
     "@workday/canvas-system-icons-web": "3.0.36",
     "@workday/canvas-tokens-web": "3.1.2"
   },

package/dist/es6/mdx/accessibility/examples/Popups/InlinePopupNoPortal.d.ts

@@ -0,0 +1,2 @@
+export declare const InlinePopupNoPortal: () => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=InlinePopupNoPortal.d.ts.map

package/dist/es6/mdx/accessibility/examples/Popups/InlinePopupNoPortal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InlinePopupNoPortal.d.ts","sourceRoot":"","sources":["../../../../../../mdx/accessibility/examples/Popups/InlinePopupNoPortal.tsx"],"names":[],"mappings":"AA0GA,eAAO,MAAM,mBAAmB,+CAsB/B,CAAC"}

package/dist/es6/mdx/accessibility/examples/Popups/InlinePopupNoPortal.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { DeleteButton } from '@workday/canvas-kit-react/button';
+import { Popup, usePopupModel, useCloseOnEscape, useCloseOnOutsideClick, useInitialFocus, useReturnFocus, } from '@workday/canvas-kit-react/popup';
+import { Box, Flex } from '@workday/canvas-kit-react/layout';
+import { Heading } from '@workday/canvas-kit-react/text';
+import { createStyles, px2rem } from '@workday/canvas-kit-styling';
+import { system } from '@workday/canvas-tokens-web';
+import { useUniqueId } from '@workday/canvas-kit-react/common';
+const headingStyles = createStyles({
+    marginTop: system.space.zero,
+});
+const cardStyles = createStyles({
+    width: px2rem(320),
+});
+const flexStyles = createStyles({
+    gap: system.space.x4,
+    padding: system.space.x2,
+});
+const bodyStyles = createStyles({
+    marginY: system.space.zero,
+});
+const clipContainerStyles = createStyles({
+    padding: system.space.x4,
+    border: `${px2rem(2)} dashed ${system.color.border.info.default}`,
+    height: px2rem(200),
+    position: 'relative',
+    overflow: 'clip',
+});
+const visibleContainerStyles = createStyles({
+    padding: system.space.x4,
+    border: `${px2rem(2)} dashed ${system.color.border.info.default}`,
+    height: px2rem(200),
+    position: 'relative',
+    overflow: 'visible',
+});
+const scrollContainerStyles = createStyles({
+    padding: system.space.x4,
+    border: `${px2rem(2)} dashed ${system.color.border.info.default}`,
+    height: px2rem(200),
+    position: 'relative',
+    overflow: 'scroll',
+});
+const comparisonLayoutStyles = createStyles({
+    display: 'grid',
+    gridTemplateColumns: 'repeat(3, minmax(0, 1fr))',
+    gap: system.space.x6,
+    marginBottom: system.space.x4,
+});
+function SingleInlinePopup({ overflowLabel, containerStyles, }) {
+    const messageId = useUniqueId();
+    const initialFocusRef = useRef(null);
+    const model = usePopupModel({ initialFocusRef });
+    useCloseOnOutsideClick(model);
+    useCloseOnEscape(model);
+    useInitialFocus(model);
+    useReturnFocus(model);
+    return (_jsxs(Box, { cs: containerStyles, children: [_jsx(Heading, { size: "small", as: "h4", cs: headingStyles, children: overflowLabel }), _jsxs(Popup, { model: model, children: [_jsx(Popup.Target, { as: DeleteButton, children: "Delete Item" }), _jsx(Popup.Popper, { placement: "top", portal: false, children: _jsxs(Popup.Card, { cs: cardStyles, "aria-describedby": messageId, children: [_jsx(Popup.Heading, { children: "Delete Item" }), _jsx(Popup.Body, { children: _jsx(Box, { as: "p", id: messageId, cs: bodyStyles, children: "Are you sure you'd like to delete the item titled 'My Item'?" }) }), _jsxs(Flex, { cs: flexStyles, children: [_jsx(Popup.CloseButton, { ref: initialFocusRef, children: "Cancel" }), _jsx(Popup.CloseButton, { as: DeleteButton, children: "Delete" })] })] }) })] })] }));
+}
+export const InlinePopupNoPortal = () => {
+    return (_jsxs(_Fragment, { children: [_jsxs(Flex, { cs: comparisonLayoutStyles, children: [_jsx(SingleInlinePopup, { overflowLabel: "overflow: visible", containerStyles: visibleContainerStyles }), _jsx(SingleInlinePopup, { overflowLabel: "overflow: clip", containerStyles: clipContainerStyles }), _jsx(SingleInlinePopup, { overflowLabel: "overflow: scroll", containerStyles: scrollContainerStyles })] }), _jsxs("p", { children: ["With ", _jsx("code", { children: "overflow: visible" }), ", the popup can extend past the dashed border. With", ' ', _jsx("code", { children: "overflow: scroll" }), " (or ", _jsx("code", { children: "hidden" }), " / ", _jsx("code", { children: "clip" }), "), the popup is constrained and any overflow is clipped. The container uses ", _jsx("code", { children: "position: relative" }), ' ', "so it establishes a containing block for the positioned popup."] })] }));
+};

package/dist/es6/mdx/accessibility/examples/Popups/InlinePortalPopup.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Portals popup content into a sentinel div after the trigger (via PopupStack.pushStackContext)
+ * so DOM reading order matches page context. Uses a two-phase open so pushStackContext runs
+ * before Popper mounts and registers with the stack.
+ */
+export declare const InlinePortalPopup: () => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=InlinePortalPopup.d.ts.map

package/dist/es6/mdx/accessibility/examples/Popups/InlinePortalPopup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InlinePortalPopup.d.ts","sourceRoot":"","sources":["../../../../../../mdx/accessibility/examples/Popups/InlinePortalPopup.tsx"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,+CAkE7B,CAAC"}

package/dist/es6/mdx/accessibility/examples/Popups/InlinePortalPopup.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { DeleteButton } from '@workday/canvas-kit-react/button';
+import { Popup, usePopupModel, useCloseOnEscape, useCloseOnOutsideClick, useReturnFocus, } from '@workday/canvas-kit-react/popup';
+import { PopupStack } from '@workday/canvas-kit-popup-stack';
+import { Box, Flex } from '@workday/canvas-kit-react/layout';
+import { createStyles, px2rem } from '@workday/canvas-kit-styling';
+import { system } from '@workday/canvas-tokens-web';
+import { changeFocus, useUniqueId } from '@workday/canvas-kit-react/common';
+const cardStyles = createStyles({
+    width: px2rem(320),
+});
+const flexStyles = createStyles({
+    gap: system.space.x4,
+    padding: system.space.x2,
+});
+const layoutStyles = createStyles({
+    gap: system.space.x4,
+    alignItems: 'flex-start',
+    flexDirection: 'column',
+});
+const bodyStyles = createStyles({
+    marginY: system.space.zero,
+});
+/**
+ * Portals popup content into a sentinel div after the trigger (via PopupStack.pushStackContext)
+ * so DOM reading order matches page context. Uses a two-phase open so pushStackContext runs
+ * before Popper mounts and registers with the stack.
+ */
+export const InlinePortalPopup = () => {
+    const messageId = useUniqueId();
+    const sentinelRef = React.useRef(null);
+    const initialFocusRef = React.useRef(null);
+    const model = usePopupModel({ initialFocusRef });
+    const visible = model.state.visibility !== 'hidden';
+    const [portalReady, setPortalReady] = React.useState(false);
+    useCloseOnOutsideClick(model);
+    useCloseOnEscape(model);
+    useReturnFocus(model);
+    // Defer initial focus until Popper content is mounted. useInitialFocus runs when visible while
+    // stackRef can still point at an empty sentinel (second open) and throws.
+    React.useEffect(() => {
+        if (!visible || !portalReady)
+            return;
+        const el = initialFocusRef.current;
+        if (!el)
+            return;
+        requestAnimationFrame(() => {
+            changeFocus(el);
+        });
+    }, [visible, portalReady]);
+    React.useLayoutEffect(() => {
+        if (visible && sentinelRef.current && !portalReady) {
+            PopupStack.pushStackContext(sentinelRef.current);
+            setPortalReady(true);
+        }
+        if (!visible && portalReady) {
+            PopupStack.popStackContext(sentinelRef.current);
+            setPortalReady(false);
+        }
+    }, [visible, portalReady]);
+    return (_jsxs(Flex, { cs: layoutStyles, children: [_jsx(Flex, { children: _jsxs(Popup, { model: model, children: [_jsx(Popup.Target, { as: DeleteButton, children: "Delete Item" }), _jsx("div", { ref: sentinelRef }), visible && portalReady ? (_jsx(Popup.Popper, { placement: "top", children: _jsxs(Popup.Card, { cs: cardStyles, "aria-describedby": messageId, children: [_jsx(Popup.Heading, { children: "Delete Item" }), _jsx(Popup.Body, { children: _jsx(Box, { as: "p", id: messageId, cs: bodyStyles, children: "Are you sure you'd like to delete the item titled 'My Item'?" }) }), _jsxs(Flex, { cs: flexStyles, children: [_jsx(Popup.CloseButton, { ref: initialFocusRef, children: "Cancel" }), _jsx(Popup.CloseButton, { as: DeleteButton, children: "Delete" })] })] }) })) : null] }) }), _jsx("p", { children: "This content should come after the popup in the reading order. When someone uses a screen reader or moves through the page with tabbing, they will read or reach this content only after the popup content is shown. This helps keep the page easy to follow and makes sure that the popup is announced before any information that comes next." })] }));
+};

package/dist/es6/mdx/accessibility/examples/Popups/PopupAriaOwns.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Default portal to body; sibling div with aria-owns references the portaled stack container
+ * so screen readers that support aria-owns can present content in logical order.
+ * useInitialFocus announces the popup in screen readers; useFocusRedirect manages Tab in/out.
+ */
+export declare const PopupAriaOwns: () => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=PopupAriaOwns.d.ts.map

package/dist/es6/mdx/accessibility/examples/Popups/PopupAriaOwns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PopupAriaOwns.d.ts","sourceRoot":"","sources":["../../../../../../mdx/accessibility/examples/Popups/PopupAriaOwns.tsx"],"names":[],"mappings":"AAmCA;;;;GAIG;AACH,eAAO,MAAM,aAAa,+CAkDzB,CAAC"}

package/dist/es6/mdx/accessibility/examples/Popups/PopupAriaOwns.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { DeleteButton } from '@workday/canvas-kit-react/button';
+import { Popup, useCloseOnEscape, useCloseOnOutsideClick, useInitialFocus, useReturnFocus, useFocusRedirect, usePopupModel, } from '@workday/canvas-kit-react/popup';
+import { Box, Flex } from '@workday/canvas-kit-react/layout';
+import { createStyles, px2rem } from '@workday/canvas-kit-styling';
+import { system } from '@workday/canvas-tokens-web';
+import { useUniqueId } from '@workday/canvas-kit-react/common';
+const cardStyles = createStyles({
+    width: px2rem(400),
+});
+const bodyStyles = createStyles({
+    marginY: system.space.zero,
+});
+const flexStyles = createStyles({
+    gap: system.space.x4,
+    padding: system.space.x2,
+});
+const layoutStyles = createStyles({
+    gap: system.space.x4,
+    alignItems: 'flex-start',
+    flexDirection: 'column',
+});
+/**
+ * Default portal to body; sibling div with aria-owns references the portaled stack container
+ * so screen readers that support aria-owns can present content in logical order.
+ * useInitialFocus announces the popup in screen readers; useFocusRedirect manages Tab in/out.
+ */
+export const PopupAriaOwns = () => {
+    const initialFocusRef = React.useRef(null);
+    const model = usePopupModel({ initialFocusRef });
+    useCloseOnOutsideClick(model);
+    useCloseOnEscape(model);
+    useInitialFocus(model);
+    useReturnFocus(model);
+    useFocusRedirect(model);
+    const messageId = useUniqueId();
+    const popupId = useUniqueId();
+    const visible = model.state.visibility !== 'hidden';
+    React.useLayoutEffect(() => {
+        if (visible && model.state.stackRef.current) {
+            model.state.stackRef.current.setAttribute('id', popupId);
+        }
+    }, [model.state.stackRef, visible, popupId]);
+    return (_jsxs(Flex, { cs: layoutStyles, children: [_jsx(Flex, { children: _jsxs(Popup, { model: model, children: [_jsx(Popup.Target, { as: DeleteButton, children: "Delete Item" }), _jsx("div", { "aria-owns": popupId, style: { position: 'absolute' } }), _jsx(Popup.Popper, { children: _jsxs(Popup.Card, { cs: cardStyles, "aria-describedby": messageId, children: [_jsx(Popup.CloseIcon, { "aria-label": "Close" }), _jsx(Popup.Heading, { children: "Delete Item" }), _jsx(Popup.Body, { children: _jsx(Box, { as: "p", id: messageId, cs: bodyStyles, children: "Are you sure you'd like to delete the item titled 'My Item'?" }) }), _jsxs(Flex, { cs: flexStyles, children: [_jsx(Popup.CloseButton, { as: DeleteButton, children: "Delete" }), _jsx(Popup.CloseButton, { ref: initialFocusRef, children: "Cancel" })] })] }) })] }) }), _jsx("p", { children: "This content should come after the popup in the reading order. When someone uses a screen reader or moves through the page with tabbing, they will read or reach this content only after the popup content is shown. This helps keep the page easy to follow and makes sure that the popup is announced before any information that comes next." })] }));
+};

package/dist/mdx/accessibility/InlinePortals.mdx

@@ -0,0 +1,20 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+import InlinePortalPopup from './examples/Popups/InlinePortalPopup';
+
+
+## Inline portal with `PopupStack`
+
+This example builds on the patterns described in
+[Guides > Accessibility > Inline Popups](?path=/docs/guides-accessibility-inline-popups--docs).
+It does **not** use a focus trap. For modal dialogs with overlay and focus trap, use the
+[**Modal**](?path=/docs/components-popups-modal--docs) component instead.
+
+Keep using a portal (default stacking and positioning) but mount the portal **into a sentinel
+element** placed right after the trigger. Call `PopupStack.pushStackContext(sentinelElement)` while
+the popup is open so new stack items append to that sentinel instead of `body`. **Tradeoff:** You
+still get **ancestor overflow** clipping—the portaled content is a descendant of the sentinel, not
+`document.body`. You must also handle **`PopupStack` context** (push/pop on open/close), which is
+more moving parts than `portal={false}` alone. Use **`useInitialFocus`** so opening the popup is
+announced when focus enters the dialog.
+
+<ExampleCodeBlock code={InlinePortalPopup} />

package/dist/mdx/accessibility/Popups.mdx

@@ -0,0 +1,71 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+import InlinePopupNoPortal from './examples/Popups/InlinePopupNoPortal';
+import PopupAriaOwns from './examples/Popups/PopupAriaOwns';
+
+
+# How screen readers read Popups
+
+A **screen reader** is software that reads the page out loud and lets people navigate with the
+keyboard (and sometimes a braille display). It does not “see” the layout the way sighted users do.
+It walks through the page in a sequence that usually matches the **order of elements in the
+DOM**—roughly, the order nodes appear in the HTML tree.
+
+That matters for popups: if the popup’s markup is **far away** from the control that opened it in
+the DOM, the screen reader may read a lot of other page content **before** it reaches the popup. The
+user might not realize the popup is there, or they might hear unrelated content mixed in with the
+popup experience.
+
+**Moving keyboard focus** into the popup when it opens helps people continue interacting, but it
+does **not** change that underlying reading sequence. So focus management and reading order are
+related problems; you often need to address both.
+
+**None of these examples use focus traps.** For modal dialogs with an overlay and focus trap, use
+the [**Modal**](?path=/docs/components-popups-modal--docs) component instead.
+
+**`useInitialFocus`:** When the popup opens, each example moves focus into the popup (often to a
+Close control or another safe first stop). That matters because **many screen readers only announce
+new content when focus moves**. If focus stays on the trigger, the user may get **no cue** that a
+popup appeared. When choosing not to use `useInitialFocus`, consider the following:
+
+- Use `aria-expanded={true | false}` on `Popup.Target` so assistive tech can report whether the
+  popup is open or closed.
+- Use `aria-haspopup="dialog"` on `Popup.Target` as a hint that the control opens a dialog.
+  **Caveat:** some older screen readers do not understand the `"dialog"` value. They may treat it
+  like a generic popup and **announce “menu”** even when you built a dialog. For that reason, we
+  **strongly recommend** testing with your supported browsers and screen reader combinations during
+  development.
+
+## 1. Inline popup with `portal={false}`
+
+Set `portal={false}` on `Popup.Popper` so the popup renders in the DOM next to its target. Reading
+order follows document order. Use **`useInitialFocus`**, **`useReturnFocus`**, and the usual close
+hooks. **Tradeoff:** the popup is constrained by ancestor `overflow` and positioning context.
+
+<ExampleCodeBlock code={InlinePopupNoPortal} />
+
+For the same reading-order goal using a **portaled** popup mounted into a sentinel next to the
+trigger (with `PopupStack.pushStackContext`), see
+[**Testing > Inline Portals**](?path=/docs/guides-accessibility-testing-inline-portals--docs).
+
+## 2. Reading order with `aria-owns`
+
+You can keep the default portal (content at the bottom of `body`) and still try to **re-parent** the
+popup in the **accessibility tree**: add a sibling element after `Popup.Target` and set
+**`aria-owns`** to the id of the portaled `Popup.Card`. Some assistive technologies will then treat
+that card as “owned” by the trigger for browsing and announcements.
+
+**Tradeoffs:**
+
+- **Support for `aria-owns` varies.** Do not assume every combination of browser and screen reader
+  will honor it the same way.
+- **Tab order still follows the real DOM.** `aria-owns` does not move focus targets. You may still
+  need helpers like **`useFocusRedirect`** so keyboard users can reach the popup predictably.
+- Combine with **`useInitialFocus`** so opening the popup still moves focus and gives a clear
+  announcement where supported.
+
+The Canvas Kit [**Dialog**](?path=/docs/components-popups-dialog--docs) builds this pattern in.
+
+Another `aria-owns` example:
+[Advanced Tables > Table With Filterable Column Headers](?path=/docs/guides-accessibility-examples-advanced-tables--docs#filterable-column-headers).
+
+<ExampleCodeBlock code={PopupAriaOwns} />

package/dist/mdx/react/dialog/Dialog.mdx

@@ -17,34 +17,65 @@ yarn add @workday/canvas-kit-react
 
 ### Basic Example
 
-[Modal](/components/popups/modal/) and Dialog are very similar: most of the examples from Modal can
-be adapted to Dialog by changing `Modal` to `Dialog` and replacing `Modal.Overlay` with
-`Dialog.Popper`.
-
-Unlike Modal, Dialog does _not_ render the rest of the page inert while it is active. Dialog should
-be used in situations where the task does not require immediate attention such as in the example
-below.
+Unlike Modal, Dialog **does not** render the rest of the page inert while it is active. Dialog
+should be used in situations where the task does not require immediate attention.
 
 <ExampleCodeBlock code={Basic} />
 
 ### Focus Redirect
 
-Since Modal requires immediate attention, it will trap the keyboard focus inside the Modal until an
-action is taken. Dialog manages focus differently, however, since it does not require immediate
-attention.
-
-The following example shows how Dialog manages focus in and out of the component.
+Dialog **does not** trap keyboard focus like the Modal component does. Instead, it allows focus to
+move freely in and out of the dialog, supporting more flexible navigation. The following example
+shows how Dialog manages focus in and out of the component.
 
 <ExampleCodeBlock code={Focus} />
 
-Instead of trapping focus within the Dialog, it is effectively treated as an inline element next to
-its triggering `Dialog.Target` button. Tabbing out of the Dialog will close the popup and move focus
-to the next button.
-
-Dialog also adds an `aria-owns` to a `<div>` element which is rendered as a sibling of the
-`Dialog.Target` button. The `aria-owns` references the `Dialog.Card` and allows screen readers which
-[support aria-owns](/components/popups/popup/#focus-redirect) to navigate the Dialog as if it
-weren't portalled to the bottom of the document body.
+> **Accessibility Note**: Focus redirect **will not** have any effect on the reading order of a
+> screen reader.
+
+## Accessibility
+
+`Dialog` composes the popup stack with `useInitialFocus`, `useReturnFocus`, `useCloseOnEscape`,
+`useCloseOnOutsideClick`, and `useFocusRedirect`. The card container includes an ARIA
+**`role="dialog"`** that is **non-modal**: the rest of the page stays available. The card also
+includes an **`aria-labelledby`** attribute referencing the `id` on `Dialog.Heading`, so the dialog
+has an accessible name that matches the visible heading.
+
+The Dialog component includes a `<div>` element (sibling to the `Dialog.Target`) with `aria-owns`
+pointing to the `Dialog.Card`. This remaps the hierarchy of the accessibility tree to improve
+sequential reading order in supported browsers. For more information, see
+[Guides > Accessibility > Inline Popups](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-inline-popups--docs).
+
+[Dialog Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
+
+- Prefer **`Dialog.Heading`** so the dialog is properly labelled; avoid leaving a dialog without an
+  accessible name.
+- Ensure icon-only controls such as **`Dialog.CloseIcon`** include an accessible name. Prefer the
+  `Tooltip` component to provide a visible label, or a translated `aria-label` string is acceptable.
+
+### Navigation
+
+- **Enter** / **Space**: Open the dialog (standard button behavior on the trigger). When it opens,
+  focus moves to the **first focusable element** inside the dialog in DOM order—often the close
+  control—or to the element referenced by **`initialFocusRef`** on the dialog model when set.
+- **Tab** / **Shift + Tab**: Move through focusable elements inside the dialog; leaving the first or
+  last focusable element **closes** the dialog and moves focus to the next or previous focusable
+  element on the page (non-modal focus redirect behavior).
+- **Escape**: Closes the dialog and returns focus to the `Dialog.Target` (or configured return
+  target).
+
+### Screen Reader Experience
+
+- **When the dialog opens:** Screen readers should announce the name and role of the first focused
+  control (often the close button), the dialog's name (`Dialog.Heading`) and role.
+- **Reading order:** The dialog contents should be read in the same order as it appears on screen
+  for browsers and screen readers that support `aria-owns`. Results vary, so always test with your
+  supported browsers and screen reader combinations.
+- **Expanded or collapsed state:** The `Dialog.Target` does not include an expanded or collapsed
+  state by default, but it can be added if the interaction design isn't using an initial focus for
+  the Dialog. See
+  [Guides > Accessibility > Inline Popups](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-inline-popups--docs)
+  for more information.
 
 ## Component API
 

package/dist/mdx/react/modal/Modal.mdx

@@ -13,9 +13,13 @@ import FormModal from './examples/FormModal';
 
 A Modal component is a type of Dialog that renders a translucent overlay that prevents user
 interaction with the rest of the page. A Modal will render the rest of the page inert until the
-Modal is dismissed. A Modal should be used when the user needs to presented with important
+Modal is dismissed. A Modal should be used when the user needs to be presented with important
 information that must be interacted with before continuing interaction with the rest of the page.
 
+For tasks that do not require blocking the rest of the page, consider the non-modal
+[**Dialog**](https://workday.github.io/canvas-kit/?path=/docs/components-popups-dialog--docs)
+component instead.
+
 ## Installation
 
 ```sh
@@ -34,7 +38,7 @@ dialog.
 ### Without Close Icon
 
 If you wish to remove the close icon button, you can simply omit the `Modal.CloseButton`
-subcomponent. If you have a modal dialog that requires the user to accept instead of dismiss though
+subcomponent. If you have a modal dialog that requires the user to accept instead of dismiss through
 an escape key or clicking outside the modal, you must create a new `PopupModel` without those
 behaviors and hand that model to the Modal dialog component.
 
@@ -52,18 +56,29 @@ element receives focus when the modal opens.
 
 <ExampleCodeBlock code={CustomFocus} />
 
+> **Accessibility Note**: When initial focus lands on a control **below** the heading (for example,
+> a text field instead of the close button), give supplementary copy a unique `id` and pass
+> **`aria-describedby`** on **`Modal.Card`** so screen readers can announce both the dialog name and
+> that text. For more examples of custom focus techniques, see
+> [Popup > Initial Focus](https://workday.github.io/canvas-kit/?path=/docs/components-popups-popup--docs#initial-focus).
+
 ### Return Focus
 
-By default, the Modal will return focus to the `Modal.Target` element, but it is possible the Modal
-was triggered by an element that won't exist when the modal is closed. An example might be a Modal
-that was opened from an Menu item and the act of opening the Modal also closes the Menu, meaning the
-Menu item can no longer receive focus. The also probably means the `Modal.Target` component might
-not suite your needs. The `Modal.Target` adds both a `ref` and an `onClick`. If you provide a
-`returnFocusRef`, you only need to worry about the `onClick`. If you're using a menu, you might need
-to use a different callback. Calling `model.events.show()` will show the Modal.
+By default, the Modal will return focus to the `Modal.Target` element. When you open the modal with
+`model.events.show()` (without `Modal.Target`), set **`returnFocusRef`** on the model to the element
+that should receive focus when the modal closes—for example the button that opened it. That covers
+cancel, Escape, and the close icon: focus returns to the control the user activated.
+
+If confirming an action **removes** that control from the document (such as deleting the row that
+held the delete button), `returnFocusRef` alone cannot land on a **new** target. The example below
+uses **`useLayoutEffect`** after the list updates to move focus to another row’s delete control, or
+to empty-state text when no files remain.
 
 <ExampleCodeBlock code={ReturnFocus} />
 
+> **Accessibility Note**: After an item is deleted, focus is returned to the next item in the list
+> or to the empty state text when no items remain.
+
 ### Custom Target
 
 It is common to have a custom target for your modal. Use the `as` prop to use your custom component.
@@ -79,6 +94,12 @@ requires a `label` prop.
 
 <ExampleCodeBlock code={CustomTarget} />
 
+> **Accessibility Note**: Custom targets must be keyboard focusable, otherwise users will not be
+> able to access the modal. Bear in mind that click handlers only work with the keyboard when
+> applied to HTML `<button>` elements and it is **strongly recommended** to base your custom target
+> on a `<button>` element. Otherwise, you will be required to build in your own custom keyboard
+> event handlers for invoking the modal.
+
 ### Body Content Overflow
 
 The Modal automatically handles overflowing content inside the `Modal.Body` element. If contents are
@@ -87,6 +108,11 @@ need to restrict the height of your browser to observe the overflow.
 
 <ExampleCodeBlock code={BodyOverflow} />
 
+> **Accessibility Note**: When body content overflows, ensure users can scroll that region **using
+> only the keyboard**. Mouse users can drag scrollbars, but keyboard users need another path. In
+> this example, **`tabIndex={0}`** is set on **`Modal.Body`** so the scrollable area can receive
+> focus; once focused, **arrow keys** move the viewport within the overflowing content.
+
 ### Full overlay scrolling
 
 If content is large, scrolling the entire overlay container is an option. Use the
@@ -105,6 +131,58 @@ hoisted to allow for form validation and allow you to control when the modal clo
 
 <ExampleCodeBlock code={FormModal} />
 
+## Accessibility
+
+`Modal` uses the default modal model (`useModalModel`), which composes **`useInitialFocus`**,
+**`useReturnFocus`**, **`useCloseOnOverlayClick`**, **`useCloseOnEscape`**, **`useFocusTrap`**,
+**`useAssistiveHideSiblings`**, and **`useDisableBodyScroll`**.
+
+**`Modal.Card`** exposes **`role="dialog"`** and **`aria-labelledby`** referencing the `id` on
+**`Modal.Heading`**, so the dialog has an accessible name that matches the visible heading. If you
+do not use **`Modal.Heading`**, add an **`aria-label`** on **`Modal.Card`** instead.
+
+**`aria-modal`:** The card sets **`aria-modal="false"`**. When **`aria-modal`** is `true`, some
+assistive technologies hide everything outside the dialog—including portaled UI owned by the dialog
+(such as a Select menu rendered as a sibling of the modal). Canvas Kit keeps
+**`aria-modal="false"`** for a better VoiceOver experience while **`useAssistiveHideSiblings`**
+applies **`aria-hidden`** to siblings of the modal stack so background content stays hidden from
+assistive technology while the modal is open.
+
+Unlike [**Dialog**](/components/popups/dialog/), Modal does **not** add the sibling **`aria-owns`**
+pattern used to remap reading order for portaled non-modal dialogs. Focus moves into the modal when
+it opens, and sibling hiding reduces exposure to content behind the overlay. For portals, reading
+order, and related tradeoffs, see
+[Guides > Accessibility > Inline Popups](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-inline-popups--docs).
+
+[Modal Dialog Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
+
+- Prefer **`Modal.Heading`** so the dialog is properly labelled; avoid leaving a dialog without an
+  accessible name.
+- Ensure icon-only controls such as **`Modal.CloseIcon`** include an accessible name. Prefer the
+  `Tooltip` component to provide a visible label, or a translated `aria-label` string is acceptable.
+
+### Navigation
+
+- **Enter** / **Space**: Open the modal (standard button behavior on the trigger). When it opens,
+  focus moves to the **first focusable element** inside the modal in DOM order—often the close
+  control—or to the element referenced by **`initialFocusRef`** on the model when set.
+- **Tab** / **Shift + Tab**: Move through focusable elements inside the modal; focus **stays**
+  within the modal (**focus trap**).
+- **Escape**: Closes the modal and returns focus to **`Modal.Target`** (or the configured return
+  target, such as **`returnFocusRef`**).
+
+### Screen Reader Experience
+
+- **When the modal opens:** Screen readers should announce the first focused control (often the
+  close button), the dialog's name (**`Modal.Heading`**) and role.
+- **Background content:** Sibling elements of the modal stack receive **`aria-hidden="true"`** while
+  the modal is visible, which hides the rest of the page from many assistive technologies. Mouse
+  users are blocked by the overlay and inert interaction expectations; always verify behavior in
+  your supported browser and screen reader combinations.
+- **Focus trap limits:** Trapping **keyboard** focus does not stop mouse users from interacting
+  outside the dialog card, and some screen reader users can move a virtual cursor outside the
+  trapped region. Treat the trap as the primary keyboard affordance, not a hard security boundary.
+
 ## Component API
 
 <SymbolDoc name="Modal" fileName="/react/" />

package/dist/mdx/react/modal/examples/FormModal.tsx

@@ -5,7 +5,17 @@ import {PrimaryButton} from '@workday/canvas-kit-react/button';
 import {Flex} from '@workday/canvas-kit-react/layout';
 import {FormField} from '@workday/canvas-kit-react/form-field';
 import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {Select} from '@workday/canvas-kit-react/select';
 import {plusIcon} from '@workday/canvas-system-icons-web';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const FAVORITE_COLOR_OPTIONS = ['Blue', 'Yellow'];
+
+const flexStyles = createStyles({
+  gap: system.space.x4,
+  padding: system.space.x2,
+});
 
 export default () => {
   const model = useModalModel();
@@ -18,6 +28,8 @@ export default () => {
     console.log('form data', {
       first: (event.currentTarget.elements.namedItem('first') as HTMLInputElement).value,
       last: (event.currentTarget.elements.namedItem('last') as HTMLInputElement).value,
+      favoriteColor: (event.currentTarget.elements.namedItem('favoriteColor') as HTMLInputElement)
+        .value,
     });
 
     // if it looks good, submit to the server and close the modal
@@ -40,8 +52,21 @@ export default () => {
               <FormField.Label>Last Name</FormField.Label>
               <FormField.Input as={TextInput} name="last" />
             </FormField>
+            <FormField>
+              <FormField.Label>Favorite Color</FormField.Label>
+              <FormField.Field>
+                <Select items={FAVORITE_COLOR_OPTIONS}>
+                  <FormField.Input as={Select.Input} name="favoriteColor" />
+                  <Select.Popper>
+                    <Select.Card>
+                      <Select.List>{item => <Select.Item>{item}</Select.Item>}</Select.List>
+                    </Select.Card>
+                  </Select.Popper>
+                </Select>
+              </FormField.Field>
+            </FormField>
           </Modal.Body>
-          <Flex gap="s" padding="xxs">
+          <Flex cs={flexStyles}>
             <Modal.CloseButton>Cancel</Modal.CloseButton>
             <PrimaryButton type="submit">Submit</PrimaryButton>
           </Flex>