@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/render.js

@@ -0,0 +1,105 @@
+/**
+ * `renderToString` — stateless one-shot emission of a `Renderable` to a string
+ * of ANSI-encoded text. Pure function: same inputs produce byte-identical
+ * output. Does not write to `process.stdout` and does not require a `Console`
+ * instance.
+ *
+ * Note on `colorSystem: "auto"`: the `"auto"` spec resolves via
+ * `detectColorSystem`, which reads `process.env` and `process.stdout?.isTTY`
+ * by default. Callers that want a fully deterministic render must either pass
+ * an explicit `ColorDepth` enum / non-`"auto"` spec, or supply `env` and
+ * `isTTY` in the options so detection does not consult ambient process state.
+ *
+ * [LAW:single-enforcer] The Segment-to-ANSI conversion lives in `segmentToString`
+ * and is the single way a segment becomes wire bytes. `segmentsToString` is
+ * that encoding joined, and `Console._writeSegments`, `Painter` (every `Live`
+ * and `App` frame) and `renderToString` all go through it, so terminal output,
+ * live and app frames and string export agree by construction.
+ *
+ * [LAW:one-source-of-truth] What the encoding needs from where it writes
+ * arrives as one `Destination` value. Each caller resolves its destination
+ * once — spec, detection, and its own overrides — and hands it through whole,
+ * so a depth is never paired with a link setting taken from somewhere else.
+ *
+ * Every segment is written alone, exactly as Python Rich 9d8f9a3 writes it
+ * (`Console._render_buffer` calls `Style.render` per segment): its SGR codes
+ * open, its text, a reset, and an OSC 8 pair around all three when it carries
+ * a link. Two adjacent segments with equal codes are two runs, not one. That
+ * costs a reset and a reopen the terminal draws identically, and it is what
+ * lets a fixture generated from the reference hold any sequence of segments,
+ * rather than only those in which no two neighbours happen to share a style
+ * (rich-render-g5g8). The price of that is that where a renderable cuts its
+ * segments is now in the bytes, so a renderable pinned against the reference
+ * has to cut where the reference cuts, as `Box`'s rules and `Table`'s blank
+ * cell lines do. A link split across segments still hovers as one link,
+ * because every pair it becomes carries the id `osc8Open` derives from the URL.
+ *
+ * Colour and hyperlinks are two facts about the destination:
+ * `colorSystem === null` empties every segment's SGR codes, and
+ * `hyperlinks === false` drops every segment's link. A colour depth never
+ * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
+ * follows OSC 8. This is where the port departs from the reference, whose
+ * `Style.render` returns bare text for a null colour system.
+ */
+import { ColorDepth, resolveDestination } from "./color.js";
+import { OSC8_CLOSE, osc8Open } from "./osc8.js";
+const DEFAULT_WIDTH = 80;
+/**
+ * Encodes one segment as ANSI bytes for `destination`: the reference's
+ * `Style.render` for that segment, and nothing for a control segment.
+ */
+export function segmentToString(segment, destination) {
+    if (segment.isControl)
+        return "";
+    const { text, style } = segment;
+    // As the reference's `if not text` and `if style:` — no pair around nothing.
+    if (text.length === 0 || style === undefined)
+        return text;
+    // [LAW:one-type-per-behavior] Colour depth governs SGR only; hyperlinks are
+    // their own fact. Coupling them let a colour setting delete every control.
+    const codes = destination.colorSystem === null ? "" : style.toSgrCodes(destination.colorSystem);
+    const styled = codes.length > 0 ? `\x1b[${codes}m${text}\x1b[0m` : text;
+    const link = destination.hyperlinks ? style.link : undefined;
+    return link === undefined ? styled : `${osc8Open(link)}${styled}${OSC8_CLOSE}`;
+}
+/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
+export function segmentsToString(segments, destination) {
+    const parts = [];
+    for (const segment of segments)
+        parts.push(segmentToString(segment, destination));
+    return parts.join("");
+}
+export function renderToString(renderable, options) {
+    const width = options?.width ?? DEFAULT_WIDTH;
+    // [LAW:dataflow-not-control-flow] An absent spec is truecolor; an explicit
+    // `null` stays null (`??` would collapse it).
+    // [LAW:single-enforcer] Specs resolve through `resolveDestination`.
+    const detectOptions = {};
+    if (options?.env !== undefined)
+        detectOptions.env = options.env;
+    if (options?.isTTY !== undefined)
+        detectOptions.isTTY = options.isTTY;
+    const rawSpec = options?.colorSystem;
+    const resolved = resolveDestination(rawSpec === undefined ? ColorDepth.TRUECOLOR : rawSpec, detectOptions);
+    // [LAW:single-enforcer] This call's overrides are applied here, once, to
+    // make the one destination everything below is drawn for. `noColor` is a
+    // colour choice, so it overrides the depth and leaves hyperlinks to the
+    // destination; an explicit `hyperlinks` overrides what the destination takes.
+    const destination = {
+        colorSystem: options?.noColor ? null : resolved.colorSystem,
+        hyperlinks: options?.hyperlinks ?? resolved.hyperlinks,
+    };
+    const renderOptions = {
+        maxWidth: width,
+        isTerminal: false,
+        asciiOnly: options?.asciiOnly ?? false,
+        theme: options?.theme,
+        onStyleError: options?.onStyleError,
+        highlight: options?.highlight,
+        highlighter: options?.highlighter,
+        // [LAW:one-source-of-truth] The depth the segments below are encoded at,
+        // so a renderable measures what this very call will draw.
+        colorSystem: destination.colorSystem,
+    };
+    return segmentsToString(renderable.render(renderOptions), destination);
+}

package/dist/core/segment.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Segment — the atomic rendering unit. Every piece of styled terminal output
+ * is represented as a Segment: (text, style?, control?).
+ */
+import { type CellCol } from "./cells.js";
+import { Style } from "./style.js";
+import { type Anchor } from "./anchor.js";
+export declare enum ControlType {
+    BELL = "bell",
+    CARRIAGE_RETURN = "carriage_return",
+    HOME = "home",
+    CLEAR = "clear",
+    SHOW_CURSOR = "show_cursor",
+    HIDE_CURSOR = "hide_cursor",
+    ENABLE_ALT_SCREEN = "enable_alt_screen",
+    DISABLE_ALT_SCREEN = "disable_alt_screen",
+    CURSOR_UP = "cursor_up",
+    CURSOR_DOWN = "cursor_down",
+    CURSOR_FORWARD = "cursor_forward",
+    CURSOR_BACKWARD = "cursor_backward",
+    CURSOR_MOVE_TO_COLUMN = "cursor_move_to_column",
+    CURSOR_MOVE_TO = "cursor_move_to",
+    ERASE_IN_LINE = "erase_in_line",
+    SET_WINDOW_TITLE = "set_window_title"
+}
+export type ControlCode = [ControlType, ...unknown[]];
+export declare class Segment {
+    readonly text: string;
+    readonly style: Style | undefined;
+    readonly control: ControlCode[] | undefined;
+    constructor(text: string, style?: Style, control?: ControlCode[]);
+    get cellLength(): number;
+    get hasText(): boolean;
+    get isControl(): boolean;
+    /**
+     * Splits at a cell position. Returns [left, right]: the first `position`
+     * cells and the rest, so the two halves are exactly as wide as this one —
+     * `cutCells` blanks a wide glyph the cut goes through rather than keep it
+     * whole on a side it would widen by a cell.
+     *
+     * [LAW:single-enforcer] The right half starts `position` cells further into
+     * whatever drew it, and its anchor says so; see `./anchor.ts`.
+     */
+    splitCells(position: CellCol): [Segment, Segment];
+    private static _line;
+    static line(): Segment;
+    /**
+     * `lines`, as drawn by `owner`: every segment stamped with the row and
+     * column of its first cell, wrapping whatever anchor it already carried.
+     * Control segments occupy no cell and are left as they are. `firstRow` is
+     * the owner's row that `lines[0]` is, for output that arrives in pieces.
+     */
+    static anchorLines(lines: Segment[][], owner: object, firstRow?: number): Segment[][];
+    /**
+     * The anchor of the cell at column `x` of row `y` in a composed frame, or
+     * `undefined` when that cell was drawn by no owner or lies outside the frame.
+     */
+    static anchorAt(lines: readonly (readonly Segment[])[], x: number, y: number): Anchor | undefined;
+    /**
+     * Yields segments with combined styles.
+     */
+    static applyStyle(segments: Iterable<Segment>, style?: Style, postStyle?: Style): Iterable<Segment>;
+    /**
+     * Filters segments by control status.
+     */
+    static filterControl(segments: Iterable<Segment>, isControl: boolean): Iterable<Segment>;
+    /**
+     * Splits segments at newlines. Yields arrays of segments per line.
+     */
+    static splitLines(segments: Iterable<Segment>): Segment[][];
+    /**
+     * Adjusts a line of segments to exactly `width` cells.
+     */
+    static adjustLineLength(line: Segment[], width: number, style?: Style, pad?: boolean): Segment[];
+    /**
+     * Crops a renderable's output so no line exceeds `width`, leaving short lines
+     * alone and the line structure exactly as it arrived.
+     *
+     * [LAW:single-enforcer] `adjustLineLength` is where a width is enforced, but
+     * it takes one line and a container holding arbitrary content has a stream of
+     * them. Without this step the container has to trust content to honour the
+     * offer, and content that ignores it overflows the region — which is how a
+     * `Layout` leaf and a `Tree` label came to emit forty cells into a one-cell
+     * offer while `Panel` and `Padding`, which split and adjust, did not.
+     *
+     * One segment in, one segment out, shortening text and nothing else — so the
+     * line structure that arrives is the line structure that leaves. Two earlier
+     * shapes of this both decided how many lines there were and both were wrong:
+     * built on `splitLines`, which cannot tell `"abc"` from `"abc\n"`, it invented
+     * a trailing newline and dropped the row of an empty `Tree` label entirely,
+     * running its guides into the next row; rebuilt to accumulate lines, it
+     * dropped the zero-width-but-present line `RichText` emits at an offer of 0,
+     * and a row split rendered nothing at all. A crop shortens; it does not count.
+     *
+     * A wide glyph the edge cuts through leaves a space in the cell it would have
+     * half-filled, so a cropped line still reaches the edge — the reference's
+     * `set_cell_size`, which `splitText` already is. An unbounded `width` crops
+     * nothing, and a segment the crop did not change leaves as itself.
+     */
+    static cropLines(segments: Iterable<Segment>, width: number): Iterable<Segment>;
+    /**
+     * Splits a renderable's output into rows, each exactly `width` cells:
+     * short rows padded with spaces, long ones cut.
+     */
+    static splitAndCropLines(segments: Iterable<Segment>, width: number): Segment[][];
+    /**
+     * Returns total cell width of a line. Ignores control segments.
+     */
+    static getLineLength(line: Segment[]): number;
+    /**
+     * Returns [width, height] of a set of lines.
+     */
+    static getShape(lines: Segment[][]): [number, number];
+    /**
+     * Composes cells side by side into full lines. Each cell contributes its
+     * own lines cropped/padded to its declared width; a cell shorter than the
+     * tallest is filled with blank space so the grid stays aligned. Adjacent
+     * cells are separated by a gutter of spaces, and each merged row ends with a
+     * line break. This is the single side-by-side merge used by every horizontal
+     * layout (Columns grid rows, Layout row splits).
+     */
+    static mergeHorizontal(cells: readonly {
+        readonly lines: Segment[][];
+        readonly width: number;
+    }[], gutter?: number): Iterable<Segment>;
+    /**
+     * Merges contiguous segments with the same style.
+     */
+    static simplify(segments: Iterable<Segment>): Iterable<Segment>;
+    /**
+     * Yields segments with links removed.
+     */
+    static stripLinks(segments: Iterable<Segment>): Iterable<Segment>;
+    /**
+     * Yields segments with all styles removed.
+     */
+    static stripStyles(segments: Iterable<Segment>): Iterable<Segment>;
+    /**
+     * Yields segments with colors removed but attributes preserved.
+     */
+    static removeColor(segments: Iterable<Segment>): Iterable<Segment>;
+    /**
+     * Divides segments at cell positions. Yields arrays of segments for each section.
+     */
+    static divide(segments: Segment[], cuts: number[]): Segment[][];
+    /**
+     * Pads below to fill height.
+     */
+    static alignTop(lines: Segment[][], width: number, height: number, style: Style): Segment[][];
+    /**
+     * Pads above to fill height. Content at bottom.
+     */
+    static alignBottom(lines: Segment[][], width: number, height: number, style: Style): Segment[][];
+    /**
+     * Pads above and below. Content in middle.
+     */
+    static alignMiddle(lines: Segment[][], width: number, height: number, style: Style): Segment[][];
+    /**
+     * Forces lines to exactly width x height.
+     */
+    static setShape(lines: Segment[][], width: number, height: number, style?: Style): Segment[][];
+}