bare-tui 0.0.0 → 0.0.2

package/components/help.js

@@ -0,0 +1,117 @@
+// help — renders keybinding hints from key.binding({ keys, help }) objects.
+//
+// Unlike the other components this one is a *view helper*, not a loop model:
+// its view(keymap) takes the bindings to show (mirroring bubbles/help, where
+// help.View(keymap) is called from the parent's View). Bindings without a
+// `help` entry are skipped, so internal keys stay hidden.
+//
+//   const h = help.create()
+//   h.view([keys.up, keys.down, keys.quit])      // short: one line
+//   h.showAll = true
+//   h.view([[keys.up, keys.down], [keys.quit]])  // full: aligned columns
+//
+// A keymap can be an array of bindings, an object of bindings (values are
+// used), or an object exposing shortHelp()/fullHelp() for full control.
+const { style, width, truncate } = require('../style')
+
+const defaultStyles = {
+  key: (s) => s,
+  desc: (s) => style().faint(true).render(s),
+  sep: (s) => style().faint(true).render(s)
+}
+
+function toBindings(x) {
+  if (!x) return []
+  return Array.isArray(x) ? x : Object.values(x)
+}
+
+// Resolve a keymap into the binding list (short) or list-of-columns (full).
+function resolve(keymap, showAll) {
+  if (Array.isArray(keymap)) {
+    if (!showAll) return keymap
+    // Full mode: an array of arrays is already columns; a flat list is one.
+    return keymap.length && Array.isArray(keymap[0]) ? keymap : [keymap]
+  }
+
+  if (showAll) {
+    if (typeof keymap.fullHelp === 'function') return keymap.fullHelp()
+    if (keymap.full) return keymap.full
+    const short =
+      typeof keymap.shortHelp === 'function'
+        ? keymap.shortHelp()
+        : keymap.short || toBindings(keymap)
+    return [short]
+  }
+
+  if (typeof keymap.shortHelp === 'function') return keymap.shortHelp()
+  if (keymap.short) return keymap.short
+  return toBindings(keymap)
+}
+
+function helpful(binding) {
+  return binding && binding.help && binding.help.key
+}
+
+class Help {
+  constructor(opts = {}) {
+    this.width = opts.width || 0 // 0 = no truncation
+    this.showAll = !!opts.showAll
+    this.separator = opts.separator || ' • '
+    this.styles = { ...defaultStyles, ...(opts.styles || {}) }
+  }
+
+  setWidth(n) {
+    this.width = n
+    return this
+  }
+
+  view(keymap) {
+    if (this.showAll) {
+      const columns = resolve(keymap, true)
+        .map((group) => this._column(group))
+        .filter((c) => c.length)
+      if (!columns.length) return ''
+
+      const blocks = []
+      columns.forEach((c, i) => {
+        if (i) blocks.push('   ') // gutter between columns
+        blocks.push(c)
+      })
+      return style.joinHorizontal(style.position.top, ...blocks)
+    }
+
+    return this._short(resolve(keymap, false))
+  }
+
+  _short(bindings) {
+    const items = bindings.filter(helpful)
+    if (!items.length) return ''
+
+    const sep = this.styles.sep(this.separator)
+    let line = items
+      .map((b) => this.styles.key(b.help.key) + ' ' + this.styles.desc(b.help.desc))
+      .join(sep)
+
+    if (this.width > 0 && width(line) > this.width) line = truncate(line, this.width)
+    return line
+  }
+
+  _column(bindings) {
+    const items = bindings.filter(helpful)
+    if (!items.length) return ''
+
+    const keyW = Math.max(...items.map((b) => width(b.help.key)))
+    return items
+      .map((b) => {
+        const gap = ' '.repeat(keyW - width(b.help.key) + 2)
+        return this.styles.key(b.help.key) + gap + this.styles.desc(b.help.desc)
+      })
+      .join('\n')
+  }
+}
+
+function create(opts) {
+  return new Help(opts)
+}
+
+module.exports = { create, Help }

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/radio.js

@@ -0,0 +1,113 @@
+// radio — single choice from a fixed set of options.
+//
+// A tiny vertical list where the cursor *is* the value: up/down (or k/j) move
+// the selection directly, so there is no separate "highlight vs commit" step.
+// Like the other field controls it only reacts when focused and never consumes
+// enter, leaving enter free for a parent's submit.
+//
+//   const size = radio.create({
+//     options: ['small', 'medium', 'large'],
+//     selected: 1
+//   }).focus()
+//   // in update: const [r] = size.update(msg); this.size = r
+//   // in view:   size.view()
+//   size.value()   // 'medium'
+//
+// Options may be strings or { label, value } objects; value() returns the
+// underlying value (the label when none is given). The chosen option always
+// shows a filled bullet so the value is visible even when blurred; a leading
+// '›' marks the focused row.
+const key = require('../key')
+
+const keys = {
+  up: key.binding({ keys: ['up', 'k'], help: { key: '↑/k', desc: 'up' } }),
+  down: key.binding({ keys: ['down', 'j'], help: { key: '↓/j', desc: 'down' } })
+}
+
+// Normalise an option to { label, value }. Bare values become their own label.
+function normalize(opt) {
+  if (opt !== null && typeof opt === 'object') {
+    const value = 'value' in opt ? opt.value : opt.label
+    return { label: String(opt.label ?? opt.value ?? ''), value }
+  }
+  return { label: String(opt), value: opt }
+}
+
+class Radio {
+  constructor(opts = {}) {
+    this.options = (opts.options || []).map(normalize)
+    this.selected = opts.selected || 0 // index into options
+    this.focused = !!opts.focused
+    this.onGlyph = opts.onGlyph || '(•)'
+    this.offGlyph = opts.offGlyph || '( )'
+    this._clamp()
+  }
+
+  focus() {
+    this.focused = true
+    return this
+  }
+
+  blur() {
+    this.focused = false
+    return this
+  }
+
+  // The chosen option's value, or null when there are no options.
+  value() {
+    const o = this.options[this.selected]
+    return o ? o.value : null
+  }
+
+  // The chosen { label, value }, or null.
+  selectedOption() {
+    return this.options[this.selected] || null
+  }
+
+  setOptions(options) {
+    this.options = (options || []).map(normalize)
+    this._clamp()
+    return this
+  }
+
+  // Select by value; no-op if the value isn't present.
+  setValue(v) {
+    const i = this.options.findIndex((o) => o.value === v)
+    if (i >= 0) this.selected = i
+    return this
+  }
+
+  update(msg) {
+    if (!this.focused || !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)
+    return [this, null]
+  }
+
+  _move(delta) {
+    if (!this.options.length) return
+    this.selected = Math.max(0, Math.min(this.selected + delta, this.options.length - 1))
+  }
+
+  _clamp() {
+    if (!this.options.length) this.selected = 0
+    else this.selected = Math.max(0, Math.min(this.selected, this.options.length - 1))
+  }
+
+  view() {
+    return this.options
+      .map((o, i) => {
+        const chosen = i === this.selected
+        const pointer = this.focused && chosen ? '› ' : '  '
+        const bullet = chosen ? this.onGlyph : this.offGlyph
+        return pointer + bullet + ' ' + o.label
+      })
+      .join('\n')
+  }
+}
+
+function create(opts) {
+  return new Radio(opts)
+}
+
+module.exports = { create, Radio, keys }