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

package/dist/mdx/{preview-react → react}/pill/examples/WithCount.tsx

@@ -1,12 +1,13 @@
 import React from 'react';
-import {Pill} from '@workday/canvas-kit-preview-react/pill';
+
+import {Pill} from '@workday/canvas-kit-react/pill';
 import {BodyText} from '@workday/canvas-kit-react/text';
 import {createStyles} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
 
 const flexStyles = createStyles({
   display: 'flex',
-  gap: system.space.x2,
+  gap: system.gap.sm,
 });
 
 export default () => {

package/dist/mdx/{preview-react → react}/pill/examples/WithList.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 
-import {Pill} from '@workday/canvas-kit-preview-react/pill';
+import {Pill} from '@workday/canvas-kit-react/pill';
 import {createStyles} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
 
@@ -21,7 +21,7 @@ const data = [
 const flexWrapStyles = createStyles({
   display: 'flex',
   flexWrap: 'wrap',
-  gap: system.space.x2,
+  gap: system.gap.sm,
 });
 
 export default () => {

package/dist/mdx/{preview-react → react}/pill/examples/WithReadOnly.tsx

@@ -1,16 +1,16 @@
-import {Pill} from '@workday/canvas-kit-preview-react/pill';
+import {Pill} from '@workday/canvas-kit-react/pill';
 import {createStyles} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
 
 const flexStyles = createStyles({
   display: 'flex',
-  gap: system.space.x2,
+  gap: system.gap.sm,
 });
 
 export default () => (
   <div className={flexStyles} id="read-only-list">
     <Pill variant="readOnly">Read-only</Pill>
-    <Pill variant="readOnly" maxWidth={150}>
+    <Pill variant="readOnly" cs={{maxWidth: 150}}>
       Read-only but with super long text in case you want to read a paragraph in a Pill which we
       don't recommend
     </Pill>

package/dist/mdx/{preview-react → react}/pill/examples/WithRemovable.tsx

@@ -1,15 +1,16 @@
 import React from 'react';
 
-import {Pill} from '@workday/canvas-kit-preview-react/pill';
-// @ts-ignore: Cannot find module error
-import testAvatar from './test-avatar.png';
+import {Pill} from '@workday/canvas-kit-react/pill';
 import {BodyText} from '@workday/canvas-kit-react/text';
-import {system} from '@workday/canvas-tokens-web';
 import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+// @ts-ignore: Cannot find module error
+import testAvatar from './test-avatar.png';
 
 const flexStyles = createStyles({
   display: 'flex',
-  gap: system.space.x2,
+  gap: system.gap.sm,
 });
 
 export default () => {

package/dist/mdx/react/popup/Popup.mdx

@@ -1,14 +1,15 @@
-import {ExampleCodeBlock, SymbolDoc, Specifications} from '@workday/canvas-kit-docs';
+import {ExampleCodeBlock, Specifications, SymbolDoc} from '@workday/canvas-kit-docs';
+
 import Basic from './examples/Basic';
+import CustomTarget from './examples/CustomTarget';
+import ExternalWindow from './examples/ExternalWindow';
+import FocusRedirect from './examples/FocusRedirect';
+import FocusTrap from './examples/FocusTrap';
+import FullScreen from './examples/FullScreen';
 import InitialFocus from './examples/InitialFocus';
 import MultiplePopups from './examples/MultiplePopups';
 import NestedPopups from './examples/NestedPopups';
-import FocusRedirect from './examples/FocusRedirect';
-import FocusTrap from './examples/FocusTrap';
 import RTL from './examples/RTL';
-import CustomTarget from './examples/CustomTarget';
-import ExternalWindow from './examples/ExternalWindow';
-import FullScreen from './examples/FullScreen';
 
 
 # Canvas Kit Popups
@@ -44,7 +45,7 @@ yarn add @workday/canvas-kit-react
 ## Usage
 
 The `Popup` component is a generic
-[Compound Component](/getting-started/for-developers/resources/compound-components/) that is used to
+[Compound Component](/get-started/for-developers/documentation/compound-components/) that is used to
 build popup UIs that are not already covered by Canvas Kit.
 
 ### Basic Example
@@ -61,52 +62,56 @@ popup behaviors. For accessibility, these behaviors should be included most of t
 ### Initial Focus
 
 If you want focus to move to a specific element when the popup is opened, set the `initialFocusRef`
-of the model. Check with accessibility before doing this. The following example sets the focus on
-the "OK" button with an `aria-describedby` pointing to the model's `id` state so screen readers
-properly announce the message of the popup when focus is changed to the button. By default, focus
-will be placed on the first focusable element when the popup is opened.
+of the model. This is useful for popups that don't have a Close icon button near the top right of
+the popup. In general, we recommend setting focus to the first interactive component inside the
+popup that is the least destructive action.
 
 <ExampleCodeBlock code={InitialFocus} />
 
+> **Accessibility Note**: When initial focus lands on a control **below** the title (such as the OK
+> button in the example above), assign a unique `id` to supplementary text and pass
+> `aria-describedby` on `Popup.Card`. This augments the included `aria-labelledby` reference to
+> `Popup.Heading` so screen readers can announce both the heading and any supplementary text
+> automatically. When initial focus is on the heading itself, add `tabIndex={-1}` to `Popup.Heading`
+> so the title can receive programmatic focus. Choose where focus goes based on your product and
+> accessibility requirements.
+
 ### Focus Redirect
 
 Focus management is important to accessibility of popup contents. The following example shows
 `useFocusRedirect` being used to manage focus in and out of a Popup. This is very useful for
-Dialog-style popups. Since `Popup.Popper` renders contents to the bottom of the document body,
-`aria-owns` is used for screen readers that support it. This effectively treats a Popup like it
-exists in between the buttons while it is opened. Screen readers will navigate the content as if the
-content was not portalled to the bottom of the document body. Focus redirection tries to treat the
-Popup as if it were inline to the document. Tabbing out of the Popup will close the Popup and move
-focus to the next appropriate element.
-
-> **Note**: Safari does not support `aria-owns`. This means that the contents of the Popup will
-> appears out of order to Safari + VoiceOver users. We render popups at the bottom of the
-> document.body to ensure proper rendering. You could use `portal=false` on the `Popper` component,
-> but that would risk incorrect rendering in all browsers.
+non-modal popups. Focus redirection tries to treat the Popup as if it were inline to the document.
+Tabbing out of the Popup will close the Popup and move focus to an adjacent focusable element.
 
 <ExampleCodeBlock code={FocusRedirect} />
 
+> **Accessibility Note**: The `useFocusRedirect` hook **will not** have any effect on the reading
+> order of a screen reader. Screen reader users may get confused or disoriented when popups are
+> portalled to the bottom of the document body. In this example, we're testing the use of
+> `aria-owns` on a sibling `<div>` element pointing to the `Popup.Card` component. This remaps the
+> hierarchy of the accessibility tree (in supported browsers) to address the reading order problem.
+> For more information, see
+> [Guides > Accessibility > Inline Popups](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-inline-popups--docs).
+
 ### Focus Trapping
 
 Focus trapping is similar to the [Focus Redirect](#focus-redirect) example, but will trap focus
-inside the popup instead of redirecting focus, it will be trapped inside the Popup. This is most
-useful for modal dialogs where the modal must be interacted with before normal interaction can
-continue.
-
-> **Note**: Using focus trapping outside a Modal context can give users a different experience
-> depending on how they interact with your application. Focus trapping will not prevent mouse users
-> from breaking out of a focus trap, nor will it prevent screen reader users from using virtual
-> cursors from breaking out. Modals should use additional techniques to truely "trap" focus into the
-> Popup to provide a consistent experience for all users.
+inside the popup instead of redirecting focus to adjacent focusable elements. This is necessary for
+modal dialogs where users must focus on the contents of the dialog before proceeding.
 
 <ExampleCodeBlock code={FocusTrap} />
 
+> **Accessibility Note**: Focus trapping will not prevent mouse users from breaking out of a focus
+> trap, nor will it prevent screen reader users from using virtual reading cursors from breaking
+> out. Consider using [Modal](/components/popups/modal/) instead when you need to focus users'
+> attention on a specific task inside of a popup..
+
 ### Multiple Popups
 
-If you need multiple Popups within the same component, you can create multiple models and pass a
-unique model to each Popup. Below is an example of 2 different popups within the same component.
-Since each Popup gets its own model, each Popup behaves independently. The same technique can be
-used for nested Popups.
+You can render more than one `Popup` in the same view by giving each its own model. This example
+pairs `Popup` with `useDialogModel` and `useModalModel` so you can compare **focus redirection**
+(Tab / Shift + Tab can move focus out of the first popup) and **focus trapping** (focus stays inside
+the second popup until it closes). Opening one does not close the other.
 
 <ExampleCodeBlock code={MultiplePopups} />
 
@@ -123,6 +128,11 @@ preserved.
 
 <ExampleCodeBlock code={NestedPopups} />
 
+> **Accessibility Note**: In this example, observe how users can traverse both opened popups using
+> the keyboard. This is likely to be a confusing experience for users and may necessitate focus
+> trapping inside each popup with careful consideration for setting initial focus and returning
+> focus.
+
 ### Custom Target
 
 It is common to have a custom target for your popup. Use the `as` prop to use your custom component.
@@ -138,6 +148,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 popup. 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 popup.
+
 ### Full Screen API
 
 By default, popups are created as children of the `document.body` element, but the `PopupStack`
@@ -175,6 +191,18 @@ The Popup component automatically handles right-to-left rendering.
 
 <ExampleCodeBlock code={RTL} />
 
+## Accessibility
+
+Popup content is usually portaled to the bottom of the `document.body`, which can affect **reading
+order for screen readers** and **keyboard focus order**. For more information about Popup
+accessibility, check out our documentation at
+[Guides > Accessibility > Inline Popups](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-inline-popups--docs).
+
+- For non-modal dialogs with `aria-owns` built-in to improve reading order for screen readers (that
+  support it), check out the [**Dialog**](/components/popups/dialog/) component.
+- For modal dialogs with built-in overlays and focus traps, check out the
+  [**Modal**](/components/popups/modal/) component.
+
 ## Component API
 
 <>
@@ -241,4 +269,4 @@ The Popup component automatically handles right-to-left rendering.
 
 ## Specifications
 
-<Specifications file="Popup.spec.ts" name="Popup" />
+<Specifications file="./cypress/component/Popup.spec.tsx" name="Popup" />

package/dist/mdx/react/popup/examples/Basic.tsx

@@ -1,13 +1,29 @@
 import {DeleteButton} from '@workday/canvas-kit-react/button';
+import {Box, Flex} from '@workday/canvas-kit-react/layout';
 import {
   Popup,
-  usePopupModel,
   useCloseOnEscape,
   useCloseOnOutsideClick,
+  useFocusRedirect,
   useInitialFocus,
+  usePopupModel,
   useReturnFocus,
 } 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';
+
+const cardStyles = createStyles({
+  width: px2rem(400),
+});
+
+const bodyStyles = createStyles({
+  marginBlock: '0',
+});
+
+const flexStyles = createStyles({
+  gap: system.gap.md,
+  padding: system.padding.xs,
+});
 
 export default () => {
   const model = usePopupModel();
@@ -16,6 +32,7 @@ export default () => {
   useCloseOnEscape(model);
   useInitialFocus(model);
   useReturnFocus(model);
+  useFocusRedirect(model);
 
   const handleDelete = () => {
     console.log('Delete Item');
@@ -25,15 +42,15 @@ export default () => {
     <Popup model={model}>
       <Popup.Target as={DeleteButton}>Delete Item</Popup.Target>
       <Popup.Popper placement="top">
-        <Popup.Card width={400}>
+        <Popup.Card cs={cardStyles}>
           <Popup.CloseIcon aria-label="Close" />
           <Popup.Heading>Delete Item</Popup.Heading>
           <Popup.Body>
-            <Box as="p" marginY="zero">
+            <Box as="p" cs={bodyStyles}>
               Are you sure you'd like to delete the item titled 'My Item'?
             </Box>
           </Popup.Body>
-          <Flex gap="s" padding="xxs">
+          <Flex cs={flexStyles}>
             <Popup.CloseButton as={DeleteButton} onClick={handleDelete}>
               Delete
             </Popup.CloseButton>

package/dist/mdx/react/popup/examples/ComboboxWithinPopup.tsx

@@ -1,12 +1,12 @@
-import {FormField} from '@workday/canvas-kit-react/form-field';
 import {SecondaryButton} from '@workday/canvas-kit-react/button';
 import {Combobox} from '@workday/canvas-kit-react/combobox';
+import {FormField} from '@workday/canvas-kit-react/form-field';
 import {
   Popup,
-  useCloseOnOutsideClick,
   useCloseOnEscape,
-  usePopupModel,
+  useCloseOnOutsideClick,
   useInitialFocus,
+  usePopupModel,
   useReturnFocus,
 } from '@workday/canvas-kit-react/popup';
 

package/dist/mdx/react/popup/examples/CustomTarget.tsx

@@ -2,12 +2,13 @@ import React from 'react';
 
 import {
   Popup,
-  usePopupModel,
   useCloseOnEscape,
   useCloseOnOutsideClick,
   useInitialFocus,
+  usePopupModel,
   useReturnFocus,
 } from '@workday/canvas-kit-react/popup';
+import {px2rem} from '@workday/canvas-kit-styling';
 
 interface MyTargetProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   label: string;
@@ -33,7 +34,7 @@ export default () => {
     <Popup model={model}>
       <Popup.Target as={MyTarget} label="Open" />
       <Popup.Popper>
-        <Popup.Card>
+        <Popup.Card cs={{minWidth: px2rem(320)}}>
           <Popup.CloseIcon aria-label="Close" />
           <Popup.Heading>Popup</Popup.Heading>
           <Popup.Body>Contents</Popup.Body>

package/dist/mdx/react/popup/examples/ExternalWindow.tsx

@@ -1,25 +1,24 @@
 import React from 'react';
 import ReactDOM from 'react-dom';
 
-import {system} from '@workday/canvas-tokens-web';
-import {createStyles} from '@workday/canvas-kit-styling';
-import {infoIcon} from '@workday/canvas-system-icons-web';
-
+import {SecondaryButton} from '@workday/canvas-kit-react/button';
 import {
   CanvasProvider,
   ContentDirection,
-  createSubcomponent,
   PartialEmotionCanvasTheme,
+  createSubcomponent,
   useMount,
   useTheme,
 } from '@workday/canvas-kit-react/common';
-import {Tooltip} from '@workday/canvas-kit-react/tooltip';
-import {Popup, usePopupModel} from '@workday/canvas-kit-react/popup';
-import {SecondaryButton} from '@workday/canvas-kit-react/button';
 import {Flex} from '@workday/canvas-kit-react/layout';
+import {Popup, usePopupModel} from '@workday/canvas-kit-react/popup';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {infoIcon} from '@workday/canvas-system-icons-web';
+import {system} from '@workday/canvas-tokens-web';
 
 const mainContentStyles = createStyles({
-  padding: system.space.x4,
+  padding: system.padding.md,
 });
 
 export interface ExternalWindowPortalProps {
@@ -151,26 +150,24 @@ export default () => {
 
   return (
     <CanvasProvider theme={canvasTheme}>
-      <>
-        <main className={mainContentStyles}>
-          <p>Popup that opens a new Operating System Window</p>
-          <Popup model={model}>
-            <Tooltip title="Open External Window Tooltip">
-              <Popup.Target>Open External Window</Popup.Target>
-            </Tooltip>
-            <PopupExternalWindow>
-              <p>External Window Contents! Mouse over the info icon to get a tooltip</p>
-              <Flex gap="s">
-                <Tooltip title="More information">
-                  <SecondaryButton icon={infoIcon} />
-                </Tooltip>
-                <Popup.CloseButton>Close Window</Popup.CloseButton>
-              </Flex>
-            </PopupExternalWindow>
-          </Popup>
-          <p>Popup visibility: {model.state.visibility}</p>
-        </main>
-      </>
+      <main className={mainContentStyles}>
+        <p>Popup that opens a new Operating System Window</p>
+        <Popup model={model}>
+          <Tooltip title="Open External Window Tooltip">
+            <Popup.Target>Open External Window</Popup.Target>
+          </Tooltip>
+          <PopupExternalWindow>
+            <p>External Window Contents! Mouse over the info icon to get a tooltip</p>
+            <Flex cs={{gap: system.gap.sm}}>
+              <Tooltip title="More information">
+                <SecondaryButton icon={infoIcon} />
+              </Tooltip>
+              <Popup.CloseButton>Close Window</Popup.CloseButton>
+            </Flex>
+          </PopupExternalWindow>
+        </Popup>
+        <p>Popup visibility: {model.state.visibility}</p>
+      </main>
     </CanvasProvider>
   );
 };

package/dist/mdx/react/popup/examples/FocusRedirect.tsx

@@ -1,16 +1,32 @@
 import * as React from 'react';
 
 import {DeleteButton, SecondaryButton} from '@workday/canvas-kit-react/button';
+import {useUniqueId} from '@workday/canvas-kit-react/common';
+import {Box, Flex} from '@workday/canvas-kit-react/layout';
 import {
   Popup,
   useCloseOnEscape,
   useCloseOnOutsideClick,
-  useInitialFocus,
-  useReturnFocus,
   useFocusRedirect,
+  useInitialFocus,
   usePopupModel,
+  useReturnFocus,
 } 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';
+
+const cardStyles = createStyles({
+  width: px2rem(400),
+});
+
+const bodyStyles = createStyles({
+  marginBlock: '0',
+});
+
+const flexStyles = createStyles({
+  gap: system.gap.md,
+  padding: system.padding.xs,
+});
 
 export default () => {
   const model = usePopupModel();
@@ -25,34 +41,33 @@ export default () => {
     console.log('Delete Item');
   };
 
-  const popupId = 'popup-test-id';
+  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]);
+  }, [model.state.stackRef, visible, popupId]);
 
   return (
     <Popup model={model}>
-      <Flex gap="s">
+      <Flex cs={flexStyles}>
         <Popup.Target as={DeleteButton}>Delete Item</Popup.Target>
-        <div aria-owns={popupId} style={{position: 'absolute'}} />
+        <div aria-owns={popupId} style={{position: 'absolute'}}></div>
         <Popup.Popper>
-          <Popup.Card width={400}>
+          <Popup.Card cs={cardStyles}>
             <Popup.CloseIcon aria-label="Close" />
             <Popup.Heading>Delete Item</Popup.Heading>
             <Popup.Body>
-              <Box as="p" marginY="zero">
+              <Box as="p" cs={bodyStyles}>
                 Are you sure you'd like to delete the item titled 'My Item'?
               </Box>
             </Popup.Body>
-            <Flex gap="s" padding="xxs">
+            <Flex cs={flexStyles}>
               <Popup.CloseButton as={DeleteButton} onClick={handleDelete}>
                 Delete
               </Popup.CloseButton>
-              {/* Disabled elements should not be focusable and focus should move to the next focusable element */}
-              <Popup.CloseButton disabled>Cancel</Popup.CloseButton>
+              <Popup.CloseButton>Cancel</Popup.CloseButton>
             </Flex>
           </Popup.Card>
         </Popup.Popper>

package/dist/mdx/react/popup/examples/FocusTrap.tsx

@@ -1,16 +1,18 @@
 import * as React from 'react';
 
 import {DeleteButton, SecondaryButton} from '@workday/canvas-kit-react/button';
+import {Box, Flex} from '@workday/canvas-kit-react/layout';
 import {
   Popup,
   useCloseOnEscape,
   useCloseOnOutsideClick,
   useFocusTrap,
   useInitialFocus,
-  useReturnFocus,
   usePopupModel,
+  useReturnFocus,
 } from '@workday/canvas-kit-react/popup';
-import {Box, Flex} from '@workday/canvas-kit-react/layout';
+import {px2rem} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
 
 export default () => {
   const model = usePopupModel();
@@ -35,19 +37,19 @@ export default () => {
 
   return (
     <Popup model={model}>
-      <Flex gap="s">
+      <Flex cs={{gap: system.gap.sm}}>
         <Popup.Target as={DeleteButton}>Delete Item</Popup.Target>
         <div aria-owns={popupId} style={{position: 'absolute'}} />
         <Popup.Popper>
-          <Popup.Card width={400}>
+          <Popup.Card cs={{width: px2rem(400)}}>
             <Popup.CloseIcon aria-label="Close" />
             <Popup.Heading>Delete Item</Popup.Heading>
             <Popup.Body>
-              <Box as="p" marginY="zero">
+              <Box as="p" cs={{marginBlock: '0'}}>
                 Are you sure you'd like to delete the item titled 'My Item'?
               </Box>
             </Popup.Body>
-            <Flex gap="s" padding="xxs">
+            <Flex cs={{gap: system.gap.sm, paddingBlock: system.padding.xxs}}>
               <Popup.CloseButton as={DeleteButton} onClick={handleDelete}>
                 Delete
               </Popup.CloseButton>

package/dist/mdx/react/popup/examples/FullScreen.tsx

@@ -1,21 +1,21 @@
 import * as React from 'react';
+import screenfull from 'screenfull';
 
 import {SecondaryButton} from '@workday/canvas-kit-react/button';
+import {useIsFullscreen} from '@workday/canvas-kit-react/common';
+import {Flex} from '@workday/canvas-kit-react/layout';
 import {
   Popup,
   useCloseOnEscape,
+  useCloseOnFullscreenExit,
   useCloseOnOutsideClick,
   useFocusTrap,
   useInitialFocus,
-  useReturnFocus,
   usePopupModel,
-  useCloseOnFullscreenExit,
-  useTransferOnFullscreenExit,
+  useReturnFocus,
   useTransferOnFullscreenEnter,
+  useTransferOnFullscreenExit,
 } from '@workday/canvas-kit-react/popup';
-import {Flex} from '@workday/canvas-kit-react/layout';
-import {useIsFullscreen} from '@workday/canvas-kit-react/common';
-import screenfull from 'screenfull';
 
 const SelfClosePopup = () => {
   const model = usePopupModel();