@visulima/ansi 3.0.2 → 3.0.4

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+## @visulima/ansi [3.0.4](https://github.com/visulima/visulima/compare/@visulima/ansi@3.0.3...@visulima/ansi@3.0.4) (2025-11-12)
+
+### Bug Fixes
+
+* **deps:** update type-fest dependency across multiple packages ([93e13be](https://github.com/visulima/visulima/commit/93e13be5248207968a96303710db2a0604d16b9b))
+* update package configurations and TypeScript definitions ([b59aa59](https://github.com/visulima/visulima/commit/b59aa59dac1508216b944f4b917fb4a7ab1f70a4))
+
+### Miscellaneous Chores
+
+* Add jsr file to all packages for release ([#565](https://github.com/visulima/visulima/issues/565)) ([ec91652](https://github.com/visulima/visulima/commit/ec91652b4e4112adf14ba152c1239a7703ba425a))
+* update license files and clean up TypeScript definitions ([fe668cc](https://github.com/visulima/visulima/commit/fe668cc26de23591d4df54a0954455ebbe31b22d))
+
+
+### Dependencies
+
+* **@visulima/colorize:** upgraded to 1.4.28
+* **@visulima/path:** upgraded to 2.0.4
+
+## @visulima/ansi [3.0.3](https://github.com/visulima/visulima/compare/@visulima/ansi@3.0.2...@visulima/ansi@3.0.3) (2025-11-07)
+
+### Bug Fixes
+
+* update TypeScript configurations and improve linting across multiple packages ([6f25ec7](https://github.com/visulima/visulima/commit/6f25ec7841da7246f8f9166efc5292a7089d37ee))
+
+### Miscellaneous Chores
+
+* update npm and pnpm configurations for monorepo optimization ([#564](https://github.com/visulima/visulima/issues/564)) ([5512b42](https://github.com/visulima/visulima/commit/5512b42f672c216b6a3c9e39035199a4ebd9a4b8))
+
+
+### Dependencies
+
+* **@visulima/colorize:** upgraded to 1.4.27
+* **@visulima/path:** upgraded to 2.0.3
+
 ## @visulima/ansi [3.0.2](https://github.com/visulima/visulima/compare/@visulima/ansi@3.0.1...@visulima/ansi@3.0.2) (2025-11-05)
 
 ### Bug Fixes

package/LICENSE.md

@@ -122,11 +122,14 @@ Repository: https://github.com/tapjs/signal-exit.git
 <!-- TYPE_DEPENDENCIES -->
 
 # Licenses of bundled types
+
 The published @visulima/ansi artifact additionally contains code with the following licenses:
 MIT
 
 # Bundled types:
+
 ## restore-cursor
+
 License: MIT
 By: Sindre Sorhus
 Repository: sindresorhus/restore-cursor

package/dist/alternative-screen.d.ts

@@ -1,6 +1,74 @@
-declare const ALT_SCREEN_ON: string;
-declare const ALT_SCREEN_OFF: string;
-declare const alternativeScreenOn: () => string;
-declare const alternativeScreenOff: () => string;
-
-export { ALT_SCREEN_OFF, ALT_SCREEN_ON, alternativeScreenOff, alternativeScreenOn };
+/**
+ * ANSI escape sequence to enable the alternative screen buffer.
+ *
+ * This sequence (`CSI ?1049h`) instructs the terminal to switch to the alternative screen buffer.
+ * This is a common practice for full-screen terminal applications (e.g., vim, less, htop)
+ * to provide a separate screen area for their interface, leaving the original shell content
+ * undisturbed and restoring it upon exit.
+ * When this mode is activated, the original screen content is typically saved by the terminal,
+ * and a blank screen is presented. Operations then occur on this alternative buffer.
+ *
+ * The specific behavior (like whether the screen is cleared on switch) can sometimes vary
+ * slightly between terminal emulators. `?1049h` generally includes saving the cursor position
+ * along with the screen content and clearing the alternative screen.
+ * It is closely related to mode `?47h`, which also switches to an alternative buffer but might
+ * have different semantics regarding screen clearing and cursor saving.
+ * Mode `?1049h` is generally preferred for a more robust alternative screen experience.
+ * @see {@link ALT_SCREEN_OFF} for the sequence to disable the alternative screen buffer.
+ * @see {@link alternativeScreenOn} for a function that returns this sequence.
+ * @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-The-Alternate-Screen-Buffer} Xterm Control Sequences documentation.
+ * @see {@link https://vt100.net/docs/vt510-rm/DECSLPP.html} (related DEC modes, though 1049 is more common for this behavior).
+ */
+export declare const ALT_SCREEN_ON: string;
+/**
+ * ANSI escape sequence to disable the alternative screen buffer.
+ *
+ * This sequence (`CSI ?1049l`) instructs the terminal to switch back from the alternative
+ * screen buffer to the main screen buffer. When this occurs, the terminal typically
+ * restores the screen content and cursor position that were saved when the alternative
+ * buffer was activated by {@link ALT_SCREEN_ON}.
+ *
+ * This is used when a full-screen application exits, allowing the user to return to their
+ * previous shell session seamlessly.
+ * @see {@link ALT_SCREEN_ON} for the sequence to enable the alternative screen buffer.
+ * @see {@link alternativeScreenOff} for a function that returns this sequence.
+ */
+export declare const ALT_SCREEN_OFF: string;
+/**
+ * Returns the ANSI escape sequence to enable the alternative screen buffer.
+ *
+ * This function is a convenience wrapper around the {@link ALT_SCREEN_ON} constant.
+ * It provides a more descriptive way to obtain the sequence for enabling the
+ * alternative screen, often used at the initialization phase of a full-screen
+ * terminal application.
+ * @returns The ANSI escape sequence (`CSI ?1049h`) for enabling the alternative screen buffer.
+ * @example
+ * ```typescript
+ * import { alternativeScreenOn } from '@visulima/ansi/alternative-screen';
+ *
+ * process.stdout.write(alternativeScreenOn());
+ * // Terminal switches to the alternative screen buffer.
+ * ```
+ * @see {@link ALT_SCREEN_ON}
+ * @see {@link alternativeScreenOff}
+ */
+export declare const alternativeScreenOn: () => string;
+/**
+ * Returns the ANSI escape sequence to disable the alternative screen buffer.
+ *
+ * This function is a convenience wrapper around the {@link ALT_SCREEN_OFF} constant.
+ * It provides a more descriptive way to obtain the sequence for disabling the
+ * alternative screen, typically used when a full-screen terminal application is exiting
+ * to restore the user's original terminal state.
+ * @returns The ANSI escape sequence (`CSI ?1049l`) for disabling the alternative screen buffer.
+ * @example
+ * ```typescript
+ * import { alternativeScreenOff } from '@visulima/ansi/alternative-screen';
+ *
+ * process.stdout.write(alternativeScreenOff());
+ * // Terminal switches back to the main screen buffer, restoring previous content.
+ * ```
+ * @see {@link ALT_SCREEN_OFF}
+ * @see {@link alternativeScreenOn}
+ */
+export declare const alternativeScreenOff: () => string;

package/dist/clear.d.ts

@@ -1,6 +1,77 @@
-declare const clearScreenFromTopLeft: string;
-declare const clearLineAndHomeCursor: string;
-declare const clearScreenAndHomeCursor: string;
-declare const resetTerminal: string;
-
-export { clearLineAndHomeCursor, clearScreenAndHomeCursor, clearScreenFromTopLeft, resetTerminal };
+/**
+ * Moves the cursor to the top-left (0,0 in 0-indexed terms) and erases from the cursor to the end of the screen.
+ *
+ * This sequence is a combination of:
+ * 1. {@link cursorTo}(0, 0): Moves the cursor to the first row, first column.
+ * (Equivalent to `CSI 1;1H` as `cursorTo` uses 0-indexed arguments which are converted to 1-indexed for the sequence).
+ * 2. {@link eraseDisplay}({@link EraseDisplayMode.ToEnd}): Erases from the cursor position to the end of the screen (`CSI 0J` or `CSI J`).
+ *
+ * Effective combined sequence: `CSI 1;1H CSI J` (or `CSI 1;1H CSI 0J`).
+ * @see {@link cursorTo}
+ * @see {@link eraseDisplay}
+ * @see {@link EraseDisplayMode.ToEnd}
+ */
+export declare const clearScreenFromTopLeft: string;
+/**
+ * Erases the entire current line and moves the cursor to the beginning of that line (column 1).
+ *
+ * This sequence is a combination of:
+ * 1. {@link eraseInLine}({@link EraseLineMode.EntireLine}): Erases the entire current line (`CSI 2K`).
+ * 2. `CSI G`: Moves the cursor to column 1 of the current line (Cursor Horizontal Absolute).
+ * Alternatively, a carriage return (`\r`) could achieve a similar cursor move to the start of the line on many systems.
+ *
+ * Effective combined sequence: `CSI 2K CSI G`.
+ * @see {@link eraseInLine}
+ * @see {@link EraseLineMode.EntireLine}
+ */
+export declare const clearLineAndHomeCursor: string;
+/**
+ * Homes the cursor to the top-left position (row 1, column 1) and erases the entire screen.
+ *
+ * This sequence is a combination of:
+ * 1. `CSI H`: Moves the cursor to the home position (top-left, equivalent to `CSI 1;1H`).
+ * 2. {@link eraseDisplay}({@link EraseDisplayMode.EntireScreen}): Erases the entire screen (`CSI 2J`).
+ *
+ * Effective combined sequence: `CSI H CSI 2J`.
+ * @remarks This is a very common sequence for clearing the visible terminal window.
+ * @see {@link cursorPosition} (which `CSI H` relates to)
+ * @see {@link eraseDisplay}
+ * @see {@link EraseDisplayMode.EntireScreen}
+ */
+export declare const clearScreenAndHomeCursor: string;
+/**
+ * Clears the entire terminal display, including the scrollback buffer on supported terminals,
+ * and attempts to reset the terminal to its initial (or a more pristine) state.
+ *
+ * This is generally a more comprehensive and forceful clear operation than just erasing the
+ * visible screen content (like {@link clearScreenAndHomeCursor}).
+ *
+ * The exact behavior and sequences used can vary by terminal and operating system:
+ *
+ * - **On Windows:**
+ * It typically uses `CSI 2J` (erase entire screen) followed by `CSI 0f`.
+ * `CSI 0f` (or `CSI ;f`, `CSI 0;0f`) is an SGR sequence that also often acts as a cursor home command,
+ * though its standardization can be less consistent than `CSI H`.
+ * The primary goal is to clear the screen and move the cursor to the top-left.
+ *
+ * - **On other platforms (e.g., Linux, macOS with XTerm-like terminals):**
+ * A more robust combination is used:
+ * 1. {@link eraseDisplay}({@link EraseDisplayMode.EntireScreen}) (`CSI 2J`): Erases the entire visible screen.
+ * 2. {@link eraseDisplay}({@link EraseDisplayMode.EntireScreenAndScrollback}) (`CSI 3J`): Erases the scrollback buffer (XTerm-specific, but widely supported).
+ * 3. `CSI H`: Moves the cursor to the home position (top-left).
+ * 4. `ESC c` (RIS - Reset to Initial State): This is the most powerful reset sequence. It typically resets the terminal
+ * to its power-on state, clearing character sets, SGR attributes, modes, and more.
+ * @returns A string containing the ANSI escape sequence(s) for resetting the terminal.
+ * @example
+ * ```typescript
+ * import { resetTerminal } from '@visulima/ansi/clear';
+ *
+ * process.stdout.write(resetTerminal);
+ * // The terminal attempts a full reset.
+ * ```
+ * @see {@link eraseDisplay}
+ * @see {@link EraseDisplayMode.EntireScreen}
+ * @see {@link EraseDisplayMode.EntireScreenAndScrollback}
+ * @see {@link https://vt100.net/docs/vt510-rm/RIS.html} RIS documentation.
+ */
+export declare const resetTerminal: string;

package/dist/constants.d.ts

@@ -0,0 +1,20 @@
+/** Escape character (\u001B). */
+export declare const ESC: string;
+/** Control Sequence Introducer (ESC [). */
+export declare const CSI: string;
+/** Operating System Command (ESC ]). */
+export declare const OSC: string;
+/** Bell character (\u0007). Often used to terminate OSC sequences. */
+export declare const BEL: string;
+/** Separator used in some ANSI sequences, typically a semicolon. */
+export declare const SEP: string;
+/** Device Control String (ESC P). */
+export declare const DCS: string;
+/** String Terminator (ESC \\). Used to terminate DCS, SOS, PM, APC sequences. */
+export declare const ST: string;
+/** Application Program Command (ESC _). */
+export declare const APC: string;
+/** Start of String (ESC X). */
+export declare const SOS: string;
+/** Privacy Message (ESC ^). */
+export declare const PM: string;