refactor: Clean up and documentation

Author: ookami-kb

meta/preview.png

@@ -5,7 +5,6 @@
 A cross-platform storybook for showcasing widgets. It should work in all platforms supported by Flutter.
 
 - [Demo version](https://ookami-kb.github.io/storybook_flutter/)
-- [Documentation](https://ookamikb.gitbook.io/flutter-storybook/)
 
 ![](https://github.com/ookami-kb/storybook_flutter/raw/master/meta/preview.png)
 
@@ -16,42 +15,19 @@ class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) =>
       Storybook(
-        children: [
+        stories: [
           Story(
-            name: 'Flat button',
-            padding: EdgeInsets.all(5), // optional padding customization
-            background: Colors.red, // optional background color customization
-            builder: (_, k) =>
-                MaterialButton(
-                  onPressed: k.boolean(label: 'Enabled', initial: true) ? () {} : null,
-                  child: Text(k.text(label: 'Text', initial: 'Flat button')),
-                ),
+            name: 'Screens/Counter',
+            description: 'Demo Counter app with about dialog.',
+            builder: (context) => CounterPage(
+              title: context.knobs.text(label: 'Title', initial: 'Counter'),
+              enabled: context.knobs.boolean(label: 'Enabled', initial: true),
+            ),
           ),
           Story(
-            name: 'Raised button',
-            builder: (_, k) =>
-                RaisedButton(
-                  onPressed: k.boolean(label: 'Enabled', initial: true) ? () {} : null,
-                  color: k.options(
-                    label: 'Color',
-                    initial: Colors.deepOrange,
-                    options: const [
-                      Option('Red', Colors.deepOrange),
-                      Option('Green', Colors.teal),
-                    ],
-                  ),
-                  textColor: Colors.white,
-                  child: Text(k.text(label: 'Text', initial: 'Raised button')),
-                ),
-          ),
-          Story.simple(
-            name: 'Input field',
-            child: const TextField(
-              decoration: InputDecoration(
-                border: OutlineInputBorder(),
-                labelText: 'Input field',
-              ),
-            ),
+            name: 'Widgets/Text',
+            description: 'Simple text widget.',
+            builder: (context) => const Center(child: Text('Simple text')),
           ),
         ],
       );
@@ -60,30 +36,21 @@ class MyApp extends StatelessWidget {
 
 ## Customization
 
-By default, each story is wrapped into:
-
-```
-Container(
-  color: story.background,
-  padding: story.padding,
-  child: Center(child: child),
-)
-```
-
-You can override this behavior by providing either `wrapperBuilder` to the `Story` or `storyWrapperBuilder` to
-the `Storybook`. In the latest case this wrapper will be applied to each story (of course, you can still override this
-behavior by providing another `wrapperBuilder` to individual stories).
+By default, each story is wrapped into `MaterialApp`.
 
-## CustomStorybook
+You can override this behavior by providing either `wrapperBuilder` to the
+`Storybook`. You can either use one of the default ones: `materialWrapper` or
+`cupertinoWrapper`, or provide a fully custom wrapper. In the latest case,
+make sure to use `child` widget that will contain the story.
 
-If you need even more customization, you can use `CustomStorybook`. You have to provide `builder` parameter to it where
-you can define the custom layout. In this case you're responsible for rendering the story, contents and knobs panel.
+## Plugins
 
-You can use `CurrentStory`, `Contents` and `KnobPanel` widgets that will render the corresponding data automatically.
+Almost all the functionality is provided by plugins, even contents and
+knobs are plugins (although, they are first-party plugins).
 
-As an example of full customization, take a look
-at [storybook_device_preview](https://pub.dev/packages/storybook_device_preview) package that allows to embed storybook
-into [device_preview](https://pub.dev/packages/device_preview) package with knobs and contents rendered as plugins.
+Plugins documentation is TBD, but you can take a look at the existing
+first-party plugins: `ContentsPlugin`, `DeviceFramePlugin`, `KnobsPlugin`,
+`ThemModePlugin`.
 
 ## Features and bugs
 

packages/storybook_flutter/README.md

@@ -6,6 +6,10 @@ import '../story.dart';
 import '../storybook.dart';
 import 'plugin.dart';
 
+/// Plugin that adds content as expandable list of stories.
+///
+/// If [sidePanel] is true, the stories are shown in a left side panel,
+/// otherwise as a popup.
 class ContentsPlugin extends Plugin {
   const ContentsPlugin({bool sidePanel = false})
       : super(
@@ -17,7 +21,7 @@ class ContentsPlugin extends Plugin {
 
 Widget _buildIcon(BuildContext _) => const Icon(Icons.list);
 
-Widget _buildPanel(BuildContext context) => const Contents();
+Widget _buildPanel(BuildContext context) => const _Contents();
 
 Widget _buildWrapper(BuildContext context, Widget? child) => Directionality(
       textDirection: TextDirection.ltr,
@@ -30,7 +34,7 @@ Widget _buildWrapper(BuildContext context, Widget? child) => Directionality(
                   right: BorderSide(color: Colors.black12),
                 ),
               ),
-              child: const SizedBox(width: 250, child: Contents()),
+              child: const SizedBox(width: 250, child: _Contents()),
             ),
           ),
           Expanded(
@@ -40,27 +44,8 @@ Widget _buildWrapper(BuildContext context, Widget? child) => Directionality(
       ),
     );
 
-class Contents extends StatelessWidget {
-  const Contents({
-    Key? key,
-    this.onStorySelected,
-  }) : super(key: key);
-
-  final ValueSetter<Story>? onStorySelected;
-
-  @override
-  Widget build(BuildContext context) => _Contents(
-        onStorySelected: (story) {
-          context.read<StoryNotifier>().value = story;
-          onStorySelected?.call(story);
-        },
-      );
-}
-
 class _Contents extends StatefulWidget {
-  const _Contents({Key? key, required this.onStorySelected}) : super(key: key);
-
-  final ValueSetter<Story> onStorySelected;
+  const _Contents({Key? key}) : super(key: key);
 
   @override
   _ContentsState createState() => _ContentsState();
@@ -93,10 +78,7 @@ class _ContentsState extends State<_Contents> {
         selected: story == context.watch<StoryNotifier>().value,
         title: Text(story.title),
         subtitle: story.description == null ? null : Text(story.description!),
-        onTap: () {
-          final onStorySelected = widget.onStorySelected;
-          onStorySelected(story);
-        },
+        onTap: () => context.read<StoryNotifier>().value = story,
       );
 
   Widget _buildSection(String title, Iterable<Story> stories) => ExpansionTile(

packages/storybook_flutter/lib/src/plugins/contents.dart

@@ -8,6 +8,7 @@ import 'plugin.dart';
 
 part 'device_frame.freezed.dart';
 
+/// Plugin that allows wrapping each story into a device frame.
 class DeviceFramePlugin extends Plugin {
   DeviceFramePlugin({DeviceFrameData initialData = const DeviceFrameData()})
       : super(

packages/storybook_flutter/lib/src/plugins/device_frame.dart

@@ -9,6 +9,9 @@ import '../knobs/string_knob.dart';
 import '../story.dart';
 import 'plugin.dart';
 
+/// Plugin that adds story customization knobs.
+///
+/// If [sidePanel] is true, the knobs will be displayed in the right side panel.
 class KnobsPlugin extends Plugin {
   KnobsPlugin({bool sidePanel = false})
       : super(

packages/storybook_flutter/lib/src/plugins/knobs.dart

@@ -10,6 +10,7 @@ export 'device_frame.dart';
 export 'knobs.dart';
 export 'theme_mode.dart';
 
+/// Use this method to initialize and customize built-in plugins.
 List<Plugin> initializePlugins({
   bool enableContents = true,
   bool enableKnobs = true,
@@ -38,9 +39,28 @@ class Plugin {
     this.onPressed,
   });
 
+  /// Optional wrapper that will be inserted above the whole storybook content,
+  /// including panel.
+  ///
+  /// E.g. `ContentsPlugin` uses this builder to add side panel.
   final TransitionBuilder? wrapperBuilder;
+
+  /// Optional builder that will be used to display panel popup. It appears when
+  /// user clicks on the [icon].
+  ///
+  /// For it to be used, [icon] must be provided.
   final WidgetBuilder? panelBuilder;
+
+  /// Optional wrapper that will be inserted above each story.
+  ///
+  /// E.g. `DeviceFramePlugin` uses this builder to display device frame.
   final TransitionBuilder? storyBuilder;
+
+  /// Optional icon that will be displayed on the bottom panel.
   final WidgetBuilder? icon;
+
+  /// Optional callback that will be called when user clicks on the [icon].
+  ///
+  /// For it to be used, [icon] must be provided.
   final OnPluginButtonPressed? onPressed;
 }

packages/storybook_flutter/lib/src/plugins/plugin.dart

@@ -62,6 +62,9 @@ Widget _buildWrapper(BuildContext context, Widget? child) =>
       ),
     );
 
+/// Use this notifier to get the current theme mode.
+///
+/// [ThemeModePlugin] should be added to plugins for this to work.
 class ThemeModeNotifier extends ValueNotifier<ThemeMode> {
   ThemeModeNotifier(ThemeMode value) : super(value);
 }

packages/storybook_flutter/lib/src/plugins/theme_mode.dart

@@ -7,8 +7,18 @@ class Story {
     required this.builder,
   });
 
+  /// Unique name of the story.
+  ///
+  /// Use `/` to group stories in sections, e.g. `Buttons/FlatButton`
+  /// will create a section `Buttons` with a story `FlatButton` in it.
   final String name;
+
+  /// Optional description of the story.
+  ///
+  /// It will be used in the contents as a secondary text.
   final String? description;
+
+  /// Story builder.
   final WidgetBuilder builder;
 
   String get section {
@@ -29,6 +39,7 @@ class Story {
   }
 }
 
+/// Use this notifier to get the current story.
 class StoryNotifier extends ValueNotifier<Story?> {
   StoryNotifier(Story? value) : super(value);
 }

packages/storybook_flutter/lib/src/story.dart

@@ -1,3 +1,4 @@
+import 'package:collection/collection.dart';
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import 'package:nested/nested.dart';
@@ -7,6 +8,7 @@ import 'plugins/plugin.dart';
 import 'plugins/plugin_panel.dart';
 import 'story.dart';
 
+/// Use this wrapper to wrap each story into a [MaterialApp] widget.
 Widget materialWrapper(BuildContext context, Widget? child) => MaterialApp(
       theme: ThemeData.light(),
       darkTheme: ThemeData.dark(),
@@ -15,6 +17,7 @@ Widget materialWrapper(BuildContext context, Widget? child) => MaterialApp(
       home: Scaffold(body: Center(child: child)),
     );
 
+/// Use this wrapper to wrap each story into a [CupertinoApp] widget.
 Widget cupertinoWrapper(BuildContext context, Widget? child) => CupertinoApp(
       debugShowCheckedModeBanner: false,
       useInheritedMediaQuery: true,
@@ -26,18 +29,28 @@ final _defaultPlugins = initializePlugins();
 class Storybook extends StatefulWidget {
   Storybook({
     Key? key,
-    required this.stories,
-    List<Plugin>? plugins,
+    required Iterable<Story> stories,
+    Iterable<Plugin>? plugins,
     this.initialStory,
     this.wrapperBuilder = materialWrapper,
     this.showPanel = true,
-  })  : plugins = plugins ?? _defaultPlugins,
+  })  : plugins = UnmodifiableListView(plugins ?? _defaultPlugins),
+        stories = UnmodifiableListView(stories),
         super(key: key);
 
+  /// All enabled plugins.
   final List<Plugin> plugins;
+
+  /// All available stories.
   final List<Story> stories;
+
+  /// Optional initial story.
   final String? initialStory;
+
+  /// Each story will be wrapped into a widget returned by this builder.
   final TransitionBuilder wrapperBuilder;
+
+  /// Whether to show the plugin panel at the bottom.
   final bool showPanel;
 
   @override