@mdxui/terminal 2.0.0

package/src/renderers/tabs.ts

@@ -0,0 +1,682 @@
+/**
+ * @mdxui/terminal Tabs Renderer
+ *
+ * Multi-tier renderer for tabs navigation component.
+ * Supports all 6 tiers: text, markdown, ascii, unicode, ansi, interactive.
+ */
+
+import type { UINode, RenderContext, RenderTier } from '../core/types'
+import {
+  matchPath,
+  findActiveItemByPath,
+  type RouteMatchMode,
+  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 Tab {
+  id: string
+  label: string
+  icon?: string
+  badge?: string | number
+  disabled?: boolean
+  content?: string | UINode
+  /** Path associated with this tab for route-based switching */
+  path?: string
+}
+
+interface TabsProps {
+  tabs: Tab[]
+  activeId: string
+  variant?: 'default' | 'pills' | 'underline'
+  orientation?: 'horizontal' | 'vertical'
+  onTabChange?: (tabId: string) => void
+  /** Current route path for automatic active tab detection */
+  currentPath?: string
+  /** Route matching mode: 'exact', 'prefix', or 'pattern' */
+  routeMatchMode?: RouteMatchMode
+  /** Router adapter for framework integration */
+  router?: RouterAdapter
+}
+
+interface TabsState {
+  tabs: Tab[]
+  activeId: string
+  focusedId: string
+  orientation?: 'horizontal' | 'vertical'
+  wrapNavigation?: boolean
+  onTabChange?: (tabId: string) => void
+  activationMode?: 'automatic' | 'manual'
+  /** Current route path for automatic active detection */
+  currentPath?: string
+  /** Route matching mode */
+  routeMatchMode?: RouteMatchMode
+  /** Router adapter for framework integration */
+  router?: RouterAdapter
+}
+
+// ============================================================================
+// Main Render Function
+// ============================================================================
+
+export function renderTabs(node: UINode, ctx: RenderContext): string {
+  const props = node.props as unknown as TabsProps
+  const {
+    activeId: providedActiveId,
+    variant = 'default',
+    orientation = 'horizontal',
+    currentPath,
+    routeMatchMode = 'exact',
+    router,
+  } = props
+
+  // Extract tabs from node structure
+  const tabs = extractTabs(node)
+
+  if (!tabs || tabs.length === 0) {
+    return ''
+  }
+
+  // Determine active tab ID - prefer explicit activeId, then route-based detection
+  let activeId: string = providedActiveId || ''
+  if (!activeId && currentPath) {
+    activeId = findActiveTabByPath(tabs, currentPath, routeMatchMode) || ''
+  }
+  if (!activeId && router) {
+    const routerPath = router.getCurrentPath()
+    activeId = findActiveTabByPath(tabs, routerPath, routeMatchMode) || ''
+  }
+  // Fallback to first tab if no active found
+  if (!activeId && tabs.length > 0) {
+    activeId = tabs[0].id
+  }
+
+  const tier = ctx.tier
+  const maxWidth = ctx.width || 80
+  const lines: string[] = []
+
+  // Render tab list
+  const tabList = renderTabList(tabs, activeId, variant, orientation, tier, ctx, maxWidth)
+  lines.push(...tabList)
+
+  // Render active tab content
+  const activeTab = tabs.find((t) => t.id === activeId)
+  if (activeTab && activeTab.content) {
+    lines.push('') // Separator
+    const contentStr = renderTabContent(activeTab.content, tier, ctx)
+    if (contentStr) {
+      lines.push(contentStr)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+// ============================================================================
+// Tab Extraction
+// ============================================================================
+
+function extractTabs(node: UINode): Tab[] {
+  const props = node.props as unknown as TabsProps
+  if (props.tabs) {
+    return props.tabs
+  }
+
+  // Extract from children if structured as tab-list
+  const tabs: Tab[] = []
+  const rawChildren = node.children
+  const children: UINode[] = Array.isArray(rawChildren) ? rawChildren : []
+
+  for (const child of children) {
+    if (child.type === 'tab-list') {
+      const rawTabItems = child.children
+      const tabItems: UINode[] = Array.isArray(rawTabItems) ? rawTabItems : []
+      for (const tabItem of tabItems) {
+        if (tabItem.type === 'tab') {
+          const tabItemProps = tabItem.props || {}
+          tabs.push({
+            id: tabItemProps.id as string,
+            label: tabItemProps.label as string,
+            icon: tabItemProps.icon as string | undefined,
+            badge: tabItemProps.badge as string | number | undefined,
+            disabled: tabItemProps.disabled as boolean | undefined,
+          })
+        }
+      }
+    } else if (child.type === 'tab-panel') {
+      // Find corresponding tab and attach content
+      const childProps = child.props || {}
+      const tabId = childProps.tabId as string
+      const tab = tabs.find((t) => t.id === tabId)
+      if (tab) {
+        const rawPanelChildren = child.children
+        const panelChildren: UINode[] = Array.isArray(rawPanelChildren) ? rawPanelChildren : []
+        if (panelChildren.length > 0) {
+          const textChild = panelChildren[0]
+          if (textChild.type === 'text') {
+            const textChildProps = textChild.props || {}
+            tab.content = textChildProps.content as string
+          } else {
+            tab.content = textChild
+          }
+        }
+      }
+    }
+  }
+
+  return tabs
+}
+
+// ============================================================================
+// Tab List Rendering
+// ============================================================================
+
+function renderTabList(
+  tabs: Tab[],
+  activeId: string,
+  variant: 'default' | 'pills' | 'underline',
+  orientation: 'horizontal' | 'vertical',
+  tier: RenderTier,
+  ctx: RenderContext,
+  maxWidth: number
+): string[] {
+  const lines: string[] = []
+
+  if (orientation === 'vertical') {
+    // Vertical: each tab on its own line
+    for (const tab of tabs) {
+      const isActive = tab.id === activeId
+      const tabStr = renderSingleTab(tab, isActive, variant, tier, ctx)
+      lines.push(tabStr)
+    }
+    return lines
+  }
+
+  // Horizontal: all tabs on one line
+  const tabParts: string[] = []
+  const underlineParts: string[] = []
+
+  for (const tab of tabs) {
+    const isActive = tab.id === activeId
+    const tabStr = renderSingleTab(tab, isActive, variant, tier, ctx)
+    tabParts.push(tabStr)
+
+    // For underline variant, track underline parts
+    if (variant === 'underline' && tier !== 'text' && tier !== 'markdown') {
+      const labelLen = stripAnsi(tabStr).length
+      if (isActive) {
+        const underlineChar = tier === 'ascii' ? '-' : '\u2500'
+        underlineParts.push(underlineChar.repeat(labelLen))
+      } else {
+        underlineParts.push(' '.repeat(labelLen))
+      }
+    }
+  }
+
+  // Join tabs with separator
+  const separator = tier === 'text' || tier === 'markdown' || tier === 'ascii' ? ' | ' : ' \u2502 '
+  let tabLine = tabParts.join(separator)
+  let finalParts = tabParts
+
+  // Check if we need to truncate individual tab labels (when total is too wide)
+  let currentWidth = stripAnsi(tabLine).length
+  if (currentWidth > maxWidth) {
+    // Truncate individual tab labels
+    const truncatedParts: string[] = []
+    const separatorWidth = separator.length
+    const availableForTabs = maxWidth - (separatorWidth * (tabs.length - 1))
+    const maxLabelWidth = Math.max(5, Math.floor(availableForTabs / tabs.length) - 4) // Reserve space for styling
+
+    for (const tab of tabs) {
+      const isActive = tab.id === activeId
+      let label = tab.label
+
+      // Truncate label if too long
+      if (label.length > maxLabelWidth) {
+        const ellipsis = tier === 'unicode' || tier === 'ansi' || tier === 'interactive' ? '\u2026' : '...'
+        label = label.slice(0, maxLabelWidth - 1) + ellipsis
+      }
+
+      const truncatedTab: Tab = { ...tab, label }
+      const tabStr = renderSingleTab(truncatedTab, isActive, variant, tier, ctx)
+      truncatedParts.push(tabStr)
+    }
+
+    tabLine = truncatedParts.join(separator)
+    finalParts = truncatedParts
+  }
+
+  // Stretch tabs to fill available width (only add modest padding)
+  currentWidth = stripAnsi(tabLine).length
+  if (currentWidth < maxWidth && tabs.length > 1) {
+    const extraSpace = maxWidth - currentWidth
+    const paddingPerSide = Math.min(4, Math.floor(extraSpace / (2 * (tabs.length - 1))))
+    if (paddingPerSide > 0) {
+      const paddedParts = finalParts.map((part, idx) => {
+        if (idx === 0) return part + ' '.repeat(paddingPerSide)
+        if (idx === finalParts.length - 1) return ' '.repeat(paddingPerSide) + part
+        return ' '.repeat(paddingPerSide) + part + ' '.repeat(paddingPerSide)
+      })
+      tabLine = paddedParts.join(separator)
+    }
+  }
+
+  lines.push(tabLine)
+
+  // Add underline row for underline variant
+  if (variant === 'underline' && underlineParts.length > 0) {
+    const underlineSep = ' '.repeat(separator.length)
+    lines.push(underlineParts.join(underlineSep))
+  }
+
+  return lines
+}
+
+function renderSingleTab(
+  tab: Tab,
+  isActive: boolean,
+  variant: 'default' | 'pills' | 'underline',
+  tier: RenderTier,
+  ctx: RenderContext
+): string {
+  let label = tab.label
+
+  // Add icon for unicode/ansi/interactive
+  if (tab.icon && (tier === 'unicode' || tier === 'ansi' || tier === 'interactive')) {
+    label = tab.icon + ' ' + label
+  }
+
+  // Add badge
+  if (tab.badge !== undefined) {
+    label = label + ` (${tab.badge})`
+  }
+
+  // Text tier
+  if (tier === 'text') {
+    if (tab.disabled) {
+      return `${label} (disabled)`
+    }
+    return isActive ? `[${label}]` : label
+  }
+
+  // Markdown tier
+  if (tier === 'markdown') {
+    if (tab.disabled) {
+      return `~${label}~`
+    }
+    return isActive ? `**${label}**` : label
+  }
+
+  // ASCII tier
+  if (tier === 'ascii') {
+    if (tab.disabled) {
+      return `${label} (disabled)`
+    }
+    if (variant === 'pills' && isActive) {
+      return `( ${label} )`
+    }
+    return isActive ? `[${label}]` : label
+  }
+
+  // Unicode tier
+  if (tier === 'unicode') {
+    if (tab.disabled) {
+      return label
+    }
+    if (variant === 'pills' && isActive) {
+      return `\u256D ${label} \u256E`
+    }
+    return label
+  }
+
+  // ANSI tier
+  if (tier === 'ansi') {
+    if (tab.disabled) {
+      return ctx.theme.muted + label + RESET
+    }
+    if (isActive) {
+      return ctx.theme.primary + BOLD + label + RESET
+    }
+    return label
+  }
+
+  // Interactive tier
+  if (tier === 'interactive') {
+    if (tab.disabled) {
+      return ctx.theme.muted + label + RESET
+    }
+    if (isActive) {
+      return INVERSE + label + RESET
+    }
+    return label
+  }
+
+  return label
+}
+
+// ============================================================================
+// Tab Content Rendering
+// ============================================================================
+
+function renderTabContent(content: string | UINode, tier: RenderTier, ctx: RenderContext): string {
+  if (typeof content === 'string') {
+    return content
+  }
+
+  const contentProps = content.props || {}
+
+  // For UINode content, render recursively
+  if (content.type === 'text') {
+    return contentProps.content as string
+  }
+
+  // For complex nodes, render their text content
+  if (content.type === 'box') {
+    const rawChildren = content.children
+    const children: UINode[] = Array.isArray(rawChildren) ? rawChildren : []
+    const parts: string[] = []
+    for (const child of children) {
+      if (child.type === 'text') {
+        const childProps = child.props || {}
+        parts.push(childProps.content as string)
+      }
+    }
+    return parts.join('\n')
+  }
+
+  return ''
+}
+
+// ============================================================================
+// Keyboard Bindings
+// ============================================================================
+
+export function getTabsKeyBindings(): Record<string, string> {
+  return {
+    left: 'focus-prev',
+    right: 'focus-next',
+    h: 'focus-prev',
+    l: 'focus-next',
+    j: 'focus-next', // For vertical orientation
+    k: 'focus-prev', // For vertical orientation
+    enter: 'activate',
+    space: 'activate',
+    home: 'focus-first',
+    end: 'focus-last',
+  }
+}
+
+// ============================================================================
+// State Management
+// ============================================================================
+
+export function createTabsState(config: {
+  tabs: Tab[]
+  activeId: string
+  focusedId?: string
+  orientation?: 'horizontal' | 'vertical'
+  wrapNavigation?: boolean
+  onTabChange?: (tabId: string) => void
+  activationMode?: 'automatic' | 'manual'
+  /** Current route path for automatic active detection */
+  currentPath?: string
+  /** Route matching mode */
+  routeMatchMode?: RouteMatchMode
+  /** Router adapter for framework integration */
+  router?: RouterAdapter
+}): TabsState {
+  const {
+    tabs,
+    activeId,
+    focusedId,
+    orientation,
+    wrapNavigation,
+    onTabChange,
+    activationMode,
+    currentPath,
+    routeMatchMode,
+    router,
+  } = config
+
+  return {
+    tabs,
+    activeId,
+    focusedId: focusedId || activeId,
+    orientation,
+    wrapNavigation,
+    onTabChange,
+    activationMode: activationMode || 'manual',
+    currentPath,
+    routeMatchMode,
+    router,
+  }
+}
+
+export function handleTabsKey(state: TabsState, key: string): TabsState {
+  const { tabs, focusedId, orientation, wrapNavigation, onTabChange, activationMode, router } = state
+  const enabledTabs = tabs.filter((t) => !t.disabled)
+
+  // Helper to handle tab activation (with router support)
+  const activateTab = (tabId: string): void => {
+    const tab = tabs.find((t) => t.id === tabId)
+    // Use router adapter if available and tab has a path, otherwise use callback
+    if (tab?.path && router) {
+      router.navigate(tab.path)
+    } else if (onTabChange) {
+      onTabChange(tabId)
+    }
+  }
+  const focusedIndex = enabledTabs.findIndex((t) => t.id === focusedId)
+
+  // Determine movement keys based on orientation
+  const isVertical = orientation === 'vertical'
+  const nextKeys = isVertical ? ['j', 'down'] : ['l', 'right']
+  const prevKeys = isVertical ? ['k', 'up'] : ['h', 'left']
+
+  if (nextKeys.includes(key)) {
+    let newIndex = focusedIndex + 1
+    if (newIndex >= enabledTabs.length) {
+      newIndex = wrapNavigation ? 0 : enabledTabs.length - 1
+    }
+    const newFocusedId = enabledTabs[newIndex]?.id || focusedId
+
+    // Automatic activation
+    if (activationMode === 'automatic' && newFocusedId !== focusedId) {
+      activateTab(newFocusedId)
+      return { ...state, focusedId: newFocusedId, activeId: newFocusedId }
+    }
+
+    return { ...state, focusedId: newFocusedId }
+  }
+
+  if (prevKeys.includes(key)) {
+    let newIndex = focusedIndex - 1
+    if (newIndex < 0) {
+      newIndex = wrapNavigation ? enabledTabs.length - 1 : 0
+    }
+    const newFocusedId = enabledTabs[newIndex]?.id || focusedId
+
+    // Automatic activation
+    if (activationMode === 'automatic' && newFocusedId !== focusedId) {
+      activateTab(newFocusedId)
+      return { ...state, focusedId: newFocusedId, activeId: newFocusedId }
+    }
+
+    return { ...state, focusedId: newFocusedId }
+  }
+
+  switch (key) {
+    case 'home': {
+      const firstTab = enabledTabs[0]
+      if (firstTab) {
+        return { ...state, focusedId: firstTab.id }
+      }
+      return state
+    }
+
+    case 'end': {
+      const lastTab = enabledTabs[enabledTabs.length - 1]
+      if (lastTab) {
+        return { ...state, focusedId: lastTab.id }
+      }
+      return state
+    }
+
+    case 'enter':
+    case 'space': {
+      activateTab(focusedId)
+      return { ...state, activeId: focusedId }
+    }
+
+    default:
+      return state
+  }
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function stripAnsi(str: string): string {
+  return str.replace(/\x1b\[[\d;]*m/g, '')
+}
+
+function truncateToWidth(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
+}
+
+// ============================================================================
+// Router Integration Functions
+// ============================================================================
+
+/**
+ * Finds the active tab ID based on the current route path.
+ * Tabs with `path` property will be matched against the current path.
+ *
+ * @param tabs - Array of tabs with optional path property
+ * @param currentPath - Current route path
+ * @param mode - Route matching mode ('exact', 'prefix', or 'pattern')
+ * @returns The ID of the matching tab, or undefined if no match
+ */
+export function findActiveTabByPath(
+  tabs: Tab[],
+  currentPath: string,
+  mode: RouteMatchMode = 'exact'
+): string | undefined {
+  // Filter to tabs that have paths
+  const tabsWithPaths = tabs.filter((t) => t.path)
+  return findActiveItemByPath(tabsWithPaths, currentPath, mode)
+}
+
+/**
+ * Checks if a specific tab is active based on the current route.
+ *
+ * @param tab - Tab to check
+ * @param currentPath - Current route path
+ * @param mode - Route matching mode
+ * @returns true if the tab is active
+ */
+export function isTabActiveByRoute(
+  tab: Tab,
+  currentPath: string,
+  mode: RouteMatchMode = 'exact'
+): boolean {
+  if (!tab.path) return false
+  return matchPath(currentPath, tab.path, mode)
+}
+
+/**
+ * Creates a tab change handler that integrates with a router adapter.
+ * Returns a function compatible with the onTabChange callback.
+ *
+ * @param tabs - Array of tabs (needed to look up paths by ID)
+ * @param router - Router adapter instance
+ * @param fallback - Optional fallback handler if router navigation fails
+ * @returns Tab change handler function
+ */
+export function createRouterTabChangeHandler(
+  tabs: Tab[],
+  router: RouterAdapter,
+  fallback?: (tabId: string) => void
+): (tabId: string) => void {
+  return (tabId: string) => {
+    const tab = tabs.find((t) => t.id === tabId)
+    if (tab?.path) {
+      router.navigate(tab.path)
+    } else if (fallback) {
+      fallback(tabId)
+    }
+  }
+}
+
+/**
+ * Creates tabs from route definitions.
+ * Useful for generating tabs from a list of routes.
+ *
+ * @param routes - Array of route definitions
+ * @param labelGenerator - Optional function to generate labels from paths
+ * @returns Array of Tab objects
+ */
+export function tabsFromRoutes(
+  routes: Array<{
+    path: string
+    label?: string
+    icon?: string
+    disabled?: boolean
+  }>,
+  labelGenerator?: (path: string) => string
+): Tab[] {
+  return routes.map((route, index) => ({
+    id: route.path || `tab-${index}`,
+    label: route.label || (labelGenerator ? labelGenerator(route.path) : route.path),
+    path: route.path,
+    icon: route.icon,
+    disabled: route.disabled,
+  }))
+}