Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# Changelog

## 0.2.0
* **Breaking:** Showcase explanations no longer open by themselves. The visitor opens them with the info button, or the website does with `ShowcaseState.tour`. `hasSeenHighlights` and `markHighlightsSeen` are removed
* **Breaking:** Showcase explanations follow the style of Dutch Coding Company instead of the theme of the app, dim the app around the target with a cutout and stop touches outside it. Pass `fontFamily` to `ShowcaseScope` for DM Sans
* **Breaking:** Showcase notices follow that style as well. `ShowcaseScope.noticeBuilder` is removed
* **Breaking:** Removed the end of the showcase story: `FinishPrompt`, `ShowcaseState.finish`, `begin`, `reset`, `resetData`, `isFinished`, `takeFinishPrompt` and the strings of the finish dialog. `ShowcaseState` is no longer abstract; a demo that should start over resets its own data
* **Breaking:** `ShowcaseState` takes the whole `ShowcaseConfig` (`DemoState(config: config)`) instead of `highlightsEnabled`, and `ShowcaseShell` reads its insets from it
* Added the `?tour=host` url parameter and `ShowcaseConfig.tourOnHost`: the page around the demo starts the explanations through `postMessage`, see [doc/showcase.md](doc/showcase.md)
* Documented `overscroll-behavior: none` in `web/index.html`, so scrolling over an embedded showcase never scrolls the website

## 0.1.2
* Added `removeShowcaseSplash` to show the splash of the app from `web/index.html` while the showcase loads, for at least a fixed duration, and the `?splash=off` url parameter

Expand Down
45 changes: 32 additions & 13 deletions doc/showcase.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ It is a separate entrypoint, so apps that do not have a showcase do not see any
void main() => runApp(ShowcaseApp(ShowcaseConfig.fromUri(kIsWeb ? Uri.base : Uri())));

class _ShowcaseAppState extends State<ShowcaseApp> {
late final DemoState _demo = DemoState(highlightsEnabled: widget.config.highlightsEnabled);
late final DemoState _demo = DemoState(config: widget.config);

@override
Widget build(BuildContext context) {
Expand All @@ -30,25 +30,25 @@ class _ShowcaseAppState extends State<ShowcaseApp> {
},
highlights: (context, page, state) => highlightsFor(page, state as DemoState),
),
builder: (context, child) => ShowcaseShell(insets: widget.config.insets, child: child!),
builder: (context, child) => ShowcaseShell(child: child!),
),
);
}
}
```

- **`ShowcaseState`** holds what the demo remembers. Extend it with the data of your app and put that data back
at the start in `resetData`. Read it with `ShowcaseScope.of<DemoState>(context)`.
- **`ShowcaseState`** holds what the demo remembers. Extend it with the data of your app and call
`notifyListeners()` when it changes. Read it with `ShowcaseScope.of<DemoState>(context)`.
- **`ShowcaseNavigator`** navigates with the plain Flutter `Navigator`, so the url of the browser never changes.
The pages are the values of an enum, opened with `context.showcase.push(DemoPage.detail, args: id)`.
- **`ShowcaseShell`** adds the safe areas that the config asks for and shows notices above everything else.
- **`ShowcaseStrings`** holds the texts of the kit. The defaults are English, pass your own to `ShowcaseScope`.
Pass `noticeBuilder` to make notices look like the snackbars of the app.

## Highlights

A `Highlight` explains part of a screen with a pulsing ring around the target and a small card, without dimming
the app. The real views do not change for the showcase, so the target is found in the widget tree:
A `Highlight` explains part of a screen with a card. The app is dimmed around the target, which gets a ring and stays
usable; touches anywhere else are stopped until the explanation is closed. The real views do not change for the
showcase, so the target is found in the widget tree:

```dart
Highlight(
Expand All @@ -58,14 +58,30 @@ Highlight(
)
```

A page explains itself once. After that, the explanation waits behind a small info button.
Explanations never open by themselves. The visitor opens the one of the page on screen with a small info button, and
it starts at the first step every time.

## The story
The explanations and the notices are in the style of Dutch Coding Company, not of the app. Their sizes come from the
Figma design of the DCC website, which shows the phone at 90%; they are divided by that, so they match the design
there. Declare DM Sans in the pubspec of the
showcase and pass its family name to `ShowcaseScope(fontFamily: 'DM Sans')`.

- Call `begin()` on the state when a visitor starts a flow, and `finish()` at the end of the story.
- Wrap home in `FinishPrompt`: back on home it offers to start over. When the visitor keeps looking around, the demo
starts over by itself at the next `begin()`.
- Call `context.showOutOfScope('Payout')` for a part of the app that is not in the demo.
### Starting them from the website

With `?tour=host` the info button is left out, and the website starts the explanations with a button of its own.
`ShowcaseShell` connects the two with `postMessage`, on the same origin only:

- the demo sends `{type: 'showcase:tour', canStart: bool}` at the start and whenever it changes. Enable the button
only while `canStart` is true: the page on screen has an explanation, it is not open, and no sheet or dialog
covers it (also not one in the root navigator);
- the website sends `{type: 'showcase:start-tour'}` to the frame to open it.

`ShowcaseState.tour` is the same switch in Dart, for tests or a button of your own.

## Out of scope

Call `context.showOutOfScope('Payout')` for a part of the app that is not in the demo. It shows a notice for a
moment.

## Splash

Expand All @@ -78,6 +94,8 @@ element with id `splash`, with the color and logo of the app, so it is there bef
background: #FFFFFF; transition: opacity 300ms; }
#splash img { width: 192px; }
#splash.splash--hidden { opacity: 0; pointer-events: none; }
/* Keeps a scroll over the embedded demo inside it, instead of scrolling the website once the app has none left. */
html, body { overscroll-behavior: none; }
</style>
...
<body>
Expand Down Expand Up @@ -105,3 +123,4 @@ out with the class `splash--hidden`. Keep the transition under a second, the ele
| `highlights=off` | Hides the explanations. |
| `insets=ios` | Adds the safe areas of an iPhone, for embedding without a status bar. |
| `splash=off` | Removes the splash as soon as the app is drawn. |
| `tour=host` | Leaves starting the explanations to the website, see above. |
2 changes: 1 addition & 1 deletion example/pubspec.lock
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ packages:
path: ".."
relative: true
source: path
version: "0.1.2"
version: "0.2.0"
equatable:
dependency: transitive
description:
Expand Down
4 changes: 2 additions & 2 deletions lib/showcase.dart
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
/// 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_navigator.dart' hide isShowcaseOnTop;
export 'showcase/showcase_scope.dart';
export 'showcase/showcase_shell.dart';
export 'showcase/showcase_splash.dart';
export 'showcase/showcase_state.dart';
export 'showcase/showcase_strings.dart';
export 'showcase/showcase_tour.dart' hide TourController;
56 changes: 0 additions & 56 deletions lib/showcase/finish_prompt.dart

This file was deleted.

Loading
Loading