@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/renderables/table.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Table — tabular data with headers, borders, auto-sizing, and alignment.
+ */
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import { Box } from "../core/box.js";
+import { RichText } from "../core/text.js";
+import type { PaddingDimensions } from "./padding.js";
+import type { Renderable, Measurable, OverflowMethod, RenderOptions } from "../core/protocol.js";
+export interface ColumnOptions {
+    /** Anything a cell can hold, as Rich's `RenderableType` header is. */
+    header?: string | RichText | Renderable;
+    footer?: string | RichText | Renderable;
+    headerStyle?: string | Style;
+    footerStyle?: string | Style;
+    style?: string | Style;
+    justify?: "left" | "center" | "right" | "full";
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    ratio?: number;
+    noWrap?: boolean;
+    overflow?: OverflowMethod;
+    /**
+     * Whether the column's string cells — its header and footer among them — are
+     * drawn with the console's highlighter, as Rich's `Column(highlight=)`.
+     * `false` for a `Column` built alone; `addColumn` takes the table's.
+     */
+    highlight?: boolean;
+}
+export declare class Column {
+    private _header;
+    private _footer;
+    headerStyle: string | Style;
+    footerStyle: string | Style;
+    style: string | Style;
+    justify: "left" | "center" | "right" | "full";
+    width: number | undefined;
+    minWidth: number | undefined;
+    maxWidth: number | undefined;
+    ratio: number | undefined;
+    noWrap: boolean;
+    overflow: OverflowMethod;
+    highlight: boolean;
+    private _cells;
+    constructor(options?: ColumnOptions);
+    /**
+     * The two stamped cells, stamped on assignment rather than at the constructor.
+     * `Table.columns` hands out the live column and both fields are public, so a
+     * constructor-only stamp held only until the first `columns[0].footer = mine`
+     * — which installed content still owned by the caller into a slot every
+     * reader below assumes `embed` has been through. [LAW:parse-dont-validate] The setter
+     * is the border, so the guarantee holds for the object's whole lifetime and
+     * the constructor is one caller of it rather than the one place it is true.
+     *
+     * Absent and empty are the same header, and the same footer.
+     * [LAW:types-are-the-program] Rich declares `footer: RenderableType = ""`, so
+     * a column always has one and `show_footer` alone decides whether it is
+     * drawn. Modelling the absence as `undefined` instead made "no column has a
+     * footer" a state the render path could ask about — and it did, skipping the
+     * row a caller had asked for. `embed` already maps nothing onto empty,
+     * which is why the setters take `undefined` rather than defaulting around it.
+     */
+    get header(): Renderable & Partial<Measurable>;
+    set header(content: ColumnOptions["header"]);
+    get footer(): Renderable & Partial<Measurable>;
+    set footer(content: ColumnOptions["footer"]);
+    get flexible(): boolean;
+    /** @internal */
+    addCell(cell: Renderable): void;
+    /** @internal */
+    getCells(): Renderable[];
+    copy(): Column;
+}
+export interface TableOptions {
+    box?: Box | null;
+    title?: string | RichText;
+    caption?: string | RichText;
+    expand?: boolean;
+    showHeader?: boolean;
+    showFooter?: boolean;
+    showLines?: boolean;
+    showEdge?: boolean;
+    padding?: PaddingDimensions;
+    collapsePadding?: boolean;
+    padEdge?: boolean;
+    style?: string | Style;
+    headerStyle?: string | Style;
+    footerStyle?: string | Style;
+    borderStyle?: string | Style;
+    titleStyle?: string | Style;
+    captionStyle?: string | Style;
+    titleJustify?: "left" | "center" | "right" | "full";
+    captionJustify?: "left" | "center" | "right" | "full";
+    width?: number;
+    minWidth?: number;
+    rowStyles?: string[];
+    /** The `highlight` every column `addColumn` makes takes unless told otherwise (default: `false`). */
+    highlight?: boolean;
+}
+export declare class Table implements Renderable, Measurable {
+    private _columns;
+    private _rows;
+    readonly box: Box | null;
+    private readonly _title;
+    private readonly _caption;
+    readonly expand: boolean;
+    readonly showHeader: boolean;
+    readonly showFooter: boolean;
+    readonly showLines: boolean;
+    readonly showEdge: boolean;
+    readonly padding: [number, number, number, number];
+    readonly collapsePadding: boolean;
+    readonly padEdge: boolean;
+    readonly style: string | Style;
+    readonly headerStyle: string | Style;
+    readonly footerStyle: string | Style;
+    readonly borderStyle: string | Style;
+    readonly titleStyle: string | Style;
+    readonly captionStyle: string | Style;
+    readonly titleJustify: "left" | "center" | "right" | "full";
+    readonly captionJustify: "left" | "center" | "right" | "full";
+    readonly tableWidth: number | undefined;
+    readonly minWidth: number | undefined;
+    readonly rowStyles: string[];
+    readonly highlight: boolean;
+    get title(): (Renderable & Measurable) | undefined;
+    get caption(): (Renderable & Measurable) | undefined;
+    constructor(options?: TableOptions);
+    get columns(): Column[];
+    get rowCount(): number;
+    addColumn(header?: ColumnOptions["header"], options?: ColumnOptions): this;
+    addRow(...cells: unknown[]): this;
+    addSection(): this;
+    render(rawOptions: RenderOptions): Iterable<Segment>;
+    /**
+     * [LAW:one-source-of-truth] Both ends of the range are widths the geometry
+     * actually produced — the maximum from the demands as they stand, the
+     * minimum from the same layout with every column asking for its minimum.
+     * Neither end stretches or fills into an offer: both only spend cells an
+     * offer happens to leave over, and a renderable reports the width its content
+     * wants rather than the width it was offered. A declared `width` is not an
+     * offer, and the maximum reports it. Letting either in made the table measure
+     * `Infinity` against an unbounded offer, where `withBoundedWidth` needs a
+     * natural width to fall back on — an expanding table, and an empty
+     * `Table.grid()`.
+     * Neither can exceed the width offered and the tighter request cannot exceed
+     * the looser one, so the range cannot invert. Deriving the minimum from raw
+     * column and padding counts instead is what used to return
+     * `{minimum: 6, maximum: 1}` at `maxWidth: 1` — a floor above its own ceiling.
+     */
+    measure(rawOptions: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    /**
+     * A table with no frame and no header, padded between its columns and never
+     * at its edges, so an expanded grid reaches both sides of its width. The
+     * reference's `grid` defaults, but for `padding`: Rich's is 0, which runs
+     * adjacent columns together, and this port's is one cell to the right.
+     */
+    static grid(options?: Omit<TableOptions, "box" | "showHeader" | "showEdge">): Table;
+    private _frame;
+    /**
+     * The width this table lays itself out against: what it was told to be, as a
+     * count of cells, never wider than what it was offered.
+     *
+     * [LAW:one-source-of-truth] `render` and `measure` divide the same two fields
+     * and once did it in two places. `measure` bounded the declared width by the
+     * offer and `render` preferred it outright, walking past the value
+     * `withBoundedWidth` had just resolved — so `new Table({width: Infinity})`
+     * with a `{ratio: 1}` column granted that column `UNBOUNDED` cells and threw
+     * `RangeError: Invalid string length` out of the top border, at a perfectly
+     * ordinary 80-cell offer.
+     */
+    private _outerWidth;
+    private _geometry;
+    /**
+     * [LAW:dataflow-not-control-flow] The three ways a column can be sized —
+     * declared width, ratio, natural content — differ only in the demand they
+     * produce, and `expand` only in its `stretch`. They are resolved once, here, into uniform data, so
+     * `layoutTable` runs the same apportionment for every table and no sizing
+     * mode gets its own path through the width division.
+     *
+     * Cells are measured against the width left once the frame is paid, as the
+     * reference's `_measure_column` measures them. Padding and the floor are laid
+     * over whichever sizing the column has: they are the same for all three.
+     */
+    private _columnDemands;
+    private _columnSizing;
+    /**
+     * The padding either side of column `index`'s content, and above and below
+     * one row of cells: the reference's `get_padding`. `collapsePadding` lets a
+     * cell's left padding and its row's bottom padding merge into the padding
+     * beside and below them; `padEdge: false` drops every side that meets the
+     * table's edge. Each side is the configured padding unless one of those two
+     * reduces it.
+     */
+    private _columnPadding;
+    private _rowPadding;
+    /**
+     * Every cell column `index` draws, in draw order.
+     *
+     * [LAW:one-source-of-truth] The reference's `_get_cells` is the one answer to
+     * "which cells belong to this column", and both `_measure_column` and
+     * `_render` read it. Enumerating that set a second time inside the width path
+     * is how the two ends drifted: the header was measured whether or not
+     * `showHeader` drew it, and `col.footer` was never measured at all, so a
+     * footer wider than its column — a totals row, exactly — was cut to `…`.
+     * A flag is the whole membership rule; nothing here asks after content.
+     */
+    private _columnCells;
+    /**
+     * The widest any cell in a column draws, and the narrowest the column can be
+     * without cutting one — the reference's `_measure_column` — or `undefined`
+     * when the column has no cell to measure. Zero is a column whose cells draw
+     * nothing — a gutter asks for its padding and nothing else — and is not the
+     * same answer. [LAW:types-are-the-program]
+     */
+    private _cellRange;
+    /**
+     * A natural width held to the column's own `minWidth`/`maxWidth`.
+     *
+     * A bound is a count of cells, read by the rule every width is read by: NaN
+     * and a negative are zero cells, so a NaN floor bounds nothing and a NaN
+     * ceiling is a ceiling of zero, as `width: NaN` is. A bare `Math.max` returns
+     * NaN instead, and the column vanishes. [LAW:one-source-of-truth]
+     */
+    private _bounded;
+    private _renderRow;
+    private _renderTitle;
+}