Count adjust

A React component in Beamline's Form controls category.

A count of whole things against its whole (received of ordered, credits of bought), set by hand: what is on record stays solid, the change is drawn as its own segments up to where you hold the row's end (added lit, taken away struck), the exact field is its twin, the words say the change, the new count and the rest, the limits refuse in words, a suggestion is marked; the app gets the count and the delta apart.

Use it for

Receiving part of an order (3 of 10 came before, this delivery adds some): the received-so-far and this delivery must never be confused.
Correcting a held count (package credits, stock on hand) where the change itself must be seen before it is saved; draw only what is left (whole = what is held), so an empty box keeps meaning "not yet".
Setting a quantity beside a suggestion, with a different count said as your own.

Not for

An exact number with no record or whole (number-field).
An approximate value on a continuous scale (slider).
Showing an allowance filling up without editing it (usage-meter).

Anatomy

row: one segment per unit of the whole up to 40, one continuous bar beyond; an empty box is "not yet"; on record solid ink; the change being made in the accent role (what you are acting on); taken away outlined and struck in ink. No success or danger tones: those belong to the app's saved result
grip (value-grip, role slider): at the row's end on the new count
suggestion mark: a dashed upright at the suggested count
field (number-field): the exact twin, named "<label>, exact"
words (live): the change with its label, the new count of the whole, the rest with its label, the suggestion
limit line: why it can't go lower or higher, once the hand has moved the count onto a limit with a reason (never at rest)

States

same (data-state=same): no change, only the count of the whole said
added (data-state=added): the change drawn in the accent and said in ink
removed (data-state=removed): the units taken away struck, said in ink
settling: when the record rises to meet the count (a saved change), the new units glide into the record one after another
at a limit after a move: the reason said under the row
held: the count follows the hand per unit; saved once on letting go
suggested: the mark and "Suggested n"; a different count also says "Your own count"
disabled: no hand, the field disabled
right to left: the row and the arrow keys mirror
reduced motion: segments change at once
void rest (voidRest): the empty units struck faint, for what will never come

Keyboard

Left/Right (mirrored right to left) and Down/Up on the grip: one unit
Shift with an arrow, or Page Up/Down: ten
Home/End: the floor and the ceiling
Escape during a drag: back to the count at the press
The field: type the exact count, Enter or leave to set it

Motion

A saved change settles: when `recorded` rises to the count, each new unit's solid layer glides a few pixels into place and fades in, one after another from the old record's end (opacity and translate only, the considered duration, staggered a sixth of it). Moving the count changes the units at once; the grip glides between key steps and follows the hand while held. Nothing runs at rest; reduced motion changes at once.

Props

Prop	Type	Default	Description
`label` (required)	`string`	—	The count's name ("Received", "Credits left"); the grip and the field are named from it.
`recorded` (required)	`number`	—	What is on record now (received so far, credits left). Drawn solid; the hand never moves it.
`whole` (required)	`number`	—	The whole the count is out of (ordered, bought): one segment each, up to 40, a bar beyond.
`value`	`number`	—	The new count, controlled with `onValueChange`, or `defaultValue` (default `recorded`).
`defaultValue`	`number`	—	Initial selection when uncontrolled; omitted by default.
`onValueChange`	`(count: number) => void`	—	Every step while held and every key or typed change.
`onValueCommit`	`(change: { count: number; delta: number }) => void`	—	Once when the count settles (let go, a key step, the field left): the count and the delta apart.
`min`	`number`	—	The least it can be (default 0): the credits already used, or what is already received when only adding.
`max`	`number`	—	The most it can be (default `whole`).
`minReason`	`string`	—	Why it can't go lower or higher, in your words ("2 already used", "that's all 10 ordered"); said at the limit.
`maxReason`	`string`	—	Why it can't go higher, in your words; said at the ceiling.
`suggested`	`number \| null`	—	A count your app suggests, marked on the row with its words; null or left out for none.
`changeLabel`	`string`	—	What the change is ("this delivery", "credits"), said after its number: "+3 this delivery".
`restLabel`	`string`	—	What the rest of the whole is ("still due", "used"), said after its number: "4 still due". Left out, not said.
`voidRest`	`boolean`	—	The rest of the whole won't come (an order closing short): its empty units drawn struck, faint.
`disabled`	`boolean`	—	No hand; the field disabled.
`className`	`string`	—	Classes on the documented visual root; no override 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.
`held`	`number`	—	Units already there that aren't the hand's to change (in stock, on other orders), drawn solid before the record and kept out of the count, its limits and the change's words; part of `whole`. Default 0.
`used`	`number`	—	Units already spent out of the whole (credits used, seats taken), drawn as quiet filled units after the rest, so the whole can stay what was bought; raising the count takes units back from them (a credit given back). Part of `whole`. Default 0.
`heldLabel`	`string`	—	What `held` and `used` are, said after their numbers ("3 in stock", "2 used"). Left out, not said.
`usedLabel`	`string`	—

Built from

Used in

Dependencies

value-grip, number-field

Import

import { CountAdjust } from "@beamline/count-adjust";

Get it

Count adjust 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