@heinrichb/console-toolkit 1.0.3 → 1.0.6

package/dist/core/utils.d.ts

@@ -0,0 +1,25 @@
+import { PrintLine, PrintStyle } from "./types";
+/**
+ * Gets the plain text length of a PrintLine (ignoring ANSI codes).
+ *
+ * @param line - The PrintLine to measure.
+ * @returns The length of the text content.
+ */
+export declare function getLineLength(line: PrintLine): number;
+/**
+ * Computes the maximum width among an array of PrintLines.
+ * Useful for aligning columns.
+ *
+ * @param lines - Array of PrintLines.
+ * @returns The maximum line length found.
+ */
+export declare function computeMaxWidth(lines: PrintLine[]): number;
+/**
+ * Pads a PrintLine 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 PrintLine with padding added if necessary.
+ */
+export declare function padLine(line: PrintLine, targetWidth: number, padStyle?: PrintStyle): PrintLine;

package/dist/core/utils.js

@@ -0,0 +1,36 @@
+/**
+ * Gets the plain text length of a PrintLine (ignoring ANSI codes).
+ *
+ * @param line - The PrintLine 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 PrintLines.
+ * Useful for aligning columns.
+ *
+ * @param lines - Array of PrintLines.
+ * @returns The maximum line length found.
+ */
+export function computeMaxWidth(lines) {
+    return lines.length > 0 ? Math.max(...lines.map(getLineLength)) : 0;
+}
+/**
+ * Pads a PrintLine 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 PrintLine 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, { color: "red" });
+        expect(getLineLength(padded)).toBe(10);
+        expect(padded.segments[1].style).toEqual({ color: "red" });
+        expect(padded.segments[1].text).toBe("     ");
+    });
+    test("padLine does nothing if line is already wide enough", () => {
+        const ignored = padLine(lineB, 5, { color: "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,17 +1,27 @@
-import { printDualColumn, getDragonLines, Printer, interpolateColor, createProgressBar } from "./index";
+import { printColumns, getDragon, 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();
-    // 1. Test Static Dual Column Print
+    const staticPrinter = new Printer();
+    // 1. Static Dual Column Print
     console.log("--- Static Dual Column Demo ---");
-    const purple = "#A78BFA";
-    const blue = "#60A5FA";
-    const green = "#34D399";
-    const yellow = "#FBBF24";
+    const purple = { color: "#A78BFA" };
+    const blue = { color: "#60A5FA" };
+    const green = { color: "#34D399" };
+    const yellow = { color: "#FBBF24" };
     const leftContent = [
         { segments: [{ text: "Package:", style: purple }] },
         { segments: [{ text: "Version:", style: purple }] },
@@ -22,22 +32,34 @@ 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");
+    // 2. Block Vertical Gradient Demo
+    console.log("--- Block Vertical Gradient Demo ---");
+    const gradientBlockLines = Array.from({ length: 10 }, (_, i) => ({
+        segments: [{ text: `Line ${i + 1} - Inherits Gradient` }]
+    }));
+    staticPrinter.print({
+        style: { color: ["#EF4444", "#3B82F6"] },
+        lines: gradientBlockLines
+    });
     console.log("\n");
-    // 2. Test the Dragon Gradient Preset
+    // 3. Dragon Gradient Preset
     console.log("--- Dragon Gradient Preset ---");
-    const dragon = getDragonLines("#EF4444", "#FDE047");
-    const printer = new Printer();
-    printer.print(dragon);
+    const dragon = getDragon("#EF4444", "#FDE047");
+    staticPrinter.print({ lines: dragon });
     console.log("\n");
-    // 3. Test Progress Bar
-    console.log("--- Interactive Progress Bar Demo ---");
-    const interactivePrinter = new Printer({ interactive: true });
-    const gray = "#4B5563";
+    // 4. Interactive Progress Bar Demo
+    console.log("--- Live Progress Bar Demo ---");
+    const livePrinter = new Printer({ live: true });
+    const gray = { color: "#4B5563" };
     for (let i = 0; i <= 100; i += 2) {
-        const progressColor = interpolateColor("#3B82F6", "#10B981", i / 100);
+        const factor = i / 100;
+        const progressColorHex = interpolateColor("#3B82F6", "#10B981", factor);
+        const progressColor = { color: progressColorHex };
+        // Standard Bar
         const progressLine = createProgressBar({
-            progress: i / 100,
+            progress: factor,
             width: 30,
             startChar: "[",
             endChar: "]",
@@ -47,38 +69,77 @@ export async function runDemo() {
             emptyStyle: gray,
             percentageStyle: progressColor
         });
-        interactivePrinter.print([progressLine]);
-        await new Promise((resolve) => setTimeout(resolve, 20));
+        // Gradient Bar
+        const gradientHex = getProgressBarColor(factor);
+        const gradientStyle = { color: gradientHex };
+        const complexGradientBar = createProgressBar({
+            progress: factor,
+            width: 40,
+            startChar: "▕",
+            endChar: "▏",
+            fillChar: "█",
+            emptyChar: "░",
+            startStyle: gradientStyle,
+            endStyle: gradientStyle,
+            fillStyle: { color: ["#3B82F6", "#EC4899"] },
+            emptyStyle: { color: "gray" },
+            percentageStyle: { modifiers: ["bold"], color: gradientHex }
+        });
+        livePrinter.print({
+            lines: [
+                progressLine,
+                { segments: [] },
+                { segments: [{ text: "Horizontal Gradient on Bar Segment:", style: { modifiers: ["bold"] } }] },
+                complexGradientBar
+            ]
+        });
+        await new Promise((resolve) => setTimeout(resolve, 30));
+    }
+    console.log("\n");
+    // 5. Spinners Demo
+    console.log("--- Spinners Demo ---");
+    const spinnerTypes = Object.keys(SPINNERS);
+    const spinners = spinnerTypes.map((type) => ({
+        type,
+        instance: new Spinner({ frames: SPINNERS[type], interval: 80 })
+    }));
+    const spinnerPrinter = new Printer({ live: true });
+    const spinnerStart = Date.now();
+    while (Date.now() - spinnerStart < 3000) {
+        const lines = spinners.map((s) => ({
+            segments: [
+                { text: `${s.type.charAt(0).toUpperCase() + s.type.slice(1)}:`.padEnd(10), style: { modifiers: ["dim"] } },
+                { text: s.instance.getFrame(), style: { color: "cyan" } }
+            ]
+        }));
+        spinnerPrinter.print({ lines });
+        await new Promise((resolve) => setTimeout(resolve, 50));
     }
     console.log("\n");
-    // 4. Style Codes Demo
+    // 6. 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" }
+        { name: "Default" },
+        { name: "Bold + Red", style: { modifiers: ["bold"], color: "red" } },
+        { name: "Bold", style: { modifiers: ["bold"] } },
+        { name: "Dim", style: { modifiers: ["dim"] } },
+        { name: "Italic", style: { modifiers: ["italic"] } },
+        { name: "Underline", style: { modifiers: ["underline"] } },
+        { name: "Strikethrough", style: { modifiers: ["strikethrough"] } },
+        { name: "Inverse", style: { modifiers: ["inverse"] } },
+        { name: "Hidden", style: { modifiers: ["hidden"] } },
+        { name: "Red", style: { color: "red" } },
+        { name: "Green", style: { color: "green" } },
+        { name: "Yellow", style: { color: "yellow" } },
+        { name: "Blue", style: { color: "blue" } },
+        { name: "Magenta", style: { color: "magenta" } },
+        { name: "Cyan", style: { color: "cyan" } },
+        { name: "White", style: { color: "white" } },
+        { name: "Gray", style: { color: "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(20) }, { text: "Sample Text", style: s.style }]
     }));
-    const stylePrinter = new Printer();
-    stylePrinter.print(styleLines);
+    staticPrinter.print({ lines: styleLines });
     console.log("\n✨ Demo Complete!");
 }

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/presets/ascii.d.ts

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