@heinrichb/console-toolkit 1.0.3 → 1.0.6

package/README.md

@@ -1,2 +1,162 @@
-# console-toolkit
-A versatile TypeScript utility library for enhanced console logging, formatting, and layout management.
+# 🎨 Console Toolkit
+
+**@heinrichb/console-toolkit** is a powerful, lightweight TypeScript library for creating beautiful, interactive, and structured command-line interfaces. From simple colored text to complex multi-column layouts and live-updating progress bars, this toolkit has everything you need to elevate your CLI experience.
+
+---
+
+## 🚀 Features
+
+- **🌈 Rich Styling:** Support for standard ANSI colors, true-color Hex codes, and text modifiers (bold, dim, italic, etc.).
+- **✨ Gradients:** Easy-to-use linear gradients for text and backgrounds.
+- **live-updating:** Built-in support for live-updating displays (perfect for spinners and progress bars).
+- **📐 Flexible Layouts:** powerful grid system for multi-column layouts with automatic padding and alignment.
+- **🧩 Components:** Pre-built, customizable components like **Progress Bars** and **Spinners**.
+- **🐉 Presets:** Fun ASCII art presets (like dragons!) to spice up your output.
+- **TypeScript First:** Fully typed for a great developer experience.
+
+---
+
+## 📦 Installation
+
+This library is designed for use with **Bun** or **Node.js**.
+
+```bash
+bun add @heinrichb/console-toolkit
+# or
+npm install @heinrichb/console-toolkit
+```
+
+---
+
+## ⚡ Quick Start
+
+Get up and running in seconds:
+
+```typescript
+import { Printer } from "@heinrichb/console-toolkit";
+
+const printer = new Printer();
+
+printer.print({
+	lines: [
+		{
+			segments: [
+				{ text: "Hello, ", style: { color: "blue", modifiers: ["bold"] } },
+				{ text: "World!", style: { color: "#10B981", modifiers: ["italic"] } } // Hex color support!
+			]
+		}
+	]
+});
+```
+
+---
+
+## 🎨 Styling
+
+We support a flexible styling system that works with both standard terminal colors and full RGB Hex codes.
+
+### Basic Colors & Modifiers
+
+```typescript
+import { PrintStyle } from "@heinrichb/console-toolkit";
+
+const myStyle: PrintStyle = {
+	color: "red", // Standard color
+	modifiers: ["bold", "underline"]
+};
+```
+
+### Hex Colors & Gradients
+
+You can use any hex color string. For gradients, simply provide an array of colors!
+
+```typescript
+const gradientStyle: PrintStyle = {
+	// Creates a gradient from Red to Blue
+	color: ["#EF4444", "#3B82F6"]
+};
+```
+
+---
+
+## 📐 Layouts
+
+Creating multi-column layouts is a breeze.
+
+```typescript
+import { printColumns } from "@heinrichb/console-toolkit";
+
+printColumns(
+	[
+		[
+			// Column 1
+			{ segments: [{ text: "Item 1" }] },
+			{ segments: [{ text: "Item 2" }] }
+		],
+		[
+			// Column 2
+			{ segments: [{ text: "Description 1", style: { color: "gray" } }] },
+			{ segments: [{ text: "Description 2", style: { color: "gray" } }] }
+		]
+	],
+	{ separator: " | " }
+);
+```
+
+---
+
+## 🧩 Components
+
+### Progress Bars
+
+Create customizable progress bars with ease.
+
+```typescript
+import { createProgressBar, Printer } from "@heinrichb/console-toolkit";
+
+const printer = new Printer({ live: true });
+const bar = createProgressBar({
+	progress: 0.75,
+	width: 30,
+	fillStyle: { color: "green" },
+	emptyStyle: { color: "gray" }
+});
+
+printer.print({ lines: [bar] });
+```
+
+### Spinners
+
+Add activity indicators to your long-running tasks.
+
+```typescript
+import { Spinner, SPINNERS, Printer } from "@heinrichb/console-toolkit";
+
+const spinner = new Spinner({ frames: SPINNERS.dots });
+const printer = new Printer({ live: true });
+
+// In your loop:
+printer.print({
+	lines: [
+		{
+			segments: [{ text: spinner.getFrame(), style: { color: "cyan" } }]
+		}
+	]
+});
+```
+
+---
+
+## 📚 Detailed Documentation
+
+For more in-depth information on specific parts of the library, check out the detailed guides below:
+
+- **[Core Engine & Styling](src/core/README.md):** Deep dive into `Printer`, `PrintBlock`, `PrintStyle`, and advanced layout techniques.
+- **[Components](src/components/README.md):** Full API reference for `ProgressBar`, `Spinner`, and how to build your own components.
+- **[Presets](src/presets/README.md):** Explore available ASCII art and other presets.
+
+---
+
+## 📄 License
+
+MIT © Brennen Heinrich

package/dist/{progress.d.ts → components/progress.d.ts}

@@ -1,4 +1,4 @@
-import { StyledLine, Style } from "./index";
+import { PrintLine, PrintStyle } from "../core/types";
 export interface ProgressBarOptions {
     /**
      * Progress value between 0.0 and 1.0.
@@ -12,38 +12,38 @@ export interface ProgressBarOptions {
     /**
      * Base style for the entire progress bar.
      */
-    style?: Style | Style[];
+    style?: PrintStyle;
     /**
      * Style for the brackets (start and end characters).
-     * Defaults to `style` or gray.
+     * Defaults to `style`.
      */
-    bracketStyle?: Style | Style[];
+    bracketStyle?: PrintStyle;
     /**
      * Specific style for the start bracket. Overrides `bracketStyle`.
      */
-    startStyle?: Style | Style[];
+    startStyle?: PrintStyle;
     /**
      * Specific style for the end bracket. Overrides `bracketStyle`.
      */
-    endStyle?: Style | Style[];
+    endStyle?: PrintStyle;
     /**
      * Style for the bar (filled and empty parts).
      * Defaults to `style`.
      */
-    barStyle?: Style | Style[];
+    barStyle?: PrintStyle;
     /**
      * Specific style for the filled part. Overrides `barStyle`.
      */
-    fillStyle?: Style | Style[];
+    fillStyle?: PrintStyle;
     /**
      * Specific style for the empty part. Overrides `barStyle`.
      */
-    emptyStyle?: Style | Style[];
+    emptyStyle?: PrintStyle;
     /**
      * Style for the percentage text.
      * Defaults to `style`.
      */
-    percentageStyle?: Style | Style[];
+    percentageStyle?: PrintStyle;
     /**
      * Character to use for the start bracket. Defaults to `[`.
      */
@@ -70,6 +70,6 @@ export interface ProgressBarOptions {
     formatPercentage?: (progress: number) => string;
 }
 /**
- * Creates a StyledLine representing a progress bar.
+ * Creates a PrintLine representing a progress bar.
  */
-export declare function createProgressBar(options: ProgressBarOptions): StyledLine;
+export declare function createProgressBar(options: ProgressBarOptions): PrintLine;

package/dist/{progress.js → components/progress.js}

@@ -1,5 +1,5 @@
 /**
- * Creates a StyledLine representing a progress bar.
+ * Creates a PrintLine representing a progress bar.
  */
 export function createProgressBar(options) {
     const { progress, width = 20, style, bracketStyle, startStyle, endStyle, barStyle, fillStyle, emptyStyle, percentageStyle, startChar = "[", endChar = "]", fillChar = "█", emptyChar = "░", showPercentage = true, formatPercentage } = options;
@@ -8,15 +8,14 @@ export function createProgressBar(options) {
     // Calculate filled width
     const filledWidth = Math.round(p * width);
     const emptyWidth = width - filledWidth;
-    // Resolve styles
-    const baseStyle = style ?? [];
-    const resolvedBracketStyle = bracketStyle ?? baseStyle;
+    // Resolve styles (Defaults)
+    const resolvedBracketStyle = bracketStyle ?? style;
     const resolvedStartStyle = startStyle ?? resolvedBracketStyle;
     const resolvedEndStyle = endStyle ?? resolvedBracketStyle;
-    const resolvedBarStyle = barStyle ?? baseStyle;
+    const resolvedBarStyle = barStyle ?? style;
     const resolvedFillStyle = fillStyle ?? resolvedBarStyle;
     const resolvedEmptyStyle = emptyStyle ?? resolvedBarStyle;
-    const resolvedPercentageStyle = percentageStyle ?? baseStyle;
+    const resolvedPercentageStyle = percentageStyle ?? style;
     const segments = [];
     // Start Bracket
     if (startChar) {

package/dist/{progress.test.js → components/progress.test.js}

@@ -7,6 +7,7 @@ describe("createProgressBar", () => {
     test("generates a default progress bar at 0%", () => {
         const line = createProgressBar({ progress: 0 });
         const text = getText(line);
+        // Default format: [░░░░░░░░░░░░░░░░░░░░] 0%
         expect(text).toContain("[");
         expect(text).toContain("]");
         expect(text).toContain("0%");
@@ -23,6 +24,8 @@ describe("createProgressBar", () => {
         const line = createProgressBar({ progress: 1.0 });
         const text = getText(line);
         expect(text).toContain("100%");
+        // Should not contain empty char
+        // But wait, width default 20. 100% means 20 filled. 0 empty.
         expect(text).not.toContain("░");
     });
     test("allows custom width", () => {
@@ -31,34 +34,35 @@ describe("createProgressBar", () => {
         const segments = line.segments;
         const filled = segments.find((s) => s.text.includes("█"));
         const empty = segments.find((s) => s.text.includes("░"));
+        // 50% of 10 is 5.
         expect(filled?.text.length).toBe(5);
         expect(empty?.text.length).toBe(5);
     });
     test("applies styles correctly", () => {
         const line = createProgressBar({
             progress: 0.5,
-            style: "blue",
-            bracketStyle: "red",
-            barStyle: "green",
-            percentageStyle: "yellow"
+            style: { color: "blue" },
+            bracketStyle: { color: "red" },
+            barStyle: { color: "green" },
+            percentageStyle: { color: "yellow" }
         });
         const start = line.segments.find((s) => s.text === "[");
         const filled = line.segments.find((s) => s.text.includes("█"));
         const end = line.segments.find((s) => s.text === "]");
         const percentage = line.segments.find((s) => s.text.includes("%"));
-        expect(start?.style).toBe("red");
-        expect(filled?.style).toBe("green");
-        expect(end?.style).toBe("red");
-        expect(percentage?.style).toBe("yellow");
+        expect(start?.style).toEqual({ color: "red" });
+        expect(filled?.style).toEqual({ color: "green" });
+        expect(end?.style).toEqual({ color: "red" });
+        expect(percentage?.style).toEqual({ color: "yellow" });
     });
     test("cascades styles (general style -> specific)", () => {
         const line = createProgressBar({
             progress: 0.5,
-            style: "blue"
+            style: { color: "blue" }
         });
         line.segments.forEach((s) => {
             if (s.text.trim().length > 0) {
-                expect(s.style).toBe("blue");
+                expect(s.style).toEqual({ color: "blue" });
             }
         });
     });

package/dist/components/spinner.d.ts

@@ -0,0 +1,36 @@
+export type SpinnerFrames = string[];
+export interface SpinnerOptions {
+    /**
+     * The array of frames to cycle through.
+     */
+    frames: SpinnerFrames;
+    /**
+     * The interval in milliseconds between frames.
+     * Defaults to 80ms.
+     */
+    interval?: number;
+}
+/**
+ * Common spinner frame presets.
+ */
+export declare const SPINNERS: {
+    dots: string[];
+    lines: string[];
+    arrows: string[];
+    circle: string[];
+    square: string[];
+};
+/**
+ * A stateful spinner that calculates the current frame based on elapsed time.
+ * Designed to be used within a render loop (e.g. Printer.print loop).
+ */
+export declare class Spinner {
+    private frames;
+    private interval;
+    private startTime;
+    constructor(options: SpinnerOptions);
+    /**
+     * Returns the current frame based on the elapsed time.
+     */
+    getFrame(): string;
+}

package/dist/components/spinner.js

@@ -0,0 +1,33 @@
+/**
+ * Common spinner frame presets.
+ */
+export const SPINNERS = {
+    dots: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    lines: ["-", "\\", "|", "/"],
+    arrows: ["←", "↖", "↑", "↗", "→", "↘", "↓", "↙"],
+    circle: ["◐", "◓", "◑", "◒"],
+    square: ["▖", "▘", "▝", "▗"]
+};
+/**
+ * A stateful spinner that calculates the current frame based on elapsed time.
+ * Designed to be used within a render loop (e.g. Printer.print loop).
+ */
+export class Spinner {
+    frames;
+    interval;
+    startTime;
+    constructor(options) {
+        this.frames = options.frames;
+        this.interval = options.interval ?? 80;
+        this.startTime = Date.now();
+    }
+    /**
+     * Returns the current frame based on the elapsed time.
+     */
+    getFrame() {
+        const now = Date.now();
+        const elapsed = now - this.startTime;
+        const index = Math.floor(elapsed / this.interval) % this.frames.length;
+        return this.frames[index];
+    }
+}

package/dist/components/spinner.test.js

@@ -0,0 +1,53 @@
+import { expect, test, describe, spyOn, afterEach, beforeEach } from "bun:test";
+import { Spinner, SPINNERS } from "./spinner";
+describe("Spinner Class", () => {
+    let now = 1000;
+    // Mock Date.now() to control time
+    const dateSpy = spyOn(Date, "now").mockImplementation(() => now);
+    beforeEach(() => {
+        now = 1000;
+        dateSpy.mockClear();
+        dateSpy.mockImplementation(() => now);
+    });
+    afterEach(() => {
+        dateSpy.mockClear();
+    });
+    test("initializes with correct defaults", () => {
+        const spinner = new Spinner({ frames: ["a", "b"] });
+        expect(spinner.getFrame()).toBe("a");
+    });
+    test("advances frames over time", () => {
+        const spinner = new Spinner({ frames: ["a", "b", "c"], interval: 100 });
+        // t=0 (1000)
+        expect(spinner.getFrame()).toBe("a");
+        // t=50 (1050) -> still frame 0
+        now = 1050;
+        expect(spinner.getFrame()).toBe("a");
+        // t=100 (1100) -> frame 1
+        now = 1100;
+        expect(spinner.getFrame()).toBe("b");
+        // t=200 (1200) -> frame 2
+        now = 1200;
+        expect(spinner.getFrame()).toBe("c");
+        // t=300 (1300) -> frame 0 (loop)
+        now = 1300;
+        expect(spinner.getFrame()).toBe("a");
+    });
+    test("uses custom interval", () => {
+        const spinner = new Spinner({ frames: ["a", "b"], interval: 50 });
+        // t=0
+        expect(spinner.getFrame()).toBe("a");
+        // t=50 -> frame 1
+        now = 1050;
+        expect(spinner.getFrame()).toBe("b");
+    });
+});
+describe("Spinner Presets", () => {
+    test("dots preset exists and has frames", () => {
+        expect(SPINNERS.dots).toBeDefined();
+        expect(SPINNERS.dots.length).toBeGreaterThan(0);
+    });
+    test("lines preset exists", () => {
+        expect(SPINNERS.lines).toBeDefined();
+    });
+});

package/dist/core/layout.d.ts

@@ -0,0 +1,25 @@
+import { PrintLine, PrintStyle } from "./types";
+import { Printer } from "./printer";
+/**
+ * Merges multiple columns of PrintLines into a single layout.
+ * Ensures proper alignment by padding shorter lines.
+ *
+ * @param columns - Array of columns, where each column is an array of PrintLines.
+ * @param separator - String used to separate columns.
+ * @param defaultStyle - Style to apply to the separator and padding.
+ * @param widths - Optional fixed widths for each column.
+ * @returns A single array of PrintLines representing the merged output.
+ */
+export declare function mergeMultipleColumns(columns: PrintLine[][], separator?: string, defaultStyle?: PrintStyle, widths?: number[]): PrintLine[];
+/**
+ * Prints multiple columns of styled content to the console.
+ * A convenience wrapper around `mergeMultipleColumns` and `Printer.print`.
+ *
+ * @param columns - Array of columns to print.
+ * @param options - Layout options (widths, separator, custom printer).
+ */
+export declare function printColumns(columns: PrintLine[][], options?: {
+    widths?: number[];
+    separator?: string;
+    printer?: Printer;
+}): void;

package/dist/core/layout.js

@@ -0,0 +1,55 @@
+import { computeMaxWidth, padLine } from "./utils";
+import { Printer } from "./printer";
+// -----------------
+// Core Layout & Printing
+// -----------------
+/**
+ * Merges multiple columns of PrintLines into a single layout.
+ * Ensures proper alignment by padding shorter lines.
+ *
+ * @param columns - Array of columns, where each column is an array of PrintLines.
+ * @param separator - String used to separate columns.
+ * @param defaultStyle - Style to apply to the separator and padding.
+ * @param widths - Optional fixed widths for each column.
+ * @returns A single array of PrintLines representing the merged output.
+ */
+export function mergeMultipleColumns(columns, separator = "     ", defaultStyle, widths) {
+    if (columns.length === 0)
+        return [];
+    const maxLines = Math.max(...columns.map((c) => c.length));
+    const colWidths = columns.map((col, i) => {
+        if (widths?.[i] !== undefined)
+            return widths[i];
+        return computeMaxWidth(col);
+    });
+    const output = [];
+    for (let i = 0; i < maxLines; i++) {
+        let segments = [];
+        for (let j = 0; j < columns.length; j++) {
+            const line = columns[j][i] || { segments: [] };
+            // If not the last column, pad it
+            if (j < columns.length - 1) {
+                const padded = padLine(line, colWidths[j], defaultStyle);
+                segments = [...segments, ...padded.segments, { text: separator, style: defaultStyle }];
+            }
+            else {
+                // Last column, just add segments
+                segments = [...segments, ...line.segments];
+            }
+        }
+        output.push({ segments });
+    }
+    return output;
+}
+/**
+ * Prints multiple columns of styled content to the console.
+ * A convenience wrapper around `mergeMultipleColumns` and `Printer.print`.
+ *
+ * @param columns - Array of columns to print.
+ * @param options - Layout options (widths, separator, custom printer).
+ */
+export function printColumns(columns, options = {}) {
+    const { widths, separator = "     ", printer = new Printer() } = options;
+    const mergedLines = mergeMultipleColumns(columns, separator, undefined, widths);
+    printer.print({ lines: mergedLines });
+}

package/dist/core/layout.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/layout.test.js

@@ -0,0 +1,52 @@
+import { expect, test, describe, spyOn, afterEach } from "bun:test";
+import { mergeMultipleColumns, printColumns } from "./layout";
+import { getLineLength } from "./utils";
+const lineA = { segments: [{ text: "Hello" }] };
+const lineB = { segments: [{ text: "World!!" }] };
+describe("Layout Utilities", () => {
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true);
+    afterEach(() => {
+        stdoutSpy.mockClear();
+    });
+    test("mergeMultipleColumns handles asymmetric column lengths", () => {
+        // Column 1: [lineA]
+        // Column 2: [lineB, lineB]
+        // Separator: " | "
+        // Default Style: undefined
+        // Widths: [10] (first col width 10)
+        const merged = mergeMultipleColumns([[lineA], [lineB, lineB]], " | ", undefined, [10]);
+        expect(merged.length).toBe(2);
+        // Second merged line:
+        // Col 1 is empty (pad to 10) + " | " + Col 2 (lineB, length 7)
+        // 10 + 3 + 7 = 20
+        expect(getLineLength(merged[1])).toBe(20);
+    });
+    test("printColumns executes correctly", () => {
+        printColumns([[lineA], [lineB]]);
+        expect(stdoutSpy).toHaveBeenCalled();
+        const output = stdoutSpy.mock.calls[0][0];
+        expect(output).toContain("Hello");
+        expect(output).toContain("World!!");
+    });
+    test("printColumns handles undefined style in segments", () => {
+        const lineNoStyle = { segments: [{ text: "NoStyle" }] };
+        printColumns([[lineNoStyle]]);
+        expect(stdoutSpy).toHaveBeenCalled();
+        const output = stdoutSpy.mock.calls[0][0];
+        expect(output).toContain("NoStyle");
+    });
+    test("printColumns handles empty columns", () => {
+        printColumns([]);
+        // Should just print nothing or minimal output (if logic handles empty array gracefully)
+        // mergeMultipleColumns returns []
+        // printer.print({ lines: [] }) -> might output clear sequence or empty string
+        expect(stdoutSpy).toHaveBeenCalled();
+    });
+    test("printColumns handles 3 columns", () => {
+        printColumns([[lineA], [lineA], [lineB]]);
+        expect(stdoutSpy).toHaveBeenCalled();
+        const output = stdoutSpy.mock.calls[0][0];
+        expect(output).toContain("Hello");
+        expect(output).toContain("World!!");
+    });
+});

package/dist/core/printer.d.ts

@@ -0,0 +1,33 @@
+import { PrintBlock, PrinterOptions } from "./types";
+/**
+ * Handles rendering PrintBlocks to the terminal with support for interactive/live overwriting.
+ */
+export declare class Printer {
+    private linesRendered;
+    private isLive;
+    private data?;
+    constructor(options?: PrinterOptions);
+    /**
+     * Generates the clear sequence to move cursor and clear previously rendered lines.
+     */
+    private getClearSequence;
+    /**
+     * Clears the console using the stored line count.
+     */
+    clear(): void;
+    /**
+     * Renders the PrintBlock to the standard output.
+     * If data is provided, updates the internal state.
+     *
+     * @param data - Optional data to update the printer with.
+     */
+    print(data?: PrintBlock): void;
+    /**
+     * Resolves the block's vertical gradient (if any) to a solid color for the specific line.
+     */
+    private resolveBlockColorForLine;
+    /**
+     * Renders a single line.
+     */
+    private renderLine;
+}