Initial commit

docs/form-inputs/number-inputs.md

@@ -0,0 +1,154 @@
+# Number Inputs Documentation
+
+## Overview
+
+A comprehensive collection of numeric input components with drag-to-modify functionality, specialized inputs for measurements, angles, and multi-dimensional data types.
+
+## Basic Number Input (InputRoot)
+
+The fundamental numeric input uses InputRoot with `etype="number"`. Mouse dragging is not supported.
+
+```jsx
+const [value, setValue] = useState(42.5);
+
+<InputRoot
+  size="sm"
+  type="number"
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  placeholder="Enter a number"
+/>
+```
+
+## InputNumbers (Single)
+
+Advanced numeric input component with drag-to-modify functionality and enhanced UX.
+
+```jsx
+const [value, setValue] = useState([42.5]);
+
+<InputNumbers
+  size="sm"
+  value={value}
+  onValuesChange={setValue}
+  step={0.1}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number[]` | — | Array of numbers for each input |
+| `onValuesChange` | `(value: number[]) => void` | — | Callback when values change |
+| `step` | `number` | `0.1` | Step size for drag modifications |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size variant |
+| `side` | `'left' \| 'center' \| 'right'` | `'left'` | Text alignment |
+| `prefix` | `ReactNode[]` | — | Array of prefix labels/units for each input |
+| `suffix` | `ReactNode[]` | — | Array of suffix labels/units for each input |
+
+### Types
+
+```typescript
+interface InputNumbersProps extends Pick<InputRootProps, "size" | "side"> {
+  step?: number;
+  value: number[];
+  prefix?: ReactNode[];
+  suffix?: ReactNode[];
+  onValuesChange?: (value: Array<number>) => void;
+}
+```
+
+## Text Alignment Options
+
+InputNumbers supports three text alignment variants:
+
+**Left aligned (default)**
+```jsx
+const [leftValue, setLeftValue] = useState([123.45]);
+<InputNumbers
+  size="sm"
+  value={leftValue}
+  onValuesChange={setLeftValue}
+  side="left"
+/>
+```
+
+**Center aligned**
+```jsx
+const [centerValue, setCenterValue] = useState([123.45]);
+<InputNumbers
+  size="sm"
+  value={centerValue}
+  onValuesChange={setCenterValue}
+  side="center"
+/>
+```
+
+**Right aligned**
+```jsx
+const [rightValue, setRightValue] = useState([123.45]);
+<InputNumbers
+  size="sm"
+  value={rightValue}
+  onValuesChange={setRightValue}
+  side="right"
+/>
+```
+
+## Prefix and Suffix Usage
+
+Add context to inputs with prefixes or suffixes:
+
+**With prefix ($)**
+```jsx
+const [price, setPrice] = useState([299.99]);
+<InputNumbers
+  size="sm"
+  value={price}
+  onValuesChange={setPrice}
+  prefix={["$"]}
+  step={0.01}
+/>
+```
+
+**With suffix (kg)**
+```jsx
+const [weight, setWeight] = useState([75.5]);
+<InputNumbers
+  size="sm"
+  value={weight}
+  onValuesChange={setWeight}
+  suffix={["kg"]}
+  step={0.1}
+/>
+```
+
+## Grouped Inputs
+
+Multiple numeric inputs grouped together with coordinated drag selection for multi-dimensional data:
+
+```jsx
+const [position, setPosition] = useState([10.5, 20.3, -5.8]);
+<InputNumbers
+  size="sm"
+  value={position}
+  onValuesChange={setPosition}
+  prefix={["x", "y", "z"]}
+  step={0.1}
+/>
+```
+
+## Drag Interaction Features
+
+All InputNumbers components support advanced drag interactions:
+
+- **Vertical drag**: Select multiple inputs by dragging up/down
+- **Horizontal drag**: Modify selected values by dragging left/right
+- **Modifier keys**:
+  - `Shift` + drag: 5x step size
+  - `Alt` + drag: 0.2x step size
+
+## Related Components
+
+For specialized input components with built-in units and advanced data types, see the Specialized Input Components documentation.