Initial commit

2025-11-30 09:05:04 +08:00
commit 7afdd6601b
69 changed files with 9552 additions and 0 deletions
--- a/docs/form-inputs/specialized-inputs.md
+++ b/docs/form-inputs/specialized-inputs.md
@@ -0,0 +1,115 @@
+# Specialized Input Components Documentation
+
+## Overview
+
+Pre-configured numeric input components for common measurement units, angles, and multi-dimensional data types.
+
+## Common Props
+
+All specialized input components share these properties:
+
+| Prop | Type | Default | Purpose |
+|------|------|---------|---------|
+| `value` | `number` or `number[]` | — | Current value(s) |
+| `onChange` / `onValuesChange` | `(value) => void` | — | Callback when values change |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size variant |
+| `step` | `number` | varies | Step size for drag modifications |
+
+### Angle Input Additional Props
+
+| Prop | Type | Default | Component |
+|------|------|---------|-----------|
+| `display` | `'rad' \| 'deg' \| 'pi'` | `'rad'` | `RadInput`, `EulerRadInput`, `PresetsRadInput` |
+| `presets` | `[number, number, number]` | — | `PresetsRadInput` |
+
+## Measurement Unit Inputs
+
+Components with built-in unit suffixes:
+
+- **CmInput**: centimeters (cm)
+- **InchInput**: inches (in)
+- **TimeInput**: seconds (s)
+
+Example usage:
+```javascript
+const [length, setLength] = useState(150);
+<CmInput size="sm" value={length} onChange={setLength} />
+```
+
+## Angular Measurement Inputs
+
+### DegInput and RadInput
+
+**DegInput** displays degrees (°), while **RadInput** offers flexible display formats:
+
+| Mode | Display | Example |
+|------|---------|---------|
+| `"rad"` | Radians | 1.57 rad |
+| `"deg"` | Degrees | 90° |
+| `"pi"` | π multiples | 0.5π |
+
+The underlying value remains in radians regardless of display format.
+
+```javascript
+const [radians, setRadians] = useState(Math.PI / 2);
+<RadInput value={radians} onChange={setRadians} display="deg" />
+```
+
+### PresetsRadInput
+
+Combines **RadInput** with preset buttons for common angles:
+
+```javascript
+const [angle, setAngle] = useState(0);
+const commonAngles = [0, Math.PI/2, Math.PI];
+
+<PresetsRadInput
+  presets={commonAngles}
+  value={angle}
+  onChange={setAngle}
+  display="deg"
+  size="sm"
+/>
+```
+
+## Integer Input
+
+**IntInput** restricts values to integers only:
+
+```javascript
+const [count, setCount] = useState(42);
+<IntInput size="sm" value={count} onChange={setCount} />
+```
+
+## Vector Inputs
+
+Multi-dimensional components for 3D data:
+
+- **Vec3Input**: x, y, z coordinates
+- **EulerInput**: x°, y°, z° (degrees)
+- **EulerRadInput**: x, y, z (radians with flexible display)
+- **QuaternionInput**: w, x, y, z components
+
+```javascript
+const [position, setPosition] = useState([1, 0, 0]);
+<Vec3Input value={position} onValuesChange={setPosition} size="sm" />
+
+const [rotationRad, setRotationRad] = useState([0, Math.PI/2, Math.PI]);
+<EulerRadInput value={rotationRad} onValuesChange={setRotationRad} display="deg" />
+```
+
+### Euler Angle Components Comparison
+
+| Component | Storage | Display Options |
+|-----------|---------|-----------------|
+| `EulerInput` | Degrees | Always degrees |
+| `EulerRadInput` | Radians | `"rad"`, `"deg"`, `"pi"` |
+
+## Drag Interaction Features
+
+All specialized inputs support advanced drag interactions inherited from InputNumbers:
+
+- **Vertical drag**: Select multiple inputs
+- **Horizontal drag**: Modify selected values
+- **Shift + drag**: 5× step multiplier
+- **Alt + drag**: 0.2× step multiplier