xonecas.io
70160
Ce

cel-tui / files

cel-tui / packages / core / src / primitives / text-input.ts

2.2 KB
1import 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 unless the
11 * controlled `cursor` prop is provided with `onCursorChange`.
12 * `cursorStyle` selects a block (default), bar, or underline cursor for both
13 * the painted fallback and native terminal cursor.
14 * Scroll is always uncontrolled — the view follows the cursor and
15 * responds to mouse wheel automatically.
16 *
17 * TextInput is focusable by default; pass `focusable: false` to remove it
18 * from keyboard traversal and mouse focus. When focused through controlled
19 * focus, it consumes insertable text
20 * plus editing/navigation keys (arrows, backspace, delete, Enter, Tab),
21 * along with a small set of readline-style shortcuts: `ctrl+a` / `ctrl+e`,
22 * `alt+b` / `alt+f`, `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`.
23 * Word movement and deletion use whitespace-delimited boundaries, and
24 * `up` / `down` follow visual wrapped lines. Other modifier combos (e.g.,
25 * `ctrl+s`) and non-insertable control keys bubble up to ancestor
26 * `onKeyPress` handlers.
27 *
28 * Use `onKeyPress` to intercept keys before editing. The handler receives a
29 * normalized semantic key string and structured event metadata; `event.text`
30 * preserves exact insertable characters. Return `false` to prevent the
31 * default editing action.
32 *
33 * @param props - Value, callbacks, sizing, styling, and focus props.
34 * @returns A text input node for the UI tree.
35 *
36 * @example
37 * // Basic input
38 * TextInput({
39 *   value: text,
40 *   onChange: (v) => { text = v; cel.render(); },
41 * })
42 *
43 * @example
44 * // Growing input with max height, Enter submits
45 * TextInput({
46 *   flex: 1,
47 *   maxHeight: 10,
48 *   value: text,
49 *   onChange: handleChange,
50 *   onKeyPress: (key) => {
51 *     if (key === "enter") { handleSend(); return false; }
52 *   },
53 *   placeholder: Text("type a message...", { fgColor: "color08" }),
54 * })
55 */
56export function TextInput(props: TextInputProps): TextInputNode {
57  return { type: "textinput", props };
58}