bare-tui 0.0.0 → 0.0.2

package/docs/textinput.md

@@ -0,0 +1,51 @@
+# textinput
+
+A single-line editable text field. Input-driven: no commands, just state folded
+from key messages. Only consumes keys while focused, so a parent can host several
+and route to whichever has focus.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { textinput } = require('bare-tui')
+
+class Form {
+  constructor() {
+    this.name = textinput.create({ placeholder: 'name', prompt: '> ' }).focus()
+  }
+  update(msg) {
+    const [f, cmd] = this.name.update(msg)
+    this.name = f
+    return [this, cmd]
+  }
+  view() {
+    return this.name.view()
+  }
+}
+```
+
+## Options
+
+| Option        | Default    | Description                                 |
+| ------------- | ---------- | ------------------------------------------- |
+| `value`       | `''`       | Initial text                                |
+| `placeholder` | `''`       | Dim text shown when empty                   |
+| `prompt`      | `''`       | Prefix drawn before the value (e.g. `'> '`) |
+| `charLimit`   | `0`        | Max length (`0` = unlimited)                |
+| `echoMode`    | `'normal'` | `'password'` masks the value                |
+| `maskChar`    | `'•'`      | Mask character in password mode             |
+| `focused`     | `false`    | Start focused                               |
+
+## API
+
+- `focus()` / `blur()` — toggle whether keys are consumed.
+- `setValue(v)` / `reset()` — set or clear the text.
+- `.value` — the current string.
+
+## Keys
+
+`←`/`→` move, `home`/`end` (and `ctrl+a`/`ctrl+e`) jump, `backspace`/`delete`
+edit, printable characters insert at the cursor. The field draws its own
+reverse-video cursor (the Program hides the real one).

package/docs/timer.md

@@ -0,0 +1,57 @@
+# timer
+
+Counts a duration down to zero. Command-driven like the
+[stopwatch](stopwatch.md); when it reaches zero it stops and emits a one-shot
+timeout message.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { timer } = require('bare-tui')
+
+class App {
+  constructor() {
+    this.timer = timer.create({ timeout: 10000 }) // 10s
+  }
+  init() {
+    return this.timer.start()
+  }
+  update(msg) {
+    if (msg.type === 'timer.timeout') {
+      /* done */ return [this, null]
+    }
+    if (msg.type === 'timer.tick') {
+      const [t, cmd] = this.timer.update(msg)
+      this.timer = t
+      return [this, cmd]
+    }
+    return [this, null]
+  }
+  view() {
+    return this.timer.view() // "00:09"
+  }
+}
+```
+
+## Options
+
+| Option     | Default | Description                      |
+| ---------- | ------- | -------------------------------- |
+| `timeout`  | `0`     | Initial duration in milliseconds |
+| `interval` | `1000`  | Milliseconds per tick            |
+
+## API
+
+- `start()` / `stop()` / `toggle()` — return a command (or `null`). Won't start
+  from zero.
+- `reset()` — restore the initial duration.
+- `.timeout` (ms remaining) / `.running` / `.timedOut`.
+- `view()` → `MM:SS`.
+
+## Messages
+
+Consumes `{ type: 'timer.tick', id, tag }`; on reaching zero its `update` returns
+a command that emits `{ type: 'timer.timeout', id }` — handle that to react to
+the timeout.

package/docs/viewport.md

@@ -0,0 +1,39 @@
+# viewport
+
+A scrollable window over content taller than the available space. Renders a
+fixed `height`-row window and always emits exactly that many lines (padding short
+content), so surrounding layout stays stable.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { viewport } = require('bare-tui')
+
+const vp = viewport.create({ width: 40, height: 10 })
+vp.setContent(longText)
+
+// in update: const [v] = vp.update(msg); this.vp = v
+// in view:   this.vp.view()
+```
+
+## Options
+
+| Option   | Default | Description                                        |
+| -------- | ------- | -------------------------------------------------- |
+| `width`  | `0`     | Truncate lines to this width (`0` = no truncation) |
+| `height` | `0`     | Visible rows                                       |
+
+## API
+
+- `setContent(string)` — set the scrollable text.
+- `scrollUp(n)` / `scrollDown(n)` / `gotoTop()` / `gotoBottom()` /
+  `setYOffset(n)`.
+- `.atTop` / `.atBottom` / `.scrollPercent` / `.maxOffset` / `.yOffset`.
+
+## Keys
+
+`↑`/`↓` (`k`/`j`) by line, `pgup`/`pgdn` (`b`/`f`) by page, `ctrl+u`/`ctrl+d`
+half-page, `home`/`end` to the ends. Bindings are exported as `viewport.keys`
+for the [help](help.md) component.

package/index.d.ts

@@ -0,0 +1 @@
+declare module '@holepunchto/bare-tui'

package/index.js

@@ -0,0 +1,71 @@
+// tea — a tiny Elm Architecture runtime for Bare terminals.
+//
+// Built on Bare's native primitives (bare-tty for raw IO + window size,
+// bare-ansi-escapes for key decoding and escape sequences), so it runs
+// anywhere Bare runs and pulls in no Node-only dependencies. The API is shaped
+// after Charm's Bubble Tea (Model/Cmd/Msg/Program) with the intent of growing
+// into a drop-out framework.
+//
+//   const { Program, quit } = require('./lib/tea')
+//
+//   class App {
+//     init() { return null }
+//     update(msg) {
+//       if (msg.type === 'key' && String(msg) === 'q') return [this, quit]
+//       return [this, null]
+//     }
+//     view() { return 'press q to quit' }
+//   }
+//
+//   new Program(new App()).run()
+const Program = require('./program')
+const commands = require('./commands')
+const messages = require('./messages')
+const key = require('./key')
+const ansi = require('./ansi')
+const { style } = require('./style')
+const spinner = require('./components/spinner')
+const textinput = require('./components/textinput')
+const autocomplete = require('./components/autocomplete')
+const textarea = require('./components/textarea')
+const viewport = require('./components/viewport')
+const list = require('./components/list')
+const table = require('./components/table')
+const help = require('./components/help')
+const progress = require('./components/progress')
+const paginator = require('./components/paginator')
+const stopwatch = require('./components/stopwatch')
+const timer = require('./components/timer')
+const filepicker = require('./components/filepicker')
+const checkbox = require('./components/checkbox')
+const radio = require('./components/radio')
+const select = require('./components/select')
+const focus = require('./components/focus')
+
+module.exports = {
+  Program,
+  ...commands, // quit, batch, sequence, tick, every, suspend
+  KeyMsg: messages.KeyMsg,
+  key, // key.matches(msg, ...chords | bindings), key.binding({ keys, help })
+  ansi,
+  style, // style().bold().border(style.borders.rounded).render(...) + style.joinHorizontal/Vertical
+
+  // Components — each a composable { init?, update, view } model.
+  spinner, // spinner.create({ frames, fps })
+  textinput, // textinput.create({ placeholder, prompt, charLimit, echoMode })
+  autocomplete, // autocomplete.create({ prompt, placeholder, suggestions, trigger }) — input + suggestion menu
+  textarea, // textarea.create({ width, height, placeholder, charLimit }) — multi-line
+  viewport, // viewport.create({ width, height }) — scrollable window
+  list, // list.create({ items, height, width, title }) — selectable + filterable
+  table, // table.create({ columns, rows, height }) — selectable scrolling rows
+  help, // help.create() — renders keybinding hints; view(keymap)
+  progress, // progress.create({ width, gradient }) — view(percent)
+  paginator, // paginator.create({ perPage, total, type }) — page state + indicator
+  stopwatch, // stopwatch.create({ interval }) — counts up; start/stop/toggle
+  timer, // timer.create({ timeout, interval }) — counts down; emits timer.timeout
+  filepicker, // filepicker.create({ fs, path, cwd }) — browse + pick; filepicker.mock(tree)
+  checkbox, // checkbox.create({ label, checked }) — boolean toggle (space)
+  radio, // radio.create({ options, selected }) — single choice; value()
+  select, // select.create({ options, placeholder }) — dropdown; view() + menuView()
+  focus // focus.create({ items }) — ordered focus ring across child components
+}

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.2",
+  "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"
+}