@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/core/style.d.ts

@@ -108,8 +108,7 @@ export declare class Style {
     /**
      * Returns the SGR parameter list this style emits (e.g. `"1;31;48;2;0;0;255"`),
      * or `""` when the style has no SGR contribution. Excludes OSC 8 link bytes —
-     * links are not SGR. The segment encoder (`segmentsToString`) uses this
-     * string as the group key for adjacent-same-style coalescing and wraps it in
+     * links are not SGR. The segment encoder (`segmentToString`) wraps it in
      * `\x1b[...m`; styled text reaches the wire only through that encoder.
      *
      * [LAW:one-source-of-truth] One computation of SGR codes.
@@ -127,7 +126,7 @@ export declare class Style {
     static chain(...styles: (Style | undefined)[]): Style;
     static normalize(definition: string): string;
     /**
-     * Parse a space-separated style definition. Cached.
+     * Parse a space-separated style definition. Memoized (`Memo`).
      *
      * A definition only: `"bold red"` parses, `"repr.number"` does not. Names
      * belong to a `Theme`, and `Theme.resolve` is where one is looked up.
@@ -142,6 +141,26 @@ export declare class StyleStack {
     push(style: Style): void;
     pop(): Style;
 }
+/**
+ * A `Style` added over a style name or definition a render has yet to
+ * resolve. Which it is cannot be told before then: a theme's names shadow
+ * definitions (`Theme.resolve`), so the addition waits for the render whose
+ * theme says what `under` stands for, and draws as `under` resolved with
+ * `over` added on top.
+ */
+export interface LayeredStyle {
+    readonly under: string;
+    readonly over: Style;
+}
+/** A style as a RichText stores it, base or span: resolved when it is drawn. */
+export type TextStyle = string | Style | LayeredStyle;
+/**
+ * `over` added to `base`, the outer style winning as `Style.add` has it. A
+ * `Style` base takes the addition now, and so does `""`, the definition that
+ * adds nothing; any other string keeps it as a `LayeredStyle` for the render
+ * that resolves the string.
+ */
+export declare function layerStyle(base: TextStyle, over: Style): TextStyle;
 export declare class Theme {
     private readonly styles;
     constructor(definitions?: Record<string, string>, options?: {
@@ -149,16 +168,17 @@ export declare class Theme {
     });
     get(name: string): Style | undefined;
     /**
-     * The style a `string | Style` stands for under this theme: a name this
-     * theme defines, otherwise a definition for `Style.parse`, which throws
-     * `StyleSyntaxError` when the string is neither.
+     * The style a `TextStyle` stands for under this theme: a name this theme
+     * defines, otherwise a definition for `Style.parse`, which throws
+     * `StyleSyntaxError` when the string is neither. A `LayeredStyle` is its
+     * `under` resolved here with its `over` added on top.
      *
      * [LAW:one-source-of-truth] The theme is the one map from names to styles.
      * The lookup stays outside `Style.parse`'s process-wide cache on purpose:
      * cached there, the first console to resolve `repr.number` would decide it
      * for every console after it, whatever theme each was given.
      */
-    resolve(style: string | Style): Style;
+    resolve(style: TextStyle): Style;
     has(name: string): boolean;
 }
 export declare const DEFAULT_STYLES: Record<string, Style>;

package/dist/core/style.js

@@ -3,6 +3,7 @@
  */
 import { COLOR_NAMES, ColorSpec, SURFACE_BLACK, } from "./color.js";
 import { shiftAnchor } from "./anchor.js";
+import { Memo } from "./memo.js";
 // [LAW:one-way-deps] `core/style` depends only on `core/color`. The substrate
 // a translucent colour is flattened over is `SURFACE_BLACK`, defined beside
 // `compositeOver`.
@@ -66,8 +67,8 @@ export class StyleSyntaxError extends Error {
         this.name = "StyleSyntaxError";
     }
 }
-// [LAW:one-source-of-truth] Parse cache is the single source for parsed Style instances
-const styleParseCache = new Map();
+// [LAW:one-source-of-truth] The single source for parsed Style instances.
+const styleParseMemo = new Memo();
 // --- Style ---
 export class Style {
     color;
@@ -95,7 +96,7 @@ export class Style {
     anchor;
     constructor(options = {}) {
         this.color = resolveColor(options.color);
-        this.bgcolor = resolveColor(options.bgcolor);
+        this.bgcolor = resolveBackground(options.bgcolor);
         this.bold = options.bold;
         this.dim = options.dim;
         this.italic = options.italic;
@@ -251,8 +252,7 @@ export class Style {
     /**
      * Returns the SGR parameter list this style emits (e.g. `"1;31;48;2;0;0;255"`),
      * or `""` when the style has no SGR contribution. Excludes OSC 8 link bytes —
-     * links are not SGR. The segment encoder (`segmentsToString`) uses this
-     * string as the group key for adjacent-same-style coalescing and wraps it in
+     * links are not SGR. The segment encoder (`segmentToString`) wraps it in
      * `\x1b[...m`; styled text reaches the wire only through that encoder.
      *
      * [LAW:one-source-of-truth] One computation of SGR codes.
@@ -329,7 +329,7 @@ export class Style {
         return definition.trim().replace(/\s+/g, " ");
     }
     /**
-     * Parse a space-separated style definition. Cached.
+     * Parse a space-separated style definition. Memoized (`Memo`).
      *
      * A definition only: `"bold red"` parses, `"repr.number"` does not. Names
      * belong to a `Theme`, and `Theme.resolve` is where one is looked up.
@@ -338,12 +338,7 @@ export class Style {
         const normalized = Style.normalize(definition);
         if (normalized === "" || normalized === "none")
             return NULL_STYLE;
-        const cached = styleParseCache.get(normalized);
-        if (cached)
-            return cached;
-        const result = parseStyleDefinition(normalized);
-        styleParseCache.set(normalized, result);
-        return result;
+        return styleParseMemo.get(normalized, parseStyleDefinition);
     }
 }
 export const NULL_STYLE = new Style();
@@ -368,6 +363,21 @@ export class StyleStack {
 }
 // --- Theme ---
 const STYLE_NAME_RE = /^[a-z][a-z0-9._-]*$/;
+/**
+ * `over` added to `base`, the outer style winning as `Style.add` has it. A
+ * `Style` base takes the addition now, and so does `""`, the definition that
+ * adds nothing; any other string keeps it as a `LayeredStyle` for the render
+ * that resolves the string.
+ */
+export function layerStyle(base, over) {
+    if (base instanceof Style)
+        return base.add(over);
+    if (base === "")
+        return over;
+    if (typeof base === "string")
+        return { under: base, over };
+    return { under: base.under, over: base.over.add(over) };
+}
 export class Theme {
     styles;
     constructor(definitions = {}, options) {
@@ -389,9 +399,10 @@ export class Theme {
         return this.styles.get(name);
     }
     /**
-     * The style a `string | Style` stands for under this theme: a name this
-     * theme defines, otherwise a definition for `Style.parse`, which throws
-     * `StyleSyntaxError` when the string is neither.
+     * The style a `TextStyle` stands for under this theme: a name this theme
+     * defines, otherwise a definition for `Style.parse`, which throws
+     * `StyleSyntaxError` when the string is neither. A `LayeredStyle` is its
+     * `under` resolved here with its `over` added on top.
      *
      * [LAW:one-source-of-truth] The theme is the one map from names to styles.
      * The lookup stays outside `Style.parse`'s process-wide cache on purpose:
@@ -401,6 +412,8 @@ export class Theme {
     resolve(style) {
         if (style instanceof Style)
             return style;
+        if (typeof style !== "string")
+            return this.resolve(style.under).add(style.over);
         return this.styles.get(style) ?? Style.parse(style);
     }
     has(name) {
@@ -545,6 +558,15 @@ function resolveColor(c) {
         return c;
     return ColorSpec.parse(c);
 }
+// A fully transparent background draws nothing over whatever lies beneath it,
+// so it is no background: a style added on top of another keeps that one's,
+// which is what Textual's `#00000000` means. A transparent foreground is not
+// the same, it draws its glyph in whatever lies beneath it — the background,
+// or `SURFACE_BLACK` when there is none — so it stays a colour.
+function resolveBackground(c) {
+    const spec = resolveColor(c);
+    return spec?.value?.alpha === 0 ? undefined : spec;
+}
 // --- DEFAULT_STYLES ---
 // [LAW:one-source-of-truth] Single canonical mapping of semantic names to styles
 export const DEFAULT_STYLES = {
@@ -585,22 +607,34 @@ export const DEFAULT_STYLES = {
     "table.cell": NULL_STYLE,
     "table.title": new Style({ italic: true }),
     "table.caption": new Style({ italic: true, dim: true }),
-    // Repr/highlighting
-    "repr.str": Style.parse("green"),
-    "repr.number": Style.parse("cyan"),
-    "repr.bool": Style.parse("italic bright_magenta"),
-    "repr.none": Style.parse("italic magenta"),
-    "repr.url": Style.parse("not italic underline bright_blue"),
-    "repr.uuid": Style.parse("bright_yellow"),
-    "repr.error": Style.parse("bold red"),
+    // Repr/highlighting — Rich 15.0.0's `rich.default_styles`, in its order
+    "repr.ellipsis": Style.parse("yellow"),
     "repr.indent": Style.parse("dim green"),
-    "repr.attrib_name": Style.parse("yellow"),
-    "repr.attrib_value": Style.parse("magenta"),
-    "repr.attrib_equal": Style.parse("bold"),
+    "repr.error": Style.parse("bold red"),
+    "repr.str": Style.parse("not bold not italic green"),
+    "repr.brace": Style.parse("bold"),
+    "repr.comma": Style.parse("bold"),
+    "repr.ipv4": Style.parse("bold bright_green"),
+    "repr.ipv6": Style.parse("bold bright_green"),
+    "repr.eui48": Style.parse("bold bright_green"),
+    "repr.eui64": Style.parse("bold bright_green"),
     "repr.tag_start": Style.parse("bold"),
-    "repr.tag_name": Style.parse("bright_magenta"),
+    "repr.tag_name": Style.parse("bold bright_magenta"),
     "repr.tag_contents": Style.parse("default"),
     "repr.tag_end": Style.parse("bold"),
+    "repr.attrib_name": Style.parse("not italic yellow"),
+    "repr.attrib_equal": Style.parse("bold"),
+    "repr.attrib_value": Style.parse("not italic magenta"),
+    "repr.number": Style.parse("bold not italic cyan"),
+    "repr.number_complex": Style.parse("bold not italic cyan"),
+    "repr.bool_true": Style.parse("italic bright_green"),
+    "repr.bool_false": Style.parse("italic bright_red"),
+    "repr.none": Style.parse("italic magenta"),
+    "repr.url": Style.parse("not bold not italic underline bright_blue"),
+    "repr.uuid": Style.parse("not bold bright_yellow"),
+    "repr.call": Style.parse("bold magenta"),
+    "repr.path": Style.parse("magenta"),
+    "repr.filename": Style.parse("bright_magenta"),
     // Log
     "log.time": Style.parse("cyan dim"),
     "log.message": NULL_STYLE,
@@ -618,12 +652,26 @@ export const DEFAULT_STYLES = {
     "json.null": Style.parse("italic magenta"),
     "json.number": Style.parse("bold not italic cyan"),
     "json.str": Style.parse("not bold not italic green"),
+    // Syntax
+    "syntax.keyword": Style.parse("bold magenta"),
+    "syntax.constant": Style.parse("italic bright_magenta"),
+    "syntax.string": Style.parse("green"),
+    "syntax.number": Style.parse("cyan"),
+    "syntax.comment": Style.parse("dim italic"),
+    "syntax.line_number": Style.parse("dim"),
+    // Ink and ground both from the fixed 256-colour greys: the terminal theme's
+    // own foreground is dark on a light theme and would vanish on grey27. At 16
+    // colours `Syntax` draws it without the pair (`groundedStyle`).
+    "syntax.line_number.highlight": Style.parse("bold grey93 on grey27"),
     // Markdown
     "markdown.h1": Style.parse("bold underline"),
     "markdown.h2": Style.parse("bold"),
     "markdown.h3": Style.parse("bold dim"),
     "markdown.h4": Style.parse("bold dim italic"),
-    "markdown.code": Style.parse("cyan on grey11"),
+    // A fixed cyan, not the theme's: `cyan` is dark enough on some themes to
+    // sink into grey11. Bold, as Rich's is: at 16 colours a renderable draws it
+    // without its pair (`groundedStyle`), and bold is what still marks code.
+    "markdown.code": Style.parse("bold dark_turquoise on grey11"),
     "markdown.hr": Style.parse("yellow"),
     "markdown.link": Style.parse("bright_blue"),
     "markdown.link_url": Style.parse("blue"),
@@ -652,9 +700,11 @@ export const DEFAULT_STYLES = {
     "status.spinner": Style.parse("green"),
     "status.message": NULL_STYLE,
     // Prompt
-    "prompt": Style.parse("bold"),
-    "prompt.choices": Style.parse("magenta"),
-    "prompt.default": Style.parse("cyan"),
+    "prompt": NULL_STYLE,
+    "prompt.choices": Style.parse("bold magenta"),
+    "prompt.default": Style.parse("bold cyan"),
+    "prompt.invalid": Style.parse("red"),
+    "prompt.invalid.choice": Style.parse("red"),
     // Inspect
     "inspect.attr": Style.parse("yellow italic"),
     "inspect.attr.dunder": Style.parse("yellow italic dim"),
@@ -677,9 +727,22 @@ export const DEFAULT_STYLES = {
     // Pretty
     "pretty": NULL_STYLE,
     // ISO8601
-    "iso8601.date": Style.parse("cyan"),
-    "iso8601.time": Style.parse("cyan"),
-    "iso8601.timezone": Style.parse("bright_blue"),
+    "iso8601.date": Style.parse("blue"),
+    "iso8601.time": Style.parse("magenta"),
+    "iso8601.timezone": Style.parse("yellow"),
+    // The parts ISO8601Highlighter lays inside a date or time. Rich's theme names
+    // none of them, so they draw nothing; they are here so a theme can set them
+    // and so none reaches `onStyleError` as an unknown name.
+    "iso8601.year": NULL_STYLE,
+    "iso8601.month": NULL_STYLE,
+    "iso8601.day": NULL_STYLE,
+    "iso8601.week": NULL_STYLE,
+    "iso8601.hour": NULL_STYLE,
+    "iso8601.minute": NULL_STYLE,
+    "iso8601.second": NULL_STYLE,
+    "iso8601.frac": NULL_STYLE,
+    "iso8601.ms": NULL_STYLE,
+    "iso8601.hyphen": NULL_STYLE,
 };
 /**
  * The theme a render resolves names against when nothing supplied one — what

package/dist/core/text.d.ts

@@ -2,14 +2,21 @@
  * RichText — styled text with spans. The primary text type for the library.
  */
 import { Segment } from "./segment.js";
-import { Style } from "./style.js";
+import { Style, type TextStyle } from "./style.js";
 import type { Renderable, Measurable, OverflowMethod, RenderOptions } from "./protocol.js";
 export declare function stripControlChars(text: string): string;
+/**
+ * The style a stored `TextStyle` stands for in this render.
+ *
+ * A parsed string can carry a link, so the result is sanitized on the way out
+ * as well.
+ */
+export declare function resolveStyle(options: RenderOptions, style: TextStyle): Style;
 export declare class Span {
     readonly start: number;
     readonly end: number;
-    readonly style: string | Style;
-    constructor(start: number, end: number, style: string | Style);
+    readonly style: TextStyle;
+    constructor(start: number, end: number, style: TextStyle);
     get hasLength(): boolean;
     toString(): string;
     split(offset: number): [Span, Span | undefined];
@@ -18,7 +25,7 @@ export declare class Span {
     extend(count: number): Span;
 }
 export interface RichTextOptions {
-    style?: string | Style;
+    style?: TextStyle;
     justify?: "left" | "center" | "right" | "full";
     overflow?: OverflowMethod;
     end?: string;
@@ -38,11 +45,19 @@ export declare class RichText implements Renderable, Measurable {
     get plain(): string;
     set plain(value: string);
     get length(): number;
+    /**
+     * The cells of the plain text with each tab widened to its stop counted from
+     * this text's own column 0, as `render` widens it — so it is the drawn width
+     * of a one-line text set at a stop. A deliberate departure from Rich, whose
+     * `Text.cell_len` counts a tab as no cells, so everything sized by it — a
+     * truncation, an alignment, a header's remaining width — decided on a width
+     * no render draws.
+     */
     get cellLength(): number;
     get hasContent(): boolean;
-    /** The base style every span layers over: a `Style`, or a name resolved at render. */
-    get style(): string | Style;
-    set style(value: string | Style);
+    /** The base style every span layers over, resolved at render unless it is a `Style`. */
+    get style(): TextStyle;
+    set style(value: TextStyle);
     get justify(): "left" | "center" | "right" | "full" | undefined;
     set justify(value: "left" | "center" | "right" | "full" | undefined);
     get overflow(): OverflowMethod | undefined;
@@ -79,7 +94,7 @@ export declare class RichText implements Renderable, Measurable {
      * drawn, and a style name draws as whatever the render's theme says.
      */
     edgeStyle(side: "left" | "right", options: RenderOptions): Style;
-    append(content: string | RichText, style?: string | Style): this;
+    append(content: string | RichText, style?: TextStyle): this;
     contains(needle: string | RichText): boolean;
     at(index: number): RichText;
     slice(start?: number, end?: number): RichText;
@@ -89,9 +104,9 @@ export declare class RichText implements Renderable, Measurable {
      * is admitted as given.
      */
     private _addSpan;
-    stylize(style: string | Style, start?: number, end?: number): this;
-    highlightRegex(pattern: RegExp, style?: string | Style): number;
-    highlightWords(words: string[], style: string | Style, options?: {
+    stylize(style: TextStyle, start?: number, end?: number): this;
+    highlightRegex(pattern: RegExp, style?: TextStyle): number;
+    highlightWords(words: string[], style: TextStyle, options?: {
         caseSensitive?: boolean;
     }): number;
     copy(): RichText;
@@ -100,6 +115,12 @@ export declare class RichText implements Renderable, Measurable {
     divide(offsets: number[]): RichText[];
     rstrip(): this;
     pad(count: number, char?: string): this;
+    /**
+     * Each tab widened to the next tab stop, in place, as Rich's
+     * `Text.expand_tabs` widens it: spans move with the characters they style, so
+     * the text measures what it will draw.
+     */
+    expandTabs(): this;
     padLeft(count: number, char?: string): this;
     padRight(count: number, char?: string): this;
     setLength(length: number): this;
@@ -124,6 +145,10 @@ export declare class RichText implements Renderable, Measurable {
      * styling; the marker (if any) is inserted as plain text with no span.
      * Use `stylize(...)` on the result to color the marker if needed.
      *
+     * Text that fits comes back untouched. Text that is cut has its tabs widened
+     * to their stops first, as `expandTabs` widens them, so the width cut to is
+     * the width drawn.
+     *
      * [LAW:dataflow-not-control-flow] mode/marker/width all flow as values;
      * the walk is the same shape regardless. No "if truncated then rebuild"
      * branch \u2014 the unchanged path just early-returns when content fits.
@@ -136,11 +161,11 @@ export declare class RichText implements Renderable, Measurable {
     private _cropLeftTo;
     align(justify: "left" | "center" | "right", width: number): this;
     removeSuffix(suffix: string): this;
-    appendTokens(tokens: Array<[string, (string | Style)?]>): this;
-    static assemble(parts: Array<string | [string, (string | Style)?] | RichText>, options?: {
-        style?: string | Style;
+    appendTokens(tokens: Array<[string, TextStyle?]>): this;
+    static assemble(parts: Array<string | [string, TextStyle?] | RichText>, options?: {
+        style?: TextStyle;
     }): RichText;
-    static styled(text: string, style: string | Style): RichText;
+    static styled(text: string, style: TextStyle): RichText;
     /**
      * Concatenate a sequence of `RichText` fragments into a single `RichText`,
      * flattening each fragment's wrapping `style` onto a span over that
@@ -165,7 +190,6 @@ export declare class RichText implements Renderable, Measurable {
         minimum: number;
         maximum: number;
     };
-    private _expandTabs;
     /**
      * The rendered text cut at every span edge, each piece carrying the base
      * style plus every span covering it.
@@ -218,6 +242,9 @@ export declare class RichText implements Renderable, Measurable {
      * `undefined` is not `"left"`: it is Rich's `"default"`, which places the
      * line without padding it at all. That distinction is what lets a soft-wrapped
      * `Console.print` leave its lines at their natural width.
+     *
+     * The padding is drawn in the text's base style, as the reference pads
+     * inside the `Text` it justifies: a title "on red" fills its row in red.
      */
     private _justifyLine;
     /**