Period Comparison Widget
Component Detail
Description
Reusable widget that visualises the difference between the current period and the equivalent period in the prior year. Renders a numeric delta with directional arrow and colour-coded text when historical data is available, or gracefully omits the comparison when it is not.
period-comparison-widget
Summaries
The Period Comparison Widget provides users with immediate, intuitive context about whether current performance is improving or declining relative to the same period last year. By presenting a colour-coded delta with a directional arrow, the widget transforms raw numbers into meaningful trend signals — enabling mentors and coordinators to understand progress without requiring data literacy. This supports a culture of continuous improvement and gives the organisation evidence of programme effectiveness over time. The component handles missing historical data gracefully, ensuring a polished experience even for new participants in their first year of the programme.
Period Comparison Widget is a low-complexity, self-contained mobile UI component with no external dependencies, making it straightforward to develop and test in isolation. It can be built and validated early in the sprint cycle, then integrated wherever period-over-period comparisons are needed in the UI. The main delivery consideration is agreeing on the colour scheme and threshold logic for positive versus negative trends with design and product stakeholders before implementation begins, to avoid rework. Testing must cover three states: positive delta, negative delta, and unavailable historical data.
Because this is a reusable widget, invest in thorough snapshot and unit tests to protect against regressions as it is consumed in multiple contexts.
PeriodComparisonWidget is a stateless, low-complexity mobile UI component accepting current, previous, and unit props via PeriodComparisonWidget({current, previous, unit}). It computes the delta internally and delegates rendering to renderDelta(value, direction) for the numeric and arrow display, or renderUnavailableState(reason) when previous is null or undefined. Colour coding should use the design system's semantic tokens (positive/negative/neutral) rather than hardcoded hex values to remain consistent with the broader theme. Because this component has no dependencies, it is fully unit-testable without mocks.
Consider memoisation if it appears in high-frequency re-render contexts such as a scrollable list of mentor rows.
Responsibilities
- Display current-period vs prior-year-period delta
- Handle missing historical data gracefully with placeholder text
- Apply colour coding for positive/negative trends
Interfaces
PeriodComparisonWidget({current, previous, unit})
renderDelta(value, direction)
renderUnavailableState(reason)
Related Data Entities (1)
Data entities managed by this component