feat: adding possibility to pin information on preview area

README.md

@@ -92,10 +92,54 @@ dashbook
  );
  });
 
- return Text('Use actions to show the Dialog');
+ return SizedBox();
  });
 ```
 
+## Example information
+
+More than often, an example may not be intuitive enough and the user may be lost without some instruction on how to interact with it. To mitigate that, text information can be linked to an example to serve as a guide, or really to show any relevant information.
+
+To do so, simple use the `info` parameter on the `add` method of a story:
+
+```dart
+final dashbook = Dashbook();
+
+dashbook
+ .storiesOf('CustomDialog')
+ .add('default',
+ (ctx) {
+ ctx.action('Open dialog', (context) {
+ showDialog(
+ context: context,
+ builder: (_) => CustomDialog(),
+ );
+ });
+
+ return SizedBox();
+ },
+ info: 'Use the actions button on the side to show the dialog.',
+ );
+```
+
+This will present a small `i` icon on the side toolbar that once clicked will present the information to the user.
+
+Dashbook also offers the possibility to directly show the information on the preview area, removing the necessity for the user to click on the icon. To do so, simple pass `true` to the `pinInfo` parameter.
+
+```dart
+final dashbook = Dashbook();
+
+dashbook
+ .storiesOf('CustomDialog')
+ .add('default',
+ (ctx) {
+ // omitted ...
+ },
+ info: 'Use the actions button on the side to show the dialog.',
+ pinInfo: true,
+ );
+```
+
 ## Preview area
 
 By default Dashbook will provide the whole screen area for the preview, which means that its controll icons will appear floating above the example.

example/lib/stories.dart

@@ -116,7 +116,9 @@ void addStories(Dashbook dashbook) {
  );
  });
 
- return const Center(child: Text('Use the actions menu to show a Toast'));
+ return const SizedBox();
  },
+ info: 'Use the actions menu to show a Toast',
+ pinInfo: true,
  );
 }

lib/src/story.dart

@@ -274,13 +274,15 @@ class Story {
  ChapterBuildFunction buildFn, {
  String? codeLink,
  String? info,
+ bool pinInfo = false,
  }) {
  final _chapter = Chapter(
  name,
  buildFn,
  this,
  codeLink: codeLink,
  info: info,
+ pinInfo: pinInfo,
  );
  chapters.add(_chapter);
 
@@ -300,10 +302,18 @@ class Chapter {
  DashbookContext ctx = DashbookContext();
  final String? codeLink;
  final String? info;
+ final bool pinInfo;
 
  final Story story;
 
- Chapter(this.name, this._buildFn, this.story, {this.codeLink, this.info});
+ Chapter(
+ this.name,
+ this._buildFn,
+ this.story, {
+ this.codeLink,
+ this.info,
+ this.pinInfo = false,
+ });
 
  Widget widget() {
  final w = _buildFn(ctx);

lib/src/widgets/preview_container.dart

@@ -11,6 +11,7 @@ class PreviewContainer extends StatelessWidget {
  final DeviceInfo? deviceInfo;
  final Orientation? deviceOrientation;
  final bool showDeviceFrame;
+ final String? info;
 
  const PreviewContainer({
  required Key key,
@@ -20,39 +21,61 @@ class PreviewContainer extends StatelessWidget {
  required this.showDeviceFrame,
  this.deviceInfo,
  this.deviceOrientation,
+ this.info,
  }) : super(key: key);
 
  @override
  Widget build(BuildContext context) {
+ final preview = deviceInfo != null
+ ? DevicePreview(
+ showDeviceFrame: showDeviceFrame,
+ deviceInfo: deviceInfo!,
+ deviceOrientation: deviceOrientation!,
+ child: Container(
+ decoration: BoxDecoration(
+ border: usePreviewSafeArea
+ ? Border(
+ left: BorderSide(
+ color: Theme.of(context).cardColor,
+ width: iconSize(context) * 2,
+ ),
+ right: BorderSide(
+ color: Theme.of(context).cardColor,
+ width: iconSize(context) * 2,
+ ),
+ )
+ : null,
+ ),
+ child: child,
+ ),
+ )
+ : child;
+
  return Positioned(
  top: 0,
  bottom: 0,
  left: 0,
  right: (kIsWeb && isPropertiesOpen) ? sideBarSizeProperties(context) : 0,
- child: deviceInfo != null
- ? DevicePreview(
- showDeviceFrame: showDeviceFrame,
- deviceInfo: deviceInfo!,
- deviceOrientation: deviceOrientation!,
- child: Container(
- decoration: BoxDecoration(
- border: usePreviewSafeArea
- ? Border(
- left: BorderSide(
- color: Theme.of(context).cardColor,
- width: iconSize(context) * 2,
- ),
- right: BorderSide(
- color: Theme.of(context).cardColor,
- width: iconSize(context) * 2,
- ),
- )
- : null,
+ child: info == null
+ ? preview
+ : Stack(
+ children: [
+ Positioned.fill(child: preview),
+ Positioned(
+ bottom: 6,
+ left: 6,
+ right: 6,
+ child: Center(
+ child: Card(
+ child: Padding(
+ padding: const EdgeInsets.all(8),
+ child: Text(info!),
+ ),
+ ),
+ ),
  ),
- child: child,
- ),
- )
- : child,
+ ],
+ ),
  );
  }
 }

lib/src/widgets/widget.dart

@@ -261,6 +261,9 @@ class _DashbookState extends State<Dashbook> {
  deviceInfo: deviceInfo,
  deviceOrientation: deviceOrientation,
  showDeviceFrame: showDeviceFrame,
+ info: _currentChapter?.pinInfo == true
+ ? _currentChapter?.info
+ : null,
  child: chapterWidget!,
  ),
  Positioned(
@@ -293,7 +296,8 @@ class _DashbookState extends State<Dashbook> {
  },
  ),
  ),
- if (_currentChapter?.info != null)
+ if (_currentChapter?.info != null &&
+ _currentChapter?.pinInfo == false)
  DashbookIcon(
  tooltip: 'Instructions',
  icon: Icons.info,

test/helpers.dart

@@ -1,4 +1,5 @@
 import 'package:dashbook/dashbook.dart';
+import 'package:dashbook/src/widgets/icon.dart';
 import 'package:dashbook/src/widgets/keys.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:shared_preferences/shared_preferences.dart';
@@ -18,3 +19,11 @@ extension WidgetTesterExtension on WidgetTester {
  await pumpAndSettle();
  }
 }
+
+extension CommonFindersX on CommonFinders {
+ Finder dashbookIconByTooltip(String tooltip) {
+ return byWidgetPredicate(
+ (widget) => widget is DashbookIcon && widget.tooltip == tooltip,
+ );
+ }
+}

test/widget/chapter_info_test.dart

@@ -0,0 +1,69 @@
+import 'package:dashbook/dashbook.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+import '../helpers.dart';
+
+Dashbook _getDashbookWithIconInfo() {
+ final dashbook = Dashbook();
+
+ dashbook.storiesOf('Text').add(
+ 'default',
+ (context) => const SizedBox(),
+ info: 'This is some info',
+ );
+
+ return dashbook;
+}
+
+Dashbook _getDashbookWithPinnedInfo() {
+ final dashbook = Dashbook();
+
+ dashbook.storiesOf('Text').add(
+ 'default',
+ (context) => const SizedBox(),
+ info: 'Behold! The info is already upon you!',
+ pinInfo: true,
+ );
+
+ return dashbook;
+}
+
+void main() {
+ group('Chapter Info', () {
+ testWidgets('shows the info icon', (tester) async {
+ await tester.pumpDashbook(_getDashbookWithIconInfo());
+ expect(
+ find.dashbookIconByTooltip('Instructions'),
+ findsOneWidget,
+ );
+ });
+
+ testWidgets(
+ 'show the info dialog when the icon is clicked',
+ (tester) async {
+ await tester.pumpDashbook(_getDashbookWithIconInfo());
+
+ await tester.tap(
+ find.dashbookIconByTooltip('Instructions'),
+ );
+
+ await tester.pumpAndSettle();
+ expect(find.text('This is some info'), findsOneWidget);
+ },
+ );
+
+ testWidgets(
+ 'show the info dialog when the icon is clicked',
+ (tester) async {
+ await tester.pumpDashbook(_getDashbookWithPinnedInfo());
+
+ await tester.pumpAndSettle();
+ expect(
+ find.text('Behold! The info is already upon you!'),
+ findsOneWidget,
+ );
+ },
+ );
+ });
+}