@visulima/string/dist/get-string-truncated-width.d.ts

Functions for manipulating strings.

/**
* Configuration options for string width calculation and truncation.
* @example
* ```typescript
* // Basic usage with defaults
* const options: StringTruncatedWidthOptions = {};
*
* // Custom character widths
* const options: StringTruncatedWidthOptions = {
*   regularWidth: 2,
*   emojiWidth: 3,
*   tabWidth: 4
* };
*
* // Truncation settings
* const options: StringTruncatedWidthOptions = {
*   limit: 10,
*   ellipsis: '...',
*   ellipsisWidth: 3
* };
* ```
*/
interface StringTruncatedWidthOptions {
  /**
  * Count [ambiguous width characters](https://www.unicode.org/reports/tr11/#Ambiguous) as having narrow width (count of 1 (regular)) instead of wide width (count of 2 (wide)).
  * @default false
  */
  ambiguousIsNarrow?: boolean;
  /**
  * Width of ANSI escape sequences
  * @default 0
  */
  ansiWidth?: number;
  /**
  * Width of control characters
  * @default 0
  */
  controlWidth?: number;
  /**
  * Whether to count ANSI escape codes in width calculation
  * @default false
  */
  countAnsiEscapeCodes?: boolean;
  /**
  * Text appended to the string when it is truncated
  * @default ''
  */
  ellipsis?: string;
  /**
  * Width of the ellipsis string
  * If not provided, it will be calculated using getStringTruncatedWidth
  */
  ellipsisWidth?: number;
  /**
  * Width of emoji characters
  * @default 2
  */
  emojiWidth?: number;
  /**
  * Width of full-width characters
  * @default 2
  */
  fullWidth?: number;
  /**
  * Width of half-width characters
  * @default 1
  */
  halfWidth?: number;
  /**
  * Maximum width limit for the string
  * @default Infinity
  */
  limit?: number;
  /**
  * Width of regular characters
  * @default 1
  */
  regularWidth?: number;
  /**
  * Width of tab characters
  * @default 8
  */
  tabWidth?: number;
  /**
  * Width of wide characters
  * @default 2
  */
  wideWidth?: number;
}
/**
* Result object returned by getStringTruncatedWidth containing width calculation and the truncation details.
* @example
* ```typescript
* // No truncation
* const result: StringTruncatedWidthResult = {
*   width: 5,        // Total visual width
*   truncated: false, // String was not truncated
*   ellipsed: false, // No ellipsis added
*   index: 5,        // Full string length
* };
*
* // With truncation
* const result: StringTruncatedWidthResult = {
*   width: 8,        // Width including ellipsis
*   truncated: true,  // String was truncated
*   ellipsed: true,   // Ellipsis was added
*   index: 5,         // Truncation point
* };
* ```
*/
interface StringTruncatedWidthResult {
  /**
  * Whether an ellipsis was added
  */
  ellipsed: boolean;
  /**
  * The index at which truncation occurred (if any)
  */
  index: number;
  /**
  * Whether the string was truncated
  */
  truncated: boolean;
  /**
  * The calculated width of the string
  */
  width: number;
}
/**
* Calculate the visual width of a string with optional truncation, handling various Unicode character types.
* @example
* ```typescript
* // Basic width calculation
* getStringTruncatedWidth('hello');
* // => { width: 5, truncated: false, ellipsed: false, index: 5 }
*
* // With truncation
* getStringTruncatedWidth('hello world', {
*   limit: 8,
*   ellipsis: '...'
* });
* // => { width: 8, truncated: true, ellipsed: true, index: 5 }
*
* // With custom character widths
* getStringTruncatedWidth('あいう', {
*   fullWidth: 2,
*   ambiguousIsNarrow: true
* });
* // => { width: 6, truncated: false, ellipsed: false, index: 3 }
*
* // With combining characters
* getStringTruncatedWidth('e\u0301'); // Latin e with acute
* // => { width: 1, truncated: false, ellipsed: false, index: 2 }
*
* getStringTruncatedWidth('ก\u0e31'); // Thai character with vowel mark
* // => { width: 1, truncated: false, ellipsed: false, index: 2 }
* ```
*
* Features:
* - Full Unicode support including combining marks from various scripts
* - Accurate width calculation for emoji sequences
* - ANSI escape code handling
* - Customizable character widths
* - Optional string truncation with ellipsis
* @param input The string to calculate the width for
* @param options Configuration options for width calculation and truncation
* @returns Result object containing:
* - width: The calculated visual width of the string
* - truncated: Whether the string was truncated
* - ellipsed: Whether an ellipsis was added
* - index: The index at which truncation occurred (if any)
*/
declare const getStringTruncatedWidth: (input: string, options?: StringTruncatedWidthOptions) => StringTruncatedWidthResult;
export { StringTruncatedWidthOptions, StringTruncatedWidthResult, getStringTruncatedWidth };