flutter_gb_ui_kit 4.0.0

A UI utility package for Geekbears, it contains some useful UI widgets

flutter_gb_ui_kit

A comprehensive, production-ready Flutter UI Kit and design system tailored for modern mobile applications. Built on top of Flutter Material 3, flutter_gb_ui_kit provides robust theming, smart async buttons, accessible form controls, smooth micro-animations, and reusable turnkey screen templates.

---

🚀 Key Features

• 🎨 Modern Material 3 Theming: Factory helper (createGBTheme) generating a unified ThemeData across color schemes, typography, radiuses, and component themes.
• ⚡ Smart Asynchronous Buttons: ContainedButton, OutlinedButton, and LinkButton subclassing standard Material 3 buttons with built-in debounced loading states (busy).
• 📝 Form Inputs & Selects: Rich input suite featuring TextField with custom validation feedback checklists, PasswordField with visibility toggle, 4/6-digit CodeField (PIN/OTP), SelectField (Bottom Sheet & Overlay modes), MultiSelectField with chips, and Switcher.
• ✨ Micro-Animations & Shimmers: MusicVisualizer frequency waves, AnimatedPlaceholder skeleton shimmers, AnimatedFadeHeightSwitcher accordion toggles, and AnimatedDisplayable.
• 📜 Dynamic Lists & Slivers: AnimatableStateListView for auto-diffing smooth item insertions and deletions, and SliverFooter for pinning footers in CustomScrollViews.
• 💬 Modals & Snackbars: Accessible dialogs (showAppModal) and floating alerts (showSnackBarAlert).
• 🛠️ Utility Components: ScreenLoadingIndicator, Stepper, TimePicker with slot constraints, GenericDataHandlerWidget (loading/error/retry), and TimerCountDownBuilder.
• 📱 Production Screen Templates: Turnkey authentication screens including Login, Sign Up, Password Recovery, Code Verification, and Loading/Error state views.

---

📖 Table of Contents

1. Installation
2. Quick Start & Theming
3. Component Showcases
   • Buttons & Actions
   • Form Fields & Inputs
   • Animations & Shimmers
   • Lists & Slivers
   • Utilities & Modals
4. Screen Templates
5. Running the Example App
6. Migration Guide

---

Installation

Add flutter_gb_ui_kit to your project's pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  flutter_gb_ui_kit:
    path: ../gb-ui-kit # or your git/pub dependency

Then run:

flutter pub get

---

Quick Start & Theming

flutter_gb_ui_kit leverages standard Flutter ThemeData via createGBTheme(). Wrap your app root with OverlayCanvas to support overlay-mode dropdowns and popups.

import 'package:flutter/material.dart';
import 'package:flutter_gb_ui_kit/flutter_gb_ui_kit.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // Generate a cohesive Material 3 theme
    final theme = createGBTheme(
      primary: const Color(0xFF2563EB),
      secondary: const Color(0xFFF59E0B),
      background: Colors.white,
      surface: Colors.white,
      borderRadius: BorderRadius.circular(12),
      isDark: false,
    );

    return MaterialApp(
      title: 'My App',
      theme: theme,
      builder: (context, child) => OverlayCanvas(
        child: child ?? const SizedBox.shrink(),
      ),
      home: const HomeScreen(),
    );
  }
}

---

Component Showcases

Buttons & Actions

Buttons inherit your ThemeData styling and provide automatic spinner debounce handling when asynchronous tasks are executing:

// Large Primary Button with built-in busy indicator
ContainedButton.large(
  text: 'Submit Application',
  busy: _isSubmitting,
  onPressed: _handleSubmit,
);

// Gradient Button
ContainedButton.large(
  text: 'Upgrade to Pro',
  gradient: const GBButtonGradient(
    colors: [Color(0xFF2563EB), Color(0xFF7C3AED)],
  ),
  onPressed: _handleUpgrade,
);

// Outlined Button
OutlinedButton.small(
  text: 'Cancel',
  onPressed: () => Navigator.pop(context),
);

// Inline Action Link Text
ComposedActionText(
  normalText: 'Don’t have an account? ',
  actionText: 'Sign Up',
  onAction: () => navigateToSignUp(),
);

Form Fields & Inputs

// Text Field with icon and helper
TextField(
  label: 'Email Address',
  hintText: '[e-mail]',
  prefixIcon: const Icon(Icons.email_outlined),
  errorText: _hasError ? 'Invalid email format' : null,
);

// Password Field with eye toggle
PasswordField(
  label: 'Password',
  hintText: 'Enter your password',
);

// 4-Digit OTP / PIN Field
CodeField(
  length: 4,
  onChanged: (pin) {
    if (pin.length == 4) verifyPin(pin);
  },
);

// Single Select Field (Bottom Sheet or Overlay menu)
SelectField<String>(
  label: 'Country / Region',
  unselectedString: 'Choose your region',
  options: const [
    SelectFieldOption(title: 'United States', value: 'US'),
    SelectFieldOption(title: 'Canada', value: 'CA'),
    SelectFieldOption(title: 'United Kingdom', value: 'UK'),
  ],
  makeOverlay: true, // false for modal bottom sheet
  enableSearch: true,
  onSelected: (code) => print('Selected: $code'),
);

// Multi-Select Field with compact chips
MultiSelectField<String>(
  label: 'Skills',
  options: mySkillOptions,
  initialValue: const ['flutter', 'dart'],
  initialValueComparison: (initial, val) => initial.contains(val),
  onSelected: (selectedList) => print(selectedList),
);

Animations & Shimmers

// Audio equalizer frequency wave visualizer
MusicVisualizer(
  barCount: 25,
  colors: [Colors.blue, Colors.purple],
  duration: [900, 700, 600, 800, 500],
);

// Shimmer skeleton loading placeholder
AnimatedPlaceholder(
  height: 60,
  width: double.infinity,
  borderRadius: BorderRadius.circular(12),
);

// Accordion Expand/Collapse Switcher
AnimatedFadeHeightSwitcher(
  expanded: _isSectionOpen,
  child: MyDetailsWidget(),
);

Lists & Slivers

// Auto-animating collection diff list
AnimatableStateListView<TaskItem>(
  items: tasks,
  idMapper: (task) => task.id,
  itemBuilder: (context, index, animation, task) {
    return SizeTransition(
      sizeFactor: animation,
      child: ListTile(title: Text(task.title)),
    );
  },
);

// Sticking or viewport-filling footer in CustomScrollViews
CustomScrollView(
  slivers: [
    SliverList(...),
    SliverFooter(
      fillRemaining: true,
      footer: LegalDisclaimerWidget(),
    ),
  ],
);

Utilities & Modals

// Theme-styled modal dialogues
showAppModal(
  context,
  title: const Text('Confirm Action'),
  message: const Text('Are you sure you want to proceed?'),
  actions: [
    OutlinedButton.small(text: 'Cancel', onPressed: () => Navigator.pop(context)),
    ContainedButton.small(text: 'Confirm', onPressed: _onConfirm),
  ],
);

// Toast alert snackbars
showSnackBarAlert(
  context,
  title: 'Profile Updated',
  message: 'Your settings have been saved.',
  type: SnackbarAlertType.success,
);

// Countdown timer for OTP expirations and promotions
TimerCountDownBuilder(
  toDate: DateTime.now().add(const Duration(minutes: 10)),
  builder: (context, state) {
    return Text('Expires in: ${state.timeToEndFormatted}');
  },
);

---

Screen Templates

flutter_gb_ui_kit comes bundled with high-converting, accessible screen templates to jumpstart app development:

Template	Description
LoginTemplate	Authentication view with email, password, remember me, and forgot password triggers.
SignUpTemplate	Registration view with terms acceptance, dynamic validations, and login redirect.
RequestPasswordResetTemplate	Password recovery request with instructions and email field.
ResetPasswordCodeInputTemplate	Verification code (OTP) input with resend countdown timer.
ResetPasswordSetTemplate	Form view to input and confirm new password credentials.
AccountCodeConfirmationTemplate	Account activation code entry with resend timer.
LoadingTemplate	Branded full-screen loader with animated indicators and status copy.
ErrorTemplate	Friendly error presentation with retry action handling.

Detailed template documentation and visual previews can be found in docs/TEMPLATE_SCREENS.md.

---

Running the Example App

The example/ folder contains a full catalog application demonstrating every component in action with live Material 3 theme switching (6 curated palettes and 4 corner-radius presets).

To run the interactive showcase:

cd example
flutter pub get
flutter run

---

Migration Guide

If you are upgrading from flutter_gb_ui_kit v3.x or earlier (projects using legacy GBTheme, GBThemeData, or GBText), see our comprehensive MIGRATION_GUIDE.md for step-by-step instructions.