@effect-tui/react 0.1.7 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effect-tui/react",
-	"version": "0.1.7",
+	"version": "0.2.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.1.7",
+		"@effect-tui/core": "^0.2.0",
 		"@effect/platform": "^0.94.0",
 		"@effect/platform-bun": "^0.87.0",
 		"@effect/rpc": "^0.73.0",
@@ -110,6 +110,7 @@
 		}
 	},
 	"devDependencies": {
+		"@effect-tui/emulator": "workspace:^",
 		"@effect/opentelemetry": "^0.60.0",
 		"@effect/vitest": "^0.27.0",
 		"@opentelemetry/api": "^1.9.0",

package/src/hooks/index.ts

@@ -3,5 +3,6 @@ export type { UseKeyboardOptions } from "./use-keyboard.js"
 export { useMouse } from "./use-mouse.js"
 export type { UseMouseOptions } from "./use-mouse.js"
 export { usePaste } from "./use-paste.js"
+export { useQuit } from "./use-quit.js"
 export { useScroll } from "./use-scroll.js"
 export type { UseScrollOptions, UseScrollReturn, ScrollState } from "./use-scroll.js"

package/src/hooks/use-quit.ts

@@ -0,0 +1,33 @@
+import { useCallback } from "react"
+import { useRenderer } from "../renderer-context.js"
+
+/**
+ * Hook that returns a quit function for cleanly exiting the TUI application.
+ *
+ * This ensures terminal state is properly restored (alternate buffer exit,
+ * cursor shown, raw mode disabled) before the process exits.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const quit = useQuit()
+ *
+ *   useKeyboard((key) => {
+ *     if (key.text === "q") quit()
+ *   })
+ *
+ *   return <text>Press q to quit</text>
+ * }
+ * ```
+ */
+export function useQuit(): (code?: number) => void {
+	const renderer = useRenderer()
+
+	return useCallback(
+		(code = 0) => {
+			renderer.stop()
+			process.exit(code)
+		},
+		[renderer],
+	)
+}

package/src/hosts/base.ts

@@ -32,9 +32,11 @@ export abstract class BaseHost implements HostInstance {
 	children: HostInstance[] = []
 	rect: Rect | null = null
 
-	// Common flex props
-	flexGrow = 0
-	flexShrink = 1
+	// Greedy layout - expands to fill remaining space
+	// undefined = not greedy (hug content)
+	// true or 1 = 1 share
+	// number > 1 = proportionally more shares
+	greedy: boolean | number | undefined = undefined
 
 	// ─────────────────────────────────────────────────────────────
 	// Frame constraints (like SwiftUI's .frame modifier)
@@ -65,7 +67,20 @@ export abstract class BaseHost implements HostInstance {
 	abstract render(buffer: CellBuffer, palette: Palette): void
 
 	layout(rect: Rect): void {
-		this.rect = rect
+		// Apply frame constraints to the assigned rect
+		let { w, h } = rect
+
+		// Fixed width/height override
+		if (this.frameWidth !== undefined) w = this.frameWidth
+		if (this.frameHeight !== undefined) h = this.frameHeight
+
+		// Apply min/max clamps
+		if (this.frameMinWidth !== undefined) w = Math.max(this.frameMinWidth, w)
+		if (this.frameMaxWidth !== undefined) w = Math.min(this.frameMaxWidth, w)
+		if (this.frameMinHeight !== undefined) h = Math.max(this.frameMinHeight, h)
+		if (this.frameMaxHeight !== undefined) h = Math.min(this.frameMaxHeight, h)
+
+		this.rect = { x: rect.x, y: rect.y, w, h }
 	}
 
 	/**
@@ -144,8 +159,23 @@ export abstract class BaseHost implements HostInstance {
 	}
 
 	updateProps(props: Record<string, unknown>): void {
-		this.flexGrow = (props.flexGrow as number | undefined) ?? 0
-		this.flexShrink = (props.flexShrink as number | undefined) ?? 1
+		// Greedy layout - reset to undefined unless explicitly set
+		// Subclasses like Spacer/Scroll set their own default before calling super
+		if ("greedy" in props) {
+			const greedy = props.greedy
+			if (greedy === true) {
+				this.greedy = 1
+			} else if (typeof greedy === "number") {
+				this.greedy = greedy
+			} else {
+				// greedy is false, undefined, or null
+				this.greedy = undefined
+			}
+		} else {
+			// No greedy prop - reset to default (undefined)
+			// Subclasses like Spacer/Scroll handle this before calling super
+			this.greedy = undefined
+		}
 
 		// Frame constraints - only accept valid numbers (ignore strings like "100%")
 		this.frameWidth = typeof props.width === "number" ? props.width : undefined

package/src/hosts/flex-container.ts

@@ -84,12 +84,14 @@ export class FlexContainerHost<A extends FlexAxis> extends BaseHost {
 
 	override layout(rect: Rect): void {
 		super.layout(rect)
+		// Use this.rect (constrained) not rect (raw input)
+		if (!this.rect) return
 		const stretchCross = this.axis === "vertical" ? this.alignment === "leading" : this.alignment === "top"
 		layoutFlex(
 			this.axis,
 			this.layoutChildren,
 			this.cachedSizes,
-			rect,
+			this.rect,
 			this.spacing,
 			toFlexAlignment(this.axis, this.alignment),
 			stretchCross,

package/src/hosts/scroll.ts

@@ -38,6 +38,9 @@ export class ScrollHost extends SingleChildHost {
 	bg?: Color
 	showScrollbar = true
 	sticky = false
+
+	// Scroll is greedy by default - expands to fill available space
+	override greedy: boolean | number | undefined = 1
 	onContentSize?: (width: number, height: number) => void
 	onViewportSize?: (width: number, height: number) => void
 	onEffectiveOffset?: (offset: number) => void
@@ -85,8 +88,12 @@ export class ScrollHost extends SingleChildHost {
 			// Note: onContentSize callback is deferred to layout() to keep measure() pure
 		}
 
-		// Scroll container is greedy - takes all available space (after constraints)
-		return this.constrainResult({ w: constrained.w, h: constrained.h })
+		// Report natural content size (clamped to constrained bounds)
+		// Greedy expansion happens in layout phase via layoutFlex
+		const naturalW = Math.min(this.contentWidth, constrained.w)
+		const naturalH = Math.min(this.contentHeight, constrained.h)
+
+		return this.constrainResult({ w: naturalW, h: naturalH })
 	}
 
 	override layout(rect: Rect): void {
@@ -239,6 +246,10 @@ export class ScrollHost extends SingleChildHost {
 
 	override updateProps(props: Record<string, unknown>): void {
 		super.updateProps(props)
+		// Scroll is greedy by default unless explicitly set to false
+		if (!("greedy" in props)) {
+			this.greedy = 1
+		}
 		if (props.axis !== undefined) this.axis = (props.axis as ScrollProps["axis"]) ?? "vertical"
 		if (props.offset !== undefined) this.offset = props.offset as number
 		if (props.offsetX !== undefined) this.offsetX = props.offsetX as number

package/src/hosts/spacer.ts

@@ -13,15 +13,16 @@ export class SpacerHost extends BaseHost {
 	minWidth = 0
 	minHeight = 0
 
+	// Spacers are greedy by default
+	override greedy: boolean | number | undefined = 1
+
 	constructor(props: SpacerProps, ctx: HostContext) {
-		// Spacers have flexGrow=1 by default
-		const propsWithDefaults = { flexGrow: 1, ...props }
-		super("spacer", propsWithDefaults, ctx)
-		this.updateProps(propsWithDefaults)
+		super("spacer", props, ctx)
+		this.updateProps(props)
 	}
 
 	measure(_maxW: number, _maxH: number): Size {
-		// Spacers have no natural size, they expand via flexGrow
+		// Spacers have no natural size, they expand via greedy
 		return { w: this.minWidth, h: this.minHeight }
 	}
 
@@ -34,10 +35,11 @@ export class SpacerHost extends BaseHost {
 	}
 
 	override updateProps(props: Record<string, unknown>): void {
-		// Keep spacer default flexGrow=1 unless explicitly provided
-		const flexGrow = props.flexGrow as number | undefined
-		const propsWithDefaults = flexGrow === undefined ? { ...props, flexGrow: 1 } : props
-		super.updateProps(propsWithDefaults)
+		super.updateProps(props)
+		// Spacer is greedy by default unless explicitly set to false
+		if (!("greedy" in props)) {
+			this.greedy = 1
+		}
 		if (props.minWidth !== undefined) this.minWidth = props.minWidth as number
 		if (props.minHeight !== undefined) this.minHeight = props.minHeight as number
 	}

package/src/reconciler/types.ts

@@ -92,10 +92,15 @@ export interface HostContext {
  * With the constraint, it reports exactly 10, so spacer gets the rest.
  */
 export interface CommonProps {
-	/** Flex grow factor - how much extra space this view takes (default: 0) */
-	flexGrow?: number
-	/** Flex shrink factor - how much this view shrinks when space is tight (default: 1) */
-	flexShrink?: number
+	/**
+	 * Greedy layout - element expands to fill remaining space.
+	 * - `true` or `1`: takes 1 share of remaining space
+	 * - number > 1: takes proportionally more (e.g., `greedy={2}` gets 2x space)
+	 * - `false` or undefined: hugs content (default)
+	 *
+	 * Scroll and Spacer are greedy by default.
+	 */
+	greedy?: boolean | number
 
 	// ─────────────────────────────────────────────────────────────
 	// Frame constraints (like SwiftUI's .frame modifier)

package/src/renderer/input/InputProcessor.ts

@@ -7,6 +7,7 @@ export interface InputProcessorConfig {
 	dispatchPaste: (text: string) => void
 	flushSync: <T>(fn: () => T) => T
 	onInputProcessed: () => void
+	onQuit?: () => void // Called instead of process.exit() for proper cleanup
 }
 
 /**
@@ -86,7 +87,11 @@ export class InputProcessor {
 				// Default Ctrl+C handling - exit unless user called preventDefault()
 				// Only match Ctrl+C (not Ctrl+Shift+C which should be available for copy)
 				if (this.config.exitOnCtrlC && !wrapped.defaultPrevented && event.ctrl && !event.shift && event.text === "c") {
-					process.exit(0)
+					if (this.config.onQuit) {
+						this.config.onQuit()
+					} else {
+						process.exit(0)
+					}
 				}
 			}
 		}

package/src/renderer/lifecycle/TerminalSetup.ts

@@ -70,36 +70,47 @@ export class TerminalSetup {
 	/**
 	 * Restore terminal to normal state.
 	 * Call this when stopping the renderer.
+	 * Uses a single write call to ensure atomic output and reliable flushing.
 	 */
 	teardown(): void {
 		if (this.config.skipTerminalSetup) return
 
-		if (this.config.mode === "fullscreen") {
-			this.stdout.write(Terminal.exitFullscreen)
-		} else {
-			// Re-enable reflow on exit
-			this.stdout.write(ANSI.reflow.enable)
-			this.stdout.write("\r\n")
+		// Disable raw mode FIRST - this is critical for proper terminal restoration
+		// Must happen before writing escape sequences so the terminal processes them correctly
+		if (this.stdin.isTTY && this.stdin.setRawMode) {
+			this.stdin.setRawMode(false)
 		}
 
-		if (this.config.enablePaste) {
-			this.stdout.write(ANSI.paste.disable)
+		// Build all escape sequences into a single string for atomic write
+		// This ensures all sequences are flushed together before process exit
+		let output = ""
+
+		// Disable enhanced keyboard protocols first
+		if (this.config.enableKittyKeyboard !== false) {
+			output += ANSI.keyboard.disable
+			output += ANSI.modifyOtherKeys.disable
 		}
 
 		if (this.config.enableMouse) {
-			this.stdout.write(ANSI.mouse.disable)
+			output += ANSI.mouse.disable
 		}
 
-		// Disable enhanced keyboard protocols
-		if (this.config.enableKittyKeyboard !== false) {
-			this.stdout.write(ANSI.keyboard.disable)
-			this.stdout.write(ANSI.modifyOtherKeys.disable)
+		if (this.config.enablePaste) {
+			output += ANSI.paste.disable
 		}
 
-		this.stdout.write(Terminal.showCursor)
-
-		if (this.stdin.isTTY && this.stdin.setRawMode) {
-			this.stdin.setRawMode(false)
+		// Exit fullscreen or re-enable reflow
+		if (this.config.mode === "fullscreen") {
+			output += Terminal.exitFullscreen
+		} else {
+			output += ANSI.reflow.enable
+			output += "\r\n"
 		}
+
+		// Always show cursor at the end
+		output += Terminal.showCursor
+
+		// Single atomic write - more reliable for process exit scenarios
+		this.stdout.write(output)
 	}
 }

package/src/renderer.ts

@@ -71,6 +71,11 @@ export function createRenderer(options?: RendererOptions): TuiRenderer {
 		onInputProcessed: () => {
 			if (!manualMode) renderFrame()
 		},
+		onQuit: () => {
+			// Clean up terminal state before exiting
+			renderer.stop()
+			process.exit(0)
+		},
 	})
 
 	// The render frame logic
@@ -300,6 +305,27 @@ export function createRenderer(options?: RendererOptions): TuiRenderer {
 		}, frameMs)
 	}
 
+	// Process exit handlers - ensure terminal is restored on any exit
+	// These handlers are critical for proper cleanup when process.exit() is called
+	let cleanedUp = false
+	const cleanup = () => {
+		if (cleanedUp) return
+		cleanedUp = true
+		renderer.stop()
+	}
+
+	// Handle normal process exit (synchronous - runs before exit completes)
+	const onExit = () => cleanup()
+	process.on("exit", onExit)
+
+	// Handle SIGINT (Ctrl+C from shell, not from TUI input) and SIGTERM
+	const onSignal = () => {
+		cleanup()
+		process.exit(0)
+	}
+	process.on("SIGINT", onSignal)
+	process.on("SIGTERM", onSignal)
+
 	;(renderer as TuiRendererInternal)._container = null
 	return renderer
 }
@@ -365,6 +391,8 @@ export interface RenderInstance {
 	rerender(element: ReactNode): void
 	unmount(): void
 	waitUntilExit(): Promise<void>
+	/** Cleanly exit the application, restoring terminal state before process.exit() */
+	quit(code?: number): void
 }
 
 export function render(element: ReactNode, options?: RendererOptions): RenderInstance {
@@ -383,18 +411,20 @@ export function render(element: ReactNode, options?: RendererOptions): RenderIns
 		}
 	})
 
+	// Resolve the exit promise on process exit
+	// Note: Terminal cleanup is handled by createRenderer's exit handlers
 	const onExit = () => {
-		if (!resolved) {
-			renderer.stop()
-			resolveExit?.()
-		}
+		resolveExit?.()
 	}
 	process.once("exit", onExit)
 
 	const unmount = () => {
 		process.off("exit", onExit)
-		renderer.stop()
-		resolveExit?.()
+		if (!resolved) {
+			resolved = true
+			renderer.stop()
+			resolveExit?.()
+		}
 	}
 
 	const rerender = (next: ReactNode) => {
@@ -402,11 +432,19 @@ export function render(element: ReactNode, options?: RendererOptions): RenderIns
 		root.render(next)
 	}
 
+	// Clean quit function - renderer.stop() + process.exit()
+	// The createRenderer exit handler will also run, but it's idempotent
+	const quit = (code = 0) => {
+		renderer.stop()
+		process.exit(code)
+	}
+
 	return {
 		renderer,
 		root,
 		rerender,
 		unmount,
 		waitUntilExit: () => exitPromise,
+		quit,
 	}
 }

package/src/test/render-tui.ts

@@ -7,6 +7,8 @@ import { MockStdout, MockStdin, stripAnsi, getVisibleLines } from "./mock-stream
 export interface RenderTUIOptions {
 	width?: number
 	height?: number
+	mode?: "fullscreen" | "inline"
+	diff?: boolean
 }
 
 export interface RenderTUIResult {
@@ -26,6 +28,8 @@ export interface RenderTUIResult {
 	stdout: MockStdout
 	/** Access mock stdin for advanced input simulation */
 	stdin: MockStdin
+	/** Access renderer for advanced assertions */
+	renderer: ReturnType<typeof createRenderer>
 	/** Resize the terminal */
 	resize(width: number, height: number): void
 }
@@ -60,6 +64,8 @@ export function renderTUI(element: ReactElement, options?: RenderTUIOptions): Re
 		stdin: stdin as any,
 		manualMode: true,
 		skipTerminalSetup: true,
+		mode: options?.mode,
+		diff: options?.diff,
 	})
 
 	const root = createRoot(renderer)
@@ -106,6 +112,7 @@ export function renderTUI(element: ReactElement, options?: RenderTUIOptions): Re
 
 		stdout,
 		stdin,
+		renderer,
 
 		resize(w: number, h: number) {
 			stdout.resize(w, h)

package/src/utils/flex-layout.ts

@@ -53,6 +53,19 @@ export function measureFlex(
 	return { sizes, totalSize }
 }
 
+/**
+ * Get the greedy weight for a child.
+ * - undefined/false = 0 (not greedy, hugs content)
+ * - true = 1
+ * - number = that weight
+ */
+function getGreedyWeight(child: HostInstance): number {
+	const greedy = (child as BaseHost).greedy
+	if (greedy === undefined || greedy === false) return 0
+	if (greedy === true) return 1
+	return greedy
+}
+
 /**
  * Layout children along a flex axis using cached sizes.
  */
@@ -67,17 +80,17 @@ export function layoutFlex(
 ): void {
 	// Calculate totals
 	let totalNaturalMain = 0
-	let totalFlexGrow = 0
+	let totalGreedyWeight = 0
 	const totalSpacing = Math.max(0, (children.length - 1) * spacing)
 
 	for (let i = 0; i < children.length; i++) {
 		const child = children[i]
 		const size = cachedSizes[i] ?? child.measure(rect.w, rect.h)
 		totalNaturalMain += mainSize(axis, size)
-		totalFlexGrow += (child as BaseHost).flexGrow ?? 0
+		totalGreedyWeight += getGreedyWeight(child)
 	}
 
-	// Calculate extra space to distribute
+	// Calculate extra space to distribute to greedy children
 	const availableMain = mainDim(axis, rect)
 	const extraSpace = Math.max(0, availableMain - totalNaturalMain - totalSpacing)
 
@@ -89,10 +102,10 @@ export function layoutFlex(
 	for (let i = 0; i < children.length; i++) {
 		const child = children[i]
 		const size = cachedSizes[i] ?? { w: 0, h: 0 }
-		const flexGrow = (child as BaseHost).flexGrow ?? 0
-		const flexExtra = totalFlexGrow > 0 ? (extraSpace * flexGrow) / totalFlexGrow : 0
+		const greedyWeight = getGreedyWeight(child)
+		const greedyExtra = totalGreedyWeight > 0 ? (extraSpace * greedyWeight) / totalGreedyWeight : 0
 
-		const childMainDim = mainSize(axis, size) + flexExtra
+		const childMainDim = mainSize(axis, size) + greedyExtra
 		const childCrossDim = crossSize(axis, size)
 
 		// Calculate cross position based on alignment