@mdxui/terminal 2.0.0

package/src/router/adapters.ts

@@ -0,0 +1,383 @@
+/**
+ * @mdxui/terminal Router Adapters
+ *
+ * Pre-built router adapters for common routing libraries and patterns.
+ */
+
+import type {
+  RouterAdapter,
+  RouteMatchMode,
+  RouterConfig,
+  MemoryRouterState,
+  HistoryEntry,
+} from './types'
+import { matchPath, normalizePath } from './utils'
+
+/**
+ * Creates a callback-based router adapter.
+ * Use when you want to handle navigation with custom callbacks.
+ *
+ * @param config - Configuration with callbacks
+ * @returns RouterAdapter instance
+ *
+ * @example
+ * ```typescript
+ * const [currentPath, setCurrentPath] = useState('/')
+ *
+ * const router = createCallbackRouterAdapter({
+ *   currentPath,
+ *   onNavigate: setCurrentPath,
+ * })
+ * ```
+ */
+export function createCallbackRouterAdapter(config: {
+  currentPath?: string
+  onNavigate?: (path: string) => void
+  onReplace?: (path: string) => void
+}): RouterAdapter {
+  return {
+    getCurrentPath: () => config.currentPath || '/',
+    navigate: (path: string) => config.onNavigate?.(path),
+    replace: (path: string) => (config.onReplace || config.onNavigate)?.(path),
+    isActive: (path: string, mode: RouteMatchMode = 'exact') => {
+      const current = config.currentPath || '/'
+      return matchPath(current, path, mode)
+    },
+  }
+}
+
+/**
+ * Creates an in-memory router adapter with full history support.
+ * Useful for testing, CLI applications, and server-side rendering.
+ *
+ * @param config - Router configuration
+ * @returns RouterAdapter with additional memory router methods
+ *
+ * @example
+ * ```typescript
+ * const router = createMemoryRouterAdapter({ initialPath: '/home' })
+ *
+ * router.navigate('/products')
+ * router.back() // Returns to /home
+ *
+ * const unsubscribe = router.subscribe?.((path) => {
+ *   console.log('Navigated to:', path)
+ * })
+ * ```
+ */
+export function createMemoryRouterAdapter(config?: RouterConfig): RouterAdapter & {
+  getState(): MemoryRouterState
+  getHistory(): HistoryEntry[]
+  reset(path?: string): void
+} {
+  const state: MemoryRouterState = {
+    entries: [{
+      path: normalizePath(config?.initialPath || '/'),
+      timestamp: Date.now(),
+    }],
+    index: 0,
+    listeners: new Set(),
+  }
+
+  const basePath = config?.basePath || ''
+  const defaultMode = config?.defaultMatchMode || 'exact'
+
+  function notifyListeners() {
+    const currentPath = state.entries[state.index]?.path || '/'
+    state.listeners.forEach(listener => listener(currentPath))
+  }
+
+  function resolvePath(path: string): string {
+    if (basePath && !path.startsWith(basePath)) {
+      return normalizePath(basePath + path)
+    }
+    return normalizePath(path)
+  }
+
+  return {
+    getCurrentPath: () => state.entries[state.index]?.path || '/',
+
+    navigate: (path: string) => {
+      const resolved = resolvePath(path)
+      // Truncate forward history when navigating from a point in history
+      state.entries = state.entries.slice(0, state.index + 1)
+      state.entries.push({ path: resolved, timestamp: Date.now() })
+      state.index = state.entries.length - 1
+      notifyListeners()
+    },
+
+    replace: (path: string) => {
+      const resolved = resolvePath(path)
+      state.entries[state.index] = { path: resolved, timestamp: Date.now() }
+      notifyListeners()
+    },
+
+    isActive: (path: string, mode: RouteMatchMode = defaultMode) => {
+      const current = state.entries[state.index]?.path || '/'
+      return matchPath(current, resolvePath(path), mode)
+    },
+
+    subscribe: (callback: (path: string) => void) => {
+      state.listeners.add(callback)
+      return () => {
+        state.listeners.delete(callback)
+      }
+    },
+
+    back: () => {
+      if (state.index > 0) {
+        state.index--
+        notifyListeners()
+      }
+    },
+
+    forward: () => {
+      if (state.index < state.entries.length - 1) {
+        state.index++
+        notifyListeners()
+      }
+    },
+
+    getParams: () => ({}), // Would need route patterns to extract params
+
+    getQuery: () => {
+      const current = state.entries[state.index]?.path || '/'
+      const queryStart = current.indexOf('?')
+      if (queryStart === -1) return {}
+
+      const queryString = current.slice(queryStart + 1)
+      const params: Record<string, string> = {}
+      for (const pair of queryString.split('&')) {
+        const [key, value] = pair.split('=')
+        if (key) {
+          params[decodeURIComponent(key)] = decodeURIComponent(value || '')
+        }
+      }
+      return params
+    },
+
+    // Memory router specific methods
+    getState: () => ({ ...state, listeners: new Set(state.listeners) }),
+    getHistory: () => [...state.entries],
+    reset: (path?: string) => {
+      state.entries = [{
+        path: normalizePath(path || config?.initialPath || '/'),
+        timestamp: Date.now(),
+      }]
+      state.index = 0
+      notifyListeners()
+    },
+  }
+}
+
+/**
+ * Creates a URL-sync router adapter that syncs with browser URL.
+ * Falls back to in-memory routing when window is not available.
+ *
+ * @param config - Router configuration
+ * @returns RouterAdapter that syncs with browser URL
+ *
+ * @example
+ * ```typescript
+ * const router = createUrlSyncRouterAdapter({
+ *   basePath: '/app',
+ * })
+ *
+ * // Navigating updates browser URL
+ * router.navigate('/dashboard')
+ * // URL becomes: /app/dashboard
+ * ```
+ */
+export function createUrlSyncRouterAdapter(config?: RouterConfig): RouterAdapter {
+  // Check if we're in a browser environment
+  const isBrowser = typeof window !== 'undefined' && typeof window.history !== 'undefined'
+
+  if (!isBrowser) {
+    // Fall back to memory router in non-browser environments
+    return createMemoryRouterAdapter(config)
+  }
+
+  const basePath = config?.basePath || ''
+  const defaultMode = config?.defaultMatchMode || 'exact'
+  const listeners = new Set<(path: string) => void>()
+
+  function getCurrentPath(): string {
+    const path = window.location.pathname
+    if (basePath && path.startsWith(basePath)) {
+      return normalizePath(path.slice(basePath.length) || '/')
+    }
+    return normalizePath(path)
+  }
+
+  function resolvePath(path: string): string {
+    if (basePath) {
+      return basePath + normalizePath(path)
+    }
+    return normalizePath(path)
+  }
+
+  // Listen for popstate events (back/forward)
+  if (isBrowser) {
+    window.addEventListener('popstate', () => {
+      const path = getCurrentPath()
+      listeners.forEach(listener => listener(path))
+    })
+  }
+
+  return {
+    getCurrentPath,
+
+    navigate: (path: string) => {
+      const resolved = resolvePath(path)
+      window.history.pushState(null, '', resolved)
+      listeners.forEach(listener => listener(normalizePath(path)))
+    },
+
+    replace: (path: string) => {
+      const resolved = resolvePath(path)
+      window.history.replaceState(null, '', resolved)
+      listeners.forEach(listener => listener(normalizePath(path)))
+    },
+
+    isActive: (path: string, mode: RouteMatchMode = defaultMode) => {
+      return matchPath(getCurrentPath(), path, mode)
+    },
+
+    subscribe: (callback: (path: string) => void) => {
+      listeners.add(callback)
+      return () => {
+        listeners.delete(callback)
+      }
+    },
+
+    back: () => {
+      window.history.back()
+    },
+
+    forward: () => {
+      window.history.forward()
+    },
+
+    getParams: () => ({}),
+
+    getQuery: () => {
+      const params: Record<string, string> = {}
+      const searchParams = new URLSearchParams(window.location.search)
+      searchParams.forEach((value, key) => {
+        params[key] = value
+      })
+      return params
+    },
+  }
+}
+
+/**
+ * Creates a hash-based router adapter using URL hash for routing.
+ * Useful for static hosting where server-side routing is not available.
+ *
+ * @param config - Router configuration
+ * @returns RouterAdapter that uses URL hash
+ *
+ * @example
+ * ```typescript
+ * const router = createHashRouterAdapter()
+ *
+ * router.navigate('/products')
+ * // URL becomes: /#/products
+ * ```
+ */
+export function createHashRouterAdapter(config?: RouterConfig): RouterAdapter {
+  // Check if we're in a browser environment
+  const isBrowser = typeof window !== 'undefined'
+
+  if (!isBrowser) {
+    return createMemoryRouterAdapter(config)
+  }
+
+  const defaultMode = config?.defaultMatchMode || 'exact'
+  const listeners = new Set<(path: string) => void>()
+
+  function getCurrentPath(): string {
+    const hash = window.location.hash
+    const path = hash.startsWith('#') ? hash.slice(1) : hash
+    return normalizePath(path || '/')
+  }
+
+  // Listen for hashchange events
+  if (isBrowser) {
+    window.addEventListener('hashchange', () => {
+      const path = getCurrentPath()
+      listeners.forEach(listener => listener(path))
+    })
+  }
+
+  return {
+    getCurrentPath,
+
+    navigate: (path: string) => {
+      window.location.hash = normalizePath(path)
+    },
+
+    replace: (path: string) => {
+      const url = new URL(window.location.href)
+      url.hash = normalizePath(path)
+      window.history.replaceState(null, '', url.toString())
+      listeners.forEach(listener => listener(normalizePath(path)))
+    },
+
+    isActive: (path: string, mode: RouteMatchMode = defaultMode) => {
+      return matchPath(getCurrentPath(), path, mode)
+    },
+
+    subscribe: (callback: (path: string) => void) => {
+      listeners.add(callback)
+      return () => {
+        listeners.delete(callback)
+      }
+    },
+
+    back: () => {
+      window.history.back()
+    },
+
+    forward: () => {
+      window.history.forward()
+    },
+
+    getParams: () => ({}),
+
+    getQuery: () => {
+      const hash = window.location.hash
+      const queryStart = hash.indexOf('?')
+      if (queryStart === -1) return {}
+
+      const params: Record<string, string> = {}
+      const searchParams = new URLSearchParams(hash.slice(queryStart + 1))
+      searchParams.forEach((value, key) => {
+        params[key] = value
+      })
+      return params
+    },
+  }
+}
+
+/**
+ * Creates a static router adapter for server-side rendering or testing.
+ * The path never changes - it's purely read-only.
+ *
+ * @param path - Static path to use
+ * @returns Read-only RouterAdapter
+ */
+export function createStaticRouterAdapter(path: string = '/'): RouterAdapter {
+  const normalizedPath = normalizePath(path)
+
+  return {
+    getCurrentPath: () => normalizedPath,
+    navigate: () => {
+      // No-op in static router
+    },
+    isActive: (targetPath: string, mode: RouteMatchMode = 'exact') => {
+      return matchPath(normalizedPath, targetPath, mode)
+    },
+  }
+}

package/src/router/types.ts

@@ -0,0 +1,140 @@
+/**
+ * @mdxui/terminal Router Types
+ *
+ * Type definitions for the router integration system.
+ * These types enable router-agnostic navigation across all navigation components.
+ */
+
+/**
+ * Route matching mode for navigation components.
+ * - `exact`: Path must match exactly
+ * - `prefix`: Path starts with target (for nested routes)
+ * - `pattern`: Path matches pattern with :param and * wildcards
+ */
+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,
+ * or any custom routing solution.
+ *
+ * @example
+ * ```typescript
+ * // React Router adapter
+ * const reactRouterAdapter: RouterAdapter = {
+ *   getCurrentPath: () => location.pathname,
+ *   navigate: (path) => navigate(path),
+ *   isActive: (path, mode) => matchPath(location.pathname, path, mode),
+ *   subscribe: (callback) => {
+ *     return history.listen(({ location }) => callback(location.pathname))
+ *   },
+ * }
+ *
+ * // Next.js adapter
+ * const nextAdapter: RouterAdapter = {
+ *   getCurrentPath: () => router.asPath,
+ *   navigate: (path) => router.push(path),
+ *   isActive: (path, mode) => matchPath(router.asPath, path, mode),
+ * }
+ * ```
+ */
+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
+  /** Replace current history entry instead of push */
+  replace?(path: string): void
+  /** Go back in history */
+  back?(): void
+  /** Go forward in history */
+  forward?(): void
+  /** Get route parameters */
+  getParams?(): Record<string, string>
+  /** Get query parameters */
+  getQuery?(): Record<string, string>
+}
+
+/**
+ * Router context value for React context integration.
+ */
+export interface RouterContextValue {
+  /** Current path */
+  path: string
+  /** Router adapter instance */
+  adapter: RouterAdapter
+  /** Route parameters */
+  params: Record<string, string>
+  /** Query parameters */
+  query: Record<string, string>
+}
+
+/**
+ * Configuration for creating router adapters.
+ */
+export interface RouterConfig {
+  /** Initial path */
+  initialPath?: string
+  /** Base path for all routes */
+  basePath?: string
+  /** Default route match mode */
+  defaultMatchMode?: RouteMatchMode
+}
+
+/**
+ * History entry for in-memory router.
+ */
+export interface HistoryEntry {
+  path: string
+  state?: unknown
+  timestamp: number
+}
+
+/**
+ * In-memory router state.
+ */
+export interface MemoryRouterState {
+  entries: HistoryEntry[]
+  index: number
+  listeners: Set<(path: string) => void>
+}
+
+/**
+ * Navigation item with optional path for router integration.
+ */
+export interface NavigableItem {
+  id: string
+  path?: string
+  label?: string
+  icon?: string
+  disabled?: boolean
+}
+
+/**
+ * Breadcrumb segment with path information.
+ */
+export interface BreadcrumbSegment {
+  label: string
+  path?: string
+  icon?: string
+}
+
+/**
+ * Options for generating breadcrumbs from a path.
+ */
+export interface BreadcrumbGeneratorOptions {
+  /** 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
+  /** Home segment icon */
+  homeIcon?: string
+}