Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
12.2 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file hooks.ts
 * @input Uses React hooks, the shared useTypeahead hook, MultiSelectorOptionData type
 * @output Exports useMultiCombobox hook
 * @position Public hook, exported from the MultiSelector entry point; used by
 *   MultiSelector.tsx
 *
 * SYNC: When modified, update:
 * - /packages/core/src/MultiSelector/index.ts
 * - /packages/core/src/MultiSelector/useMultiCombobox.doc.mjs
 */

import {useCallback, useState} from 'react';
import {isRtlElement} from '../hooks/isRtlElement';
import {useHighlightedOptionScroll} from '../hooks/useHighlightedOptionScroll';
import type {MultiSelectorOptionData} from './types';
import {useTypeahead} from '../hooks/useTypeahead';
import {enabledEdgeIndex} from '../utils/enabledEdgeIndex';

interface UseMultiComboboxOptions {
  selectableItems: MultiSelectorOptionData[];
  isDisabled?: boolean;
  isOpen: boolean;
  hasSearch?: boolean;
  onOpen: () => unknown;
  onClose: () => void;
  onToggle: (itemValue: string) => void;
  /**
   * Clear all selected values. When provided, pressing Delete or Backspace on
   * the closed trigger clears the selection — a keyboard equivalent of the
   * clear button (comboboxes-2). No-op when the popup is open or search is on.
   */
  onClear?: () => void;
  /**
   * Whether at least one value is selected (i.e. there is something to clear).
   * The Delete/Backspace clear path is skipped when false.
   */
  hasValue?: boolean;
  listboxId: string;
  /**
   * Whether the popup is a grid (`spec:AST-058`): rows pair an option cell
   * with an action cell, the inline-end arrow moves the highlight from the
   * option to the action and the inline-start arrow back, and Enter on the
   * action cell activates the caller's control instead of toggling.
   */
  isGrid?: boolean;
  /** Whether the row at `index` carries an action to move to. */
  rowHasAction?: (index: number) => boolean;
  /** Activate the control in the highlighted row's action cell. */
  onActivateAction?: (index: number) => void;
}

/** Which cell of the highlighted row the highlight is on. */
export type MultiComboboxCell = 'option' | 'action';

interface UseMultiComboboxResult {
  highlightedIndex: number;
  setHighlightedIndex: (index: number) => void;
  /** `'action'` only in a grid, while the highlight is on the action cell. */
  highlightedCell: MultiComboboxCell;
  getItemId: (index: number) => string;
  /** Id of the action cell of the row at `index` (the active descendant there). */
  getActionCellId: (index: number) => string;
  /** The element `aria-activedescendant` names, or undefined. */
  activeDescendantId: string | undefined;
  onTriggerClick: () => void;
  onKeyDown: (e: React.KeyboardEvent) => void;
  onItemMouseEnter: (
    item: MultiSelectorOptionData,
    index: number,
    cell?: MultiComboboxCell,
  ) => void;
}

/**
 * Handles keyboard navigation and toggle logic for multi-select combobox.
 * Works like useCombobox (index-based) but toggling does NOT close the dropdown.
 *
 * The caller must ensure selectableItems is in the same order as the rendered DOM.
 */
export function useMultiCombobox({
  selectableItems,
  isDisabled = false,
  isOpen,
  hasSearch = false,
  onOpen,
  onClose,
  onToggle,
  onClear,
  hasValue = false,
  listboxId,
  isGrid = false,
  rowHasAction,
  onActivateAction,
}: UseMultiComboboxOptions): UseMultiComboboxResult {
  const [highlightedIndex, setHighlightedIndexState] = useState<number>(-1);
  const [highlightedCell, setHighlightedCell] =
    useState<MultiComboboxCell>('option');
  // Every move between rows lands on the option cell (spec:AST-058 FR5).
  const setHighlightedIndex = useCallback((index: number) => {
    setHighlightedIndexState(index);
    setHighlightedCell('option');
  }, []);

  // A match on the closed control opens the list on that option.
  const typeahead = useTypeahead({
    getItemLabels: () => selectableItems.map(item => item.label),
    isDisabled: index => selectableItems[index]?.disabled === true,
    getCurrentIndex: () => (isOpen ? highlightedIndex : -1),
    onMatch: index => {
      if (isOpen || onOpen() !== false) {
        setHighlightedIndex(index);
      }
    },
  });
  const resetTypeahead = typeahead.reset;

  const getItemId = useCallback(
    (index: number) => `${listboxId}-item-${index}`,
    [listboxId],
  );
  const getActionCellId = useCallback(
    (index: number) => `${listboxId}-item-${index}-action`,
    [listboxId],
  );
  const activeDescendantId =
    isOpen && highlightedIndex >= 0
      ? isGrid && highlightedCell === 'action'
        ? getActionCellId(highlightedIndex)
        : getItemId(highlightedIndex)
      : undefined;

  const getEnabledIndices = useCallback(() => {
    return selectableItems
      .map((item, i) => (!item.disabled ? i : -1))
      .filter(i => i >= 0);
  }, [selectableItems]);

  /** Opening never lands on a disabled option; -1 when none is enabled. */
  const findOpeningIndex = useCallback(
    (fromEnd: boolean) => enabledEdgeIndex(selectableItems, fromEnd),
    [selectableItems],
  );

  const closeAndReset = useCallback(() => {
    // Clear the typed prefix on close. Otherwise the next key extends it.
    resetTypeahead();
    setHighlightedIndex(-1);
    onClose();
  }, [onClose, resetTypeahead, setHighlightedIndex]);

  const onTriggerClick = useCallback(() => {
    if (isDisabled) {
      return;
    }
    if (isOpen) {
      closeAndReset();
    } else {
      const didOpen = onOpen() !== false;
      if (didOpen && !hasSearch) {
        setHighlightedIndex(findOpeningIndex(false));
      }
    }
  }, [
    isDisabled,
    isOpen,
    onOpen,
    closeAndReset,
    hasSearch,
    setHighlightedIndex,
    findOpeningIndex,
  ]);

  // The scroll effect lives here, the highlight owner, so the hover/keyboard
  // split is shared instead of re-implemented in MultiSelector.tsx (#6077).
  const highlightOnHover = useHighlightedOptionScroll({
    isOpen,
    highlightedIndex,
    setHighlightedIndex,
    getOptionId: getItemId,
  });

  const onItemMouseEnter = useCallback(
    (
      item: MultiSelectorOptionData,
      index: number,
      cell: MultiComboboxCell = 'option',
    ) => {
      // The action cell is the caller's control, usable whether or not the
      // option itself is disabled (spec:AST-058 FR4).
      if (cell === 'action') {
        highlightOnHover(index, () => setHighlightedCell('action'));
        return;
      }
      if (!item.disabled) {
        highlightOnHover(index, () => setHighlightedCell('option'));
      }
    },
    [highlightOnHover],
  );

  const onKeyDown = useCallback(
    (e: React.KeyboardEvent) => {
      if (isDisabled) {
        return;
      }

      // With hasSearch the query input owns typing, so type-to-select is off.
      // Space stays the toggle: after a letter jumps to an option, Space picks
      // it, so Space never extends the typed prefix here.
      if (!hasSearch && e.key !== ' ' && typeahead.onKeyDown(e)) {
        e.preventDefault();
        return;
      }

      const enabledIndices = getEnabledIndices();

      // In a grid the horizontal arrows move between the row's two cells,
      // following visual direction under RTL (spec:AST-058 FR5). Outside a
      // grid, or with no row highlighted, they keep their default meaning
      // (the caret, in a search input).
      if (isGrid && isOpen && highlightedIndex >= 0) {
        const isRtl = isRtlElement(e.currentTarget as HTMLElement);
        const inlineEnd = isRtl ? 'ArrowLeft' : 'ArrowRight';
        const inlineStart = isRtl ? 'ArrowRight' : 'ArrowLeft';
        if (e.key === inlineEnd) {
          if (
            highlightedCell === 'option' &&
            rowHasAction?.(highlightedIndex) === true
          ) {
            e.preventDefault();
            setHighlightedCell('action');
          }
          return;
        }
        if (e.key === inlineStart) {
          if (highlightedCell === 'action') {
            e.preventDefault();
            setHighlightedCell('option');
          }
          return;
        }
      }

      switch (e.key) {
        case 'ArrowDown':
          e.preventDefault();
          if (!isOpen) {
            if (onOpen() !== false) {
              setHighlightedIndex(findOpeningIndex(false));
            }
          } else {
            const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);
            const nextPos = Math.min(
              currentEnabledPos + 1,
              enabledIndices.length - 1,
            );
            setHighlightedIndex(enabledIndices[nextPos] ?? highlightedIndex);
          }
          break;

        case 'ArrowUp':
          e.preventDefault();
          if (!isOpen) {
            if (onOpen() !== false) {
              setHighlightedIndex(findOpeningIndex(true));
            }
          } else {
            const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);
            const prevPos = Math.max(currentEnabledPos - 1, 0);
            setHighlightedIndex(enabledIndices[prevPos] ?? highlightedIndex);
          }
          break;

        case 'Enter':
        case ' ':
          // Don't intercept Space when search input is focused
          if (e.key === ' ' && hasSearch) {
            break;
          }
          e.preventDefault();
          if (isOpen && highlightedIndex >= 0) {
            if (isGrid && highlightedCell === 'action') {
              // The highlight is on the caller's control: fire it, and only
              // it — the selection does not change (spec:AST-058 FR4).
              onActivateAction?.(highlightedIndex);
              break;
            }
            const item = selectableItems[highlightedIndex];
            if (item && !item.disabled) {
              onToggle(item.value);
            }
          } else if (!isOpen) {
            const didOpen = onOpen() !== false;
            if (didOpen && !hasSearch) {
              setHighlightedIndex(findOpeningIndex(false));
            }
          }
          break;

        case 'Tab':
          if (isOpen) {
            closeAndReset();
          }
          break;

        case 'Escape':
          if (isOpen) {
            e.preventDefault();
            closeAndReset();
          }
          break;

        case 'Home':
          e.preventDefault();
          if (isOpen && enabledIndices.length > 0) {
            setHighlightedIndex(enabledIndices[0]);
          }
          break;

        case 'End':
          e.preventDefault();
          if (isOpen && enabledIndices.length > 0) {
            setHighlightedIndex(enabledIndices[enabledIndices.length - 1]);
          }
          break;

        // PageUp/PageDown mirror Home/End. In search mode Home/End stay on
        // the input for caret movement (APG editable combobox), so these are
        // the sanctioned substitute for jumping to the first/last option.
        case 'PageUp':
          e.preventDefault();
          if (isOpen && enabledIndices.length > 0) {
            setHighlightedIndex(enabledIndices[0]);
          }
          break;

        case 'PageDown':
          e.preventDefault();
          if (isOpen && enabledIndices.length > 0) {
            setHighlightedIndex(enabledIndices[enabledIndices.length - 1]);
          }
          break;

        case 'Delete':
        case 'Backspace':
          // Keyboard equivalent of the clear button (comboboxes-2): clear all
          // selected values from the closed trigger so clearing is not
          // mouse-only. Skipped in search mode (keys edit the query) and while
          // the popup is open (arrow navigation owns interaction).
          if (!hasSearch && !isOpen && onClear != null && hasValue) {
            e.preventDefault();
            onClear();
          }
          break;
      }
    },
    [
      isDisabled,
      isOpen,
      onOpen,
      closeAndReset,
      selectableItems,
      highlightedIndex,
      highlightedCell,
      isGrid,
      rowHasAction,
      onActivateAction,
      setHighlightedIndex,
      onToggle,
      getEnabledIndices,
      findOpeningIndex,
      hasSearch,
      typeahead,
      onClear,
      hasValue,
    ],
  );

  return {
    highlightedIndex,
    setHighlightedIndex,
    highlightedCell,
    getItemId,
    getActionCellId,
    activeDescendantId,
    onTriggerClick,
    onKeyDown,
    onItemMouseEnter,
  };
}