ngx-material-entity 0.1.0 → 0.1.3

package/CONTRIBUTING.md

@@ -13,6 +13,7 @@ All development is done using github.
 - [Codestyle](#codestyle)
   - [Decorator Configs / User Input](#decorator-configs--user-input)
   - [Naming conventions](#naming-conventions)
+- [Tests](#tests)
 - [Workflow for submitting Code Changes](#workflow-for-submitting-code-changes)
 - [License](#license)
 
@@ -75,13 +76,18 @@ Their selector should follow the same logic:
 
 In the folder structure however, you are encouraged to leave the prefix out, because the user will never see this anyway.
 
+# Tests
+The testing consists of two test types:
+1. Unit Tests with Jest, should be used for everything that isn't an angular component
+2. E2E Tests using Cypress, should be used to test how angular components behave in the "real" world
+
 # Workflow for submitting Code Changes
 
 1. Create an issue if it not already exists.
 2. Create a branch for that specific issue (The best way to this is directly inside the issue on the right side under "Development". That way the the issue and the branch are automatically linked)
 3. Checkout the new branch
 4. Add your code
-5. Update / add tests.
+5. Update / add [tests](#tests).
 6. Update the documentation.
 7. Check that tests and linting passes.
    1. For tests: `npm run test`

package/README.md

@@ -1,9 +1,11 @@
 # NgxMaterialEntity
 Create Entities and define how to display them directly on their properties.
-<br>
 Can even generate complete and highly customizable CRUD-Tables for them.
 
 [![CI/CD](https://github.com/tim-fabian/ngx-material-entity/actions/workflows/main.yml/badge.svg?branch=release)](https://github.com/tim-fabian/ngx-material-entity/actions/workflows/main.yml)
+[![npm version](https://badge.fury.io/js/ngx-material-entity.svg)](https://badge.fury.io/js/ngx-material-entity)
+[![Known Vulnerabilities](https://snyk.io/test/npm/ngx-material-entity/badge.svg)](https://snyk.io/test/npm/ngx-material-entity)
+[![codecov](https://codecov.io/gh/tim-fabian/ngx-material-entity/branch/dev/graph/badge.svg?token=8Y45KLA74K)](https://codecov.io/gh/tim-fabian/ngx-material-entity)
 
 # Table of Contents
 - [NgxMaterialEntity](#ngxmaterialentity)
@@ -688,4 +690,3 @@ export interface MultiSelectAction<EntityType extends Entity> {
     enabled?: (entity: EntityType[]) => boolean;
 }
 ```
-//TODO

package/classes/base-builder.class.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The abstract BaseBuilder class.
+ */
+export declare abstract class BaseBuilder<InternalType extends InputType, InputType extends object> {
+    private readonly data;
+    private readonly inputData?;
+    protected constructor(data?: InputType);
+    /**
+     * Generates the internal data from the given user inputs.
+     *
+     * @param data - The input from the user.
+     * @returns The internal data.
+     */
+    protected abstract generateBaseData(data?: InputType): InternalType;
+    /**
+     * Used to validate the user input in the constructor.
+     *
+     * @param data - The user input.
+     */
+    protected validateInput(data?: InputType): void;
+    /**
+     * Sets the value for the given key if no user value was provided.
+     *
+     * @param key - The key to set the default value for.
+     * @param value - The value to set when nothing was provided.
+     * @returns The Builder.
+     */
+    withDefault(key: keyof InputType, value: Omit<InternalType[keyof InputType], 'undefined'>): BaseBuilder<InternalType, InputType>;
+    /**
+     * Method used to get the final build value after applying all chaining.
+     *
+     * @returns The build value.
+     */
+    getResult(): InternalType;
+}

package/classes/entity-model.class.d.ts

@@ -3,7 +3,7 @@
  */
 export declare abstract class Entity {
     /**
-     * A unique identifier for the Entity
+     * A unique identifier for the Entity.
      */
     id: string;
 }

package/classes/entity-service.class.d.ts

@@ -12,45 +12,55 @@ export declare abstract class EntityService<EntityType extends Entity> {
     /**
      * The base url used for api requests. If u want to have more control over this,
      * you can override the create, read, update and delete methods.
-     * @create Sends a POST-Request to baseUrl
-     * @read Sends a GET-Request to baseUrl
-     * @update Sends a PATCH-Request to baseUrl/{id}
-     * @delete Sends a DEL-Request to baseUrl/{id}
+     *
+     * Create Sends a POST-Request to baseUrl.
+     *
+     * Read Sends a GET-Request to baseUrl.
+     *
+     * Update Sends a PATCH-Request to baseUrl/{id}.
+     *
+     * Delete Sends a DEL-Request to baseUrl/{id}.
      */
     abstract readonly baseUrl: string;
     /**
-     * a subject of all the entity values.
+     * A subject of all the entity values.
      * Can be subscribed to when you want to do a specific thing whenever the entities change.
      */
     readonly entitiesSubject: BehaviorSubject<EntityType[]>;
     /**
-     * gets the entities in an array from the internal entitiesSubject
+     * Gets the entities in an array from the internal entitiesSubject.
+     *
+     * @returns The current entities in form of an array.
      */
     get entities(): EntityType[];
     constructor(http: HttpClient);
     /**
-     * Creates a new Entity and pushes it to the entities array
-     * @param entity The data of the entity to create.
+     * Creates a new Entity and pushes it to the entities array.
+     *
+     * @param entity - The data of the entity to create.
      * All values that should be omitted will be removed from it inside this method.
-     * @returns A Promise of the created entity
+     * @returns A Promise of the created entity.
      */
     create(entity: EntityType): Promise<EntityType>;
     /**
-     * Gets all existing entities and pushes them to the entites array
-     * @returns A Promise of all received Entities
+     * Gets all existing entities and pushes them to the entities array.
+     *
+     * @returns A Promise of all received Entities.
      */
     read(): Promise<EntityType[]>;
     /**
-     * Updates a specific Entity
-     * @param entity The updated Entity
+     * Updates a specific Entity.
+     *
+     * @param entity - The updated Entity
      * All values that should be omitted will be removed from it inside this method.
-     * @param entityPriorChanges The current Entity.
-     * It Is used to get changed values and only update them instead of sending the whole entity data
+     * @param entityPriorChanges - The current Entity.
+     * It Is used to get changed values and only update them instead of sending the whole entity data.
      */
     update(entity: EntityType, entityPriorChanges: EntityType): Promise<void>;
     /**
-     * Method to delete a specific Entity
-     * @param id The id of the element to delete
+     * Deletes a specific Entity.
+     *
+     * @param id - The id of the element to delete.
      */
     delete(id: string): Promise<void>;
 }

package/classes/entity-utilities.class.d.ts

@@ -1,40 +1,47 @@
 import { DecoratorType, DecoratorTypes } from '../decorators/base/decorator-types.enum';
 import { Entity } from './entity-model.class';
 /**
- * Contains HelperMethods around handling Entities and their property-metadata
+ * Contains HelperMethods around handling Entities and their property-metadata.
  */
 export declare abstract class EntityUtilities {
     /**
-     * Gets the properties to omit when updating the entity
-     * @returns The properties which should be left out for updating a new Entity
+     * Gets the properties to omit when updating the entity.
+     *
+     * @param entity - The entity to get the properties which should be left out for updating from.
+     * @returns The properties which should be left out for updating an Entity.
      */
     static getOmitForUpdate<EntityType extends Entity>(entity: EntityType): (keyof EntityType)[];
     /**
-     * Gets the properties to omit when creating new entities
-     * @returns The properties which should be left out for creating a new Entity
+     * Gets the properties to omit when creating new entities.
+     *
+     * @param entity - The entity to get the properties which should be left out for creating from.
+     * @returns The properties which should be left out for creating a new Entity.
      */
     static getOmitForCreate<EntityType extends Entity>(entity: EntityType): (keyof EntityType)[];
     /**
-     * Gets the metadata included in an property
-     * @param entity The entity with the property to get the metadata from
-     * @param propertyKey The property on the given Entity to get the metadata from
-     * @param type For secure Typing, defines the returned PropertyConfig
-     * @returns The metadata of the property
+     * Gets the metadata included in an property.
+     *
+     * @param entity - The entity with the property to get the metadata from.
+     * @param propertyKey - The property on the given Entity to get the metadata from.
+     * @param type - For secure Typing, defines the returned PropertyConfig.
+     * @returns The metadata of the property.
+     * @throws When no metadata can be found for the given property.
      */
-    static getPropertyMetadata<EntityType extends Entity, T extends DecoratorTypes>(entity: EntityType, propertyKey: keyof EntityType, type: T): DecoratorType<T>;
+    static getPropertyMetadata<EntityType extends Entity, T extends DecoratorTypes>(entity: EntityType, propertyKey: keyof EntityType, type?: T): DecoratorType<T>;
     /**
      * Gets the type of the property-metadata.
-     * @param entity The entity with the property to get the type from
-     * @param propertyKey The property on the given Entity to get the type from
-     * @returns The type of the metadata
+     *
+     * @param entity - The entity with the property to get the type from.
+     * @param propertyKey - The property on the given Entity to get the type from.
+     * @returns The type of the metadata.
+     * @throws Will throw an error if no metadata can be found for the given property.
      */
     static getPropertyType<EntityType extends Entity>(entity: EntityType, propertyKey: keyof EntityType): DecoratorTypes;
     /**
      * Sets all property values based on a given entity data-object.
-     * @param entity The data object to get the property values from.
-     * @param target
-     * the target object that needs to be constructed
-     * (if called inside a Entity constructor its usually this)
+     *
+     * @param target - The target object that needs to be constructed (if called inside an Entity constructor its usually this).
+     * @param entity - The data object to get the property values from.
      * @alias new
      * @alias build
      * @alias construct
@@ -44,52 +51,95 @@ export declare abstract class EntityUtilities {
     static build: typeof EntityUtilities.new;
     /**
      * Checks if the values on an entity are valid.
-     * Also checks all the validators given by the metadata ("required", "maxLength" etc.)
-     * @param entity The entity to validate.
-     * @param omit Whether to check for creatiung or editing validity
+     * Also checks all the validators given by the metadata ("required", "maxLength" etc.).
+     *
+     * @param entity - The entity to validate.
+     * @param omit - Whether to check for creating or editing validity.
      * @returns Whether or not the entity is valid.
      */
-    static isEntityValid<EntityType extends Entity>(entity: EntityType, omit: 'create' | 'edit'): boolean;
+    static isEntityValid<EntityType extends Entity>(entity: EntityType, omit: 'create' | 'update'): boolean;
     /**
-     * Checks if a single property value is valid
-     * @param entity The entity where the property is from
-     * @param key The name of the property
-     * @returns Whether or not the property value is valid
+     * Checks if a single property value is valid.
+     *
+     * @param entity - The entity where the property is from.
+     * @param key - The name of the property.
+     * @param omit - Whether to check if the given entity is valid for creation or updating.
+     * @returns Whether or not the property value is valid.
+     * @throws Throws when it extracts an unknown metadata type.
      */
     private static isPropertyValid;
     /**
-     * Checks if an entity is "dirty" (if its values have changed)
-     * @param entity The entity after all changes
-     * @param entityPriorChanges The entity before the changes
-     * @returns Whether or not the entity is dirty
+     * Checks if an entity is "dirty" (if its values have changed).
+     *
+     * @param entity - The entity after all changes.
+     * @param entityPriorChanges - The entity before the changes.
+     * @returns Whether or not the entity is dirty.
      */
     static dirty(entity: Entity, entityPriorChanges: Entity): boolean;
     /**
-     * Compares two Entities and returns their difference in an object
-     * @param entity The first entity to compare
-     * @param entityPriorChanges The second entity to compare
-     * @returns The difference between the two Entities in form of a Partial
+     * Compares two Entities and returns their difference in an object.
+     *
+     * @param entity - The first entity to compare.
+     * @param entityPriorChanges - The second entity to compare.
+     * @returns The difference between the two Entities in form of a Partial.
      */
     static difference<EntityType extends Entity>(entity: EntityType, entityPriorChanges: EntityType): Partial<EntityType>;
     /**
-     * compare function for sorting entity keys by their order value
-     * @param a first key of entity
-     * @param b second key of entity
-     * @param entity current entity (used to get metadata of entity keys)
+     * Compare function for sorting entity keys by their order value.
+     *
+     * @param a - First key of entity.
+     * @param b - Second key of entity.
+     * @param entity - Current entity (used to get metadata of entity keys).
+     * @returns 0 if both values have the same order, a negative value if X, a positive value if Y.
      */
     static compareOrder<EntityType extends Entity>(a: keyof EntityType, b: keyof EntityType, entity: EntityType): number;
     /**
-     * gets the bootstrap column values for "lg", "md", "sm"
-     * @param entity entity to get the bootstrap column values of the key
-     * @param key key of the property to get bootstrap column values from
-     * @param type defines for which screensize the column values should be returned
-     * @returns bootstrap column value
+     * Gets the bootstrap column values for "lg", "md", "sm".
+     *
+     * @param entity - Entity to get the bootstrap column values of the key.
+     * @param key - Key of the property to get bootstrap column values from.
+     * @param type - Defines for which screen size the column values should be returned.
+     * @returns Bootstrap column value.
      */
     static getWidth<EntityType extends Entity>(entity: EntityType, key: keyof EntityType, type: 'lg' | 'md' | 'sm'): number;
     /**
-     * Resets all changes on an entity
-     * @param entity The entity to reset
-     * @param entityPriorChanges The entity before any changes
+     * Resets all changes on an entity.
+     *
+     * @param entity - The entity to reset.
+     * @param entityPriorChanges - The entity before any changes.
      */
     static resetChangesOnEntity<EntityType extends Entity>(entity: EntityType, entityPriorChanges: EntityType): void;
+    /**
+     * Gets the rows that are used to display the given entity.
+     *
+     * @param entity - The entity to get the rows from.
+     * @param hideOmitForCreate - Whether or not keys with the metadata omitForCreate should be filtered out.
+     * @param hideOmitForEdit - Whether or not keys with the metadata omitForUpdate should be filtered out.
+     * @returns The sorted Rows containing the row number and the keys to display in that row.
+     */
+    static getEntityRows<EntityType extends Entity>(entity: EntityType, hideOmitForCreate?: boolean, hideOmitForEdit?: boolean): EntityRow<EntityType>[];
+    private static getKeysForRow;
+    private static getNumberOfRows;
+    /**
+     * Gets the keys of the provided entity correctly typed.
+     *
+     * @param entity - The entity to get the keys of.
+     * @param hideOmitForCreate - Whether or not keys with the metadata omitForCreate should be filtered out.
+     * @param hideOmitForEdit - Whether or not keys with the metadata omitForUpdate should be filtered out.
+     * @returns An array of keys of the entity.
+     */
+    static keysOf<EntityType extends Entity>(entity: EntityType, hideOmitForCreate?: boolean, hideOmitForEdit?: boolean): (keyof EntityType)[];
+}
+/**
+ * A row that contains all the information about how to display an entity.
+ */
+export interface EntityRow<EntityType extends Entity> {
+    /**
+     * The row in which this should be displayed.
+     */
+    row: number;
+    /**
+     * The keys of the values that should be displayed in that row.
+     */
+    keys: (keyof EntityType)[];
 }

package/components/confirm-dialog/confirm-dialog-data.builder.d.ts

@@ -0,0 +1,23 @@
+import { BaseBuilder } from '../../classes/base-builder.class';
+import { ConfirmDialogData, ConfirmDialogTypes } from './confirm-dialog-data';
+/**
+ * The internal ConfirmDialogData. Requires all default values the user can leave out.
+ */
+export declare class ConfirmDialogDataInternal implements ConfirmDialogData {
+    text: string[];
+    type: ConfirmDialogTypes;
+    confirmButtonLabel: string;
+    cancelButtonLabel: string;
+    title: string;
+    requireConfirmation: boolean;
+    confirmationText?: string;
+    constructor(text: string[], type: ConfirmDialogTypes, confirmButtonLabel: string, cancelButtonLabel: string, title: string, requireConfirmation: boolean, confirmationText?: string);
+}
+/**
+ * The Builder for the ConfirmDialogData. Sets default values.
+ */
+export declare class ConfirmDialogDataBuilder extends BaseBuilder<ConfirmDialogDataInternal, ConfirmDialogData> {
+    constructor(data?: ConfirmDialogData);
+    protected generateBaseData(data?: ConfirmDialogData): ConfirmDialogDataInternal;
+    protected validateInput(data?: ConfirmDialogData): void;
+}

package/components/confirm-dialog/confirm-dialog-data.d.ts

@@ -1,28 +1,37 @@
+/**
+ * The different types of a confirm dialog.
+ * Is used for displaying different buttons accordingly.
+ */
 export declare type ConfirmDialogTypes = 'default' | 'delete' | 'info-only';
 /**
- * The Definition of the Confirm Dialog Data
+ * The Definition of the Confirm Dialog Data.
  */
 export interface ConfirmDialogData {
     /**
-     * An array of paragraphs to display inside the dialog body
+     * An array of paragraphs to display inside the dialog body.
      */
     text?: string[];
     /**
      * The type of the Confirm Dialog. Changes the button layout. Can be either:
-     * @value 'default': A confirm- and a cancel-button
-     * @value 'delete': Like default but the confirm-button is red
-     * @value 'info-only': Only a cancel-button
+     *
+     * 'default': A confirm- and a cancel-button.
+     *
+     * 'delete': Like default but the confirm-button is red.
+     *
+     * 'info-only': Only a cancel-button.
      */
     type?: ConfirmDialogTypes;
     /**
      * The label of the button that confirms the dialog.
      * In case of the 'delete' Dialog this is the string that is shown on the delete-button.
-     * Defaults to "Confirm" or "Delete", depending on the type
+     *
+     * @default 'Confirm' or 'Delete', depending on the type
      */
     confirmButtonLabel?: string;
     /**
      * The label of the button that closes the dialog without doing anything.
-     * Defaults to "Cancel"
+     *
+     * @default 'Cancel'
      */
     cancelButtonLabel?: string;
     /**
@@ -31,7 +40,8 @@ export interface ConfirmDialogData {
     title?: string;
     /**
      * Whether or not a checkbox needs to be selected before the user can confirm the dialog.
-     * Defaults to false.
+     *
+     * @default false
      */
     requireConfirmation?: boolean;
     /**

package/components/confirm-dialog/confirm-dialog.component.d.ts

@@ -1,17 +1,27 @@
 import { OnInit } from '@angular/core';
 import { MatDialogRef } from '@angular/material/dialog';
 import { ConfirmDialogData } from './confirm-dialog-data';
+import { ConfirmDialogDataInternal } from './confirm-dialog-data.builder';
 import * as i0 from "@angular/core";
+/**
+ * The Dialog used whenever confirmation by the user is required (e.g. When the user tries to delete an entity).
+ *
+ * Can be customized with the MAT_DIALOG_DATA "inputData". Customization options are defined in "ConfirmDialogData".
+ */
 export declare class NgxMatEntityConfirmDialogComponent implements OnInit {
     private readonly dialogRef;
-    readonly data: ConfirmDialogData;
-    /**
-     * Used for the checkbox to confirm the action
-     */
+    private readonly inputData;
     confirm: boolean;
-    constructor(dialogRef: MatDialogRef<NgxMatEntityConfirmDialogComponent>, data: ConfirmDialogData);
+    data: ConfirmDialogDataInternal;
+    constructor(dialogRef: MatDialogRef<NgxMatEntityConfirmDialogComponent>, inputData: ConfirmDialogData);
     ngOnInit(): void;
+    /**
+     * Closes the dialog with value 1 to signal that the action should be run.
+     */
     confirmAction(): void;
+    /**
+     * Closes the dialog.
+     */
     cancel(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgxMatEntityConfirmDialogComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NgxMatEntityConfirmDialogComponent, "ngx-mat-entity-confirm-dialog", never, {}, {}, never, never>;

package/components/get-validation-error-message.function.d.ts

@@ -1,7 +1,8 @@
 import { NgModel } from '@angular/forms';
 /**
  * Generates a default error message for most validation errors.
- * @param model The ngModel to get the error from
- * @returns The Validation Error Message to display
+ *
+ * @param model - The ngModel to get the error from.
+ * @returns The Validation Error Message to display.
  */
 export declare function getValidationErrorMessage(model: NgModel): string;

package/components/input/add-array-item-dialog-data.builder.d.ts

@@ -0,0 +1,21 @@
+import { NgModel } from '@angular/forms';
+import { BaseBuilder } from '../../classes/base-builder.class';
+import { Entity } from '../../classes/entity-model.class';
+import { CreateDialogDataInternal } from '../table/create-dialog/create-dialog-data.builder';
+import { AddArrayItemDialogData } from './add-array-item-dialog-data';
+/**
+ * The internal AddArrayItemDialogData. Requires all default values the user can leave out.
+ */
+export declare class AddArrayItemDialogDataInternal<EntityType extends Entity> implements AddArrayItemDialogData<EntityType> {
+    entity: EntityType;
+    createDialogData: CreateDialogDataInternal;
+    getValidationErrorMessage: (model: NgModel) => string;
+    constructor(entity: EntityType, createDialogData: CreateDialogDataInternal, getValidationErrorMessage: (model: NgModel) => string);
+}
+/**
+ * The Builder for the AddArrayItemDialogData. Sets default values.
+ */
+export declare class AddArrayItemDialogDataBuilder<EntityType extends Entity> extends BaseBuilder<AddArrayItemDialogDataInternal<EntityType>, AddArrayItemDialogData<EntityType>> {
+    constructor(data: AddArrayItemDialogData<EntityType>);
+    protected generateBaseData(data: AddArrayItemDialogData<EntityType>): AddArrayItemDialogDataInternal<EntityType>;
+}

package/components/input/add-array-item-dialog-data.d.ts

@@ -0,0 +1,20 @@
+import { NgModel } from '@angular/forms';
+import { Entity } from '../../classes/entity-model.class';
+import { CreateDialogData } from '../table/table-data';
+/**
+ * The configuration options for the dialog that adds items to an array.
+ */
+export interface AddArrayItemDialogData<EntityType extends Entity> {
+    /**
+     * An empty entity that is used as the data model.
+     */
+    entity: EntityType;
+    /**
+     * The info of the generic create-dialog.
+     */
+    createDialogData?: CreateDialogData;
+    /**
+     * A custom function to generate the error-message for invalid inputs.
+     */
+    getValidationErrorMessage?: (model: NgModel) => string;
+}