@workday/canvas-kit-docs 12.0.0-alpha.855-next.0 → 12.0.0-alpha.898-next.0

package/dist/mdx/react/_examples/mdx/examples/common/VisibleLiveRegion.tsx

@@ -0,0 +1,40 @@
+import React, {useState, useRef} from 'react';
+import {AriaLiveRegion} from '@workday/canvas-kit-react/common';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {TextInput} from '@workday/canvas-kit-preview-react/text-input';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {Text} from '@workday/canvas-kit-react/text';
+import {system, base} from '@workday/canvas-tokens-web';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+
+const liveRegionStyle = createStyles({
+  border: `${px2rem(1)} solid ${base.cantaloupe400}`,
+  backgroundColor: base.cantaloupe100,
+  padding: system.space.x4,
+  display: 'block',
+  margin: system.space.x4 + ' 0',
+});
+
+export default () => {
+  const [message, setMessage] = useState('This is an ARIA Live Region!');
+  const inputRef = useRef();
+  function handleSendMessage() {
+    setMessage(inputRef.current.value);
+    inputRef.current.value = '';
+  }
+
+  return (
+    <>
+      <AriaLiveRegion>
+        <Text cs={liveRegionStyle}>{message}</Text>
+      </AriaLiveRegion>
+      <Flex gap={`var(${system.space.x4})`} alignItems="flex-end">
+        <TextInput orientation="vertical">
+          <TextInput.Label>Type your message:</TextInput.Label>
+          <TextInput.Field ref={inputRef} />
+        </TextInput>
+        <PrimaryButton onClick={handleSendMessage}>Send Message</PrimaryButton>
+      </Flex>
+    </>
+  );
+};

package/dist/mdx/react/action-bar/ActionBar.mdx

@@ -1,14 +1,10 @@
-import {SymbolDoc, Specifications} from '@workday/canvas-kit-docs';
-
-import {ActionBar} from '@workday/canvas-kit-react/action-bar';
-
+import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
 import Basic from './examples/Basic';
 import Icons from './examples/Icons';
 import DeleteAction from './examples/DeleteAction';
 import OverflowActionBar from './examples/OverflowActionBar';
 import OverflowActionBarCustomButtonCount from './examples/OverflowActionBarCustomButtonCount';
 
-
 # Canvas Kit Action Bar
 
 Action Bar is a [compound component](/getting-started/for-developers/resources/compound-components/)

package/dist/mdx/react/action-bar/examples/Basic.tsx

@@ -2,13 +2,15 @@ import React from 'react';
 import {ActionBar} from '@workday/canvas-kit-react/action-bar';
 import {PrimaryButton} from '@workday/canvas-kit-react/button';
 
-export default () => (
-  <ActionBar>
-    <ActionBar.List position="relative" as="section" aria-label="Basic example actions">
-      <ActionBar.Item as={PrimaryButton} onClick={() => console.log('first action')}>
-        First Action
-      </ActionBar.Item>
-      <ActionBar.Item>Second Action</ActionBar.Item>
-    </ActionBar.List>
-  </ActionBar>
-);
+export default () => {
+  return (
+    <ActionBar>
+      <ActionBar.List position="relative" as="section" aria-label="Basic example actions">
+        <ActionBar.Item as={PrimaryButton} onClick={() => console.log('first action')}>
+          First Action
+        </ActionBar.Item>
+        <ActionBar.Item>Second Action</ActionBar.Item>
+      </ActionBar.List>
+    </ActionBar>
+  );
+};

package/dist/mdx/react/action-bar/examples/OverflowActionBar.tsx

@@ -54,16 +54,19 @@ export default () => {
           </ActionBar.Menu.Popper>
         </ActionBar>
       </Box>
-      <hr />
-      <h4>Change Action Bar container size</h4>
-      <SegmentedControl onSelect={data => setContainerWidth(data.id)}>
-        <SegmentedControl.List aria-label="container width control" marginBottom="m">
-          <SegmentedControl.Item data-id="100%">100%</SegmentedControl.Item>
-          <SegmentedControl.Item data-id={`${breakpoints.m}px`}>Small</SegmentedControl.Item>
-          <SegmentedControl.Item data-id="420px">420px</SegmentedControl.Item>
-          <SegmentedControl.Item data-id={`${breakpoints.s}px`}>Extra Small</SegmentedControl.Item>
-        </SegmentedControl.List>
-      </SegmentedControl>
+      <footer>
+        <h4>Change Action Bar container size</h4>
+        <SegmentedControl onSelect={data => setContainerWidth(data.id)}>
+          <SegmentedControl.List role="group" aria-label="container width control" marginBottom="m">
+            <SegmentedControl.Item data-id="100%">100%</SegmentedControl.Item>
+            <SegmentedControl.Item data-id={`${breakpoints.m}px`}>Small</SegmentedControl.Item>
+            <SegmentedControl.Item data-id="420px">420px</SegmentedControl.Item>
+            <SegmentedControl.Item data-id={`${breakpoints.s}px`}>
+              Extra Small
+            </SegmentedControl.Item>
+          </SegmentedControl.List>
+        </SegmentedControl>
+      </footer>
     </div>
   );
 };

package/dist/mdx/react/action-bar/examples/index.ts

@@ -0,0 +1,5 @@
+export {Basic} from './Basic';
+export {DeleteAction} from './DeleteAction';
+export {Icons} from './Icons';
+export {OverflowActionBar} from './OverflowActionBar';
+export {OverflowActionBarCustomButtonCount} from './OverflowActionBarCustomButtonCount';

package/dist/mdx/react/avatar/avatar/Avatar.mdx

@@ -0,0 +1,95 @@
+import {Specifications, SymbolDoc, SymbolDescription, ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import Basic from './examples/Basic';
+import Button from './examples/Button';
+import Image from './examples/Image';
+import LazyLoad from './examples/LazyLoad';
+import ObjectFit from './examples/ObjectFit';
+import Size from './examples/Size';
+import Variant from './examples/Variant';
+import CustomStyles from './examples/CustomStyles';
+
+import * as AvatarStories from './Avatar.stories'
+
+
+# Canvas Kit Avatar
+
+Represents a person's profile.
+
+[> Workday Design Reference](https://canvas.workdaydesign.com/components/indicators/avatar)
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-react
+```
+
+## Usage
+
+<SymbolDescription name="Avatar" fileName="/react/" />
+
+The example below shows multiple instances of a `Avatar` with various configurations.
+
+### Basic
+
+By default, the Avatar renders a `button` element. If yo'd like to change the default element, use
+the `as` prop.
+
+<ExampleCodeBlock code={Basic} />
+
+### Button
+
+Like many of our components, Avatar accepts an `as` prop, which lets you change the underlying
+semantic element to a `div`. This should be done with caution to ensure the best accessibility.
+Generally, `<button>` elements should be used for actions.
+
+<ExampleCodeBlock code={Button} />
+
+### Variant
+
+Avatar defaults to using a `"light"` `variant` property. You can change the `variant` prop to "dark"
+by including `variant="dark"`.
+
+<ExampleCodeBlock code={Variant} />
+
+### Size
+
+Avatar defaults to using a `"medium"` `size` property. You can change the `size` prop to various
+sizing options. See Component API for more details.
+
+Additionally, you can explicitly specify the size you want for the Avatar in pixels or rems.
+
+<ExampleCodeBlock code={Size} />
+
+### Image
+
+Avatar renders an image when the `url` prop is defined.
+
+<ExampleCodeBlock code={Image} />
+
+### Object Fit
+
+Avatar defaults to using `contain` for object-fit. You can change this property to any other
+acceptable `object-fit` properties. For best fit, try to use square images.
+
+<ExampleCodeBlock code={ObjectFit} />
+
+### Lazy Load
+
+Example of implementing lazy load behavior with Avatar.
+
+<ExampleCodeBlock code={LazyLoad} />
+
+### Custom Styling
+
+To change the background color of the Avatar, you can use our `createStencil` functionality.
+
+<ExampleCodeBlock code={CustomStyles} />
+
+## Component API
+
+<SymbolDoc name="Avatar" fileName="/react/" />
+
+## Specifications
+
+<Specifications file="Avatar.spec.ts" name="Avatar" />

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

@@ -0,0 +1,18 @@
+import React from 'react';
+import {Avatar} from '@workday/canvas-kit-react/avatar';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const handleAvatarButtonClick = () => console.log('AvatarButton clicked');
+
+const containerStyles = createStyles({
+  display: 'inline-flex',
+  gap: system.space.x2,
+});
+
+export default () => (
+  <div className={containerStyles}>
+    <Avatar onClick={handleAvatarButtonClick} />
+    <Avatar as="div" />
+  </div>
+);

package/dist/mdx/react/avatar/avatar/examples/Button.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import {Avatar} from '@workday/canvas-kit-react/avatar';
+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 handleAvatarButtonClick = () => console.log('AvatarButton clicked');
+
+const containerStyles = createStyles({
+  display: 'inline-flex',
+  gap: system.space.x2,
+});
+
+export default () => (
+  <div className={containerStyles}>
+    <Avatar variant="dark" onClick={handleAvatarButtonClick} />
+    <Avatar onClick={handleAvatarButtonClick} />
+    <Avatar url={testAvatar} onClick={handleAvatarButtonClick} />
+  </div>
+);

package/dist/mdx/react/avatar/avatar/examples/CustomStyles.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import {Avatar} from '@workday/canvas-kit-react/avatar';
+import {createStencil, createStyles} from '@workday/canvas-kit-styling';
+import {base, system} from '@workday/canvas-tokens-web';
+import {systemIconStencil} from '../../../../icon';
+
+const customBlueAvatarStencil = createStencil({
+  base: {
+    backgroundColor: base.berrySmoothie400,
+    ['[data-part="avatar-icon"]']: {
+      [systemIconStencil.vars.color]: base.berrySmoothie100,
+    },
+  },
+});
+
+const customGreenAvatarStencil = createStencil({
+  base: {
+    backgroundColor: base.watermelon400,
+    ['[data-part="avatar-icon"]']: {
+      [systemIconStencil.vars.color]: base.watermelon100,
+    },
+  },
+});
+
+const containerStyles = createStyles({
+  display: 'inline-flex',
+  gap: system.space.x2,
+});
+
+export default () => (
+  <div className={containerStyles}>
+    <Avatar as="div" {...customBlueAvatarStencil()} />
+    <Avatar as="div" {...customGreenAvatarStencil()} />
+  </div>
+);

package/dist/mdx/react/avatar/avatar/examples/Image.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import {Avatar} from '@workday/canvas-kit-react/avatar';
+// @ts-ignore: Cannot find module error
+import testAvatar from './test-avatar.png';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const containerStyles = createStyles({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: system.space.x2,
+});
+
+export default () => (
+  <div className={containerStyles}>
+    <h3>Working Images</h3>
+    <Avatar size="extraExtraLarge" as="div" url={testAvatar} />
+    <Avatar size="extraLarge" as="div" url={testAvatar} />
+    <Avatar size="large" as="div" url={testAvatar} />
+    <Avatar size="medium" as="div" url={testAvatar} />
+    <Avatar size="small" as="div" url={testAvatar} />
+    <Avatar size="extraSmall" as="div" url={testAvatar} />
+    <h3>Broken Image</h3>
+    <Avatar url="/fake/path/to/image.png" as="div" />
+  </div>
+);

package/dist/mdx/react/avatar/avatar/examples/LazyLoad.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import {Avatar} from '@workday/canvas-kit-react/avatar';
+// @ts-ignore: Cannot find module error
+import testAvatar from './test-avatar.png';
+
+export default () => (
+  <div className="story">
+    {Array.from({length: 5}, (v, index) => (
+      <>
+        <Avatar key={index} as="div" size="medium" url={testAvatar + '?v=' + index} />
+        <br />
+      </>
+    ))}
+  </div>
+);

package/dist/mdx/react/avatar/avatar/examples/ObjectFit.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import {Avatar} from '@workday/canvas-kit-react/avatar';
+import {px2rem} from '@workday/canvas-kit-styling';
+
+export default () => (
+  <div className="story">
+    <h3>Original Rectangle Image</h3>
+    <img alt="" src="https://picsum.photos/id/237/300/200" />
+    <h3>Object fit on a Rectangle Image</h3>
+    <Avatar as="div" url="https://picsum.photos/id/237/300/200" />
+    <h3>Object fit on a Rectangle Image using Dynamic Size</h3>
+    <Avatar
+      as="div"
+      size={px2rem(200)}
+      url="https://picsum.photos/id/237/300/200"
+      objectFit="contain"
+    />
+    <h3>Original Square Image</h3>
+    <img alt="" src="https://picsum.photos/id/237/300/300" />
+    <h3>Object fit on a Square Image</h3>
+    <Avatar as="div" url="https://picsum.photos/id/237/300/300" />
+    <h3>Object fit on a Square Image using Dynamic Size</h3>
+    <Avatar as="div" size={px2rem(200)} url="https://picsum.photos/id/237/300/300" />
+  </div>
+);

package/dist/mdx/react/avatar/avatar/examples/Size.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import {Avatar} from '@workday/canvas-kit-react/avatar';
+import {px2rem} from '@workday/canvas-kit-styling';
+
+export default () => (
+  <div className="story">
+    <h3>Extra-Extra Large</h3>
+    <Avatar as="div" size="extraExtraLarge" />
+    <h3>Extra Large</h3>
+    <Avatar as="div" size="extraLarge" />
+    <h3>Large</h3>
+    <Avatar as="div" size="large" />
+    <h3>Medium</h3>
+    <Avatar as="div" size="medium" />
+    <h3>Small</h3>
+    <Avatar as="div" size="small" />
+    <h3>Extra Small</h3>
+    <Avatar as="div" size="extraSmall" />
+    <h3>30px</h3>
+    <Avatar as="div" size={px2rem(30)} />
+    <h3>40px</h3>
+    <Avatar as="div" size={px2rem(40)} />
+    <h3>3rem</h3>
+    <Avatar as="div" size="3rem" />
+    <h3>4rem</h3>
+    <Avatar as="div" size="4rem" />
+  </div>
+);

package/dist/mdx/react/avatar/avatar/examples/Variant.tsx

@@ -0,0 +1,11 @@
+import React from 'react';
+import {Avatar} from '@workday/canvas-kit-react/avatar';
+
+export default () => (
+  <div className="story">
+    <h3>Light</h3>
+    <Avatar as="div" size="medium" />
+    <h3>Dark</h3>
+    <Avatar as="div" size="medium" variant="dark" />
+  </div>
+);

package/dist/mdx/react/badge/CountBadge.mdx

@@ -1,6 +1,4 @@
-import {SymbolDoc} from '@workday/canvas-kit-docs';
-
-import {CountBadge} from '@workday/canvas-kit-react/badge';
+import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
 
 import Basic from './examples/Basic';
 import CustomLimit from './examples/CustomLimit';
@@ -42,10 +40,20 @@ messages on their first day back.
 
 ### Notification Badge
 
-Notifications are a major use case for `CountBadge`. Remember that any `CountBadge` with a
-live-updating value should be announced to screen readers with an `aria-live` region and an
-`aria-label` on the button to provide additional context, as in the example below. Please also read
-the Accessibility guidance below this example for aditional information.
+Notifications are a major use case for `CountBadge`. When the `CountBadge` value is updated in
+real-time, screen readers must be supported with an `AriaLiveRegion` that will automatically
+describe the change in the number of notifications. If the web app only updates `CountBadge` as part
+of another screen update, then this use of `AriaLiveRegion` is unnecessary and not recommended.
+
+#### Notes on accessibility for the example below
+
+- `Tooltip` is set on the `SecondaryButton` automatically applying the `aria-label` to the button.
+- `aria-describedby` property is conditionally set on the `SecondaryButton` when greater than zero
+  referencing a unique `id` for the `CountBadge` value .
+- `AriaLiveRegion` is used around the `CountBadge`, enabling screen readers to monitor changes in
+  value.
+- `aria-label` string is conditionally set on `AriaLiveRegion` when greater than zero, describing
+  "New notification"
 
 <ExampleCodeBlock code={NotificationBadge} />
 
@@ -54,17 +62,6 @@ the Accessibility guidance below this example for aditional information.
 Count Badge supports custom styling via the `cs` prop. For more information, check our
 ["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-how-to-customize-styles--page).
 
-## Accessibility
-
-A common use case for `CountBadge` is displaying notifications, but there are other situations where
-they will have live-updated values. There are several accessibility concerns you'll want to keep in
-mind:
-
-- The button should have an aria-label that updates with the count
-- The elements inside the button should have `aria-hidden`
-- The live region should be outside the button
-- The live region should be visually hidden and only contain text
-
 ## Component API
 
 <SymbolDoc name="CountBadge" fileName="/react/" />

package/dist/mdx/react/badge/examples/NotificationBadge.tsx

@@ -1,10 +1,12 @@
 import * as React from 'react';
 import {CountBadge} from '@workday/canvas-kit-react/badge';
 import {SecondaryButton, TertiaryButton} from '@workday/canvas-kit-react/button';
-import {accessibleHide} from '@workday/canvas-kit-react/common';
+import {AriaLiveRegion, useUniqueId} from '@workday/canvas-kit-react/common';
 import {createStyles, cssVar} from '@workday/canvas-kit-styling';
 import {notificationsIcon} from '@workday/canvas-system-icons-web';
 import {base, system} from '@workday/canvas-tokens-web';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {Flex} from '@workday/canvas-kit-react/layout';
 
 function negate(value: string, fallback?: string) {
   return `calc(${cssVar(value, fallback)} * -1)`;
@@ -12,16 +14,13 @@ function negate(value: string, fallback?: string) {
 
 const container = createStyles({
   boxSizing: 'border-box',
-  display: 'flex',
   flexDirection: 'column',
   gap: system.space.x4,
 });
 
 const controls = createStyles({
   boxSizing: 'border-box',
-  borderBottom: `solid 1px ${cssVar(base.soap400)}`,
-  display: 'flex',
-  gap: system.space.x1,
+  gap: system.space.x2,
   padding: system.space.x1,
 });
 
@@ -33,40 +32,46 @@ const notificationContainerStyles = createStyles({
 const countBadgeStyles = createStyles({
   boxSizing: 'border-box',
   position: 'absolute',
-  top: negate(system.space.x4),
+  top: negate(system.space.x1),
   insetInlineEnd: negate(system.space.x1),
 });
 
-const accessibleHideStyles = createStyles(accessibleHide);
-
+// Testing notes (Aug. 30, 2024):
+// Windows 11
+// JAWS 2024 + Chrome / Edge: "New notifications" once, then only the count change "2"
+// JAWS 2024 + FF: "New notifications" once, then describes nothing
+// NVDA + Chrome / Edge: Consistently describes "{X} New notifications"
+// NVDA + FF: Consistently describes count value only "{X}"
+// macOS v14.6.1
+// VoiceOver + Chrome / Safari: Consistently describes "New notifications {X}"
 export function NotificationBadge() {
   const [count, setCount] = React.useState(4);
+  const badgeID = useUniqueId();
 
   return (
-    <div className={container}>
-      <div className={controls}>
+    <Flex cs={container}>
+      <Flex cs={controls}>
         <TertiaryButton size="small" onClick={() => setCount(count + 1)}>
           Add Notification
         </TertiaryButton>
         <TertiaryButton size="small" onClick={() => setCount(0)}>
           Clear
         </TertiaryButton>
-      </div>
-      <div>
+      </Flex>
+      <Flex>
         <span className={notificationContainerStyles}>
-          <SecondaryButton
-            aria-label={`Alerts ${count} new notifications`}
-            size="medium"
-            icon={notificationsIcon}
-          />
-          {!!count && (
-            <CountBadge count={count} limit={100} aria-hidden="true" cs={countBadgeStyles} />
-          )}
-          <div className={accessibleHideStyles} role="status" aria-live="polite" aria-atomic="true">
-            New notifications
-          </div>
+          <Tooltip title="Notifications">
+            <SecondaryButton
+              size="medium"
+              icon={notificationsIcon}
+              aria-describedby={!!count ? badgeID : undefined}
+            />
+          </Tooltip>
+          <AriaLiveRegion aria-label={!!count ? 'New notifications' : undefined}>
+            {!!count && <CountBadge id={badgeID} count={count} limit={100} cs={countBadgeStyles} />}
+          </AriaLiveRegion>
         </span>
-      </div>
-    </div>
+      </Flex>
+    </Flex>
   );
 }

package/dist/mdx/react/banner/Banner.mdx

@@ -1,7 +1,4 @@
-import {SymbolDoc} from '@workday/canvas-kit-docs';
-
-import {Banner} from '@workday/canvas-kit-react/banner';
-
+import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
 import ActionText from './examples/ActionText';
 import Basic from './examples/Basic';
 import Error from './examples/Error';
@@ -51,7 +48,8 @@ banner. This will change the defualt icon to `exclamationCircleIcon`.
 
 ### Icon Banner
 
-When only using an icon in the `Banner`, use our `Tooltip` component to both show a visible text alternative, and assign an `aria-label` string to the child `Banner`.
+When only using an icon in the `Banner`, use our `Tooltip` component to both show a visible text
+alternative, and assign an `aria-label` string to the child `Banner`.
 
 <ExampleCodeBlock code={IconBanner} />
 

package/dist/mdx/react/breadcrumbs/Breadcrumbs.mdx

@@ -1,14 +1,10 @@
-import {SymbolDoc, Specifications} from '@workday/canvas-kit-docs';
-
-import {Breadcrumbs} from '@workday/canvas-kit-react/breadcrumbs';
-
+import {ExampleCodeBlock, SymbolDoc, Specifications} from '@workday/canvas-kit-docs';
 import Basic from './examples/Basic';
 import OverflowBreadcrumbs from './examples/Overflow';
 import RTLOverflowList from './examples/RTL';
 import CurrentItemTruncation from './examples/CurrentItemTruncation';
 import LinkTruncation from './examples/LinkTruncation';
 
-
 # Canvas Kit Breadcrumbs
 
 Breadcrumbs is a

package/dist/mdx/react/button/button/Button.mdx

@@ -1,4 +1,9 @@
-import {Specifications, SymbolDoc, SymbolDescription} from '@workday/canvas-kit-docs';
+import {
+  ExampleCodeBlock,
+  Specifications,
+  SymbolDoc,
+  SymbolDescription,
+} from '@workday/canvas-kit-docs';
 
 import Primary from './examples/Primary';
 import PrimaryInverse from './examples/PrimaryInverse';

package/dist/mdx/react/button/button/Hyperlink.mdx

@@ -1,7 +1,4 @@
-import {SymbolDoc, Specifications} from '@workday/canvas-kit-docs';
-
-import {Hyperlink, ExternalHyperlink} from '@workday/canvas-kit-react/button';
-
+import {ExampleCodeBlock, Specifications, SymbolDoc} from '@workday/canvas-kit-docs';
 import Link from './examples/Hyperlink';
 import LinkInverse from './examples/HyperlinkInverse';
 import ExternalLink from './examples/ExternalHyperlink';