@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/protocol.d.ts

@@ -4,7 +4,8 @@
  */
 import type { Segment } from "./segment.js";
 import { type Style, type StyleSyntaxError, type Theme } from "./style.js";
-import type { ColorDepth } from "./color.js";
+import { ColorDepth } from "./color.js";
+import type { Highlighter } from "./highlighter.js";
 /**
  * What becomes of a line still wider than its width once wrapping is done.
  * `"fold"` breaks it across lines, `"crop"` cuts it at the edge, `"ellipsis"`
@@ -41,8 +42,30 @@ export interface RenderOptions {
     justify?: "left" | "center" | "right" | "full";
     overflow?: OverflowMethod;
     noWrap?: boolean;
-    highlight?: unknown;
-    markup?: unknown;
+    /**
+     * Whether a string handed to a renderable — a cell, a label, a pane — is
+     * read as markup when it is drawn. Absent, it is, as a `Console`'s is unless
+     * told otherwise. A `Console` passes its own setting, and `print`'s.
+     */
+    markup?: boolean;
+    /**
+     * Whether a string handed to a renderable is highlighted when it is drawn,
+     * by `highlighter`. Absent, it is, as a `Console`'s is unless told
+     * otherwise. A `Console` passes its own setting, and `print`'s; a renderable
+     * that draws its strings plain, as Rich's `Panel`, `Table` and `Tree` do by
+     * default, sets it false for what it renders — Rich's
+     * `options.update(highlight=False)` — and a table column's `highlight` sets
+     * it either way. `activeHighlighter` is the one reading of the pair.
+     */
+    highlight?: boolean;
+    /**
+     * What highlights a string handed to a renderable, while `highlight` says
+     * to. A `Console` passes its highlighter whether or not its own `highlight`
+     * is on, as Rich's `render_str` reaches `console.highlighter`, so content
+     * that turns highlighting on finds the console's highlighter there. Absent,
+     * nothing highlights.
+     */
+    highlighter?: Highlighter;
     /**
      * The depth the output will be encoded at, `null` when it carries no colour.
      * A renderable choosing between two ways of drawing something — the strip's
@@ -73,6 +96,8 @@ export interface RenderOptions {
      */
     onDraw?: (owner: object) => void;
 }
+/** Whether `text` is all ASCII — what an `asciiOnly` output can draw. */
+export declare const isAscii: (text: string) => boolean;
 /**
  * `chosen` as this output can draw it: `ascii` in its place when the output is
  * ASCII-only and `chosen` spends a glyph outside ASCII, otherwise `chosen`
@@ -177,6 +202,21 @@ export type StyleErrorHandler = (error: StyleSyntaxError, style: string) => void
  * theme })` changed nothing.
  */
 export declare function getStyle(options: RenderOptions, style: string | Style): Style;
+/**
+ * `style` as the depth the render is encoded at can draw it. A style that
+ * paints its own ground in fixed colours chose its ink and ground as a pair;
+ * at sixteen colours the writer rounds a fixed colour to an ANSI slot, which
+ * the terminal paints in its own theme's colour, and no pair of slots reads in
+ * every bundled theme. So where the depth would turn a fixed colour of the
+ * pair into a slot, the pair is dropped and the run is drawn on the
+ * terminal's own foreground and background, which its theme does make
+ * readable; its attributes still set it apart. A style whose colours are
+ * slots already (`white on blue`), or that paints no ground (`bold magenta`),
+ * was written for the terminal's own colours and is drawn as written. Rich
+ * draws a highlighted line number the same way below 256 colours
+ * (`Syntax._get_number_styles`).
+ */
+export declare function groundedStyle(options: RenderOptions, style: Style): Style;
 /**
  * The options a renderable should work from: the caller's, with `maxWidth`
  * parsed into an actual count of cells.

package/dist/core/protocol.js

@@ -4,9 +4,10 @@
  */
 import { cellCount } from "./cells.js";
 import { DEFAULT_THEME } from "./style.js";
-const ASCII_TEXT = /^[\x00-\x7F]*$/;
+/** Whether `text` is all ASCII — what an `asciiOnly` output can draw. */
+export const isAscii = (text) => /^[\x00-\x7F]*$/.test(text);
 export function drawable(options, chosen, ascii, glyphs = String) {
-    return options.asciiOnly === true && !ASCII_TEXT.test(glyphs(chosen)) ? ascii : chosen;
+    return options.asciiOnly === true && !isAscii(glyphs(chosen)) ? ascii : chosen;
 }
 /**
  * The budget a renderable hands the one child filling its space: its own, less
@@ -60,6 +61,26 @@ export function fitHeight(lines, height) {
 export function getStyle(options, style) {
     return (options.theme ?? DEFAULT_THEME).resolve(style);
 }
+/**
+ * `style` as the depth the render is encoded at can draw it. A style that
+ * paints its own ground in fixed colours chose its ink and ground as a pair;
+ * at sixteen colours the writer rounds a fixed colour to an ANSI slot, which
+ * the terminal paints in its own theme's colour, and no pair of slots reads in
+ * every bundled theme. So where the depth would turn a fixed colour of the
+ * pair into a slot, the pair is dropped and the run is drawn on the
+ * terminal's own foreground and background, which its theme does make
+ * readable; its attributes still set it apart. A style whose colours are
+ * slots already (`white on blue`), or that paints no ground (`bold magenta`),
+ * was written for the terminal's own colours and is drawn as written. Rich
+ * draws a highlighted line number the same way below 256 colours
+ * (`Syntax._get_number_styles`).
+ */
+export function groundedStyle(options, style) {
+    const drawn = style.drawnColors(options.colorSystem ?? undefined);
+    const lost = (written, shown) => written?.fixedValue !== undefined && shown?.fixedValue === undefined;
+    const pairLost = style.bgcolor !== undefined && (lost(style.color, drawn.color) || lost(style.bgcolor, drawn.bgcolor));
+    return pairLost ? style.withoutColor : style;
+}
 /**
  * The options a renderable should work from: the caller's, with `maxWidth`
  * parsed into an actual count of cells.

package/dist/core/render.d.ts

@@ -10,50 +10,57 @@
  * 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 `segmentsToString`
- * and is the single way segments become wire bytes. `Console._writeSegments`,
- * `Live.refresh`, `Screen`'s frame paint, `renderToString`, and
- * `segmentToString` all delegate here, so terminal output, live frames, widget
- * frames, string export, and single-segment encoding agree by construction.
+ * [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.
  *
- * [LAW:dataflow-not-control-flow] The same pipeline runs every render: collect
- * non-control non-empty pieces, partition by SGR-codes (SGR-runs), partition
- * each run by link (link-runs), emit one SGR open/close per run with link
- * open/close pairs sitting inside. Colour and hyperlinks are two facts about
- * the destination: `colorSystem === null` empties every piece's SGR-codes, and
- * `hyperlinks === false` empties every piece's link. A colour depth never
- * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
- * follows OSC 8.
+ * 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.
  *
- * [LAW:types-are-the-program] Adjacent same-style segments share an SGR wrap
- * because the SGR-codes string is the same group key for both — the
- * partitioning shape (data) encodes the byte structure; the emit walk is a
- * mechanical fold over it.
+ * 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 } from "./color.js";
-import type { Destination } from "./color.js";
+import type { ColorSystemName, Destination } from "./color.js";
+import type { Env } from "./env.js";
 import type { Segment } from "./segment.js";
 import type { Renderable, RenderOptions } from "./protocol.js";
-export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "onStyleError"> {
+export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "theme" | "onStyleError" | "highlight" | "highlighter"> {
     /** Cell width to render into. Default 80. */
     width?: number;
     /**
-     * Color encoding to emit. Accepts a string spec (`"auto"`, `"truecolor"`,
-     * `"256"`, `"ansi"`, `"none"`), a `ColorDepth` enum value, or `null` to
+     * Color encoding to emit. Accepts a `ColorSystemName` (`"auto"`,
+     * `"truecolor"`, `"256"`, `"ansi"`, `"none"`), a `ColorDepth` enum value, or `null` to
      * strip SGR colors/attributes. Hyperlinks are `hyperlinks`' concern. Default
      * truecolor.
      */
-    colorSystem?: string | ColorDepth | null;
+    colorSystem?: ColorSystemName | ColorDepth | null;
     /**
      * Environment to consult when `colorSystem` is `"auto"`. Defaults to
      * `process.env`. Pass an explicit value to keep rendering deterministic.
      */
-    env?: NodeJS.ProcessEnv;
+    env?: Env;
     /**
      * Whether output is going to a TTY when `colorSystem` is `"auto"`. Defaults
      * to `process.stdout?.isTTY`. Pass an explicit value to keep rendering
@@ -71,14 +78,10 @@ export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" |
     hyperlinks?: boolean;
 }
 /**
- * Encodes a single segment as ANSI bytes for `destination`. Equivalent to
- * `segmentsToString([segment], destination)` — same SGR / OSC 8 layout.
+ * Encodes one segment as ANSI bytes for `destination`: the reference's
+ * `Style.render` for that segment, and nothing for a control segment.
  */
 export declare function segmentToString(segment: Segment, destination: Destination): string;
-/**
- * Encodes a sequence of segments as ANSI bytes for `destination`, coalescing
- * adjacent same-SGR segments under a single SGR open/close pair, with OSC 8
- * link pairs nested inside per same-link sub-run.
- */
+/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
 export declare function segmentsToString(segments: Iterable<Segment>, destination: Destination): string;
 export declare function renderToString(renderable: Renderable, options?: RenderToStringOptions): string;

package/dist/core/render.js

@@ -10,106 +10,63 @@
  * 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 `segmentsToString`
- * and is the single way segments become wire bytes. `Console._writeSegments`,
- * `Live.refresh`, `Screen`'s frame paint, `renderToString`, and
- * `segmentToString` all delegate here, so terminal output, live frames, widget
- * frames, string export, and single-segment encoding agree by construction.
+ * [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.
  *
- * [LAW:dataflow-not-control-flow] The same pipeline runs every render: collect
- * non-control non-empty pieces, partition by SGR-codes (SGR-runs), partition
- * each run by link (link-runs), emit one SGR open/close per run with link
- * open/close pairs sitting inside. Colour and hyperlinks are two facts about
- * the destination: `colorSystem === null` empties every piece's SGR-codes, and
- * `hyperlinks === false` empties every piece's link. A colour depth never
- * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
- * follows OSC 8.
+ * 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.
  *
- * [LAW:types-are-the-program] Adjacent same-style segments share an SGR wrap
- * because the SGR-codes string is the same group key for both — the
- * partitioning shape (data) encodes the byte structure; the emit walk is a
- * mechanical fold over it.
+ * 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;
-function segmentToPiece(segment, destination) {
-    if (segment.isControl)
-        return undefined;
-    if (segment.text.length === 0)
-        return undefined;
-    const style = segment.style;
-    if (!style || style.isNull) {
-        return { text: segment.text, sgrCodes: "", link: undefined };
-    }
-    // [LAW:one-type-per-behavior] Colour depth governs SGR only; hyperlinks are
-    // their own fact. Coupling them let a colour setting delete every control.
-    return {
-        text: segment.text,
-        sgrCodes: destination.colorSystem === null ? "" : style.toSgrCodes(destination.colorSystem),
-        link: destination.hyperlinks ? style.link : undefined,
-    };
-}
 /**
- * Encodes a single segment as ANSI bytes for `destination`. Equivalent to
- * `segmentsToString([segment], destination)` — same SGR / OSC 8 layout.
+ * 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) {
-    return segmentsToString([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`, coalescing
- * adjacent same-SGR segments under a single SGR open/close pair, with OSC 8
- * link pairs nested inside per same-link sub-run.
- */
+/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
 export function segmentsToString(segments, destination) {
-    const pieces = [];
-    for (const s of segments) {
-        const p = segmentToPiece(s, destination);
-        if (p)
-            pieces.push(p);
-    }
-    if (pieces.length === 0)
-        return "";
-    // [LAW:dataflow-not-control-flow] One linear chunk accumulator for the
-    // entire output; SGR / OSC 8 boundaries and piece texts all push into it
-    // in order. No per-link-run intermediate string, no quadratic `+=` chains.
     const parts = [];
-    let i = 0;
-    while (i < pieces.length) {
-        const sgr = pieces[i].sgrCodes;
-        let j = i + 1;
-        while (j < pieces.length && pieces[j].sgrCodes === sgr)
-            j++;
-        if (sgr.length > 0)
-            parts.push(`\x1b[${sgr}m`);
-        let k = i;
-        while (k < j) {
-            const link = pieces[k].link;
-            let l = k + 1;
-            while (l < j && pieces[l].link === link)
-                l++;
-            if (link) {
-                parts.push(osc8Open(link));
-                for (let m = k; m < l; m++)
-                    parts.push(pieces[m].text);
-                parts.push(OSC8_CLOSE);
-            }
-            else {
-                for (let m = k; m < l; m++)
-                    parts.push(pieces[m].text);
-            }
-            k = l;
-        }
-        if (sgr.length > 0)
-            parts.push("\x1b[0m");
-        i = j;
-    }
+    for (const segment of segments)
+        parts.push(segmentToString(segment, destination));
     return parts.join("");
 }
 export function renderToString(renderable, options) {
@@ -136,7 +93,10 @@ export function renderToString(renderable, options) {
         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,

package/dist/core/segment.d.ts

@@ -33,12 +33,13 @@ export declare class Segment {
     get hasText(): boolean;
     get isControl(): boolean;
     /**
-     * Splits at a cell position. Returns [left, right].
+     * 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 as many cells further into
-     * whatever drew it as the left half took from this one, and its anchor says
-     * so; see `./anchor.ts`. That is not `leftText`'s width: a cut through a
-     * wide glyph pads the left half and keeps the whole glyph on the right.
+     * [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;

package/dist/core/segment.js

@@ -2,7 +2,7 @@
  * Segment — the atomic rendering unit. Every piece of styled terminal output
  * is represented as a Segment: (text, style?, control?).
  */
-import { cellLen, splitText, asCellCol } from "./cells.js";
+import { cellLen, cutCells, splitText, asCellCol } from "./cells.js";
 import { Style } from "./style.js";
 import { shiftAnchor } from "./anchor.js";
 // --- ControlType ---
@@ -45,12 +45,13 @@ export class Segment {
         return this.control !== undefined;
     }
     /**
-     * Splits at a cell position. Returns [left, right].
+     * 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 as many cells further into
-     * whatever drew it as the left half took from this one, and its anchor says
-     * so; see `./anchor.ts`. That is not `leftText`'s width: a cut through a
-     * wide glyph pads the left half and keeps the whole glyph on the right.
+     * [LAW:single-enforcer] The right half starts `position` cells further into
+     * whatever drew it, and its anchor says so; see `./anchor.ts`.
      */
     splitCells(position) {
         const len = this.cellLength;
@@ -58,10 +59,10 @@ export class Segment {
             return [this, new Segment("")];
         if (position <= 0)
             return [new Segment(""), this];
-        const [leftText, rightText] = splitText(this.text, position);
+        const [leftText, rightText] = cutCells(this.text, position);
         return [
             new Segment(leftText, this.style),
-            new Segment(rightText, this.style?.shiftedBy(len - cellLen(rightText))),
+            new Segment(rightText, this.style?.shiftedBy(position)),
         ];
     }
     // --- Static factories ---
@@ -394,13 +395,8 @@ export class Segment {
         for (const cut of cuts) {
             const section = [];
             while (currentSegment && cellOffset + currentSegment.cellLength <= cut) {
-                if (currentSegment.isControl) {
-                    section.push(currentSegment);
-                }
-                else {
-                    section.push(currentSegment);
-                    cellOffset += currentSegment.cellLength;
-                }
+                section.push(currentSegment);
+                cellOffset += currentSegment.cellLength;
                 segmentIndex++;
                 currentSegment = segments[segmentIndex];
             }

package/dist/core/selection.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The list cursor: one clamp, shared by every list that moves a selection —
+ * `ListView`'s callers and `Dropdown` alike — so it has one definition.
+ */
+/**
+ * The selection `delta` items on from `index` in a list of `length`, held to
+ * the list's ends: `-Infinity` is the first item and `Infinity` the last. A
+ * move that cannot go anywhere returns `index` itself, so `next === index`
+ * says nothing moved and the caller can skip a repaint. An empty list has
+ * nowhere to move to and returns `index`.
+ */
+export declare function moveSelection(index: number, delta: number, length: number): number;

package/dist/core/selection.js

@@ -0,0 +1,14 @@
+/**
+ * The list cursor: one clamp, shared by every list that moves a selection —
+ * `ListView`'s callers and `Dropdown` alike — so it has one definition.
+ */
+/**
+ * The selection `delta` items on from `index` in a list of `length`, held to
+ * the list's ends: `-Infinity` is the first item and `Infinity` the last. A
+ * move that cannot go anywhere returns `index` itself, so `next === index`
+ * says nothing moved and the caller can skip a repaint. An empty list has
+ * nowhere to move to and returns `index`.
+ */
+export function moveSelection(index, delta, length) {
+    return length === 0 ? index : Math.max(0, Math.min(length - 1, index + delta));
+}