@effect-tui/react 0.1.1 → 0.1.4

package/src/hosts/overlay.ts

@@ -0,0 +1,125 @@
+/**
+ * Overlay host - SwiftUI-style overlay layout
+ *
+ * Unlike zstack (which sizes to MAX of all children), overlay:
+ * 1. First child is the "base" - determines the container size
+ * 2. Subsequent children (overlayItem) are overlaid without affecting measurement
+ * 3. Each overlayItem specifies its own alignment
+ *
+ * Usage with compound component:
+ * ```tsx
+ * <Overlay>
+ *   <MainContent />
+ *   <Overlay.Item alignment={{ v: "top" }}><Toast /></Overlay.Item>
+ *   <Overlay.Item alignment={{ v: "bottom" }}><Console /></Overlay.Item>
+ * </Overlay>
+ * ```
+ */
+
+import type { CellBuffer, Palette, Rect, Size } from "@effect-tui/core"
+import type { HostContext, CommonProps } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+import type { OverlayItemHost } from "./overlay-item.js"
+
+export interface OverlayProps extends CommonProps {}
+
+export class OverlayHost extends BaseHost {
+	private cachedSizes: Size[] = []
+
+	constructor(props: OverlayProps, ctx: HostContext) {
+		super("overlay", props, ctx)
+	}
+
+	override measure(maxW: number, maxH: number): Size {
+		// Apply frame constraints to what we propose to children
+		const constrained = this.constrainProposal(maxW, maxH)
+
+		// Only first child determines our size
+		const baseChild = this.children[0]
+		if (!baseChild) {
+			return this.constrainResult({ w: 0, h: 0 })
+		}
+
+		const baseSize = baseChild.measure(constrained.w, constrained.h)
+		this.cachedSizes = [baseSize]
+
+		// Measure overlay children with the base size
+		// They don't affect our size, but need to know their constraints
+		for (let i = 1; i < this.children.length; i++) {
+			const size = this.children[i].measure(baseSize.w, baseSize.h)
+			this.cachedSizes.push(size)
+		}
+
+		// Return base size (overlay children don't affect our size)
+		return this.constrainResult(baseSize)
+	}
+
+	override layout(rect: Rect): void {
+		this.rect = rect
+
+		// Layout base child to fill our rect
+		const baseChild = this.children[0]
+		if (baseChild) {
+			baseChild.layout(rect)
+		}
+
+		// Layout overlay children with their alignment
+		for (let i = 1; i < this.children.length; i++) {
+			const child = this.children[i]
+			const size = this.cachedSizes[i] ?? child.measure(rect.w, rect.h)
+
+			// Read alignment from OverlayItemHost (use type check, not instanceof, for bundler compatibility)
+			const alignment = child.type === "overlayItem" ? (child as OverlayItemHost).alignment : {}
+			const hAlign = alignment.h ?? "center"
+			const vAlign = alignment.v ?? "center"
+
+			// Calculate position based on alignment
+			let x = rect.x
+			let y = rect.y
+
+			switch (hAlign) {
+				case "left":
+					x = rect.x
+					break
+				case "center":
+					x = rect.x + Math.floor((rect.w - size.w) / 2)
+					break
+				case "right":
+					x = rect.x + rect.w - size.w
+					break
+			}
+
+			switch (vAlign) {
+				case "top":
+					y = rect.y
+					break
+				case "center":
+					y = rect.y + Math.floor((rect.h - size.h) / 2)
+					break
+				case "bottom":
+					y = rect.y + rect.h - size.h
+					break
+			}
+
+			child.layout({
+				x,
+				y,
+				w: Math.min(rect.w, size.w),
+				h: Math.min(rect.h, size.h),
+			})
+		}
+	}
+
+	override render(buffer: CellBuffer, palette: Palette): void {
+		// Render all children in order (base first, then overlays)
+		for (const child of this.children) {
+			if (child.rect) {
+				buffer.withClip(child.rect.x, child.rect.y, child.rect.w, child.rect.h, () => {
+					child.render(buffer, palette)
+				})
+			} else {
+				child.render(buffer, palette)
+			}
+		}
+	}
+}

package/src/hosts/scroll.ts

@@ -0,0 +1,255 @@
+// scroll.ts — Scrollable container host
+import type { CellBuffer, Palette, Color } from "@effect-tui/core"
+import type { HostContext, Rect, Size, CommonProps } from "../reconciler/types.js"
+import { getInheritedBg } from "./base.js"
+import { SingleChildHost } from "./single-child.js"
+import { resolveBgStyle } from "../utils/index.js"
+
+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" */
+	offsetX?: number
+	/** Alignment when content is smaller than viewport */
+	align?: "start" | "end"
+	/** Background color for the scroll viewport */
+	bg?: Color
+	/** Whether to show scrollbar indicators */
+	showScrollbar?: boolean
+	/**
+	 * Sticky scroll - automatically stay at end when content grows.
+	 * 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
+}
+
+export class ScrollHost extends SingleChildHost {
+	axis: "vertical" | "horizontal" | "both" = "vertical"
+	offset = 0
+	offsetX = 0
+	align: "start" | "end" = "start"
+	bg?: Color
+	showScrollbar = true
+	sticky = false
+	onContentSize?: (width: number, height: number) => void
+	onViewportSize?: (width: number, height: number) => void
+	onEffectiveOffset?: (offset: number) => void
+
+	// Measured content dimensions (full size before clipping)
+	private contentWidth = 0
+	private contentHeight = 0
+	// Track last reported sizes to avoid redundant callbacks
+	private lastViewportW = 0
+	private lastViewportH = 0
+	private lastReportedContentW = 0
+	private lastReportedContentH = 0
+	// Track if we were at end (for sticky behavior)
+	private wasAtEnd = true
+	// Effective offset after sticky adjustment (used for rendering)
+	private effectiveOffset = 0
+	private effectiveOffsetX = 0
+
+	constructor(props: ScrollProps, ctx: HostContext) {
+		super("scroll", props, ctx)
+		this.updateProps(props)
+	}
+
+	measure(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
+		}
+		if (this.axis === "horizontal" || this.axis === "both") {
+			childMaxW = Number.MAX_SAFE_INTEGER
+		}
+
+		// 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
+		}
+
+		// Scroll container is greedy - takes all available space (after constraints)
+		return this.constrainResult({ w: constrained.w, h: constrained.h })
+	}
+
+	override layout(rect: Rect): void {
+		super.layout(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 (rect.w !== this.lastViewportW || rect.h !== this.lastViewportH) {
+			this.lastViewportW = rect.w
+			this.lastViewportH = rect.h
+			this.onViewportSize?.(rect.w, rect.h)
+		}
+
+		const child = this.child
+		if (!child) return
+
+		// Calculate max scroll offsets
+		const maxScrollY = Math.max(0, this.contentHeight - rect.h)
+		const maxScrollX = Math.max(0, this.contentWidth - rect.w)
+
+		// Start with the offset from props (controlled by useScroll)
+		let scrollY = this.offset
+		let scrollX = this.offsetX
+
+		// Sticky scroll logic:
+		// - 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) {
+			// Detect if user scrolled away (offset prop is less than where we rendered)
+			const userScrolledAway = this.offset < this.effectiveOffset - 1
+
+			if (userScrolledAway) {
+				// User scrolled up - unstick
+				this.wasAtEnd = false
+			} else if (this.wasAtEnd) {
+				// Was at end, content may have grown - stay at end
+				scrollY = maxScrollY
+			}
+		}
+
+		// Track if we're at end for next frame
+		this.wasAtEnd = scrollY >= maxScrollY - 1
+
+		// Clamp offsets
+		scrollY = Math.max(0, Math.min(maxScrollY, scrollY))
+		scrollX = Math.max(0, Math.min(maxScrollX, scrollX))
+
+		// Store effective offsets for rendering (scrollbar position)
+		// Report back if changed (for useScroll to sync its state)
+		if (scrollY !== this.effectiveOffset) {
+			this.onEffectiveOffset?.(scrollY)
+		}
+		this.effectiveOffset = scrollY
+		this.effectiveOffsetX = scrollX
+
+		// Handle alignment when content is smaller than viewport
+		if (this.align === "end") {
+			if (this.contentHeight < rect.h && (this.axis === "vertical" || this.axis === "both")) {
+				// Align to bottom
+				scrollY = -(rect.h - this.contentHeight)
+			}
+			if (this.contentWidth < rect.w && (this.axis === "horizontal" || this.axis === "both")) {
+				// Align to right
+				scrollX = -(rect.w - this.contentWidth)
+			}
+		}
+
+		// Layout child at offset position
+		const childRect: Rect = {
+			x: rect.x - scrollX,
+			y: rect.y - scrollY,
+			w: this.contentWidth,
+			h: this.contentHeight,
+		}
+		child.layout(childRect)
+	}
+
+	render(buffer: CellBuffer, palette: Palette): void {
+		if (!this.rect) return
+		const { x, y, w, h } = this.rect
+
+		// Fill background
+		const rawBg: Color | undefined = this.bg ?? getInheritedBg(this.parent)
+		const { value: bgValue, styleId: bgStyleId } = resolveBgStyle(palette, rawBg)
+		if (bgValue !== undefined) {
+			buffer.fillRect(x, y, w, h, " ".codePointAt(0)!, bgStyleId)
+		}
+
+		// Render children with clipping
+		buffer.withClip(x, y, w, h, () => {
+			const child = this.child
+			if (child) {
+				child.render(buffer, palette)
+			}
+		})
+
+		// Draw scrollbar indicators
+		if (this.showScrollbar) {
+			this.renderScrollbars(buffer, palette)
+		}
+	}
+
+	private renderScrollbars(buffer: CellBuffer, palette: Palette): void {
+		if (!this.rect) return
+		const { x, y, w, h } = this.rect
+
+		// Vertical scrollbar
+		if ((this.axis === "vertical" || this.axis === "both") && this.contentHeight > h) {
+			const maxScroll = this.contentHeight - h
+			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 trackStyle = palette.id({ fg: 8 }) // dim
+			const thumbStyle = palette.id({ fg: 7 }) // brighter
+
+			// Draw track
+			for (let row = 0; row < h; 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)
+			}
+		}
+
+		// Horizontal scrollbar
+		if ((this.axis === "horizontal" || this.axis === "both") && this.contentWidth > w) {
+			const maxScroll = this.contentWidth - w
+			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 trackStyle = palette.id({ fg: 8 })
+			const thumbStyle = palette.id({ fg: 7 })
+
+			// Draw track
+			for (let col = 0; col < w; 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)
+			}
+		}
+	}
+
+	override updateProps(props: Record<string, unknown>): void {
+		super.updateProps(props)
+		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
+		if (props.align !== undefined) this.align = (props.align as ScrollProps["align"]) ?? "start"
+		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"]
+	}
+}

package/src/hosts/single-child.ts

@@ -0,0 +1,52 @@
+import type { HostInstance, CommonProps, HostContext } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+
+/**
+ * Base host that enforces a single child.
+ * Additional children replace the existing child and emit a warning once.
+ */
+export abstract class SingleChildHost extends BaseHost {
+	private warned = false
+
+	constructor(type: string, props: CommonProps, ctx: HostContext) {
+		super(type, props, ctx)
+	}
+
+	protected get child(): HostInstance | null {
+		return this.children[0] ?? null
+	}
+
+	override appendChild(child: HostInstance): void {
+		this.setSingleChild(child)
+	}
+
+	override insertBefore(child: HostInstance, _before: HostInstance): void {
+		this.setSingleChild(child)
+	}
+
+	override removeChild(child: HostInstance): void {
+		const current = this.children[0]
+		if (current === child) {
+			this.children.splice(0, 1)
+		}
+		child.parent = null
+	}
+
+	private setSingleChild(child: HostInstance): void {
+		const current = this.children[0]
+		if (current === child) return
+
+		if (current) {
+			if (!this.warned) {
+				console.warn(`[effect-tui] <${this.type}> only supports a single child; replacing previous child.`)
+				this.warned = true
+			}
+			current.parent = null
+			this.children[0] = child
+		} else {
+			this.children.push(child)
+		}
+
+		child.parent = this
+	}
+}

package/src/hosts/spacer.ts

@@ -3,38 +3,42 @@ import type { HostContext, Rect, Size, CommonProps } from "../reconciler/types.j
 import { BaseHost } from "./base.js"
 
 export interface SpacerProps extends CommonProps {
-  /** Minimum width (default 0) */
-  minWidth?: number
-  /** Minimum height (default 0) */
-  minHeight?: number
+	/** Minimum width (default 0) */
+	minWidth?: number
+	/** Minimum height (default 0) */
+	minHeight?: number
 }
 
 export class SpacerHost extends BaseHost {
-  minWidth = 0
-  minHeight = 0
+	minWidth = 0
+	minHeight = 0
 
-  constructor(props: SpacerProps, ctx: HostContext) {
-    // Spacers have flexGrow=1 by default
-    super("spacer", { flexGrow: 1, ...props }, ctx)
-    this.updateProps(props)
-  }
+	constructor(props: SpacerProps, ctx: HostContext) {
+		// Spacers have flexGrow=1 by default
+		const propsWithDefaults = { flexGrow: 1, ...props }
+		super("spacer", propsWithDefaults, ctx)
+		this.updateProps(propsWithDefaults)
+	}
 
-  measure(_maxW: number, _maxH: number): Size {
-    // Spacers have no natural size, they expand via flexGrow
-    return { w: this.minWidth, h: this.minHeight }
-  }
+	measure(_maxW: number, _maxH: number): Size {
+		// Spacers have no natural size, they expand via flexGrow
+		return { w: this.minWidth, h: this.minHeight }
+	}
 
-  override layout(rect: Rect): void {
-    super.layout(rect)
-  }
+	override layout(rect: Rect): void {
+		super.layout(rect)
+	}
 
-  render(_buffer: CellBuffer, _palette: Palette): void {
-    // Spacers render nothing
-  }
+	render(_buffer: CellBuffer, _palette: Palette): void {
+		// Spacers render nothing
+	}
 
-  override updateProps(props: Record<string, unknown>): void {
-    super.updateProps(props)
-    if (props.minWidth !== undefined) this.minWidth = props.minWidth as number
-    if (props.minHeight !== undefined) this.minHeight = props.minHeight as number
-  }
+	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)
+		if (props.minWidth !== undefined) this.minWidth = props.minWidth as number
+		if (props.minHeight !== undefined) this.minHeight = props.minHeight as number
+	}
 }