gmana_flutter
Flutter UI toolkit for production apps: design tokens, widgets, typed form
fields, loading spinners, and Flutter extensions, built on the pure Dart
gmana package.
import 'package:gmana_flutter/gmana_flutter.dart';
One import gives you this package and everything in gmana (functional types,
extensions, predicates, validation, value objects, utilities). The one
exception is the functional State monad, which is hidden because it clashes
with Flutter's State. Import package:gmana/functional.dart with a prefix if
you need it.
Topic libraries are available when you want a narrower import:
import 'package:gmana_flutter/extensions.dart';
import 'package:gmana_flutter/form.dart';
import 'package:gmana_flutter/spinner.dart';
Requirements
- Dart SDK
^3.7.2 - Flutter
>=3.29.0
Installation
flutter pub add gmana_flutter
Guides
| Area | Guide |
|---|---|
| Flutter extensions | doc/extensions.md |
| Form fields and validators | doc/form.md |
| Loading spinners | doc/spinner.md |
| Widgets and tokens reference | doc/api.md |
| Pure Dart APIs | gmana guides |
Quick Start
import 'package:flutter/material.dart';
import 'package:gmana_flutter/gmana_flutter.dart';
void main() => runApp(const App());
class App extends StatelessWidget {
const App({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Gmana Flutter Demo',
theme: GColors.lightTheme,
darkTheme: GColors.darkTheme,
themeMode: 'system'.toThemeMode(),
home: const HomePage(),
);
}
}
class HomePage extends StatelessWidget {
const HomePage({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: const GAppBar(title: 'Home'),
body: Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
const GWaveDotSpinner(size: 28, color: GColors.primary),
const GGap.vertical(GSpacing.md),
Text(
'Ready',
style: TextStyle(color: GColors.primary.contrastText),
),
],
),
),
);
}
}
What You Can Use
| Area | APIs |
|---|---|
| Widgets | GAppBar, GButton, GCard, GListTile, GGap, GStarRatingBar, GTextField |
| Status UI | GTag, GBanner, GAvatar, GEmptyState |
| Forms | GEmailField, GPasswordField, GNumberField, GTextFormField, GConfirmPasswordField, GFormSubmitButton |
| Loading | GCircularSpinner, GLinearSpinner, GDotSpinner, GWaveSpinner, GWaveDotSpinner |
| Tokens | GColors, GFontWeight, GSpacing, GRadius, GMotion, GTone |
| Theme | ThemeModeX, ThemeModes |
| Extensions | ColorX, StringColorX, BoxConstraintsX, BuildContextResponsiveX, BuildContextX |
| Utilities | IconDataCodec, IconDataX, formatLocale, parseLocale, registerErrorHandlers |
Theme Setup
Use the built-in themes directly:
MaterialApp(
theme: GColors.lightTheme,
darkTheme: GColors.darkTheme,
themeMode: ThemeMode.system,
home: const HomePage(),
);
Or keep the selected theme mode as a string:
final savedTheme = 'dark';
MaterialApp(
themeMode: savedTheme.toThemeMode(),
theme: GColors.lightTheme,
darkTheme: GColors.darkTheme,
home: const HomePage(),
);
Useful theme helpers:
// ThemeMode extensions
ThemeMode.dark.toKey(); // 'dark'
ThemeMode.dark.toLabel(); // 'Dark Mode'
ThemeMode.dark.toIcon(); // Icons.dark_mode
// ThemeModes — all methods are static
ThemeModes.fromKey('light'); // ThemeMode.light
ThemeModes.getThemeKeys(); // ['system', 'light', 'dark']
ThemeModes.getThemeKeys().map(ThemeModes.getLabelFromKey).toList(); // ['System Mode', 'Light Mode', 'Dark Mode']
Forms
The field widgets wrap TextFormField with consistent defaults and the typed
validators from gmana. See doc/form.md for every field,
GForm, GFormController, and GValidators.
import 'package:flutter/material.dart';
import 'package:gmana_flutter/gmana_flutter.dart';
class AccountForm extends StatefulWidget {
const AccountForm({super.key});
@override
State<AccountForm> createState() => _AccountFormState();
}
class _AccountFormState extends State<AccountForm> {
final formKey = GlobalKey<FormState>();
final emailController = TextEditingController();
final passwordController = TextEditingController();
final confirmPasswordController = TextEditingController();
@override
void dispose() {
emailController.dispose();
passwordController.dispose();
confirmPasswordController.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Form(
key: formKey,
child: Column(
children: [
GEmailField(
controller: emailController,
label: 'Email',
),
const GGap.vertical(GSpacing.md),
GPasswordField(
controller: passwordController,
validationConfig: PasswordValidationConfig.strong(),
),
const GGap.vertical(GSpacing.md),
GConfirmPasswordField(
controller: confirmPasswordController,
passwordController: passwordController,
),
const GGap.vertical(GSpacing.xlg),
GButton(
label: 'Create account',
fullWidth: true,
onPressed: () {
if (formKey.currentState?.validate() ?? false) {
context.showSuccessSnackBar(message: 'Account form is valid');
}
},
),
],
),
);
}
}
For custom TextFormField configuration, use GConfiguredTextFormField:
GConfiguredTextFormField(
config: GTextFieldConfig(
controller: controller,
label: 'Display name',
hint: 'Enter your name',
prefixIcon: Icons.person,
validator: (value) => value == null || value.isEmpty ? 'Required' : null,
),
);
Loading Indicators
Use the lightweight indicators anywhere a normal widget is accepted:
const GCircularSpinner();
const GLinearSpinner();
const GDotSpinner(color: Colors.blue);
const GWaveDotSpinner(size: 24, color: Colors.blue);
Widgets
gmana_flutter provides core curated widgets:
// Buttons
GButton(
label: 'Submit',
onPressed: () => print('Submitted'),
variant: GButtonVariant.primary,
isLoading: false,
);
// Cards
GCard(
onTap: () => print('Tapped'),
child: Text('Card Content'),
);
// Input Fields
GTextField(
label: 'Password',
enablePasswordToggle: true,
enableClearButton: true,
);
// Spacing
const GGap.vertical(GSpacing.md);
const GGap.horizontal(GSpacing.lg);
const GGap(GSpacing.sm);
GButton has size presets, a destructive variant, and a trailing icon slot:
GButton(
label: 'Delete account',
variant: GButtonVariant.danger,
size: GButtonSize.large,
tooltip: 'This cannot be undone',
onPressed: confirmDelete,
);
GButton(
label: 'Next',
size: GButtonSize.small,
trailingIcon: const Icon(Icons.arrow_forward, size: 16),
onPressed: goNext,
);
GStarRatingBar is read-only until you give it a callback:
GStarRatingBar(
ratingValue: rating,
starSize: 32,
onRatingChanged: (value) => setState(() => rating = value),
);
Design Tokens
Radius and motion tokens keep components visually consistent:
GRadius.xs; // 4 — chips, tags
GRadius.sm; // 8 — buttons, inputs
GRadius.md; // 12 — cards
GRadius.pill; // fully rounded
GRadius.all(GRadius.md); // BorderRadius
GRadius.top(GRadius.lg); // top corners only
GRadius.start(GRadius.sm); // direction-aware
GRadius.shape(GRadius.md); // RoundedRectangleBorder
GMotion.fast; // 150ms
GMotion.normal; // 250ms
GMotion.standard; // Curves.easeInOut
AnimatedContainer(
duration: GMotion.normal,
curve: GMotion.standard,
decoration: BoxDecoration(borderRadius: GRadius.all()),
child: child,
);
GSpacing also covers single sides and RTL-aware insets:
GSpacing.paddingOnly(left: GSpacing.md, bottom: GSpacing.sm);
GSpacing.paddingDirectional(start: GSpacing.lg, end: GSpacing.xs);
Semantic Tones
GTone is the shared vocabulary behind the status widgets. It resolves the
GColors semantic tokens for the current theme — light mode uses the
hand-tuned containers, dark mode derives a readable tint instead.
final colors = GTone.warning.resolve(context);
Container(
color: colors.container,
child: Text('Careful', style: TextStyle(color: colors.onContainer)),
);
GTone.error.icon; // Icons.error_outline
GTone.success.icon; // Icons.check_circle_outline
Status And Placeholder Widgets
Tags
const GTag(label: 'Active', tone: GTone.success);
const GTag(label: 'Overdue', tone: GTone.error, filled: true);
const GTag(label: 'Beta', icon: Icons.science, compact: true);
GTag(label: 'Filter', onTap: applyFilter);
Banners
const GBanner(
tone: GTone.warning,
title: 'Payment overdue',
message: 'Update your card to keep the subscription active.',
);
GBanner(
tone: GTone.error,
message: 'Could not reach the server.',
onDismiss: hideBanner,
actions: [
GButton(label: 'Retry', size: GButtonSize.small, onPressed: retry),
],
);
Avatars
GAvatar(name: 'Ada Lovelace'); // 'AL' on a stable tint
GAvatar(image: NetworkImage(url), name: 'Ada'); // falls back if it fails
GAvatar(name: 'Ada', size: 56, square: true);
GAvatar(
name: 'Ada',
badge: const Icon(Icons.circle, size: 10, color: Colors.green),
);
// The same tint the avatar picks, for matching chrome
final tint = GAvatar.tintFor('Ada Lovelace');
Empty states
GEmptyState(
icon: Icons.inbox_outlined,
title: 'No messages',
message: 'When someone writes to you it will show up here.',
action: GButton(label: 'Refresh', onPressed: reload),
);
const GEmptyState(title: 'Nothing matched', compact: true);
Use GWaveSpinner with explicit bounds:
const SizedBox(
width: 48,
height: 48,
child: GWaveSpinner(color: GColors.primary),
);
GButton shows a spinner while work is running. Inside a GForm,
GFormSubmitButton drives that state from the form controller:
GButton(label: 'Save', isLoading: saving, onPressed: save);
GFormSubmitButton(label: 'Save', onSubmit: (values) => repository.save(values));
Color Utilities
Color extensions cover common UI operations:
const brand = Color(0xFFF57224);
final rgb = brand.toHexRGB(); // '#F57224'
final argb = brand.toHexARGB(); // '#FFF57224'
final textColor = brand.contrastText;
final hover = brand.lighten(0.08);
final pressed = brand.darken(0.12);
final muted = brand.desaturate(0.2);
final complementary = brand.complementary;
final materialSwatch = brand.toMaterialColor();
Parse colors from strings:
final fromFullHex = '#F57224'.toColor();
final fromShortHex = '#F50'.toColor();
final optionalColor = ColorMath.tryParseHex('#80F57224');
Check contrast:
final passesAA = Colors.white.meetsWcagAA(GColors.primary);
final ratio = Colors.white.contrastRatio(GColors.primary);
Responsive Layout
Resolve values from BoxConstraints:
LayoutBuilder(
builder: (context, constraints) {
final columns = constraints.resolve(
mobile: 1,
tablet: 2,
desktop: 3,
widescreen: 4,
);
return GridView.count(
crossAxisCount: columns,
children: const [],
);
},
);
Resolve values from BuildContext:
final padding = context.responsive(
mobile: 16.0,
tablet: 24.0,
desktop: 32.0,
widescreen: 40.0,
);
final isCompact = context.isMobile;
final size = context.screenSize;
Layout & Responsive Widgets
GResponsiveBuilder
GResponsiveBuilder(
mobile: (context) => MobileLayout(),
tablet: (context) => TabletLayout(),
desktop: (context) => DesktopLayout(),
)
It switches at the same thresholds as context.breakpoint: tablet from
Breakpoints.tablet (730) and desktop from Breakpoints.desktop (1200). Pass
mobileBreakpoint and tabletBreakpoint to use others.
GGrid
GGrid(
maxItemWidth: 200,
spacing: GSpacing.md,
children: [Card1(), Card2(), Card3()],
)
GGap
Column(
children: [
WidgetA(),
GGap.vertical(GSpacing.md),
WidgetB(),
],
)
GDivider
GDivider(label: 'OR')
Snackbars, Navigation, And Dialogs
BuildContextX gives short helpers for common app actions:
context.showSuccessSnackBar(message: 'Saved');
context.showErrorSnackBar(message: 'Unable to save');
context.unfocus();
final confirmed = await context.showConfirmDialog(
title: 'Delete item?',
message: 'This action cannot be undone.',
destructive: true,
);
if (confirmed) {
context.pop();
}
Icon Serialization
Store Flutter IconData values as JSON strings:
final json = Icons.home.toJsonString();
final icon = IconDataCodec.tryParse(json) ?? Icons.broken_image;
Use a fallback when parsing required values:
final icon = IconDataCodec.parse(
savedIconJson,
fallback: Icons.help_outline,
);
Locale Helpers
Convert between Locale and underscore-separated locale tags:
final tag = formatLocale(const Locale('en', 'US')); // 'en_US'
final locale = parseLocale('km_KH'); // Locale('km', 'KH')
Error Handler Setup
Call registerErrorHandlers() once in main() when you want Flutter framework
errors forwarded through the package's handler setup:
void main() {
registerErrorHandlers();
runApp(const App());
}
Example App
The package includes a Flutter showcase under example/.
cd example
flutter pub get
flutter run
The example demonstrates theme switching, color utilities, layout polish, the package's UI components, and dedicated pages for the Flutter extensions, form fields, and loading spinners.
Libraries
- extensions
- Flutter extension methods and small services for colors, layout, context, icons, time, and theme mode.
- form
- Form fields, validators, and submit controls built on
gmanavalidation. - gmana_flutter
- Flutter UI toolkit for the gmana ecosystem: design tokens, widgets, form fields, spinners, and Flutter extensions.
- spinner
- Flutter loading spinner widgets for the Gmana ecosystem.