create-flutterinit 0.1.0

package/templates/base/lib/src/shared/helpers/show_dialog.dart.hbs

@@ -0,0 +1,49 @@
+import 'dart:ui';
+import '../../imports/imports.dart';
+
+/// Shows a premium custom dialog with optional backdrop blur.
+/// 
+/// This helper uses the [rootNavigatorKey] to display the dialog 
+/// without needing a local [BuildContext].
+Future<T?> showAppDialog<T>({
+  required Widget child,
+  bool hasBlur = true,
+  double blurSigma = 5.0,
+  Color barrierColor = Colors.black26,
+  bool dismissible = true,
+  Duration duration = const Duration(milliseconds: 300),
+}) {
+  final context = rootContext;
+  if (context == null) return Future.value(null);
+
+  return showGeneralDialog<T>(
+    context: context,
+    barrierColor: barrierColor,
+    barrierDismissible: dismissible,
+    barrierLabel: 'AppDialog',
+    transitionDuration: duration,
+    pageBuilder: (context, animation, secondaryAnimation) => child,
+    transitionBuilder: (context, animation, secondaryAnimation, child) {
+      final curve = Curves.easeInOut.transform(animation.value);
+      return BackdropFilter(
+        filter: ImageFilter.blur(
+          sigmaX: hasBlur ? (blurSigma * animation.value) : 0,
+          sigmaY: hasBlur ? (blurSigma * animation.value) : 0,
+        ),
+        child: Opacity(
+          opacity: animation.value,
+          child: Transform.scale(
+            scale: 0.9 + (0.1 * curve),
+            child: child,
+          ),
+        ),
+      );
+    },
+  );
+}
+
+/// Alias for [showAppDialog] to maintain compatibility with custom references.
+Future<T?> showCustomDialogue<T>({
+  required Widget child,
+  bool hasBlur = true,
+}) => showAppDialog<T>(child: child, hasBlur: hasBlur);

package/templates/base/lib/src/shared/helpers/show_toast.dart.hbs

@@ -0,0 +1,92 @@
+import '../../imports/imports.dart';
+
+void showToast(
+  BuildContext context, {
+  required String message,
+  String? status = 'success',
+  dynamic icon,
+  Duration? duration,
+  bool? autoDismiss,
+}) {
+  final toastStatus = status ?? 'info';
+  final colorScheme = context.colors;
+  final appColors = context.appColors;
+
+  final (backgroundColor, foregroundColor, iconColor) = switch (toastStatus) {
+    'error' => (
+      colorScheme.errorContainer,
+      colorScheme.onErrorContainer,
+      colorScheme.error,
+    ),
+    'success' => (
+      appColors.successContainer ?? appColors.success,
+      appColors.onSuccessContainer ?? appColors.onSuccess,
+      appColors.success,
+    ),
+    'warning' => (
+      appColors.warningContainer ?? appColors.warning,
+      appColors.onWarningContainer ?? appColors.onWarning,
+      appColors.warning,
+    ),
+    'info' => (
+      appColors.infoContainer ?? appColors.info,
+      appColors.onInfoContainer ?? appColors.onInfo,
+      appColors.info,
+    ),
+    _ => (
+      context.theme.scaffoldBackgroundColor,
+      colorScheme.onSurface,
+      colorScheme.onSurfaceVariant,
+    ),
+  };
+
+  return ToastBar(
+    position: ToastPosition.top,
+    autoDismiss: autoDismiss ?? true,
+    toastDuration: duration ?? const Duration(seconds: 2),
+    animationDuration: const Duration(milliseconds: 150),
+    animationCurve: Curves.easeIn,
+    builder: (context) => ToastCard(
+      color: backgroundColor,
+      shadowColor: colorScheme.shadow.withValues(alpha: 0.05),
+      leading: AppIcon(
+        icon: icon ??
+            (toastStatus == 'success'
+                ? {{#if flags.usesIconsaxPlus}}IconsaxPlusBold.tick_circle{{else if flags.usesFlutterRemix}}FlutterRemix.checkbox_circle_fill{{else if flags.usesHugeicons}}HugeIcons.strokeRoundedTickCircle{{else}}Icons.check_circle_outline{{/if}}
+                : toastStatus == 'error'
+                    ? {{#if flags.usesIconsaxPlus}}IconsaxPlusBold.danger{{else if flags.usesFlutterRemix}}FlutterRemix.error_warning_fill{{else if flags.usesHugeicons}}HugeIcons.strokeRoundedAlertCircle{{else}}Icons.error_outline{{/if}}
+                    : {{#if flags.usesIconsaxPlus}}IconsaxPlusBold.info_circle{{else if flags.usesFlutterRemix}}FlutterRemix.information_fill{{else if flags.usesHugeicons}}HugeIcons.strokeRoundedInformationCircle{{else}}Icons.info_outline{{/if}}),
+        color: iconColor,
+        size: {{res 22 'sp' flags.usesScreenutil}},
+      ),
+      title: Text(
+        message,
+        style: context.theme.textTheme.labelSmall!.copyWith(
+          fontWeight: FontWeight.w600,
+          fontSize: {{res 11 'sp' flags.usesScreenutil}},
+          color: foregroundColor,
+        ),
+      ),
+    ),
+  ).show(context);
+}
+
+void showGlobalToast({
+  required String message,
+  String? status = 'success',
+  dynamic icon,
+  Duration? duration,
+  bool? autoDismiss,
+}) {
+  final ctx = rootContext;
+  if (ctx == null) return;
+
+  showToast(
+    ctx,
+    message: message,
+    status: status,
+    icon: icon,
+    duration: duration,
+    autoDismiss: autoDismiss,
+  );
+}

package/templates/base/lib/src/shared/hooks/hooks.dart.hbs

@@ -0,0 +1,13 @@
+{{#if flags.usesFlutterHooks}}
+export 'use_copy.dart';
+{{#if flags.usesSharePlus}}
+export 'use_share.dart';
+{{/if}}
+{{#if flags.usesPermissionHandler}}
+export 'use_permission.dart';
+{{/if}}
+{{#if flags.usesUrlLauncher}}
+export 'use_launch_url.dart';
+{{/if}}
+export 'use_timer.dart';
+{{/if}}

package/templates/base/lib/src/shared/hooks/use_copy.dart.hbs

@@ -0,0 +1,41 @@
+{{#if flags.usesFlutterHooks}}
+import '../../imports/imports.dart';
+
+/// A hook to handle copying text to clipboard with state feedback.
+(Future<void> Function(String), bool) useCopy() {
+  final hasCopied = useState(false);
+
+  Future<void> copyToClipboard(String text) async {
+    try {
+      hasCopied.value = true;
+      await Clipboard.setData(ClipboardData(text: text));
+      
+      showGlobalToast(
+        message: 'Copied successfully',
+        status: 'success',
+      );
+
+      await Future.delayed(
+        const Duration(seconds: 2),
+        () => hasCopied.value = false,
+      );
+    } catch (e) {
+      AppLogger.error('Error copying to clipboard: $e');
+      hasCopied.value = false;
+      
+      showGlobalToast(
+        message: 'Failed to copy',
+        status: 'error',
+      );
+    }
+  }
+
+  useEffect(() {
+    return () {
+      hasCopied.value = false;
+    };
+  }, []);
+
+  return (copyToClipboard, hasCopied.value);
+}
+{{/if}}

package/templates/base/lib/src/shared/hooks/use_timer.dart.hbs

@@ -0,0 +1,158 @@
+{{#if flags.usesFlutterHooks}}
+import 'dart:async';
+import 'package:flutter/widgets.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
+
+/// A lightweight immutable value representing the current time and time left.
+class TimerTick {
+  const TimerTick({required this.now, required this.remaining});
+
+  final DateTime now;
+  final Duration remaining;
+
+  /// Convenience formatted remaining time as mm:ss.
+  String get remainingMmSs => formatMmSs(remaining);
+}
+
+/// Runs a countdown for [duration], invokes [onComplete] at the end, and
+/// returns the current [TimerTick] containing `now` and `remaining`.
+///
+/// - Set [isActive] to false to stop the timer.
+/// - Changing [duration], [isActive], [tick], or [onComplete] restarts logic.
+/// - The timer is cancelled automatically on dispose.
+TimerTick useTimer({
+  required Duration duration,
+  required VoidCallback onComplete,
+  bool isActive = true,
+  Duration tick = const Duration(seconds: 1),
+  bool autoStart = true,
+}) =>
+    use(_TimerHook(
+      duration: duration,
+      onComplete: onComplete,
+      isActive: isActive,
+      tick: tick,
+      autoStart: autoStart,
+    ));
+
+class _TimerHook extends Hook<TimerTick> {
+  const _TimerHook({
+    required this.duration,
+    required this.onComplete,
+    required this.isActive,
+    required this.tick,
+    required this.autoStart,
+  });
+
+  final Duration duration;
+  final VoidCallback onComplete;
+  final bool isActive;
+  final Duration tick;
+  final bool autoStart;
+
+  @override
+  HookState<TimerTick, _TimerHook> createState() => _TimerHookState();
+}
+
+class _TimerHookState extends HookState<TimerTick, _TimerHook> {
+  Timer? _timer;
+  late DateTime _now;
+  late Duration _remaining;
+  DateTime? startedAt;
+  int? _lastLoggedRemainingSecs;
+  late VoidCallback _onComplete;
+
+  @override
+  void initHook() {
+    super.initHook();
+    _now = DateTime.now();
+    _remaining = hook.duration;
+    _onComplete = hook.onComplete;
+    _lastLoggedRemainingSecs = _remaining.inSeconds;
+
+    if (hook.autoStart) {
+      _startOrStop();
+    }
+  }
+
+  @override
+  void didUpdateHook(covariant _TimerHook oldHook) {
+    super.didUpdateHook(oldHook);
+    final shouldRestart = oldHook.duration != hook.duration ||
+        oldHook.isActive != hook.isActive ||
+        oldHook.tick != hook.tick;
+    // Always keep the latest completion callback without forcing a restart.
+    if (oldHook.onComplete != hook.onComplete) {
+      _onComplete = hook.onComplete;
+    }
+    if (shouldRestart) _startOrStop();
+  }
+
+  @override
+  TimerTick build(BuildContext context) =>
+      TimerTick(now: _now, remaining: _remaining);
+
+  void _startOrStop() {
+    _timer?.cancel();
+    startedAt = DateTime.now();
+    _now = startedAt!;
+    _remaining = hook.duration;
+    _lastLoggedRemainingSecs = _remaining.inSeconds;
+    if (!hook.isActive) {
+      return;
+    }
+
+    void handleTick() {
+      final current = DateTime.now();
+      final elapsed = current.difference(startedAt!);
+      final left = hook.duration - elapsed;
+      final leftSecs = left.inSeconds;
+      if (left <= Duration.zero) {
+        _now = current;
+        _remaining = Duration.zero;
+        _timer?.cancel();
+
+        if (context.mounted) _onComplete();
+        setState(() {});
+        return;
+      }
+
+      setState(() {
+        _now = current;
+        _remaining = left;
+      });
+
+      if (_lastLoggedRemainingSecs != leftSecs) {
+        _lastLoggedRemainingSecs = leftSecs;
+      }
+    }
+
+    // Fire an immediate tick so the UI reflects that the timer started
+    // without waiting for the first interval.
+    handleTick();
+
+    // Periodic updates to compute remaining and call completion.
+    _timer = Timer.periodic(hook.tick, (_) => handleTick());
+  }
+
+  @override
+  void dispose() {
+    _timer?.cancel();
+    super.dispose();
+  }
+}
+
+/// Formats a [Duration] adaptively as:
+/// - H:MM:SS when hours > 0
+/// - M:SS otherwise (including pure seconds)
+String formatMmSs(Duration duration) {
+  final totalSeconds = duration.inSeconds < 0 ? 0 : duration.inSeconds;
+  final hours = totalSeconds ~/ 3600;
+  final minutes = (totalSeconds % 3600) ~/ 60;
+  final seconds = totalSeconds % 60;
+  if (hours > 0) {
+    return '$hours:${minutes.toString().padLeft(2, '0')}:${seconds.toString().padLeft(2, '0')}';
+  }
+  return '$minutes:${seconds.toString().padLeft(2, '0')}';
+}
+{{/if}}

package/templates/base/lib/src/shared/shared.dart.hbs

@@ -0,0 +1,12 @@
+export 'helpers/imports.dart';
+export '../extensions/extensions.dart';
+export '../utils/utils.dart';
+
+export 'enums/enums.dart';
+export 'widgets/widgets.dart';
+export '../theme/theme_constants.dart';
+export 'wrappers/wrappers.dart';
+export 'app_assets.dart';
+{{#if flags.usesFlutterHooks}}
+export 'hooks/hooks.dart';
+{{/if}}

package/templates/base/lib/src/shared/widgets/app_button.dart.hbs

@@ -0,0 +1,144 @@
+import '../../imports/imports.dart';
+
+/// A fully themed button supporting all [ButtonVariant]s and [ButtonSize]s.
+///
+/// Usage:
+/// ```dart
+/// AppButton(
+///   label: 'Save',
+///   onPressed: _save,
+///   variant: ButtonVariant.primary,
+///   size: ButtonSize.large,
+///   isLoading: state.isLoading,
+/// )
+/// ```
+class AppButton extends StatelessWidget {
+  const AppButton({
+    super.key,
+    required this.label,
+    this.onPressed,
+    this.variant = ButtonVariant.primary,
+    this.color,
+    this.textColor,
+    this.height = ButtonSize.medium,
+    this.width,
+    this.isLoading = false,
+    this.isFullWidth = false,
+    this.prefixIcon,
+    this.suffixIcon,
+  });
+
+  final String label;
+  final VoidCallback? onPressed;
+  final ButtonVariant variant;
+  final Color? color;
+  final Color? textColor;
+  final ButtonSize height;
+  final ButtonSize? width;
+  final bool isLoading;
+  final bool isFullWidth;
+  final Widget? prefixIcon;
+  final Widget? suffixIcon;
+
+  @override
+  Widget build(BuildContext context) {
+    final cs = context.theme.colorScheme;
+    final appColors = context.theme.extension<AppColorsExtension>()!;
+    final isDisabled = onPressed == null || isLoading;
+
+    final double buttonHeight = switch (height) {
+      ButtonSize.small  => {{res 36 'h' flags.usesScreenutil}},
+      ButtonSize.medium => {{res 48 'h' flags.usesScreenutil}},
+      ButtonSize.large  => {{res 56 'h' flags.usesScreenutil}},
+    };
+
+    final double? buttonWidth = switch (width) {
+      ButtonSize.small  => {{res 100 'w' flags.usesScreenutil}},
+      ButtonSize.medium => {{res 150 'w' flags.usesScreenutil}},
+      ButtonSize.large  => {{res 200 'w' flags.usesScreenutil}},
+      null              => null,
+    };
+
+    final double horizontalPadding = switch (height) {
+      ButtonSize.small  => {{res 12 'w' flags.usesScreenutil}},
+      ButtonSize.medium => {{res 20 'w' flags.usesScreenutil}},
+      ButtonSize.large  => {{res 28 'w' flags.usesScreenutil}},
+    };
+
+    final double fontSize = switch (height) {
+      ButtonSize.small  => {{res 12 'sp' flags.usesScreenutil}},
+      ButtonSize.medium => {{res 14 'sp' flags.usesScreenutil}},
+      ButtonSize.large  => {{res 16 'sp' flags.usesScreenutil}},
+    };
+
+    final (bg, fg, border) = switch (variant) {
+      ButtonVariant.primary   => (color ?? cs.primary, color ?? cs.onPrimary, null),
+      ButtonVariant.secondary => (cs.secondaryContainer, cs.onSecondaryContainer, null),
+      ButtonVariant.outline   => (Colors.transparent, cs.primary, BorderSide(color: cs.outline, width: 1.5)),
+      ButtonVariant.ghost     => (Colors.transparent, cs.primary, null),
+      ButtonVariant.danger    => (cs.error, cs.onError, null),
+      ButtonVariant.success   => (appColors.success, appColors.onSuccess, null),
+    };
+
+    final child = AnimatedSwitcher(
+      duration: AppDurations.fast,
+      switchInCurve: AppCurves.decelerate,
+      child: isLoading
+          ? SizedBox(
+              key: const ValueKey('loader'),
+              width: {{res 20 'w' flags.usesScreenutil}},
+              height: {{res 20 'h' flags.usesScreenutil}},
+              child: CircularProgressIndicator(
+                strokeWidth: 2,
+                color: fg,
+              ),
+            )
+          : Row(
+              key: const ValueKey('content'),
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                if (prefixIcon != null) ...[
+                  prefixIcon!,
+                  {{#if flags.usesScreenutil}}SizedBox(width: 8.w){{else}}const SizedBox(width: 8){{/if}},
+                ],
+                Text(
+                  label,
+                  style: TextStyle(
+                    fontSize: fontSize,
+                    fontWeight: FontWeight.w600,
+                    color: isDisabled ?  fg.withValues(alpha: 0.5) : textColor ?? fg,
+                  ),
+                ),
+                if (suffixIcon != null) ...[
+                  {{#if flags.usesScreenutil}}SizedBox(width: 8.w){{else}}const SizedBox(width: 8){{/if}},
+                  suffixIcon!,
+                ],
+              ],
+            ),
+    );
+
+    return AnimatedOpacity(
+      duration: AppDurations.fast,
+      opacity: isDisabled ? 0.6 : 1.0,
+      child: SizedBox(
+        width: isFullWidth ? double.infinity : buttonWidth,
+        height: buttonHeight,
+        child: TextButton(
+          onPressed: isDisabled ? null : onPressed,
+          style: TextButton.styleFrom(
+            backgroundColor: bg,
+            foregroundColor: fg,
+            padding: EdgeInsets.symmetric(horizontal: horizontalPadding),
+            shape: border != null
+                ? RoundedRectangleBorder(
+                    borderRadius: AppBorders.button,
+                    side: border,
+                  )
+                : const RoundedRectangleBorder(borderRadius: AppBorders.button),
+          ),
+          child: child,
+        ),
+      ),
+    );
+  }
+}

package/templates/base/lib/src/shared/widgets/app_card.dart.hbs

@@ -0,0 +1,126 @@
+import '../../imports/imports.dart';
+
+/// A themed card widget with consistent padding, radius, and optional header.
+///
+/// Usage:
+/// ```dart
+/// AppCard(
+///   child: Text('Card content'),
+/// )
+///
+/// // With a header
+/// AppCard(
+///   title: 'Recent Transactions',
+///   trailing: TextButton(onPressed: _seeAll, child: const Text('See all')),
+///   child: TransactionList(),
+/// )
+/// ```
+class AppCard extends StatelessWidget {
+  const AppCard({
+    super.key,
+    required this.child,
+    this.title,
+    this.subtitle,
+    this.leading,
+    this.trailing,
+    this.padding,
+    this.margin,
+    this.onTap,
+    this.showShadow = false,
+    this.color,
+  });
+
+  final Widget child;
+  final String? title;
+  final String? subtitle;
+  final Widget? leading;
+  final Widget? trailing;
+  final EdgeInsetsGeometry? padding;
+  final EdgeInsetsGeometry? margin;
+  final VoidCallback? onTap;
+
+  /// When true, uses [AppShadows.card] instead of a border outline.
+  final bool showShadow;
+  final Color? color;
+
+  @override
+  Widget build(BuildContext context) {
+    final cs = context.theme.colorScheme;
+    final tt = context.theme.textTheme;
+
+    final cardColor = color ?? cs.surfaceContainerLow;
+
+    final Widget content = Column(
+      mainAxisSize: MainAxisSize.min,
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        if (title != null || leading != null || trailing != null)
+          Padding(
+            padding: EdgeInsets.only(
+              left: AppSpacing.md,
+              right: AppSpacing.md,
+              top: AppSpacing.md,
+              bottom: AppSpacing.sm,
+            ),
+            child: Row(
+              children: [
+                if (leading != null) ...[leading!, {{#if flags.usesScreenutil}}SizedBox(width: 12.w){{else}}const SizedBox(width: 12){{/if}}],
+                Expanded(
+                  child: Column(
+                    crossAxisAlignment: CrossAxisAlignment.start,
+                    children: [
+                      if (title != null)
+                        Text(
+                          title!,
+                          style: tt.titleMedium?.copyWith(
+                            fontWeight: FontWeight.w600,
+                          ),
+                        ),
+                      if (subtitle != null)
+                        Text(
+                          subtitle!,
+                          style: tt.bodySmall?.copyWith(
+                            color: cs.onSurfaceVariant,
+                          ),
+                        ),
+                    ],
+                  ),
+                ),
+                if (trailing != null) trailing!,
+              ],
+            ),
+          ),
+        Padding(
+          padding: padding ??
+              EdgeInsets.fromLTRB(
+                AppSpacing.md,
+                title == null ? AppSpacing.md : 0,
+                AppSpacing.md,
+                AppSpacing.md,
+              ),
+          child: child,
+        ),
+      ],
+    );
+
+    return Container(
+      margin: margin,
+      decoration: BoxDecoration(
+        color: cardColor,
+        borderRadius: AppBorders.card,
+        border: showShadow
+            ? null
+            : Border.all(color: cs.outlineVariant, width: 1),
+        boxShadow: showShadow ? AppShadows.card : AppShadows.none,
+      ),
+      clipBehavior: Clip.antiAlias,
+      child: onTap != null
+          ? InkWell(
+              onTap: onTap,
+              borderRadius: AppBorders.card,
+              child: content,
+            )
+          : content,
+    );
+  }
+}