@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/renderables/syntax.d.ts

@@ -1,35 +1,65 @@
 /**
  * Syntax — renders source code with basic syntax highlighting.
  * Uses built-in tokenization (no external dependency).
+ *
+ * Colours are names in the console's theme (`syntax.keyword`,
+ * `syntax.line_number`, …), not a per-instance palette: a theme is how every
+ * other renderable here is restyled, and a second styling vocabulary on this
+ * one class would be a second answer to "what colour is a keyword".
  */
 import { Segment } from "../core/segment.js";
-import type { PaddingDimensions } from "./padding.js";
 import { type Measurable, type Renderable, type RenderOptions } from "../core/protocol.js";
 export interface SyntaxOptions {
     lineNumbers?: boolean;
-    theme?: string;
     startLine?: number;
     lineRange?: [number, number];
     highlightLines?: Set<number>;
     wordWrap?: boolean;
     tabSize?: number;
-    padding?: PaddingDimensions;
 }
+/**
+ * [LAW:one-type-per-behavior] A language is a value here — a grammar — not a
+ * code path. The union is the set of languages this module can actually
+ * tokenize, so a name it cannot is a compile error rather than a silent plain
+ * render; `"text"` is the grammar with no rules.
+ */
+declare const GRAMMARS: {
+    javascript: RegExp;
+    typescript: RegExp;
+    python: RegExp;
+    bash: RegExp;
+    text: RegExp;
+};
+export type SyntaxLanguage = keyof typeof GRAMMARS;
 export declare class Syntax implements Renderable, Measurable {
     readonly code: string;
-    readonly language: string;
+    readonly language: SyntaxLanguage;
     readonly lineNumbers: boolean;
     readonly startLine: number;
     readonly lineRange: [number, number] | undefined;
     readonly highlightLines: Set<number>;
     readonly wordWrap: boolean;
     readonly tabSize: number;
-    constructor(code: string, language?: string, options?: SyntaxOptions);
+    /** The code with its tabs expanded, as lines — what both render and measure read. */
+    private readonly _lines;
+    constructor(code: string, language?: SyntaxLanguage, options?: SyntaxOptions);
+    /**
+     * The lines shown, as a 0-based half-open slice of `_lines`, and the number
+     * the first is given — render and measure both read them here, so a range
+     * counts the same in each. `lineRange` is 1-based and inclusive, and a line
+     * keeps the number it has in the whole code: `[3, 4]` shows lines 3 and 4
+     * numbered 3 and 4 (with a `startLine` of 1), as Rich does. A range reaching
+     * outside the code shows the part inside it, which may be none.
+     */
+    private _shown;
+    /** Digits of the last number, a space, and the `│ ` rule; nothing without numbers. */
+    private _gutterWidth;
     render(options: RenderOptions): Iterable<Segment>;
+    private _rows;
+    /** The gutter is the narrowest it can be drawn; the widest shown line plus the gutter, the widest. */
     measure(options: RenderOptions): {
         minimum: number;
         maximum: number;
     };
-    private _highlight;
-    static fromPath(_filePath: string, _options?: SyntaxOptions): Syntax;
 }
+export {};

package/dist/renderables/syntax.js

@@ -1,34 +1,64 @@
 /**
  * Syntax — renders source code with basic syntax highlighting.
  * Uses built-in tokenization (no external dependency).
+ *
+ * Colours are names in the console's theme (`syntax.keyword`,
+ * `syntax.line_number`, …), not a per-instance palette: a theme is how every
+ * other renderable here is restyled, and a second styling vocabulary on this
+ * one class would be a second answer to "what colour is a keyword".
  */
-import { cellLen } from "../core/cells.js";
+import { cellLen, expandTabs, parseTabSize } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
-import { Style } from "../core/style.js";
 import { RichText } from "../core/text.js";
-import { drawable } from "../core/protocol.js";
-// Built-in token patterns for common languages
-const TOKEN_PATTERNS = {
-    _default: [
-        [/\/\/.*$/gm, "comment"],
-        [/\/\*[\s\S]*?\*\//g, "comment"],
-        [/#.*$/gm, "comment"],
-        [/"(?:[^"\\]|\\.)*"/g, "string"],
-        [/'(?:[^'\\]|\\.)*'/g, "string"],
-        [/`(?:[^`\\]|\\.)*`/g, "string"],
-        [/\b(?:true|false|null|undefined|NaN|Infinity)\b/g, "keyword.constant"],
-        [/\b(?:function|class|const|let|var|return|if|else|for|while|do|switch|case|break|continue|new|throw|try|catch|finally|import|export|from|default|async|await|yield|of|in|typeof|instanceof|void|delete)\b/g, "keyword"],
-        [/\b(?:def|lambda|with|as|pass|raise|elif|except|print|self|cls|None|True|False)\b/g, "keyword"],
-        [/\b\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\b/g, "number"],
-        [/\b0x[0-9a-fA-F]+\b/g, "number"],
-    ],
-};
-const TOKEN_STYLES = {
-    "keyword": Style.parse("bold magenta"),
-    "keyword.constant": Style.parse("italic bright_magenta"),
-    "string": Style.parse("green"),
-    "number": Style.parse("cyan"),
-    "comment": Style.parse("dim italic"),
+import { drawable, groundedStyle, getStyle, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+/**
+ * One regex per grammar, each token a named alternative. A single left-to-right
+ * scan is what keeps a `//` inside a string from starting a comment, and a
+ * keyword inside a comment from being drawn as one: at any position the
+ * leftmost match wins, and among matches starting there the earliest rule.
+ * `(?!)` never matches, so a grammar with no rules is still a regex.
+ */
+function grammar(rules) {
+    return new RegExp([...rules.map(([token, source]) => `(?<${token}>${source})`), "(?!)"].join("|"), "g");
+}
+// Not after a `.`: `map.get` and `node.type` are properties, not keywords.
+const words = (list) => `(?<!\\.)\\b(?:${list.split(" ").join("|")})\\b`;
+const NUMBER = String.raw `\b(?:0x[0-9a-fA-F]+|\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)\b`;
+const QUOTED = String.raw `"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'`;
+const JS_KEYWORDS = "function class const let var return if else for while do switch case break continue new throw try catch " +
+    "finally import export from default async await yield of in typeof instanceof void delete this super extends static";
+const TS_KEYWORDS = "interface type enum implements private public protected readonly as declare namespace keyof satisfies abstract is infer";
+const JAVASCRIPT = [
+    ["comment", String.raw `\/\/[^\n]*|\/\*[\s\S]*?\*\/`],
+    ["string", String.raw `${QUOTED}|` + "`(?:[^`\\\\]|\\\\.)*`"],
+    ["constant", words("true false null undefined NaN Infinity")],
+    ["keyword", words(JS_KEYWORDS)],
+    ["number", NUMBER],
+];
+/**
+ * [LAW:one-type-per-behavior] A language is a value here — a grammar — not a
+ * code path. The union is the set of languages this module can actually
+ * tokenize, so a name it cannot is a compile error rather than a silent plain
+ * render; `"text"` is the grammar with no rules.
+ */
+const GRAMMARS = {
+    javascript: grammar(JAVASCRIPT),
+    typescript: grammar(JAVASCRIPT.map(([token, source]) => token === "keyword" ? [token, words(`${JS_KEYWORDS} ${TS_KEYWORDS}`)] : [token, source])),
+    python: grammar([
+        ["comment", "#[^\\n]*"],
+        ["string", String.raw `"""[\s\S]*?"""|'''[\s\S]*?'''|${QUOTED}`],
+        ["constant", words("True False None")],
+        ["keyword", words("def class return if elif else for while in not and or is import from as with try except finally raise " +
+                "pass break continue lambda yield global nonlocal assert del async await self cls")],
+        ["number", NUMBER],
+    ]),
+    bash: grammar([
+        ["comment", "(?<![^\\s;])#[^\\n]*"],
+        ["string", QUOTED],
+        ["keyword", words("if then else elif fi for while until do done case esac function in return local export select")],
+        ["number", NUMBER],
+    ]),
+    text: grammar([]),
 };
 export class Syntax {
     code;
@@ -39,77 +69,98 @@ export class Syntax {
     highlightLines;
     wordWrap;
     tabSize;
-    constructor(code, language, options) {
+    /** The code with its tabs expanded, as lines — what both render and measure read. */
+    _lines;
+    constructor(code, language = "text", options) {
+        // A plain-JS caller, or one passing a language read at runtime, gets past
+        // the type; left here, the name surfaces at render as a TypeError about
+        // `undefined`. [LAW:no-silent-failure] Refused where it is given, by name.
+        if (!Object.hasOwn(GRAMMARS, language)) {
+            throw new TypeError(`Syntax has no grammar for ${JSON.stringify(language)}: use one of ${Object.keys(GRAMMARS).join(", ")}`);
+        }
         this.code = code;
-        this.language = language ?? "text";
+        this.language = language;
         this.lineNumbers = options?.lineNumbers ?? false;
         this.startLine = options?.startLine ?? 1;
         this.lineRange = options?.lineRange;
         this.highlightLines = options?.highlightLines ?? new Set();
         this.wordWrap = options?.wordWrap ?? false;
-        this.tabSize = options?.tabSize ?? 4;
+        const tabSize = parseTabSize(options?.tabSize ?? 4);
+        this.tabSize = tabSize;
+        this._lines = expandTabs(code, tabSize).text.split("\n");
+    }
+    /**
+     * The lines shown, as a 0-based half-open slice of `_lines`, and the number
+     * the first is given — render and measure both read them here, so a range
+     * counts the same in each. `lineRange` is 1-based and inclusive, and a line
+     * keeps the number it has in the whole code: `[3, 4]` shows lines 3 and 4
+     * numbered 3 and 4 (with a `startLine` of 1), as Rich does. A range reaching
+     * outside the code shows the part inside it, which may be none.
+     */
+    _shown() {
+        const [start, end] = this.lineRange ?? [1, this._lines.length];
+        const from = Math.max(0, start - 1);
+        return { first: this.startLine + from, from, to: Math.max(from, end) };
+    }
+    /** Digits of the last number, a space, and the `│ ` rule; nothing without numbers. */
+    _gutterWidth(first, count) {
+        return this.lineNumbers ? String(first + count - 1).length + 3 : 0;
     }
     *render(options) {
-        const expandedCode = this.code.replace(/\t/g, " ".repeat(this.tabSize));
-        let lines = expandedCode.split("\n");
-        // Apply line range
-        if (this.lineRange) {
-            const [start, end] = this.lineRange;
-            lines = lines.slice(start - 1, end);
-        }
-        const lineNumWidth = this.lineNumbers
-            ? String(this.startLine + lines.length - 1).length + 1
-            : 0;
-        // Tokenize the full text for highlighting
-        const text = new RichText(lines.join("\n"), { end: "" });
-        this._highlight(text);
-        const textLines = text.split("\n");
-        for (let i = 0; i < textLines.length; i++) {
-            const lineNo = this.startLine + i;
-            const isHighlighted = this.highlightLines.has(lineNo);
-            if (this.lineNumbers) {
-                const numStr = String(lineNo).padStart(lineNumWidth - 1) + " ";
-                const numStyle = isHighlighted
-                    ? Style.parse("bold on grey27")
-                    : Style.parse("dim");
-                yield new Segment(numStr, numStyle);
-                yield new Segment(drawable(options, "│ ", "| "), Style.parse("dim"));
-            }
-            const line = textLines[i];
-            const segs = [...line.render({ ...options, maxWidth: options.maxWidth - lineNumWidth - 2 })];
-            // Filter out trailing newline from render
-            for (const seg of segs) {
-                if (seg.text !== "\n")
-                    yield seg;
-            }
-            yield Segment.line();
-        }
+        const bounded = withBoundedWidth(options, this);
+        // A gutter wider than the offer is cut at its edge like any other row.
+        yield* Segment.cropLines(this._rows(bounded), bounded.maxWidth);
     }
-    measure(options) {
-        const lines = this.code.split("\n");
-        let maxLine = 0;
-        for (const line of lines) {
-            maxLine = Math.max(maxLine, cellLen(line));
+    *_rows(options) {
+        const { first, from, to } = this._shown();
+        const numberStyle = getStyle(options, "syntax.line_number");
+        const highlightStyle = groundedStyle(options, getStyle(options, "syntax.line_number.highlight"));
+        const rule = drawable(options, "│ ", "| ");
+        // Tokenized whole and then sliced, so a block comment or a triple-quoted
+        // string that spans lines is one token even when the range starts inside it.
+        const text = new RichText(this._lines.join("\n"), { end: "" });
+        for (const match of text.plain.matchAll(GRAMMARS[this.language])) {
+            const [token] = Object.entries(match.groups).find(([, value]) => value !== undefined);
+            text.stylize(`syntax.${token}`, match.index, match.index + match[0].length);
         }
-        const lineNumWidth = this.lineNumbers
-            ? String(this.startLine + lines.length - 1).length + 3
-            : 0;
-        return {
-            minimum: 10,
-            maximum: Math.min(maxLine + lineNumWidth, options.maxWidth),
+        const textLines = text.split("\n").slice(from, to);
+        const gutterWidth = this._gutterWidth(first, textLines.length);
+        // [LAW:dataflow-not-control-flow] `wordWrap` reaches the line as the
+        // overflow it is drawn with, not as a second path: wrapped, a line may
+        // become several rows; cropped, it is always one. Never justified: a
+        // caller's `justify` would align each line alone and lose its indent.
+        const lineOptions = {
+            ...options,
+            maxWidth: Math.max(0, options.maxWidth - gutterWidth),
+            justify: undefined,
+            noWrap: !this.wordWrap,
+            overflow: this.wordWrap ? "fold" : "crop",
         };
-    }
-    _highlight(text) {
-        const patterns = TOKEN_PATTERNS["_default"] ?? [];
-        for (const [pattern, tokenType] of patterns) {
-            const style = TOKEN_STYLES[tokenType];
-            if (style) {
-                text.highlightRegex(pattern, style);
+        for (let i = 0; i < textLines.length; i++) {
+            const lineNo = first + i;
+            const style = this.highlightLines.has(lineNo) ? highlightStyle : numberStyle;
+            // Terminated, so an empty line is one empty row rather than none.
+            const rows = Segment.splitLines([...textLines[i].render(lineOptions), Segment.line()]);
+            for (let row = 0; row < rows.length; row++) {
+                if (this.lineNumbers) {
+                    // A wrapped line's continuation rows keep the gutter, unnumbered.
+                    const label = row === 0 ? String(lineNo) : "";
+                    yield new Segment(label.padStart(gutterWidth - 3) + " ", style);
+                    yield new Segment(rule, numberStyle);
+                }
+                yield* rows[row];
+                yield Segment.line();
             }
         }
     }
-    static fromPath(_filePath, _options) {
-        // In a real implementation, this would read the file and detect language
-        throw new Error("Syntax.fromPath requires file system access — use the constructor with code string instead");
+    /** The gutter is the narrowest it can be drawn; the widest shown line plus the gutter, the widest. */
+    measure(options) {
+        const { maxWidth } = withCellWidth(options);
+        const { first, from, to } = this._shown();
+        const lines = this._lines.slice(from, to);
+        const gutterWidth = this._gutterWidth(first, lines.length);
+        const widest = lines.reduce((width, line) => Math.max(width, cellLen(line)), 0);
+        const maximum = Math.min(gutterWidth + widest, maxWidth);
+        return { minimum: Math.min(gutterWidth, maximum), maximum };
     }
 }

package/dist/renderables/table.d.ts

@@ -8,8 +8,9 @@ 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;
+    /** 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;
@@ -20,6 +21,12 @@ export interface ColumnOptions {
     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;
@@ -34,15 +41,15 @@ export declare class Column {
     ratio: number | undefined;
     noWrap: boolean;
     overflow: OverflowMethod;
+    highlight: boolean;
     private _cells;
     constructor(options?: ColumnOptions);
     /**
-     * The two stamped cells, parsed on assignment rather than at the constructor.
+     * 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 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
+     * — 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.
      *
@@ -51,13 +58,13 @@ export declare class Column {
      * 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,
+     * 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(): RichText;
-    set header(content: string | RichText | undefined);
-    get footer(): RichText;
-    set footer(content: string | RichText | undefined);
+    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;
@@ -75,6 +82,8 @@ export interface TableOptions {
     showLines?: boolean;
     showEdge?: boolean;
     padding?: PaddingDimensions;
+    collapsePadding?: boolean;
+    padEdge?: boolean;
     style?: string | Style;
     headerStyle?: string | Style;
     footerStyle?: string | Style;
@@ -86,19 +95,23 @@ export interface TableOptions {
     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;
-    readonly title: RichText | undefined;
-    readonly caption: RichText | undefined;
+    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;
@@ -110,17 +123,20 @@ export declare class Table implements Renderable, Measurable {
     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?: string | RichText, options?: ColumnOptions): this;
+    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 a single cell.
+     * 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
@@ -137,6 +153,12 @@ export declare class Table implements Renderable, Measurable {
         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;
     /**
@@ -159,8 +181,23 @@ export declare class Table implements Renderable, Measurable {
      * 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.
      *
@@ -174,12 +211,13 @@ export declare class Table implements Renderable, Measurable {
      */
     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]
+     * 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 _widestCell;
+    private _cellRange;
     /**
      * A natural width held to the column's own `minWidth`/`maxWidth`.
      *