@mdxui/terminal 2.0.0

package/src/renderers/utils.ts

@@ -0,0 +1,942 @@
+/**
+ * Renderer Common Utilities
+ *
+ * Shared abstractions used across all 6-tier renderers (TEXT, MARKDOWN, ASCII, UNICODE, ANSI, INTERACTIVE).
+ * Extracted to ensure DRY principles and consistent behavior across renderers.
+ *
+ * Key abstractions:
+ * - Box drawing (ASCII/Unicode share logic)
+ * - Width/height calculations
+ * - Text alignment and wrapping
+ * - Indentation helpers
+ * - Character sanitization
+ * - Renderer registry pattern
+ */
+
+import type { UINode } from '../core/types'
+
+/**
+ * Box drawing character sets for different border styles
+ */
+export interface BoxChars {
+  topLeft: string
+  topRight: string
+  bottomLeft: string
+  bottomRight: string
+  horizontal: string
+  vertical: string
+}
+
+/**
+ * Text alignment options
+ */
+export type TextAlign = 'left' | 'center' | 'right'
+
+/**
+ * Indent calculation: returns a string of spaces for the given level
+ * Each level = 2 spaces
+ *
+ * @param level - Indentation level (0-based)
+ * @returns Indentation string (2 spaces per level)
+ */
+export function getIndentStr(level: number): string {
+  return '  '.repeat(Math.max(0, level))
+}
+
+/**
+ * Calculates visible text width by counting characters
+ * This is a basic implementation; use in TEXT/MARKDOWN tiers
+ *
+ * @param text - Text to measure
+ * @returns Character count (visible width)
+ */
+export function getTextWidth(text: string): number {
+  return text.length
+}
+
+/**
+ * Pads text to a given width for alignment
+ * Supports left/center/right alignment
+ *
+ * @param text - Text to pad
+ * @param width - Target width
+ * @param align - Alignment direction (default: 'left')
+ * @param padChar - Character to use for padding (default: space)
+ * @returns Padded text string
+ */
+export function padText(
+  text: string,
+  width: number,
+  align: TextAlign = 'left',
+  padChar: string = ' '
+): string {
+  const textLen = getTextWidth(text)
+  if (textLen >= width) {
+    return text.slice(0, width)
+  }
+
+  const totalPad = width - textLen
+  const padStr = padChar.repeat(totalPad)
+
+  switch (align) {
+    case 'center':
+      const leftPad = Math.floor(totalPad / 2)
+      const rightPad = totalPad - leftPad
+      return padChar.repeat(leftPad) + text + padChar.repeat(rightPad)
+
+    case 'right':
+      return padStr + text
+
+    case 'left':
+    default:
+      return text + padStr
+  }
+}
+
+/**
+ * Wraps text to fit within a given width, preserving words when possible.
+ * Handles explicit newlines and long words.
+ *
+ * @param text - Text to wrap
+ * @param maxWidth - Maximum line width
+ * @returns Array of wrapped lines
+ */
+export function wrapText(text: string, maxWidth: number): string[] {
+  if (maxWidth <= 0) {
+    return [text]
+  }
+
+  // Normalize whitespace
+  const normalized = text.replace(/[ \t]+/g, ' ')
+  const lines: string[] = []
+
+  // Handle explicit newlines first
+  const paragraphs = normalized.split('\n')
+
+  for (const paragraph of paragraphs) {
+    if (paragraph.length === 0) {
+      lines.push('')
+      continue
+    }
+
+    const words = paragraph.split(' ').filter((w) => w.length > 0)
+    let currentLine = ''
+
+    for (const word of words) {
+      if (word.length > maxWidth) {
+        // Word is too long, must break it
+        if (currentLine.length > 0) {
+          lines.push(currentLine)
+          currentLine = ''
+        }
+        // Break the long word
+        let remaining = word
+        while (remaining.length > maxWidth) {
+          lines.push(remaining.slice(0, maxWidth))
+          remaining = remaining.slice(maxWidth)
+        }
+        if (remaining.length > 0) {
+          currentLine = remaining
+        }
+      } else if (currentLine.length === 0) {
+        currentLine = word
+      } else if (currentLine.length + 1 + word.length <= maxWidth) {
+        currentLine += ' ' + word
+      } else {
+        lines.push(currentLine)
+        currentLine = word
+      }
+    }
+
+    if (currentLine.length > 0 || paragraph.length === 0) {
+      lines.push(currentLine)
+    }
+  }
+
+  return lines
+}
+
+/**
+ * Sanitizes text to ensure only ASCII characters (0x00-0x7F) are present.
+ * Replaces unicode characters with ASCII equivalents or removes them.
+ *
+ * @param text - Text to sanitize
+ * @returns ASCII-safe text string
+ */
+export function sanitizeToASCII(text: string): string {
+  let result = ''
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0
+    if (code <= 0x7f) {
+      result += char
+    } else if (char === '\u2022' || char === '\u25CF' || char === '\u25CB' || char === '\u25A0') {
+      // Unicode bullets -> ASCII
+      result += '*'
+    } else if (code >= 0x2500 && code <= 0x257f) {
+      // Unicode box drawing -> ASCII equivalents
+      result += boxDrawingToASCII(char)
+    } else if ((code >= 0x1f600 && code <= 0x1f64f) || code > 0x10000) {
+      // Emoji range and high unicode - remove
+      result += ''
+    } else {
+      // Other unicode - skip
+      result += ''
+    }
+  }
+  return result
+}
+
+/**
+ * Converts unicode box drawing character to ASCII equivalent
+ * Used by sanitizeToASCII and ASCII renderer
+ *
+ * @param char - Unicode box drawing character
+ * @returns ASCII equivalent or '+'
+ */
+export function boxDrawingToASCII(char: string): string {
+  const code = char.codePointAt(0) ?? 0
+  // Horizontal lines
+  if ([0x2500, 0x2501, 0x2504, 0x2505, 0x2508, 0x2509, 0x254c, 0x254d].includes(code)) {
+    return '-'
+  }
+  // Vertical lines
+  if ([0x2502, 0x2503, 0x2506, 0x2507, 0x250a, 0x250b, 0x254e, 0x254f].includes(code)) {
+    return '|'
+  }
+  // Corners and intersections -> +
+  return '+'
+}
+
+/**
+ * Builds a box (border + content) using provided box characters
+ * Shared logic for ASCII and Unicode renderers
+ *
+ * @param chars - Box characters (corners, edges)
+ * @param contentLines - Content lines to place inside box
+ * @param width - Total box width (including borders)
+ * @returns Array of box lines (ready to join with '\n')
+ */
+export function buildBox(chars: BoxChars, contentLines: string[], width: number): string[] {
+  // Handle zero or minimal dimensions
+  if (width <= 0) return []
+  if (width <= 2) return [chars.topLeft + chars.topRight]
+
+  const innerWidth = width - 2
+  const lines: string[] = []
+
+  // Top border
+  lines.push(chars.topLeft + chars.horizontal.repeat(innerWidth) + chars.topRight)
+
+  // Content lines
+  for (const lineContent of contentLines) {
+    const paddedContent = padText(lineContent, innerWidth, 'left')
+    lines.push(chars.vertical + paddedContent.slice(0, innerWidth) + chars.vertical)
+  }
+
+  // Bottom border
+  lines.push(chars.bottomLeft + chars.horizontal.repeat(innerWidth) + chars.bottomRight)
+
+  return lines
+}
+
+/**
+ * Extracts string values from mixed-type arrays
+ * Common pattern: converting items array to string array for rendering
+ *
+ * @param items - Array of unknown items
+ * @returns Array of string values
+ */
+export function extractStringArray(items: unknown[]): string[] {
+  if (!Array.isArray(items)) return []
+
+  return items.map((item) => {
+    if (typeof item === 'string') {
+      return item
+    }
+    if (typeof item === 'object' && item !== null && 'text' in item) {
+      return String((item as { text: string }).text)
+    }
+    return String(item)
+  })
+}
+
+/**
+ * Extracts headers from column definitions
+ * Common pattern: table renderers need to map columns to headers
+ *
+ * @param columns - Array of column definitions with 'header' property
+ * @returns Array of header strings
+ */
+export function extractHeaders(
+  columns: Array<{ header?: string; key?: string }> | undefined
+): string[] {
+  if (!Array.isArray(columns)) return []
+  return columns.map((col) => col.header || col.key || '')
+}
+
+/**
+ * Extracts values from a row using column keys
+ * Common pattern: table row rendering
+ *
+ * @param row - Object with row data
+ * @param columns - Array of column definitions with 'key' property
+ * @returns Array of row values as strings
+ */
+export function extractRowValues(
+  row: Record<string, unknown>,
+  columns: Array<{ key: string }> | undefined
+): string[] {
+  if (!Array.isArray(columns)) return []
+  return columns.map((col) => {
+    const val = row[col.key]
+    return val != null ? String(val) : ''
+  })
+}
+
+/**
+ * Combines multiple strings into a single output with separator
+ * Used for joining title, content, and footer sections
+ *
+ * @param parts - Array of string parts (filtered to remove empty)
+ * @param separator - String to join parts (default: '\n\n')
+ * @returns Joined string or empty string
+ */
+export function joinParts(parts: string[], separator: string = '\n\n'): string {
+  return parts.filter((p) => p.length > 0).join(separator)
+}
+
+/**
+ * Type-safe property access with default fallback
+ * Used throughout renderers to safely extract typed props
+ *
+ * @param obj - Object to access
+ * @param key - Property key
+ * @param defaultValue - Fallback value if undefined
+ * @returns Property value or default
+ */
+export function getProp<T>(
+  obj: Record<string, unknown>,
+  key: string,
+  defaultValue: T
+): T {
+  const val = obj[key]
+  return val === undefined ? defaultValue : (val as T)
+}
+
+/**
+ * Renderer registry pattern: allows dynamic renderer lookup
+ * Used by multi-tier rendering to delegate to appropriate renderer
+ */
+export type RendererRegistry = {
+  [tier in 'text' | 'markdown' | 'ascii' | 'unicode' | 'ansi' | 'interactive']?: (
+    node: any,
+    context?: any
+  ) => string
+}
+
+/**
+ * Theme token color constants
+ * Shared across renderers for theme support
+ */
+export const DEFAULT_THEME_TOKENS = {
+  primary: '',
+  secondary: '',
+  muted: '',
+  foreground: '',
+  background: '',
+  border: '',
+  success: '',
+  warning: '',
+  error: '',
+  info: '',
+} as const
+
+/**
+ * Default render context values
+ * Standard dimensions for terminal rendering
+ */
+export const DEFAULT_RENDER_CONTEXT = {
+  width: 80,
+  height: 24,
+  depth: 0,
+} as const
+
+// ============================================================================
+// Box Character Sets
+// ============================================================================
+
+/**
+ * ASCII box drawing characters
+ * Uses +, -, | for maximum compatibility
+ */
+export const ASCII_BOX_CHARS: BoxChars = {
+  topLeft: '+',
+  topRight: '+',
+  bottomLeft: '+',
+  bottomRight: '+',
+  horizontal: '-',
+  vertical: '|',
+}
+
+/**
+ * ASCII double-line box drawing characters
+ * Uses = for horizontal lines
+ */
+export const ASCII_DOUBLE_BOX_CHARS: BoxChars = {
+  topLeft: '+',
+  topRight: '+',
+  bottomLeft: '+',
+  bottomRight: '+',
+  horizontal: '=',
+  vertical: '|',
+}
+
+/**
+ * Unicode single-line box drawing characters
+ */
+export const UNICODE_SINGLE_BOX_CHARS: BoxChars = {
+  topLeft: '┌',
+  topRight: '┐',
+  bottomLeft: '└',
+  bottomRight: '┘',
+  horizontal: '─',
+  vertical: '│',
+}
+
+/**
+ * Unicode double-line box drawing characters
+ */
+export const UNICODE_DOUBLE_BOX_CHARS: BoxChars = {
+  topLeft: '╔',
+  topRight: '╗',
+  bottomLeft: '╚',
+  bottomRight: '╝',
+  horizontal: '═',
+  vertical: '║',
+}
+
+/**
+ * Unicode rounded box drawing characters
+ */
+export const UNICODE_ROUNDED_BOX_CHARS: BoxChars = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '─',
+  vertical: '│',
+}
+
+/**
+ * Gets ASCII box characters for a border style
+ *
+ * @param style - Border style: 'single', 'double', or 'none'
+ * @returns BoxChars for the specified style
+ */
+export function getASCIIBoxChars(style: string): BoxChars {
+  if (style === 'double') {
+    return ASCII_DOUBLE_BOX_CHARS
+  }
+  return ASCII_BOX_CHARS
+}
+
+/**
+ * Gets Unicode box characters for a border style
+ *
+ * @param style - Border style: 'single', 'double', 'rounded', or 'none'
+ * @returns BoxChars for the specified style
+ */
+export function getUnicodeBoxChars(style: string): BoxChars {
+  switch (style) {
+    case 'double':
+      return UNICODE_DOUBLE_BOX_CHARS
+    case 'rounded':
+      return UNICODE_ROUNDED_BOX_CHARS
+    case 'single':
+    default:
+      return UNICODE_SINGLE_BOX_CHARS
+  }
+}
+
+// ============================================================================
+// Unicode Symbol Constants
+// ============================================================================
+
+/**
+ * Unicode symbols for lists, progress, spinners, etc.
+ * Shared across Unicode and ANSI renderers
+ */
+export const UNICODE_SYMBOLS = {
+  // Bullets and list markers
+  bullet: '•',
+  hollowBullet: '◦',
+  squareBullet: '▪',
+  triangleRight: '▸',
+  triangleDown: '▾',
+  checkmark: '✓',
+  crossMark: '✗',
+  unchecked: '☐',
+  arrowRight: '→',
+  arrowDown: '↓',
+
+  // Progress bar characters
+  progressFull: '▓',
+  progressEmpty: '░',
+  progressHalf: '▒',
+
+  // Dividers
+  ellipsis: '…',
+  middleDot: '·',
+
+  // Table junction characters
+  teeLeft: '├',
+  teeRight: '┤',
+  teeTop: '┬',
+  teeBottom: '┴',
+  crossJunction: '┼',
+} as const
+
+/**
+ * Braille spinner animation frames
+ */
+export const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] as const
+
+// ============================================================================
+// Table Utilities
+// ============================================================================
+
+/**
+ * Calculates column widths for table rendering
+ *
+ * @param headers - Array of header strings
+ * @param rows - Array of row data (string arrays)
+ * @param maxTableWidth - Maximum allowed table width (optional)
+ * @returns Array of column widths
+ */
+export function calculateColumnWidths(
+  headers: string[],
+  rows: string[][],
+  maxTableWidth?: number
+): number[] {
+  const columnCount = Math.max(headers.length, ...rows.map((r) => r.length))
+  const colWidths: number[] = []
+
+  for (let i = 0; i < columnCount; i++) {
+    let maxWidth = headers[i]?.length ?? 0
+    for (const row of rows) {
+      const cellLen = (row[i] ?? '').length
+      maxWidth = Math.max(maxWidth, cellLen)
+    }
+    colWidths.push(maxWidth)
+  }
+
+  // Respect max table width if specified, but preserve header widths
+  // Headers should not be truncated - content may overflow instead
+  if (maxTableWidth && maxTableWidth > 0 && columnCount > 0) {
+    // Calculate minimum widths needed for headers
+    const headerWidths = headers.map((h) => h?.length ?? 0)
+
+    // +1 for each | and borders
+    const totalWidth = colWidths.reduce((a, b) => a + b, 0) + columnCount + 1
+    if (totalWidth > maxTableWidth) {
+      const availableForContent = maxTableWidth - columnCount - 1
+      const maxPerColumn = Math.max(1, Math.floor(availableForContent / columnCount))
+
+      for (let i = 0; i < colWidths.length; i++) {
+        // Ensure we keep at least the header width to prevent header truncation
+        const minWidth = headerWidths[i] ?? 1
+        colWidths[i] = Math.max(minWidth, Math.min(colWidths[i], maxPerColumn))
+      }
+    }
+  }
+
+  return colWidths
+}
+
+/**
+ * Builds a table separator line
+ *
+ * @param colWidths - Array of column widths
+ * @param chars - Characters for corners and horizontal line
+ * @returns Separator line string
+ */
+export function buildTableSeparator(
+  colWidths: number[],
+  chars: { left: string; middle: string; right: string; horizontal: string }
+): string {
+  return chars.left + colWidths.map((w) => chars.horizontal.repeat(w)).join(chars.middle) + chars.right
+}
+
+/**
+ * Builds a table row with cell content
+ *
+ * @param cells - Array of cell content strings
+ * @param colWidths - Array of column widths
+ * @param vertical - Vertical separator character
+ * @returns Row line string
+ */
+export function buildTableRow(cells: string[], colWidths: number[], vertical: string): string {
+  const parts = colWidths.map((w, i) => {
+    const cell = cells[i] ?? ''
+    const truncated = cell.length > w ? cell.slice(0, w) : cell
+    return truncated.padEnd(w)
+  })
+  return vertical + parts.join(vertical) + vertical
+}
+
+// ============================================================================
+// Router Utilities (Router-Agnostic Navigation Patterns)
+// ============================================================================
+
+/**
+ * Route matching mode for navigation components
+ */
+export type RouteMatchMode = 'exact' | 'prefix' | 'pattern'
+
+/**
+ * Router adapter interface - implement this to integrate with any router library
+ * This abstraction allows components to work with React Router, Next.js, Vue Router, etc.
+ */
+export interface RouterAdapter {
+  /** Get the current path/location */
+  getCurrentPath(): string
+  /** Navigate to a path */
+  navigate(path: string): void
+  /** Check if a path matches the current route */
+  isActive(path: string, mode?: RouteMatchMode): boolean
+  /** Subscribe to route changes (returns unsubscribe function) */
+  subscribe?(callback: (path: string) => void): () => void
+}
+
+/**
+ * Default router adapter that works without any router library
+ * Uses callbacks provided by the component user
+ */
+export function createCallbackRouterAdapter(config: {
+  currentPath?: string
+  onNavigate?: (path: string) => void
+}): RouterAdapter {
+  return {
+    getCurrentPath: () => config.currentPath || '/',
+    navigate: (path: string) => config.onNavigate?.(path),
+    isActive: (path: string, mode: RouteMatchMode = 'exact') => {
+      const current = config.currentPath || '/'
+      return matchPath(current, path, mode)
+    },
+  }
+}
+
+/**
+ * Matches a current path against a target path using the specified mode
+ *
+ * @param currentPath - The current route path
+ * @param targetPath - The path to match against
+ * @param mode - Match mode: 'exact', 'prefix', or 'pattern'
+ * @returns true if the paths match according to the mode
+ */
+export function matchPath(currentPath: string, targetPath: string, mode: RouteMatchMode = 'exact'): boolean {
+  // Normalize paths (remove trailing slashes, except for root)
+  const normCurrent = normalizePath(currentPath)
+  const normTarget = normalizePath(targetPath)
+
+  switch (mode) {
+    case 'exact':
+      return normCurrent === normTarget
+
+    case 'prefix':
+      // Root path only matches itself in prefix mode
+      if (normTarget === '/') {
+        return normCurrent === '/'
+      }
+      return normCurrent === normTarget || normCurrent.startsWith(normTarget + '/')
+
+    case 'pattern':
+      // Simple pattern matching with :param and * wildcards
+      return matchPathPattern(normCurrent, normTarget)
+
+    default:
+      return normCurrent === normTarget
+  }
+}
+
+/**
+ * Normalizes a path by removing trailing slashes (except for root)
+ *
+ * @param path - Path to normalize
+ * @returns Normalized path
+ */
+export function normalizePath(path: string): string {
+  if (!path || path === '/') return '/'
+  // Remove trailing slash
+  const normalized = path.endsWith('/') ? path.slice(0, -1) : path
+  // Ensure leading slash
+  return normalized.startsWith('/') ? normalized : '/' + normalized
+}
+
+/**
+ * Matches a path against a pattern with :param and * wildcards
+ *
+ * @param path - Actual path to test
+ * @param pattern - Pattern with :param segments or * wildcard
+ * @returns true if the path matches the pattern
+ */
+export function matchPathPattern(path: string, pattern: string): boolean {
+  // Handle wildcard at end
+  if (pattern.endsWith('*')) {
+    const prefix = pattern.slice(0, -1)
+    return path.startsWith(prefix)
+  }
+
+  const pathSegments = path.split('/').filter(Boolean)
+  const patternSegments = pattern.split('/').filter(Boolean)
+
+  if (pathSegments.length !== patternSegments.length) {
+    return false
+  }
+
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternSeg = patternSegments[i]
+    const pathSeg = pathSegments[i]
+
+    // :param matches any single segment
+    if (patternSeg.startsWith(':')) {
+      continue
+    }
+
+    if (patternSeg !== pathSeg) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Generates breadcrumb segments from a path
+ *
+ * @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 generateBreadcrumbSegments(
+  path: string,
+  options?: {
+    /** Custom labels for specific paths (e.g., { '/products': 'Shop' }) */
+    labels?: Record<string, string>
+    /** Function to generate label from segment (default: capitalize) */
+    labelGenerator?: (segment: string, fullPath: string) => string
+    /** Whether to include home segment */
+    includeHome?: boolean
+    /** Home segment label */
+    homeLabel?: string
+  }
+): Array<{ label: string; path: string }> {
+  const {
+    labels = {},
+    labelGenerator = (s: string) => formatSegmentLabel(s),
+    includeHome = true,
+    homeLabel = 'Home',
+  } = options || {}
+
+  const segments: Array<{ label: string; path: string }> = []
+
+  // Add home segment if requested
+  if (includeHome) {
+    segments.push({ label: labels['/'] || homeLabel, path: '/' })
+  }
+
+  // Split path and build cumulative paths
+  const parts = path.split('/').filter(Boolean)
+  let cumulativePath = ''
+
+  for (const part of parts) {
+    cumulativePath += '/' + part
+    const label = labels[cumulativePath] || labelGenerator(part, cumulativePath)
+    segments.push({ label, path: cumulativePath })
+  }
+
+  return segments
+}
+
+/**
+ * Formats a URL segment into a human-readable label
+ * Converts kebab-case or snake_case to Title Case
+ *
+ * @param segment - URL path segment (e.g., 'my-products')
+ * @returns Formatted label (e.g., 'My Products')
+ */
+export function formatSegmentLabel(segment: string): string {
+  return segment
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+/**
+ * Finds the active item in a navigation structure based on current path
+ *
+ * @param items - Array of items with path property
+ * @param currentPath - Current route path
+ * @param mode - Match mode for path comparison
+ * @returns The matching item's ID or undefined
+ */
+export function findActiveItemByPath<T extends { id: string; path?: string }>(
+  items: T[],
+  currentPath: string,
+  mode: RouteMatchMode = 'prefix'
+): string | undefined {
+  // First try exact match
+  const exactMatch = items.find((item) => item.path && matchPath(currentPath, item.path, 'exact'))
+  if (exactMatch) return exactMatch.id
+
+  // Then try prefix match (for nested routes)
+  if (mode === 'prefix') {
+    // Sort by path length descending to get most specific match
+    const sortedItems = [...items]
+      .filter((item) => item.path)
+      .sort((a, b) => (b.path?.length ?? 0) - (a.path?.length ?? 0))
+
+    for (const item of sortedItems) {
+      if (item.path && matchPath(currentPath, item.path, 'prefix')) {
+        return item.id
+      }
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Finds the active item in nested navigation sections based on current path
+ *
+ * @param sections - Array of sections containing items with path property
+ * @param currentPath - Current route path
+ * @param mode - Match mode for path comparison
+ * @returns The matching item's ID or undefined
+ */
+export function findActiveItemInSections<T extends { id: string; path?: string }>(
+  sections: Array<{ items: T[] }>,
+  currentPath: string,
+  mode: RouteMatchMode = 'prefix'
+): string | undefined {
+  const allItems = sections.flatMap((s) => s.items)
+  return findActiveItemByPath(allItems, currentPath, mode)
+}
+
+/**
+ * Builds a path by joining segments
+ *
+ * @param segments - Path segments to join
+ * @returns Joined and normalized path
+ */
+export function joinPath(...segments: string[]): string {
+  const joined = segments
+    .map((s) => s.replace(/^\/+|\/+$/g, ''))
+    .filter(Boolean)
+    .join('/')
+  return '/' + joined
+}
+
+/**
+ * Extracts path parameters from a path using a pattern
+ *
+ * @param path - Actual path (e.g., '/users/123/edit')
+ * @param pattern - Pattern with :param segments (e.g., '/users/:id/edit')
+ * @returns Object with extracted parameters or null if no match
+ */
+export function extractPathParams(
+  path: string,
+  pattern: string
+): Record<string, string> | null {
+  const pathSegments = path.split('/').filter(Boolean)
+  const patternSegments = pattern.split('/').filter(Boolean)
+
+  if (pathSegments.length !== patternSegments.length) {
+    return null
+  }
+
+  const params: Record<string, string> = {}
+
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternSeg = patternSegments[i]
+    const pathSeg = pathSegments[i]
+
+    if (patternSeg.startsWith(':')) {
+      const paramName = patternSeg.slice(1)
+      params[paramName] = pathSeg
+    } else if (patternSeg !== pathSeg) {
+      return null
+    }
+  }
+
+  return params
+}
+
+// ============================================================================
+// UINode Helper Functions
+// ============================================================================
+
+/**
+ * Normalizes UINode children to an array of UINodes.
+ * Handles both array and string children forms.
+ *
+ * @param children - Children from UINode (can be UINode[], string, or undefined)
+ * @returns Array of UINodes (empty array if no children)
+ *
+ * @example
+ * ```tsx
+ * const children = normalizeChildren(node.children)
+ * children.forEach(child => renderNode(child))
+ * ```
+ */
+export function normalizeChildren(children: UINode['children']): UINode[] {
+  if (!children) return []
+  if (typeof children === 'string') {
+    // Convert string to a text node
+    return [{ type: 'text', props: { content: children } }]
+  }
+  return children
+}
+
+/**
+ * Gets text content from a UINode, checking both text property and props.content.
+ *
+ * @param node - The UINode to extract text from
+ * @returns Text content as string, or empty string if none found
+ *
+ * @example
+ * ```tsx
+ * const text = getNodeText(node)
+ * ```
+ */
+export function getNodeText(node: UINode): string {
+  // Check direct text property first
+  if (node.text !== undefined) {
+    return node.text
+  }
+  // Then check props.content
+  const content = node.props?.content
+  if (content !== undefined && content !== null) {
+    return String(content)
+  }
+  // Finally check if children is a string
+  if (typeof node.children === 'string') {
+    return node.children
+  }
+  return ''
+}
+
+/**
+ * Safely gets props from a UINode, defaulting to empty object.
+ *
+ * @param node - The UINode to get props from
+ * @returns Props object (never undefined)
+ *
+ * @example
+ * ```tsx
+ * const props = getNodeProps(node)
+ * const color = props.color as string | undefined
+ * ```
+ */
+export function getNodeProps(node: UINode): Record<string, unknown> {
+  return node.props || {}
+}