@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/renderables/layout.js

@@ -0,0 +1,223 @@
+/**
+ * Layout — divides the screen into rectangular regions.
+ */
+import { Segment } from "../core/segment.js";
+import { embed } from "./embed.js";
+import { fitHeight, regionRows, stackedHeight, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+import { Measurement } from "../core/measure.js";
+import { cellCount } from "../core/cells.js";
+import { ratioBudget, ratioResolve, shareWeight } from "./ratio.js";
+/**
+ * A pane rendered into a region of `rows` and held to exactly that many lines,
+ * or — with `rows` undefined — rendered under the layout's own budget, as a
+ * ceiling, at its natural height.
+ *
+ * [LAW:single-enforcer] The region's setter shapes it (`fitHeight`). Forwarded
+ * unshaped, a pane whose content ran short pulled every pane below it up, and
+ * one that ran long pushed them down.
+ */
+function paneLines(pane, options, rows) {
+    const height = rows === undefined ? stackedHeight(options.height) : { rows, exact: true };
+    return fitHeight(Segment.splitLines(pane.render({ ...options, height })), height);
+}
+export class Layout {
+    name;
+    visible;
+    _ratio;
+    _size;
+    _minimumSize;
+    _renderable;
+    _children;
+    _splitDirection;
+    constructor(renderable, options) {
+        if (renderable !== undefined) {
+            this._renderable = embed(renderable);
+        }
+        this.name = options?.name;
+        this.ratio = options?.ratio ?? 1;
+        this.size = options?.size;
+        this.minimumSize = options?.minimumSize ?? 1;
+        this.visible = options?.visible !== false;
+        this._children = [];
+        this._splitDirection = undefined;
+    }
+    /**
+     * The three declared numbers, parsed on assignment rather than at the
+     * constructor. All three are public and a caller reaches them long after
+     * construction — `layout.getByName("pane")!.ratio = -1` walked straight past a
+     * constructor-only parse and put a negative weight back into the division that
+     * `ratioResolve` and `ratioBudget` are written to trust.
+     *
+     * [LAW:parse-dont-validate] The setter is the border, so the guarantee holds
+     * for the object's whole lifetime and nothing downstream re-checks. `size` and
+     * `minimumSize` are cell counts; `ratio` is a share weight and keeps its
+     * fractions. Absence is preserved rather than parsed: an undefined `size`
+     * selects a flex pane, and `cellCount` would read it as a declared zero.
+     */
+    get ratio() {
+        return this._ratio;
+    }
+    set ratio(value) {
+        this._ratio = shareWeight(value);
+    }
+    get size() {
+        return this._size;
+    }
+    set size(value) {
+        this._size = value === undefined ? undefined : cellCount(value);
+    }
+    get minimumSize() {
+        return this._minimumSize;
+    }
+    set minimumSize(value) {
+        this._minimumSize = cellCount(value);
+    }
+    get children() {
+        return this._children;
+    }
+    /**
+     * Whether this layout draws `_renderable` or its children.
+     *
+     * [LAW:one-source-of-truth] `render` and `_naturalWidth` must answer this the
+     * same way. Asked separately they did not: `_naturalWidth` read it off the
+     * *visible* children, so a layout holding content and a single hidden child
+     * reported that content's width while `render` emitted nothing at all, and a
+     * fit-mode `Panel` framed twelve cells of air.
+     */
+    get _isLeaf() {
+        return this._children.length === 0;
+    }
+    splitColumn(...layouts) {
+        this._children = layouts;
+        this._splitDirection = "column";
+    }
+    splitRow(...layouts) {
+        this._children = layouts;
+        this._splitDirection = "row";
+    }
+    update(renderable) {
+        this._renderable = embed(renderable);
+    }
+    getByName(name) {
+        if (this.name === name)
+            return this;
+        for (const child of this._children) {
+            const found = child.getByName(name);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    *render(rawOptions) {
+        if (!this.visible)
+            return;
+        // Parsed once at the top of the layout rather than at the row split below,
+        // because a column split forwards the width to its children untouched and
+        // would otherwise hand each of them the caller's raw number.
+        const options = withBoundedWidth(rawOptions, this);
+        if (this._isLeaf) {
+            // Shaped to its region, as Rich's `render_lines` shapes a pane: every
+            // line cropped and padded to the width, and held to the region's rows.
+            // The leaf sets its content's region, so it shapes what comes back, as
+            // `paneLines` shapes a pane for the split that set the pane's.
+            // Cropped rather than forwarded because content is free to ignore its
+            // offer, and a pane wider than its region is the one thing a layout may
+            // never emit — in a row split it overwrites the pane beside it. Held to
+            // the rows because content keeps its own `end`: `RichText("status:
+            // ok\n")` is two lines, and a one-row region cuts the second. Every line
+            // ended, as the split paths below end theirs: a leaf stacked in a
+            // `Group` is still a region of lines.
+            if (this._renderable) {
+                const lines = fitHeight(Segment.splitLines(this._renderable.render(options)), options.height);
+                for (const line of lines) {
+                    yield* Segment.adjustLineLength(line, options.maxWidth);
+                    yield Segment.line();
+                }
+            }
+            return;
+        }
+        const visibleChildren = this._children.filter((c) => c.visible);
+        if (visibleChildren.length === 0)
+            return;
+        if (this._splitDirection === "row") {
+            yield* this._renderRow(visibleChildren, options);
+        }
+        else {
+            yield* this._renderColumn(visibleChildren, options);
+        }
+    }
+    *_renderColumn(children, options) {
+        // Each pane gets full width and its share of the region. With no region —
+        // a ceiling, or no budget at all — a pane's share is its declared `size`,
+        // and a pane without one takes its content's height.
+        const region = regionRows(options.height);
+        const shares = region === undefined
+            ? children.map((child) => child.size)
+            : ratioResolve(region, children);
+        for (let i = 0; i < children.length; i++) {
+            for (const line of paneLines(children[i], options, shares[i])) {
+                yield* line;
+                yield Segment.line();
+            }
+        }
+    }
+    *_renderRow(children, options) {
+        // Horizontal side-by-side: divide the requested width once, then merge
+        // child lines. The budget arrives parsed from `render` — unparsed, a NaN
+        // width made every share NaN and the merge threw `Invalid array length`.
+        // Every pane stands in the whole region, and with none the merge pads the
+        // row to its tallest pane.
+        const widths = ratioResolve(options.maxWidth, children);
+        const region = regionRows(options.height);
+        const cells = children.map((child, i) => ({
+            width: widths[i],
+            lines: paneLines(child, { ...options, maxWidth: widths[i] }, region),
+        }));
+        yield* Segment.mergeHorizontal(cells);
+    }
+    /**
+     * The width this layout would take if nothing constrained it: its content's
+     * for a leaf, its children's laid out the way the split lays them out.
+     *
+     * A `size` counts only across a row, which is the one direction in which it
+     * is a width — down a column the same field is a height, and reading it as a
+     * width there would report a two-line pane as two cells wide.
+     */
+    _naturalWidth(options) {
+        if (!this.visible)
+            return 0;
+        if (this._isLeaf) {
+            if (this._renderable === undefined)
+                return 0;
+            return Measurement.get(options, this._renderable).maximum;
+        }
+        const visible = this._children.filter((c) => c.visible);
+        if (visible.length === 0)
+            return 0;
+        const widths = visible.map((c) => c._naturalWidth(options));
+        if (this._splitDirection === "row")
+            return ratioBudget(visible, widths);
+        // Accumulated, not spread: a column split holds as many children as a caller
+        // made, and `Math.max(...widths)` passes one argument per child, so a
+        // generated dashboard deep enough overruns the engine's argument limit and
+        // throws out of `measure()`.
+        let widest = 0;
+        for (const width of widths)
+            widest = Math.max(widest, width);
+        return widest;
+    }
+    measure(rawOptions) {
+        // `minimumSize` is what this layout asks for and the ceiling is what it was
+        // offered; the ceiling wins. Unclamped, a layout measured into no width
+        // reported the range 1..0 — a floor above its own ceiling, which the parent
+        // that asked cannot divide.
+        //
+        // The ceiling alone was not the answer either: a layout that reported the
+        // whole offer as its maximum told every parent it wanted all of it, so
+        // `Panel` in fit mode drew its frame at the full console width around a
+        // layout of two short panes, and an unbounded offer came back unbounded.
+        const parsed = withCellWidth(rawOptions);
+        const maximum = Math.min(this._naturalWidth(parsed), parsed.maxWidth);
+        return { minimum: Math.min(this.minimumSize, maximum), maximum };
+    }
+}

package/dist/renderables/live.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Live — animates a portion of the terminal by continuously re-rendering.
+ *
+ * Two modes, each painting every frame over the last in place
+ * (`core/paint`):
+ * - **Inline** (default): the frame starts at the cursor's line and keeps its
+ *   own height. Good for spinners/progress bars below other output.
+ * - **Alt-screen** (`altScreen: true`): enters the alternate screen buffer
+ *   on start and restores the original buffer on stop. The screen is the
+ *   frame's region, so a `Layout` fills it. Good for full-screen TUI apps.
+ *
+ * On a console that is not interactive — a file, a pipe, a CI log — neither
+ * mode paints: what is printed goes out plain, and the frame is written once,
+ * when the display stops, as Rich's `Live` does.
+ *
+ * Live is not built on `App`, though both take a terminal, paint a frame over
+ * the last and hand the terminal back. That much is the `Painter`'s, and both
+ * hold one. The rest differs in who owns what. An `App` owns its terminal: it
+ * starts and stops a `TerminalHost`, sets raw mode, reads keys and pointers,
+ * suspends, and builds its own `Console` from the host. A `Live` owns none of
+ * that. It draws into a `Console` its caller owns and goes on writing
+ * through — a sink that may be a file, whose every other write has to step
+ * around the frame (`Console.claimLiveRegion`) — and it reads no input. An
+ * `App` over that console would need a host that cannot start, stop, read or
+ * suspend, and a second owner of the console's writes.
+ */
+import { type Clock } from "../core/clock.js";
+import { Console } from "../core/console.js";
+import { type Renderable } from "../core/protocol.js";
+export interface LiveOptions {
+    /** Frames a second while auto-refreshing: positive and finite, fractional included. */
+    refreshPerSecond?: number;
+    /** What the auto-refresh ticks on. The platform's, unless given. */
+    clock?: Clock;
+    autoRefresh?: boolean;
+    transient?: boolean;
+    console?: Console;
+    verticalOverflow?: "crop" | "ellipsis" | "visible";
+    /** When true, Live enters the alternate screen buffer on start() and
+     *  restores the original on stop(). The screen is the frame's region, so
+     *  a full-screen layout fills it. */
+    altScreen?: boolean;
+}
+export declare class Live {
+    private _renderable;
+    private _console;
+    private readonly _rate;
+    private readonly _clock;
+    private _autoRefresh;
+    private _transient;
+    private _verticalOverflow;
+    private readonly _painter;
+    private _stopTicking;
+    private _held;
+    constructor(renderable?: Renderable, options?: LiveOptions);
+    /**
+     * The console to print through while this Live runs: what it prints lands
+     * above an inline frame. The alternate screen is all frame, and paints over it.
+     */
+    get console(): Console;
+    get renderable(): Renderable | undefined;
+    start(): void;
+    stop(): void;
+    update(renderable?: Renderable, options?: {
+        refresh?: boolean;
+    }): void;
+    refresh(): void;
+    private _frame;
+    private _stepAround;
+    private _paint;
+    private _screen;
+    private _overflow;
+    private _release;
+}

package/dist/renderables/live.js

@@ -0,0 +1,188 @@
+/**
+ * Live — animates a portion of the terminal by continuously re-rendering.
+ *
+ * Two modes, each painting every frame over the last in place
+ * (`core/paint`):
+ * - **Inline** (default): the frame starts at the cursor's line and keeps its
+ *   own height. Good for spinners/progress bars below other output.
+ * - **Alt-screen** (`altScreen: true`): enters the alternate screen buffer
+ *   on start and restores the original buffer on stop. The screen is the
+ *   frame's region, so a `Layout` fills it. Good for full-screen TUI apps.
+ *
+ * On a console that is not interactive — a file, a pipe, a CI log — neither
+ * mode paints: what is printed goes out plain, and the frame is written once,
+ * when the display stops, as Rich's `Live` does.
+ *
+ * Live is not built on `App`, though both take a terminal, paint a frame over
+ * the last and hand the terminal back. That much is the `Painter`'s, and both
+ * hold one. The rest differs in who owns what. An `App` owns its terminal: it
+ * starts and stops a `TerminalHost`, sets raw mode, reads keys and pointers,
+ * suspends, and builds its own `Console` from the host. A `Live` owns none of
+ * that. It draws into a `Console` its caller owns and goes on writing
+ * through — a sink that may be a file, whose every other write has to step
+ * around the frame (`Console.claimLiveRegion`) — and it reads no input. An
+ * `App` over that console would need a host that cannot start, stop, read or
+ * suspend, and a second owner of the console's writes.
+ */
+import { frameRate, systemClock } from "../core/clock.js";
+import { Console } from "../core/console.js";
+import { Segment } from "../core/segment.js";
+import { FinalFramePainter, SurfacePainter } from "../core/paint.js";
+import { fitHeight } from "../core/protocol.js";
+export class Live {
+    _renderable;
+    _console;
+    _rate;
+    _clock;
+    _autoRefresh;
+    _transient;
+    _verticalOverflow;
+    _painter;
+    _stopTicking;
+    // [LAW:one-source-of-truth] The console's live region, held from `start()`
+    // to the hand-back — which is what "started" means, so there is no separate
+    // flag to disagree with it.
+    _held;
+    constructor(renderable, options) {
+        this._renderable = renderable;
+        this._console = options?.console ?? new Console();
+        // [LAW:parse-dont-validate] Parsed whether or not it auto-refreshes, so a
+        // rate that could never tick is refused where it is given.
+        this._rate = frameRate(options?.refreshPerSecond ?? 4);
+        this._clock = options?.clock ?? systemClock();
+        this._autoRefresh = options?.autoRefresh !== false;
+        this._transient = options?.transient ?? false;
+        this._verticalOverflow = options?.verticalOverflow ?? "ellipsis";
+        // [LAW:dataflow-not-control-flow] What the console is decides which
+        // painter Live holds; every frame then takes the same path through it.
+        // The final frame is a print, as in Rich, so a recording or a capture
+        // holds it with everything else the console wrote.
+        this._painter = this._console.isInteractive
+            ? new SurfacePainter(options?.altScreen ? "alternate" : "inline", (bytes) => void this._console.file.write(bytes))
+            : new FinalFramePainter((frame) => this._console.print(linesOf(frame)));
+        this._held = null;
+    }
+    /**
+     * The console to print through while this Live runs: what it prints lands
+     * above an inline frame. The alternate screen is all frame, and paints over it.
+     */
+    get console() {
+        return this._console;
+    }
+    get renderable() {
+        return this._renderable;
+    }
+    start() {
+        if (this._held !== null)
+            return;
+        // Claimed before a byte is written, so a console another Live is running
+        // on refuses this one with the terminal untouched.
+        const held = this._console.claimLiveRegion({ around: (text) => this._stepAround(text) });
+        this._held = held;
+        this._painter.take();
+        if (this._autoRefresh) {
+            // No caller is on the stack to run `stop()` for a frame that throws
+            // here, and in Node the throw ends the process — so the terminal is
+            // handed back first, and the error then goes on to wherever an uncaught
+            // one goes.
+            this._stopTicking = this._clock.every(this._rate, () => {
+                try {
+                    this.refresh();
+                }
+                catch (error) {
+                    this._release(held);
+                    throw error;
+                }
+            });
+        }
+    }
+    stop() {
+        const held = this._held;
+        if (held === null)
+            return;
+        // [LAW:no-silent-failure] A final frame that throws still propagates, and
+        // the terminal is handed back on the way out.
+        try {
+            if (this._transient) {
+                this._paint(() => []);
+            }
+            else {
+                this.refresh();
+            }
+        }
+        finally {
+            this._release(held);
+        }
+    }
+    update(renderable, options) {
+        if (renderable !== undefined) {
+            this._renderable = renderable;
+        }
+        if (options?.refresh) {
+            this.refresh();
+        }
+    }
+    refresh() {
+        // A frame is drawn only while this Live holds the terminal, as in Rich:
+        // before `start()` or after the hand-back it would land on a screen that
+        // belongs to someone else — the main buffer, under the user's own output.
+        if (this._held === null)
+            return;
+        this._paint(() => this._frame());
+    }
+    _frame() {
+        if (!this._renderable)
+            return [];
+        // [LAW:dataflow-not-control-flow] Both modes render under the terminal's
+        // rows and differ only in what those rows are: the alternate screen is a
+        // region the frame stands in, and an inline frame keeps its natural height
+        // under them as a ceiling. Live set the budget, so Live shapes what comes
+        // back — its overflow policy, then `fitHeight`, which pads only a region.
+        const options = this._console.options;
+        const height = this._painter.height(options.height.rows);
+        const lines = Segment.splitLines(this._renderable.render({ ...options, height }));
+        return fitHeight(this._overflow(lines, height.rows), height);
+    }
+    // What the console writes goes where the frame was, and the frame is painted
+    // again under it, as Rich's render hook does — in the bytes the console
+    // writes, so a render that throws writes nothing.
+    _stepAround(text) {
+        return this._painter.around(text, () => this._frame(), this._screen(), this._console.destination);
+    }
+    // [LAW:effects-at-boundaries] The frame is fully rendered before a byte
+    // reaches the terminal, and whatever takes the last frame away goes out in
+    // the same write as the new one — so a render that throws leaves the last
+    // good frame showing.
+    _paint(frame) {
+        this._painter.paint(frame, this._screen(), this._console.destination);
+    }
+    _screen() {
+        const { height, maxWidth } = this._console.options;
+        return { rows: height.rows, cols: maxWidth };
+    }
+    // Lines past `rows`: dropped, with the last kept row replaced by an ellipsis,
+    // or left for the terminal to scroll.
+    _overflow(lines, rows) {
+        if (this._verticalOverflow === "visible" || lines.length <= rows)
+            return lines;
+        const kept = lines.slice(0, rows);
+        if (this._verticalOverflow === "ellipsis" && kept.length > 0) {
+            kept[kept.length - 1] = [new Segment("...")];
+        }
+        return kept;
+    }
+    // [LAW:single-enforcer] The one way the terminal is handed back — the timer
+    // stopped, the cursor shown, the alternate screen left — whether `stop()`
+    // ran or a frame threw with no caller to run it.
+    _release(held) {
+        held();
+        this._held = null;
+        this._stopTicking?.();
+        this._stopTicking = undefined;
+        this._painter.handBack();
+    }
+}
+// A drawn frame as a renderable, each row a line, for the console to print.
+function linesOf(frame) {
+    return { render: () => frame.flatMap((row) => [...row, Segment.line()]) };
+}

package/dist/renderables/markdown.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Markdown — renders Markdown content to the terminal.
+ * Uses built-in parsing (no external dependency).
+ *
+ * Block structure is read as CommonMark reads it: a blockquote and a list
+ * item are both containers, their lines tokenized as Markdown of their own
+ * once the container's marker or indentation is cut off, and drawn beside a
+ * gutter — the quote's bar, the item's marker then its hang. Where CommonMark
+ * leaves the drawing open, Rich's is followed.
+ */
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export interface MarkdownOptions {
+    /** The style of `inline code`: a theme name or a style definition. Default `markdown.code`. */
+    inlineCodeStyle?: string | Style;
+    /**
+     * Whether a link's text is the link. `false` writes the URL after the text
+     * in parentheses, for a reader who cannot click it. Default `true`.
+     */
+    hyperlinks?: boolean;
+    /** How body text — paragraphs, list items, quotes — is placed in its width. Default `"left"`; headings keep their own. */
+    justify?: Justify;
+}
+type Justify = NonNullable<RenderOptions["justify"]>;
+export declare class Markdown implements Renderable, Measurable {
+    readonly markdown: string;
+    readonly inlineCodeStyle: string | Style;
+    readonly hyperlinks: boolean;
+    readonly justify: Justify;
+    constructor(markdown: string, options?: MarkdownOptions);
+    render(rawOptions: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}
+export {};