Command Search Overlay

Este componente ofrece una búsqueda rápida en una capa sobre la página, para encontrar destinos, contenidos o acciones sin salir del contexto actual. Es útil cuando se abre con un atajo o un ícono y conviene mostrar sugerencias al instante.

No es un bloque propio del kit: combina Dialog (--command-search), Searchbar (--sm --fluid) e Item List (--compact --dense). El kit define el diseño del panel; la aplicación se encarga de abrir y cerrar, filtrar los resultados, resaltar coincidencias y navegar con teclado.

Propiedades y configuraciones

• Úsalo para localizar componentes, trámites, contenidos o comandos sin recorrer menús.
• Úsalo cuando conviene mostrar sugerencias mientras la persona escribe. Para una búsqueda simple siempre visible, usa Searchbar en el header o en el contenido.
• Si coexiste con el searchbar del header, define roles claros: uno puede abrir este overlay y el otro resolver una búsqueda en línea.
• Muestra pocas sugerencias, las más relevantes, con título y descripción breve. Cierra la lista con una opción para ver todos los resultados del término buscado.
• Conserva la consulta en el campo mientras se muestran resultados para que la persona pueda corregir o afinar.
• Ofrece siempre una salida evidente: botón cerrar, Escape y cierre del <dialog>.
• El panel no define estados vacíos propios: la aplicación debe mostrar “sin resultados”, “cargando” o una sugerencia de corrección dentro de .cl-dialog__body.
• No lo uses como formulario ni como flujo largo: el overlay sirve para encontrar y saltar a otro destino.

Buenas prácticas

Recomendado: Sugiere resultados relevantes y con contexto

Muestra solo los destinos más probables y acompaña cada título con contexto, como tipo de contenido o institución.

Recomendado: Conserva la consulta mientras muestra resultados

Deja el término escrito en el buscador junto a la lista de resultados. Así la persona puede corregir o precisar sin partir de cero.

Recomendado: Prioriza los resultados más probables

Ordena primero las coincidencias exactas, recientes o más usadas. El overlay debe ayudar a saltar rápido, no obligar a leer una lista completa.

Recomendado: Distingue destinos, contenidos y acciones

Si mezclas páginas, componentes o acciones, usa la descripción para indicar qué es cada resultado y qué ocurrirá al seleccionarlo.

Malas prácticas

No recomendado: No llenes el overlay con demasiados resultados

Una lista larga obliga a recorrer el overlay como si fuera una página de resultados. Muestra sugerencias y ofrece ver todos.

No recomendado: No muestres resultados sin contexto

Resultados con el mismo título y sin descripción obligan a abrir cada uno para saber cuál es el correcto.

No recomendado: No lo uses para capturar datos de un trámite

RUT, folio o datos personales pertenecen a un formulario con label, ayuda y validación, no a una búsqueda de comandos.

No recomendado: No metas flujos largos dentro del panel

El overlay interrumpe el contexto. No lo uses para completar pasos, editar datos o resolver tareas que necesitan una pantalla completa.

• Usa <dialog> con showModal() para obtener modal nativo (backdrop, Escape y atrape de foco gratis).
• Da nombre accesible al diálogo, por ejemplo aria-label="Buscar componentes".
• El input funciona como combobox: aria-expanded, aria-controls, aria-autocomplete="list" y aria-activedescendant mientras se recorren las opciones con flechas.
• Los resultados forman un role="listbox" de role="option"; el foco de teclado permanece en el input mientras las flechas mueven el resaltado visual (aria-selected + estado ._focus).
• El botón de cierre necesita aria-label; su ícono va con aria-hidden="true".
• Al cerrar el panel, devuelve el foco al control que lo abrió.
• Sigue el patrón combobox + listbox de WAI-ARIA APG: evita anunciar doble semántica de lista (usa <li role="presentation"> alrededor de cada role="option").