bare-tui-form 0.0.0 → 0.0.1

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/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 }

package/fields/number.js

@@ -0,0 +1,60 @@
+// number — a numeric field. Wraps textinput for entry, but value() coerces to a
+// Number and syncValidate() enforces numeric-ness plus optional min/max/integer.
+const { textinput } = require('bare-tui')
+const { Field } = require('./base')
+
+class NumberField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.min = opts.min
+    this.max = opts.max
+    this.integer = !!opts.integer
+    this.control = textinput.create({
+      value: opts.value === undefined || opts.value === null ? '' : String(opts.value),
+      placeholder: opts.placeholder || '',
+      prompt: opts.prompt ?? '> '
+    })
+  }
+
+  // null when blank, a finite Number when parseable, otherwise NaN (so
+  // syncValidate() can flag it; an unflagged NaN would JSON-serialize to null).
+  value() {
+    const raw = this.control.value.trim()
+    if (raw === '') return null
+    return Number(raw)
+  }
+
+  setValue(v) {
+    this.control.setValue(v === undefined || v === null ? '' : String(v))
+    return this
+  }
+
+  isEmpty(v) {
+    return v === null
+  }
+
+  // The numeric rules live here (not in validate()) because the form validates
+  // through syncValidate — both on enter-confirm and on submit.
+  syncValidate(v) {
+    // Base handles required + empty + any custom validator first.
+    const base = super.syncValidate(v)
+    if (base) return base
+
+    if (v === null) return null // optional and blank
+    if (Number.isNaN(v)) return 'must be a number'
+    if (this.integer && !Number.isInteger(v)) return 'must be a whole number'
+    if (this.min !== undefined && v < this.min) return `must be ≥ ${this.min}`
+    if (this.max !== undefined && v > this.max) return `must be ≤ ${this.max}`
+    return null
+  }
+
+  controlView() {
+    return this.control.view()
+  }
+}
+
+function number(opts) {
+  return new NumberField(opts)
+}
+
+module.exports = { number, NumberField }

package/fields/radio.js

@@ -0,0 +1,32 @@
+// radio — pick one from an expanded list, wrapping bare-tui's radio.
+const { radio } = require('bare-tui')
+const { Field } = require('./base')
+
+class RadioField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.control = radio.create({
+      options: opts.options || [],
+      selected: opts.selected || 0
+    })
+  }
+
+  value() {
+    return this.control.value()
+  }
+
+  setValue(v) {
+    this.control.setValue(v)
+    return this
+  }
+
+  controlView() {
+    return this.control.view()
+  }
+}
+
+function radio_(opts) {
+  return new RadioField(opts)
+}
+
+module.exports = { radio: radio_, RadioField }

package/fields/section.js

@@ -0,0 +1,71 @@
+// section — the include/omit toggle for an optional nested-object section.
+//
+// A non-required object in a schema becomes a sub-section the user can choose to
+// fill in or leave out. This field is its gate: a focusable checkbox rendered as
+// the section's heading. The form:
+//
+//   - auto-checks it the moment any field inside the section gets a value,
+//   - omits the whole subtree from value() while it's unchecked,
+//   - and only validates the section's inner `required` fields while it's on.
+//
+// So the user is in control — start typing and the section is "in", toggle the
+// box off to drop it — and the fields stay visible the whole time (no dynamic
+// show/hide). It never carries a value of its own; `isSection` tells the form to
+// treat it as a gate, not a leaf, and it never blocks submission itself.
+const { checkbox } = require('bare-tui')
+const { Field } = require('./base')
+
+class SectionToggleField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.isSection = true
+    this.control = checkbox.create({
+      label: opts.title || opts.label || this.key,
+      checked: !!opts.value
+    })
+  }
+
+  get checked() {
+    return this.control.checked
+  }
+
+  value() {
+    return this.control.checked
+  }
+
+  setValue(v) {
+    this.control.setChecked(v)
+    return this
+  }
+
+  // A section gate is never itself required and never reports an error — the
+  // completeness of an included section is enforced by its own inner fields.
+  requiredError() {
+    return null
+  }
+
+  syncValidate() {
+    return null
+  }
+
+  controlView() {
+    return this.control.view()
+  }
+
+  // Renders as the section heading: the checkbox + title, with a quiet hint when
+  // it's off so it's clear the section won't be submitted.
+  view() {
+    const t = this.theme
+    const head = t.sectionTitle(this.control.view())
+    const hint = this.control.checked ? '' : '  ' + t.help('(off — not included)')
+    const lines = [head + hint]
+    if (this.description) lines.push(t.description(this.description))
+    return lines.join('\n')
+  }
+}
+
+function section(opts) {
+  return new SectionToggleField(opts)
+}
+
+module.exports = { section, SectionToggleField }

package/fields/select.js

@@ -0,0 +1,46 @@
+// select — pick one from a dropdown, wrapping bare-tui's select.
+//
+// It forwards the control's overlay (menuView) so the form can composite the
+// dropdown, and claims enter while the menu is open (to commit the choice).
+const { select } = require('bare-tui')
+const { Field } = require('./base')
+
+class SelectField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.control = select.create({
+      options: opts.options || [],
+      selected: opts.selected ?? -1,
+      placeholder: opts.placeholder || 'select…',
+      maxVisible: opts.maxVisible || 6
+    })
+  }
+
+  value() {
+    return this.control.value()
+  }
+
+  setValue(v) {
+    this.control.setValue(v)
+    return this
+  }
+
+  // While the menu is open, enter commits the highlighted option.
+  wantsEnter() {
+    return this.control.open
+  }
+
+  menuView() {
+    return this.control.menuView()
+  }
+
+  controlView() {
+    return this.control.view()
+  }
+}
+
+function select_(opts) {
+  return new SelectField(opts)
+}
+
+module.exports = { select: select_, SelectField }

package/fields/text.js

@@ -0,0 +1,35 @@
+// text — a single-line text field, wrapping bare-tui's textinput.
+const { textinput } = require('bare-tui')
+const { Field } = require('./base')
+
+class TextField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.control = textinput.create({
+      value: opts.value || '',
+      placeholder: opts.placeholder || '',
+      prompt: opts.prompt ?? '> ',
+      charLimit: opts.charLimit || 0,
+      echoMode: opts.echoMode || 'normal'
+    })
+  }
+
+  value() {
+    return this.control.value
+  }
+
+  setValue(v) {
+    this.control.setValue(v === null || v === undefined ? '' : v)
+    return this
+  }
+
+  controlView() {
+    return this.control.view()
+  }
+}
+
+function text(opts) {
+  return new TextField(opts)
+}
+
+module.exports = { text, TextField }

package/fields/textarea.js

@@ -0,0 +1,43 @@
+// textarea — a multi-line text field, wrapping bare-tui's textarea.
+//
+// Unlike the other fields it *captures enter* (newline), so the form moves on
+// via tab rather than enter.
+const { textarea } = require('bare-tui')
+const { Field } = require('./base')
+
+class TextareaField extends Field {
+  constructor(opts = {}) {
+    super(opts)
+    this.control = textarea.create({
+      value: opts.value || '',
+      placeholder: opts.placeholder || '',
+      width: opts.width || 40,
+      height: opts.rows || opts.height || 4, // `rows` mirrors uiSchema's ui:rows
+      charLimit: opts.charLimit || 0
+    })
+  }
+
+  value() {
+    return this.control.value
+  }
+
+  setValue(v) {
+    this.control.setValue(v === null || v === undefined ? '' : v)
+    return this
+  }
+
+  // Enter inserts a newline here; advance with tab instead.
+  wantsEnter() {
+    return true
+  }
+
+  controlView() {
+    return this.control.view()
+  }
+}
+
+function textarea_(opts) {
+  return new TextareaField(opts)
+}
+
+module.exports = { textarea: textarea_, TextareaField }