@effect-tui/react 0.4.2 → 0.6.0

package/jsx-runtime.ts

@@ -11,7 +11,7 @@ import type { OverlayProps } from "./src/hosts/overlay.js"
 import type { OverlayItemProps } from "./src/hosts/overlay-item.js"
 import type { ScrollProps } from "./src/hosts/scroll.js"
 import type { SpacerProps } from "./src/hosts/spacer.js"
-import type { TextProps } from "./src/hosts/text.js"
+import type { StyledTextProps, TextProps } from "./src/hosts/text.js"
 import type { VStackProps } from "./src/hosts/vstack.js"
 import type { ZStackProps } from "./src/hosts/zstack.js"
 
@@ -40,6 +40,7 @@ export declare namespace JSX {
 	export interface IntrinsicElements extends React.JSX.IntrinsicElements {
 		// Our custom TUI elements (override any React conflicts)
 		text: TextProps & { children?: React.ReactNode }
+		styledtext: StyledTextProps
 		spacer: SpacerProps
 		vstack: VStackProps & { children?: React.ReactNode; __static?: boolean }
 		hstack: HStackProps & { children?: React.ReactNode }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effect-tui/react",
-	"version": "0.4.2",
+	"version": "0.6.0",
 	"description": "React bindings for @effect-tui/core",
 	"type": "module",
 	"files": [
@@ -83,7 +83,7 @@
 		"prepublishOnly": "bun run typecheck && bun run build"
 	},
 	"dependencies": {
-		"@effect-tui/core": "^0.4.2",
+		"@effect-tui/core": "^0.6.0",
 		"@effect/platform": "^0.94.0",
 		"@effect/platform-bun": "^0.87.0",
 		"@effect/rpc": "^0.73.0",

package/src/components/ListView.tsx

@@ -0,0 +1,112 @@
+// ListView.tsx — Selection-aware scrolling list with scroll-into-view behavior
+import type { ReactNode } from "react"
+import { useEffect, useRef } from "react"
+import { useScroll } from "../hooks/use-scroll.js"
+
+export interface ListViewProps<T> {
+	/** Items to render */
+	items: readonly T[]
+	/** Currently selected index */
+	selectedIndex: number
+	/** Render function for each item */
+	renderItem: (item: T, index: number, isSelected: boolean) => ReactNode
+	/** Extract unique key for each item */
+	keyExtractor: (item: T, index: number) => string | number
+	/** Height of each item in rows (default: 1) */
+	itemHeight?: number
+	/** Padding rows to keep around selected item (default: 0) */
+	scrollPadding?: number
+	/** Show scrollbar (default: true) */
+	showScrollbar?: boolean
+	/** Empty state content when items is empty */
+	emptyContent?: ReactNode
+}
+
+/**
+ * A scrolling list view with selection and scroll-into-view behavior.
+ *
+ * Features:
+ * - Automatically scrolls to keep selected item visible when selection changes
+ * - Supports mouse wheel scrolling with macOS-style acceleration
+ * - Shows a scroll bar when content overflows
+ *
+ * Keyboard navigation should be handled by the parent component - update
+ * `selectedIndex` and ListView will scroll to keep it visible.
+ *
+ * @example
+ * ```tsx
+ * const [selectedIndex, setSelectedIndex] = useState(0)
+ *
+ * // Handle keyboard in parent
+ * useKeyboard((key) => {
+ *   if (key.name === "down" || key.text === "j") {
+ *     setSelectedIndex(i => Math.min(items.length - 1, i + 1))
+ *   }
+ *   if (key.name === "up" || key.text === "k") {
+ *     setSelectedIndex(i => Math.max(0, i - 1))
+ *   }
+ * })
+ *
+ * return (
+ *   <ListView
+ *     items={cards}
+ *     selectedIndex={selectedIndex}
+ *     renderItem={(card, i, isSelected) => (
+ *       <CardListItem card={card} isSelected={isSelected} />
+ *     )}
+ *     keyExtractor={(card) => card.id}
+ *   />
+ * )
+ * ```
+ */
+export function ListView<T>({
+	items,
+	selectedIndex,
+	renderItem,
+	keyExtractor,
+	itemHeight = 1,
+	scrollPadding = 0,
+	showScrollbar = true,
+	emptyContent,
+}: ListViewProps<T>) {
+	const { scrollProps, scrollToVisible } = useScroll({
+		enableKeyboard: false, // Parent handles keyboard for selection
+		enableMouseWheel: true, // Free scroll with wheel
+	})
+
+	// Track previous selection to detect changes
+	const prevSelectedRef = useRef(selectedIndex)
+
+	// Scroll to keep selection visible when it changes
+	useEffect(() => {
+		if (selectedIndex !== prevSelectedRef.current) {
+			prevSelectedRef.current = selectedIndex
+			scrollToVisible(selectedIndex, itemHeight, scrollPadding)
+		}
+	}, [selectedIndex, itemHeight, scrollPadding, scrollToVisible])
+
+	// Also scroll on initial render if selection is not 0
+	useEffect(() => {
+		if (selectedIndex > 0) {
+			scrollToVisible(selectedIndex, itemHeight, scrollPadding)
+		}
+		// Only run on mount
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [])
+
+	if (items.length === 0 && emptyContent) {
+		return <>{emptyContent}</>
+	}
+
+	return (
+		<scroll {...scrollProps} showScrollbar={showScrollbar}>
+			<vstack>
+				{items.map((item, index) => (
+					<vstack key={keyExtractor(item, index)}>
+						{renderItem(item, index, index === selectedIndex)}
+					</vstack>
+				))}
+			</vstack>
+		</scroll>
+	)
+}

package/src/components/Markdown.tsx

@@ -1,6 +1,7 @@
 import { Colors, type ColorValue } from "@effect-tui/core"
 import type { BundledLanguage, BundledTheme } from "shiki"
 import { CodeBlock } from "../codeblock.js"
+import type { StyledSpan } from "../hosts/text.js"
 
 export interface MarkdownTheme {
 	/** Header colors by level (h1, h2, h3+) */
@@ -54,6 +55,8 @@ export interface MarkdownProps {
 	codeTheme?: BundledTheme
 	/** Enable text wrapping (default: false, text is truncated) */
 	wrap?: boolean
+	/** Max width for wrapping styled paragraphs. Required when wrap=true for proper inline formatting. */
+	maxWidth?: number
 }
 
 // Parsed markdown elements
@@ -226,42 +229,68 @@ function parseMarkdown(content: string): MdElement[] {
 }
 
 /**
- * Render inline spans as text elements.
- * Uses <text wrap> for host-level wrapping when wrap=true.
+ * Convert markdown spans to styled spans for StyledTextHost
  */
-function renderSpans(spans: MdSpan[], theme: Required<MarkdownTheme>, wrap = false) {
+function toStyledSpans(spans: MdSpan[], theme: Required<MarkdownTheme>): StyledSpan[] {
+	const result: StyledSpan[] = []
+	for (const span of spans) {
+		switch (span.type) {
+			case "text":
+				result.push({ text: span.text, fg: theme.text })
+				break
+			case "bold":
+				result.push({ text: span.text, fg: theme.bold, bold: true })
+				break
+			case "italic":
+				result.push({ text: span.text, fg: theme.italic, italic: true })
+				break
+			case "code":
+				result.push({ text: span.text, fg: theme.code, bg: theme.codeBg })
+				break
+			case "link":
+				result.push({ text: span.text, fg: theme.link })
+				result.push({ text: ` (${span.url})`, fg: theme.linkUrl })
+				break
+		}
+	}
+	return result
+}
+
+/**
+ * Render inline spans as text elements (used for non-wrapping contexts like lists).
+ * For wrapping paragraphs, use <styledtext> instead.
+ */
+function renderSpans(spans: MdSpan[], theme: Required<MarkdownTheme>) {
 	return spans.map((span, i) => {
 		switch (span.type) {
 			case "text":
 				return (
-					<text key={i} fg={theme.text} wrap={wrap}>
+					<text key={i} fg={theme.text}>
 						{span.text}
 					</text>
 				)
 			case "bold":
 				return (
-					<text key={i} fg={theme.bold} bold wrap={wrap}>
+					<text key={i} fg={theme.bold} bold>
 						{span.text}
 					</text>
 				)
 			case "italic":
 				return (
-					<text key={i} fg={theme.italic} italic wrap={wrap}>
+					<text key={i} fg={theme.italic} italic>
 						{span.text}
 					</text>
 				)
 			case "code":
 				return (
-					<text key={i} fg={theme.code} bg={theme.codeBg} wrap={wrap}>
+					<text key={i} fg={theme.code} bg={theme.codeBg}>
 						{span.text}
 					</text>
 				)
 			case "link":
 				return (
 					<hstack key={i}>
-						<text fg={theme.link} wrap={wrap}>
-							{span.text}
-						</text>
+						<text fg={theme.link}>{span.text}</text>
 						<text fg={theme.linkUrl}>{" ("}</text>
 						<text fg={theme.linkUrl}>{span.url}</text>
 						<text fg={theme.linkUrl}>{")"}</text>
@@ -327,7 +356,11 @@ export function Markdown({ content, theme: themeOverrides, codeTheme = "nord", w
 							</text>
 						)
 					case "paragraph":
-						return <hstack key={i}>{renderSpans(el.spans, theme, wrap)}</hstack>
+						// Use styledtext for proper wrapping of styled inline text
+						if (wrap) {
+							return <styledtext key={i} spans={toStyledSpans(el.spans, theme)} wrap />
+						}
+						return <hstack key={i}>{renderSpans(el.spans, theme)}</hstack>
 					case "code":
 						return (
 							<CodeBlock
@@ -343,7 +376,11 @@ export function Markdown({ content, theme: themeOverrides, codeTheme = "nord", w
 						return (
 							<hstack key={i}>
 								<text fg={theme.quoteBorder}>{"│ "}</text>
-								{renderSpans(el.spans, theme, wrap)}
+								{wrap ? (
+									<styledtext spans={toStyledSpans(el.spans, theme)} wrap />
+								) : (
+									renderSpans(el.spans, theme)
+								)}
 							</hstack>
 						)
 					case "ul":
@@ -352,7 +389,11 @@ export function Markdown({ content, theme: themeOverrides, codeTheme = "nord", w
 								{el.items.map((item, j) => (
 									<hstack key={j}>
 										<text fg={theme.listMarker}>{"  • "}</text>
-										{renderSpans(item, theme, wrap)}
+										{wrap ? (
+											<styledtext spans={toStyledSpans(item, theme)} wrap />
+										) : (
+											renderSpans(item, theme)
+										)}
 									</hstack>
 								))}
 							</vstack>
@@ -363,7 +404,11 @@ export function Markdown({ content, theme: themeOverrides, codeTheme = "nord", w
 								{el.items.map((item, j) => (
 									<hstack key={j}>
 										<text fg={theme.listMarker}>{`  ${el.start + j}. `}</text>
-										{renderSpans(item, theme, wrap)}
+										{wrap ? (
+											<styledtext spans={toStyledSpans(item, theme)} wrap />
+										) : (
+											renderSpans(item, theme)
+										)}
 									</hstack>
 								))}
 							</vstack>

package/src/components/index.ts

@@ -1,4 +1,5 @@
 export { Divider, type DividerProps } from "./Divider.js"
+export { ListView, type ListViewProps } from "./ListView.js"
 export { Markdown, type MarkdownProps, type MarkdownTheme } from "./Markdown.js"
 export { MultilineTextInput, type MultilineTextInputProps } from "./MultilineTextInput.js"
 export { Overlay, type OverlayItemProps, type OverlayProps } from "./Overlay.js"

package/src/hosts/index.ts

@@ -8,7 +8,7 @@ import { OverlayHost } from "./overlay.js"
 import { OverlayItemHost } from "./overlay-item.js"
 import { ScrollHost } from "./scroll.js"
 import { SpacerHost } from "./spacer.js"
-import { RawTextHost, TextHost } from "./text.js"
+import { RawTextHost, StyledTextHost, TextHost } from "./text.js"
 import { VStackHost } from "./vstack.js"
 import { ZStackHost } from "./zstack.js"
 
@@ -22,7 +22,7 @@ export { OverlayItemHost, type OverlayItemProps } from "./overlay-item.js"
 export { ScrollHost, type ScrollProps } from "./scroll.js"
 export { SingleChildHost } from "./single-child.js"
 export { SpacerHost, type SpacerProps } from "./spacer.js"
-export { RawTextHost, TextHost, type TextProps } from "./text.js"
+export { RawTextHost, StyledTextHost, TextHost, type StyledSpan, type StyledTextProps, type TextProps } from "./text.js"
 export { VStackHost, type VStackProps } from "./vstack.js"
 export { ZStackHost, type ZStackProps } from "./zstack.js"
 
@@ -30,6 +30,7 @@ export { ZStackHost, type ZStackProps } from "./zstack.js"
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const hostRegistry: Record<string, new (props: any, ctx: HostContext) => BaseHost> = {
 	text: TextHost,
+	styledtext: StyledTextHost,
 	spacer: SpacerHost,
 	vstack: VStackHost,
 	hstack: HStackHost,

package/src/hosts/text.ts

@@ -235,3 +235,172 @@ export class RawTextHost extends BaseHost {
 		// Raw text has no props
 	}
 }
+
+// ============================================================================
+// Styled Text Host - for inline formatted text that wraps as a unit
+// ============================================================================
+
+/** A span of text with optional styling */
+export interface StyledSpan {
+	text: string
+	fg?: Color
+	bg?: Color
+	bold?: boolean
+	italic?: boolean
+	underline?: boolean
+}
+
+export interface StyledTextProps extends CommonProps {
+	/** Array of styled text spans */
+	spans: StyledSpan[]
+	/** Default text color */
+	fg?: Color
+	/** Default background color */
+	bg?: Color
+	/** If true, wrap text to multiple lines */
+	wrap?: boolean
+}
+
+/**
+ * Host for rendering multiple styled spans that wrap as a unit.
+ * Unlike using hstack with multiple text elements, this properly
+ * wraps styled inline text across lines.
+ */
+export class StyledTextHost extends BaseHost {
+	spans: StyledSpan[] = []
+	fg?: Color
+	bg?: Color
+	wrap = false
+
+	// Cache wrapped lines - each line is an array of spans
+	private cachedLines: StyledSpan[][] | null = null
+	private cachedWidth = 0
+
+	constructor(props: StyledTextProps, ctx: HostContext) {
+		super("styledtext", props, ctx)
+		this.updateProps(props)
+	}
+
+	measure(maxW: number, maxH: number): Size {
+		if (this.wrap) {
+			this.cachedLines = this.wrapSpans(this.spans, maxW)
+			this.cachedWidth = maxW
+			const h = Math.min(this.cachedLines.length, maxH)
+			const w = this.cachedLines.reduce(
+				(max, line) => Math.max(max, line.reduce((sum, span) => sum + displayWidth(span.text), 0)),
+				0,
+			)
+			return { w, h }
+		}
+
+		// Non-wrap mode: single line, may truncate
+		const totalWidth = this.spans.reduce((sum, span) => sum + displayWidth(span.text), 0)
+		return { w: Math.min(totalWidth, maxW), h: 1 }
+	}
+
+	/** Wrap spans into lines, breaking at word boundaries */
+	private wrapSpans(spans: StyledSpan[], maxWidth: number): StyledSpan[][] {
+		const lines: StyledSpan[][] = [[]]
+		let lineWidth = 0
+
+		for (const span of spans) {
+			// Split span text into words (keeping whitespace as separate tokens)
+			const tokens = span.text.split(/(\s+)/)
+
+			for (const token of tokens) {
+				if (!token) continue
+				const tokenWidth = displayWidth(token)
+				const isWhitespace = /^\s+$/.test(token)
+
+				if (lineWidth + tokenWidth <= maxWidth) {
+					// Token fits on current line
+					lines[lines.length - 1].push({ ...span, text: token })
+					lineWidth += tokenWidth
+				} else if (isWhitespace) {
+					// Skip whitespace at line break
+					continue
+				} else if (tokenWidth <= maxWidth) {
+					// Start new line with this token
+					lines.push([{ ...span, text: token }])
+					lineWidth = tokenWidth
+				} else {
+					// Token is longer than maxWidth - break by character
+					let charLine = ""
+					let charLineWidth = 0
+					for (const ch of token) {
+						const chWidth = displayWidth(ch)
+						if (lineWidth + charLineWidth + chWidth > maxWidth && (charLine || lineWidth > 0)) {
+							if (charLine) {
+								lines[lines.length - 1].push({ ...span, text: charLine })
+							}
+							lines.push([])
+							lineWidth = 0
+							charLine = ch
+							charLineWidth = chWidth
+						} else {
+							charLine += ch
+							charLineWidth += chWidth
+						}
+					}
+					if (charLine) {
+						lines[lines.length - 1].push({ ...span, text: charLine })
+						lineWidth += charLineWidth
+					}
+				}
+			}
+		}
+
+		// Remove empty lines at the end
+		while (lines.length > 0 && lines[lines.length - 1].length === 0) {
+			lines.pop()
+		}
+
+		return lines.length > 0 ? lines : [[]]
+	}
+
+	override layout(rect: Rect): void {
+		super.layout(rect)
+	}
+
+	render(buffer: CellBuffer, palette: Palette): void {
+		if (!this.rect) return
+
+		const inheritedBg = this.bg ?? getInheritedBg(this.parent)
+
+		// Get lines to render
+		const lines =
+			this.wrap && this.cachedLines && this.cachedWidth === this.rect.w
+				? this.cachedLines
+				: this.wrap
+					? this.wrapSpans(this.spans, this.rect.w)
+					: [this.spans]
+
+		for (let y = 0; y < Math.min(lines.length, this.rect.h); y++) {
+			let x = this.rect.x
+			for (const span of lines[y]) {
+				const styleId = styleIdFromProps(palette, {
+					fg: span.fg ?? this.fg,
+					bg: span.bg ?? inheritedBg,
+					bold: span.bold,
+					italic: span.italic,
+					underline: span.underline,
+				})
+				const availableWidth = this.rect.w - (x - this.rect.x)
+				if (availableWidth <= 0) break
+				const textWidth = Math.min(displayWidth(span.text), availableWidth)
+				buffer.drawText(x, this.rect.y + y, span.text, styleId, textWidth)
+				x += displayWidth(span.text)
+			}
+		}
+	}
+
+	override updateProps(props: Record<string, unknown>): void {
+		super.updateProps(props)
+		this.spans = (props.spans as StyledSpan[] | undefined) ?? []
+		this.fg = props.fg as Color | undefined
+		this.bg = props.bg as Color | undefined
+		this.wrap = Boolean(props.wrap)
+		// Invalidate cache when props change
+		this.cachedLines = null
+	}
+}

package/src/index.ts

@@ -6,6 +6,8 @@ export { CodeBlock } from "./codeblock.js"
 // Input components
 export {
 	type ColumnProps,
+	ListView,
+	type ListViewProps,
 	Markdown,
 	type MarkdownProps,
 	type MarkdownTheme,