@effect-tui/react 0.1.0-alpha.1

package/src/hosts/codeblock.ts

@@ -0,0 +1,145 @@
+import {
+  Colors,
+  displayWidth,
+  parseColor,
+  type CellBuffer,
+  type ColorLike,
+  type Palette,
+  type ColorValue,
+} from "@effect-tui/core"
+import type { HighlightLine } from "../highlight.js"
+import type { HostContext, Rect, Size, CommonProps } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+import { type Padding, type PaddingInput, resolvePadding } from "../utils/index.js"
+
+export interface CodeBlockProps extends CommonProps {
+  lines: HighlightLine[]
+  lineNumbers?: boolean
+  padding?: PaddingInput
+  background?: ColorLike
+  lineNumberColor?: ColorLike
+  lineNumberBackground?: ColorLike
+}
+
+function normalizeColor(c: unknown): ColorValue | undefined {
+  if (c === undefined || c === null) return undefined
+  if (typeof c === "number" || typeof c === "object") return c as ColorValue
+  return parseColor(c as string)
+}
+
+function lineDisplayWidth(line: HighlightLine): number {
+  return line.reduce((w, token) => w + displayWidth(token.text), 0)
+}
+
+export class CodeBlockHost extends BaseHost {
+  lines: HighlightLine[] = [[]]
+  lineNumbers = false
+  padding: Padding = { top: 0, right: 0, bottom: 0, left: 0 }
+  background?: ColorLike
+  lineNumberColor?: ColorLike
+  lineNumberBackground?: ColorLike
+
+  private cachedLineWidths: number[] = []
+  private gutterWidth = 0
+
+  constructor(props: CodeBlockProps, ctx: HostContext) {
+    super("codeblock", props, ctx)
+    this.updateProps(props)
+  }
+
+  private computeGutterWidth(): number {
+    if (!this.lineNumbers) return 0
+    // Fix width so layout doesn't shift when moving from 1→2 digits.
+    const digits = Math.max(2, String(Math.max(1, this.lines.length)).length)
+    // digits plus a trailing space
+    return digits + 1
+  }
+
+  private get insetX(): number {
+    return this.padding.left + this.padding.right + this.gutterWidth
+  }
+
+  private get insetY(): number {
+    return this.padding.top + this.padding.bottom
+  }
+
+  measure(maxW: number, maxH: number): Size {
+    this.cachedLineWidths = this.lines.map((l) => lineDisplayWidth(l))
+    this.gutterWidth = this.computeGutterWidth()
+
+    const maxLineW = this.cachedLineWidths.reduce((max, w) => (w > max ? w : max), 0)
+    const contentW = maxLineW + this.insetX
+
+    const innerHeight = Math.max(1, this.lines.length) + this.insetY
+
+    return {
+      w: Math.min(maxW, contentW),
+      h: Math.min(maxH, innerHeight),
+    }
+  }
+
+  override layout(rect: Rect): void {
+    super.layout(rect)
+  }
+
+  render(buffer: CellBuffer, palette: Palette): void {
+    if (!this.rect) return
+
+    const { x, y, w, h } = this.rect
+    const contentWidth = Math.max(0, w - this.insetX)
+    const maxLines = Math.max(0, Math.min(this.lines.length, h - this.insetY))
+    const startX = x + this.padding.left + this.gutterWidth
+    const startY = y + this.padding.top
+
+    if (this.background !== undefined && w > 0 && h > 0) {
+      const bgStyle = palette.id({ bg: normalizeColor(this.background) })
+      buffer.fillRect(x, y, w, h, " ".codePointAt(0)!, bgStyle)
+    }
+
+    for (let i = 0; i < maxLines; i++) {
+      const lineY = startY + i
+      let drawX = startX
+
+      if (this.lineNumbers) {
+        const gutterStyle = palette.id({
+          fg: normalizeColor(this.lineNumberColor) ?? Colors.gray(11),
+          bg: normalizeColor(this.lineNumberBackground ?? this.background),
+        })
+        const digits = String(i + 1).padStart(this.gutterWidth - 1, " ")
+        buffer.drawText(x + this.padding.left, lineY, `${digits} `, gutterStyle, this.gutterWidth)
+      }
+
+      const line = this.lines[i] ?? []
+      for (const token of line) {
+        if (contentWidth <= 0) break
+        const remaining = x + w - drawX
+        if (remaining <= 0) break
+
+        const style = token.style ?? {}
+        const fg = normalizeColor(style.fg)
+        const bg = normalizeColor(style.bg ?? this.background)
+        const styleId = palette.id({
+          fg,
+          bg,
+          bold: style.bold,
+          italic: style.italic,
+          underline: style.underline,
+        })
+
+        buffer.drawText(drawX, lineY, token.text, styleId, remaining)
+        drawX += displayWidth(token.text)
+        if (drawX >= x + w) break
+      }
+    }
+  }
+
+  override updateProps(props: Record<string, unknown>): void {
+    super.updateProps(props)
+    if (props.lines !== undefined) this.lines = props.lines as HighlightLine[]
+    if (props.lineNumbers !== undefined) this.lineNumbers = !!props.lineNumbers
+    if (props.padding !== undefined) this.padding = resolvePadding(props.padding as CodeBlockProps["padding"])
+    if (props.background !== undefined) this.background = props.background as ColorLike
+    if (props.lineNumberColor !== undefined) this.lineNumberColor = props.lineNumberColor as ColorLike
+    if (props.lineNumberBackground !== undefined) this.lineNumberBackground = props.lineNumberBackground as ColorLike
+  }
+}

package/src/hosts/hstack.ts

@@ -0,0 +1,64 @@
+import type { CellBuffer, Palette } from "@effect-tui/core"
+import type { HostContext, Rect, Size, CommonProps } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+import { measureFlex, layoutFlex, type FlexAlignment } from "../utils/index.js"
+
+export interface HStackProps extends CommonProps {
+  spacing?: number
+  alignment?: "top" | "center" | "bottom"
+}
+
+// Map HStack alignment names to generic flex alignment
+function toFlexAlignment(alignment: "top" | "center" | "bottom"): FlexAlignment {
+  switch (alignment) {
+    case "top":
+      return "start"
+    case "center":
+      return "center"
+    case "bottom":
+      return "end"
+  }
+}
+
+export class HStackHost extends BaseHost {
+  spacing = 0
+  alignment: "top" | "center" | "bottom" = "top"
+  private cachedSizes: Size[] = []
+
+  constructor(props: HStackProps, ctx: HostContext) {
+    super("hstack", props, ctx)
+    this.updateProps(props)
+  }
+
+  measure(maxW: number, maxH: number): Size {
+    const result = measureFlex("horizontal", this.children, this.spacing, maxW, maxH)
+    this.cachedSizes = result.sizes
+    return result.totalSize
+  }
+
+  override layout(rect: Rect): void {
+    super.layout(rect)
+    const stretchCross = this.alignment === "top"
+    layoutFlex(
+      "horizontal",
+      this.children,
+      this.cachedSizes,
+      rect,
+      this.spacing,
+      toFlexAlignment(this.alignment),
+      stretchCross,
+    )
+  }
+
+  render(buffer: CellBuffer, palette: Palette): void {
+    for (const child of this.children) {
+      child.render(buffer, palette)
+    }
+  }
+
+  override updateProps(props: Record<string, unknown>): void {
+    super.updateProps(props)
+    if (props.spacing !== undefined) this.spacing = props.spacing as number
+    if (props.alignment !== undefined) this.alignment = props.alignment as "top" | "center" | "bottom"
+  }
+}

package/src/hosts/index.ts

@@ -0,0 +1,45 @@
+import type { HostContext, CommonProps } from "../reconciler/types.js"
+import type { BaseHost } from "./base.js"
+import { TextHost, RawTextHost } from "./text.js"
+import { SpacerHost } from "./spacer.js"
+import { VStackHost } from "./vstack.js"
+import { HStackHost } from "./hstack.js"
+import { ZStackHost } from "./zstack.js"
+import { BoxHost } from "./box.js"
+import { CanvasHost } from "./canvas.js"
+import { CodeBlockHost } from "./codeblock.js"
+
+export { BaseHost } from "./base.js"
+export { TextHost, RawTextHost, type TextProps } from "./text.js"
+export { SpacerHost, type SpacerProps } from "./spacer.js"
+export { VStackHost, type VStackProps } from "./vstack.js"
+export { HStackHost, type HStackProps } from "./hstack.js"
+export { ZStackHost, type ZStackProps } from "./zstack.js"
+export { BoxHost, type BoxProps } from "./box.js"
+export { CanvasHost, type CanvasProps, type DrawContext } from "./canvas.js"
+export { CodeBlockHost, type CodeBlockProps } from "./codeblock.js"
+
+// Use any to allow specialized props on each host type
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const hostRegistry: Record<string, new (props: any, ctx: HostContext) => BaseHost> = {
+  text: TextHost,
+  spacer: SpacerHost,
+  vstack: VStackHost,
+  hstack: HStackHost,
+  zstack: ZStackHost,
+  box: BoxHost,
+  canvas: CanvasHost,
+  codeblock: CodeBlockHost,
+}
+
+export function createHostInstance(type: string, props: CommonProps, ctx: HostContext): BaseHost {
+  const Host = hostRegistry[type]
+  if (!Host) {
+    throw new Error(`Unknown host component type: ${type}`)
+  }
+  return new Host(props, ctx)
+}
+
+export function createTextInstance(text: string, ctx: HostContext): RawTextHost {
+  return new RawTextHost(text, ctx)
+}

package/src/hosts/spacer.ts

@@ -0,0 +1,40 @@
+import type { CellBuffer, Palette } from "@effect-tui/core"
+import type { HostContext, Rect, Size, CommonProps } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+
+export interface SpacerProps extends CommonProps {
+  /** Minimum width (default 0) */
+  minWidth?: number
+  /** Minimum height (default 0) */
+  minHeight?: number
+}
+
+export class SpacerHost extends BaseHost {
+  minWidth = 0
+  minHeight = 0
+
+  constructor(props: SpacerProps, ctx: HostContext) {
+    // Spacers have flexGrow=1 by default
+    super("spacer", { flexGrow: 1, ...props }, ctx)
+    this.updateProps(props)
+  }
+
+  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)
+  }
+
+  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
+  }
+}

package/src/hosts/text.ts

@@ -0,0 +1,175 @@
+import { displayWidth, parseColor, type CellBuffer, type Palette, type ColorLike } from "@effect-tui/core"
+import type { HostContext, Rect, Size, CommonProps } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+
+export interface TextProps extends CommonProps {
+  fg?: ColorLike
+  bg?: ColorLike
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+  inverse?: boolean
+  /** If true, wrap text to multiple lines (default: false, text is truncated) */
+  wrap?: boolean
+}
+
+export class TextHost extends BaseHost {
+  fg?: ColorLike
+  bg?: ColorLike
+  bold = false
+  italic = false
+  underline = false
+  inverse = false
+  wrap = false // Default: truncate (no wrap)
+
+  // Cache wrapped lines between measure() and render()
+  private cachedLines: string[] | null = null
+  private cachedWidth = 0
+
+  constructor(props: TextProps, ctx: HostContext) {
+    super("text", props, ctx)
+    this.updateProps(props)
+  }
+
+  /** Get text content from RawTextHost children */
+  private getContent(): string {
+    return this.children
+      .filter((c): c is RawTextHost => c instanceof RawTextHost)
+      .map((c) => c.content)
+      .join("")
+  }
+
+  measure(maxW: number, maxH: number): Size {
+    const content = this.getContent()
+    const rawLines = content.split("\n")
+
+    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, maxW), ""] : this.wrapText(line, maxW),
+      )
+      this.cachedWidth = maxW
+      const w = this.cachedLines.reduce((max, line) => Math.max(max, displayWidth(line)), 0)
+      return { w, h: Math.min(this.cachedLines.length, maxH) }
+    }
+
+    // Default: respect explicit newlines but do not wrap long words
+    this.cachedLines = null
+    const widths = rawLines.map((line) => Math.min(displayWidth(line), maxW))
+    const w = widths.reduce((max, val) => Math.max(max, val), 0)
+    const h = Math.min(rawLines.length, maxH)
+    return { w, h }
+  }
+
+  /** Wrap text to fit within maxWidth */
+  private wrapText(text: string, maxWidth: number): string[] {
+    const result: string[] = []
+    for (const rawLine of text.split("\n")) {
+      if (rawLine === "") {
+        result.push("")
+        continue
+      }
+      let line = ""
+      let lineW = 0
+      for (const ch of rawLine) {
+        const w = displayWidth(ch)
+        if (lineW + w > maxWidth && line.length > 0) {
+          result.push(line)
+          line = ch
+          lineW = w
+        } else {
+          line += ch
+          lineW += w
+        }
+      }
+      if (line.length > 0) result.push(line)
+    }
+    return result.length > 0 ? result : [""]
+  }
+
+  override layout(rect: Rect): void {
+    super.layout(rect)
+    // Layout children (RawTextHost nodes) at same position
+    for (const child of this.children) {
+      child.layout(rect)
+    }
+  }
+
+  render(buffer: CellBuffer, palette: Palette): void {
+    if (!this.rect) return
+
+    const style: Record<string, unknown> = {}
+    if (this.fg !== undefined) style.fg = typeof this.fg === "string" ? parseColor(this.fg) : this.fg
+    if (this.bg !== undefined) style.bg = typeof this.bg === "string" ? parseColor(this.bg) : this.bg
+    if (this.bold) style.bold = true
+    if (this.italic) style.italic = true
+    if (this.underline) style.underline = true
+    if (this.inverse) style.inverse = true
+
+    const styleId = palette.id(style)
+    const content = this.getContent()
+    const rawLines = content.split("\n")
+
+    if (this.wrap) {
+      // Wrap mode: use cached lines if width matches, otherwise rewrap
+      const rectW = this.rect.w
+      const lines =
+        this.cachedLines && this.cachedWidth === rectW
+          ? this.cachedLines
+          : rawLines.flatMap((line, idx) =>
+              idx < rawLines.length - 1 ? [...this.wrapText(line, rectW), ""] : this.wrapText(line, rectW),
+            )
+      for (let i = 0; i < lines.length && i < this.rect.h; i++) {
+        buffer.drawText(this.rect.x, this.rect.y + i, lines[i], styleId, this.rect.w)
+      }
+      return
+    }
+
+    // Default: render explicit newlines, clip to width/height
+    const maxLines = Math.min(this.rect.h, rawLines.length)
+    for (let i = 0; i < maxLines; i++) {
+      buffer.drawText(this.rect.x, this.rect.y + i, rawLines[i], styleId, this.rect.w)
+    }
+  }
+
+  override updateProps(props: Record<string, unknown>): void {
+    super.updateProps(props)
+    // Always assign; props may be undefined when attribute is removed
+    this.fg = props.fg as ColorLike | undefined
+    this.bg = props.bg as ColorLike | undefined
+    this.bold = Boolean(props.bold)
+    this.italic = Boolean(props.italic)
+    this.underline = Boolean(props.underline)
+    this.inverse = Boolean(props.inverse)
+    this.wrap = Boolean(props.wrap)
+  }
+}
+
+/** Special host for raw text nodes (React text children) */
+export class RawTextHost extends BaseHost {
+  content = ""
+
+  constructor(text: string, ctx: HostContext) {
+    super("rawtext", {}, ctx)
+    this.content = text
+  }
+
+  measure(maxW: number, _maxH: number): Size {
+    const w = Math.min(displayWidth(this.content), maxW)
+    return { w, h: 1 }
+  }
+
+  render(buffer: CellBuffer, palette: Palette): void {
+    if (!this.rect) return
+    const styleId = palette.id({})
+    buffer.drawText(this.rect.x, this.rect.y, this.content, styleId, this.rect.w)
+  }
+
+  updateText(text: string): void {
+    this.content = text
+  }
+
+  override updateProps(_props: Record<string, unknown>): void {
+    // Raw text has no props
+  }
+}

package/src/hosts/vstack.ts

@@ -0,0 +1,64 @@
+import type { CellBuffer, Palette } from "@effect-tui/core"
+import type { HostContext, Rect, Size, CommonProps } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+import { measureFlex, layoutFlex, type FlexAlignment } from "../utils/index.js"
+
+export interface VStackProps extends CommonProps {
+  spacing?: number
+  alignment?: "leading" | "center" | "trailing"
+}
+
+// Map VStack alignment names to generic flex alignment
+function toFlexAlignment(alignment: "leading" | "center" | "trailing"): FlexAlignment {
+  switch (alignment) {
+    case "leading":
+      return "start"
+    case "center":
+      return "center"
+    case "trailing":
+      return "end"
+  }
+}
+
+export class VStackHost extends BaseHost {
+  spacing = 0
+  alignment: "leading" | "center" | "trailing" = "leading"
+  private cachedSizes: Size[] = []
+
+  constructor(props: VStackProps, ctx: HostContext) {
+    super("vstack", props, ctx)
+    this.updateProps(props)
+  }
+
+  measure(maxW: number, maxH: number): Size {
+    const result = measureFlex("vertical", this.children, this.spacing, maxH, maxW)
+    this.cachedSizes = result.sizes
+    return result.totalSize
+  }
+
+  override layout(rect: Rect): void {
+    super.layout(rect)
+    const stretchCross = this.alignment === "leading"
+    layoutFlex(
+      "vertical",
+      this.children,
+      this.cachedSizes,
+      rect,
+      this.spacing,
+      toFlexAlignment(this.alignment),
+      stretchCross,
+    )
+  }
+
+  render(buffer: CellBuffer, palette: Palette): void {
+    for (const child of this.children) {
+      child.render(buffer, palette)
+    }
+  }
+
+  override updateProps(props: Record<string, unknown>): void {
+    super.updateProps(props)
+    if (props.spacing !== undefined) this.spacing = props.spacing as number
+    if (props.alignment !== undefined) this.alignment = props.alignment as "leading" | "center" | "trailing"
+  }
+}

package/src/hosts/zstack.ts

@@ -0,0 +1,77 @@
+import type { CellBuffer, Palette } from "@effect-tui/core"
+import type { HostContext, Rect, Size, CommonProps } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+
+export interface ZStackProps extends CommonProps {
+  alignment?: { h?: "leading" | "center" | "trailing"; v?: "top" | "center" | "bottom" }
+}
+
+// Overlay children in the same rect, honoring alignment for each child.
+export class ZStackHost extends BaseHost {
+  alignmentH: "leading" | "center" | "trailing" = "center"
+  alignmentV: "top" | "center" | "bottom" = "center"
+  private cachedSizes: Size[] = []
+
+  constructor(props: ZStackProps, ctx: HostContext) {
+    super("zstack", props, ctx)
+    this.updateProps(props)
+  }
+
+  measure(maxW: number, maxH: number): Size {
+    let maxChildW = 0
+    let maxChildH = 0
+    this.cachedSizes = []
+
+    for (const child of this.children) {
+      const size = child.measure(maxW, maxH)
+      this.cachedSizes.push(size)
+      maxChildW = Math.max(maxChildW, size.w)
+      maxChildH = Math.max(maxChildH, size.h)
+    }
+
+    return {
+      w: Math.min(maxW, maxChildW),
+      h: Math.min(maxH, maxChildH),
+    }
+  }
+
+  override layout(rect: Rect): void {
+    super.layout(rect)
+
+    for (let i = 0; i < this.children.length; i++) {
+      const child = this.children[i]
+      const size = this.cachedSizes[i] ?? child.measure(rect.w, rect.h)
+
+      let x = rect.x
+      let y = rect.y
+
+      if (this.alignmentH === "center") x += Math.floor((rect.w - size.w) / 2)
+      else if (this.alignmentH === "trailing") x += Math.max(0, rect.w - size.w)
+
+      if (this.alignmentV === "center") y += Math.floor((rect.h - size.h) / 2)
+      else if (this.alignmentV === "bottom") y += Math.max(0, rect.h - size.h)
+
+      child.layout({
+        x,
+        y,
+        w: Math.min(rect.w, size.w),
+        h: Math.min(rect.h, size.h),
+      })
+    }
+  }
+
+  render(buffer: CellBuffer, palette: Palette): void {
+    for (const child of this.children) {
+      child.render(buffer, palette)
+    }
+  }
+
+  override updateProps(props: Record<string, unknown>): void {
+    super.updateProps(props)
+    if (props.alignment !== undefined) {
+      const a = props.alignment as ZStackProps["alignment"]
+      if (a?.h) this.alignmentH = a.h
+      if (a?.v) this.alignmentV = a.v
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+// Convenience: re-export core theming/types so apps can import from one place
+export * from "@effect-tui/core"
+
+// Renderer
+export {
+	createRenderer,
+	createRoot,
+	render,
+	useRenderer,
+	useTerminalSize,
+	RendererContext,
+} from "./renderer.js"
+export type { TuiRenderer, RendererOptions, Root, FrameStats, RenderInstance } from "./renderer.js"
+
+// Components
+export { CodeBlock } from "./codeblock.js"
+export type { CodeBlockProps } from "./codeblock.js"
+
+// Highlight utilities
+export {
+  highlightCode,
+  toPlainLines,
+  type HighlightLine,
+  type HighlightToken,
+  type HighlightTokenStyle,
+} from "./highlight.js"
+
+// Hooks
+export { useKeyboard, usePaste } from "./hooks/index.js"
+export { useFrameStats } from "./hooks/useFrameStats.js"
+export type { UseKeyboardOptions } from "./hooks/index.js"
+
+// Motion (spring animations)
+export {
+  useMotionValue,
+  useSpring,
+  useSprings,
+  useSpringRenderer,
+  useMotionValueEvent,
+  useAnimationFrame,
+  motionValue,
+  // Color springs
+  ColorMotionValue,
+  useColorMotionValue,
+  useColorSpring,
+} from "./motion/index.js"
+export type { SpringOptions, MotionValue, RGBA, ColorInput } from "./motion/index.js"
+
+// Types
+export type { HostInstance, HostContext, Rect, Size, CommonProps } from "./reconciler/types.js"
+export type { TextProps } from "./hosts/text.js"
+export type { SpacerProps } from "./hosts/spacer.js"
+export type { VStackProps } from "./hosts/vstack.js"
+export type { HStackProps } from "./hosts/hstack.js"
+export type { BoxProps, BorderKind } from "./hosts/box.js"
+export type { CanvasProps, DrawContext } from "./hosts/canvas.js"
+
+// Debug
+export { DiagnosticsPanel } from "./debug/DiagnosticsPanel.js"
+
+// JSX types are provided via jsxImportSource: "@effect-tui/react"
+// See jsx-runtime.ts at package root for the JSX namespace