@heinrichb/console-toolkit 1.0.3 → 1.0.5

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/components/progress.d.ts

@@ -0,0 +1,75 @@
+import { StyledLine, Style } from "../core/types";
+export interface ProgressBarOptions {
+    /**
+     * Progress value between 0.0 and 1.0.
+     */
+    progress: number;
+    /**
+     * Width of the progress bar (excluding brackets and percentage).
+     * Defaults to 20.
+     */
+    width?: number;
+    /**
+     * Base style for the entire progress bar.
+     */
+    style?: Style | Style[];
+    /**
+     * Style for the brackets (start and end characters).
+     * Defaults to `style` or gray.
+     */
+    bracketStyle?: Style | Style[];
+    /**
+     * Specific style for the start bracket. Overrides `bracketStyle`.
+     */
+    startStyle?: Style | Style[];
+    /**
+     * Specific style for the end bracket. Overrides `bracketStyle`.
+     */
+    endStyle?: Style | Style[];
+    /**
+     * Style for the bar (filled and empty parts).
+     * Defaults to `style`.
+     */
+    barStyle?: Style | Style[];
+    /**
+     * Specific style for the filled part. Overrides `barStyle`.
+     */
+    fillStyle?: Style | Style[];
+    /**
+     * Specific style for the empty part. Overrides `barStyle`.
+     */
+    emptyStyle?: Style | Style[];
+    /**
+     * Style for the percentage text.
+     * Defaults to `style`.
+     */
+    percentageStyle?: Style | Style[];
+    /**
+     * Character to use for the start bracket. Defaults to `[`.
+     */
+    startChar?: string;
+    /**
+     * Character to use for the end bracket. Defaults to `]`.
+     */
+    endChar?: string;
+    /**
+     * Character to use for the filled part. Defaults to `█`.
+     */
+    fillChar?: string;
+    /**
+     * Character to use for the empty part. Defaults to `░`.
+     */
+    emptyChar?: string;
+    /**
+     * Whether to show the percentage text. Defaults to `true`.
+     */
+    showPercentage?: boolean;
+    /**
+     * Custom formatter for the percentage text.
+     */
+    formatPercentage?: (progress: number) => string;
+}
+/**
+ * Creates a StyledLine representing a progress bar.
+ */
+export declare function createProgressBar(options: ProgressBarOptions): StyledLine;

package/dist/components/progress.js

@@ -0,0 +1,43 @@
+/**
+ * Creates a StyledLine 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;
+    // Clamp progress
+    const p = Math.max(0, Math.min(1, progress));
+    // Calculate filled width
+    const filledWidth = Math.round(p * width);
+    const emptyWidth = width - filledWidth;
+    // Resolve styles
+    const baseStyle = style ?? [];
+    const resolvedBracketStyle = bracketStyle ?? baseStyle;
+    const resolvedStartStyle = startStyle ?? resolvedBracketStyle;
+    const resolvedEndStyle = endStyle ?? resolvedBracketStyle;
+    const resolvedBarStyle = barStyle ?? baseStyle;
+    const resolvedFillStyle = fillStyle ?? resolvedBarStyle;
+    const resolvedEmptyStyle = emptyStyle ?? resolvedBarStyle;
+    const resolvedPercentageStyle = percentageStyle ?? baseStyle;
+    const segments = [];
+    // Start Bracket
+    if (startChar) {
+        segments.push({ text: startChar, style: resolvedStartStyle });
+    }
+    // Filled Part
+    if (filledWidth > 0) {
+        segments.push({ text: fillChar.repeat(filledWidth), style: resolvedFillStyle });
+    }
+    // Empty Part
+    if (emptyWidth > 0) {
+        segments.push({ text: emptyChar.repeat(emptyWidth), style: resolvedEmptyStyle });
+    }
+    // End Bracket
+    if (endChar) {
+        segments.push({ text: endChar, style: resolvedEndStyle });
+    }
+    // Percentage
+    if (showPercentage) {
+        const percentageText = formatPercentage ? formatPercentage(p) : ` ${Math.round(p * 100)}%`;
+        segments.push({ text: percentageText, style: resolvedPercentageStyle });
+    }
+    return { segments };
+}

package/dist/components/progress.test.d.ts

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

package/dist/components/progress.test.js

@@ -0,0 +1,101 @@
+import { expect, test, describe } from "bun:test";
+import { createProgressBar } from "./progress";
+function getText(line) {
+    return line.segments.map((s) => s.text).join("");
+}
+describe("createProgressBar", () => {
+    test("generates a default progress bar at 0%", () => {
+        const line = createProgressBar({ progress: 0 });
+        const text = getText(line);
+        expect(text).toContain("[");
+        expect(text).toContain("]");
+        expect(text).toContain("0%");
+        expect(text).toContain("░");
+    });
+    test("generates a default progress bar at 50%", () => {
+        const line = createProgressBar({ progress: 0.5 });
+        const text = getText(line);
+        expect(text).toContain("50%");
+        expect(text).toContain("█");
+        expect(text).toContain("░");
+    });
+    test("generates a default progress bar at 100%", () => {
+        const line = createProgressBar({ progress: 1.0 });
+        const text = getText(line);
+        expect(text).toContain("100%");
+        expect(text).not.toContain("░");
+    });
+    test("allows custom width", () => {
+        const width = 10;
+        const line = createProgressBar({ progress: 0.5, width });
+        const segments = line.segments;
+        const filled = segments.find((s) => s.text.includes("█"));
+        const empty = segments.find((s) => s.text.includes("░"));
+        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"
+        });
+        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");
+    });
+    test("cascades styles (general style -> specific)", () => {
+        const line = createProgressBar({
+            progress: 0.5,
+            style: "blue"
+        });
+        line.segments.forEach((s) => {
+            if (s.text.trim().length > 0) {
+                expect(s.style).toBe("blue");
+            }
+        });
+    });
+    test("allows custom characters", () => {
+        const line = createProgressBar({
+            progress: 0.5,
+            startChar: "<",
+            endChar: ">",
+            fillChar: "=",
+            emptyChar: "-"
+        });
+        const text = getText(line);
+        expect(text).toContain("<");
+        expect(text).toContain(">");
+        expect(text).toContain("=");
+        expect(text).toContain("-");
+    });
+    test("hides percentage", () => {
+        const line = createProgressBar({
+            progress: 0.5,
+            showPercentage: false
+        });
+        const text = getText(line);
+        expect(text).not.toContain("%");
+    });
+    test("formats percentage custom", () => {
+        const line = createProgressBar({
+            progress: 0.5,
+            formatPercentage: (p) => `${p * 10}/10`
+        });
+        const text = getText(line);
+        expect(text).toContain("5/10");
+    });
+    test("clamping progress", () => {
+        const lineLow = createProgressBar({ progress: -0.1 });
+        expect(getText(lineLow)).toContain("0%");
+        const lineHigh = createProgressBar({ progress: 1.1 });
+        expect(getText(lineHigh)).toContain("100%");
+    });
+});

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.d.ts

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

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 { Style, StyledLine } from "./types";
+import { Printer } from "./printer";
+/**
+ * Merges multiple columns of StyledLines into a single layout.
+ * Ensures proper alignment by padding shorter lines.
+ *
+ * @param columns - Array of columns, where each column is an array of StyledLines.
+ * @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 StyledLines representing the merged output.
+ */
+export declare function mergeMultipleColumns(columns: StyledLine[][], separator: string, defaultStyle: Style | Style[], widths?: number[]): StyledLine[];
+/**
+ * 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: StyledLine[][], options?: {
+    widths?: number[];
+    separator?: string;
+    printer?: Printer;
+}): void;

package/dist/core/layout.js

@@ -0,0 +1,57 @@
+import { computeMaxWidth, padLine } from "./utils";
+import { Printer } from "./printer";
+import { RESET } from "./style";
+// -----------------
+// Core Layout & Printing
+// -----------------
+const defaultPrinter = new Printer();
+/**
+ * Merges multiple columns of StyledLines into a single layout.
+ * Ensures proper alignment by padding shorter lines.
+ *
+ * @param columns - Array of columns, where each column is an array of StyledLines.
+ * @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 StyledLines 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: [] };
+            // Pad if not the last column
+            if (j < columns.length - 1) {
+                const padded = padLine(line, colWidths[j], defaultStyle);
+                segments = [...segments, ...padded.segments, { text: separator, style: defaultStyle }];
+            }
+            else {
+                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 = defaultPrinter } = options;
+    const defaultStyle = RESET;
+    const mergedLines = mergeMultipleColumns(columns, separator, defaultStyle, widths);
+    printer.print(mergedLines);
+}

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

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

package/dist/core/layout.test.js

@@ -0,0 +1,41 @@
+import { expect, test, describe, spyOn, afterEach } from "bun:test";
+import { mergeMultipleColumns, printColumns } from "./layout";
+import { getLineLength } from "./utils";
+const lineA = { segments: [{ text: "Hello", style: [] }] };
+const lineB = { segments: [{ text: "World!!", style: [] }] };
+describe("Layout Utilities", () => {
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true);
+    afterEach(() => {
+        stdoutSpy.mockClear();
+    });
+    test("mergeMultipleColumns handles asymmetric column lengths", () => {
+        const merged = mergeMultipleColumns([[lineA], [lineB, lineB]], " | ", "", [10]);
+        expect(merged.length).toBe(2);
+        expect(getLineLength(merged[1])).toBe(10 + 3 + 7);
+    });
+    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([]);
+        expect(stdoutSpy).toHaveBeenCalled(); // Should clear lines if interactive, or do nothing.
+    });
+    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,20 @@
+import { PrinterOptions, StyledLine } from "./types";
+/**
+ * Handles rendering StyledLines to the terminal with support for interactive overwriting.
+ */
+export declare class Printer {
+    private linesRendered;
+    private isInteractive;
+    constructor(options?: PrinterOptions);
+    /**
+     * Generates the clear sequence to move cursor and clear previously rendered lines.
+     */
+    private getClearSequence;
+    /**
+     * Renders an array of StyledLines to the standard output.
+     * If interactive mode is enabled, it clears the previously printed lines first.
+     *
+     * @param lines - The lines to print.
+     */
+    print(lines: StyledLine[]): void;
+}