chore!: Collection navigation getItem can return undefined (#2982)

Allow the `ListModel` `navigation.getItem()` to return `undefined`.

[category:Components]

### BREAKING CHANGES
A list model's `navigation.getItem()` can return `undefined` if no item is found. Previously it threw an error, which cause many problems. It is now up to the caller to decide what to do with an `undefined` return value

modules/docs/mdx/12.0-UPGRADE-GUIDE.mdx

@@ -53,6 +53,7 @@ A note to the reader:
   - [Select](#select)
   - [Text Area](#text-area)
   - [Text Input](#text-input)
+  - [Collections](#collections)
 - [Utility Updates](#utility-updates)
 - [Troubleshooting](#troubleshooting)
 - [Glossary](#glossary)
@@ -584,6 +585,15 @@ const theme: PartialEmotionCanvasTheme = {
 </CanvasProvider>;
 ```
 
+### Collections
+
+**PR:** [#2982](https://github.com/Workday/canvas-kit/pull/2982)
+
+The `navigation.getItem()` function can now return `undefined` instead of throwing an error when an
+item is not found. Throwing an error caused lots of problems when it came to dynamic data. This is a
+breaking change if your application uses `getItem`. It will now have to deal with the possibility of
+an `undefined`.
+
 ## Utility Updates
 
 **PR:** [#2908](https://github.com/Workday/canvas-kit/pull/2908)

modules/react/collection/lib/useCursorListModel.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import {assert, createModelHook, Generic} from '@workday/canvas-kit-react/common';
+import {createModelHook, Generic} from '@workday/canvas-kit-react/common';
 
 import {useBaseListModel, Item} from './useBaseListModel';
 
@@ -18,7 +18,7 @@ export interface NavigationManager {
    * and `Ctrl+End` for Grids. */
   getLast: NavigationRequestor;
   /** Get an item with the provided `id`. */
-  getItem: (id: string, model: NavigationInput) => Item<Generic>;
+  getItem: (id: string, model: NavigationInput) => Item<Generic> | undefined;
   /** Get the next item after the provided `id`. This will be called when the `Right` arrow key is
    * pressed for RTL languages and when the `Left` arrow is pressed for LTR languages. */
   getNext: NavigationRequestor;
@@ -129,10 +129,11 @@ export const getNextPage: NavigationRequestor = (index, {state}) => {
   return getLast(index, {state});
 };
 
-const getItem: (id: string, model: NavigationInput) => Item<Generic> = (id, {state}) => {
-  const item = state.items.find(item => item.id === id) || state.items[0]; // no id, return first item
-  assert(item, `Item not found: ${id}`);
-  return item;
+const getItem: (id: string, model: NavigationInput) => Item<Generic> | undefined = (
+  id,
+  {state}
+) => {
+  return state.items.find(item => item.id === id);
 };
 
 export const getWrappingOffsetItem =

modules/react/collection/lib/useListItemRovingFocus.tsx

@@ -39,28 +39,30 @@ export const useListItemRovingFocus = createElemPropsHook(useCursorListModel)(
     React.useEffect(() => {
       if (keyElementRef.current) {
         const item = model.navigation.getItem(model.state.cursorId, model);
-        if (model.state.isVirtualized) {
-          model.state.UNSTABLE_virtual.scrollToIndex(item.index);
-        }
+        if (item) {
+          if (model.state.isVirtualized) {
+            model.state.UNSTABLE_virtual.scrollToIndex(item.index);
+          }
 
-        const selector = (id?: string) => {
-          return document.querySelector<HTMLElement>(`[data-focus-id="${`${id}-${item.id}`}"]`);
-        };
+          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);
+          // 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?!
+            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

modules/react/combobox/lib/hooks/useComboboxKeyboardTypeAhead.ts

@@ -58,7 +58,9 @@ export const useComboboxKeyboardTypeAhead = createElemPropsHook(useComboboxModel
   };
 
   const currentItemIndex =
-    model.state.items.length > 0 ? model.navigation.getItem(model.state.cursorId, model).index : 0;
+    model.state.items.length > 0
+      ? model.navigation.getItem(model.state.cursorId, model)?.index || 0
+      : 0;
 
   const handleKeyboardTypeAhead = (key: string, numOptions: number) => {
     // If the starting point is beyond the list of options, reset it

modules/react/select/lib/hooks/useSelectInput.ts

@@ -89,7 +89,7 @@ export const useSelectInput = composeHooks(
           model.state.items.length > 0 &&
           model.state.selectedIds[0]
         ) {
-          const value = model.navigation.getItem(model.state.selectedIds[0], model).id;
+          const value = model.state.selectedIds[0];
           const oldValue = model.state.inputRef.current.value;
 
           // force the hidden input to have the correct value
@@ -184,7 +184,7 @@ export const useSelectInput = composeHooks(
           onChange: noop,
           value:
             model.state.selectedIds.length > 0 && model.state.items.length > 0
-              ? model.navigation.getItem(model.state.selectedIds[0], model).textValue
+              ? model.navigation.getItem(model.state.selectedIds[0], model)?.textValue || ''
               : '',
         },
         'aria-haspopup': 'menu',

modules/react/select/stories/examples/WithIcons.tsx

@@ -40,7 +40,7 @@ export const WithIcons = () => {
             <FormField.Input
               as={Select.Input}
               cs={styleOverrides.formfieldInputStyles}
-              inputStartIcon={selectedItem.value.icon}
+              inputStartIcon={selectedItem?.value.icon}
             />
             <Select.Popper>
               <Select.Card cs={styleOverrides.selectCardStyles}>