@smallpearl/ngx-helper 0.33.26 → 0.33.28

package/fesm2022/smallpearl-ngx-helper-mat-entity-crud.mjs

@@ -1,5 +1,5 @@
 import * as i1 from '@angular/common/http';
-import { HttpContextToken, HttpParams, HttpContext, HttpClient } from '@angular/common/http';
+import { HttpContextToken, HttpContext, HttpParams, HttpClient } from '@angular/common/http';
 import * as i0 from '@angular/core';
 import { InjectionToken, inject, input, computed, signal, viewChild, ViewContainerRef, Component, ChangeDetectionStrategy, viewChildren, EventEmitter, effect, ContentChildren, Output, ChangeDetectorRef } from '@angular/core';
 import * as i4 from '@angular/common';
@@ -42,6 +42,31 @@ const SP_MAT_ENTITY_CRUD_HTTP_CONTEXT = new HttpContextToken(() => ({
 
 const SP_MAT_ENTITY_CRUD_CONFIG = new InjectionToken('SPMatEntityCrudConfig');
 
+/**
+ * Converts array of HttpContextToken key, value pairs to HttpContext
+ * object in argument 'context'.
+ * @param context HTTP context to which the key, value pairs are added
+ * @param reqContext HttpContextToken key, value pairs array
+ * @returns HttpContext object, with the key, value pairs added. This is
+ * the same object as the 'context' argument.
+ */
+function convertHttpContextInputToHttpContext(context, reqContext) {
+    if (reqContext instanceof HttpContext) {
+        // reqContext is already an HttpContext object.
+        for (const k of reqContext.keys()) {
+            context.set(k, reqContext.get(k));
+        }
+    }
+    else if (Array.isArray(reqContext) && reqContext.length == 2 && !Array.isArray(reqContext[0])) {
+        // one dimensional array of a key, value pair.
+        context.set(reqContext[0], reqContext[1]);
+    }
+    else {
+        reqContext.forEach(([k, v]) => context.set(k, v));
+    }
+    return context;
+}
+
 function defaultCrudResponseParser(entityName, idKey, method, // 'create' | 'retrieve' | 'update' | 'delete',
 resp) {
     // If the response is an object with a property '<idKey>', return it as
@@ -1084,30 +1109,6 @@ class SPMatEntityCrudComponent extends SPMatEntityListComponent {
         }
     }
     getCrudReqHttpContext(op) {
-        /**
-         * Converts array of HttpContextToken key, value pairs to HttpContext
-         * object in argument 'context'.
-         * @param context HTTP context to which the key, value pairs are added
-         * @param reqContext HttpContextToken key, value pairs array
-         * @returns HttpContext object, with the key, value pairs added. This is
-         * the same object as the 'context' argument.
-         */
-        const contextParamToHttpContext = (context, reqContext) => {
-            if (reqContext instanceof HttpContext) {
-                // reqContext is already an HttpContext object.
-                for (const k of reqContext.keys()) {
-                    context.set(k, reqContext.get(k));
-                }
-            }
-            else if (reqContext.length == 2 && !Array.isArray(reqContext[0])) {
-                // one dimensional array of a key, value pair.
-                context.set(reqContext[0], reqContext[1]);
-            }
-            else {
-                reqContext.forEach(([k, v]) => context.set(k, v));
-            }
-            return context;
-        };
         let context = new HttpContext();
         // HttpContext for crud operations are taken from either the global httpReqContext
         // or from the crudHttpReqContext, with the latter taking precedence.
@@ -1126,13 +1127,13 @@ class SPMatEntityCrudComponent extends SPMatEntityListComponent {
                 if (Array.isArray(crudHttpReqContext)) {
                     // Same HttpContext for all crud requests. Being an array, it must
                     // be an array of HttpContextToken key, value pairs.
-                    contextParamToHttpContext(context, crudHttpReqContext);
+                    convertHttpContextInputToHttpContext(context, crudHttpReqContext);
                 }
                 else if (typeof crudHttpReqContext === 'object' &&
                     op &&
                     Object.keys(crudHttpReqContext).find((k) => k === op)) {
                     // HttpContext specific to this crud operation, 'create'|'retrieve'|'update'|'delete'
-                    contextParamToHttpContext(context, crudHttpReqContext[op]);
+                    convertHttpContextInputToHttpContext(context, crudHttpReqContext[op]);
                 }
             }
         }
@@ -1723,11 +1724,39 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.1.6", ngImpor
  * checking form.touched), then a 'Lose Changes' prompt is displayed allowing
  * the user to cancel the closure.
  *
- * The @Component is fake just to keep the VSCode angular linter quiet.
+ * The `@Component` decorator is fake to keep the VSCode angular linter quiet.
  *
- * To use this class:-
+ * This class can be used in two modes:
  *
- * 1. Declare a FormGroup<> type as
+ *  I. SPMatEntityCrudComponent mode
+ *     This mode relies on a bridge interface that implements the
+ *     SPMatEntityCrudCreateEditBridge interface to perform the entity
+ *     load/create/update operations. This is the intended mode when the
+ *     component is used as a part of the SPMatEntityCrudComponent to
+ *     create/update an entity. This mode requires the following properties
+ *     to be set:
+ *       - entity: TEntity | TEntity[IdKey] | undefined (for create)
+ *       - bridge: SPMatEntityCrudCreateEditBridge
+ *
+ *  II. Standalone mode
+ *     This mode does not rely on the bridge interface and the component
+ *     itself performs the entity load/create/update operations.
+ *     This mode requires the following properties to be set:
+ *      - entity: TEntity | TEntity[IdKey] | undefined (for create)
+ *      - baseUrl: string - Base URL for CRUD operations. This URL does not
+ *        include the entity id. The entity id will be appended to this URL
+ *        for entity load and update operations. For create operation, this
+ *        URL is used as is.
+ *      - entityName: string - Name of the entity, used to parse sideloaded
+ *        entity responses.
+ *      - httpReqContext?: HttpContextInput - Optional HTTP context to be
+ *        passed to the HTTP requests. For instance, if your app has a HTTP
+ *        interceptor that adds authentication tokens to the requests based
+ *        on a HttpContextToken, then you can pass that token here.
+ *
+ * I. SPMatEntityCrudComponent mode:
+ *
+ *  1. Declare a FormGroup<> type as
  *
  *      ```
  *      type MyForm = FormGroup<{
@@ -1737,64 +1766,101 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.1.6", ngImpor
  *      }>;
  *      ```
  *
- * 2. Derive your form's component class from this and implement the
+ *  2. Derive your form's component class from this and implement the
  *    createForm() method returing the FormGroup<> instance that matches
  *    the FormGroup concrete type above.
  *
- *    ```
- *    class MyFormComponent extends SPMatEntityCrudFormBase<MyForm, MyEntity> {
- *      constructor() {
- *        super()
- *      }
- *
- *      createForm() {
- *        return new FormGroup([...])
+ *      ```
+ *      class MyFormComponent extends SPMatEntityCrudFormBase<MyForm, MyEntity> {
+ *        constructor() {
+ *          super()
+ *        }
+ *        createForm() {
+ *          return new FormGroup([...])
+ *        }
  *      }
- *    }
- *    ```
+ *      ```
  *
- * 3. If you form's value requires manipulation before being sent to the
+ *  3. If your form's value requires manipulation before being sent to the
  *    server, override `getFormValue()` method and do it there before returning
  *    the modified values.
  *
- * 4. Wire up the form in the template as:
+ *  4. Wire up the form in the template as below
+ *
+ *      ```html
+ *      @if (loadEntity$ | async) {
+ *      <form [formGroup]='form'.. (ngSubmit)="onSubmit()">
+ *        <button type="submit">Submit</button>
+ *      </form>
+ *      } @else {
+ *        <div>Loading...</div>
+ *      }
+ *      ```
+ *
+ *     Here `loadEntity$` is an Observable<boolean> that upon emission of `true`
+ *     indicates that the entity has been loaded from server (in case of edit)
+ *     and the form is ready to be displayed. Note that if the full entity was
+ *     passed in the `entity` input property, then no server load is necessary
+ *     and the form will be created immediately.
+ *
+ *  5. In the parent component that hosts the SPMatEntityCrudComponent, set
+ *     the `entity` and `bridge` input properties of this component to
+ *     appropriate values. For instance, if your form component has the
+ *     selector `app-my-entity-form`, then the parent component's template
+ *     will have:
+ *
+ *    ```html
+ *   <sp-mat-entity-crud
+ *    ...
+ *    createEditFormTemplate="entityFormTemplate"
+ *   ></sp-mat-entity-crud>
+ *   <ng-template #entityFormTemplate let-data="data">
+ *    <app-my-entity-form
+ *      [entity]="data.entity"
+ *      [bridge]="data.bridge"
+ *    ></app-my-entity-form>
+ *   </ng-template>
+ *  ```
  *
- *    ```
- *    @if (loadEntity$ | async) {
- *    <form [formGroup]='form'.. (ngSubmit)="onSubmit()">
- *      <button type="submit">Submit</button>
- *    </form>
- *    } @else {
- *     <div>Loading...</div>
- *    }
- *    ```
- *    Here `loadEntity$` is an Observable<boolean> that upon emission of `true`
- *    indicates that the entity has been loaded from server (in case of edit)
- *    and the form is ready to be displayed. Note that if the full entity was
- *    passed in the `entity` input property, then no server load is necessary
- *    and the form will be created immediately.
+ *  II. Standalone mode
  *
- * 5. If the entity shape required by the form requires additional parameters
- *    to be loaded from server, initialize `entity` property with it's id.
- *    Then override the `getLoadEntityParams()` method to return the additional
- *    load parameters. The parameters returned by this method will be
- *    passed to the `loadEntity()` method of the bridge interface.
+ * 1..4. Same as above, except set the required `bridge` input to `undefined`.
+ * 5. Initialize the component's inputs `baseUrl` and `entityName` with the
+ *    appropriate values. If you would like to pass additional HTTP context to
+ *    the HTTP requests, then set the `httpReqContext` input as well.
+ *    If the entity uses an id key other than 'id', then set the `idKey` input
+ *    to the appropriate id key name.
+ * 6. If you want to retrieve the created/updated entity after the create/update
+ *    operation, override the `onPostCreate()` and/or `onPostUpdate()` methods
+ *    respectively.
  */
 class SPMatEntityCrudFormBase {
-    _form = signal(undefined);
     entity = input.required();
     bridge = input.required();
     params = input();
+    // --- BEGIN inputs used when `bridge` input is undefined
+    // Entity name, which is used to parse sideloaded entity responses
+    entityName = input();
+    // Base CRUD URL, which is the GET-list-of-entities/POST-to-create
+    // URL. Update URL will be derived from this ias `baseUrl()/${TEntity[IdKey]}`
+    baseUrl = input();
+    // Additional request context to be passed to the request
+    httpReqContext = input();
+    // ID key, defaults to 'id'
+    idKey = input('id');
+    // -- END inputs used when `bridge` input is undefined
+    // IMPLEMENTATION
     loadEntity$;
     _entity = signal(undefined);
     sub$ = new Subscription();
+    // Store for internal form signal. form() is computed from this.
+    _form = signal(undefined);
     // Force typecast to TFormGroup so that we can use it in the template
     // without having to use the non-nullable operator ! with every reference
     // of form(). In any case the form() signal is always set in ngOnInit()
     // method after the form is created. And if form() is not set, then there
     // will be errors while loading the form in the template.
     form = computed(() => this._form());
-    // crudConfig = getEntityCrudConfig();
     transloco = inject(TranslocoService);
     cdr = inject(ChangeDetectorRef);
     http = inject(HttpClient);
@@ -1809,16 +1875,24 @@ class SPMatEntityCrudFormBase {
         return true;
     }
     ngOnInit() {
+        // validate inputs. Either bridge or (baseUrl and entityName) must be
+        // defined.
+        if (!this.bridge() && (!this.baseUrl() || !this.entityName())) {
+            throw new Error('SPMatEntityCrudFormBase: baseUrl and entityName inputs must be defined in standalone mode.');
+        }
         this.loadEntity$ = (typeof this.entity() === 'object' || this.entity() === undefined
             ? new Observable((subscriber) => {
                 subscriber.next(this.entity());
                 subscriber.complete();
             })
-            : this.bridge()?.loadEntity(this.entity(), this.getLoadEntityParams())).pipe(map((resp) => {
+            : this.load(this.entity())).pipe(map((resp) => {
             const compositeEntity = this.getEntityFromLoadResponse(resp);
             this._entity.set(compositeEntity);
             this._form.set(this.createForm(compositeEntity));
-            this.bridge()?.registerCanCancelEditCallback(this.canCancelEdit);
+            const bridge = this.bridge();
+            if (bridge && bridge.registerCanCancelEditCallback) {
+                bridge.registerCanCancelEditCallback(this.canCancelEdit);
+            }
             return true;
         }));
     }
@@ -1835,23 +1909,32 @@ class SPMatEntityCrudFormBase {
     }
     /**
      * Return the TEntity object from the response returned by the
-     * loadEntity() method of the bridge. Typically entity load return the actual
+     * load() method. Typically entity load returns the actual
      * entity object itself. In some cases, where response is sideloaded, the
      * default implementation here uses the `sideloadToComposite()` utility to
      * extract the entity from the response after merging (inplace) the
      * sideloaded data into a composite.
      *
-     * If you have a different response shape, override this method to
-     * extract the TEntity object from the response.
+     * If you have a different response shape, or if your sideloaded object
+     * response requires custom custom `sideloadDataMap`, override this method
+     * and implement your custom logic to extract the TEntity object from the
+     * response.
      * @param resp
      * @returns
      */
     getEntityFromLoadResponse(resp) {
-        if (!resp) {
+        if (!resp || typeof resp !== 'object') {
             return undefined;
         }
-        const sideloaded = sideloadToComposite(resp, this.bridge().getEntityName(), this.bridge().getIdKey());
-        return sideloaded;
+        const entityName = this.entityName();
+        if (resp.hasOwnProperty(this.getIdKey())) {
+            return resp;
+        }
+        else if (entityName && resp.hasOwnProperty(entityName)) {
+            // const sideloadDataMap = this.sideloadDataMap();
+            return sideloadToComposite(resp, this.entityName(), this.getIdKey());
+        }
+        return undefined;
     }
     /**
      * Override to customize the id key name if it's not 'id'
@@ -1859,7 +1942,11 @@ class SPMatEntityCrudFormBase {
      * extract the entity's id for UPDATE operation.
      */
     getIdKey() {
-        return 'id';
+        const bridge = this.bridge();
+        if (bridge) {
+            return bridge.getIdKey();
+        }
+        return this.idKey();
     }
     /**
      * Return the form's value to be sent to server as Create/Update CRUD
@@ -1872,15 +1959,117 @@ class SPMatEntityCrudFormBase {
     }
     onSubmit() {
         const value = this.getFormValue();
-        const obs = !this.entity()
-            ? this.bridge()?.create(value)
-            : this.bridge()?.update(this.entity()[this.getIdKey()], value);
+        const obs = !this._entity()
+            ? this.create(value)
+            : this.update(this._entity()[this.getIdKey()], value);
         this.sub$.add(obs
-            ?.pipe(setServerErrorsAsFormErrors(this._form(), this.cdr))
+            ?.pipe(tap(entity => this._entity() ? this.onPostUpdate(entity) : this.onPostCreate(entity)), setServerErrorsAsFormErrors(this._form(), this.cdr))
             .subscribe());
     }
+    onPostCreate(entity) {
+        /* empty */
+    }
+    onPostUpdate(entity) {
+        /* empty */
+    }
+    /**
+     * Loads the entity if `this.entity()` is of type TEntity[IdKey]. If `bridge`
+     * input is defined, then it's `loadEntity()` method is used to load the
+     * entity. Otherwise, then this method attempts to load the entity using
+     * HTTP GET from the URL derived from `baseUrl` input.
+     * @param entityId
+     * @param params
+     * @returns
+     */
+    load(entityId) {
+        const bridge = this.bridge();
+        const params = this.getLoadEntityParams();
+        if (bridge) {
+            return bridge.loadEntity(entityId, params);
+        }
+        // Try to load using baseUrl.
+        if (!this.baseUrl()) {
+            console.warn(`SPMatEntityCrudFormBase.load: No bridge defined, baseUrl input is undefined. Returning undefined.`);
+            return new Observable((subscriber) => {
+                subscriber.next(undefined);
+                subscriber.complete();
+            });
+        }
+        let context = new HttpContext();
+        if (this.httpReqContext()) {
+            context = convertHttpContextInputToHttpContext(context, this.httpReqContext());
+        }
+        const url = this.getEntityUrl(entityId);
+        return this.http
+            .get(this.getEntityUrl(entityId), {
+            params: typeof params === 'string'
+                ? new HttpParams({ fromString: params })
+                : params,
+            context: context,
+        })
+            .pipe(map((resp) => this.getEntityFromLoadResponse(resp)));
+    }
+    /**
+     * Create a new entity using the bridge if defined, otherwise using HTTP
+     * POST to the `baseUrl`.
+     * @param values
+     * @returns
+     */
+    create(values) {
+        const bridge = this.bridge();
+        if (bridge) {
+            return bridge.create(values);
+        }
+        const url = this.baseUrl();
+        if (!url) {
+            console.warn('SPMatEntityCrudFormBase.create: Cannot create entity as neither bridge nor baseUrl inputs are provided.');
+            return of(undefined);
+        }
+        const httpReqContext = this.httpReqContext();
+        let context = new HttpContext();
+        if (httpReqContext) {
+            context = convertHttpContextInputToHttpContext(context, httpReqContext);
+        }
+        return this.http
+            .post(url, values, { context: context })
+            .pipe(map((resp) => this.getEntityFromLoadResponse(resp)));
+    }
+    /**
+     * Update an existing entity using the bridge if defined, otherwise using HTTP
+     * PATCH to the URL derived from `baseUrl` and the entity id.
+     * @param id
+     * @param values
+     * @returns
+     */
+    update(id, values) {
+        const bridge = this.bridge();
+        if (bridge) {
+            return bridge.update(id, values);
+        }
+        const url = this.baseUrl();
+        if (!url) {
+            console.warn('SPMatEntityCrudFormBase.update: Cannot update entity as neither bridge nor baseUrl inputs are provided.');
+            return of(undefined);
+        }
+        return this.http
+            .patch(this.getEntityUrl(id), values)
+            .pipe(map((resp) => this.getEntityFromLoadResponse(resp)));
+    }
+    getEntityUrl(entityId) {
+        const bridge = this.bridge();
+        if (bridge) {
+            return bridge.getEntityUrl(entityId);
+        }
+        const baseUrl = this.baseUrl();
+        if (baseUrl) {
+            const urlParts = baseUrl.split('?');
+            return `${urlParts[0]}${String(entityId)}/${urlParts[1] ? '?' + urlParts[1] : ''}`;
+        }
+        console.warn('SPMatEntityCrudFormBase.getEntityUrl: Cannot determine entity URL as neither baseUrl nor bridge inputs are provided.');
+        return '';
+    }
     /** @nocollapse */ static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.1.6", ngImport: i0, type: SPMatEntityCrudFormBase, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    /** @nocollapse */ static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "19.1.6", type: SPMatEntityCrudFormBase, isStandalone: false, selector: "_#_sp-mat-entity-crud-form-base_#_", inputs: { entity: { classPropertyName: "entity", publicName: "entity", isSignal: true, isRequired: true, transformFunction: null }, bridge: { classPropertyName: "bridge", publicName: "bridge", isSignal: true, isRequired: true, transformFunction: null }, params: { classPropertyName: "params", publicName: "params", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: ``, isInline: true });
+    /** @nocollapse */ static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "19.1.6", type: SPMatEntityCrudFormBase, isStandalone: false, selector: "_#_sp-mat-entity-crud-form-base_#_", inputs: { entity: { classPropertyName: "entity", publicName: "entity", isSignal: true, isRequired: true, transformFunction: null }, bridge: { classPropertyName: "bridge", publicName: "bridge", isSignal: true, isRequired: true, transformFunction: null }, params: { classPropertyName: "params", publicName: "params", isSignal: true, isRequired: false, transformFunction: null }, entityName: { classPropertyName: "entityName", publicName: "entityName", isSignal: true, isRequired: false, transformFunction: null }, baseUrl: { classPropertyName: "baseUrl", publicName: "baseUrl", isSignal: true, isRequired: false, transformFunction: null }, httpReqContext: { classPropertyName: "httpReqContext", publicName: "httpReqContext", isSignal: true, isRequired: false, transformFunction: null }, idKey: { classPropertyName: "idKey", publicName: "idKey", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: ``, isInline: true });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.1.6", ngImport: i0, type: SPMatEntityCrudFormBase, decorators: [{
             type: Component,