@arbor-education/design-system.components 0.6.0 → 0.7.0

package/src/components/combobox/useComboboxChipKeyboard.test.tsx

@@ -0,0 +1,141 @@
+import { renderHook } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+import { useComboboxChipKeyboard } from './useComboboxChipKeyboard';
+
+const keyEvent = (
+  key: string,
+  init: Partial<React.KeyboardEvent<HTMLInputElement>> = {},
+): React.KeyboardEvent<HTMLInputElement> =>
+  ({
+    key,
+    preventDefault: vi.fn(),
+    ...init,
+  }) as unknown as React.KeyboardEvent<HTMLInputElement>;
+
+const inputRef = (
+  current: HTMLInputElement | null = null,
+): React.RefObject<HTMLInputElement | null> => ({ current });
+
+describe('useComboboxChipKeyboard', () => {
+  test('returns false for ArrowDown so listbox can handle', () => {
+    const ref = inputRef();
+    const { result } = renderHook(() =>
+      useComboboxChipKeyboard({
+        inputRef: ref,
+        clearAll: vi.fn(),
+        clearChipSelection: vi.fn(),
+        exitChipNav: vi.fn(),
+        focusedChipIndex: null,
+        removeValue: vi.fn(),
+        selectedChipValues: [],
+        selectedValues: [],
+        setFocusedChipIndex: vi.fn(),
+      }),
+    );
+    expect(result.current(keyEvent('ArrowDown'))).toBe(false);
+  });
+
+  test('ArrowLeft in chip nav decrements focus', () => {
+    const setFocusedChipIndex = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxChipKeyboard({
+        inputRef: inputRef(),
+        clearAll: vi.fn(),
+        clearChipSelection: vi.fn(),
+        exitChipNav: vi.fn(),
+        focusedChipIndex: 2,
+        removeValue: vi.fn(),
+        selectedChipValues: [],
+        selectedValues: ['a', 'b', 'c'],
+        setFocusedChipIndex,
+      }),
+    );
+    expect(result.current(keyEvent('ArrowLeft'))).toBe(true);
+    expect(setFocusedChipIndex).toHaveBeenCalled();
+  });
+
+  test('ArrowLeft at caret 0 enters chip nav from last chip', () => {
+    const input = document.createElement('input');
+    const ref = inputRef(input);
+    input.setSelectionRange(0, 0);
+    const setFocusedChipIndex = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxChipKeyboard({
+        inputRef: ref,
+        clearAll: vi.fn(),
+        clearChipSelection: vi.fn(),
+        exitChipNav: vi.fn(),
+        focusedChipIndex: null,
+        removeValue: vi.fn(),
+        selectedChipValues: [],
+        selectedValues: ['x'],
+        setFocusedChipIndex,
+      }),
+    );
+    expect(result.current(keyEvent('ArrowLeft'))).toBe(true);
+    expect(setFocusedChipIndex).toHaveBeenCalledWith(0);
+  });
+
+  test('Escape in chip nav exits', () => {
+    const exitChipNav = vi.fn();
+    const e = keyEvent('Escape');
+    const { result } = renderHook(() =>
+      useComboboxChipKeyboard({
+        inputRef: inputRef(),
+        clearAll: vi.fn(),
+        clearChipSelection: vi.fn(),
+        exitChipNav,
+        focusedChipIndex: 0,
+        removeValue: vi.fn(),
+        selectedChipValues: [],
+        selectedValues: ['a'],
+        setFocusedChipIndex: vi.fn(),
+      }),
+    );
+    expect(result.current(e)).toBe(true);
+    expect(exitChipNav).toHaveBeenCalled();
+    expect(e.preventDefault).toHaveBeenCalled();
+  });
+
+  test('Backspace with bulk chip selection clears', () => {
+    const clearAll = vi.fn();
+    const clearChipSelection = vi.fn();
+    const e = keyEvent('Backspace');
+    const { result } = renderHook(() =>
+      useComboboxChipKeyboard({
+        inputRef: inputRef(),
+        clearAll,
+        clearChipSelection,
+        exitChipNav: vi.fn(),
+        focusedChipIndex: null,
+        removeValue: vi.fn(),
+        selectedChipValues: ['a'],
+        selectedValues: ['a'],
+        setFocusedChipIndex: vi.fn(),
+      }),
+    );
+    expect(result.current(e)).toBe(true);
+    expect(clearAll).toHaveBeenCalled();
+    expect(clearChipSelection).toHaveBeenCalled();
+  });
+
+  test('Backspace in chip nav removes value', () => {
+    const removeValue = vi.fn();
+    const e = keyEvent('Backspace');
+    const { result } = renderHook(() =>
+      useComboboxChipKeyboard({
+        inputRef: inputRef(),
+        clearAll: vi.fn(),
+        clearChipSelection: vi.fn(),
+        exitChipNav: vi.fn(),
+        focusedChipIndex: 0,
+        removeValue,
+        selectedChipValues: [],
+        selectedValues: ['only'],
+        setFocusedChipIndex: vi.fn(),
+      }),
+    );
+    expect(result.current(e)).toBe(true);
+    expect(removeValue).toHaveBeenCalledWith('only');
+  });
+});

package/src/components/combobox/useComboboxChipKeyboard.ts

@@ -0,0 +1,121 @@
+import { useCallback } from 'react';
+import type { UseComboboxChipKeyboardParams } from './comboboxKeyboardTypes';
+
+export const useComboboxChipKeyboard = ({
+  inputRef,
+  clearAll,
+  clearChipSelection,
+  exitChipNav,
+  focusedChipIndex,
+  removeValue,
+  selectedChipValues,
+  selectedValues,
+  setFocusedChipIndex,
+}: UseComboboxChipKeyboardParams) =>
+  useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>): boolean => {
+      const inChipNav = focusedChipIndex !== null;
+
+      switch (e.key) {
+        case 'ArrowLeft': {
+          if (inChipNav) {
+            e.preventDefault();
+            setFocusedChipIndex(prev => (prev !== null && prev > 0 ? prev - 1 : prev));
+            return true;
+          }
+          if (
+            selectedValues.length > 0
+            && inputRef.current?.selectionStart === 0
+            && inputRef.current?.selectionEnd === 0
+          ) {
+            e.preventDefault();
+            setFocusedChipIndex(selectedValues.length - 1);
+            return true;
+          }
+          return false;
+        }
+        case 'ArrowRight': {
+          if (inChipNav) {
+            e.preventDefault();
+            if (focusedChipIndex !== null && focusedChipIndex < selectedValues.length - 1) {
+              setFocusedChipIndex(focusedChipIndex + 1);
+            }
+            else {
+              exitChipNav();
+            }
+            return true;
+          }
+          return false;
+        }
+        case 'Backspace': {
+          if (selectedChipValues.length > 0) {
+            e.preventDefault();
+            clearAll();
+            clearChipSelection();
+            return true;
+          }
+          if (inChipNav && focusedChipIndex !== null) {
+            e.preventDefault();
+            const valueToRemove = selectedValues[focusedChipIndex];
+            if (valueToRemove) {
+              removeValue(valueToRemove);
+              if (focusedChipIndex > 0) {
+                setFocusedChipIndex(focusedChipIndex - 1);
+              }
+              else if (selectedValues.length <= 1) {
+                exitChipNav();
+              }
+            }
+            return true;
+          }
+          return false;
+        }
+        case 'Delete': {
+          if (selectedChipValues.length > 0) {
+            e.preventDefault();
+            clearAll();
+            clearChipSelection();
+            return true;
+          }
+          if (inChipNav && focusedChipIndex !== null) {
+            e.preventDefault();
+            const valueToRemove = selectedValues[focusedChipIndex];
+            if (valueToRemove) {
+              removeValue(valueToRemove);
+              if (focusedChipIndex >= selectedValues.length - 1) {
+                if (selectedValues.length <= 1) {
+                  exitChipNav();
+                }
+                else {
+                  setFocusedChipIndex(focusedChipIndex - 1);
+                }
+              }
+            }
+            return true;
+          }
+          return false;
+        }
+        case 'Escape': {
+          if (inChipNav) {
+            e.preventDefault();
+            exitChipNav();
+            return true;
+          }
+          return false;
+        }
+        default:
+          return false;
+      }
+    },
+    [
+      clearAll,
+      clearChipSelection,
+      exitChipNav,
+      focusedChipIndex,
+      inputRef,
+      removeValue,
+      selectedChipValues.length,
+      selectedValues,
+      setFocusedChipIndex,
+    ],
+  );

package/src/components/combobox/useComboboxKeyboard.ts

@@ -0,0 +1,108 @@
+import { useCallback } from 'react';
+import { isSelectAllChord } from 'Utils/isSelectAllChord';
+import type { UseComboboxKeyboardParams } from './comboboxKeyboardTypes';
+import { useComboboxChipKeyboard } from './useComboboxChipKeyboard';
+import { useComboboxListboxKeyboard } from './useComboboxListboxKeyboard';
+
+export type { UseComboboxKeyboardParams } from './comboboxKeyboardTypes';
+
+export const useComboboxKeyboard = ({
+  inputRef,
+  allowCreate,
+  clearAll,
+  clearChipSelection,
+  exitChipNav,
+  focusDeleteButtonForHighlighted,
+  listboxOptions,
+  focusedChipIndex,
+  handleCreate,
+  highlightIndex,
+  isOpen,
+  mergedOptions,
+  openPopover,
+  query,
+  removeValue,
+  scrollHighlightedIntoView,
+  selectOption,
+  selectedChipValues,
+  selectedValues,
+  setFocusedChipIndex,
+  setHighlightIndex,
+  setIsOpen,
+  setQuery,
+  setSelectedChipValues,
+  showCreateRow,
+  showListboxLoading,
+  totalItems,
+}: UseComboboxKeyboardParams) => {
+  const handleChipKeyDown = useComboboxChipKeyboard({
+    inputRef,
+    clearAll,
+    clearChipSelection,
+    exitChipNav,
+    focusedChipIndex,
+    removeValue,
+    selectedChipValues,
+    selectedValues,
+    setFocusedChipIndex,
+  });
+
+  const handleListboxKeyDown = useComboboxListboxKeyboard({
+    allowCreate,
+    clearChipSelection,
+    exitChipNav,
+    focusDeleteButtonForHighlighted,
+    listboxOptions,
+    focusedChipIndex,
+    handleCreate,
+    highlightIndex,
+    isOpen,
+    mergedOptions,
+    openPopover,
+    query,
+    removeValue,
+    scrollHighlightedIntoView,
+    selectOption,
+    selectedChipValues,
+    selectedValues,
+    setHighlightIndex,
+    setIsOpen,
+    setQuery,
+    showCreateRow,
+    showListboxLoading,
+    totalItems,
+  });
+
+  return useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      const inChipNav = focusedChipIndex !== null;
+
+      if (isSelectAllChord(e.nativeEvent) && selectedValues.length > 0) {
+        setSelectedChipValues(selectedValues);
+        setFocusedChipIndex(null);
+        return;
+      }
+
+      if (inChipNav && e.key.length === 1 && !e.metaKey && !e.ctrlKey && !e.altKey) {
+        exitChipNav();
+        return;
+      }
+
+      if (handleChipKeyDown(e)) {
+        return;
+      }
+
+      handleListboxKeyDown(e);
+    },
+    [
+      exitChipNav,
+      focusDeleteButtonForHighlighted,
+      focusedChipIndex,
+      handleChipKeyDown,
+      handleListboxKeyDown,
+      selectedValues,
+      setFocusedChipIndex,
+      setSelectedChipValues,
+    ],
+  );
+};

package/src/components/combobox/useComboboxListboxDom.ts

@@ -0,0 +1,36 @@
+import { useCallback, useRef } from 'react';
+import { scrollElementIntoViewById } from 'Utils/scrollElementIntoViewById';
+
+type UseComboboxListboxDomParams = {
+  comboboxId: string;
+};
+
+export type UseComboboxListboxDomReturn = {
+  listboxRef: React.RefObject<HTMLUListElement | null>;
+  getOptionId: (index: number) => string;
+  scrollHighlightedIntoView: (index: number) => void;
+};
+
+export const useComboboxListboxDom = ({
+  comboboxId,
+}: UseComboboxListboxDomParams): UseComboboxListboxDomReturn => {
+  const listboxRef = useRef<HTMLUListElement>(null);
+
+  const getOptionId = useCallback(
+    (index: number): string => `${comboboxId}-option-${index}`,
+    [comboboxId],
+  );
+
+  const scrollHighlightedIntoView = useCallback(
+    (index: number) => {
+      scrollElementIntoViewById(listboxRef.current, getOptionId(index));
+    },
+    [getOptionId],
+  );
+
+  return {
+    listboxRef,
+    getOptionId,
+    scrollHighlightedIntoView,
+  };
+};

package/src/components/combobox/useComboboxListboxKeyboard.test.tsx

@@ -0,0 +1,186 @@
+import { renderHook } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+import type { ComboboxOption } from './types';
+import { useComboboxListboxKeyboard } from './useComboboxListboxKeyboard';
+
+const keyEvent = (
+  key: string,
+  init: Partial<React.KeyboardEvent<HTMLInputElement>> = {},
+): React.KeyboardEvent<HTMLInputElement> =>
+  ({
+    key,
+    preventDefault: vi.fn(),
+    altKey: false,
+    ...init,
+  }) as unknown as React.KeyboardEvent<HTMLInputElement>;
+
+const options: ComboboxOption[] = [
+  { value: '1', label: 'One' },
+  { value: '2', label: 'Two' },
+];
+
+const baseListboxParams = {
+  allowCreate: false,
+  clearChipSelection: vi.fn(),
+  exitChipNav: vi.fn(),
+  listboxOptions: options,
+  focusedChipIndex: null as number | null,
+  handleCreate: vi.fn(),
+  highlightIndex: 0,
+  isOpen: true,
+  mergedOptions: options,
+  openPopover: vi.fn(),
+  query: '',
+  removeValue: vi.fn(),
+  scrollHighlightedIntoView: vi.fn(),
+  selectOption: vi.fn(),
+  selectedChipValues: [] as string[],
+  selectedValues: [] as string[],
+  setHighlightIndex: vi.fn(),
+  setIsOpen: vi.fn(),
+  setQuery: vi.fn(),
+  showCreateRow: false,
+  showListboxLoading: false,
+  totalItems: 2,
+};
+
+describe('useComboboxListboxKeyboard', () => {
+  test('ArrowDown when closed opens and highlights first', () => {
+    const openPopover = vi.fn();
+    const setHighlightIndex = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxListboxKeyboard({
+        ...baseListboxParams,
+        isOpen: false,
+        openPopover,
+        setHighlightIndex,
+      }),
+    );
+    result.current(keyEvent('ArrowDown'));
+    expect(openPopover).toHaveBeenCalled();
+    expect(setHighlightIndex).toHaveBeenCalledWith(0);
+  });
+
+  test('ArrowDown when loading does nothing beyond preventDefault', () => {
+    const openPopover = vi.fn();
+    const setHighlightIndex = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxListboxKeyboard({
+        ...baseListboxParams,
+        showListboxLoading: true,
+        openPopover,
+        setHighlightIndex,
+      }),
+    );
+    result.current(keyEvent('ArrowDown'));
+    expect(openPopover).not.toHaveBeenCalled();
+    expect(setHighlightIndex).not.toHaveBeenCalled();
+  });
+
+  test('Alt+ArrowDown opens without changing highlight when already open', () => {
+    const openPopover = vi.fn();
+    const setHighlightIndex = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxListboxKeyboard({
+        ...baseListboxParams,
+        isOpen: true,
+        highlightIndex: 1,
+        openPopover,
+        setHighlightIndex,
+      }),
+    );
+    result.current(keyEvent('ArrowDown', { altKey: true }));
+    expect(openPopover).toHaveBeenCalled();
+    expect(setHighlightIndex).not.toHaveBeenCalled();
+  });
+
+  test('ArrowDown advances highlight with wrap', () => {
+    const setHighlightIndex = vi.fn();
+    const scrollHighlightedIntoView = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxListboxKeyboard({
+        ...baseListboxParams,
+        highlightIndex: 1,
+        setHighlightIndex,
+        scrollHighlightedIntoView,
+      }),
+    );
+    result.current(keyEvent('ArrowDown'));
+    expect(setHighlightIndex).toHaveBeenCalledWith(0);
+    expect(scrollHighlightedIntoView).toHaveBeenCalledWith(0);
+  });
+
+  test('ArrowUp when closed is no-op after preventDefault', () => {
+    const setHighlightIndex = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxListboxKeyboard({
+        ...baseListboxParams,
+        isOpen: false,
+        setHighlightIndex,
+      }),
+    );
+    result.current(keyEvent('ArrowUp'));
+    expect(setHighlightIndex).not.toHaveBeenCalled();
+  });
+
+  test('Enter selects highlighted option', () => {
+    const selectOption = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxListboxKeyboard({
+        ...baseListboxParams,
+        highlightIndex: 0,
+        selectOption,
+      }),
+    );
+    result.current(keyEvent('Enter'));
+    expect(selectOption).toHaveBeenCalledWith('1');
+  });
+
+  test('Escape clears chip selection when chips are multi-selected', () => {
+    const clearChipSelection = vi.fn();
+    const setIsOpen = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxListboxKeyboard({
+        ...baseListboxParams,
+        selectedChipValues: ['a', 'b'],
+        clearChipSelection,
+        setIsOpen,
+      }),
+    );
+    const e = keyEvent('Escape');
+    result.current(e);
+    expect(clearChipSelection).toHaveBeenCalled();
+    expect(setIsOpen).not.toHaveBeenCalled();
+    expect(e.preventDefault).toHaveBeenCalled();
+  });
+
+  test('Escape closes popover when open and no chip selection', () => {
+    const setIsOpen = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxListboxKeyboard({
+        ...baseListboxParams,
+        isOpen: true,
+        selectedChipValues: [],
+        setIsOpen,
+      }),
+    );
+    const e = keyEvent('Escape');
+    result.current(e);
+    expect(setIsOpen).toHaveBeenCalledWith(false);
+    expect(e.preventDefault).toHaveBeenCalled();
+  });
+
+  test('Backspace with empty query removes last selected value', () => {
+    const removeValue = vi.fn();
+    const { result } = renderHook(() =>
+      useComboboxListboxKeyboard({
+        ...baseListboxParams,
+        query: '',
+        selectedValues: ['a', 'b'],
+        removeValue,
+      }),
+    );
+    result.current(keyEvent('Backspace'));
+    expect(removeValue).toHaveBeenCalledWith('b');
+  });
+});