bare-tui 0.0.0 → 0.0.2

package/components/textarea.js

@@ -0,0 +1,279 @@
+// textarea — a multi-line editable field.
+//
+// The sibling of textinput: it holds logical lines and a (row, col) cursor,
+// soft-wraps each line to `width` for display, and scrolls a `height`-row
+// window. Editing splits/merges lines (enter/backspace); arrows move by
+// character horizontally and by *visual* row vertically (so up/down feel right
+// inside wrapped text). Like textinput it only consumes keys when focused and
+// draws its own reverse-video cursor.
+//
+//   const ta = textarea.create({ width: 60, height: 10, placeholder: '…' }).focus()
+const ansi = require('../ansi')
+
+const dim = (s) => ansi.modifierDim + s + ansi.modifierReset
+const reverse = (s) => ansi.modifierReverse + s + ansi.modifierNotReverse
+
+class TextArea {
+  constructor(opts = {}) {
+    this.width = Math.max(1, opts.width || 40)
+    this.height = Math.max(1, opts.height || 6)
+    this.placeholder = opts.placeholder || ''
+    this.charLimit = opts.charLimit || 0 // 0 = unlimited
+    this.focused = !!opts.focused
+
+    this.lines = String(opts.value || '').split('\n')
+    this.row = this.lines.length - 1
+    this.col = this.lines[this.row].length
+    this.yOffset = 0
+  }
+
+  get value() {
+    return this.lines.join('\n')
+  }
+
+  // Total character count including the newlines between lines.
+  get length() {
+    let n = this.lines.length - 1
+    for (const line of this.lines) n += line.length
+    return n
+  }
+
+  focus() {
+    this.focused = true
+    return this
+  }
+
+  blur() {
+    this.focused = false
+    return this
+  }
+
+  setValue(v) {
+    this.lines = String(v).split('\n')
+    if (this.lines.length === 0) this.lines = ['']
+    this.row = this.lines.length - 1
+    this.col = this.lines[this.row].length
+    this._clamp()
+    return this
+  }
+
+  setSize(width, height) {
+    if (width) this.width = Math.max(1, width)
+    if (height) this.height = Math.max(1, height)
+    return this
+  }
+
+  reset() {
+    this.lines = ['']
+    this.row = 0
+    this.col = 0
+    this.yOffset = 0
+    return this
+  }
+
+  update(msg) {
+    if (!this.focused || !msg || msg.type !== 'key') return [this, null]
+
+    if (msg.is('left', 'ctrl+b')) this._left()
+    else if (msg.is('right', 'ctrl+f')) this._right()
+    else if (msg.is('up')) this._vertical(-1)
+    else if (msg.is('down')) this._vertical(1)
+    else if (msg.is('home', 'ctrl+a')) this._home()
+    else if (msg.is('end', 'ctrl+e')) this._end()
+    else if (msg.is('enter')) this._newline()
+    else if (msg.is('backspace')) this._backspace()
+    else if (msg.is('delete')) this._delete()
+    else this._insert(msg)
+
+    return [this, null]
+  }
+
+  // ── editing ────────────────────────────────────────────────────────────
+
+  _line() {
+    return this.lines[this.row]
+  }
+
+  _left() {
+    if (this.col > 0) this.col--
+    else if (this.row > 0) {
+      this.row--
+      this.col = this._line().length
+    }
+  }
+
+  _right() {
+    if (this.col < this._line().length) this.col++
+    else if (this.row < this.lines.length - 1) {
+      this.row++
+      this.col = 0
+    }
+  }
+
+  _home() {
+    const { vrow, rows } = this._cursor()
+    this.col = rows[vrow].start
+  }
+
+  _end() {
+    const { vrow, rows } = this._cursor()
+    this.col = rows[vrow].start + rows[vrow].text.length
+  }
+
+  _newline() {
+    if (this.charLimit && this.length >= this.charLimit) return
+    const line = this._line()
+    this.lines.splice(this.row, 1, line.slice(0, this.col), line.slice(this.col))
+    this.row++
+    this.col = 0
+  }
+
+  _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--
+    } else if (this.row > 0) {
+      const prev = this.lines[this.row - 1]
+      this.col = prev.length
+      this.lines[this.row - 1] = prev + line
+      this.lines.splice(this.row, 1)
+      this.row--
+    }
+  }
+
+  _delete() {
+    const line = this._line()
+    if (this.col < line.length) {
+      this.lines[this.row] = line.slice(0, this.col) + line.slice(this.col + 1)
+    } 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)
+    }
+  }
+
+  _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.length >= this.charLimit) return
+
+    const line = this._line()
+    this.lines[this.row] = line.slice(0, this.col) + ch + line.slice(this.col)
+    this.col++
+  }
+
+  _vertical(delta) {
+    const { vrow, vcol, rows } = this._cursor()
+    const target = Math.max(0, Math.min(vrow + delta, rows.length - 1))
+    if (target === vrow) return
+    const r = rows[target]
+    this.row = r.line
+    this.col = r.start + Math.min(vcol, r.text.length)
+  }
+
+  _clamp() {
+    this.row = Math.max(0, Math.min(this.row, this.lines.length - 1))
+    this.col = Math.max(0, Math.min(this.col, this._line().length))
+  }
+
+  // ── wrapping / cursor mapping ────────────────────────────────────────────
+
+  // Visual rows: each logical line char-wrapped to width. A line whose length
+  // is an exact multiple of width gets a trailing empty row so the cursor has
+  // somewhere to sit at the wrap boundary.
+  _visualRows() {
+    const w = this.width
+    const rows = []
+    for (let l = 0; l < this.lines.length; l++) {
+      const line = this.lines[l]
+      if (line.length === 0) {
+        rows.push({ line: l, start: 0, text: '' })
+        continue
+      }
+      for (let s = 0; s < line.length; s += w) {
+        rows.push({ line: l, start: s, text: line.slice(s, s + w) })
+      }
+      if (line.length % w === 0) rows.push({ line: l, start: line.length, text: '' })
+    }
+    return rows
+  }
+
+  // Locate the cursor among the visual rows.
+  _cursor() {
+    const rows = this._visualRows()
+    let last = 0
+    for (let i = 0; i < rows.length; i++) {
+      const r = rows[i]
+      if (r.line !== this.row) continue
+      last = i
+      if (this.col >= r.start && this.col < r.start + r.text.length) {
+        return { vrow: i, vcol: this.col - r.start, rows }
+      }
+      if (r.text.length === 0 && this.col === r.start) {
+        return { vrow: i, vcol: 0, rows }
+      }
+    }
+    const r = rows[last]
+    return { vrow: last, vcol: this.col - r.start, rows }
+  }
+
+  // ── rendering ────────────────────────────────────────────────────────────
+
+  view() {
+    const empty = this.lines.length === 1 && this.lines[0] === ''
+    const { vrow, vcol, rows } = this._cursor()
+
+    // Scroll the window to keep the cursor visible.
+    if (vrow < this.yOffset) this.yOffset = vrow
+    else if (vrow >= this.yOffset + this.height) this.yOffset = vrow - this.height + 1
+    const maxOffset = Math.max(0, rows.length - this.height)
+    this.yOffset = Math.max(0, Math.min(this.yOffset, maxOffset))
+
+    const out = []
+    for (let i = 0; i < this.height; i++) {
+      const idx = this.yOffset + i
+      if (empty && idx === 0) {
+        out.push(this._placeholderRow())
+      } else if (!rows[idx]) {
+        out.push(' '.repeat(this.width))
+      } else {
+        const onCursor = this.focused && idx === vrow
+        out.push(this._renderRow(rows[idx].text, onCursor ? vcol : -1))
+      }
+    }
+    return out.join('\n')
+  }
+
+  _renderRow(text, cursorCol) {
+    if (cursorCol < 0) return text.padEnd(this.width)
+    const at = text[cursorCol] ?? ' '
+    const line = text.slice(0, cursorCol) + reverse(at) + text.slice(cursorCol + 1)
+    const visible = Math.max(text.length, cursorCol + 1)
+    return line + ' '.repeat(Math.max(0, this.width - visible))
+  }
+
+  _placeholderRow() {
+    const ph = this.placeholder
+    if (!this.focused) return this._pad(dim(ph), ph.length)
+    const head = ph.slice(0, 1) || ' '
+    const body = reverse(head) + dim(ph.slice(1))
+    return this._pad(body, Math.max(ph.length, 1))
+  }
+
+  _pad(styled, visibleLen) {
+    return styled + ' '.repeat(Math.max(0, this.width - visibleLen))
+  }
+}
+
+function create(opts) {
+  return new TextArea(opts)
+}
+
+module.exports = { create, TextArea }

package/components/textinput.js

@@ -0,0 +1,135 @@
+// textinput — a single-line editable field.
+//
+// This is the reference for an *input-driven* component: no Cmds, just state
+// folded from key Msgs. It only reacts when focused, so a parent can host
+// several and route keys to whichever has focus:
+//
+//   class Form {
+//     constructor () {
+//       this.name = textinput.create({ placeholder: 'name' }).focus()
+//     }
+//     update (msg) {
+//       const [f, cmd] = this.name.update(msg)
+//       this.name = f
+//       return [this, cmd]
+//     }
+//     view () { return this.name.view() }
+//   }
+//
+// Because the Program hides the real terminal cursor, the field draws its own
+// as a reverse-video cell.
+const ansi = require('../ansi')
+
+const dim = (s) => ansi.modifierDim + s + ansi.modifierReset
+const reverse = (s) => ansi.modifierReverse + s + ansi.modifierNotReverse
+
+class TextInput {
+  constructor(opts = {}) {
+    this.value = opts.value || ''
+    this.placeholder = opts.placeholder || ''
+    this.prompt = opts.prompt || ''
+    this.charLimit = opts.charLimit || 0 // 0 = unlimited
+    this.echoMode = opts.echoMode || 'normal' // 'normal' | 'password'
+    this.maskChar = opts.maskChar || '•'
+    this.focused = !!opts.focused
+    this.cursor = this.value.length // insertion point, 0..value.length
+  }
+
+  focus() {
+    this.focused = true
+    return this
+  }
+
+  blur() {
+    this.focused = false
+    return this
+  }
+
+  setValue(v) {
+    v = String(v)
+    this.value = this.charLimit ? v.slice(0, this.charLimit) : v
+    this.cursor = Math.min(this.cursor, this.value.length)
+    return this
+  }
+
+  reset() {
+    this.value = ''
+    this.cursor = 0
+    return this
+  }
+
+  update(msg) {
+    // Only a focused field consumes keys; everything else is a no-op so the
+    // parent can broadcast Msgs freely.
+    if (!this.focused || !msg || msg.type !== 'key') return [this, null]
+
+    if (msg.is('left', 'ctrl+b')) {
+      this.cursor = Math.max(0, this.cursor - 1)
+    } else if (msg.is('right', 'ctrl+f')) {
+      this.cursor = Math.min(this.value.length, this.cursor + 1)
+    } 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--
+      }
+    } 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)
+      }
+    } else {
+      this._insert(msg)
+    }
+
+    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(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
+
+    this.value = this.value.slice(0, this.cursor) + ch + this.value.slice(this.cursor)
+    this.cursor++
+  }
+
+  _display() {
+    if (this.echoMode === 'password') return this.maskChar.repeat(this.value.length)
+    return this.value
+  }
+
+  view() {
+    // Empty: dim placeholder, with the cursor over its first cell when focused.
+    if (this.value.length === 0) {
+      if (!this.focused) return this.prompt + dim(this.placeholder)
+      const head = this.placeholder.slice(0, 1) || ' '
+      return this.prompt + reverse(head) + dim(this.placeholder.slice(1))
+    }
+
+    const text = this._display()
+    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)
+  }
+}
+
+function create(opts) {
+  return new TextInput(opts)
+}
+
+module.exports = { create, TextInput }

package/components/timer.js

@@ -0,0 +1,91 @@
+// timer — counts a duration down to zero.
+//
+// Cmd-driven like the stopwatch. Each accepted 'timer.tick' decrements
+// `timeout`; when it hits zero the timer stops and emits a one-shot
+// { type: 'timer.timeout', id } Msg so the app can react.
+//
+//   this.timer = timer.create({ timeout: 10000 })   // 10s
+//   init()   { return this.timer.start() }
+//   update(msg) {
+//     if (msg.type === 'timer.timeout') { ...done... }
+//     const [t, cmd] = this.timer.update(msg); this.timer = t; return [this, cmd]
+//   }
+//   view()   { return this.timer.view() }   // "00:09"
+const { tick } = require('../commands')
+const { format } = require('./stopwatch')
+
+let nextId = 1
+
+class Timer {
+  constructor(opts = {}) {
+    this.interval = opts.interval || 1000
+    this.timeout = opts.timeout ?? 0 // ms remaining
+    this.initial = this.timeout
+    this.running = false
+    this.id = nextId++
+    this.tag = 0
+  }
+
+  get timedOut() {
+    return this.timeout <= 0
+  }
+
+  _tick() {
+    const id = this.id
+    const tag = this.tag
+    return tick(this.interval, () => ({ type: 'timer.tick', id, tag }))
+  }
+
+  start() {
+    if (this.running || this.timeout <= 0) return null
+    this.running = true
+    return this._tick()
+  }
+
+  stop() {
+    this.running = false
+    this.tag++
+    return null
+  }
+
+  toggle() {
+    return this.running ? this.stop() : this.start()
+  }
+
+  reset() {
+    this.timeout = this.initial
+    return null // a running timer keeps counting, now from the initial duration
+  }
+
+  update(msg) {
+    if (
+      !msg ||
+      msg.type !== 'timer.tick' ||
+      msg.id !== this.id ||
+      msg.tag !== this.tag ||
+      !this.running
+    ) {
+      return [this, null]
+    }
+
+    this.timeout = Math.max(0, this.timeout - this.interval)
+    this.tag++
+
+    if (this.timeout === 0) {
+      this.running = false
+      const id = this.id
+      return [this, () => ({ type: 'timer.timeout', id })]
+    }
+    return [this, this._tick()]
+  }
+
+  view() {
+    return format(this.timeout)
+  }
+}
+
+function create(opts) {
+  return new Timer(opts)
+}
+
+module.exports = { create, Timer }

package/components/viewport.js

@@ -0,0 +1,104 @@
+// viewport — a scrollable window over content taller than the available space.
+//
+// Holds its content as lines and renders a fixed `height`-row window starting
+// at `yOffset`. It always emits exactly `height` lines (padding short content),
+// which keeps the surrounding layout stable for the diff renderer. Long lines
+// are truncated to `width`.
+//
+// Useful on its own (a pager, a scrollable log/help panel) and as the scrolling
+// concept the list component mirrors.
+const key = require('../key')
+
+// Scroll keymap, expressed as reusable bindings.
+const keys = {
+  up: key.binding({ keys: ['up', 'k'], help: { key: '↑/k', desc: 'up' } }),
+  down: key.binding({ keys: ['down', 'j'], help: { key: '↓/j', desc: 'down' } }),
+  pageUp: key.binding({ keys: ['pageup', 'b'], help: { key: 'pgup', desc: 'page up' } }),
+  pageDown: key.binding({ keys: ['pagedown', 'f'], help: { key: 'pgdn', desc: 'page down' } }),
+  halfUp: key.binding({ keys: ['ctrl+u'] }),
+  halfDown: key.binding({ keys: ['ctrl+d'] }),
+  top: key.binding({ keys: ['home'], help: { key: 'home', desc: 'top' } }),
+  bottom: key.binding({ keys: ['end'], help: { key: 'end', desc: 'bottom' } })
+}
+
+class Viewport {
+  constructor(opts = {}) {
+    this.width = opts.width || 0 // 0 = no horizontal truncation
+    this.height = opts.height || 0
+    this.yOffset = 0
+    this.lines = []
+  }
+
+  setContent(content) {
+    this.lines = String(content).split('\n')
+    this._clamp()
+    return this
+  }
+
+  get maxOffset() {
+    return Math.max(0, this.lines.length - this.height)
+  }
+  get atTop() {
+    return this.yOffset <= 0
+  }
+  get atBottom() {
+    return this.yOffset >= this.maxOffset
+  }
+  get scrollPercent() {
+    if (this.lines.length <= this.height) return 1
+    return this.yOffset / this.maxOffset
+  }
+
+  setYOffset(n) {
+    this.yOffset = n
+    this._clamp()
+    return this
+  }
+  scrollUp(n = 1) {
+    return this.setYOffset(this.yOffset - n)
+  }
+  scrollDown(n = 1) {
+    return this.setYOffset(this.yOffset + n)
+  }
+  gotoTop() {
+    return this.setYOffset(0)
+  }
+  gotoBottom() {
+    return this.setYOffset(this.maxOffset)
+  }
+
+  _clamp() {
+    this.yOffset = Math.max(0, Math.min(this.yOffset, this.maxOffset))
+  }
+
+  update(msg) {
+    if (!msg || msg.type !== 'key') return [this, null]
+    const h = this.height || 1
+
+    if (key.matches(msg, keys.up)) this.scrollUp(1)
+    else if (key.matches(msg, keys.down)) this.scrollDown(1)
+    else if (key.matches(msg, keys.pageUp)) this.scrollUp(h)
+    else if (key.matches(msg, keys.pageDown)) this.scrollDown(h)
+    else if (key.matches(msg, keys.halfUp)) this.scrollUp(Math.ceil(h / 2))
+    else if (key.matches(msg, keys.halfDown)) this.scrollDown(Math.ceil(h / 2))
+    else if (key.matches(msg, keys.top)) this.gotoTop()
+    else if (key.matches(msg, keys.bottom)) this.gotoBottom()
+
+    return [this, null]
+  }
+
+  view() {
+    const out = []
+    for (let i = 0; i < this.height; i++) {
+      const line = this.lines[this.yOffset + i] ?? ''
+      out.push(this.width > 0 ? line.slice(0, this.width) : line)
+    }
+    return out.join('\n')
+  }
+}
+
+function create(opts) {
+  return new Viewport(opts)
+}
+
+module.exports = { create, Viewport, keys }

package/docs/autocomplete.md

@@ -0,0 +1,80 @@
+# autocomplete
+
+A single-line input with a filtered suggestion menu — a slash-command palette.
+Input-driven (no commands), built as a composition over
+[textinput](textinput.md): keys fold into an embedded field, and a dropdown
+offers the suggestions that match what's been typed. The menu opens only once
+the line begins with a **trigger** character (default `/`), so ordinary prose in
+the same field never pops a menu.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { autocomplete, key } = require('bare-tui')
+
+class Prompt {
+  constructor() {
+    this.input = autocomplete
+      .create({
+        prompt: '> ',
+        placeholder: 'message, or / for commands',
+        suggestions: [
+          { name: 'help', desc: 'show help' },
+          { name: 'clear', desc: 'clear the screen' },
+          { name: 'quit', desc: 'exit' }
+        ]
+      })
+      .focus()
+  }
+  update(msg) {
+    // Enter submits — the highlighted command when the menu is open (so it
+    // both completes and runs), otherwise the typed line. Tab just completes.
+    if (key.matches(msg, 'enter')) {
+      const s = this.input.open && this.input.selectedSuggestion()
+      this.submit(s ? '/' + s.name : this.input.value)
+      this.input.reset()
+      return [this, null]
+    }
+    const [f, cmd] = this.input.update(msg)
+    this.input = f
+    return [this, cmd]
+  }
+  view() {
+    // Render the menu wherever it fits — above a bottom-anchored prompt here.
+    return [this.input.menuView(), this.input.view()].filter(Boolean).join('\n')
+  }
+}
+```
+
+## Options
+
+| Option        | Default | Description                                            |
+| ------------- | ------- | ------------------------------------------------------ |
+| `value`       | `''`    | Initial text                                           |
+| `placeholder` | `''`    | Dim text shown when empty                              |
+| `prompt`      | `''`    | Prefix drawn before the value (e.g. `'> '`)            |
+| `suggestions` | `[]`    | `{ name, desc }` objects (or bare strings)             |
+| `trigger`     | `'/'`   | The menu opens only when the line starts with this     |
+| `maxVisible`  | `6`     | Rows shown before the menu scrolls and notes "…N more" |
+| `focused`     | `false` | Start focused                                          |
+
+## API
+
+- `focus()` / `blur()` — toggle whether keys are consumed.
+- `setValue(v)` / `reset()` — set or clear the text.
+- `setSuggestions(list)` — replace the suggestion set.
+- `accept()` — complete the line to the highlighted suggestion.
+- `.value` — the current string.
+- `.open` — whether the dropdown is currently showing.
+- `selectedSuggestion()` — the highlighted `{ name, desc }`, or `null`.
+- `matches()` — the suggestions matching the current text.
+- `view()` — the input line. `menuView()` — the dropdown (or `''` when closed).
+
+## Keys
+
+While the menu is open: `↑`/`↓` (or `ctrl+p`/`ctrl+n`) move the highlight, `tab`
+accepts it (completing the line), `esc` dismisses it until the text changes.
+Every other key edits the field — see [textinput](textinput.md). The component
+never consumes `enter`, leaving "submit" entirely to the parent (see above).