@workday/canvas-kit-docs 6.9.0-next.0 → 6.9.0-next.4

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/color-picker/color-input/ColorInput.mdx

@@ -105,12 +105,12 @@ standards.
 
 <ExampleCodeBlock code={Error} />
 
-## Props
+## Color Input Props
 
 Undocumented props are spread to the underlying `<input type="text">` element.
 
 <ArgsTable of={ColorInput} />
 
-## Specifications
+## Color Input Specifications
 
 <Specifications file="ColorPicker.spec.ts" name="ColorInput" />

package/dist/mdx/react/color-picker/color-preview/ColorPreview.mdx

@@ -42,12 +42,12 @@ relative to the Color Preview. `labelPosition` accepts the following values:
 
 <ExampleCodeBlock code={LabelPosition} />
 
-## Props
+## Color Preview Props
 
 Undocumented props are spread to the underlying `<input type="text">` element.
 
 <ArgsTable of={ColorPreview} />
 
-## Specifications
+## Color Preview Specifications
 
 <Specifications file="ColorPicker.spec.ts" name="ColorPreview" />

package/dist/mdx/{labs-react/common → react/layout}/Box.mdx

@@ -1,4 +1,4 @@
-import {Box} from '@workday/canvas-kit-labs-react/common';
+import {Box} from '@workday/canvas-kit-react/layout';
 // examples
 import As from './examples/As';
 import Border from './examples/Border';
@@ -33,9 +33,6 @@ import {
 
 # Box
 
-[![LABS: Beta](https://img.shields.io/badge/LABS-beta-orange)](https://github.com/Workday/canvas-kit/tree/master/modules/labs-react/README.md)
-This component is work in progress and currently in pre-release.
-
 `Box` is a primitive component that provides a common, ergonomic API around Canvas design tokens. It
 is highly flexible, and its primary purpose is to build other components.
 
@@ -85,14 +82,14 @@ is highly flexible, and its primary purpose is to build other components.
 ## Usage
 
 ```tsx
-import {Box, BoxProps} from '@workday/canvas-kit-labs-react/common';
+import {Box, BoxProps} from '@workday/canvas-kit-react/layout';
 
 interface CardProps extends BoxProps {
   // custom Card props go here
 }
 
 const Card = (props: CardProps) => {
-  return <Box borderRadius="m" depth={2} padding="m" {...props} />;
+  return <Box borderRadius="m" depth={1} padding="m" {...props} />;
 };
 ```
 

package/dist/mdx/{labs-react → react}/layout/Flex.mdx

@@ -1,35 +1,43 @@
-import {Flex} from '@workday/canvas-kit-labs-react/layout';
+import {Flex} from '@workday/canvas-kit-react/layout';
 // examples
 import FlexCard from './examples/Flex/FlexCard';
 import FlexLayout from './examples/Flex/FlexLayout';
 import Usage from './examples/Flex/Usage';
-import FlexStyle from './examples/PropTables.splitprops.tsx';
+import {FlexStyle} from './examples/PropTables.splitprops.tsx';
 
 
-# Flex
-
-[![LABS: Beta](https://img.shields.io/badge/LABS-beta-orange)](https://github.com/Workday/canvas-kit/tree/master/modules/labs-react/README.md)
-This component is work in progress and currently in pre-release.
+# Canvas Kit Flex
 
 `Flex` is a low-level layout component that provides a common, ergonomic API for building
 one-dimensional layouts with
 [CSS Flexbox](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox).
 
-## Table of Contents
+## Installation
 
-- [Flex](#flex)
-  - [Table of Contents](#table-of-contents)
-  - [Usage](#usage)
-  - [What's the difference between `Flex` and `Box`?](#whats-the-difference-between-flex-and-box)
-  - [Flex Props](#flex-props)
-  - [Examples](#examples)
-  - [Exhaustive Prop List](#exhaustive-prop-list)
+```sh
+yarn add @workday/canvas-kit-react
+```
 
 ## Usage
 
+### Basic Example
+
 <ExampleCodeBlock code={Usage} />
 
-## What's the difference between `Flex` and `Box`?
+### Rows and Columns
+
+You can nest `Flex` components to build layouts with rows and columns.
+
+<ExampleCodeBlock code={FlexLayout} />
+
+### Small Containers
+
+You can also use `Flex` to create layouts within smaller containers, such as this card example
+below:
+
+<ExampleCodeBlock code={FlexCard} />
+
+### Flex vs. Box
 
 `Flex` is built with `Box` and has access to all `BoxProps`. The main differences between `Box` and
 `Flex` are:
@@ -52,17 +60,6 @@ through style props as well. There are seven flex container props:
 
 <ArgsTable of={FlexStyle} />
 
-## Examples
-
-You can nest `Flex` components to build layouts with rows and columns.
-
-<ExampleCodeBlock code={FlexLayout} />
-
-You can also use `Flex` to create layouts within smaller containers, such as this card example
-below:
-
-<ExampleCodeBlock code={FlexCard} />
-
-## Exhaustive Prop List
+### Flex Props (Exhaustive List)
 
 <ArgsTable of={Flex} />