@webqit/oohtml 3.1.0 → 3.1.3

package/README.md

@@ -7,13 +7,13 @@
 
 **[On the Agenda](#on-the-agenda) • [Modular HTML](#modular-html) • [HTML Imports](#html-imports) • [Data Binding](#data-binding) • [Data Plumbing](#data-plumbing) • [Polyfill](#polyfill) • [Examples](#examples) • [License](#license)**
 
-Object-Oriented HTML (OOHTML) is a set of features that extend standard HTML and the DOM to enable authoring modular, reusable and reactive markup - with a "buildless", web-native workflow as design goal! This project presents what "modern HTML" could look like at its best!
+Object-Oriented HTML (OOHTML) is a set of features that extend standard HTML and the DOM to enable authoring modular, reusable and reactive markup - with a "buildless", web-native workflow as design goal! This project presents what "modern HTML" could mean today!
 
 Building Single Page Applications? OOHTML is a special love letter!
 
 <details><summary>Versions</summary>
 
-*This is documentation for `OOHTML@2.x`. (Looking for [`OOHTML@1.x`](https://github.com/webqit/oohtml/tree/v1.10.4)?)*
+*This is documentation for `OOHTML@3`. (Looking for [`OOHTML@1`](https://github.com/webqit/oohtml/tree/v1.10.4)?)*
 
 </details>
 
@@ -21,7 +21,7 @@ Building Single Page Applications? OOHTML is a special love letter!
 
 <details><summary>Show</summary>
 
-Vanilla HTML is unsurprisingly becoming a compelling option for an increasing number of developers! But the current authoring experience still leaves much to be desired in how the language lacks modularity, reusability, and other fundamental capabilities like data binding! Authors still have to rely on tools - or, to say the least, have to do half of the work in HTML and half in JS - to get even basic things working!
+Vanilla HTML is unsurprisingly becoming the most compelling option for an increasing number of developers! But the current authoring experience still leaves much to be desired in how the language lacks modularity, reusability, and other fundamental capabilities like data binding! Authors still have to rely on tools - or, to say the least, have to do half of the work in HTML and half in JS - to get even basic things working!
 
 This project pursues an object-oriented approach to HTML and implicitly revisits much of what inhibits the idea of a *component* architecture for HTML!
 
@@ -42,13 +42,13 @@ This project pursues an object-oriented approach to HTML and implicitly revisits
 
 Modular HTML is a markup pattern that lets us write arbitrary markup as self-contained objects - with each *encapsulating* their own structure, styling and logic!
 
-OOHTML makes this possible in just simple conventions - via two new attributes: `namespace` and `scoped`!
+OOHTML makes this possible by introducing "namespacing" and style and script scoping!
 
 ### Namespacing
 
 Naming things is hard! That's especially so where you have one global namespace and a miriad of potentially conflicting names to coordinate!
 
-Here, we get the `namespace` attribute for designating an element as own naming context for identifiers instead of the global namespace:
+Here, we get the `namespace` attribute for designating an element as own naming context for identifiers instead of the global document namespace:
 
 ```html
 <div id="user" namespace>
@@ -124,11 +124,11 @@ console.log(window.foo); // div
 
 </details>
 
-### Scoping
+### Style and Script Scoping
 
-We often need a way to keep things like styles and scripts [scoped to a component](https://vuejs.org/guide/scaling-up/sfc.html).
+We often need a way to keep things like component-specific stylesheets and scripts [scoped to a component](https://vuejs.org/guide/scaling-up/sfc.html).
 
-Here, we get the `scoped` attribute for *scoping* said element-specific stylesheets and scripts:
+Here, we get the `scoped` attribute for doing just that:
 
 ```html
 <div>
@@ -144,7 +144,7 @@ Here, we get the `scoped` attribute for *scoping* said element-specific styleshe
 </div>
 ```
 
-**-->** *with a complementary API that exposes said assets to JavaScript applications*:
+**-->** *with a complementary API that exposes said assets for low-level access*:
 
 ```js
 let { styleSheets, scripts } = user; // APIs that are analogous to the document.styleSheets, document.scripts properties
@@ -152,9 +152,9 @@ let { styleSheets, scripts } = user; // APIs that are analogous to the document.
 
 <details><summary>Learn more</summary>
 
-The `scoped` has two effects on the `<script>` element:
+Here, the `scoped` has two effects on the `<script>` element:
 
-+ The `this` keyword is a reference to the script's host element
++ The `this` keyword is implicitly bound to the script's host element
 + The `<script>` element is executed again on each re-insertion to the DOM
 
 </details>
@@ -169,7 +169,7 @@ OOHTML makes this possible in just simple conventions - via a new `def` attribut
 
 A module here is any piece of markup that can be reused.
 
-Here, we get the `def` attribute for defining those - either as whole *module* or as *fragment*:
+Here, we get the `def` attribute for defining those - both at the `<template>` element level and at its contents (*fragment*) level:
 
 ```html
 <head>
@@ -203,7 +203,7 @@ Here, we get the `def` attribute for defining those - either as whole *module* o
 
 We shouldn't need a different mechanism to work with remote content.
 
-Here, we get the `<template src>` element for that:
+Here, we get remote-loading modules with same `<template>` element using the `src` attribute:
 
 ```html
 <template def="foo" src="/foo.html"></template>
@@ -222,7 +222,7 @@ Here, we get the `<template src>` element for that:
 <div def="fragment2"></div>
 ```
 
-**-->** *which borrows from how elements like images work; terminating with either a `load` or an `error` event*:
+**-->** *which borrow from how `src` works in elements like `<img>`; terminating with either a `load` or an `error` event*:
 
 ```js
 foo.addEventListener('load', loadCallback);
@@ -231,9 +231,9 @@ foo.addEventListener('error', errorCallback);
 
 ### Declarative Module Imports
 
-The essence of a module is for reuse.
+HTML snippets should be reusable in HTML itself!
 
-Here, we get an `<import>` element that lets us do that declaratively:
+Here, we get an `<import>` element that lets us do just that:
 
 ```html
 <body>
@@ -251,13 +251,14 @@ Here, we get an `<import>` element that lets us do that declaratively:
 
 <details><summary>All in realtime</summary>
 
-Import *refs* are live references and are sensitive to:
+Here, import *refs* are live bindings that are highly sensitive to:
 
-+ changes in the *ref* itself (in being defined/undefined/redefined)
-+ changes in the referenced *defs* themselves (in being added/removed/loaded)
++ changes in the *ref* itself (on being defined/undefined/redefined)
++ changes in the referenced *defs* themselves (on being added/removed/loaded)
 
 And an `<import>` element that has been resolved will self-restore in the event that:
 
++ the above changes resolve to no imports.
 + the previously slotted contents have *all* been programmatically removed and slot is empty.
 
 </details>
@@ -277,13 +278,13 @@ The above resolved imports would thus give us something like:
 </body>
 ```
 
-But they also will need to remember the exact imported nodes that they manage so as to be able to re-establish that relationship on getting to the client. This information is automatically encoded as part of the serialised element itself, in something like:
+But they also will need to remember the exact imported nodes that they manage so as to be able to re-establish relevant relationships on getting to the client. This information is automatically encoded as part of the serialised element itself, in something like:
 
 ```html
 <!--&lt;import ref="/foo/nested#fragment2" nodecount="1"&gt;&lt;/import&gt;-->
 ```
 
-Now, on getting to the client and "hydrating" the `<import>` element, that extra bit of information gets decoded, and original relationships are formed again. But, the `<import>` element itself stays invisible in the DOM while still continuing to kick as above!
+Now, on getting to the client and getting "hydrated" back into an `<import>` element, that extra bit of information is decoded, and original relationships are formed again. But, the `<import>` element itself stays invisible in the DOM while still continuing to kick as above!
 
 > Note: We know we're on the server when `window.webqit.env === 'server'`. This flag is automatically set by OOHTML's current SSR engine: [OOHTML-SSR](https://github.com/webqit/oohtml-ssr)
 
@@ -305,7 +306,7 @@ const moduleObject2 = document.import('/foo/nested#fragment2');
 console.log(moduleObject2.value); // divElement
 ```
 
-**-->** *with the `moduleObject.value` property being a live property for when results are asynchronous; e.g. asynchronously loaded modules*:
+**-->** *with the `moduleObject.value` property being a live property for when results are delivered asynchronous; e.g. in the case of remote modules*:
 
 ```js
 Observer.observe(moduleObject2, 'value', e => {
@@ -313,7 +314,7 @@ Observer.observe(moduleObject2, 'value', e => {
 });
 ```
 
-**-->** *with an equivalent `callback` option on the `import()` method itself*:
+**-->** *with an equivalent `callback` option on the `import()` API itself*:
 
 ```js
 document.import('/foo#fragment1', divElement => {
@@ -321,7 +322,7 @@ document.import('/foo#fragment1', divElement => {
 });
 ```
 
-**-->** *with an optional `live` parameter for staying subscribed to updated results*:
+**-->** *with an optional `live` parameter for staying subscribed to live results*:
 
 ```js
 const moduleObject2 = document.import('/foo/nested#fragment2', true/*live*/);
@@ -337,7 +338,7 @@ document.import('/foo#fragment1', true/*live*/, divElement => {
 });
 ```
 
-*...both of which gets notified on doing the below*:
+*...both of which get notified on doing something like the below*:
 
 ```js
 document.querySelector('template[def="foo"]').content.firstElementChild.remove();
@@ -362,9 +363,9 @@ setTimeout(() => {
 
 ### Lazy-Loading Modules
 
-We can defer module loading until we really need them.
+We should be able to defer module loading until we really need them.
 
-Here, we get the `loading="lazy"` directive for that; and loading is only then triggered on the first attempt to import them or their contents:
+Here, we get the `loading="lazy"` directive for that; and loading is only then triggered on the first attempt to import those or their contents:
 
 ```html
 <!-- Loading doesn't happen until the first time this is being accessed -->
@@ -382,9 +383,9 @@ const moduleObject2 = document.import('/foo#fragment1'); // Triggers module load
 
 ### Module Inheritance
 
-We'll often have repeating markup structures.
+We'll often have repeating markup structures across component layouts.
 
-Here, we get module nesting with inheritance to simplify that:
+Here, we get module nesting with inheritance to facilitate more reusability:
 
 ```html
 <template def="foo">
@@ -432,14 +433,14 @@ Here, we get module nesting with inheritance to simplify that:
 
 We should be able to have *relative* import refs that resolve against local contexts in the document tree.
 
-Here, we call those arbitrary contexts "Imports Contexts", and these could be:
+Here, we get just that - as "Imports Contexts", which could be:
 
 + Simple Base Path Contexts ([below](#base-path-contexts))
 + Scoped Module Contexts ([below](#scoped-module-contexts))
 + Named Contexts ([below](#named-contexts))
 + Extended Scoped Module Contexts ([below](#extended-scoped-module-contexts))
 
-Alongside which we have a complementary `Element.prototype.import()` API for thinking in contexts.
+And to facilitate thinking in contexts, we also get an `Element.prototype.import()` API for context-based module imports.
 
 #### "Base Path" Contexts
 
@@ -499,7 +500,7 @@ const response = contextElement.import('#fragment1'); // Relative path (beginnin
 
 Some modules will only be relevant within a specific context in the page, and those wouldn't need to have a business with the global scope.
 
-Here, we get the `scoped` attribute for scoping those to their respective contexts, to give us an *object-scoped* module system (like what Scoped Registries are to Custom Elements):
+Here, we get the `scoped` attribute for scoping those to their respective contexts, to give us an *object-scoped* module system (like what Scoped Registries seek to be to Custom Elements):
 
 ```html
 <section> <!-- Host object -->
@@ -532,7 +533,7 @@ const globalModule = contextElement.import('/foo#fragment1'); // Absolute path,
 
 #### Named Contexts
 
-Imports Contexts may be named:
+Imports Contexts may be named for direct referencing:
 
 ```html
 <body contextname="context1" importscontext="/foo/nested">
@@ -598,7 +599,7 @@ Data binding is about declaratively binding the UI to application data, wherein
 
 OOHTML makes this possible in just simple conventions - via a new comment-based data-binding syntax `<?{ }?>` and a complementary new `expr` attribute!
 
-And there's one more: Quantum Scripts which brings the most advanced form of reactivity to HTML!
+And there's one more: Quantum Scripts for when we need to write extended reactive logic on the UI!
 
 ### Discrete Data-Binding
 
@@ -761,7 +762,7 @@ Bindings are resolved in realtime! And in fact, for lists, in-place mutations -
 
 <details><summary>With SSR support</summary>
 
-For lists, generated item elements are automatically assigned a corresponding key with a `data-key` attribute! This helps in remapping generated item nodes to their respective entry in *iteratee* during a rerendering or during hydration.
+For lists, generated item elements are automatically assigned a corresponding key with a `data-key` attribute! This helps in remapping generated item nodes to their corresponding entry in *iteratee* during a rerendering or during hydration.
 
 </details>
 
@@ -769,7 +770,7 @@ For lists, generated item elements are automatically assigned a corresponding ke
 
 We often still need to write more serious reactive logic on the UI than a declarative data-binding language can provide for. But we shouldn't need to reach for special tooling or some "serious" programming paradigm on top of JavaScript.
 
-Here, from the same `<script>` element we already write, we get a direct upgrade path to reactive programming in just the addition of an attribute: `quantum`:
+Here, from the same `<script>` element we already write, we get a direct upgrade path to reactive programming in just the addition of an attribute: `quantum` - for [Quantum Scripts](https://github.com/webqit/quantum-js):
 
 ```html
 <script quantum>
@@ -785,7 +786,7 @@ Here, from the same `<script>` element we already write, we get a direct upgrade
 </script>
 ```
 
-**-->** *which gives us fine-grained reactivity on top of literal JavaScript syntax; and which adds up really well with the `scoped` attribute*:
+**-->** *which gives us fine-grained reactivity on top of literal JavaScript syntax; and which adds up really well with the `scoped` attribute for Single Page Applications*:
 
 ```html
 <main>
@@ -880,7 +881,7 @@ But while that is automatic, DOM event handlers bound via `addEventListener()` w
 
 ## Data Plumbing
 
-Components often need to manage, or be managed by, dynamic data. That could get pretty problematic and messy if all of that should go on DOM nodes as direct properties:
+Components often need to manage, and be managed by, dynamic data. That could get pretty problematic and messy if all of that should go on DOM nodes as direct properties:
 
 <details><summary>Example</summary>
 
@@ -960,7 +961,7 @@ connectedCallback() {
 }
 ```
 
-**-->** *and with the Observer API in the picture for reactivity*:
+**-->** *and with the Observer API in the picture all the way for reactivity*:
 
 ```js
 Observer.observe(document.bindings, mutations => {
@@ -992,7 +993,7 @@ node.bindings.style = 'tall-dark'; // Reactive assignment
 delete node.bindings.style; // Reactive deletion
 ```
 
-For mutations at a deeper level to be reactive, the corresponding Observer API method must be used:
+For mutations at a deeper level to be reactive, the corresponding Observer API method would need to be used:
 
 ```js
 Observer.set(document.bindings.app, 'title', 'Demo App!!!');
@@ -1003,9 +1004,9 @@ Observer.deleteProperty(document.bindings.app, 'title');
 
 ### The Context API
 
-A complex hierarchy of objects will 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. 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.
 
-Interestingly, the Context API is the resolution mechanism behind HTML Imports and Data Binding in OOHTML!
+Interestingly, the Context API is the underlying resolution mechanism behind HTML Imports and Data Binding 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.
 
@@ -1019,11 +1020,11 @@ const node = document.querySelector('my-element');
 // ------------
 // Prepare and fire request event
 const requestParams = { kind: 'html-imports', detail: '/foo#fragment1' };
-const contextResponse = node.contexts.request(requestParams);
+const response = node.contexts.request(requestParams);
 
 // ------------
 // Handle response
-console.log(contextResponse.value); // It works!
+console.log(response.value); // It works!
 ```
 
 **-->** *and the `contexts.attach()` and  `contexts.detach()` methods for attaching/detaching providers at arbitrary levels in the DOM tree*:
@@ -1054,10 +1055,10 @@ document.contexts.detach(fakeImportsContext);
 In the current OOHTML implementation, the Context API interfaces are exposed via the global `webqit` object:
 
 ```js
-const { DOMContext, DOMContextRequestEvent, DOMContextResponse } = window.webqit;
+const { DOMContext, DOMContextRequestEvent, DOMContextResponse, DuplicateContextError } = window.webqit;
 ```
 
-In addition...
+Now, by design...
 
 + a provider will automatically adopt the `contextname`, if any, of its host element:
 
@@ -1078,7 +1079,7 @@ In addition...
 
     ```js
     const requestParams = { kind: FakeImportsContext.kind, targetContext: 'context1', detail: '/foo#fragment1' };
-    const contextResponse = node.contexts.request(requestParams);
+    const response = node.contexts.request(requestParams);
     ```
 
 + and providers of same kind could be differentiated by an extra "detail" - an arbitrary value passed to the constructor:
@@ -1096,7 +1097,7 @@ In addition...
       static kind = 'html-imports';
       matchEvent(event) {
         // The default request matching algorithm + "detail" matching
-        return super.matchEvent() && event.detail === this.detail;
+        return super.matchEvent(event) && event.detail === this.detail;
       }
       handle(event) {
         console.log(event.detail);
@@ -1116,9 +1117,9 @@ In addition...
 
     ```js
     // Handle response without a callback
-    const contextResponse = node.contexts.request(requestParams);
-    console.log(contextResponse.value); // It works!
-    Observer.observe(contextResponse, 'value', e => {
+    const response = node.contexts.request(requestParams);
+    console.log(response.value); // It works!
+    Observer.observe(response, 'value', e => {
       console.log(e.value); // It works live!
     });
     ```
@@ -1149,7 +1150,7 @@ In addition...
     }
     ```
 
-    ...and optionally implements a `subscribed` and `unsubscribed` lifecycle hook for when a "live" event enters and leaves the instance:
+    ...or optionally implement a `subscribed` and `unsubscribed` lifecycle hook for when a "live" event enters and leaves the instance:
 
     ```js
     // Define a CustomContext class
@@ -1175,7 +1176,7 @@ In addition...
 + live requests are terminated via the returned `DOMContextResponse` object...
 
     ```js
-    contextResponse.abort();
+    response.abort();
     ```
 
     ...or via an initially specified custom `AbortSignal`:
@@ -1187,10 +1188,10 @@ In addition...
     ```
 
     ```js
-    abortController.abort(); // Which also calls contextResponse.abort();
+    abortController.abort(); // Which also calls response.abort();
     ```
 
-+ now, when a node in a provider's subtree is suddenly attached an identical provider, any live requests the super provider may be serving are automatically "claimed" by the sub provider:
++ now, where a node in a provider's subtree is suddenly attached an identical provider, any live requests the super provider may be serving are automatically "claimed" by the sub provider:
 
     ```js
     document: // 'fake-provider' here
@@ -1199,7 +1200,7 @@ In addition...
       └── body:  // 'fake-provider' here. Our request above is now served from here.
     ```
 
-    And when the sub provider is suddenly detached from said node, any live requests it may have served are automatically hoisted back to super provider.
+    And where the sub provider is suddenly detached from said node, any live requests it may have served are automatically hoisted back to super provider.
 
     ```js
     document: // 'fake-provider' here. Our request above is now served from here.
@@ -1208,11 +1209,11 @@ In addition...
       └── body:
     ```
 
-    While, in all, saving the requesting code that "admin" work!
+    While, in all, the requesting code is saved that "admin" work!
 
 </details>
 
-**-->** *all of which gives us the imperative equivalent of context-based declarative features like HTMLImports and Data Binding*:
+**-->** *all of which gives us a standardized API underneath context-based features in HTML - like HTMLImports and Data Binding*:
 
 ```html
 <div contextname="vendor1">
@@ -1234,35 +1235,35 @@ In addition...
 ```js
 // ------------
 // Equivalent import() approach
-const contextResponse = myElement.import('@vendor1/foo#fragment1');
+const response = myElement.import('@vendor1/foo#fragment1');
 
 // ------------
 // Equivalent Context API approach
 const requestParams = { kind: 'html-imports', targetContext: 'vendor1', detail: 'foo#fragment1' };
-const contextResponse = myElement.contexts.request(requestParams);
+const response = myElement.contexts.request(requestParams);
 
 // ------------
 // Handle response
-console.log(contextResponse.value);
+console.log(response.value);
 ```
 
 ```js
 // ------------
 // Context API request for bindings
 const requestParams = { kind: 'bindings', targetContext: 'vendor2', detail: 'app' };
-const contextResponse = myElement.contexts.request(requestParams);
+const response = myElement.contexts.request(requestParams);
 
 // ------------
 // Handle response
-console.log(contextResponse.value.title);
+console.log(response.value.title);
 ```
 
 ## Polyfill
 
-OOHTML is being developed as something to be used today—via a polyfill. This is an intentional effort that's helping to ensure that the project evolves through a practice-driven process.
+OOHTML is being developed as something to be used today—via a polyfill. This is an intentional effort that has continued to ensure that the proposal evolves through a practice-driven process.
 
 <details><summary>Load from a CDN<br>
-└───────── <a href="https://bundlephobia.com/result?p=@webqit/oohtml"><img align="right" src="https://img.shields.io/badge/21.7%20kB-black"></a></summary>
+└───────── <a href="https://bundlephobia.com/result?p=@webqit/oohtml"><img align="right" src="https://img.shields.io/badge/21.8%20kB-black"></a></summary>
 
 ```html
 <script src="https://unpkg.com/@webqit/oohtml/dist/main.lite.js"></script>
@@ -1354,7 +1355,7 @@ If you'll be going ahead to build a real app with OOHTML, you may want to consid
 
     ...still gives the `window` object in the console.
 
-+ **Scoped CSS**. This feature is only in "concept" implementation and doesn't work right now as is. The current implementation simply wraps `<style scoped>` blocks in an `@scope {}` block - which itself isn't supported in any browser. To try this "concept" implementation, set the `style.strategy` config to `@scope`:
++ **Scoped CSS**. This feature is only in "concept" implementation and doesn't work right now as is. The current implementation simply wraps `<style scoped>` blocks in an `@scope {}` block - which itself isn't supported in any browser *yet*. To try this "concept" implementation, set the `style.strategy` config to `@scope`:
 
     ```html
     <head>
@@ -1381,7 +1382,7 @@ If you'll be going ahead to build a real app with OOHTML, you may want to consid
     </style>
     ```
 
-    A working implementation may be coming soon, but in the meantime, you could try one of the polyfills for `<style scoped>` out there; e.g. [samthor/scoped](https://github.com/samthor/scoped):
+    Browser support for `@scope {}` style blocks may be coming soon, but in the meantime, you could try one of the polyfills for `<style scoped>` out there; e.g. [samthor/scoped](https://github.com/samthor/scoped):
 
     ```html
     <script src="https://unpkg.com/style-scoped/scoped.min.js"></script>

package/package.json

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