Tables

The because.table() builder constructs a TableGroup for use as span input or output.

Basic usage

because.addSpan('table', 'results', {
  output: because.table('Query Results').fromRecords(rows).round(2).build()
});

`because.table(title?)`

Returns a TableBuilder. Chain methods and call .build() to get a TableGroup.

Data sources

`.fromRecords(data)`

Build from an array of objects. Column names are derived from object keys.

because
  .table('Users')
  .fromRecords([
    { name: 'Alice', score: 98.5 },
    { name: 'Bob', score: 72.1 }
  ])
  .build();

`.fromObject(data)`

Build a key-value table from a plain object. Renders as two columns: Key and Value.

because
  .table('Config')
  .fromObject({ timeout: 5000, retries: 3, env: 'production' })
  .build();

Column selection

`.pick(...keys)`

Only include the specified columns, in order.

.pick('name', 'email', 'role')

Labels & formatting

`.label(map)`

Override column display labels.

.label({ usageKwh: 'Usage (kWh)', ratePerKwh: 'Rate ($/kWh)' })

`.round(decimals)`

Round all numeric values to decimals decimal places.

.round(2)

`.transformValues(map)`

Apply a transform function to values in specific columns.

.transformValues({
  status: (v) => String(v).toUpperCase(),
  createdAt: (v) => new Date(v as string).toLocaleDateString(),
})

`.noAutoLabel()`

Disable automatic camelCase → Sentence Case conversion for column names.

Highlighting

`.highlightColumn(key, highlight)`

Apply a highlight colour to an entire column header and cells.

.highlightColumn('revenue', 'success')

`.highlightRows(fn)`

Apply a per-row highlight based on the row's data.

.highlightRows((row) => {
  if ((row.errorRate as number) > 0.1) return 'danger';
  if ((row.errorRate as number) > 0.05) return 'warn';
  return null;
})

`.highlightCells(key, fn)`

Apply a per-cell highlight for a specific column.

.highlightCells('status', (v) => {
  if (v === 'error') return 'danger';
  if (v === 'ok') return 'success';
  return null;
})

Highlight values: 'danger' | 'warn' | 'success' | 'info' | 'muted'

Column spans

`.spanColumn(key, span)`

Make a column header span multiple columns.

.spanColumn('metrics', 3)

Extra rows

`.appendRow(cells, highlight?)`

Append a summary row at the bottom of the table.

.appendRow(['Total', 450, 890], 'info')

Use because.spanCell(value, span) to create a cell that spans multiple columns:

.appendRow([because.spanCell('Grand total: $1,234', 4)], 'success')

`.summary(stats)`

Define stats to show inline when this table is collapsed inside a multi-table span. Each stat has a text string and an optional highlight colour.

.summary([
  { text: '$64.70', highlight: 'info' },
  { text: '28.8% less', highlight: 'success' },
])

Without .summary(), the collapsed row shows only the table title. Use it whenever a table is one of many in a { tables: [] } span and you want a quick-scan value visible without expanding.

Highlight values: 'danger' | 'warn' | 'success' | 'info' | 'muted'

`because.spanCell(value, span)`

Creates a cell that spans span columns. Only useful inside .appendRow().

because.spanCell('Total Cost: $99.00', 3);

Multiple tables

Wrap multiple TableGroup objects to render them together in one span:

because.addSpan('table', 'report', {
  output: {
    tables: [
      because.table('Summary').fromObject(summary).build(),
      because.table('Breakdown').fromRecords(rows).round(2).build()
    ]
  }
});

On this page