@quandis/qbo4.ui 4.0.1-CI-20240426-215901 → 4.0.1-CI-20240429-172951

package/package.json

@@ -3,7 +3,7 @@
   "author": "Quandis, Inc.",
   "license": "MIT",
   "type": "module",
-  "version": "4.0.1-CI-20240426-215901",
+  "version": "4.0.1-CI-20240429-172951",
   "workspaces": [
     "code"
   ],

package/readme.md

@@ -34,6 +34,38 @@ const address = getApiService('geoApi').fetch('', { value: '1600 Pennsylvania Av
 > - The `json` object can be a string, or an object. If it is an object, it will be stringified.
 > - Additional headers can be specified in the `qbo-api` component.
 
+## Default API Endpoint
+
+The `qbo4-ui` package will automatically register a default API endpoint using the window.location.
+So, if your endpoints are on the same page as your web page, you can use the default API endpoint.
+
+```typescript
+// This will point to the same website you are on.
+const defaultApi = getApiService('default');
+```
+
+## Reusing the same API with different paths
+
+You may register an API, and then reuse it with different paths:
+
+```html
+<qbo-api name="qms" method="POST" apiEndpoint="https://services.quandis.io/api/military/">
+    <header name="Accept">application/json</header>
+</qbo-api>
+```
+
+Then, in typescript:
+
+```typescript
+import { getApiService } from '@quandis/qbo4.ui';
+const qmsSearch = getApiService('api://qms/scra/instant/{clientID}');
+const qmsHealth = getApiService('api://qms/scra/healthcheck');
+```
+
+In this example, the `qms` is cloned in `getApiService`, and the `relativePath` is substituted into the `apiEndpoint`.
+
+## Custom API Services
+
 You can write your own `IApiService` class, and register it to qbo's DI container:
 
 ```typescript
@@ -52,6 +84,80 @@ export class MyApi implements IApiService {
 services.container.registerInstance<IApiService>('myApi', new MyApi());
 ```
 
+# QboFormElement
+
+The `QboFormElement` web component is used to wrap form elements, 
+and present them to a <code>form</code> element upon submission.
+
+For example, a credit card components might look like this:
+
+```typescript
+export class QboPayment extends QboFormElement {
+    render() {
+        return html`<slot>
+    <input type="text" name="Number" placeholder="Card Number" required />
+    <input type="text" name="Expiry" placeholder="MM/YY" required />
+    <input type="text" name="CVC" placeholder="CVC" required />
+    <input type="text" name="Name" placeholder="Name on Card" required />
+</slot>`;
+    }
+}
+```
+
+> This is a simple example without any credit card validation logic.
+
+This can be used within a form multiple times:
+
+```html
+<form id='fact'>
+    <qbo-payment name="primary"></qbo-payment>
+    <qbo-payment name="backup"></qbo-payment>
+</form>
+```
+
+Upon submission, the form will contain the following fields:
+
+```json
+{
+	"primaryNumber": "...",
+	"primaryExpiry": "...",
+	"primaryCVC": "...",
+	"primaryName": "..."
+	"backupNumber": "...",
+	"backupExpiry": "...",
+	"backupCVC": "...",
+	"backupName": "..."
+}
+```
+
+> The `name` attribute is used to prefix the field names for any fields in the `ShadowDOM`.
+
+If you render elements as children of a `QboFormElement`, they will be directly visible to the form:
+
+```html
+<form id='fact'>
+    <qbo-payment name="primary">
+      Number: <input type="text" name="myNumber" placeholder="Card Number" required value="1234567890">
+    </qbo-payment>
+    <qbo-payment name="backup"></qbo-payment>
+</form>
+```
+
+Upon submission, the form will contain the following fields:
+
+```json
+{
+	"myNumber": "...",
+	"backupNumber": "...",
+	"backupExpiry": "...",
+	"backupCVC": "...",
+	"backupName": "..."
+}
+```
+
+> The `myNumber` field is slotted into the `ShadowDOM` from the normal markup, and is visible to the form.
+Thus, `myNumber` is not prefixed with `primary`.
+
 # Form Validation
 
 Modern browers support a very rich set of [form valiation functionality](https://www.w3.org/TR/2009/WD-html5-20090825/forms.html#attr-input-pattern); use it!

package/src/qbo/IApiService.d.ts

@@ -3,10 +3,18 @@ import { InjectionToken } from "tsyringe";
   * Defines a contract for API calls.
   */
 export interface IApiService {
+    /**
+     * The relative path to the API endpoint.
+     */
+    relativePath: string;
+    /**
+     * Fetch data from the API.
+     * @param relativePath The relative path to the API endpoint.
+     * @param payload The payload to send to the API.
+     */
     fetch(relativePath: string | null, payload: Record<string, string> | null): Promise<any>;
 }
 /**
  *  Define a token for the IApiService interface
  */
 export declare const IApiServiceToken: InjectionToken<IApiService>;
-export declare function getApiService(name: string): IApiService;

package/src/qbo/IApiService.js

@@ -1,8 +1,4 @@
-import { services } from "@quandis/qbo4.logging";
 /**
  *  Define a token for the IApiService interface
  */
 export const IApiServiceToken = 'ApiServiceToken';
-export function getApiService(name) {
-    return services.container.resolve(name);
-}

package/src/qbo/IApiService.ts

@@ -5,6 +5,16 @@ import { InjectionToken } from "tsyringe";
   * Defines a contract for API calls.
   */
 export interface IApiService {
+    /**
+     * The relative path to the API endpoint.
+     */
+    relativePath: string;
+
+    /**
+     * Fetch data from the API.
+     * @param relativePath The relative path to the API endpoint.
+     * @param payload The payload to send to the API.
+     */
     fetch(relativePath: string | null, payload: Record<string, string> | null): Promise<any>;
 }
 
@@ -13,6 +23,3 @@ export interface IApiService {
  */
 export const IApiServiceToken: InjectionToken<IApiService> = 'ApiServiceToken';
 
-export function getApiService(name: string) {
-    return services.container.resolve<IApiService>(name);
-}

package/src/qbo/Program.d.ts

@@ -1,4 +1,5 @@
 import 'reflect-metadata';
+import { IApiService } from './IApiService.js';
 export { services } from '@quandis/qbo4.configuration';
 export * from './IApiService.js';
 export * from './IValidate.js';
@@ -27,3 +28,5 @@ export declare function elementSelectorAll(element: Element, selector: string):
 export declare function elementResetValue(element: Element): void;
 export declare function elementClearValue(element: Element): void;
 export declare function matches(source: any, match: any, wildCard?: string, ignoreCase?: boolean): boolean;
+export declare function elementData(element: HTMLElement): Record<string, string>;
+export declare function getApiService(url: string): IApiService;

package/src/qbo/Program.js

@@ -1,4 +1,6 @@
 import 'reflect-metadata';
+import { services } from '@quandis/qbo4.configuration';
+import { RestApiService } from './RestApiService.js';
 export { services } from '@quandis/qbo4.configuration';
 export * from './IApiService.js';
 export * from './IValidate.js';
@@ -96,3 +98,27 @@ export function matches(source, match, wildCard = "*", ignoreCase = true) {
     let regex = new RegExp("^" + match + "$", ignoreCase ? "i" : "");
     return regex.test(source);
 }
+export function elementData(element) {
+    const data = element.dataset;
+    const record = {};
+    for (const key in data) {
+        if (data.hasOwnProperty(key) && data[key] !== undefined) {
+            record[key] = data[key];
+        }
+    }
+    return record;
+}
+export function getApiService(url) {
+    const parts = url.match(/api:\/\/([^/]+)/);
+    const name = parts ? parts[1] : url;
+    const relativePath = parts ? url.substring(`api://${name}`.length) : '';
+    const service = services.container.isRegistered(name)
+        ? services.container.resolve(name)
+        : new RestApiService(url);
+    if (relativePath) {
+        const clone = structuredClone(service);
+        clone.relativePath = relativePath;
+        return clone;
+    }
+    return service;
+}

package/src/qbo/Program.ts

@@ -1,4 +1,7 @@
 import 'reflect-metadata';
+import { IApiService } from './IApiService.js';
+import { services } from '@quandis/qbo4.configuration';
+import { RestApiService } from './RestApiService.js';
 
 export { services } from '@quandis/qbo4.configuration';
 export * from './IApiService.js';
@@ -101,3 +104,30 @@ export function matches(source, match, wildCard = "*", ignoreCase = true) {
     return regex.test(source);
 }
 
+export function elementData(element: HTMLElement) {
+    const data = element.dataset;
+    const record: Record<string, string> = {};
+    for (const key in data) {
+        if (data.hasOwnProperty(key) && data[key] !== undefined) {
+            record[key] = data[key] as string;
+        }
+    }
+    return record;
+}
+
+
+export function getApiService(url: string) {
+    const parts = url.match(/api:\/\/([^/]+)/);
+    const name = parts ? parts[1] : url;
+    const relativePath = parts ? url.substring(`api://${name}`.length) : '';
+    const service: IApiService = services.container.isRegistered(name)
+        ? services.container.resolve<IApiService>(name)
+        : new RestApiService(url);
+
+    if (relativePath) {
+        const clone = structuredClone(service);
+        clone.relativePath = relativePath;
+        return clone;
+    }
+    return service;
+}

package/src/qbo/RestApiService.d.ts

@@ -3,6 +3,7 @@ export declare class RestApiService implements IApiService {
     private headers;
     private apiEndpoint;
     private method;
+    relativePath: string;
     constructor(apiEndpoint: string, headers?: HeadersInit, method?: string | null);
     fetch(relativePath: string | null, payload?: Record<string, string> | null): Promise<any>;
 }

package/src/qbo/RestApiService.js

@@ -2,12 +2,13 @@ import { services } from "@quandis/qbo4.logging";
 import { substitute } from "./qbo-json.js";
 export class RestApiService {
     constructor(apiEndpoint, headers = { 'Content-Type': 'application/json' }, method = null) {
+        this.relativePath = '';
         this.apiEndpoint = apiEndpoint;
         this.headers = headers;
         this.method = method;
     }
     async fetch(relativePath, payload = null) {
-        const endpoint = substitute(new URL(relativePath ?? '', this.apiEndpoint).href, payload);
+        const endpoint = substitute(new URL(relativePath ?? this.relativePath, this.apiEndpoint).href, payload);
         const method = this.method ?? (payload !== null ? 'POST' : 'GET');
         const headers = new Headers(this.headers || {});
         if (payload !== null && !headers.has('Content-Type')) {

package/src/qbo/RestApiService.ts

@@ -7,6 +7,7 @@ export class RestApiService implements IApiService {
     private headers: HeadersInit;
     private apiEndpoint: string;
     private method: string | null;
+    public relativePath: string = '';
 
     constructor(apiEndpoint: string, headers: HeadersInit = { 'Content-Type': 'application/json' }, method: string | null = null) {
         this.apiEndpoint = apiEndpoint;
@@ -15,7 +16,7 @@ export class RestApiService implements IApiService {
     }
 
     async fetch(relativePath: string | null, payload: Record<string, string> | null = null): Promise<any> {
-        const endpoint = substitute(new URL(relativePath ?? '', this.apiEndpoint).href, payload);
+        const endpoint = substitute(new URL(relativePath ?? this.relativePath, this.apiEndpoint).href, payload);
         const method = this.method ?? (payload !== null ? 'POST' : 'GET');
         const headers = new Headers(this.headers || {});
         if (payload !== null && !headers.has('Content-Type')) {

package/src/qbo/qbo-api.d.ts

@@ -1,5 +1,5 @@
 import { LitElement } from 'lit';
-export declare class ApiServiceComponent extends LitElement {
+export declare class QboApiElement extends LitElement {
     name: string | null;
     apiEndpoint: string | null;
     method: string;

package/src/qbo/qbo-api.js

@@ -10,7 +10,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 import { LitElement, html } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { registerRestApi } from './RestApiService.js';
-let ApiServiceComponent = class ApiServiceComponent extends LitElement {
+let QboApiElement = class QboApiElement extends LitElement {
     constructor() {
         super(...arguments);
         this.name = null;
@@ -51,16 +51,16 @@ let ApiServiceComponent = class ApiServiceComponent extends LitElement {
 __decorate([
     property({ type: String }),
     __metadata("design:type", Object)
-], ApiServiceComponent.prototype, "name", void 0);
+], QboApiElement.prototype, "name", void 0);
 __decorate([
     property({ type: String }),
     __metadata("design:type", Object)
-], ApiServiceComponent.prototype, "apiEndpoint", void 0);
+], QboApiElement.prototype, "apiEndpoint", void 0);
 __decorate([
     property({ type: String }),
     __metadata("design:type", String)
-], ApiServiceComponent.prototype, "method", void 0);
-ApiServiceComponent = __decorate([
+], QboApiElement.prototype, "method", void 0);
+QboApiElement = __decorate([
     customElement('qbo-api')
-], ApiServiceComponent);
-export { ApiServiceComponent };
+], QboApiElement);
+export { QboApiElement };

package/src/qbo/qbo-api.ts

@@ -5,7 +5,7 @@ import { registerRestApi } from './RestApiService.js';
 
 
 @customElement('qbo-api')
-export class ApiServiceComponent extends LitElement {
+export class QboApiElement extends LitElement {
     @property({ type: String })
     name: string | null = null;