@webqit/oohtml 2.1.56 → 2.1.57

package/README.md

@@ -161,18 +161,17 @@ foo.addEventListener('load', loadedCallback);
 └ *The HTMLImports API  for programmatic module import*:
 
 ```js
-document.import('/foo#fragment1', divElement => {
-    console.log(divElement); // module:/foo#fragment2, received synchronously
-});
+const import1 = document.import('/foo#fragment1');
+console.log(import1); // { value: div }
 ```
 
 ```js
-document.import('/foo/nested#fragment2', divElement => {
-    console.log(divElement); // module:/foo/nested#fragment2;
-});
+const import2 = document.import('/foo/nested#fragment2');
+console.log(import2); // { value: div }
 ```
 
 └ *Scoped templates for object-scoped module system*:
+> With an equivalent `Element.prototype.import()` API for accessing scoped modules
 
 ```html
 <section> <!-- object with own modules -->
@@ -191,16 +190,16 @@ document.import('/foo/nested#fragment2', divElement => {
 
 ```js
 // Using the HTMLImports API
-document.querySelector('div').import('foo#fragment1', divElement => {
-    console.log(divElement); // the local module: foo#fragment1
-});
+const moduleHost = document.querySelector('div');
+const localImport1 = moduleHost.import('foo#fragment1'); // the local module: foo#fragment1
+console.log(localImport1); // { value: div }
 ```
 
 ```js
 // Using the HTMLImports API
-document.querySelector('div').import('/foo#fragment1', divElement => {
-    console.log(divElement); // the global module: foo#fragment1
-});
+const moduleHost = document.querySelector('div');
+const globalImport1 = moduleHost.import('/foo#fragment1'); // the global module: foo#fragment1
+console.log(globalImport1); // { value: div }
 ```
 
 <details><summary>
@@ -270,6 +269,14 @@ document.import('/foo#fragment1', divElement => {
 });
 ```
 
+```js
+const import1 = document.import('/foo#fragment1', true);
+console.log(import1); // { value: undefined }
+Observer.observe(import1, 'value', divElement => {
+    console.log(divElement); // To be received after remote module has been loaded
+});
+```
+
 └ *"Imports Contexts" for context-based imports resolution*:
 
 ```html
@@ -290,9 +297,9 @@ document.import('/foo#fragment1', divElement => {
 
 ```js
 // Using the HTMLImports API
-document.querySelector('section').import('#fragment2', divElement => {
-    console.log(divElement); // module:/foo/nested#fragment2
-});
+const moduleHost = document.querySelector('section');
+const globalImport2 = moduleHost.import('#fragment2'); // module:/foo/nested#fragment2
+console.log(globalImport2); // { value: div }
 ```
 
 └ *"Imports Contexts" with named contexts*:
@@ -314,9 +321,9 @@ document.querySelector('section').import('#fragment2', divElement => {
 
 ```js
 // Using the HTMLImports API
-document.querySelector('div').import('@context1#fragment2', divElement => {
-    console.log(divElement); // module:/foo/nested#fragment2
-});
+const moduleHost = document.querySelector('div');
+const globalImport2 = moduleHost.import('@context1#fragment2'); // module:/foo/nested#fragment2
+console.log(globalImport2); // { value: div }
 ```
 
 └ *"Imports Contexts" with context inheritance*:
@@ -356,9 +363,9 @@ document.querySelector('div').import('@context1#fragment2', divElement => {
 
 ```js
 // Using the HTMLImports API
-document.querySelector('div').import('#fragment2', divElement => {
-    console.log(divElement); // the local module: foo#fragment2, and if not found, resolves from context to the module: /bar/nested#fragment2
-});
+const moduleHost = document.querySelector('div');
+const localOrGlobalImport2 = moduleHost.import('#fragment2'); // the local module: foo#fragment2, and if not found, resolves from context to the module: /bar/nested#fragment2
+console.log(localOrGlobalImport2); // { value: div }
 ```
 
 </details>
@@ -621,6 +628,7 @@ Here are a few examples in the wide range of use cases these features cover.
 + [Example 2: *Multi-Level Namespacing*](#example-2-multi-level-namespacing)
 + [Example 3: *Dynamic Shadow DOM*](#example-3-dynamic-shadow-dom)
 + [Example 4: *List Items*](#example-4-list-items)
++ [Example 5: *Live List*](#example-4-live-list)
 
 ### Example 1: *Single Page Application*
 
@@ -829,25 +837,71 @@ The following is a "component" that derives its list items and other reusable sn
 ```html
 <div namespace>
 
-  <import ref="other"></import>
   <ul id="list"></ul>
-  <import ref="other"></import>
 
   <template def="item" scoped>
-    <li>
-      <a></a>
-    </li>
+    <li><a>Item</a></li>
   </template>
 
-  <template def="other" scoped>
-    <button>Call to Action >><button>
+  <script scoped>
+    // Import item template
+    let itemImport = this.import('item');
+    let itemTemplate = itemImport.value;
+
+    // Iterate
+    [ 'Item 1', 'Item 2', 'Item 3' ].forEach(entry => {
+      const currentItem = itemTemplate.content.cloneNode(true);
+      // Add to DOM
+      this.namespace.list.appendChild(currentItem);
+      // Render
+      currentItem.innerHTML = entry;
+    });
+  </script>
+
+</div>
+```
+
+</details>
+
+### Example 4: *Live List*
+
+The following is the same list as above but implemented as a live list! Here, we make a few changes: the script element is Stateful; the loop itself now uses the literal `for ... of` construct, [which is capable of rendering live lists](https://github.com/webqit/stateful-js/wiki#with-control-structures), so that any additions and removals on the original list is statically reflected!
+
+<details><summary>Code</summary>
+
+```html
+<div namespace>
+
+  <ul id="list"></ul>
+
+  <template def="item" scoped>
+    <li><a>Item</a></li>
   </template>
 
   <script scoped>
-    this.import('item', template => {
-      const clone = template.content.cloneNode(true);
-      this.namespace.list.appendChild(clone);
-    });
+    // Import item template
+    let itemImport = this.import('item');
+    let itemTemplate = itemImport.value;
+
+    // Iterate
+    let items = [ 'Item 1', 'Item 2', 'Item 3' ];
+    for (let entry of items) {
+      const currentItem = itemTemplate.content.cloneNode(true);
+      // Add to DOM
+      this.namespace.list.appendChild(currentItem);
+      // Remove from DOM whenever corresponding entry is removed
+      if (typeof entry === 'undefined') {
+        currentItem.remove();
+        continue;
+      }
+      // Render
+      currentItem.innerHTML = entry;
+    }
+
+    // Add a new entry
+    setTimeout(() => items.push('Item 4'), 1000);
+    // Remove an new entry
+    setTimeout(() => items.pop(), 2000);
   </script>
 
 </div>

package/package.json

@@ -14,7 +14,7 @@
     "wicg-proposal"
   ],
   "homepage": "https://webqit.io/tooling/oohtml",
-  "version": "2.1.56",
+  "version": "2.1.57",
   "license": "MIT",
   "repository": {
     "type": "git",