@webqit/webflo 0.11.5 → 0.11.8

package/README.md

@@ -22,6 +22,7 @@ Ok, we've put all of that up for a straight read!
 + [Webflo Applications](#webflo-applications)
 + [Workflow API](#workflow-api)
 + [Webflo Config](#webflo-config)
++ [Technology Stack](#technology-stack)
 + [Getting Started](#getting-started)
 + [Getting Involved](#getting-involved)
 
@@ -135,13 +136,13 @@ For when your application involves routing:
 + [WHATWG URL](https://url.spec.whatwg.org/) and [WHATWG URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) are used for all things *URL* and *URL pattern matching*, respectively - across client, server, and Service Worker environments. ([Details ahead](#))
 
 For when your application involves pages and a UI:
-+ [The HTML Standard](https://html.spec.whatwg.org/) is held for all things *markup* - across client, server, and Service Worker environments! Webflo is all about using conventional `.html`-based pages and templates, valid HTML syntax, etc. You are able to get away with a "zero-JavaScript" proposition or with *Progressive Enhancement* that makes do with "just-enough JavaScript"!
++ [The HTML Standard](https://html.spec.whatwg.org/) is held for all things *markup* - across client, server, and Service Worker environments! Webflo is all about using conventional `.html`-based pages and templates, valid HTML syntax, etc. You are able to get away with a "zero-JavaScript" proposition, or a *Progressive Enhancement* proposition that makes do with "just-enough JavaScript"!
 
-  > Your markup is also easily extendable with [OOHTML](https://github.com/webqit/oohtml) - a set of new features for HTML that makes it fun to hand-author your UI! Within OOHTML are [HTML Modules (`<template name="partials"></template>`)](https://github.com/webqit/oohtml#html-modules) and [HTML Imports (`<import template="partials"></import>`)](https://github.com/webqit/oohtml#html-imports), [Reactive Scripts (`<script type="subscript"></script>`)](https://github.com/webqit/oohtml#subscript) and more!
+  > Your markup is also easily extendable with [OOHTML](#oohtml) - a set of new features for HTML that makes it fun to hand-author your UI! Within OOHTML are [HTML Modules](https://github.com/webqit/oohtml#html-modules) and [HTML Imports](https://github.com/webqit/oohtml#html-imports), [Reactive Scripts](https://github.com/webqit/oohtml#subscript) and more!
 
-+ [WHATWG DOM](https://dom.spec.whatwg.org/) is universally available - not only on the client-side, but also on the server-side via [OOHTML-SSR](https://github.com/webqit/oohtml-ssr) - for all things *dynamic pages*: rendering, manipulation, interactivity, etc.
++ [WHATWG DOM](https://dom.spec.whatwg.org/) is universally available - not only on the client-side, but also on the server-side via [OOHTML-SSR](#oohtml-ssr) - for all things *dynamic pages*: rendering, manipulation, interactivity, etc.
 
-  > Your DOM is also easily enrichable with [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements), plus [Subscript Elements](https://github.com/webqit/oohtml#subscript) and [The State API (`document.state` and `element.state`)](https://github.com/webqit/oohtml#state-api) from OOHTML.
+  > Your DOM is also easily enrichable with [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements), plus [Subscript Elements](https://github.com/webqit/oohtml#subscript) and [The State API](https://github.com/webqit/oohtml#state-api) from OOHTML.
 
 For when your application needs to give an app-like experience:
 + [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API), extended with full support for routing, come into play for offline and [Progressive Web Apps (PWA)](https://web.dev/progressive-web-apps/) capabilities.
@@ -153,7 +154,7 @@ This and more - ahead! For building web-native apps!
 
 ## Installation
 
-Every Webflo project starts on an empty directory that you can create on your machine. The command below will make a new directory `my-app` from the terminal and navigate into it.
+Every Webflo project starts on an empty directory that you can create on your machine. The command below makes a new directory `my-app` from the terminal and navigates into it.
 
 ```shell
 mkdir my-app
@@ -198,7 +199,7 @@ All is now set! The commands `npm start` and `npm run generate` will be coming i
 
 ### "Hello World!"
 
-To be sure that Webflo is listening, run `npx webflo help` on the terminal. An overview of available commands will be shown.
+To be sure that Webflo is listening, run `npx webflo help` on the terminal. An overview of available commands should be shown.
 
 If you can't wait to say *Hello World!* 😅, you can have an HTML page say that right now!
 + Create an `index.html` file in a new subdirectory `public`.
@@ -238,7 +239,7 @@ If you can't wait to say *Hello World!* 😅, you can have an HTML page say that
 
 ### Handler Functions and Layout
 
-Whether building a *server-based*, *browser-based*, or *universal* application, Webflo gives us one consistent way to handle routing and navigation: using *handler functions*!
+Whether building a *server-based*, *browser-based*, or *universal* application, Webflo gives you one consistent way to handle routing and navigation: using *handler functions*!
 
 ```js
 /**
@@ -249,7 +250,10 @@ export default function(event, context, next) {
 }
 ```
 
-Each function receives an `event` object representing details - e.g. `event.request`, `event.url`, `event.session` - about the current flow. (Details ahead.)
+> **Note**
+> <br>Other [*method*](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods)-specific function names may be used: `get`, `post`, `put`, `patch`, `del` (for *delete*), `options`, `head`, etc.
+
+Each function receives an `event` object representing details - e.g. `event.request`, `event.url`, `event.session` - about the current request. ([Details ahead](#workflow-api).)
 
 For *server-based* applications (e.g. traditional web apps and API backends), server-side handlers go into a directory named `server`.
 
@@ -372,7 +376,7 @@ export default function(event, context, next) {
 
 This step-based workflow helps to decomplicate routing and gets us scaling horizontally as our application grows larger.
 
-Workflows may be designed with *wildcard* steps using a hyphen `-` as step name. Wildcard steps match all paths at the given level of the route! A `this.stepname` property can always be used to see the current URL step that matched.
+Workflows may be designed with *wildcard* steps using a hyphen `-` as step name. At runtime, a wildcard step matches any URL segment at its level in the layout! A `this.stepname` property could be used to see which URL segment has been matched.
 
 ```js
 /**
@@ -424,7 +428,7 @@ Webflo takes a *default action* when `next()` is called at the *edge* of the wor
 
 For workflows in **the `/server` directory**, the *default action* of `next()`ing at the edge is to go match and return a static file in the `public` directory.
 
-So, above, should our handler receive static file requests like `http://localhost:3000/logo.png`, the expression `return next()` would get Webflo to match and return the logo at `public/logo.png`, if any; a `404` response otherwise.
+So, above, should our handler receive static file requests like `http://localhost:3000/logo.png`, the statement `return next()` would get Webflo to match and return the logo at `public/logo.png`, if any; a `404` response otherwise.
 
 ```shell
 my-app
@@ -433,7 +437,7 @@ my-app
 ```
 
 > **Note**
-> <br>The root handler effectively becomes the single point of entry to the application - being that it sees even static requests!
+> <br>The root handler effectively becomes the single point of entry to the application - being that it sees even requests for static files!
 
 Now, for workflows in **the `/worker` directory**, the *default action* of `next()`ing at the edge is to send the request through the network to the server. (But Webflo will know to attempt resolving the request from the application's caching system built into the Service Worker.)
 
@@ -562,7 +566,7 @@ But, we can also access the route in a way that gets the data rendered into the
 Now, for Single Page Applications, subsequent navigations, after the initial page load, just ask for the data on destination URLs and perform [Client-Side Rendering](#client-and-server-side-rendering) on the same running document. Navigation is sleek and instant!
 
 > **Note**
-> <br>Unless disabled in [config](#spa_routing), SPA routing is automatically built into your app's JS bundle from the `npm run generate` command. So, it just works!
+> <br>Unless disabled, [SPA Routing](#spa_routing) is automatically built into your app's JS bundle from the `npm run generate` command. So, it just works!
 
 With no extra work, your application can function as either a *Multi Page App (MPA)* or a *Single Page App (SPA)*!
 
@@ -596,7 +600,7 @@ my-app
 
 This, in both cases, is templating - the ability to define HTML *partials* once, and have them reused multiple times. Webflo just concerns itself with templating, and the choice of a Multi Page Application or Single Page Application becomes yours! And heck, you can even have the best of both worlds in the same application - with an architecture we'll call [Multi SPA](#in-a-multi-spa-layout)! It's all a *layout* thing!
 
-Now, with pages in Webflo being [DOM-based](#overview) (both client-side and [server-side](https://github.com/webqit/oohtml-ssr)), documents can be manipulated directly with DOM APIs, e.g. to replace or insert nodes, attributes, etc. But even better, templating in Webflo is based on the [HTML Modules](https://github.com/webqit/oohtml#html-modules) and [HTML Imports](https://github.com/webqit/oohtml#html-imports) features in [OOHTML](https://github.com/webqit/oohtml) - unless disabled in [config](#oohtml_support). These features provide a powerful declarative templating system on top of the standard [HTML `<template>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template) element - with a *module*, *export* and *import* paradigm.
+Now, with pages in Webflo being [DOM-based](#overview) (both client-side and [server-side](#oohtml-ssr)), documents can be manipulated directly with DOM APIs, e.g. to replace or insert nodes, attributes, etc. But even better, templating in Webflo is based on the [HTML Modules](https://github.com/webqit/oohtml#html-modules) and [HTML Imports](https://github.com/webqit/oohtml#html-imports) features in [OOHTML](#oohtml) - unless disabled in config. These features provide a powerful declarative templating system on top of the standard [HTML `<template>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template) element - with a *module*, *export* and *import* paradigm.
 
 Here, you are able to define reusable contents in a `<template>` element...
 
@@ -703,7 +707,7 @@ public/products
 
 #### In a Single Page Layout
 
-In a Single Page layout (as [above](#layout-and-templating-overview)), page-specific contents - e.g. main sections - are typically bundled together into one `bundle.html` file that can be embedded on the document root. Nested routes end up as nested `<template>` elements to form the equivalent of their URL structure.
+In a Single Page layout (as seen [earlier](#layout-and-templating-overview)), page-specific contents - e.g. main sections - are typically bundled together into one `bundle.html` file that can be embedded on the document root. Nested routes end up as nested `<template>` elements that form the equivalent of thw application's URL structure.
 
 ```html
 <!--
@@ -817,7 +821,7 @@ The Webflo `generate` command automatically figures out a given architecture and
 
 #### Bundling
 
-Template `.html` files are bundled from the filesystem into a single file using the [OOHTML CLI](https://github.com/webqit/oohtml-cli) utility. On installing this utility, you may want to add the following to your npm scripts in `package.json`.
+Template `.html` files are bundled from the filesystem into a single file using the [OOHTML CLI](#oohtml-cli) utility. On installing this utility, you may want to add the following to your npm scripts in `package.json`.
 
 ```json
 "scripts": {
@@ -830,13 +834,13 @@ The `--recursive` flag gets the bundler to recursively bundle *subroots* in a [M
 The `--auto-embed` flag gets the bundler to automatically embed the generated `bundle.html` file on the matched `index.html` document. A value of `routes` for the flag ends up as the name of the *embed* template: `<template name="routes" src="/bundle.html"></template>`.
 
 > **Note**
-> <br>If your HTML files are actually based off the `public` directory, you'll need to tell the above command to run in the `public` directory, either by [configuring the bundler](https://github.com/webqit/oohtml-cli#other-options), or by rewriting the command with a prefix: `cd public && oohtml bundle --recursive --auto-embed=routes`. 
+> <br>If your HTML files are actually based off the `public` directory, you'll need to tell the above command to run in the `public` directory, either by [configuring the bundler](https://github.com/webqit/oohtml-cli#other-options), or by rewriting the command with a prefix: `cd public && oohtml bundle --recursive --auto-embed=routes`.
 
 ### Client and Server-Side Rendering
 
-With pages in Webflo being [DOM-based](#overview) (both client-side and [server-side](https://github.com/webqit/oohtml-ssr)), we are able to access and manipulate documents and elements using familiar DOM APIs - e.g. to replace or insert contents, attributes, etc. Rendering in Webflo is based on this concept!
+With pages in Webflo being [DOM-based](#overview) (both client-side and [server-side](#oohtml-ssr)), we are able to access and manipulate documents and elements using familiar DOM APIs - e.g. to replace or insert contents, attributes, etc. Rendering in Webflo is based on this concept!
 
-Here, Webflo simply makes sure that the data obtained from each route is available as part of the `document` object, such that it is accessible to our rendering logic as a `data` property on the `document.state` object - `document.state.data`. (The `document.state` object is always available unless disabled in config.)
+Here, Webflo simply makes sure that the data obtained from each route is available as part of the `document` object, such that it is accessible to our rendering logic as a `data` property on the [`document.state`](#the-idea-of-state) object - [`document.state.data`](#the-documentstatedata-object).
 
 So, we could embed a script on our page and render this data on the relevant parts of the document.
 
@@ -880,7 +884,7 @@ public
 
 From here, even the most-rudimentary form of rendering (using vanilla HTML and native DOM methods) becomes possible, and this is a good thing: you get away with less tooling until you absolutely need to add up on tooling!
 
-However, since the `document` objects in Webflo natively support [OOHTML](https://github.com/webqit/oohtml) - unless disabled in [config](#oohtml_support), we are able to write reactive UI logic! Here, OOHTML makes it possible to embed reactive `<script>` elements (called [Subscript](https://github.com/webqit/oohtml#subscript)) right within HTML elements - where each expression automatically self-updates whenever references to data, or its properties, get an update!
+However, since the `document` objects in Webflo natively support [OOHTML](#oohtml) - unless disabled in config, we are able to write reactive UI logic! Here, OOHTML makes it possible to embed reactive `<script>` elements (called [Subscript](https://github.com/webqit/oohtml#subscript)) right within HTML elements - where each expression automatically self-updates whenever references to data, or its properties, get an update!
 
 ```html
  <!--
@@ -929,7 +933,9 @@ Going forward, we can get to write more succinct code! Using the [Namespaced HTM
           document.title = title;
           let { headline1, headline2 } = this.namespace;
           $(headline1).html(title);
-          $(headline2).html(title);
+          if (headline2) {
+              $(headline2).html(title);
+          }
          </script>
      </body>
  </html>
@@ -1021,16 +1027,122 @@ export async function render(event, data, next) {
 
 Custom render functions must return a value, and `window` objects are accepted. (Actually, any object that has a `toString()` method can be returned.)
 
+#### The Idea of State
+
+There often needs to be a central point in an application where things are stored and managed. You could think of it is having a global object initialized `window.store = {}` on which different parts of an application can store and retrieve values. This is the basic idea of state. But it also doesn't go without the idea of *observability* - something that lets the different parts of the application observe and respond to changes made on this object!
+
+*State* and *Observability* in Webflo applications come down to this basic form: there is an object...
+
+```js
+state = {}
+```
+
+...and there is a way to observe property changes on it...
+
+```js
+Observer.observe(state, changes => {
+    changes.forEach(change => {
+        console.log(change.name, change.value);
+    });
+});
+```
+
+```js
+Observer.observe(state, propertyName, change => {
+    console.log(change.name, change.value);
+});
+```
+
+...plus, all references to the object and its properties from within embedded Subscript code are reactive.
+
+```html
+<script type="subscript">
+    // Always log the value of this property in realtime
+    console.log(state.propertyName);
+</script>
+```
+
+This way, all the moving parts of your application remain coordinated, and can easily be rendered to reflect them on the UI!
+
+For all things application state, Webflo leverages the [State API](https://github.com/webqit/oohtml#state-api) that's natively available in OOHTML-based documents - both client-side and server-side. This API exposes an application-wide `document.state` object and a per-element `element.state` object. And these are *live* read/write objects that can be observed for property changes using the [Observer API](#the-observer-api). It comes off as the simplest approach to state and reactivity!
+
+> **Note**
+> <br>The State API is not available when the [OOHTML support level](#oohtml) in config is switched away from `full` and `scripting`.
+
+#### The `document.state.data` Object
+
+This property reperesents the application data at any point in time - obtained from route handers on each navigation. Webflo simply updates this property and lets the page's [rendering logic](#client-and-server-side-rendering), or other parts of the application, take over.
+
+```js
+Observer.observe(document.state, 'data', e => {
+    console.log('Current page data is: ', e.value);
+});
+```
+
+```html
+<script type="subscript">
+ let { title } = document.state.data;
+ document.title = title;
+</script>
+```
+
+#### The `document.state.url` Object
+
+This is a *live* object that reperesents the properties of the application URL at any point in time. The object exposes the same URL properties as with the [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) API, but as *live* properties that can be observed as navigation happens, and modified to initiate navigation - all using the [Observer API](#the-observer-api).
+
+```js
+console.log(document.state.url) // { hash, host, hostname, href, origin, password, pathname, port, protocol, search, searchParams, username }
+```
+
+```js
+Observer.observe(document.state.url, 'hash', e => {
+    console.log(document.state.url.hash === e.value); // true
+});
+```
+
+```js
+// Navigates to "/login#form" as if a link was clicked
+document.addEventListener('synthetic-navigation', e => {
+    Observer.set(document.state.url, 'href', '/login#form');
+});
+
+// Or...
+document.addEventListener('synthetic-navigation', e => {
+    Observer.set(document.state.url, { pathname: '/login', hash: '#form' });
+});
+
+console.log(document.state.url.hash); // #form
+```
+
+There is also the *convenience* `query` property that offers the URL parameters as a *live* object.
+
+```js
+// For URL: http://localhost:3000/login?as=student
+console.log(document.state.url.query.as) // student
+
+// Re-rewrite the URL and initiate navigation by simply modifying a query parameter
+document.addEventListener('synthetic-navigation', e => {
+    Observer.set(document.state.url.query, 'as', 'business');
+});
+```
+
+```html
+<script type="subscript">
+ let { query: { as: role } } = document.state.url;
+ document.title = 'Login as ' + role;
+</script>
+```
+
 ### Requests and Responses
 
-On each request, the event object passed to route handlers exposes the incoming request as `event.request`. This is an instance of `event.Request` - an extension of the [WHATWG Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) class. The event object also exposes `event.Response` - an extension of the [WHATWG Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) class, for returning instance-based responses.
+On each request, the event object passed to route handlers exposes the incoming request as `event.request`. This is an instance of `event.Request` - an extension of the [WHATWG Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) class. The event object also exposes `event.Response` - an extension of the [WHATWG Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) class, for returning instance-based responses. You enjoy routing that is based on standard interfaces!
 
-Now, routes in Webflo can be designed for different types of request/response scenarios. Webflo does the heavy lifting on each request/response flow!
+Routes in Webflo can be designed for different types of request/response scenarios. Here are some important ones:
 
 #### Scenario 1: Static File Requests and Responses
 
 Static file requests like `http://localhost:3000/logo.png` are expected to get a file response. These requests are automatically handled by Webflo when `next()`ed forward by route handlers, or where there are no route handlers.
-+ On the server, Webflo serves files from the `public` directory. File conents along with the appropriate headers like [`Content-Type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type), [`Content-Length`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length), etc. are returned as an instance of `event.Response`. Where a request has an [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header set (e.g. `gzip`, `br`) and there exists a matching *compressed version* of the said file on the file system (e.g. `./public/logo.png.gz`, `./public/logo.png.br`), the compressed version is served and the appropriate [`Content-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) response header is set.
++ On the server, Webflo serves files from the `public` directory. File contents along with the appropriate headers like [`Content-Type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type), [`Content-Length`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length), etc. are returned as an instance of `event.Response`. Where a request has an [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header set (e.g. `gzip`, `br`) and there exists a matching *compressed version* of the said file on the file system (e.g. `./public/logo.png.gz`, `./public/logo.png.br`), the compressed version is served and the appropriate [`Content-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) response header is set.
 + On the client, Webflo serves static files from the network, or from the application cache, where available.
 
 #### Scenario 2: API Requests and Responses
@@ -1120,111 +1232,121 @@ Webflo also offers a *convenience* method.
 
 ```js
 console.log(event.request.headers.cookies); // { 'Cookie-1': 'cookie-val', 'Cookie-2': 'cookie2-val' };
-````
+```
 
 ### Webflo Applications
 
-In just a few concepts, Webflo comes ready for any type of application! Now, additional details of a Webflo app - depending on the type - are covered in the following sections.
+In just a few concepts, Webflo comes ready for any type of application!
 
-+ [Application State](#application-state)
 + [Client-Side Applications](#client-side-applications)
++ [Progressive Web Apps](#progressive-web-apps)
 + [API Backends](#api-backends)
 + [Static Sites](#static-sites)
 
-#### Application State
-
-For all things application state, Webflo leverages the [State API](https://github.com/webqit/oohtml#state-api) that's natively available in OOHTML-based documents - both client-side and server-side. This API exposes an application-wide `document.state` object and a per-element `element.state` object. And these are *live* read/write objects that can be observed for property changes using the [Observer API](https://github.com/webqit/observer). It comes off as the simplest approach to state and reactivity!
-
-> **Note**
-> <br>The State API is not available when the OOHTML support level in config is switched away from `full` and `scripting`.
-
-##### The `document.state.data` Object
-
-This property represents the data obtained from route handers on each navigation. Webflo simply exposes this data and lets the page's [rendering logic](#client-and-server-side-rendering), or other parts of the application, take over.
-
-```js
-Observer.observe(document.state, 'data', e => {
-    console.log('Current page data is: ', e.value);
-});
-```
-
-##### The `document.state.url` Object
-
-This is a *live* object that reperesents the properties of the application URL at any point in time. The object exposes the same URL properties as with the [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) API, but as *live* properties that can be observed as navigation happens, and modified to initiate navigation - all using the [Observer API](https://github.com/webqit/observer).
-
-```js
-console.log(document.state.url) // { hash, host, hostname, href, origin, password, pathname, port, protocol, search, searchParams, username }
-```
-
-```js
-Observer.observe(document.state.url, 'hash', e => {
-    console.log(document.state.url.hash === e.value); // true
-});
-```
-
-```js
-// Navigates to "/login#form" as if a link was clicked
-document.addEventListener('synthetic-navigation', e => {
-    Observer.set(document.state.url, 'href', '/login#form');
-});
-
-// Or...
-document.addEventListener('synthetic-navigation', e => {
-    Observer.set(document.state.url, { pathname: '/login', hash: '#form' });
-});
-
-console.log(document.state.url.hash); // #form
-```
-
-There is also the *convenience* `query` property that offers the URL parameters as a *live* object.
-
-```js
-// For URL: http://localhost:3000/login?as=student
-console.log(document.state.url.query.as) // student
-
-// Re-rewrite the URL and initiate navigation by simply modifying a query parameter
-document.addEventListener('synthetic-navigation', e => {
-    Observer.set(document.state.url.query, 'as', 'business');
-});
-```
-
 #### Client-Side Applications
 
-Web pages that embed the Webflo client JS bundle deliver a great user experience.
-+ **First-paint-ready.** On the first page request, you get a [server-rendered](#client-and-server-side-rendering) HTML page that's optimized for the first paint of your application.
-+ **Fluid and app-like.** On being loaded, the state of the application is restored through hydration, and [subsequent navigations](#spa-navigation) are sleek and instant, while performing [Client-Side Rendering](#client-and-server-side-rendering).
+Web pages that embed the Webflo client JS bundle deliver a great user experience. It's simple: the `npm run generate` command does both the building and embedding of the script, or scripts, for the document root, or document roots (in a [Multi Page](#in-a-multi-page-layout) / [Multi SPA](#in-a-multi-spa-layout) layout)!
 
-For these client-side applications, the `npm run generate` command does both the building and embedding of the script for each document root in the application.
+On being loaded, the state of the application is initialized, or is restored through hydration - where [Server-Side Rendering](#client-and-server-side-rendering) was involved to optimize for first paint, and an app-like experience kicks in! For [Single-Page Applications](#in-a-single-page-layout), [Client-Side Rendering](#client-and-server-side-rendering) is performed on each navigation.
 
 ##### SPA Navigation
 
-Unless disabled in [config](#spa_navigation), it is factored-in at build time for the application client JS to be able to automatially figure out when to intercept a navigation event and prevent a full page reload, and when not to. It follows the following rules:
+Unless disabled in config, it is factored-in at build time for the application client JS to be able to automatially figure out when to intercept a navigation event and prevent a full page reload, and when not to. It follows the following rules:
 + When it ascertains that the destination URL is based on the current running `index.html` document in the browser (an SPA architecture), a full page reload is prevented for *soft* navigation. But where the destination URL points out of the current document root (a [Multi SPA](#in-a-multi-spa-layout) architecture), navigation is allowed as a normal page load, and a new page root is loaded.
 + If navigation is initiated with any of the following keys pressed: Meta Key, Alt Key, Shift Key, Ctrl Key, navigation is allowed to work the default way - regardless of the first rule above.
 + If navigation is initiated from a link element that has the `target` attribute, or the `download` attribute, navigation is allowed to work the default way - regardless of the first rule above.
 + If navigation is initiated from a form element that has the `target` attribute, navigation is allowed to work the default way - regardless of the first rule above.
 
-> To entirely disable SPA navigation in config where necessary, run `webflo config client` and follow the prompt.
+<details>
+<summary>Default Config</summary>
+
+> File: `.webqit/webflo/client.json` | Command: `webflo config client spa_navigation=TRUE`
+
+```json
+{ "spa_navigation": true }
+```
+<details>
 
 ##### SPA State
 
-In addition to [the universal concept of state](#application-state) of a Webflo application, state on the client side also includes the following aspects of the client-side lifecycle that can be used to provide visual cues on the UI.
+On the client side of a Webflo application, [the idea of state](#the-idea-of-state) also includes the following aspects of the client-side lifecycle that can be used to provide visual cues on the UI.
   
 ###### The `document.state.network` Object
 
 This is a *live* object that exposes the network activity and network state of the application.
 
 ```js
-console.log(document.state.network) // { requesting, remote, error, redirecting, online, }
+console.log(document.state.network) // { requesting, remote, error, redirecting, connectivity, }
 ```
 
 + **`network.requesting`: `null|Object`** - This property tells when a request is ongoing, in which case it exposes the `params` object used to initiate the request.
+  
+  On the UI, this could be used to hide a menu drawer that may have been open.
+  
+  ```html
+  <menu-drawer>
+      <script type="subscript">
+      let { network: { requesting } } = document.state;
+      if (requesting) {
+          $(this).attr('open', false);
+      }
+      </script>
+  </menu-drawer>
+  ```
+  
 + **`network.remote`: `null|String`** - This property tells when a remote request is ongoing - usually the same navigation requests as at `network.requesting`, but when not handled by any client-side route handlers, or when `next()`ed to this point by route handlers. The `remote` property also goes live when a route handler calls the special `fetch()` function that they recieve on their fourth parameter.
+  
+  On the UI, this could be used to show/hide a spinner, or progress bar, to provide a visual cue.
+  
+  ```html
+  <progress-bar>
+      <script type="subscript">
+      let { network: { remote } } = document.state;
+      $(this).attr('hidden', !remote);
+      </script>
+  </progress-bar>
+  ```
+  
 + **`network.error`: `null|Error`** - This property tells when a request is *errored* in which case it contains an `Error` instance of the error. For requests that can be retried, the `Error` instance also has a custom `retry()` method.
+  
+  On the UI, this could be used to show/hide cute error elements.
+  
+  ```html
+  <nice-error>
+      <script type="subscript">
+      let { network: { error } } = document.state;
+      $(this).attr('hidden', !error);
+      </script>
+  </nice-error>
+  ```
+  
 + **`network.redirecting`: `null|String`** - This property tells when a client-side redirect is ongoing - see [Scenario 4: Single Page Navigation Requests and Responses](#scenario-4-single-page-navigation-requests-and-responses) - in which case it exposes the destination URL.
-+ **`network.online`: `Boolean`** - This property tells of [the browser's ability to connect to the network](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine).
-
-Now, being a *live* object means that `document.state.network` can be observed using the [Observer API](https://github.com/webqit/observer).
+  
+  On the UI, this could be used to prevent further interactions with the outgoing page.
+  
+  ```html
+  <body>
+      <script type="subscript">
+      let { network: { redirecting } } = document.state;
+      $(this).css(redirecting ? { pointerEvents: 'none', filter: 'blur(2)' } : { pointerEvents: 'auto', filter: 'blur(0)' });
+      </script>
+  </body>
+  ```
+  
++ **`network.connectivity`: `String`** - This property tells of [the browser's ability to connect to the network](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine): `online`, `offline`.
+  
+  On the UI, this could be used to show/hide a connectivity status.
+  
+  ```html
+  <body>
+      <script type="subscript">
+      let { network: { connectivity } } = document.state;
+      $(this).attr( 'connectivity', connectivity });
+      </script>
+  </body>
+  ```
+  
+Here are some additional examples with the [Observer API](#the-observer-api).
 
 ```js
 // Visualize the network state
@@ -1238,12 +1360,12 @@ Observer.observe(document.state.network, onlineVisualizer);
 ```
 
 ```js
-// Visualize the 'online' property
-let onlineVisualizer = e => {
-    console.log('You are ', e.value ? 'online' : 'offline');
+// Visualize the 'connectivity' property
+let connectivityVisualizer = e => {
+    console.log('You are ', e.value);
 };
-Observer.observe(document.state.network, 'online', onlineVisualizer);
-// Or: Observer.observe(document.state, [ ['network', 'online'] ], onlineVisualizer);
+Observer.observe(document.state.network, 'connectivity', connectivityVisualizer);
+// Or: Observer.observe(document.state, [ ['network', 'connectivity'] ], connectivityeVisualizer);
 ```
 
 ```js
@@ -1258,26 +1380,124 @@ Observer.observe(document.state.network, 'error', e => {
 });
 ```
 
-###### Form Actions
+##### Form Actions
+
+When navigation occurs [via form submissions](#scenario-4-single-page-navigation-requests-and-responses), the form element and the submit button are made to go on the *active* state while the request is being processed. For both of these elements, the Webflo client simply sets the `element.state.active` to `true` on submission, then `false`, on completion.
+
+```html
+<form method="post">
+    <input name="username" placeholder="Your username..." />
+    <script>
+    $(this).css(this.state.active ? { pointerEvents: 'none', opacity: 'o.5' } : { pointerEvents: 'auto', opacity: '1' });
+    </script>
+</form>
+```
+
+One more thing: HTML forms can only accept two HTTP methods on their `method` attribute: `GET`, `POST`! The same constraint exists on the equivalent `formmethod` attribue in submit buttons. You are able to overcome this in Webflo by using alternative `data-` attributes: `data-method`, `data-formmethod`, respectively.
+
+```html
+<form data-method="patch">
+    <input name="price" placeholder="Enter new price..." />
+</form>
+```
+
+#### Progressive Web Apps
 
-When navigation occurs [via form submissions](#scenario-4-single-page-navigation-requests-and-responses), the form element and the submit button are made to go on the *active* state while the request is processed. For both of these elements, the Webflo client simply sets the `element.state.active` to `true` on submission, then `false`, on completion.
+Webflo client-side applications are intended to provide an app-like-first experience. So unless disabled in config, a [Service Worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) is built as part of your application on running the `npm run generate` command. You may define [route handlers in the `/worker` directory](#handler-functions-and-layout) of your application, and these will be built into the service worker to handle Same-Origin requests of the application. Where there are no *worker* handlers, or where these forward incoming requests, requests are fetched, either from the cache, or from the network, depending on the fetching strategy built into the Service Worker.
 
-##### Service Workers
+<details>
+<summary>Default Config</summary>
 
-Webflo client-side applications are intended to provide an app-like-first experience. So unless disabled in [config](#enable_service_worker), a [Service Worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) is built as part of your application on running the `npm run generate` command. You may define [route handlers in the `/worker` directory](#handler-functions-and-layout) of your application, and these will be built into the service worker to handle Same-Origin requests of the application. Where there are no *worker* handlers, or where they forward these requests, the request is fetched, either from the cache, or from the network, depending on the fetching strategy built into the Service Worker.
+> File: `.webqit/webflo/client.json` | Command: `webflo config client enable_service_worker=TRUE`
 
-###### Fetching Strategy
+```json
+{ "enable_service_worker": true }
+```
+<details>
+
+##### Fetching Strategy
+
++ **Network First** - This strategy tells the Service Worker to always attempt fetching from the network first for given resources, before fetching from the cache. On every successful network fetch, a copy of the response is saved to the cache for next time. (This is good for resources that need to be fresh to the user on a "best effort" basis.) Unless changed, this is Webflo's default fetching strategy. When not the default strategy, a list of specific URLs that should be fetched this way can be configured.
+    
+    <details>
+    <summary>Default Config</summary>
+
+    > File: `.webqit/webflo/client.json` | Command: `webflo config client default_fetching_strategy=network-first`
+
+    ```json
+    { "default_fetching_strategy": "network-first" }
+    ```
 
-+ **Network First** - This strategy tells the Service Worker to always attempt fetching from the network first for given resources, before fetching from the cache. On every successful network fetch, a copy of the response is saved to the cache for next time. (This is good for resources that need to be fresh to the user on a "best effort" basis.) Unless [changed](#default_fetching_strategy), this is Webflo's default fetching strategy. When not the default strategy, a list of specific URLs that should be fetched this way can be [configured](#network_first_urls).
-+ **Cache First** - This strategy tells the Service Worker to always attempt fetching from the cache first for given resources, before fetching from the network. After serving a cached response, or where not found in cache, a network fetch happens and a copy of the response is saved to the cache for next time. (This is good for resources that do not critially need to be fresh to the user.) When not the default strategy, a list of specific URLs that should be fetched this way can be [configured](#cache_first_urls).
-+ **Network Only** - This strategy tells the Service Worker to always fetch given resources from the network only. They are simply not available when offline. (This is good for resources that critially need to be fresh to the user.) When not the default strategy, a list of specific URLs that should be fetched this way can be [configured](#network_only_urls).
-+ **Cache Only** - This strategy tells the Service Worker to always fetch given resources from the cache only. (This is good for resources that do not change often.) When not the default strategy, a list of specific URLs that should be fetched this way can be [configured](#cache_only_urls). The listed resources are pre-cached ahead of when they'll be needed - and are served from the cache each time. (Pre-caching happens on the one-time `install` event of the Service Worker.)
+    *To list specific URLs...*
+
+    ```json
+    { "network_first_urls": [ "/logo.png" ] }
+    ```
+    <details>
+
++ **Cache First** - This strategy tells the Service Worker to always attempt fetching from the cache first for given resources, before fetching from the network. After serving a cached response, or where not found in cache, a network fetch happens and a copy of the response is saved to the cache for next time. (This is good for resources that do not critially need to be fresh to the user.) When not the default strategy, a list of specific URLs that should be fetched this way can be configured.
+    
+    <details>
+    <summary>Default Config</summary>
+
+    > File: `.webqit/webflo/client.json` | Command: `webflo config client default_fetching_strategy=cache-first`
+
+    ```json
+    { "default_fetching_strategy": "cache-first" }
+    ```
+
+    *To list specific URLs...*
+
+    ```json
+    { "cache_first_urls": [ "/logo.png" ] }
+    ```
+    <details>
+
++ **Network Only** - This strategy tells the Service Worker to always fetch given resources from the network only. They are simply not available when offline. (This is good for resources that critially need to be fresh to the user.) When not the default strategy, a list of specific URLs that should be fetched this way can be configured.
+    
+    <details>
+    <summary>Default Config</summary>
+
+    > File: `.webqit/webflo/client.json` | Command: `webflo config client default_fetching_strategy=network-only`
+
+    ```json
+    { "default_fetching_strategy": "network-only" }
+    ```
+
+    *To list specific URLs...*
+
+    ```json
+    { "network_only_urls": [ "/logo.png" ] }
+    ```
+    <details>
+
++ **Cache Only** - This strategy tells the Service Worker to always fetch given resources from the cache only. (This is good for resources that do not change often.) When not the default strategy, a list of specific URLs that should be fetched this way can be configured. The listed resources are pre-cached ahead of when they'll be needed - and are served from the cache each time. (Pre-caching happens on the one-time `install` event of the Service Worker.)
+
+    <details>
+    <summary>Default Config</summary>
+
+    > File: `.webqit/webflo/client.json` | Command: `webflo config client default_fetching_strategy=cache-only`
+
+    ```json
+    { "default_fetching_strategy": "cache-only" }
+    ```
+
+    *To list specific URLs...*
+
+    ```json
+    { "cache_only_urls": [ "/logo.png" ] }
+    ```
+    <details>
 
 In all cases above, the convention for specifying URLs for a strategy accepts [URL patterns](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) - against which URLs can be matched on the fly. For example, to place all files in an `/image` directory (and subdirectories) on the *Cache First* strategy, the pattern `/image/*` can be used. To place all `.svg` files in an `/icons` directory (including subdirectories) on the *Cache Only* strategy, the pattern `/icons/*.svg` can be used. (Specifically for the *Cache Only* strategy, patterns are resolved at Service Worker build-time, and each pattern must match, at least, a file.)
 
-###### Cross-Thread Communications
+```json
+{ "cache_only_urls": [ "/icons/*.svg" ] }
+```
+
+##### Cross-Thread Communications
 
-A couple APIs exists in browsers for establishing a two-way communication channel between a page and its service worker, for firing UI Notifications from either ends, and for implementing Push Notifications. Webflo offers to simply this with a unifying set of conventions:
+A couple APIs exists in browsers for establishing a two-way communication channel between a page and its Service Worker, for firing UI Notifications from either ends, and for implementing Push Notifications. Webflo offers to simply this with a unifying set of conventions:
 
 + The `workport` API - an object with simple methods for working with *cross-thread* messages, UI and Push Notifications.
   
@@ -1417,7 +1637,7 @@ export default function(event, context, next) {
 }
 ```
 
-You are always able to lay out your route handlers in the structure for a formalized REST API.
+You are always able to lay out your route handlers in the structure for a formal REST API.
 
 ```shell
 server
@@ -1426,15 +1646,15 @@ server
  └── api/v1/products/index.js
 ```
 
-And if you will partition your backend for both page routes and a formalized REST API...
+And if you will partition your backend for both page routes and a formal REST API...
 
 ```shell
 server
  ├── index.js                  ──┐
- ├── cart/index.js               ├── Page Routes
+ ├── cart/index.js               ├─ Page Routes
  ├── products/index.js         ──┘
  ├── api/v1/index.js           ──┐
- ├── api/v1/orders/index.js      ├── REST API
+ ├── api/v1/orders/index.js      ├─ REST API
  └── api/v1/products/index.js  ──┘
 ```
 
@@ -1485,7 +1705,46 @@ You have a static site!
 
 ### Webflo Config
 
-> TODO
+Webflo comes *convention-first*! But it is entirely configurable for when you need it! The easiest way to do this is to run the command `webflo config` and follow the walkthrough. To simply get an overview, use the command `webflo config help`, and all commands and their description are shown.
+
+## Technology Stack
+
+Webflo applications are often built on/with the following technologies.
+
+### OOHTML
+
+[OOHTML](https://github.com/webqit/oohtml) is a proposed set of new features for HTML that makes it fun to hand-author your UI! Within OOHTML are [HTML Modules](https://github.com/webqit/oohtml#html-modules) and [HTML Imports](https://github.com/webqit/oohtml#html-imports), [Reactive Scripts](https://github.com/webqit/oohtml#subscript) and more!
+
+Webflo natively supports OOHTML in full! But it is also possible to switch this to none, or to partial support - when specific features aren't needed anywhere in your application. Server-side and client-side support for OOHTML exist independently. This is good when, for example, your application places more importance on SSR, and less on CSR, in which case a reduced support for OOHTML can reduce the overall client JS bundle size.
+
+<details>
+<summary>Default Config</summary>
+
+> File: `.webqit/webflo/client.json` | Command: `webflo config client oohtml_support=full`
+
+> File: `.webqit/webflo/client.json` | Command: `webflo config server oohtml_support=full`
+
+```json
+{ "oohtml_support": "full" }
+```
+
+*Values: `full`, `namespacing`, `scripting`, `templating`, `none` - See [details at OOHTML SSR](https://github.com/webqit/oohtml-ssr#options)*
+<details>
+
+
+### OOHTML SSR
+
+[OOHTML SSR](https://github.com/webqit/oohtml-ssr) is a server-side DOM implementation with native support for OOHTML. This is internally used by Webflo as the Server-Side Rendering engine, and it it what gives Webflo its native support for OOHTML.
+
+### OOHTML CLI
+
+[OOHTML CLI](https://github.com/webqit/oohtml-cli) is a small Command Line utility that automates certain aspects of hand-authored OOHTML-based documents.
+
+### The Observer API
+
+[The Observer API](https://github.com/webqit/observer) is a simple set of functions for intercepting and observing JavaScript objects and arrays. (Reflection, Interception, and Events.)
+
+This is part of OOHTML's reactivity system, and it is made available on OOHTML-based documents as `window.WebQit.Observer`.
 
 ## Getting Started
 
@@ -1503,13 +1762,3 @@ All forms of contributions and PR are welcome! To report bugs or request feature
 ## License
 
 MIT.
-
-...
-
-## Getting Involved
-
-All forms of contributions and PR are welcome! To report bugs or request features, please submit an [issue](https://github.com/webqit/webflo/issues).
-
-## License
-
-MIT.

package/package.json

@@ -12,7 +12,7 @@
     "vanila-javascript"
   ],
   "homepage": "https://webqit.io/tooling/webflo",
-  "version": "0.11.5",
+  "version": "0.11.8",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/runtime-pi/client/Runtime.js

@@ -118,7 +118,7 @@ export default class Runtime {
 				return params;
 			}, {});
 			// We support method hacking
-			submitParams.method = (submitter && submitter.dataset.method) || form.dataset.method || submitParams.method;
+			submitParams.method = (submitter && submitter.dataset.formmethod) || form.dataset.method || submitParams.method;
 			submitParams.submitter = submitter;
 			// ---------------
 			var actionEl = window.document.createElement('a');
@@ -152,8 +152,8 @@ export default class Runtime {
 		// -----------------------
 		// Initialize network
 		Observer.set(this, 'network', {});
-		window.addEventListener('online', () => Observer.set(this.network, 'online', navigator.onLine));
-		window.addEventListener('offline', () => Observer.set(this.network, 'online', navigator.onLine));
+		window.addEventListener('online', () => Observer.set(this.network, 'connectivity', 'online'));
+		window.addEventListener('offline', () => Observer.set(this.network, 'connectivity', 'offline'));
 
 		// -----------------------
 		// Service Worker && COMM