@promptctl/rich-js 0.24.0 → 0.24.1

package/dist/renderables/spinner.d.ts

@@ -31,20 +31,22 @@
  * agree at every `t`, a `Progress` on a hand-moved clock turns its spinners
  * on that clock, and a draw costs the same at `t = 0` and `t = 10⁶`.
  *
- * `speed` scales the holds, not the time: at speed 2 each frame is held half
- * the interval, and a negative speed is the frames in reverse order, each held
- * the interval over the speed's size. [LAW:one-source-of-truth] Rich scales
- * the time instead, `t × speed` into the beat. At a positive speed the frame
- * drawn is the same; but when the frame next changes (`Style.nextChange`) is
- * a time on the host's timeline, and a beat over scaled time answers on the
- * scaled one — so the sequence is scaled where it is built, and the
- * `FrameSequence` stamps host time with nothing to map back. Backwards, this is the plain
- * reversed sequence from `t = 0`, where Rich's `int()` truncation holds
- * frame 0 for a first interval and then counts down: a departure, made so a
- * negative speed is one more sequence on the beat and not a second rule
- * about time. A speed of zero would hold a frame forever, which is not a
- * beat, and is refused where it is given.
+ * `speed` is a `Timeline` (`core/timeline.ts`) playing from `t = 0` at
+ * that rate, as Rich scales the time, `t × speed` into the beat: the frames
+ * are held for the interval the data gives, and the spinner is asked for the
+ * frame at the time the timeline maps the host's to. [LAW:one-source-of-truth]
+ * When the frame next changes (`Style.nextChange`) is a time on the host's
+ * timeline, and the sequence answers on its own, so the timeline carries the
+ * answer back and the drawn cells are stamped with that (`frameAt`), where
+ * the host's time is known. Backwards, the frames count down from the last at `t = 0`,
+ * a negative time landing in the last frame of the pass before, where Rich's
+ * `int()` truncation holds frame 0 for a first interval and then counts
+ * down: a departure, made so a negative speed is the one timeline run
+ * backwards and not a second rule about time. A speed of zero would hold a
+ * frame forever, which a paused timeline is and a rate is not, and the
+ * timeline refuses it.
  */
+import type { Animation } from "../core/animation.js";
 import { Style } from "../core/style.js";
 import { RichText } from "../core/text.js";
 import type { Renderable, Measurable } from "../core/protocol.js";
@@ -53,7 +55,7 @@ export interface SpinnerOptions {
     speed?: number;
     style?: string | Style;
 }
-export declare class Spinner {
+export declare class Spinner implements Animation<Renderable & Measurable> {
     readonly name: string;
     readonly speed: number;
     readonly style: string | Style;
@@ -79,6 +81,16 @@ export declare class Spinner {
      * The frames this output can draw are chosen where the output is known.
      */
     at(t: number): Renderable & Measurable;
+    /**
+     * When the spinner drawn at `t` next turns, on the host's clock: the
+     * sooner of its two sequences' answers, since which one is drawn is the
+     * output's to choose and the line spinner that stands in on an ASCII-only
+     * output keeps its own interval. An early answer, on the output that draws
+     * the other one, which the contract allows; the drawn cells carry the exact one.
+     */
+    nextChange(t: number): number;
+    /** When the spinner drawn at `t` began to be drawn: the later of its two sequences' answers, by the same argument. */
+    lastChange(t: number): number;
     private _render;
     /**
      * The frame in progress and the label as one text, as Rich's

package/dist/renderables/spinner.js

@@ -31,33 +31,32 @@
  * agree at every `t`, a `Progress` on a hand-moved clock turns its spinners
  * on that clock, and a draw costs the same at `t = 0` and `t = 10⁶`.
  *
- * `speed` scales the holds, not the time: at speed 2 each frame is held half
- * the interval, and a negative speed is the frames in reverse order, each held
- * the interval over the speed's size. [LAW:one-source-of-truth] Rich scales
- * the time instead, `t × speed` into the beat. At a positive speed the frame
- * drawn is the same; but when the frame next changes (`Style.nextChange`) is
- * a time on the host's timeline, and a beat over scaled time answers on the
- * scaled one — so the sequence is scaled where it is built, and the
- * `FrameSequence` stamps host time with nothing to map back. Backwards, this is the plain
- * reversed sequence from `t = 0`, where Rich's `int()` truncation holds
- * frame 0 for a first interval and then counts down: a departure, made so a
- * negative speed is one more sequence on the beat and not a second rule
- * about time. A speed of zero would hold a frame forever, which is not a
- * beat, and is refused where it is given.
+ * `speed` is a `Timeline` (`core/timeline.ts`) playing from `t = 0` at
+ * that rate, as Rich scales the time, `t × speed` into the beat: the frames
+ * are held for the interval the data gives, and the spinner is asked for the
+ * frame at the time the timeline maps the host's to. [LAW:one-source-of-truth]
+ * When the frame next changes (`Style.nextChange`) is a time on the host's
+ * timeline, and the sequence answers on its own, so the timeline carries the
+ * answer back and the drawn cells are stamped with that (`frameAt`), where
+ * the host's time is known. Backwards, the frames count down from the last at `t = 0`,
+ * a negative time landing in the last frame of the pass before, where Rich's
+ * `int()` truncation holds frame 0 for a first interval and then counts
+ * down: a departure, made so a negative speed is the one timeline run
+ * backwards and not a second rule about time. A speed of zero would hold a
+ * frame forever, which a paused timeline is and a rate is not, and the
+ * timeline refuses it.
  */
 import { Segment } from "../core/segment.js";
 import { NULL_STYLE } from "../core/style.js";
 import { RichText } from "../core/text.js";
 import { SPINNERS, DEFAULT_SPINNER, LINE_SPINNER } from "../core/spinnerData.js";
-import { drawable } from "../core/protocol.js";
+import { Timeline } from "../core/timeline.js";
+import { drawable, render } from "../core/protocol.js";
 import { EmbeddedText } from "./embed.js";
-import { FrameSequence } from "./frames.js";
-const sequence = (data, style, speed) => {
-    const frames = data.frames.map((frame) => ({
-        text: new RichText("", { end: "" }).append(frame, style),
-        seconds: data.interval / 1000 / Math.abs(speed),
-    }));
-    return { frames: new FrameSequence(speed < 0 ? frames.reverse() : frames), glyphs: data.frames.join("") };
+import { FrameSequence, frameAt } from "./frames.js";
+const sequence = (data, style, timeline) => {
+    const frames = new FrameSequence(data.frames.map((frame) => ({ text: new RichText("", { end: "" }).append(frame, style), seconds: data.interval / 1000 })));
+    return { frames, played: Timeline.run(timeline, frames), glyphs: data.frames.join("") };
 };
 const sequenceGlyphs = ({ glyphs }) => glyphs;
 export class Spinner {
@@ -84,18 +83,16 @@ export class Spinner {
             throw new Error(`Unknown spinner: "${spinnerName}"`);
         }
         const speed = options?.speed ?? 1;
-        // [LAW:parse-dont-validate] A hold is a positive number of seconds, so the
-        // speed it is divided by is finite and not zero, settled here.
-        if (!Number.isFinite(speed) || speed === 0) {
-            throw new RangeError(`Spinner speed must be finite and not zero, got ${speed}`);
-        }
+        // [LAW:single-enforcer] A rate is finite and not zero, and the timeline
+        // refuses one that is not where it is built.
+        const timeline = Timeline.play(0, speed);
         this.name = spinnerName;
         this.text = text;
         this.speed = speed;
         this.style = options?.style ?? NULL_STYLE;
         this._data = data;
-        this._named = sequence(data, this.style, speed);
-        this._ascii = sequence(LINE_SPINNER, this.style, speed);
+        this._named = sequence(data, this.style, timeline);
+        this._ascii = sequence(LINE_SPINNER, this.style, timeline);
     }
     get frames() {
         return this._data.frames;
@@ -114,22 +111,36 @@ export class Spinner {
         if (!Number.isFinite(t)) {
             throw new RangeError(`Spinner.at needs a finite t, got ${t}`);
         }
-        const frames = (options) => drawable(options, this._named, this._ascii, sequenceGlyphs).frames;
+        const drawn = (options) => drawable(options, this._named, this._ascii, sequenceGlyphs);
         return {
-            render: (options) => this._render(frames(options), t, options),
+            render: (options) => this._render(drawn(options), t, options),
             // Measured at the frames' one width, the widest frame's, so a column
             // holding it never narrows as it turns, and never offered less than
             // that frame: a frame is one picture, which the reference's `Text`
             // measure would let wrap apart at its spaces.
             measure: (options) => {
-                const drawn = frames(options);
-                const { minimum, maximum } = this._line(drawn, t, options).measure(options);
-                return { minimum: Math.max(minimum, Math.min(drawn.width, maximum)), maximum };
+                const { frames, played } = drawn(options);
+                const { minimum, maximum } = this._line(played, t, options).measure(options);
+                return { minimum: Math.max(minimum, Math.min(frames.width, maximum)), maximum };
             },
         };
     }
-    *_render(frames, t, options) {
-        yield* this._line(frames, t, options).render(options);
+    /**
+     * When the spinner drawn at `t` next turns, on the host's clock: the
+     * sooner of its two sequences' answers, since which one is drawn is the
+     * output's to choose and the line spinner that stands in on an ASCII-only
+     * output keeps its own interval. An early answer, on the output that draws
+     * the other one, which the contract allows; the drawn cells carry the exact one.
+     */
+    nextChange(t) {
+        return Math.min(this._named.played.nextChange(t), this._ascii.played.nextChange(t));
+    }
+    /** When the spinner drawn at `t` began to be drawn: the later of its two sequences' answers, by the same argument. */
+    lastChange(t) {
+        return Math.max(this._named.played.lastChange(t), this._ascii.played.lastChange(t));
+    }
+    *_render({ played }, t, options) {
+        yield* render(this._line(played, t, options), options);
         yield Segment.line();
     }
     /**
@@ -139,8 +150,9 @@ export class Spinner {
      * styles nothing — is no label, not a trailing space, as an empty `Text` is
      * falsy there.
      */
-    _line(frames, t, options) {
-        const line = new RichText("", { end: "" }).append(frames.text(t));
+    _line(played, t, options) {
+        // The frame's cells say when it turns on the host's clock, the label's keep their own word.
+        const line = new RichText("", { end: "" }).append(frameAt(played, t));
         // Unhighlighted: Rich's label is a `Text` from the moment it is handed over, and a `Text` is never highlighted.
         const label = new EmbeddedText(this.text).text({ ...options, highlight: false });
         if (label.plain !== "")

package/dist/renderables/syntax.js

@@ -11,6 +11,7 @@ import { cellLen, expandTabs, parseTabSize } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";
 import { drawable, groundedStyle, getStyle, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+import { render } from "../core/protocol.js";
 /**
  * One regex per grammar, each token a named alternative. A single left-to-right
  * scan is what keeps a `//` inside a string from starting a comment, and a
@@ -140,7 +141,7 @@ export class Syntax {
             const lineNo = first + i;
             const style = this.highlightLines.has(lineNo) ? highlightStyle : numberStyle;
             // Terminated, so an empty line is one empty row rather than none.
-            const rows = Segment.splitLines([...textLines[i].render(lineOptions), Segment.line()]);
+            const rows = Segment.splitLines([...render(textLines[i], lineOptions), Segment.line()]);
             for (let row = 0; row < rows.length; row++) {
                 if (this.lineNumbers) {
                     // A wrapped line's continuation rows keep the gutter, unnumbered.

package/dist/renderables/table.d.ts

@@ -6,7 +6,7 @@ import { Style } from "../core/style.js";
 import { Box } from "../core/box.js";
 import { RichText } from "../core/text.js";
 import type { PaddingDimensions } from "./padding.js";
-import type { Renderable, Measurable, OverflowMethod, RenderOptions } from "../core/protocol.js";
+import type { Composite, Renderable, Measurable, OverflowMethod, RenderOptions } from "../core/protocol.js";
 export interface ColumnOptions {
     /** Anything a cell can hold, as Rich's `RenderableType` header is. */
     header?: string | RichText | Renderable;
@@ -98,7 +98,7 @@ export interface TableOptions {
     /** The `highlight` every column `addColumn` makes takes unless told otherwise (default: `false`). */
     highlight?: boolean;
 }
-export declare class Table implements Renderable, Measurable {
+export declare class Table implements Renderable, Measurable, Composite {
     private _columns;
     private _rows;
     readonly box: Box | null;
@@ -183,8 +183,11 @@ export declare class Table implements Renderable, Measurable {
      * mode gets its own path through the width division.
      *
      * Cells are measured against the width left once the frame is paid, as the
-     * reference's `_measure_column` measures them. Padding and the floor are laid
-     * over whichever sizing the column has: they are the same for all three.
+     * reference's `_measure_column` measures them. Padding is part of every
+     * width the demand names, because the reference measures a cell wrapped in
+     * its `Padding`, and each sizing adds it where the reference does — a
+     * rowless column's minimum is the one width it never reaches. The floor is
+     * laid over whichever sizing the column has.
      */
     private _columnDemands;
     private _columnSizing;
@@ -198,6 +201,8 @@ export declare class Table implements Renderable, Measurable {
      */
     private _columnPadding;
     private _rowPadding;
+    contents(): Iterable<Renderable>;
+    private _rowCells;
     /**
      * Every cell column `index` draws, in draw order.
      *
@@ -211,19 +216,22 @@ export declare class Table implements Renderable, Measurable {
      */
     private _columnCells;
     /**
-     * The widest any cell in a column draws, and the narrowest the column can be
-     * without cutting one — the reference's `_measure_column` — or `undefined`
-     * when the column has no cell to measure. Zero is a column whose cells draw
-     * nothing — a gutter asks for its padding and nothing else — and is not the
-     * same answer. [LAW:types-are-the-program]
+     * The widest any cell in a column draws, its padding included, and the
+     * narrowest the column can be without cutting one — the reference's
+     * `_measure_column` — or `undefined` when the column has no cell to measure.
+     * A column whose cells draw nothing measures its padding — a gutter asks for
+     * that and nothing else — which is not the same answer.
+     * [LAW:types-are-the-program]
      */
     private _cellRange;
     /**
-     * A natural width held to the column's own `minWidth`/`maxWidth`.
+     * A natural width held to the column's own `minWidth`/`maxWidth`, each
+     * widened by the column's `pad`, as the reference clamps a padded
+     * measurement to `min_width + padding_width`.
      *
      * A bound is a count of cells, read by the rule every width is read by: NaN
      * and a negative are zero cells, so a NaN floor bounds nothing and a NaN
-     * ceiling is a ceiling of zero, as `width: NaN` is. A bare `Math.max` returns
+     * ceiling holds the column to its padding alone, as `width: NaN` does. A bare `Math.max` returns
      * NaN instead, and the column vanishes. [LAW:one-source-of-truth]
      */
     private _bounded;