@promptctl/rich-js 0.17.0 → 0.18.1

package/dist/core/strip.js

@@ -29,6 +29,7 @@ import { Segment } from "./segment.js";
 import { Style } from "./style.js";
 import { ColorDepth, ColorSpec, blendRgb } from "./color.js";
 import { Oklch } from "./oklch.js";
+import { drawable } from "./protocol.js";
 // --- Strip ---
 export class Strip {
     items;
@@ -72,17 +73,6 @@ const EMPTY = {
         // intentionally empty
     },
 };
-class FixedSegment {
-    _text;
-    _style;
-    constructor(text, style) {
-        this._text = text;
-        this._style = style;
-    }
-    *render(_options) {
-        yield new Segment(this._text, this._style);
-    }
-}
 /** A renderable whose segments are computed from the options it is rendered with. */
 function deferred(emit) {
     return { render: emit };
@@ -159,16 +149,18 @@ export const POWERLINE_JOINER_GLYPHS = Object.freeze({
     lead: "\ue0d7",
     tail: "\ue0b0",
 });
+/** The powerline set in ASCII: an arrow for every join, runs begun flat. */
+const ASCII_POWERLINE_GLYPHS = Object.freeze({
+    glyph: ">",
+    divider: ">",
+    lead: "",
+    tail: ">",
+});
+const powerlineGlyphs = ({ glyph, divider, lead, tail }) => glyph + divider + lead + tail;
 export class PowerlineJoiner {
-    _glyph;
-    _divider;
-    _lead;
-    _tail;
+    _glyphs;
     constructor(options = POWERLINE_JOINER_GLYPHS) {
-        this._glyph = options.glyph;
-        this._divider = options.divider;
-        this._lead = options.lead;
-        this._tail = options.tail;
+        this._glyphs = options;
     }
     join(left, right) {
         // [LAW:dataflow-not-control-flow] One table for all three positions (start
@@ -196,11 +188,9 @@ export class PowerlineJoiner {
         // is the only thing that elides the separator, and that is paint logic.
         // "Absent" = no bg OR the terminal default (transparent) — paintableBg folds
         // both to undefined so an explicit `… on default` cannot smuggle a separator.
-        const glyph = this._glyph;
-        const divider = this._divider;
-        const lead = this._lead;
-        const tail = this._tail;
+        const glyphs = this._glyphs;
         return deferred(function* (options) {
+            const { glyph, divider, lead, tail } = drawable(options, glyphs, ASCII_POWERLINE_GLYPHS, powerlineGlyphs);
             const leftEdge = left?.edgeStyle("right", options);
             const leftBg = paintableBg(leftEdge?.bgcolor);
             const rightBg = paintableBg(right?.edgeStyle("left", options).bgcolor);
@@ -222,31 +212,33 @@ export class PowerlineJoiner {
         });
     }
 }
+const ASCII_CAPS = { left: "(", right: ")" };
+const capGlyphs = ({ left, right }) => left + right;
 export class CapsuleJoiner {
-    _left;
-    _right;
+    _caps;
     _separator;
     constructor(options) {
-        this._left = options?.left ?? "";
-        this._right = options?.right ?? "";
+        this._caps = { left: options?.left ?? "", right: options?.right ?? "" };
         this._separator = options?.separator ?? " ";
     }
     *_emit(left, right, options) {
+        const caps = drawable(options, this._caps, ASCII_CAPS, capGlyphs);
+        const separator = drawable(options, this._separator, " ");
         if (left === null && right === null)
             return;
         if (left === null) {
-            yield new Segment(this._left, bgAsFg(right.edgeStyle("left", options)));
+            yield new Segment(caps.left, bgAsFg(right.edgeStyle("left", options)));
             return;
         }
         if (right === null) {
-            yield new Segment(this._right, bgAsFg(left.edgeStyle("right", options)));
+            yield new Segment(caps.right, bgAsFg(left.edgeStyle("right", options)));
             return;
         }
         // Middle: close the left capsule, separator (unstyled), open the right.
-        yield new Segment(this._right, bgAsFg(left.edgeStyle("right", options)));
-        if (this._separator.length > 0)
-            yield new Segment(this._separator);
-        yield new Segment(this._left, bgAsFg(right.edgeStyle("left", options)));
+        yield new Segment(caps.right, bgAsFg(left.edgeStyle("right", options)));
+        if (separator.length > 0)
+            yield new Segment(separator);
+        yield new Segment(caps.left, bgAsFg(right.edgeStyle("left", options)));
     }
     join(left, right) {
         return deferred((options) => this._emit(left, right, options));
@@ -263,7 +255,9 @@ export class PlainJoiner {
         // Endpoints are empty — a fixed separator has no natural cap.
         if (left === null || right === null)
             return EMPTY;
-        return new FixedSegment(this._separator, this._style);
+        const separator = this._separator;
+        const style = this._style;
+        return deferred((options) => [new Segment(drawable(options, separator, " | "), style)]);
     }
 }
 /**
@@ -292,6 +286,9 @@ export class GradientJoiner {
                 return;
             const lTrip = lbg.getTruecolor();
             const rTrip = rbg.getTruecolor();
+            // An ASCII cell carries one sample, the background: the gradient keeps
+            // its colours at half the resolution.
+            const half = drawable(options, HALF_BLOCK, " ");
             const samples = 2 * steps;
             // Midpoint sampling across `2 * steps` half-cell positions: sample j has
             // t = (j + 0.5) / samples. Cell i takes samples 2i (left half) and 2i+1
@@ -301,7 +298,7 @@ export class GradientJoiner {
                 const tRight = (2 * i + 1.5) / samples;
                 const fg = ColorSpec.fromRgba(blendRgb(lTrip, rTrip, tLeft));
                 const bg = ColorSpec.fromRgba(blendRgb(lTrip, rTrip, tRight));
-                yield new Segment(HALF_BLOCK, new Style({ color: fg, bgcolor: bg }));
+                yield new Segment(half, new Style({ color: fg, bgcolor: bg }));
             }
         });
     }

package/dist/core/style.d.ts

@@ -2,6 +2,7 @@
  * Immutable style descriptors — colors, text attributes, links, metadata.
  */
 import { ColorSpec, ColorDepth } from "./color.js";
+import { type Anchor } from "./anchor.js";
 /**
  * Canonical text-attribute inventory. Single source of truth consumed by
  * `Style.parse` / `Style.toString` and the template bindings — adding an
@@ -10,6 +11,7 @@ import { ColorSpec, ColorDepth } from "./color.js";
  */
 export declare const ATTRIBUTE_NAMES: readonly ["bold", "dim", "italic", "underline", "blink", "blink2", "reverse", "conceal", "strike", "underline2", "frame", "encircle", "overline"];
 export type AttributeName = (typeof ATTRIBUTE_NAMES)[number];
+export declare const ATTRIBUTE_SGR: Record<AttributeName, number>;
 /**
  * Canonical short-attribute aliases (`b` → `bold`, `i` → `italic`, …).
  * Single source of truth consumed by `Style.parse` and the template
@@ -35,6 +37,7 @@ export interface StyleOptions {
     overline?: boolean;
     link?: string;
     meta?: Record<string, unknown>;
+    anchor?: Anchor;
 }
 export declare class StyleSyntaxError extends Error {
     constructor(message: string, options?: ErrorOptions);
@@ -57,13 +60,35 @@ export declare class Style {
     readonly overline: boolean | undefined;
     readonly link: string | undefined;
     readonly meta: Record<string, unknown> | undefined;
+    /**
+     * Where this style's cells sat in the output of whatever drew them; see
+     * `./anchor.ts`. It draws nothing, and it makes two styles that draw alike
+     * unequal, because they came from different places.
+     */
+    readonly anchor: Anchor | undefined;
     constructor(options?: StyleOptions);
     get isNull(): boolean;
     get transparentBackground(): boolean;
     get backgroundStyle(): Style;
+    /**
+     * This style with `overrides` in place of its own fields.
+     *
+     * [LAW:one-source-of-truth] The field list is the class's own fields, so a
+     * field added to `Style` is carried by every copy without being named here.
+     */
+    private with;
     get withoutColor(): Style;
     withLink(link: string | undefined): Style;
     clearMetaAndLinks(): Style;
+    /**
+     * The same look, drawn from the place `anchor` names, or from nowhere.
+     */
+    withAnchor(anchor: Anchor | undefined): Style;
+    /**
+     * This style on the cell `cells` to the right: its anchor shifted along its
+     * row, or the style itself when it has no anchor.
+     */
+    shiftedBy(cells: number): Style;
     /**
      * Merges two styles. `other`'s values take priority.
      */

package/dist/core/style.js

@@ -2,6 +2,7 @@
  * Immutable style descriptors — colors, text attributes, links, metadata.
  */
 import { COLOR_NAMES, ColorSpec, SURFACE_BLACK, } from "./color.js";
+import { shiftAnchor } from "./anchor.js";
 // [LAW:one-way-deps] `core/style` depends only on `core/color`. The substrate
 // a translucent colour is flattened over is `SURFACE_BLACK`, defined beside
 // `compositeOver`.
@@ -27,8 +28,8 @@ export const ATTRIBUTE_NAMES = [
     "encircle",
     "overline",
 ];
-// The SGR parameter that turns each attribute on
-const ATTRIBUTE_SGR = {
+// The SGR parameter that turns each attribute on. `ansi.ts` reads it back.
+export const ATTRIBUTE_SGR = {
     bold: 1,
     dim: 2,
     italic: 3,
@@ -86,27 +87,13 @@ export class Style {
     overline;
     link;
     meta;
-    constructor(options) {
-        if (!options) {
-            this.color = undefined;
-            this.bgcolor = undefined;
-            this.bold = undefined;
-            this.dim = undefined;
-            this.italic = undefined;
-            this.underline = undefined;
-            this.blink = undefined;
-            this.blink2 = undefined;
-            this.reverse = undefined;
-            this.conceal = undefined;
-            this.strike = undefined;
-            this.underline2 = undefined;
-            this.frame = undefined;
-            this.encircle = undefined;
-            this.overline = undefined;
-            this.link = undefined;
-            this.meta = undefined;
-            return;
-        }
+    /**
+     * Where this style's cells sat in the output of whatever drew them; see
+     * `./anchor.ts`. It draws nothing, and it makes two styles that draw alike
+     * unequal, because they came from different places.
+     */
+    anchor;
+    constructor(options = {}) {
         this.color = resolveColor(options.color);
         this.bgcolor = resolveColor(options.bgcolor);
         this.bold = options.bold;
@@ -124,6 +111,7 @@ export class Style {
         this.overline = options.overline;
         this.link = options.link;
         this.meta = options.meta;
+        this.anchor = options.anchor;
     }
     get isNull() {
         return (this.color === undefined &&
@@ -142,7 +130,8 @@ export class Style {
             this.encircle === undefined &&
             this.overline === undefined &&
             this.link === undefined &&
-            this.meta === undefined);
+            this.meta === undefined &&
+            this.anchor === undefined);
     }
     get transparentBackground() {
         return this.bgcolor === undefined || this.bgcolor.isDefault;
@@ -150,68 +139,40 @@ export class Style {
     get backgroundStyle() {
         return new Style({ bgcolor: this.bgcolor });
     }
+    /**
+     * This style with `overrides` in place of its own fields.
+     *
+     * [LAW:one-source-of-truth] The field list is the class's own fields, so a
+     * field added to `Style` is carried by every copy without being named here.
+     */
+    with(overrides) {
+        return new Style({ ...this, ...overrides });
+    }
     get withoutColor() {
-        return new Style({
-            bold: this.bold,
-            dim: this.dim,
-            italic: this.italic,
-            underline: this.underline,
-            blink: this.blink,
-            blink2: this.blink2,
-            reverse: this.reverse,
-            conceal: this.conceal,
-            strike: this.strike,
-            underline2: this.underline2,
-            frame: this.frame,
-            encircle: this.encircle,
-            overline: this.overline,
-            link: this.link,
-            meta: this.meta,
-        });
+        return this.with({ color: undefined, bgcolor: undefined });
     }
     // [LAW:types-are-the-program] Structural clone helper — pure rearrangement
     // of fields, no policy. Sanitization of the URL is the trust boundary's
     // job (see RichText in text.ts); Style stays a faithful container so
     // callers that have already sanitized are not silently re-mutated.
     withLink(link) {
-        return new Style({
-            color: this.color,
-            bgcolor: this.bgcolor,
-            bold: this.bold,
-            dim: this.dim,
-            italic: this.italic,
-            underline: this.underline,
-            blink: this.blink,
-            blink2: this.blink2,
-            reverse: this.reverse,
-            conceal: this.conceal,
-            strike: this.strike,
-            underline2: this.underline2,
-            frame: this.frame,
-            encircle: this.encircle,
-            overline: this.overline,
-            link,
-            meta: this.meta,
-        });
+        return this.with({ link });
     }
     clearMetaAndLinks() {
-        return new Style({
-            color: this.color,
-            bgcolor: this.bgcolor,
-            bold: this.bold,
-            dim: this.dim,
-            italic: this.italic,
-            underline: this.underline,
-            blink: this.blink,
-            blink2: this.blink2,
-            reverse: this.reverse,
-            conceal: this.conceal,
-            strike: this.strike,
-            underline2: this.underline2,
-            frame: this.frame,
-            encircle: this.encircle,
-            overline: this.overline,
-        });
+        return this.with({ link: undefined, meta: undefined });
+    }
+    /**
+     * The same look, drawn from the place `anchor` names, or from nowhere.
+     */
+    withAnchor(anchor) {
+        return this.with({ anchor });
+    }
+    /**
+     * This style on the cell `cells` to the right: its anchor shifted along its
+     * row, or the style itself when it has no anchor.
+     */
+    shiftedBy(cells) {
+        return this.anchor ? this.withAnchor(shiftAnchor(this.anchor, cells)) : this;
     }
     /**
      * Merges two styles. `other`'s values take priority.
@@ -241,6 +202,7 @@ export class Style {
             meta: other.meta && this.meta
                 ? { ...this.meta, ...other.meta }
                 : other.meta ?? this.meta,
+            anchor: other.anchor ?? this.anchor,
         });
     }
     equals(other) {
@@ -261,7 +223,8 @@ export class Style {
             this.frame === other.frame &&
             this.encircle === other.encircle &&
             this.overline === other.overline &&
-            this.link === other.link);
+            this.link === other.link &&
+            anchorsEqual(this.anchor, other.anchor));
     }
     /**
      * The colours this style puts on screen at `colorSystem`: each flattened
@@ -297,18 +260,17 @@ export class Style {
     toSgrCodes(colorSystem) {
         if (this.isNull)
             return "";
-        const attrs = [];
+        // Attributes, then foreground, then background: Python Rich 9d8f9a3's
+        // `_make_ansi_codes` order, so a byte pinned against the reference holds.
+        // An attribute set false writes nothing, as there. It overrides an
+        // inherited attribute when styles combine, and every styled run is written
+        // after a reset, so no off code is ever needed.
         const drawn = this.drawnColors(colorSystem);
-        if (drawn.color)
-            attrs.push(...drawn.color.getAnsiCodes(true));
-        if (drawn.bgcolor)
-            attrs.push(...drawn.bgcolor.getAnsiCodes(false));
-        // An attribute set false writes nothing, as in Python Rich 9d8f9a3's
-        // `_make_ansi_codes`. It overrides an inherited attribute when styles
-        // combine, and every styled run is written after a reset, so no off
-        // code is ever needed.
-        attrs.push(...ATTRIBUTE_NAMES.filter((name) => this[name] === true).map((name) => `${ATTRIBUTE_SGR[name]}`));
-        return attrs.join(";");
+        return [
+            ...ATTRIBUTE_NAMES.filter((name) => this[name] === true).map((name) => `${ATTRIBUTE_SGR[name]}`),
+            ...(drawn.color?.getAnsiCodes(true) ?? []),
+            ...(drawn.bgcolor?.getAnsiCodes(false) ?? []),
+        ].join(";");
     }
     /**
      * Serializes to a canonical string that round-trips through `Style.parse()`.
@@ -680,6 +642,9 @@ export const DEFAULT_STYLES = {
     "bar.complete": Style.parse("magenta"),
     "bar.finished": Style.parse("green"),
     "bar.pulse": Style.parse("magenta"),
+    // Scrollbar
+    "scrollbar.thumb": NULL_STYLE,
+    "scrollbar.track": Style.parse("grey37"),
     // Tree
     "tree": NULL_STYLE,
     "tree.guide": NULL_STYLE,
@@ -721,3 +686,10 @@ export const DEFAULT_STYLES = {
  * a renderable sees outside a `Console`, as in `renderToString`.
  */
 export const DEFAULT_THEME = new Theme();
+function anchorsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return a.owner === b.owner && a.row === b.row && a.col === b.col && anchorsEqual(a.inner, b.inner);
+}

package/dist/core/text.d.ts

@@ -3,7 +3,8 @@
  */
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
-import type { Renderable, Measurable, RenderOptions } from "./protocol.js";
+import type { Renderable, Measurable, OverflowMethod, RenderOptions } from "./protocol.js";
+export declare function stripControlChars(text: string): string;
 export declare class Span {
     readonly start: number;
     readonly end: number;
@@ -19,7 +20,7 @@ export declare class Span {
 export interface RichTextOptions {
     style?: string | Style;
     justify?: "left" | "center" | "right" | "full";
-    overflow?: "fold" | "crop" | "ellipsis";
+    overflow?: OverflowMethod;
     end?: string;
     tabSize?: number;
     noWrap?: boolean;
@@ -44,8 +45,8 @@ export declare class RichText implements Renderable, Measurable {
     set style(value: string | Style);
     get justify(): "left" | "center" | "right" | "full" | undefined;
     set justify(value: "left" | "center" | "right" | "full" | undefined);
-    get overflow(): "fold" | "crop" | "ellipsis" | undefined;
-    set overflow(value: "fold" | "crop" | "ellipsis" | undefined);
+    get overflow(): OverflowMethod | undefined;
+    set overflow(value: OverflowMethod | undefined);
     get end(): string;
     set end(value: string);
     get noWrap(): boolean;
@@ -114,7 +115,10 @@ export declare class RichText implements Renderable, Measurable {
      *   in the middle.
      *
      * Marker default is `"\u2026"`. Pass `marker: ""` for raw cropping without an
-     * indicator glyph.
+     * indicator glyph. A marker wider than `width` is itself cut to the glyphs
+     * that fit, and the text takes whatever cells that leaves — all of them, when
+     * not one glyph of the marker fits — so the result is never wider than asked.
+     * Every cut, marker and text alike, falls between grapheme clusters.
      *
      * Spans are preserved through the cut: characters that survive keep their
      * styling; the marker (if any) is inserted as plain text with no span.
@@ -130,10 +134,6 @@ export declare class RichText implements Renderable, Measurable {
     }): this;
     private _cropRightTo;
     private _cropLeftTo;
-    /** Number of char-index code units that fit within `targetWidth` cell columns from the left. */
-    private _cellPrefixCharLength;
-    /** Char-index at which the suffix of `targetWidth` cell columns starts. */
-    private _cellSuffixStartCharIndex;
     align(justify: "left" | "center" | "right", width: number): this;
     removeSuffix(suffix: string): this;
     appendTokens(tokens: Array<[string, (string | Style)?]>): this;
@@ -150,9 +150,8 @@ export declare class RichText implements Renderable, Measurable {
      * `{{ red "x" }}{{ blue "y" }}` evaluates to two fragments — one with
      * wrapping `style = red`, one with `blue` — and consumers that want a
      * single styled string for downstream rendering need both styles
-     * preserved as spans on the concatenated result. The plain `append()`
-     * propagates spans only, so this static does the additional work of
-     * lifting `frag.style` into a span before appending.
+     * preserved as spans on the concatenated result, which is what `append()`
+     * does with each fragment.
      *
      * Empty input → empty `RichText` with `end: ""`. Caller can override
      * `end` (defaults to `""` — the engine-output case rarely wants a
@@ -247,9 +246,11 @@ export declare class RichText implements Renderable, Measurable {
      *
      * Everything reaching here already survived wrapping, so the only text still
      * too wide is text no break could help: a word longer than the canvas under
-     * a non-folding overflow method, a glyph wider than the budget, or a canvas
-     * with no cells at all. That is what makes the overflow method a last
-     * resort rather than the first thing a long cell meets.
+     * a non-folding overflow method, a glyph wider than the budget, a canvas
+     * with no cells at all, or a `noWrap` line, which no break was allowed to
+     * help. That is what makes the overflow method a last resort rather than the
+     * first thing a long cell meets. `"fold"` has nothing left to fold here and
+     * cuts as `"crop"` does, as the reference's `truncate` does.
      */
     private _fitLine;
 }