@mdxui/terminal 2.0.0

package/dist/types-Ca8p_p5X.d.ts

@@ -0,0 +1,710 @@
+import { z } from 'zod';
+
+/**
+ * @mdxui/terminal UINode Type System
+ *
+ * Core type definitions and Zod schemas for the Universal Terminal UI's
+ * multi-tier rendering architecture.
+ */
+
+/**
+ * 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 }
+ *   ]
+ * }
+ * ```
+ */
+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'
+ * ```
+ */
+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: '',
+ * }
+ * ```
+ */
+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
+ * }
+ * ```
+ */
+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 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)
+ * ```
+ */
+declare const RenderTierSchema: z.ZodEnum<["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
+ * ```
+ */
+declare const ThemeTokensSchema: z.ZodObject<{
+    primary: z.ZodString;
+    secondary: z.ZodString;
+    muted: z.ZodString;
+    foreground: z.ZodString;
+    background: z.ZodString;
+    border: z.ZodString;
+    success: z.ZodString;
+    warning: z.ZodString;
+    error: z.ZodString;
+    info: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    primary: string;
+    secondary: string;
+    muted: string;
+    success: string;
+    warning: string;
+    error: string;
+    info: string;
+    border: string;
+    background: string;
+    foreground: string;
+}, {
+    primary: string;
+    secondary: string;
+    muted: string;
+    success: string;
+    warning: string;
+    error: string;
+    info: string;
+    border: string;
+    background: string;
+    foreground: 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
+ * ```
+ */
+declare const UINodeSchema: z.ZodType<UINode>;
+/**
+ * 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
+ * ```
+ */
+declare const RenderContextSchema: z.ZodObject<{
+    tier: z.ZodEnum<["text", "markdown", "ascii", "unicode", "ansi", "interactive"]>;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    depth: z.ZodNumber;
+    theme: z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodString;
+        muted: z.ZodString;
+        foreground: z.ZodString;
+        background: z.ZodString;
+        border: z.ZodString;
+        success: z.ZodString;
+        warning: z.ZodString;
+        error: z.ZodString;
+        info: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        primary: string;
+        secondary: string;
+        muted: string;
+        success: string;
+        warning: string;
+        error: string;
+        info: string;
+        border: string;
+        background: string;
+        foreground: string;
+    }, {
+        primary: string;
+        secondary: string;
+        muted: string;
+        success: string;
+        warning: string;
+        error: string;
+        info: string;
+        border: string;
+        background: string;
+        foreground: string;
+    }>;
+    interactive: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    width: number;
+    height: number;
+    theme: {
+        primary: string;
+        secondary: string;
+        muted: string;
+        success: string;
+        warning: string;
+        error: string;
+        info: string;
+        border: string;
+        background: string;
+        foreground: string;
+    };
+    interactive: boolean;
+    tier: "text" | "ascii" | "markdown" | "unicode" | "ansi" | "interactive";
+    depth: number;
+}, {
+    width: number;
+    height: number;
+    theme: {
+        primary: string;
+        secondary: string;
+        muted: string;
+        success: string;
+        warning: string;
+        error: string;
+        info: string;
+        border: string;
+        background: string;
+        foreground: string;
+    };
+    interactive: boolean;
+    tier: "text" | "ascii" | "markdown" | "unicode" | "ansi" | "interactive";
+    depth: number;
+}>;
+
+export { type RenderTier as R, type ThemeTokens as T, type UINode as U, type RenderContext as a, UINodeSchema as b, RenderTierSchema as c, ThemeTokensSchema as d, RenderContextSchema as e };