@marcos_feitoza/personal-finance-frontend-core-ui 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.2.2](https://github.com/MarcosOps/personal-finance-frontend-core-ui/compare/v1.2.1...v1.2.2) (2026-01-30)
+
+
+### Bug Fixes
+
+* Padronizar mensagens de erro e estados de loading ([66ea1d0](https://github.com/MarcosOps/personal-finance-frontend-core-ui/commit/66ea1d074dffa12bcd068265a6920e5997c20f2b))
+
 ## [1.2.1](https://github.com/MarcosOps/personal-finance-frontend-core-ui/compare/v1.2.0...v1.2.1) (2026-01-30)
 
 

package/README.md

@@ -75,6 +75,34 @@ showErrorSnackBar(context, 'Something went wrong');
 
 ---
 
+## Loading / Empty / Error / Success (Fase 3)
+
+Para evitar telas “silenciosas” e condicionais repetidos em cada screen (`if (isLoading) ... else if (error) ...`), use o widget centralizado:
+
+- `lib/widgets/app_async_state_view.dart`
+
+Ele padroniza os estados:
+
+- **loading**: `CircularProgressIndicator`
+- **error**: mensagem + botão “Try again” (opcional)
+- **empty**: mensagem + ação (opcional)
+- **success**: renderiza o `child`
+
+Exemplo:
+
+```dart
+return AppAsyncStateView(
+  isLoading: viewModel.isLoading,
+  errorMessage: viewModel.errorMessage,
+  isEmpty: viewModel.items.isEmpty,
+  emptyMessage: 'No items found.',
+  onRetry: viewModel.fetch,
+  child: ListView(...),
+);
+```
+
+---
+
 ## Como Usar (Instalação como Dependência)
 
 Este pacote é uma dependência local para a aplicação principal (`personal-finance-frontend`) e outras features packages do frontend.

package/lib/personal_finance_frontend_core_ui.dart

@@ -1,4 +1,5 @@
 export 'widgets/app_widgets.dart';
+export 'widgets/app_async_state_view.dart';
 export 'theme/app_theme.dart';
 export 'theme/app_colors.dart';
 export 'theme/app_spacing.dart';

package/lib/widgets/app_async_state_view.dart

@@ -0,0 +1,147 @@
+import 'package:flutter/material.dart';
+
+/// A centralized widget to standardize async UI states.
+///
+/// Goal: avoid duplicated `if (isLoading) ... else if (error) ...` blocks
+/// across screens and keep messaging consistent.
+///
+/// Supported states:
+/// - loading: shows a centered progress indicator
+/// - error: shows a message + optional retry button
+/// - empty: shows a message + optional action
+/// - success: renders the provided [child]
+///
+/// Usage:
+/// ```dart
+/// return AppAsyncStateView(
+///   isLoading: viewModel.isLoading,
+///   errorMessage: viewModel.errorMessage,
+///   isEmpty: viewModel.items.isEmpty,
+///   emptyMessage: 'No items found.',
+///   onRetry: viewModel.fetch,
+///   child: ListView(...),
+/// );
+/// ```
+class AppAsyncStateView extends StatelessWidget {
+  final bool isLoading;
+
+  /// Any non-empty string will be treated as an error state.
+  final String? errorMessage;
+
+  /// The screen decides what "empty" means (list empty, object null, etc.).
+  final bool isEmpty;
+  final String emptyMessage;
+
+  /// Optional retry action, commonly used for network errors.
+  final VoidCallback? onRetry;
+
+  /// Optional action shown in the empty state.
+  final String? emptyActionLabel;
+  final VoidCallback? onEmptyAction;
+
+  /// The content when success.
+  final Widget child;
+
+  /// You can override the default loading indicator.
+  final Widget? loadingWidget;
+
+  const AppAsyncStateView({
+    super.key,
+    required this.isLoading,
+    required this.child,
+    this.errorMessage,
+    this.isEmpty = false,
+    this.emptyMessage = 'No data found.',
+    this.onRetry,
+    this.emptyActionLabel,
+    this.onEmptyAction,
+    this.loadingWidget,
+  });
+
+  bool get _hasError => (errorMessage ?? '').trim().isNotEmpty;
+
+  @override
+  Widget build(BuildContext context) {
+    if (isLoading) {
+      return loadingWidget ?? const Center(child: CircularProgressIndicator());
+    }
+
+    if (_hasError) {
+      return _CenteredMessage(
+        title: 'Something went wrong',
+        message: errorMessage!.trim(),
+        icon: Icons.error_outline,
+        actionLabel: onRetry == null ? null : 'Try again',
+        onAction: onRetry,
+      );
+    }
+
+    if (isEmpty) {
+      return _CenteredMessage(
+        title: 'Nothing here yet',
+        message: emptyMessage,
+        icon: Icons.inbox_outlined,
+        actionLabel: emptyActionLabel,
+        onAction: onEmptyAction,
+      );
+    }
+
+    return child;
+  }
+}
+
+class _CenteredMessage extends StatelessWidget {
+  final String title;
+  final String message;
+  final IconData icon;
+  final String? actionLabel;
+  final VoidCallback? onAction;
+
+  const _CenteredMessage({
+    required this.title,
+    required this.message,
+    required this.icon,
+    this.actionLabel,
+    this.onAction,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return Center(
+      child: Padding(
+        padding: const EdgeInsets.all(24.0),
+        child: ConstrainedBox(
+          constraints: const BoxConstraints(maxWidth: 480),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Icon(icon, size: 44, color: theme.colorScheme.onSurfaceVariant),
+              const SizedBox(height: 12),
+              Text(
+                title,
+                textAlign: TextAlign.center,
+                style: theme.textTheme.titleMedium,
+              ),
+              const SizedBox(height: 8),
+              Text(
+                message,
+                textAlign: TextAlign.center,
+                style: theme.textTheme.bodyMedium?.copyWith(
+                  color: theme.colorScheme.onSurfaceVariant,
+                ),
+              ),
+              if (actionLabel != null && onAction != null) ...[
+                const SizedBox(height: 16),
+                ElevatedButton(
+                  onPressed: onAction,
+                  child: Text(actionLabel!),
+                ),
+              ],
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@marcos_feitoza/personal-finance-frontend-core-ui",
-    "version": "1.2.1",
+    "version": "1.2.2",
     "publishConfig": {
         "access": "public"
     },