CETEIcean 1.8.0-beta.1 → 1.9.0

package/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "cSpell.words": [
+    "Ordinality",
+    "prefixdef"
+  ]
+}

package/README.md

@@ -12,10 +12,7 @@ documents to be displayed in a web browser without first transforming them to
 HTML. It uses the emerging [Web Components](http://webcomponents.org) standards,
 especially [Custom Elements](http://w3c.github.io/webcomponents/spec/custom/). It 
 works by loading the TEI file dynamically, renaming the elements to follow the
-Custom Elements conventions, and registering them with the browser. Browsers
-that support Web Components will use them to add the appropriate display and
-behaviors to the TEI elements; other browsers will use fallback methods to
-achieve the same result.
+Custom Elements conventions, and registering them with the browser.
 
 Because it preserves the full structure and information from your TEI data model,
 CETEIcean allows you to build rich web applications from your source documents

package/TEI-CE_specification.md

@@ -0,0 +1,86 @@
+# TEI Custom Elements Specification and Contract
+
+When CETEIcean processes a TEI document, the document structures will by default be converted as follows:
+
+## Elements
+
+All tag names will be converted into [prefix]-[lowercased tagname]. The prefix can be defined in a behaviors object. There must be one prefix defined per XML namespace. There are three predefined prefixes:
+
+```js
+  "namespaces": {
+    "tei": "http://www.tei-c.org/ns/1.0",
+    "teieg": "http://www.tei-c.org/ns/Examples",
+    "rng": "http://relaxng.org/ns/structure/1.0"  
+  }   
+```
+
+These prefixes can be remapped in the behaviors object passed to CETEIcean.
+
+### CETEIcean-created Elements
+
+CETEIcean may add the following elements to markup it processes:
+
+* `<cetei-content>`: holds any content returned from a behavior function call.
+* `<cetei-original`: wraps any original content that has been hidden and replaced by the result of a behavior function call.
+
+## Attributes
+
+CETEIcean adds a number of data attributes when it processes an XML element:
+
+* `@data-origname`: contains the original tag name with whatever upper- or lowercasing it used. The HTML DOM normalizes tag names to uppercase.
+* `@data-origatts`: contains a list of attribute names on the element before it was processed with whatever upper- or lowercasing they used. The HTML DOM normalizes attribute names to lowercase.
+* `@data-processed`: a flag CETEIcean uses to determine whether elements have had behaviors applied. Normally, this will happen upon insertion into the browser DOM.
+* `@data-empty`: a flag CETEIcean uses to mark empty elements (these may not remain empty after behaviors have been applied).
+
+### Automatically Converted Attributes
+
+* `@xml:id` is preserved and the value copied to `@id`.
+* `@xml:lang` is preserved and the value copied to `@lang`.
+* `@xmlns` is removed and its value copied to `@data-xmlns`.
+* `@rendition` is preserved and its value copied to `@class`.
+
+## Processing Instructions and Comments
+
+PIs and comments are copied over into the result, so, for example, `<?xml-model?>` PIs pointing to a schema will be present before the root element of the converted document. The XML declaration, if present, is not a PI, and will not be copied over.
+
+## Document Type Declarations
+
+DTDs are not copied over into the result.
+
+## Contract
+
+If a source XML document has been processed into CETEIcean Custom Elements and is then re-serialized into XML using the `CETEI.utilities` instance method `resetAndSerialize()`, then the result will be logically equivalent to the source, provided that additional processing has not altered the document. Note that custom behaviors have direct access to the DOM, and thus are capable of directly manipulating the document in any way. No guarantees can be made as to the consistency of a serialized document if it has been rearranged, fo example.
+
+This contract means that CETEIcean can be used in conjunction with in-browser editing or annotation tools to produce prospectively valid output XML.
+
+For example, the built-in behavior for TEI `<ref>` is to create an HTML anchor tag with the content being the content of the `<ref>` and the `@href` attribute containing the pointer in the `@target` of the `<ref>` (or the first pointer if there are more than one). Given an element like
+
+```xml
+<ref target="https://github.com/TEIC/TEI/blob/dev/P5/Source/guidelines-en.xml" mimeType="application/tei+xml">guidelines-en.xml</ref>
+```
+
+The structure CETEIcean creates will look like this:
+
+```xml
+<tei-ref target="https://github.com/TEIC/TEI/blob/dev/P5/Source/guidelines-en.xml" mimetype="application/tei+xml" data-origname="ref" data-origatts="target mimeType" data-processed="">
+  <cetei-original hidden="" data-original="">guidelines-en.xml</cetei-original>
+  <a href="https://github.com/TEIC/TEI/blob/dev/P5/Source/guidelines-en.xml">guidelines-en.xml</a>
+</tei-ref>
+```
+
+If this element is loaded into a variable and then passed to the `CETEI.utilities.copyAndReset()` function, the result will be:
+
+```xml
+<tei-ref target="https://github.com/TEIC/TEI/blob/dev/P5/Source/guidelines-en.xml" mimetype="application/tei+xml" data-origname="ref" data-origatts="target mimeType">guidelines-en.xml</tei-ref>
+```
+
+that is, the element as it was after CETEIcean has loaded it, but before it was inserted into the document DOM and had behaviors applied to it.
+
+If this result is then passed to the `CETEI.utilities.serialize()` function, the output is
+
+```xml
+<ref target="https://github.com/TEIC/TEI/blob/dev/P5/Source/guidelines-en.xml" mimeType="application/tei+xml">guidelines-en.xml</ref>
+```
+
+CETEIcean's contract means that 
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "CETEIcean",
-  "version": "1.8.0-beta.1",
+  "version": "1.9.0",
   "description": "JavaScript library to load a TEI XML document and register it as HTML5 custom elements.",
   "main": "src/CETEI.js",
   "type": "module",

package/src/CETEI.js

@@ -61,7 +61,6 @@ class CETEI {
         window.removeEventListener("ceteiceanload", CETEI.restorePosition);
       }
     }
-    
   }
 
   /* 
@@ -69,36 +68,22 @@ class CETEI {
     provided in the first parameter and then calls the makeHTML5 method
     on the returned document.
   */
-  getHTML5(XML_url, callback, perElementFn){
+  async getHTML5(XML_url, callback, perElementFn){
     if (window && window.location.href.startsWith(this.base) && (XML_url.indexOf("/") >= 0)) {
       this.base = XML_url.replace(/\/[^\/]*$/, "/");
     }
-    // Get XML from XML_url and create a promise
-    let promise = new Promise( function (resolve, reject) {
-      let client = new XMLHttpRequest();
-      client.open('GET', XML_url);
-      client.send();
-      client.onload = function () {
-        if (this.status >= 200 && this.status < 300) {
-          resolve(this.response);
-        } else {
-          reject(this.statusText);
-        }
-      };
-      client.onerror = function () {
-        reject(this.statusText);
-      };
-    })
-    .catch( function(reason) {
-      console.log("Could not get XML file.");
-      if (this.debug) {
-          console.log(reason);
-      }
-    });
-
-    return promise.then((XML) => {
+    try {
+      const response = await fetch(XML_url);
+      if (response.ok) {
+        const XML = await response.text();
         return this.makeHTML5(XML, callback, perElementFn);
-    });
+      } else {
+        console.log(`Could not get XML file ${XML_url}.\nServer returned ${response.status}: ${response.statusText}`);
+      }
+    }
+    catch (error) {
+      console.log(error);
+    }
   }
 
   /* 
@@ -120,7 +105,7 @@ class CETEI {
       let newElement;
       if (this.namespaces.has(el.namespaceURI ? el.namespaceURI : "")) {
         let prefix = this.namespaces.get(el.namespaceURI ? el.namespaceURI : "");
-        newElement = this.document.createElement(`${prefix}-${el.localName}`);
+        newElement = this.document.createElement(`${prefix}-${el.localName.toLowerCase()}`);
       } else {
         newElement = this.document.importNode(el, false);
       }
@@ -207,8 +192,23 @@ class CETEI {
       return newElement;
     }
 
-    this.dom = convertEl(XML_dom.documentElement);
-    this.utilities.dom = this.dom;
+    this.dom = this.document.createDocumentFragment();
+    for (let node of Array.from(XML_dom.childNodes)) {
+      // Node.ELEMENT_NODE
+      if (node.nodeType == 1) {
+        this.dom.appendChild(convertEl(node));
+      }
+      // Node.PROCESSING_INSTRUCTION_NODE
+      if (node.nodeType == 7) {
+        this.dom.appendChild(this.document.importNode(node, true));
+      }
+      // Node.COMMENT_NODE
+      if (node.nodeType == 8) {
+        this.dom.appendChild(this.document.importNode(node, true));
+      }
+    }
+    // DocumentFragments don't work in the same ways as other nodes, so use the root element.
+    this.utilities.dom = this.dom.firstElementChild;
 
     if (callback) {
       callback(this.dom, this);
@@ -255,6 +255,9 @@ class CETEI {
   processPage() {
     this.els = learnCustomElementNames(this.document);
     this.applyBehaviors();
+    if (window) {
+      window.dispatchEvent(ceteiceanLoad);
+    }
   }
 
   /* 
@@ -282,19 +285,19 @@ class CETEI {
   by the provided function.
 
   Called by getHandler() and fallback()
-*/
+  */
 append(fn, elt) {
   let self = this;
-  if (elt) {
+  if (elt && !elt.hasAttribute('data-processed')) {
     let content = fn.call(self.utilities, elt);
-    if (content && !self.childExists(elt.firstElementChild, content.nodeName)) {
+    if (content) {
       self.appendBasic(elt, content);
     }
   } else {
     return function() {
       if (!this.hasAttribute("data-processed")) {
         let content = fn.call(self.utilities, this);
-        if (content && !self.childExists(this.firstElementChild, content.nodeName)) {
+        if (content) {
           self.appendBasic(this, content);
         }
       }
@@ -398,7 +401,7 @@ getHandler(behaviors, fn) {
 }
 
 insert(elt, strings) {
-  let span = this.document.createElement("span");
+  let content = this.document.createElement("cetei-content");
   for (let node of Array.from(elt.childNodes)) {
     // nodeType 1 is Node.ELEMENT_NODE
     if (node.nodeType === 1 && !node.hasAttribute("data-processed")) {
@@ -408,19 +411,23 @@ insert(elt, strings) {
   // If we have before and after tags have them parsed by
   // .innerHTML and then add the content to the resulting child
   if (strings[0].match("<[^>]+>") && strings[1] && strings[1].match("<[^>]+>")) { 
-    span.innerHTML = strings[0] + elt.innerHTML + (strings[1]?strings[1]:"");
+    content.innerHTML = strings[0] + elt.innerHTML + (strings[1]?strings[1]:"");
   } else {
-    span.innerHTML = strings[0];
-    span.setAttribute("data-before", strings[0].replace(/<[^>]+>/g,"").length);
+    content.innerHTML = strings[0];
+    content.setAttribute("data-before", strings[0].replace(/<[^>]+>/g,"").length);
     for (let node of Array.from(elt.childNodes)) {
-      span.appendChild(node.cloneNode(true));
+      content.appendChild(node.cloneNode(true));
     }
     if (strings.length > 1) {
-      span.innerHTML += strings[1];
-      span.setAttribute("data-after", strings[1].replace(/<[^>]+>/g,"").length);
+      content.innerHTML += strings[1];
+      content.setAttribute("data-after", strings[1].replace(/<[^>]+>/g,"").length);
     } 
   }
-  return span;
+  if (content.childNodes.length < 2) {
+    return content.firstChild;
+  } else {
+    return content;
+  }
 }
 
 // Runs behaviors recursively on the supplied element and children
@@ -482,7 +489,7 @@ define(names) {
 }
 
 /* 
-  Provides fallback functionality for browsers where Custom Elements
+  Provides fallback functionality for environments where Custom Elements
   are not supported.
 
   Like define(), this is called by makeHTML5(), but can be called
@@ -496,9 +503,10 @@ fallback(names) {
           this.dom && !this.done 
           ? this.dom
           : this.document
-        ).getElementsByTagName(utilities.tagName(name)))) {
+        ).querySelectorAll(utilities.tagName(name)))) {
         if (!elt.hasAttribute("data-processed")) {
           this.append(fn, elt);
+          elt.setAttribute("data-processed", "");
         }
       }
     }
@@ -518,6 +526,7 @@ fallback(names) {
     if (!window.location.hash) {
       let scroll;
       if (scroll = window.sessionStorage.getItem(window.location + "-scroll")) {
+        window.sessionStorage.removeItem(window.location + "-scroll");
         setTimeout(function() {
           window.scrollTo(0, scroll);
         }, 100);

package/src/behaviors.js

@@ -21,7 +21,7 @@ export function addBehaviors(bhvs) {
   }
   if (bhvs["functions"]) {
     for (let fn of Object.keys(bhvs["functions"])) {
-      this.utilities[fn] = bhvs["functions"][fn];
+      this.utilities[fn] = bhvs["functions"][fn].bind(this.utilities);
     }
   }
   if (bhvs["handlers"]) {

package/src/defaultBehaviors.js

@@ -9,10 +9,12 @@ export default {
     // inserts a link inside <ptr> using the @target; the link in the
     // @href is piped through the rw (rewrite) function before insertion
     "ptr": ["<a href=\"$rw@target\">$@target</a>"],
-    // wraps the content of the <ref> in an HTML link
+    // wraps the content of the <ref> in an HTML link with the @target in 
+    // the @href. If there are multiple @targets, only the first is used.
     "ref": [
       ["[target]", ["<a href=\"$rw@target\">","</a>"]]
     ],
+    // creates an img tag with the @url as the src attribute
     "graphic": function(elt) {
       let content = new Image();
       content.src = this.rw(elt.getAttribute("url"));
@@ -71,15 +73,17 @@ export default {
         }
         let note = doc.createElement("li");
         note.id = id;
-        note.innerHTML = elt.innerHTML
+        note.innerHTML = elt.innerHTML;
         notes.appendChild(note);
         return content;
       }],
       ["_", ["(",")"]]
     ],
+    // Hide the teiHeader by default
     "teiHeader": function(e) {
       this.hideContent(e, false);
     },
+    // Make the title element the HTML title
     "title": [
       ["tei-titlestmt>tei-title", function(elt) {
         const doc = elt.ownerDocument;

package/src/dom.js

@@ -16,5 +16,5 @@ export function learnElementNames(XML_dom, namespaces) {
 }
 
 export function learnCustomElementNames(HTML_dom) {
-  return Array.from(HTML_dom.querySelectorAll("*[data-origname]"), e => e.localName.replace(/(\w+)-.+/,"$1:") + e.getAttribute("data-origname"));
+  return new Set(Array.from(HTML_dom.querySelectorAll("*[data-origname]"), e => e.localName.replace(/(\w+)-.+/,"$1:") + e.getAttribute("data-origname")));
 }

package/src/utilities.js

@@ -1,7 +1,7 @@
 export function getOrdinality(elt, name) {
   let pos = 1;
   let e = elt;
-  while (e && e.previousElementSibling !== null && (name?e.previousElementSibling.localName == name:true)) {
+  while (e && e.previousElementSibling !== null && (name ? e.previousElementSibling.localName == name : true)) {
     pos++;
     e = e.previousElementSibling;
     if (!e.previousElementSibling) {
@@ -17,11 +17,21 @@ export function getOrdinality(elt, name) {
 */ 
 export function copyAndReset(node) {
   const doc = node.ownerDocument;
-  let clone = (n) => {
-    // nodeType 1 is Node.ELEMENT_NODE
-    let result = n.nodeType === 1
-      ? doc.createElement(n.nodeName)
-      : n.cloneNode(true);
+  let clone = (n) => {    
+    let result;
+    switch (n.nodeType) {
+      case 1: // nodeType 1 is Node.ELEMENT_NODE
+        result = doc.createElement(n.nodeName);
+        break;
+      case 9: // nodeType 9 is Node.DOCUMENT_NODE
+        result = doc.implementation.createDocument();
+        break;
+      case 11: // nodeType 11 is Node.DOCUMENT_FRAGMENT_NODE
+        result = doc.createDocumentFragment();
+        break;
+      default:
+        result = n.cloneNode(true);
+    }
     if (n.attributes) {
       for (let att of Array.from(n.attributes)) {
         if (att.name !== "data-processed") {
@@ -32,23 +42,20 @@ export function copyAndReset(node) {
     for (let nd of Array.from(n.childNodes)){
       // nodeType 1 is Node.ELEMENT_NODE
       if (nd.nodeType == 1) {
-        if (!n.hasAttribute("data-empty")) {
-          if (nd.hasAttribute("data-original")) {
-            for (let childNode of Array.from(nd.childNodes)) {
-              let child = result.appendChild(clone(childNode));
-              // nodeType 1 is Node.ELEMENT_NODE
-              if (child.nodeType === 1 && child.hasAttribute("data-origid")) {
-                child.setAttribute("id", child.getAttribute("data-origid"));
-                child.removeAttribute("data-origid");
-              }
+        if (nd.hasAttribute("data-original")) {
+          for (let childNode of Array.from(nd.childNodes)) {
+            let child = result.appendChild(clone(childNode));
+            // nodeType 1 is Node.ELEMENT_NODE
+            if (child.nodeType === 1 && child.hasAttribute("data-origid")) {
+              child.setAttribute("id", child.getAttribute("data-origid"));
+              child.removeAttribute("data-origid");
             }
-            return result;
-          } else {
-            result.appendChild(clone(nd));
           }
+          return result;
+        } else if (nd.hasAttribute("data-origname")) {
+          result.appendChild(clone(nd));
         }
-      }
-      else {
+      } else {
         result.appendChild(nd.cloneNode());
       }
     }
@@ -66,13 +73,12 @@ export function first(urls) {
 }
 
 /* 
-  Wraps the content of the element parameter in a <span data-original>
-  with display set to "none".
+  Wraps the content of the element parameter in a hidden <cetei-original data-original>
 */
 export function hideContent(elt, rewriteIds = true) {
   const doc = elt.ownerDocument;
   if (elt.childNodes.length > 0) {
-    let hidden = doc.createElement("span");
+    let hidden = doc.createElement("cetei-original");
     elt.appendChild(hidden);
     hidden.setAttribute("hidden", "");
     hidden.setAttribute("data-original", "");
@@ -139,12 +145,20 @@ export function getPrefixDef(prefix) {
 */
 export function rw(url) {
   if (!url.match(/^(?:http|mailto|file|\/|#).*$/)) {
-    return this.base + this.utilities.first(url);
+    return this.base + first(url);
   } else {
     return url;
   }
 }
 
+/*
+  Combines the functionality of copyAndReset() and serialize() to return
+  a "clean" version of the XML markup.
+ */
+export function resetAndSerialize(el, stripElt, ws) {
+  return serialize(copyAndReset(el), stripElt, ws);
+}
+
 /* 
   Takes an element and serializes it to an XML string or, if the stripElt
   parameter is set, serializes the element's content. The ws parameter, if
@@ -153,9 +167,12 @@ export function rw(url) {
 */
 export function serialize(el, stripElt, ws) {
   let str = "";
-  let ignorable = (txt) => {
+  const ignorable = (txt) => {
     return !(/[^\t\n\r ]/.test(txt));
   }
+  if (el.nodeType === 9 || el.nodeType === 11) { // nodeType 9 is Node.DOCUMENT_NODE; nodeType 11 is Node.DOCUMENT_FRAGMENT_NODE
+    str += "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
+  }
   // nodeType 1 is Node.ELEMENT_NODE
   if (!stripElt && el.nodeType == 1) {
     if ((typeof ws === "string") && ws !== "") {
@@ -180,7 +197,6 @@ export function serialize(el, stripElt, ws) {
       str += "/>";
     }
   }
-  //TODO: Be smarter about skipping generated content with hidden original
   for (let node of Array.from(el.childNodes)) {
     // nodeType 1 is Node.ELEMENT_NODE
     // nodeType 7 is Node.PROCESSING_INSTRUCTION_NODE
@@ -194,10 +210,16 @@ export function serialize(el, stripElt, ws) {
         }
         break;
       case 7:
-        str += "<?" + node.nodeValue + "?>";
+        str += `<?${node.nodeName} ${node.nodeValue}?>`;
+        if (el.nodeType === 9 || el.nodeType === 11) {
+          str += "\n";
+        }
         break;
       case 8:
-        str += "<!--" + node.nodeValue + "-->";
+        str += `<!--${node.nodeValue}-->`;
+        if (el.nodeType === 9 || el.nodeType === 11) {
+          str += "\n";
+        }
         break;
       default:
         if (stripElt && ignorable(node.nodeValue)) {
@@ -209,7 +231,7 @@ export function serialize(el, stripElt, ws) {
         str += node.nodeValue;
     }
   }
-  if (!stripElt && el.childNodes.length > 0) {
+  if (!stripElt && el.nodeType == 1 && el.childNodes.length > 0) {
     if (typeof ws === "string") {
       str += "\n" + ws + "</";
     } else  {
@@ -217,6 +239,9 @@ export function serialize(el, stripElt, ws) {
     }
     str += el.getAttribute("data-origname") + ">";
   }
+  if (el.nodeType === 9 || el.nodeType === 11) {
+    str += "\n";
+  }
   return str;
 }
 
@@ -249,9 +274,9 @@ export function defineCustomElement(name, behavior = null, debug = false) {
         if (!this.matches(":defined")) { // "Upgraded" undefined elements can have attributes & children; new elements can't
           if (behavior) {
             behavior.call(this);
+            // We don't want to double-process elements, so add a flag
+            this.setAttribute("data-processed", "");
           }
-          // We don't want to double-process elements, so add a flag
-          this.setAttribute("data-processed", "");
         }
       }
       // Process new elements when they are connected to the browser DOM
@@ -259,8 +284,8 @@ export function defineCustomElement(name, behavior = null, debug = false) {
         if (!this.hasAttribute("data-processed")) {
           if (behavior) {
             behavior.call(this);
+            this.setAttribute("data-processed", "");
           }
-          this.setAttribute("data-processed", "");
         }
       };
     });

package/test/CETEIcean.css

@@ -212,6 +212,9 @@ tei-cell {
   border-bottom: thin solid black;
   padding: 2px;
 }
+tei-cell[cols="2"] {
+  grid-column: span 2;
+}
 /* for cell or row with @role = label */
 tei-cell[data-tei-role=label] {
   font-weight: bold;