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

package/collection/lib/useListLoader.ts

@@ -0,0 +1,375 @@
+import React from 'react';
+
+import {Model} from '@workday/canvas-kit-react/common';
+
+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, M extends Model<any, any>> {
+  /**
+   * The desired results per page.
+   */
+  pageSize: number;
+  /**
+   * The total items in the collection. If you do not have this information before making an API
+   * call, leave it blank and it will default to `0` and be updated when `load` comes back with
+   * results.
+   * @default 0
+   */
+  total?: number;
+  /**
+   * This function acts like a guard similar to model events. If you provide this function and it
+   * returns `false`, the `load` call from the loader will be cancelled. Be aware, this function can
+   * cause a loader to not function properly. You will need to call `loader.load(pageNumber)` on
+   * your own if a valid load event is cancelled. An example of using this function is in
+   * {@link useComboboxLoader} where the load calls are only allowed when the menu is open.
+   */
+  shouldLoad?(
+    /**
+     * Parameters that are being sent to the `load` function
+     */
+    params: LoadParams,
+    /**
+     * State coming from the model
+     */
+    prevState: M['state']
+  ): boolean;
+  /**
+   * A `load` callback function provides an easier way to hook up loader requests for data to an
+   * API. It will be called when the user is ready for more of the virtual data set. The `load`
+   * function will be called when:
+   * - The list UI initially loads. It will request as many pages as necessary to render enough
+   *   items in the viewport
+   * - The user is scrolling the list and has run out of cached data
+   * - The user is using the keyboard to navigate the list and has run out of cached data
+   * - A filter or sorter value has changed and the cached data is now invalid
+   * - `loader.load` was called by the developer, manually requesting a page 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;
+  load(pageNumber?: number): void;
+}
+
+/**
+ * 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, any>['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 list loader should be used on virtual data sets with
+ * possibly large amounts of data. 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, 'Context'>
+>(
+  config: AsyncCollectionConfig<T, ReturnType<M>> & M['TConfig'],
+  modelHook: M
+): {model: ReturnType<M>; loader: CollectionLoader} {
+  const [total, setTotal] = React.useState(config.total || 0);
+  const [items, setItems] = React.useState<T[]>(() => {
+    return resetItems(config.total || 0);
+  });
+
+  // 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]
+  );
+
+  // 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 shouldLoadRef = React.useRef(config.shouldLoad);
+  shouldLoadRef.current = config.shouldLoad;
+
+  const requestAnimationFrameRef = React.useRef(0);
+
+  const shouldLoadIndex = (
+    navigationMethod: Exclude<keyof ReturnType<typeof useListModel>['navigation'], 'getItem'>,
+    eventKey: keyof ReturnType<typeof useListModel>['events']
+  ) => {
+    return (data: any, prevState: any) => {
+      const index = model.navigation[navigationMethod](model.state.cursorIndexRef.current, model);
+      const params = {
+        pageNumber: Math.floor(index / config.pageSize) + 1,
+        pageSize: config.pageSize,
+        filter,
+        sorter,
+      };
+      if (!items[index]) {
+        if (config.shouldLoad && !config.shouldLoad(params, prevState)) {
+          return false;
+        }
+        load(params, 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;
+
+  const {state} = model;
+  const stateRef = React.useRef(state);
+  stateRef.current = state;
+
+  const updateFilter = (filter: CollectionLoader['filter']) => {
+    loadingRef.current = {};
+    setFilter(filter);
+    const params = {
+      pageNumber: 1,
+      pageSize: config.pageSize,
+      filter,
+      sorter,
+    };
+    if (config.shouldLoad && !config.shouldLoad(params, state)) {
+      return;
+    }
+    load(params, loadRef.current, loadingRef.current).then(updateItems);
+  };
+
+  const updateSorter = (sorter: CollectionLoader['sorter']) => {
+    loadingRef.current = {};
+    setSorter(sorter);
+    const params = {
+      pageNumber: 1,
+      pageSize: config.pageSize,
+      filter,
+      sorter,
+    };
+    if (config.shouldLoad && !config.shouldLoad(params, state)) {
+      return;
+    }
+    load(params, loadRef.current, loadingRef.current).then(updateItems);
+  };
+
+  // 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 => {
+      const params = {pageNumber, pageSize: config.pageSize, filter, sorter};
+      const shouldLoad = shouldLoadRef.current;
+      if (shouldLoad && !shouldLoad(params, stateRef.current)) {
+        return;
+      }
+      load(params, loadRef.current, loadingRef.current).then(updateItems);
+    });
+
+    return () => {
+      cancelAnimationFrame(requestAnimationFrameRef.current);
+    };
+  }, [virtualItems, config.pageSize, filter, sorter, updateItems]);
+
+  const loaderLoad: CollectionLoader['load'] = (pageNumber = 1) => {
+    return load<T>(
+      {pageNumber, pageSize: config.pageSize, filter, sorter},
+      loadRef.current,
+      loadingRef.current
+    ).then(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
+      ),
+      load: loaderLoad,
+    },
+  };
+}

package/collection/lib/useListModel.tsx

@@ -15,10 +15,26 @@ export type ListItemProps = {
 };
 
 /**
- * Create a list model that includes item registration, cursors for focus, and selection. You can
- * inject navigation and selection managers to change how a user navigates or how selection works.
+ * The List model contains the the state and events necessary to track items, selection, and a cursor.
+ * Various hooks can be used for a List model to create common behaviors associated with lists, such as
+ * navigating a list with a keyboard, selection (single and multiple), and virtualization.
  *
- * @example
+ * A list also has a "cursor". A cursor is often represented by focus, but it is not always a 1:1
+ * mapping. Think of the cursor as the focus item within the list. If the list has browser focus, the
+ * cursor will map to browser focus. Behaviors such as `useListRovingFocus` will map the cursor to the
+ * active tab stop of the list. For more information, see
+ * [Roving Tabindex](https://w3c.github.io/aria-practices/#kbd_roving_tabindex). `useListRovingFocus`
+ * adds keyboard events that map to navigation events. A [Navigation Manager](#navigation-manager) is
+ * used to map new cursor ids to these events. The `ListModel` takes an optional `navigation`
+ * configuration to change the default navigation behavior. The default navigation manager is a
+ * [wrappingNavigationManager](#wrappingnavigationmanager) meaning the cursor will wrap around the
+ * beginning and the ends. The cursor also provides a [navigationManager](#navigationmanager) that does
+ * not wrap. This is the default navigation for grids.
+ *
+ * The cursor also adds the concept of `orientation` which defaults to `'vertical'`. A Tab list is an
+ * example of a `'horizontal'` list.
+ *
+ * ```tsx
  * const list = useListModel({
  *   // custom handling for selection. single and multi select are provided
  *   selection: mySelectionManager,
@@ -27,6 +43,7 @@ export type ListItemProps = {
  *   items: [{ id: '1', text: 'First'}, { id: '2', text: 'Second' }],
  *   getId: item => item.id, // get the unique identifier of your item
  * })
+ * ```
  */
 export const useListModel = createModelHook({
   defaultConfig: useSelectionListModel.defaultConfig,

package/collection/lib/useListRenderItem.tsx

@@ -4,29 +4,53 @@ import {Generic} from '@workday/canvas-kit-react/common';
 
 import {useBaseListModel} from './useBaseListModel';
 
+/**
+ * This hook is meant to be used inside the render function of `List` style components. It is used
+ * by `ListBox`. This hook gives list-based components their static and dynamic APIs to handle list
+ * items. This hook should only be used if you want to implement your own List. For example,
+ * `Tabs.List` uses this hook, but `Menu.List` uses `ListBox` which uses this hook.
+ *
+ * ```tsx
+ * const MyList = createContainer('ul')({
+ *   modelHook: useListModel,
+ * })((elemProps, Element, model) => {
+ *   return <Element {...elemProps}>{useListRenderItems(model, elemProps.children)}</Element>;
+ * });
+```
+ */
 export function useListRenderItems<T>(
   model: ReturnType<typeof useBaseListModel>,
   children: ((item: Generic, index: number) => React.ReactNode) | React.ReactNode
-) {
+): React.ReactNode {
   const items =
     typeof children === 'function'
       ? model.state.isVirtualized
         ? model.state.UNSTABLE_virtual.virtualItems.map(virtual => {
             const item = model.state.items[virtual.index];
             const child = children(item.value, virtual.index);
-            return React.cloneElement(child, {
-              // We call this `virtual` instead of `virtualItem` to avoid a React render warning
-              // about capital letters in attributes. React thinks this will be applied to the DOM
-              // element even though we remove it later...
-              virtual,
-              key: item.id,
-              item,
-            });
+            if (React.isValidElement(child)) {
+              return React.cloneElement(child, {
+                // We call this `virtual` instead of `virtualItem` to avoid a React render warning
+                // about capital letters in attributes. React thinks this will be applied to the DOM
+                // element even though we remove it later...
+                virtual,
+                key: item.id,
+                item,
+              });
+            }
+            return child;
           })
-        : model.state.items.map(item =>
-            React.cloneElement(children(item.value, item.index), {key: item.id, item: item.value})
-          )
-      : null;
+        : model.state.items.map(item => {
+            const child = children(item.value, item.index);
+            if (React.isValidElement(child)) {
+              return React.cloneElement(child, {
+                key: item.id,
+                item: item.value,
+              });
+            }
+            return child;
+          })
+      : children;
 
-  return items || children;
+  return items;
 }

package/collection/lib/useListResetCursorOnBlur.tsx

@@ -1,11 +1,22 @@
 import React from 'react';
 
 import {createElemPropsHook} from '@workday/canvas-kit-react/common';
-import {orientationKeyMap} from './useListItemRovingFocus';
+import {orientationKeyMap} from './keyUtils';
 import {useListModel} from './useListModel';
 
 /**
- * Reset the cursor to the selected item when the list looses focus
+ * This elemProps hook resets the cursor when the list looses focus. By default,
+ * [useListItemRovingFocus](#use-list-item-roving-focus) will leave the last focused item as the
+ * focusable item in the list. Sometimes it is desireable to reset the cursor to the last selected
+ * item. For example, `Tabs.Item` uses this hook to reset the tab stop to the currently selected tab.
+ *
+ * ```ts
+ * const useMyItem = composeHooks(
+ *   useListResetCursorOnBlur, // adds the cursor reset to selected for roving tabindex
+ *   useListItemRovingFocus,
+ *   useListItemRegister
+ * );
+```
  */
 export const useListResetCursorOnBlur = createElemPropsHook(useListModel)(({state, events}) => {
   const programmaticFocusRef = React.useRef(false);

package/collection/lib/useOverflowListItemMeasure.tsx

@@ -7,9 +7,20 @@ const hiddenStyles = {
   left: -99999,
 } as const;
 
+/**
+ * This elemProps hook measures a list item and reports it to an `OverflowListModel`. This is used
+ * in overflow detection.
+ *
+ * ```ts
+ * const useMyItem = composeHooks(
+ *   useOverflowListItemMeasure,
+ *   useListRegisterItem,
+ * )
+ * ```
+ */
 export const useOverflowListItemMeasure = createElemPropsHook(useOverflowListModel)(
-  (model, ref?: React.Ref<HTMLElement>, elemProps: {'data-id'?: string} = {}) => {
-    const {elementRef, localRef} = useLocalRef(ref);
+  (model, ref, elemProps: {'data-id'?: string} = {}) => {
+    const {elementRef, localRef} = useLocalRef(ref as React.Ref<HTMLElement>);
     const name = elemProps['data-id'] || '';
 
     useMountLayout(() => {

package/collection/lib/useOverflowListMeasure.ts

@@ -4,17 +4,19 @@ import {createElemPropsHook, useForkRef, useResizeObserver} from '@workday/canva
 
 import {useOverflowListModel} from './useOverflowListModel';
 
-export const useOverflowListMeasure = createElemPropsHook(useOverflowListModel)(
-  (model, ref?: React.Ref<HTMLElement>) => {
-    const localRef = React.useRef(null);
-    const {ref: resizeRef} = useResizeObserver({
-      ref: localRef,
-      onResize: model.events.setContainerWidth,
-    });
-    const elementRef = useForkRef(ref, resizeRef);
+/**
+ * This elemProps hook measures a list and reports it to an `OverflowListModel`. This is used in
+ * overflow detection.
+ */
+export const useOverflowListMeasure = createElemPropsHook(useOverflowListModel)((model, ref) => {
+  const localRef = React.useRef(null);
+  const {ref: resizeRef} = useResizeObserver({
+    ref: localRef,
+    onResize: model.events.setContainerWidth,
+  });
+  const elementRef = useForkRef(ref, resizeRef);
 
-    return {
-      ref: elementRef,
-    };
-  }
-);
+  return {
+    ref: elementRef,
+  };
+});

package/collection/lib/useOverflowListTarget.tsx

@@ -10,33 +10,35 @@ const hiddenStyle = {
   left: -99999,
 };
 
-export const useOverflowListTarget = createElemPropsHook(useOverflowListModel)(
-  (model, ref?: React.Ref<HTMLButtonElement>) => {
-    const {elementRef, localRef} = useLocalRef(ref);
-    // track first render to force correct size calculations
-    const firstRender = React.useRef(true);
-
-    useMountLayout(() => {
-      firstRender.current = false;
-      if (localRef.current) {
-        const styles = getComputedStyle(localRef.current);
-
-        model.events.setOverflowTargetWidth({
-          width:
-            localRef.current.offsetWidth +
-            parseFloat(styles.marginLeft) +
-            parseFloat(styles.marginRight),
-        });
-      }
-    });
-
-    const isHidden = !model.state.hiddenIds.length;
-
-    return {
-      ref: elementRef,
-      'aria-hidden': isHidden,
-      tabIndex: isHidden ? -1 : 0,
-      style: isHidden ? hiddenStyle : {},
-    };
-  }
-);
+/**
+ * This elemProps hook measures an overflow list target and reports it to an `OverflowListModel`.
+ * This is used in overflow detection.
+ */
+export const useOverflowListTarget = createElemPropsHook(useOverflowListModel)((model, ref) => {
+  const {elementRef, localRef} = useLocalRef(ref as React.Ref<HTMLElement>);
+  // track first render to force correct size calculations
+  const firstRender = React.useRef(true);
+
+  useMountLayout(() => {
+    firstRender.current = false;
+    if (localRef.current) {
+      const styles = getComputedStyle(localRef.current);
+
+      model.events.setOverflowTargetWidth({
+        width:
+          localRef.current.offsetWidth +
+          parseFloat(styles.marginLeft) +
+          parseFloat(styles.marginRight),
+      });
+    }
+  });
+
+  const isHidden = !model.state.hiddenIds.length;
+
+  return {
+    ref: elementRef,
+    'aria-hidden': isHidden,
+    tabIndex: isHidden ? -1 : 0,
+    style: isHidden ? hiddenStyle : undefined,
+  };
+});

package/collection/lib/useSelectionListModel.tsx

@@ -11,9 +11,21 @@ export type Selection = {
 };
 
 /**
- * A SelectionManager is used
+ * The list and grid models accept a `selection` config. If one is not provided,
+ * `singleSelectManager` is used. You can provide a custom select manager to suite your needs. A
+ * selection manager is an object with a single `select` method that takes an id and previously
+ * selected ids and returns a new set of selected ids.
+ *
+ * The collection system provides two selection managers: `singleSelectManager` and
+ * `multiSelectionManager`.
  */
 export interface SelectionManager {
+  /**
+   * Sets a new `Selection` state based on the current ID passed and the previous state. Each
+   * selection manager can implement this differently. For example, a single select manager may
+   * unselect all other items and select only the passed in id. A multiselect manager may toggle the
+   * passed id.
+   */
   select(id: string, prevState: Selection): Selection;
 }
 
@@ -59,6 +71,7 @@ export const useSelectionListModel = createModelHook({
     selection: singleSelectionManager,
   },
   requiredConfig: useCursorListModel.requiredConfig,
+  contextOverride: useCursorListModel.Context,
 })(config => {
   const cursor = useCursorListModel(config);
   const [selectedIds, setSelectedIds] = React.useState(config.initialSelectedIds);

package/color-picker/index.ts

@@ -1,7 +1,3 @@
-import ColorInput from './lib/ColorInput';
-import ColorPreview from './lib/ColorPreview';
-
-export {ColorInput, ColorPreview};
 export * from './lib/ColorInput';
 export * from './lib/ColorPreview';
 export * from './lib/parts/ColorSwatch';