written 0.0.5 → 0.1.1

data/lib/written/app/assets/javascripts/written/polyfills/CustomElements/observe.js

@@ -0,0 +1,318 @@
+/**
+ * @license
+ * Copyright (c) 2014 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
+ */
+
+/**
+ * Implements custom element observation and attached/detached callbacks
+ * @module observe
+*/
+
+window.CustomElements.addModule(function(scope){
+
+// imports
+var flags = scope.flags;
+var forSubtree = scope.forSubtree;
+var forDocumentTree = scope.forDocumentTree;
+
+/*
+  Manage nodes attached to document trees
+*/
+
+// manage lifecycle on added node and it's subtree; upgrade the node and
+// entire subtree if necessary and process attached for the node and entire
+// subtree
+function addedNode(node, isAttached) {
+  return added(node, isAttached) || addedSubtree(node, isAttached);
+}
+
+// manage lifecycle on added node; upgrade if necessary and process attached
+function added(node, isAttached) {
+  if (scope.upgrade(node, isAttached)) {
+    // Return true to indicate
+    return true;
+  }
+  if (isAttached) {
+    attached(node);
+  }
+}
+
+// manage lifecycle on added node's subtree only; allows the entire subtree
+// to upgrade if necessary and process attached
+function addedSubtree(node, isAttached) {
+  forSubtree(node, function(e) {
+    if (added(e, isAttached)) {
+      return true;
+    }
+  });
+}
+
+// On platforms without MutationObserver, mutations may not be
+// reliable and therefore attached/detached are not reliable. We think this
+// occurs sometimes under heavy DOM operation load, but it is not easy to
+// reproduce.
+// To make these callbacks less likely to fail in this scenario,
+// we *optionally* defer all inserts and removes
+// to give a chance for elements to be attached into dom.
+// This helps ensure attachedCallback fires for elements that are created and
+// immediately added to dom.
+// This change can significantly alter the performance characteristics
+// of attaching elements and therefore we only enable it if the user has
+// explicitly provided the `throttle-attached` flag.
+var hasThrottledAttached = (window.MutationObserver._isPolyfilled &&
+    flags['throttle-attached']);
+// bc
+scope.hasPolyfillMutations = hasThrottledAttached;
+// exposed for testing
+scope.hasThrottledAttached = hasThrottledAttached;
+
+var isPendingMutations = false;
+var pendingMutations = [];
+function deferMutation(fn) {
+  pendingMutations.push(fn);
+  if (!isPendingMutations) {
+    isPendingMutations = true;
+    setTimeout(takeMutations);
+  }
+}
+
+function takeMutations() {
+  isPendingMutations = false;
+  var $p = pendingMutations;
+  for (var i=0, l=$p.length, p; (i<l) && (p=$p[i]); i++) {
+    p();
+  }
+  pendingMutations = [];
+}
+
+function attached(element) {
+  if (hasThrottledAttached) {
+    deferMutation(function() {
+      _attached(element);
+    });
+  } else {
+    _attached(element);
+  }
+}
+
+// NOTE: due to how MO works (see comments below), an element may be attached
+// multiple times so we protect against extra processing here.
+function _attached(element) {
+  // track element for insertion if it's upgraded and cares about insertion
+  // bail if the element is already marked as attached
+  if (element.__upgraded__ && !element.__attached) {
+    element.__attached = true;
+    if (element.attachedCallback) {
+      element.attachedCallback();
+    }
+  }
+}
+
+/*
+  Manage nodes detached from document trees
+*/
+
+// manage lifecycle on detached node and it's subtree; process detached
+// for the node and entire subtree
+function detachedNode(node) {
+  detached(node);
+  forSubtree(node, function(e) {
+    detached(e);
+  });
+}
+
+function detached(element) {
+  if (hasThrottledAttached) {
+    deferMutation(function() {
+      _detached(element);
+    });
+  } else {
+    _detached(element);
+  }
+}
+
+// NOTE: due to how MO works (see comments below), an element may be detached
+// multiple times so we protect against extra processing here.
+function _detached(element) {
+  // track element for removal if it's upgraded and cares about removal
+  // bail if the element is already marked as not attached
+  if (element.__upgraded__ && element.__attached) {
+    element.__attached = false;
+    if (element.detachedCallback) {
+      element.detachedCallback();
+    }
+  }
+}
+
+// recurse up the tree to check if an element is actually in the main document.
+function inDocument(element) {
+  var p = element;
+  var doc = window.wrap(document);
+  while (p) {
+    if (p == doc) {
+      return true;
+    }
+    p = p.parentNode || ((p.nodeType === Node.DOCUMENT_FRAGMENT_NODE) && p.host);
+  }
+}
+
+//  Install an element observer on all shadowRoots owned by node.
+function watchShadow(node) {
+  if (node.shadowRoot && !node.shadowRoot.__watched) {
+    flags.dom && console.log('watching shadow-root for: ', node.localName);
+    // watch all unwatched roots...
+    var root = node.shadowRoot;
+    while (root) {
+      observe(root);
+      root = root.olderShadowRoot;
+    }
+  }
+}
+
+/*
+  NOTE: In order to process all mutations, it's necessary to recurse into
+  any added nodes. However, it's not possible to determine a priori if a node
+  will get its own mutation record. This means
+  *nodes can be seen multiple times*.
+
+  Here's an example:
+
+  (1) In this case, recursion is required to see `child`:
+
+      node.innerHTML = '<div><child></child></div>'
+
+  (2) In this case, child will get its own mutation record:
+
+      node.appendChild(div).appendChild(child);
+
+  We cannot know ahead of time if we need to walk into the node in (1) so we
+  do and see child; however, if it was added via case (2) then it will have its
+  own record and therefore be seen 2x.
+*/
+function handler(root, mutations) {
+  // for logging only
+  if (flags.dom) {
+    var mx = mutations[0];
+    if (mx && mx.type === 'childList' && mx.addedNodes) {
+        if (mx.addedNodes) {
+          var d = mx.addedNodes[0];
+          while (d && d !== document && !d.host) {
+            d = d.parentNode;
+          }
+          var u = d && (d.URL || d._URL || (d.host && d.host.localName)) || '';
+          u = u.split('/?').shift().split('/').pop();
+        }
+    }
+    console.group('mutations (%d) [%s]', mutations.length, u || '');
+  }
+  // handle mutations
+  // NOTE: do an `inDocument` check dynamically here. It's possible that `root`
+  // is a document in which case the answer here can never change; however
+  // `root` may be an element like a shadowRoot that can be added/removed
+  // from the main document.
+  var isAttached = inDocument(root);
+  mutations.forEach(function(mx) {
+    if (mx.type === 'childList') {
+      forEach(mx.addedNodes, function(n) {
+        if (!n.localName) {
+          return;
+        }
+        addedNode(n, isAttached);
+      });
+      forEach(mx.removedNodes, function(n) {
+        if (!n.localName) {
+          return;
+        }
+        detachedNode(n);
+      });
+    }
+  });
+  flags.dom && console.groupEnd();
+};
+
+
+/*
+  When elements are added to the dom, upgrade and attached/detached may be
+  asynchronous. `CustomElements.takeRecords` can be called to process any
+  pending upgrades and attached/detached callbacks synchronously.
+*/
+function takeRecords(node) {
+  node = window.wrap(node);
+  // If the optional node is not supplied, assume we mean the whole document.
+  if (!node) {
+    node = window.wrap(document);
+  }
+  // Find the root of the tree, which will be an Document or ShadowRoot.
+  while (node.parentNode) {
+    node = node.parentNode;
+  }
+  var observer = node.__observer;
+  if (observer) {
+    handler(node, observer.takeRecords());
+    takeMutations();
+  }
+}
+
+var forEach = Array.prototype.forEach.call.bind(Array.prototype.forEach);
+
+
+// observe a node tree; bail if it's already being observed.
+function observe(inRoot) {
+  if (inRoot.__observer) {
+    return;
+  }
+  // For each ShadowRoot, we create a new MutationObserver, so the root can be
+  // garbage collected once all references to the `inRoot` node are gone.
+  // Give the handler access to the root so that an 'in document' check can
+  // be done.
+  var observer = new MutationObserver(handler.bind(this, inRoot));
+  observer.observe(inRoot, {childList: true, subtree: true});
+  inRoot.__observer = observer;
+}
+
+// upgrade an entire document and observe it for elements changes.
+function upgradeDocument(doc) {
+  doc = window.wrap(doc);
+  flags.dom && console.group('upgradeDocument: ', (doc.baseURI).split('/').pop());
+  var isMainDocument = (doc === window.wrap(document));
+  addedNode(doc, isMainDocument);
+  observe(doc);
+  flags.dom && console.groupEnd();
+}
+
+/*
+This method is intended to be called when the document tree (including imports)
+has pending custom elements to upgrade. It can be called multiple times and
+should do nothing if no elements are in need of upgrade.
+*/
+function upgradeDocumentTree(doc) {
+  forDocumentTree(doc, upgradeDocument);
+}
+
+
+// Patch `createShadowRoot()` if Shadow DOM is available, otherwise leave
+// undefined to aid feature detection of Shadow DOM.
+var originalCreateShadowRoot = Element.prototype.createShadowRoot;
+if (originalCreateShadowRoot) {
+  Element.prototype.createShadowRoot = function() {
+    var root = originalCreateShadowRoot.call(this);
+    window.CustomElements.watchShadow(this);
+    return root;
+  };
+}
+
+// exports
+scope.watchShadow = watchShadow;
+scope.upgradeDocumentTree = upgradeDocumentTree;
+scope.upgradeDocument = upgradeDocument;
+scope.upgradeSubtree = addedSubtree;
+scope.upgradeAll = addedNode;
+scope.attached = attached;
+scope.takeRecords = takeRecords;
+
+});

data/lib/written/app/assets/javascripts/written/polyfills/CustomElements/register.js

@@ -0,0 +1,369 @@
+/**
+ * @license
+ * Copyright (c) 2014 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
+ */
+
+/**
+ * Implements `document.registerElement`
+ * @module register
+*/
+
+/**
+ * Polyfilled extensions to the `document` object.
+ * @class Document
+*/
+
+window.CustomElements.addModule(function(scope) {
+
+// imports
+var isIE = scope.isIE;
+var upgradeDocumentTree = scope.upgradeDocumentTree;
+var upgradeAll = scope.upgradeAll;
+var upgradeWithDefinition = scope.upgradeWithDefinition;
+var implementPrototype = scope.implementPrototype;
+var useNative = scope.useNative;
+
+/**
+ * Registers a custom tag name with the document.
+ *
+ * When a registered element is created, a `readyCallback` method is called
+ * in the scope of the element. The `readyCallback` method can be specified on
+ * either `options.prototype` or `options.lifecycle` with the latter taking
+ * precedence.
+ *
+ * @method register
+ * @param {String} name The tag name to register. Must include a dash ('-'),
+ *    for example 'x-component'.
+ * @param {Object} options
+ *    @param {String} [options.extends]
+ *      (_off spec_) Tag name of an element to extend (or blank for a new
+ *      element). This parameter is not part of the specification, but instead
+ *      is a hint for the polyfill because the extendee is difficult to infer.
+ *      Remember that the input prototype must chain to the extended element's
+ *      prototype (or HTMLElement.prototype) regardless of the value of
+ *      `extends`.
+ *    @param {Object} options.prototype The prototype to use for the new
+ *      element. The prototype must inherit from HTMLElement.
+ *    @param {Object} [options.lifecycle]
+ *      Callbacks that fire at important phases in the life of the custom
+ *      element.
+ *
+ * @example
+ *      FancyButton = document.registerElement("fancy-button", {
+ *        extends: 'button',
+ *        prototype: Object.create(HTMLButtonElement.prototype, {
+ *          readyCallback: {
+ *            value: function() {
+ *              console.log("a fancy-button was created",
+ *            }
+ *          }
+ *        })
+ *      });
+ * @return {Function} Constructor for the newly registered type.
+ */
+function register(name, options) {
+  //console.warn('document.registerElement("' + name + '", ', options, ')');
+  // construct a defintion out of options
+  // TODO(sjmiles): probably should clone options instead of mutating it
+  var definition = options || {};
+  if (!name) {
+    throw new Error('document.registerElement: first argument `name` must not be empty');
+  }
+  if (name.indexOf('-') < 0) {
+    throw new Error('document.registerElement: first argument (\'name\') must contain a dash (\'-\'). Argument provided was \'' + String(name) + '\'.');
+  }
+  // prevent registering reserved names
+  if (isReservedTag(name)) {
+    throw new Error('Failed to execute \'registerElement\' on \'Document\': Registration failed for type \'' + String(name) + '\'. The type name is invalid.');
+  }
+  // elements may only be registered once
+  if (getRegisteredDefinition(name)) {
+    throw new Error('DuplicateDefinitionError: a type with name \'' + String(name) + '\' is already registered');
+  }
+  // prototype is optional, default to an extension of HTMLElement
+  if (!definition.prototype) {
+    definition.prototype = Object.create(HTMLElement.prototype);
+  }
+  // record name
+  definition.__name = name.toLowerCase();
+  // ensure extended name is also treated case-insensitively
+  if (definition.extends) {
+    definition.extends = definition.extends.toLowerCase();
+  }
+  // ensure a lifecycle object so we don't have to null test it
+  definition.lifecycle = definition.lifecycle || {};
+  // build a list of ancestral custom elements (for native base detection)
+  // TODO(sjmiles): we used to need to store this, but current code only
+  // uses it in 'resolveTagName': it should probably be inlined
+  definition.ancestry = ancestry(definition.extends);
+  // extensions of native specializations of HTMLElement require localName
+  // to remain native, and use secondary 'is' specifier for extension type
+  resolveTagName(definition);
+  // some platforms require modifications to the user-supplied prototype
+  // chain
+  resolvePrototypeChain(definition);
+  // overrides to implement attributeChanged callback
+  overrideAttributeApi(definition.prototype);
+  // 7.1.5: Register the DEFINITION with DOCUMENT
+  registerDefinition(definition.__name, definition);
+  // 7.1.7. Run custom element constructor generation algorithm with PROTOTYPE
+  // 7.1.8. Return the output of the previous step.
+  definition.ctor = generateConstructor(definition);
+  definition.ctor.prototype = definition.prototype;
+  // force our .constructor to be our actual constructor
+  definition.prototype.constructor = definition.ctor;
+  // if initial parsing is complete
+  if (scope.ready) {
+    // upgrade any pre-existing nodes of this type
+    upgradeDocumentTree(document);
+  }
+  return definition.ctor;
+}
+
+// attribute watching
+function overrideAttributeApi(prototype) {
+  // overrides to implement callbacks
+  // TODO(sjmiles): should support access via .attributes NamedNodeMap
+  // TODO(sjmiles): preserves user defined overrides, if any
+  if (prototype.setAttribute._polyfilled) {
+    return;
+  }
+  var setAttribute = prototype.setAttribute;
+  prototype.setAttribute = function(name, value) {
+    changeAttribute.call(this, name, value, setAttribute);
+  };
+  var removeAttribute = prototype.removeAttribute;
+  prototype.removeAttribute = function(name) {
+    changeAttribute.call(this, name, null, removeAttribute);
+  };
+  prototype.setAttribute._polyfilled = true;
+}
+
+// https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/custom/
+// index.html#dfn-attribute-changed-callback
+function changeAttribute(name, value, operation) {
+  name = name.toLowerCase();
+  var oldValue = this.getAttribute(name);
+  operation.apply(this, arguments);
+  var newValue = this.getAttribute(name);
+  if (this.attributeChangedCallback &&
+      (newValue !== oldValue)) {
+    this.attributeChangedCallback(name, oldValue, newValue);
+  }
+}
+
+function isReservedTag(name) {
+  for (var i = 0; i < reservedTagList.length; i++) {
+    if (name === reservedTagList[i]) {
+      return true;
+    }
+  }
+}
+
+var reservedTagList = [
+  'annotation-xml', 'color-profile', 'font-face', 'font-face-src',
+  'font-face-uri', 'font-face-format', 'font-face-name', 'missing-glyph'
+];
+
+function ancestry(extnds) {
+  var extendee = getRegisteredDefinition(extnds);
+  if (extendee) {
+    return ancestry(extendee.extends).concat([extendee]);
+  }
+  return [];
+}
+
+function resolveTagName(definition) {
+  // if we are explicitly extending something, that thing is our
+  // baseTag, unless it represents a custom component
+  var baseTag = definition.extends;
+  // if our ancestry includes custom components, we only have a
+  // baseTag if one of them does
+  for (var i=0, a; (a=definition.ancestry[i]); i++) {
+    baseTag = a.is && a.tag;
+  }
+  // our tag is our baseTag, if it exists, and otherwise just our name
+  definition.tag = baseTag || definition.__name;
+  if (baseTag) {
+    // if there is a base tag, use secondary 'is' specifier
+    definition.is = definition.__name;
+  }
+}
+
+function resolvePrototypeChain(definition) {
+  // if we don't support __proto__ we need to locate the native level
+  // prototype for precise mixing in
+  if (!Object.__proto__) {
+    // default prototype
+    var nativePrototype = HTMLElement.prototype;
+    // work out prototype when using type-extension
+    if (definition.is) {
+      var inst = document.createElement(definition.tag);
+      nativePrototype = Object.getPrototypeOf(inst);
+    }
+    // ensure __proto__ reference is installed at each point on the prototype
+    // chain.
+    // NOTE: On platforms without __proto__, a mixin strategy is used instead
+    // of prototype swizzling. In this case, this generated __proto__ provides
+    // limited support for prototype traversal.
+    var proto = definition.prototype, ancestor;
+    var foundPrototype = false;
+    while (proto) {
+      if (proto == nativePrototype) {
+        foundPrototype = true;
+      }
+      ancestor = Object.getPrototypeOf(proto);
+      if (ancestor) {
+        proto.__proto__ = ancestor;
+      }
+      proto = ancestor;
+    }
+    if (!foundPrototype) {
+      // Note the spec actually allows this, but it results in broken elements
+      // and is difficult to polyfill correctly, so we throw
+      console.warn(definition.tag + ' prototype not found in prototype chain for ' +
+        definition.is);
+    }
+    // cache this in case of mixin
+    definition.native = nativePrototype;
+  }
+}
+
+// SECTION 4
+
+function instantiate(definition) {
+  // 4.a.1. Create a new object that implements PROTOTYPE
+  // 4.a.2. Let ELEMENT by this new object
+  //
+  // the custom element instantiation algorithm must also ensure that the
+  // output is a valid DOM element with the proper wrapper in place.
+  //
+  return upgradeWithDefinition(domCreateElement(definition.tag), definition);
+}
+
+// element registry (maps tag names to definitions)
+
+var registry = {};
+
+function getRegisteredDefinition(name) {
+  if (name) {
+    return registry[name.toLowerCase()];
+  }
+}
+
+function registerDefinition(name, definition) {
+  registry[name] = definition;
+}
+
+function generateConstructor(definition) {
+  return function() {
+    return instantiate(definition);
+  };
+}
+
+var HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
+function createElementNS(namespace, tag, typeExtension) {
+  // NOTE: we do not support non-HTML elements,
+  // just call createElementNS for non HTML Elements
+  if (namespace === HTML_NAMESPACE) {
+    return createElement(tag, typeExtension);
+  } else {
+    return domCreateElementNS(namespace, tag);
+  }
+}
+
+function createElement(tag, typeExtension) {
+  // TODO(sjmiles): ignore 'tag' when using 'typeExtension', we could
+  // error check it, or perhaps there should only ever be one argument
+  if (tag) {
+    tag = tag.toLowerCase();
+  }
+  if (typeExtension) {
+    typeExtension = typeExtension.toLowerCase();
+  }
+  var definition = getRegisteredDefinition(typeExtension || tag);
+  if (definition) {
+    if (tag == definition.tag && typeExtension == definition.is) {
+      return new definition.ctor();
+    }
+    // Handle empty string for type extension.
+    if (!typeExtension && !definition.is) {
+      return new definition.ctor();
+    }
+  }
+  var element;
+  if (typeExtension) {
+    element = createElement(tag);
+    element.setAttribute('is', typeExtension);
+    return element;
+  }
+  element = domCreateElement(tag);
+  // Custom tags should be HTMLElements even if not upgraded.
+  if (tag.indexOf('-') >= 0) {
+    implementPrototype(element, HTMLElement);
+  }
+  return element;
+}
+
+// capture native createElement before we override it
+var domCreateElement = document.createElement.bind(document);
+var domCreateElementNS = document.createElementNS.bind(document);
+
+// Create a custom 'instanceof'. This is necessary when CustomElements
+// are implemented via a mixin strategy, as for example on IE10.
+var isInstance;
+if (!Object.__proto__ && !useNative) {
+  isInstance = function(obj, ctor) {
+    // Allows instanceof(<div>, HTMLElement.prototype) to work
+    if (obj instanceof ctor) {
+      return true;
+    }
+    var p = obj;
+    while (p) {
+      // NOTE: this is not technically correct since we're not checking if
+      // an object is an instance of a constructor; however, this should
+      // be good enough for the mixin strategy.
+      if (p === ctor.prototype) {
+        return true;
+      }
+      p = p.__proto__;
+    }
+    return false;
+  };
+} else {
+  isInstance = function(obj, base) {
+    return obj instanceof base;
+  };
+}
+
+// wrap a dom object method that works on nodes such that it forces upgrade
+function wrapDomMethodToForceUpgrade(obj, methodName) {
+  var orig = obj[methodName];
+  obj[methodName] = function() {
+    var n = orig.apply(this, arguments);
+    upgradeAll(n);
+    return n;
+  };
+}
+
+wrapDomMethodToForceUpgrade(Node.prototype, 'cloneNode');
+wrapDomMethodToForceUpgrade(document, 'importNode');
+
+// exports
+document.registerElement = register;
+document.createElement = createElement; // override
+document.createElementNS = createElementNS; // override
+scope.registry = registry;
+scope.instanceof = isInstance;
+scope.reservedTagList = reservedTagList;
+scope.getRegisteredDefinition = getRegisteredDefinition;
+
+// bc
+document.register = document.registerElement;
+
+});