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/input.md
+++ b/docs/form-inputs/input.md
@@ -0,0 +1,95 @@
+# Input Component Documentation
+
+## Overview
+
+The Input component represents a fundamental UI element within the toolkit, supporting multiple visual presentations, dimensions, and operational states.
+
+## Props Configuration
+
+### InputRoot Properties
+
+| Property | Type | Default | Purpose |
+|----------|------|---------|---------|
+| `size` | `'sm' \| 'base' \| 'lg'` | `'base'` | Adjusts input dimensions |
+| `state` | `'default' \| 'error'` | `'default'` | Visual feedback styling |
+| `side` | `'left' \| 'center' \| 'right'` | — | Text positioning and cursor placement |
+| `inputClassName` | `string` | — | Custom classes for inner input element |
+| Standard input attributes | `ComponentProps<'input'>` | — | Native HTML input properties |
+
+### InputSlot Properties
+
+| Property | Type | Default | Purpose |
+|----------|------|---------|---------|
+| `side` | `'left' \| 'right'` | `'left'` | Slot positioning |
+| Standard div attributes | `ComponentProps<'div'>` | — | Native HTML div properties |
+
+## Type Definitions
+
+```typescript
+interface InputRootProps extends ComponentProps<"div">, VariantProps<typeof inputVariants> {
+  state?: "default" | "error";
+  side?: "left" | "right" | "center";
+  asChild?: boolean;
+  inputClassName?: string;
+  size?: "sm" | "base" | "lg";
+}
+
+interface InputSlotProps extends ComponentProps<"div"> {
+  side?: "left" | "right";
+}
+```
+
+## Text Alignment Options
+
+The component accommodates three alignment directions: left (default), center, and right. Slot components enable prefixes and suffixes through positioned elements.
+
+## State Management
+
+**Default State**: Standard appearance for typical interactions
+
+**Error State**: Visual indication for validation failures and user feedback
+
+**Disabled State**: Prevents user interaction and modification
+
+## Input Type Examples
+
+- **Text Input**: Standard character input
+- **Number Input**: Numeric values with optional currency symbols
+- **Password Input**: Masked character display
+- **Email Input**: Email-specific validation
+- **Search Input**: Search functionality with supplementary icons
+
+## Interactive Examples
+
+### Character Counter Implementation
+
+```javascript
+const [value, setValue] = useState('');
+const [count, setCount] = useState(0);
+
+return (
+  <InputRoot
+    size="sm"
+    placeholder="Type something..."
+    value={value}
+    onChange={(e) => {
+      setValue(e.target.value);
+      setCount(e.target.value.length);
+    }}
+  />
+);
+```
+
+### Calculation Feature
+
+Combines price and quantity inputs for real-time total computation:
+
+```javascript
+const [price, setPrice] = useState('');
+const [quantity, setQuantity] = useState('');
+const total = (parseFloat(price) || 0) * (parseInt(quantity) || 0);
+```
+
+### Form Validation Pattern
+
+Implements error detection and submission handling through state management and conditional styling based on validation results.
--- a/docs/form-inputs/number-inputs.md
+++ b/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.
--- a/docs/form-inputs/playground.md
+++ b/docs/form-inputs/playground.md
@@ -0,0 +1,32 @@
+# Form Inputs Playground
+
+This page appears to be a **demonstration/showcase page** for the Vuer UIKit form components rather than a documentation article with detailed explanations.
+
+## Available Components Displayed
+
+The playground showcases interactive examples of:
+
+- **Text Input** - with various label positioning options (left, top, with sub-labels)
+- **Toggle** - switch control
+- **Input Groups** - both vertical and horizontal layouts
+- **Textarea** - multi-line text input
+- **Selectors** - dropdown/select components
+- **Number Inputs** - including:
+  - Steps (with configurable increments)
+  - Interval controls
+- **Radio Groups** - both vertical and horizontal layouts
+- **Preset Inputs** - with values like 10, 20, 30
+- **Color Picker** - with hexadecimal input field
+
+## Component Variations
+
+Each component type is presented with multiple configurations:
+
+- Different label arrangements
+- Horizontal and vertical orientations
+- Optional sublabel/helper text
+- Various state examples
+
+## Documentation Structure
+
+This playground appears designed as an **interactive testing ground** rather than a reference guide. The actual implementation details and code examples would be found in the linked documentation pages for each specific input type (Input, Number Inputs, Specialized Inputs).
--- 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