blecsd 0.4.0 → 0.6.2

package/dist/terminalBuffer-BbUz27qM.d.ts

@@ -0,0 +1,691 @@
+import { z } from 'zod';
+import { W as World, E as Entity } from './types-B8LmNkzG.js';
+import { A as Attribute } from './parser-Q1YLXYpF.js';
+import { S as ScreenBufferData, C as Cell } from './cell-5Ty_3yMs.js';
+import { S as ScrollbackBuffer } from './virtualScrollback-CiooIebp.js';
+
+/**
+ * List Component Types
+ *
+ * @module components/list/types
+ */
+/**
+ * List state type.
+ */
+type ListState = 'idle' | 'focused' | 'selecting' | 'searching' | 'disabled';
+/**
+ * List event type.
+ */
+type ListEvent = 'focus' | 'blur' | 'startSelect' | 'endSelect' | 'startSearch' | 'endSearch' | 'disable' | 'enable';
+/**
+ * List item data.
+ */
+interface ListItem {
+    /** Display text */
+    readonly text: string;
+    /** Optional value associated with the item */
+    readonly value?: string;
+    /** Whether the item is disabled */
+    readonly disabled?: boolean;
+}
+/**
+ * List store for managing list-specific data.
+ */
+interface ListStore {
+    /** Whether entity is a list */
+    isList: Uint8Array;
+    /** Currently selected index (-1 if none) */
+    selectedIndex: Int32Array;
+    /** Number of items in the list */
+    itemCount: Uint32Array;
+    /** First visible item index (for virtualization) */
+    firstVisible: Uint32Array;
+    /** Number of visible items */
+    visibleCount: Uint32Array;
+    /** Whether list is interactive */
+    interactive: Uint8Array;
+    /** Whether list responds to mouse */
+    mouse: Uint8Array;
+    /** Whether list responds to keyboard */
+    keys: Uint8Array;
+    /** Whether search mode is enabled */
+    searchEnabled: Uint8Array;
+    /** Total item count for virtualized lists (may be > itemCount) */
+    totalCount: Uint32Array;
+    /** Whether items are currently loading */
+    isLoading: Uint8Array;
+}
+/**
+ * Lazy load callback for virtualized lists.
+ * Called when items need to be loaded for a range.
+ *
+ * @param startIndex - First item index to load
+ * @param count - Number of items to load
+ * @returns Promise that resolves when items are loaded
+ */
+type ListLazyLoadCallback = (startIndex: number, count: number) => Promise<ListItem[]>;
+/**
+ * Scroll event callback for infinite scroll detection.
+ *
+ * @param scrollInfo - Information about current scroll state
+ */
+type ListScrollCallback = (scrollInfo: ListScrollInfo) => void;
+/**
+ * Scroll information for infinite scroll.
+ */
+interface ListScrollInfo {
+    /** First visible item index */
+    readonly firstVisible: number;
+    /** Number of visible items */
+    readonly visibleCount: number;
+    /** Total loaded items */
+    readonly loadedCount: number;
+    /** Total items (may be larger than loaded for infinite scroll) */
+    readonly totalCount: number;
+    /** Whether we're near the end (within threshold) */
+    readonly nearEnd: boolean;
+    /** Whether we're near the start (within threshold) */
+    readonly nearStart: boolean;
+}
+/**
+ * List display configuration.
+ */
+interface ListDisplay {
+    /** Character shown before selected item */
+    readonly selectedPrefix: string;
+    /** Character shown before unselected items */
+    readonly unselectedPrefix: string;
+    /** Selected item foreground color */
+    readonly selectedFg: number;
+    /** Selected item background color */
+    readonly selectedBg: number;
+    /** Item foreground color */
+    readonly itemFg: number;
+    /** Item background color */
+    readonly itemBg: number;
+    /** Disabled item foreground color */
+    readonly disabledFg: number;
+}
+/**
+ * List display options for configuration.
+ */
+interface ListDisplayOptions {
+    selectedPrefix?: string;
+    unselectedPrefix?: string;
+    selectedFg?: number;
+    selectedBg?: number;
+    itemFg?: number;
+    itemBg?: number;
+    disabledFg?: number;
+}
+/**
+ * List selection callback function type.
+ */
+type ListSelectCallback = (index: number, item: ListItem) => void;
+/**
+ * List action returned from key press handling.
+ */
+type ListAction = {
+    type: 'selectPrev';
+} | {
+    type: 'selectNext';
+} | {
+    type: 'selectFirst';
+} | {
+    type: 'selectLast';
+} | {
+    type: 'pageUp';
+} | {
+    type: 'pageDown';
+} | {
+    type: 'confirm';
+} | {
+    type: 'cancel';
+} | {
+    type: 'toggleSelect';
+} | {
+    type: 'startSearch';
+} | {
+    type: 'endSearch';
+} | {
+    type: 'searchChar';
+    char: string;
+} | {
+    type: 'searchBackspace';
+} | {
+    type: 'searchNextMatch';
+};
+
+/**
+ * Scrollable component for scrolling support.
+ * @module components/scrollable
+ */
+/**
+ * Scrollbar visibility mode.
+ */
+declare enum ScrollbarVisibility {
+    /** Always hidden */
+    Hidden = 0,
+    /** Always visible */
+    Visible = 1,
+    /** Visible only when content overflows */
+    Auto = 2
+}
+/**
+ * Scrollable component store using SoA (Structure of Arrays) for performance.
+ *
+ * - `scrollX`, `scrollY`: Current scroll offset
+ * - `scrollWidth`, `scrollHeight`: Total scrollable content size
+ * - `scrollbarVisible`: Scrollbar visibility mode
+ * - `trackVisible`: Whether scroll track is visible
+ * - `alwaysScroll`: Always show scrollbar even when not needed
+ *
+ * @example
+ * ```typescript
+ * import { Scrollable, setScroll, getScroll, scrollBy } from 'blecsd';
+ *
+ * setScroll(world, entity, 0, 100);
+ * scrollBy(world, entity, 0, 50);
+ *
+ * const scroll = getScroll(world, entity);
+ * console.log(scroll.y); // 150
+ * ```
+ */
+declare const Scrollable: {
+    /** Horizontal scroll offset */
+    scrollX: Float32Array<ArrayBuffer>;
+    /** Vertical scroll offset */
+    scrollY: Float32Array<ArrayBuffer>;
+    /** Total scrollable width */
+    scrollWidth: Float32Array<ArrayBuffer>;
+    /** Total scrollable height */
+    scrollHeight: Float32Array<ArrayBuffer>;
+    /** Viewport width (visible area) - used for clamping */
+    viewportWidth: Float32Array<ArrayBuffer>;
+    /** Viewport height (visible area) - used for clamping */
+    viewportHeight: Float32Array<ArrayBuffer>;
+    /** Scrollbar visibility mode (0=hidden, 1=visible, 2=auto) */
+    scrollbarVisible: Uint8Array<ArrayBuffer>;
+    /** Whether scroll track is visible */
+    trackVisible: Uint8Array<ArrayBuffer>;
+    /** Always show scrollbar (0=no, 1=yes) */
+    alwaysScroll: Uint8Array<ArrayBuffer>;
+    /** Whether clamping is enabled (0=no, 1=yes) - default yes */
+    clampEnabled: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Scrollable configuration options.
+ */
+interface ScrollableOptions {
+    /** Initial horizontal scroll offset */
+    scrollX?: number;
+    /** Initial vertical scroll offset */
+    scrollY?: number;
+    /** Total scrollable width */
+    scrollWidth?: number;
+    /** Total scrollable height */
+    scrollHeight?: number;
+    /** Viewport width (visible area) */
+    viewportWidth?: number;
+    /** Viewport height (visible area) */
+    viewportHeight?: number;
+    /** Scrollbar visibility mode */
+    scrollbarVisible?: ScrollbarVisibility;
+    /** Whether scroll track is visible */
+    trackVisible?: boolean;
+    /** Always show scrollbar */
+    alwaysScroll?: boolean;
+    /** Whether scroll clamping is enabled (default: true) */
+    clampEnabled?: boolean;
+}
+/**
+ * Scroll position data.
+ */
+interface ScrollPosition {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Scroll percentage data.
+ */
+interface ScrollPercentage {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Full scrollable data returned by getScrollable.
+ */
+interface ScrollableData {
+    readonly scrollX: number;
+    readonly scrollY: number;
+    readonly scrollWidth: number;
+    readonly scrollHeight: number;
+    readonly viewportWidth: number;
+    readonly viewportHeight: number;
+    readonly scrollbarVisible: ScrollbarVisibility;
+    readonly trackVisible: boolean;
+    readonly alwaysScroll: boolean;
+    readonly clampEnabled: boolean;
+}
+
+/**
+ * Table Component
+ *
+ * Pure data container for table/grid functionality.
+ * All business logic is in tableSystem.ts.
+ *
+ * @module components/table
+ */
+/**
+ * Table cell alignment.
+ */
+type CellAlign = 'left' | 'center' | 'right';
+/**
+ * Table cell data.
+ */
+interface TableCell {
+    /** Cell text value */
+    readonly value: string;
+    /** Cell foreground color (optional) */
+    readonly fg?: number;
+    /** Cell background color (optional) */
+    readonly bg?: number;
+    /** Cell alignment (optional, defaults to left) */
+    readonly align?: CellAlign;
+}
+/**
+ * Table row data.
+ */
+type TableRow = readonly TableCell[];
+/**
+ * Table data (array of rows).
+ */
+type TableData = readonly TableRow[];
+/**
+ * Table column configuration.
+ */
+interface TableColumn {
+    /** Column header text */
+    readonly header: string;
+    /** Column width (characters) */
+    readonly width?: number | undefined;
+    /** Column minimum width */
+    readonly minWidth?: number | undefined;
+    /** Column maximum width */
+    readonly maxWidth?: number | undefined;
+    /** Column alignment */
+    readonly align?: CellAlign | undefined;
+}
+/**
+ * Table store for managing table-specific data.
+ */
+interface TableStore {
+    /** Whether entity is a table */
+    isTable: Uint8Array;
+    /** Number of rows in table */
+    rowCount: Uint32Array;
+    /** Number of columns in table */
+    colCount: Uint16Array;
+    /** Number of header rows */
+    headerRows: Uint8Array;
+    /** Cell padding */
+    pad: Uint8Array;
+    /** Whether to show cell borders */
+    cellBorders: Uint8Array;
+}
+/**
+ * Table display configuration.
+ */
+interface TableDisplay {
+    /** Header foreground color */
+    readonly headerFg: number;
+    /** Header background color */
+    readonly headerBg: number;
+    /** Cell foreground color */
+    readonly cellFg: number;
+    /** Cell background color */
+    readonly cellBg: number;
+    /** Alternate row background color (for striping) */
+    readonly altRowBg?: number;
+    /** Border foreground color */
+    readonly borderFg: number;
+    /** Border background color */
+    readonly borderBg: number;
+    /** Selected row foreground color */
+    readonly selectedFg?: number;
+    /** Selected row background color */
+    readonly selectedBg?: number;
+}
+/**
+ * Table display options for configuration.
+ */
+interface TableDisplayOptions {
+    headerFg?: number;
+    headerBg?: number;
+    cellFg?: number;
+    cellBg?: number;
+    altRowBg?: number;
+    borderFg?: number;
+    borderBg?: number;
+    selectedFg?: number;
+    selectedBg?: number;
+}
+/** Default header foreground color */
+declare const DEFAULT_HEADER_FG = 4294967295;
+/** Default header background color */
+declare const DEFAULT_HEADER_BG = 858993663;
+/** Default cell foreground color */
+declare const DEFAULT_CELL_FG = 3435973887;
+/** Default cell background color */
+declare const DEFAULT_CELL_BG = 255;
+/** Default border foreground color */
+declare const DEFAULT_BORDER_FG = 1717987071;
+/** Default border background color */
+declare const DEFAULT_BORDER_BG = 255;
+/**
+ * Table component store using SoA (Structure of Arrays) for performance.
+ *
+ * Stores table grid metadata.
+ *
+ * @deprecated Use tableStore instead
+ *
+ * @example
+ * ```typescript
+ * import { Table, attachTableBehavior, setData } from 'blecsd';
+ *
+ * attachTableBehavior(world, eid);
+ * setData(world, eid, [
+ *   ['Name', 'Age'],
+ *   ['Alice', '30'],
+ * ]);
+ * ```
+ */
+declare const Table: {
+    /** Number of data rows (excluding headers) */
+    rowCount: Uint32Array<ArrayBuffer>;
+    /** Number of columns */
+    colCount: Uint16Array<ArrayBuffer>;
+    /** Number of header rows */
+    headerRows: Uint8Array<ArrayBuffer>;
+    /** Cell padding (spaces) */
+    pad: Uint8Array<ArrayBuffer>;
+    /** Whether to render cell borders (0 = no, 1 = yes) */
+    cellBorders: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Store for table component data.
+ */
+declare const tableStore: TableStore;
+
+/**
+ * TerminalBuffer Component
+ *
+ * ECS component for terminal emulator buffers. Stores a 2D grid of cells
+ * with per-cell styling, cursor state, and scrollback history.
+ *
+ * @module components/terminalBuffer
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity } from 'blecsd';
+ * import {
+ *   setTerminalBuffer,
+ *   writeToTerminal,
+ *   getTerminalState,
+ *   clearTerminal,
+ * } from 'blecsd/components';
+ *
+ * const world = createWorld();
+ * const eid = addEntity(world);
+ *
+ * // Initialize a terminal buffer
+ * setTerminalBuffer(world, eid, { width: 80, height: 24 });
+ *
+ * // Write ANSI content
+ * writeToTerminal(world, eid, '\x1b[31mHello\x1b[0m World');
+ *
+ * // Get current state
+ * const state = getTerminalState(eid);
+ * console.log(state?.cursorX, state?.cursorY);
+ *
+ * // Clear the terminal
+ * clearTerminal(world, eid);
+ * ```
+ */
+
+/** Default terminal width in columns */
+declare const DEFAULT_TERMINAL_WIDTH = 80;
+/** Default terminal height in rows */
+declare const DEFAULT_TERMINAL_HEIGHT = 24;
+/** Default scrollback lines */
+declare const DEFAULT_SCROLLBACK_LINES = 1000;
+/**
+ * TerminalBuffer component for scalar state.
+ * Complex state (cells, scrollback, parser state) is stored in a Map.
+ */
+declare const TerminalBuffer: {
+    /** Tag indicating this is a terminal buffer (1 = yes) */
+    isTerminal: Uint8Array<ArrayBuffer>;
+    /** Terminal width in columns */
+    width: Uint16Array<ArrayBuffer>;
+    /** Terminal height in rows */
+    height: Uint16Array<ArrayBuffer>;
+    /** Cursor X position (column) */
+    cursorX: Uint16Array<ArrayBuffer>;
+    /** Cursor Y position (row) */
+    cursorY: Uint16Array<ArrayBuffer>;
+    /** Cursor visible flag (1 = visible) */
+    cursorVisible: Uint8Array<ArrayBuffer>;
+    /** Scroll offset from top (for viewing history) */
+    scrollOffset: Uint32Array<ArrayBuffer>;
+    /** Alternate screen buffer active (1 = yes) */
+    altScreenActive: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Terminal state stored in a Map for complex data.
+ */
+interface TerminalState {
+    /** Cell buffer (2D grid in row-major order) */
+    readonly buffer: ScreenBufferData;
+    /** Scrollback history */
+    readonly scrollback: ScrollbackBuffer;
+    /** Current text attributes for new characters */
+    currentAttr: Attribute;
+    /** Partial escape sequence buffer */
+    escapeBuffer: string;
+    /** Whether we're in the middle of parsing an escape sequence */
+    inEscape: boolean;
+    /** Saved cursor position X */
+    savedCursorX: number;
+    /** Saved cursor position Y */
+    savedCursorY: number;
+    /** Saved attributes */
+    savedAttr: Attribute;
+    /** Alternate screen buffer (for full-screen apps) */
+    altBuffer: ScreenBufferData | null;
+    /** Cursor shape: 'block' | 'underline' | 'bar' */
+    cursorShape: CursorShape;
+    /** Cursor blink enabled */
+    cursorBlink: boolean;
+}
+/**
+ * Cursor shape types.
+ */
+type CursorShape = 'block' | 'underline' | 'bar';
+/**
+ * Terminal buffer configuration schema.
+ */
+declare const TerminalBufferConfigSchema: z.ZodObject<{
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    scrollbackLines: z.ZodDefault<z.ZodNumber>;
+    cursorVisible: z.ZodDefault<z.ZodBoolean>;
+    cursorShape: z.ZodDefault<z.ZodEnum<{
+        underline: "underline";
+        block: "block";
+        bar: "bar";
+    }>>;
+    cursorBlink: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Terminal buffer configuration type.
+ */
+type TerminalBufferConfig = z.input<typeof TerminalBufferConfigSchema>;
+/**
+ * Sets up a terminal buffer on an entity.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ * @param config - Terminal buffer configuration
+ *
+ * @example
+ * ```typescript
+ * setTerminalBuffer(world, eid, {
+ *   width: 80,
+ *   height: 24,
+ *   scrollbackLines: 1000,
+ * });
+ * ```
+ */
+declare function setTerminalBuffer(world: World, eid: Entity, config?: TerminalBufferConfig): void;
+/**
+ * Checks if an entity has a terminal buffer.
+ *
+ * @param eid - Entity ID
+ * @returns true if the entity has a terminal buffer
+ */
+declare function hasTerminalBuffer(eid: Entity): boolean;
+/**
+ * Gets the terminal state for an entity.
+ *
+ * @param eid - Entity ID
+ * @returns Terminal state or undefined
+ */
+declare function getTerminalState(eid: Entity): TerminalState | undefined;
+/**
+ * Gets terminal buffer data (scalar values).
+ *
+ * @param eid - Entity ID
+ * @returns Terminal buffer data
+ */
+declare function getTerminalBuffer(eid: Entity): {
+    width: number;
+    height: number;
+    cursorX: number;
+    cursorY: number;
+    cursorVisible: boolean;
+    scrollOffset: number;
+} | undefined;
+/**
+ * Writes a character to the terminal at the current cursor position.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ * @param char - Character to write
+ */
+declare function writeChar(world: World, eid: Entity, char: string): void;
+/**
+ * Writes a string to the terminal (processes escape sequences).
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ * @param data - String to write
+ */
+declare function writeToTerminal(world: World, eid: Entity, data: string): void;
+/**
+ * Clears the terminal buffer.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ */
+declare function clearTerminal(world: World, eid: Entity): void;
+/**
+ * Resets the terminal to initial state.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ */
+declare function resetTerminal(world: World, eid: Entity): void;
+/**
+ * Sets cursor position.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ * @param x - Column (0-indexed)
+ * @param y - Row (0-indexed)
+ */
+declare function setCursorPosition(world: World, eid: Entity, x: number, y: number): void;
+/**
+ * Sets cursor visibility.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ * @param visible - Cursor visibility
+ */
+declare function setCursorVisible(world: World, eid: Entity, visible: boolean): void;
+/**
+ * Scrolls the terminal view up.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ * @param lines - Number of lines to scroll
+ */
+declare function scrollTerminalUp(world: World, eid: Entity, lines: number): void;
+/**
+ * Scrolls the terminal view down.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ * @param lines - Number of lines to scroll
+ */
+declare function scrollTerminalDown(world: World, eid: Entity, lines: number): void;
+/**
+ * Scrolls to the top of history.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ */
+declare function scrollTerminalToTop(world: World, eid: Entity): void;
+/**
+ * Scrolls to the bottom (current view).
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ */
+declare function scrollTerminalToBottom(world: World, eid: Entity): void;
+/**
+ * Resizes the terminal buffer.
+ *
+ * @param world - The ECS world
+ * @param eid - Entity ID
+ * @param width - New width in columns
+ * @param height - New height in rows
+ */
+declare function resizeTerminalBuffer(world: World, eid: Entity, width: number, height: number): void;
+/**
+ * Removes a terminal buffer from an entity.
+ *
+ * @param eid - Entity ID
+ */
+declare function removeTerminalBuffer(eid: Entity): void;
+/**
+ * Renders terminal buffer to an ANSI string (for display).
+ *
+ * @param eid - Entity ID
+ * @returns ANSI string representation of the terminal
+ */
+declare function renderTerminalToAnsi(eid: Entity): string;
+/**
+ * Gets the cells for rendering.
+ *
+ * @param eid - Entity ID
+ * @returns Readonly array of cells
+ */
+declare function getTerminalCells(eid: Entity): readonly Cell[] | undefined;
+/**
+ * Resets the terminal buffer store (for testing).
+ * @internal
+ */
+declare function resetTerminalBufferStore(): void;
+
+export { scrollTerminalUp as $, type ListScrollCallback as A, Scrollable as B, type CellAlign as C, DEFAULT_CELL_BG as D, Table as E, type TableStore as F, TerminalBuffer as G, type TerminalBufferConfig as H, TerminalBufferConfigSchema as I, type CursorShape as J, type TerminalState as K, type ListSelectCallback as L, clearTerminal as M, getTerminalBuffer as N, getTerminalCells as O, getTerminalState as P, hasTerminalBuffer as Q, removeTerminalBuffer as R, type ScrollableData as S, type TableData as T, renderTerminalToAnsi as U, resetTerminal as V, resetTerminalBufferStore as W, resizeTerminalBuffer as X, scrollTerminalDown as Y, scrollTerminalToBottom as Z, scrollTerminalToTop as _, type ListItem as a, setCursorPosition as a0, setCursorVisible as a1, setTerminalBuffer as a2, tableStore as a3, writeChar as a4, writeToTerminal as a5, type ListState as b, type ListEvent as c, type ListDisplay as d, type ListDisplayOptions as e, type ListAction as f, type ListStore as g, type ListScrollInfo as h, type ScrollableOptions as i, type ScrollPosition as j, type ScrollPercentage as k, ScrollbarVisibility as l, type TableCell as m, type TableRow as n, type TableColumn as o, type TableDisplay as p, type TableDisplayOptions as q, DEFAULT_CELL_FG as r, DEFAULT_HEADER_BG as s, DEFAULT_HEADER_FG as t, DEFAULT_SCROLLBACK_LINES as u, DEFAULT_BORDER_BG as v, DEFAULT_BORDER_FG as w, DEFAULT_TERMINAL_HEIGHT as x, DEFAULT_TERMINAL_WIDTH as y, type ListLazyLoadCallback as z };