@workday/canvas-kit-react 9.0.0-alpha.415-next.17 → 9.0.0-alpha.417-next.19

package/collection/index.ts

@@ -8,6 +8,7 @@ export * from './lib/useListRenderItem';
 export * from './lib/useListResetCursorOnBlur';
 export * from './lib/useListItemRovingFocus';
 export * from './lib/useListItemSelect';
+export * from './lib/useListLoader';
 export * from './lib/useListModel';
 export * from './lib/useGridModel';
 export * from './lib/useListItemAllowChildStrings';

package/collection/lib/useCursorListModel.tsx

@@ -279,6 +279,8 @@ export const navigationManager = createNavigationManager({
   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
@@ -322,11 +324,9 @@ export const useCursorListModel = createModelHook({
   const pageSizeRef = React.useRef(config.pageSize);
   const columnCount = config.columnCount || 0;
   const list = useBaseListModel(config);
-  const initialCurrentRef = React.useRef(
-    config.initialCursorId || (config.items?.length ? list.state.items![0].id : '')
-  );
   const navigation = config.navigation;
-  const cursorIndexRef = React.useRef(-1);
+  // 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);
@@ -334,9 +334,12 @@ export const useCursorListModel = createModelHook({
 
   // 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);
+    // 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.current = -1;
+    (cursorIndexRef as Writeable<typeof cursorIndexRef>).current = -1;
   }
 
   const state = {
@@ -354,22 +357,18 @@ export const useCursorListModel = createModelHook({
      * 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 = list.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}) {
       const index = state.items.findIndex(item => item.id === data.id);

package/collection/lib/useListItemAllowChildStrings.ts

@@ -2,9 +2,9 @@ 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 defined _before_ {@link useListItemRegister} because it sets the `data-id`
+ * 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:

package/collection/lib/useListItemRovingFocus.tsx

@@ -4,6 +4,13 @@ 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));
+  }
+};
+
 /**
  * This elemProps hook is used for cursor navigation by using [Roving
  * Tabindex](https://w3c.github.io/aria-practices/#kbd_roving_tabindex). Only a single item in the
@@ -19,7 +26,7 @@ import {keyboardEventToCursorEvents} from './keyUtils';
 ```
  */
 export const useListItemRovingFocus = createElemPropsHook(useCursorListModel)(
-  (model, ref, elemProps: {'data-id'?: string} = {}) => {
+  (model, _ref, elemProps: {'data-id'?: string} = {}) => {
     // Create a ref out of state. We don't want to watch state on unmount, so we use a ref to get the
     // current value at the time of unmounting. Otherwise, `state.items` would be a cached value of an
     // empty array
@@ -35,11 +42,17 @@ export const useListItemRovingFocus = createElemPropsHook(useCursorListModel)(
         if (model.state.isVirtualized) {
           model.state.UNSTABLE_virtual.scrollToIndex(item.index);
         }
-        requestAnimationFrame(() => {
-          document
-            .querySelector<HTMLElement>(`[data-focus-id="${`${model.state.id}-${item.id}`}"]`)
-            ?.focus();
-        });
+
+        // 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 = document.querySelector<HTMLElement>(
+            `[data-focus-id="${`${model.state.id}-${item.id}`}"]`
+          );
+
+          element?.focus();
+          return !!element;
+        }, 5); // 5 should be enough, right?!
 
         keyDownRef.current = false;
       }
@@ -47,6 +60,13 @@ export const useListItemRovingFocus = createElemPropsHook(useCursorListModel)(
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [model.state.cursorId]);
 
+    // Roving focus must always have a focus stop to function correctly
+    React.useEffect(() => {
+      if (!model.state.cursorId && model.state.items.length) {
+        model.events.goTo({id: model.state.items[0].id});
+      }
+    }, [model.state.cursorId, model.state.items, model.events]);
+
     return {
       onKeyDown(event: React.KeyboardEvent) {
         const handled = keyboardEventToCursorEvents(event, model, isRTL);
@@ -64,7 +84,6 @@ export const useListItemRovingFocus = createElemPropsHook(useCursorListModel)(
         : !!elemProps['data-id'] && model.state.cursorId === elemProps['data-id']
         ? 0 // A name is known and cursor is here
         : -1, // A name is known an cursor is somewhere else
-      ref,
     };
   }
 );

package/collection/lib/useListLoader.ts

@@ -0,0 +1,313 @@
+import React from 'react';
+
+import {useListModel} from './useListModel';
+
+export interface LoadReturn<T> {
+  items: T[];
+  total?: number;
+}
+
+export interface LoadParams {
+  pageNumber: number;
+  pageSize: number;
+  filter: CollectionLoader['filter'];
+  sorter: CollectionLoader['sorter'];
+}
+export interface AsyncCollectionConfig<T> {
+  pageSize: number;
+  total: number;
+  load(params: LoadParams): LoadReturn<T> | Promise<LoadReturn<T>>;
+}
+
+export interface CollectionLoader {
+  filter: string | Record<string, string>;
+  updateFilter(value: string): void;
+  sorter: string | Record<string, string>;
+  updateSorter(value: string): void;
+  isLoading: boolean;
+}
+
+/**
+ * A loading buffer is how many items we want to look at ahead of the current virtual window. A
+ * higher amount can load too many pages initially. A lower number can cause items to not be loaded
+ * yet when scrolling. This will probably become a floating number later based on scrolling speed.
+ * Ideally the faster the user scrolls, this number will be higher or "predict" where to focus loading
+ * so the user doesn't see unloaded items. But if the user is scrolling too fast, we may simply delay
+ * data loading. That logic would be based on timers. For now, we'll just hardcode.
+ */
+const loadingBuffer = 3;
+
+function updateItems<T>(newItems: T[], startIndex = 0) {
+  return function itemStateUpdater(items: T[]) {
+    // replace existing indexes with data from external service
+    newItems.forEach((item, index) => {
+      items[index + startIndex] = item;
+    });
+    const returnedItems = items.concat([]);
+    return returnedItems; // return a new reference
+  };
+}
+
+type Updater<T> = {total?: number; updater: (items: T[]) => T[]};
+
+function load<T>(
+  params: {
+    pageNumber: number;
+    pageSize: number;
+    filter: CollectionLoader['filter'];
+    sorter: CollectionLoader['sorter'];
+  },
+  loadCb: AsyncCollectionConfig<T>['load'],
+  loadingCache: Record<number, boolean>
+): Promise<Updater<T>> {
+  if (loadingCache[params.pageNumber]) {
+    return Promise.resolve({updater: items => items});
+  }
+  loadingCache[params.pageNumber] = true;
+
+  return Promise.resolve(loadCb(params)).then(({items, total}) => {
+    loadingCache[params.pageNumber] = false;
+    return {total, updater: updateItems(items, (params.pageNumber - 1) * params.pageSize)};
+  });
+}
+
+export function getPageNumber(index: number, pageSize: number) {
+  if (index <= 0) {
+    return 1;
+  }
+
+  return Math.ceil((index + 1) / pageSize);
+}
+
+function clamp(input: number, min: number, max: number) {
+  return Math.max(Math.min(input, max), min);
+}
+
+/**
+ *
+ * @param start The start index of the virtual window
+ * @param end The end index of the virtual window
+ * @param pageSize Expected load page size
+ * @param items Sparse array of all loaded items
+ * @param overScan How many items ahead we want to look ahead to trigger loading. Unloaded items
+ * that are this many items outside the current start and end numbers will trigger a loading of
+ * a page
+ */
+export function getPagesToLoad<T>(
+  start: number,
+  end: number,
+  pageSize: number,
+  items: T[],
+  overScan = 3
+): number[] {
+  const pagesToLoad: number[] = [];
+
+  const lookBehindIndex = clamp(start - overScan, 0, items.length - 1);
+  if (start >= 0 && !items[lookBehindIndex]) {
+    const pageNumber = getPageNumber(lookBehindIndex, pageSize);
+    pagesToLoad.push(pageNumber);
+  }
+
+  const lookaheadIndex = clamp(end + overScan - 1, 0, items.length - 1);
+  if (end < items.length - 1 && !items[lookaheadIndex]) {
+    const pageNumber = getPageNumber(lookaheadIndex, pageSize);
+    if (!pagesToLoad.includes(pageNumber)) {
+      pagesToLoad.push(pageNumber);
+    }
+  }
+
+  return pagesToLoad;
+}
+
+const resetItems = (total: number) => Array(total).fill(undefined);
+
+/**
+ * Create a data loader and a model. The model should be passed to a collection component. The
+ * loader can be used to manipulate filters, sorters, and clear cache.
+ *
+ * A simple loader using [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+ * could look like the following:
+ *
+ * ```ts
+ * const {model, loader} = useListLoader(
+ *   {
+ *     total: 1000,
+ *     pageSize: 20,
+ *     async load({pageNumber, pageSize}) {
+ *       return fetch('/myUrl')
+ *         .then(response => response.json())
+ *         .then(response => {
+ *           return {total: response.total, items: response.items};
+ *         });
+ *     },
+ *   },
+ *   useListModel
+ * );
+ * ```
+ *
+ * @param config Config that contains the loader config and the model config
+ * @param modelHook A model hook that describes which model should be returned.
+ */
+export function useListLoader<
+  T,
+  // I cannot get Typescript to accept models that extend from `useListModel` to be considered valid
+  M extends ((...args: any[]) => any) & Omit<typeof useListModel, 'TConfig' | 'Context'>
+>(
+  config: AsyncCollectionConfig<T> & typeof useListModel.TConfig,
+  modelHook: M
+): {model: ReturnType<M>; loader: CollectionLoader} {
+  const [total, setTotal] = React.useState(config.total);
+  const [items, setItems] = React.useState<T[]>(() => {
+    return resetItems(config.total);
+  });
+
+  // keep track of pages that are currently loading
+  const loadingRef = React.useRef<Record<number, boolean>>({});
+
+  const [filter, setFilter] = React.useState<CollectionLoader['filter']>('');
+  const [sorter, setSorter] = React.useState<CollectionLoader['sorter']>('');
+
+  const updateItems = React.useCallback(
+    ({updater, total: newTotal}: Updater<T>) => {
+      if (newTotal !== undefined && total !== newTotal) {
+        setTotal(newTotal);
+        setItems(() => {
+          const items = resetItems(newTotal);
+          return updater(items);
+        });
+        return;
+      }
+      setItems(updater);
+    },
+    [total]
+  );
+
+  const updateFilter = (filter: CollectionLoader['filter']) => {
+    loadingRef.current = {};
+    setFilter(filter);
+    const params = {
+      pageNumber: 1,
+      pageSize: config.pageSize,
+      filter,
+      sorter,
+    };
+    load(params, loadRef.current, loadingRef.current).then(updateItems);
+  };
+
+  const updateSorter = (sorter: CollectionLoader['sorter']) => {
+    loadingRef.current = {};
+    setSorter(sorter);
+    load(
+      {
+        pageNumber: 1,
+        pageSize: config.pageSize,
+        filter,
+        sorter,
+      },
+      loadRef.current,
+      loadingRef.current
+    ).then(updateItems);
+  };
+
+  // Our `useEffect` functions use `config.load`, but we don't want to rerun the effects if the user
+  // sends a different load function every render
+  const loadRef = React.useRef(config.load);
+  loadRef.current = config.load;
+
+  const itemsRef = React.useRef(items);
+  itemsRef.current = items;
+  const requestAnimationFrameRef = React.useRef(0);
+
+  const shouldLoadIndex = (
+    navigationMethod: Exclude<keyof ReturnType<typeof useListModel>['navigation'], 'getItem'>,
+    eventKey: keyof ReturnType<typeof useListModel>['events']
+  ) => {
+    return (data: any) => {
+      const index = model.navigation[navigationMethod](model.state.cursorIndexRef.current, model);
+      if (!items[index]) {
+        load(
+          {
+            pageNumber: Math.floor(index / config.pageSize) + 1,
+            pageSize: config.pageSize,
+            filter,
+            sorter,
+          },
+          loadRef.current,
+          loadingRef.current
+        )
+          .then(updateItems)
+          .then(() => {
+            cancelAnimationFrame(requestAnimationFrameRef.current);
+            requestAnimationFrameRef.current = requestAnimationFrame(() => {
+              model.events[eventKey](data as any);
+            });
+          });
+        return false;
+      }
+      return true;
+    };
+  };
+
+  const model = modelHook(
+    modelHook.mergeConfig(config, {
+      items,
+      shouldGoToNext: shouldLoadIndex('getNext', 'goToNext'),
+      shouldGoToPrevious: shouldLoadIndex('getPrevious', 'goToPrevious'),
+      shouldGoToLast: shouldLoadIndex('getLast', 'goToLast'),
+      shouldGoToFirst: shouldLoadIndex('getFirst', 'goToFirst'),
+      shouldGoToNextPage: shouldLoadIndex('getNextPage', 'goToNextPage'),
+      shouldGoToPreviousPage: shouldLoadIndex('getPreviousPage', 'goToPreviousPage'),
+    })
+  ) as ReturnType<typeof useListModel>;
+
+  const {virtualItems} = model.state.UNSTABLE_virtual;
+
+  // Our only signal to trigger loading is if our virtual indexes are too close to boundaries.
+  React.useEffect(() => {
+    if (!virtualItems.length) {
+      return;
+    }
+
+    const firstItem = virtualItems[0];
+    const lastItem = virtualItems[virtualItems.length - 1];
+
+    const pagesToLoad = getPagesToLoad(
+      firstItem.index,
+      lastItem.index,
+      config.pageSize,
+      itemsRef.current,
+      loadingBuffer
+    );
+
+    pagesToLoad.forEach(pageNumber => {
+      load(
+        {pageNumber, pageSize: config.pageSize, filter, sorter},
+        loadRef.current,
+        loadingRef.current
+      ).then(updateItems);
+    });
+
+    return () => {
+      cancelAnimationFrame(requestAnimationFrameRef.current);
+    };
+  }, [virtualItems, config.pageSize, filter, sorter, updateItems]);
+
+  // Typescript won't allow me to say the included model extends `useListModel` for some reason, so
+  // we have no way to type check it. Without the constraint, Typescript doesn't know how type it
+  // properly, so we have an `as any`.
+  return {
+    model: model as any,
+    loader: {
+      filter,
+      updateFilter,
+      sorter,
+      updateSorter,
+      // we reduce the ref instead of a state variable because the loader mutates this ref and
+      // triggers state changes when loading is finished.
+      isLoading: Object.values(loadingRef.current).reduce(
+        (loading, result) => loading || result,
+        false
+      ),
+    },
+  };
+}