@@ -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;