Files
pipelines/app/lib/features/walkthrough/first_run_walkthrough.dart
T
alan 30ba70ade8 Add first-run walkthrough
Guide new users through connecting a server, configuring an agent harness, starting runs, and chatting with agents. Persist completion per device and offer the walkthrough again for empty servers or from Settings, with widget coverage and implementation notes.
2026-11-12 02:23:15 +00:00

184 lines
5.5 KiB
Dart

import 'package:flutter/material.dart';
import '../../ui/adaptive/app_popups.dart';
import 'walkthrough_harness_command.dart';
import 'walkthrough_steps.dart';
/// Opens the walkthrough as a Material details sheet on phones and a dialog on
/// wide windows. [onClosed] runs once however it closes (Skip, Done, the close
/// button or a tap outside), so the caller can record it as seen.
Future<void> showFirstRunWalkthrough(
BuildContext context, {
Future<void> Function()? onClosed,
}) async {
await showAppDetails<void>(
context,
maxWidth: 560,
builder: (sheet) =>
FirstRunWalkthrough(onClose: () => Navigator.of(sheet).pop()),
);
await onClosed?.call();
}
/// The four-page stepper: Back and Next between pages, Skip on every page and
/// Done on the last. Every control is a standard Material button; the layout
/// wraps rather than clipping at large text scales.
class FirstRunWalkthrough extends StatefulWidget {
const FirstRunWalkthrough({
super.key,
required this.onClose,
this.steps = walkthroughSteps,
});
/// Called by Skip, Done and the close button.
final VoidCallback onClose;
final List<WalkthroughStep> steps;
@override
State<FirstRunWalkthrough> createState() => _FirstRunWalkthroughState();
}
class _FirstRunWalkthroughState extends State<FirstRunWalkthrough> {
int _index = 0;
bool get _last => _index == widget.steps.length - 1;
void _back() => setState(() => _index = _index > 0 ? _index - 1 : 0);
void _next() => setState(() => _index = _last ? _index : _index + 1);
@override
Widget build(BuildContext context) {
final step = widget.steps[_index];
final theme = Theme.of(context);
final content = Semantics(
scopesRoute: true,
namesRoute: true,
explicitChildNodes: true,
label: 'Pipelines walkthrough',
child: Padding(
padding: const EdgeInsets.fromLTRB(24, 8, 24, 24),
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: <Widget>[
Text(
'Step ${_index + 1} of ${widget.steps.length}',
key: const ValueKey<String>('walkthrough.progress'),
style: theme.textTheme.labelLarge,
),
const SizedBox(height: 8),
LinearProgressIndicator(value: (_index + 1) / widget.steps.length),
const SizedBox(height: 20),
Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
Icon(step.icon, color: theme.colorScheme.primary),
const SizedBox(width: 12),
Expanded(
child: Text(
step.title,
key: ValueKey<String>('walkthrough.title.$_index'),
style: theme.textTheme.headlineSmall,
),
),
],
),
const SizedBox(height: 12),
Text(step.body, style: theme.textTheme.bodyLarge),
for (final point in step.points) ...<Widget>[
const SizedBox(height: 8),
_Point(text: point),
],
if (step.showsHarnessCommand) ...<Widget>[
const SizedBox(height: 16),
const WalkthroughHarnessCommand(),
],
const SizedBox(height: 24),
_Footer(
last: _last,
canGoBack: _index > 0,
onBack: _back,
onNext: _last ? widget.onClose : _next,
onSkip: widget.onClose,
),
],
),
),
);
// A wide window wraps the sheet's content in its own scroll view; a phone
// sheet does not, so the page scrolls here at large text scales.
return usesDesktopPopups(context)
? content
: SingleChildScrollView(child: content);
}
}
class _Point extends StatelessWidget {
const _Point({required this.text});
final String text;
@override
Widget build(BuildContext context) => Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
const Padding(
padding: EdgeInsets.only(top: 2),
child: Icon(Icons.circle, size: 6),
),
const SizedBox(width: 12),
Expanded(
child: Text(text, style: Theme.of(context).textTheme.bodyMedium),
),
],
);
}
class _Footer extends StatelessWidget {
const _Footer({
required this.last,
required this.canGoBack,
required this.onBack,
required this.onNext,
required this.onSkip,
});
final bool last;
final bool canGoBack;
final VoidCallback onBack;
final VoidCallback onNext;
final VoidCallback onSkip;
@override
Widget build(BuildContext context) => Wrap(
alignment: WrapAlignment.spaceBetween,
crossAxisAlignment: WrapCrossAlignment.center,
spacing: 8,
runSpacing: 8,
children: <Widget>[
TextButton(
key: const ValueKey<String>('walkthrough.skip'),
onPressed: onSkip,
child: const Text('Skip'),
),
Wrap(
spacing: 8,
runSpacing: 8,
children: <Widget>[
TextButton(
key: const ValueKey<String>('walkthrough.back'),
onPressed: canGoBack ? onBack : null,
child: const Text('Back'),
),
FilledButton(
key: const ValueKey<String>('walkthrough.next'),
onPressed: onNext,
child: Text(last ? 'Done' : 'Next'),
),
],
),
],
);
}