pixelweaver 0.1.0

package/src/lib/shortcuts/shortcut-manager.test.ts

@@ -0,0 +1,466 @@
+/**
+ * Unit tests for the keyboard shortcut system.
+ *
+ * Covers parsing, normalization, event matching, bind/unbind, rebind,
+ * conflict detection, enable/disable, profile export/import, and
+ * integration with default bindings.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  parseShortcut,
+  normalizeShortcut,
+  matchesEvent,
+  ShortcutManager,
+} from './shortcut-manager.js';
+import { DEFAULT_BINDINGS } from './default-bindings.js';
+
+// --- Helpers ---
+
+/** Create a synthetic KeyboardEvent for testing. */
+function makeKeyEvent(
+  key: string,
+  modifiers: {
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+  } = {},
+): KeyboardEvent {
+  return new KeyboardEvent('keydown', {
+    key,
+    ctrlKey: modifiers.ctrlKey ?? false,
+    shiftKey: modifiers.shiftKey ?? false,
+    altKey: modifiers.altKey ?? false,
+    metaKey: modifiers.metaKey ?? false,
+    bubbles: true,
+    cancelable: true,
+  });
+}
+
+// --- parseShortcut ---
+
+describe('parseShortcut', () => {
+  it('parses a single letter key', () => {
+    const parsed = parseShortcut('B');
+    expect(parsed).toEqual({
+      key: 'b',
+      ctrl: false,
+      shift: false,
+      alt: false,
+      meta: false,
+    });
+  });
+
+  it('parses Ctrl+Z', () => {
+    const parsed = parseShortcut('Ctrl+Z');
+    expect(parsed).toEqual({
+      key: 'z',
+      ctrl: true,
+      shift: false,
+      alt: false,
+      meta: false,
+    });
+  });
+
+  it('parses Ctrl+Shift+Z', () => {
+    const parsed = parseShortcut('Ctrl+Shift+Z');
+    expect(parsed).toEqual({
+      key: 'z',
+      ctrl: true,
+      shift: true,
+      alt: false,
+      meta: false,
+    });
+  });
+
+  it('parses Alt+F4', () => {
+    const parsed = parseShortcut('Alt+F4');
+    expect(parsed).toEqual({
+      key: 'f4',
+      ctrl: false,
+      shift: false,
+      alt: true,
+      meta: false,
+    });
+  });
+
+  it('parses Meta/Cmd modifier aliases', () => {
+    expect(parseShortcut('Meta+S').meta).toBe(true);
+    expect(parseShortcut('Cmd+S').meta).toBe(true);
+    expect(parseShortcut('Command+S').meta).toBe(true);
+    expect(parseShortcut('Win+S').meta).toBe(true);
+    expect(parseShortcut('Super+S').meta).toBe(true);
+  });
+
+  it('parses Control as alias for Ctrl', () => {
+    const parsed = parseShortcut('Control+C');
+    expect(parsed.ctrl).toBe(true);
+    expect(parsed.key).toBe('c');
+  });
+
+  it('handles extra whitespace around parts', () => {
+    const parsed = parseShortcut(' Ctrl + Shift + Z ');
+    expect(parsed.ctrl).toBe(true);
+    expect(parsed.shift).toBe(true);
+    expect(parsed.key).toBe('z');
+  });
+
+  it('parses special key names', () => {
+    expect(parseShortcut('Escape').key).toBe('escape');
+    expect(parseShortcut('Enter').key).toBe('enter');
+    expect(parseShortcut('=').key).toBe('=');
+    expect(parseShortcut('-').key).toBe('-');
+  });
+});
+
+// --- normalizeShortcut ---
+
+describe('normalizeShortcut', () => {
+  it('normalizes a single key to lowercase', () => {
+    expect(normalizeShortcut('B')).toBe('b');
+  });
+
+  it('normalizes modifiers to fixed order: ctrl+alt+shift+meta+key', () => {
+    // Regardless of input order, output should be ctrl+shift+z
+    expect(normalizeShortcut('Ctrl+Shift+Z')).toBe('ctrl+shift+z');
+    expect(normalizeShortcut('Shift+Ctrl+Z')).toBe('ctrl+shift+z');
+  });
+
+  it('normalizes modifier aliases', () => {
+    expect(normalizeShortcut('Cmd+S')).toBe('meta+s');
+    expect(normalizeShortcut('Control+Z')).toBe('ctrl+z');
+  });
+
+  it('produces consistent output for equivalent inputs', () => {
+    const a = normalizeShortcut('Ctrl+Alt+Shift+X');
+    const b = normalizeShortcut('shift+alt+ctrl+x');
+    const c = normalizeShortcut('Alt+Ctrl+Shift+X');
+    expect(a).toBe(b);
+    expect(b).toBe(c);
+    expect(a).toBe('ctrl+alt+shift+x');
+  });
+});
+
+// --- matchesEvent ---
+
+describe('matchesEvent', () => {
+  it('matches a simple key', () => {
+    const parsed = parseShortcut('B');
+    const event = makeKeyEvent('b');
+    expect(matchesEvent(parsed, event)).toBe(true);
+  });
+
+  it('does not match when modifiers differ', () => {
+    const parsed = parseShortcut('B');
+    const event = makeKeyEvent('b', { ctrlKey: true });
+    expect(matchesEvent(parsed, event)).toBe(false);
+  });
+
+  it('matches Ctrl+Z', () => {
+    const parsed = parseShortcut('Ctrl+Z');
+    const event = makeKeyEvent('z', { ctrlKey: true });
+    expect(matchesEvent(parsed, event)).toBe(true);
+  });
+
+  it('does not match Ctrl+Z when Shift is also pressed', () => {
+    const parsed = parseShortcut('Ctrl+Z');
+    const event = makeKeyEvent('z', { ctrlKey: true, shiftKey: true });
+    expect(matchesEvent(parsed, event)).toBe(false);
+  });
+
+  it('matches Ctrl+Shift+Z exactly', () => {
+    const parsed = parseShortcut('Ctrl+Shift+Z');
+    const event = makeKeyEvent('z', { ctrlKey: true, shiftKey: true });
+    expect(matchesEvent(parsed, event)).toBe(true);
+  });
+
+  it('is case-insensitive for the key', () => {
+    const parsed = parseShortcut('B');
+    const eventUpper = makeKeyEvent('B');
+    // event.key is case-sensitive in the browser, but our matchesEvent
+    // lowercases it, so uppercase 'B' should still match parsed 'b'
+    // However, the browser sends 'B' for Shift+b, which would have shiftKey=true.
+    // For a plain 'b' press, the browser sends lowercase 'b'.
+    // Our matching lowercases event.key, so 'B' -> 'b' matches parsed.key 'b'.
+    // But if event also has shiftKey=false, it should match.
+    expect(matchesEvent(parsed, eventUpper)).toBe(true);
+  });
+});
+
+// --- ShortcutManager: bind/unbind ---
+
+describe('ShortcutManager', () => {
+  let manager: ShortcutManager;
+
+  beforeEach(() => {
+    manager = new ShortcutManager();
+  });
+
+  describe('bind and unbind', () => {
+    it('binds a shortcut and fires the action on handleKeyDown', () => {
+      const action = vi.fn();
+      manager.bind('B', action, 'Test action');
+
+      const event = makeKeyEvent('b');
+      const handled = manager.handleKeyDown(event);
+
+      expect(handled).toBe(true);
+      expect(action).toHaveBeenCalledOnce();
+    });
+
+    it('returns false for unbound keys', () => {
+      const handled = manager.handleKeyDown(makeKeyEvent('q'));
+      expect(handled).toBe(false);
+    });
+
+    it('unbinds a shortcut', () => {
+      const action = vi.fn();
+      manager.bind('B', action, 'Test');
+      manager.unbind('B');
+
+      const handled = manager.handleKeyDown(makeKeyEvent('b'));
+      expect(handled).toBe(false);
+      expect(action).not.toHaveBeenCalled();
+    });
+
+    it('getBindings returns all current bindings', () => {
+      const action1 = vi.fn();
+      const action2 = vi.fn();
+      manager.bind('B', action1, 'Action 1');
+      manager.bind('Ctrl+Z', action2, 'Action 2');
+
+      const bindings = manager.getBindings();
+      expect(bindings.size).toBe(2);
+      expect(bindings.get('b')?.description).toBe('Action 1');
+      expect(bindings.get('ctrl+z')?.description).toBe('Action 2');
+    });
+  });
+
+  describe('handleKeyDown', () => {
+    it('calls preventDefault on matched shortcuts', () => {
+      manager.bind('Ctrl+S', vi.fn(), 'Save');
+      const event = makeKeyEvent('s', { ctrlKey: true });
+
+      // spy on preventDefault
+      const preventSpy = vi.spyOn(event, 'preventDefault');
+      manager.handleKeyDown(event);
+
+      expect(preventSpy).toHaveBeenCalledOnce();
+    });
+
+    it('does NOT call preventDefault on unmatched keys', () => {
+      const event = makeKeyEvent('q');
+      const preventSpy = vi.spyOn(event, 'preventDefault');
+      manager.handleKeyDown(event);
+
+      expect(preventSpy).not.toHaveBeenCalled();
+    });
+
+    it('distinguishes Ctrl+Z from Ctrl+Shift+Z', () => {
+      const undoAction = vi.fn();
+      const redoAction = vi.fn();
+      manager.bind('Ctrl+Z', undoAction, 'Undo');
+      manager.bind('Ctrl+Shift+Z', redoAction, 'Redo');
+
+      manager.handleKeyDown(makeKeyEvent('z', { ctrlKey: true }));
+      expect(undoAction).toHaveBeenCalledOnce();
+      expect(redoAction).not.toHaveBeenCalled();
+
+      manager.handleKeyDown(makeKeyEvent('z', { ctrlKey: true, shiftKey: true }));
+      expect(redoAction).toHaveBeenCalledOnce();
+      expect(undoAction).toHaveBeenCalledOnce(); // still 1 from before
+    });
+  });
+
+  describe('conflict detection', () => {
+    it('returns null when no conflict exists', () => {
+      expect(manager.getConflict('B')).toBeNull();
+    });
+
+    it('returns description of conflicting binding', () => {
+      manager.bind('B', vi.fn(), 'Pencil tool');
+      expect(manager.getConflict('B')).toBe('Pencil tool');
+    });
+
+    it('normalizes before checking for conflicts', () => {
+      manager.bind('Ctrl+Shift+Z', vi.fn(), 'Redo');
+      // Same shortcut written differently
+      expect(manager.getConflict('Shift+Ctrl+Z')).toBe('Redo');
+    });
+  });
+
+  describe('rebind', () => {
+    it('moves an action from one key to another', () => {
+      const action = vi.fn();
+      manager.bind('B', action, 'Pencil tool', 'tool.pencil');
+
+      manager.rebind('B', 'P');
+
+      // Old key should no longer fire
+      expect(manager.handleKeyDown(makeKeyEvent('b'))).toBe(false);
+
+      // New key should fire
+      expect(manager.handleKeyDown(makeKeyEvent('p'))).toBe(true);
+      expect(action).toHaveBeenCalledOnce();
+    });
+
+    it('preserves description and name after rebind', () => {
+      manager.bind('B', vi.fn(), 'Pencil tool', 'tool.pencil');
+      manager.rebind('B', 'P');
+
+      const bindings = manager.getBindings();
+      expect(bindings.get('p')?.description).toBe('Pencil tool');
+      expect(bindings.has('b')).toBe(false);
+    });
+
+    it('updates the name-to-shortcut mapping after rebind', () => {
+      manager.bind('B', vi.fn(), 'Pencil tool', 'tool.pencil');
+      manager.rebind('B', 'P');
+
+      expect(manager.getShortcutForName('tool.pencil')).toBe('p');
+    });
+
+    it('does nothing for a non-existent old shortcut', () => {
+      // Should not throw
+      manager.rebind('Q', 'W');
+      expect(manager.getBindings().size).toBe(0);
+    });
+  });
+
+  describe('setEnabled', () => {
+    it('prevents shortcuts from firing when disabled', () => {
+      const action = vi.fn();
+      manager.bind('B', action, 'Test');
+
+      manager.setEnabled(false);
+      const handled = manager.handleKeyDown(makeKeyEvent('b'));
+
+      expect(handled).toBe(false);
+      expect(action).not.toHaveBeenCalled();
+    });
+
+    it('re-enables shortcuts after being disabled', () => {
+      const action = vi.fn();
+      manager.bind('B', action, 'Test');
+
+      manager.setEnabled(false);
+      manager.setEnabled(true);
+
+      const handled = manager.handleKeyDown(makeKeyEvent('b'));
+      expect(handled).toBe(true);
+      expect(action).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('reset', () => {
+    it('removes all bindings', () => {
+      manager.bind('B', vi.fn(), 'Test');
+      manager.bind('Ctrl+Z', vi.fn(), 'Test2');
+      manager.reset();
+
+      expect(manager.getBindings().size).toBe(0);
+      expect(manager.handleKeyDown(makeKeyEvent('b'))).toBe(false);
+    });
+
+    it('re-enables the manager after reset', () => {
+      manager.setEnabled(false);
+      manager.reset();
+      expect(manager.isEnabled()).toBe(true);
+    });
+  });
+
+  describe('profile export/import', () => {
+    it('exports named bindings as a profile', () => {
+      manager.bind('B', vi.fn(), 'Pencil tool', 'tool.pencil');
+      manager.bind('E', vi.fn(), 'Eraser tool', 'tool.eraser');
+      manager.bind('Ctrl+Z', vi.fn(), 'Undo', 'edit.undo');
+
+      const profile = manager.exportProfile();
+      expect(profile).toEqual({
+        'tool.pencil': 'b',
+        'tool.eraser': 'e',
+        'edit.undo': 'ctrl+z',
+      });
+    });
+
+    it('does not export unnamed bindings', () => {
+      manager.bind('B', vi.fn(), 'Anonymous binding'); // no name
+      const profile = manager.exportProfile();
+      expect(Object.keys(profile)).toHaveLength(0);
+    });
+
+    it('roundtrips export/import without changing bindings', () => {
+      const action1 = vi.fn();
+      const action2 = vi.fn();
+      manager.bind('B', action1, 'Pencil', 'tool.pencil');
+      manager.bind('Ctrl+Z', action2, 'Undo', 'edit.undo');
+
+      const profile = manager.exportProfile();
+      manager.importProfile(profile);
+
+      // Bindings should be unchanged
+      expect(manager.handleKeyDown(makeKeyEvent('b'))).toBe(true);
+      expect(action1).toHaveBeenCalledOnce();
+      expect(manager.handleKeyDown(makeKeyEvent('z', { ctrlKey: true }))).toBe(true);
+      expect(action2).toHaveBeenCalledOnce();
+    });
+
+    it('imports a modified profile and rebinds actions', () => {
+      const action = vi.fn();
+      manager.bind('B', action, 'Pencil', 'tool.pencil');
+
+      // Import a profile that changes pencil from B to P
+      manager.importProfile({ 'tool.pencil': 'P' });
+
+      expect(manager.handleKeyDown(makeKeyEvent('b'))).toBe(false);
+      expect(manager.handleKeyDown(makeKeyEvent('p'))).toBe(true);
+      expect(action).toHaveBeenCalledOnce();
+    });
+
+    it('ignores profile entries for unknown action names', () => {
+      manager.bind('B', vi.fn(), 'Pencil', 'tool.pencil');
+
+      // 'tool.unknown' doesn't exist, should be silently ignored
+      manager.importProfile({ 'tool.unknown': 'Q' });
+      expect(manager.getBindings().size).toBe(1);
+    });
+  });
+
+  describe('default bindings', () => {
+    it('loads all default bindings without errors', () => {
+      for (const binding of DEFAULT_BINDINGS) {
+        // Using a noop action since we're just testing that binding works
+        manager.bind(binding.key, () => {}, binding.description, binding.name);
+      }
+
+      expect(manager.getBindings().size).toBe(DEFAULT_BINDINGS.length);
+    });
+
+    it('all default binding names are unique', () => {
+      const names = DEFAULT_BINDINGS.map((b) => b.name);
+      const uniqueNames = new Set(names);
+      expect(uniqueNames.size).toBe(names.length);
+    });
+
+    it('all default binding keys are unique (no collisions)', () => {
+      const keys = DEFAULT_BINDINGS.map((b) => normalizeShortcut(b.key));
+      const uniqueKeys = new Set(keys);
+      expect(uniqueKeys.size).toBe(keys.length);
+    });
+
+    it('exports default bindings profile correctly', () => {
+      for (const binding of DEFAULT_BINDINGS) {
+        manager.bind(binding.key, () => {}, binding.description, binding.name);
+      }
+
+      const profile = manager.exportProfile();
+      expect(Object.keys(profile).length).toBe(DEFAULT_BINDINGS.length);
+
+      // Spot check a few entries
+      expect(profile['tool.pencil']).toBe('b');
+      expect(profile['edit.undo']).toBe('ctrl+z');
+      expect(profile['edit.redo']).toBe('ctrl+shift+z');
+    });
+  });
+});