Reports UI V2 - Developer Implementation Guide

Overview

Replace the current card-based react-grid-layout reports dashboard with a tab-based, fuel-driven reporting interface.

Key Changes:

Remove draggable cards → single canvas per tab
Fuel selector becomes primary control
Add 6 semantic tabs
Light uniform surface (no dark cards)

V1 Scope Note:

V1 is building-level reporting only.
We are deferring tenant-scoped reporting (i.e., a global "show me only Tenant X" mode) until later.

Wireframes

Global Layout

┌──────────────────────────────────────────────────────────────────────────┐
│ HEADER                                                                   │
├────────────┬─────────────────────────────────────────────────────────────┤
│            │  CONTROL PLANE (sticky)                                     │
│            │  ┌────────────────────────────────────────────────────────┐ │
│  SIDEBAR   │  │ Fuel: [Electricity ▼]                                  │ │
│            │  │ Period: [Last 12M ▼]   Compare: [None ▼]               │ │
│  Dashboard │  └────────────────────────────────────────────────────────┘ │
│  Buildings │                                                             │
│  Readings  │  TABS                                                       │
│  Recharges │  ┌────────────────────────────────────────────────────────┐ │
│  Bills     │  │ [Summary] [Trends] [Comparison] [Tenants] [SPC] [Data] │ │
│  Reports ← │  └────────────────────────────────────────────────────────┘ │
│  Users     │                                                             │
│  Activity  │  MAIN CONTENT AREA                                          │
│            │  ┌────────────────────────────────────────────────────────┐ │
│            │  │                                                        │ │
│            │  │         Tab content renders here                       │ │
│            │  │         (single canvas, no cards)                      │ │
│            │  │                                                        │ │
│            │  └────────────────────────────────────────────────────────┘ │
└────────────┴─────────────────────────────────────────────────────────────┘

Summary Tab

┌──────────────────────────────────────────────────────────────────────────┐
│ KPI STRIP (inline row, no cards)                                         │
│ ┌─────────────┬─────────────┬─────────────┬─────────────┐                │
│ │ Total kWh   │ Total £     │ Avg £/kWh   │ % Recharged │                │
│ │ 145,230     │ £14,523     │ £0.10       │ 87%         │                │
│ └─────────────┴─────────────┴─────────────┴─────────────┘                │
├──────────────────────────────────────────────────────────────────────────┤
│ PRIMARY TREND CHART                                                      │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │     ╭──╮                                                             │ │
│ │    ╱    ╲    ╭──╮                                                    │ │
│ │ ──╱      ╲──╱    ╲──────                    12-month consumption     │ │
│ │ Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec                      │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ SECONDARY CHART (Charges / Recharge % / Baseload)                        │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ ████ ███ ████ ██ ████ ███ ████ ███ ████ ███ ████ ███                 │ │
│ │ Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec                      │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘

Trends Tab

┌──────────────────────────────────────────────────────────────────────────┐
│ CONTROLS                                                                 │
│ Metric: [Consumption ▼]  Aggregation: [Monthly ▼]  [☐ Normalise per m²] │
├──────────────────────────────────────────────────────────────────────────┤
│ FULL-WIDTH TIME SERIES                                                   │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ ── Tenant A                                                          │ │
│ │ ── Tenant B    ╭──╮         ╭──╮                                     │ │
│ │ ── Tenant C   ╱    ╲   ╭──╮╱    ╲                                    │ │
│ │            ──╱      ╲─╱    ╲      ╲──                                │ │
│ │ Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec                      │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ SUPPORTING CHART (rolling average / seasonality)                         │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Rolling 3-month average: ────────────────────                        │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘

Comparison Tab

┌──────────────────────────────────────────────────────────────────────────┐
│ PERIOD SELECTORS                                                         │
│ Period A: [Jan-Dec 2025 ▼]    vs    Period B: [Jan-Dec 2024 ▼]           │
│ Mode: (●) YoY  ( ) MoM  ( ) Custom                                       │
├──────────────────────────────────────────────────────────────────────────┤
│ OVERLAID TREND CHART                                                     │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ ── 2025 (solid)                                                      │ │
│ │ -- 2024 (dashed)     ╭──╮                                            │ │
│ │                     ╱    ╲    - - - -                                │ │
│ │                 ───╱      ╲──╱                                       │ │
│ │ Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec                      │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ DELTA KPIS                                                               │
│ ┌─────────────────┬─────────────────┬─────────────────┐                  │
│ │ Δ kWh: +12,450  │ Δ £: +£1,245    │ Δ %: +8.6%      │                  │
│ │ ▲ vs last year  │ ▲ vs last year  │ ▲ vs last year  │                  │
│ └─────────────────┴─────────────────┴─────────────────┘                  │
├──────────────────────────────────────────────────────────────────────────┤
│ DELTA BARS (monthly deviation)                                           │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │      ▲         ▲                   ▲                                 │ │
│ │ ──── ████ ──── ████ ▼▼▼▼ ──── ──── ████ ▼▼▼▼ ────                    │ │
│ │      +5%       +8%  -3%            +12% -2%                          │ │
│ │ Jan  Feb  Mar  Apr  May  Jun  Jul  Aug  Sep  Oct  Nov  Dec           │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘

Tenants Tab

┌──────────────────────────────────────────────────────────────────────────┐
│ CONTROLS                                                                 │
│ Sort by: [Consumption ▼]  Metric: [kWh ▼]                                │
├──────────────────────────────────────────────────────────────────────────┤
│ RANKING TABLE                                                            │
│ ┌────────────────┬──────────┬──────────┬─────────┬───────────────────┐   │
│ │ Tenant         │ kWh      │ £        │ % Total │ Trend             │   │
│ ├────────────────┼──────────┼──────────┼─────────┼───────────────────┤   │ 
│ │ ▶ Tenant A     │ 45,230   │ £4,523   │ 31%     │ ▁▂▃▄▅▆▇█▇▆▅▄   │ 
│ │   Tenant B     │ 32,100   │ £3,210   │ 22%     │ ▁▁▂▂▃▃▄▄▅▅▆▆        │  
│ │   Tenant C     │ 28,450   │ £2,845   │ 20%     │ ▆▅▄▃▂▁▁▂▃▄▅▆   │
│ │   Tenant D     │ 21,200   │ £2,120   │ 15%     │ ▃▃▃▃▃▃▃▃▃▃▃▃│
│ │   Tenant E     │ 18,250   │ £1,825   │ 12%     │ ▁▂▃▄▅▆▇▆▅▄▃▂     │ │
│ └────────────────┴──────────┴──────────┴─────────┴───────────────────┘  │
├──────────────────────────────────────────────────────────────────────────┤
│ DRILLDOWN PANEL (expanded for Tenant A)                                  │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Tenant A - Meter Breakdown                                           │ │
│ │ ┌────────────┬─────────┬─────────┐  ╭──╮                             │ │
│ │ │ Meter      │ kWh     │ %       │ ╱    ╲    Mini trend              │ │
│ │ │ Floor 1    │ 22,000  │ 49%     │╱      ╲──                         │ │
│ │ │ Floor 2    │ 23,230  │ 51%     │                                   │ │
│ │ └────────────┴─────────┴─────────┘                                   │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘

SPC Tab (Statistical Process Control)

┌──────────────────────────────────────────────────────────────────────────┐
│ SPC CONTROLS                                                              │
│ Metric: [Consumption ▼]  Aggregation: [Daily ▼]  Baseline: [Rolling 12M ▼]│
├──────────────────────────────────────────────────────────────────────────┤
│ SPC CONTROL CHART                                                        │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ UCL (+3σ) ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─    │ │
│ │                                                                      │ │
│ │              ●                           ●  ← Out of control (red)   │ │
│ │         ○   ○ ○        ○    ○       ○   ○                            │ │
│ │ Mean ───○──○───○──○──○──○──○──○──○──○──○───○──○──○──○──○──○──○──     │ │
│ │        ○    ○    ○  ○    ○    ○  ○    ○      ○    ○                  │ │
│ │                                                                      │ │
│ │ LCL (-3σ) ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─    │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ ANOMALY LOG                                                              │
│ ┌────────────┬──────────┬───────────┬──────────┬───────────────────────┐│
│ │ Date       │ Value    │ Deviation │ Severity │ Notes                 ││
│ ├────────────┼──────────┼───────────┼──────────┼───────────────────────┤│
│ │ 2025-12-15 │ 1,450kWh │ +2.8σ     │ ● High   │ Above UCL             ││
│ │ 2025-11-03 │ 1,380kWh │ +2.1σ     │ ○ Medium │ Approaching UCL       ││
│ │ 2025-09-22 │ 890kWh   │ -2.4σ     │ ○ Medium │ Below normal          ││
│ └────────────┴──────────┴───────────┴──────────┴───────────────────────┘│
└──────────────────────────────────────────────────────────────────────────┘

Data Tab

┌──────────────────────────────────────────────────────────────────────────┐
│ EXPORT CONTROLS                                                          │
│ [📥 CSV]  [📥 Excel]                                                    │
├──────────────────────────────────────────────────────────────────────────┤
│ RAW DATA TABLE                                                           │
│ ┌────────────┬──────────┬──────────┬─────────┬────────┬────────┬──────┐ │
│ │ Timestamp  │ Meter    │ Tenant   │ kWh     │ £      │ Rate   │Source│ │
│ ├────────────┼──────────┼──────────┼─────────┼────────┼────────┼──────┤ │
│ │ 2025-12-01 │ M-001    │ Tenant A │ 1,245   │ £124.50│ £0.10  │ API  │ │
│ │ 2025-12-01 │ M-002    │ Tenant A │ 987     │ £98.70 │ £0.10  │ API  │ │
│ │ 2025-12-01 │ M-003    │ Tenant B │ 1,102   │ £110.20│ £0.10  │ API  │ │
│ │ 2025-12-01 │ M-004    │ Tenant C │ 856     │ £85.60 │ £0.10  │ API  │ │
│ │ ...        │ ...      │ ...      │ ...     │ ...    │ ...    │ ...  │ │
│ └────────────┴──────────┴──────────┴─────────┴────────┴────────┴──────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ PAGINATION                                                               │
│ Showing 1-100 of 1,245 records    [< Prev]  Page 1 of 13  [Next >]       │
└──────────────────────────────────────────────────────────────────────────┘

File Structure

src/views/pages/reports_v2/
├── index.js                    # Route entry, loads ReportsDashboard
├── ReportsDashboard.jsx        # Main container with control plane + tabs
├── components/
│   ├── ControlPlane.jsx        # Sticky filter bar (Fuel/Period/Compare)
│   ├── ReportTabs.jsx          # Tab navigation component
│   ├── tabs/
│   │   ├── SummaryTab.jsx      # KPI strip + primary/secondary charts
│   │   ├── TrendsTab.jsx       # Time series with controls
│   │   ├── ComparisonTab.jsx   # Period A vs B comparison
│   │   ├── TenantsTab.jsx      # Ranking table with drilldown
│   │   ├── SpcTab.jsx          # Statistical Process Control
│   │   └── DataTab.jsx         # Raw data table + export
│   ├── charts/
│   │   ├── TrendChart.jsx      # Reusable line chart
│   │   ├── SpcChart.jsx        # Control chart with limits
│   │   ├── DeltaChart.jsx      # Comparison delta bars
│   │   └── Sparkline.jsx       # Mini inline chart
│   └── shared/
│       ├── KpiStrip.jsx        # Inline KPI display
│       ├── EmptyState.jsx      # No data placeholder
│       └── ExportButtons.jsx   # CSV/Excel export
├── hooks/
│   ├── useReportData.js        # Data fetching hook
│   ├── useSpcCalculations.js   # SPC math (mean, UCL, LCL)
│   └── useUrlState.js          # Sync filters to URL params
├── constants.js                # Fuel configs, period options
└── styles.module.scss          # Component styles

Component Specifications

1. ControlPlane.jsx

Sticky bar at top of report area.

Props: {
  fuel: string,              // 'electricity' | 'gas' | 'water'
  onFuelChange: fn,
  period: string,            // '1m' | '3m' | '6m' | '12m'
  onPeriodChange: fn,
  comparePeriod: string?,    // optional comparison period
  onComparePeriodChange: fn,
  availableFuels: string[],  // from API - which fuels have data
}

Layout:

┌─────────────────────────────────────────────────────────┐
│ Fuel: [Electricity ▼]                                  │
│ Period: [Last 12 Months ▼]  Compare: [None ▼]           │
└─────────────────────────────────────────────────────────┘

Behaviour:

Fuel change may hide/show tabs (e.g., SPC not available for all fuels)
Persist all selections to URL query params

2. ReportTabs.jsx

Tab navigation below control plane.

Props: {
  activeTab: string,
  onTabChange: fn,
  fuel: string,              // to conditionally show/hide tabs
}

Tabs:

Key	Label	Always Visible
`summary`	Summary	Yes
`trends`	Trends	Yes
`comparison`	Comparison	Yes
`tenants`	Tenants	Yes
`spc`	SPC	Yes
`data`	Data	Yes

Styling:

Horizontal tabs, underline active
No icons needed
Use ARIA roles: role="tablist", role="tab", aria-selected

3. SummaryTab.jsx

Executive overview.

Props: {
  fuel: string,
  period: string,
  buildingId: string,
}

Sections:

KPI Strip (inline, not cards)
- Total consumption (kWh/m³)
- Total charges (£)
- Average rate (£/kWh or £/m³)
- % Recharged
Primary Chart
- 12-month consumption trend line
Secondary Chart
- Charges trend OR Recharge % OR Baseload (fuel-dependent)

API Calls:

reportGetConsumptionSeries(buildingId, params)
reportGetChargesSeries(buildingId, params)
reportGetRechargedPercentSeries(buildingId, params)

4. TrendsTab.jsx

Detailed time series analysis.

Props: {
  fuel: string,
  period: string,
  buildingId: string,
}

Local Controls:

Metric dropdown: Consumption | Charges | Rate | CO2
Aggregation: Daily | Weekly | Monthly
Normalise checkbox (per m²)

Charts:

Full-width time series (multi-line if multiple tenants selected)
Optional: rolling average overlay

5. ComparisonTab.jsx

Period-over-period comparison.

Props: {
  fuel: string,
  periodA: string,
  periodB: string,
  buildingId: string,
}

Local Controls:

Period A selector
Period B selector
Mode: YoY | MoM | Custom

Sections:

Overlaid Chart - Two lines (Period A vs B)
Delta KPIs - +/- kWh, +/- £, +/- %
Delta Bars - Monthly deviation (green/red)

6. TenantsTab.jsx

Building-level tenant/meter ranking (no tenant-scoped dashboard in V1).

Props: {
  fuel: string,
  period: string,
  buildingId: string,
}

Local Controls:

Sort by: Consumption | Charges | % of Total
Metric: kWh | £

Table Columns:

Name	kWh	£	% Total	Trend
Tenant A	12,450	£1,245	32%	[sparkline]

Interaction:

Click row → expand inline drilldown panel
Drilldown shows: mini trend chart + meter breakdown

7. SpcTab.jsx

Statistical Process Control.

Props: {
  fuel: string,
  period: string,
  buildingId: string,
}

Local Controls:

Metric: Consumption | Baseload | Rate
Aggregation: Daily | Weekly | Monthly
Baseline: Rolling 12M | Fixed Period

SPC Chart:

Center line (mean)
UCL (Upper Control Limit) = mean + 3σ
LCL (Lower Control Limit) = mean - 3σ
Data points with out-of-control flags (red dots)

Anomaly Log Table:

Date	Value	Deviation	Severity	Notes
2025-12-15	1,450 kWh	+2.3σ	Warning	-

SPC Calculation (useSpcCalculations.js):

function calculateSpc(data) {
  const values = data.map(d => d.value);
  const mean = values.reduce((a, b) => a + b, 0) / values.length;
  const stdDev = Math.sqrt(
    values.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / values.length
  );
  const ucl = mean + 3 * stdDev;
  const lcl = mean - 3 * stdDev;
  
  return {
    mean,
    ucl,
    lcl,
    points: data.map(d => ({
      ...d,
      deviation: (d.value - mean) / stdDev,
      outOfControl: d.value > ucl || d.value < lcl,
    })),
  };
}

8. DataTab.jsx

Raw data export.

Props: {
  fuel: string,
  period: string,
  buildingId: string,
}

Export Buttons:

CSV download
Excel download

Table Columns:

Timestamp	Meter	Tenant	Value	£	Rate	Source

Pagination: Server-side, 100 rows per page

Styling Guidelines

DO:

Single light background (#f8f9fa or similar)
Subtle borders between sections
Consistent spacing (16px/24px grid)
Use existing CoreUI components where possible

DON'T:

No card shadows
No dark panels
No gradient backgrounds
No floating elements

CSS Variables to Define:

$report-bg: #f8f9fa;
$report-border: #e9ecef;
$report-text: #212529;
$report-muted: #6c757d;
$report-accent: #0d6efd;

URL State

Sync all filters to URL for bookmarking/sharing:

/reports/:buildingId?fuel=electricity&period=12m&compare=&tab=summary

Hook: useUrlState.js

function useUrlState() {
  const history = useHistory();
  const location = useLocation();
  
  const params = new URLSearchParams(location.search);
  
  const setParam = (key, value) => {
    params.set(key, value);
    history.replace({ search: params.toString() });
  };
  
  return {
    fuel: params.get('fuel') || 'electricity',
    period: params.get('period') || '12m',
    compare: params.get('compare') || '',
    tab: params.get('tab') || 'summary',
    setParam,
  };
}

API Endpoints (Existing)

All endpoints are in newreportService.js:

Endpoint	Used By
`reportGetConsumptionSeries`	Summary, Trends
`reportGetChargesSeries`	Summary, Trends
`reportGetCo2Series`	Trends
`reportGetRechargedPercentSeries`	Summary
`reportGetMonthlyProgress`	Summary
`reportGetPerformanceMonthly`	Trends, Data
`reportGetMatrix`	Tenants
`reportGetTenants`	Tenants (for ranking labels / drilldown)
`reportGetAvailableUtilities`	Control Plane

Migration Notes

Keep existing report_new/ folder untouched for rollback
Create new reports_v2/ folder
Add route in router: /reports_v2/:id → ReportsDashboard
Feature flag (optional): toggle between old/new in settings

Acceptance Criteria

Fuel selector changes all data across tabs
Tabs switch without page reload
URL reflects current state (bookmarkable)
SPC chart shows control limits and flags anomalies
Data tab exports to CSV
Empty states shown when no data
Mobile: control plane collapses to filter button
No visual cards - single surface design

daveapex/REPORTS-UI-IMPLEMENTATION.md

Select an option

No results found

Select an option

No results found

Reports UI V2 - Developer Implementation Guide

Overview

Wireframes

Global Layout

Summary Tab

Trends Tab

Comparison Tab

Tenants Tab

SPC Tab (Statistical Process Control)

Data Tab

File Structure

Component Specifications

1. ControlPlane.jsx

2. ReportTabs.jsx

3. SummaryTab.jsx

4. TrendsTab.jsx

5. ComparisonTab.jsx

6. TenantsTab.jsx

7. SpcTab.jsx

8. DataTab.jsx

Styling Guidelines

URL State

API Endpoints (Existing)

Migration Notes

Acceptance Criteria