ngx-input-eip/README.md

Lightweight edit in place text editor.

# Input edit in place
## # Summary
> Lightweight edit in place text editor.

<!-- TODO DEMO HERE -->
<!-- TODO gif showing the item -->

## Example
Example project [here](https://gitlab.opinioni.net/angular-components/ngx-input-eip-example.git)
```
git clone https://gitlab.opinioni.net/angular-components/ngx-input-eip-example.git
```

## Getting started
1. Install the library using [npm](http://npmjs.com)
```
npm i --save ngx-input-eip
```

2. Import the module to `yourmodule.module.ts`
```ts
import { NgxInputEipModule } from 'ngx-input-eip';
```

3. Add the module to the imports
```ts
@NgModule({
  declarations: [
    MyComponentPage
  ],
  imports: [
    CommonModule,
    NgxInputEipModule // Adding the module import here
  ]
})
export class MyComponentModule { }
```

4. Start using the library
```html
<!-- Mandatory short field -->
<ngx-input-eip [isMandatory]="true" [(ngModel)]="user.fullname" ></ngx-input-eip>

<!-- Non-mandatory long field. -->
<ngx-input-eip [isShort]="false" [(ngModel)]="user.funnyStory" ></ngx-input-eip>
```

## Api
### Inputs
| Input | Type | Default | Description |
| ----- | ---- | ------- | ----------- |
| [isShort] | `boolean` | `true` | If the input should appear as input or textarea. |
| [isMandatory] | `boolean` | `false` | If the input is required. |
| [enableValidations] | `boolean` | `true` | If the input should be validated. |
| [placeholder] | `string` | `"Type here..."` | The text to display when the input is empty. |
| [label] | `string` | `""` | The label of the input. You can use html templates by using `label` attribute. |
| [showLabel] | `boolean` | `true` | If the label should be shown. |
| [autosave] | `boolean \| null` | `null` | If the input should ask confirmation before emitting the changes. |
| [classes] | `string` | `""` | Classes to add to the input. |
| [customValidators] | `ValidatorFn[]` | `[]` | Adding validators to the input. |
| [isDisabled] | `boolean` | `false` | If the input should be disabled. |
| [numbersOnly] | `boolean` | `false` | If the input should be numbers only. |
| [min] | `undefined \| number` | `undefined` | Minimum vaule for numerical input. |
| [max] | `undefined \| number` | `undefined` | Maximum value for numerical input. |
| [maxLength] | `undefined \| number` | `undefined` | Maximum string length for non-numerical inputs. |
| [minLength] | `undefined \| number` | `undefined` | Minimum string length for non-numerical inputs. |
| [submitButtonLabel] | `string` | `"Confirm"` | The label for the submit button. You can pass html using `submitButton` attribute. |
| [cancelButtonLabel] | `string` | `"Cancel"` | The label for the cancel button. You can pass html using `cancelButton` attribute. |
| [actionbarMode] | `"always"\|"show"\|"overlay"` | `isShort ? 'overlay' : 'show'` | How the actionbar should be displayed. Default value is `"overlay"` if `[isShort]="true"`, otherwise it's `"show"`. Mode `"always"` means that the actionbar takes always the necessary space, but it has `visibility: hidden` if hasn't any changes. Mode `"show"` means that the actionbar does not take space if no changes, but when there are any changes, the actionbar takes the necessary space. Mode `"overlay"` means that the actionbar has `position: absolute`. |
| [animateActionbar] | `boolean` | `true` | If `[actionBarMode]="'show'"`, should the actionbar be shown with a transition or not. |
| [allowInvalid] | `boolean` | `false` | If the input should be able to emit invalid values. The input is invalid if it has at least one error. Custom error messages are counded too. (`[customErrorMessages]=['Some error message']`) |
| [errorsParser] | `(c: AbstractControl) => (string\|TemplateRef<any>)[]` | `DefaultErrorsParser` | Function that formats errors. Default value is a function that returns the most common errors in english. |
| [showErrors] | `boolean` | `true` | If the error should be shown or not. You can validate the input and set is a invalid, but choose to avoid showing the errors. |
| [customErrorMessages] | `(string\|TemplateRef<any>)[]` | `[]` | Add custom errors messages. This messages will counded as errors of the input itself, and they will prevent the input from emitting changes if `[allowInvalid]="false"` |
| [customErrorsMap] | `{ [key: string]: ((e?: any) => string\|TemplateRef<any>)\|string\|TemplateRef<any> }` | `{}` | Custom errors mapping. Overwrite default messages and show your custom errors. |
| [inputStyle] | `[ngStyle]` | `{}` | Custom `ngStyle` for the input. |


### Outpus
Most of the common events from the html element will be trasmitted.
| Output | Type | Description |
| ------ | ---- | ----------- |
| (onSubmit) | `{value: string, valid: boolean, errors: any}` | This event will be emitted when the input is submitted. WARNING: This event will not be emitted if `[autosave]="true"` |
| (onCancel) | `void` | Emitted when the changes are cancelled (click on "deny/cancel" button). WARNING: this event will not be emitted if `[autosave]="true"` |
| (areUnsavedChanges) | `boolean` | Is there any changes that hasnt been emitted to parent? Useful to block user from leaving the page if there are any unsaved changes. |
| (onChange) | `any` | Event emitted by the input. |
| (onInput) | `any` | Event emitted by the input. |
| (onClick) | `any` | Event emitted by the input. |
| (onFocus) | `any` | Event emitted by the input. |
| (onKeyDown) | `any` | Event emitted by the input. |
| (onResize) | `any` | Event emitted by the input. |
| (onDblclick) | `any` | Event emitted by the input. |
| (onBlur) | `any` | Event emitted by the input. |
| (onKeyPress) | `any` | Event emitted by the input. |
| (onKeyUp) | `any` | Event emitted by the input. |

### Html params
Params that you can use to edit the dom.
```html
<ngx-input-eip>
  <span label >Label for the input</span>

  <button submitButton i18n >Conferma</button>
  <button cancelButton i18n >Annulla</button>
</ngx-input-eip>
```

### Public properties
Public properties that can be useful; You can call any of this on the component.
| Method | Description |
| ------ | ----------- |
| `get debugJson(): any` | This getter will return a hash of information. Cool if you want to see exactly what is going on inside the component. |
| `submit(): void` | Function called when the submit button is clicked. |
| `cancel(): void` | Function called when the cancel button is clicked. |
| `input?: ElementRef;` | The actual input where user can write. WARNING: this is a `<textarea>`, not an `<input>`. |
| `get allErrorsMessages(): (string \| TemplateRef<any>)[]` | Get all the error messages. |

## Examples
All the examples below skip the initial setup
1. Simple short input
```html
<ngx-input-eip [(ngModel)]="myValue" ></ngx-input-eip>
```

2. Textarea edit-in-place
```html
<!-- [short]="false" -->
<ngx-input-eip [short]="false" [(ngModel)]="myValue"></ngx-input-eip>
```

3. Numerical input
```html
<ngx-input-eip formControlName="myValue" [numerical]="true" [min]="0" [max]="100" ></ngx-input-eip>

```
4. With custom html label and/or buttons
```html
<ngx-input-eip formControlName="myValue">
  <app-my-label [for]="'myValue'" label ></app-my-label>

  <button submitButton i18n >Conferma</button>
  <button cancelButton i18n >Annulla</button>
</ngx-input-eip>
```

5. Calling public properties
```html
<ngx-input-eip #input formControlName="myValue"></ngx-input-eip>

<hr>

<pre [innerText]="input.debugJson | json" ></pre>
```
<!-- TODO browsers support -->
## Next features
- On numerical input, +1 if arrow up and -1 if arrow down.
- On numerical input, do not allow text input. (delete everything except the numbers)
- On numerical input, add input `[step]` to define how much should the value be shifted with the arrows (down/up).
- On numerical input, allow negative and decimal numbers.
- Labels: TemplateRef can be passed too, not only strings.