@effect-tui/react 0.16.0 → 2.0.0

package/src/utils/index.ts

@@ -20,5 +20,19 @@ export {
 	styleSpecFromProps,
 	toColorValue,
 } from "./styles.js"
-export { wrapSpans, wrapText } from "./text-wrap.js"
+export {
+	buildTextLayout,
+	type LineLayout,
+	type TextLayout,
+	type TextLayoutOptions,
+	type VisualLine,
+} from "./text-layout.js"
+export {
+	splitSpansByNewline,
+	spansDisplayWidth,
+	wrapLineWithRanges,
+	wrapSpans,
+	wrapSpansByLine,
+	wrapText,
+} from "./text-wrap.js"
 export { isWhitespace, matchNextWord, matchPrevWord, splitWords } from "./word-boundaries.js"

package/src/utils/text-layout.ts

@@ -0,0 +1,65 @@
+import { displayWidth, graphemes } from "@effect-tui/core"
+import { wrapLineWithRanges } from "./text-wrap.js"
+
+export type VisualLine = {
+	logicalRow: number
+	startCol: number
+	endCol: number
+	text: string
+}
+
+export type LineLayout = {
+	graphemeList: string[]
+	widths: number[]
+	prefixWidths: number[]
+	visualLines: VisualLine[]
+}
+
+export type TextLayout = {
+	lines: LineLayout[]
+	allVisualLines: VisualLine[]
+}
+
+export type TextLayoutOptions = {
+	wrap?: boolean
+	preserveWhitespace?: boolean
+}
+
+export function buildTextLayout(text: string, maxWidth: number, options?: TextLayoutOptions): TextLayout {
+	const logicalLines = text.split("\n")
+	const wrap = options?.wrap ?? true
+	const preserveWhitespace = options?.preserveWhitespace ?? false
+	const lines: LineLayout[] = []
+	const allVisualLines: VisualLine[] = []
+
+	for (let row = 0; row < logicalLines.length; row++) {
+		const line = logicalLines[row]
+		const graphemeList = graphemes(line)
+		const widths = graphemeList.map((g) => displayWidth(g))
+		const prefixWidths: number[] = [0]
+		for (let i = 0; i < widths.length; i++) {
+			prefixWidths.push(prefixWidths[i] + widths[i])
+		}
+
+		const visualLines: VisualLine[] = wrap
+			? wrapLineWithRanges(line, maxWidth, { preserveWhitespace }).map((range) => ({
+					logicalRow: row,
+					startCol: range.startCol,
+					endCol: range.endCol,
+					text: range.text,
+				}))
+			: [
+					{
+						logicalRow: row,
+						startCol: 0,
+						endCol: graphemeList.length,
+						text: line,
+					},
+				]
+
+		lines.push({ graphemeList, widths, prefixWidths, visualLines })
+		allVisualLines.push(...visualLines)
+	}
+
+	return { lines, allVisualLines }
+}

package/src/utils/text-wrap.ts

@@ -1,4 +1,4 @@
-import { displayWidth } from "@effect-tui/core"
+import { displayWidth, graphemes } from "@effect-tui/core"
 import { isWhitespace, splitWords } from "./word-boundaries.js"
 
 type SpanLike = { text: string }
@@ -6,8 +6,11 @@ type SpanLike = { text: string }
 type TokenSpec<T> = {
 	text: string
 	width: number
+	graphemeCount: number
 	isWhitespace: boolean
-	make: (text: string) => T
+	startCol?: number
+	segments?: string[]
+	make: (text: string, segmentStart: number, segmentEnd: number) => T
 }
 
 type LineToken<T> = {
@@ -16,8 +19,13 @@ type LineToken<T> = {
 	isWhitespace: boolean
 }
 
-type WrapOptions = {
+export type WrapOptions = {
 	trimTrailingWhitespace?: boolean
+	preserveWhitespace?: boolean
+}
+
+export function spansDisplayWidth<T extends { text: string }>(spans: T[]): number {
+	return spans.reduce((sum, span) => sum + displayWidth(span.text), 0)
 }
 
 function wrapTokens<T>(tokens: TokenSpec<T>[], maxWidth: number, options?: WrapOptions): T[][] {
@@ -40,8 +48,15 @@ function wrapTokens<T>(tokens: TokenSpec<T>[], maxWidth: number, options?: WrapO
 		lineWidth = 0
 	}
 
-	const addToken = (token: TokenSpec<T>, text: string, width: number, isWhitespace: boolean) => {
-		lines[lines.length - 1].push({ value: token.make(text), width, isWhitespace })
+	const addToken = (
+		token: TokenSpec<T>,
+		text: string,
+		width: number,
+		isWhitespace: boolean,
+		segmentStart: number,
+		segmentEnd: number,
+	) => {
+		lines[lines.length - 1].push({ value: token.make(text, segmentStart, segmentEnd), width, isWhitespace })
 		lineWidth += width
 	}
 
@@ -51,11 +66,12 @@ function wrapTokens<T>(tokens: TokenSpec<T>[], maxWidth: number, options?: WrapO
 		const isWs = token.isWhitespace
 
 		if (lineWidth + tokenWidth <= maxWidth) {
-			addToken(token, token.text, tokenWidth, isWs)
+			const start = token.startCol ?? 0
+			addToken(token, token.text, tokenWidth, isWs, start, start + token.graphemeCount)
 			continue
 		}
 
-		if (isWs) {
+		if (isWs && !options?.preserveWhitespace) {
 			// Skip whitespace at line break
 			continue
 		}
@@ -65,7 +81,8 @@ function wrapTokens<T>(tokens: TokenSpec<T>[], maxWidth: number, options?: WrapO
 			if (lines[lines.length - 1].length > 0) {
 				startNewLine()
 			}
-			addToken(token, token.text, tokenWidth, isWs)
+			const start = token.startCol ?? 0
+			addToken(token, token.text, tokenWidth, isWs, start, start + token.graphemeCount)
 			continue
 		}
 
@@ -75,26 +92,32 @@ function wrapTokens<T>(tokens: TokenSpec<T>[], maxWidth: number, options?: WrapO
 			startNewLine()
 		}
 
+		const segments = token.segments ?? Array.from(token.text)
+		const tokenStart = token.startCol ?? 0
 		let segment = ""
 		let segmentWidth = 0
+		let segmentStartOffset = 0
+		let segmentOffset = 0
 
-		for (const ch of token.text) {
+		for (const ch of segments) {
 			const chWidth = displayWidth(ch)
 			if (lineWidth + segmentWidth + chWidth > maxWidth && (segment || lineWidth > 0)) {
 				if (segment) {
-					addToken(token, segment, segmentWidth, false)
+					addToken(token, segment, segmentWidth, false, tokenStart + segmentStartOffset, tokenStart + segmentOffset)
 				}
 				startNewLine()
 				segment = ch
 				segmentWidth = chWidth
+				segmentStartOffset = segmentOffset
 			} else {
 				segment += ch
 				segmentWidth += chWidth
 			}
+			segmentOffset += 1
 		}
 
 		if (segment) {
-			addToken(token, segment, segmentWidth, false)
+			addToken(token, segment, segmentWidth, false, tokenStart + segmentStartOffset, tokenStart + segmentOffset)
 		}
 	}
 
@@ -106,25 +129,121 @@ function wrapTokens<T>(tokens: TokenSpec<T>[], maxWidth: number, options?: WrapO
 	return lines.length > 0 ? lines.map((line) => line.map((token) => token.value)) : [[]]
 }
 
+export type WrappedLineRange = {
+	text: string
+	startCol: number
+	endCol: number
+}
+
+/**
+ * Wrap a single line into visual lines with grapheme ranges.
+ */
+export function wrapLineWithRanges(line: string, maxWidth: number, options?: WrapOptions): WrappedLineRange[] {
+	if (line === "") {
+		return [{ text: "", startCol: 0, endCol: 0 }]
+	}
+
+	const tokens: Array<TokenSpec<WrappedLineRange>> = []
+	let col = 0
+	for (const token of splitWords(line)) {
+		if (!token) continue
+		const segments = graphemes(token)
+		const graphemeCount = segments.length
+		const startCol = col
+		tokens.push({
+			text: token,
+			width: displayWidth(token),
+			graphemeCount,
+			startCol,
+			segments,
+			isWhitespace: isWhitespace(token),
+			make: (text, segmentStart, segmentEnd) => ({ text, startCol: segmentStart, endCol: segmentEnd }),
+		})
+		col += graphemeCount
+	}
+
+	const wrapped = wrapTokens(tokens, maxWidth, options)
+	const lines: WrappedLineRange[] = []
+
+	for (const lineTokens of wrapped) {
+		if (lineTokens.length === 0) {
+			lines.push({ text: "", startCol: 0, endCol: 0 })
+			continue
+		}
+		lines.push({
+			text: lineTokens.map((token) => token.text).join(""),
+			startCol: lineTokens[0].startCol,
+			endCol: lineTokens[lineTokens.length - 1].endCol,
+		})
+	}
+
+	return lines.length > 0 ? lines : [{ text: "", startCol: 0, endCol: 0 }]
+}
+
 /**
  * Wrap spans into lines, breaking at word boundaries.
  * Preserves span styling by cloning span objects with updated text.
  */
-export function wrapSpans<T extends SpanLike>(spans: T[], maxWidth: number): T[][] {
+export function wrapSpans<T extends SpanLike>(spans: T[], maxWidth: number, options?: WrapOptions): T[][] {
 	const tokens: Array<TokenSpec<T>> = []
 	for (const span of spans) {
 		for (const token of splitWords(span.text)) {
 			if (!token) continue
+			const segments = graphemes(token)
 			tokens.push({
 				text: token,
 				width: displayWidth(token),
+				graphemeCount: segments.length,
+				segments,
 				isWhitespace: isWhitespace(token),
 				make: (text) => ({ ...span, text }),
 			})
 		}
 	}
 
-	return wrapTokens(tokens, maxWidth)
+	return wrapTokens(tokens, maxWidth, options)
+}
+
+/**
+ * Split spans into logical lines at newline boundaries.
+ * Preserves empty lines.
+ */
+export function splitSpansByNewline<T extends SpanLike>(spans: T[]): T[][] {
+	const lines: T[][] = [[]]
+
+	for (const span of spans) {
+		if (!span.text) continue
+		const parts = span.text.split("\n")
+		for (let i = 0; i < parts.length; i++) {
+			if (i > 0) {
+				lines.push([])
+			}
+			const part = parts[i]
+			if (part) {
+				lines[lines.length - 1].push({ ...span, text: part })
+			}
+		}
+	}
+
+	return lines.length > 0 ? lines : [[]]
+}
+
+/**
+ * Wrap spans per logical line (newline-aware).
+ */
+export function wrapSpansByLine<T extends SpanLike>(spans: T[], maxWidth: number, options?: WrapOptions): T[][] {
+	const logicalLines = splitSpansByNewline(spans)
+	const lines: T[][] = []
+
+	for (const line of logicalLines) {
+		if (line.length === 0) {
+			lines.push([])
+			continue
+		}
+		lines.push(...wrapSpans(line, maxWidth, options))
+	}
+
+	return lines.length > 0 ? lines : [[]]
 }
 
 /**
@@ -141,9 +260,12 @@ export function wrapText(text: string, maxWidth: number): string[] {
 		const tokens: Array<TokenSpec<string>> = []
 		for (const token of splitWords(rawLine)) {
 			if (!token) continue
+			const segments = graphemes(token)
 			tokens.push({
 				text: token,
 				width: displayWidth(token),
+				graphemeCount: segments.length,
+				segments,
 				isWhitespace: isWhitespace(token),
 				make: (segment) => segment,
 			})