Budget vessels
A React component in Beamline's Dashboard category.
Budgets as glasses of money: the liquid is what is left (free money on top, committed money as a lighter layer under it), the lip at the period's budget, an overspend a red band of owed money on the floor. Pick a glass up and hold it over another: it tips until its level liquid reaches the lip and pours while you hold (tipping further as it empties), the target fills, owed money first, it pauses at exactly the amount that covers an overspend, and letting go moves it with an Undo; more than the plan heaps over the rim. A quick drop pours the suggestion; Enter or a tap on two glasses opens a slider instead. One panel under the glasses explains whichever is hovered or focused: budget − spent − committed = left, and what carries into next period.
Use it for
- Personal finance, project, team and procurement budgets: categories with a budget each, spending against them, and money moved between them to cover an overspend.
- The host owns the budgets and applies a pour (onPour); the part shows the layers, previews the move and says what carries.
Not for
- One quota or limit with its usage → usage-meter.
- Shares of a fixed whole edited as transfers → allocation-editor.
Anatomy
- header: the label and period; N left of the total, and how much is over in how many categories
- glass: the money left as liquid coloured by pace (green keeps up with the period, amber is low for the time left with the word low, red only ever means over): free on top, committed as a lighter layer under it, an overspend as a red band of owed money on the floor, more than the plan as a heap over the rim; the lip at the budget the glass first had this period, its sum beside it; the name and one line: N left / N left · low / All spent / N over
- panel: the hint at rest; the glass in view as a sum (Budget + Carried in − Spent − Committed (named by its commitments) = Left or Over) and what carries; while pouring, the amount and what to do; after a pour, Moved N from a to b with Undo
- slider (keyboard and taps): From a to b, a slider marked $0, Covers N and All N, Pour N, Cancel
States
- rest
- over (owed band)
- all spent
- committed
- rollover (carries)
- explained (hover or focus)
- held
- pouring (live)
- covers the overspend (magnet)
- picking a target
- slider
- poured (Undo)
- read-only
- phone bars
- over the plan (heap)
Keyboard
- Tab reaches each glass (it reads its state) and the panel explains it; Enter or Space picks it as the source, Enter on another glass opens the slider with focus on it (Enter on the same glass, Cancel or Escape drops the pick)
- Arrows step the amount by one unit, Page Up/Down by ten, Home and End to nothing or all; the levels preview as it moves; Pour commits and focus returns to the target, Escape or Cancel puts it back with focus on the source; Undo reverses the last pour
Motion
Held over another glass the carried glass glides to its pouring place above and beside it and tips toward the target's mouth by exactly the angle its liquid needs to reach the lip (solved from how much is in it, so a full glass pours at a small tip and an emptying one tips further); inside it the liquid lies level; a stream falls from the lip and the levels follow the hold with no lag. At rest and after a pour the levels move on the considered ease; an owed band or a heap rises on the considered ease; reduced motion keeps the levels and drops the stream.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label (required) | string | — | "Household budget". |
period | string | — | This period's name, "October"; and the next one's, "November", for what carries. |
next | string | — | |
categories (required) | BudgetCategory[] | — | The categories; the host applies a pour to the budgets (onPour) and passes them back. |
currency | string | — | ISO code. Default USD. |
format | ((amount: number) => string) | — | Money in the host's own format; it wins over `currency`. |
onPour | ((pour: BudgetPour) => void) | — | Move budget from one category to another (an Undo calls it again the other way). Without it the vessels are read-only. |
className | string | — | Classes on the documented visual root; no override by default. |
classNames | Partial<Record<"root" | "total" | "vessel" | "pour", string>> | — | Classes for the named visual parts; no overrides by default. |
style | CSSProperties | — | Inline styles on the documented visual root; no overrides by default. |
ref | Ref<HTMLDivElement> | — | Receives the documented native target or imperative handle; omitted by default. |
elapsed | number | — | How much of the period has gone, 0–1 (18 October ≈ 0.58). A glass with less left than the rest of the period needs is running low; without it, a glass under a quarter full is. |
Built from
Used in
Import
import { BudgetVessels } from "@beamline/budget-vessels";Get it
Budget vessels is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. Get Beamline · Connect your agent
More in Dashboard
- Explainable total: A total that answers "why this much?" in place: it unfolds into the steps that made it — a waterfall whose bars start where the last step ended, each…
- Explainable change: A metric whose change explains itself: at rest the value, the change against a named period and a thin ribbon of its causes under the change; opened in…
- Insight cards: Findings from an agent, one per page: the sentence, the series it is about with their change, a chart to scrub that names each point, and a follow-up…
- Tracker: A row of status blocks for uptime, job runs or daily checks, with tooltips and a legend.
- Metric card: A KPI that fills its tile: label, a value that rolls to each new number, the change with arrow, sign and tone, what it compares with and the value it…
- Category bar: One bar split into labelled ranges with an optional marker that names its range.
- Bar list: Ranked horizontal bars, label and value over a meter, one line per row when there is room — top pages, sources, customers.
- App shell: The frame for every app screen: collapsible sidebar with grouped navigation, top bar and page.