Allocation editor

A React component in Beamline's Form controls category.

Parts of a fixed whole edited as transfers: an ordered strip whose boundaries drag or step between neighbours and a roster of exact amounts where typing names the part that gives or takes; locks, limits and your rules refuse with words, nothing is redistributed out of sight, and Save waits for your handler.

Use it for

Moving amounts between parts of a fixed whole: minutes of a session, hours of a week, a budget across a few lines.
Ordered plans (an agenda, a route, a shift) where moving a boundary between neighbours is the natural edit.
When the whole must stay correct after every change and some parts are locked or limited by your rules.

Not for

Independent numbers whose sum is an outcome, not a fixed whole (number-field per value, with a computed total).
Typing a whole plan from a document, or more than about eight parts (number-field rows with a running total and Save blocked until it matches).
Showing a split without editing it (category-bar, usage-meter, pie-chart).
Resizing panes of a layout (resizable-panels).
One approximate value or range (slider).

Anatomy

header (title, fixed total, description)
strip: track, segments (part, gap, unallocated, over), boundary handles (slider), fixed seams beside locked parts, saved-boundary marks, scale
roster: one row per part (label, exact amount or locked value, change 30 → 35 +5, note: trades-with / lock reason / error, partner choice while an entry needs one)
status line and a polite live region
refused-save alert
footer: Cancel, Save (with onSave)

Variants

order: sequence, set

States

resting
dirty (data-dirty on root, rows and segments)
dragging
at limit (data-limit)
pending partner (data-pending)
working: saving (data-loading, aria-busy)
resolved: Saved (caller's acknowledged result)
error: refused transfer (reason beside the cause)
error: refused save (data-error, alert, draft kept)
locked part (data-locked, lock reason)
unallocated (named segment, Save blocked)
over (named hatched band, Save blocked)
not set (null: — and Not set, never 0)
loading
empty
read-only
disabled

Keyboard

Boundary: → / ← move it one step in that direction (mirrored in RTL); ↑ / ↓ toward the end / start
Boundary: Shift+arrow or Page Up / Page Down a large step; Home / End as far as limits and rules allow; Esc during a drag reverts
Amount field: type, ↑ / ↓ adjust the proposal, Enter applies, Esc reverts; the note names the part that gives or takes before it applies
Two eligible partners: Enter moves to the choice; Enter or Space on a choice applies it and returns to the field
Tab: boundaries, then fields, then Cancel and Save; locked parts have no stop

Motion

Boundary keys and drags place the boundary at once, in whole steps; an applied entry, Cancel or adopted save moves widths over --pui-duration-standard without overshoot; change marks arrive in 90ms and leave in 180ms; never bounces at a limit. Reduced motion: all instant.

Props

Prop	Type	Default	Description
`label` (required)	`string`	—	The whole's name and the group's accessible name.
`items` (required)	`{ id, label, kind?: "part" \| "gap", min?, max?, locked?, lockReason?, description?, color? }[]`	—
`total` (required)	`number`	—	The fixed whole; never changed by the component.
`step / largeStep`	`number`	—	Every transfer is a whole multiple of step. Defaults 1 / 5 × step.
`unit / format / locale`	`string / (amount) => string / string`	—
`scale`	`boolean \| (offset) => string`	`true`	Labels at boundaries, e.g. clock times.
`order`	`"sequence" \| "set"`	`"sequence"`	set: order is arbitrary, no handles; an entry asks which part gives whenever more than one could.
`value / defaultValue / onValueChange`	`Record<id, number \| null>, (value, transfer \| null) => void`	—
`onValueCommit`	`(value) => void`	—	Once per drag, key press, applied entry, Cancel or adopted save.
`savedValue`	`Record<id, number \| null>`	—	The persisted baseline; Cancel returns to it.
`canTransfer`	`({ from, to, amount, via }, next) => true \| string`	—	Your rule; a string refuses with those words.
`onSave`	`({ value, changes, transfers }) => Promise<value \| void>`	—	Shows Cancel and Save; throw to refuse and keep the draft.
`onCancel`	`() => void`	—
`saveLabel / savedLabel / cancelLabel / messages`	`string / Partial<AllocationMessages>`	—
`error / loading / emptyLabel / readOnly / disabled / name`	`mixed`	—
`className / style / classNames`	`string / CSSProperties / Partial<Record<slot, string>>`	—

Dependencies

lucide-react

Import

import { AllocationEditor, UNALLOCATED } from "@/components/allocation-editor/allocation-editor";

Get it

Allocation editor is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. Get Beamline · Connect your agent