@akc42/app-utils 3.6.3 → 4.0.1

package/README.md

@@ -152,3 +152,102 @@ In doing this it can traverse inside custom elements looking for input elements.
 # switch-path
 
 Changed window location based on parameters provided
+
+# distributed-router
+Distributed Client Side Router for use with a hierarchy of custom components in an Single Page Application
+
+This is a series of javascript modules that you can link together to form a distributed client router system.  It links 
+the browsers URL bar into a chained list of `Routee` objects that process a part of the segmented url.  It takes in a `route` object
+and passes out a `subRoute` object.  These are chained together, the subRoute at one level being fed into route of the next level down
+the hierarchy.  
+
+At the top level is a pair of functions `connectUrl` and `disconnectUrl`.  Which ever element will be your master controller (I generally 
+have a `<main-app>` element which has a `<session-manager>` and `<page-manager>`, both of which are controlling pages.  A `<session-manager>` 
+page doesn't reflect in the url bar at all as the user navigates the sign in process.  But once authorised, the `<page-manager>` takes over
+and controls which page is displayed based on the url.  So it is the `<page-manager>` custom element that calls `connectUrl` in its `connectedCallback`
+function, and `disconnectUrl` in its `disconnectedCallback` function.  `connectUrl` uses a callback function as its only parameter and this callback
+function gets called on url change, passing the top level `route` object.
+
+The next piece in this arrangement is a router.  This is a class called `Route` and is instanciated with one required parameter and one 
+optional parameter. The required parameter is a string containing "/" separated segments, which must either literally match the part of 
+the url, or can start with a ":" character followed by a name, in which case we assume that that part of the url should be interpreted 
+as a parameter.  We process a new `route` (however we receive it - either via the `connectUrl` callback, or being passed into a custom 
+element via a property/attribute) by calling the `routeChange` method, this returns a `route` object which the part of the url segment 
+checked against the specification provdied in the `new Route()` call. `route` has an `active` property to determine if it matched and 
+a `params` property the value of any of the ":" segments. Any queryString is also decoded and placed in the `query` property of objects.
+
+If the `active` propery of a route is false, the subRoute will also have an `active` value of false.  A `query` property is always passed 
+straight through and it is up to the application to decided how and when to use it.
+
+The optional second parameter to the `new Route()` call is a matching string for the previous route up the chain.  It consists of a string
+which contains a single ":" character.  The left of the ":" character is a parameter name, and to the right a parameter value.  The incoming
+route's `params` property must contain the "name" and it must have the value "value" for the subRoute to be active (as well as matching the url).
+
+This is usually used with something like this
+```
+ const topLevel = new Route('/:page');
+ const firstLevel = new Route('/:id', 'page:appointments');
+ connectUrl(route => {
+    const subRoute = topLevel.routeChange(route);
+    if (subRoute.active) {
+      ...
+
+      const subSubRoute = firstLevel.routeChange(subRoute);
+      if (subSubRoute.active) {
+        readDatabaseRecord(subSubRoute.params.id)
+      }
+      ...
+    }
+ });
+ 
+```
+(I have simplified what happens - subRoute would probably be passed in as the `route` property to a custom element which might at some point want
+read a database record based on id).
+
+In this example we only want to read the (lets say) the appointment record from the database if the `<appointment-manager>` element had been activated
+with a url of the form "/appointements/53" and not (say) when the url was "/user/53", when the `<user-manager>` element is in the dom and the `<appointment-manager>` is still in the dom, but not doing anything.  The other obvious question is why not do this:-
+
+```
+ const firstLevel = new Route('/appointments/:id');
+ connectUrl(route => {
+    const subRoute = topLevel.routeChange(route);
+    if (subRoute.active) {
+      ...
+
+      const subSubRoute = firstLevel.routeChange(subRoute);
+      if (subSubRoute.active) {
+        readDatabaseRecord(subSubRoute.params.id)
+      }
+      ...
+    }
+ });
+
+```
+and the answer to that is that I have an element `<route-manager>` which in fact something like `<page-manager>` extends
+which then allows me to do (in `lit-element`s `render` function)
+```
+    ${ {
+      home: html`<app-home></app-home>`,
+      user: html`<app-user managed-page .route=${this.subRoute}></app-user>
+      appointments: html`<app-appointments managed-page .route=${this.subRoute}></app-appointments`
+        }[this.page]
+     }
+```
+
+The route manager users `new Route('/:page')` to translate the incoming `route` to the `page` property.
+
+Internally the `Route` class uses a `route-changed` event which this overall module listens to on the window and this can be used to change the url.
+the `Route` class has three properties that can be set and which can change the url.
+
+- `connection` which if set `true` join the input and output of the route managed by this instance provided only that the route doesn't have any ":" segment,
+   and change the url accordingly.  If set to `false` it will always make the output disconnected.
+- `params` which when set with an object which maps the properties of an active `params` in the `subRoute` will change the url - so for instance in the example
+   above calling `firstlevel.params = {id: 20}` will change the url to `/appointments/20`.
+-  `query` we can set a query set of parameters and these will then change the url to have those query parameters.
+
+Other modules that wish to change the url can do so, but they need to dispatch a `location-altered` event in the window. A helper 
+class `LocationAltered` can generate it for you, so to change the location do:-
+```
+  history.pushState({}, null, '/user/23');
+  window.dispatchEvent(new LocationAltered());
+```

package/location.js

@@ -0,0 +1,171 @@
+/**
+@licence
+    Copyright (c) 2020 Alan Chandler, all rights reserved
+
+    This file is part of Distributed Router.
+
+    Distributed Router is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    Distributed Router is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with Distributed Router.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import {Debug} from './debug.js';
+let routeCallback = null;
+let lastChangedAt;
+let route = null;
+
+const debug = Debug('router');
+
+const dwellTime = () => {
+  return parseInt(localStorage.getItem('dwellTime') || 2000, 10);  //dwell time might not be set initially, so keep retrying.
+}
+
+export function connectUrl(callback) {
+  debug('connectUrl called')
+  if (routeCallback  === null) {
+    window.addEventListener('hashchange', urlChanged);
+    window.addEventListener('popstate', urlChanged);
+    window.addEventListener('location-altered', urlChanged);
+    window.addEventListener('route-changed', routeChanged);
+  }
+  routeCallback = callback;
+  route = null;
+  Promise.resolve().then(() => {
+    urlChanged();
+    lastChangedAt = window.performance.now() - (dwellTime() - 200); //first time we need to adjust for dwell time
+  });
+
+}
+export function disconnectUrl() {
+  debug('disconnectUrl called')
+  routeCallback = null;
+  window.removeEventListener('hashchange',urlChanged);
+  window.removeEventListener('popstate', urlChanged);
+  window.removeEventListener('location-altered',urlChanged);
+  window.removeEventListener('route-changed', routeChanged);
+}
+
+function urlChanged() {
+  let path = window.decodeURIComponent(window.location.pathname);
+  const slashIndex = path.lastIndexOf('/');
+  if (path.substring(slashIndex + 1).indexOf('.') >= 0) {
+    //we have a '.' in the last part of the path, so cut off this segment
+    path = slashIndex < 0 ? '/' : path.substring(0,slashIndex);
+  } 
+  const query = decodeParams(window.location.search.substring(1));
+  if (route && route.path ===  path && JSON.stringify(route.query) === JSON.stringify(query)) return;
+  debug('url change route to path',path, 'has query', Object.keys(query).length > 0 )
+  lastChangedAt = window.performance.now();
+  route = {
+    path: path ,
+    segment: 0,
+    params: {},
+    query: query,
+    active: true
+  };
+
+  if (routeCallback) routeCallback(route); 
+}
+function routeChanged(e) {
+  let newPath = route.path;
+  if(e.detail.path !== undefined) {
+    if (Number.isInteger(e.detail.segment)) {
+      debug('route change called path', e.detail.path, 'segments', d.detail.segment, 'current path', route.path )
+      let segments = route.path.split('/');
+      if (segments[0] === '') segments.shift(); //loose leeding
+      if(segments.length < e.detail.segment) {
+        throw new Error('routeUpdated with a segment longer than current route');
+      }
+      if(segments.length > e.detail.segment) segments.length = e.detail.segment; //truncate to just before path
+      if (e.detail.path.length > 1) {
+        const newPaths = e.detail.path.split('/');
+        if (newPaths[0] === '') newPaths.shift(); //ignore blank if first char of path is '/'
+        segments = segments.concat(newPaths);
+      }
+      newPath = '/' + segments.join('/');
+      //lose trailing slash if not just a single '/'
+      if (newPath.slice(-1)  === '/' && newPath.length > 1) newPath = newPath.slice(0,-1);
+    } else {
+      throw new Error('Invalid segment info in route-updated event');
+    }
+  }
+  let query = Object.assign({}, route.query);
+  if (e.detail.query !== undefined) {
+    query = e.detail.query;
+  }
+  let newUrl = window.encodeURI(newPath).replace(/#/g, '%23').replace(/\?/g, '%3F');
+  if (Object.keys(query).length > 0) {
+    newUrl += '?' + encodeParams(query)
+      .replace(/%3F/g, '?')
+      .replace(/%2F/g, '/')
+      .replace(/'/g, '%27')
+      .replace(/#/g, '%23')
+    ;
+
+  }
+  newUrl += window.location.hash;
+  // Tidy up if base tag in header
+  const fullUrl = new URL(newUrl, window.location.protocol + '//' + window.location.host).href;
+  if (fullUrl !== window.location.href) { //has it changed?
+    let now = window.performance.now();
+    if (lastChangedAt + dwellTime() > now) {
+      window.history.replaceState({}, '', fullUrl);
+    } else {
+      window.history.pushState({}, '', fullUrl);
+    }
+    urlChanged();
+  }
+}
+function encodeParams(params) {
+  const encodedParams = [];
+
+  for (let key in params) {
+    const value = params[key];
+    if (value === '') {
+      encodedParams.push(encodeURIComponent(key) + '=');
+    } else  {
+      encodedParams.push(
+        encodeURIComponent(key) + '=' +
+        encodeURIComponent(value.toString()));
+    }
+  }
+  return encodedParams.join('&');
+}
+function decodeParams(paramString) {
+  var params = {};
+  // Work around a bug in decodeURIComponent where + is not
+  // converted to spaces:
+  paramString = (paramString || '').replace(/\+/g, '%20');
+  var paramList = paramString.split('&');
+  for (var i = 0; i < paramList.length; i++) {
+    var param = paramList[i].split('=');
+    if (param.length === 2) {
+      let value;
+      try {
+        value = decodeURIComponent(param[1]);
+        if (value === 'true') {
+          value = true;
+        } else if (value === 'false') {
+          value = false;
+        } else if (/^-?(0|[1-9]\d*)$/.test(value)) {
+          //convert to integer, only if not a value with leading zero (like phone number)
+          value = parseInt(value,10);
+        }
+      } catch (e) {
+        value = '';
+      }
+      params[decodeURIComponent(param[0])] = value;
+    }
+  }
+  return params;
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akc42/app-utils",
-  "version": "3.6.3",
+  "version": "4.0.1",
   "description": "General Utilities for SPAs",
   "exports": {
     ".": "./*.js"

package/route.js

@@ -0,0 +1,233 @@
+/**
+@licence
+    Copyright (c) 2020 Alan Chandler, all rights reserved
+
+    This file is part of Distributed Router.
+
+    Distributed Router is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    Distributed Router is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with Distributed Router.  If not, see <http://www.gnu.org/licenses/>.
+*/
+import Debug from './debug.js';
+
+const debug = Debug('router');
+
+export default class Route  {
+  constructor(match = '', ifmatched = '') {
+    //set default values
+    this.preroute = {active: false, segment: 0, path: '', params: {}, query: {}};
+    if (ifmatched.length > 0) {
+      this.matcher = ifmatched.split(':');
+      if (this.matcher.length !== 2) throw new Error('pas-route: Invalid ifmatched String');
+    } else {
+      this.matcher = [];
+    }
+    this.match = match;
+    //this is our output
+    this._route = {active: false, segment: 0, path: '', params: {}, query: {}};
+    this.sentRouteChanged = false;
+    debug('new route made with match', match, 'ifmatched', ifmatched)
+  }
+
+  routeChange(preroute) {
+    debug('routeChanged called with preroute of', JSON.stringify(preroute));
+    this.preroute = preroute; //remember it
+    if (preroute !== undefined && preroute.active && preroute.path.length > 0 &&
+      this._ifMatches(preroute.params) ) {
+      if (this.match.length > 0) {
+        let completed = false;
+        if (this.match.slice(-1)  === '/') {
+          completed = true;  //Special meaning
+          if (this.match.length > 1) {
+            this.match = this.match.slice(0,-1);
+          }
+        }
+        const matchedPieces = this.match.split('/');
+        if (matchedPieces[0] === '') matchedPieces.shift();  //not interested in blank front
+
+        const urlPieces = preroute.path.split('/');
+        if (urlPieces.length < 2 || urlPieces[0] !== '') {
+          //something is wrong with path as it should have started with a '/'
+          this._route.active = false;
+          throw new Error('Route: Invalid path (should start with /) in route');
+        }
+
+        urlPieces.shift();
+        let j = urlPieces.length;
+        const newRoute = {
+          segment: preroute.segment + matchedPieces.length,
+          params: {},
+          active: true,
+          query: preroute.query
+        };
+        for(let i = 0; i < matchedPieces.length; i++) {
+          if (j <= 0)  {
+            return this._clearOutActive();
+          }
+          let segment = urlPieces.shift();
+          j--;
+          if (matchedPieces[i].length !== 0) {
+            if (matchedPieces[i].substring(0,1) === ':') {
+              const key = matchedPieces[i].substring(1);
+              if (key.length > 0) {
+                if (/^-?\d+$/.test(segment)) {
+                  segment = parseInt(segment,10);
+                }
+                newRoute.params[key] = segment;
+              } else {
+                throw new Error('Route: Match pattern missing parameter name');
+              }
+            } else if (matchedPieces[i] !== segment) {
+              return this._clearOutActive();
+            }
+          } else if (segment.length > 0 ){
+            return this._clearOutActive();
+          }
+        }
+        if (completed || preroute.path === '/') {
+          newRoute.path = '';
+        } else if (j == 0) {
+          newRoute.path = '/';
+        } else {
+          newRoute.path = '/' + urlPieces.join('/');
+        }
+        if (!this._route.active ||
+          JSON.stringify(this._route.params) !== JSON.stringify(newRoute.params) ||
+          JSON.stringify(this._route.query) !== JSON.stringify(newRoute.query) ||
+          this._route.path !== newRoute.path || this._route.segment !== newRoute.segment) {
+          this._route =  newRoute;
+          this.sentRouteChanged = true;
+        }
+        debug('Route Change returning (no clear active)', JSON.stringify(this._route));
+      } else {
+        throw new Error('Route: Match String Required');
+      }
+    } else {
+      this._clearOutActive();
+    }
+    return this._route;
+  }
+  /*
+  * set new paramters provided route is active
+  */
+  set params(value) {
+    if (this._route.active) {
+      let match = this.match;
+      if (match.slice(-1)  === '/' && match.length > 1) match = this.match.slice(0,-1);
+      const matchedPieces = match.split('/');
+      if (matchedPieces[0] === '') matchedPieces.shift();  //not interested in blank front
+
+      let urlPieces = this.preroute.path.split('/');
+      urlPieces.shift();  //loose blank front
+      let changeMade = false;
+      for (let i = 0; i < matchedPieces.length; i++) {
+        if (urlPieces.length < i) urlPieces.push(''); //ensure there is a url segment for this match
+        if (matchedPieces[i].length !== 0) {
+          if (matchedPieces[i].substring(0,1) === ':') {
+            const key = matchedPieces[i].substring(1);
+            if (value[key] !== undefined) {
+              if (Number.isInteger(value[key])) {
+                if (urlPieces[i] !== value[key].toString()) {
+                  urlPieces[i] = value[key].toString();
+                  changeMade = true;
+                }
+              } else if (typeof value[key] === 'string') {
+                if (value[key].length > 0) {
+                  if (urlPieces[i] !== value[key]) {
+                    urlPieces[i] = value[key];
+                    changeMade = true;
+                  }
+                } else {
+                  //terminate url here
+                  urlPieces.length = i;
+                  changeMade = true;
+                  break;
+                }
+              } else if (value[key] === null) {
+                //terminate url here
+                urlPieces.length = i;
+                changeMade = true;
+                break;
+              } else {
+                throw new Error('Route: Invalid params.' + key + ' provided (should be a String or an Integer)');
+              }
+            }
+          }
+        }
+      }
+      if (changeMade) {
+        const path = '/' + urlPieces.join('/');
+        debug('params set, about to set path',path,'segment', this.preroute.segment );
+        window.dispatchEvent(new CustomEvent ('route-changed',{bubbles: true, composed: true, detail:{
+          segment: this.preroute.segment,
+          path: path
+        }}));
+      }
+    }
+  }
+  /*
+   *  Set a new query value provided route is active
+   */
+  set query(value) {
+    const jsv = JSON.stringify(value)
+    debug('set query to value', jsv)
+    if (this._route.active && JSON.stringify(this._route.query) !== jsv) {
+      window.dispatchEvent(new CustomEvent('route-changed',{bubbles: true, composed: true, detail:{query: value}}));
+    }
+  }
+  /*
+   * We can set or break the connection between a pre-route and its route
+   */
+  set connection(value) {
+    debug('set connection called with value', value);
+    if (this.preroute.active) {
+      if (this._route.active) {
+        if (value) return; //can't set a matched route active
+        //just reset to a url
+        window.dispatchEvent(new CustomEvent('route-changed', { bubbles: true, composed: true, detail:{
+          segment: this.preroute.segment,
+          path: '/'
+        }}));
+      } else {
+        if (value) {
+          let match = this.match;
+          if (match.slice(-1)  === '/' && match.length > 1) match = this.match.slice(0,-1);
+          const matchedPieces = match.split('/');
+          if (matchedPieces[0] === '') matchedPieces.shift();  //not interested in blank front
+          if (matchedPieces.length < 1) return;
+          if (matchedPieces.every(piece => piece.length > 0 && piece.indexOf(':') < 0)) {
+            window.dispatchEvent(new CustomEvent('route-changed', {bubbles: true, composed: true, detail:{
+              segment: this.preroute.segment,
+              path: '/' + matchedPieces.join('/')
+            }}));
+
+          }
+        }
+      }
+    }
+  }
+
+  _ifMatches (params) {
+    if (this.matcher.length === 0) return true;  //Empty String always matches
+    return (params[this.matcher[0]] !== undefined && params[this.matcher[0]] === this.matcher[1]);
+  }
+  _clearOutActive () {
+    if (this._route === undefined) return;
+    if (this._route.active || !this.sentRouteChanged) {
+      this._route = Object.assign({}, this._route, {active:false});
+      this.sentRouteChanged = true;
+    }
+    debug('clearOutActive returning route', JSON.stringify(this._route));
+    return this._route;
+  }
+}
+