@workday/canvas-kit-docs 7.2.0-next.1 → 7.2.0-next.2

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

@@ -7,6 +7,17 @@ import IdentifiedItems from './examples/IdentifiedItems';
 import RovingFocus from './examples/RovingFocus';
 import Selection from './examples/Selection';
 import MultiSelection from './examples/MultiSelection';
+import BasicGrid from './examples/BasicGrid';
+import WrappingGrid from './examples/WrappingGrid';
+import {
+  ListModelConfigComponent,
+  ListStateComponent,
+  ListEventsComponent,
+  GridModelConfigComponent,
+  GridStateComponent,
+  GridEventsComponent,
+  NavigationManager,
+} from './Collection.splitprops';
 
 
 # Canvas Kit Collection API
@@ -24,21 +35,7 @@ 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
+### 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
@@ -47,7 +44,7 @@ as [Dynamic List](#dynamic-list) example).
 
 <ExampleCodeBlock code={Basic} />
 
-#### Identifying Items
+### 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
@@ -57,7 +54,7 @@ item for selection, maintaining a cursor, or anything else.
 
 <ExampleCodeBlock code={IdentifiedItems} />
 
-#### Dynamic Items
+### 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
@@ -68,35 +65,6 @@ item, which could cause problems for popup menus. If your item count is low, pas
 
 <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
@@ -128,9 +96,263 @@ uses `ListBox` and creates a custom `SelectableItem` elemProps hook and componen
 
 #### 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.
+The `selection` manager can be passed directly to the model configuration to handle different
+selection types. This example passes the `multiSelectionManager` to handle selecting multiple items.
 
 <ExampleCodeBlock code={MultiSelection} />
 
-### Hooks
+### Basic Grid
+
+A grid is a two dimensional list. A `columnCount` config is added to inform how to break up an array
+of items. A grid is very similar to a list - it receives items as a single dimension list and uses
+the `columnCount` to determine keyboard navigation. Grids only support a single orientation.
+
+<ExampleCodeBlock code={BasicGrid} />
+
+#### Wrapping Grid
+
+By default, navigating a grid does not wrap around when the user reaches the end of a row or column.
+The grid model supports passing in a navigation manager. The collection system supports two types of
+navigation managers, a non-wrapping `navigationManager` and the `wrappingNavigationManager`. The
+following example passes the `wrappingNavigationManager` manager to the model. Observe how the
+cursor wraps around columns and rows when an edge of a column or row is encountered.
+
+<ExampleCodeBlock code={WrappingGrid} />
+
+## Components
+
+### ListBox
+
+#### Usage
+
+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`.
+
+#### Props
+
+<ArgsTable of={ListBox} />
+
+### ListBox.Item
+
+#### Usage
+
+The `ListBox.Item` is a simple placeholder for listbox items. The functionality of a collection item
+varies between components. For example, a `Tabs.Item` and a `Menu.Item` have shared functionality,
+but have different behavior. All collection-based components should implement a custom `Item`
+subcomponent using the collection-based behavior hooks. The [Roving Tabindex](#roving-tabindex)
+example uses the `elemPropsHook` to provide additional functionality. `elemPropsHook` is provided on
+all compound components and is useful in the example to add additional functionality without making
+a new component.
+
+#### Props
+
+<ArgsTable of={ListBox.Item} />
+
+## Models
+
+There are two supported models based on the collection system.
+
+### `useListModel`
+
+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.
+
+#### Config
+
+<ArgsTable of={ListModelConfigComponent} />
+
+#### State
+
+<ArgsTable of={ListStateComponent} />
+
+#### Events
+
+<ArgsTable of={ListEventsComponent} />
+
+### `useGridModel`
+
+The Grid model extends the List model and changes some config. For example, the `columnCount` is
+required on the grid model's configuration and `orientation` is removed.
+
+#### Config
+
+<ArgsTable of={GridModelConfigComponent} />
+
+#### State
+
+<ArgsTable of={GridStateComponent} />
+
+#### Events
+
+<ArgsTable of={GridEventsComponent} />
+
+### Navigation Manager
+
+The list and grid models accept a `navigation` config. If one is not provided, a default will be
+chosen. It is possible to create a custom navigation manager to hand to the model if the default
+doesn't work.
+
+<ArgsTable of={NavigationManager} />
+
+```ts
+type NavigationRequestor = <T>(id: string, model: Model) => Item<T>;
+
+interface Item<T> {
+  index: number;
+  id: string;
+  value: T;
+  /**
+   * Used by components that allow jumping to an item based on typing
+   */
+  textValue?: string;
+}
+```
+
+#### `navigationManager`
+
+The `navigationManager` implements the [Navigation Manager](#navigation-manager) interface for lists
+and grids, but does not wrap when the user hits a boundary of the collection. This is the default
+navigation manager for grids.
+
+#### `wrappingNavigationManager`
+
+The `wrappingNavigationManager` implements the [Navigation Manager](#navigation-manager) interface
+for lists and grids, and wraps when the user hits a boundary of the collection. Grids will wrap
+columns, but not rows. This is the default navigation manager for lists.
+
+### Selection Manager
+
+The list and grid models accept a `selection` config. If one is not provided, `singleSelectManager`
+is used. You can provide a custom select manager to suite your needs. A selection manager is an
+object with a single `select` method that takes an id and previously selected ids and returns a new
+set of selected ids.
+
+The collection system provides two selection managers: `singleSelectManager` and
+`multiSelectionManager`.
+
+```ts
+interface Selection {
+  selectedIds: 'all' | string[];
+  unselectedIds: string[];
+}
+
+interface SelectionManager {
+  select(id: string, prevState: Selection): Selection;
+}
+```
+
+## Hooks
+
+### `useListItemRegister`
+
+This elemProps hook is the base of all item component hooks. It registers an item with a collection
+and sets the `data-id` that is used by other hooks. It should always be the last defined hook when
+using `composeHooks` (`composeHooks` executes hooks right to left and merges props left to right).
+It is used by `ListBox.Item` and all `*.Item` subcomponents.
+
+```ts
+const useMyItem = composeHooks(
+  useListItemSelect, // additional hooks go here
+  useListItemRegister // always last
+);
+```
+
+### `useListItemRovingFocus`
+
+This elemProps hook is used for cursor navigation by using
+[Roving Tabindex](https://w3c.github.io/aria-practices/#kbd_roving_tabindex). Only a single item in
+the collection has a tab stop. Pressing an arrow key moves the tab stop to a different item in the
+corresponding direction. See the [Roving Tabindex](#roving-tabindex) example. This elemProps hook
+should be applied to an `*.Item` component.
+
+```ts
+const useMyItem = composeHooks(
+  useListItemRovingFocus, // adds the roving tabindex support
+  useListItemRegister
+);
+```
+
+### `useListItemSelect`
+
+This elemProps hook adds selection support to a `*.Item` subcomponent of a collection. It adds a
+click handler that toggles selection status according to the [Selection Manager](#selection-manager)
+used.
+
+```ts
+const useMyItem = composeHooks(
+  useListItemSelect, // adds selection support to an item
+  useListItemRegister
+);
+```
+
+### `useListRenderItem`
+
+```ts
+declare function useListRenderItem<T>(
+  model: Model,
+  children: React.ReactNode | ((item: T, index: number) => React.ReactNode)
+): React.ReactNode;
+```
+
+This hook is meant to be used inside the render function of `List` style components. It is used by
+`ListBox`. This hook gives list-based components their static and dynamic APIs to handle list items.
+This hook should only be used if you want to implement your own List. For example, `Tabs.List` uses
+this hook, but `Menu.List` uses `ListBox` which uses this hook.
+
+```tsx
+const MyList = createContainer('ul')({
+  modelHook: useListModel,
+})((elemProps, Element, model) => {
+  return <Element {...elemProps}>{useListRenderItems(model, elemProps.children)}</Element>;
+});
+```
+
+### `useListResetCursorOnBlur`
+
+This elemProps hook resets the cursor when the list looses focus. By default,
+[useListItemRovingFocus](#use-list-item-roving-focus) will leave the last focused item as the
+focusable item in the list. Sometimes it is desireable to reset the cursor to the last selected
+item. For example, `Tabs.Item` uses this hook to reset the tab stop to the currently selected tab.
+
+```ts
+const useMyItem = composeHooks(
+  useListResetCursorOnBlur, // adds the cursor reset to selected for roving tabindex
+  useListItemRovingFocus,
+  useListItemRegister
+);
+```
+
+### `useOverflowListItemMeasure`
+
+Coming Soon
+
+### `useOverflowListMeasure`
+
+Coming Soon
+
+### `useOverflowListTarget`
+
+Coming Soon

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

@@ -0,0 +1,19 @@
+import {useListModel, useGridModel} from '@workday/canvas-kit-react/collection';
+
+type ListModelConfig = Partial<typeof useListModel.defaultConfig> &
+  typeof useListModel.requiredConfig;
+type ListModel = ReturnType<typeof useListModel>;
+
+type GridModelConfig = Partial<typeof useGridModel.defaultConfig> &
+  typeof useGridModel.requiredConfig;
+type GridModel = ReturnType<typeof useGridModel>;
+
+export const ListModelConfigComponent = (_: ListModelConfig) => <div />;
+export const ListStateComponent = (_: ListModel['state']) => <div />;
+export const ListEventsComponent = (_: ListModel['events']) => <div />;
+
+export const GridModelConfigComponent = (_: GridModelConfig) => <div />;
+export const GridStateComponent = (_: GridModel['state']) => <div />;
+export const GridEventsComponent = (_: GridModel['events']) => <div />;
+
+export const NavigationManager = (_: GridModelConfig['navigation']) => <div />;

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

@@ -0,0 +1,46 @@
+import React from 'react';
+
+import {Flex, Box} from '@workday/canvas-kit-react/layout';
+import {
+  ListBox,
+  useGridModel,
+  useListItemSelect,
+  useListItemRovingFocus,
+  useListItemRegister,
+} from '@workday/canvas-kit-react/collection';
+import {composeHooks, createSubcomponent} from '@workday/canvas-kit-react/common';
+
+const useItem = composeHooks(useListItemSelect, useListItemRovingFocus, useListItemRegister);
+
+const Item = createSubcomponent('button')({
+  modelHook: useGridModel,
+  elemPropsHook: useItem,
+})((elemProps, Element, model) => {
+  return (
+    <Box
+      as={Element}
+      {...elemProps}
+      width={40}
+      border="solid 1px black"
+      style={{
+        background: model.state.selectedIds.includes(elemProps['data-id']) ? 'gray' : 'white',
+      }}
+    />
+  );
+});
+
+export default () => {
+  const model = useGridModel({
+    columnCount: 5,
+    // @ts-ignore Create an array of [{id: 1}, ...{id: n}]
+    items: [...Array(25).keys()].map(i => ({id: i + 1})),
+    // we don't need virtualization here
+    shouldVirtualize: false,
+  });
+
+  return (
+    <ListBox model={model} as={Flex} flexDirection="row" flexWrap="wrap" width={200}>
+      {item => <Item>{item.id}</Item>}
+    </ListBox>
+  );
+};

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

@@ -0,0 +1,48 @@
+import React from 'react';
+
+import {Flex, Box} from '@workday/canvas-kit-react/layout';
+import {
+  ListBox,
+  useGridModel,
+  useListItemSelect,
+  useListItemRovingFocus,
+  useListItemRegister,
+  wrappingNavigationManager,
+} from '@workday/canvas-kit-react/collection';
+import {composeHooks, createSubcomponent} from '@workday/canvas-kit-react/common';
+
+const useItem = composeHooks(useListItemSelect, useListItemRovingFocus, useListItemRegister);
+
+const Item = createSubcomponent('button')({
+  modelHook: useGridModel,
+  elemPropsHook: useItem,
+})((elemProps, Element, model) => {
+  return (
+    <Box
+      as={Element}
+      {...elemProps}
+      width={40}
+      border="solid 1px black"
+      style={{
+        background: model.state.selectedIds.includes(elemProps['data-id']) ? 'gray' : 'white',
+      }}
+    />
+  );
+});
+
+export default () => {
+  const model = useGridModel({
+    columnCount: 5,
+    // @ts-ignore Create an array of [{id: 1}, ...{id: n}]
+    items: [...Array(25).keys()].map(i => ({id: i + 1})),
+    // we don't need virtualization here
+    shouldVirtualize: false,
+    navigation: wrappingNavigationManager,
+  });
+
+  return (
+    <ListBox model={model} as={Flex} flexDirection="row" flexWrap="wrap" width={200}>
+      {item => <Item>{item.id}</Item>}
+    </ListBox>
+  );
+};

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

@@ -1,6 +1,7 @@
 import React from 'react';
 import {FormField} from '@workday/canvas-kit-react/form-field';
 import {Radio, RadioGroup} from '@workday/canvas-kit-react/radio';
+import styled from '@emotion/styled';
 
 export default () => {
   const [value, setValue] = React.useState<string | number>('deep-dish');
@@ -9,14 +10,22 @@ export default () => {
     setValue(value);
   };
 
+  const StyledFormField = styled(FormField)({
+    width: '161px',
+  });
+
   return (
-    <FormField label="Choose Your Pizza Crust" useFieldset={true}>
+    <StyledFormField label="Choose Your Pizza Crust" useFieldset={true}>
       <RadioGroup name="crust" onChange={handleChange} value={value}>
         <Radio label="Deep dish" value="deep-dish" />
         <Radio label="Thin" value="thin" />
         <Radio label="Gluten free" value="gluten-free" />
         <Radio label="Cauliflower" value="cauliflower" />
+        <Radio
+          label="My favorite pizza crust flavor is butter because it's the best thing to put on bread"
+          value="cauliflower"
+        />
       </RadioGroup>
-    </FormField>
+    </StyledFormField>
   );
 };

package/dist/mdx/react/skeleton/examples/Simulation.tsx

@@ -79,7 +79,29 @@ export default () => {
       <Card>
         <Card.Body>
           <Box minHeight={180} position="relative">
-            {!loading && (
+            {loading ? (
+              <StyledSimulation
+                position="absolute"
+                top={0}
+                left={0}
+                width="100%"
+                animation={!loading ? `${fadeOut} 150ms ease-out forwards` : undefined}
+              >
+                <Skeleton>
+                  <Flex alignItems="center">
+                    <Skeleton.Shape
+                      width={space.xl}
+                      height={space.xl}
+                      borderRadius={borderRadius.circle}
+                    />
+                    <Box flex={1} marginLeft="xs">
+                      <Skeleton.Header />
+                    </Box>
+                  </Flex>
+                  <Skeleton.Text lineCount={3} />
+                </Skeleton>
+              </StyledSimulation>
+            ) : (
               <Box>
                 <Flex alignItems="center" display="inline-flex" marginBottom="s">
                   <SystemIconCircle icon={patternIcon} />
@@ -100,28 +122,6 @@ export default () => {
                 </p>
               </Box>
             )}
-
-            <StyledSimulation
-              position="absolute"
-              top={0}
-              left={0}
-              width="100%"
-              animation={!loading ? `${fadeOut} 150ms ease-out forwards` : undefined}
-            >
-              <Skeleton>
-                <Flex alignItems="center">
-                  <Skeleton.Shape
-                    width={space.xl}
-                    height={space.xl}
-                    borderRadius={borderRadius.circle}
-                  />
-                  <Box flex={1} marginLeft="xs">
-                    <Skeleton.Header />
-                  </Box>
-                </Flex>
-                <Skeleton.Text lineCount={3} />
-              </Skeleton>
-            </StyledSimulation>
           </Box>
         </Card.Body>
       </Card>

package/dist/mdx/react/tabs/TabsModel.splitprops.tsx

@@ -1,5 +1,9 @@
-import {TabsModelConfig, TabsState, TabsEvents} from '@workday/canvas-kit-react/tabs';
+import {useTabsModel} from '@workday/canvas-kit-react/tabs';
+
+type TabsModelConfig = Partial<typeof useTabsModel.defaultConfig> &
+  typeof useTabsModel.requiredConfig;
+type Model = ReturnType<typeof useTabsModel>;
 
 export const TabsModelConfigComponent = (_: TabsModelConfig) => <div />;
-export const TabsStateComponent = (_: TabsState) => <div />;
-export const TabsEventsComponent = (_: TabsEvents) => <div />;
+export const TabsStateComponent = (_: Model['state']) => <div />;
+export const TabsEventsComponent = (_: Model['events']) => <div />;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "7.2.0-next.1+a7d03680",
+  "version": "7.2.0-next.2+2d1c962c",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -42,7 +42,7 @@
   ],
   "dependencies": {
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-react": "^7.2.0-next.1+a7d03680"
+    "@workday/canvas-kit-react": "^7.2.0-next.2+2d1c962c"
   },
   "devDependencies": {
     "fs-extra": "^10.0.0",
@@ -50,5 +50,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "4.1"
   },
-  "gitHead": "a7d036805acd5dc1deee93a82f20c843bda6a7dc"
+  "gitHead": "2d1c962c704eec264f341f2f3a5cad9a0e7c2c02"
 }