@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/renderables/rule.d.ts

@@ -16,6 +16,7 @@ export declare class Rule implements Renderable, Measurable {
     readonly characters: string;
     readonly align: RuleAlign;
     readonly style: string | Style;
+    private readonly _label;
     constructor(title?: string | RichText, options?: RuleOptions);
     render(options: RenderOptions): Iterable<Segment>;
     measure(_options: RenderOptions): {

package/dist/renderables/rule.js

@@ -1,11 +1,11 @@
 /**
  * Rule — a horizontal divider line, optionally with a centered title.
  */
-import { cellLen } from "../core/cells.js";
+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 { inlineLabel } from "./embed.js";
+import { cutLabel, drawLabel, inlineLabel } from "./embed.js";
 const ASCII_RULE_CHAR = "-";
 const DEFAULT_RULE_CHAR = "\u2500"; // ─
 export class Rule {
@@ -13,16 +13,20 @@ export class Rule {
     characters;
     align;
     style;
+    _label;
     constructor(title, options) {
         const chars = options?.characters ?? DEFAULT_RULE_CHAR;
-        if (chars.length === 0) {
-            throw new Error("Rule characters must not be empty");
+        // [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;
@@ -32,34 +36,42 @@ export class Rule {
         const ruleChar = drawable(options, this.characters, ASCII_RULE_CHAR);
         const style = getStyle(options, this.style);
         const ruleStyle = style.isNull ? undefined : style;
-        const title = inlineLabel(this.title, options, ruleStyle);
-        const titleWidth = Segment.getLineLength(title);
-        if (titleWidth === 0) {
-            // No title — just a line of repeated characters
-            yield new Segment(repeatToWidth(ruleChar, maxWidth), ruleStyle);
-            yield Segment.line();
-            return;
-        }
-        if (titleWidth >= maxWidth) {
-            // Title fills the whole width; adjustLineLength cuts by cells, not code units.
-            yield* Segment.adjustLineLength(title, maxWidth, ruleStyle);
+        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 remaining = maxWidth - titleWidth;
-        // [LAW:dataflow-not-control-flow] Always compute both sides; alignment determines distribution
-        const leftWidth = this.align === "right"
-            ? remaining
-            : this.align === "center"
-                ? Math.floor(remaining / 2)
-                : 0;
-        const rightWidth = remaining - leftWidth;
-        if (leftWidth > 0) {
-            yield new Segment(repeatToWidth(ruleChar, leftWidth), ruleStyle);
-        }
-        yield* title;
-        if (rightWidth > 0) {
-            yield new Segment(repeatToWidth(ruleChar, rightWidth), ruleStyle);
+        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();
     }
@@ -67,24 +79,8 @@ export class Rule {
         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) {
-    const charWidth = cellLen(char);
-    if (charWidth === 0)
-        return " ".repeat(width);
-    const repeats = Math.ceil(width / charWidth);
-    const full = char.repeat(repeats);
-    // Trim to exact width
-    let w = 0;
-    let i = 0;
-    for (const c of full) {
-        const cw = cellLen(c);
-        if (w + cw > width)
-            break;
-        w += cw;
-        i += c.length;
-    }
-    const result = full.slice(0, i);
-    // Pad if needed (wide char couldn't fill exact width)
-    const gap = width - w;
-    return gap > 0 ? result + " ".repeat(gap) : result;
+    return setCellSize(char.repeat(Math.ceil(width / cellLen(char))), asCellCol(width));
 }

package/dist/renderables/spinner.d.ts

@@ -3,6 +3,7 @@
  */
 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;
@@ -10,20 +11,45 @@ export interface SpinnerOptions {
 }
 export declare class Spinner implements Renderable, Measurable {
     readonly name: string;
-    readonly text: string | undefined;
     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, options?: SpinnerOptions);
+    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

@@ -4,18 +4,27 @@
 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, getStyle } from "../core/protocol.js";
+import { drawable } from "../core/protocol.js";
+import { EmbeddedText } from "./embed.js";
 const spinnerGlyphs = ({ frames }) => frames.join("");
 export class Spinner {
     name;
-    text;
     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) {
+    constructor(name, text = "", options) {
         const spinnerName = name ?? DEFAULT_SPINNER;
         const data = SPINNERS[spinnerName];
         if (!data) {
@@ -38,11 +47,12 @@ export class Spinner {
     /** Advance the frame count by the time elapsed, and return it. */
     _advance() {
         const now = Date.now();
-        const elapsed = now - this._lastUpdate;
-        const effectiveInterval = this.interval / this.speed;
-        if (elapsed >= effectiveInterval) {
-            const steps = Math.floor(elapsed / effectiveInterval);
-            this._frameIndex = (this._frameIndex + steps) % this._data.frames.length;
+        // 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;
@@ -51,20 +61,43 @@ export class Spinner {
     _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);
-        const frame = frames[this._advance() % frames.length];
-        const style = getStyle(options, this.style);
-        const spinStyle = style.isNull ? undefined : style;
-        yield new Segment(frame, spinStyle);
-        if (this.text) {
-            yield new Segment(` ${this.text}`);
-        }
+        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 frameWidth = Math.max(...this._drawnFrames(options).map((f) => cellLen(f)));
-        const textWidth = this.text ? cellLen(this.text) + 1 : 0;
-        const total = frameWidth + textWidth;
-        return { minimum: frameWidth, maximum: total };
+        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

@@ -1,23 +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 { Style } from "../core/style.js";
+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;
-    style?: string | Style;
+    /** The spinner's frame style; the message styles itself with its markup. */
+    spinnerStyle?: string | Style;
     console?: Console;
 }
 export declare class Status {
     private _live;
-    private _renderable;
+    private _spinner;
     private _console;
-    constructor(message: string, options?: StatusOptions);
+    constructor(message: string | RichText, options?: StatusOptions);
     get console(): Console;
-    get message(): string;
-    set message(value: string);
+    get message(): string | RichText;
+    set message(value: string | RichText);
     start(): void;
     stop(): void;
-    update(message: string): void;
+    update(message: string | RichText): void;
 }

package/dist/renderables/status.js

@@ -1,38 +1,24 @@
 /**
  * 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 { Segment } from "../core/segment.js";
-import { NULL_STYLE } from "../core/style.js";
 import { Console } from "../core/console.js";
 import { Spinner } from "./spinner.js";
 import { Live } from "./live.js";
-import { getStyle } from "../core/protocol.js";
-/** A renderable that shows spinner + message */
-class StatusRenderable {
-    message;
-    _spinner;
-    _style;
-    constructor(message, spinner, style) {
-        this.message = message;
-        this._spinner = spinner;
-        this._style = style;
-    }
-    *render(options) {
-        yield* this._spinner.render(options);
-        const style = getStyle(options, this._style);
-        const msgStyle = style.isNull ? undefined : style;
-        yield new Segment(` ${this.message}`, msgStyle);
-    }
-}
 export class Status {
     _live;
-    _renderable;
+    _spinner;
     _console;
     constructor(message, options) {
-        this._console = options?.console ?? new Console({ forceTerminal: true });
-        const spinner = new Spinner(options?.spinner ?? "dots", undefined, { speed: options?.speed });
-        this._renderable = new StatusRenderable(message, spinner, options?.style ?? NULL_STYLE);
-        this._live = new Live(this._renderable, {
+        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,
@@ -42,10 +28,10 @@ export class Status {
         return this._console;
     }
     get message() {
-        return this._renderable.message;
+        return this._spinner.text;
     }
     set message(value) {
-        this._renderable.message = value;
+        this._spinner.text = value;
     }
     start() {
         this._live.start();
@@ -54,7 +40,7 @@ export class Status {
         this._live.stop();
     }
     update(message) {
-        this._renderable.message = message;
-        this._live.update(this._renderable, { refresh: true });
+        this._spinner.text = message;
+        this._live.update(this._spinner, { refresh: true });
     }
 }

package/dist/renderables/syntax.d.ts

@@ -1,35 +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 { PaddingDimensions } from "./padding.js";
 import { type Measurable, type Renderable, type RenderOptions } from "../core/protocol.js";
 export interface SyntaxOptions {
     lineNumbers?: boolean;
-    theme?: string;
     startLine?: number;
     lineRange?: [number, number];
     highlightLines?: Set<number>;
     wordWrap?: boolean;
     tabSize?: number;
-    padding?: PaddingDimensions;
 }
+/**
+ * [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: 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;
-    constructor(code: string, language?: string, options?: SyntaxOptions);
+    /** 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;
     };
-    private _highlight;
-    static fromPath(_filePath: string, _options?: SyntaxOptions): Syntax;
 }
+export {};