@effect-tui/react 0.12.3 → 0.13.0

package/src/hosts/scroll.ts

@@ -28,6 +28,8 @@ export interface ScrollProps extends CommonProps {
 	onViewportSize?: (width: number, height: number) => void
 	/** Called when effective offset changes (for syncing with useScroll when sticky adjusts) */
 	onEffectiveOffset?: (offset: number) => void
+	/** Called when effective horizontal offset changes */
+	onEffectiveOffsetX?: (offsetX: number) => void
 	/** Called when layout rect changes (for hit testing) */
 	onRect?: (x: number, y: number, w: number, h: number) => void
 }
@@ -46,6 +48,7 @@ export class ScrollHost extends SingleChildHost {
 	onContentSize?: (width: number, height: number) => void
 	onViewportSize?: (width: number, height: number) => void
 	onEffectiveOffset?: (offset: number) => void
+	onEffectiveOffsetX?: (offsetX: number) => void
 	onRect?: (x: number, y: number, w: number, h: number) => void
 
 	// Measured content dimensions (full size before clipping)
@@ -58,6 +61,7 @@ export class ScrollHost extends SingleChildHost {
 	private lastRectY = -1
 	// Track if we were at end (for sticky behavior)
 	private wasAtEnd = true
+	private wasAtEndX = true
 	// Effective offset after sticky adjustment (used for rendering)
 	private effectiveOffset = 0
 	private effectiveOffsetX = 0
@@ -133,10 +137,10 @@ export class ScrollHost extends SingleChildHost {
 		let scrollY = this.offset
 		let scrollX = this.offsetX
 
-		// Sticky scroll logic:
+		// Sticky scroll logic (vertical):
 		// - If user manually scrolled away from end (offset < effectiveOffset), unstick
 		// - If at end (or was at end and content grew), stay stuck
-		if (this.sticky) {
+		if (this.sticky && (this.axis === "vertical" || this.axis === "both")) {
 			// Detect if user scrolled away (offset prop is less than where we rendered)
 			const userScrolledAway = this.offset < this.effectiveOffset - 1
 
@@ -149,8 +153,20 @@ export class ScrollHost extends SingleChildHost {
 			}
 		}
 
+		// Sticky scroll logic (horizontal)
+		if (this.sticky && (this.axis === "horizontal" || this.axis === "both")) {
+			const userScrolledAway = this.offsetX < this.effectiveOffsetX - 1
+
+			if (userScrolledAway) {
+				this.wasAtEndX = false
+			} else if (this.wasAtEndX) {
+				scrollX = maxScrollX
+			}
+		}
+
 		// Track if we're at end for next frame
 		this.wasAtEnd = scrollY >= maxScrollY - 1
+		this.wasAtEndX = scrollX >= maxScrollX - 1
 
 		// Clamp offsets
 		scrollY = Math.max(0, Math.min(maxScrollY, scrollY))
@@ -161,6 +177,9 @@ export class ScrollHost extends SingleChildHost {
 		if (scrollY !== this.effectiveOffset || scrollY !== this.offset) {
 			this.onEffectiveOffset?.(scrollY)
 		}
+		if (scrollX !== this.effectiveOffsetX || scrollX !== this.offsetX) {
+			this.onEffectiveOffsetX?.(scrollX)
+		}
 		this.effectiveOffset = scrollY
 		this.effectiveOffsetX = scrollX
 

package/src/index.ts

@@ -29,10 +29,8 @@ export { DiagnosticsPanel } from "./debug/DiagnosticsPanel.js"
 // Development utilities (HMR)
 export {
 	autoHmr,
-	type DevRenderOptions,
-	type DevRenderResult,
-	devMain,
-	devRender,
+	type DevOptions,
+	type DevRuntime,
 	DevWrapper,
 	type DevWrapperProps,
 	hmr,
@@ -48,17 +46,23 @@ export {
 } from "./highlight.js"
 export type {
 	ScrollState,
+	ShortcutHandler,
+	ShortcutMap,
 	TimerStatus,
 	TimerType,
 	UseKeyboardOptions,
 	UseMouseOptions,
+	UsePasteOptions,
+	UseShortcutOptions,
 	UseScrollOptions,
 	UseScrollReturn,
 	UseTimerConfig,
 	UseTimerReturn,
 } from "./hooks/index.js"
+export type { Shortcut, ShortcutMatchOptions, ShortcutSpec } from "./shortcuts.js"
 // Hooks
-export { useKeyboard, useMouse, usePaste, useQuit, useScroll, useTimer } from "./hooks/index.js"
+export { useKeyboard, useMouse, usePaste, useQuit, useScroll, useShortcut, useTimer } from "./hooks/index.js"
+export { isKey } from "./shortcuts.js"
 export { useFrameStats } from "./hooks/useFrameStats.js"
 export type { BorderKind, BoxProps } from "./hosts/box.js"
 export type { CanvasProps, DrawContext } from "./hosts/canvas.js"
@@ -85,7 +89,16 @@ export {
 } from "./motion/index.js"
 // Types
 export type { CommonProps, HostContext, HostInstance, Rect, Size } from "./reconciler/types.js"
-export type { FrameStats, RendererOptions, RenderInstance, Root, TuiRenderer } from "./renderer.js"
+export type {
+	FrameStats,
+	ImportMetaLike,
+	PasteMsg,
+	RenderInstance,
+	RenderOptions,
+	RendererOptions,
+	Root,
+	TuiRenderer,
+} from "./renderer.js"
 // Renderer
 export {
 	createRenderer,

package/src/renderer/input/InputProcessor.ts

@@ -75,8 +75,15 @@ export class InputProcessor {
 
 		for (const event of events) {
 			if (event.type === "mouse") {
+				const wrapped: MouseMsg = {
+					...event,
+					defaultPrevented: false,
+					preventDefault() {
+						wrapped.defaultPrevented = true
+					},
+				}
 				this.config.flushSync(() => {
-					this.config.dispatchMouse(event)
+					this.config.dispatchMouse(wrapped)
 				})
 			} else {
 				const wrapped: KeyMsg = {

package/src/renderer/lifecycle/EventBus.ts

@@ -1,5 +1,5 @@
 import type { KeyMsg, MouseMsg } from "@effect-tui/core"
-import type { FrameStats } from "../../renderer-types.js"
+import type { FrameStats, PasteMsg } from "../../renderer-types.js"
 
 /**
  * Centralized event subscription management for the renderer.
@@ -8,7 +8,7 @@ import type { FrameStats } from "../../renderer-types.js"
 export class EventBus {
 	private keyHandlers = new Set<(key: KeyMsg) => void>()
 	private mouseHandlers = new Set<(mouse: MouseMsg) => void>()
-	private pasteHandlers = new Set<(text: string) => void>()
+	private pasteHandlers = new Set<(paste: PasteMsg) => void>()
 	private resizeHandlers = new Set<(width: number, height: number) => void>()
 	private frameHandlers = new Set<(stats: FrameStats) => void>()
 
@@ -22,7 +22,7 @@ export class EventBus {
 		return () => this.mouseHandlers.delete(handler)
 	}
 
-	onPaste(handler: (text: string) => void): () => void {
+	onPaste(handler: (paste: PasteMsg) => void): () => void {
 		this.pasteHandlers.add(handler)
 		return () => this.pasteHandlers.delete(handler)
 	}
@@ -53,6 +53,7 @@ export class EventBus {
 	 */
 	dispatchMouse(mouse: MouseMsg): void {
 		for (const handler of this.mouseHandlers) {
+			if (mouse.defaultPrevented) break
 			handler(mouse)
 		}
 	}
@@ -61,8 +62,17 @@ export class EventBus {
 	 * Dispatch a paste event to all handlers.
 	 */
 	dispatchPaste(text: string): void {
+		const paste: PasteMsg = {
+			type: "paste",
+			text,
+			defaultPrevented: false,
+			preventDefault() {
+				paste.defaultPrevented = true
+			},
+		}
 		for (const handler of this.pasteHandlers) {
-			handler(text)
+			if (paste.defaultPrevented) break
+			handler(paste)
 		}
 	}
 

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 */

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"
@@ -13,9 +14,11 @@ import { InputProcessor } from "./renderer/input/index.js"
 import { EventBus, 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() {
@@ -445,11 +455,43 @@ 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
+	}
+
+type RenderCache = Map<string, RenderInstance>
+
+const getRenderCache = (): RenderCache => {
+	const globalAny = globalThis as typeof globalThis & {
+		__effectTuiRenderCache?: RenderCache
+	}
+	if (!globalAny.__effectTuiRenderCache) {
+		globalAny.__effectTuiRenderCache = new Map()
+	}
+	return globalAny.__effectTuiRenderCache
+}
 
-	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 +514,7 @@ export function render(element: ReactNode, options?: RendererOptions): RenderIns
 		process.off("exit", onExit)
 		if (!resolved) {
 			resolved = true
-			renderer.stop()
+			stop()
 			resolveExit?.()
 		}
 	}
@@ -482,10 +524,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 +540,48 @@ 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()
+	const cached = renderCache.get(baseUrl)
+	if (cached) return cached
+
+	if (!importMeta.main) {
+		throw new Error("[effect-tui] render(..., { dev: true }) must be called from the entry module")
+	}
+
+	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