@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/box.js

@@ -0,0 +1,372 @@
+/**
+ * Box-drawing character sets for borders and table grids.
+ *
+ * A style is declared as an 8x4 character grid — one line per row a table can
+ * draw, one column per position within that row:
+ *
+ *     ┌─┬┐   top border
+ *     │ ││   header content
+ *     ├─┼┤   header separator
+ *     │ ││   body content
+ *     ├─┼┤   row separator
+ *     ├─┼┤   footer separator
+ *     │ ││   footer content
+ *     └─┴┘   bottom border
+ *
+ * [LAW:one-source-of-truth] The grid is the shape the reference implementation
+ * (Python Rich's `box.py`) publishes these glyphs in, so a constant below can
+ * be diffed against it character for character. The eighteen named fields this
+ * replaced were a second, differently-shaped map of the same territory, and it
+ * had drifted: seven of the nineteen constants carried wrong glyphs, and the
+ * field named `mid` held the reference's line 3 while the reference's `mid_*`
+ * is line 4 — so reading the reference name-for-name swapped a separator for a
+ * content row. Named row fields are gone for that reason; a row is reached by
+ * what it is (`getRow`, `getContentChars`), never by a name that can be
+ * mismatched to a line.
+ */
+import { cellLen } from "./cells.js";
+import { Segment } from "./segment.js";
+import { drawable } from "./protocol.js";
+const GRID_ROWS = 8;
+const GRID_COLUMNS = 4;
+/** Corners that a legacy Windows terminal cannot draw, and their square kin. */
+const SAFE_SUBSTITUTIONS = {
+    "╭": "┌",
+    "╮": "┐",
+    "╰": "└",
+    "╯": "┘",
+};
+const edgeOf = (row) => ({
+    left: row[0],
+    horizontal: row[1],
+    cross: row[2],
+    right: row[3],
+});
+const contentOf = (row) => ({
+    left: row[0],
+    vertical: row[2],
+    right: row[3],
+});
+// [LAW:one-type-per-behavior] Box is a single type for all border styles — instances differ by data
+export class Box {
+    top;
+    bottom;
+    grid;
+    headContent;
+    headSeparator;
+    bodyContent;
+    rowSeparator;
+    footSeparator;
+    footContent;
+    /**
+     * [LAW:parse-dont-validate] The one crossing between a grid string and box
+     * glyphs. A `Box` cannot exist without eight rows of four characters, so no
+     * consumer below ever re-checks the shape of the data it reads.
+     */
+    constructor(grid) {
+        const lines = grid.split("\n");
+        // A row is four characters because `getEdge` indexes the four positions,
+        // and four cells because that is what the terminal draws — a single astral
+        // glyph satisfies the first and breaks every frame the box appears in.
+        // [LAW:single-enforcer] `cellLen` is the cell-width authority.
+        const malformed = lines.length !== GRID_ROWS
+            || lines.some((line) => Array.from(line).length !== GRID_COLUMNS)
+            || lines.some((line) => cellLen(line) !== GRID_COLUMNS);
+        if (malformed) {
+            throw new Error(`A box grid is ${GRID_ROWS} lines of ${GRID_COLUMNS} single-cell `
+                + `characters; got ${lines.length} line(s) measuring `
+                + lines.map((line) => `${Array.from(line).length}/${cellLen(line)}`).join(", ")
+                + " characters/cells");
+        }
+        const rows = lines.map((line) => Array.from(line));
+        this.grid = grid;
+        this.top = edgeOf(rows[0]);
+        this.headContent = contentOf(rows[1]);
+        this.headSeparator = edgeOf(rows[2]);
+        this.bodyContent = contentOf(rows[3]);
+        this.rowSeparator = edgeOf(rows[4]);
+        this.footSeparator = edgeOf(rows[5]);
+        this.footContent = contentOf(rows[6]);
+        this.bottom = edgeOf(rows[7]);
+    }
+    /**
+     * Renders the top border row for given column widths.
+     */
+    getTop(widths, style, edge = true) {
+        return this.getEdge(widths, this.top, style, edge);
+    }
+    /**
+     * Renders the separator drawn *above* a row at `level` — the head separator
+     * under the header, the row separator between body rows, the foot separator
+     * above the footer.
+     */
+    getRow(widths, level, style, edge = true) {
+        return this.getEdge(widths, this.getRowChars(level), style, edge);
+    }
+    /**
+     * The verticals that frame a content row at `level` — the counterpart to
+     * `getRow`, which draws the separator between two such rows.
+     */
+    getContentChars(level) {
+        switch (level) {
+            case "head":
+                return this.headContent;
+            // `mid` is a spacer between body rows, so it is framed as one.
+            case "row":
+            case "mid":
+                return this.bodyContent;
+            case "foot":
+                return this.footContent;
+        }
+    }
+    /**
+     * Renders the bottom border row.
+     */
+    getBottom(widths, style, edge = true) {
+        return this.getEdge(widths, this.bottom, style, edge);
+    }
+    /**
+     * The box to draw with when the platform cannot render this one as written.
+     *
+     * `asciiOnly` gives up a box that spends non-ASCII glyphs for `ASCII`, and
+     * leaves the four already-ASCII styles as they are — a caller that chose
+     * MARKDOWN or ASCII_DOUBLE_HEAD asked for that frame and it is already
+     * drawable, so answering with `ASCII` would trade a frame the terminal
+     * supports for a different one it equally supports. `safe` squares off the
+     * rounded corners a legacy Windows terminal draws as blanks.
+     */
+    substitute(options = {}) {
+        // [LAW:one-source-of-truth] A box is wholly its grid, so the grid is what
+        // says whether it is already drawable — for a box built by `safeSubstitute`
+        // as much as for a shipped constant.
+        const drawn = drawable(options, this, ASCII, (box) => box.grid);
+        return drawn === this && options.safe === true ? this.safeSubstitute() : drawn;
+    }
+    safeSubstitute() {
+        return new Box(Array.from(this.grid, (char) => SAFE_SUBSTITUTIONS[char] ?? char).join(""));
+    }
+    /**
+     * The nearest box that spends no special glyphs on a header — what a table
+     * with `showHeader: false` draws with. A box whose head row already matches
+     * its body is its own answer, so this is the identity for fourteen of the
+     * nineteen shipped styles.
+     *
+     * It stands beside `substitute` rather than joining it because the two ask
+     * unrelated questions: `substitute` asks what the *platform* can draw, this
+     * asks what the *table* contains. Nothing correlates them, so a caller that
+     * wants both wants both, and a shared options bag would only multiply the
+     * combinations either one has to reason about. [LAW:no-mode-explosion]
+     *
+     * [LAW:types-are-the-program] The relation is keyed on the grid, not on
+     * object identity as the reference's dict is. A `Box` is wholly determined by
+     * its grid — that is what the constructor takes and all eight rows derive
+     * from — so two boxes with one grid must answer this alike. Identity keying
+     * would say otherwise the moment a box arrived by any route but the shipped
+     * constant, and `safeSubstitute` above builds exactly such a box: a fresh
+     * instance carrying an unchanged grid.
+     */
+    plainHeaded() {
+        // `private` is scoped to the class, so the pairs below can be read by grid
+        // without exposing one.
+        return PLAIN_HEADED_SUBSTITUTIONS.find(([headed]) => headed.grid === this.grid)?.[1]
+            ?? this;
+    }
+    /**
+     * [LAW:dataflow-not-control-flow] Every full-width rule the box can draw is
+     * this one join; which rule it is arrives as four characters, not a branch.
+     * The rule is one segment, as the reference's `get_top` is one string, so
+     * its bytes are one styled run.
+     */
+    getEdge(widths, chars, style, edge) {
+        const inner = widths.map((width) => chars.horizontal.repeat(width)).join(chars.cross);
+        const rule = edge ? chars.left + inner + chars.right : inner;
+        return [new Segment(rule, style), Segment.line()];
+    }
+    getRowChars(level) {
+        switch (level) {
+            case "head":
+                return this.headSeparator;
+            case "row":
+                return this.rowSeparator;
+            case "foot":
+                return this.footSeparator;
+            // The reference's spacer row, not a rule: blank fill between the body
+            // row's verticals. Nothing draws it yet — rich-table-jx1 has the details.
+            case "mid":
+                return {
+                    left: this.bodyContent.left,
+                    horizontal: " ",
+                    cross: this.bodyContent.vertical,
+                    right: this.bodyContent.right,
+                };
+        }
+    }
+}
+// --- Pre-built box styles ---
+// Transcribed from Python Rich's `rich/box.py` and verified grid-for-grid
+// against it; see this module's header for the shape and why it is this shape.
+export const ASCII = new Box("+--+\n" +
+    "| ||\n" +
+    "|-+|\n" +
+    "| ||\n" +
+    "|-+|\n" +
+    "|-+|\n" +
+    "| ||\n" +
+    "+--+");
+export const ASCII2 = new Box("+-++\n" +
+    "| ||\n" +
+    "+-++\n" +
+    "| ||\n" +
+    "+-++\n" +
+    "+-++\n" +
+    "| ||\n" +
+    "+-++");
+export const ASCII_DOUBLE_HEAD = new Box("+-++\n" +
+    "| ||\n" +
+    "+=++\n" +
+    "| ||\n" +
+    "+-++\n" +
+    "+-++\n" +
+    "| ||\n" +
+    "+-++");
+export const SQUARE = new Box("┌─┬┐\n" +
+    "│ ││\n" +
+    "├─┼┤\n" +
+    "│ ││\n" +
+    "├─┼┤\n" +
+    "├─┼┤\n" +
+    "│ ││\n" +
+    "└─┴┘");
+export const SQUARE_DOUBLE_HEAD = new Box("┌─┬┐\n" +
+    "│ ││\n" +
+    "╞═╪╡\n" +
+    "│ ││\n" +
+    "├─┼┤\n" +
+    "├─┼┤\n" +
+    "│ ││\n" +
+    "└─┴┘");
+export const MINIMAL = new Box("  ╷ \n" +
+    "  │ \n" +
+    "╶─┼╴\n" +
+    "  │ \n" +
+    "╶─┼╴\n" +
+    "╶─┼╴\n" +
+    "  │ \n" +
+    "  ╵ ");
+export const MINIMAL_HEAVY_HEAD = new Box("  ╷ \n" +
+    "  │ \n" +
+    "╺━┿╸\n" +
+    "  │ \n" +
+    "╶─┼╴\n" +
+    "╶─┼╴\n" +
+    "  │ \n" +
+    "  ╵ ");
+export const MINIMAL_DOUBLE_HEAD = new Box("  ╷ \n" +
+    "  │ \n" +
+    " ═╪ \n" +
+    "  │ \n" +
+    " ─┼ \n" +
+    " ─┼ \n" +
+    "  │ \n" +
+    "  ╵ ");
+export const SIMPLE = new Box("    \n" +
+    "    \n" +
+    " ── \n" +
+    "    \n" +
+    "    \n" +
+    " ── \n" +
+    "    \n" +
+    "    ");
+export const SIMPLE_HEAD = new Box("    \n" +
+    "    \n" +
+    " ── \n" +
+    "    \n" +
+    "    \n" +
+    "    \n" +
+    "    \n" +
+    "    ");
+export const SIMPLE_HEAVY = new Box("    \n" +
+    "    \n" +
+    " ━━ \n" +
+    "    \n" +
+    "    \n" +
+    " ━━ \n" +
+    "    \n" +
+    "    ");
+export const HORIZONTALS = new Box(" ── \n" +
+    "    \n" +
+    " ── \n" +
+    "    \n" +
+    " ── \n" +
+    " ── \n" +
+    "    \n" +
+    " ── ");
+export const ROUNDED = new Box("╭─┬╮\n" +
+    "│ ││\n" +
+    "├─┼┤\n" +
+    "│ ││\n" +
+    "├─┼┤\n" +
+    "├─┼┤\n" +
+    "│ ││\n" +
+    "╰─┴╯");
+export const HEAVY = new Box("┏━┳┓\n" +
+    "┃ ┃┃\n" +
+    "┣━╋┫\n" +
+    "┃ ┃┃\n" +
+    "┣━╋┫\n" +
+    "┣━╋┫\n" +
+    "┃ ┃┃\n" +
+    "┗━┻┛");
+export const HEAVY_EDGE = new Box("┏━┯┓\n" +
+    "┃ │┃\n" +
+    "┠─┼┨\n" +
+    "┃ │┃\n" +
+    "┠─┼┨\n" +
+    "┠─┼┨\n" +
+    "┃ │┃\n" +
+    "┗━┷┛");
+export const HEAVY_HEAD = new Box("┏━┳┓\n" +
+    "┃ ┃┃\n" +
+    "┡━╇┩\n" +
+    "│ ││\n" +
+    "├─┼┤\n" +
+    "├─┼┤\n" +
+    "│ ││\n" +
+    "└─┴┘");
+export const DOUBLE = new Box("╔═╦╗\n" +
+    "║ ║║\n" +
+    "╠═╬╣\n" +
+    "║ ║║\n" +
+    "╠═╬╣\n" +
+    "╠═╬╣\n" +
+    "║ ║║\n" +
+    "╚═╩╝");
+export const DOUBLE_EDGE = new Box("╔═╤╗\n" +
+    "║ │║\n" +
+    "╟─┼╢\n" +
+    "║ │║\n" +
+    "╟─┼╢\n" +
+    "╟─┼╢\n" +
+    "║ │║\n" +
+    "╚═╧╝");
+export const MARKDOWN = new Box("    \n" +
+    "| ||\n" +
+    "|-||\n" +
+    "| ||\n" +
+    "|-||\n" +
+    "|-||\n" +
+    "| ||\n" +
+    "    ");
+/**
+ * Boxes whose header glyphs differ from their body's, paired with the kin that
+ * draws the same frame without them. Transcribed from the reference's
+ * `PLAIN_HEADED_SUBSTITUTIONS`; the fourteen styles absent here already draw a
+ * plain head, and `plainHeaded` returns them unchanged.
+ */
+const PLAIN_HEADED_SUBSTITUTIONS = [
+    [HEAVY_HEAD, SQUARE],
+    [SQUARE_DOUBLE_HEAD, SQUARE],
+    [MINIMAL_HEAVY_HEAD, MINIMAL],
+    [MINIMAL_DOUBLE_HEAD, MINIMAL],
+    [ASCII_DOUBLE_HEAD, ASCII2],
+];

package/dist/core/cells.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Terminal cell width calculation.
+ * Handles ASCII, CJK (double-width), and emoji characters.
+ */
+/**
+ * Returns the terminal cell width of a string.
+ */
+export declare function cellLen(text: string): number;
+declare const _cellCol: unique symbol;
+declare const _codeUnit: unique symbol;
+declare const _codePoint: unique symbol;
+/** Terminal cell-column offset. Never interchangeable with a code-unit index. */
+export type CellCol = number & {
+    readonly [_cellCol]: true;
+};
+/** JS string code-unit index. Never interchangeable with a cell-column offset. */
+export type CodeUnit = number & {
+    readonly [_codeUnit]: true;
+};
+/**
+ * A `CodeUnit` index that is additionally guaranteed to fall on a Unicode
+ * code-point boundary (i.e. never inside a surrogate pair). Assignable to
+ * `CodeUnit`; the reverse assignment is forbidden.
+ */
+export type CodePoint = CodeUnit & {
+    readonly [_codePoint]: true;
+};
+/** Brand a raw number as a CellCol. Use only at trust boundaries. */
+export declare function asCellCol(n: number): CellCol;
+/** Brand a raw number as a CodeUnit. Use only at trust boundaries. */
+export declare function asCodeUnit(n: number): CodeUnit;
+/** Brand a raw number as a CodePoint. Use only when the value is known to be
+ *  on a Unicode code-point boundary. */
+export declare function asCodePoint(n: number): CodePoint;
+/**
+ * [LAW:parse-dont-validate] A caller's number as a count of cells — the checked
+ * counterpart to `asCellCol`'s unchecked brand, and the one place the rule "a
+ * cell count is a non-negative integer" is written.
+ *
+ * [LAW:one-source-of-truth] Every renderable is handed `RenderOptions.maxWidth`
+ * as a plain `number`, so every renderable used to answer this for itself and
+ * they disagreed: at NaN, `Table` collapsed to one cell of garbage, `Columns`
+ * and `Layout` threw `Invalid array length`, and `RichText` ignored the request
+ * and emitted its full natural width. Parse at the entry to `render`/`measure`
+ * and nothing downstream re-asks.
+ *
+ * The comparison is the point, not `Math.max(0, n)`: NaN fails every comparison
+ * and so floors here, where `Math.max` would return it and let it poison every
+ * bounds check downstream. Integral because a cell is not divisible — a
+ * fractional budget reaches a largest-remainder division, which grants a whole
+ * cell against a fractional residue and hands out more width than it was given.
+ *
+ * `Infinity` is outside what the comparison floors, so it passes through
+ * unchanged, and no clamp belongs here: the finite answer to an unbounded offer
+ * is the renderable's own natural width, which this function cannot see from
+ * the number alone. `withBoundedWidth` in `protocol.ts` is the second half of
+ * the parse and the only place that value is resolved.
+ */
+export declare function cellCount(n: number): CellCol;
+/**
+ * Pads or crops a string to exactly `totalWidth` terminal cells.
+ * Invariant: cellLen(setCellSize(text, n)) === n (unless n is 0)
+ */
+export declare function setCellSize(text: string, totalWidth: CellCol): string;
+/**
+ * Splits text at a cell position. Returns [left, right].
+ * When the position falls mid-wide-character, the left side is padded
+ * to reach exactly `position` cells. The wide char remains in the right side.
+ *
+ * [LAW:one-source-of-truth] The left side is `cellFit`'s, so the cut falls
+ * between the grapheme clusters `cellLen` measures and never inside one.
+ */
+export declare function splitText(text: string, position: CellCol): [string, string];
+/**
+ * Cuts `text` into exactly `position` cells and the rest, as the reference's
+ * `Segment.split_cells` does: a wide glyph the cut goes through fits neither
+ * side, so it leaves a space in each of its cells, where `splitText` keeps it
+ * whole on the right. Every other character lands on exactly one side.
+ * `position` must fall inside `text`, between 0 and its width.
+ */
+export declare function cutCells(text: string, position: CellCol): [string, string];
+/**
+ * Wraps text into lines of at most `maxWidth` cells, preserving every code
+ * point: `chopCells(t, w).join("") === t`. Unlike `splitText` this never pads,
+ * so a line ending before a wide glyph is narrower than `maxWidth` rather than
+ * padded out to it.
+ *
+ * A line overflows exactly where the budget cannot be met: a glyph wider than
+ * `maxWidth` is force-taken whole rather than dropped, and a `maxWidth` of zero
+ * or less is no budget at all, so the text comes back as one line.
+ */
+export declare function chopCells(text: string, maxWidth: CellCol): string[];
+/**
+ * `line` split at each of `cuts`, in one walk over it. Converting each cut to a
+ * code-unit offset on its own rescans the line from the start every time, which
+ * is quadratic in a long enough string.
+ */
+export declare function splitAtCells(line: string, cuts: readonly CellCol[]): string[];
+/**
+ * The grapheme clusters of `text`, in order: the unit `string-width` measures,
+ * and so the unit `cellLen` of a whole string is the sum of. Summing `cellLen`
+ * over code points instead disagrees with it on every glyph built from several:
+ * `❤️` is 1 + 0 by code point and 2 as a cluster, `👨‍👩‍👧` is 6 and 2, and a cut
+ * between two of its code points leaves half a glyph.
+ */
+export declare function graphemes(text: string): string[];
+/**
+ * Returns the largest prefix of `text` whose cell width fits within `cap` cells,
+ * cut between grapheme clusters. No padding — the returned string may be
+ * narrower than `cap` when the next glyph is wide and would overshoot. Never
+ * wider than `cap` cells.
+ *
+ * When the first glyph already exceeds `cap` cells, returns "" (the caller
+ * must decide whether to force-take the glyph or skip it).
+ */
+export declare function cellFit(text: string, cap: CellCol): string;
+/** `cellFit` from the other end: the largest suffix of `text` within `cap` cells. */
+export declare function cellFitEnd(text: string, cap: CellCol): string;
+/**
+ * Returns the largest code-unit end offset starting from `startCU` whose
+ * prefix (from `startCU`) has cell width ≤ `cap`. Iterates from the given
+ * offset without slicing the tail, avoiding O(N²) allocation when called
+ * repeatedly across a long string.
+ *
+ * [LAW:types-are-the-program] returns CodePoint because it stops between
+ * grapheme clusters, and every cluster boundary is a code-point boundary.
+ */
+export declare function cellFitFrom(text: string, startCU: CodePoint, cap: CellCol): CodePoint;
+/**
+ * Like `cellFitFrom`, but for any `startCU` inside `text` the result is
+ * strictly past it: a glyph too wide for `cap` is force-taken whole and
+ * overflows `cap` by its own width. So a `while (i < text.length)` loop driven
+ * by this terminates by construction, and the re-brand is honest — both
+ * operands land on code-point boundaries, so their max does too.
+ *
+ * [LAW:single-enforcer] `cellFit` documents that its caller must choose between
+ * force-taking and skipping; this is that choice, made once. It was made twice
+ * before and the copies drifted — the textarea's soft wrap force-took,
+ * `chopCells` did neither and hung.
+ */
+export declare function cellStepFrom(text: string, startCU: CodePoint, cap: CellCol): CodePoint;
+/**
+ * The code-unit offset a visual column falls at: the end of the largest
+ * prefix of `content` within `cellCol` cells, so a column inside a wide glyph
+ * lands before it. The inverse of `cellLen(content.slice(0, offset))`.
+ */
+export declare function cellColToCodeUnitOffset(content: string, cellCol: CellCol): CodePoint;
+/**
+ * The offset just past the grapheme cluster at `cu`: one step of a cursor, a
+ * Delete, a transposition, so `👍🏽` or `👨‍👩‍👧` moves and goes as the one
+ * glyph `cellLen` measures, never a code point at a time. `cu` is a cluster
+ * boundary in `s` (see `graphemeBoundary`); `s.length` gives `s.length`.
+ */
+export declare function nextGrapheme(s: string, cu: CodePoint): CodePoint;
+/** `nextGrapheme` backwards: the start of the cluster ending at `cu`; 0 at the start. */
+export declare function prevGrapheme(s: string, cu: CodePoint): CodePoint;
+/**
+ * Where an offset into `s` comes to rest as a cursor: itself when it is a
+ * cluster boundary, else the end of the cluster it falls inside, and never
+ * past `s.length`. The one parse from any number to the boundaries
+ * `nextGrapheme` and `prevGrapheme` step between.
+ */
+export declare function graphemeBoundary(s: string, cu: CodeUnit): CodePoint;
+declare const _tabSize: unique symbol;
+/** Cells between tab stops: a positive integer, so every stop is a column. */
+export type TabSize = number & {
+    readonly [_tabSize]: true;
+};
+/**
+ * `n` as a `TabSize`, or a `RangeError` naming it. Rich divides by the tab
+ * size and raises on 0; here the value is refused where it is given, not at
+ * the first tab it meets.
+ */
+export declare function parseTabSize(n: number): TabSize;
+/** Text with its tabs expanded, and where each offset into the original went. */
+export interface TabExpansion {
+    readonly text: string;
+    offsetOf(offset: number): number;
+}
+/**
+ * `text` with each tab widened to the next tab stop — a multiple of `tabSize`
+ * cells from the start of its line — as Rich's `Text.expand_tabs` widens it, and
+ * `offsetOf`, where each code-unit offset into `text` lands in the result.
+ *
+ * A tab is a column position, not a run of spaces: one that already sits a
+ * cell short of a stop widens to a single space. `offsetOf` is there because a
+ * caller that annotates the text by offset — a `RichText`'s spans — has to move
+ * its offsets with the characters, or every annotation after a tab lands short
+ * of what it styled.
+ */
+export declare function expandTabs(text: string, tabSize: TabSize): TabExpansion;
+export {};