@heinrichb/console-toolkit 1.0.8 → 1.0.9

package/dist/components/progress.d.ts

@@ -0,0 +1,75 @@
+import { PrintLine, PrintStyle } from "../core/types";
+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?: PrintStyle;
+    /**
+     * Style for the brackets (start and end characters).
+     * Defaults to `style`.
+     */
+    bracketStyle?: PrintStyle;
+    /**
+     * Specific style for the start bracket. Overrides `bracketStyle`.
+     */
+    startStyle?: PrintStyle;
+    /**
+     * Specific style for the end bracket. Overrides `bracketStyle`.
+     */
+    endStyle?: PrintStyle;
+    /**
+     * Style for the bar (filled and empty parts).
+     * Defaults to `style`.
+     */
+    barStyle?: PrintStyle;
+    /**
+     * Specific style for the filled part. Overrides `barStyle`.
+     */
+    fillStyle?: PrintStyle;
+    /**
+     * Specific style for the empty part. Overrides `barStyle`.
+     */
+    emptyStyle?: PrintStyle;
+    /**
+     * Style for the percentage text.
+     * Defaults to `style`.
+     */
+    percentageStyle?: PrintStyle;
+    /**
+     * 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 PrintLine representing a progress bar.
+ */
+export declare function createProgressBar(options: ProgressBarOptions): PrintLine;

package/dist/components/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/core/layout.d.ts

@@ -0,0 +1,25 @@
+import { PrintLine, PrintStyle } from "./types";
+import { Printer } from "./printer";
+/**
+ * Merges multiple columns of PrintLines into a single layout.
+ * Ensures proper alignment by padding shorter lines.
+ *
+ * @param columns - Array of columns, where each column is an array of PrintLines.
+ * @param separator - String used to separate columns.
+ * @param defaultStyle - Style to apply to the separator and padding.
+ * @param widths - Optional fixed widths for each column.
+ * @returns A single array of PrintLines representing the merged output.
+ */
+export declare function mergeColumns(columns: PrintLine[][], separator?: string, defaultStyle?: PrintStyle, widths?: number[]): PrintLine[];
+/**
+ * Prints multiple columns of styled content to the console.
+ * A convenience wrapper around `mergeColumns` and `Printer.print`.
+ *
+ * @param columns - Array of columns to print.
+ * @param options - Layout options (widths, separator, custom printer).
+ */
+export declare function printColumns(columns: PrintLine[][], options?: {
+    widths?: number[];
+    separator?: string;
+    printer?: Printer;
+}): void;

package/dist/core/printer.d.ts

@@ -0,0 +1,33 @@
+import { PrintBlock, PrinterOptions } from "./types";
+/**
+ * Handles rendering PrintBlocks to the terminal with support for interactive/live overwriting.
+ */
+export declare class Printer {
+    private linesRendered;
+    private isLive;
+    private data?;
+    constructor(options?: PrinterOptions);
+    /**
+     * Generates the clear sequence to move cursor and clear previously rendered lines.
+     */
+    private getClearSequence;
+    /**
+     * Clears the console using the stored line count.
+     */
+    clear(): void;
+    /**
+     * Renders the PrintBlock to the standard output.
+     * If data is provided, updates the internal state.
+     *
+     * @param data - Optional data to update the printer with.
+     */
+    print(data?: PrintBlock): void;
+    /**
+     * Resolves the block's vertical gradient (if any) to a solid color for the specific line.
+     */
+    private resolveBlockColorForLine;
+    /**
+     * Renders a single line.
+     */
+    private renderLine;
+}

package/dist/core/style.d.ts

@@ -0,0 +1,53 @@
+import { Color, HexColor, PrintStyle, StyleModifier } from "./types";
+/**
+ * ANSI escape sequence to reset all styles.
+ */
+export declare const RESET = "\u001B[0m";
+/**
+ * Converts any Color (hex or standard name) to a Hex string.
+ */
+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;
+};
+/**
+ * Converts RGB to a 24-bit ANSI foreground color escape sequence.
+ */
+export declare function rgbToAnsi(r: number, g: number, b: number): string;
+/**
+ * Converts any Color to an ANSI escape sequence.
+ */
+export declare function resolveColorToAnsi(color: Color): string;
+/**
+ * Converts a list of modifiers to an ANSI escape sequence.
+ */
+export declare function resolveModifiersToAnsi(modifiers?: StyleModifier[]): string;
+/**
+ * Interpolates between two hex colors.
+ */
+export declare function interpolateHex(color1: string, color2: string, factor: number): string;
+/**
+ * Public interpolation function that accepts any Color type.
+ */
+export declare function interpolateColor(color1: Color, color2: Color, factor: number): HexColor;
+/**
+ * logic to get a specific color from a multi-stop gradient array at a specific factor (0-1).
+ */
+export declare function getGradientColor(colors: Color[], factor: number): string;
+/**
+ * Merges a child style into a parent style.
+ * - Modifiers are combined (union).
+ * - Child color overrides parent color.
+ */
+export declare function mergeStyles(parent?: PrintStyle, child?: PrintStyle): PrintStyle;
+/**
+ * Resolves a style object into an ANSI string.
+ * If the color is a gradient (array), it uses the provided factor (0-1) to pick the color.
+ * Defaults to factor 0 if not provided.
+ */
+export declare function resolveStyle(style?: PrintStyle, gradientFactor?: number): string;

package/dist/core/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Standard colors supported by most terminals.
+ */
+export type StandardColor = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "grey";
+/**
+ * Text style modifiers.
+ */
+export type StyleModifier = "bold" | "dim" | "italic" | "underline" | "default" | "hidden" | "inverse" | "strikethrough";
+/**
+ * A valid Hex color string (e.g., "#FF0000").
+ */
+export type HexColor = `#${string}`;
+/**
+ * A color can be a standard color name or a hex color string.
+ */
+export type Color = StandardColor | HexColor;
+/**
+ * Represents the style configuration for a text segment, line, or block.
+ */
+export interface PrintStyle {
+    /**
+     * The color to apply.
+     * - A single color (string) applies a solid color.
+     * - An array of colors applies a gradient.
+     */
+    color?: Color | Color[];
+    /**
+     * A list of style modifiers (e.g., bold, italic) to apply.
+     */
+    modifiers?: StyleModifier[];
+}
+/**
+ * Represents a segment of text with applied styles.
+ */
+export interface PrintSegment {
+    /** The text content of the segment. */
+    text: string;
+    /** The style specific to this segment. Merges with parent styles. */
+    style?: PrintStyle;
+}
+/**
+ * Represents a line of text composed of multiple styled segments.
+ */
+export interface PrintLine {
+    /** Array of segments that make up the line. */
+    segments: PrintSegment[];
+    /** The style specific to this line. Merges with parent block style and applies to all children. */
+    style?: PrintStyle;
+}
+/**
+ * Represents a block of lines managed by the printer.
+ */
+export interface PrintBlock {
+    /** Array of lines that make up the block. */
+    lines: PrintLine[];
+    /** The style specific to this block. Applies to all children. */
+    style?: PrintStyle;
+}
+/**
+ * Configuration for the Printer engine.
+ */
+export interface PrinterOptions {
+    /**
+     * If true, the printer will overwrite previous output on subsequent print calls.
+     * Useful for live-updating displays (spinners, progress bars).
+     */
+    live?: boolean;
+    /**
+     * Initial data to load into the printer.
+     */
+    data?: PrintBlock;
+}

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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,385 @@
+// src/core/style.ts
+var ESC = "\x1B";
+var RESET = `${ESC}[0m`;
+var STANDARD_COLORS = {
+  black: "#000000",
+  red: "#EF4444",
+  green: "#10B981",
+  yellow: "#F59E0B",
+  blue: "#3B82F6",
+  magenta: "#EC4899",
+  cyan: "#06B6D4",
+  white: "#FFFFFF",
+  gray: "#6B7280",
+  grey: "#6B7280"
+};
+var MODIFIER_CODES = {
+  default: "0",
+  bold: "1",
+  dim: "2",
+  italic: "3",
+  underline: "4",
+  inverse: "7",
+  hidden: "8",
+  strikethrough: "9"
+};
+function colorToHex(color) {
+  if (color.startsWith("#"))
+    return color;
+  const hex = STANDARD_COLORS[color.toLowerCase()];
+  if (!hex)
+    return "#FFFFFF";
+  return hex;
+}
+function hexToRgb(hex) {
+  const h = hex.replace(/^#/, "");
+  if (h.length !== 6)
+    return { r: 255, g: 255, b: 255 };
+  return {
+    r: parseInt(h.substring(0, 2), 16),
+    g: parseInt(h.substring(2, 4), 16),
+    b: parseInt(h.substring(4, 6), 16)
+  };
+}
+function rgbToAnsi(r, g, b) {
+  return `${ESC}[38;2;${r};${g};${b}m`;
+}
+function resolveColorToAnsi(color) {
+  const hex = colorToHex(color);
+  const { r, g, b } = hexToRgb(hex);
+  return rgbToAnsi(r, g, b);
+}
+function resolveModifiersToAnsi(modifiers) {
+  if (!modifiers || modifiers.length === 0)
+    return "";
+  return modifiers.map((m) => {
+    const code = MODIFIER_CODES[m];
+    return code ? `${ESC}[${code}m` : "";
+  }).join("");
+}
+function toHex(c) {
+  const hex = Math.max(0, Math.min(255, Math.round(c))).toString(16);
+  return hex.length === 1 ? "0" + hex : hex;
+}
+function interpolateHex(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)}`;
+}
+function interpolateColor(color1, color2, factor) {
+  return interpolateHex(colorToHex(color1), colorToHex(color2), factor);
+}
+function getGradientColor(colors, factor) {
+  if (colors.length === 0)
+    return "";
+  if (colors.length === 1)
+    return resolveColorToAnsi(colors[0]);
+  const f = Math.max(0, Math.min(1, factor));
+  const segmentLength = 1 / (colors.length - 1);
+  const segmentIndex = Math.min(Math.floor(f / segmentLength), colors.length - 2);
+  const segmentFactor = (f - segmentIndex * segmentLength) / segmentLength;
+  const c1 = colors[segmentIndex];
+  const c2 = colors[segmentIndex + 1];
+  const hex = interpolateColor(c1, c2, segmentFactor);
+  return resolveColorToAnsi(hex);
+}
+function mergeStyles(parent, child) {
+  if (!parent && !child)
+    return {};
+  if (!parent)
+    return child ?? {};
+  if (!child)
+    return parent;
+  const mergedModifiers = Array.from(new Set([...parent.modifiers ?? [], ...child.modifiers ?? []]));
+  return {
+    modifiers: mergedModifiers,
+    color: child.color ?? parent.color
+  };
+}
+function resolveStyle(style, gradientFactor = 0) {
+  if (!style)
+    return "";
+  let ansi = "";
+  if (style.modifiers) {
+    ansi += resolveModifiersToAnsi(style.modifiers);
+  }
+  if (style.color) {
+    if (Array.isArray(style.color)) {
+      const hex = getGradientColor(style.color, gradientFactor);
+      ansi += hex;
+    } else {
+      ansi += resolveColorToAnsi(style.color);
+    }
+  }
+  return ansi;
+}
+// src/core/utils.ts
+function getLineLength(line) {
+  return line.segments.reduce((acc, seg) => acc + seg.text.length, 0);
+}
+function computeMaxWidth(lines) {
+  return lines.length > 0 ? Math.max(...lines.map(getLineLength)) : 0;
+}
+function padLine(line, targetWidth, padStyle) {
+  const currentLength = getLineLength(line);
+  if (currentLength < targetWidth) {
+    return {
+      segments: [...line.segments, { text: " ".repeat(targetWidth - currentLength), style: padStyle }]
+    };
+  }
+  return line;
+}
+// src/core/printer.ts
+var ESC2 = "\x1B";
+
+class Printer {
+  linesRendered = 0;
+  isLive;
+  data;
+  constructor(options = {}) {
+    this.isLive = options.live ?? false;
+    this.data = options.data;
+  }
+  getClearSequence() {
+    if (!this.isLive || this.linesRendered === 0)
+      return "";
+    return `${ESC2}[1A${ESC2}[2K\r`.repeat(this.linesRendered);
+  }
+  clear() {
+    if (this.linesRendered > 0) {
+      process.stdout.write(this.getClearSequence());
+      this.linesRendered = 0;
+    }
+  }
+  print(data) {
+    if (data) {
+      this.data = data;
+    }
+    if (!this.data) {
+      return;
+    }
+    let output = this.getClearSequence();
+    const lines = this.data.lines;
+    const blockStyle = this.data.style ?? {};
+    lines.forEach((line, lineIndex) => {
+      output += this.renderLine(line, lineIndex, lines.length, blockStyle);
+      output += `
+`;
+    });
+    process.stdout.write(output);
+    this.linesRendered = lines.length;
+  }
+  resolveBlockColorForLine(blockStyle, lineIndex, totalLines) {
+    if (!blockStyle.color)
+      return;
+    if (Array.isArray(blockStyle.color)) {
+      if (totalLines <= 1)
+        return blockStyle.color[0];
+      const colors = blockStyle.color;
+      const factor = lineIndex / (totalLines - 1);
+      const f = Math.max(0, Math.min(1, factor));
+      const segmentLength = 1 / (colors.length - 1);
+      const segmentIndex = Math.min(Math.floor(f / segmentLength), colors.length - 2);
+      const segmentFactor = (f - segmentIndex * segmentLength) / segmentLength;
+      const c1 = colors[segmentIndex];
+      const c2 = colors[segmentIndex + 1];
+      return interpolateColor(c1, c2, segmentFactor);
+    }
+    return blockStyle.color;
+  }
+  renderLine(line, lineIndex, totalLines, parentBlockStyle) {
+    const blockColorForLine = this.resolveBlockColorForLine(parentBlockStyle, lineIndex, totalLines);
+    const baseLineStyle = {
+      modifiers: parentBlockStyle.modifiers,
+      color: blockColorForLine
+    };
+    const effectiveLineStyle = mergeStyles(baseLineStyle, line.style);
+    const totalChars = line.segments.reduce((acc, seg) => acc + seg.text.length, 0);
+    let currentCharIndex = 0;
+    let lineOutput = "";
+    line.segments.forEach((seg) => {
+      const effectiveSegmentStyle = mergeStyles(effectiveLineStyle, seg.style);
+      if (Array.isArray(effectiveSegmentStyle.color)) {
+        const colors = effectiveSegmentStyle.color;
+        const text = seg.text;
+        const isGlobalGradient = effectiveSegmentStyle.color === effectiveLineStyle.color;
+        const modifiersAnsi = resolveModifiersToAnsi(effectiveSegmentStyle.modifiers);
+        for (let i = 0;i < text.length; i++) {
+          let factor = 0;
+          if (isGlobalGradient && totalChars > 1) {
+            factor = (currentCharIndex + i) / (totalChars - 1);
+          } else if (!isGlobalGradient && text.length > 1) {
+            factor = i / (text.length - 1);
+          }
+          const colorAnsi = getGradientColor(colors, factor);
+          lineOutput += `${modifiersAnsi}${colorAnsi}${text[i]}`;
+        }
+        lineOutput += RESET;
+      } else {
+        const ansi = resolveStyle(effectiveSegmentStyle);
+        lineOutput += `${ansi}${seg.text}${RESET}`;
+      }
+      currentCharIndex += seg.text.length;
+    });
+    return lineOutput;
+  }
+}
+// src/core/layout.ts
+function mergeColumns(columns, separator = "     ", defaultStyle, widths) {
+  if (columns.length === 0)
+    return [];
+  const maxLines = Math.max(...columns.map((c) => c.length));
+  const colWidths = columns.map((col, i) => {
+    if (widths?.[i] !== undefined)
+      return widths[i];
+    return computeMaxWidth(col);
+  });
+  const output = [];
+  for (let i = 0;i < maxLines; i++) {
+    let segments = [];
+    for (let j = 0;j < columns.length; j++) {
+      const line = columns[j][i] || { segments: [] };
+      if (j < columns.length - 1) {
+        const padded = padLine(line, colWidths[j], defaultStyle);
+        segments = [...segments, ...padded.segments, { text: separator, style: defaultStyle }];
+      } else {
+        segments = [...segments, ...line.segments];
+      }
+    }
+    output.push({ segments });
+  }
+  return output;
+}
+function printColumns(columns, options = {}) {
+  const { widths, separator = "     ", printer = new Printer } = options;
+  const mergedLines = mergeColumns(columns, separator, undefined, widths);
+  printer.print({ lines: mergedLines });
+}
+// src/components/progress.ts
+function createProgressBar(options) {
+  const {
+    progress,
+    width = 20,
+    style,
+    bracketStyle,
+    startStyle,
+    endStyle,
+    barStyle,
+    fillStyle,
+    emptyStyle,
+    percentageStyle,
+    startChar = "[",
+    endChar = "]",
+    fillChar = "█",
+    emptyChar = "░",
+    showPercentage = true,
+    formatPercentage
+  } = options;
+  const p = Math.max(0, Math.min(1, progress));
+  const filledWidth = Math.round(p * width);
+  const emptyWidth = width - filledWidth;
+  const resolvedBracketStyle = bracketStyle ?? style;
+  const resolvedStartStyle = startStyle ?? resolvedBracketStyle;
+  const resolvedEndStyle = endStyle ?? resolvedBracketStyle;
+  const resolvedBarStyle = barStyle ?? style;
+  const resolvedFillStyle = fillStyle ?? resolvedBarStyle;
+  const resolvedEmptyStyle = emptyStyle ?? resolvedBarStyle;
+  const resolvedPercentageStyle = percentageStyle ?? style;
+  const segments = [];
+  if (startChar) {
+    segments.push({ text: startChar, style: resolvedStartStyle });
+  }
+  if (filledWidth > 0) {
+    segments.push({ text: fillChar.repeat(filledWidth), style: resolvedFillStyle });
+  }
+  if (emptyWidth > 0) {
+    segments.push({ text: emptyChar.repeat(emptyWidth), style: resolvedEmptyStyle });
+  }
+  if (endChar) {
+    segments.push({ text: endChar, style: resolvedEndStyle });
+  }
+  if (showPercentage) {
+    const percentageText = formatPercentage ? formatPercentage(p) : ` ${Math.round(p * 100)}%`;
+    segments.push({ text: percentageText, style: resolvedPercentageStyle });
+  }
+  return { segments };
+}
+// src/components/spinner.ts
+var SPINNERS = {
+  dots: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  lines: ["-", "\\", "|", "/"],
+  arrows: ["←", "↖", "↑", "↗", "→", "↘", "↓", "↙"],
+  circle: ["◐", "◓", "◑", "◒"],
+  square: ["▖", "▘", "▝", "▗"]
+};
+
+class Spinner {
+  frames;
+  interval;
+  startTime;
+  constructor(options) {
+    this.frames = options.frames;
+    this.interval = options.interval ?? 80;
+    this.startTime = Date.now();
+  }
+  getFrame() {
+    const now = Date.now();
+    const elapsed = now - this.startTime;
+    const index = Math.floor(elapsed / this.interval) % this.frames.length;
+    return this.frames[index];
+  }
+}
+// src/presets/ascii.ts
+function getDragon(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: { color: colorStyle } }] };
+  });
+}
+export {
+  rgbToAnsi,
+  resolveStyle,
+  resolveModifiersToAnsi,
+  resolveColorToAnsi,
+  printColumns,
+  padLine,
+  mergeStyles,
+  mergeColumns,
+  interpolateHex,
+  interpolateColor,
+  hexToRgb,
+  getLineLength,
+  getGradientColor,
+  getDragon,
+  createProgressBar,
+  computeMaxWidth,
+  colorToHex,
+  Spinner,
+  SPINNERS,
+  RESET,
+  Printer
+};

package/dist/index.min.js

@@ -0,0 +1,2 @@
+var A="\x1B",T=`${A}[0m`,a={black:"#000000",red:"#EF4444",green:"#10B981",yellow:"#F59E0B",blue:"#3B82F6",magenta:"#EC4899",cyan:"#06B6D4",white:"#FFFFFF",gray:"#6B7280",grey:"#6B7280"},i={default:"0",bold:"1",dim:"2",italic:"3",underline:"4",inverse:"7",hidden:"8",strikethrough:"9"};function W(q){if(q.startsWith("#"))return q;let z=a[q.toLowerCase()];if(!z)return"#FFFFFF";return z}function E(q){let z=q.replace(/^#/,"");if(z.length!==6)return{r:255,g:255,b:255};return{r:parseInt(z.substring(0,2),16),g:parseInt(z.substring(2,4),16),b:parseInt(z.substring(4,6),16)}}function s(q,z,J){return`${A}[38;2;${q};${z};${J}m`}function P(q){let z=W(q),{r:J,g:K,b:Q}=E(z);return s(J,K,Q)}function w(q){if(!q||q.length===0)return"";return q.map((z)=>{let J=i[z];return J?`${A}[${J}m`:""}).join("")}function R(q){let z=Math.max(0,Math.min(255,Math.round(q))).toString(16);return z.length===1?"0"+z:z}function r(q,z,J){let K=Math.max(0,Math.min(1,J)),Q=E(q),U=E(z),Y=Q.r+K*(U.r-Q.r),V=Q.g+K*(U.g-Q.g),X=Q.b+K*(U.b-Q.b);return`#${R(Y)}${R(V)}${R(X)}`}function O(q,z,J){return r(W(q),W(z),J)}function I(q,z){if(q.length===0)return"";if(q.length===1)return P(q[0]);let J=Math.max(0,Math.min(1,z)),K=1/(q.length-1),Q=Math.min(Math.floor(J/K),q.length-2),U=(J-Q*K)/K,Y=q[Q],V=q[Q+1],X=O(Y,V,U);return P(X)}function k(q,z){if(!q&&!z)return{};if(!q)return z??{};if(!z)return q;return{modifiers:Array.from(new Set([...q.modifiers??[],...z.modifiers??[]])),color:z.color??q.color}}function C(q,z=0){if(!q)return"";let J="";if(q.modifiers)J+=w(q.modifiers);if(q.color)if(Array.isArray(q.color)){let K=I(q.color,z);J+=K}else J+=P(q.color);return J}function f(q){return q.segments.reduce((z,J)=>z+J.text.length,0)}function u(q){return q.length>0?Math.max(...q.map(f)):0}function S(q,z,J){let K=f(q);if(K<z)return{segments:[...q.segments,{text:" ".repeat(z-K),style:J}]};return q}var m="\x1B";class v{linesRendered=0;isLive;data;constructor(q={}){this.isLive=q.live??!1,this.data=q.data}getClearSequence(){if(!this.isLive||this.linesRendered===0)return"";return`${m}[1A${m}[2K\r`.repeat(this.linesRendered)}clear(){if(this.linesRendered>0)process.stdout.write(this.getClearSequence()),this.linesRendered=0}print(q){if(q)this.data=q;if(!this.data)return;let z=this.getClearSequence(),J=this.data.lines,K=this.data.style??{};J.forEach((Q,U)=>{z+=this.renderLine(Q,U,J.length,K),z+=`
+`}),process.stdout.write(z),this.linesRendered=J.length}resolveBlockColorForLine(q,z,J){if(!q.color)return;if(Array.isArray(q.color)){if(J<=1)return q.color[0];let K=q.color,Q=z/(J-1),U=Math.max(0,Math.min(1,Q)),Y=1/(K.length-1),V=Math.min(Math.floor(U/Y),K.length-2),X=(U-V*Y)/Y,Z=K[V],$=K[V+1];return O(Z,$,X)}return q.color}renderLine(q,z,J,K){let Q=this.resolveBlockColorForLine(K,z,J),U={modifiers:K.modifiers,color:Q},Y=k(U,q.style),V=q.segments.reduce(($,_)=>$+_.text.length,0),X=0,Z="";return q.segments.forEach(($)=>{let _=k(Y,$.style);if(Array.isArray(_.color)){let j=_.color,G=$.text,D=_.color===Y.color,B=w(_.modifiers);for(let N=0;N<G.length;N++){let M=0;if(D&&V>1)M=(X+N)/(V-1);else if(!D&&G.length>1)M=N/(G.length-1);let H=I(j,M);Z+=`${B}${H}${G[N]}`}Z+=T}else{let j=C(_);Z+=`${j}${$.text}${T}`}X+=$.text.length}),Z}}function n(q,z="     ",J,K){if(q.length===0)return[];let Q=Math.max(...q.map((V)=>V.length)),U=q.map((V,X)=>{if(K?.[X]!==void 0)return K[X];return u(V)}),Y=[];for(let V=0;V<Q;V++){let X=[];for(let Z=0;Z<q.length;Z++){let $=q[Z][V]||{segments:[]};if(Z<q.length-1){let _=S($,U[Z],J);X=[...X,..._.segments,{text:z,style:J}]}else X=[...X,...$.segments]}Y.push({segments:X})}return Y}function Kq(q,z={}){let{widths:J,separator:K="     ",printer:Q=new v}=z,U=n(q,K,void 0,J);Q.print({lines:U})}function Uq(q){let{progress:z,width:J=20,style:K,bracketStyle:Q,startStyle:U,endStyle:Y,barStyle:V,fillStyle:X,emptyStyle:Z,percentageStyle:$,startChar:_="[",endChar:j="]",fillChar:G="█",emptyChar:D="░",showPercentage:B=!0,formatPercentage:N}=q,M=Math.max(0,Math.min(1,z)),H=Math.round(M*J),b=J-H,L=Q??K,h=U??L,p=Y??L,x=V??K,y=X??x,g=Z??x,d=$??K,F=[];if(_)F.push({text:_,style:h});if(H>0)F.push({text:G.repeat(H),style:y});if(b>0)F.push({text:D.repeat(b),style:g});if(j)F.push({text:j,style:p});if(B){let c=N?N(M):` ${Math.round(M*100)}%`;F.push({text:c,style:d})}return{segments:F}}var Xq={dots:["⠋","⠙","⠹","⠸","⠼","⠴","⠦","⠧","⠇","⠏"],lines:["-","\\","|","/"],arrows:["←","↖","↑","↗","→","↘","↓","↙"],circle:["◐","◓","◑","◒"],square:["▖","▘","▝","▗"]};class l{frames;interval;startTime;constructor(q){this.frames=q.frames,this.interval=q.interval??80,this.startTime=Date.now()}getFrame(){let z=Date.now()-this.startTime,J=Math.floor(z/this.interval)%this.frames.length;return this.frames[J]}}function $q(q="#EF4444",z="#F59E0B"){let J=["                ^    ^","               / \\  //\\"," |\\___/|      /   \\//  .\\"," /O  O  \\__  /    //  | \\ \\","/     /  \\_/_/    //   |  \\  \\","@___@'    \\_//   //    |   \\   \\ ","   |       \\_// //     |    \\    \\ ","   |        \\///      |     \\     \\ ","  _|_ /   )  //       |      \\     _\\"," '/,_ _ _/  ( ; -.    |    _ _\\.-~        .-~~~^-."," ,-{        _      `-.|.-~-.           .~         `.","  '/\\      /                 ~-. _ .-~      .-~^-.  \\","     `.   {            }                   /      \\  \\","   .----~-\\.        \\-'                 .~         \\  `. \\^-.","  ///.----..>    c   \\             _ -~             `.  ^-`   ^-_","    ///-._ _ _ _ _ _ _}^ - - - - ~                     ~--,   .-~","                                                          /.-'"];return J.map((K,Q)=>{let U=J.length<=1?0:Q/(J.length-1),Y=O(q,z,U);return{segments:[{text:K,style:{color:Y}}]}})}export{s as rgbToAnsi,C as resolveStyle,w as resolveModifiersToAnsi,P as resolveColorToAnsi,Kq as printColumns,S as padLine,k as mergeStyles,n as mergeColumns,r as interpolateHex,O as interpolateColor,E as hexToRgb,f as getLineLength,I as getGradientColor,$q as getDragon,Uq as createProgressBar,u as computeMaxWidth,W as colorToHex,l as Spinner,Xq as SPINNERS,T as RESET,v as Printer};

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[];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heinrichb/console-toolkit",
-	"version": "1.0.8",
+	"version": "1.0.9",
 	"description": "A versatile TypeScript utility library for enhanced console logging, formatting, and layout management.",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -17,6 +17,7 @@
 		"test": "bun test src",
 		"test:coverage": "bun test src --coverage --coverage-threshold=100",
 		"build": "bun run scripts/build.ts",
+		"publish": "bun run build && bun publish --tag latest",
 		"typecheck": "bun x tsc --noEmit",
 		"format:check": "prettier --check \"src/**/*.{ts,json,md}\"",
 		"format:write": "prettier --write \"src/**/*.{ts,json,md}\"",