buffalo-tui 1.0.0

package/README.md

@@ -0,0 +1,196 @@
+# Buffalo TUI Framework
+A beginner friendly TUI framework available on various package managers for Node.js projects.
+
+## Features
+1. **Floating Windows** are movable, overlapping windows with ZIndex support.
+2. **RGB Color Support** allows for full 24-bit RGB coloring with ANSI escape sequences.
+3. **Input Handling** gives native keyboard event handling.
+4. **Interactive Elements** such as input fields, buttons, and labels with support for keyboard navigation.
+5. **Control Bar** allows you to write a useful status bar with nice keyboard shortcuts.
+6. **Efficient Rendering** uses a buffer-based rendering system for seamless render updates.
+
+## Install Buffalo 
+Buffalo is available for anyone on the [NPM]() marketplace.
+
+> [!NOTE]
+> As of **Tuesday, February 10th, 2026**, Buffalo does not support TypeScript type declarations!
+
+Install Buffalo using the Node Package Manager:
+```bash
+npm install buffalo
+```
+
+## Getting Started
+Writing your first TUI with Buffalo is extremely easy and can be done using the code below:
+```javascript
+import { Screen, Frame, ColorManager, InputManager } from "buffalo";
+
+const screen = new Screen();
+const inputManager = new InputManager();
+
+screen.enterFullscreen();
+
+// (sizeX, sizeY, posX, posY, windowTitle, color)
+const frame = new Frame(
+    50, 20,
+    5, 2,
+    "My Buffalo Program",
+    new ColorManager().setColor(100, 150, 255)
+);
+
+frame.setBackgroundColor(15, 15, 25);
+frame.addContent(2, 2, "Hello, Buffalo!", new ColorManager().setColor(255, 255, 100));
+
+screen.addElement(frame);
+screen.setControlBar("Press Q to quit");
+
+inputManager.onAny((keyName) => {
+    if (keyName === "q" || keyName === "Q") {
+        inputManager.stop();
+        screen.exitFullscreen();
+        process.exit(0);
+    }
+});
+
+inputManager.start();
+screen.render();
+```
+
+## Learn Buffalo through API Documentation
+
+### Screen
+Main class for managing the terminal display.
+```javascript
+const screen = new Screen();
+```
+
+**Properties:**
+- `width` - Terminal width in characters
+- `height` - Terminal height in characters
+- `elements` - Array of elements to render
+
+**Methods:**
+- `enterFullscreen()` - Enter fullscreen mode
+- `exitFullscreen()` - Exit fullscreen mode
+- `render()` - Render all elements to terminal
+- `addElement(element)` - Add an element to the screen
+- `removeElement(element)` - Remove an element
+- `setControlBar(text)` - Set control bar text
+- `writeAt(x, y, char, color)` - Write a single character
+- `writeString(x, y, str, color)` - Write a string
+- `drawRect(x, y, width, height, filled, char, color)` - Draw a rectangle
+- `drawLine(x1, y1, x2, y2, char, color)` - Draw a line
+- `getUsableHeight()` - Get height minus control bar
+
+### Frame
+
+Floating window element with border, title, and content.
+
+**Constructor:**
+```javascript
+new Frame(sizeX, sizeY, posX, posY, windowTitle, borderColor)
+```
+
+**Parameters:**
+- `sizeX` - Width of the frame
+- `sizeY` - Height of the frame
+- `posX` - X position on screen
+- `posY` - Y position on screen
+- `windowTitle` - Title displayed on top border
+- `borderColor` - ColorManager instance for border
+
+**Methods:**
+- `setWindowTitle(title)` - Update window title
+- `setBorderColor(R, G, B)` - Set border color (0-255 RGB)
+- `setBackgroundColor(R, G, B)` - Set background color
+- `addContent(x, y, text, color)` - Add text content at position
+- `clearContent()` - Remove all content
+- `show()` - Make frame visible
+- `hide()` - Make frame invisible
+- `setZIndex(z)` - Set layering order (higher = front)
+
+### Input
+
+Text input field element.
+
+**Constructor:**
+```javascript
+new Input(posX, posY, width, label, color)
+```
+
+**Parameters:**
+- `posX` - X position on screen
+- `posY` - Y position on screen
+- `width` - Width of input field
+- `label` - Label text above input
+- `color` - ColorManager instance (optional)
+
+**Methods:**
+- `setValue(value)` - Set input value
+- `getValue()` - Get current value
+- `setFocus(focused)` - Set focus state
+- `show()` / `hide()` - Visibility control
+
+### Button
+
+Clickable button element.
+
+**Constructor:**
+```javascript
+new Button(posX, posY, text, color)
+```
+
+**Parameters:**
+- `posX` - X position on screen
+- `posY` - Y position on screen
+- `text` - Button text
+- `color` - ColorManager instance (optional)
+
+**Methods:**
+- `setText(text)` - Update button text
+- `setHovered(hovered)` - Set hover state
+- `show()` / `hide()` - Visibility control
+
+### Label
+
+Static text label element.
+
+**Constructor:**
+```javascript
+new Label(posX, posY, text, color)
+```
+
+**Parameters:**
+- `posX` - X position on screen
+- `posY` - Y position on screen
+- `text` - Label text
+- `color` - ColorManager instance (optional)
+
+**Methods:**
+- `setText(text)` - Update label text
+- `setColor(R, G, B)` - Set text color
+- `show()` / `hide()` - Visibility control
+
+### ColorManager
+
+RGB color management with ANSI conversion.
+
+**Methods:**
+- `setColor(R, G, B)` - Set RGB color (0-255 each)
+- `getColor()` - Returns `{R, G, B}` object
+- `toANSIForeground()` - Convert to ANSI foreground code
+- `toANSIBackground()` - Convert to ANSI background code
+- `static reset()` - Get ANSI reset code
+
+### InputManager
+
+Keyboard input handling.
+
+**Methods:**
+- `start()` - Start capturing keyboard input
+- `stop()` - Stop capturing input
+- `onAny(callback)` - Register callback for any key: `(keyName, rawKey) => {}`
+
+**Key Events:**
+- `keyName` - Human-readable key name
+- `rawKey` - Raw escape sequence

package/USAGE.md

@@ -0,0 +1,151 @@
+# Buffalo - Usage Examples
+
+## Basic Setup
+
+```javascript
+import { Screen, Frame, ColorManager } from 'buffalo';
+
+const screen = new Screen();
+screen.enterFullscreen();
+```
+
+## Creating a Simple Window
+
+```javascript
+const myFrame = new Frame(
+    50,    // width
+    15,    // height
+    10,    // x position
+    5,     // y position
+    'My Window',  // title
+    new ColorManager().setColor(100, 150, 255)  // border color (RGB)
+);
+
+// Add the frame to the screen
+screen.addElement(myFrame);
+```
+
+## Adding Content to Frames
+
+```javascript
+// Add text at position (x, y) relative to frame interior
+myFrame.addContent(1, 1, 'Hello, World!', new ColorManager().setColor(255, 255, 0));
+myFrame.addContent(1, 3, 'Another line', new ColorManager().setColor(200, 200, 200));
+
+// Set background color
+myFrame.setBackgroundColor(20, 20, 40);
+```
+
+## Control Bar
+
+```javascript
+// Set text in the bottom control bar
+screen.setControlBar('Press Q to quit  |  Press H for help');
+```
+
+## Rendering
+
+```javascript
+// Render once
+screen.render();
+
+// Or set up an animation loop
+setInterval(() => {
+    // Update content
+    myFrame.clearContent();
+    myFrame.addContent(1, 1, `Time: ${Date.now()}`);
+    
+    // Render
+    screen.render();
+}, 100);
+```
+
+## Drawing Primitives
+
+```javascript
+// Draw a rectangle (can be filled or outlined)
+screen.drawRect(10, 10, 20, 10, false, '█', new ColorManager().setColor(255, 0, 0));
+
+// Draw a line
+screen.drawLine(5, 5, 30, 5, '─', new ColorManager().setColor(0, 255, 0));
+
+// Write text directly to buffer
+screen.writeString(15, 15, 'Direct text!', new ColorManager().setColor(255, 255, 255));
+```
+
+## Color Management
+
+```javascript
+// Create colors
+const red = new ColorManager().setColor(255, 0, 0);
+const green = new ColorManager().setColor(0, 255, 0);
+const blue = new ColorManager().setColor(0, 0, 255);
+
+// Get RGB values
+const rgb = red.getColor();  // { R: 255, G: 0, B: 0 }
+
+// Colors are automatically converted to ANSI codes for terminal display
+```
+
+## Keyboard Input
+
+```javascript
+import * as readline from 'readline';
+
+readline.emitKeypressEvents(process.stdin);
+if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+}
+
+process.stdin.on('keypress', (str, key) => {
+    if (key.name === 'q') {
+        screen.cleanup();
+        process.exit(0);
+    }
+    
+    if (key.name === 'up') {
+        // Handle up arrow
+    }
+});
+```
+
+## Multiple Overlapping Frames
+
+```javascript
+const frame1 = new Frame(40, 10, 5, 5, 'Frame 1', new ColorManager().setColor(255, 100, 100));
+frame1.zIndex = 0;
+
+const frame2 = new Frame(40, 10, 15, 8, 'Frame 2', new ColorManager().setColor(100, 255, 100));
+frame2.zIndex = 1;  // Will render on top
+
+screen.addElement(frame1);
+screen.addElement(frame2);
+```
+
+## Cleanup
+
+```javascript
+function cleanup() {
+    screen.cleanup();  // Restores terminal to normal mode
+    process.stdin.setRawMode(false);
+    process.exit(0);
+}
+
+// Handle process termination
+process.on('SIGINT', cleanup);
+process.on('SIGTERM', cleanup);
+```
+
+## Complete Example
+
+See `example.js` for a simple working example.
+See `demo.js` for a comprehensive demo with multiple features.
+
+## Tips
+
+- Always call `screen.enterFullscreen()` before rendering
+- Always call `screen.cleanup()` before exiting
+- Use `setInterval()` for animations and live updates
+- The control bar takes up the bottom 3 lines
+- Use `getUsableHeight()` to get drawing area excluding control bar
+- Colors are clamped to 0-255 range automatically

package/classes/colorManager.js

@@ -0,0 +1,44 @@
+// only supports RGB values because it's the only kind of
+// color codes I have memorized
+export class ColorManager {
+  constructor() {
+    this.R = 255;
+    this.G = 255;
+    this.B = 255;
+  }
+
+  setColor(R, G, B) {
+    this.R = Math.max(0, Math.min(255, R));
+    this.G = Math.max(0, Math.min(255, G));
+    this.B = Math.max(0, Math.min(255, B));
+    return this;
+  }
+
+  getColor() {
+    return { R: this.R, G: this.G, B: this.B };
+  }
+
+  toANSIForeground() {
+    return `\x1b[38;2;${this.R};${this.G};${this.B}m`;
+  }
+
+  toANSIBackground() {
+    return `\x1b[48;2;${this.R};${this.G};${this.B}m`;
+  }
+  toANSI256() {
+    if (this.R === this.G && this.G === this.B) {
+      if (this.R < 8) return 16;
+      if (this.R > 248) return 231;
+      return Math.round(((this.R - 8) / 247) * 24) + 232;
+    }
+
+    const r = Math.round((this.R / 255) * 5);
+    const g = Math.round((this.G / 255) * 5);
+    const b = Math.round((this.B / 255) * 5);
+    return 16 + 36 * r + 6 * g + b;
+  }
+
+  static reset() {
+    return "\x1b[0m";
+  }
+}

package/classes/element.js

@@ -0,0 +1,31 @@
+export const properties = {
+    // hardcoded element list with what properties each has because I was too lazy
+    // to automize it lol
+    frame: {
+        sizeX: 'number',
+        sizeY: 'number',
+        posX: 'number',
+        posY: 'number',
+        windowTitle: 'string',
+        borderColor: 'ColorManager',
+    }
+}
+
+export class Element {
+    constructor() {
+        this.visible = true;
+        this.zIndex = 0;
+    }
+
+    show() {
+        this.visible = true;
+    }
+
+    hide() {
+        this.visible = false;
+    }
+
+    setZIndex(z) {
+        this.zIndex = z;
+    }
+}

package/classes/inputManager.js

@@ -0,0 +1,155 @@
+export class InputManager {
+    constructor() {
+        this.listeners = {};
+        this.focusedElement = null;
+        this.isListening = false;
+        this.keyBuffer = '';
+        this.inputHandlers = [];
+        this.specialKeys = {
+            'up': '\u001b[A',
+            'down': '\u001b[B',
+            'right': '\u001b[C',
+            'left': '\u001b[D',
+            'enter': '\r',
+            'escape': '\u001b',
+            'backspace': '\x7f',
+            'tab': '\t'
+        };
+    }
+
+    start() {
+        if (this.isListening) return;
+
+        this.isListening = true;
+        this.setupStdin();
+    }
+
+    stop() {
+        this.isListening = false;
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(false);
+        }
+        process.stdin.removeAllListeners('data');
+    }
+
+    setupStdin() {
+        if (!process.stdin.isTTY) {
+            console.warn('Warning: InputManager requires TTY mode');
+            return;
+        }
+
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding('utf8');
+
+        process.stdin.on('data', (key) => {
+            this.handleKeyPress(key);
+        });
+    }
+
+    handleKeyPress(key) {
+        if (key === '\u0003') {
+            this.stop();
+            process.exit(0);
+        }
+
+        this.keyBuffer = key;
+        const keyName = this.identifyKey(key);
+
+        if (this.listeners['any']) {
+            this.listeners['any'].forEach(callback => callback(keyName, key));
+        }
+
+        if (this.listeners[keyName]) {
+            this.listeners[keyName].forEach(callback => callback(key));
+        }
+
+        if (this.focusedElement && this.focusedElement.handleInput) {
+            this.focusedElement.handleInput(keyName, key);
+        }
+
+        this.inputHandlers.forEach(handler => {
+            if (handler.predicate ? handler.predicate(keyName) : true) {
+                handler.callback(keyName, key);
+            }
+        });
+    }
+
+    identifyKey(key) {
+        for (let name in this.specialKeys) {
+            if (this.specialKeys[name] === key) {
+                return name;
+            }
+        }
+
+        if (key.length === 1) {
+            return key;
+        }
+
+        return `unknown_${key.charCodeAt(0)}`;
+    }
+
+    on(keyName, callback) {
+        if (!this.listeners[keyName]) {
+            this.listeners[keyName] = [];
+        }
+        this.listeners[keyName].push(callback);
+        return this;
+    }
+
+    onAny(callback) {
+        return this.on('any', callback);
+    }
+
+    off(keyName, callback) {
+        if (this.listeners[keyName]) {
+            this.listeners[keyName] = this.listeners[keyName].filter(cb => cb !== callback);
+        }
+        return this;
+    }
+
+    addHandler(callback, predicate = null) {
+        this.inputHandlers.push({ callback, predicate });
+        return this;
+    }
+
+    removeHandler(callback) {
+        this.inputHandlers = this.inputHandlers.filter(h => h.callback !== callback);
+        return this;
+    }
+
+    setFocus(element) {
+        if (this.focusedElement && this.focusedElement.onBlur) {
+            this.focusedElement.onBlur();
+        }
+
+        this.focusedElement = element;
+
+        if (element && element.onFocus) {
+            element.onFocus();
+        }
+
+        return this;
+    }
+
+    getFocus() {
+        return this.focusedElement;
+    }
+
+    clearListeners(keyName = 'all') {
+        if (keyName === 'all') {
+            this.listeners = {};
+        } else {
+            delete this.listeners[keyName];
+        }
+        return this;
+    }
+
+    getLastKey() {
+        return this.keyBuffer;
+    }
+
+    isActive() {
+        return this.isListening;
+    }
+}

package/classes/screen.js

@@ -0,0 +1,206 @@
+import { ColorManager } from './colorManager.js';
+
+export class Screen {
+    constructor() {
+        this.width = process.stdout.columns || 80;
+        this.height = process.stdout.rows || 24;
+        this.buffer = [];
+        this.colorBuffer = [];
+        this.elements = [];
+        this.controlBarHeight = 3;
+        this.controlBarText = '';
+        
+        this.clearBuffer();
+        
+        process.stdout.on('resize', () => {
+            this.width = process.stdout.columns;
+            this.height = process.stdout.rows;
+            this.clearBuffer();
+            this.render();
+        });
+    }
+
+    clearBuffer() {
+        this.buffer = [];
+        this.colorBuffer = [];
+        
+        for (let y = 0; y < this.height; y++) {
+            this.buffer[y] = [];
+            this.colorBuffer[y] = [];
+            for (let x = 0; x < this.width; x++) {
+                this.buffer[y][x] = ' ';
+                this.colorBuffer[y][x] = null;
+            }
+        }
+    }
+
+    clear() {
+        this.clearBuffer();
+    }
+
+    writeAt(x, y, char, color = null) {
+        if (x >= 0 && x < this.width && y >= 0 && y < this.height) {
+            this.buffer[y][x] = char || ' ';
+            this.colorBuffer[y][x] = color;
+        }
+    }
+
+    writeString(x, y, str, color = null) {
+        for (let i = 0; i < str.length; i++) {
+            this.writeAt(x + i, y, str[i], color);
+        }
+    }
+
+    drawRect(x, y, width, height, filled = false, char = '█', borderColor = null) {
+        if (filled) {
+            for (let dy = 0; dy < height; dy++) {
+                for (let dx = 0; dx < width; dx++) {
+                    this.writeAt(x + dx, y + dy, char, borderColor);
+                }
+            }
+        } else {
+            for (let dx = 0; dx < width; dx++) {
+                this.writeAt(x + dx, y, '─', borderColor);
+                this.writeAt(x + dx, y + height - 1, '─', borderColor);
+            }
+            
+            for (let dy = 0; dy < height; dy++) {
+                this.writeAt(x, y + dy, '│', borderColor);
+                this.writeAt(x + width - 1, y + dy, '│', borderColor);
+            }
+            
+            this.writeAt(x, y, '┌', borderColor);
+            this.writeAt(x + width - 1, y, '┐', borderColor);
+            this.writeAt(x, y + height - 1, '└', borderColor);
+            this.writeAt(x + width - 1, y + height - 1, '┘', borderColor);
+        }
+    }
+
+    drawLine(x1, y1, x2, y2, char = '─', color = null) {
+        const dx = Math.abs(x2 - x1);
+        const dy = Math.abs(y2 - y1);
+        const sx = x1 < x2 ? 1 : -1;
+        const sy = y1 < y2 ? 1 : -1;
+        let err = dx - dy;
+
+        let x = x1;
+        let y = y1;
+
+        while (true) {
+            this.writeAt(x, y, char, color);
+            
+            if (x === x2 && y === y2) break;
+            
+            const e2 = 2 * err;
+            if (e2 > -dy) {
+                err -= dy;
+                x += sx;
+            }
+            if (e2 < dx) {
+                err += dx;
+                y += sy;
+            }
+        }
+    }
+
+    addElement(element) {
+        this.elements.push(element);
+        this.elements.sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0));
+    }
+
+    removeElement(element) {
+        const index = this.elements.indexOf(element);
+        if (index > -1) {
+            this.elements.splice(index, 1);
+        }
+    }
+
+    setControlBar(text) {
+        this.controlBarText = text;
+    }
+
+    drawControlBar() {
+        const barY = this.height - this.controlBarHeight;
+        const barColor = new ColorManager().setColor(200, 200, 200);
+        const bgColor = new ColorManager().setColor(40, 40, 40);
+        
+        for (let x = 0; x < this.width; x++) {
+            this.writeAt(x, barY, '═', barColor);
+        }
+        
+        for (let y = barY + 1; y < this.height; y++) {
+            for (let x = 0; x < this.width; x++) {
+                this.writeAt(x, y, ' ', bgColor);
+            }
+        }
+        
+        if (this.controlBarText) {
+            this.writeString(2, barY + 1, this.controlBarText, new ColorManager().setColor(255, 255, 255));
+        }
+    }
+
+    renderElements() {
+        for (const element of this.elements) {
+            if (element.visible !== false && typeof element.drawToBuffer === 'function') {
+                element.drawToBuffer(this);
+            }
+        }
+    }
+
+    render() {
+        this.clearBuffer();
+        this.renderElements();
+        this.drawControlBar();
+        
+        process.stdout.write('\x1b[H\x1b[?25l');
+        
+        let output = '';
+        let lastColor = null;
+        
+        for (let y = 0; y < this.height; y++) {
+            for (let x = 0; x < this.width; x++) {
+                const char = this.buffer[y][x];
+                const color = this.colorBuffer[y][x];
+                
+                if (color && color !== lastColor) {
+                    output += color.toANSIForeground();
+                    lastColor = color;
+                } else if (!color && lastColor) {
+                    output += ColorManager.reset();
+                    lastColor = null;
+                }
+                
+                output += char;
+            }
+            
+            if (y < this.height - 1) {
+                output += '\n';
+            }
+        }
+        
+        if (lastColor) {
+            output += ColorManager.reset();
+        }
+        
+        process.stdout.write(output);
+    }
+
+    enterFullscreen() {
+        process.stdout.write('\x1b[?1049h');
+        process.stdout.write('\x1b[2J');
+        process.stdout.write('\x1b[?25l');
+    }
+
+    exitFullscreen() {
+        process.stdout.write('\x1b[?25h');
+        process.stdout.write('\x1b[?1049l');
+    }
+
+    getUsableHeight() {
+        return this.height - this.controlBarHeight;
+    }
+
+    cleanup() {
+        this.exitFullscreen();
+    }
+}

package/elements/button.js

@@ -0,0 +1,31 @@
+import { Element } from "../classes/element.js";
+import { ColorManager } from "../classes/colorManager.js";
+
+export class Button extends Element {
+    constructor(posX, posY, text, color = null) {
+        super();
+        this.posX = posX;
+        this.posY = posY;
+        this.text = text;
+        this.color = color || new ColorManager().setColor(255, 255, 255);
+        this.hovered = false;
+    }
+
+    setText(text) {
+        this.text = text;
+    }
+
+    setHovered(hovered) {
+        this.hovered = hovered;
+    }
+
+    drawToBuffer(screen) {
+        if (!this.visible) return;
+        
+        const buttonColor = this.hovered 
+            ? new ColorManager().setColor(100, 255, 100)
+            : this.color;
+        
+        screen.writeString(this.posX, this.posY, `[ ${this.text} ]`, buttonColor);
+    }
+}

package/elements/frame.js

@@ -0,0 +1,70 @@
+import { properties, Element } from "../classes/element.js";
+import { ColorManager } from "../classes/colorManager.js";
+
+export class Frame extends Element {
+    sizeX = 0;
+    sizeY = 0;
+    posX = 0;
+    posY = 0;
+    windowTitle = "";
+    borderColor = new ColorManager().setColor(255, 255, 255);
+    backgroundColor = null;
+    content = [];
+    visible = true;
+    zIndex = 0;
+
+    constructor(sizeX, sizeY, posX, posY, windowTitle, borderColor) {
+        super();
+        this.sizeX = sizeX;
+        this.sizeY = sizeY;
+        this.posX = posX;
+        this.posY = posY;
+        this.windowTitle = windowTitle || "";
+        this.borderColor = borderColor || new ColorManager().setColor(255, 255, 255);
+    }
+
+    setWindowTitle(title) {
+        this.windowTitle = title;
+    }
+
+    setBorderColor(R, G, B) {
+        this.borderColor = new ColorManager().setColor(R, G, B);
+    }
+
+    setBackgroundColor(R, G, B) {
+        this.backgroundColor = new ColorManager().setColor(R, G, B);
+    }
+
+    addContent(x, y, text, color = null) {
+        this.content.push({ x, y, text, color });
+    }
+
+    clearContent() {
+        this.content = [];
+    }
+
+    drawToBuffer(screen) {
+        if (!this.visible) return;
+        if (this.backgroundColor) {
+            for (let y = 1; y < this.sizeY - 1; y++) {
+                for (let x = 1; x < this.sizeX - 1; x++) {
+                    screen.writeAt(this.posX + x, this.posY + y, ' ', this.backgroundColor);
+                }
+            }
+        }
+
+        screen.drawRect(this.posX, this.posY, this.sizeX, this.sizeY, false, '█', this.borderColor);
+
+        if (this.windowTitle && this.sizeX > 4) {
+            const titleText = ` ${this.windowTitle} `;
+            const titleX = this.posX + Math.floor((this.sizeX - titleText.length) / 2);
+            screen.writeString(titleX, this.posY, titleText, this.borderColor);
+        }
+
+        for (const item of this.content) {
+            const contentX = this.posX + item.x + 1;
+            const contentY = this.posY + item.y + 1;
+            screen.writeString(contentX, contentY, item.text, item.color);
+        }
+    }
+}

package/elements/input.js

@@ -0,0 +1,43 @@
+import { Element } from "../classes/element.js";
+import { ColorManager } from "../classes/colorManager.js";
+
+export class Input extends Element {
+    constructor(posX, posY, width, label, color = null) {
+        super();
+        this.posX = posX;
+        this.posY = posY;
+        this.width = width;
+        this.label = label;
+        this.value = "";
+        this.color = color || new ColorManager().setColor(255, 255, 255);
+        this.focused = false;
+    }
+
+    setValue(value) {
+        this.value = value;
+    }
+
+    getValue() {
+        return this.value;
+    }
+
+    setFocus(focused) {
+        this.focused = focused;
+    }
+
+    drawToBuffer(screen) {
+        if (!this.visible) return;
+        
+        if (this.label) {
+            screen.writeString(this.posX, this.posY, this.label, this.color);
+        }
+
+        const inputY = this.label ? this.posY + 1 : this.posY;
+        const display = this.value.padEnd(this.width, ' ').substring(0, this.width);
+        const inputColor = this.focused 
+            ? new ColorManager().setColor(100, 200, 255)
+            : new ColorManager().setColor(150, 150, 150);
+        
+        screen.writeString(this.posX, inputY, `[${display}]`, inputColor);
+    }
+}

package/elements/label.js

@@ -0,0 +1,25 @@
+import { Element } from "../classes/element.js";
+import { ColorManager } from "../classes/colorManager.js";
+
+export class Label extends Element {
+    constructor(posX, posY, text, color = null) {
+        super();
+        this.posX = posX;
+        this.posY = posY;
+        this.text = text;
+        this.color = color || new ColorManager().setColor(255, 255, 255);
+    }
+
+    setText(text) {
+        this.text = text;
+    }
+
+    setColor(R, G, B) {
+        this.color = new ColorManager().setColor(R, G, B);
+    }
+
+    drawToBuffer(screen) {
+        if (!this.visible) return;
+        screen.writeString(this.posX, this.posY, this.text, this.color);
+    }
+}

package/examples/demo.js

@@ -0,0 +1,413 @@
+import {
+  Screen,
+  Frame,
+  ColorManager,
+  InputManager,
+} from "../index.js";
+import os from "os";
+
+const screen = new Screen();
+const inputManager = new InputManager();
+
+screen.enterFullscreen();
+
+let counter = 0;
+let selectedElement = 0;
+let inputValue = "";
+let buttonPressed = false;
+let hideOtherWindows = false;
+
+const sampleElements = [
+  { type: "input", name: "Text Input" },
+  { type: "button", name: "Submit Button" },
+  { type: "button", name: "Increment Counter" },
+];
+
+const windows = [
+  {
+    frame: new Frame(
+      50,
+      20,
+      5,
+      2,
+      "System Performance",
+      new ColorManager().setColor(100, 200, 255),
+    ),
+    update: updateSystemPerformance,
+  },
+  {
+    frame: new Frame(
+      55,
+      25,
+      15,
+      5,
+      "Sample Features",
+      new ColorManager().setColor(100, 255, 150),
+    ),
+    update: updateSampleFeatures,
+  },
+];
+
+windows.forEach((win) => {
+  win.frame.setBackgroundColor(15, 15, 25);
+  screen.addElement(win.frame);
+});
+
+let activeWindowIndex = 0;
+
+function getCPUUsage() {
+  const cpus = os.cpus();
+  let totalIdle = 0;
+  let totalTick = 0;
+
+  cpus.forEach((cpu) => {
+    for (let type in cpu.times) {
+      totalTick += cpu.times[type];
+    }
+    totalIdle += cpu.times.idle;
+  });
+
+  const idle = totalIdle / cpus.length;
+  const total = totalTick / cpus.length;
+  const usage = 100 - ~~((100 * idle) / total);
+  return usage;
+}
+
+function updateSystemPerformance(frame) {
+  frame.clearContent();
+
+  const totalMem = os.totalmem();
+  const freeMem = os.freemem();
+  const usedMem = totalMem - freeMem;
+  const memPercent = ((usedMem / totalMem) * 100).toFixed(1);
+
+  const cpuUsage = getCPUUsage();
+  const uptime = os.uptime();
+  const days = Math.floor(uptime / 86400);
+  const hours = Math.floor((uptime % 86400) / 3600);
+  const minutes = Math.floor((uptime % 3600) / 60);
+
+  const loadAvg = os.loadavg();
+
+  frame.addContent(
+    2,
+    2,
+    `CPU Usage: ${cpuUsage}%`,
+    new ColorManager().setColor(100, 255, 100),
+  );
+  frame.addContent(
+    2,
+    3,
+    `Memory: ${memPercent}% (${(usedMem / 1024 / 1024 / 1024).toFixed(2)} GB / ${(totalMem / 1024 / 1024 / 1024).toFixed(2)} GB)`,
+    new ColorManager().setColor(150, 200, 255),
+  );
+  frame.addContent(
+    2,
+    5,
+    `Platform: ${os.platform()} ${os.arch()}`,
+    new ColorManager().setColor(200, 200, 200),
+  );
+  frame.addContent(
+    2,
+    6,
+    `Hostname: ${os.hostname()}`,
+    new ColorManager().setColor(200, 200, 200),
+  );
+  frame.addContent(
+    2,
+    7,
+    `Uptime: ${days}d ${hours}h ${minutes}m`,
+    new ColorManager().setColor(200, 200, 200),
+  );
+  frame.addContent(
+    2,
+    9,
+    `Load Average:`,
+    new ColorManager().setColor(180, 180, 180),
+  );
+  frame.addContent(
+    2,
+    10,
+    `  1m: ${loadAvg[0].toFixed(2)}`,
+    new ColorManager().setColor(160, 160, 160),
+  );
+  frame.addContent(
+    2,
+    11,
+    `  5m: ${loadAvg[1].toFixed(2)}`,
+    new ColorManager().setColor(160, 160, 160),
+  );
+  frame.addContent(
+    2,
+    12,
+    ` 15m: ${loadAvg[2].toFixed(2)}`,
+    new ColorManager().setColor(160, 160, 160),
+  );
+
+  frame.addContent(
+    2,
+    14,
+    `CPUs: ${os.cpus().length} cores`,
+    new ColorManager().setColor(200, 200, 200),
+  );
+  frame.addContent(
+    2,
+    15,
+    `Arch: ${os.cpus()[0].model.substring(0, 35)}`,
+    new ColorManager().setColor(180, 180, 180),
+  );
+}
+
+function updateSampleFeatures(frame) {
+  frame.clearContent();
+
+  frame.addContent(
+    2,
+    2,
+    "Interactive Elements Demo:",
+    new ColorManager().setColor(255, 255, 100),
+  );
+  frame.addContent(
+    2,
+    3,
+    "Use ↑↓ arrows to navigate, Enter to interact",
+    new ColorManager().setColor(100, 100, 100),
+  );
+
+  let yPos = 5;
+
+  frame.addContent(
+    2,
+    yPos,
+    "Label Element:",
+    new ColorManager().setColor(150, 150, 150),
+  );
+  frame.addContent(
+    2,
+    yPos + 1,
+    "  This is a label that cannot be changed!",
+    new ColorManager().setColor(200, 200, 200),
+  );
+  yPos += 3;
+
+  const inputSelected = selectedElement === 0;
+  const inputColor = inputSelected
+    ? new ColorManager().setColor(100, 255, 100)
+    : new ColorManager().setColor(100, 200, 255);
+  const inputPrefix = inputSelected ? "► " : "  ";
+  frame.addContent(
+    2,
+    yPos,
+    "Input Field:",
+    new ColorManager().setColor(150, 150, 150),
+  );
+  const displayValue = inputValue.padEnd(30, " ").substring(0, 30);
+  frame.addContent(2, yPos + 1, `${inputPrefix}[${displayValue}]`, inputColor);
+  if (inputSelected) {
+    frame.addContent(
+      2,
+      yPos + 2,
+      "  Type a silly message :3",
+      new ColorManager().setColor(100, 100, 100),
+    );
+  }
+  yPos += inputSelected ? 4 : 3;
+
+  const button1Selected = selectedElement === 1;
+  const button1Color = button1Selected
+    ? new ColorManager().setColor(255, 255, 100)
+    : new ColorManager().setColor(100, 255, 100);
+  const button1Prefix = button1Selected ? "► " : "  ";
+  frame.addContent(
+    2,
+    yPos,
+    "Submit Button:",
+    new ColorManager().setColor(150, 150, 150),
+  );
+  frame.addContent(
+    2,
+    yPos + 1,
+    `${button1Prefix}[ Press me!! ]`,
+    button1Color,
+  );
+  if (buttonPressed && button1Selected) {
+    frame.addContent(
+      2,
+      yPos + 2,
+      "  Meeoww :3",
+      new ColorManager().setColor(100, 255, 100),
+    );
+    yPos += 3;
+  } else {
+    yPos += 2;
+  }
+  yPos += 1;
+
+  const button2Selected = selectedElement === 2;
+  const button2Color = button2Selected
+    ? new ColorManager().setColor(255, 255, 100)
+    : new ColorManager().setColor(255, 150, 100);
+  const button2Prefix = button2Selected ? "► " : "  ";
+  frame.addContent(
+    2,
+    yPos,
+    "Counter Button:",
+    new ColorManager().setColor(150, 150, 150),
+  );
+  frame.addContent(
+    2,
+    yPos + 1,
+    `${button2Prefix}[ Increment Counter ]`,
+    button2Color,
+  );
+  frame.addContent(
+    2,
+    yPos + 2,
+    `  Count: ${counter}`,
+    new ColorManager().setColor(255, 200, 100),
+  );
+}
+
+function updateAllWindows() {
+  windows.forEach((win, idx) => {
+    win.update(win.frame);
+    if (idx === activeWindowIndex) {
+      win.frame.setBorderColor(255, 255, 100);
+      win.frame.show();
+      win.frame.setZIndex(100);
+    } else {
+      const colors = [
+        [100, 200, 255],
+        [100, 255, 150],
+        [255, 150, 200],
+      ];
+      win.frame.setBorderColor(...colors[idx]);
+      win.frame.setZIndex(0);
+      if (hideOtherWindows) {
+        win.frame.hide();
+      } else {
+        win.frame.show();
+      }
+    }
+  });
+  screen.elements.sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0));
+}
+
+function render() {
+  updateAllWindows();
+  let controlText = `Tab: Switch  |  Shift+Arrows: Move  |  Alt+H: Focus Mode`;
+  if (activeWindowIndex === 1) {
+    controlText = `↑↓: Navigate  |  Enter: Select  |  Tab: Next Window  |  Shift+Arrows: Move  |  Alt+H: Focus Mode`;
+  }
+  if (hideOtherWindows) {
+    controlText = `[FOCUS MODE] |  Alt+H: Show All  |  Tab: Switch  |  Shift+Arrows: Move`;
+  }
+  screen.setControlBar(controlText);
+  screen.render();
+}
+
+inputManager.onAny((keyName, rawKey) => {
+  if (activeWindowIndex === 1 && selectedElement === 0) {
+    if (rawKey === "\r") {
+      render();
+      return;
+    } else if (rawKey === "\x7f") {
+      inputValue = inputValue.slice(0, -1);
+      render();
+      return;
+    } else if (
+      keyName &&
+      keyName.length === 1 &&
+      !rawKey.startsWith("\x1b") &&
+      keyName.charCodeAt(0) >= 32
+    ) {
+      if (inputValue.length < 30) {
+        inputValue += keyName;
+        render();
+      }
+      return;
+    }
+  }
+
+  if (keyName === "q" || keyName === "Q") {
+    inputManager.stop();
+    screen.exitFullscreen();
+    process.exit(0);
+  }
+
+  if (rawKey === "\t") {
+    activeWindowIndex = (activeWindowIndex + 1) % windows.length;
+    selectedElement = 0;
+    render();
+    return;
+  }
+
+  if (rawKey === '\x1bh' || rawKey === '\x1bH') {
+    hideOtherWindows = !hideOtherWindows;
+    render();
+    return;
+  }
+
+  const activeWin = windows[activeWindowIndex].frame;
+
+  if (rawKey === "\x1b[1;2A") {
+    activeWin.posY = Math.max(1, activeWin.posY - 2);
+    render();
+    return;
+  } else if (rawKey === "\x1b[1;2B") {
+    activeWin.posY = Math.min(
+      screen.height - activeWin.sizeY - 1,
+      activeWin.posY + 2,
+    );
+    render();
+    return;
+  } else if (rawKey === "\x1b[1;2C") {
+    activeWin.posX = Math.min(
+      screen.width - activeWin.sizeX - 1,
+      activeWin.posX + 2,
+    );
+    render();
+    return;
+  } else if (rawKey === "\x1b[1;2D") {
+    activeWin.posX = Math.max(1, activeWin.posX - 2);
+    render();
+    return;
+  }
+
+  if (activeWindowIndex === 1) {
+    if (rawKey === "\x1b[A") {
+      selectedElement =
+        (selectedElement - 1 + sampleElements.length) % sampleElements.length;
+      buttonPressed = false;
+      render();
+      return;
+    } else if (rawKey === "\x1b[B") {
+      selectedElement = (selectedElement + 1) % sampleElements.length;
+      buttonPressed = false;
+      render();
+      return;
+    }
+
+    if (rawKey === "\r") {
+      if (selectedElement === 1) {
+        buttonPressed = true;
+        render();
+        setTimeout(() => {
+          buttonPressed = false;
+          render();
+        }, 500);
+      } else if (selectedElement === 2) {
+        counter++;
+        render();
+      }
+      return;
+    }
+  }
+});
+
+inputManager.start();
+render();
+
+setInterval(() => {
+  render();
+}, 2000);

package/index.js

@@ -0,0 +1,8 @@
+export { Screen } from './classes/screen.js';
+export { ColorManager } from './classes/colorManager.js';
+export { Element, properties } from './classes/element.js';
+export { Frame } from './elements/frame.js';
+export { Input } from './elements/input.js';
+export { Button } from './elements/button.js';
+export { Label } from './elements/label.js';
+export { InputManager } from './classes/inputManager.js';

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "buffalo-tui",
+  "version": "1.0.0",
+  "description": "A beginner friendly TUI framework available on various package managers for Node.js projects",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "demo": "node ./examples/demo.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/transicle/buffalo.git"
+  },
+  "author": "lily.transgirls.win <ilovesuno@proton.me>",
+  "license": "MIT"
+}