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
|
# 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.
|
The Vue framework for terminal UIs.
|
||||||
Build with components, develop with HMR, test with confidence.
|
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
|
- **Vue SFC & JSX** — write terminal interfaces with `<template>`, TSX, or both
|
||||||
- **Flexbox layout** — powered by Yoga, the same engine behind React Native
|
- **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
|
- **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
|
- **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.
|
Edit `app.vue` and watch the terminal update instantly.
|
||||||
|
|
||||||
|
### Add to an existing project
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install @vue-tui/runtime
|
||||||
|
```
|
||||||
|
|
||||||
## Example
|
## Example
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
@@ -67,6 +73,8 @@ useInput((input) => {
|
|||||||
</template>
|
</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
|
## Table of Contents
|
||||||
|
|
||||||
- [Quick Start](#quick-start)
|
- [Quick Start](#quick-start)
|
||||||
@@ -83,11 +91,11 @@ useInput((input) => {
|
|||||||
|
|
||||||
## Packages
|
## Packages
|
||||||
|
|
||||||
| Package | Description |
|
| 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/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 |
|
| [`@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 |
|
| [`@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
|
## Examples
|
||||||
|
|
||||||
@@ -111,20 +119,21 @@ useInput((input) => {
|
|||||||
|
|
||||||
## Composables (Hooks)
|
## Composables (Hooks)
|
||||||
|
|
||||||
| Composable | Description |
|
| Composable | Description |
|
||||||
| -------------------------- | ------------------------------------------------------------------------------------- |
|
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||||
| `useInput(handler, opts?)` | Handle keyboard input — receives `(input, key)` with modifier and arrow key detection |
|
| `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 |
|
| `usePaste(handler, opts?)` | Handle bracketed paste — receives the pasted `text` as a single event |
|
||||||
| `useFocus(opts?)` | Component-level focus — returns `{ isFocused, focus }` |
|
| `useFocus(opts?)` | Component-level focus — returns `{ isFocused, focus }` |
|
||||||
| `useFocusManager()` | App-level focus control — `focusNext()`, `focusPrevious()`, `focus(id)` |
|
| `useFocusManager()` | App-level focus control — `focusNext()`, `focusPrevious()`, `focus(id)` |
|
||||||
| `useApp()` | App lifecycle — `{ exit(error?), waitUntilRenderFlush() }` |
|
| `useApp()` | App lifecycle — `{ exit(error?), waitUntilRenderFlush() }` |
|
||||||
| `useWindowSize()` | Reactive terminal dimensions — `{ columns, rows }` |
|
| `useWindowSize()` | Reactive terminal dimensions — `{ columns, rows }` |
|
||||||
| `useStdin()` | Access stdin stream and raw mode control |
|
| `useStdin()` | Access stdin stream and raw mode control |
|
||||||
| `useStdout()` | Write directly to stdout |
|
| `useStdout()` | Write directly to stdout |
|
||||||
| `useStderr()` | Write directly to stderr |
|
| `useStderr()` | Write directly to stderr |
|
||||||
| `useBoxMetrics(ref)` | Measure a `<Box>` via a template ref — reactive `{ width, height, left, top }` |
|
| `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 |
|
| `useCursor()` | Control the terminal cursor — `setCursorPosition(pos)` in output coordinates |
|
||||||
| `useAnimation(opts?)` | Frame-based animation driver — reactive `{ frame, time, delta }` + `reset()` |
|
| `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
|
## Testing
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user