@effect-tui/core 0.1.0-alpha.1

package/src/ui/textinput.ts

@@ -0,0 +1,496 @@
+/* textinput.ts — single-line TextInput component and edit helpers */
+
+import type { Palette, Surface, StyleSpec } from "../render/surface.js"
+import type { Rect } from "./core/geometry.js"
+import { View } from "./core/view.js"
+import { geometryStore } from "./core/geometry-store.js"
+import { Colors } from "../render/surface.js"
+import { wrapText, findVisualPos, cellXWithinLine, cursorFromCellX, caretXYFromCursor } from "./text/layout.js"
+import { Schema } from "effect"
+import type { KeyMsg } from "../keys.js"
+
+/** Geometry info captured from last render. */
+export type TextInputGeom = { firstW: number; wrapW: number }
+
+/**
+ * TextInputState — immutable state for text input with built-in editing.
+ *
+ * Geometry is captured from render and used automatically in edit().
+ * This eliminates the need to manually pass wrap widths.
+ */
+export class TextInputState extends Schema.Class<TextInputState>("TextInputState")({
+  value: Schema.String,
+  cursor: Schema.Number,
+  focused: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  _vcol: Schema.optionalWith(Schema.UndefinedOr(Schema.Number), { default: () => undefined }),
+  _geom: Schema.optionalWith(Schema.Unknown, { default: () => undefined }),
+}) {
+  /** Create a new TextInputState with sensible defaults. */
+  static of(value: string, opts?: { cursor?: number; focused?: boolean }): TextInputState {
+    return new TextInputState({
+      value,
+      cursor: opts?.cursor ?? value.length,
+      focused: opts?.focused ?? false,
+    })
+  }
+
+  /** Create empty focused state. */
+  static empty(focused = true): TextInputState {
+    return new TextInputState({ value: "", cursor: 0, focused })
+  }
+
+  /**
+   * Edit state in response to a key press.
+   * Uses geometry captured from last render for accurate multiline navigation.
+   */
+  edit(key: KeyMsg, opts?: { multiline?: boolean }): { state: TextInputState; quit?: boolean } {
+    const geom = this._geom as TextInputGeom | undefined
+    return editTextInputCore(this, key, {
+      multiline: opts?.multiline ?? false,
+      wrapWidth: geom?.wrapW ?? Infinity,
+      firstLineWidth: geom?.firstW ?? Infinity,
+    })
+  }
+
+  // --- Immutable setters ---
+
+  withValue(value: string, cursor?: number): TextInputState {
+    return new TextInputState({
+      ...this,
+      value,
+      cursor: cursor ?? Math.min(this.cursor, [...value].length),
+      _vcol: undefined,
+    })
+  }
+
+  withCursor(cursor: number): TextInputState {
+    const max = [...this.value].length
+    return new TextInputState({
+      ...this,
+      cursor: Math.max(0, Math.min(max, cursor)),
+      _vcol: undefined,
+    })
+  }
+
+  focus(): TextInputState {
+    return this.focused ? this : new TextInputState({ ...this, focused: true })
+  }
+
+  blur(): TextInputState {
+    return !this.focused ? this : new TextInputState({ ...this, focused: false })
+  }
+
+  clear(): TextInputState {
+    return new TextInputState({ ...this, value: "", cursor: 0, _vcol: undefined })
+  }
+
+  /** Internal: capture geometry from render. Called by TextInput view. */
+  _captureGeom(geom: TextInputGeom): void {
+    ;(this as any)._geom = geom
+  }
+}
+
+/** Legacy plain-object type for backward compatibility. */
+export type TextInputStatePlain = {
+  value: string
+  cursor: number
+  focused?: boolean
+  _vcol?: number
+  _geom?: TextInputGeom
+}
+
+export type TextInputOptions = {
+  placeholder?: string
+  /** Optional left prompt character(s), e.g. ">" */
+  prompt?: string
+  /** Optional styles, merged with inherited styles */
+  style?: {
+    base?: StyleSpec
+    placeholder?: StyleSpec // e.g. { fg: Colors.gray(12) }
+    prompt?: StyleSpec
+    caret?: StyleSpec // e.g. { inverse: true }
+  }
+  /** Enable multiline input and rendering (supports newlines and wrapping). */
+  multiline?: boolean
+  /** Word-wrapping preferences when multiline (defaults: wordWrap=true, breakWords=true). */
+  wrap?: {
+    wordWrap?: boolean
+    breakWords?: boolean
+  }
+}
+
+/** State that can be passed to TextInput: class instance or plain object. */
+export type TextInputStateLike = TextInputState | TextInputStatePlain
+
+/** A minimal single-line text input view (no border). */
+export class TextInput extends View {
+  constructor(
+    readonly state: TextInputStateLike,
+    readonly opts?: TextInputOptions,
+  ) {
+    super()
+  }
+
+  protected measureContent(maxW: number, maxH: number) {
+    const w = Math.max(0, maxW)
+    if (!this.opts?.multiline) {
+      // Greedy single line
+      return { w, h: 1 }
+    }
+    // Multiline: compute wrapped lines to determine natural height (clamped by maxH)
+    const { lines } = wrapText(this.state.value, {
+      widthFirst: Math.max(0, w - (this.opts?.prompt ? displayWidth(this.opts?.prompt ?? "") : 0)),
+      widthOther: w,
+      wordWrap: this.opts?.wrap?.wordWrap ?? true,
+      breakWords: this.opts?.wrap?.breakWords ?? true,
+    })
+    const h = Math.min(Math.max(1, lines.length), maxH)
+    return { w, h }
+  }
+
+  protected renderContent(s: Surface, pal: Palette, rect: Rect) {
+    const styles = this.opts?.style ?? {}
+    const idBase = pal.id(styles.base)
+    const idPlaceholder = pal.id(styles.placeholder ?? { fg: Colors.gray(12) })
+    const idCaret = pal.id(styles.caret ?? { inverse: true })
+
+    const w = Math.max(0, rect.w)
+    if (w <= 0 || rect.h <= 0) return
+
+    const promptText = this.opts?.prompt ?? ""
+    const prefix = promptText ? `${promptText}` : ""
+    const prefixW = displayWidth(prefix)
+    if (prefixW > 0) s.drawText(rect.x, rect.y, prefix, pal.id(styles.prompt), w)
+
+    const contentX = rect.x + prefixW
+    const contentW = Math.max(0, w - prefixW)
+    if (contentW <= 0) return
+
+    const valueEmpty = this.state.value.length === 0
+    const placeholderText = this.opts?.placeholder ?? ""
+
+    // Capture geometry into state for accurate edit calculations
+    const geom: TextInputGeom = {
+      firstW: contentW,
+      wrapW: this.opts?.multiline ? w : contentW,
+    }
+    if (this.state instanceof TextInputState) {
+      this.state._captureGeom(geom)
+    } else {
+      ;(this.state as TextInputStatePlain)._geom = geom
+    }
+
+    if (!this.opts?.multiline) {
+      // Single-line path (back-compat)
+      const text = valueEmpty ? placeholderText : this.state.value
+      const isPlaceholder = valueEmpty && text.length > 0
+      const textStyle = isPlaceholder ? idPlaceholder : idBase
+      s.drawText(contentX, rect.y, text, textStyle, contentW)
+
+      if (this.state.focused) {
+        const cx0 = this.state.cursor | 0
+        const cx = Math.max(0, Math.min(contentW - 1, cx0))
+        const arr = [...text]
+        const ch = arr[cx] ?? " "
+        s.drawText(contentX + cx, rect.y, ch, idCaret, 1)
+      }
+      // Publish geometry snapshot if id is attached (legacy)
+      if ((this as any)._id) {
+        geometryStore.setInputGeom((this as any)._id, {
+          firstW: contentW,
+          wrapW: contentW,
+          xFirst: contentX,
+          xOther: contentX,
+        })
+      }
+      return
+    }
+
+    // Multiline path: wrap and render multiple rows
+    const wrap = wrapText(this.state.value, {
+      widthFirst: contentW,
+      widthOther: w,
+      wordWrap: this.opts?.wrap?.wordWrap ?? true,
+      breakWords: this.opts?.wrap?.breakWords ?? true,
+    })
+
+    // Draw placeholder on first line only when empty
+    if (valueEmpty && placeholderText) {
+      s.drawText(contentX, rect.y, placeholderText, idPlaceholder, contentW)
+    }
+
+    // Determine cursor location in visual coordinates
+    let caretAbsX = contentX
+    let caretAbsY = rect.y
+    if (this.state.focused) {
+      const { x, y } = caretXYFromCursor(wrap, this.state.cursor, {
+        xFirst: contentX,
+        xOther: rect.x,
+      })
+      caretAbsX = x
+      caretAbsY = y + rect.y
+    }
+
+    // Render lines (clip to rect.h)
+    const maxLines = Math.min(rect.h, wrap.lines.length)
+    for (let i = 0; i < maxLines; i++) {
+      const line = wrap.lines[i]
+      const baseX = i === 0 ? contentX : rect.x
+      const maxW = i === 0 ? contentW : w
+      const text = line.text
+      if (text.length > 0) s.drawText(baseX, rect.y + i, text, idBase, maxW)
+    }
+
+    // Publish input geometry for this id (legacy)
+    if ((this as any)._id) {
+      geometryStore.setInputGeom((this as any)._id, {
+        firstW: contentW,
+        wrapW: w,
+        xFirst: contentX,
+        xOther: rect.x,
+      })
+    }
+
+    // Caret on top
+    if (this.state.focused) {
+      // Determine caret character (either actual char under cursor or space)
+      const { lineIdx, colInLine } = findVisualPos(wrap, this.state.cursor)
+      const line = wrap.lines[lineIdx]
+      const ch = line?.graphemes[colInLine] ?? " "
+      s.drawText(caretAbsX, caretAbsY, ch, idCaret, 1)
+    }
+  }
+}
+// Builder contribution for the View object
+export type ViewTextInputExt = {
+  textInput(state: TextInputStateLike, opts?: TextInputOptions): View
+}
+export const viewTextInput: ViewTextInputExt = {
+  textInput(state: TextInputStateLike, opts?: TextInputOptions): View {
+    return new TextInput(state, opts)
+  },
+}
+
+// --- Text editing helpers ---
+
+export type TextInputEditResult = {
+  state: TextInputState
+  quit?: boolean
+}
+
+export type TextInputEditOptions = {
+  /** Enable multiline editing semantics (enter inserts newline with shift). */
+  multiline?: boolean
+  /** Visual wrap width for subsequent lines. If absent, only explicit newlines are considered. */
+  wrapWidth?: number
+  /** Visual wrap width for first line (after prompt). Defaults to wrapWidth. */
+  firstLineWidth?: number
+}
+
+/** Core edit function. Prefer using TextInputState.edit() for automatic geometry. */
+function editTextInputCore(state: TextInputStateLike, key: KeyMsg, opts?: TextInputEditOptions): TextInputEditResult {
+  const { value, cursor, focused, _geom } = state
+  const vcol = state._vcol as number | undefined
+  const len = [...value].length
+
+  const clamp = (n: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, n))
+
+  // Create new state preserving geometry
+  const make = (updates: { value?: string; cursor?: number; _vcol?: number }): TextInputState =>
+    new TextInputState({
+      value: updates.value ?? value,
+      cursor: updates.cursor ?? cursor,
+      focused,
+      _vcol: updates._vcol,
+      _geom,
+    })
+
+  // Unchanged state (preserve as-is, converting to class if needed)
+  const unchanged = (): TextInputState =>
+    state instanceof TextInputState ? state : new TextInputState({ value, cursor, focused, _vcol: vcol, _geom })
+
+  const isSpace = (ch: string) => /\s/.test(ch)
+  const prevWord = (arr: string[], pos: number) => {
+    let i = clamp(pos, 0, arr.length)
+    if (i === 0) return 0
+    while (i > 0 && isSpace(arr[i - 1])) i--
+    while (i > 0 && !isSpace(arr[i - 1])) i--
+    return i
+  }
+  const nextWord = (arr: string[], pos: number) => {
+    let i = clamp(pos, 0, arr.length)
+    if (i === arr.length) return i
+    while (i < arr.length && !isSpace(arr[i])) i++
+    while (i < arr.length && isSpace(arr[i])) i++
+    return i
+  }
+
+  const multiline = !!opts?.multiline
+  const wrapWidth = opts?.wrapWidth
+  const firstWidth = opts?.firstLineWidth ?? wrapWidth
+
+  const getWrap = () =>
+    wrapText(value, {
+      widthFirst: firstWidth ?? Infinity,
+      widthOther: wrapWidth ?? Infinity,
+      wordWrap: true,
+      breakWords: true,
+    })
+
+  switch (key.name) {
+    case "left":
+      if (key.meta) {
+        const arr = [...value]
+        return { state: make({ cursor: prevWord(arr, cursor) }) }
+      }
+      return { state: make({ cursor: clamp(cursor - 1, 0, len) }) }
+
+    case "right":
+      if (key.meta) {
+        const arr = [...value]
+        return { state: make({ cursor: nextWord(arr, cursor) }) }
+      }
+      return { state: make({ cursor: clamp(cursor + 1, 0, len) }) }
+
+    case "home":
+      return { state: make({ cursor: 0 }) }
+
+    case "end":
+      return { state: make({ cursor: len }) }
+
+    case "up": {
+      if (!multiline) return { state: unchanged() }
+      const wrap = getWrap()
+      const pos = findVisualPos(wrap, cursor)
+      if (pos.lineIdx <= 0) return { state: unchanged() }
+      const curX = vcol ?? cellXWithinLine(wrap, pos.lineIdx, pos.colInLine)
+      const target = cursorFromCellX(wrap, pos.lineIdx - 1, curX)
+      return { state: make({ cursor: target, _vcol: curX }) }
+    }
+
+    case "down": {
+      if (!multiline) return { state: unchanged() }
+      const wrap = getWrap()
+      const pos = findVisualPos(wrap, cursor)
+      if (pos.lineIdx >= wrap.lines.length - 1) return { state: unchanged() }
+      const curX = vcol ?? cellXWithinLine(wrap, pos.lineIdx, pos.colInLine)
+      const target = cursorFromCellX(wrap, pos.lineIdx + 1, curX)
+      return { state: make({ cursor: target, _vcol: curX }) }
+    }
+
+    case "backspace": {
+      if (key.meta) {
+        if (cursor <= 0) return { state: unchanged() }
+        const arr = [...value]
+        const start = prevWord(arr, cursor)
+        arr.splice(start, cursor - start)
+        return { state: make({ value: arr.join(""), cursor: start }) }
+      }
+      if (cursor <= 0) return { state: unchanged() }
+      const arr = [...value]
+      arr.splice(cursor - 1, 1)
+      return { state: make({ value: arr.join(""), cursor: cursor - 1 }) }
+    }
+
+    case "delete": {
+      if (key.meta) {
+        if (cursor <= 0) return { state: unchanged() }
+        const arr = [...value]
+        arr.splice(0, cursor)
+        return { state: make({ value: arr.join(""), cursor: 0 }) }
+      }
+      if (cursor >= len) return { state: unchanged() }
+      const arr = [...value]
+      arr.splice(cursor, 1)
+      return { state: make({ value: arr.join(""), cursor }) }
+    }
+
+    case "enter":
+    case "return": {
+      if (multiline) {
+        const arr = [...value]
+        arr.splice(cursor, 0, "\n")
+        return { state: make({ value: arr.join(""), cursor: cursor + 1 }) }
+      }
+      return { state: unchanged() }
+    }
+
+    case "space": {
+      return editTextInputCore(state, { ...key, name: "char", text: " " }, opts)
+    }
+
+    case "char": {
+      if (!key.text) return { state: unchanged() }
+
+      // Ctrl-C: clear or quit
+      if (key.ctrl && key.text === "c") {
+        if (value.length > 0) {
+          return { state: make({ value: "", cursor: 0 }) }
+        }
+        return { state: unchanged(), quit: true }
+      }
+
+      // Ctrl-U: delete to start
+      if (key.ctrl && key.text === "u") {
+        if (cursor <= 0) return { state: unchanged() }
+        const arr = [...value]
+        arr.splice(0, cursor)
+        return { state: make({ value: arr.join(""), cursor: 0 }) }
+      }
+
+      // Ctrl-W: delete previous word
+      if (key.ctrl && key.text === "w") {
+        const arr = [...value]
+        const start = prevWord(arr, cursor)
+        arr.splice(start, cursor - start)
+        return { state: make({ value: arr.join(""), cursor: start }) }
+      }
+
+      // Meta-b/B: previous word
+      if (key.meta && (key.text === "b" || key.text === "B")) {
+        const arr = [...value]
+        return { state: make({ cursor: prevWord(arr, cursor) }) }
+      }
+
+      // Meta-f/F: next word
+      if (key.meta && (key.text === "f" || key.text === "F")) {
+        const arr = [...value]
+        return { state: make({ cursor: nextWord(arr, cursor) }) }
+      }
+
+      // Meta-d/D: delete next word
+      if (key.meta && (key.text === "d" || key.text === "D")) {
+        const arr = [...value]
+        const end = nextWord(arr, cursor)
+        if (end === cursor) return { state: unchanged() }
+        arr.splice(cursor, end - cursor)
+        return { state: make({ value: arr.join(""), cursor }) }
+      }
+
+      if (key.meta) return { state: unchanged() }
+
+      // Insert character
+      const arr = [...value]
+      arr.splice(cursor, 0, key.text)
+      return { state: make({ value: arr.join(""), cursor: cursor + 1 }) }
+    }
+
+    default:
+      return { state: unchanged() }
+  }
+}
+
+/**
+ * Edit text input state with a key event.
+ * @deprecated Use TextInputState.edit() instead for automatic geometry handling.
+ */
+export function editTextInput(
+  state: TextInputStateLike,
+  key: KeyMsg,
+  opts?: TextInputEditOptions,
+): TextInputEditResult {
+  return editTextInputCore(state, key, opts)
+}
+
+// --- Internal helpers for wrapping-aware cursor movement & rendering ---
+import { displayWidth } from "../render/measure.js"

package/src/ui/view-constructors.ts

@@ -0,0 +1,96 @@
+/* view-constructors.ts — Static constructor methods for View
+ *
+ * This module contains all the static constructor methods that will be merged
+ * with the View class via namespace merging to avoid circular dependencies.
+ */
+
+import { Colors } from "../render/surface.js"
+import type { View } from "./core/view.js"
+import type { Align2D, HAlign, VAlign } from "./core/geometry.js"
+
+// Import all component classes for builders
+import { Text } from "./primitives/text.js"
+import { Rectangle } from "./primitives/rectangle.js"
+import { Spacer } from "./primitives/spacer.js"
+import { WrappedText, type WrappingOptions } from "./primitives/wrapped-text.js"
+import { HStack } from "./containers/hstack.js"
+import { VStack } from "./containers/vstack.js"
+import { ZStack } from "./containers/zstack.js"
+import { Scroll } from "./containers/scroll.js"
+import { Canvas } from "./containers/canvas.js"
+import { GeometryReader, type GeometryProxy } from "./containers/geometry-reader.js"
+import { TextInput, type TextInputState, type TextInputOptions } from "./textinput.js"
+import { Markdown, type MarkdownOptions } from "./markdown.js"
+
+// Options types for clean API (gap preferred; spacing kept for compat)
+type HStackOpts = { gap?: number; spacing?: number; alignment?: VAlign }
+type VStackOpts = { gap?: number; spacing?: number; alignment?: HAlign }
+type ScrollOpts = { axis?: "vertical" | "horizontal"; offset?: number; align?: VAlign | HAlign }
+
+// Constructor functions that will become static methods on View
+export const ViewConstructors = {
+  // Primitives
+  text: (s: string, wrap?: boolean): Text => {
+    return new Text(s, wrap)
+  },
+
+  wrappedText: (s: string, options?: WrappingOptions): WrappedText => {
+    return new WrappedText(s, options)
+  },
+
+  rect: (w: number, h: number, fill?: string | number): Rectangle => {
+    return new Rectangle(w, h, typeof fill === "number" ? fill : (fill?.codePointAt?.(0) ?? 32))
+  },
+
+  spacer: (minLength = 0): Spacer => {
+    return new Spacer(minLength)
+  },
+
+  // Containers (accept opts or legacy (gap, { alignment }))
+  hstack: (children: View[], optsOrGap: number | HStackOpts = {}, maybe: { alignment?: VAlign } = {}): HStack => {
+    const isNum = typeof optsOrGap === "number"
+    const gap = isNum ? (optsOrGap as number) : (optsOrGap.gap ?? optsOrGap.spacing ?? 1)
+    const alignment = (isNum ? maybe.alignment : (optsOrGap as HStackOpts).alignment) ?? "center"
+    return new HStack(children, gap, alignment)
+  },
+
+  vstack: (children: View[], optsOrGap: number | VStackOpts = {}, maybe: { alignment?: HAlign } = {}): VStack => {
+    const isNum = typeof optsOrGap === "number"
+    const gap = isNum ? (optsOrGap as number) : (optsOrGap.gap ?? optsOrGap.spacing ?? 0)
+    const alignment = (isNum ? maybe.alignment : (optsOrGap as VStackOpts).alignment) ?? "leading"
+    return new VStack(children, gap, alignment)
+  },
+
+  zstack: (children: View[], alignment?: Align2D): ZStack => {
+    return new ZStack(children, alignment ?? { h: "center", v: "center" })
+  },
+
+  scroll: (child: View, opts?: ScrollOpts): Scroll => {
+    return new Scroll(child, opts ?? {})
+  },
+
+  canvas: (paint: (s: any, pal: any, rect: any) => void): Canvas => {
+    return new Canvas(paint)
+  },
+
+  geometryReader: (reader: (proxy: GeometryProxy) => View): GeometryReader => {
+    return new GeometryReader(reader)
+  },
+
+  // Overlay method (moved from chainer to avoid circular dependency)
+  overlay: (base: View, overlay: View, alignment?: Align2D): ZStack => {
+    return new ZStack([base, overlay], alignment ?? { h: "center", v: "center" })
+  },
+
+  // Components
+  textInput: (state: TextInputState, opts?: TextInputOptions): TextInput => {
+    return new TextInput(state, opts)
+  },
+
+  markdown: (text: string, opts?: MarkdownOptions): Markdown => {
+    return new Markdown(text, opts)
+  },
+
+  // Utilities
+  Colors,
+} as const