@workday/canvas-kit-docs 11.0.0-alpha.671-next.0 → 11.0.0-alpha.693-next.0

package/dist/es6/lib/specs.js

@@ -4345,6 +4345,10 @@ module.exports = {specifications: [
                 "type": "it",
                 "name": "should not have any axe errors"
               },
+              {
+                "type": "it",
+                "name": "should not have an aria-activedescendant attribute"
+              },
               {
                 "type": "describe",
                 "name": "when the select button is clicked",
@@ -4587,6 +4591,10 @@ module.exports = {specifications: [
                     "type": "describe",
                     "name": "when the menu is closed WITHOUT selecting the newly focused option (\"Phone\")",
                     "children": [
+                      {
+                        "type": "it",
+                        "name": "should not have an aria-activedescendant attribute"
+                      },
                       {
                         "type": "describe",
                         "name": "when the menu is re-opened AFTER it has fully closed",
@@ -4946,6 +4954,22 @@ module.exports = {specifications: [
             ]
           }
         ]
+      },
+      {
+        "type": "describe",
+        "name": "given the \"FetchingDynamicItems\" story is rendered",
+        "children": [
+          {
+            "type": "describe",
+            "name": "when Get Items is clicked",
+            "children": [
+              {
+                "type": "it",
+                "name": "should change the value of the select to 456 (the id) after 1.5 seconds"
+              }
+            ]
+          }
+        ]
       }
     ]
   },

package/dist/es6/mdx/versionsTable.d.ts

@@ -0,0 +1,2 @@
+export declare const VersionTable: () => JSX.Element;
+//# sourceMappingURL=versionsTable.d.ts.map

package/dist/es6/mdx/versionsTable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionsTable.d.ts","sourceRoot":"","sources":["../../../mdx/versionsTable.tsx"],"names":[],"mappings":"AA6DA,eAAO,MAAM,YAAY,mBAgCxB,CAAC"}

package/dist/es6/mdx/versionsTable.js

@@ -0,0 +1,76 @@
+import React from 'react';
+import { Table, StatusIndicator } from '@workday/canvas-kit-preview-react';
+// @ts-ignore: Cannot find module error
+import { version } from '../../../lerna.json';
+// When we release a new version, add the support version before the first item.
+const allVersions = [
+    {
+        versionNumber: version,
+        documentation: 'https://github.com/Workday/canvas-kit',
+    },
+    {
+        versionNumber: 9,
+        documentation: 'https://d2krrudi3mmzzw.cloudfront.net/v9/?path=/docs/welcome--page',
+    },
+    {
+        versionNumber: 8,
+        documentation: 'https://d2krrudi3mmzzw.cloudfront.net/v8/?path=/docs/welcome--page',
+    },
+    {
+        versionNumber: 7,
+        documentation: 'https://d2krrudi3mmzzw.cloudfront.net/v7/?path=/story/welcome-getting-started--page',
+    },
+    {
+        versionNumber: 6,
+        documentation: 'https://d2krrudi3mmzzw.cloudfront.net/v7/?path=/story/welcome-getting-started--page',
+    },
+];
+const statusIndicators = {
+    stable: {
+        variant: 'blue',
+        label: 'Stable',
+    },
+    support: {
+        variant: 'green',
+        label: 'Support',
+    },
+    deprecated: {
+        variant: 'red',
+        label: 'No Longer Supported',
+    },
+};
+function getVersionStatusIndicator(versionNumber) {
+    // version from lerna is a string, so we need to do modify into a number
+    const currentMajorVersion = Number(version.split('.')[0]);
+    const modifiedVersionNumber = typeof versionNumber === 'string' ? Number(versionNumber.split('.')[0]) : versionNumber;
+    // if this is the current version
+    if (modifiedVersionNumber === currentMajorVersion) {
+        return statusIndicators.stable;
+    }
+    else if (modifiedVersionNumber === currentMajorVersion - 1) {
+        return statusIndicators.support;
+    }
+    else {
+        return statusIndicators.deprecated;
+    }
+}
+export const VersionTable = () => {
+    return (React.createElement(Table, null,
+        React.createElement(Table.Head, null,
+            React.createElement(Table.Row, null,
+                React.createElement(Table.Header, { scope: "col" }, "Version"),
+                React.createElement(Table.Header, { scope: "col" }, "Documentation"),
+                React.createElement(Table.Header, { scope: "col" }, "Status"))),
+        React.createElement(Table.Body, null, allVersions.map(item => {
+            const { label, variant } = getVersionStatusIndicator(item.versionNumber);
+            return (React.createElement(Table.Row, null,
+                React.createElement(Table.Cell, null,
+                    "v",
+                    item.versionNumber),
+                React.createElement(Table.Cell, null,
+                    React.createElement("a", { href: item.documentation, target: "_blank", rel: "noreferrer" }, "Documentation")),
+                React.createElement(Table.Cell, null,
+                    React.createElement(StatusIndicator, { variant: variant },
+                        React.createElement(StatusIndicator.Label, null, label)))));
+        }))));
+};

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

@@ -18,6 +18,7 @@ any questions.
 - [Component Updates](#component-updates)
   - [Component Style Updates](#component-style-updates)
   - [Card](#card)
+  - [Checkbox](#checkbox)
   - [Count Badge](#count-badge)
   - [Form Field Preview](#form-field-preview)
   - [Radio (Preview)](#radio-preview)
@@ -345,6 +346,14 @@ See below:
 and [tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs). `Card`
 no longer extends the `Box` component, however, it still supports Emotion `styled` and style props.
 
+### Checkbox
+
+**PR:** [#2542](https://github.com/Workday/canvas-kit/pull/2542)
+
+`Checkbox` 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.
+
 ### Count Badge
 
 **PR:** [#2442](https://github.com/Workday/canvas-kit/pull/2442)
@@ -407,8 +416,11 @@ import {TextInput} from '@workday/canvas-kit-react/text-input';
 
 **PR:** [#2546](https://github.com/Workday/canvas-kit/pull/2546)
 
-`Radio` and `RadioGroup` now use [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
+`Radio` and `RadioGroup` now use
+[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.
 
 ### Text

package/dist/mdx/Versions.mdx

@@ -0,0 +1,8 @@
+import {VersionTable} from './versionsTable';
+
+
+## Released Versions
+
+Reference older versions documentation when needed.
+
+<VersionTable />

package/dist/mdx/preview-react/_examples/TablesAdvanced.mdx

@@ -0,0 +1,84 @@
+import {Table} from '@workday/canvas-kit-preview-react/table';
+
+import SelectableRows from './examples/Table/WithSelectableRows';
+import ExpandableRows from './examples/Table/WithExpandableRows';
+import SortableColumnHeaders from './examples/Table/WithSortableColumnHeaders';
+
+
+## Advanced Table Examples
+
+Out of the box, `Table` is a lightweight component with a high degree of flexibility, but not much
+functionality outside of providing a basic table layout. This leaves a gap for developers to
+implement common features, such as selecting rows and sorting columns, on top of `Table` to meet
+their specific application needs. During the development process, it's often unclear how to
+implement these features in an accessible way. In an effort to reduce that gap and increase clarity,
+we've documented several advanced examples below to communicate the accessibility nuances alongside
+tangible code snippets.
+
+### Expandable Rows
+
+Expandable Rows combines the likes of an accordion with tabular data tables. Column 1 renders icon
+buttons with 2 states, a collapsed and expanded state. A new row that spans the entire width of the
+table is added to the table just after the expanded row.
+
+- The `aria-expanded` property is added to the button to communicate this state to screen reader
+  users.
+- A Canvas accessible `Tooltip` component is used to assign names to each icon button based on the
+  most useful value in the row. In this example, we combined the car make and model together. This
+  allows everyone to view the name of the checkboxes by hovering the mouse or focusing with the
+  keyboard.
+- The expanded row uses `colspan` to span the entire width of the table and support screen readers.
+  This space provides flexibility to show headings, lists, and other structured content for the
+  table row above.
+- There is no explicit relationship between a row of cells, and the spanned content below it. The
+  spanned content is assumed to belong to the row of cells above it, based on established accordion
+  patterns and logical reading order of content rendered to the screen.
+- Outlining hierarchy in a data table is not supported for screen readers in this example.
+
+<ExampleCodeBlock code={ExpandableRows} />
+
+### Selectable Rows
+
+Developed by the Workday accessibility team, using a `Checkbox` labeled "Select All" inside of a table
+column header can be a confusing experience for screen reader users. Screen readers will
+automatically announce the "Select All" column header each time users are reading any cell in
+column 1. For instance, the `Checkbox` in row 4 is decidedly not going to select all of the rows. Here
+is what we did about it:
+
+- We intentionally rendered row 1, column 1 as a standard `<td>` element so screen readers won't
+  automatically announce "Select All" while reading cells in column 1.
+- Our research found that VoiceOver (MacOS v12.7, Safari v17.1) persistently announce "Select All"
+  despite using the `<td>` element because of the optional `<thead>` element in the table. We
+  omitted the optional `<thead>` and `<tbody>` elements from this example for that reason.
+- We used Canvas' accessible `Tooltip` component to assign names to each Checkbox based on the most
+  useful value in the row, the topping name. This allows everyone to view the name of the checkboxes
+  by hovering the mouse or focusing with the keyboard.
+- We rendered the cells in column 2 as the row headers for the table, enabling screen readers to
+  automatically announce the topping name even while reading down the Amounts in column 3. When we
+  rendered column 1 as row headers, then reading down column 2 (Topping Name) sounded redundant
+  because the `Checkbox` names in column 1 are identical to the Topping Name in column 2.
+
+<ExampleCodeBlock code={SelectableRows} />
+
+### Sortable Column Headers
+
+The challenge in this example is, how will we clearly communicate the complexity of the column
+headers to screen readers and keep the tabular data easy to understand? The column headers must
+describe the column name, the current sort state of the column, they are interactive (a button), and
+instructions about how the column will be sorted next. When screen reader users are focused on the
+tabular data cells, instructions about how the column will be sorted next is probably not relevant,
+distracting, and makes it harder to understand the data.
+
+- The `aria-sort` property has been initialized to `none` on each of the `<th>` elements; this value
+  is updated to `ascending` or `descending` to reflect the current state.
+- A `<button>` element describing the column name is used inside of the `<th>` column header.
+- The `describe` variant of the Canvas `Tooltip` component is applied to the button in the column
+  header. This is used to describe how the column will be sorted after interaction and applied to
+  the accessible description of the button with the `aria-describedby` property. This way screen
+  readers won't read the longer description of the column headers automatically while focusing on
+  the tabular data below.
+- The `aria-sort` property may not reliably provide the current sort state of the column to users
+  focused on the tabular data in the table. It may be more reliable to use an `aria-label` string on
+  the button that describes the column name and sort state together.
+
+<ExampleCodeBlock code={SortableColumnHeaders} />

package/dist/mdx/preview-react/_examples/examples/Table/WithExpandableRows.tsx

@@ -0,0 +1,219 @@
+import React from 'react';
+
+import {StatusIndicator} from '@workday/canvas-kit-preview-react/status-indicator';
+import {Table} from '@workday/canvas-kit-preview-react/table';
+import {TertiaryButton} from '@workday/canvas-kit-react/button';
+import {createComponent, generateUniqueId} from '@workday/canvas-kit-react/common';
+import {Heading, Subtext} from '@workday/canvas-kit-react/text';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {createStyles} from '@workday/canvas-kit-styling';
+
+import {chevronDownSmallIcon, chevronRightSmallIcon} from '@workday/canvas-system-icons-web';
+import {system} from '@workday/canvas-tokens-web';
+
+interface AutoData {
+  id: string;
+  brand: string;
+  model: string;
+  year: string;
+  price: string;
+  engine: string;
+  transmission: string;
+  horsepower: string;
+  torque: string;
+  curbWeight: string;
+  orderStatus: string;
+}
+
+const headingID = generateUniqueId();
+const autoData: AutoData[] = [
+  {
+    id: generateUniqueId(),
+    brand: 'Porsche',
+    model: '992 911 GT3',
+    year: '2022',
+    price: 'Starts at $160,000',
+    engine: '4.0L Flat 6',
+    transmission: 'PDK or 7-Speed Manual',
+    horsepower: '502hp',
+    torque: '346 lb-ft',
+    curbWeight: '3,164 lbs',
+    orderStatus: 'Order Placed',
+  },
+  {
+    id: generateUniqueId(),
+    brand: 'BMW',
+    model: 'M5 Competition',
+    year: '2018',
+    price: 'Starts at $105,000',
+    engine: 'Twin-Turbo 4.4L V8',
+    transmission: 'Automatic',
+    horsepower: '627hp',
+    torque: '553 lb-ft',
+    curbWeight: '4,345 lbs',
+    orderStatus: 'Order Fulfilled',
+  },
+  {
+    id: generateUniqueId(),
+    brand: 'Audi',
+    model: 'R8',
+    year: '2022',
+    price: 'Starts at $148,000',
+    engine: '5.2L V10',
+    transmission: 'Automatic',
+    horsepower: '562hp',
+    torque: '408 lb-ft',
+    curbWeight: '3,594 lbs',
+    orderStatus: 'Order Fulfilled',
+  },
+  {
+    id: generateUniqueId(),
+    brand: 'Lotus',
+    model: 'Emira',
+    year: '2023',
+    price: 'Starts at $78,000',
+    engine: 'Supercharged 3.5L V6',
+    transmission: 'Automatic or 6-Speed Manual',
+    horsepower: '400hp',
+    torque: '317 lb-ft',
+    curbWeight: '3520 lbs',
+    orderStatus: 'Shipped: In Transit',
+  },
+  {
+    id: generateUniqueId(),
+    brand: 'Toyota',
+    model: 'Supra',
+    year: '1998',
+    price: '$40,000 - $80,000',
+    engine: '3.0L Inline 6',
+    transmission: 'Automatic or 6-Speed Manual',
+    horsepower: '320hp',
+    torque: '315 lb-ft',
+    curbWeight: '3,599 lbs',
+    orderStatus: 'Delivered',
+  },
+  {
+    id: generateUniqueId(),
+    brand: 'Nissan',
+    model: 'Skyline GT-R',
+    year: '1994',
+    price: '$45,000 - $90,000',
+    engine: '2.6L Twin-Turbo Inline 6',
+    transmission: '5-Speed Manual',
+    horsepower: '276hp',
+    torque: '260 lb-ft',
+    curbWeight: '3,153 lbs',
+    orderStatus: 'Delivered',
+  },
+];
+
+interface RowProps {
+  data: AutoData;
+}
+
+const expandableSectionStyles = createStyles({
+  alignItems: 'flex-start',
+  display: 'flex',
+  gap: system.space.x4,
+  padding: system.space.x8,
+});
+
+const expandableHeadingStyles = createStyles({
+  margin: 0,
+  fontWeight: system.fontWeight.bold,
+});
+
+const expandableListStyles = createStyles({
+  listStyle: 'none',
+  margin: 0,
+  padding: 0,
+  gap: system.space.x2,
+});
+
+function ExpandableRow({data}: RowProps) {
+  const [rowExpanded, setRowExpanded] = React.useState(false);
+
+  return (
+    <>
+      <Table.Row gridTemplateColumns="4rem repeat(4, 1fr)">
+        <Table.Cell>
+          <Tooltip title={`${data.brand} ${data.model}`}>
+            <TertiaryButton
+              size="small"
+              icon={rowExpanded ? chevronDownSmallIcon : chevronRightSmallIcon}
+              aria-expanded={rowExpanded}
+              onClick={() => setRowExpanded(!rowExpanded)}
+            />
+          </Tooltip>
+        </Table.Cell>
+        <Table.Header scope="row">{data.brand}</Table.Header>
+        <Table.Cell>{data.model}</Table.Cell>
+        <Table.Cell>{data.year}</Table.Cell>
+        <Table.Cell>{data.price}</Table.Cell>
+      </Table.Row>
+      {rowExpanded && (
+        <Table.Row>
+          <Table.Cell colSpan={5} cs={expandableSectionStyles}>
+            <div>
+              <Subtext as="h4" size="large" cs={expandableHeadingStyles}>
+                Status
+              </Subtext>
+              <StatusIndicator variant="blue">{data.orderStatus}</StatusIndicator>
+            </div>
+            <div>
+              <Subtext as="h4" size="large" cs={expandableHeadingStyles}>
+                Specifications
+              </Subtext>
+              <ul className={expandableListStyles}>
+                <Subtext as="li" size="large">
+                  Engine: {data.engine}
+                </Subtext>
+                <Subtext as="li" size="large">
+                  Transmission: {data.transmission}
+                </Subtext>
+                <Subtext as="li" size="large">
+                  Horsepower: {data.horsepower}
+                </Subtext>
+                <Subtext as="li" size="large">
+                  Torque: {data.torque}
+                </Subtext>
+                <Subtext as="li" size="large">
+                  Curb Weight: {data.curbWeight}
+                </Subtext>
+              </ul>
+            </div>
+          </Table.Cell>
+        </Table.Row>
+      )}
+    </>
+  );
+}
+
+export default createComponent()({
+  displayName: 'ExpandableRows',
+  Component: () => {
+    return (
+      <>
+        <Heading as="h3" id={headingID} size="small">
+          Showroom Inventory
+        </Heading>
+        <Table aria-labelledby={headingID}>
+          <Table.Head>
+            <Table.Row gridTemplateColumns="4rem repeat(4, 1fr)">
+              <Table.Cell></Table.Cell>
+              <Table.Header scope="col">Make</Table.Header>
+              <Table.Header scope="col">Model</Table.Header>
+              <Table.Header scope="col">Year</Table.Header>
+              <Table.Header scope="col">Price</Table.Header>
+            </Table.Row>
+          </Table.Head>
+          <Table.Body>
+            {autoData.map(item => (
+              <ExpandableRow key={item.id} data={item} />
+            ))}
+          </Table.Body>
+        </Table>
+      </>
+    );
+  },
+});

package/dist/mdx/preview-react/_examples/examples/Table/WithSelectableRows.tsx

@@ -0,0 +1,156 @@
+import React from 'react';
+
+import {Table} from '@workday/canvas-kit-preview-react/table';
+import {Heading} from '@workday/canvas-kit-react/text';
+import {Checkbox} from '@workday/canvas-kit-react/checkbox';
+import {createComponent, generateUniqueId} from '@workday/canvas-kit-react/common';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {createStencil, createStyles} from '@workday/canvas-kit-styling';
+import {base} from '@workday/canvas-tokens-web';
+
+const selectableRowStencil = createStencil({
+  base: {
+    gridTemplateColumns: '3.5rem repeat(2, 1fr)',
+    transition: 'background-color 200ms',
+  },
+  modifiers: {
+    isSelected: {
+      true: {
+        backgroundColor: base.blueberry100,
+      },
+    },
+  },
+});
+
+const tableHeaderStyles = createStyles({
+  backgroundColor: base.soap100,
+});
+
+const tableCellStyles = createStyles({
+  backgroundColor: 'transparent',
+});
+
+interface SelectableRowProps {
+  onSelect?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+  rowData: PizzaTopping;
+}
+
+const SelectableRow = createComponent('tr')({
+  displayName: 'SelectableRow',
+  Component: ({onSelect, rowData}: SelectableRowProps) => {
+    return (
+      <Table.Row cs={selectableRowStencil({isSelected: rowData.checked})}>
+        <Table.Cell cs={tableCellStyles}>
+          <Tooltip title={rowData.name}>
+            <Checkbox checked={rowData.checked} onChange={onSelect} />
+          </Tooltip>
+        </Table.Cell>
+        <Table.Cell cs={tableCellStyles} scope="row">
+          {rowData.name}
+        </Table.Cell>
+        <Table.Cell cs={tableCellStyles}>{rowData.amount}</Table.Cell>
+      </Table.Row>
+    );
+  },
+});
+
+interface PizzaTopping {
+  name: string;
+  amount: string;
+  checked: boolean;
+}
+
+const pizzaToppingData: PizzaTopping[] = [
+  {name: 'Pepperoni', amount: '2.5 oz.', checked: false},
+  {name: 'Mozzarella', amount: '5 oz.', checked: false},
+  {name: 'Basil', amount: '10 Leaves', checked: false},
+  {name: 'Roasted Red Peppers', amount: '3 oz.', checked: false},
+  {name: 'Mushrooms', amount: '2 oz.', checked: false},
+];
+
+const headingID = generateUniqueId();
+
+type SelectAll = 'checked' | 'indeterminate' | 'unchecked';
+
+export default () => {
+  const [selectAllState, setSelectAllState] = React.useState<SelectAll>('unchecked');
+  const [toppings, setToppings] = React.useState(pizzaToppingData);
+
+  const handleToppingChange = (name: string) => {
+    // Toggle the selected item's checked state and update state
+    const updatedToppings = toppings.map(topping => {
+      if (topping.name === name) {
+        return {...topping, checked: !topping.checked};
+      } else {
+        return topping;
+      }
+    });
+    setToppings(updatedToppings);
+
+    // Update the Select All checkbox state
+    const selectedToppings = updatedToppings.filter(topping => topping.checked === true);
+    // If no toppings are selected, set the Select All checkbox to 'unchecked'
+    if (selectedToppings.length === 0) {
+      setSelectAllState('unchecked');
+      // If all toppings are selected, set the Select All checkbox to 'checked'
+    } else if (selectedToppings.length === updatedToppings.length) {
+      setSelectAllState('checked');
+      // Otherwise, set the Select All checkbox to 'indeterminate'
+    } else {
+      setSelectAllState('indeterminate');
+    }
+  };
+
+  const handleSelectAll = () => {
+    // If the Select All checkbox is in a checked or indeterminate state,
+    // update it to 'unchecked', and uncheck all topping checkboxes
+    if (selectAllState === 'checked' || selectAllState === 'indeterminate') {
+      setSelectAllState('unchecked');
+      const updatedToppingData = toppings.map(topping => ({...topping, checked: false}));
+      setToppings(updatedToppingData);
+    }
+    // If the Select All checkbox is in an unchecked state,
+    // update it to 'checked', and check all topping checkboxes
+    if (selectAllState === 'unchecked') {
+      setSelectAllState('checked');
+      const updatedToppingData = toppings.map(topping => ({...topping, checked: true}));
+      setToppings(updatedToppingData);
+    }
+  };
+
+  return (
+    <>
+      <Heading as="h3" id={headingID} size="small">
+        Select your pizza toppings
+      </Heading>
+      <Table aria-labelledby={headingID}>
+        <Table.Row gridTemplateColumns="3.5rem repeat(2, 1fr)">
+          <Table.Cell cs={tableHeaderStyles}>
+            <Tooltip title="Select All">
+              <Checkbox
+                checked={selectAllState === 'checked'}
+                indeterminate={selectAllState === 'indeterminate'}
+                onChange={handleSelectAll}
+              />
+            </Tooltip>
+          </Table.Cell>
+          <Table.Header scope="col" cs={tableHeaderStyles}>
+            Toppings
+          </Table.Header>
+          <Table.Header scope="col" cs={tableHeaderStyles}>
+            Amount
+          </Table.Header>
+        </Table.Row>
+        <Table.Body>
+          {toppings.map(rowData => (
+            <SelectableRow
+              key={rowData.name}
+              rowData={rowData}
+              onSelect={() => handleToppingChange(rowData.name)}
+            />
+          ))}
+        </Table.Body>
+      </Table>
+    </>
+  );
+};