Neverland 🌈🦄

 

!Cosmic Timetraveler
^{Photo by Cosmic Timetraveler on Unsplash}

$3

Please ask questions in the dedicated discussions repository, to help the community around this project grow ♥

---

Update if you're looking for something even smaller than _neverland_, don't miss µland!

- - -

Hooks via lighterhtml

``js
import {Component, render, html, useState} from 'neverland';

const Counter = Component((initialState) => {
const [count, setCount] = useState(initialState);
return html
setCount(count + 1)}>
Count: ${count}
;
});

// basic example, show two independent counters
render(document.body, html

`js
// if you don't need hooks, you don't need to wrap components
const LinkLi = ({text, href}, highlighted) => html

// some container with some click logic that uses hooks: $(wrap it)
const Links = $((items) => {
const [clicked, changeState] = useState(-1);
const onclick = useCallback(event => {
const li = event.target.closest('li');
changeState(
// changeState accordingly to the clicked index
[].indexOf.call(event.currentTarget.children, li)
);
}, []);
return html

${items.map(
(item, i) => LinkLi(item, i === clicked ? 'highlight' : '')
)}

// render components within an element
render(document.body, html
List of links:
${Links([
{text: 'blog', href: 'www.blog.me'},
{text: 'bio', href: 'www.bio.me'},
])}
);
`

$3

Both html and svg renders are exposed via the neverland module, and you must use the render utility

$3

All hooks are provided by augmentor, via dom-augmentor that takes care or injecting life-cycle DOM events when useEffect is used.

* Basic Hooks
* useState
* useEffect
* useContext, which can be defined via createContext(value)
* Additional Hooks
* useReducer
* useCallback
* useMemo
* useRef
* useLayoutEffect

#### About useImperativeHandle

This hook is strictly _React_ oriented with no meaning in current _dom-augmentor_ world.

$3

Every time you wrap a component you grant yourself the used hooks within would run specifically for that component.

However, if you create an extra hook, or your callback doesn't return either html or svg result, you don't need to wrap it.

A simple rule of thumbs to know when a component should be wrapped or not is the following one:

* does this function/callback/arrow returns html or svg templates tag literals?
* if previous point is true, am I using any sort of direct, or composed, hook within such function, so that I want its state/results to be confined in the returned element, instead of side-effecting outer wrappers?

If the answer to both points is yes, then you should wrap the callback, otherwise, you most likely shouldn't.

This little thinking is currently needed due the fact there's no parsing or pre-processing in _neverland_, so that such wrapping cannot be done automatically for you, when needed.

You can still decide to wrap any callback that returns html or svg templates tag literals results, but that might have performance implication in larger projects.

$3

Common ways via bundlers or CDNs:

* globally, as const {neverland: $, render, html, useState} = window.neverland through _script_ with source https://unpkg.com/neverland
* CJS via const {neverland: $, render, html, useState} = require('neverland')
* ESM with bundlers via import {neverland as $, render, html, useState} from 'neverland'
* pure ESM via import {neverland as $, render, html, useState} from 'https://unpkg.com/neverland?module'

If you use a bundler you can simply install neverland via npm or yarn.

It is also possible to use it in browsers via https://unpkg.com/neverland:

`js
// you can import it in any scope
const {neverland, html, useState} = window.neverland;
const VirtualComp = neverland(...);

// or ...
const {neverland:$, html} = neverland;
const VirtualComp = $(...);
`

V3 Features / Breaking Changes

* no more unnecessary DOM trashes 🎉
* it is possible to have keyed results, when necessary, via html.for(ref[, id]) or svg.for(ref[, id])
* the usage of render is mandatory, no more DOM nodes out of the box

V2 Breaking Changes

* there is no default exported, but neverland` named export
* there are still more DOM trashes than desired, but it works, and the DX is awesome, as well as performance anyway 😊