bare-tui-form 0.0.0 → 0.0.2

package/fields/base.js

@@ -0,0 +1,213 @@
+// Field — the base class every form field extends.
+//
+// A field adapts a bare-tui control (textinput, select, radio, …) to the form:
+// it carries a value `key`, a `label`/`description`, an optional `validate`
+// function, and the current `error`. The form treats every field through one
+// small contract:
+//
+//   field.key                  // the value key in form.value()
+//   field.focus() / blur()     // gate input (delegates to the control)
+//   field.focused              // is this field focused
+//   field.update(msg) → [f,cmd]// fold a Msg (delegates to the control)
+//   field.value()              // current value           (subclass)
+//   field.setValue(v)          // set it                  (subclass)
+//   field.controlView()        // render just the control (subclass)
+//   field.menuView()           // optional overlay (select dropdown); '' default
+//   field.wantsEnter()         // true if enter belongs to the control right now
+//   field.validate()           // run SYNC validation, set .error, return it
+//   field.view()               // label + description + control + error/spinner
+//
+// Validation can be synchronous or asynchronous. If `validate` is an async
+// function it's run by the form through a Cmd, with a spinner shown meanwhile;
+// the sync helpers below (requiredError/syncValidate) are what the form uses for
+// the instant checks, and runValidator() is what it awaits for the async one.
+//
+// Subclasses set `this.control` (a bare-tui component) and implement value(),
+// setValue() and controlView(). The base delegates focus/blur/update to the
+// control and assembles the field's block in view(), styled through `this.theme`
+// (set to the form's theme on construction, or the default for a lone field).
+const { spinner } = require('bare-tui')
+const { defaultTheme } = require('../theme')
+
+const FRAME_SETS = { dots: spinner.dots, line: spinner.line, points: spinner.points }
+
+// Sentinel for "this field's async validator has never passed for any value".
+const UNCHECKED = Symbol('unchecked')
+
+class Field {
+  constructor(opts = {}) {
+    this.key = opts.name || opts.key || ''
+    // The address of this field's value in the (possibly nested) result object.
+    // A flat field's path is just [key]; a field inside a nested object section
+    // carries the full chain (['address', 'street']). The form walks it to build
+    // and read nested values. Set by the form when it flattens nested defs.
+    this.path = Array.isArray(opts.path) && opts.path.length ? opts.path.slice() : [this.key]
+    // Section toggles (the optional-subform checkbox) set this; leaf fields don't.
+    this.isSection = false
+    // A oneOf/anyOf variant *selector* sets this: it drives which branch is live
+    // but carries no value of its own, so the form skips it when collecting.
+    this.isSelector = false
+    // Can the focus ring land here? A const (fixed discriminator) field is shown
+    // and collected but not interactive, so it opts out.
+    this.focusable = true
+    // An action button (array add/remove): focusable, carries no value, and the
+    // form runs its `action` on enter instead of validating/advancing.
+    this.isButton = false
+    this.label = opts.label || this.key
+    this.description = opts.description || ''
+    // Presentation (uiSchema): extra help line, hidden label, read-only display,
+    // initial-focus hint, and fully-hidden (collected but never shown) fields.
+    this.help = opts.help || ''
+    this.hideLabel = !!opts.hideLabel
+    this.autofocus = !!opts.autofocus
+    this.hidden = !!opts.hidden
+    if (opts.readonly || opts.hidden) this.focusable = false
+    this.required = !!opts.required
+    this.requiredMessage = opts.requiredMessage || 'required'
+    this.validatingMessage = opts.validatingMessage || 'checking…'
+    this._validate = typeof opts.validate === 'function' ? opts.validate : null
+    this._isAsync = !!this._validate && this._validate.constructor.name === 'AsyncFunction'
+
+    this.error = null
+    this.validating = false // true while an async check is in flight
+    this.spinner = null // bare-tui spinner, live only while validating
+    this._runId = 0 // generation: bumped to discard stale async results
+    // The value its async validator last *passed* for; compared to the current
+    // value to tell whether an async check still needs running (see the form's
+    // validate-on-submit pass). UNCHECKED until the first passing result.
+    this._asyncCheckedValue = UNCHECKED
+
+    this.theme = defaultTheme
+    this.control = null // set by the subclass
+  }
+
+  setTheme(theme) {
+    this.theme = theme
+    return this
+  }
+
+  focus() {
+    if (this.control) this.control.focus()
+    return this
+  }
+
+  blur() {
+    if (this.control) this.control.blur()
+    return this
+  }
+
+  get focused() {
+    return this.control ? this.control.focused : false
+  }
+
+  update(msg) {
+    if (!this.control) return [this, null]
+    const [c, cmd] = this.control.update(msg)
+    this.control = c
+    // Editing clears a stale error; it's re-checked on the next confirm.
+    if (this.error) this.error = null
+    return [this, cmd]
+  }
+
+  // Most controls don't need enter; textarea (newline) and an open select
+  // (commit) do, and override this.
+  wantsEnter() {
+    return false
+  }
+
+  // Overlay content (the select dropdown). Empty for everything else.
+  menuView() {
+    return ''
+  }
+
+  // Is `v` "empty" for the purpose of `required`? Overridable (confirm/number).
+  isEmpty(v) {
+    return v === '' || v === null || v === undefined || (Array.isArray(v) && v.length === 0)
+  }
+
+  // --- validation -----------------------------------------------------------
+
+  // The required-but-empty error, or null. (sync)
+  requiredError(v) {
+    return this.required && this.isEmpty(v) ? this.requiredMessage : null
+  }
+
+  hasValidator() {
+    return !!this._validate
+  }
+
+  isAsync() {
+    return this._isAsync
+  }
+
+  // Does this field have an async validator whose current (non-empty) value
+  // hasn't passed yet? Used by the form to re-run dirty async checks on submit.
+  // Editing changes the value, so a once-passed field goes dirty automatically.
+  needsAsyncCheck() {
+    if (!this._isAsync) return false
+    const v = this.value()
+    if (this.isEmpty(v)) return false
+    return this._asyncCheckedValue !== v
+  }
+
+  // Run the user validator (may return a string, null, or a Promise of those).
+  runValidator(v) {
+    return this._validate ? this._validate(v) : null
+  }
+
+  // The instant verdict: required, then the sync validator. Async validators
+  // aren't run here (the form awaits them separately); an empty optional field
+  // is always fine.
+  syncValidate(v) {
+    if (this.required && this.isEmpty(v)) return this.requiredMessage
+    if (this.isEmpty(v)) return null
+    if (this._validate && !this._isAsync) return this._validate(v) || null
+    return null
+  }
+
+  // Backwards-compatible sync entry point: set and return .error.
+  validate() {
+    this.error = this.syncValidate(this.value())
+    return this.error
+  }
+
+  // --- spinner lifecycle (driven by the form) -------------------------------
+
+  // Start the validating spinner and return its initial tick Cmd.
+  startSpinner() {
+    const cfg = (this.theme && this.theme.spinner) || {}
+    const frames = typeof cfg.frames === 'string' ? FRAME_SETS[cfg.frames] : cfg.frames
+    this.spinner = spinner.create({ frames, fps: cfg.fps })
+    return this.spinner.init()
+  }
+
+  stopSpinner() {
+    this.spinner = null
+  }
+
+  // --- rendering ------------------------------------------------------------
+
+  // label (+ marker when required) · description · control · help · error|spinner.
+  // The label is omitted when hideLabel (uiSchema's `ui:label: false`).
+  view() {
+    const t = this.theme
+    const lines = []
+    if (!this.hideLabel) {
+      const labelText = this.label + (this.required ? t.requiredMarker : '')
+      lines.push(this.focused ? t.labelFocused(labelText) : t.label(labelText))
+    }
+    if (this.description) lines.push(t.description(this.description))
+    lines.push(...this.controlView().split('\n'))
+    if (this.help) lines.push(t.help(this.help))
+
+    if (this.validating) {
+      const frame = this.spinner ? this.spinner.view() : ''
+      lines.push(t.validating((frame ? frame + ' ' : '') + this.validatingMessage))
+    } else if (this.error) {
+      lines.push(t.error(t.errorPrefix + this.error))
+    }
+    return lines.join('\n')
+  }
+}
+
+module.exports = { Field }

package/fields/confirm.js

@@ -0,0 +1,46 @@
+// confirm — a boolean field, wrapping bare-tui's checkbox.
+//
+// When `required`, "empty" means "not checked", so a required confirm must be
+// ticked to pass (e.g. an "I agree" box).
+const { checkbox } = require('bare-tui')
+const { Field } = require('./base')
+
+class ConfirmField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    // The checkbox line *is* the label, so suppress the separate label row that
+    // every other field renders above its control — otherwise the text shows
+    // twice ("Accept terms" then "[ ] Accept terms").
+    this.hideLabel = true
+    // The checkbox draws just the pointer + box; the label is added (themed) in
+    // controlView so it picks up labelFocused and the required marker.
+    this.control = checkbox.create({ label: '', checked: !!opts.value })
+  }
+
+  value() {
+    return this.control.checked
+  }
+
+  setValue(v) {
+    this.control.setChecked(v)
+    return this
+  }
+
+  isEmpty(v) {
+    return v !== true
+  }
+
+  // "› [x] Accept terms *" — the box from the checkbox, the label themed here.
+  controlView() {
+    const t = this.theme
+    const text = this.label + (this.required ? t.requiredMarker : '')
+    const styled = this.focused ? t.labelFocused(text) : t.label(text)
+    return this.control.view() + ' ' + styled
+  }
+}
+
+function confirm(opts) {
+  return new ConfirmField(opts)
+}
+
+module.exports = { confirm, ConfirmField }

package/fields/constant.js

@@ -0,0 +1,41 @@
+// constant — a fixed value (JSON Schema `const`).
+//
+// A const property carries a value the user can't change — most often the
+// discriminator of a oneOf branch (`type: { const: 'card' }`). It's shown as a
+// static line and included in the collected value, but it's not interactive, so
+// it opts out of the focus ring (`focusable = false`) and never errors.
+const { Field } = require('./base')
+
+class ConstField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.focusable = false
+    this.constValue = opts.value
+  }
+
+  value() {
+    return this.constValue
+  }
+
+  setValue() {
+    return this // fixed — rehydration can't change a const
+  }
+
+  isEmpty() {
+    return false
+  }
+
+  syncValidate() {
+    return null
+  }
+
+  controlView() {
+    return this.constValue === undefined ? '' : String(this.constValue)
+  }
+}
+
+function constant(opts) {
+  return new ConstField(opts)
+}
+
+module.exports = { constant, ConstField }

package/fields/file.js

@@ -0,0 +1,129 @@
+// file — a path field you can either type or browse.
+//
+// It wraps bare-tui's textinput (the editable path, and the field's string
+// value) and lazily opens bare-tui's filepicker as an overlay — the same
+// host-the-control-and-expose-an-overlay shape as fields/select.js. The picker
+// is created the first time you open it, so a form full of file fields doesn't
+// pull in bare-fs until one is actually browsed.
+//
+// Interaction (mirrors select's "space opens, never steals enter"):
+//   closed  — type a path; SPACE on an empty input opens the picker
+//   open    — ↑/↓ move, →/l descend, ↵ open/select, ⌫ up a dir, esc closes
+// While open the field claims enter (wantsEnter) so the form's enter reaches the
+// picker instead of advancing; on a pick the chosen path fills the input.
+//
+// `pick: 'file' | 'dir'` chooses the picker mode. `fs`/`path`/`cwd`/`height`/
+// `showHidden` are forwarded to filepicker.create — `fs`/`path` let tests inject
+// filepicker.mock with no real I/O.
+const { textinput, filepicker, key } = require('bare-tui')
+const { Field } = require('./base')
+
+const openKey = key.binding({ keys: ['space'] })
+const closeKey = key.binding({ keys: ['esc'] })
+
+class FileField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.pick = opts.pick === 'dir' ? 'dir' : 'file'
+    this.input = textinput.create({
+      value: opts.value || '',
+      placeholder:
+        opts.placeholder ||
+        (this.pick === 'dir' ? 'choose a directory…' : 'type a path or browse…'),
+      prompt: opts.prompt ?? '> ',
+      charLimit: opts.charLimit || 0
+    })
+    // The base delegates focus()/blur()/`focused` to this.control — point it at
+    // the text input (the picker is a transient overlay, not the resting state).
+    this.control = this.input
+    this._pickerOpts = {
+      pick: this.pick,
+      cwd: opts.cwd,
+      height: opts.height,
+      showHidden: opts.showHidden,
+      fs: opts.fs,
+      path: opts.path
+    }
+    this.picker = null
+  }
+
+  value() {
+    return this.input.value
+  }
+
+  setValue(v) {
+    this.input.setValue(v === null || v === undefined ? '' : v)
+    return this
+  }
+
+  // While the picker is open, enter belongs to it (descend/select), so the form
+  // must not treat enter as confirm/advance.
+  get isOpen() {
+    return this.picker !== null
+  }
+
+  wantsEnter() {
+    return this.isOpen
+  }
+
+  update(msg) {
+    if (this.picker) return this._updateOpen(msg)
+
+    // Closed: SPACE on an empty input opens the browser; otherwise the text
+    // input handles the key (so you can type, and type spaces in a real path).
+    if (msg && msg.type === 'key' && key.matches(msg, openKey) && this.input.value === '') {
+      return this._open()
+    }
+    const [c, cmd] = this.input.update(msg)
+    this.input = c
+    if (this.error) this.error = null
+    return [this, cmd]
+  }
+
+  _updateOpen(msg) {
+    if (msg && msg.type === 'filepicker.select') {
+      this.setValue(msg.path)
+      this.picker = null
+      this.error = null
+      return [this, null]
+    }
+    if (msg && msg.type === 'key' && key.matches(msg, closeKey)) {
+      this.picker = null
+      return [this, null]
+    }
+    const [p, cmd] = this.picker.update(msg)
+    this.picker = p
+    return [this, cmd]
+  }
+
+  _open() {
+    this.picker = filepicker.create(this._pickerOpts)
+    // The first directory read is a Cmd; thread it up so the form/program runs it.
+    return [this, this.picker.init()]
+  }
+
+  // Tab-away (or any focus change) closes the overlay so it can't linger.
+  blur() {
+    this.picker = null
+    return super.blur()
+  }
+
+  menuView() {
+    return this.picker ? this.picker.view() : ''
+  }
+
+  controlView() {
+    const view = this.input.view()
+    if (this.isOpen) return view
+    const hint = this.theme.help(
+      this.pick === 'dir' ? '  space to browse folders' : '  space to browse'
+    )
+    return view + '\n' + hint
+  }
+}
+
+function file(opts) {
+  return new FileField(opts)
+}
+
+module.exports = { file, FileField }

package/fields/list.js

@@ -0,0 +1,158 @@
+// list — an editable list of scalar text values (add / remove rows).
+//
+// For a repeatable value with no fixed option set — tags, waypoints, a flag the
+// CLI accepts many times — where multiselect (a fixed enum) and array (a
+// repeatable OBJECT subform) don't fit. Each row is a bare-tui textinput; the
+// field is one focus stop in the form and manages its own row cursor:
+//
+//   ↑/↓   move between rows
+//   ↵     add a new row below and focus it
+//   ⌫     on an EMPTY row, remove it (otherwise deletes a character)
+//   tab   leave the field (the form's focus ring)
+//
+// value() is a plain array of the non-empty rows, in order — so a multi-valued
+// CLI flag round-trips as ["a","b"], not a single space-joined string.
+const { key, textinput } = require('bare-tui')
+const { Field } = require('./base')
+
+const keys = {
+  up: key.binding({ keys: ['up'] }),
+  down: key.binding({ keys: ['down'] }),
+  add: key.binding({ keys: ['enter'] }),
+  back: key.binding({ keys: ['backspace'] })
+}
+
+class ListField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.itemPlaceholder = opts.itemPlaceholder || 'type a value…'
+    this.min = Math.max(0, opts.minItems || 0)
+    this.max = opts.maxItems > 0 ? opts.maxItems : 0 // 0 = unbounded
+    this.cursor = 0
+    this._focused = false
+    const seed = Array.isArray(opts.value) ? opts.value.map(String) : []
+    // Always keep at least one (editable) row, even when minItems is 0; empty
+    // rows are dropped from value().
+    this.rows = (seed.length ? seed : ['']).map((v) => this._mkRow(v))
+    // No single wrapped control — the delegating methods are overridden below.
+    this.control = null
+  }
+
+  _mkRow(value) {
+    return textinput.create({ value, placeholder: this.itemPlaceholder, prompt: '' })
+  }
+
+  _floor() {
+    return Math.max(this.min, 1) // never collapse below one editable row
+  }
+
+  focus() {
+    this._focused = true
+    this._syncFocus()
+    return this
+  }
+
+  blur() {
+    this._focused = false
+    for (const r of this.rows) r.blur()
+    return this
+  }
+
+  get focused() {
+    return this._focused
+  }
+
+  // Enter belongs to the field (it adds a row) whenever it's focused, so the form
+  // doesn't treat enter as confirm/advance. Tab still moves to the next field.
+  wantsEnter() {
+    return this._focused
+  }
+
+  value() {
+    return this.rows.map((r) => r.value).filter((v) => v.trim() !== '')
+  }
+
+  setValue(values) {
+    const seed = Array.isArray(values) ? values.map(String) : []
+    this.rows = (seed.length ? seed : ['']).map((v) => this._mkRow(v))
+    this.cursor = 0
+    this._syncFocus()
+    return this
+  }
+
+  isEmpty(v) {
+    return !Array.isArray(v) || v.length === 0
+  }
+
+  update(msg) {
+    if (!this._focused || !msg || msg.type !== 'key') return [this, null]
+    const row = this.rows[this.cursor]
+
+    if (key.matches(msg, keys.up)) {
+      this._move(-1)
+      return [this, null]
+    }
+    if (key.matches(msg, keys.down)) {
+      this._move(1)
+      return [this, null]
+    }
+    if (key.matches(msg, keys.add)) {
+      this._addRow()
+      return [this, null]
+    }
+    // Backspace on an EMPTY row removes it; otherwise it edits (deletes a char).
+    if (
+      key.matches(msg, keys.back) &&
+      row &&
+      row.value === '' &&
+      this.rows.length > this._floor()
+    ) {
+      this._removeRow()
+      return [this, null]
+    }
+
+    const [c] = row.update(msg)
+    this.rows[this.cursor] = c
+    if (this.error) this.error = null
+    return [this, null]
+  }
+
+  _move(delta) {
+    this.cursor = Math.max(0, Math.min(this.cursor + delta, this.rows.length - 1))
+    this._syncFocus()
+  }
+
+  _addRow() {
+    if (this.max && this.rows.length >= this.max) return
+    this.rows.splice(this.cursor + 1, 0, this._mkRow(''))
+    this.cursor++
+    this._syncFocus()
+  }
+
+  _removeRow() {
+    this.rows.splice(this.cursor, 1)
+    this.cursor = Math.max(0, Math.min(this.cursor, this.rows.length - 1))
+    this._syncFocus()
+    if (this.error) this.error = null
+  }
+
+  _syncFocus() {
+    this.rows.forEach((r, i) => (this._focused && i === this.cursor ? r.focus() : r.blur()))
+  }
+
+  controlView() {
+    const t = this.theme
+    const lines = this.rows.map((r, i) => {
+      const pointer = this._focused && i === this.cursor ? '› ' : '  '
+      return pointer + r.view()
+    })
+    if (this._focused) lines.push(t.help('  ↵ add · ⌫ on an empty row removes'))
+    return lines.join('\n')
+  }
+}
+
+function list(opts) {
+  return new ListField(opts)
+}
+
+module.exports = { list, ListField, keys }

package/fields/multiselect.js

@@ -0,0 +1,97 @@
+// multiselect — choose many from a list of toggles.
+//
+// bare-tui has no checkbox *group*, so this field implements its own little
+// control inline (cursor + a checked set) rather than wrapping one. It still
+// presents the standard Field contract, so the form treats it like any other.
+// value() is an array of the checked values, in option order.
+const { key } = require('bare-tui')
+const { Field } = require('./base')
+
+const keys = {
+  up: key.binding({ keys: ['up', 'k'] }),
+  down: key.binding({ keys: ['down', 'j'] }),
+  toggle: key.binding({ keys: ['space'] })
+}
+
+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 MultiSelectField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.options = (opts.options || []).map(normalize)
+    this.cursor = 0
+    this.checked = new Set() // indices
+    this._focused = false
+    this.onGlyph = opts.onGlyph || '[x]'
+    this.offGlyph = opts.offGlyph || '[ ]'
+    if (Array.isArray(opts.value)) this.setValue(opts.value)
+    // No wrapped control; we override the delegating methods below.
+    this.control = null
+  }
+
+  focus() {
+    this._focused = true
+    return this
+  }
+
+  blur() {
+    this._focused = false
+    return this
+  }
+
+  get focused() {
+    return this._focused
+  }
+
+  value() {
+    const out = []
+    this.options.forEach((o, i) => {
+      if (this.checked.has(i)) out.push(o.value)
+    })
+    return out
+  }
+
+  setValue(values) {
+    const want = new Set(values || [])
+    this.checked = new Set()
+    this.options.forEach((o, i) => {
+      if (want.has(o.value)) this.checked.add(i)
+    })
+    return this
+  }
+
+  update(msg) {
+    if (!this._focused || !msg || msg.type !== 'key') return [this, null]
+    if (key.matches(msg, keys.up)) this.cursor = Math.max(0, this.cursor - 1)
+    else if (key.matches(msg, keys.down)) {
+      this.cursor = Math.min(this.options.length - 1, this.cursor + 1)
+    } else if (key.matches(msg, keys.toggle)) {
+      if (this.checked.has(this.cursor)) this.checked.delete(this.cursor)
+      else this.checked.add(this.cursor)
+      if (this.error) this.error = null
+    }
+    return [this, null]
+  }
+
+  controlView() {
+    return this.options
+      .map((o, i) => {
+        const pointer = this._focused && i === this.cursor ? '› ' : '  '
+        const box = this.checked.has(i) ? this.onGlyph : this.offGlyph
+        return pointer + box + ' ' + o.label
+      })
+      .join('\n')
+  }
+}
+
+function multiselect(opts) {
+  return new MultiSelectField(opts)
+}
+
+module.exports = { multiselect, MultiSelectField, keys }