console-toolkit 1.2.8 → 1.2.10

package/src/strings/split.d.ts

@@ -0,0 +1,38 @@
+/** A single grapheme with its display width. */
+export interface Grapheme {
+  /** The grapheme string. */
+  symbol: string;
+  /** The display width in columns. */
+  width: number;
+}
+
+/** Result of splitting a string into graphemes. */
+export interface SplitResult {
+  /** Array of graphemes. */
+  graphemes: Grapheme[];
+  /** Total display width. */
+  width: number;
+}
+
+/** Options for `split()` and `size()`. */
+export interface SplitOptions {
+  /** If true, ignore control symbols. */
+  ignoreControlSymbols?: boolean;
+  /** If true, treat East Asian ambiguous-width characters as wide. */
+  ambiguousAsWide?: boolean;
+}
+
+/** Splits a string into graphemes with their display widths.
+ * @param s - The string to split.
+ * @param options - Split options.
+ * @returns The graphemes and total width.
+ */
+export function split(s: string, options?: SplitOptions): SplitResult;
+/** Returns the display width of a string.
+ * @param s - The string to measure.
+ * @param options - Split options.
+ * @returns The display width in columns.
+ */
+export function size(s: string, options?: SplitOptions): number;
+
+export default split;

package/src/strings/split.js

@@ -18,6 +18,14 @@ if (!globalThis.Bun) {
 
 const segmenter = new Intl.Segmenter();
 
+/** Splits a string into graphemes (individual symbols) and calculates its display width.
+ * Optionally detects double-width characters using `emoji-regex` and `get-east-asian-width` if available.
+ * @param {string} s - The string to split.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.ignoreControlSymbols=false] - If true, control symbols are ignored.
+ * @param {boolean} [options.ambiguousAsWide=false] - If true, ambiguous East Asian characters are treated as double-wide.
+ * @returns {{graphemes: {symbol: string, width: number}[], width: number}} The graphemes and total display width.
+ */
 export const split = (s, options = {}) => {
   s = String(s);
   if (!s) return {graphemes: [], width: 0};
@@ -66,6 +74,13 @@ export const split = (s, options = {}) => {
   return {graphemes, width};
 };
 
+/** Calculates the display width of a string, accounting for double-width characters.
+ * @param {string} s - The string to measure.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.ignoreControlSymbols=false] - If true, control symbols are ignored.
+ * @param {boolean} [options.ambiguousAsWide=false] - If true, ambiguous East Asian characters are treated as double-wide.
+ * @returns {number} The display width of the string.
+ */
 export const size = (s, options = {}) => {
   s = String(s);
   if (!s) return 0;

package/src/strings.d.ts

@@ -0,0 +1,44 @@
+import {ClipOptions} from './strings/clip.js';
+
+/** Returns the display width of a string, ignoring ANSI escape sequences.
+ * @param s - The string to measure.
+ * @param matcher - RegExp for matching escape sequences (default: matchCsiNoGroups).
+ * @returns The visible display width.
+ */
+export function getLength(s: string, matcher?: RegExp): number;
+/** Returns the maximum display width among an array of strings.
+ * @param strings - The strings to measure.
+ * @param matcher - RegExp for matching escape sequences.
+ * @returns The maximum display width.
+ */
+export function getMaxLength(strings: string[], matcher?: RegExp): number;
+/** Clips each string in an array to a given display width.
+ * @param strings - The strings to clip.
+ * @param width - Maximum display width.
+ * @param options - Clip options.
+ * @returns The clipped strings.
+ */
+export function clipStrings(strings: string[], width: number, options?: ClipOptions): string[];
+
+export type StringsValue =
+  | null
+  | undefined
+  | boolean
+  | number
+  | string
+  | string[]
+  | object
+  | {toStrings(): string[]}
+  | {toBox(): {box: string[]}}
+  | {toPanel(): {toStrings(): string[]}};
+export type StringsFunction = () => StringsFunction | StringsValue;
+export type StringsInput = StringsValue | StringsFunction;
+
+/** Converts various input types to a string array.
+ * @param s - Input: string, string array, Box, number, null/undefined, or object with `toStrings()`.
+ * @returns An array of strings.
+ */
+export function toStrings(s: StringsInput): string[];
+
+export {default as clip} from './strings/clip.js';
+export {matchCsiNoGroups, matchCsiNoSgrNoGroups} from './strings/parse.js';

package/src/strings.js

@@ -2,6 +2,12 @@ import {size} from './strings/split.js';
 import parse, {matchCsiNoGroups, matchCsiNoSgrNoGroups} from './strings/parse.js';
 import clip from './strings/clip.js';
 
+/** Returns the visible display length of a string, excluding invisible ANSI escape sequences
+ * and correctly handling Unicode code points that span multiple UTF-16 items.
+ * @param {string} s - The string to measure.
+ * @param {RegExp} [matcher=matchCsiNoGroups] - The regular expression used to match escape sequences.
+ * @returns {number} The visible display length.
+ */
 export const getLength = (s, matcher) => {
   let counter = 0;
   for (const {string} of parse(s, matcher)) {
@@ -10,12 +16,36 @@ export const getLength = (s, matcher) => {
   return counter;
 };
 
-export const getMaxLength = (strings, matcher) =>
-  strings.reduce((acc, s) => Math.max(acc, getLength(s, matcher)), 0);
+/** Returns the maximum visible display length among an array of strings.
+ * @param {string[]} strings - The strings to measure.
+ * @param {RegExp} [matcher=matchCsiNoGroups] - The regular expression used to match escape sequences.
+ * @returns {number} The maximum visible display length.
+ */
+export const getMaxLength = (strings, matcher) => strings.reduce((acc, s) => Math.max(acc, getLength(s, matcher)), 0);
 
-export const clipStrings = (strings, width, options) =>
-  strings.map(s => clip(s, width, options));
+/** Clips each string in an array to a specified display width.
+ * @param {string[]} strings - The strings to clip.
+ * @param {number} width - The maximum display width.
+ * @param {object} [options] - Options passed to `clip()`.
+ * @returns {string[]} The clipped strings.
+ */
+export const clipStrings = (strings, width, options) => strings.map(s => clip(s, width, options));
 
+/** Converts a variety of inputs into an array of strings (the simplest text container).
+ *
+ * - A function is called (up to 10 times) and its result is re-processed.
+ * - A number or boolean returns `[String(s)]`.
+ * - A string is split by newlines.
+ * - An array is shallow-copied.
+ * - An object with `toStrings()` is called.
+ * - An object with `toBox()` returns `toBox().box`.
+ * - An object with `toPanel()` returns `toPanel().toStrings()`.
+ * - Other non-null objects are converted via `String()`.
+ * - Null/undefined returns `[]`.
+ *
+ * @param {*} s - The input to convert.
+ * @returns {string[]} An array of strings.
+ */
 export const toStrings = s => {
   main: for (;;) {
     switch (typeof s) {

package/src/style.d.ts

@@ -0,0 +1,462 @@
+import {SgrState} from './ansi/sgr-state.js';
+
+export {RESET_STATE} from './ansi/sgr-state.js';
+
+/** Methods available on color namespace objects (fg, bg, colorDecoration). */
+interface ColorMethods {
+  /** Sets color by standard color number.
+   * @param c - Color number (0-9).
+   * @returns A new Style.
+   */
+  color(c: number): Style;
+  /** Sets 256-color by standard RGB.
+   * @param r - Red (0-5).
+   * @param g - Green (0-5).
+   * @param b - Blue (0-5).
+   * @returns A new Style.
+   */
+  stdRgb256(r: number, g: number, b: number): Style;
+  /** Sets bright 256-color by standard RGB.
+   * @returns A new Style.
+   */
+  brightStdRgb256(r: number, g: number, b: number): Style;
+  /** Sets dark 256-color by standard RGB.
+   * @returns A new Style.
+   */
+  darkStdRgb256(r: number, g: number, b: number): Style;
+  /** Sets color by standard RGB (alias for stdRgb256).
+   * @returns A new Style.
+   */
+  stdRgb(r: number, g: number, b: number): Style;
+  /** Sets bright color by standard RGB (alias for brightStdRgb256).
+   * @returns A new Style.
+   */
+  brightStdRgb(r: number, g: number, b: number): Style;
+  /** Sets dark color by standard RGB (alias for darkStdRgb256).
+   * @returns A new Style.
+   */
+  darkStdRgb(r: number, g: number, b: number): Style;
+  /** Sets 256-color by RGB.
+   * @param r - Red (0-255).
+   * @param g - Green (0-255).
+   * @param b - Blue (0-255).
+   * @returns A new Style.
+   */
+  rgb256(r: number, g: number, b: number): Style;
+  /** Sets 256-color by hex.
+   * @param hex - Hex color value.
+   * @returns A new Style.
+   */
+  hex256(hex: number): Style;
+  /** Sets 256-color by 6x6x6 RGB.
+   * @param r - Red (0-5).
+   * @param g - Green (0-5).
+   * @param b - Blue (0-5).
+   * @returns A new Style.
+   */
+  rgb6(r: number, g: number, b: number): Style;
+  /** Sets 256-color grayscale by intensity.
+   * @param i - Intensity (0-255).
+   * @returns A new Style.
+   */
+  grayscale256(i: number): Style;
+  /** Sets 256-color grayscale by index.
+   * @param i - Index (0-23).
+   * @returns A new Style.
+   */
+  grayscale24(i: number): Style;
+  /** Sets true color by RGB.
+   * @param r - Red (0-255).
+   * @param g - Green (0-255).
+   * @param b - Blue (0-255).
+   * @returns A new Style.
+   */
+  trueColor(r: number, g: number, b: number): Style;
+  /** Sets true color grayscale.
+   * @param i - Intensity (0-255).
+   * @returns A new Style.
+   */
+  trueGrayscale(i: number): Style;
+  /** Sets true color by hex.
+   * @param hex - Hex color value.
+   * @returns A new Style.
+   */
+  hexTrueColor(hex: number): Style;
+  /** Sets color by RGB (auto-selects true color or 256-color based on depth).
+   * @returns A new Style.
+   */
+  rgb(r: number, g: number, b: number): Style;
+  /** Sets grayscale (auto-selects based on depth).
+   * @param i - Intensity.
+   * @returns A new Style.
+   */
+  grayscale(i: number): Style;
+  /** Sets color by hex (auto-selects based on depth).
+   * @param hex - Hex color value.
+   * @returns A new Style.
+   */
+  hex(hex: number): Style;
+
+  /** Switches to bright color mode. */
+  readonly bright: this;
+  /** Switches to dark (standard) color mode. */
+  readonly dark: this;
+  /** Resets to default color. */
+  readonly default: Style;
+
+  // standard color getters
+  readonly black: Style;
+  readonly red: Style;
+  readonly green: Style;
+  readonly yellow: Style;
+  readonly blue: Style;
+  readonly magenta: Style;
+  readonly cyan: Style;
+  readonly white: Style;
+  readonly brightBlack: Style;
+  readonly brightRed: Style;
+  readonly brightGreen: Style;
+  readonly brightYellow: Style;
+  readonly brightBlue: Style;
+  readonly brightMagenta: Style;
+  readonly brightCyan: Style;
+  readonly brightWhite: Style;
+  readonly darkBlack: Style;
+  readonly darkRed: Style;
+  readonly darkGreen: Style;
+  readonly darkYellow: Style;
+  readonly darkBlue: Style;
+  readonly darkMagenta: Style;
+  readonly darkCyan: Style;
+  readonly darkWhite: Style;
+  readonly gray: Style;
+  readonly grey: Style;
+}
+
+/** Chainable API for building SGR (Select Graphics Rendition) states.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Module:-style}
+ */
+export class Style {
+  /**
+   * @param initState - The initial SGR state (SgrState, string, or null for reset).
+   * @param currentState - The current SGR state (defaults to initState).
+   * @param colorDepth - Color depth (1, 4, 8, or 24; default: 24).
+   */
+  constructor(initState: SgrState | string | null, currentState?: SgrState | string | null, colorDepth?: number);
+
+  /** Creates a new Style with additional SGR commands applied.
+   * @param newCommands - SGR command(s) to add.
+   * @returns A new Style.
+   */
+  make(newCommands?: string | number | (string | number)[]): Style;
+  /** Alias for `make`. */
+  addCommands: Style['make'];
+  /** Adds SGR commands from an escape sequence string.
+   * @param commandSequence - An ANSI escape sequence string.
+   * @returns A new Style.
+   */
+  add(commandSequence: string): Style;
+  /** Combines an SGR state into the current state.
+   * @param state - State to combine (SgrState, string, or null).
+   * @returns A new Style.
+   */
+  addState(state: SgrState | string | null): Style;
+  /** Creates a new Style with the current state as the initial state.
+   * @param fn - Optional callback receiving the new Style. If provided, returns `this` instead.
+   * @returns A new Style, or `this` if `fn` is provided.
+   */
+  mark(fn?: (style: Style) => void): Style;
+  /** Returns the initial state, or passes it to a callback.
+   * @param fn - Optional callback. If provided, returns `this` instead.
+   * @returns The initial SgrState, or `this` if `fn` is provided.
+   */
+  getInitialState(fn?: (state: SgrState) => void): SgrState | Style;
+  /** Returns the current state, or passes it to a callback.
+   * @param fn - Optional callback. If provided, returns `this` instead.
+   * @returns The current SgrState, or `this` if `fn` is provided.
+   */
+  getState(fn?: (state: SgrState) => void): SgrState | Style;
+
+  /** The color depth (1, 4, 8, or 24). */
+  readonly colorDepth: number;
+  /** Creates a new Style with a different color depth.
+   * @param colorDepth - Color depth (1, 4, 8, or 24).
+   * @returns A new Style.
+   */
+  setColorDepth(colorDepth: number): Style;
+
+  /** Foreground color namespace. */
+  readonly fg: ColorMethods;
+  /** Background color namespace. */
+  readonly bg: ColorMethods;
+  /** Foreground color namespace (alias for `fg`). */
+  readonly foreground: ColorMethods;
+  /** Background color namespace (alias for `bg`). */
+  readonly background: ColorMethods;
+  /** Decoration (underline) color namespace. */
+  readonly colorDecoration: ColorMethods;
+  /** Decoration color namespace (alias for `colorDecoration`). */
+  readonly decoration: ColorMethods;
+
+  /** Reset namespace — each property returns a Style with that attribute reset. */
+  readonly reset: {
+    /** Resets all attributes. */
+    readonly all: Style;
+    readonly bold: Style;
+    readonly dim: Style;
+    readonly italic: Style;
+    readonly underline: Style;
+    readonly blink: Style;
+    readonly rapidBlink: Style;
+    readonly inverse: Style;
+    readonly hidden: Style;
+    readonly strikethrough: Style;
+    readonly curlyUnderline: Style;
+    readonly doubleUnderline: Style;
+    readonly overline: Style;
+    readonly color: Style;
+    readonly bgColor: Style;
+    readonly font: Style;
+    readonly decorationColor: Style;
+  };
+
+  /** Bright color namespace — provides bright standard colors and RGB methods. */
+  readonly bright: {
+    /** Returns the bright namespace (self-reference). */
+    readonly bright: Style['bright'];
+    /** Returns the dark namespace. */
+    readonly dark: Style['bright'];
+    readonly black: Style;
+    readonly red: Style;
+    readonly green: Style;
+    readonly yellow: Style;
+    readonly blue: Style;
+    readonly magenta: Style;
+    readonly cyan: Style;
+    readonly white: Style;
+    readonly brightBlack: Style;
+    readonly brightRed: Style;
+    readonly brightGreen: Style;
+    readonly brightYellow: Style;
+    readonly brightBlue: Style;
+    readonly brightMagenta: Style;
+    readonly brightCyan: Style;
+    readonly brightWhite: Style;
+    readonly darkBlack: Style;
+    readonly darkRed: Style;
+    readonly darkGreen: Style;
+    readonly darkYellow: Style;
+    readonly darkBlue: Style;
+    readonly darkMagenta: Style;
+    readonly darkCyan: Style;
+    readonly darkWhite: Style;
+    stdRgb(r: number, g: number, b: number): Style;
+    brightStdRgb(r: number, g: number, b: number): Style;
+    darkStdRgb(r: number, g: number, b: number): Style;
+  };
+
+  /** Dark (standard) color namespace — mirrors bright namespace structure. */
+  readonly dark: Style['bright'];
+
+  // SGR command getters
+  readonly resetAll: Style;
+  readonly resetBold: Style;
+  readonly resetDim: Style;
+  readonly bold: Style;
+  readonly dim: Style;
+  readonly italic: Style;
+  readonly underline: Style;
+  readonly blink: Style;
+  readonly rapidBlink: Style;
+  readonly inverse: Style;
+  readonly hidden: Style;
+  readonly strikethrough: Style;
+  readonly overline: Style;
+  readonly defaultFont: Style;
+  readonly resetFont: Style;
+  readonly fontGothic: Style;
+  readonly resetItalic: Style;
+  readonly resetUnderline: Style;
+  readonly resetBlink: Style;
+  readonly resetRapidBlink: Style;
+  readonly resetInverse: Style;
+  readonly resetHidden: Style;
+  readonly resetStrikethrough: Style;
+  readonly curlyUnderline: Style;
+  readonly resetCurlyUnderline: Style;
+  readonly doubleUnderline: Style;
+  readonly resetDoubleUnderline: Style;
+  readonly defaultColor: Style;
+  readonly bgDefaultColor: Style;
+  readonly resetColor: Style;
+  readonly resetBgColor: Style;
+  readonly resetOverline: Style;
+  readonly decorationDefaultColor: Style;
+  readonly resetDecorationColor: Style;
+
+  // standard color getters
+  readonly black: Style;
+  readonly red: Style;
+  readonly green: Style;
+  readonly yellow: Style;
+  readonly blue: Style;
+  readonly magenta: Style;
+  readonly cyan: Style;
+  readonly white: Style;
+  readonly brightBlack: Style;
+  readonly brightRed: Style;
+  readonly brightGreen: Style;
+  readonly brightYellow: Style;
+  readonly brightBlue: Style;
+  readonly brightMagenta: Style;
+  readonly brightCyan: Style;
+  readonly brightWhite: Style;
+  readonly darkBlack: Style;
+  readonly darkRed: Style;
+  readonly darkGreen: Style;
+  readonly darkYellow: Style;
+  readonly darkBlue: Style;
+  readonly darkMagenta: Style;
+  readonly darkCyan: Style;
+  readonly darkWhite: Style;
+  readonly bgBlack: Style;
+  readonly bgRed: Style;
+  readonly bgGreen: Style;
+  readonly bgYellow: Style;
+  readonly bgBlue: Style;
+  readonly bgMagenta: Style;
+  readonly bgCyan: Style;
+  readonly bgWhite: Style;
+  readonly bgBrightBlack: Style;
+  readonly bgBrightRed: Style;
+  readonly bgBrightGreen: Style;
+  readonly bgBrightYellow: Style;
+  readonly bgBrightBlue: Style;
+  readonly bgBrightMagenta: Style;
+  readonly bgBrightCyan: Style;
+  readonly bgBrightWhite: Style;
+  readonly bgDarkBlack: Style;
+  readonly bgDarkRed: Style;
+  readonly bgDarkGreen: Style;
+  readonly bgDarkYellow: Style;
+  readonly bgDarkBlue: Style;
+  readonly bgDarkMagenta: Style;
+  readonly bgDarkCyan: Style;
+  readonly bgDarkWhite: Style;
+  readonly gray: Style;
+  readonly grey: Style;
+  readonly bgGray: Style;
+  readonly bgGrey: Style;
+
+  // fg color methods
+  stdRgb(r: number, g: number, b: number): Style;
+  brightStdRgb(r: number, g: number, b: number): Style;
+  color(c: number): Style;
+  rgb256(r: number, g: number, b: number): Style;
+  hex256(hex: number): Style;
+  rgb6(r: number, g: number, b: number): Style;
+  grayscale256(i: number): Style;
+  grayscale24(i: number): Style;
+  trueColor(r: number, g: number, b: number): Style;
+  trueGrayscale(i: number): Style;
+  hexTrueColor(hex: number): Style;
+  rgb(r: number, g: number, b: number): Style;
+  grayscale(i: number): Style;
+  hex(hex: number): Style;
+  greyscale(i: number): Style;
+  greyscale24(i: number): Style;
+  greyscale256(i: number): Style;
+  trueGreyscale(i: number): Style;
+
+  // bg color methods
+  bgStdRgb(r: number, g: number, b: number): Style;
+  bgBrightStdRgb(r: number, g: number, b: number): Style;
+  bgColor(c: number): Style;
+  bgRgb256(r: number, g: number, b: number): Style;
+  bgHex256(hex: number): Style;
+  bgRgb6(r: number, g: number, b: number): Style;
+  bgGrayscale256(i: number): Style;
+  bgGrayscale24(i: number): Style;
+  bgTrueColor(r: number, g: number, b: number): Style;
+  bgTrueGrayscale(i: number): Style;
+  bgHexTrueColor(hex: number): Style;
+  bgRgb(r: number, g: number, b: number): Style;
+  bgGrayscale(i: number): Style;
+  bgHex(hex: number): Style;
+  bgGreyscale(i: number): Style;
+  bgGreyscale24(i: number): Style;
+  bgGreyscale256(i: number): Style;
+  bgTrueGreyscale(i: number): Style;
+
+  // decoration color methods
+  decorationStdRgb256(r: number, g: number, b: number): Style;
+  decorationBrightStdRgb256(r: number, g: number, b: number): Style;
+  decorationColor(c: number): Style;
+  decorationRgb256(r: number, g: number, b: number): Style;
+  decorationHex256(hex: number): Style;
+  decorationRgb6(r: number, g: number, b: number): Style;
+  decorationGrayscale256(i: number): Style;
+  decorationGrayscale24(i: number): Style;
+  decorationTrueColor(r: number, g: number, b: number): Style;
+  decorationTrueGrayscale(i: number): Style;
+  decorationHexTrueColor(hex: number): Style;
+  decorationRgb(r: number, g: number, b: number): Style;
+  decorationGrayscale(i: number): Style;
+  decorationHex(hex: number): Style;
+  decorationGreyscale(i: number): Style;
+  decorationGreyscale24(i: number): Style;
+  decorationGreyscale256(i: number): Style;
+  decorationTrueGreyscale(i: number): Style;
+
+  /** Wraps a string with SGR escape sequences for the current style.
+   * @param s - The string to wrap.
+   * @returns The styled string.
+   */
+  text(s: string): string;
+  /** Wraps an array of strings with SGR escape sequences for the current style.
+   * @param s - The strings to wrap.
+   * @returns The styled strings.
+   */
+  text(s: string[]): string[];
+  /** Converts the style to an SGR escape sequence string.
+   * @returns The SGR escape sequence.
+   */
+  toString(): string;
+}
+
+/** Configuration for the `s` and `c` tagged template literal functions. */
+interface BqStates {
+  /** Initial SGR state for the template. */
+  initState?: SgrState | string | null;
+  /** SGR state to set before processing. */
+  setState?: SgrState | string | null;
+}
+
+/** Tagged template literal function for styled text. Can be called directly or configured with states first. */
+type BqFunction = {
+  /** Direct tagged template usage.
+   * @param strings - Template string parts.
+   * @param args - Interpolated values.
+   * @returns The styled string.
+   */
+  (strings: TemplateStringsArray, ...args: unknown[]): string;
+  /** Configured usage — returns a tagged template function with the given states.
+   * @param states - Initial and current SGR state configuration.
+   * @returns A tagged template function.
+   */
+  (states: BqStates): (strings: TemplateStringsArray, ...args: unknown[]) => string;
+};
+
+/** Tagged template literal for styled text. Style changes persist after the string.
+ * Can also be called as `s({initState, setState})` to create a configured tagger.
+ */
+export const s: BqFunction;
+/** Tagged template literal for styled text. Automatically resets the style at the end.
+ * Can also be called as `c({initState, setState})` to create a configured tagger.
+ */
+export const c: BqFunction;
+
+/** The default Style singleton with an empty initial state. */
+export const style: Style;
+
+export default style;