@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/core/color.d.ts

@@ -259,6 +259,16 @@ export declare class ColorSpec {
      * on a ground (`flattenAlpha`).
      */
     static matchOn(value: ColorRgba, depth: ColorDepth, theme: TerminalTheme, foreground: boolean): ColorSpec;
+    /**
+     * Every colour `depth` writes by index, each with the colour a terminal
+     * known to show `theme` draws it in, lowest index first: the theme's
+     * sixteen, and at 256 colours the cube and grey ramp after them. Each is
+     * drawn alike as glyph and as ground, which the default colour is not, so
+     * it is not among them. Truecolor writes a colour itself and the default
+     * depth only the default, so neither writes any by index. The colours
+     * `matchOn` rounds to, but for the default, read off the same two tables.
+     */
+    static indexed(depth: ColorDepth, theme: TerminalTheme): readonly (readonly [ColorSpec, ColorRgba])[];
     /**
      * The spec a slot is written in once its colour moves from `was`, what its
      * written spec draws on `theme`, to the opaque `now`: `matchOn`'s — or

package/dist/core/color.js

@@ -614,9 +614,11 @@ export class ColorSpec {
             return ColorSpec.fromRgba(value);
         if (depth === ColorDepth.DEFAULT)
             return ColorSpec.default();
-        const slot = theme.ansiColors.match(value);
         // [LAW:dataflow-not-control-flow] Every candidate is scored; the depth
         // only decides whether the cube is among them. Ties go to the earlier.
+        // Each table's nearest stands in for all of it: the tables' `match` is
+        // memoised and ranks by this distance, so the winner is `indexed`'s.
+        const slot = theme.ansiColors.match(value);
         const candidates = [
             [ColorSpec.default(), foreground ? theme.foregroundColor : theme.backgroundColor],
             [new ColorSpec(`color(${slot})`, depth === ColorDepth.WINDOWS ? depth : ColorDepth.STANDARD, slot), theme.ansiColors.get(slot)],
@@ -624,6 +626,22 @@ export class ColorSpec {
         ];
         return candidates.reduce((best, next) => (rgbDistance(next[1], value) < rgbDistance(best[1], value) ? next : best))[0];
     }
+    /**
+     * Every colour `depth` writes by index, each with the colour a terminal
+     * known to show `theme` draws it in, lowest index first: the theme's
+     * sixteen, and at 256 colours the cube and grey ramp after them. Each is
+     * drawn alike as glyph and as ground, which the default colour is not, so
+     * it is not among them. Truecolor writes a colour itself and the default
+     * depth only the default, so neither writes any by index. The colours
+     * `matchOn` rounds to, but for the default, read off the same two tables.
+     */
+    static indexed(depth, theme) {
+        const byDepth = indexedMemo.get(theme) ?? new Map();
+        indexedMemo.set(theme, byDepth);
+        const listed = byDepth.get(depth) ?? listIndexed(depth, theme);
+        byDepth.set(depth, listed);
+        return listed;
+    }
     /**
      * The spec a slot is written in once its colour moves from `was`, what its
      * written spec draws on `theme`, to the opaque `now`: `matchOn`'s — or
@@ -670,6 +688,23 @@ function cubeCandidate(value) {
     const index = EIGHT_BIT_DOWNGRADE_TABLE.match(value);
     return [ColorSpec.fromAnsi(index), EIGHT_BIT_DOWNGRADE_TABLE.get(index)];
 }
+/** `ColorSpec.indexed`'s list, made once for each theme and depth. */
+const indexedMemo = new WeakMap();
+function listIndexed(depth, theme) {
+    const slots = () => Array.from({ length: 16 }, (_, slot) => [new ColorSpec(`color(${slot})`, depth === ColorDepth.WINDOWS ? depth : ColorDepth.STANDARD, slot), theme.ansiColors.get(slot)]);
+    switch (depth) {
+        case ColorDepth.TRUECOLOR:
+        case ColorDepth.DEFAULT:
+            return [];
+        case ColorDepth.STANDARD:
+        case ColorDepth.WINDOWS:
+            return slots();
+        case ColorDepth.EIGHT_BIT: {
+            const { firstIndex, size } = EIGHT_BIT_DOWNGRADE_TABLE;
+            return [...slots(), ...Array.from({ length: size }, (_, i) => [ColorSpec.fromAnsi(firstIndex + i), EIGHT_BIT_DOWNGRADE_TABLE.get(firstIndex + i)])];
+        }
+    }
+}
 function mix(from, to, t, theme) {
     return blendRgb(from.getTruecolor(theme), to.getTruecolor(theme), t);
 }

package/dist/core/console.js

@@ -18,7 +18,7 @@ import { ReprHighlighter, NullHighlighter } from "./highlighter.js";
 import { Rule } from "../renderables/rule.js";
 import { segmentsToString } from "./render.js";
 import { placeBlock } from "./place.js";
-import { isRenderable } from "./protocol.js";
+import { isRenderable, render } from "./protocol.js";
 // [LAW:dataflow-not-control-flow] With no live region claimed, stepping around
 // it is the text itself: every write takes the same path.
 const NO_LIVE_REGION = { around: (text) => text };
@@ -67,7 +67,7 @@ class TextRun {
         this.text = items.reduce((joined, item) => joined.append(item), new RichText("", { end: "" }));
     }
     *render(options) {
-        yield* this.text.render(options);
+        yield* render(this.text, options);
         yield this.end;
     }
     measure(options) {
@@ -433,7 +433,7 @@ export class Console {
             const renderable = block.kind === "text" ? new TextRun(block.items, terminator) : block.renderable;
             if (align)
                 return { lines: placeBlock(renderable, align, renderOpts), closed: true };
-            const drawn = [...renderable.render(renderOpts)];
+            const drawn = [...render(renderable, renderOpts)];
             // A text run's last segment is always its `end`, yielded even when
             // empty, and `splitLines` drops the empty line after a final break only
             // when nothing follows it — so the run is closed exactly when `end` is.
@@ -479,7 +479,7 @@ export class Console {
         time.stylize("log.time");
         const width = Math.min(time.cellLength, options.maxWidth - 1);
         const { rows, cropWidth } = this._draw(args, { ...options, maxWidth: options.maxWidth - width });
-        const [stampLine = []] = Segment.splitLines(time.render({ ...options, maxWidth: time.cellLength }));
+        const [stampLine = []] = Segment.splitLines(render(time, { ...options, maxWidth: time.cellLength }));
         const styled = (cell) => [...Segment.applyStyle(cell, this._style)];
         const stamp = styled(Segment.adjustLineLength(stampLine, width));
         const blank = styled([new Segment(" ".repeat(width))]);
@@ -499,7 +499,7 @@ export class Console {
     // into this constructor, which made a second map of one shape — identical
     // then, free to drift the moment `Rule` grew an option.
     rule(title, options) {
-        const segments = [...new Rule(title, options).render(this.options)];
+        const segments = [...render(new Rule(title, options), this.options)];
         this._writeSegments(segments);
     }
     // [LAW:one-source-of-truth] `JSONRenderable` is the one formatter for JSON and

package/dist/core/easing.d.ts

@@ -1,6 +1,7 @@
 /**
- * Easing and phase: the one vocabulary for "how far along" — every function
- * here returns progress in [0, 1].
+ * Easing and phase: the one vocabulary for "how far along" — a time in
+ * seconds becomes progress in [0, 1], and an ease reshapes that progress,
+ * usually but not always within [0, 1].
  *
  * Two kinds of curve, composed as `ease(phase(t))`:
  *
@@ -13,20 +14,31 @@
  *   built-ins are CSS's easing functions (CSS Easing Functions Level 1):
  *   `linear`, `cubic-bezier()` with its named curves, and `steps()` with its
  *   jump terms, plus `sine` for pulses — a half-cosine, so a `pingPong`
- *   through it brightens and dims with no corner at either end.
+ *   through it brightens and dims with no corner at either end — and the
+ *   physics-flavoured curves a cursor snapping, a counter settling or a
+ *   panel sliding in want: `spring`, a damped harmonic oscillator released
+ *   toward its rest, which is the one of them with parameters and so the one
+ *   that also says how long it takes; `bounce`, `back-in`, `back-out` and
+ *   `elastic`, Robert Penner's curves at the constants every animation
+ *   library since has shipped. An ease that leaves [0, 1] — a spring or a
+ *   back curve overshooting its rest — is still an ease: a `ColorRamp` holds
+ *   its end colours where it does, and an effect's `Curve` saturates at its
+ *   swing, so the overshoot is read by what can show it (a position, a
+ *   count) and clipped by what cannot.
  *
  * [LAW:no-ambient-temporal-coupling] Nothing here reads a clock. `t` is an
  * argument; whoever draws frames owns the clock and samples these at
  * whatever rate it likes, so the same `t` always gives the same progress.
  *
  * [LAW:one-type-per-behavior] An ease is a plain function value. CSS's named
- * curves are four instances of `cubicBezier`, not four implementations, and
- * `ColorRamp` and every effect take the same `Ease`.
+ * curves are four instances of `cubicBezier`, not four implementations, the
+ * spring in `EASES` is one `spring()`, and `ColorRamp` and every effect take
+ * the same `Ease`.
  *
  * Tier 0 of `src/core/`: imports nothing, so `themes/` and every later
  * `core/` module reach it downhill. [LAW:one-way-deps]
  */
-/** Progress in, progress out: a reshaping of [0, 1]. */
+/** Progress in [0, 1] in, progress out: a reshaping of [0, 1] that may leave it, as a spring overshooting its rest does. */
 export type Ease = (x: number) => number;
 /** Time in seconds (plus any per-cell offset) in, progress in [0, 1] out. */
 export type Phase = (t: number) => number;
@@ -51,11 +63,66 @@ export type StepPosition = "jump-start" | "jump-end" | "jump-none" | "jump-both"
  * the very end.
  */
 export declare function steps(n: number, position?: StepPosition): Ease;
+/**
+ * A spring's physics: the mass on it, the stiffness of its coil and the
+ * damping it moves against, in the units every animation library spells them
+ * in (React Spring, Framer Motion), whose defaults these are — a spring that
+ * overshoots once and settles in about a second and a quarter.
+ */
+export interface SpringOptions {
+    /** The restoring force per unit of displacement; stiffer swings faster and settles in about the same time, since the decay is the damping's over the mass's. Positive. Defaults to 100. */
+    readonly stiffness?: number;
+    /** The force against the motion per unit of velocity; more settles sooner and overshoots less. Positive. Defaults to 10. */
+    readonly damping?: number;
+    /** What the spring moves; heavier is slower and overshoots further. Positive. Defaults to 1. */
+    readonly mass?: number;
+}
+/**
+ * An ease over a duration: CSS's timing function and duration as one value,
+ * the whole of what a one-shot move needs to know about time — a tween's
+ * (`./tween.ts`), a `spring()`'s, and the part of an effect's `Curve` that
+ * is not its swing. `Phase.once(start, seconds)` through `ease` is the move
+ * on a timeline. [LAW:one-type-per-behavior] One shape, so a spring is handed
+ * to a tween as it is, and a curve written for an effect times a tween.
+ */
+export interface Timing {
+    /** How the move is shaped, as progress in to progress out. */
+    readonly ease: Ease;
+    /** How long the move takes, in seconds. */
+    readonly seconds: number;
+}
+/**
+ * How close to its rest a spring must come to count as settled: one part in a
+ * thousand of the way it moves, under a colour channel's step (1/255) and
+ * under any cell, so what rounds the spring's value to show it draws the rest
+ * from there on.
+ */
+export declare const SPRING_REST = 0.001;
+/**
+ * A damped harmonic oscillator, `m·x″ = −k·x − c·x′`, released at rest one
+ * unit from its equilibrium: the spring every animation library means. Its
+ * progress at `s` seconds is `1 − displacement(s)`, the closed-form solution
+ * of that equation in the regime its damping ratio `ζ = c / 2√(k·m)` puts it
+ * in — ringing past its rest for `ζ < 1`, creeping up to it for `ζ ≥ 1` — and
+ * its `seconds` is its settling time: the first moment after which the
+ * displacement stays within `SPRING_REST`, found once here by `crossing` on
+ * the bracket each regime knows its last crossing lies in, so a sample costs
+ * an exponential and a cosine whatever `x` is. [LAW:no-ambient-temporal-coupling]
+ *
+ * The ease is exactly 1 at `x = 1` (`settled`): settled means at rest. The
+ * `seconds` are the spring's to say, not the caller's: how long it rings is
+ * a fact about its physics, which is why this is the one ease that comes as
+ * a `Timing` — released at rest a unit from where it is going, at 1 when it
+ * has settled there.
+ */
+export declare function spring(options?: SpringOptions): Timing;
 /**
  * Every built-in ease by the name a template spells it with — CSS's keyword
  * names, plus `sine`, plus `step`: the spelling `ColorRamp` used before this
  * vocabulary existed, kept so every template written against it renders the
- * same. It is CSS's `step-end`, the same function value.
+ * same. It is CSS's `step-end`, the same function value. Then the
+ * physics-flavoured curves: `spring` is the default `spring()`, whose
+ * `seconds` are `DEFAULT_SPRING`'s; the rest are Penner's at his constants.
  */
 export declare const EASES: {
     readonly linear: Ease;
@@ -67,6 +134,11 @@ export declare const EASES: {
     readonly "step-end": Ease;
     readonly step: Ease;
     readonly sine: Ease;
+    readonly spring: Ease;
+    readonly bounce: Ease;
+    readonly "back-in": Ease;
+    readonly "back-out": Ease;
+    readonly elastic: Ease;
 };
 export type EaseName = keyof typeof EASES;
 /**
@@ -75,6 +147,65 @@ export type EaseName = keyof typeof EASES;
  * Unknown names throw naming every legal one. [LAW:no-silent-failure]
  */
 export declare function parseEase(name: string): Ease;
+/** Throws, naming `what`, unless `seconds` is a positive, finite number of seconds. */
+export declare function positiveSeconds(what: string, seconds: number): void;
+/**
+ * A beat: holds of given lengths in seconds, played in order and looped, the
+ * way the frames of an animation are each held and then replaced. `at(t)` is
+ * the index of the hold in progress at `t`, counted from the first hold at
+ * `t = 0`, and the sequence wraps every `period` seconds, before zero too,
+ * as `Phase.loop` wraps. With equal holds `at` is `steps(n)` read as an
+ * index; the holds here may differ, which `steps` cannot say, so a frame
+ * held for a second and the next for a quarter are one beat.
+ */
+export interface Beat {
+    readonly holds: readonly number[];
+    /** The sum of the holds: how long one pass takes, in seconds. */
+    readonly period: number;
+    /** Which hold is in progress at `t` seconds: an index into `holds`. */
+    at(t: number): number;
+    /**
+     * When the hold in progress at `t` began, in seconds on `t`'s own
+     * timeline: what a sample-and-hold on this beat reads at `t`. Every `t`
+     * inside one hold of one pass answers the same number, to the bit, so an
+     * effect handed it draws the same frame throughout. With `nextChange`,
+     * the two ends of the hold, as every `Animation` answers them.
+     */
+    lastChange(t: number): number;
+    /**
+     * When the hold in progress at `t` ends, in seconds on `t`'s own timeline:
+     * the start of the next hold, the first moment `at` places in it, so it is
+     * always after `t`. What is drawn on this beat at `t` is drawn until then.
+     * With `at`, this makes a beat an `Animation` of the hold in progress
+     * (`./animation.ts`).
+     */
+    nextChange(t: number): number;
+}
+/**
+ * The first float from `sum` up at which `reached` holds: a time built as a
+ * sum to land on a boundary — where a hold begins, where an animation's next
+ * part changes — that rounding put an ulp or two under it, walked up to the
+ * first moment on the far side. [LAW:single-enforcer] The one walk, so every
+ * boundary a time is carried onto is the moment the change shows, to the
+ * float. A walk longer than rounding can cost throws `finer()`'s message: the
+ * boundary is narrower than the floats around it are apart.
+ */
+export declare function walkUp(sum: number, reached: (x: number) => boolean, finer: () => string): number;
+/**
+ * The least float at which `reached` holds, `reached` being false up to some
+ * float and true from it on, found from `near`, a guess at it on either
+ * side. Where `walkUp` carries a sum onto a boundary on its own clock, and
+ * an ulp or two is all rounding can cost, this carries a moment across
+ * clocks (`./timeline.ts`): a host float is a step of `rate` on the
+ * animation's clock, so the host floats between the guess and the first one
+ * past the boundary are as many as the two clocks' resolutions are apart,
+ * which no cap bounds and is no error. The bracket is found by doubling the
+ * step out from `near`, and halved to two adjacent floats, so the answer is
+ * exact to the float and the cost is logarithmic in that distance.
+ */
+export declare function firstReaching(near: number, reached: (x: number) => boolean): number;
+/** `holds` as a `Beat`; a beat with no hold, or a hold that is not a positive number of seconds, throws. */
+export declare function beat(holds: readonly number[]): Beat;
 /** The three phase shapes. Each takes seconds and returns a `Phase`. */
 export declare const Phase: {
     /** 0 before `start`, rising to 1 over `duration` seconds, then held at 1. */