Add detailed documentation for cursor navigation and text manipulation functions

- Enhanced comments across `delete`, `insert`, `redo`, and cursor-related utility functions for improved clarity.
- Addressed cursor offset handling during vertical navigation to ensure computation consistency.
- Improved logic for backspace and delete operations, including state management and selection clearing.
- Streamlined handling for cursor column alignment in wrapped text during vertical movement.

Author: mike-ward

view_input.v

@@ -288,6 +288,14 @@ fn (cfg &InputCfg) on_char(layout &Layout, mut event Event, mut w Window) {
 	}
 }
 
+// delete removes text from the input field based on the cursor position or
+// selected text range. If text is selected, it deletes the entire selection.
+// Otherwise, it deletes the character before the cursor (backspace) when
+// is_delete is false, or the character after the cursor (delete key) when
+// is_delete is true. The function saves the current state to the undo stack
+// before performing the deletion, updates the cursor position, and clears any
+// text selection. Returns the modified text string, or none if the operation
+// cannot be performed (e.g., cursor at start with backspace).
 fn (cfg &InputCfg) delete(mut w Window, is_delete bool) ?string {
 	mut text := cfg.text.runes()
 	input_state := w.view_state.input_state[cfg.id_focus]
@@ -329,14 +337,23 @@ fn (cfg &InputCfg) delete(mut w Window, is_delete bool) ?string {
 		select_end: input_state.select_end
 	})
 	w.view_state.input_state[cfg.id_focus] = InputState{
-		cursor_pos: cursor_pos
-		select_beg: 0
-		select_end: 0
-		undo:       undo
+		cursor_pos:    cursor_pos
+		select_beg:    0
+		select_end:    0
+		undo:          undo
+		cursor_offset: -1 // view_text.v-on_key_down-up/down handler tests for < 0
 	}
 	return text.string()
 }
 
+// insert adds text to the input field at the current cursor position or
+// replaces the currently selected text. For single-line fixed-width inputs,
+// it validates that the inserted text fits within the available width. If
+// text is selected, the selection is replaced with the inserted text. The
+// function saves the current state to the undo stack before performing the
+// insertion, updates the cursor position to after the inserted text, and
+// clears any text selection. Returns the modified text string, or an error
+// if the cursor position is out of range.
 fn (cfg &InputCfg) insert(s string, mut w Window) !string {
 	// clamp max chars to width of box when single line fixed.
 	if cfg.mode == .single_line && cfg.sizing.width == .fixed {
@@ -376,12 +393,12 @@ fn (cfg &InputCfg) insert(s string, mut w Window) !string {
 		select_beg: input_state.select_beg
 		select_end: input_state.select_end
 	})
-	offset := offset_from_cursor_position()
 	w.view_state.input_state[cfg.id_focus] = InputState{
-		cursor_pos: cursor_pos
-		select_beg: 0
-		select_end: 0
-		undo:       undo
+		cursor_pos:    cursor_pos
+		select_beg:    0
+		select_end:    0
+		undo:          undo
+		cursor_offset: -1 // view_text.v-on_key_down-up/down handler tests for < 0
 	}
 	return text.string()
 }
@@ -464,6 +481,12 @@ pub fn (cfg &InputCfg) undo(mut w Window) string {
 	return memento.text
 }
 
+// redo re-applies a previously undone operation by popping the last state from
+// the redo stack and pushing the current state onto the undo stack. Returns
+// the text content from the restored state. If the redo stack is empty, returns
+// the current text unchanged. The function restores cursor position, selection
+// range, and text content from the saved memento, effectively reversing an undo
+// operation.
 pub fn (cfg &InputCfg) redo(mut w Window) string {
 	input_state := w.view_state.input_state[cfg.id_focus]
 	mut redo := input_state.redo

view_text.v

@@ -340,7 +340,7 @@ fn (tv &TextView) on_key_down(layout &Layout, mut e Event, mut window Window) {
 			return
 		}
 
-		if e.key_code != .up && e.key_code != .down {
+		if (e.key_code != .up && e.key_code != .down) || input_state.cursor_offset < 0 {
 			offset = offset_from_cursor_position(layout.shape, position, window)
 		}
 

xtra_text.v

@@ -411,6 +411,8 @@ pub fn to_clipboard(s ?string) bool {
 	return false
 }
 
+// count_chars returns the total number of visible characters across all
+// strings in the array, used for cursor positioning in wrapped text.
 fn count_chars(strs []string) int {
 	mut count := 0
 	for str in strs {

xtra_text_cursor.v

@@ -1,19 +1,30 @@
 module gui
 
+// cursor_left moves the cursor position one character to the left in the text.
+// It decrements the position by one, but ensures the result never goes below
+// zero, effectively preventing the cursor from moving before the start of the
+// text. Returns the new cursor position.
 fn cursor_left(pos int) int {
 	return int_max(0, pos - 1)
 }
 
+// cursor_right moves the cursor position one character to the right in wrapped
+// text. It increments the position by one, but ensures the result never exceeds
+// the total character count of all text lines combined, effectively preventing
+// the cursor from moving beyond the end of the text. Returns the new cursor
+// position.
 fn cursor_right(strs []string, pos int) int {
 	return int_min(count_chars(strs), pos + 1)
 }
 
 // cursor_up moves the cursor position up one line in wrapped text, attempting
-// to maintain the same horizontal pixel offset. It locates the current line,
-// moves to the previous line, and uses the cursor_offset to find the corresponding
-// column position. If the previous line is shorter than the calculated column,
-// the cursor moves to the end of that line. Returns the original position if
-// already at the first line.
+// to maintain the same horizontal pixel offset. It locates the current line by
+// iterating through the wrapped text lines, moves to the previous line, and
+// uses the cursor_offset to find the corresponding column position. If the
+// cursor_offset is invalid (less than zero, typically -1), it is recomputed
+// from the current cursor position. If the previous line is shorter than the
+// calculated column, the cursor moves to the end of that line. Returns the
+// original position if already at the first line.
 fn cursor_up(shape Shape, cursor_pos int, cursor_offset f32, window &Window) int {
 	mut idx := 0
 	mut offset := 0
@@ -39,7 +50,15 @@ fn cursor_up(shape Shape, cursor_pos int, cursor_offset f32, window &Window) int
 			}
 		}
 
-		cursor_column := cursor_position_from_offset(shape.text_lines[p_idx], cursor_offset,
+		// An offset of less than zero (usually -1) indicates that the offset was
+		// invalidated, likely because of an edit operation like insert/delete.
+		// Compute a new offset based on the current cursor position
+		c_offset := match cursor_offset >= 0 {
+			true { cursor_offset }
+			else { offset_from_cursor_position(shape, cursor_pos, window) }
+		}
+
+		cursor_column := cursor_position_from_offset(shape.text_lines[p_idx], c_offset,
 			shape.text_style, window)
 
 		new_cursor_position := match true {
@@ -53,11 +72,14 @@ fn cursor_up(shape Shape, cursor_pos int, cursor_offset f32, window &Window) int
 }
 
 // cursor_down moves the cursor position down one line in wrapped text, attempting
-// to maintain the same horizontal pixel offset. It locates the current line,
-// moves to the next line, and uses the cursor_offset to find the corresponding
-// column position. If the next line is shorter than the calculated column,
-// the cursor moves to the end of that line. Returns the original position if
-// already at the last line.
+// to maintain the same horizontal pixel offset. It locates the current line by
+// iterating through the wrapped text lines, moves to the next line, and uses
+// the cursor_offset to find the corresponding column position. If the cursor_offset
+// is invalid (less than zero, typically -1), it is recomputed from the current
+// cursor position. If the next line is shorter than the calculated column, the
+// cursor position is adjusted: for lines ending with a newline, it moves to the
+// position before the newline; for the last line, it moves to the end of the line.
+// Returns the original position if already at the last line.
 fn cursor_down(shape Shape, cursor_pos int, cursor_offset f32, window &Window) int {
 	mut idx := 0
 	mut offset := 0
@@ -84,7 +106,15 @@ fn cursor_down(shape Shape, cursor_pos int, cursor_offset f32, window &Window) i
 			}
 		}
 
-		cursor_column := cursor_position_from_offset(n_text, cursor_offset, shape.text_style,
+		// An offset of less than zero (usually -1) indicates that the offset was
+		// invalidated, likely because of an edit operation like insert/delete.
+		// Compute a new offset based on the current cursor position
+		c_offset := match cursor_offset >= 0 {
+			true { cursor_offset }
+			else { offset_from_cursor_position(shape, cursor_pos, window) }
+		}
+
+		cursor_column := cursor_position_from_offset(n_text, c_offset, shape.text_style,
 			window)
 
 		new_cursor_position := match true {
@@ -101,10 +131,16 @@ fn cursor_down(shape Shape, cursor_pos int, cursor_offset f32, window &Window) i
 	return cursor_pos
 }
 
+// cursor_home moves the cursor to the beginning of the text by returning
+// position 0. This is equivalent to the "Home" key behavior, placing the
+// cursor at the start of the entire text content.
 fn cursor_home() int {
 	return 0
 }
 
+// cursor_end moves the cursor to the end of the text by returning the total
+// character count across all wrapped text lines. This is equivalent to the
+// "End" key behavior, placing the cursor at the end of the entire text content.
 fn cursor_end(strs []string) int {
 	return count_chars(strs)
 }