@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/renderables/columns.d.ts

@@ -1,7 +1,14 @@
 /**
  * Columns — arranges renderables in a multi-column layout.
+ *
+ * A port of Rich's `Columns`. What it decides is how many columns, and which
+ * item goes in which cell. Everything after that — how wide each column is, how
+ * far apart, what `expand` does, how rows are separated — is the grid's: the
+ * items are laid out as a `Table.grid`, as the reference lays them out.
+ * [LAW:one-source-of-truth] A second copy of that geometry here is how the two
+ * drifted: an empty item's column was drawn with no width where the grid draws one cell.
  */
-import { Segment } from "../core/segment.js";
+import type { Segment } from "../core/segment.js";
 import type { PaddingDimensions } from "./padding.js";
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 export interface ColumnsOptions {
@@ -17,45 +24,54 @@ export declare class Columns implements Renderable, Measurable {
     readonly equal: boolean;
     readonly colWidth: number | undefined;
     readonly columnFirst: boolean;
-    readonly gutterWidth: number;
+    private readonly padding;
     constructor(items?: Iterable<unknown>, options?: ColumnsOptions);
     render(rawOptions: RenderOptions): Iterable<Segment>;
+    measure(rawOptions: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
     /**
-     * The requested width divided into columns, once.
+     * The items at the width offered, as the reference's grid: `_layout`'s
+     * cells in a `Table.grid`.
+     *
+     * [LAW:single-enforcer] `render` draws this and `measure` reports its width,
+     * so the two cannot disagree about how wide a Columns is.
      *
-     * [LAW:single-enforcer] The three modes disagree only about how many columns
-     * there are and how wide each one is, so they disagree in one place. `render`
-     * lays out against this division and `_naturalWidth` is the width at which it
-     * comes out as one row of every item.
+     * A declared `width` is each column's natural width rather than a Table
+     * column `width`, which this port never stretches: the reference's grid
+     * stretches a Columns' declared width under `expand` like any other.
+     * `equal` holds every item to the widest, Rich's `Constrain`; without it
+     * the cap is `undefined` and holds nothing.
      */
-    private _divide;
+    private _grid;
     /**
-     * The widest any one item wants to be.
+     * How many columns fit the width offered, and which item goes in each cell,
+     * decided the way Rich's `Columns` decides them.
      *
-     * An item that cannot measure itself wants the offer, which is what `Panel`,
-     * `Padding`, `Layout` and `Tree` all answer for the same case — and under an
-     * unbounded offer that is `Infinity`, so `withBoundedWidth` throws and says
-     * the request was unanswerable. Counting it as one cell instead reported a
-     * natural width of 1, which resolved an unbounded offer to a single column and
-     * cropped forty cells of content down to `"x"` with no error at all.
+     * Every item carries a width. It is what the item measures, or the declared
+     * `width` for all of them. `equal` counts every item as the widest when
+     * choosing how many columns fit, and the grid still sizes each column by
+     * what is in it — which is why an `equal` layout is not a grid of equal
+     * columns, in the reference or here.
+     *
+     * The count starts at one column per item and drops whenever the columns
+     * filled so far, and the gaps between them, pass the width offered. Two
+     * columns stand the wider of the padding's left and right sides apart, which
+     * is what the collapsed grid leaves between them. One departure from the
+     * reference: a declared `width` is searched the same way rather than by
+     * `max_width // (width + gap)`, which laid out empty trailing columns and
+     * charged the last column a gap it does not have.
      */
-    private _itemWidth;
+    private _layout;
     /**
      * The declared column width, bounded by the width offered.
      *
-     * [LAW:single-enforcer] A declared width is what a column asks for, not what
-     * it takes — the contract `Table._outerWidth` keeps for a declared table
-     * width. Read by `_divide` for render and by `_naturalWidth` for measure, so
-     * the two answer from one number: laid out at the raw declared width, a
-     * six-cell column offered three emitted six-cell lines while `measure`
-     * reported three, and the terminal's soft wrap took the frame of everything
-     * printed after it.
+     * A declared width is what a column asks for, not what it takes — the
+     * contract `Table._outerWidth` keeps for a declared table width. Laid out at
+     * the raw declared width, a six-cell column offered three emitted six-cell
+     * lines while `measure` reported three, and the terminal's soft wrap took the
+     * frame of everything printed after it.
      */
     private _declaredWidth;
-    /** The width at which every item sits on one row: n columns and the gutters between them. */
-    private _naturalWidth;
-    measure(rawOptions: RenderOptions): {
-        minimum: number;
-        maximum: number;
-    };
 }

package/dist/renderables/columns.js

@@ -1,18 +1,47 @@
 /**
  * Columns — arranges renderables in a multi-column layout.
+ *
+ * A port of Rich's `Columns`. What it decides is how many columns, and which
+ * item goes in which cell. Everything after that — how wide each column is, how
+ * far apart, what `expand` does, how rows are separated — is the grid's: the
+ * items are laid out as a `Table.grid`, as the reference lays them out.
+ * [LAW:one-source-of-truth] A second copy of that geometry here is how the two
+ * drifted: an empty item's column was drawn with no width where the grid draws one cell.
  */
-import { Segment } from "../core/segment.js";
 import { Measurement } from "../core/measure.js";
-import { isMeasurable, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { normalizePadding } from "./padding.js";
+import { withBoundedWidth, withCellWidth } from "../core/protocol.js";
 import { cellCount } from "../core/cells.js";
-import { embed } from "./embed.js";
+import { EmbeddedText, embed } from "./embed.js";
+import { Constrain } from "./constrain.js";
+import { Table } from "./table.js";
+/**
+ * The item in slot `slot` of the grid for `count` columns, counting row by row;
+ * `undefined` is a slot no item fills. Constant time, so a search that stops at
+ * the first slot that overflows pays for no slot after it.
+ */
+function slotItem(slot, items, count, columnFirst) {
+    const row = Math.floor(slot / count);
+    const col = slot % count;
+    // Column-first fills each column top to bottom, and the columns that take one
+    // item more than the rest are the leading ones — Rich's `column_lengths`.
+    const base = Math.floor(items / count);
+    const extra = items % count;
+    const length = base + (col < extra ? 1 : 0);
+    const index = !columnFirst ? slot : row < length ? col * base + Math.min(col, extra) + row : items;
+    return index < items ? index : undefined;
+}
+/** How many slots the grid for `count` columns has: every row full, the last one padded. */
+function slotCount(items, count) {
+    return Math.ceil(items / count) * count;
+}
 export class Columns {
     renderables;
     expand;
     equal;
     colWidth;
     columnFirst;
-    gutterWidth;
+    padding;
     constructor(items, options) {
         this.renderables = items ? [...items].map(embed) : [];
         this.expand = options?.expand ?? false;
@@ -26,127 +55,137 @@ export class Columns {
         // read it as a declared zero.
         this.colWidth = options?.width === undefined ? undefined : cellCount(options.width);
         this.columnFirst = options?.columnFirst ?? false;
-        this.gutterWidth = 2; // default gutter between columns
+        // [LAW:parse-dont-validate] Rich's default is `(0, 1)`: one cell between
+        // columns and none between rows.
+        this.padding = normalizePadding(options?.padding ?? [0, 1]);
     }
     *render(rawOptions) {
-        const items = this.renderables;
-        if (items.length === 0)
+        if (this.renderables.length === 0)
             return;
-        // The parsed options, not just a parsed local: `_divide` hands them to
+        // The parsed options, not just a parsed local: `_layout` hands them to
         // `Measurement.get`, and a raw NaN reaching it comes back as a NaN item
-        // width, then a NaN column count, then `Invalid array length` out of
-        // `new Array(numCols)` before a single column is laid out. An unbounded
-        // width reaches the same `new Array` by the same route, which is why the
-        // parse here is the bounded one.
+        // width, then a NaN column count, then `Invalid array length` before a
+        // single column is laid out. An unbounded width reaches the same place by
+        // the same route, which is why the parse here is the bounded one.
         const options = withBoundedWidth(rawOptions, this);
-        const { numCols, colWidths } = this._divide(options);
-        // Layout items into rows
-        const numRows = Math.ceil(items.length / numCols);
-        // [LAW:types-are-the-program] The element type is Renderable — any number
-        // of lines. Each grid cell renders to its full set of lines; an out-of-range
-        // slot (the last row is rarely full) is an empty cell. mergeHorizontal then
-        // stacks every row of every cell line-by-line, so multi-line children
-        // (Panels, Tables) compose instead of being truncated to their first row.
-        for (let row = 0; row < numRows; row++) {
-            const cells = colWidths.map((width, col) => {
-                const idx = this.columnFirst ? col * numRows + row : row * numCols + col;
-                const item = items[idx];
-                const lines = item === undefined
-                    ? []
-                    : Segment.splitLines([
-                        ...item.render({ ...options, maxWidth: width, height: stackedHeight(options.height) }),
-                    ]);
-                return { lines, width };
-            });
-            yield* Segment.mergeHorizontal(cells, this.gutterWidth);
-        }
+        yield* this._grid(options).render(options);
+    }
+    measure(rawOptions) {
+        // The maximum is the grid's, which reports its width before `expand`: a
+        // stretch is what a Columns does with a width it is given, not a width it
+        // asks for. Reported as the offer instead, `Panel` in fit mode drew a
+        // 40-cell frame around five cells of content and an unbounded offer came
+        // back unbounded.
+        //
+        // A floor of one cell is what Columns asks for, since it can always fall
+        // back to one column, and the ceiling wins: a bare `minimum: 1` measured
+        // into no width at all reported the range 1..0 — a floor above its own
+        // ceiling, which the parent that asked cannot divide.
+        const parsed = withCellWidth(rawOptions);
+        if (this.renderables.length === 0)
+            return { minimum: 0, maximum: 0 };
+        const { maximum } = this._grid(parsed).measure(parsed);
+        return { minimum: Math.min(1, maximum), maximum };
     }
     /**
-     * The requested width divided into columns, once.
+     * The items at the width offered, as the reference's grid: `_layout`'s
+     * cells in a `Table.grid`.
+     *
+     * [LAW:single-enforcer] `render` draws this and `measure` reports its width,
+     * so the two cannot disagree about how wide a Columns is.
      *
-     * [LAW:single-enforcer] The three modes disagree only about how many columns
-     * there are and how wide each one is, so they disagree in one place. `render`
-     * lays out against this division and `_naturalWidth` is the width at which it
-     * comes out as one row of every item.
+     * A declared `width` is each column's natural width rather than a Table
+     * column `width`, which this port never stretches: the reference's grid
+     * stretches a Columns' declared width under `expand` like any other.
+     * `equal` holds every item to the widest, Rich's `Constrain`; without it
+     * the cap is `undefined` and holds nothing.
      */
-    _divide(options) {
-        const maxWidth = options.maxWidth;
-        const gutter = this.gutterWidth;
+    _grid(options) {
+        const { columns, rows, widest } = this._layout(options);
+        const grid = Table.grid({ padding: this.padding, expand: this.expand });
         const declared = this._declaredWidth(options);
-        if (declared !== undefined) {
-            const numCols = Math.max(1, Math.floor((maxWidth + gutter) / (declared + gutter)));
-            return { numCols, colWidths: new Array(numCols).fill(declared) };
+        for (let col = 0; col < columns; col++) {
+            grid.addColumn(undefined, { minWidth: declared, maxWidth: declared });
         }
-        if (this.equal) {
-            const itemWidth = this._itemWidth(options);
-            const numCols = Math.max(1, Math.floor((maxWidth + gutter) / (itemWidth + gutter)));
-            const equalWidth = Math.floor((maxWidth - gutter * (numCols - 1)) / numCols);
-            return { numCols, colWidths: new Array(numCols).fill(equalWidth) };
+        const cap = this.equal ? widest : undefined;
+        // A string item is read here, under the options Columns is drawn with,
+        // before the grid gets it: Rich's `Columns` reads its strings through
+        // `render_str`, so they are highlighted where a table cell's are not.
+        const items = this.renderables.map((item) => (item instanceof EmbeddedText ? item.text(options) : item));
+        for (const row of rows) {
+            grid.addRow(...row.map((index) => (index === undefined ? "" : new Constrain(items[index], cap))));
         }
-        // Auto: as many columns as the widest item fits into, capped at the item
-        // count. Sized from the content rather than from a flat four cells per
-        // column, because `_naturalWidth` below is the inverse of *this* expression
-        // and a constant has no inverse: six two-cell items reported a natural
-        // width of 22 and then wrapped into two rows at 22, since `floor(22 / 4)`
-        // is five columns no matter how narrow the items are.
-        const itemWidth = this._itemWidth(options);
-        const numCols = Math.min(this.renderables.length, Math.max(1, Math.floor((maxWidth + gutter) / (itemWidth + gutter))));
-        const colW = Math.floor((maxWidth - gutter * (numCols - 1)) / numCols);
-        return { numCols, colWidths: new Array(numCols).fill(colW) };
+        return grid;
     }
     /**
-     * The widest any one item wants to be.
+     * How many columns fit the width offered, and which item goes in each cell,
+     * decided the way Rich's `Columns` decides them.
      *
-     * An item that cannot measure itself wants the offer, which is what `Panel`,
-     * `Padding`, `Layout` and `Tree` all answer for the same case — and under an
-     * unbounded offer that is `Infinity`, so `withBoundedWidth` throws and says
-     * the request was unanswerable. Counting it as one cell instead reported a
-     * natural width of 1, which resolved an unbounded offer to a single column and
-     * cropped forty cells of content down to `"x"` with no error at all.
+     * Every item carries a width. It is what the item measures, or the declared
+     * `width` for all of them. `equal` counts every item as the widest when
+     * choosing how many columns fit, and the grid still sizes each column by
+     * what is in it — which is why an `equal` layout is not a grid of equal
+     * columns, in the reference or here.
+     *
+     * The count starts at one column per item and drops whenever the columns
+     * filled so far, and the gaps between them, pass the width offered. Two
+     * columns stand the wider of the padding's left and right sides apart, which
+     * is what the collapsed grid leaves between them. One departure from the
+     * reference: a declared `width` is searched the same way rather than by
+     * `max_width // (width + gap)`, which laid out empty trailing columns and
+     * charged the last column a gap it does not have.
      */
-    _itemWidth(options) {
-        let widest = 1;
-        for (const item of this.renderables) {
-            widest = Math.max(widest, isMeasurable(item)
-                ? Measurement.get(options, item).maximum
-                : options.maxWidth);
-        }
-        return widest;
+    _layout(options) {
+        const count = this.renderables.length;
+        const maxWidth = options.maxWidth;
+        const [, right, , left] = this.padding;
+        const gap = Math.max(left, right);
+        const declared = this._declaredWidth(options);
+        // An item that cannot measure itself wants the whole offer. Counting it as one
+        // cell instead resolved an unbounded offer to a single column and cropped
+        // forty cells of content down to `"x"` with no error at all.
+        const sizes = this.renderables.map((item) => declared ?? Measurement.get(options, item).maximum);
+        // A fold, not `Math.max(...sizes)`: spreading one argument per item
+        // overflows the call stack at a few hundred thousand items.
+        const widest = sizes.reduce((w, size) => Math.max(w, size), 0);
+        const fits = this.equal ? sizes.map(() => widest) : sizes;
+        // One attempt either fits in the offer or names the smaller count to try
+        // next. `total` is the columns so far and the gaps between them, kept as
+        // the widths grow so that a slot costs the same however many columns came
+        // before it.
+        const attempt = (columns) => {
+            const widths = [];
+            let total = 0;
+            for (let slot = 0; slot < slotCount(count, columns); slot++) {
+                const col = slot % columns;
+                const index = slotItem(slot, count, columns, this.columnFirst);
+                const held = widths[col];
+                const width = Math.max(held ?? 0, index === undefined ? 0 : fits[index]);
+                total += width - (held ?? 0) + (held === undefined && col > 0 ? gap : 0);
+                widths[col] = width;
+                // Never zero: no item measures wider than the offer, so the first
+                // column alone always fits.
+                if (total > maxWidth)
+                    return widths.length - 1;
+            }
+            return columns;
+        };
+        let columns = count;
+        for (let next = attempt(columns); next < columns; next = attempt(columns))
+            columns = next;
+        const rows = Array.from({ length: slotCount(count, columns) / columns }, (_, row) => Array.from({ length: columns }, (_, col) => slotItem(row * columns + col, count, columns, this.columnFirst)));
+        return { columns, rows, widest };
     }
     /**
      * The declared column width, bounded by the width offered.
      *
-     * [LAW:single-enforcer] A declared width is what a column asks for, not what
-     * it takes — the contract `Table._outerWidth` keeps for a declared table
-     * width. Read by `_divide` for render and by `_naturalWidth` for measure, so
-     * the two answer from one number: laid out at the raw declared width, a
-     * six-cell column offered three emitted six-cell lines while `measure`
-     * reported three, and the terminal's soft wrap took the frame of everything
-     * printed after it.
+     * A declared width is what a column asks for, not what it takes — the
+     * contract `Table._outerWidth` keeps for a declared table width. Laid out at
+     * the raw declared width, a six-cell column offered three emitted six-cell
+     * lines while `measure` reported three, and the terminal's soft wrap took the
+     * frame of everything printed after it.
      */
     _declaredWidth(options) {
         return this.colWidth === undefined ? undefined : Math.min(this.colWidth, options.maxWidth);
     }
-    /** The width at which every item sits on one row: n columns and the gutters between them. */
-    _naturalWidth(options) {
-        const count = this.renderables.length;
-        if (count === 0)
-            return 0;
-        const width = this._declaredWidth(options) ?? this._itemWidth(options);
-        return count * width + this.gutterWidth * (count - 1);
-    }
-    measure(rawOptions) {
-        // A floor of one cell is what Columns asks for; the ceiling is what it was
-        // offered, and the ceiling wins. Stated as a bare `minimum: 1`, a Columns
-        // measured into no width at all reported the range 1..0 — a floor above
-        // its own ceiling, which the parent that asked cannot divide.
-        //
-        // The ceiling is not the whole answer, though: reported as the offer alone,
-        // a Columns claimed every cell it was shown, so `Panel` in fit mode drew a
-        // 40-cell frame around five cells of content and an unbounded offer came
-        // back unbounded.
-        const parsed = withCellWidth(rawOptions);
-        const maximum = Math.min(this._naturalWidth(parsed), parsed.maxWidth);
-        return { minimum: Math.min(1, maximum), maximum };
-    }
 }

package/dist/renderables/constrain.js

@@ -2,7 +2,6 @@
  * Constrain — wraps a renderable and constrains its maximum width.
  */
 import { Measurement } from "../core/measure.js";
-import { isMeasurable } from "../core/protocol.js";
 export class Constrain {
     renderable;
     width;
@@ -22,16 +21,11 @@ export class Constrain {
         yield* this.renderable.render(innerOptions);
     }
     measure(options) {
-        if (isMeasurable(this.renderable)) {
-            const measurement = Measurement.get(options, this.renderable);
-            const maxWidth = this.width !== undefined
-                ? Math.min(this.width, options.maxWidth)
-                : options.maxWidth;
-            return {
-                minimum: measurement.minimum,
-                maximum: Math.min(measurement.maximum, maxWidth),
-            };
-        }
-        return { minimum: 1, maximum: options.maxWidth };
+        // Measured at the width it will be drawn at, as Rich's `update_width` does;
+        // `Measurement.get` then holds the answer inside that offer.
+        const maxWidth = this.width !== undefined
+            ? Math.min(this.width, options.maxWidth)
+            : options.maxWidth;
+        return Measurement.get({ ...options, maxWidth }, this.renderable);
     }
 }

package/dist/renderables/effect.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Effected — a renderable whose finished cells' colours pass through an
+ * effect at a moment `t`.
+ *
+ * An effect is one pure function: a cell's colours, where the cell is, and a
+ * time in, the cell's new colours out. Shimmer, pulse, fade and dissolve are
+ * all this one shape, differing by what the function does with its inputs
+ * [LAW:one-type-per-behavior]; two effects stack by nesting one wrapper in
+ * another, which is the same as calling one after the other.
+ *
+ * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
+ * clock read. Whoever draws frames builds the view for each frame's `t`, so
+ * the same `t` always draws the same bytes, at 30 frames a second or one
+ * every two seconds.
+ *
+ * What an effect may not do is the contract this module holds:
+ *
+ * - It changes how cells look, never which cells exist or who drew them. The
+ *   child's text is walked by grapheme cluster, so a wide glyph is one cell
+ *   to the effect and is never cut, and a run cut out of a segment keeps that
+ *   segment's link and meta and carries its anchor shifted to the run's first
+ *   cell (`Style.shiftedBy`), so hit testing still finds the owner.
+ * - A cell whose colours come back unchanged keeps its original `ColorSpec`,
+ *   and a segment whose every cell is unchanged is yielded as it was, so the
+ *   identity effect is byte-identical. Neighbouring cells given equal colours
+ *   stay one segment: a segment is cut only where the colours change.
+ * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
+ *   string, so no frame adds an entry to a parse cache.
+ * - With no colour output (`colorSystem: null`) there is nothing for an
+ *   effect to change, and the child's segments pass through untouched.
+ *
+ * Positions are the child's own: row and column count from the top-left of
+ * what the child drew, so a sweep crosses the element, not the screen.
+ */
+import { type ColorRgba, type TerminalTheme } from "../core/color.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import { Segment } from "../core/segment.js";
+/**
+ * A cell's foreground and background as they appear on screen — the glyph's
+ * colour and the colour behind it — which are the colours an effect moves.
+ * Under `reverse` they are the style's two colours swapped.
+ */
+export interface CellColors {
+    readonly fg: ColorRgba;
+    readonly bg: ColorRgba;
+}
+/**
+ * Where a cell is in the output of the renderable an effect wraps, and its
+ * seed: a number in [0, 1) that is the same for that cell on every frame, for
+ * an effect that varies cell by cell (a per-cell offset in time, a sparkle).
+ */
+export interface EffectCell {
+    readonly row: number;
+    readonly col: number;
+    readonly seed: number;
+}
+/** A cell's colours at time `t`, in seconds. Return `colors` to leave it be. */
+export type Effect = (colors: CellColors, cell: EffectCell, t: number) => CellColors;
+export interface EffectedOptions {
+    /** The moment to draw, in seconds. */
+    readonly t: number;
+    /**
+     * Names the element for its seeds, so two elements showing the same text do
+     * not twinkle in lockstep. The same key gives the same seeds on every frame.
+     */
+    readonly key: string;
+    /**
+     * The terminal the frame is drawn on: the colours a cell that sets none is
+     * drawn in, and the sixteen an ANSI colour names. The terminal's own palette
+     * is never queried, so the caller says what it is.
+     */
+    readonly theme: TerminalTheme;
+}
+export declare class Effected implements Renderable, Measurable {
+    readonly renderable: Renderable;
+    readonly effect: Effect;
+    readonly t: number;
+    readonly key: string;
+    readonly theme: TerminalTheme;
+    constructor(renderable: Renderable, effect: Effect, options: EffectedOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    /**
+     * The style that draws a run's slot colours `to` where the segment drew
+     * `from` with `wire`: a slot the effect left alone keeps its written spec,
+     * and a moved one is laid on what is beneath it — the ground on
+     * `SURFACE_BLACK`, the glyph on that ground, as the writer lays any
+     * translucent colour (`Style.drawnColors`) — then drawn in the colour nearest it at `depth`
+     * that the terminal shows (`ColorSpec.matchOn`), so a colour moved a little
+     * off a theme slot or the default colour is still drawn as that one.
+     */
+    private respec;
+    /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
+    private seed;
+}