FocusNavigator class

Manages focus navigation (with optional per-item error tracking) for views where every item is already visible.

When to use

Choose FocusNavigator when you have a finite list of focusable items on screen at once-forms, multi-step wizards, setting pages, command palettes, onboarding questionnaires, etc. It is intentionally simpler than ListNavigator because there is no viewport math to keep in sync.

Highlights

• Index-based API that plugs nicely into your own data structures
• Built-in wrapping so keyboard navigation feels natural
• Optional validation helpers so UI can jump to the first invalid control
• Cheap updates when the number of focusable widgets changes
• Works great together with SelectionController and key handlers

Usage

final focus = FocusNavigator(itemCount: fields.length);

// Navigate with wrapping
focus.moveBy(1);   // down/next (wraps at end)
focus.moveBy(-1);  // up/previous (wraps at start)

// Absolute jumps
focus.jumpTo(3);
focus.jumpToLast();

// Track errors
focus.setError(2, 'Field is required');
if (focus.hasAnyError) {
  focus.focusFirstError(); // focus jumps to first invalid item
}

// Rendering loop
for (var i = 0; i < items.length; i++) {
  final isFocused = focus.isFocused(i);
  final error = focus.getError(i);
  // render item with focus indicator + error badge
}

Validation workflow

Wire up validation once and reuse it everywhere:

final allValid = focus.validateAll(
  (index) => values[index].isEmpty ? 'Required' : null,
  focusFirstInvalid: true,
);
if (allValid) submit();

By centralizing navigation state you avoid scattered int fields across widgets and make the API friendly for pub.flutter-io.cn consumers who just want a lightweight, well-documented helper.