xonecas.io
70160
Ce

cel-tui / commit 87e3e12

chore: intial commit

xonecas2026-04-03 87e3e12eda273e3de7aea23fce9c09ea4f14edb7 parent b9f4e67

2 files changed

README.md+14−0
@@ -0,0 +1,14 @@
1+# cel-tui
2+
3+A TypeScript TUI framework built around a concise API and ultra-fast rendering.
4+
5+## Why "cel"?
6+
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.
8+
9+## Goals
10+
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
spec.md+285−0
@@ -0,0 +1,285 @@
1+# cel-tui Specification
2+
3+## Overview
4+
5+cel-tui is a TypeScript TUI framework built around a declarative functional API, ultra-fast rendering, and a concise developer experience. Layout is inspired by CSS Flexbox, using composable horizontal and vertical stacks as the core container primitives.
6+
7+---
8+
9+## API Surface
10+
11+cel-tui ships with a minimal set of primitives. The v1 scope is guided by what's needed to build a functional agentic chat UI.
12+
13+### Primitives
14+
15+| Category | Primitive | Description |
16+|---|---|---|
17+| Layout | `VStack(props, children)` | Vertical stack — children laid out top to bottom |
18+| Layout | `HStack(props, children)` | Horizontal stack — children laid out left to right |
19+| Content | `Text(content, props?)` | Styled text content |
20+| Content | `Box(props, children)` | Bordered container |
21+| Interactive | `TextInput(props)` | Editable text field |
22+| Utility | `Spacer()` | Flex-filling empty space, pushes siblings apart |
23+| Utility | `Divider(props?)` | Horizontal or vertical line separator |
24+
25+### Systems
26+
27+| System | Scope | Status |
28+|---|---|---|
29+| Flexbox layout engine | Sizing, alignment, gap | v1 |
30+| Overflow & scrolling | `overflow: "hidden" \| "scroll"`, scrollbar | v1 |
31+| Mouse scroll hit detection | Pointer-driven, innermost scrollable wins | v1 |
32+| Focus management | Keyboard-driven, for `TextInput` | v1 |
33+| Mouse click hit detection | For interactive elements | v1 |
34+| Scroll bubble-on-boundary | Nested scrollable overflow | Deferred |
35+| `overflow: "auto"` | Conditional scrollbar | Deferred |
36+| `overflowX` / `overflowY` | Independent axis control | Deferred |
37+
38+---
39+
40+## Layout Model
41+
42+### Core Containers
43+
44+- **VStack** — vertical stack, children laid out top to bottom (`flex-direction: column`)
45+- **HStack** — horizontal stack, children laid out left to right (`flex-direction: row`)
46+
47+Containers are arbitrarily nestable: `HStack > VStack > HStack > ...`
48+
49+### API Shape
50+
51+Declarative and functional:
52+
53+```ts
54+VStack(props, children)
55+HStack(props, children)
56+```
57+
58+### Sizing
59+
60+Three sizing strategies, inspired by CSS Flexbox:
61+
62+| Strategy | Example | Description |
63+|---|---|---|
64+| **Fixed** | `width: 30, height: 10` | Exact cell count |
65+| **Flex** | `flex: 1`, `flex: 2` | Proportional to siblings |
66+| **Percentage** | `width: "50%"`, `height: "100%"` | Relative to parent |
67+
68+Constraints via `minWidth`, `maxWidth`, `minHeight`, `maxHeight`.
69+
70+**Sizing priority:** Fixed sizes are allocated first, then remaining space is distributed among flex/percentage children.
71+
72+### Gap
73+
74+Cell-based spacing between children:
75+
76+```ts
77+HStack({ gap: 1 }, [...])
78+```
79+
80+### Alignment
81+
82+Inspired by Flexbox:
83+
84+- `justifyContent` — distribute children along the main axis
85+- `alignItems` — align children along the cross axis
86+
87+---
88+
89+## Overflow & Scrolling
90+
91+### Overflow Modes
92+
93+```ts
94+VStack({ overflow: "hidden" }) // clip content (default)
95+VStack({ overflow: "scroll" }) // enable scrolling
96+```
97+
98+Future additions: `"visible"`, `"auto"` (scrollbar only when content overflows).
99+
100+### Scrollbar
101+
102+Optional visual scrollbar indicator:
103+
104+```ts
105+VStack({ overflow: "scroll", scrollbar: true })
106+```
107+
108+### Scroll Direction
109+
110+Follows the container's main axis:
111+
112+- VStack with `overflow: "scroll"` → vertical scroll
113+- HStack with `overflow: "scroll"` → horizontal scroll
114+
115+Future: independent `overflowX` / `overflowY` properties.
116+
117+### Scroll Position
118+
119+Controlled via `scrollOffset` prop and event callbacks.
120+
121+---
122+
123+## Scroll Input Model
124+
125+Scroll is **pointer-driven**, not focus-driven. Mouse wheel events are routed spatially based on cursor position.
126+
127+### Hit Detection
128+
129+1. Terminal reports mouse position via SGR mouse mode
130+2. Map the `(x, y)` coordinate to the deepest node in the layout tree at that position
131+3. Walk up the ancestor chain to find the nearest container with `overflow: "scroll"`
132+4. That container handles the scroll event
133+
134+### Nested Scrollable Containers
135+
136+**Innermost scrollable wins.** The deepest scrollable ancestor of the hit target handles the event.
137+
138+Future: bubble-on-boundary behavior (inner container scrolls to its limit, then event bubbles to the next scrollable ancestor).
139+
140+### Architecture Requirements
141+
142+- Each node stores its **absolute screen rect** after layout
143+- The layout tree supports **bottom-up traversal** (child → parent)
144+- Hit testing: given `(x, y)` → return the deepest node at that position
145+
146+---
147+
148+## Focus Model
149+
150+Focus is **keyboard-driven** and separate from scroll.
151+
152+- Focus is for interactive widgets (text inputs, buttons, selectable lists)
153+- Scroll does not require focus
154+- A user can type in a focused widget while scrolling a different container with the mouse
155+
156+> **TODO:** Define focus traversal, focus trapping, and keybinding model.
157+
158+---
159+
160+## Primitives
161+
162+### Text
163+
164+> **TODO:** Define styling props (bold, dim, color, etc.) and text wrapping behavior.
165+
166+### Box
167+
168+> **TODO:** Define border styles, padding model, and box-sizing behavior.
169+
170+### TextInput
171+
172+> **TODO:** Define props (placeholder, value, onSubmit, onChange), cursor behavior, and focus interaction.
173+
174+### Spacer
175+
176+A zero-content element with `flex: 1`. Used to push siblings apart within a stack.
177+
178+```ts
179+HStack({ height: 1 }, [
180+ Text("left"),
181+ Spacer(),
182+ Text("right"),
183+])
184+```
185+
186+### Divider
187+
188+> **TODO:** Define orientation (auto from parent axis?), character style, and sizing.
189+
190+---
191+
192+## Reference Example: Agentic Chat UI
193+
194+```
195+┌──────────────────────────────────────────────┐
196+│ Agent Name model: gpt │
197+├──────────────────────────────────────────────┤
198+│ ▶ User: What files are in this dir? │
199+│ │
200+│ ▷ Agent: I'll check that for you. │
201+│ ┌──────────────────────────────┐ │
202+│ │ $ ls -la │ │
203+│ │ file1.ts │ │
204+│ │ file2.ts │ │
205+│ │ README.md │ │
206+│ └──────────────────────────────┘ │
207+│ Found 3 files. │
208+│ │
209+│ ▶ User: Delete file2.ts │
210+│ │
211+│ ▷ Agent: Running... ⠋ │
212+├──────────────────────────────────────────────┤
213+│ > type a message... [Send]│
214+└──────────────────────────────────────────────┘
215+```
216+
217+```ts
218+VStack({ height: "100%" }, [
219+
220+ // Header
221+ HStack({ height: 1, padding: { x: 1 } }, [
222+ Text("Agent Name", { bold: true }),
223+ Spacer(),
224+ Text("model: gpt", { dim: true }),
225+ ]),
226+
227+ Divider(),
228+
229+ // Message history
230+ VStack({ flex: 1, overflow: "scroll", scrollbar: true, padding: { x: 1 } }, [
231+ ...messages.map(msg =>
232+ VStack({ gap: 0 }, [
233+ Text(`${msg.role === "user" ? "▶" : "▷"} ${msg.role}:`, {
234+ bold: msg.role === "user",
235+ color: msg.role === "user" ? "blue" : "green",
236+ }),
237+ ...msg.blocks.map(block =>
238+ block.type === "code"
239+ ? Box({ border: "round", marginLeft: 2 }, [
240+ Text(block.content, { dim: true }),
241+ ])
242+ : Text(block.content, { marginLeft: 2 }),
243+ ),
244+ ]),
245+ ),
246+ ]),
247+
248+ Divider(),
249+
250+ // Input area
251+ HStack({ height: 1, padding: { x: 1 }, gap: 1 }, [
252+ Text(">"),
253+ TextInput({
254+ flex: 1,
255+ placeholder: "type a message...",
256+ onSubmit: handleSend,
257+ }),
258+ ]),
259+
260+])
261+```
262+
263+---
264+
265+## Rounding Strategy
266+
267+Terminals operate on integer cell coordinates. When dividing space among flex/percentage children produces fractional values, a deterministic rounding strategy is needed.
268+
269+> **TODO:** Define rounding approach (e.g., largest remainder method).
270+
271+---
272+
273+## Open Questions
274+
275+- [ ] Flex wrap support — defer to post-v1?
276+- [ ] Borders/padding — part of the container or a separate `Box` wrapper?
277+- [ ] `overflow: "auto"` — show scrollbar only when content overflows
278+- [ ] `overflowX` / `overflowY` — independent axis control
279+- [ ] Scroll bubble-on-boundary behavior for nested scrollables
280+- [ ] Focus traversal and keybinding model
281+- [ ] Controlled vs uncontrolled scroll position
282+- [ ] `Text` styling props and text wrapping
283+- [ ] `Box` border styles and padding model
284+- [ ] `TextInput` props, cursor, and submit behavior
285+- [ ] `Divider` orientation and styling