@effect-tui/react 0.15.2 → 0.16.0

package/src/hosts/scroll.ts

@@ -4,15 +4,32 @@ import type { CommonProps, HostContext, Rect, Size } from "../reconciler/types.j
 import { fillRectWithInheritedBg } from "../utils/index.js"
 import { SingleChildHost } from "./single-child.js"
 
+export type ScrollAxis = "vertical" | "horizontal" | "both"
+export type ScrollAlignX = "left" | "center" | "right"
+export type ScrollAlignY = "top" | "center" | "bottom"
+export type ScrollAlign = ScrollAlignX | ScrollAlignY | { x?: ScrollAlignX; y?: ScrollAlignY }
+export interface ScrollLayoutChange {
+	content: { width: number; height: number }
+	viewport: { width: number; height: number }
+	offset: { x: number; y: number }
+	rect: { x: number; y: number; w: number; h: number }
+	axis: ScrollAxis
+}
+
 export interface ScrollProps extends CommonProps {
 	/** Scroll axis: "vertical" (default), "horizontal", or "both" */
-	axis?: "vertical" | "horizontal" | "both"
-	/** Current scroll offset in pixels (0 = start) */
-	offset?: number
-	/** Horizontal offset when axis="both" */
+	axis?: ScrollAxis
+	/** Vertical scroll offset in pixels (0 = top) */
+	offsetY?: number
+	/** Horizontal scroll offset in pixels (0 = left) */
 	offsetX?: number
-	/** Alignment when content is smaller than viewport */
-	align?: "start" | "end"
+	/**
+	 * Alignment when content is smaller than viewport.
+	 * - axis="vertical": "top" | "center" | "bottom"
+	 * - axis="horizontal": "left" | "center" | "right"
+	 * - axis="both": { x, y }
+	 */
+	align?: ScrollAlign
 	/** Background color for the scroll viewport */
 	bg?: Color
 	/** Whether to show scrollbar indicators */
@@ -22,34 +39,43 @@ export interface ScrollProps extends CommonProps {
 	 * This is handled in the host itself for instant updates (no React roundtrip).
 	 */
 	sticky?: boolean
-	/** Called when content size is measured (for useScroll) */
-	onContentSize?: (width: number, height: number) => void
-	/** Called when viewport size changes (for useScroll) */
-	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
+	/** Called when scroll layout changes (content/viewport/offset/rect). */
+	onScrollLayoutChange?: (event: ScrollLayoutChange) => void
+}
+
+const isAlignX = (value: string): value is ScrollAlignX => value === "left" || value === "center" || value === "right"
+const isAlignY = (value: string): value is ScrollAlignY => value === "top" || value === "center" || value === "bottom"
+
+const resolveAlign = (align: ScrollAlign | undefined): { x: ScrollAlignX; y: ScrollAlignY } => {
+	let x: ScrollAlignX | undefined
+	let y: ScrollAlignY | undefined
+
+	if (typeof align === "string") {
+		if (isAlignX(align)) x = align
+		if (isAlignY(align)) y = align
+	} else if (align) {
+		x = align.x
+		y = align.y
+	}
+
+	return {
+		x: x ?? "left",
+		y: y ?? "top",
+	}
 }
 
 export class ScrollHost extends SingleChildHost {
-	axis: "vertical" | "horizontal" | "both" = "vertical"
-	offset = 0
+	axis: ScrollAxis = "vertical"
+	offsetY = 0
 	offsetX = 0
-	align: "start" | "end" = "start"
+	align?: ScrollAlign
 	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
-	onEffectiveOffsetX?: (offsetX: number) => void
-	onRect?: (x: number, y: number, w: number, h: number) => void
+	onScrollLayoutChange?: (event: ScrollLayoutChange) => void
 
 	// Measured content dimensions (full size before clipping)
 	private contentWidth = 0
@@ -63,6 +89,8 @@ export class ScrollHost extends SingleChildHost {
 	private lastRectY = -1
 	private lastRectW = -1
 	private lastRectH = -1
+	private lastOffsetY = -1
+	private lastOffsetX = -1
 	// Track if we were at end (for sticky behavior)
 	private wasAtEnd = true
 	private wasAtEndX = true
@@ -96,7 +124,7 @@ export class ScrollHost extends SingleChildHost {
 			const childSize = child.measure(childMaxW, childMaxH)
 			this.contentWidth = childSize.w
 			this.contentHeight = childSize.h
-			// Note: onContentSize callback is deferred to layout() to keep measure() pure
+			// Note: onScrollLayoutChange callback is deferred to layout() to keep measure() pure
 		}
 
 		// Report natural content size (clamped to constrained bounds)
@@ -109,34 +137,16 @@ export class ScrollHost extends SingleChildHost {
 
 	override layout(rect: Rect): void {
 		const layoutRect = this.layoutWithConstraints(rect)
+		const { x: alignX, y: alignY } = resolveAlign(this.align)
 
-		// Report content size if changed (deferred from measure() to keep it pure)
-		if (this.contentWidth !== this.lastReportedContentW || this.contentHeight !== this.lastReportedContentH) {
-			this.lastReportedContentW = this.contentWidth
-			this.lastReportedContentH = this.contentHeight
-			this.onContentSize?.(this.contentWidth, this.contentHeight)
-		}
-
-		// Report viewport size if changed (for useScroll hook)
-		if (this.onViewportSize && (layoutRect.w !== this.lastViewportW || layoutRect.h !== this.lastViewportH)) {
-			this.lastViewportW = layoutRect.w
-			this.lastViewportH = layoutRect.h
-			this.onViewportSize(layoutRect.w, layoutRect.h)
-		}
-
-		// Report rect if position changed (for hit testing)
-		if (
+		const contentChanged =
+			this.contentWidth !== this.lastReportedContentW || this.contentHeight !== this.lastReportedContentH
+		const viewportChanged = layoutRect.w !== this.lastViewportW || layoutRect.h !== this.lastViewportH
+		const rectChanged =
 			layoutRect.x !== this.lastRectX ||
 			layoutRect.y !== this.lastRectY ||
 			layoutRect.w !== this.lastRectW ||
 			layoutRect.h !== this.lastRectH
-		) {
-			this.lastRectX = layoutRect.x
-			this.lastRectY = layoutRect.y
-			this.lastRectW = layoutRect.w
-			this.lastRectH = layoutRect.h
-			this.onRect?.(layoutRect.x, layoutRect.y, layoutRect.w, layoutRect.h)
-		}
 
 		const child = this.child
 		if (!child) return
@@ -146,7 +156,7 @@ export class ScrollHost extends SingleChildHost {
 		const maxScrollX = Math.max(0, this.contentWidth - layoutRect.w)
 
 		// Start with the offset from props (controlled by useScroll)
-		let scrollY = this.offset
+		let scrollY = this.offsetY
 		let scrollX = this.offsetX
 
 		// Sticky scroll logic (vertical):
@@ -154,7 +164,7 @@ export class ScrollHost extends SingleChildHost {
 		// - If at end (or was at end and content grew), stay stuck
 		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
+			const userScrolledAway = this.offsetY < this.effectiveOffset - 1
 
 			if (userScrolledAway) {
 				// User scrolled up - unstick
@@ -185,25 +195,23 @@ export class ScrollHost extends SingleChildHost {
 		scrollX = Math.max(0, Math.min(maxScrollX, scrollX))
 
 		// Store effective offsets for rendering (scrollbar position)
-		// Report back if clamped or changed (keep controller in sync)
-		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
+		const offsetChanged = this.effectiveOffset !== this.lastOffsetY || this.effectiveOffsetX !== this.lastOffsetX
 
 		// Handle alignment when content is smaller than viewport
-		if (this.align === "end") {
-			if (this.contentHeight < layoutRect.h && (this.axis === "vertical" || this.axis === "both")) {
-				// Align to bottom
+		if (this.contentHeight < layoutRect.h && (this.axis === "vertical" || this.axis === "both")) {
+			if (alignY === "bottom") {
 				scrollY = -(layoutRect.h - this.contentHeight)
+			} else if (alignY === "center") {
+				scrollY = -Math.floor((layoutRect.h - this.contentHeight) / 2)
 			}
-			if (this.contentWidth < layoutRect.w && (this.axis === "horizontal" || this.axis === "both")) {
-				// Align to right
+		}
+		if (this.contentWidth < layoutRect.w && (this.axis === "horizontal" || this.axis === "both")) {
+			if (alignX === "right") {
 				scrollX = -(layoutRect.w - this.contentWidth)
+			} else if (alignX === "center") {
+				scrollX = -Math.floor((layoutRect.w - this.contentWidth) / 2)
 			}
 		}
 
@@ -215,6 +223,27 @@ export class ScrollHost extends SingleChildHost {
 			h: this.contentHeight,
 		}
 		child.layout(childRect)
+
+		if (this.onScrollLayoutChange && (contentChanged || viewportChanged || rectChanged || offsetChanged)) {
+			this.lastReportedContentW = this.contentWidth
+			this.lastReportedContentH = this.contentHeight
+			this.lastViewportW = layoutRect.w
+			this.lastViewportH = layoutRect.h
+			this.lastRectX = layoutRect.x
+			this.lastRectY = layoutRect.y
+			this.lastRectW = layoutRect.w
+			this.lastRectH = layoutRect.h
+			this.lastOffsetY = this.effectiveOffset
+			this.lastOffsetX = this.effectiveOffsetX
+
+			this.onScrollLayoutChange({
+				content: { width: this.contentWidth, height: this.contentHeight },
+				viewport: { width: layoutRect.w, height: layoutRect.h },
+				offset: { x: this.effectiveOffsetX, y: this.effectiveOffset },
+				rect: { x: layoutRect.x, y: layoutRect.y, w: layoutRect.w, h: layoutRect.h },
+				axis: this.axis,
+			})
+		}
 	}
 
 	render(buffer: CellBuffer, palette: Palette): void {
@@ -286,16 +315,12 @@ export class ScrollHost extends SingleChildHost {
 		// Scroll is greedy by default unless explicitly set to false
 		this.applyGreedyDefault(props, 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.offsetY !== undefined) this.offsetY = props.offsetY as number
 		if (props.offsetX !== undefined) this.offsetX = props.offsetX as number
-		if (props.align !== undefined) this.align = (props.align as ScrollProps["align"]) ?? "start"
+		if (props.align !== undefined) this.align = props.align as ScrollProps["align"]
 		this.bg = props.bg as Color | undefined
 		if (props.showScrollbar !== undefined) this.showScrollbar = props.showScrollbar as boolean
 		if (props.sticky !== undefined) this.sticky = props.sticky as boolean
-		this.onContentSize = props.onContentSize as ScrollProps["onContentSize"]
-		this.onViewportSize = props.onViewportSize as ScrollProps["onViewportSize"]
-		this.onEffectiveOffset = props.onEffectiveOffset as ScrollProps["onEffectiveOffset"]
-		this.onEffectiveOffsetX = props.onEffectiveOffsetX as ScrollProps["onEffectiveOffsetX"]
-		this.onRect = props.onRect as ScrollProps["onRect"]
+		this.onScrollLayoutChange = props.onScrollLayoutChange as ScrollProps["onScrollLayoutChange"]
 	}
 }

package/src/hosts/spacer.ts

@@ -1,6 +1,6 @@
 import type { CellBuffer, Palette } from "@effect-tui/core"
 import type { CommonProps, HostContext, Size } from "../reconciler/types.js"
-import { BaseHost } from "./base.js"
+import { LeafHost } from "./leaf.js"
 
 export interface SpacerProps extends CommonProps {
 	/** Minimum width (default 0) */
@@ -9,7 +9,7 @@ export interface SpacerProps extends CommonProps {
 	minHeight?: number
 }
 
-export class SpacerHost extends BaseHost {
+export class SpacerHost extends LeafHost {
 	minWidth = 0
 	minHeight = 0
 

package/src/hosts/text.ts

@@ -1,8 +1,9 @@
 import { type CellBuffer, type Color, displayWidth, type Palette } from "@effect-tui/core"
 import type { ColorMotionValue } from "../motion/color-motion-value.js"
 import type { CommonProps, HostContext, HostInstance, Rect, Size } from "../reconciler/types.js"
-import { isWhitespace, resolveInheritedBgStyle, splitWords, styleIdFromProps, wrapSpans } from "../utils/index.js"
+import { resolveInheritedBgStyle, styleIdFromProps, wrapSpans, wrapText } from "../utils/index.js"
 import { BaseHost, getInheritedBg } from "./base.js"
+import { LeafHost } from "./leaf.js"
 
 /** Color prop that can be a static Color or a spring-animated ColorMotionValue */
 export type ColorProp = Color | ColorMotionValue
@@ -205,7 +206,7 @@ export class TextHost extends BaseHost {
 		if (this.wrap) {
 			// Wrap mode: may span multiple lines. Cache result for render()
 			this.cachedLines = rawLines.flatMap((line, idx) =>
-				idx < rawLines.length - 1 ? [...this.wrapText(line, constrained.w), ""] : this.wrapText(line, constrained.w),
+				idx < rawLines.length - 1 ? [...wrapText(line, constrained.w), ""] : wrapText(line, constrained.w),
 			)
 			this.cachedWidth = constrained.w
 			const w = this.cachedLines.reduce((max, line) => Math.max(max, displayWidth(line)), 0)
@@ -220,60 +221,6 @@ export class TextHost extends BaseHost {
 		return this.constrainResult({ w, h })
 	}
 
-	/** Wrap text to fit within maxWidth, preferring word boundaries */
-	private wrapText(text: string, maxWidth: number): string[] {
-		const result: string[] = []
-		for (const rawLine of text.split("\n")) {
-			if (rawLine === "") {
-				result.push("")
-				continue
-			}
-
-			// Split into words (keeping whitespace as separate tokens)
-			const tokens = splitWords(rawLine)
-			let line = ""
-			let lineW = 0
-
-			for (const token of tokens) {
-				const tokenW = displayWidth(token)
-				const isWs = isWhitespace(token)
-
-				if (lineW + tokenW <= maxWidth) {
-					// Token fits on current line
-					line += token
-					lineW += tokenW
-				} else if (isWs) {
-					// Whitespace doesn't fit - just skip it (don't start new line with space)
-					continue
-				} else if (tokenW <= maxWidth) {
-					// Word doesn't fit but is smaller than maxWidth - start new line
-					if (line.trimEnd()) result.push(line.trimEnd())
-					line = token
-					lineW = tokenW
-				} else {
-					// Word is longer than maxWidth - break it character by character
-					if (line.trimEnd()) result.push(line.trimEnd())
-					line = ""
-					lineW = 0
-					for (const ch of token) {
-						const chW = displayWidth(ch)
-						if (lineW + chW > maxWidth && line.length > 0) {
-							result.push(line)
-							line = ch
-							lineW = chW
-						} else {
-							line += ch
-							lineW += chW
-						}
-					}
-				}
-			}
-			// Preserve trailing space for inline flow - only trimEnd when breaking mid-line (done above)
-			if (line) result.push(line)
-		}
-		return result.length > 0 ? result : [""]
-	}
-
 	override layout(rect: Rect): void {
 		const layoutRect = this.layoutWithConstraints(rect)
 		// Layout children (RawTextHost nodes) at same position
@@ -349,7 +296,7 @@ export class TextHost extends BaseHost {
 				this.cachedLines && this.cachedWidth === rectW
 					? this.cachedLines
 					: rawLines.flatMap((line, idx) =>
-							idx < rawLines.length - 1 ? [...this.wrapText(line, rectW), ""] : this.wrapText(line, rectW),
+							idx < rawLines.length - 1 ? [...wrapText(line, rectW), ""] : wrapText(line, rectW),
 						)
 			const visibleLines = Math.min(lines.length, this.rect.h)
 			// Explicitly paint background under text lines to clear stale styles (e.g., selection highlights).
@@ -399,7 +346,7 @@ export class TextHost extends BaseHost {
 }
 
 /** Special host for raw text nodes (React text children) */
-export class RawTextHost extends BaseHost {
+export class RawTextHost extends LeafHost {
 	content = ""
 
 	constructor(text: string, ctx: HostContext) {

package/src/hosts/vstack.ts

@@ -8,6 +8,6 @@ export interface VStackProps extends FlexContainerProps<"vertical"> {}
  */
 export class VStackHost extends FlexContainerHost<"vertical"> {
 	constructor(props: VStackProps, ctx: HostContext) {
-		super("vertical", "vstack", props as FlexContainerProps<"vertical">, ctx, "leading")
+		super("vertical", "vstack", props as FlexContainerProps<"vertical">, ctx, "left")
 	}
 }

package/src/hosts/zstack.ts

@@ -1,10 +1,11 @@
 import type { CellBuffer, Palette } from "@effect-tui/core"
 import type { CommonProps, HostContext, Rect, Size } from "../reconciler/types.js"
-import { alignedChildRect, type HAlign, type VAlign } from "../utils/index.js"
+import { type HAlign, type VAlign } from "../utils/index.js"
 import { BaseHost } from "./base.js"
+import { layoutAlignedChildren } from "./layout-helpers.js"
 
 export interface ZStackProps extends CommonProps {
-	alignment?: { h?: "leading" | "center" | "trailing"; v?: "top" | "center" | "bottom" }
+	alignment?: { h?: "left" | "center" | "right"; v?: "top" | "center" | "bottom" }
 }
 
 // Overlay children in the same rect, honoring alignment for each child.
@@ -45,11 +46,10 @@ export class ZStackHost extends BaseHost {
 	override layout(rect: Rect): void {
 		const layoutRect = this.layoutWithConstraints(rect)
 
-		for (let i = 0; i < this.children.length; i++) {
-			const child = this.children[i]
-			const size = this.cachedSizes[i] ?? child.measure(layoutRect.w, layoutRect.h)
-			child.layout(alignedChildRect(layoutRect, size, this.alignmentH, this.alignmentV))
-		}
+		layoutAlignedChildren(layoutRect, this.children, this.cachedSizes, () => ({
+			h: this.alignmentH,
+			v: this.alignmentV,
+		}))
 	}
 
 	render(buffer: CellBuffer, palette: Palette): void {

package/src/index.ts

@@ -67,7 +67,7 @@ export { useFrameStats } from "./hooks/useFrameStats.js"
 export type { BorderKind, BoxProps } from "./hosts/box.js"
 export type { CanvasProps, DrawContext } from "./hosts/canvas.js"
 export type { HStackProps } from "./hosts/hstack.js"
-export type { ScrollProps } from "./hosts/scroll.js"
+export type { ScrollAlign, ScrollAlignX, ScrollAlignY, ScrollAxis, ScrollLayoutChange, ScrollProps } from "./hosts/scroll.js"
 export type { SpacerProps } from "./hosts/spacer.js"
 export type { SpanProps, SpanStyle, TextProps } from "./hosts/text.js"
 export type { VStackProps } from "./hosts/vstack.js"

package/src/internal/dev/hmr.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs"
+import { globalValue } from "effect/GlobalValue"
+
+/**
+ * Pipeable combinator that makes an atom persist across hot reloads.
+ *
+ * This is the cleanest way to define HMR-persistent atoms - just pipe it!
+ * Combines globalValue (for persistence) + keepAlive (prevents registry cleanup).
+ */
+export function hmr(key: string): <A,>(self: A) => A {
+	return <A,>(self: A): A => {
+		return globalValue(Symbol.for(`hmr/${key}`), () => {
+			// Apply keepAlive if it's an atom (just sets keepAlive: true)
+			if (typeof self === "object" && self !== null && "keepAlive" in self) {
+				return Object.assign(Object.create(Object.getPrototypeOf(self)), {
+					...self,
+					keepAlive: true,
+				})
+			}
+			return self
+		}) as A
+	}
+}
+
+/**
+ * Wrap any value creation in HMR persistence.
+ */
+export function hmrState<T>(key: string, create: () => T): T {
+	return globalValue(Symbol.for(`hmr/${key}`), create)
+}
+
+// Cache for runtime key extraction
+const keyCache = new Map<string, string>()
+
+/**
+ * Parse stack trace to get file path and line number.
+ * Returns null if parsing fails.
+ */
+function parseStack(stack: string): { file: string; line: number; col: number } | null {
+	// Bun stack format: "    at functionName (file:line:col)" or "    at file:line:col"
+	const lines = stack.split("\n")
+	// Skip first line (Error message) and find caller (skip autoHmr itself)
+	for (let i = 2; i < lines.length; i++) {
+		const match = lines[i].match(/\((.+?):(\d+):(\d+)\)/) || lines[i].match(/at\s+(.+?):(\d+):(\d+)/)
+		if (match) {
+			return { file: match[1], line: parseInt(match[2], 10), col: parseInt(match[3], 10) }
+		}
+	}
+	return null
+}
+
+/**
+ * Extract variable name from source line using regex.
+ * Returns null if extraction fails.
+ */
+function extractVarName(source: string, line: number): string | null {
+	const lines = source.split("\n")
+	if (line < 1 || line > lines.length) return null
+
+	const sourceLine = lines[line - 1]
+	const match = sourceLine.match(/(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=/)
+	return match?.[1] ?? null
+}
+
+/**
+ * Auto-keyed HMR persistence for atoms.
+ *
+ * When used with the HMR plugin (recommended), keys are injected at load time
+ * based on the variable name. Without the plugin, falls back to runtime
+ * stack trace parsing.
+ */
+export function autoHmr<A>(self: A): A {
+	// Get stack trace for caller location
+	const stack = new Error().stack ?? ""
+	const location = parseStack(stack)
+
+	if (!location) {
+		// Fallback: use a hash of the stack trace
+		const fallbackKey = `unknown:${stack.slice(0, 100)}`
+		return hmr(fallbackKey)(self)
+	}
+
+	const cacheKey = `${location.file}:${location.line}:${location.col}`
+
+	// Check cache first
+	let key = keyCache.get(cacheKey)
+	if (!key) {
+		try {
+			// Read source file and extract variable name
+			const source = readFileSync(location.file, "utf-8")
+			const varName = extractVarName(source, location.line)
+			key = `${location.file}:${varName ?? `line${location.line}`}`
+		} catch {
+			// File read failed, use line-based key
+			key = `${location.file}:line${location.line}`
+		}
+		keyCache.set(cacheKey, key)
+	}
+
+	return hmr(key)(self)
+}