@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/renderables/spinner.js

@@ -8,7 +8,7 @@
  * the interval; the beat, the width every frame draws at and which frame `t`
  * lands on are the frames primitive's, so a spinner is one more sequence on
  * it and not a second way of turning frames. Custom frames are a `FrameSequence`
- * drawn through `Frames` directly. [LAW:one-source-of-truth]
+ * placed directly. [LAW:one-source-of-truth]
  *
  * It is built once and asked for each frame, as Rich's `Spinner` is built
  * once and has `render(time)` called on it: the name is parsed and the
@@ -19,45 +19,47 @@
  * the beat, the width, each frame padded to it — is made there too, so a
  * drawn frame costs only finding which one `t` lands on.
  *
- * [LAW:no-ambient-temporal-coupling] A Spinner draws nothing on its own:
- * only `at(t)` is a renderable, so a spinner cannot be drawn without being
- * handed its time, and nothing here reads a clock. Whoever draws frames
- * hands each one its time (`core/clock.ts`) — `SpinnerColumn` the task's
- * `time`, a `Live` the frame's time on its clock — as Rich's `Spinner.render`
- * is handed `console.get_time()` or `task.get_time()`. `t` is the clock's
- * time, as `App` and `Task.time` hand it, where Rich's spinner counts from
+ * [LAW:no-ambient-temporal-coupling] Placed, a spinner draws at the time of
+ * the frame it is drawn in, and nothing here reads a clock. Whoever draws
+ * frames hands each one its time (`core/clock.ts`) — a `Progress` the
+ * moment its tasks are drawn at, a `Live` the frame's time on its clock — as
+ * Rich's `Spinner.render` is handed `console.get_time()` or `task.get_time()`. `t` is the clock's
+ * time, as a host writes it on the frame, where Rich's spinner counts from
  * its first draw: here nothing is kept between frames, so the same `t` draws
  * the same bytes at one redraw a second or sixty, two spinners on one clock
  * agree at every `t`, a `Progress` on a hand-moved clock turns its spinners
  * on that clock, and a draw costs the same at `t = 0` and `t = 10⁶`.
  *
- * `speed` scales the holds, not the time: at speed 2 each frame is held half
- * the interval, and a negative speed is the frames in reverse order, each held
- * the interval over the speed's size. [LAW:one-source-of-truth] Rich scales
- * the time instead, `t × speed` into the beat. At a positive speed the frame
- * drawn is the same; but when the frame next changes (`Style.nextChange`) is
- * a time on the host's timeline, and a beat over scaled time answers on the
- * scaled one — so the sequence is scaled where it is built, and the
- * `FrameSequence` stamps host time with nothing to map back. Backwards, this is the plain
- * reversed sequence from `t = 0`, where Rich's `int()` truncation holds
- * frame 0 for a first interval and then counts down: a departure, made so a
- * negative speed is one more sequence on the beat and not a second rule
- * about time. A speed of zero would hold a frame forever, which is not a
- * beat, and is refused where it is given.
+ * `speed` is a `Timeline` (`core/timeline.ts`) playing from `t = 0` at
+ * that rate, as Rich scales the time, `t × speed` into the beat: the frames
+ * are held for the interval the data gives, and the spinner is asked for the
+ * frame at the time the timeline maps the host's to. [LAW:one-source-of-truth]
+ * When the frame next changes (`Style.hold`) is a time on the host's
+ * timeline, and the sequence answers on its own, so the timeline carries the
+ * answer back. `at` hands over the frame alone, as every animation's does;
+ * placed, a spinner draws at the frame's time and stamps its cells with that
+ * answer for the frames the output draws. Backwards, the frames count down from the last at `t = 0`,
+ * a negative time landing in the last frame of the pass before, where Rich's
+ * `int()` truncation holds frame 0 for a first interval and then counts
+ * down: a departure, made so a negative speed is the one timeline run
+ * backwards and not a second rule about time. A speed of zero would hold a
+ * frame forever, which a paused timeline is and a rate is not, and the
+ * timeline refuses it.
  */
+import { Animation, frameTimeOf, holdOf, shownAt, stampFrame } from "../core/animation.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 } from "../core/protocol.js";
+import { Timeline } from "../core/timeline.js";
+import { drawable, measure, render } from "../core/protocol.js";
 import { EmbeddedText } from "./embed.js";
 import { FrameSequence } from "./frames.js";
-const sequence = (data, style, speed) => {
-    const frames = data.frames.map((frame) => ({
-        text: new RichText("", { end: "" }).append(frame, style),
-        seconds: data.interval / 1000 / Math.abs(speed),
-    }));
-    return { frames: new FrameSequence(speed < 0 ? frames.reverse() : frames), glyphs: data.frames.join("") };
+import { finiteTime } from "../core/easing.js";
+import { State } from "../core/state.js";
+const sequence = (data, style, timeline) => {
+    const frames = new FrameSequence(data.frames.map((frame) => ({ text: new RichText("", { end: "" }).append(frame, style), seconds: data.interval / 1000 })));
+    return { frames, played: Timeline.run(timeline, frames), glyphs: data.frames.join("") };
 };
 const sequenceGlyphs = ({ glyphs }) => glyphs;
 export class Spinner {
@@ -71,12 +73,26 @@ export class Spinner {
      * whatever the console says — and a `RichText` changed in place draws as
      * changed, as the `Text` Rich keeps does. [LAW:single-enforcer]
      */
-    text;
+    get text() {
+        return this._text.get();
+    }
+    set text(value) {
+        this._text.set(value);
+    }
+    // Rich's `Spinner.update` sets the text after it is built.
+    _text;
     _data;
     // The named data's frames, and the `line` spinner's that stand in for them
     // on an ASCII-only output: prepared once, which is drawn chosen at `at`.
     _named;
     _ascii;
+    /**
+     * The spinner drawn at the frame's time, its cells saying the hold it is in
+     * on the host's clock (`stampFrame`) — exactly, for the frames the output
+     * draws, where `nextChange` must answer for both. Under reduced motion it
+     * is the spinner reduced, which never turns (`shownAt`).
+     */
+    _placed;
     constructor(name, text = "", options) {
         const spinnerName = name ?? DEFAULT_SPINNER;
         const data = SPINNERS[spinnerName];
@@ -84,18 +100,21 @@ export class Spinner {
             throw new Error(`Unknown spinner: "${spinnerName}"`);
         }
         const speed = options?.speed ?? 1;
-        // [LAW:parse-dont-validate] A hold is a positive number of seconds, so the
-        // speed it is divided by is finite and not zero, settled here.
-        if (!Number.isFinite(speed) || speed === 0) {
-            throw new RangeError(`Spinner speed must be finite and not zero, got ${speed}`);
-        }
+        // [LAW:single-enforcer] A rate is finite and not zero, and the timeline
+        // refuses one that is not where it is built.
+        const timeline = Timeline.play(0, speed);
         this.name = spinnerName;
-        this.text = text;
+        this._text = new State(text);
         this.speed = speed;
         this.style = options?.style ?? NULL_STYLE;
         this._data = data;
-        this._named = sequence(data, this.style, speed);
-        this._ascii = sequence(LINE_SPINNER, this.style, speed);
+        this._named = sequence(data, this.style, timeline);
+        this._ascii = sequence(LINE_SPINNER, this.style, timeline);
+        this._placed = this._frame((played, options) => {
+            const t = frameTimeOf(options);
+            const shown = shownAt(played, t, options);
+            return { value: shown.value, hold: holdOf(shown, t) };
+        });
     }
     get frames() {
         return this._data.frames;
@@ -109,27 +128,59 @@ export class Spinner {
      * the 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.
      * The frames this output can draw are chosen where the output is known.
+     * The frame says nothing of when it turns — `t` may be a time a timeline
+     * mapped — so placed, the spinner itself stamps it.
      */
     at(t) {
-        if (!Number.isFinite(t)) {
-            throw new RangeError(`Spinner.at needs a finite t, got ${t}`);
-        }
-        const frames = (options) => drawable(options, this._named, this._ascii, sequenceGlyphs).frames;
+        finiteTime("Spinner.at", t);
+        return this._frame((played) => ({ value: played.at(t) }));
+    }
+    /** The spinner with its motion taken out: its first frame and the label, which never turn, so any time answers. */
+    reduced() {
+        return Animation.constant(this._frame((played) => ({ value: played.reduced().at(0) })));
+    }
+    render(options) {
+        return render(this._placed, options);
+    }
+    measure(options) {
+        return measure(this._placed, options);
+    }
+    /** The frame `choose` picks from the frames the output can draw, and the label, saying the hold it is in if `choose` says. */
+    _frame(choose) {
+        const drawn = (options) => drawable(options, this._named, this._ascii, sequenceGlyphs);
         return {
-            render: (options) => this._render(frames(options), t, options),
+            render: (options) => {
+                const { value, hold } = choose(drawn(options).played, options);
+                const segments = this._render(value, options);
+                return hold === undefined ? segments : stampFrame(segments, hold);
+            },
             // Measured at the frames' one width, the widest frame's, 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 drawn = frames(options);
-                const { minimum, maximum } = this._line(drawn, t, options).measure(options);
-                return { minimum: Math.max(minimum, Math.min(drawn.width, maximum)), maximum };
+                const { frames, played } = drawn(options);
+                const { minimum, maximum } = measure(this._line(choose(played, options).value, options), options);
+                return { minimum: Math.max(minimum, Math.min(frames.width, maximum)), maximum };
             },
         };
     }
-    *_render(frames, t, options) {
-        yield* this._line(frames, t, options).render(options);
+    /**
+     * When the spinner drawn at `t` next turns, on the host's clock: the
+     * sooner of its two sequences' answers, since which one is drawn is the
+     * output's to choose and the line spinner that stands in on an ASCII-only
+     * output keeps its own interval. An early answer, on the output that draws
+     * the other one, which the contract allows; the drawn cells carry the exact one.
+     */
+    nextChange(t) {
+        return Math.min(this._named.played.nextChange(t), this._ascii.played.nextChange(t));
+    }
+    /** When the spinner drawn at `t` began to be drawn: the later of its two sequences' answers, by the same argument. */
+    lastChange(t) {
+        return Math.max(this._named.played.lastChange(t), this._ascii.played.lastChange(t));
+    }
+    *_render(frame, options) {
+        yield* render(this._line(frame, options), options);
         yield Segment.line();
     }
     /**
@@ -139,8 +190,9 @@ export class Spinner {
      * styles nothing — is no label, not a trailing space, as an empty `Text` is
      * falsy there.
      */
-    _line(frames, t, options) {
-        const line = new RichText("", { end: "" }).append(frames.text(t));
+    _line(frame, options) {
+        // The frame alone, saying nothing of when it turns: placed, the spinner stamps it.
+        const line = new RichText("", { end: "" }).append(frame);
         // 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 !== "")

package/dist/renderables/status.js

@@ -20,7 +20,7 @@ export class Status {
             speed: options?.speed,
             style: options?.spinnerStyle ?? "status.spinner",
         });
-        this._live = new Live((t) => this._spinner.at(t), {
+        this._live = new Live(this._spinner, {
             console: this._console,
             clock: options?.clock,
             transient: true,

package/dist/renderables/syntax.d.ts

@@ -9,11 +9,12 @@
  */
 import { Segment } from "../core/segment.js";
 import { type Measurable, type Renderable, type RenderOptions } from "../core/protocol.js";
+import { type Pattern } from "../core/pattern.js";
 export interface SyntaxOptions {
     lineNumbers?: boolean;
     startLine?: number;
-    lineRange?: [number, number];
-    highlightLines?: Set<number>;
+    lineRange?: readonly [number, number];
+    highlightLines?: ReadonlySet<number>;
     wordWrap?: boolean;
     tabSize?: number;
 }
@@ -24,11 +25,11 @@ export interface SyntaxOptions {
  * render; `"text"` is the grammar with no rules.
  */
 declare const GRAMMARS: {
-    javascript: RegExp;
-    typescript: RegExp;
-    python: RegExp;
-    bash: RegExp;
-    text: RegExp;
+    readonly javascript: Pattern;
+    readonly typescript: Pattern;
+    readonly python: Pattern;
+    readonly bash: Pattern;
+    readonly text: Pattern;
 };
 export type SyntaxLanguage = keyof typeof GRAMMARS;
 export declare class Syntax implements Renderable, Measurable {
@@ -36,8 +37,8 @@ export declare class Syntax implements Renderable, Measurable {
     readonly language: SyntaxLanguage;
     readonly lineNumbers: boolean;
     readonly startLine: number;
-    readonly lineRange: [number, number] | undefined;
-    readonly highlightLines: Set<number>;
+    readonly lineRange: readonly [number, number] | undefined;
+    readonly highlightLines: ReadonlySet<number>;
     readonly wordWrap: boolean;
     readonly tabSize: number;
     /** The code with its tabs expanded, as lines — what both render and measure read. */

package/dist/renderables/syntax.js

@@ -11,6 +11,8 @@ import { cellLen, expandTabs, parseTabSize } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";
 import { drawable, groundedStyle, getStyle, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+import { render } from "../core/protocol.js";
+import { pattern } from "../core/pattern.js";
 /**
  * One regex per grammar, each token a named alternative. A single left-to-right
  * scan is what keeps a `//` inside a string from starting a comment, and a
@@ -19,7 +21,7 @@ import { drawable, groundedStyle, getStyle, withBoundedWidth, withCellWidth, } f
  * `(?!)` never matches, so a grammar with no rules is still a regex.
  */
 function grammar(rules) {
-    return new RegExp([...rules.map(([token, source]) => `(?<${token}>${source})`), "(?!)"].join("|"), "g");
+    return pattern(new RegExp([...rules.map(([token, source]) => `(?<${token}>${source})`), "(?!)"].join("|")));
 }
 // Not after a `.`: `map.get` and `node.type` are properties, not keywords.
 const words = (list) => `(?<!\\.)\\b(?:${list.split(" ").join("|")})\\b`;
@@ -119,7 +121,7 @@ export class Syntax {
         // Tokenized whole and then sliced, so a block comment or a triple-quoted
         // string that spans lines is one token even when the range starts inside it.
         const text = new RichText(this._lines.join("\n"), { end: "" });
-        for (const match of text.plain.matchAll(GRAMMARS[this.language])) {
+        for (const match of text.plain.matchAll(new RegExp(GRAMMARS[this.language].source, "g"))) {
             const [token] = Object.entries(match.groups).find(([, value]) => value !== undefined);
             text.stylize(`syntax.${token}`, match.index, match.index + match[0].length);
         }
@@ -140,7 +142,7 @@ export class Syntax {
             const lineNo = first + i;
             const style = this.highlightLines.has(lineNo) ? highlightStyle : numberStyle;
             // Terminated, so an empty line is one empty row rather than none.
-            const rows = Segment.splitLines([...textLines[i].render(lineOptions), Segment.line()]);
+            const rows = Segment.splitLines([...render(textLines[i], lineOptions), Segment.line()]);
             for (let row = 0; row < rows.length; row++) {
                 if (this.lineNumbers) {
                     // A wrapped line's continuation rows keep the gutter, unnumbered.

package/dist/renderables/table.d.ts

@@ -9,40 +9,39 @@ import type { PaddingDimensions } from "./padding.js";
 import type { Renderable, Measurable, OverflowMethod, RenderOptions } from "../core/protocol.js";
 export interface ColumnOptions {
     /** Anything a cell can hold, as Rich's `RenderableType` header is. */
-    header?: string | RichText | Renderable;
-    footer?: string | RichText | Renderable;
-    headerStyle?: string | Style;
-    footerStyle?: string | Style;
-    style?: string | Style;
-    justify?: "left" | "center" | "right" | "full";
-    width?: number;
-    minWidth?: number;
-    maxWidth?: number;
-    ratio?: number;
-    noWrap?: boolean;
-    overflow?: OverflowMethod;
+    readonly header?: string | RichText | Renderable;
+    readonly footer?: string | RichText | Renderable;
+    readonly headerStyle?: string | Style;
+    readonly footerStyle?: string | Style;
+    readonly style?: string | Style;
+    readonly justify?: "left" | "center" | "right" | "full";
+    readonly width?: number;
+    readonly minWidth?: number;
+    readonly maxWidth?: number;
+    readonly ratio?: number;
+    readonly noWrap?: boolean;
+    readonly overflow?: OverflowMethod;
     /**
      * Whether the column's string cells — its header and footer among them — are
      * drawn with the console's highlighter, as Rich's `Column(highlight=)`.
      * `false` for a `Column` built alone; `addColumn` takes the table's.
      */
-    highlight?: boolean;
+    readonly highlight?: boolean;
 }
 export declare class Column {
-    private _header;
-    private _footer;
-    headerStyle: string | Style;
-    footerStyle: string | Style;
-    style: string | Style;
-    justify: "left" | "center" | "right" | "full";
-    width: number | undefined;
-    minWidth: number | undefined;
-    maxWidth: number | undefined;
-    ratio: number | undefined;
-    noWrap: boolean;
-    overflow: OverflowMethod;
-    highlight: boolean;
-    private _cells;
+    private readonly _header;
+    private readonly _footer;
+    readonly headerStyle: string | Style;
+    readonly footerStyle: string | Style;
+    readonly style: string | Style;
+    readonly justify: "left" | "center" | "right" | "full";
+    readonly width: number | undefined;
+    readonly minWidth: number | undefined;
+    readonly maxWidth: number | undefined;
+    readonly ratio: number | undefined;
+    readonly noWrap: boolean;
+    readonly overflow: OverflowMethod;
+    readonly highlight: boolean;
     constructor(options?: ColumnOptions);
     /**
      * The two stamped cells, stamped on assignment rather than at the constructor.
@@ -66,10 +65,6 @@ export declare class Column {
     get footer(): Renderable & Partial<Measurable>;
     set footer(content: ColumnOptions["footer"]);
     get flexible(): boolean;
-    /** @internal */
-    addCell(cell: Renderable): void;
-    /** @internal */
-    getCells(): Renderable[];
     copy(): Column;
 }
 export interface TableOptions {
@@ -94,13 +89,13 @@ export interface TableOptions {
     captionJustify?: "left" | "center" | "right" | "full";
     width?: number;
     minWidth?: number;
-    rowStyles?: string[];
+    rowStyles?: readonly string[];
     /** The `highlight` every column `addColumn` makes takes unless told otherwise (default: `false`). */
     highlight?: boolean;
 }
 export declare class Table implements Renderable, Measurable {
-    private _columns;
-    private _rows;
+    private readonly _columns;
+    private readonly _rows;
     readonly box: Box | null;
     private readonly _title;
     private readonly _caption;
@@ -109,7 +104,7 @@ export declare class Table implements Renderable, Measurable {
     readonly showFooter: boolean;
     readonly showLines: boolean;
     readonly showEdge: boolean;
-    readonly padding: [number, number, number, number];
+    readonly padding: readonly [number, number, number, number];
     readonly collapsePadding: boolean;
     readonly padEdge: boolean;
     readonly style: string | Style;
@@ -122,12 +117,12 @@ export declare class Table implements Renderable, Measurable {
     readonly captionJustify: "left" | "center" | "right" | "full";
     readonly tableWidth: number | undefined;
     readonly minWidth: number | undefined;
-    readonly rowStyles: string[];
+    readonly rowStyles: readonly string[];
     readonly highlight: boolean;
     get title(): (Renderable & Measurable) | undefined;
     get caption(): (Renderable & Measurable) | undefined;
     constructor(options?: TableOptions);
-    get columns(): Column[];
+    get columns(): readonly Column[];
     get rowCount(): number;
     addColumn(header?: ColumnOptions["header"], options?: ColumnOptions): this;
     addRow(...cells: unknown[]): this;
@@ -183,8 +178,11 @@ export declare class Table implements Renderable, Measurable {
      * mode gets its own path through the width division.
      *
      * Cells are measured against the width left once the frame is paid, as the
-     * reference's `_measure_column` measures them. Padding and the floor are laid
-     * over whichever sizing the column has: they are the same for all three.
+     * reference's `_measure_column` measures them. Padding is part of every
+     * width the demand names, because the reference measures a cell wrapped in
+     * its `Padding`, and each sizing adds it where the reference does — a
+     * rowless column's minimum is the one width it never reaches. The floor is
+     * laid over whichever sizing the column has.
      */
     private _columnDemands;
     private _columnSizing;
@@ -198,6 +196,7 @@ export declare class Table implements Renderable, Measurable {
      */
     private _columnPadding;
     private _rowPadding;
+    private _rowCells;
     /**
      * Every cell column `index` draws, in draw order.
      *
@@ -211,19 +210,22 @@ export declare class Table implements Renderable, Measurable {
      */
     private _columnCells;
     /**
-     * The widest any cell in a column draws, and the narrowest the column can be
-     * without cutting one — the reference's `_measure_column` — or `undefined`
-     * when the column has no cell to measure. Zero is a column whose cells draw
-     * nothing — a gutter asks for its padding and nothing else — and is not the
-     * same answer. [LAW:types-are-the-program]
+     * The widest any cell in a column draws, its padding included, and the
+     * narrowest the column can be without cutting one — the reference's
+     * `_measure_column` — or `undefined` when the column has no cell to measure.
+     * A column whose cells draw nothing measures its padding — a gutter asks for
+     * that and nothing else — which is not the same answer.
+     * [LAW:types-are-the-program]
      */
     private _cellRange;
     /**
-     * A natural width held to the column's own `minWidth`/`maxWidth`.
+     * A natural width held to the column's own `minWidth`/`maxWidth`, each
+     * widened by the column's `pad`, as the reference clamps a padded
+     * measurement to `min_width + padding_width`.
      *
      * A bound is a count of cells, read by the rule every width is read by: NaN
      * and a negative are zero cells, so a NaN floor bounds nothing and a NaN
-     * ceiling is a ceiling of zero, as `width: NaN` is. A bare `Math.max` returns
+     * ceiling holds the column to its padding alone, as `width: NaN` does. A bare `Math.max` returns
      * NaN instead, and the column vanishes. [LAW:one-source-of-truth]
      */
     private _bounded;