@matter/tools 0.12.2-alpha.0-20250201-eb5d40a2f → 0.12.3-alpha.0-20250203-34ba45cae

package/src/ansi-text/text-builder.ts

@@ -0,0 +1,261 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Producer } from "./producer.js";
+import {
+    Color,
+    EightBitColor,
+    ExtendedColor,
+    RgbColor,
+    SgrOpcode,
+    SgrOpcodeBlock,
+    SgrOpcodeToUndoOpcode,
+} from "./sgr.js";
+import { Style } from "./style.js";
+import { TextWriter } from "./text-writer.js";
+
+/**
+ * Convenience API for building ANSI text.
+ *
+ * Allows you to create ANSI escape sequences using e.g. `ansi.bright.yellow.bg.blue.blink`.
+ */
+export interface TextBuilder extends Style {
+    (...text: Producer.Sequence): TextBuilder;
+
+    readonly state: TextBuilder.State;
+    readonly bg: TextBuilder;
+    readonly not: TextBuilder;
+    readonly reset: TextBuilder;
+    readonly bold: TextBuilder;
+    readonly dim: TextBuilder;
+    readonly bright: TextBuilder;
+    readonly italic: TextBuilder;
+    readonly underline: TextBuilder;
+    readonly doubleUnderline: TextBuilder;
+    readonly blink: TextBuilder;
+    readonly fastBlink: TextBuilder;
+    readonly invert: TextBuilder;
+    readonly conceal: TextBuilder;
+    readonly strike: TextBuilder;
+    readonly black: TextBuilder;
+    readonly red: TextBuilder;
+    readonly green: TextBuilder;
+    readonly yellow: TextBuilder;
+    readonly blue: TextBuilder;
+    readonly magenta: TextBuilder;
+    readonly cyan: TextBuilder;
+    readonly white: TextBuilder;
+    color(color: Color | EightBitColor | RgbColor): TextBuilder;
+
+    factory: TextBuilder.Factory;
+}
+
+export function TextBuilder(
+    definition?: Style.InputDefinition | Style,
+    derivesFrom?: Style,
+    state?: TextBuilder.State,
+) {
+    if (derivesFrom instanceof TextBuilder) {
+        state = { ...(derivesFrom as TextBuilder).state, ...state };
+    } else if (state === undefined) {
+        state = {};
+    }
+
+    definition = Style.definitionOf(definition);
+
+    const self = function TextBuilderInstance(...text: Producer.Sequence) {
+        const sequence = self.state.sequence ? [...self.state.sequence] : [];
+        if (self.styleDefinition?.length) {
+            sequence.push(self.styleToken);
+        }
+        sequence.push(...text);
+        return TextBuilder(self, self, { sequence, revert: true });
+    } as TextBuilder;
+
+    Object.setPrototypeOf(self, TextBuilder.prototype);
+
+    (self as any).state = state;
+
+    if (definition !== undefined) {
+        self.styleDefinition = definition;
+    }
+
+    return self;
+}
+
+TextBuilder.prototype = Object.create(Style.prototype, {
+    bg: chmode({ bg: true }),
+    not: chmode({ not: true }),
+    bold: toggle("bold"),
+    dim: toggle("dim"),
+    bright: chmode({ bright: true }),
+    italic: toggle("italic"),
+    underline: toggle("underline"),
+    doubleUnderline: toggle("doubleUnderline"),
+    slowBlink: toggle("slowBlink"),
+    fastBlink: toggle("fastBlink"),
+    invert: toggle("invert"),
+    conceal: toggle("conceal"),
+    strike: toggle("strike"),
+    black: color("black"),
+    red: color("red"),
+    green: color("green"),
+    yellow: color("yellow"),
+    blue: color("blue"),
+    magenta: color("magenta"),
+    cyan: color("cyan"),
+    white: color("white"),
+
+    reset: {
+        get() {
+            return (this as TextBuilder).addStyle([0]);
+        },
+    },
+
+    color: {
+        value(this: TextBuilder, color: Color | EightBitColor | RgbColor) {
+            if (this.state.not) {
+                return this.addStyle([this.state.bg ? SgrOpcode.normalBg : SgrOpcode.normalFg]);
+            }
+
+            if (typeof color === "object") {
+                if ("color" in color) {
+                    return this.addStyle([Color.extended, ExtendedColor.eightBit, color.color]);
+                }
+                return this.addStyle([Color.extended, ExtendedColor.rgb, color.r ?? 0, color.g ?? 0, color.b ?? 0]);
+            }
+
+            const block = this.state.bg
+                ? this.state.bright
+                    ? SgrOpcodeBlock.bgBright
+                    : SgrOpcodeBlock.bg
+                : this.state.bright
+                  ? SgrOpcodeBlock.fgBright
+                  : SgrOpcodeBlock.fg;
+
+            return this.addStyle([block + color]);
+        },
+    },
+
+    toString: {
+        value(this: TextBuilder) {
+            let { sequence } = this.state;
+            if (!sequence) {
+                sequence = [this.styleToken];
+            }
+
+            if (this.state.revert) {
+                sequence = [...sequence, this.undoStyle.styleToken];
+            }
+
+            const parts = Array<string>();
+
+            const writer = new TextWriter(part => parts.push(part));
+            writer.write(...sequence);
+            writer.close();
+
+            return parts.join("");
+        },
+    },
+
+    [Symbol.iterator]: {
+        get(this: TextBuilder) {
+            if (this.state.sequence === undefined) {
+                return {
+                    next() {
+                        return undefined;
+                    },
+
+                    done: true,
+                };
+            }
+            let sequence = this.state.sequence;
+            if (this.state.revert) {
+                sequence = [...sequence, this.undoStyle.styleToken];
+            }
+            const iterable = Producer.of(sequence);
+            return iterable[Symbol.iterator].bind(iterable);
+        },
+    },
+
+    factory: {
+        value: TextBuilder,
+    },
+});
+
+function chmode(state?: TextBuilder.State) {
+    return {
+        get(this: TextBuilder) {
+            return TextBuilder(this, this, state);
+        },
+    };
+}
+
+function toggle(name: keyof typeof SgrOpcode) {
+    const on = SgrOpcode[name];
+    const off = SgrOpcodeToUndoOpcode[on];
+    if (off === undefined) {
+        throw new Error(`Can't toggle opcode ${on}`);
+    }
+
+    return {
+        get(this: TextBuilder) {
+            return this.addStyle([this.state.not ? off : on]);
+        },
+    };
+}
+
+function color(color: keyof typeof Color) {
+    const opcode = Color[color];
+    return {
+        get(this: TextBuilder) {
+            return this.color(opcode);
+        },
+    };
+}
+
+export namespace TextBuilder {
+    export interface State {
+        /**
+         * If next build affects a color it will modify bg rather than fg.
+         */
+        readonly bg?: boolean;
+
+        /**
+         * If next build affects 8-bit color the color will render as bright.
+         */
+        readonly bright?: boolean;
+
+        /**
+         * If next build modifies ANSI styling its meaning is inverted.
+         */
+        readonly not?: boolean;
+
+        /**
+         * Serialization will include style reversion as the final token.
+         *
+         * Set after invoking builder as function, cleared when modifying style.  This means that ansi.red("foo") is
+         * terminated but ansi.red("foo").green will render as a red "foo" and leave text styled green.
+         */
+        readonly revert?: boolean;
+
+        /**
+         * The serialization sequence.  Populated by invoking builder as function.
+         */
+        readonly sequence?: Producer.Sequence;
+    }
+
+    export type Factory = (
+        definition?: Style.Definition | Style,
+        derivesFrom?: Style,
+        state?: TextBuilder.State,
+    ) => TextBuilder;
+}
+
+/**
+ * Initial builder.
+ */
+export const ansi = TextBuilder();

package/src/ansi-text/text-writer.ts

@@ -0,0 +1,363 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Consumer } from "./consumer.js";
+import { ContiguousOutputSegment } from "./contiguous-output-segment.js";
+import { Producer } from "./producer.js";
+import { SgrOpcode } from "./sgr.js";
+import { Style } from "./style.js";
+import { Token } from "./token.js";
+import { tokenize } from "./tokenize.js";
+
+const DEFAULT_TAB_WIDTH = 4;
+
+/**
+ * Low-level text output with ANSI escape sequences, maintaining state regarding style and width of current line.
+ */
+export class TextWriter implements Consumer {
+    tabWidth: number;
+
+    #terminalWidth?: number;
+    #currentLineWidth = 0;
+    #out: (text: string) => void;
+    #activeStyle = Style.Inherit;
+    #styleDirty = true;
+    #currentStyle = Style.Inherit;
+    #linePrefix?: ContiguousOutputSegment;
+    #state: Consumer.State;
+    #styleEnabled = true;
+    #isNewLine = true;
+    #buffer?: string[];
+    #revertHandlers?: Set<() => void>;
+
+    constructor(out: (text: string) => void, options?: Writer.Options) {
+        const { tabWidth, terminalWidth, linePrefix } = options ?? {};
+        this.#out = out;
+        this.tabWidth = tabWidth ?? DEFAULT_TAB_WIDTH;
+        this.#terminalWidth = terminalWidth;
+        if (linePrefix) {
+            this.#linePrefix = new ContiguousOutputSegment(...tokenize(linePrefix));
+        }
+
+        const self = this;
+
+        this.#state = function state(options?: Consumer.Options, executor?: () => void): Consumer.Context | undefined {
+            options = { ...options };
+
+            const revertTo = { ...self.state, options } as Consumer.Options;
+
+            const { linePrefix, style, buffer } = options;
+            if (linePrefix) {
+                if (self.#linePrefix) {
+                    self.#linePrefix.push(linePrefix);
+                } else {
+                    self.#linePrefix = new ContiguousOutputSegment(linePrefix);
+                }
+            }
+
+            if (style) {
+                if (self.#currentStyle) {
+                    self.#currentStyle = self.#currentStyle.addStyle(style);
+                } else {
+                    self.#currentStyle = style;
+                }
+                self.#styleDirty = true;
+            }
+
+            if (!!buffer !== !!self.#buffer) {
+                if (buffer) {
+                    self.#buffer = [];
+                } else {
+                    self.#buffer = undefined;
+                }
+            }
+
+            const context = {
+                close() {
+                    if (self.#revertHandlers) {
+                        for (const fn of self.#revertHandlers) {
+                            fn();
+                        }
+                    }
+
+                    if (revertTo.style) {
+                        revertTo.style = self.#currentStyle.undoStyle.addStyle(revertTo.style);
+                    } else {
+                        revertTo.style = Style.None;
+                    }
+
+                    for (const key in revertTo) {
+                        (self.state as any)[key] = (revertTo as any)[key];
+                    }
+                },
+
+                [Symbol.dispose]() {
+                    this.close();
+                },
+            };
+
+            if (executor) {
+                try {
+                    executor();
+                } finally {
+                    context.close();
+                }
+            } else {
+                return context;
+            }
+        } as Consumer.State;
+
+        Object.defineProperties(this.#state, {
+            style: {
+                get(this: never) {
+                    return self.#currentStyle;
+                },
+
+                set(this: never, style) {
+                    self.#currentStyle = style ?? Style.Inherit;
+                    self.#styleDirty = true;
+                },
+
+                enumerable: true,
+            },
+
+            linePrefix: {
+                get(this: never) {
+                    return self.#linePrefix?.toString();
+                },
+
+                set(this: never, prefix) {
+                    if (prefix) {
+                        self.#linePrefix = new ContiguousOutputSegment(...tokenize(prefix));
+                    } else {
+                        self.#linePrefix = undefined;
+                    }
+                },
+
+                enumerable: true,
+            },
+
+            terminalWidth: {
+                get(this: never) {
+                    return self.#terminalWidth;
+                },
+
+                set(this: never, width: number | undefined) {
+                    self.#terminalWidth = width;
+                },
+
+                enumerable: true,
+            },
+
+            styleEnabled: {
+                get(this: never) {
+                    return self.#styleEnabled;
+                },
+
+                set(this: never, enabled: boolean) {
+                    self.#styleEnabled = enabled;
+                },
+
+                enumerable: true,
+            },
+
+            availableWidth: {
+                get(this: never) {
+                    if (self.#terminalWidth === undefined) {
+                        return undefined;
+                    }
+
+                    if (self.#linePrefix) {
+                        const width = self.#terminalWidth - self.#linePrefix.width;
+                        if (width > 0) {
+                            return width;
+                        }
+                        return undefined;
+                    }
+
+                    return self.#terminalWidth;
+                },
+            },
+
+            remainingWidth: {
+                get(this: never) {
+                    if (self.#terminalWidth === undefined) {
+                        return undefined;
+                    }
+                    return self.#terminalWidth - self.#currentLineWidth;
+                },
+            },
+
+            buffer: {
+                get(this: never) {
+                    return !!self.#buffer;
+                },
+
+                set(this: never, buffering: boolean) {
+                    if (!!self.#buffer === buffering) {
+                        return;
+                    }
+                    if (buffering) {
+                        self.#buffer = [];
+                        return;
+                    }
+                    if (self.#buffer) {
+                        self.#out(self.#buffer.join(""));
+                        self.#buffer = undefined;
+                    }
+                },
+
+                enumerable: true,
+            },
+
+            onRevert: {
+                value(fn: () => void) {
+                    if (!self.#revertHandlers) {
+                        self.#revertHandlers = new Set();
+                    }
+                    self.#revertHandlers.add(fn);
+                },
+            },
+
+            offRevert: {
+                value(fn: () => void) {
+                    if (self.#revertHandlers) {
+                        self.#revertHandlers.add(fn);
+                    }
+                },
+            },
+        });
+    }
+
+    get state() {
+        return this.#state;
+    }
+
+    write(...text: Producer.Sequence) {
+        for (const token of Producer.of(text)) {
+            this.#addToken(token);
+        }
+    }
+
+    close() {
+        this.#writeStyle();
+    }
+
+    /**
+     * Reset styling.
+     */
+    reset() {
+        if (this.#currentStyle.styleCodes.find(code => code !== SgrOpcode.reset)) {
+            this.#currentStyle = Style.None;
+            this.#styleDirty = true;
+        }
+    }
+
+    #addToken(token: Token, forLinePrefix = false) {
+        if (this.#isNewLine && this.#linePrefix && !forLinePrefix) {
+            this.#isNewLine = false;
+            const style = this.#currentStyle;
+            this.#currentStyle = Style.None;
+            this.#styleDirty = true;
+            for (const token of this.#linePrefix.tokens) {
+                this.#addToken(token, true);
+            }
+            this.#currentStyle = style;
+            this.#styleDirty = true;
+        }
+
+        switch (token.kind) {
+            case "newline":
+                this.#emitLine("\n");
+                break;
+
+            case "carriage-return":
+                this.#emitLine("\r");
+                break;
+
+            case "tab":
+                let width = this.tabWidth - (this.#currentLineWidth % this.tabWidth);
+                if (width === 0) {
+                    width = this.tabWidth;
+                }
+                this.#writeText("".padStart(width));
+                this.#currentLineWidth += width;
+                break;
+
+            case "breaking":
+                this.#writeText(token.str);
+                this.#currentLineWidth += token.width;
+                break;
+
+            case "style":
+                this.#currentStyle = this.#currentStyle.addStyle(token.style);
+                this.#styleDirty = true;
+                break;
+
+            case "ansi":
+                if (this.#styleEnabled) {
+                    this.#writeText(token.sequence);
+                }
+                if (token.newColumn !== undefined) {
+                    // TODO - don't need to support yet but to be correct should adjust sequence to account for indent
+                    if (!this.#currentLineWidth) {
+                        this.#isNewLine = true;
+                    }
+                    this.#currentLineWidth = token.newColumn;
+                }
+                break;
+
+            case "nonbreaking":
+                this.#writeText(token.str);
+                this.#currentLineWidth += token.width;
+                break;
+        }
+    }
+
+    #writeText(text: string) {
+        this.#writeStyle();
+        this.#emit(text);
+    }
+
+    #writeStyle() {
+        if (this.#styleDirty && this.#styleEnabled) {
+            this.#styleDirty = false;
+
+            this.#emit(this.#activeStyle.diffStyle(this.#currentStyle).toString());
+
+            this.#activeStyle = this.#currentStyle;
+        }
+    }
+
+    #emit(text: string) {
+        if (this.#buffer) {
+            this.#buffer.push(text);
+        } else {
+            this.#out(text);
+        }
+    }
+
+    #emitLine(terminator?: string) {
+        this.#writeStyle();
+        this.#beginLine();
+        if (terminator) {
+            this.#emit(terminator);
+        }
+    }
+
+    #beginLine() {
+        this.#isNewLine = true;
+        this.#currentLineWidth = 0;
+    }
+}
+
+export namespace Writer {
+    export interface Options {
+        tabWidth?: number;
+        terminalWidth?: number;
+        linePrefix?: string;
+    }
+}

package/src/ansi-text/token.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Style } from "./style.js";
+
+/**
+ * An individual lexical token in a Unicode string with ANSI escape codes.
+ */
+export type Token =
+    | NonbreakingToken
+    | BreakingToken
+    | StyleToken
+    | NewlineToken
+    | CarriageReturnToken
+    | TabToken
+    | AnsiToken;
+
+/**
+ * Text sequence that is not whitespace or a control sequence.
+ */
+export interface NonbreakingToken {
+    kind: "nonbreaking";
+    str: string;
+    width: number;
+}
+
+/**
+ * Non-tab non-newline whitespace sequence.
+ */
+export interface BreakingToken {
+    kind: "breaking";
+    str: string;
+    width: number;
+}
+
+/**
+ * A text styling sequence.
+ */
+export interface StyleToken {
+    kind: "style";
+    style: Style;
+}
+
+/**
+ * Newline character.
+ */
+export interface NewlineToken {
+    kind: "newline";
+}
+
+/**
+ * Carriage return character.
+ */
+export interface CarriageReturnToken {
+    kind: "carriage-return";
+}
+
+/**
+ * Tab character.
+ */
+export interface TabToken {
+    kind: "tab";
+}
+
+/**
+ * Misc valid non-CSI (style) ANSI codes.  Currently we tokenize because we have to parse them anyway to skip, but
+ * otherwise we ignore.
+ */
+export interface AnsiToken {
+    kind: "ansi";
+    sequence: string;
+    newColumn?: number;
+}