@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/renderables/embed.d.ts

@@ -1,50 +1,113 @@
 /**
  * The one crossing where content a caller hands a renderable — a table cell, a
- * panel's body, title or subtitle, a tree label, a column item, a layout pane,
- * a rule's title — becomes something that renderable can lay out.
+ * panel's body, title or subtitle, a padding's body, a tree label, a column
+ * item, a layout pane, a rule's title — becomes something that renderable can
+ * lay out.
  * [LAW:single-enforcer]
  *
- * Each of those sites used to build its own `RichText` straight from the
- * constructor, which does not parse markup, so `[red]Solo[/red]` reached the
- * terminal with its tags intact. Table cells were fixed on their own first; the
- * rest kept the defect until the rule moved here.
+ * A string is kept as written and read when it is drawn, through `readStr`,
+ * under the options it is drawn with. That is where a console's settings
+ * arrive: its `markup` decides whether the string is markup, and its
+ * highlighter highlights it, exactly as they do for a string handed to `print`.
+ * Parsed when the renderable was built, a string was markup under a console
+ * that had turned markup off, never met the console's highlighter, and an
+ * unmatched closing tag threw from a constructor rather than from the render
+ * that would draw it, where Rich's does (rich-markup-3sw).
  *
- * Markup is parsed because Rich parses it: every one of these positions
- * reaches the wire through Rich's `render_str`, and a console's markup is on by
- * default. Rich's `render_str` also honours `Console(markup=False)` and runs the
- * console's highlighter; this crossing does neither, because the console's
- * settings do not reach it (rich-markup-3sw).
- *
- * `end` is cleared because embedded text is a fragment rather than a printed
- * line; left at the default `"\n"` it draws a trailing blank row. A `RichText`
- * is copied first, since clearing in place would reach back into the caller's
- * object.
+ * Text keeps its own `end`, as a body does in Rich: `RichText("foo\n")` draws
+ * the blank row its default `"\n"` end makes, and a string reads with that
+ * default end as `render_str` gives it. Only a label, set into a line it
+ * shares, clears it. A `RichText` is copied when it is handed over, since the
+ * caller still holds it, and every text drawn from it is a copy again, since
+ * the drawing site may change it.
  */
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
-import type { Style } from "../core/style.js";
+import type { Style, TextStyle } from "../core/style.js";
 import { RichText } from "../core/text.js";
 /**
- * Caller content as the text an embedding site lays out, `end` cleared. A
- * string is the only kind of content that can contain markup, so it is the only
- * kind parsed; any other value is its `String` form as written, so an object's
- * `[object Object]` is not eaten as a tag.
+ * Caller content as text an embedding site lays out. A string is the only kind
+ * of content that can contain markup, so it is the only kind whose reading
+ * waits for the options; any other value is its `String` form as written, so an
+ * object's `[object Object]` is not eaten as a tag.
  */
-export declare function embeddedText(content: unknown): RichText;
+export declare class EmbeddedText implements Renderable, Measurable {
+    private readonly _source;
+    private readonly _readings;
+    constructor(content: unknown);
+    /**
+     * The text this content draws under `options`. A string reads with `base` as
+     * its style, as Rich's `render_str(style=)` gives one; text handed over
+     * keeps its own, since the caller already said how it looks — so a table's
+     * `Text` title draws without the title style, as Rich's does. A highlighted
+     * string keeps only its spans: Rich's `render_str` highlights a fresh `Text`
+     * of the plain string and copies the spans onto it, so `base` is lost there,
+     * and a title Rich reads with highlighting on draws without it.
+     */
+    text(options: RenderOptions, base?: TextStyle): RichText;
+    render(options: RenderOptions): Iterable<Segment>;
+    /**
+     * Measured unhighlighted, as Rich's `Measurement.get` reads a string with
+     * `highlight=False`: so a container that clears the highlighter for what it
+     * draws measures what it draws, whether or not it clears it for what it
+     * measures, and no highlighter runs just to be thrown away.
+     */
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}
 /**
  * Caller content as something an embedding site can render. A non-text
- * `Renderable` (a nested `Panel` or `Table`) passes through: it carries no
- * `end` to clear and no markup to parse. Everything else is `embeddedText`.
+ * `Renderable` (a nested `Panel` or `Table`) passes through: it has no markup
+ * to parse. Everything else is `EmbeddedText`.
  */
 export declare function embed(content: unknown): Renderable & Partial<Measurable>;
 /**
  * Caller content set into a line it shares with other drawing — a panel's
- * title or subtitle in its border, a rule's title — as one line of segments:
- * a space either side, its own styles over `base`. The caller cuts it to the
- * room it has with `Segment.adjustLineLength`, which is cell-aware.
+ * title or subtitle in its border, a rule's title — read as Rich's `_title`
+ * reads it: newlines become spaces, so the label stays on its line, and tabs
+ * are widened to their stops. Whatever sets it off from the line around it —
+ * a panel's space either side, a rule's gaps — is the embedding site's.
  *
- * Content with no text is no label at all, not two spaces: an absent title, an
- * empty string, an empty `RichText` and markup that styles nothing all draw
- * the plain line, as Rich's do (an empty `Text` is falsy there).
+ * Held once by the renderable that owns it, so a string's markup is read once
+ * and every measure and render after reuses that reading.
+ */
+export declare class InlineLabel {
+    private readonly _content;
+    constructor(content: string | RichText);
+    /**
+     * The label drawn under `options`: one line, its own overflow kept for the
+     * caller's cut. A string reads with `base` as its style, as `EmbeddedText.text` reads one.
+     */
+    text(options: RenderOptions, base?: TextStyle): RichText;
+}
+/**
+ * A label cut to `width` cells as Rich's `Text.truncate` cuts one: its plain
+ * text set to the width less `marker` — a wide character the cut splits leaves
+ * a space in its cell rather than a cell of the line around it — then the
+ * marker, with every span that ran past the cut trimmed to the new end, so the
+ * pad and the marker take the styling of what they replace. A label that fits
+ * is left as it is.
+ */
+export declare function cutLabel(text: RichText, width: number, marker: string): void;
+/**
+ * Whether caller content is there at all, decided on the content as given, as
+ * Rich's `if self.title` decides it: absent, an empty string and an empty
+ * `Text` are not, and markup that styles nothing is — it reads as empty text,
+ * but the string that holds it is not empty.
+ */
+export declare function present(content: string | RichText | undefined): content is string | RichText;
+/**
+ * A label's text as one line of segments at its natural width, its own styles
+ * laid over `base`. The caller has already cut it to its room, so it leaves as
+ * it stands: `"ignore"` also leaves it unjustified, its spaces where `pad` put
+ * them.
+ */
+export declare function drawLabel(text: RichText, options: RenderOptions, base: Style | undefined): Segment[];
+/**
+ * Caller content as a label, or no label at all: content that is not
+ * `present` draws the plain rule, and markup that styles nothing is an empty
+ * label, which still opens a gap in the rule, as Rich's does.
  */
-export declare function inlineLabel(content: unknown, options: RenderOptions, base: Style | undefined): Segment[];
+export declare function inlineLabel(content: string | RichText | undefined): InlineLabel | undefined;

package/dist/renderables/embed.js

@@ -1,71 +1,167 @@
 /**
  * The one crossing where content a caller hands a renderable — a table cell, a
- * panel's body, title or subtitle, a tree label, a column item, a layout pane,
- * a rule's title — becomes something that renderable can lay out.
+ * panel's body, title or subtitle, a padding's body, a tree label, a column
+ * item, a layout pane, a rule's title — becomes something that renderable can
+ * lay out.
  * [LAW:single-enforcer]
  *
- * Each of those sites used to build its own `RichText` straight from the
- * constructor, which does not parse markup, so `[red]Solo[/red]` reached the
- * terminal with its tags intact. Table cells were fixed on their own first; the
- * rest kept the defect until the rule moved here.
+ * A string is kept as written and read when it is drawn, through `readStr`,
+ * under the options it is drawn with. That is where a console's settings
+ * arrive: its `markup` decides whether the string is markup, and its
+ * highlighter highlights it, exactly as they do for a string handed to `print`.
+ * Parsed when the renderable was built, a string was markup under a console
+ * that had turned markup off, never met the console's highlighter, and an
+ * unmatched closing tag threw from a constructor rather than from the render
+ * that would draw it, where Rich's does (rich-markup-3sw).
  *
- * Markup is parsed because Rich parses it: every one of these positions
- * reaches the wire through Rich's `render_str`, and a console's markup is on by
- * default. Rich's `render_str` also honours `Console(markup=False)` and runs the
- * console's highlighter; this crossing does neither, because the console's
- * settings do not reach it (rich-markup-3sw).
- *
- * `end` is cleared because embedded text is a fragment rather than a printed
- * line; left at the default `"\n"` it draws a trailing blank row. A `RichText`
- * is copied first, since clearing in place would reach back into the caller's
- * object.
+ * Text keeps its own `end`, as a body does in Rich: `RichText("foo\n")` draws
+ * the blank row its default `"\n"` end makes, and a string reads with that
+ * default end as `render_str` gives it. Only a label, set into a line it
+ * shares, clears it. A `RichText` is copied when it is handed over, since the
+ * caller still holds it, and every text drawn from it is a copy again, since
+ * the drawing site may change it.
  */
-import { renderMarkup } from "../core/markup.js";
+import { cellCount, cellLen, setCellSize } from "../core/cells.js";
+import { activeHighlighter, readStr } from "../core/markup.js";
 import { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";
 /**
- * Caller content as the text an embedding site lays out, `end` cleared. A
- * string is the only kind of content that can contain markup, so it is the only
- * kind parsed; any other value is its `String` form as written, so an object's
- * `[object Object]` is not eaten as a tag.
+ * Caller content as text an embedding site lays out. A string is the only kind
+ * of content that can contain markup, so it is the only kind whose reading
+ * waits for the options; any other value is its `String` form as written, so an
+ * object's `[object Object]` is not eaten as a tag.
  */
-export function embeddedText(content) {
-    const text = content instanceof RichText
-        ? content.copy()
-        : typeof content === "string"
-            ? renderMarkup(content)
-            : new RichText(String(content ?? ""));
-    text.end = "";
-    return text;
+export class EmbeddedText {
+    // [LAW:types-are-the-program] Two kinds, and the kind is the discriminator: a
+    // string still to be read, or text whose reading is already fixed.
+    _source;
+    // A string's reading under each markup setting, made the first time one is
+    // asked for. Parsing is the costly half of drawing a string, and a table
+    // measures every cell more than once per print; read on every call, a
+    // 500-row table of markup printed 75% slower.
+    _readings = new Map();
+    constructor(content) {
+        if (typeof content === "string") {
+            this._source = content;
+        }
+        else {
+            this._source = content instanceof RichText ? content.copy() : new RichText(String(content ?? ""));
+        }
+    }
+    /**
+     * The text this content draws under `options`. A string reads with `base` as
+     * its style, as Rich's `render_str(style=)` gives one; text handed over
+     * keeps its own, since the caller already said how it looks — so a table's
+     * `Text` title draws without the title style, as Rich's does. A highlighted
+     * string keeps only its spans: Rich's `render_str` highlights a fresh `Text`
+     * of the plain string and copies the spans onto it, so `base` is lost there,
+     * and a title Rich reads with highlighting on draws without it.
+     */
+    text(options, base) {
+        if (typeof this._source !== "string")
+            return this._source.copy();
+        const markup = options.markup !== false;
+        const reading = this._readings.get(markup) ?? readStr(this._source, markup);
+        this._readings.set(markup, reading);
+        const text = reading.copy();
+        const highlighter = activeHighlighter(options);
+        if (base !== undefined && highlighter === undefined)
+            text.style = base;
+        highlighter?.highlight(text);
+        return text;
+    }
+    render(options) {
+        return this.text(options).render(options);
+    }
+    /**
+     * Measured unhighlighted, as Rich's `Measurement.get` reads a string with
+     * `highlight=False`: so a container that clears the highlighter for what it
+     * draws measures what it draws, whether or not it clears it for what it
+     * measures, and no highlighter runs just to be thrown away.
+     */
+    measure(options) {
+        return this.text({ ...options, highlight: false }).measure(options);
+    }
 }
 /**
  * Caller content as something an embedding site can render. A non-text
- * `Renderable` (a nested `Panel` or `Table`) passes through: it carries no
- * `end` to clear and no markup to parse. Everything else is `embeddedText`.
+ * `Renderable` (a nested `Panel` or `Table`) passes through: it has no markup
+ * to parse. Everything else is `EmbeddedText`.
  */
 export function embed(content) {
     if (!(content instanceof RichText) && typeof content === "object" && content !== null && "render" in content) {
         return content;
     }
-    return embeddedText(content);
+    return new EmbeddedText(content);
 }
 /**
  * Caller content set into a line it shares with other drawing — a panel's
- * title or subtitle in its border, a rule's title — as one line of segments:
- * a space either side, its own styles over `base`. The caller cuts it to the
- * room it has with `Segment.adjustLineLength`, which is cell-aware.
+ * title or subtitle in its border, a rule's title — read as Rich's `_title`
+ * reads it: newlines become spaces, so the label stays on its line, and tabs
+ * are widened to their stops. Whatever sets it off from the line around it —
+ * a panel's space either side, a rule's gaps — is the embedding site's.
  *
- * Content with no text is no label at all, not two spaces: an absent title, an
- * empty string, an empty `RichText` and markup that styles nothing all draw
- * the plain line, as Rich's do (an empty `Text` is falsy there).
+ * Held once by the renderable that owns it, so a string's markup is read once
+ * and every measure and render after reuses that reading.
+ */
+export class InlineLabel {
+    _content;
+    constructor(content) {
+        this._content = new EmbeddedText(content);
+    }
+    /**
+     * The label drawn under `options`: one line, its own overflow kept for the
+     * caller's cut. A string reads with `base` as its style, as `EmbeddedText.text` reads one.
+     */
+    text(options, base) {
+        const text = this._content.text(options, base);
+        // A fragment of the line, so its own end is not drawn, as Rich's `_title` clears it.
+        text.end = "";
+        text.plain = text.plain.replaceAll("\n", " ");
+        // Tabs widened before anything measures it, so a cut to the border and
+        // the width a title asks for count the cells the label will draw.
+        return text.expandTabs();
+    }
+}
+/**
+ * A label cut to `width` cells as Rich's `Text.truncate` cuts one: its plain
+ * text set to the width less `marker` — a wide character the cut splits leaves
+ * a space in its cell rather than a cell of the line around it — then the
+ * marker, with every span that ran past the cut trimmed to the new end, so the
+ * pad and the marker take the styling of what they replace. A label that fits
+ * is left as it is.
  */
-export function inlineLabel(content, options, base) {
-    // The label leaves at its natural width, `"ignore"`, because the caller does
-    // the cutting; the label's own overflow method would cut it first, and to a
-    // width no one measured. `"ignore"` also leaves it unjustified, so its spaces
-    // stay where `pad` put them.
-    const bare = embeddedText(content);
-    const text = bare.plain === "" ? bare : bare.pad(1);
+export function cutLabel(text, width, marker) {
+    if (text.cellLength <= width)
+        return;
+    text.plain = setCellSize(text.plain, cellCount(width - cellLen(marker))) + marker;
+}
+/**
+ * Whether caller content is there at all, decided on the content as given, as
+ * Rich's `if self.title` decides it: absent, an empty string and an empty
+ * `Text` are not, and markup that styles nothing is — it reads as empty text,
+ * but the string that holds it is not empty.
+ */
+export function present(content) {
+    // Asked of what the content is rather than of what it is not, so a `null`
+    // from untyped JS is no content, as Rich's `None` is.
+    return typeof content === "string" ? content !== "" : content instanceof RichText && content.plain !== "";
+}
+/**
+ * A label's text as one line of segments at its natural width, its own styles
+ * laid over `base`. The caller has already cut it to its room, so it leaves as
+ * it stands: `"ignore"` also leaves it unjustified, its spaces where `pad` put
+ * them.
+ */
+export function drawLabel(text, options, base) {
     text.overflow = "ignore";
     return [...Segment.applyStyle(text.render(options), base)];
 }
+/**
+ * Caller content as a label, or no label at all: content that is not
+ * `present` draws the plain rule, and markup that styles nothing is an empty
+ * label, which still opens a gap in the rule, as Rich's does.
+ */
+export function inlineLabel(content) {
+    return present(content) ? new InlineLabel(content) : undefined;
+}

package/dist/renderables/group.d.ts

@@ -2,10 +2,13 @@
  * Group — renders multiple renderables in sequence.
  * No visual chrome — purely a container.
  */
-import { Segment } from "../core/segment.js";
-import type { Renderable, RenderOptions } from "../core/protocol.js";
-export declare class Group implements Renderable {
+import type { Segment } from "../core/segment.js";
+import { type Measurement } from "../core/measure.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+export declare class Group implements Renderable, Measurable {
     readonly renderables: Renderable[];
     constructor(...renderables: Renderable[]);
     render(options: RenderOptions): Iterable<Segment>;
+    /** As wide as its widest member: the reference's `measure_renderables`. */
+    measure(options: RenderOptions): Measurement;
 }

package/dist/renderables/group.js

@@ -2,6 +2,7 @@
  * Group — renders multiple renderables in sequence.
  * No visual chrome — purely a container.
  */
+import { measureRenderables } from "../core/measure.js";
 import { stackedHeight } from "../core/protocol.js";
 export class Group {
     renderables;
@@ -14,4 +15,8 @@ export class Group {
             yield* renderable.render(memberOptions);
         }
     }
+    /** As wide as its widest member: the reference's `measure_renderables`. */
+    measure(options) {
+        return measureRenderables(options, this.renderables);
+    }
 }

package/dist/renderables/layout.d.ts

@@ -3,6 +3,8 @@
  */
 import { Segment } from "../core/segment.js";
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { CellCol } from "../core/cells.js";
+import type { Weight } from "./ratio.js";
 export interface LayoutOptions {
     name?: string;
     ratio?: number;
@@ -25,7 +27,7 @@ export declare class Layout implements Renderable, Measurable {
      * 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
-     * `_rowBudgetFor` and `_distributeSpace` are written to trust.
+     * `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
@@ -33,11 +35,11 @@ export declare class Layout implements Renderable, Measurable {
      * 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(): number;
+    get ratio(): Weight;
     set ratio(value: number);
-    get size(): number | undefined;
+    get size(): CellCol | undefined;
     set size(value: number | undefined);
-    get minimumSize(): number;
+    get minimumSize(): CellCol;
     set minimumSize(value: number);
     get children(): Layout[];
     /**
@@ -57,7 +59,6 @@ export declare class Layout implements Renderable, Measurable {
     render(rawOptions: RenderOptions): Iterable<Segment>;
     private _renderColumn;
     private _renderRow;
-    private _distributeSpace;
     /**
      * 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.
@@ -67,24 +68,6 @@ export declare class Layout implements Renderable, Measurable {
      * width there would report a two-line pane as two cells wide.
      */
     private _naturalWidth;
-    /**
-     * The budget at which `_distributeSpace` gives every child of a row at least
-     * the width it wants — the inverse of the ratio rule above, and the reason
-     * this is not the sum of those widths.
-     *
-     * [LAW:one-source-of-truth] A growing child receives `floor(budget * ratio /
-     * totalRatio)`, so to receive `want` cells it needs the budget to reach
-     * `want * totalRatio / ratio`, and one budget serves them all: the row needs
-     * the largest demand, never their total. Summed instead, a 1:1 split of
-     * "left" and "right" reported 9 and then rendered "right" into the 4 cells
-     * that `floor(9/2)` actually hands it.
-     *
-     * The panes that do not grow are paid first here for the same reason they
-     * are paid first there — and it is the reason this divides by no zero: a
-     * `ratio` of 0 never reaches the division, because a pane that does not grow
-     * demands nothing of a budget for growing.
-     */
-    private _rowBudgetFor;
     measure(rawOptions: RenderOptions): {
         minimum: number;
         maximum: number;