feat: support counting ANSI escapes

Author: haltcase

README.md

@@ -74,6 +74,7 @@ tablemark (input: InputData, options?: TablemarkOptions): string
   | :----------------------: | :------------------------------------------: | :--------------: | -------------------------------------------------------------------------------------------------- |
   |         `align`          |       `"left" \| "center" \| "right"`        |     `"left"`     | Horizontal alignment to use for all columns.                                                       |
   |        `columns`         |     `Array<string \| ColumnDescriptor>`      |        -         | Array of [column descriptors](#optionscolumns).                                                    |
+  |  `countAnsiEscapeCodes`  |                  `boolean`                   |     `false`      | Whether to count ANSI escape codes when calculating string width.                                  |
   |       `headerCase`       |             `"preserve" \| ...`              | `"sentenceCase"` | Casing to use for headers derived from input object keys ([read more](#optionsheadercase)).        |
   |   `lineBreakStrategy`    |    `"preserve" \| "strip" \| "truncate"`     |   `"preserve"`   | What to do when cell content contains line breaks.                                                 |
   |       `lineEnding`       |                   `string`                   |      `"\n"`      | String used at end-of-line.                                                                        |
@@ -169,6 +170,31 @@ tablemark(
 | Lee        |   23    | true          |
 <!-- prettier-ignore-end -->
 
+### `options.countAnsiEscapeCodes`
+
+Control whether to count ANSI escape codes when calculating string width. The default is `false`, meaning ANSI codes are ignored. Setting this to `true` is useful when the output is not intended for a terminal, such as when generating a markdown table for an example in a README file.
+
+```ts
+const data = [
+	{ text: "\u001B[31mRed\u001B[0m", note: "Normal text" },
+	{ text: "\u001B[32mGreen\u001B[0m", note: "More text" }
+];
+
+tablemark(data, { countAnsiEscapeCodes: false });
+
+// | Text  | Note        |
+// | :---- | :---------- |
+// | Red   | Normal text |
+// | Green | More text   |
+
+tablemark(data, { countAnsiEscapeCodes: true });
+
+// | Text           | Note        |
+// | :------------- | :---------- |
+// | Red   | Normal text |
+// | Green | More text   |
+```
+
 ### `options.headerCase`
 
 Control the casing of headers derived from input object keys. The default is `"sentenceCase"`. The options are:

src/constants.ts

@@ -29,6 +29,8 @@ export const textHandlingStrategies = {
 
 export const columnsMinimumWidth = 3;
 
+// oxlint-disable-next-line no-control-regex
+export const ansiCodeRegex = /\u001B/g;
 export const lineEndingRegex = /\r?\n/g;
 
 export const truncationCharacter = "\u2026";

src/types.ts

@@ -130,14 +130,20 @@ export interface TablemarkOptions<
 	 */
 	columns?: (ColumnDescriptor | string)[];
 
+	/**
+	 * Whether to count ANSI escape codes when calculating string width. The
+	 * default is `false`, meaning ANSI escape codes are treated as zero-width.
+	 */
+	countAnsiEscapeCodes?: boolean;
+
 	/**
 	 * Text casing method for header titles derived from input object keys.
 	 */
 	headerCase?: HeaderCase;
 
 	/**
 	 * What to do when cell content contains line breaks. The default is
-	 * "preserve"
+	 * "preserve".
 	 */
 	lineBreakStrategy?: LineBreakStrategy;
 
@@ -159,7 +165,7 @@ export interface TablemarkOptions<
 
 	/**
 	 * What to do when body cell content reaches `maxWidth`. The default is
-	 * "truncateEnd".
+	 * "wrap".
 	 */
 	overflowStrategy?: OverflowStrategy;
 
@@ -193,12 +199,19 @@ export interface TablemarkOptions<
 	unknownKeyStrategy?: UnknownKeyStrategy;
 
 	/**
-	 * Set to `true` to enable broader support of languages, Unicode entities
-	 * like emoji and [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms)
+	 * The default "auto" strategy detects and provides broader support of
+	 * languages, Unicode entities like emoji and
+	 * [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms)
 	 * characters, and ANSI escape codes (like terminal colors and styles).
 	 *
-	 * By default, tablemark uses "naive" text processing that is much faster,
-	 * but is unaware of these "wider" or invisible characters.
+	 * To force this enhanced support, set this to `"advanced"`.
+	 *
+	 * To force using a faster, more "naive" strategy, set this to `"basic"`.
+	 * However, this can result in misaligned columns and improper ANSI styling.
+	 *
+	 * Note that ANSI escape codes are treated as zero-width regardless of the
+	 * strategy. If you want to change that behavior, use the
+	 * `countAnsiEscapeCodes` option.
 	 */
 	textHandlingStrategy?: TextHandlingStrategy;
 

src/utilities.ts

@@ -6,6 +6,7 @@ import wrapAnsi from "wrap-ansi";
 
 import {
 	alignmentOptions,
+	ansiCodeRegex,
 	lineBreakStrategies,
 	lineEndingRegex,
 	overflowStrategies,
@@ -24,7 +25,10 @@ import type {
 } from "./types.js";
 
 type StringWrapMethod = (string: string, width: number) => string[];
-type StringWidthMethod = (string: string) => number;
+type StringWidthMethod = (
+	string: string,
+	shouldCountAnsiEscapeCodes?: boolean
+) => number;
 
 const pipeRegex = /\|/g;
 export const ansiRegex = getAnsiRegex({ onlyFirst: true });
@@ -126,12 +130,29 @@ export const getStringWrapMethod = (
 	}
 };
 
-export const advancedStringWidth: StringWidthMethod = (string) =>
-	stringWidth(string);
+export const advancedStringWidth: StringWidthMethod = (
+	string,
+	shouldCountAnsiEscapeCodes = false
+) => {
+	const width = stringWidth(string, {
+		countAnsiEscapeCodes: shouldCountAnsiEscapeCodes
+	});
+
+	if (shouldCountAnsiEscapeCodes) {
+		// `stringWidth` doesn't count the ASCII escape character, but we need to if
+		// we want to align column sides accurately
+		return width + (string.match(ansiCodeRegex) ?? []).length;
+	}
 
-export const autoStringWidth: StringWidthMethod = (string) => {
+	return width;
+};
+
+export const autoStringWidth: StringWidthMethod = (
+	string,
+	shouldCountAnsiEscapeCodes
+) => {
 	if (hasSpecialCharacters(string)) {
-		return advancedStringWidth(string);
+		return advancedStringWidth(string, shouldCountAnsiEscapeCodes);
 	}
 
 	return string.length;
@@ -144,13 +165,13 @@ export const autoStringWidth: StringWidthMethod = (string) => {
  * Note that `content` is expected to be a string _not_ containing newlines.
  */
 export const pad = (
-	_config: TablemarkOptionsNormalized,
+	config: TablemarkOptionsNormalized,
 	content: string,
 	_columnIndex: number,
 	alignment: Alignment | undefined,
 	width: number
 ): string => {
-	const contentWidth = autoStringWidth(content);
+	const contentWidth = autoStringWidth(content, config.countAnsiEscapeCodes);
 
 	if (alignment == null || alignment === alignmentOptions.left) {
 		return content + " ".repeat(Math.max(0, width - contentWidth));
@@ -182,6 +203,7 @@ export const toCellText: ToCellText = ({ value }) => {
 const defaultOptions: TablemarkOptionsNormalized = {
 	align: alignmentOptions.left,
 	columns: [],
+	countAnsiEscapeCodes: false,
 	headerCase: "sentenceCase",
 	lineBreakStrategy: lineBreakStrategies.preserve,
 	lineEnding: "\n",
@@ -309,7 +331,10 @@ export const getMaxStringWidth = (
 		const longestLineWidth =
 			lines.reduce<number>(
 				(currentMax, nextString) =>
-					Math.max(currentMax, stringWidth(nextString)),
+					Math.max(
+						currentMax,
+						autoStringWidth(nextString, config.countAnsiEscapeCodes)
+					),
 				0
 			) +
 			(config.lineBreakStrategy === lineBreakStrategies.truncate
@@ -319,7 +344,7 @@ export const getMaxStringWidth = (
 		return longestLineWidth;
 	}
 
-	return stringWidth(text);
+	return autoStringWidth(text, config.countAnsiEscapeCodes);
 };
 
 /**

tests/__snapshots__/countAnsiEscapeCodes-false.md

@@ -0,0 +1,4 @@
+| Text  | Note        |
+| :---- | :---------- |
+| Red   | Normal text |
+| Green | More text   |

tests/__snapshots__/countAnsiEscapeCodes-true.md

@@ -0,0 +1,4 @@
+| Text           | Note        |
+| :------------- | :---------- |
+| Red   | Normal text |
+| Green | More text   |

tests/basic-usage.test.ts

@@ -391,4 +391,30 @@ describe("basic usage", () => {
 			})
 		).toMatchFileSnapshot(snapshotFile("combo-maxWidth-overflow-lineBreak"));
 	});
+
+	test("counts width of ANSI escape codes when `countAnsiEscapeCodes: false`", async () => {
+		const data = [
+			{ text: "\u001B[31mRed\u001B[0m", note: "Normal text" },
+			{ text: "\u001B[32mGreen\u001B[0m", note: "More text" }
+		];
+
+		await expect(
+			tablemark(data, {
+				countAnsiEscapeCodes: false
+			})
+		).toMatchFileSnapshot(snapshotFile("countAnsiEscapeCodes-false"));
+	});
+
+	test("counts width of ANSI escape codes when `countAnsiEscapeCodes: true`", async () => {
+		const data = [
+			{ text: "\u001B[31mRed\u001B[0m", note: "Normal text" },
+			{ text: "\u001B[32mGreen\u001B[0m", note: "More text" }
+		];
+
+		await expect(
+			tablemark(data, {
+				countAnsiEscapeCodes: true
+			})
+		).toMatchFileSnapshot(snapshotFile("countAnsiEscapeCodes-true"));
+	});
 });

tests/utilities.test.ts

@@ -109,6 +109,14 @@ test("pad (center alignment): even content width and given width", () => {
 	).toBe("   hi   ");
 });
 
+test("advancedStringWidth: ignores ANSI escape codes when `countAnsiEscapeCodes: false`", () => {
+	expect(utilites.advancedStringWidth("\u001B[31mRed\u001B[0m", false)).toBe(3);
+});
+
+test("advancedStringWidth: counts ANSI escape codes when `countAnsiEscapeCodes: true`", () => {
+	expect(utilites.advancedStringWidth("\u001B[31mRed\u001B[0m", true)).toBe(12);
+});
+
 test("toCellText: renders its argument as a string suitable for a table cell", () => {
 	expect(utilites.toCellText({ key: "undefined", value: undefined })).toBe("");