@mdxui/terminal 2.0.0

package/src/core/types.ts

@@ -0,0 +1,672 @@
+/**
+ * @mdxui/terminal UINode Type System
+ *
+ * Core type definitions and Zod schemas for the Universal Terminal UI's
+ * multi-tier rendering architecture.
+ */
+import { z } from 'zod'
+
+// ============================================================================
+// TypeScript Interfaces
+// ============================================================================
+
+/**
+ * UINode - The fundamental building block of the terminal UI tree.
+ *
+ * Represents a component with type, props, optional children, data, and key.
+ * This is the core abstraction that allows universal rendering across different
+ * output tiers (text, markdown, ascii, unicode, ansi, interactive).
+ *
+ * @remarks
+ * UINode follows a tree-based component model similar to React:
+ * - Each node has a `type` that identifies the component (e.g., 'box', 'text', 'panel')
+ * - Props are passed as a generic key-value record
+ * - Children can be nested to arbitrary depth
+ * - Optional `data` field can hold query results for data-driven components
+ * - Optional `key` field helps with list reconciliation
+ *
+ * @example
+ * Simple text node:
+ * ```tsx
+ * const node: UINode = {
+ *   type: 'text',
+ *   props: { content: 'Hello, World!' }
+ * }
+ * ```
+ *
+ * @example
+ * Nested structure with children:
+ * ```tsx
+ * const node: UINode = {
+ *   type: 'box',
+ *   props: { padding: 2, border: 'rounded' },
+ *   children: [
+ *     { type: 'text', props: { content: 'Title' } },
+ *     { type: 'text', props: { content: 'Subtitle' } }
+ *   ]
+ * }
+ * ```
+ *
+ * @example
+ * Data-driven component:
+ * ```tsx
+ * const node: UINode = {
+ *   type: 'table',
+ *   props: { headers: ['Name', 'Age'] },
+ *   data: [
+ *     { name: 'Alice', age: 30 },
+ *     { name: 'Bob', age: 28 }
+ *   ]
+ * }
+ * ```
+ */
+export interface UINode {
+  /**
+   * Component type identifier
+   * @remarks
+   * String that identifies the component type. Common examples: 'text', 'box', 'panel',
+   * 'table', 'list', 'button'. Custom component types are supported.
+   */
+  type: string
+
+  /**
+   * Component props as a generic record
+   * @remarks
+   * Props are component-specific configuration. All values must be serializable
+   * for cross-tier rendering. Examples:
+   * - { content: 'text content' }
+   * - { padding: 2, border: 'single' }
+   * - { columns: ['Name', 'Email'] }
+   */
+  props?: Record<string, unknown>
+
+  /**
+   * Optional child UINodes or string content for nested components
+   * @remarks
+   * Children are rendered as the component's content. Nested to arbitrary depth.
+   * Can be an array of UINode objects or a direct string for simple text content.
+   * Undefined if the component has no children.
+   */
+  children?: UINode[] | string
+
+  /**
+   * Optional shorthand for text content
+   * @remarks
+   * Convenience property for setting text content directly on a node without
+   * using props.content. Commonly used for simple text nodes.
+   * Example: { type: 'text', text: 'Hello World' }
+   */
+  text?: string
+
+  /**
+   * Optional bound query data for data-driven components
+   * @remarks
+   * Used for components that render arrays of items (tables, lists, grids).
+   * The data can be any shape; the component implementation defines how to use it.
+   * Examples: array of records, nested objects, primitive values.
+   */
+  data?: unknown
+
+  /**
+   * Optional key for React-style reconciliation
+   * @remarks
+   * Used in lists to maintain identity across renders. If a node's key changes,
+   * the component is recreated. Useful for preserving component state.
+   * Should be stable across renders for the same logical item.
+   */
+  key?: string
+}
+
+/**
+ * RenderTier - Defines the capability level for rendering output.
+ *
+ * Tiers are ordered by increasing capability:
+ * `text` < `markdown` < `ascii` < `unicode` < `ansi` < `interactive`
+ *
+ * Each tier builds on the previous one, enabling progressively richer
+ * terminal output while maintaining backward compatibility.
+ *
+ * @remarks
+ * **Tier Definitions:**
+ *
+ * - **text** - Plain text output without any formatting or special characters.
+ *   No colors, no box drawing, no markdown. Useful for piping output or
+ *   basic terminal environments with no formatting support.
+ *   Example: `Hello World`
+ *
+ * - **markdown** - Text with Markdown syntax for basic formatting:
+ *   **bold**, *italic*, `code`, links. No color support. Good for converting
+ *   terminal output to documentation or emails.
+ *   Example: `**Hello** _World_`
+ *
+ * - **ascii** - ASCII art characters (/, \, |, -, +, =) for drawing
+ *   boxes, borders, and diagrams. No unicode box drawing characters.
+ *   Broader terminal compatibility than unicode.
+ *   Example: `+---+\n| A |\n+---+`
+ *
+ * - **unicode** - Unicode box drawing characters (┌, ─, │, └, etc.)
+ *   for elegant borders and tables. Better appearance than ASCII but
+ *   requires UTF-8 terminal support.
+ *   Example: `┌───┐\n│ A │\n└───┘`
+ *
+ * - **ansi** - ANSI escape sequences for 256-color or truecolor output.
+ *   Supports foreground/background colors, bold, underline, etc.
+ *   Requires modern terminal supporting ANSI codes.
+ *   Example: `\x1b[31mRed Text\x1b[0m`
+ *
+ * - **interactive** - Full interactive terminal UI with keyboard input,
+ *   mouse events, and real-time updates. Requires a terminal library like
+ *   Ink or Blessed. Most capable tier but requires active user interaction.
+ *   Example: Menu navigation, live dashboards, text input.
+ *
+ * @example
+ * Checking tier capability:
+ * ```tsx
+ * const canUseColors = tier === 'ansi' || tier === 'interactive'
+ * const canUseUnicode = tier === 'unicode' || tier === 'ansi' || tier === 'interactive'
+ * const isPlainText = tier === 'text'
+ * ```
+ */
+export type RenderTier =
+  | 'text'
+  | 'markdown'
+  | 'ascii'
+  | 'unicode'
+  | 'ansi'
+  | 'interactive'
+
+/**
+ * ThemeTokens - Color tokens for theming terminal output.
+ *
+ * All tokens are strings containing ANSI escape sequences (or empty for text tier).
+ * This interface defines a complete semantic color palette for terminal applications.
+ *
+ * @remarks
+ * **Format and Values:**
+ * - For `text` tier: Empty string `''` (no color support)
+ * - For `markdown` tier: Empty string `''` (colors not supported in markdown)
+ * - For `ascii`/`unicode`/`ansi`/`interactive` tiers:
+ *   ANSI escape sequences like `'\x1b[31m'` (red) or `'\x1b[1;32m'` (bold green)
+ *
+ * **Semantic Categories:**
+ * - **Primary/Secondary**: Brand colors for emphasis and hierarchy
+ * - **Foreground/Background**: Text and surface colors
+ * - **Status Colors**: Semantic meaning (green=success, red=error, yellow=warning, blue=info)
+ * - **Muted**: De-emphasized text (help text, secondary content)
+ * - **Border**: For drawing boxes and separators
+ *
+ * @example
+ * Light ANSI theme:
+ * ```tsx
+ * const lightTheme: ThemeTokens = {
+ *   primary: '\x1b[34m',      // Blue
+ *   secondary: '\x1b[36m',    // Cyan
+ *   muted: '\x1b[90m',        // Bright black
+ *   foreground: '\x1b[37m',   // White
+ *   background: '\x1b[40m',   // Black background
+ *   border: '\x1b[90m',       // Gray
+ *   success: '\x1b[32m',      // Green
+ *   warning: '\x1b[33m',      // Yellow
+ *   error: '\x1b[31m',        // Red
+ *   info: '\x1b[34m',         // Blue
+ * }
+ * ```
+ *
+ * @example
+ * Text tier (no colors):
+ * ```tsx
+ * const textTheme: ThemeTokens = {
+ *   primary: '',
+ *   secondary: '',
+ *   muted: '',
+ *   foreground: '',
+ *   background: '',
+ *   border: '',
+ *   success: '',
+ *   warning: '',
+ *   error: '',
+ *   info: '',
+ * }
+ * ```
+ */
+export interface ThemeTokens {
+  /**
+   * Primary brand color
+   * @remarks
+   * Used for primary CTAs, headings, and key UI elements.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  primary: string
+
+  /**
+   * Secondary accent color
+   * @remarks
+   * Used for secondary actions and accents.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  secondary: string
+
+  /**
+   * Muted/dimmed text color
+   * @remarks
+   * Used for helper text, secondary content, disabled states.
+   * Lower contrast than foreground color.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  muted: string
+
+  /**
+   * Default foreground text color
+   * @remarks
+   * Primary text color for body content and labels.
+   * Should have high contrast with background.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  foreground: string
+
+  /**
+   * Background color
+   * @remarks
+   * Used for panels, boxes, and background surfaces.
+   * Should contrast well with foreground for readability.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  background: string
+
+  /**
+   * Border/separator color
+   * @remarks
+   * Used for drawing borders, dividers, and separators.
+   * Often same as muted for subtle appearance.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  border: string
+
+  /**
+   * Success state color (typically green)
+   * @remarks
+   * Used for success messages, checkmarks, confirmations.
+   * Semantic meaning: positive outcome, success state.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  success: string
+
+  /**
+   * Warning state color (typically yellow/orange)
+   * @remarks
+   * Used for warnings, alerts, caution messages.
+   * Semantic meaning: attention needed, non-critical issue.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  warning: string
+
+  /**
+   * Error state color (typically red)
+   * @remarks
+   * Used for errors, failures, destructive actions.
+   * Semantic meaning: critical issue, failure state.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  error: string
+
+  /**
+   * Info state color (typically blue)
+   * @remarks
+   * Used for information, hints, explanatory messages.
+   * Semantic meaning: additional context, non-critical info.
+   * ANSI code string, empty for text/markdown tiers.
+   */
+  info: string
+}
+
+/**
+ * RenderContext - Context passed to renderers during tree traversal.
+ *
+ * Contains information about the rendering environment and is passed down
+ * through the UINode tree as components render. This allows renderers to
+ * make decisions about layout, styling, and interactivity based on the
+ * current environment.
+ *
+ * @remarks
+ * **Context Propagation:**
+ * - Passed to each component's renderer function
+ * - Updated for nested components (depth increments)
+ * - Allows renderers to adapt output to terminal capabilities
+ * - Enables responsive layouts based on terminal dimensions
+ *
+ * **Tier-Dependent Behavior:**
+ * - Lower tiers (text, markdown) ignore complex styling
+ * - Higher tiers (ansi, interactive) use full theme and interactivity
+ * - Renderers should gracefully degrade for lower tiers
+ *
+ * @example
+ * Using context in a renderer:
+ * ```tsx
+ * function renderBox(node: UINode, ctx: RenderContext): string {
+ *   if (ctx.tier === 'text') {
+ *     // No styling, return plain text
+ *     return node.props.content as string
+ *   }
+ *
+ *   if (ctx.tier === 'ansi' || ctx.tier === 'interactive') {
+ *     // Can use colors and styling
+ *     return `${ctx.theme.primary}[Box]${RESET}${node.props.content}`
+ *   }
+ *
+ *   // Other tiers: use unicode or ascii
+ *   return drawBox(node, ctx)
+ * }
+ * ```
+ *
+ * @example
+ * Responsive layout based on terminal width:
+ * ```tsx
+ * function renderGrid(node: UINode, ctx: RenderContext): string {
+ *   const columns = ctx.width < 80 ? 1 : ctx.width < 120 ? 2 : 3
+ *   // ... render grid with calculated columns
+ * }
+ * ```
+ */
+export interface RenderContext {
+  /**
+   * Current rendering tier
+   * @remarks
+   * Determines what output capabilities are available (colors, unicode, etc).
+   * Renderers should adapt their output based on this tier.
+   */
+  tier: RenderTier
+
+  /**
+   * Terminal width in columns
+   * @remarks
+   * Used for responsive layouts and line wrapping decisions.
+   * Standard values: 80 (legacy), 120 (modern), 160+ (wide monitors).
+   * Must be positive integer.
+   */
+  width: number
+
+  /**
+   * Terminal height in rows
+   * @remarks
+   * Used for pagination and viewport-aware rendering.
+   * Standard values: 24 (legacy), 40 (modern).
+   * Must be positive integer.
+   */
+  height: number
+
+  /**
+   * Current nesting depth
+   * @remarks
+   * Starts at 0 for root components, increments for each nested level.
+   * Used for indentation, padding, and determining when to truncate output.
+   * Must be non-negative integer.
+   */
+  depth: number
+
+  /**
+   * Theme tokens for styling
+   * @remarks
+   * Contains ANSI color codes for the current tier.
+   * For text/markdown tiers, all values are empty strings.
+   * Renderers should use these tokens instead of hardcoding colors.
+   */
+  theme: ThemeTokens
+
+  /**
+   * Whether interactive input is enabled
+   * @remarks
+   * True only for the 'interactive' tier. Indicates that the renderer
+   * should support keyboard input, mouse events, and real-time updates.
+   * Always false for non-interactive tiers.
+   */
+  interactive: boolean
+}
+
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+
+/**
+ * Zod schema for RenderTier validation.
+ *
+ * @remarks
+ * Validates that a value is one of the six defined render tiers.
+ * Rejects any other string or non-string values.
+ *
+ * **Validation Rules:**
+ * - Must be exactly one of: 'text', 'markdown', 'ascii', 'unicode', 'ansi', 'interactive'
+ * - Case-sensitive (e.g., 'TEXT' is rejected)
+ * - Rejects null, undefined, numbers, objects
+ *
+ * @example
+ * ```tsx
+ * // Valid
+ * RenderTierSchema.parse('ansi')
+ * RenderTierSchema.parse('text')
+ *
+ * // Invalid - throws ZodError
+ * RenderTierSchema.parse('html')
+ * RenderTierSchema.parse('TEXT')
+ * RenderTierSchema.parse(123)
+ * ```
+ */
+export const RenderTierSchema = z.enum([
+  'text',
+  'markdown',
+  'ascii',
+  'unicode',
+  'ansi',
+  'interactive',
+])
+
+/**
+ * Zod schema for ThemeTokens validation.
+ *
+ * @remarks
+ * Validates that all 10 color tokens are present and are strings.
+ * No validation of ANSI code format - any string is accepted
+ * (including empty strings for text tier).
+ *
+ * **Validation Rules:**
+ * - All 10 fields are required: primary, secondary, muted, foreground,
+ *   background, border, success, warning, error, info
+ * - Each field must be a string (empty string is valid)
+ * - Rejects objects with missing fields or non-string values
+ * - No validation of ANSI code validity
+ *
+ * **Required Fields:**
+ * ```
+ * primary, secondary, muted, foreground, background,
+ * border, success, warning, error, info
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Valid theme
+ * const validTheme = {
+ *   primary: '\x1b[34m',
+ *   secondary: '\x1b[36m',
+ *   muted: '\x1b[90m',
+ *   foreground: '\x1b[37m',
+ *   background: '\x1b[40m',
+ *   border: '\x1b[90m',
+ *   success: '\x1b[32m',
+ *   warning: '\x1b[33m',
+ *   error: '\x1b[31m',
+ *   info: '\x1b[34m',
+ * }
+ * ThemeTokensSchema.parse(validTheme) // OK
+ *
+ * // Invalid - missing field
+ * ThemeTokensSchema.parse({ primary: '\x1b[34m' }) // Throws
+ *
+ * // Invalid - non-string value
+ * ThemeTokensSchema.parse({ ...validTheme, primary: 123 }) // Throws
+ * ```
+ */
+export const ThemeTokensSchema = z.object({
+  primary: z.string(),
+  secondary: z.string(),
+  muted: z.string(),
+  foreground: z.string(),
+  background: z.string(),
+  border: z.string(),
+  success: z.string(),
+  warning: z.string(),
+  error: z.string(),
+  info: z.string(),
+})
+
+/**
+ * Zod schema for UINode validation.
+ *
+ * @remarks
+ * Validates the complete UINode structure including recursive children.
+ * Uses `z.lazy()` to support arbitrary nesting depth.
+ *
+ * **Validation Rules:**
+ * - `type`: Required, must be string
+ * - `props`: Required, must be object with string keys and any values
+ * - `children`: Optional, must be array of UINode objects
+ * - `data`: Optional, can be any value (unknown)
+ * - `key`: Optional, must be string if provided
+ * - Extra fields are not allowed (strict validation)
+ *
+ * **Recursion:**
+ * Uses `z.lazy()` to support infinitely nested children without
+ * causing infinite type computation. Each child must also be valid UINode.
+ *
+ * @example
+ * ```tsx
+ * // Valid - simple node
+ * UINodeSchema.parse({
+ *   type: 'text',
+ *   props: { content: 'Hello' }
+ * }) // OK
+ *
+ * // Valid - nested children
+ * UINodeSchema.parse({
+ *   type: 'box',
+ *   props: {},
+ *   children: [
+ *     { type: 'text', props: { content: 'Child' } }
+ *   ]
+ * }) // OK
+ *
+ * // Valid - all optional fields
+ * UINodeSchema.parse({
+ *   type: 'table',
+ *   props: { columns: ['A', 'B'] },
+ *   children: [],
+ *   data: [{ a: 1, b: 2 }],
+ *   key: 'table-1'
+ * }) // OK
+ *
+ * // Invalid - missing type
+ * UINodeSchema.parse({ props: {} }) // Throws ZodError
+ *
+ * // Invalid - non-string type
+ * UINodeSchema.parse({ type: 123, props: {} }) // Throws ZodError
+ *
+ * // Invalid - invalid child
+ * UINodeSchema.parse({
+ *   type: 'box',
+ *   props: {},
+ *   children: [{ props: {} }] // Missing type
+ * }) // Throws ZodError
+ * ```
+ */
+export const UINodeSchema: z.ZodType<UINode> = z.lazy(() =>
+  z.object({
+    type: z.string(),
+    props: z.record(z.string(), z.unknown()).optional(),
+    children: z.union([z.array(UINodeSchema), z.string()]).optional(),
+    text: z.string().optional(),
+    data: z.unknown().optional(),
+    key: z.string().optional(),
+  })
+)
+
+/**
+ * Zod schema for RenderContext validation.
+ *
+ * @remarks
+ * Validates the complete RenderContext structure with all required fields.
+ * Ensures numeric constraints are met and nested types are valid.
+ *
+ * **Validation Rules:**
+ * - `tier`: Required, must be valid RenderTier
+ * - `width`: Required, must be non-negative number (positive in practice)
+ * - `height`: Required, must be non-negative number (positive in practice)
+ * - `depth`: Required, must be non-negative number
+ * - `theme`: Required, must be valid ThemeTokens with all fields
+ * - `interactive`: Required, must be boolean
+ * - All fields are required (no optional fields)
+ * - Extra fields are not allowed
+ *
+ * **Numeric Constraints:**
+ * - width, height, depth must all satisfy `.nonnegative()`
+ * - No upper bounds enforced (size validation handled elsewhere)
+ *
+ * @example
+ * ```tsx
+ * // Valid context
+ * RenderContextSchema.parse({
+ *   tier: 'ansi',
+ *   width: 80,
+ *   height: 24,
+ *   depth: 0,
+ *   theme: {
+ *     primary: '\x1b[34m',
+ *     secondary: '\x1b[36m',
+ *     muted: '\x1b[90m',
+ *     foreground: '\x1b[37m',
+ *     background: '\x1b[40m',
+ *     border: '\x1b[90m',
+ *     success: '\x1b[32m',
+ *     warning: '\x1b[33m',
+ *     error: '\x1b[31m',
+ *     info: '\x1b[34m',
+ *   },
+ *   interactive: false
+ * }) // OK
+ *
+ * // Invalid - negative width
+ * RenderContextSchema.parse({
+ *   tier: 'text',
+ *   width: -10,  // ERROR
+ *   height: 24,
+ *   depth: 0,
+ *   theme: { primary: '', secondary: '' }, // truncated
+ *   interactive: false
+ * }) // Throws ZodError
+ *
+ * // Invalid - invalid tier
+ * RenderContextSchema.parse({
+ *   tier: 'html',  // ERROR - not a valid tier
+ *   width: 80,
+ *   height: 24,
+ *   depth: 0,
+ *   theme: { primary: '', secondary: '' }, // truncated
+ *   interactive: false
+ * }) // Throws ZodError
+ *
+ * // Invalid - missing theme field
+ * RenderContextSchema.parse({
+ *   tier: 'text',
+ *   width: 80,
+ *   height: 24,
+ *   depth: 0,
+ *   interactive: false
+ *   // Missing: theme field
+ * }) // Throws ZodError
+ * ```
+ */
+export const RenderContextSchema = z.object({
+  tier: RenderTierSchema,
+  width: z.number().nonnegative(),
+  height: z.number().nonnegative(),
+  depth: z.number().nonnegative(),
+  theme: ThemeTokensSchema,
+  interactive: z.boolean(),
+})