Lots of random changes...

- Many improvements to devtools, including dark-mode logo, tabs, and
  embedded gitter chat

- Added componentWillMount callback

- Make createTree([]) be treated as fragment with children

Author: tbranyen

CONTRIBUTING.md

@@ -22,6 +22,9 @@ sed -i -e 's/1.0.0-beta.8/1.0.0-beta.9/g' **/lib/*.js
 # Update the root package version.
 sed -i -e 's/1.0.0-beta.8/1.0.0-beta.9/g' ./package.json
 
+# Update the DevTools version. It cannot use letters or dashes.
+sed -i -e 's/1.0.0.8/1.0.0.9/g' ./packages/diffhtml-devtools/chrome-extension/manifest.json
+
 # Make a descriptive commit.
 git commit -am"Update JavaScript and REAMDE files to 1.0.0-beta.9"
 ```

docs/api.html

@@ -300,19 +300,45 @@ <h1>
 
         <hr></hr>
 
-        <section id="content"><h1 id="core-api-a-classgithub-hrefhttpsgithubcomtbranyendiffhtmltreemasterpackagesdiffhtmli-classfa-fa-githubia">Core API <a class="github" href="https://github.com/tbranyen/diffhtml/tree/master/packages/diffhtml"><i class="fa fa-github"></i></a></h1>
-<p>This reference contains all stable API documentation which is up-to-date with
-the latest release. The core was designed to be minimal and familiar if you&#39;ve
-used browser DOM APIs such as <code>innerHTML</code> and <code>addEventListener</code>.</p>
+        <section id="content"><h1 id="a-hrefapihtmlcore-apia-a-classgithub-hrefhttpsgithubcomtbranyendiffhtmltreemasterpackagesdiffhtmli-classfa-fa-githubia"><a href="/api.html">Core API</a> <a class="github" href="https://github.com/tbranyen/diffhtml/tree/master/packages/diffhtml"><i class="fa fa-github"></i></a></h1>
+<p>This documentation covers the core public API. This page stays up-to-date with
+the latest version. All of these methods work in the browser, with JSDOM, and
+directly in Node.</p>
+<pre><code class="language-sh">npm install diffhtml</code></pre>
+<p>Some diffHTML lingo to be aware of:</p>
+<ul>
+<li><p><strong>Transaction</strong>: A class structure which represents a set of changes to the
+DOM.</p>
+</li>
+<li><p><strong>VTree</strong>: Virtual Tree, represents the shape of a DOM node, Component,
+etc. These objects are created when diffHTML first loads and help regulate
+memory usage.</p>
+</li>
+<li><p><strong>Mount</strong>: Most commonly a DOM node that you want to update, but can also be
+VTrees and other types.</p>
+</li>
+</ul>
 <p><a name="inner-html"></a></p>
 <hr></hr>
-<h2 id="a-hrefinner-htmlinnerhtmla-domnode-markup-options"><a href="#inner-html">innerHTML</a> <strong><code>(domNode, markup, options)</code></strong></h2>
-<p>Replaces the contents of a DOM node with the passed in markup, but will only
-update changed content and structure. Works like the browser&#39;s <code>innerHTML</code> only
-changing the element&#39;s children, but not the containing element. If you want to
-control the entire tag, use 
-    <a href="#outer-html" title="null"><code>outerHTML</code></a>
-  .</p>
+<h2 id="a-hrefinner-htmlinnerhtmla-mount-input-options"><a href="#inner-html">innerHTML</a> <strong><code>(mount, input, options)</code></strong></h2>
+<p>The <code>innerHTML</code> and <code>outerHTML</code> methods are the most common to use. They allow
+you to mimic the respective browser feature, where you replace the contents of
+a DOM node and in the case of <code>outerHTML</code> replace the top-level element
+attributes as well.  You may call this once in a complex application where the
+individual components re-render themselves, or in a game you would call this on
+every render tick, if you&#39;re building something simple, you can call it
+whenever the state changes.</p>
+<p>These methods can work in the browser and browser-like environments like JSDOM.
+An interesting feature is that you can pass in more than just DOM nodes. This
+comes in handy for advanced use cases such as</p>
+<p>What&#39;s nice about these methods is that all renders go through the same
+scheduling pipeline and VTrees are shared across all other renders.</p>
+<p>By calling these methods you are signaling intent that you want the mount to
+reflect the incoming input.</p>
+<ul>
+<li>Creating and scheduling a render transaction</li>
+<li></li>
+</ul>
 <h3 id="arguments">Arguments</h3>
 <table>
 <thead>
@@ -322,27 +348,27 @@ <h3 id="arguments">Arguments</h3>
 </tr>
 </thead>
 <tbody><tr>
-<td><strong>domNode</strong></td>
-<td>The root DOM Node to change the child contents of, but not the element itself.</td>
+<td><strong>mount</strong></td>
+<td>The root DOM node to update children in, but not the node itself.</td>
 </tr>
 <tr>
 <td><strong>input</strong></td>
-<td>New markup to replace into <strong>domNode</strong>.</td>
+<td>New markup to replace into <strong>mount</strong>.</td>
 </tr>
 <tr>
 <td><strong>options</strong></td>
-<td><ul><li><strong>tasks:</strong> An array of tasks to run. Can swap these out completely to run custom logic instead.</li><li><strong>parser:</strong> Settings which influence the HTML parser. No parser settings available in the runtime build.</li></ul></td>
+<td><ul><li><strong>tasks:</strong> An array of tasks to run. Can swap these out to modify the render flow.</li><li><strong>parser:</strong> Settings which influence the HTML parser.</li></ul></td>
 </tr>
 </tbody></table>
-<h3 id="example">Example</h3>
+<h3 id="examples">Examples</h3>
 <pre><code class="language-js">import { innerHTML } from &#39;diffhtml&#39;;
 
 innerHTML(document.body, `
   &lt;h1&gt;Hello world!&lt;/h1&gt;
 `);</code></pre>
 <p><a name="outer-html"></a></p>
 <hr></hr>
-<h2 id="a-hrefouter-htmlouterhtmla-domnode-markup-options"><a href="#outer-html">outerHTML</a> <strong><code>(domNode, markup, options)</code></strong></h2>
+<h2 id="a-hrefouter-htmlouterhtmla-mount-input-options"><a href="#outer-html">outerHTML</a> <strong><code>(mount, input, options)</code></strong></h2>
 <p>Replaces the contents of a DOM node with the passed in markup, only updates
 what has changed. Additionally updates the attributes of the parent. If the
 element you&#39;re modifying has a parent, you may also change the element type,
@@ -358,16 +384,16 @@ <h3 id="arguments-1">Arguments</h3>
 </tr>
 </thead>
 <tbody><tr>
-<td><strong>domNode</strong></td>
-<td>A DOM Node to change.</td>
+<td><strong>mount</strong></td>
+<td>The root DOM node to update including attributes and children.</td>
 </tr>
 <tr>
-<td><strong>markup</strong></td>
-<td>New markup to replace the entire <code>domNode</code> with.</td>
+<td><strong>input</strong></td>
+<td>New markup to replace into <strong>mount</strong>.</td>
 </tr>
 <tr>
 <td><strong>options</strong></td>
-<td><ul><li><strong>tasks:</strong> An array of tasks to run. Can swap these out completely to run custom logic instead.</li><li><strong>parser:</strong> Settings which influence the HTML parser, not available with the runtime build.</li></ul></td>
+<td><ul><li><strong>tasks:</strong> An array of tasks to run. Can swap these out to modify the render flow.</li><li><strong>parser:</strong> Settings which influence the HTML parser.</li></ul></td>
 </tr>
 </tbody></table>
 <p><a name="html"></a></p>
@@ -386,7 +412,7 @@ <h2 id="a-hrefhtmlhtmla-markup"><a href="#html">html</a> <strong><code>(markup)<
 after it, like the example below, it will be automatically trimmed. If you
 provide multiple elements, the whitespace becomes</p>
 <p>A simple example of its usage along with interpolation.</p>
-<pre><code class="language-js">html`
+<pre><code class="language-js">const vTree = html`
   &lt;body&gt;
     &lt;center style=${{ fontSize: &#39;11px&#39; }}&gt;Hello world&lt;/center&gt;
   &lt;/body&gt;
@@ -406,15 +432,13 @@ <h3 id="arguments-2">Arguments</h3>
 <p><a name="use"></a></p>
 <hr></hr>
 <h2 id="a-hrefuseusea-middlewarefunction-or-middlewareobject"><a href="#use">use</a> <strong><code>(middlewareFunction or middlewareObject)</code></strong></h2>
-<p>Can be used to mount pre-existing middleware or you can write your own.
-Middleware are effectively hooks that execute in various areas of the
-reconciler during a render call such as <code>innerHTML</code> or <code>outerHTML</code>.</p>
-<p>A function is useful when you want to follow the transactions (which are
-started and run a series of tasks), and passing an object can be cleaner when
-you want to modify the Virtual Tree or automatically add properties.</p>
+<p>This function is used to hook plugins into your render pipeline. These plugins
+are referred to as middleware. They are meant for advanced use cases such as
+observing the render flow, modifying attributes or elements, and more.</p>
+<p>Middleware can be enabled and disabled via code or the browser DevTools.</p>
 <p>
-    <a href="/middleware.html#writing-middleware" title="null"><strong>Refer to the Middleware documentation for more in-depth
-information.</strong></a>
+    <a href="/middleware.html" title="null"><strong>Refer to the Middleware documentation for documentation on writing your own
+and find existing plugins.</strong></a>
   </p>
 <h3 id="arguments-3">Arguments</h3>
 <table>
@@ -430,10 +454,10 @@ <h3 id="arguments-3">Arguments</h3>
 </tr>
 <tr>
 <td><strong>middlewareObject</strong></td>
-<td>Use this when you don&#39;t care about the transaction start/stop, and want a cleaner way to monitor the VTree lifecycle. <p><b>- createTreeHook</b></p><p><b>- syncTreeHook</b></p> <p><b>- releaseHook</b></p><p><b>- subscribe</b></p><p><b>- unsubscribe</b></p></td>
+<td>Use this when you don&#39;t care about the transaction start/stop, and want a cleaner way to monitor the VTree lifecycle. <ul><li>displayName</li><li>createNodeHook</li><li>createTreeHook</li><li>syncTreeHook</li><li>releaseHook</li><li>subscribe</li><li>unsubscribe</li></ul></td>
 </tr>
 </tbody></table>
-<h3 id="examples">Examples</h3>
+<h3 id="examples-1">Examples</h3>
 <h4 id="logging-the-start-of-a-render-transaction">Logging the start of a render transaction</h4>
 <pre><code class="language-js">function someTask(transaction) {
   console.log(&#39;Start of render transaction:&#39;, transaction);
@@ -579,9 +603,9 @@ <h3 id="arguments-6">Arguments</h3>
 <p><a name="create-tree"></a></p>
 <hr></hr>
 <h2 id="a-hrefcreate-treecreatetreea-nodename-attributes-childnodes"><a href="#create-tree">createTree</a> <strong><code>(nodeName, attributes, ...childNodes)</code></strong></h2>
-<p>Creates a Virtual Tree which can be interpolated and rendered. This has a
-similar purpose to hyperscript&#39;s <code>h()</code> and React&#39;s <code>createElement</code>.</p>
-<p>Example:</p>
+<p>Creates a Virtual Tree (VTree) which can be interpolated and rendered. This has
+a similar purpose to hyperscript&#39;s <code>h()</code> and React&#39;s <code>createElement</code>.</p>
+<p>Examples:</p>
 <pre><code class="language-js">const attributes = {
   id: &#39;test&#39;,
   style: &#39;color: red&#39;,
@@ -603,7 +627,7 @@ <h3 id="arguments-7">Arguments</h3>
 </thead>
 <tbody><tr>
 <td><strong>nodeName</strong></td>
-<td>A string for HTML, or if using components or middleware other types, like functions</td>
+<td>A string for HTML, or couuld be a component or other types like functions when using middleware</td>
 </tr>
 <tr>
 <td><strong>attributes</strong></td>
@@ -616,7 +640,7 @@ <h3 id="arguments-7">Arguments</h3>
 </tbody></table>
 <p><a name="release"></a></p>
 <hr></hr>
-<h2 id="a-hrefreleasereleasea-domnode"><a href="#release">release</a> <strong><code>(domNode)</code></strong></h2>
+<h2 id="a-hrefreleasereleasea-mount"><a href="#release">release</a> <strong><code>(mount)</code></strong></h2>
 <p>Use this method if you need to clean up memory allocations and anything else
 internal to diffHTML associated with your element. This is very useful for unit
 testing and general cleanup when you&#39;re done with an element. Applications will
@@ -630,18 +654,15 @@ <h3 id="arguments-8">Arguments</h3>
 </tr>
 </thead>
 <tbody><tr>
-<td><strong>domNode</strong></td>
-<td>The root DOM Node to release memory around</td>
+<td><strong>mount</strong></td>
+<td>Release memory and all internal references to the DOM node.</td>
 </tr>
 </tbody></table>
-<p>This method should fully release everything related to the rendering, but its
-possible an untested code path is hit, so you should track the internal memory
-allocations to verify that memory isn&#39;t causing a problem.</p>
 <h4 id="domnode">domNode</h4>
 <p><em>Reference element.</em></p>
 <p>This argument is overloaded. Can be one of many types:</p>
 <ul>
-<li>HTML Element / DOM Node (Used interchangeably)</li>
+<li>HTML Element / DOM node (Used interchangeably)</li>
 <li>Virtual Tree Element (produced from <code>diff.html</code>)</li>
 </ul>
 <p><a name="internals"></a></p>
@@ -669,7 +690,7 @@ <h3 id="a-namesync-tree-hook-cache-hrefsync-tree-hook-cachesynctreehookcachea"><
 <p>A JavaScript Set object that contains functions that trigger whenever Virtual
 Trees are compared.</p>
 <h3 id="a-namenode-cache-hrefnode-cachenodecachea"><a name="node-cache" href="#node-cache">NodeCache</a></h3>
-<p>A Map that can be used to get access to the DOM Node associated to a VTree.
+<p>A Map that can be used to get access to the DOM node associated to a VTree.
 This is comparable to <code>findDOMNode</code> in React. Basically if you encounter an
 object that the documentation says is a VTree and you want to convert to a DOM
 Node, you could write something like:</p>
@@ -731,7 +752,7 @@ <h3 id="a-nameinternals-version-hrefinternals-versionversiona"><a name="internal
 <hr></hr>
 <h2 id="a-hrefversionversiona"><a href="#version">VERSION</a></h2>
 <p>Property which indicates the current running version of diffHTML.</p>
-<h3 id="example-1">Example</h3>
+<h3 id="example">Example</h3>
 <pre><code class="language-js">console.log(VERSION);</code></pre>
 <hr></hr>
 </section>

docs/index.css

@@ -197,6 +197,7 @@ layer#main h2 {
   margin-top: 40px;
 }
 
+layer#main h1 a,
 layer#main h2 a {
   text-decoration: none;
 }
@@ -366,6 +367,13 @@ h2 a.github,
 h1 a.github {
   margin-left: 15px;
   font-size: 20px;
+  position: relative;
+  top: -2px;
+}
+
+h2 a.github:hover,
+h1 a.github:hover {
+  font-weight: bold;
 }
 
 .open-menu {

packages/diffhtml-components/lib/component.js

@@ -88,19 +88,26 @@ class Component {
      */
     const domNode = (childNodes[0]);
 
-    // If there is no DOM Node association then error out.
-    if (process.env.NODE_ENV !== 'production') {
-      if (!domNode) {
-        throw new Error('Missing DOM Node association to this component');
-      }
-
-      // Throw an error if we are not connected, cannot use stateful components
-      // if they are rendered shallow.
-      if (!domNode.parentNode) {
-        throw new Error('Cannot use stateful features when shallow rendered');
-      }
+    // Do not attempt to re-render if we do not have prior children.
+    // TODO This is cheating until there is a better way to determine if a
+    // component has rendered or not.
+    if (!domNode || !domNode.parentNode) {
+      return;
     }
 
+    // If there is no DOM Node association then error out.
+    //if (process.env.NODE_ENV !== 'production') {
+    //  if (!domNode) {
+    //    throw new Error('Missing DOM Node association to this component');
+    //  }
+
+    //  // Throw an error if we are not connected, cannot use stateful components
+    //  // if they are rendered shallow.
+    //  if (!domNode.parentNode) {
+    //    throw new Error('Cannot use stateful features when shallow rendered');
+    //  }
+    //}
+
     const { parentNode } = domNode;
 
     // Render directly from the Component.

packages/diffhtml-components/lib/shared/render-component.js

@@ -63,6 +63,11 @@ export default function renderComponent(vTree, context) {
     // Now that the instance is associated, we can look up context.
     context = getContext(vTree);
 
+    // Signal the component is about to mount.
+    if (instance.componentWillMount) {
+      instance.componentWillMount();
+    }
+
     // Initial render of the class component.
     renderTree = createTree(instance.render(props, instance.state, context));
 

packages/diffhtml-components/lib/shared/set-state.js

@@ -1,4 +1,5 @@
-import { $$render } from '../util/symbols';
+import { $$vTree, $$render } from '../util/symbols';
+import { InstanceCache } from '../util/caches';
 
 const Debounce = new WeakMap();
 const { assign } = Object;
@@ -7,6 +8,7 @@ export default function setState(state) {
   this.state = assign({}, this.state, state);
 
   if (!Debounce.has(this) && this.shouldComponentUpdate()) {
+    // Only render if we have an instance (has rendered before).
     this[$$render]();
   }
-}
+}

packages/diffhtml-devtools/build/tasks/browserify.coffee

@@ -4,7 +4,7 @@ module.exports = ->
   @config 'browserify',
     'bridge':
       files:
-        'chrome-extension/dist/extension/js/bridge.js': ['shared/scripts/bridge.js']
+        'chrome-extension/dist/extension/js/bridge.js': ['lib/scripts/bridge.js']
 
       options:
         transform: ['babelify', 'brfs']
@@ -15,10 +15,10 @@ module.exports = ->
 
     'chrome-extension':
       files:
-        'chrome-extension/dist/extension/js/index.js': ['shared/scripts/index.js']
-        'chrome-extension/dist/extension/js/contentscript.js': ['shared/scripts/contentscript.js']
-        'chrome-extension/dist/extension/js/devtools.js': ['shared/scripts/devtools.js']
-        'chrome-extension/dist/extension/js/background.js': ['shared/scripts/background.js']
+        'chrome-extension/dist/extension/js/index.js': ['lib/scripts/index.js']
+        'chrome-extension/dist/extension/js/contentscript.js': ['lib/scripts/contentscript.js']
+        'chrome-extension/dist/extension/js/devtools.js': ['lib/scripts/devtools.js']
+        'chrome-extension/dist/extension/js/background.js': ['lib/scripts/background.js']
 
       options:
         transform: [

packages/diffhtml-devtools/build/tasks/compress.coffee

@@ -8,7 +8,7 @@ module.exports = ->
         mode: 'zip'
 
       files: [
-        { src: ['**/*'], expand: true, cwd: 'shared' }
+        { src: ['**/*'], expand: true, cwd: 'lib' }
         {
           src: [
             'key.pem'

packages/diffhtml-devtools/build/tasks/copy.coffee

@@ -35,7 +35,7 @@ module.exports = ->
             '!_assets/**'
           ]
           expand: true
-          cwd: 'shared'
+          cwd: 'lib'
           dest: chromeDest
         }
         {

packages/diffhtml-devtools/build/tasks/jshint.coffee

@@ -7,5 +7,5 @@ module.exports = ->
       jshintrc: '.jshintrc'
 
     files: [
-      'shared/**/*.js'
+      'lib/**/*.js'
     ]

packages/diffhtml-devtools/build/tasks/mocha.coffee

@@ -13,7 +13,7 @@ module.exports = ->
         'test/integration/tests/**/*.js'
       ]
 
-    'shared':
+    'lib':
       src: [
         'test/unit/runner.js'
         'test/unit/tests/**/*.js'

packages/diffhtml-devtools/build/tasks/watch.coffee

@@ -6,7 +6,7 @@ module.exports = ->
       files: [
         'chrome-extension/**/*'
         '!chrome-extension/dist/**/*'
-        'shared/**/*'
+        'lib/**/*'
       ]
 
       tasks: [