@effect-tui/react 0.1.3 → 0.1.5

package/src/components/Overlay.tsx

@@ -0,0 +1,56 @@
+/**
+ * Overlay compound component - SwiftUI-style overlay layout
+ *
+ * Unlike ZStack (which sizes to MAX of all children), Overlay:
+ * 1. First child is the "base" - determines the container size
+ * 2. Overlay.Item children are overlaid without affecting measurement
+ * 3. Each Overlay.Item specifies its own alignment
+ *
+ * @example
+ * ```tsx
+ * <Overlay>
+ *   <MainContent />
+ *   <Overlay.Item alignment={{ v: "top" }}>
+ *     <Toast />
+ *   </Overlay.Item>
+ *   <Overlay.Item alignment={{ v: "bottom" }}>
+ *     <Console />
+ *   </Overlay.Item>
+ * </Overlay>
+ * ```
+ */
+
+import type { ReactNode } from "react"
+
+type HAlign = "left" | "center" | "right"
+type VAlign = "top" | "center" | "bottom"
+
+export interface OverlayProps {
+	children?: ReactNode
+	/** Fixed width */
+	width?: number
+	/** Fixed height */
+	height?: number
+}
+
+export interface OverlayItemProps {
+	/** Alignment within the overlay container */
+	alignment?: { h?: HAlign; v?: VAlign }
+	children?: ReactNode
+}
+
+function OverlayRoot({ children, ...props }: OverlayProps) {
+	return <overlay {...props}>{children}</overlay>
+}
+
+function OverlayItem({ children, alignment, ...props }: OverlayItemProps) {
+	return (
+		<overlayItem alignment={alignment} {...props}>
+			{children}
+		</overlayItem>
+	)
+}
+
+export const Overlay = Object.assign(OverlayRoot, {
+	Item: OverlayItem,
+})

package/src/components/Static.tsx

@@ -0,0 +1,68 @@
+import { useState, useMemo, useLayoutEffect, type ReactNode } from "react"
+
+export interface StaticProps<T> {
+	/**
+	 * Array of items to render. Items should only be appended, not removed or modified.
+	 * Each new item is rendered once and then "printed" to scrollback.
+	 */
+	items: T[]
+	/**
+	 * Render function for each item. Must return a keyed element.
+	 */
+	children: (item: T, index: number) => ReactNode
+}
+
+/**
+ * Renders items to terminal scrollback (inline mode only).
+ *
+ * Static content is printed once and scrolls up as new items are added,
+ * while dynamic content below it re-renders in place. Great for:
+ * - Build tools (completed steps scroll up, spinner at bottom)
+ * - Test runners (passed tests scroll up, current test at bottom)
+ * - Log viewers (history accumulates, live tail at bottom)
+ *
+ * **Important:** Static must be used at the root level of your component tree,
+ * as a direct child of a Fragment or the root element. Do not nest it inside
+ * other containers like `<box>`, `<scroll>`, or `<zstack>`.
+ *
+ * Items are append-only: removing or modifying items won't update printed output.
+ *
+ * @example
+ * ```tsx
+ * const [logs, setLogs] = useState<string[]>([])
+ *
+ * // Correct: Static at root level
+ * return (
+ *   <>
+ *     <Static items={logs}>
+ *       {(log, i) => <text key={i}>{log}</text>}
+ *     </Static>
+ *     <text>Live status: {status}</text>
+ *   </>
+ * )
+ * ```
+ */
+export function Static<T>({ items, children }: StaticProps<T>) {
+	// Track how many items we've already "printed"
+	const [printedIndex, setPrintedIndex] = useState(0)
+
+	// Only render new items (items we haven't printed yet)
+	const newItems = useMemo(() => items.slice(printedIndex), [items, printedIndex])
+
+	// After rendering, mark all items as printed
+	// useLayoutEffect ensures this happens before paint, so items unmount quickly
+	useLayoutEffect(() => {
+		if (items.length > printedIndex) {
+			setPrintedIndex(items.length)
+		}
+	}, [items.length, printedIndex])
+
+	// If no new items, render nothing
+	if (newItems.length === 0) {
+		return null
+	}
+
+	// Render new items in a vstack with the __static marker
+	// The reconciler will detect this and handle it specially
+	return <vstack __static>{newItems.map((item, i) => children(item, printedIndex + i))}</vstack>
+}

package/src/components/TextInput.tsx

@@ -0,0 +1,356 @@
+import { useState, useCallback, useEffect } from "react"
+import { Colors, type Color, displayWidth } from "@effect-tui/core"
+import { useKeyboard } from "../hooks/use-keyboard.js"
+import type { DrawContext } from "../hosts/canvas.js"
+import {
+	type TextState,
+	deleteWordBackward,
+	killToEnd,
+	killToStart,
+	deleteCharForward,
+	deleteCharBackward,
+	transposeChars,
+	insertText,
+	matchPrevWord,
+	matchNextWord,
+} from "./text-editing.js"
+
+export interface TextInputProps {
+	/** Current input value (controlled) */
+	value: string
+	/** Called when value changes */
+	onChange: (value: string) => void
+	/** Placeholder text shown when value is empty */
+	placeholder?: string
+	/** Width of the input (default: fill available) */
+	width?: number
+	/** Foreground color for text */
+	fg?: Color
+	/** Background color */
+	bg?: Color
+	/** Cursor foreground color (for block style) */
+	cursorFg?: Color
+	/** Cursor background color (for block style) or underline color (for underline style) */
+	cursorBg?: Color
+	/** Placeholder foreground color */
+	placeholderFg?: Color
+	/** Called when Enter is pressed */
+	onSubmit?: (value: string) => void
+	/** Called when Escape is pressed */
+	onCancel?: () => void
+	/** Whether the input is focused and accepts input */
+	focused?: boolean
+	/** Show cursor even when not focused */
+	showCursor?: boolean
+	/** Cursor style: block (inverted colors) or underline */
+	cursorStyle?: "block" | "underline"
+}
+
+/**
+ * A controlled text input component for terminal UIs.
+ *
+ * Features:
+ * - Arrow key navigation (Home/End for line start/end)
+ * - Word-by-word navigation with Option/Alt+Arrow
+ * - Backspace/Delete with word variants (Option+Backspace, Ctrl+W)
+ * - Emacs keybindings: Ctrl+A/E (start/end), Ctrl+B/F (back/forward char),
+ *   Ctrl+H/D (delete back/forward char), Ctrl+K/U (kill to end/start),
+ *   Ctrl+W (delete word back), Ctrl+T (transpose), Ctrl+Y (yank)
+ * - Kill ring for Ctrl+Y (yank last killed text)
+ *
+ * @example
+ * ```tsx
+ * const [text, setText] = useState("")
+ * <TextInput
+ *   value={text}
+ *   onChange={setText}
+ *   placeholder="Type here..."
+ * />
+ * ```
+ */
+export function TextInput({
+	value,
+	onChange,
+	placeholder = "",
+	width,
+	fg = Colors.brightWhite,
+	bg,
+	cursorFg = Colors.black,
+	cursorBg = Colors.brightWhite,
+	placeholderFg = Colors.gray(10),
+	onSubmit,
+	onCancel,
+	focused = true,
+	showCursor = true,
+	cursorStyle = "block",
+}: TextInputProps) {
+	const [cursorPos, setCursorPos] = useState(value.length)
+	const [killRing, setKillRing] = useState("")
+	const [scrollOffset, setScrollOffset] = useState(0)
+
+	// Keep cursor in bounds when value changes externally
+	useEffect(() => {
+		if (cursorPos > value.length) {
+			setCursorPos(value.length)
+		}
+	}, [value, cursorPos])
+
+	const handleKey = useCallback(
+		(key: { name: string; text?: string; ctrl?: boolean; meta?: boolean; shift?: boolean }) => {
+			if (!focused) return
+
+			const state: TextState = { text: value, cursor: cursorPos, killRing }
+
+			// Helper to apply an edit result
+			const applyEdit = (result: { state: TextState; changed: boolean }) => {
+				if (result.changed) {
+					onChange(result.state.text)
+					setCursorPos(result.state.cursor)
+					if (result.state.killRing !== killRing) {
+						setKillRing(result.state.killRing)
+					}
+				}
+			}
+
+			// Helper for word boundary movement
+			const moveToPrevWord = () => {
+				const beforeCursor = value.slice(0, cursorPos)
+				const match = matchPrevWord(beforeCursor)
+				setCursorPos(match ? cursorPos - match.length : 0)
+			}
+
+			const moveToNextWord = () => {
+				const afterCursor = value.slice(cursorPos)
+				const match = matchNextWord(afterCursor)
+				setCursorPos(match ? cursorPos + match.length : value.length)
+			}
+
+			switch (key.name) {
+				case "left":
+					if (key.meta) {
+						moveToPrevWord()
+					} else {
+						setCursorPos(Math.max(0, cursorPos - 1))
+					}
+					break
+
+				case "right":
+					if (key.meta) {
+						moveToNextWord()
+					} else {
+						setCursorPos(Math.min(value.length, cursorPos + 1))
+					}
+					break
+
+				case "home":
+					setCursorPos(0)
+					break
+
+				case "end":
+					setCursorPos(value.length)
+					break
+
+				case "backspace":
+					if (key.meta) {
+						// Option+Backspace: Delete to previous word boundary
+						const beforeCursor = value.slice(0, cursorPos)
+						const match = matchPrevWord(beforeCursor)
+						if (match) {
+							const newPos = cursorPos - match.length
+							onChange(value.slice(0, newPos) + value.slice(cursorPos))
+							setCursorPos(newPos)
+						} else if (cursorPos > 0) {
+							onChange(value.slice(cursorPos))
+							setCursorPos(0)
+						}
+					} else {
+						applyEdit(deleteCharBackward(state))
+					}
+					break
+
+				case "delete":
+					if (key.meta) {
+						// Option+Delete: Delete to next word boundary
+						const afterCursor = value.slice(cursorPos)
+						const match = matchNextWord(afterCursor)
+						if (match) {
+							onChange(value.slice(0, cursorPos) + value.slice(cursorPos + match.length))
+						} else if (cursorPos < value.length) {
+							onChange(value.slice(0, cursorPos))
+						}
+					} else {
+						applyEdit(deleteCharForward(state))
+					}
+					break
+
+				case "enter":
+					onSubmit?.(value)
+					break
+
+				case "escape":
+					onCancel?.()
+					break
+
+				case "char":
+				case "space":
+					if (key.ctrl && key.text) {
+						// Emacs-style keybindings
+						switch (key.text) {
+							case "a":
+								setCursorPos(0)
+								break
+							case "e":
+								setCursorPos(value.length)
+								break
+							case "b":
+								setCursorPos(Math.max(0, cursorPos - 1))
+								break
+							case "f":
+								setCursorPos(Math.min(value.length, cursorPos + 1))
+								break
+							case "d":
+								applyEdit(deleteCharForward(state))
+								break
+							case "h":
+								applyEdit(deleteCharBackward(state))
+								break
+							case "k":
+								applyEdit(killToEnd(state))
+								break
+							case "u":
+								applyEdit(killToStart(state))
+								break
+							case "w":
+								applyEdit(deleteWordBackward(state))
+								break
+							case "t":
+								applyEdit(transposeChars(state))
+								break
+							case "y":
+								applyEdit(insertText(state, killRing))
+								break
+						}
+					} else if (key.text && !key.meta) {
+						applyEdit(insertText(state, key.text))
+					}
+					break
+			}
+		},
+		[value, cursorPos, focused, onChange, onSubmit, onCancel, killRing],
+	)
+
+	useKeyboard(handleKey, { phase: "any" })
+
+	const draw = useCallback(
+		(ctx: DrawContext) => {
+			const displayText = value || placeholder
+			const isPlaceholder = !value
+			const textColor = isPlaceholder ? placeholderFg : fg
+			const maxLen = width ?? ctx.width
+
+			// Clear the line with background color
+			if (bg !== undefined) {
+				ctx.fill(0, 0, ctx.width, 1, " ", { bg })
+			}
+
+			// Calculate scroll offset to keep cursor visible
+			let effectiveScrollOffset = scrollOffset
+
+			// Compute character positions (for variable-width chars)
+			const charPositions: number[] = []
+			let totalWidth = 0
+			for (let i = 0; i < value.length; i++) {
+				charPositions.push(totalWidth)
+				totalWidth += displayWidth(value[i])
+			}
+			charPositions.push(totalWidth) // Position after last char (for cursor at end)
+
+			if (!isPlaceholder) {
+				const cursorX = charPositions[cursorPos] ?? totalWidth
+
+				// Scroll right if cursor is past visible area
+				if (cursorX >= effectiveScrollOffset + maxLen) {
+					effectiveScrollOffset = cursorX - maxLen + 1
+				}
+				// Scroll left if cursor is before visible area
+				if (cursorX < effectiveScrollOffset) {
+					effectiveScrollOffset = cursorX
+				}
+
+				// Update scroll state if changed
+				if (effectiveScrollOffset !== scrollOffset) {
+					setScrollOffset(effectiveScrollOffset)
+				}
+			} else {
+				effectiveScrollOffset = 0
+			}
+
+			// Draw text starting from scroll offset
+			let x = 0
+			for (let i = 0; i < displayText.length && x < maxLen; i++) {
+				const ch = displayText[i]
+				const charWidth = displayWidth(ch)
+				const charX = isPlaceholder ? x : charPositions[i] - effectiveScrollOffset
+
+				// Skip characters before visible area
+				if (!isPlaceholder && charPositions[i] + charWidth <= effectiveScrollOffset) {
+					continue
+				}
+				// Stop if we're past the visible area
+				if (charX >= maxLen) break
+
+				// Draw cursor at cursor position when focused
+				const isCursor = !isPlaceholder && i === cursorPos && focused && showCursor
+				if (isCursor) {
+					if (cursorStyle === "underline") {
+						ctx.text(charX, 0, ch, { fg: cursorBg, bg, underline: true })
+					} else {
+						ctx.text(charX, 0, ch, { fg: cursorFg, bg: cursorBg })
+					}
+				} else {
+					ctx.text(charX, 0, ch, { fg: textColor, bg })
+				}
+
+				x = charX + charWidth
+			}
+
+			// Draw cursor at end if cursor is at end of text
+			if (!isPlaceholder && cursorPos >= value.length && focused && showCursor) {
+				const cursorX = (charPositions[cursorPos] ?? totalWidth) - effectiveScrollOffset
+				if (cursorX >= 0 && cursorX < maxLen) {
+					if (cursorStyle === "underline") {
+						ctx.text(cursorX, 0, "_", { fg: cursorBg, bg })
+					} else {
+						ctx.text(cursorX, 0, " ", { fg: cursorFg, bg: cursorBg })
+					}
+				}
+			}
+
+			// If placeholder and focused, show cursor at start
+			if (isPlaceholder && focused && showCursor) {
+				if (cursorStyle === "underline") {
+					ctx.text(0, 0, placeholder[0] || "_", { fg: cursorBg, bg, underline: placeholder.length > 0 })
+				} else {
+					ctx.text(0, 0, placeholder[0] || " ", { fg: cursorFg, bg: cursorBg })
+				}
+			}
+		},
+		[
+			value,
+			placeholder,
+			cursorPos,
+			focused,
+			showCursor,
+			fg,
+			bg,
+			cursorFg,
+			cursorBg,
+			placeholderFg,
+			width,
+			cursorStyle,
+			scrollOffset,
+		],
+	)
+
+	return <canvas draw={draw} width={width} height={1} />
+}

package/src/components/index.ts

@@ -0,0 +1,6 @@
+export { TextInput, type TextInputProps } from "./TextInput.js"
+export { MultilineTextInput, type MultilineTextInputProps } from "./MultilineTextInput.js"
+export { Markdown, type MarkdownProps, type MarkdownTheme } from "./Markdown.js"
+export { Static, type StaticProps } from "./Static.js"
+export { Divider, type DividerProps } from "./Divider.js"
+export { Overlay, type OverlayProps, type OverlayItemProps } from "./Overlay.js"