@workday/canvas-kit-react 9.0.0-alpha.411-next.13 → 9.0.0-alpha.413-next.15

package/collection/lib/useBaseListModel.tsx

@@ -1,13 +1,12 @@
 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 item.id || '';
 };
 
 export const defaultGetTextValue = (item: any): string => {
@@ -79,14 +78,18 @@ 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,
-
+    /**
+     * 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) => (item.text || '') as string,
     /**
      * Array of all ids which are currently disabled. This is used for navigation to skip over items
@@ -112,8 +115,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 +137,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({

package/collection/lib/useCursorListModel.tsx

@@ -18,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;
@@ -69,90 +69,89 @@ export const createNavigationManager = (manager: NavigationManager) => manager;
 /**
  * Given an id and a model, return an item from the collection
  */
-export type NavigationRequestor = (id: string, model: NavigationInput) => Item<Generic>;
+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);
@@ -185,34 +184,32 @@ export const getWrappingOffsetItem = (offset: number) => (
     }
   }
 
-  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 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
@@ -220,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;
     }
   }
 
@@ -236,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;
 };
 
 /**
@@ -255,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,
@@ -273,9 +270,9 @@ 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,
@@ -312,16 +309,35 @@ 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(list.state.items![0]) : '')
+    config.initialCursorId || (config.items?.length ? list.state.items![0].id : '')
   );
   const navigation = config.navigation;
+  const cursorIndexRef = React.useRef(-1);
+  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) {
+    cursorIndexRef.current = list.state.items.findIndex(item => item.id === cursorId);
+  } else if (!cursorId) {
+    cursorIndexRef.current = -1;
+  }
 
   const state = {
     ...list.state,
@@ -333,6 +349,11 @@ 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,
   };
 
   const events = {
@@ -351,7 +372,8 @@ export const useCursorListModel = createModelHook({
     },
     /** 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
@@ -360,14 +382,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
@@ -376,13 +400,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,
@@ -391,33 +412,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/dialog/lib/Dialog.tsx

@@ -14,16 +14,82 @@ export interface DialogProps {
   children: React.ReactNode;
 }
 
+/**
+ * This component is the container component and does not render any semantic elements. It provides
+ * a React Context model for the `Dialog` subcomponents. If you manually pass a `model` to all
+ * subcomponents, this container component isn't needed. If you do not pass a `model`, the `Dialog`
+ * container component will build a default one using `useDialogModel`. `Dialog` is a composition of a
+ * {@link Popup} component and has a similar structure to `Popup`.
+ */
 export const Dialog = createContainer()({
   displayName: 'Dialog',
   modelHook: useDialogModel,
   subComponents: {
+    /**
+     * A `Dialog.Body` is a thin wrapper around {@link CardBody Card.Body} and doesn't actually take
+     * a model. It adds `body` styling and nothing else.
+     */
     Body: Popup.Body,
+    /**
+     * A `Dialog.Card` is a wrapper around the {@link Card} component, but hooked up to a
+     * {@link DialogModel}. By default, this element has a `role=dialog`, `aria-labelledby` and an `id`.
+     * The behavior hook used is called {@link useDialogCard}.
+     */
     Card: DialogCard,
+    /**
+     * A `Dialog.CloseIcon` is an icon button that is the `X` at the top of a dialog. It will hide a
+     * dialog when clicked. The behavior hook used is called {@link usePopupCloseButton}.
+     */
     CloseIcon: Popup.CloseIcon,
+    /**
+     * A `Dialog.Target` is any element that is meant to show the Dialog. The default component
+     * rendered by this component is a {@link SecondaryButton} element. You can override this by
+     * passing the desired component via `as`. Many examples above use `as={DeleteButton}`. If you
+     * want to render a {@link TertiaryButton} instead, use `as={TertiaryButton}`. The behavior hook
+     * used is called {@link usePopupTarget}.
+     *
+     * ```tsx
+     * const model = useDialogModel();
+     *
+     * // using this component
+     * <Dialog.Target>Show Dialog</Dialog.Target>
+     *
+     * // using props instead
+     * const dialogTargetButtonProps = useDialogTarget(model);
+     * <SecondaryButton {...dialogTargetButtonProps}>Show Dialog</SecondaryButton>
+     * ```
+     *
+     * `Dialog.Target` doesn't provide any styling by default. All styling comes from the default
+     * component used, which is {@link SecondaryButton}. If you don't want any styling, you can do
+     * the following:
+     *
+     * ```tsx
+     * <Dialog.Target as="button">Open</Dialog.Target>
+     * ```
+     *
+     * To add your own styling, you could either add a `css` prop, or make a styled button and pass
+     * that styled component via the `as` prop.
+     */
     Target: Popup.Target,
+    /**
+     * A `Dialog.Heading` is a wrapper around {@link CardHeading Card.Heading} that connect the
+     * heading to a {@link DialogModel}. It will add an `id` to the element that match the
+     * `aria-labelledby` that is applied to the `Dialog.Card` element for accessibility. The behavior
+     * hook used is called {@link usePopupHeading}.
+     */
     Heading: Popup.Heading,
+    /**
+     * A `Dialog.Popper` is a wrapper around {@link PopupPopper Popup.Popper}. The behavior
+     * hook used is called {@link useDialogPopper}.
+     */
+
     Popper: DialogPopper,
+    /**
+     * A `Dialog.CloseButton` is a button that will hide a dialog. By default, this is a
+     * {@link SecondaryButton} component, but `as` can be used to render any button element (i.e
+     * {@link DeleteButton} or {@link PrimaryButton}). The behavior hook used is called
+     * {@link usePopupCloseButton}.
+     */
     CloseButton: Popup.CloseButton,
   },
 })(({children}: DialogProps) => {