@workday/canvas-kit-docs 15.0.0-alpha.1303-next.0 → 15.0.0

package/dist/mdx/react/common/mdx/examples/Theming.tsx

@@ -1,34 +1,52 @@
-import {createStyles} from '@workday/canvas-kit-styling';
-import {brand, base, system} from '@workday/canvas-tokens-web';
-import {CanvasProvider} from '@workday/canvas-kit-react/common';
-import {Card} from '@workday/canvas-kit-react/card';
 import {PrimaryButton} from '@workday/canvas-kit-react/button';
-
-const customTheme = createStyles({
-  [brand.primary.base]: base.green600,
-  [brand.primary.dark]: base.green700,
-  [brand.primary.darkest]: base.green800,
-  [brand.common.focusOutline]: base.green600,
-  [system.color.fg.strong]: base.indigo900,
-  [system.color.border.container]: base.indigo300,
-});
+import {Card} from '@workday/canvas-kit-react/card';
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {base} from '@workday/canvas-tokens-web';
 
 const App = () => {
   return (
-    <Card>
-      <Card.Heading>Theming</Card.Heading>
-      <Card.Body>
-        <PrimaryButton>Theming</PrimaryButton>
-        <input />
-      </Card.Body>
-    </Card>
+    <CanvasProvider
+      theme={{
+        canvas: {
+          palette: {
+            primary: {
+              main: base.green600,
+            },
+            alert: {
+              main: base.magenta600,
+            },
+            common: {
+              focusOutline: base.purple500,
+              alertInner: base.magenta400,
+              alertOuter: base.magenta500,
+              errorInner: base.red500,
+            },
+          },
+        },
+      }}
+    >
+      <Card>
+        <Card.Heading>Theming</Card.Heading>
+        <Card.Body>
+          <PrimaryButton>Theming</PrimaryButton>
+          <FormField error="caution">
+            <FormField.Label>Email</FormField.Label>
+            <FormField.Field>
+              <FormField.Input as={TextInput} />
+            </FormField.Field>
+          </FormField>
+        </Card.Body>
+      </Card>
+    </CanvasProvider>
   );
 };
 
 export default () => {
   return (
-    <CanvasProvider className={customTheme}>
+    <div>
       <App />
-    </CanvasProvider>
+    </div>
   );
 };

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/dialog/examples/Basic.tsx

@@ -1,9 +1,10 @@
 import React from 'react';
+
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {Dialog} from '@workday/canvas-kit-react/dialog';
 import {FormField} from '@workday/canvas-kit-react/form-field';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {Dialog} from '@workday/canvas-kit-react/dialog';
-import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 
 export default () => {
   const [value, setValue] = React.useState('');

package/dist/mdx/react/dialog/examples/DialogWithFallbackPlacements.tsx

@@ -1,8 +1,8 @@
-import {Dialog} from '@workday/canvas-kit-react/dialog';
 import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {Dialog} from '@workday/canvas-kit-react/dialog';
 import {Flex, Grid} from '@workday/canvas-kit-react/layout';
 import {calc, createStyles} from '@workday/canvas-kit-styling';
-import {system} from '@workday/canvas-tokens-web';
+import {base, system} from '@workday/canvas-tokens-web';
 
 export default {
   title: 'Testing/Popups/Dialog',
@@ -11,8 +11,8 @@ export default {
 
 const grid = createStyles({
   gridTemplateAreas: "'topButton topButton''leftButton rightButton''bottomButton bottomButton'",
-  height: calc.subtract('100vh', system.space.x16),
-  width: calc.subtract('100vw', system.space.x20),
+  height: calc.subtract('100vh', system.size.xxl),
+  width: calc.subtract('100vw', base.size1000),
 });
 
 const topButton = createStyles({
@@ -46,9 +46,11 @@ export default () => {
           <Dialog.Popper placement="top">
             <Dialog.Card>
               <Dialog.CloseIcon aria-label="Close" />
-              <Dialog.Heading paddingTop="m">This is dialog heading</Dialog.Heading>
+              <Dialog.Heading cs={{paddingTop: system.padding.md}}>
+                This is dialog heading
+              </Dialog.Heading>
               <Dialog.Body>This is dialog body.</Dialog.Body>
-              <Flex gap="s" padding="xxs" marginTop="xxs">
+              <Flex cs={{gap: system.gap.sm, padding: system.padding.xs, marginTop: system.gap.sm}}>
                 <Dialog.CloseButton as={PrimaryButton}>Submit</Dialog.CloseButton>
                 <Dialog.CloseButton>Cancel</Dialog.CloseButton>
               </Flex>
@@ -62,9 +64,11 @@ export default () => {
           <Dialog.Popper placement="left">
             <Dialog.Card>
               <Dialog.CloseIcon aria-label="Close" />
-              <Dialog.Heading paddingTop="m">This is dialog heading</Dialog.Heading>
+              <Dialog.Heading cs={{paddingTop: system.padding.md}}>
+                This is dialog heading
+              </Dialog.Heading>
               <Dialog.Body>This is dialog body.</Dialog.Body>
-              <Flex gap="s" padding="xxs" marginTop="xxs">
+              <Flex cs={{gap: system.gap.sm, padding: system.padding.xs, marginTop: system.gap.sm}}>
                 <Dialog.CloseButton as={PrimaryButton}>Submit</Dialog.CloseButton>
                 <Dialog.CloseButton>Cancel</Dialog.CloseButton>
               </Flex>
@@ -78,9 +82,11 @@ export default () => {
           <Dialog.Popper placement="right">
             <Dialog.Card>
               <Dialog.CloseIcon aria-label="Close" />
-              <Dialog.Heading paddingTop="m">This is dialog heading</Dialog.Heading>
+              <Dialog.Heading cs={{paddingTop: system.padding.md}}>
+                This is dialog heading
+              </Dialog.Heading>
               <Dialog.Body>This is dialog body.</Dialog.Body>
-              <Flex gap="s" padding="xxs" marginTop="xxs">
+              <Flex cs={{gap: system.gap.sm, padding: system.padding.xs, marginTop: system.gap.sm}}>
                 <Dialog.CloseButton as={PrimaryButton}>Submit</Dialog.CloseButton>
                 <Dialog.CloseButton>Cancel</Dialog.CloseButton>
               </Flex>
@@ -94,9 +100,11 @@ export default () => {
           <Dialog.Popper placement="bottom">
             <Dialog.Card>
               <Dialog.CloseIcon aria-label="Close" />
-              <Dialog.Heading paddingTop="m">This is dialog heading</Dialog.Heading>
+              <Dialog.Heading cs={{paddingTop: system.padding.md}}>
+                This is dialog heading
+              </Dialog.Heading>
               <Dialog.Body>This is dialog body.</Dialog.Body>
-              <Flex gap="s" padding="xxs" marginTop="xxs">
+              <Flex cs={{gap: system.gap.sm, padding: system.padding.xs, marginTop: system.gap.sm}}>
                 <Dialog.CloseButton as={PrimaryButton}>Submit</Dialog.CloseButton>
                 <Dialog.CloseButton>Cancel</Dialog.CloseButton>
               </Flex>

package/dist/mdx/react/dialog/examples/Focus.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {Dialog} from '@workday/canvas-kit-react/dialog';
 import {FormField} from '@workday/canvas-kit-react/form-field';
-import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {Dialog} from '@workday/canvas-kit-react/dialog';
-import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
 
 export default () => {
   const [value, setValue] = React.useState('');

package/dist/mdx/react/expandable/Expandable.mdx

@@ -46,8 +46,18 @@ To include an avatar image, `Expandable.Avatar` should be placed between `Expand
 to `Expandable.Icon` depending on whether the `Expandable.Icon` is placed before or after
 `Expandable.Title`.
 
+**Note:** If using an avatar image, do not also include an Icon component in addition to the Expandable.Icon.
+This component is meant to have either an avatar image or an icon in addition to the Expandable.Icon, or neither
+an avatar image nor an extra icon.
+
+
 <ExampleCodeBlock code={Avatar} />
 
+> **Accessibility Note:** In this situation, the Avatar is decorative and should not be announced to
+> screen readers. The `<Expandable.Avatar>` component has `isDecorative` set to `true` by default to
+> hide it from screen readers, as avatars in expandable headers are typically decorative when paired
+> with adjacent text.
+
 ### Right to Left (RTL)
 
 Expandable container has bidirectional support and should function as expected with RTL languages as
@@ -72,11 +82,53 @@ You can also have direct access to the model if
 
 ### Hoisted Model
 
-If you you need direct access to the model, you can hoist it with the `useExpandableModel` hook. In
-the example below, we're hoisting the models to expand and collapse all three containers at once.
+If you need direct access to the model, you can hoist it with the `useExpandableModel` hook. In the
+example below, we're hoisting the models to expand and collapse all three containers at once.
 
 <ExampleCodeBlock code={HoistedModel} />
 
+> **Accessibility Note:** When using multiple Expandable Containers on a page, use the `as` prop to
+> render the `<Expandable.Content>` sub-component as an HTML `<section>` element. Then, use
+> `aria-labelledby` to reference the unique `id` of the `<Expandable.Title>` element. This practice
+> can be useful to screen reader users when multiple Expandable Containers are opened at one time
+> for uniquely describing the boundaries of the expandable content.
+
+## Accessibility
+
+Our Expandable component renders a semantic HTML `<button>` element to the DOM, with an optional
+parent heading element as defined by the `headingLevel` prop. The `aria-expanded` property is
+included on the button to indicate the state of the content to screen readers.
+
+[Accordion Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
+
+- Use the `headingLevel` prop to assign an appropriate heading level based on the context of the
+  page content.
+- When using Expandable Container for navigation elements, then we don't recommend using the
+  `headingLevel` prop. This will render only expandable buttons to the DOM, reserving headings for
+  organizing content in the main body of the page.
+- The `as` prop may also be used on `<Expandable.Content>` to render an HTML `<ul>` element for
+  displaying a list of items. For example, check out
+  [Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs).
+
+### Navigation
+
+- **Tab key**: Moves focus to the next expandable button or focusable element
+- **Shift + Tab**: Moves focus to the previous focusable element
+- **Enter or Space**: Toggles the expanded/collapsed state
+
+### Screen Reader Experience
+
+- The expandable button will be announced with its title text followed by the button role
+- The current state will be announced as either "collapsed" or "expanded" (For example: "Usage
+  Guidance, button, collapsed" or "Usage Guidance, button, expanded")
+- **State Changes:** When activating the button to expand content, screen readers will announce the
+  new "expanded" state and vice versa when collapsing content.
+- **Content Regions:** Screen reader users can use landmark navigation to jump between sections and
+  each section will be announced with its associated title (For example: "Usage Guidance, landmark
+  region")
+- **Heading Structure:** Using heading levels with expandable buttons allows screen reader users to
+  navigate by headings, making the document structure and hierarchy easier to understand.
+
 ## Component API
 
 <SymbolDoc name="Expandable" fileName="/react/" />

package/dist/mdx/react/expandable/examples/Avatar.tsx

@@ -1,4 +1,5 @@
 import {Expandable} from '@workday/canvas-kit-react/expandable';
+
 // @ts-ignore: Cannot find module error
 import testAvatar from './test-avatar.png';
 

package/dist/mdx/react/expandable/examples/Depth.tsx

@@ -1,8 +1,17 @@
 import {Expandable} from '@workday/canvas-kit-react/expandable';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const expandableStyles = createStyles({
+  boxShadow: system.depth[3],
+  borderRadius: system.shape.lg,
+  padding: system.padding.xs,
+  margin: system.gap.xs,
+});
 
 export default () => {
   return (
-    <Expandable borderRadius="l" depth={3} margin="xxxs" padding="xs">
+    <Expandable cs={expandableStyles}>
       <Expandable.Target headingLevel="h4">
         <Expandable.Title>Additional Information</Expandable.Title>
         <Expandable.Icon iconPosition="end" />

package/dist/mdx/react/expandable/examples/HoistedModel.tsx

@@ -1,14 +1,27 @@
-import React from 'react';
-
+import {SecondaryButton} from '@workday/canvas-kit-react/button';
+import {useUniqueId} from '@workday/canvas-kit-react/common';
 import {Expandable, useExpandableModel} from '@workday/canvas-kit-react/expandable';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {SecondaryButton} from '@workday/canvas-kit-react/button';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const listStyles = createStyles({
+  flexDirection: 'column',
+  gap: system.gap.sm,
+  padding: '0',
+  marginInline: system.padding.md,
+  marginBlock: '0',
+});
 
 export default () => {
   const modelOne = useExpandableModel();
   const modelTwo = useExpandableModel();
   const modelThree = useExpandableModel();
 
+  const idOne = useUniqueId();
+  const idTwo = useUniqueId();
+  const idThree = useUniqueId();
+
   const handleExpandAll = () => {
     modelOne.events.show();
     modelTwo.events.show();
@@ -22,19 +35,19 @@ export default () => {
   };
 
   return (
-    <Flex gap="m" flexDirection="column">
-      <Flex gap="s">
+    <Flex cs={{gap: system.gap.lg, flexDirection: 'column'}}>
+      <Flex cs={{gap: system.gap.md}}>
         <SecondaryButton onClick={handleExpandAll}>Expand All</SecondaryButton>
         <SecondaryButton onClick={handleCollapseAll}>Collapse All</SecondaryButton>
       </Flex>
-      <Flex flexDirection="column">
+      <Flex cs={{flexDirection: 'column'}}>
         <Expandable model={modelOne}>
           <Expandable.Target headingLevel="h4">
-            <Expandable.Title>Usage Guidance</Expandable.Title>
+            <Expandable.Title id={idOne}>Usage Guidance</Expandable.Title>
             <Expandable.Icon iconPosition="end" />
           </Expandable.Target>
 
-          <Expandable.Content>
+          <Expandable.Content as="section" aria-labelledby={idOne}>
             This component highlights the most important details of a section and reveals more when
             a user taps or clicks on the header part of the container. Enabling users to hide and
             show information ensures the design remains focused and relevant to their expectations.
@@ -44,20 +57,12 @@ export default () => {
         </Expandable>
         <Expandable model={modelTwo}>
           <Expandable.Target headingLevel="h4">
-            <Expandable.Title>Accessibility Guidelines</Expandable.Title>
+            <Expandable.Title id={idTwo}>Accessibility Guidelines</Expandable.Title>
             <Expandable.Icon iconPosition="end" />
           </Expandable.Target>
 
-          <Expandable.Content>
-            <Flex
-              flexDirection="column"
-              as="ul"
-              gap="xxs"
-              maxWidth="60ch"
-              padding="zero"
-              marginX="s"
-              marginY="zero"
-            >
+          <Expandable.Content as="section" aria-labelledby={idTwo}>
+            <Flex as="ul" cs={listStyles}>
               <li>
                 The state of a component being open or closed must be conveyed to assistive
                 technologies.
@@ -92,10 +97,10 @@ export default () => {
         </Expandable>
         <Expandable model={modelThree}>
           <Expandable.Target headingLevel="h4">
-            <Expandable.Title>Content Guidelines</Expandable.Title>
+            <Expandable.Title id={idThree}>Content Guidelines</Expandable.Title>
             <Expandable.Icon iconPosition="end" />
           </Expandable.Target>
-          <Expandable.Content>
+          <Expandable.Content as="section" aria-labelledby={idThree}>
             Titles should be short and concise, yet long enough to explain what the user would
             expect to see when the content is expanded. If titles must be long, make sure it doesn't
             wrap more than two lines.

package/dist/mdx/react/expandable/examples/LongTitle.tsx

@@ -1,4 +1,5 @@
 import {Expandable} from '@workday/canvas-kit-react/expandable';
+
 // @ts-ignore: Cannot find module error
 import testAvatar from './test-avatar.png';
 

package/dist/mdx/react/expandable/examples/RTL.tsx

@@ -1,14 +1,9 @@
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
 import {Expandable} from '@workday/canvas-kit-react/expandable';
-import {CanvasProvider, ContentDirection} from '@workday/canvas-kit-react/common';
 
 export default () => {
-  const theme = {
-    canvas: {
-      direction: ContentDirection.RTL,
-    },
-  };
   return (
-    <CanvasProvider theme={theme}>
+    <CanvasProvider dir="rtl">
       <Expandable>
         <Expandable.Target headingLevel="h4">
           <Expandable.Icon iconPosition="start" />