@mdxui/terminal 2.0.0

package/src/renderers/command-palette.ts

@@ -0,0 +1,802 @@
+/**
+ * @mdxui/terminal Command Palette Renderer
+ *
+ * Multi-tier renderer for command palette navigation component.
+ * Supports all 6 tiers: text, markdown, ascii, unicode, ansi, interactive.
+ */
+
+import type { UINode, RenderContext, RenderTier } from '../core/types'
+import { type RouterAdapter } from './utils'
+
+// ANSI constants
+const RESET = '\x1b[0m'
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+const UNDERLINE = '\x1b[4m'
+const INVERSE = '\x1b[7m'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Command {
+  id: string
+  label: string
+  description?: string
+  shortcut?: string
+  icon?: string
+  category?: string
+  disabled?: boolean
+  keywords?: string[]
+  /** Path for route-based navigation commands */
+  path?: string
+  /** Action type: 'navigate' triggers router navigation, 'action' uses callback */
+  actionType?: 'navigate' | 'action'
+}
+
+interface CommandGroup {
+  id: string
+  label: string
+  commands: Command[]
+}
+
+interface CommandPaletteProps {
+  commands: Command[]
+  groups?: CommandGroup[]
+  searchQuery?: string
+  selectedIndex?: number
+  placeholder?: string
+  maxResults?: number
+  showShortcuts?: boolean
+  onSelect?: (commandId: string) => void
+  onQueryChange?: (query: string) => void
+  onClose?: () => void
+  /** Router adapter for navigation commands */
+  router?: RouterAdapter
+}
+
+interface CommandPaletteState {
+  commands: Command[]
+  groups?: CommandGroup[]
+  searchQuery: string
+  selectedIndex: number
+  wrapNavigation?: boolean
+  onSelect?: (commandId: string) => void
+  onQueryChange?: (query: string) => void
+  onClose?: () => void
+  /** Router adapter for navigation commands */
+  router?: RouterAdapter
+}
+
+// ============================================================================
+// Main Render Function
+// ============================================================================
+
+export function renderCommandPalette(node: UINode, ctx: RenderContext): string {
+  const props = node.props as unknown as CommandPaletteProps
+  const {
+    searchQuery = '',
+    selectedIndex = 0,
+    placeholder = 'Search commands...',
+    maxResults = 10,
+    showShortcuts = true,
+  } = props
+
+  // Extract commands from node or props
+  const { commands, groups } = extractCommandsAndGroups(node, props)
+
+  const tier = ctx.tier
+  const maxWidth = ctx.width || 80
+  const lines: string[] = []
+
+  // Render the input box
+  lines.push(renderInputBox(searchQuery, placeholder, tier, ctx, maxWidth))
+
+  // Filter commands based on search
+  let filteredCommands = commands
+  let filteredGroups = groups
+
+  if (searchQuery) {
+    if (groups && groups.length > 0) {
+      filteredGroups = filterGroupedCommands(groups, searchQuery)
+      filteredCommands = []
+    } else {
+      filteredCommands = filterCommands(commands, searchQuery, { maxResults })
+    }
+  }
+
+  // Limit results
+  if (!groups && filteredCommands.length > maxResults) {
+    filteredCommands = filteredCommands.slice(0, maxResults)
+  }
+
+  // Check if no results
+  const hasResults = filteredGroups?.some(g => g.commands.length > 0) || filteredCommands.length > 0
+
+  if (!hasResults && searchQuery) {
+    lines.push(renderNoResults(tier, ctx))
+  } else if (filteredGroups && filteredGroups.length > 0) {
+    // Render grouped commands
+    let globalIndex = 0
+    for (const group of filteredGroups) {
+      if (group.commands.length === 0) continue
+      lines.push(renderGroupHeader(group.label, tier, ctx))
+      for (const cmd of group.commands) {
+        const isSelected = globalIndex === selectedIndex
+        lines.push(renderCommandItem(cmd, isSelected, showShortcuts, tier, ctx, maxWidth))
+        globalIndex++
+      }
+    }
+  } else {
+    // Render flat command list
+    for (let i = 0; i < filteredCommands.length; i++) {
+      const cmd = filteredCommands[i]
+      const isSelected = i === selectedIndex
+      lines.push(renderCommandItem(cmd, isSelected, showShortcuts, tier, ctx, maxWidth))
+    }
+  }
+
+  // Wrap in box for better tiers
+  return wrapInBox(lines, tier, ctx, maxWidth)
+}
+
+// ============================================================================
+// Command Extraction
+// ============================================================================
+
+function extractCommandsAndGroups(node: UINode, props: CommandPaletteProps): {
+  commands: Command[]
+  groups?: CommandGroup[]
+} {
+  if (props.commands && props.commands.length > 0) {
+    return { commands: props.commands, groups: props.groups }
+  }
+
+  // Extract from children
+  const commands: Command[] = []
+  const groups: CommandGroup[] = []
+  const rawChildren = node.children
+  const children: UINode[] = Array.isArray(rawChildren) ? rawChildren : []
+
+  for (const child of children) {
+    if (child.type === 'command-palette-list') {
+      const rawListChildren = child.children
+      const listChildren: UINode[] = Array.isArray(rawListChildren) ? rawListChildren : []
+      for (const item of listChildren) {
+        if (item.type === 'command-group') {
+          const groupCommands: Command[] = []
+          const rawGroupChildren = item.children
+          const groupChildren: UINode[] = Array.isArray(rawGroupChildren) ? rawGroupChildren : []
+          for (const cmdItem of groupChildren) {
+            if (cmdItem.type === 'command-item') {
+              groupCommands.push(extractCommand(cmdItem))
+            }
+          }
+          const itemProps = item.props || {}
+          groups.push({
+            id: itemProps.id as string,
+            label: itemProps.label as string,
+            commands: groupCommands,
+          })
+        } else if (item.type === 'command-item') {
+          commands.push(extractCommand(item))
+        }
+      }
+    }
+  }
+
+  return { commands, groups: groups.length > 0 ? groups : undefined }
+}
+
+function extractCommand(node: UINode): Command {
+  const props = node.props || {}
+  return {
+    id: props.id as string,
+    label: props.label as string,
+    description: props.description as string | undefined,
+    shortcut: props.shortcut as string | undefined,
+    icon: props.icon as string | undefined,
+    category: props.category as string | undefined,
+    disabled: props.disabled as boolean | undefined,
+    keywords: props.keywords as string[] | undefined,
+  }
+}
+
+// ============================================================================
+// Search/Filter Functions
+// ============================================================================
+
+export function filterCommands(
+  commands: Command[],
+  query: string,
+  options?: { maxResults?: number; recentIds?: string[] }
+): Command[] {
+  const { maxResults, recentIds } = options || {}
+  const lowerQuery = query.toLowerCase()
+
+  // Score each command
+  const scored = commands.map((cmd, originalIndex) => {
+    let score = 0
+    let recentRank = -1
+
+    // Boost recent commands and track their order
+    if (recentIds?.includes(cmd.id)) {
+      score += 100
+      recentRank = recentIds.indexOf(cmd.id)
+    }
+
+    // For empty query, include all commands (but give base score to non-recent)
+    if (!query) {
+      if (recentRank < 0) {
+        score += 1 // Base score so they're included
+      }
+    } else {
+      // Match label
+      if (cmd.label.toLowerCase().includes(lowerQuery)) {
+        score += 50
+      }
+
+      // Fuzzy match label
+      if (fuzzyMatch(cmd.label, query)) {
+        score += 30
+      }
+
+      // Match keywords
+      if (cmd.keywords?.some(k => k.toLowerCase().includes(lowerQuery))) {
+        score += 40
+      }
+
+      // Match description
+      if (cmd.description?.toLowerCase().includes(lowerQuery)) {
+        score += 20
+      }
+    }
+
+    return { cmd, score, recentRank, originalIndex }
+  })
+
+  // Filter and sort
+  let results = scored
+    .filter(s => s.score > 0)
+    .sort((a, b) => {
+      // Primary sort by score
+      if (b.score !== a.score) return b.score - a.score
+      // Secondary sort by recent rank (lower is better, -1 means not recent)
+      if (a.recentRank >= 0 && b.recentRank >= 0) return a.recentRank - b.recentRank
+      if (a.recentRank >= 0) return -1
+      if (b.recentRank >= 0) return 1
+      // Tertiary sort by original order
+      return a.originalIndex - b.originalIndex
+    })
+    .map(s => s.cmd)
+
+  // Apply max results
+  if (maxResults && results.length > maxResults) {
+    results = results.slice(0, maxResults)
+  }
+
+  return results
+}
+
+export function filterGroupedCommands(groups: CommandGroup[], query: string): CommandGroup[] {
+  return groups
+    .map(group => ({
+      ...group,
+      commands: filterCommands(group.commands, query),
+    }))
+    .filter(group => group.commands.length > 0)
+}
+
+function fuzzyMatch(text: string, pattern: string): boolean {
+  const textLower = text.toLowerCase()
+  const patternLower = pattern.toLowerCase()
+
+  let textIndex = 0
+  let patternIndex = 0
+
+  while (textIndex < textLower.length && patternIndex < patternLower.length) {
+    if (textLower[textIndex] === patternLower[patternIndex]) {
+      patternIndex++
+    }
+    textIndex++
+  }
+
+  return patternIndex === patternLower.length
+}
+
+// ============================================================================
+// Render Components
+// ============================================================================
+
+function renderInputBox(
+  query: string,
+  placeholder: string,
+  tier: RenderTier,
+  ctx: RenderContext,
+  maxWidth: number
+): string {
+  const displayText = query || placeholder
+  const isPlaceholder = !query
+  const cursorChar = tier === 'interactive' ? '\u2588' : ''
+
+  let content = displayText
+  if (tier === 'interactive') {
+    content = query + cursorChar
+    if (!query) {
+      content = ctx.theme.muted + placeholder + RESET
+    }
+  } else if (isPlaceholder) {
+    if (tier === 'ansi') {
+      content = ctx.theme.muted + placeholder + RESET
+    }
+  }
+
+  const prefix = tier === 'unicode' || tier === 'ansi' || tier === 'interactive' ? '\u2315 ' : '> '
+  return prefix + content
+}
+
+function renderGroupHeader(label: string, tier: RenderTier, ctx: RenderContext): string {
+  if (tier === 'ansi' || tier === 'interactive') {
+    return ctx.theme.muted + label + RESET
+  }
+  if (tier === 'markdown') {
+    return `### ${label}`
+  }
+  return label
+}
+
+function renderNoResults(tier: RenderTier, ctx: RenderContext): string {
+  const message = 'No results found'
+  if (tier === 'ansi' || tier === 'interactive') {
+    return ctx.theme.muted + message + RESET
+  }
+  return message
+}
+
+function renderCommandItem(
+  cmd: Command,
+  isSelected: boolean,
+  showShortcuts: boolean,
+  tier: RenderTier,
+  ctx: RenderContext,
+  maxWidth: number
+): string {
+  const indent = '  '
+  let prefix = isSelected ? '> ' : '  '
+
+  // Build label with icon
+  let label = cmd.label
+  if (cmd.icon && (tier === 'unicode' || tier === 'ansi' || tier === 'interactive')) {
+    label = cmd.icon + ' ' + label
+  }
+
+  // Add description
+  let description = ''
+  if (cmd.description) {
+    if (tier === 'ansi' || tier === 'interactive') {
+      description = ' ' + ctx.theme.muted + cmd.description + RESET
+    } else {
+      description = ' - ' + cmd.description
+    }
+  }
+
+  // Add shortcut
+  let shortcut = ''
+  if (showShortcuts && cmd.shortcut) {
+    if (tier === 'markdown') {
+      shortcut = ' `' + cmd.shortcut + '`'
+    } else if (tier === 'ansi' || tier === 'interactive') {
+      shortcut = '  ' + ctx.theme.muted + cmd.shortcut + RESET
+    } else {
+      shortcut = '  ' + cmd.shortcut
+    }
+  }
+
+  // Build the line
+  let line = indent + prefix + label + description + shortcut
+
+  // Apply styling
+  if (tier === 'text') {
+    if (isSelected) {
+      line = indent + '> ' + label + description + shortcut
+    }
+    if (cmd.disabled) {
+      line += ' (disabled)'
+    }
+  } else if (tier === 'ansi' || tier === 'interactive') {
+    if (cmd.disabled) {
+      return indent + '  ' + ctx.theme.muted + label + RESET
+    }
+    if (isSelected) {
+      return INVERSE + indent + prefix + label + RESET + description + shortcut
+    }
+  }
+
+  return line
+}
+
+function wrapInBox(lines: string[], tier: RenderTier, ctx: RenderContext, maxWidth: number): string {
+  if (tier === 'text' || tier === 'markdown') {
+    return lines.join('\n')
+  }
+
+  // Add box border
+  const horizontal = tier === 'ascii' ? '-' : '\u2500'
+  const vertical = tier === 'ascii' ? '|' : '\u2502'
+  const topLeft = tier === 'ascii' ? '+' : '\u250C'
+  const topRight = tier === 'ascii' ? '+' : '\u2510'
+  const bottomLeft = tier === 'ascii' ? '+' : '\u2514'
+  const bottomRight = tier === 'ascii' ? '+' : '\u2518'
+
+  // Calculate content width - account for border (4 chars: "| " + " |")
+  const maxContentWidth = maxWidth - 4
+  const contentWidth = Math.min(maxContentWidth, Math.max(...lines.map(l => stripAnsi(l).length)))
+  // Ensure minimum width of 20, but not exceeding maxWidth - 4
+  const innerWidth = Math.min(Math.max(contentWidth, 20), maxContentWidth)
+
+  const boxLines: string[] = []
+  boxLines.push(topLeft + horizontal.repeat(innerWidth + 2) + topRight)
+
+  for (const line of lines) {
+    let truncatedLine = line
+    const stripped = stripAnsi(line)
+
+    // Truncate line if it exceeds inner width
+    if (stripped.length > innerWidth) {
+      truncatedLine = truncateLineToWidth(line, innerWidth, tier)
+    }
+
+    const truncatedStripped = stripAnsi(truncatedLine)
+    const padding = innerWidth - truncatedStripped.length
+    boxLines.push(vertical + ' ' + truncatedLine + ' '.repeat(Math.max(0, padding)) + ' ' + vertical)
+  }
+
+  boxLines.push(bottomLeft + horizontal.repeat(innerWidth + 2) + bottomRight)
+
+  return boxLines.join('\n')
+}
+
+function truncateLineToWidth(line: string, maxWidth: number, tier: RenderTier): string {
+  const stripped = stripAnsi(line)
+  if (stripped.length <= maxWidth) return line
+
+  const ellipsis = tier === 'unicode' || tier === 'ansi' || tier === 'interactive' ? '\u2026' : '...'
+  const ellipsisLen = tier === 'unicode' || tier === 'ansi' || tier === 'interactive' ? 1 : 3
+  const RESET = '\x1b[0m'
+
+  let visibleLen = 0
+  let result = ''
+  let inEscape = false
+
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i]
+
+    if (char === '\x1b') {
+      inEscape = true
+      result += char
+      continue
+    }
+
+    if (inEscape) {
+      result += char
+      if (char === 'm') {
+        inEscape = false
+      }
+      continue
+    }
+
+    if (visibleLen >= maxWidth - ellipsisLen) {
+      result += ellipsis + RESET
+      break
+    }
+
+    result += char
+    visibleLen++
+  }
+
+  return result
+}
+
+// ============================================================================
+// Keyboard Bindings
+// ============================================================================
+
+export function getCommandPaletteKeyBindings(): Record<string, string> {
+  return {
+    up: 'select-prev',
+    down: 'select-next',
+    k: 'select-prev',
+    j: 'select-next',
+    enter: 'execute',
+    escape: 'close',
+    'ctrl+n': 'select-next',
+    'ctrl+p': 'select-prev',
+    'ctrl+u': 'clear-query',
+    home: 'select-first',
+    end: 'select-last',
+    tab: 'select-next',
+    'shift+tab': 'select-prev',
+    backspace: 'delete-char',
+  }
+}
+
+// ============================================================================
+// State Management
+// ============================================================================
+
+export function createCommandPaletteState(config: {
+  commands: Command[]
+  groups?: CommandGroup[]
+  searchQuery?: string
+  selectedIndex?: number
+  wrapNavigation?: boolean
+  onSelect?: (commandId: string) => void
+  onQueryChange?: (query: string) => void
+  onClose?: () => void
+  /** Router adapter for navigation commands */
+  router?: RouterAdapter
+}): CommandPaletteState {
+  return {
+    commands: config.commands,
+    groups: config.groups,
+    searchQuery: config.searchQuery || '',
+    selectedIndex: config.selectedIndex || 0,
+    wrapNavigation: config.wrapNavigation,
+    onSelect: config.onSelect,
+    onQueryChange: config.onQueryChange,
+    onClose: config.onClose,
+    router: config.router,
+  }
+}
+
+export function handleCommandPaletteKey(state: CommandPaletteState, key: string): CommandPaletteState {
+  const { commands, groups, searchQuery, selectedIndex, wrapNavigation, onSelect, onQueryChange, onClose, router } =
+    state
+
+  // Helper to execute a command (with router support)
+  const executeCommand = (cmd: Command): void => {
+    if (cmd.disabled) return
+
+    // Check if this is a navigation command
+    const isNavigationCommand = cmd.actionType === 'navigate' || (cmd.path && !cmd.actionType)
+
+    if (isNavigationCommand && cmd.path && router) {
+      // Use router for navigation commands
+      router.navigate(cmd.path)
+    } else if (onSelect) {
+      // Use callback for action commands or when no router available
+      onSelect(cmd.id)
+    }
+  }
+
+  // Get all commands (maintaining original order and indices)
+  let allCommands: Command[]
+  if (groups && groups.length > 0) {
+    allCommands = groups.flatMap(g => g.commands)
+  } else {
+    allCommands = commands
+  }
+
+  // Filter by search if needed
+  if (searchQuery) {
+    allCommands = filterCommands(allCommands, searchQuery)
+  }
+
+  const maxIndex = allCommands.length - 1
+
+  // Helper to find next non-disabled index
+  function findNextEnabled(fromIndex: number, direction: 1 | -1): number {
+    let newIndex = fromIndex + direction
+
+    // Keep moving in direction until we find a non-disabled command
+    while (newIndex >= 0 && newIndex <= maxIndex && allCommands[newIndex]?.disabled) {
+      newIndex += direction
+    }
+
+    // Handle boundary cases
+    if (newIndex < 0) {
+      if (wrapNavigation) {
+        // Wrap to end and search backwards for enabled
+        newIndex = maxIndex
+        while (newIndex > fromIndex && allCommands[newIndex]?.disabled) {
+          newIndex--
+        }
+      } else {
+        newIndex = 0
+        // Find first non-disabled from start
+        while (newIndex <= maxIndex && allCommands[newIndex]?.disabled) {
+          newIndex++
+        }
+        if (newIndex > maxIndex) newIndex = fromIndex
+      }
+    } else if (newIndex > maxIndex) {
+      if (wrapNavigation) {
+        // Wrap to start and search forward for enabled
+        newIndex = 0
+        while (newIndex < fromIndex && allCommands[newIndex]?.disabled) {
+          newIndex++
+        }
+      } else {
+        newIndex = maxIndex
+        // Find last non-disabled from end
+        while (newIndex >= 0 && allCommands[newIndex]?.disabled) {
+          newIndex--
+        }
+        if (newIndex < 0) newIndex = fromIndex
+      }
+    }
+
+    return newIndex
+  }
+
+  switch (key) {
+    case 'down':
+    case 'j':
+    case 'ctrl+n':
+    case 'tab': {
+      const newIndex = findNextEnabled(selectedIndex, 1)
+      return { ...state, selectedIndex: newIndex }
+    }
+
+    case 'up':
+    case 'k':
+    case 'ctrl+p':
+    case 'shift+tab': {
+      const newIndex = findNextEnabled(selectedIndex, -1)
+      return { ...state, selectedIndex: newIndex }
+    }
+
+    case 'home': {
+      // Find first non-disabled
+      let newIndex = 0
+      while (newIndex <= maxIndex && allCommands[newIndex]?.disabled) {
+        newIndex++
+      }
+      return { ...state, selectedIndex: newIndex > maxIndex ? 0 : newIndex }
+    }
+
+    case 'end': {
+      // Find last non-disabled
+      let newIndex = maxIndex
+      while (newIndex >= 0 && allCommands[newIndex]?.disabled) {
+        newIndex--
+      }
+      return { ...state, selectedIndex: newIndex < 0 ? 0 : newIndex }
+    }
+
+    case 'enter': {
+      const selectedCmd = allCommands[selectedIndex]
+      if (selectedCmd && !selectedCmd.disabled) {
+        executeCommand(selectedCmd)
+      }
+      return state
+    }
+
+    case 'escape': {
+      if (onClose) {
+        onClose()
+      }
+      return state
+    }
+
+    case 'backspace': {
+      if (searchQuery && onQueryChange) {
+        onQueryChange(searchQuery.slice(0, -1))
+      }
+      return { ...state, searchQuery: searchQuery.slice(0, -1), selectedIndex: 0 }
+    }
+
+    case 'ctrl+u': {
+      if (onQueryChange) {
+        onQueryChange('')
+      }
+      return { ...state, searchQuery: '', selectedIndex: 0 }
+    }
+
+    default: {
+      // Typing a character
+      if (key.length === 1 && /[a-zA-Z0-9 ]/.test(key)) {
+        const newQuery = searchQuery + key
+        if (onQueryChange) {
+          onQueryChange(newQuery)
+        }
+        return { ...state, searchQuery: newQuery, selectedIndex: 0 }
+      }
+      return state
+    }
+  }
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function stripAnsi(str: string): string {
+  return str.replace(/\x1b\[[\d;]*m/g, '')
+}
+
+// ============================================================================
+// Router Integration Functions
+// ============================================================================
+
+/**
+ * Creates navigation commands from route definitions.
+ * Useful for generating commands from a list of routes/pages.
+ *
+ * @param routes - Array of route definitions
+ * @returns Array of Command objects with navigation action type
+ */
+export function navigationCommandsFromRoutes(
+  routes: Array<{
+    path: string
+    label: string
+    description?: string
+    icon?: string
+    shortcut?: string
+    keywords?: string[]
+    category?: string
+  }>
+): Command[] {
+  return routes.map((route) => ({
+    id: `nav:${route.path}`,
+    label: route.label,
+    description: route.description,
+    icon: route.icon,
+    shortcut: route.shortcut,
+    keywords: route.keywords,
+    category: route.category || 'Navigation',
+    path: route.path,
+    actionType: 'navigate' as const,
+  }))
+}
+
+/**
+ * Creates a command execution handler that integrates with a router adapter.
+ * Navigation commands will be handled by the router, action commands by the callback.
+ *
+ * @param commands - Array of commands (needed to look up command details by ID)
+ * @param router - Router adapter instance
+ * @param onAction - Callback for non-navigation actions
+ * @returns Command selection handler function
+ */
+export function createRouterCommandHandler(
+  commands: Command[],
+  router: RouterAdapter,
+  onAction?: (commandId: string, command: Command) => void
+): (commandId: string) => void {
+  return (commandId: string) => {
+    const command = commands.find((c) => c.id === commandId)
+    if (!command) return
+
+    // Check if this is a navigation command
+    const isNavigationCommand = command.actionType === 'navigate' || (command.path && !command.actionType)
+
+    if (isNavigationCommand && command.path) {
+      router.navigate(command.path)
+    } else if (onAction) {
+      onAction(commandId, command)
+    }
+  }
+}
+
+/**
+ * Filters commands to only include navigation commands.
+ * Useful for creating a page navigation palette.
+ *
+ * @param commands - Array of commands
+ * @returns Array of navigation-only commands
+ */
+export function getNavigationCommands(commands: Command[]): Command[] {
+  return commands.filter((cmd) => cmd.actionType === 'navigate' || cmd.path)
+}
+
+/**
+ * Filters commands to only include action commands.
+ * Useful for creating an actions palette.
+ *
+ * @param commands - Array of commands
+ * @returns Array of action-only commands
+ */
+export function getActionCommands(commands: Command[]): Command[] {
+  return commands.filter((cmd) => cmd.actionType === 'action' || (!cmd.path && !cmd.actionType))
+}