@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/renderables/embed.d.ts

@@ -82,6 +82,16 @@ export declare class InlineLabel {
      */
     text(options: RenderOptions, base?: TextStyle): RichText;
 }
+/**
+ * `text`, changed in place into a fragment of a line it shares, as Rich's
+ * `_title` reads one: its own end is not drawn, newlines become spaces so it
+ * stays on its line, and tabs are widened to their stops before anything
+ * measures it, so a cut to a border and the width a label asks for count
+ * the cells it will draw. [LAW:single-enforcer] The one reading of "set into
+ * a line", for a label read through the crossing above and for text a
+ * caller hands over already read (`Frames`).
+ */
+export declare function setIntoLine(text: RichText): RichText;
 /**
  * A label cut to `width` cells as Rich's `Text.truncate` cuts one: its plain
  * text set to the width less `marker` — a wide character the cut splits leaves

package/dist/renderables/embed.js

@@ -23,6 +23,7 @@
  */
 import { cellCount, cellLen, setCellSize } from "../core/cells.js";
 import { activeHighlighter, readStr } from "../core/markup.js";
+import { render } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";
 /**
@@ -71,7 +72,7 @@ export class EmbeddedText {
         return text;
     }
     render(options) {
-        return this.text(options).render(options);
+        return render(this.text(options), options);
     }
     /**
      * Measured unhighlighted, as Rich's `Measurement.get` reads a string with
@@ -114,15 +115,23 @@ export class InlineLabel {
      * caller's cut. A string reads with `base` as its style, as `EmbeddedText.text` reads one.
      */
     text(options, base) {
-        const text = this._content.text(options, base);
-        // A fragment of the line, so its own end is not drawn, as Rich's `_title` clears it.
-        text.end = "";
-        text.plain = text.plain.replaceAll("\n", " ");
-        // Tabs widened before anything measures it, so a cut to the border and
-        // the width a title asks for count the cells the label will draw.
-        return text.expandTabs();
+        return setIntoLine(this._content.text(options, base));
     }
 }
+/**
+ * `text`, changed in place into a fragment of a line it shares, as Rich's
+ * `_title` reads one: its own end is not drawn, newlines become spaces so it
+ * stays on its line, and tabs are widened to their stops before anything
+ * measures it, so a cut to a border and the width a label asks for count
+ * the cells it will draw. [LAW:single-enforcer] The one reading of "set into
+ * a line", for a label read through the crossing above and for text a
+ * caller hands over already read (`Frames`).
+ */
+export function setIntoLine(text) {
+    text.end = "";
+    text.plain = text.plain.replaceAll("\n", " ");
+    return text.expandTabs();
+}
 /**
  * A label cut to `width` cells as Rich's `Text.truncate` cuts one: its plain
  * text set to the width less `marker` — a wide character the cut splits leaves
@@ -155,7 +164,7 @@ export function present(content) {
  */
 export function drawLabel(text, options, base) {
     text.overflow = "ignore";
-    return [...Segment.applyStyle(text.render(options), base)];
+    return [...Segment.applyStyle(render(text, options), base)];
 }
 /**
  * Caller content as a label, or no label at all: content that is not

package/dist/renderables/flexStrip.d.ts

@@ -16,7 +16,7 @@
  * FlexStrip reuses it verbatim. There is no second concept of "join."
  */
 import { Segment } from "../core/segment.js";
-import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Composite, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 import { type Joiner, type StyledRenderable } from "../core/strip.js";
 export type FlexAlign = "left" | "center" | "right" | "justify";
 export interface FlexStripOptions<T extends StyledRenderable> {
@@ -27,12 +27,13 @@ export interface FlexStripOptions<T extends StyledRenderable> {
     /** Line alignment when packed items don't fill the available width (default "left"). */
     align?: FlexAlign;
 }
-export declare class FlexStrip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable {
+export declare class FlexStrip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable, Composite {
     readonly items: readonly T[];
     readonly joiner: Joiner<T> | undefined;
     readonly gap: number;
     readonly align: FlexAlign;
     constructor(items: readonly T[], options?: FlexStripOptions<T>);
+    contents(): Iterable<Renderable>;
     render(options: RenderOptions): Iterable<Segment>;
     measure(options: RenderOptions): {
         minimum: number;

package/dist/renderables/flexStrip.js

@@ -16,9 +16,10 @@
  * FlexStrip reuses it verbatim. There is no second concept of "join."
  */
 import { Segment } from "../core/segment.js";
+import { render } from "../core/protocol.js";
 import { drawItem, drawJoin } from "../core/strip.js";
 function renderToBlock(r, options) {
-    const segments = [...r.render(options)];
+    const segments = [...render(r, options)];
     let width = 0;
     for (const s of segments)
         width += s.cellLength;
@@ -55,6 +56,10 @@ export class FlexStrip {
         this.gap = options?.gap ?? 0;
         this.align = options?.align ?? "left";
     }
+    // The items; a join is drawn from what the joiner emits for it, not held.
+    contents() {
+        return this.items;
+    }
     *render(options) {
         const items = this.items;
         if (items.length === 0)

package/dist/renderables/frames.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Frames — content that changes on a beat: a sequence of frames, each held
+ * for its own seconds and looping, drawn as the one in progress at a time
+ * the host hands in.
+ *
+ * An effect moves a cell's colours and may never change a glyph
+ * (`./effect.ts`: "It changes how cells look, never which cells exist or who
+ * drew them"). A frame is the other kind of motion — what the element shows
+ * changes — so it is its own primitive and not a wider `Effect`, and the two
+ * compose by nesting: `new Effected(new Frames(…), …)` lights whichever frame
+ * is up.
+ *
+ * [LAW:no-ambient-temporal-coupling] `t` is an argument, as
+ * `Effected`'s is, never a clock read: whoever draws frames hands each one
+ * its time (`core/clock.ts`), so the same `t` draws the same bytes at one
+ * redraw a second or sixty. The host's rate is the host's. At sixty a frame
+ * shows for exactly its hold; at one a second a hold shorter than a second is
+ * skipped and a period of whole seconds freezes on one frame, and nothing
+ * here adapts to that — the beat is `core/easing.ts`'s, the one timing
+ * vocabulary, and a draw costs the same at `t = 0` and `t = 10⁶`.
+ *
+ * The sequence and the moment are two values, because only one of them
+ * changes from frame to frame. A `FrameSequence` is the frames prepared once
+ * — the beat, the one width, each frame set into a line and padded — and an
+ * `Animation` of the frame shown (`core/animation.ts`); a `Frames` is that
+ * sequence at a `t`, whose work is one frame's — finding which, and copying
+ * it: a host holds the sequence and asks it for a frame, as `Spinner` holds
+ * its two, so a draw costs the same over ninety frames as over one. The
+ * sequence is a value the host keeps, not a memo here: nothing is looked up
+ * by key.
+ *
+ * The frame drawn is drawn until the next begins, and its cells say so: they
+ * are stamped with the sequence's `nextChange` (`Style.nextChange`), which
+ * rides up through every container to whoever holds the composed frame
+ * (`Segment.nextChange`), so a host drawing at `t` knows when to draw again,
+ * and one drawing slower than the frames turn can see that it is skipping
+ * them. The stamp is put on by whoever draws the frame at a host time
+ * (`frameAt`) — a `Frames`, a `Spinner`, the template `frames` function —
+ * and the sequence's `at` hands over the frame alone, because the time a
+ * sequence is asked for may be one a `Timeline` mapped from the host's.
+ *
+ * Every frame is drawn at one width, the widest frame's, each padded on the
+ * right to it, so whatever sits beside the frames never moves as they turn;
+ * and the frame is a fragment of a line (`setIntoLine`), ending no line of
+ * its own, so it sits among other cells. Frames are `RichText`, each free to
+ * carry its own style, and read once, here: markup is a string's reading
+ * under the console that draws it, which a frame handed to a template
+ * binding has no console for, so the frame arrives read, as a `Group`'s
+ * children do.
+ */
+import type { Animation } from "../core/animation.js";
+import { type Beat } from "../core/easing.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import type { Segment } from "../core/segment.js";
+import type { RichText } from "../core/text.js";
+/** One frame: what it shows, and how long it is held, in seconds. */
+export interface Frame {
+    readonly text: RichText;
+    readonly seconds: number;
+}
+/** A sequence of frames prepared to be drawn: built once, asked for the frame at a time. */
+export declare class FrameSequence implements Animation<RichText> {
+    /** Which frame is in progress when: the holds are the frames' seconds, in order. */
+    readonly beat: Beat;
+    /** The width every frame draws at: the widest frame's, in cells. */
+    readonly width: number;
+    private readonly _shown;
+    constructor(frames: readonly Frame[]);
+    /**
+     * The frame in progress at `t`, at `width` cells, ending no line: a copy,
+     * the caller's to change, carrying no word on when it changes — that is
+     * `frameAt`'s, stamped by whoever draws it at a host time. `beat.at`
+     * refuses a `t` that is not finite.
+     */
+    at(t: number): RichText;
+    /** When the frame in progress at `t` gives way to the next: the beat's answer, its holds being the frames'. */
+    nextChange(t: number): number;
+    /** When the frame in progress at `t` began: the beat's answer. */
+    lastChange(t: number): number;
+}
+/**
+ * The frame `animation` shows at host time `t`, its every cell — padding
+ * included, so a blank frame among drawn ones still turns — stamped with when
+ * it gives way to the next, `animation.nextChange(t)`. [LAW:one-source-of-truth]
+ * The stamp is that one answer carried on the cells (`Segment.nextChange`),
+ * so a container holding the frame passes it up without asking the
+ * animation; and it is put on here, where the host's time is known, and not
+ * in the animation's `at`, whose own time a `Timeline` or an
+ * `Animation.sequence` may have mapped from the host's — a stamp made there
+ * would be a moment on a clock the host cannot read. A copy is stamped, the
+ * caller's to change: an animation may hand back the one `RichText` it
+ * holds, as `Animation.constant` does, and a stamp on that would outlive
+ * the draw it was true for.
+ */
+export declare function frameAt(animation: Animation<RichText>, t: number): RichText;
+export interface FramesOptions {
+    /** The moment to draw, in seconds. */
+    readonly t: number;
+}
+/** A sequence's frame in progress at one moment, as a renderable. */
+export declare class Frames implements Renderable, Measurable {
+    readonly sequence: FrameSequence;
+    readonly t: number;
+    private readonly _shown;
+    constructor(sequence: FrameSequence, options: FramesOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+    /**
+     * One width both ways: a frame is one picture, never wrapped apart at a
+     * space or narrowed as the frames turn. Fitting it to the room is
+     * `Measurement.get`'s, as for every measurable.
+     */
+    measure(): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/frames.js

@@ -0,0 +1,133 @@
+/**
+ * Frames — content that changes on a beat: a sequence of frames, each held
+ * for its own seconds and looping, drawn as the one in progress at a time
+ * the host hands in.
+ *
+ * An effect moves a cell's colours and may never change a glyph
+ * (`./effect.ts`: "It changes how cells look, never which cells exist or who
+ * drew them"). A frame is the other kind of motion — what the element shows
+ * changes — so it is its own primitive and not a wider `Effect`, and the two
+ * compose by nesting: `new Effected(new Frames(…), …)` lights whichever frame
+ * is up.
+ *
+ * [LAW:no-ambient-temporal-coupling] `t` is an argument, as
+ * `Effected`'s is, never a clock read: whoever draws frames hands each one
+ * its time (`core/clock.ts`), so the same `t` draws the same bytes at one
+ * redraw a second or sixty. The host's rate is the host's. At sixty a frame
+ * shows for exactly its hold; at one a second a hold shorter than a second is
+ * skipped and a period of whole seconds freezes on one frame, and nothing
+ * here adapts to that — the beat is `core/easing.ts`'s, the one timing
+ * vocabulary, and a draw costs the same at `t = 0` and `t = 10⁶`.
+ *
+ * The sequence and the moment are two values, because only one of them
+ * changes from frame to frame. A `FrameSequence` is the frames prepared once
+ * — the beat, the one width, each frame set into a line and padded — and an
+ * `Animation` of the frame shown (`core/animation.ts`); a `Frames` is that
+ * sequence at a `t`, whose work is one frame's — finding which, and copying
+ * it: a host holds the sequence and asks it for a frame, as `Spinner` holds
+ * its two, so a draw costs the same over ninety frames as over one. The
+ * sequence is a value the host keeps, not a memo here: nothing is looked up
+ * by key.
+ *
+ * The frame drawn is drawn until the next begins, and its cells say so: they
+ * are stamped with the sequence's `nextChange` (`Style.nextChange`), which
+ * rides up through every container to whoever holds the composed frame
+ * (`Segment.nextChange`), so a host drawing at `t` knows when to draw again,
+ * and one drawing slower than the frames turn can see that it is skipping
+ * them. The stamp is put on by whoever draws the frame at a host time
+ * (`frameAt`) — a `Frames`, a `Spinner`, the template `frames` function —
+ * and the sequence's `at` hands over the frame alone, because the time a
+ * sequence is asked for may be one a `Timeline` mapped from the host's.
+ *
+ * Every frame is drawn at one width, the widest frame's, each padded on the
+ * right to it, so whatever sits beside the frames never moves as they turn;
+ * and the frame is a fragment of a line (`setIntoLine`), ending no line of
+ * its own, so it sits among other cells. Frames are `RichText`, each free to
+ * carry its own style, and read once, here: markup is a string's reading
+ * under the console that draws it, which a frame handed to a template
+ * binding has no console for, so the frame arrives read, as a `Group`'s
+ * children do.
+ */
+import { beat } from "../core/easing.js";
+import { render } from "../core/protocol.js";
+import { Style } from "../core/style.js";
+import { setIntoLine } from "./embed.js";
+/** A sequence of frames prepared to be drawn: built once, asked for the frame at a time. */
+export class FrameSequence {
+    /** Which frame is in progress when: the holds are the frames' seconds, in order. */
+    beat;
+    /** The width every frame draws at: the widest frame's, in cells. */
+    width;
+    // Each frame as it draws: a line fragment padded to `width`, made once.
+    _shown;
+    constructor(frames) {
+        this.beat = beat(frames.map((frame) => frame.seconds));
+        const texts = frames.map((frame) => setIntoLine(frame.text.copy()));
+        const widths = texts.map((text) => text.cellLength);
+        this.width = Math.max(...widths);
+        this._shown = texts.map((text, i) => {
+            // One picture: a slot narrower than the frame crops it, never folds
+            // or wraps it onto a second line, which `Frames.measure` says it cannot take.
+            text.noWrap = true;
+            text.overflow = "crop";
+            return text.padRight(this.width - widths[i]);
+        });
+    }
+    /**
+     * The frame in progress at `t`, at `width` cells, ending no line: a copy,
+     * the caller's to change, carrying no word on when it changes — that is
+     * `frameAt`'s, stamped by whoever draws it at a host time. `beat.at`
+     * refuses a `t` that is not finite.
+     */
+    at(t) {
+        return this._shown[this.beat.at(t)].copy();
+    }
+    /** When the frame in progress at `t` gives way to the next: the beat's answer, its holds being the frames'. */
+    nextChange(t) {
+        return this.beat.nextChange(t);
+    }
+    /** When the frame in progress at `t` began: the beat's answer. */
+    lastChange(t) {
+        return this.beat.lastChange(t);
+    }
+}
+/**
+ * The frame `animation` shows at host time `t`, its every cell — padding
+ * included, so a blank frame among drawn ones still turns — stamped with when
+ * it gives way to the next, `animation.nextChange(t)`. [LAW:one-source-of-truth]
+ * The stamp is that one answer carried on the cells (`Segment.nextChange`),
+ * so a container holding the frame passes it up without asking the
+ * animation; and it is put on here, where the host's time is known, and not
+ * in the animation's `at`, whose own time a `Timeline` or an
+ * `Animation.sequence` may have mapped from the host's — a stamp made there
+ * would be a moment on a clock the host cannot read. A copy is stamped, the
+ * caller's to change: an animation may hand back the one `RichText` it
+ * holds, as `Animation.constant` does, and a stamp on that would outlive
+ * the draw it was true for.
+ */
+export function frameAt(animation, t) {
+    return animation.at(t).copy().stylize(new Style({ nextChange: animation.nextChange(t) }));
+}
+/** A sequence's frame in progress at one moment, as a renderable. */
+export class Frames {
+    sequence;
+    t;
+    // The frame `t` lands on, found once, here, so a bad time fails at construction.
+    _shown;
+    constructor(sequence, options) {
+        this.sequence = sequence;
+        this.t = options.t;
+        this._shown = frameAt(sequence, options.t);
+    }
+    render(options) {
+        return render(this._shown, options);
+    }
+    /**
+     * One width both ways: a frame is one picture, never wrapped apart at a
+     * space or narrowed as the frames turn. Fitting it to the room is
+     * `Measurement.get`'s, as for every measurable.
+     */
+    measure() {
+        return { minimum: this.sequence.width, maximum: this.sequence.width };
+    }
+}

package/dist/renderables/group.d.ts

@@ -4,11 +4,12 @@
  */
 import type { Segment } from "../core/segment.js";
 import { type Measurement } from "../core/measure.js";
-import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
-export declare class Group implements Renderable, Measurable {
+import type { Composite, Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+export declare class Group implements Renderable, Measurable, Composite {
     readonly renderables: Renderable[];
     constructor(...renderables: Renderable[]);
     render(options: RenderOptions): Iterable<Segment>;
     /** As wide as its widest member: the reference's `measure_renderables`. */
     measure(options: RenderOptions): Measurement;
+    contents(): Iterable<Renderable>;
 }

package/dist/renderables/group.js

@@ -3,7 +3,7 @@
  * No visual chrome — purely a container.
  */
 import { measureRenderables } from "../core/measure.js";
-import { stackedHeight } from "../core/protocol.js";
+import { render, stackedHeight } from "../core/protocol.js";
 export class Group {
     renderables;
     constructor(...renderables) {
@@ -12,11 +12,14 @@ export class Group {
     *render(options) {
         const memberOptions = { ...options, height: stackedHeight(options.height) };
         for (const renderable of this.renderables) {
-            yield* renderable.render(memberOptions);
+            yield* render(renderable, memberOptions);
         }
     }
     /** As wide as its widest member: the reference's `measure_renderables`. */
     measure(options) {
         return measureRenderables(options, this.renderables);
     }
+    contents() {
+        return this.renderables;
+    }
 }

package/dist/renderables/html-entities.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTML's named character references, each name without its `;`, to the
+ * characters it stands for — the table markdown-it-py, Rich's parser, decodes
+ * with. Generated by scripts/html-entities.py from Python's
+ * `html.entities.html5`; regenerate rather than edit.
+ */
+/** The characters `name`, a reference's name without its `&` and `;`, stands for, if it names any. */
+export declare function namedReference(name: string): string | undefined;