bare-tui 0.0.0 → 0.0.1

package/components/list.js

@@ -0,0 +1,172 @@
+// list — a selectable, filterable list.
+//
+// Selection + filtering live here; scrolling mirrors the viewport model — a
+// window [offset, offset+height) over the (possibly filtered) items, nudged to
+// keep the selection visible. Filtering is delegated to an embedded textinput,
+// so the list is itself a composition of components.
+//
+// Items may be strings or objects: `title` is shown, `filterValue` (falling
+// back to title) is matched. selectedItem() returns the underlying item.
+const key = require('../key')
+const ansi = require('../ansi')
+const textinput = require('./textinput')
+
+const reverse = (s) => ansi.modifierReverse + s + ansi.modifierNotReverse
+const dim = (s) => ansi.modifierDim + s + ansi.modifierReset
+
+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'] }),
+  pageDown: key.binding({ keys: ['pagedown'] }),
+  filter: key.binding({ keys: ['/'], help: { key: '/', desc: 'filter' } }),
+  accept: key.binding({ keys: ['enter'] }),
+  cancel: key.binding({ keys: ['esc'], help: { key: 'esc', desc: 'clear filter' } })
+}
+
+function filterValue(item) {
+  if (item === undefined || item === null) return ''
+  if (typeof item === 'string') return item
+  return item.filterValue || item.title || String(item)
+}
+
+function titleOf(item) {
+  if (item === undefined || item === null) return ''
+  if (typeof item === 'string') return item
+  return item.title ?? String(item)
+}
+
+class List {
+  constructor(opts = {}) {
+    this.items = opts.items ? opts.items.slice() : []
+    this.height = opts.height || 10 // visible rows
+    this.width = opts.width || 0
+    this.title = opts.title || ''
+    this.filterable = opts.filterable !== false
+
+    this.input = textinput.create({ prompt: '' }) // filter query editor
+    this.filter = ''
+    this.filtering = false
+
+    this.selected = 0 // position within `filtered`
+    this.offset = 0 // top of the visible window
+    this.filtered = this.items.map((_, i) => i) // original indices that match
+  }
+
+  get visibleCount() {
+    return this.filtered.length
+  }
+
+  selectedItem() {
+    if (!this.filtered.length) return null
+    return this.items[this.filtered[this.selected]]
+  }
+
+  setItems(items) {
+    this.items = items.slice()
+    this._applyFilter()
+    return this
+  }
+
+  update(msg) {
+    if (!msg || msg.type !== 'key') return [this, null]
+
+    // While filtering, keys edit the query; esc cancels, enter accepts.
+    if (this.filtering) {
+      if (key.matches(msg, keys.cancel)) {
+        this.filtering = false
+        this.filter = ''
+        this.input.reset().blur()
+        this._applyFilter()
+        return [this, null]
+      }
+      if (key.matches(msg, keys.accept)) {
+        this.filtering = false
+        this.input.blur()
+        return [this, null]
+      }
+      const [input, cmd] = this.input.update(msg)
+      this.input = input
+      this.filter = this.input.value
+      this._applyFilter()
+      return [this, cmd]
+    }
+
+    if (this.filterable && key.matches(msg, keys.filter)) {
+      this.filtering = true
+      this.input.focus()
+      return [this, null]
+    }
+    if (key.matches(msg, keys.cancel) && this.filter) {
+      this.filter = ''
+      this.input.reset()
+      this._applyFilter()
+      return [this, null]
+    }
+
+    if (key.matches(msg, keys.up)) this._move(-1)
+    else if (key.matches(msg, keys.down)) this._move(1)
+    else if (key.matches(msg, keys.pageUp)) this._move(-this.height)
+    else if (key.matches(msg, keys.pageDown)) this._move(this.height)
+
+    return [this, null]
+  }
+
+  _applyFilter() {
+    const q = this.filter.trim().toLowerCase()
+    const all = this.items.map((_, i) => i)
+    this.filtered = q
+      ? all.filter((i) => filterValue(this.items[i]).toLowerCase().includes(q))
+      : all
+    // Filtering changes what's under the cursor, so reset to the first match.
+    this.selected = 0
+    this.offset = 0
+  }
+
+  _move(delta) {
+    if (!this.filtered.length) return
+    const last = this.filtered.length - 1
+    this.selected = Math.max(0, Math.min(this.selected + delta, last))
+    if (this.selected < this.offset) this.offset = this.selected
+    else if (this.selected >= this.offset + this.height) {
+      this.offset = this.selected - this.height + 1
+    }
+  }
+
+  view() {
+    const lines = []
+    if (this.title) lines.push(this.title)
+    if (this.filtering || this.filter) {
+      lines.push('/' + (this.filtering ? this.input.view() : this.filter))
+    }
+
+    const rows = []
+    if (!this.filtered.length) {
+      rows.push(dim('  no matches'))
+    } else {
+      const end = Math.min(this.offset + this.height, this.filtered.length)
+      for (let p = this.offset; p < end; p++) {
+        const item = this.items[this.filtered[p]]
+        rows.push(this._renderRow(titleOf(item), p === this.selected))
+      }
+    }
+    while (rows.length < this.height) rows.push('') // stable height
+    lines.push(...rows)
+
+    const pos = this.filtered.length ? this.selected + 1 : 0
+    lines.push(dim(`  ${pos}/${this.filtered.length}`))
+    return lines.join('\n')
+  }
+
+  _renderRow(label, selected) {
+    let line = (selected ? '› ' : '  ') + label
+    if (this.width > 0) line = line.slice(0, this.width).padEnd(this.width)
+    return selected ? reverse(line) : line
+  }
+}
+
+function create(opts) {
+  return new List(opts)
+}
+
+module.exports = { create, List, keys }

package/components/paginator.js

@@ -0,0 +1,111 @@
+// paginator — page state plus an indicator, for paging through a long list.
+//
+// Holds the current page and page size, handles the paging keys, and offers
+// sliceBounds() so a parent can carve the visible page out of its items:
+//
+//   const p = paginator.create({ perPage: 10, total: items.length, type: 'dots' })
+//   const [start, end] = p.sliceBounds()
+//   render(items.slice(start, end))
+//   p.view()   // "●○○○○"  (dots)  or  "1/5"  (arabic)
+const key = require('../key')
+const { style } = require('../style')
+
+const dim = (s) => style().faint(true).render(s)
+
+const keys = {
+  prev: key.binding({
+    keys: ['left', 'h', 'pageup'],
+    help: { key: '←/h', desc: 'prev page' }
+  }),
+  next: key.binding({
+    keys: ['right', 'l', 'pagedown'],
+    help: { key: '→/l', desc: 'next page' }
+  })
+}
+
+class Paginator {
+  constructor(opts = {}) {
+    this.perPage = opts.perPage || 10
+    this.total = opts.total || 0 // number of items
+    this.page = opts.page || 0 // zero-indexed
+    this.type = opts.type || 'arabic' // 'arabic' | 'dots'
+    this.activeDot = opts.activeDot || '●'
+    this.inactiveDot = opts.inactiveDot || '○'
+    this._clamp()
+  }
+
+  get totalPages() {
+    return Math.max(1, Math.ceil(this.total / this.perPage))
+  }
+
+  onFirstPage() {
+    return this.page <= 0
+  }
+
+  onLastPage() {
+    return this.page >= this.totalPages - 1
+  }
+
+  setTotal(n) {
+    this.total = n
+    this._clamp()
+    return this
+  }
+
+  setPage(n) {
+    this.page = n
+    this._clamp()
+    return this
+  }
+
+  nextPage() {
+    if (!this.onLastPage()) this.page++
+    return this
+  }
+
+  prevPage() {
+    if (!this.onFirstPage()) this.page--
+    return this
+  }
+
+  _clamp() {
+    this.page = Math.max(0, Math.min(this.page, this.totalPages - 1))
+  }
+
+  // Items on the current page (last page may be short).
+  itemsOnPage(length = this.total) {
+    const [start, end] = this.sliceBounds(length)
+    return Math.max(0, end - start)
+  }
+
+  // [start, end) into a collection of `length` items for the current page.
+  sliceBounds(length = this.total) {
+    const start = Math.min(this.page * this.perPage, length)
+    const end = Math.min(start + this.perPage, length)
+    return [start, end]
+  }
+
+  update(msg) {
+    if (!msg || msg.type !== 'key') return [this, null]
+    if (key.matches(msg, keys.next)) this.nextPage()
+    else if (key.matches(msg, keys.prev)) this.prevPage()
+    return [this, null]
+  }
+
+  view() {
+    if (this.type === 'dots') {
+      let out = ''
+      for (let i = 0; i < this.totalPages; i++) {
+        out += i === this.page ? this.activeDot : dim(this.inactiveDot)
+      }
+      return out
+    }
+    return `${this.page + 1}/${this.totalPages}`
+  }
+}
+
+function create(opts) {
+  return new Paginator(opts)
+}
+
+module.exports = { create, Paginator, keys }

package/components/progress.js

@@ -0,0 +1,78 @@
+// progress — a percentage bar.
+//
+// Static like the help component: it holds the look (width, fill chars, color)
+// and view(percent) renders a bar at the given fraction (0..1). Drive the
+// percent from your model (a tick Cmd, a download callback, the OTA updater).
+//
+//   const bar = progress.create({ width: 40, gradient: ['#5A56E0', '#EE6FF8'] })
+//   bar.view(0.42)   // -> "████████░░░░…  42%"
+const { style } = require('../style')
+
+const dim = (s) => style().faint(true).render(s)
+
+class Progress {
+  constructor(opts = {}) {
+    this.width = opts.width || 40
+    this.full = opts.full || '█'
+    this.empty = opts.empty || '░'
+    this.showPercentage = opts.showPercentage !== false
+    this.color = opts.color || null // solid fill color (any style color spec)
+    this.gradient = opts.gradient || null // [fromHex, toHex] across the fill
+  }
+
+  setWidth(n) {
+    this.width = n
+    return this
+  }
+
+  view(percent) {
+    percent = Math.max(0, Math.min(1, percent || 0))
+
+    // A fixed 5 cells (" 100%") are reserved for the label so the bar width is
+    // stable as the number changes.
+    const reserve = this.showPercentage ? 5 : 0
+    const w = Math.max(1, this.width - reserve)
+    const filled = Math.round(w * percent)
+    const gap = w - filled
+
+    let bar
+    if (this.gradient) {
+      let head = ''
+      for (let i = 0; i < filled; i++) {
+        const t = filled <= 1 ? 0 : i / (filled - 1)
+        const color = lerpHex(this.gradient[0], this.gradient[1], t)
+        head += style().foreground(color).render(this.full)
+      }
+      bar = head + dim(this.empty.repeat(gap))
+    } else {
+      const head = this.color
+        ? style().foreground(this.color).render(this.full.repeat(filled))
+        : this.full.repeat(filled)
+      bar = head + dim(this.empty.repeat(gap))
+    }
+
+    if (!this.showPercentage) return bar
+    const pct = Math.round(percent * 100)
+    return bar + ' ' + (pct + '%').padStart(4)
+  }
+}
+
+function hexToRgb(hex) {
+  let h = hex.replace('#', '')
+  if (h.length === 3) h = h.replace(/./g, (c) => c + c)
+  const n = parseInt(h, 16)
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+}
+
+function lerpHex(a, b, t) {
+  const A = hexToRgb(a)
+  const B = hexToRgb(b)
+  const mix = A.map((v, i) => Math.round(v + (B[i] - v) * t))
+  return '#' + mix.map((v) => v.toString(16).padStart(2, '0')).join('')
+}
+
+function create(opts) {
+  return new Progress(opts)
+}
+
+module.exports = { create, Progress }

package/components/spinner.js

@@ -0,0 +1,70 @@
+// spinner — a Cmd-driven animated spinner.
+//
+// This is the reference for a *command-driven* component. It animates by
+// re-issuing a tick Cmd each frame; the parent model just routes 'spinner.tick'
+// Msgs into update() and threads the returned Cmd up to the Program:
+//
+//   class App {
+//     constructor () { this.spinner = spinner.create() }
+//     init () { return this.spinner.init() }
+//     update (msg) {
+//       const [s, cmd] = this.spinner.update(msg)
+//       this.spinner = s
+//       return [this, cmd]
+//     }
+//     view () { return this.spinner.view() + ' loading…' }
+//   }
+//
+// Each spinner has a unique id and a monotonic tag so that strays — a second
+// spinner's ticks, or a duplicated/late tick — can't double-drive the loop.
+const { tick } = require('../commands')
+
+// A few frame sets. `dots` is the default.
+const dots = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+const line = ['|', '/', '-', '\\']
+const points = ['∙∙∙', '●∙∙', '∙●∙', '∙∙●']
+
+let nextId = 1
+
+class Spinner {
+  constructor(opts = {}) {
+    this.frames = opts.frames || dots
+    this.fps = opts.fps || 10
+    this.frame = 0
+    this.id = nextId++ // distinguishes this spinner's ticks from any other's
+    this.tag = 0 // bumped each accepted tick; stale ticks are ignored
+  }
+
+  // Returns the Cmd that starts the animation. Call from the parent's init().
+  init() {
+    return this._tick()
+  }
+
+  _tick() {
+    const id = this.id
+    const tag = this.tag
+    const ms = Math.max(1, Math.round(1000 / this.fps))
+    return tick(ms, () => ({ type: 'spinner.tick', id, tag }))
+  }
+
+  update(msg) {
+    if (!msg || msg.type !== 'spinner.tick') return [this, null]
+    // Ignore another spinner's ticks and any tick that isn't the one we're
+    // currently waiting on (duplicates, late fires).
+    if (msg.id !== this.id || msg.tag !== this.tag) return [this, null]
+
+    this.frame = (this.frame + 1) % this.frames.length
+    this.tag++
+    return [this, this._tick()]
+  }
+
+  view() {
+    return this.frames[this.frame]
+  }
+}
+
+function create(opts) {
+  return new Spinner(opts)
+}
+
+module.exports = { create, Spinner, dots, line, points }

package/components/stopwatch.js

@@ -0,0 +1,88 @@
+// stopwatch — counts elapsed time upward.
+//
+// Cmd-driven like the spinner: start() returns a tick Cmd, and each accepted
+// 'stopwatch.tick' advances `elapsed` and re-issues the next tick. id + tag
+// guard against strays so pausing/resuming can't double-drive it.
+//
+//   this.sw = stopwatch.create()
+//   init()   { return this.sw.start() }
+//   update(msg) { const [sw, cmd] = this.sw.update(msg); this.sw = sw; return [this, cmd] }
+//   view()   { return this.sw.view() }   // "01:23"
+const { tick } = require('../commands')
+
+let nextId = 1
+
+function pad(n) {
+  return String(n).padStart(2, '0')
+}
+
+// ms → "M:SS" / "MM:SS" / "H:MM:SS"
+function format(ms) {
+  const total = Math.floor(ms / 1000)
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  const s = total % 60
+  return h > 0 ? `${h}:${pad(m)}:${pad(s)}` : `${pad(m)}:${pad(s)}`
+}
+
+class Stopwatch {
+  constructor(opts = {}) {
+    this.interval = opts.interval || 1000
+    this.elapsed = opts.elapsed || 0
+    this.running = false
+    this.id = nextId++
+    this.tag = 0
+  }
+
+  _tick() {
+    const id = this.id
+    const tag = this.tag
+    return tick(this.interval, () => ({ type: 'stopwatch.tick', id, tag }))
+  }
+
+  start() {
+    if (this.running) return null
+    this.running = true
+    return this._tick()
+  }
+
+  stop() {
+    this.running = false
+    this.tag++ // invalidate any in-flight tick
+    return null
+  }
+
+  toggle() {
+    return this.running ? this.stop() : this.start()
+  }
+
+  reset() {
+    this.elapsed = 0
+    return null // a running stopwatch keeps ticking
+  }
+
+  update(msg) {
+    if (
+      !msg ||
+      msg.type !== 'stopwatch.tick' ||
+      msg.id !== this.id ||
+      msg.tag !== this.tag ||
+      !this.running
+    ) {
+      return [this, null]
+    }
+    this.elapsed += this.interval
+    this.tag++
+    return [this, this._tick()]
+  }
+
+  view() {
+    return format(this.elapsed)
+  }
+}
+
+function create(opts) {
+  return new Stopwatch(opts)
+}
+
+module.exports = { create, Stopwatch, format }

package/components/table.js

@@ -0,0 +1,130 @@
+// table — fixed-width columns with selectable, scrolling rows.
+//
+//   const t = table.create({
+//     columns: [{ title: 'Name', width: 12 }, { title: 'Lang', width: 8 }],
+//     rows: [['corestore', 'js'], ['hypercore', 'js']],
+//     height: 8
+//   })
+//
+// Cells are truncated/padded to their column width (ANSI-aware), the selection
+// is a reverse-video bar, and the body scrolls in a `height`-row window. Like
+// list/viewport it always responds to its keys — the parent decides routing.
+const key = require('../key')
+const { style, width, truncate } = require('../style')
+
+const header = (s) => style().bold(true).render(s)
+const selected = (s) => style().reverse(true).render(s)
+const dim = (s) => style().faint(true).render(s)
+
+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'] }),
+  pageDown: key.binding({ keys: ['pagedown'] }),
+  top: key.binding({ keys: ['home'], help: { key: 'home', desc: 'top' } }),
+  bottom: key.binding({ keys: ['end'], help: { key: 'end', desc: 'bottom' } })
+}
+
+// Truncate/pad a value to exactly `w` visible cells.
+function cell(value, w) {
+  const text = String(value ?? '')
+  if (width(text) > w) return truncate(text, w)
+  return text + ' '.repeat(w - width(text))
+}
+
+class Table {
+  constructor(opts = {}) {
+    this.columns = opts.columns || []
+    this.rows = opts.rows || []
+    this.height = opts.height || 10 // visible body rows
+    this.rule = opts.rule || '─'
+    this.cursor = 0
+    this.offset = 0
+    this._clamp()
+  }
+
+  get totalWidth() {
+    if (!this.columns.length) return 0
+    const cols = this.columns.reduce((sum, c) => sum + c.width, 0)
+    return cols + (this.columns.length - 1) // single-space gutters
+  }
+
+  selectedRow() {
+    return this.rows[this.cursor] || null
+  }
+
+  setRows(rows) {
+    this.rows = rows
+    this._clamp()
+    return this
+  }
+
+  setColumns(columns) {
+    this.columns = columns
+    return this
+  }
+
+  gotoTop() {
+    this.cursor = 0
+    this.offset = 0
+    return this
+  }
+
+  gotoBottom() {
+    this.cursor = Math.max(0, this.rows.length - 1)
+    this.offset = Math.max(0, this.rows.length - this.height)
+    return this
+  }
+
+  _move(delta) {
+    if (!this.rows.length) return
+    this.cursor = Math.max(0, Math.min(this.cursor + delta, this.rows.length - 1))
+    if (this.cursor < this.offset) this.offset = this.cursor
+    else if (this.cursor >= this.offset + this.height) {
+      this.offset = this.cursor - this.height + 1
+    }
+  }
+
+  _clamp() {
+    this.cursor = Math.max(0, Math.min(this.cursor, Math.max(0, this.rows.length - 1)))
+    const maxOffset = Math.max(0, this.rows.length - this.height)
+    this.offset = Math.max(0, Math.min(this.offset, maxOffset))
+  }
+
+  update(msg) {
+    if (!msg || msg.type !== 'key') return [this, null]
+    if (key.matches(msg, keys.up)) this._move(-1)
+    else if (key.matches(msg, keys.down)) this._move(1)
+    else if (key.matches(msg, keys.pageUp)) this._move(-this.height)
+    else if (key.matches(msg, keys.pageDown)) this._move(this.height)
+    else if (key.matches(msg, keys.top)) this.gotoTop()
+    else if (key.matches(msg, keys.bottom)) this.gotoBottom()
+    return [this, null]
+  }
+
+  _row(cells) {
+    return this.columns.map((c, i) => cell(cells[i], c.width)).join(' ')
+  }
+
+  view() {
+    const lines = []
+    lines.push(header(this._row(this.columns.map((c) => c.title))))
+    lines.push(dim(this.rule.repeat(this.totalWidth)))
+
+    const end = Math.min(this.offset + this.height, this.rows.length)
+    const body = []
+    for (let i = this.offset; i < end; i++) {
+      const line = this._row(this.rows[i])
+      body.push(i === this.cursor ? selected(line) : line)
+    }
+    while (body.length < this.height) body.push(' '.repeat(this.totalWidth))
+
+    return lines.concat(body).join('\n')
+  }
+}
+
+function create(opts) {
+  return new Table(opts)
+}
+
+module.exports = { create, Table, keys }