@workday/canvas-kit-docs 7.0.0-alpha.89-next.16 → 7.0.0-alpha.90-next.17

package/dist/mdx/react/collection/Collection.mdx

@@ -0,0 +1,136 @@
+import {ListBox} from '@workday/canvas-kit-react/collection';
+
+import Basic from './examples/Basic';
+import DynamicItems from './examples/DynamicItems';
+import BasicVirtual from './examples/BasicVirtual';
+import IdentifiedItems from './examples/IdentifiedItems';
+import RovingFocus from './examples/RovingFocus';
+import Selection from './examples/Selection';
+import MultiSelection from './examples/MultiSelection';
+
+
+# Canvas Kit Collection API
+
+The Collection API is a system of models and behaviors for creating lists and grids. For example,
+`Tabs` uses collection behaviors and so does `Menu`. The UI of each looks very different, but much
+of the behavior is shared. The Collection API should be used if a component doesn't already exist to
+satisfy your needs.
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-react
+```
+
+## Usage
+
+### ListBox
+
+The `ListBox` is a basic component that offers vertical rendering of a collection in the form of a
+2-dimension list. It understands virtualization, rendering only visible items in the DOM while also
+providing aria attributes to allow screen readers to still navigate virtual lists. The `ListBox`
+contains a basic `ListBox.Item` that renders list items that render correctly with virtualization
+and adds `aria-setsize` and `aria-posinset` for screen readers.
+
+The `ListBox` is very basic and only adds enough functionality to render correctly. No additional
+behaviors are added to navigate or select. React Hooks are provided to add this functionality and
+are used by higher level components like `Menu` and `Menu.Item` which utilize `ListBox`.
+
+<ArgsTable of={ListBox} />
+
+#### Basic Example
+
+The `ListBox` on its own isn't very useful. It registers each item with the model. The
+`ListBox.Item` only uses the `useListItemRegister` hook which handles registration of static items
+to the model. The `ListBox` uses `useListRenderItems` which handles rendering static items as well
+as [Dynamic List](#dynamic-list) example).
+
+<ExampleCodeBlock code={Basic} />
+
+#### Identifying Items
+
+A list item takes an optional `data-id` property that will be used to identify an item. Without a
+`data-id`, the identifier will be the item's index when first registered. The basic example has a
+`data-id` attribute that is a string representation of the index. Providing a `data-id` will
+override to a value of your choosing. This identifier will be used by other hooks to identify the
+item for selection, maintaining a cursor, or anything else.
+
+<ExampleCodeBlock code={IdentifiedItems} />
+
+#### Dynamic Items
+
+The `ListBox` also handles a dynamic collection of items. Instead of providing each `ListBox.Item`
+statically, provide a render function instead. The function is called with an `items` value that is
+the same was what's provided to the model. By default, providing items will enable virtualization.
+This example adds a `maxHeight` to ensure overflow. Virtualization uses absolute positioning of each
+item, which could cause problems for popup menus. If your item count is low, pass
+`shouldVirtualize={false}` to disable virtualization.
+
+<ExampleCodeBlock code={DynamicItems} />
+
+### List Model
+
+The List model contains the the state and events necessary to track items, selection, and a cursor.
+Various hooks can be used for a List model to create common behaviors associated with lists, such as
+navigating a list with a keyboard, selection (single and multiple), and virtualization.
+
+A list also has a "cursor". A cursor is often represented by focus, but it is not always a 1:1
+mapping. Think of the cursor as the focus item within the list. If the list has browser focus, the
+cursor will map to browser focus. Behaviors such as `useListRovingFocus` will map the cursor to the
+active tab stop of the list. For more information, see
+[Roving Tabindex](https://w3c.github.io/aria-practices/#kbd_roving_tabindex). `useListRovingFocus`
+adds keyboard events that map to navigation events. A [Navigation Manager](#navigation-manager) is
+used to map new cursor ids to these events. The `ListModel` takes an optional `navigation`
+configuration to change the default navigation behavior. The default navigation manager is a
+[wrappingNavigationManager](#wrappingnavigationmanager) meaning the cursor will wrap around the
+beginning and the ends. The cursor also provides a [navigationManager](#navigationmanager) that does
+not wrap. This is the default navigation for grids.
+
+The cursor also adds the concept of `orientation` which defaults to `'vertical'`. A Tab list is an
+example of a `'horizontal'` list.
+
+### Grid
+
+A Cursor List can become a grid if a `columnCount` is provided. The array of items is still flat,
+but navigational controls are now in two dimensions instead of one. A one dimension list is
+bidirectionally aware, but a grid will always
+
+#### Navigation Manager
+
+#### Roving Tabindex
+
+The list system also includes a cursor that extends the list. A cursor is mostly used for focusing
+items. The [roving tabindex](https://w3c.github.io/aria-practices/#kbd_roving_tabindex) is a
+well-supported way to accomplish accessibility requirements for focusing items within a list. This
+example shows how to use `useListRovingFocus`. This example uses the `ListBox` component, but the
+default `ListBox.Item` is very basic. We have two options, we can either pass additional
+functionality via `elemPropsHook` or by creating a new item using our elemProps hook primitives.
+Both will be demonstrated. Creating a custom item is recommended if you create a custom component
+and export it. Using `elemPropsHook` with `ListBox.Item` is recommended only for one-off instances.
+
+You can either use the tab key for focus on an item or click on an item and then use the up/down
+keys to navigation the list. By default, the list is set to wrap navigation using the
+`wrappingNavigationManager`. Only a single item in the list is a focus stop that "roves" as the
+up/down arrows are pressed.
+
+**Note:** This example doesn't meet accessibility requirements. The list will have to have some type
+of context. Like "navigation list" or "menu list".
+
+<ExampleCodeBlock code={RovingFocus} />
+
+#### Selection
+
+Lists support selection. `useSelectionItem` is applied to an item which adds an `onClick` that adds
+the item to the `state.selectedIds`. The default selection manager is a single select. This example
+uses `ListBox` and creates a custom `SelectableItem` elemProps hook and component.
+
+<ExampleCodeBlock code={Selection} />
+
+#### Multiple Selection
+
+Lists support selection. `useSelectionItem` is applied to an item which adds an `onClick` that adds
+the item to the `state.selectedIds`. The default selection manager is a single select.
+
+<ExampleCodeBlock code={MultiSelection} />
+
+### Hooks

package/dist/mdx/react/collection/examples/Basic.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+
+import {ListBox} from '@workday/canvas-kit-react/collection';
+
+export default () => {
+  return (
+    <ListBox>
+      <ListBox.Item>First</ListBox.Item>
+      <ListBox.Item>Second</ListBox.Item>
+    </ListBox>
+  );
+};

package/dist/mdx/react/collection/examples/BasicVirtual.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+
+import {ListBox, useListItemRovingFocus} from '@workday/canvas-kit-react/collection';
+
+interface Item {
+  id: string;
+  text: string;
+}
+
+const items: Item[] = Array(1000)
+  .fill(true)
+  .map((_, index) => ({id: String(index + 1), text: `Item - ${index + 1}`}));
+
+export default () => {
+  return (
+    <ListBox items={items} maxHeight={300}>
+      {(item: Item) => (
+        <ListBox.Item data-id={item.id} elemPropsHook={useListItemRovingFocus}>
+          {item.text}
+        </ListBox.Item>
+      )}
+    </ListBox>
+  );
+};

package/dist/mdx/react/collection/examples/DynamicItems.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+
+import {ListBox} from '@workday/canvas-kit-react/collection';
+
+interface Item {
+  id: string;
+  text: string;
+}
+
+const items: Item[] = Array(1000)
+  .fill(true)
+  .map((_, index) => ({id: String(index + 1), text: `Item - ${index + 1}`}));
+
+export default () => {
+  return (
+    <ListBox items={items} maxHeight={300}>
+      {(item: Item) => <ListBox.Item data-id={item.id}>{item.text}</ListBox.Item>}
+    </ListBox>
+  );
+};

package/dist/mdx/react/collection/examples/IdentifiedItems.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+
+import {ListBox} from '@workday/canvas-kit-react/collection';
+
+export default () => {
+  return (
+    <ListBox>
+      <ListBox.Item data-id="first">First</ListBox.Item>
+      <ListBox.Item data-id="second">Second</ListBox.Item>
+    </ListBox>
+  );
+};

package/dist/mdx/react/collection/examples/MultiSelection.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+
+import {
+  useListItemRegister,
+  useListItemRovingFocus,
+  useListItemSelect,
+  useListModel,
+  ListItemProps,
+  ListBox,
+} from '@workday/canvas-kit-react/collection';
+import {composeHooks, createSubcomponent} from '@workday/canvas-kit-react/common';
+import {multiSelectionManager} from '../../lib/useSelectionListModel';
+
+const useMultiSelectItem = composeHooks(
+  useListItemSelect,
+  useListItemRovingFocus,
+  useListItemRegister
+);
+
+const Item = createSubcomponent('button')({
+  displayName: 'MultiSelectableItem',
+  modelHook: useListModel,
+  elemPropsHook: useMultiSelectItem,
+})<ListItemProps>((elemProps, Element, model) => {
+  return (
+    <Element
+      role="listitem"
+      {...elemProps}
+      style={{
+        background: model.state.selectedIds.includes(elemProps['data-id']) ? 'gray' : 'white',
+      }}
+    />
+  );
+});
+
+export default () => {
+  const model = useListModel({
+    initialSelectedIds: ['first', 'second'],
+    selection: multiSelectionManager,
+    orientation: 'horizontal',
+  });
+  return (
+    <>
+      <ListBox model={model}>
+        <Item data-id="first">First</Item>
+        <Item data-id="second">Second</Item>
+        <Item data-id="third">Third</Item>
+      </ListBox>
+
+      <p>Cursor ID: {model.state.cursorId}</p>
+      <p>
+        Selected IDs: {(model.state.selectedIds !== 'all' ? model.state.selectedIds : []).join(',')}
+      </p>
+    </>
+  );
+};

package/dist/mdx/react/collection/examples/RovingFocus.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+
+import {
+  useListItemRegister,
+  useListItemRovingFocus,
+  useListModel,
+  ListBox,
+  ListItemProps,
+} from '@workday/canvas-kit-react/collection';
+import {composeHooks, createSubcomponent} from '@workday/canvas-kit-react/common';
+
+// create our own hook using `useListItemRegister` and `useListItemRovingFocus`. Note the
+// `useListItemRegister` must be the last hook when using `composeHooks`
+const useRovingFocusItem = composeHooks(useListItemRovingFocus, useListItemRegister);
+
+// create our own item. We use `modelHook` to define which model should be used and `elemPropsHook`
+// to determine which elemProps hook should be used. `elemProps` will be populated with props to
+// pass to the element
+const RovingFocusItem = createSubcomponent('li')({
+  displayName: 'RovingFocusItem',
+  modelHook: useListModel,
+  elemPropsHook: useRovingFocusItem,
+})<ListItemProps>((elemProps, Element) => {
+  return <Element {...elemProps} />;
+});
+
+export default () => {
+  return (
+    <ListBox>
+      {/* We can use `ListBox.Item` and add `useListItemRovingFocus`. Useful for one-off */}
+      <ListBox.Item data-id="first" elemPropsHook={useListItemRovingFocus}>
+        First
+      </ListBox.Item>
+      {/* Use a custom item. Useful for reusing components */}
+      <RovingFocusItem data-id="second">Second</RovingFocusItem>
+      <RovingFocusItem data-id="third">Third</RovingFocusItem>
+    </ListBox>
+  );
+};

package/dist/mdx/react/collection/examples/Selection.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+
+import {
+  useListItemRegister,
+  useListItemRovingFocus,
+  useListItemSelect,
+  useListModel,
+  ListItemProps,
+  ListBox,
+} from '@workday/canvas-kit-react/collection';
+import {
+  composeHooks,
+  createElemPropsHook,
+  createSubcomponent,
+} from '@workday/canvas-kit-react/common';
+
+// Create a custom hook for our item
+const useItem = composeHooks(
+  createElemPropsHook(useListModel)((model, ref, elemProps: ListItemProps) => {
+    return {
+      role: 'listitem',
+      style: {
+        background: model.state.selectedIds.includes(elemProps['data-id']) ? 'gray' : 'white',
+      },
+    };
+  }),
+  useListItemSelect,
+  useListItemRovingFocus,
+  useListItemRegister
+);
+
+// Create a custom item
+const SelectableItem = createSubcomponent('button')({
+  displayName: 'SelectableItem',
+  modelHook: useListModel,
+  elemPropsHook: useItem,
+})<ListItemProps>((elemProps, Element) => {
+  return <Element {...elemProps} />;
+});
+
+export default () => {
+  const model = useListModel({
+    initialSelectedIds: ['first'],
+    orientation: 'horizontal',
+  });
+  return (
+    <>
+      <ListBox model={model}>
+        <SelectableItem data-id="first">First</SelectableItem>
+        <SelectableItem data-id="second">Second</SelectableItem>
+        <SelectableItem data-id="third">Third</SelectableItem>
+      </ListBox>
+
+      <p>Cursor ID: {model.state.cursorId}</p>
+      <p>Selected ID: {model.state.selectedIds[0]}</p>
+    </>
+  );
+};

package/dist/mdx/react/menu/Menu.mdx

@@ -0,0 +1,123 @@
+import {Specifications} from '@workday/canvas-kit-docs';
+import {Menu} from '@workday/canvas-kit-react/menu';
+
+import Basic from './examples/Basic';
+import ContextMenu from './examples/ContextMenu';
+import Icons from './examples/Icons';
+
+
+# Canvas Kit Menu
+
+`Menu` displays a list of options when triggered by an action or UI element like an icon or button.
+
+[> Workday Design Reference](https://design.workday.com/components/popups/menus)
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-react
+```
+
+## Usage
+
+### Basic Example
+
+`Menu` is typically triggered by an action such as pressing a button. The `Menu` comes with a
+`Target` subcomponent and a Popup.
+
+<ExampleCodeBlock code={Basic} />
+
+`Menu` will automatically focus on the cursor item (first item by default). The `Menu` uses a menu
+model which composes a list model and a popup model and sets up accessibility features for you.
+
+`Menu` follows the
+[Actions Menu pattern](https://www.w3.org/TR/wai-aria-practices/examples/menu-button/menu-button-actions.html)
+using roving tabindex. Below is table of supported keyboard shortcuts and associated actions.
+
+| Key                | Action                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `Enter` or `Space` | Activates the menu item and then closes the menu                                                             |
+| `Escape`           | Closes the menu                                                                                              |
+| `Up Arrow`         | Moves focus to the previous menu item – if focus is on first menu item, it moves focus to the last menu item |
+| `Down Arrow`       | Moves focus to the next menu item – if focus is on last menu item, it moves focus to the first menu item     |
+| `Home`             | Moves focus to the first menu item                                                                           |
+| `End`              | Moves focus to the last menu item                                                                            |
+
+### Context Menu
+
+<ExampleCodeBlock code={ContextMenu} />
+
+### Icons
+
+<ExampleCodeBlock code={Icons} />
+
+## Components
+
+### Menu
+
+### Usage
+
+`Menu` is a combination of as popup and a list. It usually has some type of target element that
+expands/collapses the menu and a `menu` role and and several `menuitem` roles. Focus is managed uses
+[roving tabindex](https://w3c.github.io/aria-practices/#kbd_roving_tabindex) for maximum
+compatibility. A `Menu` can have two modes: `single` and `multiple`. This mode determines both how
+many items can be selected as well as the default behavior when a menuitem is clicked. For the
+`single` mode, selecting a `menuitem` will select and close the menu. For the `multiple` mode,
+clicking a `menuitem` will toggle selection and will not close the menu.
+
+#### Props
+
+<ArgsTable of={Menu} />
+
+#### Usage
+
+Like all compound components, the `Menu` component is a container component. It is responsible for
+putting a `MenuModel` in the React context for all the menu subcomponents. You can either pass this
+component model config or a "hoisted" model.
+
+With model config:
+
+```tsx
+<Menu mode="multiple">{/* Child components */}</Menu>
+```
+
+With a hoisted model:
+
+```tsx
+const model = useMenuModel({
+  mode: 'multiple',
+});
+
+// we now have access to `model.state` and `model.events`
+
+<Menu model={model}>{/* Child components */}</Menu>;
+```
+
+### Menu.Target
+
+#### Usage
+
+`Menu.Target` is similar to all `Popup.Target` types. The component only provides behavior and no
+styling. The `as` prop is used to determine which component is rendered. This component should
+forward the `ref` and apply any additional props directly to an element. The default `as` is a
+`SecondaryButton`. Any Canvas Kit component should work with an `as`.
+
+An example changing to a `PrimaryButton`
+
+```tsx
+<Menu.Target as={PrimaryButton}>Primary Button Text</Menu.Target>
+```
+
+This element will apply `aria-haspopup` and `aria-expanded` to inform screen readers there's a popup
+associated with the element.
+
+#### Props
+
+Undocumented props are spread to the element provided by the `as` which is a `SecondaryButton` by
+default.
+
+<ArgsTable of={Menu.Target} />
+
+## Specifications
+
+<Specifications file="Menu.spec.ts" name="Menu" />

package/dist/mdx/react/menu/examples/Basic.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+
+import {Menu} from '@workday/canvas-kit-react/menu';
+
+export default () => {
+  const [selected, setSelected] = React.useState('');
+  return (
+    <Menu onSelect={data => setSelected(data.id)}>
+      <Menu.Target>Open Menu</Menu.Target>
+      <Menu.Popper>
+        <Menu.Card>
+          <Menu.List>
+            <Menu.Item>First Item</Menu.Item>
+            <Menu.Item>Second Item</Menu.Item>
+            <Menu.Divider />
+            <Menu.Item>Third Item (with a really, really, really long label)</Menu.Item>
+            <Menu.Item>Fourth Item</Menu.Item>
+          </Menu.List>
+        </Menu.Card>
+      </Menu.Popper>
+      <p>
+        Selected: <span data-testid="output">{selected}</span>
+      </p>
+    </Menu>
+  );
+};

package/dist/mdx/react/menu/examples/ContextMenu.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+
+import {Menu} from '@workday/canvas-kit-react/menu';
+
+export default () => {
+  const [selected, setSelected] = React.useState('');
+  return (
+    <Menu onSelect={data => setSelected(data.id)}>
+      <Menu.TargetContext>Open Menu</Menu.TargetContext>
+      <Menu.Popper>
+        <Menu.Card>
+          <Menu.List>
+            <Menu.Item>First Item</Menu.Item>
+            <Menu.Item>Second Item</Menu.Item>
+            <Menu.Item>Third Item (with a really, really, really long label)</Menu.Item>
+            <Menu.Item>Fourth Item</Menu.Item>
+          </Menu.List>
+        </Menu.Card>
+      </Menu.Popper>
+      <p>
+        Selected: <span data-testid="output">{selected}</span>
+      </p>
+    </Menu>
+  );
+};

package/dist/mdx/react/menu/examples/Icons.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import {
+  setupIcon,
+  uploadCloudIcon,
+  userIcon,
+  taskContactIcon,
+} from '@workday/canvas-system-icons-web';
+import {Menu} from '@workday/canvas-kit-react/menu';
+
+export default () => {
+  return (
+    <Menu>
+      <Menu.Card>
+        <Menu.List>
+          <Menu.Item>
+            <Menu.Item.Icon icon={uploadCloudIcon} />
+            <Menu.Item.Text>First Item</Menu.Item.Text>
+          </Menu.Item>
+          <Menu.Item>
+            <Menu.Item.Icon icon={setupIcon} />
+            <Menu.Item.Text>Second Item (with a really really really long label)</Menu.Item.Text>
+          </Menu.Item>
+          <Menu.Item aria-disabled>
+            <Menu.Item.Icon icon={uploadCloudIcon} />
+            <Menu.Item.Text>Third Item</Menu.Item.Text>
+            <Menu.Item.Icon icon={taskContactIcon} />
+          </Menu.Item>
+          <Menu.Item>
+            <Menu.Item.Icon icon={userIcon} />
+            <Menu.Item.Text></Menu.Item.Text>
+          </Menu.Item>
+          <Menu.Divider />
+          <Menu.Item>
+            <Menu.Item.Icon icon={taskContactIcon} />
+            <Menu.Item.Text>Fifth Item (with divider)</Menu.Item.Text>
+          </Menu.Item>
+        </Menu.List>
+      </Menu.Card>
+    </Menu>
+  );
+};

package/dist/mdx/react/modal/examples/ReturnFocus.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import {Modal, useModalModel} from '@workday/canvas-kit-react/modal';
-import {DeleteButton, SecondaryButton} from '@workday/canvas-kit-react/button';
+import {DeleteButton} from '@workday/canvas-kit-react/button';
 import {FormField} from '@workday/canvas-kit-react/form-field';
 import {HStack, Box} from '@workday/canvas-kit-react/layout';
 import {Select} from '@workday/canvas-kit-preview-react/select';

package/dist/mdx/react/popup/examples/InitialFocus.tsx

@@ -8,6 +8,7 @@ import {
   useInitialFocus,
   useReturnFocus,
 } from '@workday/canvas-kit-react/popup';
+import {HStack} from '@workday/canvas-kit-react/layout';
 
 export default () => {
   const initialFocusRef = React.useRef(null);
@@ -29,11 +30,12 @@ export default () => {
           <Popup.Heading>Confirmation</Popup.Heading>
           <Popup.Body>
             <p id="popup-message">Your message has been sent!</p>
-
+          </Popup.Body>
+          <HStack spacing="s">
             <Popup.CloseButton ref={initialFocusRef} aria-describedby="popup-message">
               OK
             </Popup.CloseButton>
-          </Popup.Body>
+          </HStack>
         </Popup.Card>
       </Popup.Popper>
     </Popup>

package/dist/mdx/react/popup/examples/NestedPopups.tsx

@@ -37,24 +37,24 @@ export default () => {
             <Popup.CloseIcon aria-label="Close" size="small" />
             <Popup.Body>
               <p>Contents of Popup 1</p>
-              <Popup model={popup2}>
-                <Popup.Target>Open Popup 2</Popup.Target>
-                <Popup.Popper>
-                  <Popup.Card aria-label="Popup 2">
-                    <Popup.CloseIcon aria-label="Close" size="small" />
-                    <Popup.Body>
-                      <p>Contents of Popup 2</p>
-                      <HStack spacing="s">
-                        <Popup.CloseButton as={Popup.CloseButton} model={popup1}>
-                          Close Both (as)
-                        </Popup.CloseButton>
-                        <SecondaryButton {...closeBothProps}>Close Both (props)</SecondaryButton>
-                      </HStack>
-                    </Popup.Body>
-                  </Popup.Card>
-                </Popup.Popper>
-              </Popup>
             </Popup.Body>
+            <Popup model={popup2}>
+              <Popup.Target>Open Popup 2</Popup.Target>
+              <Popup.Popper>
+                <Popup.Card aria-label="Popup 2">
+                  <Popup.CloseIcon aria-label="Close" size="small" />
+                  <Popup.Body>
+                    <p>Contents of Popup 2</p>
+                  </Popup.Body>
+                  <HStack spacing="s">
+                    <Popup.CloseButton as={Popup.CloseButton} model={popup1}>
+                      Close Both (as)
+                    </Popup.CloseButton>
+                    <SecondaryButton {...closeBothProps}>Close Both (props)</SecondaryButton>
+                  </HStack>
+                </Popup.Card>
+              </Popup.Popper>
+            </Popup>
           </Popup.Card>
         </Popup.Popper>
       </Popup>