@markii/ansi 0.0.1

package/dist/components/layout-wrapper.js

@@ -0,0 +1,62 @@
+import { layoutWrapperAxis } from '@markii/stdlib';
+import { applyLayout } from '../layout.js';
+/**
+ * The closed set of layout-wrapper container names (docs/format.md):
+ * aliases of the one shared implementation below (`createLayoutWrapper`),
+ * matching `@markii/html`'s `layout-wrapper.ts`. There is deliberately no
+ * `normal` alias: the default needs no wrapper at all. Every name here is
+ * ALSO one of `@markii/stdlib`'s own width/align preset values (`center`/
+ * `left`/`right` are align presets, `wide`/`narrow`/`full`/`fit` are width
+ * presets), which is what lets `createLayoutWrapper` use the preset name
+ * itself as that axis's value with no separate lookup table.
+ */
+export const LAYOUT_WRAPPER_PRESETS = [
+    'center',
+    'left',
+    'right',
+    'wide',
+    'narrow',
+    'full',
+    'fit',
+];
+/**
+ * Creates the registry component for one of docs/format.md's layout-wrapper
+ * container names. One shared implementation, bound to `preset` at
+ * registration time, matching `@markii/html`'s `createLayoutWrapper` in
+ * spirit: it never reads `attributes` at all — `render.ts` already stripped
+ * both reserved keys before this ever runs.
+ *
+ * A wrapper sets ONE axis by its own NAME (docs/spec.md §3): `preset` itself
+ * IS that axis's value (`center` sets `align: 'center'`; `narrow` sets
+ * `width: 'narrow'`), so it is applied unconditionally, whatever the author
+ * wrote for that axis's own reserved attribute (already discarded — the
+ * name always wins). The OTHER axis, when the author supplied it, arrives
+ * as `ctx.layout` (`render.ts` resolved it on this wrapper's behalf, since
+ * this wrapper is the directive's registered `layout` scope). Both are
+ * merged into one `ResolvedLayoutPresets` and applied together via
+ * `../layout.js`'s `applyLayout`, so `:::center{width=fit}` narrows AND
+ * centers in one pass.
+ */
+export function createLayoutWrapper(preset) {
+    const ownAxis = layoutWrapperAxis(preset);
+    if (ownAxis === undefined) {
+        // Unreachable for the closed preset list above.
+        throw new Error(`"${preset}" is not a layout-wrapper name`);
+    }
+    const own = ownAxis === 'align'
+        ? { align: preset }
+        : { width: preset };
+    return (_attributes, children, ctx) => {
+        const merged = { ...own, ...ctx.layout };
+        return applyLayout(children(), merged, ctx.width);
+    };
+}
+/** The layout axis `preset` sets by its own name. Mirrors `@markii/html`'s `layoutWrapperPresetAxis`. */
+export function layoutWrapperPresetAxis(preset) {
+    const axis = layoutWrapperAxis(preset);
+    if (axis === undefined) {
+        // Unreachable for the closed preset list above.
+        throw new Error(`"${preset}" is not a layout-wrapper name`);
+    }
+    return axis;
+}

package/dist/components/progress.d.ts

@@ -0,0 +1,15 @@
+import type { AnsiComponent } from '../registry.js';
+/**
+ * `::progress{value=3 max=5 label="tasks"}` — a meter bar. Data binding (§8)
+ * mirrors `@markii/html`'s `Progress`: a bound number supplies `value`; a
+ * bound object may supply `value`/`max` — explicit attributes always win.
+ * Non-numeric/`NaN`/`Infinity` input falls back to `0` (value) or the
+ * default `max` of `1`; the effective value is clamped to `[0, max]`.
+ * Terminal form: `label bar percent`, the bar drawn with `█` (filled) and
+ * `░` (empty) at up to `MAX_BAR_WIDTH` columns, narrower when the label and
+ * percent text leave less room. `format`/`decimals`, when given, format the
+ * `value/max` fraction for the percent readout in place of the default
+ * rounded integer percent, matching `@markii/html` exactly. A failed/stale
+ * binding appends the quiet failure suffix after the percent.
+ */
+export declare const Progress: AnsiComponent;

package/dist/components/progress.js

@@ -0,0 +1,78 @@
+import { formatValue } from '@markii/stdlib';
+import { measure } from '../measure.js';
+import { safeRead } from '../resolve.js';
+import { dataStateSuffix, failureToken } from '../failure-presentation.js';
+const DEFAULT_MAX = 1;
+function parseFiniteNumber(raw, fallback) {
+    if (raw === null || raw === undefined)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+function coerceNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function readProgressFields(data) {
+    if (typeof data === 'number') {
+        return { value: Number.isFinite(data) ? data : undefined };
+    }
+    if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+        const record = data;
+        return { value: coerceNumber(record.value), max: coerceNumber(record.max) };
+    }
+    return {};
+}
+/** Block characters the bar fills with, and its widest allowed footprint (columns), sized down further when the label/percent text leaves less room. */
+const FILLED_CHAR = '█';
+const EMPTY_CHAR = '░';
+const MAX_BAR_WIDTH = 30;
+const MIN_BAR_WIDTH = 3;
+/**
+ * `::progress{value=3 max=5 label="tasks"}` — a meter bar. Data binding (§8)
+ * mirrors `@markii/html`'s `Progress`: a bound number supplies `value`; a
+ * bound object may supply `value`/`max` — explicit attributes always win.
+ * Non-numeric/`NaN`/`Infinity` input falls back to `0` (value) or the
+ * default `max` of `1`; the effective value is clamped to `[0, max]`.
+ * Terminal form: `label bar percent`, the bar drawn with `█` (filled) and
+ * `░` (empty) at up to `MAX_BAR_WIDTH` columns, narrower when the label and
+ * percent text leave less room. `format`/`decimals`, when given, format the
+ * `value/max` fraction for the percent readout in place of the default
+ * rounded integer percent, matching `@markii/html` exactly. A failed/stale
+ * binding appends the quiet failure suffix after the percent.
+ */
+export const Progress = (attributes, _children, ctx) => {
+    const { data, dataStatus, dataFailureKind } = ctx;
+    const bound = safeRead(() => dataStatus === 'missing' || dataStatus === 'error'
+        ? {}
+        : readProgressFields(data), () => ({}));
+    const fromData = bound.fields;
+    const rawMax = parseFiniteNumber(attributes.max, fromData.max ?? DEFAULT_MAX);
+    const max = rawMax > 0 ? rawMax : DEFAULT_MAX;
+    const rawValue = parseFiniteNumber(attributes.value, fromData.value ?? 0);
+    const value = clamp(rawValue, 0, max);
+    const percent = clamp((value / max) * 100, 0, 100);
+    const label = attributes.label ?? null;
+    const rawFormat = attributes.format ?? undefined;
+    const percentText = rawFormat
+        ? formatValue(percent / 100, rawFormat, attributes.decimals ?? undefined)
+        : `${String(Math.round(percent))}%`;
+    const labelPart = label ? `${ctx.text(label)} ` : '';
+    const suffix = dataStateSuffix(dataStatus, dataFailureKind);
+    const token = failureToken(dataFailureKind);
+    const percentPart = ` ${ctx.text(percentText)}${suffix ? (token ? ctx.style(suffix, token) : ctx.dim(suffix)) : ''}`;
+    const overhead = measure(labelPart) + measure(percentText) + 1;
+    const barWidth = Math.max(MIN_BAR_WIDTH, Math.min(MAX_BAR_WIDTH, ctx.width - overhead));
+    const filledCount = Math.round((percent / 100) * barWidth);
+    const bar = FILLED_CHAR.repeat(filledCount) + EMPTY_CHAR.repeat(barWidth - filledCount);
+    return `${labelPart}${bar}${percentPart}`;
+};

package/dist/components/rating.d.ts

@@ -0,0 +1,9 @@
+import type { AnsiComponent } from '../registry.js';
+/**
+ * `::rating{value=3 max=5}` — a leaf directive rendering a row of stars.
+ * Both attributes are optional and clamped to sane bounds; malformed input
+ * degrades gracefully instead of throwing. Terminal form: filled (`★`) and
+ * empty (`☆`) stars, one per position up to `max`. Matches
+ * `@markii/html`'s `Rating` clamping rules exactly.
+ */
+export declare const Rating: AnsiComponent;

package/dist/components/rating.js

@@ -0,0 +1,28 @@
+const DEFAULT_MAX = 5;
+const MIN_MAX = 1;
+const MAX_MAX = 20;
+function parseCount(raw, fallback) {
+    if (raw === null || raw === undefined)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * `::rating{value=3 max=5}` — a leaf directive rendering a row of stars.
+ * Both attributes are optional and clamped to sane bounds; malformed input
+ * degrades gracefully instead of throwing. Terminal form: filled (`★`) and
+ * empty (`☆`) stars, one per position up to `max`. Matches
+ * `@markii/html`'s `Rating` clamping rules exactly.
+ */
+export const Rating = (attributes) => {
+    const max = clamp(parseCount(attributes.max, DEFAULT_MAX), MIN_MAX, MAX_MAX);
+    const value = clamp(parseCount(attributes.value, 0), 0, max);
+    let stars = '';
+    for (let index = 0; index < max; index += 1) {
+        stars += index < value ? '★' : '☆';
+    }
+    return stars;
+};

package/dist/components/row.d.ts

@@ -0,0 +1,26 @@
+import type { AnsiComponent } from '../registry.js';
+/** Below this width, cells stack vertically instead of sitting side by side — a named constant per the batch brief, not a magic number. */
+export declare const ROW_COLUMN_THRESHOLD = 60;
+/**
+ * `:::row{cols=2|3|4 text=left|center|right} ... :::` — docs/format.md's one
+ * layout container. An absent/invalid `cols` auto-fits: every direct block
+ * child becomes one column, all in a single row of columns. A `cols` value
+ * smaller than the child count wraps into further grid rows, `cols` cells at
+ * a time — the terminal counterpart of the CSS grid wrap a live host does.
+ * Below `ROW_COLUMN_THRESHOLD` columns, or with only one cell, cells stack
+ * vertically instead (a plain blank-line-separated list) — a fixed-width
+ * terminal has no responsive reflow, so this is the one width breakpoint
+ * that stands in for it.
+ *
+ * Each cell is one of the directive's own top-level children
+ * (`registry.ts`'s `AnsiChildren.parts`: a `:::cell` directive grouping
+ * several blocks, or any other block standing for itself, per docs/format.md's
+ * "a row counts its direct block children as its cells"), rendered through
+ * that part's own `render({ width })` at the ACTUAL column width decided
+ * below, rather than rendered once at the row's full width and then
+ * re-wrapped into a narrower column. A cell containing a self-drawing box
+ * (a nested `card`/`table`) therefore draws that box at the real column
+ * width in the first place, instead of having an already-drawn frame
+ * mangled by a later re-wrap.
+ */
+export declare const Row: AnsiComponent;

package/dist/components/row.js

@@ -0,0 +1,67 @@
+import { columns } from '../box.js';
+const COLS_VALUES = ['2', '3', '4'];
+function isColsValue(value) {
+    return COLS_VALUES.includes(value);
+}
+const TEXT_ALIGNS = ['left', 'center', 'right'];
+function isTextAlign(value) {
+    return TEXT_ALIGNS.includes(value);
+}
+/** Below this width, cells stack vertically instead of sitting side by side — a named constant per the batch brief, not a magic number. */
+export const ROW_COLUMN_THRESHOLD = 60;
+/** Spaces between adjacent columns. */
+const GUTTER = 1;
+/**
+ * `:::row{cols=2|3|4 text=left|center|right} ... :::` — docs/format.md's one
+ * layout container. An absent/invalid `cols` auto-fits: every direct block
+ * child becomes one column, all in a single row of columns. A `cols` value
+ * smaller than the child count wraps into further grid rows, `cols` cells at
+ * a time — the terminal counterpart of the CSS grid wrap a live host does.
+ * Below `ROW_COLUMN_THRESHOLD` columns, or with only one cell, cells stack
+ * vertically instead (a plain blank-line-separated list) — a fixed-width
+ * terminal has no responsive reflow, so this is the one width breakpoint
+ * that stands in for it.
+ *
+ * Each cell is one of the directive's own top-level children
+ * (`registry.ts`'s `AnsiChildren.parts`: a `:::cell` directive grouping
+ * several blocks, or any other block standing for itself, per docs/format.md's
+ * "a row counts its direct block children as its cells"), rendered through
+ * that part's own `render({ width })` at the ACTUAL column width decided
+ * below, rather than rendered once at the row's full width and then
+ * re-wrapped into a narrower column. A cell containing a self-drawing box
+ * (a nested `card`/`table`) therefore draws that box at the real column
+ * width in the first place, instead of having an already-drawn frame
+ * mangled by a later re-wrap.
+ */
+export const Row = (attributes, children, ctx) => {
+    const rawTextAlign = attributes.text;
+    const align = rawTextAlign && isTextAlign(rawTextAlign) ? rawTextAlign : 'left';
+    const cellParts = children.parts;
+    if (cellParts.length === 0)
+        return '';
+    const rawCols = attributes.cols ?? '';
+    const requestedCols = isColsValue(rawCols)
+        ? Number(rawCols)
+        : cellParts.length;
+    const columnCount = Math.max(1, Math.min(requestedCols, cellParts.length));
+    const place = (text, width) => align === 'left'
+        ? text
+        : text
+            .split('\n')
+            .map((line) => ctx.pad(line, width, align))
+            .join('\n');
+    if (ctx.width < ROW_COLUMN_THRESHOLD || columnCount <= 1) {
+        return cellParts
+            .map((part) => place(part.render({ width: ctx.width }), ctx.width))
+            .join('\n\n');
+    }
+    const colWidth = Math.max(1, Math.floor((ctx.width - GUTTER * (columnCount - 1)) / columnCount));
+    const placedCells = cellParts.map((part) => place(part.render({ width: colWidth }), colWidth));
+    const gridRows = [];
+    for (let index = 0; index < placedCells.length; index += columnCount) {
+        const rowCells = placedCells.slice(index, index + columnCount);
+        const widths = rowCells.map(() => colWidth);
+        gridRows.push(columns(rowCells, widths, GUTTER));
+    }
+    return gridRows.join('\n\n');
+};

package/dist/components/stat.d.ts

@@ -0,0 +1,13 @@
+import type { AnsiComponent } from '../registry.js';
+/**
+ * `::stat{value=42 label="stars" trend=up}` — a big value plus label. Data
+ * binding (§8) mirrors `@markii/html`'s `Stat` exactly: a bound number/string
+ * supplies `value`; a bound object may supply `value`/`label`/`delta`/`trend`
+ * — an explicit attribute always wins. Missing value renders `—` rather than
+ * a blank line. Terminal form: a muted label line, then a bold value line
+ * (with `delta` appended, colored by `trend` when recognized). A failed or
+ * stale binding appends `failure-presentation.ts`'s quiet suffix to the
+ * value line — the terminal has no tooltip channel, so the reason has to
+ * reach the text itself (AGENTS.md's "clean is not silent").
+ */
+export declare const Stat: AnsiComponent;

package/dist/components/stat.js

@@ -0,0 +1,79 @@
+import { formatValue } from '@markii/stdlib';
+import { safeRead } from '../resolve.js';
+import { dataStateSuffix, failureToken } from '../failure-presentation.js';
+const EMPTY_VALUE = '—';
+const TRENDS = ['up', 'down', 'flat'];
+function isTrend(value) {
+    return TRENDS.includes(value);
+}
+function coerceField(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return undefined;
+}
+function readStatFields(data) {
+    if (typeof data === 'number' || typeof data === 'string') {
+        return { value: String(data) };
+    }
+    if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+        const record = data;
+        return {
+            value: coerceField(record.value),
+            label: coerceField(record.label),
+            delta: coerceField(record.delta),
+            trend: coerceField(record.trend),
+        };
+    }
+    return {};
+}
+/** Explicit directive attributes win over the bound `data` object's own fields. */
+function pick(attribute, fromData) {
+    return attribute ?? fromData ?? undefined;
+}
+/**
+ * `::stat{value=42 label="stars" trend=up}` — a big value plus label. Data
+ * binding (§8) mirrors `@markii/html`'s `Stat` exactly: a bound number/string
+ * supplies `value`; a bound object may supply `value`/`label`/`delta`/`trend`
+ * — an explicit attribute always wins. Missing value renders `—` rather than
+ * a blank line. Terminal form: a muted label line, then a bold value line
+ * (with `delta` appended, colored by `trend` when recognized). A failed or
+ * stale binding appends `failure-presentation.ts`'s quiet suffix to the
+ * value line — the terminal has no tooltip channel, so the reason has to
+ * reach the text itself (AGENTS.md's "clean is not silent").
+ */
+export const Stat = (attributes, _children, ctx) => {
+    const { data, dataStatus, dataFailureKind } = ctx;
+    const bound = safeRead(() => dataStatus === 'missing' || dataStatus === 'error'
+        ? {}
+        : readStatFields(data), () => ({}));
+    const fromData = bound.fields;
+    const value = pick(attributes.value, fromData.value);
+    const formattedValue = formatValue(value, attributes.format ?? undefined, attributes.decimals ?? undefined);
+    const label = pick(attributes.label, fromData.label);
+    const delta = pick(attributes.delta, fromData.delta);
+    const rawTrend = pick(attributes.trend, fromData.trend);
+    const trend = rawTrend && isTrend(rawTrend) ? rawTrend : undefined;
+    const lines = [];
+    if (label)
+        lines.push(ctx.style(ctx.text(label), '--mk-muted'));
+    let valueLine = ctx.bold(ctx.text(formattedValue || EMPTY_VALUE));
+    if (delta) {
+        const deltaToken = trend === 'up'
+            ? '--mk-success'
+            : trend === 'down'
+                ? '--mk-danger'
+                : undefined;
+        const deltaText = ctx.text(delta);
+        valueLine += `  ${deltaToken ? ctx.style(deltaText, deltaToken) : deltaText}`;
+    }
+    const suffix = dataStateSuffix(dataStatus, dataFailureKind);
+    if (suffix) {
+        const token = failureToken(dataFailureKind);
+        valueLine += token ? ctx.style(suffix, token) : ctx.dim(suffix);
+    }
+    lines.push(valueLine);
+    return lines.join('\n');
+};

package/dist/components/tab.d.ts

@@ -0,0 +1,13 @@
+import type { AnsiComponent } from '../registry.js';
+export declare const DEFAULT_TAB_LABEL = "Tab";
+/**
+ * `:::tab{label="..."} ... :::` — one panel of a `tabs` component
+ * (`tabs.ts`). Unlike `@markii/html`'s `Tab` (which never reads `label` at
+ * all — see that module's `tabs.ts` for why a string-based engine usually
+ * can't reach a child directive's own attributes from its parent), THIS
+ * engine's `tab` reads its OWN `label` directly, since it is rendered as
+ * its OWN directive, not inspected by `tabs` from the outside: the label
+ * becomes a bold heading line above the panel body. Rendered standalone
+ * (outside a `tabs` parent) it shows exactly the same heading and panel.
+ */
+export declare const Tab: AnsiComponent;

package/dist/components/tab.js

@@ -0,0 +1,17 @@
+export const DEFAULT_TAB_LABEL = 'Tab';
+/**
+ * `:::tab{label="..."} ... :::` — one panel of a `tabs` component
+ * (`tabs.ts`). Unlike `@markii/html`'s `Tab` (which never reads `label` at
+ * all — see that module's `tabs.ts` for why a string-based engine usually
+ * can't reach a child directive's own attributes from its parent), THIS
+ * engine's `tab` reads its OWN `label` directly, since it is rendered as
+ * its OWN directive, not inspected by `tabs` from the outside: the label
+ * becomes a bold heading line above the panel body. Rendered standalone
+ * (outside a `tabs` parent) it shows exactly the same heading and panel.
+ */
+export const Tab = (attributes, children, ctx) => {
+    const label = attributes.label ?? DEFAULT_TAB_LABEL;
+    const heading = ctx.bold(ctx.text(label));
+    const childrenText = children();
+    return childrenText ? `${heading}\n${childrenText}` : heading;
+};

package/dist/components/table-grid.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The ONE box-drawing/width-negotiation routine every table this engine
+ * draws goes through: the data-bound `::table` component (`./table.ts`) and
+ * `render.ts`'s plain GFM markdown table both call `drawTableGrid`, so there
+ * is exactly one place that decides how a table's columns share the
+ * available width and exactly one set of box-drawing glyphs in the whole
+ * engine (`┌ ┬ ┐ ├ ┼ ┤ └ ┴ ┘ ─ │`).
+ *
+ * Column-width negotiation: every cell (header included) is measured at its
+ * natural width; if the natural total fits `width`, every column gets its
+ * natural width. Otherwise the widest column is shrunk one column at a time
+ * (ties broken by the leftmost widest column) until the total fits or every
+ * column has hit `MIN_COLUMN_WIDTH`, whichever comes first — a table wider
+ * than `width` even at every column's minimum is allowed to overflow rather
+ * than produce unreadably thin columns; nothing in this engine truncates
+ * text outright. A column narrower than its content wraps that cell's text
+ * inside its own box (`./box.ts`'s `wrap`), so a row's height grows to fit
+ * its tallest cell rather than losing text.
+ */
+/** The floor a column is shrunk to before a table is allowed to overflow `width`. Chosen so a wrapped cell still reads as more than one letter per line. */
+export declare const MIN_COLUMN_WIDTH = 3;
+/**
+ * Draws a box-drawn table. `header`, when given, is the bold first row,
+ * separated from the body by its own rule; `rows` is every remaining row.
+ * Every string is display text ALREADY sanitized/formatted by the caller
+ * (this module escapes nothing of its own — there is no HTML/ANSI injection
+ * risk in a plain string, only in the escape SEQUENCES `boldFn` itself
+ * generates, which this module never constructs by hand). Returns a
+ * complete grid at most `width` columns wide when the natural content
+ * allows it, otherwise as narrow as `MIN_COLUMN_WIDTH` per column permits.
+ */
+export declare function drawTableGrid(header: readonly string[] | undefined, rows: readonly (readonly string[])[], width: number, boldFn?: (text: string) => string, align?: 'left' | 'center' | 'right'): string;
+/** The widest a `drawTableGrid` result's lines get, for a `selfLayout` component (`./table.ts`) that needs to know its own natural footprint (the `fit` width preset). */
+export declare function measureTableGridWidth(header: readonly string[] | undefined, rows: readonly (readonly string[])[]): number;

package/dist/components/table-grid.js

@@ -0,0 +1,124 @@
+import { pad, wrap } from '../box.js';
+import { measure } from '../measure.js';
+/**
+ * The ONE box-drawing/width-negotiation routine every table this engine
+ * draws goes through: the data-bound `::table` component (`./table.ts`) and
+ * `render.ts`'s plain GFM markdown table both call `drawTableGrid`, so there
+ * is exactly one place that decides how a table's columns share the
+ * available width and exactly one set of box-drawing glyphs in the whole
+ * engine (`┌ ┬ ┐ ├ ┼ ┤ └ ┴ ┘ ─ │`).
+ *
+ * Column-width negotiation: every cell (header included) is measured at its
+ * natural width; if the natural total fits `width`, every column gets its
+ * natural width. Otherwise the widest column is shrunk one column at a time
+ * (ties broken by the leftmost widest column) until the total fits or every
+ * column has hit `MIN_COLUMN_WIDTH`, whichever comes first — a table wider
+ * than `width` even at every column's minimum is allowed to overflow rather
+ * than produce unreadably thin columns; nothing in this engine truncates
+ * text outright. A column narrower than its content wraps that cell's text
+ * inside its own box (`./box.ts`'s `wrap`), so a row's height grows to fit
+ * its tallest cell rather than losing text.
+ */
+/** The floor a column is shrunk to before a table is allowed to overflow `width`. Chosen so a wrapped cell still reads as more than one letter per line. */
+export const MIN_COLUMN_WIDTH = 3;
+/** Per-column border/padding overhead: one leading space, one trailing space, shared with `measureOverhead` below. */
+const CELL_PADDING = 2;
+function measureOverhead(columnCount) {
+    // One vertical border before each column plus one closing border, plus
+    // one space of padding on each side of every column's content.
+    return columnCount + 1 + columnCount * CELL_PADDING;
+}
+function naturalColumnWidths(header, rows, columnCount) {
+    const widths = new Array(columnCount).fill(1);
+    const consider = (cells) => {
+        for (let c = 0; c < columnCount; c += 1) {
+            const width = measure(cells?.[c] ?? '');
+            if (width > widths[c])
+                widths[c] = width;
+        }
+    };
+    consider(header);
+    for (const row of rows)
+        consider(row);
+    return widths;
+}
+/**
+ * Shrinks `widths` (in place, returning a new array) until their total plus
+ * `overhead` fits `budget`, or every column is at `MIN_COLUMN_WIDTH`. Each
+ * step removes one column from the widest-remaining pool, so several
+ * over-wide columns shrink roughly evenly rather than one column absorbing
+ * the whole deficit.
+ */
+function negotiateColumnWidths(natural, width) {
+    const widths = [...natural];
+    const columnCount = widths.length;
+    const overhead = measureOverhead(columnCount);
+    const budget = Math.max(columnCount * MIN_COLUMN_WIDTH, width - overhead);
+    let total = widths.reduce((sum, w) => sum + w, 0);
+    while (total > budget) {
+        let widest = -1;
+        for (let c = 0; c < columnCount; c += 1) {
+            if (widths[c] > MIN_COLUMN_WIDTH &&
+                (widest === -1 || widths[c] > widths[widest])) {
+                widest = c;
+            }
+        }
+        if (widest === -1)
+            break; // every column is already at the floor
+        widths[widest] = widths[widest] - 1;
+        total -= 1;
+    }
+    return widths;
+}
+/** Wraps every cell in `row` to its column's width, returning the row's cells as line arrays and the row's resulting height. */
+function wrapRow(row, widths) {
+    const lines = widths.map((w, c) => wrap(row[c] ?? '', w));
+    const height = Math.max(1, ...lines.map((l) => l.length));
+    return { lines, height };
+}
+function drawRow(row, widths, boldRow, boldFn, align) {
+    const { lines, height } = wrapRow(row, widths);
+    const rowLines = [];
+    for (let line = 0; line < height; line += 1) {
+        const cells = widths.map((w, c) => {
+            const text = pad(lines[c]?.[line] ?? '', w, align);
+            return boldRow ? boldFn(text) : text;
+        });
+        rowLines.push(`│ ${cells.join(' │ ')} │`);
+    }
+    return rowLines.join('\n');
+}
+function drawSeparator(widths, left, mid, right) {
+    return `${left}${widths.map((w) => '─'.repeat(w + CELL_PADDING)).join(mid)}${right}`;
+}
+/**
+ * Draws a box-drawn table. `header`, when given, is the bold first row,
+ * separated from the body by its own rule; `rows` is every remaining row.
+ * Every string is display text ALREADY sanitized/formatted by the caller
+ * (this module escapes nothing of its own — there is no HTML/ANSI injection
+ * risk in a plain string, only in the escape SEQUENCES `boldFn` itself
+ * generates, which this module never constructs by hand). Returns a
+ * complete grid at most `width` columns wide when the natural content
+ * allows it, otherwise as narrow as `MIN_COLUMN_WIDTH` per column permits.
+ */
+export function drawTableGrid(header, rows, width, boldFn = (text) => text, align = 'left') {
+    const columnCount = Math.max(header?.length ?? 0, ...rows.map((row) => row.length), 1);
+    const natural = naturalColumnWidths(header, rows, columnCount);
+    const widths = negotiateColumnWidths(natural, width);
+    const lines = [];
+    lines.push(drawSeparator(widths, '┌', '┬', '┐'));
+    if (header) {
+        lines.push(drawRow(header, widths, true, boldFn, align));
+        lines.push(drawSeparator(widths, '├', '┼', '┤'));
+    }
+    for (const row of rows)
+        lines.push(drawRow(row, widths, false, boldFn, align));
+    lines.push(drawSeparator(widths, '└', '┴', '┘'));
+    return lines.join('\n');
+}
+/** The widest a `drawTableGrid` result's lines get, for a `selfLayout` component (`./table.ts`) that needs to know its own natural footprint (the `fit` width preset). */
+export function measureTableGridWidth(header, rows) {
+    const columnCount = Math.max(header?.length ?? 0, ...rows.map((row) => row.length), 1);
+    const natural = naturalColumnWidths(header, rows, columnCount);
+    return natural.reduce((sum, w) => sum + w, 0) + measureOverhead(columnCount);
+}

package/dist/components/table.d.ts

@@ -0,0 +1,16 @@
+import type { AnsiComponent } from '../registry.js';
+/**
+ * `::table{data=users columns="name,role" limit=10}` — a data-bound table.
+ * Data binding (§8) mirrors `@markii/html`'s `Table`: `@markii/stdlib`'s
+ * `deriveTableShape` decides the layout from the bound value's own shape.
+ * `format`/`decimals` apply to numeric cells only; `text` aligns every
+ * cell's content within its column; `caption`, when given, is a bold line
+ * above the grid. A missing/stale/failed binding degrades to the same quiet
+ * "no data" line `chart`/`progress` use, with the failure suffix appended.
+ *
+ * Registered `selfLayout` (see `card.ts`'s doc comment): draws real
+ * box-drawing glyphs (`./table-grid.ts`), so it sizes its own grid off
+ * `ctx.layout` instead of letting a generic post-render narrow/pad corrupt
+ * the borders.
+ */
+export declare const Table: AnsiComponent;