@effect-tui/core 0.1.0-alpha.1

package/dist/ui/view-constructors.js

@@ -0,0 +1,74 @@
+/* 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 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 } 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 } from "./containers/geometry-reader.js";
+import { TextInput } from "./textinput.js";
+import { Markdown } from "./markdown.js";
+// Constructor functions that will become static methods on View
+export const ViewConstructors = {
+    // Primitives
+    text: (s, wrap) => {
+        return new Text(s, wrap);
+    },
+    wrappedText: (s, options) => {
+        return new WrappedText(s, options);
+    },
+    rect: (w, h, fill) => {
+        return new Rectangle(w, h, typeof fill === "number" ? fill : (fill?.codePointAt?.(0) ?? 32));
+    },
+    spacer: (minLength = 0) => {
+        return new Spacer(minLength);
+    },
+    // Containers (accept opts or legacy (gap, { alignment }))
+    hstack: (children, optsOrGap = {}, maybe = {}) => {
+        const isNum = typeof optsOrGap === "number";
+        const gap = isNum ? optsOrGap : (optsOrGap.gap ?? optsOrGap.spacing ?? 1);
+        const alignment = (isNum ? maybe.alignment : optsOrGap.alignment) ?? "center";
+        return new HStack(children, gap, alignment);
+    },
+    vstack: (children, optsOrGap = {}, maybe = {}) => {
+        const isNum = typeof optsOrGap === "number";
+        const gap = isNum ? optsOrGap : (optsOrGap.gap ?? optsOrGap.spacing ?? 0);
+        const alignment = (isNum ? maybe.alignment : optsOrGap.alignment) ?? "leading";
+        return new VStack(children, gap, alignment);
+    },
+    zstack: (children, alignment) => {
+        return new ZStack(children, alignment ?? { h: "center", v: "center" });
+    },
+    scroll: (child, opts) => {
+        return new Scroll(child, opts ?? {});
+    },
+    canvas: (paint) => {
+        return new Canvas(paint);
+    },
+    geometryReader: (reader) => {
+        return new GeometryReader(reader);
+    },
+    // Overlay method (moved from chainer to avoid circular dependency)
+    overlay: (base, overlay, alignment) => {
+        return new ZStack([base, overlay], alignment ?? { h: "center", v: "center" });
+    },
+    // Components
+    textInput: (state, opts) => {
+        return new TextInput(state, opts);
+    },
+    markdown: (text, opts) => {
+        return new Markdown(text, opts);
+    },
+    // Utilities
+    Colors,
+};
+//# sourceMappingURL=view-constructors.js.map

package/dist/ui/view-constructors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-constructors.js","sourceRoot":"","sources":["../../src/ui/view-constructors.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@effect-tui/core",
+  "version": "0.1.0-alpha.1",
+  "description": "Terminal UI library built with Effect",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kitlangton/effect-tui.git"
+  },
+  "homepage": "https://github.com/kitlangton/effect-tui",
+  "bugs": "https://github.com/kitlangton/effect-tui/issues",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "keywords": [
+    "terminal",
+    "tui",
+    "effect",
+    "cli",
+    "console"
+  ],
+  "author": "Kit Langton",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p . --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "prepublishOnly": "bun run typecheck && bun run build"
+  },
+  "peerDependencies": {
+    "effect": "^3.0.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^0.27.0",
+    "@types/node": "^24.10.1",
+    "effect": "^3.19.8",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
+  }
+}

package/src/anim.ts

@@ -0,0 +1,5 @@
+// anim.ts - Re-export all animation primitives for backwards compatibility
+
+export * from "./spring-physics.js"
+export * from "./spring.js"
+export * from "./motion-value.js"

package/src/ansi.ts

@@ -0,0 +1,83 @@
+// ANSI escape sequences and terminal control utilities
+
+/** CSI prefix (ESC [) */
+const CSI = "\x1b["
+
+/** Basic ANSI codes and helpers */
+export const ANSI = {
+  /** Reset all attributes */
+  reset: `${CSI}0m`,
+
+  /** Cursor control */
+  cursor: {
+    /** Hide cursor */
+    hide: `${CSI}?25l`,
+    /** Show cursor */
+    show: `${CSI}?25h`,
+    /** Move cursor to home position (1,1) */
+    home: `${CSI}H`,
+    /** Move cursor to 1-based row/column */
+    to: (row1: number, col1: number) => `${CSI}${row1};${col1}H`,
+    /** Move cursor to 1-based column on current row */
+    toCol: (col1: number) => `${CSI}${col1}G`,
+  },
+
+  /** Screen control */
+  screen: {
+    /** Enter alternate screen buffer */
+    altEnter: `${CSI}?1049h`,
+    /** Exit alternate screen buffer */
+    altExit: `${CSI}?1049l`,
+    /** Clear entire display */
+    clear: `${CSI}2J`,
+    /** Clear scrollback buffer */
+    clearScrollback: `${CSI}3J`,
+  },
+
+  /** Scrolling */
+  scroll: {
+    /** Scroll up by n lines */
+    up: (n: number) => `${CSI}${n}S`,
+  },
+
+  /** Device Status Reports / queries */
+  report: {
+    /** Report Cursor Position (response: ESC [ row ; col R) */
+    cursorPosition: `${CSI}6n`,
+  },
+
+  /** Bracketed paste mode */
+  paste: {
+    bracketed: {
+      on: `${CSI}?2004h`,
+      off: `${CSI}?2004l`,
+    },
+  },
+
+  /** Mouse reporting toggles */
+  mouse: {
+    /** Enable button tracking and SGR coordinates */
+    on: `${CSI}?1002h${CSI}?1006h`,
+    /** Disable SGR coords and button tracking */
+    off: `${CSI}?1006l${CSI}?1002l`,
+  },
+} as const
+
+/** Terminal session control utilities (compositions of ANSI primitives) */
+export const Terminal = {
+  /** Enter full-screen mode: alternate screen + hide cursor */
+  enterFullscreen: ANSI.screen.altEnter + ANSI.cursor.hide,
+
+  /** Exit full-screen mode: reset + show cursor + exit alternate screen */
+  exitFullscreen: ANSI.reset + ANSI.cursor.show + ANSI.screen.altExit,
+
+  /** Clear screen and move cursor to home */
+  clearAndHome: ANSI.screen.clear + ANSI.cursor.home,
+
+  /** Convenience shorthands for common toggles */
+  bracketedPasteOn: ANSI.paste.bracketed.on,
+  bracketedPasteOff: ANSI.paste.bracketed.off,
+  mouseOn: ANSI.mouse.on,
+  mouseOff: ANSI.mouse.off,
+  reportCursorPosition: ANSI.report.cursorPosition,
+} as const

package/src/index.ts

@@ -0,0 +1,21 @@
+// Re-export core modules
+export * from "./render/surface.js"
+export * from "./render/buffer.js"
+export * from "./render/measure.js"
+export * from "./anim.js"
+export * from "./keys.js"
+
+// UI (canonical View and curated exports)
+export { View } from "./ui/index.js"
+export { ShinyText } from "./ui/index.js"
+export { TextInput, TextInputState, editTextInput } from "./ui/index.js"
+export { Markdown } from "./ui/index.js"
+export type { TextInputStateLike, TextInputStatePlain, TextInputGeom, TextInputOptions } from "./ui/index.js"
+export type { MarkdownOptions } from "./ui/index.js"
+// Geometry store (last-known layout)
+export { geometryStore } from "./ui/core/geometry-store.js"
+export type { ViewId, Rect as GeometryRect, InputGeom } from "./ui/core/geometry-store.js"
+
+// Renderers (optional public API)
+export * from "./present/display.js"
+export type { TerminalBackend } from "./runtime/backend_node.js"

package/src/keys.ts

@@ -0,0 +1,302 @@
+// Minimal key decoder for Node raw input → semantic key messages.
+
+export type KeyName =
+  | "up"
+  | "down"
+  | "left"
+  | "right"
+  | "enter"
+  | "escape"
+  | "tab"
+  | "shift-tab"
+  | "backspace"
+  | "delete"
+  | "home"
+  | "end"
+  | "pageup"
+  | "pagedown"
+  | "insert"
+  | "return"
+  | "space"
+  | "char" // printable
+
+export type KeyMsg = {
+  type: "key"
+  name: KeyName
+  text?: string // for printable chars
+  ctrl?: boolean
+  meta?: boolean
+  shift?: boolean
+  /** Optional phase; currently always "press" but left extensible. */
+  phase?: "press" | "repeat" | "release"
+  /** Set by renderer to allow handlers to stop further propagation. */
+  defaultPrevented?: boolean
+  preventDefault?: () => void
+  /** Source protocol (raw|csiu|modifyOther|kitty). */
+  source?: "raw" | "csiu" | "modify-other" | "kitty"
+}
+
+const ESC = "\x1b"
+
+export function* decodeKeys(buf: Buffer): Iterable<KeyMsg> {
+  // Handle control characters (0x00-0x1F)
+  // These are generated by Ctrl+letter combinations
+  if (buf.length === 1 && buf[0] !== undefined && buf[0] < 0x20) {
+    const byte = buf[0]
+
+    // Special control characters with specific meanings
+    switch (byte) {
+      case 0x03: // Ctrl-C (ETX - End of Text)
+        yield { type: "key", name: "char", text: "c", ctrl: true }
+        return
+      case 0x04: // Ctrl-D (EOT - End of Transmission)
+        yield { type: "key", name: "char", text: "d", ctrl: true }
+        return
+      case 0x17: // Ctrl-W (ETB - End of Transmission Block)
+        yield { type: "key", name: "char", text: "w", ctrl: true }
+        return
+      case 0x1a: // Ctrl-Z (SUB - Substitute)
+        yield { type: "key", name: "char", text: "z", ctrl: true }
+        return
+      case 0x0c: // Ctrl-L (FF - Form Feed)
+        yield { type: "key", name: "char", text: "l", ctrl: true }
+        return
+      case 0x09: // Tab (HT - Horizontal Tab)
+        yield { type: "key", name: "tab" }
+        return
+      case 0x0d: // Enter (CR - Carriage Return)
+        yield { type: "key", name: "enter" }
+        return
+      case 0x0a: // Line Feed (LF)
+        yield { type: "key", name: "enter" }
+        return
+      case 0x08: // Backspace (BS)
+        yield { type: "key", name: "backspace" }
+        return
+      case 0x1b: // Escape (ESC)
+        yield { type: "key", name: "escape" }
+        return
+      default:
+        // Other control characters: convert back to letter
+        // Ctrl-A = 0x01, Ctrl-B = 0x02, etc.
+        if (byte >= 0x01 && byte <= 0x1a) {
+          const letter = String.fromCharCode(byte + 96) // 0x01 + 96 = 'a'
+          yield { type: "key", name: "char", text: letter, ctrl: true }
+        } else {
+          // Unknown control character, emit raw
+          yield { type: "key", name: "char", text: String.fromCharCode(byte), ctrl: true }
+        }
+        return
+    }
+  }
+
+  // Handle 0x7F (DEL) separately as it's outside the control character range
+  if (buf.length === 1 && buf[0] === 0x7f) {
+    yield { type: "key", name: "backspace" }
+    return
+  }
+
+  let s = buf.toString("utf8")
+
+  // Handle one or more SGR mouse reports possibly coalesced in a single chunk.
+  // Format: ESC [ < Cb ; Cx ; Cy (M|m) — terminals vary on the trailing letter; accept any A-Z.
+  const sgrRe = /\x1b\x5b<(?<cb>\d+);(?<cx>\d+);(?<cy>\d+)(?<updown>[A-Za-z])/g
+  let matchedAny = false
+  for (const m of s.matchAll(sgrRe)) {
+    matchedAny = true
+    const code = parseInt(m.groups?.cb ?? "0", 10)
+    if (code === 64) {
+      yield { type: "key", name: "pageup", meta: true }
+      continue
+    }
+    if (code === 65) {
+      yield { type: "key", name: "pagedown", meta: true }
+    }
+    // ignore other mouse events
+  }
+  if (matchedAny) {
+    // Strip SGR mouse sequences so they never leak into the input as text
+    // Create a fresh regex since the global one was consumed by matchAll()
+    s = s.replace(/\x1b\x5b<(?<cb>\d+);(?<cx>\d+);(?<cy>\d+)(?<updown>[A-Za-z])/g, "")
+    if (s.length === 0) return
+  }
+
+  // Legacy single SGR report path (when only one arrives)
+  const sgr = /^\x1b\[<(?<cb>\d+);(?<cx>\d+);(?<cy>\d+)(?<updown>[A-Za-z])$/.exec(s)
+  if (sgr?.groups) {
+    const code = parseInt(sgr.groups.cb ?? "0", 10)
+    if (code === 64) {
+      yield { type: "key", name: "pageup", meta: true }
+      return
+    }
+    if (code === 65) {
+      yield { type: "key", name: "pagedown", meta: true }
+      return
+    }
+    return
+  }
+
+  // Meta+Backspace (Option+Backspace on macOS terminals) — often ESC + DEL / BS
+  if (s === `${ESC}\x7f` || s === `${ESC}\b` || s === `${ESC}\x08`) {
+    yield { type: "key", name: "backspace", meta: true }
+    return
+  }
+
+  // Alt/Meta + Enter (many terminals send ESC + CR/LF)
+  if (s === `${ESC}\r` || s === `${ESC}\n`) {
+    yield { type: "key", name: "enter", meta: true }
+    return
+  }
+
+  // modifyOtherKeys (xterm / some terminals): CSI 27;modifier;code~
+  const moo = /^\x1b\[27;(?<mod>\d+);(?<code>\d+)~$/.exec(s)
+  if (moo?.groups) {
+    const mod = parseInt(moo.groups.mod ?? "1", 10) - 1
+    const code = parseInt(moo.groups.code ?? "0", 10)
+    const shift = !!(mod & 1)
+    const alt = !!(mod & 2)
+    const ctrl = !!(mod & 4)
+    const meta = !!(mod & 8) || alt
+    const key = fromCharCode(code, { shift, ctrl, meta, source: "modify-other" })
+    if (key) {
+      yield key
+      return
+    }
+  }
+
+  // CSI-u (modern modifyOtherKeys): CSI <code> ; <modifier> u
+  const csiu = /^\x1b\[(?<code>\d+);(?<mod>\d+)u$/.exec(s)
+  if (csiu?.groups) {
+    const mod = parseInt(csiu.groups.mod ?? "1", 10) - 1
+    const code = parseInt(csiu.groups.code ?? "0", 10)
+    const shift = !!(mod & 1)
+    const alt = !!(mod & 2)
+    const ctrl = !!(mod & 4)
+    const meta = !!(mod & 8) || alt
+    const key = fromCharCode(code, { shift, ctrl, meta, source: "csiu" })
+    if (key) {
+      yield key
+      return
+    }
+  }
+
+  // Escape (lone ESC) - handle after meta combinations
+  if (s === ESC) {
+    yield { type: "key", name: "escape" }
+    return
+  }
+
+  // Single printable
+  if (s.length === 1 && s !== ESC && s !== "\x7f") {
+    if (s === " ") {
+      yield { type: "key", name: "space", text: " " }
+      return
+    }
+    if (s >= " ") {
+      yield { type: "key", name: "char", text: s }
+      return
+    }
+  }
+
+  // Common escapes
+  switch (s) {
+    case `${ESC}[A`:
+      yield { type: "key", name: "up" }
+      return
+    case `${ESC}[B`:
+      yield { type: "key", name: "down" }
+      return
+    case `${ESC}[C`:
+      yield { type: "key", name: "right" }
+      return
+    case `${ESC}[D`:
+      yield { type: "key", name: "left" }
+      return
+    case `${ESC}[1;3C`:
+      yield { type: "key", name: "right", meta: true }
+      return
+    case `${ESC}[1;3D`:
+      yield { type: "key", name: "left", meta: true }
+      return
+    case `${ESC}OP`: // F1 (ignored)
+      return
+    case `${ESC}[H`:
+      yield { type: "key", name: "home" }
+      return
+    case `${ESC}[F`:
+      yield { type: "key", name: "end" }
+      return
+    case `${ESC}[5~`:
+      yield { type: "key", name: "pageup" }
+      return
+    case `${ESC}[6~`:
+      yield { type: "key", name: "pagedown" }
+      return
+    case `${ESC}[2~`:
+      yield { type: "key", name: "insert" }
+      return
+    case `${ESC}[3~`:
+      yield { type: "key", name: "delete" }
+      return
+    case `${ESC}[3;3~`: // Meta+Delete (best-effort for some terminals)
+      yield { type: "key", name: "delete", meta: true }
+      return
+    case `${ESC}[Z`:
+      yield { type: "key", name: "shift-tab", shift: true }
+      return
+  }
+
+  // Alt/Meta + char (ESC <char>)
+  if (s.length === 2 && s[0] === ESC && s[1] && s[1] >= " ") {
+    const ch = s[1]
+    if (ch === " ") {
+      yield { type: "key", name: "space", text: " ", meta: true }
+      return
+    }
+    yield { type: "key", name: "char", text: ch, meta: true }
+    return
+  }
+
+  // Fallback: emit printable chars individually
+  for (const ch of s) {
+    if (ch >= " ") yield { type: "key", name: "char", text: ch }
+  }
+}
+
+function fromCharCode(
+  code: number,
+  mods: { shift?: boolean; ctrl?: boolean; meta?: boolean; source: KeyMsg["source"] },
+): KeyMsg | null {
+  const { shift, ctrl, meta, source } = mods
+  const common: Omit<KeyMsg, "name"> = {
+    type: "key",
+    ctrl,
+    meta,
+    shift,
+    phase: "press",
+    source,
+  }
+
+  switch (code) {
+    case 13:
+      return { ...common, name: "enter" }
+    case 27:
+      return { ...common, name: "escape" }
+    case 9:
+      return { ...common, name: "tab" }
+    case 32:
+      return { ...common, name: "space", text: " " }
+    case 127:
+    case 8:
+      return { ...common, name: "backspace" }
+  }
+
+  if (code >= 0 && code < 32) {
+    // Control character -> map to letter when possible
+    const letter = String.fromCharCode(code + 96)
+    return { ...common, name: "char", text: letter, ctrl: true }
+  }
+
+  const ch = String.fromCharCode(code)
+  return { ...common, name: "char", text: ch }
+}

package/src/layout/linearStack.ts

@@ -0,0 +1,115 @@
+// linearStack.ts — SwiftUI-like linear stacks with flexible children
+
+export type Axis = "horizontal" | "vertical"
+export type Size = { w: number; h: number }
+export type Rect = { x: number; y: number; w: number; h: number }
+export type HAlign = "leading" | "center" | "trailing"
+export type VAlign = "top" | "center" | "bottom"
+
+/** flexBase[i] = null for fixed, or the child's base main-size for flexible. */
+export function measureLinear(
+  axis: Axis,
+  maxW: number,
+  maxH: number,
+  spacing: number,
+  sizes: Size[],
+  flexBase: (number | null)[],
+): Size {
+  const n = sizes.length
+  const gaps = Math.max(0, n - 1) * Math.max(0, spacing)
+
+  let mainSum = 0
+  let crossMax = 0
+  let hasFlex = false
+
+  for (let i = 0; i < n; i++) {
+    const s = sizes[i]
+    if (!s) continue
+    const main = axis === "horizontal" ? s.w : s.h
+    const cross = axis === "horizontal" ? s.h : s.w
+    crossMax = Math.max(crossMax, cross)
+    hasFlex ||= flexBase[i] != null
+    mainSum += flexBase[i] ?? main
+  }
+
+  const maxMain = axis === "horizontal" ? maxW : maxH
+  const totalMain = hasFlex ? maxMain : Math.min(maxMain, mainSum + gaps)
+
+  return axis === "horizontal"
+    ? { w: Math.min(maxW, totalMain), h: Math.min(maxH, crossMax) }
+    : { w: Math.min(maxW, crossMax), h: Math.min(maxH, totalMain) }
+}
+
+export function layoutLinear(
+  axis: Axis,
+  rect: Rect,
+  spacing: number,
+  crossAlign: HAlign | VAlign,
+  sizes: Size[],
+  flexBase: (number | null)[],
+): Rect[] {
+  const n = sizes.length
+  const out: Rect[] = new Array(n)
+  const gaps = Math.max(0, n - 1) * Math.max(0, spacing)
+
+  const mainAvail = axis === "horizontal" ? rect.w : rect.h
+  const crossAvail = axis === "horizontal" ? rect.h : rect.w
+
+  let baseSum = 0
+  let flexCount = 0
+  for (let i = 0; i < n; i++) {
+    if (flexBase[i] != null) {
+      baseSum += flexBase[i]!
+      flexCount++
+    } else {
+      const size = sizes[i]
+      if (size) {
+        baseSum += axis === "horizontal" ? size.w : size.h
+      }
+    }
+  }
+
+  const leftover = Math.max(0, mainAvail - baseSum - gaps)
+  const per = flexCount > 0 ? Math.floor(leftover / flexCount) : 0
+  let rem = flexCount > 0 ? leftover - per * flexCount : 0
+
+  const crossOffset = (childCross: number) => {
+    if (crossAlign === "center") return Math.floor((crossAvail - childCross) / 2)
+    if ((crossAlign === "trailing" && axis === "vertical") || (crossAlign === "bottom" && axis === "horizontal"))
+      return Math.max(0, crossAvail - childCross)
+    return 0
+  }
+
+  let pos = 0
+  for (let i = 0; i < n; i++) {
+    const s = sizes[i]
+    if (!s) continue
+    const baseMain = flexBase[i] ?? (axis === "horizontal" ? s.w : s.h)
+    const flexExtra = flexBase[i] != null ? per + (rem > 0 ? (rem--, 1) : 0) : 0
+    const wantMain = baseMain + flexExtra
+    const childCross = Math.min(crossAvail, axis === "horizontal" ? s.h : s.w)
+    const remaining = Math.max(0, mainAvail - pos)
+    const takeMain = Math.min(wantMain, remaining)
+    const cs = crossOffset(childCross)
+
+    out[i] =
+      axis === "horizontal"
+        ? { x: rect.x + pos, y: rect.y + cs, w: Math.max(0, takeMain), h: Math.max(0, childCross) }
+        : { x: rect.x + cs, y: rect.y + pos, w: Math.max(0, childCross), h: Math.max(0, takeMain) }
+
+    pos += takeMain
+    if (i < n - 1) pos += spacing
+
+    if (pos >= mainAvail) {
+      for (let j = i + 1; j < n; j++) {
+        out[j] =
+          axis === "horizontal"
+            ? { x: rect.x + mainAvail, y: rect.y, w: 0, h: 0 }
+            : { x: rect.x, y: rect.y + mainAvail, w: 0, h: 0 }
+      }
+      break
+    }
+  }
+
+  return out
+}