Ensure templates always have stable boundaries

Previously, if a template’s first (or last) child was a dynamic node
(like a mustache or block), the associated render node’s firstChild or
lastChild would change.

```hbs
{{#if condition}}{{value}}{{/if}}
```

In this case, the render node associated with the `#if` helper cannot
have stable `firstNode` and `lastNode`, because when the nodes
associated with `value` change, the nodes associated with the `if`
helper must change as well.

The solution was to require that templates create fragments with stable
start and end nodes. If the first node is dynamic, we insert a boundary
empty text node to ensure that the template’s boundaries will not
change.

Author: Tom Dale and Yehuda Katz

packages/dom-helper/lib/main.js

@@ -414,6 +414,12 @@ prototype.appendMorph = function(element, contextualElement) {
   return this.createMorph(element, insertion, insertion, contextualElement);
 };
 
+prototype.insertBoundary = function(fragment, index) {
+  // this will always be null or firstChild
+  var child = index === null ? null : this.childAtIndex(fragment, index);
+  this.insertBefore(fragment, this.createTextNode(''), child);
+};
+
 prototype.parseHTML = function(html, contextualElement) {
   var childNodes;
 

packages/htmlbars-compiler/lib/hydration-javascript-compiler.js

@@ -30,6 +30,8 @@ prototype.compile = function(opcodes, options) {
   this.statements = [];
   this.expressionStack = [];
   this.augmentContext = [];
+  this.hasOpenBoundary = false;
+  this.hasCloseBoundary = false;
 
   processOpcodes(this, opcodes);
 
@@ -64,23 +66,35 @@ prototype.compile = function(opcodes, options) {
   if (this.fragmentProcessing.length) {
     var processing = "";
     for (i = 0, l = this.fragmentProcessing.length; i < l; ++i) {
-      processing += this.indent+this.fragmentProcessing[i]+'\n';
+      processing += this.indent+'  '+this.fragmentProcessing[i]+'\n';
     }
     result.fragmentProcessingProgram = processing;
   }
 
+  var createMorphsProgram;
   if (result.hasMorphs) {
-    result.createMorphsProgram =
+    createMorphsProgram =
       'function buildRenderNodes(dom, fragment, contextualElement) {\n' +
-      result.fragmentProcessingProgram +
-      morphs +
+      result.fragmentProcessingProgram + morphs;
+
+      if (this.hasOpenBoundary) {
+        createMorphsProgram += indent+"  dom.insertBoundary(fragment, 0);\n";
+      }
+
+      if (this.hasCloseBoundary) {
+        createMorphsProgram += indent+"  dom.insertBoundary(fragment, null);\n";
+      }
+
+      createMorphsProgram +=
       indent + '  return morphs;\n' +
       indent+'}';
   } else {
-    result.createMorphsProgram =
+    createMorphsProgram =
       'function buildRenderNodes() { return []; }';
   }
 
+  result.createMorphsProgram = createMorphsProgram;
+
   return result;
 };
 
@@ -104,6 +118,14 @@ prototype.prepareObject = function(size) {
   this.expressionStack.push(pairs);
 };
 
+prototype.openBoundary = function() {
+  this.hasOpenBoundary = true;
+};
+
+prototype.closeBoundary = function() {
+  this.hasCloseBoundary = true;
+};
+
 prototype.pushLiteral = function(value) {
   this.expressionStack.push(value);
 };

packages/htmlbars-compiler/lib/hydration-opcode-compiler.js

@@ -71,6 +71,10 @@ HydrationOpcodeCompiler.prototype.startProgram = function(program, c, blankChild
   }
 };
 
+HydrationOpcodeCompiler.prototype.insertBoundary = function(first) {
+  this.opcode(first ? 'openBoundary' : 'closeBoundary');
+};
+
 HydrationOpcodeCompiler.prototype.endProgram = function() {
   distributeMorphs(this.morphs, this.opcodes);
 };

packages/htmlbars-compiler/lib/template-compiler.js

@@ -18,11 +18,37 @@ function TemplateCompiler(options) {
 
 export default TemplateCompiler;
 
+var dynamicNodes = {
+  mustache: true,
+  block: true,
+  component: true
+};
+
 TemplateCompiler.prototype.compile = function(ast) {
   var templateVisitor = new TemplateVisitor();
   templateVisitor.visit(ast);
 
-  processOpcodes(this, templateVisitor.actions);
+  var normalizedActions = [];
+  var actions = templateVisitor.actions;
+
+  for (var i=0, l=actions.length - 1; i<l; i++) {
+    var action = actions[i];
+    var nextAction = actions[i + 1];
+
+    normalizedActions.push(action);
+
+    if (action[0] === "startProgram" && nextAction[0] in dynamicNodes) {
+      normalizedActions.push(['insertBoundary', [true]]);
+    }
+
+    if (nextAction[0] === "endProgram" && action[0] in dynamicNodes) {
+      normalizedActions.push(['insertBoundary', [false]]);
+    }
+  }
+
+  normalizedActions.push(actions[actions.length - 1]);
+
+  processOpcodes(this, normalizedActions);
 
   return this.templates.pop();
 };
@@ -37,6 +63,10 @@ TemplateCompiler.prototype.startProgram = function(program, childTemplateCount,
   }
 };
 
+TemplateCompiler.prototype.insertBoundary = function(first) {
+  this.hydrationOpcodeCompiler.insertBoundary(first);
+};
+
 TemplateCompiler.prototype.getChildTemplateVars = function(indent) {
   var vars = '';
   if (this.childTemplates) {

packages/htmlbars-compiler/tests/dirtying-test.js

@@ -84,6 +84,39 @@ test("a simple implementation of a dirtying rerender", function() {
   equalTokens(result.fragment, '<div><p>Nothing</p></div>');
 });
 
+test("block helpers whose template has a morph at the edge", function() {
+  registerHelper('id', function(params, hash, options) {
+    return options.template.render(this);
+  });
+
+  var template = compile("{{#id}}{{value}}{{/id}}");
+  var object = { value: "hello world" };
+  var result = template.render(object, env);
+
+  equalTokens(result.fragment, 'hello world');
+  var firstNode = result.root.firstNode;
+  equal(firstNode.nodeType, 3, "first node of the parent template");
+  equal(firstNode.textContent, "", "its content should be empty");
+
+  var secondNode = firstNode.nextSibling;
+  equal(secondNode.nodeType, 3, "first node of the helper template should be a text node");
+  equal(secondNode.textContent, "", "its content should be empty");
+
+  var textContent = secondNode.nextSibling;
+  equal(textContent.nodeType, 3, "second node of the helper should be a text node");
+  equal(textContent.textContent, "hello world", "its content should be hello world");
+
+  var fourthNode = textContent.nextSibling;
+  equal(fourthNode.nodeType, 3, "last node of the helper should be a text node");
+  equal(fourthNode.textContent, "", "its content should be empty");
+
+  var lastNode = fourthNode.nextSibling;
+  equal(lastNode.nodeType, 3, "last node of the parent template should be a text node");
+  equal(lastNode.textContent, "", "its content should be empty");
+
+  strictEqual(lastNode.nextSibling, null, "there should only be five nodes");
+});
+
 test("clean content doesn't get blown away", function() {
   var template = compile("<div>{{value}}</div>");
   var object = { value: "hello" };

packages/htmlbars-compiler/tests/html-compiler-test.js

@@ -277,7 +277,7 @@ test("The compiler can handle top-level unescaped tr", function() {
   var fragment = template.render(context, env, { contextualElement: document.createElement('table') }).fragment;
 
   equal(
-    fragment.firstChild.tagName, 'TR',
+    fragment.firstChild.nextSibling.tagName, 'TR',
     "root tr is present" );
 });
 
@@ -287,7 +287,7 @@ test("The compiler can handle top-level unescaped td inside tr contextualElement
   var fragment = template.render(context, env, { contextualElement: document.createElement('tr') }).fragment;
 
   equal(
-    fragment.firstChild.tagName, 'TD',
+    fragment.firstChild.nextSibling.tagName, 'TD',
     "root td is returned" );
 });
 
@@ -301,7 +301,7 @@ test("The compiler can handle unescaped tr in top of content", function() {
   var fragment = template.render(context, env, { contextualElement: document.createElement('table') }).fragment;
 
   equal(
-    fragment.firstChild.tagName, 'TR',
+    fragment.firstChild.nextSibling.nextSibling.tagName, 'TR',
     "root tr is present" );
 });
 
@@ -316,7 +316,7 @@ test("The compiler can handle unescaped tr inside fragment table", function() {
   var tableNode = fragment.firstChild;
 
   equal(
-    tableNode.firstChild.tagName, 'TR',
+    tableNode.firstChild.nextSibling.tagName, 'TR',
     "root tr is present" );
 });
 
@@ -1187,6 +1187,7 @@ test("svg can live with hydration", function() {
   var template = compile('<svg></svg>{{name}}');
 
   var fragment = template.render({ name: 'Milly' }, env, { contextualElement: document.body }).fragment;
+
   equal(
     fragment.childNodes[0].namespaceURI, svgNamespace,
     "svg namespace inside a block is present" );
@@ -1246,16 +1247,16 @@ test("Block helper allows interior namespace", function() {
 
   var fragment = template.render({ isTrue: true }, env, { contextualElement: document.body }).fragment;
   equal(
-    fragment.firstChild.namespaceURI, svgNamespace,
+    fragment.firstChild.nextSibling.namespaceURI, svgNamespace,
     "svg namespace inside a block is present" );
 
   isTrue = false;
   fragment = template.render({ isTrue: false }, env, { contextualElement: document.body }).fragment;
   equal(
-    fragment.firstChild.namespaceURI, xhtmlNamespace,
+    fragment.firstChild.nextSibling.namespaceURI, xhtmlNamespace,
     "inverse block path has a normal namespace");
   equal(
-    fragment.firstChild.childNodes[0].namespaceURI, svgNamespace,
+    fragment.firstChild.nextSibling.firstChild.namespaceURI, svgNamespace,
     "svg namespace inside an element inside a block is present" );
 });