ui_playground_generator 0.0.6

A build_runner code generator that creates UI Playground items from annotated widget classes.

ui_playground_generator

Purpose

A build_runner code generator that creates UI Playground items from annotated widget classes.

This package automatically generates UiPlaygroundItem, UiPlaygroundVariant, and UiPlaygroundInputs classes for widgets annotated with @UiPlaygroundComponent. All generated code is aggregated into a single file marked with @UiPlaygroundComponents.

Other packages

This packages is part of an ecosystem of packages that work together to create an ui playground for testing and showcasing UI components.

• ui_playground_annotations - The annotations package for the ui_playground_generator
• ui_playground - The Flutter UI package that provides the playground UI widget

Installation

Add to your pubspec.yaml:

dependencies:
  ui_playground:
    path: ../ui_playground
  ui_playground_annotations:
    path: ../ui_playground_annotations

dev_dependencies:
  build_runner: ^2.4.9
  ui_playground_generator:
    path: ../ui_playground_generator

Usage

1. Create an Aggregation Class

// lib/ui_playground/components.dart
import 'package:ui_playground/ui_playground.dart';
import 'package:my_app/ui_playground/components.ui_playground.dart';

@UiPlaygroundComponents()
class AppComponents {
  static List<UiPlaygroundItem> get items => GeneratedUiPlaygroundComponents.items;
}

2. Annotate Your Widgets

// lib/component/button.dart
import 'package:flutter/material.dart';
import 'package:ui_playground/ui_playground.dart';

@UiPlaygroundComponent(
  title: 'My Button',
  excludeParams: ['onTap'],
)
class MyButton extends StatelessWidget {
  final String title;
  final bool isEnabled;
  final VoidCallback? onTap;

  const MyButton({
    required this.title,
    this.isEnabled = true,
    this.onTap,
    super.key,
  });

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: isEnabled ? onTap : null,
      child: Text(title),
    );
  }
}

3. Run the Generator

dart run build_runner build

Or use watch mode:

dart run build_runner watch

4. Use in Your App

import 'package:my_app/ui_playground/components.dart';

UiPlaygroundApp(
  sections: [
    UiPlaygroundSection(
      title: 'Buttons',
      items: AppComponents.items,
    ),
  ],
)

External Components

For widgets from external packages you cannot annotate, use UiPlaygroundComponentConfig:

import 'package:external_ui/external_ui.dart';

@UiPlaygroundComponents(
  components: [
    UiPlaygroundComponentConfig(
      ExternalButton,
      title: 'External Button',
      excludeParams: ['onTap', 'controller'],
    ),
    UiPlaygroundComponentConfig(ExternalCard),
  ],
)
class AppComponents {
  static List<UiPlaygroundItem> get items => GeneratedUiPlaygroundComponents.items;
}

componentsOnly Mode

To only use external components and skip scanning for @UiPlaygroundComponent:

@UiPlaygroundComponents(
  componentsOnly: true,
  components: [
    UiPlaygroundComponentConfig(ExternalButton),
    UiPlaygroundComponentConfig(ExternalCard),
  ],
)
class AppComponents {
  static List<UiPlaygroundItem> get items => GeneratedUiPlaygroundComponents.items;
}

Generated Code

The generator creates three classes for each annotated widget:

// ui_playground_items.g.dart (all in one file)

class MyButtonPlaygroundItem extends UiPlaygroundItem { ... }
class MyButtonPlaygroundVariant extends UiPlaygroundVariant<MyButtonPlaygroundInputs> { ... }
class MyButtonPlaygroundInputs extends UiPlaygroundInputs { ... }

Supported Parameter Types

The generator automatically maps Dart types to playground inputs:

Dart Type	Generated Input
String	UiPlaygroundStringInput
bool	UiPlaygroundBooleanInput
int	UiPlaygroundIntInput
double	UiPlaygroundDoubleInput
Enum	UiPlaygroundEnumInput<T>
Color	UiPlaygroundColorInput
DateTime	UiPlaygroundDateTimeInput

Automatically Excluded Parameters

• key (Widget key)
• Function types (callbacks like VoidCallback, Function)

Manually Excluding Parameters

@UiPlaygroundComponent(
  excludeParams: ['onTap', 'controller', 'focusNode'],
)
class MyWidget extends StatelessWidget { ... }

Package Structure

ui_playground_generator/
├── lib/
│   ├── builder.dart                    # Builder factory
│   ├── ui_playground_generator.dart    # Library exports
│   └── src/
│       ├── ui_playground_generator.dart  # Aggregating generator
│       └── parameter_analyzer.dart       # Parameter type analysis
├── build.yaml                          # Build configuration
└── pubspec.yaml

Why a Separate Annotations Package?

The generator depends on (pure Dart) instead of (Flutter) because build_runner runs in a pure Dart environment and cannot resolve Flutter dependencies.