0
# RC Input Number
1

2
RC Input Number is a React component that provides a controlled numeric input field with built-in increment/decrement controls, high-precision decimal arithmetic, and extensive customization options. It supports keyboard navigation, mouse wheel interaction, formatting, validation, and accessibility features.
3

4
## Package Information
5

6
- **Package Name**: @rc-component/input-number
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @rc-component/input-number`
10

11
## Core Imports
12

13
```typescript
14
import InputNumber from "@rc-component/input-number";
15
import type { InputNumberProps, ValueType, InputNumberRef } from "@rc-component/input-number";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const InputNumber = require("@rc-component/input-number");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import React from "react";
28
import InputNumber from "@rc-component/input-number";
29

30
// Basic controlled component
31
function BasicExample() {
32
  const [value, setValue] = React.useState<number | null>(10);
33
  
34
  return (
35
    <InputNumber
36
      value={value}
37
      onChange={setValue}
38
      min={0}
39
      max={100}
40
      step={1}
41
    />
42
  );
43
}
44

45
// With formatting and precision
46
function FormattedExample() {
47
  const [value, setValue] = React.useState<string>("12.34");
48
  
49
  return (
50
    <InputNumber
51
      stringMode
52
      value={value}
53
      onChange={setValue}
54
      precision={2}
55
      decimalSeparator=","
56
      formatter={(value) => `$ ${value}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}
57
      parser={(value) => value?.replace(/\$\s?|(,*)/g, '') || ''}
58
    />
59
  );
60
}
61
```
62

63
## Architecture
64

65
RC Input Number is built around several key components:
66

67
- **Main Component**: The `InputNumber` component wraps the internal input with BaseInput for consistent styling
68
- **Internal Input**: `InternalInputNumber` handles the core numeric logic and state management
69
- **Step Handler**: `StepHandler` component provides the increment/decrement buttons with long-press support
70
- **Decimal System**: Uses `@rc-component/mini-decimal` for high-precision arithmetic avoiding floating-point errors
71
- **Hooks**: Custom hooks for cursor management (`useCursor`) and frame scheduling (`useFrame`)
72

73
## Capabilities
74

75
### Core Input Component
76

77
The main InputNumber component that provides controlled numeric input with validation and formatting.
78

79
```typescript { .api }
80
/**
81
 * React input number component with step controls and high-precision arithmetic
82
 */
83
declare const InputNumber: <T extends ValueType = ValueType>(
84
  props: React.PropsWithChildren<InputNumberProps<T>> & {
85
    ref?: React.Ref<InputNumberRef>;
86
  }
87
) => React.ReactElement;
88

89
interface InputNumberProps<T extends ValueType = ValueType>
90
  extends Omit<
91
    React.InputHTMLAttributes<HTMLInputElement>,
92
    'value' | 'defaultValue' | 'onInput' | 'onChange' | 'prefix' | 'suffix'
93
  > {
94
  /** value will show as string */
95
  stringMode?: boolean;
96
  /** Default value for uncontrolled mode */
97
  defaultValue?: T;
98
  /** Current value for controlled mode */
99
  value?: T | null;
100
  /** CSS class prefix (default: 'rc-input-number') */
101
  prefixCls?: string;
102
  /** Additional CSS class name */
103
  className?: string;
104
  /** Inline styles */
105
  style?: React.CSSProperties;
106
  /** Minimum allowed value */
107
  min?: T;
108
  /** Maximum allowed value */
109
  max?: T;
110
  /** Step increment/decrement value (default: 1) */
111
  step?: ValueType;
112
  /** Tab index for keyboard navigation */
113
  tabIndex?: number;
114
  /** Show/hide step control buttons (default: true) */
115
  controls?: boolean;
116
  /** Prefix content inside input */
117
  prefix?: React.ReactNode;
118
  /** Suffix content inside input */
119
  suffix?: React.ReactNode;
120
  /** Content before input wrapper */
121
  addonBefore?: React.ReactNode;
122
  /** Content after input wrapper */
123
  addonAfter?: React.ReactNode;
124
  /** Custom class names for different parts */
125
  classNames?: {
126
    input?: string;
127
    affixWrapper?: string;
128
    prefix?: string;
129
    suffix?: string;
130
    groupWrapper?: string;
131
  };
132
  /** Custom up button content */
133
  upHandler?: React.ReactNode;
134
  /** Custom down button content */
135
  downHandler?: React.ReactNode;
136
  /** Enable keyboard arrow key control (default: true) */
137
  keyboard?: boolean;
138
  /** Enable mouse wheel to change value */
139
  changeOnWheel?: boolean;
140
  /** Parse display value to validate number */
141
  parser?: (displayValue: string | undefined) => T;
142
  /** Transform value to display value show in input */
143
  formatter?: (value: T | undefined, info: { userTyping: boolean; input: string }) => string;
144
  /** Number of decimal places to display */
145
  precision?: number;
146
  /** Custom decimal separator character */
147
  decimalSeparator?: string;
148
  /** Input text change callback */
149
  onInput?: (text: string) => void;
150
  /** Value change callback */
151
  onChange?: (value: T | null) => void;
152
  /** Enter key press handler */
153
  onPressEnter?: React.KeyboardEventHandler<HTMLInputElement>;
154
  /** Step change callback with detailed information */
155
  onStep?: (value: T, info: { 
156
    offset: ValueType; 
157
    type: 'up' | 'down'; 
158
    emitter: 'handler' | 'keyboard' | 'wheel' 
159
  }) => void;
160
  /** Trigger change on blur event (default: true) */
161
  changeOnBlur?: boolean;
162
}
163
```
164

165
### Component Reference Interface
166

167
Interface for accessing the component methods via ref.
168

169
```typescript { .api }
170
interface InputNumberRef extends HTMLInputElement {
171
  /** Focus the input with optional focus options */
172
  focus: (options?: InputFocusOptions) => void;
173
  /** Blur the input */
174
  blur: () => void;
175
  /** Access to native DOM element */
176
  nativeElement: HTMLElement;
177
}
178

179
interface InputFocusOptions {
180
  /** Whether to prevent scroll when focusing */
181
  preventScroll?: boolean;
182
  /** Cursor selection range */
183
  cursor?: {
184
    start?: number;
185
    end?: number;
186
  };
187
}
188
```
189

190
### Value Types
191

192
Core type definitions for numeric values and validation.
193

194
```typescript { .api }
195
/** Union type for numeric values supporting both strings and numbers */
196
type ValueType = string | number;
197
```
198

199
### Step Control Features
200

201
The component includes built-in step controls with the following behavior:
202

203
- **Click**: Single step increment/decrement
204
- **Hold**: Continuous stepping with initial delay (600ms) then rapid intervals (200ms)
205
- **Keyboard**: Arrow up/down keys for stepping (disabled with `keyboard={false}`)
206
- **Shift + Keyboard**: 10x step values when holding shift key
207
- **Mouse Wheel**: Optional wheel support via `changeOnWheel` prop
208
- **Mobile**: Step controls automatically hidden on mobile devices
209

210
### Formatting and Parsing
211

212
Advanced formatting capabilities for display and input parsing:
213

214
```typescript
215
// Custom currency formatter
216
const currencyFormatter = (value: string | undefined) => {
217
  if (!value) return '';
218
  return `$ ${value}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
219
};
220

221
const currencyParser = (value: string | undefined) => {
222
  return value?.replace(/\$\s?|(,*)/g, '') || '';
223
};
224

225
<InputNumber
226
  formatter={currencyFormatter}
227
  parser={currencyParser}
228
  precision={2}
229
/>
230
```
231

232
### High-Precision Arithmetic
233

234
The component uses `@rc-component/mini-decimal` internally to avoid JavaScript floating-point precision issues:
235

236
- Supports arbitrary precision decimal calculations
237
- Safe handling of very large numbers
238
- Consistent decimal arithmetic operations
239
- No floating-point precision errors in stepping operations
240

241
### Validation and Constraints
242

243
Built-in validation features:
244

245
- **Min/Max Validation**: Automatic clamping to specified range
246
- **Step Validation**: Values automatically aligned to step increments
247
- **Format Validation**: Parser validation for custom input formats
248
- **Range Indicators**: CSS classes applied for out-of-range values
249
- **Accessibility**: ARIA attributes for screen readers (aria-valuemin, aria-valuemax, aria-valuenow)
250

251
### Event Handling
252

253
Comprehensive event system for different interaction types:
254

255
```typescript
256
<InputNumber
257
  onChange={(value) => {
258
    console.log('Value changed:', value);
259
  }}
260
  onStep={(value, info) => {
261
    console.log('Stepped:', value, 'via', info.emitter, info.type);
262
  }}
263
  onInput={(text) => {
264
    console.log('Raw input:', text);
265
  }}
266
  onPressEnter={(event) => {
267
    console.log('Enter pressed');
268
  }}
269
/>
270
```
271

272
### String Mode Operation
273

274
For applications requiring string-based numeric handling:
275

276
```typescript
277
<InputNumber
278
  stringMode
279
  value="123.456789"
280
  precision={6}
281
  onChange={(stringValue) => {
282
    // Value returned as string: "123.456789"
283
    console.log(typeof stringValue); // "string"
284
  }}
285
/>
286
```
287

288
This mode is useful for:
289
- High-precision financial calculations
290
- Integration with string-based APIs
291
- Avoiding JavaScript number type limitations
292
- Maintaining exact decimal representation