@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/index.js

@@ -1,13 +1,13 @@
 // Core primitives
-export { cellLen, setCellSize, splitText, chopCells, cellFit, asCellCol, asCodePoint, } from "./core/cells.js";
-export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
+export { cellLen, setCellSize, splitText, chopCells, cellFit, graphemes, asCellCol, asCodePoint, } from "./core/cells.js";
+export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, parseHexColor, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
 // Perceptually-uniform color space (manipulation, transposition).
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
 // Themes — semantic palettes (distinct from ColorTable quantization LUTs)
 export { Palette } from "./themes/palette.js";
 // The one checkpoint turning an author-written colour string — a palette
 // variable name or a `#RRGGBB` literal — into a colour. [LAW:parse-dont-validate]
-export { resolveColorRef, parseHexColor, ColorRefError, HEX_COLOR_RE, } from "./themes/colorRef.js";
+export { resolveColorRef, ColorRefError } from "./themes/colorRef.js";
 export { buildPalette } from "./themes/buildPalette.js";
 export { DEFAULT_TERMINAL_THEME, MONOKAI, SVG_EXPORT_THEME, NORD, GRUVBOX, DRACULA, TOKYO_NIGHT, FLEXOKI, CYBERPUNK, CATPPUCCIN_MOCHA, CATPPUCCIN_LATTE, CATPPUCCIN_FRAPPE, CATPPUCCIN_MACCHIATO, SOLARIZED_DARK, SOLARIZED_LIGHT, ROSE_PINE, ROSE_PINE_MOON, ROSE_PINE_DAWN, ATOM_ONE_DARK, ATOM_ONE_LIGHT, TEXTUAL_DARK, TEXTUAL_LIGHT, TEXTUAL_ANSI, } from "./themes/terminalThemes.js";
 export { getThemePalette, listThemePalettes } from "./themes/registry.js";
@@ -24,9 +24,15 @@ export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "
 export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
 // A number → a color through ordered stops, interpolated in OKLCH — the one
 // color operation whose input is a measurement rather than a color, so a
-// gradient (or, with the `step` easing, a threshold cascade) stays inside the
+// gradient (or, with the `step` ease, a threshold cascade) stays inside the
 // theme system instead of being computed beside it.
-export { ColorRamp, RAMP_EASING_NAMES, parseRampEasing } from "./themes/ramp.js";
+export { ColorRamp } from "./themes/ramp.js";
+// Progress in [0, 1]: phases turn seconds into it, eases reshape it. One
+// vocabulary for ramps and time-based effects alike, CSS's names throughout.
+export { EASES, Phase, cubicBezier, parseEase, steps } from "./core/easing.js";
+// The time source and timer whoever draws frames is handed, and the one
+// parser of the rate it ticks at.
+export { frameRate, systemClock } from "./core/clock.js";
 export { Style, StyleSyntaxError, StyleStack, Theme, NULL_STYLE, DEFAULT_STYLES, } from "./core/style.js";
 export { Segment, ControlType, } from "./core/segment.js";
 export { Box } from "./core/box.js";
@@ -38,7 +44,7 @@ export { Measurement, measureRenderables } from "./core/measure.js";
 // Text
 export { Span, RichText } from "./core/text.js";
 // Strip + Joiner
-export { Strip, PowerlineJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER_GLYPHS, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
+export { Strip, CellJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER, CAPSULE_JOINER, PLAIN_JOINER, gradientJoiner, } from "./core/strip.js";
 // renderToString — stateless one-shot emission
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 // OSC 8 hyperlink wire grammar — for consumers that read rendered bytes back
@@ -63,9 +69,13 @@ export { SPINNERS, DEFAULT_SPINNER } from "./core/spinnerData.js";
 export { Console } from "./core/console.js";
 // Renderables
 export { Constrain } from "./renderables/constrain.js";
+export { Effected } from "./renderables/effect.js";
+export { EFFECT_CURVES, EFFECT_LIGHTS, SHIMMER_WIDTH, dissolveOut, fadeIn, onColors, pulse, shares, shimmer, sparkle, wheel, } from "./renderables/effects.js";
 export { Align } from "./renderables/align.js";
 export { Padding } from "./renderables/padding.js";
-export { Viewport, SCROLLBAR } from "./renderables/viewport.js";
+export { Viewport, ViewportPerKey, SCROLLBAR } from "./renderables/viewport.js";
+export { ListView } from "./renderables/list-view.js";
+export { moveSelection } from "./core/selection.js";
 export { Rule } from "./renderables/rule.js";
 export { Panel } from "./renderables/panel.js";
 export { Group } from "./renderables/group.js";

package/dist/node/prompt.d.ts

@@ -13,6 +13,19 @@
  *     // or with options:
  *     const choice = await Prompt.ask("Pick one", nodeAsk, { choices: ["a", "b"] });
  *
+ * The prompt is printed by the `Console` it was asked on — the app's, when it
+ * passed one as `console`, a new default one otherwise — and then a line is
+ * read, as Rich's `Console.input` prints its prompt and calls `input()`. So
+ * the prompt is coloured exactly as that console's own output would be and
+ * goes to its target: a console on stderr asks on stderr, beside the
+ * invalid-answer messages it prints. It goes as one logical line, never broken
+ * at the console's width: the terminal wraps it at whatever width it has.
+ *
+ * readline reads in non-terminal mode, the terminal's own cooked line
+ * discipline, as Python's `input()` does without its readline module: in
+ * terminal mode readline redraws the line itself, prompt included, and needs a
+ * whole `tty.WriteStream` to draw on, which a console's target need not be.
+ *
  * [LAW:single-enforcer] One readline interface per `nodeAsk` call —
  * created, asked, closed. No shared `rl` across prompts, no listener-leak
  * pitfalls when callers stack prompts in a loop.

package/dist/node/prompt.js

@@ -13,18 +13,39 @@
  *     // or with options:
  *     const choice = await Prompt.ask("Pick one", nodeAsk, { choices: ["a", "b"] });
  *
+ * The prompt is printed by the `Console` it was asked on — the app's, when it
+ * passed one as `console`, a new default one otherwise — and then a line is
+ * read, as Rich's `Console.input` prints its prompt and calls `input()`. So
+ * the prompt is coloured exactly as that console's own output would be and
+ * goes to its target: a console on stderr asks on stderr, beside the
+ * invalid-answer messages it prints. It goes as one logical line, never broken
+ * at the console's width: the terminal wraps it at whatever width it has.
+ *
+ * readline reads in non-terminal mode, the terminal's own cooked line
+ * discipline, as Python's `input()` does without its readline module: in
+ * terminal mode readline redraws the line itself, prompt included, and needs a
+ * whole `tty.WriteStream` to draw on, which a console's target need not be.
+ *
  * [LAW:single-enforcer] One readline interface per `nodeAsk` call —
  * created, asked, closed. No shared `rl` across prompts, no listener-leak
  * pitfalls when callers stack prompts in a loop.
  */
 import * as readline from "node:readline";
-export const nodeAsk = (prompt) => new Promise((resolve) => {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    rl.question(prompt, (answer) => {
-        rl.close();
-        resolve(answer);
+export const nodeAsk = (prompt, console) => {
+    console.print(prompt, { end: "", softWrap: true });
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            // [LAW:types-are-the-program] exception: readline types its output as a
+            // whole `NodeJS.WritableStream`, and a console's target is only a
+            // `ConsoleSink`. With `terminal: false` readline only ever calls its
+            // `write`, whatever its `isTTY` says.
+            output: console.file,
+            terminal: false,
+        });
+        rl.question("", (answer) => {
+            rl.close();
+            resolve(answer);
+        });
     });
-});
+};

package/dist/node/save.d.ts

@@ -8,10 +8,11 @@
  * refuse to resolve `fs` if a consumer ever pulls it in by accident.
  *
  * [LAW:single-enforcer] One funnel per format: `saveText` consumes
- * `Console.exportText()` and `saveHtml` consumes `Console.exportHtml()`.
- * The encoding and recording logic stays on Console; this file is purely
- * the IO sink.
+ * `Console.exportText()`, `saveHtml` consumes `Console.exportHtml()`, and
+ * `saveSvg` consumes `Console.exportSvg()`. The encoding and recording logic
+ * stays on Console; this file is purely the IO sink.
  */
 import type { Console } from "../core/console.js";
 export declare function saveText(out: Console, path: string, options?: Parameters<Console["exportText"]>[0]): void;
 export declare function saveHtml(out: Console, path: string, options?: Parameters<Console["exportHtml"]>[0]): void;
+export declare function saveSvg(out: Console, path: string, options?: Parameters<Console["exportSvg"]>[0]): void;

package/dist/node/save.js

@@ -8,9 +8,9 @@
  * refuse to resolve `fs` if a consumer ever pulls it in by accident.
  *
  * [LAW:single-enforcer] One funnel per format: `saveText` consumes
- * `Console.exportText()` and `saveHtml` consumes `Console.exportHtml()`.
- * The encoding and recording logic stays on Console; this file is purely
- * the IO sink.
+ * `Console.exportText()`, `saveHtml` consumes `Console.exportHtml()`, and
+ * `saveSvg` consumes `Console.exportSvg()`. The encoding and recording logic
+ * stays on Console; this file is purely the IO sink.
  */
 import { writeFileSync } from "node:fs";
 export function saveText(out, path, options) {
@@ -19,3 +19,6 @@ export function saveText(out, path, options) {
 export function saveHtml(out, path, options) {
     writeFileSync(path, out.exportHtml(options), "utf-8");
 }
+export function saveSvg(out, path, options) {
+    writeFileSync(path, out.exportSvg(options), "utf-8");
+}

package/dist/node/terminal-host.d.ts

@@ -29,6 +29,7 @@
  */
 import type { DataHandler, ExitHandler, ResizeHandler, TerminalHost, TerminalSize } from "../host/terminal-host.js";
 import type { Unsubscribe } from "../core/subscription.js";
+import type { Env } from "../core/env.js";
 /**
  * Subset of NodeJS stream API the node host actually depends on. Tests
  * construct a host over PassThrough / Writable mocks; production wires it
@@ -49,6 +50,12 @@ interface NodeWritable {
     readonly columns?: number;
     readonly rows?: number;
     readonly isTTY?: boolean;
+    /**
+     * Scroll whatever holds the terminal this stream writes to. Node's own
+     * stdout has none: its terminal is the outermost thing. A stand-in whose
+     * terminal sits in a page (the docs' example card) has one.
+     */
+    passWheel?(lines: number): void;
 }
 /**
  * Subset of node's `process` the host hears the program end through and
@@ -79,7 +86,7 @@ export interface NodeTerminalHostOptions {
      * pass a fixed map so what the host reports does not depend on the shell
      * that ran them.
      */
-    env?: NodeJS.ProcessEnv;
+    env?: Env;
     /**
      * What the host hears the program end through and suspends it with.
      * Defaults to `process`; tests pass an emitter that records `kill`.
@@ -90,7 +97,7 @@ export declare class NodeTerminalHost implements TerminalHost {
     private readonly stdin;
     private readonly stdout;
     private readonly process;
-    readonly env: NodeJS.ProcessEnv;
+    readonly env: Env;
     private readonly dataHandlers;
     private readonly resizeHandlers;
     private dataListener;
@@ -100,6 +107,7 @@ export declare class NodeTerminalHost implements TerminalHost {
     get isTTY(): boolean;
     get writesToTerminal(): boolean;
     write(data: Uint8Array | string): void;
+    passWheel(lines: number): void;
     size(): TerminalSize;
     setRawMode(raw: boolean): void;
     private applyRawMode;

package/dist/node/terminal-host.js

@@ -65,6 +65,13 @@ export class NodeTerminalHost {
     write(data) {
         this.stdout.write(data);
     }
+    // A terminal that reports the wheel to the program has taken it from its
+    // own scrollback, and nothing here can hand it back: on node's stdout this
+    // does nothing. A stdout whose terminal sits in something that scrolls
+    // carries the way out itself.
+    passWheel(lines) {
+        this.stdout.passWheel?.(lines);
+    }
     size() {
         return {
             cols: this.stdout.columns ?? DEFAULT_COLS,

package/dist/node/traceback.d.ts

@@ -15,7 +15,8 @@
  * payload is trusted to be an `Error`: `@types/node` annotates
  * `uncaughtException` with `Error`, but `throw "boom"` delivers the raw
  * string, so the annotation is a claim about the common case rather than a
- * guarantee. `report` takes `unknown`.
+ * guarantee. `report` takes `unknown` and hands it to `Traceback` as it came,
+ * which reads a caught value of any shape.
  *
  * [LAW:no-ambient-temporal-coupling] The one channel is also what puts the
  * report after the terminal is handed back. A program holding the alternate

package/dist/node/traceback.js

@@ -15,7 +15,8 @@
  * payload is trusted to be an `Error`: `@types/node` annotates
  * `uncaughtException` with `Error`, but `throw "boom"` delivers the raw
  * string, so the annotation is a claim about the common case rather than a
- * guarantee. `report` takes `unknown`.
+ * guarantee. `report` takes `unknown` and hands it to `Traceback` as it came,
+ * which reads a caught value of any shape.
  *
  * [LAW:no-ambient-temporal-coupling] The one channel is also what puts the
  * report after the terminal is handed back. A program holding the alternate
@@ -26,45 +27,8 @@
  * the terminal. Node's crash sequence owns the order, not the order in which
  * `installTraceback` and a host happened to add their listeners.
  */
-import { inspect, types } from "node:util";
 import { Console } from "../core/console.js";
 import { Traceback } from "../renderables/traceback.js";
-/** A payload's own stack, when it carries one, or `""` when it does not. */
-function stackOf(reason) {
-    if (typeof reason !== "object" || reason === null)
-        return "";
-    if (!("stack" in reason))
-        return "";
-    return typeof reason.stack === "string" ? reason.stack : "";
-}
-/**
- * [LAW:parse-dont-validate] The checkpoint between a crash payload, which node
- * allows to be any value at all, and `Traceback`, which renders an `Error`.
- * The return type is the proof: nothing downstream re-asks whether the payload
- * was throwable, and no raw value can reach the renderable to have `.name` and
- * `.message` read off it as `undefined`.
- *
- * The gate is `isNativeError`, not `instanceof Error`. An error thrown inside a
- * `node:vm` context is a real error with real frames, but its prototype comes
- * from that realm, so `instanceof` answers false and the frames would be
- * discarded by the one component that exists to show them. `isNativeError`
- * reads V8's internal error slot and is realm-independent.
- *
- * Whatever survives that gate is not an error, so it has no call site of its
- * own; `stackOf` salvages a stack from a duck-typed thrower and otherwise
- * leaves it empty rather than reporting the frames of this function, which
- * point into rich-js and describe nothing about the fault. `inspect` renders
- * every payload shape, including circular objects, where `String(reason)`
- * would collapse them to `[object Object]`.
- */
-function toError(reason) {
-    if (types.isNativeError(reason))
-        return reason;
-    const error = new Error(inspect(reason));
-    error.name = "NonError";
-    error.stack = stackOf(reason);
-    return error;
-}
 /**
  * The handler currently registered, or a no-op standing in for "none yet".
  *
@@ -116,7 +80,7 @@ export function installTraceback(options) {
         // sink would report `isTTY === false` and silently strip colour.
         const out = new Console({ stderr: true });
         out.beginCapture();
-        out.print(new Traceback(toError(reason), options));
+        out.print(new Traceback(reason, options));
         // [LAW:no-silent-failure] Exit only once the bytes have drained. When
         // stderr is a pipe (CI logs, `2>&1 | tee`), writes are asynchronous and
         // an immediate `process.exit(1)` truncates the traceback at the pipe

package/dist/renderables/align.js

@@ -3,7 +3,7 @@
  */
 import { Segment } from "../core/segment.js";
 import { Measurement } from "../core/measure.js";
-import { isMeasurable, withBoundedWidth } from "../core/protocol.js";
+import { withBoundedWidth } from "../core/protocol.js";
 import { placeBlock } from "../core/place.js";
 export class Align {
     renderable;
@@ -21,13 +21,6 @@ export class Align {
         }
     }
     measure(options) {
-        if (isMeasurable(this.renderable)) {
-            const measurement = Measurement.get(options, this.renderable);
-            return {
-                minimum: Math.max(1, measurement.minimum),
-                maximum: measurement.maximum,
-            };
-        }
-        return { minimum: 1, maximum: options.maxWidth };
+        return Measurement.get(options, this.renderable);
     }
 }

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;
-    };
 }