Str.Visual.Table

Import

Namespace

import { Str } from '@wollybeard/kit'

// Access via namespace
Str.Visual.Table

Barrel

import { Table } from '@wollybeard/kit/str'

Text Formatting

[T] Cell

type Cell = string

Visual-aware table operations for multi-column text layout.

Tables are row-major 2D arrays where table[row][col] accesses individual cells. All operations use visual width (ANSI-aware) for alignment and measurement.

Examples:

import { Str } from '@wollybeard/kit'

// Create table from row data
const table = [
  ['Name', 'Age'],
  ['Alice', '30'],
]

// Render with visual alignment
Str.Visual.Table.render(table)
// "Name   Age"
// "Alice  30"

// With ANSI codes
const colored = [['\x1b[31mRed\x1b[0m', 'Normal']]
Str.Visual.Table.render(colored, { separator: ' | ' })
// "Red | Normal"  (correctly aligned despite ANSI)

[T] Row

type Row = Cell[]

Row of cells in a table.

[T] Table

type Table = Row[]

Row-major 2D table of text cells.

Access pattern: table[rowIndex][columnIndex] Can be jagged (rows with different lengths).

[I] RenderOptions

interface RenderOptions {
  /**
   * String to place between columns.
   * @default '   ' (three spaces)
   */
  separator?: string

  /**
   * How to align content within columns.
   * @default 'left'
   */
  align?: 'left' | 'right'

  /**
   * Explicit column widths. If omitted, auto-calculated from content.
   * Useful for forcing specific column sizes.
   */
  columnWidths?: number[]
}

Options for rendering tables into formatted text.

[F] render

(table: Table, options?: RenderOptions | undefined): string

Parameters:

• table - The table to render
• options - Formatting options

Returns: Multi-line string with aligned columns

Render table rows into a formatted multi-line string.

Each column is aligned to its maximum visual width (or explicit width if provided). Missing cells in jagged arrays are treated as empty strings.

Examples:

const table = [
  ['Name', 'Age', 'City'],
  ['Alice', '30', 'NYC'],
  ['Bob', '25', 'LA'],
]

Str.Visual.Table.render(table)
// "Name   Age  City"
// "Alice  30   NYC"
// "Bob    25   LA"

Str.Visual.Table.render(table, { separator: ' | ', align: 'right' })
// " Name | Age | City"
// "Alice |  30 |  NYC"
// "  Bob |  25 |   LA"

[C] renderOn

;((table: Table) => (options?: RenderOptions | undefined) => string)

Curried version of render with table first.

[C] renderWith

;((options?: RenderOptions | undefined) => (table: Table) => string)

Curried version of render with options first.

[F] renderColumns

(columns: string[][], options?: RenderOptions | undefined): string

Parameters:

• columns - Array of columns, each column is an array of cell values
• options - Formatting options

Returns: Multi-line string with aligned columns

Render columns of text as aligned output.

Takes column-oriented data where each column can have multiple lines. Columns with different heights are padded with empty strings. Transposes the column data to row-oriented format before rendering.

Examples:

// Column-oriented data
const columns = [
  ['Name', 'Alice', 'Bob'], // Column 1
  ['Age', '30', '25'], // Column 2
]

Str.Visual.Table.renderColumns(columns)
// "Name   Age"
// "Alice  30"
// "Bob    25"

// Handles jagged arrays
const jagged = [
  ['A', 'B'],
  ['X', 'Y', 'Z'],
]
Str.Visual.Table.renderColumns(jagged)
// "A  X"
// "B  Y"
// "   Z"

[C] renderColumnsOn

;((columns: string[][]) => (options?: RenderOptions | undefined) => string)

Curried version of renderColumns with columns first.

[C] renderColumnsWith

;((options?: RenderOptions | undefined) => (columns: string[][]) => string)

Curried version of renderColumns with options first.

[F] columnWidths

(table: Table): number[]

Parameters:

• table - The table to measure

Returns: Array of column widths

Calculate the visual width of each column.

Returns an array where each element is the maximum visual width of cells in that column.

Examples:

const table = [
  ['hi', 'world'],
  ['hello', 'x'],
]

Str.Visual.Table.columnWidths(table)
// [5, 5]  (max of 'hi'/'hello', max of 'world'/'x')

[F] dimensions

(table: Table): { rows: number; columns: number; }

Parameters:

• table - The table to measure

Returns: Object with row and column counts

Get the dimensions of a table.

Examples:

const table = [['a', 'b'], ['c']]
Str.Visual.Table.dimensions(table)
// { rows: 2, columns: 2 }

[F] normalize

(table: Table): Table

Parameters:

• table - The table to normalize

Returns: Rectangular table

Normalize a jagged table to be rectangular.

Fills missing cells with empty strings so all rows have the same length.

Examples:

const jagged = [['a', 'b'], ['c']]
Str.Visual.Table.normalize(jagged)
// [['a', 'b'], ['c', '']]