tinky 0.1.0

package/lib/log-update.js

@@ -0,0 +1,147 @@
+import ansiEscapes from "ansi-escapes";
+import cliCursor from "cli-cursor";
+/**
+ * Creates a standard LogUpdate instance.
+ * Re-renders the entire previous output on each update.
+ *
+ * @param stream - The writable stream to log to.
+ * @param options - Configuration options.
+ * @param options.showCursor - Whether to show the cursor.
+ * @returns A LogUpdate instance.
+ */
+const createStandard = (stream, { showCursor = false } = {}) => {
+    let previousLineCount = 0;
+    let previousOutput = "";
+    let hasHiddenCursor = false;
+    const render = (str) => {
+        if (!showCursor && !hasHiddenCursor) {
+            cliCursor.hide(stream);
+            hasHiddenCursor = true;
+        }
+        const output = str + "\n";
+        if (output === previousOutput) {
+            return;
+        }
+        previousOutput = output;
+        stream.write(ansiEscapes.eraseLines(previousLineCount) + output);
+        previousLineCount = output.split("\n").length;
+    };
+    render.clear = () => {
+        stream.write(ansiEscapes.eraseLines(previousLineCount));
+        previousOutput = "";
+        previousLineCount = 0;
+    };
+    render.done = () => {
+        previousOutput = "";
+        previousLineCount = 0;
+        if (!showCursor) {
+            cliCursor.show(stream);
+            hasHiddenCursor = false;
+        }
+    };
+    render.sync = (str) => {
+        const output = str + "\n";
+        previousOutput = output;
+        previousLineCount = output.split("\n").length;
+    };
+    return render;
+};
+/**
+ * Creates an incremental LogUpdate instance.
+ * Updates only changed lines to improve performance and reduce flickering.
+ *
+ * @param stream - The writable stream to log to.
+ * @param options - Configuration options.
+ * @param options.showCursor - Whether to show the cursor.
+ * @returns A LogUpdate instance.
+ */
+const createIncremental = (stream, { showCursor = false } = {}) => {
+    let previousLines = [];
+    let previousOutput = "";
+    let hasHiddenCursor = false;
+    const render = (str) => {
+        if (!showCursor && !hasHiddenCursor) {
+            cliCursor.hide(stream);
+            hasHiddenCursor = true;
+        }
+        const output = str + "\n";
+        if (output === previousOutput) {
+            return;
+        }
+        const previousCount = previousLines.length;
+        const nextLines = output.split("\n");
+        const nextCount = nextLines.length;
+        const visibleCount = nextCount - 1;
+        if (output === "\n" || previousOutput.length === 0) {
+            stream.write(ansiEscapes.eraseLines(previousCount) + output);
+            previousOutput = output;
+            previousLines = nextLines;
+            return;
+        }
+        // We aggregate all chunks for incremental rendering into a buffer, and then
+        // write them to stdout at the end.
+        const buffer = [];
+        // Clear extra lines if the current content's line count is lower than the
+        // previous.
+        if (nextCount < previousCount) {
+            buffer.push(
+            // Erases the trailing lines and the final newline slot.
+            ansiEscapes.eraseLines(previousCount - nextCount + 1), 
+            // Positions cursor to the top of the rendered output.
+            ansiEscapes.cursorUp(visibleCount));
+        }
+        else {
+            buffer.push(ansiEscapes.cursorUp(previousCount - 1));
+        }
+        for (let i = 0; i < visibleCount; i++) {
+            // We do not write lines if the contents are the same. This prevents
+            // flickering during renders.
+            if (nextLines[i] === previousLines[i]) {
+                buffer.push(ansiEscapes.cursorNextLine);
+                continue;
+            }
+            buffer.push(ansiEscapes.cursorTo(0) +
+                nextLines[i] +
+                ansiEscapes.eraseEndLine +
+                "\n");
+        }
+        stream.write(buffer.join(""));
+        previousOutput = output;
+        previousLines = nextLines;
+    };
+    render.clear = () => {
+        stream.write(ansiEscapes.eraseLines(previousLines.length));
+        previousOutput = "";
+        previousLines = [];
+    };
+    render.done = () => {
+        previousOutput = "";
+        previousLines = [];
+        if (!showCursor) {
+            cliCursor.show(stream);
+            hasHiddenCursor = false;
+        }
+    };
+    render.sync = (str) => {
+        const output = str + "\n";
+        previousOutput = output;
+        previousLines = output.split("\n");
+    };
+    return render;
+};
+/**
+ * Creates a LogUpdate instance.
+ *
+ * @param stream - The writable stream to log to.
+ * @param options - Configuration options.
+ * @param options.showCursor - Whether to show the cursor. Default is false.
+ * @param options.incremental - Whether to use incremental rendering.
+ * @returns A LogUpdate instance.
+ */
+const create = (stream, { showCursor = false, incremental = false } = {}) => {
+    if (incremental) {
+        return createIncremental(stream, { showCursor });
+    }
+    return createStandard(stream, { showCursor });
+};
+export const logUpdate = { create };

package/lib/measure-element.d.ts

@@ -0,0 +1,19 @@
+import { type DOMElement } from "./dom.js";
+interface Output {
+    /**
+     * Element width.
+     */
+    width: number;
+    /**
+     * Element height.
+     */
+    height: number;
+}
+/**
+ * Measure the dimensions of a particular `<Box>` element.
+ *
+ * @param node - The DOM element to measure.
+ * @returns The measured dimensions.
+ */
+export declare const measureElement: (node: DOMElement) => Output;
+export {};

package/lib/measure-element.js

@@ -0,0 +1,13 @@
+/**
+ * Measure the dimensions of a particular `<Box>` element.
+ *
+ * @param node - The DOM element to measure.
+ * @returns The measured dimensions.
+ */
+export const measureElement = (node) => {
+    const layout = node.taffyNode?.tree.getLayout(node.taffyNode.id);
+    return {
+        width: layout?.width ?? 0,
+        height: layout?.height ?? 0,
+    };
+};

package/lib/measure-text.d.ts

@@ -0,0 +1,13 @@
+interface Output {
+    width: number;
+    height: number;
+}
+/**
+ * Measures the width and height of a text string.
+ * Results are cached to improve performance.
+ *
+ * @param text - The text string to measure.
+ * @returns The width and height of the text.
+ */
+export declare const measureText: (text: string) => Output;
+export {};

package/lib/measure-text.js

@@ -0,0 +1,26 @@
+import widestLine from "widest-line";
+const cache = new Map();
+/**
+ * Measures the width and height of a text string.
+ * Results are cached to improve performance.
+ *
+ * @param text - The text string to measure.
+ * @returns The width and height of the text.
+ */
+export const measureText = (text) => {
+    if (text.length === 0) {
+        return {
+            width: 0,
+            height: 0,
+        };
+    }
+    const cachedDimensions = cache.get(text);
+    if (cachedDimensions) {
+        return cachedDimensions;
+    }
+    const width = widestLine(text);
+    const height = text.split("\n").length;
+    const dimensions = { width, height };
+    cache.set(text, dimensions);
+    return dimensions;
+};

package/lib/output.d.ts

@@ -0,0 +1,73 @@
+import { type OutputTransformer } from "./render-node-to-output.js";
+/**
+ * Options for creating an Output instance.
+ */
+interface Options {
+    /**
+     * Width of the output area.
+     */
+    width: number;
+    /**
+     * Height of the output area.
+     */
+    height: number;
+}
+/**
+ * Represents a clipping rectangle.
+ */
+interface Clip {
+    x1: number | undefined;
+    x2: number | undefined;
+    y1: number | undefined;
+    y2: number | undefined;
+}
+/**
+ * "Virtual" output class
+ *
+ * Handles the positioning and saving of the output of each node in the tree.
+ * Also responsible for applying transformations to each character.
+ *
+ * Used to generate the final output of all nodes before writing to stdout.
+ */
+export declare class Output {
+    width: number;
+    height: number;
+    private readonly operations;
+    /**
+     * Creates a new Output instance.
+     *
+     * @param options - Configuration options containing width and height.
+     */
+    constructor(options: Options);
+    /**
+     * Writes text to the output at a specified position.
+     *
+     * @param x - The x-coordinate (column).
+     * @param y - The y-coordinate (row).
+     * @param text - The text to write.
+     * @param options - Options containing transformers.
+     */
+    write(x: number, y: number, text: string, options: {
+        transformers: OutputTransformer[];
+    }): void;
+    /**
+     * Sets a clipping area for subsequent operations.
+     *
+     * @param clip - The clipping rectangle.
+     */
+    clip(clip: Clip): void;
+    /**
+     * Removes the last clipping area, restoring the previous one.
+     */
+    unclip(): void;
+    /**
+     * Generates the final output string and its height.
+     *
+     * @returns An object containing the generated output string and its height.
+     */
+    get(): {
+        output: string;
+        height: number;
+    };
+}
+export {};

package/lib/output.js

@@ -0,0 +1,190 @@
+import sliceAnsi from "slice-ansi";
+import stringWidth from "string-width";
+import widestLine from "widest-line";
+import { styledCharsFromTokens, styledCharsToString, tokenize, } from "@alcalzone/ansi-tokenize";
+/**
+ * "Virtual" output class
+ *
+ * Handles the positioning and saving of the output of each node in the tree.
+ * Also responsible for applying transformations to each character.
+ *
+ * Used to generate the final output of all nodes before writing to stdout.
+ */
+export class Output {
+    width;
+    height;
+    operations = [];
+    /**
+     * Creates a new Output instance.
+     *
+     * @param options - Configuration options containing width and height.
+     */
+    constructor(options) {
+        const { width, height } = options;
+        this.width = width;
+        this.height = height;
+    }
+    /**
+     * Writes text to the output at a specified position.
+     *
+     * @param x - The x-coordinate (column).
+     * @param y - The y-coordinate (row).
+     * @param text - The text to write.
+     * @param options - Options containing transformers.
+     */
+    write(x, y, text, options) {
+        const { transformers } = options;
+        if (!text) {
+            return;
+        }
+        this.operations.push({
+            type: "write",
+            x,
+            y,
+            text,
+            transformers,
+        });
+    }
+    /**
+     * Sets a clipping area for subsequent operations.
+     *
+     * @param clip - The clipping rectangle.
+     */
+    clip(clip) {
+        this.operations.push({
+            type: "clip",
+            clip,
+        });
+    }
+    /**
+     * Removes the last clipping area, restoring the previous one.
+     */
+    unclip() {
+        this.operations.push({
+            type: "unclip",
+        });
+    }
+    /**
+     * Generates the final output string and its height.
+     *
+     * @returns An object containing the generated output string and its height.
+     */
+    get() {
+        // Initialize output array with a specific set of rows, so that
+        // margin/padding at the bottom is preserved
+        const output = [];
+        for (let y = 0; y < this.height; y++) {
+            const row = [];
+            for (let x = 0; x < this.width; x++) {
+                row.push({
+                    type: "char",
+                    value: " ",
+                    fullWidth: false,
+                    styles: [],
+                });
+            }
+            output.push(row);
+        }
+        const clips = [];
+        for (const operation of this.operations) {
+            if (operation.type === "clip") {
+                clips.push(operation.clip);
+            }
+            if (operation.type === "unclip") {
+                clips.pop();
+            }
+            if (operation.type === "write") {
+                const { text, transformers } = operation;
+                let { x, y } = operation;
+                let lines = text.split("\n");
+                const clip = clips.at(-1);
+                if (clip) {
+                    const clipHorizontally = typeof clip.x1 === "number" && typeof clip.x2 === "number";
+                    const clipVertically = typeof clip.y1 === "number" && typeof clip.y2 === "number";
+                    const clipX1 = clip.x1 ?? 0;
+                    const clipX2 = clip.x2 ?? 0;
+                    const clipY1 = clip.y1 ?? 0;
+                    const clipY2 = clip.y2 ?? 0;
+                    // If text is positioned outside of clipping area altogether,
+                    // skip to the next operation to avoid unnecessary calculations
+                    if (clipHorizontally) {
+                        const width = widestLine(text);
+                        if (x + width < clipX1 || x > clipX2) {
+                            continue;
+                        }
+                    }
+                    if (clipVertically) {
+                        const height = lines.length;
+                        if (y + height < clipY1 || y > clipY2) {
+                            continue;
+                        }
+                    }
+                    if (clipHorizontally) {
+                        lines = lines.map((line) => {
+                            const from = x < clipX1 ? clipX1 - x : 0;
+                            const width = stringWidth(line);
+                            const to = x + width > clipX2 ? clipX2 - x : width;
+                            return sliceAnsi(line, from, to);
+                        });
+                        if (x < clipX1) {
+                            x = clipX1;
+                        }
+                    }
+                    if (clipVertically) {
+                        const from = y < clipY1 ? clipY1 - y : 0;
+                        const height = lines.length;
+                        const to = y + height > clipY2 ? clipY2 - y : height;
+                        lines = lines.slice(from, to);
+                        if (y < clipY1) {
+                            y = clipY1;
+                        }
+                    }
+                }
+                let offsetY = 0;
+                for (const [index, line] of lines.entries()) {
+                    const currentLine = output[y + offsetY];
+                    // Line can be missing if `text` is taller than height of
+                    // pre-initialized `this.output`
+                    if (!currentLine) {
+                        continue;
+                    }
+                    let transformedLine = line;
+                    for (const transformer of transformers) {
+                        transformedLine = transformer(transformedLine, index);
+                    }
+                    const characters = styledCharsFromTokens(tokenize(transformedLine));
+                    let offsetX = x;
+                    for (const character of characters) {
+                        currentLine[offsetX] = character;
+                        // Determine printed width using string-width to align with measurement
+                        const characterWidth = Math.max(1, stringWidth(character.value));
+                        // For multi-column characters, clear following cells to avoid stray
+                        // spaces/artifacts
+                        if (characterWidth > 1) {
+                            for (let index = 1; index < characterWidth; index++) {
+                                currentLine[offsetX + index] = {
+                                    type: "char",
+                                    value: "",
+                                    fullWidth: false,
+                                    styles: character.styles,
+                                };
+                            }
+                        }
+                        offsetX += characterWidth;
+                    }
+                    offsetY++;
+                }
+            }
+        }
+        const generatedOutput = output
+            .map((line) => {
+            const lineWithoutEmptyItems = line.filter((item) => item !== undefined);
+            return styledCharsToString(lineWithoutEmptyItems).trimEnd();
+        })
+            .join("\n");
+        return {
+            output: generatedOutput,
+            height: output.length,
+        };
+    }
+}

package/lib/parse-keypress.d.ts

@@ -0,0 +1,20 @@
+import { Buffer } from "node:buffer";
+export declare const nonAlphanumericKeys: string[];
+interface ParsedKey {
+    name: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    option: boolean;
+    sequence: string;
+    raw: string | undefined;
+    code?: string;
+}
+/**
+ * Parses a keypress string or buffer into a structured key object.
+ *
+ * @param s - The string or buffer to parse.
+ * @returns The parsed key object.
+ */
+export declare const parseKeypress: (s?: Buffer | string) => ParsedKey;
+export {};