@workday/canvas-kit-docs 11.0.0-alpha.682-next.0 → 11.0.0-alpha.696-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",
@@ -252446,6 +252620,23 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
           ],
           "tags": {}
         },
+        {
+          "kind": "property",
+          "name": "extractCSS",
+          "required": false,
+          "type": {
+            "kind": "primitive",
+            "value": "boolean"
+          },
+          "description": "Should the CSS be statically extracted into CSS files? If `true`, CSS files will be created\naccording to the `getFileName` configuration. If `getFileName` is not defined, a CSS file will\nbe created with the same name as the source file with a `.css` extension.",
+          "declarations": [
+            {
+              "name": "extractCSS",
+              "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/styling-transform/lib/utils/types.ts"
+            }
+          ],
+          "tags": {}
+        },
         {
           "kind": "property",
           "name": "getFileName",

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

@@ -22,6 +22,7 @@ any questions.
   - [Count Badge](#count-badge)
   - [Form Field Preview](#form-field-preview)
   - [Radio (Preview)](#radio-preview)
+  - [Table (Preview)](#table-preview)
   - [Text](#text)
 
 ## Codemod
@@ -423,6 +424,17 @@ our
 The component now supports the `cs` prop, but otherwise the API has not changed. It should behave
 identically as it did in previous versions.
 
+### Table (Preview)
+
+**PR:** [#2567](https://github.com/Workday/canvas-kit/pull/2567)
+
+`Table` 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.
+
 ### Text
 
 **PR:** [#2455](https://github.com/Workday/canvas-kit/pull/2455)

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} />