@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/renderables/table.d.ts

@@ -0,0 +1,194 @@
+/**
+ * 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 {
+    header?: string | RichText;
+    footer?: string | RichText;
+    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;
+}
+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;
+    private _cells;
+    constructor(options?: ColumnOptions);
+    /**
+     * The two stamped cells, parsed 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 that had parsed no markup, still carried its
+     * `end`, and was still owned by the caller, into a slot every reader below
+     * assumes `embeddedText` 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. `embeddedText` already maps nothing onto empty,
+     * which is why the setters take `undefined` rather than defaulting around it.
+     */
+    get header(): RichText;
+    set header(content: string | RichText | undefined);
+    get footer(): RichText;
+    set footer(content: string | RichText | undefined);
+    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;
+    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[];
+}
+export declare class Table implements Renderable, Measurable {
+    private _columns;
+    private _rows;
+    readonly box: Box | null;
+    readonly title: RichText | undefined;
+    readonly caption: RichText | undefined;
+    readonly expand: boolean;
+    readonly showHeader: boolean;
+    readonly showFooter: boolean;
+    readonly showLines: boolean;
+    readonly showEdge: boolean;
+    readonly padding: [number, number, number, number];
+    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[];
+    constructor(options?: TableOptions);
+    get columns(): Column[];
+    get rowCount(): number;
+    addColumn(header?: string | RichText, 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 a single cell.
+     * 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;
+    };
+    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.
+     */
+    private _columnDemands;
+    /**
+     * 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 cell in a 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 _widestCell;
+    /**
+     * 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;
+}