green-screen-react 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,400 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Supported terminal protocol types.
+ */
+type TerminalProtocol = 'tn5250' | 'tn3270' | 'vt' | 'hp6530';
+/**
+ * Protocol-specific color/rendering conventions.
+ */
+interface ProtocolColorProfile {
+    /** CSS class for a row based on its index and content */
+    getRowColorClass(rowIndex: number, rowContent: string, totalRows: number): string;
+    /** Parse the header row into colored segments, or null for default rendering */
+    parseHeaderRow(line: string): {
+        text: string;
+        colorClass: string;
+    }[] | null;
+}
+/**
+ * Protocol profile — configures terminal behavior per legacy system type.
+ */
+interface ProtocolProfile {
+    /** Protocol identifier */
+    protocol: TerminalProtocol;
+    /** Human-readable name */
+    displayName: string;
+    /** Default terminal dimensions */
+    defaultRows: number;
+    defaultCols: number;
+    /** Color/rendering profile */
+    colors: ProtocolColorProfile;
+    /** Header label shown in terminal chrome */
+    headerLabel: string;
+    /** Boot loader default text */
+    bootText: string;
+}
+/**
+ * Field definition from the terminal data stream.
+ * Describes an input or protected field on the terminal screen.
+ */
+interface Field {
+    /** 0-based row index */
+    row: number;
+    /** 0-based column index */
+    col: number;
+    /** Field length in characters */
+    length: number;
+    /** Whether the field accepts user input */
+    is_input: boolean;
+    /** Whether the field is protected (read-only) */
+    is_protected: boolean;
+    /** Whether the field is displayed with high intensity (bright/white) */
+    is_highlighted?: boolean;
+    /** Whether the field is displayed in reverse video */
+    is_reverse?: boolean;
+}
+/**
+ * Screen data returned by the adapter.
+ * Represents the current state of the terminal screen.
+ */
+interface ScreenData {
+    /** Screen content as newline-separated text (e.g. 24 lines of 80 chars) */
+    content: string;
+    /** 0-based cursor row */
+    cursor_row: number;
+    /** 0-based cursor column */
+    cursor_col: number;
+    /** Number of rows (default 24) */
+    rows?: number;
+    /** Number of columns (default 80) */
+    cols?: number;
+    /** Field definitions on the current screen */
+    fields?: Field[];
+    /** Unique identifier for the current screen state */
+    screen_signature?: string;
+    /** ISO timestamp of when this screen was captured */
+    timestamp?: string;
+}
+/**
+ * Connection status information.
+ */
+interface ConnectionStatus {
+    /** Whether a TCP connection is established */
+    connected: boolean;
+    /** Current connection state */
+    status: 'disconnected' | 'connecting' | 'connected' | 'authenticated' | 'error';
+    /** Terminal protocol in use */
+    protocol?: TerminalProtocol;
+    /** Host address */
+    host?: string;
+    /** Authenticated username */
+    username?: string;
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/**
+ * Result from a send operation (text or key).
+ */
+interface SendResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Updated cursor row after the operation */
+    cursor_row?: number;
+    /** Updated cursor column after the operation */
+    cursor_col?: number;
+    /** Updated screen content after the operation (for key presses that change screens) */
+    content?: string;
+    /** Updated screen signature */
+    screen_signature?: string;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Adapter interface for terminal communication.
+ *
+ * Implement this interface to connect the terminal component to your backend.
+ * The package ships a `RestAdapter` for HTTP-based backends.
+ */
+interface TerminalAdapter {
+    /** Fetch the current screen content */
+    getScreen(): Promise<ScreenData | null>;
+    /** Fetch the current connection status */
+    getStatus(): Promise<ConnectionStatus>;
+    /** Send text input to the terminal */
+    sendText(text: string): Promise<SendResult>;
+    /** Send a special key (ENTER, F1-F24, TAB, etc.) */
+    sendKey(key: string): Promise<SendResult>;
+    /** Establish a connection, optionally with sign-in config */
+    connect(config?: ConnectConfig): Promise<SendResult>;
+    /** Close the connection */
+    disconnect(): Promise<SendResult>;
+    /** Reconnect to the host */
+    reconnect(): Promise<SendResult>;
+}
+/**
+ * Configuration passed from the inline sign-in form to adapter.connect().
+ */
+interface ConnectConfig {
+    /** Target host address */
+    host: string;
+    /** Target port (optional, adapter/server can default per protocol) */
+    port?: number;
+    /** Terminal protocol */
+    protocol: TerminalProtocol;
+    /** Username for authentication */
+    username: string;
+    /** Password for authentication */
+    password: string;
+}
+/** @deprecated Use `TerminalAdapter` instead */
+type TN5250Adapter = TerminalAdapter;
+
+interface GreenScreenTerminalProps {
+    /** Adapter for communicating with the terminal backend */
+    adapter: TerminalAdapter;
+    /** Terminal protocol (determines color conventions, header label, etc.) */
+    protocol?: TerminalProtocol;
+    /** Custom protocol profile (overrides protocol param) */
+    protocolProfile?: ProtocolProfile;
+    /** Direct screen data injection (bypasses polling) */
+    screenData?: ScreenData | null;
+    /** Direct connection status injection */
+    connectionStatus?: ConnectionStatus | null;
+    /** Whether the terminal is read-only (no keyboard input) */
+    readOnly?: boolean;
+    /** Polling interval in ms (0 to disable polling; default 2000) */
+    pollInterval?: number;
+    /** Whether to auto-reconnect on disconnect (default true) */
+    autoReconnect?: boolean;
+    /** Max auto-reconnect attempts (default 5) */
+    maxReconnectAttempts?: number;
+    /** Compact embedded mode */
+    embedded?: boolean;
+    /** Show the header bar (default true) */
+    showHeader?: boolean;
+    /** Enable typing animation (default true) */
+    typingAnimation?: boolean;
+    /** Typing animation budget in ms (default 60) */
+    typingBudgetMs?: number;
+    /** Show inline sign-in form when disconnected (default false) */
+    inlineSignIn?: boolean;
+    /** Default protocol for the sign-in form dropdown (default 'tn5250') */
+    defaultProtocol?: TerminalProtocol;
+    /** Callback when sign-in form is submitted */
+    onSignIn?: (config: ConnectConfig) => void;
+    /** Custom boot loader element, or false to disable */
+    bootLoader?: React.ReactNode | false;
+    /** Content for the right side of the header */
+    headerRight?: React.ReactNode;
+    /** Overlay content (e.g. "Extracting..." state) */
+    overlay?: React.ReactNode;
+    /** Callback for notifications (replaces toast) */
+    onNotification?: (message: string, type: 'info' | 'error') => void;
+    /** Callback when screen content changes */
+    onScreenChange?: (screen: ScreenData) => void;
+    /** Callback for minimize action (embedded mode) */
+    onMinimize?: () => void;
+    /** Additional CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+}
+/** @deprecated Use GreenScreenTerminalProps instead */
+type TN5250TerminalProps = GreenScreenTerminalProps;
+/**
+ * GreenScreenTerminal — Multi-protocol legacy terminal emulator component.
+ *
+ * Renders a terminal screen with:
+ * - Green-on-black terminal aesthetic with protocol-specific color conventions
+ * - Connection status indicator
+ * - Keyboard input support (text, function keys, tab)
+ * - Auto-reconnect with exponential backoff
+ * - Typing animation for field entries
+ * - Focus lock mode for keyboard capture
+ *
+ * Supports: TN5250 (IBM i), TN3270 (z/OS), VT (OpenVMS/Pick), HP 6530 (NonStop)
+ */
+declare function GreenScreenTerminal({ adapter, protocol, protocolProfile: customProfile, screenData: externalScreenData, connectionStatus: externalStatus, readOnly, pollInterval, autoReconnect: autoReconnectEnabled, maxReconnectAttempts: maxAttempts, embedded, showHeader, typingAnimation, typingBudgetMs, inlineSignIn, defaultProtocol: signInDefaultProtocol, onSignIn, bootLoader, headerRight, overlay, onNotification, onScreenChange, onMinimize, className, style, }: GreenScreenTerminalProps): react_jsx_runtime.JSX.Element;
+/** @deprecated Use GreenScreenTerminal instead */
+declare const TN5250Terminal: typeof GreenScreenTerminal;
+
+interface TerminalBootLoaderProps {
+    /** Text to display during boot animation */
+    brandText?: string;
+    /** Speed in ms per character */
+    charSpeed?: number;
+    /** Optional logo element to render alongside the text */
+    logo?: React.ReactNode;
+    /** Height of the boot loader container */
+    height?: number | string;
+}
+/**
+ * Animated boot loader for the terminal.
+ * Shows a typewriter-style text reveal animation.
+ */
+declare function TerminalBootLoader({ brandText, charSpeed, logo, height, }: TerminalBootLoaderProps): react_jsx_runtime.JSX.Element;
+
+interface RestAdapterOptions {
+    /** Base URL for the terminal API (e.g. "https://myhost.com/api/terminal") */
+    baseUrl: string;
+    /** Optional headers to include with every request (e.g. Authorization) */
+    headers?: Record<string, string>;
+    /** Optional function that returns headers (called per-request, useful for dynamic tokens) */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+}
+/**
+ * REST API adapter for terminal communication.
+ *
+ * Expects a backend that exposes these endpoints relative to `baseUrl`:
+ * - GET  /screen       → ScreenData
+ * - GET  /status       → ConnectionStatus
+ * - POST /send-text    → SendResult  (body: { text })
+ * - POST /send-key     → SendResult  (body: { key })
+ * - POST /connect      → SendResult
+ * - POST /disconnect   → SendResult
+ * - POST /reconnect    → SendResult
+ */
+declare class RestAdapter implements TerminalAdapter {
+    private baseUrl;
+    private staticHeaders;
+    private getHeaders?;
+    constructor(options: RestAdapterOptions);
+    private buildHeaders;
+    private request;
+    getScreen(): Promise<ScreenData | null>;
+    getStatus(): Promise<ConnectionStatus>;
+    sendText(text: string): Promise<SendResult>;
+    sendKey(key: string): Promise<SendResult>;
+    connect(config?: ConnectConfig): Promise<SendResult>;
+    disconnect(): Promise<SendResult>;
+    reconnect(): Promise<SendResult>;
+}
+
+/**
+ * Hook for typing animation effect on terminal screen content.
+ * Reveals characters progressively when screen content changes.
+ * Also provides animated cursor position that follows the typing.
+ *
+ * Uses a queue-based model: incoming content updates are queued when an
+ * animation is in progress, then played sequentially. This prevents
+ * blinks (no mid-animation cancellation) and skips (every field entry
+ * gets its own animation). Queue depth is capped to avoid falling
+ * behind real-time.
+ *
+ * Screen transitions (large changes) always display SYNCHRONOUSLY.
+ */
+declare function useTypingAnimation(content: string | null | undefined, enabled?: boolean, typingBudgetMs?: number): {
+    displayedContent: string;
+    isAnimating: boolean;
+    animatedCursorPos: {
+        row: number;
+        col: number;
+    } | null;
+};
+
+/**
+ * Hook for terminal connection management via adapter.
+ */
+declare function useTerminalConnection(adapter: TerminalAdapter): {
+    status: ConnectionStatus | null;
+    loading: boolean;
+    error: string | null;
+    fetchStatus: () => Promise<ConnectionStatus | null>;
+    connect: (config?: ConnectConfig) => Promise<{
+        success: boolean;
+        cursor_row?: number;
+        cursor_col?: number;
+        content?: string;
+        screen_signature?: string;
+        error?: string;
+    }>;
+    disconnect: () => Promise<{
+        success: boolean;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+    }>;
+    reconnect: () => Promise<{
+        success: boolean;
+        cursor_row?: number;
+        cursor_col?: number;
+        content?: string;
+        screen_signature?: string;
+        error?: string;
+    }>;
+};
+/**
+ * Hook for terminal screen content with polling.
+ */
+declare function useTerminalScreen(adapter: TerminalAdapter, interval?: number, enabled?: boolean): {
+    data: ScreenData | null;
+    error: unknown;
+};
+/**
+ * Hook for terminal operations (sendText, sendKey).
+ */
+declare function useTerminalInput(adapter: TerminalAdapter): {
+    loading: boolean;
+    error: string | null;
+    sendText: (text: string) => Promise<SendResult>;
+    sendKey: (key: string) => Promise<SendResult>;
+};
+/** @deprecated Use `useTerminalConnection` instead */
+declare const useTN5250Connection: typeof useTerminalConnection;
+/** @deprecated Use `useTerminalScreen` instead */
+declare const useTN5250Screen: typeof useTerminalScreen;
+/** @deprecated Use `useTerminalInput` instead */
+declare const useTN5250Terminal: typeof useTerminalInput;
+
+/**
+ * Get a protocol profile by type. Defaults to TN5250 for backward compatibility.
+ */
+declare function getProtocolProfile(protocol?: TerminalProtocol): ProtocolProfile;
+
+declare const tn5250Profile: ProtocolProfile;
+
+declare const tn3270Profile: ProtocolProfile;
+
+declare const vtProfile: ProtocolProfile;
+
+declare const hp6530Profile: ProtocolProfile;
+
+/**
+ * Convert a linear position in screen content to row/col coordinates.
+ * Content is lines of characters separated by newlines.
+ */
+declare function positionToRowCol(content: string, position: number): {
+    row: number;
+    col: number;
+};
+/**
+ * Detect if a content change is a field entry (small, localized change)
+ * vs a screen transition (large, distributed change).
+ *
+ * Field entries: < 50 changed characters within a span of < 100 positions.
+ * Screen transitions: everything else.
+ */
+declare function isFieldEntry(previousContent: string | null | undefined, content: string | null | undefined): boolean;
+
+/**
+ * Get the appropriate CSS class name for a row.
+ * Delegates to the TN5250 protocol profile for backward compatibility.
+ *
+ * For protocol-aware rendering, use `getProtocolProfile(protocol).colors.getRowColorClass()`.
+ */
+declare function getRowColorClass(rowIndex: number, rowContent: string): string;
+/**
+ * Parse the header row into colored segments.
+ * Delegates to the TN5250 protocol profile for backward compatibility.
+ *
+ * For protocol-aware rendering, use `getProtocolProfile(protocol).colors.parseHeaderRow()`.
+ */
+declare function parseHeaderRow(line: string): {
+    text: string;
+    colorClass: string;
+}[] | null;
+
+export { type ConnectConfig, type ConnectionStatus, type Field, GreenScreenTerminal, type GreenScreenTerminalProps, type ProtocolColorProfile, type ProtocolProfile, RestAdapter, type RestAdapterOptions, type ScreenData, type SendResult, type TN5250Adapter, TN5250Terminal, type TN5250TerminalProps, type TerminalAdapter, TerminalBootLoader, type TerminalBootLoaderProps, type TerminalProtocol, getProtocolProfile, getRowColorClass, hp6530Profile, isFieldEntry, parseHeaderRow, positionToRowCol, tn3270Profile, tn5250Profile, useTN5250Connection, useTN5250Screen, useTN5250Terminal, useTerminalConnection, useTerminalInput, useTerminalScreen, useTypingAnimation, vtProfile };