@heinrichb/console-toolkit 1.0.3 → 1.0.5

package/dist/core/printer.js

@@ -0,0 +1,41 @@
+import { resolveStyle, RESET } from "./style";
+const ESC = "\x1b";
+// -----------------
+// Printer Class
+// -----------------
+/**
+ * Handles rendering StyledLines to the terminal with support for interactive overwriting.
+ */
+export class Printer {
+    linesRendered = 0;
+    isInteractive;
+    constructor(options = {}) {
+        this.isInteractive = options.interactive ?? false;
+    }
+    /**
+     * Generates the clear sequence to move cursor and clear previously rendered lines.
+     */
+    getClearSequence() {
+        if (!this.isInteractive || this.linesRendered === 0)
+            return "";
+        return `${ESC}[1A${ESC}[2K\r`.repeat(this.linesRendered);
+    }
+    /**
+     * 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) {
+        let output = this.getClearSequence();
+        lines.forEach((line) => {
+            line.segments.forEach((seg) => {
+                const ansiStyle = resolveStyle(seg.style);
+                output += `${ansiStyle}${seg.text}${RESET}`;
+            });
+            output += "\n";
+        });
+        process.stdout.write(output);
+        this.linesRendered = lines.length;
+    }
+}

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

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

package/dist/core/printer.test.js

@@ -0,0 +1,36 @@
+import { expect, test, describe, spyOn, afterEach } from "bun:test";
+import { Printer } from "./printer";
+describe("Printer", () => {
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true);
+    afterEach(() => {
+        stdoutSpy.mockClear();
+    });
+    test("Printer.print outputs to console with resolved styles", () => {
+        const printer = new Printer();
+        printer.print([{ segments: [{ text: "Test", style: "red" }] }]);
+        expect(stdoutSpy).toHaveBeenCalled();
+        const output = stdoutSpy.mock.calls[0][0];
+        expect(output).toContain("\x1b[31mTest");
+    });
+    test("Printer handles interactive clearing", () => {
+        const printer = new Printer({ interactive: true });
+        printer.print([{ segments: [{ text: "L1", style: "" }] }]);
+        printer.print([{ segments: [{ text: "L2", style: "" }] }]);
+        expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining("\x1b[1A\x1b[2K\r"));
+    });
+    test("Printer optimizes clearing of multiple lines", () => {
+        const printer = new Printer({ interactive: true });
+        printer.print([
+            { segments: [{ text: "L1", style: "" }] },
+            { segments: [{ text: "L2", style: "" }] },
+            { segments: [{ text: "L3", style: "" }] }
+        ]);
+        stdoutSpy.mockClear();
+        printer.print([{ segments: [{ text: "New", style: "" }] }]);
+        const clearSeq = "\x1b[1A\x1b[2K\r";
+        const expectedClear = clearSeq.repeat(3);
+        expect(stdoutSpy).toHaveBeenCalledTimes(1);
+        const callArg = stdoutSpy.mock.calls[0][0];
+        expect(callArg.startsWith(expectedClear)).toBe(true);
+    });
+});

package/dist/core/style.d.ts

@@ -0,0 +1,51 @@
+import { HexColor, Style } from "./types";
+/**
+ * ANSI escape sequence to reset all styles.
+ */
+export declare const RESET = "\u001B[0m";
+/**
+ * Converts a hex color string to an RGB object.
+ * Validates the hex string format.
+ *
+ * @param hex - Hex color in the form "#RRGGBB".
+ * @returns Object with r, g, b components (0-255).
+ */
+export declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Converts RGB to a 24-bit ANSI foreground color escape sequence.
+ *
+ * @param r - Red component (0-255).
+ * @param g - Green component (0-255).
+ * @param b - Blue component (0-255).
+ * @returns ANSI escape sequence string.
+ */
+export declare function rgbToAnsi(r: number, g: number, b: number): string;
+/**
+ * Converts a hex color string directly to an ANSI escape sequence.
+ *
+ * @param hex - Hex color string.
+ * @returns ANSI escape sequence string.
+ */
+export declare function hexToAnsi(hex: string): string;
+/**
+ * Interpolates between two hex colors based on a factor (0 to 1) and returns a Hex color string.
+ * Used for gradients.
+ *
+ * @param color1 - Start color (hex).
+ * @param color2 - End color (hex).
+ * @param factor - Interpolation factor (0.0 to 1.0).
+ * @returns Interpolated Hex color.
+ */
+export declare function interpolateColor(color1: string, color2: string, factor: number): HexColor;
+/**
+ * Resolves a single Style or array of Styles into an ANSI escape sequence.
+ * Handles hex colors, standard colors, and modifiers.
+ *
+ * @param style - The style or array of styles to resolve.
+ * @returns The resulting ANSI escape sequence string.
+ */
+export declare function resolveStyle(style?: Style | Style[]): string;

package/dist/core/style.js

@@ -0,0 +1,127 @@
+// -----------------
+// Color Utilities
+// -----------------
+const ESC = "\x1b";
+/**
+ * ANSI escape sequence to reset all styles.
+ */
+export const RESET = `${ESC}[0m`;
+/**
+ * Converts a hex color string to an RGB object.
+ * Validates the hex string format.
+ *
+ * @param hex - Hex color in the form "#RRGGBB".
+ * @returns Object with r, g, b components (0-255).
+ */
+export function hexToRgb(hex) {
+    const h = hex.replace(/^#/, "");
+    if (h.length !== 6)
+        throw new Error("Invalid hex color.");
+    return {
+        r: parseInt(h.substring(0, 2), 16),
+        g: parseInt(h.substring(2, 4), 16),
+        b: parseInt(h.substring(4, 6), 16)
+    };
+}
+/**
+ * Converts RGB to a 24-bit ANSI foreground color escape sequence.
+ *
+ * @param r - Red component (0-255).
+ * @param g - Green component (0-255).
+ * @param b - Blue component (0-255).
+ * @returns ANSI escape sequence string.
+ */
+export function rgbToAnsi(r, g, b) {
+    return `${ESC}[38;2;${r};${g};${b}m`;
+}
+/**
+ * Converts a hex color string directly to an ANSI escape sequence.
+ *
+ * @param hex - Hex color string.
+ * @returns ANSI escape sequence string.
+ */
+export function hexToAnsi(hex) {
+    const { r, g, b } = hexToRgb(hex);
+    return rgbToAnsi(r, g, b);
+}
+/**
+ * Converts a single RGB component to a 2-digit hex string.
+ * Helper for interpolation.
+ */
+function toHex(c) {
+    const hex = Math.max(0, Math.min(255, Math.round(c))).toString(16);
+    return hex.length === 1 ? "0" + hex : hex;
+}
+/**
+ * Interpolates between two hex colors based on a factor (0 to 1) and returns a Hex color string.
+ * Used for gradients.
+ *
+ * @param color1 - Start color (hex).
+ * @param color2 - End color (hex).
+ * @param factor - Interpolation factor (0.0 to 1.0).
+ * @returns Interpolated Hex color.
+ */
+export function interpolateColor(color1, color2, factor) {
+    const f = Math.max(0, Math.min(1, factor));
+    const c1 = hexToRgb(color1);
+    const c2 = hexToRgb(color2);
+    const r = c1.r + f * (c2.r - c1.r);
+    const g = c1.g + f * (c2.g - c1.g);
+    const b = c1.b + f * (c2.b - c1.b);
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+// -----------------
+// Style Resolution
+// -----------------
+const STYLE_CODES = {
+    default: "0",
+    bold: "1",
+    dim: "2",
+    italic: "3",
+    underline: "4",
+    inverse: "7",
+    hidden: "8",
+    strikethrough: "9",
+    black: "30",
+    red: "31",
+    green: "32",
+    yellow: "33",
+    blue: "34",
+    magenta: "35",
+    cyan: "36",
+    white: "37",
+    gray: "90",
+    grey: "90"
+};
+/**
+ * Resolves a single Style or array of Styles into an ANSI escape sequence.
+ * Handles hex colors, standard colors, and modifiers.
+ *
+ * @param style - The style or array of styles to resolve.
+ * @returns The resulting ANSI escape sequence string.
+ */
+export function resolveStyle(style) {
+    if (Array.isArray(style)) {
+        return style.map(resolveStyle).join("");
+    }
+    if (typeof style !== "string") {
+        return "";
+    }
+    // Check for hex color
+    if (style.startsWith("#")) {
+        try {
+            return hexToAnsi(style);
+        }
+        catch {
+            return ""; // Invalid hex, ignore
+        }
+    }
+    // Check for standard styles/colors
+    const code = STYLE_CODES[style.toLowerCase()];
+    if (code) {
+        return `${ESC}[${code}m`;
+    }
+    // Fallback: return as raw string if it looks like ANSI or just text
+    // Ideally we would validate ANSI here, but for flexibility we return it.
+    return style;
+}

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

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

package/dist/core/style.test.js

@@ -0,0 +1,53 @@
+import { expect, test, describe } from "bun:test";
+import { hexToRgb, rgbToAnsi, hexToAnsi, interpolateColor, resolveStyle } from "./style";
+describe("Color Utilities", () => {
+    test("hexToRgb converts correctly", () => {
+        expect(hexToRgb("#FFFFFF")).toEqual({ r: 255, g: 255, b: 255 });
+        expect(hexToRgb("#000000")).toEqual({ r: 0, g: 0, b: 0 });
+    });
+    test("hexToRgb throws on invalid hex", () => {
+        expect(() => hexToRgb("invalid")).toThrow("Invalid hex color.");
+        expect(() => hexToRgb("#FFF")).toThrow("Invalid hex color.");
+    });
+    test("rgbToAnsi converts correctly", () => {
+        expect(rgbToAnsi(255, 255, 255)).toBe("\x1b[38;2;255;255;255m");
+        expect(rgbToAnsi(0, 0, 0)).toBe("\x1b[38;2;0;0;0m");
+    });
+    test("hexToAnsi converts hex string directly to ANSI", () => {
+        expect(hexToAnsi("#FFFFFF")).toBe("\x1b[38;2;255;255;255m");
+        expect(hexToAnsi("#000000")).toBe("\x1b[38;2;0;0;0m");
+        expect(hexToAnsi("#FF0000")).toBe("\x1b[38;2;255;0;0m");
+    });
+    test("interpolateColor returns hex string", () => {
+        const start = "#000000";
+        const end = "#ffffff";
+        expect(interpolateColor(start, end, 0.5)).toBe("#808080");
+    });
+    test("interpolateColor clamps factors", () => {
+        expect(interpolateColor("#000000", "#ffffff", -1)).toBe("#000000");
+        expect(interpolateColor("#000000", "#ffffff", 2)).toBe("#ffffff");
+    });
+});
+describe("Style Resolution", () => {
+    test("resolveStyle handles standard colors", () => {
+        expect(resolveStyle("red")).toBe("\x1b[31m");
+        expect(resolveStyle("blue")).toBe("\x1b[34m");
+    });
+    test("resolveStyle handles modifiers", () => {
+        expect(resolveStyle("bold")).toBe("\x1b[1m");
+    });
+    test("resolveStyle handles hex colors", () => {
+        expect(resolveStyle("#FF0000")).toBe("\x1b[38;2;255;0;0m");
+    });
+    test("resolveStyle handles arrays of styles", () => {
+        expect(resolveStyle(["bold", "red"])).toBe("\x1b[1m\x1b[31m");
+    });
+    test("resolveStyle handles undefined style", () => {
+        expect(resolveStyle(undefined)).toBe("");
+    });
+    test("resolveStyle passes through raw strings", () => {
+        const raw = "\x1b[31m";
+        expect(resolveStyle(raw)).toBe(raw);
+        expect(resolveStyle("unknown")).toBe("unknown");
+    });
+});

package/dist/core/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Standard colors supported by most terminals.
+ */
+export type StandardColor = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "grey";
+/**
+ * Text style modifiers.
+ */
+export type StyleModifier = "bold" | "dim" | "italic" | "underline" | "default" | "hidden" | "inverse" | "strikethrough";
+/**
+ * A valid Hex color string (e.g., "#FF0000").
+ */
+export type HexColor = `#${string}`;
+/**
+ * A style can be a standard color name, a hex color string, or a style modifier.
+ * It can also be a raw ANSI string (though discouraged) for backward compatibility or special cases.
+ */
+export type Style = StandardColor | StyleModifier | HexColor | string;
+/**
+ * Represents a segment of text with applied styles.
+ */
+export interface StyledSegment {
+    /** The text content of the segment. */
+    text: string;
+    /** Style or array of styles to apply to the text. */
+    style?: Style | Style[];
+}
+/**
+ * Represents a line of text composed of multiple styled segments.
+ */
+export interface StyledLine {
+    /** Array of segments that make up the line. */
+    segments: StyledSegment[];
+}
+/**
+ * Configuration for the Printer engine.
+ */
+export interface PrinterOptions {
+    /** If true, the printer will overwrite previous lines instead of appending new ones. */
+    interactive?: boolean;
+    /** The default style to apply to padding or separators. */
+    defaultStyle?: Style | Style[];
+}

package/dist/core/types.js

@@ -0,0 +1,4 @@
+// -----------------
+// Style Types
+// -----------------
+export {};

package/dist/core/utils.d.ts

@@ -0,0 +1,25 @@
+import { Style, StyledLine } from "./types";
+/**
+ * Gets the plain text length of a StyledLine (ignoring ANSI codes).
+ *
+ * @param line - The StyledLine to measure.
+ * @returns The length of the text content.
+ */
+export declare function getLineLength(line: StyledLine): number;
+/**
+ * Computes the maximum width among an array of StyledLines.
+ * Useful for aligning columns.
+ *
+ * @param lines - Array of StyledLines.
+ * @returns The maximum line length found.
+ */
+export declare function computeMaxWidth(lines: StyledLine[]): number;
+/**
+ * Pads a StyledLine to a target width by adding an empty segment at the end.
+ *
+ * @param line - The line to pad.
+ * @param targetWidth - The desired minimum width.
+ * @param padStyle - The style to apply to the padding spaces.
+ * @returns A new StyledLine with padding added if necessary.
+ */
+export declare function padLine(line: StyledLine, targetWidth: number, padStyle: Style | Style[]): StyledLine;

package/dist/core/utils.js

@@ -0,0 +1,39 @@
+// -----------------
+// Line Manipulation Helpers
+// -----------------
+/**
+ * Gets the plain text length of a StyledLine (ignoring ANSI codes).
+ *
+ * @param line - The StyledLine to measure.
+ * @returns The length of the text content.
+ */
+export function getLineLength(line) {
+    return line.segments.reduce((acc, seg) => acc + seg.text.length, 0);
+}
+/**
+ * Computes the maximum width among an array of StyledLines.
+ * Useful for aligning columns.
+ *
+ * @param lines - Array of StyledLines.
+ * @returns The maximum line length found.
+ */
+export function computeMaxWidth(lines) {
+    return lines.length > 0 ? Math.max(...lines.map(getLineLength)) : 0;
+}
+/**
+ * Pads a StyledLine to a target width by adding an empty segment at the end.
+ *
+ * @param line - The line to pad.
+ * @param targetWidth - The desired minimum width.
+ * @param padStyle - The style to apply to the padding spaces.
+ * @returns A new StyledLine with padding added if necessary.
+ */
+export function padLine(line, targetWidth, padStyle) {
+    const currentLength = getLineLength(line);
+    if (currentLength < targetWidth) {
+        return {
+            segments: [...line.segments, { text: " ".repeat(targetWidth - currentLength), style: padStyle }]
+        };
+    }
+    return line;
+}

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

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

package/dist/core/utils.test.js

@@ -0,0 +1,25 @@
+import { expect, test, describe } from "bun:test";
+import { getLineLength, computeMaxWidth, padLine } from "./utils";
+const lineA = { segments: [{ text: "Hello", style: [] }] };
+const lineB = { segments: [{ text: "World!!", style: [] }] };
+describe("Line Utilities", () => {
+    test("getLineLength calculates correctly", () => {
+        expect(getLineLength(lineA)).toBe(5);
+        expect(getLineLength(lineB)).toBe(7);
+    });
+    test("computeMaxWidth finds the longest line", () => {
+        expect(computeMaxWidth([lineA, lineB])).toBe(7);
+        expect(computeMaxWidth([])).toBe(0);
+    });
+    test("padLine adds padding when needed", () => {
+        const padded = padLine(lineA, 10, "red");
+        expect(getLineLength(padded)).toBe(10);
+        expect(padded.segments[1].style).toBe("red");
+        expect(padded.segments[1].text).toBe("     ");
+    });
+    test("padLine does nothing if line is already wide enough", () => {
+        const ignored = padLine(lineB, 5, "red");
+        expect(getLineLength(ignored)).toBe(7);
+        expect(ignored.segments.length).toBe(1);
+    });
+});

package/dist/demo.d.ts

@@ -1,5 +1 @@
-/**
- * Run this demo to visually verify terminal output:
- * bun run src/demo.ts
- */
 export declare function runDemo(): Promise<void>;

package/dist/demo.js

@@ -1,11 +1,21 @@
-import { printDualColumn, getDragonLines, Printer, interpolateColor, createProgressBar } from "./index";
+import { printColumns, getDragonLines, Printer, interpolateColor, createProgressBar, Spinner, SPINNERS } from "./index";
 import pkg from "../package.json";
 /**
  * Run this demo to visually verify terminal output:
  * bun run src/demo.ts
  */
+function getProgressBarColor(factor) {
+    // Multi-stop gradient: Blue -> Cyan -> Green
+    if (factor < 0.5) {
+        return interpolateColor("#3B82F6", "#06B6D4", factor * 2);
+    }
+    else {
+        return interpolateColor("#06B6D4", "#10B981", (factor - 0.5) * 2);
+    }
+}
 export async function runDemo() {
     console.clear();
+    const staticPrinter = new Printer();
     // 1. Test Static Dual Column Print
     console.log("--- Static Dual Column Demo ---");
     const purple = "#A78BFA";
@@ -22,17 +32,23 @@ export async function runDemo() {
         { segments: [{ text: pkg.version, style: green }] },
         { segments: [{ text: "Testing live output...", style: yellow }] }
     ];
-    printDualColumn(leftContent, rightContent, { separator: "  =>  " });
+    printColumns([leftContent, rightContent], { separator: "  =>  " });
+    console.log("\n");
+    // 1b. Test 3-Column Print
+    console.log("--- Static 3-Column Demo ---");
+    const col1 = [{ segments: [{ text: "Column 1", style: "red" }] }];
+    const col2 = [{ segments: [{ text: "Column 2", style: "green" }] }];
+    const col3 = [{ segments: [{ text: "Column 3", style: "blue" }] }];
+    printColumns([col1, col2, col3], { separator: " | " });
     console.log("\n");
     // 2. Test the Dragon Gradient Preset
     console.log("--- Dragon Gradient Preset ---");
     const dragon = getDragonLines("#EF4444", "#FDE047");
-    const printer = new Printer();
-    printer.print(dragon);
+    staticPrinter.print(dragon);
     console.log("\n");
     // 3. Test Progress Bar
     console.log("--- Interactive Progress Bar Demo ---");
-    const interactivePrinter = new Printer({ interactive: true });
+    const interactiveProgressPrinter = new Printer({ interactive: true });
     const gray = "#4B5563";
     for (let i = 0; i <= 100; i += 2) {
         const progressColor = interpolateColor("#3B82F6", "#10B981", i / 100);
@@ -47,14 +63,106 @@ export async function runDemo() {
             emptyStyle: gray,
             percentageStyle: progressColor
         });
-        interactivePrinter.print([progressLine]);
-        await new Promise((resolve) => setTimeout(resolve, 20));
+        const factor = i / 100;
+        const gradientColor = getProgressBarColor(factor);
+        const gradientBar = createProgressBar({
+            progress: factor,
+            width: 40,
+            startChar: "▕",
+            endChar: "▏",
+            fillChar: "█",
+            emptyChar: "░",
+            startStyle: gradientColor,
+            endStyle: gradientColor,
+            fillStyle: gradientColor,
+            emptyStyle: "gray",
+            percentageStyle: ["bold", gradientColor]
+        });
+        const sharpBar = createProgressBar({
+            progress: factor,
+            width: 40,
+            startChar: "[",
+            endChar: "]",
+            fillChar: "#",
+            emptyChar: "-",
+            style: "white",
+            fillStyle: "green",
+            emptyStyle: "dim"
+        });
+        const noStyleBar = createProgressBar({
+            progress: factor,
+            width: 40,
+            startChar: "<",
+            endChar: ">",
+            fillChar: "=",
+            emptyChar: " "
+        });
+        interactiveProgressPrinter.print([
+            progressLine,
+            { segments: [] },
+            { segments: [{ text: "Gradient: ", style: "bold" }] },
+            gradientBar,
+            { segments: [] },
+            { segments: [{ text: "Sharp:    ", style: "bold" }] },
+            sharpBar,
+            { segments: [] },
+            { segments: [{ text: "Minimal:  ", style: "bold" }] },
+            noStyleBar
+        ]);
+        await new Promise((resolve) => setTimeout(resolve, 30));
+    }
+    console.log("\n");
+    // 4. Spinners Demo
+    console.log("--- Spinners Demo ---");
+    const spinnerDots = new Spinner({ frames: SPINNERS.dots, interval: 80 });
+    const spinnerLines = new Spinner({ frames: SPINNERS.lines, interval: 100 });
+    const spinnerArrows = new Spinner({ frames: SPINNERS.arrows, interval: 120 });
+    const spinnerCircle = new Spinner({ frames: SPINNERS.circle, interval: 150 });
+    const spinnerSquare = new Spinner({ frames: SPINNERS.square, interval: 200 });
+    const interactiveSpinnerPrinter = new Printer({ interactive: true });
+    const startTime = Date.now();
+    while (Date.now() - startTime < 3000) {
+        const lines = [
+            {
+                segments: [
+                    { text: "Dots:   ", style: "dim" },
+                    { text: spinnerDots.getFrame(), style: "cyan" }
+                ]
+            },
+            {
+                segments: [
+                    { text: "Lines:  ", style: "dim" },
+                    { text: spinnerLines.getFrame(), style: "yellow" }
+                ]
+            },
+            {
+                segments: [
+                    { text: "Arrows: ", style: "dim" },
+                    { text: spinnerArrows.getFrame(), style: "green" }
+                ]
+            },
+            {
+                segments: [
+                    { text: "Circle: ", style: "dim" },
+                    { text: spinnerCircle.getFrame(), style: "magenta" }
+                ]
+            },
+            {
+                segments: [
+                    { text: "Square: ", style: "dim" },
+                    { text: spinnerSquare.getFrame(), style: "blue" }
+                ]
+            }
+        ];
+        interactiveSpinnerPrinter.print(lines);
+        await new Promise((resolve) => setTimeout(resolve, 50));
     }
     console.log("\n");
-    // 4. Style Codes Demo
+    // 5. Style Codes Demo
     console.log("--- Style Codes Demo ---");
     const styles = [
-        { name: "Default", style: "default" },
+        { name: "Default", style: undefined },
+        { name: "Bold + Red", style: ["bold", "red"] },
         { name: "Bold", style: "bold" },
         { name: "Dim", style: "dim" },
         { name: "Italic", style: "italic" },
@@ -73,12 +181,8 @@ export async function runDemo() {
         { name: "Gray", style: "gray" }
     ];
     const styleLines = styles.map((s) => ({
-        segments: [
-            { text: s.name.padEnd(15), style: "default" },
-            { text: "Sample Text", style: s.style }
-        ]
+        segments: [{ text: s.name.padEnd(15) }, { text: "Sample Text", style: s.style }]
     }));
-    const stylePrinter = new Printer();
-    stylePrinter.print(styleLines);
+    staticPrinter.print(styleLines);
     console.log("\n✨ Demo Complete!");
 }