bare-tui 0.0.1 → 0.0.2

package/README.md

@@ -20,8 +20,7 @@ This tutorial assumes you have [Bare](https://bare.pears.com) installed. We'll b
 bare-tui programs are made of a **model** describing the application state, and three methods on that model:
 
 - **`init`** — a function that returns an initial _command_ (or `null`).
-- **`update`** — a function that handles incoming _messages_ and updates the
-  model.
+- **`update`** — a function that handles incoming _messages_ and updates the model.
 - **`view`** — a function that renders the model to a string.
 
 ### The Model
@@ -108,13 +107,26 @@ Run it with `bare counter.js`. The `Program` puts the terminal into raw mode, en
 A **command** (`Cmd`) is a function `() => Msg | Promise<Msg> | null`. The runtime runs it _off_ the update path and feeds whatever message it returns back into `update`. This is how you do anything asynchronous — timers, file or network I/O, talking to a worker — without blocking the UI.
 
 ```js
-const { quit, batch, sequence, tick, every } = require('bare-tui')
+const { quit, batch, sequence, tick, every, suspend } = require('bare-tui')
 
 quit // a Cmd that quits the program
 tick(1000, () => ({ type: 'tick' })) // fire a Msg after 1s
 every(1000, () => ({ type: 'tick' })) // fire on the wall-clock second
 batch(cmdA, cmdB) // run several Cmds concurrently
 sequence(cmdA, cmdB) // run several Cmds in order
+suspend(fn) // drop the TUI, run fn() with the real terminal, then resume
+```
+
+Use `suspend` to hand the terminal to an external program that needs it — an editor (`$EDITOR`), a pager, a sub-shell. The runtime drops raw mode, leaves the alt-screen and releases stdin while `fn()` runs, then re-attaches and repaints; the message `fn` resolves to is delivered once the TUI is back:
+
+```js
+return [
+  model,
+  suspend(async () => {
+    await spawnEditor(file) // owns the real terminal while it runs
+    return { type: 'edited', file }
+  })
+]
 ```
 
 An async command just returns a promise:
@@ -162,6 +174,10 @@ Ready-made, composable pieces — each is a model (`update`/`view`) you embed in
 | [autocomplete](docs/autocomplete.md) | Text field with a suggestion menu       |
 | [textarea](docs/textarea.md)         | Multi-line text editor                  |
 | [list](docs/list.md)                 | Selectable, filterable list             |
+| [select](docs/select.md)             | Compact dropdown over a fixed list      |
+| [radio](docs/radio.md)               | Single choice from a fixed set          |
+| [checkbox](docs/checkbox.md)         | Boolean toggle                          |
+| [focus](docs/focus.md)               | Focus ring across child components      |
 | [table](docs/table.md)               | Columns with selectable, scrolling rows |
 | [viewport](docs/viewport.md)         | Scrollable window over long content     |
 | [paginator](docs/paginator.md)       | Page state + indicator                  |
@@ -218,8 +234,9 @@ bare-tui is built to be tested headlessly — no real terminal, no real I/O.
 
 Runnable, one per concept, in [`examples/`](examples):
 
-`counter` · `form` · `list` · `table` · `dashboard` · `pager` · `progress` ·
-`paginator` · `mouse` · `textarea` · `timer` · `filepicker` · `claude-code`
+`counter` · `form` · `controls` · `list` · `table` · `dashboard` · `pager` ·
+`progress` · `paginator` · `mouse` · `textarea` · `timer` · `filepicker` ·
+`claude-code`
 
 ```sh
 bare examples/dashboard.js

package/commands.js

@@ -37,6 +37,22 @@ function tick(ms, fn) {
     })
 }
 
+// Suspend the TUI, run an async function with the terminal handed back to the
+// shell, then resume and repaint. Use it to drop into an external program that
+// needs the real terminal — an editor ($EDITOR), a pager, a sub-shell:
+//
+//   return [model, suspend(async () => {
+//     await runEditor(file)              // owns the TTY while it runs
+//     return { type: 'edited', file }    // delivered to update() after resume
+//   })]
+//
+// The runtime detaches the terminal (drops raw mode, leaves the alt-screen,
+// releases stdin) before calling fn and re-attaches + repaints after it
+// settles. Whatever Msg fn resolves to is dispatched once the TUI is back.
+function suspend(fn) {
+  return { __suspend: fn }
+}
+
 // Like tick, but aligned to wall-clock boundaries: every(1000, ...) fires on
 // each whole second rather than one second after it happened to start. Keeps
 // repeated timers from drifting. Re-issue from update() to keep it going.
@@ -48,4 +64,4 @@ function every(ms, fn) {
     })
 }
 
-module.exports = { quit, batch, sequence, tick, every }
+module.exports = { quit, batch, sequence, tick, every, suspend }

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

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 }

package/components/select.js

@@ -0,0 +1,165 @@
+// select — a compact dropdown over a fixed list of options.
+//
+// Where autocomplete is for *open* typing with a filtered menu, select is for a
+// *closed* set you pick from. It shows one line (the current choice) until you
+// open it, then a menu of options to choose from. Like autocomplete it splits
+// rendering in two so a dropdown never reflows the layout:
+//
+//   view()      → the one-line control (always one line, stable width)
+//   menuView()  → the dropdown rows, or '' when closed — overlay this where it
+//                 fits (below a top-anchored control, above a bottom one)
+//
+//   const fruit = select.create({
+//     options: ['apple', 'banana', 'cherry'],
+//     placeholder: 'pick one'
+//   }).focus()
+//   fruit.value()   // 'apple', or null while nothing is chosen
+//
+// Key contract (mirrors the other field controls): while *closed* it consumes
+// only space (to open) and never enter, so a parent form keeps enter for
+// submit. While *open* it owns the menu — up/down move, enter or space commit,
+// esc cancels — which is fine because a form won't submit with a menu open.
+const key = require('../key')
+const ansi = require('../ansi')
+const { style } = require('../style')
+
+const dim = (s) => ansi.modifierDim + s + ansi.modifierReset
+
+const keys = {
+  open: key.binding({ keys: ['space'], help: { key: 'space', desc: 'open' } }),
+  up: key.binding({ keys: ['up', 'k'], help: { key: '↑/k', desc: 'up' } }),
+  down: key.binding({ keys: ['down', 'j'], help: { key: '↓/j', desc: 'down' } }),
+  commit: key.binding({ keys: ['enter', 'space'], help: { key: 'enter', desc: 'select' } }),
+  cancel: key.binding({ keys: ['esc'], help: { key: 'esc', desc: 'cancel' } })
+}
+
+// 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 Select {
+  constructor(opts = {}) {
+    this.options = (opts.options || []).map(normalize)
+    this.selected = opts.selected ?? -1 // committed choice; -1 = none yet
+    this.placeholder = opts.placeholder || 'select…'
+    this.focused = !!opts.focused
+    this.maxVisible = opts.maxVisible || 6
+    this.openGlyph = opts.openGlyph || '▾'
+
+    this.open = false
+    this.highlight = 0 // cursor within the menu while open
+    this._clampSelected()
+  }
+
+  focus() {
+    this.focused = true
+    return this
+  }
+
+  blur() {
+    this.focused = false
+    this.open = false
+    return this
+  }
+
+  // The committed value, or null when nothing is chosen.
+  value() {
+    const o = this.options[this.selected]
+    return o ? o.value : null
+  }
+
+  selectedOption() {
+    return this.options[this.selected] || null
+  }
+
+  setOptions(options) {
+    this.options = (options || []).map(normalize)
+    this._clampSelected()
+    return this
+  }
+
+  // Select by value; no-op if absent.
+  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 (!this.open) {
+      if (key.matches(msg, keys.open) && this.options.length) {
+        this.open = true
+        this.highlight = this.selected >= 0 ? this.selected : 0
+      }
+      return [this, null]
+    }
+
+    // Menu is open: it owns navigation, commit and cancel.
+    if (key.matches(msg, keys.cancel)) this.open = false
+    else 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.commit)) {
+      this.selected = this.highlight
+      this.open = false
+    }
+    return [this, null]
+  }
+
+  _move(delta) {
+    if (!this.options.length) return
+    this.highlight = Math.max(0, Math.min(this.highlight + delta, this.options.length - 1))
+  }
+
+  _clampSelected() {
+    if (this.selected < -1) this.selected = -1
+    if (this.selected > this.options.length - 1) this.selected = this.options.length - 1
+  }
+
+  view() {
+    const pointer = this.focused ? '› ' : '  '
+    const chosen = this.options[this.selected]
+    const label = chosen ? chosen.label : dim(this.placeholder)
+    return pointer + label + ' ' + this.openGlyph
+  }
+
+  // The dropdown, or '' when closed. Highlight is drawn black-on-magenta to
+  // match autocomplete's menu; a footer notes options scrolled out of view.
+  menuView() {
+    if (!this.open || !this.options.length) return ''
+
+    // Keep the highlight inside a maxVisible-row window.
+    const n = this.options.length
+    const start =
+      n > this.maxVisible
+        ? Math.max(0, Math.min(this.highlight - this.maxVisible + 1, n - this.maxVisible))
+        : 0
+    const shown = this.options.slice(start, start + this.maxVisible)
+
+    const rows = shown.map((o, i) => {
+      const isSel = start + i === this.highlight
+      if (isSel) {
+        return style()
+          .foreground('black')
+          .background('magenta')
+          .render(' ' + o.label + ' ')
+      }
+      return ' ' + o.label
+    })
+
+    if (n > shown.length) rows.push(dim(`  …${n - shown.length} more`))
+    return rows.join('\n')
+  }
+}
+
+function create(opts) {
+  return new Select(opts)
+}
+
+module.exports = { create, Select, keys }

package/docs/checkbox.md

@@ -0,0 +1,43 @@
+# checkbox
+
+A single boolean toggle. A focus-gated leaf input: it only reacts when focused,
+so a parent can broadcast keys to several controls and only the focused one
+moves.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { checkbox } = require('bare-tui')
+
+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"
+agree.checked // boolean
+```
+
+## Options
+
+| Option                            | Default       | Description              |
+| --------------------------------- | ------------- | ------------------------ |
+| `label`                           | `''`          | Text shown after the box |
+| `checked`                         | `false`       | Initial state            |
+| `focused`                         | `false`       | Start focused            |
+| `checkedGlyph` / `uncheckedGlyph` | `[x]` / `[ ]` | Box characters           |
+
+## API
+
+- `toggle()` / `setChecked(v)` — change state imperatively.
+- `focus()` / `blur()` — gate input. `.checked` / `.focused` are readable.
+
+## Keys
+
+`space` toggles. **`enter` is deliberately not consumed**, so a parent form can
+keep `enter` for "submit" while a checkbox has focus. Bindings are exported as
+`checkbox.keys` for the [help](help.md) component.
+
+A leading `›` marks focus (a blank when blurred), the same idiom
+[radio](radio.md) and [select](select.md) use, so the pointer never shifts the
+line width.

package/docs/focus.md

@@ -0,0 +1,68 @@
+# focus
+
+An ordered focus ring across a set of child components. This is connective
+tissue, not a widget — it has **no `view()`**. It owns the one job every
+multi-field screen reimplements: moving focus between children 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) → [model, cmd]`).
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { focus, textinput, radio, checkbox } = require('bare-tui')
+
+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')
+}
+```
+
+## Options
+
+| Option  | Default             | Description                            |
+| ------- | ------------------- | -------------------------------------- |
+| `items` | `[]`                | Ordered focusable children             |
+| `index` | `0`                 | Which child starts focused             |
+| `keys`  | `tab` / `shift+tab` | Navigation bindings (`{ next, prev }`) |
+
+On construction the ring syncs the children so exactly the indexed one is
+focused.
+
+## API
+
+- `focused()` — the active child, or `null`. `.index` / `.items` are readable.
+- `next()` / `prev()` / `focus(i)` — move focus imperatively (wraps).
+- `setItems(items)` — replace the children and re-sync focus.
+- `update(msg)` — handles navigation, then delegates everything else to the
+  focused child and threads its Cmd up.
+
+## Keys
+
+Navigation defaults to `tab`/`shift+tab` **only** — deliberately not the arrows,
+because the focusable children ([radio](radio.md), [select](select.md),
+[list](list.md), [textarea](textarea.md)) use the arrows internally. Pass `keys`
+to override if your children don't. Always handle global and submit keys in the
+parent _before_ calling `ring.update`, so a focused child can't swallow the
+escape hatch.

package/docs/radio.md

@@ -0,0 +1,49 @@
+# radio
+
+Single choice from a fixed set of options. A tiny vertical list where the cursor
+_is_ the value — the arrows move the selection directly, so there is no separate
+highlight-then-commit step.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { radio } = require('bare-tui')
+
+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).
+
+## Options
+
+| Option               | Default       | Description                  |
+| -------------------- | ------------- | ---------------------------- |
+| `options`            | `[]`          | Strings or `{ label, value}` |
+| `selected`           | `0`           | Initial index                |
+| `focused`            | `false`       | Start focused                |
+| `onGlyph`/`offGlyph` | `(•)` / `( )` | Bullet characters            |
+
+## API
+
+- `value()` — the chosen value, or `null` when there are no options.
+- `selectedOption()` — the chosen `{ label, value }`.
+- `setValue(v)` — select by value (no-op if absent). `setOptions(opts)`.
+
+## Keys
+
+`↑`/`↓` (`k`/`j`) move the selection. **`enter` is not consumed**, so a parent
+keeps it for "submit". The chosen option always shows a filled bullet (even when
+blurred); a leading `›` marks the focused row. Bindings are exported as
+`radio.keys` for the [help](help.md) component.

package/docs/select.md

@@ -0,0 +1,54 @@
+# select
+
+A compact dropdown over a fixed list of options. Where
+[autocomplete](autocomplete.md) is for _open_ typing with a filtered menu,
+select is for a _closed_ set you pick from: it shows one line (the current
+choice) until you open it, then a menu to choose from.
+
+[← all components](../README.md#components)
+
+## Usage
+
+Like autocomplete, rendering is split in two so the dropdown never reflows the
+layout — `view()` is the one-line control, `menuView()` is the overlay:
+
+```js
+const { select } = require('bare-tui')
+
+const fruit = select
+  .create({
+    options: ['apple', 'banana', 'cherry'],
+    placeholder: 'pick one'
+  })
+  .focus()
+
+// in view: draw the control, then overlay the menu where it fits
+const line = fruit.view() // always one line, stable width
+const menu = fruit.menuView() // '' when closed; rows when open
+fruit.value() // 'apple', or null while nothing is chosen
+```
+
+## Options
+
+| Option        | Default     | Description                       |
+| ------------- | ----------- | --------------------------------- |
+| `options`     | `[]`        | Strings or `{ label, value }`     |
+| `selected`    | `-1`        | Initial index (`-1` = none)       |
+| `placeholder` | `'select…'` | Shown when nothing is chosen      |
+| `maxVisible`  | `6`         | Rows before the menu scrolls      |
+| `openGlyph`   | `'▾'`       | Trailing indicator on the control |
+
+## API
+
+- `value()` — the committed value, or `null`. `selectedOption()` → `{label,value}`.
+- `setValue(v)` / `setOptions(opts)`.
+- `view()` — the closed control line. `menuView()` — the dropdown, or `''`.
+- `.open` — whether the menu is showing. `blur()` also closes it.
+
+## Keys
+
+The contract mirrors the other field controls. While **closed** it consumes only
+`space` (to open) and never `enter`, so a parent form keeps `enter` for "submit".
+While **open** it owns the menu — `↑`/`↓` move, `enter`/`space` commit, `esc`
+cancels — which is fine because a form won't submit with a menu open. Bindings
+are exported as `select.keys` for the [help](help.md) component.

package/index.js

@@ -37,10 +37,14 @@ const paginator = require('./components/paginator')
 const stopwatch = require('./components/stopwatch')
 const timer = require('./components/timer')
 const filepicker = require('./components/filepicker')
+const checkbox = require('./components/checkbox')
+const radio = require('./components/radio')
+const select = require('./components/select')
+const focus = require('./components/focus')
 
 module.exports = {
   Program,
-  ...commands, // quit, batch, sequence, tick, every
+  ...commands, // quit, batch, sequence, tick, every, suspend
   KeyMsg: messages.KeyMsg,
   key, // key.matches(msg, ...chords | bindings), key.binding({ keys, help })
   ansi,
@@ -59,5 +63,9 @@ module.exports = {
   paginator, // paginator.create({ perPage, total, type }) — page state + indicator
   stopwatch, // stopwatch.create({ interval }) — counts up; start/stop/toggle
   timer, // timer.create({ timeout, interval }) — counts down; emits timer.timeout
-  filepicker // filepicker.create({ fs, path, cwd }) — browse + pick; filepicker.mock(tree)
+  filepicker, // filepicker.create({ fs, path, cwd }) — browse + pick; filepicker.mock(tree)
+  checkbox, // checkbox.create({ label, checked }) — boolean toggle (space)
+  radio, // radio.create({ options, selected }) — single choice; value()
+  select, // select.create({ options, placeholder }) — dropdown; view() + menuView()
+  focus // focus.create({ items }) — ordered focus ring across child components
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-tui",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "A little TUI framework for Bare, based on bubbletea",
   "main": "index.js",
   "exports": {

package/program.js

@@ -62,6 +62,7 @@ module.exports = class Program {
     this._wake = null
     this._running = false
     this._tornDown = false
+    this._suspended = false // true while the terminal is handed to a child process
 
     this._decoder = null
     this._onInput = null
@@ -125,6 +126,9 @@ module.exports = class Program {
   // Mark the view dirty and schedule a render at most once per frame. Updates
   // that land in the same frame collapse into one write.
   _invalidate() {
+    // While suspended the terminal belongs to a child process; a render here
+    // would paint over it. We repaint in full on resume instead.
+    if (this._suspended) return
     if (this._frameMs === 0) {
       this.renderer.render(this._view())
       return
@@ -247,6 +251,59 @@ module.exports = class Program {
     }
   }
 
+  // Hand the terminal back to the shell: stop decoding input, drop raw mode,
+  // stop reading stdin, and leave the alt-screen. Mirrors the terminal parts of
+  // _teardown, but keeps the model and loop alive.
+  //
+  // Crucially we must NOT close stdin's fd here: a child spawned with
+  // `stdio: 'inherit'` inherits fd 0 directly, and a closed fd would hand it a
+  // dead stdin (the editor exits instantly). So we detach + pause and leave the
+  // fd open for the child.
+  _suspendTerminal() {
+    this._suspended = true
+    this._cancelFrame()
+    try {
+      if (this.input && this._onInput) this.input.removeListener('data', this._onInput)
+    } catch {}
+    try {
+      if (this._decoder && this._onKey) this._decoder.removeListener('data', this._onKey)
+    } catch {}
+    try {
+      this._decoder?.destroy()
+    } catch {}
+    this._decoder = null
+    try {
+      if (this.input && this.inputIsTTY && this.input.setRawMode) this.input.setRawMode(false)
+    } catch {}
+    try {
+      this.input?.pause?.()
+    } catch {}
+    try {
+      if (this._mouseMode) this.output.write(mouse.disable(this._mouseMode))
+    } catch {}
+    this.renderer.stop()
+  }
+
+  // Reclaim the terminal after a suspend: re-enter the screen, restore raw mode,
+  // re-attach the decoder, resume reading, and force a full repaint.
+  _resumeTerminal() {
+    this.renderer.start()
+    if (this.input) {
+      try {
+        if (this.inputIsTTY && this.input.setRawMode) this.input.setRawMode(true)
+      } catch {}
+      this._decoder = new KeyDecoder()
+      this._decoder.on('data', this._onKey)
+      this.input.on('data', this._onInput)
+      try {
+        this.input.resume?.()
+      } catch {}
+    }
+    if (this._mouseMode) this.output.write(mouse.enable(this._mouseMode))
+    this.renderer.clear() // next render repaints everything
+    this._suspended = false
+  }
+
   // Normalise update()'s return into a [model, cmd] pair. Accepts a bare model
   // (no cmd) or null (no change), so update() can be terse.
   _update(msg) {
@@ -293,6 +350,23 @@ module.exports = class Program {
       return
     }
 
+    // suspend: hand the terminal to fn() (a child process), then resume.
+    if (cmd.__suspend) {
+      this._suspendTerminal()
+      let msg = null
+      try {
+        msg = await cmd.__suspend()
+      } catch (error) {
+        msg = { type: 'error', error }
+      }
+      if (this._running) {
+        this._resumeTerminal()
+        this._invalidate() // repaint the restored screen
+      }
+      this.send(msg)
+      return
+    }
+
     try {
       this.send(await cmd())
     } catch (error) {

package/style.js

@@ -354,9 +354,12 @@ class Style {
     for (let i = 0; i < pad[0]; i++) lines.unshift(blank)
     for (let i = 0; i < pad[2]; i++) lines.push(blank)
 
-    // 4. text styling — wraps padding too so a background fills the box
+    // 4. text styling — wraps padding too so a background fills the box.
+    // Re-apply the block's SGR after every reset *inside* the content, so a
+    // background (or any attribute) covers the whole line instead of dying at
+    // the first nested span's reset and leaving the remainder unstyled.
     const open = this._open()
-    if (open) lines = lines.map((line) => open + line + RESET)
+    if (open) lines = lines.map((line) => open + line.split(RESET).join(RESET + open) + RESET)
 
     // 5. border
     if (p.border) lines = applyBorder(lines, innerW, p.border, p.borderSides, p.borderFg)
@@ -454,6 +457,7 @@ style.joinVertical = joinVertical
 style.width = width
 style.height = height
 style.truncate = truncate
+style.stripAnsi = stripAnsi
 
 module.exports = {
   style,