bare-tui 0.0.0 → 0.0.2

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

@@ -0,0 +1,68 @@
+// checkbox — a single boolean toggle.
+//
+// A leaf input in the textinput mould: it only reacts when focused, so a parent
+// can broadcast keys to several controls and only the focused one moves. Space
+// toggles; it deliberately never consumes enter, so a parent form can keep enter
+// for "submit" while a checkbox has focus.
+//
+//   const agree = checkbox.create({ label: 'I agree', checked: false }).focus()
+//   // in update: const [c] = agree.update(msg); this.agree = c
+//   // in view:   agree.view()   // "› [x] I agree"
+//
+// Focus is shown with a leading '›' pointer (a blank when blurred), the same
+// idiom radio and select use, so a stack of controls reads consistently and the
+// pointer never shifts the line width.
+const key = require('../key')
+
+const keys = {
+  // Space only — enter is left for the parent (e.g. submit).
+  toggle: key.binding({ keys: ['space'], help: { key: 'space', desc: 'toggle' } })
+}
+
+class Checkbox {
+  constructor(opts = {}) {
+    this.label = opts.label || ''
+    this.checked = !!opts.checked
+    this.focused = !!opts.focused
+    this.checkedGlyph = opts.checkedGlyph || '[x]'
+    this.uncheckedGlyph = opts.uncheckedGlyph || '[ ]'
+  }
+
+  focus() {
+    this.focused = true
+    return this
+  }
+
+  blur() {
+    this.focused = false
+    return this
+  }
+
+  setChecked(v) {
+    this.checked = !!v
+    return this
+  }
+
+  toggle() {
+    this.checked = !this.checked
+    return this
+  }
+
+  update(msg) {
+    if (!this.focused || !msg || msg.type !== 'key') return [this, null]
+    if (key.matches(msg, keys.toggle)) this.toggle()
+    return [this, null]
+  }
+
+  view() {
+    const pointer = this.focused ? '› ' : '  '
+    const box = this.checked ? this.checkedGlyph : this.uncheckedGlyph
+    return pointer + (this.label ? box + ' ' + this.label : box)
+  }
+}
+
+function create(opts) {
+  return new Checkbox(opts)
+}
+
+module.exports = { create, Checkbox, 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/focus.js

@@ -0,0 +1,129 @@
+// focus — an ordered focus ring across a set of child components.
+//
+// This is connective tissue, not a widget: it has no view(). It holds an
+// ordered list of focusable children and owns the one job every multi-field
+// screen reimplements — moving focus between them with tab/shift+tab, blurring
+// the old and focusing the new. It relies only on the component contract the
+// built-ins already follow (`focus()` / `blur()` and `update(msg) → [m, cmd]`).
+//
+//   this.ring = focus.create({
+//     items: [
+//       textinput.create({ prompt: '> ' }),
+//       radio.create({ options: ['a', 'b'] }),
+//       checkbox.create({ label: 'ok' })
+//     ]
+//   })
+//
+//   update(msg) {
+//     // Handle global / submit keys FIRST so a focused child can't swallow them.
+//     if (key.matches(msg, 'ctrl+c')) return [this, quit]
+//     if (key.matches(msg, 'enter')) return [this, this._submit()]
+//     // Then let the ring move focus and route the rest to the focused child,
+//     // threading its Cmd back up.
+//     const [ring, cmd] = this.ring.update(msg)
+//     this.ring = ring
+//     return [this, cmd]
+//   }
+//   view() { return this.ring.items.map((it) => it.view()).join('\n') }
+//
+// Navigation defaults to tab/shift+tab ONLY — deliberately not up/down, because
+// the focusable children (radio, select, list, textarea) use the arrows
+// internally. Pass `keys` to override if your children don't. focus() syncs the
+// children on construction so exactly the indexed one is focused.
+const key = require('../key')
+
+const defaultKeys = {
+  next: key.binding({ keys: ['tab'], help: { key: 'tab', desc: 'next field' } }),
+  prev: key.binding({ keys: ['shift+tab'], help: { key: 'shift+tab', desc: 'prev field' } })
+}
+
+class Focus {
+  constructor(opts = {}) {
+    this.items = opts.items ? opts.items.slice() : []
+    this.index = opts.index || 0
+    this.keys = opts.keys || defaultKeys
+    this._clamp()
+    this._sync()
+  }
+
+  // The currently focused child, or null when there are none.
+  focused() {
+    return this.items[this.index] || null
+  }
+
+  setItems(items) {
+    this.items = items ? items.slice() : []
+    this._clamp()
+    this._sync()
+    return this
+  }
+
+  // Focus a specific index (clamped); blurs the rest.
+  focus(i) {
+    this.index = i
+    this._clamp()
+    this._sync()
+    return this
+  }
+
+  next() {
+    this._move(1)
+    return this
+  }
+
+  prev() {
+    this._move(-1)
+    return this
+  }
+
+  update(msg) {
+    // Ring navigation is handled here, before the child sees the key. Check the
+    // more-specific 'prev' chord (shift+tab) first: key matching also accepts a
+    // bare name, so a 'tab' binding would otherwise swallow 'shift+tab' too.
+    if (key.matches(msg, this.keys.prev)) {
+      this._move(-1)
+      return [this, null]
+    }
+    if (key.matches(msg, this.keys.next)) {
+      this._move(1)
+      return [this, null]
+    }
+
+    // Everything else goes to the focused child; thread its Cmd up.
+    const cur = this.items[this.index]
+    if (cur && typeof cur.update === 'function') {
+      const [m, cmd] = cur.update(msg)
+      this.items[this.index] = m
+      return [this, cmd]
+    }
+    return [this, null]
+  }
+
+  _move(dir) {
+    if (this.items.length < 2) return
+    this.index = (this.index + dir + this.items.length) % this.items.length
+    this._sync()
+  }
+
+  _clamp() {
+    if (!this.items.length) this.index = 0
+    else this.index = Math.max(0, Math.min(this.index, this.items.length - 1))
+  }
+
+  // Make exactly items[index] focused; blur the rest. Guards children that
+  // don't implement the focus contract.
+  _sync() {
+    this.items.forEach((it, i) => {
+      if (!it) return
+      if (i === this.index) {
+        if (typeof it.focus === 'function') it.focus()
+      } else if (typeof it.blur === 'function') it.blur()
+    })
+  }
+}
+
+function create(opts) {
+  return new Focus(opts)
+}
+
+module.exports = { create, Focus, defaultKeys }