@remotex-labs/xansi/dist/shadow.service.d.ts

A lightweight ANSI utility library for styling terminal output

/**
 * This file was automatically generated by xBuild.
 * DO NOT EDIT MANUALLY.
 */

/**
 * A virtual terminal renderer that manages efficient screen updates
 *
 * ShadowRenderer provides a mechanism to render content to the terminal
 * while minimizing the number of draw operations needed. It does this by
 * maintaining an internal representation of both the desired content and
 * the current terminal state, only updating parts of the screen that have
 * changed between render cycles.
 *
 * @remarks
 * The renderer maintains separate buffers for content (what should be displayed)
 * and view (what is currently displayed). During rendering, it performs a diff
 * between these buffers to determine the minimal set of changes needed to update
 * the terminal display.
 *
 * This class supports:
 * - Partial screen updates for performance
 * - Content scrolling
 * - Variable viewport dimensions
 * - Rich text styling through cell properties
 *
 * @example
 * ```ts
 * // Create a new renderer positioned at row 2, column 3 with dimensions 80x24
 * const renderer = new ShadowRenderer(2, 3, 80, 24);
 *
 * // Set some content and render it
 * renderer.writeText(0, 0, contentCells);
 * renderer.render();
 * ```
 *
 * @since 1.0.0
 */
declare class ShadowRenderer {
    private terminalHeight;
    private terminalWidth;
    private topPosition;
    private leftPosition;
    /**
     * Current scroll position in the content
     *
     * @remarks
     * Tracks the index of the first row visible at the top of the viewport.
     * A value of 0 indicates the content is not scrolled, while higher values
     * indicate the content has been scrolled down by that many rows.
     *
     * This value is used during rendering to determine which portion of the
     * contentBuffer to display in the visible area of the terminal.
     *
     * @see scroll - The getter for accessing this value
     *
     * @private
     */
    private scrollPosition;
    /**
     * Internal buffer representing the current visible state of the terminal
     *
     * @remarks
     * This two-dimensional array stores the actual rendered content as it appears in the terminal.
     * It's organized in a row-major format, with each row containing an array of strings.
     *
     * Unlike contentBuffer which stores full cell information, viewBuffer only contains
     * the string representation of each cell. This buffer is used for diffing against
     * new content to determine what needs to be redrawn during render operations,
     * allowing for efficient partial updates to the terminal display.
     *
     * @private
     */
    private viewBuffer;
    /**
     * Internal buffer containing the content to be rendered
     *
     * @remarks
     * This two-dimensional array stores all content cells in a row-major format,
     * where each row is an array of CellInterface objects representing individual
     * characters with their associated style information.
     *
     * The outer array represents rows, while the inner arrays represent columns within each row.
     * This structure allows for efficient access and manipulation of cell data during
     * the rendering process.
     *
     * @private
     * @see CellInterface
     */
    private contentBuffer;
    /**
     * Creates a new ShadowRenderer instance for terminal-based UI rendering
     *
     * @param terminalHeight - The height of the terminal viewport in rows
     * @param terminalWidth - The width of the terminal viewport in columns
     * @param topPosition - The top-offset position within the terminal
     * @param leftPosition - The left offset position within the terminal
     *
     * @since 1.0.0
     */
    constructor(terminalHeight: number, terminalWidth: number, topPosition: number, leftPosition: number);
    /**
     * Gets the top position offset of the renderer in the terminal
     *
     * @returns The row offset from the top edge of the terminal
     *
     * @since 1.0.0
     */
    get top(): number;
    /**
     * Gets the left position offset of the renderer in the terminal
     *
     * @returns The column offset from the left edge of the terminal
     *
     * @since 1.0.0
     */
    get left(): number;
    /**
     * Gets the width of the renderer's viewport
     *
     * @returns The number of columns visible in the renderer's viewport
     *
     * @since 1.0.0
     */
    get width(): number;
    /**
     * Gets the height of the renderer's viewport
     *
     * @returns The number of rows visible in the renderer's viewport
     *
     * @since 1.0.0
     */
    get height(): number;
    /**
     * Gets the current scroll position
     *
     * @returns The current row index at the top of the viewport
     *
     * @since 1.0.0
     */
    get scroll(): number;
    /**
     * Sets the top position offset of the renderer in the terminal
     *
     * @param top - The row offset from the top edge of the terminal
     *
     * @remarks
     * This setter updates the vertical positioning of the renderer's viewport
     * within the terminal. The top position is used as an offset when calculating
     * absolute cursor positions during rendering operations.
     *
     * Note that changing the top position does not automatically trigger a re-render.
     * You should call the render() method separately after changing the position.
     *
     * @since 1.0.0
     */
    set top(top: number);
    /**
     * Sets the left position offset of the renderer in the terminal
     *
     * @param left - The column offset from the left edge of the terminal
     *
     * @remarks
     * This setter updates the horizontal positioning of the renderer's viewport
     * within the terminal. The left position is used as an offset when calculating
     * absolute cursor positions during rendering operations.
     *
     * Note that changing the left position does not automatically trigger a re-render.
     * You should call the render() method separately after changing the position.
     *
     * @since 1.0.0
     */
    set left(left: number);
    /**
     * Sets the width of the renderer's viewport
     *
     * @param terminalWidth - The number of columns visible in the renderer's viewport
     *
     * @remarks
     * This setter updates the internal width property which controls how many
     * columns are rendered during the rendering process. This should be updated
     * whenever the terminal or display area is resized.
     *
     * Note that changing the width does not automatically trigger a re-render.
     * You should call the render() method separately after changing dimensions.
     *
     * @since 1.0.0
     */
    set width(terminalWidth: number);
    /**
     * Sets the height of the renderer's viewport
     *
     * @param terminalHeight - The number of rows visible in the renderer's viewport
     *
     * @remarks
     * This setter updates the internal height property which controls how many
     * rows are rendered during the rendering process. This should be updated
     * whenever the terminal or display area is resized.
     *
     * Note that changing the height does not automatically trigger a re-render.
     * You should call the render() method separately after changing dimensions.
     *
     * @since 1.0.0
     */
    set height(terminalHeight: number);
    /**
     * Sets the scroll position and renders the updated view
     *
     * @param position - New scroll position or relative movement (if negative)
     *
     * @remarks
     * This setter handles both absolute and relative scrolling:
     * - Positive values set the absolute scroll position
     * - Negative values move relative to the current position
     *
     * If the requested position scrolls beyond the end of the content,
     * the operation is ignored. After setting a valid scroll position,
     * the view is automatically re-rendered.
     *
     * @example
     * ```ts
     * // Set absolute scroll position to row 10
     * renderer.scroll = 10;
     *
     * // Scroll up 3 rows (relative movement)
     * renderer.scroll = -3;
     * ```
     *
     * @since 1.0.0
     */
    set scroll(position: number);
    /**
     * Clears all content from the renderer and resets its internal state.
     *
     * @remarks
     * This method removes all entries from both the `viewBuffer` and `contentBuffer`,
     * effectively resetting the renderer to its initial empty state.
     *
     * @returns void — This method does not produce a return value.
     *
     * @example
     * ```ts
     * // Completely reset the renderer's buffers
     * renderer.clear();
     * ```
     *
     * @since 1.0.0
     */
    clear(): void;
    /**
     * Clears the visible content from the terminal screen
     *
     * @returns Nothing
     *
     * @remarks
     * This method builds a string of ANSI escape sequences that move the cursor
     * to the beginning of each line in the view buffer and then clears each line.
     * It doesn't reset the internal buffers, only clears the visible output.
     *
     * @example
     * ```ts
     * // Clear just the screen output without resetting buffers
     * renderer.clearScreen();
     * ```
     *
     * @since 1.0.0
     */
    clearScreen(): void;
    /**
     * Writes text to the specified position in the content buffer
     *
     * @param row - Row position (0-based)
     * @param column - Column position (0-based)
     * @param text - Text to write
     * @param clean - Whether to clear existing content first
     *
     * @remarks
     * This method only updates the internal content buffer and marks cells as dirty.
     * It doesn't immediately render to the screen - call render() to display changes.
     * Only the first line of multi-line text is processed, and a text is truncated
     * if it exceeds terminal boundaries.
     *
     * @example
     * ```ts
     * // Write text in the top-left corner
     * renderer.writeText(0, 0, "Hello world");
     *
     * // Write text at position (5,10) and clear any existing content
     * renderer.writeText(5, 10, "Menu Options", true);
     *
     * // Display the changes
     * renderer.render();
     * ```
     *
     * @since 1.0.0
     */
    writeText(row: number, column: number, text: string, clean?: boolean): void;
    /**
     * Writes multi-line text into the content buffer.
     *
     * @param row - Starting row position (0-based).
     * @param column - Starting column position (0-based).
     * @param text - Text to write, either as a string (may contain newlines) or an array of strings (one per line).
     * @param clean - Whether to clear existing content before writing.
     *                Only applies to the first written line; subsequent lines always append.
     *
     * @remarks
     * Unlike {@link writeText}, this method supports writing multiple lines
     * at once. If the input is a single string, it is split by newline characters.
     * If an array of strings is provided, each element represents a line.
     *
     * This method automatically allocates new rows in the content buffer
     * as needed, making it suitable for rendering large blocks of text
     * that can later be scrolled with the renderer.
     *
     * @example
     * Writing a block of text from a single string:
     * ```ts
     * renderer.writeBlock(0, 0, "Line 1\nLine 2\nLine 3");
     * renderer.render();
     * ```
     *
     * @example
     * Writing a block of text from an array:
     * ```ts
     * renderer.writeBlock(2, 4, ["Indented line 1", "Indented line 2"]);
     * renderer.render();
     * ```
     *
     * @since 1.2.0
     */
    writeBlock(row: number, column: number, text: string | Array<string>, clean?: boolean): void;
    /**
     * Renders the content buffer to the screen using optimized terminal output
     *
     * @param force - Forces all cells to be redrawn, even if they haven't changed
     *
     * @remarks
     * This method performs an optimized render by:
     * - Only rendering the visible portion of the content buffer based on scroll position
     * - Only updating cells that have been marked as dirty (unless force=true)
     * - Clearing trailing content from previous renders
     * - Repositioning the cursor to the bottom right when finished
     *
     * If the content buffer is empty or all content is scrolled out of view,
     * the method will return early without performing any operations.
     *
     * @example
     * ```ts
     * // Normal render - only updates what changed
     * renderer.render();
     *
     * // Force redraw of everything, useful after terminal resize
     * renderer.render(true);
     * ```
     *
     * @since 1.0.0
     */
    render(force?: boolean): void;
    /**
     * Flushes the current content buffer directly to the terminal.
     *
     * @remarks
     * This method writes all rows from {@link contentBuffer} to `stdout`,
     * appending a newline after each row. It also clears each line with
     * {@link ANSI.CLEAR_LINE} before writing, ensuring no stale characters
     * remain on screen.
     *
     * Once flushing is complete, both {@link viewBuffer} and {@link contentBuffer}
     * are reset to empty arrays, preparing the renderer for the next cycle.
     *
     * Unlike {@link render}, this method bypasses diffing and incremental
     * optimizations. It always emits the full buffer to the terminal, which
     * guarantees a complete reset of the visible state but may be less
     * efficient for large outputs.
     *
     * @returns void — This method does not produce a return value.
     *
     * @example
     * ```ts
     * // Write a block of text to the buffer
     * renderer.writeBlock(0, 0, "Hello\nWorld");
     * renderer.clearScreen();
     *
     * // Forcefully flush everything to the terminal
     * renderer.flushToTerminal();
     * ```
     *
     * @since 1.2.0
     */
    flushToTerminal(): void;
    /**
     * Renders a single line of content to the output buffer
     *
     * @param context - The current rendering context
     *
     * @remarks
     * This private method handles the optimization of terminal output by:
     * - Skipping cells that haven't changed since the last render
     * - Only moving the cursor when necessary
     * - Updating the view buffer to reflect what's been rendered
     * - Clearing the dirty flag on cells after they're processed
     *
     * The context object contains all states needed for the rendering process,
     * including the accumulating output string and references to the current
     * content and view lines.
     *
     * @private
     * @since 1.0.0
     */
    private renderLine;
    /**
     * Generates an ANSI escape sequence to move the cursor to a position
     *
     * @param row - The row position relative to renderer's viewport
     * @param column - The column position relative to renderer's viewport (defaults to 0)
     * @returns ANSI escape sequence string for cursor positioning
     *
     * @remarks
     * This private helper method translates relative viewport coordinates to
     * absolute terminal coordinates by adding the renderer's top and left
     * position offsets. The returned value is a string containing the
     * appropriate ANSI escape sequence.
     *
     * @private
     * @since 1.0.0
     */
    private moveCursor;
}

export {
	ShadowRenderer
};