Both initState and connect are called only once when the component first appears.

Update

Synchronously sending a message to the component in its render method is forbidden to avoid loops.

Destruction

Additionally, for any of these phases, the snabbdom hooks can be used on any VNode returned in render

If I want to

Initiate the component state from the initial props

Return the init state in initState:
`ts
function initState(props: Props) {
return { enabled: props.isEnabledByDefault }
}
`

Continuously compute a part of the component state from its props (e.g perf optimization)

Derive some state from the props Observable in connect:

`ts
function connect({ on, props }: ConnectParams) {
on(props, newProps => ({ statePart: expensiveOperation(newProps) }))
}
`
There is no need to also derive the state in initState, since props is
an observable that always have an initial value (the handler will be called synchronously in connect).

Recompute the component state if its props changed in a specific way

This is a specialization of the above that avoid doing unnecessary work.
We just have to remember the last props and compare it with the new ones:

`ts
function connect({ on, props }: ConnectParams) {
on(props.sliding2, ([newProps, oldProps]) => {
if (!oldProps || newProps.expr !== oldProps.expr)
return ({ expr: parseExpr(newProps) })
})
}
`
Note however that for inexpensive computations, it is generally advised to simply do it in render as it's then easier to guarantee props, state and view are in sync.

Perform a side effect when the component is added or removed

Use a snabbdom hook.

create is called before the element is added to the DOM,
insert is called after the element is added the DOM,
remove is called when the node's direct parent removes this node,
destroy is called when this node is directly or indirectly being removed from the vnode tree.

`ts
function render() {
return (
h('div', { hook: { create: enterAnimation, remove: exitAnimation } })
)
}
`

Alter the DOM when the component was rendered

Use the postpatch snabbdom hook.

`ts
function render() {
return (
h('div', { hook: { postpatch: fiddleWithTheDOMBehindYourBack } })
)
}
`


Clean up a setInterval or remove a DOM event listener when the component is removed
Good news everyone! You don't need to, if you use observables.
Observables are automatically cleaned up when the component is removed.

`ts
function connect({ on }: ConnectProps) {
const polling = Observable.interval(2000)
on(polling, () => {
// This handler will not be called once the component is removed
callSomeAjax()
})

on(Observable.fromEvent('click', document.body), evt => {
// This handler will not be called once the component is removed (the event handler is removed)
})
}
`
You could also reproduce the same behavior imperatively:

`ts
import { Observable } from 'kaiju'

function connect({ on }: ConnectProps) {
const pingTimeout = setTimeout(() => console.log('ping!'), 2000)

const observeDestruction = Observable(_ => () => {

/* This is the cleanup function that is called when there are no longer any subscribers
to the observable. It will be called when the component gets removed,
provided the component was the sole subscriber */

clearTimeout(pingTimeout)
})
on(observeDestruction, () => {})
}
`

Instantiate/destroy a vanillaJS widget when the component is added/removed

We can send a message from a DOM hook.

Assuming we found some vanillaJS widget named widget.Map that has a create and destroy method:
`ts

const inserted = Message('inserted')
const destroyed = Message('destroyed')

function connect({ on }: RenderParams & { context: Context }) {
let mapWidget: MapWidget | undefined

on(inserted, elm => { mapWidget = widget.Map.create(elm) })

on(destroyed, () => mapWidget.destroy())
}

function render({ props, state, msg }: RenderParams & { context: Context }) {
return (
h('div', { hook: {
insert: node => msg.send(inserted(node.elm)),
destroy: () => msg.send(destroyed())
}})
)
}
`
Note that this kind of Message sent from a DOM lifecycle hook should always perform side effects only.
If the state is updated, a warning will be logged and the component will ignore that change.

Local state vs Global state

Choosing whether a particular state is local or global, whether it's very local (component leaf) or not so local
(owned by a component somewhere else in the tree) is an important decision, although it can easily be refactored
based on new needs.

You typically want to keep very transient state as local as possible so that it remains encapsulated in a component and do not leak up. Less stateful components are more flexible because their parents can do what they want with that
component, but stateful components are more productive and less error prone, as you can skip having boilerplate to wire the same
parent state => component props everywhere it's used.


Example of typically local state
* Whether a select dropdown is opened
* Whether the component is focused
* Which grid row is highlighted
* Basically any state that resets if the user navigates away then comes back

Additionally, keeping state that is only useful to one screen should be kept inside the top-most component of that screen and no higher. Else, you would have to manually clean up that state when exiting the component.

That just leaves global state, which can be updated from anywhere and is accessed from multiple screens.


Example of typically global state
* The current url route
* User preferences
* Any cached, raw domain data that will be mapped/filtered/transformed in the different screens

Stores

A construct is provided to easily build push-based observables in a type-safe manner. This is entirely optional.

If you need a piece of state to live outside a component (it's not tied to a particular component's lifecycle), or you want your components to only care about presentational logic, you can either use Observables or Stores.
The difference is that a Store's state can be updated from the outside via Messages and is guaranteed to have an initial value whereas an Observable can only be transformed via operators.

Example:
`ts

import { Store, Message } from 'kaiju'
import merge from './util/obj/merge' // Fictitious


export const setUserName = Message('setUserName')


interface UserState {
name: string
}

const initialState = { name: 'bob' }

// This exports a store containing an observable ready to be used in a component's connect function
export default Store(initialState, ({on, state}) => {
on(setUserName, name =>
merge(state(), { name })
)
})

// ...
// Subscribe to it in a component's connect
import userStore from './userStore'

// Provide an initial value
function initialState() {
return {
userName: userStore.state().name
}
}

function connect({ on, state }: ConnectParams<{}, State>) {
on(userStore.state, user => {
// Copies the global user name into our local component state to make it available to render
return merge(state(), { userName: user.name })
})
}

// ...
// Then anywhere else, import the store and the message
userStore.send(setUserName('Monique'))
`

$3

Similarly to redux, a function is provided to create a new Component/function from an existing Component/function and a selector:

`ts
import { Component, ConnectParams, RenderParams, Message, Store, connectToStore } from 'kaiju'

const increaseBy = Message('increaseBy')

const initState = { num: 1 }

const store = Store(initState, ({ on, state }) => {
on(increaseBy, by => ({ num: state().num + by }))
})

type StoreType = typeof store

type Props = {
counter: number // From the store
mode: '1' | '2' // From the direct parent
opt?: string
}

const BaseComponent = (() => {

function initState() { return {} }

function connect({}: ConnectParams) {}

function render({ props }: RenderParams) {
renderedProps.push(props)
return h('button')
}

return function(props: Props) {
return Component({ name: 'baseComponent', props, initState, connect, render })
}
})()

const ConnectedComponent = connectToStore()(
BaseComponent,
store => ({ counter: store.state().num })
)

const connectedComponent = ConnectedComponent({ mode: '1', store })
`

It can only connect to a single store as you usually have a global store, or a very local one that can plug into other stores' data.

API

Creating a VNode with h

Creates a VNode
This is proxied to snabbdom's h so we can add our type definitions transparently.

`ts
import { h } from 'kaiju'
h('div', 'hello')
`
On top of the snabbdom modules you may feed to startApp, an extra module is always installed by kaiju: events.
events is like snabbdom's own on module except it works with Messages instead of just any event handler.

`ts

import { Message } from 'kaiju'

const someMessage = Message('someMessage')

// Send a message to the enclosing component on click and on mousedown
h('div', { events: { click: someMessage, mousedown: someMessage } })

// Or prepare the message to be sent with an argument.
// This is more efficient than creating a closure on every render.
const anotherMessage = Message<[Event, {x: number}]>('anotherMessage')

h('div', { events: { click: anotherMessage.with({ x: 3 }) } })
`

Creating a component

The Component factory function takes an object with the following properties:

$3

Mandatory String
This is the standard Virtual DOM key used in the diffing algorithm to uniquely identify this VNode.
It is also used for logging purposes, so it is usually just the name of the component.
By default, components have a key set to their name to differentiate them from other components.
However, you can also set an external key by defining a key property inside the Component's props. The overall key will then be name + _ + your key.
This can be useful when switching between two instances of the same component but without reusing any of its state.

$3

Optional Object
An object representing all the properties passed by our parent.
Typically props either represents state that is maintained outside the component or properties used to tweak the component's behavior.
The render function will be called if the props object changed shallowly (any of its property references changed), hence it's a good practice to try and use a flat object.
Note 1: props and state are separated exactly like in React as it works great. The same design best practices apply.
Note 2: If you wish to compute some state or generally perform a side effect based on whether some part of the props changed (similar to using componentWillReceiveProps in react) you can use the sliding2 combinator to compare the previous props with the new ones:

`ts
import { Observable } from 'kaiju'

on(props.sliding2(), (state, [newProps, oldProps]) => ...)
`

$3

Mandatory Object
A function taking the initial props as an argument and returning the starting state.
Note: Any synchronous observables further modifying the state in connect will effectively change the state used for the first render.

$3

Mandatory function({ on, msg, props, state }: ConnectParams): void
Connects the component to the app and computes the local state of the component.
connect is called only once when the component is mounted.

connect is called with four arguments, encapsulated in a ConnectParams object:

- on registers a Message or Observable that modifies the component local state.
The Observable will be automatically unsubscribed from when the component is unmounted.
Returning the current state or undefined in an on handler will skip rendering and can be used to do side effects.

- msg is the interface used to send and listen to messages.

Full interface:

`ts
/**
* Listens for a message sent from local VNodes or component children
*/
listen

(message: Message

): Observable

/**
* Listens to all messages bubbling up to a particular DOM node
*
* Example:
* const overlayMessages = msg.listenAt('#popupLayer .overlay')
*
* Note: The DOM Element must be available at the time the function is called.
*/
listenAt

(target: string | Element): Observable>

/**
* Sends a message to self.
*
* Example:
* msg.send(AjaxSuccess([1, 2]))
*/
send

(payload: MessagePayload

): void

/**
* Sends a message to this component's nearest parent.
*
* Example:
* msg.sendToParent(ItemSelected(item))
*/
sendToParent

(payload: MessagePayload

): void
`

- props An Observable with a new value every time the props passed by our parent changed.
It is often enough to simply let the render function take care of these new props but advanced users may sometimes want to derive some state from props.

Just like with props, a redraw will only get scheduled if the state object changed shallowly.

- state The Observable current state.

$3

Mandatory function({ props, state, msg }: RenderParams): VNode | Node[]

Returns the current VNode tree of the component based on its props and state.
You can also return an Array of Nodes, where a Node is either a VNode, a string, null or undefined.

Example:

`ts
import { h, Message, RenderParams } from 'kaiju'

interface State {
text: string
}

const buttonClick = Message<[Event, number]>('buttonClick')

function render({ state }: RenderParams) {
const { text } = state

return (
h('div#text', [
h('h1', 'Hello'),
h('p', text),
h('button', { events: { click: buttonClick.with(33) } })
])
)
}
`

startApp

Installs and performs the initial render of the app synchronously.

`ts
function startApp(options: {
app: VNode // The root VNode
elm: HTMLElement // The root element where the app will be rendered
replaceElm?: boolean // Whether elm should be fully replaced by the app, instead of acting as the app parent. Defaults to false.
snabbdomModules: any[] // The snabbdom modules that should be active during patching
}): void
`

`ts
import { startApp } from 'kaiju'
import app from './app'


const snabbdomModules = [
require('snabbdom/modules/class'),
require('snabbdom/modules/props'),
require('snabbdom/modules/attributes'),
require('snabbdom/modules/style')
]

startApp({ app, snabbdomModules, elm: document.body })
`

For more information about snabbdom modules see the official documentation

Render.into

This function is made available after the app was created with startApp.
This can be used to create some advanced components with their own internal rendering needs (e.g: Efficient popups, alerts, etc).
It renders either synchronously if called from an ongoing rendering phase, or asynchronously.

`ts
import { Render, h } from 'kaiju'

const firstVDom = h('div')

// Creates a new div as a child of body
Render.into(document.body, firstVDom)

// Patch that div so that it becomes a span
const cancel = Render.into(firstVDom, h('span'), () => {
// Inside the rendered callback
})
`

Render.scheduleDOMWrite

The virtual DOM abstraction pretty much guarantees an optimal way of creating and updating the DOM in a single pass, without any layout trashing.
Sometimes, however, you may want to further alter the DOM in an imperative way when it's not possible to have a straightforward state->view binding.
Kaiju provides two functions to do that without causing layout trashing:
Render.scheduleDOMRead and Render.scheduleDOMWrite.
Both are called at the end of a render cycle (so still inside a requestAnimationFrame context)
The reads and writes are batched, reads are called first.

`ts
import { Render, VNode } from 'kaiju'

// Called within an insert hook
function increaseHeight(vnode: VNode) {
const el = vnode.elm as HTMLElement

Render.scheduleDOMRead(() => {
const height = el.clientHeight

Render.scheduleDOMWrite(() => {
el.style['height'] = ${height + 10}px
})
})
}

`

Message

Stores and Component can both send and listen to message. Indeed, each component has a private Store to manage its state.
Messages help debugging and communicate intent better than generic model-altering callbacks. Here's what you can do with messages:

$3

`ts
import { Message } from 'kaiju'

// Message taking no arguments
const increment = Message('increment')

// Message taking one argument
const incrementBy = Message('incrementBy')

// Message taking a tuple
const incrementBy2 = Message<[number, Event]>('incrementBy')
// Then pre-bind it so it can be used directly in the DOM:
incrementBy2.with(33) // Message
`

To store references of messages with a specific number of payloads, use:

`ts
const msg0: Message.NoPayload

const msg1: Message.OnePayload

const msg2: Message.TwoPayloads
`

$3