@primer/components 30.3.0-rc.2010c7d4 → 30.3.0-rc.9dbc85a9

package/src/Autocomplete/Autocomplete.tsx

@@ -0,0 +1,103 @@
+import React, {useCallback, useReducer, useRef} from 'react'
+import {useSSRSafeId} from '@react-aria/ssr'
+import {ComponentProps} from '../utils/types'
+import {AutocompleteContext} from './AutocompleteContext'
+import AutocompleteInput from './AutocompleteInput'
+import AutocompleteMenu from './AutocompleteMenu'
+import AutocompleteOverlay from './AutocompleteOverlay'
+
+type Action =
+  | {type: 'showMenu' | 'isMenuDirectlyActivated'; payload: boolean}
+  | {type: 'autocompleteSuggestion' | 'inputValue'; payload: string}
+  | {type: 'selectedItemLength'; payload: number}
+
+interface State {
+  inputValue: string
+  showMenu: boolean
+  isMenuDirectlyActivated: boolean
+  autocompleteSuggestion: string
+  selectedItemLength: number
+}
+
+const initialState = {
+  inputValue: '',
+  showMenu: false,
+  isMenuDirectlyActivated: false,
+  autocompleteSuggestion: '',
+  selectedItemLength: 0
+}
+
+const reducer = (state: State, action: Action) => {
+  const {type, payload} = action
+  switch (type) {
+    case 'inputValue':
+      return {...state, inputValue: payload as State['inputValue']}
+    case 'showMenu':
+      return {...state, showMenu: payload as State['showMenu']}
+    case 'isMenuDirectlyActivated':
+      return {...state, isMenuDirectlyActivated: payload as State['isMenuDirectlyActivated']}
+    case 'autocompleteSuggestion':
+      return {...state, autocompleteSuggestion: payload as State['autocompleteSuggestion']}
+    case 'selectedItemLength':
+      return {...state, selectedItemLength: payload as State['selectedItemLength']}
+    default:
+      return state
+  }
+}
+
+const Autocomplete: React.FC<{id?: string}> = ({children, id: idProp}) => {
+  const activeDescendantRef = useRef<HTMLElement>(null)
+  const scrollContainerRef = useRef<HTMLDivElement>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [state, dispatch] = useReducer(reducer, initialState)
+  const {inputValue, showMenu, autocompleteSuggestion, isMenuDirectlyActivated, selectedItemLength} = state
+  const setInputValue = useCallback((value: State['inputValue']) => {
+    dispatch({type: 'inputValue', payload: value})
+  }, [])
+  const setShowMenu = useCallback((value: State['showMenu']) => {
+    dispatch({type: 'showMenu', payload: value})
+  }, [])
+  const setAutocompleteSuggestion = useCallback((value: State['autocompleteSuggestion']) => {
+    dispatch({type: 'autocompleteSuggestion', payload: value})
+  }, [])
+  const setIsMenuDirectlyActivated = useCallback((value: State['isMenuDirectlyActivated']) => {
+    dispatch({type: 'isMenuDirectlyActivated', payload: value})
+  }, [])
+  const setSelectedItemLength = useCallback((value: State['selectedItemLength']) => {
+    dispatch({type: 'selectedItemLength', payload: value})
+  }, [])
+  const id = useSSRSafeId(idProp)
+
+  return (
+    <AutocompleteContext.Provider
+      value={{
+        activeDescendantRef,
+        autocompleteSuggestion,
+        id,
+        inputRef,
+        inputValue,
+        isMenuDirectlyActivated,
+        scrollContainerRef,
+        selectedItemLength,
+        setAutocompleteSuggestion,
+        setInputValue,
+        setIsMenuDirectlyActivated,
+        setShowMenu,
+        setSelectedItemLength,
+        showMenu
+      }}
+    >
+      {children}
+    </AutocompleteContext.Provider>
+  )
+}
+
+export type AutocompleteProps = ComponentProps<typeof Autocomplete>
+export type {AutocompleteInputProps} from './AutocompleteInput'
+export type {AutocompleteMenuProps} from './AutocompleteMenu'
+export type {AutocompleteOverlayProps} from './AutocompleteOverlay'
+export default Object.assign(Autocomplete, {
+  Input: AutocompleteInput,
+  Menu: AutocompleteMenu,
+  Overlay: AutocompleteOverlay
+})

package/src/Autocomplete/AutocompleteContext.tsx

@@ -0,0 +1,19 @@
+import {createContext} from 'react'
+
+export const AutocompleteContext = createContext<{
+  activeDescendantRef: React.MutableRefObject<HTMLElement | null>
+  autocompleteSuggestion: string
+  // TODO: consider changing `id` to `listboxId` because we're just using it to associate the input and combobox with the listbox
+  id: string
+  inputRef: React.MutableRefObject<HTMLInputElement | null>
+  inputValue: string
+  isMenuDirectlyActivated: boolean
+  scrollContainerRef: React.MutableRefObject<HTMLElement | null>
+  selectedItemLength: number
+  setAutocompleteSuggestion: (value: string) => void
+  setInputValue: (value: string) => void
+  setIsMenuDirectlyActivated: (value: boolean) => void
+  setSelectedItemLength: (value: number) => void
+  setShowMenu: (value: boolean) => void
+  showMenu: boolean
+} | null>(null)

package/src/Autocomplete/AutocompleteInput.tsx

@@ -0,0 +1,179 @@
+import React, {
+  ChangeEventHandler,
+  FocusEventHandler,
+  KeyboardEventHandler,
+  MutableRefObject,
+  useCallback,
+  useContext,
+  useEffect,
+  useState
+} from 'react'
+import {ForwardRefComponent as PolymorphicForwardRefComponent} from '@radix-ui/react-polymorphic'
+import {AutocompleteContext} from './AutocompleteContext'
+import TextInput from '../TextInput'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
+import {ComponentProps} from '../utils/types'
+
+type InternalAutocompleteInputProps = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  as?: React.ComponentType<any>
+}
+
+const AutocompleteInput = React.forwardRef(
+  (
+    {as: Component = TextInput, onFocus, onBlur, onChange, onKeyDown, onKeyUp, onKeyPress, value, ...props},
+    forwardedRef
+  ) => {
+    const autocompleteContext = useContext(AutocompleteContext)
+    if (autocompleteContext === null) {
+      throw new Error('AutocompleteContext returned null values')
+    }
+    const {
+      activeDescendantRef,
+      autocompleteSuggestion = '',
+      id,
+      inputRef,
+      inputValue = '',
+      isMenuDirectlyActivated,
+      setInputValue,
+      setShowMenu,
+      showMenu
+    } = autocompleteContext
+    const combinedInputRef = useCombinedRefs(inputRef, forwardedRef)
+    const [highlightRemainingText, setHighlightRemainingText] = useState<boolean>(true)
+
+    const handleInputFocus: FocusEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onFocus && onFocus(event)
+        setShowMenu(true)
+      },
+      [onFocus, setShowMenu]
+    )
+
+    const handleInputBlur: FocusEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onBlur && onBlur(event)
+
+        // HACK: wait a tick and check the focused element before hiding the autocomplete menu
+        // this prevents the menu from hiding when the user is clicking an option in the Autoselect.Menu,
+        // but still hides the menu when the user blurs the input by tabbing out or clicking somewhere else on the page
+        setTimeout(() => {
+          if (document.activeElement !== combinedInputRef.current) {
+            setShowMenu(false)
+          }
+        }, 0)
+      },
+      [onBlur, setShowMenu, combinedInputRef]
+    )
+
+    const handleInputChange: ChangeEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onChange && onChange(event)
+        setInputValue(event.currentTarget.value)
+        if (!showMenu) {
+          setShowMenu(true)
+        }
+      },
+      [onChange, setInputValue, setShowMenu, showMenu]
+    )
+
+    const handleInputKeyDown: KeyboardEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onKeyDown && onKeyDown(event)
+
+        if (event.key === 'Backspace') {
+          setHighlightRemainingText(false)
+        }
+
+        if (event.key === 'Escape' && inputRef.current?.value) {
+          setInputValue('')
+          inputRef.current.value = ''
+        }
+      },
+      [inputRef, setInputValue, setHighlightRemainingText, onKeyDown]
+    )
+
+    const handleInputKeyUp: KeyboardEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onKeyUp && onKeyUp(event)
+
+        if (event.key === 'Backspace') {
+          setHighlightRemainingText(true)
+        }
+      },
+      [setHighlightRemainingText, onKeyUp]
+    )
+
+    const onInputKeyPress: KeyboardEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onKeyPress && onKeyPress(event)
+
+        if (showMenu && event.key === 'Enter' && activeDescendantRef.current) {
+          event.preventDefault()
+          event.nativeEvent.stopImmediatePropagation()
+
+          // Forward Enter key press to active descendant so that item gets activated
+          const activeDescendantEvent = new KeyboardEvent(event.type, event.nativeEvent)
+          activeDescendantRef.current.dispatchEvent(activeDescendantEvent)
+        }
+      },
+      [activeDescendantRef, showMenu, onKeyPress]
+    )
+
+    useEffect(() => {
+      if (!inputRef.current) {
+        return
+      }
+
+      // resets input value to being empty after a selection has been made
+      if (!autocompleteSuggestion) {
+        inputRef.current.value = inputValue
+      }
+
+      // TODO: fix bug where this function prevents `onChange` from being triggered if the highlighted item text
+      //       is the same as what I'm typing
+      //       e.g.: typing 'tw' highights 'two', but when I 'two', the text input change does not get triggered
+      if (highlightRemainingText && autocompleteSuggestion && (inputValue || isMenuDirectlyActivated)) {
+        inputRef.current.value = autocompleteSuggestion
+
+        if (autocompleteSuggestion.toLowerCase().indexOf(inputValue.toLowerCase()) === 0) {
+          inputRef.current.setSelectionRange(inputValue.length, autocompleteSuggestion.length)
+        }
+      }
+
+      // calling this useEffeect when `highlightRemainingText` changes breaks backspace functionality
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [autocompleteSuggestion, inputValue, inputRef, isMenuDirectlyActivated])
+
+    useEffect(() => {
+      if (value) {
+        setInputValue(value.toString())
+      }
+    }, [value, setInputValue])
+
+    return (
+      <Component
+        onFocus={handleInputFocus}
+        onBlur={handleInputBlur}
+        onChange={handleInputChange}
+        onKeyDown={handleInputKeyDown}
+        onKeyPress={onInputKeyPress}
+        onKeyUp={handleInputKeyUp}
+        ref={combinedInputRef as MutableRefObject<HTMLInputElement>}
+        aria-controls={`${id}-listbox`}
+        aria-autocomplete="both"
+        role="combobox"
+        aria-expanded={showMenu}
+        aria-haspopup="listbox"
+        aria-owns={`${id}-listbox`}
+        autocomplete="off"
+        {...props}
+      />
+    )
+  }
+) as PolymorphicForwardRefComponent<typeof TextInput, InternalAutocompleteInputProps>
+
+AutocompleteInput.displayName = 'AutocompleteInput'
+
+export type AutocompleteInputProps = ComponentProps<typeof AutocompleteInput>
+export default AutocompleteInput

package/src/Autocomplete/AutocompleteMenu.tsx

@@ -0,0 +1,341 @@
+import React, {useContext, useEffect, useMemo, useRef, useState} from 'react'
+import {ActionList, ItemProps} from '../ActionList'
+import {useFocusZone} from '../hooks/useFocusZone'
+import {ComponentProps, MandateProps} from '../utils/types'
+import {Box, Spinner} from '../'
+import {AutocompleteContext} from './AutocompleteContext'
+import {PlusIcon} from '@primer/octicons-react'
+import {uniqueId} from '../utils/uniqueId'
+import {scrollIntoViewingArea} from '../behaviors/scrollIntoViewingArea'
+
+type OnSelectedChange<T> = (item: T | T[]) => void
+type AutocompleteMenuItem = MandateProps<ItemProps, 'id'>
+
+const getDefaultSortFn =
+  (isItemSelectedFn: (itemId: string | number) => boolean) => (itemIdA: string | number, itemIdB: string | number) =>
+    isItemSelectedFn(itemIdA) === isItemSelectedFn(itemIdB) ? 0 : isItemSelectedFn(itemIdA) ? -1 : 1
+
+function getDefaultItemFilter<T extends AutocompleteMenuItem>(filterValue: string) {
+  return function (item: T, _i: number) {
+    return Boolean(item.text?.toLowerCase().startsWith(filterValue.toLowerCase()))
+  }
+}
+
+function getDefaultOnSelectionChange<T extends AutocompleteMenuItem>(
+  setInputValueFn: (value: string) => void
+): OnSelectedChange<T> {
+  return function (itemOrItems) {
+    const {text = ''} = Array.isArray(itemOrItems) ? itemOrItems.slice(-1)[0] : itemOrItems
+    setInputValueFn(text)
+  }
+}
+
+const isItemSelected = (itemId: string | number, selectedItemIds: Array<string | number>) =>
+  selectedItemIds.includes(itemId)
+
+function getItemById<T extends AutocompleteMenuItem>(itemId: string | number, items: T[]) {
+  return items.find(item => item.id === itemId)
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AutocompleteItemProps<T = Record<string, any>> = AutocompleteMenuItem & {metadata?: T}
+
+export type AutocompleteMenuInternalProps<T extends AutocompleteItemProps> = {
+  /**
+   * A menu item that is used to allow users make a selection that is not available in the array passed to the `items` prop.
+   * This menu item gets appended to the end of the list of options.
+   */
+  // TODO: rethink this part of the component API. this is kind of weird and confusing to use
+  // TODO: rethink `addNewItem` prop name
+  addNewItem?: Omit<T, 'onAction' | 'leadingVisual' | 'id'> & {
+    handleAddItem: (item: Omit<T, 'onAction' | 'leadingVisual'>) => void
+  }
+
+  /**
+   * The text that appears in the menu when there are no options in the array passed to the `items` prop.
+   */
+  emptyStateText?: React.ReactNode | false
+
+  /**
+   * A custom function used to filter the options in the array passed to the `items` prop.
+   * By default, we filter out items that don't match the value of the autocomplete text input. The default filter is not case-sensitive.
+   */
+  filterFn?: (item: T, i: number) => boolean
+
+  /**
+   * The options for field values that are displayed in the dropdown menu.
+   * One or more may be selected depending on the value of the `selectionVariant` prop.
+   */
+  items: T[]
+
+  /**
+   * Whether the data is loaded for the menu items
+   */
+  loading?: boolean
+
+  /**
+   * The IDs of the selected items
+   */
+  // NOTE: this diverges from the SelectPanel component API, where we pass an array of objects to the `selected` prop
+  selectedItemIds: Array<string | number>
+
+  /**
+   * The sort function that is applied to the options in the array passed to the `items` prop after the user closes the menu.
+   * By default, selected items are sorted to the top after the user closes the menu.
+   */
+  sortOnCloseFn?: (itemIdA: string | number, itemIdB: string | number) => number
+
+  /**
+   * Whether there can be one item selected from the menu or multiple items selected from the menu
+   */
+  selectionVariant?: 'single' | 'multiple'
+
+  /**
+   * Function that gets called when the menu is opened or closed
+   */
+  onOpenChange?: (open: boolean) => void
+
+  /**
+   * The function that is called when an item in the list is selected or deselected
+   */
+  onSelectedChange?: OnSelectedChange<T>
+
+  /**
+   * If the menu is rendered in a scrolling element other than the `Autocomplete.Overlay` component,
+   * pass the ref of that element to `customScrollContainerRef` to ensure the container automatically
+   * scrolls when the user highlights an item in the menu that is outside the scroll container
+   */
+  customScrollContainerRef?: React.MutableRefObject<HTMLElement | null>
+} & Pick<React.AriaAttributes, 'aria-labelledby'>
+
+function AutocompleteMenu<T extends AutocompleteItemProps>(props: AutocompleteMenuInternalProps<T>) {
+  const autocompleteContext = useContext(AutocompleteContext)
+  if (autocompleteContext === null) {
+    throw new Error('AutocompleteContext returned null values')
+  }
+  const {
+    activeDescendantRef,
+    id,
+    inputRef,
+    inputValue = '',
+    scrollContainerRef,
+    setAutocompleteSuggestion,
+    setShowMenu,
+    setInputValue,
+    setIsMenuDirectlyActivated,
+    setSelectedItemLength,
+    showMenu
+  } = autocompleteContext
+  const {
+    items,
+    selectedItemIds,
+    sortOnCloseFn,
+    emptyStateText,
+    addNewItem,
+    loading,
+    selectionVariant,
+    filterFn,
+    'aria-labelledby': ariaLabelledBy,
+    onOpenChange,
+    onSelectedChange,
+    customScrollContainerRef
+  } = props
+  const listContainerRef = useRef<HTMLDivElement>(null)
+  const [highlightedItem, setHighlightedItem] = useState<T>()
+  const [sortedItemIds, setSortedItemIds] = useState<Array<number | string>>(items.map(({id: itemId}) => itemId))
+
+  const selectableItems = useMemo(
+    () =>
+      items.map(selectableItem => {
+        return {
+          ...selectableItem,
+          role: 'option',
+          id: selectableItem.id,
+          selected: selectionVariant === 'multiple' ? selectedItemIds.includes(selectableItem.id) : undefined,
+          onAction: (item: T) => {
+            const otherSelectedItemIds = selectedItemIds.filter(selectedItemId => selectedItemId !== item.id)
+            const newSelectedItemIds = selectedItemIds.includes(item.id)
+              ? otherSelectedItemIds
+              : [...otherSelectedItemIds, item.id]
+            const onSelectedChangeFn = onSelectedChange ? onSelectedChange : getDefaultOnSelectionChange(setInputValue)
+
+            onSelectedChangeFn(
+              newSelectedItemIds.map(newSelectedItemId => getItemById(newSelectedItemId, items)) as T[]
+            )
+
+            if (selectionVariant === 'multiple') {
+              setInputValue('')
+              setAutocompleteSuggestion('')
+            } else {
+              setShowMenu(false)
+              inputRef.current?.setSelectionRange(inputRef.current.value.length, inputRef.current.value.length)
+            }
+          }
+        }
+      }),
+    [
+      items,
+      selectedItemIds,
+      inputRef,
+      onSelectedChange,
+      selectionVariant,
+      setAutocompleteSuggestion,
+      setInputValue,
+      setShowMenu
+    ]
+  )
+
+  const itemSortOrderData = useMemo(
+    () =>
+      sortedItemIds.reduce<Record<string | number, number>>((acc, curr, i) => {
+        acc[curr] = i
+
+        return acc
+      }, {}),
+    [sortedItemIds]
+  )
+
+  const sortedAndFilteredItemsToRender = useMemo(
+    () =>
+      selectableItems
+        .filter(filterFn ? filterFn : getDefaultItemFilter(inputValue))
+        .sort((a, b) => itemSortOrderData[a.id] - itemSortOrderData[b.id]),
+    [selectableItems, itemSortOrderData, filterFn, inputValue]
+  )
+
+  const allItemsToRender = useMemo(
+    () => [
+      // sorted and filtered selectable items
+      ...sortedAndFilteredItemsToRender,
+
+      // menu item used for creating a token from whatever is in the text input
+      ...(addNewItem
+        ? [
+            {
+              ...addNewItem,
+              leadingVisual: () => <PlusIcon />,
+              onAction: (item: T) => {
+                // TODO: make it possible to pass a leadingVisual when using `addNewItem`
+                addNewItem.handleAddItem({...item, id: item.id || uniqueId(), leadingVisual: undefined})
+
+                if (selectionVariant === 'multiple') {
+                  setInputValue('')
+                  setAutocompleteSuggestion('')
+                }
+              }
+            }
+          ]
+        : [])
+    ],
+    [sortedAndFilteredItemsToRender, addNewItem, setAutocompleteSuggestion, selectionVariant, setInputValue]
+  )
+
+  useFocusZone(
+    {
+      containerRef: listContainerRef,
+      focusOutBehavior: 'wrap',
+      focusableElementFilter: element => {
+        return !(element instanceof HTMLInputElement)
+      },
+      activeDescendantFocus: inputRef,
+      onActiveDescendantChanged: (current, _previous, directlyActivated) => {
+        activeDescendantRef.current = current || null
+        if (current) {
+          const selectedItem = selectableItems.find(item => item.id.toString() === current.getAttribute('data-id'))
+
+          setHighlightedItem(selectedItem)
+          setIsMenuDirectlyActivated(directlyActivated)
+        }
+
+        if (current && customScrollContainerRef && customScrollContainerRef.current && directlyActivated) {
+          scrollIntoViewingArea(current, customScrollContainerRef.current)
+        } else if (current && scrollContainerRef.current && directlyActivated) {
+          scrollIntoViewingArea(current, scrollContainerRef.current)
+        }
+      }
+    },
+    [loading]
+  )
+
+  useEffect(() => {
+    if (highlightedItem?.text?.startsWith(inputValue) && !selectedItemIds.includes(highlightedItem.id)) {
+      setAutocompleteSuggestion(highlightedItem.text)
+    } else {
+      setAutocompleteSuggestion('')
+    }
+  }, [highlightedItem, inputValue, selectedItemIds, setAutocompleteSuggestion])
+
+  useEffect(() => {
+    const itemIdSortResult = [...sortedItemIds].sort(
+      sortOnCloseFn ? sortOnCloseFn : getDefaultSortFn(itemId => isItemSelected(itemId, selectedItemIds))
+    )
+    const sortResultMatchesState =
+      itemIdSortResult.length === sortedItemIds.length &&
+      itemIdSortResult.every((element, index) => element === sortedItemIds[index])
+
+    if (showMenu === false && !sortResultMatchesState) {
+      setSortedItemIds(itemIdSortResult)
+    }
+
+    onOpenChange && onOpenChange(Boolean(showMenu))
+  }, [showMenu, onOpenChange, selectedItemIds, sortOnCloseFn, sortedItemIds])
+
+  useEffect(() => {
+    if (selectedItemIds.length) {
+      setSelectedItemLength(selectedItemIds.length)
+    }
+  }, [selectedItemIds, setSelectedItemLength])
+
+  return (
+    <Box
+      sx={
+        !showMenu
+          ? {
+              // visually hides this label for sighted users
+              position: 'absolute',
+              width: '1px',
+              height: '1px',
+              padding: '0',
+              margin: '-1px',
+              overflow: 'hidden',
+              clip: 'rect(0, 0, 0, 0)',
+              whiteSpace: 'nowrap',
+              borderWidth: '0'
+            }
+          : {}
+      }
+    >
+      {loading ? (
+        <Box p={3} display="flex" justifyContent="center">
+          <Spinner />
+        </Box>
+      ) : (
+        <div ref={listContainerRef}>
+          {allItemsToRender.length ? (
+            <ActionList
+              selectionVariant="multiple"
+              // have to typecast to `ItemProps` because we have an extra property
+              // on `items` for Autocomplete: `metadata`
+              items={allItemsToRender as ItemProps[]}
+              role="listbox"
+              id={`${id}-listbox`}
+              aria-labelledby={ariaLabelledBy}
+            />
+          ) : (
+            <Box p={3}>{emptyStateText}</Box>
+          )}
+        </div>
+      )}
+    </Box>
+  )
+}
+
+AutocompleteMenu.defaultProps = {
+  emptyStateText: 'No selectable options',
+  selectionVariant: 'single'
+}
+
+AutocompleteMenu.displayName = 'AutocompleteMenu'
+
+export type AutocompleteMenuProps = ComponentProps<typeof AutocompleteMenu>
+export default AutocompleteMenu