KQ-1131 · CALC/FIELD

Calc Field

An amount field that takes arithmetic: type 1240/3, 12*4+3 or 15% and the answer rides in a bubble just past the last character, kept up with on the snap spring, its digits rolling up as the answer grows and down as it shrinks. Enter or leaving the field commits: the sum folds away, or down into a receipt, on the exit tween while the answer folds down into place on snap; a character that can never be arithmetic is refused with a soft shake. The parser is a small recursive descent with no eval, and the input stays native, so typing, IME, paste and undo work, and undo brings a committed sum back.

KQ-1131 · CALC/FIELD

Coldbrook cabin

Waylight Pay · 3 nights

$1,240 total

Amount to pay back

not set · enter or leave the field to set it

Open it on the Tactile stage

Install

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

$ pnpm dlx shadcn@latest add @kinetiq/calc-field

Props

label: string; default —; What the amount is. Shown above the field and tied to it by id.
value / defaultValue: number | null; default null; The committed amount, already rounded. Controlled or uncontrolled; a host that sets an amount the field did not report sees it written into the field.
onValueChange: (value: number | null) => void; default —; Fires from the Enter or blur that committed it, with the rounded amount; null when the field is emptied and committed.
defaultText: string; default —; A sum the field starts with, worked out but not committed.
percentOf: number; default —; What a bare percentage is a share of: with 1240, 15% is 186. Without it a bare percentage is its fraction.
placeholder: string; default "0.00" at the field's precision; The field's placeholder.
precision: number; default 2; Decimals in the answer and the committed amount, 0 to 3 — the range currencies use.
currency: string; default "USD"; An ISO currency code whose symbol sits before the field and in the bubble, or "none" for a plain number.
expression: boolean; default true; Write the sum out under the field while you type (× ÷ −, and which way it was rounded when it was), fold it down into a receipt on commit, and make the receipt a button that brings the sum back. Off, the sum folds away with nothing kept.
rounding: "half-up" | "half-even" | "up" | "down"; default "half-up"; How the answer is brought to precision, on its decimal digits (1.005 is 1.01 half up). "up" and "down" are away from and toward zero. A rounded answer shows ≈, and the tape names the mode.
sound: boolean; default false; A tick as the answer changes, pitched by its size and panned by the bubble's place, a click on commit, and a quiet shrug with each shake. Nothing plays, and no audio context exists, unless this is on.
disabled: boolean; default false; Disables the field and the receipt.
className: string; default —; Merged onto the root's classes.

Prop	Type	Default	Description
label	string	—	What the amount is. Shown above the field and tied to it by id.
value / defaultValue	number \| null	null	The committed amount, already rounded. Controlled or uncontrolled; a host that sets an amount the field did not report sees it written into the field.
onValueChange	(value: number \| null) => void	—	Fires from the Enter or blur that committed it, with the rounded amount; null when the field is emptied and committed.
defaultText	string	—	A sum the field starts with, worked out but not committed.
percentOf	number	—	What a bare percentage is a share of: with 1240, 15% is 186. Without it a bare percentage is its fraction.
placeholder	string	"0.00" at the field's precision	The field's placeholder.
precision	number	2	Decimals in the answer and the committed amount, 0 to 3 — the range currencies use.
currency	string	"USD"	An ISO currency code whose symbol sits before the field and in the bubble, or "none" for a plain number.
expression	boolean	true	Write the sum out under the field while you type (× ÷ −, and which way it was rounded when it was), fold it down into a receipt on commit, and make the receipt a button that brings the sum back. Off, the sum folds away with nothing kept.
rounding	"half-up" \| "half-even" \| "up" \| "down"	"half-up"	How the answer is brought to precision, on its decimal digits (1.005 is 1.01 half up). "up" and "down" are away from and toward zero. A rounded answer shows ≈, and the tape names the mode.
sound	boolean	false	A tick as the answer changes, pitched by its size and panned by the bubble's place, a click on commit, and a quiet shrug with each shake. Nothing plays, and no audio context exists, unless this is on.
disabled	boolean	false	Disables the field and the receipt.
className	string	—	Merged onto the root's classes.