@@ -1,14 +1,81 @@
11 # cel-tui
22
3-A TypeScript TUI framework built around a concise API and ultra-fast rendering.
3+A TypeScript TUI framework built around a declarative functional API and ultra-fast rendering.
44
55 ## Why "cel"?
66
7-A **cel** is the smallest unit of a terminal display — a single character cell. It represents the atomic building block of every terminal interface. The name reflects the library's philosophy: start from the smallest meaningful unit and build up, with nothing wasted.
7+A **cel** is the smallest unit of a terminal display — a single character cell. Start from the smallest meaningful unit and build up, with nothing wasted.
88
9-## Goals
9+## Quick Example
1010
11-- **Concise API** — minimal surface area, maximum expressiveness
12-- **Ultra fast** — performance-first rendering and state updates
13-- **TypeScript native** — full type safety out of the box
14-- **Terminal native** — built for the terminal, not ported from the browser
11+```ts
12+import { cel, VStack, Text, TextInput, ProcessTerminal } from "@cel-tui/core";
13+
14+let input = "";
15+
16+cel.init(new ProcessTerminal());
17+cel.viewport(() =>
18+ VStack(
19+ {
20+ height: "100%",
21+ onKeyPress: (key) => {
22+ if (key === "ctrl+q") process.exit();
23+ },
24+ },
25+ [
26+ Text("Hello, cel-tui!", { bold: true, fgColor: "cyan" }),
27+ Text("─", { repeat: "fill", fgColor: "brightBlack" }),
28+ TextInput({
29+ flex: 1,
30+ value: input,
31+ focused: true,
32+ onChange: (v) => {
33+ input = v;
34+ cel.render();
35+ },
36+ }),
37+ ],
38+ ),
39+);
40+```
41+
42+## Primitives
43+
44+| Primitive | Description |
45+| ------------------------- | ---------------------------------- |
46+| `VStack(props, children)` | Vertical stack — top to bottom |
47+| `HStack(props, children)` | Horizontal stack — left to right |
48+| `Text(content, props?)` | Styled text leaf |
49+| `TextInput(props)` | Multi-line editable text container |
50+
51+## Key Concepts
52+
53+- **State is external** — the framework renders what you give it. Use any state approach.
54+- **`cel.viewport(() => tree)`** sets the render function, **`cel.render()`** triggers re-renders.
55+- **Flexbox layout** — fixed, flex, percentage, and intrinsic sizing with gap, padding, alignment.
56+- **Layers** — return an array for multi-layer compositing (modals, overlays).
57+- **Controlled props** — focus, scroll, and text value are app-owned.
58+- **Cell buffer rendering** — styled cells, differential updates, synchronized output.
59+
60+## Packages
61+
62+| Package | Description |
63+| --------------------- | --------------------------------------------- |
64+| `@cel-tui/types` | Shared type definitions |
65+| `@cel-tui/core` | Framework engine and primitives |
66+| `@cel-tui/components` | Pre-made components (Button, Spacer, Divider) |
67+
68+## Development
69+
70+```bash
71+bun install # install dependencies
72+bun test # run tests (170+)
73+bun run check # biome lint
74+bun run format # prettier check
75+bun run typecheck # tsc --noEmit
76+bun run docs # generate API docs
77+```
78+
79+## License
80+
81+MIT