voonex 0.2.0 → 0.3.0

package/README.md

@@ -6,10 +6,11 @@
 
 - **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.
-- **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.
@@ -24,41 +25,48 @@ npm install voonex
 
 ## Quick Start
 
-Here is a minimal example showing how to initialize the screen and display a simple box.
+Here is a minimal example showing how to create a reactive counter app.
 
 ```typescript
-import { Screen, Box, Styler, Input } from 'voonex';
-
-// 1. Enter the alternate screen buffer
-Screen.enter();
+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. 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'
-    });
+    // 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. Mount the render function to the screen loop
-Screen.mount(render);
+// 3. Setup Screen
+Screen.enter();
 
-// 4. Handle Input
-Input.onKey((key) => {
-    if (key.name === 'q') {
-        // Leave the screen buffer properly before exiting
-        Screen.leave();
-        process.exit(0);
-    }
-});
+// 4. Mount the App
+const app = new CounterApp();
+app.mount();
 ```
 
 Run it with:
@@ -68,32 +76,48 @@ 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.**
-- `Screen.mount(renderFn, layer?)`: Registers a function to be called during the render cycle.
-- `Screen.scheduleRender()`: Triggers a screen update.
 
 #### Layer Management
 Voonex uses a "Painter's Algorithm" with Z-index layers.
 ```typescript
-import { Screen, Layer } from 'voonex';
+import { Layer } from 'voonex';
 
-Screen.mount(drawBackground, Layer.BACKGROUND); // 0
-Screen.mount(drawContent, Layer.CONTENT);       // 10
-Screen.mount(drawPopup, Layer.MODAL);           // 100
-```
-
-### Input Handling
-Voonex provides global input listeners.
-
-**Keyboard:**
-```typescript
-Input.onKey((key) => {
-    console.log(key.name); 
-});
+// Components handle this automatically via mount()
+myComponent.mount(Layer.MODAL);
 ```
 
 ### Layout Engine
@@ -114,7 +138,7 @@ const sidebarRect = rects[0];
 const contentRect = rects[1];
 ```
 
-## Components
+## Built-in Components
 
 ### Box
 A container for text with optional borders, padding, and titles.
@@ -131,8 +155,8 @@ Box.render([
 });
 ```
 
-### Button
-Interactive button that supports Enter.
+### Button (Reactive)
+Interactive button that supports focus and press states.
 
 ```typescript
 const btn = new Button({
@@ -141,6 +165,8 @@ const btn = new Button({
     x: 10, y: 10,
     onPress: () => submitForm()
 });
+
+btn.mount(); // Don't forget to mount!
 ```
 
 ### Input Field
@@ -170,6 +196,10 @@ A modal dialog that overlays other content (uses `Layer.MODAL`).
 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,11 +10,16 @@ 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;

package/dist/components/Button.js

@@ -3,21 +3,30 @@ 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)
@@ -30,16 +39,17 @@ class Button {
     }
     triggerPress() {
         this.isPressed = true;
-        this.render(); // Show pressed state visually
+        // render triggered by signal
         // Trigger action slightly delayed to show visual feedback
         setTimeout(() => {
             this.isPressed = false;
-            this.render();
             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) {
@@ -61,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/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/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.2.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": {
-    "@types/node": "^20.4.2",
-    "ts-node": "10.9.2",
-    "typescript": "5.9.3"
+    "@types/node": "^22",
+    "ts-node": "^10",
+    "typescript": "^5"
   },
   "files": [
     "dist",