Files
pipelines/app/lib/features/search/domain/search_controller.dart
T
alan 51140cd3b7 feat(app): add native omni-search screen over the search gateway
Pure request/parse/row logic in lib/features/search/domain, a
gateway-backed repository, and Material plus Cupertino bodies.
The header and rows share one scroll view, and the server's
truncation, scan and cap facts stay visible even when a bounded
scan returns no matches.

Tests cover the exact search envelope, token parsing, stale replies,
retry, truncation bounds and platform layouts. A Web-only fixture
and CDP probe support rendered verification; the screen is not yet
registered in the shell.
2026-10-21 16:41:30 +01:00

237 lines
7.3 KiB
Dart

import 'dart:async';
import 'package:flutter/foundation.dart';
import '../../../core/api_gateway.dart';
import '../data/search_repository.dart';
import 'search_models.dart';
import 'search_query.dart';
import 'search_row.dart';
/// The body the results area shows, in the browser's precedence order: an error
/// takes precedence over retained results, a refresh keeps results on screen,
/// and a first load shows the searching row.
enum SearchBodyKind { idle, searching, results, empty, error }
/// Debounced, stale-safe omni-search state. It owns no widgets and no socket:
/// the screen listens to it and the repository talks to the shared gateway.
class OmniSearchController extends ChangeNotifier {
OmniSearchController({
required this.repository,
this.debounce = const Duration(milliseconds: 250),
});
final SearchRepository repository;
final Duration debounce;
final SearchSequencer _sequencer = SearchSequencer();
Timer? _timer;
bool _disposed = false;
String _query = '';
SearchKind _selectedKind = SearchKind.all;
List<JsonMap> _results = const [];
bool _loading = false;
bool _loaded = false;
bool _truncated = false;
int _scannedSteps = 0;
int _scannedBytes = 0;
int _cap = 0;
int _scanBoundBytes = 0;
String? _error;
String get query => _query;
SearchKind get selectedKind => _selectedKind;
ParsedSearchQuery get parsed => parseSearchQuery(_query, _selectedKind);
List<JsonMap> get results => _results;
bool get loading => _loading;
bool get loaded => _loaded;
bool get truncated => _truncated;
int get scannedSteps => _scannedSteps;
int get scannedBytes => _scannedBytes;
int get cap => _cap;
int get scanBoundBytes => _scanBoundBytes;
String? get error => _error;
/// The results already in hand, re-narrowed to the effective kind so the list
/// always matches the control while a narrowed request loads.
List<JsonMap> get shownResults {
final kind = parsed.kind;
if (kind == SearchKind.all) return _results;
return _results
.where((hit) => hit['kind'] == kind.wire)
.toList(growable: false);
}
SearchBodyKind get bodyKind {
if (_error != null) return SearchBodyKind.error;
if (shownResults.isNotEmpty) return SearchBodyKind.results;
if (_loading && _results.isEmpty) return SearchBodyKind.searching;
if (emptyMessage != null) return SearchBodyKind.empty;
return SearchBodyKind.idle;
}
/// A thin progress report above retained results while a newer query loads.
bool get showProgress => _loading && _results.isNotEmpty;
String? get emptyMessage {
if (_error != null || _loading || shownResults.isNotEmpty) return null;
final effective = parsed;
if (effective.query.trim().isEmpty) {
if (!_loaded || effective.kind == SearchKind.all) return null;
final label = effective.kind.label.toLowerCase();
return _truncated
? "No $label found within the server's scan limit."
: 'No $label yet.';
}
final bounded = _truncated ? " within the server's scan limit" : '';
if (effective.kind == SearchKind.all) {
return 'No matches for "${effective.query}"$bounded.';
}
return 'No ${effective.kind.label.toLowerCase()} match '
'"${effective.query}"$bounded.';
}
/// The server's own result/scan bounds, so a capped answer is not presented as
/// a complete one. A truncated reply keeps its warning even with no rows;
/// before any loaded reply there is nothing to report.
String? get boundsText {
if (!_loaded) return null;
// A new first load has no current result set yet, so do not carry the
// previous reply's warning while the searching state is on screen.
if (_loading && _results.isEmpty) return null;
if (_results.isEmpty && !_truncated) return null;
final count = _results.length;
final parts = <String>[];
if (_truncated) {
parts.add("Results truncated by the server's result or scan limit.");
}
parts.add('$count ${count == 1 ? 'result' : 'results'}');
if (_cap > 0) parts.add('cap $_cap');
parts.add('scanned $_scannedSteps steps');
parts.add('${humanBytes(_scannedBytes)} scanned');
if (_scanBoundBytes > 0) {
parts.add('scan limit ${humanBytes(_scanBoundBytes)}');
}
return parts.join(' · ');
}
/// Record a keystroke. Blank text with no kind clears locally and sends
/// nothing; valid kind-only browsing is sendable like the browser's search.
void updateQuery(String value) {
_query = value;
_error = null;
_cancelTimer();
final effective = parsed;
if (!searchQuerySendable(effective.query, effective.kind)) {
_sequencer.edit('');
_clearResults();
_notify();
return;
}
_loading = true;
final edit = _sequencer.edit(value);
_notify();
_timer = Timer(debounce, () {
_timer = null;
final sent = _sequencer.begin(edit);
if (sent != null) unawaited(_send(sent));
});
}
/// A kind change removes recognised type tokens from the visible text and
/// sends at once, matching the browser's selector behaviour.
void selectKind(SearchKind kind) {
_query = parseSearchQuery(_query, _selectedKind).query;
_selectedKind = kind;
_error = null;
_notify();
unawaited(sendNow());
}
/// Enter: send the current query immediately, skipping the debounce.
Future<void> submit() => sendNow();
/// Retry the current query after a failure.
Future<void> retry() => sendNow();
Future<void> sendNow() async {
_cancelTimer();
final effective = parseSearchQuery(_query, _selectedKind);
if (!searchQuerySendable(effective.query, effective.kind)) {
_sequencer.edit('');
_clearResults();
_notify();
return;
}
final sent = _sequencer.begin(_sequencer.edit(_query));
if (sent == null) return;
await _send(sent);
}
Future<void> _send(SearchEdit sent) async {
final effective = parseSearchQuery(sent.query, _selectedKind);
_loading = true;
_error = null;
_notify();
try {
final response = await repository.search(
query: effective.query.trim(),
kind: effective.kind,
);
if (!_sequencer.accepts(sent.token) || _disposed) return;
if (response == null) {
_loading = false;
_loaded = true;
_error = unsupportedSearchCopy;
_notify();
return;
}
_results = response.results;
_truncated = response.truncated;
_scannedSteps = response.scannedSteps;
_scannedBytes = response.scannedBytes;
_cap = response.cap;
_scanBoundBytes = response.scanBoundBytes;
_loading = false;
_loaded = true;
_error = null;
_notify();
} catch (error) {
if (!_sequencer.accepts(sent.token) || _disposed) return;
_loading = false;
_loaded = true;
_error = searchFailureText(error);
_notify();
}
}
void _clearResults() {
_results = const [];
_truncated = false;
_scannedSteps = 0;
_scannedBytes = 0;
_cap = 0;
_scanBoundBytes = 0;
_loading = false;
_loaded = false;
_error = null;
}
void _cancelTimer() {
_timer?.cancel();
_timer = null;
}
void _notify() {
if (!_disposed) notifyListeners();
}
@override
void dispose() {
_disposed = true;
_cancelTimer();
super.dispose();
}
}