@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/renderables/padding.d.ts

@@ -5,7 +5,7 @@ import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import type { RichText } from "../core/text.js";
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
-export type PaddingDimensions = number | [number, number] | [number, number, number, number];
+export type PaddingDimensions = number | readonly [number, number] | readonly [number, number, number, number];
 /**
  * Parses the shapes a caller may write padding in — one number, a vertical/
  * horizontal pair, or all four sides — into the four-sided form every
@@ -18,26 +18,14 @@ export type PaddingDimensions = number | [number, number] | [number, number, num
  * to reach the renderers, where `Panel` drew content rows wider than its own
  * border and `Table` threw outright.
  */
-export declare function normalizePadding(padding: PaddingDimensions): [number, number, number, number];
-/** The three spans of a padded row, summing to exactly the requested width. */
-interface PaddingGeometry {
-    readonly left: number;
-    readonly contentWidth: number;
-    readonly right: number;
-}
+export declare function normalizePadding(padding: PaddingDimensions): readonly [number, number, number, number];
 /**
- * Divides the requested width once into the three spans a padded row is made
- * of, in the order they are worth spending cells on.
- *
- * The three used to be derived separately and disagree where it matters:
- * `render` took the canvas as `Math.max(1, maxWidth - left - right)`, which
- * clamps *up*, so a padding of 1 inside a 2-cell request drew 3-cell content
- * rows beside 2-cell blank rows — an open frame the terminal then soft-wraps.
- * Content takes its first cell before padding takes any, for the reason
- * `layoutPanel` gives: a squeeze should cost you the decoration, not the thing
- * being decorated.
+ * The width a padding leaves its content: what the request holds once both
+ * sides are paid for, as Rich's `Padding` divides it. The sides are paid in
+ * full, so a request too narrow for them leaves the content no column, and it
+ * is drawn as nothing — Rich's `Console.render` under one column.
  */
-export declare function layoutPadding(outerWidth: number, leftWanted: number, rightWanted: number): PaddingGeometry;
+export declare function paddedContentWidth(outerWidth: number, left: number, right: number): number;
 export declare class Padding implements Renderable, Measurable {
     readonly renderable: Renderable;
     readonly top: number;
@@ -56,4 +44,3 @@ export declare class Padding implements Renderable, Measurable {
         maximum: number;
     };
 }
-export {};

package/dist/renderables/padding.js

@@ -5,7 +5,7 @@ import { Segment } from "../core/segment.js";
 import { cellCount } from "../core/cells.js";
 import { NULL_STYLE } from "../core/style.js";
 import { Measurement } from "../core/measure.js";
-import { fitHeight, getStyle, insetHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { fitHeight, getStyle, insetHeight, render, withBoundedWidth, withCellWidth } from "../core/protocol.js";
 import { embed } from "./embed.js";
 /**
  * Parses the shapes a caller may write padding in — one number, a vertical/
@@ -41,32 +41,13 @@ export function normalizePadding(padding) {
     return [side(sides[0]), side(sides[1]), side(sides[2]), side(sides[3])];
 }
 /**
- * Divides the requested width once into the three spans a padded row is made
- * of, in the order they are worth spending cells on.
- *
- * The three used to be derived separately and disagree where it matters:
- * `render` took the canvas as `Math.max(1, maxWidth - left - right)`, which
- * clamps *up*, so a padding of 1 inside a 2-cell request drew 3-cell content
- * rows beside 2-cell blank rows — an open frame the terminal then soft-wraps.
- * Content takes its first cell before padding takes any, for the reason
- * `layoutPanel` gives: a squeeze should cost you the decoration, not the thing
- * being decorated.
+ * The width a padding leaves its content: what the request holds once both
+ * sides are paid for, as Rich's `Padding` divides it. The sides are paid in
+ * full, so a request too narrow for them leaves the content no column, and it
+ * is drawn as nothing — Rich's `Console.render` under one column.
  */
-export function layoutPadding(outerWidth, leftWanted, rightWanted) {
-    let budget = cellCount(outerWidth);
-    const take = (want) => {
-        const got = Math.min(want, budget);
-        budget -= got;
-        return got;
-    };
-    const firstContentCell = take(1);
-    const left = take(leftWanted);
-    const right = take(rightWanted);
-    return { left, contentWidth: firstContentCell + budget, right };
-}
-/** The full width of a padded row — the division, added back up. */
-function rowWidth(geometry) {
-    return geometry.left + geometry.contentWidth + geometry.right;
+export function paddedContentWidth(outerWidth, left, right) {
+    return cellCount(cellCount(outerWidth) - left - right);
 }
 export class Padding {
     renderable;
@@ -94,10 +75,10 @@ export class Padding {
         // rows instead left the content rows ragged under a full-width blank row,
         // and a `style` ground with holes down its right-hand side.
         const width = this.expand ? options.maxWidth : Measurement.get(options, this).maximum;
-        const geometry = layoutPadding(width, this.left, this.right);
+        const contentWidth = paddedContentWidth(width, this.left, this.right);
         const innerOptions = {
             ...options,
-            maxWidth: geometry.contentWidth,
+            maxWidth: contentWidth,
             height: insetHeight(options.height, this.top + this.bottom),
         };
         const resolved = getStyle(options, this.style);
@@ -105,35 +86,33 @@ export class Padding {
         // The style is the ground the content is drawn on, not only the spaces
         // around it — Rich's `render_lines(..., style=style)`. Applied to the
         // padding alone, a background left a hole behind the content.
-        const segments = [...Segment.applyStyle(this.renderable.render(innerOptions), style)];
-        const lines = fitHeight(Segment.splitLines(segments), innerOptions.height);
-        // Zero-length spans need no branch to suppress: the wire boundary drops
-        // empty segments, so a padding the width could not afford emits nothing.
-        const leftPad = new Segment(" ".repeat(geometry.left), style);
-        const rightPad = new Segment(" ".repeat(geometry.right), style);
-        const blankLine = new Segment(" ".repeat(rowWidth(geometry)), style);
-        for (let i = 0; i < this.top; i++) {
-            yield blankLine;
-            yield Segment.line();
-        }
+        const drawn = Segment.splitLines(Segment.applyStyle(render(this.renderable, innerOptions), style));
+        const lines = fitHeight(drawn, innerOptions.height);
+        const leftPad = new Segment(" ".repeat(this.left), style);
+        const rightPad = new Segment(" ".repeat(this.right), style);
+        for (let i = 0; i < this.top; i++)
+            yield* row([]);
+        // Every row is the block's width: content rows pad and crop the content to
+        // its canvas — a child that ignored the canvas it was handed (a Table at
+        // its natural width) would otherwise burst the padding — and the row to
+        // the block, so the rows a region asks for under sides the width cannot
+        // hold are cut at its edge rather than drawn past it.
         for (const line of lines) {
-            yield leftPad;
-            // Crops as well as pads: a child that ignored the canvas it was handed
-            // (a Table at its natural width) would otherwise burst the padding.
-            yield* Segment.adjustLineLength(line, geometry.contentWidth, style);
-            yield rightPad;
-            yield Segment.line();
+            yield* row([leftPad, ...Segment.adjustLineLength(line, contentWidth, style), rightPad]);
         }
-        for (let i = 0; i < this.bottom; i++) {
-            yield blankLine;
+        for (let i = 0; i < this.bottom; i++)
+            yield* row([]);
+        function* row(cells) {
+            yield* Segment.adjustLineLength(cells, width, style);
             yield Segment.line();
         }
     }
     measure(rawOptions) {
         const options = withCellWidth(rawOptions);
-        const geometry = layoutPadding(options.maxWidth, this.left, this.right);
-        const overhead = geometry.left + geometry.right;
-        const measurement = Measurement.get({ ...options, maxWidth: geometry.contentWidth }, this.renderable);
+        const overhead = this.left + this.right;
+        // Content left no column measures as nothing, so the padding asks for the
+        // whole offer — Rich's `Padding.__rich_measure__`.
+        const measurement = Measurement.get({ ...options, maxWidth: paddedContentWidth(options.maxWidth, this.left, this.right) }, this.renderable);
         // The ceiling is what was offered, and it wins over what the child asks
         // for: a range whose floor sits above its own ceiling — this returned
         // {8, 8} for three cells of padding inside a two-cell offer — is one no

package/dist/renderables/panel.d.ts

@@ -8,16 +8,18 @@ import { RichText } from "../core/text.js";
 import type { PaddingDimensions } from "./padding.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 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;
@@ -58,39 +60,35 @@ export declare class Panel implements Renderable, Measurable {
     readonly titleStyle: string | Style | undefined;
     readonly subtitleStyle: string | Style | undefined;
     readonly width: number | undefined;
-    readonly padding: [number, number, number, number];
     private readonly _titleLabel;
     private readonly _subtitleLabel;
-    constructor(content: string | RichText | Renderable, options?: PanelOptions);
-    render(rawOptions: RenderOptions): Iterable<Segment>;
     /**
-     * The wrapped renderable's lines, laid out on a canvas `contentWidth` cells
-     * wide. Below width 3 a panel is all frame and the canvas holds no lines —
-     * but the render still happens, because a `bottomRightAccessory` thunk
-     * fires at every width and reads state this render populates.
+     * What the frame is drawn around: the content inside its padding, on the
+     * panel's ground. Rich's `Panel` draws its body as this same `Padding`, so
+     * how a squeezed width divides between padding and content is answered once,
+     * by `Padding`, for both.
      */
-    private _renderContent;
-    /**
-     * One row of the panel body, cut where Rich cuts it: frame column, left
-     * padding, the content line made exactly `contentWidth` wide, right padding,
-     * frame column — each its own segment, so each its own SGR run.
-     *
-     * [LAW:single-enforcer] `adjustLineLength` is the one place the content's
-     * width is decided: content that rendered wider than its canvas (a `Table`
-     * at its natural width, say) is cropped back to it, and a short line is
-     * filled out to it, so the right padding always starts at the same column.
-     */
-    private _renderRow;
+    private readonly _body;
+    /** The padding inside the frame, top, right, bottom, left — the body's, read back. */
+    get padding(): readonly [number, number, number, number];
+    constructor(content: string | RichText | Renderable, options?: PanelOptions);
+    render(rawOptions: RenderOptions): Iterable<Segment>;
     /**
-     * A row of vertical padding: one blank run across the whole span, as Rich's
-     * `Padding` draws its blank lines, not a content row with nothing in it.
+     * 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`
+     * cells: `Padding` makes every row its block's width, cropping content that
+     * ignored its canvas. A span of no cells renders nothing, as Rich's
+     * `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` function is handed the rows it drew.
      */
-    private _renderPaddingRow;
+    private _renderBody;
     measure(rawOptions: RenderOptions): {
         minimum: number;
         maximum: number;
     };
-    /** The content plus its own frame, both read off the division it will render against. */
+    /** The body plus the frame around it, both read off the division it will render against. */
     private _contentRange;
     /** The cells the title's label takes, its padding included; none without a title. */
     private _labelWidth;

package/dist/renderables/panel.js

@@ -8,45 +8,22 @@ import { ROUNDED } from "../core/box.js";
 import { Measurement } from "../core/measure.js";
 import { RichText } from "../core/text.js";
 import { cutLabel, drawLabel, embed, inlineLabel } from "./embed.js";
-import { normalizePadding } from "./padding.js";
-import { drawable, fitHeight, getStyle, insetHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
-function layoutPanel(outerWidth, padding) {
-    const [, padRightWanted, , padLeftWanted] = padding;
+import { Padding } from "./padding.js";
+import { drawable, fitHeight, getStyle, insetHeight, render, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+function layoutPanel(outerWidth) {
     // Panel's one division point, and the width reaching it is not always one
     // this file produced: `_getPanelWidth` derives the fit-mode width from
     // `Measurement.get` on an arbitrary `Measurable`, so a renderable reporting a
     // negative maximum arrives here unparsed and reaches `repeat` as a negative
     // count.
-    let budget = cellCount(outerWidth);
-    const take = (want) => {
-        const got = Math.min(want, budget);
-        budget -= got;
-        return got;
-    };
-    const left = take(1);
-    const right = take(1);
-    const firstContentCell = take(1);
-    const padLeft = take(padLeftWanted);
-    const padRight = take(padRightWanted);
-    const contentWidth = firstContentCell + budget;
-    return {
-        left,
-        right,
-        padLeft,
-        contentWidth,
-        padRight,
-        spanWidth: padLeft + contentWidth + padRight,
-    };
+    const width = cellCount(outerWidth);
+    const left = Math.min(1, width);
+    const right = Math.min(1, width - left);
+    return { left, right, spanWidth: width - left - right };
 }
-/**
- * Every cell of a panel that is not content canvas. Read off the geometry
- * rather than recomputed as `2 + padLeft + padRight`, because the two differ
- * exactly where this panel is squeezed: a width that cannot afford its right
- * frame column or its padding does not spend cells on them, and a measurement
- * that assumed it did would report a minimum larger than its own maximum.
- */
-function frameOverhead(geometry) {
-    return geometry.left + geometry.right + geometry.padLeft + geometry.padRight;
+/** The cells a panel's frame takes from the width it is given. */
+function frameWidth(geometry) {
+    return geometry.left + geometry.right;
 }
 /**
  * How a title or subtitle string is read: always as markup and never
@@ -114,9 +91,20 @@ export class Panel {
     titleStyle;
     subtitleStyle;
     width;
-    padding;
     _titleLabel;
     _subtitleLabel;
+    /**
+     * What the frame is drawn around: the content inside its padding, on the
+     * panel's ground. Rich's `Panel` draws its body as this same `Padding`, so
+     * how a squeezed width divides between padding and content is answered once,
+     * by `Padding`, for both.
+     */
+    _body;
+    /** The padding inside the frame, top, right, bottom, left — the body's, read back. */
+    get padding() {
+        const body = this._body;
+        return [body.top, body.right, body.bottom, body.left];
+    }
     constructor(content, options) {
         this.renderable = embed(content);
         this.box = options?.box ?? ROUNDED;
@@ -131,7 +119,7 @@ export class Panel {
         this.titleStyle = options?.titleStyle;
         this.subtitleStyle = options?.subtitleStyle;
         this.width = options?.width;
-        this.padding = normalizePadding(options?.padding ?? [0, 1, 0, 1]);
+        this._body = new Padding(this.renderable, options?.padding ?? [0, 1, 0, 1], { style: this.style });
     }
     *render(rawOptions) {
         const options = withBoundedWidth(rawOptions, this);
@@ -140,72 +128,44 @@ export class Panel {
         // on, as Rich's is: the frame's style is the border style laid over it,
         // and the content is rendered on top of it. Applied to the padding alone,
         // "white on dark_blue" drew a blue ring with a hole where the text was.
-        const style = getStyle(options, this.style);
-        const borderStyle = style.add(getStyle(options, this.borderStyle));
+        const borderStyle = getStyle(options, this.style).add(getStyle(options, this.borderStyle));
         const border = borderStyle.isNull ? undefined : borderStyle;
-        const contentStyle = style.isNull ? undefined : style;
-        const geometry = layoutPanel(this._getPanelWidth(options), this.padding);
-        const [padTop, , padBottom] = this.padding;
-        const contentLines = this._renderContent(options, geometry.contentWidth, contentStyle);
+        const geometry = layoutPanel(this._getPanelWidth(options));
+        const bodyLines = this._renderBody(options, geometry.spanWidth);
         yield* this._renderTopBorder(options, box, geometry, border);
-        for (let i = 0; i < padTop; i++) {
-            yield* this._renderPaddingRow(box, geometry, border, contentStyle);
-        }
-        for (const line of contentLines) {
-            yield* this._renderRow(box, geometry, line, border, contentStyle);
-        }
-        for (let i = 0; i < padBottom; i++) {
-            yield* this._renderPaddingRow(box, geometry, border, contentStyle);
-        }
-        yield* this._renderBottomBorder(options, box, geometry, border);
-    }
-    /**
-     * The wrapped renderable's lines, laid out on a canvas `contentWidth` cells
-     * wide. Below width 3 a panel is all frame and the canvas holds no lines —
-     * but the render still happens, because a `bottomRightAccessory` thunk
-     * fires at every width and reads state this render populates.
-     */
-    _renderContent(options, contentWidth, style) {
-        // Two border rows and the vertical padding are the panel's own. Handed on
-        // as a region, the rest is the panel's to shape, which is what stretches
-        // its frame down a pane and keeps its bottom border inside one.
-        const [padTop, , padBottom] = this.padding;
-        const height = insetHeight(options.height, 2 + padTop + padBottom);
-        // No highlighter: what the panel holds is drawn plain, as Rich's `Panel`
-        // hands its body `highlight=False`.
-        const innerOptions = { ...options, highlight: false, maxWidth: contentWidth, height };
-        const lines = fitHeight(Segment.splitLines([...Segment.applyStyle(this.renderable.render(innerOptions), style)]), height);
-        return contentWidth === 0 ? [] : lines;
-    }
-    /**
-     * One row of the panel body, cut where Rich cuts it: frame column, left
-     * padding, the content line made exactly `contentWidth` wide, right padding,
-     * frame column — each its own segment, so each its own SGR run.
-     *
-     * [LAW:single-enforcer] `adjustLineLength` is the one place the content's
-     * width is decided: content that rendered wider than its canvas (a `Table`
-     * at its natural width, say) is cropped back to it, and a short line is
-     * filled out to it, so the right padding always starts at the same column.
-     */
-    *_renderRow(box, geometry, line, border, contentStyle) {
         const frame = box.getContentChars("row");
-        yield new Segment(frame.left.repeat(geometry.left), border);
-        yield new Segment(" ".repeat(geometry.padLeft), contentStyle);
-        yield* Segment.adjustLineLength(line, geometry.contentWidth, contentStyle);
-        yield new Segment(" ".repeat(geometry.padRight), contentStyle);
-        yield new Segment(frame.right.repeat(geometry.right), border);
-        yield Segment.line();
+        for (const line of bodyLines) {
+            yield new Segment(frame.left.repeat(geometry.left), border);
+            yield* line;
+            yield new Segment(frame.right.repeat(geometry.right), border);
+            yield Segment.line();
+        }
+        yield* this._renderBottomBorder(options, box, geometry, border, bodyLines);
     }
     /**
-     * A row of vertical padding: one blank run across the whole span, as Rich's
-     * `Padding` draws its blank lines, not a content row with nothing in it.
+     * 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`
+     * cells: `Padding` makes every row its block's width, cropping content that
+     * ignored its canvas. A span of no cells renders nothing, as Rich's
+     * `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` function is handed the rows it drew.
      */
-    *_renderPaddingRow(box, geometry, border, contentStyle) {
-        const frame = box.getContentChars("row");
-        yield new Segment(frame.left.repeat(geometry.left), border);
-        yield new Segment(" ".repeat(geometry.spanWidth), contentStyle);
-        yield new Segment(frame.right.repeat(geometry.right), border);
-        yield Segment.line();
+    _renderBody(options, spanWidth) {
+        // Two border rows are the panel's own, and the vertical padding is the
+        // body's. Handed on as a region, the rest is the panel's to shape, which
+        // is what stretches its frame down a pane and keeps its bottom border
+        // inside one. No highlighter: what the panel holds is drawn plain, as
+        // Rich's `Panel` hands its body `highlight=False`.
+        const bodyOptions = {
+            ...options,
+            highlight: false,
+            maxWidth: spanWidth,
+            height: insetHeight(options.height, 2),
+        };
+        const lines = Segment.splitLines(render(this._body, bodyOptions));
+        return fitHeight(lines, bodyOptions.height);
     }
     measure(rawOptions) {
         const options = withCellWidth(rawOptions);
@@ -220,18 +180,17 @@ export class Panel {
             return { minimum: width, maximum: width };
         }
         const content = this._contentRange(options);
-        const overhead = frameOverhead(layoutPanel(options.maxWidth, this.padding));
+        const overhead = frameWidth(layoutPanel(options.maxWidth)) + this._body.left + this._body.right;
         const maximum = Math.min(options.maxWidth, Math.max(content.maximum, this._labelWidth(options) + overhead));
         return { minimum: Math.min(content.minimum, maximum), maximum };
     }
-    /** The content plus its own frame, both read off the division it will render against. */
+    /** The body plus the frame around it, both read off the division it will render against. */
     _contentRange(options) {
-        const geometry = layoutPanel(options.maxWidth, this.padding);
-        const overhead = frameOverhead(geometry);
-        const measurement = Measurement.get({ ...options, maxWidth: geometry.contentWidth }, this.renderable);
+        const geometry = layoutPanel(options.maxWidth);
+        const measurement = Measurement.get({ ...options, maxWidth: geometry.spanWidth }, this._body);
         return {
-            minimum: measurement.minimum + overhead,
-            maximum: Math.min(options.maxWidth, measurement.maximum + overhead),
+            minimum: measurement.minimum + frameWidth(geometry),
+            maximum: measurement.maximum + frameWidth(geometry),
         };
     }
     /** The cells the title's label takes, its padding included; none without a title. */
@@ -265,11 +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*. Function form evaluates after
-        // content has been rendered (Panel.render collects content segments
-        // before yielding any borders), so the thunk sees fresh widget state.
-        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"
@@ -289,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 ---