@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/renderables/progress.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Progress — displays continuously updated progress bars.
+ */
+import type { Segment } from "../core/segment.js";
+import { RichText } from "../core/text.js";
+import { Console } from "../core/console.js";
+import type { Style } from "../core/style.js";
+import { ProgressBar } from "./progressBar.js";
+import { type Clock } from "../core/clock.js";
+import { type ColumnOptions } from "./table.js";
+import type { Renderable, RenderOptions } from "../core/protocol.js";
+export interface TaskOptions {
+    total?: number;
+    start?: boolean;
+    visible?: boolean;
+}
+export interface TaskUpdateOptions {
+    completed?: number;
+    advance?: number;
+    description?: string;
+    visible?: boolean;
+    refresh?: boolean;
+}
+export interface Task {
+    id: number;
+    description: string;
+    total: number | undefined;
+    completed: number;
+    visible: boolean;
+    /** When the task started, in seconds on its `Progress`'s clock; undefined until it has. */
+    startTime: number | undefined;
+    /**
+     * Rich's `Task.elapsed`: seconds since the task started, as of the frame
+     * being drawn — `Progress` reads its clock once a frame and hands columns
+     * the result, so no column reads a clock. Undefined until the task starts.
+     */
+    elapsed: number | undefined;
+    /**
+     * Rich's `Task.finished_time`: the elapsed time the first time an update
+     * finds a started task at its total, kept from then on, so a finished task
+     * stays finished however its count moves after.
+     */
+    finishedTime: number | undefined;
+    /**
+     * Rich's `Task.speed`: steps a second over the updates that moved the task
+     * in the `SPEED_ESTIMATE_PERIOD` before its latest update — measured back from
+     * that update, not from now, so a task that stops being updated keeps the
+     * speed it had. Undefined until the task has started and two such updates lie
+     * apart in time.
+     */
+    speed: number | undefined;
+}
+/**
+ * One cell of a `Progress` row, made for the task on that row. Not a
+ * `Renderable`: a column has nothing to draw without a task, as the
+ * reference's `ProgressColumn` is a callable of one. What it returns is the
+ * cell's content, which the progress grid lays out like any table cell's —
+ * width, wrapping and justify are decided once, in the cell, as Rich's
+ * `make_tasks_table` decides them. [LAW:single-enforcer]
+ */
+export interface ProgressColumn {
+    /**
+     * The grid column this one is laid out in, Rich's `get_table_column()`:
+     * whether its cell may wrap, how it justifies, its share of the width.
+     */
+    readonly tableColumn: ColumnOptions;
+    render(task: Task): Renderable;
+}
+export declare class TextColumn implements ProgressColumn {
+    readonly format: string;
+    /** Text is cut, never wrapped, as Rich's `TextColumn` defaults to `Column(no_wrap=True)`. */
+    readonly tableColumn: ColumnOptions;
+    constructor(format?: string);
+    render(task: Task): RichText;
+}
+export declare class BarColumn implements ProgressColumn {
+    readonly barWidth: number;
+    readonly tableColumn: ColumnOptions;
+    constructor(barWidth?: number);
+    render(task: Task): ProgressBar;
+}
+/**
+ * Rich's `{task.percentage:>3.0f}%`: the percentage right-aligned in three
+ * cells, so the column is four wide from 0% to 100% and the row does not
+ * shift as it counts. A task with no total shows nothing, Rich's
+ * `text_format_no_percentage`.
+ */
+export declare class TaskProgressColumn implements ProgressColumn {
+    /** A `TextColumn` in Rich, and laid out as one. */
+    readonly tableColumn: ColumnOptions;
+    render(task: Task): RichText;
+}
+export interface TimeRemainingColumnOptions {
+    /**
+     * Once the task is finished, draw the time it took, styled
+     * `progress.elapsed`, in place of the zero left to go: Rich's
+     * `elapsed_when_finished`. Defaults to false.
+     */
+    elapsedWhenFinished?: boolean;
+}
+export declare class TimeRemainingColumn implements ProgressColumn {
+    readonly tableColumn: ColumnOptions;
+    readonly elapsedWhenFinished: boolean;
+    constructor(options?: TimeRemainingColumnOptions);
+    render(task: Task): RichText;
+}
+export declare class TimeElapsedColumn implements ProgressColumn {
+    readonly tableColumn: ColumnOptions;
+    render(task: Task): RichText;
+}
+export interface SpinnerColumnOptions {
+    /** The frame's style. Defaults to `progress.spinner`, a name its console's theme resolves. */
+    style?: string | Style;
+    /** Multiplies the spinner's frame rate. Defaults to 1. */
+    speed?: number;
+    /** Drawn in place of the frame once the task reaches its total; a string is markup. Defaults to `" "`. */
+    finishedText?: string | RichText;
+}
+export declare class SpinnerColumn implements ProgressColumn {
+    readonly tableColumn: ColumnOptions;
+    private _spinner;
+    private _finishedText;
+    constructor(spinnerName?: string, options?: SpinnerColumnOptions);
+    render(task: Task): Renderable;
+}
+export interface MofNCompleteColumnOptions {
+    /** Drawn between the two counts: Rich's `separator`. Defaults to `"/"`. */
+    separator?: string;
+}
+/**
+ * Rich's `MofNCompleteColumn`: both counts as whole numbers, the completed one
+ * padded to the total's width so the column holds still as it counts up to its
+ * total, styled `progress.download`.
+ */
+export declare class MofNCompleteColumn implements ProgressColumn {
+    readonly tableColumn: ColumnOptions;
+    readonly separator: string;
+    constructor(options?: MofNCompleteColumnOptions);
+    render(task: Task): RichText;
+}
+export interface ProgressOptions {
+    refreshPerSecond?: number;
+    autoRefresh?: boolean;
+    transient?: boolean;
+    expand?: boolean;
+    console?: Console;
+    /**
+     * What tasks are timed by and frames are drawn on, Rich's `get_time`;
+     * defaults to the platform's monotonic clock. Handed on to the `Live`.
+     */
+    clock?: Clock;
+}
+export declare class Progress implements Renderable {
+    private _columns;
+    private _tasks;
+    private _nextId;
+    private _live;
+    private _console;
+    private readonly _clock;
+    readonly expand: boolean;
+    constructor(...columns: (ProgressColumn | ProgressOptions)[]);
+    get console(): Console;
+    /** Rich's `Progress.finished`: every task finished, and so true with none. */
+    get finished(): boolean;
+    static getDefaultColumns(): ProgressColumn[];
+    addTask(description: string, options?: TaskOptions): number;
+    updateTask(taskId: number, options: TaskUpdateOptions): void;
+    startTask(taskId: number): void;
+    start(): void;
+    stop(): void;
+    refresh(): void;
+    render(options: RenderOptions): Iterable<Segment>;
+}
+export declare function track<T>(iterable: Iterable<T>, options?: {
+    description?: string;
+    total?: number;
+    console?: Console;
+}): Iterable<T>;

package/dist/renderables/progress.js

@@ -0,0 +1,362 @@
+/**
+ * Progress — displays continuously updated progress bars.
+ */
+import { RichText } from "../core/text.js";
+import { Console } from "../core/console.js";
+import { escape as escapeMarkup, readStr, renderStr } from "../core/markup.js";
+import { ProgressBar } from "./progressBar.js";
+import { Spinner } from "./spinner.js";
+import { Live } from "./live.js";
+import { systemClock } from "../core/clock.js";
+import { Table } from "./table.js";
+/**
+ * Rich's defaults for `speed_estimate_period` and its sample deque's
+ * `maxlen`: an update forgets samples older than the period, and the newest
+ * thousand are all a task keeps.
+ */
+const SPEED_ESTIMATE_PERIOD = 30;
+const MAX_SAMPLES = 1000;
+/**
+ * Rich's `Progress.update` bookkeeping on its sample deque, in place: drop the
+ * samples older than the period as of `now`, then add this update's if it
+ * moved the task forward, keeping the newest `MAX_SAMPLES`. The samples are in
+ * time order, so the stale ones are a prefix.
+ */
+function recordSample(samples, now, moved) {
+    const firstFresh = samples.findIndex((sample) => sample.timestamp >= now - SPEED_ESTIMATE_PERIOD);
+    samples.splice(0, firstFresh === -1 ? samples.length : firstFresh);
+    if (moved > 0)
+        samples.push({ timestamp: now, completed: moved });
+    samples.splice(0, samples.length - MAX_SAMPLES);
+}
+/**
+ * Rich's `Task.speed` over a started task's samples: everything moved after
+ * the first sample, over the time from the first to the last. No samples, or
+ * none apart in time, is no speed.
+ */
+function sampleSpeed(samples) {
+    const span = (samples.at(-1)?.timestamp ?? 0) - (samples[0]?.timestamp ?? 0);
+    if (span === 0)
+        return undefined;
+    return samples.slice(1).reduce((sum, sample) => sum + sample.completed, 0) / span;
+}
+/**
+ * A count as a task takes it in. [LAW:single-enforcer] `addTask` and
+ * `updateTask` are where counts enter, so a NaN or an Infinity is refused there,
+ * with the caller's stack, rather than drawn as `NaN%` by one column and thrown
+ * on a refresh tick by another.
+ */
+function finiteCount(field, value) {
+    if (!Number.isFinite(value))
+        throw new RangeError(`progress task ${field} must be a finite number, got ${value}`);
+    return value;
+}
+/** Rich's `Task.finished`. [LAW:one-source-of-truth] The one predicate every reader of "finished" asks. */
+function finished(task) {
+    return task.finishedTime !== undefined;
+}
+export class TextColumn {
+    format;
+    /** Text is cut, never wrapped, as Rich's `TextColumn` defaults to `Column(no_wrap=True)`. */
+    tableColumn = { noWrap: true };
+    constructor(format) {
+        this.format = format ?? "{task.description}";
+    }
+    render(task) {
+        // [LAW:single-enforcer] Format strings flow through the markup parser so
+        // tags like `[progress.description]` become Style spans, not literal text.
+        // Task descriptions are escaped first to prevent injection of stray tags.
+        const description = escapeMarkup(task.description);
+        // Use a callback so `$&`/`$1`/`$$` in the task description aren't
+        // reinterpreted by String.replace as replacement patterns.
+        const formatted = this.format.replace(/\{task\.description\}/g, () => description);
+        // Markup whatever the console says, and never highlighted: Rich's
+        // `TextColumn` reads its format as markup on its own `markup=True` and
+        // highlights only with a highlighter it was given, not the console's.
+        return renderStr(formatted, { markup: true });
+    }
+}
+export class BarColumn {
+    barWidth;
+    tableColumn = {};
+    constructor(barWidth) {
+        this.barWidth = barWidth ?? 40;
+    }
+    render(task) {
+        return new ProgressBar({
+            total: task.total ?? 100,
+            completed: task.completed,
+            width: this.barWidth,
+        });
+    }
+}
+/**
+ * Rich's `{task.percentage:>3.0f}%`: the percentage right-aligned in three
+ * cells, so the column is four wide from 0% to 100% and the row does not
+ * shift as it counts. A task with no total shows nothing, Rich's
+ * `text_format_no_percentage`.
+ */
+export class TaskProgressColumn {
+    /** A `TextColumn` in Rich, and laid out as one. */
+    tableColumn = { noWrap: true };
+    render(task) {
+        const text = task.total === undefined ? "" : `${String(roundHalfEven(percentage(task))).padStart(3)}%`;
+        return new RichText(text, { style: "progress.percentage" });
+    }
+}
+/** Rich's `Task.percentage`: 0 without a total, and clamped to [0, 100]. */
+function percentage(task) {
+    return task.total ? Math.min(100, Math.max(0, (task.completed / task.total) * 100)) : 0;
+}
+/**
+ * Python's `format(x, ".0f")`: the nearest integer to the double's exact
+ * value, a tie going to the even one. `Math.round` is exact too but sends a
+ * tie up, so only a tie is corrected.
+ */
+function roundHalfEven(x) {
+    const up = Math.round(x);
+    return up - x === 0.5 && up % 2 !== 0 ? up - 1 : up;
+}
+export class TimeRemainingColumn {
+    tableColumn = {};
+    elapsedWhenFinished;
+    constructor(options) {
+        this.elapsedWhenFinished = options?.elapsedWhenFinished ?? false;
+    }
+    render(task) {
+        const took = this.elapsedWhenFinished && finished(task) ? task.finishedTime : undefined;
+        const time = took ?? timeRemaining(task);
+        const style = took === undefined ? "progress.remaining" : "progress.elapsed";
+        // A task with no total has no time to estimate, and Rich draws its cell empty.
+        return new RichText(task.total === undefined ? "" : clockFace(time), { style });
+    }
+}
+/**
+ * Rich's `Task.time_remaining`: nothing left once the task is finished,
+ * however long ago that was, unknown until it has a speed against a total,
+ * and otherwise whole seconds, rounded up.
+ */
+function timeRemaining(task) {
+    if (finished(task))
+        return 0;
+    if (!task.speed || task.total === undefined)
+        return undefined;
+    return Math.ceil((task.total - task.completed) / task.speed);
+}
+export class TimeElapsedColumn {
+    tableColumn = {};
+    render(task) {
+        // Rich's `finished_time if finished else elapsed`: a finished task's clock
+        // holds where it stopped, and one never started has no time to show.
+        const time = finished(task) ? task.finishedTime : task.elapsed;
+        return new RichText(clockFace(time), { style: "progress.elapsed" });
+    }
+}
+/** A time as the time columns draw it, `-:--:--` when there is none to draw. */
+function clockFace(seconds) {
+    return seconds === undefined ? "-:--:--" : formatTime(seconds);
+}
+export class SpinnerColumn {
+    tableColumn = {};
+    _spinner;
+    _finishedText;
+    constructor(spinnerName, options) {
+        this._spinner = new Spinner(spinnerName, "", {
+            style: options?.style ?? "progress.spinner",
+            speed: options?.speed,
+        });
+        // Markup whatever the console says, as Rich's `Text.from_markup`. A
+        // `RichText` is copied, since the caller still holds it.
+        const finishedText = options?.finishedText ?? " ";
+        this._finishedText = typeof finishedText === "string" ? readStr(finishedText, true) : finishedText.copy();
+    }
+    render(task) {
+        return finished(task) ? this._finishedText : this._spinner;
+    }
+}
+/**
+ * Rich's `MofNCompleteColumn`: both counts as whole numbers, the completed one
+ * padded to the total's width so the column holds still as it counts up to its
+ * total, styled `progress.download`.
+ */
+export class MofNCompleteColumn {
+    tableColumn = {};
+    separator;
+    constructor(options) {
+        this.separator = options?.separator ?? "/";
+    }
+    render(task) {
+        const total = task.total === undefined ? "?" : wholeNumber(task.total);
+        const completed = wholeNumber(task.completed).padStart(total.length);
+        return new RichText(`${completed}${this.separator}${total}`, { style: "progress.download" });
+    }
+}
+/**
+ * Python's `str(int(x))`: truncated toward zero and written out in full,
+ * never in exponent form. `Progress` admits only finite counts, so `BigInt`
+ * has nothing here to refuse.
+ */
+function wholeNumber(x) {
+    return BigInt(Math.trunc(x)).toString();
+}
+/**
+ * Rich's clock face: `int()` the seconds, then Python's floor `divmod` by 60
+ * twice, so a negative estimate — a task past its total — reads as Rich's
+ * does, `-3` as `-1:59:57`.
+ */
+function formatTime(seconds) {
+    const whole = Math.trunc(seconds);
+    const minutes = Math.floor(whole / 60);
+    const h = Math.floor(minutes / 60);
+    const m = minutes - h * 60;
+    const s = whole - minutes * 60;
+    return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+}
+export class Progress {
+    _columns;
+    _tasks;
+    _nextId;
+    _live;
+    _console;
+    _clock;
+    expand;
+    constructor(...columns) {
+        // Last arg might be options
+        let opts = {};
+        const cols = [];
+        for (const arg of columns) {
+            if ("render" in arg) {
+                cols.push(arg);
+            }
+            else {
+                opts = arg;
+            }
+        }
+        if (cols.length === 0) {
+            cols.push(new TextColumn("[progress.description]{task.description}"), new BarColumn(), new TaskProgressColumn(), new TimeRemainingColumn());
+        }
+        this._columns = cols;
+        this._tasks = new Map();
+        this._nextId = 1;
+        this._console = opts.console ?? new Console();
+        this.expand = opts.expand ?? false;
+        this._clock = opts.clock ?? systemClock();
+        this._live = new Live(this, {
+            console: this._console,
+            clock: this._clock,
+            refreshPerSecond: opts.refreshPerSecond ?? 10,
+            autoRefresh: opts.autoRefresh,
+            transient: opts.transient,
+        });
+    }
+    get console() {
+        return this._console;
+    }
+    /** Rich's `Progress.finished`: every task finished, and so true with none. */
+    get finished() {
+        return [...this._tasks.values()].every(finished);
+    }
+    static getDefaultColumns() {
+        return [
+            new TextColumn("[progress.description]{task.description}"),
+            new BarColumn(),
+            new TaskProgressColumn(),
+            new TimeRemainingColumn(),
+        ];
+    }
+    addTask(description, options) {
+        const id = this._nextId++;
+        const task = {
+            id,
+            description,
+            total: options?.total === undefined ? undefined : finiteCount("total", options.total),
+            completed: 0,
+            visible: options?.visible !== false,
+            startTime: options?.start === false ? undefined : this._clock.now(),
+            finishedTime: undefined,
+            samples: [],
+        };
+        this._tasks.set(id, task);
+        return id;
+    }
+    updateTask(taskId, options) {
+        const task = this._tasks.get(taskId);
+        if (!task)
+            return;
+        // Rich's order, `completed` then `advance`, checked whole before any field
+        // is written, so a refused update leaves the task as it was.
+        const advance = finiteCount("advance", options.advance ?? 0);
+        const completed = finiteCount("completed", (options.completed ?? task.completed) + advance);
+        const now = this._clock.now();
+        recordSample(task.samples, now, completed - task.completed);
+        task.completed = completed;
+        if (options.description !== undefined)
+            task.description = options.description;
+        if (options.visible !== undefined)
+            task.visible = options.visible;
+        if (!finished(task) &&
+            task.startTime !== undefined &&
+            task.total !== undefined &&
+            task.completed >= task.total) {
+            task.finishedTime = now - task.startTime;
+        }
+        if (options.refresh) {
+            this._live.update(this, { refresh: true });
+        }
+    }
+    startTask(taskId) {
+        const task = this._tasks.get(taskId);
+        // Rich's `start_task`: a task already running keeps the time it started.
+        if (task)
+            task.startTime ??= this._clock.now();
+    }
+    start() {
+        this._live.start();
+    }
+    stop() {
+        this._live.stop();
+    }
+    refresh() {
+        this._live.refresh();
+    }
+    *render(options) {
+        // Rich's `make_tasks_table`: each column laid out as it says.
+        const table = Table.grid({ expand: this.expand });
+        for (const col of this._columns) {
+            table.addColumn(undefined, col.tableColumn);
+        }
+        // [LAW:effects-at-boundaries] One read of the clock a frame, handed to
+        // every column as the task's `elapsed`.
+        const now = this._clock.now();
+        for (const { samples, ...state } of this._tasks.values()) {
+            if (!state.visible)
+                continue;
+            const { startTime } = state;
+            const started = startTime !== undefined;
+            const task = {
+                ...state,
+                elapsed: started ? now - startTime : undefined,
+                speed: started ? sampleSpeed(samples) : undefined,
+            };
+            table.addRow(...this._columns.map((col) => col.render(task)));
+        }
+        yield* table.render(options);
+    }
+}
+// --- track ---
+export function* track(iterable, options) {
+    const items = [...iterable];
+    const total = options?.total ?? items.length;
+    const progress = new Progress({ console: options?.console });
+    const taskId = progress.addTask(options?.description ?? "Working...", { total });
+    progress.start();
+    try {
+        for (let i = 0; i < items.length; i++) {
+            yield items[i];
+            progress.updateTask(taskId, { completed: i + 1 });
+        }
+    }
+    finally {
+        progress.stop();
+    }
+}

package/dist/renderables/progressBar.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ProgressBar — a visual progress bar rendered with block characters.
+ */
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export interface ProgressBarOptions {
+    total?: number;
+    completed?: number;
+    width?: number;
+    pulse?: boolean;
+    style?: string | Style;
+    completeStyle?: string | Style;
+    finishedStyle?: string | Style;
+}
+export declare class ProgressBar implements Renderable, Measurable {
+    total: number;
+    completed: number;
+    readonly width: number | undefined;
+    readonly pulse: boolean;
+    readonly style: string | Style;
+    readonly completeStyle: string | Style;
+    readonly finishedStyle: string | Style;
+    constructor(options?: ProgressBarOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+    /** A width given is the bar's exact width, as Rich measures it; one left open fills what it is offered, down to 4. */
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/progressBar.js

@@ -0,0 +1,64 @@
+/**
+ * ProgressBar — a visual progress bar rendered with block characters.
+ */
+import { cellCount } from "../core/cells.js";
+import { Segment } from "../core/segment.js";
+import { NULL_STYLE } from "../core/style.js";
+import { drawable, getStyle } from "../core/protocol.js";
+const BAR = "━";
+const ASCII_BAR = "-";
+const HALF_BAR_RIGHT = "╸";
+const HALF_BAR_LEFT = "╺";
+export class ProgressBar {
+    total;
+    completed;
+    width;
+    pulse;
+    style;
+    completeStyle;
+    finishedStyle;
+    constructor(options) {
+        this.total = options?.total ?? 100;
+        this.completed = options?.completed ?? 0;
+        this.width = options?.width;
+        this.pulse = options?.pulse ?? false;
+        this.style = options?.style ?? NULL_STYLE;
+        this.completeStyle = options?.completeStyle ?? "bar.complete";
+        this.finishedStyle = options?.finishedStyle ?? "bar.finished";
+    }
+    *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));
+        // Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and
+        // a total of zero is a bar already full.
+        const completed = Math.min(this.total, Math.max(0, this.completed));
+        const completeHalves = this.total ? Math.trunc((width * 2 * completed) / this.total) : width * 2;
+        const barCount = Math.floor(completeHalves / 2);
+        const halfBarCount = completeHalves % 2;
+        const isFinished = this.completed >= this.total;
+        const fill = getStyle(options, isFinished ? this.finishedStyle : this.completeStyle);
+        const back = getStyle(options, this.style);
+        const fillStyle = fill.isNull ? undefined : fill;
+        const backStyle = back.isNull ? undefined : back;
+        const bar = drawable(options, BAR, ASCII_BAR);
+        if (barCount)
+            yield new Segment(bar.repeat(barCount), fillStyle);
+        if (halfBarCount)
+            yield new Segment(drawable(options, HALF_BAR_RIGHT, " "), fillStyle);
+        // The back is drawn in colour alone, so an output with none leaves it blank.
+        if (options.colorSystem === null)
+            return;
+        let remaining = width - barCount - halfBarCount;
+        if (remaining && !halfBarCount && barCount) {
+            yield new Segment(drawable(options, HALF_BAR_LEFT, " "), backStyle);
+            remaining -= 1;
+        }
+        if (remaining)
+            yield new Segment(bar.repeat(remaining), backStyle);
+    }
+    /** A width given is the bar's exact width, as Rich measures it; one left open fills what it is offered, down to 4. */
+    measure(options) {
+        return this.width === undefined ? { minimum: 4, maximum: options.maxWidth } : { minimum: this.width, maximum: this.width };
+    }
+}