@smallpearl/ngx-helper 0.32.9 → 0.32.11

package/assets/i18n/sp-mat-select-entity/en.json

@@ -1,5 +1,5 @@
 {
   "search": "Search",
   "notFound": "Not found",
-  "addItem": "Add {{item}}"
+  "createNew": "Create New"
 }

package/assets/i18n/sp-mat-select-entity/zh-hant.json

@@ -1,5 +1,5 @@
 {
   "search": "搜索",
   "notFound": "未找到",
-  "additem": "添加"
+  "createNew": "創建新的"
 }

package/entities/index.d.ts

@@ -0,0 +1,2 @@
+export * from './src/paged-loader';
+export * from './src/paginator';

package/entities/src/paged-loader.d.ts

@@ -0,0 +1,212 @@
+import { HttpClient, HttpContext, HttpContextToken, HttpParams } from '@angular/common/http';
+import { SPMatEntityListPaginator } from '@smallpearl/ngx-helper/mat-entity-list';
+import { Observable, Subject, Subscription } from 'rxjs';
+import * as i0 from "@angular/core";
+/**
+ * A type representing an entity loader function that takes page number,
+ * page size, and an optional search value and returns an Observable of
+ * the response. This is similar the http.get() method of HttpClient but
+ * with pagination parameters. The return value is deliberately kept generic
+ * (Observable<any>) to allow flexibility in the response type. This reponse
+ * will be parsed by the provided paginator's parseRequestResponse() method.
+ * So as long as the function return type and paginator are compatible,
+ * any response type can be handled.
+ *
+ * Ideally the response should contain the total number of entities available
+ * at the remote and the array of entities for the requested page.
+ */
+export type SPEntityLoaderFn = (page: number, pageSize: number, searchValue: string | undefined) => Observable<any>;
+/**
+ * Represents a request to load entities from the remote. This is used to
+ * compare two requests to determine if they are equal. This is useful to
+ * prevent duplicate requests being sent to the remote.
+ */
+declare class LoadRequest {
+    endpoint: string | SPEntityLoaderFn;
+    pageNumber: number;
+    searchStr: string | undefined;
+    force: boolean;
+    constructor(endpoint: string | SPEntityLoaderFn, pageNumber: number, searchStr: string | undefined, force?: boolean);
+    isEqualToAndNotForced(prev: LoadRequest): boolean;
+}
+type StateProps = {
+    allEntitiesLoaded: boolean;
+    loading: boolean;
+};
+/**
+ * An abstract class that you can use wherever you would like to load entities
+ * from a remote endpoint in a paged manner. Entities can be loaded in one of
+ * two ways:
+ *
+ * 1. By providing an entityLoaderFn that takes an endpoint and HttpParams
+ *    and returns a Observable of entities.
+ * 2. Or by providing a URL and using the default loader that uses HttpClient
+ *    to load entities.
+ * This class uses RxJS to manage the loading of entities and provides
+ * signals to track the loading state, entity count, page index, page size,
+ * and whether more entities are available to load.
+ *
+ * How to use this class:
+ *
+ * 1. Dervice your component from SPPagedEntityLoader.
+ * 2. After your component is initialized, call the startLoader() method to
+ *    get the component going. This sets up the necessary subscriptions to
+ *    listen for load requests. Load requests are triggered by calling the
+ *    loadPage() or loadNextPage() methods.
+ * 3. If your component supports infinite scrolling, call loadMoreEntities()
+ *    method to load the next page of entities when it detects a scroll event.
+ * 4. If you component needs to load a specific page (via a pagination control),
+ *    call the loadPage(pageNumber) method to load the specified page.
+ * 5. Entities are stored in an internal entities store which is an @ngneat/elf
+ *    store. You can subscribe to the store's query to get the list of entities.
+ * 6. When your component is destroyed, call the stopLoader() method to clean up
+ *    internal subscriptions.
+ *
+ * The class is decorated with Angular's @Directive decorator so that we can
+ * use signals for the input properties and dependency injection for HttpClient.
+ * There are no abstract methods as such, but the class is meant to be extended
+ * by your component to provide the necessary configuration via input properties.
+ * This is why it is declared as abstract.
+ */
+export declare abstract class SPPagedEntityLoader<TEntity extends {
+    [P in IdKey]: PropertyKey;
+}, IdKey extends string = 'id'> {
+    static _entitiesCache: Map<string, {
+        refCount: number;
+        resp: any;
+    }>;
+    cacheKeys: Set<string>;
+    searchParamValue: string | undefined;
+    /**
+     * Entity name, that is used to form the "New { item }" menu item if
+     * inlineNew=true. This is also used as the key of the object in GET response
+     * if the reponse JSON is an object (sideloaded response), where the values
+     * are stored indexed by the server model name. For eg:-
+     *
+     * {
+     *    'customers': [
+     *      {...},
+     *      {...},
+     *      {...},
+     *    ]
+     * }
+     */
+    entityName: import("@angular/core").InputSignal<string>;
+    url: import("@angular/core").InputSignal<string | SPEntityLoaderFn>;
+    pageSize: import("@angular/core").InputSignal<number>;
+    paginator: import("@angular/core").InputSignal<SPMatEntityListPaginator | undefined>;
+    searchParamName: import("@angular/core").InputSignal<string>;
+    idKey: import("@angular/core").InputSignal<string>;
+    pluralEntityName: import("@angular/core").InputSignal<string | undefined>;
+    httpReqContext: import("@angular/core").InputSignal<[HttpContextToken<any>, any] | [[HttpContextToken<any>, any]] | undefined>;
+    httpParams: import("@angular/core").InputSignal<HttpParams | undefined>;
+    protected loadRequest$: Subject<LoadRequest>;
+    protected sub$: Subscription | undefined;
+    protected _pageSize: import("@angular/core").Signal<number>;
+    protected _pluralEntityName: import("@angular/core").Signal<string>;
+    protected _capitalizedEntityName: import("@angular/core").Signal<string>;
+    protected _httpReqContext: import("@angular/core").Signal<HttpContext>;
+    entityListConfig: import("@smallpearl/ngx-helper/mat-entity-list").SPMatEntityListConfig | null;
+    protected _paginator: import("@angular/core").Signal<SPMatEntityListPaginator>;
+    protected store: import("@ngneat/elf").Store<{
+        name: string;
+        state: {
+            entities: Record<TEntity[IdKey], TEntity>;
+            ids: TEntity[IdKey][];
+        } & StateProps & import("@ngneat/elf-pagination").PaginationState<0>;
+        config: never;
+    }, {
+        entities: Record<TEntity[IdKey], TEntity>;
+        ids: TEntity[IdKey][];
+    } & StateProps & import("@ngneat/elf-pagination").PaginationState<0>>;
+    protected http: HttpClient;
+    constructor();
+    /**
+     * Starts listening for load requests and processes them. Call this from your
+     * component's ngOnInit() or ngAfterViewInit() method.
+     */
+    startLoader(): void;
+    /**
+     * Stops listening for load requests and cleans up subscriptions.
+     */
+    stopLoader(): void;
+    /**
+     * Returns a boolean indicating whether all entities at the remote have been
+     * loaded. All entities are considered loaded when there are no more entities
+     * to load from the remote (that is all pages have been loaded without
+     * a search filter).
+     * @returns
+     */
+    allEntitiesLoaded(): boolean;
+    /**
+     * Returns the total number of entities at the remote as reported by the
+     * server (or load fn) during each load.
+     * @returns
+     */
+    totalEntitiesAtRemote(): number;
+    /**
+     * Returns number of entities currently stored in the internal store.
+     * @returns
+     */
+    totalEntitiesCount(): number;
+    /**
+     * Returns true if there are more entities to load from the remote.
+     * This is computed based on the total entities count and the number of
+     * entities loaded so far. For this method to work correctly, an initial
+     * load must have been performed to get the total count from the remote.
+     * @returns
+     */
+    hasMore(): boolean;
+    /**
+     * Returns true if a load operation is in progress. The load async operation
+     * method turns the loading state to true when a load operation starts and
+     * turns it to false when the operation completes.
+     * @returns
+     */
+    loading(): boolean;
+    /**
+     * Returns the endpoint URL if the loader was created with an endpoint.
+     * If the loader was created with a loader function, an empty string is
+     * returned.
+     * @returns
+     */
+    endpoint(): string;
+    /**
+     * Loads the specified page number of entities from the remote.
+     * @param pageNumber
+     */
+    loadPage(pageNumber: number): void;
+    /**
+     * Returns the next page number to be loaded. This is based on the current
+     * page number stored in the internal pagination state. Note that this method
+     * only makes sense when pages are loaded sequentially as in an infinite
+     * scroll UI.
+     * @returns
+     */
+    nextPageNumber(): number;
+    /**
+     * Returns the total number of pages available at the remote.
+     * @returns
+     */
+    totalPages(): number;
+    /**
+     * Loads the next page of entities from the remote. If forceRefresh is true,
+     * the internal store is reset before loading the next page. Use this for
+     * infinite scroll scenarios where you want to load the pages sequentially.
+     * @param forceRefresh
+     */
+    loadNextPage(forceRefresh?: boolean): void;
+    setSearchParamValue(searchStr: string): void;
+    setEntities(entities: TEntity[]): void;
+    getEntities(): TEntity[];
+    getEntity(id: TEntity[IdKey]): TEntity | undefined;
+    protected doActualLoad(lr: LoadRequest): Observable<any>;
+    private existsInCache;
+    private getCacheKey;
+    private getFromCache;
+    addToCache(cacheKey: string, resp: any): void;
+    private removeFromCache;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SPPagedEntityLoader<any, any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SPPagedEntityLoader<any, any>, "**spPagedEntityLoader**", never, { "entityName": { "alias": "entityName"; "required": true; "isSignal": true; }; "url": { "alias": "url"; "required": true; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "paginator": { "alias": "paginator"; "required": false; "isSignal": true; }; "searchParamName": { "alias": "searchParamName"; "required": false; "isSignal": true; }; "idKey": { "alias": "idKey"; "required": false; "isSignal": true; }; "pluralEntityName": { "alias": "pluralEntityName"; "required": false; "isSignal": true; }; "httpReqContext": { "alias": "httpReqContext"; "required": false; "isSignal": true; }; "httpParams": { "alias": "httpParams"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+export {};

package/entities/src/paginator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pagination HTTP request params. Actually copied from Angular's HttpParams
+ * declaration. The ReadonlyArray<string|number|boolean> is a bit of an
+ * overkill for pagination params, but what the heck. When you copy-paste,
+ * do it in full!
+ */
+export type SPPageParams = {
+    [param: string]: string | number | boolean | ReadonlyArray<string | number | boolean>;
+};
+/**
+ * An interface that the clients should provide, either via a global config
+ * (see above), that handles parsing the GET response and returns the entities
+ * stored therein. This class will allow the entity-list component to be
+ * used across different pagination response types as long as the appropriate
+ * SPEntityListPaginator class is provided to the component.
+ */
+export interface SPEntityListPaginator {
+    /**
+     * Return the HTTP request params for the given page index and page size as
+     * an object. For example, for a REST API that supports 'skip' and 'top' params,
+     * the implementation would be:
+     *
+     * ```typescript
+     * getRequestPageParams(endpoint: string, pageIndex: number, pageSize: number): SPPageParams {
+     *   return {
+     *     skip: pageIndex * pageSize,
+     *     top: pageSize
+     *   };
+     * }
+     * ```
+     * @param endpoint
+     * @param pageIndex
+     * @param pageSize
+     * @returns
+     */
+    getRequestPageParams: (endpoint: string, pageIndex: number, pageSize: number) => SPPageParams;
+    /**
+     * Parse the HTTP response received from the GET request and return an object
+     * containing the total number of entities available and the array of entities
+     * for the current page. For example, for the pure DRF paginated response
+     * like below:
+     * ```json
+     * {
+     *  "count": 102,
+     *  "next": "http://api.example.org/entities/?page=3",
+     *  "previous": "http://api.example.org/entities/?page=1",
+     *  "results": [
+     *    {
+     *      "id": 1,
+     *      "name": "Entity 1"
+     *    },
+     *    {
+     *      "id": 2,
+     *      "name": "Entity 2"
+     *    }
+     *  ]
+     * }
+     * ```
+     * The implementation would be:
+     * ```typescript
+     * parseRequestResponse<TEntity extends { [P in IdKey]: PropertyKey }, IdKey extends string = 'id'>(
+     *   entityName: string,
+     *   entityNamePlural: string,
+     *   endpoint: string,
+     *   params: SPPageParams,
+     *   resp: any
+     * ): { total: number; entities: TEntity[] } {
+     *   return {
+     *     total: resp.count,
+     *     entities: resp.results
+     *   };
+     * }
+     * ```
+     * @param entityName
+     * @param entityNamePlural
+     * @param endpoint
+     * @param params
+     * @param resp
+     * @returns
+     */
+    parseRequestResponse: <TEntity extends {
+        [P in IdKey]: PropertyKey;
+    }, IdKey extends string = 'id'>(entityName: string, entityNamePlural: string, endpoint: string, params: SPPageParams, resp: any) => {
+        total: number;
+        entities: TEntity[];
+    };
+}