@heinrichb/console-toolkit 1.0.10 → 1.0.13

package/README.md

@@ -1,162 +1,320 @@
-# 🎨 Console Toolkit
-
-**@heinrichb/console-toolkit** is a powerful, lightweight TypeScript library for creating beautiful, interactive, and structured command-line interfaces. From simple colored text to complex multi-column layouts and live-updating progress bars, this toolkit has everything you need to elevate your CLI experience.
-
----
-
-## 🚀 Features
-
-- **🌈 Rich Styling:** Support for standard ANSI colors, true-color Hex codes, and text modifiers (bold, dim, italic, etc.).
-- **✨ Gradients:** Easy-to-use linear gradients for text and backgrounds.
-- **live-updating:** Built-in support for live-updating displays (perfect for spinners and progress bars).
-- **📐 Flexible Layouts:** powerful grid system for multi-column layouts with automatic padding and alignment.
-- **🧩 Components:** Pre-built, customizable components like **Progress Bars** and **Spinners**.
-- **🐉 Presets:** Fun ASCII art presets (like dragons!) to spice up your output.
-- **TypeScript First:** Fully typed for a great developer experience.
-
----
-
-## 📦 Installation
-
-This library is designed for use with **Bun** or **Node.js**.
-
-```bash
-bun add @heinrichb/console-toolkit
-# or
-npm install @heinrichb/console-toolkit
-```
-
----
-
-## ⚡ Quick Start
-
-Get up and running in seconds:
-
-```typescript
-import { Printer } from "@heinrichb/console-toolkit";
-
-const printer = new Printer();
-
-printer.print({
-	lines: [
-		{
-			segments: [
-				{ text: "Hello, ", style: { color: "blue", modifiers: ["bold"] } },
-				{ text: "World!", style: { color: "#10B981", modifiers: ["italic"] } } // Hex color support!
-			]
-		}
-	]
-});
-```
-
----
-
-## 🎨 Styling
-
-We support a flexible styling system that works with both standard terminal colors and full RGB Hex codes.
-
-### Basic Colors & Modifiers
-
-```typescript
-import { PrintStyle } from "@heinrichb/console-toolkit";
-
-const myStyle: PrintStyle = {
-	color: "red", // Standard color
-	modifiers: ["bold", "underline"]
-};
-```
-
-### Hex Colors & Gradients
-
-You can use any hex color string. For gradients, simply provide an array of colors!
-
-```typescript
-const gradientStyle: PrintStyle = {
-	// Creates a gradient from Red to Blue
-	color: ["#EF4444", "#3B82F6"]
-};
-```
-
----
-
-## 📐 Layouts
-
-Creating multi-column layouts is a breeze.
-
-```typescript
-import { printColumns } from "@heinrichb/console-toolkit";
-
-printColumns(
-	[
-		[
-			// Column 1
-			{ segments: [{ text: "Item 1" }] },
-			{ segments: [{ text: "Item 2" }] }
-		],
-		[
-			// Column 2
-			{ segments: [{ text: "Description 1", style: { color: "gray" } }] },
-			{ segments: [{ text: "Description 2", style: { color: "gray" } }] }
-		]
-	],
-	{ separator: " | " }
-);
-```
-
----
-
-## 🧩 Components
-
-### Progress Bars
-
-Create customizable progress bars with ease.
-
-```typescript
-import { createProgressBar, Printer } from "@heinrichb/console-toolkit";
-
-const printer = new Printer({ live: true });
-const bar = createProgressBar({
-	progress: 0.75,
-	width: 30,
-	fillStyle: { color: "green" },
-	emptyStyle: { color: "gray" }
-});
-
-printer.print({ lines: [bar] });
-```
-
-### Spinners
-
-Add activity indicators to your long-running tasks.
-
-```typescript
-import { Spinner, SPINNERS, Printer } from "@heinrichb/console-toolkit";
-
-const spinner = new Spinner({ frames: SPINNERS.dots });
-const printer = new Printer({ live: true });
-
-// In your loop:
-printer.print({
-	lines: [
-		{
-			segments: [{ text: spinner.getFrame(), style: { color: "cyan" } }]
-		}
-	]
-});
-```
-
----
-
-## 📚 Detailed Documentation
-
-For more in-depth information on specific parts of the library, check out the detailed guides below:
-
-- **[Core Engine & Styling](src/core/README.md):** Deep dive into `Printer`, `PrintBlock`, `PrintStyle`, and advanced layout techniques.
-- **[Components](src/components/README.md):** Full API reference for `ProgressBar`, `Spinner`, and how to build your own components.
-- **[Presets](src/presets/README.md):** Explore available ASCII art and other presets.
-
----
-
-## 📄 License
-
-MIT © Brennen Heinrich
+# 🎨 Console Toolkit
+
+**@heinrichb/console-toolkit** — zero-dependency TypeScript library for beautiful console output. True-color gradients, background colors, column layouts, tables, progress bars, spinners, and ASCII art — all fully typed, all composable.
+
+---
+
+## 🚀 Features
+
+- **🌈 True-Color Styling:** Standard ANSI colors, hex RGB codes, background colors, and text modifiers (bold, dim, italic, etc.).
+- **✨ Gradients:** Horizontal (per-character) and vertical (per-line) gradients with multi-stop support. Includes preset palettes.
+- **📊 Tables:** Styled tables with automatic column sizing, four border styles, and per-section styling.
+- **📈 Live Updates:** Built-in live mode for smooth animations — spinners, progress bars, dashboards.
+- **📐 Column Layouts:** Multi-column grid system with automatic padding, fixed widths, and custom separators.
+- **🧩 Components:** Progress bars (17 options) and spinners (5 presets) ready to use.
+- **🐉 ASCII Presets:** Dragon art with customizable multi-stop gradient colors.
+- **🔧 Utilities:** `renderToString` for capturing output and `stripAnsi` for plain text extraction.
+- **TypeScript First:** Fully typed, zero dependencies, works with Bun and Node.js 18+.
+
+---
+
+## 📦 Installation
+
+```bash
+bun add @heinrichb/console-toolkit
+# or
+npm install @heinrichb/console-toolkit
+```
+
+---
+
+## 🎮 Try the Demo
+
+See every feature in action:
+
+```bash
+git clone https://github.com/heinrichb/console-toolkit.git
+cd console-toolkit && bun install
+bun run demo
+```
+
+---
+
+## ⚡ Quick Start
+
+Build output with three functions: `segment` (text + style), `line` (row of segments), `block` (group of lines).
+
+```typescript
+import { Printer, segment, line, block } from "@heinrichb/console-toolkit";
+
+const printer = new Printer();
+
+printer.print(
+	block([
+		line([
+			segment("Hello, ", { color: "blue", modifiers: ["bold"] }),
+			segment("World!", { color: "#10B981", modifiers: ["italic"] })
+		])
+	])
+);
+```
+
+---
+
+## 🎨 Styling
+
+Every style accepts `color`, `bgColor`, and `modifiers`. Colors can be standard names or hex strings. Gradients are just arrays of colors.
+
+### Colors and Modifiers
+
+```typescript
+import { Printer, segment, line, block } from "@heinrichb/console-toolkit";
+
+const printer = new Printer();
+
+printer.print(
+	block([
+		line([segment("Bold red text", { color: "red", modifiers: ["bold"] })]),
+		line([segment("Hex color", { color: "#FF6B35" })]),
+		line([segment("White on blue", { color: "white", bgColor: "#3B82F6" })]),
+		line([segment("Bold on purple", { color: "white", bgColor: "#7C3AED", modifiers: ["bold"] })])
+	])
+);
+```
+
+**Standard colors:** `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`, `grey`
+
+**Modifiers:** `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`
+
+### Background Colors
+
+Background colors support everything foreground colors do — solid colors, hex codes, and gradient arrays:
+
+```typescript
+import { Printer, segment, line, block, GRADIENTS } from "@heinrichb/console-toolkit";
+
+const printer = new Printer();
+
+printer.print(block([line([segment("  Ocean background gradient  ", { color: "white", bgColor: GRADIENTS.ocean })])]));
+```
+
+---
+
+## ✨ Gradients
+
+### Horizontal Gradients
+
+Apply a color array to a line or segment for per-character interpolation:
+
+```typescript
+import { Printer, segment, line, block, GRADIENTS } from "@heinrichb/console-toolkit";
+
+const printer = new Printer();
+
+// Line-level gradient spans all segments
+printer.print(block([line([segment("Rainbow across the entire line")], { color: GRADIENTS.rainbow })]));
+
+// Segment-level gradient affects only that segment
+printer.print(block([line([segment("Normal text "), segment("gradient here", { color: GRADIENTS.sunset })])]));
+```
+
+### Vertical Gradients
+
+Apply a color array to a block for per-line interpolation:
+
+```typescript
+import { Printer, segment, line, block, GRADIENTS } from "@heinrichb/console-toolkit";
+
+const printer = new Printer();
+
+const lines = Array.from({ length: 6 }, (_, i) => line([segment(`  Line ${i + 1}  `)]));
+printer.print(block(lines, { color: GRADIENTS.fire }));
+```
+
+### Gradient Presets (`GRADIENTS`)
+
+Ready-made color arrays you can plug into any `color` or `bgColor` property:
+
+| Preset       | Colors                                  |
+| :----------- | :-------------------------------------- |
+| `rainbow`    | Red, amber, emerald, cyan, blue, violet |
+| `ocean`      | Deep navy, teal, cyan, light cyan       |
+| `fire`       | Dark red, red, amber, yellow            |
+| `sunset`     | Violet, pink, orange, amber             |
+| `forest`     | Dark emerald, emerald, lime, light lime |
+| `monochrome` | Black, gray, white                      |
+
+### Custom Gradient Interpolation
+
+Use `interpolateGradient` to compute a color at any point in a gradient:
+
+```typescript
+import { interpolateGradient } from "@heinrichb/console-toolkit";
+
+const color = interpolateGradient(["#EF4444", "#F59E0B", "#10B981"], 0.5);
+// Returns the hex color at 50% through the gradient
+```
+
+---
+
+## 📐 Layouts
+
+### `printColumns`
+
+Print multiple columns side-by-side with automatic padding:
+
+```typescript
+import { printColumns, line, segment } from "@heinrichb/console-toolkit";
+
+const labels = [
+	line([segment("Name:", { color: "#A78BFA" })]),
+	line([segment("Version:", { color: "#A78BFA" })]),
+	line([segment("Status:", { color: "#A78BFA" })])
+];
+const values = [
+	line([segment("console-toolkit", { color: "#60A5FA" })]),
+	line([segment("1.0.10", { color: "#34D399" })]),
+	line([segment("Operational", { color: "#FBBF24" })])
+];
+
+printColumns([labels, values], {
+	separator: "  =>  ",
+	widths: [10, 20]
+});
+```
+
+### `mergeColumns`
+
+Returns `PrintLine[]` instead of printing — useful for composing into larger layouts:
+
+```typescript
+import { mergeColumns, Printer, block, line, segment } from "@heinrichb/console-toolkit";
+
+const merged = mergeColumns([[line([segment("Left")])], [line([segment("Right")])]], " | ");
+
+new Printer().print(block(merged));
+```
+
+---
+
+## 🧩 Components
+
+### Progress Bars
+
+Fully customizable progress bars with 17 configuration options:
+
+```typescript
+import { createProgressBar, Printer, block } from "@heinrichb/console-toolkit";
+
+const printer = new Printer({ live: true });
+
+for (let i = 0; i <= 100; i += 2) {
+	const bar = createProgressBar({
+		progress: i / 100,
+		width: 40,
+		fillStyle: { color: ["#3B82F6", "#EC4899"] },
+		emptyStyle: { color: "#4B5563" }
+	});
+	printer.print(block([bar]));
+	await new Promise((r) => setTimeout(r, 25));
+}
+```
+
+### Spinners
+
+Time-based spinners with 5 built-in presets:
+
+```typescript
+import { Spinner, SPINNERS, Printer, line, segment, block } from "@heinrichb/console-toolkit";
+
+const spinner = new Spinner({ frames: SPINNERS.dots });
+const printer = new Printer({ live: true });
+
+// In your render loop:
+printer.print(block([line([segment(spinner.getFrame(), { color: "cyan" }), segment(" Loading...")])]));
+```
+
+### Tables
+
+Styled tables with automatic column sizing and four border styles (`single`, `double`, `rounded`, `none`):
+
+```typescript
+import { createTable, Printer, block } from "@heinrichb/console-toolkit";
+
+const printer = new Printer();
+
+const tableLines = createTable({
+	headers: ["Feature", "Status", "Since"],
+	rows: [
+		["Colors & Hex", "Stable", "v1.0"],
+		["Gradients", "Stable", "v1.0"],
+		["Background Colors", "New", "v1.1"],
+		["Tables", "New", "v1.1"]
+	],
+	headerStyle: { color: "cyan", modifiers: ["bold"] },
+	style: { color: "white" },
+	borderStyle: { color: "#6B7280" },
+	border: "rounded"
+});
+
+printer.print(block(tableLines));
+```
+
+---
+
+## 🐉 Presets
+
+### Dragon ASCII Art
+
+Vertical gradient dragon art — pass a `Color[]` array for the gradient stops:
+
+```typescript
+import { getDragon, Printer, block, GRADIENTS } from "@heinrichb/console-toolkit";
+
+const printer = new Printer();
+
+printer.print(block(getDragon())); // Default: red -> amber
+printer.print(block(getDragon(["#3B82F6", "#06B6D4"]))); // Two-color
+printer.print(block(getDragon(GRADIENTS.fire))); // Multi-stop preset
+```
+
+---
+
+## 🔧 Utilities
+
+### `renderToString`
+
+Capture styled output as a string instead of writing to stdout:
+
+```typescript
+import { Printer, segment, line, block } from "@heinrichb/console-toolkit";
+
+const printer = new Printer();
+const output = printer.renderToString(block([line([segment("Hello!", { color: "green", modifiers: ["bold"] })])]));
+// output contains the full ANSI-styled string
+```
+
+### `stripAnsi`
+
+Remove all ANSI escape sequences from a string:
+
+```typescript
+import { stripAnsi } from "@heinrichb/console-toolkit";
+
+const plain = stripAnsi("\x1b[38;2;255;0;0mRed text\x1b[0m");
+// Returns "Red text"
+```
+
+---
+
+## 📚 Detailed Documentation
+
+- **[Core Engine & Styling](https://github.com/heinrichb/console-toolkit/blob/main/src/core/README.md):** Printer class, data structures, styling system, gradients, layout utilities.
+- **[Components](https://github.com/heinrichb/console-toolkit/blob/main/src/components/README.md):** Full API reference for progress bars, spinners, and tables.
+- **[Presets](https://github.com/heinrichb/console-toolkit/blob/main/src/presets/README.md):** Dragon art, gradient presets, and usage examples.
+
+---
+
+## 📄 License
+
+MIT © Brennen Heinrich

package/dist/components/progress.d.ts

@@ -35,6 +35,16 @@ export interface ProgressBarOptions {
      * Specific style for the filled part. Overrides `barStyle`.
      */
     fillStyle?: PrintStyle;
+    /**
+     * Style to apply to the filled part when progress reaches 100%.
+     * Overrides `fillStyle`.
+     */
+    completeStyle?: PrintStyle;
+    /**
+     * Character to use for the filled part when progress reaches 100%.
+     * Overrides `fillChar`.
+     */
+    completeChar?: string;
     /**
      * Specific style for the empty part. Overrides `barStyle`.
      */

package/dist/components/table.d.ts

@@ -0,0 +1,31 @@
+import { PrintLine, PrintStyle } from "../core/types";
+/**
+ * Border drawing style for tables.
+ */
+export type BorderStyle = "single" | "double" | "rounded" | "none";
+/**
+ * Configuration options for creating a styled table.
+ */
+export interface TableOptions {
+    /** Column headers. If omitted, no header row is rendered. */
+    headers?: string[];
+    /** Row data. Each row is an array of cell strings. */
+    rows: string[][];
+    /** Base style for all table cell content. */
+    style?: PrintStyle;
+    /** Style override for header cells. */
+    headerStyle?: PrintStyle;
+    /** Style for border characters. */
+    borderStyle?: PrintStyle;
+    /** Border drawing style. Defaults to "single". */
+    border?: BorderStyle;
+    /** Fixed column widths (content area, excluding padding). Auto-computed from content if omitted. */
+    columnWidths?: number[];
+    /** Padding inside each cell (spaces on each side). Defaults to 1. */
+    cellPadding?: number;
+}
+/**
+ * Creates a styled table as an array of PrintLines.
+ * Composable with Printer: `printer.print(block(createTable(options)))`.
+ */
+export declare function createTable(options: TableOptions): PrintLine[];

package/dist/core/layout.d.ts

@@ -21,5 +21,6 @@ export declare function mergeColumns(columns: PrintLine[][], separator?: string,
 export declare function printColumns(columns: PrintLine[][], options?: {
     widths?: number[];
     separator?: string;
+    defaultStyle?: PrintStyle;
     printer?: Printer;
 }): void;

package/dist/core/printer.d.ts

@@ -15,6 +15,14 @@ export declare class Printer {
      * Clears the console using the stored line count.
      */
     clear(): void;
+    /**
+     * Renders a PrintBlock to a string without writing to stdout or affecting live mode state.
+     * Useful for capturing output, testing, or composing before display.
+     *
+     * @param data - Optional data to update the printer with.
+     * @returns The rendered ANSI string.
+     */
+    renderToString(data?: PrintBlock): string;
     /**
      * Renders the PrintBlock to the standard output.
      * If data is provided, updates the internal state.
@@ -23,9 +31,17 @@ export declare class Printer {
      */
     print(data?: PrintBlock): void;
     /**
-     * Resolves the block's vertical gradient (if any) to a solid color for the specific line.
+     * Shared rendering core — builds the ANSI output string for a PrintBlock.
+     */
+    private renderBlock;
+    /**
+     * Resolves the block's vertical gradients (color and bgColor) to solid colors for a specific line.
+     */
+    private resolveBlockStyleForLine;
+    /**
+     * Resolves a single color/gradient value to a solid color for a specific line position.
      */
-    private resolveBlockColorForLine;
+    private resolveGradientForLine;
     /**
      * Renders a single line.
      */

package/dist/core/style.d.ts

@@ -1,4 +1,5 @@
-import { Color, HexColor, PrintStyle, StyleModifier } from "./types";
+import { Color, HexColor, PrintStyle, StyleModifier, RGB } from "./types";
+export declare const ESC = "\u001B";
 /**
  * ANSI escape sequence to reset all styles.
  */
@@ -10,19 +11,23 @@ export declare function colorToHex(color: Color): string;
 /**
  * Converts a hex color string to an RGB object.
  */
-export declare function hexToRgb(hex: string): {
-    r: number;
-    g: number;
-    b: number;
-};
+export declare function hexToRgb(hex: string): RGB;
 /**
  * Converts RGB to a 24-bit ANSI foreground color escape sequence.
  */
 export declare function rgbToAnsi(r: number, g: number, b: number): string;
+/**
+ * Converts RGB to a 24-bit ANSI background color escape sequence.
+ */
+export declare function rgbToBgAnsi(r: number, g: number, b: number): string;
 /**
  * Converts any Color to an ANSI escape sequence.
  */
 export declare function resolveColorToAnsi(color: Color): string;
+/**
+ * Resolves a Color (Standard or Hex) to an RGB object.
+ */
+export declare function resolveColorToRgb(color: Color): RGB;
 /**
  * Converts a list of modifiers to an ANSI escape sequence.
  */
@@ -32,13 +37,20 @@ export declare function resolveModifiersToAnsi(modifiers?: StyleModifier[]): str
  */
 export declare function interpolateHex(color1: string, color2: string, factor: number): string;
 /**
- * Public interpolation function that accepts any Color type.
+ * Gets a foreground color from a multi-stop gradient as an ANSI escape sequence.
+ * Uses pre-resolved RGB colors for performance in per-character hot paths.
+ */
+export declare function getGradientColorFromRgb(colors: RGB[], factor: number): string;
+/**
+ * Gets a background color from a multi-stop gradient as an ANSI escape sequence.
+ * Uses pre-resolved RGB colors for performance in per-character hot paths.
  */
-export declare function interpolateColor(color1: Color, color2: Color, factor: number): HexColor;
+export declare function getGradientBgColorFromRgb(colors: RGB[], factor: number): string;
 /**
- * logic to get a specific color from a multi-stop gradient array at a specific factor (0-1).
+ * Interpolates a multi-stop gradient at a given factor (0-1), returning a HexColor.
+ * Useful for computing vertical gradient colors per-line or for any custom gradient logic.
  */
-export declare function getGradientColor(colors: Color[], factor: number): string;
+export declare function interpolateGradient(colors: Color[], factor: number): HexColor;
 /**
  * Merges a child style into a parent style.
  * - Modifiers are combined (union).