console-toolkit 1.2.8 → 1.2.10

package/src/plot/draw-rect.js

@@ -1,3 +1,11 @@
+/** Draws a filled rectangle on a Bitmap by efficiently manipulating the underlying bit array.
+ * @param {import('./bitmap.js').Bitmap} bmp - The bitmap to draw on.
+ * @param {number} x0 - First corner x coordinate.
+ * @param {number} y0 - First corner y coordinate.
+ * @param {number} x1 - Opposite corner x coordinate.
+ * @param {number} y1 - Opposite corner y coordinate.
+ * @param {number} [value=1] - Bit value: positive to set, 0 to clear, negative to toggle.
+ */
 export const drawRect = (bmp, x0, y0, x1, y1, value = 1) => {
   if (x1 < x0) [x0, x1] = [x1, x0];
   if (y1 < y0) [y0, y1] = [y1, y0];
@@ -26,8 +34,8 @@ export const drawRect = (bmp, x0, y0, x1, y1, value = 1) => {
         value > 0
           ? bmp.bitmap[indexL] | fullMask
           : value < 0
-          ? bmp.bitmap[indexL] ^ fullMask
-          : bmp.bitmap[indexL] & ~fullMask;
+            ? bmp.bitmap[indexL] ^ fullMask
+            : bmp.bitmap[indexL] & ~fullMask;
       return;
     }
 
@@ -52,21 +60,21 @@ export const drawRect = (bmp, x0, y0, x1, y1, value = 1) => {
       value > 0
         ? bmp.bitmap[indexL] | fullMaskL
         : value < 0
-        ? bmp.bitmap[indexL] ^ fullMaskL
-        : bmp.bitmap[indexL] & ~fullMaskL;
+          ? bmp.bitmap[indexL] ^ fullMaskL
+          : bmp.bitmap[indexL] & ~fullMaskL;
     for (let index = indexL + 1; index < indexR; ++index)
       bmp.bitmap[index] =
         value > 0
           ? bmp.bitmap[index] | fullMaskM
           : value < 0
-          ? bmp.bitmap[index] ^ fullMaskM
-          : bmp.bitmap[index] & ~fullMaskM;
+            ? bmp.bitmap[index] ^ fullMaskM
+            : bmp.bitmap[index] & ~fullMaskM;
     bmp.bitmap[indexR] =
       value > 0
         ? bmp.bitmap[indexR] | fullMaskR
         : value < 0
-        ? bmp.bitmap[indexR] ^ fullMaskR
-        : bmp.bitmap[indexR] & ~fullMaskR;
+          ? bmp.bitmap[indexR] ^ fullMaskR
+          : bmp.bitmap[indexR] & ~fullMaskR;
     return;
   }
 
@@ -86,8 +94,8 @@ export const drawRect = (bmp, x0, y0, x1, y1, value = 1) => {
         value > 0
           ? bmp.bitmap[indexL] | fullMask
           : value < 0
-          ? bmp.bitmap[indexL] ^ fullMask
-          : bmp.bitmap[indexL] & ~fullMask;
+            ? bmp.bitmap[indexL] ^ fullMask
+            : bmp.bitmap[indexL] & ~fullMask;
       indexL += bmp.lineSize;
     }
     if (fullLines) {
@@ -100,8 +108,8 @@ export const drawRect = (bmp, x0, y0, x1, y1, value = 1) => {
           value > 0
             ? bmp.bitmap[indexL] | fullMask
             : value < 0
-            ? bmp.bitmap[indexL] ^ fullMask
-            : bmp.bitmap[indexL] & ~fullMask;
+              ? bmp.bitmap[indexL] ^ fullMask
+              : bmp.bitmap[indexL] & ~fullMask;
     }
     if (lastRows) {
       // apply the mask to the last incomplete block
@@ -111,8 +119,8 @@ export const drawRect = (bmp, x0, y0, x1, y1, value = 1) => {
         value > 0
           ? bmp.bitmap[indexL] | fullMask
           : value < 0
-          ? bmp.bitmap[indexL] ^ fullMask
-          : bmp.bitmap[indexL] & ~fullMask;
+            ? bmp.bitmap[indexL] ^ fullMask
+            : bmp.bitmap[indexL] & ~fullMask;
     }
     return;
   }
@@ -136,21 +144,21 @@ export const drawRect = (bmp, x0, y0, x1, y1, value = 1) => {
       value > 0
         ? bmp.bitmap[indexL] | fullMaskL
         : value < 0
-        ? bmp.bitmap[indexL] ^ fullMaskL
-        : bmp.bitmap[indexL] & ~fullMaskL;
+          ? bmp.bitmap[indexL] ^ fullMaskL
+          : bmp.bitmap[indexL] & ~fullMaskL;
     for (let index = indexL + 1; index < indexR; ++index)
       bmp.bitmap[index] =
         value > 0
           ? bmp.bitmap[index] | fullMaskM
           : value < 0
-          ? bmp.bitmap[index] ^ fullMaskM
-          : bmp.bitmap[index] & ~fullMaskM;
+            ? bmp.bitmap[index] ^ fullMaskM
+            : bmp.bitmap[index] & ~fullMaskM;
     bmp.bitmap[indexR] =
       value > 0
         ? bmp.bitmap[indexR] | fullMaskR
         : value < 0
-        ? bmp.bitmap[indexR] ^ fullMaskR
-        : bmp.bitmap[indexR] & ~fullMaskR;
+          ? bmp.bitmap[indexR] ^ fullMaskR
+          : bmp.bitmap[indexR] & ~fullMaskR;
     indexL += bmp.lineSize;
     indexR += bmp.lineSize;
   }
@@ -169,16 +177,16 @@ export const drawRect = (bmp, x0, y0, x1, y1, value = 1) => {
         value > 0
           ? bmp.bitmap[indexL] | fullMaskL
           : value < 0
-          ? bmp.bitmap[indexL] ^ fullMaskL
-          : bmp.bitmap[indexL] & ~fullMaskL;
+            ? bmp.bitmap[indexL] ^ fullMaskL
+            : bmp.bitmap[indexL] & ~fullMaskL;
       for (let index = indexL + 1; index < indexR; ++index)
         bmp.bitmap[index] = value > 0 ? ~0 : value < 0 ? ~bmp.bitmap[index] : 0;
       bmp.bitmap[indexR] =
         value > 0
           ? bmp.bitmap[indexR] | fullMaskR
           : value < 0
-          ? bmp.bitmap[indexR] ^ fullMaskR
-          : bmp.bitmap[indexR] & ~fullMaskR;
+            ? bmp.bitmap[indexR] ^ fullMaskR
+            : bmp.bitmap[indexR] & ~fullMaskR;
     }
   }
 
@@ -195,21 +203,21 @@ export const drawRect = (bmp, x0, y0, x1, y1, value = 1) => {
       value > 0
         ? bmp.bitmap[indexL] | fullMaskL
         : value < 0
-        ? bmp.bitmap[indexL] ^ fullMaskL
-        : bmp.bitmap[indexL] & ~fullMaskL;
+          ? bmp.bitmap[indexL] ^ fullMaskL
+          : bmp.bitmap[indexL] & ~fullMaskL;
     for (let index = indexL + 1; index < indexR; ++index)
       bmp.bitmap[index] =
         value > 0
           ? bmp.bitmap[index] | fullMaskM
           : value < 0
-          ? bmp.bitmap[index] ^ fullMaskM
-          : bmp.bitmap[index] & ~fullMaskM;
+            ? bmp.bitmap[index] ^ fullMaskM
+            : bmp.bitmap[index] & ~fullMaskM;
     bmp.bitmap[indexR] =
       value > 0
         ? bmp.bitmap[indexR] | fullMaskR
         : value < 0
-        ? bmp.bitmap[indexR] ^ fullMaskR
-        : bmp.bitmap[indexR] & ~fullMaskR;
+          ? bmp.bitmap[indexR] ^ fullMaskR
+          : bmp.bitmap[indexR] & ~fullMaskR;
   }
 };
 

package/src/plot/index.d.ts

@@ -0,0 +1,39 @@
+import {Bitmap} from './bitmap.js';
+import {drawLine} from './draw-line.js';
+import {drawRect} from './draw-rect.js';
+import {toQuads} from './to-quads.js';
+import Box from '../box.js';
+
+declare module './bitmap.js' {
+  interface Bitmap {
+    /** Draws a line on this bitmap.
+     * @param x0 - Start X.
+     * @param y0 - Start Y.
+     * @param x1 - End X.
+     * @param y1 - End Y.
+     * @param value - Bit value.
+     * @returns This Bitmap.
+     */
+    line(x0: number, y0: number, x1: number, y1: number, value?: number): Bitmap;
+    /** Draws a filled rectangle on this bitmap.
+     * @param x0 - First corner x coordinate.
+     * @param y0 - First corner y coordinate.
+     * @param x1 - Opposite corner x coordinate.
+     * @param y1 - Opposite corner y coordinate.
+     * @param value - Bit value.
+     * @returns This Bitmap.
+     */
+    rect(x0: number, y0: number, x1: number, y1: number, value?: number): Bitmap;
+    /** Converts this bitmap to a Box using quadrant characters.
+     * @returns A Box.
+     */
+    toQuads(): Box;
+    /** Converts this bitmap to a string array via `toBox()`.
+     * @returns Array of strings.
+     */
+    toStrings(): string[];
+  }
+}
+
+export {Bitmap, drawLine, drawRect, toQuads};
+export default Bitmap;

package/src/plot/index.js

@@ -5,17 +5,39 @@ import toQuads from './to-quads.js';
 
 // patch Bitmap
 
+/** Draws a line on this bitmap.
+ * @param {number} x0 - Start X.
+ * @param {number} y0 - Start Y.
+ * @param {number} x1 - End X.
+ * @param {number} y1 - End Y.
+ * @param {number} [value=1] - Bit value.
+ * @returns {this}
+ */
 Bitmap.prototype.line = function (...args) {
   drawLine(this, ...args);
   return this;
 };
+/** Draws a filled rectangle on this bitmap.
+ * @param {number} x0 - First corner x coordinate.
+ * @param {number} y0 - First corner y coordinate.
+ * @param {number} x1 - Opposite corner x coordinate.
+ * @param {number} y1 - Opposite corner y coordinate.
+ * @param {number} [value=1] - Bit value.
+ * @returns {this}
+ */
 Bitmap.prototype.rect = function (...args) {
   drawRect(this, ...args);
   return this;
 };
+/** Converts this bitmap to a Box using quadrant characters.
+ * @returns {import('../box.js').default}
+ */
 Bitmap.prototype.toQuads = function () {
   return toQuads(this);
 };
+/** Converts this bitmap to a string array via `toBox()`.
+ * @returns {string[]}
+ */
 Bitmap.prototype.toStrings = function () {
   return this.toBox().toStrings();
 };

package/src/plot/to-quads.d.ts

@@ -0,0 +1,10 @@
+import Box from '../box.js';
+import {Bitmap} from './bitmap.js';
+
+/** Converts a Bitmap to a Box using Unicode quadrant characters (2x2 pixels per character).
+ * @param bmp - The source bitmap.
+ * @returns A Box representation using quadrant characters.
+ */
+export function toQuads(bmp: Bitmap): Box;
+
+export default toQuads;

package/src/plot/to-quads.js

@@ -1,6 +1,11 @@
 import Box from '../box.js';
 import {quadrants} from '../symbols.js';
 
+/** Converts a Bitmap to a Box using Unicode quadrant characters (2x2 pixels per character).
+ * Provides higher resolution representation than `toBox()`.
+ * @param {import('./bitmap.js').Bitmap} bmp - The bitmap to convert.
+ * @returns {import('../box.js').Box} A Box with quadrant characters.
+ */
 export const toQuads = bmp => {
   const result = [],
     rowSize = Math.floor((bmp.width + 1) / 2),

package/src/spinner/index.d.ts

@@ -0,0 +1,4 @@
+export {Spinner} from './spinner.js';
+export {default as spin} from './spin.js';
+
+export default spin;

package/src/spinner/index.js

@@ -1,5 +1,3 @@
-'use strict';
-
 export {Spinner} from './spinner.js';
 import spin from './spin.js';
 

package/src/spinner/spin.d.ts

@@ -0,0 +1,13 @@
+import {SpinnerBase} from './spinner.js';
+
+/** A spinner argument: frame array, state-to-string function, SpinnerBase instance, or other value. */
+type SpinArg = string[] | ((state: string) => string) | SpinnerBase | unknown;
+
+/** Tagged template literal for creating composite spinners from multiple parts.
+ * @param strings - Template string parts.
+ * @param args - Spinner arguments interpolated between string parts.
+ * @returns A composite SpinnerBase.
+ */
+declare function spin(strings: TemplateStringsArray, ...args: SpinArg[]): SpinnerBase;
+
+export default spin;

package/src/spinner/spin.js

@@ -1,8 +1,10 @@
-'use strict';
-
 import {SpinnerBase} from './spinner.js';
 
+/** Internal composite spinner that handles multiple spinner parts and functions via tagged template literals. */
 class Spinner extends SpinnerBase {
+  /** @param {TemplateStringsArray} strings - Template literal strings.
+   * @param {any[]} args - Interpolated values.
+   */
   constructor(strings, args) {
     super(false);
     this.strings = strings;
@@ -10,6 +12,9 @@ class Spinner extends SpinnerBase {
     this.indices = new WeakMap();
   }
 
+  /** Returns the current composite frame string.
+   * @returns {string}
+   */
   getFrame() {
     let result = '';
     for (let i = 0; i < this.args.length; ++i) {
@@ -46,6 +51,12 @@ class Spinner extends SpinnerBase {
   }
 }
 
+/** Tagged template literal function that creates a composite spinner.
+ * Arguments can be string arrays (cycled through), functions `(state) => string`, or SpinnerBase instances.
+ * @param {TemplateStringsArray} strings - Template literal strings.
+ * @param {...(string[]|Function|import('./spinner.js').SpinnerBase|*)} args - Interpolated values.
+ * @returns {import('./spinner.js').SpinnerBase} A composite spinner.
+ */
 const spin = (strings, ...args) => new Spinner(strings, args);
 
 export default spin;

package/src/spinner/spinner.d.ts

@@ -0,0 +1,69 @@
+/** Base class for managing spinner state (active, paused, finished). */
+export class SpinnerBase {
+  /** Whether the spinner is active. */
+  active: boolean;
+  /** Whether the spinner is paused. */
+  paused: boolean;
+  /** Whether the spinner is finished. */
+  finished: boolean;
+  /** Current frame index. */
+  frameIndex: number;
+
+  /**
+   * @param isStarted - If true, start in active state.
+   */
+  constructor(isStarted?: boolean);
+
+  /** Whether the spinner has been started. */
+  readonly isStarted: boolean;
+  /** Whether the spinner is currently active. */
+  readonly isActive: boolean;
+  /** Whether the spinner is finished. */
+  readonly isFinished: boolean;
+
+  /** The current state string: '', 'active', 'paused', or 'finished'. */
+  state: '' | 'active' | 'paused' | 'finished';
+
+  /** Resets the spinner to its initial state. */
+  reset(): void;
+  /** Advances and returns the next frame index.
+   * @param length - Number of frames available.
+   * @returns The next frame index.
+   */
+  nextFrameIndex(length: number): number;
+  /** Returns the current frame string.
+   * @returns The frame string.
+   */
+  getFrame(): string;
+}
+
+/** Definition of spinner frame sets. */
+export interface SpinnerDefinition {
+  /** Frames for the active state. */
+  frames?: string[];
+  /** Frames for the not-started state. */
+  notStarted?: string[];
+  /** Frames for the finished state. */
+  finished?: string[];
+}
+
+/** A spinner with configurable frame sets for different states.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Module:-spinner}
+ */
+export class Spinner extends SpinnerBase {
+  /** The resolved spinner definition with all frame sets. */
+  spinner: Required<SpinnerDefinition>;
+
+  /**
+   * @param spinnerDefinition - Spinner frame definition.
+   * @param isStarted - If true, start in active state.
+   */
+  constructor(spinnerDefinition?: SpinnerDefinition, isStarted?: boolean);
+
+  /** Returns the current frame string based on state.
+   * @returns The frame string.
+   */
+  getFrame(): string;
+}
+
+export default Spinner;

package/src/spinner/spinner.js

@@ -1,8 +1,10 @@
-'use strict';
-
 import {checkMarkHeavy} from '../symbols.js';
 
+/** Base class for spinners. Manages spinner state (active, paused, finished) and frame index. */
 export class SpinnerBase {
+  /**
+   * @param {boolean} [isStarted=false] - Whether the spinner starts in the active state.
+   */
   constructor(isStarted) {
     this.active = isStarted;
     this.paused = false;
@@ -10,24 +12,31 @@ export class SpinnerBase {
     this.frameIndex = 0;
   }
 
+  /** Whether the spinner has been started (active or finished). */
   get isStarted() {
     return this.active || this.finished;
   }
 
+  /** Whether the spinner is currently active. */
   get isActive() {
     return this.active;
   }
 
+  /** Whether the spinner has finished. */
   get isFinished() {
     return this.finished;
   }
 
+  /** The current state: `''`, `'active'`, `'paused'`, or `'finished'`. */
   get state() {
     if (this.finished) return 'finished';
     if (this.active) return this.paused ? 'paused' : 'active';
     return '';
   }
 
+  /** Sets the spinner state.
+   * @param {''|'active'|'paused'|'finished'} value
+   */
   set state(value) {
     this.finished = this.active = this.paused = false;
     switch (value) {
@@ -43,14 +52,22 @@ export class SpinnerBase {
     }
   }
 
+  /** Resets the spinner to its initial (not started) state. */
   reset() {
     this.active = this.paused = this.finished = false;
   }
 
+  /** Advances and returns the next frame index.
+   * @param {number} length - The total number of frames.
+   * @returns {number} The new frame index.
+   */
   nextFrameIndex(length) {
     return (this.frameIndex = (this.frameIndex + 1) % length);
   }
 
+  /** Returns the current frame string. Override in subclasses.
+   * @returns {string}
+   */
   getFrame() {
     return 'X';
   }
@@ -58,12 +75,23 @@ export class SpinnerBase {
 
 const defaultSpinnerDefinition = {notStarted: [' '], finished: [checkMarkHeavy], frames: [...'⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏']};
 
+/** A spinner with configurable frame sets for active, not-started, and finished states. */
 export class Spinner extends SpinnerBase {
+  /**
+   * @param {object} [spinnerDefinition] - Spinner definition with `frames`, `notStarted`, and `finished` arrays.
+   * @param {string[]} [spinnerDefinition.frames] - Animation frames for the active state.
+   * @param {string[]} [spinnerDefinition.notStarted] - Frames shown before the spinner starts.
+   * @param {string[]} [spinnerDefinition.finished] - Frames shown after the spinner finishes.
+   * @param {boolean} [isStarted=false] - Whether the spinner starts active.
+   */
   constructor(spinnerDefinition, isStarted) {
     super(isStarted);
     this.spinner = {...defaultSpinnerDefinition, ...spinnerDefinition};
   }
 
+  /** Returns the current frame based on the spinner's state.
+   * @returns {string}
+   */
   getFrame() {
     if (this.finished) return this.spinner.finished[this.nextFrameIndex(this.spinner.finished.length)];
     if (!this.active) return this.spinner.notStarted[this.nextFrameIndex(this.spinner.notStarted.length)];

package/src/spinner/spinners.d.ts

@@ -0,0 +1,34 @@
+import {SpinnerDefinition} from './spinner.js';
+
+/** Braille dots spinner. */
+export const dots: SpinnerDefinition;
+/** Sand/hourglass spinner. */
+export const sand: SpinnerDefinition;
+/** Line spinner (|/-\). */
+export const line: SpinnerDefinition;
+/** Pipe spinner. */
+export const pipe: SpinnerDefinition;
+/** Vertical growing bar spinner. */
+export const growVertical: SpinnerDefinition;
+/** Horizontal growing bar spinner. */
+export const growHorizontal: SpinnerDefinition;
+/** Random noise spinner. */
+export const noise: SpinnerDefinition;
+/** Bouncing spinner. */
+export const bounce: SpinnerDefinition;
+/** Arc spinner. */
+export const arc: SpinnerDefinition;
+/** Square quarters spinner. */
+export const squareQuarters: SpinnerDefinition;
+/** Circle quarters spinner. */
+export const circleQuarters: SpinnerDefinition;
+/** Circle halves spinner. */
+export const circleHalves: SpinnerDefinition;
+/** Arrows spinner. */
+export const arrows: SpinnerDefinition;
+/** Clock spinner. */
+export const clock: SpinnerDefinition;
+/** Bouncing bar spinner. */
+export const bouncingBar: SpinnerDefinition;
+/** Bouncing ball spinner. */
+export const bouncingBall: SpinnerDefinition;

package/src/spinner/spinners.js

@@ -1,29 +1,42 @@
-'use strict';
-
 // Spinners are from https://github.com/sindresorhus/cli-spinners under the MIT license.
 // Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
 // See `cli-spinners` for more great options.
 
+/** Braille dots spinner. */
 export const dots = {frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']};
+/** Sand/hourglass spinner. */
 export const sand = {frames: [...'⠁⠂⠄⡀⡈⡐⡠⣀⣁⣂⣄⣌⣔⣤⣥⣦⣮⣶⣷⣿⡿⠿⢟⠟⡛⠛⠫⢋⠋⠍⡉⠉⠑⠡⢁']};
+/** Line spinner (|/-\). */
 export const line = {frames: ['-', '\\', '|', '/']};
-export const pipe = {frame: ['┤', '┘', '┴', '└', '├', '┌', '┬', '┐']};
-export const growVertical = {frame: ['▁', '▃', '▄', '▅', '▆', '▇', '▆', '▅', '▄', '▃']};
-export const growHorizontal = {frame: ['▏', '▎', '▍', '▌', '▋', '▊', '▉', '▊', '▋', '▌', '▍', '▎']};
-export const noise = {frame: ['▓', '▒', '░']};
-export const bounce = {frame: ['⠁', '⠂', '⠄', '⠂']};
-export const arc = {frame: ['◜', '◠', '◝', '◞', '◡', '◟']};
+/** Pipe spinner. */
+export const pipe = {frames: ['┤', '┘', '┴', '└', '├', '┌', '┬', '┐']};
+/** Vertical growing bar spinner. */
+export const growVertical = {frames: ['▁', '▃', '▄', '▅', '▆', '▇', '▆', '▅', '▄', '▃']};
+/** Horizontal growing bar spinner. */
+export const growHorizontal = {frames: ['▏', '▎', '▍', '▌', '▋', '▊', '▉', '▊', '▋', '▌', '▍', '▎']};
+/** Random noise spinner. */
+export const noise = {frames: ['▓', '▒', '░']};
+/** Bouncing spinner. */
+export const bounce = {frames: ['⠁', '⠂', '⠄', '⠂']};
+/** Arc spinner. */
+export const arc = {frames: ['◜', '◠', '◝', '◞', '◡', '◟']};
+/** Square quarters spinner. */
 export const squareQuarters = {frames: ['◰', '◳', '◲', '◱']};
+/** Circle quarters spinner. */
 export const circleQuarters = {frames: ['◴', '◷', '◶', '◵']};
+/** Circle halves spinner. */
 export const circleHalves = {frames: ['◐', '◓', '◑', '◒']};
-export const arrows = {frame: ['←', '↖', '↑', '↗', '→', '↘', '↓', '↙']};
+/** Arrows spinner. */
+export const arrows = {frames: ['←', '↖', '↑', '↗', '→', '↘', '↓', '↙']};
 
+/** Clock spinner. */
 export const clock = {
   frames: ['🕛 ', '🕐 ', '🕑 ', '🕒 ', '🕓 ', '🕔 ', '🕕 ', '🕖 ', '🕗 ', '🕘 ', '🕙 ', '🕚 '],
   notStarted: [' '],
   finished: ['✔ ']
 };
 
+/** Bouncing bar spinner. */
 export const bouncingBar = {
   frames: [
     '[    ]',
@@ -47,6 +60,7 @@ export const bouncingBar = {
   finished: ['[####]']
 };
 
+/** Bouncing ball spinner. */
 export const bouncingBall = {
   frames: [
     '( ●    )',

package/src/strings/clip.d.ts

@@ -0,0 +1,21 @@
+/** Options for the `clip()` function. */
+export interface ClipOptions {
+  /** If true, include the last ANSI command at the clip boundary. */
+  includeLastCommand?: boolean;
+  /** RegExp for matching escape sequences. */
+  matcher?: RegExp;
+  /** If true, ignore control symbols when calculating width. */
+  ignoreControlSymbols?: boolean;
+  /** If true, treat East Asian ambiguous-width characters as wide. */
+  ambiguousAsWide?: boolean;
+}
+
+/** Clips a string to a given display width, correctly handling ANSI escape codes and multi-width characters.
+ * @param s - The string to clip.
+ * @param width - Maximum display width.
+ * @param options - Clip options.
+ * @returns The clipped string.
+ */
+export function clip(s: string, width: number, options?: ClipOptions): string;
+
+export default clip;

package/src/strings/clip.js

@@ -1,6 +1,16 @@
 import parse, {matchCsiNoGroups} from './parse.js';
 import {split} from './split.js';
 
+/** Clips a string to a specified display width, correctly handling ANSI escape codes and multi-width characters.
+ * @param {string} s - The string to clip.
+ * @param {number} width - The maximum display width.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.includeLastCommand=false] - If true, include the last (invisible) ANSI command in the clipped result.
+ * @param {RegExp} [options.matcher=matchCsiNoGroups] - The regular expression used to match escape sequences.
+ * @param {boolean} [options.ignoreControlSymbols] - If true, control symbols are ignored during width calculation.
+ * @param {boolean} [options.ambiguousAsWide] - If true, ambiguous East Asian characters are treated as double-wide.
+ * @returns {string} The clipped string.
+ */
 export const clip = (s, width, options = {}) => {
   const {includeLastCommand = false, matcher = matchCsiNoGroups} = options;
 

package/src/strings/parse.d.ts

@@ -0,0 +1,23 @@
+/** RegExp matching CSI sequences without capture groups. */
+export const matchCsiNoGroups: RegExp;
+/** RegExp matching CSI sequences excluding SGR, without capture groups. */
+export const matchCsiNoSgrNoGroups: RegExp;
+
+/** A segment yielded by the `parse()` generator. */
+export interface ParseResult {
+  /** Start index of this segment in the original string. */
+  start: number;
+  /** The text content of this segment. */
+  string: string;
+  /** The RegExp match for an escape sequence, or `null` for plain text. */
+  match: RegExpMatchArray | null;
+}
+
+/** Generator that yields segments of text and matched ANSI escape sequences.
+ * @param s - The string to parse.
+ * @param matcher - RegExp for matching escape sequences (default: matchCsiNoGroups).
+ * @returns A generator of ParseResult segments.
+ */
+export function parse(s: string, matcher?: RegExp): Generator<ParseResult, void, unknown>;
+
+export default parse;

package/src/strings/parse.js

@@ -1,6 +1,13 @@
+/** RegExp that matches CSI sequences with no capture groups. */
 export const matchCsiNoGroups = /\x1B\[[\x30-\x3F]*[\x20-\x2F]*[\x40-\x7E]/g;
+/** RegExp that matches CSI sequences excluding SGR commands, with no capture groups. */
 export const matchCsiNoSgrNoGroups = /\x1B\[[\x30-\x3F]*[\x20-\x2F]*[\x40-\x6C\x6E-\x7E]/g;
 
+/** Parses a string yielding segments of text and matched ANSI escape sequences.
+ * @param {string} s - The string to parse.
+ * @param {RegExp} [matcher=matchCsiNoGroups] - The regular expression used to match escape sequences.
+ * @yields {{start: number, string: string, match: RegExpMatchArray | null}} Parsed segments.
+ */
 export function* parse(s, matcher = matchCsiNoGroups) {
   s = String(s);
   let start = 0;