Package: table - uhop/console-toolkit GitHub Wiki

The table package provides functions to draw tables. The tables support themes, data alignments, merging cells and more.

`table/index.js`

The table/index.js is the main user-facing module. It exports other modules:

draw — draws table borders. Re-exported from table/draw-borders.js.
Table — the table class. Re-exported from table/table.js.

The default export is the Table.make() function that helps to define a table.

`table/draw-borders.js`

The table/draw-borders.js module is used internally by the table package. It generates a table border as a Box.

Function `draw()`

The draw() function draws a table border using a line theme, axis definitions and skip lists, which define what cells are merged. It returns a Box.

draw(theme, hAxis, vAxis, options) has the following arguments:

theme — the table theme. See line themes for details.
hAxis — the horizontal axis represented as an array of cells and borders.
vAxis — the vertical axis represented as an array of cells and borders.
options — the table options:
- skip — an array of rectangles to skip borders. Defaults to an empty array ([]).
  - Rectangles are defined as {x, y, width, height} in terms of axes' indices. width and height are exclusive.
- symbol — the character used to fill the interior of cells. Defaults to a space (' ').

An axis is defined as an array. All even elements (starting with 0) are assumed to be borders and their values are sub-themes of the theme. (Usually themes have two sub-themes: 1 and 2). If the value is 0, the corresponding line is skipped. All odd elements (starting with 1) are assumed to be cells and their values are sizes in symbols.

If an element has a non-zero value it means that we have a line going through it. If an element is 0, it defines a cell.

The example below shows how draw() can be used to draw a frame with different styles. It draw a table with no cell:

import drawTable from 'console-toolkit/table/draw-borders.js';
import lineTheme from 'console-toolkit/themes/lines/unicode.js';

const box1 = drawTable(lineTheme, [1, 0, 1], [1, 0, 1]);
const box2 = drawTable(lineTheme, [2, 0, 2], [2, 0, 2]);
const box3 = drawTable(lineTheme, [1, 0, 2], [1, 0, 2]);
const box4 = drawTable(lineTheme,[2, 0, 1], [2, 0, 1]);

const box = box1.padRight(2).addRight(box2).
  padRight(2).addRight(box3).
  padRight(2).addRight(box4);
for (const line of box.box) console.log(line);

It produces the following output:

┌┐  ╔╗  ┌╖  ╔╕
└┘  ╚╝  ╘╝  ╙┘

skip can have rectangles to skip borders in terms of axes' indices:

import drawTable from 'console-toolkit/table/draw-borders.js';
import lineTheme from 'console-toolkit/themes/lines/unicode.js';

const box = drawTable(
  lineTheme,
  [1, 1, 1, 1, 2, 1, 2],
  [1, 1, 1, 1, 2, 1, 2],
  {
    skip: [
      {x: 1, y: 1, width: 3, height: 1},
      {x: 1, y: 3, width: 1, height: 3},
      {x: 3, y: 3, width: 3, height: 1}
    ]
  }
);
for (const line of box.box) console.log(line);

The output is:

┌───╥─╖
│   ║ ║
├─┬─╨─╢
│ │   ║
│ ╞═╦═╣
│ │ ║ ║
╘═╧═╩═╝

Exports

The module exports draw() by name and as the default export.

`table/table.js`

The table/table.js module provides the Table class.

Class `Table`

The Table class contains a table and can produce a text container (strings, a Box, or a Panel). It provides the following methods:

Name	Return type	Description
`constructor(data, lineTheme, options)`	`Table`	Creates a new table.
`hAxis`	array	The horizontal axis.
`vAxis`	array	The vertical axis.
`widths`	array	The widths of the cells.
`heights`	array	The heights of the cells.
`cells`	2D array	The cells of the table.
`draw(options)`	`Panel`	Draws the table.
`toPanel(options)`	`Panel`	An alias for `draw()`
`toBox(options)`	`Box`	Returns a box containing the table
`toStrings(options)`	strings	Returns an array of strings

The table object is usually made by the Table.make() static method. After that, you may update the resulting table properties to your needs, then draw it. These are updatable properties:

hAxis — the horizontal axis represented as an array of vertical borders. For example, if your table has two columns, then hAxis will be an array of three borders. A value can be 0 (no line), or a line sub-theme value, typically 1 (single line) or 2 (double/thick line).
vAxis — the vertical axis represented as an array of horizontal borders similar to hAxis.
widths — the widths of the cells for each column in characters not counting the borders and the cell padding.
heights — the heights of the cells for each row in characters similar to widths.

Changing values of these properties will be reflected in the resulting table when it is drawn by draw().

data is a 2D array of values or objects representing cells. The values can be:

null — an empty cell
An object with the following properties:
- value — the value of the cell. It can be a text container or any value that can be converted to a string or a text container.
- width — the width of the cell. Defaults to 1.
- height — the height of the cell. Defaults to 1.
- align — the alignment of the cell.
Any other value — the value of the cell, which will be converted to a text container (a number, a string, etc).

align is a string that encodes the horizontal and vertical alignments of the cell. The first character is the horizontal alignment and the second character is the vertical.

The first character can be one of: l, c, r (left, center, right) or d (default). The second character can be one of: t, c, b (top, center, bottom). If the second character is omitted, it assumed to be d (use the default).

constructor()'s options argument is an object with the following properties:

hAxis — the horizontal axis represented as an array of cells and borders. Defaults to 1.
- If it is a scalar value, it is repeated for all vertical lines.
vAxis — the vertical axis represented as an array of cells and borders. Defaults to 1.
- If it is a scalar value, it is repeated for all horizontal lines.
hAlign — the horizontal alignment of the table represented as an array. Defaults to d.
- If it is a scalar value, it is repeated for all cells.
vAlign — the vertical alignment of the table represented as an array. Defaults to d.
- If it is a scalar value, it is repeated for all cells.
hMin — the minimum width of the cells represented as an array. Defaults to 0.
- This option allows to set a minimal width for a column.
- If it is a scalar value, it is repeated for all cells.
vMin — the minimum height of the cells represented as an array. Defaults to 0.
- This option allows to set a minimal height for a row.
- If it is a scalar value, it is repeated for all cells.
cellPadding — the padding of the cells represented as an object: {l, r, t, b}.
- Defaults to {l: 1, r: 1, t: 0, b: 0}.

The options of draw(), toPanel(), toBox(), and toStrings() are the same. This objects can have the following properties:

lineState — the style state of the table lines. Defaults to style.dim.

The Table.make() static method returns a Table instance. It is the most common way to create a table. The function involves a preprocessor that updates data according to the options argument and forms necessary objects.

Table.make(data, lineTheme, options, overrides) has the following arguments:

data — the table data. See the data argument of the Table constructor.
lineTheme — the table line theme. See the lineTheme argument of the Table constructor.
options — the table options. It can have the following properties:
- states — an object, which provides style states for cells:
  - data — the style state of the data cells.
  - rowOdd — the style state for data cells in the odd rows.
  - rowEven — the style state for data cells in the even rows.
  - columnOdd — the style state for data cells in the odd columns.
  - columnEven — the style state for data cells in the even columns.
  - rowFirst — the style state for the first row.
  - rowLast — the style state for the last row.
  - columnFirst — the style state for the first column.
  - columnLast — the style state for the last column.
- hTheme — the table horizontal theme. See the hTheme argument of the Table constructor.
- vTheme — the table vertical theme. See the vTheme argument of the Table constructor.
- borderTop — the theme for the table top border.
- borderRight — the theme for the table right border.
- borderBottom — the theme for the table bottom border.
- borderLeft — the theme for the table left border.
- columnFirst — the theme for the first column.
- columnLast — the theme for the last column.
- rowFirst — the theme for the first row.
- rowLast — the theme for the last row.
- vDataSep — the theme for the vertical data separator.
- hDataSep — the theme for the horizontal data separator.
- hAlignDefault — the default horizontal alignment. Defaults to l.
- hLeft — the array of column numbers to be left-aligned. Defaults to [].
- hCenter — the array of column numbers to be centered. Defaults to [].
- hRight — the array of column numbers to be right-aligned. Defaults to [].
- vAlignDefault — the default vertical alignment. Defaults to t.
- vTop — the array of row numbers to be top-aligned. Defaults to [].
- vCenter — the array of row numbers to be centered. Defaults to [].
- vBottom — the array of row numbers to be bottom-aligned. Defaults to [].
- hMinDefault — the default minimum width of the cells. Defaults to 0.
- hMin — the object, which associates a minimal width with a column number. Defaults to {}.
- vMinDefault — the default minimum height of the cells. Defaults to 0.
- vMin — the object, which associates a minimal height with a row number. Defaults to {}.
overrides — an object, which provides overrides for the options argument of the Table constructor.

Example

import makeTable from 'console-toolkit/table/index.js';
import lineTheme from 'console-toolkit/themes/lines/unicode-rounded.js';
import {s} from 'console-toolkit/style.js';

const data = [
  [null, 'Quarter', 'Number'],
  [{value: 'Year\n2024', height: 4, align: 'dc'}, 'I', 31],
  [null, 'II', 41],
  [null, 'III', 59],
  [null, 'IV', 26],
  [{value: 'Total:', width: 2, align: 'r'}, null, s`{{bold}}157`]
];

const table = makeTable(data, lineTheme, {
  hCenter: [1],
  hRight: [2],
  columnLast: '2',
  rowFirst: '2',
  rowLast: '2',
  hDataSep: 0,
  states: {
    rowFirst: s`{{bold}}`,
    rowLast: s`{{bright.cyan}}`
  }
});

for (const line of table.toStrings()) console.log(line);

The output is:

╭──────┬─────────╥────────╮
│      │ Quarter ║ Number │
╞══════╪═════════╬════════╡
│      │    I    ║     31 │
│ Year │   II    ║     41 │
│ 2024 │   III   ║     59 │
│      │   IV    ║     26 │
╞══════╧═════════╬════════╡
│         Total: ║    157 │
╰────────────────╨────────╯

As an image:

Table

Exports

The module exports Table by name and as the default export.

Package: table - uhop/console-toolkit GitHub Wiki

table/index.js

table/draw-borders.js

Function draw()

Exports

table/table.js

Class Table

Example

Exports

`table/index.js`

`table/draw-borders.js`

Function `draw()`

`table/table.js`

Class `Table`