@al4k4z4m/console-mode

A zero-dependency, plug-and-play JavaScript framework for adding native, console-like controller support to web applications. Bridge the gap between hardware polling and DOM-based UI navigation (Spatial Navigation).

🚀 Features

• Spatial Navigation: Smart, proximity-based 2D navigation (Up/Down/Left/Right).
• Focus Memory: Automatically remembers and restores focus within containers (data-nav-container).
• Dynamic DOM Support: Automatically detects added/removed elements via MutationObserver.
• Hardware Ready: Built-in 60Hz polling and optimized mapping for standard controllers and DualSense (PS5).
• Ultra-Lightweight: ~2.1KB gzipped, 0 dependencies.

📦 Installation

npm install @al4k4z4m/console-mode

🛠 Quick Start

1. Define Focusable Elements

Simply add data-nav-focusable to any element you want the controller to reach.

<nav data-nav-container="sidebar">
  <button data-nav-focusable>Home</button>
  <button data-nav-focusable>Gallery</button>
</nav>

<main data-nav-container="content">
  <div class="card" data-nav-focusable>Project 1</div>
  <div class="card" data-nav-focusable>Project 2</div>
</main>

2. Initialize the Engine

import { FocusManager, GamepadPoller, GamepadMapper, GamepadManager } from '@al4k4z4m/console-mode';

const focusManager = new FocusManager();
const mapper = new GamepadMapper();
const manager = new GamepadManager();

// Gamepad polling loop (60Hz)
const poller = new GamepadPoller((gamepads) => {
  gamepads.forEach(pad => {
    if (!pad) return;

    // 1. Check Axes (Sticks & D-pad)
    pad.axes.forEach((val, idx) => {
      const intent = mapper.getIntentFromAxis(idx, val);
      if (intent) focusManager.move(intent);
    });

    // 2. Check Buttons (Cross, Square, etc.)
    pad.buttons.forEach((btn, idx) => {
      if (btn.pressed) {
        const intent = mapper.getIntentFromButton(idx);
        if (intent === 'select') {
          focusManager.getCurrentFocus()?.click();
        }
      }
    });
  });
});

poller.start();

🎮 DualSense (PS5) Support

This framework is pre-configured for the DualSense controller on Windows/Chrome:

• Cross Button (Index 1): Mapped to select.
• D-Pad (Axis 9): Fully supported via POV Hat mapping.
• Left Stick: Mapped to standard navigation.

📚 API Reference

HTML Attributes

• data-nav-focusable: Marks an element as navigable.
• data-nav-container="id": Groups elements. When focus enters the container, the framework restores the last focused child.

Event System

Elements dispatch custom events for easy styling or analytics:

• nav-focus: Dispatched when an element gains focus.
• nav-blur: Dispatched when an element loses focus.
• nav-focus-change: Bubbles from the newly focused element.

document.addEventListener('nav-focus', (e) => {
  console.log('Focused element:', e.detail.element);
});

📄 License

MIT