Merge pull request #52 from DutchCodingCompany/feature/showcase

✨ Move showcase_kit into the toolkit

Author: Guldem

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.1
+* Added the showcase kit, building blocks for a clickable web demo of an app made from its real screens. Import it with `package:dcc_toolkit/showcase.dart`, see [doc/showcase.md](doc/showcase.md)
+* Added the `dcc-toolkit-create-showcase` agent skill for setting up a showcase app
+
 ## 0.1.0
 * **Breaking:** Requires Flutter `>=3.47.0` and Dart `^3.13.0`
 * **Breaking:** Migrated from `package:flutter/material.dart` / `package:flutter/cupertino.dart` to the `material_ui` and `cupertino_ui` packages. Apps must migrate as well, see [doc/migrate_to_material_ui.md](doc/migrate_to_material_ui.md)

lib/showcase.dart

@@ -0,0 +1,13 @@
+/// Building blocks for a clickable demo of an app, made from its real screens.
+library;
+
+export 'showcase/finish_prompt.dart';
+export 'showcase/highlight.dart';
+export 'showcase/highlighted_page.dart';
+export 'showcase/out_of_scope.dart';
+export 'showcase/showcase_config.dart';
+export 'showcase/showcase_navigator.dart';
+export 'showcase/showcase_scope.dart';
+export 'showcase/showcase_shell.dart';
+export 'showcase/showcase_state.dart';
+export 'showcase/showcase_strings.dart';

lib/showcase/finish_prompt.dart

@@ -0,0 +1,56 @@
+import 'dart:async';
+
+import 'package:dcc_toolkit/dcc_toolkit.dart';
+import 'package:dcc_toolkit/showcase/showcase_scope.dart';
+import 'package:dcc_toolkit/showcase/showcase_state.dart';
+import 'package:material_ui/material_ui.dart';
+
+/// Wait a moment, so the visitor sees the result of the last step first.
+const _delay = Duration(milliseconds: 700);
+
+/// Offers to start over once the demo is finished and the visitor is back on the page that contains this widget,
+/// usually the home of the app.
+///
+/// Keeping looking around closes the dialog. The demo then starts over by itself at the next
+/// [ShowcaseState.begin].
+class const FinishPrompt({required final Widget child, super.key}) extends StatefulWidget {
+  /// Creates a [FinishPrompt].
+  this;
+
+  @override
+  State<FinishPrompt> createState() => _FinishPromptState();
+}
+
+class _FinishPromptState extends State<FinishPrompt> {
+  bool _isScheduled = false;
+
+  Future<void> _showAfterDelay(ShowcaseState state) async {
+    await Future<void>.delayed(_delay);
+    _isScheduled = false;
+    if (!mounted) return;
+
+    final strings = ShowcaseScope.stringsOf(context);
+    await showNativeDialog<void>(
+      context,
+      title: strings.finishTitle,
+      content: strings.finishMessage,
+      actions: [
+        DialogAction(text: strings.keepLooking, onTap: () {}),
+        DialogAction(text: strings.startOver, onTap: state.reset),
+      ],
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final state = ShowcaseScope.of<ShowcaseState>(context);
+    final isCurrent = ModalRoute.of(context)?.isCurrent ?? false;
+
+    if (isCurrent && !_isScheduled && state.takeFinishPrompt()) {
+      _isScheduled = true;
+      unawaited(_showAfterDelay(state));
+    }
+
+    return widget.child;
+  }
+}

lib/showcase/highlight.dart

@@ -0,0 +1,26 @@
+import 'package:dcc_toolkit/dcc_toolkit.dart';
+import 'package:material_ui/material_ui.dart';
+
+/// Decides whether [widget] is the target of a [Highlight].
+typedef WidgetMatcher = bool Function(Widget widget);
+
+/// One explanation shown on top of a screen.
+///
+/// The real views are not changed for the showcase, so a [target] finds the widget to mark in the widget tree
+/// of the screen. Without a target only the explanation is shown. A highlight whose target is not built (yet)
+/// waits until it appears, for example behind a loading state.
+class const Highlight({
+  required final String title,
+  required final String body,
+  final WidgetMatcher? target,
+
+  /// Space between the target and the ring around it.
+  final EdgeInsets padding = Paddings.all8,
+}) {
+  /// Creates a [Highlight].
+  this;
+
+  /// Matches the first widget of type [T] on the screen.
+  static WidgetMatcher type<T extends Widget>() =>
+      (widget) => widget is T;
+}