Documentación del Sistema

Appearance

Mejoras de Usabilidad del Componente AutoComplete ​

Módulo: frontend-shared Tipo: Feature Componente: AutoComplete Fecha: 2025-12-19 Estado: Implementado

Resumen ​

Se implementaron mejoras de usabilidad en el componente AutoComplete de React para optimizar la velocidad de captura de datos y reducir las interacciones del usuario necesarias para seleccionar resultados.

Beneficios principales:

  • 🚀 50% reducción en interacciones con resultado único
  • ⌨️ Selección con tecla Tab además de Enter
  • ✨ Auto-selección inteligente de resultados únicos

Contexto del Negocio ​

Problema Identificado ​

El componente AutoComplete requería que los usuarios realizaran múltiples pasos innecesarios para seleccionar resultados:

  1. Con un solo resultado: El usuario debía presionar flecha abajo para resaltar el resultado y luego Enter para seleccionarlo, incluso cuando era el único resultado disponible.

  2. Selección con Tab: La tecla Tab solo movía el foco al siguiente campo sin seleccionar el resultado resaltado, obligando a los usuarios a usar Enter exclusivamente.

Impacto en el Negocio ​

  • ❌ Ralentización en la captura de datos
  • ❌ Más interacciones de teclado requeridas
  • ❌ Experiencia de usuario menos fluida
  • ❌ Inconsistencia con patrones de UI modernos
  • ❌ Mayor fatiga en operadores de datos

Requerimientos de Negocio ​

RN-01: Selección con Tecla Tab ​

Descripción: El usuario debe poder seleccionar la opción resaltada en el dropdown presionando la tecla Tab.

Comportamiento Anterior:

  • Tab movía el foco al siguiente campo
  • No seleccionaba el resultado resaltado
  • Obligaba al usuario a usar solo Enter

Comportamiento Nuevo:

  • Tab selecciona el ítem resaltado/activo en el dropdown
  • Si no hay ítem explícitamente resaltado, selecciona el primero de la lista
  • Después de seleccionar, permite continuar con el flujo normal

Justificación de Negocio:

  • Mejorar velocidad de captura de datos en formularios extensos
  • Reducir cambios entre mouse y teclado
  • Alinear con patrones de UI modernos que los usuarios esperan
  • Disminuir fatiga en operadores que procesan muchos formularios

RN-02: Auto-selección con Único Resultado ​

Descripción: Cuando el autocomplete retorna un solo resultado, presionar Enter o Tab debe seleccionarlo automáticamente.

Comportamiento Anterior:

  • Usuario debía presionar flecha abajo para resaltar
  • Luego presionar Enter para seleccionar
  • Total: 2 interacciones adicionales innecesarias

Comportamiento Nuevo:

  • Si hay un solo resultado visible
  • Y el usuario presiona Enter o Tab
  • Entonces selecciona automáticamente ese único resultado
  • Sin necesidad de navegación previa

Justificación de Negocio:

  • Eliminar pasos innecesarios cuando el resultado es obvio
  • Optimizar flujos de captura rápida (por ejemplo: búsqueda de clientes frecuentes)
  • Reducir fatiga en operadores de datos
  • Mejorar eficiencia en procesos repetitivos

Reglas de Negocio ​

RB-01: Condiciones para Auto-selección ​

  • Solo se activa cuando hay exactamente 1 resultado
  • El resultado debe estar visible en el dropdown
  • No debe haber un ítem previamente seleccionado
  • Funciona tanto con Enter como con Tab
  • La auto-selección es inmediata, sin confirmación adicional

RB-02: Condiciones para Selección con Tab ​

  • Se activa cuando hay resultados disponibles (1 o más)
  • El dropdown debe estar abierto y visible
  • No debe haber un ítem previamente seleccionado
  • Si hay un ítem resaltado por navegación con flechas, selecciona ese
  • Si no hay ítem resaltado, selecciona el primero como fallback
  • No interfiere con Tab cuando no hay resultados

RB-03: Preservación de Funcionalidad Existente ​

  • La funcionalidad de Enter se mantiene sin cambios
  • La navegación con flechas continúa funcionando normalmente
  • Escape sigue cerrando el dropdown sin seleccionar
  • El comportamiento con mouse no se ve afectado
  • Compatible con configuraciones existentes de dataMapping y queryParams

Casos de Uso ​

CU-01: Búsqueda con Resultado Único ​

Actor: Operador de datos / Usuario de formularios

Precondiciones:

  • Formulario con campo AutoComplete visible
  • Usuario tiene datos para buscar

Flujo Principal:

  1. Usuario hace clic en el campo AutoComplete
  2. Usuario escribe término de búsqueda (ej: "Juan")
  3. Sistema busca y retorna 1 solo resultado coincidente
  4. Sistema muestra el único resultado en el dropdown
  5. Usuario presiona Tab (o Enter)
  6. Sistema selecciona automáticamente el resultado
  7. Usuario continúa con el siguiente campo del formulario

Flujo Alternativo (comportamiento anterior): 1-4. (Igual que flujo principal) 5. Usuario presiona flecha abajo 6. Usuario presiona Enter 7. Usuario continúa con el siguiente campo

Postcondiciones:

  • El resultado se ha seleccionado correctamente
  • El valor se refleja en el campo
  • El formulario está listo para el siguiente campo

Beneficio Medible: Reducción de 4 a 2 interacciones de teclado (50% menos pasos)

CU-02: Búsqueda con Múltiples Resultados ​

Actor: Operador de datos / Usuario de formularios

Precondiciones:

  • Formulario con campo AutoComplete visible
  • Existen múltiples opciones coincidentes

Flujo Principal:

  1. Usuario escribe en el autocomplete
  2. Sistema busca y retorna múltiples resultados
  3. Sistema muestra dropdown con todos los resultados
  4. Usuario navega con flechas (↑↓) al resultado deseado
  5. Usuario presiona Tab (o Enter)
  6. Sistema selecciona el resultado resaltado
  7. Usuario continúa con el siguiente campo

Flujo Alternativo A (Sin navegación con flechas): 1-3. (Igual que flujo principal) 4. Usuario presiona Tab directamente 5. Sistema selecciona el primer resultado como fallback 6. Usuario continúa o corrige la selección si no era el deseado

Postcondiciones:

  • Un resultado ha sido seleccionado
  • El formulario está listo para continuar

Beneficio: Flexibilidad para usar Tab en lugar de solo Enter, acelerando el flujo de trabajo

CU-03: Sin Resultados ​

Actor: Operador de datos

Flujo Principal:

  1. Usuario escribe en el autocomplete
  2. Sistema busca pero no encuentra coincidencias
  3. Sistema muestra mensaje "Sin coincidencias"
  4. Usuario presiona Tab
  5. Sistema mueve el foco al siguiente campo normalmente
  6. No se selecciona ningún valor (campo queda vacío)

Beneficio: Tab funciona como se espera cuando no hay resultados, sin interferir con la navegación normal

Criterios de Aceptación ​

✅ CA-01: Auto-selección con Resultado Único ​

  • [x] DADO que hay 1 solo resultado en el autocomplete
  • [x] CUANDO el usuario presiona Enter
  • [x] ENTONCES el resultado se selecciona automáticamente sin necesidad de navegación previa

✅ CA-02: Auto-selección con Tab y Resultado Único ​

  • [x] DADO que hay 1 solo resultado en el autocomplete
  • [x] CUANDO el usuario presiona Tab
  • [x] ENTONCES el resultado se selecciona automáticamente y el foco puede moverse

✅ CA-03: Selección con Tab (Múltiples Resultados) ​

  • [x] DADO que hay múltiples resultados en el autocomplete
  • [x] Y el usuario ha navegado a un resultado con las flechas
  • [x] CUANDO el usuario presiona Tab
  • [x] ENTONCES se selecciona el ítem resaltado
  • [x] NOTA: Si no hay navegación previa, selecciona el primer resultado

✅ CA-04: No Interferir con Navegación Normal ​

  • [x] DADO que el autocomplete no tiene resultados
  • [x] CUANDO el usuario presiona Tab
  • [x] ENTONCES el foco se mueve al siguiente campo normalmente
  • [x] Y no se selecciona ningún valor

✅ CA-05: Prevención de Doble Selección ​

  • [x] DADO que ya hay un ítem seleccionado en el autocomplete
  • [x] CUANDO el usuario presiona Tab o Enter
  • [x] ENTONCES no se ejecuta la lógica de auto-selección
  • [x] Y el comportamiento es el normal para un campo ya completado

✅ CA-06: Compatibilidad con Enter ​

  • [x] DADO cualquier escenario de uso
  • [x] CUANDO el usuario presiona Enter
  • [x] ENTONCES el comportamiento es consistente con Tab
  • [x] Y ambas teclas funcionan de manera equivalente

Impacto en Módulos ​

Módulos que usan AutoComplete ​

Este componente se usa extensivamente en todo el sistema. Las mejoras benefician a:

  • ✅ Ventas: Búsqueda de clientes, productos
  • ✅ Compras: Búsqueda de proveedores, artículos
  • ✅ Tesorería: Selección de conceptos, cuentas bancarias
  • ✅ Contabilidad: Búsqueda de cuentas contables, imputaciones
  • ✅ CRM: Búsqueda de contactos, empresas
  • ✅ Stock: Selección de artículos, ubicaciones
  • ✅ Todas las ABM: Cualquier formulario con búsqueda por autocomplete

Impacto estimado: Mejora en la productividad de todos los usuarios que usan formularios del sistema.

Historial de Cambios ​

2025-12-19 - Implementación Inicial ​

  • ✅ Implementados requerimientos RN-01 y RN-02
  • ✅ Validadas todas las reglas de negocio (RB-01, RB-02, RB-03)
  • ✅ Todos los criterios de aceptación cumplidos
  • ✅ Build de producción exitoso
  • ✅ 21 tests automatizados pasando (1 skipped por limitación técnica de testing)
  • ✅ Validación manual exitosa en navegador

Archivos modificados:

  • ts/core/components/form/AutoComplete.tsx
  • tests/unit/core/components/AutoComplete.test.tsx

Documentación técnica: Ver Frontend/Components/Autocomplete

Conclusión ​

Las mejoras de usabilidad implementadas optimizan significativamente la experiencia del usuario al:

  • Reducir en 50% las interacciones necesarias para seleccionar resultados únicos
  • Permitir uso de Tab para selección, acelerando el flujo de trabajo
  • Eliminar pasos innecesarios en flujos repetitivos
  • Mantener total compatibilidad con funcionalidad existente
  • Mejorar la productividad de operadores de datos

La funcionalidad está implementada, testeada y lista para uso en producción.