@mdxui/terminal 2.0.0

package/src/renderers/breadcrumb.ts

@@ -0,0 +1,480 @@
+/**
+ * @mdxui/terminal Breadcrumb Renderer
+ *
+ * Multi-tier renderer for breadcrumb navigation component.
+ * Supports all 6 tiers: text, markdown, ascii, unicode, ansi, interactive.
+ */
+
+import type { UINode, RenderContext, RenderTier } from '../core/types'
+import {
+  generateBreadcrumbSegments,
+  formatSegmentLabel,
+  type RouterAdapter,
+  type RouteMatchMode,
+} 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 BreadcrumbSegment {
+  label: string
+  path?: string
+  icon?: string
+}
+
+interface BreadcrumbProps {
+  segments: BreadcrumbSegment[]
+  separator?: string
+  maxItems?: number
+  showHome?: boolean
+  homeLabel?: string
+  homeIcon?: string
+  onNavigate?: (path: string) => void
+  /** Current route path - if provided, segments can be auto-generated */
+  currentPath?: string
+  /** Custom labels for specific paths (used with currentPath) */
+  pathLabels?: Record<string, string>
+  /** Router adapter for framework integration */
+  router?: RouterAdapter
+}
+
+interface BreadcrumbState {
+  segments: BreadcrumbSegment[]
+  focusedIndex: number
+  wrapNavigation?: boolean
+  onNavigate?: (path: string) => void
+  onBlur?: () => void
+  /** Router adapter for framework integration */
+  router?: RouterAdapter
+}
+
+// ============================================================================
+// Tier-specific Separators
+// ============================================================================
+
+function getSeparator(tier: RenderTier, customSeparator?: string): string {
+  if (customSeparator) return customSeparator
+
+  switch (tier) {
+    case 'text':
+      return ' / '
+    case 'markdown':
+      return ' / '
+    case 'ascii':
+      return ' > '
+    case 'unicode':
+    case 'ansi':
+    case 'interactive':
+      return ' \u203A ' // Single right-pointing angle quotation mark
+    default:
+      return ' / '
+  }
+}
+
+// ============================================================================
+// Main Render Function
+// ============================================================================
+
+export function renderBreadcrumb(node: UINode, ctx: RenderContext): string {
+  const props = node.props as unknown as BreadcrumbProps
+  let { segments, separator, maxItems, showHome, homeLabel, homeIcon, currentPath, pathLabels, router } = props
+
+  // Generate segments from currentPath if not provided
+  if ((!segments || segments.length === 0) && currentPath) {
+    segments = generateBreadcrumbSegments(currentPath, {
+      labels: pathLabels,
+      includeHome: showHome !== false,
+      homeLabel: homeLabel || 'Home',
+    })
+    // Don't add home again if we just generated segments with home
+    showHome = false
+  }
+  // Also try to get path from router if no segments provided
+  if ((!segments || segments.length === 0) && router) {
+    const routerPath = router.getCurrentPath()
+    segments = generateBreadcrumbSegments(routerPath, {
+      labels: pathLabels,
+      includeHome: showHome !== false,
+      homeLabel: homeLabel || 'Home',
+    })
+    // Don't add home again if we just generated segments with home
+    showHome = false
+  }
+
+  if (!segments || segments.length === 0) {
+    return ''
+  }
+
+  const tier = ctx.tier
+  const maxWidth = ctx.width || 80
+
+  // Prepend home segment if requested
+  if (showHome) {
+    const homeSegment: BreadcrumbSegment = {
+      label: homeLabel || 'Home',
+      path: '/',
+      icon: homeIcon,
+    }
+    segments = [homeSegment, ...segments]
+  }
+
+  // Handle truncation with maxItems
+  let displaySegments = segments
+  let showEllipsis = false
+
+  if (maxItems && segments.length > maxItems) {
+    // Show first, ellipsis, and last (maxItems - 1) segments
+    const firstSegment = segments[0]
+    const lastSegments = segments.slice(-(maxItems - 1))
+    displaySegments = [firstSegment, ...lastSegments]
+    showEllipsis = true
+  }
+
+  // Get the separator for this tier
+  const sep = getSeparator(tier, separator)
+
+  // Render segments
+  const parts: string[] = []
+
+  for (let i = 0; i < displaySegments.length; i++) {
+    // Insert ellipsis after first segment if needed
+    if (showEllipsis && i === 1) {
+      const ellipsis = tier === 'unicode' || tier === 'ansi' || tier === 'interactive' ? '\u2026' : '...'
+      parts.push(ellipsis)
+    }
+
+    const segment = displaySegments[i]
+    const isLast = i === displaySegments.length - 1
+    const hasPath = !!segment.path && !isLast
+
+    parts.push(renderSegment(segment, isLast, hasPath, tier, ctx))
+  }
+
+  let result = parts.join(sep)
+
+  // Apply width truncation
+  const stripped = stripAnsi(result)
+  if (stripped.length > maxWidth) {
+    result = truncateResult(result, segments, maxWidth, tier, ctx)
+  }
+
+  return result
+}
+
+// ============================================================================
+// Segment Rendering
+// ============================================================================
+
+function renderSegment(
+  segment: BreadcrumbSegment,
+  isCurrent: boolean,
+  hasPath: boolean,
+  tier: RenderTier,
+  ctx: RenderContext
+): string {
+  let label = segment.label
+
+  // Add icon for unicode/ansi/interactive tiers
+  if (segment.icon && (tier === 'unicode' || tier === 'ansi' || tier === 'interactive')) {
+    label = segment.icon + ' ' + label
+  }
+
+  switch (tier) {
+    case 'text':
+      return label
+
+    case 'markdown':
+      if (hasPath && segment.path) {
+        return `[${segment.label}](${segment.path})`
+      }
+      return label
+
+    case 'ascii':
+      return label
+
+    case 'unicode':
+      return label
+
+    case 'ansi':
+      if (isCurrent) {
+        return BOLD + label + RESET
+      }
+      if (hasPath) {
+        return ctx.theme.primary + UNDERLINE + label + RESET
+      }
+      return label
+
+    case 'interactive':
+      if (isCurrent) {
+        return BOLD + label + RESET
+      }
+      if (hasPath) {
+        return ctx.theme.primary + UNDERLINE + label + RESET
+      }
+      return label
+
+    default:
+      return label
+  }
+}
+
+// ============================================================================
+// Truncation
+// ============================================================================
+
+function truncateResult(
+  result: string,
+  segments: BreadcrumbSegment[],
+  maxWidth: number,
+  tier: RenderTier,
+  ctx: RenderContext
+): string {
+  // For very narrow widths, just return ellipsis
+  if (maxWidth < 10) {
+    return tier === 'unicode' || tier === 'ansi' || tier === 'interactive' ? '\u2026' : '...'
+  }
+
+  // Try to truncate individual segment labels
+  const ellipsis = tier === 'unicode' || tier === 'ansi' || tier === 'interactive' ? '\u2026' : '...'
+  const sep = getSeparator(tier, undefined)
+
+  // Truncate long labels
+  const truncatedParts: string[] = []
+  const targetLabelWidth = Math.floor((maxWidth - (segments.length - 1) * sep.length) / segments.length)
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+    const isLast = i === segments.length - 1
+    const hasPath = !!segment.path && !isLast
+
+    let label = segment.label
+    if (label.length > targetLabelWidth && targetLabelWidth > 3) {
+      label = label.slice(0, targetLabelWidth - 1) + ellipsis
+    }
+
+    const modifiedSegment = { ...segment, label }
+    truncatedParts.push(renderSegment(modifiedSegment, isLast, hasPath, tier, ctx))
+  }
+
+  const truncatedResult = truncatedParts.join(sep)
+  const stripped = stripAnsi(truncatedResult)
+
+  // Final truncation if still too long
+  if (stripped.length > maxWidth) {
+    return truncateLine(truncatedResult, maxWidth, tier)
+  }
+
+  return truncatedResult
+}
+
+function truncateLine(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
+
+  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
+}
+
+function stripAnsi(str: string): string {
+  return str.replace(/\x1b\[[\d;]*m/g, '')
+}
+
+// ============================================================================
+// Keyboard Bindings
+// ============================================================================
+
+export function getBreadcrumbKeyBindings(): Record<string, string> {
+  return {
+    h: 'focus-prev',
+    l: 'focus-next',
+    left: 'focus-prev',
+    right: 'focus-next',
+    enter: 'navigate',
+    escape: 'blur',
+    home: 'focus-first',
+    end: 'focus-last',
+  }
+}
+
+// ============================================================================
+// State Management
+// ============================================================================
+
+export function createBreadcrumbState(config: {
+  segments: BreadcrumbSegment[]
+  focusedIndex?: number
+  wrapNavigation?: boolean
+  onNavigate?: (path: string) => void
+  onBlur?: () => void
+  /** Router adapter for framework integration */
+  router?: RouterAdapter
+}): BreadcrumbState {
+  const { segments, focusedIndex, wrapNavigation, onNavigate, onBlur, router } = config
+
+  return {
+    segments,
+    focusedIndex: focusedIndex ?? 0,
+    wrapNavigation,
+    onNavigate,
+    onBlur,
+    router,
+  }
+}
+
+export function handleBreadcrumbKey(state: BreadcrumbState, key: string): BreadcrumbState {
+  const { segments, focusedIndex, wrapNavigation, onNavigate, onBlur, router } = state
+  const maxIndex = segments.length - 1
+
+  switch (key) {
+    case 'l':
+    case 'right': {
+      let newIndex = focusedIndex + 1
+      if (newIndex > maxIndex) {
+        newIndex = wrapNavigation ? 0 : maxIndex
+      }
+      return { ...state, focusedIndex: newIndex }
+    }
+
+    case 'h':
+    case 'left': {
+      let newIndex = focusedIndex - 1
+      if (newIndex < 0) {
+        newIndex = wrapNavigation ? maxIndex : 0
+      }
+      return { ...state, focusedIndex: newIndex }
+    }
+
+    case 'home': {
+      return { ...state, focusedIndex: 0 }
+    }
+
+    case 'end': {
+      return { ...state, focusedIndex: maxIndex }
+    }
+
+    case 'enter': {
+      const segment = segments[focusedIndex]
+      const isLast = focusedIndex === maxIndex
+      if (segment && segment.path && !isLast) {
+        // Use router adapter if available, otherwise use callback
+        if (router) {
+          router.navigate(segment.path)
+        } else if (onNavigate) {
+          onNavigate(segment.path)
+        }
+      }
+      return state
+    }
+
+    case 'escape': {
+      if (onBlur) {
+        onBlur()
+      }
+      return state
+    }
+
+    default:
+      return state
+  }
+}
+
+// ============================================================================
+// Click Handler
+// ============================================================================
+
+export function handleBreadcrumbClick(state: BreadcrumbState, index: number): void {
+  const { segments, onNavigate, router } = state
+  const segment = segments[index]
+  const isLast = index === segments.length - 1
+
+  if (segment && segment.path && !isLast) {
+    // Use router adapter if available, otherwise use callback
+    if (router) {
+      router.navigate(segment.path)
+    } else if (onNavigate) {
+      onNavigate(segment.path)
+    }
+  }
+}
+
+// ============================================================================
+// Router Integration Functions
+// ============================================================================
+
+/**
+ * Generates breadcrumb segments from a URL path.
+ * This is a convenience re-export of the utility function.
+ *
+ * @param path - URL path (e.g., '/products/electronics/phones')
+ * @param options - Configuration for segment generation
+ * @returns Array of breadcrumb segments with labels and paths
+ */
+export function breadcrumbsFromPath(
+  path: string,
+  options?: {
+    labels?: Record<string, string>
+    labelGenerator?: (segment: string, fullPath: string) => string
+    includeHome?: boolean
+    homeLabel?: string
+  }
+): BreadcrumbSegment[] {
+  return generateBreadcrumbSegments(path, options)
+}
+
+/**
+ * Creates a navigation handler that integrates with a router adapter.
+ * Returns a function compatible with the onNavigate callback.
+ *
+ * @param router - Router adapter instance
+ * @param fallback - Optional fallback handler if router navigation fails
+ * @returns Navigation handler function
+ */
+export function createRouterNavigationHandler(
+  router: RouterAdapter,
+  fallback?: (path: string) => void
+): (path: string) => void {
+  return (path: string) => {
+    router.navigate(path)
+    fallback?.(path)
+  }
+}