Struct AutocompleteController 

pub struct AutocompleteController { /* private fields */ }

Owns the popup lifecycle and the (debounced via generation tokens) query plumbing. The host calls sync(host) after every edit; the controller decides whether to open, refresh, or close the popup.

Implementations

impl AutocompleteController

pub fn new( suggestions: Arc<dyn SuggestionSource>, mode: AutocompleteMode, ) -> Self

pub fn with_trigger_opts(self, opts: TriggerOptions) -> Self

Override the trigger-detection options. Used by the search-box controller to disable the column-0 header disambiguation rule (Markdown headers don’t exist in a search input).

pub fn with_debounce(self, debounce: Duration) -> Self

Override the per-refinement debounce window. Tests pass Duration::ZERO so query results land promptly inside drain_results.

pub fn set_redraw_callback(&mut self, cb: RedrawCallback)

Register a redraw callback. Without one, the popup state updates on background threads but the render loop has no signal to wake. Idempotent — safe to call from a host’s first handle_input to lazily bind once the host has a way to trigger redraws.

pub fn is_open(&self) -> bool

Whether the popup is currently interactive — held state AND at least one visible suggestion. Returns false while a query is in flight (state exists but items not yet arrived) or when a query returned no matches: in both cases the popup is not drawn and must not intercept key events, so Esc/Up/Down/Tab fall through to the host (modal Esc closes the modal, list Up/Down navigates files, etc).

pub fn state(&self) -> Option<&AutocompleteState>

Borrow the popup state for read-only inspection (rendering, query introspection, tests). Returns None whenever the popup is not active.

pub fn state_mut(&mut self) -> Option<&mut AutocompleteState>

Borrow the popup state mutably. The only legitimate caller-side use today is the host’s render path, which re-anchors state.anchor from the freshly rendered caret position so the popup follows the cursor without a one-frame lag. Mutating items / highlighted / scroll_offset from outside the controller will desync the popup; use the dedicated sync / refresh_if_open / handle_key entry points for those.

pub fn close(&mut self)

Close the popup immediately. Safe to call when already closed. Use whenever focus moves away from the host or the host triggers a buffer-replacement that invalidates the trigger context (e.g. set_text).

Also aborts any in-flight query task — without this, pressing Esc during the 80ms debounce window leaks a spawned tokio task that continues to the SQLite hit and posts a result discarded later via generation mismatch.

pub fn handle_key<H: AutocompleteHost>( &mut self, key: KeyEvent, host: &H, ) -> HandleKeyOutcome

Route a key event through the popup when one is open. Returns a HandleKeyOutcome so the host can decide whether to apply an accept, fall through to its own key handling, etc. The controller never mutates the host’s buffer directly — on accept it returns an AcceptAction describing the replacement.

pub fn sync<H: AutocompleteHost>(&mut self, host: &H)

Inspect the host’s current buffer + cursor and reconcile the popup state. Call this after a text edit (insert / delete / paste / any change that modifies the buffer). Will open a fresh popup when the cursor lands inside a trigger context, refresh an open popup’s range/query/anchor, or close the popup when the trigger is gone.

pub fn refresh_if_open<H: AutocompleteHost>(&mut self, host: &H)

Refresh the popup state for a cursor-only event (arrow keys, click, Home/End, etc). If the popup is closed, this is a no-op — cursor movement never opens a new popup. If the popup is open, it follows the cursor: query, range, and anchor update; the popup closes when the cursor leaves the trigger range.

pub fn poll_results(&mut self)

Drain pending query responses and apply the latest one whose generation matches the controller’s current generation. Older responses (stale) are discarded.