@marcos_feitoza/personal-finance-frontend-core-ui 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [1.2.0](https://github.com/MarcosOps/personal-finance-frontend-core-ui/compare/v1.1.0...v1.2.0) (2026-01-29)
+
+
+### Bug Fixes
+
+* new SnackBar ([7c519e0](https://github.com/MarcosOps/personal-finance-frontend-core-ui/commit/7c519e06b53884863a32170015080860ddf836be))
+* update SnackBar ([b0c3b71](https://github.com/MarcosOps/personal-finance-frontend-core-ui/commit/b0c3b71efa0a7dd855fed3561c0c40bca33b23ec))
+
+
+### Features
+
+* new AppTheme process ([7557114](https://github.com/MarcosOps/personal-finance-frontend-core-ui/commit/755711424e37a65f6891748c9d60940e1bbf2e80))
+
+# [1.1.0](https://github.com/MarcosOps/personal-finance-frontend-core-ui/compare/v1.0.2...v1.1.0) (2025-11-28)
+
+
+### Features
+
+* add confirmation dialog for deletion operations ([029b159](https://github.com/MarcosOps/personal-finance-frontend-core-ui/commit/029b159d370e2c68f71afeefb320dea7182b58bb))
+* update readme.me ([7b1ac44](https://github.com/MarcosOps/personal-finance-frontend-core-ui/commit/7b1ac445a2b3183283779f710e46a0fed7238657))
+
 ## [1.0.2](https://github.com/MarcosOps/personal-finance-frontend-core-ui/compare/v1.0.1...v1.0.2) (2025-11-26)
 
 

package/README.md

@@ -1,16 +1,94 @@
-# personal_finance_frontend_core_ui
+# Core UI - Frontend (Flutter)
 
-A new Flutter project.
+Este pacote contém os widgets e componentes de interface do usuário (UI) reutilizáveis para a aplicação Personal Finance Frontend.
 
-## Getting Started
+## Propósito
 
-This project is a starting point for a Flutter application.
+O objetivo deste pacote é centralizar e padronizar a aparência e o comportamento dos elementos de UI em todo o aplicativo. Ele fornece uma biblioteca de componentes que podem ser utilizados por outros pacotes de feature, garantindo consistência visual e reduzindo a duplicação de código.
 
-A few resources to get you started if this is your first Flutter project:
+## Conteúdo Principal
 
-- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+- **`widgets/`**: Contém diversos widgets reutilizáveis, como `AppFormCard`, `AppDropdown`, `TradeForm`, `DividendLogForm`, `CryptoTradeForm`, `RrspContributionForm`, etc.
+- **`utils/app_dialogs.dart`**: Funções utilitárias para exibir diálogos padronizados (ex: confirmação de exclusão).
+- **`utils/app_logger.dart`**: Implementação de um logger condicional que exibe logs apenas em modo de depuração.
+- **`utils/currency_input_formatter.dart`**: Formatter para campos de entrada de moeda.
+- **`utils/theme_notifier.dart`**: Provedor para gerenciar o tema da aplicação (claro/escuro).
 
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+## Tema (Fase 1 — centralização)
+
+Para evitar que cada tela/feature package defina seus próprios estilos (cores, espaçamentos, bordas), o **tema global** foi centralizado no core-ui.
+
+Arquivos:
+
+- `lib/theme/app_theme.dart`
+  - Define `AppTheme.light` e `AppTheme.dark`.
+  - **O que controla:**
+    - `ColorScheme` (paleta de cores principal)
+    - `AppBarTheme` (cor do topo e cor do texto/ícones)
+    - `ElevatedButtonTheme` / `OutlinedButtonTheme` (tamanho e bordas padrão dos botões)
+    - `InputDecorationTheme` (bordas/padding padrão de `TextFormField`)
+- `lib/theme/app_colors.dart`
+  - Tokens semânticos (ex.: `success`, `error`, `warning`) e `seed`.
+  - **O que controla:**
+    - cores usadas em feedback (SnackBars, highlights de sucesso/erro)
+    - seed do tema (mudança global do “tom” do app)
+- `lib/theme/app_spacing.dart`
+  - Tokens de espaçamento (`xs/sm/md/lg/xl/...`).
+  - **O que controla:**
+    - valores de padding/margin padronizados
+
+Uso no app shell (`personal-finance-frontend/lib/main.dart`):
+
+```dart
+import 'package:personal_finance_frontend_core_ui/theme/app_theme.dart';
+
+MaterialApp(
+  theme: AppTheme.light,
+  darkTheme: AppTheme.dark,
+)
+```
+
+Regras recomendadas:
+
+- Em telas/features: preferir `Theme.of(context).colorScheme`.
+- Para cores semânticas (ex.: erro/sucesso), usar `AppColors`.
+- Para componentes, preferir `widgets/app_widgets.dart`.
+
+## SnackBars padronizados (Fase 2)
+
+Para evitar SnackBars com cores/textos inconsistentes, use os helpers:
+
+- `showErrorSnackBar(context, message)`
+- `showSuccessSnackBar(context, message)`
+- `showInfoSnackBar(context, message)`
+
+Arquivo:
+- `lib/utils/app_snackbars.dart`
+
+Exemplo:
+
+```dart
+import 'package:personal_finance_frontend_core_ui/utils/app_snackbars.dart';
+
+showErrorSnackBar(context, 'Something went wrong');
+```
+
+---
+
+## 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.
+
+No `pubspec.yaml` do pacote consumidor, adicione a seguinte linha em `dependencies`:
+
+```yaml
+personal_finance_frontend_core_ui:
+  path: ../personal-finance-frontend-core-ui
+```
+
+## Features
+
+-   **Widgets Reutilizáveis**: Componentes de UI com design e comportamento padronizados.
+-   **Diálogos Centralizados**: Funções para exibir diálogos consistentes em todo o aplicativo.
+-   **Logging Condicional**: Um logger que ajuda a manter o console limpo em produção, exibindo mensagens apenas em desenvolvimento.
+-   **Ferramentas de Formatação**: Utilitários para formatar entradas de usuário (ex: valores monetários).

package/lib/personal_finance_frontend_core_ui.dart

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

package/lib/theme/app_colors.dart

@@ -0,0 +1,37 @@
+import 'package:flutter/material.dart';
+
+/// App-wide color tokens.
+///
+/// Why this file exists:
+/// - In a modular Flutter app (multiple packages/features), colors tend to be
+///   duplicated across screens and drift over time.
+/// - By keeping "semantic" colors here (success/error/warning + seed), we can
+///   change the look globally without hunting through many screens.
+///
+/// How to use:
+/// - Prefer `Theme.of(context).colorScheme.*` for most UI.
+/// - Use these tokens when the color is semantic (success/error), not arbitrary.
+class AppColors {
+  AppColors._();
+
+  /// Seed used to generate the Material `ColorScheme`.
+  ///
+  /// Changing this will change the app's primary/secondary tones.
+  static const Color seed = Colors.blueGrey;
+
+  /// Background colors (used as overrides in ThemeData).
+  ///
+  /// Note: in the current setup, the light theme relies on Material defaults
+  /// (we don't override scaffoldBackgroundColor). If you want to set a custom
+  /// background, add a token here and wire it in `AppTheme.light`.
+  static const Color darkScaffoldBackground = Color(0xFF212121); // ~ Colors.grey[900]
+  static const Color darkCardBackground = Color(0xFF303030); // ~ Colors.grey[850]
+  static const Color darkTextFieldFill = Color(0xFF424242); // ~ Colors.grey[800]
+
+  /// Semantic colors.
+  ///
+  /// These should be used for meaning (success/error) instead of random `Colors.*`.
+  static const Color success = Colors.green;
+  static const Color error = Colors.red;
+  static const Color warning = Colors.orange;
+}

package/lib/theme/app_spacing.dart

@@ -0,0 +1,34 @@
+/// App-wide spacing tokens.
+///
+/// Why this file exists:
+/// - Prevents each screen from inventing its own paddings/margins.
+/// - Makes global layout adjustments easy.
+///
+/// Usage:
+/// ```dart
+/// Padding(
+///   padding: const EdgeInsets.all(AppSpacing.lg),
+///   child: ...,
+/// )
+/// ```
+class AppSpacing {
+  AppSpacing._();
+
+  /// 4px base spacing.
+  static const double xs = 4;
+
+  /// 8px spacing.
+  static const double sm = 8;
+
+  /// 12px spacing.
+  static const double md = 12;
+
+  /// 16px spacing.
+  static const double lg = 16;
+
+  /// 20px spacing.
+  static const double xl = 20;
+
+  /// 24px spacing.
+  static const double xxl = 24;
+}

package/lib/theme/app_theme.dart

@@ -0,0 +1,112 @@
+import 'package:flutter/material.dart';
+
+import 'app_colors.dart';
+
+/// Centralized ThemeData for the whole app.
+///
+/// Why this file exists:
+/// - The app is split into multiple Flutter packages (shell + feature packages).
+/// - If each screen defines its own colors/fonts, UI drift happens.
+/// - By centralizing ThemeData here, we keep a single source of truth.
+///
+/// How to use:
+/// - In the app shell (`personal-finance-frontend/lib/main.dart`), set:
+///   - `theme: AppTheme.light`
+///   - `darkTheme: AppTheme.dark`
+/// - Inside widgets, prefer `Theme.of(context)` and `ColorScheme`.
+class AppTheme {
+  AppTheme._();
+
+  /// Light theme.
+  ///
+  /// Key choices:
+  /// - `ColorScheme.fromSeed`: creates a consistent palette based on a single seed.
+  /// - `useMaterial3: true`: aligns the app to modern Material components.
+  static final ThemeData light = ThemeData(
+    colorScheme: ColorScheme.fromSeed(seedColor: AppColors.seed),
+    useMaterial3: true,
+
+    // AppBar (top bar)
+    // - backgroundColor: the bar background
+    // - foregroundColor: icon/text color on top of the bar
+    appBarTheme: const AppBarTheme(
+      centerTitle: true,
+      backgroundColor: AppColors.seed,
+      foregroundColor: Colors.white,
+    ),
+
+    // Default style for elevated buttons.
+    // Affects buttons created without custom style.
+    elevatedButtonTheme: ElevatedButtonThemeData(
+      style: ElevatedButton.styleFrom(
+        minimumSize: const Size.fromHeight(50),
+        shape: RoundedRectangleBorder(
+          borderRadius: BorderRadius.circular(8),
+        ),
+      ),
+    ),
+
+    // Default style for outlined buttons.
+    outlinedButtonTheme: OutlinedButtonThemeData(
+      style: OutlinedButton.styleFrom(
+        minimumSize: const Size.fromHeight(50),
+        shape: RoundedRectangleBorder(
+          borderRadius: BorderRadius.circular(8),
+        ),
+      ),
+    ),
+
+    // Default decoration for text fields.
+    // Controls border and padding used by TextFormField/InputDecoration.
+    inputDecorationTheme: const InputDecorationTheme(
+      border: OutlineInputBorder(),
+      contentPadding: EdgeInsets.symmetric(vertical: 16.0, horizontal: 12.0),
+    ),
+  );
+
+  /// Dark theme.
+  ///
+  /// Differences from light theme:
+  /// - `brightness: Brightness.dark` for proper Material defaults
+  /// - custom scaffold/card/text field background colors
+  static final ThemeData dark = ThemeData(
+    colorScheme: ColorScheme.fromSeed(
+      seedColor: AppColors.seed,
+      brightness: Brightness.dark,
+    ),
+    useMaterial3: true,
+    appBarTheme: const AppBarTheme(
+      centerTitle: true,
+      backgroundColor: Colors.black,
+      foregroundColor: Colors.white,
+    ),
+    elevatedButtonTheme: ElevatedButtonThemeData(
+      style: ElevatedButton.styleFrom(
+        minimumSize: const Size.fromHeight(50),
+        shape: RoundedRectangleBorder(
+          borderRadius: BorderRadius.circular(8),
+        ),
+        backgroundColor: Colors.blueGrey,
+        foregroundColor: Colors.white,
+      ),
+    ),
+    outlinedButtonTheme: OutlinedButtonThemeData(
+      style: OutlinedButton.styleFrom(
+        minimumSize: const Size.fromHeight(50),
+        shape: RoundedRectangleBorder(
+          borderRadius: BorderRadius.circular(8),
+        ),
+        backgroundColor: Colors.blueGrey,
+        foregroundColor: Colors.white,
+      ),
+    ),
+    inputDecorationTheme: const InputDecorationTheme(
+      border: OutlineInputBorder(),
+      contentPadding: EdgeInsets.symmetric(vertical: 16.0, horizontal: 12.0),
+      fillColor: AppColors.darkTextFieldFill,
+      filled: true,
+    ),
+    scaffoldBackgroundColor: AppColors.darkScaffoldBackground,
+    cardColor: AppColors.darkCardBackground,
+  );
+}

package/lib/utils/app_dialogs.dart

@@ -0,0 +1,30 @@
+import 'package:flutter/material.dart';
+
+class AppDialogs {
+  /// Displays a confirmation dialog for deletion operations.
+  ///
+  /// Returns `true` if the user confirms deletion, `false` otherwise.
+  static Future<bool?> showDeleteConfirmationDialog(
+      BuildContext context, String itemName) async {
+    return await showDialog<bool>(
+      context: context,
+      builder: (BuildContext context) {
+        return AlertDialog(
+          title: const Text('Confirmar Exclusão'),
+          content: Text(
+              'Você tem certeza que deseja excluir "$itemName"? Esta ação não pode ser desfeita.'),
+          actions: <Widget>[
+            TextButton(
+              onPressed: () => Navigator.of(context).pop(false),
+              child: const Text('Cancelar'),
+            ),
+            TextButton(
+              onPressed: () => Navigator.of(context).pop(true),
+              child: const Text('Excluir'),
+            ),
+          ],
+        );
+      },
+    );
+  }
+}

package/lib/utils/app_snackbars.dart

@@ -0,0 +1,49 @@
+import 'package:flutter/material.dart';
+
+import '../theme/app_colors.dart';
+
+/// Standard SnackBars for the whole app.
+///
+/// Why this exists:
+/// - Many screens create SnackBars with hardcoded colors.
+/// - Over time, feedback UX becomes inconsistent.
+/// - Centralizing here makes it easy to change styling globally.
+///
+/// Usage:
+/// ```dart
+/// showErrorSnackBar(context, 'Login failed');
+/// showSuccessSnackBar(context, 'Saved!');
+/// ```
+void showErrorSnackBar(BuildContext context, String message) {
+  ScaffoldMessenger.of(context).showSnackBar(
+    SnackBar(
+      content: Text(message),
+      backgroundColor: AppColors.error,
+    ),
+  );
+}
+
+void showSuccessSnackBar(BuildContext context, String message) {
+  ScaffoldMessenger.of(context).showSnackBar(
+    SnackBar(
+      content: Text(message),
+      backgroundColor: AppColors.success,
+    ),
+  );
+}
+
+void showInfoSnackBar(BuildContext context, String message) {
+  // Info uses the current theme's surface for readability.
+  final theme = Theme.of(context);
+  ScaffoldMessenger.of(context).showSnackBar(
+    SnackBar(
+      // SnackBar doesn't support a `textStyle` parameter in some Flutter versions,
+      // so we style the Text directly.
+      content: Text(
+        message,
+        style: TextStyle(color: theme.colorScheme.onInverseSurface),
+      ),
+      backgroundColor: theme.colorScheme.inverseSurface,
+    ),
+  );
+}

package/lib/widgets/crypto_trade_form.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:intl/intl.dart';
 import 'package:personal_finance_frontend_core_services/services/crypto_service.dart';
+import 'package:personal_finance_frontend_core_ui/utils/app_snackbars.dart';
 import 'package:personal_finance_frontend_core_services/services/transaction_service.dart';
 import 'package:personal_finance_frontend_core_ui/utils/currency_input_formatter.dart';
 import 'package:personal_finance_frontend_core_ui/widgets/app_widgets.dart';
@@ -156,9 +157,7 @@ class _CryptoTradeFormState extends State<CryptoTradeForm> {
       final validationResult = await _cryptoService.validateCryptoSymbol(symbol);
       if (validationResult == null) {
         if (mounted) {
-          ScaffoldMessenger.of(context).showSnackBar(
-            SnackBar(content: Text('Invalid crypto ID: "$symbol"'), backgroundColor: Colors.red),
-          );
+          showErrorSnackBar(context, 'Invalid crypto ID: "$symbol"');
         }
         setState(() => _isSubmitting = false);
         return;
@@ -176,9 +175,7 @@ class _CryptoTradeFormState extends State<CryptoTradeForm> {
     } else { // Sell
       if (_livePriceForSell == null) {
         if (mounted) {
-          ScaffoldMessenger.of(context).showSnackBar(
-            const SnackBar(content: Text('Could not get live price. Please try again.'), backgroundColor: Colors.red),
-          );
+          showErrorSnackBar(context, 'Could not get live price. Please try again.');
         }
         setState(() => _isSubmitting = false);
         return;
@@ -201,13 +198,9 @@ class _CryptoTradeFormState extends State<CryptoTradeForm> {
 
     if (mounted) {
       if (errorMessage != null) {
-        ScaffoldMessenger.of(context).showSnackBar(
-          SnackBar(content: Text(errorMessage), backgroundColor: Colors.red),
-        );
+        showErrorSnackBar(context, errorMessage);
       } else {
-        ScaffoldMessenger.of(context).showSnackBar(
-          SnackBar(content: Text('Trade created successfully!'), backgroundColor: Colors.green),
-        );
+          showSuccessSnackBar(context, 'Trade created successfully!');
         widget.onTradeCreated(tradeData);
         _formKey.currentState!.reset();
         _symbolController.clear();

package/lib/widgets/dividend_log_form.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:intl/intl.dart';
 import 'package:personal_finance_frontend_core_services/services/transaction_service.dart';
+import 'package:personal_finance_frontend_core_ui/utils/app_snackbars.dart';
 import 'package:personal_finance_frontend_core_ui/utils/currency_input_formatter.dart';
 import 'package:personal_finance_frontend_core_ui/widgets/app_widgets.dart';
 
@@ -75,13 +76,9 @@ class _DividendLogFormState extends State<DividendLogForm> {
 
       if (mounted) {
         if (errorMessage != null) {
-          ScaffoldMessenger.of(context).showSnackBar(
-            SnackBar(content: Text(errorMessage), backgroundColor: Colors.red),
-          );
+          showErrorSnackBar(context, errorMessage);
         } else {
-          ScaffoldMessenger.of(context).showSnackBar(
-            const SnackBar(content: Text('Dividend logged successfully!'), backgroundColor: Colors.green),
-          );
+          showSuccessSnackBar(context, 'Dividend logged successfully!');
           widget.onDividendLogged();
           _formKey.currentState!.reset();
           _amountController.clear();

package/lib/widgets/historical_data_table.dart

@@ -0,0 +1,36 @@
+import 'package:flutter/material.dart';
+
+/// A reusable widget to display historical data in a standardized DataTable.
+class HistoricalDataTable extends StatelessWidget {
+  final List<DataColumn> columns;
+  final List<DataRow> rows;
+  final String noDataFoundMessage;
+
+  const HistoricalDataTable({
+    Key? key,
+    required this.columns,
+    required this.rows,
+    this.noDataFoundMessage = 'No data found.',
+  }) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    if (rows.isEmpty) {
+      return Center(
+        child: Padding(
+          padding: const EdgeInsets.all(16.0),
+          child: Text(noDataFoundMessage),
+        ),
+      );
+    }
+
+    return SingleChildScrollView(
+      scrollDirection: Axis.horizontal,
+      child: DataTable(
+        columnSpacing: 24.0,
+        columns: columns,
+        rows: rows,
+      ),
+    );
+  }
+}

package/lib/widgets/rrsp_contribution_form.dart

@@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:intl/intl.dart';
 import 'package:personal_finance_frontend_core_services/services/transaction_service.dart';
+import 'package:personal_finance_frontend_core_ui/utils/app_snackbars.dart';
 import 'package:personal_finance_frontend_core_ui/utils/currency_input_formatter.dart';
 import 'package:personal_finance_frontend_core_ui/widgets/app_widgets.dart';
 
@@ -77,13 +78,9 @@ class _RrspContributionFormState extends State<RrspContributionForm> {
 
       if (mounted) {
         if (errorMessage != null) {
-          ScaffoldMessenger.of(context).showSnackBar(
-            SnackBar(content: Text(errorMessage), backgroundColor: Colors.red),
-          );
+          showErrorSnackBar(context, errorMessage);
         } else {
-          ScaffoldMessenger.of(context).showSnackBar(
-            const SnackBar(content: Text('RRSP Contribution logged successfully!'), backgroundColor: Colors.green),
-          );
+          showSuccessSnackBar(context, 'RRSP Contribution logged successfully!');
           widget.onContributionLogged(); // Notify parent to refresh
           _formKey.currentState!.reset();
           _rrspAmountController.clear();
@@ -154,4 +151,4 @@ class _RrspContributionFormState extends State<RrspContributionForm> {
       ),
     );
   }
-}
+}

package/lib/widgets/trade_form.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:intl/intl.dart';
 import 'package:personal_finance_frontend_core_services/services/stock_service.dart';
+import 'package:personal_finance_frontend_core_ui/utils/app_snackbars.dart';
 import 'package:personal_finance_frontend_core_services/services/transaction_service.dart';
 import 'package:personal_finance_frontend_core_ui/utils/currency_input_formatter.dart';
 import 'package:personal_finance_frontend_core_ui/widgets/app_widgets.dart';
@@ -147,11 +148,7 @@ class _TradeFormState extends State<TradeForm> {
       final isValid = await _stockService.validateStockSymbol(symbol);
       if (!isValid) {
         if (mounted) {
-          ScaffoldMessenger.of(context).showSnackBar(
-            SnackBar(
-                content: Text('Invalid stock symbol: "$symbol"'),
-                backgroundColor: Colors.red),
-          );
+          showErrorSnackBar(context, 'Invalid stock symbol: "$symbol"');
         }
         setState(() => _isSubmitting = false);
         return; // Stop submission
@@ -163,11 +160,7 @@ class _TradeFormState extends State<TradeForm> {
     if (_tradeType == 'sell') {
       if (_livePriceForSell == null) {
         if (mounted) {
-          ScaffoldMessenger.of(context).showSnackBar(
-            const SnackBar(
-                content: Text('Could not get live price. Please try again.'),
-                backgroundColor: Colors.red),
-          );
+          showErrorSnackBar(context, 'Could not get live price. Please try again.');
         }
         setState(() => _isSubmitting = false);
         return;
@@ -195,15 +188,9 @@ class _TradeFormState extends State<TradeForm> {
 
     if (mounted) {
       if (errorMessage != null) {
-        ScaffoldMessenger.of(context).showSnackBar(
-          SnackBar(content: Text(errorMessage), backgroundColor: Colors.red),
-        );
+        showErrorSnackBar(context, errorMessage);
       } else {
-        ScaffoldMessenger.of(context).showSnackBar(
-          const SnackBar(
-              content: Text('Trade created successfully!'),
-              backgroundColor: Colors.green),
-        );
+        showSuccessSnackBar(context, 'Trade created successfully!');
         widget.onTradeCreated(tradeData);
         _formKey.currentState!.reset();
         _symbolController.clear();

package/package.json

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