@webqit/webflo 0.11.18 → 0.11.21

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-present, Yuxi (Evan) You
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -7,41 +7,75 @@
 
 <!-- /BADGES -->
 
-Webflo is a universal *web*, *mobile*, and *API backend* framework built to solve for the underrated `.html` + `.css` + `.js` stack! This has been written specifically to draw directly on the plain old stack at the language level - to facilitate building web-native applications!
+Webflo is a universal *web*, *mobile*, and *API backend* framework built to solve for the underrated `.html` + `.css` + `.js` stack! This has been written  to facilitate working and thinking in vanilla HTML, CSS and JavaScript - for building more authentic, web-native applications!
 
-Ok, we've put all of that up for a straight read!
+Ok, we've put all of that up for a 10min straight read!
 
-> **Note**
-> <br>Depending on your current framework background, the hardest part of Webflo might be having to break ties with something that isn't conventional to the `.html` + `.css` + `.js` stack: all of that JSX, CSS-in-JS, etc.!
+## The Catch...
+
+The overall motivation for Webflo is to facilitate *web-native* development; to be the cool framework that draws on native web platform features - including new fascinating features we're proposing as standards! So, it gets a little bit "futuristic"! You thus have to be excited about taking a plunge to happily meet Webflo!
+
+## The Wins...
+
+Much of what eludes the web today...
+
++ An overarching HTML-first thinking!
++ The build-less, vanilla advantage!
++ (Futuristic) Native reactivity!
++ (Futuristic) Minimalist-JS philosophy!
++ Universal-everything!
 
-## Documentation 
+(Details just ahead!)
+
+## Documentation
+
+All of Webflo in a 10-min read!
 
 + [Overview](#overview)
 + [Installation](#installation)
 + [Concepts](#concepts)
+  + [Handler Functions and Layout](#handler-functions-and-layout)
+  + [Step Functions and Workflows](#step-functions-and-workflows)
+  + [Pages, Layout and Templating](#pages-layout-and-templating)
+  + [Client and Server-Side Rendering](#client-and-server-side-rendering)
+  + [Requests and Responses](#requests-and-responses)
 + [Webflo Applications](#webflo-applications)
+  + [Client-Side Applications](#client-side-applications)
+  + [Progressive Web Apps](#progressive-web-apps)
+  + [API Backends](#api-backends)
+  + [Static Sites](#static-sites)
 + [Webflo Config](#webflo-config)
-+ [Technology Stack](#technology-stack)
++ [Webflo Tooling](#webflo-tooling)
+  + [OOHTML](#oohtml)
+  + [OOHTML SSR](#oohtml-ssr)
+  + [OOHTML CLI](#oohtml-cli)
+  + [The Observer API](#the-observer-api)
 + [Getting Started](#getting-started)
 + [Getting Involved](#getting-involved)
 
 ## Overview
 
 <details>
- <summary><b>Build <i>anything</i></b> - from as basic as a static <code>index.html</code> page to as rich as a universal app that's either a <i>Multi Page Application (MPA)</i>, <i>Single Page Application (SPA)</i>, or a hybrid of these, implementing <i>Server Side Rendering (SSR)</i>, <i>Client Side Rendering (CSR)</i>, or a hybrid of these, offline and <i>PWA</i> capabilities, etc. - this time, <i>without loosing the vanilla advantage</i>!
+ <summary><b>Build <i>anything</i></b> - from as basic as a static <code>index.html</code> page to as rich as a universal app that's either a <i>Multi Page Application (MPA)</i>, <i>Single Page Application (SPA)</i>, or a hybrid of both, implementing <i>Server Side Rendering (SSR)</i>, <i>Client Side Rendering (CSR)</i>, or a hybrid of both, offline and <i>PWA</i> capabilities, etc. - this time, <i>without loosing the vanilla advantage</i>!
 </summary>
  
 Here's a glimpse of your Webflo app.
 
-For when your application has a Server side.
+For when your application is a static site, or has static files to serve.
 + The `public` directory for static files.
-+ The `server` directory for server-side routing. (i.e. dynamic request handling on the server - in the case of Multi Page Applications, API backends, etc.)
 
   ```shell
   my-app
-    ├── server/index.js
     └── public/logo.png
   ```
+
+For when your application has a Server side.
++ The `server` directory for server-side routing. (i.e. dynamic request handling on the server - in the case of Multi Page Applications, API backends, etc.)
+
+  ```shell
+  my-app
+    └── server/index.js
+  ```
   
   And a typical `index.js` route handler has the following anatomy.
 
@@ -100,7 +134,7 @@ For when your application has a Client side.
     └── worker/index.js
   ```
   
-  And in both cases, a typical `index.js` route handler has the following anatomy.
+  And in both cases, a typical `index.js` route handler has the following anatomy. (Same with server-side handlers.)
 
   ```js
   /**
@@ -165,7 +199,7 @@ With [npm available on your terminal](https://docs.npmjs.com/downloading-and-ins
 > System Requirements: Node.js 14.0 or later
 
 ```shell
-$ npm i @webqit/webflo
+npm i @webqit/webflo
 ```
 
 The installation automatically creates a `package.json` file at project root, containing `@webqit/webflo` as a project dependency.
@@ -385,7 +419,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.
+We get a step-based workflow that helps to decomplicate routing and lets us scale horizontally as our application grows larger.
 
 <details>
 <summary>More details...</summary>
@@ -525,7 +559,7 @@ So, above, should our handler receive static file requests like `http://localhos
 
 ```shell
 my-app
-  ├── server/index.js ------------------------- http://localhost:3000, http://localhost:3000/prodcuts, http://localhost:3000/prodcuts/stickers, etc
+  ├── server/index.js ------------------------- http://localhost:3000, http://localhost:3000/products, http://localhost:3000/products/stickers, etc
   └── public/logo.png ------------------------- http://localhost:3000/logo.png
 ```
 
@@ -567,7 +601,7 @@ Now we get the following handler-to-URL mapping for our application:
 ```shell
 my-app
   ├── worker/index.js ------------------------- http://localhost:3000/about, http://localhost:3000/logo.png
-  ├── server/index.js ------------------------- http://localhost:3000, http://localhost:3000/prodcuts, http://localhost:3000/prodcuts/stickers, etc
+  ├── server/index.js ------------------------- http://localhost:3000, http://localhost:3000/products, http://localhost:3000/products/stickers, etc
   └── public/logo.png ------------------------- http://localhost:3000/logo.png
 ```
 
@@ -606,7 +640,7 @@ Our overall handler-to-URL mapping for this application now becomes:
 my-app
   ├── client/index.js ------------------------- http://localhost:3000/login
   ├── worker/index.js ------------------------- http://localhost:3000/about, http://localhost:3000/logo.png
-  ├── server/index.js ------------------------- http://localhost:3000, http://localhost:3000/prodcuts, http://localhost:3000/prodcuts/stickers, etc
+  ├── server/index.js ------------------------- http://localhost:3000, http://localhost:3000/products, http://localhost:3000/products/stickers, etc
   └── public/logo.png ------------------------- http://localhost:3000/logo.png
 ```
 
@@ -692,7 +726,7 @@ In a Multi Page Application (with an individual-page architecture), each page is
 my-app
   └── public
       ├── about/index.html ------------------------- <!DOCTYPE html>
-      ├── prodcuts/index.html ---------------------- <!DOCTYPE html>
+      ├── products/index.html ---------------------- <!DOCTYPE html>
       ├── index.html ------------------------------- <!DOCTYPE html>
       ├── header.html ------------------------------ <header></header> <!-- To appear at top of each index.html page -->
       └── footer.html ------------------------------ <footer></footer> <!-- To appear at bottom of each index.html page -->
@@ -704,7 +738,7 @@ In a Single Page Application, each page is the same `index.html` document, and i
 my-app
   └── public
       ├── about/main.html -------------------------- <main></main> <!-- To appear at main area of index.html -->
-      ├── prodcuts/main.html ----------------------- <main></main> <!-- To appear at main area of index.html -->
+      ├── products/main.html ----------------------- <main></main> <!-- To appear at main area of index.html -->
       ├── main.html -------------------------------- <main></main> <!-- To appear at main area of index.html -->
       └── index.html ------------------------------- <!DOCTYPE html>
 ```
@@ -876,7 +910,7 @@ It's all a *layout* thing, so a hybrid of the two architectures above is possibl
 my-app
   └── public
       ├── about/index.html ------------------------- <!DOCTYPE html> <!-- Document root 1 -->
-      ├── prodcuts
+      ├── products
       │     ├── free/main.html --------------------------- <main></main> <!-- To appear at main area of document root 2 -->
       │     ├── paid/main.html --------------------------- <main></main> <!-- To appear at main area of document root 2 -->
       │     ├── main.html -------------------------------- <main></main> <!-- To appear at main area of document root 2 -->
@@ -886,7 +920,7 @@ my-app
       └── footer.html ------------------------------ <footer></footer> <!-- To appear at bottom of each document root -->
 ```
 
-The above gives us three document roots: `/index.html`, `/about/index.html`, `/prodcuts/index.html`. The `/prodcuts` route doubles as a Single Page Application such that visiting the `/prodcuts` route loads the document root `/prodcuts/index.html` and lets Webflo SPA routing determine which of `/prodcuts/main.html`, `/prodcuts/free/main.html`, `/prodcuts/paid/main.html` is imported on a given URL.
+The above gives us three document roots: `/index.html`, `/about/index.html`, `/products/index.html`. The `/products` route doubles as a Single Page Application such that visiting the `/products` route loads the document root `/products/index.html` and lets Webflo SPA routing determine which of `/products/main.html`, `/products/free/main.html`, `/products/paid/main.html` is imported on a given URL.
 
 Webflo ensures that only the amount of JavaScript for a document root is actually loaded! So, above, a common JavaScript build is shared across the three document roots alongside an often tiny root-specific build.
 
@@ -1490,7 +1524,7 @@ On the UI, this could be used to show/hide cute error elements.
 
 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.
 
-On the UI, this could be used to prevent further interactions with the outgoing page.
+On the UI, this could be used to mark the current page as stale and prevent further interactions.
 
 ```html
 <body>
@@ -1526,13 +1560,13 @@ Here are some additional examples with the [Observer API](#the-observer-api).
 
 ```js
 // Visualize the network state
-let onlineVisualizer = changes => {
+let networkVisualizer = changes => {
     changes.forEach(e => {
         console.log(e.name, ':', e.value);
     });
 };
-Observer.observe(document.state.network, onlineVisualizer);
-// Or: Observer.observe(document, [ ['state', 'network'] ], onlineVisualizer, { subtree: true });
+Observer.observe(document.state.network, networkVisualizer);
+// Or: Observer.observe(document, [ ['state', 'network'] ], networkVisualizer, { subtree: true });
 ```
 </details>
 
@@ -1700,7 +1734,7 @@ This strategy tells the Service Worker to always fetch given resources from the
 </details>
 </details>
 
-In all cases above, the convention for specifying URLs for a strategy accepts an [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.)
+In all cases above, the convention for specifying URLs for a strategy accepts an [URL pattern](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.)
 
 <details>
 <summary>Example...</summary>
@@ -1716,7 +1750,7 @@ A couple APIs exists in browsers for establishing a two-way communication channe
 
 ###### The `workport` API
 
-This is an object with simple methods for working with *cross-thread* messages, UI and Push Notifications.
+This is an object with simple methods for working with *cross-thread* messages, UI Notifications, and Push Notifications.
 
 On both the client and worker side of your application, the `workport` object is accessible from route handlers as `this.runtime.workport`.
 
@@ -1805,12 +1839,12 @@ workport.nofitications.fire(title, options).then(event => {
 </details>
 
 <details>
-<summary>Method: <code>.nofitications.listen()</code></summary>
+<summary>Method: <code>.nofitications.handle()</code></summary>
 
-The `.nofitications.listen()` method (in Service-Workers) is used for listening to [`notificationclick`](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/notificationclick_event) events. (Handlers are called each time a notification is clicked.)
+The `.nofitications.handle()` method (in Service-Workers) is used for handling [`notificationclick`](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/notificationclick_event) events. (Handlers are called each time a notification is clicked.)
 
 ```js
-workport.nofitications.listen(event => {
+workport.nofitications.handle(event => {
     console.log(event.action);
 });
 ```
@@ -1973,10 +2007,15 @@ A simple tool, like [`staticgen`](https://github.com/tj/staticgen), or the basic
 
 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 Tooling
 
 Webflo applications are often built on/with the following technologies.
 
++ [OOHTML](#oohtml)
++ [OOHTML SSR](#oohtml-ssr)
++ [OOHTML CLI](#oohtml-cli)
++ [The Observer API](#the-observer-api)
+
 ### OOHTML
 
 [OOHTML](https://github.com/webqit/oohtml) is a proposed set of new features for HTML that makes it fun to hand-author your HTML documents! 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!

package/package.json

@@ -12,7 +12,7 @@
     "vanila-javascript"
   ],
   "homepage": "https://webqit.io/tooling/webflo",
-  "version": "0.11.18",
+  "version": "0.11.21",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@octokit/webhooks": "^7.15.1",
-    "@webqit/backpack": "^0.1.0",
+    "@webqit/backpack": "^0.1.2",
     "@webqit/oohtml-ssr": "^1.1.0",
     "@webqit/util": "^0.8.9",
     "client-sessions": "^0.8.0",

package/src/runtime-pi/Router.js

@@ -41,12 +41,13 @@ export default class Router {
     async route(method, event, arg, _default, remoteFetch = null) {
 
         const $this = this;
+        const $runtime = this.cx.runtime;
 
         // ----------------
         // The loop
         // ----------------
         const next = async function(thisTick) {
-            const thisContext = { };
+            const thisContext = { runtime: $runtime };
             if (!thisTick.trail || thisTick.trail.length < thisTick.destination.length) {
                 thisTick = await $this.readTick(thisTick);
                 // -------------

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

@@ -112,8 +112,8 @@ export default class Runtime {
 		// Capture all form-submit
 		// and fire to this router.
 		window.addEventListener('submit', e => {
-			var form = e.target.closest('form'), submitter = e.submitter;
-			var submitParams = [ 'action', 'enctype', 'method', 'noValidate', 'target' ].reduce((params, prop) => {
+			const form = e.target.closest('form'), submitter = e.submitter;
+			const submitParams = [ 'action', 'enctype', 'method', 'noValidate', 'target' ].reduce((params, prop) => {
 				params[prop] = submitter && submitter.hasAttribute(`form${prop.toLowerCase()}`) ? submitter[`form${_toTitle(prop)}`] : form[prop];
 				return params;
 			}, {});

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

@@ -15,4 +15,9 @@ export async function start(clientCallback = null) {
     return new Runtime(Context.create(cx), ( ...args ) => {
         return clientCallback ? clientCallback( ...args.concat( defaultClientCallback ) ) : defaultClientCallback( ...args );
     });
-}
+}
+
+/**
+ * @APIS
+ */
+export * as APIS from './Runtime.js';

package/src/runtime-pi/client/worker/Worker.js

@@ -3,9 +3,21 @@
  * @imports
  */
 import { _any } from '@webqit/util/arr/index.js';
-import { HttpEvent, Request, Response, Observer } from '../Runtime.js';
 import { urlPattern } from '../../util.js';
+import { HttpEvent, Request, Response, Observer } from '../Runtime.js';
 import Workport from './Workport.js';
+export {
+	URL,
+	FormData,
+	ReadableStream,
+	RequestHeaders,
+	ResponseHeaders,
+	Request,
+	Response,
+	fetch,
+	HttpEvent,
+	Observer,
+} from '../Runtime.js';
 
 /**
  * ---------------------------
@@ -71,6 +83,14 @@ export default class Worker {
 			}) );
 		});
 
+		// ---------------
+        Observer.set(this, 'location', {});
+        Observer.set(this, 'network', {});
+        // ---------------
+		Observer.observe(this.network, es => {
+			//console.log('//////////', ...es.map(e => `${e.name}: ${e.value}`))
+		});
+
 		// -------------
 		// ONFETCH
 		self.addEventListener('fetch', event => {
@@ -114,22 +134,10 @@ export default class Worker {
 				}
 			}
 		});
-		workport.notifications.listen(async evt => {
-			let client = this.clients.get('*');
-			client.alert && await client.alert(evt);
-		});
 		workport.push.listen(async evt => {
 			let client = this.clients.get('*');
 			client.alert && await client.alert(evt);
 		});
-
-		// ---------------
-        Observer.set(this, 'location', {});
-        Observer.set(this, 'network', {});
-        // ---------------
-		Observer.observe(this.network, es => {
-			//console.log('//////////', ...es.map(e => `${e.name}: ${e.value}`))
-		});
 		
 	}
 

package/src/runtime-pi/client/worker/Workport.js

@@ -56,7 +56,7 @@ export default class Workport {
                     notification.addEventListener('close', res);
                 });
             },
-            listen: callback => {
+            handle: callback => {
                 self.addEventListener('notificationclick', callback);
                 return this.notifications;
             },

package/src/runtime-pi/client/worker/index.js

@@ -15,4 +15,9 @@ export async function start(clientCallback = null) {
     return new Worker(Context.create(cx), ( ...args ) => {
         return clientCallback ? clientCallback( ...args.concat( defaultClientCallback ) ) : defaultClientCallback( ...args );
     });
-}
+}
+
+/**
+ * @APIS
+ */
+export * as APIS from './Worker.js';

package/src/runtime-pi/server/index.js

@@ -6,20 +6,6 @@ import Context from './Context.js';
 import RuntimeClient from './RuntimeClient.js';
 import Runtime from './Runtime.js';
 
-/**
- * @desc
- */
-export const desc = {
-    config: {
-        headers: 'Configure automatic http headers.',
-        prerendering: 'Configure prerendering.',
-        redirects: 'Configure automatic redirects.',
-        server: 'Configure server settings.',
-        vhosts: 'Configure virtual hosts.',
-    },
-    start: 'Starts the Webflo server.',
-};
-
 /**
  * @start
  */
@@ -32,10 +18,6 @@ export async function start(clientCallback = null) {
 }
 
 /**
- * @exports
+ * @APIS
  */
-export {
-    Context,
-    RuntimeClient,
-    Runtime,
-}
+export * as APIS from './Runtime.js';