voonex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CodeTease
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# Voonex
+
+**Voonex** is a modern, zero-dependency Terminal UI (TUI) library for Node.js, built with TypeScript. It provides a robust virtual buffer, reactive rendering system, and a rich set of widgets to build complex command-line interfaces with ease.
+
+## Features
+
+- **Zero Dependencies**: Lightweight and easy to audit.
+- **Double Buffering & Diffing**: Efficient rendering that eliminates flickering and minimizes I/O.
+- **Component System**: Built-in widgets like `Box`, `Menu`, `ProgressBar`, `Input`, `Table`, and more.
+- **Reactive Rendering**: Automated screen updates via `Screen.mount()` and `Screen.scheduleRender()`.
+- **Focus Management**: Built-in keyboard navigation and focus delegation.
+- **Styling Engine**: Simple yet powerful API for ANSI colors and text modifiers.
+- **TypeScript Support**: Written in TypeScript with full type definitions included.
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install voonex
+```
+
+## Quick Start
+
+Here is a minimal example showing how to initialize the screen and display a simple box.
+
+```typescript
+import { Screen, Box, Styler, Input } from 'voonex';
+
+// 1. Enter the alternate screen buffer
+Screen.enter();
+
+// 2. Define your render function
+function render() {
+    // Render a Box at (5, 5) with a title
+    Box.render([
+        "Welcome to Voonex!",
+        "Press 'q' to exit."
+    ], {
+        title: "Hello World",
+        x: 5,
+        y: 5,
+        padding: 1,
+        style: 'double',
+        borderColor: 'cyan'
+    });
+}
+
+// 3. Mount the render function to the screen loop
+Screen.mount(render);
+
+// 4. Handle Input
+Input.onKey((key) => {
+    if (key.name === 'q') {
+        // Leave the screen buffer properly before exiting
+        Screen.leave();
+        process.exit(0);
+    }
+});
+```
+
+Run it with:
+```bash
+npx ts-node my-app.ts
+```
+
+## Core Concepts
+
+### The Screen
+The `Screen` class is the heart of Voonex. It manages the terminal buffer, handles resizing, and optimizes rendering using a diffing algorithm.
+
+- `Screen.enter()`: Switches to the alternate buffer (like `vim` or `nano`).
+- `Screen.leave()`: Restores the original terminal state. **Always call this before exiting.**
+- `Screen.mount(renderFn)`: Registers a function to be called during the render cycle. Voonex uses a "Painter's Algorithm", so functions mounted later are drawn on top.
+- `Screen.scheduleRender()`: Triggers a screen update. This is automatically called by most interactive components, but you can call it manually if you update state asynchronously (e.g., inside a `setInterval`).
+
+### Input Handling
+Voonex provides a global input listener wrapper around Node's `process.stdin`.
+
+```typescript
+import { Input } from 'voonex';
+
+Input.onKey((key) => {
+    console.log(key.name); // 'up', 'down', 'enter', 'a', 'b', etc.
+    console.log(key.ctrl); // true if Ctrl is pressed
+});
+```
+
+### Styling
+The `Styler` class provides utilities for coloring and formatting text.
+
+```typescript
+import { Styler } from 'voonex';
+
+const text = Styler.style("Success!", 'green', 'bold', 'underline');
+```
+
+## Components
+
+Voonex comes with several built-in components. Components can be used in two ways:
+1. **Static Rendering**: Using static methods like `Box.render()`.
+2. **Stateful Instances**: Creating an instance (e.g., `new Menu()`) and calling its methods.
+
+### Box
+A container for text with optional borders, padding, and titles.
+
+```typescript
+Box.render([
+    "Line 1",
+    "Line 2"
+], {
+    x: 2, y: 2,
+    width: 30,
+    borderColor: 'green',
+    style: 'round' // 'single', 'double', or 'round'
+});
+```
+
+### Menu
+A vertical list of selectable items.
+
+```typescript
+const menu = new Menu({
+    title: "Main Menu",
+    x: 4, y: 4,
+    items: ["Start", "Options", "Exit"],
+    onSelect: (index, item) => {
+        console.log(`Selected: ${item}`);
+    }
+});
+
+// In your input handler:
+Input.onKey((key) => {
+    menu.handleKey(key); // Passes key events to the menu
+});
+
+// In your render function:
+menu.render();
+```
+
+### ProgressBar
+Displays a progress bar.
+
+```typescript
+const bar = new ProgressBar({
+    width: 20,
+    total: 100,
+    x: 4, y: 10,
+    completeChar: '█',
+    incompleteChar: '░'
+});
+
+// Update progress
+bar.update(50); // 50%
+```
+
+### Popup
+A modal dialog that overlays other content.
+
+```typescript
+// Shows a message and waits for user to press Enter/Esc
+await Popup.alert("This is an important message!", { title: "Alert" });
+
+// Asks for confirmation (returns boolean)
+const confirmed = await Popup.confirm("Are you sure?", { title: "Confirm" });
+```
+
+### Input Field
+A text input field for capturing user input.
+
+```typescript
+const nameInput = new InputField({
+    x: 2, y: 2,
+    width: 20,
+    placeholder: "Enter name..."
+});
+
+Input.onKey(key => {
+    if (key.name === 'tab') {
+        nameInput.focus();
+    }
+    nameInput.handleKey(key);
+});
+
+// In render loop
+nameInput.render();
+```
+
+## Advanced Usage
+
+### Manual Layout
+Voonex relies on absolute positioning `(x, y)`. For complex layouts, you can calculate coordinates dynamically based on `Screen.size`.
+
+```typescript
+const { width, height } = Screen.size;
+const centerX = Math.floor(width / 2);
+const centerY = Math.floor(height / 2);
+```
+
+### Creating Custom Components
+Any class can be a component. To integrate with the Voonex ecosystem, it's recommended (but not required) to implement the `Focusable` interface if the component handles input.
+
+```typescript
+import { Screen, Styler, Focusable } from 'voonex';
+
+class MyWidget implements Focusable {
+    focus() { /* handle focus */ }
+    blur() { /* handle blur */ }
+    
+    handleKey(key) {
+        // return true if key was consumed
+        return false;
+    }
+
+    render() {
+        Screen.write(10, 10, "My Custom Widget");
+    }
+}
+```
+
+## License
+
+This project is under the **MIT License**.

package/dist/components/Box.d.ts

@@ -0,0 +1,33 @@
+import { ColorName } from '../core/Styler';
+import { Focusable } from '../core/Focus';
+import * as readline from 'readline';
+export interface BoxOptions {
+    id?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    padding?: number;
+    borderColor?: ColorName;
+    title?: string;
+    style?: 'single' | 'double' | 'round';
+    scrollable?: boolean;
+    wrap?: boolean;
+}
+export declare class Box implements Focusable {
+    id: string;
+    private options;
+    private content;
+    private processedLines;
+    private scrollTop;
+    private isFocused;
+    constructor(content: string | string[], options?: BoxOptions);
+    private calculateDimensions;
+    private processContent;
+    private wrapLine;
+    focus(): void;
+    blur(): void;
+    handleKey(key: readline.Key): boolean;
+    render(): void;
+    static render(content: string | string[], options?: BoxOptions): void;
+}

package/dist/components/Box.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Box = void 0;
+const Styler_1 = require("../core/Styler");
+const Screen_1 = require("../core/Screen");
+const BORDERS = {
+    single: { tl: '┌', tr: '┐', bl: '└', br: '┘', h: '─', v: '│' },
+    double: { tl: '╔', tr: '╗', bl: '╚', br: '╝', h: '═', v: '║' },
+    round: { tl: '╭', tr: '╮', bl: '╰', br: '╯', h: '─', v: '│' }
+};
+class Box {
+    constructor(content, options = {}) {
+        this.processedLines = [];
+        this.scrollTop = 0;
+        this.isFocused = false;
+        this.id = options.id || `box-${Math.random().toString(36).substr(2, 9)}`;
+        this.options = {
+            padding: 1,
+            style: 'round',
+            borderColor: 'white',
+            scrollable: false,
+            wrap: false,
+            x: 1,
+            y: 1,
+            ...options
+        };
+        this.content = Array.isArray(content) ? content : content.split('\n');
+        this.calculateDimensions();
+        this.processContent();
+    }
+    calculateDimensions() {
+        const { padding } = this.options;
+        const pad = padding || 1;
+        // If width/height not provided, calculate from content
+        if (!this.options.width) {
+            const contentMaxWidth = Math.max(...this.content.map(l => Styler_1.Styler.len(l)));
+            this.options.width = contentMaxWidth + (pad * 2) + 2;
+        }
+        if (!this.options.height) {
+            this.options.height = this.content.length + (pad * 2) + 2;
+        }
+    }
+    processContent() {
+        const { width, padding, wrap } = this.options;
+        const pad = padding || 1;
+        // Ensure innerWidth is at least 1 to avoid infinite loops
+        const calculatedInnerWidth = (width || 0) - 2 - (pad * 2);
+        const innerWidth = Math.max(1, calculatedInnerWidth);
+        if (wrap) {
+            this.processedLines = [];
+            for (const line of this.content) {
+                if (Styler_1.Styler.len(line) <= innerWidth) {
+                    this.processedLines.push(line);
+                }
+                else {
+                    // Simple wrap logic
+                    let currentLine = line;
+                    let safetyCounter = 0;
+                    const MAX_LOOPS = 1000; // Prevent infinite loops
+                    while (Styler_1.Styler.len(currentLine) > innerWidth) {
+                        if (safetyCounter++ > MAX_LOOPS) {
+                            console.error(`Box processContent infinite loop detected. line="${currentLine.substring(0, 20)}..."`);
+                            break;
+                        }
+                        const wrapped = this.wrapLine(currentLine, innerWidth);
+                        // If head is empty, we force a split to avoid infinite loop
+                        if (!wrapped.head && wrapped.tail === currentLine) {
+                            this.processedLines.push(currentLine.substring(0, innerWidth));
+                            currentLine = currentLine.substring(innerWidth);
+                        }
+                        else {
+                            this.processedLines.push(wrapped.head);
+                            currentLine = wrapped.tail;
+                        }
+                    }
+                    if (currentLine)
+                        this.processedLines.push(currentLine);
+                }
+            }
+        }
+        else {
+            this.processedLines = this.content;
+        }
+    }
+    wrapLine(line, width) {
+        // Updated implementation to use Styler.len (visual width) and Styler.truncateWithState
+        const raw = line;
+        const visualLen = Styler_1.Styler.len(raw);
+        if (visualLen <= width)
+            return { head: raw, tail: '' };
+        // Use the new truncateWithState to correctly handle ANSI split
+        const { result, remaining } = Styler_1.Styler.truncateWithState(raw, width);
+        // Word wrapping optimization (optional but nice)
+        // If the cut was in the middle of a word, try to backtrack to last space.
+        // But backtracking with visual width and ANSI is hard. 
+        // For now, stick to char wrap which is robust.
+        return {
+            head: result,
+            tail: remaining
+        };
+    }
+    focus() {
+        this.isFocused = true;
+        this.render(); // Re-render to show focus indicator (border color change?)
+    }
+    blur() {
+        this.isFocused = false;
+        this.render();
+    }
+    handleKey(key) {
+        if (!this.options.scrollable)
+            return false;
+        const { height, padding } = this.options;
+        const pad = padding || 1;
+        const innerHeight = (height || 0) - 2 - (pad * 2);
+        const maxScroll = Math.max(0, this.processedLines.length - innerHeight);
+        let consumed = false;
+        if (key.name === 'up') {
+            if (this.scrollTop > 0) {
+                this.scrollTop--;
+                consumed = true;
+            }
+        }
+        else if (key.name === 'down') {
+            if (this.scrollTop < maxScroll) {
+                this.scrollTop++;
+                consumed = true;
+            }
+        }
+        else if (key.name === 'pageup') {
+            this.scrollTop = Math.max(0, this.scrollTop - innerHeight);
+            consumed = true;
+        }
+        else if (key.name === 'pagedown') {
+            this.scrollTop = Math.min(maxScroll, this.scrollTop + innerHeight);
+            consumed = true;
+        }
+        if (consumed) {
+            this.render();
+            return true;
+        }
+        return false;
+    }
+    render() {
+        const { x, y, width, height, padding, title, style: borderStyle, borderColor, scrollable } = this.options;
+        const style = BORDERS[borderStyle || 'round'];
+        // Use bright color if focused
+        const color = this.isFocused ? 'brightCyan' : (borderColor || 'white');
+        const startX = x || 1;
+        const startY = y || 1;
+        const pad = padding || 1;
+        const innerWidth = (width || 0) - 2;
+        const innerHeight = (height || 0) - 2;
+        const contentHeight = innerHeight - (pad * 2);
+        // 1. Draw Top Border
+        let topBorder = style.tl + style.h.repeat(innerWidth) + style.tr;
+        if (title) {
+            const titleStr = ` ${title} `;
+            const leftLen = Math.floor((innerWidth - titleStr.length) / 2);
+            const rightLen = innerWidth - leftLen - titleStr.length;
+            if (leftLen >= 0) {
+                topBorder = style.tl + style.h.repeat(leftLen) + Styler_1.Styler.style(titleStr, 'bold') + style.h.repeat(rightLen) + style.tr;
+            }
+        }
+        Screen_1.Screen.write(startX, startY, Styler_1.Styler.style(topBorder, color));
+        // 2. Draw Content Body
+        for (let i = 0; i < innerHeight; i++) {
+            // Check if we are in padding zone or content zone
+            // Padding is applied at top and bottom inside the box?
+            // Usually padding is around content.
+            // Let's assume uniform padding for simplicity in calculation, 
+            // but here we iterate lines.
+            let lineContent = "";
+            if (i >= pad && i < innerHeight - pad) {
+                const contentIndex = (i - pad) + this.scrollTop;
+                if (contentIndex < this.processedLines.length) {
+                    lineContent = this.processedLines[contentIndex];
+                }
+            }
+            const rawLen = Styler_1.Styler.len(lineContent);
+            const contentWidth = innerWidth - (pad * 2);
+            // Ensure we don't overflow horizontally even if wrap failed or wasn't on
+            if (rawLen > contentWidth) {
+                lineContent = Styler_1.Styler.truncate(lineContent, contentWidth);
+            }
+            const remainingSpace = contentWidth - Styler_1.Styler.len(lineContent);
+            const rowString = ' '.repeat(pad) + lineContent + ' '.repeat(Math.max(0, remainingSpace)) + ' '.repeat(pad);
+            // Trim/Pad to exact innerWidth using visual logic if possible, 
+            // but padEnd/substring use string length. 
+            // Since we ensured lineContent visual length is correct and we added spaces (width 1),
+            // we should be careful.
+            // Re-calculate visual length of the constructed row
+            // We want 'rowString' to have visual width exactly 'innerWidth'
+            // If we constructed it correctly: 
+            // pad (len) + lineContent (len) + remaining (len) + pad (len)
+            // = pad + (contentWidth - remaining) + remaining + pad = contentWidth + 2*pad = innerWidth.
+            // So visual width should be correct.
+            // However, padEnd/substring operate on string length.
+            // If lineContent has wide chars, string length < visual width.
+            // 'safeRowString' logic below was:
+            // const safeRowString = rowString.padEnd(innerWidth).substring(0, innerWidth);
+            // This is DANGEROUS because it truncates by string index!
+            // We should trust our construction above.
+            const safeRowString = rowString;
+            let rightBorder = style.v;
+            // Scrollbar logic
+            if (scrollable) {
+                const maxScroll = Math.max(0, this.processedLines.length - contentHeight);
+                if (maxScroll > 0) {
+                    // Calculate scrollbar position
+                    const scrollbarHeight = Math.max(1, Math.floor((contentHeight / this.processedLines.length) * contentHeight));
+                    const scrollPercent = this.scrollTop / maxScroll;
+                    const scrollPos = Math.floor(scrollPercent * (contentHeight - scrollbarHeight));
+                    // Are we in the scrollbar zone? (i is relative to inner box, 0 to innerHeight-1)
+                    // But content area is from pad to innerHeight-pad
+                    if (i >= pad && i < innerHeight - pad) {
+                        const contentRow = i - pad;
+                        if (contentRow >= scrollPos && contentRow < scrollPos + scrollbarHeight) {
+                            rightBorder = '│'; // Active scrollbar part, maybe color it differently
+                            // Actually user suggested using unicode or color change
+                            // Let's make it a colored block or pipe
+                            rightBorder = Styler_1.Styler.style('│', 'brightWhite');
+                        }
+                        else {
+                            rightBorder = Styler_1.Styler.style('│', 'dim'); // Track
+                        }
+                    }
+                }
+            }
+            const row = `${style.v}${safeRowString}${rightBorder}`;
+            Screen_1.Screen.write(startX, startY + 1 + i, Styler_1.Styler.style(row, color));
+        }
+        // 3. Draw Bottom Border
+        Screen_1.Screen.write(startX, startY + (height || 0) - 1, Styler_1.Styler.style(style.bl + style.h.repeat(innerWidth) + style.br, color));
+    }
+    // Static compatibility method
+    static render(content, options = {}) {
+        const box = new Box(content, options);
+        box.render();
+    }
+}
+exports.Box = Box;

package/dist/components/Button.d.ts

@@ -0,0 +1,23 @@
+import { Focusable } from '../core/Focus';
+import * as readline from 'readline';
+interface ButtonOptions {
+    id: string;
+    text: string;
+    x: number;
+    y: number;
+    width?: number;
+    style?: 'simple' | 'brackets';
+    onPress: () => void;
+}
+export declare class Button implements Focusable {
+    id: string;
+    private options;
+    private isFocused;
+    private isPressed;
+    constructor(options: ButtonOptions);
+    focus(): void;
+    blur(): void;
+    handleKey(key: readline.Key): boolean;
+    render(): void;
+}
+export {};

package/dist/components/Button.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Button = void 0;
+const Styler_1 = require("../core/Styler");
+const Screen_1 = require("../core/Screen");
+class Button {
+    constructor(options) {
+        this.isFocused = false;
+        this.isPressed = false; // For visual feedback
+        this.id = options.id;
+        this.options = { style: 'brackets', ...options };
+    }
+    focus() {
+        this.isFocused = true;
+        this.render(); // Ensure render called on focus
+    }
+    blur() {
+        this.isFocused = false;
+        this.isPressed = false;
+        this.render();
+    }
+    handleKey(key) {
+        if (!this.isFocused)
+            return false;
+        if (key.name === 'return' || key.name === 'enter' || key.name === 'space') {
+            this.isPressed = true;
+            this.render(); // Show pressed state visually
+            // Trigger action slightly delayed to show visual feedback
+            setTimeout(() => {
+                this.isPressed = false;
+                this.render();
+                this.options.onPress();
+            }, 150);
+            return true;
+        }
+        return false;
+    }
+    render() {
+        const { x, y, text, width } = this.options;
+        let label = text;
+        // Simple visual centering if width is provided
+        if (width) {
+            const pad = Math.max(0, width - text.length);
+            const padLeft = Math.floor(pad / 2);
+            const padRight = pad - padLeft;
+            label = ' '.repeat(padLeft) + text + ' '.repeat(padRight);
+        }
+        let renderedText = "";
+        let color = 'white';
+        let bgStyle = '';
+        if (this.isFocused) {
+            color = this.isPressed ? 'black' : 'white';
+            bgStyle = this.isPressed ? 'bgGreen' : 'bgBlue'; // Green when clicked, Blue when focused
+            if (this.options.style === 'brackets') {
+                renderedText = `[ ${label} ]`;
+            }
+            else {
+                renderedText = `  ${label}  `;
+            }
+            // Apply styles
+            // Note: Styler.style takes varargs, we need to handle types carefully or cast
+            Screen_1.Screen.write(x, y, Styler_1.Styler.style(renderedText, color, 'bold', bgStyle));
+        }
+        else {
+            // Normal State
+            if (this.options.style === 'brackets') {
+                renderedText = `[ ${label} ]`;
+            }
+            else {
+                renderedText = `  ${label}  `;
+            }
+            Screen_1.Screen.write(x, y, Styler_1.Styler.style(renderedText, 'dim'));
+        }
+    }
+}
+exports.Button = Button;

package/dist/components/Checkbox.d.ts

@@ -0,0 +1,20 @@
+import { Focusable } from '../core/Focus';
+import * as readline from 'readline';
+export interface CheckboxOptions {
+    id: string;
+    label: string;
+    checked?: boolean;
+    x: number;
+    y: number;
+}
+export declare class Checkbox implements Focusable {
+    id: string;
+    checked: boolean;
+    private options;
+    private isFocused;
+    constructor(options: CheckboxOptions);
+    focus(): void;
+    blur(): void;
+    handleKey(key: readline.Key): boolean;
+    render(): void;
+}

package/dist/components/Checkbox.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Checkbox = void 0;
+const Styler_1 = require("../core/Styler");
+const Screen_1 = require("../core/Screen");
+class Checkbox {
+    constructor(options) {
+        this.isFocused = false;
+        this.id = options.id;
+        this.options = options;
+        this.checked = options.checked || false;
+    }
+    focus() {
+        this.isFocused = true;
+        this.render();
+    }
+    blur() {
+        this.isFocused = false;
+        this.render();
+    }
+    handleKey(key) {
+        if (!this.isFocused)
+            return false;
+        if (key.name === 'space' || key.name === 'return' || key.name === 'enter') {
+            this.checked = !this.checked;
+            this.render();
+            return true;
+        }
+        return false;
+    }
+    render() {
+        const { x, y, label } = this.options;
+        const box = this.checked ? '[x]' : '[ ]';
+        const style = this.isFocused ? 'brightCyan' : 'white';
+        const boxStyle = this.checked ? 'green' : 'dim';
+        const content = Styler_1.Styler.style(box, boxStyle) + ' ' + Styler_1.Styler.style(label, style);
+        Screen_1.Screen.write(x, y, content);
+    }
+}
+exports.Checkbox = Checkbox;