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

package/collection/lib/useCursorListModel.tsx

@@ -1,22 +1,50 @@
 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. */
   getFirst: NavigationRequestor;
+  /** Get the last item in a collection. This will be called when the `End` key is pressed for Lists
+   * and `Ctrl+End` for Grids. */
   getLast: NavigationRequestor;
-  getItem: NavigationRequestor;
+  /** Get an item with the provided `id`. */
+  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;
+  /** **For Grids:** Get the cell in the next row from the provided `id`. This will be called when
+   * the `Down` arrow is pressed.  */
   getNextRow: NavigationRequestor;
+  /** Get the previous item before the provided `id`. This will be called when the `Left` arrow key
+   * is pressed for RTL languages and when the `Right` arrow is pressed for LTR languages. */
   getPrevious: NavigationRequestor;
+  /** **For Grids:** Get the cell in the previous row from the provided `id`. This will be called
+   * when the `Up` arrow is pressed.  */
   getPreviousRow: NavigationRequestor;
+  /** **For Grids:** Get the first item in a row. This will be called when the `Home` key is
+   * pressed. */
   getFirstOfRow: NavigationRequestor;
+  /** **For Grids:** Get the last item in a row. This will be called when the `End` key is
+   * pressed. */
   getLastOfRow: NavigationRequestor;
-  getPreviousPage: NavigationRequestor;
+  /** Get the next "page". A "page" is application specific and usually means next visible screen.
+   * If the viewport is scrollable, it would scroll so that the last item visible is now the first
+   * item visible. This is called when the `PageDown` key is pressed */
   getNextPage: NavigationRequestor;
+  /** Get the next "page". A "page" is application specific and usually means previous visible
+   * screen. If the viewport is scrollable, it would scroll so that the first item visible is now
+   * the last item visible. This is called when the `PageUp` key is pressed */
+  getPreviousPage: NavigationRequestor;
 }
 
 /**
@@ -38,174 +66,221 @@ 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 = state.items.findIndex(i => getId(item) === getId(i));
-    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 = state.items.findIndex(i => getId(item) === getId(i));
-    const offset = (currentIndex % state.columnCount) - state.columnCount + 1;
-    return state.items[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 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 = state.items.findIndex(i => getId(item) === getId(i));
-    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 = state.items.findIndex(i => getId(item) === getId(i));
     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 = items.findIndex(i => getId(item) === getId(i));
-  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);
+  const idealLength = rows * state.columnCount;
   if (nextIndex < 0) {
-    nextIndex = items.length + nextIndex;
+    if (offset === -1) {
+      // if the offset is -1, we want to wrap to the end
+      nextIndex = items.length - 1;
+    } else {
+      // if the offset is smaller than -1, we want to wrap by column
+      if (idealLength + nextIndex >= items.length) {
+        // we'll overflow the grid because there isn't enough items. Move `nextIndex` up so we wrap in
+        // the right spot
+        nextIndex -= state.columnCount;
+      }
+      nextIndex = idealLength + nextIndex;
+    }
   } else if (nextIndex >= items.length) {
-    nextIndex = nextIndex - items.length;
+    if (offset === 1) {
+      // if the offset is 1, we want to wrap to the beginning
+      nextIndex = 0;
+    } else {
+      // if the offset is larger than 1, we want to wrap by column
+      if (nextIndex - idealLength < 0) {
+        // we're going to overflow the grid because there isn't enough items. Move `nextIndex` down to
+        // the missing item in the next row. This way we'll end up wrapping in the right spot
+        nextIndex += state.columnCount;
+      }
+      nextIndex = nextIndex - idealLength;
+    }
   }
 
-  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 = items.findIndex(i => getId(item) === getId(i));
-  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
     // bound to row values
     const nextRow = Math.floor(nextIndex / columnCount);
+
     if (nextRow < 0 || nextRow >= columnCount) {
-      nextIndex = currentIndex;
+      nextIndex = index;
     }
-  } else if (nextIndex < 0) {
+
+    // make sure we don't go out of bounds if the grid isn't a perfect rectangle
+    if (nextIndex > items.length - 1) {
+      nextIndex = index;
+    }
+  }
+
+  // make sure we're always in bounds
+  if (nextIndex < 0) {
     nextIndex = 0;
   } else if (nextIndex >= items.length) {
     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;
 };
 
 /**
- * The default navigation manager of lists
+ * The default navigation manager of lists. This navigation manager will wrap around when the edge
+ * is hit. For example, if the user is the the right-most item in a list or right-most item in a
+ * row, the cursor will wrap around to the beginning or the next row.
  */
 export const wrappingNavigationManager = createNavigationManager({
   getFirst,
   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,
   getLastOfRow,
 });
 
+/**
+ * The default navigation of grids. This navigation manager will not wrap, but will stop when an
+ * edge is detected. This could be the last item in a list or the last item of a row in a grid.
+ */
 export const navigationManager = createNavigationManager({
   getFirst,
   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
@@ -229,24 +304,43 @@ export const useCursorListModel = createModelHook({
      * (left-to-right or right-to-left) and call the correct navigation method. In our example, a
      * left-to-right language would send a `getNext`. The navigation manager may return the next item
      * in the list. Different managers can be created for slightly different use cases. The default
-     * navigation manager will accept `orientation` and directionality to determine mapping. If
-     * `columnCount` is non-zero, it will use a grid mode where `orientation` is ignored and only
-     * directionality matters.
+     * navigation manager will accept `orientation` and directionality to determine mapping.
      *
      * An example override might be a tab list with an overflow menu that is meant to be transparent
      * to screen reader users. This would require the overflow menu to accept both up/down keys as
      * 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,
@@ -255,28 +349,30 @@ export const useCursorListModel = createModelHook({
     /**
      * Any positive non-zero value treats the list like a grid with rows and columns
      * @default 0
+     * @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 navigation = config.navigation || wrappingNavigationManager;
 
   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
@@ -285,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
@@ -301,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,
@@ -316,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

@@ -0,0 +1,38 @@
+import {createModelHook} from '@workday/canvas-kit-react/common';
+import {navigationManager} from './useCursorListModel';
+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,
+    /**
+     * Controls the state changes when the user sends navigation events to the model. For example,
+     * when the user hits the "right" arrow, a behavior hook will determine directionality
+     * (left-to-right or right-to-left) and call the correct navigation method. In our example, a
+     * left-to-right language would send a `getNext`. The navigation manager may return the next
+     * item in the list. Different managers can be created for slightly different use cases. The
+     * default navigation manager will stop when the end of a row/column is detected. For example,
+     * `getNext` will return the same item the cursor was previously on if the cursor is on the last
+     * item of a row.
+     */
+    navigation: navigationManager,
+  },
+  requiredConfig: {
+    /**
+     * The number of columns represented in a grid
+     */
+    columnCount: 1,
+    ...useListModel.requiredConfig,
+  },
+  contextOverride: useListModel.Context,
+})(config => {
+  const list = useListModel(config);
+
+  return list;
+});

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;
+  }
+);