@mdxui/terminal 2.0.0

package/src/router/utils.ts

@@ -0,0 +1,452 @@
+/**
+ * @mdxui/terminal Router Utilities
+ *
+ * Path matching, normalization, and breadcrumb generation utilities.
+ * These are re-exported from renderers/utils for consistency.
+ */
+
+import type {
+  RouteMatchMode,
+  NavigableItem,
+  BreadcrumbSegment,
+  BreadcrumbGeneratorOptions,
+} from './types'
+
+/**
+ * Normalizes a path by removing trailing slashes (except for root).
+ *
+ * @param path - Path to normalize
+ * @returns Normalized path
+ *
+ * @example
+ * ```typescript
+ * normalizePath('/products/') // '/products'
+ * normalizePath('products')   // '/products'
+ * normalizePath('/')          // '/'
+ * normalizePath('')           // '/'
+ * ```
+ */
+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 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
+ *
+ * @example
+ * ```typescript
+ * matchPath('/products/123', '/products', 'prefix')     // true
+ * matchPath('/products/123', '/products', 'exact')      // false
+ * matchPath('/users/123', '/users/:id', 'pattern')      // true
+ * matchPath('/products/all', '/products/*', 'pattern')  // true
+ * ```
+ */
+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
+  }
+}
+
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * matchPathPattern('/users/123', '/users/:id')           // true
+ * matchPathPattern('/users/123/posts', '/users/:id/*')   // true
+ * matchPathPattern('/products', '/users/:id')            // false
+ * ```
+ */
+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
+}
+
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * extractPathParams('/users/123/posts/456', '/users/:userId/posts/:postId')
+ * // { userId: '123', postId: '456' }
+ *
+ * extractPathParams('/products/shoes', '/users/:id')
+ * // null (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
+}
+
+/**
+ * Builds a path by joining segments.
+ *
+ * @param segments - Path segments to join
+ * @returns Joined and normalized path
+ *
+ * @example
+ * ```typescript
+ * joinPath('/users', '123', 'posts')   // '/users/123/posts'
+ * joinPath('users/', '/123/', '/posts/') // '/users/123/posts'
+ * ```
+ */
+export function joinPath(...segments: string[]): string {
+  const joined = segments
+    .map((s) => s.replace(/^\/+|\/+$/g, ''))
+    .filter(Boolean)
+    .join('/')
+  return '/' + joined
+}
+
+/**
+ * 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')
+ *
+ * @example
+ * ```typescript
+ * formatSegmentLabel('my-products')  // 'My Products'
+ * formatSegmentLabel('user_settings') // 'User Settings'
+ * formatSegmentLabel('api')          // 'Api'
+ * ```
+ */
+export function formatSegmentLabel(segment: string): string {
+  return segment
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+/**
+ * Generates breadcrumb segments from a URL 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
+ *
+ * @example
+ * ```typescript
+ * generateBreadcrumbSegments('/products/electronics/phones')
+ * // [
+ * //   { label: 'Home', path: '/' },
+ * //   { label: 'Products', path: '/products' },
+ * //   { label: 'Electronics', path: '/products/electronics' },
+ * //   { label: 'Phones', path: '/products/electronics/phones' },
+ * // ]
+ *
+ * generateBreadcrumbSegments('/users/123', {
+ *   labels: { '/users': 'Members', '/users/123': 'John Doe' },
+ *   includeHome: false,
+ * })
+ * // [
+ * //   { label: 'Members', path: '/users' },
+ * //   { label: 'John Doe', path: '/users/123' },
+ * // ]
+ * ```
+ */
+export function generateBreadcrumbSegments(
+  path: string,
+  options?: BreadcrumbGeneratorOptions
+): BreadcrumbSegment[] {
+  const {
+    labels = {},
+    labelGenerator = (s: string) => formatSegmentLabel(s),
+    includeHome = true,
+    homeLabel = 'Home',
+    homeIcon,
+  } = options || {}
+
+  const segments: BreadcrumbSegment[] = []
+
+  // Add home segment if requested
+  if (includeHome) {
+    segments.push({
+      label: labels['/'] || homeLabel,
+      path: '/',
+      icon: homeIcon,
+    })
+  }
+
+  // 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
+}
+
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * const items = [
+ *   { id: 'home', path: '/' },
+ *   { id: 'products', path: '/products' },
+ *   { id: 'product-detail', path: '/products/:id' },
+ * ]
+ *
+ * findActiveItemByPath(items, '/products/123', 'prefix')
+ * // 'products'
+ *
+ * findActiveItemByPath(items, '/products/123', 'pattern')
+ * // 'product-detail'
+ * ```
+ */
+export function findActiveItemByPath<T extends NavigableItem>(
+  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
+      }
+    }
+  }
+
+  // Try pattern match
+  if (mode === 'pattern') {
+    for (const item of items) {
+      if (item.path && matchPath(currentPath, item.path, 'pattern')) {
+        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 NavigableItem>(
+  sections: Array<{ items: T[] }>,
+  currentPath: string,
+  mode: RouteMatchMode = 'prefix'
+): string | undefined {
+  const allItems = sections.flatMap((s) => s.items)
+  return findActiveItemByPath(allItems, currentPath, mode)
+}
+
+/**
+ * Resolves relative paths against a base path.
+ *
+ * @param relativePath - Relative path (can start with ./ or ../)
+ * @param basePath - Base path to resolve against
+ * @returns Resolved absolute path
+ *
+ * @example
+ * ```typescript
+ * resolvePath('./edit', '/users/123')    // '/users/123/edit'
+ * resolvePath('../posts', '/users/123')  // '/users/posts'
+ * resolvePath('/dashboard', '/users')    // '/dashboard'
+ * ```
+ */
+export function resolvePath(relativePath: string, basePath: string): string {
+  // Absolute paths stay as-is
+  if (relativePath.startsWith('/')) {
+    return normalizePath(relativePath)
+  }
+
+  const baseSegments = basePath.split('/').filter(Boolean)
+  const relativeSegments = relativePath.split('/').filter(Boolean)
+
+  for (const segment of relativeSegments) {
+    if (segment === '..') {
+      baseSegments.pop()
+    } else if (segment !== '.') {
+      baseSegments.push(segment)
+    }
+  }
+
+  return '/' + baseSegments.join('/')
+}
+
+/**
+ * Checks if a path is within a base path.
+ *
+ * @param path - Path to check
+ * @param basePath - Base path
+ * @returns true if path is within basePath
+ *
+ * @example
+ * ```typescript
+ * isWithinPath('/products/123', '/products')  // true
+ * isWithinPath('/users/123', '/products')     // false
+ * isWithinPath('/products', '/products')      // true
+ * ```
+ */
+export function isWithinPath(path: string, basePath: string): boolean {
+  const normPath = normalizePath(path)
+  const normBase = normalizePath(basePath)
+
+  if (normBase === '/') {
+    return true
+  }
+
+  return normPath === normBase || normPath.startsWith(normBase + '/')
+}
+
+/**
+ * Gets the parent path of a given path.
+ *
+ * @param path - Path to get parent of
+ * @returns Parent path or '/' if at root
+ *
+ * @example
+ * ```typescript
+ * getParentPath('/users/123/posts')  // '/users/123'
+ * getParentPath('/users')            // '/'
+ * getParentPath('/')                 // '/'
+ * ```
+ */
+export function getParentPath(path: string): string {
+  const normalized = normalizePath(path)
+  if (normalized === '/') return '/'
+
+  const lastSlash = normalized.lastIndexOf('/')
+  if (lastSlash <= 0) return '/'
+
+  return normalized.slice(0, lastSlash)
+}
+
+/**
+ * Gets the last segment of a path.
+ *
+ * @param path - Path to get segment from
+ * @returns Last path segment
+ *
+ * @example
+ * ```typescript
+ * getLastSegment('/users/123/posts')  // 'posts'
+ * getLastSegment('/users')            // 'users'
+ * getLastSegment('/')                 // ''
+ * ```
+ */
+export function getLastSegment(path: string): string {
+  const normalized = normalizePath(path)
+  if (normalized === '/') return ''
+
+  const segments = normalized.split('/').filter(Boolean)
+  return segments[segments.length - 1] || ''
+}

package/src/schemas.ts

@@ -0,0 +1,205 @@
+/**
+ * Zod Schemas for Runtime Validation
+ *
+ * Provides Zod schemas for validating public API inputs at runtime.
+ * These schemas ensure type safety beyond TypeScript's compile-time checks.
+ *
+ * @module
+ */
+
+import { z } from 'zod'
+
+// ============================================================================
+// Color Schemas
+// ============================================================================
+
+/**
+ * Schema for hex color strings.
+ *
+ * Accepts:
+ * - 3-character hex: #RGB or RGB
+ * - 6-character hex: #RRGGBB or RRGGBB
+ *
+ * @example
+ * ```tsx
+ * HexColorSchema.parse('#ff0000')  // Valid
+ * HexColorSchema.parse('ff0000')   // Valid
+ * HexColorSchema.parse('#f00')     // Valid
+ * HexColorSchema.parse('invalid')  // Throws ZodError
+ * ```
+ */
+export const HexColorSchema = z
+  .string()
+  .regex(
+    /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/,
+    'Invalid hex color format. Expected #RGB, RGB, #RRGGBB, or RRGGBB'
+  )
+
+/**
+ * Schema for RGB component values (0-255).
+ */
+export const RgbComponentSchema = z
+  .number()
+  .int('RGB component must be an integer')
+  .min(0, 'RGB component must be >= 0')
+  .max(255, 'RGB component must be <= 255')
+
+/**
+ * Schema for RGB color object.
+ */
+export const RgbColorSchema = z.object({
+  r: RgbComponentSchema,
+  g: RgbComponentSchema,
+  b: RgbComponentSchema,
+})
+
+/**
+ * Schema for ANSI 256 color codes (0-255).
+ */
+export const Ansi256CodeSchema = z
+  .number()
+  .int('ANSI 256 code must be an integer')
+  .min(0, 'ANSI 256 code must be >= 0')
+  .max(255, 'ANSI 256 code must be <= 255')
+
+/**
+ * Schema for ANSI escape sequence strings.
+ * Validates that a string is a valid ANSI escape sequence.
+ *
+ * Accepts:
+ * - Empty string (valid for 'no color')
+ * - ANSI escape sequences like \x1b[38;5;33m
+ */
+export const AnsiEscapeSchema = z
+  .string()
+  .refine(
+    (val) => {
+      if (val === '') return true
+      // eslint-disable-next-line no-control-regex
+      return /^\x1b\[\d+(;\d+)*m$/.test(val)
+    },
+    {
+      message: 'Invalid ANSI escape sequence',
+    }
+  )
+
+// ============================================================================
+// Theme Schemas
+// ============================================================================
+
+/**
+ * Schema for theme color mode.
+ */
+export const ThemeModeSchema = z.enum(['dark', 'light'])
+
+/**
+ * Schema for terminal theme colors.
+ * All values are ANSI escape sequences.
+ */
+export const TerminalThemeColorsSchema = z.object({
+  primary: AnsiEscapeSchema,
+  secondary: AnsiEscapeSchema,
+  accent: AnsiEscapeSchema,
+  muted: AnsiEscapeSchema,
+  success: AnsiEscapeSchema,
+  warning: AnsiEscapeSchema,
+  error: AnsiEscapeSchema,
+  info: AnsiEscapeSchema,
+  border: AnsiEscapeSchema,
+  background: AnsiEscapeSchema,
+  foreground: AnsiEscapeSchema,
+  selection: AnsiEscapeSchema,
+  focus: AnsiEscapeSchema,
+})
+
+/**
+ * Schema for CreateTerminalThemeOptions.
+ */
+export const CreateTerminalThemeOptionsSchema = z.object({
+  mode: ThemeModeSchema.optional(),
+  colors: TerminalThemeColorsSchema.partial().optional(),
+})
+
+/**
+ * Schema for legacy terminal theme.
+ */
+export const LegacyTerminalThemeSchema = z.object({
+  primary: AnsiEscapeSchema,
+  secondary: AnsiEscapeSchema,
+  accent: AnsiEscapeSchema,
+  muted: AnsiEscapeSchema,
+  success: AnsiEscapeSchema,
+  warning: AnsiEscapeSchema,
+  error: AnsiEscapeSchema,
+  info: AnsiEscapeSchema,
+  border: AnsiEscapeSchema,
+  background: AnsiEscapeSchema,
+  foreground: AnsiEscapeSchema,
+  selection: AnsiEscapeSchema,
+  focus: AnsiEscapeSchema,
+})
+
+/**
+ * Schema for typography options in legacy theme.
+ */
+export const TypographyOptionsSchema = z.object({
+  headingWeight: z.string(),
+  bodyWeight: z.string(),
+  codeFont: z.string(),
+})
+
+/**
+ * Schema for spacing options in legacy theme.
+ */
+export const SpacingOptionsSchema = z.object({
+  xs: z.number(),
+  sm: z.number(),
+  md: z.number(),
+  lg: z.number(),
+  xl: z.number(),
+})
+
+/**
+ * Schema for legacy terminal theme with extras.
+ */
+export const LegacyTerminalThemeWithExtrasSchema = LegacyTerminalThemeSchema.extend({
+  typography: TypographyOptionsSchema.optional(),
+  spacing: SpacingOptionsSchema.optional(),
+})
+
+/**
+ * Schema for createTheme() function input (partial legacy theme).
+ */
+export const CreateThemeInputSchema = LegacyTerminalThemeWithExtrasSchema.partial()
+
+// ============================================================================
+// Color Conversion Schemas
+// ============================================================================
+
+/**
+ * Schema for RGB to ANSI conversion options.
+ */
+export const RgbToAnsiOptionsSchema = z.object({
+  background: z.boolean().optional(),
+})
+
+// ============================================================================
+// Color Support Schemas
+// ============================================================================
+
+/**
+ * Schema for color support levels.
+ */
+export const ColorSupportSchema = z.enum(['none', '16', '256', 'truecolor'])
+
+// ============================================================================
+// Type Exports (inferred from schemas)
+// ============================================================================
+
+export type HexColor = z.infer<typeof HexColorSchema>
+export type RgbColor = z.infer<typeof RgbColorSchema>
+export type Ansi256Code = z.infer<typeof Ansi256CodeSchema>
+export type ThemeMode = z.infer<typeof ThemeModeSchema>
+export type CreateTerminalThemeOptionsInput = z.infer<typeof CreateTerminalThemeOptionsSchema>
+export type CreateThemeInput = z.infer<typeof CreateThemeInputSchema>
+export type ColorSupport = z.infer<typeof ColorSupportSchema>