0
# Path API
1

2
Vector path construction using the ART Path class for creating custom shapes and complex vector graphics. The Path API provides a fluent interface for building vector paths that can be used with Shape components.
3

4
## Capabilities
5

6
### Path Class
7

8
The main Path class from the ART library provides methods for constructing vector paths through a fluent API.
9

10
```javascript { .api }
11
/**
12
 * Path class for vector path construction
13
 * Provides a fluent API for building complex vector paths
14
 * All methods return the Path instance for chaining
15
 */
16
class Path {
17
  /**
18
   * Move to a specific point without drawing
19
   * @param x - X coordinate to move to
20
   * @param y - Y coordinate to move to
21
   * @returns Path instance for chaining
22
   */
23
  moveTo(x: number, y: number): Path;
24

25
  /**
26
   * Move relative to current position without drawing
27
   * @param x - X offset from current position
28
   * @param y - Y offset from current position
29
   * @returns Path instance for chaining
30
   */
31
  move(x: number, y: number): Path;
32

33
  /**
34
   * Draw a line to a specific point
35
   * @param x - X coordinate to draw line to
36
   * @param y - Y coordinate to draw line to
37
   * @returns Path instance for chaining
38
   */
39
  lineTo(x: number, y: number): Path;
40

41
  /**
42
   * Draw a line relative to current position
43
   * @param x - X offset from current position
44
   * @param y - Y offset from current position
45
   * @returns Path instance for chaining
46
   */
47
  line(x: number, y: number): Path;
48

49
  /**
50
   * Draw an arc from current position
51
   * @param x - X offset to arc endpoint
52
   * @param y - Y offset to arc endpoint
53
   * @param rx - X radius of arc
54
   * @param ry - Y radius of arc (optional, defaults to rx)
55
   * @param large - Whether to use large arc sweep
56
   * @returns Path instance for chaining
57
   */
58
  arc(x: number, y: number, rx: number, ry?: number, large?: boolean): Path;
59

60
  /**
61
   * Draw a counter-clockwise arc from current position
62
   * @param x - X offset to arc endpoint
63
   * @param y - Y offset to arc endpoint
64
   * @param rx - X radius of arc
65
   * @param ry - Y radius of arc (optional, defaults to rx)
66
   * @param large - Whether to use large arc sweep
67
   * @returns Path instance for chaining
68
   */
69
  counterArc(x: number, y: number, rx: number, ry?: number, large?: boolean): Path;
70

71
  /**
72
   * Draw a cubic Bezier curve
73
   * @param cp1x - X coordinate of first control point
74
   * @param cp1y - Y coordinate of first control point
75
   * @param cp2x - X coordinate of second control point
76
   * @param cp2y - Y coordinate of second control point
77
   * @param x - X coordinate of end point
78
   * @param y - Y coordinate of end point
79
   * @returns Path instance for chaining
80
   */
81
  curveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): Path;
82

83
  /**
84
   * Draw a quadratic Bezier curve
85
   * @param cpx - X coordinate of control point
86
   * @param cpy - Y coordinate of control point
87
   * @param x - X coordinate of end point
88
   * @param y - Y coordinate of end point
89
   * @returns Path instance for chaining
90
   */
91
  quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): Path;
92

93
  /**
94
   * Close the current path by drawing a line to the starting point
95
   * @returns Path instance for chaining
96
   */
97
  close(): Path;
98

99
  /**
100
   * Reset the path, clearing all commands
101
   * @returns Path instance for chaining
102
   */
103
  reset(): Path;
104
}
105

106
/**
107
 * Create a new empty Path instance
108
 * @returns New Path instance
109
 */
110
function Path(): Path;
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
import React from 'react';
117
import { Surface, Shape, Path } from 'react-art';
118

119
// Basic triangle path
120
function Triangle() {
121
  const trianglePath = Path()
122
    .moveTo(50, 0)      // Start at top center
123
    .lineTo(100, 100)   // Line to bottom right
124
    .lineTo(0, 100)     // Line to bottom left
125
    .close();           // Close back to start
126

127
  return (
128
    <Surface width={100} height={100}>
129
      <Shape d={trianglePath} fill="blue" stroke="darkblue" strokeWidth={2} />
130
    </Surface>
131
  );
132
}
133

134
// Complex path with curves
135
function ComplexPath() {
136
  const path = Path()
137
    .moveTo(10, 50)                        // Start point
138
    .curveTo(10, 10, 90, 10, 90, 50)      // Cubic curve (top arc)
139
    .curveTo(90, 90, 10, 90, 10, 50)      // Cubic curve (bottom arc)
140
    .close();
141

142
  return (
143
    <Surface width={100} height={100}>
144
      <Shape d={path} fill="green" />
145
    </Surface>
146
  );
147
}
148

149
// Path with arcs
150
function ArcPath() {
151
  const path = Path()
152
    .moveTo(20, 50)         // Start on left
153
    .arc(60, 0, 30)         // Arc to right side
154
    .lineTo(80, 80)         // Line down
155
    .arc(-60, 0, 30)        // Arc back to left
156
    .close();               // Close path
157

158
  return (
159
    <Surface width={100} height={100}>
160
      <Shape d={path} fill="orange" stroke="red" strokeWidth={2} />
161
    </Surface>
162
  );
163
}
164
```
165

166
### Path Building Patterns
167

168
**Creating Custom Shapes:**
169

170
```javascript
171
import { Path } from 'react-art';
172

173
// Star shape
174
function createStarPath(centerX, centerY, outerRadius, innerRadius, points) {
175
  const path = Path();
176
  const angleStep = (Math.PI * 2) / (points * 2);
177
  
178
  for (let i = 0; i < points * 2; i++) {
179
    const angle = i * angleStep - Math.PI / 2;
180
    const radius = i % 2 === 0 ? outerRadius : innerRadius;
181
    const x = centerX + Math.cos(angle) * radius;
182
    const y = centerY + Math.sin(angle) * radius;
183
    
184
    if (i === 0) {
185
      path.moveTo(x, y);
186
    } else {
187
      path.lineTo(x, y);
188
    }
189
  }
190
  
191
  return path.close();
192
}
193

194
// Rounded rectangle path
195
function createRoundedRectPath(width, height, radius) {
196
  return Path()
197
    .moveTo(radius, 0)
198
    .lineTo(width - radius, 0)
199
    .arc(radius, radius, radius)
200
    .lineTo(width, height - radius)
201
    .arc(-radius, radius, radius)
202
    .lineTo(radius, height)
203
    .arc(-radius, -radius, radius)
204
    .lineTo(0, radius)
205
    .arc(radius, -radius, radius)
206
    .close();
207
}
208

209
// Heart shape path
210
function createHeartPath(size) {
211
  const path = Path();
212
  const x = size / 2;
213
  const y = size / 4;
214
  
215
  return path
216
    .moveTo(x, y)
217
    .curveTo(x, y - size/4, x - size/4, y - size/4, x - size/4, y)
218
    .curveTo(x - size/4, y + size/8, x, y + size/2, x, y + size/2)
219
    .curveTo(x, y + size/2, x + size/4, y + size/8, x + size/4, y)
220
    .curveTo(x + size/4, y - size/4, x, y - size/4, x, y)
221
    .close();
222
}
223
```
224

225
### Path Manipulation
226

227
**Combining Paths:**
228

229
```javascript
230
// Multiple disconnected shapes in one path
231
function MultiShapePath() {
232
  const path = Path()
233
    // First shape - circle
234
    .moveTo(20, 20)
235
    .arc(20, 0, 10)
236
    .arc(-20, 0, 10)
237
    .close()
238
    // Second shape - square (disconnected)
239
    .moveTo(60, 10)
240
    .lineTo(80, 10)
241
    .lineTo(80, 30)
242
    .lineTo(60, 30)
243
    .close();
244

245
  return (
246
    <Surface width={100} height={50}>
247
      <Shape d={path} fill="purple" />
248
    </Surface>
249
  );
250
}
251

252
// Path with holes
253
function PathWithHole() {
254
  const path = Path()
255
    // Outer rectangle
256
    .moveTo(10, 10)
257
    .lineTo(90, 10)
258
    .lineTo(90, 90)
259
    .lineTo(10, 90)
260
    .close()
261
    // Inner rectangle (hole) - drawn in reverse direction
262
    .moveTo(30, 30)
263
    .lineTo(30, 70)
264
    .lineTo(70, 70)
265
    .lineTo(70, 30)
266
    .close();
267

268
  return (
269
    <Surface width={100} height={100}>
270
      <Shape d={path} fill="teal" />
271
    </Surface>
272
  );
273
}
274
```
275

276
### Advanced Path Techniques
277

278
**Smooth Curves:**
279

280
```javascript
281
// Smooth wavy line using quadratic curves
282
function WavyPath() {
283
  const path = Path()
284
    .moveTo(0, 50);
285

286
  // Create wave pattern
287
  for (let x = 0; x < 200; x += 40) {
288
    path.quadraticCurveTo(x + 20, 20, x + 40, 50)
289
        .quadraticCurveTo(x + 60, 80, x + 80, 50);
290
  }
291

292
  return (
293
    <Surface width={200} height={100}>
294
      <Shape d={path} fill="none" stroke="blue" strokeWidth={3} />
295
    </Surface>
296
  );
297
}
298

299
// Bezier curve examples
300
function BezierCurves() {
301
  const path = Path()
302
    // Cubic bezier curve
303
    .moveTo(10, 80)
304
    .curveTo(40, 10, 60, 10, 90, 80)
305
    // Quadratic bezier curve
306
    .moveTo(110, 80)
307
    .quadraticCurveTo(125, 10, 140, 80);
308

309
  return (
310
    <Surface width={150} height={100}>
311
      <Shape d={path} fill="none" stroke="red" strokeWidth={2} />
312
    </Surface>
313
  );
314
}
315
```
316

317
### Path Coordinate System
318

319
- **Origin**: (0, 0) is at the top-left of the Surface
320
- **X-axis**: Increases from left to right
321
- **Y-axis**: Increases from top to bottom
322
- **Units**: All coordinates are in pixels
323
- **Relative vs Absolute**: 
324
  - `moveTo`, `lineTo`, `curveTo`, `quadraticCurveTo` use absolute coordinates
325
  - `move`, `line`, `arc`, `counterArc` use relative coordinates from current position
326

327
### Methods Used by React ART Components
328

329
The following Path methods are actively used by React ART's built-in components (Circle, Rectangle, Wedge):
330

331
**Core methods used:**
332
- `moveTo()` - Used for positioning
333
- `move()` - Used for relative positioning 
334
- `line()` - Used for straight line segments
335
- `arc()` - Used for curved segments (both 3-param and 5-param versions)
336
- `counterArc()` - Used for reverse direction arcs
337
- `close()` - Used to close paths
338

339
**Additional methods available:**
340
- `lineTo()`, `curveTo()`, `quadraticCurveTo()`, `reset()` - Part of the ART Path API but not used by built-in components
341

342
### Path Performance
343

344
- Paths are immutable - each method call returns a new path
345
- Complex paths with many segments can impact rendering performance
346
- Consider simplifying paths for better performance
347
- Reuse path objects when possible rather than recreating them
348

349
## Types
350

351
```javascript { .api }
352
// Path class from ART library
353
class Path {
354
  // All path construction methods return Path for chaining
355
}
356

357
// Path factory function
358
function Path(): Path;
359
```