# output/table

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

`table` renders structured data as a formatted ASCII table with header row, optional borders, and configurable column alignment. It computes column widths from the full data set — header and all rows — ensuring that every column is at least as wide as its widest cell. The result is a plain multi-line string ready for console output or piping.

The function is pure: it takes a `TableOptions` object and returns a `string`. No state, no I/O, no mutations.

## Features

- Automatic column width calculation: each column is as wide as its widest cell across all rows
- Three alignment modes per column: `"left"` (default), `"right"`, `"center"`
- Border mode (default on): header and data rows separated by `─┼─` divider
- Border-off mode: columns joined with two spaces
- Handles empty rows gracefully — returns header-only output
- Property-tested: column widths always `>=` max cell content width

## Usage: Basic Example

```ts
import { table } from "@suaveplan/cli/output/table/table";

const out = table({
  headers: ["Name", "Role", "Since"],
  rows: [
    ["Alice", "Admin", "2022"],
    ["Bob", "User", "2023"],
  ],
});
console.log(out);
// Name  │ Role  │ Since
// ──────┼───────┼──────
// Alice │ Admin │ 2022
// Bob   │ User  │ 2023
```

## Usage: Advanced Example

```ts
import { table } from "@suaveplan/cli/output/table/table";

const out = table({
  headers: ["Package", "Version", "Size"],
  rows: [
    ["@suaveplan/error", "0.1.0", "12 kB"],
    ["@suaveplan/cli", "0.1.0", "48 kB"],
  ],
  alignment: ["left", "center", "right"],
  border: true,
});
console.log(out);
```

## API Reference

### `table(opts: TableOptions): string`

Renders the table and returns the formatted string.

**`opts.headers: string[]`** — column header labels. Determines the number of columns.

**`opts.rows: string[][]`** — data rows. Each row is an array of string cells. Extra cells beyond `headers.length` are ignored; missing cells are treated as empty.

**`opts.alignment?: Alignment[]`** — per-column alignment (`"left"` | `"right"` | `"center"`). Defaults to `"left"` for any column not specified.

**`opts.border?: boolean`** — whether to render `│` column separators and `─┼─` divider line. Default `true`.

### `Alignment`

`"left" | "right" | "center"` — the alignment mode for a table column.

### `TableOptions`

The full options type. Corresponds to `TableOptionsSchema` for Zod validation.

## Implementation Notes

Column widths are computed with a single `Math.max` pass over `[headers, ...rows]`. Cells are padded with `String.prototype.padEnd` (left/center) or `String.prototype.padStart` (right via the `align` helper). The divider line joins `"─".repeat(width)` segments with `"─┼─"`. When `border` is false, the divider is omitted and segments are joined with `"  "` instead of `" │ "`. Trailing whitespace on each row is trimmed to keep output clean.