bare-tui 0.0.0 → 0.0.2

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/filepicker.md

@@ -0,0 +1,80 @@
+# filepicker
+
+Browse a filesystem and pick a file. Directory reads happen through commands
+(async), and the filesystem dependency is **injected** — so the framework core
+never depends on `bare-fs`, and your file UIs are trivially testable.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { filepicker } = require('bare-tui')
+
+class App {
+  constructor() {
+    this.fp = filepicker.create({ height: 14 }) // lazily requires bare-fs
+  }
+  init() {
+    return this.fp.init()
+  }
+  update(msg) {
+    if (msg.type === 'filepicker.select') {
+      /* msg.path chosen */ return [this, null]
+    }
+    const [fp, cmd] = this.fp.update(msg)
+    this.fp = fp
+    return [this, cmd]
+  }
+  view() {
+    return this.fp.view()
+  }
+}
+```
+
+## Dependency injection
+
+The component never `require`s `bare-fs`/`bare-path` at module load. You either
+pass them in, or `create()` lazily requires them — so importing the framework
+pulls in nothing, and only constructing a real filepicker loads the filesystem.
+The only surface used is `fs.readdir(dir, { withFileTypes: true }, cb)` and
+`path.join` / `path.dirname`.
+
+## Options
+
+| Option       | Default                     | Description               |
+| ------------ | --------------------------- | ------------------------- |
+| `fs`         | lazy `require('bare-fs')`   | Filesystem implementation |
+| `path`       | lazy `require('bare-path')` | Path implementation       |
+| `cwd`        | `path.resolve('.')`         | Starting directory        |
+| `height`     | `12`                        | Visible rows              |
+| `showHidden` | `false`                     | Show dotfiles             |
+
+## API
+
+- `init()` → a command that reads the starting directory.
+- `selectedPath()` — the chosen file path (once selected).
+
+## Messages
+
+- `{ type: 'filepicker.entries', dir, entries }` — a directory was read.
+- `{ type: 'filepicker.error', dir, error }` — a read failed.
+- `{ type: 'filepicker.select', path }` — a file was chosen.
+
+## Keys
+
+`↑`/`↓` (`k`/`j`) move, `enter`/`→` (`l`) open a directory or pick a file,
+`backspace`/`←` (`h`) go up.
+
+## Testing
+
+`filepicker.mock(tree)` returns an in-memory `{ fs, path, root }` from a plain
+object — keys are entry names, an object value is a directory, anything else a
+file:
+
+```js
+const m = filepicker.mock({ docs: { 'a.md': null }, 'readme.txt': null })
+const fp = filepicker.create({ fs: m.fs, path: m.path, cwd: m.root })
+```
+
+No real disk access — ideal for tests.

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/help.md

@@ -0,0 +1,45 @@
+# help
+
+Renders keybinding hints from `key.binding({ keys, help })` objects. It's a
+_view helper_, not a loop model: `view(keymap)` is called from your own `view`.
+Bindings without a `help` entry are skipped, so internal keys stay hidden.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { help, list } = require('bare-tui')
+
+const h = help.create()
+
+// short (one line) — pass any component's exported keymap:
+h.view(list.keys)
+
+// full (aligned columns) — toggle with '?', say:
+h.showAll = true
+h.view([[keys.up, keys.down], [keys.quit]])
+```
+
+A keymap can be:
+
+- an **array** of bindings (short) or array-of-arrays (full columns),
+- an **object** of bindings (its values are used), or
+- an object exposing **`shortHelp()`** / **`fullHelp()`**.
+
+## Options
+
+| Option      | Default | Description                                        |
+| ----------- | ------- | -------------------------------------------------- |
+| `showAll`   | `false` | Full multi-column help vs the one-line short form  |
+| `width`     | `0`     | Truncate the short line to this width (`0` = none) |
+| `separator` | `' • '` | Between items in short mode                        |
+| `styles`    | —       | `{ key, desc, sep }` functions to restyle parts    |
+
+## API
+
+- `view(keymap)` → the rendered hint string.
+- `setWidth(n)`.
+
+Every component that owns keys exports a `keys` keymap (`list.keys`,
+`table.keys`, `viewport.keys`, `paginator.keys`) ready to pass straight in.

package/docs/list.md

@@ -0,0 +1,47 @@
+# list
+
+A selectable, filterable list. Owns selection and a scroll window that follows
+the cursor; filtering is delegated to an embedded [textinput](textinput.md).
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { list } = require('bare-tui')
+
+const l = list.create({
+  items: ['apple', 'banana', 'cherry'],
+  height: 8,
+  title: ' fruit'
+})
+
+// in update: const [m, cmd] = l.update(msg); this.list = m
+// pick:      l.selectedItem()
+```
+
+Items can be strings or objects: `title` is shown, `filterValue` (falling back
+to `title`) is matched.
+
+## Options
+
+| Option       | Default | Description                                 |
+| ------------ | ------- | ------------------------------------------- |
+| `items`      | `[]`    | Strings or `{ title, filterValue }` objects |
+| `height`     | `10`    | Visible rows                                |
+| `width`      | `0`     | Pad rows to this width (`0` = ragged)       |
+| `title`      | `''`    | Optional heading line                       |
+| `filterable` | `true`  | Allow `/` filtering                         |
+
+## API
+
+- `selectedItem()` — the underlying item under the cursor (or `null`).
+- `setItems(items)`.
+- `.filtering` — whether the filter input is active. `.visibleCount`,
+  `.selected`, `.filter`.
+
+## Keys
+
+`↑`/`↓` (`k`/`j`) move, `pgup`/`pgdn` page, `/` enters filter mode (type to
+narrow, `enter` keeps it, `esc` clears it). Bindings are exported as `list.keys`
+for the [help](help.md) component.

package/docs/paginator.md

@@ -0,0 +1,43 @@
+# paginator
+
+Page state plus an indicator, for paging through a long collection. Holds the
+current page and page size, handles the paging keys, and offers `sliceBounds()`
+so you can carve the visible page out of your items.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { paginator } = require('bare-tui')
+
+const p = paginator.create({ perPage: 10, total: items.length, type: 'dots' })
+
+// in update: const [m] = p.update(msg); this.pager = m
+// in view:
+const [start, end] = p.sliceBounds()
+render(items.slice(start, end))
+p.view() // "●○○○○"  (dots)  or  "1/5"  (arabic)
+```
+
+## Options
+
+| Option                      | Default       | Description                            |
+| --------------------------- | ------------- | -------------------------------------- |
+| `perPage`                   | `10`          | Items per page                         |
+| `total`                     | `0`           | Total item count                       |
+| `page`                      | `0`           | Initial page (zero-indexed)            |
+| `type`                      | `'arabic'`    | `'arabic'` (`1/5`) or `'dots'` (`●○○`) |
+| `activeDot` / `inactiveDot` | `'●'` / `'○'` | Dot characters                         |
+
+## API
+
+- `sliceBounds(length?)` → `[start, end)` for the current page.
+- `itemsOnPage(length?)` — count on the current page.
+- `nextPage()` / `prevPage()` / `setPage(n)` / `setTotal(n)`.
+- `.page` / `.totalPages` / `onFirstPage()` / `onLastPage()`.
+
+## Keys
+
+`←`/`→` (`h`/`l`, `pgup`/`pgdn`) change pages. Bindings are exported as
+`paginator.keys` for the [help](help.md) component.

package/docs/progress.md

@@ -0,0 +1,36 @@
+# progress
+
+A percentage bar. Static like [help](help.md): it holds the look and
+`view(percent)` renders a bar at the given fraction. Drive the percent from your
+model (a tick, a download callback, the OTA updater).
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { progress } = require('bare-tui')
+
+const bar = progress.create({ width: 40, gradient: ['#5A56E0', '#EE6FF8'] })
+
+// in view:
+bar.view(0.42) // "████████████░░░░…  42%"
+```
+
+## Options
+
+| Option           | Default | Description                                     |
+| ---------------- | ------- | ----------------------------------------------- |
+| `width`          | `40`    | Total width including the percentage label      |
+| `full`           | `'█'`   | Filled cell character                           |
+| `empty`          | `'░'`   | Empty cell character                            |
+| `showPercentage` | `true`  | Append a ` NNN%` label (reserves 5 cells)       |
+| `color`          | `null`  | Solid fill color (name, 0–255, or `#hex`)       |
+| `gradient`       | `null`  | `[fromHex, toHex]` interpolated across the fill |
+
+## API
+
+- `view(percent)` → bar string. `percent` is `0..1` and is clamped.
+- `setWidth(n)` — e.g. on a resize message.
+
+The label slot is a fixed width, so the bar doesn't jump as the number changes.

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/docs/spinner.md

@@ -0,0 +1,54 @@
+# spinner
+
+An animated loading indicator. Command-driven: it animates by re-issuing a tick
+command each frame.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { spinner } = require('bare-tui')
+
+class App {
+  constructor() {
+    this.spinner = spinner.create({ fps: 12 })
+  }
+  init() {
+    return this.spinner.init() // start animating
+  }
+  update(msg) {
+    if (msg.type === 'spinner.tick') {
+      const [s, cmd] = this.spinner.update(msg)
+      this.spinner = s
+      return [this, cmd]
+    }
+    return [this, null]
+  }
+  view() {
+    return `${this.spinner.view()} loading…`
+  }
+}
+```
+
+## Options
+
+| Option   | Default        | Description                     |
+| -------- | -------------- | ------------------------------- |
+| `frames` | `spinner.dots` | Array of frame strings to cycle |
+| `fps`    | `10`           | Frames per second               |
+
+Frame presets: `spinner.dots`, `spinner.line`, `spinner.points`.
+
+## API
+
+- `init()` → a command that starts the animation. Call from your `init`.
+- `update(msg)` → advances on its own `spinner.tick`, returns the next tick
+  command.
+- `view()` → the current frame string.
+
+## Messages
+
+Emits and consumes `{ type: 'spinner.tick', id, tag }`. The `id` + `tag` ensure a
+second spinner's ticks (or a duplicate) can't double-drive this one — route every
+`spinner.tick` to `update` and it sorts itself out.

package/docs/stopwatch.md

@@ -0,0 +1,52 @@
+# stopwatch
+
+Counts elapsed time upward. Command-driven like the [spinner](spinner.md):
+`start()` returns a tick command, and each accepted tick advances `elapsed` and
+re-issues the next.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { stopwatch } = require('bare-tui')
+
+class App {
+  constructor() {
+    this.sw = stopwatch.create()
+  }
+  init() {
+    return this.sw.start()
+  }
+  update(msg) {
+    if (msg.type === 'stopwatch.tick') {
+      const [sw, cmd] = this.sw.update(msg)
+      this.sw = sw
+      return [this, cmd]
+    }
+    return [this, null]
+  }
+  view() {
+    return this.sw.view() // "01:23"
+  }
+}
+```
+
+## Options
+
+| Option     | Default | Description                  |
+| ---------- | ------- | ---------------------------- |
+| `interval` | `1000`  | Milliseconds per tick        |
+| `elapsed`  | `0`     | Initial elapsed milliseconds |
+
+## API
+
+- `start()` / `stop()` / `toggle()` — return a command (or `null`); thread it up.
+- `reset()` — zero `elapsed`; a running stopwatch keeps ticking.
+- `.elapsed` (ms) / `.running`.
+- `view()` → `MM:SS` (or `H:MM:SS`).
+
+## Messages
+
+Emits and consumes `{ type: 'stopwatch.tick', id, tag }`; id + tag guard against
+strays, so pause/resume can't double-drive it.

package/docs/table.md

@@ -0,0 +1,52 @@
+# table
+
+Fixed-width columns with selectable, scrolling rows. Cells are truncated/padded
+to their column width (ANSI-aware), the selection is a reverse-video bar, and the
+body scrolls in a fixed-height window.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { table } = require('bare-tui')
+
+const t = table.create({
+  columns: [
+    { title: 'Package', width: 18 },
+    { title: 'Lang', width: 5 }
+  ],
+  rows: [
+    ['corestore', 'js'],
+    ['hypercore', 'js']
+  ],
+  height: 8
+})
+
+// in update: const [m] = t.update(msg); this.table = m
+// selected:  t.selectedRow()
+```
+
+## Options
+
+| Option    | Default | Description                           |
+| --------- | ------- | ------------------------------------- |
+| `columns` | `[]`    | `{ title, width }` per column         |
+| `rows`    | `[]`    | Arrays of cell values, one per column |
+| `height`  | `10`    | Visible body rows                     |
+| `rule`    | `'─'`   | Character for the header underline    |
+
+## API
+
+- `selectedRow()` — the row array under the cursor (or `null`).
+- `setRows(rows)` / `setColumns(columns)`.
+- `gotoTop()` / `gotoBottom()`.
+- `.cursor` / `.offset` / `.totalWidth`.
+
+Renders a stable `2 + height`-row block (header, rule, body), so it sits cleanly
+inside a `style` box.
+
+## Keys
+
+`↑`/`↓` (`k`/`j`) move, `pgup`/`pgdn` page, `home`/`end` jump. Bindings are
+exported as `table.keys` for the [help](help.md) component.

package/docs/textarea.md

@@ -0,0 +1,43 @@
+# textarea
+
+A multi-line text editor. Soft-wraps to its width, scrolls a fixed-height
+window, and moves the cursor by _visual_ row (so up/down feel right inside
+wrapped text). Input-driven and focus-gated, like [textinput](textinput.md).
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { textarea } = require('bare-tui')
+
+const ta = textarea.create({ width: 60, height: 10, placeholder: 'Type…' }).focus()
+
+// in update: const [t, cmd] = ta.update(msg); this.ta = t
+// in view:   this.ta.view()
+```
+
+## Options
+
+| Option        | Default | Description                                     |
+| ------------- | ------- | ----------------------------------------------- |
+| `value`       | `''`    | Initial contents                                |
+| `width`       | `40`    | Wrap width / render width                       |
+| `height`      | `6`     | Visible rows                                    |
+| `placeholder` | `''`    | Dim text shown when empty                       |
+| `charLimit`   | `0`     | Max characters incl. newlines (`0` = unlimited) |
+| `focused`     | `false` | Start focused                                   |
+
+## API
+
+- `focus()` / `blur()`.
+- `setValue(v)` / `reset()`.
+- `setSize(width, height)` — e.g. on a resize message.
+- `.value` — the text (lines joined by `\n`). `.length` — character count.
+
+## Keys
+
+`←`/`→` move by character (wrapping across lines), `↑`/`↓` by visual row,
+`home`/`end` to the visual row's edges, `enter` splits the line, `backspace`/
+`delete` edit and merge lines, printable characters insert. Renders a
+rectangular `width × height` block, so it drops straight into a `style` box.