feat: dynamic columns

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

Author: unicornware

README.md

@@ -25,6 +25,8 @@ Wrap a string
   - [`lines(thing, config[, options])`](#linesthing-config-options)
   - [`wrap(thing, config[, options])`](#wrapthing-config-options)
 - [Types](#types)
+  - [`ColumnsFunction<[T]>`](#columnsfunctiont)
+  - [`Columns`](#columns)
   - [`Config`](#config)
   - [`LinesInfo`](#linesinfo)
   - [`Options`](#options)
@@ -41,6 +43,7 @@ This is a small, but useful package for word-wrapping a string to a specified co
 ### Features
 
 \:rainbow: [ansi][] support\
+\:triangular\_ruler: configure columns dynamically\
 \:unicorn: emoji and fullwidth character support\
 \:arrow\_right: indent and pad lines
 
@@ -133,15 +136,16 @@ Get info about the lines of a wrapped string.
 
 #### Overloads
 
-- `lines(thing: unknown, config: number | string, options?: Options | null | undefined): LinesInfo`
-- `lines(thing: unknown, config: Config | number | string): LinesInfo`
+- `lines(thing: unknown, config: Columns, options?: Options | null | undefined): LinesInfo`
+- `lines(thing: unknown, config: Columns | Config): LinesInfo`
 
 ##### Parameters
 
 - `thing` (`unknown`)
   — the thing to wrap. non-string values will be converted to strings
-- `config` ([`Config`](#config) | `number` | `string`)
-  — the wrap configuration or the number of columns to wrap the string to
+- `config` ([`Columns`](#columns) | [`Config`](#config))
+  — the wrap configuration, the number of columns to wrap the string to,
+  or a function that returns the maximum number of columns per line
 - `options` ([`Options`](#options) | `null` | `undefined`, `optional`)
   — options for wrapping
 
@@ -155,15 +159,16 @@ Wrap a string to the specified column width.
 
 #### Overloads
 
-- `wrap(thing: unknown, config: number | string, options?: Options | null | undefined): string`
-- `wrap(thing: unknown, config: Config | number | string): string`
+- `wrap(thing: unknown, config: Columns, options?: Options | null | undefined): string`
+- `wrap(thing: unknown, config: Columns | Config): string`
 
 ##### Parameters
 
 - `thing` (`unknown`)
   — the thing to wrap. non-string values will be converted to strings
-- `config` ([`Config`](#config) | `number` | `string`)
-  — the wrap configuration or the number of columns to wrap the string to
+- `config` ([`Columns`](#columns) | [`Config`](#config))
+  — the wrap configuration, the number of columns to wrap the string to,
+  or a function that returns the maximum number of columns per line
 - `options` ([`Options`](#options) | `null` | `undefined`, `optional`)
   — options for wrapping
 
@@ -175,6 +180,45 @@ Wrap a string to the specified column width.
 
 This package is fully typed with [TypeScript][].
 
+### `ColumnsFunction<[T]>`
+
+Get the maximum number of columns for the line at `index` (`type`).
+
+> 👉 **Note**: The total number of available columns is calculated from the
+> maximum number of columns, indentation, and padding.
+
+```ts
+type ColumnsFunction<T extends number | string = number | string> = (
+  this: void,
+  index: number,
+  lines?: readonly string[] | null | undefined
+) => T
+```
+
+#### Type Parameters
+
+- `T` (`number` | `string`, optional)
+  — the maximum number of columns
+
+#### Parameters
+
+- `index` (`number`)
+  — the index of the current line, or `-1` on init
+- `lines` (`readonly string[]` | `null` | `undefined`, optional)
+  — the current list of lines
+
+#### Returns
+
+(`T`) The maximum number of columns
+
+### `Columns`
+
+Union of column configurations (`type`).
+
+```ts
+type Columns = ColumnsFunction | number | string
+```
+
 ### `Config`
 
 String wrapping configuration (`interface`).
@@ -185,15 +229,17 @@ String wrapping configuration (`interface`).
 
 #### Properties
 
-- `columns` (`number` | `string`)
-  — the number of columns to wrap the string to
+- `columns` ([`Columns`](#columns))
+  — the number of columns to wrap the string to, or a function that returns the maximum number of columns per line
 
 ### `LinesInfo`
 
 Info about the lines of a wrapped string (`interface`).
 
 #### Properties
 
+- `columns` ([`ColumnsFunction<number>`](#columnsfunctiont))
+  — get the maximum number of columns per line
 - `eol` (`string`)
   — the character, or characters, used to mark the end of a line
 - `indent` ([`SpacerFunction<string>`](#spacerfunctiont))
@@ -270,7 +316,7 @@ type SpacerFunction<
 #### Parameters
 
 - `index` (`number`)
-  — the index of the current line
+  — the index of the current line, or `-1` on init
 - `lines` (`readonly string[]` | `null` | `undefined`, optional)
   — the current list of lines
 

__tests__/plugins/chai/satisfy-columns.mts

@@ -4,8 +4,9 @@
  */
 
 import gs from '#internal/gs'
-import satisfyColumns from '#tests/utils/satisfy-columns'
+import type { ColumnsFunction } from '@flex-development/string-wrap'
 import stripAnsi from '@flex-development/strip-ansi'
+import { ok } from 'devlop'
 
 export default plugin
 
@@ -29,27 +30,62 @@ function plugin(chai: Chai.ChaiStatic, utils: Chai.ChaiUtils): undefined {
   /**
    * @this {Chai.Assertion}
    *
-   * @param {number | string} columns
-   *  The maximum (inclusive) number of columns
+   * @param {ColumnsFunction<number>} columns
+   *  A function that returns the maximum number of columns per line
    * @return {undefined}
    */
   function satisfy(
     this: Chai.Assertion,
-    columns: number | string
+    columns: ColumnsFunction<number>
   ): undefined {
     /**
-     * The line to check.
+     * The lines to check.
      *
-     * @const {string} line
+     * @const {string[]} lines
      */
-    const line: string = utils.flag(this, 'object')
-
-    return void this.assert(
-      satisfyColumns(columns)(line),
-      'expected length of #{this} to be in range [0,#{exp}] but got #{act}',
-      'expected length of #{this} to not be in range [0,#{exp}] but got #{act}',
-      +columns,
-      gs.countGraphemes(stripAnsi(line))
-    )
+    const lines: string[] = utils.flag(this, 'object')
+
+    /**
+     * The index of the current line.
+     *
+     * @var {number} i
+     */
+    let i: number = -1
+
+    // check size of each line.
+    while (++i < lines.length) {
+      /**
+       * The current line.
+       *
+       * @const {string | undefined} line
+       */
+      const line: string | undefined = lines[i]
+
+      ok(typeof line === 'string', 'expected `line[index]`')
+
+      /**
+       * The maximum number of allowed columns.
+       *
+       * @const {number} max
+       */
+      const max: number = columns(i, lines.slice(0, i))
+
+      /**
+       * The number of graphemes in the line.
+       *
+       * @const {number} size
+       */
+      const size: number = gs.countGraphemes(stripAnsi(line))
+
+      void this.assert(
+        size <= max,
+        `expected line[${i}] size to be in range [0,#{exp}] but got #{act}`,
+        `expected line[${i}] size to not be in range [0,#{exp}] but got #{act}`,
+        max,
+        size
+      )
+    }
+
+    return void columns
   }
 }

__tests__/utils/satisfy-columns.mts

@@ -62,7 +62,7 @@ function resolveSequence(this: void, events: Event[]): Event[] {
 
   // fill columns completely,
   // or break long sequences that don't fit on the current line.
-  if (self.fill || (seq > self.cols && self.hard)) {
+  if (self.fill || (seq > self.ac && self.hard)) {
     /**
      * The current sequence.
      *
@@ -78,7 +78,7 @@ function resolveSequence(this: void, events: Event[]): Event[] {
        *
        * @const {number} space
        */
-      const space: number = self.cols - width(self.line)
+      const space: number = self.ac - width(self.line)
 
       /**
        * The longest prefix of {@linkcode sequence} that fits into the
@@ -97,7 +97,7 @@ function resolveSequence(this: void, events: Event[]): Event[] {
       if (take) sequence = sequence.slice(take.length)
 
       // start new line if there is no more space.
-      if (width(self.line) === self.cols) self.flush()
+      if (width(self.line) === self.ac) self.flush()
     }
   } else {
     /**
@@ -108,7 +108,7 @@ function resolveSequence(this: void, events: Event[]): Event[] {
     const columns: number = width(self.line)
 
     // start new line if sequence cannot fit.
-    if (columns && columns + seq > self.cols) self.flush()
+    if (columns && columns + seq > self.ac) self.flush()
 
     // sequence fits on line normally, or soft wrap is enabled
     // and long words may extend past the configured column width.

src/constructs/sequence.mts

@@ -53,7 +53,7 @@ function resolveSpace(this: void, events: Event[]): Event[] {
   // start a new line if a space cannot fit,
   // or add the space to the current line if the line already has content.
   // if the line has no content, but should not be trimmed, also add the space.
-  if (width(self.line) + token.value.length > self.cols) {
+  if (width(self.line) + token.value.length > self.ac) {
     self.flush()
     if (!self.trim) self.line += token.value
   } else if (width(self.line) || !self.trim) {

src/constructs/space.mts

@@ -4,16 +4,16 @@
  */
 
 import type TestSubject from '#interfaces/config'
-import type { Options } from '@flex-development/string-wrap'
+import type { Columns, Options } from '@flex-development/string-wrap'
 
 describe('unit-d:interfaces/Config', () => {
   it('should extend Options', () => {
     expectTypeOf<TestSubject>().toExtend<Options>()
   })
 
-  it('should match [columns: number | string]', () => {
+  it('should match [columns: Columns]', () => {
     expectTypeOf<TestSubject>()
       .toHaveProperty('columns')
-      .toEqualTypeOf<number | string>()
+      .toEqualTypeOf<Columns>()
   })
 })

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

@@ -4,9 +4,18 @@
  */
 
 import type TestSubject from '#interfaces/lines-info'
-import type { SpacerFunction } from '@flex-development/string-wrap'
+import type {
+  ColumnsFunction,
+  SpacerFunction
+} from '@flex-development/string-wrap'
 
 describe('unit-d:interfaces/LinesInfo', () => {
+  it('should match [columns: ColumnsFunction<number>]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('columns')
+      .toEqualTypeOf<ColumnsFunction<number>>()
+  })
+
   it('should match [eol: string]', () => {
     expectTypeOf<TestSubject>().toHaveProperty('eol').toEqualTypeOf<string>()
   })

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

@@ -3,7 +3,7 @@
  * @module string-wrap/interfaces/Config
  */
 
-import type { Options } from '@flex-development/string-wrap'
+import type { Columns, Options } from '@flex-development/string-wrap'
 
 /**
  * String wrapping configuration.
@@ -14,9 +14,12 @@ import type { Options } from '@flex-development/string-wrap'
  */
 interface Config extends Options {
   /**
-   * The number of columns to wrap the string to.
+   * The number of columns to wrap the string to,
+   * or a function that returns the maximum number of columns per line.
+   *
+   * @see {@linkcode Columns}
    */
-  columns: number | string
+  columns: Columns
 }
 
 export type { Config as default }

src/interfaces/config.mts

@@ -3,12 +3,22 @@
  * @module string-wrap/interfaces/LinesInfo
  */
 
-import type { SpacerFunction } from '@flex-development/string-wrap'
+import type {
+  ColumnsFunction,
+  SpacerFunction
+} from '@flex-development/string-wrap'
 
 /**
  * Info about the lines of a wrapped string.
  */
 interface LinesInfo {
+  /**
+   * Get the maximum number of columns per line.
+   *
+   * @see {ColumnsFunction}
+   */
+  columns: ColumnsFunction<number>
+
   /**
    * The character, or characters, used to mark the end of a line.
    */