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}