part 'app_route_codec.dart'; /// The destinations the app has a URL for. /// /// The set mirrors [AppDestination] but stays free of widget imports so the /// parser and serialiser can be exercised without a Flutter host. enum AppRouteKind { pipelines, runs, chat, search, settings, templates, schedules } /// One page route: a destination plus the detail, pane and query it opens. /// /// The URL vocabulary mirrors `web/src/routes.js`: /// /// /pipelines Pipelines list /// /pipelines/:id pipeline detail, latest version /// /pipelines/:id/:version pipeline detail at a version /// /pipelines/:id[/:version]/stage/:key definition stage pane /// /runs Runs list (optional ?pipeline=) /// /runs/:id run detail (optional ?action=decide) /// /runs/:id/stage/:key[?visit=N] one visit's stage pane /// /templates[/:key] template gallery / detail /// /settings/templates[/:key] aliases for the template routes /// /chat[/:id], /search, /settings unchanged destinations /// /// Only the two stage panes are deep-linkable; other in-page state stays out /// of the URL. Unknown query parameters are ignored, and an invalid `visit`, /// `action` or `pipeline` value is dropped rather than failing the route. /// /// Parsing is total: an unknown or malformed path resolves to the default /// Pipelines list instead of throwing, and the serialiser is its inverse for /// every route the app can produce. class AppRoute { const AppRoute( this.kind, { this.runId, this.chatSessionId, this.pipelineId, this.version = 0, this.stageKey, this.visit, this.decide = false, this.templateKey, }); static const pipelines = AppRoute(AppRouteKind.pipelines); static const runs = AppRoute(AppRouteKind.runs); static const chat = AppRoute(AppRouteKind.chat); static const search = AppRoute(AppRouteKind.search); static const settings = AppRoute(AppRouteKind.settings); /// The template gallery, reached from Settings. It is a Settings sub-page, /// not a fifth tab, so Back returns to Settings. static const templates = AppRoute(AppRouteKind.templates); /// The saved-schedule list, a Settings sub-page on `/schedules`. static const schedules = AppRoute(AppRouteKind.schedules); static const run = _RunRouteFactory(); /// One chat session, or the chat list when [id] is not a session id. static AppRoute chatSession(String id) => isChatSessionId(id) ? AppRoute(AppRouteKind.chat, chatSessionId: id) : chat; /// A pipeline detail; [version] 0 is the latest published version. static AppRoute pipeline(int id, {int version = 0}) => _validId(id) == null ? pipelines : AppRoute( AppRouteKind.pipelines, pipelineId: id, version: _latest(version), ); /// The definition pane's stage [stageKey] for pipeline [id]. static AppRoute pipelineStage(int id, String stageKey, {int version = 0}) => _validId(id) == null || stageKey.isEmpty ? pipelines : AppRoute( AppRouteKind.pipelines, pipelineId: id, version: _latest(version), stageKey: stageKey, ); /// The Runs list filtered to one pipeline. static AppRoute runsForPipeline(int pipelineId) => _validId(pipelineId) == null ? runs : AppRoute(AppRouteKind.runs, pipelineId: pipelineId); /// One template's detail page, or the gallery for an empty [key]. static AppRoute template(String key) => key.isEmpty ? templates : AppRoute(AppRouteKind.templates, templateKey: key); final AppRouteKind kind; /// The run shown by the Runs destination, or null for the list. When /// [stageKey] is also set, this is the run whose stage pane is open. final int? runId; /// The chat session shown by the Chat destination, or null for the list. final String? chatSessionId; /// The pipeline shown by the Pipelines destination, or the pipeline the Runs /// list is filtered to. Null is the unfiltered list. final int? pipelineId; /// The pipeline version for [pipelineId]; 0 is the latest. final int version; /// The stage pane's key, for a pipeline definition or a run visit. final String? stageKey; /// The zero-based visit index for a run's [stageKey], or null when absent. final int? visit; /// Whether a run detail opens its decision prompt (`?action=decide`). final bool decide; /// The template whose detail page is open, or null for the gallery. final String? templateKey; /// The path the app writes into history for this route. String get path => _routePath(this); /// Parses a browser pathname (or a full URL) into a route. /// /// `/runs/abc`, `/pipelines/0` and other malformed details are the default /// route, matching the web parser; `/pipelines/` and other trailing slashes /// are normalised. static AppRoute parse(String location) => _parseRoute(location); /// A chat session id is nonempty, bounded and URL-safe, matching the web /// parser. Anything else is malformed rather than a stale session the /// destination has to guess about. static bool isChatSessionId(String value) => value.isNotEmpty && value.length <= 200 && RegExp(r'^[A-Za-z0-9_-]+$').hasMatch(value); @override bool operator ==(Object other) => other is AppRoute && other.kind == kind && other.runId == runId && other.chatSessionId == chatSessionId && other.pipelineId == pipelineId && other.version == version && other.stageKey == stageKey && other.visit == visit && other.decide == decide && other.templateKey == templateKey; @override int get hashCode => Object.hash( kind, runId, chatSessionId, pipelineId, version, stageKey, visit, decide, templateKey, ); @override String toString() => path; } /// `AppRoute.run(3)` reads better than a constructor named after a field. class _RunRouteFactory { const _RunRouteFactory(); AppRoute call(int id) => _validId(id) == null ? AppRoute.runs : AppRoute(AppRouteKind.runs, runId: id); /// One visit's stage pane; [visit] is zero-based and omitted when null. AppRoute stage(int id, String stageKey, {int? visit}) => _validId(id) == null || stageKey.isEmpty ? AppRoute.runs : AppRoute( AppRouteKind.runs, runId: id, stageKey: stageKey, visit: _nonNegative(visit), ); /// A run detail with its decision prompt open. AppRoute decide(int id) => _validId(id) == null ? AppRoute.runs : AppRoute(AppRouteKind.runs, runId: id, decide: true); }