Beidou 北斗 - Librería de Navegación por Teclado

Presiona una tecla. Ve los atajos. Navega.

Overlay de navegacion por teclado — cero configuracion, cero dependencias, ~2.7KB gzipped.

Comenzar GitHub

Caracteristicas

Cero Dependencias

Construido completamente con JavaScript vanilla. Sin bibliotecas externas requeridas, garantizando maxima estabilidad.

Tamaño Pequeño

Pesa aproximadamente ~2.9KB gzipped. No aumentara el tamaño de tu bundle.

Framework Agnostico

Funciona perfectamente con React, Vue, Svelte, Angular, o configuraciones de HTML puro.

TypeScript Completo

Compatibilidad de primer nivel con TypeScript, con definiciones de tipos completas incluidas de serie.

Como Funciona

1Paso 1

Presiona Alt (o la tecla configurada) para mostrar los badges.

2Paso 2

Presiona la Letra correspondiente para activar la accion o entrar al contexto.

3Paso 3

Presiona Esc o la tecla de activacion nuevamente para cerrar.

Flujo de Estados

Inactive

Presiona Alt

Active: Root

Presiona Tecla de Contexto

Active: Sub

Instalacion

npm install @sayagodev/beidou
pnpm add @sayagodev/beidou
yarn add @sayagodev/beidou
<script src="https://unpkg.com/@sayagodev/beidou"></script>

Inicialización

import Beidou from '@sayagodev/beidou/min';

// Initialize with default options
const beidou = new Beidou();

// Or with custom options
const beidouCustom = new Beidou({
  key: 'Alt',
  position: 'top-right'
});

Atributos HTML

Beidou usa atributos data para entender tu estructura de navegacion. Agrega estos a tus elementos interactivos.

Atributo	Descripcion	Ejemplo
data-ko-ctx	Define un contexto de navegacion. Los elementos con este atributo revelaran los objetivos hijos cuando se activen.	`<div data-ko-ctx="menu">...</div>`
data-ko-target	Marca un elemento como objetivo de navegacion. Debe estar dentro de un contexto o el body (contexto raiz). El valor es el ID del objectivo.	`<button data-ko-target="save">Save</button>`
data-ko-back	Usado para navegar al contexto padre.	`<button data-ko-back>Back</button>`
data-ko-skip	Indica a Beidou ignorar este elemento y sus hijos.	`<div data-ko-skip>...</div>`

Configuracion

Puedes personalizar el comportamiento de Beidou pasando un objeto de opciones al constructor.

const options = {
  // Trigger key to toggle navigation mode
  key: 'Alt',

  // Key bindings configuration
  keys: {
    // If true, ignores elements matching CSS selectors
    ignore: ['input', 'textarea', '[contenteditable]']
  },

  // Ring configuration
  ring: {
    // Color of the focus ring
    color: '#4f6d8a',
    // Width of the focus ring
    width: '2px',
    // Offset of the focus ring
    offset: '2px'
  },

  // Badge configuration
  badge: {
    // Default positioning of badges
    position: 'top-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
    // Background color
    bg: '#4f6d8a',
    // Text color
    color: '#ffffff',
    // Border radius
    radius: '0px'
  }
};

new Beidou(options);

Variables CSS

Beidou inyecta variables CSS para estilizar el anillo de enfoque y los badges. Puedes sobreescribirlas en tu propia hoja de estilos.

Variable	Default	Descripcion
--ko-ring-c	#0284c7	Color del anillo
--ko-ring-s	dashed	Estilo del anillo
--ko-ring-w	2px	Ancho del anillo
--ko-ring-o	-2px	Offset del anillo
--ko-badge-bg	#f97316	Fondo del badge
--ko-badge-fg	white	Color de texto del badge
--ko-badge-size	11px	Tamaño de fuente
--ko-badge-w	800	Peso de fuente
--ko-badge-font	system-ui,-apple-system,sans-serif	Font family
--ko-badge-p	2px 6px	Relleno
--ko-badge-rad	4px	Radio del borde
--ko-badge-sh	...	Sombra de caja
--ko-input-ring	#059669	Color del anillo de input
--ko-input-ring-s	dashed	Estilo del anillo de input
--ko-input-bg	#059669	Fondo del badge de input
--ko-input-fg	white	Color de texto del badge de input
--ko-input-border	none	Borde del badge de input

API Publica

open()

Abre manualmente el overlay de navegacion.

reset()

Reinicia el estado de navegacion al contexto raiz y oculta los badges.

destroy()

Elimina todos los event listeners y limpia el DOM.

Integracion con Frameworks

Beidou funciona de serie con la mayoria de frameworks. Solo asegurate de que se inicialice despues de que el DOM este listo.

import { useEffect } from 'react';
import Beidou from 'beidou-nav';

export function useBeidou(options) {
  useEffect(() => {
    const beidou = new Beidou(options);
    return () => beidou.destroy();
  }, [options]);
}
<!-- Vue 3 Composition API -->
<script setup>
import { onMounted, onUnmounted } from 'vue'
import Beidou from 'beidou-nav'

let beidou

onMounted(() => {
  beidou = new Beidou({ key: 'Alt' })
})

onUnmounted(() => {
  beidou?.destroy()
})
</script>
<!-- Svelte -->
<script>
  import { onMount, onDestroy } from 'svelte';
  import Beidou from 'beidou-nav';

  let beidou;

  onMount(() => {
    beidou = new Beidou({ key: 'Alt' });
  });

  onDestroy(() => {
    beidou?.destroy();
  });
</script>

Menus Anidados

Crea jerarquias complejas usando contextos.

 {/* body with data-ko-ctx="root" exist */}
  <button data-ko-target="settings">⚙️ Settings</button>
  <div data-ko-ctx="settings">
    <button data-ko-target="profile">Profile</button>
    <button data-ko-target="security">Security</button>
    <button data-ko-back><- Back</button>
  </div>
  <div data-ko-ctx="profile">
    <button onClick={edit()}>Edit</button>
    <button data-ko-back><- Back</button>
  </div>
  <div data-ko-ctx="security">
    <button onClick={changePw()}>Change Password</button>
    <button data-ko-back><- Back</button>
  </div>

Preguntas Frecuentes

¿Cómo cambio la tecla de activación?

Por defecto se usa Alt. Puedes cambiarla al constructor:

const beidou = new Beidou({ key: 'Control' });

¿Cómo funciona Beidou?

Presiona Alt (o la tecla configurada) para activar el modo navegación
Aparecerán badges (A, B, C...) sobre cada elemento interactivo visible
Presiona la letra correspondiente para hacer clic en ese elemento
Presiona Alt de nuevo, la tecla Esc o haz clic en un espacio vacío para desactivar

¿Qué elementos reciben atajos de teclado?

Beidou detecta automáticamente:

<a>, <button>, <input>, <textarea>, <select>
Elementos con role="button", role="link", role="tab"
Elementos con onclick o tabindex >= 0

¿Qué son los contextos?

Los contextos permiten navegar entre diferentes "niveles" de la UI (como menús anidados o modales). Usan los atributos data-ko-ctx y data-ko-target.

¿Cómo creo un sub-contexto?

<div data-ko-ctx="root">
  <button data-ko-target="menu1">Abrir menú</button>

  <div data-ko-ctx="menu1">
    <button>Opción 1</button>
    <button data-ko-back>Volver</button>
  </div>
</div>

data-ko-ctx="menu1"

Los badges no aparecen o no se ven

Verifica que:

Los elementos estén visibles (no tengan display: none o visibility: hidden)
Los elementos tengan dimensiones reales (no estén colapsados)
No estén fuera del viewport
Un ancestro no tenga overflow: hidden/clip que recorte el elemento

Los badges aparecen detrás de otros elementos

El z-index de las insignias es 99999. Si tu página usa z-index mayores, puedes sobrescribirlo con CSS:

:root { --ko-badge-z: 999999; }
.ko-badge { z-index: var(--ko-badge-z); }

¿Qué navegadores soporta?

Todos los navegadores modernos: Chrome, Firefox, Safari, Edge. Requiere Element.closest() y CSS.escape() (ES2020+).

¿Funciona en móvil?

Beidou está diseñado para navegación por teclado. En dispositivos móviles sin teclado físico, no tiene utilidad práctica.

¿Es accesible (a11y)?

Beidou mejora la navegación por teclado, pero no reemplaza un correcto marcado semántico. Úsalo como capa adicional, no como única forma de navegación.