# @teaui/react
React custom renderer for [TeaUI](https://github.com/colinta/teaui). Write fullscreen terminal UIs with React components, hooks, and JSX.
## Install
```bash
pnpm install @teaui/core @teaui/react react
# TypeScript users:
pnpm install -D @types/react
```
## Usage
```tsx
import React, {useReducer} from 'react'
import {interceptConsoleLog} from '@teaui/core'
import {Box, Button, Stack, run} from '@teaui/react'
interceptConsoleLog()
function App() {
const [bang, addBang] = useReducer(s => s + '!', '')
return (
Hello TeaUI{bang}
)
}
run()
```
Compile and run:
```bash
pnpm tsc && node .dist/index.js
```
## API
### `run(element, options?)`
Creates a `Window` and `Screen`, renders the React element tree, and enters fullscreen mode.
```ts
const [screen, window, component, unmount] = await run()
```
Returns `[Screen, Window, ReactNode, unmount]`. Call `unmount()` to tear down the React tree.
### `render(screen, window, element)`
Lower-level alternative — mount a React element into an existing `Screen` and `Window`.
```ts
import {Screen, Window} from '@teaui/core'
import {render} from '@teaui/react'
const window = new Window()
const [screen] = await Screen.start(window)
const unmount = render(screen, window, )
```
Returns an `unmount()` function.
## Components
All components are typed wrappers around TeaUI core views. They accept the same props as the core constructors, with `children` mapped to React children.
### Views (leaf nodes)
| Component | Element | Description |
| --------------------- | ------------------------ | ---------------------------------------- |
| `
` | `` | Line break in text |
| `` | `` | Toggle checkbox |
| `` | `` | Text that truncates with expand/collapse |
| `` | `` | Displays intercepted `console.*` output |
| `` | `` | Large-font digit display |
| ``–`` | ``–`` | Header text |
| `` | `` | Text input field |
| `` | `` | Horizontal or vertical line |
| `` | `` | Value slider |
| `` | `` | Empty spacer |
| `` | `` | Group of toggle options |
`Separator` has `.horizontal` and `.vertical` variants. `Slider` has `.horizontal` and `.vertical` variants.
### Containers
| Component | Element | Description |
| ----------------- | ------------------- | ------------------------------------------------- |
| `` | `` | Box with optional border and padding |
| `` | `` | Clickable button |
| `` | `` | Toggle between `collapsed` and `expanded` content |
| `` | `` | Scrollable content region |
| `` | `` | Linear layout |
| `` | `` | Text container (sets font, alignment, wrap) |
| `` | `` | Inline text styles (bold, italic, etc.) |
`Stack` has `.down`, `.up`, `.left`, and `.right` variants.
### Complex Containers
| Component | Element | Description |
| ----------------------- | ------------------------- | --------------------------------- |
| `` | `` | Expandable section group |
| `` | `` | Section within an accordion |
| `` | `` | Panel that slides in from an edge |
| `` | `` | Tabbed container |
| `` | `` | Tab within tabs |
| `` | `` | Tree view with expandable nodes |
`Drawer` has `.top`, `.right`, `.bottom`, and `.left` variants. Each accepts `content` and `drawer` props for the two panes.
### Intrinsic Elements
You can also use the `tui-` prefixed JSX elements directly:
```tsx
Hello
```
## Text Handling
React string literals are rendered as `TextLiteral` nodes, which are automatically grouped into `TextContainer`s for layout:
```tsx
hello {/* TextLiteral → TextContainer #1 */}
{/* TextLiteral → TextContainer #1 */}
{/* Box breaks the text group */}
goodbye {/* TextLiteral → TextContainer #2 */}
```
Use `` to control font, alignment, and word wrap. Use ` text.
```
## React Features
| Feature | Status |
| --------------------------------------------------- | ------------------------------------------------ |
| Hooks (`useState`, `useReducer`, `useEffect`, etc.) | ✅ Works |
| Context (`useContext`, providers) | ✅ Works |
| Refs (`useRef`, callback refs) | ✅ Works |
| Suspense | ✅ Supported (timeouts delegate to `setTimeout`) |
| Portals | ⚠️ No-op (doesn't crash, but no portal behavior) |
| Error Boundaries | Not yet supported |
## Tests
```bash
pnpm test # run once
pnpm test:watch # watch mode
```
Tests use [vitest](https://vitest.dev/) and cover:
- **`isSame.test.ts`** — Deep equality comparisons (primitives, arrays, Sets, Maps, Dates, objects, React fiber nodes)
- **`reconciler.test.ts`** — Rendering, child manipulation, text node grouping, updates, refs, unmount
- **`components.test.ts`** — All component wrappers render the correct view types; Drawer variants pass `content`/`drawer` props
## Architecture
```
@teaui/react
├── lib/
│ ├── index.ts # Re-exports reconciler + components
│ ├── reconciler.ts # react-reconciler host config, render(), run()
│ ├── isSame.ts # Deep equality for prepareUpdate
│ ├── components.tsx # Typed React wrappers + JSX IntrinsicElements
│ └── components/
│ └── TextReact.ts # TextLiteral, TextContainer, TextProvider, TextStyle
├── tests/
│ ├── isSame.test.ts
│ ├── reconciler.test.tsx
│ └── components.test.tsx
└── vitest.config.ts
```
**`reconciler.ts`** implements the `react-reconciler` host config. It maps JSX element types to TeaUI view constructors in `createInstance`, manages the view tree via `appendChild`/`removeChild`/`insertBefore`, and applies prop updates via `commitUpdate` (which calls `view.update()`). Text string children become `TextLiteral` instances. The `prepareUpdate` function uses `isSame` to diff old and new props — if anything changed, `commitUpdate` passes the full new props to the view.
**`components/TextReact.ts`** defines the text rendering architecture. Adjacent `TextLiteral` nodes are grouped into a `TextContainer`, which handles layout. `TextProvider` (``) sets text properties (font, alignment, wrap) for descendant text. `TextStyle` (`