@akc42/app-utils 4.2.1 → 5.0.0

package/README.md

@@ -1,15 +1,24 @@
 # app-utils
 General utilities that I use for building SPAs 
 
-New from release 3.0
+Release 5.0 adds a lot of new functions and some major changes to existing ones. It also has been packaged into an export from a single file.
 
-config-promise is a function which returns both a promise for the config AND adds the config items to sessionStorage.
+## api and ApiError
 
-debug has been replaced with a version that works differently and is incompatible with our previous usage (hence the bump to version 3)
+The key function is **api** which handles a post request to a `/api/<url>` server, managing the response. ApiError are
+how problems with this are reported. The api call takes two essential parameters and one optional.
 
-# app-keys
+1. url - the url appended to `/api/` to the endpoint of the server.
+2. params - an object containing the parameters to be passed to the endpoint
+3. optional flag to indicate the response is a blob (normally a pdf) to be opened in a new window rather than as a direct response.
 
-    `keys` is a module that provides keyboard support by normalising key
+The response is aysnchronousally returned as an object.  Errors are throw using the **ApiError** object.
+
+## ApiKeys
+
+  **ApiKeys** is a class where the new 
+
+    ApiKeys is a class that provides keyboard support by normalising key
     handling amongst browsers and providing a simple interface that can be used
     by the application.  Each keyboard usage request the user create a new
     instance of the AppKeys class passing the key target in to the constructor.
@@ -33,7 +42,7 @@ debug has been replaced with a version that works differently and is incompatibl
     NOTE: If you take this approach limit the keys to non function keys as the main app, with its main 
     menu may add a handler for the function keys and both menus, and any actions you choose would run at the same time.
 
-```
+```javascript
     constructor() {
       super();
       ...
@@ -62,7 +71,7 @@ debug has been replaced with a version that works differently and is incompatibl
     if there are different areas of the page needing the respond depending which area
     has focus.  This is to create the AppKeys object in the firstUpdated function.  Here is a possible example (just one area)
 
-```
+```javascript
   connectedCallback() {
     super.connectedCallback();
     if (this.keys !== undefined) this.keys.connect();
@@ -85,106 +94,104 @@ debug has been replaced with a version that works differently and is incompatibl
   If for any reason you want more info about the keyPress, access
   `this.keys.lastPressed`, and it will return the complete binding object
 
+## calcTextColour
 
-# csv
-
-  the modules default export is a function which can be called with a name and optionally a parameters object.  The name is added to `/api/csv/` to make a download request and if they exist the parameters object is turned into a query string.  The response from that uri is downloaded (expected to be a csv file).
-
-# debug
-
-The purpose of this module is to provide a debugable capability which can be
-  dynamically switched on and off browser by setting a key in the config
-  returned by the server. It will post request to `/api/log` url with an
-  `application/json` body part containing message, topic and gap, where message is
-  the concatenation of the debug parameters separated by space, topic is the
-  topic of this debug message and gap is the number of milliseconds since the
-  last debug message with the same topic.
-
-  Topic data is held in a map, so this module can be used in multiple modules in
-  the client and if its the same topic then the gap will be since the last call
-  from **any** module.
-
-  To use the debug function in your code, import this module then set the topic
-  as shown.
-
-  import Debug from 'debug.js';
-
-  const debug = Debug('topic') topic should only contain the characters a-z or
-  A-Z as is converted to lowercase.
-
-  debug(..messages) //messages will be concatenated by space
-
-  the debug function will only log the message if config.debug (see
-  config-promise) is set to a string which is a comma separated list of topics
-  and that list has the topic for this debug call in it.
-
-  **Note**: the debug function checks with the sessionStorage.getItem('debug) (via an await for the Config Promise)
-  to see if the topic is enabled (assumes the result is a ':' separated string of topics).  This allows the server to
-  change what topics are available via the config api call.
-
-# dom-host
-
-  the default function of this module is called with a single parameter (normally `this` inside a custom element)
-  and it finds the parent.  Its useful for custom elements to sit at the top level of the custom element above and listen for
-  events bubbling up from below.  It uses this function to find the element to add an event listener to.
-
-# master-tab-promise
-
-the default function returns a promise, which when resolves will tell you if you are the first (and therefore master) tab in a particular application.
-
-if the master tab closes an custom Event 'master-close' is dispatched on the window.  You can use that to recheck the promise to see if you (or perhaps some other tab also still open is now master);
-
-
-# pdf
+This is a utility function to determine the correct foreground colour (black or white) to use with a background colour
+passed as the parameter (as a hex strings with an optional proceeding `#` symbol.). The colour is returned as either `#000000` or `#ffffff`
 
-the modules default export is a function which can be called with a name and optionally a parameters object.  The name is added to `/api/pdf/` to post a message to the server, expecting it to stream a precreated, or created on the fly pdf document.  This is opened in a new window.
+## config and related 
 
-# post-api
+By importing the **config** constant you are infact resolving from promise (this `import` statement does the resolving) to make an api call to the server `/api/config` to return config data as an object.  What is returned is obviously server dependant. It has two independant functions.  From an application point of view `import {config} from '@akc42/app-utils` produces a config constant with the config data set.
 
-Provides a wrapper found the `fetch` api with error handling and built it post message support to a url prefixed with `/api/`.  
+Additional support is provided with
+  
+1. **setConfig** which can optionally be given a promise which resolves to a new config (useful in testing scenarios), or causes a re-read of the config from the server, although it does not return this reread..
+2. **reReadConfig** actualy causes a re-read from the server and returns the promise for its eventual resolution (i.e
+   `const config = await reReadConfig()`).
 
-# submit-function
+## csv
 
-Acts as the on-submit handler for a form.  But instead of allowing the form to send itself it creates an ajax request with all the correct parameters.  
-In doing this it can traverse inside custom elements looking for input elements. It will also check for custom elements and if they have both a name and value property if can pretend to be in input.  Also slots are also traversed for all assigned nodes.
+  the modules default export is a function which can be called with a name and optionally a parameters object.  The name is formed into url to `/api/csv/<name>`  to make a download request and if they exist the parameters object is turned into a query string.  The response from that uri is downloaded (expected to be a csv file).
 
+## debug
 
-# 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).
+The purpose of this module is to provide a debugable capability which can be
+dynamically switched on and off browser by setting a key in the config
+returned by the server. It will post request to `/api/debuglog/:immediate` url with an
+`application/json` body part containing debug data.  Its purpose is to emulate what it's 
+server counterpart does locally.
+
+It consists of two functions **Debug** and **Logger**.
+
+**Debug** creates an instance of a debug function and its called with parameters:
+
+- **topic** - a value that can be searched for. Useful for dividing into different sections
+- **colourspec** - One of name of standard colors [app,db,api,client,log,mail,auth,error], 
+  a hex color string, an rgb, comma seperated, string of three values 0-255 
+- **shortdate** - if true, then dates will be output as YYYY-MM-DD hh:mm else 
+  YYYY-MM-DD hh:mm:ss.ms
+- **immediate** - if true, the message is output (formatted) to the console, both in the 
+  browser and in the server.
+  
+Calling this function returns a function that will send a row to the server (for writing into the log there), using the
+parameters above and some optional extra values these extra parameters (just skip if not provided, the function
+dynamically checks them) are:-
+
+- **crash** - the literal word "crash".  if set, then this will be highlighted in the output. Don't provide this as
+  the first parameter if a normal call
+- **logtime**- a unix millisecond timestamp.  If provided if must be for today, otherwise it will be as
+  though it were not provided. If provided it will be the `logtime`, otherwise `Date.now()` will be used.
+- **ipaddress** - an optional parameter container a string representation of an ip address. Ignored if not
+  a valid adddress. If provided its value will be highlighted and surrounded in "[]"
+- **...messages** - As many parameters containing parts of the message.  The message will be joined together
+  with a space separation and displayed with the colourspec parameter.
+
+
+
+**Logger** is like Debug (indeed its a wrapper for it) except it doesn't need short date, or immediate parameters as 
+that is what is assumed.
+
+## dom-host
+
+The **domHost** function is called with a single parameter (normally `this` inside a custom element)
+and it finds the parent.  Its useful for custom elements to sit at the top level of the custom element above and listen for
+events bubbling up from below.  It uses this function to find the element to add an event listener to.
+
+## Client Side Routing.
+
+A Distributed Client Side Router for use with a hierarchy of custom components in an Single Page Application. The
+functions of this subsystem links the browsers URL bar into a chained list of `Route` 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 (generally 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 log 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
-```
+
+```javascript
  const topLevel = new Route('/:page');
  const firstLevel = new Route('/:id', 'page:appointments');
  connectUrl(route => {
@@ -201,13 +208,15 @@ This is usually used with something like this
  });
  
 ```
-(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).
+(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:-
+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:-
 
-```
+```javascript
  const firstLevel = new Route('/appointments/:id');
  connectUrl(route => {
     const subRoute = topLevel.routeChange(route);
@@ -225,41 +234,57 @@ with a url of the form "/appointements/53" and not (say) when the url was "/user
 ```
 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]
-     }
+
+```javascript
+    ${
+      {
+        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.
+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`.
+- `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());
-```
-# config
+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 function **switchPath** can do this for you.  It takes two parameters, `path` and a `params` object, the latter
+of which is formed into a query string and appended (with the appropriate "?") into a string.  A helper function
+**generateUri** takes the same two parameters and creates the final url, it just doesn't apply the result.
+
+**navigate** is a function to be used as an event handler on an element (normally for `@click`). It calls `switchPath` with the
+`path` set to the  `path` attribute of the element which fired the event.
+
+## master-tab-promise
+
+The **getMasterTabPromise** function returns a promise, which when resolves will tell you if you are the first (and therefore master) tab in a particular application.
+
+if the master tab closes an custom Event 'master-close' is dispatched on the window.  You can use that to recheck the promise to see if you (or perhaps some other tab also still open is now master);
+
+## partMap
+
+**partMap** is a `lit` "directive", exactly analogous to the provided `classMap`, but for the `part` attribute. Use it in the same way to dynamically assign parts to an element.
+
+## pdf
 
-Newly added in release 4.1.0, this function is used for getting the client config from the server
+the modules default export is a function which can be called with a name and optionally a parameters object.  The name is added to `/api/pdf/` to post a message to the server, expecting it to stream a precreated, or created on the fly pdf document (as Blob).  This is opened in a new window.
 
-The default export, normally named config (ie the client does `import config from @akc42/app-utils/config.js`) and allows the normal await mechanisms in `import` to 
-allow this module to make an get request to the server of `/api/config` and for the server to return it.  The   `config` variable then holds (without any further waiting)
-the client config object returned by the server.
 
-Two non default async exports are also provided. `setConfig` called with no parameters will read the config from the server, called with a promise as a parameter it expects
-that promise to be resolved with a config (useful in testing).  The other async function is `reReadConfig` with essentially causes the config to be reRead, but does also returns a promise resolving to the config.
+## submit-function
 
+Acts as the on-submit handler for a form.  But instead of allowing the form to send itself it creates an ajax request
+with all the correct parameters. In doing this it can traverse inside custom elements looking for input elements. It
+will also check for custom elements and if they have both a name and value property if can pretend to be in input.  Also
+slots are also traversed for all assigned nodes.
 

package/api.js

@@ -0,0 +1,94 @@
+/**
+@licence
+    Copyright (c) 2020 Alan Chandler, all rights reserved
+
+    This file is part of @akc42/app-utils.
+
+    @akc42/app-utils 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.
+
+    @akc42/app-utils 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 @akc42/app-utils.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import Debug from './debug.js';
+
+const debug = Debug('client-api', 'api');
+
+class ApiError extends Error {
+  constructor(address, code) {
+    super('API Error: ' + address)
+    this.name = 'API' + code.toString();
+  }
+}
+
+async function api(url, params, bl) {
+  const blob = bl;
+  const controller = new AbortController();
+  const address = '/api/' + url;
+  const options = {
+    mode: 'cors',
+    credentials: 'include',
+    method: 'post',
+    headers: new Headers({
+      'content-type': 'application/json'
+    }),
+    body: new Blob([JSON.stringify(params ?? {})], { type: 'application/json' }),
+    signal: controller.signal
+  };
+  let text;
+  const timer = setTimeout(() => controller.abort('timeout'),60000); //just a protection against complete loss of response.
+  try {
+    const response = await window.fetch(address, options)
+    if (response.ok) {
+      clearTimeout(timer);
+      if (blob) {
+        text = '---502---';  //Simulate a 502 (bad gateway) incase there is an error in following.
+        const b = await response.blob();
+        window.open(
+          URL.createObjectURL(b),
+          '_blank',
+          'chrome=yes,centerscreen,resizable,scrollbars,status,height=800,width=800');
+
+        document.body.dispatchEvent(new CustomEvent('wait-request',{bubbles: true, composed: true, detail: false}));
+        debug('request returned blob');
+        return {};
+      } else {
+        text = await response.text();
+        if (text.length > 0) {
+          const j = JSON.parse(text);
+          document.body.dispatchEvent(new CustomEvent('wait-request',{bubbles: true, composed: true, detail: false}));
+          debug('request returned JSON', text);
+          return j;
+        }
+        document.body.dispatchEvent(new CustomEvent('wait-request',{bubbles: true, composed: true, detail: false}));
+        debug('empty return');
+        return {};
+      }
+
+    } else if (response.status < 500) throw new ApiError(address, response.status);
+  } catch (err) {
+    //no debug needed - will report at where its thrown
+    clearTimeout(timer);
+    if (!(err instanceof TypeError)) {
+      //not network failure so no retry
+      if (err instanceof SyntaxError) {
+        const code = Number((text?? '---502---').slice(-6, -3));
+        if (code > 299) throw new ApiError(address,code);    
+      } else if (err.name === 'AbortError') throw new ApiError(address, 504);  //simulate gateway timeout
+      throw err; //just throw what we have
+    }
+  }
+  clearTimeout(timer);
+  return {};
+} 
+
+export { api , ApiError };
+

package/app-utils.js

@@ -0,0 +1,17 @@
+import {api, ApiError} from './api.js';
+import AppKeys from './app-keys.js';
+import calcTextColor from './colour.js';
+import config, {setConfig, reReadConfig}from './config.js'
+import csv from './csv.js';
+import {Debug,Logger} from './debug.js';
+import domHost from './dom-host.js';
+import { connectUrl, disconnectUrl} from './location.js';
+import getMasterTabPromise from './master-tab-promise.js';
+import {partMap} from './partMap.js';
+import pdf from './pdf.js';
+import Route from './route.js';
+import submit from './submit-function.js';
+import {switchPath, generateUri, nagivate} from './switch-path.js';
+
+export {api,ApiError,AppKeys,calcTextColor,config, connectUrl, csv, Debug, disconnectUrl, domHost, generateUri,
+  getMasterTabPromise, Logger, navigate, partMap, pdf, reReadConfig, Route,setConfig, submit, switchPath };

package/colour.js

@@ -0,0 +1,34 @@
+/**
+@licence
+    Copyright (c) 2023 Alan Chandler, all rights reserved
+
+    This file is part of @akc42/app-utils.
+
+    @akc42/app-utils 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.
+
+    @akc42/app-utils 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 @akc42/app-utils.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/*
+  Given a background colour, this function calculates what the color string from
+  the text should be. Backgroundcolour should be a hex string, optionally
+  proceeded by #
+*/
+
+function calcTextColor(backgroundColor) {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(backgroundColor);
+  if (result) {
+    const luminance = (0.2126 * parseInt(result[1], 16) + 0.7152 * parseInt(result[2], 16) + 0.0722 * parseInt(result[3], 16));
+    return (luminance < 140) ? "#ffffff" : "#000000";
+  }
+  return "#000000"
+}
+export default calcTextColor;

package/debug.js

@@ -19,138 +19,54 @@
 */
 
 /*
-  The purpose of this module is to provide a debugable capability which can be dynamically switched on and off browser
-  by setting sessionStorage value 'debug' to the config returned by the server. It will post request to '/api/debuglog'
-  url with application/json body part containing message, topic and gap, where message is the concatenation of the debug
-  parameters separated by space, topic is the topic of this debug message and gap is the number of milliseconds since
-  the last debug message with the same topic.
+  import {Debug} from '@akc42/app-utils'
 
-  Topic data is held in a map, so this module can be used in multiple modules in
-  the client and if its the same topic then the gap will be since the last call
-  from ANY module.
+  Debug creates an instance of a debug function 
 
-  To use the debug function in your code, import this module then set the topic
-  as shown.
+  parameters:
+    topic       - a value that can be searched for. Useful for dividing into different sections
+    colourspec  - One of name of standard colors [app,db,api,client,log,mail,auth,error], a hex color string, an rgb, 
+                  comma seperated, string of three values 0-255 
+    shortdate   - if true, then dates will be output as YYYY-MM-DD hh:mm else YYYY-MM-DD hh:mm:ss.ms
 
-  import Debug from 'debug.js';
-
-  const debug = Debug('topic') topic should only contain the characters a-z or
-  A-Z as is converted to lowercase.
-
-  debug(..messages) //messages will be concatenated by space
-
-  the debug function will only log the message on the server if sessionStorage "debug"  is set to a string which is a colon separated list of topics
-  and that list has the topic for this debug call in it.
-
-  NOTE: It is normally expected for the server to provide a mechanism to update
-  the confgi before it is returned,  The main app then overwrites sessionStorage 'debug' item with a new list of topics when you want
-  debug to switch on and off dynamically.
-
-  regardless of whether the message is logged on the server, it is also added to the performance.mark buffer
-  so that it can be sent to the server on a crash.
-
-  Although Debug is the default export this module also provides the following named exports
+    immediate   - if set, the message is output (formatted) to the console.
   
-  initialiseDebug - this function is used to manage tracing of debug messages regardless of whether the topic is set
-    It also adds an event handler to handle resource buffer full events.  NOTE if the buffer fills up priority is given
-  
-  unloadDebug - this function tidies up and reverses the initialiseDebug
-
-  debugDump - perform a dump to the server (and and a clearing out of the buffered info) of the debug calls made to date
-
+  Returns a function that will send a row to the server (for writing into the log there), using the parameters above and
+  some optional extra values these extra parameters are
+
+    crash       - the literal word "crash".  if set, then this will be highlighted in the output. Don't provide this as
+                  the first parameter if a normal call
+    logtime     - a unix millisecond timestamp.  If provided if must be for today, otherwise it will be as
+                  though it were not provided. If provided it will be the logtime, otherwise "Now" will be used.
+    ipaddress   - an optional parameter container a string representation of an ip address. Ignored if not
+                  a valid adddress. If provided its value will be highlighted and surrounded in "[]"
+    ...messages - As many parameters containing parts of the message.  The message will be joined together
+                  with a space separation and displayed with the colourspec parameter.
 */
 
-const BUFFER_SIZE = 50;
-const KEY_TOPIC = 'key'; //topic name which will get kept from a full resource buffer when we empty it.
-let buffer = []; //buffer of up to 50 topic/message pairs to allow us to hold some if resource buffer becomes full;
-
-const topicMap = new Map();
-
-let initialised = false;
-
+/*
+  Logger is like Debug (indeed its a wrapper for it) except
 
-function bufferFull() {
-  const entries = performance.getEntriesByType('mark');
-  performance.clearMarks();
-  const startPoint = entries.length - BUFFER_SIZE;
-  buffer.splice(0, buffer.length + startPoint);
-  for (let i = 0; i < entries.length; i++) {
-    if (entries[i].name === KEY_TOPIC || i >= startPoint) {
-      buffer.push({ topic: entries[i].name, message: entries[i].detail, time: Math.round(entries[i].startTime) });
-    }
-  }
-}
+  It doesn't need short date, or immediate parameters as thats whats assumed
 
-function initialiseDebug() {
-  initialised = true;
-  buffer = [];
-  performance.setResourceTimingBufferSize(150)
-  window.addEventListener('resourcetimingbufferfull', bufferFull)
-}
+*/
+import {DebugHelper, messageFormatter} from '@akc42/server-utils';
 
-function unloadDebug() {
-  window.removeEventListener('resourcetimingbufferfull', bufferFull);
-}
-function debugDump() {
-  bufferFull();  //this clears out the marks and gives us a buffer to now send to
-  buffer.reverse();
-  let message = '';
-  for (let i = 0; i < buffer.length; i++) {
-    message += `(${buffer[i].topic}) ${buffer[i].message} :gap ${i < buffer.length - 1 ? buffer[i].time - buffer[i + 1].time : 0}ms\n`;
+export function Logger(topic, colourspec) {
+  const debug = Debug(topic, colourspec, 1,1);
+  return function(c, ip, ...args) {
+    const output = debug(c,ip,args);
+    console.log(output.message);
   }
-  const blob = new Blob([JSON.stringify({
-    message: message
-  })], { type: 'application/json' });
-  navigator.sendBeacon(`/api/debuglog/clientpath`, blob);
-
-  buffer = []; //we will start our buffer from scratch again
-
 }
 
+export function Debug(topic, colourspec, shortdate, immediate = false) {
+  return DebugHelper(topic, colourspec, shortdate, immediate , writer)
 
-function Debug(t) {
-  if (typeof t !== 'string' || t.length === 0 || !/^[a-zA-Z]+$/.test(t)) {
-    console.error('Debug requires topic which is a non zero length string of only letters', t, 'Received');
-    throw new Error('Invalid Debug Topic');
-  }
-  const tl = t.toLowerCase();
-  if (topicMap.has(tl)) {
-    const topic = topicMap.get(tl);
-    return topic.debug;
-  }
-
-  const topicHandler = {
-    topic: tl,
-    timestamp: new Date().getTime(),
-    defined: false, //has the config been defined yet
-    debug: function (...args) {
-      //do time calc before potential delay to see if we are enabled
-      const now = new Date().getTime();
-      const gap = now - this.timestamp;
-      this.timestamp = now;
-      const message = args.reduce((cum, arg) => {
-        return `${cum} ${arg}`.trim();
-      }, '');
-      if (initialised) performance.mark(this.topic, { detail: message });  //save our message locally regardless of if enabled
-      let enabled = false;
-      const debugConf = sessionStorage.getItem('debug');
-      if (debugConf) {
-        const topics = debugConf.split(':');
-        if (topics.includes(this.topic)) enabled = true;
-      }
-      if (enabled) {
-        const blob = new Blob([JSON.stringify({
-          message: message,
-          gap: gap
-        })], { type: 'application/json' });
-
-        navigator.sendBeacon(`/api/debuglog/${this.topic}`, blob);
-      }
-    }
-  }
-  topicHandler.debug = topicHandler.debug.bind(topicHandler);
-  topicMap.set(topicHandler.topic, topicHandler);
-  return topicHandler.debug
 }
 
-export { Debug as default, initialiseDebug, unloadDebug, debugDump };
+function writer (logtime, crash, shortdate,ip, topic, message, colourspec,gap, i) {
+  const blob = new Blob([JSON.stringify({logtime,crash, shortdate, topic,message,colourspec,gap})], { type: 'application/json' });
+  navigator.sendBeacon(`/api/debuglog/${i ? 1: 0}`, blob);
+  return messageFormatter('no id', logtime,crash,shortdate,ip,topic,message,colourspec,gap)
+}

package/location.js

@@ -55,7 +55,7 @@ export function disconnectUrl() {
 }
 
 function urlChanged() {
-  let path = window.decodeURIComponent(window.location.pathname);
+  let path = 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

package/package.json

@@ -1,10 +1,8 @@
 {
   "name": "@akc42/app-utils",
-  "version": "4.2.1",
+  "version": "5.0.0",
   "description": "General Utilities for SPAs",
-  "exports": {
-    ".": "./*.js"
-  },
+  "mains": "app-utils.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
@@ -20,5 +18,9 @@
   "bugs": {
     "url": "https://github.com/akc42/app-utils/issues"
   },
-  "homepage": "https://github.com/akc42/app-utils#readme"
+  "homepage": "https://github.com/akc42/app-utils#readme",
+  "dependencies": {
+    "@akc42/server-utils": "^3.4.2",
+    "lit": "^3.3.1"
+  }
 }

package/partMap.js

@@ -0,0 +1,117 @@
+/**
+@licence
+    Copyright (c) 2021 Alan Chandler, all rights reserved
+
+    This file is part of @akc42/app-utils.
+
+    @akc42/app-utils 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.
+
+    @akc42/app-utils 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 @akc42/app-utils.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/**
+ * Much of this code is copied (as a model of what to do) from the classMap directive in Googles lit package.  
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+import {noChange} from 'lit'
+import {directive,Directive,PartType} from 'lit/directive';
+
+class PartMapDirective extends Directive {
+  
+  constructor(partInfo) {
+    super(partInfo);
+
+    if (partInfo.type !== PartType.ATTRIBUTE || partInfo.name !== 'part' || partInfo.strings?.length > 2) {
+      throw new Error(
+        '`partMap()` can only be used in the `part` attribute ' +
+          'and must be the only part in the attribute.'
+      );
+    }
+  }
+
+  render(partInfo) {
+    // Add spaces to ensure separation from static parts
+    return (
+      ' ' +
+      Object.keys(partInfo)
+        .filter((key) => partInfo[key])
+        .join(' ') +
+      ' '
+    );
+  }
+
+  update(part, [partInfo]) {
+    // Remember dynamic parts on the first render
+    if (this._previousParts === undefined) {
+      this._previousParts = new Set();
+      if (part.strings !== undefined) {
+        this._staticParts = new Set(
+          part.strings
+            .join(' ')
+            .split(/\s/)
+            .filter((s) => s !== '')
+        );
+      }
+      for (const name in partInfo) {
+        if (partInfo[name] && !this._staticParts?.has(name)) {
+          this._previousParts.add(name);
+        }
+      }
+      return this.render(partInfo);
+    }
+    let changed = false;
+    // Remove old classes that no longer apply
+    for (const name of this._previousParts) {
+      if (!(name in partInfo)) {
+        this._previousParts.delete(name);
+        changed = true;
+      }
+    }
+
+    // Add or remove classes based on their classMap value
+    for (const name in partInfo) {
+      // We explicitly want a loose truthy check of `value` because it seems
+      // more convenient that '' and 0 are skipped.
+      const value = !!partInfo[name];
+      if (
+        value !== this._previousParts.has(name) &&
+        !this._staticParts?.has(name)
+      ) {
+        changed = true;
+        if (value) {
+          this._previousParts.add(name);
+        } else {
+          this._previousParts.delete(name);
+        }
+      }
+    }
+    if (changed) return this.render(partInfo);
+    return noChange;
+  }
+}
+
+/**
+ * A directive that applies dynamic parts
+ *
+ * This must be used in the `part` attribute and must be the only part used in
+ * the attribute. It takes each property in the `partInfo` argument and adds
+ * the property name to the element's `part` if the property value is
+ * truthy; if the property value is falsy, the property name is removed from
+ * the element's `part`.
+ *
+ * For example `{foo: bar}` applies the part name `foo` if the value of `bar` is
+ * truthy.
+ *
+ * @param partInfo
+ */
+export const partMap = directive(PartMapDirective);

package/route.js

@@ -73,7 +73,7 @@ export default class Route  {
           if (j <= 0)  {
             return this._clearOutActive();
           }
-          let segment = urlPieces.shift();
+          let segment = decodeURIComponent(urlPieces.shift());
           j--;
           if (matchedPieces[i].length !== 0) {
             if (matchedPieces[i].substring(0,1) === ':') {

package/switch-path.js

@@ -21,7 +21,7 @@
 export function generateUri(path, params) {
   var str = [];
   if (params) {
-    for (var param in params) {
+    for (const param in params) {
       //eslint-disable-next-line no-prototype-builtins
       if (params.hasOwnProperty(param)) {
         str.push(encodeURIComponent(param) + '=' + encodeURIComponent(params[param]));
@@ -38,5 +38,10 @@ export function switchPath(path, params) {
   history.pushState({}, null, generateUri(path, params));
   window.dispatchEvent(new CustomEvent('location-altered', { composed: true, bubbles: true }));
 }
-export default switchPath;
 
+export function navigate (e) {
+  const link = e.currentTarget.getAttribute('path');
+  if (typeof link !== 'undefined') {
+    switchPath(link);
+  }
+}

package/post-api.js

@@ -1,61 +0,0 @@
-/**
-@licence
-    Copyright (c) 2020 Alan Chandler, all rights reserved
-
-    This file is part of @akc42/app-utils.
-
-    @akc42/app-utils 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.
-
-    @akc42/app-utils 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 @akc42/app-utils.  If not, see <http://www.gnu.org/licenses/>.
-*/
-
-
-export default async function api(url, params, blob, signal) {
-  const address = '/api/' + url;
-  const options = {
-    credentials: 'same-origin',
-    method: 'post',
-    headers: new Headers({
-      'content-type': 'application/json'
-    }),
-    body: JSON.stringify(params ?? {})
-  };
-  performance.mark('fetchapi', { detail: `${address} params: ${options.body}` })
-  if (signal) options.signal = signal;
-  let text;
-  try {
-    const response = await window.fetch(address, options);
-    if (!response.ok) throw new CustomEvent('api-error', {composed: true, bubbles: true , detail:{status:response.status, url:address}});
-    performance.mark('fetchdone', {detail: address});
-    performance.measure('apicalltime',{start: 'fetchapi', end:'fetchdone', detail: address});
-    if (blob) {
-      text = '---502---';  //Simulate a 502 (bad gateway) incase there is an error in following.
-      const b = await response.blob();
-      window.open(
-        URL.createObjectURL(b),
-        '_blank',
-        'chrome=yes,centerscreen,resizable,scrollbars,status,height=800,width=800');
-      return {};
-    } else {
-      text = await response.text();
-      if (text.length > 0) return JSON.parse(text);
-      return {};
-    }
-  } catch (err) {
-    if (!options.signal || !options.signal.aborted) {
-      if (err instanceof TypeError) throw new CustomEvent('api-network', { bubbles:true, composed:true, detail: address})
-      if (err.type === 'api-error') throw err; //just throw whatever error we had
-      //we failed to parse the json - the actual code should be in the text near the end;
-      throw new CustomEvent('api-error', { composed: true, bubbles: true, detail: {status:parseInt((text?? '---502---').slice(-6, -3), 10), url:address }});
-    }
-  }
-}