@webqit/oohtml 2.1.55 → 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>
@@ -491,37 +498,7 @@ OOHTML is being developed as something to be used today - via a polyfill.
 
 └ This is to be placed early on in the document and should be a classic script without any `defer` or `async` directives!
 
-<details><summary>Want Async Loading?</summary>
-
-If you must load the script "async", one little trade-off has to be made for `<script scoped>` and `<script stateful>` elements to have them ignored by the browser until the polyfill comes picking them up: *employing a custom MIME type in place of the standard `text/javascript` and `module` types*, in which case, a `<meta name="scoped-js">` element is used to configure the polyfill to honor the custom MIME type:
-
-```html
-<head>
-  <meta name="scoped-js" content="script.mimeType=some-mime">
-  <script async src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
-</head>
-<body>
-  <script type="some-mime" scoped>
-    console.log(this); // body
-  </script>
-</body>
-```
-
-The custom MIME type strategy also comes in as a "fix" for when in a browser or other runtime where the polyfill is not able to intercept `<script scoped>` and `<script stateful>` elements ahead of the runtime - e.g. where...
-
-```html
-<body>
-  <script scoped>
-    console.log(this); // body
-  </script>
-</body>
-```
-
-...still gives the `window` object in the console.
-
-</details>
-
-For the Scoped Styles feature, you'd also need something like the [samthor/scoped](https://github.com/samthor/scoped) polyfill (more details below):
+└ For the Scoped Styles feature, you'd also need something like the [samthor/scoped](https://github.com/samthor/scoped) polyfill (more details below):
 
 ```html
 <head>
@@ -559,6 +536,34 @@ Also, if you'll be going ahead to build a real app to see OOHTML in action, you
 
 <details><summary>Implementation Notes</summary>
 
++ **Loading Requirements**. As specified above, the OOHTML script tag is to be placed early on in the document and should be a classic script without any `defer` or `async` directives!
+    
+    If you must load the script "async", one little trade-off has to be made for `<script scoped>` and `<script stateful>` elements to have them ignored by the browser until the polyfill comes picking them up: *employing a custom MIME type in place of the standard `text/javascript` and `module` types*, in which case, a `<meta name="scoped-js">` element is used to configure the polyfill to honor the custom MIME type:
+
+    ```html
+    <head>
+      <meta name="scoped-js" content="script.mimeType=some-mime">
+      <script async src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
+    </head>
+    <body>
+      <script type="some-mime" scoped>
+        console.log(this); // body
+      </script>
+    </body>
+    ```
+
+    The custom MIME type strategy also comes in as a "fix" for when in a browser or other runtime where the polyfill is not able to intercept `<script scoped>` and `<script stateful>` elements ahead of the runtime - e.g. where...
+
+    ```html
+    <body>
+      <script scoped>
+        console.log(this); // body
+      </script>
+    </body>
+    ```
+
+    ...still gives the `window` object in the console.
+
 + **Scoped/Stateful Scripts**. This feature is an extension of [Stateful JS](https://github.com/webqit/stateful-js). The default OOHTML build is based on the [Stateful JS Lite APIs](https://github.com/webqit/stateful-js#stateful-js-lite) and this means that `<script stateful></script>` and `<script scoped></script>` elements are parsed "asynchronously", in the same timing as `<script type="module"></script>`!
 
     This timing works perfectly generally, but if you have a requirment to have classic scripts follow their [native synchronous timing](https://html.spec.whatwg.org/multipage/parsing.html#scripts-that-modify-the-page-as-it-is-being-parsed), then you need to the *realtime* OOHTML build:
@@ -623,70 +628,71 @@ 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*
 
 The following is how something you could call a Single Page Application ([SPA](https://en.wikipedia.org/wiki/Single-page_application)) could be made - with zero tooling:
 
-└ *First, two components that are themselves analogous to a Single File Component ([SFC](https://vuejs.org/guide/scaling-up/sfc.html))*:
-
-<details><summary>Code</summary>
-
-```html
-<template def="pages">
++ *First, two components that are themselves analogous to a Single File Component ([SFC](https://vuejs.org/guide/scaling-up/sfc.html))*:
 
-  <template def="layout">
-    <header def="header"></header>
-    <footer def="footer"></footer>
-  </template>
+    <details><summary>Code</summary>
 
-  <!-- Home Page -->
-  <template def="home" extends="layout">
-    <main def="main" namespace>
-      <h1 id="banner">Home Page</h1>
-      <a id="cta" href="#/products">Go to Products</a>
-      <template scoped></template>
-      <style scoped></style>
-      <script scoped></script>
-    </main>
-  </template>
-
-  <!-- Products Page -->
-  <template def="products" extends="layout">
-    <main def="main" namespace>
-      <h1 id="banner">Products Page</h1>
-      <a id="cta" href="#/home">Go to Home</a>
-      <template scoped></template>
-      <style scoped></style>
-      <script scoped></script>
-    </main>
-  </template>
+    ```html
+    <template def="pages">
+
+      <template def="layout">
+        <header def="header"></header>
+        <footer def="footer"></footer>
+      </template>
+
+      <!-- Home Page -->
+      <template def="home" extends="layout">
+        <main def="main" namespace>
+          <h1 id="banner">Home Page</h1>
+          <a id="cta" href="#/products">Go to Products</a>
+          <template scoped></template>
+          <style scoped></style>
+          <script scoped></script>
+        </main>
+      </template>
+
+      <!-- Products Page -->
+      <template def="products" extends="layout">
+        <main def="main" namespace>
+          <h1 id="banner">Products Page</h1>
+          <a id="cta" href="#/home">Go to Home</a>
+          <template scoped></template>
+          <style scoped></style>
+          <script scoped></script>
+        </main>
+      </template>
 
-</template>
-```
+    </template>
+    ```
 
-</details>
+    </details>
 
-└ *Then a 2-line router that alternates the view based on the URL hash*:
++ *Then a 2-line router that alternates the view based on the URL hash*:
 
-<details><summary>Code</summary>
+    <details><summary>Code</summary>
 
-```html
-<body importscontext="/pages/home">
-
-  <import ref="#header"></import>
-  <import ref="#main"></import>
-  <import ref="#footer"></import>
-  
-  <script>
-  const route = () => { document.body.setAttribute('importscontext', '/pages' + location.hash.substring(1)); };
-  window.addEventListener('hashchange', route);
-  </script>
-  
-</body>
-```
+    ```html
+    <body importscontext="/pages/home">
+
+      <import ref="#header"></import>
+      <import ref="#main"></import>
+      <import ref="#footer"></import>
+      
+      <script>
+      const route = () => { document.body.setAttribute('importscontext', '/pages' + location.hash.substring(1)); };
+      window.addEventListener('hashchange', route);
+      </script>
+      
+    </body>
+    ```
 
-</details>
+    </details>
 
 ### Example 2: *Multi-Level Namespacing*
 
@@ -763,93 +769,139 @@ The following is a Listbox component lifted directly from the [ARIA Authoring Pr
 
 The following is a custom element that derives its Shadow DOM from an imported `<tenplate>` element. The idea is to have different Shadow DOM layouts defined and let the "usage" context decide which variant is imported!
 
-└ *First, two layout options defined for the Shadow DOM*:
++ *First, two layout options defined for the Shadow DOM*:
 
-<details><summary>Code</summary>
+    <details><summary>Code</summary>
 
-```html
-<template def="vendor1">
+    ```html
+    <template def="vendor1">
 
-  <template def="components-layout1">
-    <template def="magic-button">
-      <span id="icon"></span> <span id="text"></span>
-    </template>
-  </template>
+      <template def="components-layout1">
+        <template def="magic-button">
+          <span id="icon"></span> <span id="text"></span>
+        </template>
+      </template>
 
-  <template def="components-layout2">
-    <template def="magic-button">
-      <span id="text"></span> <span id="icon"></span>
-    </template>
-  </template>
+      <template def="components-layout2">
+        <template def="magic-button">
+          <span id="text"></span> <span id="icon"></span>
+        </template>
+      </template>
 
-</template>
-```
+    </template>
+    ```
 
-</details>
+    </details>
 
-└ *Next, the Shadow DOM creation that imports its layout from context*:
++ *Next, the Shadow DOM creation that imports its layout from context*:
 
-<details><summary>Code</summary>
+    <details><summary>Code</summary>
 
-```js
-customElements.define('magic-button', class extends HTMLElement {
-  connectedCallback() {
-    const shadowRoot = this.attachShadow({ mode: 'open' });
-    this.import('@vendor1/magic-button', template => {
-      shadowRoot.appendChild( template.content.cloneNode(true) );
+    ```js
+    customElements.define('magic-button', class extends HTMLElement {
+      connectedCallback() {
+        const shadowRoot = this.attachShadow({ mode: 'open' });
+        this.import('@vendor1/magic-button', template => {
+          shadowRoot.appendChild( template.content.cloneNode(true) );
+        });
+      }
     });
-  }
-});
-```
+    ```
 
-</details>
+    </details>
 
-└ *Then, the part where we just drop the component in "layout" contexts*:
++ *Then, the part where we just drop the component in "layout" contexts*:
+
+    <details><summary>Code</summary>
+
+    ```html
+    <div contextname="vendor1" importscontext="/vendor1/components-layout1">
+
+      <magic-button></magic-button>
+
+      <aside contextname="vendor1" importscontext="/vendor1/components-layout2">
+        <magic-button></magic-button>
+      </aside>
+
+    </div>
+    ```
+
+    </details>
+
+### Example 4: *List Items*
+
+The following is a "component" that derives its list items and other reusable snippets from "scoped" `<tenplate>` elements. The idea is to have a "self-contained" component that's all markup-based, not class-based!
 
 <details><summary>Code</summary>
 
 ```html
-<div contextname="vendor1" importscontext="/vendor1/components-layout1">
+<div namespace>
 
-  <magic-button></magic-button>
+  <ul id="list"></ul>
 
-  <aside contextname="vendor1" importscontext="/vendor1/components-layout2">
-    <magic-button></magic-button>
-  </aside>
+  <template def="item" scoped>
+    <li><a>Item</a></li>
+  </template>
+
+  <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: *List Items*
+### Example 4: *Live List*
 
-The following is a "component" that derives its list items and other reusable snippets from "scoped" `<tenplate>` elements. The idea is to have a "self-contained" component that's all markup-based, not class-based!
+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>
 
-  <import ref="other"></import>
   <ul id="list"></ul>
-  <import ref="other"></import>
 
   <template def="item" scoped>
-    <li>
-      <a></a>
-    </li>
-  </template>
-
-  <template def="other" scoped>
-    <button>Call to Action >><button>
+    <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.55",
+  "version": "2.1.57",
   "license": "MIT",
   "repository": {
     "type": "git",