AutocompleteField

AutocompleteField renderiza un input de texto que debouncea la entrada del usuario y consulta una API remota para mostrar las opciones coincidentes en un popover. Soporta selección simple y múltiple (mostrada como pills), navegación por teclado (flechas + Enter) y un botón de creación opcional que abre un modal de formulario para agregar nuevos registros.

Props

| Prop | Tipo | Requerido | Por defecto | Descripción | |------|------|-----------|-------------|-------------| | apiBaseUrl | string | Sí | — | URL base de la API usada para las requests de búsqueda. | | searchPath | string | Sí | — | Ruta para las requests de búsqueda (ej. /v1/products). | | value | any \| any[] | No | '' / [] | Valor(es) seleccionado(s). Pasar un array cuando multiple es true. | | onChange | (selectedValue: any \| any[]) => void | Sí | — | Llamado con la nueva selección en cada cambio. | | label | string | No | — | Etiqueta mostrada sobre el input. | | description | string | No | — | Texto de ayuda mostrado debajo del componente. | | options | { [key: string]: any }[] | No | [] | Opciones estáticas de respaldo (mostradas cuando el término de búsqueda está vacío). | | multiple | boolean | No | false | Permite seleccionar más de un item. Los items seleccionados se muestran como pills. | | placeholder | string | No | 'Escriba para buscar...' | Texto placeholder del input de búsqueda. | | useAuthToken | boolean | No | true | Si se adjunta el token de auth a las requests de búsqueda. | | searchParam | string | No | — | Clave del query-string para el término de búsqueda. Si se omite, el término se añade como segmento de ruta. | | noResultsText | string | No | 'No results found' | Texto mostrado en el popover cuando la búsqueda no devuelve resultados. | | searchingText | string | No | 'Searching...' | Texto mostrado en el popover mientras la request está en vuelo. | | itemLabelKey | string | No | 'name' | Clave del resultado usada como etiqueta de visualización. | | itemDescriptionKey | string | No | — | Clave del resultado usada como descripción secundaria. | | itemImageKey | string | No | — | Clave del resultado usada como URL de imagen (avatar pequeño). | | itemLabelStyle | React.CSSProperties | No | — | Estilos de la etiqueta dentro de cada opción. | | itemDescriptionStyle | React.CSSProperties | No | — | Estilos de la descripción dentro de cada opción. | | itemImageStyle | React.CSSProperties | No | — | Estilos del avatar dentro de cada opción. | | allowCreate | boolean | No | false | Muestra un botón para abrir el modal de creación. | | createPath | string | No | — | Ruta API usada por el formulario de creación (POST). | | formFields | Field[] | No | [] | Definiciones de campos para el modal de creación. | | formTitle | string | No | 'Crear nuevo registro' | Título del modal de creación. | | formButtonTitle | string | No | 'Crear nuevo' | Etiqueta del botón de envío en el modal de creación. | | formWidth | number \| string | No | 500 | Ancho del modal de creación. | | onCreateSuccess | (newRecord: any) => void | No | — | Llamado tras crear un registro exitosamente. | | onCreateError | (error: any) => void | No | — | Llamado cuando la request de creación falla. | | createButtonType | 'solid' \| 'clear' \| 'outline' | No | 'solid' | Estilo visual del botón de creación. | | createButtonSize | 'sm' \| 'md' \| 'lg' | No | 'sm' | Tamaño del botón de creación. | | createButtonColor | string | No | themeColors.light | Color del botón de creación. | | createButtonIcon | string | No | 'add' | Nombre del ícono del botón de creación. | | containerStyle | React.CSSProperties | No | {} | Estilos del div contenedor raíz. | | labelStyle | React.CSSProperties | No | {} | Estilos del elemento de etiqueta. | | descriptionStyle | React.CSSProperties | No | {} | Estilos del párrafo de descripción. | | popoverStyle | React.CSSProperties | No | {} | Estilos del div interior del popover de resultados. |

Uso

Selección simple básica

import React, { useState } from 'react';
import AutocompleteField from '@/components/fields/AutocompleteField';

export default function Example() {
  const [product, setProduct] = useState(null);

  return (
    <AutocompleteField
      label="Producto"
      apiBaseUrl="https://api.example.com"
      searchPath="/v1/products"
      searchParam="search"
      value={product}
      onChange={setProduct}
      itemLabelKey="name"
    />
  );
}

Selección múltiple con avatar

<AutocompleteField
  label="Asignar usuarios"
  apiBaseUrl="https://api.example.com"
  searchPath="/v1/users"
  searchParam="q"
  multiple={true}
  value={selectedUsers}
  onChange={setSelectedUsers}
  itemLabelKey="full_name"
  itemDescriptionKey="email"
  itemImageKey="avatar_url"
/>

Con modal de creación

<AutocompleteField
  label="Categoría"
  apiBaseUrl="https://api.example.com"
  searchPath="/v1/categories"
  searchParam="search"
  value={category}
  onChange={setCategory}
  allowCreate={true}
  createPath="/v1/categories"
  formTitle="Nueva categoría"
  formFields={[{ type: 'text', name: 'name', label: 'Nombre' }]}
  onCreateSuccess={(rec) => console.log('Creado', rec)}
/>