@effect-tui/react 0.15.2 → 2.0.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,38 +39,53 @@ 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
 	private contentHeight = 0
+	// Effective viewport dimensions (excludes scrollbar gutter when visible)
+	private viewportWidth = 0
+	private viewportHeight = 0
+	// Scrollbar visibility after accounting for content overflow
+	private showVerticalScrollbar = false
+	private showHorizontalScrollbar = false
 	// Track last reported sizes to avoid redundant callbacks
 	private lastReportedContentW = -1
 	private lastReportedContentH = -1
@@ -63,6 +95,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
@@ -75,78 +109,129 @@ export class ScrollHost extends SingleChildHost {
 		this.updateProps(props as unknown as Record<string, unknown>)
 	}
 
-	measure(maxW: number, maxH: number): Size {
+	private computeViewport(baseW: number, baseH: number, contentW: number, contentH: number): {
+		viewportW: number
+		viewportH: number
+		showV: boolean
+		showH: boolean
+	} {
+		const allowV = this.showScrollbar && (this.axis === "vertical" || this.axis === "both")
+		const allowH = this.showScrollbar && (this.axis === "horizontal" || this.axis === "both")
+		let viewportW = Math.max(0, baseW)
+		let viewportH = Math.max(0, baseH)
+		let showV = false
+		let showH = false
+
+		for (let i = 0; i < 2; i++) {
+			const nextShowV = allowV && contentH > viewportH
+			const nextShowH = allowH && contentW > viewportW
+			if (nextShowV === showV && nextShowH === showH) break
+			showV = nextShowV
+			showH = nextShowH
+			viewportW = Math.max(0, baseW - (showV ? 1 : 0))
+			viewportH = Math.max(0, baseH - (showH ? 1 : 0))
+		}
+
+		return { viewportW, viewportH, showV, showH }
+	}
+
+	protected measureSelf(maxW: number, maxH: number): Size {
 		// Apply frame constraints to determine our size
 		const constrained = this.constrainProposal(maxW, maxH)
 
-		// Measure child with unbounded dimension(s) based on axis
-		let childMaxW = constrained.w
-		let childMaxH = constrained.h
-
-		if (this.axis === "vertical" || this.axis === "both") {
-			childMaxH = Number.MAX_SAFE_INTEGER
+		const child = this.child
+		if (!child) {
+			this.contentWidth = 0
+			this.contentHeight = 0
+			const viewport = this.computeViewport(constrained.w, constrained.h, 0, 0)
+			this.viewportWidth = viewport.viewportW
+			this.viewportHeight = viewport.viewportH
+			this.showVerticalScrollbar = viewport.showV
+			this.showHorizontalScrollbar = viewport.showH
+			return this.constrainResult({ w: 0, h: 0 })
 		}
-		if (this.axis === "horizontal" || this.axis === "both") {
-			childMaxW = Number.MAX_SAFE_INTEGER
+
+		const measureChild = (proposalW: number, proposalH: number): Size => {
+			let childMaxW = proposalW
+			let childMaxH = proposalH
+
+			if (this.axis === "vertical" || this.axis === "both") {
+				childMaxH = Number.MAX_SAFE_INTEGER
+			}
+			if (this.axis === "horizontal" || this.axis === "both") {
+				childMaxW = Number.MAX_SAFE_INTEGER
+			}
+
+			return child.measure(childMaxW, childMaxH)
 		}
 
-		// Measure single child (scroll should have at most one child)
-		const child = this.child
-		if (child) {
-			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
+		let viewportW = constrained.w
+		let viewportH = constrained.h
+		let contentW = 0
+		let contentH = 0
+		let showV = false
+		let showH = false
+
+		for (let i = 0; i < 3; i++) {
+			const childSize = measureChild(viewportW, viewportH)
+			contentW = childSize.w
+			contentH = childSize.h
+			const viewport = this.computeViewport(constrained.w, constrained.h, contentW, contentH)
+			if (viewport.viewportW === viewportW && viewport.viewportH === viewportH) {
+				showV = viewport.showV
+				showH = viewport.showH
+				break
+			}
+			viewportW = viewport.viewportW
+			viewportH = viewport.viewportH
+			showV = viewport.showV
+			showH = viewport.showH
 		}
 
+		this.contentWidth = contentW
+		this.contentHeight = contentH
+		this.viewportWidth = viewportW
+		this.viewportHeight = viewportH
+		this.showVerticalScrollbar = showV
+		this.showHorizontalScrollbar = showH
+
 		// 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)
+		const naturalW = Math.min(this.contentWidth + (this.showVerticalScrollbar ? 1 : 0), constrained.w)
+		const naturalH = Math.min(this.contentHeight + (this.showHorizontalScrollbar ? 1 : 0), constrained.h)
 
 		return this.constrainResult({ w: naturalW, h: naturalH })
 	}
 
-	override layout(rect: Rect): void {
+	protected override layoutSelf(rect: Rect): void {
 		const layoutRect = this.layoutWithConstraints(rect)
-
-		// 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 viewport = this.computeViewport(layoutRect.w, layoutRect.h, this.contentWidth, this.contentHeight)
+		this.viewportWidth = viewport.viewportW
+		this.viewportHeight = viewport.viewportH
+		this.showVerticalScrollbar = viewport.showV
+		this.showHorizontalScrollbar = viewport.showH
+
+		const { x: alignX, y: alignY } = resolveAlign(this.align)
+
+		const contentChanged =
+			this.contentWidth !== this.lastReportedContentW || this.contentHeight !== this.lastReportedContentH
+		const viewportChanged =
+			this.viewportWidth !== this.lastViewportW || this.viewportHeight !== 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
 
 		// Calculate max scroll offsets
-		const maxScrollY = Math.max(0, this.contentHeight - layoutRect.h)
-		const maxScrollX = Math.max(0, this.contentWidth - layoutRect.w)
+		const maxScrollY = Math.max(0, this.contentHeight - this.viewportHeight)
+		const maxScrollX = Math.max(0, this.contentWidth - this.viewportWidth)
 
 		// 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 +239,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 +270,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
-				scrollY = -(layoutRect.h - this.contentHeight)
+		if (this.contentHeight < this.viewportHeight && (this.axis === "vertical" || this.axis === "both")) {
+			if (alignY === "bottom") {
+				scrollY = -(this.viewportHeight - this.contentHeight)
+			} else if (alignY === "center") {
+				scrollY = -Math.floor((this.viewportHeight - this.contentHeight) / 2)
 			}
-			if (this.contentWidth < layoutRect.w && (this.axis === "horizontal" || this.axis === "both")) {
-				// Align to right
-				scrollX = -(layoutRect.w - this.contentWidth)
+		}
+		if (this.contentWidth < this.viewportWidth && (this.axis === "horizontal" || this.axis === "both")) {
+			if (alignX === "right") {
+				scrollX = -(this.viewportWidth - this.contentWidth)
+			} else if (alignX === "center") {
+				scrollX = -Math.floor((this.viewportWidth - this.contentWidth) / 2)
 			}
 		}
 
@@ -215,6 +298,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 = this.viewportWidth
+			this.lastViewportH = this.viewportHeight
+			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: this.viewportWidth, height: this.viewportHeight },
+				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 {
@@ -224,8 +328,8 @@ export class ScrollHost extends SingleChildHost {
 		// Fill background (inherit from parent if not explicitly set)
 		fillRectWithInheritedBg(buffer, palette, { x, y, w, h }, this.bg, this.parent)
 
-		// Render children with clipping
-		buffer.withClip(x, y, w, h, () => {
+		// Render children with clipping (exclude scrollbar gutters)
+		buffer.withClip(x, y, this.viewportWidth, this.viewportHeight, () => {
 			const child = this.child
 			if (child) {
 				child.render(buffer, palette)
@@ -243,18 +347,18 @@ export class ScrollHost extends SingleChildHost {
 		const { x, y, w, h } = this.rect
 
 		// Vertical scrollbar
-		if ((this.axis === "vertical" || this.axis === "both") && this.contentHeight > h) {
-			const maxScroll = this.contentHeight - h
+		if (this.showVerticalScrollbar) {
+			const maxScroll = Math.max(1, this.contentHeight - this.viewportHeight)
 			const scrollRatio = Math.min(1, this.effectiveOffset / maxScroll)
-			const thumbRatio = h / this.contentHeight
-			const thumbHeight = Math.max(1, Math.floor(h * thumbRatio))
-			const thumbY = Math.floor((h - thumbHeight) * scrollRatio)
+			const thumbRatio = this.viewportHeight / this.contentHeight
+			const thumbHeight = Math.max(1, Math.floor(this.viewportHeight * thumbRatio))
+			const thumbY = Math.floor((this.viewportHeight - thumbHeight) * scrollRatio)
 
 			const trackStyle = palette.id({ fg: 8 }) // dim
 			const thumbStyle = palette.id({ fg: 7 }) // brighter
 
 			// Draw track
-			for (let row = 0; row < h; row++) {
+			for (let row = 0; row < this.viewportHeight; row++) {
 				const char = row >= thumbY && row < thumbY + thumbHeight ? "┃" : "│"
 				const style = row >= thumbY && row < thumbY + thumbHeight ? thumbStyle : trackStyle
 				buffer.drawCP(x + w - 1, y + row, char.codePointAt(0)!, style)
@@ -262,18 +366,18 @@ export class ScrollHost extends SingleChildHost {
 		}
 
 		// Horizontal scrollbar
-		if ((this.axis === "horizontal" || this.axis === "both") && this.contentWidth > w) {
-			const maxScroll = this.contentWidth - w
+		if (this.showHorizontalScrollbar) {
+			const maxScroll = Math.max(1, this.contentWidth - this.viewportWidth)
 			const scrollRatio = Math.min(1, this.effectiveOffsetX / maxScroll)
-			const thumbRatio = w / this.contentWidth
-			const thumbWidth = Math.max(1, Math.floor(w * thumbRatio))
-			const thumbX = Math.floor((w - thumbWidth) * scrollRatio)
+			const thumbRatio = this.viewportWidth / this.contentWidth
+			const thumbWidth = Math.max(1, Math.floor(this.viewportWidth * thumbRatio))
+			const thumbX = Math.floor((this.viewportWidth - thumbWidth) * scrollRatio)
 
 			const trackStyle = palette.id({ fg: 8 })
 			const thumbStyle = palette.id({ fg: 7 })
 
 			// Draw track
-			for (let col = 0; col < w; col++) {
+			for (let col = 0; col < this.viewportWidth; col++) {
 				const char = col >= thumbX && col < thumbX + thumbWidth ? "━" : "─"
 				const style = col >= thumbX && col < thumbX + thumbWidth ? thumbStyle : trackStyle
 				buffer.drawCP(x + col, y + h - 1, char.codePointAt(0)!, style)
@@ -285,17 +389,35 @@ export class ScrollHost extends SingleChildHost {
 		super.updateProps(props)
 		// Scroll is greedy by default unless explicitly set to false
 		this.applyGreedyDefault(props, 1)
+		const prevAxis = this.axis
+		const prevOffsetY = this.offsetY
+		const prevOffsetX = this.offsetX
+		const prevAlign = this.align
+		const prevBg = this.bg
+		const prevShowScrollbar = this.showScrollbar
+		const prevSticky = this.sticky
+
 		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"]
+
+		const layoutChanged =
+			prevAxis !== this.axis ||
+			prevOffsetY !== this.offsetY ||
+			prevOffsetX !== this.offsetX ||
+			prevSticky !== this.sticky ||
+			prevAlign !== this.align ||
+			prevShowScrollbar !== this.showScrollbar
+
+		if (layoutChanged) {
+			this.invalidateLayout()
+		} else if (prevBg !== this.bg) {
+			this.invalidateRender()
+		}
 	}
 }

package/src/hosts/single-child.ts

@@ -26,6 +26,7 @@ export abstract class SingleChildHost extends BaseHost {
 			this.children.splice(0, 1)
 		}
 		child.parent = null
+		this.invalidateLayout()
 	}
 
 	private setSingleChild(child: HostInstance): void {
@@ -44,5 +45,6 @@ export abstract class SingleChildHost extends BaseHost {
 		}
 
 		child.parent = this
+		this.invalidateLayout()
 	}
 }

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
 
@@ -21,7 +21,7 @@ export class SpacerHost extends BaseHost {
 		this.updateProps(props as unknown as Record<string, unknown>)
 	}
 
-	measure(_maxW: number, _maxH: number): Size {
+	protected measureSelf(_maxW: number, _maxH: number): Size {
 		// Spacers have no natural size, they expand via greedy
 		return { w: this.minWidth, h: this.minHeight }
 	}
@@ -34,7 +34,12 @@ export class SpacerHost extends BaseHost {
 		super.updateProps(props)
 		// Spacer is greedy by default unless explicitly set to false
 		this.applyGreedyDefault(props, 1)
+		const prevMinWidth = this.minWidth
+		const prevMinHeight = this.minHeight
 		if (props.minWidth !== undefined) this.minWidth = props.minWidth as number
 		if (props.minHeight !== undefined) this.minHeight = props.minHeight as number
+		if (prevMinWidth !== this.minWidth || prevMinHeight !== this.minHeight) {
+			this.invalidateLayout()
+		}
 	}
 }