@heinrichb/console-toolkit 1.0.3 → 1.0.5

package/dist/index.d.ts

@@ -1,99 +1,8 @@
-/**
- * Core types for styled console output.
- */
-export type StandardColor = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "grey";
-export type StyleModifier = "bold" | "dim" | "italic" | "underline" | "reset" | "default" | "hidden" | "inverse" | "strikethrough";
-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;
-export interface StyledSegment {
-    text: string;
-    /** Style or array of styles to apply to the text */
-    style: Style | Style[];
-}
-export interface StyledLine {
-    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[];
-}
-export declare const RESET = "\u001B[0m";
-/**
- * Converts a hex color string to an RGB object.
- * @param hex - Hex color in the form "#RRGGBB".
- */
-export declare function hexToRgb(hex: string): {
-    r: number;
-    g: number;
-    b: number;
-};
-/**
- * Converts RGB to a 24-bit ANSI foreground color escape sequence.
- */
-export declare function rgbToAnsi(r: number, g: number, b: number): string;
-/**
- * Converts a hex color string directly to an ANSI escape sequence.
- */
-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.
- */
-export declare function interpolateColor(color1: string, color2: string, factor: number): HexColor;
-/**
- * Resolves a single Style or array of Styles into an ANSI escape sequence.
- */
-export declare function resolveStyle(style: Style | Style[]): string;
-/**
- * Gets the plain text length of a StyledLine.
- */
-export declare function getLineLength(line: StyledLine): number;
-/**
- * Computes the maximum width among an array of StyledLines.
- */
-export declare function computeMaxWidth(lines: StyledLine[]): number;
-/**
- * Pads a StyledLine to a target width by adding an empty segment at the end.
- */
-export declare function padLine(line: StyledLine, targetWidth: number, padStyle: Style | Style[]): StyledLine;
-/**
- * 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.
-     */
-    print(lines: StyledLine[]): void;
-}
-/**
- * Merges two columns of StyledLines into a single layout.
- */
-export declare function mergeColumns(leftColumn: StyledLine[], rightColumn: StyledLine[], leftWidth: number, separator: string, defaultStyle: Style | Style[]): StyledLine[];
-/**
- * Prints two columns of styled content to the console.
- */
-export declare function printDualColumn(left: StyledLine[], right: StyledLine[], options?: {
-    leftWidth?: number;
-    separator?: string;
-    printer?: Printer;
-}): void;
-/**
- * Returns the classic Dragon ASCII art as StyledLines with a vertical color gradient.
- */
-export declare function getDragonLines(startColor?: string, endColor?: string): StyledLine[];
-export * from "./progress";
+export * from "./core/types";
+export * from "./core/style";
+export * from "./core/utils";
+export * from "./core/printer";
+export * from "./core/layout";
+export * from "./components/progress";
+export * from "./components/spinner";
+export * from "./presets/ascii";

package/dist/index.js

@@ -1,234 +1,14 @@
-/**
- * Core types for styled console output.
- */
-// -----------------
-// Color Utilities
-// -----------------
-const ESC = "\x1b";
-export const RESET = `${ESC}[0m`;
-/**
- * Converts a hex color string to an RGB object.
- * @param hex - Hex color in the form "#RRGGBB".
- */
-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.
- */
-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.
- */
-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.
- */
-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.
- */
-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 = {
-    reset: "0",
-    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.
- */
-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;
-}
-// -----------------
-// Line Manipulation Helpers
-// -----------------
-/**
- * Gets the plain text length of a StyledLine.
- */
-export function getLineLength(line) {
-    return line.segments.reduce((acc, seg) => acc + seg.text.length, 0);
-}
-/**
- * Computes the maximum width among an array of StyledLines.
- */
-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.
- */
-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;
-}
-// -----------------
-// 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.
-     */
-    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;
-    }
-}
-// -----------------
-// Core Layout & Printing
-// -----------------
-const defaultPrinter = new Printer();
-/**
- * Merges two columns of StyledLines into a single layout.
- */
-export function mergeColumns(leftColumn, rightColumn, leftWidth, separator, defaultStyle) {
-    const maxLines = Math.max(leftColumn.length, rightColumn.length);
-    const output = [];
-    for (let i = 0; i < maxLines; i++) {
-        const left = padLine(leftColumn[i] || { segments: [] }, leftWidth, defaultStyle);
-        const right = rightColumn[i] || { segments: [] };
-        output.push({
-            segments: [...left.segments, { text: separator, style: defaultStyle }, ...right.segments]
-        });
-    }
-    return output;
-}
-/**
- * Prints two columns of styled content to the console.
- */
-export function printDualColumn(left, right, options = {}) {
-    const { leftWidth, separator = "     ", printer = defaultPrinter } = options;
-    const defaultStyle = RESET;
-    const finalLeftWidth = leftWidth ?? computeMaxWidth(left);
-    const mergedLines = mergeColumns(left, right, finalLeftWidth, separator, defaultStyle);
-    printer.print(mergedLines);
-}
-// -----------------
-// Presets
-// -----------------
-/**
- * Returns the classic Dragon ASCII art as StyledLines with a vertical color gradient.
- */
-export function getDragonLines(startColor = "#EF4444", endColor = "#F59E0B") {
-    const rawDragon = [
-        "                ^    ^",
-        "               / \\  //\\",
-        " |\\___/|      /   \\//  .\\",
-        " /O  O  \\__  /    //  | \\ \\",
-        "/     /  \\_/_/    //   |  \\  \\",
-        "@___@'    \\_//   //    |   \\   \\ ",
-        "   |       \\_// //     |    \\    \\ ",
-        "   |        \\///      |     \\     \\ ",
-        "  _|_ /   )  //       |      \\     _\\",
-        " '/,_ _ _/  ( ; -.    |    _ _\\.-~        .-~~~^-.",
-        " ,-{        _      `-.|.-~-.           .~         `.",
-        "  '/\\      /                 ~-. _ .-~      .-~^-.  \\",
-        "     `.   {            }                   /      \\  \\",
-        "   .----~-\\.        \\-'                 .~         \\  `. \\^-.",
-        "  ///.----..>    c   \\             _ -~             `.  ^-`   ^-_",
-        "    ///-._ _ _ _ _ _ _}^ - - - - ~                     ~--,   .-~",
-        "                                                          /.-'"
-    ];
-    return rawDragon.map((text, i) => {
-        const factor = rawDragon.length <= 1 ? 0 : i / (rawDragon.length - 1);
-        const colorStyle = interpolateColor(startColor, endColor, factor);
-        return { segments: [{ text, style: colorStyle }] };
-    });
-}
-// -----------------
-// Progress Bar
-// -----------------
-export * from "./progress";
+// Export Core Types
+export * from "./core/types";
+// Export Core Utilities
+export * from "./core/style";
+export * from "./core/utils";
+// Export Printer Engine
+export * from "./core/printer";
+// Export Layout Helpers
+export * from "./core/layout";
+// Export Components
+export * from "./components/progress";
+export * from "./components/spinner";
+// Export Presets
+export * from "./presets/ascii";

package/dist/index.test.js

@@ -1,5 +1,5 @@
 import { expect, test, describe, spyOn, afterEach } from "bun:test";
-import { hexToRgb, rgbToAnsi, hexToAnsi, interpolateColor, getLineLength, computeMaxWidth, padLine, Printer, printDualColumn, getDragonLines, mergeColumns, resolveStyle } from "./index";
+import { hexToRgb, rgbToAnsi, hexToAnsi, interpolateColor, getLineLength, computeMaxWidth, padLine, Printer, printColumns, getDragonLines, mergeMultipleColumns, resolveStyle } from "./index";
 const lineA = { segments: [{ text: "Hello", style: [] }] };
 const lineB = { segments: [{ text: "World!!", style: [] }] };
 describe("Color Utilities", () => {
@@ -37,7 +37,6 @@ describe("Style Resolution", () => {
     });
     test("resolveStyle handles modifiers", () => {
         expect(resolveStyle("bold")).toBe("\x1b[1m");
-        expect(resolveStyle("reset")).toBe("\x1b[0m");
     });
     test("resolveStyle handles hex colors", () => {
         expect(resolveStyle("#FF0000")).toBe("\x1b[38;2;255;0;0m");
@@ -45,6 +44,9 @@ describe("Style Resolution", () => {
     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);
@@ -71,8 +73,8 @@ describe("Line Utilities", () => {
         expect(getLineLength(ignored)).toBe(7);
         expect(ignored.segments.length).toBe(1);
     });
-    test("mergeColumns handles asymmetric column lengths", () => {
-        const merged = mergeColumns([lineA], [lineB, lineB], 10, " | ", "");
+    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);
     });
@@ -110,8 +112,26 @@ describe("Printer & Layout", () => {
         const callArg = stdoutSpy.mock.calls[0][0];
         expect(callArg.startsWith(expectedClear)).toBe(true);
     });
-    test("printDualColumn executes correctly", () => {
-        printDualColumn([lineA], [lineB]);
+    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");

package/dist/presets/ascii.d.ts

@@ -0,0 +1,5 @@
+import { StyledLine } from "../core/types";
+/**
+ * Returns the classic Dragon ASCII art as StyledLines with a vertical color gradient.
+ */
+export declare function getDragonLines(startColor?: string, endColor?: string): StyledLine[];

package/dist/presets/ascii.js

@@ -0,0 +1,33 @@
+import { interpolateColor } from "../core/style";
+// -----------------
+// Presets
+// -----------------
+/**
+ * Returns the classic Dragon ASCII art as StyledLines with a vertical color gradient.
+ */
+export function getDragonLines(startColor = "#EF4444", endColor = "#F59E0B") {
+    const rawDragon = [
+        "                ^    ^",
+        "               / \\  //\\",
+        " |\\___/|      /   \\//  .\\",
+        " /O  O  \\__  /    //  | \\ \\",
+        "/     /  \\_/_/    //   |  \\  \\",
+        "@___@'    \\_//   //    |   \\   \\ ",
+        "   |       \\_// //     |    \\    \\ ",
+        "   |        \\///      |     \\     \\ ",
+        "  _|_ /   )  //       |      \\     _\\",
+        " '/,_ _ _/  ( ; -.    |    _ _\\.-~        .-~~~^-.",
+        " ,-{        _      `-.|.-~-.           .~         `.",
+        "  '/\\      /                 ~-. _ .-~      .-~^-.  \\",
+        "     `.   {            }                   /      \\  \\",
+        "   .----~-\\.        \\-'                 .~         \\  `. \\^-.",
+        "  ///.----..>    c   \\             _ -~             `.  ^-`   ^-_",
+        "    ///-._ _ _ _ _ _ _}^ - - - - ~                     ~--,   .-~",
+        "                                                          /.-'"
+    ];
+    return rawDragon.map((text, i) => {
+        const factor = rawDragon.length <= 1 ? 0 : i / (rawDragon.length - 1);
+        const colorStyle = interpolateColor(startColor, endColor, factor);
+        return { segments: [{ text, style: colorStyle }] };
+    });
+}

package/dist/presets/ascii.test.d.ts

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

package/dist/presets/ascii.test.js

@@ -0,0 +1,10 @@
+import { expect, test, describe } from "bun:test";
+import { getDragonLines } from "./ascii";
+describe("Presets", () => {
+    test("getDragonLines returns valid array", () => {
+        const lines = getDragonLines();
+        expect(lines.length).toBeGreaterThan(0);
+        const firstSegmentStyle = lines[0].segments[0].style;
+        expect(firstSegmentStyle.startsWith("#")).toBe(true);
+    });
+});

package/dist/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/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/spinner.test.d.ts

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

package/dist/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heinrichb/console-toolkit",
-	"version": "1.0.3",
+	"version": "1.0.5",
 	"description": "A versatile TypeScript utility library for enhanced console logging, formatting, and layout management.",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -33,12 +33,14 @@
 		"useTabs": true
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.0.0",
-		"@types/bun": "latest",
-		"eslint": "^9.0.0",
+		"@eslint/js": "^10.0.1",
+		"@types/bun": "^1.3.9",
+		"eslint": "^10.0.2",
 		"eslint-config-prettier": "^10.1.8",
-		"prettier": "^3.5.3",
-		"typescript": "^5",
+		"globals": "^17.3.0",
+		"jiti": "^2.6.1",
+		"prettier": "^3.8.1",
+		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.56.1"
 	}
 }