bare-tui 0.0.0 → 0.0.1

package/key.js

@@ -0,0 +1,29 @@
+// Key matching helpers — the ergonomic front door to KeyMsg in update().
+//
+//   const { key } = require('./lib/tea')
+//   if (key.matches(msg, 'q', 'ctrl+c')) return [model, quit]
+//
+// matches() is null/type-safe: it returns false for any non-key Msg, so you
+// don't have to guard `msg.type === 'key'` first.
+
+// A reusable named binding: the chords that trigger an action plus optional
+// help text. Shaped for a future help component, but useful now as a single
+// place to define an action's keys.
+//   const up = key.binding({ keys: ['up', 'k'], help: { key: '↑/k', desc: 'up' } })
+//   if (key.matches(msg, up)) ...
+function binding({ keys = [], help = null } = {}) {
+  return { keys: [].concat(keys), help }
+}
+
+// True if `msg` is a key matching any of the given chords or bindings. Bindings
+// are expanded to their `keys`, so you can mix:
+//   key.matches(msg, 'enter', someBinding, 'ctrl+c')
+function matches(msg, ...items) {
+  if (!msg || msg.type !== 'key' || typeof msg.is !== 'function') return false
+  const chords = items.flatMap((item) =>
+    item && typeof item === 'object' && Array.isArray(item.keys) ? item.keys : [item]
+  )
+  return msg.is(...chords)
+}
+
+module.exports = { matches, binding }

package/messages.js

@@ -0,0 +1,62 @@
+// Messages (Msg) are the only thing that flows into a model's update().
+//
+// A Msg is just a tagged plain object — authors can define their own. These are
+// the ones the runtime itself produces. We keep the shapes small and stable so
+// they read the same as Bubble Tea's KeyMsg / WindowSizeMsg / QuitMsg.
+
+// KeyMsg wraps a decoded key from bare-ansi-escapes' KeyDecoder. The raw fields
+// (name, ctrl, meta, shift, sequence) are preserved; toString() renders the
+// Bubble Tea-style chord ("ctrl+c", "up", "enter") so update() can match on a
+// single string instead of juggling booleans.
+class KeyMsg {
+  constructor(key) {
+    this.type = 'key'
+    this.name = key.name
+    this.sequence = key.sequence
+    this.ctrl = key.ctrl
+    this.meta = key.meta
+    this.shift = key.shift
+  }
+
+  toString() {
+    const parts = []
+    if (this.ctrl) parts.push('ctrl')
+    if (this.meta) parts.push('alt')
+    // Only surface shift for named keys; letters already arrive upper/lower.
+    if (this.shift && this.name && this.name.length > 1) parts.push('shift')
+    parts.push(this.name === 'return' ? 'enter' : this.name)
+    return parts.join('+')
+  }
+
+  // True if this key matches any of the given chords. A chord is matched
+  // against both the full string form ("ctrl+c", "enter") and the bare name
+  // ("c", "return"), so 'enter'/'return' and 'esc'/'escape' both work.
+  //   if (msg.is('q', 'ctrl+c')) ...
+  is(...chords) {
+    const str = this.toString()
+    for (let chord of chords) {
+      if (chord === 'esc') chord = 'escape'
+      if (chord === str || chord === this.name) return true
+    }
+    return false
+  }
+}
+
+// Emitted on startup and whenever the terminal is resized.
+function windowSize(width, height) {
+  return { type: 'resize', width, height }
+}
+
+// The runtime tears down and exits when it sees this. `quit` (see commands.js)
+// is the Cmd that produces it.
+function quitMsg() {
+  return { type: 'quit' }
+}
+
+// Wraps an error thrown by a Cmd so it can be handled in update() rather than
+// crashing the loop.
+function errorMsg(error) {
+  return { type: 'error', error }
+}
+
+module.exports = { KeyMsg, windowSize, quitMsg, errorMsg }

package/mouse.js

@@ -0,0 +1,102 @@
+// Mouse support — SGR (1006) tracking and decoding.
+//
+// bare-ansi-escapes' KeyDecoder doesn't understand mouse reports, so the
+// Program runs raw input through MouseParser first: it pulls SGR sequences
+// (\x1b[<b;x;yM for press / motion, \x1b[<b;x;ym for release) out of the byte
+// stream as MouseMsgs and forwards everything else to the key decoder.
+//
+// A MouseMsg looks like:
+//   { type: 'mouse', action, button, x, y, ctrl, alt, shift }
+//   action: 'press' | 'release' | 'motion' | 'wheel'
+//   button: 'left' | 'middle' | 'right' | 'none' | 'wheelup' | 'wheeldown'
+//   x, y:   zero-indexed cell coordinates
+const { constants } = require('bare-ansi-escapes')
+const CSI = constants.CSI
+
+const SGR = '?1006' // SGR extended coordinates (no 223-column cap, clean parse)
+const MODES = {
+  basic: '?1000', // press / release
+  drag: '?1002', // + motion while a button is held
+  all: '?1003' // + motion with no button (hover)
+}
+
+function enable(mode = 'basic') {
+  const m = MODES[mode] || MODES.basic
+  return CSI + m + 'h' + CSI + SGR + 'h'
+}
+
+function disable(mode = 'basic') {
+  const m = MODES[mode] || MODES.basic
+  return CSI + SGR + 'l' + CSI + m + 'l'
+}
+
+const BUTTONS = ['left', 'middle', 'right', 'none']
+
+// Decode the "b;x;y" body of an SGR mouse report plus its final char.
+function decode(body, final) {
+  const parts = body.split(';')
+  if (parts.length !== 3) return null
+  const b = Number(parts[0])
+  const col = Number(parts[1])
+  const row = Number(parts[2])
+  if (!Number.isInteger(b) || !Number.isInteger(col) || !Number.isInteger(row)) {
+    return null
+  }
+
+  const mods = { ctrl: !!(b & 16), alt: !!(b & 8), shift: !!(b & 4) }
+
+  let action
+  let button
+  if (b & 64) {
+    action = 'wheel'
+    button = b & 1 ? 'wheeldown' : 'wheelup'
+  } else {
+    button = BUTTONS[b & 3]
+    action = b & 32 ? 'motion' : final === 'M' ? 'press' : 'release'
+  }
+
+  return { type: 'mouse', action, button, x: col - 1, y: row - 1, ...mods }
+}
+
+// Splits a byte stream into MouseMsgs and the remaining key bytes. Holds an
+// incomplete trailing mouse sequence between feeds; uses latin1 throughout so
+// non-mouse bytes (including 8-bit meta keys) round-trip to the decoder intact.
+//
+// Note: a mouse report split across two reads *before* its `<` arrives can't be
+// distinguished from a key escape, so we only buffer once `\x1b[<` is seen.
+// Terminals emit each report in a single write, so this is not a problem in
+// practice.
+class MouseParser {
+  constructor() {
+    this._partial = ''
+  }
+
+  feed(buf) {
+    const s = this._partial + buf.toString('latin1')
+    this._partial = ''
+
+    let keys = ''
+    const events = []
+    let i = 0
+    while (i < s.length) {
+      if (s[i] === '\x1b' && s[i + 1] === '[' && s[i + 2] === '<') {
+        let j = i + 3
+        while (j < s.length && s[j] !== 'M' && s[j] !== 'm') j++
+        if (j >= s.length) {
+          this._partial = s.slice(i) // incomplete report; wait for more
+          break
+        }
+        const ev = decode(s.slice(i + 3, j), s[j])
+        if (ev) events.push(ev)
+        i = j + 1
+      } else {
+        keys += s[i]
+        i++
+      }
+    }
+
+    return { keys: Buffer.from(keys, 'latin1'), events }
+  }
+}
+
+module.exports = { enable, disable, decode, MouseParser, MODES }

package/package.json

@@ -1 +1,59 @@
-{"name":"bare-tui","version":"0.0.0"}
+{
+  "name": "bare-tui",
+  "version": "0.0.1",
+  "description": "A little TUI framework for Bare, based on bubbletea",
+  "main": "index.js",
+  "exports": {
+    "./package": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "package.json",
+    "index.js",
+    "index.d.ts",
+    "ansi.js",
+    "commands.js",
+    "key.js",
+    "messages.js",
+    "mouse.js",
+    "program.js",
+    "renderer.js",
+    "style.js",
+    "components",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "bare-ansi-escapes": "^2.2.3",
+    "bare-tty": "^5.1.0"
+  },
+  "devDependencies": {
+    "bare-fs": "^4.7.1",
+    "bare-path": "^3.0.0",
+    "bare-stream": "^2.13.1",
+    "brittle": "^3.19.0",
+    "lunte": "^1.2.0",
+    "prettier": "^3.6.2",
+    "prettier-config-holepunch": "^2.0.0"
+  },
+  "scripts": {
+    "format": "prettier --write . && lunte --fix",
+    "lint": "prettier --check . && lunte",
+    "test": "brittle-bare --coverage test/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/holepunchto/bare-tui.git"
+  },
+  "author": "Holepunch",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/holepunchto/bare-tui/issues"
+  },
+  "homepage": "https://github.com/holepunchto/bare-tui"
+}

package/program.js

@@ -0,0 +1,313 @@
+// Program is the runtime — the event loop that drives one model.
+//
+// The Elm Architecture in three methods on a model:
+//   init()        -> Cmd | null            run once at startup
+//   update(msg)   -> [model, Cmd] | model  fold a Msg into new state
+//   view()        -> string                render current state to text
+//
+// Program wires those to the terminal: it puts the input into raw mode, decodes
+// keystrokes into KeyMsgs, turns SIGWINCH into resize Msgs, runs the
+// update/render loop, executes Cmds off the update path, and — crucially —
+// always restores the terminal on the way out.
+//
+// IO is injectable. By default it grabs the real TTY (fd 0/1); tests pass their
+// own streams plus `isTTY: true` to exercise the full escape-sequence path
+// without a terminal.
+const tty = require('bare-tty')
+const KeyDecoder = require('bare-ansi-escapes/key-decoder')
+const Renderer = require('./renderer')
+const mouse = require('./mouse')
+const { KeyMsg, windowSize } = require('./messages')
+
+module.exports = class Program {
+  constructor(model, opts = {}) {
+    this.model = model
+    this.opts = opts
+    this.altScreen = opts.altScreen !== false
+
+    // Frame coalescing: many Msgs arriving within one frame produce a single
+    // render. fps <= 0 renders synchronously per update (handy in tests).
+    this.fps = opts.fps ?? 60
+    this._frameMs = this.fps > 0 ? Math.max(1, Math.round(1000 / this.fps)) : 0
+    this._frameTimer = null
+    this._needsRender = false
+
+    // Mouse tracking: true → press/release, 'drag' → + held-button motion,
+    // 'all' → + hover motion. Off by default.
+    const m = opts.mouse
+    this._mouseMode = m === true ? 'basic' : m === 'motion' ? 'drag' : m in mouse.MODES ? m : null
+    this._mouseParser = null
+
+    // Only TTY fds can be put in raw mode / sized, and constructing a
+    // tty.WriteStream on a non-TTY fd throws — so fall back to a no-op-ish
+    // stream when there's no real terminal and nothing was injected.
+    this._ownsInput = !opts.input
+    this._ownsOutput = !opts.output
+    this.input = opts.input || (tty.isTTY(0) ? new tty.ReadStream(0) : null)
+    this.output = opts.output || (tty.isTTY(1) ? new tty.WriteStream(1) : null)
+
+    // `isTTY` override lets headless tests drive the real rendering path.
+    const detected = (s) => !!(s && s.isTTY)
+    this.inputIsTTY = opts.isTTY ?? detected(this.input)
+    this.outputIsTTY = opts.isTTY ?? detected(this.output)
+
+    if (!this.output) {
+      throw new Error('tea: no output stream (not a TTY); pass opts.output')
+    }
+
+    this.renderer = new Renderer(this.output, { altScreen: this.altScreen })
+
+    // Single-consumer async message queue. send() wakes the loop.
+    this._queue = []
+    this._wake = null
+    this._running = false
+    this._tornDown = false
+
+    this._decoder = null
+    this._onInput = null
+    this._onKey = null
+    this._onResize = null
+    this._signals = []
+  }
+
+  // Enqueue a Msg from anywhere — key decoder, resize handler, Cmd result, or
+  // external code (e.g. a worker IPC bridge calling program.send(...)).
+  send(msg) {
+    if (!msg) return
+    this._queue.push(msg)
+    if (this._wake) {
+      const wake = this._wake
+      this._wake = null
+      wake()
+    }
+  }
+
+  quit() {
+    this.send({ type: 'quit' })
+  }
+
+  async run() {
+    this._running = true
+    // try/finally guarantees the terminal is restored even if init/update/view
+    // throws — otherwise a single bad model would leave the user in raw mode and
+    // the alt-screen. The error still propagates after cleanup.
+    try {
+      this._setup()
+
+      if (typeof this.model.init === 'function') this._exec(this.model.init())
+      this.renderer.render(this._view()) // first frame before any input
+
+      while (this._running) {
+        const msg = await this._next()
+        if (!msg) continue
+        if (msg.type === 'quit') break
+        if (msg.type === 'resize') this.renderer.clear() // geometry changed: repaint
+
+        const [model, cmd] = this._update(msg)
+        this.model = model
+        this._invalidate() // coalesced render
+        this._exec(cmd)
+      }
+    } finally {
+      this._running = false
+      this._cancelFrame()
+      // Flush any pending coalesced frame so the final state is the last thing
+      // drawn (matters for inline mode; harmless under the alt-screen).
+      if (this._needsRender) {
+        this._needsRender = false
+        this.renderer.render(this._view())
+      }
+      this._teardown()
+    }
+    return this.model
+  }
+
+  // Mark the view dirty and schedule a render at most once per frame. Updates
+  // that land in the same frame collapse into one write.
+  _invalidate() {
+    if (this._frameMs === 0) {
+      this.renderer.render(this._view())
+      return
+    }
+    this._needsRender = true
+    if (this._frameTimer) return
+    this._frameTimer = setTimeout(() => {
+      this._frameTimer = null
+      if (this._needsRender) {
+        this._needsRender = false
+        this.renderer.render(this._view())
+      }
+    }, this._frameMs)
+  }
+
+  _cancelFrame() {
+    if (this._frameTimer) {
+      clearTimeout(this._frameTimer)
+      this._frameTimer = null
+    }
+  }
+
+  _setup() {
+    if (this.input) {
+      if (this.inputIsTTY && this.input.setRawMode) this.input.setRawMode(true)
+      this._decoder = new KeyDecoder()
+      // Forward bytes manually instead of input.pipe(decoder): streamx has no
+      // unpipe, and a piped source destroyed mid-stream (which is exactly what
+      // teardown does) destroys the destination with a synthetic "closed before
+      // ending" error. Manual forwarding has no Pipeline, so teardown is clean.
+      this._mouseParser = this._mouseMode ? new mouse.MouseParser() : null
+      this._onKey = (key) => this.send(new KeyMsg(key))
+      this._onInput = (data) => {
+        if (this._mouseParser) {
+          // Peel mouse reports off the stream; the rest is keys.
+          const { keys, events } = this._mouseParser.feed(data)
+          for (const event of events) this.send(event)
+          if (keys.length) this._decoder.write(keys)
+        } else {
+          this._decoder.write(data)
+        }
+      }
+      this._decoder.on('data', this._onKey)
+      this.input.on('data', this._onInput)
+    }
+
+    if (this.outputIsTTY && typeof this.output.on === 'function') {
+      this._onResize = () => this.send(windowSize(this.output.columns, this.output.rows))
+      this.output.on('resize', this._onResize)
+    }
+
+    this.renderer.start()
+    if (this._mouseMode) this.output.write(mouse.enable(this._mouseMode))
+
+    // Seed the model with the initial geometry. Real TTYs report columns/rows;
+    // injected streams won't, so fall back to opts then a sane default.
+    const width = this.output.columns ?? this.opts.width ?? 80
+    const height = this.output.rows ?? this.opts.height ?? 24
+    this.send(windowSize(width, height))
+
+    // In raw mode the kernel won't deliver Ctrl+C as SIGINT (the app sees it as
+    // a key), but a kill/hangup from outside still must restore the terminal.
+    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+      const handler = () => this.send({ type: 'quit' })
+      try {
+        global.Bare.on(sig, handler)
+        this._signals.push([sig, handler])
+      } catch {}
+    }
+  }
+
+  _teardown() {
+    if (this._tornDown) return
+    this._tornDown = true
+
+    // No frame may fire after the screen is restored, or it writes onto the
+    // user's normal buffer.
+    this._cancelFrame()
+
+    for (const [sig, handler] of this._signals) {
+      try {
+        global.Bare.removeListener(sig, handler)
+      } catch {}
+    }
+    try {
+      if (this._onResize) this.output.removeListener('resize', this._onResize)
+    } catch {}
+    // Detach the manual forwarders before tearing anything down so neither
+    // stream sees data after it's gone.
+    try {
+      if (this.input && this._onInput) {
+        this.input.removeListener('data', this._onInput)
+      }
+    } catch {}
+    try {
+      if (this._decoder && this._onKey) {
+        this._decoder.removeListener('data', this._onKey)
+      }
+    } catch {}
+    try {
+      this._decoder?.destroy()
+    } catch {}
+    try {
+      if (this.input && this.inputIsTTY && this.input.setRawMode) {
+        this.input.setRawMode(false)
+      }
+    } catch {}
+    try {
+      if (this._mouseMode) this.output.write(mouse.disable(this._mouseMode))
+    } catch {}
+
+    this.renderer.stop() // show cursor, leave alt screen
+
+    // We own the input fd, so close it; leave output open in case the host CLI
+    // keeps writing after the TUI exits.
+    if (this._ownsInput && this.input) {
+      try {
+        this.input.destroy()
+      } catch {}
+    }
+  }
+
+  // Normalise update()'s return into a [model, cmd] pair. Accepts a bare model
+  // (no cmd) or null (no change), so update() can be terse.
+  _update(msg) {
+    const ret = this.model.update(msg)
+    if (ret === undefined || ret === null) return [this.model, null]
+    if (Array.isArray(ret)) return [ret[0] ?? this.model, ret[1] ?? null]
+    return [ret, null]
+  }
+
+  _view() {
+    try {
+      return String(this.model.view())
+    } catch (err) {
+      return 'view error: ' + (err && err.message)
+    }
+  }
+
+  // Kick off a Cmd off the update path. Fire-and-forget at the top level —
+  // _runCmd dispatches each resulting Msg as it resolves.
+  _exec(cmd) {
+    this._runCmd(cmd)
+  }
+
+  // Recursively run a Cmd to completion. One function handles every shape so
+  // they nest correctly:
+  //   null/undefined  -> nothing
+  //   array (batch)   -> run all concurrently, resolve when the last finishes
+  //   { __seq } (seq) -> run in order, awaiting each (and its nested cmds)
+  //   function (Cmd)  -> call it, send the Msg it returns
+  // Bails if the program is quitting so a sequence can't outlive teardown.
+  async _runCmd(cmd) {
+    if (!cmd || !this._running) return
+
+    if (Array.isArray(cmd)) {
+      await Promise.all(cmd.map((c) => this._runCmd(c)))
+      return
+    }
+
+    if (cmd.__seq) {
+      for (const c of cmd.__seq) {
+        if (!this._running) return
+        await this._runCmd(c)
+      }
+      return
+    }
+
+    try {
+      this.send(await cmd())
+    } catch (error) {
+      this.send({ type: 'error', error })
+    }
+  }
+
+  // Await the next Msg. The executor body runs synchronously, so _wake is set
+  // before we suspend — no lost-wakeup race with send().
+  async _next() {
+    if (this._queue.length === 0) {
+      await new Promise((resolve) => {
+        this._wake = resolve
+      })
+    }
+    return this._queue.shift()
+  }
+}

package/renderer.js

@@ -0,0 +1,67 @@
+// The renderer turns a model's View() string into terminal output, repainting
+// only what changed.
+//
+// View() returns the whole frame as text. Naively rewriting it every tick
+// flickers and wastes bandwidth, so we keep the previous frame and, on each
+// render, only rewrite the lines that actually differ — addressing them with
+// absolute cursor moves. This is the same strategy as Bubble Tea's standard
+// renderer, and it's what makes a redraw-on-every-keystroke loop feel instant.
+const ansi = require('./ansi')
+
+module.exports = class Renderer {
+  constructor(output, { altScreen = true } = {}) {
+    this.out = output
+    this.altScreen = altScreen
+    this.lastLines = null // null => next render is a full repaint
+  }
+
+  // Enter the screen: optional alt buffer, hide the cursor, clear.
+  start() {
+    let s = ''
+    if (this.altScreen) s += ansi.enterAltScreen
+    s += ansi.cursorHide + ansi.home + ansi.eraseDisplay
+    this.out.write(s)
+  }
+
+  // Force the next render() to repaint everything (used on resize).
+  clear() {
+    this.lastLines = null
+  }
+
+  render(view) {
+    const lines = String(view).split('\n')
+    let s = ''
+
+    if (this.lastLines === null) {
+      // Full repaint. \r\n (not \n) because raw mode doesn't translate \n into
+      // a carriage return, so we'd otherwise stair-step down the screen.
+      s += ansi.home
+      for (let i = 0; i < lines.length; i++) {
+        s += ansi.eraseLineEnd + lines[i]
+        if (i < lines.length - 1) s += '\r\n'
+      }
+      s += ansi.eraseDisplayEnd
+    } else {
+      // Diff: touch only changed rows.
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i] !== this.lastLines[i]) {
+          s += ansi.cursorTo(i, 0) + ansi.eraseLineEnd + lines[i]
+        }
+      }
+      // The frame got shorter — wipe the now-orphaned rows below it.
+      if (this.lastLines.length > lines.length) {
+        s += ansi.cursorTo(lines.length, 0) + ansi.eraseDisplayEnd
+      }
+    }
+
+    this.lastLines = lines
+    if (s) this.out.write(s)
+  }
+
+  // Restore the terminal: show the cursor, leave the alt buffer.
+  stop() {
+    let s = ansi.cursorShow
+    if (this.altScreen) s += ansi.leaveAltScreen
+    this.out.write(s)
+  }
+}