@promptctl/rich-js 0.24.1 → 0.25.0

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;
@@ -153,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;
@@ -189,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.
@@ -225,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) {
@@ -249,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
@@ -299,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.
      */
@@ -390,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
@@ -409,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);

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;