@workday/canvas-kit-react 7.0.0-alpha.89-next.16 → 7.0.0-alpha.92-next.19

package/collection/lib/useListItemRegister.tsx

@@ -0,0 +1,85 @@
+import React, {CSSProperties} from 'react';
+
+import {
+  useMountLayout,
+  createElemPropsHook,
+  useLocalRef,
+  useForkRef,
+} from '@workday/canvas-kit-react/common';
+
+import {Item} from './useBaseListModel';
+import {VirtualItem} from './react-virtual';
+import {useListModel} from './useListModel';
+
+/**
+ * Registers an item with a list. It will return elemProps with a `name` which can be used by other
+ * hooks to identify the item in the list.
+ */
+export const useListItemRegister = createElemPropsHook(useListModel)(
+  (
+    {state, events, getId},
+    ref?: React.Ref<HTMLElement>,
+    elemProps: {
+      'data-id'?: string;
+      children?: React.ReactNode;
+      index?: number;
+      disabled?: boolean;
+      item?: Item<any>;
+      virtual?: VirtualItem;
+    } = {}
+  ) => {
+    const [localId, setLocalId] = React.useState(elemProps['data-id'] || elemProps.item?.id || '');
+    const {localRef, elementRef} = useLocalRef(useForkRef(ref, elemProps.virtual?.measureRef));
+
+    // if the list is virtual, force the correct styling. Without this, weird things happen...
+    const style: CSSProperties = elemProps.virtual
+      ? {
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          transform: `translateY(${elemProps.virtual.start}px)`,
+        }
+      : {};
+
+    useMountLayout(() => {
+      if (elemProps.virtual?.index === 0 && localRef.current?.clientHeight) {
+        // TODO: This update doesn't seem to be working correctly
+        // events.updateItemHeight?.(localRef.current!.clientHeight);
+      }
+      // if an item is already provided, there's nothing left to do
+      if (elemProps.item) {
+        return;
+      }
+      const defaultId = state.indexRef.current;
+      const itemId = localId || String(defaultId);
+
+      // TODO: Better lookup that using `items.find`. We need a more generic collection to handle seeing if an item already exists
+      // bail early if item already exists. This happens if items were already provided.
+      if (state.items.find(item => getId(item) === itemId)) {
+        return;
+      }
+      events.registerItem({
+        item: {
+          id: itemId,
+        },
+        textValue: typeof elemProps.children === 'string' ? elemProps.children : '',
+      });
+      setLocalId(itemId);
+
+      return () => {
+        events.unregisterItem({id: itemId});
+      };
+    });
+
+    return {
+      ref: elementRef,
+      'data-id': localId,
+      disabled: elemProps.disabled || state.nonInteractiveIds.includes(localId) ? true : undefined,
+      item: null, // remove `item` from prop list
+      virtual: null, // remove `virtual` from prop list
+      'aria-setsize': elemProps.virtual?.size,
+      'aria-posinset': elemProps.virtual ? elemProps.item!.index + 1 : undefined,
+      style,
+    };
+  }
+);

package/collection/lib/useListItemRovingFocus.tsx

@@ -0,0 +1,144 @@
+import React from 'react';
+import {useIsRTL, createElemPropsHook} from '@workday/canvas-kit-react/common';
+
+import {useCursorListModel} from './useCursorListModel';
+
+export const orientationKeyMap = {
+  horizontal: {
+    ArrowLeft: 'goToPrevious',
+    Left: 'goToPrevious',
+    ArrowRight: 'goToNext',
+    Right: 'goToNext',
+    Home: 'goToFirst',
+    End: 'goToLast',
+    PageDown: 'goToNextPage',
+    PageUp: 'goToPreviousPage',
+  },
+  vertical: {
+    ArrowUp: 'goToPrevious',
+    Up: 'goToPrevious',
+    ArrowDown: 'goToNext',
+    Down: 'goToNext',
+    Home: 'goToFirst',
+    End: 'goToLast',
+    PageDown: 'goToNextPage',
+    PageUp: 'goToPreviousPage',
+  },
+} as const;
+
+const rightToLeftMap = {
+  ArrowLeft: 'ArrowRight',
+  Left: 'Right',
+  ArrowRight: 'ArrowLeft',
+  Right: 'Left',
+  Home: 'Home',
+  End: 'End',
+  PageDown: 'PageDown',
+  PageUp: 'PageUp',
+} as const;
+
+const gridKeyMap = {
+  ...orientationKeyMap.horizontal,
+  Home: 'goToFirstOfRow',
+  End: 'goToLastOfRow',
+  ArrowUp: 'goToPreviousRow',
+  Up: 'goToPreviousRow',
+  ArrowDown: 'goToNextRow',
+  Down: 'goToNextRow',
+} as const;
+
+const ctrlKeyMap = {
+  Home: 'goToFirst',
+  End: 'goToLast',
+} as const;
+
+const keys = <T extends object>(obj: T): (keyof T)[] => Object.keys(obj) as (keyof T)[];
+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.
+ *
+ * @see https://www.w3.org/TR/wai-aria-practices/#kbd_roving_tabindex
+ */
+export const useListItemRovingFocus = createElemPropsHook(useCursorListModel)(
+  ({state, events, getId, navigation}, ref, elemProps: {'data-id'?: string} = {}) => {
+    // Tracks when this element has focus. If this item is removed while still focused, we have to
+    // inform the model to move the cursor to the next item.
+    const focusRef = React.useRef(false);
+    const getIdRef = React.useRef(getId);
+
+    // 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
+    const stateRef = React.useRef(state);
+    stateRef.current = state;
+
+    const keyDownRef = React.useRef(false);
+    const isRTL = useIsRTL();
+
+    React.useEffect(() => {
+      if (keyDownRef.current) {
+        const item = navigation.getItem(state.cursorId, {state});
+        if (state.isVirtualized) {
+          state.UNSTABLE_virtual.scrollToIndex(item.index);
+        }
+        requestAnimationFrame(() => {
+          document
+            .querySelector<HTMLElement>(`[id="${state.id}-${getIdRef.current(item)}"]`)
+            ?.focus();
+        });
+
+        keyDownRef.current = false;
+      }
+      // we only want to run this effect if the cursor changes and not any other time
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [state.cursorId]);
+
+    return {
+      onKeyDown(event: React.KeyboardEvent) {
+        // Test ctrl key first
+        if (event.ctrlKey) {
+          for (const key in ctrlKeyMap) {
+            if (hasOwnKey(ctrlKeyMap, key)) {
+              keyDownRef.current = true;
+              events[ctrlKeyMap[key]]?.();
+              event.preventDefault();
+              return;
+            }
+          }
+        }
+        // Try regular keys
+        keys(state.columnCount > 0 ? gridKeyMap : orientationKeyMap[state.orientation]).forEach(
+          key => {
+            if (isRTL ? event.key === rightToLeftMap[key] : event.key === key) {
+              const eventName =
+                state.columnCount > 0 ? gridKeyMap[key] : orientationKeyMap[state.orientation][key];
+              keyDownRef.current = true;
+              if (events[eventName]) {
+                events[eventName]?.();
+                event.preventDefault();
+              }
+            }
+          }
+        );
+      },
+      onFocus() {
+        focusRef.current = true;
+      },
+      onBlur() {
+        focusRef.current = false;
+      },
+      onClick() {
+        events.goTo({id: elemProps['data-id']!});
+      },
+      id: `${state.id}-${elemProps['data-id']}`,
+      tabIndex: !state.cursorId
+        ? 0 // cursor isn't known yet, be safe and mark this as focusable
+        : !!elemProps['data-id'] && 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/useListItemSelect.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+
+import {createElemPropsHook} from '@workday/canvas-kit-react/common';
+
+import {useListModel} from './useListModel';
+
+export const useListItemSelect = createElemPropsHook(useListModel)(
+  ({state, events}, _?: React.Ref<HTMLElement>, elemProps: {'data-id'?: string} = {}) => {
+    const name = elemProps['data-id'] || '';
+    const onClick = (event: React.MouseEvent<HTMLElement>) => {
+      if (
+        state.nonInteractiveIds.includes(name) ||
+        event.currentTarget.hasAttribute('aria-disabled')
+      ) {
+        return;
+      }
+      events.select({id: name});
+    };
+
+    return {onClick};
+  }
+);

package/collection/lib/useListModel.tsx

@@ -0,0 +1,34 @@
+import {createModelHook} from '@workday/canvas-kit-react/common';
+import {useSelectionListModel} from './useSelectionListModel';
+
+// This file creates a `ListModel` composing a `BaseListModel`, `CursorListModel`, and
+// `SelectionListModel` and renames to `List*`. Without interfaces like this, the result would be
+// `SelectionList*` which is confusing to users, but the separation is easier to maintain
+
+export type ListProps<T = unknown> = {
+  children: React.ReactNode | ((item: T) => React.ReactNode);
+};
+
+export type ListItemProps = {
+  children?: React.ReactNode;
+  'data-id'?: string;
+};
+
+/**
+ * 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.
+ *
+ * @example
+ * const list = useListModel({
+ *   // custom handling for selection. single and multi select are provided
+ *   selection: mySelectionManager,
+ *   // wrapping and non-wrapping navigation are provided
+ *   navigation: myNavigationManager,
+ *   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,
+  requiredConfig: useSelectionListModel.requiredConfig,
+})(useSelectionListModel);

package/collection/lib/useListRenderItem.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+
+import {Generic} from '@workday/canvas-kit-react/common';
+
+import {useBaseListModel} from './useBaseListModel';
+
+export function useListRenderItems<T>(
+  model: ReturnType<typeof useBaseListModel>,
+  children: ((item: Generic) => 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);
+            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: item,
+            });
+          })
+        : model.state.items.map(item =>
+            React.cloneElement(children(item.value), {key: item.id, item: item.value})
+          )
+      : null;
+
+  return items || children;
+}

package/{tabs/lib/selection/useResetCursorOnBlur.tsx → collection/lib/useListResetCursorOnBlur.tsx}

@@ -1,14 +1,13 @@
 import React from 'react';
 
-import {createHook} from '@workday/canvas-kit-react/common';
-import {orientationKeyMap} from '../cursor';
-
-import {SelectionModel} from './useSelectionModel';
+import {createElemPropsHook} from '@workday/canvas-kit-react/common';
+import {orientationKeyMap} from './useListItemRovingFocus';
+import {useListModel} from './useListModel';
 
 /**
  * Reset the cursor to the selected item when the list looses focus
  */
-export const useResetCursorOnBlur = createHook(({state, events}: SelectionModel) => {
+export const useListResetCursorOnBlur = createElemPropsHook(useListModel)(({state, events}) => {
   const programmaticFocusRef = React.useRef(false);
   return {
     onKeyDown(event: React.KeyboardEvent) {

package/{tabs/lib/overflow/useOverflowMeasureItem.tsx → collection/lib/useOverflowListItemMeasure.tsx}

@@ -1,16 +1,16 @@
-import {createHook, useLocalRef, useMountLayout} from '@workday/canvas-kit-react/common';
+import {createElemPropsHook, useLocalRef, useMountLayout} from '@workday/canvas-kit-react/common';
 
-import {OverflowModel} from './useOverflowModel';
+import {useOverflowListModel} from './useOverflowListModel';
 
 const hiddenStyles = {
   position: 'absolute',
   left: -99999,
 } as const;
 
-export const useOverflowMeasureItem = createHook(
-  (model: OverflowModel, ref?: React.Ref<HTMLElement>, elemProps: {name?: string} = {}) => {
+export const useOverflowListItemMeasure = createElemPropsHook(useOverflowListModel)(
+  (model, ref?: React.Ref<HTMLElement>, elemProps: {'data-id'?: string} = {}) => {
     const {elementRef, localRef} = useLocalRef(ref);
-    const name = elemProps.name || '';
+    const name = elemProps['data-id'] || '';
 
     useMountLayout(() => {
       if (localRef.current) {

package/{tabs/lib/overflow/useOverflowMeasureContainer.ts → collection/lib/useOverflowListMeasure.ts}

@@ -1,11 +1,11 @@
 import * as React from 'react';
 
-import {createHook, useForkRef, useResizeObserver} from '@workday/canvas-kit-react/common';
+import {createElemPropsHook, useForkRef, useResizeObserver} from '@workday/canvas-kit-react/common';
 
-import {OverflowModel} from './useOverflowModel';
+import {useOverflowListModel} from './useOverflowListModel';
 
-export const useOverflowMeasureContainer = createHook(
-  (model: OverflowModel, ref?: React.Ref<HTMLElement>) => {
+export const useOverflowListMeasure = createElemPropsHook(useOverflowListModel)(
+  (model, ref?: React.Ref<HTMLElement>) => {
     const localRef = React.useRef(null);
     const {ref: resizeRef} = useResizeObserver({
       ref: localRef,

package/{tabs/lib/overflow/useOverflowModel.tsx → collection/lib/useOverflowListModel.tsx}

@@ -1,65 +1,7 @@
 import React from 'react';
 
-import {createEventMap, ToModelConfig, useEventMap} from '@workday/canvas-kit-react/common';
-import {
-  SelectionState,
-  SelectionEvents,
-  BaseSelectionModelConfig,
-  useSelectionModel,
-  SelectionModelConfig,
-  selectionEventMap,
-  SelectionModel,
-} from '../selection';
-
-export type OverflowState<T = unknown> = SelectionState<T> & {
-  containerWidth: number;
-  overflowTargetWidth: number;
-  itemWidthCache: Record<string, number>;
-  hiddenIds: string[];
-};
-
-export type OverflowEvents<T = unknown> = SelectionEvents<T> & {
-  setContainerWidth(data: {width?: number}): void;
-  setOverflowTargetWidth(data: {width: number}): void;
-  addItemWidth(data: {id: string; width: number}): void;
-  removeItemWidth(data: {id: string}): void;
-  addHiddenKey(data: {id: string}): void;
-  removeHiddenKey(data: {id: string}): void;
-};
-
-export interface OverflowModel<T = unknown> extends SelectionModel<T> {
-  state: OverflowState<T>;
-  events: OverflowEvents<T>;
-}
-
-export const overflowEventMap = createEventMap<OverflowEvents>()({
-  guards: {
-    ...selectionEventMap.guards,
-    shouldSetContainerWidth: 'setContainerWidth',
-    shouldSetOverflowTargetWidth: 'setOverflowTargetWidth',
-    shouldAddItemWidth: 'addItemWidth',
-    shouldRemoveItemWidth: 'removeItemWidth',
-    shouldAddHiddenKey: 'addHiddenKey',
-    shouldRemoveHiddenKey: 'removeHiddenKey',
-  },
-  callbacks: {
-    ...selectionEventMap.callbacks,
-    onSetContainerWidth: 'setContainerWidth',
-    onSetOverflowTargetWidth: 'setOverflowTargetWidth',
-    onAddItemWidth: 'addItemWidth',
-    onRemoveItemWidth: 'removeItemWidth',
-    onAddHiddenKey: 'addHiddenKey',
-    onRemoveHiddenKey: 'removeHiddenKey',
-  },
-});
-
-export type BaseOverflowModelConfig<T> = BaseSelectionModelConfig<T> & {
-  initialHiddenIds?: string[];
-  containerWidth?: number;
-};
-
-export type OverflowModelConfig<T> = BaseOverflowModelConfig<T> &
-  Partial<ToModelConfig<OverflowState<T>, OverflowEvents<T>, typeof selectionEventMap>>;
+import {createModelHook} from '@workday/canvas-kit-react/common';
+import {useSelectionListModel} from './useSelectionListModel';
 
 export function getHiddenIds(
   containerWidth: number,
@@ -108,10 +50,16 @@ export function getHiddenIds(
   return hiddenIds;
 }
 
-export const useOverflowModel = <T extends unknown>(
-  config: OverflowModelConfig<T> = {}
-): OverflowModel<T> => {
-  const [hiddenIds, setHiddenIds] = React.useState(config.initialHiddenIds || []);
+export const useOverflowListModel = createModelHook({
+  defaultConfig: {
+    ...useSelectionListModel.defaultConfig,
+    initialHiddenIds: [] as string[],
+    containerWidth: 0,
+  },
+  requiredConfig: useSelectionListModel.requiredConfig,
+  contextOverride: useSelectionListModel.Context,
+})(config => {
+  const [hiddenIds, setHiddenIds] = React.useState(config.initialHiddenIds);
   const [itemWidthCache, setItemWidthCache] = React.useState<Record<string, number>>({});
   const [containerWidth, setContainerWidth] = React.useState(0);
   const containerWidthRef = React.useRef(0);
@@ -123,7 +71,10 @@ export const useOverflowModel = <T extends unknown>(
   // hidden ids as well
   const nonInteractiveIds = (config.nonInteractiveIds || []).concat(hiddenIds);
 
-  const model = useSelectionModel({...(config as SelectionModelConfig<T>), nonInteractiveIds});
+  const model = useSelectionListModel({
+    ...config,
+    nonInteractiveIds,
+  });
 
   const state = {
     ...model.state,
@@ -133,10 +84,10 @@ export const useOverflowModel = <T extends unknown>(
     overflowTargetWidth,
   };
 
-  const events = useEventMap(overflowEventMap, state, config, {
+  const events = {
     ...model.events,
-    select(data) {
-      const {selectedIds} = model.selection.select(data.id, state as SelectionState<T>);
+    select(data: Parameters<typeof model.events.select>[0]) {
+      const {selectedIds} = model.selection.select(data.id, state);
       const ids = getHiddenIds(
         containerWidthRef.current,
         overflowTargetWidthRef.current,
@@ -147,9 +98,9 @@ export const useOverflowModel = <T extends unknown>(
 
       setHiddenIds(ids);
     },
-    setContainerWidth({width}) {
-      containerWidthRef.current = width || 0;
-      setContainerWidth(width || 0);
+    setContainerWidth(data: {width?: number}) {
+      containerWidthRef.current = data.width || 0;
+      setContainerWidth(data.width || 0);
 
       const ids = getHiddenIds(
         containerWidthRef.current,
@@ -160,12 +111,15 @@ export const useOverflowModel = <T extends unknown>(
 
       setHiddenIds(ids);
     },
-    setOverflowTargetWidth({width}) {
-      overflowTargetWidthRef.current = width;
-      setOverflowTargetWidth(width);
+    setOverflowTargetWidth(data: {width: number}) {
+      overflowTargetWidthRef.current = data.width;
+      setOverflowTargetWidth(data.width);
     },
-    addItemWidth({id, width}) {
-      itemWidthCacheRef.current = {...itemWidthCacheRef.current, [id]: width};
+    addItemWidth(data: {id: string; width: number}) {
+      itemWidthCacheRef.current = {
+        ...itemWidthCacheRef.current,
+        [data.id]: data.width,
+      };
 
       setItemWidthCache(itemWidthCacheRef.current);
 
@@ -178,9 +132,9 @@ export const useOverflowModel = <T extends unknown>(
 
       setHiddenIds(ids);
     },
-    removeItemWidth({id}) {
+    removeItemWidth(data: {id: string}) {
       const newCache = {...itemWidthCacheRef.current};
-      delete newCache[id];
+      delete newCache[data.id];
       itemWidthCacheRef.current = newCache;
       setItemWidthCache(itemWidthCacheRef.current);
 
@@ -189,19 +143,19 @@ export const useOverflowModel = <T extends unknown>(
         overflowTargetWidthRef.current,
         itemWidthCacheRef.current,
         state.selectedIds !== 'all'
-          ? state.selectedIds.filter(sId => id !== sId)
+          ? state.selectedIds.filter(sId => data.id !== sId)
           : state.selectedIds
       );
 
       setHiddenIds(ids);
     },
-    addHiddenKey({id}) {
-      setHiddenIds(ids => ids.concat(id));
+    addHiddenKey(data: {id: string}) {
+      setHiddenIds(ids => ids.concat(data.id));
     },
-    removeHiddenKey({id}) {
-      setHiddenIds(ids => ids.filter(key => key !== id));
+    removeHiddenKey(data: {id: string}) {
+      setHiddenIds(ids => ids.filter(key => key !== data.id));
     },
-  } as OverflowEvents<T>);
+  };
 
-  return {state, events, selection: model.selection, getId: model.getId};
-};
+  return {...model, state, events};
+});

package/{tabs/lib/overflow/useOverflowTarget.tsx → collection/lib/useOverflowListTarget.tsx}

@@ -1,8 +1,8 @@
 import React from 'react';
 
-import {createHook, useMountLayout, useLocalRef} from '@workday/canvas-kit-react/common';
+import {createElemPropsHook, useMountLayout, useLocalRef} from '@workday/canvas-kit-react/common';
 
-import {OverflowModel} from './useOverflowModel';
+import {useOverflowListModel} from './useOverflowListModel';
 
 // use a hidden style instead of `hidden` attribute for measurement purposes. `hidden` elements have no dimensions
 const hiddenStyle = {
@@ -10,8 +10,8 @@ const hiddenStyle = {
   left: -99999,
 };
 
-export const useOverflowTarget = createHook(
-  (model: OverflowModel, ref?: React.Ref<HTMLButtonElement>) => {
+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);

package/collection/lib/useSelectionListModel.tsx

@@ -0,0 +1,95 @@
+import React from 'react';
+import {createModelHook} from '@workday/canvas-kit-react/common';
+
+import {useCursorListModel} from './useCursorListModel';
+
+export type SelectedIds = 'all' | string[];
+
+export type Selection = {
+  selectedIds: SelectedIds;
+  unselectedIds: string[];
+};
+
+/**
+ * A SelectionManager is used
+ */
+export interface SelectionManager {
+  select(id: string, prevState: Selection): Selection;
+}
+
+export const isSelected = (id: string, {selectedIds, unselectedIds}: Selection) => {
+  if (selectedIds === 'all') {
+    return !unselectedIds.includes(id);
+  }
+  return selectedIds.includes(id);
+};
+
+export const singleSelectionManager: SelectionManager = {
+  select(id: string) {
+    return {selectedIds: [id], unselectedIds: []};
+  },
+};
+
+export const multiSelectionManager: SelectionManager = {
+  select(id: string, {selectedIds, unselectedIds}) {
+    if (selectedIds === 'all') {
+      // If we have all selected, start adding/removing from `unselectedIds`
+      const existingKey = unselectedIds.includes(id);
+      return {
+        selectedIds: 'all',
+        unselectedIds: existingKey
+          ? unselectedIds.filter(key => key !== id)
+          : unselectedIds.concat(id),
+      };
+    } else {
+      const existingKey = selectedIds.includes(id);
+      return {
+        selectedIds: existingKey ? selectedIds.filter(key => key !== id) : selectedIds.concat(id),
+        unselectedIds: [],
+      };
+    }
+  },
+};
+
+export const useSelectionListModel = createModelHook({
+  defaultConfig: {
+    ...useCursorListModel.defaultConfig,
+    initialSelectedIds: [] as SelectedIds,
+    initialUnselectedIds: [] as string[],
+    selection: singleSelectionManager,
+  },
+  requiredConfig: useCursorListModel.requiredConfig,
+})(config => {
+  const cursor = useCursorListModel(config);
+  const [selectedIds, setSelectedIds] = React.useState(config.initialSelectedIds);
+  const [unselectedIds, setUnselectedIds] = React.useState(config.initialUnselectedIds);
+
+  const selection = config.selection;
+
+  const state = {...cursor.state, selectedIds, unselectedIds};
+
+  const events = {
+    ...cursor.events,
+    /** Select a specific item by its identifier. */
+    select(data: {id: string}) {
+      const {selectedIds, unselectedIds} = selection.select(data.id, state);
+      setSelectedIds(selectedIds);
+      setUnselectedIds(unselectedIds);
+    },
+    /**
+     * Select all items. This will set `selectedIds` to `'all'` and remove all `unselectedIds`.
+     * This is especially useful for virtual lists where not all items are loaded in memory.
+     */
+    selectAll() {
+      setSelectedIds('all');
+    },
+    /**
+     * Unselect all items.
+     */
+    unselectAll() {
+      setSelectedIds([]);
+    },
+  };
+
+  return {...cursor, state, events, selection};
+});