junk: WIP

Author: rschristian

content/en/guide/v10/api-reference.md

@@ -13,40 +13,11 @@ This page serves as a quick overview over all exported functions.
 
 ---
 
-## Component
+## preact
 
-`Component` is a base class that can be extended to create stateful Preact components.
-
-Rather than being instantiated directly, Components are managed by the renderer and created as-needed.
-
-```js
-import { Component } from 'preact';
-
-class MyComponent extends Component {
-	// (see below)
-}
-```
-
-### Component.render(props, state)
-
-All components must provide a `render()` function. The render function is passed the component's current props and state, and should return a Virtual DOM Element (typically a JSX "element"), an Array, or `null`.
-
-```jsx
-import { Component } from 'preact';
+The `preact` module provides only essential functionality, such as rendering components and creating VDOM elements. Additional utilities are provided by the various subpath exports, such as `preact/hooks`, `preact/compat`, `preact/debug`, etc.
 
-class MyComponent extends Component {
-	render(props, state) {
-		// props is the same as this.props
-		// state is the same as this.state
-
-		return <h1>Hello, {props.name}!</h1>;
-	}
-}
-```
-
-To learn more about components and how they can be used, check out the [Components Documentation](/guide/v10/components).
-
-## render()
+### render()
 
 `render(virtualDom, containerNode, [replaceNode])`
 
@@ -112,7 +83,9 @@ render(
 
 > ⚠️ The `replaceNode`-argument will be removed with Preact `v11`. It introduces too many edge cases and bugs which need to be accounted for in the rest of Preact's source code. If you still need this functionality, we recommend using [`preact-root-fragment`](/guide/v10/preact-root-fragment), a small helper library that provides similar functionality. It is compatible with both Preact `v10` and `v11`.
 
-## hydrate()
+### hydrate()
+
+`hydrate(virtualDom, containerNode)`
 
 If you've already pre-rendered or server-side-rendered your application to HTML, Preact can bypass most rendering work when loading in the browser. This can be enabled by switching from `render()` to `hydrate()`, which skips most diffing while still attaching event listeners and setting up your component tree. This works only when used in conjunction with pre-rendering or [Server-Side Rendering](/guide/v10/server-side-rendering).
 
@@ -124,7 +97,7 @@ const Foo = () => <div>foo</div>;
 hydrate(<Foo />, document.getElementById('container'));
 ```
 
-## h() / createElement()
+### h() / createElement()
 
 `h(type, props, ...children)`
 
@@ -150,34 +123,40 @@ h('div', { id: 'foo' }, h('span', null, 'Hello!'));
 // <div id="foo"><span>Hello!</span></div>
 ```
 
-## toChildArray
+### Component
 
-This helper function converts a `props.children` value to a flattened Array regardless of its structure or nesting. If `props.children` is already an array, a copy is returned. This function is useful in cases where `props.children` may not be an array, which can happen with certain combinations of static and dynamic expressions in JSX.
+`Component` is a base class that can be extended to create stateful Preact components.
 
-For Virtual DOM Elements with a single child, `props.children` is a reference to the child. When there are multiple children, `props.children` is always an Array. The `toChildArray` helper provides a way to consistently handle all cases.
+Rather than being instantiated directly, Components are managed by the renderer and created as-needed.
 
-```jsx
-import { toChildArray } from 'preact';
+```js
+import { Component } from 'preact';
 
-function Foo(props) {
-	const count = toChildArray(props.children).length;
-	return <div>I have {count} children</div>;
+class MyComponent extends Component {
+	// (see below)
 }
+```
 
-// props.children is "bar"
-render(<Foo>bar</Foo>, container);
+#### Component.render(props, state)
 
-// props.children is [<p>A</p>, <p>B</p>]
-render(
-	<Foo>
-		<p>A</p>
-		<p>B</p>
-	</Foo>,
-	container
-);
+All components must provide a `render()` function. The render function is passed the component's current props and state, and should return a Virtual DOM Element (typically a JSX "element"), an Array, or `null`.
+
+```jsx
+import { Component } from 'preact';
+
+class MyComponent extends Component {
+	render(props, state) {
+		// props is the same as this.props
+		// state is the same as this.state
+
+		return <h1>Hello, {props.name}!</h1>;
+	}
+}
 ```
 
-## cloneElement
+To learn more about components and how they can be used, check out the [Components Documentation](/guide/v10/components).
+
+### cloneElement
 
 `cloneElement(virtualElement, props, ...children)`
 
@@ -197,17 +176,23 @@ render(
 // <a href="/" target="_blank">home</a>
 ```
 
-## createContext
+### createContext
+
+`createContext(initialState)`
+
+Creates a new Context object which can be used to pass data through the component tree without passing down props through each level.
 
 See the section in the [Context documentation](/guide/v10/context#createcontext).
 
-## createRef
+### createRef
 
-Provides a way to reference an element or component once it has been rendered.
+`createRef(initialValue)`
+
+Creates a new Ref object that acts as a stable, local value that will persist across renders. This can be used to store DOM references, component instances, or any arbitrary value.
 
 See the [References documentation](/guide/v10/refs#createref) for more details.
 
-## Fragment
+### Fragment
 
 A special kind of component that can have children, but is not rendered as a DOM element.
 Fragments make it possible to return multiple sibling children without needing to wrap them in a DOM container:
@@ -231,3 +216,68 @@ render(
 //   <div>C</div>
 // </div>
 ```
+
+### toChildArray
+
+`toChildArray(componentChildren)`
+
+This helper function converts a `props.children` value to a flattened Array regardless of its structure or nesting. If `props.children` is already an array, a copy is returned. This function is useful in cases where `props.children` may not be an array, which can happen with certain combinations of static and dynamic expressions in JSX.
+
+For Virtual DOM Elements with a single child, `props.children` is a reference to the child. When there are multiple children, `props.children` is always an Array. The `toChildArray` helper provides a way to consistently handle all cases.
+
+```jsx
+import { toChildArray } from 'preact';
+
+function Foo(props) {
+	const count = toChildArray(props.children).length;
+	return <div>I have {count} children</div>;
+}
+
+// props.children is "bar"
+render(<Foo>bar</Foo>, container);
+
+// props.children is [<p>A</p>, <p>B</p>]
+render(
+	<Foo>
+		<p>A</p>
+		<p>B</p>
+	</Foo>,
+	container
+);
+```
+
+### isValidElement
+
+`isValidElement(virtualElement)`
+
+Checks if the provided value is a valid Preact VNode.
+
+### options
+
+See the [Option Hooks](/guide/v10/options) documentation for more details.
+
+## preact/hooks
+
+See the [Hooks](/guide/v10/hooks) documentation for more details. Please note that the page includes a number of "Compat-specific hooks" that are not available from `preact/hooks`, only `preact/compat`.
+
+## preact/compat
+
+`preact/compat` is our compatibility layer that allows you to use Preact as a drop-in replacement for React. It provides all of the APIs of `preact` and `preact/hooks`, whilst also providing a few more to match the React API.
+
+### Children
+
+### createPortal
+
+### memo
+
+### forwardRef
+
+### StrictMode
+
+Preact does not implement `StrictMode` and so the `StrictMode` component is just an alias of [`Fragment`](#Fragment). You can pass children to it, but for all debugging checks and warnings, you should instead use [`preact/debug`](#preactdebug).
+
+### Suspense
+
+### lazy
+
+## preact/debug