@stack-spot/citric-react 0.42.0 → 0.43.0

package/src/components/Autocomplete.tsx

@@ -0,0 +1,1038 @@
+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 CustomSelectedTagsConfig {
+  /**
+   * Color scheme for the tags (badges).
+   */
+  colorScheme?: ColorSchemeName,
+  /**
+   * Color palette for the tags (badges).
+   */
+  colorPalette?: ColorPaletteName,
+  /**
+   * Appearance of the tags (badges).
+   * @default 'circle'
+   */
+  appearance?: 'square' | 'circle',
+  /**
+   * Maximum number of tags to show before displaying "+N more".
+   */
+  maxItems?: number,
+}
+
+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 | undefined
+   * - Multiple selection: T[]
+   */
+  value: Multiple extends true ? T[] : (T | undefined),
+  /**
+   * Callback fired when the value changes (user selects/removes an option).
+   * This is the main callback for getting the final selected value(s).
+   * 
+   * @example
+   * ```tsx
+   * // Single selection
+   * <Autocomplete
+   *   value={user}
+   *   onChange={(selectedUser) => {
+   *     console.log('Selected:', selectedUser)
+   *     setUser(selectedUser)
+   *   }}
+   * />
+   * 
+   * // Multiple selection
+   * <Autocomplete
+   *   multiple
+   *   value={selectedUsers}
+   *   onChange={(users) => {
+   *     console.log('Selected users:', users)
+   *     setSelectedUsers(users)
+   *   }}
+   * />
+   * ```
+   */
+  onChange: Multiple extends true ? (value: T[]) => void : (value: T | undefined) => 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.
+   * Used when creatable is true and onCreate is NOT defined.
+   * Allows automatic option creation on Enter key.
+   * 
+   * Note: This prop has no effect when onCreate is defined, as onCreate takes precedence.
+   * 
+   * @param inputValue - The text typed by the user
+   * @returns A new option object
+   * 
+   * @example
+   * ```tsx
+   * // Auto-create tags on Enter
+   * <Autocomplete
+   *   multiple
+   *   creatable
+   *   freeSolo
+   *   getOptionFromInput={(text) => ({
+   *     id: Date.now(),
+   *     name: text,
+   *     isCustom: true
+   *   })}
+   * />
+   * ```
+   */
+  getOptionFromInput?: (inputValue: string) => T,
+  /**
+   * The input value (controlled mode).
+   * Use this when you need full control over the input text.
+   * Usually used with onInputChange for controlled components.
+   * 
+   * @example
+   * ```tsx
+   * const [inputValue, setInputValue] = useState('')
+   * 
+   * <Autocomplete
+   *   inputValue={inputValue}
+   *   onInputChange={setInputValue}
+   *   options={options}
+   * />
+   * ```
+   */
+  inputValue?: string,
+  /**
+   * Callback fired when the input text changes (user types).
+   * Use this to control the input value or perform side effects like API calls.
+   * Different from onChange which fires when an option is selected.
+   * 
+   * @param value - The current text in the input field
+   * 
+   * @example
+   * ```tsx
+   * // Debounced API search
+   * <Autocomplete
+   *   onInputChange={(text) => {
+   *     console.log('User typed:', text)
+   *     debouncedSearch(text)
+   *   }}
+   * />
+   * 
+   * // Controlled input
+   * <Autocomplete
+   *   inputValue={inputValue}
+   *   onInputChange={(text) => setInputValue(text.toUpperCase())}
+   * />
+   * ```
+   */
+  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 | undefined,
+  /**
+   * A function to render an option in the dropdown.
+   */
+  renderOption?: (option: T) => React.ReactNode,
+  /**
+   * Custom function to render the selected values display area in multiple mode.
+   * When defined, gives you full control over how selected values are displayed.
+   * The customSelectedTags prop has no effect when this is defined.
+   * 
+   * @param values - Array of selected options
+   * @param onRemove - Function to call when user wants to remove an option
+   * @returns React element to display selected values
+   * 
+   * @example
+   * ```tsx
+   * <Autocomplete
+   *   multiple
+   *   renderSelected={(values, onRemove) => (
+   *     <div style={{ display: 'flex', gap: '4px', flexWrap: 'wrap' }}>
+   *       {values.map(user => (
+   *         <div key={user.id} style={{ background: '#e3f2fd', padding: '4px 8px', borderRadius: '12px' }}>
+   *           <Avatar src={user.avatar} size="xs" />
+   *           {user.name}
+   *           <button onClick={() => onRemove(user)}>×</button>
+   *         </div>
+   *       ))}
+   *     </div>
+   *   )}
+   * />
+   * ```
+   */
+  renderSelected?: (values: T[], onRemove: (option: T) => void) => React.ReactElement,
+  /**
+   * Configuration for the default selected tags appearance in multiple mode.
+   * Has no effect when renderSelected is defined.
+   * 
+   * @example
+   * ```tsx
+   * <Autocomplete
+   *   multiple
+   *   customSelectedTags={{
+   *     colorScheme: 'primary',
+   *     appearance: 'square',
+   *     maxItems: 3
+   *   }}
+   * />
+   * ```
+   */
+  customSelectedTags?: CustomSelectedTagsConfig,
+  /**
+   * Custom filter function for options.
+   * When not set, the filter will use the text returned by renderLabel (case-insensitive includes).
+   * 
+   * @param options - The full list of options
+   * @param inputValue - The current input text
+   * @returns Filtered array of options
+   * 
+   * @example
+   * ```tsx
+   * // Search by name OR email
+   * <Autocomplete
+   *   filterOptions={(options, input) =>
+   *     options.filter(user =>
+   *       user.name.toLowerCase().includes(input.toLowerCase()) ||
+   *       user.email.toLowerCase().includes(input.toLowerCase())
+   *     )
+   *   }
+   * />
+   * ```
+   */
+  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,
+  /**
+   * 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.
+   * When false, the input keeps the text after selection, useful for adding multiple similar items quickly.
+   * 
+   * Note: Adding multiple tags with similar prefixes when clearOnSelect={false}, you can select "React", 
+   * then easily select "React Native" 
+   * without retyping "React" from scratch
+   * @default true (for multiple mode)
+   * 
+   * @example
+   * ```tsx
+   * // Clear input after each selection (default)
+   * <Autocomplete multiple clearOnSelect />
+   * 
+   * // Keep input text after selection
+   * const [tags, setTags] = useState<Tag[]>([])
+   * 
+   * <Autocomplete
+   *   multiple
+   *   clearOnSelect={false}
+   *   value={tags}
+   *   onChange={setTags}
+   *   options={availableTags}
+   *   renderLabel={tag => tag.name}
+   * />
+   * ```
+   */
+  clearOnSelect?: boolean,
+  /**
+   * If true, the popup will open on input focus.
+   * @default true
+   */
+  openOnFocus?: boolean,
+  /**
+   * 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 autocomplete component.
+   * Applies the theme's color scheme to the component root.
+   */
+  colorScheme?: ColorSchemeName,
+  /**
+   * The id attribute for the input element.
+   * Useful for associating with a label element.
+   */
+  id?: string,
+}
+
+export type AutocompleteProps<T, Multiple extends boolean = false> =
+  Omit<React.JSX.IntrinsicElements['div'], 'ref' | 'onChange'> &
+  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,
+    renderSelected,
+    customSelectedTags,
+    filterOptions,
+    loading = false,
+    disabled = false,
+    placeholder,
+    maxHeight,
+    autoHighlight = false,
+    clearOnSelect = multiple,
+    openOnFocus = true,
+    noOptionsText,
+    loadingText,
+    onScrollEnd,
+    scrollEndMargin = 200,
+    colorScheme,
+    id,
+    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 isNavigatingWithKeyboard = useRef(false)
+    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(() => {
+      if (!multiple && value && renderLabel(value as T) === inputValue) {
+        return options
+      }
+      return filter(options, inputValue)
+    }, [options, inputValue, filter, multiple, value, renderLabel])
+
+    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 (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, clearOnSelect, setInputValue, renderLabel])
+
+    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)
+        
+        if (autoHighlight && filteredOptions.length > 0) {
+          setHighlightedIndex(0)
+        }
+      }
+    }
+
+    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)
+          }
+        }
+      } else if (!multiple && inputValue) {
+        const exactMatch = options.find(o =>
+          renderLabel(o).toLowerCase() === inputValue.toLowerCase(),
+        )
+        
+        if (exactMatch) {
+          handleSelect(exactMatch)
+        } else {
+          if (value) {
+            setInputValue(renderLabel(value as T))
+          } else {
+            setInputValue('')
+          }
+        }
+      }
+    }
+
+    const handleCreateNewOption = useCallback(() => {
+      if (!inputValue.trim()) return false
+
+      if (onCreate) {
+        handleCreate()
+        return true
+      }
+
+      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)
+        }
+        return true
+      }
+
+      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)
+        }
+        return true
+      }
+
+      return false
+    }, [onCreate, handleCreate, freeSolo, getOptionFromInput, inputValue, multiple, value, renderKey, onChange, setInputValue, renderLabel])
+
+    const handleEnterKey = useCallback(() => {
+      if (open && highlightedIndex >= 0 && filteredOptions[highlightedIndex]) {
+        handleSelect(filteredOptions[highlightedIndex])
+        return
+      }
+
+      if (!open && filteredOptions.length === 1) {
+        handleSelect(filteredOptions[0])
+        return
+      }
+
+      if (creatable && handleCreateNewOption()) {
+        return
+      }
+
+      if (freeSolo && inputValue && !multiple) {
+        const exactMatch = options.find(o =>
+          renderLabel(o).toLowerCase() === inputValue.toLowerCase(),
+        )
+        if (exactMatch) {
+          handleSelect(exactMatch)
+        }
+      }
+    }, [
+      open,
+      highlightedIndex,
+      filteredOptions,
+      handleSelect,
+      creatable,
+      handleCreateNewOption,
+      freeSolo,
+      inputValue,
+      multiple,
+      options,
+      renderLabel,
+    ])
+
+    const handleKeyDown = (e: React.KeyboardEvent) => {
+      if (disabled) return
+
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault()
+          isNavigatingWithKeyboard.current = true
+          if (!open) {
+            setOpen(true)
+            setHighlightedIndex(0)
+          } else {
+            setHighlightedIndex(prev =>
+              prev < filteredOptions.length - 1 ? prev + 1 : prev,
+            )
+          }
+          break
+
+        case 'ArrowUp':
+          e.preventDefault()
+          isNavigatingWithKeyboard.current = true
+          if (open) {
+            setHighlightedIndex(prev => prev > 0 ? prev - 1 : 0)
+          }
+          break
+
+        case 'Enter':
+          e.preventDefault()
+          handleEnterKey()
+          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)
+          } else if (!multiple && !inputValue && value) {
+            (onChange as (value: T | null) => void)(null)
+          }
+          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()
+      }
+    }
+
+    const handleFocusAndOpen = () => {
+      if (disabled) return
+      setFocused(true)
+      inputRef.current?.focus()
+      if (openOnFocus) {
+        setOpen(true)
+      }
+    }
+
+    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[]
+
+      if (renderSelected) {
+        return renderSelected(tags, handleRemoveTag)
+      }
+
+      const config = customSelectedTags || {}
+      const maxItems = config.maxItems
+      const visibleTags = maxItems && tags.length > maxItems
+        ? tags.slice(0, maxItems)
+        : tags
+      const remainingCount = maxItems && tags.length > maxItems
+        ? tags.length - maxItems
+        : 0
+
+      return (
+        <>
+          {visibleTags.map(tag => (
+            <Badge
+              key={renderKey(tag)}
+              colorScheme={config.colorScheme}
+              colorPalette={config.colorPalette}
+              appearance={config.appearance || 'circle'}
+            >
+              {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={config.colorScheme}
+              colorPalette={config.colorPalette}
+              appearance={config.appearance || 'circle'}
+            >
+              +{remainingCount}
+            </Badge>
+          )}
+        </>
+      )
+    }
+
+    const showClearButton = !disabled && (
+      (!multiple && value !== null) ||
+      (multiple && (value as T[]).length > 0)
+    )
+
+    return (
+      <CitricComponent
+        tag="div"
+        component="autocomplete"
+        colorScheme={colorScheme}
+        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
+          tabIndex={disabled ? undefined : 0}
+          onClick={handleFocusAndOpen}
+          onFocus={handleFocusAndOpen}
+          onKeyDown={handleKeyDown}
+        >
+          <Row gap="4px" className="input-container">
+            {multiple && renderTags()}
+            <input
+              ref={inputRef}
+              id={id}
+              type="text"
+              value={inputValue}
+              onChange={(e) => handleInputChange(e.target.value)}
+              onFocus={handleFocus}
+              onBlur={handleBlur}
+              disabled={disabled}
+              placeholder={(multiple && (value as T[]).length > 0) ? '' : placeholder}
+              tabIndex={disabled ? undefined : 0}
+              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()
+                  e.preventDefault()
+                  handleClear()
+                }}
+                onMouseDown={(e) => {
+                  e.stopPropagation()
+                  e.preventDefault()
+                }}
+                onFocus={(e) => {
+                  e.stopPropagation()
+                }}
+                disabled={disabled}
+                aria-label={t.clear}
+                tabIndex={0}
+                style={{ width: '12px', height: '12px' }}
+              />
+            )}
+            <IconButton
+              icon={open ? 'ChevronUp' : 'ChevronDown'}
+              appearance="none"
+              size="md"
+              type="button"
+              onClick={(e) => {
+                e.stopPropagation()
+                e.preventDefault()
+                setOpen((prev) => !prev)
+              }}
+              onMouseDown={(e) => {
+                e.stopPropagation()
+                e.preventDefault()
+              }}
+              onFocus={(e) => {
+                e.stopPropagation()
+              }}
+              disabled={disabled}
+              aria-label={open ? t.collapse : t.expand}
+              tabIndex={0}
+              style={{ width: '12px', height: '12px' }}
+            />
+          </div>
+        </header>
+
+        <div
+          className="dropdown-panel"
+          ref={dropdownRef}
+          id="autocomplete-listbox"
+          role="listbox"
+          aria-hidden={!open}
+          onMouseMove={() => {
+            isNavigatingWithKeyboard.current = false
+          }}
+          {...(open ? {} : { inert: 'true' })}
+        >
+          {loading && !filteredOptions.length ? (
+            <div className="message">{loadingText || t.loading}</div>
+          ) : filteredOptions.length === 0 && !showCreateOption && !freeSolo ? (
+            <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={() => {
+                    if (!isNavigatingWithKeyboard.current) {
+                      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}"',
+  },
+}