Dashboard & UI Framework

The dashboard-upgrade branch adds a complete home-tab dashboard built on a modern component system, plus FlatLaf (Flat Look and Feel) for a cleaner, flatter visual appearance across the whole application.

Dashboard Architecture

The dashboard lives in two packages with 49 classes:

com.storeharmony.desktop.dashpack/ — the new dashboard rewrite
com.storeharmony.desktop.dashboard/ — screens for login, cloud, welcome, system check

Integration Contract — `DashboardHost`

The dashboard plugs into any StoreHarmony version (current or older) through a single interface:

DashboardHostPanel panel = new DashboardHostPanel(myHost);
parentTabbedPane.addTab("Dashboard", panel);

The DashboardHost interface provides the integration seam — store identity, license info, cloud URLs, and adverts. Database queries don’t go through this interface; they extend DashOp which inherits from StoreHarmony’s AbstractReadDataOperation. Every widget is null-tolerant for graceful degradation.

Dashboard Zones

Zone A — KPI Strip

Responsive grid of KpiTile cards. Switches between 1, 2, and 3-column layouts based on available width. Tiles show: Sales Today (₦), Orders Today, Stock Value, Low Stock Count, Pending Supplies. Values load asynchronously via SwingWorker so the UI never blocks.

Zone B — Charts

Three JFreeChart panels in a 2+1 layout:
• Sales Trend — green line chart with 7D/30D/90D ToggleChip selector
• Top Products — horizontal bar chart of best sellers
• Stock Movement — dual-series (received vs sold) bar chart

Zone C — Side Deck

Right-hand column with: Store Info card (name, address, dataExId), Quick Links (cloud dashboard, settings), Advert Banner rotator (cloud-fetched images), Mobile API Server status, Info Updates feed.

Refresh & Lifecycle

Auto-refresh every 5 minutes via Swing Timer. Manual refresh on tab focus. All data binders are null-safe — a single broken query won’t blank the whole dashboard. DashboardHostPanel.refreshData() re-runs all binders; dispose() stops the timer.

Component Library

The dashboard introduces a reusable component library under dashpack.components:

Component	Package	Purpose
HarmonyCard	`components.cards`	Base card with rounded corners, outline, elevation shadow, padding, and constrained layout
SoftShadowPanel	`components.cards`	Drop-shadow panel used under elevated cards and popups
HarmonyButtons	`components.buttons`	Primary/secondary/ghost/danger FlatLaf-styled buttons with consistent padding
RoundedButton	`components.buttons`	Fully rounded pill-style button for accent actions
ToggleChipGroup	`components.buttons`	Segmented button group (e.g. 7D / 30D / 90D) with single-select
BrandmarkHeader	`dashboard.components.display`	Login/branding header with logo and tagline
ConnectionStatusStrip	`components.display`	Coloured pill showing online/offline/reconnecting state
IconBadge	`components.display`	Coloured icon circle/badge for KPI tile headers
StatusPill	`components.display`	Small coloured label (active/inactive/warning)
TrendArrowIcon	`components.display`	Up/down arrow with delta percentage for KPI trends
RoundedAvatar	`components.display`	Circular user avatar placeholder
ChevronIcon	`components.display`	Expand/collapse chevron indicator
KeyValueInfoGrid	`dashboard.components.display`	Two-column label:value layout for info panels
LabeledInputRow	`components.inputs`	Form row with label + input alignment
InlineFeedbackBanner	`dashboard.components.display`	Animated notification banner (success/warning/error)
CardStateSwitcher	`components.layout`	Card layout that fades between loading, content, and error states
WrapLayout	`components.layout`	FlowLayout variant that wraps at container width
WorkspaceHost	`components.workspace`	Full-window workspace container with toolbar zones
HarmonyTints	`components.theme`	Colour palette enum (GREEN, BLUE, ORANGE, RED, GRAY) with accent/background/light shades

New Dependencies

Library	Version	Purpose
FlatLaf	3.7.1	Modern flat Look and Feel for Swing — replaces the older custom LAF
JFreeChart	1.5.6	Professional charting library for dashboard charts

Application Screens

The dashboard.screens package handles the pre-dashboard experience:

LocalLoginPanel — PIN/password login to the local instance
CloudLoginCard — Cloud account login panel
CloudLandingPanel — Cloud-connection landing screen
WelcomeLandingPanel — First-run welcome with setup prompts
SystemCheckPanel — Pre-flight check (database, cloud reachability)
LocationListCard — Multi-store / multi-branch selector
CurrentVersionDashboardHost — Production DashboardHost implementation
QuickActionDeckBinder — Binds the quick-action grid (shortcut buttons)
ScreenState — State machine driving screen transitions
HarmonyScreens — Screen registry and transition manager

FlatLaf UI Rules

The FlatLaf LAF is applied at startup and affects all Swing chrome:

Flat, borderless buttons, text fields, and scrollbars
Consistent 8px / 16px spacing grid
System font rendering (no more bold-heavy WinLAF look)
Custom accent colours via HarmonyTints palette
Rounded card corners via HarmonyCard with configurable radius, outline, and elevation

Design pattern: The dashboard uses an interface + SwingWorker pattern throughout — all data loading is async on background threads, callbacks update UI components on the EDT. This keeps the interface responsive even when H2 queries take seconds.