xonecas.io
70160
Ce

cel-tui / commit 8011c0e

Add entrypoint, layering, and consistency fixes

- cel.viewport(layer | layers[]) as framework entrypoint
- Layering: independent viewport-sized trees, bottom-to-top compositing
- Hit detection: topmost layer first, then innermost node wins
- Modal backdrop pattern documented
- Scroll: both controlled and uncontrolled modes
- TextInput: container with sizing props, implicit uncontrolled scroll
- TextInput props scoped to sizing/padding/focus (no gap/alignment/overflow)
- Reference examples updated with cel.viewport
- Consistency fixes across systems table, intrinsic sizing, hit detection

xonecas2026-04-03 8011c0e0cb6a56253ea8ecf25141647a740dd731 parent db7529d

1 file changed

spec.md+204−120
@@ -8,23 +8,32 @@ cel-tui is a TypeScript TUI framework built around a declarative functional API,
88
99 ## API Surface
1010
11+### Entrypoint
12+
13+```ts
14+cel.viewport(layer: Node | Node[])
15+```
16+
17+Accepts a single layer or an array of layers. Each layer is a container with full viewport dimensions, laid out independently. When multiple layers are provided, they are composited bottom-to-top (array index = z-order).
18+
1119 ### Primitives
1220
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 |
21+| Category | Primitive | Description |
22+| --------- | ------------------------- | -------------------------------------------------- |
23+| Layout | `VStack(props, children)` | Vertical stack — children laid out top to bottom |
24+| Layout | `HStack(props, children)` | Horizontal stack — children laid out left to right |
25+| Content | `Text(content, props?)` | Styled text content |
26+| Container | `TextInput(props)` | Editable text container |
1927
2028 ### Systems
2129
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` |
30+| System | Description |
31+| -------------------------- | --------------------------------------------------------- |
32+| Flexbox layout engine | Sizing, alignment, gap |
33+| Overflow & scrolling | `overflow: "hidden" \| "scroll"`, scrollbar |
34+| Layering | Multiple viewport layers, composited bottom-to-top |
35+| Mouse/scroll hit detection | Pointer-driven, topmost layer first, innermost node wins |
36+| Focus management | Keyboard-driven, for `TextInput` and clickable containers |
2837
2938 ---
3039
@@ -86,7 +95,7 @@ Four sizing strategies, inspired by CSS Flexbox:
8695
8796 Constraints via `minWidth`, `maxWidth`, `minHeight`, `maxHeight`.
8897
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.
98+**Intrinsic sizing:** A container with no explicit `width`/`height`/`flex`/percentage sizes to fit its children. Leaf nodes (Text) and TextInput compute intrinsic height from content and wrapping at the given width.
9099
91100 **Sizing priority:** Intrinsic and fixed sizes are allocated first, then remaining space is distributed among flex/percentage children.
92101
@@ -109,9 +118,20 @@ Inspired by Flexbox:
109118
110119 ## Rounding Strategy
111120
112-Terminals operate on integer cell coordinates. When dividing space among flex/percentage children produces fractional values, a deterministic rounding strategy is needed.
121+Terminals operate on integer cell coordinates. When dividing space among flex/percentage children produces fractional values, the **Largest Remainder Method** is used:
113122
114-> **TODO:** Define rounding approach (e.g., largest remainder method).
123+1. Floor all computed sizes
124+2. Calculate the remaining cells (available space minus sum of floored values)
125+3. Distribute remaining cells one-by-one to children with the largest fractional remainders
126+
127+Example: 80 columns, three `flex: 1` children (80 ÷ 3 = 26.667 each):
128+
129+- Floor: 26, 26, 26 = 78
130+- Remaining: 2 cells
131+- All fractional parts are equal (0.667), first two children receive +1
132+- Result: 27, 27, 26
133+
134+This guarantees the total always sums exactly to the available space, with no order bias.
115135
116136 ---
117137
@@ -141,7 +161,15 @@ Follows the container's main axis:
141161
142162 ### Scroll Position
143163
144-Scroll is **controlled only** — the app owns the scroll state.
164+Scroll supports both **uncontrolled** and **controlled** modes, determined by whether `scrollOffset` is provided:
165+
166+**Uncontrolled** (default) — the framework manages scroll position internally. Mouse wheel just works:
167+
168+```ts
169+VStack({ overflow: "scroll" }, [...])
170+```
171+
172+**Controlled** — the app owns the scroll state. Enables patterns like auto-scroll to bottom on new content:
145173
146174 ```ts
147175 VStack({
@@ -150,10 +178,10 @@ VStack({
150178 onScroll: (newOffset) => {
151179 offset = newOffset;
152180 },
153-});
181+}, [...])
154182 ```
155183
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.
184+In controlled mode, mouse wheel events fire `onScroll` with the new offset; the UI only moves when the app passes the updated `scrollOffset` back.
157185
158186 ---
159187
@@ -164,9 +192,10 @@ Scroll is **pointer-driven**, not focus-driven. Mouse wheel events are routed sp
164192 ### Hit Detection
165193
166194 1. Terminal reports mouse position via SGR mouse mode
167-2. Map the `(x, y)` coordinate to the deepest node in the layout tree at that position
168-3. Walk up the ancestor chain to find the nearest container with `overflow: "scroll"`
169-4. That container handles the scroll event
195+2. Starting from the **topmost layer**, find the deepest node at `(x, y)`
196+3. If the layer has a node at that position, it handles the event. Otherwise, try the next layer down.
197+4. For scroll: walk up the ancestor chain to find the nearest scrollable node (container with `overflow: "scroll"`, or TextInput)
198+5. For click: walk up to find the nearest container with `onClick`
170199
171200 ### Nested Scrollable Containers
172201
@@ -239,6 +268,54 @@ Only one element can be focused at a time. The app is responsible for ensuring t
239268
240269 ---
241270
271+## Layering
272+
273+Layering enables modals, dropdowns, and overlay UI. Each layer is an independent layout tree with full viewport dimensions.
274+
275+```ts
276+// Single layer — most apps
277+cel.viewport(
278+ VStack({ height: "100%" }, [...])
279+)
280+
281+// Multiple layers — ordered bottom-to-top
282+cel.viewport([
283+ VStack({ height: "100%" }, [...mainUI]),
284+ VStack({ height: "100%" }, [...modalUI]),
285+])
286+```
287+
288+**Compositing:** Layers are rendered bottom-to-top. Cells without content in a higher layer are transparent — the lower layer shows through.
289+
290+**Input:** Events target the topmost layer that has a node at the event position. This naturally blocks input to lower layers when a modal or overlay is present.
291+
292+**Modal backdrop pattern:** A full-viewport container on the top layer captures all input, preventing interaction with the base UI:
293+
294+```ts
295+cel.viewport([
296+ VStack({ height: "100%" }, [...mainUI]),
297+ VStack(
298+ {
299+ height: "100%",
300+ justifyContent: "center",
301+ alignItems: "center",
302+ onClick: dismissModal,
303+ },
304+ [
305+ VStack({ width: 40, height: 15 }, [
306+ Text("Are you sure?"),
307+ HStack({ gap: 1 }, [
308+ HStack({ onClick: handleYes }, [Text("[Yes]")]),
309+ HStack({ onClick: handleNo }, [Text("[No]")]),
310+ ]),
311+ ]),
312+ ],
313+ ),
314+]);
315+```
316+
317+---
318+
242319 ## Primitives
243320
244321 ### Text
@@ -285,21 +362,16 @@ Whitespace is always preserved. `\n` in content produces explicit line breaks.
285362
286363 ### TextInput
287364
288-Multi-line editable text field. Leaf node — no children, no sizing props. Fills parent like Text.
365+Multi-line editable text container. Accepts all container props but has no children — its content is the editable `value`. Scroll is always uncontrolled (framework-managed: follows cursor and responds to mouse wheel).
289366
290367 ```ts
291368 TextInput(props: TextInputProps)
292369 ```
293370
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-
301371 #### Props
302372
373+Container sizing props (`width`, `height`, `flex`, `min*`, `max*`, `padding`), focus props, and:
374+
303375 | Prop | Type | Description |
304376 | ------------- | ------------------------- | -------------------------------------------------- |
305377 | `value` | `string` | Current text content (controlled) |
@@ -317,17 +389,21 @@ TextInput also accepts the shared styling props (see Styling Props below).
317389
318390 #### Growing / Shrinking Pattern
319391
320-Because TextInput has intrinsic height, a parent with `maxHeight` creates a naturally growing input:
392+Without explicit height, TextInput uses intrinsic sizing (content height). Combined with `maxHeight`, this creates a naturally growing input:
321393
322394 ```ts
323-VStack({ maxHeight: 10 }, [
324- TextInput({ value, onChange, onSubmit, submitKey: "ctrl+enter" }),
325-]);
395+TextInput({
396+ maxHeight: 10,
397+ value,
398+ onChange,
399+ onSubmit,
400+ submitKey: "ctrl+enter",
401+});
326402 ```
327403
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
404+- 1 line of text → height is 1
405+- 5 lines → height is 5
406+- 15 lines → height is 10 (capped), internal scroll kicks in
331407
332408 ---
333409
@@ -373,32 +449,37 @@ Shared by Text and TextInput:
373449 ```
374450
375451 ```ts
376-VStack({ height: "100%" }, [
377- // Header
378- HStack({ height: 1, padding: { x: 1 } }, [
379- Text("Agent Name", { bold: true }),
380- VStack({ flex: 1 }),
381- Text("model: gpt", { fgColor: "brightBlack" }),
382- ]),
452+cel.viewport(
453+ VStack({ height: "100%" }, [
454+ // Header
455+ HStack({ height: 1, padding: { x: 1 } }, [
456+ Text("Agent Name", { bold: true }),
457+ VStack({ flex: 1 }),
458+ Text("model: gpt", { fgColor: "brightBlack" }),
459+ ]),
383460
384- // Message history
385- VStack({ flex: 1, overflow: "scroll", scrollbar: true, padding: { x: 1 } }, [
386- ...messages.map((msg) =>
387- VStack({ gap: 0 }, [
388- Text(`${msg.role === "user" ? "▶" : "▷"} ${msg.role}:`, {
389- bold: msg.role === "user",
390- fgColor: msg.role === "user" ? "blue" : "green",
391- }),
392- ...msg.blocks.map((block) => Text(` ${block.content}`)),
393- ]),
461+ // Message history
462+ VStack(
463+ { flex: 1, overflow: "scroll", scrollbar: true, padding: { x: 1 } },
464+ [
465+ ...messages.map((msg) =>
466+ VStack({ gap: 0 }, [
467+ Text(`${msg.role === "user" ? "▶" : "▷"} ${msg.role}:`, {
468+ bold: msg.role === "user",
469+ fgColor: msg.role === "user" ? "blue" : "green",
470+ }),
471+ ...msg.blocks.map((block) => Text(` ${block.content}`)),
472+ ]),
473+ ),
474+ ],
394475 ),
395- ]),
396476
397- // Input area
398- HStack({ maxHeight: 10, padding: { x: 1 }, gap: 1 }, [
399- Text(">"),
400- VStack({ flex: 1 }, [
477+ // Input area
478+ HStack({ padding: { x: 1 }, gap: 1 }, [
479+ Text(">"),
401480 TextInput({
481+ flex: 1,
482+ maxHeight: 10,
402483 value: input,
403484 onChange: handleChange,
404485 placeholder: Text("type a message...", { fgColor: "brightBlack" }),
@@ -406,7 +487,7 @@ VStack({ height: "100%" }, [
406487 }),
407488 ]),
408489 ]),
409-]);
490+);
410491 ```
411492
412493 ---
@@ -417,7 +498,7 @@ VStack({ height: "100%" }, [
417498 ┌──────────────┬───────────────────────────────┐
418499 │ files/ │ main.ts │
419500 │ ▸ main.ts │ │
420-│ utils.ts │ import { foo } from "./utils"; │
501+│ utils.ts │ import { foo } from "./utils";│
421502 │ test.ts │ │
422503 │ │ function main() { │
423504 │ │ console.log(foo()); │
@@ -430,71 +511,74 @@ VStack({ height: "100%" }, [
430511 ```
431512
432513 ```ts
433-HStack({ height: "100%" }, [
434- // Sidebar
435- VStack(
436- {
437- width: 20,
438- overflow: "scroll",
439- scrollOffset: sidebarScroll,
440- onScroll: (o) => {
441- sidebarScroll = o;
514+cel.viewport(
515+ HStack({ height: "100%" }, [
516+ // Sidebar
517+ VStack(
518+ {
519+ width: 20,
520+ overflow: "scroll",
521+ scrollOffset: sidebarScroll,
522+ onScroll: (o) => {
523+ sidebarScroll = o;
524+ },
442525 },
443- },
444- [
445- Text("files/", { bold: true }),
446- ...files.map((file) =>
447- HStack(
448- {
449- onClick: () => selectFile(file),
450- focusable: false,
451- },
452- [
453- Text(
454- `${file === activeFile ? "▸" : " "} ${file.name}`,
455- file === activeFile
456- ? { fgColor: "cyan", bgColor: "brightBlack" }
457- : {},
458- ),
459- ],
526+ [
527+ Text("files/", { bold: true }),
528+ ...files.map((file) =>
529+ HStack(
530+ {
531+ onClick: () => selectFile(file),
532+ focusable: false,
533+ },
534+ [
535+ Text(
536+ `${file === activeFile ? "▸" : " "} ${file.name}`,
537+ file === activeFile
538+ ? { fgColor: "cyan", bgColor: "brightBlack" }
539+ : {},
540+ ),
541+ ],
542+ ),
460543 ),
461- ),
462- ],
463- ),
544+ ],
545+ ),
464546
465- // Main area
466- VStack({ flex: 1 }, [
467- // Tab bar
468- HStack({ height: 1 }, [
469- Text(` ${activeFile.name} `, { bold: true, bgColor: "brightBlack" }),
470- Text(" ", { repeat: "fill" }),
471- ]),
547+ // Main area
548+ VStack({ flex: 1 }, [
549+ // Tab bar
550+ HStack({ height: 1 }, [
551+ Text(` ${activeFile.name} `, { bold: true, bgColor: "brightBlack" }),
552+ Text(" ", { repeat: "fill" }),
553+ ]),
472554
473- // Editor
474- TextInput({
475- value: activeFile.content,
476- onChange: handleEdit,
477- focused: editorFocused,
478- onFocus: () => {
479- editorFocused = true;
480- },
481- onBlur: () => {
482- editorFocused = false;
483- },
484- }),
485-
486- // Status bar
487- HStack({ height: 1 }, [
488- Text(` ${activeFile.name}`, { fgColor: "white", bgColor: "blue" }),
489- Text(` Ln ${cursor.line}, Col ${cursor.col}`, {
490- fgColor: "white",
491- bgColor: "blue",
555+ // Editor
556+ TextInput({
557+ flex: 1,
558+ value: activeFile.content,
559+ onChange: handleEdit,
560+ focused: editorFocused,
561+ onFocus: () => {
562+ editorFocused = true;
563+ },
564+ onBlur: () => {
565+ editorFocused = false;
566+ },
492567 }),
493- Text(" ", { repeat: "fill", bgColor: "blue" }),
494- Text(`TypeScript ✓ `, { fgColor: "white", bgColor: "blue" }),
568+
569+ // Status bar
570+ HStack({ height: 1 }, [
571+ Text(` ${activeFile.name}`, { fgColor: "white", bgColor: "blue" }),
572+ Text(` Ln ${cursor.line}, Col ${cursor.col}`, {
573+ fgColor: "white",
574+ bgColor: "blue",
575+ }),
576+ Text(" ", { repeat: "fill", bgColor: "blue" }),
577+ Text(`TypeScript ✓ `, { fgColor: "white", bgColor: "blue" }),
578+ ]),
495579 ]),
496580 ]),
497-]);
581+);
498582 ```
499583
500584 ---
@@ -505,9 +589,9 @@ HStack({ height: "100%" }, [
505589 - [x] `TextInput` props, cursor, and submit behavior
506590 - [x] Focus traversal and keybinding model
507591 - [x] Controlled vs uncontrolled scroll position
508-- [ ] Layering for interactive components, like modals and autocomplete interactions.
592+- [x] Layering for interactive components, like modals and autocomplete interactions.
509593 - [x] Clickable areas/containers. Could be it's own primitive or a prop in the containers.
510-- [ ] Rounding strategy for fractional cell division
594+- [x] Rounding strategy for fractional cell division
511595 - [ ] Handling different width characters and ANSI escapes sequences when computing sizes.
512596 - [ ] Flicker free rendering strategy. Reactive or FPS based? Diff rendering?