@workday/canvas-kit-docs 11.1.8 → 11.1.9

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

@@ -42,10 +42,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 +64,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "11.1.8",
+  "version": "11.1.9",
   "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.1.8",
-    "@workday/canvas-kit-preview-react": "^11.1.8",
-    "@workday/canvas-kit-react": "^11.1.8",
-    "@workday/canvas-kit-styling": "^11.1.8",
+    "@workday/canvas-kit-labs-react": "^11.1.9",
+    "@workday/canvas-kit-preview-react": "^11.1.9",
+    "@workday/canvas-kit-react": "^11.1.9",
+    "@workday/canvas-kit-styling": "^11.1.9",
     "@workday/canvas-system-icons-web": "^3.0.0",
     "@workday/canvas-tokens-web": "^2.0.0",
     "markdown-to-jsx": "^7.2.0",
@@ -59,5 +59,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "4.2"
   },
-  "gitHead": "6a3bca7c56f654e282109430f4918d5bc89f2d21"
+  "gitHead": "c81e8e0bef16f336966043e58a3c119dbab19617"
 }

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

@@ -1,98 +0,0 @@
-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>
-    </>
-  );
-};