Keyboard Shortcuts & Accessibility

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/keyboard.ts
• src/lib/tests/keyboard.test.ts
• src/components/keyboard-help-overlay.tsx
• src/components/bulk/bulk-actions-bar.tsx
• README.md
• CHANGELOG.md

Refined GitHub Projects implements a comprehensive keyboard-driven workflow to enhance productivity within the GitHub Projects V2 interface. The system is designed to allow power users to manage project items, trigger bulk operations, and navigate the UI without relying on mouse interactions.

The architecture centers around a centralized shortcut registry that manages keybindings across different contexts, ensuring that shortcuts do not interfere with standard browser or GitHub native behaviors, particularly when users are interacting with editable fields. This system is paired with a visual accessibility layer, including a help overlay, to ensure discoverability and ease of use.

Sources: README.md:144-150, src/lib/keyboard.ts:1-20

Shortcut Management System

The core of the keyboard system is the shortcutRegistry, a singleton object that manages the registration, unregistration, and execution of keyboard actions.

Architecture and Data Flow

The registry maintains a collection of ShortcutDefinition objects. Each definition includes the target key, modifiers (Shift, Meta/Ctrl, Alt), and an execution context.

The system uses a subscription model to notify UI components (like the help overlay) whenever the registry changes, ensuring the visual documentation is always in sync with the available features.

Sources: src/lib/keyboard.ts:40-100, src/lib/tests/keyboard.test.ts:100-120

Key Components

Component	Description
shortcutRegistry	Centralized store for all active keybindings. Handles DOM event listeners.
ShortcutDefinition	Interface defining a shortcut's ID, key, modifiers, context, and callback action.
formatShortcut	Utility function to convert raw key data into human-readable strings (e.g., "⌘⇧B").
isEditableTarget	Logic to determine if the focus is inside a textarea or input to prevent accidental triggers.

Sources: src/lib/keyboard.ts:5-35, src/lib/keyboard.ts:153-180

Bulk Operation Shortcuts

Keyboard shortcuts are primarily used to drive the Bulk Actions Bar. When items are selected in the project table, a specific set of shortcuts becomes active.

Global and Selection Contexts

The project categorizes shortcuts into two main contexts:

1. Global: Always available (e.g., "Select All", "Help").
2. Table Selection: Only active when one or more items are selected.

Available Shortcuts Table

Shortcut	Context	Action
⌘A / Ctrl+A	Global	Select all visible items in the table.
? (Shift + /)	Global	Open Keyboard Shortcuts Help Overlay.
Esc	Global	Clear current selection or close open modals.
⌘⇧B	Selection	Focus and open the Actions menu.
⌘⇧E / E	Selection	Open Bulk Edit Fields wizard.
⌘⇧X	Selection	Open Bulk Close issues modal.
⌘⇧D / D	Selection (Single)	Open Deep Duplicate modal for a single item.
⌘⇧⌫ / Delete	Selection	Open Bulk Delete confirmation.

Sources: src/components/bulk/bulk-actions-bar.tsx:210-350, README.md:270-285

Visual Accessibility & Help Overlay

To ensure shortcuts are discoverable, the extension includes a KeyboardHelpOverlay component. This overlay is triggered by the standard GitHub shortcut ?.

Help Overlay Implementation

The overlay dynamically reads from the shortcutRegistry using the getGrouped() method to display shortcuts organized by their context (e.g., "Global", "Table Selection").

This ensures that even as the project evolves and new features are added via the modular background architecture, the help documentation remains technically accurate without manual updates to the help text.

Sources: src/components/keyboard-help-overlay.tsx:10-50, CHANGELOG.md:10-15

Code Snippet: Shortcut Formatting

The system normalizes symbols across platforms, using Mac-specific symbols (⌘) or generic modifier labels (Ctrl/⌃) as appropriate.

// src/lib/keyboard.ts:153-157
export function formatShortcut(def: ShortcutDefinition): string {
  const parts: string[] = []
  if (def.modifiers.meta) parts.push(isMac ? '\u2318' : 'Ctrl')
  if (def.modifiers.shift) parts.push('\u21E7')
  // ... formats and joins parts
}

Sources: src/lib/keyboard.ts:153-170

Accessibility Guardrails

A critical part of the system's accessibility and usability is the prevention of "ghost" triggers.

1. Input Protection: Shortcuts are automatically disabled when the user is typing in an input field, textarea, or content-editable element, unless specifically overridden by the allowInEditable flag.
2. Sequential Queue: While not a direct keyboard feature, all shortcuts that trigger mutations (like Bulk Delete) pass through a sequential background queue to prevent rate-limiting (403/429 errors), which provides a stable experience for the user.
3. Screen Reader Support: The project uses @primer/react components which include ARIA labels and roles, and stubs out live-region elements to ensure compatibility within the isolated world of content scripts.

Sources: src/lib/keyboard.ts:114-125, wxt.config.ts:31-35, CONTRIBUTING.md:10-15

Refined GitHub Projects' keyboard system prioritizes efficiency through a centralized registry while maintaining standard accessibility practices to ensure the tool remains a seamless addition to the GitHub ecosystem.