@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/renderables/panel.d.ts

@@ -6,20 +6,20 @@ import { Style } from "../core/style.js";
 import { Box } from "../core/box.js";
 import { RichText } from "../core/text.js";
 import type { PaddingDimensions } from "./padding.js";
-import type { Composite, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 /**
- * A lazily-resolved border accessory. Strings render inline in the
- * border style; a `RichText` accessory lays ONLY its wrapping `style` over
- * the border's (per-range spans within the RichText are not preserved — the
- * accessory is a small status indicator, not an arbitrary span carrier).
- * A function form is evaluated at render time, *after* content has been
- * rendered for the current frame — use this when the accessory mirrors
- * state that the wrapped renderable populates during its own `render()`
- * (e.g. a widget's post-render scroll position). A width that leaves the
- * content no column does not render it, as Rich's does not, and the thunk
- * then reads the state of the last frame that did.
+ * A border accessory. Strings render inline in the border style; a
+ * `RichText` accessory lays ONLY its wrapping `style` over the border's
+ * (per-range spans within the RichText are not preserved — the accessory is a
+ * small status indicator, not an arbitrary span carrier).
+ *
+ * [LAW:no-ambient-temporal-coupling] A function form is handed the rows the
+ * body drew this frame, so an accessory that mirrors the content's layout (a
+ * widget's scroll position) reads it off the frame it labels, not off state
+ * the content kept from an earlier one. A width that leaves the content no column does not render it,
+ * as Rich's does not, and the rows it is handed are then blank.
  */
-export type BorderAccessory = string | RichText | (() => string | RichText | undefined);
+export type BorderAccessory = string | RichText | ((body: readonly (readonly Segment[])[]) => string | RichText | undefined);
 export interface PanelOptions {
     box?: Box;
     title?: string | RichText;
@@ -48,7 +48,7 @@ export interface PanelOptions {
     width?: number;
     padding?: PaddingDimensions;
 }
-export declare class Panel implements Renderable, Measurable, Composite {
+export declare class Panel implements Renderable, Measurable {
     readonly renderable: Renderable;
     readonly box: Box;
     readonly title: string | RichText | undefined;
@@ -73,7 +73,6 @@ export declare class Panel implements Renderable, Measurable, Composite {
     get padding(): readonly [number, number, number, number];
     constructor(content: string | RichText | Renderable, options?: PanelOptions);
     render(rawOptions: RenderOptions): Iterable<Segment>;
-    contents(): Iterable<Renderable>;
     /**
      * The body's rows, held to the region as Rich's `render_lines` holds them —
      * padded below, cropped from the bottom — and each exactly `spanWidth`
@@ -82,8 +81,7 @@ export declare class Panel implements Renderable, Measurable, Composite {
      * `Console.render` renders nothing under one column, so outside a region it
      * draws no rows, padding rows included, and inside one the frame stands
      * around empty rows. The render happens before either border is drawn,
-     * because a `bottomRightAccessory` thunk reads state the content's render
-     * populates.
+     * because a `bottomRightAccessory` function is handed the rows it drew.
      */
     private _renderBody;
     measure(rawOptions: RenderOptions): {

package/dist/renderables/panel.js

@@ -140,12 +140,7 @@ export class Panel {
             yield new Segment(frame.right.repeat(geometry.right), border);
             yield Segment.line();
         }
-        yield* this._renderBottomBorder(options, box, geometry, border);
-    }
-    // The body is the one thing a panel draws through `render`: its title and
-    // subtitle are text it builds.
-    *contents() {
-        yield this._body;
+        yield* this._renderBottomBorder(options, box, geometry, border, bodyLines);
     }
     /**
      * The body's rows, held to the region as Rich's `render_lines` holds them —
@@ -155,8 +150,7 @@ export class Panel {
      * `Console.render` renders nothing under one column, so outside a region it
      * draws no rows, padding rows included, and inside one the frame stands
      * around empty rows. The render happens before either border is drawn,
-     * because a `bottomRightAccessory` thunk reads state the content's render
-     * populates.
+     * because a `bottomRightAccessory` function is handed the rows it drew.
      */
     _renderBody(options, spanWidth) {
         // Two border rows are the panel's own, and the vertical padding is the
@@ -230,10 +224,8 @@ export class Panel {
         yield* borderRow(options, box.top, geometry, geometry.spanWidth, this._titleLabel, titleStyle, border, box.top.right.repeat(geometry.right));
         yield Segment.line();
     }
-    *_renderBottomBorder(options, box, geometry, border) {
-        // Resolve the right accessory *now*, after the body has rendered —
-        // `BorderAccessory` owns what a thunk sees.
-        const accessory = this._resolveAccessory(this.bottomRightAccessory);
+    *_renderBottomBorder(options, box, geometry, border, body) {
+        const accessory = this._resolveAccessory(this.bottomRightAccessory, body);
         const accessoryDisplay = accessory === undefined
             ? ""
             : typeof accessory === "string"
@@ -253,11 +245,11 @@ export class Panel {
         yield new Segment(afterAccessory, border);
         yield Segment.line();
     }
-    _resolveAccessory(a) {
+    _resolveAccessory(a, body) {
         if (a === undefined)
             return undefined;
         if (typeof a === "function")
-            return a();
+            return a(body);
         return a;
     }
     // --- Static factory ---

package/dist/renderables/progress.d.ts

@@ -5,10 +5,11 @@ 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 { Clock } from "../core/clock.js";
 import { type ColumnOptions } from "./table.js";
-import type { Composite, Renderable, RenderOptions } from "../core/protocol.js";
+import type { FrameHost, Renderable, RenderOptions } from "../core/protocol.js";
+import { Animation } from "../core/animation.js";
+import type { Timing } from "../core/easing.js";
 export interface TaskOptions {
     total?: number;
     start?: boolean;
@@ -22,30 +23,31 @@ export interface TaskUpdateOptions {
     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;
+    readonly id: number;
+    readonly description: string;
+    readonly total: number | undefined;
+    readonly completed: number;
     /**
-     * Rich's `Task.get_time()`: the moment the frame being drawn is drawn at, in
-     * seconds on its `Progress`'s clock, so a column animates without reading one.
+     * The count a bar shows, over its `Progress`'s clock: `completed` itself,
+     * or moving to it after each update when the `Progress` was given a `fill`
+     * timing. `completed` stays the count; only the bar draws this.
      */
-    time: number;
+    readonly fill: Animation<number>;
+    readonly visible: boolean;
+    /** When the task started, in seconds on its `Progress`'s host's time; undefined until it has, as of the frame being drawn. */
+    readonly 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
+     * being drawn — `Progress` takes the time once a frame and hands columns
      * the result, so no column reads a clock. Undefined until the task starts.
      */
-    elapsed: number | undefined;
+    readonly 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;
+    readonly 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
@@ -53,7 +55,7 @@ export interface Task {
      * speed it had. Undefined until the task has started and two such updates lie
      * apart in time.
      */
-    speed: number | undefined;
+    readonly speed: number | undefined;
 }
 /**
  * One cell of a `Progress` row, made for the task on that row. Not a
@@ -82,8 +84,16 @@ export declare class BarColumn implements ProgressColumn {
     readonly barWidth: number;
     readonly tableColumn: ColumnOptions;
     constructor(barWidth?: number);
-    /** Rich's `BarColumn`: a task not yet started, or with no total to fill toward, pulses. */
-    render(task: Task): ProgressBar;
+    /**
+     * Rich's `BarColumn`: a task not yet started, or with no total to fill
+     * toward, pulses, and a pulse draws no fill. Otherwise the bar is the
+     * task's `fill` drawn at the frame's time, every cell stamped with when the
+     * fill next moves, so a host draws while it eases and the bar asks for
+     * nothing once it lands. Its colour is the task's: an ease that overshoots
+     * the total does not finish the bar, and one that dips back does not
+     * unfinish it.
+     */
+    render(task: Task): Renderable;
 }
 /**
  * Rich's `{task.percentage:>3.0f}%`: the percentage right-aligned in three
@@ -112,7 +122,7 @@ export declare class TimeRemainingColumn implements ProgressColumn {
 }
 export declare class TimeElapsedColumn implements ProgressColumn {
     readonly tableColumn: ColumnOptions;
-    render(task: Task): RichText;
+    render(task: Task): Renderable;
 }
 export interface SpinnerColumnOptions {
     /** The frame's style. Defaults to `progress.spinner`, a name its console's theme resolves. */
@@ -125,7 +135,7 @@ export interface SpinnerColumnOptions {
 export declare class SpinnerColumn implements ProgressColumn {
     readonly tableColumn: ColumnOptions;
     private readonly _spinner;
-    private _finishedText;
+    private readonly _finishedText;
     constructor(spinnerName?: string, options?: SpinnerColumnOptions);
     render(task: Task): Renderable;
 }
@@ -144,39 +154,77 @@ export declare class MofNCompleteColumn implements ProgressColumn {
     constructor(options?: MofNCompleteColumnOptions);
     render(task: Task): RichText;
 }
-export interface ProgressOptions {
+/**
+ * How a `Progress` is set up. It is drawn by one host, and every time it
+ * keeps or draws at is that host's `frameTime`: by its own `Live`, which the
+ * options for that `Live` configure, or, given `drawnBy`, by another host —
+ * which then does all the drawing, so none of them apply.
+ */
+export type ProgressOptions = ProgressDisplayOptions & (OwnLiveOptions | DrawnByOptions);
+interface ProgressDisplayOptions {
+    expand?: boolean;
+    /**
+     * How a bar's fill moves to a task's new count: eased over this timing
+     * from wherever it is when the count changes, so a bar advancing in bursts
+     * reads as motion. Unset, the bar jumps to the count, as Rich's does.
+     */
+    fill?: Timing;
+}
+interface OwnLiveOptions {
+    drawnBy?: undefined;
+    console?: Console;
     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`.
+     * What its own `Live` ticks on, and so what tasks are timed by — Rich's
+     * `get_time`; defaults to the platform's monotonic clock.
      */
     clock?: Clock;
 }
-export declare class Progress implements Renderable, Composite {
-    private _columns;
-    private _tasks;
-    private _nextId;
-    private _live;
-    private _console;
-    private readonly _clock;
+interface DrawnByOptions {
+    /**
+     * The host — a `Live`, an `App` — whose frames this `Progress` is drawn in:
+     * tasks are timed by its `frameTime`, so they hold while its timeline is
+     * paused and run back while it is reversed. Drawn in any other host's
+     * frame, the `Progress` throws.
+     */
+    drawnBy: FrameHost;
+    console?: never;
+    refreshPerSecond?: never;
+    autoRefresh?: never;
+    transient?: never;
+    clock?: never;
+}
+export declare class Progress implements Renderable {
+    private readonly _columns;
+    private readonly _tasks;
+    private readonly _live;
+    private readonly _host;
+    /** A task's fill after its count changes at `now`, from the value it shows then. */
+    private readonly _refill;
     readonly expand: boolean;
     constructor(...columns: (ProgressColumn | ProgressOptions)[]);
+    /** The console its own `Live` prints above the bars through. */
     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;
+    private _task;
     updateTask(taskId: number, options: TaskUpdateOptions): void;
     startTask(taskId: number): void;
     start(): void;
+    /**
+     * Every bar settles at its count, so the frame drawn next — its own `Live`'s
+     * final one, handed back here, or the next of the host that draws it —
+     * shows where the work got to, not a bar caught mid-ease.
+     */
     stop(): void;
     refresh(): void;
+    private _ownLive;
     render(options: RenderOptions): Iterable<Segment>;
-    contents(): Iterable<Renderable>;
+    private _framed;
     private _table;
 }
 export declare function track<T>(iterable: Iterable<T>, options?: {
@@ -184,3 +232,4 @@ export declare function track<T>(iterable: Iterable<T>, options?: {
     total?: number;
     console?: Console;
 }): Iterable<T>;
+export {};