bare-tui 0.0.0 → 0.0.1

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

package/docs/textinput.md

@@ -0,0 +1,51 @@
+# textinput
+
+A single-line editable text field. Input-driven: no commands, just state folded
+from key messages. Only consumes keys while focused, so a parent can host several
+and route to whichever has focus.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { textinput } = require('bare-tui')
+
+class Form {
+  constructor() {
+    this.name = textinput.create({ placeholder: 'name', prompt: '> ' }).focus()
+  }
+  update(msg) {
+    const [f, cmd] = this.name.update(msg)
+    this.name = f
+    return [this, cmd]
+  }
+  view() {
+    return this.name.view()
+  }
+}
+```
+
+## Options
+
+| Option        | Default    | Description                                 |
+| ------------- | ---------- | ------------------------------------------- |
+| `value`       | `''`       | Initial text                                |
+| `placeholder` | `''`       | Dim text shown when empty                   |
+| `prompt`      | `''`       | Prefix drawn before the value (e.g. `'> '`) |
+| `charLimit`   | `0`        | Max length (`0` = unlimited)                |
+| `echoMode`    | `'normal'` | `'password'` masks the value                |
+| `maskChar`    | `'•'`      | Mask character in password mode             |
+| `focused`     | `false`    | Start focused                               |
+
+## API
+
+- `focus()` / `blur()` — toggle whether keys are consumed.
+- `setValue(v)` / `reset()` — set or clear the text.
+- `.value` — the current string.
+
+## Keys
+
+`←`/`→` move, `home`/`end` (and `ctrl+a`/`ctrl+e`) jump, `backspace`/`delete`
+edit, printable characters insert at the cursor. The field draws its own
+reverse-video cursor (the Program hides the real one).

package/docs/timer.md

@@ -0,0 +1,57 @@
+# timer
+
+Counts a duration down to zero. Command-driven like the
+[stopwatch](stopwatch.md); when it reaches zero it stops and emits a one-shot
+timeout message.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { timer } = require('bare-tui')
+
+class App {
+  constructor() {
+    this.timer = timer.create({ timeout: 10000 }) // 10s
+  }
+  init() {
+    return this.timer.start()
+  }
+  update(msg) {
+    if (msg.type === 'timer.timeout') {
+      /* done */ return [this, null]
+    }
+    if (msg.type === 'timer.tick') {
+      const [t, cmd] = this.timer.update(msg)
+      this.timer = t
+      return [this, cmd]
+    }
+    return [this, null]
+  }
+  view() {
+    return this.timer.view() // "00:09"
+  }
+}
+```
+
+## Options
+
+| Option     | Default | Description                      |
+| ---------- | ------- | -------------------------------- |
+| `timeout`  | `0`     | Initial duration in milliseconds |
+| `interval` | `1000`  | Milliseconds per tick            |
+
+## API
+
+- `start()` / `stop()` / `toggle()` — return a command (or `null`). Won't start
+  from zero.
+- `reset()` — restore the initial duration.
+- `.timeout` (ms remaining) / `.running` / `.timedOut`.
+- `view()` → `MM:SS`.
+
+## Messages
+
+Consumes `{ type: 'timer.tick', id, tag }`; on reaching zero its `update` returns
+a command that emits `{ type: 'timer.timeout', id }` — handle that to react to
+the timeout.

package/docs/viewport.md

@@ -0,0 +1,39 @@
+# viewport
+
+A scrollable window over content taller than the available space. Renders a
+fixed `height`-row window and always emits exactly that many lines (padding short
+content), so surrounding layout stays stable.
+
+[← all components](../README.md#components)
+
+## Usage
+
+```js
+const { viewport } = require('bare-tui')
+
+const vp = viewport.create({ width: 40, height: 10 })
+vp.setContent(longText)
+
+// in update: const [v] = vp.update(msg); this.vp = v
+// in view:   this.vp.view()
+```
+
+## Options
+
+| Option   | Default | Description                                        |
+| -------- | ------- | -------------------------------------------------- |
+| `width`  | `0`     | Truncate lines to this width (`0` = no truncation) |
+| `height` | `0`     | Visible rows                                       |
+
+## API
+
+- `setContent(string)` — set the scrollable text.
+- `scrollUp(n)` / `scrollDown(n)` / `gotoTop()` / `gotoBottom()` /
+  `setYOffset(n)`.
+- `.atTop` / `.atBottom` / `.scrollPercent` / `.maxOffset` / `.yOffset`.
+
+## Keys
+
+`↑`/`↓` (`k`/`j`) by line, `pgup`/`pgdn` (`b`/`f`) by page, `ctrl+u`/`ctrl+d`
+half-page, `home`/`end` to the ends. Bindings are exported as `viewport.keys`
+for the [help](help.md) component.

package/index.d.ts

@@ -0,0 +1 @@
+declare module '@holepunchto/bare-tui'

package/index.js

@@ -0,0 +1,63 @@
+// tea — a tiny Elm Architecture runtime for Bare terminals.
+//
+// Built on Bare's native primitives (bare-tty for raw IO + window size,
+// bare-ansi-escapes for key decoding and escape sequences), so it runs
+// anywhere Bare runs and pulls in no Node-only dependencies. The API is shaped
+// after Charm's Bubble Tea (Model/Cmd/Msg/Program) with the intent of growing
+// into a drop-out framework.
+//
+//   const { Program, quit } = require('./lib/tea')
+//
+//   class App {
+//     init() { return null }
+//     update(msg) {
+//       if (msg.type === 'key' && String(msg) === 'q') return [this, quit]
+//       return [this, null]
+//     }
+//     view() { return 'press q to quit' }
+//   }
+//
+//   new Program(new App()).run()
+const Program = require('./program')
+const commands = require('./commands')
+const messages = require('./messages')
+const key = require('./key')
+const ansi = require('./ansi')
+const { style } = require('./style')
+const spinner = require('./components/spinner')
+const textinput = require('./components/textinput')
+const autocomplete = require('./components/autocomplete')
+const textarea = require('./components/textarea')
+const viewport = require('./components/viewport')
+const list = require('./components/list')
+const table = require('./components/table')
+const help = require('./components/help')
+const progress = require('./components/progress')
+const paginator = require('./components/paginator')
+const stopwatch = require('./components/stopwatch')
+const timer = require('./components/timer')
+const filepicker = require('./components/filepicker')
+
+module.exports = {
+  Program,
+  ...commands, // quit, batch, sequence, tick, every
+  KeyMsg: messages.KeyMsg,
+  key, // key.matches(msg, ...chords | bindings), key.binding({ keys, help })
+  ansi,
+  style, // style().bold().border(style.borders.rounded).render(...) + style.joinHorizontal/Vertical
+
+  // Components — each a composable { init?, update, view } model.
+  spinner, // spinner.create({ frames, fps })
+  textinput, // textinput.create({ placeholder, prompt, charLimit, echoMode })
+  autocomplete, // autocomplete.create({ prompt, placeholder, suggestions, trigger }) — input + suggestion menu
+  textarea, // textarea.create({ width, height, placeholder, charLimit }) — multi-line
+  viewport, // viewport.create({ width, height }) — scrollable window
+  list, // list.create({ items, height, width, title }) — selectable + filterable
+  table, // table.create({ columns, rows, height }) — selectable scrolling rows
+  help, // help.create() — renders keybinding hints; view(keymap)
+  progress, // progress.create({ width, gradient }) — view(percent)
+  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)
+}