bare-tui 0.2.0 → 0.3.0

package/README.md

@@ -107,9 +107,10 @@ Run it with `bare counter.js`. The `Program` puts the terminal into raw mode, en
 A **command** (`Cmd`) is a function `() => Msg | Promise<Msg> | null`. The runtime runs it _off_ the update path and feeds whatever message it returns back into `update`. This is how you do anything asynchronous — timers, file or network I/O, talking to a worker — without blocking the UI.
 
 ```js
-const { quit, batch, sequence, tick, every, suspend } = require('bare-tui')
+const { quit, repaint, batch, sequence, tick, every, suspend } = require('bare-tui')
 
 quit // a Cmd that quits the program
+repaint // a Cmd that forces a full repaint of the screen
 tick(1000, () => ({ type: 'tick' })) // fire a Msg after 1s
 every(1000, () => ({ type: 'tick' })) // fire on the wall-clock second
 batch(cmdA, cmdB) // run several Cmds concurrently
@@ -140,9 +141,24 @@ const load = () =>
 
 Return commands from `init` or `update`; the result comes back as a message.
 
+## Repainting
+
+The renderer rewrites only the rows whose text actually changed, which is what makes a redraw-per-keystroke loop feel instant. The flip side is that it has no way to know when _something else_ has drawn over the screen — a native library logging to the same fd, a multiplexer redrawing a pane, a terminal that dropped the alt-screen. Those rows are never repainted on their own: a header with a clock heals itself on the next frame, while a static body stays broken.
+
+When you know the screen may have been disturbed, ask for a full repaint:
+
+```js
+return [model, repaint] // from update()
+program.repaint() // from outside the loop
+```
+
+The runtime already repaints on its own whenever the window is resized, after a `suspend`, and — if you enabled `focus: true` — whenever the window regains focus.
+
+You should not need it for your own output: the renderer knows the screen size and fits every frame to it, dropping rows past the last one and trimming lines to the visible width (measured in cells, so ANSI escapes and wide glyphs are counted correctly). That matters because a frame one row too tall scrolls the terminal, and every absolute cursor move after that addresses the wrong row — permanently. If content is disappearing off the bottom or right, your layout is bigger than the terminal; measure it with `style.height` / `style.width` rather than counting lines by hand.
+
 ## Key, mouse & focus input
 
-Keys arrive as `{ type: 'key' }` messages (a `KeyMsg`). Match them with `key.matches`, which is null- and type-safe:
+Keys arrive as `{ type: 'key' }` messages (a `KeyMsg`). Match them with `key.matches`, which is null- and type-safe. A chord is compared whole — `'up'` does not match `ctrl+up` — and `esc`/`escape`, `enter`/`return` are aliases:
 
 ```js
 if (key.matches(msg, 'enter')) ...
@@ -172,6 +188,8 @@ new Program(model, { focus: true })
 
 Focus messages are **transitions**, not state: nothing is sent until the focus actually changes, so assume you start focused. They may also never arrive at all — Terminal.app, `screen` and the Linux console don't implement the mode, and under tmux the pane needs `set -g focus-events on`. Don't gate anything your app needs on receiving one.
 
+With `focus: true` the runtime also repaints the whole screen on every focus-in, on the theory that anything could have happened to the window while you were away.
+
 ## Components
 
 Ready-made, composable pieces — each is a model (`update`/`view`) you embed in your own. See each doc for options, methods, messages, and keybindings.

package/commands.js

@@ -7,7 +7,7 @@
 // update() returns `[model, cmd]`. `cmd` may be a single Cmd, an array of Cmds
 // (run concurrently — see batch), a sequence marker (run in order — see
 // sequence), or null for "do nothing".
-const { quitMsg } = require('./messages')
+const { quitMsg, repaintMsg } = require('./messages')
 
 // `quit` is itself a Cmd: return it from update() to tear down and exit, e.g.
 //   return [model, quit]
@@ -15,6 +15,16 @@ function quit() {
   return quitMsg()
 }
 
+// Force a full repaint of the screen on the next frame:
+//   return [model, repaint]
+// The renderer normally rewrites only the rows whose text changed, which is
+// what makes it fast — but it also means it cannot know when something else has
+// drawn over the screen. Reach for this after spawning something that writes to
+// the same terminal, or whenever the display might have been disturbed.
+function repaint() {
+  return repaintMsg()
+}
+
 // Run several Cmds concurrently. The runtime expands arrays, so batch is just a
 // null-filtering spread — but naming it documents intent at the call site.
 function batch(...cmds) {
@@ -64,4 +74,4 @@ function every(ms, fn) {
     })
 }
 
-module.exports = { quit, batch, sequence, tick, every, suspend }
+module.exports = { quit, repaint, batch, sequence, tick, every, suspend }

package/components/chars.js

@@ -0,0 +1,38 @@
+// Characters, not code units. A JS string index can land inside a surrogate
+// pair — every emoji is one — so the text fields step their cursor with these
+// and insert whatever printable string the decoder handed them.
+
+// A key that should be inserted as text: no modifier, and a sequence with no
+// control bytes in it. Named keys always arrive as escape sequences, so they
+// fail the second test; a single grapheme such as '❤️' passes whole.
+function printable(msg) {
+  const s = msg.sequence
+  // eslint-disable-next-line no-control-regex
+  return (
+    !msg.ctrl && !msg.meta && typeof s === 'string' && s.length > 0 && !/[\x00-\x1f\x7f]/.test(s)
+  )
+}
+
+// Index of the start of the character before `i`.
+function before(s, i) {
+  if (i <= 0) return 0
+  const j = i - 1
+  return j > 0 && isLow(s.charCodeAt(j)) && isHigh(s.charCodeAt(j - 1)) ? j - 1 : j
+}
+
+// Index just past the character at `i`.
+function after(s, i) {
+  if (i >= s.length) return s.length
+  return i + (isHigh(s.charCodeAt(i)) && isLow(s.charCodeAt(i + 1)) ? 2 : 1)
+}
+
+function count(s) {
+  let n = 0
+  for (let i = 0; i < s.length; i = after(s, i)) n++
+  return n
+}
+
+const isHigh = (c) => c >= 0xd800 && c <= 0xdbff
+const isLow = (c) => c >= 0xdc00 && c <= 0xdfff
+
+module.exports = { printable, before, after, count }

package/components/textarea.js

@@ -9,6 +9,7 @@
 //
 //   const ta = textarea.create({ width: 60, height: 10, placeholder: '…' }).focus()
 const ansi = require('../ansi')
+const chars = require('./chars')
 
 const dim = (s) => ansi.modifierDim + s + ansi.modifierReset
 const reverse = (s) => ansi.modifierReverse + s + ansi.modifierNotReverse
@@ -95,7 +96,7 @@ class TextArea {
   }
 
   _left() {
-    if (this.col > 0) this.col--
+    if (this.col > 0) this.col = chars.before(this._line(), this.col)
     else if (this.row > 0) {
       this.row--
       this.col = this._line().length
@@ -103,7 +104,7 @@ class TextArea {
   }
 
   _right() {
-    if (this.col < this._line().length) this.col++
+    if (this.col < this._line().length) this.col = chars.after(this._line(), this.col)
     else if (this.row < this.lines.length - 1) {
       this.row++
       this.col = 0
@@ -131,8 +132,9 @@ class TextArea {
   _backspace() {
     const line = this._line()
     if (this.col > 0) {
-      this.lines[this.row] = line.slice(0, this.col - 1) + line.slice(this.col)
-      this.col--
+      const from = chars.before(line, this.col)
+      this.lines[this.row] = line.slice(0, from) + line.slice(this.col)
+      this.col = from
     } else if (this.row > 0) {
       const prev = this.lines[this.row - 1]
       this.col = prev.length
@@ -145,7 +147,7 @@ class TextArea {
   _delete() {
     const line = this._line()
     if (this.col < line.length) {
-      this.lines[this.row] = line.slice(0, this.col) + line.slice(this.col + 1)
+      this.lines[this.row] = line.slice(0, this.col) + line.slice(chars.after(line, this.col))
     } else if (this.row < this.lines.length - 1) {
       this.lines[this.row] = line + this.lines[this.row + 1]
       this.lines.splice(this.row + 1, 1)
@@ -153,20 +155,13 @@ class TextArea {
   }
 
   _insert(msg) {
-    const ch = msg.sequence
-    const printable =
-      !msg.ctrl &&
-      !msg.meta &&
-      typeof ch === 'string' &&
-      ch.length === 1 &&
-      ch >= ' ' &&
-      ch !== '\x7f'
-    if (!printable) return
+    if (!chars.printable(msg)) return
     if (this.charLimit && this.length >= this.charLimit) return
 
+    const ch = msg.sequence
     const line = this._line()
     this.lines[this.row] = line.slice(0, this.col) + ch + line.slice(this.col)
-    this.col++
+    this.col += ch.length
   }
 
   _vertical(delta) {

package/components/textinput.js

@@ -19,6 +19,7 @@
 // Because the Program hides the real terminal cursor, the field draws its own
 // as a reverse-video cell.
 const ansi = require('../ansi')
+const chars = require('./chars')
 
 const dim = (s) => ansi.modifierDim + s + ansi.modifierReset
 const reverse = (s) => ansi.modifierReverse + s + ansi.modifierNotReverse
@@ -64,22 +65,20 @@ class TextInput {
     if (!this.focused || !msg || msg.type !== 'key') return [this, null]
 
     if (msg.is('left', 'ctrl+b')) {
-      this.cursor = Math.max(0, this.cursor - 1)
+      this.cursor = chars.before(this.value, this.cursor)
     } else if (msg.is('right', 'ctrl+f')) {
-      this.cursor = Math.min(this.value.length, this.cursor + 1)
+      this.cursor = chars.after(this.value, this.cursor)
     } else if (msg.is('home', 'ctrl+a')) {
       this.cursor = 0
     } else if (msg.is('end', 'ctrl+e')) {
       this.cursor = this.value.length
     } else if (msg.is('backspace')) {
-      if (this.cursor > 0) {
-        this.value = this.value.slice(0, this.cursor - 1) + this.value.slice(this.cursor)
-        this.cursor--
-      }
+      const from = chars.before(this.value, this.cursor)
+      this.value = this.value.slice(0, from) + this.value.slice(this.cursor)
+      this.cursor = from
     } else if (msg.is('delete')) {
-      if (this.cursor < this.value.length) {
-        this.value = this.value.slice(0, this.cursor) + this.value.slice(this.cursor + 1)
-      }
+      const to = chars.after(this.value, this.cursor)
+      this.value = this.value.slice(0, this.cursor) + this.value.slice(to)
     } else {
       this._insert(msg)
     }
@@ -87,23 +86,17 @@ class TextInput {
     return [this, null]
   }
 
-  // Insert a single printable character at the cursor. We key off the decoded
-  // sequence (not name) so case and punctuation come through verbatim, and skip
-  // control bytes, chorded keys, and DEL.
+  // Insert a printable key at the cursor. We key off the decoded sequence (not
+  // name) so case and punctuation come through verbatim, and skip control
+  // bytes, chorded keys, and DEL. The sequence may be more than one code unit:
+  // an emoji is a surrogate pair, and some come with a variation selector.
   _insert(msg) {
-    const ch = msg.sequence
-    const printable =
-      !msg.ctrl &&
-      !msg.meta &&
-      typeof ch === 'string' &&
-      ch.length === 1 &&
-      ch >= ' ' &&
-      ch !== '\x7f'
-    if (!printable) return
-    if (this.charLimit && this.value.length >= this.charLimit) return
+    if (!chars.printable(msg)) return
+    if (this.charLimit && chars.count(this.value) >= this.charLimit) return
 
+    const ch = msg.sequence
     this.value = this.value.slice(0, this.cursor) + ch + this.value.slice(this.cursor)
-    this.cursor++
+    this.cursor += ch.length
   }
 
   _display() {
@@ -123,8 +116,9 @@ class TextInput {
     if (!this.focused) return this.prompt + text
 
     // Draw the cursor as a reverse cell; a trailing space when at end-of-line.
-    const at = text.slice(this.cursor, this.cursor + 1) || ' '
-    return this.prompt + text.slice(0, this.cursor) + reverse(at) + text.slice(this.cursor + 1)
+    const end = chars.after(text, this.cursor)
+    const at = text.slice(this.cursor, end) || ' '
+    return this.prompt + text.slice(0, this.cursor) + reverse(at) + text.slice(end)
   }
 }
 

package/index.js

@@ -44,7 +44,7 @@ const focus = require('./components/focus')
 
 module.exports = {
   Program,
-  ...commands, // quit, batch, sequence, tick, every, suspend
+  ...commands, // quit, repaint, batch, sequence, tick, every, suspend
   KeyMsg: messages.KeyMsg,
   key, // key.matches(msg, ...chords | bindings), key.binding({ keys, help })
   ansi,

package/messages.js

@@ -28,20 +28,28 @@ class KeyMsg {
     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.
+  // True if this key matches any of the given chords. A chord is compared
+  // whole, so 'up' means up and not ctrl+up or shift+up; 'esc'/'escape' and
+  // 'enter'/'return' are aliases.
   //   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
+    for (const chord of chords) {
+      if (alias(chord) === str) return true
     }
     return false
   }
 }
 
+// The names a key goes by: the decoder says 'escape' and 'return', chords
+// usually say 'esc' and 'enter'. Only the final segment is a key name.
+function alias(chord) {
+  return String(chord).replace(
+    /(^|\+)(esc|return)$/,
+    (m, sep, name) => sep + (name === 'esc' ? 'escape' : 'enter')
+  )
+}
+
 // Emitted on startup and whenever the terminal is resized.
 function windowSize(width, height) {
   return { type: 'resize', width, height }
@@ -56,6 +64,16 @@ function focusMsg(focused) {
   return { type: 'focus', focused }
 }
 
+// Asks the runtime to repaint the whole screen on the next frame. The renderer
+// only rewrites rows whose text changed, so anything that draws to the terminal
+// behind its back — a native library logging to the same fd, a multiplexer
+// redrawing a pane — leaves stale rows that never heal on their own. `repaint`
+// (see commands.js) is the Cmd that produces it, and program.repaint() sends it
+// from outside the loop.
+function repaintMsg() {
+  return { type: 'repaint' }
+}
+
 // The runtime tears down and exits when it sees this. `quit` (see commands.js)
 // is the Cmd that produces it.
 function quitMsg() {
@@ -68,4 +86,4 @@ function errorMsg(error) {
   return { type: 'error', error }
 }
 
-module.exports = { KeyMsg, windowSize, focusMsg, quitMsg, errorMsg }
+module.exports = { KeyMsg, windowSize, focusMsg, repaintMsg, quitMsg, errorMsg }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-tui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A little TUI framework for Bare, based on bubbletea",
   "main": "index.js",
   "exports": {

package/program.js

@@ -20,7 +20,13 @@ const Renderer = require('./renderer')
 const ansi = require('./ansi')
 const mouse = require('./mouse')
 const { InputParser } = require('./input')
-const { KeyMsg, windowSize } = require('./messages')
+const { KeyMsg, windowSize, repaintMsg } = require('./messages')
+
+// A terminal that is minimised, occluded, or backed by a detached pty reports
+// a size of 0 — that means "unknown", not "zero rows". Forwarding it collapses
+// any `height - chrome` layout to nothing, and the app has no way back until the
+// next real resize, so we treat it as no report at all.
+const known = (n) => (typeof n === 'number' && n > 0 ? n : null)
 
 module.exports = class Program {
   constructor(model, opts = {}) {
@@ -99,6 +105,15 @@ module.exports = class Program {
     this.send({ type: 'quit' })
   }
 
+  // Force a full repaint on the next frame. The renderer only rewrites rows
+  // whose text changed, so it cannot know when something else has drawn over
+  // the screen — a native library logging to the same fd, say. Call this from
+  // outside the loop after such a write; from inside update(), return the
+  // `repaint` Cmd instead.
+  repaint() {
+    this.send(repaintMsg())
+  }
+
   async run() {
     this._running = true
     // try/finally guarantees the terminal is restored even if init/update/view
@@ -114,7 +129,12 @@ module.exports = class Program {
         const msg = await this._next()
         if (!msg) continue
         if (msg.type === 'quit') break
-        if (msg.type === 'resize') this.renderer.clear() // geometry changed: repaint
+        // Three ways the screen stops matching what the renderer believes:
+        // the geometry moved, the app told us it was disturbed, or the window
+        // came back after something else may have drawn over it.
+        if (msg.type === 'resize') this.renderer.resize(msg.width, msg.height)
+        else if (msg.type === 'repaint') this.renderer.clear()
+        else if (msg.type === 'focus' && msg.focused) this.renderer.clear()
 
         const [model, cmd] = this._update(msg)
         this.model = model
@@ -210,7 +230,12 @@ module.exports = class Program {
     }
 
     if (this.outputIsTTY && typeof this.output.on === 'function') {
-      this._onResize = () => this.send(windowSize(this.output.columns, this.output.rows))
+      this._onResize = () => {
+        const width = known(this.output.columns)
+        const height = known(this.output.rows)
+        if (width === null || height === null) return // not a real geometry
+        this.send(windowSize(width, height))
+      }
       this.output.on('resize', this._onResize)
     }
 
@@ -219,8 +244,9 @@ module.exports = class Program {
 
     // 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
+    const width = known(this.output.columns) ?? known(this.opts.width) ?? 80
+    const height = known(this.output.rows) ?? known(this.opts.height) ?? 24
+    this.renderer.resize(width, height) // fit frames to the screen from frame one
     this.send(windowSize(width, height))
 
     // In raw mode the kernel won't deliver Ctrl+C as SIGINT (the app sees it as
@@ -340,6 +366,18 @@ module.exports = class Program {
     this._enableModes()
     this.renderer.clear() // next render repaints everything
     this._suspended = false
+
+    // The window may well have been resized while the child owned the terminal,
+    // and no SIGWINCH is coming to tell us about it — we were the ones not
+    // looking. Re-read the geometry so the repaint below is drawn to the right
+    // shape, and let the model re-lay-out if it actually moved.
+    const width = known(this.output.columns)
+    const height = known(this.output.rows)
+    if (width !== null && height !== null) {
+      const moved = width !== this.renderer.width || height !== this.renderer.height
+      this.renderer.resize(width, height)
+      if (moved) this.send(windowSize(width, height))
+    }
   }
 
   // Normalise update()'s return into a [model, cmd] pair. Accepts a bare model

package/renderer.js

@@ -6,12 +6,28 @@
 // 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.
+//
+// Absolute addressing is only correct while the screen hasn't moved under us,
+// so the renderer also owns two safeguards:
+//
+//   - it knows the screen geometry and fits every frame to it, because a frame
+//     one row too tall (or one cell too wide, which wraps) scrolls the terminal
+//     and puts every subsequent row address permanently out by one;
+//   - clear() re-syncs from scratch, for the damage it can't prevent — another
+//     process writing to the same fd, a terminal that dropped the alt-screen.
+//
+// Without those, a stale row is never repainted again: only rows whose *text*
+// changed are rewritten, so a header with a clock heals itself every frame
+// while a static body stays broken for the life of the process.
 const ansi = require('./ansi')
+const { style } = require('./style')
 
 module.exports = class Renderer {
-  constructor(output, { altScreen = true } = {}) {
+  constructor(output, { altScreen = true, width = 0, height = 0 } = {}) {
     this.out = output
     this.altScreen = altScreen
+    this.width = width > 0 ? width : 0 // 0 => unknown, don't fit
+    this.height = height > 0 ? height : 0
     this.lastLines = null // null => next render is a full repaint
   }
 
@@ -23,13 +39,36 @@ module.exports = class Renderer {
     this.out.write(s)
   }
 
-  // Force the next render() to repaint everything (used on resize).
+  // Force the next render() to repaint everything (used on resize, on a
+  // repaint Msg, and when the terminal window regains focus).
   clear() {
     this.lastLines = null
   }
 
+  // Tell the renderer how big the screen is. Frames are fitted to it from here
+  // on, and the next render repaints in full since the geometry moved.
+  resize(width, height) {
+    this.width = width > 0 ? width : 0
+    this.height = height > 0 ? height : 0
+    this.clear()
+  }
+
+  // Trim one line to the screen width. Measured in visible cells — a styled
+  // line's .length counts escape bytes the terminal never draws, and a wide
+  // glyph occupies two columns.
+  _fit(line) {
+    if (this.width <= 0 || style.width(line) <= this.width) return line
+    return style.truncate(line, this.width)
+  }
+
   render(view) {
-    const lines = String(view).split('\n')
+    let lines = String(view).split('\n')
+
+    // Surplus rows would scroll the screen, and a scrolled screen breaks every
+    // absolute cursor move from then on. Losing the overflow is recoverable;
+    // losing the row addressing is not.
+    if (this.height > 0 && lines.length > this.height) lines = lines.slice(0, this.height)
+
     let s = ''
 
     if (this.lastLines === null) {
@@ -37,15 +76,17 @@ module.exports = class Renderer {
       // 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]
+        s += ansi.eraseLineEnd + this._fit(lines[i])
         if (i < lines.length - 1) s += '\r\n'
       }
       s += ansi.eraseDisplayEnd
     } else {
-      // Diff: touch only changed rows.
+      // Diff: touch only changed rows. Compare the untrimmed text — _fit is a
+      // pure function of (line, width) and a width change clears lastLines, so
+      // equal input always means equal output.
       for (let i = 0; i < lines.length; i++) {
         if (lines[i] !== this.lastLines[i]) {
-          s += ansi.cursorTo(i, 0) + ansi.eraseLineEnd + lines[i]
+          s += ansi.cursorTo(i, 0) + ansi.eraseLineEnd + this._fit(lines[i])
         }
       }
       // The frame got shorter — wipe the now-orphaned rows below it.