Add portals implementation (#77)

* initial implementation of portals

* fix an issue with useValueSelector in <Portal>

* remove overreporting in case useValueSelector fails

* add more tests to check edge-case behaviours

* add basic support for <Fragment> in Portals

* fix Fragments not updating conditionally inside Portals

* add portals documentation

README.md

@@ -4,8 +4,6 @@
 [![Build Size](https://img.shields.io/bundlephobia/minzip/veles?label=bundle%20size)](https://bundlephobia.com/result?p=veles)
 [![Version](https://img.shields.io/npm/v/veles)](https://www.npmjs.com/package/veles)
 
-> This library is still in early stages, so the API is not 100% finalized
-
 `Veles` is a component-based performance-focused UI library. The main goal of this library is to provide a composable way to build highly interactive interfaces, which should be performant out of the box, as long as you follow the recommendations.
 
 ## Performance
@@ -55,7 +53,3 @@ This will render an input and will update the Text node dynamically, without re-
 - [Differences from other frameworks](https://bloomca.github.io/veles/frameworks-difference.html)
 
 There also a companion app ([veles-calendar-app](https://github.com/Bloomca/veles-calendar-app)), which is developed using Veles and is supposed to push it to the limits, identify the issues and ideally improve performance even more.
-
-### Features
-
-The library is under development, so some features are not available yet. Namely the TypeScript type inferring is not the best (although the library does support TypeScript), and Portals are not implemented yet.

docs/api/portals.md

@@ -0,0 +1,44 @@
+---
+layout: default
+title: Portals
+nav_order: 9
+parent: API
+---
+
+## Portals
+
+If you want to render a part of your application in a different part of the DOM, but want to maintain a logical structure in your components, you can use the `<Portal>` component. This components accepts two props:
+
+- `portalNode`: an HTML component where children will be mounted
+- `children`: any valid Veles children components
+
+## Example
+
+```jsx
+import { Portal, useState } from "veles";
+
+function Component() {
+  const showMenu = useState(false);
+  return (
+    <div
+      onMouseOver={() => showMenu.setState(true)}
+      onMouseOut={() => showMenu.setState(false)}
+    >
+      <h1>Title</h1>
+      {showMenu.useValue((shouldShow) =>
+        shouldShow ? (
+          <Portal portalNode={document.getElementById("portal")}>
+            <div>Component menu</div>
+          </Portal>
+        ) : null
+      )}
+    </div>
+  );
+}
+```
+
+This is a simple example of a menu which will be rendered when we hover over the component, but instead of the app DOM tree, it will use the node with `portal` ID.
+
+## Caveats
+
+If you render multiple Portals to the same `portalNode`, the initial order will be correct. However, if you render Portals conditionally, they will be added to the end of HTML node at the time of their rendering, not respecting the order in the markup. I don't consider it as a bug at the moment, feel free to create an issue if that causes problems.

docs/frameworks-difference.md

@@ -29,8 +29,4 @@ Overall, with the correct approach, both libraries should give you good interact
 
 ## Veles' drawbacks
 
-The library is pretty much in alpha state, and there are several missing concepts:
-
-- Portals
-- Not ideal TypeScript support
-- No server rendering (this one is not planned to be supported)
+`Veles` strives to provide a small core of features. For example, server rendering is not really planned to support, at least right now.