@remotex-labs/xansi/dist/ansi.component.d.ts

A lightweight ANSI utility library for styling terminal output

/**
 * Writes raw data directly to the standard output stream without any processing
 *
 * @param data - The string or Buffer to write to stdout
 *
 * @returns Nothing
 *
 * @example
 * ```ts
 * // Write an ANSI escape sequence followed by text
 * writeRaw('\x1b[31mThis text is red\x1b[0m');
 * ```
 *
 * @since 1.0.0
 */
export declare function writeRaw(data: string | Buffer): void;
/**
 * Generates an ANSI escape sequence to move the terminal cursor to the specified position
 *
 * @param row - The row (line) number to move the cursor to (1-based index)
 * @param column - The column position to move the cursor to (1-based index)
 *
 * @returns ANSI escape sequence string that moves the cursor when written to the terminal
 *
 * @example
 * ```ts
 * // Move cursor to the beginning of line 5
 * const escapeSequence = moveCursor(5, 1);
 * process.stdout.write(escapeSequence);
 * ```
 *
 * @since 1.0.0
 */
export declare function moveCursor(row: number, column?: number): string;
/**
 * Removes ANSI escape sequences from a string
 *
 * @param str - The input string containing ANSI escape sequences
 * @returns A plain string with all ANSI escape sequences removed
 *
 * @remarks
 * This function uses a regular expression to match and remove ANSI escape sequences
 * that control text styling in terminal output. These sequences typically start with
 * the escape character (x1b) followed by square brackets and control codes.
 *
 * The function is useful for:
 * - Getting accurate string length measurements without styling codes
 * - Preparing terminal output for non-terminal destinations (files, logs)
 * - Normalizing text for comparison or processing
 *
 * @example
 * ```ts
 * import { xterm, stripAnsi } from '@remotex-labs/xansi';
 *
 * const coloredText = xterm.red('Error!');
 * console.log(stripAnsi(coloredText)); // "Error!" (without ANSI codes)
 * ```
 *
 * @since 1.0.0
 */
export declare function stripAnsi(str: string): string;
/**
 * Contains ANSI escape sequence constants for terminal control operations
 *
 * @remarks
 * These ANSI escape codes are used to control terminal output behavior such as
 * cursor movement, screen clearing, and visibility. The enum provides a type-safe
 * way to access these constants without having to remember the raw escape sequences.
 *
 * Each constant is an escape sequence that can be written directly to the terminal
 * to achieve the described effect.
 *
 * @see ShadowRenderer
 * @see https://en.wikipedia.org/wiki/ANSI_escape_code
 *
 * @since 1.0.0
 */
export declare const ANSI: {
    /**
     * Clears from the cursor to the end of the line
     *
     * @see https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_sequences
     * @since 1.0.0
     */
    readonly CLEAR_LINE: "\u001B[K";
    /**
     * Hides the cursor
     *
     * @see https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_sequences
     * @since 1.0.0
     */
    readonly HIDE_CURSOR: "\u001B[?25l";
    /**
     * Shows the cursor
     *
     * @see https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_sequences
     * @since 1.0.0
     */
    readonly SHOW_CURSOR: "\u001B[?25h";
    /**
     * Saves the current cursor position
     *
     * @see https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_sequences
     * @since 1.0.0
     */
    readonly SAVE_CURSOR: "\u001B[s";
    /**
     * Clears the entire screen and moves the cursor to home position (top-left)
     *
     * @see https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_sequences
     * @since 1.0.0
     */
    readonly CLEAR_SCREEN: "\u001B[2J\u001B[H";
    /**
     * Restores the cursor to the previously saved position
     *
     * @see https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_sequences
     * @since 1.0.0
     */
    readonly RESTORE_CURSOR: "\u001B[u";
    /**
     * Clears the screen from the cursor position down
     *
     * @see https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_sequences
     * @since 1.0.0
     */
    readonly CLEAR_SCREEN_DOWN: "\u001B[J";
    /**
     * Resets the terminal to its initial state (RIS - Reset to Initial State).
     * Clears screen, scrollback buffer, and most settings.
     * This is a "hard reset" escape code.
     *
     * @see https://en.wikipedia.org/wiki/ANSI_escape_code#Reset_(RIS)
     * @since 1.0.0
     */
    readonly RESET_TERMINAL: "\u001Bc";
};