lit-html
Version:
HTML template literals in JavaScript
371 lines • 14.3 kB
JavaScript
/**
* @license
* Copyright (c) 2017 The Polymer Project Authors. All rights reserved.
* This code may only be used under the BSD style license found at
* http://polymer.github.io/LICENSE.txt
* The complete set of authors may be found at
* http://polymer.github.io/AUTHORS.txt
* The complete set of contributors may be found at
* http://polymer.github.io/CONTRIBUTORS.txt
* Code distributed by Google as part of the polymer project is also
* subject to an additional IP rights grant found at
* http://polymer.github.io/PATENTS.txt
*/
// The first argument to JS template tags retain identity across multiple
// calls to a tag for the same literal, so we can cache work done per literal
// in a Map.
const templates = new Map();
/**
* Interprets a template literal as an HTML template that can efficiently
* render to and update a container.
*/
export function html(strings, ...values) {
let template = templates.get(strings);
if (template === undefined) {
template = new Template(strings);
templates.set(strings, template);
}
return new TemplateResult(template, values);
}
/**
* The return type of `html`, which holds a Template and the values from
* interpolated expressions.
*/
export class TemplateResult {
constructor(template, values) {
this.template = template;
this.values = values;
}
/**
* Renders this template to a container. To update a container with new values,
* reevaluate the template literal and call `renderTo` of the new result.
*/
renderTo(container) {
let instance = container.__templateInstance;
if (instance === undefined) {
instance = new TemplateInstance(this.template);
container.__templateInstance = instance;
const fragment = instance._clone();
instance.update(this.values);
container.appendChild(fragment);
}
else {
instance.update(this.values);
}
}
}
const exprMarker = '{{}}';
/**
* A placeholder for a dynamic expression in an HTML template.
*
* There are two built-in part types: AttributePart and NodePart. NodeParts
* always represent a single dynamic expression, while AttributeParts may
* represent as many expressions are contained in the attribute.
*
* A Template's parts are mutable, so parts can be replaced or modified
* (possibly to implement different template semantics). The contract is that
* parts can only be replaced, not removed, added or reordered, and parts must
* always consume the correct number of values in their `update()` method.
*
* TODO(justinfagnani): That requirement is a little fragile. A
* TemplateInstance could instead be more careful about which values it gives
* to Part.update().
*/
export class TemplatePart {
constructor(type, index, name, rawName, strings) {
this.type = type;
this.index = index;
this.name = name;
this.rawName = rawName;
this.strings = strings;
}
}
export class Template {
constructor(strings) {
this.parts = [];
this._strings = strings;
this._parse();
}
_parse() {
this.element = document.createElement('template');
this.element.innerHTML = this._getTemplateHtml(this._strings);
const walker = document.createTreeWalker(this.element.content, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
let index = -1;
let partIndex = 0;
const nodesToRemove = [];
const attributesToRemove = [];
while (walker.nextNode()) {
index++;
const node = walker.currentNode;
if (node.nodeType === Node.ELEMENT_NODE) {
const attributes = node.attributes;
for (let i = 0; i < attributes.length; i++) {
const attribute = attributes.item(i);
const value = attribute.value;
const strings = value.split(exprMarker);
if (strings.length > 1) {
const attributeString = this._strings[partIndex];
// Trim the trailing literal value if this is an interpolation
const rawNameString = attributeString.substring(0, attributeString.length - strings[0].length);
const match = rawNameString.match(/((?:\w|[.\-_$])+)=["']?$/);
const rawName = match[1];
this.parts.push(new TemplatePart('attribute', index, attribute.name, rawName, strings));
attributesToRemove.push(attribute);
partIndex += strings.length - 1;
}
}
}
else if (node.nodeType === Node.TEXT_NODE) {
const strings = node.nodeValue.split(exprMarker);
if (strings.length > 1) {
// Generate a new text node for each literal and two for each part,
// a start and end
partIndex += strings.length - 1;
for (let i = 0; i < strings.length; i++) {
const string = strings[i];
const literalNode = new Text(string);
node.parentNode.insertBefore(literalNode, node);
index++;
if (i < strings.length - 1) {
node.parentNode.insertBefore(new Text(), node);
node.parentNode.insertBefore(new Text(), node);
this.parts.push(new TemplatePart('node', index));
index += 2;
}
}
index--;
nodesToRemove.push(node);
}
else if (!node.nodeValue.trim()) {
nodesToRemove.push(node);
index--;
}
}
}
// Remove text binding nodes after the walk to not disturb the TreeWalker
for (const n of nodesToRemove) {
n.parentNode.removeChild(n);
}
for (const a of attributesToRemove) {
a.ownerElement.removeAttribute(a.name);
}
}
_getTemplateHtml(strings) {
const parts = [];
for (let i = 0; i < strings.length; i++) {
parts.push(strings[i]);
if (i < strings.length - 1) {
parts.push(exprMarker);
}
}
return parts.join('');
}
}
export class Part {
constructor(instance) {
this.instance = instance;
}
_getValue(value) {
if (typeof value === 'function') {
try {
value = value(this);
}
catch (e) {
console.error(e);
return;
}
}
if (value === null) {
// `null` as the value of Text node will render the string 'null'
return undefined;
}
return value;
}
}
export class AttributePart extends Part {
constructor(instance, element, name, strings) {
super(instance);
console.assert(element.nodeType === Node.ELEMENT_NODE);
this.element = element;
this.name = name;
this.strings = strings;
}
setValue(values) {
const strings = this.strings;
let text = '';
for (let i = 0; i < strings.length; i++) {
text += strings[i];
if (i < strings.length - 1) {
const v = this._getValue(values[i]);
if (v && typeof v !== 'string' && v[Symbol.iterator]) {
for (const t of v) {
// TODO: we need to recursively call getValue into iterables...
text += t;
}
}
else {
text += v;
}
}
}
this.element.setAttribute(this.name, text);
}
get size() {
return this.strings.length - 1;
}
}
export class NodePart extends Part {
constructor(instance, startNode, endNode) {
super(instance);
this.startNode = startNode;
this.endNode = endNode;
}
setValue(value) {
let node = undefined;
value = this._getValue(value);
if (value instanceof Node) {
this.clear();
node = value;
}
else if (value instanceof TemplateResult) {
let instance;
if (this._previousValue && this._previousValue._template === value.template) {
instance = this._previousValue;
}
else {
this.clear();
instance = this.instance._createInstance(value.template);
node = instance._clone();
}
instance.update(value.values);
this._previousValue = instance;
}
else if (value && typeof value !== 'string' && value[Symbol.iterator]) {
// For an Iterable, we create a new InstancePart per item, then set its
// value to the item. This is a little bit of overhead for every item in
// an Iterable, but it lets us recurse easily and update Arrays of
// TemplateResults that will be commonly returned from expressions like:
// array.map((i) => html`${i}`)
// We reuse this parts startNode as the first part's startNode, and this
// parts endNode as the last part's endNode.
let itemStart = this.startNode;
let itemEnd;
const values = value[Symbol.iterator]();
const previousParts = Array.isArray(this._previousValue) ? this._previousValue : undefined;
let previousPartsIndex = 0;
const itemParts = [];
let current = values.next();
let next = values.next();
if (current.done) {
// Empty iterable, just clear
this.clear();
}
while (!current.done) {
// Reuse a previous part if we can, otherwise create a new one
let itemPart;
if (previousParts !== undefined && previousPartsIndex < previousParts.length) {
itemPart = previousParts[previousPartsIndex++];
if (next.done && itemPart.endNode !== this.endNode) {
// Since this is the last part we'll use, set it's endNode to the
// container's endNode. Setting the value of this part will clean
// up any residual nodes from a previously longer iterable.
const range = document.createRange();
range.setStartBefore(itemPart.endNode);
range.setEndBefore(this.endNode);
range.deleteContents();
range.detach();
itemPart.endNode = this.endNode;
}
itemEnd = itemPart.endNode;
}
else {
if (next.done) {
// on the last item, reuse this part's endNode
itemEnd = this.endNode;
}
else {
itemEnd = new Text();
this.endNode.parentNode.insertBefore(itemEnd, this.endNode);
}
itemPart = new NodePart(this.instance, itemStart, itemEnd);
}
itemPart.setValue(current.value);
itemParts.push(itemPart);
current = next;
next = values.next();
itemStart = itemEnd;
}
this._previousValue = itemParts;
}
else {
this.clear();
node = new Text(value);
}
if (node !== undefined) {
this.endNode.parentNode.insertBefore(node, this.endNode);
}
}
clear() {
this._previousValue = undefined;
const range = document.createRange();
range.setStartAfter(this.startNode);
range.setEndBefore(this.endNode);
range.deleteContents();
range.detach();
}
}
export class TemplateInstance {
constructor(template) {
this._parts = [];
this._template = template;
}
update(values) {
let valueIndex = 0;
for (const part of this._parts) {
if (part.size === undefined) {
part.setValue(values[valueIndex++]);
}
else {
part.setValue(values.slice(valueIndex, valueIndex + part.size));
valueIndex += part.size;
}
}
}
_clone() {
const fragment = document.importNode(this._template.element.content, true);
if (this._template.parts.length > 0) {
const walker = document.createTreeWalker(fragment, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
const parts = this._template.parts;
let index = 0;
let partIndex = 0;
let templatePart = parts[0];
let node = walker.nextNode();
while (node != null && partIndex < parts.length) {
if (index === templatePart.index) {
this._parts.push(this._createPart(templatePart, node));
templatePart = parts[++partIndex];
}
else {
index++;
node = walker.nextNode();
}
}
}
return fragment;
}
_createPart(templatePart, node) {
if (templatePart.type === 'attribute') {
return new AttributePart(this, node, templatePart.name, templatePart.strings);
}
else if (templatePart.type === 'node') {
return new NodePart(this, node, node.nextSibling);
}
else {
throw new Error(`unknown part type: ${templatePart.type}`);
}
}
_createInstance(template) {
return new TemplateInstance(template);
}
}
//# sourceMappingURL=lit-html.js.map