From b745f412ef489f9dffea3e0413493a4fae868968 Mon Sep 17 00:00:00 2001 From: Emmanuel DE SAINT STEBAN Date: Fri, 23 Feb 2024 17:41:54 +0100 Subject: [PATCH] docs: improve generators + specify correct tslint version + generate docs --- .github/workflows/test-and-release.yml | 2 + .gitignore | 10 +- angular.json | 42 +- docs/3rdpartylicenses.txt | 279 ++++---- docs/assets/README.md | 676 ------------------ docs/favicon.ico | Bin 5430 -> 0 bytes docs/index.html | 18 - package.json | 11 +- projects/akita-filters-plugin/ng-package.json | 2 +- .../akita-filters-plugin/ng-package2.json | 7 + projects/akita-filters-plugin/package.json | 3 + .../src/{public_api.ts => index.ts} | 0 projects/akita-mat-datasource/ng-package.json | 2 +- projects/akita-mat-datasource/package.json | 3 + .../src/{public-api.ts => index.ts} | 1 + src/app/app.component.html | 2 +- src/index.html | 2 +- tsconfig.json | 3 +- yarn.lock | 380 +++++++++- 19 files changed, 527 insertions(+), 916 deletions(-) delete mode 100644 docs/assets/README.md delete mode 100644 docs/favicon.ico delete mode 100644 docs/index.html create mode 100644 projects/akita-filters-plugin/ng-package2.json rename projects/akita-filters-plugin/src/{public_api.ts => index.ts} (100%) rename projects/akita-mat-datasource/src/{public-api.ts => index.ts} (99%) diff --git a/.github/workflows/test-and-release.yml b/.github/workflows/test-and-release.yml index dff688c..32967db 100644 --- a/.github/workflows/test-and-release.yml +++ b/.github/workflows/test-and-release.yml @@ -49,7 +49,9 @@ jobs: if: success() run: | yarn run compile + yarn run compile:forDatasource yarn run compile:datasource + yarn run build cp README.md dist/akita-filters-plugin/README.md cp LICENSE.md dist/akita-filters-plugin/LICENSE.md - name: Semantic Release diff --git a/.gitignore b/.gitignore index d834f70..a253b69 100644 --- a/.gitignore +++ b/.gitignore @@ -40,10 +40,6 @@ testem.log .DS_Store Thumbs.db -/.angular -/docs -/.nx/cache/file-map.json -/.nx/cache/lockfile.hash -/.nx/cache/nx_files.nxt -/.nx/cache/parsed-lock-file.json -/.nx/cache/project-graph.json +.angular +docs +.nx diff --git a/angular.json b/angular.json index ebee37a..88b630f 100644 --- a/angular.json +++ b/angular.json @@ -15,12 +15,15 @@ }, "architect": { "build": { - "builder": "@angular-devkit/build-angular:browser", + "builder": "@angular-devkit/build-angular:application", "options": { - "outputPath": "dist/akita-filters-plugin-playground", + "outputPath": { + "base": "dist/akita-filters-plugin-playground" + }, "index": "src/index.html", - "main": "src/main.ts", - "polyfills": "src/polyfills.ts", + "polyfills": [ + "src/polyfills.ts" + ], "tsConfig": "src/tsconfig.app.json", "assets": [ "src/favicon.ico", @@ -35,12 +38,11 @@ "node_modules/prismjs/prism.js", "node_modules/prismjs/components/prism-typescript.min.js" ], - "vendorChunk": true, "extractLicenses": false, - "buildOptimizer": false, "sourceMap": true, "optimization": false, - "namedChunks": true + "namedChunks": true, + "browser": "src/main.ts" }, "configurations": { "production": { @@ -55,8 +57,6 @@ "sourceMap": false, "namedChunks": false, "extractLicenses": true, - "vendorChunk": false, - "buildOptimizer": true, "budgets": [ { "type": "initial", @@ -134,18 +134,6 @@ "projectType": "library", "prefix": "lib", "architect": { - "build": { - "builder": "@angular-devkit/build-ng-packagr:build", - "options": { - "tsConfig": "projects/akita-filters-plugin/tsconfig.lib.json", - "project": "projects/akita-filters-plugin/ng-package.json" - }, - "configurations": { - "production": { - "tsConfig": "projects/akita-filters-plugin/tsconfig.lib.prod.json" - } - } - }, "lint": { "builder": "@angular-eslint/builder:lint", "options": { @@ -163,18 +151,6 @@ "sourceRoot": "projects/akita-mat-datasource/src", "prefix": "lib", "architect": { - "build": { - "builder": "@angular-devkit/build-ng-packagr:build", - "options": { - "tsConfig": "projects/akita-mat-datasource/tsconfig.lib.json", - "project": "projects/akita-mat-datasource/ng-package.json" - }, - "configurations": { - "production": { - "tsConfig": "projects/akita-mat-datasource/tsconfig.lib.prod.json" - } - } - }, "lint": { "builder": "@angular-eslint/builder:lint", "options": { diff --git a/docs/3rdpartylicenses.txt b/docs/3rdpartylicenses.txt index 5de8076..e97510b 100644 --- a/docs/3rdpartylicenses.txt +++ b/docs/3rdpartylicenses.txt @@ -1,136 +1,8 @@ -@angular-devkit/build-angular -MIT -The MIT License - -Copyright (c) 2017 Google, Inc. - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - - -@angular/animations -MIT - -@angular/cdk -MIT -The MIT License - -Copyright (c) 2021 Google LLC. - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - - -@angular/common -MIT - -@angular/core -MIT - -@angular/forms -MIT - -@angular/material -MIT -The MIT License - -Copyright (c) 2021 Google LLC. - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - - -@angular/platform-browser -MIT - -@angular/router -MIT - -@datorama/akita -Apache-2.0 - -@datorama/akita-ng-entity-service -Apache-2.0 - -@datorama/akita-ngdevtools -Apache-2.0 - -akita-filters-plugin -Apache License 2.0 - -akita-mat-datasource -Apache License 2.0 - -core-js -MIT -Copyright (c) 2014-2021 Denis Pushkarev - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. +-------------------------------------------------------------------------------- +Package: marked +License: "MIT" -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - - -marked -MIT # License information ## Contribution License Agreement @@ -176,12 +48,13 @@ Redistribution and use in source and binary forms, with or without modification, This software is provided by the copyright holders and contributors “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. +-------------------------------------------------------------------------------- +Package: ngx-markdown +License: "MIT" -ngx-markdown -MIT MIT License -Copyright (c) 2017-2021 Jean-Francois Cere +Copyright (c) 2017-2023 Jean-Francois Cere Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -201,15 +74,38 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +-------------------------------------------------------------------------------- +Package: @datorama/akita-ngdevtools +License: "Apache-2.0" -ngx-take-until-destroy -MIT -prismjs -MIT -MIT LICENSE +-------------------------------------------------------------------------------- +Package: @angular/animations +License: "MIT" + + +-------------------------------------------------------------------------------- +Package: @angular/platform-browser +License: "MIT" + + +-------------------------------------------------------------------------------- +Package: ngx-take-until-destroy +License: "MIT" + + +-------------------------------------------------------------------------------- +Package: @datorama/akita-ng-entity-service +License: "Apache-2.0" -Copyright (c) 2012 Lea Verou + +-------------------------------------------------------------------------------- +Package: @angular/cdk +License: "MIT" + +The MIT License + +Copyright (c) 2024 Google LLC. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -229,12 +125,13 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +-------------------------------------------------------------------------------- +Package: @angular/material +License: "MIT" -regenerator-runtime -MIT -MIT License +The MIT License -Copyright (c) 2014-present, Facebook, Inc. +Copyright (c) 2024 Google LLC. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -243,20 +140,31 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +-------------------------------------------------------------------------------- +Package: @angular/forms +License: "MIT" -rxjs -Apache-2.0 +-------------------------------------------------------------------------------- +Package: @angular/core +License: "MIT" + + +-------------------------------------------------------------------------------- +Package: rxjs +License: "Apache-2.0" + Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ @@ -460,9 +368,41 @@ Apache-2.0 limitations under the License. +-------------------------------------------------------------------------------- +Package: tslib +License: "0BSD" + +Copyright (c) Microsoft Corporation. + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH +REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, +INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR +OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +PERFORMANCE OF THIS SOFTWARE. +-------------------------------------------------------------------------------- +Package: @angular/common +License: "MIT" + + +-------------------------------------------------------------------------------- +Package: @angular/router +License: "MIT" + + +-------------------------------------------------------------------------------- +Package: @datorama/akita +License: "Apache-2.0" + + +-------------------------------------------------------------------------------- +Package: tslib +License: "0BSD" -tslib -0BSD Copyright (c) Microsoft Corporation. Permission to use, copy, modify, and/or distribute this software for any @@ -475,12 +415,13 @@ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +-------------------------------------------------------------------------------- +Package: zone.js +License: "MIT" -zone.js -MIT The MIT License -Copyright (c) 2010-2022 Google LLC. https://angular.io/license +Copyright (c) 2010-2023 Google LLC. https://angular.io/license Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -499,3 +440,31 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +-------------------------------------------------------------------------------- +Package: prismjs +License: "MIT" + +MIT LICENSE + +Copyright (c) 2012 Lea Verou + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +-------------------------------------------------------------------------------- diff --git a/docs/assets/README.md b/docs/assets/README.md deleted file mode 100644 index 12f968e..0000000 --- a/docs/assets/README.md +++ /dev/null @@ -1,676 +0,0 @@ -# Akita Filters Plugins - -![npm](https://img.shields.io/npm/v/akita-filters-plugin.svg?style=popout-square) ![npm bundle size](https://img.shields.io/bundlephobia/min/akita-filters-plugin.svg?style=popout-square) -![GitHub last commit](https://img.shields.io/github/last-commit/manudss/akita-filters-plugin.svg?style=popout-square) - -![Travis (.org)](https://img.shields.io/travis/manudss/akita-filters-plugin.svg?style=popout-square) - -Sometimes, you need to display a list and provide users the ability to filter your list. -Entity-store give the ability to filter, an sorting, by given options to selectAll() function. -But each time, you want to change this filter, you need to recall the function. - -Filters plugins give you the possibility to managed multiples filters, add, remove and update filters, and each time filters have been updated, new filtered value has been emitted. - -#### Usage -This could be useful, to display : - -- products list, (with categories filter, search, price filter, etc...) -- Store locator (with filter by region, location, etc... ) -- portfolio, image gallery -- Any list of elements that need multiple filters -- Config filter that could be applied in multiple pages -- ... - -#### Advantage : -- Add multiple filters (dynamically add, remove and update filters) without changing data. - -- The filters and the entity query could be separated. You could have one component, that displays only your element. Is just make a select, to observe and display all information. - And have another component to manage all filters. - -- You could also display a list of filters, and permit to delete one. - -- You could set the order to apply all filters - -# Installations - -Install the module - -```typescript -npm install --save akita-filters-plugin - -yarn add akita-filters-plugin -``` -npm page : https://www.npmjs.com/package/akita-filters-plugin - -# Filters Plugins - -## Instantiation - -You need to instantiate the filters Plugins : - -```typescript -myFilter = new AkitaFiltersPlugin(this.myEntitiesQuery); -``` - - --> Give just the entytiesQuery class to the plugins. - -You could define it in the constructor of your service, and add it to the property of your service. -```typescript - constructor(private productsStore: ProductsFiltersStore, private productsQuery: ProductsFiltersQuery, private productsDataService: ProductsFiltersDataService) { - this.filtersProduct = new AkitaFiltersPlugin(this.productsQuery); - } -``` - -You could also extend your class with last AkitaFiltersPlugin, and call the super method. All methods from AkitaFiltersPlugin will be available -```typescript -class CustomService extends AkitaFiltersPlugin { - constructor() { - super(wishQuery, {filtersStoreName: 'CustomFilters'}); - } - } -``` - - -## Use - -To get elements you need to call the function selectAllByFilters() form your filters plugins instance, instead of using the selectAll() function from your Query Class. - -```ts -myFilter.selectAllByFilters(); -``` - -Then add filter - -```typescript -myFilter.setFilter({ - id: 'category', - value: 'garden', - predicate: (value: ProductPlant, index, array) => value.category === category - }); -``` - -By adding these filters, the data will be filtered, and the new data will be emitted. - -Example with Angular, you could add a filter for example with a component like this. - -```typescript - -@Component({ - selector: 'app-category-filter', - changeDetection: ChangeDetectionStrategy.OnPush, - template: ` -
- -
- -
-
- ` -}) -export class CategoryFiltersComponent { - - categoryControl: new FormControl(); - - constructor(private productsService: ProductsFiltersService) {} - - ngOnInit() { - this.getallFiltersValues(); - - // On each change, set filters - this.categoryControl.valueChanges.pipe(untilDestroyed(this)).subscribe(category => { - this.productsService.setFilter({ - id: 'category', - value: category, - predicate: (value: ProductPlant, index, array) => value.category === category - }); - }); - - this.filterForm.controls.sortControl.setValue(this.productsService.getFilterValue('category'), { emitEvent: false }); // emit event false, to not emit value in the above value change subscribe - } -} -``` - -# API - -### AkitaFilter type - -An Akita filter is an object with the corresponding format : - -```typescript -type AkitaFilter: AkitaFilter = { - id: ID; - /** A corresponding name for display the filter, by default, it will be ${id): ${value} */ - name?: string; - /** set the order for filter, by default, it is 10 */ - order?: number; - /** The filter value, this will be used to compute name, or getting the current value, to initiate your form */ - value?: any; - /** If you want to have filter that is not displayed on the list */ - hide?: boolean; - /** If you have enabled server filter, specify witch filters will be call to server, default to false. */ - server?: boolean; - /** The function to apply filters, by default use defaultFilter helpers, that will search the value in the object */ - predicate: ( entity: getEntityType, index: number, array: getEntityType[] | HashMap>, filter: AkitaFilterBase | AkitaFilterLocal | AkitaFilterServer ) => boolean; - /** add any other data you want to add **/ - [key: string]: any; - }; -``` - -- Id and function were mandatored. (By default, Id will guid(), and default function, will be defaultFilter helpers). - -- But you can set a name, that will be useful to display the filter in the ui. (by default, it will be calculated with ID and value). - -- You can set the value, that could be used in your filter function, or retrieve the value for a filter (in ex to init the form filter) - -- Or it could be useful, to execute a filter at the begin or the end. (Could be useful to execute simple filter at the beginning, and complex filter like full search at the end) - -- hide: true, it will be applied and not displayed in the ui. - - -# AkitaFilterPlugins API - -## Get Entity -### selectAllByFilters(options?: SelectAllOptions*): Observable[] | HashMap>> - -The main function to subscribe to filtered data. Select All Entity with an apply filter to it, and updated with any change (entity or filter) - -You can pass the same options than selectAll Function in EntityQuery. - -## Manage filters - -### selectFilters(): Observable - -Select all the filters - -Note: filters with hide=true, will not be displayed. If you want it, call directly the filterQuery : - -```typescript -this.filterQuery.selectAll() -``` - -### getFilters(): AkitaFilter[] - -Get all the current snapshot filters -Note: filters with hide=true, will not be displayed. If you want it, call directly the filterQuery : -```typescript -this.filterQuery.getAll() -``` - -### setFilter(filter: Partial) - -Create or update a filter (give a Partial AkitaFilter object, all mandatory properties missing will be calculated) - -```typescript -filterPlugin.setFilter({ - id: 'fastDelivery', - name: 'Only fast Delivery', - value: true, - order: 1, - predicate: (value: ProductPlant, index, array) => value.rapidDelivery - }); -``` - -### setFilters(filter: Partial[]) - -Create or update multiples filters at once (will trigger only one change) - - -### removeFilter(id: string) - -Remove a specified filter by their id name - -### removeFilters(id: string[]) - -Remove multiples filters at once by their id name (will trigger only one change) - -### clearFilters() - -Remove all filters. - -### getFilterValue(id: string): any | null - -Get filter value or return null, if value not available. - -Usefull to set init a form value, ex: - -```typescript -this.filterForm.controls.searchControl.setValue( this.productsService.getFilterValue('search') ); -``` - -## Example to display the filters list - -```typescript -@Component({ - selector: 'app-list-filter', - changeDetection: ChangeDetectionStrategy.OnPush, - template: ` -
- Filter : - -
- {{filter.name}} - close -
- - remove all - -
- ` -}) -export class ListFiltersComponent { - -private filters$: Observable; - - constructor(private productsService: ProductsFiltersService) {} - - ngOnInit() { - this.filters$ = this.productsService.selectFilters(); - } - - removeFilter(id: any) { - this.productsService.removeFilter(id); - } - - removeFilterAll() { - this.productsService.clearFilters(); - } -} -``` - -## Sorting - -You could also set sorting, that will be applied after the filter. Change sorting will also re-emit newly sorted data. - -### setSortBy(order: SortByOptions) - -set the sort value - -### getSortValue(): SortByOptions | null - -Retrieve the defined sort value, - -## Advanced - -All filter is managed by an EntityStore, if you need to do more you could access it and use all standard API - -### AkitaFilterPlugins.filterStore - -get the filter store, It's an Entity store. Be getting the instance, you could do everything than EntityStore could be done. - -### AkitaFilterPlugins.filterQuery - -get the Filter Query. To query the list of your filters. Use the API of EntityFilters. - -### set the filterStore name. - -If you want to use a different filterStore name, you can set it setting params : filtersStoreName when create plugins: -```typescript -myFilter = new AkitaFiltersPlugin(this.myEntitiesQuery, {filtersStoreName: 'newFiltersName'}); -``` - -By default, the name will, your 'EntityStoreName' concat with 'Filter' - - -### AkitaFilters set AkitaFiltersStore and AkitaFiltersQuery (version 4.x) - -If you want to create an akitaFiltersPlugin by giving the AkitaFiltersStore or AkitaFiltersQuery, -You can specify in constructor params, an existing AkitaFiltersStore or AkitaFiltersQuery. -Useful to create another plugins that use the same Filters store, for exemple to separate your query. -@see issue : https://github.com/manudss/akita-filters-plugin/issues/10 - -```typescript - const myFiltersStore = new AkitaFiltersStore("MyFilters"); - const myFiltersQuery = new AkitaFiltersQuery(filtersStore); - - myFilter = new AkitaFiltersPlugin(this.myEntitiesQuery, - {filtersStore: myFiltersStore, filtersQuery: myFiltersQuery}); -``` - -# Filter helpers Functions - -In filter-utils.ts file, there is a helper function, to do some search filters. - -## function defaultFilter(inElement: E, index: number, array: E[], filter: Filter) - -Helper function to do a default filter, that will do a search if the value is the object, or equals otherwise. (only if the filter value is defined) - -```typescript -this.filterForm.controls.search.valueChanges.pipe(untilDestroyed(this)).subscribe((search: string) => { - if (search) { - this.productsService.setFilter({ - id: 'search', - value: search, - order: 20, - name: `" ${search} "`, - - predicate: defaultFilter); - } else { - this.productsService.removeFilter('search'); - } - }); -``` - -## function searchFilter(searchKey: string, inObj: Object) - -Helper function to do a search on all string element - -```typescript -this.filterForm.controls.search.valueChanges.pipe(untilDestroyed(this)).subscribe((search: string) => { - if (search) { - this.productsService.setFilter({ - id: 'search', - value: search, - order: 20, - name: `" ${search} "`, - - predicate: (value: ProductPlant, index, array) => { - return searchFilter(search, value); - } - }); - } else { - this.productsService.removeFilter('search'); - } - }); -``` - -## function searchFilterIn(searchKey: string, inObj: Object, inKey: string) - -Helper function to do a search in one string key of an object - -```typescript -this.filterForm.controls.search.valueChanges.pipe(untilDestroyed(this)).subscribe((search: string) => { - if (search) { - this.productsService.setFilter({ - id: 'search', - value: search, - order: 20, - name: `" ${search} "`, - - predicate: (value: ProductPlant, index, array) => { - return searchFilterIn(search, value, 'name'); - } - }); - } else { - this.productsService.removeFilter('search'); - } - }); -``` - -### With Server : apply filters from server - -Previous options applys all filters locally. But some times, you wants to call filters by making request to server. -To do this, you need to setWithServer options to your AkitaFiltersPlugin. You will provide a callback function, that will be called everytime a filter changed. -You will make your call, and return this observable. AkitaFiltersPlugin will subscribe to this observable, and add your new data in the store. -An exemple, is available in playground page "photos" - -```typescript -myFilter = new AkitaFiltersPlugin(this.myEntitiesQuery) -.withServer((filtersNormalized: string | HashMap) => - { - return this.httpClient.get({params: filtersNormalized as HashMap}); // make here your pull request to server and return the observable - }); -``` -The data will be filtersNormalized that will be returned by getNormalizedFilters(). -This function will return all your server filters in a normalized format : - -By default return an key value object, with all server filters : -```json -{filter1: 'value 1', filter2: 'value 2'} -``` -or if you specify the NormalizedFilterOptions options in `withServer(Callbackfunc, {asQueryParams: true})` - -You will have directly a serialized version for your query params: -`filter1=value%201&filter2=value%202` - -You can also give some others options : -```typescript -ìnterface NormalizedFilterOptions { - asQueryParams?: boolean; // display as query params : filter1=value%201&filter2=value%202 - withSort?: boolean; // To include sort : { filter1: 'value 1', - // filter2: 'value 2', - // sortBy: 'id', - // sortByOrder: 'desc' } - // or as query params : filter1=value%201&filter2=value%202&sortBy=id&sortByOrder=desc - sortByKey?: string; // to specify the sortBy key used in previous example, default 'sortBy' - sortByOrderKey?: string; // to specify the sortBy key used in previous example, 'sortByOrder' - // will result for example : filter1=value%201&filter2=value%202&_sort=id&_order=desc -} -``` - -This will return only all filters that was set as `server = true`. - -In your components, you will need to only subecribe to your selectAll() function from your store, to get all new data. - -Or you can also combine it with locals filters or sort (if you add some filters with ``server: false`` ). In this case subscribe to selectAllByFilters(). - - - -# BONUS: Angular Material Datasource - -This specific package is only for Angular Material datatable. But akita filters plugins could be used without angular material. And maybe without angular. -This was released since version 4.x as a subpackage to avoid error, when not using Angular Material. - -## Data Connector for Angular Material Table. - -For dealing with angular material table, you need to provide a Data Connector. -This connector, help you by just giving the Entity Store. Data Connector, will deal with Akita Filter for you. - -Define your data source here : -```typescript - this.dataSource = new AkitaMatDataSource(EntityQuery); - this.dataSource.setDefaultSort('colomnName', 'asc'); -``` - -Import it with submodule package : -```typescript -import { AkitaMatDataSource } from 'akita-filters-mat-datasource'; -``` - -then use it in Mat Data Table like other DataSource. - -```angular2html -...
-``` - -#### Demo - -a demo page is available in the playground "angular-material-demo" - -#### Dependencies - -Need to have installed in your project these api : -"@angular/material": "latest", -"@angular/cdk": "latest" - -#### Constructor, use existing AkitaFiltersPlugin - -If needed you can specify, an already existing AkitaFiltersPlugins in the constructor. Usefull to share it with another page/components. @see demo : angular-material-demo. -Else, it will create an internal AkitaFiltersPlugins. - -```typescript - this.dataSource = new AkitaMatDataSource(this.productsQuery, this.productsService.filtersProduct); -``` - -## Function - -Then you have some function that you can use for manage filters - -### filter/search properties : set search(search: string) - -By setting search properties, you set a filter like search. -```typescript -this.dataSource.search = "Search"; -``` -Both use filter and filter, but prefer using search, as filter is so confusing with setFilters functions. (filter is here to be iso functionality, then the MatDataSource) -You can also customize the filter id, if different in your server api - -```typescript - this.dataSource = new AkitaMatDataSource(this.photosQuery, this.photosService, { - searchFilterId: 'search', // you can set the id of this filter, usefull if the params is different for you (default : "search") -}); -``` - -### Sort properties : set sort(sort: MatSort) - -By setting Mat Sort for sorting you can set the sort. Used by Mat Table when changing filter - -```typescript - @ViewChild(MatSort, { static: true }) sort: MatSort; - - ngAfterViewInit(): void { - this.dataSource.sort = this.sort; - } -``` - - -### Paginator properties : set paginator(paginator: MatPaginator) - -By setting MatPaginator for enable pagination with datasource. Used by Mat Paginator to define pagination - -```typescript -@ViewChild(MatPaginator, { static: true }) paginator: MatPaginator; - - ngAfterViewInit(): void { - this.dataSource.paginator = this.paginator; - } -``` - -And add the paginator directly like this in the template. No need to give the size, as it will be setted by the datasource. - -```html - - -``` -### Paginator server side : use server side pagination - -By setting MatPaginator (cf before), it will use a local paginator. -You can specify the option : "serverPagination" to use server side pagination. (Need also to set a MatPaginator). -It will subscribe to MatPaginator change page, and create server filter that send the page Number, and page Size. -We will be then notified in withServer callback function. - -See exemple in exemple page "photos" - -```typescript - this.dataSource = new AkitaMatDataSource(this.photosQuery, this.photosService, { - serverPagination: true, // set to true, to use server side pagination. - pageIndexId: '_page', // you can set the id of this filter, usefull if the params is different for you (default : "page") - pageIndexDisplay: true, // Set to true to display page filter (default: false) - pageIndexName: 'Page', // Set the Name, to you filter, usefull if you want to display the filter : "Name: (value)" (default: "Page") - pageSizeId: '_limit', // you can set the id of this filter, usefull if the params is different for you (default : "size") - pageSizeDisplay: true, // Set to true to display size filter (default: false) - pageSizeName: 'Size', // Set the Name, to you filter, usefull if you want to display the filter : "Name: (value)" (default: "Size") -}); -``` - - -But you will need to set the total by your one, depending on how you get this information. - -```typescript - this.dataSource.total = 100; // set the total to Mat Paginator - console.log('total number', this.dataSource.total); // or get the setted total, was the length setted in Mat Paginator -``` - - - - -### AkitaFilters properties : get akitaFiltersPlugin(): AkitaFiltersPlugin - -Access to the AkitaFilters plugins instance, and use all function from AkitaFilters plugins. -```typescript -this.dataSource.akitaFiltersPlugin.setFilter({ - id: 'category', - value: 'garden', - predicate: (value: ProductPlant, index, array) => value.category === category - }); -``` - - -### setDefaultSort : public setDefaultSort(sortColumun: keyof T, direction: 'asc' | 'desc' = 'asc') - -Set the default sort. -```typescript -this.dataSource.setDefaultSort('colomnName', 'asc'); -``` - -### Proxy helper function - -Some proxy function, just to call AkitaFilters Plugins. -```typescript -* setFilter(filter: Partial>): void; // Create or update a filter. Any mandatory properties, will be added -* setFilters(filter: Partial>[]): void; // Create or update multiples filters in one time with emit changes onlu once -* removeFilter(id: ID): void; // Remove a filter by their name -* removeFilters(id: ID[]): void; // Remove multiples filters with emit changes onlu once -* clearFilters(): void; // Remove all filters -* getFilterValue< S >(id: string): E | null; // Get a filters values -``` -### WithServer : you can also use Akita-Mat-DataSource with server call - -You can also use AkitaFilters plugins withServer in Akita-Mat-DataSource by using AkitaFilters Plugins function. -Or there is also a function similar in Akita-Mat-DataSource. - - - - -### Breaking Changes : 3.x to 4.x - -Akita-mat-data-source is now a subpackage to avoid error with akita-filters-plugin, if you don't use Angular Material. - -Changes this -```typescript -import { AkitaMatDataSource } from 'akita-filters-plugin'; -``` -to -```typescript -import { AkitaMatDataSource } from 'akita-filters-mat-datasource'; -``` - - - -### Breaking Changes : 2.x to 3.x - -To correspond with Akita, you need now to specify only the entityState. The entity element is calculated as in akita with getEntityType - -Changes this -```typescript -new AkitaFiltersPlugin() -``` -to -```typescript -new AkitaFiltersPlugin() -``` - -Changes this -```typescript -AkitaFilter[] -``` -to -```typescript -AkitaFilter[] -``` - -Changes this -```typescript -new AkitaMatDataSource() -``` -to -```typescript -new AkitaMatDataSource() -``` diff --git a/docs/favicon.ico b/docs/favicon.ico deleted file mode 100644 index 8081c7ceaf2be08bf59010158c586170d9d2d517..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 5430 zcmc(je{54#6vvCoAI3i*G5%$U7!sA3wtMZ$fH6V9C`=eXGJb@R1%(I_{vnZtpD{6n z5Pl{DmxzBDbrB>}`90e12m8T*36WoeDLA&SD_hw{H^wM!cl_RWcVA!I+x87ee975; z@4kD^=bYPn&pmG@(+JZ`rqQEKxW<}RzhW}I!|ulN=fmjVi@x{p$cC`)5$a!)X&U+blKNvN5tg=uLvuLnuqRM;Yc*swiexsoh#XPNu{9F#c`G zQLe{yWA(Y6(;>y|-efAy11k<09(@Oo1B2@0`PtZSkqK&${ zgEY}`W@t{%?9u5rF?}Y7OL{338l*JY#P!%MVQY@oqnItpZ}?s z!r?*kwuR{A@jg2Chlf0^{q*>8n5Ir~YWf*wmsh7B5&EpHfd5@xVaj&gqsdui^spyL zB|kUoblGoO7G(MuKTfa9?pGH0@QP^b#!lM1yHWLh*2iq#`C1TdrnO-d#?Oh@XV2HK zKA{`eo{--^K&MW66Lgsktfvn#cCAc*(}qsfhrvOjMGLE?`dHVipu1J3Kgr%g?cNa8 z)pkmC8DGH~fG+dlrp(5^-QBeEvkOvv#q7MBVLtm2oD^$lJZx--_=K&Ttd=-krx(Bb zcEoKJda@S!%%@`P-##$>*u%T*mh+QjV@)Qa=Mk1?#zLk+M4tIt%}wagT{5J%!tXAE;r{@=bb%nNVxvI+C+$t?!VJ@0d@HIyMJTI{vEw0Ul ze(ha!e&qANbTL1ZneNl45t=#Ot??C0MHjjgY8%*mGisN|S6%g3;Hlx#fMNcL<87MW zZ>6moo1YD?P!fJ#Jb(4)_cc50X5n0KoDYfdPoL^iV`k&o{LPyaoqMqk92wVM#_O0l z09$(A-D+gVIlq4TA&{1T@BsUH`Bm=r#l$Z51J-U&F32+hfUP-iLo=jg7Xmy+WLq6_tWv&`wDlz#`&)Jp~iQf zZP)tu>}pIIJKuw+$&t}GQuqMd%Z>0?t%&BM&Wo^4P^Y z)c6h^f2R>X8*}q|bblAF?@;%?2>$y+cMQbN{X$)^R>vtNq_5AB|0N5U*d^T?X9{xQnJYeU{ zoZL#obI;~Pp95f1`%X3D$Mh*4^?O?IT~7HqlWguezmg?Ybq|7>qQ(@pPHbE9V?f|( z+0xo!#m@Np9PljsyxBY-UA*{U*la#8Wz2sO|48_-5t8%_!n?S$zlGe+NA%?vmxjS- zHE5O3ZarU=X}$7>;Okp(UWXJxI%G_J-@IH;%5#Rt$(WUX?6*Ux!IRd$dLP6+SmPn= z8zjm4jGjN772R{FGkXwcNv8GBcZI#@Y2m{RNF_w8(Z%^A*!bS*!}s6sh*NnURytky humW;*g7R+&|Ledvc- - - Akita Filter plugin example - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/package.json b/package.json index e6e7d5f..56de234 100644 --- a/package.json +++ b/package.json @@ -5,8 +5,9 @@ "ng": "ng", "start": "ng serve --port 4949", "build": "ng build --configuration production --output-path docs --base-href /akita-filters-plugin/", - "compile": "ng build akita-filters-plugin --configuration production", - "compile:datasource": "ng build akita-mat-datasource --configuration production", + "compile": "ng-packagr -p ./projects/akita-filters-plugin/ng-package.json", + "compile:forDatasource": "ng-packagr -p ./projects/akita-filters-plugin/ng-package2.json", + "compile:datasource": "ng-packagr -p ./projects/akita-mat-datasource/ng-package.json", "test": "jest --ci", "test:debug": "node --inspect-brk ./node_modules/.bin/jest --runInBand --watch", "test:watch": "jest --watch", @@ -44,7 +45,7 @@ "ngx-markdown": "17.1.1", "ngx-take-until-destroy": "5.4.0", "rxjs": "7.8.1", - "tslib": "2.6.2", + "tslib": "2.4.1", "zone.js": "0.14.4" }, "devDependencies": { @@ -58,6 +59,7 @@ "@angular/compiler-cli": "17.2.2", "@angular/language-service": "17.2.2", "@jest/globals": "29.7.0", + "@qiwi/semantic-release-gh-pages-plugin": "^5.2.12", "@semantic-release/changelog": "6.0.3", "@semantic-release/commit-analyzer": "11.1.0", "@semantic-release/git": "10.0.1", @@ -166,7 +168,8 @@ "message": "release(version): Release ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}" } ], - "@semantic-release/github" + "@semantic-release/github", + "@qiwi/semantic-release-gh-pages-plugin" ], "extends": "semantic-release-npm-github-publish" } diff --git a/projects/akita-filters-plugin/ng-package.json b/projects/akita-filters-plugin/ng-package.json index eb25c20..08680d0 100644 --- a/projects/akita-filters-plugin/ng-package.json +++ b/projects/akita-filters-plugin/ng-package.json @@ -2,6 +2,6 @@ "$schema": "../../node_modules/ng-packagr/ng-package.schema.json", "dest": "../../dist/akita-filters-plugin", "lib": { - "entryFile": "src/public_api.ts" + "entryFile": "src/index.ts" } } diff --git a/projects/akita-filters-plugin/ng-package2.json b/projects/akita-filters-plugin/ng-package2.json new file mode 100644 index 0000000..9d4959f --- /dev/null +++ b/projects/akita-filters-plugin/ng-package2.json @@ -0,0 +1,7 @@ +{ + "$schema": "../../node_modules/ng-packagr/ng-package.schema.json", + "dest": "../../node_modules/akita-filters-plugin", + "lib": { + "entryFile": "src/index.ts" + } +} diff --git a/projects/akita-filters-plugin/package.json b/projects/akita-filters-plugin/package.json index f48fe0a..7b8b0ed 100644 --- a/projects/akita-filters-plugin/package.json +++ b/projects/akita-filters-plugin/package.json @@ -9,6 +9,9 @@ "@angular/common": ">=16.0.0", "@angular/core": ">=16.0.0" }, + "dependencies": { + "tslib": "^2.4.1" + }, "repository": { "type": "git", "url": "https://github.com/manudss/akita-filters-plugin.git" diff --git a/projects/akita-filters-plugin/src/public_api.ts b/projects/akita-filters-plugin/src/index.ts similarity index 100% rename from projects/akita-filters-plugin/src/public_api.ts rename to projects/akita-filters-plugin/src/index.ts diff --git a/projects/akita-mat-datasource/ng-package.json b/projects/akita-mat-datasource/ng-package.json index 4f7d045..ada61a1 100644 --- a/projects/akita-mat-datasource/ng-package.json +++ b/projects/akita-mat-datasource/ng-package.json @@ -2,6 +2,6 @@ "$schema": "../../node_modules/ng-packagr/ng-package.schema.json", "dest": "../../dist/akita-filters-mat-datasource", "lib": { - "entryFile": "src/public-api.ts" + "entryFile": "src/index.ts" } } diff --git a/projects/akita-mat-datasource/package.json b/projects/akita-mat-datasource/package.json index 7ce0fa5..78fb85b 100644 --- a/projects/akita-mat-datasource/package.json +++ b/projects/akita-mat-datasource/package.json @@ -11,6 +11,9 @@ "@angular/core": ">=16.0.0", "@angular/material": ">=16.0.0" }, + "dependencies": { + "tslib": "^2.4.1" + }, "repository": { "type": "git", "url": "https://github.com/manudss/akita-filters-plugin.git" diff --git a/projects/akita-mat-datasource/src/public-api.ts b/projects/akita-mat-datasource/src/index.ts similarity index 99% rename from projects/akita-mat-datasource/src/public-api.ts rename to projects/akita-mat-datasource/src/index.ts index 8b8e829..3a0470e 100644 --- a/projects/akita-mat-datasource/src/public-api.ts +++ b/projects/akita-mat-datasource/src/index.ts @@ -4,3 +4,4 @@ export * from './lib/akita-mat-data-source'; export {DataSourceWithServerOptions} from './lib'; export {MatTableDataSourceInterface} from './lib'; + diff --git a/src/app/app.component.html b/src/app/app.component.html index 6aabc39..9baa034 100644 --- a/src/app/app.component.html +++ b/src/app/app.component.html @@ -6,7 +6,7 @@