@peteanderson/ansi 0.0.1 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @peteanderson/ansi
 
-ANSI escape sequence helpers for Node.js terminal output. Automatically disables color when stdout is not a TTY or when standard environment variables (`NO_COLOR`, `NODE_DISABLE_COLORS`, `FORCE_COLOR`, `TERM=dumb`) indicate it should be.
+ANSI escape sequence helpers for Node.js terminal output.
 
 ## Installation
 
@@ -13,52 +13,53 @@ npm install @peteanderson/ansi
 ```js
 const ansi = require("@peteanderson/ansi");
 
-console.log(ansi.fg.red("error: something went wrong"));
-console.log(ansi.bg.blue(ansi.fg.white("highlighted")));
-console.log(ansi.style.bold("important"));
-console.log(ansi.fg.rgb(5, 2, 0)("custom color"));
-console.log("some styled text" + ansi.reset);
-console.log(ansi.stripAnsiSequences("\x1b[31mred\x1b[0m")); // => "red"
+console.log(ansi.fg.red + "error: something went wrong" + ansi.fg.default);
+console.log(ansi.bg.blue + ansi.fg.white + "highlighted" + ansi.fg.default + ansi.bg.default);
+console.log(ansi.erase.screen);
+console.log(ansi.slice(coloredText, 0, 10)); // slice by visible characters
+console.log(ansi.strip(coloredText)); // remove ANSI codes
 ```
 
 ## API
 
-All color and style functions accept a string and return a string. When color is disabled, the functions are identity — they return the input unchanged.
-
 ### `fg` — foreground colors
 
-`black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `gray`
-
-```js
-ansi.fg.red("text")
-ansi.fg.rgb(r, g, b)("text")  // r, g, b in 0–5 for the 6×6×6 cube, or grayscale 232–255
-```
+Raw ANSI open sequences: `black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `default`
 
 ### `bg` — background colors
 
-`black` `red` `green` `yellow` `blue` `magenta` `cyan` `white`
-
-```js
-ansi.bg.green("text")
-ansi.bg.rgb(r, g, b)("text")
-```
+Raw ANSI open sequences: `black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `default`
 
 ### `style`
 
-`bold` `dim` `italic` `underline` `inverse` `hidden` `strikethrough`
+`underline` `reverse` (raw sequences)
 
-```js
-ansi.style.bold("text")
-ansi.style.italic(ansi.style.bold("text"))
-```
+### `caret`
+
+- `show` / `hide` - show or hide the cursor
+- `position.get` - get the current cursor position (terminal sends position to stdin)
+- `position.set(row, col)` - set cursor position (1-based indexing)
+- `shape.block` / `shape.underline` / `shape.bar` - change cursor shape
+
+### `erase`
+
+Raw sequences:
+- `erase.line.toStart` / `erase.line.toEnd` / `erase.line.full`
+- `erase.screen`
+
+### `scroll`
+
+- `scroll.up(lines)` - scroll up (default 1 line)
+- `scroll.down(lines)` - scroll down (default 1 line)
 
-### `reset`
+### `strip(text)`
 
-The SGR reset sequence (`\x1b[0m`). An empty string when color is disabled.
+Removes ANSI CSI sequences from a string.
 
-### `stripAnsiSequences(text)`
+### `slice(text, start, end)`
 
-Removes ANSI SGR escape sequences from a string.
+Slices a string by visible characters, ignoring ANSI sequences. Works like `String.prototype.slice`
+but counts only visible characters.
 
 ## License
 

package/dist/ansi.d.ts

@@ -0,0 +1,66 @@
+export let reset: string;
+export let underline: string;
+export let reverse: string;
+export namespace fg {
+    export let black: string;
+    export let red: string;
+    export let green: string;
+    export let yellow: string;
+    export let blue: string;
+    export let magenta: string;
+    export let cyan: string;
+    export let white: string;
+    let _default: string;
+    export { _default as default };
+    export let rgb: (r: number, g: number, b: number) => string;
+}
+export namespace bg {
+    let black_1: string;
+    export { black_1 as black };
+    let red_1: string;
+    export { red_1 as red };
+    let green_1: string;
+    export { green_1 as green };
+    let yellow_1: string;
+    export { yellow_1 as yellow };
+    let blue_1: string;
+    export { blue_1 as blue };
+    let magenta_1: string;
+    export { magenta_1 as magenta };
+    let cyan_1: string;
+    export { cyan_1 as cyan };
+    let white_1: string;
+    export { white_1 as white };
+    let _default_1: string;
+    export { _default_1 as default };
+    let rgb_1: (r: number, g: number, b: number) => string;
+    export { rgb_1 as rgb };
+}
+export namespace erase {
+    let toLineStart: string;
+    let toLineEnd: string;
+    let line: string;
+    let screen: string;
+}
+export namespace caret {
+    let hide: string;
+    let show: string;
+    namespace position {
+        let get: string;
+        let set: (x: number, y: number) => string;
+    }
+    namespace shape {
+        export let steadyBlock: string;
+        export let steadyBar: string;
+        export let steadyUnderline: string;
+        export let blinkingBlock: string;
+        export let blinkingBar: string;
+        export let blinkingUnderline: string;
+        let _default_2: string;
+        export { _default_2 as default };
+    }
+}
+export let scrollUp: (lines: number) => string;
+export let scrollDown: (lines: number) => string;
+export let strip: (text: string) => string;
+export function slice(text: string, start: number, end: number): string;

package/dist/ansi.js

@@ -0,0 +1,120 @@
+"use strict";
+const rxCSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+/** @type {(r: number, g: number, b: number, code: number) => string} */
+function rgb(r, g, b, code) {
+    if (r === g && g === b) {
+        // Grayscale range.
+        if (r >= 232 && r <= 255)
+            return `\x1b[${code};5;${r}m`;
+    }
+    else if (r >= 0 && r <= 5 && g >= 0 && g <= 5 && b >= 0 && b <= 5) {
+        // 6x6x6 color cube.
+        const code = 16 + r * 36 + g * 6 + b;
+        return `\x1b[${code};5;${code}m`;
+    }
+    return `\x1b[${code};2;${r};${g};${b}m`;
+}
+const ansi = {
+    reset: "\x1b[0m",
+    underline: "\x1b[4m",
+    reverse: "\x1b[7m",
+    fg: {
+        black: "\x1b[30m",
+        red: "\x1b[31m",
+        green: "\x1b[32m",
+        yellow: "\x1b[33m",
+        blue: "\x1b[34m",
+        magenta: "\x1b[35m",
+        cyan: "\x1b[36m",
+        white: "\x1b[37m",
+        default: "\x1b[39m",
+        /** @type {(r: number, g: number, b: number) => string} */
+        rgb: (r, g, b) => rgb(r, g, b, 38),
+    },
+    bg: {
+        black: "\x1b[40m",
+        red: "\x1b[41m",
+        green: "\x1b[42m",
+        yellow: "\x1b[43m",
+        blue: "\x1b[44m",
+        magenta: "\x1b[45m",
+        cyan: "\x1b[46m",
+        white: "\x1b[47m",
+        default: "\x1b[49m",
+        /** @type {(r: number, g: number, b: number) => string} */
+        rgb: (r, g, b) => rgb(r, g, b, 48),
+    },
+    erase: {
+        toLineStart: "\x1b[1K",
+        toLineEnd: "\x1b[0K",
+        line: "\x1b[2K",
+        screen: "\x1b[2J",
+    },
+    caret: {
+        hide: "\x1b[?25l",
+        show: "\x1b[?25h",
+        position: {
+            get: "\x1b[6n",
+            /** @type {(x: number, y: number) => string} */
+            set: (x, y) => `\x1b[${y + 1};${x + 1}H`,
+        },
+        shape: {
+            steadyBlock: "\x1b[2 q",
+            steadyBar: "\x1b[6 q",
+            steadyUnderline: "\x1b[4 q",
+            blinkingBlock: "\x1b[1 q",
+            blinkingBar: "\x1b[5 q",
+            blinkingUnderline: "\x1b[3 q",
+            default: "\x1b[0 q",
+        },
+    },
+    /** @type {(lines: number) => string} */
+    scrollUp: lines => `\x1b[${lines}S`,
+    /** @type {(lines: number) => string} */
+    scrollDown: lines => `\x1b[${lines}T`,
+    /** @type {(text: string) => string} */
+    strip: text => text.replace(rxCSI, ''),
+    /** @type {(text: string, start: number, end: number) => string} */
+    slice(text, start, end) {
+        if (start < 0 || end < 0) {
+            const visibleLength = ansi.strip(text).length;
+            if (start < 0)
+                start = Math.max(0, visibleLength + start);
+            if (end < 0)
+                end = Math.max(0, visibleLength + end);
+        }
+        if (start > end)
+            return "";
+        let visibleIndex = 0;
+        let startIndex = 0;
+        while (startIndex < text.length && visibleIndex < start) {
+            if (text[startIndex] === "\x1b") {
+                rxCSI.lastIndex = startIndex;
+                const match = rxCSI.exec(text);
+                if (match?.index === startIndex) {
+                    startIndex += match[0].length;
+                    continue;
+                }
+            }
+            startIndex++;
+            visibleIndex++;
+        }
+        let endIndex = startIndex;
+        let hasAnsi = false;
+        while (endIndex < text.length && visibleIndex < end) {
+            if (text[endIndex] === "\x1b") {
+                rxCSI.lastIndex = endIndex;
+                const match = rxCSI.exec(text);
+                if (match?.index === endIndex) {
+                    endIndex += match[0].length;
+                    hasAnsi = true;
+                    continue;
+                }
+            }
+            endIndex++;
+            visibleIndex++;
+        }
+        return text.slice(startIndex, endIndex) + (hasAnsi ? ansi.reset : "");
+    },
+};
+module.exports = ansi;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name"            : "@peteanderson/ansi",
-	"version"         : "0.0.1",
+	"version"         : "0.1.1",
 	"description"     : "ANSI escape sequence generation with automatic feature detection",
 	"author"          : {
 		"name"  : "Pete Anderson",
@@ -13,12 +13,12 @@
 	"keywords"        : ["ansi", "nodejs", "color", "terminal", "cli"],
 	"engines"         : {"node": ">=18"},
 	"files"           : ["dist", "src"],
-	"main"            : "dist/color.js",
-	"types"           : "dist/color.d.ts",
+	"main"            : "dist/ansi.js",
+	"types"           : "dist/ansi.d.ts",
 	"exports"         : {
 		".": {
-			"types"   : "./dist/color.d.ts",
-			"require" : "./dist/color.js"
+			"types"   : "./dist/ansi.d.ts",
+			"require" : "./dist/ansi.js"
 		}
 	},
 	"license"         : "MIT",

package/src/ansi.js

@@ -0,0 +1,143 @@
+"use strict";
+
+const rxCSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+
+/** @type {(r: number, g: number, b: number, code: number) => string} */
+function rgb(r, g, b, code) {
+	if (r === g && g === b) {
+		// Grayscale range.
+		if (r >= 232 && r <= 255)
+			return `\x1b[${code};5;${r}m`;
+	} else if (r >= 0 && r <= 5 && g >= 0 && g <= 5 && b >= 0 && b <= 5) {
+		// 6x6x6 color cube.
+		const code = 16 + r * 36 + g * 6 + b;
+		return `\x1b[${code};5;${code}m`;
+	}
+
+	return `\x1b[${code};2;${r};${g};${b}m`;
+}
+
+const ansi = {
+	reset     : "\x1b[0m",
+	underline : "\x1b[4m",
+	reverse   : "\x1b[7m",
+
+	fg: {
+		black   : "\x1b[30m",
+		red     : "\x1b[31m",
+		green   : "\x1b[32m",
+		yellow  : "\x1b[33m",
+		blue    : "\x1b[34m",
+		magenta : "\x1b[35m",
+		cyan    : "\x1b[36m",
+		white   : "\x1b[37m",
+
+		default : "\x1b[39m",
+
+		/** @type {(r: number, g: number, b: number) => string} */
+		rgb: (r, g, b) => rgb(r, g, b, 38),
+	},
+
+	bg: {
+		black   : "\x1b[40m",
+		red     : "\x1b[41m",
+		green   : "\x1b[42m",
+		yellow  : "\x1b[43m",
+		blue    : "\x1b[44m",
+		magenta : "\x1b[45m",
+		cyan    : "\x1b[46m",
+		white   : "\x1b[47m",
+
+		default : "\x1b[49m",
+
+		/** @type {(r: number, g: number, b: number) => string} */
+		rgb: (r, g, b) => rgb(r, g, b, 48),
+	},
+
+	erase: {
+		toLineStart : "\x1b[1K",
+		toLineEnd   : "\x1b[0K",
+		line        : "\x1b[2K",
+		screen      : "\x1b[2J",
+	},
+
+	caret: {
+		hide : "\x1b[?25l",
+		show : "\x1b[?25h",
+
+		position: {
+			get: "\x1b[6n",
+			/** @type {(x: number, y: number) => string} */
+			set: (x, y) => `\x1b[${y + 1};${x + 1}H`,
+		},
+
+		shape: {
+			steadyBlock       : "\x1b[2 q",
+			steadyBar         : "\x1b[6 q",
+			steadyUnderline   : "\x1b[4 q",
+			blinkingBlock     : "\x1b[1 q",
+			blinkingBar       : "\x1b[5 q",
+			blinkingUnderline : "\x1b[3 q",
+			default           : "\x1b[0 q",
+		},
+	},
+
+	/** @type {(lines: number) => string} */
+	scrollUp   : lines => `\x1b[${lines}S`,
+	/** @type {(lines: number) => string} */
+	scrollDown : lines => `\x1b[${lines}T`,
+
+	/** @type {(text: string) => string} */
+	strip: text => text.replace(rxCSI, ''),
+
+	/** @type {(text: string, start: number, end: number) => string} */
+	slice(text, start, end) {
+		if (start < 0 || end < 0) {
+			const visibleLength = ansi.strip(text).length;
+			if (start < 0)
+				start = Math.max(0, visibleLength + start);
+			if (end < 0)
+				end = Math.max(0, visibleLength + end);
+		}
+		if (start > end)
+			return "";
+
+		let visibleIndex = 0;
+		let startIndex   = 0;
+
+		while (startIndex < text.length && visibleIndex < start) {
+			if (text[startIndex] === "\x1b") {
+				rxCSI.lastIndex = startIndex;
+				const match = rxCSI.exec(text);
+				if (match?.index === startIndex) {
+					startIndex += match[0].length;
+					continue;
+				}
+			}
+
+			startIndex++;
+			visibleIndex++;
+		}
+
+		let endIndex = startIndex;
+		let hasAnsi  = false;
+		while (endIndex < text.length && visibleIndex < end) {
+			if (text[endIndex] === "\x1b") {
+				rxCSI.lastIndex = endIndex;
+				const match = rxCSI.exec(text);
+				if (match?.index === endIndex) {
+					endIndex += match[0].length;
+					hasAnsi = true;
+					continue;
+				}
+			}
+
+			endIndex++;
+			visibleIndex++;
+		}
+
+		return text.slice(startIndex, endIndex) + (hasAnsi ? ansi.reset : "");
+	},
+};
+
+module.exports = ansi;

package/dist/color.d.ts

@@ -1,44 +0,0 @@
-/** @param {string} text */
-export function stripAnsiSequences(text: string): string;
-export namespace style {
-    let bold: (text: string) => string;
-    let dim: (text: string) => string;
-    let italic: (text: string) => string;
-    let underline: (text: string) => string;
-    let inverse: (text: string) => string;
-    let hidden: (text: string) => string;
-    let strikethrough: (text: string) => string;
-}
-export namespace fg {
-    let black: (text: string) => string;
-    let red: (text: string) => string;
-    let green: (text: string) => string;
-    let yellow: (text: string) => string;
-    let blue: (text: string) => string;
-    let magenta: (text: string) => string;
-    let cyan: (text: string) => string;
-    let white: (text: string) => string;
-    let gray: (text: string) => string;
-    let rgb: (r: number, g: number, b: number) => (text: string) => string;
-}
-export namespace bg {
-    let black_1: (text: string) => string;
-    export { black_1 as black };
-    let red_1: (text: string) => string;
-    export { red_1 as red };
-    let green_1: (text: string) => string;
-    export { green_1 as green };
-    let yellow_1: (text: string) => string;
-    export { yellow_1 as yellow };
-    let blue_1: (text: string) => string;
-    export { blue_1 as blue };
-    let magenta_1: (text: string) => string;
-    export { magenta_1 as magenta };
-    let cyan_1: (text: string) => string;
-    export { cyan_1 as cyan };
-    let white_1: (text: string) => string;
-    export { white_1 as white };
-    let rgb_1: (r: number, g: number, b: number) => (text: string) => string;
-    export { rgb_1 as rgb };
-}
-export const reset: "\u001B[0m";

package/dist/color.js

@@ -1,85 +0,0 @@
-"use strict";
-/**
- * @param   {string | undefined} value
- * @returns {boolean}
- */
-const isSet = value => !!value && value !== '0' && value.toLowerCase() !== "false";
-const enabled = isSet(process.env.FORCE_COLOR) ||
-    !isSet(process.env.NODE_DISABLE_COLORS) &&
-        !isSet(process.env.NO_COLOR) &&
-        process.env.TERM !== "dumb" &&
-        process.stdout.isTTY;
-/**
- * @param   {number | string} open
- * @param   {number | string} close
- * @returns {(text: string) => string}
- */
-function ansi(open, close) {
-    if (!enabled)
-        return s => s;
-    const openSequence = `\x1b[${open}m`;
-    const closeSequence = `\x1b[${close}m`;
-    return s => openSequence +
-        s.replaceAll(openSequence, '').replaceAll(closeSequence, openSequence) +
-        closeSequence;
-}
-/** @param {string} text */
-const stripAnsiSequences = text => text.replace(/\x1b\[\d+m/g, '');
-/** @type {(r: number, g: number, b: number, open: number, close: number) => (text: string) => string} */
-function rgb(r, g, b, open, close) {
-    if (r === g && g === b) {
-        // Grayscale range.
-        if (r >= 232 && r <= 255)
-            return ansi(`${open};5;${r}`, close);
-    }
-    else if (r >= 0 && r <= 5 && g >= 0 && g <= 5 && b >= 0 && b <= 5) {
-        // 6x6x6 color cube.
-        const code = 16 + r * 36 + g * 6 + b;
-        return ansi(`${open};5;${code}`, close);
-    }
-    return ansi(`${open};2;${r};${g};${b}`, close);
-}
-const style = {
-    bold: ansi(1, 22),
-    dim: ansi(2, 22),
-    italic: ansi(3, 23),
-    underline: ansi(4, 24),
-    inverse: ansi(7, 27),
-    hidden: ansi(8, 28),
-    strikethrough: ansi(9, 29),
-};
-// export type Style = keyof typeof style;
-const fg = {
-    black: ansi(30, 39),
-    red: ansi(31, 39),
-    green: ansi(32, 39),
-    yellow: ansi(33, 39),
-    blue: ansi(34, 39),
-    magenta: ansi(35, 39),
-    cyan: ansi(36, 39),
-    white: ansi(37, 39),
-    gray: ansi(90, 39),
-    /** @type {(r: number, g: number, b: number) => (text: string) => string} */
-    rgb: (r, g, b) => rgb(r, g, b, 38, 39),
-};
-// export type Color = keyof typeof fg;
-const bg = {
-    black: ansi(40, 49),
-    red: ansi(41, 49),
-    green: ansi(42, 49),
-    yellow: ansi(43, 49),
-    blue: ansi(44, 49),
-    magenta: ansi(45, 49),
-    cyan: ansi(46, 49),
-    white: ansi(47, 49),
-    /** @type {(r: number, g: number, b: number) => (text: string) => string} */
-    rgb: (r, g, b) => rgb(r, g, b, 48, 49),
-};
-const reset = "\x1b[0m";
-module.exports = {
-    stripAnsiSequences,
-    style,
-    fg,
-    bg,
-    reset,
-};

package/src/color.js

@@ -1,101 +0,0 @@
-/**
- * @param   {string | undefined} value
- * @returns {boolean}
- */
-const isSet = value => !!value && value !== '0' && value.toLowerCase() !== "false";
-
-const enabled =
-	isSet(process.env.FORCE_COLOR) ||
-		!isSet(process.env.NODE_DISABLE_COLORS) &&
-		!isSet(process.env.NO_COLOR) &&
-		process.env.TERM !== "dumb" &&
-		process.stdout.isTTY;
-
-/**
- * @param   {number | string} open
- * @param   {number | string} close
- * @returns {(text: string) => string}
- */
-function ansi(open, close) {
-	if (!enabled)
-		return s => s;
-
-	const openSequence  = `\x1b[${open}m`;
-	const closeSequence = `\x1b[${close}m`;
-
-	return s =>
-		openSequence +
-		s.replaceAll(openSequence, '').replaceAll(closeSequence, openSequence) +
-		closeSequence;
-}
-
-/** @param {string} text */
-const stripAnsiSequences = text => text.replace(/\x1b\[\d+m/g, '');
-
-/** @type {(r: number, g: number, b: number, open: number, close: number) => (text: string) => string} */
-function rgb(r, g, b, open, close) {
-	if (r === g && g === b) {
-		// Grayscale range.
-		if (r >= 232 && r <= 255)
-			return ansi(`${open};5;${r}`, close);
-	} else if (r >= 0 && r <= 5 && g >= 0 && g <= 5 && b >= 0 && b <= 5) {
-		// 6x6x6 color cube.
-		const code = 16 + r * 36 + g * 6 + b;
-		return ansi(`${open};5;${code}`, close);
-	}
-
-	return ansi(`${open};2;${r};${g};${b}`, close);
-}
-
-const style = {
-	bold          : ansi(1, 22),
-	dim           : ansi(2, 22),
-	italic        : ansi(3, 23),
-	underline     : ansi(4, 24),
-	inverse       : ansi(7, 27),
-	hidden        : ansi(8, 28),
-	strikethrough : ansi(9, 29),
-};
-
-// export type Style = keyof typeof style;
-
-const fg = {
-	black   : ansi(30, 39),
-	red     : ansi(31, 39),
-	green   : ansi(32, 39),
-	yellow  : ansi(33, 39),
-	blue    : ansi(34, 39),
-	magenta : ansi(35, 39),
-	cyan    : ansi(36, 39),
-	white   : ansi(37, 39),
-	gray    : ansi(90, 39),
-
-	/** @type {(r: number, g: number, b: number) => (text: string) => string} */
-	rgb: (r, g, b) => rgb(r, g, b, 38, 39),
-};
-
-// export type Color = keyof typeof fg;
-
-const bg = {
-	black   : ansi(40, 49),
-	red     : ansi(41, 49),
-	green   : ansi(42, 49),
-	yellow  : ansi(43, 49),
-	blue    : ansi(44, 49),
-	magenta : ansi(45, 49),
-	cyan    : ansi(46, 49),
-	white   : ansi(47, 49),
-
-	/** @type {(r: number, g: number, b: number) => (text: string) => string} */
-	rgb: (r, g, b) => rgb(r, g, b, 48, 49),
-};
-
-const reset = "\x1b[0m";
-
-module.exports = {
-	stripAnsiSequences,
-	style,
-	fg,
-	bg,
-	reset,
-};