@workday/canvas-kit-react 8.5.0-339-next.0 → 8.5.0-342-next.2

package/collection/lib/ListBox.tsx

@@ -22,7 +22,7 @@ export const ListBoxItem = createSubcomponent('li')({
   return <Box as={Element} {...elemProps} />;
 });
 
-const useListBox = createElemPropsHook(useListModel)(model => {
+export const useListBox = createElemPropsHook(useListModel)(model => {
   return {
     style: {
       position: 'relative' as const,
@@ -32,8 +32,17 @@ const useListBox = createElemPropsHook(useListModel)(model => {
 });
 
 /**
- * Basic list box that supports virtualization. `ListBox.Item` contains a very simple list item
- * without much functionality. The `ListBox` contains two `Box` elements:
+ * The `ListBox` component that offers vertical rendering of a collection in the form of a
+ * 2-dimension list. It supports virtualization, rendering only visible items in the DOM while also
+ * providing aria attributes to allow screen readers to still navigate virtual lists. The `ListBox`
+ * contains a basic `ListBox.Item` that renders list items that render correctly with virtualization
+ * and adds `aria-setsize` and `aria-posinset` for screen readers.
+
+ * The `ListBox` is very basic and only adds enough functionality to render correctly. No additional
+ * behaviors are added to navigate or select. React Hooks are provided to add this functionality and
+ * are used by higher level components like `Menu` and `Menu.Item` which utilize `ListBox`. The
+ * `ListBox` contains two `Box` elements:
+ *
  * - Outer Box: Presentational container element responsible for overflow and height. `height` and
  *   `maxHeight` props will be applied here.
  * - Inner Box: The element responsible for the virtual container. Height is controlled by the model
@@ -45,9 +54,13 @@ export const ListBox = createContainer('ul')({
   elemPropsHook: useListBox,
   subComponents: {
     /**
-     * Extremely simple ListBox item that contains no functionality other than registering items and
-     * adding aria virtualization attributes. If you need more functionality, create your own
-     * component using list item hooks.
+     * The `ListBox.Item` is a simple placeholder for listbox items. The functionality of a
+     * collection item varies between components. For example, a `Tabs.Item` and a `Menu.Item` have
+     * shared functionality, but have different behavior. All collection-based components should
+     * implement a custom `Item` subcomponent using the collection-based behavior hooks. The [Roving
+     * Tabindex](#roving-tabindex) example uses the `elemPropsHook` to provide additional
+     * functionality. `elemPropsHook` is provided on all compound components and is useful in the
+     * example to add additional functionality without making a new component.
      */
     Item: ListBoxItem,
   },

package/collection/lib/useCursorListModel.tsx

@@ -5,6 +5,11 @@ import {useBaseListModel, Item, defaultGetId as getId} from './useBaseListModel'
 
 type NavigationInput = Pick<ReturnType<typeof useCursorListModel>, 'state'>;
 
+/**
+ * The list and grid models accept a `navigation` config. If one is not provided, a default will be
+ * chosen. It is possible to create a custom navigation manager to hand to the model if the default
+ * doesn't work.
+ */
 export interface NavigationManager {
   /** Get the first item in a collection. This will be called when the `Home` key is pressed for
    * Lists and `Ctrl+Home` for Grids. */
@@ -61,8 +66,10 @@ export interface NavigationManager {
  */
 export const createNavigationManager = (manager: NavigationManager) => manager;
 
-/** Function type to make it easier to define navigation functions */
-export type NavigationRequestor = (id: string, {state}: NavigationInput) => Item<Generic>;
+/**
+ * Given an id and a model, return an item from the collection
+ */
+export type NavigationRequestor = (id: string, model: NavigationInput) => Item<Generic>;
 
 /**
  * Get the first item in a list regardless of column count

package/collection/lib/useGridModel.ts

@@ -4,6 +4,10 @@ import {useListModel} from './useListModel';
 
 const {columnCount, orientation, ...defaultConfig} = useListModel.defaultConfig;
 
+/**
+ * The Grid model extends the `ListModel` and changes some config. For example, the `columnCount` is
+ * required on the grid model's configuration and `orientation` is removed.
+ */
 export const useGridModel = createModelHook({
   defaultConfig: {
     ...defaultConfig,

package/collection/lib/useListItemRegister.tsx

@@ -12,8 +12,17 @@ import {VirtualItem} from './react-virtual';
 import {useListModel} from './useListModel';
 
 /**
- * Registers an item with a list. It will return elemProps with a `data-id` which can be used by other
- * hooks to identify the item in the list.
+ * This elemProps hook is the base of all item component hooks. It registers an item with a
+ * collection and sets the `data-id` that is used by other hooks. It should always be the last
+ * defined hook when using `composeHooks` (`composeHooks` executes hooks right to left and merges
+ * props left to right). It is used by `ListBox.Item` and all `*.Item` subcomponents.
+ *
+ * ```ts
+ * const useMyItem = composeHooks(
+ *   useListItemSelect, // additional hooks go here
+ *   useListItemRegister // always last
+ * );
+ * ```
  */
 export const useListItemRegister = createElemPropsHook(useListModel)(
   (

package/collection/lib/useListItemRovingFocus.tsx

@@ -56,10 +56,18 @@ const keys = <T extends object>(obj: T): (keyof T)[] => Object.keys(obj) as (key
 const hasOwnKey = <T extends object>(obj: T, key: any): key is keyof T => obj.hasOwnProperty(key);
 
 /**
- * Handles the roving focus behavior of a Cursor model. It should be added to the element
- * representing a list item.
+ * 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
+ * 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.
  *
- * @see https://www.w3.org/TR/wai-aria-practices/#kbd_roving_tabindex
+ * ```ts
+ * const useMyItem = composeHooks(
+ *   useListItemRovingFocus, // adds the roving tabindex support
+ *   useListItemRegister
+ * );
+```
  */
 export const useListItemRovingFocus = createElemPropsHook(useCursorListModel)(
   ({state, events, getId, navigation}, ref, elemProps: {'data-id'?: string} = {}) => {

package/collection/lib/useListItemSelect.tsx

@@ -4,6 +4,18 @@ import {createElemPropsHook} from '@workday/canvas-kit-react/common';
 
 import {useListModel} from './useListModel';
 
+/**
+ * This elemProps hook adds selection support to a `*.Item` subcomponent of a collection. It adds a
+ * click handler that toggles selection status according to the [Selection
+ * Manager](#selection-manager) used.
+ *
+ * ```ts
+ * const useMyItem = composeHooks(
+ *   useListItemSelect, // adds selection support to an item
+ *   useListItemRegister
+ * );
+ * ```
+ */
 export const useListItemSelect = createElemPropsHook(useListModel)(
   ({state, events}, _?: React.Ref<HTMLElement>, elemProps: {'data-id'?: string} = {}) => {
     const name = elemProps['data-id'] || '';

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,6 +4,20 @@ 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

package/collection/lib/useListResetCursorOnBlur.tsx

@@ -5,7 +5,18 @@ import {orientationKeyMap} from './useListItemRovingFocus';
 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,6 +7,17 @@ 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);

package/collection/lib/useOverflowListMeasure.ts

@@ -4,6 +4,10 @@ import {createElemPropsHook, useForkRef, useResizeObserver} from '@workday/canva
 
 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);

package/collection/lib/useOverflowListTarget.tsx

@@ -10,6 +10,10 @@ const hiddenStyle = {
   left: -99999,
 };
 
+/**
+ * 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);

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;
 }
 

package/common/lib/EllipsisText.tsx

@@ -1,5 +1,7 @@
+import React from 'react';
 import styled, {CSSObject} from '@emotion/styled';
-import {ElementComponent} from '..';
+
+import {createComponent} from './utils';
 
 export const ellipsisStyles: CSSObject = {
   whiteSpace: 'nowrap',
@@ -7,5 +9,11 @@ export const ellipsisStyles: CSSObject = {
   overflow: 'hidden',
 };
 
-// Recast as an `ElementComponent` due to better type support for `as` and `ref`
-export const EllipsisText = (styled('span')(ellipsisStyles) as any) as ElementComponent<'span', {}>;
+const StyledEllipsisComponent = styled('span')(ellipsisStyles);
+
+export const EllipsisText = createComponent('span')({
+  displayName: 'EllipsisText',
+  Component(elemProps = {}, ref, Element) {
+    return <StyledEllipsisComponent as={Element} ref={ref} {...elemProps} />;
+  },
+});

package/common/lib/theming/getObjectProxy.ts

@@ -5,10 +5,11 @@
  * @param target Any custom theme object
  * @param fallback A fallback theme object
  */
-/* eslint-disable compat/compat  */ // TODO: Revisit eslint rules that are no longer needed now that we don't support IE11
+/* eslint-disable compat/compat  */
 export function getObjectProxy<T extends {}>(target: unknown, fallback: T): T {
   return new Proxy(target as any, {
-    get(target, prop: keyof T) {
+    get(target, p: string) {
+      const prop = p as keyof T; // keep Typescript happy - the `get` signature cannot contain `keyof T`
       if (typeof fallback[prop] === 'object' && typeof target[prop] === 'object') {
         return getObjectProxy(target[prop] || {}, fallback[prop]);
       } else if (target[prop] !== undefined) {

package/common/lib/utils/components.ts

@@ -106,7 +106,7 @@ export type ExtractProps<
       : TElement extends keyof JSX.IntrinsicElements // `TElement` was defined, test if it is in `JSX.IntrinsicElements`
       ? P & ExtractHTMLAttributes<JSX.IntrinsicElements[TElement]> // `TElement` is in `JSX.IntrinsicElements`, return inferred props `P` + HTML attributes of `TElement`
       : P & ExtractProps<TElement> // `TElement` is not in `JSX.IntrinsicElements`, return inferred props `P` + props extracted from component `TElement`.
-    : TComponent extends Component<infer P> // test if `TComponent` is a `Component`, while inferring props `P`
+    : TComponent extends {__props: infer P} // test if `TComponent` is a `Component`, while inferring props `P`
     ? P // else attach only inferred props `P`
     : TComponent extends React.ComponentType<infer P> // test if `TComponent` is a `React.ComponentType` (class or functional component)
     ? P // it was a `React.ComponentType`, return inferred props `P`
@@ -205,7 +205,7 @@ export type Component<P> = {
 
 interface RefForwardingComponent<T, P = {}> {
   (
-    props: React.PropsWithChildren<P> & {as?: React.ElementType},
+    props: React.PropsWithChildren<P>,
     /**
      * A ref to be forwarded. Pass it along to the root element. If no element was passed, this
      * will result in a `never`
@@ -515,6 +515,35 @@ export const createComponent = <
   return ReturnedComponent as any;
 };
 
+/**
+ * An `elemPropsHook` is a React hook that takes a model, ref, and elemProps and returns props and
+ * attributes to be spread to an element or component.
+ *
+ * ```tsx
+ * const useMyHook = createElemPropsHook(useMyModel)((model) => {
+ *   return {
+ *     id: model.state.id
+ *   }
+ * })
+ * ```
+ *
+ * **Note:** If your hook needs to use a ref, it must be forked using `useLocalRef` or `useForkRef`
+ * and return the forked ref:
+ *
+ * ```tsx
+ * const useMyHook = createElemPropsHook(useMyModel)((model, ref, elemProps) => {
+ *   const {localRef, elementRef} = useLocalRef(ref);
+ *
+ *   React.useLayoutEffect(() => {
+ *     console.log('element', localRef.current) // logs the DOM element
+ *   }, [])
+ *
+ *   return {
+ *     ref: elementRef
+ *   }
+ * })
+ * ```
+ */
 export const createElemPropsHook = <
   TModelHook extends (config: any) => {state: Record<string, any>; events: Record<string, any>}
 >(
@@ -588,6 +617,9 @@ export const createHook = <M extends Model<any, any>, PO extends {}, PI extends
   };
 };
 
+/**
+ * @deprecated use `subModel` instead
+ */
 export const subModelHook = <M extends Model<any, any>, SM extends Model<any, any>, O extends {}>(
   fn: (model: M) => SM,
   hook: BehaviorHook<SM, O>
@@ -597,6 +629,42 @@ export const subModelHook = <M extends Model<any, any>, SM extends Model<any, an
   };
 };
 
+/**
+ * Creates an elemPropsHook that returns the elemProps from another hook that is meant for a
+ * subModel. Usually only used when composing elemProps hooks.
+ *
+ * For example:
+ *
+ * ```tsx
+ * const useMySubModel = () => {}
+ *
+ * const useMyModel = () => {
+ *   const subModel = useMySubModel()
+ *
+ *   return {
+ *     state,
+ *     events,
+ *     subModel,
+ *   }
+ * }
+ *
+ * const useMyComponent = composeHook(
+ *   createElemPropsHook(useMyModel)(model => ({ id: '' })),
+ *   createSubModelElemPropsHook(useMyModel)(m => m.subModel, useSomeOtherComponent)
+ * )
+ * ```
+ */
+export function createSubModelElemPropsHook<M extends () => Model<any, any>>(modelHook: M) {
+  return <SM extends Model<any, any>, O extends {}>(
+    fn: (model: ReturnType<M>) => SM,
+    elemPropsHook: BehaviorHook<SM, O>
+  ): BehaviorHook<ReturnType<M>, O> => {
+    return (model: ReturnType<M>, props: any, ref: React.Ref<any>) => {
+      return elemPropsHook(fn(model), props, ref);
+    };
+  };
+}
+
 // Typescript function parameters are contravariant while return types are covariant. This is a
 // problem when someone hands us a model that correctly extends `Model<any, any>`, but adds extra
 // properties to the model. So `M extends Model<any, any>`. But the `BehaviorHook` is the return
@@ -607,6 +675,10 @@ export const subModelHook = <M extends Model<any, any>, SM extends Model<any, an
 // isn't a real issue. Not 100% this is a bug, but the "hack" is a bit messy.
 // https://www.stephanboyer.com/post/132/what-are-covariance-and-contravariance
 // https://stackoverflow.com/questions/52667959/what-is-the-purpose-of-bivariancehack-in-typescript-types/52668133
+/**
+ * A BehaviorHook is a React hook that takes a model, elemProps, and a ref and returns props and
+ * attributes to apply to an element or component.
+ */
 export type BehaviorHook<M extends Model<any, any>, O extends {}> = {
   bivarianceHack<P extends {}, R>(
     model: M,
@@ -717,21 +789,42 @@ export function useModelContext<T>(context: React.Context<T>, model?: T): T {
 }
 
 /**
- * Compose many hooks together. Assumes hooks are using `mergeProps`. Returns a function that will
- * receive a model and return props to be applied to a component. These props should always be
- * applied last on the Component. The props will override as follows: rightmost hook props override
- * leftmost hook props which are overridden by props passed to the composeHooks function.
+ * Compose many hooks together. Each hook should make a call to `mergeProps` which is automatically
+ * done by `createElemPropsHook` and `createHook. Returns a function that will receive a model and
+ * return props to be applied to a component. Hooks run from right to left, but props override from
+ * left to right.
  *
- * A `ref` should be passed for hooks that require a ref. Each hook should fork the ref using
- * `useLocalRef`, passing the `elementRef` in the returned props object. This ref will be passed to
- * the next hook.
+ * For example:
  *
- * @example
- * const MyComponent = React.forwardRef(({ children, model, ...elemProps }, ref) => {
- *   const props = composeHooks(useHook1, useHook2)(model, elemProps, ref)
+ * ```ts
+ * const useHook1 = createElemPropsHook(useMyModel)((model, ref, elemProps) => {
+ *   console.log('useHook1', elemProps)
+ *   return {
+ *     a: 'useHook1',
+ *     c: 'useHook1'
+ *   }
+ * })
  *
- *   return <div id="foo" {...props}>{children}</div>
+ * const useHook2 = createElemPropsHook(useMyModel)((model, ref, elemProps) => {
+ *   console.log('useHook2', elemProps)
+ *   return {
+ *     b: 'useHook2',
+ *     c: 'useHook2'
+ *   }
  * })
+ *
+ * const useHook3 = composeHooks(useHook1, useHook2)
+ * const props = composeHooks(model, { c: 'props' })
+ * console.log('props', props)
+ * ```
+ *
+ * The output would be:
+ *
+ * ```ts
+ * useHook2 {c: 'foo'}
+ * useHook1 {b: 'useHook2', c: 'foo'}
+ * props {a: 'useHook1', b: 'useHook2', c: 'foo'}
+ * ```
  */
 export function composeHooks<M extends Model<any, any>, O1 extends {}, O2 extends {}>(
   hook1: BehaviorHook<M, O1>,
@@ -740,8 +833,6 @@ export function composeHooks<M extends Model<any, any>, O1 extends {}, O2 extend
 
 export function composeHooks<
   M extends Model<any, any>,
-  R,
-  P extends {},
   O1 extends {},
   O2 extends {},
   O3 extends {}
@@ -752,8 +843,6 @@ export function composeHooks<
 ): BehaviorHook<M, O1 & O2 & O3>;
 export function composeHooks<
   M extends Model<any, any>,
-  R,
-  P extends {},
   O1 extends {},
   O2 extends {},
   O3 extends {},
@@ -766,8 +855,6 @@ export function composeHooks<
 ): BehaviorHook<M, O1 & O2 & O3 & O4>;
 export function composeHooks<
   M extends Model<any, any>,
-  R,
-  P extends {},
   O1 extends {},
   O2 extends {},
   O3 extends {},

package/dialog/lib/DialogPopper.tsx

@@ -14,6 +14,9 @@ export const DialogPopper = createSubcomponent('div')({
   ({children, placement, popperOptions, ref, ...props}, Element, model) => {
     const popperProps = usePopupPopper(model, {placement, popperOptions}, ref);
     const elemProps = useDialogPopper(model, props);
+    if (model.state.visibility === 'hidden') {
+      return null;
+    }
     return (
       <Element {...elemProps}>
         <Popper {...popperProps}>{children}</Popper>

package/disclosure/lib/useDisclosureModel.tsx

@@ -22,8 +22,8 @@ export const useDisclosureModel = createModelHook({
     id,
     /**
      * Visibility state of the disclosed content. Models are allowed to extend the states to fit
-     * their needs, so if you need to consistently determine "not hidden", use `visibility !==
-     * 'hidden'` rather than `visibility === 'visible'`
+     * their needs, so if you need to consistently determine "not hidden", use
+     * `visibility !== 'hidden'` rather than `visibility === 'visible'`
      */
     visibility,
   };