@workday/canvas-kit-react 8.0.0-alpha.253-next.22 → 8.0.0-alpha.428-next.2

package/collection/lib/useCursorListModel.tsx

@@ -1,10 +1,15 @@
 import React from 'react';
 import {assert, createModelHook, Generic} from '@workday/canvas-kit-react/common';
 
-import {useBaseListModel, Item, defaultGetId as getId} from './useBaseListModel';
+import {useBaseListModel, Item} from './useBaseListModel';
 
 type NavigationInput = Pick<ReturnType<typeof useCursorListModel>, 'state'>;
 
+/**
+ * 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.
+ */
 export interface NavigationManager {
   /** Get the first item in a collection. This will be called when the `Home` key is pressed for
    * Lists and `Ctrl+Home` for Grids. */
@@ -13,7 +18,7 @@ export interface NavigationManager {
    * and `Ctrl+End` for Grids. */
   getLast: NavigationRequestor;
   /** Get an item with the provided `id`. */
-  getItem: NavigationRequestor;
+  getItem: (id: string, model: NavigationInput) => Item<Generic>;
   /** Get the next item after the provided `id`. This will be called when the `Right` arrow key is
    * pressed for RTL languages and when the `Left` arrow is pressed for LTR languages. */
   getNext: NavigationRequestor;
@@ -61,91 +66,92 @@ export interface NavigationManager {
  */
 export const createNavigationManager = (manager: NavigationManager) => manager;
 
-/** Function type to make it easier to define navigation functions */
-export type NavigationRequestor = (id: string, {state}: NavigationInput) => Item<Generic>;
+/**
+ * Given an id and a model, return an item from the collection
+ */
+export type NavigationRequestor = (index: number, model: NavigationInput) => number;
 
 /**
  * Get the first item in a list regardless of column count
  */
-export const getFirst: NavigationRequestor = (_, {state}) => state.items[0];
+export const getFirst: NavigationRequestor = (_, {state}) => 0;
 /**
  * Get the last item in a list regardless of column count
  */
-export const getLast: NavigationRequestor = (_, {state}) => state.items[state.items.length - 1];
+export const getLast: NavigationRequestor = (_, {state}) => state.items.length - 1;
 
 /**
  * Get the first item in a row. If column count is 0, it will return the results of `getFirst`
  */
-export const getFirstOfRow: NavigationRequestor = (id, {state}) => {
+export const getFirstOfRow: NavigationRequestor = (index, {state}) => {
   if (state.columnCount) {
-    const item = getItem(id, {state});
-    const currentIndex = item.index;
-    const offset = currentIndex % state.columnCount;
-    return state.items[currentIndex - offset];
+    const offset = index % state.columnCount;
+    return index - offset;
   }
-  return getFirst(id, {state});
+  return getFirst(index, {state});
 };
 
 /**
  * get the last item in a row - if column count is 0, it will return the results of `getLast`
  */
-export const getLastOfRow: NavigationRequestor = (id, {state}) => {
+export const getLastOfRow: NavigationRequestor = (index, {state}) => {
   if (state.columnCount) {
-    const item = getItem(id, {state});
-    const currentIndex = item.index;
-    const offset = (currentIndex % state.columnCount) - state.columnCount + 1;
-    let nextIndex = currentIndex - offset;
+    const offset = (index % state.columnCount) - state.columnCount + 1;
+    let nextIndex = index - offset;
     if (nextIndex >= state.items.length) {
       nextIndex = state.items.length - 1;
     }
-    return state.items[nextIndex];
+    return nextIndex;
   }
-  return getLast(id, {state});
+  return getLast(index, {state});
 };
 
 /**
  * get the item in the previous page. This can be author defined. By default it will return the
  * first item for a list, and the first item in the same column for a grid.
  */
-export const getPreviousPage: NavigationRequestor = (id, {state}) => {
+export const getPreviousPage: NavigationRequestor = (index, {state}) => {
   if (state.columnCount) {
-    const item = getItem(id, {state});
-    const currentIndex = item.index;
-    return state.items[currentIndex % state.columnCount];
+    return index % state.columnCount;
   }
-  return getFirst(id, {state});
+  return getFirst(index, {state});
 };
 
 /**
  * get the item in the next page. This can be author defined. By default, it will return the last
  * item for a list, and the last item in the same column for a grid.
  */
-export const getNextPage: NavigationRequestor = (id, {state}) => {
+export const getNextPage: NavigationRequestor = (index, {state}) => {
   if (state.columnCount) {
-    const item = getItem(id, {state});
-    const currentIndex = item.index;
     const lastRowIndex = state.items.length - state.columnCount;
-    return state.items[lastRowIndex + (currentIndex % state.columnCount)];
+    return lastRowIndex + (index % state.columnCount);
   }
-  return getLast(id, {state});
+  return getLast(index, {state});
 };
 
-const getItem: NavigationRequestor = (id, {state}) => {
-  const item = id ? state.items.find(item => getId(item) === id) : getFirst(id, {state}); // no id, return first item
+const getItem: (id: string, model: NavigationInput) => Item<Generic> = (id, {state}) => {
+  const item = id ? state.items.find(item => item.id === id) : state.items[0]; // no id, return first item
   assert(item, `Item not found: ${id}`);
   return item;
 };
 
 export const getWrappingOffsetItem = (offset: number) => (
-  id: string,
+  index: number,
   {state}: NavigationInput,
   tries = state.items.length
-): Item<Generic> => {
+): number => {
+  if (Number.isNaN(index)) {
+    // we have no valid index. If the offset is positive, we'll return the first item
+    if (offset === 1) {
+      return getFirst(index, {state});
+    }
+    if (offset === -1) {
+      return getLast(index, {state});
+    }
+  }
   const items = state.items;
-  const item = getItem(id, {state});
 
-  const currentIndex = item.index;
-  let nextIndex = currentIndex + offset;
+  let nextIndex = index + offset;
 
   // calculate idealLength as in if the grid was a perfect rectangle
   const rows = Math.ceil(items.length / state.columnCount);
@@ -178,34 +184,32 @@ export const getWrappingOffsetItem = (offset: number) => (
     }
   }
 
-  if (state.nonInteractiveIds.includes(getId(items[nextIndex])) && tries > 0) {
+  if (items.length > 1 && state.nonInteractiveIds.includes(items[nextIndex].id) && tries > 0) {
     // The next item is disabled, try again, but only if we haven't already tried everything.
     // Avoid an infinite loop with `tries`
-    return getWrappingOffsetItem(offset)(getId(items[nextIndex]), {state}, tries - 1);
+    return getWrappingOffsetItem(offset)(nextIndex, {state}, tries - 1);
   }
 
-  return items[nextIndex];
+  return nextIndex;
 };
 
 export const getOffsetItem = (offset: number) => (
-  id: string,
+  index: number,
   {state}: NavigationInput,
   tries = state.items.length
-): Item<Generic> => {
+): number => {
   const {items, columnCount} = state;
-  const item = getItem(id, {state});
 
-  const currentIndex = item.index;
-  let nextIndex = currentIndex + offset;
+  let nextIndex = index + offset;
 
   if (Math.abs(offset) < columnCount) {
     // if we're here, the columnCount is non-zero and the absolute value of offset is less than the
     // column count. We don't want to wrap, so we'll bound within the row
 
-    const currentIndexInRow = currentIndex % columnCount;
-    const nextIndexInRow = nextIndex - currentIndex + currentIndexInRow;
+    const currentIndexInRow = index % columnCount;
+    const nextIndexInRow = nextIndex - index + currentIndexInRow;
     if (nextIndexInRow >= columnCount || nextIndexInRow < 0) {
-      nextIndex = currentIndex;
+      nextIndex = index;
     }
   } else if (columnCount) {
     // if we're here, there's a column count, but the offset will move into another row. We need to
@@ -213,12 +217,12 @@ export const getOffsetItem = (offset: number) => (
     const nextRow = Math.floor(nextIndex / columnCount);
 
     if (nextRow < 0 || nextRow >= columnCount) {
-      nextIndex = currentIndex;
+      nextIndex = index;
     }
 
     // make sure we don't go out of bounds if the grid isn't a perfect rectangle
     if (nextIndex > items.length - 1) {
-      nextIndex = currentIndex;
+      nextIndex = index;
     }
   }
 
@@ -229,13 +233,13 @@ export const getOffsetItem = (offset: number) => (
     nextIndex = items.length - 1;
   }
 
-  if (state.nonInteractiveIds.includes(getId(items[nextIndex])) && tries > 0) {
+  if (state.nonInteractiveIds.includes(items[nextIndex].id) && tries > 0) {
     // The next item is disabled, try again, but only if we haven't already tried everything.
     // Avoid an infinite loop with `tries`
-    return getOffsetItem(offset)(getId(items[nextIndex]), {state}, tries - 1);
+    return getOffsetItem(offset)(nextIndex, {state}, tries - 1);
   }
 
-  return items[nextIndex];
+  return nextIndex;
 };
 
 /**
@@ -248,9 +252,9 @@ export const wrappingNavigationManager = createNavigationManager({
   getLast,
   getItem,
   getNext: getWrappingOffsetItem(1),
-  getNextRow: (id, {state}) => getWrappingOffsetItem(state.columnCount)(id, {state}),
+  getNextRow: (index, {state}) => getWrappingOffsetItem(state.columnCount)(index, {state}),
   getPrevious: getWrappingOffsetItem(-1),
-  getPreviousRow: (id, {state}) => getWrappingOffsetItem(-state.columnCount)(id, {state}),
+  getPreviousRow: (index, {state}) => getWrappingOffsetItem(-state.columnCount)(index, {state}),
   getPreviousPage,
   getNextPage,
   getFirstOfRow,
@@ -266,15 +270,17 @@ export const navigationManager = createNavigationManager({
   getLast,
   getItem,
   getNext: getOffsetItem(1),
-  getNextRow: (id, {state}) => getOffsetItem(state.columnCount)(id, {state}),
+  getNextRow: (index, {state}) => getOffsetItem(state.columnCount)(index, {state}),
   getPrevious: getOffsetItem(-1),
-  getPreviousRow: (id, {state}) => getOffsetItem(-state.columnCount)(id, {state}),
+  getPreviousRow: (index, {state}) => getOffsetItem(-state.columnCount)(index, {state}),
   getPreviousPage,
   getNextPage,
   getFirstOfRow,
   getLastOfRow,
 });
 
+type Writeable<T> = {-readonly [P in keyof T]: T[P]};
+
 /**
  * A `CursorModel` extends a `ListModel` and adds a "cursor" to the list. A cursor is a pointer to a
  * current position in the list. The most common use-case is keeping track of which item currently
@@ -305,16 +311,36 @@ export const useCursorListModel = createModelHook({
      * well as left/right keys to give a more consistent experience to all users.
      */
     navigation: wrappingNavigationManager,
+    /**
+     * Controls how much a pageUp/pageDown navigation request will jump. If not provided, the size
+     * of the list and number of items rendered will determine this value.
+     */
+    pageSize: 0,
   },
   requiredConfig: useBaseListModel.requiredConfig,
+  contextOverride: useBaseListModel.Context,
 })(config => {
   const [cursorId, setCursorId] = React.useState(config.initialCursorId);
+  const pageSizeRef = React.useRef(config.pageSize);
   const columnCount = config.columnCount || 0;
   const list = useBaseListModel(config);
-  const initialCurrentRef = React.useRef(
-    config.initialCursorId || (config.items?.length ? getId(config.items![0]) : '')
-  );
   const navigation = config.navigation;
+  // Cast as a readonly to signify this value should never be set
+  const cursorIndexRef = React.useRef(-1) as {readonly current: number};
+  const setCursor = (index: number) => {
+    const id = state.items[index]?.id || '';
+    setCursorId(id);
+  };
+
+  // Keep the cursorIndex up to date with the cursor ID
+  if (cursorId && list.state.items[cursorIndexRef.current]?.id !== cursorId) {
+    // We cast back as a writeable because this is the only place the value should be changed.
+    (cursorIndexRef as Writeable<typeof cursorIndexRef>).current = list.state.items.findIndex(
+      item => item.id === cursorId
+    );
+  } else if (!cursorId) {
+    (cursorIndexRef as Writeable<typeof cursorIndexRef>).current = -1;
+  }
 
   const state = {
     ...list.state,
@@ -326,25 +352,27 @@ export const useCursorListModel = createModelHook({
      * @private Use useGridModel instead to make a grid instead of a list
      */
     columnCount,
+    /**
+     * A React.Ref of the current page size. Either provided as config, or determined at runtime
+     * based on the size of the list container and the number of items fitting within the container.
+     */
+    pageSizeRef,
+    /**
+     * A readonly [React.Ref](https://react.dev/learn/referencing-values-with-refs) that tracks the
+     * index of the `state.cursorId`. This value is automatically updated when the `state.cursorId`
+     * or the `items` change.
+     *
+     * @readonly
+     */
+    cursorIndexRef,
   };
 
   const events = {
     ...list.events,
-    /**
-     * Register an item to the list. Takes in an identifier, a React.Ref and an optional index. This
-     * should be called on component mount
-     */
-    registerItem(data: Parameters<typeof list.events.registerItem>[0]) {
-      // point the cursor at the first item
-      if (!initialCurrentRef.current) {
-        initialCurrentRef.current = getId(data.item);
-        setCursorId(initialCurrentRef.current);
-      }
-      list.events.registerItem(data);
-    },
     /** Directly sets the cursor to the list item by its identifier. */
     goTo(data: {id: string}) {
-      setCursorId(data.id);
+      const index = state.items.findIndex(item => item.id === data.id);
+      setCursor(index);
     },
     /**
      * Set the cursor to the "next" item in the list. This event delegates to the `getNext` method of
@@ -353,14 +381,16 @@ export const useCursorListModel = createModelHook({
      * item in a row.
      */
     goToNext() {
-      setCursorId(getId(navigation.getNext(state.cursorId, {state})));
+      const index = navigation.getNext(cursorIndexRef.current, {state});
+      setCursor(index);
     },
     /**
      * Set the cursor to the "previous" item in the list. If the beginning of the list is detected,
      * it will wrap to the last item
      */
     goToPrevious() {
-      setCursorId(getId(navigation.getPrevious(state.cursorId, {state})));
+      const index = navigation.getPrevious(cursorIndexRef.current, {state});
+      setCursor(index);
     },
     /**
      * Previous item perpendicular to the orientation of a list, or the previous row in a grid. For
@@ -369,13 +399,10 @@ export const useCursorListModel = createModelHook({
      * this would be the previous row (current position - column count).
      */
     goToPreviousRow() {
-      setCursorId(
-        getId(
-          navigation.getPreviousRow(state.cursorId, {
-            state,
-          })
-        )
-      );
+      const index = navigation.getPreviousRow(cursorIndexRef.current, {
+        state,
+      });
+      setCursor(index);
     },
     /**
      * Next item perpendicular to the orientation of a list, or the next row in a grid. For example,
@@ -384,33 +411,36 @@ export const useCursorListModel = createModelHook({
      * next row (current position + column count).
      */
     goToNextRow() {
-      setCursorId(getId(navigation.getNextRow(state.cursorId, {state})));
+      const index = navigation.getNextRow(cursorIndexRef.current, {state});
+      setCursor(index);
     },
     /** Set the cursor to the first item in the list */
     goToFirst() {
-      setCursorId(getId(navigation.getFirst(state.cursorId, {state})));
+      const index = navigation.getFirst(cursorIndexRef.current, {state});
+      setCursor(index);
     },
     /** Set the cursor to the last item in the list */
     goToLast() {
-      setCursorId(getId(navigation.getLast(state.cursorId, {state})));
+      const index = navigation.getLast(cursorIndexRef.current, {state});
+      setCursor(index);
     },
     goToFirstOfRow() {
-      setCursorId(getId(navigation.getFirstOfRow(state.cursorId, {state})));
+      const index = navigation.getFirstOfRow(cursorIndexRef.current, {state});
+      setCursor(index);
     },
     goToLastOfRow() {
-      setCursorId(getId(navigation.getLastOfRow(state.cursorId, {state})));
+      const index = navigation.getLastOfRow(cursorIndexRef.current, {state});
+      setCursor(index);
     },
     goToNextPage() {
-      setCursorId(getId(navigation.getNextPage(state.cursorId, {state})));
+      const index = navigation.getNextPage(cursorIndexRef.current, {state});
+      setCursor(index);
     },
     goToPreviousPage() {
-      setCursorId(
-        getId(
-          navigation.getPreviousPage(state.cursorId, {
-            state,
-          })
-        )
-      );
+      const index = navigation.getPreviousPage(cursorIndexRef.current, {
+        state,
+      });
+      setCursor(index);
     },
   };
 

package/collection/lib/useGridModel.ts

@@ -4,6 +4,10 @@ import {useListModel} from './useListModel';
 
 const {columnCount, orientation, ...defaultConfig} = useListModel.defaultConfig;
 
+/**
+ * The Grid model extends the `ListModel` and changes some config. For example, the `columnCount` is
+ * required on the grid model's configuration and `orientation` is removed.
+ */
 export const useGridModel = createModelHook({
   defaultConfig: {
     ...defaultConfig,

package/collection/lib/useListActiveDescendant.ts

@@ -0,0 +1,24 @@
+import {createElemPropsHook, slugify} from '@workday/canvas-kit-react/common';
+
+import {useCursorListModel} from './useCursorListModel';
+
+/**
+ * This elemProps hook is used for cursor navigation by using [Active
+ * Descendant](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_activedescendant).
+ * `aria-activedescendant` tells assistive technology which element has "focus" within the component
+ * while this single element maintains focus.
+ *
+ * ```ts
+ * const useMyItem = composeHooks(
+ *   useListActiveDescendant, // adds `aria-activedescendant` support
+ *   useListItemRegister
+ * );
+```
+ */
+export const useListActiveDescendant = createElemPropsHook(useCursorListModel)(model => {
+  return {
+    'aria-activedescendant': model.state.cursorId
+      ? slugify(`${model.state.id}-${model.state.cursorId}`)
+      : undefined,
+  };
+});

package/collection/lib/useListItemAllowChildStrings.ts

@@ -0,0 +1,38 @@
+import {createElemPropsHook} from '@workday/canvas-kit-react/common';
+import {useListModel} from '@workday/canvas-kit-react/collection';
+
+/**
+ * This elemProps hook allows for children values to be considered identifiers if the children are
+ * strings. This can be useful for autocomplete or select components that allow string values. This
+ * hook must be passed _after_ {@link useListItemRegister} because this hook sets the `data-id`
+ * attribute if one hasn't been defined by the application.
+ *
+ * An example might look like:
+ *
+ * ```tsx
+ * const useMyListItem = composeHooks(
+ *   // any other hooks here
+ *   useListItemSelect,
+ *   useListItemRegister,
+ *   useListItemAllowChildStrings // always the last in the list
+ * )
+ *
+ *
+ * <MyList onSelect={({id}) => {
+ *   console.log(id) // will be "First" or "Second"
+ * }}>
+ *   <MyList.Item>First</MyList.Item>
+ *   <MyList.Item>Second</MyList.Item>
+ * </MyList>
+ * ```
+ */
+export const useListItemAllowChildStrings = createElemPropsHook(useListModel)(
+  (_, __, elemProps: {'data-id'?: string; children?: React.ReactNode} = {}) => {
+    const props: {'data-id'?: string} = {};
+    if (!elemProps['data-id'] && typeof elemProps.children === 'string') {
+      props['data-id'] = elemProps.children;
+    }
+
+    return props;
+  }
+);

package/collection/lib/useListItemRegister.tsx

@@ -5,6 +5,7 @@ import {
   createElemPropsHook,
   useLocalRef,
   useForkRef,
+  slugify,
 } from '@workday/canvas-kit-react/common';
 
 import {Item} from './useBaseListModel';
@@ -12,15 +13,25 @@ import {VirtualItem} from './react-virtual';
 import {useListModel} from './useListModel';
 
 /**
- * Registers an item with a list. It will return elemProps with a `data-id` which can be used by other
- * hooks to identify the item in the list.
+ * 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
+ * );
+ * ```
  */
 export const useListItemRegister = createElemPropsHook(useListModel)(
   (
-    {state, events, getId},
-    ref?: React.Ref<HTMLElement>,
+    {state, events},
+    ref,
     elemProps: {
       'data-id'?: string;
+      'data-text'?: string;
       children?: React.ReactNode;
       index?: number;
       disabled?: boolean;
@@ -29,7 +40,9 @@ export const useListItemRegister = createElemPropsHook(useListModel)(
     } = {}
   ) => {
     const [localId, setLocalId] = React.useState(elemProps['data-id'] || elemProps.item?.id || '');
-    const {localRef, elementRef} = useLocalRef(useForkRef(ref, elemProps.virtual?.measureRef));
+    const {localRef, elementRef} = useLocalRef(
+      useForkRef(ref as React.Ref<HTMLElement>, elemProps.virtual?.measureRef)
+    );
 
     // if the list is virtual, force the correct styling. Without this, weird things happen...
     const style: CSSProperties = elemProps.virtual
@@ -55,14 +68,18 @@ export const useListItemRegister = createElemPropsHook(useListModel)(
 
       // TODO: Better lookup that using `items.find`. We need a more generic collection to handle seeing if an item already exists
       // bail early if item already exists. This happens if items were already provided.
-      if (state.items.find(item => getId(item) === itemId)) {
+      if (state.items.find(item => item.id === itemId)) {
         return;
       }
       events.registerItem({
         item: {
           id: itemId,
         },
-        textValue: typeof elemProps.children === 'string' ? elemProps.children : '',
+        textValue: elemProps['data-text']
+          ? elemProps['data-text']
+          : typeof elemProps.children === 'string'
+          ? elemProps.children
+          : '',
       });
       setLocalId(itemId);
 
@@ -80,6 +97,7 @@ export const useListItemRegister = createElemPropsHook(useListModel)(
       'aria-setsize': elemProps.virtual?.size,
       'aria-posinset': elemProps.virtual ? elemProps.item!.index + 1 : undefined,
       style,
+      id: slugify(`${state.id}-${localId}`),
     };
   }
 );