@workday/canvas-kit-react 8.0.0-alpha.253-next.22 → 8.0.0-alpha.428-next.2

package/collection/lib/useListItemRovingFocus.tsx

@@ -2,147 +2,94 @@ import React from 'react';
 import {useIsRTL, createElemPropsHook} from '@workday/canvas-kit-react/common';
 
 import {useCursorListModel} from './useCursorListModel';
+import {keyboardEventToCursorEvents} from './keyUtils';
 
-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);
+// retry a function each frame so we don't rely on the timing mechanism of React's render cycle.
+const retryEachFrame = (cb: () => boolean, iterations: number) => {
+  if (cb() === false && iterations > 1) {
+    requestAnimationFrame(() => retryEachFrame(cb, iterations - 1));
+  }
+};
 
 /**
- * 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} = {}) => {
-    // 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);
-
+  (model, _ref, elemProps: {'data-id'?: string} = {}) => {
     // Create a ref out of state. We don't want to watch state on unmount, so we use a ref to get the
     // current value at the time of unmounting. Otherwise, `state.items` would be a cached value of an
     // empty array
-    const stateRef = React.useRef(state);
-    stateRef.current = state;
+    const stateRef = React.useRef(model.state);
+    stateRef.current = model.state;
 
-    const keyDownRef = React.useRef(false);
+    const keyElementRef = React.useRef<Element | null>(null);
     const isRTL = useIsRTL();
 
     React.useEffect(() => {
-      if (keyDownRef.current) {
-        const item = navigation.getItem(state.cursorId, {state});
-        if (state.isVirtualized) {
-          state.UNSTABLE_virtual.scrollToIndex(item.index);
+      if (keyElementRef.current) {
+        const item = model.navigation.getItem(model.state.cursorId, model);
+        if (model.state.isVirtualized) {
+          model.state.UNSTABLE_virtual.scrollToIndex(item.index);
         }
-        requestAnimationFrame(() => {
-          document
-            .querySelector<HTMLElement>(
-              `[data-focus-id="${`${state.id}-${getIdRef.current(item)}`}"]`
-            )
-            ?.focus();
-        });
 
-        keyDownRef.current = false;
+        const selector = (id?: string) => {
+          return document.querySelector<HTMLElement>(`[data-focus-id="${`${id}-${item.id}`}"]`);
+        };
+
+        // In React concurrent mode, there could be several render attempts before the element we're
+        // looking for could be available in the DOM
+        retryEachFrame(() => {
+          // Attempt to extract the ID from the DOM element. This fixes issues where the server and client
+          // do not agree on a generated ID
+          const clientId = keyElementRef.current?.getAttribute('data-focus-id')?.split('-')[0];
+          const element = selector(clientId) || selector(model.state.id);
+
+          element?.focus();
+          if (element) {
+            keyElementRef.current = null;
+          }
+          return !!element;
+        }, 5); // 5 should be enough, right?!
       }
       // 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]);
+    }, [model.state.cursorId]);
+
+    // Roving focus must always have a focus stop to function correctly
+    React.useEffect(() => {
+      if (!model.state.cursorId && model.state.items.length) {
+        model.events.goTo({id: model.state.items[0].id});
+      }
+    }, [model.state.cursorId, model.state.items, model.events]);
 
     return {
       onKeyDown(event: React.KeyboardEvent) {
-        // Test ctrl key first
-        if (event.ctrlKey) {
-          for (const key in ctrlKeyMap) {
-            if (hasOwnKey(ctrlKeyMap, key)) {
-              if (event.key === key) {
-                keyDownRef.current = true;
-                events[ctrlKeyMap[key]]?.();
-                event.preventDefault();
-                return;
-              }
-            }
-          }
+        const handled = keyboardEventToCursorEvents(event, model, isRTL);
+        if (handled) {
+          event.preventDefault();
+          keyElementRef.current = event.currentTarget;
         }
-        // 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']!});
+        model.events.goTo({id: elemProps['data-id']!});
       },
-      'data-focus-id': `${state.id}-${elemProps['data-id']}`,
-      tabIndex: !state.cursorId
+      'data-focus-id': `${model.state.id}-${elemProps['data-id']}`,
+      tabIndex: !model.state.cursorId
         ? 0 // cursor isn't known yet, be safe and mark this as focusable
-        : !!elemProps['data-id'] && state.cursorId === elemProps['data-id']
+        : !!elemProps['data-id'] && model.state.cursorId === elemProps['data-id']
         ? 0 // A name is known and cursor is here
         : -1, // A name is known an cursor is somewhere else
-      ref,
     };
   }
 );

package/collection/lib/useListItemSelect.tsx

@@ -4,17 +4,28 @@ 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} = {}) => {
+  ({state, events}, _, 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')
+        !state.nonInteractiveIds.includes(name) &&
+        event.currentTarget.getAttribute('aria-disabled') !== 'true'
       ) {
-        return;
+        events.select({id: name});
       }
-      events.select({id: name});
     };
 
     return {onClick};

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

@@ -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,