@effect-tui/react 0.12.3 → 0.14.0

package/src/renderer-types.ts

@@ -1,6 +1,14 @@
 import type { KeyMsg, MouseMsg } from "@effect-tui/core"
 import type { HostContext, HostInstance } from "./reconciler/types.js"
 
+export type PasteMsg = {
+	type: "paste"
+	text: string
+	/** Set by renderer to allow handlers to stop further propagation. */
+	defaultPrevented?: boolean
+	preventDefault?: () => void
+}
+
 /** Minimal write stream interface for renderer output */
 export interface TuiWriteStream {
 	write(s: string): void
@@ -33,7 +41,7 @@ export interface TuiRenderer {
 	/** Subscribe to mouse events (clicks, scroll, etc.) */
 	onMouse(handler: (mouse: MouseMsg) => void): () => void
 	/** Subscribe to paste events (bracketed paste mode). */
-	onPaste?(handler: (text: string) => void): () => void
+	onPaste?(handler: (paste: PasteMsg) => void): () => void
 	/** Subscribe to resize events */
 	onResize(handler: (width: number, height: number) => void): () => void
 	/** Stop the renderer */
@@ -75,7 +83,7 @@ export interface RendererOptions {
 	mode?: "fullscreen" | "inline"
 	/** Exit the process on Ctrl+C unless preventDefault was called. Defaults to true. */
 	exitOnCtrlC?: boolean
-	/** Handle SIGINT/SIGTERM and restore terminal. Defaults to true. */
+	/** Handle SIGINT/SIGTERM and process exit cleanup. Defaults to true. */
 	handleSignals?: boolean
 	/** Exit the process after handling SIGINT/SIGTERM. Defaults to true. */
 	exitOnSignal?: boolean

package/src/renderer.ts

@@ -1,4 +1,5 @@
 import { performance } from "node:perf_hooks"
+import { fileURLToPath } from "node:url"
 import { ANSI, bufferToString, type KeyMsg, type MouseMsg } from "@effect-tui/core"
 import React, { type ReactNode } from "react"
 import { createTerminalWriter } from "./console/ConsoleCapture.js"
@@ -10,12 +11,14 @@ import type { HostContext } from "./reconciler/types.js"
 // Extracted modules
 import { FrameBuilder, RendererState } from "./renderer/core/index.js"
 import { InputProcessor } from "./renderer/input/index.js"
-import { EventBus, TerminalSetup } from "./renderer/lifecycle/index.js"
+import { EventBus, getRenderCache, TerminalSetup } from "./renderer/lifecycle/index.js"
 import { FullscreenRenderer, InlineRenderer, StaticContentRenderer } from "./renderer/modes/index.js"
 import { RendererContext } from "./renderer-context.js"
+import { startDevRuntime, type DevOptions } from "./dev.js"
 import type {
 	Container,
 	FrameStats,
+	PasteMsg,
 	RendererOptions,
 	TuiReadStream,
 	TuiRenderer,
@@ -25,7 +28,14 @@ import type {
 
 export { RendererContext, useRenderer, useTerminalSize } from "./renderer-context.js"
 // Re-export types and context for backwards compatibility
-export type { FrameStats, RendererOptions, TuiReadStream, TuiRenderer, TuiWriteStream } from "./renderer-types.js"
+export type {
+	FrameStats,
+	PasteMsg,
+	RendererOptions,
+	TuiReadStream,
+	TuiRenderer,
+	TuiWriteStream,
+} from "./renderer-types.js"
 
 type HandledSignal = "SIGINT" | "SIGTERM"
 
@@ -261,7 +271,7 @@ export function createRenderer(options?: RendererOptions): TuiRenderer {
 		},
 		onKey: (handler: (key: KeyMsg) => void) => events.onKey(handler),
 		onMouse: (handler: (mouse: MouseMsg) => void) => events.onMouse(handler),
-		onPaste: (handler: (text: string) => void) => events.onPaste(handler),
+		onPaste: (handler: (paste: PasteMsg) => void) => events.onPaste(handler),
 		onResize: (handler: (width: number, height: number) => void) => events.onResize(handler),
 		onFrameStats: (handler: (stats: FrameStats) => void) => events.onFrameStats(handler),
 		stop() {
@@ -360,11 +370,11 @@ export function createRenderer(options?: RendererOptions): TuiRenderer {
 		renderer.stop()
 	}
 
-	// Handle normal process exit (synchronous - runs before exit completes)
-	onExit = () => cleanup()
-	process.on("exit", onExit)
-
 	if (handleSignals) {
+		// Handle normal process exit (synchronous - runs before exit completes)
+		onExit = () => cleanup()
+		process.on("exit", onExit)
+
 		// Handle SIGINT (Ctrl+C from shell, not from TUI input) and SIGTERM
 		onSignal = (signal: NodeJS.Signals) => {
 			cleanup()
@@ -445,11 +455,31 @@ export interface RenderInstance {
 	quit(code?: number): void
 }
 
-export function render(element: ReactNode, options?: RendererOptions): RenderInstance {
-	const renderer = createRenderer(options)
-	const root = createRoot(renderer)
+export type ImportMetaLike = {
+	url: string
+	main?: boolean
+}
+
+export type RenderOptions = RendererOptions &
+	DevOptions & {
+		/** Enable dev runtime (HMR, console overlay, remote control). */
+		dev?: boolean
+		/** Required when passing options. */
+		importMeta: ImportMetaLike
+	}
 
-	root.render(element, true)
+const stripQuery = (url: string): string => url.split("?")[0]
+
+const createRenderInstance = (
+	renderer: TuiRenderer,
+	root: Root,
+	element: ReactNode,
+	stop: () => void,
+	skipInitialRender = false,
+): RenderInstance => {
+	if (!skipInitialRender) {
+		root.render(element, true)
+	}
 
 	let resolved = false
 	let resolveExit: (() => void) | null = null
@@ -472,7 +502,7 @@ export function render(element: ReactNode, options?: RendererOptions): RenderIns
 		process.off("exit", onExit)
 		if (!resolved) {
 			resolved = true
-			renderer.stop()
+			stop()
 			resolveExit?.()
 		}
 	}
@@ -482,10 +512,10 @@ export function render(element: ReactNode, options?: RendererOptions): RenderIns
 		root.render(next)
 	}
 
-	// Clean quit function - renderer.stop() + process.exit()
+	// Clean quit function - stop() + process.exit()
 	// The createRenderer exit handler will also run, but it's idempotent
 	const quit = (code = 0) => {
-		renderer.stop()
+		stop()
 		requestExit(code)
 	}
 
@@ -498,3 +528,44 @@ export function render(element: ReactNode, options?: RendererOptions): RenderIns
 		quit,
 	}
 }
+
+export function render(element: ReactNode, options?: RenderOptions): RenderInstance {
+	if (options && !options.importMeta) {
+		throw new Error("[effect-tui] render(..., options) requires { importMeta: import.meta }")
+	}
+
+	if (!options?.dev) {
+		const renderer = createRenderer(options)
+		const root = createRoot(renderer)
+		return createRenderInstance(renderer, root, element, () => renderer.stop())
+	}
+
+	const importMeta = options.importMeta
+	if (!importMeta) {
+		throw new Error("[effect-tui] render(..., { dev: true, importMeta }) is required in dev mode")
+	}
+
+	const baseUrl = stripQuery(importMeta.url)
+	const renderCache = getRenderCache<RenderInstance>()
+	const cached = renderCache.get(baseUrl)
+	if (cached) return cached
+
+	const renderer = createRenderer(options)
+	const root = createRoot(renderer)
+	const entryPath = fileURLToPath(new URL(baseUrl))
+
+	const devRuntime = startDevRuntime(entryPath, renderer, root, options)
+
+	const instance = createRenderInstance(
+		renderer,
+		root,
+		element,
+		() => {
+			void devRuntime.stop()
+		},
+		true,
+	)
+
+	renderCache.set(baseUrl, instance)
+	return instance
+}

package/src/shortcuts.ts

@@ -0,0 +1,180 @@
+import type { KeyMsg, KeyName } from "@effect-tui/core"
+
+export type ShortcutSpec = {
+	key: KeyName | "char"
+	text?: string
+	ctrl?: boolean
+	meta?: boolean
+	shift?: boolean
+}
+
+export type Shortcut = string | ShortcutSpec
+
+export type ShortcutMatchOptions = {
+	/** Require that unspecified modifiers are not pressed (default: true). */
+	exact?: boolean
+}
+
+type ParsedShortcut = {
+	name: KeyName | "char"
+	text?: string
+	ctrl?: boolean
+	meta?: boolean
+	shift?: boolean
+}
+
+const parseCache = new Map<string, ParsedShortcut>()
+
+const normalizeKeyToken = (token: string): { name: KeyName | "char"; text?: string } => {
+	const lower = token.toLowerCase()
+	switch (lower) {
+		case "enter":
+		case "return":
+			return { name: "enter" }
+		case "esc":
+		case "escape":
+			return { name: "escape" }
+		case "tab":
+			return { name: "tab" }
+		case "shift-tab":
+			return { name: "shift-tab" }
+		case "backspace":
+		case "bs":
+			return { name: "backspace" }
+		case "delete":
+		case "del":
+			return { name: "delete" }
+		case "home":
+		case "end":
+		case "up":
+		case "down":
+		case "left":
+		case "right":
+		case "pageup":
+		case "pagedown":
+		case "insert":
+			return { name: lower as KeyName }
+		case "space":
+		case "spacebar":
+			return { name: "char", text: " " }
+		default:
+			if (token.length === 1) {
+				return { name: "char", text: token }
+			}
+			return { name: "char", text: token }
+	}
+}
+
+const parseShortcutString = (shortcut: string): ParsedShortcut => {
+	const cached = parseCache.get(shortcut)
+	if (cached) return cached
+
+	const raw = shortcut.trim()
+	if (!raw) {
+		throw new Error("[effect-tui] Shortcut cannot be empty")
+	}
+
+	const parts = raw.split("+").map((part) => part.trim()).filter(Boolean)
+	let keyToken: string | null = null
+	let ctrl: boolean | undefined
+	let meta: boolean | undefined
+	let shift: boolean | undefined
+
+	for (const part of parts) {
+		const lower = part.toLowerCase()
+		switch (lower) {
+			case "ctrl":
+			case "control":
+				ctrl = true
+				break
+			case "meta":
+			case "cmd":
+			case "command":
+			case "alt":
+			case "option":
+				meta = true
+				break
+			case "shift":
+				shift = true
+				break
+			default:
+				keyToken = part
+				break
+		}
+	}
+
+	if (!keyToken) {
+		throw new Error(`[effect-tui] Shortcut missing key: \"${shortcut}\"`)
+	}
+
+	const normalized = normalizeKeyToken(keyToken)
+	const parsed: ParsedShortcut = {
+		name: normalized.name,
+		text: normalized.text,
+		ctrl,
+		meta,
+		shift,
+	}
+	parseCache.set(shortcut, parsed)
+	return parsed
+}
+
+const parseShortcut = (shortcut: Shortcut): ParsedShortcut => {
+	if (typeof shortcut === "string") {
+		return parseShortcutString(shortcut)
+	}
+	return {
+		name: shortcut.key,
+		text: shortcut.text,
+		ctrl: shortcut.ctrl,
+		meta: shortcut.meta,
+		shift: shortcut.shift,
+	}
+}
+
+const matchesModifiers = (key: KeyMsg, parsed: ParsedShortcut, exact: boolean): boolean => {
+	const keyCtrl = !!key.ctrl
+	const keyMeta = !!key.meta
+	const keyShift = !!key.shift || key.name === "shift-tab"
+
+	if (parsed.ctrl !== undefined) {
+		if (parsed.ctrl !== keyCtrl) return false
+	} else if (exact && keyCtrl) {
+		return false
+	}
+
+	if (parsed.meta !== undefined) {
+		if (parsed.meta !== keyMeta) return false
+	} else if (exact && keyMeta) {
+		return false
+	}
+
+	if (parsed.shift !== undefined) {
+		if (parsed.shift !== keyShift) return false
+	} else if (exact && keyShift) {
+		return false
+	}
+
+	return true
+}
+
+export function isKey(key: KeyMsg, shortcut: Shortcut, options: ShortcutMatchOptions = {}): boolean {
+	const parsed = parseShortcut(shortcut)
+	const effective = parsed.name === "char" && parsed.shift ? { ...parsed, shift: undefined } : parsed
+	const exact = options.exact ?? true
+
+	if (!matchesModifiers(key, effective, exact)) return false
+
+	if (effective.name === "char") {
+		if (key.name !== "char") return false
+		return effective.text === undefined ? true : key.text === effective.text
+	}
+
+	if (effective.name === "tab" && effective.shift) {
+		if (key.name === "shift-tab") return true
+		if (key.name !== "tab") return false
+		return !!key.shift
+	}
+
+	return key.name === effective.name
+}

package/src/test/mock-streams.ts

@@ -112,12 +112,9 @@ export function encodeKey(key: KeyMsg): Buffer {
 		case "tab":
 			return Buffer.from([0x09])
 		case "enter":
-		case "return":
 			return Buffer.from([0x0d])
 		case "backspace":
 			return Buffer.from([0x7f])
-		case "space":
-			return Buffer.from([0x20])
 	}
 
 	// Regular character

package/src/test/render-tui.ts

@@ -64,6 +64,7 @@ export function renderTUI(element: ReactElement, options?: RenderTUIOptions): Re
 		stdin: stdin as any,
 		manualMode: true,
 		skipTerminalSetup: true,
+		handleSignals: false,
 		mode: options?.mode,
 		diff: options?.diff,
 	})

package/src/utils/alignment.ts

@@ -48,3 +48,21 @@ export function alignInRect(
 
 	return { x, y }
 }
+
+/**
+ * Calculate a child rect aligned within a container rect, clamped to container size.
+ */
+export function alignedChildRect(
+	rect: Rect,
+	size: Size,
+	hAlign: HAlign = "center",
+	vAlign: VAlign = "center",
+): Rect {
+	const { x, y } = alignInRect(rect, size, hAlign, vAlign)
+	return {
+		x,
+		y,
+		w: Math.min(rect.w, size.w),
+		h: Math.min(rect.h, size.h),
+	}
+}

package/src/utils/index.ts

@@ -1,4 +1,4 @@
-export { alignInRect, type HAlign, type VAlign } from "./alignment.js"
+export { alignInRect, alignedChildRect, type HAlign, type VAlign } from "./alignment.js"
 export {
 	type BorderChars,
 	type BorderKind,
@@ -11,6 +11,7 @@ export {
 export { type FlexAlignment, type FlexAxis, type FlexMeasureResult, layoutFlex, measureFlex } from "./flex-layout.js"
 export { type Padding, type PaddingInput, resolvePadding } from "./padding.js"
 export {
+	fillRectWithInheritedBg,
 	resolveBgStyle,
 	resolveInheritedBgStyle,
 	type StyleInput,
@@ -19,3 +20,4 @@ export {
 	styleSpecFromProps,
 	toColorValue,
 } from "./styles.js"
+export { wrapSpans } from "./text-wrap.js"

package/src/utils/styles.ts

@@ -2,7 +2,8 @@
  * Style utilities for building palette-compatible style objects.
  */
 
-import { type Color, type ColorValue, type Palette, parseColor, type StyleSpec } from "@effect-tui/core"
+import type { CellBuffer, Color, ColorValue, Palette, StyleSpec } from "@effect-tui/core"
+import { parseColor } from "@effect-tui/core"
 
 export interface StyleOptions {
 	fg?: ColorValue
@@ -64,6 +65,7 @@ export function resolveBgStyle(palette: Palette, bg?: Color): { value?: ColorVal
 
 import { getInheritedBg } from "../hosts/base.js"
 import type { HostInstance } from "../reconciler/types.js"
+import type { Rect } from "../reconciler/types.js"
 
 /**
  * Resolve background style, inheriting from parent if not explicitly set.
@@ -77,3 +79,18 @@ export function resolveInheritedBgStyle(
 	const bg = explicitBg ?? getInheritedBg(parent)
 	return resolveBgStyle(palette, bg)
 }
+
+/**
+ * Fill a rect with background color, inheriting from parent if needed.
+ */
+export function fillRectWithInheritedBg(
+	buffer: CellBuffer,
+	palette: Palette,
+	rect: Rect,
+	explicitBg: Color | undefined,
+	parent: HostInstance | null,
+): void {
+	if (rect.w <= 0 || rect.h <= 0) return
+	const { styleId } = resolveInheritedBgStyle(palette, explicitBg, parent)
+	buffer.fillRect(rect.x, rect.y, rect.w, rect.h, " ".codePointAt(0)!, styleId)
+}

package/src/utils/text-wrap.ts

@@ -0,0 +1,66 @@
+import { displayWidth } from "@effect-tui/core"
+
+type SpanLike = { text: string }
+
+/**
+ * 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[][] {
+	const lines: T[][] = [[]]
+	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 : [[]]
+}