npm - @webqit/oohtml - Versions diffs - 3.0.1-12 → 3.0.1-3 - Mend

@webqit/oohtml 3.0.1-12 → 3.0.1-3

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 (2) hide show

package/README.md +130 -180
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -375,7 +375,7 @@ setTimeout(() => abortController.abort(), 1000);
 We can 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 their contents:
+Here, we get the `loading="lazy"` directive for that; and loading is only then triggered on the first attempt to import its contents:
 ```html
 <!-- Loading doesn't happen until the first time this is being accessed -->
@@ -593,42 +593,12 @@ Here, we get a comment-based data-binding tag `<?{ }?>` which works like regular
     <title><?{ app.title }?></title>
   </head>
   <body>
-    Hi, I'm <?{ name ?? 'Default name' }?>!
-    and here's another way to write the same comment: <!--?{ cool }?-->
+    Hi, I'm <?{ app.name ?? 'Default name' }?>!
+    and here's another way to write the same comment: <!--?{ app.cool }?-->
   </body>
 </html>
 ```
-<details><summary>Resolution details</summary>
-Here, JavaScript references are resolved from the closest node up the document hierarchy that exposes a corresponding *binding* on its Bindings API ([discussed below](#bindings-api)). Thus, for the above markup, our underlying data structure could be anything like the below:
-```js
-document.bind({ name: 'James Boye', cool: '100%', app: { title: 'Demo App' } });
-document.body.bind({ name: 'John Doe' });
-```
-```js
-document: { name: 'James Boye', cool: '100%', app: { title: 'Demo App' } }
- └── html
-  ├── head
-  └── body: { name: 'John Doe' }
-```
-Now, the `name` reference remains bound to the `name` *binding* on the `<body>` element until the meaning of "closest node" changes again:
-```js
-delete document.body.bindings.name;
-```
-While the `cool` reference remains bound to the `cool` *binding* on the `document` node until the meaning of "closest node" changes again:
-```js
-document.body.bindings.cool = '200%';
-```
-</details>
 <details><summary>With SSR Support</summary>
 On the server, these data-binding tags would retain their place in the DOM while having their output rendered to their right in a text node.
@@ -677,7 +647,7 @@ Here, we get the `binding` attribute for a declarative and neat, key/value data-
 | Directive | Type | Usage |
 | :---- | :---- | :---- |
-| `&`  | CSS Property | `<div binding="& color:someColor; & backgroundColor:someBgColor;"></div>` |
+| `&`  | CSS Property | `<div binding="& color:someColor; & backgroundColor:someColor;"></div>` |
 | `%`  | Class Name | `<div binding="% active:app.isActive; % expanded:app.isExpanded;"></div>` |
 | `~`  | Attribute Name | `<a binding="~ href:person.profileUrl+'#bio'; ~ title:'Click me';"></a>` |
 |   | Boolean Attribute | `<a binding="~ ?required:formField.required; ~ ?aria-checked: formField.checked"></a>` |
@@ -706,53 +676,23 @@ Here, we get the `binding` attribute for a declarative and neat, key/value data-
 </details>
-<details><summary>Resolution details</summary>
-Here, JavaScript references are resolved from the closest node up the document hierarchy that exposes a corresponding *binding* on its Bindings API ([discussed below](#bindings-api)). Thus, for the above CSS bindings, our underlying data structure could be anything like the below:
-```js
-document.bind({ someColor: 'green', someBgColor: 'yellow' });
-document.body.bind({ someBgColor: 'silver' });
-```
-```js
-document: { someColor: 'green', someBgColor: 'yellow' }
- └── html
-  ├── head
-  └── body: { someBgColor: 'silver' }
-```
-Now, the `someBgColor` reference remains bound to the `someBgColor` *binding* on the `<body>` element until the meaning of "closest node" changes again:
-```js
-delete document.body.bindings.someBgColor;
-```
-While the `someColor` reference remains bound to the `someColor` *binding* on the `document` node until the meaning of "closest node" changes again:
-```js
-document.body.bindings.someColor = 'brown';
-```
-</details>
 <details><summary>All in realtime</summary>
-Bindings are resolved in realtime! And in fact, for lists, in-place mutations - additions and removals - on the *iteratee* are automatically reflected on the UI!
+Lists are rendered in realtime, which means that in-place mutations - additions and removals - on the *iteratee* will be automatically reflected on the UI!
 </details>
 <details><summary>With SSR Support</summary>
-For lists, generated item elements are automatically assigned a corresponding index with a `data-index` attribute! This helps in remapping generated item nodes to their respective entry in *iteratee* - universally.
+Generated item elements are automatically assigned a corresponding index with a `data-index` attribute! This helps in remapping generated item nodes to their respective entry in *iteratee* - universally.
 </details>
 ### Quantum Scripts
-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.
+We often still need to write more serious reactive logic on the UI than a declarative data-binding language can provide. 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 an attribute: `quantum`:
+Here, from the same `<script>` element we write everyday, we get a direct upgrade path to reactive programming in just an attribute: `quantum`:
 ```html
 <script quantum>
@@ -849,17 +789,9 @@ It's Imperative Reactive Programming ([IRP](https://en.wikipedia.org/wiki/Reacti
 Here, the runtime executes your code in a special execution mode that gets literal JavaScript expressions to statically reflect changes. This makes a lot of things possible on the UI! The [Quantum JS](https://github.com/webqit/quantum-js) documentation has a detailed run down.
-Now, in each case above, reactivity terminates on script's removal from the DOM. And a programmatic termination is sill possible:
-```js
-const script = document.querySelector('script[quantum]');
-// const script = document.querySelector('main').scripts[0];
-script.abort();
-```
-But while that is automatic, DOM event handlers bound via `addEventListener()` would still need to be terminated in their own way.
+Now, in each case above, reactivity terminates on script's removal from the DOM. But of course, DOM event handlers bound via `addEventListener()` would still need to be terminated in their own way.
-</details>
+<details>
 ## Data Plumbing
@@ -960,7 +892,7 @@ Observer.set(element, 'liveProperty'); // Live expressions rerun
 ## Polyfill
-OOHTML is being developed as something to be used today—via a polyfill. This is an active and intentional effort that continues to ensure that the project evolves through a practice-driven process.
+OOHTML is being developed as something to be used today - via a polyfill.
 <details><summary>Load from a CDN<br>
 └───────── <a href="https://bundlephobia.com/result?p=@webqit/oohtml"><img align="right" src="https://img.shields.io/bundlephobia/minzip/@webqit/oohtml?label=&style=flat&colorB=black"></a></summary>
@@ -981,8 +913,9 @@ OOHTML is being developed as something to be used today—via a polyfill. This i
 </details>
-<details><summary>Install from NPM<br>
-└───────── <a href="https://npmjs.com/package/@webqit/oohtml"><img align="right" src="https://img.shields.io/npm/v/@webqit/oohtml?style=flat&label=&colorB=black"></a></summary>
+<details><summary>Extended usage concepts</summary>
+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 `@webqit/oohtml` with the DOM instance:
 ```bash
 npm i @webqit/oohtml
@@ -996,15 +929,9 @@ import init from '@webqit/oohtml';
 init.call( window[, options = {} ]);
 ```
-└ 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 `@webqit/oohtml` 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!
-└ But all things "SSR" for OOHTML are best left to the [`@webqit/oohtml-ssr`](https://github.com/webqit/oohtml-ssr) package!
-</details>
-<details><summary>Extended usage concepts</summary>
-If you'll be going ahead to build a real app to see OOHTML in action, you may want to consider also using:
+Also, if you'll be going ahead to build a real app to see OOHTML in action, you may want to consider also using:
 + the [`@webqit/oohtml-cli`](https://github.com/webqit/oohtml-cli) package for operating a file-based templating system.
@@ -1042,7 +969,7 @@ If you'll be going ahead to build a real app to see OOHTML in action, you may wa
     ...still gives the `window` object in the console.
-+ **Scoped/Quantum Scripts**. This feature is an extension of [Quantum JS](https://github.com/webqit/quantum-js) and the default OOHTML build is based on the [Quantum JS Lite APIs](https://github.com/webqit/quantum-js#quantum-js-lite). Now, while Quantum JS Lite yields faster load times, it also means that `<script quantum></script>` and `<script scoped></script>` elements are parsed "asynchronously", in the same timing as `<script type="module"></script>`!
++ **Scoped/Quantum Scripts**. This feature is an extension of [Quantum JS](https://github.com/webqit/quantum-js). The default OOHTML build is based on the [Quantum JS Lite APIs](https://github.com/webqit/quantum-js#quantum-js-lite) and this means that `<script quantum></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'd need to use the *realtime* OOHTML build:
@@ -1100,72 +1027,84 @@ If you'll be going ahead to build a real app to see OOHTML in action, you may wa
 ## Examples
-Here are a few examples in the wide range of use cases these features cover. While we'll demonstrate the most basic forms of these scenarios, it takes roughly the same principles to build an intricate form and a highly interactive UI.
+Here are a few examples in the wide range of use cases these features cover.
++ [Example 1: *Single Page Application*](#example-1-single-page-application)
++ [Example 2: *Multi-Level Namespacing*](#example-2-multi-level-namespacing)
++ [Example 3: *Dynamic Shadow DOM*](#example-3-dynamic-shadow-dom)
++ [Example 4: *Declarative Lists*](#example-4-declarative-lists)
++ [Example 5: *Imperative Lists*](#example-4-imperative-lists)
-<details><summary>Example 1: <i>Single Page Application</i><br>
-└───────── </summary>
+### 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))*:
++ *First, two components that are themselves analogous to a Single File Component ([SFC](https://vuejs.org/guide/scaling-up/sfc.html))*:
-```html
-<template def="pages">
+    <details><summary>Code</summary>
-  <template def="layout">
-    <header def="header"></header>
-    <footer def="footer"></footer>
-  </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>
-  <!-- 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>
+    </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>
+    </details>
-</template>
-```
++ *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>
-```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>
-<details><summary>Example 2: <i>Multi-Level Namespacing</i><br>
-└───────── </summary>
+### Example 2: *Multi-Level Namespacing*
 The following is a Listbox component lifted directly from the [ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-grouped/#sc_label) but with IDs effectively "contained" at different levels within the component using the `namespace` attribute.
+<details><summary>Code</summary>
 ```html
 <div namespace class="listbox-area">
   <div>
@@ -1231,65 +1170,75 @@ The following is a Listbox component lifted directly from the [ARIA Authoring Pr
 </details>
-<details><summary>Example 3: <i>Dynamic Shadow DOM</i><br>
-└───────── </summary>
+### Example 3: *Dynamic Shadow DOM*
 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*:
-```html
-<template def="vendor1">
+    <details><summary>Code</summary>
-  <template def="components-layout1">
-    <template def="magic-button">
-      <span id="icon"></span> <span id="text"></span>
-    </template>
-  </template>
+    ```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-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>
-```
+    </details>
-**-->** *Next, the Shadow DOM creation that imports its layout from context*:
++ *Next, the Shadow DOM creation that imports its layout from context*:
-```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><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) );
+        });
+      }
     });
-  }
-});
-```
+    ```
-**-->** *Then, the part where we just drop the component in "layout" contexts*:
+    </details>
-```html
-<div contextname="vendor1" importscontext="/vendor1/components-layout1">
++ *Then, the part where we just drop the component in "layout" contexts*:
-  <magic-button></magic-button>
+    <details><summary>Code</summary>
-  <aside contextname="vendor1" importscontext="/vendor1/components-layout2">
-    <magic-button></magic-button>
-  </aside>
+    ```html
+    <div contextname="vendor1" importscontext="/vendor1/components-layout1">
-</div>
-```
+      <magic-button></magic-button>
-</details>
+      <aside contextname="vendor1" importscontext="/vendor1/components-layout2">
+        <magic-button></magic-button>
+      </aside>
-<details><summary>Example 4: <i>Declarative Lists</i><br>
-└───────── </summary>
+    </div>
+    ```
+    </details>
+### Example 4: *Declarative Lists*
 The following is a hypothetical list page!
+<details><summary>Code</summary>
 ```html
 <section>
@@ -1306,11 +1255,12 @@ The following is a hypothetical list page!
 </details>
-<details><summary>Example 5: <i>Imperative Lists</i><br>
-└───────── </summary>
+### Example 4: *Imperative Lists*
 The following is much like the above, but imperative. Additions and removals on the data items are also statically reflected!
+<details><summary>Code</summary>
 ```html
 <section namespace>

package/package.json CHANGED Viewed

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