xonecas.io
70160
Ce

cel-tui / commit fa41f7f

Scaffold monorepo with types, core, components packages

- packages/types: shared type definitions (Color, Node, all prop interfaces)
- packages/core: primitives (VStack, HStack, Text, TextInput) + cel entrypoint
- packages/components: pre-made components (Spacer, Divider, Button)
- Thorough JSDoc on all types, interfaces, properties, and functions
- Biome for linting + import sorting, Prettier for formatting
- tsc --noEmit script for type checking
- AGENTS.md for onboarding future sessions
- Spec updated: cel.viewport render function, cel.render, key handling,
  onKeyPress prop, key format, key bubbling model

xonecas2026-04-03 fa41f7f458aba5030b9ddb0f808b1414d06581f9 parent 8011c0e

25 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

.gitignore+4−0
@@ -0,0 +1,4 @@
1+node_modules/
2+dist/
3+bun.lockb
4+*.tsbuildinfo
.prettierignore+3−0
@@ -0,0 +1,3 @@
1+node_modules
2+dist
3+bun.lock
.prettierrc+1−0
@@ -0,0 +1 @@
1+{}
AGENTS.md+62−0
@@ -0,0 +1,62 @@
1+# cel-tui — Agent Guide
2+
3+## What is this?
4+
5+cel-tui is a TypeScript TUI framework built around a declarative functional API, ultra-fast rendering, and a concise developer experience. Read `spec.md` for the full specification.
6+
7+## Project Structure
8+
9+Bun monorepo with three packages:
10+
11+```
12+packages/
13+ types/ — Shared type definitions (Color, ContainerProps, TextProps, Node, etc.)
14+ core/ — Framework engine (primitives, layout, rendering, input handling)
15+ components/ — Pre-made components built with core (Button, Spacer, Divider, etc.)
16+```
17+
18+Dependency chain: `components → core → types`
19+
20+## Key Design Decisions
21+
22+- **4 primitives only:** VStack, HStack (layout), Text (content leaf), TextInput (editable container)
23+- **State is external:** The framework has no state management. `cel.viewport(() => tree)` sets a render function, `cel.render()` requests re-evaluation. Apps use whatever state approach they want.
24+- **Controlled props pattern:** Focus (`focused`/`onFocus`/`onBlur`), scroll (`scrollOffset`/`onScroll`), and value (`value`/`onChange`) are app-controlled. The app owns the state, the framework renders it.
25+- **Uncontrolled scroll default:** `overflow: "scroll"` without `scrollOffset` is framework-managed. Adding `scrollOffset` makes it controlled.
26+- **TextInput is a container:** Accepts sizing props (flex, width, height, padding, min/max constraints) but has no children — its content is the `value` prop. Scroll is always framework-managed (follows cursor + responds to mouse wheel).
27+- **Text is a pure leaf:** No sizing props, no children. Parent controls the box. Height is intrinsic (from content + wrapping).
28+- **No style inheritance:** Every Text/TextInput sets its own styles explicitly. No cascading. Verbose but predictable.
29+- **Cell buffer rendering:** Layout writes to a 2D grid of styled cells, not raw strings. Clipping and layer compositing are cell writes. Diff against previous buffer for minimal terminal output.
30+- **Reactive rendering:** `cel.render()` batches via `process.nextTick()`. No fixed FPS.
31+- **Layers:** `cel.viewport(() => [layer1, layer2])` — array of independent viewport-sized trees, composited bottom-to-top. Conditional inclusion = show/hide.
32+- **Key bubbling:** Unconsumed keys bubble up from focused element through ancestors. Root `onKeyPress` = global handler.
33+- **Hit detection:** Topmost layer first, deepest node at (x,y), walk up to find handler. Innermost wins for scroll, click, keys.
34+
35+## Runtime
36+
37+- **Bun** for package management and running TypeScript
38+- **TypeScript** with strict mode, ESNext target, bundler module resolution
39+
40+## Commands
41+
42+```bash
43+bun install # install workspace dependencies
44+bun run <file.ts> # run any TypeScript file directly
45+bun run check # biome lint + import sorting
46+bun run check:fix # biome auto-fix
47+bun run format # prettier format check
48+bun run format:fix # prettier auto-fix
49+bun run typecheck # tsc --noEmit type checking
50+```
51+
52+## Spec
53+
54+The `spec.md` file is the source of truth for all API design decisions. Always read it before making changes to core framework behavior. The open questions at the bottom track what's been decided vs. still in progress.
55+
56+## Conventions
57+
58+- All code is TypeScript with strict mode
59+- Primitives are functions that return typed Node objects (not classes)
60+- Components in `packages/components/` are plain functions using core primitives
61+- Key format: all lowercase, modifiers joined by `+` (e.g., `"ctrl+shift+s"`)
62+- Colors: ANSI base 16 only (Color type in types package)
biome.json+22−0
@@ -0,0 +1,22 @@
1+{
2+ "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
3+ "assist": {
4+ "actions": {
5+ "source": {
6+ "organizeImports": "on"
7+ }
8+ }
9+ },
10+ "formatter": {
11+ "indentStyle": "space"
12+ },
13+ "linter": {
14+ "enabled": true,
15+ "rules": {
16+ "recommended": true
17+ }
18+ },
19+ "files": {
20+ "includes": ["packages/*/src/**/*.ts"]
21+ }
22+}
bun.lock+62−0
@@ -0,0 +1,62 @@
1+{
2+ "lockfileVersion": 1,
3+ "configVersion": 1,
4+ "workspaces": {
5+ "": {
6+ "name": "cel-tui",
7+ "devDependencies": {
8+ "@biomejs/biome": "^2.4.10",
9+ "prettier": "^3.8.1",
10+ "typescript": "^6.0.2",
11+ },
12+ },
13+ "packages/components": {
14+ "name": "@cel-tui/components",
15+ "version": "0.0.1",
16+ "dependencies": {
17+ "@cel-tui/core": "workspace:*",
18+ "@cel-tui/types": "workspace:*",
19+ },
20+ },
21+ "packages/core": {
22+ "name": "@cel-tui/core",
23+ "version": "0.0.1",
24+ "dependencies": {
25+ "@cel-tui/types": "workspace:*",
26+ },
27+ },
28+ "packages/types": {
29+ "name": "@cel-tui/types",
30+ "version": "0.0.1",
31+ },
32+ },
33+ "packages": {
34+ "@biomejs/biome": ["@biomejs/biome@2.4.10", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.10", "@biomejs/cli-darwin-x64": "2.4.10", "@biomejs/cli-linux-arm64": "2.4.10", "@biomejs/cli-linux-arm64-musl": "2.4.10", "@biomejs/cli-linux-x64": "2.4.10", "@biomejs/cli-linux-x64-musl": "2.4.10", "@biomejs/cli-win32-arm64": "2.4.10", "@biomejs/cli-win32-x64": "2.4.10" }, "bin": { "biome": "bin/biome" } }, "sha512-xxA3AphFQ1geij4JTHXv4EeSTda1IFn22ye9LdyVPoJU19fNVl0uzfEuhsfQ4Yue/0F …
35+
36+ "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.10", "", { "os": "darwin", "cpu": "arm64" }, "sha512-vuzzI1cWqDVzOMIkYyHbKqp+AkQq4K7k+UCXWpkYcY/HDn1UxdsbsfgtVpa40shem8Kax4TLDLlx8kMAecgqiw=="],
37+
38+ "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.10", "", { "os": "darwin", "cpu": "x64" }, "sha512-14fzASRo+BPotwp7nWULy2W5xeUyFnTaq1V13Etrrxkrih+ez/2QfgFm5Ehtf5vSjtgx/IJycMMpn5kPd5ZNaA=="],
39+
40+ "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.10", "", { "os": "linux", "cpu": "arm64" }, "sha512-7MH1CMW5uuxQ/s7FLST63qF8B3Hgu2HRdZ7tA1X1+mk+St4JOuIrqdhIBnnyqeyWJNI+Bww7Es5QZ0wIc1Cmkw=="],
41+
42+ "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.10", "", { "os": "linux", "cpu": "arm64" }, "sha512-WrJY6UuiSD/Dh+nwK2qOTu8kdMDlLV3dLMmychIghHPAysWFq1/DGC1pVZx8POE3ZkzKR3PUUnVrtZfMfaJjyQ=="],
43+
44+ "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.10", "", { "os": "linux", "cpu": "x64" }, "sha512-tZLvEEi2u9Xu1zAqRjTcpIDGVtldigVvzug2fTuPG0ME/g8/mXpRPcNgLB22bGn6FvLJpHHnqLnwliOu8xjYrg=="],
45+
46+ "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.10", "", { "os": "linux", "cpu": "x64" }, "sha512-kDTi3pI6PBN6CiczsWYOyP2zk0IJI08EWEQyDMQWW221rPaaEz6FvjLhnU07KMzLv8q3qSuoB93ua6inSQ55Tw=="],
47+
48+ "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.10", "", { "os": "win32", "cpu": "arm64" }, "sha512-umwQU6qPzH+ISTf/eHyJ/QoQnJs3V9Vpjz2OjZXe9MVBZ7prgGafMy7yYeRGnlmDAn87AKTF3Q6weLoMGpeqdQ=="],
49+
50+ "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.10", "", { "os": "win32", "cpu": "x64" }, "sha512-aW/JU5GuyH4uxMrNYpoC2kjaHlyJGLgIa3XkhPEZI0uKhZhJZU8BuEyJmvgzSPQNGozBwWjC972RaNdcJ9KyJg=="],
51+
52+ "@cel-tui/components": ["@cel-tui/components@workspace:packages/components"],
53+
54+ "@cel-tui/core": ["@cel-tui/core@workspace:packages/core"],
55+
56+ "@cel-tui/types": ["@cel-tui/types@workspace:packages/types"],
57+
58+ "prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="],
59+
60+ "typescript": ["typescript@6.0.2", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ=="],
61+ }
62+}
package.json+19−0
@@ -0,0 +1,19 @@
1+{
2+ "name": "cel-tui",
3+ "private": true,
4+ "workspaces": [
5+ "packages/*"
6+ ],
7+ "scripts": {
8+ "check": "biome check packages/*/src/**/*.ts",
9+ "check:fix": "biome check --write packages/*/src/**/*.ts",
10+ "format": "prettier --check .",
11+ "format:fix": "prettier --write .",
12+ "typecheck": "tsc --noEmit"
13+ },
14+ "devDependencies": {
15+ "@biomejs/biome": "^2.4.10",
16+ "prettier": "^3.8.1",
17+ "typescript": "^6.0.2"
18+ }
19+}
packages/components/package.json+12−0
@@ -0,0 +1,12 @@
1+{
2+ "name": "@cel-tui/components",
3+ "version": "0.0.1",
4+ "type": "module",
5+ "main": "src/index.ts",
6+ "types": "src/index.ts",
7+ "license": "MIT",
8+ "dependencies": {
9+ "@cel-tui/types": "workspace:*",
10+ "@cel-tui/core": "workspace:*"
11+ }
12+}
packages/components/src/button.ts+44−0
@@ -0,0 +1,44 @@
1+import type { Color, ContainerNode } from "@cel-tui/types";
2+import { HStack, Text } from "@cel-tui/core";
3+
4+/** Props for the {@link Button} component. */
5+export interface ButtonProps {
6+ /** Called on mouse click or Enter when focused. */
7+ onClick: () => void;
8+ /** Render the label in bold. */
9+ bold?: boolean;
10+ /** Label text color. */
11+ fgColor?: Color;
12+ /** Label background color. */
13+ bgColor?: Color;
14+ /**
15+ * Whether the button participates in focus traversal.
16+ * @default true
17+ */
18+ focusable?: boolean;
19+}
20+
21+/**
22+ * Clickable button with a styled text label.
23+ *
24+ * A convenience wrapper around an `HStack` with `onClick` containing
25+ * a styled `Text` node. Focusable by default — reachable via Tab and
26+ * activated with Enter.
27+ *
28+ * @param label - Button text.
29+ * @param props - Click handler and styling.
30+ * @returns A clickable container node.
31+ *
32+ * @example
33+ * Button("[Send]", { onClick: handleSend, bold: true, fgColor: "cyan" })
34+ *
35+ * @example
36+ * // Mouse-only button (not in Tab order)
37+ * Button("✕", { onClick: handleClose, focusable: false })
38+ */
39+export function Button(label: string, props: ButtonProps): ContainerNode {
40+ const { onClick, bold, fgColor, bgColor, focusable } = props;
41+ return HStack({ onClick, focusable }, [
42+ Text(label, { bold, fgColor, bgColor }),
43+ ]);
44+}
packages/components/src/divider.ts+37−0
@@ -0,0 +1,37 @@
1+import type { Color, TextNode } from "@cel-tui/types";
2+import { Text } from "@cel-tui/core";
3+
4+/** Props for the {@link Divider} component. */
5+export interface DividerProps {
6+ /**
7+ * Character to repeat across the width.
8+ * @default "─"
9+ */
10+ char?: string;
11+ /** Foreground color of the divider character. */
12+ fgColor?: Color;
13+}
14+
15+/**
16+ * Horizontal divider that fills the available width.
17+ *
18+ * Renders a single character repeated to fill the parent's width
19+ * using `Text` with `repeat: "fill"`.
20+ *
21+ * @param props - Divider character and color.
22+ * @returns A text node that fills the available width.
23+ *
24+ * @example
25+ * // Default thin line
26+ * Divider()
27+ *
28+ * // Thick line with color
29+ * Divider({ char: "━", fgColor: "brightBlack" })
30+ *
31+ * // Double line
32+ * Divider({ char: "═" })
33+ */
34+export function Divider(props: DividerProps = {}): TextNode {
35+ const { char = "─", fgColor } = props;
36+ return Text(char, { repeat: "fill", fgColor });
37+}
packages/components/src/index.ts+21−0
@@ -0,0 +1,21 @@
1+/**
2+ * @module @cel-tui/components
3+ *
4+ * Pre-made components built with `@cel-tui/core` primitives.
5+ * These are convenience wrappers for common UI patterns.
6+ *
7+ * @example
8+ * ```ts
9+ * import { Spacer, Divider, Button } from "@cel-tui/components";
10+ *
11+ * HStack({ height: 1 }, [
12+ * Text("Title", { bold: true }),
13+ * Spacer(),
14+ * Button("[OK]", { onClick: handleOk }),
15+ * ])
16+ * ```
17+ */
18+
19+export { Spacer } from "./spacer.js";
20+export { Divider, type DividerProps } from "./divider.js";
21+export { Button, type ButtonProps } from "./button.js";
packages/components/src/spacer.ts+22−0
@@ -0,0 +1,22 @@
1+import type { ContainerNode } from "@cel-tui/types";
2+import { VStack } from "@cel-tui/core";
3+
4+/**
5+ * Flexible spacer that fills available space along the parent's main axis.
6+ *
7+ * Equivalent to an empty `VStack({ flex: 1 }, [])`. Use inside an HStack
8+ * to push siblings apart, or inside a VStack for vertical spacing.
9+ *
10+ * @returns A flex container node that expands to fill remaining space.
11+ *
12+ * @example
13+ * // Push items to opposite ends of a row
14+ * HStack({ height: 1 }, [
15+ * Text("left"),
16+ * Spacer(),
17+ * Text("right"),
18+ * ])
19+ */
20+export function Spacer(): ContainerNode {
21+ return VStack({ flex: 1 }, []);
22+}
packages/components/tsconfig.json+13−0
@@ -0,0 +1,13 @@
1+{
2+ "compilerOptions": {
3+ "strict": true,
4+ "target": "ESNext",
5+ "module": "ESNext",
6+ "moduleResolution": "bundler",
7+ "declaration": true,
8+ "outDir": "dist",
9+ "rootDir": "src"
10+ },
11+ "include": ["src"],
12+ "references": [{ "path": "../types" }, { "path": "../core" }]
13+}
packages/core/package.json+11−0
@@ -0,0 +1,11 @@
1+{
2+ "name": "@cel-tui/core",
3+ "version": "0.0.1",
4+ "type": "module",
5+ "main": "src/index.ts",
6+ "types": "src/index.ts",
7+ "license": "MIT",
8+ "dependencies": {
9+ "@cel-tui/types": "workspace:*"
10+ }
11+}
packages/core/src/cel.ts+76−0
@@ -0,0 +1,76 @@
1+import type { Node } from "@cel-tui/types";
2+
3+type RenderFn = () => Node | Node[];
4+
5+let renderFn: RenderFn | null = null;
6+let renderScheduled = false;
7+
8+function doRender(): void {
9+ renderScheduled = false;
10+ if (!renderFn) return;
11+ const _tree = renderFn();
12+ // TODO: layout → paint → composite → diff → emit
13+}
14+
15+/**
16+ * cel-tui framework entrypoint.
17+ *
18+ * The framework is stateless — it renders whatever tree the render function
19+ * returns. State management is fully external. Use any approach you like
20+ * (plain variables, classes, libraries) and call {@link cel.render} when
21+ * state changes.
22+ *
23+ * @example
24+ * ```ts
25+ * let count = 0;
26+ *
27+ * cel.viewport(() =>
28+ * VStack({ height: "100%" }, [
29+ * Text(`Count: ${count}`),
30+ * HStack({ onClick: () => { count++; cel.render(); } }, [
31+ * Text("[+1]"),
32+ * ]),
33+ * ])
34+ * );
35+ * ```
36+ */
37+export const cel = {
38+ /**
39+ * Set the render function that returns the UI tree.
40+ * Triggers the first render automatically.
41+ *
42+ * The render function is called by the framework whenever a render is
43+ * needed (after {@link cel.render} is called, or on terminal resize).
44+ * It should return a single {@link Node} (one layer) or an array of
45+ * nodes (multiple layers, composited bottom-to-top).
46+ *
47+ * @param fn - A function that returns the current UI tree.
48+ *
49+ * @example
50+ * // Single layer
51+ * cel.viewport(() => VStack({ height: "100%" }, [...]))
52+ *
53+ * // Multiple layers (modal on top)
54+ * cel.viewport(() => [
55+ * VStack({ height: "100%" }, [...mainUI]),
56+ * VStack({ height: "100%" }, [...modalUI]),
57+ * ])
58+ */
59+ viewport(fn: RenderFn): void {
60+ renderFn = fn;
61+ cel.render();
62+ },
63+
64+ /**
65+ * Request a re-render. Call this after state changes.
66+ *
67+ * Batched via `process.nextTick()` — multiple calls within the same
68+ * tick produce a single render. Safe to call from any callback
69+ * (`onChange`, `onClick`, `onKeyPress`, etc.).
70+ */
71+ render(): void {
72+ if (renderScheduled) return;
73+ renderScheduled = true;
74+ process.nextTick(doRender);
75+ },
76+};
packages/core/src/index.ts+44−0
@@ -0,0 +1,44 @@
1+/**
2+ * @module @cel-tui/core
3+ *
4+ * Core framework package. Provides the four primitives ({@link VStack},
5+ * {@link HStack}, {@link Text}, {@link TextInput}) and the framework
6+ * entrypoint ({@link cel}).
7+ *
8+ * All types are re-exported from `@cel-tui/types`.
9+ *
10+ * @example
11+ * ```ts
12+ * import { cel, VStack, HStack, Text, TextInput } from "@cel-tui/core";
13+ *
14+ * let name = "";
15+ *
16+ * cel.viewport(() =>
17+ * VStack({ height: "100%" }, [
18+ * Text("What is your name?", { bold: true }),
19+ * TextInput({
20+ * value: name,
21+ * onChange: (v) => { name = v; cel.render(); },
22+ * }),
23+ * ])
24+ * );
25+ * ```
26+ */
27+
28+export type {
29+ Color,
30+ StyleProps,
31+ SizeValue,
32+ ContainerProps,
33+ TextProps,
34+ TextInputProps,
35+ TextNode,
36+ TextInputNode,
37+ ContainerNode,
38+ Node,
39+} from "@cel-tui/types";
40+
41+export { VStack, HStack } from "./primitives/stacks.js";
42+export { Text } from "./primitives/text.js";
43+export { TextInput } from "./primitives/text-input.js";
44+export { cel } from "./cel.js";
packages/core/src/primitives/stacks.ts+42−0
@@ -0,0 +1,42 @@
1+import type { ContainerNode, ContainerProps, Node } from "@cel-tui/types";
2+
3+/**
4+ * Create a vertical stack container — children laid out top to bottom.
5+ *
6+ * Equivalent to CSS `flex-direction: column`. Main axis is vertical,
7+ * cross axis is horizontal.
8+ *
9+ * @param props - Layout, sizing, scrolling, focus, and interaction props.
10+ * @param children - Ordered child nodes.
11+ * @returns A container node for the UI tree.
12+ *
13+ * @example
14+ * VStack({ flex: 1, gap: 1 }, [
15+ * Text("Hello"),
16+ * Text("World"),
17+ * ])
18+ */
19+export function VStack(props: ContainerProps, children: Node[]): ContainerNode {
20+ return { type: "vstack", props, children };
21+}
22+
23+/**
24+ * Create a horizontal stack container — children laid out left to right.
25+ *
26+ * Equivalent to CSS `flex-direction: row`. Main axis is horizontal,
27+ * cross axis is vertical.
28+ *
29+ * @param props - Layout, sizing, scrolling, focus, and interaction props.
30+ * @param children - Ordered child nodes.
31+ * @returns A container node for the UI tree.
32+ *
33+ * @example
34+ * HStack({ height: 1, gap: 1 }, [
35+ * Text("Name", { bold: true }),
36+ * VStack({ flex: 1 }, []),
37+ * Text("value", { fgColor: "brightBlack" }),
38+ * ])
39+ */
40+export function HStack(props: ContainerProps, children: Node[]): ContainerNode {
41+ return { type: "hstack", props, children };
42+}
packages/core/src/primitives/text-input.ts+42−0
@@ -0,0 +1,42 @@
1+import type { TextInputNode, TextInputProps } from "@cel-tui/types";
2+
3+/**
4+ * Create a multi-line editable text container.
5+ *
6+ * TextInput accepts container sizing props (`flex`, `width`, `height`,
7+ * `padding`, `maxHeight`, etc.) but has no children — its content is the
8+ * {@link TextInputProps.value | value} prop.
9+ *
10+ * Word-wrap is always on. Cursor position is framework-managed.
11+ * Scroll is always uncontrolled — the view follows the cursor and
12+ * responds to mouse wheel automatically.
13+ *
14+ * TextInput is always focusable. When focused, text-editing keys
15+ * (printable characters, arrows, backspace, Tab) are consumed.
16+ * Modifier combos (e.g., `ctrl+s`) bubble up to ancestor `onKeyPress` handlers.
17+ *
18+ * @param props - Value, callbacks, sizing, styling, and focus props.
19+ * @returns A text input node for the UI tree.
20+ *
21+ * @example
22+ * // Basic input
23+ * TextInput({
24+ * value: text,
25+ * onChange: (v) => { text = v; cel.render(); },
26+ * })
27+ *
28+ * @example
29+ * // Growing input with max height
30+ * TextInput({
31+ * flex: 1,
32+ * maxHeight: 10,
33+ * value: text,
34+ * onChange: handleChange,
35+ * onSubmit: handleSend,
36+ * submitKey: "ctrl+enter",
37+ * placeholder: Text("type a message...", { fgColor: "brightBlack" }),
38+ * })
39+ */
40+export function TextInput(props: TextInputProps): TextInputNode {
41+ return { type: "textinput", props };
42+}
packages/core/src/primitives/text.ts+29−0
@@ -0,0 +1,29 @@
1+import type { TextNode, TextProps } from "@cel-tui/types";
2+
3+/**
4+ * Create a styled text leaf node.
5+ *
6+ * Text has no children and no sizing props — the parent container
7+ * controls the box. Width is always parent-assigned. Height is intrinsic,
8+ * computed from content, newlines (`\n`), and word-wrapping at the given width.
9+ *
10+ * Whitespace is always preserved. Content that exceeds the box is
11+ * hard-clipped (no ellipsis).
12+ *
13+ * @param content - The text string to display.
14+ * @param props - Styling, repeat, and wrapping props.
15+ * @returns A text node for the UI tree.
16+ *
17+ * @example
18+ * // Simple styled text
19+ * Text("Hello", { bold: true, fgColor: "cyan" })
20+ *
21+ * // Horizontal divider
22+ * Text("─", { repeat: "fill" })
23+ *
24+ * // Word-wrapped paragraph
25+ * Text(paragraph, { wrap: "word" })
26+ */
27+export function Text(content: string, props: TextProps = {}): TextNode {
28+ return { type: "text", content, props };
29+}
packages/core/tsconfig.json+13−0
@@ -0,0 +1,13 @@
1+{
2+ "compilerOptions": {
3+ "strict": true,
4+ "target": "ESNext",
5+ "module": "ESNext",
6+ "moduleResolution": "bundler",
7+ "declaration": true,
8+ "outDir": "dist",
9+ "rootDir": "src"
10+ },
11+ "include": ["src"],
12+ "references": [{ "path": "../types" }]
13+}
packages/types/package.json+8−0
@@ -0,0 +1,8 @@
1+{
2+ "name": "@cel-tui/types",
3+ "version": "0.0.1",
4+ "type": "module",
5+ "main": "src/index.ts",
6+ "types": "src/index.ts",
7+ "license": "MIT"
8+}
packages/types/src/index.ts+316−0
@@ -0,0 +1,316 @@
1+/**
2+ * ANSI base 16 terminal color.
3+ *
4+ * The 8 standard colors and their bright variants. These map directly
5+ * to the terminal's configured color palette.
6+ */
7+export type Color =
8+ | "black"
9+ | "red"
10+ | "green"
11+ | "yellow"
12+ | "blue"
13+ | "magenta"
14+ | "cyan"
15+ | "white"
16+ | "brightBlack"
17+ | "brightRed"
18+ | "brightGreen"
19+ | "brightYellow"
20+ | "brightBlue"
21+ | "brightMagenta"
22+ | "brightCyan"
23+ | "brightWhite";
24+
25+/**
26+ * Styling props shared by {@link TextProps} and {@link TextInputProps}.
27+ *
28+ * Maps directly to terminal SGR (Select Graphic Rendition) attributes.
29+ * There is no style inheritance — every node sets its own styles explicitly.
30+ */
31+export interface StyleProps {
32+ /** Render text with bold weight. */
33+ bold?: boolean;
34+ /** Render text in italic style. */
35+ italic?: boolean;
36+ /** Render text with an underline. */
37+ underline?: boolean;
38+ /** Foreground (text) color. */
39+ fgColor?: Color;
40+ /** Background color. */
41+ bgColor?: Color;
42+}
43+
44+/**
45+ * A size value expressed as a fixed cell count or a percentage string.
46+ *
47+ * @example
48+ * 30 // 30 cells
49+ * "50%" // 50% of parent
50+ * "100%" // fill parent
51+ */
52+export type SizeValue = number | `${number}%`;
53+
54+/**
55+ * Props shared by all container nodes ({@link ContainerNode} and {@link TextInputNode}).
56+ *
57+ * Controls layout, sizing, scrolling, focus, click handling, and key events.
58+ */
59+export interface ContainerProps {
60+ /**
61+ * Fixed width in cells, or percentage of parent width.
62+ * When omitted, the container uses intrinsic sizing (fits content)
63+ * or flex/percentage if those are set.
64+ */
65+ width?: SizeValue;
66+
67+ /**
68+ * Fixed height in cells, or percentage of parent height.
69+ * When omitted, the container uses intrinsic sizing (fits content)
70+ * or flex/percentage if those are set.
71+ */
72+ height?: SizeValue;
73+
74+ /**
75+ * Flex grow factor. Space remaining after fixed and intrinsic children
76+ * is distributed proportionally among flex children.
77+ *
78+ * @example
79+ * flex: 1 // equal share
80+ * flex: 2 // double share
81+ */
82+ flex?: number;
83+
84+ /** Minimum width constraint in cells. */
85+ minWidth?: number;
86+ /** Maximum width constraint in cells. */
87+ maxWidth?: number;
88+ /** Minimum height constraint in cells. */
89+ minHeight?: number;
90+ /** Maximum height constraint in cells. */
91+ maxHeight?: number;
92+
93+ /**
94+ * Internal padding in cells.
95+ * `x` adds horizontal padding (left + right), `y` adds vertical (top + bottom).
96+ */
97+ padding?: { x?: number; y?: number };
98+
99+ /** Spacing between children in cells. */
100+ gap?: number;
101+
102+ /**
103+ * Distribute children along the main axis.
104+ * - VStack main axis = vertical
105+ * - HStack main axis = horizontal
106+ */
107+ justifyContent?: "start" | "end" | "center" | "space-between";
108+
109+ /**
110+ * Align children along the cross axis.
111+ * - VStack cross axis = horizontal
112+ * - HStack cross axis = vertical
113+ */
114+ alignItems?: "start" | "end" | "center" | "stretch";
115+
116+ /**
117+ * Content overflow behavior.
118+ * - `"hidden"` (default) — clip content at the container edge.
119+ * - `"scroll"` — enable scrolling along the main axis.
120+ */
121+ overflow?: "hidden" | "scroll";
122+
123+ /** Show a scrollbar indicator when `overflow` is `"scroll"`. */
124+ scrollbar?: boolean;
125+
126+ /**
127+ * Controlled scroll position in cells. When provided, the app owns
128+ * scroll state and must update this value via {@link onScroll}.
129+ * When omitted, scroll is framework-managed (uncontrolled).
130+ */
131+ scrollOffset?: number;
132+
133+ /**
134+ * Called when the user scrolls this container (mouse wheel).
135+ * In controlled mode, update {@link scrollOffset} with the new value
136+ * to move the scroll position.
137+ *
138+ * @param offset - The new scroll offset in cells.
139+ */
140+ onScroll?: (offset: number) => void;
141+
142+ /**
143+ * Called on mouse click or Enter key when this container is focused.
144+ * Setting this prop makes the container focusable by default.
145+ */
146+ onClick?: () => void;
147+
148+ /**
149+ * Whether this container participates in focus traversal.
150+ * Defaults to `true` when {@link onClick} is set. Set to `false`
151+ * to make a container clickable by mouse but not reachable via Tab.
152+ */
153+ focusable?: boolean;
154+
155+ /**
156+ * Whether this container is currently focused. Controlled by the app —
157+ * only one element should be focused at a time.
158+ */
159+ focused?: boolean;
160+
161+ /** Called when this container receives focus (Tab, Shift+Tab, or mouse click). */
162+ onFocus?: () => void;
163+
164+ /** Called when this container loses focus. */
165+ onBlur?: () => void;
166+
167+ /**
168+ * Called on key events that bubble up to this container.
169+ * Keys are first handled by the focused element; unconsumed keys
170+ * (e.g., modifier combos like `"ctrl+s"`) bubble up through ancestors.
171+ * The root container's `onKeyPress` acts as the global key handler.
172+ *
173+ * Key format: all lowercase, modifiers joined by `+` in canonical
174+ * order `ctrl+alt+shift+<key>` (e.g., `"ctrl+s"`, `"alt+up"`, `"escape"`).
175+ *
176+ * @param key - Normalized key string.
177+ */
178+ onKeyPress?: (key: string) => void;
179+}
180+
181+/**
182+ * Props for the {@link Text} primitive.
183+ *
184+ * Text is a styled leaf node with no children and no sizing props —
185+ * the parent container controls the box. Height is intrinsic, computed
186+ * from content, newlines, and word-wrapping at the given width.
187+ */
188+export interface TextProps extends StyleProps {
189+ /**
190+ * Repeat the text content a fixed number of times or to fill the
191+ * available width. When set, wrapping is ignored.
192+ *
193+ * @example
194+ * repeat: "fill" // fills parent width (e.g., dividers)
195+ * repeat: 20 // repeats exactly 20 times
196+ */
197+ repeat?: number | "fill";
198+
199+ /**
200+ * Text wrapping mode.
201+ * - `"none"` (default) — no wrapping, content is hard-clipped at the box edge.
202+ * - `"word"` — word-wrap to fit available width. Affects computed height.
203+ *
204+ * Whitespace is always preserved. `\n` produces explicit line breaks.
205+ */
206+ wrap?: "none" | "word";
207+}
208+
209+/**
210+ * Props for the {@link TextInput} primitive.
211+ *
212+ * TextInput is a multi-line editable text container. It accepts container
213+ * sizing props but has no children — its content is the {@link value} prop.
214+ * Scroll is always framework-managed (follows cursor and responds to mouse wheel).
215+ * Word-wrap is always on.
216+ */
217+export interface TextInputProps extends ContainerProps, StyleProps {
218+ /** Current text content. Controlled — the app owns this value. */
219+ value: string;
220+
221+ /**
222+ * Called when the user edits text. Update {@link value} with the new
223+ * string and call `cel.render()` to reflect the change.
224+ *
225+ * @param value - The new text content.
226+ */
227+ onChange: (value: string) => void;
228+
229+ /**
230+ * Called when the user presses the submit key.
231+ * @see {@link submitKey}
232+ */
233+ onSubmit?: () => void;
234+
235+ /**
236+ * Key combo that fires {@link onSubmit}.
237+ * @default "enter"
238+ *
239+ * @example
240+ * submitKey: "ctrl+enter" // Enter inserts newline, Ctrl+Enter submits
241+ */
242+ submitKey?: string;
243+
244+ /**
245+ * A {@link TextNode} displayed when {@link value} is empty.
246+ * Fully stylable — pass a `Text()` call with any styling props.
247+ *
248+ * @example
249+ * placeholder: Text("type a message...", { fgColor: "brightBlack" })
250+ */
251+ placeholder?: TextNode;
252+
253+ /**
254+ * Whether this input is currently focused. Controlled — the app
255+ * owns focus state. TextInput is always focusable.
256+ */
257+ focused?: boolean;
258+
259+ /** Called when this input receives focus (Tab, Shift+Tab, or mouse click). */
260+ onFocus?: () => void;
261+
262+ /** Called when this input loses focus. */
263+ onBlur?: () => void;
264+}
265+
266+/**
267+ * A text leaf node in the UI tree.
268+ *
269+ * Created by the {@link Text} function. Has no children — the parent
270+ * container controls the box, and height is intrinsic (computed from
271+ * content and wrapping).
272+ */
273+export interface TextNode {
274+ type: "text";
275+ /** The text content to display. */
276+ content: string;
277+ /** Text styling and behavior props. */
278+ props: TextProps;
279+}
280+
281+/**
282+ * An editable text container node in the UI tree.
283+ *
284+ * Created by the {@link TextInput} function. Accepts container sizing
285+ * props but has no children — its content is the `value` prop.
286+ */
287+export interface TextInputNode {
288+ type: "textinput";
289+ /** TextInput configuration and styling props. */
290+ props: TextInputProps;
291+}
292+
293+/**
294+ * A layout container node in the UI tree.
295+ *
296+ * Created by {@link VStack} (vertical) or {@link HStack} (horizontal).
297+ * Contains an ordered list of child nodes.
298+ */
299+export interface ContainerNode {
300+ /** `"vstack"` for vertical layout, `"hstack"` for horizontal. */
301+ type: "vstack" | "hstack";
302+ /** Container layout, sizing, and interaction props. */
303+ props: ContainerProps;
304+ /** Ordered child nodes. */
305+ children: Node[];
306+}
307+
308+/**
309+ * Any node in the cel-tui UI tree.
310+ *
311+ * The tree is built from three node types:
312+ * - {@link ContainerNode} — layout containers (VStack, HStack)
313+ * - {@link TextNode} — styled text leaf
314+ * - {@link TextInputNode} — editable text container
315+ */
316+export type Node = TextNode | TextInputNode | ContainerNode;
packages/types/tsconfig.json+12−0
@@ -0,0 +1,12 @@
1+{
2+ "compilerOptions": {
3+ "strict": true,
4+ "target": "ESNext",
5+ "module": "ESNext",
6+ "moduleResolution": "bundler",
7+ "declaration": true,
8+ "outDir": "dist",
9+ "rootDir": "src"
10+ },
11+ "include": ["src"]
12+}
spec.md+248−113
@@ -11,10 +11,15 @@ cel-tui is a TypeScript TUI framework built around a declarative functional API,
1111 ### Entrypoint
1212
1313 ```ts
14-cel.viewport(layer: Node | Node[])
14+cel.viewport(render: () => Node | Node[])
15+cel.render()
1516 ```
1617
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+`cel.viewport` sets the render function that returns the UI tree. 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). Setting the viewport triggers the first render.
19+
20+`cel.render` requests a re-render. Batched via `process.nextTick()` — multiple calls within the same tick produce a single render. Call this after state changes.
21+
22+State is fully external to the framework. Use any state management approach — plain variables, classes, libraries. The framework just calls the render function and renders the returned tree.
1823
1924 ### Primitives
2025
@@ -81,6 +86,7 @@ Shared by both VStack and HStack:
8186 | `focused` | `boolean` | Whether this element is focused (controlled) |
8287 | `onFocus` | `() => void` | Called when element receives focus |
8388 | `onBlur` | `() => void` | Called when element loses focus |
89+| `onKeyPress` | `(key: string) => void` | Called on key event (bubbles up from focus) |
8490
8591 ### Sizing
8692
@@ -236,7 +242,43 @@ Focus is implicit — no `focusable` prop needed for the common case:
236242
237243 **Escape** unfocuses the current element. **Tab / Shift+Tab** moves focus to the next/previous focusable element in document order (depth-first tree traversal).
238244
239-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.
245+When a TextInput is focused, text-editing keys (printable characters, arrows, backspace, Tab) go to the input. Modifier combos (e.g., `ctrl+s`) are not consumed by TextInput and bubble up. Press Escape to leave the input, then Tab to traverse.
246+
247+---
248+
249+## Key Handling
250+
251+Key events are routed through the focus and layer system, then bubble up the tree.
252+
253+### Key Event Flow
254+
255+1. **Topmost layer** receives the key event
256+2. If a **TextInput** is focused, it consumes text-editing keys (printable characters, arrows, backspace, Tab). Modifier combos pass through.
257+3. If a **clickable container** is focused, Enter fires `onClick`. Other keys pass through.
258+4. Unconsumed keys **bubble up** through ancestors — the nearest `onKeyPress` handler in the ancestor chain handles it.
259+5. The root container's `onKeyPress` acts as the global key handler.
260+
261+### Key Format
262+
263+All lowercase, modifiers joined by `+` in canonical order `ctrl+alt+shift+<key>`:
264+
265+```
266+"ctrl+s"
267+"ctrl+shift+n"
268+"escape"
269+"enter"
270+"alt+up"
271+"f1"
272+"ctrl+plus"
273+```
274+
275+**Modifiers:** `ctrl`, `alt`, `shift`
Cut short: this commit's diff is over 1000 lines.
tsconfig.json+13−0
Cut short: this commit's diff is over 1000 lines.