bare-tui 0.0.3 → 0.2.0

package/README.md

@@ -140,7 +140,7 @@ const load = () =>
 
 Return commands from `init` or `update`; the result comes back as a message.
 
-## Key & mouse input
+## Key, mouse & focus input
 
 Keys arrive as `{ type: 'key' }` messages (a `KeyMsg`). Match them with `key.matches`, which is null- and type-safe:
 
@@ -163,6 +163,15 @@ Enable the mouse with a Program option; clicks/scroll/drag arrive as `{ type: 'm
 new Program(model, { mouse: true }) //  true | 'drag' | 'all'
 ```
 
+Ask for focus reporting the same way, and the terminal tells you when its window gains or loses focus — handy for pausing an animation or muting a bell while the user is elsewhere:
+
+```js
+new Program(model, { focus: true })
+// update(msg): msg.type === 'focus' -> msg.focused is true on focus in, false on focus out
+```
+
+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.
+
 ## 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/ansi.js

@@ -30,5 +30,12 @@ module.exports = {
 
   // SGR mouse tracking (button events + SGR extended coordinates).
   enableMouse: CSI + '?1000h' + CSI + '?1006h',
-  disableMouse: CSI + '?1006l' + CSI + '?1000l'
+  disableMouse: CSI + '?1006l' + CSI + '?1000l',
+
+  // Focus reporting (DEC private mode 1004) — the terminal sends ESC [ I when
+  // the window gains focus and ESC [ O when it loses it. Plain constants rather
+  // than the enable(mode)/disable(mode) functions mouse.js exposes, because
+  // there is only one mode to set; see input.js for the reports themselves.
+  enableFocus: CSI + '?1004h',
+  disableFocus: CSI + '?1004l'
 }

package/input.js

@@ -0,0 +1,110 @@
+// Input pre-parser — peels the sequences that aren't keystrokes off the byte
+// stream before the key decoder sees them.
+//
+// bare-ansi-escapes' KeyDecoder only understands keys, so anything else the
+// terminal reports has to be claimed first: SGR mouse reports
+// (\x1b[<b;x;yM / m) and focus reports (\x1b[I on focus in, \x1b[O on focus
+// out). InputParser does both in a single pass with a single partial buffer and
+// hands the remaining bytes on untouched:
+//
+//   const parser = new InputParser({ mouse: 'basic', focus: true })
+//   const { keys, events } = parser.feed(chunk)
+//
+// Each stream is opt-in: with `focus` off a focus report is left in `keys` and
+// reaches the decoder exactly as it does today (as a key named 'undefined'), so
+// enabling one mode never changes the other's behaviour. latin1 throughout so
+// non-claimed bytes — including 8-bit meta keys — round-trip intact.
+const { decode } = require('./mouse')
+const { focusMsg } = require('./messages')
+
+const ESC = '\x1b'
+
+// An SGR mouse body is "b;x;y" — at most a handful of digits. Bounding the scan
+// keeps a stray \x1b[< (which a user can type) from swallowing the rest of the
+// session while it hunts for a terminator that never comes.
+const MAX_MOUSE_BODY = 24
+
+class InputParser {
+  constructor({ mouse = null, focus = false } = {}) {
+    this.mouse = !!mouse
+    this.focus = !!focus
+    this._partial = ''
+  }
+
+  // Drop any half-claimed sequence. Called when the terminal is handed to a
+  // child process and reclaimed, so a prefix from before the suspend can't
+  // corrupt the first bytes read after it.
+  reset() {
+    this._partial = ''
+  }
+
+  feed(buf) {
+    const s = this._partial + buf.toString('latin1')
+    this._partial = ''
+
+    let keys = ''
+    const events = []
+    let i = 0
+
+    while (i < s.length) {
+      // Only CSI (ESC [) introduces something we might claim. This is also what
+      // keeps SS3 (ESC O, the prefix for F1-F4 and application-mode arrows)
+      // safe: it has no '[', so it never looks like a focus report.
+      if (s[i] !== ESC || s[i + 1] !== '[') {
+        keys += s[i++]
+        continue
+      }
+
+      // The read ended on a bare "ESC [". Hold it: the decoder would park on
+      // those same two bytes and emit nothing either way (its 500ms escape
+      // timer only arms when ESC is the *last* byte written), so holding costs
+      // no latency and lets a report split across reads still be recognised. A
+      // lone trailing ESC is never held — that one does time out into an
+      // escape key, and swallowing it would break the Escape key.
+      if (i + 2 >= s.length) {
+        this._partial = s.slice(i)
+        break
+      }
+
+      const c = s[i + 2]
+
+      if (this.focus && (c === 'I' || c === 'O')) {
+        events.push(focusMsg(c === 'I'))
+        i += 3
+        continue
+      }
+
+      if (this.mouse && c === '<') {
+        const cap = i + 3 + MAX_MOUSE_BODY
+        let j = i + 3
+        while (j < s.length && j < cap && ((s[j] >= '0' && s[j] <= '9') || s[j] === ';')) j++
+
+        // Stopped because the input ran out (rather than because the body is
+        // overlong or ended in something that isn't a terminator): wait for the
+        // rest of the report.
+        if (j === s.length && j < cap) {
+          this._partial = s.slice(i)
+          break
+        }
+
+        if (s[j] === 'M' || s[j] === 'm') {
+          const event = decode(s.slice(i + 3, j), s[j])
+          if (event) {
+            events.push(event)
+            i = j + 1
+            continue
+          }
+        }
+        // Malformed or overlong — not a report after all; fall through and let
+        // the bytes go to the decoder as keys.
+      }
+
+      // Not ours: emit the ESC and re-examine the rest as ordinary key bytes.
+      keys += s[i++]
+    }
+
+    return { keys: Buffer.from(keys, 'latin1'), events }
+  }
+}
+
+module.exports = { InputParser }

package/messages.js

@@ -47,6 +47,15 @@ function windowSize(width, height) {
   return { type: 'resize', width, height }
 }
 
+// Emitted when the terminal window gains or loses focus. Only ever produced
+// when the Program was created with `focus: true`, which puts the terminal into
+// focus reporting (DEC private mode 1004). Reports are *transitions*: a terminal
+// that supports the mode says nothing until the focus actually changes, so a
+// model should assume it starts focused rather than wait to be told.
+function focusMsg(focused) {
+  return { type: 'focus', focused }
+}
+
 // The runtime tears down and exits when it sees this. `quit` (see commands.js)
 // is the Cmd that produces it.
 function quitMsg() {
@@ -59,4 +68,4 @@ function errorMsg(error) {
   return { type: 'error', error }
 }
 
-module.exports = { KeyMsg, windowSize, quitMsg, errorMsg }
+module.exports = { KeyMsg, windowSize, focusMsg, quitMsg, errorMsg }

package/mouse.js

@@ -1,9 +1,8 @@
 // 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.
+// This module owns the mode strings and the report decoder; pulling the reports
+// out of the raw byte stream is input.js's job (it claims \x1b[<b;x;yM for
+// press / motion and \x1b[<b;x;ym for release, and calls decode() on the body).
 //
 // A MouseMsg looks like:
 //   { type: 'mouse', action, button, x, y, ctrl, alt, shift }
@@ -58,45 +57,4 @@ function decode(body, final) {
   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 }
+module.exports = { enable, disable, decode, MODES }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-tui",
-  "version": "0.0.3",
+  "version": "0.2.0",
   "description": "A little TUI framework for Bare, based on bubbletea",
   "main": "index.js",
   "exports": {
@@ -15,6 +15,7 @@
     "index.js",
     "index.d.ts",
     "ansi.js",
+    "input.js",
     "commands.js",
     "key.js",
     "messages.js",

package/program.js

@@ -6,7 +6,8 @@
 //   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
+// keystrokes into KeyMsgs, claims the terminal's non-key reports (mouse, and
+// focus when `focus: true`), 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.
 //
@@ -16,7 +17,9 @@
 const tty = require('bare-tty')
 const KeyDecoder = require('bare-ansi-escapes/key-decoder')
 const Renderer = require('./renderer')
+const ansi = require('./ansi')
 const mouse = require('./mouse')
+const { InputParser } = require('./input')
 const { KeyMsg, windowSize } = require('./messages')
 
 module.exports = class Program {
@@ -36,7 +39,16 @@ module.exports = class Program {
     // '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
+
+    // Focus reporting (DEC mode 1004): the terminal reports when its window
+    // gains or loses focus as { type: 'focus', focused }. Off by default — not
+    // every terminal implements it (Terminal.app and screen don't; tmux needs
+    // `focus-events on`), and an app that doesn't care shouldn't pay for it.
+    this._focus = opts.focus === true
+
+    // Claims mouse / focus reports before the key decoder. Null when neither is
+    // enabled, so the common case writes bytes straight through.
+    this._parser = 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
@@ -151,6 +163,28 @@ module.exports = class Program {
     }
   }
 
+  // The pre-parser only exists when there's something to claim; otherwise input
+  // bytes go straight to the key decoder.
+  _newParser() {
+    if (!this._mouseMode && !this._focus) return null
+    return new InputParser({ mouse: this._mouseMode, focus: this._focus })
+  }
+
+  // The input reporting modes go on together after the screen is entered and
+  // come off together before it's restored, so they never outlive the program
+  // (_teardown) or leak into a child process (_suspendTerminal).
+  _enableModes() {
+    if (this._mouseMode) this.output.write(mouse.enable(this._mouseMode))
+    if (this._focus) this.output.write(ansi.enableFocus)
+  }
+
+  _disableModes() {
+    try {
+      if (this._mouseMode) this.output.write(mouse.disable(this._mouseMode))
+      if (this._focus) this.output.write(ansi.disableFocus)
+    } catch {}
+  }
+
   _setup() {
     if (this.input) {
       if (this.inputIsTTY && this.input.setRawMode) this.input.setRawMode(true)
@@ -159,12 +193,12 @@ module.exports = class Program {
       // 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._parser = this._newParser()
       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)
+        if (this._parser) {
+          // Peel mouse / focus reports off the stream; the rest is keys.
+          const { keys, events } = this._parser.feed(data)
           for (const event of events) this.send(event)
           if (keys.length) this._decoder.write(keys)
         } else {
@@ -181,7 +215,7 @@ module.exports = class Program {
     }
 
     this.renderer.start()
-    if (this._mouseMode) this.output.write(mouse.enable(this._mouseMode))
+    this._enableModes()
 
     // 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.
@@ -231,14 +265,15 @@ module.exports = class Program {
     try {
       this._decoder?.destroy()
     } catch {}
+    // Stop the reporting modes before leaving raw mode: in between the terminal
+    // is line-buffered and echoing, so a report landing in that window would be
+    // painted onto the screen we're about to hand back.
+    this._disableModes()
     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
 
@@ -272,15 +307,17 @@ module.exports = class Program {
       this._decoder?.destroy()
     } catch {}
     this._decoder = null
+    // A half-claimed sequence must not survive into the resumed session.
+    this._parser?.reset()
+    // Off before the child runs: a program that doesn't understand these reports
+    // would read them as garbage input.
+    this._disableModes()
     try {
       if (this.input && this.inputIsTTY && this.input.setRawMode) this.input.setRawMode(false)
     } catch {}
     try {
       this.input?.pause?.()
     } catch {}
-    try {
-      if (this._mouseMode) this.output.write(mouse.disable(this._mouseMode))
-    } catch {}
     this.renderer.stop()
   }
 
@@ -293,13 +330,14 @@ module.exports = class Program {
         if (this.inputIsTTY && this.input.setRawMode) this.input.setRawMode(true)
       } catch {}
       this._decoder = new KeyDecoder()
+      this._parser = this._newParser()
       this._decoder.on('data', this._onKey)
       this.input.on('data', this._onInput)
       try {
         this.input.resume?.()
       } catch {}
     }
-    if (this._mouseMode) this.output.write(mouse.enable(this._mouseMode))
+    this._enableModes()
     this.renderer.clear() // next render repaints everything
     this._suspended = false
   }