@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/renderables/layout.js

@@ -3,19 +3,10 @@
  */
 import { Segment } from "../core/segment.js";
 import { embed } from "./embed.js";
-import { fitHeight, isMeasurable, regionRows, stackedHeight, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+import { fitHeight, regionRows, stackedHeight, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
 import { Measurement } from "../core/measure.js";
 import { cellCount } from "../core/cells.js";
-/**
- * A share weight, not a cell count: fractions divide space meaningfully, so
- * this parses where `cellCount` would floor. A weight that cannot name a share
- * — negative, NaN, infinite — reads as zero, which already means "this pane
- * does not grow" and is filtered out before any division. That is what makes
- * every ratio reaching `_distributeSpace` and `_rowBudgetFor` positive.
- */
-function growthRatio(ratio) {
-    return Number.isFinite(ratio) && ratio > 0 ? ratio : 0;
-}
+import { ratioBudget, ratioResolve, shareWeight } from "./ratio.js";
 /**
  * A pane rendered into a region of `rows` and held to exactly that many lines,
  * or — with `rows` undefined — rendered under the layout's own budget, as a
@@ -55,7 +46,7 @@ export class Layout {
      * constructor. All three are public and a caller reaches them long after
      * construction — `layout.getByName("pane")!.ratio = -1` walked straight past a
      * constructor-only parse and put a negative weight back into the division that
-     * `_rowBudgetFor` and `_distributeSpace` are written to trust.
+     * `ratioResolve` and `ratioBudget` are written to trust.
      *
      * [LAW:parse-dont-validate] The setter is the border, so the guarantee holds
      * for the object's whole lifetime and nothing downstream re-checks. `size` and
@@ -67,7 +58,7 @@ export class Layout {
         return this._ratio;
     }
     set ratio(value) {
-        this._ratio = growthRatio(value);
+        this._ratio = shareWeight(value);
     }
     get size() {
         return this._size;
@@ -125,13 +116,23 @@ export class Layout {
         // would otherwise hand each of them the caller's raw number.
         const options = withBoundedWidth(rawOptions, this);
         if (this._isLeaf) {
-            // Cropped rather than forwarded: a leaf hands its content the offer and
-            // content is free to ignore it, and a pane wider than the region it was
-            // given is the one thing a layout may never emit — in a row split it
-            // overwrites the pane beside it. The row path already crops each share,
-            // so this is the same rule at the one place that skipped it.
+            // Shaped to its region, as Rich's `render_lines` shapes a pane: every
+            // line cropped and padded to the width, and held to the region's rows.
+            // The leaf sets its content's region, so it shapes what comes back, as
+            // `paneLines` shapes a pane for the split that set the pane's.
+            // Cropped rather than forwarded because content is free to ignore its
+            // offer, and a pane wider than its region is the one thing a layout may
+            // never emit — in a row split it overwrites the pane beside it. Held to
+            // the rows because content keeps its own `end`: `RichText("status:
+            // ok\n")` is two lines, and a one-row region cuts the second. Every line
+            // ended, as the split paths below end theirs: a leaf stacked in a
+            // `Group` is still a region of lines.
             if (this._renderable) {
-                yield* Segment.cropLines(this._renderable.render(options), options.maxWidth);
+                const lines = fitHeight(Segment.splitLines(this._renderable.render(options)), options.height);
+                for (const line of lines) {
+                    yield* Segment.adjustLineLength(line, options.maxWidth);
+                    yield Segment.line();
+                }
             }
             return;
         }
@@ -152,7 +153,7 @@ export class Layout {
         const region = regionRows(options.height);
         const shares = region === undefined
             ? children.map((child) => child.size)
-            : this._distributeSpace(children, region);
+            : ratioResolve(region, children);
         for (let i = 0; i < children.length; i++) {
             for (const line of paneLines(children[i], options, shares[i])) {
                 yield* line;
@@ -166,7 +167,7 @@ export class Layout {
         // width made every share NaN and the merge threw `Invalid array length`.
         // Every pane stands in the whole region, and with none the merge pads the
         // row to its tallest pane.
-        const widths = this._distributeSpace(children, options.maxWidth);
+        const widths = ratioResolve(options.maxWidth, children);
         const region = regionRows(options.height);
         const cells = children.map((child, i) => ({
             width: widths[i],
@@ -174,55 +175,6 @@ export class Layout {
         }));
         yield* Segment.mergeHorizontal(cells);
     }
-    _distributeSpace(children, totalSpace) {
-        const sizes = new Array(children.length).fill(0);
-        let remaining = totalSpace;
-        // Children that do not grow are paid first: a declared `size`, and equally
-        // a `ratio` of 0, which is the caller saying this pane stays at its
-        // `minimumSize`. Left in the ratio pass below, a zero-ratio child divided
-        // by its own ratio and drew its minimum out of a budget the shares had
-        // already spent — three panes of `zzz`/`aaaaa`/`bbbbb` consumed
-        // `3 + 2*floor(T/2)` cells out of `T`, which no `T` satisfies, and the row
-        // only came out right at 16 because the `Math.min(remaining, ...)` below
-        // happened to clip the last share to the right number.
-        const growing = [];
-        for (let i = 0; i < children.length; i++) {
-            const child = children[i];
-            if (child.size !== undefined) {
-                sizes[i] = Math.min(child.size, remaining);
-            }
-            else if (child.ratio === 0) {
-                sizes[i] = Math.min(child.minimumSize, remaining);
-            }
-            else {
-                growing.push(i);
-                continue;
-            }
-            remaining -= sizes[i];
-        }
-        // Distribute what is left by ratio. Each child's share comes off one
-        // budget and is bounded by what that budget still holds: `minimumSize` is
-        // what a child asks for, `remaining` is what there is to give, and the
-        // second beats the first. Applied without that bound — as
-        // `Math.max(minimumSize, share)` alone — every child claimed its whole
-        // minimum out of a budget that could not cover one of them, so two
-        // children of a Layout asked to fit one cell merged into a two-cell row.
-        if (growing.length > 0 && remaining > 0) {
-            const budget = remaining;
-            // Every ratio in here is positive — `growthRatio` parses the rest to zero
-            // at the constructor and zero is filtered out above — which is what makes
-            // the division safe and `_rowBudgetFor`'s inverse of it finite.
-            const totalRatio = growing.reduce((s, idx) => s + children[idx].ratio, 0);
-            for (const idx of growing) {
-                const child = children[idx];
-                const share = Math.floor(budget * child.ratio / totalRatio);
-                const allocated = Math.min(remaining, Math.max(child.minimumSize, share));
-                sizes[idx] = allocated;
-                remaining -= allocated;
-            }
-        }
-        return sizes;
-    }
     /**
      * The width this layout would take if nothing constrained it: its content's
      * for a leaf, its children's laid out the way the split lays them out.
@@ -237,19 +189,14 @@ export class Layout {
         if (this._isLeaf) {
             if (this._renderable === undefined)
                 return 0;
-            // A leaf whose content cannot measure itself has no width of its own to
-            // report, so it reports the offer — unbounded included, which is where
-            // `withBoundedWidth` says so rather than inventing a number.
-            return isMeasurable(this._renderable)
-                ? Measurement.get(options, this._renderable).maximum
-                : options.maxWidth;
+            return Measurement.get(options, this._renderable).maximum;
         }
         const visible = this._children.filter((c) => c.visible);
         if (visible.length === 0)
             return 0;
         const widths = visible.map((c) => c._naturalWidth(options));
         if (this._splitDirection === "row")
-            return this._rowBudgetFor(visible, widths);
+            return ratioBudget(visible, widths);
         // Accumulated, not spread: a column split holds as many children as a caller
         // made, and `Math.max(...widths)` passes one argument per child, so a
         // generated dashboard deep enough overruns the engine's argument limit and
@@ -259,42 +206,6 @@ export class Layout {
             widest = Math.max(widest, width);
         return widest;
     }
-    /**
-     * The budget at which `_distributeSpace` gives every child of a row at least
-     * the width it wants — the inverse of the ratio rule above, and the reason
-     * this is not the sum of those widths.
-     *
-     * [LAW:one-source-of-truth] A growing child receives `floor(budget * ratio /
-     * totalRatio)`, so to receive `want` cells it needs the budget to reach
-     * `want * totalRatio / ratio`, and one budget serves them all: the row needs
-     * the largest demand, never their total. Summed instead, a 1:1 split of
-     * "left" and "right" reported 9 and then rendered "right" into the 4 cells
-     * that `floor(9/2)` actually hands it.
-     *
-     * The panes that do not grow are paid first here for the same reason they
-     * are paid first there — and it is the reason this divides by no zero: a
-     * `ratio` of 0 never reaches the division, because a pane that does not grow
-     * demands nothing of a budget for growing.
-     */
-    _rowBudgetFor(children, widths) {
-        const growing = children.filter((c) => c.size === undefined && c.ratio !== 0);
-        const totalRatio = growing.reduce((sum, c) => sum + c.ratio, 0);
-        let pinned = 0;
-        let budget = 0;
-        for (const [i, child] of children.entries()) {
-            if (child.size !== undefined) {
-                pinned += child.size;
-            }
-            else if (child.ratio === 0) {
-                pinned += child.minimumSize;
-            }
-            else {
-                const want = Math.max(child.minimumSize, widths[i]);
-                budget = Math.max(budget, Math.ceil(want * totalRatio / child.ratio));
-            }
-        }
-        return pinned + budget;
-    }
     measure(rawOptions) {
         // `minimumSize` is what this layout asks for and the ceiling is what it was
         // offered; the ceiling wins. Unclamped, a layout measured into no width

package/dist/renderables/list-view.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ListView — items stacked down a `Viewport`, scrolled to keep the selected
+ * one in view. `moveSelection` (core/selection) is the cursor that picks it.
+ *
+ * An item can wrap, so the lines the selected one covers exist only at the
+ * width it is drawn at, which a render is handed and whoever builds the frame
+ * is not. So the items are drawn here, at the viewport's content width and
+ * with no height — the lines the viewport scrolls — and the viewport is handed
+ * those lines and the selected item's range.
+ * [LAW:single-enforcer] Where the window sits is the viewport's call; this
+ * only says which lines the selection is.
+ *
+ * The viewport is handed in rather than made here: the scroll position lives
+ * in it, and a frame rebuilt on every key would otherwise start each one at
+ * the top. The pieces stay apart — a cursor, a viewport, a list drawn through
+ * it — so a consumer can take one without the others.
+ */
+import { Segment } from "../core/segment.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import type { Viewport } from "./viewport.js";
+export interface ListViewOptions {
+    /** Blank lines between one item and the next. Absent, none. */
+    gap?: number;
+    /**
+     * Lines kept in view above and below the selected item, where the list has
+     * them: the neighbour a cursor is about to move onto. Absent, none.
+     */
+    context?: number;
+}
+export declare class ListView implements Renderable, Measurable {
+    readonly viewport: Viewport;
+    readonly items: readonly Renderable[];
+    readonly selected: number;
+    readonly gap: number;
+    readonly context: number;
+    constructor(viewport: Viewport, items: readonly Renderable[], selected: number, options?: ListViewOptions);
+    render(rawOptions: RenderOptions): Iterable<Segment>;
+    measure(rawOptions: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/list-view.js

@@ -0,0 +1,78 @@
+/**
+ * ListView — items stacked down a `Viewport`, scrolled to keep the selected
+ * one in view. `moveSelection` (core/selection) is the cursor that picks it.
+ *
+ * An item can wrap, so the lines the selected one covers exist only at the
+ * width it is drawn at, which a render is handed and whoever builds the frame
+ * is not. So the items are drawn here, at the viewport's content width and
+ * with no height — the lines the viewport scrolls — and the viewport is handed
+ * those lines and the selected item's range.
+ * [LAW:single-enforcer] Where the window sits is the viewport's call; this
+ * only says which lines the selection is.
+ *
+ * The viewport is handed in rather than made here: the scroll position lives
+ * in it, and a frame rebuilt on every key would otherwise start each one at
+ * the top. The pieces stay apart — a cursor, a viewport, a list drawn through
+ * it — so a consumer can take one without the others.
+ */
+import { Segment } from "../core/segment.js";
+import { Measurement, measureRenderables } from "../core/measure.js";
+import { withBoundedWidth, withCellWidth } from "../core/protocol.js";
+function lineCount(name, value) {
+    if (!Number.isInteger(value) || value < 0)
+        throw new RangeError(`ListView: ${name} ${value} is not a whole number of lines`);
+    return value;
+}
+export class ListView {
+    viewport;
+    items;
+    selected;
+    gap;
+    context;
+    constructor(viewport, items, selected, options = {}) {
+        this.viewport = viewport;
+        this.items = items;
+        this.selected = selected;
+        this.gap = lineCount("gap", options.gap ?? 0);
+        this.context = lineCount("context", options.context ?? 0);
+        // An empty list's selection is 0: there is nothing for it to name.
+        if (!Number.isInteger(selected) || selected < 0 || selected >= Math.max(1, items.length)) {
+            throw new RangeError(`ListView: selected ${selected} is not an index of ${items.length} items`);
+        }
+    }
+    *render(rawOptions) {
+        const bounded = withBoundedWidth(rawOptions, this);
+        const { height: _height, ...rest } = bounded;
+        const options = { ...rest, maxWidth: this.viewport.contentWidth(rest.maxWidth) };
+        const gap = Array.from({ length: this.gap }, () => []);
+        const drawn = this.items.map((item) => Segment.splitLines(item.render(options)));
+        // The gap sits between items, so every item before the selected one
+        // brings its lines and one gap.
+        const start = drawn.slice(0, this.selected).reduce((total, item) => total + item.length + this.gap, 0);
+        const end = start + (drawn[this.selected]?.length ?? 0);
+        const lines = drawn.flatMap((item, i) => (i === 0 ? item : [...gap, ...item]));
+        this.viewport.content = {
+            *render() {
+                for (const line of lines) {
+                    yield* line;
+                    yield Segment.line();
+                }
+            },
+        };
+        // A range reaching past either end is clamped by the viewport, which holds
+        // its offset to the lines that exist. Followed, not ensured: the wheel can
+        // scroll away from the selection until the selection moves.
+        this.viewport.follow(start - this.context, end + this.context);
+        yield* this.viewport.render(bounded);
+    }
+    measure(rawOptions) {
+        // Stacked, the items are as wide as the widest of them, plus whatever
+        // gutter the viewport's scrollbar takes. `withCellWidth` and not
+        // `withBoundedWidth`: the bounded parse asks this very method.
+        const options = withCellWidth(rawOptions);
+        const contentWidth = this.viewport.contentWidth(options.maxWidth);
+        const gutter = this.viewport.gutter;
+        const items = measureRenderables({ ...options, maxWidth: contentWidth }, this.items);
+        return new Measurement(items.minimum + gutter, items.maximum + gutter).withMaximum(options.maxWidth);
+    }
+}

package/dist/renderables/live.d.ts

@@ -1,40 +1,62 @@
 /**
  * Live — animates a portion of the terminal by continuously re-rendering.
  *
- * Two modes:
- * - **Inline** (default): clears and redraws N lines in the current scroll
- *   region. Good for spinners/progress bars below other output.
+ * Two modes, each painting every frame over the last in place
+ * (`core/paint`):
+ * - **Inline** (default): the frame starts at the cursor's line and keeps its
+ *   own height. Good for spinners/progress bars below other output.
  * - **Alt-screen** (`altScreen: true`): enters the alternate screen buffer
- *   on start, cursor-homes on each refresh (no clear flicker), and restores
- *   the original buffer on stop. The screen is the frame's region, so a
- *   `Layout` fills it. Good for full-screen TUI apps.
+ *   on start and restores the original buffer on stop. The screen is the
+ *   frame's region, so a `Layout` fills it. Good for full-screen TUI apps.
+ *
+ * On a console that is not interactive — a file, a pipe, a CI log — neither
+ * mode paints: what is printed goes out plain, and the frame is written once,
+ * when the display stops, as Rich's `Live` does.
+ *
+ * Live is not built on `App`, though both take a terminal, paint a frame over
+ * the last and hand the terminal back. That much is the `Painter`'s, and both
+ * hold one. The rest differs in who owns what. An `App` owns its terminal: it
+ * starts and stops a `TerminalHost`, sets raw mode, reads keys and pointers,
+ * suspends, and builds its own `Console` from the host. A `Live` owns none of
+ * that. It draws into a `Console` its caller owns and goes on writing
+ * through — a sink that may be a file, whose every other write has to step
+ * around the frame (`Console.claimLiveRegion`) — and it reads no input. An
+ * `App` over that console would need a host that cannot start, stop, read or
+ * suspend, and a second owner of the console's writes.
  */
+import { type Clock } from "../core/clock.js";
 import { Console } from "../core/console.js";
 import { type Renderable } from "../core/protocol.js";
 export interface LiveOptions {
+    /** Frames a second while auto-refreshing: positive and finite, fractional included. */
     refreshPerSecond?: number;
+    /** What the auto-refresh ticks on. The platform's, unless given. */
+    clock?: Clock;
     autoRefresh?: boolean;
     transient?: boolean;
     console?: Console;
     verticalOverflow?: "crop" | "ellipsis" | "visible";
     /** When true, Live enters the alternate screen buffer on start() and
-     *  restores the original on stop(). Refresh uses cursor-home instead of
-     *  cursor-up-and-clear, eliminating flicker for full-screen layouts. */
+     *  restores the original on stop(). The screen is the frame's region, so
+     *  a full-screen layout fills it. */
     altScreen?: boolean;
 }
 export declare class Live {
     private _renderable;
     private _console;
-    private _refreshPerSecond;
+    private readonly _rate;
+    private readonly _clock;
     private _autoRefresh;
     private _transient;
     private _verticalOverflow;
-    private _altScreen;
-    private _timer;
-    private _lastLineCount;
-    private _started;
-    private _firstRefresh;
+    private readonly _painter;
+    private _stopTicking;
+    private _held;
     constructor(renderable?: Renderable, options?: LiveOptions);
+    /**
+     * The console to print through while this Live runs: what it prints lands
+     * above an inline frame. The alternate screen is all frame, and paints over it.
+     */
     get console(): Console;
     get renderable(): Renderable | undefined;
     start(): void;
@@ -43,8 +65,10 @@ export declare class Live {
         refresh?: boolean;
     }): void;
     refresh(): void;
+    private _frame;
+    private _stepAround;
+    private _paint;
+    private _screen;
     private _overflow;
-    private _erase;
     private _release;
-    private _writeCursorControl;
 }