Yunfei He
ff82f6e064
Custom Vue 3 renderer for terminal UIs, built on yoga-layout for flexbox and chalk for styling. Components: Box, Text, Newline, Spacer, Static, Transform Composables: useExit, useInput, useFocus, useFocusManager, useStdin, useStdout, useStderr, useTerminalSize Entry: createApp(root) → app.mount(options) → app.waitUntilExit() Focus: Ink-aligned Tab/Shift+Tab/Escape with Focusable[] ring Internal subpath: @vue-tui/runtime/internal (yogaNodeTracker) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
108 lines
3.1 KiB
Markdown
108 lines
3.1 KiB
Markdown
# @vue-tui/runtime
|
|
|
|
Vue-idiomatic terminal renderer in the spirit of [React Ink](https://github.com/vadimdemedes/ink). Platform-specific runtime parallel to `@vue/runtime-dom`.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
pnpm add @vue-tui/runtime vue
|
|
```
|
|
|
|
## Quickstart
|
|
|
|
```ts
|
|
import { defineComponent, h, ref } from "vue";
|
|
import { createApp, Box, Text, useInput } from "@vue-tui/runtime";
|
|
|
|
const Counter = defineComponent({
|
|
setup() {
|
|
const count = ref(0);
|
|
useInput((input) => {
|
|
if (input === "+") count.value++;
|
|
if (input === "-") count.value--;
|
|
});
|
|
return () => h(Box, null, h(Text, null, `Count: ${count.value}`));
|
|
},
|
|
});
|
|
|
|
createApp(Counter).mount();
|
|
```
|
|
|
|
## API
|
|
|
|
Single entry point — `createApp(root, rootProps?)`. Returns a `TuiApp` (`Omit<VueApp<TuiNode>, "mount">` plus four TUI methods).
|
|
|
|
```ts
|
|
import { createApp } from "@vue-tui/runtime";
|
|
|
|
const app = createApp(App, { initialState }).use(myPlugin).provide(themeKey, dark);
|
|
|
|
app.mount(); // all defaults (process.*)
|
|
app.mount({ debug: true }); // just flags
|
|
app.mount({ stdout: customWritable }); // partial stream override
|
|
app.mount({ stdout, stdin, stderr }); // explicit streams (testing)
|
|
|
|
await app.waitUntilExit();
|
|
app.unmount(); // optional — see "Cleanup" below
|
|
```
|
|
|
|
### Cleanup
|
|
|
|
`mount()` registers a `process.on("exit")` listener that runs the same teardown
|
|
as `unmount()`. So you only need `app.unmount()` if you want to tear down the
|
|
app before the process is ready to exit (mid-program, in tests, or when one
|
|
process hosts multiple UIs sequentially). For a normal CLI that exits when the
|
|
user quits or the script ends, cleanup happens automatically.
|
|
|
|
### `TuiApp` interface
|
|
|
|
```ts
|
|
interface TuiApp extends VueApp<TuiNode> {
|
|
mount(options?: MountOptions): ComponentPublicInstance;
|
|
unmount(): void;
|
|
waitUntilExit(): Promise<void>;
|
|
}
|
|
|
|
interface MountOptions {
|
|
stdout?: NodeJS.WriteStream; // default: process.stdout
|
|
stdin?: NodeJS.ReadStream; // default: process.stdin
|
|
stderr?: NodeJS.WriteStream; // default: process.stderr
|
|
debug?: boolean; // default: false
|
|
exitOnCtrlC?: boolean; // default: true
|
|
}
|
|
```
|
|
|
|
All fields optional with per-field fallback. Matches Ink's `RenderOptions` shape.
|
|
|
|
### Components
|
|
|
|
`Box`, `Text`, `Newline`, `Spacer`, `Static`, `Transform`.
|
|
|
|
### Composables
|
|
|
|
`useExit`, `useInput`, `useFocus`, `useFocusManager`, `useStdin`, `useStdout`, `useStderr`, `useTerminalSize`.
|
|
|
|
Tab / Shift+Tab / Escape are handled automatically when any component uses `useFocus`. `useFocus` returns `{ isFocused, focus }` and manages raw mode. `useFocusManager` exposes `activeId` in addition to `focusNext` / `focusPrevious` / `focus` / `enableFocus` / `disableFocus`.
|
|
|
|
## Waiting on exit / handling errors
|
|
|
|
```ts
|
|
// Fire-and-forget (most common):
|
|
createApp(App).mount();
|
|
|
|
// Wait for the app to exit:
|
|
const app = createApp(App);
|
|
app.mount();
|
|
await app.waitUntilExit();
|
|
|
|
// Catch errors thrown from setup / render / useExit(err):
|
|
const app = createApp(App);
|
|
app.mount();
|
|
app.waitUntilExit().catch((err) => {
|
|
console.error(err);
|
|
process.exitCode = 1;
|
|
});
|
|
```
|
|
|
|
See `docs/superpowers/specs/2026-05-18-vue-tui-core-design.md` for the full design.
|