Reusable UI Components
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/java/io/github/mojri/hesabyar/ui/components/BalanceCard.kt
- app/src/main/java/io/github/mojri/hesabyar/ui/components/AmountQuickFillButtons.kt
- app/src/main/java/io/github/mojri/hesabyar/ui/components/HesabyarInputField.kt
- app/src/main/java/io/github/mojri/hesabyar/ui/screens/CategoryManagementScreen.kt
- app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt
- app/src/main/java/io/github/mojri/hesabyar/ui/screens/AnalyticsScreen.kt
The Hesabyar project utilizes a modular UI architecture built with Jetpack Compose and Material 3. The "Reusable UI Components" are centralized within the ui/components package and shared across various functional screens such as the Dashboard, Analytics, and Smart Assistant. These components are designed to provide a consistent visual identity, specifically optimized for Persian-first user experiences through Right-to-Left (RTL) support and custom design tokens.
These components encapsulate complex logic for financial data visualization, input validation, and layout structures. By utilizing standardized components like HesabyarCard, HesabyarInputField, and specialized financial widgets, the application maintains a uniform design language while reducing code duplication across feature-specific modules.
Sources: README.md:143-150, AGENTS.md:73-78
Core Visual Containers
HesabyarCard
The HesabyarCard serves as the primary container for grouping related information across the application. It extends the Material 3 Card component but integrates custom design tokens for shapes and spacing. It is used extensively in the Analytics and Smart Assistant screens to present data segments like "Monthly Trend" or "Parsed Results."
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/AnalyticsScreen.kt:137-140, app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:544-549
BalanceCard
The BalanceCard is a specialized dashboard component designed to provide a high-level overview of the user's financial status. It utilizes a gradient background (PurpleAccent) and displays formatted currency values using the CurrencyFormatter.
The diagram shows how the BalanceCard interacts with the CurrencyFormatter and design system to render financial overview data.
Sources: app/src/test/java/io/github/mojri/hesabyar/ui/BalanceCardLogicTest.kt:22-53
Input and Form Components
HesabyarInputField
A customized text input field that standardizes the appearance of OutlinedTextField. It supports specialized configurations for financial inputs, such as single-line constraints and custom shapes defined in ShapeTokens.
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/CategoryManagementScreen.kt:313-319, app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:174-181
AmountQuickFillButtons
This component provides a row of shortcut buttons for rapid currency entry. It interacts with TextFieldValue to update input amounts by fixed increments, significantly improving the speed of transaction registration.
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:660-663
| Button Feature | Description | Reference File |
|---|---|---|
| Incremental Fill | Adds preset values to current amount | AmountQuickFillButtons.kt |
| TextField Integration | Bi-directional binding with TextFieldValue | SmartAssistantScreen.kt |
| UI Localization | Buttons labeled for Toman/Rial context | SmartAssistantScreen.kt |
Specialized Financial Visualization
Analytics Components
The project includes a suite of reusable visualization components for financial analysis. These components are located within AnalyticsScreen.kt but act as standalone modular blocks.
- DonutChart: Visualizes expense distribution by category using
Canvasdrawing andStrokeCap.Roundfor modern aesthetics. - BarChart: Displays monthly trends for income and expenses.
- CombinedLineChartCard: A complex component that overlays income and expense lines on a single temporal axis for comparative analysis.
The diagram represents the flow of analytics data into specific visualization components that utilize the native drawing canvas.
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/AnalyticsScreen.kt:320-350, app/src/main/java/io/github/mojri/hesabyar/ui/screens/AnalyticsScreen.kt:355-390
Category Components
The system provides a standardized way to display categories via CategoryItem and CategoryChip (or HesabyarChip). These components handle the mapping of string-based icon keys (e.g., "Restaurant", "Savings") to Material ImageVector objects and associated colors.
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/CategoryManagementScreen.kt:31-62, app/src/main/java/io/github/mojri/hesabyar/ui/screens/CategoryManagementScreen.kt:252-265
Reusable Functional Widgets
SectionHeader
A utility component used to provide labeled dividers between lists of items, such as separating "Default Categories" from "Custom Categories."
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/CategoryManagementScreen.kt:127-130
HesabyarButton
A standardized button component that supports multiple variants (Filled, Outlined, Text) and custom colors (e.g., FinancialColors.IncomeGreen for confirmation or MaterialTheme.colorScheme.error for deletion).
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/CategoryManagementScreen.kt:225-235, app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:472-480
Implementation Summary
The reusable UI components in Hesabyar prioritize developer efficiency and user consistency. By abstracting complex UI logic—such as the DonutChart for analytics or ParsedResultCard for AI confirmations—the project ensures that financial data is presented accurately and interactively. These components rely heavily on a centralized design system (Dimens, ShapeTokens, SpacingTokens) to maintain the application's Material 3 aesthetic.
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/AnalyticsScreen.kt:414-434, app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:534-540