0
# Core Components
1

2
Essential building blocks for creating vector graphics with React ART, including the Surface container, basic shapes, text rendering, and grouping functionality.
3

4
## Capabilities
5

6
### Surface Component
7

8
The root container component that creates the ART rendering surface. All React ART graphics must be rendered within a Surface component.
9

10
```javascript { .api }
11
/**
12
 * Root container component for ART graphics
13
 * Creates the rendering surface (Canvas/SVG/VML based on environment)
14
 * @param props - Surface configuration
15
 * @returns JSX.Element
16
 */
17
function Surface(props: {
18
  /** Width of the surface in pixels */
19
  width: number;
20
  /** Height of the surface in pixels */
21
  height: number;
22
  /** CSS style object */
23
  style?: object;
24
  /** CSS class name */
25
  className?: string;
26
  /** Accessibility key */
27
  accessKey?: string;
28
  /** Whether element is draggable */
29
  draggable?: boolean;
30
  /** ARIA role */
31
  role?: string;
32
  /** Tab index for keyboard navigation */
33
  tabIndex?: number;
34
  /** Title attribute */
35
  title?: string;
36
  /** Child React ART components */
37
  children?: React.ReactNode;
38
}): JSX.Element;
39
```
40

41
**Usage Examples:**
42

43
```javascript
44
import React from 'react';
45
import { Surface, Shape, Path } from 'react-art';
46

47
// Basic surface
48
function BasicDrawing() {
49
  return (
50
    <Surface width={300} height={200}>
51
      {/* Your graphics here */}
52
    </Surface>
53
  );
54
}
55

56
// Surface with styling
57
function StyledDrawing() {
58
  return (
59
    <Surface 
60
      width={400} 
61
      height={300}
62
      style={{ border: '1px solid #ccc', margin: '10px' }}
63
      className="my-drawing"
64
    >
65
      {/* Your graphics here */}
66
    </Surface>
67
  );
68
}
69
```
70

71
### Shape Component
72

73
Basic vector shape component that renders custom paths. This is the fundamental building block for all vector graphics in React ART.
74

75
```javascript { .api }
76
/**
77
 * Basic vector shape component
78
 * Renders a vector path with optional styling
79
 * @param props - Shape configuration and styling
80
 * @returns JSX.Element
81
 */
82
function Shape(props: {
83
  /** Path data defining the shape geometry */
84
  d: Path;
85
  /** Fill color (string) or fill object (gradient/pattern) */
86
  fill?: string | FillObject;
87
  /** Stroke color */
88
  stroke?: string;
89
  /** Stroke width in pixels */
90
  strokeWidth?: number;
91
  /** Stroke dash pattern */
92
  strokeDash?: number[];
93
  /** Stroke line cap style */
94
  strokeCap?: 'butt' | 'round' | 'square';
95
  /** Stroke line join style */
96
  strokeJoin?: 'miter' | 'round' | 'bevel';
97
  /** Opacity (0-1) */
98
  opacity?: number;
99
}): JSX.Element;
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
import { Surface, Shape, Path } from 'react-art';
106

107
// Custom triangle shape
108
function Triangle() {
109
  const trianglePath = Path()
110
    .moveTo(50, 0)
111
    .lineTo(100, 100)
112
    .lineTo(0, 100)
113
    .close();
114

115
  return (
116
    <Surface width={100} height={100}>
117
      <Shape 
118
        d={trianglePath} 
119
        fill="red" 
120
        stroke="black" 
121
        strokeWidth={2} 
122
      />
123
    </Surface>
124
  );
125
}
126

127
// Complex path with styling
128
function StyledShape() {
129
  const path = Path()
130
    .moveTo(10, 10)
131
    .lineTo(90, 10)
132
    .arc(0, 80, 10)
133
    .lineTo(10, 90)
134
    .arc(0, -80, 10)
135
    .close();
136

137
  return (
138
    <Surface width={100} height={100}>
139
      <Shape 
140
        d={path}
141
        fill="blue"
142
        stroke="darkblue"
143
        strokeWidth={3}
144
        strokeCap="round"
145
        strokeJoin="round"
146
        opacity={0.8}
147
      />
148
    </Surface>
149
  );
150
}
151
```
152

153
### Group Component
154

155
Container component for grouping multiple shapes together. Groups can be used to apply transformations to multiple elements or organize graphics hierarchically.
156

157
```javascript { .api }
158
/**
159
 * Container for grouping multiple shapes
160
 * Allows applying transformations and styling to multiple children
161
 * @param props - Group configuration
162
 * @returns JSX.Element
163
 */
164
function Group(props: {
165
  /** Child React ART components */
166
  children?: React.ReactNode;
167
  /** Opacity applied to all children (0-1) */
168
  opacity?: number;
169
  /** Transform object for scaling, rotation, translation */
170
  transform?: Transform;
171
}): JSX.Element;
172
```
173

174
**Usage Examples:**
175

176
```javascript
177
import { Surface, Group, Shape, Path } from 'react-art';
178

179
// Grouping multiple shapes
180
function GroupedShapes() {
181
  const circle = Path().moveTo(0, 10).arc(20, 0, 10).arc(-20, 0, 10).close();
182
  const square = Path().moveTo(30, 0).lineTo(50, 0).lineTo(50, 20).lineTo(30, 20).close();
183

184
  return (
185
    <Surface width={100} height={50}>
186
      <Group opacity={0.7}>
187
        <Shape d={circle} fill="red" />
188
        <Shape d={square} fill="blue" />
189
      </Group>
190
    </Surface>
191
  );
192
}
193
```
194

195
### Text Component
196

197
Component for rendering text within ART graphics. Provides access to text metrics and positioning.
198

199
```javascript { .api }
200
/**
201
 * Text rendering component
202
 * Renders text with optional styling and exposes metrics
203
 * @param props - Text configuration and styling
204
 * @returns JSX.Element
205
 */
206
function Text(props: {
207
  /** Text content to render */
208
  children: string;
209
  /** Font family */
210
  font?: string;
211
  /** Font size in pixels */
212
  fontSize?: number;
213
  /** Font weight */
214
  fontWeight?: string | number;
215
  /** Font style */
216
  fontStyle?: 'normal' | 'italic';
217
  /** Text alignment */
218
  alignment?: string;
219
  /** Text fill color */
220
  fill?: string;
221
  /** Text stroke color */
222
  stroke?: string;
223
  /** Text stroke width */
224
  strokeWidth?: number;
225
}): JSX.Element;
226

227
// Text component instance properties (accessible via ref)
228
interface TextInstance {
229
  /** Computed text height */
230
  height: number;
231
  /** Computed text width */
232
  width: number;
233
  /** Text x position */
234
  x: number;
235
  /** Text y position */
236
  y: number;
237
}
238
```
239

240
**Usage Examples:**
241

242
```javascript
243
import React, { useRef, useEffect } from 'react';
244
import { Surface, Text } from 'react-art';
245

246
// Basic text rendering
247
function BasicText() {
248
  return (
249
    <Surface width={200} height={100}>
250
      <Text font="Arial" fontSize={16} fill="black">
251
        Hello, React ART!
252
      </Text>
253
    </Surface>
254
  );
255
}
256

257
// Text with metrics access
258
function TextWithMetrics() {
259
  const textRef = useRef(null);
260

261
  useEffect(() => {
262
    if (textRef.current) {
263
      console.log('Text dimensions:', {
264
        width: textRef.current.width,
265
        height: textRef.current.height
266
      });
267
    }
268
  }, []);
269

270
  return (
271
    <Surface width={300} height={100}>
272
      <Text 
273
        ref={textRef}
274
        font="Arial" 
275
        fontSize={20} 
276
        fontWeight="bold"
277
        fill="darkblue"
278
      >
279
        Measured Text
280
      </Text>
281
    </Surface>
282
  );
283
}
284
```
285

286
### ClippingRectangle Component
287

288
Component for defining clipping regions to mask graphics content.
289

290
```javascript { .api }
291
/**
292
 * Clipping rectangle component
293
 * Defines a rectangular clipping region for child elements
294
 * @param props - Clipping configuration
295
 * @returns JSX.Element
296
 */
297
function ClippingRectangle(props: {
298
  /** Width of clipping rectangle */
299
  width: number;
300
  /** Height of clipping rectangle */
301
  height: number;
302
  /** X position of clipping rectangle */
303
  x?: number;
304
  /** Y position of clipping rectangle */
305
  y?: number;
306
  /** Child components to be clipped */
307
  children?: React.ReactNode;
308
}): JSX.Element;
309
```
310

311
**Usage Examples:**
312

313
```javascript
314
import { Surface, ClippingRectangle, Shape, Path } from 'react-art';
315

316
// Clipping a large shape
317
function ClippedShape() {
318
  const largePath = Path()
319
    .moveTo(0, 0)
320
    .lineTo(200, 0)
321
    .lineTo(200, 200)
322
    .lineTo(0, 200)
323
    .close();
324

325
  return (
326
    <Surface width={100} height={100}>
327
      <ClippingRectangle width={50} height={50}>
328
        <Shape d={largePath} fill="green" />
329
      </ClippingRectangle>
330
    </Surface>
331
  );
332
}
333
```
334

335
## Types
336

337
```javascript { .api }
338
// Fill object union type
339
type FillObject = LinearGradient | RadialGradient | Pattern;
340

341
// Transform class from ART library
342
class Transform {
343
  // Matrix transformation methods
344
}
345

346
// Path class from ART library
347
class Path {
348
  moveTo(x: number, y: number): Path;
349
  lineTo(x: number, y: number): Path;
350
  arc(x: number, y: number, radius: number): Path;
351
  close(): Path;
352
}
353
```