@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/pretty.d.ts

@@ -24,6 +24,11 @@ export interface PrettyOptions {
     indent?: number;
     expandAll?: boolean;
     maxLength?: number;
+    /**
+     * How many characters of a string to show before cutting it, counting the
+     * rest after the closing quote. A character is a grapheme cluster, not a
+     * UTF-16 code unit: `"😀😀"` is two, though its `length` is four.
+     */
     maxString?: number;
     /**
      * How many levels of nesting to descend before eliding. Unbounded by default.
@@ -34,6 +39,11 @@ export interface PrettyOptions {
      * `Set {...}` — visible, so the reader knows the value continues.
      */
     maxDepth?: number;
+    /**
+     * Draw a `│` in the first cell of each level of indent. Off by default, as
+     * the reference's is, and never drawn on an ASCII-only console, where the
+     * reference draws none.
+     */
     indentGuides?: boolean;
     /**
      * Who colours the formatted text. Defaults to a `ReprHighlighter`.
@@ -43,9 +53,46 @@ export interface PrettyOptions {
      * `highlighter` have to reach the output the same way they reach a printed
      * string — a `Pretty` reaching for its own singleton would silently outrank
      * both. `NullHighlighter` is the "none" case.
+     *
+     * It reads each `Map` entry's `=>` as `= `: the arrow is this formatter's
+     * punctuation, not the data's, and its `>` would close a repr tag opened by
+     * any `<` before it.
      */
     highlighter?: Highlighter;
 }
+/**
+ * What a value is bounded by when whoever formats it has not seen it:
+ * `Console.print`'s data arguments, and a thrown value `Traceback` reports.
+ *
+ * Such a caller has to assume nothing about the value's size, in any of the
+ * three ways a value can be large. Unbounded, a buffer emits a line per byte, a
+ * deeply nested object descends until the stack gives out, and a single
+ * response body assigned to a field arrives in full — each of them a line that
+ * costs megabytes or hangs the terminal. All three bounds announce themselves
+ * in the output (`... +N`, `{...}`, `+N` after the closing quote), so this
+ * truncates visibly and never silently. [LAW:no-silent-failure]
+ *
+ * A caller constructing a `Pretty` has seen their data and gets no defaults;
+ * these belong to the paths that format what they were handed, not to the
+ * formatter.
+ */
+export declare const UNSEEN_DATA_BOUNDS: {
+    readonly maxLength: 100;
+    readonly maxDepth: 16;
+    readonly maxString: 1000;
+};
+/**
+ * Whether `Pretty` lays a value out as a container — brackets and positions —
+ * rather than spelling it as one piece of text. Emptiness and the depth cap do
+ * not enter into it; `[]` is still a container that happens to print on one
+ * line. This is Python Rich's `is_expandable`, and `Console.print` reads it to
+ * give a container lines of its own.
+ *
+ * A value whose reflection throws is not one, as in the reference's
+ * `_safe_isinstance`: `Pretty` then formats it as text, and the throw reaches
+ * the output as `threw`'s marker rather than taking the print down.
+ */
+export declare function isExpandable(value: unknown): boolean;
 export declare class Pretty implements Renderable, Measurable {
     readonly data: unknown;
     readonly indent: number;
@@ -55,6 +102,7 @@ export declare class Pretty implements Renderable, Measurable {
     readonly maxDepth: number;
     readonly indentGuides: boolean;
     readonly highlighter: Highlighter;
+    private readonly cutStrings;
     constructor(data: unknown, options?: PrettyOptions);
     render(options: RenderOptions): Iterable<Segment>;
     /** The value laid out for `options.maxWidth` and highlighted: the text this renders. */
@@ -72,6 +120,42 @@ export declare class Pretty implements Renderable, Measurable {
      * traversals.
      */
     private _scalar;
+    /**
+     * `value` quoted, and cut to `maxString` when it is longer.
+     *
+     * The dropped count is an annotation about the value, not part of it, so it
+     * goes after the closing quote — the way `maxLength`'s `... +N` sits beside
+     * the kept entries rather than inside the last one. Inside the quotes it
+     * reads as content, and copying it out yields a string the program never
+     * held.
+     *
+     * A cluster is at least one code unit, so a string no longer than the cap in
+     * code units is within it in clusters, and needs no segmenting.
+     */
+    private _string;
+    /**
+     * A key as an object literal would spell it: bare when it is a name or an
+     * index, which reads as itself, and quoted as a string otherwise. Rich reprs
+     * every key; printed raw, `"a b"` was indistinguishable from two words and a
+     * `\r` in one was dropped by `RichText`, so the key shown was not the key held.
+     * Quoting only what needs it keeps the JavaScript reading `{ a: 1 }`. A
+     * quoted key is a string and `maxString` cuts it; a bare one is a name.
+     */
+    private _key;
+    /**
+     * `value` cut to `max` grapheme clusters, with the rest counted after the
+     * closing quote.
+     *
+     * The unit is the cluster of the value, counted before `quoted` escapes it. A code unit cut can keep half a surrogate pair, which
+     * JSON.stringify prints as a `\ud83d` escape; a code point cut can keep half
+     * a flag or a ZWJ family. Either way the kept prefix shows something the
+     * value never held, and the dropped count is in a unit nobody can see.
+     *
+     * Counting clusters reads the whole string, and the traversals ask for the
+     * same scalar once per probe at every level above it, so the answer is
+     * memoised per value.
+     */
+    private _cutString;
     /**
      * A container, or the text standing in for one that is empty or past the
      * depth cap.
@@ -100,6 +184,24 @@ export declare class Pretty implements Renderable, Measurable {
     private _format;
     /** The arms for a non-null object, with `value` already on the open path. */
     private _formatObject;
+    /**
+     * Where a container starts: where it stands, or — when its opener will not
+     * fit after what precedes it on its line and will fit on a hanging line —
+     * that hanging line, with `lead` the break that reaches it.
+     *
+     * This is `_place`'s rule for one-piece text, with `open` as the first word:
+     * a bracket is a literal no cut can shorten, so moving is the only way it
+     * fits. A container moved there is on a line of that indent, its children
+     * and closer included, so it reads as its key's value rather than its key's
+     * sibling. It moves only to fit: past the edge, the hanging line has no more
+     * room than this one.
+     */
+    private _opening;
+    /**
+     * `at` on a line that starts at `inset`. The one place a hang is derived: a
+     * line's continuation rows and its children both sit one indent past it.
+     */
+    private _onLine;
     /**
      * One position, with every value in it laid out.
      *
@@ -113,7 +215,8 @@ export declare class Pretty implements Renderable, Measurable {
      * of the same fact. `_joinOneLine`'s probe sibling tracks the analogous
      * thing via `budget` shrinking instead, because a probe already discards
      * anything that overruns and so never needs to know where a multi-line
-     * insert's last line ends.
+     * insert's last line ends. Where that line *starts* is the one fact `out`
+     * cannot give back, so it comes from each piece's `Laid.inset` instead.
      *
      * Each hole's `reserve` is its own `tail` plus, only for the slot's last
      * hole, whatever `at.reserve` already asked this whole slot to leave room
@@ -122,6 +225,28 @@ export declare class Pretty implements Renderable, Measurable {
      * `out` grows past it.
      */
     private _expandSlot;
+    /**
+     * Text that is one piece — a scalar, a value that spells itself, a marker —
+     * set down at `at.column` on a line this formatter owns.
+     *
+     * A container that will not fit expands; one piece of text has no structure
+     * to expand into, so it wraps, and the wrap is laid out here rather than left
+     * to `RichText`. Left there, it broke at the console's edge and resumed at
+     * column 0 — under the enclosing key, or under nothing — which is the
+     * structure a reader of nested data relies on, broken. So every line after the
+     * first hangs at `at.hang`, a line of the value's own (`Error`'s message, a
+     * multi-line `toString`) as much as a wrapped one, and each is cut to the
+     * width left there. Every row of the last line also leaves `at.reserve`, as a
+     * container's compact try does, for the `,` or `" => "` that follows it.
+     *
+     * The first line is where the text already stands. When not even its first
+     * word fits there, it starts on a hanging line instead — the only case that
+     * moves it, and one taken only when that line starts further left and so has
+     * more room; otherwise the word is folded where it stands. A Map value after
+     * a long key is the case: `[1, 2, 3, 10] =>` ends the line and `"v"` hangs
+     * beneath it, where it used to wrap to column 0.
+     */
+    private _place;
     /** The one-line form of a value, or `null` when it will not fit `at.budget`. */
     private _oneLine;
     /**
@@ -140,5 +265,4 @@ export declare class Pretty implements Renderable, Measurable {
     private _joinOneLine;
     /** One position on one line, or `null` when any value in it will not fit. */
     private _slotOneLine;
-    private _addIndentGuides;
 }