NumberBox

The NumberBox lets users enter and adjust numbers (quantity, price, tax rate, font size…). Its style and behavior reproduce the WinUI 3 (Windows App SDK) NumberBox: it is essentially a TextBox + math parsing + NaN semantics, so this component embeds FluereInput (consistent with the embedded TextBox in the WinUI template) and implements WinUI's value-handling semantics, validation modes, spin buttons and inline expressions.

Values follow WinUI's Value ↔ Text dual channel: when the value changes, the formatted text is written back to the input box; on blur or Enter, the text is parsed and the value updated. Clearing the input box yields null (corresponding to WinUI's NaN), at which point placeholder is shown.

Difference from the original plan in docs/todo.md: reuse of reka-ui's NumberField was originally planned, but its NumberFieldInput has a few hard conflicts with WinUI — Home / End are mapped to min / max (WinUI leaves them to the TextBox to move the caret), invalid input clears the value on blur (WinUI keeps the original value), arrow keys snap to the step (WinUI adds directly), the wheel direction is reversed, and LargeChange is hardcoded to 10 steps. Here the "reuse" approach is kept but re-implemented as a self-contained implementation: the format / parse / expression / step four pure-function layers plus the use-number-box / use-spin-repeat two hooks, each unit-testable independently.

Basic usage

v-model binds the numeric value, header is WinUI's title row (also the default accessible name), and description renders below the control and acts as aria-describedby.

<FluereNumberBox v-model="quantity" header="Quantity" />
<FluereNumberBox v-model="price" header="Unit price" description="Supports decimals" />

Range and step

min / max map to Minimum / Maximum (by default no bounds are set, in which case aria-valuemin / aria-valuemax are not rendered); step is SmallChange (arrow keys / wheel / spin buttons), largeStep is LargeChange (PageUp / PageDown). Consistent with WinUI: no step snapping, values are only clamped (or wrapped) when out of range.

<FluereNumberBox
  v-model="quantity"
  :min="0"
  :max="500"
  :step="10"
  :large-step="100"
  header="Quantity"
/>
<FluereNumberBox v-model="ratio" :min="0" :max="1" :step="0.1" header="Ratio" />

Pass wrap-enabled for IsWrapEnabled: after reaching an endpoint the value wraps around to the other end, and both buttons stay usable.

Spin buttons

spinButtonPlacementMode maps to SpinButtonPlacementMode: hidden (default) / inline (up/down buttons inline to the right of the input box) / compact (a button panel floats up on focus). inline shares a TextBox border with the input box; the buttons are 32×24, margin 4, corner radius 4; holding a button steps once immediately, then repeats every 250ms (the WinUI RepeatButton Delay / Interval defaults). Buttons never enter the Tab sequence (WinUI IsTabStop=False) but can be activated with Enter / Space.

<FluereNumberBox
  v-model="fontSize"
  :min="9"
  :max="72"
  spin-button-placement-mode="inline"
  header="Font size"
/>
<FluereNumberBox
  v-model="zoom"
  :min="0.5"
  :max="3"
  :step="0.25"
  spin-button-placement-mode="inline"
  header="Zoom"
/>

<FluereNumberBox
  v-model="opacity"
  :min="0"
  :max="100"
  spin-button-placement-mode="compact"
  header="Opacity"
/>

Inline expressions

accepts-expression maps to AcceptsExpression: on blur or Enter it evaluates expressions composed of + - * / ^ and parentheses, with precedence ^ > * / > + -. After evaluation the raw expression is not preserved (it is replaced by the result).

<FluereNumberBox
  v-model="total"
  accepts-expression
  placeholder="e.g. (2+3)*4^2"
  header="Computed value"
/>

Validation modes

validationMode maps to ValidationMode:

• invalidInputOverwritten (default): on blur / Enter, invalid input is overwritten by the formatted text of the current value, and out-of-range values are clamped back into the range;
• disabled: keeps the user's input and out-of-range values, leaving validation to the consumer.

Escape always discards the input and returns to the current value; Enter commits the input (and swallows the key to avoid triggering an implicit form submission, matching how WinUI handles Enter).

<FluereNumberBox v-model="strict" :min="0" :max="100" header="Default: invalid input overwritten" />
<FluereNumberBox
  v-model="lenient"
  :min="0"
  :max="100"
  validation-mode="disabled"
  header="Keep input"
/>

Formatting and locale

formatOptions (Intl.NumberFormatOptions) maps to NumberFormatter, and locale determines the decimal point / group separators / minus sign — display and parsing share the same set of symbols. SSR apps are recommended to pass locale explicitly: by default the runtime's default locale is used, but the server and browser defaults may differ (e.g. the de-DE decimal point), producing a hydration mismatch on the first frame.

WinUI's default DecimalFormatter is set to IntegerDigits(1) + FractionDigits(0), which on several WinAppSDK versions rounds the displayed value to an integer (microsoft/microsoft-ui-xaml#8780: entering 25.8 shows 26 after blur). On the web side decimals are not dropped by default (maximumFractionDigits: 20), otherwise a usage such as step = 0.1 becomes unusable at the display layer; pass :format-options="{ maximumFractionDigits: 0 }" to get WinUI's integer look. Before display, a WinUI-style 10-significant-digit rounding is also applied to wipe out floating-point noise such as 0.1 + 0.2 = 0.30000000000000004.

<FluereNumberBox
  v-model="integer"
  :format-options="{ maximumFractionDigits: 0 }"
  header="Integer appearance"
/>
<FluereNumberBox
  v-model="fixed"
  :format-options="{ minimumFractionDigits: 2, maximumFractionDigits: 2 }"
  header="Fixed two decimal places"
/>
<FluereNumberBox v-model="german" locale="de-DE" header="de-DE: 1.234,5" />

Disabled

<FluereNumberBox
  :model-value="35"
  :min="0"
  :max="100"
  disabled
  spin-button-placement-mode="inline"
  header="Disabled"
/>

Form submission

When placed inside a <form> with a name, it adds a hidden native <input type="hidden"> submitting name=value (an empty string when there is no value).

<form @submit.prevent="onSubmit">
  <FluereNumberBox v-model="amount" name="amount" :min="0" :step="8" spin-button-placement-mode="inline" header="Amount" />
  <FluereButton type="submit" appearance="primary">Submit</FluereButton>
</form>

API

Keyboard and pointer handling follow NumberBox.cpp: arrow keys step by SmallChange, PageUp / PageDown by LargeChange, Enter commits, Escape reverts, and gaining focus selects the whole text; the mouse wheel only responds while the input box holds focus, scrolling up increments (MouseWheelDelta > 0). WinUI leaves Home / End to the TextBox, and this component likewise does not treat them as step keys.

Accessibility: the input box carries role="spinbutton" with aria-valuenow / aria-valuemin / aria-valuemax (the latter two are not rendered when no bounds are set, matching WinUI's behavior of composing them into the UIA name only once Minimum / Maximum are rewritten); the spin buttons do not enter the Tab sequence but can be activated by keyboard, and each carries an accessible name.

Two web-side approximations: the compact popup approximates WinUI's Acrylic surface with colorNeutralBackground1 + shadow16 (the Fluent token set has no material tokens); when the inline buttons appear, the right side of the input box gives up an extra 84px to keep text from pressing onto the buttons (WinUI lets text press under the buttons).

WinUI's Text property is not exposed as a separate prop: on the web side the input-box text is derived from v-model plus formatting (Value → Text); use formatOptions for custom text display. The WinUI initialization order of "when both Text and Value are set, Value wins" therefore does not apply.