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

package/dist/es6/lib/docs.js

@@ -80191,6 +80191,30 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
                   }
                 ],
                 "tags": {}
+              },
+              {
+                "kind": "property",
+                "name": "item",
+                "required": false,
+                "type": {
+                  "kind": "symbol",
+                  "name": "Item",
+                  "typeParameters": [
+                    {
+                      "kind": "primitive",
+                      "value": "any"
+                    }
+                  ],
+                  "value": "Item<T>"
+                },
+                "description": "",
+                "declarations": [
+                  {
+                    "name": "item",
+                    "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/collection/lib/useListItemAllowChildStrings.ts"
+                  }
+                ],
+                "tags": {}
               }
             ]
           },
@@ -102843,6 +102867,27 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
                 "tags": {},
                 "declarations": []
               },
+              {
+                "kind": "property",
+                "name": "aria-activedescendant",
+                "required": true,
+                "type": {
+                  "kind": "union",
+                  "value": [
+                    {
+                      "kind": "primitive",
+                      "value": "null"
+                    },
+                    {
+                      "kind": "primitive",
+                      "value": "undefined"
+                    }
+                  ]
+                },
+                "description": "",
+                "tags": {},
+                "declarations": []
+              },
               {
                 "kind": "property",
                 "name": "id",
@@ -193138,6 +193183,23 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
                       }
                     ],
                     "tags": {}
+                  },
+                  {
+                    "kind": "property",
+                    "name": "placeholder",
+                    "required": false,
+                    "type": {
+                      "kind": "primitive",
+                      "value": "string"
+                    },
+                    "description": "",
+                    "declarations": [
+                      {
+                        "name": "placeholder",
+                        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/select/lib/hooks/useSelectInput.ts"
+                      }
+                    ],
+                    "tags": {}
                   }
                 ]
               },
@@ -193197,6 +193259,112 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
                 "tags": {},
                 "declarations": []
               },
+              {
+                "kind": "property",
+                "name": "onChange",
+                "required": true,
+                "type": {
+                  "kind": "function",
+                  "parameters": [
+                    {
+                      "kind": "parameter",
+                      "name": "event",
+                      "type": {
+                        "kind": "symbol",
+                        "name": "React.ChangeEvent",
+                        "typeParameters": [
+                          {
+                            "kind": "symbol",
+                            "name": "HTMLInputElement",
+                            "value": "HTMLInputElement"
+                          }
+                        ],
+                        "value": "ChangeEvent<T>"
+                      },
+                      "required": true,
+                      "rest": false,
+                      "description": "",
+                      "declarations": [
+                        {
+                          "name": "event",
+                          "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/select/lib/hooks/useSelectInput.ts"
+                        }
+                      ],
+                      "tags": {}
+                    }
+                  ],
+                  "members": [],
+                  "returnType": {
+                    "kind": "primitive",
+                    "value": "void"
+                  }
+                },
+                "description": "",
+                "tags": {},
+                "declarations": []
+              },
+              {
+                "kind": "property",
+                "name": "autoComplete",
+                "required": true,
+                "type": {
+                  "kind": "string",
+                  "value": "off"
+                },
+                "description": "",
+                "tags": {},
+                "declarations": []
+              },
+              {
+                "kind": "property",
+                "name": "onFocus",
+                "required": true,
+                "type": {
+                  "kind": "function",
+                  "parameters": [],
+                  "members": [],
+                  "returnType": {
+                    "kind": "primitive",
+                    "value": "void"
+                  }
+                },
+                "description": "",
+                "tags": {},
+                "declarations": []
+              },
+              {
+                "kind": "property",
+                "name": "textInputProps",
+                "required": true,
+                "type": {
+                  "kind": "object",
+                  "properties": [
+                    {
+                      "kind": "property",
+                      "name": "ref",
+                      "required": true,
+                      "type": {
+                        "kind": "symbol",
+                        "name": "RefObject",
+                        "typeParameters": [
+                          {
+                            "kind": "symbol",
+                            "name": "HTMLInputElement",
+                            "value": "any"
+                          }
+                        ],
+                        "value": "any"
+                      },
+                      "description": "",
+                      "tags": {},
+                      "declarations": []
+                    }
+                  ]
+                },
+                "description": "",
+                "tags": {},
+                "declarations": []
+              },
               {
                 "kind": "property",
                 "name": "ref",
@@ -193243,18 +193411,6 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
                 "tags": {},
                 "declarations": []
               },
-              {
-                "kind": "property",
-                "name": "autoComplete",
-                "required": true,
-                "type": {
-                  "kind": "string",
-                  "value": "off"
-                },
-                "description": "",
-                "tags": {},
-                "declarations": []
-              },
               {
                 "kind": "property",
                 "name": "defaultValue",
@@ -200094,6 +200250,24 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
           ],
           "tags": {}
         },
+        {
+          "kind": "property",
+          "name": "cs",
+          "required": false,
+          "type": {
+            "kind": "symbol",
+            "name": "CSToPropsInput",
+            "value": "CSToPropsInput"
+          },
+          "description": "The `cs` prop takes in a single value or an array of values. You can pass the CSS class name\nreturned by {@link createStyles}, or the result of {@link createVars} and\n{@link createModifiers}. If you're extending a component already using `cs`, you can merge that\nprop in as well. Any style that is passed to the `cs` prop will override style props. If you\nwish to have styles that are overridden by the `css` prop, or styles added via the `styled`\nAPI, use {@link handleCsProp} wherever `elemProps` is used. If your component needs to also\nhandle style props, use {@link mergeStyles} instead.\n\n\n```tsx\nimport {handleCsProp} from '@workday/canvas-kit-styling';\nimport {mergeStyles} from '@workday/canvas-kit-react/layout';\n\n// ...\n\n// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same\n// function signature, but adds support for style props.\n\nreturn (\n <Element\n   {...handleCsProp(elemProps, [\n     myStyles,\n     myModifiers({ size: 'medium' }),\n     myVars({ backgroundColor: 'red' })\n   ])}\n >\n   {children}\n </Element>\n)\n```",
+          "declarations": [
+            {
+              "name": "cs",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling/dist/es6/lib/cs.d.ts"
+            }
+          ],
+          "tags": {}
+        },
         {
           "kind": "property",
           "name": "children",

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/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>
+      </>
+    );
+  },
+});