composable · v0.8.0

useKeyboardNav

Gestiona atajos de teclado a nivel de app/página. Acepta una lista de shortcuts con modifier + handler + label, y proporciona la lista para renderizar un panel de ayuda. No interfiere con foco en form fields.

Demo

Atajos activos

Pulsa cualquier combinación de abajo (asegúrate de tener el foco fuera de cualquier input).

  • alt+1 Ir a Hero ×0
  • alt+2 Ir a Proyectos ×0
  • alt+3 Ir a Contacto ×0
  • Escape Cerrar diálogos ×0

Últimas pulsaciones detectadas

— ningún atajo disparado todavía —

Verifica que NO dispara con foco editable

Haz click en este input y prueba a pulsar Alt+1 — no debería disparar el handler porque el foco está en un form field.

Uso

app.svelte
<script>
  import { useKeyboardNav } from '@codigosinsiesta/theme';

  const nav = useKeyboardNav([
    { key: '1', modifier: 'alt', label: 'Ir a Hero',  handler: () => scrollTo('#hero')     },
    { key: 'a', modifier: 'alt', label: 'Panel a11y', handler: openA11y                       },
    { key: 'Escape',             label: 'Cerrar',     handler: closeAll                       }
  ]);
</script>

<ul aria-label="Atajos de teclado">
  {#each nav.shortcuts as s}
    <li><kbd>{s.modifier ? s.modifier + '+' : ''}{s.key}</kbd> — {s.label}</li>
  {/each}
</ul>

API

Acepta literal array o getter (mismo patrón polimórfico que useCounterAnimation.isActive):

reactivo · getter
let shortcuts = $state([...]);
const nav = useKeyboardNav(() => shortcuts); // se reasigna cuando el array cambia
Shortcut fieldTipoDefaultDescripción
keystring—Tecla: 'a', '1', 'Escape', 'ArrowLeft'… (case-insensitive para letras).
modifierstringundefined'alt' | 'ctrl' | 'shift' | 'meta' o combinaciones tipo 'altShift', 'ctrlShift'.
labelstring—Descripción legible para panel de ayuda.
handler(e: KeyboardEvent) => void—Función a ejecutar al matchear.
preventDefaultbooleantrueLlama a e.preventDefault() antes del handler.
forceTriggerbooleanfalseSi true, dispara también con foco en input/textarea/contenteditable. Útil para Escape.

Devuelve:

FieldTipoDescripción
shortcutsShortcut[] (reactivo)Lista actual — renderiza el panel de ayuda con ella.

Comportamiento

  • Modifier exacto: modifier: 'alt' matchea solo si altKey es true Y los otros modifiers están a false. Sin modifier, exige cero modifiers.
  • Foco en form fields: input, textarea, select y contenteditable bloquean el shortcut por defecto. Activa forceTrigger: true para teclas globales como Escape.
  • Primer match gana: si dos shortcuts matchean la misma combinación, solo se dispara el primero del array.
  • Múltiples instancias: cada useKeyboardNav() registra su propio listener. Coexisten sin pisarse.

Casos de uso

  • Portfolio CsS: Alt+1..6 para saltar entre secciones, Alt+A para abrir panel de accesibilidad, Escape para cerrar diálogos.
  • Decks: complementar los atajos nativos de Swiper (←/→/Esc) con atajos numerados de salto a slide.
  • Apps con paleta de comandos: Cmd+K / Ctrl+K para abrir un launcher.