@heinrichb/console-toolkit 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brennen Heinrich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,2 @@
+# console-toolkit
+A versatile TypeScript utility library for enhanced console logging, formatting, and layout management.

package/dist/demo.d.ts

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

package/dist/demo.js

@@ -0,0 +1,84 @@
+import { printDualColumn, getDragonLines, Printer, interpolateColor, createProgressBar } from "./index";
+import pkg from "../package.json";
+/**
+ * Run this demo to visually verify terminal output:
+ * bun run src/demo.ts
+ */
+export async function runDemo() {
+    console.clear();
+    // 1. Test Static Dual Column Print
+    console.log("--- Static Dual Column Demo ---");
+    const purple = "#A78BFA";
+    const blue = "#60A5FA";
+    const green = "#34D399";
+    const yellow = "#FBBF24";
+    const leftContent = [
+        { segments: [{ text: "Package:", style: purple }] },
+        { segments: [{ text: "Version:", style: purple }] },
+        { segments: [{ text: "Status:", style: purple }] }
+    ];
+    const rightContent = [
+        { segments: [{ text: pkg.name, style: blue }] },
+        { segments: [{ text: pkg.version, style: green }] },
+        { segments: [{ text: "Testing live output...", style: yellow }] }
+    ];
+    printDualColumn(leftContent, rightContent, { 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);
+    console.log("\n");
+    // 3. Test Progress Bar
+    console.log("--- Interactive Progress Bar Demo ---");
+    const interactivePrinter = new Printer({ interactive: true });
+    const gray = "#4B5563";
+    for (let i = 0; i <= 100; i += 2) {
+        const progressColor = interpolateColor("#3B82F6", "#10B981", i / 100);
+        const progressLine = createProgressBar({
+            progress: i / 100,
+            width: 30,
+            startChar: "[",
+            endChar: "]",
+            startStyle: progressColor,
+            endStyle: progressColor,
+            fillStyle: progressColor,
+            emptyStyle: gray,
+            percentageStyle: progressColor
+        });
+        interactivePrinter.print([progressLine]);
+        await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    console.log("\n");
+    // 4. Style Codes Demo
+    console.log("--- Style Codes Demo ---");
+    const styles = [
+        { name: "Default", style: "default" },
+        { name: "Bold", style: "bold" },
+        { name: "Dim", style: "dim" },
+        { name: "Italic", style: "italic" },
+        { name: "Underline", style: "underline" },
+        { name: "Strikethrough", style: "strikethrough" },
+        { name: "Inverse", style: "inverse" },
+        { name: "Hidden", style: "hidden" },
+        { name: "Black", style: "black" },
+        { name: "Red", style: "red" },
+        { name: "Green", style: "green" },
+        { name: "Yellow", style: "yellow" },
+        { name: "Blue", style: "blue" },
+        { name: "Magenta", style: "magenta" },
+        { name: "Cyan", style: "cyan" },
+        { name: "White", style: "white" },
+        { name: "Gray", style: "gray" }
+    ];
+    const styleLines = styles.map((s) => ({
+        segments: [
+            { text: s.name.padEnd(15), style: "default" },
+            { text: "Sample Text", style: s.style }
+        ]
+    }));
+    const stylePrinter = new Printer();
+    stylePrinter.print(styleLines);
+    console.log("\n✨ Demo Complete!");
+}

package/dist/demo.test.d.ts

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

package/dist/demo.test.js

@@ -0,0 +1,28 @@
+import { expect, test, describe, spyOn, afterEach, beforeEach } from "bun:test";
+import { runDemo } from "./demo";
+describe("Demo Script", () => {
+    const logSpy = spyOn(console, "log").mockImplementation(() => undefined);
+    const clearSpy = spyOn(console, "clear").mockImplementation(() => undefined);
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true);
+    const originalTimeout = global.setTimeout;
+    beforeEach(() => {
+        // Mocking setTimeout requires unknown casting due to return type mismatch in Bun (void vs Timer)
+        global.setTimeout = ((fn) => {
+            fn();
+        });
+    });
+    afterEach(() => {
+        logSpy.mockClear();
+        clearSpy.mockClear();
+        stdoutSpy.mockClear();
+        global.setTimeout = originalTimeout;
+    });
+    test("runDemo executes correctly", async () => {
+        // Just await the function call; we expect it not to throw.
+        await runDemo();
+        expect(clearSpy).toHaveBeenCalled();
+        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("Static Dual Column Demo"));
+        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("Demo Complete!"));
+        expect(stdoutSpy).toHaveBeenCalled();
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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";

package/dist/index.js

@@ -0,0 +1,234 @@
+/**
+ * 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";

package/dist/index.test.d.ts

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

package/dist/index.test.js

@@ -0,0 +1,123 @@
+import { expect, test, describe, spyOn, afterEach } from "bun:test";
+import { hexToRgb, rgbToAnsi, hexToAnsi, interpolateColor, getLineLength, computeMaxWidth, padLine, Printer, printDualColumn, getDragonLines, mergeColumns, resolveStyle } from "./index";
+const lineA = { segments: [{ text: "Hello", style: [] }] };
+const lineB = { segments: [{ text: "World!!", 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");
+        expect(resolveStyle("reset")).toBe("\x1b[0m");
+    });
+    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 passes through raw strings", () => {
+        const raw = "\x1b[31m";
+        expect(resolveStyle(raw)).toBe(raw);
+        expect(resolveStyle("unknown")).toBe("unknown");
+    });
+});
+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);
+    });
+    test("mergeColumns handles asymmetric column lengths", () => {
+        const merged = mergeColumns([lineA], [lineB, lineB], 10, " | ", "");
+        expect(merged.length).toBe(2);
+        expect(getLineLength(merged[1])).toBe(10 + 3 + 7);
+    });
+});
+describe("Printer & Layout", () => {
+    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);
+    });
+    test("printDualColumn executes correctly", () => {
+        printDualColumn([lineA], [lineB]);
+        expect(stdoutSpy).toHaveBeenCalled();
+    });
+    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/progress.d.ts

@@ -0,0 +1,75 @@
+import { StyledLine, Style } from "./index";
+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/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/progress.test.d.ts

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

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

@@ -0,0 +1,44 @@
+{
+	"name": "@heinrichb/console-toolkit",
+	"version": "1.0.1",
+	"description": "A versatile TypeScript utility library for enhanced console logging, formatting, and layout management.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"demo": "bun run scripts/run-demo.ts",
+		"test": "bun run build && bun test src",
+		"test:coverage": "bun run build && bun test src --coverage --coverage-threshold=100",
+		"build": "bun x tsc",
+		"publish": "npm publish",
+		"format:check": "prettier --check \"src/**/*.{ts,json,md}\"",
+		"format:write": "prettier --write \"src/**/*.{ts,json,md}\"",
+		"lint": "eslint \"src/**/*.ts\"",
+		"tree": "tree -a -I '.git|node_modules|dist'"
+	},
+	"prettier": {
+		"printWidth": 128,
+		"tabWidth": 2,
+		"trailingComma": "none",
+		"bracketSameLine": true,
+		"semi": true,
+		"singleQuote": false,
+		"useTabs": true
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.0.0",
+		"@types/bun": "latest",
+		"eslint": "^9.0.0",
+		"eslint-config-prettier": "^10.1.8",
+		"prettier": "^3.5.3",
+		"typescript": "^5",
+		"typescript-eslint": "^8.56.1"
+	}
+}