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

package/src/components/combobox/useComboboxListboxKeyboard.ts

@@ -0,0 +1,172 @@
+import { useCallback } from 'react';
+import { nextCircularIndex } from 'Utils/nextCircularIndex';
+import type { UseComboboxListboxKeyboardParams } from './comboboxKeyboardTypes';
+import { normaliseComboboxQuery } from './normaliseComboboxQuery';
+
+export const useComboboxListboxKeyboard = ({
+  allowCreate,
+  clearChipSelection,
+  exitChipNav,
+  focusDeleteButtonForHighlighted = () => false,
+  listboxOptions,
+  focusedChipIndex,
+  handleCreate,
+  highlightIndex,
+  isOpen,
+  mergedOptions,
+  openPopover,
+  query,
+  removeValue,
+  scrollHighlightedIntoView,
+  selectOption,
+  selectedChipValues,
+  selectedValues,
+  setHighlightIndex,
+  setIsOpen,
+  setQuery,
+  showCreateRow,
+  showListboxLoading,
+  totalItems,
+}: UseComboboxListboxKeyboardParams) =>
+  useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      const inChipNav = focusedChipIndex !== null;
+
+      switch (e.key) {
+        case 'ArrowDown': {
+          e.preventDefault();
+          if (inChipNav) {
+            exitChipNav();
+            return;
+          }
+          if (showListboxLoading) {
+            return;
+          }
+          if (e.altKey) {
+            openPopover();
+            return;
+          }
+          if (!isOpen) {
+            openPopover();
+            setHighlightIndex(0);
+            return;
+          }
+          const next = nextCircularIndex(highlightIndex, totalItems, 'next');
+          setHighlightIndex(next);
+          scrollHighlightedIntoView(next);
+          break;
+        }
+        case 'ArrowUp': {
+          e.preventDefault();
+          if (inChipNav) {
+            exitChipNav();
+            return;
+          }
+          if (!isOpen) return;
+          if (showListboxLoading) {
+            return;
+          }
+          const prev = nextCircularIndex(highlightIndex, totalItems, 'previous');
+          setHighlightIndex(prev);
+          scrollHighlightedIntoView(prev);
+          break;
+        }
+        case 'ArrowRight': {
+          if (inChipNav || !isOpen || showListboxLoading) return;
+          if (focusDeleteButtonForHighlighted()) {
+            e.preventDefault();
+          }
+          break;
+        }
+        case 'Tab': {
+          if (e.shiftKey || inChipNav || !isOpen || showListboxLoading) return;
+          if (focusDeleteButtonForHighlighted()) {
+            e.preventDefault();
+          }
+          break;
+        }
+        case 'Enter': {
+          e.preventDefault();
+          if (inChipNav) {
+            exitChipNav();
+            return;
+          }
+          if (!isOpen) {
+            openPopover();
+            return;
+          }
+          if (showListboxLoading) {
+            return;
+          }
+          if (highlightIndex >= 0 && highlightIndex < listboxOptions.length) {
+            const opt = listboxOptions[highlightIndex];
+            if (opt && !opt.disabled) selectOption(opt.value);
+          }
+          else if (showCreateRow && highlightIndex === listboxOptions.length) {
+            handleCreate();
+          }
+          else if (allowCreate && query.trim().length > 0) {
+            const exactMatch = mergedOptions.find(
+              opt =>
+                normaliseComboboxQuery(opt.label) === normaliseComboboxQuery(query),
+            );
+            if (exactMatch && !exactMatch.disabled) {
+              selectOption(exactMatch.value);
+            }
+            else if (showCreateRow) {
+              handleCreate();
+            }
+          }
+          break;
+        }
+        case 'Escape': {
+          if (selectedChipValues.length > 0) {
+            e.preventDefault();
+            clearChipSelection();
+            return;
+          }
+          if (isOpen) {
+            e.preventDefault();
+            setIsOpen(false);
+          }
+          else if (query) {
+            setQuery('');
+          }
+          break;
+        }
+        case 'Backspace': {
+          if (!query && selectedValues.length > 0) {
+            removeValue(selectedValues[selectedValues.length - 1]!);
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    },
+    [
+      allowCreate,
+      clearChipSelection,
+      exitChipNav,
+      focusDeleteButtonForHighlighted,
+      listboxOptions,
+      focusedChipIndex,
+      handleCreate,
+      highlightIndex,
+      isOpen,
+      mergedOptions,
+      openPopover,
+      query,
+      removeValue,
+      scrollHighlightedIntoView,
+      selectOption,
+      selectedChipValues.length,
+      selectedValues,
+      setHighlightIndex,
+      setIsOpen,
+      setQuery,
+      showCreateRow,
+      showListboxLoading,
+      totalItems,
+    ],
+  );

package/src/components/combobox/useComboboxPopoverBehavior.ts

@@ -0,0 +1,179 @@
+import type { DismissableLayerProps } from '@radix-ui/react-dismissable-layer';
+import { useCallback, useEffect } from 'react';
+
+type ComboboxInteractOutsideEvent = Parameters<
+  NonNullable<DismissableLayerProps['onInteractOutside']>
+>[0];
+
+type UseComboboxPopoverBehaviorParams = {
+  inputRef: React.RefObject<HTMLInputElement | null>;
+  triggerRef: React.RefObject<HTMLDivElement | null>;
+  listboxRef: React.RefObject<HTMLUListElement | null>;
+  disabled: boolean;
+  dropdownOnFocus: boolean;
+  loading: boolean;
+  onSearch?: (query: string) => void;
+  isAsync: boolean;
+  isOpen: boolean;
+  setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
+  setQuery: React.Dispatch<React.SetStateAction<string>>;
+  setHighlightIndex: React.Dispatch<React.SetStateAction<number>>;
+  openPopover: () => void;
+  totalItems: number;
+  showCreateRow: boolean;
+  filteredOptionsLength: number;
+  highlightIndex: number;
+  clearChipSelection: () => void;
+  exitChipNav: () => void;
+  triggerContainsInput?: boolean;
+};
+
+export type UseComboboxPopoverBehaviorReturn = {
+  shouldRenderPopoverContent: boolean;
+  shouldShowPopover: boolean;
+  showListboxLoading: boolean;
+  handleInputChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  handleTriggerClick: () => void;
+  handleInputFocus: () => void;
+  handleInputBlur: (e: React.FocusEvent<HTMLInputElement>) => void;
+  handleChevronClick: (e: React.MouseEvent) => void;
+  handlePopoverInteractOutside: (e: ComboboxInteractOutsideEvent) => void;
+};
+
+export const useComboboxPopoverBehavior = ({
+  inputRef,
+  triggerRef,
+  listboxRef,
+  disabled,
+  dropdownOnFocus,
+  loading,
+  onSearch,
+  isAsync,
+  isOpen,
+  setIsOpen,
+  setQuery,
+  setHighlightIndex,
+  openPopover,
+  totalItems,
+  showCreateRow,
+  filteredOptionsLength,
+  highlightIndex,
+  clearChipSelection,
+  exitChipNav,
+  triggerContainsInput = true,
+}: UseComboboxPopoverBehaviorParams): UseComboboxPopoverBehaviorReturn => {
+  const shouldRenderPopoverContent = loading || totalItems > 0;
+  const shouldShowPopover = isOpen && shouldRenderPopoverContent;
+  const showListboxLoading = Boolean(loading && shouldShowPopover);
+
+  const handleInputChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const val = e.target.value;
+      clearChipSelection();
+      exitChipNav();
+      setQuery(val);
+      setHighlightIndex(-1);
+      if (!dropdownOnFocus && val.trim() === '') {
+        setIsOpen(false);
+      }
+      else if (!isOpen) {
+        openPopover();
+      }
+      if (isAsync) onSearch?.(val);
+    },
+    [
+      clearChipSelection,
+      dropdownOnFocus,
+      exitChipNav,
+      isOpen,
+      isAsync,
+      onSearch,
+      openPopover,
+      setHighlightIndex,
+      setIsOpen,
+      setQuery,
+    ],
+  );
+
+  useEffect(() => {
+    if (loading) return;
+    if (isOpen && showCreateRow && highlightIndex === -1) {
+      setHighlightIndex(filteredOptionsLength);
+    }
+  }, [loading, isOpen, showCreateRow, highlightIndex, filteredOptionsLength, setHighlightIndex]);
+
+  useEffect(() => {
+    if (showListboxLoading) {
+      setHighlightIndex(-1);
+    }
+  }, [showListboxLoading, setHighlightIndex]);
+
+  const requestOpen = useCallback(() => {
+    if (disabled) return;
+    if (shouldRenderPopoverContent) {
+      openPopover();
+    }
+  }, [disabled, openPopover, shouldRenderPopoverContent]);
+
+  const handleTriggerClick = useCallback(() => {
+    if (disabled) return;
+    if (triggerContainsInput) {
+      inputRef.current?.focus();
+    }
+    if (dropdownOnFocus) {
+      requestOpen();
+    }
+  }, [disabled, dropdownOnFocus, inputRef, requestOpen, triggerContainsInput]);
+
+  const handleInputFocus = useCallback(() => {
+    if (!dropdownOnFocus || disabled) return;
+    requestOpen();
+  }, [disabled, dropdownOnFocus, requestOpen]);
+
+  const handleInputBlur = useCallback(
+    (e: React.FocusEvent<HTMLInputElement>) => {
+      const relatedTarget = e.relatedTarget as Node | null;
+      if (relatedTarget && triggerRef.current?.contains(relatedTarget)) return;
+      if (relatedTarget && listboxRef.current?.contains(relatedTarget)) return;
+      clearChipSelection();
+      exitChipNav();
+    },
+    [clearChipSelection, exitChipNav, listboxRef, triggerRef],
+  );
+
+  const handleChevronClick = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation();
+      if (disabled) return;
+      if (triggerContainsInput) {
+        inputRef.current?.focus();
+      }
+      if (shouldRenderPopoverContent) {
+        openPopover();
+      }
+    },
+    [disabled, inputRef, openPopover, shouldRenderPopoverContent, triggerContainsInput],
+  );
+
+  const handlePopoverInteractOutside = useCallback(
+    (e: ComboboxInteractOutsideEvent) => {
+      const target = e.target as Node | null;
+      if (target && triggerRef.current?.contains(target)) {
+        e.preventDefault();
+      }
+    },
+    [triggerRef],
+  );
+
+  return {
+    shouldRenderPopoverContent,
+    shouldShowPopover,
+    showListboxLoading,
+    handleInputChange,
+    handleTriggerClick,
+    handleInputFocus,
+    handleInputBlur,
+    handleChevronClick,
+    handlePopoverInteractOutside,
+  };
+};

package/src/components/combobox/useComboboxState.ts

@@ -0,0 +1,232 @@
+import { useCallback, useMemo, useState } from 'react';
+import { normaliseComboboxQuery } from './normaliseComboboxQuery';
+import type { ComboboxCreateResult, ComboboxOption, ComboboxProps } from './types';
+
+const builtInFilters = {
+  prefix: (option: ComboboxOption, query: string) =>
+    normaliseComboboxQuery(option.label).startsWith(normaliseComboboxQuery(query)),
+  substring: (option: ComboboxOption, query: string) =>
+    normaliseComboboxQuery(option.label).includes(normaliseComboboxQuery(query)),
+} as const;
+
+type UseComboboxStateParams = Pick<
+  ComboboxProps,
+  | 'options'
+  | 'multiple'
+  | 'value'
+  | 'defaultValue'
+  | 'onValueChange'
+  | 'onSearch'
+  | 'searchType'
+  | 'allowCreate'
+  | 'onCreateNew'
+  | 'onDeleteCreated'
+  | 'disabled'
+>;
+
+export type UseComboboxStateReturn = {
+  selectedValues: string[];
+  query: string;
+  setQuery: React.Dispatch<React.SetStateAction<string>>;
+  isOpen: boolean;
+  setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
+  highlightIndex: number;
+  setHighlightIndex: React.Dispatch<React.SetStateAction<number>>;
+
+  selectedValuesSet: Set<string>;
+  mergedOptions: ComboboxOption[];
+  filteredOptions: ComboboxOption[];
+  createdValuesSet: Set<string>;
+  showCreateRow: boolean;
+  totalItems: number;
+
+  selectOption: (optionValue: string) => void;
+  removeValue: (optionValue: string) => void;
+  clearAll: () => void;
+  handleCreate: () => void;
+  deleteCreatedOption: (optionValue: string) => void;
+  openPopover: () => void;
+
+  isAsync: boolean;
+};
+
+export const useComboboxState = (params: UseComboboxStateParams): UseComboboxStateReturn => {
+  const {
+    options,
+    multiple = false,
+    value: controlledValue,
+    defaultValue,
+    onValueChange,
+    onSearch,
+    searchType = 'prefix',
+    allowCreate = false,
+    onCreateNew,
+    onDeleteCreated,
+    disabled = false,
+  } = params;
+
+  const isControlled = controlledValue !== undefined;
+  const [internalValue, setInternalValue] = useState<string[]>(defaultValue ?? []);
+  const selectedValues = isControlled ? controlledValue : internalValue;
+
+  const selectedValuesSet = useMemo(() => new Set(selectedValues), [selectedValues]);
+
+  const updateValue = useCallback(
+    (next: string[]) => {
+      if (!isControlled) setInternalValue(next);
+      onValueChange?.(next);
+    },
+    [isControlled, onValueChange],
+  );
+
+  const [query, setQuery] = useState('');
+  const [isOpen, setIsOpen] = useState(false);
+  const [highlightIndex, setHighlightIndex] = useState(-1);
+  const [createdOptions, setCreatedOptions] = useState<ComboboxOption[]>([]);
+
+  const isAsync = Boolean(onSearch);
+  const filter = useMemo(
+    () => typeof searchType === 'function' ? searchType : builtInFilters[searchType],
+    [searchType],
+  );
+
+  const mergedOptions = useMemo(() => {
+    if (createdOptions.length === 0) return options;
+    const existingValues = new Set(options.map(opt => opt.value));
+    const extras = createdOptions.filter(opt => !existingValues.has(opt.value));
+    return [...options, ...extras];
+  }, [options, createdOptions]);
+
+  const filteredOptions = useMemo(() => {
+    if (isAsync || !query) return mergedOptions;
+    return mergedOptions.filter(opt => filter(opt, query));
+  }, [mergedOptions, query, isAsync, filter]);
+
+  const createdValuesSet = useMemo(
+    () => new Set(createdOptions.map(opt => opt.value)),
+    [createdOptions],
+  );
+
+  const showCreateRow = useMemo(
+    () =>
+      allowCreate
+      && query.trim().length > 0
+      && !filteredOptions.some(
+        o =>
+          normaliseComboboxQuery(o.label) === normaliseComboboxQuery(query),
+      ),
+    [allowCreate, query, filteredOptions],
+  );
+
+  const totalItems = filteredOptions.length + (showCreateRow ? 1 : 0);
+
+  const selectOption = useCallback(
+    (optionValue: string) => {
+      const next = multiple
+        ? selectedValuesSet.has(optionValue)
+          ? selectedValues.filter(v => v !== optionValue)
+          : [...selectedValues, optionValue]
+        : [optionValue];
+      updateValue(next);
+      setQuery('');
+    },
+    [multiple, selectedValues, selectedValuesSet, updateValue],
+  );
+
+  const removeValue = useCallback(
+    (optionValue: string) => {
+      updateValue(selectedValues.filter(v => v !== optionValue));
+    },
+    [selectedValues, updateValue],
+  );
+
+  const clearAll = useCallback(() => {
+    updateValue([]);
+    setQuery('');
+  }, [updateValue]);
+
+  const openPopover = useCallback(() => {
+    if (!disabled) setIsOpen(true);
+  }, [disabled]);
+
+  const ensureCreatedOption = useCallback(
+    (result: ComboboxCreateResult, inputValue: string): string => {
+      const fallback: ComboboxOption = {
+        value: inputValue.toLowerCase().replace(/\s+/g, '-'),
+        label: inputValue,
+      };
+
+      const created
+        = typeof result === 'string'
+          ? { value: result, label: inputValue }
+          : (result ?? fallback);
+
+      const existingByValue = mergedOptions.find(opt => opt.value === created.value);
+      if (!existingByValue) {
+        setCreatedOptions((prev) => {
+          if (prev.some(opt => opt.value === created.value)) return prev;
+          return [...prev, created];
+        });
+      }
+
+      return existingByValue?.value ?? created.value;
+    },
+    [mergedOptions],
+  );
+
+  const handleCreate = useCallback(() => {
+    const trimmed = query.trim();
+    if (!trimmed) return;
+
+    const existing = mergedOptions.find(
+      opt => normaliseComboboxQuery(opt.label) === normaliseComboboxQuery(trimmed),
+    );
+    if (existing) {
+      selectOption(existing.value);
+      return;
+    }
+
+    const createResult = onCreateNew?.(trimmed);
+    const createdValue = ensureCreatedOption(createResult, trimmed);
+    selectOption(createdValue);
+  }, [query, mergedOptions, onCreateNew, ensureCreatedOption, selectOption]);
+
+  const deleteCreatedOption = useCallback(
+    (optionValue: string) => {
+      setCreatedOptions(prev => prev.filter(opt => opt.value !== optionValue));
+
+      if (selectedValues.includes(optionValue)) {
+        updateValue(selectedValues.filter(v => v !== optionValue));
+      }
+
+      onDeleteCreated?.(optionValue);
+    },
+    [selectedValues, updateValue, onDeleteCreated],
+  );
+
+  return {
+    selectedValues,
+    selectedValuesSet,
+    query,
+    setQuery,
+    isOpen,
+    setIsOpen,
+    highlightIndex,
+    setHighlightIndex,
+
+    mergedOptions,
+    filteredOptions,
+    createdValuesSet,
+    showCreateRow,
+    totalItems,
+
+    selectOption,
+    removeValue,
+    clearAll,
+    handleCreate,
+    deleteCreatedOption,
+    openPopover,
+
+    isAsync,
+  };
+};

package/src/components/combobox/useElementWidth.ts

@@ -0,0 +1,40 @@
+import { useCallback, useLayoutEffect, useState } from 'react';
+
+export const useElementWidth = (
+  ref: React.RefObject<HTMLElement | null>,
+  watchKey: string,
+): number => {
+  const [measurement, setMeasurement] = useState({ width: 0, hasMeasured: false });
+  const element = ref.current;
+
+  const update = useCallback(() => {
+    const currentElement = ref.current;
+    if (!currentElement) {
+      setMeasurement({ width: 0, hasMeasured: true });
+      return;
+    }
+
+    setMeasurement({
+      width: currentElement.getBoundingClientRect().width,
+      hasMeasured: true,
+    });
+  }, [ref]);
+
+  useLayoutEffect(() => {
+    // Re-run measurement when callers know the element's contents/layout inputs changed.
+    update();
+  }, [update, watchKey]);
+
+  useLayoutEffect(() => {
+    if (!element) return;
+
+    const observer = new ResizeObserver(update);
+    observer.observe(element);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [element, update]);
+
+  return measurement.width;
+};

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

@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'vitest';
+import { computeTriggerLayoutModel } from './useVisibleChips';
+
+describe('computeTriggerLayoutModel', () => {
+  test('shows all chips and no ellipsis when there is no overflow', () => {
+    const result = computeTriggerLayoutModel({
+      containerWidth: 300,
+      chipWidths: [70, 80, 60],
+      chipGap: 4,
+      badgeWidth: 24,
+      ellipsisWidth: 12,
+      showBadge: true,
+    });
+
+    expect(result).toEqual({
+      visibleChipIndices: [0, 1, 2],
+      hiddenChipCount: 0,
+      showBadge: true,
+      showEllipsis: false,
+      hasOverflow: false,
+    });
+  });
+
+  test('reserves badge and ellipsis before fitting chips when overflow exists', () => {
+    const result = computeTriggerLayoutModel({
+      containerWidth: 160,
+      chipWidths: [60, 60, 60],
+      chipGap: 4,
+      badgeWidth: 24,
+      ellipsisWidth: 12,
+      showBadge: true,
+    });
+
+    expect(result.visibleChipIndices).toEqual([0]);
+    expect(result.hiddenChipCount).toBe(2);
+    expect(result.showEllipsis).toBe(true);
+    expect(result.hasOverflow).toBe(true);
+  });
+
+  test('allows zero chips when badge and ellipsis take priority in tiny space', () => {
+    const result = computeTriggerLayoutModel({
+      containerWidth: 36,
+      chipWidths: [80, 80],
+      chipGap: 4,
+      badgeWidth: 24,
+      ellipsisWidth: 12,
+      showBadge: true,
+    });
+
+    expect(result.visibleChipIndices).toEqual([]);
+    expect(result.hiddenChipCount).toBe(2);
+    expect(result.showEllipsis).toBe(true);
+  });
+
+  test('reserving badge space reduces visible count', () => {
+    const withBadge = computeTriggerLayoutModel({
+      containerWidth: 180,
+      chipWidths: [60, 60, 60],
+      chipGap: 4,
+      badgeWidth: 24,
+      ellipsisWidth: 12,
+      showBadge: true,
+    });
+
+    const withoutBadge = computeTriggerLayoutModel({
+      containerWidth: 180,
+      chipWidths: [60, 60, 60],
+      chipGap: 4,
+      badgeWidth: 24,
+      ellipsisWidth: 12,
+      showBadge: false,
+    });
+
+    expect(withoutBadge.visibleChipIndices.length).toBeGreaterThanOrEqual(withBadge.visibleChipIndices.length);
+  });
+
+  test('uses safety buffer to avoid a clipped final chip on boundary widths', () => {
+    const result = computeTriggerLayoutModel({
+      containerWidth: 195.5,
+      chipWidths: [73.4, 73.4, 20],
+      chipGap: 4,
+      badgeWidth: 24.2,
+      ellipsisWidth: 11.6,
+      showBadge: true,
+      safetyBuffer: 1,
+    });
+
+    expect(result.visibleChipIndices).toEqual([0]);
+    expect(result.showEllipsis).toBe(true);
+  });
+});