@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/subscription.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Unsubscribe — the shape every `on…()` in this library hands back.
+ *
+ * [LAW:decomposition] It lives in `core/` because two subsystems that must not
+ * depend on each other both need it: `host/` returns one from `onData` and
+ * `onResize`, `widgets/` returns one from `onChange`, `onSubmit`, `onKey` and
+ * `onMouse`. Either home above this tier would make the other import a
+ * subsystem it has no business knowing about — the extraction of `src/host/`
+ * out of `src/widgets/` is what surfaced that, since the type was sitting in
+ * `widgets/types.ts` and the host seam was importing it from there.
+ */
+export type Unsubscribe = () => void;

package/dist/core/subscription.js

@@ -0,0 +1,12 @@
+/**
+ * Unsubscribe — the shape every `on…()` in this library hands back.
+ *
+ * [LAW:decomposition] It lives in `core/` because two subsystems that must not
+ * depend on each other both need it: `host/` returns one from `onData` and
+ * `onResize`, `widgets/` returns one from `onChange`, `onSubmit`, `onKey` and
+ * `onMouse`. Either home above this tier would make the other import a
+ * subsystem it has no business knowing about — the extraction of `src/host/`
+ * out of `src/widgets/` is what surfaced that, since the type was sitting in
+ * `widgets/types.ts` and the host seam was importing it from there.
+ */
+export {};

package/dist/core/text.d.ts

@@ -0,0 +1,283 @@
+/**
+ * RichText — styled text with spans. The primary text type for the library.
+ */
+import { Segment } from "./segment.js";
+import { Style, type TextStyle } from "./style.js";
+import type { Renderable, Measurable, OverflowMethod, RenderOptions } from "./protocol.js";
+export declare function stripControlChars(text: string): string;
+/**
+ * The style a stored `TextStyle` stands for in this render.
+ *
+ * A parsed string can carry a link, so the result is sanitized on the way out
+ * as well.
+ */
+export declare function resolveStyle(options: RenderOptions, style: TextStyle): Style;
+export declare class Span {
+    readonly start: number;
+    readonly end: number;
+    readonly style: TextStyle;
+    constructor(start: number, end: number, style: TextStyle);
+    get hasLength(): boolean;
+    toString(): string;
+    split(offset: number): [Span, Span | undefined];
+    move(delta: number): Span;
+    rightCrop(offset: number): Span;
+    extend(count: number): Span;
+}
+export interface RichTextOptions {
+    style?: TextStyle;
+    justify?: "left" | "center" | "right" | "full";
+    overflow?: OverflowMethod;
+    end?: string;
+    tabSize?: number;
+    noWrap?: boolean;
+}
+export declare class RichText implements Renderable, Measurable {
+    private _text;
+    private _spans;
+    private _style;
+    private _justify;
+    private _overflow;
+    private _end;
+    private _tabSize;
+    private _noWrap;
+    constructor(text?: string, options?: RichTextOptions);
+    get plain(): string;
+    set plain(value: string);
+    get length(): number;
+    /**
+     * The cells of the plain text with each tab widened to its stop counted from
+     * this text's own column 0, as `render` widens it — so it is the drawn width
+     * of a one-line text set at a stop. A deliberate departure from Rich, whose
+     * `Text.cell_len` counts a tab as no cells, so everything sized by it — a
+     * truncation, an alignment, a header's remaining width — decided on a width
+     * no render draws.
+     */
+    get cellLength(): number;
+    get hasContent(): boolean;
+    /** The base style every span layers over, resolved at render unless it is a `Style`. */
+    get style(): TextStyle;
+    set style(value: TextStyle);
+    get justify(): "left" | "center" | "right" | "full" | undefined;
+    set justify(value: "left" | "center" | "right" | "full" | undefined);
+    get overflow(): OverflowMethod | undefined;
+    set overflow(value: OverflowMethod | undefined);
+    get end(): string;
+    set end(value: string);
+    get noWrap(): boolean;
+    set noWrap(value: boolean);
+    get spans(): readonly Span[];
+    /**
+     * This text's own style, spans aside, as the render drawing it resolves it.
+     * A name the render's theme does not define resolves to no style, because
+     * text forgives a missing name.
+     */
+    resolvedStyle(options: RenderOptions): Style;
+    /**
+     * The style of the cell-column at the named edge — base style merged with
+     * any spans covering the leftmost (side="left") or rightmost (side="right")
+     * character.
+     *
+     * [LAW:locality-or-seam] Used by `Joiner`s to paint the transition between
+     * adjacent `Strip` items. Joiners only ever need the column adjacent to
+     * them, so the cell type exposes that column rather than constraining its
+     * interior to be uniform. For RichText with uniform styling, both edges
+     * return the same style; for RichText with edge variation, each edge
+     * accurately reports the column the joiner actually meets.
+     *
+     * Position is by character index (not cell column). For wide-character
+     * text, the last character occupies the rightmost cell column — the bg
+     * of that character covers both columns, so character-index lookup gives
+     * the correct edge color.
+     *
+     * Takes the render's options because the edge is reported as it will be
+     * drawn, and a style name draws as whatever the render's theme says.
+     */
+    edgeStyle(side: "left" | "right", options: RenderOptions): Style;
+    append(content: string | RichText, style?: TextStyle): this;
+    contains(needle: string | RichText): boolean;
+    at(index: number): RichText;
+    slice(start?: number, end?: number): RichText;
+    /**
+     * The one way a span enters this text. [LAW:single-enforcer] An empty style
+     * adds nothing, as the reference's `if style:` has it, and every other style
+     * is admitted as given.
+     */
+    private _addSpan;
+    stylize(style: TextStyle, start?: number, end?: number): this;
+    highlightRegex(pattern: RegExp, style?: TextStyle): number;
+    highlightWords(words: string[], style: TextStyle, options?: {
+        caseSensitive?: boolean;
+    }): number;
+    copy(): RichText;
+    blankCopy(text?: string): RichText;
+    split(separator?: string): RichText[];
+    divide(offsets: number[]): RichText[];
+    rstrip(): this;
+    pad(count: number, char?: string): this;
+    /**
+     * Each tab widened to the next tab stop, in place, as Rich's
+     * `Text.expand_tabs` widens it: spans move with the characters they style, so
+     * the text measures what it will draw.
+     */
+    expandTabs(): this;
+    padLeft(count: number, char?: string): this;
+    padRight(count: number, char?: string): this;
+    setLength(length: number): this;
+    extendStyle(count: number): this;
+    /**
+     * Truncate to a fixed cell-column width, in one of three modes.
+     *
+     * - `mode: "right"` (default) \u2014 drop characters from the right; append
+     *   `marker` (if any) at the cut.
+     * - `mode: "left"` \u2014 drop characters from the left; prepend `marker` at
+     *   the cut.
+     * - `mode: "middle"` \u2014 keep equal halves from both ends; place `marker`
+     *   in the middle.
+     *
+     * Marker default is `"\u2026"`. Pass `marker: ""` for raw cropping without an
+     * 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.
+     * Use `stylize(...)` on the result to color the marker if needed.
+     *
+     * Text that fits comes back untouched. Text that is cut has its tabs widened
+     * to their stops first, as `expandTabs` widens them, so the width cut to is
+     * the width drawn.
+     *
+     * [LAW:dataflow-not-control-flow] mode/marker/width all flow as values;
+     * the walk is the same shape regardless. No "if truncated then rebuild"
+     * branch \u2014 the unchanged path just early-returns when content fits.
+     */
+    truncate(width: number, options?: {
+        mode?: "right" | "left" | "middle";
+        marker?: string;
+    }): this;
+    private _cropRightTo;
+    private _cropLeftTo;
+    align(justify: "left" | "center" | "right", width: number): this;
+    removeSuffix(suffix: string): this;
+    appendTokens(tokens: Array<[string, TextStyle?]>): this;
+    static assemble(parts: Array<string | [string, TextStyle?] | RichText>, options?: {
+        style?: TextStyle;
+    }): RichText;
+    static styled(text: string, style: TextStyle): RichText;
+    /**
+     * Concatenate a sequence of `RichText` fragments into a single `RichText`,
+     * flattening each fragment's wrapping `style` onto a span over that
+     * fragment's range so downstream rendering preserves the original styling.
+     *
+     * Designed for the template engine's `RichText[]` output: a top-level
+     * `{{ 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, 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
+     * trailing newline added by the container).
+     */
+    static fromFragments(fragments: readonly RichText[], options?: {
+        end?: string;
+    }): RichText;
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    /**
+     * The rendered text cut at every span edge, each piece carrying the base
+     * style plus every span covering it.
+     *
+     * Walked span-first rather than piece-first, and that direction is the whole
+     * performance argument. The pieces are cut at the span edges themselves, so
+     * a span covers a piece exactly when it covers the piece's first character —
+     * which makes each span's run of pieces a contiguous range it can be written
+     * into once, instead of a question every piece asks of every span. The
+     * piece-first form charged `spans x pieces`, and the pieces are themselves
+     * cut by the spans, so anything styling densely paid the square in ordinary
+     * use: 8,000 one-character spans took 211ms where 1,000 took 3.2ms. Every
+     * `Highlighter` over a large value reaches that, and so does `Pretty`, whose
+     * indent guides emit a span per indent character.
+     *
+     * Span-first is also what keeps the composition honest, for free. `Style.add`
+     * is order-dependent and the last writer wins, so the pieces have to fold
+     * their styles in `_spans` order — which iterating `_spans` is, and which a
+     * sweep ordered by position would have had to reconstruct.
+     *
+     * [LAW:dataflow-not-control-flow] A span covering nothing — empty, reversed,
+     * or entirely past the text — still cuts the text where its edges land, as it
+     * always did, and then folds into no piece at all: its range comes out empty
+     * and no case handles it.
+     */
+    private _buildSegments;
+    /**
+     * The pieces one logical line wrapped into, each placed in a canvas
+     * `maxWidth` wide, as Rich's `Lines.justify` places them — pinned block for
+     * block against the reference in `test/core/text-justify.test.ts`.
+     *
+     * It is handed the whole wrapped line because `full` is the one mode a
+     * piece cannot answer alone: the reference leaves a paragraph's last line
+     * ragged, so where the piece sits decides its answer where the other three
+     * modes need only the piece itself. The set that decides "last" is this one
+     * and not the whole render — `Text.wrap` calls `Lines.justify` once per
+     * *logical* line — and `Segment.divide` already handed it over whole.
+     */
+    private _justifyLines;
+    /**
+     * One line placed in a canvas `maxWidth` wide.
+     *
+     * Centre and right align on the line's *content*. The whitespace a wrap
+     * leaves on the end of the line it closed is the break's own padding, not
+     * text, and aligning around it pushes the text half a gap off true — a
+     * centred title that wraps drifts left on every line that happens to end in
+     * a space. Left keeps that whitespace, because there it is already on the
+     * side the padding goes.
+     *
+     * `undefined` is not `"left"`: it is Rich's `"default"`, which places the
+     * line without padding it at all. That distinction is what lets a soft-wrapped
+     * `Console.print` leave its lines at their natural width.
+     *
+     * The padding is drawn in the text's base style, as the reference pads
+     * inside the `Text` it justifies: a title "on red" fills its row in red.
+     */
+    private _justifyLine;
+    /**
+     * One line of a wrapped paragraph, its gaps widened until it fills the
+     * canvas — what `justify: "full"` promises, and what the reference's
+     * `Lines.justify` does to every line of a paragraph but the last.
+     *
+     * Slack goes in a cell at a time, starting at the rightmost gap and walking
+     * left, round and round until the line is full. That order is the
+     * reference's own, and what it decides is where an odd cell lands when the
+     * slack will not divide evenly: the right-hand gaps take it.
+     *
+     * The words come from the line's *text* split on a single space, with the
+     * blank a trailing separator leaves behind dropped — `Text.split` and
+     * `String.prototype.split` agree on that list, empty words and all. Two
+     * consequences read as bugs until you know whose they are: a run of n
+     * spaces is n gaps rather than one, so spacing an author widened stretches
+     * instead of collapsing, and the whitespace a wrap left hanging is a gap
+     * like the rest, which is why a filled line does not keep it. Both are
+     * pinned in `text-justify.golden.txt`, by the `uneven` and `sentence`
+     * blocks respectively.
+     */
+    private _fillLine;
+    /**
+     * One wrapped line cut to the canvas.
+     *
+     * 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, 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;
+}