Measurements

General

• More docs and context around these components can be found here
• The useMeasurements hook uses react-query under the hood and therefore needs to be wrapped with a <QueryClientProvider /> that manages the cache.
• Additionally the blueprint-api package exports an <ApiProvider /> which stores the graphQLApiRoute and potential requestHeaders. This provider needs to wrap all components that have querying logic inside.

ConsumptionGraph and ConsumptionGraphControl

These components together gives users an overview of their energy data for a single supply point. The data can be filtered based on daily, weekly, monthly, or yearly intervals, as well as with custom start dates. Additionally, there is a switch to see the associated usage costs or the generated income for the respective energy type and supply point.

If a measurement spans a time period where multiple tariff bands were active, the component will render multi-color bars to indicate how much energy was consumed/generated in each tariff band. If the costOfUsage view is toggled, and the total cost of a measurement is composed of multiple subcosts, there will be multi-color bars to showcase the distribution.

Import

import {
    ConsumptionGraph,
    ConsumptionGraphControl,
} from '@krakentech/blueprint-utils/client';

Usage

app.tsx

import { QueryClientProvider } from '@tanstack/react-query';
import { ApiProvider } from '@krakentech/blueprint-api/client';

<QueryClientProvider client={queryClient}>
    <ApiProvider apiRoute="/api/graphql" ...>
        ... other components in your tree
        <YourConsumptionPage />
        ...
    </ApiProvider>
</QueryClientProvider>;

YourConsumptionPage.tsx

import { enGB } from 'date-fns/locale';
// types from the API schema
import {
    FuelType,
} from 'your-project/types/generated/graphql/schema';
import {
    DateRangeToggleValue,
    useMeasurementFilters,
} from '@krakentech/blueprint-utils/client';

import SupplyPointConsumptionChart from './SupplyPointConsumptionChart'

const YourConsumptionPage () => {
    // in your page you need to bring in accountNumber, pick a property from a list of properties,
   // load supply points for that property
    const accountNumber = 'A-FAKE'; // probably load in from url param
   // get list of properties for account
    const properties = account.properties;
    // if multiple properties show a drop down, otherwise use the only one in the list
    const propertyId = property.id;
    const supplyPoints = property.supplyPoints; // get the list to iterate through, or whatever is appropriate for your market

 const measurementFilters = useMeasurementFilters({
        initialDateRange: DateRangeToggleValue.WEEK,
    });
    return (
        <PageLayout>
            <SupplypointConsumptionChartControl
                        utilityType={FuelType.Electricity}
                        locale={enGB}
                        supplyPoint={supplyPoints[0]}
                        translations={{
                            'graph.day': 'Day',
                            'graph.week': 'Week',
                            'graph.month': 'Month',
                            'graph.year': 'Year',
                            'start-date': 'Today',
                            'custom-interval': 'Custom',
                        }}
                        measurementFilters={measurementFilters}

            />

            {
                supplyPoints.map((supplyPoint)=> (
                    <SupplyPointConsumptionChart
                        accountNumber={accountNumber}
                        propertyId={propertyId}
                        utilityType={FuelType.Electricity} // or switch utility based on supply point
                        supplyPoint={supplyPoint}
                        locale={enGB}
                        label='See your data'
                        translations={{
                            'fuel-name': 'electricity',
                            'show-standing-charge': 'Show standing charge',
                            'cost-of-usage-tooltip': 'We don\'t have any cost data for this period yet',
                            'error-message': 'Something went wrong',
                            'no-data': 'No data available for this period',
                            'tooltip-no-data': 'No data available for this period',
                            'no-cost-of-usage-tooltip':'Cost of usage not available',
                        }}
                    />
                ))
            }

        </PageLayout>
    )
}

SupplyPointConsumptionChart.tsx

import {
    ConsumptionGraph,
    ConsumptionGraphControl,
    ConsumptionGraphProps,
    DateRangeToggleValue,
    useMeasurements,
    ConsumptionGraphControlTranslations
} from '@krakentech/blueprint-utils/client';

// This is an error handler for expired tokens
import { useKrakenAuthErrorHandler } from '@krakentech/blueprint-auth/client';
import { enGB } from 'date-fns/locale';

// types from the API schema
import {
    ReadingDirectionType,
    FuelType,
} from 'your-project/types/generated/graphql/schema';


export const SupplyPointConsumptionChart = ({
    accountNumber,
    propertyId,
    utilityType,
    supplyPoint,
    locale,
    label,
    translations,
}: {
    accountNumber: string;
    propertyId: string;
    utilityType: FuelType;
    supplyPoint: {
        id?: string | null | undefined;
        marketSupplyPointId?: string | null | undefined;
    };
} & Pick<ConsumptionGraphProps, 'translations' | 'label' | 'locale'>) => {
    const { locale } = useRouter();
    const { handleKrakenErrors } = useKrakenAuthErrorHandler();

    const measurements = useMeasurements({
        variables: {
            accountNumber,
            propertyId,
            utilityType,
            dateLocale: enGB,
            // if you want to show generation, you need to work out from the supply point which to show
            readingDirection: ReadingDirectionType.Consumption,
            marketSupplyPointId: supplyPoint.marketSupplyPointId,
            enabled: true,
            dateRange: DateRangeToggleValue.WEEK,
        },
        errorCallback: handleKrakenErrors
        locale,
    }
    );

    return (
        <ConsumptionGraph
            label={label}
            currency={'GBP'}
            translations={translations}
            locale={locale}
            measurements={measurements}
        />
    );
};

export const SupplypointConsumptionChartControl = ({
    locale,
    translations,
    utilityType,
    supplyPoint,
    measurementFilters,
}: {
    utilityType: FuelType;
     supplyPoint: {
        id?: string | null | undefined;
        marketSupplyPointId?: string | null | undefined;
    };
    translations: ConsumptionGraphControlTranslations;
} & Pick<ConsumptionGraphProps, 'locale' | 'measurementFilters'>) => {
    return (
        <ConsumptionGraphControl
            translations={translations}
            locale={locale}
            navigationButtonTestId={supplyPoint?.id || utilityType}
            measurementFilters={measurementFilters}
            stickyProps={{ enabled: true }}
        />
    );
};

StatisticsCards

SingleEnergyStatisticsCard

This component provides users with a quick overview by comparing this week's consumption for a single energy type to the previous week's consumption. It is data/market agnostic and can be used for both electricity and gas. The data for this component can be fetched by using the Blueprint util's useMeasurements hook or a custom data fetching hook. If you are using a custom data fetching hook you should ensure that the data is returned in the same format as the Blueprint util's useMeasurements hook before passing into this component.

Import

import { SingleEnergyStatisticsCard } from '@krakentech/blueprint-utils/client';

Usage

import { enGB } from 'date-fns/locale';
import {
    SingleEnergyStatisticsCard,
    useMeasurements,
} from '@krakentech/blueprint-utils/client';
import { ReadingDirectionType, UtilityType } from '@app/types/generated/graphql/schema';

...

    const measurements = useMeasurements({ ... });

    if (utilityType === UtilityType.Gas) {
        return (
            <SingleEnergyStatisticsCard
                meterpointId={meterPoint.id ?? undefined}
                measurements={measurements}
                energyType={'gas'}
                translations={translations}
                locale={enGB}
                currency={'GBP'}
                displayCost={true}
            />
        );
    }

    if (utilityType === UtilityType.Electricity) {
        return (
            <SingleEnergyStatisticsCard
                meterpointId={meterPoint.id ?? undefined}
                measurements={measurements}
                energyType={'electricity'}
                readingDirection={
                    readingDirection === ReadingDirectionType.Generation
                        ? 'Generation'
                        : 'Consumption'
                }
                translations={translations}
                locale={enGB}
                currency={'GBP'}
                displayCost={true}
            />
        );
    }

MultiEnergyStatisticsCard

Similar to the SingleEnergyStatisticsCard, this component provides users with a quick overview by comparing this week's consumption of multiple energy types (i.e. gas and electricity) to the previous week's consumption. This is useful for users who only have 1 meter point for both gas and electricity, so they can see the consumption of both energy types in one card. As with SingleEnergyStatisticsCard, it is data/market agnostic - the data for this component can be fetched by using the Blueprint util's useMeasurements hook or a custom data fetching hook. If you are using a custom data fetching hook you should ensure that the data is returned in the same format as the Blueprint util's useMeasurements hook before passing into this component.

Import

import { MultiEnergyStatisticsCard } from '@krakentech/blueprint-utils/client';

Usage

import { enGB } from 'date-fns/locale';
import {
    MultiEnergyStatisticsCard,
    useMeasurements,
} from '@krakentech/blueprint-utils/client';

...

    const electricityMeasurements = useMeasurements({ ... });
    const gasMeasurements = useMeasurements({ ... });

    return (
        <MultiEnergyStatisticsCard
            measurements={{
                electricity: {
                    data: electricityMeasurements.data,
                    meterpointId: electricityMeter?.id ?? undefined,
                },
                gas: {
                    data: gasMeasurements.data,
                    meterpointId: gasMeter?.id ?? undefined,
                },
                isLoading:
                    (!!electricityMeter && electricityMeasurements.isLoading) ||
                    (!!gasMeter && gasMeasurements.isLoading),
                error: electricityMeasurements.error || gasMeasurements.error,
            }}
            translations={translations}
            locale={enGB}
            currency={'GBP'}
            displayCost={true}
        />
    );

Preview

Storybook