@workday/canvas-kit-react 9.0.0-alpha.419-next.21 → 9.0.0

package/breadcrumbs/lib/BreadcrumbsItem.tsx

@@ -38,7 +38,7 @@ export const useBreadcrumbsItem = composeHooks(
   createElemPropsHook(useBreadcrumbsModel)(
     (
       {state},
-      _?: React.Ref<HTMLElement>,
+      _,
       elemProps: {
         'data-id'?: string;
         item?: {id: string};

package/collection/index.ts

@@ -8,9 +8,11 @@ export * from './lib/useListRenderItem';
 export * from './lib/useListResetCursorOnBlur';
 export * from './lib/useListItemRovingFocus';
 export * from './lib/useListItemSelect';
+export * from './lib/useListKeyboardHandler';
 export * from './lib/useListLoader';
 export * from './lib/useListModel';
 export * from './lib/useGridModel';
+export * from './lib/useListActiveDescendant';
 export * from './lib/useListItemAllowChildStrings';
 export {ListBox, ListBoxProps} from './lib/ListBox';
 export {

package/collection/lib/ListBox.tsx

@@ -3,22 +3,23 @@ import {
   createContainer,
   createElemPropsHook,
   createSubcomponent,
+  ExtractProps,
 } from '@workday/canvas-kit-react/common';
-import {Box, BoxProps} from '@workday/canvas-kit-react/layout';
+import {Box, Flex} from '@workday/canvas-kit-react/layout';
 
 import {useListModel} from './useListModel';
 import {useListRenderItems} from './useListRenderItem';
 import {useListItemRegister} from './useListItemRegister';
 
-export interface ListBoxProps extends Omit<BoxProps, 'children'> {
-  children?: React.ReactNode | ((item: any) => React.ReactNode);
+export interface ListBoxProps<T = any> extends Omit<ExtractProps<typeof Flex, never>, 'children'> {
+  children?: React.ReactNode | ((item: T, index: number) => React.ReactNode);
 }
 
 export const ListBoxItem = createSubcomponent('li')({
   displayName: 'Item',
   modelHook: useListModel,
   elemPropsHook: useListItemRegister,
-})<BoxProps>((elemProps, Element) => {
+})<ExtractProps<typeof Flex, never>>((elemProps, Element) => {
   return <Box as={Element} {...elemProps} />;
 });
 
@@ -64,20 +65,21 @@ export const ListBox = createContainer('ul')({
      */
     Item: ListBoxItem,
   },
-})<ListBoxProps>(({height, maxHeight, ...elemProps}, Element, model) => {
+})<ListBoxProps>(({height, maxHeight, marginY, ...elemProps}, Element, model) => {
+  // We're moving `marginY` to the container to not interfere with the virtualization size. We set
+  // the `marginY` on the Flex to `0` to avoid inaccurate scrollbars
+
   // TODO figure out what style props should go to which `Box`
   return (
     <Box
       ref={model.state.containerRef}
-      height={
-        height || model.state.isVirtualized ? model.state.UNSTABLE_virtual.totalSize : undefined
-      }
+      marginY={marginY}
       maxHeight={maxHeight}
       overflowY={model.state.orientation === 'vertical' ? 'auto' : undefined}
     >
-      <Box as={Element} {...elemProps}>
+      <Flex as={Element} flexDirection="column" {...elemProps} marginY={0}>
         {useListRenderItems(model, elemProps.children)}
-      </Box>
+      </Flex>
     </Box>
   );
 });

package/collection/lib/useBaseListModel.tsx

@@ -6,11 +6,11 @@ import {useUniqueId, createModelHook, Generic} from '@workday/canvas-kit-react/c
 export type Orientation = 'horizontal' | 'vertical';
 
 export const defaultGetId = (item: any): string => {
-  return item.id || '';
+  return typeof item === 'string' ? item : item.id || '';
 };
 
 export const defaultGetTextValue = (item: any): string => {
-  return item.text || '';
+  return typeof item === 'string' ? item : item.text || '';
 };
 
 export interface Item<T> {
@@ -84,13 +84,15 @@ export const useBaseListModel = createModelHook({
      * 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,
+    getId: (item: Generic) =>
+      typeof item === 'string' ? item : item === undefined ? '' : (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,
+    getTextValue: (item: Generic) =>
+      (typeof item === 'string' ? item : item === undefined ? '' : item.text || '') as string,
     /**
      * Array of all ids which are currently disabled. This is used for navigation to skip over items
      * which are not focusable.

package/collection/lib/useCursorListModel.tsx

@@ -184,7 +184,7 @@ export const getWrappingOffsetItem = (offset: number) => (
     }
   }
 
-  if (state.nonInteractiveIds.includes(items[nextIndex].id) && 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)(nextIndex, {state}, tries - 1);

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

@@ -8,12 +8,13 @@ import {useListModel} from '@workday/canvas-kit-react/collection';
  * 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
+ *   useListItemAllowChildStrings // always the last in the list
  * )
  *
  *

package/collection/lib/useListItemRegister.tsx

@@ -28,9 +28,10 @@ import {useListModel} from './useListModel';
 export const useListItemRegister = createElemPropsHook(useListModel)(
   (
     {state, events},
-    ref?: React.Ref<HTMLElement>,
+    ref,
     elemProps: {
       'data-id'?: string;
+      'data-text'?: string;
       children?: React.ReactNode;
       index?: number;
       disabled?: boolean;
@@ -39,7 +40,9 @@ export const useListItemRegister = createElemPropsHook(useListModel)(
     } = {}
   ) => {
     const [localId, setLocalId] = React.useState(elemProps['data-id'] || elemProps.item?.id || '');
-    const {localRef, elementRef} = useLocalRef(useForkRef(ref, elemProps.virtual?.measureRef));
+    const {localRef, elementRef} = useLocalRef(
+      useForkRef(ref as React.Ref<HTMLElement>, elemProps.virtual?.measureRef)
+    );
 
     // if the list is virtual, force the correct styling. Without this, weird things happen...
     const style: CSSProperties = elemProps.virtual
@@ -72,7 +75,11 @@ export const useListItemRegister = createElemPropsHook(useListModel)(
         item: {
           id: itemId,
         },
-        textValue: typeof elemProps.children === 'string' ? elemProps.children : '',
+        textValue: elemProps['data-text']
+          ? elemProps['data-text']
+          : typeof elemProps.children === 'string'
+          ? elemProps.children
+          : '',
       });
       setLocalId(itemId);
 

package/collection/lib/useListItemSelect.tsx

@@ -17,7 +17,7 @@ import {useListModel} from './useListModel';
  * ```
  */
 export const useListItemSelect = createElemPropsHook(useListModel)(
-  ({state, events}, _?: React.Ref<HTMLElement>, elemProps: {'data-id'?: string} = {}) => {
+  ({state, events}, _, elemProps: {'data-id'?: string} = {}) => {
     const name = elemProps['data-id'] || '';
     const onClick = (event: React.MouseEvent<HTMLElement>) => {
       if (

package/collection/lib/useListKeyboardHandler.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import {useIsRTL, createElemPropsHook} from '@workday/canvas-kit-react/common';
+
+import {useCursorListModel} from './useCursorListModel';
+import {keyboardEventToCursorEvents} from './keyUtils';
+
+/**
+ * This elemProps hook is used to attach keyboard events to handle keyboard navigation
+ *
+ * ```ts
+ * const useMyItem = composeHooks(
+ *   useListKeyboardHandler, // adds keyboard support support
+ *   useListItemRegister
+ * );
+```
+ */
+export const useListKeyboardHandler = createElemPropsHook(useCursorListModel)(model => {
+  const isRTL = useIsRTL();
+
+  return {
+    onKeyDown(event: React.KeyboardEvent) {
+      const handled = keyboardEventToCursorEvents(event, model, isRTL);
+      if (handled) {
+        event.preventDefault();
+      }
+    },
+  };
+});

package/collection/lib/useListLoader.ts

@@ -1,5 +1,7 @@
 import React from 'react';
 
+import {Model} from '@workday/canvas-kit-react/common';
+
 import {useListModel} from './useListModel';
 
 export interface LoadReturn<T> {
@@ -13,9 +15,46 @@ export interface LoadParams {
   filter: CollectionLoader['filter'];
   sorter: CollectionLoader['sorter'];
 }
-export interface AsyncCollectionConfig<T> {
+export interface AsyncCollectionConfig<T, M extends Model<any, any>> {
+  /**
+   * The desired results per page.
+   */
   pageSize: number;
-  total: 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>>;
 }
 
@@ -25,6 +64,7 @@ export interface CollectionLoader {
   sorter: string | Record<string, string>;
   updateSorter(value: string): void;
   isLoading: boolean;
+  load(pageNumber?: number): void;
 }
 
 /**
@@ -57,7 +97,7 @@ function load<T>(
     filter: CollectionLoader['filter'];
     sorter: CollectionLoader['sorter'];
   },
-  loadCb: AsyncCollectionConfig<T>['load'],
+  loadCb: AsyncCollectionConfig<T, any>['load'],
   loadingCache: Record<number, boolean>
 ): Promise<Updater<T>> {
   if (loadingCache[params.pageNumber]) {
@@ -122,11 +162,12 @@ export function getPagesToLoad<T>(
 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.
+ * 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:
+ * 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(
@@ -151,14 +192,14 @@ const resetItems = (total: number) => Array(total).fill(undefined);
 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'>
+  M extends ((...args: any[]) => any) & Omit<typeof useListModel, 'Context'>
 >(
-  config: AsyncCollectionConfig<T> & typeof useListModel.TConfig,
+  config: AsyncCollectionConfig<T, ReturnType<M>> & M['TConfig'],
   modelHook: M
 ): {model: ReturnType<M>; loader: CollectionLoader} {
-  const [total, setTotal] = React.useState(config.total);
+  const [total, setTotal] = React.useState(config.total || 0);
   const [items, setItems] = React.useState<T[]>(() => {
-    return resetItems(config.total);
+    return resetItems(config.total || 0);
   });
 
   // keep track of pages that are currently loading
@@ -182,33 +223,6 @@ export function useListLoader<
     [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);
@@ -216,25 +230,29 @@ export function useListLoader<
 
   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) => {
+    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]) {
-        load(
-          {
-            pageNumber: Math.floor(index / config.pageSize) + 1,
-            pageSize: config.pageSize,
-            filter,
-            sorter,
-          },
-          loadRef.current,
-          loadingRef.current
-        )
+        if (config.shouldLoad && !config.shouldLoad(params, prevState)) {
+          return false;
+        }
+        load(params, loadRef.current, loadingRef.current)
           .then(updateItems)
           .then(() => {
             cancelAnimationFrame(requestAnimationFrameRef.current);
@@ -262,6 +280,40 @@ export function useListLoader<
 
   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) {
@@ -280,11 +332,12 @@ export function useListLoader<
     );
 
     pagesToLoad.forEach(pageNumber => {
-      load(
-        {pageNumber, pageSize: config.pageSize, filter, sorter},
-        loadRef.current,
-        loadingRef.current
-      ).then(updateItems);
+      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 () => {
@@ -292,6 +345,14 @@ export function useListLoader<
     };
   }, [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`.
@@ -308,6 +369,7 @@ export function useListLoader<
         (loading, result) => loading || result,
         false
       ),
+      load: loaderLoad,
     },
   };
 }

package/collection/lib/useOverflowListItemMeasure.tsx

@@ -19,8 +19,8 @@ const hiddenStyles = {
  * ```
  */
 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

@@ -8,17 +8,15 @@ import {useOverflowListModel} from './useOverflowListModel';
  * 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?: React.Ref<HTMLElement>) => {
-    const localRef = React.useRef(null);
-    const {ref: resizeRef} = useResizeObserver({
-      ref: localRef,
-      onResize: model.events.setContainerWidth,
-    });
-    const elementRef = useForkRef(ref, resizeRef);
+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

@@ -14,33 +14,31 @@ const 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?: 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 : {},
-    };
-  }
-);
+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

@@ -71,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);