0
# Element Creation and Management
1

2
Core virtual DOM element creation and manipulation functionality for building Rax applications. These functions are the foundation of all Rax applications and provide React-compatible element creation.
3

4
## Capabilities
5

6
### Create Element
7

8
Creates virtual DOM elements that can be rendered by Rax. This is the core function for building component trees.
9

10
```javascript { .api }
11
/**
12
 * Creates a virtual DOM element
13
 * @param type - Element type (string for DOM elements, function/class for components)
14
 * @param config - Props object containing element properties
15
 * @param children - Child elements (variadic arguments)
16
 * @returns RaxElement virtual DOM element
17
 */
18
function createElement(type, config, ...children);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
import { createElement } from 'rax';
25

26
// DOM elements
27
const divElement = createElement('div', { className: 'container' }, 'Hello World');
28
const buttonElement = createElement('button', { 
29
  onClick: () => alert('clicked'),
30
  disabled: false
31
}, 'Click Me');
32

33
// Component elements
34
function MyComponent(props) {
35
  return createElement('span', null, props.text);
36
}
37

38
const componentElement = createElement(MyComponent, { text: 'Hello' });
39

40
// Multiple children
41
const listElement = createElement('ul', null,
42
  createElement('li', { key: '1' }, 'Item 1'),
43
  createElement('li', { key: '2' }, 'Item 2'),
44
  createElement('li', { key: '3' }, 'Item 3')
45
);
46

47
// With JSX (requires transpilation)
48
// const jsxElement = <div className="container">Hello World</div>;
49
```
50

51
### Fragment
52

53
Component for grouping multiple children without adding extra DOM nodes. Useful for returning multiple elements from a component.
54

55
```javascript { .api }
56
/**
57
 * Fragment component for grouping children without wrapper elements
58
 * @param props - Props object with children property
59
 * @returns props.children directly (no wrapper element created)
60
 */
61
function Fragment(props);
62
```
63

64
**Usage Examples:**
65

66
```javascript
67
import { createElement, Fragment } from 'rax';
68

69
// Using Fragment to group elements
70
function MyComponent() {
71
  return createElement(Fragment, null,
72
    createElement('h1', null, 'Title'),
73
    createElement('p', null, 'Description'),
74
    createElement('button', null, 'Action')
75
  );
76
}
77

78
// With JSX (requires transpilation)
79
// function MyComponent() {
80
//   return (
81
//     <>
82
//       <h1>Title</h1>
83
//       <p>Description</p>
84
//       <button>Action</button>
85
//     </>
86
//   );
87
// }
88
```
89

90
### Create Ref
91

92
Creates a ref object for accessing DOM elements or component instances directly.
93

94
```javascript { .api }
95
/**
96
 * Creates a ref object for element access
97
 * @returns RefObject with current property initially set to null
98
 */
99
function createRef();
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
import { createElement, createRef, Component } from 'rax';
106

107
class MyComponent extends Component {
108
  constructor(props) {
109
    super(props);
110
    this.inputRef = createRef();
111
  }
112

113
  focusInput = () => {
114
    if (this.inputRef.current) {
115
      this.inputRef.current.focus();
116
    }
117
  }
118

119
  render() {
120
    return createElement('div', null,
121
      createElement('input', { ref: this.inputRef, type: 'text' }),
122
      createElement('button', { onClick: this.focusInput }, 'Focus Input')
123
    );
124
  }
125
}
126
```
127

128
### Forward Ref
129

130
Forwards refs through component boundaries, allowing parent components to access child component DOM elements.
131

132
```javascript { .api }
133
/**
134
 * Creates a component that forwards refs to child elements
135
 * @param render - Render function that receives (props, ref) arguments
136
 * @returns Component function with ref forwarding capability
137
 */
138
function forwardRef(render);
139
```
140

141
**Usage Examples:**
142

143
```javascript
144
import { createElement, forwardRef, createRef } from 'rax';
145

146
// Create a component that forwards refs
147
const FancyButton = forwardRef((props, ref) => {
148
  return createElement('button', {
149
    ref: ref,
150
    className: 'fancy-button',
151
    ...props
152
  }, props.children);
153
});
154

155
// Use the ref-forwarding component
156
function App() {
157
  const buttonRef = createRef();
158
  
159
  const handleClick = () => {
160
    if (buttonRef.current) {
161
      buttonRef.current.focus();
162
    }
163
  };
164

165
  return createElement('div', null,
166
    createElement(FancyButton, { 
167
      ref: buttonRef,
168
      onClick: handleClick 
169
    }, 'Click me'),
170
    createElement('button', { onClick: handleClick }, 'Focus other button')
171
  );
172
}
173
```
174

175
### Memo
176

177
Memoizes components to prevent unnecessary re-renders when props haven't changed. Similar to React.memo.
178

179
```javascript { .api }
180
/**
181
 * Memoizes a component to optimize rendering performance
182
 * @param type - Component function to memoize
183
 * @param compare - Optional custom comparison function for props
184
 * @returns Memoized component that only re-renders when props change
185
 */
186
function memo(type, compare);
187
```
188

189
**Usage Examples:**
190

191
```javascript
192
import { createElement, memo, useState } from 'rax';
193

194
// Basic memoization
195
const ExpensiveComponent = memo(function ExpensiveComponent(props) {
196
  console.log('ExpensiveComponent rendered');
197
  return createElement('div', null, `Value: ${props.value}`);
198
});
199

200
// Custom comparison function
201
const CustomMemoComponent = memo(
202
  function CustomMemoComponent(props) {
203
    return createElement('div', null, `Name: ${props.user.name}`);
204
  },
205
  (prevProps, nextProps) => {
206
    // Only re-render if user.name changes
207
    return prevProps.user.name === nextProps.user.name;
208
  }
209
);
210

211
// Using memoized components
212
function App() {
213
  const [count, setCount] = useState(0);
214
  const [name, setName] = useState('John');
215

216
  return createElement('div', null,
217
    createElement(ExpensiveComponent, { value: 42 }), // Won't re-render when count changes
218
    createElement('button', { 
219
      onClick: () => setCount(count + 1) 
220
    }, `Count: ${count}`),
221
    createElement(CustomMemoComponent, { 
222
      user: { name, age: 30 } 
223
    })
224
  );
225
}
226
```
227

228
## Types
229

230
```javascript { .api }
231
// Element type definition
232
interface RaxElement {
233
  type: string | Function;
234
  key: string | null;
235
  ref: Function | RefObject | null;
236
  props: Object;
237
  _owner: Component | null;
238
}
239

240
// Ref object type
241
interface RefObject<T> {
242
  current: T | null;
243
}
244

245
// Component type for memo and forwardRef
246
type ComponentType<P = {}> = Function;
247

248
// Comparison function type for memo
249
type MemoCompareFunction<P> = (prevProps: P, nextProps: P) => boolean;
250

251
// Forward ref render function type
252
type ForwardRefRenderFunction<P, T> = (props: P, ref: RefObject<T>) => RaxElement;
253
```