[number field] Add imperative control of the raw input value

docs/src/app/(docs)/react/components/number-field/page.mdx

@@ -34,6 +34,45 @@ import { NumberField } from '@base-ui/react/number-field';
 </NumberField.Root>;
 ```
 
+## Examples
+
+### Setting the input text imperatively
+
+`value` holds the parsed number, so it can't represent text that isn't a number yet.
+Typing `-1.5` passes through `-` and `-1.`, neither of which parses, and both leave `value` untouched.
+
+To drive those states, reach for `actionsRef`:
+
+```tsx title="Setting the input text imperatively"
+const actionsRef = React.useRef<NumberField.Root.Actions | null>(null);
+
+<NumberField.Root min={-100} actionsRef={actionsRef}>
+  {/* ... */}
+</NumberField.Root>;
+
+// Puts the field into a valid intermediate state that `value` cannot express.
+actionsRef.current.setInputValue('-');
+```
+
+The action can only reach states typing can reach.
+The string runs through the same character validation as a typed one, so anything the input would reject — stray letters, symbols the current `locale` and `format` don't use — is ignored and the field is left unchanged.
+Partial entries are allowed, which is the point: `'-'` and `'1.'` pass validation even though neither parses.
+
+The text itself is displayed as given, never formatted, and never clamped.
+`value` follows the text when it parses and is left alone when it doesn't, which is what lets `'-'` sit over an existing number without clearing it.
+An empty string clears `value`.
+
+Unlike the text, `value` is still validated: it is clamped to `min` and `max` unless `allowOutOfRange` is set.
+Setting `'999'` on a field with `max={10}` therefore shows `999` while `value` becomes `10`.
+
+Two things do set the action apart from typing, because the caller is the component's owner rather than a user:
+
+- It works while the field is `disabled` or `readOnly`, which gate user interaction.
+- Its changes are final rather than pending: `onValueChange` and `onValueCommitted` both run right away, with `reason: 'imperative-action'`. Waiting for blur would drop the change entirely when the input is never focused.
+
+The _text_ still behaves as an unsaved edit, exactly as if it had been typed: it survives re-renders and external `value` changes.
+Blurring the input ends the edit and re-arms formatting, so the display returns to the formatted `value` on the next render — whether or not that blur changed anything.
+
 ## API reference
 
 import { TypesNumberField } from './types';

docs/src/app/(docs)/react/components/page.mdx

@@ -1158,6 +1158,8 @@ A numeric input element with increment and decrement buttons, and a scrub area.
 - Sections:
   - Usage guidelines
   - Anatomy
+  - Examples
+    - Setting the input text imperatively
   - API reference
     - Root
     - ScrubArea
@@ -1168,7 +1170,7 @@ A numeric input element with increment and decrement buttons, and a scrub area.
     - Increment
 - Exports:
   - Number Field - Root
-    - Props: allowOutOfRange, allowWheelScrub, className, defaultValue, disabled, form, format, id, inputRef, largeStep, locale, max, min, name, onValueChange, onValueCommitted, readOnly, render, required, smallStep, snapOnStep, step, style, value
+    - Props: actionsRef, allowOutOfRange, allowWheelScrub, className, defaultValue, disabled, form, format, id, inputRef, largeStep, locale, max, min, name, onValueChange, onValueCommitted, readOnly, render, required, smallStep, snapOnStep, step, style, value
     - Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-scrubbing, data-touched, data-valid
   - Number Field - Input
     - Props: aria-roledescription, className, render, style
@@ -1188,7 +1190,7 @@ A numeric input element with increment and decrement buttons, and a scrub area.
   - Number Field - Increment
     - Props: className, nativeButton, render, style
     - Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-readonly, data-required, data-scrubbing, data-touched, data-valid
-- Types: NumberField.Decrement.Props, NumberField.Decrement.State, NumberField.Group.Props, NumberField.Group.State, NumberField.Increment.Props, NumberField.Increment.State, NumberField.Input.Props, NumberField.Input.State, NumberField.Root.ChangeEventDetails, NumberField.Root.ChangeEventReason, NumberField.Root.CommitEventDetails, NumberField.Root.CommitEventReason, NumberField.Root.Props, NumberField.Root.State, NumberField.ScrubArea.Props, NumberField.ScrubArea.State, NumberField.ScrubAreaCursor.Props, NumberField.ScrubAreaCursor.State
+- Types: NumberField.Decrement.Props, NumberField.Decrement.State, NumberField.Group.Props, NumberField.Group.State, NumberField.Increment.Props, NumberField.Increment.State, NumberField.Input.Props, NumberField.Input.State, NumberField.Root.Actions, NumberField.Root.ChangeEventDetails, NumberField.Root.ChangeEventReason, NumberField.Root.CommitEventDetails, NumberField.Root.CommitEventReason, NumberField.Root.Props, NumberField.Root.State, NumberField.ScrubArea.Props, NumberField.ScrubArea.State, NumberField.ScrubAreaCursor.Props, NumberField.ScrubAreaCursor.State
 
 </details>
 

packages/react/src/number-field/input/NumberFieldInput.tsx

@@ -12,12 +12,12 @@ import { useLabelableContext } from '../../internals/labelable-provider/Labelabl
 import {
   getNumberLocaleDetails,
   isNumeralChar,
+  isValidInputString,
   parseNumber,
   ANY_MINUS_RE,
   ANY_PLUS_RE,
   ANY_MINUS_DETECT_RE,
   ANY_PLUS_DETECT_RE,
-  FORMAT_CONTROL_DETECT_RE,
 } from '../utils/parse';
 import type { NumberFieldRootState } from '../root/NumberFieldRoot';
 import { stateAttributesMapping } from '../utils/stateAttributesMapping';
@@ -256,18 +256,7 @@ export const NumberFieldInput = React.forwardRef(function NumberFieldInput(
       // Update the input text immediately and only fire onValueChange if the typed value is
       // currently parseable into a number. This preserves good UX for IME
       // composition/partial input while still providing live numeric updates when possible.
-      const allowedNonNumericKeys = getAllowedNonNumericKeys();
-      const isValidCharacterString = Array.from(targetValue).every(
-        (ch) =>
-          isNumeralChar(ch) ||
-          ANY_MINUS_DETECT_RE.test(ch) ||
-          allowedNonNumericKeys.has(ch) ||
-          // Bidi/format controls are stripped by `parseNumber`; don't let them reject the string
-          // (RTL locales insert them around exponent/currency signs, e.g. scientific notation).
-          FORMAT_CONTROL_DETECT_RE.test(ch),
-      );
-
-      if (!isValidCharacterString) {
+      if (!isValidInputString(targetValue, getAllowedNonNumericKeys())) {
         return;
       }
 

packages/react/src/number-field/root/NumberFieldRoot.spec.tsx

@@ -1,3 +1,4 @@
+import * as React from 'react';
 import { expectType } from '#test-utils';
 import { NumberField } from '@base-ui/react/number-field';
 import { REASONS } from '../../internals/reasons';
@@ -72,3 +73,13 @@ const numberFieldEventNarrowing = (
     onValueCommitted={handleNumberFieldCommit}
   />
 );
+
+declare const numberFieldActionsRef: React.RefObject<NumberField.Root.Actions | null>;
+
+const numberFieldImperativeActions = <NumberField.Root actionsRef={numberFieldActionsRef} />;
+
+function assertNumberFieldActions(actions: NumberField.Root.Actions) {
+  actions.setInputValue('-');
+  // @ts-expect-error the raw text is a string, not a number
+  actions.setInputValue(5);
+}