console-toolkit 1.2.9 → 1.2.11

package/src/table/table.d.ts

@@ -0,0 +1,239 @@
+import Box from '../box.js';
+import Panel from '../panel.js';
+import {SgrState} from '../ansi/sgr-state.js';
+import {StringsInput} from '../strings.js';
+import {LineTheme} from '../themes/utils.js';
+
+/** Input type for a single table cell: a raw value, a CellData object, or null. */
+export type TableCellInput = string | number | boolean | Box | Panel | CellData | null | undefined;
+
+/** Data for a single table cell. */
+export interface CellData {
+  /** Cell content (string, Box, Panel, or other renderable). */
+  value: StringsInput;
+  /** Horizontal alignment override for this cell. */
+  align?: string;
+  /** Column span (number of columns this cell occupies). */
+  width?: number;
+  /** Row span (number of rows this cell occupies). */
+  height?: number;
+}
+
+/** Cell padding configuration. */
+export interface CellPadding {
+  /** Left padding in columns. */
+  l?: number;
+  /** Right padding in columns. */
+  r?: number;
+  /** Top padding in rows. */
+  t?: number;
+  /** Bottom padding in rows. */
+  b?: number;
+}
+
+/** Options for the Table constructor. */
+export interface TableOptions {
+  /** Horizontal axis definition (border/separator pattern). */
+  hAxis?: string | (string | number)[];
+  /** Vertical axis definition (border/separator pattern). */
+  vAxis?: string | (string | number)[];
+  /** Horizontal alignment per column. */
+  hAlign?: string | string[];
+  /** Vertical alignment per row. */
+  vAlign?: string | string[];
+  /** Minimum column widths. */
+  hMin?: number | number[];
+  /** Minimum row heights. */
+  vMin?: number | number[];
+  /** Cell padding. */
+  cellPadding?: CellPadding;
+}
+
+/** Options for `Table.draw()`. */
+export interface TableDrawOptions {
+  /** SGR state applied to table border lines. */
+  lineState?: SgrState;
+}
+
+/** Options for `Table.generateAxes()`. */
+export interface GenerateAxesOptions {
+  /** Horizontal line theme name. */
+  hTheme?: string;
+  /** Vertical line theme name. */
+  vTheme?: string;
+  /** Top border style. */
+  borderTop?: string | number;
+  /** Right border style. */
+  borderRight?: string | number;
+  /** Left border style. */
+  borderLeft?: string | number;
+  /** Bottom border style. */
+  borderBottom?: string | number;
+  /** First row separator style. */
+  rowFirst?: string | number;
+  /** Last row separator style. */
+  rowLast?: string | number;
+  /** First column separator style. */
+  columnFirst?: string | number;
+  /** Last column separator style. */
+  columnLast?: string | number;
+  /** Horizontal data separator style. */
+  hDataSep?: string | number;
+  /** Vertical data separator style. */
+  vDataSep?: string | number;
+
+  /** Default horizontal alignment. */
+  hAlignDefault?: string;
+  /** Column indices aligned left. */
+  hLeft?: number[];
+  /** Column indices aligned center. */
+  hCenter?: number[];
+  /** Column indices aligned right. */
+  hRight?: number[];
+
+  /** Default vertical alignment. */
+  vAlignDefault?: string;
+  /** Row indices aligned top. */
+  vTop?: number[];
+  /** Row indices aligned center. */
+  vCenter?: number[];
+  /** Row indices aligned bottom. */
+  vBottom?: number[];
+
+  /** Default minimum column width. */
+  hMinDefault?: number;
+  /** Minimum widths per column index. */
+  hMin?: Record<number, number>;
+
+  /** Default minimum row height. */
+  vMinDefault?: number;
+  /** Minimum heights per row index. */
+  vMin?: Record<number, number>;
+}
+
+/** SGR styles applied to table data cells. */
+export interface DataStyleOptions {
+  /** Style for the first row. */
+  rowFirst?: SgrState;
+  /** Style for the last row. */
+  rowLast?: SgrState;
+  /** Style for the first column. */
+  columnFirst?: SgrState;
+  /** Style for the last column. */
+  columnLast?: SgrState;
+  /** Default style for data cells. */
+  data?: SgrState;
+  /** Style for odd rows. */
+  rowOdd?: SgrState;
+  /** Style for even rows. */
+  rowEven?: SgrState;
+  /** Style for odd columns. */
+  columnOdd?: SgrState;
+  /** Style for even columns. */
+  columnEven?: SgrState;
+}
+
+/** Options for `Table.make()`, combining axis generation and data styling. */
+export interface MakeOptions extends GenerateAxesOptions {
+  /** Data cell styles. */
+  states?: DataStyleOptions;
+}
+
+/** Renders tabular data with borders, alignment, and merged cells.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Package:-table}
+ */
+export class Table {
+  /** Number of data rows. */
+  height: number;
+  /** Number of data columns. */
+  width: number;
+  /** The raw data grid. */
+  data: TableCellInput[][];
+  /** Computed column widths. */
+  widths: number[];
+  /** Computed row heights. */
+  heights: number[];
+  /** Line theme for borders. */
+  lineTheme: LineTheme;
+  /** List of cells to skip (merged cell regions). */
+  skipList: {x: number; y: number; width: number; height: number}[];
+  /** Resolved table options. */
+  options: {
+    hAxis: string | (string | number)[];
+    vAxis: string | (string | number)[];
+    hAlign: string[];
+    vAlign: string[];
+  };
+  /** Resolved cell padding. */
+  cellPadding: Required<CellPadding>;
+  /** Horizontal axis pattern. */
+  hAxis: (string | number)[];
+  /** Vertical axis pattern. */
+  vAxis: (string | number)[];
+  /** Processed cell grid. */
+  cells: (object | null)[][];
+
+  /**
+   * @param data - 2D array of cell data.
+   * @param lineTheme - Line theme for borders.
+   * @param options - Table options.
+   */
+  constructor(data: TableCellInput[][], lineTheme: LineTheme, options?: TableOptions);
+
+  /** Draws the table as a Panel.
+   * @param options - Draw options.
+   * @returns A Panel.
+   */
+  draw(options?: TableDrawOptions): Panel;
+  /** Draws the table as a Panel.
+   * @param options - Draw options.
+   * @returns A Panel.
+   */
+  toPanel(options?: TableDrawOptions): Panel;
+  /** Draws the table as a Box.
+   * @param options - Draw options.
+   * @returns A Box.
+   */
+  toBox(options?: TableDrawOptions): Box;
+  /** Draws the table as a string array.
+   * @param options - Draw options.
+   * @returns Array of strings.
+   */
+  toStrings(options?: TableDrawOptions): string[];
+
+  /** Checks if a cell at (x, y) is visible (not hidden by a merged cell).
+   * @param x - Column index.
+   * @param y - Row index.
+   * @returns True if visible.
+   */
+  isVisible(x: number, y: number): boolean;
+
+  /** Generates axis options from dimensions and configuration.
+   * @param width - Number of columns.
+   * @param height - Number of rows.
+   * @param options - Generation options.
+   * @returns Table options with axis definitions.
+   */
+  static generateAxes(width: number, height: number, options: GenerateAxesOptions): TableOptions;
+  /** Processes data cells, applying styles.
+   * @param data - 2D array of cell data.
+   * @param options - Data style options.
+   * @returns Processed data grid.
+   */
+  static processData(data: TableCellInput[][], options?: DataStyleOptions): TableCellInput[][];
+  /** Factory method that generates axes, processes data, and creates a Table.
+   * @param data - 2D array of cell data.
+   * @param lineTheme - Line theme for borders.
+   * @param options - Make options.
+   * @param overrides - Additional table option overrides.
+   * @returns A new Table.
+   */
+  static make(
+    data: TableCellInput[][],
+    lineTheme: LineTheme,
+    options?: MakeOptions,
+    overrides?: Partial<TableOptions>
+  ): Table;
+}
+
+export default Table;

package/src/table/table.js

@@ -29,7 +29,22 @@ const dataInstructions = 'rowFirst,rowLast,columnFirst,columnLast,data,rowOdd,ro
 
 const DIM_STATE = style.dim.getState();
 
+/** Creates and renders tables with themes, supporting cell alignment, merged cells, and border drawing.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Package:-table}
+ */
 export class Table {
+  /**
+   * @param {any[][]} data - 2D array of cell data. Each cell can be a value, or `{value, align, width, height}`.
+   * @param {object} lineTheme - The line theme for borders.
+   * @param {object} [options] - Options.
+   * @param {string|(string|number)[]} [options.hAxis='1'] - Horizontal axis definition.
+   * @param {string|(string|number)[]} [options.vAxis='1'] - Vertical axis definition.
+   * @param {string|string[]} [options.hAlign=[]] - Horizontal alignment per column.
+   * @param {string|string[]} [options.vAlign=[]] - Vertical alignment per row.
+   * @param {number|number[]} [options.hMin=0] - Minimum column widths.
+   * @param {number|number[]} [options.vMin=0] - Minimum row heights.
+   * @param {{l?: number, r?: number, t?: number, b?: number}} [options.cellPadding={}] - Cell padding.
+   */
   constructor(data, lineTheme, options = {}) {
     let {hAxis = '1', vAxis = '1', hAlign = [], vAlign = [], hMin = 0, vMin = 0, cellPadding = {}} = options;
 
@@ -76,7 +91,10 @@ export class Table {
         const isObject = data?.hasOwnProperty('value'),
           value = isObject ? data.value : data,
           align = (isObject && data.align) || '',
-          box = value instanceof Box ? value : Box.make(value, {symbol: ' ', align: getCellAlign(align, 0) || hAlign[j] || 'left'}),
+          box =
+            value instanceof Box
+              ? value
+              : Box.make(value, {symbol: ' ', align: getCellAlign(align, 0) || hAlign[j] || 'left'}),
           width = box.width,
           height = box.height,
           cellWidth = isObject ? data.width || 1 : 1,
@@ -122,6 +140,11 @@ export class Table {
   }
 
   // TODO: accept `states`, draw even/odd rows/columns, support bg on lines optionally
+  /** Draws the table as a Panel with borders and cell content.
+   * @param {object} [options] - Options.
+   * @param {object} [options.lineState] - SGR state for border lines (defaults to dim).
+   * @returns {import('../panel.js').default} A Panel with the rendered table.
+   */
   draw({lineState = DIM_STATE} = {}) {
     // prepare axes
 
@@ -177,18 +200,35 @@ export class Table {
     return panel;
   }
 
+  /** Converts the table to a Panel.
+   * @param {object} [options] - Options passed to `draw()`.
+   * @returns {import('../panel.js').default}
+   */
   toPanel(options) {
     return this.draw(options);
   }
 
+  /** Converts the table to a Box.
+   * @param {object} [options] - Options passed to `draw()`.
+   * @returns {import('../box.js').default}
+   */
   toBox(options) {
     return this.toPanel(options).toBox(options);
   }
 
+  /** Converts the table to an array of strings.
+   * @param {object} [options] - Options passed to `draw()`.
+   * @returns {string[]}
+   */
   toStrings(options) {
     return this.toBox(options).toStrings();
   }
 
+  /** Checks if a cell is visible (not hidden by a merged cell).
+   * @param {number} x - Column index.
+   * @param {number} y - Row index.
+   * @returns {boolean}
+   */
   isVisible(x, y) {
     const i = 2 * y + 1,
       j = 2 * x + 1;
@@ -199,6 +239,12 @@ export class Table {
     return true;
   }
 
+  /** Generates axis definitions and alignment arrays from a declarative options object.
+   * @param {number} width - Number of columns.
+   * @param {number} height - Number of rows.
+   * @param {object} options - Axis generation options.
+   * @returns {object} An object with `hAxis`, `vAxis`, `hAlign`, `vAlign`, `hMin`, `vMin`.
+   */
   static generateAxes(
     width,
     height,
@@ -278,6 +324,11 @@ export class Table {
     return {hAxis, vAxis, hAlign, vAlign, hMin: hMinArray, vMin: vMinArray};
   }
 
+  /** Processes data by applying styles to rows, columns, and special positions.
+   * @param {any[][]} data - The raw data.
+   * @param {object} [options] - Style options with properties like `rowFirst`, `rowLast`, `data`, `rowOdd`, etc.
+   * @returns {any[][]} The styled data.
+   */
   static processData(data, options) {
     if (!options) return data;
 
@@ -322,6 +373,13 @@ export class Table {
     });
   }
 
+  /** Convenience factory that generates axes, processes data, and creates a Table.
+   * @param {any[][]} data - The raw data.
+   * @param {object} lineTheme - The line theme.
+   * @param {object} [options] - Combined axis generation and style options.
+   * @param {object} [overrides] - Additional overrides for the Table constructor options.
+   * @returns {Table}
+   */
   static make(data, lineTheme, options, overrides) {
     return new Table(Table.processData(data, options?.states), lineTheme, {
       ...(options && Table.generateAxes(data.length && data[0].length, data.length, options)),

package/src/themes/blocks/unicode-half.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** Unicode half-block theme. */
+export const blockTheme: LineTheme;
+
+export default blockTheme;

package/src/themes/blocks/unicode-half.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** Unicode half-block theme. */
 export const blockTheme = {};
 
 const table11 = {t: '▗▄▖', m: '▐ ▌', b: '▝▀▘', v: '▐ ▌', h: '▄ ▀', f: '█'};

package/src/themes/blocks/unicode-thin.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** Unicode thin-block theme. */
+export const blockTheme: LineTheme;
+
+export default blockTheme;

package/src/themes/blocks/unicode-thin.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** Unicode thin-block theme. */
 export const blockTheme = {};
 
 const table11 = {t: ' ▁ ', m: '▕ ▏', b: ' ▔ ', v: '▕ ▏', h: '▁ ▔', f: '█'};

package/src/themes/lines/ascii-compact.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** Compact ASCII line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/ascii-compact.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** Compact ASCII line theme. */
 export const lineTheme = {};
 
 const table11 = {t: '   ', m: '   ', b: '   ', v: '   ', h: '---'},

package/src/themes/lines/ascii-dots.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** ASCII dots line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/ascii-dots.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** ASCII dots line theme. */
 export const lineTheme = {};
 
 const dots = {t: '...', m: '.:.', b: ':::', v: ':::', h: '...'};

package/src/themes/lines/ascii-girder.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** ASCII girder line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/ascii-girder.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** ASCII girder line theme. */
 export const lineTheme = {};
 
 const girder = {t: '//[]\\\\', m: '|][][|', b: '\\\\[]//', v: '||||||', h: '===', w: 2};

package/src/themes/lines/ascii-github.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** ASCII GitHub-style line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/ascii-github.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** ASCII GitHub-style line theme. */
 export const lineTheme = {};
 
 const markdownGithub11 = {t: '|||', m: '|||', b: '|||', v: '|||', h: '---'},

package/src/themes/lines/ascii-reddit.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** ASCII Reddit-style line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/ascii-reddit.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** ASCII Reddit-style line theme. */
 export const lineTheme = {};
 
 const markdownReddit11 = {t: ' | ', m: ' | ', b: ' | ', v: ' | ', h: '---'},

package/src/themes/lines/ascii-rounded.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** ASCII rounded line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/ascii-rounded.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** ASCII rounded line theme. */
 export const lineTheme = {};
 
 const rounded11 = {t: '...', m: ':+:', b: "'''", v: '|||', h: '---'},

package/src/themes/lines/ascii.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** ASCII line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/ascii.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** ASCII line theme. */
 export const lineTheme = {};
 
 const table11 = {t: '+++', m: '+++', b: '+++', v: '|||', h: '---'},

package/src/themes/lines/unicode-bold.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** Unicode bold box-drawing line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/unicode-bold.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** Unicode bold box-drawing line theme. */
 export const lineTheme = {};
 
 const table11 = {t: '┌┬┐', m: '├┼┤', b: '└┴┘', v: '│││', h: '───'},

package/src/themes/lines/unicode-rounded.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** Unicode rounded box-drawing line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/unicode-rounded.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** Unicode rounded box-drawing line theme. */
 export const lineTheme = {};
 
 const table11 = {t: '╭┬╮', m: '├┼┤', b: '╰┴╯', v: '│││', h: '───'},

package/src/themes/lines/unicode.d.ts

@@ -0,0 +1,6 @@
+import {LineTheme} from '../utils.js';
+
+/** Unicode box-drawing line theme. */
+export const lineTheme: LineTheme;
+
+export default lineTheme;

package/src/themes/lines/unicode.js

@@ -1,5 +1,6 @@
 import {populateTheme} from '../utils.js';
 
+/** Unicode box-drawing line theme. */
 export const lineTheme = {};
 
 const table11 = {t: '┌┬┐', m: '├┼┤', b: '└┴┘', v: '│││', h: '───'},

package/src/themes/utils.d.ts

@@ -0,0 +1,33 @@
+/** Defines the characters used for table borders at various positions. */
+export interface TableDefinition {
+  /** Top border characters. */
+  t: string;
+  /** Middle (row separator) border characters. */
+  m: string;
+  /** Bottom border characters. */
+  b: string;
+  /** Vertical border characters. */
+  v: string;
+  /** Horizontal border characters. */
+  h: string;
+  /** Character width (default: 1). */
+  w?: number;
+  /** Fill character. */
+  f?: string;
+}
+
+/** A line theme mapping theme keys to border/line character definitions. */
+export type LineTheme = Record<string, string | number | string[]>;
+
+/** Populates a line theme with characters from a table definition.
+ * @param lineTheme - The theme object to populate.
+ * @param tableDefinition - The table border character definitions.
+ * @param hTheme - Horizontal theme identifier.
+ * @param vTheme - Vertical theme identifier.
+ */
+export function populateTheme(
+  lineTheme: LineTheme,
+  tableDefinition: TableDefinition,
+  hTheme: number | string,
+  vTheme: number | string
+): void;

package/src/themes/utils.js

@@ -10,6 +10,13 @@
 
 // The default value for 'w': 1
 
+/** Populates a line theme object from a table definition matrix.
+ * Sets `t_`, `h_`, `v_`, `w_`, and `f` properties on the lineTheme.
+ * @param {object} lineTheme - The line theme object to populate.
+ * @param {object} tableDefinition - Definition with `t`, `m`, `b`, `v`, `h`, optional `w` and `f` properties.
+ * @param {string|number} hTheme - Horizontal theme identifier.
+ * @param {string|number} vTheme - Vertical theme identifier.
+ */
 export const populateTheme = (lineTheme, tableDefinition, hTheme, vTheme) => {
   const w = tableDefinition.w || 1,
     s = [0, w, w << 1],

package/src/turtle/draw-line-art.d.ts

@@ -0,0 +1,19 @@
+import Box from '../box.js';
+import Turtle from './turtle.js';
+import {LineTheme} from '../themes/utils.js';
+
+/** Options for `draw()`. */
+export interface DrawLineArtOptions {
+  /** Character to use for ignored (empty) cells. */
+  ignore?: string;
+}
+
+/** Draws a Turtle's path as line art using a line theme.
+ * @param turtle - The Turtle instance.
+ * @param lineTheme - Line theme object defining line characters.
+ * @param options - Draw options.
+ * @returns A Box containing the drawn line art.
+ */
+export function draw(turtle: Turtle, lineTheme: LineTheme, options?: DrawLineArtOptions): Box;
+
+export default draw;

package/src/turtle/draw-line-art.js

@@ -15,6 +15,13 @@ const getIndex = cell => {
   return {skipFlag, hTheme, vTheme, hIndex, vIndex};
 };
 
+/** Draws a Turtle's path as line art using a line theme.
+ * @param {import('./turtle.js').Turtle} turtle - The turtle to draw.
+ * @param {object} lineTheme - The line theme defining border characters.
+ * @param {object} [options] - Options.
+ * @param {string} [options.ignore=' '] - Character for empty cells.
+ * @returns {import('../box.js').Box} A Box with the rendered line art.
+ */
 export const draw = (turtle, lineTheme, {ignore = ' '} = {}) =>
   new Box(
     turtle.cells.map(row =>

package/src/turtle/draw-unicode.d.ts

@@ -0,0 +1,19 @@
+import Box from '../box.js';
+import Turtle from './turtle.js';
+
+/** Options for `draw()`. */
+export interface DrawUnicodeOptions {
+  /** Character to use for ignored (empty) cells. */
+  ignore?: string;
+  /** If true, use arc characters for corners instead of sharp corners. */
+  useArcs?: boolean;
+}
+
+/** Draws a Turtle's path using Unicode box-drawing characters.
+ * @param turtle - The Turtle instance.
+ * @param options - Draw options.
+ * @returns A Box containing the drawn path.
+ */
+export function draw(turtle: Turtle, options?: DrawUnicodeOptions): Box;
+
+export default draw;

package/src/turtle/draw-unicode.js

@@ -15,6 +15,14 @@ const arcs = {4: '╰', 12: '╭', 28: '╯', 36: '╮'};
 
 const getIndex = cell => (cell ? (((+cell.l || 0) * 3 + (+cell.d || 0)) * 3 + (+cell.r || 0)) * 3 + (+cell.u || 0) : 0);
 
+/** Draws a Turtle's path using Unicode box-drawing characters.
+ * Supports themes 1 (thin) and 2 (thick), and optional arc characters for corners.
+ * @param {import('./turtle.js').Turtle} turtle - The turtle to draw.
+ * @param {object} [options] - Options.
+ * @param {string} [options.ignore=' '] - Character for empty cells.
+ * @param {boolean} [options.useArcs] - If true, use rounded arc characters for corners.
+ * @returns {import('../box.js').Box} A Box with the rendered Unicode drawing.
+ */
 export const draw = (turtle, {ignore = ' ', useArcs} = {}) =>
   new Box(
     turtle.cells.map(row =>