@workday/canvas-kit-docs 11.0.0-alpha.766-next.0 → 11.0.0-alpha.769-next.0

package/dist/mdx/11.0-UPGRADE-GUIDE.mdx

@@ -26,6 +26,7 @@ any questions.
   - [Count Badge](#count-badge)
   - [Form Field Preview](#form-field-preview)
   - [Icons](#icons)
+  - [Loading Dots](#loading-dots)
   - [Radio (Preview)](#radio-preview)
   - [Select](#select)
   - [Switch](#switch)
@@ -680,6 +681,15 @@ const MyComponent = StyledRadioButton('div')({
 </MyComponent>;
 ```
 
+### Loading Dots
+
+`LoadingDots` now uses
+[Canvas Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) and
+our
+[new styling utilities](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--create-modifiers#createstyles-api).
+The component now supports the `cs` prop, but otherwise the API has not changed. It should behave
+identically as it did in previous versions.
+
 ### Radio (Preview)
 
 **PR:** [#2546](https://github.com/Workday/canvas-kit/pull/2546)

package/dist/mdx/react/_examples/AriaLiveRegions.mdx

@@ -0,0 +1,75 @@
+import {AriaLiveRegion} from '@workday/canvas-kit-react/common';
+import FilterListWithLiveStatus from './examples/common/FilterListWithLiveStatus';
+import VisibleLiveRegion from './examples/common/VisibleLiveRegion';
+import HiddenLiveRegion from './examples/common/HiddenLiveRegion';
+import TextInputWithLiveError from './examples/common/TextInputWithLiveError';
+import IconButtonsWithLiveBadges from './examples/common/IconButtonsWithLiveBadges';
+
+
+# ARIA Live Regions
+
+These examples are provided to demonstrate a variety of different use cases for the `AriaLiveRegion`
+component. For the full experience, get started by first turning on your favorite screen reading
+software. On Windows, we recommend the open source
+[NVDA (Non-Visual Desktop Access)](https://www.nvaccess.org/download/) software, or
+[JAWS (Job Access With Speech)](https://support.freedomscientific.com/Downloads/JAWS) if you have
+purchased a license. MacOS and iOS include VoiceOver, which can be turned on in your settings.
+
+Live regions work by designating specific DOM nodes for screen readers to monitor for any content
+updates inside the node. When an update occurs, screen readers will announce the update to users in
+real time, based on a few rules:
+
+1. `polite` will “politely” wait for users to finish what they are doing before announcing an update
+2. `assertive` will interrupt what users are doing (or reading) by immediately announcing an update
+
+### CAUTION: Don't get carried away
+
+Key things to understand about live regions:
+
+1. A live region update will only be announced once. Users are unable to repeat them or re-examine
+   them if the announcement was not understood.
+2. Users may be able to pause a live region announcement, but they cannot prevent a live region
+   announcement from occurring. Sending frequent, repetitive, or simply too much information to a
+   live region can be very disruptive to users.
+3. Users cannot act on, or navigate to, a live region. Live regions must only contain plain text.
+   (No images, links, buttons, or other input.)
+4. Support for live regions is limited across platforms, browsers, and screen reader software. Real
+   time announcements may not be perfectly reliable.
+
+## Visible Live Regions
+
+Live regions can be applied to dynamic text on the UI. When the dynamic text is updated, screen
+readers can describe the text update in live time as it occurs. In the example below, type text into
+the input field and activate the "Send Message" button. Listen and observe the screen reader
+automatically announce the text update.
+
+<ExampleCodeBlock code={VisibleLiveRegion} />
+
+## Hidden Live Regions
+
+Live regions don't need to be visible UI text, they can be used to assist the non-visual listening
+experience when moving the keyboard focus to a new element on screen isn't feasible.
+
+<ExampleCodeBlock code={HiddenLiveRegion} />
+
+## Filtering lists with a live status
+
+In this example, a live region is applied to a short UI text describing the number of items shown in
+the list. As you type characters into the input, listen for the screen reader to automatically
+describe how many items in the list or shown.
+
+<ExampleCodeBlock code={FilterListWithLiveStatus} />
+
+## Text input with live inline error
+
+In this example, a live region is applied to the inline error message that will appear below the
+text input. Listen for the screen reader to automatically describe the error message as you leave
+the input field blank.
+
+**Note:** Use this example with discretion. Using live regions for automatically announcing form
+errors to screen reader users can be a nice experience for simple forms with a very limited number
+of error conditions. As forms increase in complexity, live regions on each error message can become
+increasingly distracting and disruptive to the experience, especially if users are trying to first
+understand the information that is required of them to complete the task.
+
+<ExampleCodeBlock code={TextInputWithLiveError} />

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

@@ -0,0 +1,65 @@
+import React, {useState} from 'react';
+import {TextInput} from '@workday/canvas-kit-preview-react/text-input';
+import {BodyText, Heading} from '@workday/canvas-kit-react/text';
+import {AriaLiveRegion} from '@workday/canvas-kit-react/common';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {system, base} from '@workday/canvas-tokens-web';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+
+const fruits = [
+  'Apples',
+  'Oranges',
+  'Bananas',
+  'Lemons',
+  'Limes',
+  'Strawberries',
+  'Raspberries',
+  'Blackberries',
+];
+
+const liveRegionStyle = createStyles({
+  border: `${px2rem(1)} solid ${base.cantaloupe400}`,
+  backgroundColor: base.cantaloupe100,
+  padding: system.space.x2,
+});
+
+const listStyles = {paddingLeft: '0px'};
+
+const listItemStyles = createStyles({
+  listStyle: 'none',
+  paddingLeft: system.space.zero,
+});
+
+let filteredFruits = fruits;
+
+export default () => {
+  const [filter, setFilter] = useState('');
+  function handleFilter(e) {
+    filteredFruits = fruits.filter(i => i.toUpperCase().indexOf(e.target.value.toUpperCase()) >= 0);
+    setFilter(e.target.value);
+  }
+
+  return (
+    <>
+      <Flex gap="1rem">
+        <Heading size="small">Fruits</Heading>
+        <AriaLiveRegion>
+          <BodyText size="small" cs={liveRegionStyle}>
+            {`Showing ${filteredFruits.length} of ${fruits.length}`}
+          </BodyText>
+        </AriaLiveRegion>
+      </Flex>
+      <TextInput orientation="vertical">
+        <TextInput.Label>Filter Items:</TextInput.Label>
+        <TextInput.Field value={filter} onChange={handleFilter} />
+      </TextInput>
+      <ul style={listStyles}>
+        {filteredFruits.map(i => (
+          <BodyText size="small" as="li" cs={listItemStyles} key={i}>
+            {i}
+          </BodyText>
+        ))}
+      </ul>
+    </>
+  );
+};

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

@@ -0,0 +1,30 @@
+import React, {useState, useRef} from 'react';
+import {AriaLiveRegion, AccessibleHide} 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 {system} from '@workday/canvas-tokens-web';
+
+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 (
+    <>
+      <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>
+      <AriaLiveRegion>
+        <AccessibleHide>{message}</AccessibleHide>
+      </AriaLiveRegion>
+    </>
+  );
+};

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

@@ -0,0 +1,98 @@
+import React, {useState} from 'react';
+import {AccessibleHide, AriaLiveRegion, useUniqueId} from '@workday/canvas-kit-react/common';
+import {notificationsIcon, inboxIcon, assistantIcon} from '@workday/canvas-system-icons-web';
+import {space} from '@workday/canvas-kit-react/tokens';
+import {SecondaryButton, TertiaryButton} from '@workday/canvas-kit-react/button';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {CountBadge} from '@workday/canvas-kit-react/badge';
+
+const MyTasksLiveBadge = ({cnt}) => {
+  // use tooltip to assign name,
+  // use AriaLiveRegion inside button,
+  // assign name to live region referencing the button,
+  // use BadgeCount inside live region,
+  // use AccessibleHide to create invisible word "new" after badge
+  // use aria-describedby on button, referencing live region container to set description
+  // Safari + VO => not working at all
+  // JAWS 2024 + Chrome / Edge => works as expected :)
+  // NVDA + Chrome / Edge => works as expected :)
+  // Firefox => isn't announcing description on focus, only announces "X New" live (missing button name)
+  const badgeID = useUniqueId();
+  const myTasksID = useUniqueId();
+
+  return (
+    <Tooltip title="My Tasks">
+      <TertiaryButton icon={inboxIcon} id={myTasksID} aria-describedby={badgeID}>
+        <AriaLiveRegion id={badgeID} aria-labelledby={myTasksID}>
+          <CountBadge count={cnt} />
+          <AccessibleHide>New</AccessibleHide>
+        </AriaLiveRegion>
+      </TertiaryButton>
+    </Tooltip>
+  );
+};
+
+// use AriaLiveRegion around the button,
+// use Tooltip to assign the name of the button,
+// make sure Tooltip title string includes count value
+// Chrome + VO => Announces name "notifications X new" and innerText 'X'
+// Safari + VO => Works as expected :)
+// JAWS 2024 => Announces full button name twice (previous state, then new state)
+// JAWS 2024 + Firefox => Works as expected :)
+// NVDA (All Browsers) => Atomic property isn't working, only announcing number change, announces twice
+const NotificationsLiveBadge = ({cnt}) => (
+  <AriaLiveRegion>
+    <Tooltip title={`Notifications ${cnt} new`}>
+      <TertiaryButton icon={notificationsIcon}>
+        <CountBadge count={cnt} />
+      </TertiaryButton>
+    </Tooltip>
+  </AriaLiveRegion>
+);
+
+const AssistantLiveBadge = ({cnt}) => {
+  // use AriaLiveRegion around the button
+  // use muted type Tooltip (avoid using aria-label to name button)
+  // use AccessibleHide inside of button to compose name
+  // Chrome + VO => announces twice
+  // Safari + VO => works as expected :)
+  const lbl = 'Workday Assistant';
+
+  return (
+    <AriaLiveRegion>
+      <Tooltip title={lbl} type="muted">
+        <TertiaryButton icon={assistantIcon}>
+          <AccessibleHide>{lbl}</AccessibleHide>
+          <CountBadge count={cnt} />
+          <AccessibleHide>New</AccessibleHide>
+        </TertiaryButton>
+      </Tooltip>
+    </AriaLiveRegion>
+  );
+};
+
+export default () => {
+  const [counter, setCounter] = useState(0);
+  const [notifications, setNotifications] = useState(0);
+  const [assistant, setAssistant] = useState(0);
+
+  const handleAddTask = () => setCounter(prev => prev + 1);
+  const handleAddNotification = () => setNotifications(prev => prev + 1);
+  const handleAssistant = () => setAssistant(prev => prev + 1);
+
+  return (
+    <>
+      <Flex padding={space.s} gap={space.s} as="header">
+        <AssistantLiveBadge cnt={assistant} />
+        <NotificationsLiveBadge cnt={notifications} />
+        <MyTasksLiveBadge cnt={counter} />
+      </Flex>
+      <Flex padding={space.s} gap={space.s} as="main">
+        <SecondaryButton onClick={handleAssistant}>Add a Message</SecondaryButton>
+        <SecondaryButton onClick={handleAddNotification}>Add a Notification</SecondaryButton>
+        <SecondaryButton onClick={handleAddTask}>Add an item to My Tasks</SecondaryButton>
+      </Flex>
+    </>
+  );
+};

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

@@ -0,0 +1,25 @@
+import React, {useState, useRef} from 'react';
+import {TextInput} from '@workday/canvas-kit-preview-react/text-input';
+import {AriaLiveRegion, changeFocus} from '@workday/canvas-kit-react/common';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+export default () => {
+  const errMsg = 'Error: First name is required.';
+  const [hasError, setHasError] = useState(false);
+  const inputRef = useRef();
+  const handleBlur = e => setHasError(e.target.value.trim().length === 0);
+  const handleSubmit = () => hasError && changeFocus(inputRef.current);
+
+  return (
+    <>
+      <TextInput orientation="vertical" hasError={hasError} isRequired={true}>
+        <TextInput.Label>First Name:</TextInput.Label>
+        <TextInput.Field onBlur={handleBlur} ref={inputRef} />
+        <TextInput.Hint height={'16px'}>
+          <AriaLiveRegion>{hasError && errMsg}</AriaLiveRegion>
+        </TextInput.Hint>
+      </TextInput>
+      <PrimaryButton onClick={handleSubmit}>Continue</PrimaryButton>
+    </>
+  );
+};

package/dist/mdx/react/_examples/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/loading-dots/LoadingDots.mdx

@@ -28,7 +28,19 @@ yarn add @workday/canvas-kit-react
 
 <ExampleCodeBlock code={RTL} />
 
-### Accessible Example
+### Adding screen reader support to loading animations
+
+Sometimes, letting users know when content has finished loading is just as important as asking users
+to "please wait" while content is loading. The disappearance of an animation is information that
+might need description. In this example, we are using `AriaLiveRegion` and `AccessibleHide`
+components included in Canvas to describe both the appearance and disappearance of `LoadingDots`.
+
+- When idle, render an empty live region
+- When loading, render `LoadingDots` inside the live region,
+- When complete, render `AccessibleHide` inside the live region expressing "Complete!"
+- We can assign a name to `AriaLiveRegion` component by passing in `aria-label="Loading"`
+- We can declare `LoadingDots` a labeled graphic by passing `role="img"` and
+  `aria-label="Please wait..."` into the component
 
 <ExampleCodeBlock code={Accessible} />
 

package/dist/mdx/react/loading-dots/examples/Accessible.tsx

@@ -1,6 +1,44 @@
 import React from 'react';
 import {LoadingDots} from '@workday/canvas-kit-react/loading-dots';
+import {base, system} from '@workday/canvas-tokens-web';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {SecondaryButton} from '@workday/canvas-kit-react/button';
+import {createStyles, cssVar} from '@workday/canvas-kit-styling';
+import {AccessibleHide, AriaLiveRegion} from '@workday/canvas-kit-react/common';
+
+const loadingStyles = createStyles({
+  backgroundColor: base.licorice300,
+  padding: system.space.x3,
+});
 
 export default () => {
-  return <LoadingDots aria-live="polite" aria-label="Loading Users" />;
+  const [loadingState, setLoadingState] = React.useState('idle');
+
+  React.useEffect(() => {
+    const timer = setTimeout(() => {
+      if (loadingState === 'loading') {
+        setLoadingState('success');
+      }
+    }, 4000);
+
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [loadingState]);
+
+  const handleLoad = () => {
+    setLoadingState('loading');
+  };
+
+  return (
+    <Flex gap={cssVar(system.space.x4)}>
+      <SecondaryButton onClick={handleLoad}>Start</SecondaryButton>
+      <AriaLiveRegion aria-label="Loading">
+        {loadingState === 'loading' && (
+          <LoadingDots className={loadingStyles} role="img" aria-label="Please wait..." />
+        )}
+        {loadingState === 'success' && <AccessibleHide>Complete.</AccessibleHide>}
+      </AriaLiveRegion>
+    </Flex>
+  );
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "11.0.0-alpha.766-next.0",
+  "version": "11.0.0-alpha.769-next.0",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -44,10 +44,10 @@
   "dependencies": {
     "@emotion/styled": "^11.6.0",
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-labs-react": "^11.0.0-alpha.766-next.0",
-    "@workday/canvas-kit-preview-react": "^11.0.0-alpha.766-next.0",
-    "@workday/canvas-kit-react": "^11.0.0-alpha.766-next.0",
-    "@workday/canvas-kit-styling": "^11.0.0-alpha.766-next.0",
+    "@workday/canvas-kit-labs-react": "^11.0.0-alpha.769-next.0",
+    "@workday/canvas-kit-preview-react": "^11.0.0-alpha.769-next.0",
+    "@workday/canvas-kit-react": "^11.0.0-alpha.769-next.0",
+    "@workday/canvas-kit-styling": "^11.0.0-alpha.769-next.0",
     "@workday/canvas-system-icons-web": "^3.0.0",
     "@workday/canvas-tokens-web": "^1.3.0",
     "markdown-to-jsx": "^6.10.3",
@@ -59,5 +59,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "4.2"
   },
-  "gitHead": "a0883a359bb6af9d380b1e562662713b99fad4cc"
+  "gitHead": "6ccdc31e5c364c7a8a6f29f7b797032a914ca2c5"
 }