@webqit/oohtml 2.1.54 → 2.1.55

package/README.md

@@ -5,25 +5,27 @@
 [![bundle][bundle-src]][bundle-href]
 [![License][license-src]][license-href]
 
-**[Overview](#an-overview) • [Polyfill](#the-polyfill) • [Design Discussion](#design-discussion) • [Getting Involved](#getting-involved) • [License](#license)**
+**[Overview](#overview) • [Modular HTML](#modular-html) • [HTML Imports](#html-imports) • [Reactive HTML](#reactive-html) • [Polyfill](#polyfill) • [Examples](#examples) • [License](#license)**
 
 Object-Oriented HTML (OOHTML) is a set of language features for authoring modular, reusable markup, and for translating that to functional DOM-level objects! Everything comes together as a delightful holistic component architecture for the modern UI!
 
 OOHTML is an upcoming proposal!
 
-<!--
 ## Motivation
 
+<details><summary>Show</summary>
+
 The web has generally outgrown the idea of a monolith architecture on the UI! But enter HTML; the current authoring experience is one where an author is trying to think out one thing but forced to work out everything, in how the language for the job poses one global scope as the unit of abstraction for styles, scripts and element identifiers — enforcing many global dependencies; inflicting much global thinking!
 
 Think too of how authors often have to do half of the work in HTML and half in JS just to have reusable markup!
 
-This project is a proposal for a new standards work that revisits much of the oldish monolith-oriented constraints in HTML that inhibit the idea of a *component* architecture in HTML! The name Object-Oriented HMTL turns out to be more descriptive of the idea than the "component" paradigm!
+This project is a proposal for a new standards work that revisits much of the oldish monolith-oriented constraints in HTML that inhibit the idea of a *component* architecture in HTML!
 
 └ [See more in the introductory blog post](https://dev.to/oxharris/the-web-native-equations-1m1p-temp-slug-6661657?preview=ba70ad2c17f05b5761bc74516dbde8c9eff8b581a0420d87334fd9ef6bab9d6e6d3ab6aaf3fe02542bb9e7250d0a88a6df91dae40919aabcc9a07320)<sup>draft</sup>
--->
 
-## An Overview
+</details>
+
+## Overview
 
 OOHTML comes in three sets of features, and the following is an overview. A more detailed documentation for OOHTML is underway in the [project wiki](https://github.com/webqit/oohtml/wiki).
 
@@ -34,7 +36,7 @@ OOHTML comes in three sets of features, and the following is an overview. A more
 
 > **Note**  This is documentation for `OOHTML@2.x`. (Looking for [`OOHTML@1.x`](https://github.com/webqit/oohtml/tree/v1.10.4)?)
 
-### Modular HTML
+## Modular HTML
 
 The first set of features covers authoring objects with self-contained structure, styling and *scripting*! This simply gets identifiers, style sheets and scripts to serve *at the object level* exactly as they do *at the document (object) level*.
 
@@ -84,7 +86,7 @@ let { styleSheets, scripts } = user; // APIs that are analogous to the document.
 
 └ [Modular HTML concepts](#)
 
-### HTML Imports
+## HTML Imports
 
 The next set of features covers *templating and reusing objects* - in both *declarative* and *programmatic* terms! It extends the language with the *module identifier* attribute `def`, and introduces a complementary new `<import>` element, and has everything working together as a real-time module system.
 
@@ -363,7 +365,7 @@ document.querySelector('div').import('#fragment2', divElement => {
 
 └ [HTML Imports concepts](#)
 
-### Reactive HTML
+## Reactive HTML
 
 The last set of features covers the concept of "state", "bindings", and "reactivity" for those objects at the DOM level - in the most exciting form of the terms and as an upgrade path! This comes factored into the design as something intrinsic to the problem.
 
@@ -476,14 +478,160 @@ Observer.set(element, 'liveProperty'); // Live expressions rerun
 
 └ [Reactive HTML concepts](#)
 
-### Put Together
+## Polyfill
+
+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>
+
+```html
+<script src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
+```
+
+└ 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...
 
-All of OOHTML brings to the platform much of the modern UI development paradigms that community-based tools have long encoded, and that just opens up new ways to leverage the web platform and bank less on abstractions! Here are a few examples in the wide range of use cases these features cover.
+```html
+<body>
+  <script scoped>
+    console.log(this); // body
+  </script>
+</body>
+```
 
-**--> Example 1:** 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:
+...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):
+
+```html
+<head>
+  <script src="https://unpkg.com/style-scoped/scoped.min.js"></script>
+</head>
+```
+
+</details>
+
+<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
+```
+
+```js
+// Import
+import init from '@webqit/oohtml';
+
+// Initialize the lib
+init.call( window[, options = {} ]);
+```
+
+But all things "SSR" for OOHTML are best left to the [`@webqit/oohtml-ssr`](https://github.com/webqit/oohtml-ssr) package!
+
+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.
+
++ the modest, OOHTML-based [Webflo](https://github.com/webqit/webflo) framework to greatly streamline your application development process!
+
+</details>
+
+<details><summary>Implementation Notes</summary>
+
++ **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:
+
+    ```html
+    <head>
+      <script src="https://unpkg.com/@webqit/oohtml/dist/main.realtime.js"></script>
+    </head>
+    ```
+
++ **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`:
+
+    ```html
+    <head>
+      <meta name="scoped-css" content="style.strategy=@scope"> <!-- Must come before the polyfil -->
+      <script src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
+    <head>
+    ```
+
+    Now the following `<style scoped>`...
+
+    ```html
+    <style scoped>
+      h2 { color: red; }
+    </style>
+    ```
+    
+    ...will be wrapped to something like:
+
+    ```html
+    <style ref="scoped8eff" scoped>
+      @scope from (:has(> style[ref="scoped8eff"])) {
+        h2 { color: red; }
+      }
+    </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):
+
+    ```html
+    <script src="https://unpkg.com/style-scoped/scoped.min.js"></script>
+    ```
+
++ **HTML Imports**. The attribute names for exposing reusable modules and for referencing them - the `def` and `ref` keywords, respectively - aren't finalized. While the principle of operation remains, these attributes may be renamed in subsequent iterations. But the polyfill is designed to always defer to any syntax that has been explicitly specified using a meta tag. Here's an example:
+
+    ```html
+    <head>
+      <meta name="html-imports" content="template.attr.moduledef=def; template.attr.fragmentdef=def; import.attr.moduleref=ref;"> <!-- Must come before the polyfil -->
+      <script src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
+    <head>
+    ```
+
+    Now, even when the default attribute names change, your `def` and `ref` implementation will still work:
+ 
+</details>
+
+## Examples
+
+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: *List Items*](#example-4-list-items)
+
+### 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">
 
@@ -517,8 +665,12 @@ All of OOHTML brings to the platform much of the modern UI development paradigms
 </template>
 ```
 
+</details>
+
 └ *Then a 2-line router that alternates the view based on the URL hash*:
 
+<details><summary>Code</summary>
+
 ```html
 <body importscontext="/pages/home">
 
@@ -534,9 +686,13 @@ All of OOHTML brings to the platform much of the modern UI development paradigms
 </body>
 ```
 
-**--> Example 2:** 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>
+
+### Example 2: *Multi-Level Namespacing*
 
-└ *A Listbox with namespaced IDs*:
+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">
@@ -601,10 +757,16 @@ All of OOHTML brings to the platform much of the modern UI development paradigms
 </div>
 ```
 
-**--> Example 3:** 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!
+</details>
+
+### 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*:
 
+<details><summary>Code</summary>
+
 ```html
 <template def="vendor1">
 
@@ -623,8 +785,12 @@ All of OOHTML brings to the platform much of the modern UI development paradigms
 </template>
 ```
 
+</details>
+
 └ *Next, the Shadow DOM creation that imports its layout from context*:
 
+<details><summary>Code</summary>
+
 ```js
 customElements.define('magic-button', class extends HTMLElement {
   connectedCallback() {
@@ -636,8 +802,12 @@ customElements.define('magic-button', class extends HTMLElement {
 });
 ```
 
+</details>
+
 └ *Then, the part where we just drop the component in "layout" contexts*:
 
+<details><summary>Code</summary>
+
 ```html
 <div contextname="vendor1" importscontext="/vendor1/components-layout1">
 
@@ -650,9 +820,13 @@ customElements.define('magic-button', class extends HTMLElement {
 </div>
 ```
 
-**--> Example 4:** 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>
+
+### Example 4: *List Items*
 
-└ *A list component with scoped module system*:
+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 namespace>
@@ -681,148 +855,8 @@ customElements.define('magic-button', class extends HTMLElement {
 </div>
 ```
 
-## The Polyfill
-
-OOHTML is being developed as something to be used today - via a polyfill. This has been helping to facilitate the "release - iterations" loop and its overall evolution.
-
-The polyfill can be loaded from the `unpkg.com` CDN, and should be placed early on in the document - before any OOHTML-specific features are used - and should be a classic script without any `defer` or `async` directives:
-
-```html
-<head>
-  <script src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
-</head>
-```
-
-> 22.5 kB min + gz | 77.5 KB min [↗](https://bundlephobia.com/package/@webqit/oohtml@2.1.45)
-
-<details><summary>
-Extended usage concepts
-</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.
-
-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
-```
-
-```js
-// Import
-import init from '@webqit/oohtml';
-
-// Initialize the lib
-init.call( window[, options = {} ]);
-```
-
-But all things "SSR" for OOHTML are best left to the [`@webqit/oohtml-ssr`](https://github.com/webqit/oohtml-ssr) package!
-
-Also, if you'll be going ahead to build a real world 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.
-
-+ the modest, OOHTML-based [Webflo](https://github.com/webqit/webflo) framework to greatly streamline your application development process!
-
-</details>
-
-<details><summary>
-Implementation Notes
-</summary>
-
-Here are some performance-specific notes for this polyfill:
-
-+ By default, the Stateful JS compiler (44.31 KB min+compressed | 157KB min) is excluded from the polyfill build and fetched separately on demand - on the first encounter with a Stateful Script. This is loaded into a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) and all compilations are able to happen off the main thread! This ensures near-zero cost to your application loading and runtime performance!
-
-    Note that this lazy-loading approach means that all Stateful Scripts will behave "async" just like module scripts; i.e. scripts are defered until the compiler has been loaded. In other words, the following two scripts will have the same timing semantics:
-
-    ```html
-    <script stateful></script>
-    <script type="module" stateful></script>
-    ```
-
-    This isn't necessarily bad unless there is 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), in which case the Stateful JS compiler will need to be explicitly and synchronously loaded ahead of any encounter with classic Stateful Scripts:
-
-    ```html
-    <head>
-      <script src="https://unpkg.com/@webqit/stateful-js/dist/compiler.js"></script> <!-- Must come before the polyfil -->
-      <script src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
-    </head>
-    ```
-
-+ Whether loaded lazily or eagerly, the compiler also factors in additional optimizations. For example, identical scripts are handled only first time, and only ever have one Stateful JS instance!
-
-Here are other notes:
-
-+ **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`:
-
-    ```html
-    <head>
-      <meta name="scoped-css" content="style.strategy=@scope"> <!-- Must come before the polyfil -->
-      <script src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
-    <head>
-    ```
-
-    Now the following `<style scoped>`...
-
-    ```html
-    <style scoped>
-      h2 { color: red; }
-    </style>
-    ```
-    
-    ...will be wrapped to something like:
-
-    ```html
-    <style ref="scoped8eff" scoped>
-      @scope from (:has(> style[ref="scoped8eff"])) {
-        h2 { color: red; }
-      }
-    </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).
-
-+ **HTML Imports**. The attribute names for exposing reusable modules and for referencing them - the `def` and `ref` keywords, respectively - aren't finalized. While the principle of operation remains, these attributes may be renamed in subsequent iterations. But the polyfill is designed to always defer to any syntax that has been explicitly specified using a meta tag. Here's an example:
-
-    ```html
-    <head>
-      <meta name="html-imports" content="template.attr.moduledef=def; template.attr.fragmentdef=def; import.attr.moduleref=ref;"> <!-- Must come before the polyfil -->
-      <script src="https://unpkg.com/@webqit/oohtml/dist/main.js"></script>
-    <head>
-    ```
-
-    Now, even when the default attribute names change, your `def` and `ref` implementation will still work:
- 
 </details>
 
-## Design Discussion
-
-*[TODO]*
-
 ## Getting Involved
 
 All forms of contributions are welcome at this time. For example, syntax and other implementation details are all up for discussion. Also, help is needed with more formal documentation. And here are specific links: