docs(readme): fill out minimum docs and clarify stability
Make the README self-sufficient as minimum docs while preserving the existing narrative and structure: - Replace the blanket "not for production" notice with a stability line that distinguishes the runtime (API stabilizing) from the still experimental CLI / dev toolkit; mirror this in the Packages table. - Tighten the dev-toolkit bullet to match the CLI's actual surface (`vue-tui dev`), which only implements the dev command. - Add an "Add to an existing project" install step (`@vue-tui/runtime`). - Document the public runtime exports the README was missing, matching the coverage of Ink v7.0.4's README: renderToString, useIsScreenReaderEnabled, and measureElement (kittyFlags/kittyModifiers stay undocumented, as in Ink's README). Correct the useBoxMetrics row to its actual return shape.
This commit is contained in:
Yunfei He
@@ -1,6 +1,6 @@
|
||||
# vue-tui
|
||||
|
||||
> **Early stage** — under active development. Bug reports welcome, but not recommended for production use yet.
|
||||
> **Status** — the runtime API is stabilizing; the CLI and dev toolkit are still experimental and may change. Bug reports welcome.
|
||||
|
||||
The Vue framework for terminal UIs.
|
||||
Build with components, develop with HMR, test with confidence.
|
||||
@@ -11,7 +11,7 @@ Build with components, develop with HMR, test with confidence.
|
||||
|
||||
- **Vue SFC & JSX** — write terminal interfaces with `<template>`, TSX, or both
|
||||
- **Flexbox layout** — powered by Yoga, the same engine behind React Native
|
||||
- **Dev toolkit** _(experimental)_ — **HMR** in the terminal, plus build and preview out of the box
|
||||
- **Dev toolkit** _(experimental)_ — **HMR** in the terminal via `vue-tui dev`
|
||||
- **Input & focus** — keyboard handling, focus management, Tab navigation, Kitty keyboard protocol
|
||||
- **Testing harness** — out-of-the-box component-level terminal testing — render, simulate input, assert frames
|
||||
|
||||
@@ -34,6 +34,12 @@ npm run dev
|
||||
|
||||
Edit `app.vue` and watch the terminal update instantly.
|
||||
|
||||
### Add to an existing project
|
||||
|
||||
```bash
|
||||
npm install @vue-tui/runtime
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```ts
|
||||
@@ -67,6 +73,8 @@ useInput((input) => {
|
||||
</template>
|
||||
```
|
||||
|
||||
For non-interactive output — snapshots, CI logs, piped commands — `renderToString(App)` renders a single frame to a string instead of mounting.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Quick Start](#quick-start)
|
||||
@@ -83,11 +91,11 @@ useInput((input) => {
|
||||
|
||||
## Packages
|
||||
|
||||
| Package | Description |
|
||||
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [`@vue-tui/runtime`](https://www.npmjs.com/package/@vue-tui/runtime) | The core framework — Vue 3 renderer for the terminal with components (`Box`, `Text`, `Static`, etc.), composables (`useInput`, `useFocus`, `useApp`, etc.), and yoga-based flexbox layout |
|
||||
| [`@vue-tui/cli`](https://www.npmjs.com/package/@vue-tui/cli) | Development tool — `vue-tui dev` starts your app with Vite-powered HMR |
|
||||
| [`@vue-tui/testing`](https://www.npmjs.com/package/@vue-tui/testing) | Test harness — render in an isolated fake terminal, simulate input, assert output frame by frame |
|
||||
| Package | Description |
|
||||
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [`@vue-tui/runtime`](https://www.npmjs.com/package/@vue-tui/runtime) | The core framework — Vue 3 renderer for the terminal with components (`Box`, `Text`, `Static`, etc.), composables (`useInput`, `useFocus`, `useApp`, etc.), and yoga-based flexbox layout. _API stabilizing._ |
|
||||
| [`@vue-tui/cli`](https://www.npmjs.com/package/@vue-tui/cli) | Development tool — `vue-tui dev` starts your app with Vite-powered HMR. _Experimental; may change._ |
|
||||
| [`@vue-tui/testing`](https://www.npmjs.com/package/@vue-tui/testing) | Test harness — render in an isolated fake terminal, simulate input, assert output frame by frame |
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -111,20 +119,21 @@ useInput((input) => {
|
||||
|
||||
## Composables (Hooks)
|
||||
|
||||
| Composable | Description |
|
||||
| -------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| `useInput(handler, opts?)` | Handle keyboard input — receives `(input, key)` with modifier and arrow key detection |
|
||||
| `usePaste(handler, opts?)` | Handle bracketed paste — receives the pasted `text` as a single event |
|
||||
| `useFocus(opts?)` | Component-level focus — returns `{ isFocused, focus }` |
|
||||
| `useFocusManager()` | App-level focus control — `focusNext()`, `focusPrevious()`, `focus(id)` |
|
||||
| `useApp()` | App lifecycle — `{ exit(error?), waitUntilRenderFlush() }` |
|
||||
| `useWindowSize()` | Reactive terminal dimensions — `{ columns, rows }` |
|
||||
| `useStdin()` | Access stdin stream and raw mode control |
|
||||
| `useStdout()` | Write directly to stdout |
|
||||
| `useStderr()` | Write directly to stderr |
|
||||
| `useBoxMetrics(ref)` | Measure a `<Box>` via a template ref — reactive `{ width, height, left, top }` |
|
||||
| `useCursor()` | Control the terminal cursor — `setCursorPosition(pos)` in output coordinates |
|
||||
| `useAnimation(opts?)` | Frame-based animation driver — reactive `{ frame, time, delta }` + `reset()` |
|
||||
| Composable | Description |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `useInput(handler, opts?)` | Handle keyboard input — receives `(input, key)` with modifier and arrow key detection |
|
||||
| `usePaste(handler, opts?)` | Handle bracketed paste — receives the pasted `text` as a single event |
|
||||
| `useFocus(opts?)` | Component-level focus — returns `{ isFocused, focus }` |
|
||||
| `useFocusManager()` | App-level focus control — `focusNext()`, `focusPrevious()`, `focus(id)` |
|
||||
| `useApp()` | App lifecycle — `{ exit(error?), waitUntilRenderFlush() }` |
|
||||
| `useWindowSize()` | Reactive terminal dimensions — `{ columns, rows }` |
|
||||
| `useStdin()` | Access stdin stream and raw mode control |
|
||||
| `useStdout()` | Write directly to stdout |
|
||||
| `useStderr()` | Write directly to stderr |
|
||||
| `useBoxMetrics(ref)` | Measure a `<Box>` via a template ref — reactive `{ width, height, left, top, hasMeasured }` (or `measureElement(el)` for a one-off `{ width, height }` read) |
|
||||
| `useCursor()` | Control the terminal cursor — `setCursorPosition(pos)` in output coordinates |
|
||||
| `useIsScreenReaderEnabled()` | Whether a screen reader is active — returns a boolean for adapting accessible output |
|
||||
| `useAnimation(opts?)` | Frame-based animation driver — reactive `{ frame, time, delta }` + `reset()` |
|
||||
|
||||
## Testing
|
||||
|
||||
|
||||
Reference in New Issue
Block a user