bare-tui 0.0.0 → 0.0.1

package/components/autocomplete.js

@@ -0,0 +1,208 @@
+// autocomplete — a single-line input with a filtered suggestion menu.
+//
+// A composition over textinput (the same pattern list uses for its filter): it
+// folds keys into an embedded field, then offers a menu of suggestions that
+// match what's been typed. Typical use is a slash-command palette — the menu
+// opens only once the line begins with a trigger character (default '/'), so
+// ordinary prose typed into the same field never pops a menu.
+//
+//   const ac = autocomplete.create({
+//     prompt: '> ',
+//     placeholder: 'message, or / for commands',
+//     suggestions: [
+//       { name: 'help', desc: 'show help' },
+//       { name: 'clear', desc: 'clear the screen' }
+//     ]
+//   }).focus()
+//
+// The component never consumes enter — the parent decides what it means. A
+// common pattern is "enter submits the line, but the highlighted command when
+// the menu is open", which both completes and runs in one keystroke:
+//
+//   if (key.matches(msg, 'enter')) {
+//     const s = ac.open && ac.selectedSuggestion()
+//     return [this, submit(s ? '/' + s.name : ac.value)]
+//   }
+//   const [f, cmd] = ac.update(msg); this.input = f; return [this, cmd]
+//
+// While the menu is open ↑/↓ move the highlight, tab accepts it (completing the
+// line), and esc dismisses it; every other key edits the field. The view()
+// draws the input line only — call menuView() to render the dropdown wherever
+// it fits (above a bottom-anchored prompt, below a top one).
+const key = require('../key')
+const ansi = require('../ansi')
+const { style } = require('../style')
+const textinput = require('./textinput')
+
+const dim = (s) => ansi.modifierDim + s + ansi.modifierReset
+
+const keys = {
+  up: key.binding({ keys: ['up', 'ctrl+p'], help: { key: '↑', desc: 'prev' } }),
+  down: key.binding({ keys: ['down', 'ctrl+n'], help: { key: '↓', desc: 'next' } }),
+  accept: key.binding({ keys: ['tab'], help: { key: 'tab', desc: 'accept' } }),
+  dismiss: key.binding({ keys: ['esc'], help: { key: 'esc', desc: 'dismiss' } })
+}
+
+// Normalise a suggestion to { name, desc }. Bare strings become name-only.
+function normalize(s) {
+  if (typeof s === 'string') return { name: s, desc: '' }
+  return { name: String(s.name ?? ''), desc: String(s.desc ?? '') }
+}
+
+class Autocomplete {
+  constructor(opts = {}) {
+    this.trigger = opts.trigger ?? '/'
+    this.suggestions = (opts.suggestions || []).map(normalize)
+    this.maxVisible = opts.maxVisible || 6
+    this.width = opts.width || 0 // 0 = size the menu to its content
+
+    this.input = textinput.create({
+      value: opts.value || '',
+      placeholder: opts.placeholder || '',
+      prompt: opts.prompt || '',
+      focused: !!opts.focused
+    })
+
+    this.selected = 0 // highlight within the current matches
+    this.dismissed = false // esc / accept hides the menu until the value changes
+    this._lastValue = this.input.value
+  }
+
+  get value() {
+    return this.input.value
+  }
+  get focused() {
+    return this.input.focused
+  }
+
+  focus() {
+    this.input.focus()
+    return this
+  }
+  blur() {
+    this.input.blur()
+    return this
+  }
+
+  setValue(v) {
+    this.input.setValue(v)
+    this._lastValue = this.input.value
+    return this
+  }
+  reset() {
+    this.input.reset()
+    this.selected = 0
+    this.dismissed = false
+    this._lastValue = ''
+    return this
+  }
+  setSuggestions(list) {
+    this.suggestions = (list || []).map(normalize)
+    return this
+  }
+
+  // The suggestions matching the typed text, or [] when no menu is warranted.
+  // A menu is warranted once the line begins with the trigger; the text after
+  // it is a case-insensitive prefix filter over suggestion names.
+  matches() {
+    const v = this.input.value
+    if (!v.startsWith(this.trigger)) return []
+    const typed = v.slice(this.trigger.length).toLowerCase()
+    return this.suggestions.filter((s) => s.name.toLowerCase().startsWith(typed))
+  }
+
+  // Whether the dropdown is currently showing.
+  get open() {
+    return this.input.focused && !this.dismissed && this.matches().length > 0
+  }
+
+  // The highlighted suggestion, or null.
+  selectedSuggestion() {
+    const m = this.matches()
+    return m.length ? m[Math.min(this.selected, m.length - 1)] : null
+  }
+
+  // Complete the line to the highlighted suggestion and close the menu.
+  accept() {
+    const s = this.selectedSuggestion()
+    if (!s) return this
+    this.input.setValue(this.trigger + s.name + ' ')
+    this.input.cursor = this.input.value.length
+    this.dismissed = true
+    this._lastValue = this.input.value
+    return this
+  }
+
+  update(msg) {
+    if (!msg || msg.type !== 'key' || !this.input.focused) return [this, null]
+
+    // Menu navigation takes priority over field editing while it's open.
+    if (this.open) {
+      if (key.matches(msg, keys.up)) return [this._move(-1), null]
+      if (key.matches(msg, keys.down)) return [this._move(1), null]
+      if (key.matches(msg, keys.accept)) return [this.accept(), null]
+      if (key.matches(msg, keys.dismiss)) {
+        this.dismissed = true
+        return [this, null]
+      }
+    }
+
+    const [input, cmd] = this.input.update(msg)
+    this.input = input
+    // Any edit to the text re-opens the menu and re-clamps the highlight.
+    if (this.input.value !== this._lastValue) {
+      this.dismissed = false
+      this._lastValue = this.input.value
+      this.selected = 0
+    }
+    return [this, cmd]
+  }
+
+  _move(dir) {
+    const n = this.matches().length
+    if (n) this.selected = (this.selected + dir + n) % n
+    return this
+  }
+
+  view() {
+    return this.input.view()
+  }
+
+  // The dropdown, or '' when closed. Rows are `/name  desc`, the highlight in
+  // reverse video; a footer notes any matches scrolled out of view.
+  menuView() {
+    if (!this.open) return ''
+    const all = this.matches()
+    const sel = Math.min(this.selected, all.length - 1)
+
+    // Keep the highlight inside a maxVisible-row window.
+    const start = Math.max(0, Math.min(sel - this.maxVisible + 1, all.length - this.maxVisible))
+    const top = all.length > this.maxVisible ? Math.max(0, start) : 0
+    const shown = all.slice(top, top + this.maxVisible)
+
+    const nameW = Math.max(...all.map((s) => (this.trigger + s.name).length))
+    const rows = shown.map((s, i) => {
+      const isSel = top + i === sel
+      const label = (this.trigger + s.name).padEnd(nameW)
+      const text = s.desc ? label + '  ' + s.desc : label
+      if (isSel) {
+        return style()
+          .foreground('black')
+          .background('magenta')
+          .render(' ' + text + ' ')
+      }
+      return ' ' + style().foreground('magenta').render(label) + (s.desc ? '  ' + dim(s.desc) : '')
+    })
+
+    if (all.length > shown.length) {
+      rows.push(dim(`  …${all.length - shown.length} more`))
+    }
+    return rows.join('\n')
+  }
+}
+
+function create(opts) {
+  return new Autocomplete(opts)
+}
+
+module.exports = { create, Autocomplete, keys }

package/components/filepicker.js

@@ -0,0 +1,232 @@
+// filepicker — browse a filesystem and pick a file.
+//
+// Dependency-injected so the framework core stays filesystem-free: pass your
+// own { fs, path } to create(), or let it lazily require('bare-fs') /
+// require('bare-path') — that require only runs when you actually construct a
+// filepicker, so consumers who don't use it never pull those modules in.
+//
+//   const fp = filepicker.create({ height: 12 })            // real fs
+//   const fp = filepicker.create({ ...filepicker.mock(tree), cwd: '/' })  // tests
+//
+// Directory reads happen through Cmds (async), surfacing as Msgs:
+//   { type: 'filepicker.entries', dir, entries }
+//   { type: 'filepicker.error',   dir, error }
+//   { type: 'filepicker.select',  path }   // a file was chosen
+//
+// The only fs surface used is fs.readdir(dir, { withFileTypes: true }, cb); the
+// only path surface is path.join and path.dirname. The mock implements exactly
+// that, so tests need no real I/O.
+const key = require('../key')
+const { style } = require('../style')
+
+const dirStyle = (s) => style().foreground('cyan').render(s)
+const selectedStyle = (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' } }),
+  open: key.binding({ keys: ['enter', 'right', 'l'], help: { key: '↵', desc: 'open' } }),
+  back: key.binding({ keys: ['backspace', 'left', 'h'], help: { key: '⌫', desc: 'up dir' } })
+}
+
+function listDir(fs, dir) {
+  return new Promise((resolve, reject) => {
+    fs.readdir(dir, { withFileTypes: true }, (err, ents) => {
+      if (err) return reject(err)
+      resolve(ents.map((e) => ({ name: e.name, directory: e.isDirectory() })))
+    })
+  })
+}
+
+function sortEntries(entries, showHidden) {
+  return entries
+    .filter((e) => showHidden || !e.name.startsWith('.'))
+    .sort((a, b) => {
+      if (a.directory !== b.directory) return a.directory ? -1 : 1
+      return a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+    })
+}
+
+class FilePicker {
+  constructor(opts = {}) {
+    this.fs = opts.fs
+    this.path = opts.path
+    this.cwd = opts.cwd
+    this.height = opts.height || 12
+    this.showHidden = !!opts.showHidden
+
+    this.entries = []
+    this.cursor = 0
+    this.offset = 0
+    this.selected = null
+    this.error = null
+    this.loading = true
+  }
+
+  init() {
+    return this._read(this.cwd)
+  }
+
+  selectedPath() {
+    return this.selected
+  }
+
+  // A Cmd that reads `dir` and resolves to an entries (or error) Msg.
+  _read(dir) {
+    const fs = this.fs
+    const showHidden = this.showHidden
+    return () =>
+      listDir(fs, dir).then(
+        (entries) => ({
+          type: 'filepicker.entries',
+          dir,
+          entries: sortEntries(entries, showHidden)
+        }),
+        (err) => ({
+          type: 'filepicker.error',
+          dir,
+          error: (err && err.message) || String(err)
+        })
+      )
+  }
+
+  update(msg) {
+    if (!msg) return [this, null]
+
+    if (msg.type === 'filepicker.entries' && msg.dir === this.cwd) {
+      this.entries = msg.entries
+      this.cursor = 0
+      this.offset = 0
+      this.loading = false
+      this.error = null
+      return [this, null]
+    }
+    if (msg.type === 'filepicker.error' && msg.dir === this.cwd) {
+      this.error = msg.error
+      this.entries = []
+      this.loading = false
+      return [this, null]
+    }
+    if (msg.type === 'key') return this._key(msg)
+    return [this, null]
+  }
+
+  _key(msg) {
+    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.back)) return this._open(this.path.dirname(this.cwd))
+    else if (key.matches(msg, keys.open)) {
+      const entry = this.entries[this.cursor]
+      if (!entry) return [this, null]
+      const full = this.path.join(this.cwd, entry.name)
+      if (entry.directory) return this._open(full)
+      this.selected = full
+      return [this, () => ({ type: 'filepicker.select', path: full })]
+    }
+    return [this, null]
+  }
+
+  _open(dir) {
+    this.cwd = dir
+    this.loading = true
+    return [this, this._read(dir)]
+  }
+
+  _move(delta) {
+    if (!this.entries.length) return
+    this.cursor = Math.max(0, Math.min(this.cursor + delta, this.entries.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
+    }
+  }
+
+  view() {
+    const out = [
+      style()
+        .bold(true)
+        .render(this.cwd || '')
+    ]
+    const rows = []
+
+    if (this.loading) rows.push(dim('  loading…'))
+    else if (this.error) rows.push(dim('  ⚠ ' + this.error))
+    else if (!this.entries.length) rows.push(dim('  (empty)'))
+    else {
+      const end = Math.min(this.offset + this.height, this.entries.length)
+      for (let p = this.offset; p < end; p++) {
+        const entry = this.entries[p]
+        const label = entry.directory ? entry.name + '/' : entry.name
+        const text = (p === this.cursor ? '› ' : '  ') + label
+        rows.push(p === this.cursor ? selectedStyle(text) : entry.directory ? dirStyle(text) : text)
+      }
+    }
+    while (rows.length < this.height) rows.push('')
+
+    return out.concat(rows).join('\n')
+  }
+}
+
+function create(opts = {}) {
+  // Lazy require: only consumers that build a filepicker load bare-fs/bare-path.
+  const fs = opts.fs || require('bare-fs')
+  const path = opts.path || require('bare-path')
+  const cwd = opts.cwd || path.resolve('.')
+  return new FilePicker({ ...opts, fs, path, cwd })
+}
+
+// ── mock filesystem ──────────────────────────────────────────────────────
+//
+// filepicker.mock(tree) returns { fs, path, root } backed by a plain object:
+// keys are entry names, an object value is a directory, anything else a file.
+//
+//   const m = filepicker.mock({ docs: { 'a.md': null }, 'readme.txt': null })
+//   const fp = filepicker.create({ fs: m.fs, path: m.path, cwd: m.root })
+
+const mockPath = {
+  sep: '/',
+  join: (...parts) => parts.join('/').replace(/\/{2,}/g, '/') || '/',
+  dirname: (p) => {
+    const segs = p.replace(/\/+$/, '').split('/')
+    segs.pop()
+    const d = segs.join('/')
+    return d === '' ? '/' : d
+  },
+  basename: (p) => p.replace(/\/+$/, '').split('/').pop() || '/',
+  resolve: (p) => p
+}
+
+function resolveNode(tree, root, p) {
+  if (p === root) return tree
+  let rel = p
+  if (root !== '/' && p.startsWith(root)) rel = p.slice(root.length)
+  const segs = rel.split('/').filter(Boolean)
+  let node = tree
+  for (const s of segs) {
+    if (node && typeof node === 'object' && s in node) node = node[s]
+    else return undefined
+  }
+  return node
+}
+
+function mock(tree, opts = {}) {
+  const root = opts.root || '/'
+  const fs = {
+    readdir(dir, options, cb) {
+      if (typeof options === 'function') cb = options
+      const node = resolveNode(tree, root, dir)
+      if (!node || typeof node !== 'object') {
+        return cb(new Error('ENOTDIR: ' + dir))
+      }
+      const ents = Object.keys(node).map((name) => {
+        const isDir = !!(node[name] && typeof node[name] === 'object')
+        return { name, isDirectory: () => isDir }
+      })
+      cb(null, ents)
+    }
+  }
+  return { fs, path: mockPath, root }
+}
+
+module.exports = { create, FilePicker, mock }

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 }