xonecas.io
70160
Ce

cel-tui / commit b1bc988

feat(core): improve TextInput keyboard editing

xonecas2026-04-11 b1bc988152786a3c536716076b532a5e4cb7eec4 parent 25d7de3

14 files changed

README.md+1−0
@@ -69,6 +69,7 @@ cel.viewport(() =>
6969 - **16-color palette** — numbered slots (`"color00"`–`"color15"`) mapped to ANSI 16 by default. Custom themes can remap to different ANSI indices or 24-bit true color.
7070 - **Cell buffer rendering** — styled cells, differential updates, synchronized output.
7171 - **Kitty-first keyboard input** — cel-tui enables Kitty level 1 for full modifier fidelity, works well in `tmux` with `set -s extended-keys on`, and accepts recoverable legacy encodings when the host does not preserve a pure Kitty stream.
72+- **TextInput editing shortcuts** — focused inputs support familiar readline-style editing (`ctrl+a/e`, `alt+b/f`, `ctrl+left/right`, `ctrl+w`, `alt+d`), and `up` / `down` follow visual wrapped lines.
7273
7374 ## Terminal Compatibility
7475
docs/skill/cel-tui/SKILL.md+1−1
@@ -264,7 +264,7 @@ SyntaxHighlight(source, "javascript", { theme: "dark-plus" });
264264
265265 - **State is external** — the framework has no state. Mutate variables then call `cel.render()`.
266266 - **Text is a pure leaf** — no sizing props, no children. Parent controls the box.
267-- **TextInput consumes insertable text and editing/navigation keys** when focused (printable text, arrows, backspace, Enter, Tab). Enter inserts a newline by default. Use `onKeyPress` on TextInput to intercept keys before editing — return `false` to prevent the default action (e.g., intercept Enter for submit). `onKeyPress` receives normalized semantic key strings, while inserted text preserves the original characters (uppercase `A` arrives as key `"a"` but inserts `"A"`). Modifier combos (`ct …
267+- **TextInput consumes insertable text and editing/navigation keys** when focused (printable text, arrows, backspace, Enter, Tab), plus readline-style shortcuts: `ctrl+a` / `ctrl+e`, `alt+b` / `alt+f`, `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`. Word movement and deletion are whitespace-delimited, and `up` / `down` follow visual wrapped lines. Enter inserts a newline by default. Use `onKeyPress` on TextInput to intercept keys before editing — return `false` to prevent the default action …
268268 - **Escape unfocuses** the current element. Tab/Shift+Tab traverses focusable elements (wraps around). After Escape, traversal continues from where focus was lost.
269269 - **Enter activates** a focused container's `onClick`. If no `onClick`, Enter reaches `onKeyPress`.
270270 - **`focusable: true`** without `onClick` makes a container keyboard-focusable (receives `onKeyPress` events via Tab). Used by stateful components like `Select`.
docs/skill/cel-tui/references/api.md+1−1
@@ -132,7 +132,7 @@ TextInput({
132132 });
133133 ```
134134
135-When focused, TextInput consumes insertable text plus editing/navigation keys. Modifier combos and non-insertable control keys bubble. Key strings are semantic identifiers for handlers, not necessarily the exact inserted text — uppercase `A` normalizes to key `"a"` while still inserting `"A"`.
135+When focused, TextInput consumes insertable text plus editing/navigation keys, including readline-style shortcuts: `ctrl+a` / `ctrl+e`, `alt+b` / `alt+f`, `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`. Word movement and deletion are whitespace-delimited, and `up` / `down` navigate visual wrapped lines. Other modifier combos and non-insertable control keys bubble. Key strings are semantic identifiers for handlers, not necessarily the exact inserted text — uppercase `A` normalizes to key `"a …
136136
137137 ## Sizing Strategies
138138
packages/core/src/cel.ts+22−1
@@ -27,7 +27,10 @@ import {
2727 insertChar,
2828 deleteBackward,
2929 deleteForward,
30+ deleteWordBackward,
31+ deleteWordForward,
3032 moveCursor,
33+ moveCursorByWord,
3134 type EditState,
3235 } from "./text-edit.js";
3336 import type { Terminal } from "./terminal.js";
@@ -854,12 +857,20 @@ function handleKeyEvent(event: KeyInput): void {
854857 case "delete":
855858 newState = deleteForward(editState);
856859 break;
860+ case "ctrl+w":
861+ newState = deleteWordBackward(editState);
862+ break;
863+ case "alt+d":
864+ newState = deleteWordForward(editState);
865+ break;
857866 case "left":
858867 case "right":
859868 case "up":
860869 case "down":
861870 case "home":
862871 case "end":
872+ case "ctrl+a":
873+ case "ctrl+e":
863874 {
864875 const tiPadX =
865876 (focusedInput.node as TextInputNode).props.padding?.x ?? 0;
@@ -867,13 +878,23 @@ function handleKeyEvent(event: KeyInput): void {
867878 0,
868879 focusedInput.rect.width - tiPadX * 2,
869880 );
881+ const direction =
882+ key === "ctrl+a" ? "home" : key === "ctrl+e" ? "end" : key;
870883 newState = moveCursor(
871884 editState,
872- key as "left" | "right" | "up" | "down" | "home" | "end",
885+ direction as "left" | "right" | "up" | "down" | "home" | "end",
873886 contentWidth,
874887 );
875888 }
876889 break;
890+ case "alt+b":
891+ case "ctrl+left":
892+ newState = moveCursorByWord(editState, "backward");
893+ break;
894+ case "alt+f":
895+ case "ctrl+right":
896+ newState = moveCursorByWord(editState, "forward");
897+ break;
877898 case "enter":
878899 case "shift+enter":
879900 newState = insertChar(editState, "\n");
packages/core/src/keys.test.ts+12−1
@@ -305,7 +305,18 @@ describe("isEditingKey", () => {
305305 expect(isEditingKey("shift+enter")).toBe(true);
306306 });
307307
308- test("modifier combos are NOT editing keys", () => {
308+ test("TextInput modifier editing shortcuts are editing keys", () => {
309+ expect(isEditingKey("ctrl+a")).toBe(true);
310+ expect(isEditingKey("ctrl+e")).toBe(true);
311+ expect(isEditingKey("alt+b")).toBe(true);
312+ expect(isEditingKey("alt+f")).toBe(true);
313+ expect(isEditingKey("ctrl+left")).toBe(true);
314+ expect(isEditingKey("ctrl+right")).toBe(true);
315+ expect(isEditingKey("ctrl+w")).toBe(true);
316+ expect(isEditingKey("alt+d")).toBe(true);
317+ });
318+
319+ test("other modifier combos are NOT editing keys", () => {
309320 expect(isEditingKey("ctrl+s")).toBe(false);
310321 expect(isEditingKey("ctrl+r")).toBe(false);
311322 expect(isEditingKey("alt+x")).toBe(false);
packages/core/src/keys.ts+12−2
@@ -306,8 +306,10 @@ export function normalizeKey(key: string): string {
306306 * Check whether a semantic key represents TextInput editing/navigation.
307307 *
308308 * Single-character semantic keys represent insertable text, while named keys
309- * like `"enter"` and `"left"` represent editing/navigation actions. Modifier
310- * combos (`ctrl+s`, `alt+x`) are NOT editing keys and should bubble.
309+ * like `"enter"` and `"left"` represent editing/navigation actions. Most
310+ * modifier combos (`ctrl+s`, `alt+x`) are NOT editing keys and should bubble,
311+ * but TextInput consumes a small set of readline-style shortcuts for cursor
312+ * movement and word deletion.
311313 */
312314 export function isEditingKey(key: string): boolean {
313315 if (key.length === 1) return true;
@@ -326,6 +328,14 @@ export function isEditingKey(key: string): boolean {
326328 "space",
327329 "plus",
328330 "shift+enter",
331+ "ctrl+a",
332+ "ctrl+e",
333+ "alt+b",
334+ "alt+f",
335+ "ctrl+left",
336+ "ctrl+right",
337+ "ctrl+w",
338+ "alt+d",
329339 ]);
330340
331341 return editingKeys.has(key);
packages/core/src/primitives/text-input.ts+7−3
@@ -12,9 +12,13 @@ import type { TextInputNode, TextInputProps } from "@cel-tui/types";
1212 * responds to mouse wheel automatically.
1313 *
1414 * TextInput is always focusable. When focused, it consumes insertable text
15- * plus editing/navigation keys (arrows, backspace, delete, Enter, Tab).
16- * Modifier combos (e.g., `ctrl+s`) and non-insertable control keys bubble
17- * up to ancestor `onKeyPress` handlers.
15+ * plus editing/navigation keys (arrows, backspace, delete, Enter, Tab),
16+ * along with a small set of readline-style shortcuts: `ctrl+a` / `ctrl+e`,
17+ * `alt+b` / `alt+f`, `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`.
18+ * Word movement and deletion use whitespace-delimited boundaries, and
19+ * `up` / `down` follow visual wrapped lines. Other modifier combos (e.g.,
20+ * `ctrl+s`) and non-insertable control keys bubble up to ancestor
21+ * `onKeyPress` handlers.
1822 *
1923 * Use `onKeyPress` to intercept keys before editing. The handler receives a
2024 * normalized semantic key string; inserted text preserves the original
packages/core/src/text-edit.test.ts+83−0
@@ -3,7 +3,10 @@ import {
33 insertChar,
44 deleteBackward,
55 deleteForward,
6+ deleteWordBackward,
7+ deleteWordForward,
68 moveCursor,
9+ moveCursorByWord,
710 type EditState,
811 } from "./text-edit.js";
912
@@ -110,6 +113,71 @@ describe("text editing", () => {
110113 });
111114 });
112115
116+ describe("deleteWordBackward", () => {
117+ test("deletes previous word", () => {
118+ const result = deleteWordBackward(state("hello brave world", 17));
119+ expect(result.value).toBe("hello brave ");
120+ expect(result.cursor).toBe(12);
121+ });
122+
123+ test("deletes previous word and preceding spaces as one chunk", () => {
124+ const result = deleteWordBackward(state("hello world", 8));
125+ expect(result.value).toBe("world");
126+ expect(result.cursor).toBe(0);
127+ });
128+
129+ test("deletes an emoji word without splitting the grapheme", () => {
130+ const result = deleteWordBackward(state("go 😀 now", 5));
131+ expect(result.value).toBe("go now");
132+ expect(result.cursor).toBe(3);
133+ });
134+ });
135+
136+ describe("deleteWordForward", () => {
137+ test("deletes next word without trimming following whitespace", () => {
138+ const result = deleteWordForward(state("hello brave world", 6));
139+ expect(result.value).toBe("hello world");
140+ expect(result.cursor).toBe(6);
141+ });
142+
143+ test("deletes next word and leading spaces as one chunk", () => {
144+ const result = deleteWordForward(state("hello world", 5));
145+ expect(result.value).toBe("hello");
146+ expect(result.cursor).toBe(5);
147+ });
148+
149+ test("deletes an emoji word without splitting the grapheme", () => {
150+ const result = deleteWordForward(state("😀 test", 0));
151+ expect(result.value).toBe(" test");
152+ expect(result.cursor).toBe(0);
153+ });
154+ });
155+
156+ describe("moveCursorByWord", () => {
157+ test("backward moves to the start of the previous word", () => {
158+ const result = moveCursorByWord(
159+ state("hello brave world", 17),
160+ "backward",
161+ );
162+ expect(result.cursor).toBe(12);
163+ });
164+
165+ test("backward skips trailing whitespace before the previous word", () => {
166+ const result = moveCursorByWord(state("hello ", 8), "backward");
167+ expect(result.cursor).toBe(0);
168+ });
169+
170+ test("forward moves to the end of the next word", () => {
171+ const result = moveCursorByWord(state("hello brave world", 0), "forward");
172+ expect(result.cursor).toBe(5);
173+ });
174+
175+ test("forward skips leading whitespace before the next word", () => {
176+ const result = moveCursorByWord(state(" hello", 0), "forward");
177+ expect(result.cursor).toBe(8);
178+ });
179+ });
180+
113181 describe("moveCursor", () => {
114182 test("left moves back one", () => {
115183 const result = moveCursor(state("hello", 3), "left");
@@ -163,6 +231,21 @@ describe("text editing", () => {
163231 expect(result.cursor).toBe(5);
164232 });
165233
234+ test("up follows visual wrapped lines", () => {
235+ const result = moveCursor(state("foo bar baz", 11), "up", 6);
236+ expect(result.cursor).toBe(7);
237+ });
238+
239+ test("down follows visual wrapped lines", () => {
240+ const result = moveCursor(state("foo bar baz", 0), "down", 6);
241+ expect(result.cursor).toBe(4);
242+ });
243+
244+ test("down clamps to the end of a shorter wrapped line", () => {
245+ const result = moveCursor(state("foo bar baz", 7), "down", 6);
246+ expect(result.cursor).toBe(11);
247+ });
248+
166249 test("up moves to previous line", () => {
167250 const result = moveCursor(state("abc\ndef", 5), "up", 10);
168251 // Cursor at "e" (offset 5), up should go to offset 1 ("b")
packages/core/src/text-edit.ts+99−41
@@ -1,3 +1,5 @@
1+import { layoutText } from "./text-layout.js";
2+
13 /**
24 * Framework-managed editing state for TextInput.
35 */
@@ -9,6 +11,7 @@ export interface EditState {
911 }
1012
1113 const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
14+const WHITESPACE_RE = /^\s+$/u;
1215
1316 /**
1417 * Get the grapheme boundary before the given cursor position.
@@ -39,6 +42,46 @@ function nextGraphemeBoundary(value: string, cursor: number): number {
3942 return value.length;
4043 }
4144
45+function isWhitespaceGrapheme(segment: string): boolean {
46+ return WHITESPACE_RE.test(segment);
47+}
48+
49+function findWordBoundaryBackward(value: string, cursor: number): number {
50+ let boundary = cursor;
51+
52+ while (boundary > 0) {
53+ const prev = prevGraphemeBoundary(value, boundary);
54+ if (!isWhitespaceGrapheme(value.slice(prev, boundary))) break;
55+ boundary = prev;
56+ }
57+
58+ while (boundary > 0) {
59+ const prev = prevGraphemeBoundary(value, boundary);
60+ if (isWhitespaceGrapheme(value.slice(prev, boundary))) break;
61+ boundary = prev;
62+ }
63+
64+ return boundary;
65+}
66+
67+function findWordBoundaryForward(value: string, cursor: number): number {
68+ let boundary = cursor;
69+
70+ while (boundary < value.length) {
71+ const next = nextGraphemeBoundary(value, boundary);
72+ if (!isWhitespaceGrapheme(value.slice(boundary, next))) break;
73+ boundary = next;
74+ }
75+
76+ while (boundary < value.length) {
77+ const next = nextGraphemeBoundary(value, boundary);
78+ if (isWhitespaceGrapheme(value.slice(boundary, next))) break;
79+ boundary = next;
80+ }
81+
82+ return boundary;
83+}
84+
4285 /**
4386 * Insert a character (or string) at the cursor position.
4487 */
@@ -78,6 +121,32 @@ export function deleteForward(state: EditState): EditState {
78121 };
79122 }
80123
124+/**
125+ * Delete the whitespace-delimited word before the cursor.
126+ */
127+export function deleteWordBackward(state: EditState): EditState {
128+ const { value, cursor } = state;
129+ const boundary = findWordBoundaryBackward(value, cursor);
130+ if (boundary === cursor) return state;
131+ return {
132+ value: value.slice(0, boundary) + value.slice(cursor),
133+ cursor: boundary,
134+ };
135+}
136+
137+/**
138+ * Delete the whitespace-delimited word after the cursor.
139+ */
140+export function deleteWordForward(state: EditState): EditState {
141+ const { value, cursor } = state;
142+ const boundary = findWordBoundaryForward(value, cursor);
143+ if (boundary === cursor) return state;
144+ return {
145+ value: value.slice(0, cursor) + value.slice(boundary),
146+ cursor,
147+ };
148+}
149+
81150 /**
82151 * Move the cursor in the given direction.
83152 * Left/right movement respects grapheme boundaries.
@@ -115,8 +184,24 @@ export function moveCursor(
115184 }
116185
117186 /**
118- * Vertical cursor movement — maps cursor offset to line/column,
119- * moves up or down a line, then maps back to offset.
187+ * Move the cursor by one whitespace-delimited word.
188+ */
189+export function moveCursorByWord(
190+ state: EditState,
191+ direction: "backward" | "forward",
192+): EditState {
193+ const { value, cursor } = state;
194+ const nextCursor =
195+ direction === "backward"
196+ ? findWordBoundaryBackward(value, cursor)
197+ : findWordBoundaryForward(value, cursor);
198+
199+ if (nextCursor === cursor) return state;
200+ return { value, cursor: nextCursor };
201+}
202+
203+/**
204+ * Vertical cursor movement follows the visual wrapped lines used for painting.
120205 */
121206 function moveVertical(
122207 state: EditState,
@@ -124,49 +209,22 @@ function moveVertical(
124209 width: number,
125210 ): EditState {
126211 const { value, cursor } = state;
127- const lines = value.split("\n");
128-
129- // Find which line and column the cursor is on
130- let offset = 0;
131- let cursorLine = 0;
132- let cursorCol = 0;
133-
134- for (let i = 0; i < lines.length; i++) {
135- const lineLen = lines[i]!.length;
136- if (cursor >= offset && cursor <= offset + lineLen) {
137- cursorLine = i;
138- cursorCol = cursor - offset;
139- break;
140- }
141- offset += lineLen + 1; // +1 for \n
142- }
143-
144- // Move line
145- let targetLine = cursorLine;
146- if (direction === "up") {
147- targetLine = Math.max(0, cursorLine - 1);
148- } else {
149- targetLine = Math.min(lines.length - 1, cursorLine + 1);
150- }
151-
152- if (targetLine === cursorLine) {
153- // Can't move — go to start (up) or end (down)
212+ const textLayout = layoutText(value, width, "word");
213+ const pos = textLayout.offsetToPosition(cursor);
214+ const targetLine =
215+ direction === "up"
216+ ? Math.max(0, pos.line - 1)
217+ : Math.min(textLayout.lineCount - 1, pos.line + 1);
218+
219+ if (targetLine === pos.line) {
154220 return {
155221 value,
156222 cursor: direction === "up" ? 0 : value.length,
157223 };
158224 }
159225
160- // Map column to new line, clamping to line length
161- const targetLineLen = lines[targetLine]!.length;
162- const targetCol = Math.min(cursorCol, targetLineLen);
163-
164- // Compute new offset
165- let newOffset = 0;
166- for (let i = 0; i < targetLine; i++) {
167- newOffset += lines[i]!.length + 1;
168- }
169- newOffset += targetCol;
170-
171- return { value, cursor: newOffset };
226+ return {
227+ value,
228+ cursor: textLayout.positionToOffset(targetLine, pos.col),
229+ };
172230 }
packages/core/src/text-input.test.ts+225−0
@@ -8,7 +8,17 @@ import { kittyEncode } from "./test-helpers.js";
88
99 const ENTER = kittyEncode("enter");
1010 const BACKSPACE = kittyEncode("backspace");
11+const CTRL_A = kittyEncode("ctrl+a");
12+const CTRL_E = kittyEncode("ctrl+e");
13+const CTRL_LEFT = kittyEncode("ctrl+left");
14+const CTRL_RIGHT = kittyEncode("ctrl+right");
1115 const CTRL_S = kittyEncode("ctrl+s");
16+const CTRL_W = kittyEncode("ctrl+w");
17+const ALT_B = kittyEncode("alt+b");
18+const ALT_D = kittyEncode("alt+d");
19+const ALT_F = kittyEncode("alt+f");
20+const UP = kittyEncode("up");
21+const DOWN = kittyEncode("down");
1222 const LEFT = kittyEncode("left");
1323 const LEGACY_CTRL_R = "\x12";
1424 const LEGACY_ALT_X = "\x1bx";
@@ -290,6 +300,221 @@ describe("TextInput integration", () => {
290300 expect(value).toBe("ab");
291301 });
292302
303+ test("ctrl+a and ctrl+e move to the start and end of the value", async () => {
304+ const term = setup(20, 3);
305+ let value = "hello";
306+ const onChange = (v: string) => {
307+ value = v;
308+ };
309+ cel.viewport(() =>
310+ VStack({}, [
311+ TextInput({
312+ value,
313+ focused: true,
314+ onChange,
315+ }),
316+ ]),
317+ );
318+ await waitForRender();
319+
320+ term.sendInput(CTRL_A);
321+ await waitForRender();
322+ term.sendInput("X");
323+ await waitForRender();
324+
325+ expect(value).toBe("Xhello");
326+
327+ term.sendInput(CTRL_E);
328+ await waitForRender();
329+ term.sendInput("!");
330+ await waitForRender();
331+
332+ expect(value).toBe("Xhello!");
333+ });
334+
335+ test("alt+b and alt+f move by whitespace-delimited words", async () => {
336+ const term = setup(20, 3);
337+ let value = "hello brave world";
338+ const onChange = (v: string) => {
339+ value = v;
340+ };
341+ cel.viewport(() =>
342+ VStack({}, [
343+ TextInput({
344+ value,
345+ focused: true,
346+ onChange,
347+ }),
348+ ]),
349+ );
350+ await waitForRender();
351+
352+ term.sendInput(ALT_B);
353+ await waitForRender();
354+ term.sendInput("!");
355+ await waitForRender();
356+
357+ expect(value).toBe("hello brave !world");
358+
359+ term.sendInput(CTRL_A);
360+ await waitForRender();
361+ term.sendInput(ALT_F);
362+ await waitForRender();
363+ term.sendInput("?");
364+ await waitForRender();
365+
366+ expect(value).toBe("hello? brave !world");
367+ });
368+
369+ test("ctrl+left and ctrl+right move by whitespace-delimited words", async () => {
370+ const term = setup(20, 3);
371+ let value = "hello brave world";
372+ const onChange = (v: string) => {
373+ value = v;
374+ };
375+ cel.viewport(() =>
376+ VStack({}, [
377+ TextInput({
378+ value,
379+ focused: true,
380+ onChange,
381+ }),
382+ ]),
383+ );
384+ await waitForRender();
385+
386+ term.sendInput(CTRL_LEFT);
387+ await waitForRender();
388+ term.sendInput("!");
389+ await waitForRender();
390+
391+ expect(value).toBe("hello brave !world");
392+
393+ term.sendInput(CTRL_A);
394+ await waitForRender();
395+ term.sendInput(CTRL_RIGHT);
396+ await waitForRender();
397+ term.sendInput("?");
398+ await waitForRender();
399+
400+ expect(value).toBe("hello? brave !world");
401+ });
402+
403+ test("ctrl+w and alt+d delete by whitespace-delimited words", async () => {
404+ const term = setup(20, 3);
405+ let value = "hello brave world";
406+ const onChange = (v: string) => {
407+ value = v;
408+ };
409+ cel.viewport(() =>
410+ VStack({}, [
411+ TextInput({
412+ value,
413+ focused: true,
414+ onChange,
415+ }),
416+ ]),
417+ );
418+ await waitForRender();
419+
420+ term.sendInput(CTRL_W);
421+ await waitForRender();
422+
423+ expect(value).toBe("hello brave ");
424+
425+ term.sendInput(CTRL_A);
426+ await waitForRender();
427+ term.sendInput(ALT_D);
428+ await waitForRender();
429+
430+ expect(value).toBe(" brave ");
431+ });
432+
433+ test("up follows visual wrapped lines in TextInput", async () => {
434+ const term = setup(20, 3);
435+ let value = "foo bar baz";
436+ const onChange = (v: string) => {
437+ value = v;
438+ };
439+ cel.viewport(() =>
440+ VStack({}, [
441+ TextInput({
442+ width: 6,
443+ value,
444+ focused: true,
445+ onChange,
446+ }),
447+ ]),
448+ );
449+ await waitForRender();
450+
451+ term.sendInput(UP);
452+ await waitForRender();
453+ term.sendInput("!");
454+ await waitForRender();
455+
456+ expect(value).toBe("foo bar! baz");
457+ });
458+
459+ test("down follows visual wrapped lines in TextInput", async () => {
460+ const term = setup(20, 3);
461+ let value = "foo bar baz";
462+ const onChange = (v: string) => {
463+ value = v;
464+ };
465+ cel.viewport(() =>
466+ VStack({}, [
467+ TextInput({
468+ width: 6,
469+ value,
470+ focused: true,
471+ onChange,
472+ }),
473+ ]),
474+ );
475+ await waitForRender();
476+
477+ term.sendInput(CTRL_A);
478+ await waitForRender();
479+ term.sendInput(DOWN);
480+ await waitForRender();
481+ term.sendInput("?");
482+ await waitForRender();
483+
484+ expect(value).toBe("foo ?bar baz");
485+ });
486+
487+ test("TextInput consumes editing modifier shortcuts instead of bubbling them", async () => {
488+ const term = setup(20, 3);
489+ let parentKey = "";
490+ let value = "hello brave world";
491+ cel.viewport(() =>
492+ VStack(
493+ {
494+ onKeyPress: (key) => {
495+ parentKey = key;
496+ },
497+ },
498+ [
499+ TextInput({
500+ value,
501+ focused: true,
502+ onChange: (v) => {
503+ value = v;
504+ },
505+ }),
506+ ],
507+ ),
508+ );
509+ await waitForRender();
510+
511+ term.sendInput(CTRL_W);
512+ await waitForRender();
513+
514+ expect(value).toBe("hello brave ");
515+ expect(parentKey).toBe("");
516+ });
517+
293518 test("enter inserts newline by default", async () => {
294519 const term = setup(20, 3);
295520 let value = "ab";
packages/core/src/text-layout.test.ts+5−0
@@ -15,6 +15,10 @@ describe("text-layout", () => {
1515 expect(result.offsetToPosition(4)).toEqual({ line: 1, col: 0 });
1616 expect(result.offsetToPosition(5)).toEqual({ line: 1, col: 1 });
1717 expect(result.offsetToPosition(8)).toEqual({ line: 2, col: 0 });
18+
19+ expect(result.positionToOffset(1, 0)).toBe(4);
20+ expect(result.positionToOffset(1, 1)).toBe(5);
21+ expect(result.positionToOffset(2, 0)).toBe(8);
1822 });
1923
2024 test("preserves repeated and trailing spaces", () => {
@@ -44,5 +48,6 @@ describe("text-layout", () => {
4448 { text: "世界", width: 4 },
4549 ]);
4650 expect(result.offsetToPosition(2)).toEqual({ line: 1, col: 0 });
51+ expect(result.positionToOffset(1, 1)).toBe(3);
4752 });
4853 });
packages/core/src/text-layout.ts+34−0
@@ -18,6 +18,7 @@ export interface TextLayoutResult {
1818 lines: VisualLine[];
1919 lineCount: number;
2020 offsetToPosition(offset: number): VisualPosition;
21+ positionToOffset(line: number, col: number): number;
2122 }
2223
2324 interface GraphemeInfo {
@@ -78,6 +79,9 @@ export function layoutText(
7879 offsetToPosition(offset: number): VisualPosition {
7980 return offsetToPosition(lines, clamp(offset, 0, value.length));
8081 },
82+ positionToOffset(line: number, col: number): number {
83+ return positionToOffset(lines, line, col);
84+ },
8185 };
8286 }
8387
@@ -245,6 +249,36 @@ function offsetToPosition(
245249 return { line: lines.length - 1, col: last.line.width };
246250 }
247251
252+function positionToOffset(
253+ lines: VisualLineData[],
254+ line: number,
255+ col: number,
256+): number {
257+ const lineIndex = clamp(line, 0, lines.length - 1);
258+ const entry = lines[lineIndex]!;
259+ const targetCol = Math.max(0, col);
260+
261+ if (targetCol === 0 || entry.graphemes.length === 0) {
262+ return entry.line.startOffset;
263+ }
264+
265+ let currentCol = 0;
266+ for (const grapheme of entry.graphemes) {
267+ const nextCol = currentCol + grapheme.width;
268+ if (targetCol < nextCol) {
269+ return targetCol - currentCol < nextCol - targetCol
270+ ? grapheme.startOffset
271+ : grapheme.endOffset;
272+ }
273+ if (targetCol === nextCol) {
274+ return grapheme.endOffset;
275+ }
276+ currentCol = nextCol;
277+ }
278+
279+ return entry.line.endOffset;
280+}
281+
248282 function clamp(value: number, min: number, max: number): number {
249283 return Math.max(min, Math.min(max, value));
250284 }
packages/types/src/index.ts+7−3
@@ -258,7 +258,7 @@ export interface ContainerProps extends StyleProps {
258258 /**
259259 * Called on key events that bubble up to this container.
260260 * Keys are first handled by the focused element; unconsumed keys
261- * (e.g., modifier combos like `"ctrl+s"`) bubble up through ancestors.
261+ * (e.g., non-editing shortcuts like `"ctrl+s"`) bubble up through ancestors.
262262 * The root container's `onKeyPress` acts as the global key handler.
263263 *
264264 * Return `false` to indicate the key was **not consumed** — it will
@@ -315,8 +315,12 @@ export interface TextProps extends StyleProps {
315315 * Word-wrap is always on.
316316 *
317317 * When focused, TextInput consumes insertable text plus editing/navigation
318- * keys (arrows, backspace, delete, Enter, Tab). Modifier combos and
319- * non-insertable control keys bubble to ancestor {@link onKeyPress} handlers.
318+ * keys (arrows, backspace, delete, Enter, Tab), along with a small set of
319+ * readline-style shortcuts: `ctrl+a` / `ctrl+e`, `alt+b` / `alt+f`,
320+ * `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`. Word movement and
321+ * deletion use whitespace-delimited boundaries, and `up` / `down` follow
322+ * visual wrapped lines. Other modifier combos and non-insertable control
323+ * keys bubble to ancestor {@link onKeyPress} handlers.
320324 */
321325 export interface TextInputProps extends ContainerProps {
322326 /** Current text content. Controlled — the app owns this value. */
spec.md+3−3
@@ -361,7 +361,7 @@ Focus is implicit — no `focusable` prop needed for the common case:
361361
362362 **Escape** unfocuses the current element. **Tab / Shift+Tab** moves focus to the next/previous focusable element in document order (depth-first tree traversal).
363363
364-When a TextInput is focused, insertable text and text-editing keys (arrows, backspace, delete, Enter, Tab) go to the input. Modifier combos (e.g., `ctrl+s`) are not consumed by TextInput and bubble up. The TextInput's `onKeyPress` handler fires before editing — returning `false` prevents the default action, letting the app override any key's behavior. Legacy control-byte encodings are normalized when possible, so recoverable shortcuts still bubble in environments like `tmux`. Press Escape to l …
364+When a TextInput is focused, insertable text and text-editing keys go to the input. This includes arrows, backspace, delete, Enter, Tab, plus readline-style shortcuts: `ctrl+a` / `ctrl+e` for start/end, `alt+b` / `alt+f` and `ctrl+left` / `ctrl+right` for whitespace-delimited word movement, and `ctrl+w` / `alt+d` for whitespace-delimited word deletion. `up` and `down` follow the input's visual wrapped lines, not just newline-separated hard lines. Other modifier combos (e.g., `ctrl+s`) are not co …
365365
366366 ### Uncontrolled Focus
367367
@@ -482,7 +482,7 @@ cel-tui enables bracketed paste mode so the terminal wraps pasted content with `
482482 1. **Topmost layer** receives the key event
483483 2. If a **TextInput** is focused:
484484 - If the TextInput has `onKeyPress`, call it first. If `onKeyPress` returns `false`, the key's **default editing action is prevented** — no character insertion, no cursor movement, nothing. The key is consumed.
485- - Otherwise, the TextInput processes insertable text and editing/navigation keys (arrows, backspace, delete, Enter, Tab). Modifier combos (e.g., `ctrl+s`) and non-insertable control keys are not editing keys and pass through.
485+ - Otherwise, the TextInput processes insertable text, editing/navigation keys (arrows, backspace, delete, Enter, Tab), and these modifier-based editing shortcuts: `ctrl+a` / `ctrl+e`, `alt+b` / `alt+f`, `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`. Word movement and deletion use whitespace-delimited boundaries, and `up` / `down` navigate visual wrapped lines. Other modifier combos (e.g., `ctrl+s`) and non-insertable control keys are not editing keys and pass through.
486486 3. If a **clickable container** is focused, Enter fires `onClick`. Other keys pass through.
487487 4. Unconsumed keys **bubble up** through ancestors — each `onKeyPress` handler in the ancestor chain is called from innermost to root.
488488 5. A handler that returns `false` signals the key was **not consumed** — bubbling continues to the next ancestor. Any other return (`undefined`, `true`, or no return) **stops bubbling** (backward-compatible: existing `void` handlers consume by default).
@@ -650,7 +650,7 @@ Container sizing props (`width`, `height`, `flex`, `min*`, `max*`, `padding`), f
650650 | `onKeyPress` | `(key: string) => boolean \| void` | Key handler, fires before editing. Receives normalized semantic key strings. Return `false` to prevent the default editing action. |
651651 | `placeholder` | `TextNode` | Text node shown when value is empty (pass a `Text()` call) |
652652
653-Word-wrap is always on. Cursor position is framework-managed. In bracketed paste mode, pasted text is inserted literally at the cursor as one batch edit: one `onChange`, no `onKeyPress`, newlines and tabs preserved.
653+Word-wrap is always on. Cursor position is framework-managed. Supported editing shortcuts include `ctrl+a` / `ctrl+e`, `alt+b` / `alt+f`, `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`; word movement and deletion use whitespace-delimited boundaries, and `up` / `down` navigate visual wrapped lines. In bracketed paste mode, pasted text is inserted literally at the cursor as one batch edit: one `onChange`, no `onKeyPress`, newlines and tabs preserved.
654654
655655 #### Growing / Shrinking Pattern