refactor(internal): [takeVisible] add ansi support

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

Author: unicornware

__tests__/utils/hrc.mts

@@ -0,0 +1,52 @@
+/**
+ * @file Test Utilities - hrc
+ * @module tests/utils/hrc
+ */
+
+import type { ToString } from '@flex-development/string-wrap'
+
+/**
+ * Make control characters in `value` human-readable.
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The string containing control characters.
+ *  Non-string values will be converted to strings (i.e. `toString(value)`)
+ * @param {ToString | null | undefined} [toString]
+ *  Convert `value` to a string
+ * @return {string}
+ *  The `value` with human-readable control characters
+ */
+function hrc(
+  this: void,
+  value: unknown,
+  toString?: ToString | null | undefined
+): string {
+  toString ??= String
+
+  /**
+   * Regular expression matching control characters.
+   *
+   * @const {RegExp} re
+   */
+  const re: RegExp = /[\u0000-\u001F\u007F-\u009F]/g
+
+  return toString(value).replace(re, hr)
+
+  /**
+   * Convert a control `character` to a human-readable string.
+   *
+   * @this {void}
+   *
+   * @param {string} character
+   *  The control character
+   * @return {string}
+   *  The control `character` as a human-readable string
+   */
+  function hr(this: void, character: string): string {
+    return `\\u${character.codePointAt(0)!.toString(16).padStart(4, '0')}`
+  }
+}
+
+export default hrc

package.json

@@ -116,6 +116,7 @@
     "typecheck:ui": "yarn test:ui --typecheck --mode=typecheck"
   },
   "dependencies": {
+    "@flex-development/ansi-regex": "1.0.0",
     "@flex-development/fsm-tokenizer": "1.0.0-alpha.1",
     "devlop": "1.1.0",
     "grapheme-splitter": "1.0.4",
@@ -127,6 +128,7 @@
     "@commitlint/cli": "20.1.0",
     "@commitlint/types": "20.0.0",
     "@faker-js/faker": "10.1.0",
+    "@flex-development/colors": "2.0.0",
     "@flex-development/commitlint-config": "1.0.1",
     "@flex-development/eslint-config": "1.1.1",
     "@flex-development/grease": "3.0.0-alpha.9",

src/internal/__snapshots__/happy-dom/take-visible.snap

@@ -1,5 +1,13 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["\\u001b[1m🦄🦾🚀\\u001b[22m", "1"]) 1`] = `"\\u001b[1m🦄"`;
+
+exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["\\u001b[4m0123456789\\u001b[24m", 3]) 1`] = `"\\u001b[4m012"`;
+
+exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["\\u001b[32mdog\\u001b[39m", "1"]) 1`] = `"\\u001b[32md"`;
+
+exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["\\u001b[32mhello\\u001b[39mworld", "5"]) 1`] = `"\\u001b[32mhello\\u001b[39m"`;
+
 exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["0123456789", "3"]) 1`] = `"012"`;
 
 exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["🦄🦾🚀", 1]) 1`] = `"🦄"`;

src/internal/__snapshots__/node/take-visible.snap

@@ -1,5 +1,13 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["\\u001b[1m🦄🦾🚀\\u001b[22m", "1"]) 1`] = `"\\u001b[1m🦄"`;
+
+exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["\\u001b[4m0123456789\\u001b[24m", 3]) 1`] = `"\\u001b[4m012"`;
+
+exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["\\u001b[32mdog\\u001b[39m", "1"]) 1`] = `"\\u001b[32md"`;
+
+exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["\\u001b[32mhello\\u001b[39mworld", "5"]) 1`] = `"\\u001b[32mhello\\u001b[39m"`;
+
 exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["0123456789", "3"]) 1`] = `"012"`;
 
 exports[`unit:internal/takeVisible > should return longest substring that fits into \`columns\` (["🦄🦾🚀", 1]) 1`] = `"🦄"`;

src/internal/__tests__/take-visible.spec.mts

@@ -3,10 +3,12 @@
  * @module string-wrap/internal/tests/unit/takeVisible
  */
 
-import digits from '#fixtures/digits'
-import emojis from '#fixtures/emoji-sequence'
+import digitSequence from '#fixtures/digit-sequence'
+import emojiSequence from '#fixtures/emoji-sequence'
 import testSubject from '#internal/take-visible'
+import hrc from '#tests/utils/hrc'
 import { faker } from '@faker-js/faker'
+import colors from '@flex-development/colors'
 import { chars } from '@flex-development/fsm-tokenizer'
 
 describe('unit:internal/takeVisible', () => {
@@ -18,12 +20,16 @@ describe('unit:internal/takeVisible', () => {
   })
 
   it.each<Parameters<typeof testSubject>>([
-    [emojis, +chars.digit1],
-    [digits.join(chars.empty), chars.digit3]
+    [colors.bold(emojiSequence), chars.digit1],
+    [colors.underline(digitSequence), +chars.digit3],
+    [colors.green('dog'), chars.digit1],
+    [colors.green('hello') + 'world', chars.digit5],
+    [emojiSequence, +chars.digit1],
+    [digitSequence, chars.digit3]
   ])('should return longest substring that fits into `columns` ([%j, %j])', (
     sequence,
     columns
   ) => {
-    expect(testSubject(sequence, columns)).toMatchSnapshot()
+    expect(hrc(testSubject(sequence, columns))).toMatchSnapshot()
   })
 })

src/internal/take-visible.mts

@@ -4,13 +4,16 @@
  */
 
 import gs from '#internal/gs'
+import { ansiRegex } from '@flex-development/ansi-regex'
 import { chars } from '@flex-development/fsm-tokenizer'
 import stringWidth from 'string-width'
 
 /**
  * Get the longest prefix of `sequence` that
  * fits within the specified number of `columns`.
  *
+ * > 👉 **Note**: ANSI escape codes do not count towards substring width.
+ *
  * @internal
  *
  * @this {void}
@@ -29,6 +32,13 @@ function takeVisible(
 ): string {
   if (+columns <= 0) return chars.empty
 
+  /**
+   * Regular expression matching ANSI escape codes.
+   *
+   * @const {RegExp} ansi
+   */
+  const ansi: RegExp = new RegExp(`^(${ansiRegex().source})`)
+
   /**
    * List of grapheme clusters.
    *
@@ -50,7 +60,11 @@ function takeVisible(
    */
   let width: number = 0
 
+  // build substring using graphemes.
+  // ansi escape codes do not count towards the width of the substring.
   for (const [index, grapheme] of graphemes.entries()) {
+    if (index < last) continue // skip clusters in ansi escape codes.
+
     /**
      * The visual width of the current grapheme.
      *
@@ -59,11 +73,29 @@ function takeVisible(
     const size: number = stringWidth(grapheme)
 
     // stop once column limit is reached, but ignore non-printing characters.
-    if (size && width + size > +columns) break
+    if (width + size > +columns && size) break
 
-    // include grapheme cluster in substring if it fits.
+    // grapheme cluster fits -- include in substring.
     width += size // increase visual width.
     last = index // capture index of last grapheme cluster in substring.
+
+    /**
+     * The remaining graphemes in the {@linkcode sequence}.
+     *
+     * @const {string[]} rest
+     */
+    const rest: string[] = last ? graphemes.slice(last + 1) : graphemes
+
+    /**
+     * A regular expression match array indicating whether the remaining portion
+     * of the {@linkcode sequence} begins with an ANSI escape code.
+     *
+     * @const {RegExpMatchArray | null} match
+     */
+    const match: RegExpMatchArray | null = rest.join(chars.empty).match(ansi)
+
+    // move index of last grapheme cluster to end of ansi escape code.
+    if (match) last = index + match[0].length
   }
 
   return graphemes.slice(0, last + 1).join(chars.empty)

yarn.lock

@@ -1437,6 +1437,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@flex-development/ansi-regex@npm:1.0.0":
+  version: 1.0.0
+  resolution: "@flex-development/ansi-regex@npm:1.0.0"
+  checksum: 10/31622b2be7ded14b8d2092e9fc8c011d865bbdfcbbfc164d688d9be228236f54369f67466d3a870cdcbbd939da9bec7cb17e44113afb6dcd2cfa1c11f5431e54
+  languageName: node
+  linkType: hard
+
 "@flex-development/builtin-modules@npm:1.0.0":
   version: 1.0.0
   resolution: "@flex-development/builtin-modules@npm:1.0.0"
@@ -1451,6 +1458,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@flex-development/colors@npm:2.0.0":
+  version: 2.0.0
+  resolution: "@flex-development/colors@npm:2.0.0"
+  checksum: 10/127b383643e16c544549459396480133fbf51a0fb75319786547672f7358a7ee7d6e14d0b2baec076c9f7d5566448b0dc71b0ff5db5b8bbda65102d86db7576a
+  languageName: node
+  linkType: hard
+
 "@flex-development/commitlint-config@npm:1.0.1":
   version: 1.0.1
   resolution: "@flex-development/commitlint-config@npm:1.0.1"
@@ -1896,6 +1910,8 @@ __metadata:
     "@commitlint/cli": "npm:20.1.0"
     "@commitlint/types": "npm:20.0.0"
     "@faker-js/faker": "npm:10.1.0"
+    "@flex-development/ansi-regex": "npm:1.0.0"
+    "@flex-development/colors": "npm:2.0.0"
     "@flex-development/commitlint-config": "npm:1.0.1"
     "@flex-development/eslint-config": "npm:1.1.1"
     "@flex-development/fsm-tokenizer": "npm:1.0.0-alpha.1"