widgetbook_annotation 0.0.1

A package featuring the annotations used by widgetbook_generator.

Introduction

This package contains annotations for package:widgetbook_generator with which the generator will create the Widgetbook defined in package:widgetbook. Therefore, this package is a part of making package:widgetbook easier to maintain. Furthermore, setting up and maintaining package:widgetbook is simplified by code generation.

Installing this package

This package requires the following dependencies:

Package	Pub
package:widgetbook
package:widgetbook_annotation

and the following dev dependencies:

Package	Pub
package:widgetbook_generator
package:build_runner

The pubspec.yaml file could look like this:

dependencies:
  widgetbook:
  widgetbook_annotation:

dev_dependencies:
  build_runner:
  widgetbook_generator:

Avaialble annotations

This package defines the annotations WidgetbookApp, WidgetbookStory, and WidgetbookTheme. The annotations and their usage are explained below.

WidgetbookApp

The annotation WidgetbookApp has to be set only once and is mandatory for the code generation process. It not not important which element is annotated, but the location of the file in which WidgetbookApp is used defines the folder in which package:widgetbook_generator will create the file app.widgetbook.main file. The app.widgetbook.main file requires all the code to run the Widgetbook.

Parameters

The annotation WidgetbookApp has one required parameter name and one optional parameter devices.

From the name parameter, the generator will create the AppInfo property of package:widgetbook. Therefore, this value will show in the upper left corner of the Widgetbook.

From the devices parameter, the generator will create the devices in which one can preview the widgets.

Example

For the following app structure

app
├─ lib
│  ├─ main.dart
│  ├─ app.dart
├─ test
│  ├─ app_test.dart
├─ pubspec.yaml

one might add WidgetbookApp to the App Widget defined in app.dart.

@WidgetbookApp('Example App', devices: [ Apple.iPhone12 ])
class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp();
  }
}

package:widgetbook_generator will then create a new file app.widgetbook.dart next to the app.dart file. the resulting app structure will look like this:

app
├─ lib
│  ├─ main.dart
│  ├─ app.dart
│  ├─ app.widgetbook.dart
├─ test
│  ├─ app_test.dart
├─ pubspec.yaml

WidgetbookStory

WidgetbookStory allows developers to mark functions as a story. The WidgetbookStory must be applied to a function

Widget name(BuildContext context) {  
  return YourWidget()
}

or a lambda expression

Widget name(BuildContext context) => YourWidget();

Parameters

WidgetbookStory requires the two parameters name and type.

The name parameter specifies how the story will be displayed in the navigation panel in the Widgetbook.

The type parameter specifies to which type of Widget the Story belongs. From this information and the location of the file in which the annotation is used, package:widgetbook_generator will create the navigation panel shown on the left side of the Widgetbook.

Example

Lets assume that the file structure looks like this

app
├─ lib
│  ├─ main.dart
│  ├─ app.dart
│  ├─ tiles
│  │  ├─ awesome_tile.dart
│  ├─ app.widgetbook.dart
├─ test
│  ├─ app_test.dart
├─ pubspec.yaml

A story for AwesomeTile located in /lib/tiles/awesome_tile.dart can be defined in that file by implementing the following

@WidgetbookStory(name: 'Default', type: AwesomeTile)
Widget awesomeTileStory(BuildContext context) {
  return AwesomeTile();
}

class AwesomeTile extends StatelessWidget {
  const AwesomeTile({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Container();
  }
}

It often happens that your widget is more complex. In such a case feel free to wrap the widget with whatever you need. This can also be a Provider, Bloc or other state management Widget.

After generating the code for the Widgetbook you will find a navigation panel with the following content.

stories (Category)
├─ tiles (Folder)
│  ├─ AwesomeTile (WidgetElement)
│  │  ├─ Default (Story)

If you require multiple stories for a Widget feel free to define multiple WidgetbookStorys per Widget. The additional Stories will be located in the navigation panel similar to the showcased Story.

WidgetbookTheme

WidgetbookTheme allows developers to annotate the light and dark theme of their app. Similar to WidgetbookStory, WidgetbookTheme is used on methods returning a ThemeData object.

Constructors

WidgetbookTheme features two constructors WidgetbookTheme.light() and WidgetbookTheme.dark() for differentiation between the light and dark theme of the app.

Example

@WidgetbookTheme.dark()
ThemeData getDarkTheme() => ThemeData(
      primarySwatch: Colors.blue,
    );