@effect-tui/core 0.1.0-alpha.1

package/src/ui/__snapshots__/wrappedtext.test.ts.snap

@@ -0,0 +1,57 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`WrappedText > basic word wrapping > should handle single words longer than width 1`] = `
+"verylo
+ngword
+"
+`;
+
+exports[`WrappedText > basic word wrapping > should preserve explicit line breaks 1`] = `
+"line1
+line2
+line3
+
+"
+`;
+
+exports[`WrappedText > basic word wrapping > should wrap text at word boundaries 1`] = `
+"hello
+world
+test"
+`;
+
+exports[`WrappedText > wrapping strategies > should break words when breakWords is enabled 1`] = `
+"supercalif
+ragilistic
+expialidoc
+ious
+"
+`;
+
+exports[`WrappedText basic word wrapping should wrap text at word boundaries 1`] = `
+"hello
+world
+test"
+`;
+
+exports[`WrappedText basic word wrapping should handle single words longer than width 1`] = `
+"verylo
+ngword
+"
+`;
+
+exports[`WrappedText basic word wrapping should preserve explicit line breaks 1`] = `
+"line1
+line2
+line3
+
+"
+`;
+
+exports[`WrappedText wrapping strategies should break words when breakWords is enabled 1`] = `
+"supercalif
+ragilistic
+expialidoc
+ious
+"
+`;

package/src/ui/containers/canvas.ts

@@ -0,0 +1,18 @@
+import type { Palette, Surface } from "../../render/surface.js"
+import { View } from "../core/view.js"
+import type { Rect } from "../core/geometry.js"
+
+export class Canvas extends View {
+  constructor(readonly paint: (s: Surface, pal: Palette, rect: Rect) => void) {
+    super()
+  }
+
+  protected measureContent(maxW: number, maxH: number) {
+    // Greedy: occupy the full available area (caller can constrain via frame())
+    return { w: Math.max(0, maxW), h: Math.max(0, maxH) }
+  }
+
+  protected renderContent(s: Surface, pal: Palette, rect: Rect) {
+    this.paint(s, pal, rect)
+  }
+}

package/src/ui/containers/geometry-reader.ts

@@ -0,0 +1,32 @@
+import type { Palette, Surface } from "../../render/surface.js"
+import { View } from "../core/view.js"
+import type { Rect } from "../core/geometry.js"
+
+// GeometryReader - provides size information to child builder
+export type GeometryProxy = {
+  width: number
+  height: number
+}
+
+export class GeometryReader extends View {
+  constructor(readonly reader: (proxy: GeometryProxy) => View) {
+    super()
+  }
+
+  protected measureContent(maxW: number, maxH: number) {
+    // GeometryReader is greedy - takes all available space
+    return { w: maxW, h: maxH }
+  }
+
+  protected renderContent(s: Surface, pal: Palette, rect: Rect) {
+    // Create the child with the actual geometry
+    const proxy: GeometryProxy = {
+      width: rect.w,
+      height: rect.h,
+    }
+    const child = this.reader(proxy)
+    // Measure the child first, then render
+    child.measure(rect.w, rect.h)
+    child.render(s, pal, rect)
+  }
+}

package/src/ui/containers/hstack.ts

@@ -0,0 +1,33 @@
+import type { Palette, Surface } from "../../render/surface.js"
+import { View } from "../core/view.js"
+import type { Rect, VAlign } from "../core/geometry.js"
+import { measureLinear, layoutLinear } from "../../layout/linearStack.js"
+import { Spacer } from "../primitives/spacer.js"
+import { flexBaseForAxis } from "./shared.js"
+
+export class HStack extends View {
+  constructor(
+    readonly children: View[],
+    readonly spacing = 1,
+    readonly align: VAlign = "center",
+  ) {
+    super()
+  }
+
+  protected measureContent(maxW: number, maxH: number) {
+    const sizes = this.children.map((c) => c.measure(maxW, maxH))
+    const flexBase = this.children.map((c, i) =>
+      c instanceof Spacer ? c.minLength | 0 : flexBaseForAxis(c, "horizontal", sizes[i]),
+    )
+    return measureLinear("horizontal", maxW, maxH, this.spacing, sizes, flexBase)
+  }
+
+  protected renderContent(s: Surface, pal: Palette, rect: Rect) {
+    const sizes = this.children.map((c) => c.measure(rect.w, rect.h))
+    const flexBase = this.children.map((c, i) =>
+      c instanceof Spacer ? c.minLength | 0 : flexBaseForAxis(c, "horizontal", sizes[i]),
+    )
+    const rects = layoutLinear("horizontal", rect, this.spacing, this.align, sizes, flexBase)
+    for (let i = 0; i < this.children.length; i++) this.children[i].render(s, pal, rects[i])
+  }
+}

package/src/ui/containers/scroll.ts

@@ -0,0 +1,106 @@
+import type { Palette, Surface } from "../../render/surface.js"
+import { View } from "../core/view.js"
+import type { Rect, VAlign, HAlign } from "../core/geometry.js"
+
+// Scroll wrapper: viewport with clean SwiftUI-like semantics
+export class Scroll extends View {
+  /** Duck-typed brand so helpers can detect Scroll without imports/cycles */
+  public readonly __isScroll = true
+
+  private _fullW = 0
+  private _fullH = 0
+
+  constructor(
+    readonly child: View,
+    readonly opts: {
+      axis?: "vertical" | "horizontal"
+      offset?: number
+      align?: VAlign | HAlign
+    } = {},
+  ) {
+    super()
+  }
+
+  /** Get the maximum valid scroll offset for this content */
+  getMaxOffset(viewportW: number, viewportH: number): number {
+    const axis = this.opts.axis ?? "vertical"
+    if (axis === "vertical") {
+      const full = this.child.measure(viewportW, Number.MAX_SAFE_INTEGER)
+      return Math.max(0, full.h - viewportH)
+    } else {
+      const full = this.child.measure(Number.MAX_SAFE_INTEGER, viewportH)
+      return Math.max(0, full.w - viewportW)
+    }
+  }
+
+  protected measureContent(maxW: number, maxH: number) {
+    const axis = this.opts.axis ?? "vertical"
+    if (axis === "vertical") {
+      const full = this.child.measure(maxW, Number.MAX_SAFE_INTEGER)
+      this._fullW = full.w
+      this._fullH = full.h
+      // Greedy: take all available space (viewport semantics)
+      return { w: Math.min(maxW, full.w), h: maxH }
+    } else {
+      const full = this.child.measure(Number.MAX_SAFE_INTEGER, maxH)
+      this._fullW = full.w
+      this._fullH = full.h
+      return { w: maxW, h: Math.min(maxH, full.h) }
+    }
+  }
+
+  protected renderContent(s: Surface, pal: Palette, rect: Rect) {
+    const axis = this.opts.axis ?? "vertical"
+    const align = this.opts.align ?? "top"
+    const rawOffset = this.opts.offset ?? 0
+
+    // Ensure we have measured the child content
+    if (this._fullH === 0 && this._fullW === 0) {
+      this.measureContent(rect.w, rect.h)
+      // measureContent sets _fullH and _fullW as side effects
+    }
+
+    if (axis === "vertical") {
+      const overflow = Math.max(0, this._fullH - rect.h)
+      // Clamp offset to valid range [0, overflow]
+      const offset = Math.max(0, Math.min(overflow, rawOffset))
+      let start: number
+
+      if (align === "bottom") {
+        // Bottom-pinned: offset 0 shows last lines, positive offset scrolls up from bottom
+        if (overflow === 0) {
+          // Content fits: bottom-align by pushing content down
+          start = -(rect.h - this._fullH)
+        } else {
+          // Content overflows: start from bottom minus offset
+          start = overflow - offset
+        }
+      } else {
+        // Top-aligned: traditional scrolling
+        start = offset
+      }
+
+      const childRect = { x: rect.x, y: rect.y - start, w: rect.w, h: this._fullH }
+      s.withClip(rect.x, rect.y, rect.w, rect.h, () => this.child.render(s, pal, childRect))
+    } else {
+      const overflow = Math.max(0, this._fullW - rect.w)
+      // Clamp offset to valid range [0, overflow]
+      const offset = Math.max(0, Math.min(overflow, rawOffset))
+      let start: number
+
+      if (align === "trailing") {
+        // Right-pinned: similar logic for horizontal
+        if (overflow === 0) {
+          start = -(rect.w - this._fullW)
+        } else {
+          start = overflow - offset
+        }
+      } else {
+        start = offset
+      }
+
+      const childRect = { x: rect.x - start, y: rect.y, w: this._fullW, h: rect.h }
+      s.withClip(rect.x, rect.y, rect.w, rect.h, () => this.child.render(s, pal, childRect))
+    }
+  }
+}

package/src/ui/containers/shared.ts

@@ -0,0 +1,27 @@
+// Shared utilities for containers
+import type { View } from "../core/view.js"
+
+// Check if a node is a Fill wrapper for a given axis
+export function isFillForAxis(node: View, axis: "horizontal" | "vertical"): boolean {
+  return node.constructor.name === "Fill" && (node as any).axis === axis
+}
+
+// Get the main-axis size from a measured size
+export function mainSize(axis: "horizontal" | "vertical", size: { w: number; h: number }): number {
+  return axis === "horizontal" ? size.w : size.h
+}
+
+/** Return the flex base size for a node on an axis, or null if fixed. */
+export function flexBaseForAxis(
+  node: View,
+  axis: "horizontal" | "vertical",
+  measured: { w: number; h: number },
+): number | null {
+  // Scroll should be flexible but with a *zero* base so siblings get their fixed space first.
+  if ((node as any).__isScroll) return 0
+
+  // Fill is flexible with intrinsic base equal to its measured main size.
+  if (isFillForAxis(node, axis)) return mainSize(axis, measured)
+
+  return null
+}

package/src/ui/containers/vstack.ts

@@ -0,0 +1,34 @@
+import type { Palette, Surface } from "../../render/surface.js"
+import { View } from "../core/view.js"
+import type { Rect, HAlign } from "../core/geometry.js"
+import { measureLinear, layoutLinear } from "../../layout/linearStack.js"
+import { Spacer } from "../primitives/spacer.js"
+import { flexBaseForAxis } from "./shared.js"
+
+export class VStack extends View {
+  constructor(
+    readonly children: View[],
+    readonly spacing = 0,
+    readonly align: HAlign = "leading",
+  ) {
+    super()
+  }
+
+  protected measureContent(maxW: number, maxH: number) {
+    const sizes = this.children.map((c) => c.measure(maxW, maxH))
+    const flexBase = this.children.map((c, i) =>
+      c instanceof Spacer ? c.minLength | 0 : flexBaseForAxis(c, "vertical", sizes[i]),
+    )
+    return measureLinear("vertical", maxW, maxH, this.spacing, sizes, flexBase)
+  }
+
+  protected renderContent(s: Surface, pal: Palette, rect: Rect) {
+    const sizes = this.children.map((c) => c.measure(rect.w, rect.h))
+    const flexBase = this.children.map((c, i) =>
+      c instanceof Spacer ? c.minLength | 0 : flexBaseForAxis(c, "vertical", sizes[i]),
+    )
+    const rects = layoutLinear("vertical", rect, this.spacing, this.align, sizes, flexBase)
+
+    for (let i = 0; i < this.children.length; i++) this.children[i].render(s, pal, rects[i])
+  }
+}

package/src/ui/containers/zstack.ts

@@ -0,0 +1,37 @@
+import type { Palette, Surface } from "../../render/surface.js"
+import { View } from "../core/view.js"
+import type { Rect, Align2D } from "../core/geometry.js"
+
+// ZStack (overlay)
+export class ZStack extends View {
+  constructor(
+    readonly children: View[],
+    readonly alignment: Align2D = { h: "center", v: "center" },
+  ) {
+    super()
+  }
+
+  protected measureContent(maxW: number, maxH: number) {
+    let w = 0,
+      h = 0
+    for (const c of this.children) {
+      const m = c.measure(maxW, maxH)
+      w = Math.max(w, m.w)
+      h = Math.max(h, m.h)
+    }
+    return { w: Math.min(maxW, w), h: Math.min(maxH, h) }
+  }
+
+  protected renderContent(s: Surface, pal: Palette, rect: Rect) {
+    for (const c of this.children) {
+      const m = c.measure(rect.w, rect.h)
+      let x = rect.x,
+        y = rect.y
+      if (this.alignment.h === "center") x += Math.floor((rect.w - m.w) / 2)
+      else if (this.alignment.h === "trailing") x += Math.max(0, rect.w - m.w)
+      if (this.alignment.v === "center") y += Math.floor((rect.h - m.h) / 2)
+      else if (this.alignment.v === "bottom") y += Math.max(0, rect.h - m.h)
+      c.render(s, pal, { x, y, w: Math.min(rect.w, m.w), h: Math.min(rect.h, m.h) })
+    }
+  }
+}

package/src/ui/core/geometry-store.ts

@@ -0,0 +1,42 @@
+/* geometry-store.ts — last-known layout/geometry store keyed by ViewId */
+
+import type { Rect } from "./geometry.js"
+
+export type ViewId = string
+export type { Rect }
+export type InputGeom = { firstW: number; wrapW: number; xFirst: number; xOther: number }
+
+class GeometryStoreImpl {
+  private frameNo = 0
+  private rects = new Map<ViewId, Rect>()
+  private inputs = new Map<ViewId, InputGeom>()
+
+  beginFrame(frameNo?: number) {
+    // Clear for the new render pass; consumers will read after endFrame
+    this.frameNo = frameNo ?? this.frameNo + 1
+    this.rects.clear()
+    this.inputs.clear()
+  }
+
+  endFrame() {
+    // no-op for now; snapshot already in maps
+  }
+
+  setRect(id: ViewId, rect: Rect) {
+    this.rects.set(id, rect)
+  }
+
+  setInputGeom(id: ViewId, g: InputGeom) {
+    this.inputs.set(id, g)
+  }
+
+  getRect(id: ViewId): Rect | undefined {
+    return this.rects.get(id)
+  }
+
+  getInputGeom(id: ViewId): InputGeom | undefined {
+    return this.inputs.get(id)
+  }
+}
+
+export const geometryStore = new GeometryStoreImpl()

package/src/ui/core/geometry.ts

@@ -0,0 +1,30 @@
+// Basic geometry types and alignments
+
+export type Rect = { x: number; y: number; w: number; h: number }
+
+export type HAlign = "leading" | "center" | "trailing"
+export type VAlign = "top" | "center" | "bottom"
+export type Align2D = { h: HAlign; v: VAlign }
+
+export const Align = {
+  leading: "leading" as HAlign,
+  center: "center" as HAlign,
+  trailing: "trailing" as HAlign,
+  top: "top" as VAlign,
+  bottom: "bottom" as VAlign,
+  topLeading: { h: "leading", v: "top" } as Align2D,
+  topTrailing: { h: "trailing", v: "top" } as Align2D,
+  bottomLeading: { h: "leading", v: "bottom" } as Align2D,
+  bottomTrailing: { h: "trailing", v: "bottom" } as Align2D,
+  center2D: { h: "center", v: "center" } as Align2D,
+}
+
+export type FrameSpec = {
+  width?: number // exact width; use Infinity to fill
+  height?: number
+  minWidth?: number
+  maxWidth?: number
+  minHeight?: number
+  maxHeight?: number
+  alignment?: Align2D // child placement within surplus
+}

package/src/ui/core/view.ts

@@ -0,0 +1,49 @@
+/* view.ts — Core View class (renamed from CoreViewBase)
+ *
+ * This module defines the fundamental UI View class with minimal base functionality.
+ * It has NO imports of concrete modifiers to avoid circular dependencies.
+ */
+
+import type { Palette, Surface } from "../../render/surface.js"
+import type { Rect } from "./geometry.js"
+import { geometryStore } from "./geometry-store.js"
+
+export interface View {
+  measure(maxW: number, maxH: number): { w: number; h: number }
+  render(s: Surface, pal: Palette, rect: Rect): void
+}
+
+/**
+ * Abstract base class providing a minimal View foundation.
+ * Subclasses implement measureContent/renderContent for their specific behavior.
+ * All styling, padding, and frame logic has been moved to modifier classes.
+ */
+export abstract class View implements View {
+  protected _id?: string
+
+  /** Attach a stable id to this view for geometry tracking. */
+  id(id: string): View {
+    const c = Object.create(Object.getPrototypeOf(this)) as this
+    // copy own fields
+    for (const k of Object.keys(this) as Array<keyof this>) (c as any)[k] = (this as any)[k]
+    c._id = id
+    return c
+  }
+
+  measure(maxW: number, maxH: number) {
+    return this.measureContent(maxW, maxH)
+  }
+
+  render(s: Surface, pal: Palette, rect: Rect) {
+    // Record geometry if id is present
+    if (this._id) {
+      geometryStore.setRect(this._id, rect)
+    }
+
+    this.renderContent(s, pal, rect)
+  }
+
+  // ---- Hooks for subclasses ----
+  protected abstract measureContent(maxW: number, maxH: number): { w: number; h: number }
+  protected abstract renderContent(s: Surface, pal: Palette, rect: Rect): void
+}

package/src/ui/index.ts

@@ -0,0 +1,84 @@
+// Single barrel export for the View-centric UI system
+
+// Install chainable modifiers (side-effect import)
+import "./install.js"
+
+// Core geometry (types + helpers)
+export * from "./core/geometry.js"
+
+// View class will be exported at bottom after enhancement
+
+// Primitives
+export * from "./primitives/text.js"
+export * from "./primitives/rectangle.js"
+export * from "./primitives/spacer.js"
+export * from "./primitives/wrapped-text.js"
+
+// Containers
+export * from "./containers/hstack.js"
+export * from "./containers/vstack.js"
+export * from "./containers/zstack.js"
+export * from "./containers/scroll.js"
+export * from "./containers/canvas.js"
+export * from "./containers/geometry-reader.js"
+
+// Modifiers (classes exported, chainers are installed via side effects above)
+export * from "./modifiers/border.js"
+export * from "./modifiers/offset.js"
+export * from "./modifiers/fill.js"
+export * from "./modifiers/padding.js"
+export { Frame, type FrameSpec as ModifierFrameSpec } from "./modifiers/frame.js"
+export * from "./modifiers/styled.js"
+
+// Components & utilities
+export { ShinyText } from "./shinytext.js"
+export {
+  TextInput,
+  TextInputState,
+  editTextInput,
+  type TextInputStateLike,
+  type TextInputStatePlain,
+  type TextInputGeom,
+  type TextInputOptions,
+} from "./textinput.js"
+export { Markdown, type MarkdownOptions } from "./markdown.js"
+
+// Import View class and constructors
+import { View as ViewClass } from "./core/view.js"
+import { ViewConstructors } from "./view-constructors.js"
+
+// Use namespace merging to add static methods to View class
+declare module "./core/view.js" {
+  namespace View {
+    // Primitives
+    const text: typeof ViewConstructors.text
+    const wrappedText: typeof ViewConstructors.wrappedText
+    const rect: typeof ViewConstructors.rect
+    const spacer: typeof ViewConstructors.spacer
+
+    // Containers
+    const hstack: typeof ViewConstructors.hstack
+    const vstack: typeof ViewConstructors.vstack
+    const zstack: typeof ViewConstructors.zstack
+    const scroll: typeof ViewConstructors.scroll
+    const canvas: typeof ViewConstructors.canvas
+    const geometryReader: typeof ViewConstructors.geometryReader
+    const overlay: typeof ViewConstructors.overlay
+
+    // Components
+    const textInput: typeof ViewConstructors.textInput
+    const markdown: typeof ViewConstructors.markdown
+
+    // Utilities
+    const Colors: typeof ViewConstructors.Colors
+  }
+}
+
+// Install all the constructor methods on the View class
+const View = ViewClass as typeof ViewClass & typeof ViewConstructors
+
+// Install all constructors
+Object.assign(View, ViewConstructors)
+
+// Export the enhanced View
+export { View }