console-toolkit 1.2.8 → 1.2.10

package/src/style.js

@@ -177,34 +177,67 @@ class Reset {
   }
 }
 
+/** Chainable API for building SGR (Select Graphics Rendition) states.
+ * Provides namespaces for foreground (`fg`), background (`bg`), decoration colors, brightness, and reset.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Module:-style}
+ */
 export class Style {
+  /**
+   * @param {object|string|null} [initState] - The initial SGR state (SgrState, string, or null for reset).
+   * @param {object|string|null} [currentState] - The current SGR state (defaults to initState).
+   * @param {number} [colorDepth=24] - Color depth (1, 4, 8, or 24).
+   */
   constructor(initState, currentState, colorDepth = 24) {
     this[initStateSymbol] = toState(initState);
     this[stateSymbol] = currentState ? toState(currentState) : this[initStateSymbol];
     this[colorDepthSymbol] = colorDepth;
   }
+  /** Creates a new Style with additional SGR commands applied.
+   * @param {string|string[]} [newCommands=[]] - SGR command(s) to add.
+   * @returns {Style}
+   */
   make(newCommands = []) {
     if (!Array.isArray(newCommands)) newCommands = [newCommands];
     return new Style(this[initStateSymbol], addCommandsToState(this[stateSymbol], newCommands), this[colorDepthSymbol]);
   }
+  /** Adds SGR commands from an escape sequence string.
+   * @param {string} commandSequence - An ANSI escape sequence string.
+   * @returns {Style}
+   */
   add(commandSequence) {
     const state = extractState(String(commandSequence), this[stateSymbol]);
     return state === this[stateSymbol] ? this : new Style(this[initStateSymbol], state, this[colorDepthSymbol]);
   }
+  /** Combines an SGR state into the current state.
+   * @param {object|string|null} state - State to combine (SgrState, string, or null).
+   * @returns {Style}
+   */
   addState(state) {
     return new Style(this[initStateSymbol], combineStates(this[stateSymbol], toState(state)), this[colorDepthSymbol]);
   }
+  /** Creates a new Style with the current state as the initial state, optionally calling a function.
+   * @param {Function} [fn] - Optional callback receiving the new Style.
+   * @returns {Style|this}
+   */
   mark(fn) {
     const newStyle = new Style(this[stateSymbol], null, this[colorDepthSymbol]);
     if (typeof fn != 'function') return newStyle;
     fn(newStyle);
     return this;
   }
+  /** Returns the initial state, or passes it to a callback.
+   * @param {Function} [fn] - Optional callback.
+   * @returns {object|this}
+   */
   getInitialState(fn) {
     if (typeof fn != 'function') return this[initStateSymbol];
     fn(this[initStateSymbol]);
     return this;
   }
+  /** Returns the current state, or passes it to a callback.
+   * @param {Function} [fn] - Optional callback.
+   * @returns {object|this}
+   */
   getState(fn) {
     if (typeof fn != 'function') return this[stateSymbol];
     fn(this[stateSymbol]);
@@ -214,6 +247,10 @@ export class Style {
   get colorDepth() {
     return this[colorDepthSymbol]; // 1, 4, 8, 24
   }
+  /** Creates a new Style with a different color depth.
+   * @param {number} colorDepth - New color depth (1, 4, 8, or 24).
+   * @returns {Style}
+   */
   setColorDepth(colorDepth) {
     return new Style(this[initStateSymbol], this[stateSymbol], colorDepth);
   }
@@ -290,7 +327,7 @@ export class Style {
     return this[colorDepthSymbol] > 8 ? this.hexTrueColor(hex) : this.hex256(hex);
   }
   bgStdRgb(r, g, b) {
-    return this.make(getBgStdRgb(r, g, b));
+    return this.make(sgr.getBgStdRgb(r, g, b));
   }
   bgBrightStdRgb(r, g, b) {
     return this.make(sgr.getBgBrightStdRgb(r, g, b));
@@ -335,7 +372,7 @@ export class Style {
     return this.make(sgr.getDecorationStdColor256(r, g, b));
   }
   decorationBrightStdRgb256(r, g, b) {
-    return this.make(getDecorationBrightStdColor256(r, g, b));
+    return this.make(sgr.getDecorationBrightStdColor256(r, g, b));
   }
   decorationColor(c) {
     return this.make(sgr.getDecorationRawColor256(c));
@@ -373,7 +410,11 @@ export class Style {
   decorationHex(hex) {
     return this[colorDepthSymbol] > 8 ? this.decorationHexTrueColor(hex) : this.decorationHex256(hex);
   }
-  // wrap a string
+  /** Wraps a string (or array of strings) with SGR escape sequences for the current style.
+   * Applies the style at the start and reverses it at the end.
+   * @param {string|string[]} s - String(s) to wrap.
+   * @returns {string|string[]} The styled string(s).
+   */
   text(s) {
     if (Array.isArray(s)) return s.map(s => this.text(s));
     s = String(s);
@@ -389,7 +430,9 @@ export class Style {
     const cleanupCommands = stateReverseTransition(this[initStateSymbol], state);
     return stringifyCommands(initialCommands) + s + stringifyCommands(cleanupCommands);
   }
-  // convert to string
+  /** Converts the style to an SGR escape sequence string (transition from initial to current state).
+   * @returns {string}
+   */
   toString() {
     const initialCommands = stateTransition(this[initStateSymbol], this[stateSymbol]);
     return stringifyCommands(initialCommands);
@@ -611,10 +654,21 @@ const makeBq =
     return bq(strings, ...args);
   };
 
+/** Tagged template literal for styled text. Style changes persist after the string.
+ * Can also be called as `s({initState, setState})` to create a configured tagger.
+ * @type {Function}
+ */
 export const s = makeBq(false);
+/** Tagged template literal for styled text. Automatically resets the style at the end.
+ * Can also be called as `c({initState, setState})` to create a configured tagger.
+ * @type {Function}
+ */
 export const c = makeBq(true);
 
 // singleton
+/** The default Style singleton with an empty initial state.
+ * @type {Style}
+ */
 export const style = new Style({});
 
 export default style;

package/src/symbols.d.ts

@@ -0,0 +1,167 @@
+/** @module symbols
+ * Unicode characters for drawing lines, tables, charts, and other visual elements.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Module:-symbols}
+ */
+
+/** Vertical block elements in 1/8th increments (index 0 = space, 7 = full block). */
+export const vBlocks8th: string[];
+/** Horizontal block elements in 1/8th increments (index 0 = space, 7 = full block). */
+export const hBlocks8th: string[];
+/** Full block character (█). */
+export const fullBlock: string;
+
+/** Left 1/8th block line. */
+export const lLine: string;
+/** Right 1/8th block line. */
+export const rLine: string;
+/** Top 1/8th block line. */
+export const tLine: string;
+/** Bottom 1/8th block line. */
+export const bLine: string;
+
+/** Left half block. */
+export const lHalf: string;
+/** Right half block. */
+export const rHalf: string;
+/** Top half block. */
+export const tHalf: string;
+/** Bottom half block. */
+export const bHalf: string;
+
+/** Top-left quadrant block. */
+export const tlQuadrant: string;
+/** Bottom-left quadrant block. */
+export const blQuadrant: string;
+/** Top-right quadrant block. */
+export const trQuadrant: string;
+/** Bottom-right quadrant block. */
+export const brQuadrant: string;
+
+/** Top-left + bottom-right diagonal quadrants. */
+export const tlBrQuadrants: string;
+/** Top-right + bottom-left diagonal quadrants. */
+export const trBlQuadrants: string;
+
+/** Negative (inverse) top-left quadrant. */
+export const tlNegativeQuadrant: string;
+/** Negative (inverse) bottom-left quadrant. */
+export const blNegativeQuadrant: string;
+/** Negative (inverse) top-right quadrant. */
+export const trNegativeQuadrant: string;
+/** Negative (inverse) bottom-right quadrant. */
+export const brNegativeQuadrant: string;
+
+/** All 16 quadrant block characters indexed by bitmask (TL=1, TR=2, BL=4, BR=8). */
+export const quadrants: string[];
+
+/** Returns the quadrant character for the given corner flags.
+ * @param tl - Top-left filled.
+ * @param tr - Top-right filled.
+ * @param bl - Bottom-left filled.
+ * @param br - Bottom-right filled.
+ * @returns The quadrant block character.
+ */
+export function quadrant(tl: boolean, tr: boolean, bl: boolean, br: boolean): string;
+
+/** Shade characters from empty to full: space, light, medium, dark, full block. */
+export const shades: string[];
+/** Light shade character (░). */
+export const shadeLight: string;
+/** Medium shade character (▒). */
+export const shadeMedium: string;
+/** Dark shade character (▓). */
+export const shadeDark: string;
+
+// ellipses
+/** Horizontal ellipsis (…). */
+export const hellip: string;
+/** Vertical ellipsis (⋮). */
+export const vellip: string;
+/** Centered triple dots (⋯). */
+export const ctdot: string;
+/** Up-pointing triple dots (⋰). */
+export const utdot: string;
+/** Down-pointing triple dots (⋱). */
+export const dtdot: string;
+
+/** Alias for `hellip`. */
+export {hellip as ellipsis};
+
+// math
+/** Infinity symbol (∞). */
+export const infinity: string;
+/** Plus-minus sign (±). */
+export const plusMinus: string;
+/** Minus-plus sign (∓). */
+export const minusPlus: string;
+/** Tilde operator (∼). */
+export const tilde: string;
+/** Minus sign (−). */
+export const minus: string;
+/** Multiplication sign (×). */
+export const multiplication: string;
+/** Division sign (÷). */
+export const division: string;
+/** N-ary product (∏). */
+export const product: string;
+/** N-ary summation (∑). */
+export const sum: string;
+/** For all (∀). */
+export const forAll: string;
+/** There exists (∃). */
+export const exist: string;
+/** Degree sign (°). */
+export const degree: string;
+
+/** Alias for `multiplication`. */
+export {multiplication as times};
+
+/** Superscript plus (⁺). */
+export const superscriptPlus: string;
+/** Superscript minus (⁻). */
+export const superscriptMinus: string;
+/** Subscript plus (₊). */
+export const subscriptPlus: string;
+/** Subscript minus (₋). */
+export const subscriptMinus: string;
+
+/** Per mille sign (‰). */
+export const permille: string;
+/** Per myriad sign (‱). */
+export const permyriad: string;
+
+// dashes
+/** Hyphen (‐). */
+export const hyphen: string;
+/** Figure dash (‒). */
+export const figureDash: string;
+/** En dash (–). */
+export const ndash: string;
+/** Em dash (—). */
+export const mdash: string;
+/** Horizontal bar (―). */
+export const horbar: string;
+
+// marks
+/** Ballot box (☐). */
+export const ballotBox: string;
+/** Ballot box with check (☑). */
+export const ballotBoxChecked: string;
+/** Ballot box with bold check (☒-variant). */
+export const ballotBoxBoldChecked: string;
+/** Ballot box with X (☒). */
+export const ballotBoxX: string;
+
+/** Check mark (✓). */
+export const checkMark: string;
+/** Heavy check mark (✔). */
+export const checkMarkHeavy: string;
+/** Light check mark (✓-variant). */
+export const checkMarkLight: string;
+
+/** Ballot X (✗). */
+export const ballotX: string;
+/** Heavy ballot X (✘). */
+export const ballotXHeavy: string;
+/** Light ballot X (✗-variant). */
+export const ballotXLight: string;

package/src/symbols.js

@@ -1,3 +1,8 @@
+/** @module symbols
+ * A collection of frequently used Unicode characters for drawing lines, tables, charts, and other visual elements.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Module:-symbols}
+ */
+
 const generateSequence = (base, from, to) => {
   const result = [];
 
@@ -16,33 +21,61 @@ const generateSequence = (base, from, to) => {
 
 // blocks
 
+/** Vertical block elements in 1/8th increments (index 0 = space, 7 = full block).
+ * @type {string[]}
+ */
 export const vBlocks8th = [' ', ...generateSequence(0x2581, 0, 7)];
+/** Horizontal block elements in 1/8th increments (index 0 = space, 7 = full block).
+ * @type {string[]}
+ */
 export const hBlocks8th = [' ', ...generateSequence(0x2588, 7, 0, -1)];
+/** Full block character (█). */
 export const fullBlock = '\u{2588}';
 
+/** Left 1/8th block line. */
 export const lLine = hBlocks8th[1];
+/** Right 1/8th block line. */
 export const rLine = `\u{2595}`;
+/** Top 1/8th block line. */
 export const tLine = `\u{2594}`;
+/** Bottom 1/8th block line. */
 export const bLine = vBlocks8th[1];
 
+/** Left half block. */
 export const lHalf = hBlocks8th[4];
+/** Right half block. */
 export const rHalf = `\u{2590}`;
+/** Top half block. */
 export const tHalf = `\u{2580}`;
+/** Bottom half block. */
 export const bHalf = vBlocks8th[4];
 
+/** Top-left quadrant block. */
 export const tlQuadrant = '\u{2598}';
+/** Bottom-left quadrant block. */
 export const blQuadrant = '\u{2596}';
+/** Top-right quadrant block. */
 export const trQuadrant = '\u{259D}';
+/** Bottom-right quadrant block. */
 export const brQuadrant = '\u{2597}';
 
+/** Top-left + bottom-right diagonal quadrants. */
 export const tlBrQuadrants = `\u{259A}`;
+/** Top-right + bottom-left diagonal quadrants. */
 export const trBlQuadrants = `\u{259E}`;
 
+/** Negative (inverse) top-left quadrant. */
 export const tlNegativeQuadrant = '\u{259F}';
+/** Negative (inverse) bottom-left quadrant. */
 export const blNegativeQuadrant = '\u{259C}';
+/** Negative (inverse) top-right quadrant. */
 export const trNegativeQuadrant = '\u{2599}';
+/** Negative (inverse) bottom-right quadrant. */
 export const brNegativeQuadrant = '\u{259B}';
 
+/** All 16 quadrant block characters indexed by bitmask (TL=1, TR=2, BL=4, BR=8).
+ * @type {string[]}
+ */
 export const quadrants = [
   ' ',
   tlQuadrant,
@@ -62,70 +95,121 @@ export const quadrants = [
   fullBlock
 ];
 
+/** Returns the quadrant character for the given corner flags.
+ * @param {boolean} tl - Top-left.
+ * @param {boolean} tr - Top-right.
+ * @param {boolean} bl - Bottom-left.
+ * @param {boolean} br - Bottom-right.
+ * @returns {string}
+ */
 export const quadrant = (tl, tr, bl, br) => quadrants[(tl ? 1 : 0) + (tr ? 2 : 0) + (bl ? 4 : 0) + (br ? 8 : 0)];
 
 // shades
 
+/** Shade characters from empty to full: space, light, medium, dark, full block.
+ * @type {string[]}
+ */
 export const shades = [' ', ...generateSequence(0x2591, 0, 2), fullBlock];
 
+/** Light shade character (░). */
 export const shadeLight = shades[1];
+/** Medium shade character (▒). */
 export const shadeMedium = shades[2];
+/** Dark shade character (▓). */
 export const shadeDark = shades[3];
 
 // ellipses
 
-export const hellip = '\u{2026}'; // horizontal ellipsis
-export const vellip = '\u{22EE}'; // vertical ellipsis
-export const ctdot = '\u{22EF}'; // midline horizontal ellipsis
-export const utdot = '\u{22F0}'; // up right diagonal ellipsis
-export const dtdot = '\u{22F1}'; // down right diagonal ellipsis
+/** Horizontal ellipsis (…). */
+export const hellip = '\u{2026}';
+/** Vertical ellipsis (⋮). */
+export const vellip = '\u{22EE}';
+/** Centered triple dots (⋯). */
+export const ctdot = '\u{22EF}';
+/** Up-pointing triple dots (⋰). */
+export const utdot = '\u{22F0}';
+/** Down-pointing triple dots (⋱). */
+export const dtdot = '\u{22F1}';
 
 export {hellip as ellipsis};
 
 // math
 
+/** Infinity symbol (∞). */
 export const infinity = '\u{221e}';
+/** Plus-minus sign (±). */
 export const plusMinus = '\u{00B1}';
+/** Minus-plus sign (∓). */
 export const minusPlus = '\u{2213}';
+/** Tilde operator (∼). */
 export const tilde = '\u{223C}';
+/** Minus sign (−). */
 export const minus = '\u{2212}';
+/** Multiplication sign (×). */
 export const multiplication = '\u{00D7}';
+/** Division sign (÷). */
 export const division = '\u{00F7}';
+/** N-ary product (∏). */
 export const product = '\u{220F}';
+/** N-ary summation (∑). */
 export const sum = '\u{2211}';
+/** For all (∀). */
 export const forAll = '\u{2200}';
+/** There exists (∃). */
 export const exist = '\u{2203}';
+/** Degree sign (°). */
 export const degree = '\u{00B0}';
 
 export {multiplication as times};
 
+/** Superscript plus (⁺). */
 export const superscriptPlus = '\u{207A}';
+/** Superscript minus (⁻). */
 export const superscriptMinus = '\u{207B}';
+/** Subscript plus (₊). */
 export const subscriptPlus = '\u{208A}';
+/** Subscript minus (₋). */
 export const subscriptMinus = '\u{208B}';
 
-export const permille = '\u{2030}'; // per thousand
-export const permyriad = '\u{2031}'; // per ten thousand
+/** Per mille sign (‰). */
+export const permille = '\u{2030}';
+/** Per myriad sign (‱). */
+export const permyriad = '\u{2031}';
 
 // dashes
 
+/** Hyphen (‐). */
 export const hyphen = '\u{2010}';
+/** Figure dash (‒). */
 export const figureDash = '\u{2012}';
+/** En dash (–). */
 export const ndash = '\u{2013}';
+/** Em dash (—). */
 export const mdash = '\u{2014}';
+/** Horizontal bar (―). */
 export const horbar = '\u{2015}';
 
 // marks
 
+/** Ballot box (☐). */
 export const ballotBox = '\u{2610}';
+/** Ballot box with check (☑). */
 export const ballotBoxChecked = '\u{2611}';
+/** Ballot box with bold check (🗹). */
 export const ballotBoxBoldChecked = '\u{1f5f9}';
+/** Ballot box with X (☒). */
 export const ballotBoxX = '\u{2612}';
 
+/** Check mark (✓). */
 export const checkMark = '\u{2713}';
+/** Heavy check mark (✔). */
 export const checkMarkHeavy = '\u{2714}';
+/** Light check mark (🗸). */
 export const checkMarkLight = '\u{1f5f8}';
 
+/** Ballot X (✖). */
 export const ballotX = '\u{2716}';
+/** Heavy ballot X (✗). */
 export const ballotXHeavy = '\u{2717}';
+/** Light ballot X (🗷). */
 export const ballotXLight = '\u{1f5f7}';

package/src/table/draw-borders.d.ts

@@ -0,0 +1,38 @@
+import Box from '../box.js';
+import {LineTheme} from '../themes/utils.js';
+
+/** A rectangular region to skip when drawing borders (merged cell area). */
+export interface SkipRect {
+  /** Left column. */
+  x: number;
+  /** Top row. */
+  y: number;
+  /** Width in columns. */
+  width: number;
+  /** Height in rows. */
+  height: number;
+}
+
+/** Options for `draw()`. */
+export interface DrawOptions {
+  /** Rectangular regions to skip (merged cells). */
+  skip?: SkipRect[];
+  /** Fill symbol for cell interiors (default: ' '). */
+  symbol?: string;
+}
+
+/** Draws table borders based on a line theme and axis definitions.
+ * @param lineTheme - Line theme object defining border characters.
+ * @param hAxis - Horizontal axis pattern.
+ * @param vAxis - Vertical axis pattern.
+ * @param options - Draw options.
+ * @returns A Box containing the drawn borders.
+ */
+export function draw(
+  lineTheme: LineTheme,
+  hAxis: (string | number)[],
+  vAxis: (string | number)[],
+  options?: DrawOptions
+): Box;
+
+export default draw;

package/src/table/draw-borders.js

@@ -13,8 +13,7 @@ import Box from '../box.js';
 
 const isSkipped = (skip, x, y) => {
   for (const rect of skip) {
-    if (rect.x <= x && x < rect.x + rect.width && rect.y <= y && y < rect.y + rect.height)
-      return true;
+    if (rect.x <= x && x < rect.x + rect.width && rect.y <= y && y < rect.y + rect.height) return true;
   }
   return false;
 };
@@ -69,6 +68,15 @@ const drawRow = (lineTheme, hAxis, vAxis, skip, symbol, y, i) =>
     })
     .join('');
 
+/** Draws table borders using a line theme and axis definitions.
+ * @param {object} lineTheme - The line theme defining border characters.
+ * @param {(string|number)[]} hAxis - Horizontal axis definition (alternating style/size values).
+ * @param {(string|number)[]} vAxis - Vertical axis definition (alternating style/size values).
+ * @param {object} [options] - Options.
+ * @param {{x: number, y: number, width: number, height: number}[]} [options.skip=[]] - Rectangles to skip (for merged cells).
+ * @param {string} [options.symbol=' '] - Fill character for cell interiors.
+ * @returns {import('../box.js').Box} A Box with the drawn borders.
+ */
 export const draw = (lineTheme, hAxis, vAxis, {skip = [], symbol = ' '} = {}) =>
   new Box(
     vAxis

package/src/table/index.d.ts

@@ -0,0 +1,8 @@
+import {draw} from './draw-borders.js';
+import Table from './table.js';
+
+export {Table, draw};
+/** Shortcut for `Table.make()`. */
+export const make: typeof Table.make;
+
+export default make;

package/src/table/index.js

@@ -2,6 +2,7 @@ import draw from './draw-borders.js';
 import Table from './table.js';
 
 export {Table, draw};
+/** Shortcut for `Table.make()`. */
 export const make = Table.make;
 
 export default make;