@webqit/oohtml 3.1.17 → 3.1.19

package/README.md

@@ -143,16 +143,16 @@ If you'll be going ahead to build a real app with OOHTML, you may want to consid
     + `document.bindings` now becomes: `document.wqBindings`,
     + etc.
 
-    The following is the full syntax table.
+    <details><summary>Show the full syntax table</summary>
 
-    Spec: **data-binding**
+    **Spec: `<meta name="data-binding">`**
 
     | Config | Default Syntax | Description |
     | :----- | :------------- | :---------- |
     | `attr.expr` | `expr` | The "expr" attribute for inline data binding. ([Docs](#inline-data-binding)) |
     | `attr.itemIndex` | `data-index` | The "item index" attribute for assigning indexes to list items. ([Docs](#inline-data-binding))  |
 
-    Spec: **bindings-api**
+    **Spec: `<meta name="bindings-api">`**
 
     | Config | Default Syntax | Description |
     | :----- | :------------- | :---------- |
@@ -160,14 +160,14 @@ If you'll be going ahead to build a real app with OOHTML, you may want to consid
     | `api.bind` | `bind` | The `document.bind()` and `Element.prototype.bind()` methods. ([Docs](#the-bindings-api)) |
     | `api.bindings` | `bindings` | The `document.bindings` and `Element.prototype.bindings` object properties. ([Docs](#the-bindings-api)) |
 
-    Spec: **context-api**
+    **Spec: `<meta name="context-api">`**
 
     | Config | Default Syntax | Description |
     | :----- | :------------- | :---------- |
     | `attr.contextname` | `contextname` | The "context name" attribute on arbitrary elements. ([Docs](#the-context-api)) |
     | `api.contexts` | `contexts` | The `document.contexts` and `Element.prototype.contexts` object properties. ([Docs](#the-context-api)) |
 
-    Spec: **html-imports**
+    **Spec: `<meta name="html-imports">`**
 
     | Config | Default Syntax | Description |
     | :----- | :------------- | :---------- |
@@ -182,7 +182,8 @@ If you'll be going ahead to build a real app with OOHTML, you may want to consid
     | `api.defs` | `defs` | The readonly object property for accessing a `<template>`'s list of definitions. ([Docs](#module-definition)) |
     | `api.import` | `import` | The `document.import()` and `Element.prototype.import()` methods. ([Docs](#imperative-module-imports)) |
 
-    Spec: **namespaced-html**
+
+    **Spec: `<meta name="namespaced-html">`**
 
     | Config | Default Syntax | Description |
     | :----- | :------------- | :---------- |
@@ -190,9 +191,11 @@ If you'll be going ahead to build a real app with OOHTML, you may want to consid
     | `attr.id` | `id` | The "id" attribute on arbitrary elements. ([Docs](#namespacing)) |
     | `api.namespace` | `namespace` | The "namespace" object property on arbitrary elements. ([Docs](#namespacing)) |
 
-    Spec: **scoped-css** (TODO)
+    **Spec: `<meta name="scoped-css">`** (TODO)
+
+    **Spec: `<meta name="scoped-js">`** (TODO)
 
-    Spec: **scoped-js** (TODO)
+    </details>
 
 </details>
 
@@ -219,7 +222,7 @@ OOHTML is effectively different from Web Components (and from the related Declar
 
 ## Modular HTML
 
-Modular HTML is markup written as self-contained objects - wherein an element *encapsulates* their own structure, styling and logic!
+The modern UI is best approached with a modular architecture (think UI component frameworks) wherein we are able to author the bits and pieces as self-contained objects - enabling us *encapsulate* structure, styling and logic!
 
 OOHTML makes this possible by introducing "namespacing" and style and script scoping!
 
@@ -227,7 +230,23 @@ OOHTML makes this possible by introducing "namespacing" and style and script sco
 
 Naming things is hard! That's especially so where you have one global namespace and a miriad of potentially conflicting identifiers to coordinate!
 
-Here, we get a modular naming convention using the `namespace` attribute. This attribute let's us create a naming context for identifiers in a given subtree:
+<details><summary>Learn more</summary>
+
+You want to see how IDs are, in fact, by default, exposed as global variables:
+
+```html
+<div id="foo"><div>
+```
+
+```js
+console.log(window.foo); // div
+```
+
+[Read more](https://stackoverflow.com/questions/6381425/is-there-a-spec-that-the-id-of-elements-should-be-made-global-variable)
+
+</details>
+
+Here, we get a modular naming convention that let's us create a naming context for identifiers in a given subtree - by means of a new `namespace` attribute:
 
 ```html
 <form>
@@ -276,14 +295,21 @@ And when used from the document context, these are resolved against top-level ID
 ```
 
 ```js
-const user = document.querySelector('#~user');
-```
+// Namespace aware ID selectors
+console.log(document.querySelector('#user')); // div#user
+console.log(document.querySelector('#~user')); // div#user
 
-```js
-const user = document.getElementById('~user');
+console.log(document.getElementById('user')); // div#user
+console.log(document.getElementById('~user')); // div#user
+
+console.log(document.querySelector('#url')); // a#url
+console.log(document.querySelector('#~url')); // null... not directly in the "document" namespace
+
+console.log(document.getElementById('url')); // a#url
+console.log(document.getElementById('~url')); // null... not directly in the "document" namespace
 ```
 
-And these also play well as URL targets, with additional support for path expressions denoting a hierarchy of namespaces:
+And these also play well as navigation targets, with additional support for path expressions given a hierarchy of namespaces:
 
 ```html
 <a href="#~user/email">Jump to Email</a>
@@ -334,27 +360,55 @@ function changeCallback(changes) {
 }
 ```
 
-</details>
+</details> 
 
-<details><summary>Learn more</summary>
+<details><summary>Implementation details</summary>
 
-You want to see how IDs are otherwise exposed as global variables:
+In the current implementation, a small random string is automatically prepended to each ID and IDREF token in the DOM to give the browser something "unique" to work with, but without that implementation detail leaking into your application. So, while an element may be seen in the browser console as having a random hash prepended to their ID or IDREF:
 
 ```html
-<div id="foo"><div>
+<!-- Original -->
+<label for="~real-id">Question 1:</label>
+<input id="real-id">
+```
+
+```html
+<!-- Transformed -->
+<label for="~hg3j:real-id">Question 1:</label>
+<input id="~hg3j:real-id">
 ```
 
+the values your application sees are the unprefixed IDs and IDREFs:
+
 ```js
-console.log(window.foo); // div
+console.log(label.htmlFor); // ~real-id
+console.log(input.id); // real-id
+
+console.log(label.getAttribute('for')); // ~real-id
+console.log(input.attributes[0].value); // real-id
 ```
 
-[Read more](https://stackoverflow.com/questions/6381425/is-there-a-spec-that-the-id-of-elements-should-be-made-global-variable)
+Now, for URL targets, e.g. `#~user/email`, the "target" element is given a custom `:target` class while it matches the URL fragment, and this may be accessed in CSS as:
+
+```css
+.\:target {
+  background-color: whitesmoke;
+}
+```
+
+or, to be more complete:
+
+```css
+:target, .\:target {
+  background-color: whitesmoke;
+}
+```
 
 </details>
 
 ### Style and Script Scoping
 
-We often need a way to keep component-specific stylesheets and scripts [scoped to a component](https://vuejs.org/guide/scaling-up/sfc.html). **This is especially crucial to "page components" in an SPA architecture.**
+We often need a way to keep component-specific style sheets and scripts [scoped to a component](https://vuejs.org/guide/scaling-up/sfc.html). **This is especially crucial to "page components" in an SPA architecture.**
 
 Here, we get a new `scoped` attribute that lets us do just that:
 
@@ -372,7 +426,7 @@ Here, we get a new `scoped` attribute that lets us do just that:
 </div>
 ```
 
-And the special "local ID" selector is supported within a scoped style sheet:
+And the special namespace-aware ID selector is supported from within scoped style sheets:
 
 ```html
 <div namespace>
@@ -398,15 +452,15 @@ let { styleSheets, scripts } = user; // APIs that are analogous to the document.
 Here, the `scoped` attribute has two effects on the `<script>` element:
 
 + The `this` keyword is implicitly bound to the script's host element
-+ The `<script>` element is executed again on each re-insertion into the DOM
++ The `<script>` element is (re)executed on each re-insertion into the DOM
 
 </details>
 
 ## HTML Imports
 
-HTML Imports is a realtime *import* system for HTML that's drawn entirely on HTML - and that's worlds apart from [the abandoned `<link type="import">` feature](https://www.w3.org/TR/html-imports/) and the [HTML Modules proposal](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md)! **Something like it is the [`<defs>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs) and [`<use>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use) system in SVG.**
+HTML Imports is a realtime *import* system for HTML that's drawn entirely on HTML - and which addresses a different pain point in comparison to [the abandoned `<link type="import">` feature](https://www.w3.org/TR/html-imports/) and the [HTML Modules proposal](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md)! **Something like it is the [`<defs>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs) and [`<use>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use) system in SVG.**
 
-Here, we get a way to both define and use a snippet within *same* document:
+Here, we get a way to both define and reuse a snippet out of *same* document:
 
 ```html
 <head>
@@ -423,7 +477,7 @@ Here, we get a way to both define and use a snippet within *same* document:
 </body>
 ```
 
-...and optionally support remote documents without a change in paradigm:
+...while optionally supporting remote content without a change in paradigm:
 
 ```html
 <head>
@@ -479,7 +533,7 @@ Here, we get the `def` attribute for defining those - both at the `<template>` e
 
 We shouldn't need a different mechanism to work with remote content.
 
-Here, OOHTML introduces an `src` attribute that lets us have self-loading `<template>` elements:
+Here, OOHTML extends the `<template>` with an `src` attribute that lets us have self-loading `<template>` elements:
 
 ```html
 <template def="foo" src="/foo.html"></template>
@@ -633,7 +687,7 @@ setTimeout(() => {
 }, 1000);
 ```
 
-<details><summary>Extended Imports concepts</summary>
+<!--<details><summary>Extended Imports concepts</summary>-->
 
 ### Lazy-Loading Modules
 
@@ -865,19 +919,19 @@ const contextElement = document.querySelector('div');
 const result = contextElement.import('foo#fragment2'); // the local module: foo#fragment2, and if not found, the inherited module: /bar/nested#fragment2
 ```
 
-</details>
+<!--</details>-->
 
 ## Data Binding
 
-Data binding is a declarative approach to binding the UI to application data, wherein the relevant parts of the UI *automatically* update as application state changes.
+Data binding is the idea of declaratively binding the UI to application data, wherein the relevant parts of the UI *automatically* update as application state changes.
 
 OOHTML makes this possible in just simple conventions - via a new comment-based data-binding syntax `<?{ }?>` and a complementary new `expr` attribute!
 
-And for when we need to write extended reactive logic on the UI, a perfect answer: Quantum Scripts!
+And for when we need to write extensive reactive logic on the UI, a perfect answer: Quantum Scripts!
 
 ### Discrete Data-Binding
 
-Here, we get a comment-based data-binding tag `<?{ }?>` (or `<!--?{ }?-->`), **which goes as a regular HTML comment** but also an insertion point for application data:
+Here, we get a comment-based data-binding syntax `<?{ }?>` (or `<!--?{ }?-->`), **which works as a regular HTML comment** but also as an insertion point for application data:
 
 ```js
 <html>
@@ -1147,10 +1201,11 @@ Now, in each case above, reactivity terminates on script's removal from the DOM
 ```js
 const script = document.querySelector('script[quantum]');
 // const script = document.querySelector('main').scripts[0];
-script.abort();
+script.state.dispose();
+// which also happens on doing script.remove()
 ```
 
-But while that is automatic, DOM event handlers bound via `addEventListener()` would still need to be terminated in their own way.
+But note that while said termination is automatic on script's removal, DOM event handlers bound via `addEventListener()` would still need to be terminated in their own way.
 
 </details>
 
@@ -1206,7 +1261,7 @@ node.bindings.style = 'tall-dark';
 node.bindings.normalize = true;
 ```
 
-**-->** *with a complementary `bind()` method that lets us make mutations in batch*:
+**-->** *with a complementary `bind()` method that lets us make multiple mutations in one batch*:
 
 ```js
 // ------------
@@ -1259,7 +1314,7 @@ const node = document.querySelector('my-element');
 node.bindings.style = 'tall-dark';
 ```
 
-<details><summary>Details</summary>
+<details><summary>Implementation details</summary>
 
 In the current OOHTML implementation, the `document.bindings` and `Element.prototype.bindings` APIs are implemented as proxies over their actual bindings interface to enable some interface-level reactivity. This lets us have reactivity over literal property assignments and deletions on these interfaces:
 
@@ -1279,9 +1334,9 @@ Observer.deleteProperty(document.bindings.app, 'title');
 
 ### The Context API
 
-Component trees on the typical UI often call for more than the normal top-down flow of data that the Bindings API facilitates. A child may require the ability to look up the component tree to directly access specific data, or in other words, get data from "context". This is where a Context API comes in.
+Component trees on the typical UI often call for more than the normal "top-down" flow of data that the Bindings API facilitates. We still often require the ability to "look up" the component tree to directly access specific data, or in other words, get data from "context". This is where a Context API comes in.
 
-Interestingly, the Context API is the underlying resolution mechanism behind HTML Imports and Data Binding in OOHTML!
+Interestingly, the Context API is the underlying "resolution" infrastructure for the Namespace API and the Data Binding and HTML Imports features in OOHTML!
 
 Here, we simply leverage the DOM's existing event system to fire a "request" event and let an arbitrary "provider" in context fulfill the request. This becomes very simple with the Context API which is exposed on the document object and on element instances as a readonly `contexts` property.
 
@@ -1610,8 +1665,8 @@ The following is a Listbox component lifted directly from the [ARIA Authoring Pr
     <div id="ss_elem_list"
          tabindex="0"
          role="listbox"
-         aria-labelledby="ss_elem">
-      <ul role="group" aria-labelledby="cat" namespace>
+         aria-labelledby="~ss_elem">
+      <ul role="group" namespace aria-labelledby="~cat">
         <li role="presentation" id="cat">
           Land
         </li>
@@ -1631,7 +1686,7 @@ The following is a Listbox component lifted directly from the [ARIA Authoring Pr
           Raccoon
         </li>
       </ul>
-      <ul role="group" aria-labelledby="cat" namespace>
+      <ul role="group" namespace aria-labelledby="~cat">
         <li role="presentation" id="cat">
           Water
         </li>
@@ -1645,7 +1700,7 @@ The following is a Listbox component lifted directly from the [ARIA Authoring Pr
           Eel
         </li>
       </ul>
-      <ul role="group" aria-labelledby="cat" namespace>
+      <ul role="group" namespace aria-labelledby="~cat">
         <li role="presentation" id="cat">
           Air
         </li>