@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/renderables/progressBar.js

@@ -5,9 +5,10 @@ import { cellCount } from "../core/cells.js";
 import { ColorDepth, ColorRgba, ColorSpec, resolveTerminal } from "../core/color.js";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
-import { drawable, getStyle } from "../core/protocol.js";
+import { drawable, getStyle, render } from "../core/protocol.js";
 import { Effected } from "./effect.js";
 import { EFFECT_CURVES, atShares, shimmer } from "./effects.js";
+import { State } from "../core/state.js";
 const BAR = "━";
 const ASCII_BAR = "-";
 const HALF_BAR_RIGHT = "╸";
@@ -22,27 +23,49 @@ const PULSE_REACH = 10;
 /** Rich's pulse back where the back style names no colour. */
 const PULSE_BACK = ColorSpec.fromRgba(new ColorRgba(0, 0, 0));
 export class ProgressBar {
-    total;
-    completed;
+    // Rich's ProgressBar is updated after it is built: `bar.completed = n`.
+    _total;
+    _completed;
+    _finished;
     width;
     pulse;
     style;
     completeStyle;
     finishedStyle;
     constructor(options) {
-        this.total = options?.total ?? 100;
-        this.completed = options?.completed ?? 0;
+        this._total = new State(options?.total ?? 100);
+        this._completed = new State(options?.completed ?? 0);
         this.width = options?.width;
-        this.pulse = options?.pulse;
+        this.pulse = options?.pulse ?? false;
+        this._finished = new State(options?.finished);
         this.style = options?.style ?? "bar.back";
         this.completeStyle = options?.completeStyle ?? "bar.complete";
         this.finishedStyle = options?.finishedStyle ?? "bar.finished";
     }
+    get total() {
+        return this._total.get();
+    }
+    set total(value) {
+        this._total.set(value);
+    }
+    get completed() {
+        return this._completed.get();
+    }
+    set completed(value) {
+        this._completed.set(value);
+    }
+    /** Whether the work is done, as given; unset, `completed` reaching `total` at the moment the bar is drawn. */
+    get finished() {
+        return this._finished.get();
+    }
+    set finished(value) {
+        this._finished.set(value);
+    }
     *render(options) {
         // Never wider than offered, as Rich's `min(self.width or max_width, max_width)`.
         // [LAW:parse-dont-validate] parsed as a cell count, so a negative width draws nothing, as Python's `"━" * -2` is "".
         const width = cellCount(Math.min(this.width || options.maxWidth, options.maxWidth));
-        if (this.pulse === undefined) {
+        if (!this.pulse) {
             yield* this.track(options, width, this.completeHalves(width), getStyle(options, this.style));
             return;
         }
@@ -56,10 +79,10 @@ export class ProgressBar {
         const style = getStyle(options, this.style);
         const ink = style.color?.isDefault === false ? style.color : ColorSpec.fromRgba((style.color ?? PULSE_BACK).getTruecolor(theme, true));
         const back = style.add(Style.fromColor(ink));
-        // [LAW:no-ambient-temporal-coupling] The moment is the caller's; the bar
+        // [LAW:no-ambient-temporal-coupling] The moment is the frame's; the bar
         // only says what it looks like then. An empty track, lit by the shimmer.
         const track = { render: (o) => this.track(o, width, 0, back) };
-        yield* new Effected(track, this.pulseEffect(options, back, depth, theme), { t: this.pulse.t, key: "progress-bar", theme }).render(options);
+        yield* render(new Effected(track, this.pulseEffect(options, back, depth, theme), { key: "progress-bar", theme }), options);
     }
     /**
      * The shimmer over this bar's back colour as `Effected` sees it drawn at
@@ -82,7 +105,7 @@ export class ProgressBar {
     *track(options, width, completeHalves, back) {
         const barCount = Math.floor(completeHalves / 2);
         const halfBarCount = completeHalves % 2;
-        const isFinished = this.completed >= this.total;
+        const isFinished = this.finished ?? this.completed >= this.total;
         const fill = getStyle(options, isFinished ? this.finishedStyle : this.completeStyle);
         const fillStyle = fill.isNull ? undefined : fill;
         const backStyle = back.isNull ? undefined : back;

package/dist/renderables/prompt.js

@@ -24,6 +24,7 @@
 import { Console } from "../core/console.js";
 import { renderMarkup } from "../core/markup.js";
 import { RichText } from "../core/text.js";
+import { pattern } from "../core/pattern.js";
 /** An answer the prompt refused, and the markup it prints before asking again — Rich's `InvalidResponse`. */
 class InvalidResponse {
     message;
@@ -104,10 +105,10 @@ function responseKind(convert, invalid, options) {
     };
 }
 /** Python's `int()` over a string: a sign, then digits, any two of which may have one `_` between them. */
-const INTEGER = /^[+-]?\d(?:_?\d)*$/;
+const INTEGER = pattern(/^[+-]?\d(?:_?\d)*$/);
 const DIGITS = String.raw `\d(?:_?\d)*`;
 /** Python's `float()` over a string: a decimal with an optional exponent, or `inf`, `infinity` or `nan`, in any case. */
-const FLOAT = new RegExp(String.raw `^[+-]?(?:(?:${DIGITS}(?:\.(?:${DIGITS})?)?|\.${DIGITS})(?:e[+-]?${DIGITS})?|inf(?:inity)?|nan)$`, "i");
+const FLOAT = pattern(new RegExp(String.raw `^[+-]?(?:(?:${DIGITS}(?:\.(?:${DIGITS})?)?|\.${DIGITS})(?:e[+-]?${DIGITS})?|inf(?:inity)?|nan)$`, "i"));
 /**
  * The integer an answer spells, as Python's `int()` reads it, or none. One a
  * `number` cannot hold exactly is none: Python's int is unbounded and a

package/dist/renderables/python-space.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Whitespace as Python reads it — `str.isspace`, `str.strip`, and `\s` in a
+ * `str` pattern of `re`, which are one set. markdown-it-py, the markdown-it
+ * Rich runs, reads whitespace through all three, and that set is not
+ * JavaScript's: `\s` and `trim` take U+FEFF, which Python does not, and leave
+ * U+001C–U+001F and U+0085, which Python takes.
+ */
+/** The set as a regex character class, every member of it a single UTF-16 unit, for composing into a pattern where markdown-it-py's has `\s`. */
+export declare const PY_WHITESPACE: string;
+/** Python's `str.strip`, a scan in from each end, so a run of interior whitespace costs one pass, as it does there. */
+export declare function pyStrip(text: string): string;
+/** Python's `str.rstrip`, a scan in from the end — not a `+$` pattern, which retries from every cell of an interior run. */
+export declare function pyRstrip(text: string): string;

package/dist/renderables/python-space.js

@@ -0,0 +1,25 @@
+/**
+ * Whitespace as Python reads it — `str.isspace`, `str.strip`, and `\s` in a
+ * `str` pattern of `re`, which are one set. markdown-it-py, the markdown-it
+ * Rich runs, reads whitespace through all three, and that set is not
+ * JavaScript's: `\s` and `trim` take U+FEFF, which Python does not, and leave
+ * U+001C–U+001F and U+0085, which Python takes.
+ */
+import { pattern } from "../core/pattern.js";
+/** The set as a regex character class, every member of it a single UTF-16 unit, for composing into a pattern where markdown-it-py's has `\s`. */
+export const PY_WHITESPACE = String.raw `[\t-\r\x1c-\x20\x85\xa0  - 

  　]`;
+const PY_SPACE = pattern(new RegExp(`^${PY_WHITESPACE}$`));
+/** Python's `str.strip`, a scan in from each end, so a run of interior whitespace costs one pass, as it does there. */
+export function pyStrip(text) {
+    let start = 0;
+    while (start < text.length && PY_SPACE.test(text[start]))
+        start++;
+    return pyRstrip(text.slice(start));
+}
+/** Python's `str.rstrip`, a scan in from the end — not a `+$` pattern, which retries from every cell of an interior run. */
+export function pyRstrip(text) {
+    let end = text.length;
+    while (end > 0 && PY_SPACE.test(text[end - 1]))
+        end--;
+    return text.slice(0, end);
+}

package/dist/renderables/scroll.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Scroll — a slot of fixed size over content wider or taller than it, the
+ * content's offset in the slot moving with time: a long line panning as a
+ * marquee, a log tail scrolling, a panel sliding into its place.
+ *
+ * [LAW:one-type-per-behavior] A marquee, a scroll and a slide are one window
+ * and differ only in the motion handed in: the offset along each axis is an
+ * `Animation<number>`, so a marquee is a looping `Phase` scaled to the span
+ * it crosses and a slide-in is a `tween` to 0, and when the window next
+ * changes is `Animation.all`'s answer over the two. Nothing here knows which
+ * one it is drawing.
+ *
+ * The slot is what the window is. It measures as its width whatever the
+ * content, and draws exactly its rows of its width at every offset — cropped
+ * only to a narrower room it is given — so what sits beside it never moves.
+ * An offset before or past the content shows blank cells rather than stopping
+ * at an edge: that is what lets a marquee enter from the right and a slide-in
+ * arrive from outside the slot.
+ *
+ * The content is drawn at its own natural width and no height, its own
+ * length, because the content wider and taller than the slot is the thing
+ * being windowed. Content that should wrap to the slot instead, or that has
+ * no natural width because it fills whatever it is given, is
+ * `new Constrain(content, width)`, composed rather than asked for.
+ *
+ * [LAW:single-enforcer] A row is cut at the window's edges by
+ * `Segment.divide`, the one place a line is cut at a column: a wide glyph a
+ * cut falls in is blanked, never halved, and each cell's anchor still names
+ * its column in the content, so hit-testing finds the owner through a moving
+ * window.
+ *
+ * [LAW:no-ambient-temporal-coupling] Pure in `t`, nothing kept between
+ * frames; `at` hands over the frame alone, and placed, the scroll stamps
+ * the hold it is in at the frame's time (`placedRender`).
+ */
+import { Animation } from "../core/animation.js";
+import type { Renderable } from "../core/protocol.js";
+/** The slot a scroll draws, and how far the content is moved in it. */
+export interface ScrollOptions {
+    /** The slot's width in cells. */
+    readonly width: number;
+    /** The slot's height in rows. */
+    readonly height: number;
+    /** Columns of content left of the slot's first, rounded to the nearest cell: negative moves the content right. Absent, 0. */
+    readonly col?: Animation<number>;
+    /** Rows of content above the slot's first, rounded to the nearest row: negative moves the content down. Absent, 0. */
+    readonly row?: Animation<number>;
+}
+/** `content` seen through a slot of `width` by `height` cells, moved in it by `col` and `row` at each moment. */
+export declare function scroll(content: Renderable, options: ScrollOptions): Animation<Renderable>;

package/dist/renderables/scroll.js

@@ -0,0 +1,106 @@
+/**
+ * Scroll — a slot of fixed size over content wider or taller than it, the
+ * content's offset in the slot moving with time: a long line panning as a
+ * marquee, a log tail scrolling, a panel sliding into its place.
+ *
+ * [LAW:one-type-per-behavior] A marquee, a scroll and a slide are one window
+ * and differ only in the motion handed in: the offset along each axis is an
+ * `Animation<number>`, so a marquee is a looping `Phase` scaled to the span
+ * it crosses and a slide-in is a `tween` to 0, and when the window next
+ * changes is `Animation.all`'s answer over the two. Nothing here knows which
+ * one it is drawing.
+ *
+ * The slot is what the window is. It measures as its width whatever the
+ * content, and draws exactly its rows of its width at every offset — cropped
+ * only to a narrower room it is given — so what sits beside it never moves.
+ * An offset before or past the content shows blank cells rather than stopping
+ * at an edge: that is what lets a marquee enter from the right and a slide-in
+ * arrive from outside the slot.
+ *
+ * The content is drawn at its own natural width and no height, its own
+ * length, because the content wider and taller than the slot is the thing
+ * being windowed. Content that should wrap to the slot instead, or that has
+ * no natural width because it fills whatever it is given, is
+ * `new Constrain(content, width)`, composed rather than asked for.
+ *
+ * [LAW:single-enforcer] A row is cut at the window's edges by
+ * `Segment.divide`, the one place a line is cut at a column: a wide glyph a
+ * cut falls in is blanked, never halved, and each cell's anchor still names
+ * its column in the content, so hit-testing finds the owner through a moving
+ * window.
+ *
+ * [LAW:no-ambient-temporal-coupling] Pure in `t`, nothing kept between
+ * frames; `at` hands over the frame alone, and placed, the scroll stamps
+ * the hold it is in at the frame's time (`placedRender`).
+ */
+import { Animation } from "../core/animation.js";
+import { Measurement } from "../core/measure.js";
+import { render, withBoundedWidth } from "../core/protocol.js";
+import { Segment } from "../core/segment.js";
+const NO_OFFSET = Animation.constant(0);
+/** `content` seen through a slot of `width` by `height` cells, moved in it by `col` and `row` at each moment. */
+export function scroll(content, options) {
+    const { width, height, col = NO_OFFSET, row = NO_OFFSET } = options;
+    for (const [name, n] of [["width", width], ["height", height]]) {
+        if (!(Number.isInteger(n) && n > 0))
+            throw new RangeError(`scroll: ${name} must be a positive whole number of cells, got ${n}`);
+    }
+    return Animation.map(Animation.all([col, row]), ([c, r]) => new ScrollFrame(content, width, height, cells("col", c), cells("row", r)));
+}
+/** `offset` rounded to the nearest cell. [LAW:no-silent-failure] One that is not finite has no cell to move to, and says so rather than drawing a blank slot. */
+function cells(name, offset) {
+    if (!Number.isFinite(offset))
+        throw new RangeError(`scroll: ${name} must be a finite number of cells, got ${offset}`);
+    return Math.round(offset);
+}
+/**
+ * The width `content` is drawn at: its own natural one. [LAW:no-silent-failure]
+ * Content that takes whatever width it is offered — a `Rule`, a renderable
+ * with no `measure` — has none, and is refused by name rather than drawn at
+ * an unbounded width it cannot fill.
+ */
+function naturalWidth(content, options) {
+    const natural = Measurement.get({ ...options, maxWidth: Number.POSITIVE_INFINITY }, content).maximum;
+    if (!Number.isFinite(natural)) {
+        throw new RangeError("scroll: the content has no natural width — it fills whatever width it is given; give it one with new Constrain(content, width)");
+    }
+    return natural;
+}
+/** One frame of a scroll: `content`'s cells from column `col` and row `row`, `width` by `height` of them, blank where it has none. */
+class ScrollFrame {
+    content;
+    width;
+    height;
+    col;
+    row;
+    constructor(content, width, height, col, row) {
+        this.content = content;
+        this.width = width;
+        this.height = height;
+        this.col = col;
+        this.row = row;
+    }
+    *render(rawOptions) {
+        const options = withBoundedWidth(rawOptions, this);
+        // The slot is cropped to the room it is given, as a `Panel` of a declared width is.
+        const width = Math.min(this.width, options.maxWidth);
+        const drawn = [...render(this.content, { ...options, maxWidth: naturalWidth(this.content, options), height: undefined })];
+        const lines = Segment.splitLines(drawn);
+        const blank = Math.min(width, Math.max(0, -this.col));
+        const start = Math.max(0, this.col);
+        // [LAW:one-source-of-truth] What the window shows is cut from the whole content, so it may change
+        // when anything in the content does — a row above the slot entering pushes every row down, and run
+        // backwards, leaving it pulls them up. The cut throws away the cells that hold rode on, so it is
+        // told to the frame (`RenderOptions.onHold`).
+        options.onHold?.({ lastChange: Segment.lastChange(drawn), nextChange: Segment.nextChange(drawn) });
+        for (let r = 0; r < this.height; r++) {
+            const line = lines[this.row + r] ?? [];
+            const shown = Segment.divide(line, [start, start + width - blank])[1] ?? [];
+            yield* Segment.adjustLineLength([new Segment(" ".repeat(blank)), ...shown], width);
+            yield Segment.line();
+        }
+    }
+    measure() {
+        return { minimum: this.width, maximum: this.width };
+    }
+}

package/dist/renderables/spinner.d.ts

@@ -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,41 +19,44 @@
  * 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 } from "../core/animation.js";
+import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { RichText } from "../core/text.js";
-import type { Renderable, Measurable } from "../core/protocol.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 export interface SpinnerOptions {
     /** Multiplies the spinner's rate; negative runs it backwards; zero is refused. Defaults to 1. */
     speed?: number;
     style?: string | Style;
 }
-export declare class Spinner {
+export declare class Spinner implements Animation<Renderable & Measurable> {
     readonly name: string;
     readonly speed: number;
     readonly style: string | Style;
@@ -64,10 +67,19 @@ export declare 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: string | RichText;
+    get text(): string | RichText;
+    set text(value: string | RichText);
+    private readonly _text;
     private readonly _data;
     private readonly _named;
     private readonly _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`).
+     */
+    private readonly _placed;
     constructor(name?: string, text?: string | RichText, options?: SpinnerOptions);
     get frames(): readonly string[];
     /** Milliseconds each frame is held, as the spinner data gives it. */
@@ -77,8 +89,29 @@ export declare 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: number): Renderable & Measurable;
+    /** The spinner with its motion taken out: its first frame and the label, which never turn, so any time answers. */
+    reduced(): Animation<Renderable & Measurable>;
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    /** The frame `choose` picks from the frames the output can draw, and the label, saying the hold it is in if `choose` says. */
+    private _frame;
+    /**
+     * 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: number): number;
+    /** When the spinner drawn at `t` began to be drawn: the later of its two sequences' answers, by the same argument. */
+    lastChange(t: number): number;
     private _render;
     /**
      * The frame in progress and the label as one text, as Rich's