@visulima/ansi 4.0.0-alpha.2 → 4.0.0-alpha.4

package/dist/screen.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Inserts a specified number of blank lines at the current cursor position.
+ * (IL - Insert Line)
+ *
+ * Existing lines from the cursor position to the bottom margin are moved downwards.
+ * Lines moved past the bottom margin are lost. The cursor position is unchanged.
+ * If the parameter `count` is 0 or 1, it defaults to inserting one line.
+ *
+ * Sequence: `CSI Pn L`
+ * - `Pn`: Number of lines to insert (default: 1).
+ * @param count The number of blank lines to insert. Defaults to 1.
+ * @returns The ANSI escape sequence for inserting lines.
+ * @see {@link https://vt100.net/docs/vt510-rm/IL.html VT510 IL Documentation}
+ * @example
+ * ```typescript
+ * import { insertLine } from \'@visulima/ansi/screen\';
+ *
+ * // Insert 1 line (default)
+ * process.stdout.write(insertLine()); // CSI L
+ *
+ * // Insert 5 lines
+ * process.stdout.write(insertLine(5)); // CSI 5L
+ * ```
+ */
+export declare const insertLine: (count?: number) => string;
+/**
+ * Deletes a specified number of lines starting from the line with the cursor.
+ * (DL - Delete Line)
+ *
+ * Lines below the deleted ones are moved upwards. Blank lines are added at the bottom
+ * of the scrolling region to fill the gap. The cursor position is unchanged.
+ * If the parameter `count` is 0 or 1, it defaults to deleting one line.
+ *
+ * Sequence: `CSI Pn M`
+ * - `Pn`: Number of lines to delete (default: 1).
+ * @param count The number of lines to delete. Defaults to 1.
+ * @returns The ANSI escape sequence for deleting lines.
+ * @see {@link https://vt100.net/docs/vt510-rm/DL.html VT510 DL Documentation}
+ * @example
+ * ```typescript
+ * import { deleteLine } from \'@visulima/ansi/screen\';
+ *
+ * // Delete 1 line (default)
+ * process.stdout.write(deleteLine()); // CSI M
+ *
+ * // Delete 3 lines
+ * process.stdout.write(deleteLine(3)); // CSI 3M
+ * ```
+ */
+export declare const deleteLine: (count?: number) => string;
+/**
+ * Sets the top and bottom margins, defining the scrolling region.
+ * (DECSTBM - Set Top and Bottom Margins)
+ *
+ * Cursor movement is typically confined to this region, especially when Origin Mode (DECOM) is active.
+ * If parameters are omitted or invalid (e.g., `0`, `null`, `undefined`), they usually default to the
+ * screen's current extents (e.g., line 1 for top, last line for bottom).
+ *
+ * Sequence: `CSI Pt ; Pb r`
+ * - `Pt`: Line number for the top margin (1-indexed). Default: 1.
+ * - `Pb`: Line number for the bottom margin (1-indexed). Default: screen height.
+ * @param top The line number for the top margin (1-indexed). If `null`, `undefined`, or `< 1`, it's omitted, implying default.
+ * @param bottom The line number for the bottom margin (1-indexed). If `null`, `undefined`, or `< 1`, it's omitted, implying default.
+ * @returns The ANSI escape sequence for DECSTBM.
+ * @see {@link https://vt100.net/docs/vt510-rm/DECSTBM.html VT510 DECSTBM Documentation}
+ * @example
+ * ```typescript
+ * import { setTopBottomMargins } from \'@visulima/ansi/screen\';
+ *
+ * // Set scrolling region from line 5 to 20
+ * process.stdout.write(setTopBottomMargins(5, 20)); // CSI 5;20r
+ *
+ * // Reset to default margins (full screen)
+ * process.stdout.write(setTopBottomMargins()); // CSI ;r
+ * ```
+ */
+export declare const setTopBottomMargins: (top?: number | null, bottom?: number | null) => string;
+/**
+ * Sets the left and right margins for the page or screen, defining horizontal boundaries.
+ * (DECSLRM - Set Left and Right Margins)
+ *
+ * This command is common on VT420+ terminals and xterm.
+ * If parameters are omitted or invalid, they usually default to the screen's current extents
+ * (e.g., column 1 for left, last column for right).
+ *
+ * Sequence: `CSI Pl ; Pr s`
+ * - `Pl`: Column number for the left margin (1-indexed). Default: 1.
+ * - `Pr`: Column number for the right margin (1-indexed). Default: screen width.
+ *
+ * Note: The final character 's' should not be confused with save cursor sequences.
+ * @param left The column number for the left margin (1-indexed). If `null`, `undefined`, or `< 1`, it's omitted.
+ * @param right The column number for the right margin (1-indexed). If `null`, `undefined`, or `< 1`, it's omitted.
+ * @returns The ANSI escape sequence for DECSLRM.
+ * @see {@link https://vt100.net/docs/vt510-rm/DECSLRM.html VT510 DECSLRM Documentation}
+ * @example
+ * ```typescript
+ * import { setLeftRightMargins } from \'@visulima/ansi/screen\';
+ *
+ * // Set left margin to 10, right margin to 70
+ * process.stdout.write(setLeftRightMargins(10, 70)); // CSI 10;70s
+ *
+ * // Reset to default margins (full width)
+ * process.stdout.write(setLeftRightMargins());      // CSI ;s
+ * ```
+ */
+export declare const setLeftRightMargins: (left?: number | null, right?: number | null) => string;
+/**
+ * Inserts a specified number of blank characters at the current cursor position.
+ * (ICH - Insert CHaracter)
+ *
+ * Existing characters from the cursor position to the right margin are shifted to the right.
+ * Characters shifted past the right margin are lost. The cursor position is unchanged.
+ * If the parameter `count` is 0 or 1, it defaults to inserting one character.
+ *
+ * Sequence: `CSI Pn @`
+ * - `Pn`: Number of blank characters to insert (default: 1).
+ * @param count The number of blank characters to insert. Defaults to 1.
+ * @returns The ANSI escape sequence for inserting characters.
+ * @see {@link https://vt100.net/docs/vt510-rm/ICH.html VT510 ICH Documentation}
+ * @example
+ * ```typescript
+ * import { insertCharacter } from \'@visulima/ansi/screen\';
+ *
+ * // Insert 1 character (default)
+ * process.stdout.write(insertCharacter()); // CSI @
+ *
+ * // Insert 10 characters
+ * process.stdout.write(insertCharacter(10)); // CSI 10@
+ * ```
+ */
+export declare const insertCharacter: (count?: number) => string;
+/**
+ * Deletes a specified number of characters starting from the current cursor position.
+ * (DCH - Delete CHaracter)
+ *
+ * Remaining characters on the line (to the right of the cursor) are shifted to the left.
+ * Character attributes move with the characters. Blank characters with default attributes
+ * are inserted at the right margin. The cursor position is unchanged.
+ * If the parameter `count` is 0 or 1, it defaults to deleting one character.
+ *
+ * Sequence: `CSI Pn P`
+ * - `Pn`: Number of characters to delete (default: 1).
+ * @param count The number of characters to delete. Defaults to 1.
+ * @returns The ANSI escape sequence for deleting characters.
+ * @see {@link https://vt100.net/docs/vt510-rm/DCH.html VT510 DCH Documentation}
+ * @example
+ * ```typescript
+ * import { deleteCharacter } from \'@visulima/ansi/screen\';
+ *
+ * // Delete 1 character (default)
+ * process.stdout.write(deleteCharacter()); // CSI P
+ *
+ * // Delete 5 characters
+ * process.stdout.write(deleteCharacter(5)); // CSI 5P
+ * ```
+ */
+export declare const deleteCharacter: (count?: number) => string;
+/**
+ * Clears horizontal tab stops.
+ * (TBC - Tabulation Clear)
+ *
+ * Sequence: `CSI Ps g`
+ * - `Ps = 0` (or omitted): Clear horizontal tab stop at the current column (default).
+ * - `Ps = 3`: Clear all horizontal tab stops in the current line (or all lines, terminal-dependent).
+ * @param mode Specifies which tab stops to clear:
+ * - `0`: Clear tab stop at the current cursor column (default).
+ * - `3`: Clear all horizontal tab stops.
+ * @returns The ANSI escape sequence for clearing tab stops.
+ * @see {@link https://vt100.net/docs/vt510-rm/TBC.html VT510 TBC Documentation}
+ * @example
+ * ```typescript
+ * import { clearTabStop } from \'@visulima/ansi/screen\';
+ *
+ * // Clear tab stop at current column
+ * process.stdout.write(clearTabStop(0)); // CSI 0g
+ * process.stdout.write(clearTabStop());  // CSI 0g (default)
+ *
+ * // Clear all tab stops
+ * process.stdout.write(clearTabStop(3)); // CSI 3g
+ * ```
+ */
+export declare const clearTabStop: (mode?: 0 | 3) => string;
+/**
+ * Requests a report of the terminal's presentation state.
+ * (DECRQPSR - Request Presentation State Report)
+ *
+ * The terminal responds with a corresponding report sequence (e.g., DECTPSSR, DECSGRSR, DECCPSR).
+ * This is useful for querying current SGR settings, color palette, etc.
+ *
+ * Sequence: `CSI Ps $ u`
+ * - `Ps = 0`: Report Text Presentation State (DECTPSSR) - font, decoration, etc.
+ * - `Ps = 1`: Report SGR State (DECSGRSR) - current graphic rendition attributes.
+ * - `Ps = 2`: Report Color Palette State (DECCPSR) - color table contents.
+ * @param mode Specifies the type of presentation state report requested:
+ * - `0`: Text Presentation State (DECTPSSR).
+ * - `1`: SGR State (DECSGRSR).
+ * - `2`: Color Palette State (DECCPSR).
+ * @returns The ANSI escape sequence to request the presentation state report.
+ * @see {@link https://vt100.net/docs/vt510-rm/DECRQPSR.html VT510 DECRQPSR Documentation}
+ * @example
+ * ```typescript
+ * import { requestPresentationStateReport } from \'@visulima/ansi/screen\';
+ *
+ * // Request SGR state
+ * process.stdout.write(requestPresentationStateReport(1)); // CSI 1$u
+ * ```
+ */
+export declare const requestPresentationStateReport: (mode: 0 | 1 | 2) => string;
+/**
+ * Repeats the preceding graphic character a specified number of times.
+ * (REP - Repeat Previous Character)
+ *
+ * The character repeated is the last non-control character that was processed by the terminal.
+ * If the parameter `count` is 0 or 1, it defaults to repeating one time (i.e., printing it again).
+ *
+ * Sequence: `CSI Pn b`
+ * - `Pn`: Number of times to repeat the character (default: 1).
+ * @param count The number of times to repeat the preceding graphic character. Defaults to 1.
+ * @returns The ANSI escape sequence for repeating the previous character.
+ * @see {@link https://vt100.net/docs/vt510-rm/REP.html VT510 REP Documentation (though REP is less common or behavior varies)}
+ * @example
+ * ```typescript
+ * import { repeatPreviousCharacter } from \'@visulima/ansi/screen\';
+ *
+ * process.stdout.write("A");
+ * // Repeat 'A' 5 times
+ * process.stdout.write(repeatPreviousCharacter(5)); // Output: AAAAA (total 6 'A's)
+ *
+ * process.stdout.write("B");
+ * // Repeat 'B' 1 time (default)
+ * process.stdout.write(repeatPreviousCharacter()); // Output: BB (total 2 'B's)
+ * ```
+ */
+export declare const repeatPreviousCharacter: (count?: number) => string;

package/dist/screen.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var o=(e,r)=>c(e,"name",{value:r,configurable:!0});import{C as t,S as s}from"./packem_shared/constants-D12jy2Zh.js";var g=Object.defineProperty,a=o((e,r)=>g(e,"name",{value:r,configurable:!0}),"n");const S=a((e=1)=>`${t+(e<=1?"":e)}L`,"insertLine"),u=a((e=1)=>`${t+(e<=1?"":e)}M`,"deleteLine"),h=a((e,r)=>{const n=e&&e>0?e.toString():"",i=r&&r>0?r.toString():"";return n===""&&i===""?`${t+s}r`:`${t+n+s+i}r`},"setTopBottomMargins"),l=a((e,r)=>{const n=e&&e>0?e.toString():"",i=r&&r>0?r.toString():"";return n===""&&i===""?`${t+s}s`:`${t+n+s+i}s`},"setLeftRightMargins"),C=a((e=1)=>`${t+(e<=1?"":e)}@`,"insertCharacter"),L=a((e=1)=>`${t+(e<=1?"":e)}P`,"deleteCharacter"),P=a((e=0)=>`${t+e}g`,"clearTabStop"),b=a(e=>`${t+e}$u`,"requestPresentationStateReport"),d=a((e=1)=>`${t+(e<=1?"":e)}b`,"repeatPreviousCharacter");export{P as clearTabStop,L as deleteCharacter,u as deleteLine,C as insertCharacter,S as insertLine,d as repeatPreviousCharacter,b as requestPresentationStateReport,l as setLeftRightMargins,h as setTopBottomMargins};

package/dist/scroll.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Scrolls the content of the active scrolling region upwards by a specified number of lines.
+ * (SU - Scroll Up)
+ *
+ * New blank lines are added at the bottom of the scrolling region.
+ * If the parameter `count` is 1 or omitted, it defaults to scrolling one line.
+ * The cursor position is not affected by this command.
+ *
+ * Sequence: `CSI Pn S`
+ * - `Pn`: Number of lines to scroll up (default: 1).
+ * @param count The number of lines to scroll up. Defaults to 1. If 0, an empty string is returned as no operation is performed.
+ * @returns The ANSI escape sequence for scrolling up.
+ * @see {@link https://vt100.net/docs/vt510-rm/SU.html VT510 SU Documentation}
+ * @example
+ * ```typescript
+ * import { scrollUp } from \'@visulima/ansi/scroll\';
+ *
+ * // Scroll up 1 line
+ * process.stdout.write(scrollUp());    // CSI S
+ * process.stdout.write(scrollUp(1)); // CSI S
+ *
+ * // Scroll up 5 lines
+ * process.stdout.write(scrollUp(5));  // CSI 5S
+ *
+ * // No operation
+ * process.stdout.write(scrollUp(0));  // ""
+ * ```
+ */
+export declare const scrollUp: (count?: number) => string;
+/**
+ * Scrolls the content of the active scrolling region downwards by a specified number of lines.
+ * (SD - Scroll Down)
+ *
+ * New blank lines are added at the top of the scrolling region.
+ * If the parameter `count` is 1 or omitted, it defaults to scrolling one line.
+ * The cursor position is not affected by this command.
+ *
+ * Sequence: `CSI Pn T`
+ * - `Pn`: Number of lines to scroll down (default: 1).
+ * @param count The number of lines to scroll down. Defaults to 1. If 0, an empty string is returned.
+ * @returns The ANSI escape sequence for scrolling down.
+ * @see {@link https://vt100.net/docs/vt510-rm/SD.html VT510 SD Documentation}
+ * @example
+ * ```typescript
+ * import { scrollDown } from \'@visulima/ansi/scroll\';
+ *
+ * // Scroll down 1 line
+ * process.stdout.write(scrollDown());    // CSI T
+ * process.stdout.write(scrollDown(1)); // CSI T
+ *
+ * // Scroll down 3 lines
+ * process.stdout.write(scrollDown(3));  // CSI 3T
+ * ```
+ */
+export declare const scrollDown: (count?: number) => string;
+/**
+ * ANSI escape sequence to scroll up one line: `CSI S`.
+ * This is equivalent to `scrollUp(1)`.
+ * @see {@link scrollUp}
+ */
+export declare const SCROLL_UP_1: string;
+/**
+ * ANSI escape sequence to scroll down one line: `CSI T`.
+ * This is equivalent to `scrollDown(1)`.
+ * @see {@link scrollDown}
+ */
+export declare const SCROLL_DOWN_1: string;

package/dist/scroll.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var r=(o,e)=>s(o,"name",{value:e,configurable:!0});import{C as l}from"./packem_shared/constants-D12jy2Zh.js";var a=Object.defineProperty,c=r((o,e)=>a(o,"name",{value:e,configurable:!0}),"s");const p=c((o=1)=>o===0?"":`${l+(o<=1?"":o)}S`,"scrollUp"),S=c((o=1)=>o===0?"":`${l+(o<=1?"":o)}T`,"scrollDown"),C=`${l}S`,L=`${l}T`;export{L as SCROLL_DOWN_1,C as SCROLL_UP_1,S as scrollDown,p as scrollUp};