@workday/canvas-kit-react 7.1.4 → 7.2.0-427-next.2

package/collection/lib/ListBox.tsx

@@ -3,26 +3,27 @@ import {
   createContainer,
   createElemPropsHook,
   createSubcomponent,
+  ExtractProps,
 } from '@workday/canvas-kit-react/common';
-import {Box, BoxProps} from '@workday/canvas-kit-react/layout';
+import {Box, Flex} from '@workday/canvas-kit-react/layout';
 
 import {useListModel} from './useListModel';
 import {useListRenderItems} from './useListRenderItem';
 import {useListItemRegister} from './useListItemRegister';
 
-export interface ListBoxProps extends BoxProps {
-  children?: React.ReactNode | ((item: any) => React.ReactNode);
+export interface ListBoxProps<T = any> extends Omit<ExtractProps<typeof Flex, never>, 'children'> {
+  children?: React.ReactNode | ((item: T, index: number) => React.ReactNode);
 }
 
 export const ListBoxItem = createSubcomponent('li')({
   displayName: 'Item',
   modelHook: useListModel,
   elemPropsHook: useListItemRegister,
-})<BoxProps>((elemProps, Element) => {
+})<ExtractProps<typeof Flex, never>>((elemProps, Element) => {
   return <Box as={Element} {...elemProps} />;
 });
 
-const useListBox = createElemPropsHook(useListModel)(model => {
+export const useListBox = createElemPropsHook(useListModel)(model => {
   return {
     style: {
       position: 'relative' as const,
@@ -32,8 +33,17 @@ const useListBox = createElemPropsHook(useListModel)(model => {
 });
 
 /**
- * Basic list box that supports virtualization. `ListBox.Item` contains a very simple list item
- * without much functionality. The `ListBox` contains two `Box` elements:
+ * The `ListBox` component that offers vertical rendering of a collection in the form of a
+ * 2-dimension list. It supports 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`. The
+ * `ListBox` contains two `Box` elements:
+ *
  * - Outer Box: Presentational container element responsible for overflow and height. `height` and
  *   `maxHeight` props will be applied here.
  * - Inner Box: The element responsible for the virtual container. Height is controlled by the model
@@ -45,26 +55,31 @@ export const ListBox = createContainer('ul')({
   elemPropsHook: useListBox,
   subComponents: {
     /**
-     * Extremely simple ListBox item that contains no functionality other than registering items and
-     * adding aria virtualization attributes. If you need more functionality, create your own
-     * component using list item hooks.
+     * 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.
      */
     Item: ListBoxItem,
   },
-})<ListBoxProps>(({height, maxHeight, ...elemProps}, Element, model) => {
+})<ListBoxProps>(({height, maxHeight, marginY, ...elemProps}, Element, model) => {
+  // We're moving `marginY` to the container to not interfere with the virtualization size. We set
+  // the `marginY` on the Flex to `0` to avoid inaccurate scrollbars
+
   // TODO figure out what style props should go to which `Box`
   return (
     <Box
       ref={model.state.containerRef}
-      height={
-        height || model.state.isVirtualized ? model.state.UNSTABLE_virtual.totalSize : undefined
-      }
+      marginY={marginY}
       maxHeight={maxHeight}
       overflowY={model.state.orientation === 'vertical' ? 'auto' : undefined}
     >
-      <Box as={Element} {...elemProps}>
+      <Flex as={Element} flexDirection="column" {...elemProps} marginY={0}>
         {useListRenderItems(model, elemProps.children)}
-      </Box>
+      </Flex>
     </Box>
   );
 });

package/collection/lib/keyUtils.ts

@@ -0,0 +1,88 @@
+import React from 'react';
+import {useCursorListModel} from './useCursorListModel';
+
+export const orientationKeyMap = {
+  horizontal: {
+    ArrowLeft: 'goToPrevious',
+    Left: 'goToPrevious',
+    ArrowRight: 'goToNext',
+    Right: 'goToNext',
+    Home: 'goToFirst',
+    End: 'goToLast',
+    PageDown: 'goToNextPage',
+    PageUp: 'goToPreviousPage',
+  },
+  vertical: {
+    ArrowUp: 'goToPrevious',
+    Up: 'goToPrevious',
+    ArrowDown: 'goToNext',
+    Down: 'goToNext',
+    Home: 'goToFirst',
+    End: 'goToLast',
+    PageDown: 'goToNextPage',
+    PageUp: 'goToPreviousPage',
+  },
+} as const;
+
+const rightToLeftMap = {
+  ArrowLeft: 'ArrowRight',
+  Left: 'Right',
+  ArrowRight: 'ArrowLeft',
+  Right: 'Left',
+  Home: 'Home',
+  End: 'End',
+  PageDown: 'PageDown',
+  PageUp: 'PageUp',
+} as const;
+
+const gridKeyMap = {
+  ...orientationKeyMap.horizontal,
+  Home: 'goToFirstOfRow',
+  End: 'goToLastOfRow',
+  ArrowUp: 'goToPreviousRow',
+  Up: 'goToPreviousRow',
+  ArrowDown: 'goToNextRow',
+  Down: 'goToNextRow',
+} as const;
+
+const ctrlKeyMap = {
+  Home: 'goToFirst',
+  End: 'goToLast',
+} as const;
+
+const hasOwnKey = <T extends object>(obj: T, key: any): key is keyof T => obj.hasOwnProperty(key);
+
+export function keyboardEventToCursorEvents(
+  event: React.KeyboardEvent,
+  model: ReturnType<typeof useCursorListModel>,
+  isRTL: boolean
+): boolean {
+  // Test ctrl key first
+  if (event.ctrlKey) {
+    for (const key in ctrlKeyMap) {
+      if (hasOwnKey(ctrlKeyMap, key)) {
+        if (event.key === key) {
+          model.events[ctrlKeyMap[key]]?.();
+          return true;
+        }
+      }
+    }
+  }
+  // Try regular keys
+  const map = model.state.columnCount > 0 ? gridKeyMap : orientationKeyMap[model.state.orientation];
+  for (const key in map) {
+    if (hasOwnKey(map, key)) {
+      if (isRTL ? event.key === rightToLeftMap[key] : event.key === key) {
+        const eventName =
+          model.state.columnCount > 0
+            ? gridKeyMap[key]
+            : orientationKeyMap[model.state.orientation][key];
+        if (model.events[eventName]) {
+          model.events[eventName]?.();
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}

package/collection/lib/useBaseListModel.tsx

@@ -1,17 +1,16 @@
 import React from 'react';
 import {useVirtual} from './react-virtual';
 
-import {useUniqueId, assert, createModelHook, Generic} from '@workday/canvas-kit-react/common';
+import {useUniqueId, createModelHook, Generic} from '@workday/canvas-kit-react/common';
 
 export type Orientation = 'horizontal' | 'vertical';
 
 export const defaultGetId = (item: any): string => {
-  assert(item.id, 'A list item must have an `id` field or a `getId` function defined');
-  return item.id;
+  return typeof item === 'string' ? item : item.id || '';
 };
 
 export const defaultGetTextValue = (item: any): string => {
-  return item.text || '';
+  return typeof item === 'string' ? item : item.text || '';
 };
 
 export interface Item<T> {
@@ -79,15 +78,21 @@ export const useBaseListModel = createModelHook({
     /** IDREF of the list. Children ids can be derived from this id */
     id: '',
     /**
-     * Optional function to return an id of an item. If not provided, the default function will return
-     * the `id` property from the object of each item. If you did not provide `items`, do not override
-     * this function. If you don't provided `items` and instead provide static items via JSX, the list
-     * will create an internal array of items where `id` is the only property and the default `getId`
-     * will return the desired result.
+     * Optional function to return an id of an item. If not provided, the default function will
+     * return the `id` property from the object of each item. If you did not provide `items`, do not
+     * override this function. If you don't provided `items` and instead provide static items via
+     * JSX, the list will create an internal array of items where `id` is the only property and the
+     * default `getId` will return the desired result.
      */
-    getId: (item: Generic) => item.id as string,
-
-    getTextValue: (item: Generic) => (item.text || '') as string,
+    getId: (item: Generic) =>
+      typeof item === 'string' ? item : item === undefined ? '' : (item.id as string),
+    /**
+     * Optional function to return the text representation of an item. If not provided, the default
+     * function will return the `text` property of the object of each item or an empty string if
+     * there is no `text` property. If you did not provide `items`, do not override this function.
+     */
+    getTextValue: (item: Generic) =>
+      (typeof item === 'string' ? item : item === undefined ? '' : item.text || '') as string,
     /**
      * Array of all ids which are currently disabled. This is used for navigation to skip over items
      * which are not focusable.
@@ -112,8 +117,17 @@ export const useBaseListModel = createModelHook({
 })(config => {
   const id = useUniqueId(config.id);
 
+  // Optimization to not redo items when `getId` and `getTextValue` references change. They will not
+  // likely change during the lifecycle and we don't want to recalculate items when a lamba is
+  // passed instead of a stable reference.
+  const getIdRef = React.useRef(defaultGetId);
+  const getTextValueRef = React.useRef(defaultGetTextValue);
+
   const getId = config.getId || defaultGetId;
   const getTextValue = config.getTextValue || defaultGetTextValue;
+  getIdRef.current = getId;
+  getTextValueRef.current = getTextValue;
+
   const [orientation] = React.useState(config.orientation || 'vertical');
   const [UNSTABLE_defaultItemHeight, setDefaultItemHeight] = React.useState(
     config.defaultItemHeight
@@ -125,13 +139,13 @@ export const useBaseListModel = createModelHook({
     () =>
       (config.items || []).map((item, index) => {
         return {
-          id: getId(item),
+          id: getIdRef.current(item),
           index,
           value: item,
-          textValue: getTextValue(item),
+          textValue: getTextValueRef.current(item),
         };
       }),
-    [config.items, getId, getTextValue]
+    [config.items]
   );
   const [staticItems, setStaticItems] = React.useState<Item<Generic>[]>([]);
   const UNSTABLE_virtual = useVirtual({
@@ -170,7 +184,7 @@ export const useBaseListModel = createModelHook({
         return items.concat({
           id: getId(data.item),
           value: data.item,
-          index: items.length - 1,
+          index: items.length,
           textValue: data.textValue,
         });
       });