README
snabbdom-react-components.js
React like, Snabbdom based, Virtual Dom framework for JavaScript Web Applications and set of simple interpretations of React loved helpers as Styled Components or Redux
Please use carfully, as documentation need to be improved.
0. Before you will start
SRC (snabbdom-react-components 🤓) is the Career Interactive project we have been developing inhouse. We are gratefull for all the Open Source project we came across and we deciced to open some of our code with the World.
We can't promise now to update this repository in regular basis until we will hear from you, as this is not the main repository for our purpose.
We are happy to collaborate with anyone who want to help develop this project 😊
We can promise one - as soon as you'll get into that, you will love how we redefined Snabbdom (if you're not familiar, see there: Snabbdom
IMPORTANT: SRC is based on Snabbdom v0.5.0 as we have started to make core changes for our own usage, we were hooked for no hassle update.
1. Getting Started
To use SRC, download package using your package manager or download the latest relase.
# npm:
npm i -S snabbdom-react-components
# yarn:
yarn add snabbdom-react-components
To render siplest SRC component, we will use Snabbdom vnode, eg. paragraph. We will use the mandatory render method and snabbdom functions h
and patch
Find more about createComponent
function here.
import { createComponent, h, patch } from 'snabbdom-react-components'
const myComponent = createComponent({
render: () => {
return h('p', 'Hello World')
}
})
patch(document.getElementById('root'), myComponent)
2. Lifecycle
One of the biggers benefits for using SRC is the React Based lifecycle mechanism which makes it so much easier to use in comparation to snabbdom hooks. Let's see how to use it.
In this example, we will render a list of all the users, but for the time we don't have them, we will render loading message
import { createComponent, h } from 'snabbdom-react-components'
const myComponent = createComponent({
state: {
users: []
},
componentDidMount: async (state, component) => {
const users = await Api.getUsers()
component.setState({ users })
},
render: (state, component) => {
const { users } = state;
if (!users.length) {
return h('p', 'Fetching users...')
}
return h('ul', users.map(user => h('li', { key: user.id }, user.name)))
}
})
3. Styled Components
Along with component builder, SRC have build in Styled Components builder we all love from React. It is not as powerfull yet. Yet 😇
import { createComponent, styled } from 'snabbdom-react-components'
const Button = styled.button`
color: ${props => !props.toggled ? '#fff' : '#4f4f4f'};
background: ${props => !props.toggled ? '#aee174' : '#eee'};
`
const myComponent = createComponent({
state: {
toggled: false
},
render: (state, component) => {
const { toggled } = state
return Button({
styled: { toggled },
on: {
click: () => {
component.setState((prevState) => ({
toggled: !prevState.toggled
}))
}
}
}, 'Click me')
}
})
4. Reducers
Redux for good become one of the best state managing libraries. Based on that, SRC has build-in simpler and easier, but powerfull reducer functionality
import { createComponent, styled } from 'snabbdom-react-components'
const Info = styled.div`
color: #4f4f4f;
font-size: 16px;
`
const List = styled.ul``;
const ListEl = styled.li``;
const FakeApi = (delay = 2000) => {
return new Promise(function (resolve) {
setTimeout(resolve, delay)
})
}
const myComponent = createComponent({
state: {
ready: false,
users: []
},
reducer: (state, action) => {
switch (action.type) {
case 'ready': {
return {
...state,
ready: true,
users: action.payload
}
}
default: return state
}
},
componentDidMount: async (state, component) => {
await FakeApi()
component.dispatch({
type: 'ready',
payload: [{id: 1, name: 'John', surname: 'Due'}]
})
},
render: (state, component) => {
const { ready, users } = state;
if (!ready) {
return Info('Wait...')
}
if (!users.length) {
return Info('No users to show...')
}
return List(users.map(user => ListEl({ key: user.id }, user.name)))
}
})
API overview
createComponent
This is the basic SRC function for creating statefull components. Take a look on all available methods and params. Below you will find FAQ for selected params.
Params
const myComponent = createComponent({
// Use to introduce the initial state of your component.
state: 'object' || (params) => 'object',
// if provided, main render element will recieve this key (check below to learn about keys)
key: 'String||null',
// If true, component will be returned as a promise
async: 'boolean',
// If true, component will return instance of SRC, not a vnode.
ejectComponent: 'boolean',
// Use to keep your reducer actions
CONSTS: 'object',
// you can provide cases when your component should trigger rerender cycle.
shouldComponentUpdate: 'boolean' || (nextState, nextComponent) => 'boolean',
// Mandatory param. Provided vnodes will be rendered into DOM.
render: (state, component) => 'vnode',
// You can use that to build your state manager. Learn more above.
reducer: (state, action, component) => 'vnode',
// Triggers Snabbdom Init hook
componentDidInit: (state, component) => undefined,
// Triggers before the vnode is created
componentWillInit: (state, component) => undefined,
// Triggers Snabbdom Insert hook
componentDidMount: (state, component) => undefined,
// Triggers Snabbdom Create hook
componentWillMount: (state, component) => undefined,
// Triggers after the rerender cycle
componentDidUpdate: (state, component) => undefined,
// Triggers Snabbdom Remove hook
componentDidUnmount: (state, component) => undefined,
// Triggers before the rerender cycle
componentWillUpdate: (state, component) => undefined,
// Triggers Snabbdom Destroy hook
componentWillUnmount: (state, component) => undefined,
// Triggers Snabbdom Prepatch hook
componentWillPrepatch: (state, component) => undefined,
// Triggers Snabbdom Postpatch hook
componentWillPostpatch: (state, component) => undefined,
// Triggers after the vnode was created, but before the patch
componentDidCreateViewObject: (state, component) => undefined,
// Triggers after state was resolved
componentWillCreateViewObject: (state) => undefined
})
Component function
Almost all livecycle methods have available instance function.
const component = {
// Use to change component state
setState: 'object' || (nextState) => 'object',
// Returns the state of component
getState: () => 'object',
// All the custom methods you will provide will be placed on the items 'sandbox'
items: 'object'
// If you have created reusable component, you can later extend your new component with the resuable one. You will found more about the hooks later.
useHook: () => {}
// You can remount the component
remount,
// If you have reducer, use this to dispatch actions
dispatch,
// Force update your component
forceUpdate,
// All the params will be provided there
...viewObject.params
})
createAsyncComponent
This is the more advanced version of simple createComponent
method. Is is highly possible that this functon will become the main createComponent
method in future. So far it is in test phase, but you're welcome to test.
The main diffrence between createComponent
function is that this component by default is returned as async
function throught the lazy
helper. That's allow you to organize your code even more! Look at example. We will get the list of all the users and display as a list:
import { createComponent, styled, createAsyncComponent } from 'snabbdom-react-components'
const Info = styled.div`
color: #4f4f4f;
font-size: 16px;
`
const List = styled.ul``;
const ListEl = styled.li``;
// createComponent:
const myComponent = createComponent({
state: {
users: []
},
componentDidMount: async (state, component) => {
const users = await Api.getUsers()
component.setState({ users })
},
render: (state, component) => {
const { users } = state;
if (!users.length) {
return Info('No users to show...')
}
return List(users.map(user => ListEl({ key: user.id }, user.name)))
}
})
// createAsyncComponent:
const myAsyncComponent = createAsyncComponent({
state: async () => {
const users = await Api.getUsers()
return { users }
},
render: (state, component) => {
const { users } = state;
return List(users.map(user => ListEl({ key: user.id }, user.name)))
}
})
As you can see on above example, we don't have to use any from the livecycle method to fetch data. Even more, we don't care about loading stage as our component will have data as default!
Styled
Except the original Styled Components, SRC Styled Components resolve provided CSS into inline vnode styles (hopefully for time being only).
The main purpose of SC has been developed:
import { styled } from 'snabbdom-react-components'
const Box = styled.div`
color: ${props => props.color || 'black'};
`
Box({
styled: {
color: 'red'
}
})
What's amazing on SRC SC is the css
helper which can resolve any valid CSS into basic Snabbdom vnode:
import { h, css, cssWithProps } from 'snabbdom-react-components'
const params = {
color: 'red'
}
const box = h('div', {
style: css`
background-color: black;
`
})
const box2 = h('div', {
style: cssWithProps(params)`
background-color: ${props => props.color || 'black'};
`
})
You can also inherit styles from other Styled Components easier:
import { styled } from 'snabbdom-react-components'
const CircleBox = styled.div`
display: block;
width: ${props => props.size || '64px'};
height: ${props => props.size || '64px'};
background-color: #eee;
border-radius: 50%;
`
const Avatar = styled.div`
${CircleBox}
background-size: cover;
background-image: url(${props => props.avatar || 'no-avatar.jpg'});
`
const avatar = Avatar({
styled: {
size: '80px',
avatar: 'avatar.jpg'
}
})
Styled Components are the thing we want to improve the most.
Lazy
This helper gives you option to load any async
function returning vnode
by rendering the loader vnode
until the function is resolved.
import { lazy, h, patch } from 'snabbdom-react-components'
const lazyFunction = async () => {
const users = await Api.getUsers()
return h('ul', users.map((user) => h('li', {key: user.id}, user.name)))
}
patch(document.getElementById('root'), lazy(lazyFunction, h('div', 'loading'))())
Learn more about projects we were inspired:
More comming soon!
Made in London with ❤️ by Career Interactive (by Szymon Pajka 👏)