@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/renderables/rule.js

@@ -0,0 +1,86 @@
+/**
+ * Rule — a horizontal divider line, optionally with a centered title.
+ */
+import { asCellCol, cellLen, setCellSize } from "../core/cells.js";
+import { Segment } from "../core/segment.js";
+import { NULL_STYLE } from "../core/style.js";
+import { drawable, getStyle } from "../core/protocol.js";
+import { cutLabel, drawLabel, inlineLabel } from "./embed.js";
+const ASCII_RULE_CHAR = "-";
+const DEFAULT_RULE_CHAR = "\u2500"; // ─
+export class Rule {
+    title;
+    characters;
+    align;
+    style;
+    _label;
+    constructor(title, options) {
+        const chars = options?.characters ?? DEFAULT_RULE_CHAR;
+        // [LAW:parse-dont-validate] Rich's rule: a rule drawn from zero-width
+        // characters would advance no cells, so `repeatToWidth` never meets one.
+        if (cellLen(chars) < 1) {
+            throw new Error("Rule characters must have a cell width of at least 1");
+        }
+        const align = options?.align;
+        if (align !== undefined && align !== "left" && align !== "center" && align !== "right") {
+            throw new Error(`Invalid align value: "${align}"`);
+        }
+        this.title = title;
+        this._label = inlineLabel(title);
+        this.characters = chars;
+        this.align = align ?? "center";
+        this.style = options?.style ?? NULL_STYLE;
+    }
+    *render(options) {
+        const maxWidth = options.maxWidth;
+        const ruleChar = drawable(options, this.characters, ASCII_RULE_CHAR);
+        const style = getStyle(options, this.style);
+        const ruleStyle = style.isNull ? undefined : style;
+        const line = (width) => new Segment(repeatToWidth(ruleChar, width), ruleStyle);
+        // Rich's `required_space`: a centred title keeps a rule cell and a space
+        // either side of it, an aligned one a space and a rule cell on its open
+        // side. A rule with no room past that draws no title, as one without a title.
+        const room = Math.max(0, maxWidth - (this.align === "center" ? 4 : 2));
+        if (this._label === undefined || room === 0) {
+            yield line(maxWidth);
+            yield Segment.line();
+            return;
+        }
+        const text = this._label.text(options);
+        cutLabel(text, room, drawable(options, "\u2026", "."));
+        const title = drawLabel(text, options, ruleStyle);
+        const titleWidth = Segment.getLineLength(title);
+        // As Rich lays the line out: the gaps of a centred title are the rule's,
+        // styled with it; an aligned title's one gap is unstyled.
+        switch (this.align) {
+            case "center": {
+                const left = Math.floor((maxWidth - titleWidth) / 2) - 1;
+                yield line(left);
+                yield new Segment(" ", ruleStyle);
+                yield* title;
+                yield new Segment(" ", ruleStyle);
+                yield line(maxWidth - left - titleWidth - 2);
+                break;
+            }
+            case "left":
+                yield* title;
+                yield new Segment(" ");
+                yield line(maxWidth - titleWidth - 1);
+                break;
+            case "right":
+                yield line(maxWidth - titleWidth - 1);
+                yield new Segment(" ");
+                yield* title;
+                break;
+        }
+        yield Segment.line();
+    }
+    measure(_options) {
+        return { minimum: 1, maximum: _options.maxWidth };
+    }
+}
+// [LAW:one-source-of-truth] `setCellSize` crops between the grapheme clusters
+// `cellLen` measures, so `❤️` or `👨‍👩‍👧` is never cut in half or over-counted.
+function repeatToWidth(char, width) {
+    return setCellSize(char.repeat(Math.ceil(width / cellLen(char))), asCellCol(width));
+}

package/dist/renderables/spinner.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Spinner — animated terminal spinner with optional text label.
+ */
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import { RichText } from "../core/text.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export interface SpinnerOptions {
+    speed?: number;
+    style?: string | Style;
+}
+export declare class Spinner implements Renderable, Measurable {
+    readonly name: string;
+    readonly speed: number;
+    readonly style: string | Style;
+    /**
+     * The label drawn after the frame. It is read through `embed`'s one crossing
+     * each time it is drawn, so a string is markup under the console that draws
+     * it, as a string handed to `print` is — where Rich's `Spinner` parses it
+     * whatever the console says — and a `RichText` changed in place draws as
+     * changed, as the `Text` Rich keeps does. [LAW:single-enforcer]
+     */
+    text: string | RichText;
+    private readonly _data;
+    private _frameIndex;
+    private _lastUpdate;
+    constructor(name?: string, text?: string | RichText, options?: SpinnerOptions);
+    get frames(): readonly string[];
+    get interval(): number;
+    /** Advance the frame count by the time elapsed, and return it. */
+    private _advance;
+    /** The frames this output can draw: the `line` spinner stands in for any other on an ASCII-only one. */
+    private _drawnFrames;
+    /**
+     * The current frame and its label as one line wrapped to the width and
+     * ended, as the reference's `Text` is — printed, stacked in a `Group`, or
+     * laid out in a `Progress` cell alike.
+     */
+    render(options: RenderOptions): Iterable<Segment>;
+    private _currentLine;
+    /**
+     * `frame` and the label as one text, as Rich's `Text.assemble(frame, " ",
+     * text)`: a long label wraps as one line with its frame. A label that draws
+     * nothing — the default `""`, or markup that styles nothing — is no label,
+     * not a trailing space, as an empty `Text` is falsy there.
+     */
+    private _line;
+    /**
+     * Measured at its widest frame, so a column holding it never narrows as it
+     * turns, and never offered less than that frame: a frame is one picture,
+     * which the reference's `Text` measure would let wrap apart at its spaces.
+     */
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/spinner.js

@@ -0,0 +1,103 @@
+/**
+ * Spinner — animated terminal spinner with optional text label.
+ */
+import { cellLen } from "../core/cells.js";
+import { Segment } from "../core/segment.js";
+import { NULL_STYLE } from "../core/style.js";
+import { RichText } from "../core/text.js";
+import { SPINNERS, DEFAULT_SPINNER, LINE_SPINNER } from "../core/spinnerData.js";
+import { drawable } from "../core/protocol.js";
+import { EmbeddedText } from "./embed.js";
+const spinnerGlyphs = ({ frames }) => frames.join("");
+export class Spinner {
+    name;
+    speed;
+    style;
+    /**
+     * The label drawn after the frame. It is read through `embed`'s one crossing
+     * each time it is drawn, so a string is markup under the console that draws
+     * it, as a string handed to `print` is — where Rich's `Spinner` parses it
+     * whatever the console says — and a `RichText` changed in place draws as
+     * changed, as the `Text` Rich keeps does. [LAW:single-enforcer]
+     */
+    text;
+    _data;
+    _frameIndex;
+    _lastUpdate;
+    constructor(name, text = "", options) {
+        const spinnerName = name ?? DEFAULT_SPINNER;
+        const data = SPINNERS[spinnerName];
+        if (!data) {
+            throw new Error(`Unknown spinner: "${spinnerName}"`);
+        }
+        this.name = spinnerName;
+        this.text = text;
+        this.speed = options?.speed ?? 1;
+        this.style = options?.style ?? NULL_STYLE;
+        this._data = data;
+        this._frameIndex = 0;
+        this._lastUpdate = Date.now();
+    }
+    get frames() {
+        return this._data.frames;
+    }
+    get interval() {
+        return this._data.interval;
+    }
+    /** Advance the frame count by the time elapsed, and return it. */
+    _advance() {
+        const now = Date.now();
+        // Whole frames passed at this speed; a negative speed steps backwards, as
+        // Rich's does, so the index wraps with a modulo that is never negative.
+        const steps = Math.trunc(((now - this._lastUpdate) * this.speed) / this.interval);
+        if (steps !== 0) {
+            const count = this._data.frames.length;
+            this._frameIndex = (((this._frameIndex + steps) % count) + count) % count;
+            this._lastUpdate = now;
+        }
+        return this._frameIndex;
+    }
+    /** The frames this output can draw: the `line` spinner stands in for any other on an ASCII-only one. */
+    _drawnFrames(options) {
+        return drawable(options, this._data, LINE_SPINNER, spinnerGlyphs).frames;
+    }
+    /**
+     * The current frame and its label as one line wrapped to the width and
+     * ended, as the reference's `Text` is — printed, stacked in a `Group`, or
+     * laid out in a `Progress` cell alike.
+     */
+    *render(options) {
+        yield* this._currentLine(options).render(options);
+        yield Segment.line();
+    }
+    _currentLine(options) {
+        const frames = this._drawnFrames(options);
+        return this._line(frames[this._advance() % frames.length], options);
+    }
+    /**
+     * `frame` and the label as one text, as Rich's `Text.assemble(frame, " ",
+     * text)`: a long label wraps as one line with its frame. A label that draws
+     * nothing — the default `""`, or markup that styles nothing — is no label,
+     * not a trailing space, as an empty `Text` is falsy there.
+     */
+    _line(frame, options) {
+        const line = new RichText("", { end: "" }).append(frame, this.style);
+        // Unhighlighted: Rich's label is a `Text` from the moment it is handed over, and a `Text` is never highlighted.
+        const label = new EmbeddedText(this.text).text({ ...options, highlight: false });
+        if (label.plain !== "")
+            line.append(" ").append(label);
+        return line;
+    }
+    /**
+     * Measured at its widest frame, so a column holding it never narrows as it
+     * turns, and never offered less than that frame: a frame is one picture,
+     * which the reference's `Text` measure would let wrap apart at its spaces.
+     */
+    measure(options) {
+        const frames = this._drawnFrames(options);
+        const widths = frames.map((frame) => cellLen(frame));
+        const frameWidth = Math.max(...widths);
+        const { minimum, maximum } = this._line(frames[widths.indexOf(frameWidth)], options).measure(options);
+        return { minimum: Math.max(minimum, Math.min(frameWidth, maximum)), maximum };
+    }
+}

package/dist/renderables/status.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Status — displays a spinner animation with a status message.
+ *
+ * Its renderable is a `Spinner` whose label is the message, as Rich's is, so
+ * the message is drawn the way the spinner draws its label: a string is markup
+ * under the console that draws it.
+ */
+import type { Style } from "../core/style.js";
+import type { RichText } from "../core/text.js";
+import { Console } from "../core/console.js";
+export interface StatusOptions {
+    spinner?: string;
+    speed?: number;
+    /** The spinner's frame style; the message styles itself with its markup. */
+    spinnerStyle?: string | Style;
+    console?: Console;
+}
+export declare class Status {
+    private _live;
+    private _spinner;
+    private _console;
+    constructor(message: string | RichText, options?: StatusOptions);
+    get console(): Console;
+    get message(): string | RichText;
+    set message(value: string | RichText);
+    start(): void;
+    stop(): void;
+    update(message: string | RichText): void;
+}

package/dist/renderables/status.js

@@ -0,0 +1,46 @@
+/**
+ * Status — displays a spinner animation with a status message.
+ *
+ * Its renderable is a `Spinner` whose label is the message, as Rich's is, so
+ * the message is drawn the way the spinner draws its label: a string is markup
+ * under the console that draws it.
+ */
+import { Console } from "../core/console.js";
+import { Spinner } from "./spinner.js";
+import { Live } from "./live.js";
+export class Status {
+    _live;
+    _spinner;
+    _console;
+    constructor(message, options) {
+        this._console = options?.console ?? new Console();
+        this._spinner = new Spinner(options?.spinner ?? "dots", message, {
+            speed: options?.speed,
+            style: options?.spinnerStyle ?? "status.spinner",
+        });
+        this._live = new Live(this._spinner, {
+            console: this._console,
+            transient: true,
+            refreshPerSecond: 12.5,
+        });
+    }
+    get console() {
+        return this._console;
+    }
+    get message() {
+        return this._spinner.text;
+    }
+    set message(value) {
+        this._spinner.text = value;
+    }
+    start() {
+        this._live.start();
+    }
+    stop() {
+        this._live.stop();
+    }
+    update(message) {
+        this._spinner.text = message;
+        this._live.update(this._spinner, { refresh: true });
+    }
+}

package/dist/renderables/syntax.d.ts

@@ -0,0 +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 Measurable, type Renderable, type RenderOptions } from "../core/protocol.js";
+export interface SyntaxOptions {
+    lineNumbers?: boolean;
+    startLine?: number;
+    lineRange?: [number, number];
+    highlightLines?: Set<number>;
+    wordWrap?: boolean;
+    tabSize?: 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.
+ */
+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: SyntaxLanguage;
+    readonly lineNumbers: boolean;
+    readonly startLine: number;
+    readonly lineRange: [number, number] | undefined;
+    readonly highlightLines: Set<number>;
+    readonly wordWrap: boolean;
+    readonly tabSize: number;
+    /** 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;
+    };
+}
+export {};

package/dist/renderables/syntax.js

@@ -0,0 +1,166 @@
+/**
+ * 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, expandTabs, parseTabSize } from "../core/cells.js";
+import { Segment } from "../core/segment.js";
+import { RichText } from "../core/text.js";
+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;
+    language;
+    lineNumbers;
+    startLine;
+    lineRange;
+    highlightLines;
+    wordWrap;
+    tabSize;
+    /** 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;
+        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;
+        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 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);
+    }
+    *_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 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",
+        };
+        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();
+            }
+        }
+    }
+    /** 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 };
+    }
+}