npm - @webqit/oohtml - Versions diffs - 3.2.0 → 4.0.1 - Mend

@webqit/oohtml 3.2.0 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/README.md +189 -78
package/dist/bindings-api.js +1 -1
package/dist/bindings-api.js.map +3 -3
package/dist/context-api.js +1 -1
package/dist/context-api.js.map +3 -3
package/dist/data-binding.js +15 -15
package/dist/data-binding.js.map +3 -3
package/dist/html-imports.js +1 -1
package/dist/html-imports.js.map +3 -3
package/dist/main.js +24 -24
package/dist/main.js.map +3 -3
package/dist/main.lite.js +25 -31
package/dist/main.lite.js.map +3 -3
package/dist/namespaced-html.js +1 -1
package/dist/namespaced-html.js.map +3 -3
package/dist/scoped-css.js +4 -4
package/dist/scoped-css.js.map +3 -3
package/dist/scoped-js.js +1 -1
package/dist/scoped-js.js.map +3 -3
package/package.json +5 -5
package/src/data-binding/index.js +4 -4
package/src/index.js +3 -21
package/src/{api.global.lite.js → index.lite.js} +1 -1
package/src/init.js +28 -0
package/src/namespaced-html/index.js +204 -141
package/src/scoped-css/index.js +43 -32
package/src/scoped-js/index.js +20 -15
package/src/util.js +11 -0
package/src/api.global.js +0 -11

package/README.md CHANGED Viewed

@@ -13,13 +13,19 @@ Building Single Page Applications? OOHTML is a special love letter! Writing Web
 <details><summary>Versions</summary>
-*This is documentation for `OOHTML@3`. (Looking for [`OOHTML@1`](https://github.com/webqit/oohtml/tree/v1.10.4)?)*
+*This is documentation for `OOHTML@4`. (Looking for [`OOHTML@1`](https://github.com/webqit/oohtml/tree/v1.10.4)?)*
 </details>
+## Status
++ Working implementation via a polyfill
++ Actively developed
++ Open to contributions
 ## Polyfill
-OOHTML is being developed as something to be used today. This implementation adheres closely to the spec and evolves the proposal through a practice-driven process.
+OOHTML is being developed as something to be used today. This implementation adheres closely to the spec and helps evolve the proposal 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.8%20kB-black"></a></summary>
@@ -30,13 +36,19 @@ OOHTML is being developed as something to be used today. This implementation adh
 └ This is to be placed early on in the document and should be a classic script without any `defer` or `async` directives!
-> For `@webqit/oohtml@3.1` and below, you would need an external polyfill - like the [samthor/scoped](https://github.com/samthor/scoped) polyfill - for the Scoped Styles feature:
->
-> ```html
-> <head>
->   <script src="https://unpkg.com/style-scoped/scoped.min.js"></script>
-> </head>
-> ```
+└ For `@webqit/oohtml@3.1` and below, you would need an external polyfill - like the [samthor/scoped](https://github.com/samthor/scoped) polyfill - for the Scoped Styles feature:
+```html
+<head>
+  <script src="https://unpkg.com/style-scoped/scoped.min.js"></script>
+</head>
+```
+└ Being an integral part of OOHTML, the Observer and Quantum JS APIs are also accessible on loading the OOHTML polyfill:
+```js
+const { QuantumFunction, QuantumAsyncFunction, QuantumScript, QuantumModule, QuantumAsyncScript, State, Observer } = window.webqit;
+```
 </details>
@@ -50,12 +62,18 @@ npm i @webqit/oohtml @webqit/quantum-js
 ```js
 // Import
 import * as Quantum from '@webqit/quantum-js/lite'; // Or from '@webqit/quantum-js'; See implementation notes below
-import init from '@webqit/oohtml';
+import init from '@webqit/oohtml/src/init.js';
 // Initialize the lib
 init.call(window, Quantum[, options = {}]);
 ```
+└ Being an integral part of OOHTML, the Observer API, in addition to the Quantum JS APIs, is also available from the OOHTML installation:
+```js
+import * as Observer from '@webqit/observer';
+```
 └ To use the polyfill on server-side DOM instances as made possible by libraries like [jsdom](https://github.com/jsdom/jsdom), simply install and initialize the library with the DOM instance as above.
 └ But all things "SSR" for OOHTML are best left to the [`@webqit/oohtml-ssr`](https://github.com/webqit/oohtml-ssr) package!
@@ -92,7 +110,7 @@ If you'll be going ahead to build a real app with OOHTML, you may want to consid
     ```html
     <head>
-      <meta name="scoped-js" content="script.mimeType=some-mime">
+      <meta name="scoped-js" content="script.mimeTypes=module|text/javascript|application/javascript|some-mime">
       <script async src="https://unpkg.com/@webqit/oohtml/dist/main.lite.js"></script>
     </head>
     <body>
@@ -114,12 +132,12 @@ 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.
-+ **Syntax**. The syntax for attribute names and API names across features - e.g. the `def` and `ref` attributes, the `expr` attribute - isn't finalized, and may change on subsequent iterations, albeit with same principle of operation. But the polyfill is designed to be configurable via meta tags, and to honour any such "overrides". Here's an example:
++ **Syntax**. The syntax for attribute names and API names across features - e.g. the `def` and `ref` attributes, the `render` attribute - isn't finalized, and may change on subsequent iterations, albeit with same principle of operation. But the polyfill is designed to be configurable via meta tags, and to honour any such "overrides". Here's an example:
     ```html
     <head>
       <!-- Configurations come before the polyfil -->
-      <meta name="data-binding" content="attr.expr=expr;">
+      <meta name="data-binding" content="attr.render=render;">
       <meta name="namespaced-html" content="attr.id=id;">
       <meta name="html-imports" content="attr.def=def; attr.ref=ref;">
       <script src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
@@ -143,16 +161,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.render` | `render` | The "render" 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 +178,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 +200,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 +209,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>
@@ -202,7 +223,7 @@ If you'll be going ahead to build a real app with OOHTML, you may want to consid
 Amidst a multitude of approaches, vanilla HTML remains an attractive option for the UI author! But the current authoring experience still leaves much to be desired in how the language lacks modularity, reusability, and certain modern paradigms like data binding! Authors still have to rely on tools - and, for the most part, have to do half of the work in HTML and half in JS - to express even basic concepts!
-"As an author, I want to be able to do 'x' *declaratively* instead of *imperatively* in JavaScript or by means of a special Custom Element!" "As a Web Component author, I want to be able to leverage *conventions* that keep my component logic *concise*!" All such "user stories" represent important developer intuitions that has yet to be met in HTML; much of which belong under a broad subject: an object-oriented markup language! This subject is what we explore with OOHTML!
+"As an author, I want to be able to do 'x' *declaratively* in HTML instead of *imperatively* in JavaScript or by means of a special Custom Element!" "As a Web Component author, I want to be able to leverage *conventions* that keep my component logic *concise*!" All such "user stories" represent important developer intuitions that has yet to be met in HTML; much of which belong under a broad subject: an object-oriented markup language! This subject is what we explore with OOHTML!
 OOHTML comes, not as a specific technology, but as a conceptual "framework" of features that solves for HTML as an object-oriented language - whether that means re-aligning existing features or introducing new ones! While features may be discussed or explored individually, the one agenda "Object-Oriented HTML" helps us stay aligned with the original problem! Each of these features has been introduced below with a small explainer.
@@ -219,7 +240,7 @@ OOHTML is effectively different from Web Components (and from the related Declar
 ## Modular HTML
-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!
+The modern UI is best approached with a modular architecture (think UI component frameworks) wherein we are able to author in bits and pieces while having each piece *encapsulate* their structure, styling and logic!
 OOHTML makes this possible by introducing "namespacing" and style and script scoping!
@@ -227,7 +248,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>
@@ -240,7 +277,7 @@ Here, we get a modular naming convention using the `namespace` attribute. This a
     <label for="~city">City</label>
     <input id="city">
-   <fieldset>
+  <fieldset>
   <fieldset namespace>
     <legend>Delivery Address</legend>
@@ -250,14 +287,21 @@ Here, we get a modular naming convention using the `namespace` attribute. This a
     <label for="~city">City</label>
     <input id="city">
-   <fieldset>
+  <fieldset>
 </form>
 ```
-This lets us have repeating structures with identical but non-conflicting identifiers and `IDREFS`.
+This lets us have repeating structures with identical but non-conflicting identifiers. These identifiers are then referenced locally using "local `IDREFS`" - denoted by the `~` prefix.
+Local `IDREFS` are resolved within the namespace where they're used (not globally; not deeply):
+```js
+// Matches "#city" within the fieldset's namespace; not super namespace, not sub namespace
+const city = fieldset.querySelector('#~city');
+```
-And this also translates well to an object model:
+And when used from the document context, these are resolved against top-level IDs; i.e. IDs in the document namespace itself (not deeply):
 ```html
 <div id="user" namespace>
@@ -268,6 +312,29 @@ And this also translates well to an object model:
 </div>
 ```
+```js
+// Namespace aware ID selectors
+console.log(document.querySelector('#user')); // div#user
+console.log(document.querySelector('#~user')); // div#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 navigation targets, with additional support for path expressions given a hierarchy of namespaces:
+```html
+<a href="#~user/email">Jump to Email</a>
+```
+And JavaScript applications are able to consume namespace structures as an object model:
 ```html
 user
  ├── url
@@ -275,8 +342,6 @@ user
  └── email
 ```
-with a complementary API that exposes said structure to JavaScript applications:
 ```js
 // The document.namespace API
 let { user } = document.namespace;
@@ -313,27 +378,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:
@@ -351,7 +444,22 @@ Here, we get a new `scoped` attribute that lets us do just that:
 </div>
 ```
-**-->** *with a complementary low-level API that exposes said assets to tools*:
+And the special namespace-aware ID selector is supported from within scoped style sheets:
+```html
+<div namespace>
+  <a id="url" href="https://example.org">
+    <span id="name">Joe Bloggs</span>
+  </a>
+  <a id="email" href="mailto:joebloggs@example.com" >joebloggs@example.com</a>
+  <style scoped>
+    #\~name { color: red }
+  </style>
+</div>
+```
+And everything comes with a complementary low-level API that exposes said assets to tools:
 ```js
 let { styleSheets, scripts } = user; // APIs that are analogous to the document.styleSheets, document.scripts properties
@@ -362,15 +470,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>
@@ -387,7 +495,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>
@@ -443,7 +551,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>
@@ -597,7 +705,7 @@ setTimeout(() => {
 }, 1000);
 ```
-<details><summary>Extended Imports concepts</summary>
+<!--<details><summary>Extended Imports concepts</summary>-->
 ### Lazy-Loading Modules
@@ -829,19 +937,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!
+OOHTML makes this possible in just simple conventions - via a new comment-based data-binding syntax `<?{ }?>` and a complementary new `render` 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>
@@ -906,10 +1014,12 @@ Now, on getting to the client, that extra bit of information gets decoded, and o
 ### Inline Data-Binding
-For attribute-based data binding, OOHTML deviates from the usual (and problematic) idea of bringing markup-style bindings into attribute texts: `title="Hello { titleValue }"`, **as though attributes had the same semantics as markup**. Instead, we get a dedicated "expressions" attribute - `expr` - for a nifty, key/value data-binding language:
+For attribute-based data binding, OOHTML deviates from the usual (and problematic) idea of bringing markup-style bindings into attribute texts: `title="Hello { titleValue }"`, **as though attributes had the same semantics as markup**. Instead, we get a dedicated "render" attribute - `render` - for a nifty, key/value data-binding language:
+> Note that in OOHTML <= v3 the `render` attribute was `expr`.
 ```html
-<div expr="<directive> <param>: <arg>;"></div>
+<div render="<directive> <param>: <arg>;"></div>
 ```
 **-->** *where*:
@@ -921,36 +1031,36 @@ For attribute-based data binding, OOHTML deviates from the usual (and problemati
 **-->** *which would give us the following for a CSS property*:
 ```html
-<div expr="& color:someColor; & backgroundColor:'red'"></div>
+<div render="& color:someColor; & backgroundColor:'red'"></div>
 ```
 **-->** *without being space-sensitive*:
 ```html
-<div expr="& color:someColor; &backgroundColor: 'red'"></div>
+<div render="& color:someColor; &backgroundColor: 'red'"></div>
 ```
 **-->** *the rest of which can be seen below*:
 | Directive | Type | Usage |
 | :---- | :---- | :---- |
-| `&`  | CSS Property | `<div expr="& color:someColor; & backgroundColor:someBgColor;"></div>` |
-| `%`  | Class Name | `<div expr="% active:app.isActive; % expanded:app.isExpanded;"></div>` |
-| `~`  | Attribute Name | `<a expr="~ href:person.profileUrl+'#bio'; ~ title:'Click me';"></a>` |
-|   | Boolean Attribute | `<a expr="~ ?required:formField.required; ~ ?aria-checked: formField.checked"></a>` |
+| `&`  | CSS Property | `<div render="& color:someColor; & backgroundColor:someBgColor;"></div>` |
+| `%`  | Class Name | `<div render="% active:app.isActive; % expanded:app.isExpanded;"></div>` |
+| `~`  | Attribute Name | `<a render="~ href:person.profileUrl+'#bio'; ~ title:'Click me';"></a>` |
+|   | Boolean Attribute | `<a render="~ ?required:formField.required; ~ ?aria-checked: formField.checked"></a>` |
 | `@`  | Structural Directive: | *See below* |
-| `@text`   | Plain text content | `<span expr="@text:firstName+' '+lastName;"></span>` |
-| `@html`   | Markup content | `<span expr="@html: '<i>'+firstName+'</i>';"></span>` |
+| `@text`   | Plain text content | `<span render="@text:firstName+' '+lastName;"></span>` |
+| `@html`   | Markup content | `<span render="@html: '<i>'+firstName+'</i>';"></span>` |
 |  `@items`  | A list, of the following format | `<declaration> <of\|in> <iterable> / <importRef>`<br>*See next two tables* |
 <details><summary><code>For ... Of</code> Loops</summary>
 |  Idea | Usage |
 | :---- | :---- |
-| A `for...of` loop over an array/iterable | `<ul expr="@items: value of [1,2,3] / 'foo#fragment';"></ul>` |
-| Same as above but with a `key` declaration  | `<ul expr="@items: (value,key) of [1,2,3] / 'foo#fragment';"></ul>` |
-| Same as above but with different variable names  | `<ul expr="@items: (product,id) of store.products / 'foo#fragment';"></ul>` |
-| Same as above but with a dynamic `importRef`  | `<ul expr="@items: (product,id) of store.products / store.importRef;"></ul>` |
+| A `for...of` loop over an array/iterable | `<ul render="@items: value of [1,2,3] / 'foo#fragment';"></ul>` |
+| Same as above but with a `key` declaration  | `<ul render="@items: (value,key) of [1,2,3] / 'foo#fragment';"></ul>` |
+| Same as above but with different variable names  | `<ul render="@items: (product,id) of store.products / 'foo#fragment';"></ul>` |
+| Same as above but with a dynamic `importRef`  | `<ul render="@items: (product,id) of store.products / store.importRef;"></ul>` |
 </details>
@@ -958,8 +1068,8 @@ For attribute-based data binding, OOHTML deviates from the usual (and problemati
 | Idea | Usage |
 | :---- | :---- |
-| A `for...in` loop over an object | `<ul expr="@items: key in {a:1,b:2} / 'foo#fragment';"></ul>` |
-| Same as above but with a `value` and `index` declaration | `<ul expr="@items: (key,value,index) in {a:1, b:2} / 'foo#fragment';"></ul>` |
+| A `for...in` loop over an object | `<ul render="@items: key in {a:1,b:2} / 'foo#fragment';"></ul>` |
+| Same as above but with a `value` and `index` declaration | `<ul render="@items: (key,value,index) in {a:1, b:2} / 'foo#fragment';"></ul>` |
 </details>
@@ -1111,10 +1221,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>
@@ -1170,7 +1281,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
 // ------------
@@ -1223,7 +1334,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:
@@ -1243,9 +1354,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.
@@ -1574,8 +1685,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>
@@ -1595,7 +1706,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>
@@ -1609,7 +1720,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>
@@ -1694,11 +1805,11 @@ The following is a hypothetical list page!
   <!-- The "items" template -->
   <template def="item" scoped>
-    <li><a expr="~href: '/animals#'+name;"><?{ index+': '+name }?></a></li>
+    <li><a render="~href: '/animals#'+name;"><?{ index+': '+name }?></a></li>
   </template>
   <!-- The loop -->
-  <ul expr="@items: (name,index) of ['dog','cat','ram'] / 'item';"></ul>
+  <ul render="@items: (name,index) of ['dog','cat','ram'] / 'item';"></ul>
 </section>
 ```