@dotdo/postgres 0.1.0

package/src/playground/keyboard-shortcuts.ts

@@ -0,0 +1,677 @@
+/**
+ * Keyboard Shortcuts for Playground
+ *
+ * Defines keyboard shortcuts and their documentation for the interactive
+ * SQL playground. Provides a consistent keyboard interface for power users.
+ *
+ * @module playground/keyboard-shortcuts
+ */
+
+/**
+ * Minimal KeyboardEvent interface for non-DOM environments
+ * Used when DOM types are not available (e.g., Cloudflare Workers)
+ */
+interface KeyboardEvent {
+  code: string
+  key: string
+  ctrlKey: boolean
+  metaKey: boolean
+  altKey: boolean
+  shiftKey: boolean
+  preventDefault(): void
+  stopPropagation(): void
+}
+
+/**
+ * Modifier keys supported by the shortcut system
+ */
+export type ModifierKey = 'Ctrl' | 'Alt' | 'Shift' | 'Meta' | 'Cmd'
+
+/**
+ * A keyboard shortcut definition
+ */
+export interface KeyboardShortcut {
+  /** Unique identifier for the shortcut */
+  id: string
+  /** Human-readable description of what the shortcut does */
+  description: string
+  /** The key code (e.g., 'Enter', 'KeyS', 'F5') */
+  key: string
+  /** Display string for the key (e.g., 'Enter', 'S', 'F5') */
+  keyDisplay: string
+  /** Modifier keys required */
+  modifiers: ModifierKey[]
+  /** Category for grouping in documentation */
+  category: ShortcutCategory
+  /** Whether this shortcut is enabled by default */
+  enabled: boolean
+  /** Platform-specific overrides (Mac uses Cmd instead of Ctrl) */
+  platformOverrides?: {
+    mac?: { modifiers: ModifierKey[] }
+    windows?: { modifiers: ModifierKey[] }
+  }
+}
+
+/**
+ * Shortcut categories
+ */
+export type ShortcutCategory =
+  | 'execution'
+  | 'editor'
+  | 'navigation'
+  | 'history'
+  | 'results'
+  | 'general'
+
+/**
+ * Category metadata for display
+ */
+export interface ShortcutCategoryInfo {
+  id: ShortcutCategory
+  name: string
+  description: string
+}
+
+/**
+ * Category information
+ */
+export const SHORTCUT_CATEGORIES: ShortcutCategoryInfo[] = [
+  {
+    id: 'execution',
+    name: 'Query Execution',
+    description: 'Run and manage query execution',
+  },
+  {
+    id: 'editor',
+    name: 'Editor',
+    description: 'SQL editor operations',
+  },
+  {
+    id: 'navigation',
+    name: 'Navigation',
+    description: 'Navigate around the playground',
+  },
+  {
+    id: 'history',
+    name: 'History',
+    description: 'Query history management',
+  },
+  {
+    id: 'results',
+    name: 'Results',
+    description: 'Result viewing and export',
+  },
+  {
+    id: 'general',
+    name: 'General',
+    description: 'General playground shortcuts',
+  },
+]
+
+/**
+ * All keyboard shortcuts
+ */
+export const KEYBOARD_SHORTCUTS: KeyboardShortcut[] = [
+  // ============================================================================
+  // Query Execution
+  // ============================================================================
+  {
+    id: 'execute-query',
+    description: 'Execute the current query or selected text',
+    key: 'Enter',
+    keyDisplay: 'Enter',
+    modifiers: ['Ctrl'],
+    category: 'execution',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'execute-query-alt',
+    description: 'Execute query (alternative)',
+    key: 'F5',
+    keyDisplay: 'F5',
+    modifiers: [],
+    category: 'execution',
+    enabled: true,
+  },
+  {
+    id: 'execute-explain',
+    description: 'Execute with EXPLAIN (show query plan)',
+    key: 'KeyE',
+    keyDisplay: 'E',
+    modifiers: ['Ctrl', 'Shift'],
+    category: 'execution',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+  {
+    id: 'cancel-query',
+    description: 'Cancel the running query',
+    key: 'Escape',
+    keyDisplay: 'Esc',
+    modifiers: [],
+    category: 'execution',
+    enabled: true,
+  },
+  {
+    id: 'execute-selection',
+    description: 'Execute only selected SQL',
+    key: 'Enter',
+    keyDisplay: 'Enter',
+    modifiers: ['Ctrl', 'Shift'],
+    category: 'execution',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+
+  // ============================================================================
+  // Editor
+  // ============================================================================
+  {
+    id: 'format-sql',
+    description: 'Format/prettify SQL',
+    key: 'KeyF',
+    keyDisplay: 'F',
+    modifiers: ['Ctrl', 'Shift'],
+    category: 'editor',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+  {
+    id: 'comment-line',
+    description: 'Toggle line comment',
+    key: 'Slash',
+    keyDisplay: '/',
+    modifiers: ['Ctrl'],
+    category: 'editor',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'select-all',
+    description: 'Select all SQL in editor',
+    key: 'KeyA',
+    keyDisplay: 'A',
+    modifiers: ['Ctrl'],
+    category: 'editor',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'undo',
+    description: 'Undo last change',
+    key: 'KeyZ',
+    keyDisplay: 'Z',
+    modifiers: ['Ctrl'],
+    category: 'editor',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'redo',
+    description: 'Redo last undone change',
+    key: 'KeyY',
+    keyDisplay: 'Y',
+    modifiers: ['Ctrl'],
+    category: 'editor',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+  {
+    id: 'find',
+    description: 'Find in editor',
+    key: 'KeyF',
+    keyDisplay: 'F',
+    modifiers: ['Ctrl'],
+    category: 'editor',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'find-replace',
+    description: 'Find and replace',
+    key: 'KeyH',
+    keyDisplay: 'H',
+    modifiers: ['Ctrl'],
+    category: 'editor',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Alt'] },
+    },
+  },
+  {
+    id: 'indent',
+    description: 'Indent selected lines',
+    key: 'Tab',
+    keyDisplay: 'Tab',
+    modifiers: [],
+    category: 'editor',
+    enabled: true,
+  },
+  {
+    id: 'outdent',
+    description: 'Outdent selected lines',
+    key: 'Tab',
+    keyDisplay: 'Tab',
+    modifiers: ['Shift'],
+    category: 'editor',
+    enabled: true,
+  },
+  {
+    id: 'duplicate-line',
+    description: 'Duplicate current line',
+    key: 'KeyD',
+    keyDisplay: 'D',
+    modifiers: ['Ctrl', 'Shift'],
+    category: 'editor',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+  {
+    id: 'autocomplete',
+    description: 'Trigger autocomplete suggestions',
+    key: 'Space',
+    keyDisplay: 'Space',
+    modifiers: ['Ctrl'],
+    category: 'editor',
+    enabled: true,
+  },
+
+  // ============================================================================
+  // Navigation
+  // ============================================================================
+  {
+    id: 'focus-editor',
+    description: 'Focus the SQL editor',
+    key: 'Digit1',
+    keyDisplay: '1',
+    modifiers: ['Alt'],
+    category: 'navigation',
+    enabled: true,
+  },
+  {
+    id: 'focus-results',
+    description: 'Focus the results panel',
+    key: 'Digit2',
+    keyDisplay: '2',
+    modifiers: ['Alt'],
+    category: 'navigation',
+    enabled: true,
+  },
+  {
+    id: 'focus-schema',
+    description: 'Focus the schema browser',
+    key: 'Digit3',
+    keyDisplay: '3',
+    modifiers: ['Alt'],
+    category: 'navigation',
+    enabled: true,
+  },
+  {
+    id: 'toggle-schema-panel',
+    description: 'Toggle schema browser panel',
+    key: 'KeyB',
+    keyDisplay: 'B',
+    modifiers: ['Ctrl'],
+    category: 'navigation',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'toggle-history-panel',
+    description: 'Toggle query history panel',
+    key: 'KeyH',
+    keyDisplay: 'H',
+    modifiers: ['Ctrl', 'Shift'],
+    category: 'navigation',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+
+  // ============================================================================
+  // History
+  // ============================================================================
+  {
+    id: 'previous-query',
+    description: 'Load previous query from history',
+    key: 'ArrowUp',
+    keyDisplay: 'Up',
+    modifiers: ['Alt'],
+    category: 'history',
+    enabled: true,
+  },
+  {
+    id: 'next-query',
+    description: 'Load next query from history',
+    key: 'ArrowDown',
+    keyDisplay: 'Down',
+    modifiers: ['Alt'],
+    category: 'history',
+    enabled: true,
+  },
+  {
+    id: 'search-history',
+    description: 'Search query history',
+    key: 'KeyR',
+    keyDisplay: 'R',
+    modifiers: ['Ctrl'],
+    category: 'history',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'star-query',
+    description: 'Star/unstar current query',
+    key: 'KeyS',
+    keyDisplay: 'S',
+    modifiers: ['Ctrl', 'Shift'],
+    category: 'history',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+
+  // ============================================================================
+  // Results
+  // ============================================================================
+  {
+    id: 'copy-results',
+    description: 'Copy selected results to clipboard',
+    key: 'KeyC',
+    keyDisplay: 'C',
+    modifiers: ['Ctrl'],
+    category: 'results',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'export-csv',
+    description: 'Export results as CSV',
+    key: 'KeyE',
+    keyDisplay: 'E',
+    modifiers: ['Ctrl', 'Alt'],
+    category: 'results',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Alt'] },
+    },
+  },
+  {
+    id: 'export-json',
+    description: 'Export results as JSON',
+    key: 'KeyJ',
+    keyDisplay: 'J',
+    modifiers: ['Ctrl', 'Alt'],
+    category: 'results',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Alt'] },
+    },
+  },
+  {
+    id: 'toggle-result-format',
+    description: 'Toggle between table/JSON view',
+    key: 'KeyT',
+    keyDisplay: 'T',
+    modifiers: ['Ctrl'],
+    category: 'results',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'next-page',
+    description: 'Go to next page of results',
+    key: 'PageDown',
+    keyDisplay: 'PageDown',
+    modifiers: [],
+    category: 'results',
+    enabled: true,
+  },
+  {
+    id: 'previous-page',
+    description: 'Go to previous page of results',
+    key: 'PageUp',
+    keyDisplay: 'PageUp',
+    modifiers: [],
+    category: 'results',
+    enabled: true,
+  },
+
+  // ============================================================================
+  // General
+  // ============================================================================
+  {
+    id: 'new-query',
+    description: 'Clear editor and start new query',
+    key: 'KeyN',
+    keyDisplay: 'N',
+    modifiers: ['Ctrl'],
+    category: 'general',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'save-query',
+    description: 'Save current query',
+    key: 'KeyS',
+    keyDisplay: 'S',
+    modifiers: ['Ctrl'],
+    category: 'general',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd'] },
+    },
+  },
+  {
+    id: 'show-shortcuts',
+    description: 'Show keyboard shortcuts help',
+    key: 'Slash',
+    keyDisplay: '?',
+    modifiers: ['Ctrl', 'Shift'],
+    category: 'general',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+  {
+    id: 'load-sample-data',
+    description: 'Load sample data into database',
+    key: 'KeyL',
+    keyDisplay: 'L',
+    modifiers: ['Ctrl', 'Shift'],
+    category: 'general',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+  {
+    id: 'reset-database',
+    description: 'Reset database (clear all tables)',
+    key: 'Delete',
+    keyDisplay: 'Del',
+    modifiers: ['Ctrl', 'Shift'],
+    category: 'general',
+    enabled: true,
+    platformOverrides: {
+      mac: { modifiers: ['Cmd', 'Shift'] },
+    },
+  },
+]
+
+/**
+ * Detect the current platform
+ */
+export function detectPlatform(): 'mac' | 'windows' | 'linux' {
+  if (typeof navigator !== 'undefined') {
+    const platform = navigator.platform.toLowerCase()
+    if (platform.includes('mac')) return 'mac'
+    if (platform.includes('win')) return 'windows'
+  }
+  return 'linux'
+}
+
+/**
+ * Get the effective modifiers for a shortcut on the current platform
+ */
+export function getEffectiveModifiers(shortcut: KeyboardShortcut, platform?: 'mac' | 'windows' | 'linux'): ModifierKey[] {
+  const currentPlatform = platform ?? detectPlatform()
+  const override = shortcut.platformOverrides?.[currentPlatform as 'mac' | 'windows']
+  return override?.modifiers ?? shortcut.modifiers
+}
+
+/**
+ * Format a shortcut for display
+ */
+export function formatShortcut(shortcut: KeyboardShortcut, platform?: 'mac' | 'windows' | 'linux'): string {
+  const modifiers = getEffectiveModifiers(shortcut, platform)
+  const currentPlatform = platform ?? detectPlatform()
+
+  const modifierSymbols: Record<ModifierKey, string> = currentPlatform === 'mac'
+    ? {
+        Ctrl: '\u2303', // Control
+        Alt: '\u2325', // Option
+        Shift: '\u21E7', // Shift
+        Meta: '\u2318', // Command
+        Cmd: '\u2318', // Command
+      }
+    : {
+        Ctrl: 'Ctrl',
+        Alt: 'Alt',
+        Shift: 'Shift',
+        Meta: 'Win',
+        Cmd: 'Ctrl', // Map Cmd to Ctrl on non-Mac
+      }
+
+  const parts = modifiers.map((m) => modifierSymbols[m])
+  parts.push(shortcut.keyDisplay)
+
+  return currentPlatform === 'mac' ? parts.join('') : parts.join('+')
+}
+
+/**
+ * Get shortcuts by category
+ */
+export function getShortcutsByCategory(category: ShortcutCategory): KeyboardShortcut[] {
+  return KEYBOARD_SHORTCUTS.filter((s) => s.category === category && s.enabled)
+}
+
+/**
+ * Get a shortcut by ID
+ */
+export function getShortcutById(id: string): KeyboardShortcut | undefined {
+  return KEYBOARD_SHORTCUTS.find((s) => s.id === id)
+}
+
+/**
+ * Check if a keyboard event matches a shortcut
+ */
+export function matchesShortcut(event: KeyboardEvent, shortcut: KeyboardShortcut): boolean {
+  const modifiers = getEffectiveModifiers(shortcut)
+  const platform = detectPlatform()
+
+  // Check modifiers
+  const ctrlRequired = modifiers.includes('Ctrl') || (platform !== 'mac' && modifiers.includes('Cmd'))
+  const metaRequired = modifiers.includes('Meta') || (platform === 'mac' && modifiers.includes('Cmd'))
+  const altRequired = modifiers.includes('Alt')
+  const shiftRequired = modifiers.includes('Shift')
+
+  if (ctrlRequired !== event.ctrlKey) return false
+  if (metaRequired !== event.metaKey) return false
+  if (altRequired !== event.altKey) return false
+  if (shiftRequired !== event.shiftKey) return false
+
+  // Check key
+  return event.code === shortcut.key || event.key === shortcut.keyDisplay
+}
+
+/**
+ * Find which shortcut matches a keyboard event
+ */
+export function findMatchingShortcut(event: KeyboardEvent): KeyboardShortcut | undefined {
+  return KEYBOARD_SHORTCUTS.find((s) => s.enabled && matchesShortcut(event, s))
+}
+
+/**
+ * Generate a printable keyboard shortcuts reference
+ */
+export function generateShortcutsReference(platform?: 'mac' | 'windows' | 'linux'): string {
+  const currentPlatform = platform ?? detectPlatform()
+  const lines: string[] = ['Keyboard Shortcuts Reference', '=' .repeat(40), '']
+
+  for (const category of SHORTCUT_CATEGORIES) {
+    const shortcuts = getShortcutsByCategory(category.id)
+    if (shortcuts.length === 0) continue
+
+    lines.push(`${category.name}`)
+    lines.push('-'.repeat(category.name.length))
+
+    for (const shortcut of shortcuts) {
+      const formatted = formatShortcut(shortcut, currentPlatform)
+      lines.push(`  ${formatted.padEnd(20)} ${shortcut.description}`)
+    }
+
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Type for shortcut handler callback
+ */
+export type ShortcutHandler = (shortcut: KeyboardShortcut, event: KeyboardEvent) => void | boolean
+
+/**
+ * Create a keyboard shortcut handler that can be attached to a DOM element
+ */
+export function createShortcutHandler(handlers: Partial<Record<string, ShortcutHandler>>): (event: KeyboardEvent) => void {
+  return (event: KeyboardEvent) => {
+    const shortcut = findMatchingShortcut(event)
+    if (!shortcut) return
+
+    const handler = handlers[shortcut.id]
+    if (handler) {
+      const result = handler(shortcut, event)
+      // If handler returns false or void, prevent default
+      if (result !== true) {
+        event.preventDefault()
+        event.stopPropagation()
+      }
+    }
+  }
+}