@stack-spot/citric-react 0.41.2 → 0.42.0-beta.0

package/src/components/Autocomplete/Autocomplete.tsx

@@ -0,0 +1,794 @@
+import { ColorPaletteName, ColorSchemeName, listToClass } from '@stack-spot/portal-theme'
+import { useTranslate } from '@stack-spot/portal-translate'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { applyCSSVariable } from '../../utils/css'
+import { defaultRenderKey, defaultRenderLabel } from '../../utils/options'
+import { withRef } from '../../utils/react'
+import { Badge } from '../Badge'
+import { Checkbox } from '../Checkbox'
+import { CitricComponent } from '../CitricComponent'
+import { IconButton } from '../IconBox'
+import { ProgressCircular } from '../ProgressCircular'
+import { useDisabledEffect, useFocusEffect } from '../Select/hooks'
+import { Row } from '../layout'
+
+export interface BaseAutocompleteProps<T, Multiple extends boolean = false> {
+  /**
+   * The list of options available for selection.
+   */
+  options: T[],
+  /**
+   * The current value(s) selected.
+   * - Single selection: T | null
+   * - Multiple selection: T[]
+   */
+  value: Multiple extends true ? T[] : (T | null),
+  /**
+   * Callback fired when the value changes.
+   */
+  onChange: Multiple extends true ? (value: T[]) => void : (value: T | null) => void,
+  /**
+   * If true, enables multiple selection mode.
+   * @default false
+   */
+  multiple?: Multiple,
+  /**
+   * If true, allows the user to enter values that are not in the options list.
+   * @default false
+   */
+  freeSolo?: boolean,
+  /**
+   * If true, allows creating new options when no match is found.
+   * Shows an "Add [value]" option at the top of the list.
+   * @default false
+   */
+  creatable?: boolean,
+  /**
+   * Callback fired when a new option is created.
+   * Required when creatable is true and you want manual control.
+   */
+  onCreate?: (inputValue: string) => void,
+  /**
+   * Function to create a new option object from the input value.
+   * Required when creatable is true without onCreate and working with objects.
+   * 
+   * @example
+   * ```tsx
+   * getOptionFromInput={(inputValue) => ({ id: Date.now(), name: inputValue })}
+   * ```
+   */
+  getOptionFromInput?: (inputValue: string) => T,
+  /**
+   * The input value (controlled).
+   */
+  inputValue?: string,
+  /**
+   * Callback fired when the input value changes.
+   */
+  onInputChange?: (value: string) => void,
+  /**
+   * A function to render the item label.
+   * @default "the item's toString() result."
+   */
+  renderLabel?: (option: T) => string,
+  /**
+   * A function to generate a unique key for each option.
+   */
+  renderKey?: (option: T) => string | number,
+  /**
+   * A function to render an option in the dropdown.
+   */
+  renderOption?: (option: T) => React.ReactNode,
+  /**
+   * A function to render a tag in multiple mode.
+   */
+  renderTag?: (option: T, onRemove: () => void) => React.ReactNode,
+  /**
+   * Custom filter function for options.
+   * @default filters by label includes input (case insensitive)
+   */
+  filterOptions?: (options: T[], inputValue: string) => T[],
+  /**
+   * If true, shows a loading indicator.
+   * @default false
+   */
+  loading?: boolean,
+  /**
+   * If true, the component is disabled.
+   * @default false
+   */
+  disabled?: boolean,
+  /**
+   * Placeholder text for the input.
+   */
+  placeholder?: string,
+  /**
+   * Maximum height for the dropdown panel in pixels.
+   */
+  maxHeight?: number,
+  /**
+   * Maximum number of tags to show before truncating.
+   * Only applies when multiple is true.
+   */
+  maxTagsToShow?: number,
+  /**
+   * If true, automatically highlights the first option.
+   * @default false
+   */
+  autoHighlight?: boolean,
+  /**
+   * If true, clears the input value when an option is selected.
+   * Only applies when multiple is true.
+   * @default true (for multiple)
+   */
+  clearOnSelect?: boolean,
+  /**
+   * If true, the popup will open on input focus.
+   * @default true
+   */
+  openOnFocus?: boolean,
+  /**
+   * Callback fired when an option is selected (before onChange).
+   */
+  onSelect?: (option: T | null) => void,
+  /**
+   * Text to display when no options are available.
+   */
+  noOptionsText?: string,
+  /**
+   * Text to display when loading.
+   */
+  loadingText?: string,
+  /**
+   * Callback fired when the user scrolls to the end of the options list.
+   * Useful for implementing infinite scroll/pagination.
+   * 
+   * @example
+   * ```tsx
+   * <Autocomplete
+   *   options={options}
+   *   onScrollEnd={() => fetchMoreOptions()}
+   *   loading={isFetchingMore}
+   * />
+   * ```
+   */
+  onScrollEnd?: () => void,
+  /**
+   * Margin in pixels before the end of the list to trigger onScrollEnd.
+   * @default 200
+   */
+  scrollEndMargin?: number,
+  /**
+   * Color scheme for the tags (badges) in multiple mode.
+   * @example 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info'
+   */
+  tagColorScheme?: ColorSchemeName,
+  /**
+   * Color palette for the tags (badges) in multiple mode.
+   * @example 'blue' | 'green' | 'red' | 'yellow' | 'purple'
+   */
+  tagColorPalette?: ColorPaletteName,
+  /**
+   * Appearance of the tags (badges) in multiple mode.
+   * @default 'circle'
+   */
+  tagAppearance?: 'square' | 'circle',
+}
+
+export type AutocompleteProps<T, Multiple extends boolean = false> =
+  Omit<React.JSX.IntrinsicElements['div'], 'ref' | 'onChange' | 'onSelect'> &
+  BaseAutocompleteProps<T, Multiple>
+
+/**
+ * A combination of a text input and a dropdown that suggests options as the user types.
+ * Supports both single and multiple selection modes, similar to Material-UI Autocomplete.
+ * 
+ * @example
+ * Basic usage (single selection):
+ * ```tsx
+ * const [value, setValue] = useState<Option | null>(null)
+ * 
+ * <Autocomplete
+ *   options={options}
+ *   value={value}
+ *   onChange={setValue}
+ *   renderLabel={o => o.name}
+ *   renderKey={o => o.id}
+ * />
+ * ```
+ * 
+ * @example
+ * Multiple selection with tags:
+ * ```tsx
+ * const [value, setValue] = useState<Option[]>([])
+ * 
+ * <Autocomplete
+ *   multiple
+ *   options={options}
+ *   value={value}
+ *   onChange={setValue}
+ *   renderLabel={o => o.name}
+ *   renderKey={o => o.id}
+ * />
+ * ```
+ * 
+ * @example
+ * Free solo (allow custom values):
+ * ```tsx
+ * <Autocomplete
+ *   freeSolo
+ *   options={options}
+ *   value={value}
+ *   onChange={setValue}
+ *   renderLabel={o => o.name}
+ * />
+ * ```
+ */
+export const Autocomplete = withRef(
+  function Autocomplete<T, Multiple extends boolean = false>({
+    options,
+    value,
+    onChange,
+    multiple = false as Multiple,
+    freeSolo = false,
+    creatable = false,
+    onCreate,
+    getOptionFromInput,
+    inputValue: controlledInputValue,
+    onInputChange,
+    renderLabel = defaultRenderLabel,
+    renderKey = defaultRenderKey as (option: T) => string | number,
+    renderOption,
+    renderTag,
+    filterOptions,
+    loading = false,
+    disabled = false,
+    placeholder,
+    maxHeight,
+    maxTagsToShow,
+    autoHighlight = false,
+    clearOnSelect = multiple,
+    openOnFocus = true,
+    onSelect,
+    noOptionsText,
+    loadingText,
+    onScrollEnd,
+    scrollEndMargin = 200,
+    tagColorScheme,
+    tagColorPalette,
+    tagAppearance = 'circle',
+    style,
+    className,
+    ...props
+  }: AutocompleteProps<T, Multiple>, ref: React.Ref<HTMLDivElement>) {
+    const t = useTranslate(dictionary)
+    const _element = useRef<HTMLDivElement | null>(null)
+    const inputRef = useRef<HTMLInputElement | null>(null)
+    const dropdownRef = useRef<HTMLDivElement | null>(null)
+    const element = (ref as React.RefObject<HTMLDivElement>) ?? _element
+
+    const [open, setOpen] = useState(false)
+    const [focused, setFocused] = useState(false)
+    const [internalInputValue, setInternalInputValue] = useState('')
+    const [highlightedIndex, setHighlightedIndex] = useState<number>(-1)
+
+    useFocusEffect({ element, focused, setFocused, setOpen })
+    useDisabledEffect({ disabled, setOpen, setFocused })
+
+    useEffect(() => {
+      if (!open) return
+
+      const handleClickOutside = (event: MouseEvent) => {
+        if (element.current && !element.current.contains(event.target as Node)) {
+          setOpen(false)
+          setFocused(false)
+        }
+      }
+
+      setTimeout(() => {
+        document.addEventListener('click', handleClickOutside)
+      }, 10)
+
+      return () => {
+        document.removeEventListener('click', handleClickOutside)
+      }
+    }, [open, element])
+
+    const inputValue = controlledInputValue ?? internalInputValue
+    const setInputValue = useCallback((newValue: string) => {
+      if (onInputChange) {
+        onInputChange(newValue)
+      } else {
+        setInternalInputValue(newValue)
+      }
+    }, [onInputChange])
+
+    const defaultFilter = useCallback((opts: T[], input: string) => {
+      if (!input) return opts
+      return opts.filter(option =>
+        renderLabel(option).toLowerCase().includes(input.toLowerCase()),
+      )
+    }, [renderLabel])
+
+    const filter = filterOptions ?? defaultFilter
+
+    const filteredOptions = useMemo(() => filter(options, inputValue), [options, inputValue, filter])
+
+    const showCreateOption = useMemo(() => {
+      if (!creatable || !onCreate || !inputValue.trim()) return false
+
+      const hasExactMatch = filteredOptions.some(option =>
+        renderLabel(option).toLowerCase() === inputValue.toLowerCase(),
+      )
+
+      return !hasExactMatch
+    }, [creatable, onCreate, inputValue, filteredOptions, renderLabel])
+
+    const handleCreate = useCallback(() => {
+      if (!onCreate || !inputValue.trim()) return
+
+      onCreate(inputValue.trim())
+      setInputValue('')
+
+      if (inputRef.current) {
+        inputRef.current.focus()
+      }
+    }, [onCreate, inputValue, setInputValue])
+
+    const isSelected = useCallback((option: T) => {
+      if (multiple) {
+        return (value as T[]).some(v => renderKey(v) === renderKey(option))
+      }
+      return value !== null && renderKey(value as T) === renderKey(option)
+    }, [value, multiple, renderKey])
+
+    const handleSelect = useCallback((option: T) => {
+      if (onSelect) onSelect(option)
+
+      if (multiple) {
+        const currentValue = value as T[]
+        const isAlreadySelected = currentValue.some(v => renderKey(v) === renderKey(option))
+
+        if (isAlreadySelected) {
+          const newValue = currentValue.filter(v => renderKey(v) !== renderKey(option));
+          (onChange as (value: T[]) => void)(newValue)
+        } else {
+          (onChange as (value: T[]) => void)([...currentValue, option])
+        }
+
+        if (clearOnSelect) {
+          setInputValue('')
+        }
+      } else {
+        (onChange as (value: T | null) => void)(option)
+        setInputValue(renderLabel(option))
+        setOpen(false)
+      }
+    }, [multiple, value, onChange, renderKey, renderLabel, clearOnSelect, setInputValue, onSelect])
+
+    const handleRemoveTag = useCallback((optionToRemove: T) => {
+      if (!multiple) return
+      const newValue = (value as T[]).filter(v => renderKey(v) !== renderKey(optionToRemove));
+      (onChange as (value: T[]) => void)(newValue)
+    }, [multiple, value, onChange, renderKey])
+
+    const handleInputChange = (newValue: string) => {
+      setInputValue(newValue)
+      if (!open && newValue) {
+        setOpen(true)
+      }
+      setHighlightedIndex(autoHighlight ? 0 : -1)
+    }
+
+    const handleFocus = () => {
+      setFocused(true)
+      if (openOnFocus) {
+        setOpen(true)
+      }
+    }
+
+    const handleBlur = (e: React.FocusEvent) => {
+      if (element.current?.contains(e.relatedTarget as Node)) {
+        return
+      }
+
+      setFocused(false)
+      setOpen(false)
+
+      if (freeSolo && inputValue && !multiple) {
+        if (creatable && !onCreate) {
+          if (getOptionFromInput) {
+            const newOption = getOptionFromInput(inputValue.trim());
+            (onChange as (value: T | null) => void)(newOption)
+          } else {
+            (onChange as (value: T | null) => void)(inputValue as unknown as T)
+          }
+        } else {
+          const exactMatch = options.find(o =>
+            renderLabel(o).toLowerCase() === inputValue.toLowerCase(),
+          )
+          if (exactMatch) {
+            handleSelect(exactMatch)
+          }
+        }
+      }
+    }
+
+    const handleKeyDown = (e: React.KeyboardEvent) => {
+      if (disabled) return
+
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault()
+          if (!open) {
+            setOpen(true)
+          } else {
+            setHighlightedIndex(prev =>
+              prev < filteredOptions.length - 1 ? prev + 1 : prev,
+            )
+          }
+          break
+
+        case 'ArrowUp':
+          e.preventDefault()
+          if (open) {
+            setHighlightedIndex(prev => prev > 0 ? prev - 1 : 0)
+          }
+          break
+
+        case 'Enter':
+          e.preventDefault()
+          if (open && highlightedIndex >= 0 && filteredOptions[highlightedIndex]) {
+            handleSelect(filteredOptions[highlightedIndex])
+          } else if (creatable && inputValue.trim()) {
+            if (onCreate) {
+              handleCreate()
+            } else if (freeSolo && getOptionFromInput) {
+              const newOption = getOptionFromInput(inputValue.trim())
+              if (multiple) {
+                const currentValue = value as T[]
+                const isDuplicate = currentValue.some(v => renderKey(v) === renderKey(newOption))
+                if (!isDuplicate) {
+                  (onChange as (value: T[]) => void)([...currentValue, newOption])
+                }
+                setInputValue('')
+              } else {
+                (onChange as (value: T | null) => void)(newOption)
+                setInputValue(renderLabel(newOption))
+                setOpen(false)
+              }
+            } else if (freeSolo) {
+              if (multiple) {
+                const currentValue = value as T[]
+                const inputAsOption = inputValue as unknown as T
+                const isDuplicate = currentValue.some(v => renderLabel(v).toLowerCase() === inputValue.toLowerCase())
+                if (!isDuplicate) {
+                  (onChange as (value: T[]) => void)([...currentValue, inputAsOption])
+                }
+                setInputValue('')
+              } else {
+                (onChange as (value: T | null) => void)(inputValue as unknown as T)
+                setOpen(false)
+              }
+            }
+          } else if (freeSolo && inputValue && !multiple) {
+            const exactMatch = options.find(o =>
+              renderLabel(o).toLowerCase() === inputValue.toLowerCase(),
+            )
+            if (exactMatch) {
+              handleSelect(exactMatch)
+            }
+          }
+          break
+
+        case 'Escape':
+          e.preventDefault()
+          setOpen(false)
+          if (inputRef.current) {
+            inputRef.current.blur()
+          }
+          break
+
+        case 'Backspace':
+          if (multiple && !inputValue && (value as T[]).length > 0) {
+            const lastTag = (value as T[])[(value as T[]).length - 1]
+            handleRemoveTag(lastTag)
+          }
+          break
+
+        default:
+          break
+      }
+    }
+
+    const handleClear = () => {
+      if (multiple) {
+        (onChange as (value: T[]) => void)([])
+      } else {
+        (onChange as (value: T | null) => void)(null)
+      }
+      setInputValue('')
+      if (inputRef.current) {
+        inputRef.current.focus()
+      }
+    }
+
+    useEffect(() => {
+      if (!multiple && value && !focused) {
+        setInternalInputValue(renderLabel(value as T))
+      }
+    }, [value, multiple, renderLabel, focused])
+
+    useEffect(() => {
+      if (autoHighlight && open && filteredOptions.length > 0) {
+        setHighlightedIndex(0)
+      }
+    }, [autoHighlight, open, filteredOptions.length])
+
+    useEffect(() => {
+      if (highlightedIndex < 0 || !open) return
+
+      const optionsContainer = dropdownRef.current?.querySelector('.options') as HTMLElement
+      if (!optionsContainer) return
+
+      const highlightedOption = optionsContainer.children[highlightedIndex] as HTMLElement
+      if (!highlightedOption) return
+
+      const containerRect = optionsContainer.getBoundingClientRect()
+      const optionRect = highlightedOption.getBoundingClientRect()
+
+      if (optionRect.bottom > containerRect.bottom) {
+        highlightedOption.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+      } else if (optionRect.top < containerRect.top) {
+        highlightedOption.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+      }
+    }, [highlightedIndex, open])
+
+    useEffect(() => {
+      if (!onScrollEnd || !open) return
+
+      const optionsContainer = dropdownRef.current?.querySelector('.options') as HTMLElement
+      if (!optionsContainer) return
+
+      const handleScroll = () => {
+        if (loading) return
+
+        const { scrollTop, scrollHeight, clientHeight } = optionsContainer
+        const scrollBottom = scrollHeight - scrollTop - clientHeight
+
+        if (scrollBottom <= scrollEndMargin) {
+          onScrollEnd()
+        }
+      }
+
+      optionsContainer.addEventListener('scroll', handleScroll)
+      
+      handleScroll()
+
+      return () => {
+        optionsContainer.removeEventListener('scroll', handleScroll)
+      }
+    }, [onScrollEnd, open, filteredOptions.length, loading, scrollEndMargin])
+
+    const renderTags = () => {
+      if (!multiple || (value as T[]).length === 0) return null
+
+      const tags = value as T[]
+      const visibleTags = maxTagsToShow && tags.length > maxTagsToShow
+        ? tags.slice(0, maxTagsToShow)
+        : tags
+      const remainingCount = maxTagsToShow && tags.length > maxTagsToShow
+        ? tags.length - maxTagsToShow
+        : 0
+
+      return (
+        <>
+          {visibleTags.map(tag => {
+            if (renderTag) {
+              return renderTag(tag, () => handleRemoveTag(tag))
+            }
+            return (
+              <Badge 
+                key={renderKey(tag)}
+                colorScheme={tagColorScheme}
+                colorPalette={tagColorPalette}
+                appearance={tagAppearance}
+              >
+                {renderLabel(tag)}
+                {!disabled && (
+                  <IconButton
+                    icon="Times"
+                    type="button"
+                    appearance="none"
+                    size="xs"
+                    style={{ color: 'inherit' }}
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      if (!disabled) handleRemoveTag(tag)
+                    }}
+                    aria-label={`${t.removeTag} ${renderLabel(tag)}`}
+                    disabled={disabled}
+                    tabIndex={0}
+                  />)}
+              </Badge>
+            )
+          })}
+          {remainingCount > 0 && (
+            <Badge
+              colorScheme={tagColorScheme}
+              colorPalette={tagColorPalette}
+              appearance={tagAppearance}
+            >
+              +{remainingCount}
+            </Badge>
+          )}
+        </>
+      )
+    }
+
+    const showClearButton = !disabled && (
+      (!multiple && value !== null) ||
+      (multiple && (value as T[]).length > 0)
+    )
+
+    return (
+      <CitricComponent
+        tag="div"
+        component="autocomplete"
+        data-citric="autocomplete"
+        style={maxHeight ? applyCSSVariable(style, 'max-height', `${maxHeight}px`) : style}
+        className={listToClass([
+          className,
+          open && 'open',
+          focused && 'focused',
+          disabled && 'disabled',
+          multiple && 'multiple',
+        ])}
+        ref={element}
+        aria-busy={loading}
+        {...props}
+      >
+        <header
+          onClick={() => {
+            if (disabled) return
+            setFocused(true)
+            setOpen(true)
+            if (inputRef.current) {
+              inputRef.current.focus()
+            }
+          }}
+          onFocus={() => setFocused(true)}
+          tabIndex={disabled ? undefined : 0}
+        >
+          <Row gap="4px" className="input-container">
+            {multiple && renderTags()}
+            <input
+              ref={inputRef}
+              type="text"
+              value={inputValue}
+              onChange={(e) => handleInputChange(e.target.value)}
+              onFocus={handleFocus}
+              onBlur={handleBlur}
+              onKeyDown={handleKeyDown}
+              disabled={disabled}
+              placeholder={multiple && (value as T[]).length > 0 ? '' : placeholder}
+              autoComplete="off"
+              aria-autocomplete="list"
+              aria-expanded={open}
+              aria-controls="autocomplete-listbox"
+            />
+          </Row>
+          <div className="end-adornment">
+            {loading && <ProgressCircular size="xs" className="loader" />}
+            {showClearButton && (
+              <IconButton
+                icon="Times"
+                appearance="none"
+                size="sm"
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  handleClear()
+                }}
+                disabled={disabled}
+                aria-label={t.clear}
+                tabIndex={1}
+                style={{ width: '12px', height: '12px' }}
+              />
+            )}
+            <IconButton
+              icon={open ? 'ChevronUp' : 'ChevronDown'}
+              appearance="none"
+              size="md"
+              type="button"
+              onClick={(e) => {
+                e.stopPropagation()
+                setOpen((prev) => !prev)
+              }}
+              disabled={disabled}
+              aria-label={open ? t.collapse : t.expand}
+              tabIndex={1}
+              style={{ width: '12px', height: '12px' }}
+            />
+          </div>
+        </header>
+
+        <div
+          className="dropdown-panel"
+          ref={dropdownRef}
+          id="autocomplete-listbox"
+          role="listbox"
+          aria-hidden={!open}
+          {...(open ? {} : { inert: 'true' })}
+        >
+          {loading && !filteredOptions.length ? (
+            <div className="message">{loadingText || t.loading}</div>
+          ) : filteredOptions.length === 0 && !showCreateOption ? (
+            <div className="message">{noOptionsText || t.noOptions}</div>
+          ) : (
+            <div className="options">
+              {showCreateOption && (
+                <div
+                  key="create-option"
+                  role="option"
+                  className="option create-option"
+                  onMouseDown={(e) => {
+                    e.preventDefault()
+                  }}
+                  onClick={handleCreate}
+                  onMouseEnter={() => setHighlightedIndex(-1)}
+                > 
+                  <i data-citric="icon" className="citric-icon outline Plus" />
+                  {t.addOption.replace('{value}', inputValue)}
+                </div>
+              )}
+              {filteredOptions.map((option, index) => (
+                <div
+                  key={renderKey(option)}
+                  role="option"
+                  aria-selected={isSelected(option)}
+                  className={listToClass([
+                    'option',
+                    isSelected(option) && 'selected',
+                    highlightedIndex === index && 'highlighted',
+                  ])}
+                  onMouseDown={(e) => {
+                    e.preventDefault()
+                  }}
+                  onClick={() => handleSelect(option)}
+                  onMouseEnter={() => setHighlightedIndex(index)}
+                >
+                  {multiple && <Checkbox value={isSelected(option)} readOnly />}
+                  {renderOption ? renderOption(option) : renderLabel(option)}
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      </CitricComponent>
+    )
+  },
+) as <T, Multiple extends boolean = false>(
+  props: AutocompleteProps<T, Multiple>,
+) => React.ReactElement
+
+const dictionary = {
+  en: {
+    removeTag: 'Remove',
+    clear: 'Clear',
+    loading: 'Loading...',
+    noOptions: 'No options',
+    collapse: 'Collapse',
+    expand: 'Expand',
+    addOption: 'Add "{value}"',
+  },
+  pt: {
+    removeTag: 'Remover',
+    clear: 'Limpar',
+    loading: 'Carregando...',
+    noOptions: 'Sem opções',
+    collapse: 'Recolher',
+    expand: 'Expandir',
+    addOption: 'Adicionar "{value}"',
+  },
+}