Struct TextFieldEditor 

pub struct TextFieldEditor {
    pub meta: FieldMeta,
    pub editor: Editor<View, FormFieldHost>,
    pub validator: Option<Validator>,
    pub rows: u16,
    /* private fields */
}

A text input field — either single-line or multi-line. Owns its own Editor<View, FormFieldHost> so the full vim grammar applies.

Two construction paths:

• TextFieldEditor::with_meta — used by crate::Form to wire a field with label / validator / placeholder metadata.
• TextFieldEditor::new / TextFieldEditor::with_text — the standalone primitive: a vim-grammar one-line (or N-line) prompt without a surrounding form. Used by hosts that need just the editing surface (: command palette, / ? search prompt, etc.).

In standalone single-line mode, Enter is swallowed by TextFieldEditor::handle_input: there is no “next field” to jump to, and the surrounding host typically interprets Enter as “submit / commit” via its own dispatcher before the keystroke ever reaches the field. This keeps the buffer single-line by construction.

Fields

meta: FieldMeta

editor: Editor<View, FormFieldHost>

validator: Option<Validator>

rows: u16

Visible body height for multi-line fields. Single-line is 1.

Implementations

impl TextFieldEditor

pub fn new(single_line: bool) -> Self

Build a standalone vim-grammar text field with empty buffer. single_line=true suppresses Enter from inserting newlines and sets rows=1; multi-line fields default to rows=3. Hosts that want a different multi-line height should bump rows afterwards or use TextFieldEditor::with_meta.

pub fn with_text(text: &str, single_line: bool) -> Self

Standalone variant pre-populated with text. Cursor lands at the end of the inserted content; mode is Normal.

pub fn with_meta(meta: FieldMeta, rows: u16) -> Self

Form-style constructor: full metadata + render-height. The label / placeholder / required marker render via crate::Form’s ratatui adapter.

pub fn with_validator(self, validator: Validator) -> Self

Attach a validator that runs on field-blur and on submit.

pub fn with_initial(self, text: &str) -> Self

Pre-fill the editor’s buffer with text.

pub fn buffer(&self) -> &View

Borrow the underlying View for span rendering, snapshots, or other read-only consumers.

pub fn buffer_mut(&mut self) -> &mut View

Mutable buffer access. Rare — prefer TextFieldEditor::handle_input which routes through the vim FSM and keeps the cursor consistent.

pub fn text(&self) -> String

Snapshot the buffer’s current text. Multi-line buffers join with '\n'. A single-line field returns only its first (visible) line, so a newline slipped in via o/O/paste can’t submit hidden multi-line data that the renderer never showed.

pub fn set_text(&mut self, text: &str)

Replace contents wholesale, e.g. when opening a prompt with a preset value. Drops the inner editor and rebuilds it; cursor lands at the end of the new content and mode is Normal.

pub fn cursor(&self) -> (usize, usize)

Cursor position as (row, col) in chars. Use directly to place the terminal cursor in the prompt’s render rect.

pub fn coarse_mode(&self) -> CoarseMode

Discipline-agnostic coarse mode of the inner editor (Normal / Insert / Select / …).

A form field only ever needs “am I inserting text or not” — it has no business naming vim-specific states. Reading CoarseMode instead of VimMode keeps this widget usable under any keybinding discipline (#265 / #267).

pub fn enter_insert_at_end(&mut self)

Force the inner editor into Insert mode at the end of the current line. Used by hosts that open a prompt and want the user typing immediately.

pub fn enter_normal(&mut self)

Force the inner editor back to Normal mode (Esc).

pub fn handle_input(&mut self, input: Input) -> bool

Forward a key event to the inner editor’s vim FSM. Returns true when the buffer’s dirty_gen advanced — useful for triggering incremental search on / ? prompts.

In single-line standalone mode, Enter while in Insert is swallowed: there is no next field to jump to. Hosts intercept Enter upstream as “submit”, so the field never sees it in practice; this guard is the belt-and-suspenders.

pub fn dirty_gen(&self) -> u64

View dirty generation — bumps on every content edit.

pub fn set_viewport_width(&mut self, width: u16)

Set the field’s host viewport width. The renderer should call this every frame so motions / scroll stay in-bounds.

pub fn set_viewport_height(&mut self, height: u16)

Set the field’s host viewport height. Single-line fields pass 1.