KQ-1768 · OVERAGE/FORECAST

Overage Forecast

A metered-usage panel where each meter is a small chart: history up to today, the plan's allowance as a hairline, and a forecast cone fanning from today's reading to the period's end, its share above the allowance drawn in warn. When a meter is first seen the history draws across and the cone grows out of today on springs.glide, a beat apart per meter, and turning on planned load springs every cone's ends to their new values on the same spring so each fan widens and lifts while the overage and the projected bill roll to their new figures. Each chart is a slider over the period's days: hover, a tap or the arrow keys move a cursor on springs.flick whose reading is the value text, Page keys move a week, Home and End reach the ends and Escape returns to today.

KQ-1768 · OVERAGE/FORECAST

Usage · Oct 1 – Oct 31

Gaugeworks · Team

Day 17 of 31 · resets Nov 1

Projected bill

$381.00

Plan $299.00 + overage $82.00

likely $327.00 – $449.00

Include planned loadLoad test Oct 24 · Archive backfill · Release branch

API calls

41.2kof 50k calls

+ overage

Storage

312of 400 GB

Within plan

Build minutes

1.9kof 3k min

+ overage

projected $381.00 · 2 meters over

Open it on the Canvas stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/overage-forecast

Props

usage: OverageUsage[]; default defaultOverageUsage; Each metered thing: { id, label, unit, used, history?, icon? }.
plan: OveragePlan; default defaultOveragePlan; The period, the base price, and each meter's { included, rate, per }.
forecast: OverageForecast; default defaultOverageForecast; Where each meter is likely to land: { low, mid, high, planned? } by meter id.
now: number; default Oct 17 2026, 14:00 UTC; The moment the meters are read at, in ms.
account: string; default "Gaugeworks"; The account the usage belongs to.
includePlanned / defaultIncludePlanned: boolean; default — / false; Whether planned load is counted in the forecast, controlled or initial.
onForecastToggle: (on) => void; default —; Fires from the switch with the new state.
alerts / defaultAlerts: Record<string, number>; default — / { api: 45000 }; Alert thresholds by meter id, controlled or initial.
onSetAlert: (id, value | null) => void; default —; Fires when an alert is saved (a number) or removed (null).
upgrade: OverageUpgrade | null; default Scale, $449; The plan to suggest in the footer; null hides the suggestion.
onUpgrade: (upgrade) => void; default —; The footer's button was pressed.
status: "ready" | "loading" | "empty" | "error"; default "ready"; Whether the readings have arrived; empty is a fresh period.
onRetry: () => void; default —; Try again was pressed after the readings failed to load.
coneStyle: "fan" | "bands" | "lines"; default "fan"; How the forecast cone is drawn: one fading wedge, nested bands, or dotted edges.
meterHeight: number; default 88; Height of each meter's chart, in px.
accent: "cobalt" | "plum" | "mint" | "ink" | string; default "cobalt"; History, cone, cursor and switch: a named pigment or any CSS colour.
formatMoney: (amount) => string; default Intl USD; How money is written.
disabled: boolean; default false; Alerts, the switch and the upgrade are unavailable; readings stay readable.
className: string; default —; Classes for the panel; it caps at 36rem tall and scrolls inside past that.

Prop	Type	Default	Description
usage	OverageUsage[]	defaultOverageUsage	Each metered thing: { id, label, unit, used, history?, icon? }.
plan	OveragePlan	defaultOveragePlan	The period, the base price, and each meter's { included, rate, per }.
forecast	OverageForecast	defaultOverageForecast	Where each meter is likely to land: { low, mid, high, planned? } by meter id.
now	number	Oct 17 2026, 14:00 UTC	The moment the meters are read at, in ms.
account	string	"Gaugeworks"	The account the usage belongs to.
includePlanned / defaultIncludePlanned	boolean	— / false	Whether planned load is counted in the forecast, controlled or initial.
onForecastToggle	(on) => void	—	Fires from the switch with the new state.
alerts / defaultAlerts	Record<string, number>	— / { api: 45000 }	Alert thresholds by meter id, controlled or initial.
onSetAlert	(id, value \| null) => void	—	Fires when an alert is saved (a number) or removed (null).
upgrade	OverageUpgrade \| null	Scale, $449	The plan to suggest in the footer; null hides the suggestion.
onUpgrade	(upgrade) => void	—	The footer's button was pressed.
status	"ready" \| "loading" \| "empty" \| "error"	"ready"	Whether the readings have arrived; empty is a fresh period.
onRetry	() => void	—	Try again was pressed after the readings failed to load.
coneStyle	"fan" \| "bands" \| "lines"	"fan"	How the forecast cone is drawn: one fading wedge, nested bands, or dotted edges.
meterHeight	number	88	Height of each meter's chart, in px.
accent	"cobalt" \| "plum" \| "mint" \| "ink" \| string	"cobalt"	History, cone, cursor and switch: a named pigment or any CSS colour.
formatMoney	(amount) => string	Intl USD	How money is written.
disabled	boolean	false	Alerts, the switch and the upgrade are unavailable; readings stay readable.
className	string	—	Classes for the panel; it caps at 36rem tall and scrolls inside past that.