Component Library
Relevant source files
The following files were used as context for generating this wiki page:The BMSview component library is a collection of reusable and specialized React components that form the user interface of the application. Built with TypeScript and styled with Tailwind CSS, the library emphasizes functional components with hooks. It is organized to support both the main public-facing application and the distinct admin dashboard, with a clear separation between general UI elements and complex, data-driven modules. For more information on how these components manage data, see the State Management Guide.
The components are located in the components/ directory, with subdirectories like admin/ and icons/ for better organization. This structure promotes code reuse, maintainability, and a consistent user experience across the application.
Sources: CONTRIBUTING.md:113-122, GEMINI.md:21
Core Principles and Structure
The component library adheres to specific standards to ensure consistency and quality.
- Technology Stack: React, TypeScript, and Tailwind CSS.
- Component Style: Functional components with hooks are the standard.
- File Naming: Component files use PascalCase (e.g.,
EditSystemModal.tsx) and the.tsxextension. - Directory Structure: Components are organized within the
BMSview/components/directory. Admin-specific components are further nested incomponents/admin/.
Sources: CONTRIBUTING.md:99-103, CONTRIBUTING.md:114
This diagram illustrates the high-level organization of the component library.
Sources: CONTRIBUTING.md:113-122
General-Purpose Components
These components are designed for reuse across different parts of the application, providing fundamental UI functionality.
Icons
The project uses a set of SVG-based React components for icons, located in components/icons/. Each icon is a separate .tsx file, which allows for easy import and usage within other components. This approach ensures that icons are treated as first-class components and can be styled and sized consistently.
Examples of available icons include:
AlertIconCheckCircleIconChevronDownIconErrorIconInfoIconSpinnerIcon
Sources: components/icons/
PaginationControls
This component provides UI controls for navigating paginated data tables, commonly used in the admin dashboard. It displays page information and buttons for moving to the first, previous, next, and last pages.
| Prop | Type | Description |
|---|---|---|
currentPage | number | The currently active page number. |
totalPages | number | The total number of available pages. |
onPageChange | (page: number) => void | Callback function triggered when a page navigation button is clicked. |
itemsPerPage | number | The number of items displayed per page. |
totalItems | number | The total number of items across all pages. |
Sources: components/admin/PaginationControls.tsx
The following diagram shows the properties and methods of the PaginationControls component.
Modal Components
Modals are a key part of the application's UI for handling focused tasks like editing data or displaying detailed information without navigating away from the current view.
EditSystemModal
This modal provides a form for creating or editing a BMS system's details. It is displayed when a user needs to input or update system information, such as name, chemistry, voltage, and capacity. The component manages its own form state locally using useState and communicates changes back to its parent via a callback.
Key Features:
- Pre-populates form fields with data from the
systemToEditprop. - Handles user input and updates local state on every change.
- Performs basic validation before submission.
- Calls the
onSaveprop with the updated system data when the user saves changes.
The data flow for saving a system is shown below.
Sources: components/EditSystemModal.tsx
DiagnosticsModal
The DiagnosticsModal is a sophisticated component used in the admin dashboard to display the results of system diagnostic tests. It is designed to render complex, nested test structures and provide clear visual feedback on the status of each test.
Key Features:
- Nested Display: Renders a hierarchical view of test results, including stages, steps, and individual checks.
- Collapsible Sections: Allows users to expand or collapse detailed information for each test, keeping the UI clean.
- Comprehensive Status Indicators: Uses distinct icons and colors to represent different outcomes.
The modal uses a recursive rendering function, renderTestResult, to handle the nested data structure of the diagnostic results.
The following table details the status indicators used within the modal.
| Status | Icon | Color | Meaning |
|---|---|---|---|
success | ✔ | Green | The test or step completed successfully. |
partial | ◐ | Yellow | The test completed with some non-critical issues. |
warning | ⚠ | Yellow | The test or step produced a warning. |
error / failed | ✖ | Red | The test or step failed. |
running | ↻ | Blue | The test is currently in progress. |
Sources: ADMIN_DIAGNOSTICS_COMPLETION.md:31-41, components/DiagnosticsModal.tsx
This flowchart shows the logic for rendering a single test result item in the DiagnosticsModal.
Admin & Analytics Components
The admin dashboard contains specialized components for data visualization and management. These are typically more complex and tightly coupled with the application's state and services.
TrendingOverview
The TrendingOverview component is a dashboard widget that displays key trending metrics for a selected BMS system. It provides a high-level summary of system performance and health.
Metrics Displayed:
| Metric | Description | Health Indicator Logic |
|---|---|---|
| Avg Charge Rate | The mean charging current from hourly analytics, displayed in Amperes (A). | N/A (informational) |
| Avg Load Current | The mean discharge current from hourly analytics, displayed in Amperes (A). | N/A (informational) |
| Charge/Discharge Ratio | The balance between charge and discharge. | Green (≥1.0): Surplus Yellow (0.8-1.0): Balanced Red (<0.8): Deficit |
| Total Alerts | A count of all historical alerts, with a breakdown of unique alert types. | Green (0) Yellow (<10) Red (≥10) |
The component also features quick-toggle buttons for changing the analysis time range (e.g., "Last 24h", "7 Days") and uses a responsive grid layout to adapt to different screen sizes.
Sources: HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md:104-133
Conclusion
The BMSview component library is a well-structured and robust collection of UI elements that effectively serves both the public and administrative sections of the application. Its adherence to modern React patterns, use of TypeScript for type safety, and clear separation between general-purpose and specialized components make it a maintainable and scalable foundation for the application's frontend. The distinction between simple, reusable elements like icons and complex, data-driven modules like DiagnosticsModal and TrendingOverview highlights the library's flexibility in handling diverse UI requirements.