0
# Shape Components
1

2
Pre-built convenience components for common geometric shapes including circles, rectangles, and wedges/arcs. These components provide an easier way to create common shapes without manually constructing paths.
3

4
## Capabilities
5

6
### Circle Component
7

8
Pre-built circular shape component that creates perfect circles with a specified radius.
9

10
```javascript { .api }
11
/**
12
 * Circle component for drawing circles
13
 * Creates a circular path with the specified radius
14
 * @param props - Circle configuration and styling
15
 * @returns JSX.Element
16
 */
17
function Circle(props: {
18
  /** Radius of the circle in pixels */
19
  radius: number;
20
  /** Fill color (string) or fill object (gradient/pattern) */
21
  fill?: string | FillObject;
22
  /** Stroke color */
23
  stroke?: string;
24
  /** Stroke width in pixels */
25
  strokeWidth?: number;
26
  /** Stroke dash pattern */
27
  strokeDash?: number[];
28
  /** Stroke line cap style */
29
  strokeCap?: 'butt' | 'round' | 'square';
30
  /** Stroke line join style */
31
  strokeJoin?: 'miter' | 'round' | 'bevel';
32
  /** Opacity (0-1) */
33
  opacity?: number;
34
}): JSX.Element;
35
```
36

37
**Usage Examples:**
38

39
```javascript
40
import React from 'react';
41
import { Surface } from 'react-art';
42
import Circle from 'react-art/Circle';
43

44
// Basic circle
45
function BasicCircle() {
46
  return (
47
    <Surface width={100} height={100}>
48
      <Circle 
49
        radius={40} 
50
        fill="blue" 
51
        stroke="darkblue" 
52
        strokeWidth={2}
53
      />
54
    </Surface>
55
  );
56
}
57

58
// Multiple circles
59
function MultipleCircles() {
60
  return (
61
    <Surface width={200} height={100}>
62
      <Circle radius={30} fill="red" />
63
      <Circle radius={20} fill="green" />
64
      <Circle radius={10} fill="blue" />
65
    </Surface>
66
  );
67
}
68
```
69

70
### Rectangle Component
71

72
Pre-built rectangular shape component with support for rounded corners through radius properties.
73

74
```javascript { .api }
75
/**
76
 * Rectangle component for drawing rectangles and rounded rectangles
77
 * Creates rectangular paths with optional rounded corners
78
 * @param props - Rectangle configuration and styling
79
 * @returns JSX.Element
80
 */
81
function Rectangle(props: {
82
  /** Width of the rectangle in pixels */
83
  width: number;
84
  /** Height of the rectangle in pixels */
85
  height: number;
86
  /** Border radius for all corners (shorthand) */
87
  radius?: number;
88
  /** Border radius for top-left corner */
89
  radiusTopLeft?: number;
90
  /** Border radius for top-right corner */
91
  radiusTopRight?: number;
92
  /** Border radius for bottom-left corner */
93
  radiusBottomLeft?: number;
94
  /** Border radius for bottom-right corner */
95
  radiusBottomRight?: number;
96
  /** Fill color (string) or fill object (gradient/pattern) */
97
  fill?: string | FillObject;
98
  /** Stroke color */
99
  stroke?: string;
100
  /** Stroke width in pixels */
101
  strokeWidth?: number;
102
  /** Stroke dash pattern */
103
  strokeDash?: number[];
104
  /** Stroke line cap style */
105
  strokeCap?: 'butt' | 'round' | 'square';
106
  /** Stroke line join style */
107
  strokeJoin?: 'miter' | 'round' | 'bevel';
108
  /** Opacity (0-1) */
109
  opacity?: number;
110
}): JSX.Element;
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
import React from 'react';
117
import { Surface } from 'react-art';
118
import Rectangle from 'react-art/Rectangle';
119

120
// Basic rectangle
121
function BasicRectangle() {
122
  return (
123
    <Surface width={150} height={100}>
124
      <Rectangle 
125
        width={100} 
126
        height={60} 
127
        fill="green" 
128
        stroke="darkgreen" 
129
        strokeWidth={2}
130
      />
131
    </Surface>
132
  );
133
}
134

135
// Rounded rectangle
136
function RoundedRectangle() {
137
  return (
138
    <Surface width={150} height={100}>
139
      <Rectangle 
140
        width={100} 
141
        height={60} 
142
        radius={10}
143
        fill="orange" 
144
        stroke="darkorange" 
145
        strokeWidth={2}
146
      />
147
    </Surface>
148
  );
149
}
150

151
// Rectangle with individual corner radii
152
function CustomRoundedRectangle() {
153
  return (
154
    <Surface width={150} height={100}>
155
      <Rectangle 
156
        width={100} 
157
        height={60} 
158
        radiusTopLeft={20}
159
        radiusTopRight={5}
160
        radiusBottomLeft={5}
161
        radiusBottomRight={20}
162
        fill="purple" 
163
      />
164
    </Surface>
165
  );
166
}
167

168
// Handling negative dimensions
169
function FlexibleRectangle() {
170
  // Rectangle handles negative width/height by offsetting position
171
  return (
172
    <Surface width={150} height={100}>
173
      <Rectangle 
174
        width={-80}  // Negative width moves rectangle left
175
        height={50} 
176
        fill="red" 
177
      />
178
    </Surface>
179
  );
180
}
181
```
182

183
### Wedge Component
184

185
Pre-built wedge/arc component for creating pie chart segments, arcs, and circular sectors with configurable angles and radii.
186

187
```javascript { .api }
188
/**
189
 * Wedge component for drawing circles, wedges, arcs, and pie chart segments
190
 * Creates arc paths with configurable start/end angles and inner/outer radii
191
 * @param props - Wedge configuration and styling
192
 * @returns JSX.Element | null (returns null when startAngle equals endAngle)
193
 */
194
function Wedge(props: {
195
  /** Outer radius of the wedge in pixels */
196
  outerRadius: number;
197
  /** Starting angle in degrees (0 = 12 o'clock, increases clockwise) */
198
  startAngle: number;
199
  /** Ending angle in degrees (0 = 12 o'clock, increases clockwise) */
200
  endAngle: number;
201
  /** Inner radius in pixels (creates arc/donut shape when > 0) */
202
  innerRadius?: number;
203
  /** Fill color (string) or fill object (gradient/pattern) */
204
  fill?: string | FillObject;
205
  /** Stroke color */
206
  stroke?: string;
207
  /** Stroke width in pixels */
208
  strokeWidth?: number;
209
  /** Stroke dash pattern */
210
  strokeDash?: number[];
211
  /** Stroke line cap style */
212
  strokeCap?: 'butt' | 'round' | 'square';
213
  /** Stroke line join style */
214
  strokeJoin?: 'miter' | 'round' | 'bevel';
215
  /** Opacity (0-1) */
216
  opacity?: number;
217
}): JSX.Element | null;
218
```
219

220
**Usage Examples:**
221

222
```javascript
223
import React from 'react';
224
import { Surface } from 'react-art';
225
import Wedge from 'react-art/Wedge';
226

227
// Pie chart segment
228
function PieSlice() {
229
  return (
230
    <Surface width={150} height={150}>
231
      <Wedge 
232
        outerRadius={60}
233
        startAngle={0}
234
        endAngle={90}
235
        fill="blue"
236
        stroke="darkblue"
237
        strokeWidth={2}
238
      />
239
    </Surface>
240
  );
241
}
242

243
// Full circle using wedge
244
function CircleFromWedge() {
245
  return (
246
    <Surface width={150} height={150}>
247
      <Wedge 
248
        outerRadius={50}
249
        startAngle={0}
250
        endAngle={360}  // Full circle
251
        fill="green"
252
      />
253
    </Surface>
254
  );
255
}
256

257
// Donut/arc shape with inner radius
258
function DonutArc() {
259
  return (
260
    <Surface width={150} height={150}>
261
      <Wedge 
262
        outerRadius={60}
263
        innerRadius={30}  // Creates hollow center
264
        startAngle={45}
265
        endAngle={135}
266
        fill="orange"
267
        stroke="darkorange"
268
        strokeWidth={2}
269
      />
270
    </Surface>
271
  );
272
}
273

274
// Multiple wedges for pie chart
275
function PieChart() {
276
  const data = [
277
    { value: 30, color: 'red' },
278
    { value: 25, color: 'blue' },
279
    { value: 20, color: 'green' },
280
    { value: 25, color: 'orange' }
281
  ];
282
  
283
  let currentAngle = 0;
284
  
285
  return (
286
    <Surface width={200} height={200}>
287
      {data.map((slice, index) => {
288
        const startAngle = currentAngle;
289
        const endAngle = currentAngle + (slice.value / 100) * 360;
290
        currentAngle = endAngle;
291
        
292
        return (
293
          <Wedge
294
            key={index}
295
            outerRadius={80}
296
            startAngle={startAngle}
297
            endAngle={endAngle}
298
            fill={slice.color}
299
            stroke="white"
300
            strokeWidth={2}
301
          />
302
        );
303
      })}
304
    </Surface>
305
  );
306
}
307

308
// Arc with large angle (>180 degrees)
309
function LargeArc() {
310
  return (
311
    <Surface width={150} height={150}>
312
      <Wedge 
313
        outerRadius={60}
314
        innerRadius={40}
315
        startAngle={45}
316
        endAngle={315}  // 270 degree arc
317
        fill="purple"
318
      />
319
    </Surface>
320
  );
321
}
322
```
323

324
## Shape Component Behavior
325

326
### Angle System
327
- All angles are specified in degrees (not radians)
328
- 0 degrees = 12 o'clock position (top of circle)
329
- Angles increase clockwise: 90° = 3 o'clock, 180° = 6 o'clock, 270° = 9 o'clock
330
- Negative angles are supported and wrap around
331
- **Note**: Wedge component returns `null` when `startAngle` equals `endAngle` (zero-degree arc)
332

333
### Radius Handling
334
- All radius values are in pixels
335
- Rectangle radius values are clamped to prevent overlapping corners
336
- Wedge component sorts inner/outer radius automatically (smaller becomes inner)
337
- Negative radius values are treated as 0
338

339
### Path Generation
340
- All shape components internally create Path objects and render them using the base Shape component
341
- The generated paths are optimized for the specific shape type
342
- Complex shapes (like rounded rectangles) handle edge cases automatically
343

344
## Types
345

346
```javascript { .api }
347
// Fill object union type used by all shape components
348
type FillObject = LinearGradient | RadialGradient | Pattern;
349

350
// Stroke cap styles
351
type StrokeCap = 'butt' | 'round' | 'square';
352

353
// Stroke join styles  
354
type StrokeJoin = 'miter' | 'round' | 'bevel';
355
```