0
# Core React API
1

2
Primary React compatibility layer providing all essential React APIs including component system, virtual DOM, lifecycle methods, and rendering functions.
3

4
## Capabilities
5

6
### Component System
7

8
Base classes for creating React-compatible components with full lifecycle support.
9

10
```javascript { .api }
11
/**
12
 * Base component class with state management and lifecycle methods
13
 */
14
class Component {
15
  /**
16
   * Component constructor
17
   * @param {object} props - Component properties
18
   * @param {object} context - Component context
19
   */
20
  constructor(props, context);
21
  
22
  /**
23
   * Update component state and trigger re-render
24
   * @param {object|function} partialState - State updates or updater function
25
   * @param {function} callback - Optional callback after state update
26
   */
27
  setState(partialState, callback);
28
  
29
  /**
30
   * Force component to re-render immediately
31
   * @param {function} callback - Optional callback after render
32
   */
33
  forceUpdate(callback);
34
  
35
  /**
36
   * Render method - must be implemented by subclasses
37
   * @returns {VNode} Virtual DOM node
38
   */
39
  render();
40
  
41
  // Lifecycle methods
42
  componentWillMount();
43
  componentDidMount();
44
  componentWillReceiveProps(nextProps);
45
  shouldComponentUpdate(nextProps, nextState);
46
  componentWillUpdate(nextProps, nextState);
47
  componentDidUpdate(prevProps, prevState);
48
  componentWillUnmount();
49
  
50
  // Instance properties
51
  props;
52
  state;
53
  context;
54
}
55

56
/**
57
 * Component with built-in shallow comparison for shouldComponentUpdate
58
 */
59
class PureComponent extends Component {
60
  /**
61
   * Automatically implements shallow comparison for props and state
62
   * @param {object} nextProps - Next props
63
   * @param {object} nextState - Next state
64
   * @returns {boolean} Whether component should update
65
   */
66
  shouldComponentUpdate(nextProps, nextState);
67
}
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
import { Component, PureComponent } from 'preact-compat';
74

75
// Class component with state
76
class Counter extends Component {
77
  constructor(props) {
78
    super(props);
79
    this.state = { count: 0 };
80
  }
81
  
82
  increment = () => {
83
    this.setState(prevState => ({ count: prevState.count + 1 }));
84
  };
85
  
86
  render() {
87
    return (
88
      <div>
89
        <p>Count: {this.state.count}</p>
90
        <button onClick={this.increment}>Increment</button>
91
      </div>
92
    );
93
  }
94
}
95

96
// Pure component for performance
97
class DisplayItem extends PureComponent {
98
  render() {
99
    return <div>{this.props.text}</div>;
100
  }
101
}
102
```
103

104
### Element Creation
105

106
Functions for creating and manipulating virtual DOM elements.
107

108
```javascript { .api }
109
/**
110
 * Create a virtual DOM element
111
 * @param {string|function} type - Element type or component
112
 * @param {object} props - Element properties
113
 * @param {...any} children - Child elements
114
 * @returns {VNode} Virtual DOM node
115
 */
116
function createElement(type, props, ...children);
117

118
/**
119
 * Clone an existing element with new props and children
120
 * @param {VNode} element - Element to clone
121
 * @param {object} props - Additional props to merge
122
 * @param {...any} children - New children (replaces existing)
123
 * @returns {VNode} Cloned virtual DOM node
124
 */
125
function cloneElement(element, props, ...children);
126

127
/**
128
 * Create a factory function for a specific element type
129
 * @param {string|function} type - Element type or component
130
 * @returns {function} Factory function that creates elements of the specified type
131
 */
132
function createFactory(type);
133

134
/**
135
 * Check if an object is a valid React element
136
 * @param {any} object - Object to validate
137
 * @returns {boolean} True if valid React element
138
 */
139
function isValidElement(object);
140

141
/**
142
 * Create a portal for rendering outside the component tree
143
 * @param {VNode} vnode - Virtual DOM node to render
144
 * @param {Element} container - DOM container to render into
145
 * @returns {VNode} Portal component
146
 */
147
function createPortal(vnode, container);
148
```
149

150
**Usage Examples:**
151

152
```javascript
153
import { createElement, cloneElement, createFactory, isValidElement, createPortal } from 'preact-compat';
154

155
// Create elements
156
const element = createElement('div', { className: 'container' }, 'Hello World');
157
const component = createElement(MyComponent, { prop: 'value' });
158

159
// Clone with modifications
160
const cloned = cloneElement(element, { id: 'main' }, 'New Content');
161

162
// Create factory
163
const div = createFactory('div');
164
const divElement = div({ className: 'box' }, 'Content');
165

166
// Create portal (render outside component tree)
167
const modal = createPortal(
168
  createElement('div', { className: 'modal' }, 'Modal content'),
169
  document.body
170
);
171

172
// Validate elements
173
console.log(isValidElement(element)); // true
174
console.log(isValidElement('string')); // false
175
```
176

177
### Rendering Functions
178

179
Functions for rendering components to the DOM and managing component lifecycle.
180

181
```javascript { .api }
182
/**
183
 * Render a component into a DOM container
184
 * @param {VNode} vnode - Virtual DOM node to render
185
 * @param {Element} parent - DOM container element
186
 * @param {Element} merge - Optional element to merge with
187
 * @returns {Component} Rendered component instance
188
 */
189
function render(vnode, parent, merge);
190

191
/**
192
 * Hydrate server-rendered markup with a component (alias for render)
193
 * @param {VNode} vnode - Virtual DOM node to hydrate
194
 * @param {Element} parent - DOM container element
195
 * @returns {Component} Hydrated component instance
196
 */
197
function hydrate(vnode, parent);
198

199
/**
200
 * Find the DOM node for a component instance
201
 * @param {Component} component - Component instance
202
 * @returns {Element} DOM node
203
 */
204
function findDOMNode(component);
205

206
/**
207
 * Unmount and remove a component from a DOM container
208
 * @param {Element} container - DOM container element
209
 * @returns {boolean} True if component was unmounted
210
 */
211
function unmountComponentAtNode(container);
212

213
/**
214
 * Render component into a container with context (unstable API)
215
 * @param {VNode} vnode - Virtual DOM node to render
216
 * @param {Element} container - DOM container element
217
 * @param {function} callback - Render callback
218
 * @returns {Component} Rendered component instance  
219
 */
220
function unstable_renderSubtreeIntoContainer(parentComponent, vnode, container, callback);
221

222
/**
223
 * Batch multiple state updates (no-op in Preact)
224
 * @param {function} callback - Function containing state updates
225
 */
226
function unstable_batchedUpdates(callback);
227
```
228

229
**Usage Examples:**
230

231
```javascript
232
import { render, hydrate, findDOMNode, unmountComponentAtNode } from 'preact-compat';
233

234
// Render to DOM
235
const container = document.getElementById('root');
236
const component = render(<App />, container);
237

238
// Hydrate server-rendered content
239
hydrate(<App />, container);
240

241
// Find DOM node
242
const domNode = findDOMNode(component);
243

244
// Unmount component
245
unmountComponentAtNode(container);
246
```
247

248
### Version Constant
249

250
```javascript { .api }
251
/**
252
 * React version string for library compatibility
253
 * @type {string}
254
 */
255
const version = '15.1.0';
256
```
257

258
**Usage:**
259

260
```javascript
261
import { version } from 'preact-compat';
262
console.log(version); // '15.1.0'
263
```
264

265
### Internal/Advanced Utilities
266

267
```javascript { .api }
268
/**
269
 * Object extension utility (alias for extend function)
270
 * @param {object} base - Base object to extend
271
 * @param {...object} props - Objects to merge into base
272
 * @returns {object} Extended object
273
 */
274
const __spread;
275
```
276

277
**Usage:**
278

279
```javascript
280
import { __spread } from 'preact-compat';
281

282
const obj1 = { a: 1, b: 2 };
283
const obj2 = { c: 3 };
284
const extended = __spread(obj1, obj2); // { a: 1, b: 2, c: 3 }
285
```
286

287
## Types
288

289
```javascript { .api }
290
interface ComponentLifecycle<P, S> {
291
  componentWillMount?(): void;
292
  componentDidMount?(): void;
293
  componentWillReceiveProps?(nextProps: P, nextContext: any): void;
294
  shouldComponentUpdate?(nextProps: P, nextState: S, nextContext: any): boolean;
295
  componentWillUpdate?(nextProps: P, nextState: S, nextContext: any): void;
296
  componentDidUpdate?(prevProps: P, prevState: S, prevContext: any): void;
297
  componentWillUnmount?(): void;
298
}
299

300
interface ComponentConstructor<P = {}, S = {}> {
301
  new (props: P, context?: any): Component<P, S>;
302
}
303

304
type StatelessComponent<P = {}> = (props: P, context?: any) => VNode<any>;
305

306
type ComponentType<P = {}> = ComponentConstructor<P> | StatelessComponent<P>;
307
```