@jaspero/ng-helpers

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) [![CircleCI](https://circleci.com/gh/Jaspero/ng-helpers.svg?style=svg)](https://circleci.com/gh/Jaspero/ng-helpers) [![NPM Version](https://img.shields.io/npm/v/@jaspero/ng-helpers.svg)](https://www.npmjs.com/package/@jaspero/ng-helpers) # @jaspero/ng-helpers A collection of useful components, directives and pipes for Angular applications. Every item (component, directive and pipe) is published in a separate module, making it easy to just import modules your application will use and not increase bundle size unnecessarily. - [Components](#components) - [Directives](#directives) - [ClickOutsideDirective](#clickoutsidedirective) - [FormTouchOnHoverDirective](#formtouchonhoverdirective) - [StopPropagationDirective](#stoppropagationdirective) - [DebounceChangeDirective](#debouncechangedirective) - [TrackByField](#trackbyfield) - [LoadClickDirective](#loadclickdirective) - [Pipes](#pipes) - [EnumPipe](#enumpipe) - [SanitizePipe](#sanitizepipe) - [TimePassedPipe](#timepassedpipe) - [EnumKeyFormatPipe](#enumkeyformatpipe) - [Helper Classes](#helper-classes) - [OnChange](#onchange) ## Installation To install this library, run: ```bash $ npm install --save @jaspero/ng-helpers ``` Then import any Module you need. For example if you need the `ClickOutsideDirective` import the `ClickOutsideModule`. ## Components ## Directives ### ClickOutsideDirective This directive listens for emitted events on the window object and emits if the event doesn't contain the target element. #### Example ```angular2html <div (jpClickOutside)="doSomething()"></div> ``` #### Use Cases - Closing modals, dropdowns, mobile navigations when clicked outside. - Toggling off one item when another is clicked (accordion) #### Outputs | name | description | | -------------- | ------------------------------------------------------- | | jpClickOutside | Emits when current element isn't contained in the event | #### Inputs | name | type | default | description | | --------------------- | ------- | ------- | ------------------------------------- | | clickOutsideEventType | string | 'click' | event to listen for | | clickOutsideBlock | boolean | false | if true `jpClickOutside` doesn't emit | ### FormTouchOnHoverDirective This directive requires a `FormGroup` or `FormArray` then on mouseenter loops over all controls and marks them touched. #### Example ```angular2html <form [formGroup]="someForm"> <input type="text" formControlName="someControl">  <div jpFormTouchOnHover> <button type="submit" [disabled]="someForm.invalid">Save</button> </div> </form> ``` #### Use Cases - This directive is particularly useful when you want to provide information on why the submit button is disabled. Since hovering over it will trigger any validation on the form. #### Outputs | name | description | | ------------------ | ---------------------------------------------------------------- | | jpFormTouchOnHover | Emits when controls finish looping and every element was touched | #### Inputs | name | type | default | description | | ------------- | ---------------------- | ------- | ---------------------------- | | jpFormTouched | FormGroup or FormArray | null | set of controls to loop over | ### StopPropagationDirective Listens for the emitted event on the target element and simply forwards it along and calls `event.stopPropagation()`. #### Example ```angular2html <button (jpStopPropagation)="doSomething()">Click</button> ``` #### Use Cases - When ever you need to stopPropagation on an event, you can use this directive rather then passing the event along #### Outputs | name | description | | ----------------- | ------------------------------------------------------ | | jpStopPropagation | Emits the original event after calling stopPropagation | #### Inputs | name | type | default | description | | ------------------------ | ------- | ------- | ------------------------------------------------ | | preventDefault | boolean | false | should `event.preventDefault()` also get called. | | stopPropagationEventType | string | 'click' | what event to listen for | | condition | boolean or (event) => boolean | undefined | a condition to check before calling `event.stopPropagation()` | ### DebounceChangeDirective Listens for the emitted event on the target element and simply forwards it along after `debounceTime`. #### Example ```angular2html <input type="text" (jpDebounceChange)="doSomething()" /> ``` #### Use Cases - When ever you need to emit events with a delay #### Outputs | name | description | | ---------------- | --------------------------------------- | | jpDebounceChange | emits original event after debounceTime | #### Inputs | name | type | default | description | | ----------------------- | ------- | ------- | ---------------------------------------- | | debounceTime | number | 500 | value to pass to the `debounceTime` pipe | | debounceChangeEventType | string | 'keyup' | what event to listen for | | emitOnlyOnChange | boolean | false | only emit event if the value changes | ### TrackByFieldDirective ### Example ```angular2html <div *ngFor="let item of items; jpTrackByField:'test'"></div> ``` ```ts @NgModule({ imports: [TrackByFieldModule.defaultKey()] }) export class Module {} ``` ### LoadClickDirective Listens for the emitted click event on the target element and add loading class. #### Example ```angular2html <button [jpLoadClick]="save()">Submit</button> ``` #### Use Cases - For preventing double click on the submit button. #### Inputs | name | type | default | description | | ------------------------ | --------------- | --------- | ---------------------------------------- | | jpLoadClick | Observable<any> | null | | loadClickClass | string | 'loading' | | loadClickStopPropagation | boolean | false | Should `stopPropagation` be called. | loadClickEventType | string | 'click' | | loadClickPreventDefault | boolean | false | Should `preventDefault` be called. | disableAttribute | boolean | true | Should the disabled attribute be attached to the element. ## Pipes ### EnumPipe A very simple pipe that returns an array of `{key: number, value: string}` objects from an enum. #### Example ```angular2html <select> <option *ngFor="let item of someEnum | jpEnum" [value]="item.key"> {{item.value}} </option> </select> ``` #### Use Cases - It's most commonly used to easily iterate over an enum in a select #### Input Value | value | type | description | | ----- | ---- | ------------------------------------------------------------------------------------------------ | | value | enum | Supports any enum value. Provide it in typescript `someEnum = SomeEnum` to iterate over in html. | #### Parameters No parameters for `EnumPipe` ### SanitizePipe Simplifies using of `DomSanitizer`. The pipe accepts any value and then tries to sanitize it to the desired format. #### Example ```angular2html <div [innerHtml]="unsanitizedHtml | jpSanitize:'html'"></div> ``` #### Use Cases - Rendering raw html, styles... #### Input Value | value | type | description | | ----- | ------ | ----------------------------------------------------------------- | | value | string | Accepts any unsanitized string and runs it through `DomSanitizer` | #### Parameters | param | type | default | description | | ----- | --------------------------------------------- | ------- | -------------------------------------------------------------------------- | | type | html or style or script or url or resourceUrl | html | Type of entry value. This determines what `DomSanitizer` method get's used | ### TimePassedPipe This pipe takes a date as input and returns the elapsed time since that date as a number in the desired format. #### Example ```angular2html <div> {{someDate | jpTimePassed:null:timePassedType.Minute}} minutes ago </div> ``` #### Use Cases - Displaying elapsed time #### Input Value | value | type | description | | ----- | ---- | ----------- | | value | Date | any date | #### Parameters | param | type | default | description | | ------- | -------------- | --------------------- | ------------------------------------------------------------------------- | | dateTwo | Date | current date | This is the ending date in the interval. It defaults to the current date. | | type | TimePassedType | TimePassedType.Minute | In what time format should the elapsed time be returned in. | ### EnumKeyFormatPipe #### Example ```angular2html <div *ngFor="let item of someObject | jpArrayFromObject"> <span>KEY: {{item.key}}</span> <span>VALUE: {{item.value}}</span> </div> ``` #### Use Cases - This pipe is useful when ever you need to iterate an object in your template #### Input Value | value | type | description | | ----- | ------ | ----------- | | value | object | any object | #### Parameters No parameters for `ArrayFromObjectPipe` ## Decorators ### OnChange A decorator for change detection on properties #### Example ```typescript export class AppComponent { @OnChange<string>((value, simpleChange) => { console.log(`Title is changed to: ${value}`); }) @Input() title: string; } ``` ### JpFunction Decorator for methods used by LoadClickDirective. <br> Wraps them in function and expects return of type Observable. #### Parameters | value | type | description | | ----- | ------ | ----------- | | take | number | When JpFunction is called programmatically by default append take(1) to Observable. Pass 0 to skip take operator. | #### Example ```typescript @JpFunction() waitFor(milliseconds: number = 1000) { return of(true).pipe( delay(milliseconds) ); } ``` ```typescript @JpFunction({take: 2}) count() { return interval(10).pipe( tap((index) => { console.log(index); }) ); } ngOnInit() { // Triggers console.log for 0 and 1 this.count(); } ``` ## License MIT © [Jaspero Ltd](mailto:info@jaspero.co)