@effect-tui/react 0.1.3 → 0.1.4

package/src/hooks/use-scroll.ts

@@ -0,0 +1,386 @@
+// use-scroll.ts — Hook for managing scroll state with keyboard/mouse input
+import { useState, useCallback, useRef, useMemo, useLayoutEffect } from "react"
+import type { KeyMsg } from "@effect-tui/core"
+import { useKeyboard } from "./use-keyboard.js"
+import { useTerminalSize } from "../renderer.js"
+
+// ============================================================================
+// Scroll Acceleration (macOS-style)
+// ============================================================================
+
+interface ScrollAcceleration {
+	tick(now?: number): number
+	reset(): void
+}
+
+/**
+ * macOS-inspired scroll acceleration.
+ * Tracks velocity via moving window of tick intervals.
+ * Fast scrolling gets progressively faster.
+ */
+class MacOSScrollAccel implements ScrollAcceleration {
+	private lastTickTime = 0
+	private velocityHistory: number[] = []
+	private readonly historySize = 3
+	private readonly streakTimeout = 150
+	// Some terminals send duplicate ticks ~4ms apart (Ghostty workaround)
+	private readonly minTickInterval = 6
+
+	constructor(
+		private opts: {
+			A?: number // Amplitude (default 0.8)
+			tau?: number // Time constant (default 3)
+			maxMultiplier?: number // Cap (default 6)
+		} = {},
+	) {}
+
+	tick(now = Date.now()): number {
+		const A = this.opts.A ?? 0.8
+		const tau = this.opts.tau ?? 3
+		const maxMultiplier = this.opts.maxMultiplier ?? 6
+
+		const dt = this.lastTickTime ? now - this.lastTickTime : Infinity
+
+		// Reset if too much time passed
+		if (dt === Infinity || dt > this.streakTimeout) {
+			this.lastTickTime = now
+			this.velocityHistory = []
+			return 1
+		}
+
+		// Ignore duplicate ticks (terminal quirks)
+		if (dt < this.minTickInterval) {
+			return 1
+		}
+
+		this.lastTickTime = now
+		this.velocityHistory.push(dt)
+		if (this.velocityHistory.length > this.historySize) {
+			this.velocityHistory.shift()
+		}
+
+		// Calculate average interval (lower = faster scrolling)
+		const avgInterval = this.velocityHistory.reduce((a, b) => a + b, 0) / this.velocityHistory.length
+
+		// Convert to velocity: faster ticks = higher velocity
+		const referenceInterval = 100
+		const velocity = referenceInterval / avgInterval
+
+		// Apply exponential curve
+		const x = velocity / tau
+		const multiplier = 1 + A * (Math.exp(x) - 1)
+
+		return Math.min(multiplier, maxMultiplier)
+	}
+
+	reset(): void {
+		this.lastTickTime = 0
+		this.velocityHistory = []
+	}
+}
+
+// ============================================================================
+// Scroll State
+// ============================================================================
+
+export interface ScrollState {
+	/** Current scroll offset (pixels from start) */
+	offset: number
+	/** Maximum scroll offset */
+	maxOffset: number
+	/** Viewport height (or width for horizontal) */
+	viewportSize: number
+	/** Total content size */
+	contentSize: number
+	/** Whether we're at the start edge */
+	atStart: boolean
+	/** Whether we're at the end edge */
+	atEnd: boolean
+}
+
+export interface UseScrollOptions {
+	/** Scroll axis: "vertical" (default) or "horizontal" */
+	axis?: "vertical" | "horizontal"
+	/** Initial scroll offset */
+	initialOffset?: number
+	/** Enable keyboard navigation (default: true) */
+	enableKeyboard?: boolean
+	/** Enable mouse wheel (default: true) */
+	enableMouseWheel?: boolean
+	/** Enable scroll acceleration (default: true) */
+	enableAcceleration?: boolean
+	/** Sticky scroll - auto-scroll to end when content grows (default: false) */
+	sticky?: boolean
+	/** Scroll speed for arrow keys (pixels, default: 1) */
+	arrowSpeed?: number
+	/** Scroll speed for page up/down (fraction of viewport, default: 0.5) */
+	pageSpeed?: number
+}
+
+export interface UseScrollReturn {
+	/** Current scroll state */
+	state: ScrollState
+	/** Set scroll offset directly */
+	setOffset: (offset: number) => void
+	/** Scroll by delta pixels */
+	scrollBy: (delta: number) => void
+	/** Scroll to start */
+	scrollToStart: () => void
+	/** Scroll to end */
+	scrollToEnd: () => void
+	/**
+	 * Scroll to make a position visible in the viewport.
+	 * Useful for keeping a selected item in view.
+	 * @param position - The position (row/col index or pixel offset)
+	 * @param itemSize - Size of each item (default: 1 for row-based lists)
+	 * @param padding - Extra padding around the item (default: 0)
+	 */
+	scrollToVisible: (position: number, itemSize?: number, padding?: number) => void
+	/** Props to spread on <scroll> element */
+	scrollProps: {
+		offset: number
+		axis: "vertical" | "horizontal"
+		onContentSize: (width: number, height: number) => void
+		onViewportSize: (width: number, height: number) => void
+	}
+}
+
+/**
+ * Hook for managing scroll state with keyboard/mouse input.
+ *
+ * @example
+ * ```tsx
+ * function ScrollableList({ items }) {
+ *   const { state, scrollProps } = useScroll({ sticky: true })
+ *
+ *   return (
+ *     <scroll {...scrollProps}>
+ *       <vstack>
+ *         {items.map(item => <text key={item.id}>{item.text}</text>)}
+ *       </vstack>
+ *     </scroll>
+ *   )
+ * }
+ * ```
+ */
+export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
+	const {
+		axis = "vertical",
+		initialOffset = 0,
+		enableKeyboard = true,
+		enableMouseWheel = true,
+		enableAcceleration = true,
+		sticky = false,
+		arrowSpeed = 1,
+		pageSpeed = 0.5,
+	} = options
+
+	const { width: termWidth, height: termHeight } = useTerminalSize()
+
+	// Scroll state
+	const [offset, setOffsetRaw] = useState(initialOffset)
+	const [contentSize, setContentSize] = useState(0)
+	// Use terminal size as initial estimate, but scroll component will report actual size
+	const [viewportSize, setViewportSize] = useState(axis === "vertical" ? termHeight : termWidth)
+
+	// Refs for sticky scroll behavior
+	const wasAtEndRef = useRef(sticky)
+	const prevContentSizeRef = useRef(0)
+
+	// Scroll acceleration
+	const accel = useMemo(
+		() => (enableAcceleration ? new MacOSScrollAccel() : { tick: () => 1, reset: () => {} }),
+		[enableAcceleration],
+	)
+
+	// Fractional accumulator for smooth sub-pixel scrolling
+	const accumulatorRef = useRef(0)
+
+	// Ref for scrollToVisible so it doesn't change on every scroll
+	const offsetRef = useRef(offset)
+	offsetRef.current = offset
+
+	// Calculate derived state
+	const maxOffset = Math.max(0, contentSize - viewportSize)
+	const atStart = offset <= 0
+	const atEnd = offset >= maxOffset
+
+	// Clamp and set offset
+	const setOffset = useCallback(
+		(newOffset: number) => {
+			const clamped = Math.max(0, Math.min(maxOffset, newOffset))
+			setOffsetRaw(clamped)
+			// Track if we're at end for sticky behavior
+			wasAtEndRef.current = clamped >= maxOffset - 1
+		},
+		[maxOffset],
+	)
+
+	// Scroll by delta with accumulator for fractional scrolling
+	const scrollBy = useCallback(
+		(delta: number) => {
+			accumulatorRef.current += delta
+			const integerDelta = Math.trunc(accumulatorRef.current)
+			if (integerDelta !== 0) {
+				setOffset(offset + integerDelta)
+				accumulatorRef.current -= integerDelta
+			}
+		},
+		[offset, setOffset],
+	)
+
+	const scrollToStart = useCallback(() => {
+		setOffset(0)
+		accumulatorRef.current = 0
+		accel.reset()
+	}, [setOffset, accel])
+
+	const scrollToEnd = useCallback(() => {
+		setOffset(maxOffset)
+		accumulatorRef.current = 0
+		accel.reset()
+	}, [setOffset, maxOffset, accel])
+
+	// Handle content size changes (for sticky scroll)
+	const handleContentSize = useCallback(
+		(width: number, height: number) => {
+			const newSize = axis === "vertical" ? height : width
+			setContentSize(newSize)
+			prevContentSizeRef.current = newSize
+		},
+		[axis],
+	)
+
+	// Synchronous sticky scroll: snap to end when content grows
+	// useLayoutEffect runs synchronously after React commit but before paint
+	useLayoutEffect(() => {
+		if (!sticky) return
+		const newMaxOffset = Math.max(0, contentSize - viewportSize)
+		if (wasAtEndRef.current && contentSize > 0) {
+			setOffsetRaw(newMaxOffset)
+		}
+	}, [sticky, contentSize, viewportSize])
+
+	// Handle viewport size changes (reported by scroll component)
+	const handleViewportSize = useCallback(
+		(width: number, height: number) => {
+			const newSize = axis === "vertical" ? height : width
+			setViewportSize(newSize)
+		},
+		[axis],
+	)
+
+	// Keyboard handler
+	const handleKey = useCallback(
+		(key: KeyMsg) => {
+			// Mouse wheel comes as pageup/pagedown with meta=true
+			// Handle separately from keyboard since enableKeyboard shouldn't disable mouse
+			if (key.meta && enableMouseWheel && (key.name === "pageup" || key.name === "pagedown")) {
+				const multiplier = accel.tick()
+				const delta = Math.ceil(arrowSpeed * multiplier)
+				scrollBy(key.name === "pageup" ? -delta : delta)
+				return
+			}
+
+			if (!enableKeyboard) return
+
+			const isVertical = axis === "vertical"
+			const upKey = isVertical ? "up" : "left"
+			const downKey = isVertical ? "down" : "right"
+
+			switch (key.name) {
+				case upKey:
+					scrollBy(-arrowSpeed)
+					break
+				case downKey:
+					scrollBy(arrowSpeed)
+					break
+				case "pageup":
+					scrollBy(-Math.floor(viewportSize * pageSpeed))
+					break
+				case "pagedown":
+					scrollBy(Math.floor(viewportSize * pageSpeed))
+					break
+				case "home":
+					scrollToStart()
+					break
+				case "end":
+					scrollToEnd()
+					break
+			}
+		},
+		[
+			enableKeyboard,
+			axis,
+			arrowSpeed,
+			pageSpeed,
+			viewportSize,
+			enableMouseWheel,
+			accel,
+			scrollBy,
+			scrollToStart,
+			scrollToEnd,
+		],
+	)
+
+	useKeyboard(handleKey)
+
+	// Scroll to make a position visible (for keeping selection in view)
+	// Uses refs to avoid changing on every scroll - only triggers when selection changes
+	const scrollToVisible = useCallback(
+		(position: number, itemSize = 1, padding = 0) => {
+			const currentOffset = offsetRef.current
+			const itemStart = position * itemSize
+			const itemEnd = itemStart + itemSize
+
+			// If item is above viewport, scroll up to show it
+			if (itemStart < currentOffset + padding) {
+				setOffset(Math.max(0, itemStart - padding))
+			}
+			// If item is below viewport, scroll down to show it
+			else if (itemEnd > currentOffset + viewportSize - padding) {
+				const currentMaxOffset = Math.max(0, contentSize - viewportSize)
+				setOffset(Math.min(currentMaxOffset, itemEnd - viewportSize + padding))
+			}
+		},
+		[viewportSize, contentSize, setOffset],
+	)
+
+	const state: ScrollState = {
+		offset,
+		maxOffset,
+		viewportSize,
+		contentSize,
+		atStart,
+		atEnd,
+	}
+
+	// Handle effective offset sync from host (when sticky adjusts the offset)
+	const handleEffectiveOffset = useCallback(
+		(effectiveOffset: number) => {
+			// Sync the ref so scrollToVisible uses the actual rendered position
+			offsetRef.current = effectiveOffset
+			// Also update state to keep in sync (but don't trigger wasAtEnd change)
+			setOffsetRaw(effectiveOffset)
+		},
+		[],
+	)
+
+	const scrollProps = {
+		offset,
+		axis,
+		onContentSize: handleContentSize,
+		onViewportSize: handleViewportSize,
+		onEffectiveOffset: handleEffectiveOffset,
+	}
+
+	return {
+		state,
+		setOffset,
+		scrollBy,
+		scrollToStart,
+		scrollToEnd,
+		scrollToVisible,
+		scrollProps,
+	}
+}

package/src/hooks/useFrameStats.ts

@@ -7,26 +7,26 @@ import type { FrameStats } from "../renderer.js"
  * Falls back to null when the renderer does not support onFrameStats.
  */
 export function useFrameStats(sampleMs = 200): FrameStats | null {
-  const renderer = useRenderer()
-  const [stats, setStats] = useState<FrameStats | null>(null)
+	const renderer = useRenderer()
+	const [stats, setStats] = useState<FrameStats | null>(null)
 
-  useEffect(() => {
-    if (!renderer.onFrameStats) return
+	useEffect(() => {
+		if (!renderer.onFrameStats) return
 
-    let last: FrameStats | null = null
-    const unsub = renderer.onFrameStats((s) => {
-      last = s
-    })
+		let last: FrameStats | null = null
+		const unsub = renderer.onFrameStats((s) => {
+			last = s
+		})
 
-    const id = setInterval(() => {
-      if (last) setStats(last)
-    }, sampleMs)
+		const id = setInterval(() => {
+			if (last) setStats(last)
+		}, sampleMs)
 
-    return () => {
-      clearInterval(id)
-      unsub?.()
-    }
-  }, [renderer, sampleMs])
+		return () => {
+			clearInterval(id)
+			unsub?.()
+		}
+	}, [renderer, sampleMs])
 
-  return stats
+	return stats
 }

package/src/hosts/base.ts

@@ -1,65 +1,186 @@
-import type { CellBuffer, Palette } from "@effect-tui/core"
+import type { CellBuffer, Palette, Color } from "@effect-tui/core"
 import type { HostInstance, Rect, Size, HostContext, CommonProps } from "../reconciler/types.js"
 
+/** Host that may have a background color (e.g., BoxHost) */
+export interface HostWithBg extends HostInstance {
+	bg?: Color
+}
+
+/** Type guard for hosts with bg property */
+function hasBackground(host: HostInstance): host is HostWithBg {
+	return "bg" in host
+}
+
+/** Walk up parent chain to find inherited background color */
+export function getInheritedBg(startParent: HostInstance | null): Color | undefined {
+	let p: HostInstance | null = startParent
+	while (p) {
+		if (hasBackground(p) && p.bg !== undefined) {
+			return p.bg
+		}
+		p = p.parent
+	}
+	return undefined
+}
+
 let idCounter = 0
 
 export abstract class BaseHost implements HostInstance {
-  id: string
-  type: string
-  parent: HostInstance | null = null
-  children: HostInstance[] = []
-  rect: Rect | null = null
-
-  // Common flex props
-  flexGrow = 0
-  flexShrink = 1
-
-  protected ctx: HostContext
-
-  constructor(type: string, props: CommonProps, ctx: HostContext) {
-    this.id = `${type}-${idCounter++}`
-    this.type = type
-    this.ctx = ctx
-    this.updateProps(props)
-  }
-
-  abstract measure(maxW: number, maxH: number): Size
-  abstract render(buffer: CellBuffer, palette: Palette): void
-
-  layout(rect: Rect): void {
-    this.rect = rect
-  }
-
-  updateProps(props: Record<string, unknown>): void {
-    if (props.flexGrow !== undefined) this.flexGrow = props.flexGrow as number
-    if (props.flexShrink !== undefined) this.flexShrink = props.flexShrink as number
-  }
-
-  destroy(): void {
-    // Override in subclasses if cleanup needed
-  }
-
-  // Child management helpers
-  appendChild(child: HostInstance): void {
-    this.children.push(child)
-    child.parent = this
-  }
-
-  removeChild(child: HostInstance): void {
-    const idx = this.children.indexOf(child)
-    if (idx >= 0) {
-      this.children.splice(idx, 1)
-      child.parent = null
-    }
-  }
-
-  insertBefore(child: HostInstance, before: HostInstance): void {
-    const idx = this.children.indexOf(before)
-    if (idx >= 0) {
-      this.children.splice(idx, 0, child)
-    } else {
-      this.children.push(child)
-    }
-    child.parent = this
-  }
+	id: string
+	type: string
+	parent: HostInstance | null = null
+	children: HostInstance[] = []
+	rect: Rect | null = null
+
+	// Common flex props
+	flexGrow = 0
+	flexShrink = 1
+
+	// ─────────────────────────────────────────────────────────────
+	// Frame constraints (like SwiftUI's .frame modifier)
+	// See CommonProps for detailed documentation
+	// ─────────────────────────────────────────────────────────────
+	frameWidth?: number
+	frameHeight?: number
+	frameMinWidth?: number
+	frameMaxWidth?: number
+	frameMinHeight?: number
+	frameMaxHeight?: number
+
+	/** @internal Marks this node as static content (for Static component) */
+	__static?: boolean
+
+	protected ctx: HostContext
+
+	constructor(type: string, props: CommonProps, ctx: HostContext) {
+		this.id = `${type}-${idCounter++}`
+		this.type = type
+		this.ctx = ctx
+		// NOTE: Subclasses must call this.updateProps(props) after super()
+		// because JavaScript field initializers run AFTER parent constructor,
+		// which would overwrite any values set here.
+	}
+
+	abstract measure(maxW: number, maxH: number): Size
+	abstract render(buffer: CellBuffer, palette: Palette): void
+
+	layout(rect: Rect): void {
+		this.rect = rect
+	}
+
+	/**
+	 * Apply frame constraints to a proposed size before passing to children.
+	 *
+	 * This is the first half of SwiftUI-style frame semantics. When a parent
+	 * proposes a size to us, we modify it based on our constraints before
+	 * passing it down to our children.
+	 *
+	 * @example
+	 * ```
+	 * Parent proposes: 100x100
+	 * Our height constraint: 10
+	 * We propose to children: 100x10
+	 * ```
+	 *
+	 * This prevents greedy children (like scroll) from measuring larger than
+	 * our constrained size.
+	 *
+	 * @param maxW - Width proposed by parent
+	 * @param maxH - Height proposed by parent
+	 * @returns Constrained size to propose to children
+	 */
+	protected constrainProposal(maxW: number, maxH: number): { w: number; h: number } {
+		let w = maxW
+		let h = maxH
+
+		// Fixed width/height override everything
+		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)
+
+		return { w, h }
+	}
+
+	/**
+	 * Apply frame constraints to our measured size before returning to parent.
+	 *
+	 * This is the second half of SwiftUI-style frame semantics. After measuring
+	 * our children, we modify our reported size based on our constraints before
+	 * returning it to our parent.
+	 *
+	 * @example
+	 * ```
+	 * Children measured: 5x1 (small content)
+	 * Our height constraint: 10
+	 * We report to parent: 5x10
+	 * ```
+	 *
+	 * This ensures we report our constrained size regardless of children's
+	 * natural size, which is essential for layout composition (e.g., spacer
+	 * needs to know our fixed size to calculate remaining space).
+	 *
+	 * @param size - Natural size from measuring children
+	 * @returns Constrained size to report to parent
+	 */
+	protected constrainResult(size: Size): Size {
+		let { w, h } = size
+
+		// Fixed width/height override the measured size
+		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)
+
+		return { w, h }
+	}
+
+	updateProps(props: Record<string, unknown>): void {
+		this.flexGrow = (props.flexGrow as number | undefined) ?? 0
+		this.flexShrink = (props.flexShrink as number | undefined) ?? 1
+
+		// Frame constraints
+		this.frameWidth = props.width as number | undefined
+		this.frameHeight = props.height as number | undefined
+		this.frameMinWidth = props.minWidth as number | undefined
+		this.frameMaxWidth = props.maxWidth as number | undefined
+		this.frameMinHeight = props.minHeight as number | undefined
+		this.frameMaxHeight = props.maxHeight as number | undefined
+	}
+
+	destroy(): void {
+		// Override in subclasses if cleanup needed
+	}
+
+	// Child management helpers
+	appendChild(child: HostInstance): void {
+		this.children.push(child)
+		child.parent = this
+	}
+
+	removeChild(child: HostInstance): void {
+		const idx = this.children.indexOf(child)
+		if (idx >= 0) {
+			this.children.splice(idx, 1)
+			child.parent = null
+		}
+	}
+
+	insertBefore(child: HostInstance, before: HostInstance): void {
+		const idx = this.children.indexOf(before)
+		if (idx >= 0) {
+			this.children.splice(idx, 0, child)
+		} else {
+			this.children.push(child)
+		}
+		child.parent = this
+	}
 }