initial: mirror of @fn_library from fn_registry

75 components + DESIGN_SYSTEM.md + sync script. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-21 19:06:49 +02:00
commit 5a824c2eee
157 changed files with 11539 additions and 0 deletions
@@ -0,0 +1,136 @@
+---
+name: autocomplete
+kind: component
+lang: ts
+domain: ui
+version: "1.0.0"
+purity: impure
+signature: "Autocomplete(props: AutocompleteProps): JSX.Element"
+description: "Input con sugerencias de autocompletado. Permite valores libres a diferencia de Select. Wrapper sobre Mantine Autocomplete."
+tags: [autocomplete, input, form, suggestions, component, ui, interactive, mantine]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: ["@mantine/core"]
+output: "Componente Autocomplete que renderiza input con dropdown de sugerencias filtradas"
+props:
+  - name: data
+    type: "string[] | { value: string; label?: string; group?: string }[]"
+    required: true
+    description: "Lista de opciones a mostrar en el dropdown"
+  - name: value
+    type: "string"
+    required: false
+    description: "Valor controlado del input"
+  - name: onChange
+    type: "(value: string) => void"
+    required: false
+    description: "Callback al cambiar el valor del input"
+  - name: label
+    type: "string"
+    required: false
+    description: "Etiqueta visible encima del input"
+  - name: placeholder
+    type: "string"
+    required: false
+    description: "Texto placeholder cuando el input está vacío"
+  - name: clearable
+    type: "boolean"
+    required: false
+    description: "Muestra botón para limpiar el valor"
+  - name: loading
+    type: "boolean"
+    required: false
+    description: "Muestra spinner de carga en el input"
+  - name: disabled
+    type: "boolean"
+    required: false
+    description: "Deshabilita el input"
+  - name: limit
+    type: "number"
+    required: false
+    description: "Número máximo de sugerencias a mostrar en el dropdown"
+  - name: size
+    type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'"
+    required: false
+    description: "Tamaño visual del input"
+emits: [onChange]
+has_state: true
+framework: react
+tested: false
+tests: []
+test_file_path: ""
+file_path: "frontend/functions/ui/autocomplete.tsx"
+---
+
+## Ejemplo
+
+```tsx
+import { Autocomplete } from '@fn_library/autocomplete'
+
+// Básico — lista de strings
+function BasicAutocomplete() {
+  return (
+    <Autocomplete
+      label="País"
+      placeholder="Escribe para buscar..."
+      data={['Argentina', 'Brasil', 'Chile', 'Colombia', 'Uruguay']}
+    />
+  )
+}
+
+// Con grupos
+function GroupedAutocomplete() {
+  return (
+    <Autocomplete
+      label="Ciudad"
+      placeholder="Selecciona una ciudad"
+      data={[
+        { value: 'Buenos Aires', group: 'Argentina' },
+        { value: 'Rosario', group: 'Argentina' },
+        { value: 'São Paulo', group: 'Brasil' },
+        { value: 'Río de Janeiro', group: 'Brasil' },
+      ]}
+      limit={5}
+    />
+  )
+}
+
+// Con loading y clearable (búsqueda asíncrona)
+function AsyncAutocomplete() {
+  const [value, setValue] = useState('')
+  const [data, setData] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+
+  const handleChange = async (val: string) => {
+    setValue(val)
+    if (val.length < 2) return
+    setLoading(true)
+    const results = await fetchSuggestions(val)
+    setData(results)
+    setLoading(false)
+  }
+
+  return (
+    <Autocomplete
+      label="Búsqueda"
+      placeholder="Escribe al menos 2 caracteres..."
+      value={value}
+      onChange={handleChange}
+      data={data}
+      loading={loading}
+      clearable
+    />
+  )
+}
+```
+
+## Notas
+
+A diferencia de `Select`, `Autocomplete` permite que el usuario ingrese cualquier valor libre, no solo los de la lista. Ideal para búsquedas con sugerencias donde el valor final puede no estar en el dataset.
+
+Cuando `data` contiene objetos con `group`, el dropdown agrupa visualmente las opciones bajo el encabezado del grupo.
+
+El prop `limit` controla cuántas sugerencias se muestran simultáneamente (por defecto Mantine muestra todas). Útil para datasets grandes o búsquedas asíncronas donde se quiere limitar el ruido visual.