@peteanderson/ansi 0.3.0 → 0.3.2

package/README.md

@@ -101,6 +101,18 @@ Available if feature is enabled:
 - `caret.x(col)` - move cursor to column (1-based)
 - `caret.save` / `caret.restore` - save/restore cursor position (VT100)
 
+### `terminal`
+
+Terminal control features (available if feature is enabled):
+
+- `terminal.focusReporting.enable` / `terminal.focusReporting.disable` - enable/disable focus
+  reporting
+- `terminal.alternateBuffer.on` / `terminal.alternateBuffer.off` - switch to/from alternate buffer
+- `terminal.alternateBuffer.legacy.on` / `terminal.alternateBuffer.legacy.off` - use legacy
+  alternate buffer sequences
+- `terminal.bracketedPasteMode.enable` / `terminal.bracketedPasteMode.disable` - enable/disable
+  bracketed paste mode
+
 ### `erase`
 
 Available if feature is enabled:
@@ -137,6 +149,11 @@ available).
 
 Returns the visible length of a string with all ANSI sequences removed (always available).
 
+### `padStart(text, targetLength)` and `padEnd(text, targetLength)`
+
+Pads a string to a target visible length using spaces. Accounts for ANSI sequences when calculating
+length.
+
 ### `features`
 
 Object containing the detected feature configuration:
@@ -148,6 +165,7 @@ Object containing the detected feature configuration:
     caret      : boolean;
     erase      : boolean;
     scroll     : boolean;
+    terminal   : boolean;
 }
 ```
 

package/dist/ansi.d.ts

@@ -8,6 +8,9 @@ declare const ansi: typeof makeAnsi & {
     scroll: ReturnType<typeof makeScroll>;
     reset: string;
     style: ReturnType<typeof makeStyle>;
+    terminal: ReturnType<typeof makeTerminal>;
+    padEnd: typeof padEnd;
+    padStart: typeof padStart;
     strip: typeof strip;
     visibleLength: typeof visibleLength;
     sanitize: typeof sanitize;
@@ -23,6 +26,9 @@ import { makeCaret } from "./caret";
 import { makeErase } from "./erase";
 import { makeScroll } from "./scroll";
 import { makeStyle } from "./sgr/style";
+import { makeTerminal } from "./terminal";
+import { padEnd } from "./pad";
+import { padStart } from "./pad";
 import { strip } from "./strip";
 import { visibleLength } from "./strip";
 import { sanitize } from "./strip";
@@ -36,6 +42,9 @@ type Ansi = ReturnType<typeof makeColor> & {
     scroll: ReturnType<typeof makeScroll>;
     reset: string;
     style: ReturnType<typeof makeStyle>;
+    terminal: ReturnType<typeof makeTerminal>;
+    padEnd: typeof padEnd;
+    padStart: typeof padStart;
     strip: typeof strip;
     visibleLength: typeof visibleLength;
     sanitize: typeof sanitize;

package/dist/ansi.js

@@ -2,11 +2,13 @@
 const { makeCaret } = require("./caret");
 const { makeErase } = require("./erase");
 const { getFeatures } = require("./features");
+const { padEnd, padStart } = require("./pad");
 const { makeScroll } = require("./scroll");
 const { makeColor, makeReset, makeStyle } = require("./sgr");
 const { simplify } = require("./simplify");
 const { slice } = require("./slice");
 const { sanitize, strip, visibleLength } = require("./strip");
+const { makeTerminal } = require("./terminal");
 /**
 @typedef {import("./features/features").Args} Args
 
@@ -18,6 +20,11 @@ const { sanitize, strip, visibleLength } = require("./strip");
     reset : string;
     style : ReturnType<typeof makeStyle>;
 
+    terminal : ReturnType<typeof makeTerminal>;
+
+    padEnd   : typeof padEnd;
+    padStart : typeof padStart;
+
     strip         : typeof strip;
     visibleLength : typeof visibleLength;
     sanitize      : typeof sanitize;
@@ -37,6 +44,9 @@ function makeAnsi(...args) {
         reset: makeReset(features.colorDepth > 1),
         style: makeStyle(features.style),
         ...makeColor(features.colorDepth),
+        terminal: makeTerminal(features.terminal),
+        padEnd,
+        padStart,
         strip,
         visibleLength,
         sanitize,

package/dist/features/build.d.ts

@@ -1,6 +1,6 @@
 export type ColorDepth = import("./types").ColorDepth;
 export type Features = import("./types").Features;
-export function build(isTTY: boolean, colorDepth: ColorDepth, style?: boolean, caret?: boolean, erase?: boolean, scroll?: boolean): Features;
+export function build(isTTY: boolean, colorDepth: ColorDepth, style?: boolean, caret?: boolean, erase?: boolean, scroll?: boolean, terminal?: boolean): Features;
 /** @type {(isTTY: boolean, enabled: boolean) => Features} */
 export const boolean: (isTTY: boolean, enabled: boolean) => Features;
 /** @type {(isTTY: boolean, colorDepth: ColorDepth) => Features} */

package/dist/features/build.js

@@ -24,12 +24,17 @@ function normalizeColorDepth(colorDepth) {
         caret?     : boolean,
         erase?     : boolean,
         scroll?    : boolean,
+        terminal?  : boolean,
     ) => Features
 }
 */
-function build(isTTY, colorDepth, style, caret, erase, scroll) {
-    if (style !== undefined && caret !== undefined && erase !== undefined && scroll !== undefined)
-        return { colorDepth: normalizeColorDepth(colorDepth), style, caret, erase, scroll };
+function build(isTTY, colorDepth, style, caret, erase, scroll, terminal) {
+    if (style !== undefined &&
+        caret !== undefined &&
+        erase !== undefined &&
+        scroll !== undefined &&
+        terminal !== undefined)
+        return { colorDepth: normalizeColorDepth(colorDepth), style, caret, erase, scroll, terminal };
     const support = detectFeatureSupport(isTTY, colorDepth);
     return {
         colorDepth: normalizeColorDepth(colorDepth),
@@ -37,6 +42,7 @@ function build(isTTY, colorDepth, style, caret, erase, scroll) {
         caret: caret ?? support.caret,
         erase: erase ?? support.erase,
         scroll: scroll ?? support.scroll,
+        terminal: terminal ?? support.terminal,
     };
 }
 /** @type {(isTTY: boolean, enabled: boolean) => Features} */

package/dist/features/detect.js

@@ -28,6 +28,7 @@ function detectFeatureSupport(isTTY, colorDepth) {
         caret: enabled,
         erase: enabled,
         scroll: enabled,
+        terminal: enabled,
     };
 }
 module.exports = { detectFeatureSupport, getColorDepth };

package/dist/features/features.js

@@ -28,12 +28,12 @@ function getFeatures(...args) {
         return tty(features);
     if (features instanceof Socket)
         return pipe();
-    const { colorDepth, style, caret, erase, scroll } = features;
+    const { colorDepth, style, caret, erase, scroll, terminal } = features;
     stream ??= process.stdout;
     if (colorDepth)
-        build(stream.isTTY, colorDepth, style, caret, erase, scroll);
+        build(stream.isTTY, colorDepth, style, caret, erase, scroll, terminal);
     if (stream.isTTY)
-        return build(true, getColorDepth(stream), style, caret, erase, scroll);
-    return build(false, getColorDepth(), style, caret, erase, scroll);
+        return build(true, getColorDepth(stream), style, caret, erase, scroll, terminal);
+    return build(false, getColorDepth(), style, caret, erase, scroll, terminal);
 }
 module.exports = { getFeatures };

package/dist/index.d.ts

@@ -47,6 +47,30 @@ declare const _exports: ((...args: Args) => Ansi) & {
     }>;
     reset: string;
     style: ReturnType<typeof import("./sgr/style").makeStyle>;
+    terminal: ReturnType<(enabled?: boolean) => {
+        focusReporting: {
+            enable: string;
+            disable: string;
+            focus: string;
+            blur: string;
+        };
+        alternateScreen: {
+            enable: string;
+            disable: string;
+            legacy: {
+                enable: string;
+                disable: string;
+            };
+        };
+        bracketedPaste: {
+            enable: string;
+            disable: string;
+            start: string;
+            end: string;
+        };
+    }>;
+    padEnd: (text: string, targetLength: number, fillString?: string) => string;
+    padStart: (text: string, targetLength: number, fillString?: string) => string;
     strip: (text: string) => string;
     visibleLength: (text: string) => number;
     sanitize: (text: string) => string;

package/dist/pad.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pad the given text at the end with the specified fill string to the target visible length without
+ * counting ANSI escape codes.
+ * @type {(text: string, targetLength: number, fillString?: string) => string}
+ */
+export const padEnd: (text: string, targetLength: number, fillString?: string) => string;
+/**
+ * Pad the given text at the start with the specified fill string to the target visible length
+ * without counting ANSI escape codes.
+ * @type {(text: string, targetLength: number, fillString?: string) => string}
+ */
+export const padStart: (text: string, targetLength: number, fillString?: string) => string;

package/dist/pad.js

@@ -0,0 +1,15 @@
+"use strict";
+const { visibleLength } = require("./strip");
+/**
+ * Pad the given text at the end with the specified fill string to the target visible length without
+ * counting ANSI escape codes.
+ * @type {(text: string, targetLength: number, fillString?: string) => string}
+ */
+const padEnd = (text, targetLength, fillString = " ") => text + fillString.repeat(Math.max(0, targetLength - visibleLength(text)) / fillString.length);
+/**
+ * Pad the given text at the start with the specified fill string to the target visible length
+ * without counting ANSI escape codes.
+ * @type {(text: string, targetLength: number, fillString?: string) => string}
+ */
+const padStart = (text, targetLength, fillString = " ") => fillString.repeat(Math.max(0, targetLength - visibleLength(text)) / fillString.length) + text;
+module.exports = { padEnd, padStart };

package/dist/terminal.d.ts

@@ -0,0 +1,22 @@
+export function makeTerminal(enabled?: boolean): {
+    focusReporting: {
+        enable: string;
+        disable: string;
+        focus: string;
+        blur: string;
+    };
+    alternateScreen: {
+        enable: string;
+        disable: string;
+        legacy: {
+            enable: string;
+            disable: string;
+        };
+    };
+    bracketedPaste: {
+        enable: string;
+        disable: string;
+        start: string;
+        end: string;
+    };
+};

package/dist/terminal.js

@@ -0,0 +1,48 @@
+"use strict";
+const terminal = {
+    focusReporting: {
+        enable: "\x1b[?1004h",
+        disable: "\x1b[?1004l",
+        focus: "\x1b[I",
+        blur: "\x1b[O",
+    },
+    alternateScreen: {
+        enable: "\x1b[?1049h",
+        disable: "\x1b[?1049l",
+        legacy: {
+            enable: "\x1b[?47h",
+            disable: "\x1b[?47l",
+        },
+    },
+    bracketedPaste: {
+        enable: "\x1b[?2004h",
+        disable: "\x1b[?2004l",
+        start: "\x1b[200~",
+        end: "\x1b[201~",
+    },
+};
+/** @type {typeof terminal} */
+const disabled = {
+    focusReporting: {
+        enable: "",
+        disable: "",
+        focus: "",
+        blur: "",
+    },
+    alternateScreen: {
+        enable: "",
+        disable: "",
+        legacy: {
+            enable: "",
+            disable: "",
+        },
+    },
+    bracketedPaste: {
+        enable: "",
+        disable: "",
+        start: "",
+        end: "",
+    },
+};
+const makeTerminal = (enabled = true) => enabled ? terminal : disabled;
+module.exports = { makeTerminal };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name"            : "@peteanderson/ansi",
-	"version"         : "0.3.0",
+	"version"         : "0.3.2",
 	"description"     : "ANSI escape sequence generation with automatic feature detection",
 	"author"          : {
 		"name"  : "Pete Anderson",

package/src/ansi.js

@@ -3,11 +3,13 @@
 const {makeCaret}                       = require("./caret");
 const {makeErase}                       = require("./erase");
 const {getFeatures}                     = require("./features");
+const {padEnd, padStart}                = require("./pad");
 const {makeScroll}                      = require("./scroll");
 const {makeColor, makeReset, makeStyle} = require("./sgr");
 const {simplify}                        = require("./simplify");
 const {slice}                           = require("./slice");
 const {sanitize, strip, visibleLength}  = require("./strip");
+const {makeTerminal}                    = require("./terminal");
 
 /**
 @typedef {import("./features/features").Args} Args
@@ -20,6 +22,11 @@ const {sanitize, strip, visibleLength}  = require("./strip");
 	reset : string;
 	style : ReturnType<typeof makeStyle>;
 
+	terminal : ReturnType<typeof makeTerminal>;
+
+	padEnd   : typeof padEnd;
+	padStart : typeof padStart;
+
 	strip         : typeof strip;
 	visibleLength : typeof visibleLength;
 	sanitize      : typeof sanitize;
@@ -43,6 +50,11 @@ function makeAnsi(...args) {
 		style : makeStyle(features.style),
 		...makeColor(features.colorDepth),
 
+		terminal: makeTerminal(features.terminal),
+
+		padEnd,
+		padStart,
+
 		strip,
 		visibleLength,
 		sanitize,

package/src/features/build.js

@@ -28,20 +28,28 @@ function normalizeColorDepth(colorDepth) {
 		caret?     : boolean,
 		erase?     : boolean,
 		scroll?    : boolean,
+		terminal?  : boolean,
 	) => Features
 }
 */
-function build(isTTY, colorDepth, style, caret, erase, scroll) {
-	if (style !== undefined && caret !== undefined && erase !== undefined && scroll !== undefined)
-		return {colorDepth: normalizeColorDepth(colorDepth), style, caret, erase, scroll};
+function build(isTTY, colorDepth, style, caret, erase, scroll, terminal) {
+	if (
+		style    !== undefined &&
+		caret    !== undefined &&
+		erase    !== undefined &&
+		scroll   !== undefined &&
+		terminal !== undefined
+	)
+		return {colorDepth: normalizeColorDepth(colorDepth), style, caret, erase, scroll, terminal};
 
 	const support = detectFeatureSupport(isTTY, colorDepth);
 	return {
 		colorDepth : normalizeColorDepth(colorDepth),
-		style      : style  ?? support.style,
-		caret      : caret  ?? support.caret,
-		erase      : erase  ?? support.erase,
-		scroll     : scroll ?? support.scroll,
+		style      : style    ?? support.style,
+		caret      : caret    ?? support.caret,
+		erase      : erase    ?? support.erase,
+		scroll     : scroll   ?? support.scroll,
+		terminal   : terminal ?? support.terminal,
 	};
 }
 

package/src/features/detect.js

@@ -29,10 +29,11 @@ function getColorDepth(stream) {
 function detectFeatureSupport(isTTY, colorDepth) {
 	const enabled = process.env.TERM !== "dumb" && isTTY;
 	return {
-		style  : colorDepth > 1,
-		caret  : enabled,
-		erase  : enabled,
-		scroll : enabled,
+		style    : colorDepth > 1,
+		caret    : enabled,
+		erase    : enabled,
+		scroll   : enabled,
+		terminal : enabled,
 	};
 }
 

package/src/features/features.js

@@ -37,17 +37,17 @@ function getFeatures(...args) {
 	if (features instanceof Socket)
 		return pipe();
 
-	const {colorDepth, style, caret, erase, scroll} = features;
+	const {colorDepth, style, caret, erase, scroll, terminal} = features;
 
 	stream ??= process.stdout;
 
 	if (colorDepth)
-		build(stream.isTTY, colorDepth, style, caret, erase, scroll);
+		build(stream.isTTY, colorDepth, style, caret, erase, scroll, terminal);
 
 	if (stream.isTTY)
-		return build(true, getColorDepth(stream), style, caret, erase, scroll);
+		return build(true, getColorDepth(stream), style, caret, erase, scroll, terminal);
 
-	return build(false, getColorDepth(), style, caret, erase, scroll);
+	return build(false, getColorDepth(), style, caret, erase, scroll, terminal);
 }
 
 module.exports = {getFeatures};

package/src/features/types.d.ts

@@ -6,4 +6,5 @@ export interface Features {
 	caret      : boolean;
 	erase      : boolean;
 	scroll     : boolean;
+	terminal   : boolean;
 }

package/src/pad.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const {visibleLength} = require("./strip");
+
+/**
+ * Pad the given text at the end with the specified fill string to the target visible length without
+ * counting ANSI escape codes.
+ * @type {(text: string, targetLength: number, fillString?: string) => string}
+ */
+const padEnd = (text, targetLength, fillString = " ") =>
+	text + fillString.repeat(Math.max(0, targetLength - visibleLength(text)) / fillString.length);
+
+/**
+ * Pad the given text at the start with the specified fill string to the target visible length
+ * without counting ANSI escape codes.
+ * @type {(text: string, targetLength: number, fillString?: string) => string}
+ */
+const padStart = (text, targetLength, fillString = " ") =>
+	fillString.repeat(Math.max(0, targetLength - visibleLength(text)) / fillString.length) + text;
+
+module.exports = {padEnd, padStart};

package/src/terminal.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const terminal = {
+	focusReporting: {
+		enable  : "\x1b[?1004h",
+		disable : "\x1b[?1004l",
+		focus   : "\x1b[I",
+		blur    : "\x1b[O",
+	},
+
+	alternateScreen: {
+		enable  : "\x1b[?1049h",
+		disable : "\x1b[?1049l",
+
+		legacy: {
+			enable  : "\x1b[?47h",
+			disable : "\x1b[?47l",
+		},
+	},
+
+	bracketedPaste: {
+		enable  : "\x1b[?2004h",
+		disable : "\x1b[?2004l",
+		start   : "\x1b[200~",
+		end     : "\x1b[201~",
+	},
+};
+
+/** @type {typeof terminal} */
+const disabled = {
+	focusReporting: {
+		enable  : "",
+		disable : "",
+		focus   : "",
+		blur    : "",
+	},
+
+	alternateScreen: {
+		enable  : "",
+		disable : "",
+
+		legacy: {
+			enable  : "",
+			disable : "",
+		},
+	},
+
+	bracketedPaste: {
+		enable  : "",
+		disable : "",
+		start   : "",
+		end     : "",
+	},
+};
+
+const makeTerminal = (enabled = true) => enabled ? terminal : disabled;
+
+module.exports = {makeTerminal};