@@ -5,12 +5,12 @@ license: MIT
55 compatibility: Requires Bun runtime and a terminal with SGR mouse mode support.
66 metadata:
77 author: sacenox
8- version: "0.0.1"
8+ version: "0.1.0"
99 ---
1010
1111 # Building TUIs with cel-tui
1212
13-cel-tui is a TypeScript TUI framework with a declarative functional API, flexbox layout, and cell-buffer rendering. It has 4 primitives and external state management.
13+cel-tui is a TypeScript TUI framework with a declarative functional API, flexbox layout, cell-buffer rendering, and style inheritance. It has 4 primitives and external state management.
1414
1515 ## Install
1616
@@ -47,6 +47,7 @@ cel.viewport(() =>
4747 VStack(
4848 {
4949 height: "100%",
50+ fgColor: "white",
5051 onKeyPress: (key) => {
5152 if (key === "ctrl+q") {
5253 cel.stop();
@@ -60,7 +61,6 @@ cel.viewport(() =>
6061 TextInput({
6162 flex: 1,
6263 value,
63- focused: true,
6464 onChange: (v) => {
6565 value = v;
6666 cel.render();
@@ -101,6 +101,7 @@ TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`,
101101
102102 ```ts
103103 {
104+ // Sizing
104105 width, height, // SizeValue (number | "50%")
105106 flex, // number
106107 minWidth, maxWidth, // number
@@ -113,9 +114,16 @@ TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`,
113114 scrollbar, // boolean
114115 scrollOffset, // number (controlled scroll)
115116 onScroll, // (offset: number) => void
117+
118+ // Styling (inherited by descendants)
119+ bold, italic, underline,// boolean
120+ fgColor, bgColor, // Color (ANSI 16)
121+ focusStyle, // StyleProps — overrides when focused
122+
123+ // Interaction
116124 onClick, // () => void
117125 focusable, // boolean (default true if onClick set)
118- focused, // boolean (controlled)
126+ focused, // boolean (controlled — omit for uncontrolled)
119127 onFocus, // () => void
120128 onBlur, // () => void
121129 onKeyPress, // (key: string) => void
@@ -147,11 +155,7 @@ TextInput({
147155 onSubmit, // () => void
148156 submitKey, // string (default "enter")
149157 placeholder, // Text() node shown when empty
150- focused, // boolean (controlled)
151- onFocus,
152- onBlur, // () => void
153- // + all container sizing props
154- // + all styling props (bold, fgColor, etc.)
158+ // + all container props (sizing, styling, focus, etc.)
155159 });
156160 ```
157161
@@ -173,12 +177,17 @@ HStack({ height: 1 }, [
173177 Text("─", { repeat: "fill", fgColor: "brightBlack" });
174178 ```
175179
176-### Button
180+### Button with focus style
177181
178182 ```ts
179-HStack({ onClick: handleClick }, [
180- Text("[Send]", { bold: true, fgColor: "cyan" }),
181-]);
183+HStack(
184+ {
185+ onClick: handleClick,
186+ fgColor: "cyan",
187+ focusStyle: { bgColor: "cyan", fgColor: "black" },
188+ },
189+ [Text(" Send ", { bold: true })],
190+);
182191 ```
183192
184193 ### Growing text input (caps at maxHeight, then scrolls)
@@ -218,7 +227,7 @@ VStack(
218227
219228 ### Layers (modals)
220229
221-Return an array from the render function. Layers composite bottom-to-top:
230+Return an array from the render function. Layers composite bottom-to-top. Use `bgColor` for opaque modal backgrounds:
222231
223232 ```ts
224233 cel.viewport(() => [
@@ -235,7 +244,11 @@ cel.viewport(() => [
235244 cel.render();
236245 },
237246 },
238- [VStack({ width: 40, height: 10 }, [...modalContent])],
247+ [
248+ VStack({ width: 40, height: 10, bgColor: "black" }, [
249+ ...modalContent,
250+ ]),
251+ ],
239252 ),
240253 ]
241254 : []),
@@ -256,9 +269,15 @@ VStack({
256269 }, [...])
257270 ```
258271
259-### Focus (controlled)
272+### Focus
273+
274+Focus is **uncontrolled by default** — Tab/Shift+Tab/Escape/click just work:
260275
261276 ```ts
277+// Uncontrolled (default) — framework manages focus
278+HStack({ onClick: handleAction }, [Text("[ OK ]")]);
279+
280+// Controlled — app owns focus state (provide `focused` prop)
262281 TextInput({
263282 value: text,
264283 onChange: handleChange,
@@ -274,6 +293,17 @@ TextInput({
274293 });
275294 ```
276295
296+### Style inheritance
297+
298+Containers propagate styles to descendants. Explicit props always win:
299+
300+```ts
301+VStack({ fgColor: "white", bgColor: "blue" }, [
302+ Text("inherits white on blue"),
303+ Text("explicit green on blue", { fgColor: "green" }),
304+]);
305+```
306+
277307 ## Key Format
278308
279309 All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`, `"enter"`, `"alt+up"`, `"f1"`. Framework normalizes modifier order.
@@ -283,7 +313,9 @@ All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`
283313 - **State is external** — framework has no state. Call `cel.render()` after changes.
284314 - **Text is a leaf** — no sizing props, no children. Parent controls the box.
285315 - **TextInput is a container** — accepts sizing props but no children.
286-- **No style inheritance** — every node sets its own styles explicitly.
316+- **Style inheritance** — containers propagate styles (fgColor, bgColor, bold, etc.) to descendants. Explicit props on a node always override. Container `bgColor` fills the rect with opaque background.
317+- **focusStyle** — `focusStyle: { bgColor, fgColor, ... }` on containers overrides styles when focused. Participates in inheritance.
318+- **Uncontrolled focus by default** — Tab/Shift+Tab/Escape/click just work. Provide `focused` prop to opt into controlled mode.
287319 - **Escape unfocuses** the current element.
288320 - **Tab/Shift+Tab** traverses focusable elements in document order (wraps around). After Escape, traversal continues from the element that lost focus (not from the start).
289321 - **Enter** activates a focused clickable container (fires onClick).