@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/core/style.d.ts

@@ -11,6 +11,13 @@ import { type Anchor } from "./anchor.js";
  */
 export declare const ATTRIBUTE_NAMES: readonly ["bold", "dim", "italic", "underline", "blink", "blink2", "reverse", "conceal", "strike", "underline2", "frame", "encircle", "overline"];
 export type AttributeName = (typeof ATTRIBUTE_NAMES)[number];
+/**
+ * Each text attribute as a style sets it: on, off, or unset — and an unset
+ * one lets a style laid beneath (`Style.add`) show through.
+ */
+export type Attributes = {
+    readonly [A in AttributeName]: boolean | undefined;
+};
 export declare const ATTRIBUTE_SGR: Record<AttributeName, number>;
 /**
  * Canonical short-attribute aliases (`b` → `bold`, `i` → `italic`, …).
@@ -18,7 +25,7 @@ export declare const ATTRIBUTE_SGR: Record<AttributeName, number>;
  * bindings — adding an alias here makes it available everywhere.
  * [LAW:one-source-of-truth]
  */
-export declare const ATTRIBUTE_SHORT_ALIASES: Record<string, AttributeName>;
+export declare const ATTRIBUTE_SHORT_ALIASES: Readonly<Record<string, AttributeName>>;
 export interface StyleOptions {
     color?: string | ColorSpec;
     bgcolor?: string | ColorSpec;
@@ -38,7 +45,18 @@ export interface StyleOptions {
     link?: string;
     meta?: Record<string, unknown>;
     anchor?: Anchor;
-    nextChange?: number;
+    /**
+     * The hold the style's cells are in, both ends or neither: a cell saying
+     * only when it next changes would claim, by default, that it always was,
+     * and a timeline run backwards past its change would never wake for it.
+     * [LAW:types-are-the-program] Absent, the cells never change.
+     */
+    hold?: Hold;
+}
+/** A hold: since when a sample has been what it is, and until when it stays so, on one clock. */
+export interface Hold {
+    readonly lastChange: number;
+    readonly nextChange: number;
 }
 export declare class StyleSyntaxError extends Error {
     constructor(message: string, options?: ErrorOptions);
@@ -60,7 +78,7 @@ export declare class Style {
     readonly encircle: boolean | undefined;
     readonly overline: boolean | undefined;
     readonly link: string | undefined;
-    readonly meta: Record<string, unknown> | undefined;
+    readonly meta: Readonly<Record<string, unknown>> | undefined;
     /**
      * Where this style's cells sat in the output of whatever drew them; see
      * `./anchor.ts`. It draws nothing, and it makes two styles that draw alike
@@ -68,17 +86,19 @@ export declare class Style {
      */
     readonly anchor: Anchor | undefined;
     /**
-     * When what this style's cells show next changes, in seconds on the
-     * timeline of whoever drew the frame — `t` itself for a cell drawn by
-     * something that moves every frame, and `Infinity`, the default, for one
+     * The hold this style's cells are in, on the timeline of whoever drew the
+     * frame: since when what they show has been what it is (`lastChange`), and
+     * when it next changes (`nextChange`) — both `t` for a cell drawn by
+     * something that moves every frame, and `-Infinity`/`Infinity` for one
      * that never changes. It draws nothing. Whatever draws for a handed time
-     * stamps its cells with it (`Frames`, `Effected`), the stamp rides up
-     * through every container as the anchor does (`./anchor.ts`), and
-     * whoever holds the composed frame reads the soonest off it
-     * (`Segment.nextChange`), so a host knows when to draw again without
-     * asking each container. Two styles laid together change at the sooner.
+     * stamps its cells with it (`placedRender`, `Effected`), the stamp rides up
+     * through every container as the anchor does (`./anchor.ts`), and whoever
+     * holds the composed frame reads it off (`Segment.nextChange`, and
+     * `Segment.lastChange` for a host running its timeline backwards), so a
+     * host knows when to draw again without asking each container. Two styles
+     * laid together are in the intersection of their holds.
      */
-    readonly nextChange: number;
+    readonly hold: Hold;
     constructor(options?: StyleOptions);
     get isNull(): boolean;
     get transparentBackground(): boolean;
@@ -97,6 +117,19 @@ export declare class Style {
      * The same look, drawn from the place `anchor` names, or from nowhere.
      */
     withAnchor(anchor: Anchor | undefined): Style;
+    /** The style's text attributes, each as it sets it. */
+    get attributes(): Attributes;
+    /**
+     * The same style with each attribute `attributes` names set as it says —
+     * on, off, or unset — and every other field as it was.
+     */
+    withAttributes(attributes: Partial<Attributes>): Style;
+    /**
+     * This style with its motion taken out, what reduced motion draws: `blink`
+     * and `blink2`, the motion a terminal makes on its own, unset, and every
+     * other field as it was. A style that does not blink is its own.
+     */
+    reduced(): Style;
     /**
      * This style on the cell `cells` to the right: its anchor shifted along its
      * row, or the style itself when it has no anchor.
@@ -130,7 +163,7 @@ export declare class Style {
     /**
      * The look as a canonical string that round-trips through `Style.parse()`:
      * colours, attributes and the link, which is all a style string can spell.
-     * What a style carries beyond its look — `meta`, `anchor`, `nextChange` —
+     * What a style carries beyond its look — `meta`, `anchor`, `hold` —
      * has no spelling and is not here, so two styles that differ only there
      * read alike; `equals` tells them apart.
      */
@@ -198,7 +231,7 @@ export declare class Theme {
     resolve(style: TextStyle): Style;
     has(name: string): boolean;
 }
-export declare const DEFAULT_STYLES: Record<string, Style>;
+export declare const DEFAULT_STYLES: Readonly<Record<string, Style>>;
 /**
  * The theme a render resolves names against when nothing supplied one — what
  * a renderable sees outside a `Console`, as in `renderToString`.

package/dist/core/style.js

@@ -4,6 +4,7 @@
 import { COLOR_NAMES, ColorSpec, SURFACE_BLACK, } from "./color.js";
 import { shiftAnchor } from "./anchor.js";
 import { Memo } from "./memo.js";
+import { pattern } from "./pattern.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`.
@@ -61,6 +62,8 @@ export const ATTRIBUTE_SHORT_ALIASES = {
     o: "overline",
     uu: "underline2",
 };
+/** The hold of a cell that never changes: always was, and always will be. */
+const NEVER_CHANGES = { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY };
 export class StyleSyntaxError extends Error {
     constructor(message, options) {
         super(message, options);
@@ -95,25 +98,31 @@ export class Style {
      */
     anchor;
     /**
-     * When what this style's cells show next changes, in seconds on the
-     * timeline of whoever drew the frame — `t` itself for a cell drawn by
-     * something that moves every frame, and `Infinity`, the default, for one
+     * The hold this style's cells are in, on the timeline of whoever drew the
+     * frame: since when what they show has been what it is (`lastChange`), and
+     * when it next changes (`nextChange`) — both `t` for a cell drawn by
+     * something that moves every frame, and `-Infinity`/`Infinity` for one
      * that never changes. It draws nothing. Whatever draws for a handed time
-     * stamps its cells with it (`Frames`, `Effected`), the stamp rides up
-     * through every container as the anchor does (`./anchor.ts`), and
-     * whoever holds the composed frame reads the soonest off it
-     * (`Segment.nextChange`), so a host knows when to draw again without
-     * asking each container. Two styles laid together change at the sooner.
+     * stamps its cells with it (`placedRender`, `Effected`), the stamp rides up
+     * through every container as the anchor does (`./anchor.ts`), and whoever
+     * holds the composed frame reads it off (`Segment.nextChange`, and
+     * `Segment.lastChange` for a host running its timeline backwards), so a
+     * host knows when to draw again without asking each container. Two styles
+     * laid together are in the intersection of their holds.
      */
-    nextChange;
+    hold;
     constructor(options = {}) {
-        const nextChange = options.nextChange ?? Number.POSITIVE_INFINITY;
+        const hold = options.hold ?? NEVER_CHANGES;
+        const { lastChange, nextChange } = hold;
         // [LAW:parse-dont-validate] A time or never, settled where the style is
-        // made: NaN and -Infinity fail here, so no reader of a frame meets one.
+        // made: NaN and the far infinity fail here, so no reader of a frame meets one.
         if (!(nextChange > Number.NEGATIVE_INFINITY)) {
             throw new RangeError(`Style nextChange must be a time in seconds or Infinity, got ${nextChange}`);
         }
-        this.nextChange = nextChange;
+        if (!(lastChange < Number.POSITIVE_INFINITY)) {
+            throw new RangeError(`Style lastChange must be a time in seconds or -Infinity, got ${lastChange}`);
+        }
+        this.hold = hold;
         this.color = resolveColor(options.color);
         this.bgcolor = resolveBackground(options.bgcolor);
         this.bold = options.bold;
@@ -129,7 +138,8 @@ export class Style {
         this.frame = options.frame;
         this.encircle = options.encircle;
         this.overline = options.overline;
-        this.link = options.link;
+        // As the reference's `self._link`, read only for truth: an empty URL is no link.
+        this.link = options.link || undefined;
         this.meta = options.meta;
         this.anchor = options.anchor;
     }
@@ -152,7 +162,8 @@ export class Style {
             this.link === undefined &&
             this.meta === undefined &&
             this.anchor === undefined &&
-            this.nextChange === Number.POSITIVE_INFINITY);
+            this.hold.nextChange === Number.POSITIVE_INFINITY &&
+            this.hold.lastChange === Number.NEGATIVE_INFINITY);
     }
     get transparentBackground() {
         return this.bgcolor === undefined || this.bgcolor.isDefault;
@@ -188,6 +199,28 @@ export class Style {
     withAnchor(anchor) {
         return this.with({ anchor });
     }
+    /** The style's text attributes, each as it sets it. */
+    get attributes() {
+        // [LAW:one-source-of-truth] Keyed by `ATTRIBUTE_NAMES`, whose every name is a key here: the cast is that list's own claim.
+        return Object.fromEntries(ATTRIBUTE_NAMES.map((name) => [name, this[name]]));
+    }
+    /**
+     * The same style with each attribute `attributes` names set as it says —
+     * on, off, or unset — and every other field as it was.
+     */
+    withAttributes(attributes) {
+        // Only the attribute names are read: a wider object — a `Style`, say —
+        // satisfies the type and must not carry its colours or anchor in with it.
+        return this.with(Object.fromEntries(ATTRIBUTE_NAMES.filter((name) => name in attributes).map((name) => [name, attributes[name]])));
+    }
+    /**
+     * This style with its motion taken out, what reduced motion draws: `blink`
+     * and `blink2`, the motion a terminal makes on its own, unset, and every
+     * other field as it was. A style that does not blink is its own.
+     */
+    reduced() {
+        return this.blink || this.blink2 ? this.withAttributes({ blink: undefined, blink2: undefined }) : this;
+    }
     /**
      * This style on the cell `cells` to the right: its anchor shifted along its
      * row, or the style itself when it has no anchor.
@@ -224,8 +257,9 @@ export class Style {
                 ? { ...this.meta, ...other.meta }
                 : other.meta ?? this.meta,
             anchor: other.anchor ?? this.anchor,
-            // Cells under both change when either does: the sooner.
-            nextChange: Math.min(this.nextChange, other.nextChange),
+            // Cells under both change when either does: the sooner, and have been
+            // what they are since the later — the intersection of the two holds.
+            hold: { lastChange: Math.max(this.hold.lastChange, other.hold.lastChange), nextChange: Math.min(this.hold.nextChange, other.hold.nextChange) },
         });
     }
     equals(other) {
@@ -248,7 +282,8 @@ export class Style {
             this.overline === other.overline &&
             this.link === other.link &&
             anchorsEqual(this.anchor, other.anchor) &&
-            this.nextChange === other.nextChange);
+            this.hold.nextChange === other.hold.nextChange &&
+            this.hold.lastChange === other.hold.lastChange);
     }
     /**
      * The colours this style puts on screen at `colorSystem`: each flattened
@@ -298,7 +333,7 @@ export class Style {
     /**
      * The look as a canonical string that round-trips through `Style.parse()`:
      * colours, attributes and the link, which is all a style string can spell.
-     * What a style carries beyond its look — `meta`, `anchor`, `nextChange` —
+     * What a style carries beyond its look — `meta`, `anchor`, `hold` —
      * has no spelling and is not here, so two styles that differ only there
      * read alike; `equals` tells them apart.
      */
@@ -389,7 +424,7 @@ export class StyleStack {
     }
 }
 // --- Theme ---
-const STYLE_NAME_RE = /^[a-z][a-z0-9._-]*$/;
+const STYLE_NAME_RE = pattern(/^[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
@@ -408,19 +443,14 @@ export function layerStyle(base, over) {
 export class Theme {
     styles;
     constructor(definitions = {}, options) {
-        this.styles = new Map();
-        const inherit = options?.inherit !== false;
-        if (inherit) {
-            for (const [name, style] of Object.entries(DEFAULT_STYLES)) {
-                this.styles.set(name, style);
-            }
-        }
-        for (const [name, def] of Object.entries(definitions)) {
+        const inherited = options?.inherit !== false ? Object.entries(DEFAULT_STYLES) : [];
+        const defined = Object.entries(definitions).map(([name, def]) => {
             if (!STYLE_NAME_RE.test(name)) {
                 throw new Error(`Invalid style name: "${name}" (must be lowercase, start with letter, contain only letters, digits, ".", "-", "_")`);
             }
-            this.styles.set(name, Style.parse(def));
-        }
+            return [name, Style.parse(def)];
+        });
+        this.styles = new Map([...inherited, ...defined]);
     }
     get(name) {
         return this.styles.get(name);
@@ -695,16 +725,26 @@ export const DEFAULT_STYLES = {
     "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.h2": Style.parse("underline magenta"),
+    "markdown.h3": Style.parse("bold magenta"),
+    "markdown.h4": Style.parse("italic magenta"),
+    "markdown.h5": Style.parse("italic"),
+    "markdown.h6": Style.parse("dim"),
     // 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.em": Style.parse("italic"),
+    "markdown.strong": Style.parse("bold"),
+    "markdown.s": Style.parse("strike"),
+    "markdown.kbd": Style.parse("bold bright_yellow"),
+    "markdown.block_quote": Style.parse("magenta"),
+    "markdown.hr": Style.parse("dim"),
+    "markdown.item": NULL_STYLE,
+    "markdown.item.bullet": Style.parse("bold"),
+    "markdown.item.number": Style.parse("cyan"),
     "markdown.link": Style.parse("bright_blue"),
-    "markdown.link_url": Style.parse("blue"),
+    "markdown.link_url": Style.parse("underline blue"),
     "markdown.table.border": Style.parse("cyan"),
     "markdown.table.header": Style.parse("not bold cyan"),
     // Progress

package/dist/core/text.d.ts

@@ -33,15 +33,12 @@ export interface RichTextOptions {
     noWrap?: boolean;
 }
 export declare class RichText implements Renderable, Measurable {
-    private _text;
-    private _spans;
-    private _style;
-    private _justify;
-    private _overflow;
-    private _end;
-    private _tabSize;
-    private _noWrap;
+    private readonly _text;
+    private readonly _spans;
+    private readonly _format;
+    private readonly _tabSize;
     constructor(text?: string, options?: RichTextOptions);
+    private _reformat;
     get plain(): string;
     set plain(value: string);
     get length(): number;