@f5xc-salesdemos/pi-tui 14.0.2

package/src/utils.ts

@@ -0,0 +1,301 @@
+import { getDefaultTabWidth, getIndentation, sliceWithWidth } from "@f5xc-salesdemos/pi-natives";
+
+export {
+	Ellipsis,
+	extractSegments,
+	sliceWithWidth,
+	truncateToWidth,
+	wrapTextWithAnsi,
+} from "@f5xc-salesdemos/pi-natives";
+
+// Pre-allocated space buffer for padding
+const SPACE_BUFFER = " ".repeat(512);
+
+/*
+ * Replace tabs with configured spacing for consistent rendering.
+ */
+export function replaceTabs(text: string, file?: string): string {
+	return text.replaceAll("\t", " ".repeat(getIndentation(file)));
+}
+
+/**
+ * Returns a string of n spaces. Uses a pre-allocated buffer for efficiency.
+ */
+export function padding(n: number): string {
+	if (n <= 0) return "";
+	if (n <= 512) return SPACE_BUFFER.slice(0, n);
+	return " ".repeat(n);
+}
+
+// Grapheme segmenter (shared instance)
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/**
+ * Get the shared grapheme segmenter instance.
+ */
+export function getSegmenter(): Intl.Segmenter {
+	return segmenter;
+}
+
+/**
+ * Calculate the visible width of a string in terminal columns.
+ */
+function _isPrintableAscii(str: string): boolean {
+	for (let i = 0; i < str.length; i++) {
+		const code = str.charCodeAt(i);
+		if (code < 0x20 || code > 0x7e) {
+			return false;
+		}
+	}
+	return true;
+}
+
+export function visibleWidthRaw(str: string): number {
+	if (!str) {
+		return 0;
+	}
+
+	// Fast path: pure ASCII printable
+	let tabLength = 0;
+	const tabWidth = getDefaultTabWidth();
+	let isPureAscii = true;
+	for (let i = 0; i < str.length; i++) {
+		const code = str.charCodeAt(i);
+		if (code === 9) {
+			tabLength += tabWidth;
+		} else if (code < 0x20 || code > 0x7e) {
+			isPureAscii = false;
+		}
+	}
+	if (isPureAscii) {
+		return str.length + tabLength;
+	}
+	return Bun.stringWidth(str) + tabLength;
+}
+
+/**
+ * Calculate the visible width of a string in terminal columns.
+ */
+export function visibleWidth(str: string): number {
+	if (!str) return 0;
+	return visibleWidthRaw(str);
+}
+
+const makeBoolArray = (chars: string): ReadonlyArray<boolean> => {
+	const table = Array.from({ length: 128 }, () => false);
+	for (let i = 0; i < chars.length; i++) {
+		const code = chars.charCodeAt(i);
+		if (code < table.length) {
+			table[code] = true;
+		}
+	}
+	return table;
+};
+
+const ASCII_WHITESPACE = makeBoolArray("\x09\x0a\x0b\x0c\x0d\x20");
+
+/**
+ * Check if a character is whitespace.
+ */
+export function isWhitespaceChar(char: string): boolean {
+	const code = char.codePointAt(0) || 0;
+	return ASCII_WHITESPACE[code] ?? false;
+}
+
+const ASCII_PUNCTUATION = makeBoolArray("(){}[]<>.,;:'\"!?+-=*/\\|&%^$#@~`");
+
+/**
+ * Check if a character is punctuation.
+ */
+export function isPunctuationChar(char: string): boolean {
+	const code = char.codePointAt(0) || 0;
+	return ASCII_PUNCTUATION[code] ?? false;
+}
+
+export type WordNavKind = "whitespace" | "delimiter" | "cjk" | "word" | "other";
+
+const WORD_NAV_RE_WHITESPACE = /^\p{White_Space}$/u;
+const WORD_NAV_RE_PUNCT = /^\p{P}$/u;
+const WORD_NAV_RE_SYMBOL = /^\p{S}$/u;
+const WORD_NAV_RE_LETTER = /^\p{L}$/u;
+const WORD_NAV_RE_NUMBER = /^\p{N}$/u;
+const WORD_NAV_RE_HAN = /^\p{Script=Han}$/u;
+const WORD_NAV_RE_HIRAGANA = /^\p{Script=Hiragana}$/u;
+const WORD_NAV_RE_KATAKANA = /^\p{Script=Katakana}$/u;
+const WORD_NAV_RE_HANGUL = /^\p{Script=Hangul}$/u;
+
+function firstCodePointChar(str: string): string {
+	const cp = str.codePointAt(0);
+	if (cp === undefined) return "";
+	return String.fromCodePoint(cp);
+}
+
+/**
+ * Coarse Unicode-aware character classification for word navigation (Option/Alt + Left/Right).
+ * This intentionally avoids language-specific word segmentation for predictability across scripts.
+ */
+export function getWordNavKind(grapheme: string): WordNavKind {
+	if (!grapheme) return "other";
+	const ch = firstCodePointChar(grapheme);
+	if (!ch) return "other";
+	if (WORD_NAV_RE_WHITESPACE.test(ch)) return "whitespace";
+	if (WORD_NAV_RE_PUNCT.test(ch) || WORD_NAV_RE_SYMBOL.test(ch)) return "delimiter";
+	if (
+		WORD_NAV_RE_HAN.test(ch) ||
+		WORD_NAV_RE_HIRAGANA.test(ch) ||
+		WORD_NAV_RE_KATAKANA.test(ch) ||
+		WORD_NAV_RE_HANGUL.test(ch)
+	) {
+		return "cjk";
+	}
+	if (ch === "_" || WORD_NAV_RE_LETTER.test(ch) || WORD_NAV_RE_NUMBER.test(ch)) return "word";
+	return "other";
+}
+
+const WORD_NAV_JOINERS = new Set(["'", "’", "-", "‐", "‑"]);
+
+export function isWordNavJoiner(grapheme: string): boolean {
+	const ch = firstCodePointChar(grapheme);
+	return WORD_NAV_JOINERS.has(ch);
+}
+
+/**
+ * Move the cursor one "word" to the left using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export function moveWordLeft(text: string, cursor: number): number {
+	const len = text.length;
+	if (len === 0) return 0;
+	let i = Math.min(Math.max(cursor, 0), len);
+	if (i === 0) return 0;
+
+	const graphemes = [...segmenter.segment(text.slice(0, i))];
+	if (graphemes.length === 0) return 0;
+
+	// Skip trailing whitespace.
+	while (graphemes.length > 0 && getWordNavKind(graphemes[graphemes.length - 1]?.segment || "") === "whitespace") {
+		i -= graphemes.pop()?.segment.length || 0;
+	}
+	if (i === 0 || graphemes.length === 0) return i;
+
+	const kind = getWordNavKind(graphemes[graphemes.length - 1]?.segment || "");
+	if (kind === "delimiter" || kind === "cjk") {
+		while (graphemes.length > 0 && getWordNavKind(graphemes[graphemes.length - 1]?.segment || "") === kind) {
+			i -= graphemes.pop()?.segment.length || 0;
+		}
+		return i;
+	}
+
+	if (kind === "word") {
+		// Skip word run (letters/numbers/underscore), keeping common joiners inside words.
+		let hasRightWord = false;
+		while (graphemes.length > 0) {
+			const g = graphemes[graphemes.length - 1]?.segment || "";
+			const k = getWordNavKind(g);
+			if (k === "word") {
+				hasRightWord = true;
+				i -= graphemes.pop()?.segment.length || 0;
+				continue;
+			}
+			if (hasRightWord && k === "delimiter" && isWordNavJoiner(g)) {
+				const left = graphemes[graphemes.length - 2]?.segment || "";
+				if (getWordNavKind(left) === "word") {
+					i -= graphemes.pop()?.segment.length || 0;
+					continue;
+				}
+			}
+			break;
+		}
+		return i;
+	}
+
+	// Fallback: move by one grapheme.
+	i -= graphemes.pop()?.segment.length || 0;
+	return Math.max(0, i);
+}
+
+/**
+ * Move the cursor one "word" to the right using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export function moveWordRight(text: string, cursor: number): number {
+	const len = text.length;
+	if (len === 0) return 0;
+	let i = Math.min(Math.max(cursor, 0), len);
+	if (i === len) return len;
+
+	const iterator = segmenter.segment(text.slice(i))[Symbol.iterator]();
+	let next = iterator.next();
+
+	// Skip leading whitespace.
+	while (!next.done && getWordNavKind(next.value.segment) === "whitespace") {
+		i += next.value.segment.length;
+		next = iterator.next();
+	}
+	if (next.done) return i;
+
+	const firstKind = getWordNavKind(next.value.segment);
+	if (firstKind === "delimiter" || firstKind === "cjk") {
+		while (!next.done && getWordNavKind(next.value.segment) === firstKind) {
+			i += next.value.segment.length;
+			next = iterator.next();
+		}
+		return i;
+	}
+
+	if (firstKind === "word") {
+		let hasLeftWord = false;
+		while (!next.done) {
+			const segment = next.value.segment;
+			const k = getWordNavKind(segment);
+			if (k === "word") {
+				hasLeftWord = true;
+				i += segment.length;
+				next = iterator.next();
+				continue;
+			}
+			if (hasLeftWord && k === "delimiter" && isWordNavJoiner(segment)) {
+				const lookahead = iterator.next();
+				if (!lookahead.done && getWordNavKind(lookahead.value.segment) === "word") {
+					i += segment.length;
+					next = lookahead;
+					continue;
+				}
+			}
+			break;
+		}
+		return i;
+	}
+
+	// Fallback: move by one grapheme.
+	return i + next.value.segment.length;
+}
+
+/**
+ * Apply background color to a line, padding to full width.
+ *
+ * @param line - Line of text (may contain ANSI codes)
+ * @param width - Total width to pad to
+ * @param bgFn - Background color function
+ * @returns Line with background applied and padded to width
+ */
+export function applyBackgroundToLine(line: string, width: number, bgFn: (text: string) => string): string {
+	// Calculate padding needed
+	const visibleLen = visibleWidth(line);
+	const paddingNeeded = Math.max(0, width - visibleLen);
+
+	// Apply background to content + padding
+	const withPadding = line + padding(paddingNeeded);
+	return bgFn(withPadding);
+}
+
+/**
+ * Extract a range of visible columns from a line. Handles ANSI codes and wide chars.
+ *
+ * @param strict - If true, exclude wide chars at boundary that would extend past the range
+ */
+export function sliceByColumn(line: string, startCol: number, length: number, strict = false): string {
+	return sliceWithWidth(line, startCol, length, strict).text;
+}