Dashbook Documentation

Dashbook organizes UI components using a hierarchical structure:

1. Stories: A collection of related widgets (e.g., all variations of a Text widget).
2. Chapters: Specific variants or states of a story (e.g., a Text widget with a specific alignment).
3. Decorators: Functions used to apply a common layout or styling to all chapters within a story (e.g., CenterDecorator() to center all widgets).

You build a Dashbook instance by chaining these methods and finally passing the instance to runApp().

final dashbook = Dashbook();

dashbook
    .storiesOf('Text')
    .decorator(CenterDecorator())
    .add('default', (ctx) {
      return Text(ctx.textProperty("text", "Example"));
    });

runApp(dashbook);

Add dashbook to your Flutter project's dependencies using the following command:

flutter pub add dashbook

The dashbook_gallery brick provides an opinionated structure for creating a Dashbook-based gallery within a Flutter application.

Important: This brick does not include platform-specific folders (like android, ios, web, etc.). After generating the project with the brick, you must manually initialize the desired platforms using the Flutter CLI to make the project runnable.

flutter create . --platforms <your_desired_platforms>

Dashbook is a widget and can be run independently of your main app. It is recommended to:

1. Create a dedicated file like lib/main_dashbook.dart.
2. Instantiate Dashbook and call runApp(dashbook) inside that file.
3. Run it using the -t flag to target the specific file.

flutter run -t lib/main_dashbook.dart

The DashbookContext is passed to your chapter's build function. It allows you to register properties that appear in the Dashbook sidebar, enabling interactive control over your widget's state during preview.

When you call a property helper (like textProperty or boolProperty), it returns the current value of that property. You should use this returned value to drive your widget's parameters.

Story( 'My Story' )
  .add( 'Interactive Widget', (context) {
    // Register properties and get their current values
    final String label = context.textProperty('Label', 'Default Label');
    final bool isEnabled = context.boolProperty('Enabled', true);
    final double padding = context.numberProperty('Padding', 16.0);

    return MyWidget(
      label: label,
      enabled: isEnabled,
      padding: EdgeInsets.all(padding),
    );
  });

By default, Dashbook control icons float over the preview area. To prevent icons from overlapping your widget, set usePreviewSafeArea to true in the Dashbook constructor. This creates a dedicated safe area for the preview.

final dashbook = Dashbook(usePreviewSafeArea: true);

You can hide or show properties in the Dashbook sidebar based on the value of another property using ControlProperty.

Pass a ControlProperty instance to the visibilityControlProperty argument of any property helper. The property will only be visible if the property identified by the ControlProperty.key evaluates to a truthy value.

// 1. Create a control property (e.g., a boolean toggle)
final showAdvanced = context.boolProperty('Show Advanced', false);

// 2. Use its key to control the visibility of another property
context.textProperty(
  'Advanced Setting',
  'Secret',
  visibilityControlProperty: ControlProperty('Show Advanced'),
);

You can provide instructions for your examples using the info and pinInfo parameters in the add method:

• info: A string containing the documentation text. This appears behind a small i icon in the side toolbar.
• pinInfo: A boolean. If set to true, the information is displayed directly in the preview area without requiring a click on the icon.

dashbook.storiesOf('CustomDialog').add(
  'default',
  (ctx) => MyWidget(),
  info: 'Use the actions button on the side to show the dialog.',
  pinInfo: true,
);

Dashbook supports three theme management modes:

1. Single Theme: Use the theme parameter in the default constructor.
2. Dual Theme: Use Dashbook.dualTheme to provide light and dark ThemeData. Dashbook will automatically add a toggle icon.
3. Multiple Themes: Use Dashbook.multiTheme with a Map<String, ThemeData>. Dashbook will provide a dropdown menu to switch between them.

// Single
final dashbook = Dashbook(theme: ThemeData());

// Dual
final dashbook = Dashbook.dualTheme(
  light: MyLightTheme(),
  dark: MyDarkTheme(),
);

// Multiple
final dashbook = Dashbook.multiTheme(
  themes: {
    'Light': ThemeData.light(),
    'Dark': ThemeData.dark(),
    'Custom': MyCustomTheme(),
  },
);

To prevent long, confusing lists of properties, use visibilityControlProperty with a ControlProperty object. This allows you to hide certain properties unless another property has a specific value.

Example: Only show errorColor when the widget type is set to MessageCardType.error.

dashbook.storiesOf('MessageCard').add(
  'default',
  (ctx) => MessageCard(
    type: ctx.listProperty('type', MessageCardType.info, MessageCardType.values),
    errorColor: ctx.colorProperty(
      'errorColor',
      const Color(0xFFCC6941),
      visibilityControlProperty: ControlProperty('type', MessageCardType.error),
    ),
  ),
);

Inside the add method of a story, use the ctx (DashbookContext) to define interactive properties that appear in the Dashbook UI. This allows users to live-edit widget parameters.

Common property methods include:

• ctx.textProperty(name, defaultValue): For text input.
• ctx.numberProperty(name, defaultValue): For numeric input.
• ctx.listProperty(name, defaultValue, values): For selecting from a list of values (e.g., Enums).
• ctx.colorProperty(name, defaultValue): For color picking.

dashbook.storiesOf('Text').add('default', (ctx) {
  return Text(
    ctx.textProperty("text", "Text Example"),
    textAlign: ctx.listProperty("text align", TextAlign.center, TextAlign.values),
    style: TextStyle(
      fontSize: ctx.numberProperty("font size", 20),
    ),
  );
});

Use ctx.action to trigger complex interactions that aren't directly controlled by properties, such as opening a Dialog or navigating. This adds a button to the Dashbook side toolbar.

dashbook.storiesOf('CustomDialog').add('default', (ctx) {
  ctx.action('Open dialog', (context) {
    showDialog(
      context: context,
      builder: (_) => CustomDialog(),
    );
  });

  return SizedBox();
});