voonex 0.1.0 → 0.3.0

package/LICENSE

@@ -1,21 +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.
+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

@@ -1,223 +1,205 @@
-# 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**.
+# 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.
+- **Reactive Signals**: Modern state management inspired by SolidJS. State changes automatically trigger updates.
+- **Component Lifecycle**: Class-based components with `mount`, `unmount`, and lifecycle hooks.
+- **Auto Layout**: Flexbox-like layout engine for responsive designs.
+- **Layer Management**: Z-index support for Modals, Tooltips, and Popups.
+- **Component System**: Built-in widgets like `Box`, `Menu`, `ProgressBar`, `Input`, `Table`, and more.
+- **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 create a reactive counter app.
+
+```typescript
+import { Screen, Component, createSignal, Input } from 'voonex';
+
+// 1. Create a Component
+class CounterApp extends Component {
+    // Define reactive state
+    private count = createSignal(0);
+
+    // Getters/Setters for convenience
+    get value() { return this.count[0](); }
+    set value(v) { this.count[1](v); }
+
+    constructor() {
+        super();
+        
+        // Handle input to increment
+        Input.onKey(key => {
+            if (key.name === 'up') this.value = this.value + 1;
+            if (key.name === 'down') this.value = this.value - 1;
+            if (key.name === 'q') {
+                Screen.leave();
+                process.exit(0);
+            }
+        });
+    }
+
+    // 2. Implement render()
+    // It runs automatically whenever 'this.value' changes!
+    render() {
+        Screen.write(5, 5, `Count: ${this.value}   `);
+        Screen.write(5, 7, "Press Up/Down to change, Q to quit.");
+    }
+}
+
+// 3. Setup Screen
+Screen.enter();
+
+// 4. Mount the App
+const app = new CounterApp();
+app.mount();
+```
+
+Run it with:
+```bash
+npx ts-node my-app.ts
+```
+
+## Core Concepts
+
+### Reactive Signals
+Voonex uses a fine-grained reactivity system. When you update a signal, Voonex automatically schedules a render for the next tick. No manual `render()` calls required.
+
+```typescript
+import { createSignal } from 'voonex';
+
+const [count, setCount] = createSignal(0);
+
+// Reading the value
+console.log(count()); 
+
+// Updating the value (triggers UI update)
+setCount(5);
+setCount(prev => prev + 1);
+```
+
+### Components & Lifecycle
+Components extend the `Component` abstract class.
+
+- `mount(zIndex?)`: Registers the component to the screen loop.
+- `unmount()`: Removes the component.
+- `render()`: The drawing logic.
+
+**Lifecycle Hooks:**
+- `init()`: Called on instantiation.
+- `onMount()`: Called after mounting.
+- `onUnmount()`: Called after unmounting.
+- `destroy()`: Cleanup hook.
+
+### 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.**
+
+#### Layer Management
+Voonex uses a "Painter's Algorithm" with Z-index layers.
+```typescript
+import { Layer } from 'voonex';
+
+// Components handle this automatically via mount()
+myComponent.mount(Layer.MODAL);
+```
+
+### Layout Engine
+The `Layout` class helps calculate coordinates dynamically (Flexbox-style).
+
+```typescript
+import { Layout, Screen } from 'voonex';
+
+const { rects } = Layout.compute(Screen.size, {
+    direction: 'row',
+    children: [
+        { weight: 1 }, // Left sidebar (33%)
+        { weight: 2 }  // Main content (66%)
+    ]
+});
+
+const sidebarRect = rects[0];
+const contentRect = rects[1];
+```
+
+## Built-in Components
+
+### 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'
+});
+```
+
+### Button (Reactive)
+Interactive button that supports focus and press states.
+
+```typescript
+const btn = new Button({
+    id: 'submit',
+    text: "Submit",
+    x: 10, y: 10,
+    onPress: () => submitForm()
+});
+
+btn.mount(); // Don't forget to mount!
+```
+
+### Input Field
+A fully featured text editor with cursor support, scrolling, and editing keys.
+
+```typescript
+const nameInput = new InputField({
+    x: 2, y: 2,
+    width: 20,
+    placeholder: "Enter name..."
+});
+
+Input.onKey(key => {
+    // Navigate focus
+    if (key.name === 'tab') nameInput.focus();
+    
+    // Handle typing (Home, End, Arrows, Backspace supported)
+    nameInput.handleKey(key);
+});
+```
+
+### Popup
+A modal dialog that overlays other content (uses `Layer.MODAL`).
+
+```typescript
+// Shows a message and waits for user to press Enter/Esc
+await Popup.alert("This is an important message!", { title: "Alert" });
+```
+
+
+> Voonex is currently in Beta stage.
+
+
+## License
+
+This project is under the **MIT License**.

package/dist/components/Button.d.ts

@@ -1,3 +1,4 @@
+import { Component } from '../core/Component';
 import { Focusable } from '../core/Focus';
 import * as readline from 'readline';
 interface ButtonOptions {
@@ -9,15 +10,21 @@ interface ButtonOptions {
     style?: 'simple' | 'brackets';
     onPress: () => void;
 }
-export declare class Button implements Focusable {
+export declare class Button extends Component implements Focusable {
     id: string;
+    parent?: Focusable;
     private options;
-    private isFocused;
-    private isPressed;
+    private isFocusedSignal;
+    private isPressedSignal;
+    private get isFocused();
+    private set isFocused(value);
+    private get isPressed();
+    private set isPressed(value);
     constructor(options: ButtonOptions);
     focus(): void;
     blur(): void;
     handleKey(key: readline.Key): boolean;
+    private triggerPress;
     render(): void;
 }
 export {};

package/dist/components/Button.js

@@ -3,40 +3,53 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Button = void 0;
 const Styler_1 = require("../core/Styler");
 const Screen_1 = require("../core/Screen");
-class Button {
+const Component_1 = require("../core/Component");
+const Signal_1 = require("../core/Signal");
+class Button extends Component_1.Component {
+    // Getters/Setters for convenience
+    get isFocused() { return this.isFocusedSignal[0](); }
+    set isFocused(v) { this.isFocusedSignal[1](v); }
+    get isPressed() { return this.isPressedSignal[0](); }
+    set isPressed(v) { this.isPressedSignal[1](v); }
     constructor(options) {
-        this.isFocused = false;
-        this.isPressed = false; // For visual feedback
+        super();
+        // State managed by signals (implicit render on change)
+        this.isFocusedSignal = (0, Signal_1.createSignal)(false);
+        this.isPressedSignal = (0, Signal_1.createSignal)(false);
         this.id = options.id;
         this.options = { style: 'brackets', ...options };
     }
     focus() {
         this.isFocused = true;
-        this.render(); // Ensure render called on focus
+        // No need to call render(), signal handles it
     }
     blur() {
         this.isFocused = false;
         this.isPressed = false;
-        this.render();
+        // No need to call render(), signal handles it
     }
     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);
+            this.triggerPress();
             return true;
         }
         return false;
     }
+    triggerPress() {
+        this.isPressed = true;
+        // render triggered by signal
+        // Trigger action slightly delayed to show visual feedback
+        setTimeout(() => {
+            this.isPressed = false;
+            this.options.onPress();
+        }, 150);
+    }
     render() {
         const { x, y, text, width } = this.options;
+        // Reading signals here (isFocused, isPressed) creates the dependency
+        // although in our simple system, any signal write triggers global render.
         let label = text;
         // Simple visual centering if width is provided
         if (width) {
@@ -58,7 +71,6 @@ class Button {
                 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 {

package/dist/components/Input.d.ts

@@ -14,6 +14,8 @@ export declare class InputField implements Focusable {
     value: string;
     private isFocused;
     private options;
+    private cursorIndex;
+    private scrollOffset;
     constructor(options: InputOptions);
     focus(): void;
     blur(): void;

package/dist/components/Input.js

@@ -7,35 +7,78 @@ class InputField {
     constructor(options) {
         this.value = "";
         this.isFocused = false;
+        // New properties for editing
+        this.cursorIndex = 0;
+        this.scrollOffset = 0;
         this.id = options.id;
         this.options = { width: 30, type: 'text', ...options };
     }
     focus() {
         this.isFocused = true;
+        this.render();
     }
     blur() {
         this.isFocused = false;
+        this.render();
     }
     setValue(val) {
         this.value = val;
+        this.cursorIndex = val.length;
+        this.render();
     }
     handleKey(key) {
         if (!this.isFocused)
             return false;
+        let consumed = false;
         if (key.name === 'backspace') {
-            this.value = this.value.slice(0, -1);
-            this.render();
-            return true;
+            if (this.cursorIndex > 0) {
+                this.value = this.value.slice(0, this.cursorIndex - 1) + this.value.slice(this.cursorIndex);
+                this.cursorIndex--;
+                consumed = true;
+            }
+        }
+        else if (key.name === 'delete') { // Forward delete
+            if (this.cursorIndex < this.value.length) {
+                this.value = this.value.slice(0, this.cursorIndex) + this.value.slice(this.cursorIndex + 1);
+                consumed = true;
+            }
+        }
+        else if (key.name === 'left') {
+            if (this.cursorIndex > 0) {
+                this.cursorIndex--;
+                consumed = true;
+            }
+        }
+        else if (key.name === 'right') {
+            if (this.cursorIndex < this.value.length) {
+                this.cursorIndex++;
+                consumed = true;
+            }
+        }
+        else if (key.name === 'home') {
+            if (this.cursorIndex > 0) {
+                this.cursorIndex = 0;
+                consumed = true;
+            }
+        }
+        else if (key.name === 'end') {
+            if (this.cursorIndex < this.value.length) {
+                this.cursorIndex = this.value.length;
+                consumed = true;
+            }
         }
         else if (key.sequence && key.sequence.length === 1 && !key.ctrl && !key.meta) {
             // Basic text input filtering
-            // Only accept printable characters (rough check)
             if (/^[\x20-\x7E]$/.test(key.sequence)) {
-                this.value += key.sequence;
-                this.render();
-                return true;
+                this.value = this.value.slice(0, this.cursorIndex) + key.sequence + this.value.slice(this.cursorIndex);
+                this.cursorIndex++;
+                consumed = true;
             }
         }
+        if (consumed) {
+            this.render();
+            return true;
+        }
         // Did not consume (e.g., arrow keys, tabs)
         return false;
     }
@@ -51,25 +94,47 @@ class InputField {
         // Draw Input Box Background
         const inputX = x + labelLen;
         const maxWidth = (width || 30) - labelLen;
-        let displayValue = this.value;
+        // Adjust scrollOffset to keep cursor in view
+        if (this.cursorIndex < this.scrollOffset) {
+            this.scrollOffset = this.cursorIndex;
+        }
+        else if (this.cursorIndex >= this.scrollOffset + maxWidth) {
+            this.scrollOffset = this.cursorIndex - maxWidth + 1;
+        }
+        // Clamp scrollOffset
+        if (this.scrollOffset < 0)
+            this.scrollOffset = 0;
+        let displayValue = this.value.substring(this.scrollOffset, this.scrollOffset + maxWidth);
         if (type === 'password') {
-            displayValue = '*'.repeat(this.value.length);
+            displayValue = '*'.repeat(displayValue.length);
         }
-        // Cursor logic
-        const showCursor = this.isFocused;
-        const cursorChar = '█';
-        // Display content calculation
-        // Ensure we don't overflow width
-        if (displayValue.length >= maxWidth - 1) {
-            const start = displayValue.length - (maxWidth - 2);
-            displayValue = displayValue.substring(start);
+        // Prepare content with cursor
+        let renderedContent = "";
+        const cursorRelPos = this.cursorIndex - this.scrollOffset;
+        // Iterate through visible area
+        for (let i = 0; i < maxWidth; i++) {
+            const charIndex = this.scrollOffset + i;
+            let char = "";
+            if (charIndex < this.value.length) {
+                char = type === 'password' ? '*' : this.value[charIndex];
+            }
+            else {
+                char = " ";
+            }
+            if (this.isFocused && i === cursorRelPos) {
+                // Draw cursor
+                renderedContent += Styler_1.Styler.style(char === " " ? " " : char, 'bgGreen', 'black');
+            }
+            else {
+                renderedContent += char;
+            }
         }
-        const fieldContent = displayValue + (showCursor ? Styler_1.Styler.style(cursorChar, 'green') : ' ');
-        // Fill remaining space to clear old chars
-        const paddingLen = Math.max(0, maxWidth - Styler_1.Styler.len(fieldContent));
-        const padding = ' '.repeat(paddingLen);
+        // If cursor is at the very end (past last char), we need to handle it
+        // The loop above goes up to maxWidth.
+        // If cursorRelPos == displayValue.length, it might be drawn?
+        // Actually the loop ensures we draw maxWidth chars.
         const style = this.isFocused ? 'white' : 'gray';
-        Screen_1.Screen.write(inputX, y, Styler_1.Styler.style(fieldContent + padding, style));
+        Screen_1.Screen.write(inputX, y, Styler_1.Styler.style(renderedContent, style));
         // Underline
         const underline = '─'.repeat(maxWidth);
         const underlineColor = this.isFocused ? 'brightGreen' : 'dim';

package/dist/components/Popup.js

@@ -33,8 +33,7 @@ class Popup {
             });
             Screen_1.Screen.write(x + 2, y + boxHeight - 1, Styler_1.Styler.style("[Press Enter]", 'dim'));
         };
-        const POPUP_Z_INDEX = 9999;
-        Screen_1.Screen.mount(renderPopup, POPUP_Z_INDEX);
+        Screen_1.Screen.mount(renderPopup, Screen_1.Layer.MODAL);
         const handler = (key) => {
             if (key.name === 'return' || key.name === 'enter' || key.name === 'escape') {
                 Screen_1.Screen.unmount(renderPopup);

package/dist/core/Component.d.ts

@@ -4,3 +4,37 @@ export interface ComponentLifecycle {
     onMount?(): void;
     onUnmount?(): void;
 }
+export declare abstract class Component implements ComponentLifecycle {
+    private mounted;
+    private boundRender;
+    constructor();
+    /**
+     * Called when the component is instantiated.
+     */
+    init?(): void;
+    /**
+     * Called before the component is destroyed.
+     */
+    destroy?(): void;
+    /**
+     * Called when the component is mounted to the screen.
+     */
+    onMount?(): void;
+    /**
+     * Called when the component is unmounted from the screen.
+     */
+    onUnmount?(): void;
+    /**
+     * The render function that draws the component to the screen.
+     */
+    abstract render(): void;
+    /**
+     * Mounts the component to the Screen rendering loop.
+     * @param zIndex Layer priority (default: Layer.CONTENT)
+     */
+    mount(zIndex?: number): void;
+    /**
+     * Unmounts the component from the Screen rendering loop.
+     */
+    unmount(): void;
+}

package/dist/core/Component.js

@@ -3,3 +3,34 @@
 // CORE: COMPONENT LIFECYCLE
 // ==========================================
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Component = void 0;
+const Screen_1 = require("./Screen");
+class Component {
+    constructor() {
+        this.mounted = false;
+        this.boundRender = this.render.bind(this);
+        this.init?.();
+    }
+    /**
+     * Mounts the component to the Screen rendering loop.
+     * @param zIndex Layer priority (default: Layer.CONTENT)
+     */
+    mount(zIndex = Screen_1.Layer.CONTENT) {
+        if (this.mounted)
+            return;
+        this.mounted = true;
+        Screen_1.Screen.mount(this.boundRender, zIndex);
+        this.onMount?.();
+    }
+    /**
+     * Unmounts the component from the Screen rendering loop.
+     */
+    unmount() {
+        if (!this.mounted)
+            return;
+        this.mounted = false;
+        Screen_1.Screen.unmount(this.boundRender);
+        this.onUnmount?.();
+    }
+}
+exports.Component = Component;

package/dist/core/Layout.d.ts

@@ -1,5 +1,19 @@
 import { Rect } from './Screen';
 export { Rect };
+export interface LayoutOptions {
+    direction: 'row' | 'column';
+    gap?: number;
+    children: LayoutItem[];
+}
+export interface LayoutItem {
+    weight?: number;
+    fixed?: number;
+    id?: string;
+}
+export interface LayoutResult {
+    rects: Rect[];
+    map: Map<string, Rect>;
+}
 export declare class Layout {
     /**
      * Splits a rectangle vertically (into columns).
@@ -15,4 +29,8 @@ export declare class Layout {
      * Creates a padded inner rectangle.
      */
     static pad(rect: Rect, padding: number): Rect;
+    /**
+     * Advanced Layout Calculator (Flexbox-like)
+     */
+    static compute(parent: Rect, options: LayoutOptions): LayoutResult;
 }

package/dist/core/Layout.js

@@ -61,5 +61,58 @@ class Layout {
             height: Math.max(0, rect.height - (padding * 2))
         };
     }
+    /**
+     * Advanced Layout Calculator (Flexbox-like)
+     */
+    static compute(parent, options) {
+        const { direction, gap = 0, children } = options;
+        const count = children.length;
+        if (count === 0)
+            return { rects: [], map: new Map() };
+        const totalGap = gap * (count - 1);
+        const availableSpace = (direction === 'row' ? parent.width : parent.height) - totalGap;
+        // 1. Calculate Fixed Sizes
+        let usedSpace = 0;
+        let totalWeight = 0;
+        children.forEach(child => {
+            if (child.fixed !== undefined) {
+                usedSpace += child.fixed;
+            }
+            else {
+                totalWeight += (child.weight || 1);
+            }
+        });
+        const remainingSpace = Math.max(0, availableSpace - usedSpace);
+        const unitSpace = totalWeight > 0 ? remainingSpace / totalWeight : 0;
+        // 2. Compute Rects
+        const rects = [];
+        const map = new Map();
+        let currentPos = direction === 'row' ? parent.x : parent.y;
+        children.forEach((child, i) => {
+            let size = 0;
+            if (child.fixed !== undefined) {
+                size = child.fixed;
+            }
+            else {
+                size = Math.floor((child.weight || 1) * unitSpace);
+                // Last dynamic item gets rounding dust? 
+                // We should be careful about accumulating errors.
+                // But for now simple floor is okay, maybe we can improve later.
+            }
+            // Adjust for last item to fill gap if we used flooring?
+            // Actually, let's keep it simple.
+            const rect = {
+                x: direction === 'row' ? currentPos : parent.x,
+                y: direction === 'column' ? currentPos : parent.y,
+                width: direction === 'row' ? size : parent.width,
+                height: direction === 'column' ? size : parent.height
+            };
+            rects.push(rect);
+            if (child.id)
+                map.set(child.id, rect);
+            currentPos += size + gap;
+        });
+        return { rects, map };
+    }
 }
 exports.Layout = Layout;

package/dist/core/Screen.d.ts

@@ -4,6 +4,13 @@ export interface Rect {
     width: number;
     height: number;
 }
+export declare const Layer: {
+    BACKGROUND: number;
+    CONTENT: number;
+    MODAL: number;
+    TOOLTIP: number;
+    MAX: number;
+};
 export declare class Screen {
     private static isAlternateBuffer;
     private static resizeTimeout;
@@ -24,6 +31,7 @@ export declare class Screen {
      * Leaves the Alternate Screen Buffer and restores cursor.
      */
     static leave(): void;
+    private static setupSignalHandlers;
     private static resizeBuffers;
     /**
      * Schedules a render flush in the next tick.
@@ -51,7 +59,7 @@ export declare class Screen {
     /**
      * Registers a root component for the rendering loop (Painter's Algorithm).
      * @param renderFn The function that renders the component
-     * @param zIndex Priority (higher draws on top)
+     * @param zIndex Priority (higher draws on top). Use Layer.* constants.
      */
     static mount(renderFn: () => void, zIndex?: number): void;
     /**

package/dist/core/Screen.js

@@ -3,8 +3,17 @@
 // CORE: SCREEN MANAGER (The "Canvas")
 // ==========================================
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Screen = void 0;
+exports.Screen = exports.Layer = void 0;
 const Cursor_1 = require("./Cursor");
+const Input_1 = require("./Input");
+// Z-Index Layers
+exports.Layer = {
+    BACKGROUND: 0,
+    CONTENT: 10,
+    MODAL: 100,
+    TOOLTIP: 1000,
+    MAX: 9999
+};
 class Screen {
     /**
      * Enters the Alternate Screen Buffer (like Vim or Nano).
@@ -21,6 +30,8 @@ class Screen {
             this.resizeBuffers();
             this.scheduleRender();
         });
+        // Setup graceful shutdown signals
+        this.setupSignalHandlers();
     }
     /**
      * Leaves the Alternate Screen Buffer and restores cursor.
@@ -28,11 +39,23 @@ class Screen {
     static leave() {
         if (!this.isAlternateBuffer)
             return;
-        // Removed stopLoop()
+        // Cleanup Input (disable mouse, reset raw mode)
+        Input_1.Input.reset();
         Cursor_1.Cursor.show();
         process.stdout.write('\x1b[?1049l'); // Leave alternate buffer
         this.isAlternateBuffer = false;
     }
+    static setupSignalHandlers() {
+        // Prevent multiple handlers if called multiple times
+        // But for static class, it's fine.
+        const cleanup = () => {
+            Screen.leave();
+            process.exit(0);
+        };
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+        // We can't catch SIGKILL
+    }
     static resizeBuffers() {
         this.width = process.stdout.columns || 80;
         this.height = process.stdout.rows || 24;
@@ -166,9 +189,9 @@ class Screen {
     /**
      * Registers a root component for the rendering loop (Painter's Algorithm).
      * @param renderFn The function that renders the component
-     * @param zIndex Priority (higher draws on top)
+     * @param zIndex Priority (higher draws on top). Use Layer.* constants.
      */
-    static mount(renderFn, zIndex = 0) {
+    static mount(renderFn, zIndex = exports.Layer.CONTENT) {
         this.renderRoots.push({ render: renderFn, zIndex });
         this.renderRoots.sort((a, b) => a.zIndex - b.zIndex);
         this.scheduleRender();
@@ -188,49 +211,18 @@ class Screen {
     static flush() {
         // Painter's Algorithm Phase: Re-run all render functions if any exist
         // This clears the buffer and redraws everything from scratch (logically)
-        // But to keep performance, we might want to just let them draw over currentBuffer?
-        // User asked for: "1. Xóa Buffer ảo. 2. Duyệt qua danh sách...".
-        // If we have registered roots, we should follow this.
         if (this.renderRoots.length > 0) {
-            // We need to clear currentBuffer effectively?
-            // Or maybe just let them overwrite. If transparency is involved, clearing is safer.
-            // But clearing everything is expensive if we just diff later. 
-            // The Diff algorithm handles the "screen update" optimization. 
-            // The "Virtual Buffer" update needs to be correct.
-            // If we have layers, and top layer moves, we need to redraw bottom layer to see what's behind.
-            // So YES, we must clear currentBuffer (or reset it to background state) and redraw all layers.
-            // Reset currentBuffer to empty/clean state WITHOUT affecting previousBuffer (screen state)
+            // Reset currentBuffer to empty/clean state
             for (let y = 0; y < this.height; y++) {
                 for (let x = 0; x < this.width; x++) {
                     this.currentBuffer[y][x] = { char: ' ', style: '' };
                 }
-                // We don't mark dirtyRows here blindly, we mark them if they CHANGE in the diff phase.
-                // Wait, dirtyRows optimization relies on us knowing which rows MIGHT have changed.
-                // If we clear everything, we potentially change everything.
-                // So we should mark all as dirty? 
-                // "Dirty" means "Virtual Buffer Row differs from Previous Buffer Row".
-                // Since we are rebuilding Virtual Buffer, we don't know yet.
-                // We should just run the diff loop on all rows?
-                // Or maybe we can track which rows are touched during render?
             }
-            // Render all layers
+            // Render all layers in sorted order
             for (const root of this.renderRoots) {
                 root.render();
             }
-            // Mark all rows as dirty for the Diff phase to check them?
-            // Since we rebuilt the buffer, any row could be different from previousBuffer.
-            // Optimization: Maybe only rows that were touched? 
-            // But 'write' marks dirtyRows.
-            // So if we clear buffer (resetting chars), we are effectively writing spaces.
-            // If we use 'clear()' method, it marks all dirty.
-            // Let's rely on 'write' marking dirtyRows.
-            // But we just did manual reset loop above.
-            // Let's check:
-            // If we reset manual loop, we are changing 'currentBuffer'.
-            // Previous buffer holds what is on screen.
-            // If we don't mark dirtyRows, flush() skips the row.
-            // If screen has text, and we cleared it to spaces, and didn't mark dirty, screen stays text. Bad.
-            // So yes, we should mark all dirty if we do a full clear-redraw cycle.
+            // Mark all rows as dirty because we rebuilt the buffer from scratch
             this.dirtyRows.fill(true);
         }
         if (!this.currentBuffer.length)
@@ -261,8 +253,6 @@ class Screen {
                         const diff = x - (lastX + 1);
                         if (diff > 0)
                             output += `\x1b[${diff}C`;
-                        // If diff is 0 (next char), we do nothing.
-                        // Actually if x = lastX + 2, diff is 1. We need \x1b[1C.
                     }
                     else {
                         // Absolute Move
@@ -279,23 +269,6 @@ class Screen {
                     while (nextX < this.width) {
                         const nextCell = this.currentBuffer[y][nextX];
                         const nextPrev = this.previousBuffer[y][nextX];
-                        // We only batch if the NEXT cell also NEEDS update AND has SAME style
-                        // Actually, even if next cell DOES NOT need update, 
-                        // if we write over it with same content, it's fine (redundant write but saves cursor move).
-                        // BUT, if we write over it, we might overwrite something valid with something else? 
-                        // No, currentBuffer is truth.
-                        // Strategy: 
-                        // 1. Only batch consecutive CHANGED cells?
-                        // 2. Or batch consecutive cells regardless, as long as style matches, to avoid cursor jumps?
-                        // If we skip a cell (not changed), we have to move cursor.
-                        // Moving cursor costs bytes (e.g. \x1b[C is 3 bytes).
-                        // Writing a char is 1 byte.
-                        // So overwriting valid char is cheaper than skipping 1-2 chars.
-                        // But if we skip 10 chars, move is cheaper.
-                        // Let's stick to simple logic: Only batch if next cell ALSO needs update OR we just overwrite it anyway to jump gap?
-                        // The user asked for "Gộp chuỗi ký tự liên tiếp có cùng style".
-                        // If we strictly follow diff, we only write changed cells.
-                        // So let's look for consecutive CHANGED cells with same style.
                         if (nextCell.char !== nextPrev.char || nextCell.style !== nextPrev.style) {
                             if (nextCell.style === cell.style) {
                                 batch += nextCell.char;
@@ -308,10 +281,6 @@ class Screen {
                             }
                         }
                         else {
-                            // Next cell is not changed.
-                            // Should we continue batching to bridge the gap?
-                            // If gap is small (1-2 chars), yes.
-                            // But that complicates logic. Let's stop batching.
                             break;
                         }
                     }
@@ -326,8 +295,6 @@ class Screen {
             }
         }
         if (output.length > 0) {
-            // Reset style
-            // output += '\x1b[0m'; 
             process.stdout.write(output);
         }
     }

package/dist/core/Signal.d.ts

@@ -0,0 +1,22 @@
+export type Accessor<T> = () => T;
+export type Setter<T> = (value: T | ((prev: T) => T)) => void;
+/**
+ * Creates a reactive signal.
+ * When the value updates, it automatically schedules a screen render.
+ * @param initialValue The initial value of the signal.
+ */
+export declare function createSignal<T>(initialValue: T): [Accessor<T>, Setter<T>];
+/**
+ * Creates a memoized value that caches its result and only re-calculates
+ * when the result of the function changes (polled during access).
+ *
+ * Note: A true dependency graph is out of scope. This implementation
+ * re-runs the function on every access but could store the last result
+ * if we had a way to know if dependencies changed.
+ *
+ * Since we don't track dependencies, we can't safely cache unless we know inputs didn't change.
+ * BUT, often `createMemo` is used to avoid expensive calcs if called multiple times in one render pass.
+ *
+ * For now, this is a simple pass-through.
+ */
+export declare function createMemo<T>(fn: () => T): Accessor<T>;

package/dist/core/Signal.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSignal = createSignal;
+exports.createMemo = createMemo;
+const Screen_1 = require("./Screen");
+/**
+ * Creates a reactive signal.
+ * When the value updates, it automatically schedules a screen render.
+ * @param initialValue The initial value of the signal.
+ */
+function createSignal(initialValue) {
+    let value = initialValue;
+    const read = () => value;
+    const write = (newValue) => {
+        const nextValue = newValue instanceof Function ? newValue(value) : newValue;
+        if (value !== nextValue) {
+            value = nextValue;
+            Screen_1.Screen.scheduleRender();
+        }
+    };
+    return [read, write];
+}
+/**
+ * Creates a memoized value that caches its result and only re-calculates
+ * when the result of the function changes (polled during access).
+ *
+ * Note: A true dependency graph is out of scope. This implementation
+ * re-runs the function on every access but could store the last result
+ * if we had a way to know if dependencies changed.
+ *
+ * Since we don't track dependencies, we can't safely cache unless we know inputs didn't change.
+ * BUT, often `createMemo` is used to avoid expensive calcs if called multiple times in one render pass.
+ *
+ * For now, this is a simple pass-through.
+ */
+function createMemo(fn) {
+    // Without a dependency graph (tracking which signals are read inside fn),
+    // we cannot safely memoize across time because we don't know when to invalidate.
+    // We would need a global "context stack" like SolidJS/React.
+    // For this architectural step, we provide the API surface.
+    return () => fn();
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './core/Layout';
 export * from './core/Focus';
 export * from './core/Events';
 export * from './core/Component';
+export * from './core/Signal';
 export * from './components/Box';
 export * from './components/Menu';
 export * from './components/ProgressBar';

package/dist/index.js

@@ -26,6 +26,7 @@ __exportStar(require("./core/Layout"), exports);
 __exportStar(require("./core/Focus"), exports);
 __exportStar(require("./core/Events"), exports);
 __exportStar(require("./core/Component"), exports);
+__exportStar(require("./core/Signal"), exports);
 __exportStar(require("./components/Box"), exports);
 __exportStar(require("./components/Menu"), exports);
 __exportStar(require("./components/ProgressBar"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voonex",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A zero-dependency Terminal UI Library for Node.js.",
   "license": "MIT",
   "author": "CodeTease",
@@ -17,9 +17,9 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
-    "typescript": "5.9.3",
-    "ts-node": "10.9.2",
-    "@types/node": "20.4.2"
+    "@types/node": "^22",
+    "ts-node": "^10",
+    "typescript": "^5"
   },
   "files": [
     "dist",