feat!: spacer functions

Signed-off-by: Lexus Drumgold <[email protected]>

Author: unicornware

README.md

@@ -26,9 +26,10 @@ Wrap a string
   - [`wrap(thing, config[, options])`](#wrapthing-config-options)
 - [Types](#types)
   - [`Config`](#config)
-  - [`LinePadding`](#linepadding)
   - [`LinesInfo`](#linesinfo)
   - [`Options`](#options)
+  - [`SpacerFunction<[T]>`](#spacerfunctiont)
+  - [`Spacer`](#spacer)
   - [`StripAnsi`](#stripansi)
   - [`ToString<[T]>`](#tostringt)
 - [Contribute](#contribute)
@@ -187,14 +188,6 @@ String wrapping configuration (`interface`).
 - `columns` (`number` | `string`)
   — the number of columns to wrap the string to
 
-### `LinePadding`
-
-The strings used to pad either side of each line (`type`).
-
-```ts
-type LinePadding = [left: string, right: string]
-```
-
 ### `LinesInfo`
 
 Info about the lines of a wrapped string (`interface`).
@@ -203,12 +196,14 @@ Info about the lines of a wrapped string (`interface`).
 
 - `eol` (`string`)
   — the character, or characters, used to mark the end of a line
-- `indent` (`string`)
-  — the string used to indent each line
+- `indent` ([`SpacerFunction<string>`](#spacerfunctiont))
+  — get the string used to indent each line
 - `lines` (`readonly string[]`)
   — the list of lines forming the wrapped string
-- `padding` ([`LinePadding`](#linepadding))
-  — the strings used to pad either side of each line
+- `padLeft` ([`SpacerFunction<string>`](#spacerfunctiont))
+  — get the string used to pad the left side of each line
+- `padRight` ([`SpacerFunction<string>`](#spacerfunctiont))
+  — get the string used to pad the right side of each line
 
 ### `Options`
 
@@ -229,11 +224,11 @@ Options for wrapping a string (`interface`).
   by default, long words remain unbroken and push onto the next line if they don't fit on the current line.\
   setting this to `true` will break long words.
   > 👉 **note**: setting this to `true` will break words.
-- `indent?` (`number` | `string` | `null` | `undefined`, optional)
+- `indent?` ([`SpacerFunction`](#spacerfunctiont) | `number` | `string` | `null` | `undefined`, optional)
   — the size of the string to use for indenting each line (as a number or numeric), or the string itself
-- `padLeft?` (`number` | `string` | `null` | `undefined`, optional)
+- `padLeft?` ([`SpacerFunction`](#spacerfunctiont) | `number` | `string` | `null` | `undefined`, optional)
   — the size of the string to use for padding the left side of each line (as a number or numeric), or the string itself
-- `padRight?` (`number` | `string` | `null` | `undefined`, optional)
+- `padRight?` ([`SpacerFunction`](#spacerfunctiont) | `number` | `string` | `null` | `undefined`, optional)
   — the size of the string to use for padding the right side of each line (as a number or numeric), or the string itself
 - `stringify?` ([`ToString`](#tostringt) | `null` | `undefined`, optional)
   — convert a value to a string
@@ -247,6 +242,54 @@ Options for wrapping a string (`interface`).
   > 👉 **note**: lines are trimmed before applying indents or padding.
   - default: `true`
 
+### `SpacerFunction<[T]>`
+
+Get a spacer configuration for the line at `index` (`type`).
+
+Spacers can be used to indent a line, and/or pad either side of it.
+
+```ts
+type SpacerFunction<
+  T extends number | string | null | undefined =
+    | number
+    | string
+    | null
+    | undefined
+> = (
+  this: void,
+  index: number,
+  lines?: readonly string[] | null | undefined
+) => T
+```
+
+#### Type Parameters
+
+- `T` (`number` | `string` | `null` | `undefined`, optional)
+  — the spacer configuration
+
+#### Parameters
+
+- `index` (`number`)
+  — the index of the current line
+- `lines` (`readonly string[]` | `null` | `undefined`, optional)
+  — the current list of lines
+
+#### Returns
+
+(`T`) The spacer configuration
+
+### `Spacer`
+
+Union of spacer configurations (`type`).
+
+Spacers can be used to indent a line, and/or pad either side of it.
+
+Valid spacer configurations are functions, sizes (as a number or numeric), or the spacer itself.
+
+```ts
+type Spacer = SpacerFunction | number | string
+```
+
 ### `StripAnsi`
 
 Remove ANSI escape codes from a string (`type`).

src/interfaces/__tests__/lines-info.spec-d.mts

@@ -4,15 +4,17 @@
  */
 
 import type TestSubject from '#interfaces/lines-info'
-import type { LinePadding } from '@flex-development/string-wrap'
+import type { SpacerFunction } from '@flex-development/string-wrap'
 
 describe('unit-d:interfaces/LinesInfo', () => {
   it('should match [eol: string]', () => {
     expectTypeOf<TestSubject>().toHaveProperty('eol').toEqualTypeOf<string>()
   })
 
-  it('should match [indent: string]', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('indent').toEqualTypeOf<string>()
+  it('should match [indent: SpacerFunction<string>]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('indent')
+      .toEqualTypeOf<SpacerFunction<string>>()
   })
 
   it('should match [lines: readonly string[]]', () => {
@@ -21,9 +23,15 @@ describe('unit-d:interfaces/LinesInfo', () => {
       .toEqualTypeOf<readonly string[]>()
   })
 
-  it('should match [padding: LinePadding]', () => {
+  it('should match [padLeft: SpacerFunction<string>]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('padLeft')
+      .toEqualTypeOf<SpacerFunction<string>>()
+  })
+
+  it('should match [padRight: SpacerFunction<string>]', () => {
     expectTypeOf<TestSubject>()
-      .toHaveProperty('padding')
-      .toEqualTypeOf<LinePadding>()
+      .toHaveProperty('padRight')
+      .toEqualTypeOf<SpacerFunction<string>>()
   })
 })

src/interfaces/__tests__/options.spec-d.mts

@@ -4,7 +4,7 @@
  */
 
 import type TestSubject from '#interfaces/options'
-import type { StripAnsi, ToString } from '@flex-development/string-wrap'
+import type { Spacer, StripAnsi, ToString } from '@flex-development/string-wrap'
 import type { Nilable, OptionalKeys } from '@flex-development/tutils'
 
 describe('unit-d:interfaces/Options', () => {
@@ -30,22 +30,22 @@ describe('unit-d:interfaces/Options', () => {
       .toEqualTypeOf<Nilable<boolean>>()
   })
 
-  it('should match [indent?: number | string | null | undefined]', () => {
+  it('should match [indent?: Spacer | null | undefined]', () => {
     expectTypeOf<TestSubject>()
       .toHaveProperty('indent')
-      .toEqualTypeOf<Nilable<number | string>>()
+      .toEqualTypeOf<Nilable<Spacer>>()
   })
 
-  it('should match [padLeft?: number | string | null | undefined]', () => {
+  it('should match [padLeft?: Spacer | null | undefined]', () => {
     expectTypeOf<TestSubject>()
       .toHaveProperty('padLeft')
-      .toEqualTypeOf<Nilable<number | string>>()
+      .toEqualTypeOf<Nilable<Spacer>>()
   })
 
-  it('should match [padRight?: number | string | null | undefined]', () => {
+  it('should match [padRight?: Spacer | null | undefined]', () => {
     expectTypeOf<TestSubject>()
       .toHaveProperty('padRight')
-      .toEqualTypeOf<Nilable<number | string>>()
+      .toEqualTypeOf<Nilable<Spacer>>()
   })
 
   it('should match [stringify?: ToString | null | undefined]', () => {

src/interfaces/lines-info.mts

@@ -3,7 +3,7 @@
  * @module string-wrap/interfaces/LinesInfo
  */
 
-import type { LinePadding } from '@flex-development/string-wrap'
+import type { SpacerFunction } from '@flex-development/string-wrap'
 
 /**
  * Info about the lines of a wrapped string.
@@ -15,21 +15,30 @@ interface LinesInfo {
   eol: string
 
   /**
-   * The string used to indent each line.
+   * Get the string used to indent each line.
+   *
+   * @see {@linkcode SpacerFunction}
    */
-  indent: string
+  indent: SpacerFunction<string>
 
   /**
    * The list of lines forming the wrapped string.
    */
   lines: readonly string[]
 
   /**
-   * The strings used to pad either side of each line.
+   * Get the string used to pad the left side of each line.
+   *
+   * @see {@linkcode SpacerFunction}
+   */
+  padLeft: SpacerFunction<string>
+
+  /**
+   * Get the string used to pad the right side of each line.
    *
-   * @see {@linkcode LinePadding}
+   * @see {@linkcode SpacerFunction}
    */
-  padding: LinePadding
+  padRight: SpacerFunction<string>
 }
 
 export type { LinesInfo as default }

src/interfaces/options.mts

@@ -3,7 +3,7 @@
  * @module string-wrap/interfaces/Options
  */
 
-import type { StripAnsi, ToString } from '@flex-development/string-wrap'
+import type { Spacer, StripAnsi, ToString } from '@flex-development/string-wrap'
 
 /**
  * Options for wrapping a string.
@@ -37,22 +37,28 @@ interface Options {
   hard?: boolean | null | undefined
 
   /**
-   * The size of the string to use for indenting each line (as a number or
-   * numeric), or the string itself.
+   * A spacer function, the size of the string to use for indenting each line
+   * (as a number or numeric), or the string itself.
+   *
+   * @see {@linkcode Spacer}
    */
-  indent?: number | string | null | undefined
+  indent?: Spacer | null | undefined
 
   /**
-   * The size of the string to use for padding the left side of each line (as a
-   * number or numeric), or the string itself.
+   * A spacer function, the size of the string to use for padding the left side
+   * of each line (as a number or numeric), or the string itself.
+   *
+   * @see {@linkcode Spacer}
    */
-  padLeft?: number | string | null | undefined
+  padLeft?: Spacer | null | undefined
 
   /**
-   * The size of the string to use for padding the right side of each line (as a
-   * number or numeric), or the string itself.
+   * A spacer function, the size of the string to use for padding the right
+   * side of each line (as a number or numeric), or the string itself.
+   *
+   * @see {@linkcode Spacer}
    */
-  padRight?: number | string | null | undefined
+  padRight?: Spacer | null | undefined
 
   /**
    * Convert a value to a string.

src/internal/__snapshots__/happy-dom/tokenize.functional.snap

@@ -3350,7 +3350,7 @@ exports[`functional:internal/tokenize > options.indent > should indent each line
   "candidate": ""The quick brown fox jumped over the lazy dog"",
   "cols": 18,
   "columns": 20,
-  "indent": "  ",
+  "indent": [Function spacer],
   "lines": [
     "  The quick brown",
     "  fox jumped over",
@@ -3360,11 +3360,25 @@ exports[`functional:internal/tokenize > options.indent > should indent each line
 `;
 
 exports[`functional:internal/tokenize > options.indent > should indent each line (1) 1`] = `
+{
+  "candidate": ""The \\u001b[1mquick\\u001b[22m brown \\u001b[31mfox jumped over \\u001b[39mthe \\u001b[3mlazy\\u001b[23m \\u001b[32mdog and then ran away with the unicorn.\\u001b[39m"",
+  "cols": 24,
+  "columns": 30,
+  "indent": [Function spacer],
+  "lines": [
+    "The \\u001b[1mquick\\u001b[22m brown \\u001b[31mfox jumped",
+    "  over \\u001b[39mthe \\u001b[3mlazy\\u001b[23m \\u001b[32mdog and then",
+    "    ran away with the unicorn.\\u001b[39m",
+  ],
+}
+`;
+
+exports[`functional:internal/tokenize > options.indent > should indent each line (2) 1`] = `
 {
   "candidate": ""hello\\r\\nworld 🌎"",
   "cols": 6,
   "columns": 7,
-  "indent": " ",
+  "indent": [Function spacer],
   "lines": [
     " hello",
     " world",
@@ -3383,8 +3397,8 @@ exports[`functional:internal/tokenize > options.pad* > should add padding to eac
     "  🦾",
     "  🚀",
   ],
-  "padLeft": "  ",
-  "padRight": "",
+  "padLeft": [Function spacer],
+  "padRight": [Function spacer],
 }
 `;
 
@@ -3406,12 +3420,34 @@ exports[`functional:internal/tokenize > options.pad* > should add padding to eac
     "9    ",
     "    ",
   ],
-  "padLeft": "",
-  "padRight": "    ",
+  "padLeft": [Function spacer],
+  "padRight": [Function spacer],
 }
 `;
 
 exports[`functional:internal/tokenize > options.pad* > should add padding to each line (2) 1`] = `
+{
+  "candidate": ""0 1 2 3 4 5 6 7 8 9"",
+  "cols": 1,
+  "columns": 13,
+  "lines": [
+    "     |0|     ",
+    "     |1|     ",
+    "     |2|     ",
+    "     |3|     ",
+    "     |4|     ",
+    "     |5|     ",
+    "     |6|     ",
+    "     |7|     ",
+    "     |8|     ",
+    "     |9|     ",
+  ],
+  "padLeft": [Function spacer],
+  "padRight": [Function spacer],
+}
+`;
+
+exports[`functional:internal/tokenize > options.pad* > should add padding to each line (3) 1`] = `
 {
   "candidate": ""The quick brown fox jumped over the lazy dog"",
   "cols": 18,
@@ -3421,8 +3457,8 @@ exports[`functional:internal/tokenize > options.pad* > should add padding to eac
     " fox jumped over ",
     " the lazy dog ",
   ],
-  "padLeft": " ",
-  "padRight": " ",
+  "padLeft": [Function spacer],
+  "padRight": [Function spacer],
 }
 `;