saasufy-components 2.14.0 → 2.15.1

package/README.md

@@ -27,7 +27,6 @@ Components for Saasufy
 
 ### Display groups
 - [render-group](#render-group)
-- [conditional-group](#conditional-group)
 - [if-group](#if-group)
 - [switch-group](#switch-group)
 - [collection-adder-group](#collection-adder-group)
@@ -69,7 +68,6 @@ To use components, you just need to include them into your `.html` file inside y
 <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>
 <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/if-group.js" type="module" defer></script>
 <script src="https://saasufy.com/node_modules/saasufy-components/switch-group.js" type="module" defer></script>
 <script src="https://saasufy.com/node_modules/saasufy-components/collection-adder-group.js" type="module" defer></script>
@@ -332,14 +330,97 @@ In the example above, the name of the first element can be accessed with `{{Cate
 
 Used for displaying and editing a single field of a model instance in real time.
 
+**Example usage**
+
+```html
+<model-input
+  type="text"
+  model-type="Product"
+  model-id="{{productId}}"
+  model-field="name"
+  placeholder="Product name"
+></model-input>
+```
+
+**Attributes**
+
+- `model-type` (required): Specifies the type of model to bind to. This should match a `Model` available in your Saasufy service.
+- `model-id` (required): The id of the model instance/record to bind to.
+- `model-field` (required): The field of the model instance/record to bind to for reading and updating.
+- `debounce-delay`: The delay in milliseconds to wait before sending an update to the server. This is useful to batch multiple updates together (as is common when user is typing). Default is 300ms.
+- `enable-rebound`: By default, real-time updates performed via `model-input` components are not sent back to the publishing client as it is assumed that state changes are either localized to a single `model-input` component or shared with other components on the same page via the use of `consumers`, `bind-to-collection` or `bind-to-model` attributes. There may be situations where you have a specific value displayed in multiple places on the same page/screen and want them to be updated in real-time to reflect the latest value of the model field. For convenience, you can add the `enable-rebound` attribute to the `model-input` component to force real-time updates to rebound back to the publisher and this will ensure that all components on the page will receive real-time updates (will sync with each other) without having to explicitly bind them together via the front end. Note that enabling rebound comes with additional performance overheads.
+- `input-id`: Can be used to set an `id` attribute on the inner `input` element.
+- `list`: If specified, this sets the list attribute of the inner `input` element to provide input suggestions (only works with standard input elements).
+- `bind-to-model`: If this attribute exists, the `model-input` component will attempt to host its model data within the nearest compatible `model-viewer` parent component instead of creating its own model internally. This can improve efficiency/reuse of model data and provide a better user experience. For example, if the `model-input` element is re-rendered, it will not have to re-fetch its data as it will be kept inside its parent `model-viewer` component.
+- `bind-to-collection`: If this attribute exists, the `model-input` component will attempt to host its model data within the nearest compatible `collection-browser` or `collection-reducer` parent component instead of creating its own model internally. This can improve efficiency/reuse of model data and provide a better user experience. For example, if the `model-input` element is re-rendered, it will not have to re-fetch its data as it will be kept inside its parent `collection-browser` or `collection-reducer` component. Note that the parent component will take over the responsibility for cleaning up the model; this includes scenarios where the user loads a different page of the collection/view where the specified model instance is no longer present.
+- `type`: The type of the input component; can be `text`, `number`, `select`, `textarea` or `checkbox`.
+- `placeholder`: Can be used to set the placeholder text on the inner input element.
+- `consumers`: This allows you to connect this `model-input` to other elements on your page which share the same parent element. It takes a list of selectors with optional attributes to target. For example `.my-input:value` will find all elements with a `my-input` class and update their `value` attributes with the value of the `model-input` component in real-time. You can specify multiple selectors separated by commas such as `.my-input,my-div` - In this case, because attribute names are not specified, values will be injected into the `value` attribute (for input elements) or into the `innerHTML` property (for other kinds of elements). The default attribute/property depends on the element type.
+- `show-error-message`: If this attribute is present, an error message will be displayed above the input if it fails to update the value.
+- `options`: A comma-separated list of options to provide - This only works if the input type is `select`.
+- `height`: Allows you to set the height of the inner `input` element programmatically.
+- `default-value`: A default value to show the user if the underlying model field's value is null or undefined. Note that setting a default value will not affect the underlying model's value.
+- `value`: Used to set the model's value.
+- `hide-error-logs`: By default, this component will log errors to the console. If set, this attribute will suppress such errors from showing up on the console.
+- `autocapitalize`: Can be `on` or `off` - It will set the auto-capitalize attribute on the inner input element. This is useful for mobile devices to enable or disable auto-capitalization of the first character which is typed into the input element.
+- `autocorrect`: Can be `on` or `off` - It will set the auto-correct attribute on the inner input element. This is useful for mobile devices to enable or disable auto-correct.
+
 ### model-text
 
 Used to displaying a field of a model instance in real time.
 
+**Example usage**
+
+```html
+<model-text
+  type="text"
+  model-type="Product"
+  model-id="{{productId}}"
+  model-field="name"
+></model-text>
+```
+
+**Attributes**
+
+- `model-type` (required): Specifies the type of model to bind to. This should match a `Model` available in your Saasufy service.
+- `model-id` (required): The id of the model instance/record to bind to.
+- `model-field` (required): The field of the model instance/record to bind to for reading.
+- `bind-to-model`: If this attribute exists, the `model-text` component will attempt to fetch its model data from the nearest compatible `model-viewer` parent component instead of creating its own model internally. This can improve efficiency/reuse of model data and provide a better user experience. For example, if the `model-text` element is re-rendered, it will not have to re-fetch its data as it will be kept inside its parent `model-viewer` component.
+- `bind-to-collection`: If this attribute exists, the `model-text` component will attempt to fetch its model data from the nearest compatible `collection-browser` or `collection-reducer` parent component instead of creating its own model internally. This can improve efficiency/reuse of model data and provide a better user experience. For example, if the `model-text` element is re-rendered, it will not have to re-fetch its data as it will be kept inside its parent `collection-browser` or `collection-reducer` component. Note that the parent component will take over the responsibility for cleaning up the model; this includes scenarios where the user loads a different page of the collection/view where the specified model instance is no longer present.
+- `hide-error-logs`: By default, this component will log errors to the console. If set, this attribute will suppress such errors from showing up on the console.
+
 ### model-viewer
 
 Used for rendering a single model resource using a template. This is the single-model alternative to the `collection-browser` which works with collections of models.
 
+**Example usage**
+
+```html
+<model-viewer
+  model-type="Product"
+  model-id="{{modelId}}"
+  model-fields="name,desc,qty"
+>
+  <template slot="item">
+    <div>
+      <div>Name: {{Product.name}}</div>
+      <div>Description: {{Product.desc}}</div>
+      <div>Quantity: {{Product.qty}}</div>
+    </div>
+  </template>
+
+  <div slot="viewport"></div>
+</model-viewer>
+```
+
+**Attributes**
+
+- `model-type` (required): Specifies the type of model to bind to. This should match a `Model` available in your Saasufy service.
+- `model-id` (required): The id of the model instance/record to bind to.
+- `model-fields` (required): A comma-separated list of fields to bind to. Note that unlike with `model-input` and `model-text`, the attribute name is plural and can bind to multiple fields.
+- `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 `model-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 `MyProduct`, then `{{Product.name}}` would become `{{MyProduct.name}}`.
+- `hide-error-logs`: A flag which, when present, suppresses error logs from being printed to the console.
+
 ### input-provider
 
 An input component which can pass data to other components (or HTML elements) via custom attributes.
@@ -347,6 +428,31 @@ A common use case for it is to pass user input to `collection-browser` or `model
 This component can be configured to provide its data to multiple components (consumers) via custom attributes.
 Note that an `input-provider` only targets elements which are downstream from its parent element in the HTML hierarchy.
 
+**Example usage**
+
+```html
+<input-provider
+  type="text"
+  consumers=".my-input"
+  value="Hello world!"
+  placeholder="Message"
+></input-provider>
+```
+
+**Attributes**
+
+- `input-id`: Can be used to set an `id` attribute on the inner `input` element.
+- `list`: If specified, this sets the list attribute of the inner `input` element to provide input suggestions (only works with standard input elements).
+- `type`: The type of the input component; can be `text`, `number`, `select`, `textarea` or `checkbox`.
+- `placeholder`: Can be used to set the placeholder text on the inner input element.
+- `consumers`: This allows you to connect this `input-provider` to other elements on your page which share the same parent element. It takes a list of selectors with optional attributes to target. For example `.my-input:value` will find all elements with a `my-input` class and update their `value` attributes with the value of the `input-provider` component in real-time. You can specify multiple selectors separated by commas such as `.my-input,my-div` - In this case, because attribute names are not specified, values will be injected into the `value` attribute (for input elements) or into the `innerHTML` property (for other kinds of elements). The default attribute/property depends on the element type.
+- `debounce-delay`: The delay in milliseconds to wait before triggering a change event. This is useful to batch multiple updates together (as is common when user is typing). Default is 800ms.
+- `options`: A comma-separated list of options to provide - This only works if the input type is `select`.
+- `height`: Allows you to set the height of the inner `input` element programmatically.
+- `value`: Used to set the input's value.
+- `autocapitalize`: Can be `on` or `off` - It will set the auto-capitalize attribute on the inner input element. This is useful for mobile devices to enable or disable auto-capitalization of the first character which is typed into the input element.
+- `autocorrect`: Can be `on` or `off` - It will set the auto-correct attribute on the inner input element. This is useful for mobile devices to enable or disable auto-correct.
+
 ### log-in-form
 
 A form component which allows end-users to authenticate themselves into your app using the Saasufy blockchain or any Capitalisk-based blockchain.
@@ -355,47 +461,221 @@ Once a user is authenticated, they will be able to access restricted data (as sp
 It's also possible to specify a `success-location-hash` attribute to trigger a client-side redirect upon successful authentication.
 The change in the location hash can then be detected by an `app-router` to switch to a different page upon successful login.
 
+**Example usage**
+
+```html
+<log-in-form
+  hostname="capitalisk.com"
+  port="443"
+  network-symbol="clsk"
+  chain-module-name="capitalisk_chain"
+  secure="true"
+></log-in-form>
+```
+
+**Attributes**
+
+- `hostname` (required): The hostname of the blockchain node to match authentication details against.
+- `port` (required): The port of the blockchain node to match authentication details against. Should be 80 for HTTP/WS or 443 for HTTPS/WSS.
+- `network-symbol` (required): The symbol of the target blockchain.
+- `chain-module-name` (required): The module name used by the target blockchain.
+- `secure` (required): Should be `true` or `false` depending on whether or not the node is exposed over HTTP/WS or HTTPS/WSS.
+- `auth-timeout`: The maximum number of milliseconds to wait for authentication to complete. Defaults to 10000 (10 seconds).
+- `success-location-hash`: If authentication is successful, the browser's `location.hash` will be set to this value. It can be used to redirect the user to their dashboard, for example.
+
 ### log-out
 
 A component which can be placed inside a `socket-provider` to deauthenticate the socket (e.g. on click).
 
-Example usage: `<log-out onclick="logOut()"><a href="javascript:void(0)">Log out</a></log-out>`
+**Example usage**
+
+```html
+<log-out onclick="logOut()"><a href="javascript:void(0)">Log out</a></log-out>
+```
 
 ### oauth-link
 
 A link to initiate an OAuth flow to authenticate a user as part of log in. Can support a range of different OAuth providers.
 
+**Example usage**
+
+```html
+<oauth-link class="log-in-oauth-section" provider="github" client-id="dabb51f8af31a0bc53bf">
+  <template slot="item">
+    <a href="https://github.com/login/oauth/authorize?client_id={{oauth.clientId}}&state={{oauth.state}}">
+      Log in with GitHub
+    </a>
+  </template>
+  <div slot="viewport"></div>
+</oauth-link>
+```
+
+**Attributes**
+
+- `provider` (required): The name of the provider. It must match the provider name specified on the `Authentication` page of your Saasufy control panel and also the value provided to the `oauth-handler` component at the end of the OAuth flow.
+- `client-id` (required): This is the client ID from the third-party OAuth provider.
+- `state-size`: This allows you to control the size (in bytes) of the random state string which is passed to the OAuth provider as part of the OAuth flow. Defaults to 20.
+- `state-session-storage-key`: The state string is stored in the browser's `sessionStorage` under this key. Defaults to `oauth.state`. It must match the value provided to the `oauth-handler` component at the end of the OAuth flow.
+
 ### oauth-handler
 
 This component handles the final stage of OAuth and then redirects the user to the relevant page/URL if successful.
 When using an OAuth provider, the callback URL which you register with the provider must lead the user back to a page which contains this `oauth-handler` component.
 
+**Example usage**
+
+```html
+<oauth-handler provider="github" success-location-hash="/chat"></oauth-handler>
+```
+
+**Attributes**
+
+- `provider` (required): The name of the provider. It must match the provider name specified on the `Authentication` page of your Saasufy control panel and also the value provided to the `oauth-link` component at the start of the OAuth flow.
+- `success-location-hash`: If authentication is successful, the browser's `location.hash` will be set to this value. It can be used to redirect the user to their dashboard, for example.
+- `success-url`: If authentication is successful, the browser's `location.href` will be set to this value. It can be used to redirect the user to their dashboard, for example.
+- `navigate-event-path`: If authentication is successful and a path is set via this attribute, the component will emit a `navigate` event which will bubble up the component hierarchy and can be used by a parent component to perform the success redirection. This approach can be used as an alternative to `success-location-hash` or `success-url` for doing the final redirect.
+- `state-session-storage-key`: The state string is stored in the browser's `sessionStorage` under this key. Defaults to `oauth.state`. It must match the value provided to the `oauth-link` component at the start of the OAuth flow.
+- `code-param-name`: The name of the query parameter which holds the `code` as provided by the OAuth provider within the OAuth callback URL. Defaults to `code`.
+- `state-param-name`: The name of the query parameter which holds the `state` as provided by the OAuth provider within the OAuth callback URL. Defaults to `state`.
+- `auth-timeout`: The number of milliseconds to wait for authentication to complete before timing out. Defaults to 10000 (10 seconds).
+
 ### render-group
 
 A component which can be used to guarantee that certain children components are always rendered at the same time (once they are loaded) to provide a smooth user experience.
 
-### conditional-group
+**Example usage**
 
-A component which exposes a `show-content` property which can be set to true or false to show or hide its content.
-It's intended to be placed inside a `model-viewer`, `collection-browser` or `collection-reducer` component such that the true/false value of the `show-content` attribute can be computed using a template `{{expression}}` placeholder. Unlike `if-group`, this component does not require a template, however, the trade-off is that the slotted content will be pre-processed by the browser even when the expression is false. This may not be suitable if you want to (for example) render child images conditionally because the browser will preload images based on their `src` attributes, even if they are not shown.
+```html
+<render-group wait-for="1,2,3">
+  <model-input
+    type="text"
+    load-id="1"
+    model-type="Product"
+    model-id="{{productId}}"
+    model-field="name"
+  ></model-input>
+  <model-input
+    type="text"
+    load-id="2"
+    model-type="Product"
+    model-id="{{productId}}"
+    model-field="desc"
+  ></model-input>
+  <model-input
+    type="number"
+    load-id="3"
+    model-type="Product"
+    model-id="{{productId}}"
+    model-field="qty"
+  ></model-input>
+</render-group>
+```
+
+**Attributes**
+
+- `wait-for` (required): A list of components to wait for before rendering based on their `load-id` attributes.
+The `render-group` will only render its content once all the components specified via this attribute have finished loading their data.
 
 ### if-group
 
 A component which exposes a `show-content` property which can be set to true or false to show or hide its content.
-It's intended to be placed inside a `model-viewer`, `collection-browser` or `collection-reducer` component such that the true/false value of the `show-content` attribute can be computed using a template `{{expression}}` placeholder. Unlike `conditional-group`, this component requires a template and a viewport to be slotted in. The content of the template will not be processed unless the `show-content` condition is met.
+It's intended to be placed inside a `model-viewer`, `collection-browser` or `collection-reducer` component such that the true/false value of the `show-content` attribute can be computed using a template `{{expression}}` placeholder. This component requires a template and a viewport to be slotted in. The content of the template will not be processed unless the `show-content` condition is met.
+
+**Example usage**
+
+```html
+
+```
 
 ### switch-group
 
 A component which exposes a `show-cases` property which can be set to key-value pairs in the format `key1=true,key2=false`. It can be used to conditionally display multiple slotted elements based on multiple conditions. It helps to keep HTML clean when the conditions are complex.
 This element is intended to be placed inside a `model-viewer`, `collection-browser` or `collection-reducer` component such that the true/false values of the `show-cases` attribute can be computed using template `{{expression}}` placeholders. This component requires one or more templates and a viewport to be slotted in. The content of the templates will not be processed unless the `show-cases` condition is met. All templates must have a `slot="content"` attribute and a name attribute in the format `name="key1"` where the value `key1` corresponds to the key specified inside the `show-cases` attribute of the `switch-group`.
 
+**Example usage**
+
+```html
+<switch-group show-cases="image={{!!Section.imageURL}},text={{!!Section.text}}">
+  <template slot="content" name="image">
+    <img src="{{Section.imageURL}}" alt="{{Section.imageDesc}}" />
+  </template>
+  <template slot="content" name="text">
+    <div>{{Section.text}}</div>
+  </template>
+  <div slot="viewport"></div>
+</switch-group>
+```
+
 ### collection-adder-group
 
 A component which can be used to group together multiple `collection-adder` components. It can be used to insert multiple records into a collection via a single button click.
 
+**Example usage**
+
+```html
+<!--
+  This collection-adder-group adds two pre-defined records into a Product
+  collection using a single button click. This example assumes that the name
+  field is the only required field in the Product model.
+-->
+<collection-adder-group>
+  <collection-adder
+    slot="collection-adder"
+    collection-type="Product"
+    model-values="name=Flour"
+    hide-submit-button
+  ></collection-adder>
+  <collection-adder
+    slot="collection-adder"
+    collection-type="Product"
+    model-values="name=Egg"
+    hide-submit-button
+  ></collection-adder>
+  <collection-adder
+    slot="collection-adder"
+    collection-type="Product"
+    model-values="name=Milk"
+    hide-submit-button
+  ></collection-adder>
+  <div slot="error-container"></div>
+  <input slot="submit-button" type="button" value="Add pancake ingredients">
+</collection-adder-group>
+```
+
 ### confirm-modal
 
-A modal component to prompt the user for confirmation before performing sensitive operations.
+A modal component to prompt the user for confirmation before performing sensitive operations. Can be slotted into a `collection-browser` component.
+
+**Example usage**
+
+```html
+<collection-browser
+  collection-type="Product"
+  collection-fields="name,qty"
+  collection-view="alphabeticalView"
+  collection-view-params=""
+  collection-page-size="50"
+>
+  <template slot="item">
+    <div>
+      <div class="chat-message">{{Product.name}}</div>
+      <collection-deleter model-id="{{Product.id}}" confirm-message="Are you sure you want to delete the {{Product.name}} product?" onclick="confirmDeleteItem()">&#x2715;</collection-deleter>
+    </div>
+  </template>
+
+  <div slot="viewport" class="chat-viewport"></div>
+
+  <!-- The confirm-modal element must be specified here with slot="modal" to prompt the user for confirmation -->
+  <confirm-modal slot="modal" title="Delete confirmation" message="" confirm-button-label="Delete"></confirm-modal>
+</collection-browser>
+```
+
+**Attributes**
+
+- `title`: The text to show in the modal's title bar.
+- `message`: The text to show as the modal's main content.
+- `confirm-button-label`: The text to use as the confirm button label.
+- `cancel-button-label`: The text to use as the cancel button label.
 
 ### overlay-modal
 

package/collection-browser.js

@@ -1,6 +1,6 @@
 import { SocketConsumer } from './socket.js';
 import AGCollection from '/node_modules/ag-collection/ag-collection.js';
-import { renderTemplate } from './utils.js';
+import { renderTemplate, convertStringToFieldParams } from './utils.js';
 
 const DEFAULT_RELOAD_DELAY = 0;
 
@@ -226,11 +226,8 @@ class CollectionBrowser extends SocketConsumer {
     let collectionReloadDelay = Number(
       this.getAttribute('collection-reload-delay') || DEFAULT_RELOAD_DELAY
     );
-    let viewParams = Object.fromEntries(
-      collectionViewParams.split(',')
-        .map(pair => pair.split('='))
-        .filter(([field]) => field)
-    );
+    let { fieldValues: viewParams } = convertStringToFieldParams(collectionViewParams);
+
     if (this.collection) this.collection.destroy();
     this.isStale = true;
 

package/collection-reducer.js

@@ -1,6 +1,6 @@
 import { SocketConsumer } from './socket.js';
 import AGCollection from '/node_modules/ag-collection/ag-collection.js';
-import { renderTemplate } from './utils.js';
+import { renderTemplate, convertStringToFieldParams } from './utils.js';
 
 const DEFAULT_RELOAD_DELAY = 0;
 
@@ -183,11 +183,8 @@ class CollectionReducer extends SocketConsumer {
     let collectionReloadDelay = Number(
       this.getAttribute('collection-reload-delay') || DEFAULT_RELOAD_DELAY
     );
-    let viewParams = Object.fromEntries(
-      collectionViewParams.split(',')
-        .map(pair => pair.split('='))
-        .filter(([field]) => field)
-    );
+    let { fieldValues: viewParams } = convertStringToFieldParams(collectionViewParams);
+
     if (this.collection) this.collection.destroy();
     this.isStale = true;
 

package/confirm-modal.js

@@ -13,7 +13,7 @@ class ConfirmModal extends HTMLElement {
   }
 
   static get observedAttributes() {
-    return [ 'message', 'title', 'confirm-button-label' ];
+    return [ 'message', 'title', 'confirm-button-label', 'cancel-button-label' ];
   }
 
   attributeChangedCallback(name, oldValue, newValue) {
@@ -32,9 +32,10 @@ class ConfirmModal extends HTMLElement {
   }
 
   render() {
-    let message = this.getAttribute('message');
+    let message = this.getAttribute('message') || '';
     let title = this.getAttribute('title') || '';
     let confirmButtonLabel = this.getAttribute('confirm-button-label') || 'Confirm';
+    let cancelButtonLabel = this.getAttribute('cancel-button-label') || 'Cancel';
 
     this.innerHTML = `
       <overlay-modal class="${this.hidden ? 'hidden' : 'visible'}">
@@ -43,7 +44,7 @@ class ConfirmModal extends HTMLElement {
           <div>${message}</div>
           <div class="confirm-modal-buttons-container">
             <input class="modal-confirm-button" type="button" value="${confirmButtonLabel}" />
-            <input class="modal-cancel-button" type="button" value="Cancel" />
+            <input class="modal-cancel-button" type="button" value="${cancelButtonLabel}" />
           </div>
         </div>
       </overlay-modal>

package/package.json

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