├── .babelrc
├── .gitignore
├── .npmignore
├── .travis.yml
├── .zuul.yml
├── README.md
├── book.json
├── docs
├── README.md
├── advanced
│ ├── context.md
│ ├── dispatcher.md
│ ├── hmr.md
│ ├── index.md
│ ├── keys.md
│ ├── lifecycle.md
│ └── model.md
├── api
│ ├── create-app.md
│ ├── diff.md
│ ├── dom.md
│ ├── element.md
│ ├── index.md
│ ├── string.md
│ └── vnode.md
├── basics
│ ├── components.md
│ ├── elements.md
│ ├── events.md
│ ├── getting-started.md
│ ├── index.md
│ ├── jsx.md
│ └── migrating.md
├── contributing.md
├── motivation.md
└── tips
│ └── innerhtml.md
├── examples
└── basic
│ ├── app.js
│ └── index.js
├── package.json
├── src
├── app
│ └── index.js
├── diff
│ └── index.js
├── dom
│ ├── create.js
│ ├── events.js
│ ├── index.js
│ ├── setAttribute.js
│ └── update.js
├── element
│ └── index.js
├── index.js
└── string
│ ├── index.js
│ └── renderString.js
└── test
├── app
├── index.js
└── thunk.js
├── diff
├── attributes.js
├── children.js
└── node.js
├── dom
├── create.js
├── setAttribute.js
└── update.js
├── element
└── index.js
├── index.js
└── string
└── index.js
/.babelrc:
--------------------------------------------------------------------------------
1 | {
2 | "presets": ["stage-2"],
3 | "sourceMaps": true,
4 | "plugins": [
5 | ["transform-react-jsx", {"pragma": "h"}],
6 | "transform-es2015-template-literals",
7 | "transform-es2015-literals",
8 | "transform-es2015-function-name",
9 | "transform-es2015-arrow-functions",
10 | "transform-es2015-block-scoped-functions",
11 | "transform-es2015-classes",
12 | "transform-es2015-object-super",
13 | "transform-es2015-shorthand-properties",
14 | "transform-es2015-duplicate-keys",
15 | "transform-es2015-computed-properties",
16 | "transform-es2015-for-of",
17 | "transform-es2015-sticky-regex",
18 | "transform-es2015-unicode-regex",
19 | "check-es2015-constants",
20 | "transform-es2015-spread",
21 | "transform-es2015-parameters",
22 | "transform-es2015-destructuring",
23 | "transform-es2015-block-scoping",
24 | "transform-es2015-typeof-symbol",
25 | ["transform-regenerator", { "async": false, "asyncGenerators": false }],
26 | ],
27 | "env": {
28 | "commonjs": {
29 | "plugins": [
30 | ["transform-es2015-modules-commonjs", { "loose": true }]
31 | ]
32 | },
33 | "es": {}
34 | }
35 | }
36 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | .DS_Store
3 | _book
4 | dist
5 | lib
6 | es
7 | npm-debug.log
8 |
--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
1 | .babelrc
2 | test
3 | src
4 |
--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | language: node_js
2 | node_js:
3 | - "5"
4 | script:
5 | - npm run test:lint
6 | - npm run test:headless
7 | addons:
8 | apt:
9 | packages:
10 | - xvfb
11 | install:
12 | - export DISPLAY=':99.0'
13 | - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
14 | - npm install
15 |
--------------------------------------------------------------------------------
/.zuul.yml:
--------------------------------------------------------------------------------
1 | ui: tape
2 | concurrency: 5
3 | browsers:
4 | - name: chrome
5 | version: latest
6 | - name: firefox
7 | version: latest
8 | - name: iphone
9 | version: latest
10 | - name: ipad
11 | version: latest
12 | - name: android
13 | version: latest
14 | - name: ie
15 | version: 10..latest
16 | - name: microsoftedge
17 | version: latest
18 | - name: safari
19 | version: latest
20 | browserify:
21 | - transform: babelify
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Deku
2 |
3 | [](https://travis-ci.org/dekujs/deku)
4 | [](https://www.npmjs.com/package/deku)
5 | [](https://github.com/feross/standard)
6 | [](https://www.npmjs.com/package/deku)
7 | [](https://discord.gg/0gNkyCAVkDYsBaFe)
8 |
9 | Deku is a library for rendering interfaces using pure functions and virtual DOM.
10 |
11 | Instead of using classes and local state, Deku just uses functions and pushes the responsibility of all state management and side-effects onto tools like [Redux](http://redux.js.org/). It also aims to support only modern browsers to keep things simple.
12 |
13 | It can be used in place of libraries like React and works well with Redux and other libraries in the React ecosystem.
14 |
15 | Deku consists of 5 modules packaged together for convenience:
16 |
17 | * `element`: Create virtual elements.
18 | * `diff`: Compute the difference between two virtual elements. You can use this if you're creating a custom renderer.
19 | * `dom`: Create DOM elements from virtual elements and update them using the result of a diff. You'll only use this directly if you're building your own app creator.
20 | * `string`: Render a HTML string from virtual elements.
21 | * `createApp`: Kickstart an app for the browser.
22 |
23 | ### Installation
24 |
25 | ```
26 | npm install --save deku
27 | ```
28 |
29 | We support the latest two versions of each browser. This means we only support IE10+.
30 |
31 | [](https://saucelabs.com/u/deku)
32 |
33 | ### Example
34 |
35 | ```js
36 | /** @jsx element */
37 | import {element, createApp} from 'deku'
38 | import {createStore} from 'redux'
39 | import reducer from './reducer'
40 |
41 | // Dispatch an action when the button is clicked
42 | let log = dispatch => event => {
43 | dispatch({
44 | type: 'CLICKED'
45 | })
46 | }
47 |
48 | // Define a state-less component
49 | let MyButton = {
50 | render: ({ props, children, dispatch }) => {
51 | return
52 | }
53 | }
54 |
55 | // Create a Redux store to handle all UI actions and side-effects
56 | let store = createStore(reducer)
57 |
58 | // Create an app that can turn vnodes into real DOM elements
59 | let render = createApp(document.body, store.dispatch)
60 |
61 | // Update the page and add redux state to the context
62 | render(
63 | Hello World!,
64 | store.getState()
65 | )
66 | ```
67 |
68 | ### Documentation
69 |
70 | You can [read the documentation online](http://anthonyshort.me/deku/).
71 |
72 | ### License
73 |
74 | The MIT License (MIT) Copyright (c) 2015 Anthony Short
75 |
--------------------------------------------------------------------------------
/book.json:
--------------------------------------------------------------------------------
1 | {
2 | "gitbook": "2.x.x",
3 | "structure": {
4 | "summary": "docs/README.md"
5 | },
6 | "plugins": ["edit-link", "prism", "-highlight"],
7 | "pluginsConfig": {
8 | "edit-link": {
9 | "base": "https://github.com/anthonyshort/deku/tree/master",
10 | "label": "Edit"
11 | },
12 | "github": {
13 | "url": "https://github.com/anthonyshort/deku/"
14 | }
15 | }
16 | }
17 |
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
1 | # Summary
2 |
3 | * [Readme](/README.md)
4 | * [Motivation](/docs/motivation.md)
5 | * [Contributing](/docs/contributing.md)
6 | * [Basics](/docs/basics/index.md)
7 | * [Migrating from v1](/docs/basics/migrating.md)
8 | * [Elements](/docs/basics/elements.md)
9 | * [JSX](/docs/basics/JSX.md)
10 | * [Events](/docs/basics/events.md)
11 | * [Components](/docs/basics/components.md)
12 | * [Advanced](/docs/advanced/index.md)
13 | * [Lifecycle Hooks](/docs/advanced/lifecycle.md)
14 | * [Keys](/docs/advanced/keys.md)
15 | * [Context](/docs/advanced/context.md)
16 | * [Dispatcher](/docs/advanced/dispatcher.md)
17 | * [Hot Module Replacement](/docs/advanced/hmr.md)
18 | * Tips
19 | * [innerHTML](/docs/tips/innerhtml.md)
20 | * [API Reference](/docs/api/index.md)
21 | * [createApp](/docs/api/create-app.md)
22 | * [dom](/docs/api/dom.md)
23 | * [string](/docs/api/string.md)
24 | * [element](/docs/api/element.md)
25 | * [diff](/docs/api/diff.md)
26 | * [vnode](/docs/api/vnode.md)
27 |
--------------------------------------------------------------------------------
/docs/advanced/context.md:
--------------------------------------------------------------------------------
1 | # Context
2 |
3 | Context is an object you can set when you call render. It will be accessible from every component in the tree. Unlike React you can't modify the context within the tree.
4 |
5 | You can use `context` to:
6 |
7 | * Access your Redux state throughout the tree.
8 | * Pass in `window` properties, like the size of the browser window.
9 | * View device information like the user agent, or the orientation.
10 | * Set global theme variables.
11 | * Store local state for components using their `path` as the key.
12 |
13 | There are some things to remember when using `context`:
14 |
15 | * Context should be **immutable**. Never mutate the object directly. The renderer can perform additional optimizations if you use a different object each time. If you're using Redux, your state should be immutable anyway. You can also use a library to help with immutable structures like [Immutable.js], [Mori] or [Scour].
16 | * Context can't be modified by components. There's no `getChildContext`.
17 |
18 | [Immutable.js]: https://github.com/facebook/immutable-js
19 | [Mori]: https://github.com/swannodette/mori
20 | [Scour]: http://ricostacruz.com/scour/
21 |
22 | ## Example
23 |
24 | We can access the `context` on the model:
25 |
26 | ```js
27 | function render ({ context }) {
28 | return
Hi
29 | }
30 |
31 | export default {
32 | render
33 | }
34 | ```
35 |
36 | Your context object might look something like this:
37 |
38 | ```js
39 | let context = {
40 | theme: {
41 | background: 'red'
42 | },
43 | device: {
44 | width: 1000,
45 | height: 1000,
46 | orientation: 'landscape'
47 | },
48 | browser: {
49 | type: 'IE',
50 | version: 10
51 | },
52 | collections: {
53 | todos: [],
54 | projects: []
55 | },
56 | user: {
57 | name: 'Anthony Short',
58 | username: 'anthoney'
59 | }
60 | }
61 | ```
62 |
63 | Which you can set when you call [`render`](../api/dom):
64 |
65 | ```js
66 | render(, context)
67 | ```
68 |
69 | ## How do I change context and re-render?
70 |
71 | Context can change in a few ways. You should listen for changes at the top level of your application rather than within components where possible. To change any type of context value from within components, you should trigger actions using `dispatch`.
72 |
73 | * You can listen to your Redux store using `subscribe`
74 | * You can listen for `window` events like `resize`
75 | * Trigger actions using the `dispatcher`
76 |
77 | The easiest way to use context is to use the Redux state. It's almost guaranteed to be immutable and you can easily keep `window` and device information in your Redux store.
78 |
79 | ```js
80 | render(, store.getState())
81 | ```
82 |
83 | You would modify context by dispatching actions and reducing them with Redux:
84 |
85 | ```js
86 | function render ({ dispatch }) {
87 | return
88 | }
89 |
90 | function resize (dispatch, width, height) {
91 | return () => dispatch({
92 | type: 'RESIZE',
93 | width,
94 | height
95 | })
96 | }
97 |
98 | export default {
99 | render
100 | }
101 | ```
102 |
--------------------------------------------------------------------------------
/docs/advanced/dispatcher.md:
--------------------------------------------------------------------------------
1 | # Dispatcher
2 |
3 | The `dispatcher` is a function you can pass to `createRenderer` that will handle actions triggered within the UI. You will typically use a library like Redux to handle reducing actions into state and side-effects.
4 |
5 | * All actions a user or program trigger should be dispatched
6 | * Side-effects, like DOM manipulation, should also be dispatched as actions and handled by this function
7 | * Access the dispatch function within components as `model.dispatch`
8 |
9 | ## Example
10 |
11 | Here's a custom `dispatch` function being passed into the `createRenderer` function.
12 |
13 | ```js
14 | // Custom dispatch method
15 | let render = createRenderer(document.body, action => {
16 | // action.type = 'ADD_TODO'
17 | })
18 |
19 | // Using Redux
20 | let render = createRenderer(document.body, store.dispatch)
21 | ```
22 |
23 | You will be able to access `dispatch` from any component as `model.dispatch`:
24 |
25 | ```js
26 | function render ({ dispatch }) {
27 | return
28 | }
29 |
30 | function addTodo (dispatch) {
31 | return event => {
32 | dispatch({
33 | type: 'ADD_TODO'
34 | })
35 | }
36 | }
37 |
38 | export default {
39 | render
40 | }
41 | ```
42 |
--------------------------------------------------------------------------------
/docs/advanced/hmr.md:
--------------------------------------------------------------------------------
1 | # Hot Module Replacement
2 |
3 | Being purely functional, Hot Module Replacement (HMR), i.e. code swapping at runtime, comes with virtually no cost while using **deku**.
4 |
5 | * [Webpack](#webpack)
6 | * [Browserify](#browserify)
7 |
8 | ## Webpack
9 |
10 | ### 1. Install dependencies
11 |
12 | First we need to create a project:
13 |
14 | ```bash
15 | mkdir project
16 | cd project
17 | npm init
18 | ```
19 |
20 | Then to install some dependencies:
21 |
22 | ```bash
23 | npm install --save deku
24 | npm install --save-dev babel-core babel-loader babel-plugin-transform-react-jsx babel-preset-es2015 express webpack webpack-dev-middleware webpack-hot-middleware
25 | ```
26 |
27 | ### 2. Create a webpack config
28 |
29 | The following webpack config will enable HMR and compile ES2015/JSX code.
30 |
31 | ```js
32 | // file: webpack.config.js
33 |
34 | var webpack = require('webpack'),
35 | path = require('path');
36 |
37 | module.exports = {
38 | devtool: '#source-map',
39 | entry: [
40 | 'webpack-hot-middleware/client',
41 | './main.jsx'
42 | ],
43 | output: {
44 | path: path.join(__dirname, 'build'),
45 | filename: 'bundle.js',
46 | library: 'app',
47 | publicPath: '/build/'
48 | },
49 | plugins: [
50 | new webpack.optimize.OccurrenceOrderPlugin(),
51 | new webpack.HotModuleReplacementPlugin(),
52 | new webpack.NoErrorsPlugin()
53 | ],
54 | module: {
55 | loaders: [
56 | {
57 | test: /\.jsx?$/,
58 | exclude: /node_modules/,
59 | loader: 'babel',
60 | query: {
61 | presets: ['es2015'],
62 | plugins: [['transform-react-jsx', {pragma: 'element'}]]
63 | }
64 | }
65 | ]
66 | }
67 | };
68 |
69 | ```
70 |
71 | ### 3. Create a development server
72 |
73 | We need to setup a little server that will serve our code and assets while being able to send HMR updates.
74 |
75 | ```js
76 | // file: server.js
77 |
78 | var webpack = require('webpack'),
79 | config = require('./webpack.config.js'),
80 | dev = require('webpack-dev-middleware'),
81 | hot = require('webpack-hot-middleware'),
82 | express = require('express'),
83 | path = require('path');
84 |
85 | var compiler = webpack(config);
86 |
87 | var app = express();
88 |
89 | app.use(dev(compiler, {publicPath: config.output.publicPath}));
90 | app.use(hot(compiler));
91 |
92 | app.get('*', function(req, res) {
93 | res.sendFile(path.join(__dirname, 'index.html'));
94 | });
95 |
96 | console.log('Compiling...');
97 | app.listen(3000, 'localhost', function (err) {
98 | if (err) return console.err(err);
99 | });
100 | ```
101 |
102 | ### 4. Creating our HTML file, JS entry and a root component
103 |
104 | ```html
105 |
106 |
107 |
108 | Deku HMR Example
109 |
110 |
111 |
112 |
113 |
114 |
115 | ```
116 |
117 | ```js
118 | // file: components/Application.jsx
119 |
120 | import {element} from 'deku';
121 |
122 | export default {
123 | render() {
124 | return (
125 |
126 |
Hello World!
127 |
128 |
129 | );
130 | }
131 | }
132 | ```
133 |
134 | ```js
135 | // file: main.jsx
136 |
137 | import {dom, element} from 'deku';
138 | import Application from './components/Application.jsx';
139 |
140 | const render = dom.createRenderer(document.getElementById('mount'));
141 |
142 | // Rendering function
143 | function update (Component) {
144 | render()
145 | }
146 |
147 | // First render
148 | update(Application);
149 |
150 | // Hooking into HMR
151 | // This is the important part as it will reload your code and re-render the app accordingly
152 | if (module.hot) {
153 | module.hot.accept('./components/Application.jsx', function() {
154 | const nextApplication = require('./components/Application.jsx').default;
155 | update(nextApplication);
156 | });
157 | }
158 | ```
159 |
160 | ### 5. Starting the development server
161 |
162 | Now, our working directory should look like the following:
163 |
164 | ```
165 | project/
166 | components/
167 | Application.jsx
168 | index.html
169 | main.jsx
170 | package.json
171 | server.js
172 | webpack.config.js
173 | ```
174 |
175 | Let's launch the dev server and code:
176 |
177 | ```bash
178 | node server.js
179 | ```
180 |
181 | Wait for webpack to perform the initial compilation and let's visit `localhost:3000`.
182 |
183 | You should now be able to edit your components without reloading the browser!
184 |
185 | ## Browserify
186 |
187 | ### 1. Install dependencies
188 |
189 | We'll use [watchify] to watch for code changes.
190 |
191 | ```sh
192 | npm install --save-dev browserify-hmr watchify
193 | ```
194 |
195 | [watchify]: https://github.com/substack/watchify
196 |
197 | ### 2. Set up HMR hooks
198 |
199 | Use the HMR API's `module.hot.accept()` to re-run `render()` when code updates happen.
200 |
201 | ```js
202 | // The root deku component.
203 | let App = require('./components/app')
204 |
205 | // The deku renderer.
206 | let store = createStore(/* ... */)
207 | let render = createRenderer(document.body, store.dispatch)
208 |
209 | // Running this will refresh your page with the latest
210 | // components and the latest state.
211 | function update () {
212 | render(, store.getState())
213 | }
214 |
215 | update()
216 |
217 | // This is the important part. It will re-render in place
218 | // after updating your code.
219 | if (module.hot) {
220 | module.hot.accept('./components/app', function () {
221 | App = require('./components/app')
222 | update()
223 | }
224 | }
225 | ```
226 |
227 | [browserify-hmr]: https://github.com/AgentME/browserify-hmr
228 |
229 | ### 3. Run watchify
230 |
231 | Use watchify with `-p browserify-hmr` to enable hot module replacement.
232 |
233 | ```sh
234 | watchify -p browserify-hmr index.js -o public/application.js
235 | ```
236 |
--------------------------------------------------------------------------------
/docs/advanced/index.md:
--------------------------------------------------------------------------------
1 | # Advanced
2 |
3 | Learn how to integrate Deku into your application and improve performance.
4 |
5 | * [Lifecycle Hooks](./hooks.md)
6 | * [Keys](./keys.md)
7 | * [Context](./context.md)
8 | * [Dispatcher](./dispatcher.md)
9 | * [Hot Module Replacement](./hmr.md)
10 |
--------------------------------------------------------------------------------
/docs/advanced/keys.md:
--------------------------------------------------------------------------------
1 | # Keys
2 |
3 | Elements can have a special attribute named `key`. This lets the renderer know how to identify an element amongst sibling elements so it can determine if an element has just been moved, instead of removing and replacing DOM nodes unnecessarily.
4 |
5 | * `key` is a special attribute that won't be passed in as a prop or rendered in the DOM.
6 | * They increase the rendering performance of large lists.
7 | * They only need to be unique to sibling elements.
8 | * They can be used to maintain state of form elements, like `input` and `select`.
9 | * Not every sibling needs a key. You can add a `key` to the elements you want to be moved around.
10 |
11 | ## Example
12 |
13 | In this example, we use the key attribute to make sure the input element is moved instead of replaced whenever the hint is added and removed:
14 |
15 | ```js
16 |
17 |
18 | {showHint ? Enter your full name : null}
19 |
20 |
21 | ```
22 |
23 | In the next example, we use keys to improve the rendering performance of a list. You can use the `id`, `name`, or other unique field for the list item.
24 |
25 | ```js
26 | let people = [
27 | { id: 1, name: 'Tom' },
28 | { id: 2, name: 'Dick' },
29 | { id: 3, name: 'Harry' }
30 | ]
31 |
32 | let el =
33 |
34 | {people.map(person =>
{person.name}
)}
35 |
36 | ```
37 |
38 | ## Why do we need keys?
39 |
40 | To see why we need to do this we need to explain how the renderer compares lists of elements. Imagine on the first render these elements are returned:
41 |
42 | ```html
43 |
44 | One
45 |
Two
46 | Three
47 |
48 | ```
49 |
50 | Then on the next render this is returned:
51 |
52 | ```html
53 |
54 | One
55 | Three
56 |
Two
57 |
58 | ```
59 |
60 | It is obvious to humans that the third element has moved up. But when the renderer is performing the diff it is just comparing the left and right sides one after the other:
61 |
62 | ```
63 | One -> One // No change. Leave it.
64 |
Two
-> Three // Different element. Replace!
65 | Three ->
Two
// Different element. Replace!
66 | ```
67 |
68 | Most of the time this won't affect you but there are a couple of cases where this becomes a problem:
69 |
70 | * When you have a large list of elements (thousands) that have moved around. The renderer will be removing and creating large sets of DOM elements.
71 | * When elements with hidden state, like `input` fields, are moved around. Their state will be lost because they've been destroyed and recreated.
72 |
73 | To get around this we can just add a `key` attribute:
74 |
75 | ```js
76 |
77 | One
78 |
Two
79 | Three
80 |
81 | ```
82 |
83 | Now during the diff the renderer will know precisely which elements have just moved:
84 |
85 | ```
86 | One -> One // No change. Leave it.
87 |
Two
->
Two
// Move to position 2!
88 | Three -> Three // Move to position 1!
89 | ```
90 |
91 | **These keys only need to be unique to siblings.** They need not be globally unique like the `id` attribute.
92 |
93 | You can also add keys only to the elements that will be moved around if that makes things easier.
94 |
95 | ```js
96 |
97 | One
98 |
Two
99 | Three
100 |
101 | ```
102 |
--------------------------------------------------------------------------------
/docs/advanced/lifecycle.md:
--------------------------------------------------------------------------------
1 | # Lifecycle hooks
2 |
3 | These are functions you can add to your component to hook into different parts of the rendering process. You can use these to manipulate the DOM in some way or trigger an action to change state.
4 |
5 | | Name | Triggered | Arguments |
6 | |-------------|--------------------------------------------------------------------------|-------------|
7 | | `onCreate` | When the component is initially created | `model` |
8 | | `onUpdate` | After the component is re-rendered and the DOM is patched | `model` |
9 | | `onRemove` | When the DOM element has been removed from the DOM | `model` |
10 |
11 | ## Example
12 |
13 | ```js
14 | function render (model) {
15 | return
{model.props.text}
16 | }
17 |
18 | function onCreate (model) {
19 | console.log('A MyComponent entity was created!')
20 | }
21 |
22 | export default {
23 | render,
24 | onCreate
25 | }
26 | ```
27 |
28 | ## How do I access the DOM element?
29 |
30 | In React, you can access the DOM element directly in the lifecycle hooks. In Deku, we only pass you the data model. If you need to access the DOM element this is a side-effect. You should dispatch an action and let another part of your application handle the side-effect. This allows you to keep your component completely DOM-free, which makes it easier to test and allows you to reuse side-effects.
31 |
32 | ```js
33 | function render ({ path }) {
34 | return
35 | }
36 |
37 | function onCreate ({ dispatch, path }) {
38 | dispatch({
39 | type: 'FOCUS',
40 | selector: `#${path}`
41 | })
42 | }
43 |
44 | export default {
45 | render,
46 | onCreate
47 | }
48 | ```
49 |
--------------------------------------------------------------------------------
/docs/advanced/model.md:
--------------------------------------------------------------------------------
1 | # Model
2 |
3 | The model is passed into the Component function and is essentially the state that you can use to create virtual nodes. The model is immutable so to make any changes to values you need modify the state somewhere else and call `render` again from the top level.
4 |
5 | ```js
6 | function App (model) {
7 | return
Hello World
8 | }
9 | ```
10 |
11 | ## Properties
12 |
13 | ### `model.attributes`
14 |
15 | The values passed into your component as virtual element attributes. For example, passing these attributes into the component:
16 |
17 | ```js
18 |
19 | ```
20 |
21 | will yield this as `model.attributes`:
22 |
23 | ```json
24 | {
25 | "count": 5,
26 | "type": "tasks"
27 | }
28 | ```
29 |
30 | ### `model.children`
31 |
32 | The child nodes that are passed to the component.
33 |
34 | ```js
35 |
36 |
37 | Hello World
38 |
39 | ```
40 |
41 | The `children` property will always be an array:
42 |
43 | ```jsx
44 | [
45 | ,
46 | Hello World
47 | ]
48 | ```
49 |
50 | You can use this to render the passed in nodes somewhere within the rendered DOM.
51 |
52 | ```js
53 | function App (model) {
54 | return
{model.children}
55 | }
56 | ```
57 |
58 | ### `model.path`
59 |
60 | The unique path to the component within the entire component tree.
61 |
62 | ```js
63 | function App (model) {
64 | return Save
65 | }
66 |
67 | function updateState (path) {
68 | return function (e) {
69 | dispatch('updateState', {
70 | path: path,
71 | value: e.target.value
72 | })
73 | }
74 | }
75 | ```
76 |
77 | Paths in a tree are strings, like `0.1.5.2`. Each number represents the index of the node in the parent node, so you can use this to find a node within a tree.
78 |
79 | If a node within that path has a `key` attribute, we use that instead so that the path is stable even if any elements move around. For example, `0.1.foo.2`. This allows you to maintain some state for a component even if it moves.
80 |
--------------------------------------------------------------------------------
/docs/api/create-app.md:
--------------------------------------------------------------------------------
1 | # `createApp`
2 |
3 | Returns a `render` function that you can use to render elements within `DOMElement`.
4 |
5 | ### Arguments
6 |
7 | 1. `el` _(HTMLElement)_: A container element that will have virtual elements rendered inside of it. The element will never be touched.
8 | 2. `dispatch` _(Function)_: A function that can receive actions from the interface. This function will be passed into every component. It usually takes an [action](http://redux.js.org/docs/basics/Actions.html) that can be handled by a [store](http://redux.js.org/docs/basics/Store.html)
9 |
10 | ### Returns
11 |
12 | `render` _(Function)_: A function that will update the current virtual element. It accepts a new `vnode` and a `context` object that will be passed to every component. You can use the context object to send shared state to every component. The `context` object should be immutable if possible as internally the renderer can provide extra optimizations.
13 |
14 | ### Example
15 |
16 | ```js
17 | import {createApp, element} from 'deku'
18 | import {createStore} from 'redux'
19 | import reducer from './reducer'
20 | import App from './app'
21 |
22 | // Create a redux store to handle actions
23 | let store = createStore(reducer)
24 |
25 | // Create a renderer
26 | let render = createApp(document.body, store.dispatch)
27 |
28 | // This renders the content into document.body
29 | render()
30 |
31 | // Update the UI
32 | render()
33 | ```
34 |
35 | ### Notes
36 |
37 | The container DOM element should:
38 |
39 | * **Not be the document.body**. You'll probably run into problems with other libraries. They'll often add elements to the `document.body` which can confuse the diff algorithm.
40 | * **Be empty**. All elements inside of the container will be removed when a virtual element is rendered into it. The renderer needs to have complete control of all of the elements within the container.
41 |
--------------------------------------------------------------------------------
/docs/api/diff.md:
--------------------------------------------------------------------------------
1 | # `diff`
2 |
3 | The `diff` object provides functions for comparing two virtual nodes. Mostly useful if you're creating your own renderer.
4 |
5 | ```js
6 | import {diff} from 'deku'
7 | ```
8 |
9 | ### Properties
10 |
11 | * [`diffNode`](#diffNode)
12 | * [`Actions`](#Actions)
13 |
14 | ## `diffNode(prevNode, nextNode)`
15 |
16 | Returns the difference between two virtual nodes as an array of actions that can be used by a renderer to patch a view.
17 |
18 | ### Arguments
19 |
20 | 1. `prevNode` _(VirtualElement)_: The current renderer vnode
21 | 2. `nextNode` _(VirtualElement)_: The updated vnode
22 |
23 | ### Returns
24 |
25 | `actions` _(Array)_: An array of `Action` objects that describe the change that needs to be made to update the view.
26 |
27 | ### Example
28 |
29 | ```js
30 | import {diff, element} from 'deku'
31 |
32 | const {diffNode, Actions} = diff
33 |
34 | let left = element('div', { class: 'foo' })
35 | let right = element('div', { class: 'bar' })
36 |
37 | let changes = diff(left, right)
38 |
39 | changes.forEach(action => {
40 | Actions.case({
41 | setAttribute: (name, value, previousValue) => {
42 | // update the attribute
43 | }
44 | }, action)
45 | })
46 | ```
47 |
48 | ## `Actions`
49 |
50 | An object containing union types for actions produced during the diff. You can create new actions using this object, but this is usually handled by `diffNode`.
51 |
52 | ### Example
53 |
54 | ```js
55 | import {diff, element} from 'deku'
56 |
57 | const {Actions} = diff
58 |
59 | // Create a new action.
60 | let action = Actions.setAttribute('class', 'foo', 'bar')
61 |
62 | // Switch between the different action types
63 | Actions.case({
64 | setAttribute: (name, value, previousValue) => {
65 | // Use the action
66 | }
67 | }, action)
68 | ```
69 |
--------------------------------------------------------------------------------
/docs/api/dom.md:
--------------------------------------------------------------------------------
1 | # `dom`
2 |
3 | The `dom` object provides functions for rendering elements to the DOM. These are lower-level functions that you generally won't need to access unless you're building your own version of `createApp`.
4 |
5 | ```js
6 | import {dom} from 'deku'
7 | ```
8 |
9 | ### Properties
10 |
11 | * `create`
12 | * `update`
13 |
14 | ## `create`
15 | `(vnode, path, dispatch, context) -> DOMElement`
16 |
17 | Create a DOM element from a virtual element.
18 |
19 | ## `update`
20 | `(dispatch, context) -> (DOMElement, action) -> DOMElement`
21 |
22 | Create a function to patch a DOM element using an action.
23 |
--------------------------------------------------------------------------------
/docs/api/element.md:
--------------------------------------------------------------------------------
1 | # `element(type, attributes, children)`
2 |
3 | Returns a `render` function that you can use to render elements within `DOMElement`. The function signature is compatible with JSX.
4 |
5 | ### Arguments
6 |
7 | 1. `type` _(String|Object)_: Each node in a tree has a type. This is only used when rendering the tree.
8 | 2. `attributes` _(Object)_ (Optional): The attributes of this node, similar to HTML attributes.
9 | 3. `children` _(Array)_ (Optional): An array of children. Each child should also be an `element`. Strings are also accepted for text nodes.
10 |
11 | ### Returns
12 |
13 | `vnode` _(Object)_: An object representing a node within a tree.
14 |
15 | ### Example
16 |
17 | ```js
18 | import {element} from 'deku'
19 |
20 | // Native elements
21 | element('div', { class: "greeting" }, [
22 | element('span', {}, ['Hello'])
23 | ])
24 |
25 | // Components
26 | let App = {
27 | render: ({ props }) =>
Hello {props.name}!
28 | }
29 |
30 | element(App, { name: "Tom" })
31 | ```
32 |
--------------------------------------------------------------------------------
/docs/api/index.md:
--------------------------------------------------------------------------------
1 | # API Reference
2 |
3 | * [dom](dom.md)
4 | * [string](string.md)
5 | * [element](element.md)
6 | * [diff](diff.md)
7 | * [vnode](vnode.md)
8 | * [createApp](create-app.md)
9 |
--------------------------------------------------------------------------------
/docs/api/string.md:
--------------------------------------------------------------------------------
1 | # `string`
2 |
3 | The `string` object provides functions for rendering virtual elements to a string.
4 |
5 | ```js
6 | import {string} from 'deku'
7 | ```
8 |
9 | ### Properties
10 |
11 | * [`render`](#-render-vnode-context)
12 |
13 | ## `render(vnode, [context])`
14 |
15 | This function renders a virtual element to a string. It will render components and call all hooks as normal. This can be used on the server to pre-render an app as HTML, and then replaced on the client.
16 |
17 | The `context` object will be passed into each component function.
18 |
19 | ### Arguments
20 |
21 | 1. `vnode` _(VirtualElement)_: A virtual element to render as a string.
22 | 2. `context` _(Object)_: You can use the context object to send shared state to every component. The `context` object should be immutable if possible as internally the renderer can provide extra optimizations.
23 |
24 | ### Returns
25 |
26 | `html` _(String)_: A string of HTML that can be rendered on the server.
27 |
28 | ### Example
29 |
30 | ```js
31 | import {string, element} from 'deku'
32 | import Sidebar from './sidebar'
33 | import Header from './header'
34 | import App from './app'
35 |
36 | let html = string.render(
37 |
38 |
39 |
40 |
41 |
42 | )
43 | ```
44 |
--------------------------------------------------------------------------------
/docs/api/vnode.md:
--------------------------------------------------------------------------------
1 | # `vnode`
2 |
3 | Contains helper functions for working with virtual nodes. Mostly useful if you're creating your own renderer.
4 |
5 | ```js
6 | import {vnode} from 'deku'
7 | ```
8 |
9 | ### Properties
10 |
11 | * create
12 | * createTextElement
13 | * createThunkElement
14 | * createEmptyElement
15 | * isThunk
16 | * isText
17 | * isEmpty
18 | * isSameThunk
19 | * isValidAttribute
20 | * createPath
21 |
22 | ## `create(type, attributes, children)`
23 |
24 | An alias for `element`.
25 |
26 | ## `createTextElement(text)`
27 |
28 | Create a virtual text element.
29 |
30 | ## `createThunkElement(component, key, props, children)`
31 |
32 | Create a virtual thunk element. These are lazily-rendered virtual elements.
33 |
34 | ## `createEmptyElement()`
35 |
36 | Create a virtual element that represents an empty space.
37 |
38 | ## `isThunk(vnode)`
39 |
40 | Check if a vnode is a thunk type.
41 |
42 | ## `isText(vnode)`
43 |
44 | Check if a vnode is a text type.
45 |
46 | ## `isEmpty(vnode)`
47 |
48 | Check if a vnode is an empty type.
49 |
50 | ## `isSameThunk(prevNode, nextNode)`
51 |
52 | Check to see if two virtual elements are both the same type of thunk.
53 |
54 | ## `isValidAttribute(value)`
55 |
56 | Check to see if an attribute is valid and should be rendered.
57 |
58 | ## `createPath(...paths)`
59 |
60 | Takes arguments and joins them with a `.` to produce a path.
61 |
--------------------------------------------------------------------------------
/docs/basics/components.md:
--------------------------------------------------------------------------------
1 | # Components
2 |
3 | Components are a way to define logical, re-usable pieces of your interface - tabs, buttons, forms. In Deku, components are just a special type of virtual element that is not rendered until it's needed. Internally, components are known as "thunks". This means that only the minimal number of virtual elements need to be re-created and patched on each render.
4 |
5 | In addition to providing a performance boost, you are able to hook into "lifecycle events" when a component is created, updated, or removed.
6 |
7 | Components are:
8 |
9 | * Plain objects with at least `render` function;
10 | * Able to provide a performance boost by caching the result of each render;
11 | * Uniquely identifiable using the `path` value, allowing you to store local state;
12 | * Able to trigger actions when they are created, updated, or removed;
13 | * Used like custom elements within your app
14 |
15 | Unlike React, components in Deku are completely stateless, there's no `setState` function or `this` used.
16 |
17 | ## Example
18 |
19 | Here's a simple `` component:
20 |
21 | ```js
22 | function render ({ props, children, context, path }) {
23 | return (
24 |
25 | {children}
26 |
27 | )
28 | }
29 |
30 | function onCreate ({ props, dispatch }) {
31 | dispatch({
32 | type: 'APP_STARTED'
33 | })
34 | }
35 |
36 | function onRemove ({ props, dispatch }) {
37 | dispatch({
38 | type: 'APP_STOPPED'
39 | })
40 | }
41 |
42 | export default {
43 | render,
44 | onCreate,
45 | onRemove
46 | }
47 | ```
48 |
49 | To use this component within other components, you simply import and compose it:
50 |
51 | ```js
52 | import App from './app'
53 |
54 | function render (model) {
55 | return
56 | }
57 |
58 | export {
59 | render
60 | }
61 | ```
62 |
63 | And you can do the same at top-level using `render`, while also setting the `context`:
64 |
65 | ```js
66 | render(, {
67 | theme: {
68 | color: 'red'
69 | }
70 | })
71 | ```
72 |
73 | ## Model
74 |
75 | The model is passed into the Component function and contains the state that you can use to create virtual nodes. The model is immutable
76 |
77 | ```js
78 | function render ({ props }) {
79 | return
Hello World
80 | }
81 | ```
82 |
83 | ### Properties
84 |
85 | #### `props`
86 |
87 | The values passed into your component as virtual element attributes. For example, passing these attributes into the component:
88 |
89 | ```js
90 |
91 | ```
92 |
93 | will yield this as `model.props`:
94 |
95 | ```json
96 | {
97 | "count": 5,
98 | "type": "tasks"
99 | }
100 | ```
101 |
102 | #### `children`
103 |
104 | The child nodes that are passed to the component.
105 |
106 | ```js
107 |
108 |
109 | Hello World
110 |
111 | ```
112 |
113 | The `children` property will always be an array:
114 |
115 | ```js
116 | [
117 | ,
118 | Hello World
119 | ]
120 | ```
121 |
122 | You can use this to render the passed in nodes somewhere within the rendered DOM.
123 |
124 | ```js
125 | function render ({ children }) {
126 | return
{children}
127 | }
128 | ```
129 |
130 | #### `path`
131 |
132 | The unique path to the component within the entire component tree.
133 |
134 | ```js
135 | function render ({ path }) {
136 | return Save
137 | }
138 | ```
139 |
140 | Paths in a tree are strings, like `0.1.5.2`. Each number represents the index of the node in the parent node, so you can use this to find a node within a tree. If a node within that path has a `key` attribute, we use that instead of the index so that the path is stable even if any elements move around.
141 |
142 | #### `context`
143 |
144 | An object that is available to every component in the tree.
145 |
--------------------------------------------------------------------------------
/docs/basics/elements.md:
--------------------------------------------------------------------------------
1 | # Virtual elements
2 |
3 | Virtual elements are objects that represent nodes in a tree, like the DOM. We call these 'virtual elements' because they create a fake DOM tree, a tree that looks like the real DOM but doesn't come with all the baggage of rendering real nodes.
4 |
5 | Virtual elements are objects:
6 |
7 | ```js
8 | {
9 | type: 'button',
10 | attributes: { class: 'Button' },
11 | children: ['Click me!']
12 | }
13 | ```
14 |
15 | They have:
16 |
17 | * a `type` that can be any primitive value (e.g. string, object, or function);
18 | * `attributes` that describe it's features;
19 | * and `children`, which is just an array of more nodes.
20 |
21 | This is how you would write it in HTML:
22 |
23 | ```html
24 |
25 | ```
26 |
27 | But these objects aren't easy to read or write so we can use the `element` function provided by Deku to make this a little nicer:
28 |
29 | ```js
30 | element('button', { class: "Button" }, ['Click Me!'])
31 | ```
32 |
33 | This function signature is the same that is expected by [JSX](/deku/docs/basics/JSX.html), so if you're using Babel you can use JSX. This will just compile back down to our simple `element` function above and end up becoming a plain object, just like what we started with:
34 |
35 | ```js
36 | {
37 | type: 'button',
38 | attributes: { class: 'Button' },
39 | children: ['Click me!']
40 | }
41 | ```
42 |
43 | Deku just requires objects that look like that, which means you can use any library you want to create those nodes. If you wanted to add some custom functionality, you can wrap the element function with your own. For example, this would allow you to write the `class` attribute as an array or object:
44 |
45 | ```js
46 | import {element} from 'deku'
47 | import classnames from 'classnames'
48 |
49 | export function magic (type, attributes, children) {
50 | let vnode = element(type, attributes, children)
51 |
52 | let classes = vnode.attributes.class
53 | if (classes) {
54 | vnode.attributes.class = classnames(classes)
55 | }
56 |
57 | return vnode
58 | }
59 | ```
60 |
--------------------------------------------------------------------------------
/docs/basics/events.md:
--------------------------------------------------------------------------------
1 | # Event handlers
2 |
3 | You can add event handlers using attributes. There are a number of attributes that Deku will recognize for you. These are treated as special attributes:
4 |
5 | ```js
6 | function render () {
7 | return
8 | }
9 |
10 | function save (event) {
11 | // event = MouseClick dom event
12 | }
13 |
14 | export { render }
15 | ```
16 |
17 | These handlers will be added and removed for you. With each render, if the handler doesn't match the new handler, they are swapped.
18 |
19 | ## Usage with Redux
20 |
21 | Redux is the preferred state management package for Deku. As `dispatch` is passed down to every component's [render](components.md) method, you can create a curried function for your event handlers to allow them to access this function.
22 |
23 | ```js
24 | let save = dispatch => event => {
25 | dispatch({
26 | type: 'SAVED'
27 | })
28 | }
29 |
30 | function render ({ dispatch }) {
31 | return
32 | }
33 |
34 | export { render }
35 | ```
36 |
37 | ```js
38 | // Assuming you passed the `dispatch` function to dom.createRenderer like below,
39 | // your components should be able to access this `dispatch` function like above.
40 | let render = dom.createRenderer(document.body, store.dispatch)
41 | render(, store.getState())
42 | ```
43 |
44 | ## How do I delegate events?
45 |
46 | The renderer doesn't automatically delegate events. To delegate events you can just add a handler on the parent element:
47 |
48 | ```js
49 | let render = model => {
50 | return (
51 |
52 |
1
53 |
2
54 |
3
55 |
56 | )
57 | }
58 |
59 | let onClick = event => {
60 | if (event.target.tagName === 'LI') {
61 | console.log('clicked')
62 | }
63 | }
64 | ```
65 |
66 | You can probably find some libraries on npm to make this easier too.
67 |
68 | ## How do I access my model in an event handler?
69 |
70 | If you want to send extra information to the handler you can curry or partially apply the handler function. We don't provide any special parameters to the event handlers, so it's as if you called `el.addEventListener` directly.
71 |
72 | ```js
73 | let render = model => {
74 | return
Hello World
75 | }
76 |
77 | let onClick = model => event => {
78 | console.log(model, event)
79 | }
80 | ```
81 |
82 | Because the handler is changing the function on every render, it will add the new event listener each time like you'd expect.
83 |
--------------------------------------------------------------------------------
/docs/basics/getting-started.md:
--------------------------------------------------------------------------------
1 | # Getting started
2 |
3 | Deku is a library that allows you to create and compose components that render virtual elements. Here's a basic example that we'll step through:
4 |
5 | ```js
6 | import {dom, element} from 'deku'
7 | let {createRenderer} = dom
8 | let render = createRenderer(document.body)
9 |
10 | let MyButton = {
11 | render: ({ children }) => {
12 | return
13 | }
14 | }
15 |
16 | render(
17 |
18 | Hello World!
19 |
20 | )
21 | ```
22 |
23 | Unlike React and other libraries, the virtual elements used in Deku are plain objects with no knowledge of what's rendering them. We'll cover this in more detail in the next section.
24 |
25 | ```js
26 | import {render} from 'deku'
27 | ```
28 |
29 | Then we're importing the renderer.
30 |
31 | Deku exports two functions: `render` and `renderString`. These are essentially two included renderers for virtual elements for rendering to the DOM.
32 |
33 | The render function takes a DOM element to use as a container, a virtual element, and an optional context argument:
34 |
35 | ```js
36 | render(DOMElement el, VirtualElement vnode, Object context)
37 | ```
38 |
39 | This function is curried, allowing you to set the paramters and create new functions:
40 |
41 | ```js
42 | let renderToContainer = render(containerEl)
43 | renderToContainer(
Hello!
)
44 | ```
45 |
46 | In the example we also created a component. Components in Deku are functions:
47 |
48 | ```js
49 | function MyButton (model, context) {
50 | return
51 | }
52 | ```
53 |
54 | They can also have other functions added to them called [lifecycle hooks](#lifecycle-hooks):
55 |
56 | ```js
57 | MyButton.onCreate = function () {
58 | console.log('created a new MyButton somewhere')
59 | }
60 | ```
61 |
62 | If you're using ES6 modules, we can also just directly export functions:
63 |
64 | ```js
65 | export default function MyButton (model) {
66 | return
67 | }
68 |
69 | export function onCreate () {
70 | console.log('created a new MyButton somewhere')
71 | }
72 | ```
73 |
--------------------------------------------------------------------------------
/docs/basics/index.md:
--------------------------------------------------------------------------------
1 | # Basics
2 |
3 | Learn how to get started using Deku.
4 |
5 | * [Getting Started](./getting-started.md)
6 | * [Virtual Elements](./elements.md)
7 | * [JSX](./jsx.md)
8 | * [Events](./events.md)
9 | * [Components](./components.md)
10 |
--------------------------------------------------------------------------------
/docs/basics/jsx.md:
--------------------------------------------------------------------------------
1 | # JSX
2 |
3 | The `element` function used to create virtual elements is compatible with [JSX] through [Babel]. When using Babel you just need to set the `jsxPragma`. This allows you to automatically transform HTML in your code into `element` calls.
4 |
5 | [JSX]: https://facebook.github.io/jsx/
6 | [Babel]: https://babeljs.io
7 |
8 | ## Setting up Babel
9 |
10 | Be sure to install [babel-preset-es2015](http://babeljs.io/docs/plugins/preset-es2015/) and [babel-plugin-transform-react-jsx](https://babeljs.io/docs/plugins/transform-react-jsx/).
11 |
12 | ```
13 | npm install babel-preset-es2015
14 | npm install babel-plugin-transform-react-jsx
15 | ```
16 |
17 | You will need to set the `pragma`. Here's an example `.babelrc` that sets the pragma:
18 |
19 | ```json
20 | {
21 | "presets": ["es2015"],
22 | "plugins": [
23 | ["transform-react-jsx", {"pragma": "element"}]
24 | ]
25 | }
26 | ```
27 |
28 | Alternatively, you can specify it in each of your files with a `@jsx` pragma comment:
29 |
30 | ```js
31 | /** @jsx element */
32 |
33 | import { element } from 'deku'
34 | ```
35 |
36 | From here, you can use [browserify] with [babelify] to build your final .js package.
37 |
38 | ```sh
39 | npm install --save browserify
40 | npm install --save babelify
41 |
42 | # compile the entry point `index.js` to `dist/application.js`
43 | browserify -t babelify index.js -o dist/application.js
44 | ```
45 |
46 | Alternatively, you can also use [babel-cli] to compile your JS files.
47 |
48 | [browserify]: https://www.npmjs.com/package/browserify
49 | [babelify]: https://www.npmjs.com/package/babelify
50 | [babel-cli]: https://www.npmjs.com/package/babel-cli
51 |
52 | ## How does it work?
53 |
54 | JSX is just syntax sugar for creating object trees. You can use Deku perfectly fine without JSX, but if you're already using Babel you can use JSX without any extra work.
55 |
56 | Instead of writing each `element` call:
57 |
58 | ```js
59 | function render (model) {
60 | return (
61 | element('button', { class: 'Button' }, [
62 | element('span', { class: 'Button-text' }, ['Click Me!'])
63 | ])
64 | )
65 | }
66 | ```
67 |
68 | You can write HTML:
69 |
70 | ```js
71 | function render (model) {
72 | return (
73 |
76 | )
77 | }
78 | ```
79 |
--------------------------------------------------------------------------------
/docs/basics/migrating.md:
--------------------------------------------------------------------------------
1 | # Migrating from v1
2 |
3 | There have been a few big changes to the API since version 1. The goal of the changes is to move Deku away from trying to be a kitchen-sink module and instead just do one small thing well.
4 |
5 | Here are the major changes:
6 |
7 | * `sources` and `.set` API have been removed
8 | * `app` API was removed. You no longer need to create a `tree` and call `.mount` whenever you want to render something different. Instead, you'll create a `render` method, and then just call that with your new virtual element.
9 | * `virtual-element` now exists within Deku and you don't need to depend on it separately. If people want to create 'magical' wrappers that handle attributes in a custom way (e.g. like `class`) they should just create a custom module.
10 | * `setState` has been removed. The reason why we needed something like `app` was because it managed the re-renders for you. Now there's only one way to re-render, and that's to call `render` again. You'll need to store local state on your own using the components `path` property.
11 | * `initialState` has been removed.
12 | * `defaultProps` has been removed.
13 | * `context` has been added.
14 | * Lifecycle hooks have changed.
15 |
16 |
17 | ## Lifecycle Hooks
18 |
19 | Having so many hooks before and after events meant that developers would need to start thinking about state over time again, rather than being declarative.
20 |
21 | #### Changed
22 | * `beforeMount(model)` -> `onCreate(model)`
23 | * `afterUpdate(prev, next, el)` -> `onUpdate(model)`
24 | * `beforeUnmount(model)` -> `onRemove(model)`
25 |
26 | #### Removed
27 | * `afterMount`
28 | * `beforeUpdate`
29 | * `beforeRender`
30 | * `afterRender`
31 |
32 | You can see how we don't worry about passing in previous and next data into the hooks. It turns out if you ever needed to do that, there was always a cleaner way to do it.
33 |
34 | ### How do I...?
35 |
36 | You should be able to still do everything you did before, but we don't pass you the DOM element. This was a deliberate choice. It was difficult to get it to work well so that the hook was called at just the right time. Instead, we'd rather not try and make a nice API for something that is inherently imperative and used for hacking at the DOM directly.
37 |
38 | This means you'll need to just add a class to the element you want to mutate, then call `querySelector` in the hook to find it. For example, if I wanted to get the element in the `onCreate` hook:
39 |
40 | ```js
41 | function onCreate ({ path }) {
42 | requestAnimationFrame(mutate(path))
43 | }
44 |
45 | function render ({ path }) {
46 | return
Hello
47 | }
48 |
49 | function mutate (path) {
50 | return () => {
51 | let el = document.querySelector('#' + path)
52 | // perform some side-effects
53 | }
54 | }
55 |
56 | export {
57 | onCreate,
58 | render
59 | }
60 | ```
61 |
62 | It would be even better to just dispatch an action from `onCreate` and let something else in your app handle it entirely. This is a trivial example, but you can see how it needs to wait until the next frame (so the element exists in the DOM).
63 |
--------------------------------------------------------------------------------
/docs/contributing.md:
--------------------------------------------------------------------------------
1 | # Contributing
2 |
3 | Anyone is free to contribute to the project. Here are some general guidelines for contributing:
4 |
5 | #### Feature requests
6 |
7 | If you have a feature you'd like added, open up an issue first to discuss it with everyone. If the idea is accepted, it would be great if you would take the time to try and implement the feature and submit a pull request.
8 |
9 | You should also add documentation for any new feature you'd added. PRs with passing tests are much, much more likely to get merged in.
10 |
11 | #### Testing
12 |
13 | The tests are run using [hihat](https://github.com/Jam3/hihat). This runs the tape tests in an Electron window with just the console. To run the tests, run `npm test`.
14 |
15 | #### Releasing
16 |
17 | Releases are created using [release-it](https://github.com/webpro/release-it). You'll need to install the `release-it` CLI tool. e.g. `release-it 2.1.3`
18 |
19 | ### CI
20 |
21 | Whenever you push a branch to dekujs/deku the tests are run in CircleCI. The unit tests are then run on many browsers at once using SauceLabs.
22 |
--------------------------------------------------------------------------------
/docs/motivation.md:
--------------------------------------------------------------------------------
1 | # Motivation
2 |
3 | React provides a great developer experience and enables a functional approach to rendering interfaces. However, it's just OOP in disguise. You're still hiding and encapsulating state within components, so you still run into the same problem of tracking down state changes and side-effects.
4 |
5 | This is great to help people switch to this new paradigm, but it's possible to remove a lot of complexity by avoiding older browsers and classical style.
6 |
7 | Deku has no opinion about how you store or manage your state unlike React. When something happens within the interface (e.g. a button is clicked) you handle the event and let some other part of your application change the state. This is a similar approach to Elm and makes Deku a natural fit for state management containers like Redux.
8 |
9 | The API was heavily based on React, and owes a lot of the recent internal changes to [virtex](https://github.com/ashaffer/virtex) and [snabbdom](https://github.com/paldepind/snabbdom).
10 |
--------------------------------------------------------------------------------
/docs/tips/innerhtml.md:
--------------------------------------------------------------------------------
1 | # innerHTML
2 |
3 | You sometimes need to set the `innerHTML` content of an element. For example, when you may transform some markdown content into a HTML string that you want rendered.
4 |
5 | You can use the special `innerHTML` attribute and it will insert the html for you.
6 |
7 | ```js
8 | let html = markdown('**Hello World**')
9 |
10 | ```
11 |
12 | Will produce:
13 |
14 | ```html
15 |
16 | Hello World
17 |
18 | ```
19 |
--------------------------------------------------------------------------------
/examples/basic/app.js:
--------------------------------------------------------------------------------
1 | import {h} from '../../src'
2 |
3 | /**
4 | * Takes some state and returns a virtual element
5 | */
6 |
7 | function view (state, dispatch) {
8 | return (
9 | h('div', {}, [
10 | h('div', {}, 'Counter: ' + state.count),
11 | h('button', {onClick: increment(dispatch)}, 'Increment'),
12 | h('button', {onClick: decrement(dispatch)}, 'Decrement')
13 | ])
14 | )
15 | }
16 |
17 | /**
18 | * Update the state
19 | */
20 |
21 | function update (state, action) {
22 | switch (action.type) {
23 | case 'INCREMENT':
24 | return {
25 | ...state,
26 | count: state.count + 10
27 | }
28 | case 'DECREMENT':
29 | return {
30 | ...state,
31 | count: state.count - 1
32 | }
33 | }
34 | return state
35 | }
36 |
37 | /**
38 | * Get the initial state
39 | */
40 |
41 | function init () {
42 | return {
43 | count: 10
44 | }
45 | }
46 |
47 | /**
48 | * Action creators
49 | */
50 |
51 | function increment (dispatch) {
52 | return e => dispatch({
53 | type: 'INCREMENT'
54 | })
55 | }
56 |
57 | function decrement (dispatch) {
58 | return e => dispatch({
59 | type: 'DECREMENT'
60 | })
61 | }
62 |
63 | export {view, update, init}
64 |
--------------------------------------------------------------------------------
/examples/basic/index.js:
--------------------------------------------------------------------------------
1 | import {createApp} from '../../src'
2 | import {view, update, init} from './app'
3 |
4 | /**
5 | * Create a DOM renderer for vnodes. It accepts a dispatch function as
6 | * a second parameter to handle all actions from the UI.
7 | */
8 |
9 | let render = createApp(document.body)
10 |
11 | /**
12 | * Update the UI with the latest state.
13 | */
14 |
15 | function main (state) {
16 | let vnode = view(state, action => {
17 | let nextState = update(state, action)
18 | main(nextState)
19 | })
20 | render(vnode)
21 | }
22 |
23 | /**
24 | * Initial render
25 | */
26 |
27 | main(init())
28 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "deku",
3 | "version": "2.0.0-rc16",
4 | "license": "MIT",
5 | "repository": "dekujs/deku",
6 | "description": "Render interfaces using pure functions and virtual DOM",
7 | "main": "lib/index.js",
8 | "jsnext:main": "es/index.js",
9 | "scripts": {
10 | "clean": "rimraf lib _book",
11 | "build": "npm run build:commonjs && npm run build:es",
12 | "build:commonjs": "cross-env BABEL_ENV=commonjs babel src --out-dir lib",
13 | "build:es": "cross-env BABEL_ENV=es babel src --out-dir es",
14 | "test": "cross-env BABEL_ENV=commonjs hihat test/index.js -- --debug -t babelify -p tap-dev-tool",
15 | "test:headless": "cross-env BABEL_ENV=commonjs browserify test/index.js -t babelify | tape-run",
16 | "test:browsers": "cross-env BABEL_ENV=commonjs zuul -- ./test/index.js",
17 | "test:lint": "standard src/**/*.js test/**/*.js | snazzy",
18 | "docs:install": "gitbook install",
19 | "docs:build": "npm run docs:install && gitbook build",
20 | "docs:serve": "npm run docs:install && gitbook serve",
21 | "docs:deploy": "npm run docs:build && gh-pages -d _book",
22 | "prepublish": "npm run clean && npm run build",
23 | "preversion": "npm run clean && npm run test:lint",
24 | "version": "npm run build",
25 | "postversion": "git push && git push --tags && npm run clean",
26 | "standalone": "browserify src/index.js -s deku -t babelify -o dist/deku.js",
27 | "example:basic": "budo examples/basic/index.js -- -t babelify"
28 | },
29 | "devDependencies": {
30 | "babel-cli": "6.3.17",
31 | "babel-plugin-check-es2015-constants": "^6.7.2",
32 | "babel-plugin-transform-es2015-arrow-functions": "^6.5.2",
33 | "babel-plugin-transform-es2015-block-scoped-functions": "^6.6.5",
34 | "babel-plugin-transform-es2015-block-scoping": "^6.7.1",
35 | "babel-plugin-transform-es2015-classes": "^6.6.5",
36 | "babel-plugin-transform-es2015-computed-properties": "^6.6.5",
37 | "babel-plugin-transform-es2015-destructuring": "^6.6.5",
38 | "babel-plugin-transform-es2015-duplicate-keys": "^6.6.4",
39 | "babel-plugin-transform-es2015-for-of": "^6.6.0",
40 | "babel-plugin-transform-es2015-function-name": "^6.5.0",
41 | "babel-plugin-transform-es2015-literals": "^6.5.0",
42 | "babel-plugin-transform-es2015-modules-commonjs": "^6.7.4",
43 | "babel-plugin-transform-es2015-object-super": "^6.6.5",
44 | "babel-plugin-transform-es2015-parameters": "^6.7.0",
45 | "babel-plugin-transform-es2015-shorthand-properties": "^6.5.0",
46 | "babel-plugin-transform-es2015-spread": "^6.6.5",
47 | "babel-plugin-transform-es2015-sticky-regex": "^6.5.0",
48 | "babel-plugin-transform-es2015-template-literals": "^6.6.5",
49 | "babel-plugin-transform-es2015-typeof-symbol": "^6.6.0",
50 | "babel-plugin-transform-es2015-unicode-regex": "^6.5.0",
51 | "babel-plugin-transform-react-jsx": "6.1.18",
52 | "babel-plugin-transform-regenerator": "^6.6.5",
53 | "babel-polyfill": "6.1.19",
54 | "babel-preset-stage-2": "6.1.18",
55 | "babelify": "7.2.0",
56 | "browserify": "13.0.0",
57 | "browserify-hmr": "^0.3.1",
58 | "budo": "7.1.0",
59 | "cross-env": "^1.0.7",
60 | "gh-pages": "0.8.0",
61 | "gitbook": "2.6.6",
62 | "hihat": "2.6.4",
63 | "is-dom": "1.0.5",
64 | "rimraf": "2.5.0",
65 | "snazzy": "2.0.1",
66 | "standard": "5.4.1",
67 | "tap-dev-tool": "1.3.0",
68 | "tape": "4.2.2",
69 | "tape-run": "2.1.0",
70 | "trigger-event": "1.0.0",
71 | "zuul": "3.9.0"
72 | },
73 | "dependencies": {
74 | "@f/create-element": "1.0.0",
75 | "@f/empty-element": "^1.0.0",
76 | "@f/foreach": "1.2.2",
77 | "@f/is-function": "1.1.1",
78 | "@f/is-null": "1.0.0",
79 | "@f/is-number": "1.1.1",
80 | "@f/is-string": "1.1.1",
81 | "@f/is-undefined": "1.1.1",
82 | "@f/is-valid-attr": "1.0.0",
83 | "@f/noop": "1.2.0",
84 | "@f/reduce-array": "^0.2.1",
85 | "@f/set-attribute": "1.0.1",
86 | "@f/to-array": "1.1.1",
87 | "dift": "0.1.12",
88 | "index-of": "0.2.0",
89 | "setify": "1.0.3",
90 | "union-type": "0.1.6"
91 | },
92 | "keywords": [
93 | "deku",
94 | "functional",
95 | "react",
96 | "virtual",
97 | "dom",
98 | "elm",
99 | "redux"
100 | ]
101 | }
102 |
--------------------------------------------------------------------------------
/src/app/index.js:
--------------------------------------------------------------------------------
1 | import * as dom from '../dom'
2 | import {diffNode} from '../diff'
3 | import empty from '@f/empty-element'
4 | import noop from '@f/noop'
5 |
6 | /**
7 | * Create a DOM renderer using a container element. Everything will be rendered
8 | * inside of that container. Returns a function that accepts new state that can
9 | * replace what is currently rendered.
10 | */
11 |
12 | export function createApp (container, handler = noop, options = {}) {
13 | let oldVnode = null
14 | let node = null
15 | let rootId = options.id || '0'
16 | let dispatch = effect => effect && handler(effect)
17 |
18 | if (container) {
19 | empty(container)
20 | }
21 |
22 | let update = (newVnode, context) => {
23 | let changes = diffNode(oldVnode, newVnode, rootId)
24 | node = changes.reduce(dom.updateElement(dispatch, context), node)
25 | oldVnode = newVnode
26 | return node
27 | }
28 |
29 | let create = (vnode, context) => {
30 | node = dom.createElement(vnode, rootId, dispatch, context)
31 | if (container) container.appendChild(node)
32 | oldVnode = vnode
33 | return node
34 | }
35 |
36 | return (vnode, context = {}) => {
37 | return node !== null
38 | ? update(vnode, context)
39 | : create(vnode, context)
40 | }
41 | }
42 |
--------------------------------------------------------------------------------
/src/diff/index.js:
--------------------------------------------------------------------------------
1 | import {isText, isThunk, isSameThunk, isNative, isEmpty, groupByKey, createPath} from '../element'
2 | import dift, * as diffActions from 'dift'
3 | import isUndefined from '@f/is-undefined'
4 | import isNull from '@f/is-null'
5 | import Type from 'union-type'
6 | let Any = () => true
7 | let Path = () => String
8 |
9 | /**
10 | * Patch actions
11 | */
12 |
13 | export let Actions = Type({
14 | setAttribute: [String, Any, Any],
15 | removeAttribute: [String, Any],
16 | insertChild: [Any, Number, Path],
17 | removeChild: [Number],
18 | updateChild: [Number, Array],
19 | updateChildren: [Array],
20 | insertBefore: [Number],
21 | replaceNode: [Any, Any, Path],
22 | removeNode: [Any],
23 | sameNode: [],
24 | updateThunk: [Any, Any, Path]
25 | })
26 |
27 | /**
28 | * Diff two attribute objects and return an array of actions that represent
29 | * changes to transform the old object into the new one.
30 | */
31 |
32 | export function diffAttributes (previous, next) {
33 | let { setAttribute, removeAttribute } = Actions
34 | let changes = []
35 | let pAttrs = previous.attributes
36 | let nAttrs = next.attributes
37 |
38 | for (let name in nAttrs) {
39 | if (nAttrs[name] !== pAttrs[name]) {
40 | changes.push(setAttribute(name, nAttrs[name], pAttrs[name]))
41 | }
42 | }
43 |
44 | for (let name in pAttrs) {
45 | if (!(name in nAttrs)) {
46 | changes.push(removeAttribute(name, pAttrs[name]))
47 | }
48 | }
49 |
50 | return changes
51 | }
52 |
53 | /**
54 | * Compare two arrays of virtual nodes and return an array of actions
55 | * to transform the left into the right. A starting path is supplied that use
56 | * recursively to build up unique paths for each node.
57 | */
58 |
59 | export function diffChildren (previous, next, parentPath) {
60 | let { insertChild, updateChild, removeChild, insertBefore, updateChildren } = Actions
61 | let { CREATE, UPDATE, MOVE, REMOVE } = diffActions
62 | let previousChildren = groupByKey(previous.children)
63 | let nextChildren = groupByKey(next.children)
64 | let key = a => a.key
65 | let changes = []
66 |
67 | function effect (type, prev, next, pos) {
68 | let nextPath = next
69 | ? createPath(parentPath, next.key == null ? next.index : next.key)
70 | : null
71 | switch (type) {
72 | case CREATE: {
73 | changes.push(insertChild(
74 | next.item,
75 | pos,
76 | nextPath
77 | ))
78 | break
79 | }
80 | case UPDATE: {
81 | let actions = diffNode(
82 | prev.item,
83 | next.item,
84 | nextPath
85 | )
86 | if (actions.length > 0) {
87 | changes.push(updateChild(prev.index, actions))
88 | }
89 | break
90 | }
91 | case MOVE: {
92 | let actions = diffNode(
93 | prev.item,
94 | next.item,
95 | nextPath
96 | )
97 | actions.push(insertBefore(pos))
98 | changes.push(updateChild(prev.index, actions))
99 | break
100 | }
101 | case REMOVE: {
102 | changes.push(removeChild(prev.index))
103 | break
104 | }
105 | }
106 | }
107 |
108 | dift(previousChildren, nextChildren, effect, key)
109 |
110 | return updateChildren(changes)
111 | }
112 |
113 | /**
114 | * Compare two virtual nodes and return an array of changes to turn the left
115 | * into the right.
116 | */
117 |
118 | export function diffNode (prev, next, path) {
119 | let {replaceNode, setAttribute, sameNode, removeNode, updateThunk} = Actions
120 |
121 | // No left node to compare it to
122 | // TODO: This should just return a createNode action
123 | if (isUndefined(prev)) {
124 | throw new Error('Left node must not be null or undefined')
125 | }
126 |
127 | // Bail out and skip updating this whole sub-tree
128 | if (prev === next) {
129 | return [sameNode()]
130 | }
131 |
132 | // Remove
133 | if (!isUndefined(prev) && isUndefined(next)) {
134 | return [removeNode(prev)]
135 | }
136 |
137 | // Replace with empty
138 | if (!isNull(prev) && isNull(next) || isNull(prev) && !isNull(next)) {
139 | return [replaceNode(prev, next, path)]
140 | }
141 |
142 | // Replace
143 | if (prev.type !== next.type) {
144 | return [replaceNode(prev, next, path)]
145 | }
146 |
147 | // Native
148 | if (isNative(next)) {
149 | if (prev.tagName !== next.tagName) {
150 | return [replaceNode(prev, next, path)]
151 | }
152 | let changes = diffAttributes(prev, next)
153 | changes.push(diffChildren(prev, next, path))
154 | return changes
155 | }
156 |
157 | // Text
158 | if (isText(next)) {
159 | let changes = []
160 | if (prev.nodeValue !== next.nodeValue) {
161 | changes.push(setAttribute('nodeValue', next.nodeValue, prev.nodeValue))
162 | }
163 | return changes
164 | }
165 |
166 | // Thunk
167 | if (isThunk(next)) {
168 | let changes = []
169 | if (isSameThunk(prev, next)) {
170 | changes.push(updateThunk(prev, next, path))
171 | } else {
172 | changes.push(replaceNode(prev, next, path))
173 | }
174 | return changes
175 | }
176 |
177 | // Empty
178 | if (isEmpty(next)) {
179 | return []
180 | }
181 |
182 | return []
183 | }
184 |
--------------------------------------------------------------------------------
/src/dom/create.js:
--------------------------------------------------------------------------------
1 | import createNativeElement from '@f/create-element'
2 | import {createPath} from '../element'
3 | import {setAttribute} from './setAttribute'
4 | import isUndefined from '@f/is-undefined'
5 | import isString from '@f/is-string'
6 | import isNumber from '@f/is-number'
7 | import isNull from '@f/is-null'
8 | const cache = {}
9 |
10 | /**
11 | * Create a real DOM element from a virtual element, recursively looping down.
12 | * When it finds custom elements it will render them, cache them, and keep going,
13 | * so they are treated like any other native element.
14 | */
15 |
16 | export function createElement (vnode, path, dispatch, context) {
17 | switch (vnode.type) {
18 | case 'text':
19 | return createTextNode(vnode.nodeValue)
20 | case 'empty':
21 | return getCachedElement('noscript')
22 | case 'thunk':
23 | return createThunk(vnode, path, dispatch, context)
24 | case 'native':
25 | return createHTMLElement(vnode, path, dispatch, context)
26 | }
27 | }
28 |
29 | function getCachedElement (type) {
30 | let cached = cache[type]
31 | if (isUndefined(cached)) {
32 | cached = cache[type] = createNativeElement(type)
33 | }
34 | return cached.cloneNode(false)
35 | }
36 |
37 | function createTextNode (text) {
38 | let value = isString(text) || isNumber(text)
39 | ? text
40 | : ''
41 | return document.createTextNode(value)
42 | }
43 |
44 | function createThunk (vnode, path, dispatch, context) {
45 | let { props, children } = vnode
46 | let { onCreate } = vnode.options
47 | let model = {
48 | children,
49 | props,
50 | path,
51 | dispatch,
52 | context
53 | }
54 | let output = vnode.fn(model)
55 | let childPath = createPath(path, output.key || '0')
56 | let DOMElement = createElement(output, childPath, dispatch, context)
57 | if (onCreate) dispatch(onCreate(model))
58 | vnode.state = {
59 | vnode: output,
60 | model: model
61 | }
62 | return DOMElement
63 | }
64 |
65 | function createHTMLElement (vnode, path, dispatch, context) {
66 | let { tagName, attributes, children } = vnode
67 | let DOMElement = getCachedElement(tagName)
68 |
69 | for (let name in attributes) {
70 | setAttribute(DOMElement, name, attributes[name])
71 | }
72 |
73 | children.forEach((node, index) => {
74 | if (isNull(node) || isUndefined(node)) return
75 | let childPath = createPath(path, node.key || index)
76 | let child = createElement(node, childPath, dispatch, context)
77 | DOMElement.appendChild(child)
78 | })
79 |
80 | return DOMElement
81 | }
82 |
--------------------------------------------------------------------------------
/src/dom/events.js:
--------------------------------------------------------------------------------
1 | /**
2 | * Special attributes that map to DOM events.
3 | */
4 |
5 | export default {
6 | onAbort: 'abort',
7 | onAnimationStart: 'animationstart',
8 | onAnimationIteration: 'animationiteration',
9 | onAnimationEnd: 'animationend',
10 | onBlur: 'blur',
11 | onCanPlay: 'canplay',
12 | onCanPlayThrough: 'canplaythrough',
13 | onChange: 'change',
14 | onClick: 'click',
15 | onContextMenu: 'contextmenu',
16 | onCopy: 'copy',
17 | onCut: 'cut',
18 | onDoubleClick: 'dblclick',
19 | onDrag: 'drag',
20 | onDragEnd: 'dragend',
21 | onDragEnter: 'dragenter',
22 | onDragExit: 'dragexit',
23 | onDragLeave: 'dragleave',
24 | onDragOver: 'dragover',
25 | onDragStart: 'dragstart',
26 | onDrop: 'drop',
27 | onDurationChange: 'durationchange',
28 | onEmptied: 'emptied',
29 | onEncrypted: 'encrypted',
30 | onEnded: 'ended',
31 | onError: 'error',
32 | onFocus: 'focus',
33 | onInput: 'input',
34 | onInvalid: 'invalid',
35 | onKeyDown: 'keydown',
36 | onKeyPress: 'keypress',
37 | onKeyUp: 'keyup',
38 | onLoad: 'load',
39 | onLoadedData: 'loadeddata',
40 | onLoadedMetadata: 'loadedmetadata',
41 | onLoadStart: 'loadstart',
42 | onPause: 'pause',
43 | onPlay: 'play',
44 | onPlaying: 'playing',
45 | onProgress: 'progress',
46 | onMouseDown: 'mousedown',
47 | onMouseEnter: 'mouseenter',
48 | onMouseLeave: 'mouseleave',
49 | onMouseMove: 'mousemove',
50 | onMouseOut: 'mouseout',
51 | onMouseOver: 'mouseover',
52 | onMouseUp: 'mouseup',
53 | onPaste: 'paste',
54 | onRateChange: 'ratechange',
55 | onReset: 'reset',
56 | onScroll: 'scroll',
57 | onSeeked: 'seeked',
58 | onSeeking: 'seeking',
59 | onSubmit: 'submit',
60 | onStalled: 'stalled',
61 | onSuspend: 'suspend',
62 | onTimeUpdate: 'timeupdate',
63 | onTransitionEnd: 'transitionend',
64 | onTouchCancel: 'touchcancel',
65 | onTouchEnd: 'touchend',
66 | onTouchMove: 'touchmove',
67 | onTouchStart: 'touchstart',
68 | onVolumeChange: 'volumechange',
69 | onWaiting: 'waiting',
70 | onWheel: 'wheel'
71 | }
72 |
--------------------------------------------------------------------------------
/src/dom/index.js:
--------------------------------------------------------------------------------
1 | import {createElement} from './create'
2 | import {updateElement} from './update'
3 |
4 | export {
5 | createElement,
6 | updateElement
7 | }
8 |
--------------------------------------------------------------------------------
/src/dom/setAttribute.js:
--------------------------------------------------------------------------------
1 | import setNativeAttribute from '@f/set-attribute'
2 | import isValidAttribute from '@f/is-valid-attr'
3 | import isFunction from '@f/is-function'
4 | import indexOf from 'index-of'
5 | import setValue from 'setify'
6 | import events from './events'
7 |
8 | export function removeAttribute (DOMElement, name, previousValue) {
9 | let eventType = events[name]
10 | if (eventType && isFunction(previousValue)) {
11 | DOMElement.removeEventListener(eventType, previousValue)
12 | return
13 | }
14 | switch (name) {
15 | case 'checked':
16 | case 'disabled':
17 | case 'selected':
18 | DOMElement[name] = false
19 | break
20 | case 'innerHTML':
21 | case 'nodeValue':
22 | case 'value':
23 | DOMElement[name] = ''
24 | break
25 | default:
26 | DOMElement.removeAttribute(name)
27 | break
28 | }
29 | }
30 |
31 | export function setAttribute (DOMElement, name, value, previousValue) {
32 | let eventType = events[name]
33 | if (value === previousValue) {
34 | return
35 | }
36 | if (eventType) {
37 | if (isFunction(previousValue)) {
38 | DOMElement.removeEventListener(eventType, previousValue)
39 | }
40 | DOMElement.addEventListener(eventType, value)
41 | return
42 | }
43 | if (!isValidAttribute(value)) {
44 | removeAttribute(DOMElement, name, previousValue)
45 | return
46 | }
47 | switch (name) {
48 | case 'checked':
49 | case 'disabled':
50 | case 'innerHTML':
51 | case 'nodeValue':
52 | DOMElement[name] = value
53 | break
54 | case 'selected':
55 | DOMElement.selected = value
56 | // Fix for IE/Safari where select is not correctly selected on change
57 | if (DOMElement.tagName === 'OPTION' && DOMElement.parentNode) {
58 | let select = DOMElement.parentNode
59 | select.selectedIndex = indexOf(select.options, DOMElement)
60 | }
61 | break
62 | case 'value':
63 | setValue(DOMElement, value)
64 | break
65 | default:
66 | setNativeAttribute(DOMElement, name, value)
67 | break
68 | }
69 | }
70 |
--------------------------------------------------------------------------------
/src/dom/update.js:
--------------------------------------------------------------------------------
1 | import {setAttribute, removeAttribute} from './setAttribute'
2 | import {isThunk, createPath} from '../element'
3 | import {Actions, diffNode} from '../diff'
4 | import reduceArray from '@f/reduce-array'
5 | import {createElement} from './create'
6 | import toArray from '@f/to-array'
7 | import forEach from '@f/foreach'
8 | import noop from '@f/noop'
9 |
10 | /**
11 | * Modify a DOM element given an array of actions.
12 | */
13 |
14 | export function updateElement (dispatch, context) {
15 | return (DOMElement, action) => {
16 | Actions.case({
17 | sameNode: noop,
18 | setAttribute: (name, value, previousValue) => {
19 | setAttribute(DOMElement, name, value, previousValue)
20 | },
21 | removeAttribute: (name, previousValue) => {
22 | removeAttribute(DOMElement, name, previousValue)
23 | },
24 | insertBefore: (index) => {
25 | insertAtIndex(DOMElement.parentNode, index, DOMElement)
26 | },
27 | updateChildren: (changes) => {
28 | updateChildren(DOMElement, changes, dispatch, context)
29 | },
30 | updateThunk: (prev, next, path) => {
31 | DOMElement = updateThunk(DOMElement, prev, next, path, dispatch, context)
32 | },
33 | replaceNode: (prev, next, path) => {
34 | let newEl = createElement(next, path, dispatch, context)
35 | let parentEl = DOMElement.parentNode
36 | if (parentEl) parentEl.replaceChild(newEl, DOMElement)
37 | DOMElement = newEl
38 | removeThunks(prev, dispatch)
39 | },
40 | removeNode: (prev) => {
41 | removeThunks(prev)
42 | DOMElement.parentNode.removeChild(DOMElement)
43 | DOMElement = null
44 | }
45 | }, action)
46 |
47 | return DOMElement
48 | }
49 | }
50 |
51 | /**
52 | * Update all the children of a DOMElement using an array of actions
53 | */
54 |
55 | function updateChildren (DOMElement, changes, dispatch, context) {
56 | // Create a clone of the children so we can reference them later
57 | // using their original position even if they move around
58 | let childNodes = toArray(DOMElement.childNodes)
59 | changes.forEach(change => {
60 | Actions.case({
61 | insertChild: (vnode, index, path) => {
62 | insertAtIndex(DOMElement, index, createElement(vnode, path, dispatch, context))
63 | },
64 | removeChild: (index) => {
65 | DOMElement.removeChild(childNodes[index])
66 | },
67 | updateChild: (index, actions) => {
68 | let _update = updateElement(dispatch, context)
69 | actions.forEach(action => _update(childNodes[index], action))
70 | }
71 | }, change)
72 | })
73 | }
74 |
75 | /**
76 | * Update a thunk and only re-render the subtree if needed.
77 | */
78 |
79 | function updateThunk (DOMElement, prev, next, path, dispatch, context) {
80 | let { props, children } = next
81 | let { onUpdate } = next.options
82 | let prevNode = prev.state.vnode
83 | let model = {
84 | children,
85 | props,
86 | path,
87 | dispatch,
88 | context
89 | }
90 | let nextNode = next.fn(model)
91 | let changes = diffNode(prevNode, nextNode, createPath(path, '0'))
92 | DOMElement = reduceArray(updateElement(dispatch, context), DOMElement, changes)
93 | if (onUpdate) dispatch(onUpdate(model))
94 | next.state = {
95 | vnode: nextNode,
96 | model: model
97 | }
98 | return DOMElement
99 | }
100 |
101 | /**
102 | * Recursively remove all thunks
103 | */
104 |
105 | function removeThunks (vnode, dispatch) {
106 | while (isThunk(vnode)) {
107 | let onRemove = vnode.options.onRemove
108 | let { model } = vnode.state
109 | if (onRemove) dispatch(onRemove(model))
110 | vnode = vnode.state.vnode
111 | }
112 | if (vnode.children) {
113 | forEach(vnode.children, child => removeThunks(child, dispatch))
114 | }
115 | }
116 |
117 | /**
118 | * Slightly nicer insertBefore
119 | */
120 |
121 | export let insertAtIndex = (parent, index, el) => {
122 | var target = parent.childNodes[index]
123 | if (target) {
124 | parent.insertBefore(el, target)
125 | } else {
126 | parent.appendChild(el)
127 | }
128 | }
129 |
--------------------------------------------------------------------------------
/src/element/index.js:
--------------------------------------------------------------------------------
1 | import isUndefined from '@f/is-undefined'
2 | import reduceArray from '@f/reduce-array'
3 | import isString from '@f/is-string'
4 | import isNumber from '@f/is-number'
5 | import isNull from '@f/is-null'
6 |
7 | /**
8 | * This function lets us create virtual nodes using a simple
9 | * syntax. It is compatible with JSX transforms so you can use
10 | * JSX to write nodes that will compile to this function.
11 | *
12 | * let node = element('div', { id: 'foo' }, [
13 | * element('a', { href: 'http://google.com' },
14 | * element('span', {}, 'Google'),
15 | * element('b', {}, 'Link')
16 | * )
17 | * ])
18 | */
19 |
20 | export function create (type, attributes, ...children) {
21 | if (!type) throw new TypeError('element() needs a type.')
22 | attributes = attributes || {}
23 | children = reduceArray(reduceChildren, [], children || [])
24 |
25 | let key = isString(attributes.key) || isNumber(attributes.key)
26 | ? attributes.key
27 | : null
28 |
29 | delete attributes.key
30 |
31 | if (typeof type === 'object') {
32 | return createThunkElement(type.render, key, attributes, children, type)
33 | }
34 |
35 | if (typeof type === 'function') {
36 | return createThunkElement(type, key, attributes, children, type)
37 | }
38 |
39 | return {
40 | type: 'native',
41 | tagName: type,
42 | attributes,
43 | children,
44 | key
45 | }
46 | }
47 |
48 | /**
49 | * Cleans up the array of child elements.
50 | * - Flattens nested arrays
51 | * - Converts raw strings and numbers into vnodes
52 | * - Filters out undefined elements
53 | */
54 |
55 | function reduceChildren (children, vnode) {
56 | if (isString(vnode) || isNumber(vnode)) {
57 | children.push(createTextElement(vnode))
58 | } else if (isNull(vnode)) {
59 | children.push(createEmptyElement())
60 | } else if (Array.isArray(vnode)) {
61 | children = [...children, ...(vnode.reduce(reduceChildren, []))]
62 | } else if (isUndefined(vnode)) {
63 | throw new Error(`vnode can't be undefined. Did you mean to use null?`)
64 | } else {
65 | children.push(vnode)
66 | }
67 | return children
68 | }
69 |
70 | /**
71 | * Text nodes are stored as objects to keep things simple
72 | */
73 |
74 | export function createTextElement (text) {
75 | return {
76 | type: 'text',
77 | nodeValue: text
78 | }
79 | }
80 |
81 | /**
82 | * Text nodes are stored as objects to keep things simple
83 | */
84 |
85 | export function createEmptyElement () {
86 | return {
87 | type: 'empty'
88 | }
89 | }
90 |
91 | /**
92 | * Lazily-rendered virtual nodes
93 | */
94 |
95 | export function createThunkElement (fn, key, props, children, options) {
96 | return {
97 | type: 'thunk',
98 | fn,
99 | children,
100 | props,
101 | options,
102 | key
103 | }
104 | }
105 |
106 | /**
107 | * Functional type checking
108 | */
109 |
110 | export let isThunk = (node) => {
111 | return node.type === 'thunk'
112 | }
113 |
114 | export let isText = (node) => {
115 | return node.type === 'text'
116 | }
117 |
118 | export let isEmpty = (node) => {
119 | return node.type === 'empty'
120 | }
121 |
122 | export let isNative = (node) => {
123 | return node.type === 'native'
124 | }
125 |
126 | export let isSameThunk = (left, right) => {
127 | return isThunk(left) && isThunk(right) && left.fn === right.fn
128 | }
129 |
130 | /**
131 | * Group an array of virtual elements by their key, using index as a fallback.
132 | */
133 |
134 | export let groupByKey = (children) => {
135 | let iterator = (acc, child, i) => {
136 | if (!isUndefined(child) && child !== false) {
137 | let key = isNull(child) ? i : (child.key || i)
138 | acc.push({
139 | key: String(key),
140 | item: child,
141 | index: i
142 | })
143 | }
144 | return acc
145 | }
146 |
147 | return reduceArray(iterator, [], children)
148 | }
149 |
150 | /**
151 | * Create a node path, eg. (23,5,2,4) => '23.5.2.4'
152 | */
153 |
154 | export let createPath = (...args) => {
155 | return args.join('.')
156 | }
157 |
--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
1 | import * as diff from './diff'
2 | import * as vnode from './element'
3 | import * as string from './string'
4 | import * as dom from './dom'
5 | import {createApp} from './app'
6 |
7 | const element = vnode.create
8 | const h = vnode.create
9 |
10 | export {
11 | createApp,
12 | element,
13 | string,
14 | vnode,
15 | diff,
16 | dom,
17 | h
18 | }
19 |
--------------------------------------------------------------------------------
/src/string/index.js:
--------------------------------------------------------------------------------
1 | import {renderString} from './renderString'
2 |
3 | const render = renderString
4 |
5 | export {
6 | render
7 | }
8 |
--------------------------------------------------------------------------------
/src/string/renderString.js:
--------------------------------------------------------------------------------
1 | import isValidAttribute from '@f/is-valid-attr'
2 | import isNull from '@f/is-null'
3 |
4 | /**
5 | * Turn an object of key/value pairs into a HTML attribute string. This
6 | * function is responsible for what attributes are allowed to be rendered and
7 | * should handle any other special cases specific to deku.
8 | */
9 |
10 | function attributesToString (attributes) {
11 | var str = ''
12 | for (var name in attributes) {
13 | let value = attributes[name]
14 | if (name === 'innerHTML') continue
15 | if (isValidAttribute(value)) str += (' ' + name + '="' + attributes[name] + '"')
16 | }
17 | return str
18 | }
19 |
20 | /**
21 | * Render a virtual element to a string. You can pass in an option state context
22 | * object that will be given to all components.
23 | */
24 |
25 | export function renderString (vnode, context, path = '0') {
26 | switch (vnode.type) {
27 | case 'text':
28 | return renderTextNode(vnode)
29 | case 'empty':
30 | return renderEmptyNode()
31 | case 'thunk':
32 | return renderThunk(vnode, path, context)
33 | case 'native':
34 | return renderHTML(vnode, path, context)
35 | }
36 | }
37 |
38 | function renderTextNode (vnode) {
39 | return vnode.nodeValue
40 | }
41 |
42 | function renderEmptyNode () {
43 | return ''
44 | }
45 |
46 | function renderThunk (vnode, path, context) {
47 | let { props, children } = vnode
48 | let output = vnode.fn({ children, props, path, context })
49 | return renderString(output, context, path)
50 | }
51 |
52 | function renderHTML (vnode, path, context) {
53 | let {attributes, tagName, children} = vnode
54 | let innerHTML = attributes.innerHTML
55 | let str = '<' + tagName + attributesToString(attributes) + '>'
56 |
57 | if (innerHTML) {
58 | str += innerHTML
59 | } else {
60 | str += children.map((child, i) => renderString(child, context, path + '.' + (isNull(child.key) ? i : child.key))).join('')
61 | }
62 |
63 | str += ''
64 | return str
65 | }
66 |
--------------------------------------------------------------------------------
/test/app/index.js:
--------------------------------------------------------------------------------
1 | /* eslint-disable react/prop-types */
2 | /** @jsx h */
3 | import test from 'tape'
4 | import {createApp} from '../../src/app'
5 | import {create as h} from '../../src/element'
6 |
7 | test('rendering elements', t => {
8 | let el = document.createElement('div')
9 | let render = createApp(el)
10 |
11 | render()
12 | t.equal(el.innerHTML, '', 'rendered')
13 |
14 | render()
15 | t.equal(el.innerHTML, '', 'attributed added')
16 |
17 | render(
',
137 | 'rendered html'
138 | )
139 |
140 | t.end()
141 | })
142 |
143 | test('context should be passed down all elements when rendered as a string', t => {
144 | let Form = {
145 | render ({ props, context }) {
146 | return