Raxol.UI.TextMeasure (Raxol v2.6.0)

Single source of truth for text display width measurement.

Delegates to CharacterHandling in raxol_terminal when available, falls back to String.length for environments without the terminal package.

All layout, rendering, and text wrapping code should use this module instead of String.length for display-width-sensitive calculations.

Summary

Returns the display width of a single grapheme (1 or 2 columns).

Returns the display width of a string in terminal columns.

Splits a string at a given display width boundary.

@spec char_display_width(String.t()) :: 1 | 2

Returns the display width of a single grapheme (1 or 2 columns).

@spec display_width(String.t()) :: non_neg_integer()

Returns the display width of a string in terminal columns.

CJK characters, fullwidth symbols, and emoji count as 2 columns. Combining characters count as 0 columns. All other characters count as 1 column.

Delegates to CharacterHandling (raxol_terminal) for correct Unicode width calculation. Falls back to String.length if unavailable.

@spec split_at_display_width(String.t(), non_neg_integer()) ::
  {String.t(), String.t()}

Splits a string at a given display width boundary.

Returns {left, right} where left fits within width display columns. Will not split a double-width character in half.