@visulima/ansi/dist/window-ops.d.ts

ANSI escape codes for some terminal swag.

/**
 * Enum for XTerm Window Operations (XTWINOPS).
 * These are parameters for the `CSI Ps ; Ps ; Ps t` sequence.
 * @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h4-Functions-using-CSI-_-ordered-by-the-final-character-lparen-s-rparen:CSI-Ps;Ps;Ps-t.1EB0}
 */
declare enum XTermWindowOp {
  /**
   * De-iconify window.
   */
  DEICONIFY_WINDOW = 1,
  /**
   * Iconify window.
   */
  ICONIFY_WINDOW = 2,
  /**
   * Move window to `[x, y]`.
   */
  MOVE_WINDOW = 3,
  /**
   * Resize the text area to `[height, width]` in characters.
   */
  RESIZE_TEXT_AREA_CHARS = 4,
  /**
   * Raise the window to the front of the stacking order.
   */
  RAISE_WINDOW = 5,
  /**
   * Lower the window to the bottom of the stacking order.
   */
  LOWER_WINDOW = 6,
  /**
   * Refresh the window.
   */
  REFRESH_WINDOW = 7,
  /**
   * Resize the text area to `[height, width]` in pixels.
   */
  RESIZE_TEXT_AREA_PIXELS = 8,
  /**
   * Restore maximized window.
   */
  RESTORE_MAXIMIZED_WINDOW = 9,
  /**
   * Maximize window (i.e., "zoom" or "toggle").
   */
  MAXIMIZE_WINDOW = 10,
  /**
   * Maximize window vertically. Emitted by {@link xtermWindowOp} as `CSI 9 ; 2 t`.
   */
  MAXIMIZE_WINDOW_VERTICALLY = 10.1,
  /**
   * Maximize window horizontally. Emitted by {@link xtermWindowOp} as `CSI 9 ; 3 t`.
   */
  MAXIMIZE_WINDOW_HORIZONTALLY = 10.2,
  /**
   * Undo full-screen mode. Emitted by {@link xtermWindowOp} as `CSI 10 ; 0 t`.
   */
  UNDO_FULL_SCREEN_MODE = 10.3,
  /**
   * Report window state.
   * Response: `CSI code t` where `code` is 1 if de-iconified, 2 if iconified.
   */
  REPORT_WINDOW_STATE = 11,
  /**
   * Report window position.
   * Response: `CSI 3 ; x ; y t`
   */
  REPORT_WINDOW_POSITION = 13,
  /**
   * Report text area size in characters.
   * Response: `CSI 4 ; height ; width t`
   */
  REPORT_TEXT_AREA_SIZE_CHARS = 14,
  /**
   * Report window size in pixels.
   * Alias for `REPORT_TEXT_AREA_SIZE_PIXELS` for compatibility with some terminals (e.g., mintty).
   * Response: `CSI 4 ; height ; width t`
   * Should be REPORT_TEXT_AREA_SIZE_PIXELS (18) for XTerm, but using Go's value.
   */
  REQUEST_WINDOW_SIZE_WIN_OP_COMPAT = 14,
  /**
   * Report cell size in pixels.
   * Response: `CSI 6 ; height ; width t`
   */
  REPORT_CELL_SIZE_PIXELS = 16,
  /**
   * Report text area size in pixels.
   * Response: `CSI 8 ; height ; width t`
   */
  REPORT_TEXT_AREA_SIZE_PIXELS = 18,
  /**
   * Report icon label.
   * Response: `OSC L label ST`
   */
  REPORT_ICON_LABEL = 19,
  /**
   * Report window title.
   * Response: `OSC l label ST`
   */
  REPORT_WINDOW_TITLE = 21,
  /**
   * Push window title on stack.
   */
  PUSH_WINDOW_TITLE = 22,
  /**
   * Pop window title from stack.
   */
  POP_WINDOW_TITLE = 23,
  /**
   * Resize the screen to `[width, height]` in pixels and resize the text area to `[cols, lines]` in characters.
   * (DECSLPP - Set Lines Per Page)
   */
  RESIZE_SCREEN_AND_TEXT_AREA = 24
}
/**
 * Generates an XTerm Window Operation (XTWINOPS) sequence.
 *
 * `CSI Ps ; Ps ; Ps t`
 * @param p The primary parameter, typically one of {@link XTermWindowOp}.
 * @param ps Additional parameters.
 * @returns The ANSI sequence string, or an empty string if `p` is invalid.
 * @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h4-Functions-using-CSI-_-ordered-by-the-final-character-lparen-s-rparen:CSI-Ps;Ps;Ps-t.1EB0}
 */
declare const xtermWindowOp: (p: number, ...ps: number[]) => string;
/**
 * Alias for {@link xtermWindowOp}.
 */
declare const XTWINOPS: (p: number, ...ps: number[]) => string;
/**
 * Resizes the terminal window's text area to a specified height and width in characters.
 * This effectively sets the number of rows and columns for text display.
 *
 * Sequence: `CSI 4 ; height ; width t`
 * @param height The desired height in characters (number of rows).
 * @param width The desired width in characters (number of columns).
 * @returns The ANSI escape sequence to resize the text area.
 * @see xtermWindowOp
 * @see XTermWindowOp.RESIZE_TEXT_AREA_CHARS
 * @example
 * ```typescript
 * import { resizeTextAreaChars } from "@visulima/ansi";
 *
 * // Resize to 24 rows, 80 columns
 * process.stdout.write(resizeTextAreaChars(24, 80));
 * // Sends: "\x1b[4;24;80t"
 * ```
 */
declare const resizeTextAreaChars: (height: number, width: number) => string;
/**
 * Requests a report of the terminal window's text area size in characters (rows and columns).
 * The terminal is expected to respond with a sequence like `CSI 4 ; height ; width t`.
 *
 * This function uses `XTermWindowOp.REQUEST_WINDOW_SIZE_WIN_OP_COMPAT` (14), which corresponds to
 * `XTermWindowOp.REPORT_TEXT_AREA_SIZE_CHARS` in XTerm.
 *
 * Sequence: `CSI 14 t` (which triggers the report `CSI 4 ; height ; width t`).
 * @returns The ANSI escape sequence to request the text area size in characters.
 * @see xtermWindowOp
 * @see XTermWindowOp.REPORT_TEXT_AREA_SIZE_CHARS
 * @see XTermWindowOp.REQUEST_WINDOW_SIZE_WIN_OP_COMPAT
 * @example
 * ```typescript
 * import { requestTextAreaSizeChars } from "@visulima/ansi";
 *
 * process.stdout.write(requestTextAreaSizeChars());
 * // Sends: "\x1b[14t"
 * // Expect response like: "\x1b[4;24;80t" if terminal is 24x80
 * ```
 */
declare const requestTextAreaSizeChars: () => string;
/**
 * Requests a report of the terminal's character cell size in pixels.
 * The terminal is expected to respond with a sequence like `CSI 6 ; height ; width t`,
 * where height and width are the dimensions of a single character cell in pixels.
 *
 * Sequence: `CSI 16 t` (which triggers the report `CSI 6 ; height ; width t`).
 * @returns The ANSI escape sequence to request the cell size in pixels.
 * @see xtermWindowOp
 * @see XTermWindowOp.REPORT_CELL_SIZE_PIXELS
 * @example
 * ```typescript
 * import { requestCellSizePixels } from "@visulima/ansi";
 *
 * process.stdout.write(requestCellSizePixels());
 * // Sends: "\x1b[16t"
 * // Expect response like: "\x1b[6;15;8t" if cell size is 15px height, 8px width
 * ```
 */
declare const requestCellSizePixels: () => string;
/**
 * Requests a report of the terminal window's text area size in pixels.
 * The terminal is expected to respond with a sequence like `CSI 8 ; height ; width t`.
 *
 * Sequence: `CSI 18 t` (which triggers the report `CSI 8 ; height ; width t`).
 * @returns The ANSI escape sequence to request the text area size in pixels.
 * @see xtermWindowOp
 * @see XTermWindowOp.REPORT_TEXT_AREA_SIZE_PIXELS
 * @example
 * ```typescript
 * import { requestTextAreaSizePixels } from "@visulima/ansi";
 *
 * process.stdout.write(requestTextAreaSizePixels());
 * // Sends: "\x1b[18t"
 * // Expect response like: "\x1b[8;600;800t" if text area is 600px height, 800px width
 * ```
 */
declare const requestTextAreaSizePixels: () => string;
/**
 * De-iconifies the terminal window (restores it if minimized).
 *
 * Sequence: `CSI 1 t`
 * @returns The ANSI escape sequence to de-iconify the window.
 * @see xtermWindowOp
 * @see XTermWindowOp.DEICONIFY_WINDOW
 * @example
 * ```typescript
 * import { deiconifyWindow } from "@visulima/ansi";
 *
 * process.stdout.write(deiconifyWindow()); // Sends: "\x1b[1t"
 * ```
 */
declare const deiconifyWindow: () => string;
/**
 * Iconifies the terminal window (minimizes it).
 *
 * Sequence: `CSI 2 t`
 * @returns The ANSI escape sequence to iconify the window.
 * @see xtermWindowOp
 * @see XTermWindowOp.ICONIFY_WINDOW
 * @example
 * ```typescript
 * import { iconifyWindow } from "@visulima/ansi";
 *
 * process.stdout.write(iconifyWindow()); // Sends: "\x1b[2t"
 * ```
 */
declare const iconifyWindow: () => string;
/**
 * Moves the terminal window to the specified screen coordinates (top-left corner).
 *
 * Sequence: `CSI 3 ; x ; y t`
 * - `x`: The X-coordinate (horizontal position in pixels from the left edge).
 * - `y`: The Y-coordinate (vertical position in pixels from the top edge).
 * @param x The target X-coordinate for the window's top-left corner.
 * @param y The target Y-coordinate for the window's top-left corner.
 * @returns The ANSI escape sequence to move the window.
 * @see xtermWindowOp
 * @see XTermWindowOp.MOVE_WINDOW
 * @example
 * ```typescript
 * import { moveWindow } from "@visulima/ansi";
 *
 * // Move window to X=100, Y=50
 * process.stdout.write(moveWindow(100, 50)); // Sends: "\x1b[3;100;50t"
 * ```
 */
declare const moveWindow: (x: number, y: number) => string;
/**
 * Raises the terminal window to the front of the stacking order.
 *
 * Sequence: `CSI 5 t`
 * @returns The ANSI escape sequence to raise the window.
 * @see xtermWindowOp
 * @see XTermWindowOp.RAISE_WINDOW
 * @example
 * ```typescript
 * import { raiseWindow } from "@visulima/ansi";
 *
 * process.stdout.write(raiseWindow()); // Sends: "\x1b[5t"
 * ```
 */
declare const raiseWindow: () => string;
/**
 * Lowers the terminal window to the bottom of the stacking order.
 *
 * Sequence: `CSI 6 t`
 * @returns The ANSI escape sequence to lower the window.
 * @see xtermWindowOp
 * @see XTermWindowOp.LOWER_WINDOW
 * @example
 * ```typescript
 * import { lowerWindow } from "@visulima/ansi";
 *
 * process.stdout.write(lowerWindow()); // Sends: "\x1b[6t"
 * ```
 */
declare const lowerWindow: () => string;
/**
 * Refreshes the terminal window content.
 * This can be useful if the display becomes corrupted or needs redrawing.
 *
 * Sequence: `CSI 7 t`
 * @returns The ANSI escape sequence to refresh the window.
 * @see xtermWindowOp
 * @see XTermWindowOp.REFRESH_WINDOW
 * @example
 * ```typescript
 * import { refreshWindow } from "@visulima/ansi";
 *
 * process.stdout.write(refreshWindow()); // Sends: "\x1b[7t"
 * ```
 */
declare const refreshWindow: () => string;
/**
 * Resizes the terminal window's text area to a specified height and width in pixels.
 *
 * Sequence: `CSI 8 ; height ; width t`
 * @param height The desired height in pixels.
 * @param width The desired width in pixels.
 * @returns The ANSI escape sequence to resize the text area in pixels.
 * @see xtermWindowOp
 * @see XTermWindowOp.RESIZE_TEXT_AREA_PIXELS
 * @example
 * ```typescript
 * import { resizeTextAreaPixels } from "@visulima/ansi";
 *
 * // Resize text area to 600px height, 800px width
 * process.stdout.write(resizeTextAreaPixels(600, 800));
 * // Sends: "\x1b[8;600;800t"
 * ```
 */
declare const resizeTextAreaPixels: (height: number, width: number) => string;
/**
 * Restores a maximized terminal window to its previous size and position.
 * XTerm typically uses `CSI 9 ; 0 t` for this operation, where 0 signifies restore.
 * Some interpretations might use `CSI 9 t` if no other parameter implies restore.
 *
 * Sequence: `CSI 9 t` (simplified, relies on `XTermWindowOp.RESTORE_MAXIMIZED_WINDOW` which is 9)
 * More specific might be `CSI 9 ; 0 t`.
 * @returns The ANSI escape sequence to restore a maximized window.
 * @see xtermWindowOp
 * @see XTermWindowOp.RESTORE_MAXIMIZED_WINDOW
 * @example
 * ```typescript
 * import { restoreMaximizedWindow } from "@visulima/ansi";
 *
 * process.stdout.write(restoreMaximizedWindow()); // Sends: "\x1b[9t"
 * ```
 */
declare const restoreMaximizedWindow: () => string;
/**
 * Maximizes the terminal window (often a "zoom" or toggle effect).
 * XTerm typically uses `CSI 9 ; 1 t` for this, where 1 signifies maximize.
 * Some terminals might use `CSI 10 t` for a general maximize/toggle.
 * This function uses `XTermWindowOp.MAXIMIZE_WINDOW` which is 10.
 *
 * Sequence: `CSI 10 t` (using `XTermWindowOp.MAXIMIZE_WINDOW`).
 * @returns The ANSI escape sequence to maximize the window.
 * @see xtermWindowOp
 * @see XTermWindowOp.MAXIMIZE_WINDOW
 * @example
 * ```typescript
 * import { maximizeWindow } from "@visulima/ansi";
 *
 * process.stdout.write(maximizeWindow()); // Sends: "\x1b[10t"
 * ```
 */
declare const maximizeWindow: () => string;
/**
 * Report window position.
 * Response: `CSI 3 ; x ; y t`
 * `CSI 1 3 t`
 *
 * Requests a report of the terminal window's position on the screen.
 * The terminal responds with `CSI 3 ; x ; y t` where x and y are the window coordinates.
 * @returns The ANSI escape sequence to request window position.
 * @see xtermWindowOp
 * @see XTermWindowOp.REPORT_WINDOW_POSITION
 * @example
 * ```typescript
 * import { reportWindowPosition } from "@visulima/ansi";
 *
 * process.stdout.write(reportWindowPosition());
 * // Sends: "\x1b[13t"
 * // Expect response like: "\x1b[3;100;50t" if window is at position (100, 50)
 * ```
 */
declare const reportWindowPosition: () => string;
/**
 * Report window state.
 * Response: `CSI 1 t` if de-iconified, `CSI 2 t` if iconified.
 * (XTerm doc uses `CSI ? 1 t` and `CSI ? 2 t`, but general form `CSI Ps t` is also listed for 11)
 * `CSI 1 1 t`
 *
 * Requests a report of the terminal window's state (iconified/minimized or de-iconified/normal).
 * The terminal responds with `CSI 1 t` if de-iconified or `CSI 2 t` if iconified.
 * @returns The ANSI escape sequence to request window state.
 * @see xtermWindowOp
 * @see XTermWindowOp.REPORT_WINDOW_STATE
 * @example
 * ```typescript
 * import { reportWindowState } from "@visulima/ansi";
 *
 * process.stdout.write(reportWindowState());
 * // Sends: "\x1b[11t"
 * // Expect response: "\x1b[1t" (de-iconified) or "\x1b[2t" (iconified)
 * ```
 */
declare const reportWindowState: () => string;
/**
 * Set page size (DECSLPP - Set Lines Per Page), often used for resizing the screen.
 * `CSI Pl t` where Pl is the number of lines.
 * XTerm extends this to `CSI > lines ; width ; height t` where width/height are in pixels.
 * `CSI 24 ; lines t`
 * @param lines The number of lines for the page.
 * @returns The ANSI escape sequence to set page size.
 * @see xtermWindowOp
 * @see XTermWindowOp.RESIZE_SCREEN_AND_TEXT_AREA
 * @example
 * ```typescript
 * import { setPageSizeLines } from "@visulima/ansi";
 *
 * // Set page size to 30 lines
 * process.stdout.write(setPageSizeLines(30));
 * // Sends: "\x1b[24;30t"
 * ```
 */
declare const setPageSizeLines: (lines: number) => string;
export { XTWINOPS, XTermWindowOp, deiconifyWindow, iconifyWindow, lowerWindow, maximizeWindow, moveWindow, raiseWindow, refreshWindow, reportWindowPosition, reportWindowState, requestCellSizePixels, requestTextAreaSizeChars, requestTextAreaSizePixels, resizeTextAreaChars, resizeTextAreaPixels, restoreMaximizedWindow, setPageSizeLines, xtermWindowOp };