xonecas.io
70160
Ce

cel-tui / commit 27ea458

Define core API: Text, TextInput, focus model, click, controlled scroll

- Text: styling props, repeat (number/fill), word wrap, hard clip
- TextInput: multi-line, controlled value, intrinsic height, growing pattern
- Shared styling props: bold, italic, underline, fgColor, bgColor (ANSI 16)
- Containers: onClick prop, focusable opt-out
- Focus: controlled (focused/onFocus/onBlur), Escape to unfocus, Tab traversal
- Click: innermost clickable wins, Enter activates focused clickable
- Scroll: controlled only (scrollOffset/onScroll)
- Sizing: added intrinsic as default (size to fit content)
- Text selection: native terminal via Shift+click/drag
- Updated reference example to match spec

xonecas2026-04-03 27ea458eff49bbb5b06f5901e6425cba7e321e49 parent 87e3e12

1 file changed

spec.md+242−98
@@ -8,32 +8,23 @@ cel-tui is a TypeScript TUI framework built around a declarative functional API,
88
99 ## API Surface
1010
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-
1311 ### Primitives
1412
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 |
13+| Category | Primitive | Description |
14+| ----------- | ------------------------- | -------------------------------------------------- |
15+| Layout | `VStack(props, children)` | Vertical stack — children laid out top to bottom |
16+| Layout | `HStack(props, children)` | Horizontal stack — children laid out left to right |
17+| Content | `Text(content, props?)` | Styled text content |
18+| Interactive | `TextInput(props)` | Editable text field |
2419
2520 ### Systems
2621
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 |
22+| System | Description |
23+| -------------------------- | ------------------------------------------- |
24+| Flexbox layout engine | Sizing, alignment, gap |
25+| Overflow & scrolling | `overflow: "hidden" \| "scroll"`, scrollbar |
26+| Mouse scroll hit detection | Pointer-driven, innermost scrollable wins |
27+| Focus management | Keyboard-driven, for `TextInput` |
3728
3829 ---
3930
@@ -51,23 +42,53 @@ Containers are arbitrarily nestable: `HStack > VStack > HStack > ...`
5142 Declarative and functional:
5243
5344 ```ts
54-VStack(props, children)
55-HStack(props, children)
45+VStack(props, children);
46+HStack(props, children);
5647 ```
5748
49+### Container Props
50+
51+Shared by both VStack and HStack:
52+
53+| Prop | Type | Description |
54+| ---------------- | ---------------------------- | ----------------------------------------------- |
55+| `width` | `number \| string` | Fixed cells or percentage (`"50%"`) |
56+| `height` | `number \| string` | Fixed cells or percentage (`"100%"`) |
57+| `flex` | `number` | Flex grow factor, proportional to siblings |
58+| `minWidth` | `number` | Minimum width constraint |
59+| `maxWidth` | `number` | Maximum width constraint |
60+| `minHeight` | `number` | Minimum height constraint |
61+| `maxHeight` | `number` | Maximum height constraint |
62+| `padding` | `{ x?: number, y?: number }` | Internal padding (cells) |
63+| `gap` | `number` | Spacing between children (cells) |
64+| `justifyContent` | `string` | Distribute children along the main axis |
65+| `alignItems` | `string` | Align children along the cross axis |
66+| `overflow` | `"hidden" \| "scroll"` | Content overflow behavior (default: `"hidden"`) |
67+| `scrollbar` | `boolean` | Show scrollbar indicator |
68+| `scrollOffset` | `number` | Scroll position in cells (controlled) |
69+| `onScroll` | `(offset: number) => void` | Called on scroll input |
70+| `onClick` | `() => void` | Called on mouse click or Enter when focused |
71+| `focusable` | `boolean` | Opt out of focus (default: `true` if `onClick`) |
72+| `focused` | `boolean` | Whether this element is focused (controlled) |
73+| `onFocus` | `() => void` | Called when element receives focus |
74+| `onBlur` | `() => void` | Called when element loses focus |
75+
5876 ### Sizing
5977
60-Three sizing strategies, inspired by CSS Flexbox:
78+Four sizing strategies, inspired by CSS Flexbox:
6179
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 |
80+| Strategy | Example | Description |
81+| -------------- | -------------------------------- | ----------------------------- |
82+| **Intrinsic** | _(no sizing props set)_ | Size to fit content (default) |
83+| **Fixed** | `width: 30, height: 10` | Exact cell count |
84+| **Flex** | `flex: 1`, `flex: 2` | Proportional to siblings |
85+| **Percentage** | `width: "50%"`, `height: "100%"` | Relative to parent |
6786
6887 Constraints via `minWidth`, `maxWidth`, `minHeight`, `maxHeight`.
6988
70-**Sizing priority:** Fixed sizes are allocated first, then remaining space is distributed among flex/percentage children.
89+**Intrinsic sizing:** A container with no explicit `width`/`height`/`flex`/percentage sizes to fit its children. Leaf nodes (Text, TextInput) compute intrinsic height from content and wrapping at the given width.
90+
91+**Sizing priority:** Intrinsic and fixed sizes are allocated first, then remaining space is distributed among flex/percentage children.
7192
7293 ### Gap
7394
@@ -86,23 +107,29 @@ Inspired by Flexbox:
86107
87108 ---
88109
110+## Rounding Strategy
111+
112+Terminals operate on integer cell coordinates. When dividing space among flex/percentage children produces fractional values, a deterministic rounding strategy is needed.
113+
114+> **TODO:** Define rounding approach (e.g., largest remainder method).
115+
116+---
117+
89118 ## Overflow & Scrolling
90119
91120 ### Overflow Modes
92121
93122 ```ts
94-VStack({ overflow: "hidden" }) // clip content (default)
95-VStack({ overflow: "scroll" }) // enable scrolling
123+VStack({ overflow: "hidden" }); // clip content (default)
124+VStack({ overflow: "scroll" }); // enable scrolling
96125 ```
97126
98-Future additions: `"visible"`, `"auto"` (scrollbar only when content overflows).
99-
100127 ### Scrollbar
101128
102129 Optional visual scrollbar indicator:
103130
104131 ```ts
105-VStack({ overflow: "scroll", scrollbar: true })
132+VStack({ overflow: "scroll", scrollbar: true });
106133 ```
107134
108135 ### Scroll Direction
@@ -112,11 +139,21 @@ Follows the container's main axis:
112139 - VStack with `overflow: "scroll"` → vertical scroll
113140 - HStack with `overflow: "scroll"` → horizontal scroll
114141
115-Future: independent `overflowX` / `overflowY` properties.
116-
117142 ### Scroll Position
118143
119-Controlled via `scrollOffset` prop and event callbacks.
144+Scroll is **controlled only** — the app owns the scroll state.
145+
146+```ts
147+VStack({
148+ overflow: "scroll",
149+ scrollOffset: offset,
150+ onScroll: (newOffset) => {
151+ offset = newOffset;
152+ },
153+});
154+```
155+
156+The framework never mutates scroll position internally. Mouse wheel events fire `onScroll` with the new offset; the UI only moves when the app passes the updated `scrollOffset` back. This enables patterns like auto-scroll to bottom on new content.
120157
121158 ---
122159
@@ -135,25 +172,70 @@ Scroll is **pointer-driven**, not focus-driven. Mouse wheel events are routed sp
135172
136173 **Innermost scrollable wins.** The deepest scrollable ancestor of the hit target handles the event.
137174
138-Future: bubble-on-boundary behavior (inner container scrolls to its limit, then event bubbles to the next scrollable ancestor).
139-
140175 ### Architecture Requirements
141176
142177 - Each node stores its **absolute screen rect** after layout
143178 - The layout tree supports **bottom-up traversal** (child → parent)
144179 - Hit testing: given `(x, y)` → return the deepest node at that position
145180
181+### Click
182+
183+Click uses the same hit model as scroll: mouse click position is mapped to the deepest node, then walks up the ancestor chain to find the nearest container with `onClick`. **Innermost clickable container wins.**
184+
185+### Text Selection
186+
187+Native terminal text selection (click-drag to highlight/copy) is handled by the terminal emulator, not the framework. With SGR mouse mode enabled, most terminals support **Shift+click/drag** to bypass application mouse capture and use native selection. This is standard behavior across terminal applications (vim, tmux, etc.).
188+
146189 ---
147190
148191 ## Focus Model
149192
150-Focus is **keyboard-driven** and separate from scroll.
193+Focus is **keyboard-driven** and separate from scroll. Focus state is **controlled** — the app owns which element is focused.
151194
152-- Focus is for interactive widgets (text inputs, buttons, selectable lists)
195+- Focus is for interactive widgets (TextInput) and clickable containers (with `onClick`)
153196 - Scroll does not require focus
154197 - A user can type in a focused widget while scrolling a different container with the mouse
155198
156-> **TODO:** Define focus traversal, focus trapping, and keybinding model.
199+### Focusable Elements
200+
201+Focus is implicit — no `focusable` prop needed for the common case:
202+
203+- **TextInput** — always focusable
204+- **Container with `onClick`** — focusable by default, opt out with `focusable: false`
205+
206+### Traversal
207+
208+**Escape** unfocuses the current element. **Tab / Shift+Tab** moves focus to the next/previous focusable element in document order (depth-first tree traversal).
209+
210+When a TextInput is focused, all keys (including Tab) go to the input. Press Escape first to leave the input, then Tab to traverse. This avoids the Tab conflict with text editing.
211+
212+### Activation
213+
214+When a clickable container is focused, **Enter** fires its `onClick`.
215+
216+### Mouse Interaction
217+
218+Clicking a focusable element also focuses it. This bridges the keyboard and mouse models — click a TextInput to start typing, click a button to focus it.
219+
220+### Controlled Focus
221+
222+The app owns focus state via `focused`, `onFocus`, and `onBlur` props on focusable elements:
223+
224+```ts
225+TextInput({
226+ value: text,
227+ onChange: handleChange,
228+ focused: isFocused,
229+ onFocus: () => {
230+ isFocused = true;
231+ },
232+ onBlur: () => {
233+ isFocused = false;
234+ },
235+});
236+```
237+
238+Only one element can be focused at a time. The app is responsible for ensuring this — if multiple elements set `focused: true`, the first in document order wins.
157239
158240 ---
159241
@@ -161,31 +243,107 @@ Focus is **keyboard-driven** and separate from scroll.
161243
162244 ### Text
163245
164-> **TODO:** Define styling props (bold, dim, color, etc.) and text wrapping behavior.
246+Styled text leaf node. No children, no sizing props — the parent container controls the box.
247+
248+```ts
249+Text(content: string, props?: TextProps)
250+```
251+
252+**Sizing behavior:**
253+
254+- Width: always parent-assigned
255+- Height: intrinsic — computed from content, newlines, and word-wrapping at the given width
256+
257+#### Props
258+
259+| Prop | Type | Description |
260+| -------- | ------------------ | ------------------------------------ |
261+| `repeat` | `number \| "fill"` | Repeat content N times or fill width |
262+| `wrap` | `"none" \| "word"` | Wrapping mode (default: `"none"`) |
263+
264+Text also accepts the shared styling props (see Styling Props below).
265+
266+#### Repeat
267+
268+```ts
269+Text("─", { repeat: "fill" }); // repeat to fill available width
270+Text("─", { repeat: 20 }); // repeat exactly 20 times
271+```
272+
273+`repeat` takes a number or `"fill"`. When set, wrapping is ignored.
165274
166-### Box
275+#### Wrapping
167276
168-> **TODO:** Define border styles, padding model, and box-sizing behavior.
277+| Mode | Description |
278+| -------------- | --------------------------------------------------------------- |
279+| `wrap: "none"` | No wrapping (default). Content is hard-clipped at the box edge. |
280+| `wrap: "word"` | Word-wrap to fit available width. Affects computed height. |
281+
282+Whitespace is always preserved. `\n` in content produces explicit line breaks.
283+
284+---
169285
170286 ### TextInput
171287
172-> **TODO:** Define props (placeholder, value, onSubmit, onChange), cursor behavior, and focus interaction.
288+Multi-line editable text field. Leaf node — no children, no sizing props. Fills parent like Text.
289+
290+```ts
291+TextInput(props: TextInputProps)
292+```
293+
294+**Sizing behavior:**
295+
296+- Width: always parent-assigned
297+- Height: intrinsic — computed from content word-wrapping at the given width
298+
299+When content exceeds the parent's box, TextInput scrolls internally. Internal scroll is framework-managed — the view follows the cursor automatically.
300+
301+#### Props
173302
174-### Spacer
303+| Prop | Type | Description |
304+| ------------- | ------------------------- | -------------------------------------------------- |
305+| `value` | `string` | Current text content (controlled) |
306+| `onChange` | `(value: string) => void` | Called on text change |
307+| `onSubmit` | `() => void` | Called on submit key |
308+| `submitKey` | `string` | Key combo that fires onSubmit (default: `"enter"`) |
309+| `placeholder` | `Text` | Text node shown when value is empty |
310+| `focused` | `boolean` | Whether this input is focused (controlled) |
311+| `onFocus` | `() => void` | Called when input receives focus |
312+| `onBlur` | `() => void` | Called when input loses focus |
175313
176-A zero-content element with `flex: 1`. Used to push siblings apart within a stack.
314+Word-wrap is always on. Cursor position is framework-managed.
315+
316+TextInput also accepts the shared styling props (see Styling Props below).
317+
318+#### Growing / Shrinking Pattern
319+
320+Because TextInput has intrinsic height, a parent with `maxHeight` creates a naturally growing input:
177321
178322 ```ts
179-HStack({ height: 1 }, [
180- Text("left"),
181- Spacer(),
182- Text("right"),
183-])
323+VStack({ maxHeight: 10 }, [
324+ TextInput({ value, onChange, onSubmit, submitKey: "ctrl+enter" }),
325+]);
184326 ```
185327
186-### Divider
328+- 1 line of text → parent height is 1
329+- 5 lines → parent height is 5
330+- 15 lines → parent height is 10 (capped), internal scroll kicks in
331+
332+---
333+
334+### Styling Props
335+
336+Shared by Text and TextInput:
337+
338+| Prop | Type | Description |
339+| ----------- | --------- | ---------------- |
340+| `bold` | `boolean` | Bold weight |
341+| `italic` | `boolean` | Italic style |
342+| `underline` | `boolean` | Underlined text |
343+| `fgColor` | `Color` | Foreground color |
344+| `bgColor` | `Color` | Background color |
187345
188-> **TODO:** Define orientation (auto from parent axis?), character style, and sizing.
346+**Colors:** ANSI base 16 — `"black"`, `"red"`, `"green"`, `"yellow"`, `"blue"`, `"magenta"`, `"cyan"`, `"white"`, and their bright variants (`"brightRed"`, `"brightGreen"`, etc.).
189347
190348 ---
191349
@@ -216,70 +374,56 @@ HStack({ height: 1 }, [
216374
217375 ```ts
218376 VStack({ height: "100%" }, [
219-
220377 // Header
221378 HStack({ height: 1, padding: { x: 1 } }, [
222379 Text("Agent Name", { bold: true }),
223- Spacer(),
224- Text("model: gpt", { dim: true }),
380+ VStack({ flex: 1 }),
381+ Text("model: gpt", { fgColor: "brightBlack" }),
225382 ]),
226383
227- Divider(),
228-
229384 // Message history
230385 VStack({ flex: 1, overflow: "scroll", scrollbar: true, padding: { x: 1 } }, [
231- ...messages.map(msg =>
386+ ...messages.map((msg) =>
232387 VStack({ gap: 0 }, [
233388 Text(`${msg.role === "user" ? "▶" : "▷"} ${msg.role}:`, {
234389 bold: msg.role === "user",
235- color: msg.role === "user" ? "blue" : "green",
390+ fgColor: msg.role === "user" ? "blue" : "green",
236391 }),
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- ),
392+ ...msg.blocks.map((block) => Text(` ${block.content}`)),
244393 ]),
245394 ),
246395 ]),
247396
248- Divider(),
249-
250397 // Input area
251- HStack({ height: 1, padding: { x: 1 }, gap: 1 }, [
398+ HStack({ maxHeight: 10, padding: { x: 1 }, gap: 1 }, [
252399 Text(">"),
253- TextInput({
254- flex: 1,
255- placeholder: "type a message...",
256- onSubmit: handleSend,
257- }),
400+ VStack({ flex: 1 }, [
401+ TextInput({
402+ value: input,
403+ onChange: handleChange,
404+ placeholder: Text("type a message...", { fgColor: "brightBlack" }),
405+ onSubmit: handleSend,
406+ }),
407+ ]),
258408 ]),
259-
260-])
409+]);
261410 ```
262411
263412 ---
264413
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).
414+## Open Questions
270415
271----
416+- [x] `Text` styling props and text wrapping
417+- [x] `TextInput` props, cursor, and submit behavior
418+- [x] Focus traversal and keybinding model
419+- [x] Controlled vs uncontrolled scroll position
420+- [ ] Layering for interactive components, like modals and autocomplete interactions.
421+- [x] Clickable areas/containers. Could be it's own primitive or a prop in the containers.
422+- [ ] Rounding strategy for fractional cell division
423+- [ ] Handling different width characters and ANSI escapes sequences when computing sizes.
424+- [ ] Flicker free rendering strategy. Reactive or FPS based? Diff rendering?
272425
273-## Open Questions
426+## Things to keep in mind for the rendering discussion
274427
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
428+- Differential Rendering: Three-strategy rendering system that only updates what changed
429+- Synchronized Output: Uses CSI 2026 for atomic screen updates (no flicker)