saasufy-components 2.6.2 → 2.8.0

package/README.md

@@ -1,23 +1,169 @@
 # Saasufy Components
 Components for Saasufy
 
+## Overview
+
+Many Saasufy components use a combination of `<template slot="item">` and `<div slot="viewport">`. Both of these are known as `slotted` elements.
+
+A `<template slot="item">` is an inert/hidden element which the component uses to format its output. The `<div slot="viewport">` is an element which will contain the rendered output of the component.
+
+Components which follow this pattern take templates as input and render them inside the specified `<div slot="viewport">` element. Note that the viewport can be any element and not necessarily a `div`.
+
+The most important thing to remember is that the element marked with the `slot="item"` attribute serves as a template for your component and the element marked with `slot="viewport"` serves as a container for its output. Although the `item` slot is commonly used, components may require different slot names for input templates so it's important to read the documentation carefully.
+
+A component's output consists of instances of your template after they've been populated with data from the component.
+You can apply custom CSS/styling to elements that are rendered inside a viewport - It may be useful to add a custom `class` attribute to your viewport element to allow targeting using CSS selectors.
+
 ## How to use
 
-Coming soon.
+To use components, you just need to include them into your `.html` file inside your `<head>` tag like this:
+
+```html
+<script src="https://saasufy.com/node_modules/saasufy-components/socket.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/app-router.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/collection-browser.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/collection-adder.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/collection-deleter.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/collection-reducer.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/model-input.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/model-text.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/model-viewer.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/input-provider.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/confirm-modal.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/render-group.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/conditional-group.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/collection-adder-group.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/log-in-form.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/log-out.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/oauth-link.js" type="module" defer></script>
+<script src="https://saasufy.com/node_modules/saasufy-components/oauth-handler.js" type="module" defer></script>
+```
+
+You should only add the script tags for the components which your page uses to avoid wasting bandwidth and unnecessarily delaying page load for your users.
+The `.js` file name of the component matches the names of the HTML tags which the script provides.
+The only exception is the `socket-provider` component which is located inside the `socket.js` file - This is because that file exposes multiple components which are used behind the scenes by other components.
+You should always include the `socket.js` script as shown above whenever you use components which depend on data from Saasufy.
+
+Linking the scripts directly from `saasufy.com` as shown above is the simplest way to get started as it doesn't require loading anything or hosting the scripts yourself.
+An alternative approach is to download Saasufy components using `npm install saasufy-components` and then link to them from your own hosting provider.
 
 ## Components
 
+### app-router
+
+A component which allows you build apps which have multiple pages. Inside it, you should specify a template for each page in your app along with the route/path to bind each page to.
+This component also supports simple redirects as well as redirects based on the user's current authentication state. Redirects can be soft or hard; a soft redirect does not change the current URL/path, a hard redirect does.
+
+**Example usage**
+
+```html
+<app-router>
+  <template slot="page" route-path="/:productName">
+    <div class="product-title">Product: {{capitalize(productName)}}</div>
+  </template>
+  <div slot="viewport"></div>
+</app-router>
+```
+
+This example shows how an infinite number of pages can be represented with a single route template.
+In this case, the `/:productName` inside the `route-path` attribute of the slotted `<template slot="page">` element serves as a placeholder variable which can match any text.
+You can then use such route variables inside the page template itself as shown with `<div class="product-title">Product: {{capitalize(productName)}}</div>` - In this case, the `productName` variable which comes from the route path is first capitalized using the `capitalize` utility function before it is rendered into the template.
+Note that the `app-router` can contain any number of pages/routes so the `slot="page"` attribute can be re-used multiple times, e.g:
+
+```html
+<app-router>
+  <template slot="page" route-path="/home">
+    <div>This is the home page</div>
+  </template>
+  <template slot="page" route-path="/about-us">
+    <div>This is the about-us page</div>
+  </template>
+  <template slot="page" route-path="/products">
+    <div>This is the products page</div>
+  </template>
+  <div slot="viewport"></div>
+</app-router>
+```
+
+The app router path is based on the `location.hash` so the path section in your browser's address bar needs to start with the `#` character.
+So for example, if your `index.html` file is served up from the URL `http://mywebsite.com`, then, to activate the `/products` route as in the example above, you would need to type the URL `http://mywebsite.com#/products`.
+
+**Attributes of app-router**
+
+- `default-page`: The path/route of the default page to send the user to in case no routes are matched. Commonly used to point to a `/page-not-found` page. For the home page, it's typically recommended to create a page template with `route-path=""` instead.
+- `debounce-delay`: The number of milliseconds to wait before changing the route. This can help to avoid multiple renders if the route changes rapidly (e.g. when doing hard redirects). Defaults to 100ms.
+
+**Attributes of slotted page templates**
+
+- `redirect`: An optional path/route which this page should redirect to. Note that the content of this page will not be shown so it should always be empty.
+- `auth-redirect`: An optional path/route which this page should redirect to if the user is authenticated. If the user is not authenticated, then the content of the template will be displayed as normal.
+- `no-auth-redirect`: An optional path/route which this page should redirect to if the user is not authenticated. If the user is authenticated, then the content of the template will be displayed as normal.
+- `hard-redirect`: An optional, additional attribute which can be specified alongside a `redirect`, `auth-redirect` or `no-auth-redirect` attribute to ensure that any redirect will change the URL in the address bar. Redirects are `soft` redirects by default; this means that they redirect the user to the target page but keep the current URL path unchanged.
+
 ### socket-provider
 
 A top level component which connects to your Saasufy service and inside which you can place other components which depends on Saasufy data.
 A Saasufy component which integrates with data from Saasufy is known as a `socket-consumer` and must always be placed inside a `socket-provider` element (although it does not have to be a direct child).
 
+**Example usage**
+
+```html
+<socket-provider url="wss://saasufy.com/sid7890/socketcluster/">
+  <!-- Elements which rely on Saasufy data go here. -->
+</socket-provider>
+```
+
+**Attributes**
+
+- `url` (required): Specifies the URL for the Saasufy service to use as the data store for all components which are placed inside it.
+- `auth-token-name`: Allows you to specify a custom key for your token - This will be used as the key in localStorage. You generally do not need to set this attribute. It is intended for situations were an app has multiple `socket-provider` elements connecting different services with different/separate authentication flows.
+
 ### collection-browser
 
 Used for rendering collections as lists, tables or other sequences based on a specific view using a template.
 Supports pagination by allowing you to specify custom buttons or links to navigate between pages.
 Can also perform basic CRUD operations such as deleting or creating records by listening for events from child components.
 
+**Example usage**
+
+```html
+<collection-browser
+  collection-type="Chat"
+  collection-fields="username,message,createdAt"
+  collection-view="recentView"
+  collection-view-params=""
+  collection-page-size="50"
+>
+  <template slot="item">
+    <div>
+      <div class="chat-username">
+        <b>{{Chat.username}}</b>
+      </div>
+      <div class="chat-message">{{Chat.message}}</div>
+      <div class="chat-created-at">{{date(Chat.createdAt)}}</div>
+    </div>
+  </template>
+
+  <div slot="viewport" class="chat-viewport"></div>
+
+  <div slot="loader" class="loading-spinner-container">
+    <div class="spinning">&#8635;</div>
+  </div>
+</collection-browser>
+```
+
+**Attributes**
+
+- `collection-type` (required): Specifies the type of collection to be used, which defines the dataset you want to work with. This should match a `Model` available in your Saasufy service.
+- `collection-fields` (required): A comma-separated list of fields from the `Model` that you want to display or use. This lets you pick specific pieces of data from your collection to work with.
+- `collection-view` (required): Determines the view of the collection. This should match one of the `Views` defined in your Saasufy service under that specific `Model`.
+- `collection-view-params` (required): Parameters for the view, specified as comma-separated key-value pairs (e.g., key1=value1,key2=value2). These parameters can customize the behavior of the collection view. The keys must match `paramFields` specified in your Saasufy service under the relevant `View`.
+- `collection-page-size`: Sets how many items from the collection are displayed at once. This is useful for pagination, allowing users to navigate through large sets of data in chunks.
+- `collection-page-offset`: Indicates the current page offset in the collection's data. It’s like telling the browser which page of data you want to display initially.
+- `type-alias`: Allows you to provide an alternative name for your `Model` to use when injecting values inside the template. This is useful for situations where you may have multiple `collection-browser` elements and/or `model-viewer` elements of the same type nested inside each other and want to avoid `Model` name clashes in the nested template definitions. For example, if the `type-alias` in the snippet above was set to `SubChat`, then `{{Chat.message}}` would become `{{SubChat.message}}`.
+- `hide-error-logs`: A flag that, when present, suppresses error logs from being printed to the console. This can be used to keep the user interface clean of technical messages.
+- `max-show-loader`: If this attribute is present, your slotted `loader` element will be shown as often as possible; this includes situations where the collection is merely refreshing itself. It is disabled by default.
+
 ### collection-adder
 
 A form component for inserting data into collections.

package/collection-adder.js

@@ -10,7 +10,10 @@ class CollectionAdder extends SocketConsumer {
       text: String,
       textarea: String,
       checkbox: Boolean,
-      number: Number
+      number: Number,
+      radio: String,
+      select: String,
+      'text-select': String
     };
     this.fieldPartsRegExp = /("[^"]*"|'[^']*'|\([^)]*\)|[^,()"']+)+/g;
     this.inputTypeWithParamsRegExp = /^([^()]*)(\(([^)]*)\))?/;
@@ -33,10 +36,14 @@ class CollectionAdder extends SocketConsumer {
       'collection-type',
       'collection-fields',
       'field-labels',
+      'option-labels',
       'model-values',
       'submit-button-label',
       'hide-submit-button',
-      'success-message'
+      'success-message',
+      'autocapitalize',
+      'autocorrect',
+      'trim-spaces'
     ];
   }
 
@@ -94,8 +101,19 @@ class CollectionAdder extends SocketConsumer {
     messageContainer.classList.remove('error');
     messageContainer.textContent = '';
 
+    let radioInputs = [...this.querySelectorAll('.collection-adder-radio')];
+    let radioData = {};
+    for (let radio of radioInputs) {
+      if (radio.checked) {
+        radioData[radio.name] = radio.value;
+      }
+    }
+
+    let trimSpaces = this.hasAttribute('trim-spaces');
+
     let newModelData = {
       ...this.modelFieldValues,
+      ...radioData,
       ...Object.fromEntries(
         [...this.querySelectorAll('.collection-adder-input')]
           .filter(input => input.value !== '')
@@ -108,7 +126,11 @@ class CollectionAdder extends SocketConsumer {
             } else {
               value = input.value;
             }
-            return [ input.name, Type(value) ];
+            let sanitizedValue = Type(value);
+            if (trimSpaces && typeof sanitizedValue === 'string') {
+              sanitizedValue = sanitizedValue.trim();
+            }
+            return [ input.name, sanitizedValue ];
           })
       )
     };
@@ -171,6 +193,19 @@ class CollectionAdder extends SocketConsumer {
       fieldValues: modelFieldLabels
     } = this.getFieldDetails(this.getAttribute('field-labels'));
 
+    let {
+      fieldValues: optionLabels
+    } = this.getFieldDetails(this.getAttribute('option-labels'));
+
+    let autocapitalize = this.getAttribute('autocapitalize');
+    let autocorrect = this.getAttribute('autocorrect');
+
+    let extraAttributesString = `${
+      autocapitalize ? ` autocapitalize="${autocapitalize}"` : ''
+    }${
+      autocorrect ? ` autocorrect="${autocorrect}"` : ''
+    }`;
+
     this.modelFieldValues = modelFieldValues;
 
     if (this.collection) this.collection.destroy();
@@ -192,6 +227,7 @@ class CollectionAdder extends SocketConsumer {
         inputTypeParams = inputTypeParts[3] ? inputTypeParts[3].split(',') : [];
       }
       let inputLabel = modelFieldLabels[field] == null ? field : modelFieldLabels[field];
+      let optionLabel = optionLabels[field] == null ? 'Options' : optionLabels[field];
       if (inputType === 'checkbox') {
         items.push(
           `<label>
@@ -205,6 +241,18 @@ class CollectionAdder extends SocketConsumer {
             }" />
           </label>`
         );
+      } else if (inputType === 'select') {
+        items.push(
+          `<label>
+            ${
+              inputLabel
+            }
+            <select name="${field}" class="collection-adder-input collection-adder-select">
+              <option value="" selected disabled hidden>${optionLabel}</option>
+              ${inputTypeParams.map(param => `<option value="${param}">${param}</option>`).join('')}
+            </select>
+          </label>`
+        );
       } else if (inputType === 'text-select') {
         items.push(
           `<div class="collection-adder-select-text-row">
@@ -212,20 +260,43 @@ class CollectionAdder extends SocketConsumer {
               field
             }" placeholder="${
               inputLabel
-            }" />
+            }"${extraAttributesString} />
             <select class="collection-adder-select">
-              <option value="" selected disabled hidden>Options</option>
-              ${inputTypeParams.map(param => `<option value="${param}">${param}</option>`)}
+              <option value="" selected disabled hidden>${optionLabel}</option>
+              ${inputTypeParams.map(param => `<option value="${param}">${param}</option>`).join('')}
             </select>
           </div>`
         );
+      } else if (inputType === 'radio') {
+        items.push(
+          `
+            ${
+              inputLabel
+            }
+            ${
+              inputTypeParams.map(
+                param => (
+                  `<label>
+                    <input class="collection-adder-radio" type="${
+                      inputType
+                    }" name="${
+                      field
+                    }" value=${
+                      param
+                    } />
+                    ${param}
+                  </label>`
+                )
+              ).join('')
+            }`
+        );
       } else if (inputType === 'textarea') {
         items.push(
           `<textarea class="collection-adder-input" name="${
             field
           }" placeholder="${
             inputLabel
-          }"></textarea>`
+          }"${extraAttributesString}></textarea>`
         );
       } else {
         items.push(
@@ -235,7 +306,7 @@ class CollectionAdder extends SocketConsumer {
             field
           }" placeholder="${
             inputLabel
-          }" />`
+          }"${extraAttributesString} />`
         );
       }
     }

package/input-provider.js

@@ -28,7 +28,9 @@ class InputProvider extends HTMLElement {
       'debounce-delay',
       'options',
       'value',
-      'height'
+      'height',
+      'autocapitalize',
+      'autocorrect'
     ];
   }
 
@@ -59,6 +61,8 @@ class InputProvider extends HTMLElement {
   render() {
     this.innerHTML = '';
     let inputId = this.getAttribute('input-id');
+    let autocapitalize = this.getAttribute('autocapitalize');
+    let autocorrect = this.getAttribute('autocorrect');
     let inputList = this.getAttribute('list');
     let type = this.getAttribute('type') || 'text';
     let placeholder = this.getAttribute('placeholder');
@@ -97,6 +101,12 @@ class InputProvider extends HTMLElement {
     if (inputId) {
       this.inputElement.setAttribute('id', inputId);
     }
+    if (autocapitalize) {
+      this.inputElement.setAttribute('autocapitalize', autocapitalize);
+    }
+    if (autocorrect) {
+      this.inputElement.setAttribute('autocorrect', autocorrect);
+    }
     if (placeholder) {
       this.inputElement.setAttribute('placeholder', placeholder);
     }

package/model-input.js

@@ -36,7 +36,9 @@ class ModelInput extends SocketConsumer {
       'enable-rebound',
       'options',
       'height',
-      'hide-error-logs'
+      'hide-error-logs',
+      'autocapitalize',
+      'autocorrect'
     ];
   }
 
@@ -71,6 +73,8 @@ class ModelInput extends SocketConsumer {
     let modelInstanceProperty = this.getAttribute('model-instance-property');
     let showErrorMessage = this.hasAttribute('show-error-message');
     let inputId = this.getAttribute('input-id');
+    let autocapitalize = this.getAttribute('autocapitalize');
+    let autocorrect = this.getAttribute('autocorrect');
     let inputList = this.getAttribute('list');
     let type = this.getAttribute('type') || 'text';
     let placeholder = this.getAttribute('placeholder');
@@ -188,6 +192,12 @@ class ModelInput extends SocketConsumer {
     if (inputId) {
       this.inputElement.setAttribute('id', inputId);
     }
+    if (autocapitalize) {
+      this.inputElement.setAttribute('autocapitalize', autocapitalize);
+    }
+    if (autocorrect) {
+      this.inputElement.setAttribute('autocorrect', autocorrect);
+    }
     if (placeholder) {
       this.inputElement.setAttribute('placeholder', placeholder);
     }
@@ -208,19 +218,23 @@ class ModelInput extends SocketConsumer {
     };
   }
 
+  updateInputElement(inputElement, fieldValue) {
+    let consumers = this.getAttribute('consumers');
+    if (inputElement.type === 'checkbox') {
+      let checked = !!fieldValue;
+      inputElement.checked = checked;
+      updateConsumerElements(this.parentElement, consumers, checked);
+    } else {
+      let defaultValue = this.getAttribute('default-value') || '';
+      inputElement.value = fieldValue == null ? defaultValue : fieldValue;
+      updateConsumerElements(this.parentElement, consumers, inputElement.value);
+    }
+  }
+
   syncInputElementWithModel(inputElement, model, fieldName, messageContainerElement) {
     if (model.isLoaded) {
-      let consumers = this.getAttribute('consumers');
       let fieldValue = model.value[fieldName];
-      if (inputElement.type === 'checkbox') {
-        let checked = !!fieldValue;
-        inputElement.checked = checked;
-        updateConsumerElements(this.parentElement, consumers, checked);
-      } else {
-        let defaultValue = this.getAttribute('default-value') || '';
-        inputElement.value = fieldValue == null ? defaultValue : fieldValue;
-        updateConsumerElements(this.parentElement, consumers, inputElement.value);
-      }
+      this.updateInputElement(inputElement, fieldValue);
     }
     let stopSaving = this.saveInputElementOnEdit(inputElement, model, fieldName, messageContainerElement);
     let changeConsumer = model.listener('change').createConsumer();
@@ -228,17 +242,8 @@ class ModelInput extends SocketConsumer {
       for await (let event of changeConsumer) {
         let hasFocus = document.activeElement === this.inputElement;
         if (event.resourceField !== fieldName || (hasFocus && !event.isRemote)) continue;
-        let consumers = this.getAttribute('consumers');
         let fieldValue = model.value[fieldName];
-        if (inputElement.type === 'checkbox') {
-          let checked = !!fieldValue;
-          inputElement.checked = checked;
-          updateConsumerElements(this.parentElement, consumers, checked);
-        } else {
-          let defaultValue = this.getAttribute('default-value') || '';
-          inputElement.value = fieldValue == null ? defaultValue : fieldValue;
-          updateConsumerElements(this.parentElement, consumers, inputElement.value);
-        }
+        this.updateInputElement(inputElement, fieldValue);
       }
     })();
     return () => {
@@ -304,7 +309,7 @@ class ModelInput extends SocketConsumer {
     inputElement.addEventListener('change', onInputChange);
 
     let onInputKeyUp;
-    if (inputElement.type !== 'checkbox') {
+    if (inputElement.type !== 'checkbox' && inputElement.type !== 'select') {
       onInputKeyUp = async (event) => {
         debounce(async () => {
           try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saasufy-components",
-  "version": "2.6.2",
+  "version": "2.8.0",
   "description": "Components for Saasufy.",
   "main": "index.js",
   "scripts": {