AutocompletePrompt.tsx

import {SelectInput, SelectInputProps, Item as SelectItem} from './SelectInput.js'
import {InfoTableProps} from './Prompts/InfoTable.js'
import {TextInput} from './TextInput.js'
import {InfoMessageProps} from './Prompts/InfoMessage.js'
import {Message, PromptLayout} from './Prompts/PromptLayout.js'
import {throttle} from '../../../../public/common/function.js'
import {AbortSignal} from '../../../../public/node/abort.js'
import {useComplete} from '../../ui.js'
import usePrompt, {PromptState} from '../hooks/use-prompt.js'

import React, {ReactElement, useCallback, useEffect, useRef, useState} from 'react'
import {Box} from 'ink'

export interface SearchResults<T> {
  data: SelectItem<T>[]
  meta?: {
    hasNextPage: boolean
  }
}

export interface AutocompletePromptProps<T> {
  message: Message
  choices: SelectInputProps<T>['items']
  onSubmit: (value: T) => void
  infoTable?: InfoTableProps['table']
  hasMorePages?: boolean
  search: (term: string) => Promise<SearchResults<T>>
  abortSignal?: AbortSignal
  infoMessage?: InfoMessageProps['message']
  groupOrder?: string[]
  /**
   * Throttle window in milliseconds applied to the search callback. Defaults to 400ms,
   * which is appropriate for remote/paginated backends. In-memory consumers (where the
   * search callback resolves synchronously) can pass 0 for instant filtering on every
   * keystroke.
   */
  searchDebounceMs?: number
}

const MIN_NUMBER_OF_ITEMS_FOR_SEARCH = 5
const DEFAULT_SEARCH_DEBOUNCE_MS = 400

function AutocompletePrompt<T>({
  message,
  choices,
  infoTable,
  onSubmit,
  search,
  hasMorePages: initialHasMorePages = false,
  abortSignal,
  infoMessage,
  groupOrder,
  searchDebounceMs = DEFAULT_SEARCH_DEBOUNCE_MS,
}: React.PropsWithChildren<AutocompletePromptProps<T>>): ReactElement | null {
  const complete = useComplete()
  const [searchTerm, setSearchTerm] = useState('')
  const [searchResults, setSearchResults] = useState<SelectItem<T>[]>(choices)
  const canSearch = choices.length > MIN_NUMBER_OF_ITEMS_FOR_SEARCH
  const [hasMorePages, setHasMorePages] = useState(initialHasMorePages)
  const {promptState, setPromptState, answer, setAnswer} = usePrompt<SelectItem<T> | undefined>({
    initialAnswer: undefined,
  })

  const paginatedSearch = useCallback(
    async (term: string) => {
      const results = await search(term)
      return results
    },
    [search],
  )

  const submitAnswer = useCallback(
    (answer: SelectItem<T>) => {
      if (promptState === PromptState.Idle) {
        setAnswer(answer)
        setPromptState(PromptState.Submitted)
      }
    },
    [promptState, setAnswer, setPromptState],
  )

  useEffect(() => {
    if (promptState === PromptState.Submitted && answer) {
      setSearchTerm('')
      onSubmit(answer.value)
      complete()
    }
  }, [answer, onSubmit, promptState, complete])

  const setLoadingWhenSlow = useRef<NodeJS.Timeout>()

  // we want to set it each time so that searchTermRef always tracks searchTerm,
  // this is NOT the same as writing useRef(searchTerm)
  const searchTermRef = useRef('')
  searchTermRef.current = searchTerm

  // Keep current values in refs to avoid stale closures
  const choicesRef = useRef(choices)
  choicesRef.current = choices
  const initialHasPagesRef = useRef(initialHasMorePages)
  initialHasPagesRef.current = initialHasMorePages

  // useMemo ensures debounceSearch is not recreated on every render
  const debounceSearch = React.useMemo(
    () =>
      throttle(
        (term: string) => {
          setLoadingWhenSlow.current = setTimeout(() => {
            setPromptState(PromptState.Loading)
          }, 100)
          paginatedSearch(term)
            .then((result) => {
              // while we were waiting for the promise to resolve, the user
              // has emptied the search term, so we want to show the default
              // choices instead
              if (searchTermRef.current.length === 0) {
                setSearchResults(choicesRef.current)
                setHasMorePages(initialHasPagesRef.current)
              } else {
                setSearchResults(result.data)
                setHasMorePages(result.meta?.hasNextPage ?? false)
              }

              setPromptState(PromptState.Idle)
            })
            .catch(() => {
              setPromptState(PromptState.Error)
            })
            .finally(() => {
              clearTimeout(setLoadingWhenSlow.current)
            })
        },
        searchDebounceMs,
        {leading: true, trailing: true},
      ),
    [paginatedSearch, setPromptState, searchDebounceMs],
  )

  return (
    <PromptLayout
      message={message}
      state={promptState}
      infoTable={infoTable}
      infoMessage={infoMessage}
      abortSignal={abortSignal}
      header={
        promptState !== PromptState.Submitted && canSearch ? (
          <Box marginLeft={3}>
            <TextInput
              value={searchTerm}
              onChange={(term) => {
                setSearchTerm(term)
                // Update ref immediately so that the debounceSearch's .then()
                // callback sees the current term. With React 19's automatic
                // batching, the render (which normally updates the ref) is
                // deferred, so without this the ref would be stale when the
                // search Promise resolves.
                searchTermRef.current = term

                if (term.length > 0) {
                  debounceSearch(term)
                } else {
                  debounceSearch.cancel()
                  setPromptState(PromptState.Idle)
                  setSearchResults(choices)
                }
              }}
              placeholder="Type to search..."
            />
          </Box>
        ) : null
      }
      submittedAnswerLabel={answer?.label}
      input={
        <SelectInput
          items={searchResults}
          initialItems={choices}
          enableShortcuts={false}
          emptyMessage="No results found."
          highlightedTerm={searchTerm}
          loading={promptState === PromptState.Loading}
          errorMessage={
            promptState === PromptState.Error
              ? 'There has been an error while searching. Please try again later.'
              : undefined
          }
          hasMorePages={hasMorePages}
          morePagesMessage="Find what you're looking for by typing its name."
          onSubmit={submitAnswer}
          groupOrder={groupOrder}
        />
      }
    />
  )
}

export {AutocompletePrompt}