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

package/src/components/combobox/Combobox.tsx

@@ -0,0 +1,434 @@
+import classNames from 'classnames';
+import { Popover } from 'radix-ui';
+import { useCallback, useContext, useId, useMemo, useRef } from 'react';
+import { PopupParentContext } from 'Utils/PopupParentContext';
+import { buildOptionGroups } from './buildListboxDisplayOptions';
+import { ComboboxButtonTrigger } from './ComboboxButtonTrigger';
+import { ComboboxListbox } from './ComboboxListbox';
+import { ComboboxTrigger } from './ComboboxTrigger';
+import type { ComboboxProps } from './types';
+import { useChipSelection } from './useChipSelection';
+import { useComboboxKeyboard } from './useComboboxKeyboard';
+import { useComboboxListboxDom } from './useComboboxListboxDom';
+import { useComboboxPopoverBehavior } from './useComboboxPopoverBehavior';
+import { useComboboxState } from './useComboboxState';
+
+const ComboboxRoot = (props: ComboboxProps): React.JSX.Element => {
+  const {
+    options,
+    multiple = false,
+    value: controlledValue,
+    defaultValue,
+    onValueChange,
+    onSearch,
+    searchType = 'prefix',
+    highlightStringMatches = false,
+    allowCreate = false,
+    onCreateNew,
+    onDeleteCreated,
+    placeholder = 'Select...',
+    disabled = false,
+    dropdownOnFocus = true,
+    triggerVariant = 'input',
+    showDropdownTrigger = true,
+    showSelectionCountBadge = triggerVariant === 'button' && multiple,
+    selectionCountA11yLabel,
+    loading = false,
+    hasError = false,
+    showClearAll = false,
+    clearAllLabel = 'Clear all',
+    renderOption,
+    getTagLabel,
+    id: externalId,
+    'aria-describedby': ariaDescribedBy,
+    'aria-invalid': ariaInvalid,
+    'aria-label': ariaLabel,
+  } = props;
+
+  const generatedId = useId();
+  const comboboxId = externalId ?? generatedId;
+  const listboxId = `${comboboxId}-listbox`;
+
+  const state = useComboboxState({
+    options,
+    multiple,
+    value: controlledValue,
+    defaultValue,
+    onValueChange,
+    onSearch,
+    searchType,
+    allowCreate,
+    onCreateNew,
+    onDeleteCreated,
+    disabled,
+  });
+
+  const {
+    selectedValues,
+    selectedValuesSet,
+    query,
+    setQuery,
+    isOpen,
+    setIsOpen,
+    highlightIndex,
+    setHighlightIndex,
+    mergedOptions,
+    filteredOptions,
+    createdValuesSet,
+    showCreateRow,
+    totalItems,
+    selectOption,
+    removeValue,
+    clearAll,
+    handleCreate,
+    deleteCreatedOption,
+    openPopover,
+    isAsync,
+  } = state;
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const triggerRef = useRef<HTMLDivElement>(null);
+  const deleteButtonRefs = useRef(new Map<string, HTMLButtonElement>());
+  const popupParentRef = useContext(PopupParentContext);
+
+  const { listboxRef, getOptionId, scrollHighlightedIntoView } = useComboboxListboxDom({
+    comboboxId,
+  });
+
+  const {
+    selectedChipValues,
+    selectedChipValuesSet,
+    setSelectedChipValues,
+    clearChipSelection,
+    focusedChipIndex,
+    setFocusedChipIndex,
+    exitChipNav,
+  } = useChipSelection(selectedValues);
+
+  const {
+    shouldRenderPopoverContent,
+    shouldShowPopover,
+    showListboxLoading,
+    handleInputChange,
+    handleTriggerClick,
+    handleInputFocus,
+    handleInputBlur,
+    handleChevronClick,
+    handlePopoverInteractOutside,
+  } = useComboboxPopoverBehavior({
+    inputRef,
+    triggerRef,
+    listboxRef,
+    disabled,
+    dropdownOnFocus,
+    loading,
+    onSearch,
+    isAsync,
+    isOpen,
+    setIsOpen,
+    setQuery,
+    setHighlightIndex,
+    openPopover,
+    totalItems,
+    showCreateRow,
+    filteredOptionsLength: filteredOptions.length,
+    highlightIndex,
+    clearChipSelection,
+    exitChipNav,
+    triggerContainsInput: triggerVariant === 'input',
+  });
+
+  const optionGroups = useMemo(() => buildOptionGroups(filteredOptions), [filteredOptions]);
+
+  const optionIndexMap = useMemo(() => {
+    const map = new Map<string, number>();
+    filteredOptions.forEach((opt, i) => map.set(opt.value, i));
+    return map;
+  }, [filteredOptions]);
+
+  const resolveTagLabel = useCallback(
+    (opt: { tagLabel?: string; label: string }): string => {
+      if (getTagLabel) return getTagLabel(opt as Parameters<typeof getTagLabel>[0]);
+      return opt.tagLabel ?? opt.label;
+    },
+    [getTagLabel],
+  );
+
+  const registerDeleteButton = useCallback((value: string, node: HTMLButtonElement | null) => {
+    if (node) {
+      deleteButtonRefs.current.set(value, node);
+    }
+    else {
+      deleteButtonRefs.current.delete(value);
+    }
+  }, []);
+
+  const focusDeleteButtonForHighlighted = useCallback((): boolean => {
+    if (highlightIndex < 0 || highlightIndex >= filteredOptions.length) return false;
+
+    const highlightedOption = filteredOptions[highlightIndex];
+    if (!highlightedOption || !createdValuesSet.has(highlightedOption.value)) return false;
+
+    const button = deleteButtonRefs.current.get(highlightedOption.value);
+    if (!button) return false;
+
+    button.focus();
+    return true;
+  }, [createdValuesSet, filteredOptions, highlightIndex]);
+
+  const focusInputAtIndex = useCallback((index: number) => {
+    setHighlightIndex(index);
+    inputRef.current?.focus();
+  }, [setHighlightIndex]);
+
+  const handleDeleteCreatedFromList = useCallback((value: string, index: number) => {
+    const nextIndex = filteredOptions.length > 1
+      ? Math.min(index, filteredOptions.length - 2)
+      : -1;
+
+    deleteCreatedOption(value);
+    focusInputAtIndex(nextIndex);
+  }, [deleteCreatedOption, filteredOptions.length, focusInputAtIndex]);
+
+  const handleDeleteButtonKeyDown = useCallback((e: React.KeyboardEvent<HTMLButtonElement>, index: number) => {
+    if (e.key === 'ArrowLeft') {
+      e.preventDefault();
+      focusInputAtIndex(index);
+    }
+    else if (e.key === 'Tab' && e.shiftKey) {
+      e.preventDefault();
+      focusInputAtIndex(index);
+    }
+  }, [focusInputAtIndex]);
+
+  const handleKeyDown = useComboboxKeyboard({
+    inputRef,
+    allowCreate,
+    clearAll,
+    clearChipSelection,
+    exitChipNav,
+    focusDeleteButtonForHighlighted,
+    listboxOptions: filteredOptions,
+    focusedChipIndex,
+    handleCreate,
+    highlightIndex,
+    isOpen,
+    mergedOptions,
+    openPopover,
+    query,
+    removeValue,
+    scrollHighlightedIntoView,
+    selectOption,
+    selectedChipValues,
+    selectedValues,
+    setFocusedChipIndex,
+    setHighlightIndex,
+    setIsOpen,
+    setQuery,
+    setSelectedChipValues,
+    showCreateRow,
+    showListboxLoading,
+    totalItems,
+  });
+
+  const activeDescendant
+    = shouldShowPopover && !showListboxLoading && highlightIndex >= 0
+      ? getOptionId(highlightIndex)
+      : undefined;
+
+  const selectedChips = useMemo(
+    () =>
+      selectedValues
+        .map(v => mergedOptions.find(o => o.value === v))
+        .filter(Boolean) as typeof mergedOptions,
+    [selectedValues, mergedOptions],
+  );
+
+  const preventMouseDefault = useCallback((e: React.MouseEvent) => {
+    e.preventDefault();
+  }, []);
+  const renderSearchInputInListbox = triggerVariant === 'button';
+
+  const handlePopoverOpenAutoFocus = useCallback(
+    (e: Event) => {
+      e.preventDefault();
+      if (triggerVariant === 'button') {
+        requestAnimationFrame(() => {
+          inputRef.current?.focus();
+        });
+      }
+    },
+    [triggerVariant],
+  );
+
+  const resolvedSelectionCountA11yLabel = useMemo(() => {
+    if (!showSelectionCountBadge || selectedValues.length === 0) {
+      return undefined;
+    }
+    if (typeof selectionCountA11yLabel === 'function') {
+      return selectionCountA11yLabel(selectedValues.length);
+    }
+    if (selectionCountA11yLabel) {
+      return selectionCountA11yLabel;
+    }
+    return `${selectedValues.length} selected item${selectedValues.length === 1 ? '' : 's'}`;
+  }, [selectedValues.length, selectionCountA11yLabel, showSelectionCountBadge]);
+
+  const handleButtonTriggerKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      if (disabled) return;
+      if (e.key === 'Enter' || e.key === ' ' || e.key === 'ArrowDown') {
+        e.preventDefault();
+        handleTriggerClick();
+      }
+    },
+    [disabled, handleTriggerClick],
+  );
+
+  return (
+    <div
+      className={classNames('ds-combobox', {
+        'ds-combobox--disabled': disabled,
+        'ds-combobox--error': hasError,
+      })}
+    >
+      <Popover.Root open={isOpen} onOpenChange={setIsOpen}>
+        {triggerVariant === 'input'
+          ? (
+              <ComboboxTrigger
+                inputRef={inputRef}
+                triggerRef={triggerRef}
+                comboboxId={comboboxId}
+                listboxId={listboxId}
+                isOpen={isOpen}
+                hasError={hasError}
+                disabled={disabled}
+                placeholder={placeholder}
+                query={query}
+                shouldShowPopover={shouldShowPopover}
+                showListboxLoading={showListboxLoading}
+                activeDescendant={activeDescendant}
+                aria-describedby={ariaDescribedBy}
+                aria-invalid={ariaInvalid}
+                aria-label={ariaLabel}
+                showDropdownTrigger={showDropdownTrigger}
+                selectedChips={selectedChips}
+                selectedChipValuesSet={selectedChipValuesSet}
+                focusedChipIndex={focusedChipIndex}
+                resolveTagLabel={resolveTagLabel}
+                removeValue={removeValue}
+                handleTriggerClick={handleTriggerClick}
+                handleInputChange={handleInputChange}
+                handleInputFocus={handleInputFocus}
+                handleInputBlur={handleInputBlur}
+                handleKeyDown={handleKeyDown}
+                handleChevronClick={handleChevronClick}
+              />
+            )
+          : (
+              <ComboboxButtonTrigger
+                triggerRef={triggerRef}
+                listboxId={listboxId}
+                isOpen={isOpen}
+                hasError={hasError}
+                disabled={disabled}
+                placeholder={placeholder}
+                ariaLabel={ariaLabel}
+                ariaDescribedBy={ariaDescribedBy}
+                ariaInvalid={ariaInvalid}
+                showDropdownTrigger={showDropdownTrigger}
+                selectedChips={selectedChips}
+                selectedChipValuesSet={selectedChipValuesSet}
+                focusedChipIndex={focusedChipIndex}
+                resolveTagLabel={resolveTagLabel}
+                removeValue={removeValue}
+                handleTriggerClick={handleTriggerClick}
+                handleTriggerKeyDown={handleButtonTriggerKeyDown}
+                handleChevronClick={handleChevronClick}
+                showSelectionCountBadge={showSelectionCountBadge}
+                selectionCountA11yLabel={resolvedSelectionCountA11yLabel}
+              />
+            )}
+
+        <Popover.Portal container={popupParentRef.current}>
+          {shouldRenderPopoverContent && (
+            <Popover.Content
+              align="start"
+              sideOffset={4}
+              onOpenAutoFocus={handlePopoverOpenAutoFocus}
+              onCloseAutoFocus={e => e.preventDefault()}
+              onInteractOutside={handlePopoverInteractOutside}
+              className={classNames('ds-dropdown__content', 'ds-combobox__popover')}
+            >
+              <ComboboxListbox
+                listboxRef={listboxRef}
+                listboxId={listboxId}
+                multiple={multiple}
+                ariaLabel={ariaLabel}
+                showListboxLoading={showListboxLoading}
+                optionGroups={optionGroups}
+                optionIndexMap={optionIndexMap}
+                getOptionId={getOptionId}
+                highlightIndex={highlightIndex}
+                setHighlightIndex={setHighlightIndex}
+                query={query}
+                searchType={searchType}
+                highlightStringMatches={highlightStringMatches}
+                renderOption={renderOption}
+                selectedValuesSet={selectedValuesSet}
+                createdValuesSet={createdValuesSet}
+                selectOption={selectOption}
+                deleteCreatedOption={handleDeleteCreatedFromList}
+                handleCreate={handleCreate}
+                showCreateRow={showCreateRow}
+                filteredOptionsLength={filteredOptions.length}
+                preventMouseDefault={preventMouseDefault}
+                renderSearchInputInListbox={renderSearchInputInListbox}
+                inputRef={inputRef}
+                comboboxId={comboboxId}
+                shouldShowPopover={shouldShowPopover}
+                activeDescendant={activeDescendant}
+                ariaDescribedBy={ariaDescribedBy}
+                ariaInvalid={ariaInvalid}
+                placeholder={placeholder}
+                handleInputChange={handleInputChange}
+                handleInputFocus={handleInputFocus}
+                handleInputBlur={handleInputBlur}
+                handleKeyDown={handleKeyDown}
+                registerDeleteButton={registerDeleteButton}
+                handleDeleteButtonKeyDown={handleDeleteButtonKeyDown}
+              />
+            </Popover.Content>
+          )}
+        </Popover.Portal>
+      </Popover.Root>
+
+      {showClearAll && selectedValues.length > 0 && (
+        <div className="ds-combobox__clear-all-wrapper">
+          <button
+            type="button"
+            className="ds-combobox__clear-all"
+            onClick={clearAll}
+            disabled={disabled}
+          >
+            {clearAllLabel}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+};
+
+ComboboxRoot.displayName = 'Combobox';
+
+type ComboboxCompound = typeof ComboboxRoot & {
+  Trigger: typeof ComboboxTrigger;
+  ButtonTrigger: typeof ComboboxButtonTrigger;
+  Listbox: typeof ComboboxListbox;
+};
+
+export const Combobox = ComboboxRoot as ComboboxCompound;
+
+Combobox.Trigger = ComboboxTrigger;
+Combobox.ButtonTrigger = ComboboxButtonTrigger;
+Combobox.Listbox = ComboboxListbox;

package/src/components/combobox/ComboboxButtonTrigger.tsx

@@ -0,0 +1,195 @@
+import classNames from 'classnames';
+import { Badge } from 'Components/badge/Badge';
+import { Icon } from 'Components/icon/Icon';
+import { Tag } from 'Components/tag/Tag';
+import { Popover } from 'radix-ui';
+import { useMemo, useRef } from 'react';
+import type { ComboboxAriaInvalid, ComboboxOption } from './types';
+import { useElementWidth } from './useElementWidth';
+import { useVisibleChips } from './useVisibleChips';
+
+export type ComboboxButtonTriggerProps = {
+  triggerRef: React.RefObject<HTMLDivElement | null>;
+  listboxId: string;
+  isOpen: boolean;
+  hasError: boolean;
+  disabled: boolean;
+  placeholder: string;
+  ariaLabel?: string;
+  ariaDescribedBy?: string;
+  ariaInvalid?: ComboboxAriaInvalid;
+  showDropdownTrigger: boolean;
+  selectedChips: ComboboxOption[];
+  selectedChipValuesSet: Set<string>;
+  focusedChipIndex: number | null;
+  resolveTagLabel: (opt: ComboboxOption) => string;
+  removeValue: (value: string) => void;
+  handleTriggerClick: () => void;
+  handleTriggerKeyDown: (e: React.KeyboardEvent<HTMLDivElement>) => void;
+  handleChevronClick: (e: React.MouseEvent) => void;
+  showSelectionCountBadge: boolean;
+  selectionCountA11yLabel?: string;
+};
+
+export const ComboboxButtonTrigger = ({
+  triggerRef,
+  listboxId,
+  isOpen,
+  hasError,
+  disabled,
+  placeholder,
+  ariaLabel,
+  ariaDescribedBy,
+  ariaInvalid,
+  showDropdownTrigger,
+  selectedChips,
+  selectedChipValuesSet,
+  focusedChipIndex,
+  resolveTagLabel,
+  removeValue,
+  handleTriggerClick,
+  handleTriggerKeyDown,
+  handleChevronClick,
+  showSelectionCountBadge,
+  selectionCountA11yLabel,
+}: ComboboxButtonTriggerProps): React.JSX.Element => {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const measureTrackRef = useRef<HTMLDivElement>(null);
+  const ellipsisProbeRef = useRef<HTMLSpanElement>(null);
+  const badgeProbeRef = useRef<HTMLSpanElement>(null);
+
+  const chipWatchKey = useMemo(
+    () =>
+      selectedChips
+        .map(opt => `${opt.value}:${resolveTagLabel(opt)}:${opt.iconName ?? ''}`)
+        .join('|'),
+    [resolveTagLabel, selectedChips],
+  );
+
+  const shouldShowBadge = showSelectionCountBadge && selectedChips.length > 0;
+
+  const contentWidth = useElementWidth(contentRef, `${chipWatchKey}-${isOpen}-${shouldShowBadge}`);
+  const measurementTrackWidth = useElementWidth(measureTrackRef, `${chipWatchKey}-${isOpen}`);
+  const ellipsisWidth = useElementWidth(ellipsisProbeRef, `${chipWatchKey}-${isOpen}`);
+  const badgeWidth = useElementWidth(badgeProbeRef, `${chipWatchKey}-${isOpen}-${shouldShowBadge}`);
+  const measurementTrackElement = measureTrackRef.current;
+
+  const chipGap = useMemo(() => {
+    const el = measureTrackRef.current;
+    if (!el) return 0;
+    const styles = getComputedStyle(el);
+    const parsed = Number.parseFloat(styles.columnGap || styles.gap || '0');
+    return Number.isFinite(parsed) ? parsed : 0;
+  }, [measurementTrackElement, measurementTrackWidth]);
+
+  const chipWidths = useMemo(() => {
+    const el = measureTrackRef.current;
+    if (!el) return [];
+    return Array.from(el.children).map((child) => {
+      const width = (child as HTMLElement).getBoundingClientRect().width;
+      return Number.isFinite(width) ? width : 0;
+    });
+  }, [chipWatchKey, measurementTrackElement, measurementTrackWidth]);
+
+  const layout = useVisibleChips({
+    containerWidth: contentWidth,
+    chipWidths,
+    chipGap,
+    badgeWidth,
+    ellipsisWidth,
+    showBadge: shouldShowBadge,
+  });
+
+  const canMeasure = contentWidth > 0 && chipWidths.length === selectedChips.length;
+  const visibleChips = canMeasure
+    ? layout.visibleChipIndices.map(index => selectedChips[index]!).filter(Boolean)
+    : selectedChips;
+  const showEllipsis = canMeasure ? layout.showEllipsis : false;
+  const showBadge = canMeasure ? layout.showBadge : shouldShowBadge;
+
+  const renderSelectionTag = (opt: ComboboxOption, chipIdx: number, onRemove?: () => void) => (
+    <Tag
+      key={opt.value}
+      color="neutral"
+      selected={selectedChipValuesSet.has(opt.value) || focusedChipIndex === chipIdx}
+      slotStart={opt.iconName ? <Icon name={opt.iconName} size={12} /> : undefined}
+      onRemove={onRemove}
+      removeLabel={`Remove ${resolveTagLabel(opt)}`}
+      removeButtonTabIndex={-1}
+    >
+      {resolveTagLabel(opt)}
+    </Tag>
+  );
+
+  const renderSelectionCountBadge = (withA11yLabel: boolean) => (
+    <Badge colour="salmon" a11yLabel={withA11yLabel ? selectionCountA11yLabel : undefined}>
+      {selectedChips.length}
+    </Badge>
+  );
+
+  return (
+    <Popover.Anchor asChild>
+      <div
+        ref={triggerRef}
+        role="button"
+        tabIndex={disabled ? -1 : 0}
+        aria-haspopup="listbox"
+        aria-expanded={isOpen}
+        aria-controls={listboxId}
+        aria-label={ariaLabel}
+        aria-describedby={ariaDescribedBy}
+        aria-invalid={ariaInvalid}
+        className={classNames('ds-combobox__trigger', 'ds-combobox__trigger--button', {
+          'ds-combobox__trigger--open': isOpen,
+          'ds-combobox__trigger--error': hasError,
+          'ds-combobox__trigger--disabled': disabled,
+        })}
+        onClick={handleTriggerClick}
+        onKeyDown={handleTriggerKeyDown}
+      >
+        <div className="ds-combobox__button-content" ref={contentRef}>
+          <div className="ds-combobox__button-tags-viewport">
+            <div className="ds-combobox__button-tags-track">
+              {selectedChips.length === 0 && (
+                <span className="ds-combobox__button-placeholder">{placeholder}</span>
+              )}
+              {visibleChips.map((opt, chipIdx) =>
+                renderSelectionTag(opt, chipIdx, disabled ? undefined : () => removeValue(opt.value)))}
+            </div>
+            {showEllipsis && <span className="ds-combobox__button-ellipsis" aria-hidden="true">…</span>}
+          </div>
+          {showBadge && renderSelectionCountBadge(true)}
+        </div>
+        {showDropdownTrigger && (
+          <button
+            type="button"
+            className="ds-combobox__chevron"
+            tabIndex={-1}
+            aria-label="Open suggestions"
+            onClick={handleChevronClick}
+            disabled={disabled}
+          >
+            <Icon name={isOpen ? 'chevron-up' : 'chevron-down'} size={16} />
+          </button>
+        )}
+
+        <div className="ds-combobox__measure" aria-hidden="true">
+          {/* Mirror the rendered chips off-screen so width calculations use the real Tag layout. */}
+          <div className="ds-combobox__button-tags-track" ref={measureTrackRef}>
+            {selectedChips.map((opt, chipIdx) => (
+              <span key={`measure-${opt.value}`} className="ds-combobox__measure-chip">
+                {renderSelectionTag(opt, chipIdx, disabled ? undefined : () => {})}
+              </span>
+            ))}
+          </div>
+          <span ref={ellipsisProbeRef} className="ds-combobox__button-ellipsis">…</span>
+          <span ref={badgeProbeRef}>
+            {shouldShowBadge ? renderSelectionCountBadge(false) : null}
+          </span>
+        </div>
+      </div>
+    </Popover.Anchor>
+  );
+};
+
+ComboboxButtonTrigger.displayName = 'Combobox.ButtonTrigger';