save_points_screen_builder 1.0.0

A modular, configuration-driven screen generator for common Flutter application flows with Material 3 support.

Save Points Screen Builder 🚀

A modular, configuration-driven screen generator for Flutter 3 applications with Material 3 support. Build beautiful, production-ready screens with minimal code using the builder pattern.

✨ Features

• 🎨 Material 3 Design - Fully compatible with Material You design system
• 🏗️ Builder Pattern API - Fluent, chainable APIs for all screen types
• 📝 Form Engine - Dynamic form generation from configuration
• 📦 List Engine - Declarative list/grid layouts with built-in pagination
• 🎯 Type Safe - Strong typing and null safety throughout
• 🔧 Highly Extensible - Easy to customize and extend
• 📱 Responsive - Adaptive layouts for different screen sizes
• ♿ Accessible - Built with accessibility in mind

📦 Installation

Add this to your package's pubspec.yaml file:

dependencies:
  save_points_screen_builder: ^1.0.0

Then run:

flutter pub get

🎯 Supported Screen Types

Static Screens

• ✅ Splash Screen
• ✅ Onboarding (Multi-page)
• ✅ Welcome Screen

Form-Based Screens

• ✅ Sign In
• ✅ Sign Up
• ✅ OTP/Verification
• ✅ Forgot Password

List-Based Screens

• ✅ Product/Catalog Lists
• ✅ Settings
• ✅ Profile

🚀 Quick Start

1. Splash Screen

import 'package:save_points_screen_builder/save_points_screen_builder.dart';

SplashScreenBuilder()
  .headline('My App')
  .subtitle('Welcome')
  .colorScheme(ColorScheme.fromSeed(seedColor: Colors.indigo))
  .animation(SplashAnimation.fadeIn)
  .duration(const Duration(seconds: 3))
  .onFinish(() => Navigator.pushReplacementNamed(context, '/home'))
  .build();

2. Sign In Screen

SignInScreenBuilder()
  .title('Welcome Back')
  .fields([
    FormFieldConfig.email(),
    FormFieldConfig.password(),
  ])
  .submitButton(
    label: 'Sign In',
    onSubmit: (formData) async {
      await authService.signIn(
        email: formData['email'],
        password: formData['password'],
      );
    },
  )
  .onForgotPassword(() => Navigator.pushNamed(context, '/forgot-password'))
  .socialLogin([
    SocialLoginButton.google(onGoogleSignIn),
    SocialLoginButton.apple(onAppleSignIn),
  ])
  .build();

3. Product List Screen

ProductListScreenBuilder()
  .title('Products')
  .layout(ListLayout.grid(columns: 2))
  .dataLoader(() async => await api.getProducts())
  .itemBuilder(ProductCardBuilder(
    onAddToCart: (product) => cart.add(product),
  ))
  .onItemTap((product) => Navigator.push(
    context,
    MaterialPageRoute(
      builder: (_) => ProductDetailScreen(product),
    ),
  ))
  .enableRefresh()
  .enablePagination(
    loader: (page) async => await api.getProducts(page: page),
  )
  .build();

📖 Documentation

Architecture Overview

The package follows clean architecture principles with clear separation of concerns:

save_points_screen_builder/
├── lib/
│   ├── src/
│   │   ├── core/              # Base classes & configuration
│   │   ├── form_engine/       # Form field configs & validators
│   │   ├── list_engine/       # List layouts & item builders
│   │   ├── screens/
│   │   │   ├── static/        # Static screen builders
│   │   │   ├── forms/         # Form-based screen builders
│   │   │   └── lists/         # List-based screen builders
│   │   └── utils/             # Theme extensions & animations
│   └── save_points_screen_builder.dart    # Main export file

Core Concepts

1. ScreenBuilderConfig

Global configuration for customizing screens:

final config = ScreenBuilderConfig(
  seedColor: Colors.blue,
  fontFamily: 'Roboto',
  spacing: 8.0,
  borderRadius: 12.0,
  useSafeArea: true,
  pagePadding: EdgeInsets.all(16.0),
);

SignInScreenBuilder()
  .configuration(config)
  .build();

2. Form Engine

Dynamic form generation from field configurations:

FormFieldConfig.email(
  id: 'email',
  label: 'Email Address',
  hint: 'Enter your email',
  required: true,
  validator: Validators.combine([
    Validators.required(),
    Validators.email(),
  ]),
)

Available Field Types:

• text, email, password, phone, number
• multiline, search, url, otp
• dropdown, checkbox, switchToggle, slider
• date, time, datetime

Built-in Validators:

• required() - Field cannot be empty
• email() - Valid email format
• phone() - Valid phone format
• url() - Valid URL format
• minLength(int) - Minimum character length
• maxLength(int) - Maximum character length
• password() - Password strength validation
• numeric() - Numeric value only
• pattern(RegExp) - Custom regex pattern
• match(getValue, fieldName) - Match another field
• otp(length) - OTP code validation
• combine(validators) - Combine multiple validators

3. List Engine

Declarative list building with multiple layouts:

ListLayout.grid(
  columns: 2,
  aspectRatio: 0.75,
  crossAxisSpacing: 16,
  mainAxisSpacing: 16,
)

ListLayout.list(spacing: 8)

ListLayout.adaptive() // Responsive columns based on screen size

Item Builders:

// Card-based items
CardItemBuilder<Product>(
  imageBuilder: (product) => Image.network(product.imageUrl),
  titleBuilder: (product) => product.name,
  subtitleBuilder: (product) => product.description,
  trailingTextBuilder: (product) => product.priceFormatted,
)

// List tile items
ListTileItemBuilder<Item>(
  leadingBuilder: (item) => Icon(item.icon),
  titleBuilder: (item) => item.title,
  trailingBuilder: (item) => Icon(Icons.chevron_right),
)

// Grid tile items
GridTileItemBuilder<Product>(
  imageBuilder: (product) => Image.network(product.imageUrl),
  titleBuilder: (product) => product.name,
)

// Custom items
CustomItemBuilder<T>((context, item, index) {
  return YourCustomWidget(item);
})

🎨 Customization

Theme Customization

ScreenBuilderConfig(
  colorScheme: ColorScheme.fromSeed(
    seedColor: Colors.indigo,
    brightness: Brightness.dark,
  ),
  textTheme: GoogleFonts.poppinsTextTheme(),
  appBarConfig: AppBarConfig(
    centerTitle: true,
    elevation: 0,
  ),
)

Custom Field Types

FormFieldConfig(
  id: 'custom',
  type: FormFieldType.custom,
  customBuilder: (context, config, controller) {
    return YourCustomFieldWidget(
      controller: controller,
      config: config,
    );
  },
)

Custom Item Builders

class MyCustomItemBuilder<T> implements ItemBuilderBase<T> {
  @override
  Widget build(BuildContext context, T item, int index) {
    return MyCustomWidget(item);
  }
}

📱 Examples

Check out the /example folder for a complete demo app showcasing all screen types.

Run the example:

cd example
flutter run

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with ❤️ using Flutter 3 and Material 3 design principles.

📞 Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation

---

Made with Flutter 💙

save_points_screen_builder