bare-tui 0.0.0 → 0.0.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+Copyright 2026 Holepunch Inc
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,261 @@
+# bare-tui
+
+A little TUI framework for [Bare](https://github.com/holepunchto/bare), based on [The Elm Architecture](https://guide.elm-lang.org/architecture/). It's a functional, stateful way to build terminal apps that's pleasant for both simple and complex programs — and it runs anywhere Bare runs, with no Node.js dependencies.
+
+It's designed for AI. You should be able to point your agent to [CLAUDE.md](CLAUDE.md) and instruct it to build out your UI. That's how the mock claude code example was built.
+
+![Mock Claude Code](assets/mock-claude.gif)
+
+> [!NOTE]  
+> This an experimental library. A version 1.0.0 release will signal stability.
+
+bare-tui is shaped after Charm's wonderful [Bubble Tea](https://github.com/charmbracelet/bubbletea); if you know that, you already know this. It ships its own component set (the [Bubbles](https://github.com/charmbracelet/bubbles) equivalent) and a styling/layout helper (the [Lip Gloss](https://github.com/charmbracelet/lipgloss) equivalent), all built on Bare's native primitives (`bare-tty`, `bare-ansi-escapes`).
+
+> The snippets below import `require('bare-tui')`. Inside this repo's own `examples/` and `test/`, that's a relative `require('..')`.
+
+## Tutorial
+
+This tutorial assumes you have [Bare](https://bare.pears.com) installed. We'll build a simple counter.
+
+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.
+- **`view`** — a function that renders the model to a string.
+
+### The Model
+
+Start with a model — anything that holds your app's state. A class is idiomatic:
+
+```js
+const { Program, quit, key } = require('bare-tui')
+
+class Counter {
+  constructor() {
+    this.count = 0
+  }
+}
+```
+
+### Initialization
+
+`init` returns the first **command** to run, or `null` for none. Commands are how you kick off work (timers, I/O); more on them below.
+
+```js
+init() {
+  return null
+}
+```
+
+### The Update Method
+
+`update` is called when a **message** arrives. A message is any tagged value — a keypress, a window resize, the result of a command. It returns a `[model, command]` pair (returning a bare model means "no command").
+
+```js
+update(msg) {
+  if (msg.type !== 'key') return [this, null]
+  if (key.matches(msg, 'q', 'ctrl+c')) return [this, quit]   // quit the program
+  if (key.matches(msg, 'up', 'k')) this.count++
+  if (key.matches(msg, 'down', 'j')) this.count--
+  return [this, null]
+}
+```
+
+Mutating `this` and returning `[this, cmd]` is the idiomatic style here.
+
+### The View Method
+
+`view` renders the current model to a string. bare-tui draws it for you and only repaints the lines that changed.
+
+```js
+view() {
+  return `count: ${this.count}\n\n↑/↓ change · q quit`
+}
+```
+
+### All Together Now
+
+```js
+const { Program, quit, key } = require('bare-tui')
+
+class Counter {
+  constructor() {
+    this.count = 0
+  }
+  init() {
+    return null
+  }
+  update(msg) {
+    if (msg.type !== 'key') return [this, null]
+    if (key.matches(msg, 'q', 'ctrl+c')) return [this, quit]
+    if (key.matches(msg, 'up', 'k')) this.count++
+    if (key.matches(msg, 'down', 'j')) this.count--
+    return [this, null]
+  }
+  view() {
+    return `count: ${this.count}\n\n↑/↓ change · q quit`
+  }
+}
+
+new Program(new Counter()).run()
+```
+
+Run it with `bare counter.js`. The `Program` puts the terminal into raw mode, enters the alternate screen, decodes input into messages, and — importantly — restores the terminal on exit, even if your code throws.
+
+## Commands
+
+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, 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:
+
+```js
+const load = () =>
+  fetch(url)
+    .then((res) => res.json())
+    .then((data) => ({ type: 'loaded', data }))
+```
+
+Return commands from `init` or `update`; the result comes back as a message.
+
+## Key & mouse input
+
+Keys arrive as `{ type: 'key' }` messages (a `KeyMsg`). Match them with `key.matches`, which is null- and type-safe:
+
+```js
+if (key.matches(msg, 'enter')) ...
+if (key.matches(msg, 'ctrl+c', 'q')) ...
+```
+
+Define reusable, self-documenting bindings with `key.binding` — the [help](docs/help.md) component renders them automatically:
+
+```js
+const keys = {
+  up: key.binding({ keys: ['up', 'k'], help: { key: '↑/k', desc: 'up' } })
+}
+```
+
+Enable the mouse with a Program option; clicks/scroll/drag arrive as `{ type: 'mouse', action, button, x, y }`:
+
+```js
+new Program(model, { mouse: true }) //  true | 'drag' | 'all'
+```
+
+## Components
+
+Ready-made, composable pieces — each is a model (`update`/`view`) you embed in your own. See each doc for options, methods, messages, and keybindings.
+
+| Component                            | Description                             |
+| ------------------------------------ | --------------------------------------- |
+| [spinner](docs/spinner.md)           | Animated loading indicator              |
+| [textinput](docs/textinput.md)       | Single-line text field                  |
+| [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                  |
+| [progress](docs/progress.md)         | Progress bar                            |
+| [help](docs/help.md)                 | Keybinding hints from `key.binding`s    |
+| [stopwatch](docs/stopwatch.md)       | Counts elapsed time up                  |
+| [timer](docs/timer.md)               | Counts a duration down                  |
+| [filepicker](docs/filepicker.md)     | Browse the filesystem and pick a file   |
+
+To embed one, hold it as a field, route messages to it, and thread its command back up:
+
+```js
+update(msg) {
+  if (msg.type === 'spinner.tick') {
+    const [s, cmd] = this.spinner.update(msg)
+    this.spinner = s
+    return [this, cmd]
+  }
+  ...
+}
+```
+
+## Styling & layout
+
+`style` is a small, chainable, immutable styling and layout helper (a Lip Gloss equivalent). All measurement is ANSI- and wide-character-aware, so styled text composes correctly.
+
+```js
+const { style } = require('bare-tui')
+
+style()
+  .bold(true)
+  .foreground('cyan') // name, 0–255, or #hex
+  .padding(1, 2)
+  .border(style.borders.rounded)
+  .borderForeground('blue')
+  .render('Hello')
+
+// Layout: place blocks side by side or stacked.
+style.joinHorizontal(style.position.top, left, '  ', right)
+style.joinVertical(style.position.left, header, body, footer)
+```
+
+Set `.width(n)` to pin a block to a fixed width (short/blank lines pad out, so a bordered box tracks the screen edge instead of shrinking to its content).
+
+## Testing
+
+bare-tui is built to be tested headlessly — no real terminal, no real I/O.
+
+- **Drive a Program** with injected streams: pass `{ input, output, isTTY: true }` (a `bare-stream` `PassThrough` and a capturing `Writable`), write key bytes to `input`, `await program.run()`, and assert on the captured output. Use `{ fps: 0 }` to render synchronously per update for deterministic frames.
+- **Mock dependencies**: components that touch the outside world take their deps by injection. For example `filepicker.mock(tree)` returns an in-memory `{ fs, path }` so you can test a file browser with zero disk access.
+- **Unit-test components** by calling `update(msg)` and asserting on state or `view()`. `style.stripAnsi(view)` gives you the visible text.
+
+## Examples
+
+Runnable, one per concept, in [`examples/`](examples):
+
+`counter` · `form` · `controls` · `list` · `table` · `dashboard` · `pager` ·
+`progress` · `paginator` · `mouse` · `textarea` · `timer` · `filepicker` ·
+`claude-code`
+
+```sh
+bare examples/dashboard.js
+```
+
+## Building your own component
+
+Components are just models, so you can build your own and they'll compose like the built-ins. Keep to the conventions the built-ins follow — a `create()` factory, `update → [model, cmd]` / `view → string`, ignore unrelated messages, gate input on a `focused` flag, define keymaps with `key.binding`, stay style-agnostic, and do animation/I/O through commands (with an injectable, mockable dependency). The shipped components are short and meant to be read; copy the closest one. The `tea-tui` skill in this repo walks through it in detail.
+
+## Acknowledgments
+
+Deeply indebted to [Charm](https://charm.sh) — bare-tui is a port of the ideas in [Bubble Tea](https://github.com/charmbracelet/bubbletea), [Bubbles](https://github.com/charmbracelet/bubbles), and [Lip Gloss](https://github.com/charmbracelet/lipgloss) to the Bare runtime. Built on [Bare](https://github.com/holepunchto/bare) by [Holepunch](https://holepunch.to).
+
+## Logo
+
+![tui-bird](assets/tui-bird.png)
+
+A Tui bird of New Zealand
+
+## License
+
+Apache-2.0

package/ansi.js

@@ -0,0 +1,34 @@
+// ANSI helpers for the tea runtime.
+//
+// We build on `bare-ansi-escapes` (cursor/erase/color + the KeyDecoder) and add
+// the few sequences it doesn't ship: alternate screen, absolute cursor
+// addressing and mouse tracking. Keeping them here means the renderer and
+// program never hand-roll escape codes.
+const ansi = require('bare-ansi-escapes')
+const {
+  constants: { CSI, SGR }
+} = ansi
+
+module.exports = {
+  ...ansi,
+
+  // Absolute cursor move (0-indexed row/col). bare-ansi-escapes' cursorPosition
+  // has a column-first signature and treats row 0 as "stay", which is awkward
+  // for a renderer that thinks in (row, col), so we expose our own.
+  cursorTo: (row = 0, col = 0) => CSI + (row + 1) + ';' + (col + 1) + 'H',
+  home: CSI + 'H',
+
+  // Reverse video — used to draw a cursor cell when the real terminal cursor is
+  // hidden (e.g. inside a text input).
+  modifierReverse: SGR(7),
+  modifierNotReverse: SGR(27),
+
+  // Alternate screen buffer — gives the app its own full screen and restores
+  // the user's scrollback untouched on exit.
+  enterAltScreen: CSI + '?1049h',
+  leaveAltScreen: CSI + '?1049l',
+
+  // SGR mouse tracking (button events + SGR extended coordinates).
+  enableMouse: CSI + '?1000h' + CSI + '?1006h',
+  disableMouse: CSI + '?1006l' + CSI + '?1000l'
+}

package/commands.js

@@ -0,0 +1,67 @@
+// Commands (Cmd) are how a model asks the runtime to perform a side effect
+// without doing it inline. A Cmd is just `() => Msg | Promise<Msg> | null`: the
+// runtime calls it off the update path and feeds whatever Msg it returns back
+// into update(). This keeps update() pure and makes async work (timers, IO,
+// worker IPC) testable.
+//
+// update() returns `[model, cmd]`. `cmd` may be a single Cmd, an array of Cmds
+// (run concurrently — see batch), a sequence marker (run in order — see
+// sequence), or null for "do nothing".
+const { quitMsg } = require('./messages')
+
+// `quit` is itself a Cmd: return it from update() to tear down and exit, e.g.
+//   return [model, quit]
+function quit() {
+  return quitMsg()
+}
+
+// Run several Cmds concurrently. The runtime expands arrays, so batch is just a
+// null-filtering spread — but naming it documents intent at the call site.
+function batch(...cmds) {
+  return cmds.flat().filter(Boolean)
+}
+
+// Run several Cmds one after another, waiting for each to resolve before
+// starting the next. The runtime recognises the `__seq` marker.
+function sequence(...cmds) {
+  return { __seq: cmds.flat().filter(Boolean) }
+}
+
+// Resolve to a Msg after `ms`, measured from when the Cmd runs. `fn(date)` maps
+// the fire time to a Msg; pass no fn for a plain timer. Re-issue it from
+// update() to repeat. Use this for relative delays / debounces.
+function tick(ms, fn) {
+  return () =>
+    new Promise((resolve) => {
+      setTimeout(() => resolve(fn ? fn(new Date()) : null), ms)
+    })
+}
+
+// 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.
+function every(ms, fn) {
+  return () =>
+    new Promise((resolve) => {
+      const delay = ms - (Date.now() % ms)
+      setTimeout(() => resolve(fn ? fn(new Date()) : null), delay)
+    })
+}
+
+module.exports = { quit, batch, sequence, tick, every, suspend }