@smallpearl/ngx-helper 0.33.26 → 0.33.28

package/mat-entity-crud/src/context-param-to-http-context.d.ts

@@ -0,0 +1,11 @@
+import { HttpContext, HttpContextToken } from '@angular/common/http';
+export type HttpContextInput = [[HttpContextToken<any>, any]] | [HttpContextToken<any>, any] | HttpContext;
+/**
+ * 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.
+ */
+export declare function convertHttpContextInputToHttpContext(context: HttpContext, reqContext: HttpContextInput): HttpContext;

package/mat-entity-crud/src/mat-entity-crud-form-base.d.ts

@@ -3,6 +3,7 @@ import { ChangeDetectorRef, OnDestroy, OnInit } from '@angular/core';
 import { AbstractControl } from '@angular/forms';
 import { TranslocoService } from '@jsverse/transloco';
 import { Observable, Subscription } from 'rxjs';
+import { HttpContextInput } from './context-param-to-http-context';
 import { SPMatEntityCrudCreateEditBridge } from './mat-entity-crud-types';
 import * as i0 from "@angular/core";
 /**
@@ -16,11 +17,39 @@ import * as i0 from "@angular/core";
  * 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<{
@@ -30,59 +59,88 @@ import * as i0 from "@angular/core";
  *      }>;
  *      ```
  *
- * 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:
- *
- *    ```
- *    @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. 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.
+ *  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>
+ *  ```
+ *
+ *  II. Standalone mode
+ *
+ * 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.
  */
 export declare abstract class SPMatEntityCrudFormBase<TFormGroup extends AbstractControl, TEntity extends {
     [P in IdKey]: PropertyKey;
 }, IdKey extends string = 'id'> implements OnInit, OnDestroy {
-    _form: import("@angular/core").WritableSignal<TFormGroup | undefined>;
     entity: import("@angular/core").InputSignal<TEntity | TEntity[IdKey]>;
     bridge: import("@angular/core").InputSignal<SPMatEntityCrudCreateEditBridge>;
     params: import("@angular/core").InputSignal<any>;
+    entityName: import("@angular/core").InputSignal<string | undefined>;
+    baseUrl: import("@angular/core").InputSignal<string | undefined>;
+    httpReqContext: import("@angular/core").InputSignal<HttpContextInput | undefined>;
+    idKey: import("@angular/core").InputSignal<string>;
     loadEntity$: Observable<boolean>;
     _entity: import("@angular/core").WritableSignal<TEntity | undefined>;
     sub$: Subscription;
+    _form: import("@angular/core").WritableSignal<TFormGroup | undefined>;
     form: import("@angular/core").Signal<TFormGroup>;
     transloco: TranslocoService;
     cdr: ChangeDetectorRef;
@@ -99,14 +157,16 @@ export declare abstract class SPMatEntityCrudFormBase<TFormGroup extends Abstrac
     getLoadEntityParams(): string | HttpParams;
     /**
      * 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
      */
@@ -130,6 +190,34 @@ export declare abstract class SPMatEntityCrudFormBase<TFormGroup extends Abstrac
      */
     getFormValue(): any;
     onSubmit(): void;
+    onPostCreate(entity: TEntity): void;
+    onPostUpdate(entity: TEntity): void;
+    /**
+     * 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: any): Observable<TEntity>;
+    /**
+     * Create a new entity using the bridge if defined, otherwise using HTTP
+     * POST to the `baseUrl`.
+     * @param values
+     * @returns
+     */
+    protected create(values: any): Observable<TEntity>;
+    /**
+     * 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
+     */
+    protected update(id: any, values: any): Observable<TEntity>;
+    protected getEntityUrl(entityId: any): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<SPMatEntityCrudFormBase<any, any, any>, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<SPMatEntityCrudFormBase<any, any, any>, "_#_sp-mat-entity-crud-form-base_#_", never, { "entity": { "alias": "entity"; "required": true; "isSignal": true; }; "bridge": { "alias": "bridge"; "required": true; "isSignal": true; }; "params": { "alias": "params"; "required": false; "isSignal": true; }; }, {}, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SPMatEntityCrudFormBase<any, any, any>, "_#_sp-mat-entity-crud-form-base_#_", never, { "entity": { "alias": "entity"; "required": true; "isSignal": true; }; "bridge": { "alias": "bridge"; "required": true; "isSignal": true; }; "params": { "alias": "params"; "required": false; "isSignal": true; }; "entityName": { "alias": "entityName"; "required": false; "isSignal": true; }; "baseUrl": { "alias": "baseUrl"; "required": false; "isSignal": true; }; "httpReqContext": { "alias": "httpReqContext"; "required": false; "isSignal": true; }; "idKey": { "alias": "idKey"; "required": false; "isSignal": true; }; }, {}, never, never, false, never>;
 }

package/mat-entity-crud/src/mat-entity-crud-internal-types.d.ts

@@ -17,7 +17,16 @@ export interface SPMatEntityCrudComponentBase<TEntity extends {
      */
     getEntityName(): string;
     getEntityNamePlural(): string;
+    /**
+     * Wrapper around idKey property.
+     */
     getIdKey(): string;
+    /**
+     * This method should return the entity URL for the given entity id.
+     * The entity URL should include any additional query parameters that were
+     * passed to the SPMatEntityCrudComponentBase component's `url` property.
+     * @param id
+     */
     getEntityUrl(id: TEntity[IdKey] | undefined): string;
     /**
      * FormViewHostComponent will call this to close the Create/Edit pane.

package/mat-entity-crud/src/mat-entity-crud-types.d.ts

@@ -26,9 +26,9 @@ export interface SPMatEntityCrudConfig {
  * This is the interface through which the client provided CRUD form component
  * interacts with the 'host' SPMatEntityCrudComponent. When the form wants to
  * submit an entity to the server (for create or update), it should call the
- * one of the create or update methods. The interface also other methods for
- * the form component to interact with SPMatEntityCrudComponent such as
- * refresh its entities list, close the form pane, etc.
+ * one of the create or update methods. The interface also provides other
+ * methods for the form component to interact with SPMatEntityCrudComponent
+ * such as refresh its entities list, close the form pane, etc.
  *
  * The interface name has a 'Bridge' as the interface acts as a bridge between
  * the client provided form handler component and the host
@@ -45,6 +45,12 @@ export interface SPMatEntityCrudCreateEditBridge {
      * @returns The entity id key string.
      */
     getIdKey(): string;
+    /**
+     * Get Entity url
+     * @param cancel
+     * @returns
+     */
+    getEntityUrl(entityId: any): string;
     /**
      * Close the edit/update form pane. This WON'T call the 'cancelEditCallback'
      * even if one is registered.

package/package.json

@@ -6,7 +6,7 @@
       "path": "src/assets/i18n/"
     }
   ],
-  "version": "0.33.26",
+  "version": "0.33.28",
   "peerDependencies": {
     "@angular/common": "^19.1.0",
     "@angular/core": "^19.1.0",
@@ -48,6 +48,14 @@
       "types": "./entities/index.d.ts",
       "default": "./fesm2022/smallpearl-ngx-helper-entities.mjs"
     },
+    "./entity-field": {
+      "types": "./entity-field/index.d.ts",
+      "default": "./fesm2022/smallpearl-ngx-helper-entity-field.mjs"
+    },
+    "./mat-busy-wheel": {
+      "types": "./mat-busy-wheel/index.d.ts",
+      "default": "./fesm2022/smallpearl-ngx-helper-mat-busy-wheel.mjs"
+    },
     "./locale": {
       "types": "./locale/index.d.ts",
       "default": "./fesm2022/smallpearl-ngx-helper-locale.mjs"
@@ -60,14 +68,6 @@
       "types": "./forms/index.d.ts",
       "default": "./fesm2022/smallpearl-ngx-helper-forms.mjs"
     },
-    "./mat-busy-wheel": {
-      "types": "./mat-busy-wheel/index.d.ts",
-      "default": "./fesm2022/smallpearl-ngx-helper-mat-busy-wheel.mjs"
-    },
-    "./entity-field": {
-      "types": "./entity-field/index.d.ts",
-      "default": "./fesm2022/smallpearl-ngx-helper-entity-field.mjs"
-    },
     "./mat-context-menu": {
       "types": "./mat-context-menu/index.d.ts",
       "default": "./fesm2022/smallpearl-ngx-helper-mat-context-menu.mjs"