@workday/canvas-kit-react 13.0.0-alpha.944-next.0 → 13.0.0-alpha.950-next.0

package/collection/index.ts

@@ -15,6 +15,9 @@ export * from './lib/useGridModel';
 export * from './lib/useListActiveDescendant';
 export * from './lib/useListItemActiveDescendant';
 export * from './lib/useListItemAllowChildStrings';
+export * from './lib/useListItemRemoveOnDeleteKey';
+export * from './lib/focusOnCurrentCursor';
+export * from './lib/listItemRemove';
 export {ListBox, ListBoxProps} from './lib/ListBox';
 export {keyboardEventToCursorEvents} from './lib/keyUtils';
 export {

package/collection/lib/focusOnCurrentCursor.ts

@@ -0,0 +1,55 @@
+import {useCursorListModel} from './useCursorListModel';
+
+// retry a function each frame so we don't rely on the timing mechanism of React's render cycle.
+const retryEachFrame = (cb: () => boolean, iterations: number, reject?: (reason?: any) => void) => {
+  if (cb() === false && iterations > 1) {
+    requestAnimationFrame(() => retryEachFrame(cb, iterations - 1));
+  }
+  reject?.('Retry timeout');
+};
+
+export const focusOnCurrentCursor = (
+  model: ReturnType<typeof useCursorListModel>,
+  nextId: string,
+  /**
+   * This can be any element in the list. It is used only to get the client-id from the element in
+   * case it is different than the server ID when DOM is hydrated.
+   */
+  element?: HTMLElement
+) => {
+  return new Promise<HTMLElement | null>((resolve, reject) => {
+    // Attempt to extract the ID from the DOM element. This fixes issues where the server and client
+    // do not agree on a generated ID
+    const clientId = (element?.dataset?.focusId || '').split('-')[0] || model.state.id;
+
+    const item = model.navigation.getItem(nextId, model);
+
+    if (item) {
+      // If the list is virtualized, we need to manually call out to the virtual list's
+      // `scrollToIndex`
+      if (model.state.isVirtualized) {
+        model.state.UNSTABLE_virtual.scrollToIndex(item.index);
+      }
+
+      const getElement = (id?: string) => {
+        return document.querySelector<HTMLElement>(`[data-focus-id="${`${id}-${item.id}`}"]`);
+      };
+
+      // In React concurrent mode, there could be several render attempts before the element we're
+      // looking for could be available in the DOM
+      retryEachFrame(
+        () => {
+          const element = getElement(clientId) || getElement(model.state.id);
+
+          if (element) {
+            element.focus();
+            resolve(element);
+          }
+          return !!element;
+        },
+        5,
+        reject
+      ); // 5 should be enough, right?!
+    }
+  });
+};

package/collection/lib/listItemRemove.ts

@@ -0,0 +1,21 @@
+import {useSelectionListModel} from './useSelectionListModel';
+
+export const listItemRemove = (
+  id: string,
+  model: ReturnType<typeof useSelectionListModel>
+): string | undefined => {
+  // bail early if an ID isn't available
+  if (!id) {
+    return;
+  }
+
+  const index = model.state.items.findIndex(item => item.id === model.state.cursorId);
+  const nextIndex = index === model.state.items.length - 1 ? index - 1 : index + 1;
+  const nextId = model.state.items[nextIndex]?.id;
+  if (nextId && model.state.cursorId === id) {
+    // We're removing the currently focused item. Focus next item
+    model.events.goTo({id: nextId});
+  }
+
+  return nextId;
+};

package/collection/lib/useListItemRemoveOnDeleteKey.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import {createElemPropsHook} from '@workday/canvas-kit-react/common';
+
+import {useSelectionListModel} from './useSelectionListModel';
+import {focusOnCurrentCursor} from './focusOnCurrentCursor';
+import {listItemRemove} from './listItemRemove';
+
+/**
+ * This elemProps hook is used when a menu item is expected to be removed. It will advance the cursor to
+ * another item.
+ * This elemProps hook is used for cursor navigation by using [Roving
+ * Tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#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
+ * );
+ * ```
+ */
+export const useListItemRemoveOnDeleteKey = createElemPropsHook(useSelectionListModel)(model => {
+  return {
+    onKeyDown(event: React.KeyboardEvent<HTMLElement>) {
+      if (event.key === 'Backspace' || event.key === 'Delete') {
+        const id = event.currentTarget.dataset.id || '';
+        const nextId = listItemRemove(id, model);
+        model.events.remove({id, nextId, event});
+        if (nextId) {
+          // use an animation frame to wait for any other model changes that may happen
+          requestAnimationFrame(() => {
+            focusOnCurrentCursor(model, nextId, event.currentTarget);
+          });
+        }
+      }
+    },
+  };
+});

package/collection/lib/useListItemRovingFocus.tsx

@@ -3,13 +3,7 @@ import {useIsRTL, createElemPropsHook} from '@workday/canvas-kit-react/common';
 
 import {useCursorListModel} from './useCursorListModel';
 import {keyboardEventToCursorEvents} from './keyUtils';
-
-// retry a function each frame so we don't rely on the timing mechanism of React's render cycle.
-const retryEachFrame = (cb: () => boolean, iterations: number) => {
-  if (cb() === false && iterations > 1) {
-    requestAnimationFrame(() => retryEachFrame(cb, iterations - 1));
-  }
-};
+import {focusOnCurrentCursor} from './focusOnCurrentCursor';
 
 /**
  * This elemProps hook is used for cursor navigation by using [Roving
@@ -33,36 +27,16 @@ export const useListItemRovingFocus = createElemPropsHook(useCursorListModel)(
     const stateRef = React.useRef(model.state);
     stateRef.current = model.state;
 
-    const keyElementRef = React.useRef<Element | null>(null);
+    const keyElementRef = React.useRef<HTMLElement | null>(null);
     const isRTL = useIsRTL();
 
     React.useEffect(() => {
+      // If the cursor change was triggered by this hook, we should change focus
       if (keyElementRef.current) {
-        const item = model.navigation.getItem(model.state.cursorId, model);
-        if (item) {
-          if (model.state.isVirtualized) {
-            model.state.UNSTABLE_virtual.scrollToIndex(item.index);
-          }
-
-          const selector = (id?: string) => {
-            return document.querySelector<HTMLElement>(`[data-focus-id="${`${id}-${item.id}`}"]`);
-          };
-
-          // In React concurrent mode, there could be several render attempts before the element we're
-          // looking for could be available in the DOM
-          retryEachFrame(() => {
-            // Attempt to extract the ID from the DOM element. This fixes issues where the server and client
-            // do not agree on a generated ID
-            const clientId = keyElementRef.current?.getAttribute('data-focus-id')?.split('-')[0];
-            const element = selector(clientId) || selector(model.state.id);
-
-            element?.focus();
-            if (element) {
-              keyElementRef.current = null;
-            }
-            return !!element;
-          }, 5); // 5 should be enough, right?!
-        }
+        focusOnCurrentCursor(model, model.state.cursorId, keyElementRef.current).then(() => {
+          // Reset key element since focus was successful
+          keyElementRef.current = null;
+        });
       }
       // we only want to run this effect if the cursor changes and not any other time
       // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -76,7 +50,7 @@ export const useListItemRovingFocus = createElemPropsHook(useCursorListModel)(
     }, [model.state.cursorId, model.state.items, model.events]);
 
     return {
-      onKeyDown(event: React.KeyboardEvent) {
+      onKeyDown(event: React.KeyboardEvent<HTMLElement>) {
         const handled = keyboardEventToCursorEvents(event, model, isRTL);
         if (handled) {
           event.preventDefault();

package/collection/lib/useListLoader.ts

@@ -269,6 +269,8 @@ export function useListLoader<
 
   const model = modelHook(
     modelHook.mergeConfig(config, {
+      // Loaders should virtualize by default. If they do not, it is an infinite scroll list
+      shouldVirtualize: true,
       items,
       shouldGoToNext: shouldLoadIndex('getNext', 'goToNext'),
       shouldGoToPrevious: shouldLoadIndex('getPrevious', 'goToPrevious'),

package/collection/lib/useListResetCursorOnBlur.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 
-import {createElemPropsHook} from '@workday/canvas-kit-react/common';
+import {createElemPropsHook, useMountLayout} from '@workday/canvas-kit-react/common';
 import {orientationKeyMap} from './keyUtils';
 import {useListModel} from './useListModel';
 
@@ -20,6 +20,15 @@ import {useListModel} from './useListModel';
  */
 export const useListResetCursorOnBlur = createElemPropsHook(useListModel)(({state, events}) => {
   const programmaticFocusRef = React.useRef(false);
+  const requestAnimationFrameRef = React.useRef(0);
+
+  useMountLayout(() => {
+    return () => {
+      // Cancelling the animation frame prevents React unmount errors
+      cancelAnimationFrame(requestAnimationFrameRef.current);
+    };
+  });
+
   return {
     onKeyDown(event: React.KeyboardEvent) {
       // Programmatic focus only on any focus change via keyboard
@@ -32,7 +41,12 @@ export const useListResetCursorOnBlur = createElemPropsHook(useListModel)(({stat
     },
     onBlur() {
       if (!programmaticFocusRef.current) {
-        events.goTo({id: state.selectedIds[0]});
+        // use an animation frame to wait for any other model changes that may happen on a blur
+        requestAnimationFrameRef.current = requestAnimationFrame(() => {
+          if (state.selectedIds[0] !== state.cursorId) {
+            events.goTo({id: state.selectedIds[0]});
+          }
+        });
       }
     },
   };

package/collection/lib/useOverflowListItemMeasure.tsx

@@ -26,17 +26,21 @@ export const useOverflowListItemMeasure = createElemPropsHook(useOverflowListMod
     useMountLayout(() => {
       if (localRef.current) {
         const styles = getComputedStyle(localRef.current);
-        model.events.addItemWidth({
+        model.events.addItemSize({
           id: name,
           width:
             localRef.current.offsetWidth +
             parseFloat(styles.marginLeft) +
             parseFloat(styles.marginRight),
+          height:
+            localRef.current.offsetHeight +
+            parseFloat(styles.marginTop) +
+            parseFloat(styles.marginBottom),
         });
       }
 
       return () => {
-        model.events.removeItemWidth({id: name});
+        model.events.removeItemSize({id: name});
       };
     });
 

package/collection/lib/useOverflowListMeasure.ts

@@ -19,7 +19,7 @@ export const useOverflowListMeasure = createElemPropsHook(useOverflowListModel)(
 
   useResizeObserver({
     ref: localRef,
-    onResize: model.events.setContainerWidth,
+    onResize: model.events.setContainerSize,
   });
   useMountLayout(() => {
     if (localRef.current) {

package/collection/lib/useOverflowListModel.tsx

@@ -5,17 +5,17 @@ import {useSelectionListModel} from './useSelectionListModel';
 import {Item} from './useBaseListModel';
 
 export function getHiddenIds(
-  containerWidth: number,
+  containerSize: number,
   containerGap: number,
-  overflowTargetWidth: number,
-  itemWidthCache: Record<string, number>,
+  overflowTargetSize: number,
+  itemSizeCache: Record<string, number>,
   selectedIds: string[] | 'all',
   items: Item<any>[]
 ): string[] {
   /** Allows us to prioritize showing the selected item */
   let selectedKey: undefined | string;
   /** Tally of combined item widths. We'll add items that fit until the container is full */
-  let itemWidth = 0;
+  let itemSize = 0;
   /** Tally ids that won't fit inside the container. These will be used by components to hide
    * elements that won't fit in the container */
   const hiddenIds: string[] = [];
@@ -31,31 +31,31 @@ export function getHiddenIds(
   }
 
   if (
-    Object.keys(itemWidthCache).reduce(
-      (sum, key, index) => sum + itemWidthCache[key] + (index > 0 ? containerGap : 0),
+    Object.keys(itemSizeCache).reduce(
+      (sum, key, index) => sum + itemSizeCache[key] + (index > 0 ? containerGap : 0),
       0
-    ) <= containerWidth
+    ) <= containerSize
   ) {
     // All items fit, return empty array
     return [];
   } else if (selectedKey) {
-    if (itemWidthCache[selectedKey] + overflowTargetWidth > containerWidth) {
+    if (itemSizeCache[selectedKey] + overflowTargetSize > containerSize) {
       // If the selected item doesn't fit, only show overflow (all items hidden)
-      return Object.keys(itemWidthCache);
+      return Object.keys(itemSizeCache);
     } else {
       // at least the selected item and overflow target fit. Update our itemWidth with the sum
-      itemWidth += itemWidthCache[selectedKey] + overflowTargetWidth;
+      itemSize += itemSizeCache[selectedKey] + overflowTargetSize;
       shouldAddGap = true;
     }
   } else {
-    itemWidth += overflowTargetWidth;
+    itemSize += overflowTargetSize;
   }
 
-  for (const key in itemWidthCache) {
+  for (const key in itemSizeCache) {
     if (key !== selectedKey) {
-      itemWidth += itemWidthCache[key] + (shouldAddGap ? containerGap : 0);
+      itemSize += itemSizeCache[key] + (shouldAddGap ? containerGap : 0);
       shouldAddGap = true;
-      if (itemWidth > containerWidth) {
+      if (itemSize > containerSize) {
         hiddenIds.push(key);
       }
     }
@@ -81,13 +81,13 @@ export const useOverflowListModel = createModelHook({
   const shouldCalculateOverflow =
     config.shouldCalculateOverflow === undefined ? true : config.shouldCalculateOverflow;
   const [hiddenIds, setHiddenIds] = React.useState(config.initialHiddenIds);
-  const [itemWidthCache, setItemWidthCache] = React.useState<Record<string, number>>({});
-  const [containerWidth, setContainerWidth] = React.useState(0);
+  const [itemSizeCache, setItemSizeCache] = React.useState<Record<string, number>>({});
+  const [containerSize, setContainerSize] = React.useState(0);
   const [containerGap, setContainerGap] = React.useState(0);
-  const containerWidthRef = React.useRef(0);
-  const itemWidthCacheRef = React.useRef(itemWidthCache);
+  const containerSizeRef = React.useRef(0);
+  const itemSizeCacheRef = React.useRef(itemSizeCache);
   const [overflowTargetWidth, setOverflowTargetWidth] = React.useState(0);
-  const overflowTargetWidthRef = React.useRef(0);
+  const overflowTargetSizeRef = React.useRef(0);
 
   const internalHiddenIds = shouldCalculateOverflow ? hiddenIds : [];
 
@@ -103,8 +103,16 @@ export const useOverflowListModel = createModelHook({
   const state = {
     ...model.state,
     hiddenIds: internalHiddenIds,
-    itemWidthCache,
-    containerWidth,
+    itemSizeCache,
+    /**
+     * @deprecated Use `itemSizeCache` instead
+     */
+    itemWidthCache: itemSizeCache,
+    containerSize,
+    /**
+     * @deprecated Use `containerSize` instead
+     */
+    containerWidth: containerSize,
     containerGap,
     overflowTargetWidth,
   };
@@ -114,10 +122,10 @@ export const useOverflowListModel = createModelHook({
     select(data: Parameters<typeof model.events.select>[0]) {
       const {selectedIds} = model.selection.select(data.id, state);
       const ids = getHiddenIds(
-        containerWidthRef.current,
+        containerSizeRef.current,
         containerGap,
-        overflowTargetWidthRef.current,
-        itemWidthCacheRef.current,
+        overflowTargetSizeRef.current,
+        itemSizeCacheRef.current,
         selectedIds,
         config.items
       );
@@ -125,69 +133,93 @@ export const useOverflowListModel = createModelHook({
 
       setHiddenIds(ids);
     },
-    setContainerWidth(data: {width?: number}) {
-      containerWidthRef.current = data.width || 0;
-      setContainerWidth(data.width || 0);
-
+    setContainerSize(data: {width?: number; height?: number}) {
+      containerSizeRef.current =
+        model.state.orientation === 'horizontal' ? data.width || 0 : data.height || 0;
+      setContainerSize(containerSizeRef.current);
       const ids = getHiddenIds(
-        containerWidthRef.current,
+        containerSizeRef.current,
         containerGap,
-        overflowTargetWidthRef.current,
-        itemWidthCacheRef.current,
+        overflowTargetSizeRef.current,
+        itemSizeCacheRef.current,
         state.selectedIds,
         config.items
       );
-
       setHiddenIds(ids);
     },
+    /**
+     * @deprecated Use `setContainerSize` instead and pass both `width` and `height`
+     */
+    setContainerWidth(data: {width?: number}) {
+      events.setContainerSize({width: data.width, height: 0});
+    },
     setContainerGap(data: {size: number}) {
       setContainerGap(data.size);
 
       const ids = getHiddenIds(
-        containerWidthRef.current,
+        containerSizeRef.current,
         data.size,
-        overflowTargetWidthRef.current,
-        itemWidthCacheRef.current,
+        overflowTargetSizeRef.current,
+        itemSizeCacheRef.current,
         state.selectedIds,
         config.items
       );
 
       setHiddenIds(ids);
     },
+    setOverflowTargetSize(data: {width: number; height: number}) {
+      overflowTargetSizeRef.current =
+        model.state.orientation === 'horizontal' ? data.width || 0 : data.height || 0;
+      setOverflowTargetWidth(overflowTargetSizeRef.current);
+    },
+
+    /**
+     *
+     * @deprecated `setOverflowTargetWidth` is deprecated. Please use `setOverflowTargetSize` and pass in the `width` and set `height` to `0`.
+     */
     setOverflowTargetWidth(data: {width: number}) {
-      overflowTargetWidthRef.current = data.width;
-      setOverflowTargetWidth(data.width);
+      overflowTargetSizeRef.current = data.width;
+      events.setOverflowTargetSize({width: overflowTargetSizeRef.current, height: 0});
     },
+
+    /**
+     *
+     * @deprecated `addItemWidth` is deprecated. Please use `addItemSize` and set the `width`
+     */
     addItemWidth(data: {id: string; width: number}) {
-      itemWidthCacheRef.current = {
-        ...itemWidthCacheRef.current,
-        [data.id]: data.width,
+      events.addItemSize({id: data.id, width: data.width, height: 0});
+    },
+    addItemSize(data: {id: string; width: number; height: number}) {
+      itemSizeCacheRef.current = {
+        ...itemSizeCacheRef.current,
+        [data.id]: model.state.orientation === 'horizontal' ? data.width : data.height,
       };
 
-      setItemWidthCache(itemWidthCacheRef.current);
+
+      setItemSizeCache(itemSizeCacheRef.current);
 
       const ids = getHiddenIds(
-        containerWidthRef.current,
+        containerSizeRef.current,
         containerGap,
-        overflowTargetWidthRef.current,
-        itemWidthCacheRef.current,
+        overflowTargetSizeRef.current,
+        itemSizeCacheRef.current,
         state.selectedIds,
         config.items
       );
 
       setHiddenIds(ids);
     },
-    removeItemWidth(data: {id: string}) {
-      const newCache = {...itemWidthCacheRef.current};
+    removeItemSize(data: {id: string}) {
+      const newCache = {...itemSizeCacheRef.current};
       delete newCache[data.id];
-      itemWidthCacheRef.current = newCache;
-      setItemWidthCache(itemWidthCacheRef.current);
+      itemSizeCacheRef.current = newCache;
+      setItemSizeCache(itemSizeCacheRef.current);
 
       const ids = getHiddenIds(
-        containerWidthRef.current,
+        containerSizeRef.current,
         containerGap,
-        overflowTargetWidthRef.current,
-        itemWidthCacheRef.current,
+        overflowTargetSizeRef.current,
+        itemSizeCacheRef.current,
         state.selectedIds !== 'all'
           ? state.selectedIds.filter(sId => data.id !== sId)
           : state.selectedIds,
@@ -196,6 +228,13 @@ export const useOverflowListModel = createModelHook({
 
       setHiddenIds(ids);
     },
+    /**
+     *
+     * @deprecated `removeItemWidth` is deprecated. Please use `removeItemSize`.
+     */
+    removeItemWidth(data: {id: string}) {
+      events.removeItemSize({id: data.id});
+    },
     addHiddenKey(data: {id: string}) {
       setHiddenIds(ids => ids.concat(data.id));
     },

package/collection/lib/useOverflowListTarget.tsx

@@ -24,11 +24,15 @@ export const useOverflowListTarget = createElemPropsHook(useOverflowListModel)((
     if (localRef.current) {
       const styles = getComputedStyle(localRef.current);
 
-      model.events.setOverflowTargetWidth({
+      model.events.setOverflowTargetSize({
         width:
           localRef.current.offsetWidth +
           parseFloat(styles.marginLeft) +
           parseFloat(styles.marginRight),
+        height:
+          localRef.current.offsetWidth +
+          parseFloat(styles.marginTop) +
+          parseFloat(styles.marginBottom),
       });
     }
   });

package/collection/lib/useSelectionListModel.tsx

@@ -109,6 +109,16 @@ export const useSelectionListModel = createModelHook({
     setSelectedIds(ids: 'all' | string[]) {
       setSelectedIds(ids);
     },
+    /**
+     * The `remove` event can be called by Behavior Hooks based on user interaction. The `onRemove`
+     * can be added to the model config to signal the user wishes to remove the item in the list.
+     * The `remove` event requires the dynamic API where `items` are passed to the model. It is up
+     * to you to remove the item from the list. Focus redirection should be automatically managed,
+     * if necessary.
+     */
+    remove(data: {id: string; nextId?: string; event?: Event | React.SyntheticEvent}) {
+      // nothing to do here. It is a signal event
+    },
   };
 
   return {...cursor, state, events, selection};

package/combobox/lib/hooks/useComboboxInput.ts

@@ -26,16 +26,13 @@ export const useComboboxInput = composeHooks(
         if (model.state.isVirtualized && item) {
           model.state.UNSTABLE_virtual.scrollToIndex(item.index);
         } else {
-          const listboxId = model.state.inputRef.current?.getAttribute('aria-controls');
-          if (listboxId) {
-            const menuItem = document.querySelector(
-              `[id="${listboxId}"] [data-id="${model.state.cursorId}"]`
-            );
-            if (menuItem) {
-              requestAnimationFrame(() => {
-                menuItem.scrollIntoView({block: 'nearest'});
-              });
-            }
+          const menuItem = document.querySelector(
+            `[id="${model.state.id}-list"] [data-id="${model.state.cursorId}"]`
+          );
+          if (menuItem) {
+            requestAnimationFrame(() => {
+              menuItem.scrollIntoView({block: 'nearest'});
+            });
           }
         }
       }