0
# Vector Operations
1

2
2D vector mathematics with full support for React Native Reanimated SharedValues, providing a foundation for position-based animations and transformations.
3

4
## Capabilities
5

6
### Vector Type
7

8
Core vector interface supporting generic types, commonly used with numbers or SharedValues.
9

10
```typescript { .api }
11
/**
12
 * 2D vector with x and y components
13
 * @template T - Type of vector components (number, SharedValue<number>, etc.)
14
 */
15
interface Vector<T = number> {
16
  x: T;
17
  y: T;
18
}
19
```
20

21
### Vector Creation
22

23
```typescript { .api }
24
/**
25
 * Create a vector with optional x and y components
26
 * @param x - X component (default: 0)
27
 * @param y - Y component (default: x or 0)
28
 * @returns Vector with specified components
29
 */
30
function vec2<T>(x?: T, y?: T): Vector<T>;
31

32
/**
33
 * Vector creation utilities
34
 */
35
const vec: {
36
  create: typeof vec2;
37
};
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { vec2, vec } from "react-native-redash";
44

45
// Create vectors with numbers
46
const origin = vec2(0, 0);
47
const position = vec2(100, 200);
48
const symmetric = vec2(50); // Creates { x: 50, y: 50 }
49

50
// Alternative syntax
51
const center = vec.create(150, 150);
52
```
53

54
### Vector Hooks
55

56
React hooks for creating vectors with Reanimated SharedValues.
57

58
```typescript { .api }
59
/**
60
 * Create a vector of SharedValues for animated positions
61
 * @param x1 - Initial x value (default: 0)
62
 * @param y1 - Initial y value (default: x1 or 0)
63
 * @returns Vector with SharedValue components
64
 */
65
function useVector(
66
  x1?: number,
67
  y1?: number
68
): Vector<Animated.SharedValue<number>>;
69
```
70

71
**Usage Examples:**
72

73
```typescript
74
import { useVector } from "react-native-redash";
75
import { useAnimatedStyle, useAnimatedGestureHandler } from "react-native-reanimated";
76
import { PanGestureHandler } from "react-native-gesture-handler";
77

78
const position = useVector(0, 0);
79
const velocity = useVector();
80

81
// Use in gesture handler
82
const gestureHandler = useAnimatedGestureHandler({
83
  onStart: () => {
84
    // Reset position
85
    position.x.value = 0;
86
    position.y.value = 0;
87
  },
88
  onActive: (event) => {
89
    // Update position during gesture
90
    position.x.value = event.translationX;
91
    position.y.value = event.translationY;
92
  },
93
  onEnd: (event) => {
94
    // Store final velocity
95
    velocity.x.value = event.velocityX;
96
    velocity.y.value = event.velocityY;
97
  }
98
});
99

100
// Use in animated styles
101
const animatedStyle = useAnimatedStyle(() => ({
102
  transform: [
103
    { translateX: position.x.value },
104
    { translateY: position.y.value }
105
  ]
106
}));
107
```
108

109
### Vector Operations with Other Modules
110

111
Vectors are used throughout the library for coordinate transformations, path operations, and matrix calculations.
112

113
```typescript
114
import { 
115
  useVector, 
116
  canvas2Cartesian, 
117
  cartesian2Polar,
118
  transformOrigin 
119
} from "react-native-redash";
120
import { useAnimatedStyle } from "react-native-reanimated";
121

122
const center = useVector(150, 150);
123
const position = useVector(100, 100);
124

125
const animatedStyle = useAnimatedStyle(() => {
126
  // Convert coordinates
127
  const cartesian = canvas2Cartesian(
128
    { x: position.x.value, y: position.y.value },
129
    { x: center.x.value, y: center.y.value }
130
  );
131
  
132
  // Convert to polar
133
  const polar = cartesian2Polar(cartesian);
134
  
135
  // Apply transformation with origin
136
  const transform = transformOrigin(
137
    { x: center.x.value, y: center.y.value },
138
    [{ rotate: `${polar.theta}rad` }]
139
  );
140
  
141
  return { transform };
142
});
143
```
144

145
### Integration with Transform Utilities
146

147
```typescript { .api }
148
/**
149
 * Hook for translation animations using vector of SharedValues
150
 * @param vector - Vector with SharedValue components
151
 * @returns Animated style with translation transform
152
 */
153
function useTranslation(vector: Vector<Animated.SharedValue<number>>): {
154
  transform: { translateX: number; translateY: number }[];
155
};
156
```
157

158
**Complete Example:**
159

160
```typescript
161
import React from "react";
162
import { View } from "react-native";
163
import { 
164
  useVector, 
165
  useTranslation,
166
  vec2 
167
} from "react-native-redash";
168
import Animated, {
169
  useSharedValue,
170
  useAnimatedGestureHandler,
171
  useAnimatedStyle,
172
  withSpring
173
} from "react-native-reanimated";
174
import { PanGestureHandler } from "react-native-gesture-handler";
175

176
export const DraggableBox = () => {
177
  const position = useVector(0, 0);
178
  const offset = useVector(0, 0);
179
  
180
  // Alternative: Use the translation hook
181
  const translationStyle = useTranslation(position);
182
  
183
  const gestureHandler = useAnimatedGestureHandler({
184
    onStart: () => {
185
      offset.x.value = position.x.value;
186
      offset.y.value = position.y.value;
187
    },
188
    onActive: (event) => {
189
      position.x.value = offset.x.value + event.translationX;
190
      position.y.value = offset.y.value + event.translationY;
191
    },
192
    onEnd: () => {
193
      // Spring back to center
194
      const center = vec2(0, 0);
195
      position.x.value = withSpring(center.x);
196
      position.y.value = withSpring(center.y);
197
    }
198
  });
199
  
200
  // Custom animated style (alternative to useTranslation)
201
  const animatedStyle = useAnimatedStyle(() => ({
202
    transform: [
203
      { translateX: position.x.value },
204
      { translateY: position.y.value }
205
    ]
206
  }));
207
  
208
  return (
209
    <PanGestureHandler onGestureEvent={gestureHandler}>
210
      <Animated.View 
211
        style={[
212
          { width: 100, height: 100, backgroundColor: 'blue' },
213
          animatedStyle // or translationStyle
214
        ]} 
215
      />
216
    </PanGestureHandler>
217
  );
218
};
219
```
220

221
## Types
222

223
All vector operations maintain type safety when working with different component types:
224

225
```typescript { .api }
226
// Vector with numbers
227
const numericVector: Vector<number> = { x: 10, y: 20 };
228

229
// Vector with SharedValues (animated)
230
const animatedVector: Vector<Animated.SharedValue<number>> = {
231
  x: useSharedValue(10),
232
  y: useSharedValue(20)
233
};
234

235
// Vector with mixed types (if needed)
236
const mixedVector: Vector<Animated.Adaptable<number>> = {
237
  x: 10,
238
  y: useSharedValue(20)
239
};
240
```