komp_ac/client/src/ui/docs/ui_redraws.md

UI Redraw Logic (needs_redraw Flag)

Problem

The main UI loop in client/src/ui/handlers/ui.rs uses crossterm_event::poll with a short timeout to remain responsive to both user input and asynchronous operations (like login results arriving via channels). However, calling terminal.draw() unconditionally in every loop iteration caused constant UI refreshes and high CPU usage, even when idle.

Solution

A boolean flag, needs_redraw, was introduced in the main loop scope to control when the UI is actually redrawn.

Mechanism

1. Initialization: needs_redraw is initialized to true before the loop starts to ensure the initial UI state is drawn.
2. Conditional Drawing: The terminal.draw(...) call is wrapped in an if needs_redraw { ... } block.
3. Flag Reset: Immediately after a successful terminal.draw(...) call, needs_redraw is set back to false.
4. Triggering Redraws: The needs_redraw flag is explicitly set to true only when a redraw is actually required.

When needs_redraw Must Be Set to true

To ensure the UI stays up-to-date without unnecessary refreshes, needs_redraw = true; must be set in the following situations:

1. After Handling User Input: When crossterm_event::poll returns true, indicating a keyboard/mouse event was received and processed by event_handler.handle_event.
2. During Active Loading States: If an asynchronous operation is in progress and a visual indicator (like a loading dialog) is active (e.g., checking if app_state.ui.dialog.is_loading). This keeps the loading state visible while waiting for the result.
3. After Processing Async Results: When the result of an asynchronous operation (e.g., received from an mpsc::channel like login_result_receiver) is processed and the application state is updated (e.g., dialog content changed, data updated).
4. After Internal State Changes: If any logic outside the direct event handling block modifies state that needs to be visually reflected (e.g., the position change logic loading new data into the form).

Rationale

This approach balances UI responsiveness for asynchronous tasks and user input with CPU efficiency by avoiding redraws when the application state is static.

Maintenance Note

When adding new asynchronous operations or internal logic that modifies UI-relevant state outside the main event handler, developers must remember to set needs_redraw = true at the appropriate point after the state change to ensure the UI updates correctly. Failure to do so can result in a stale UI.