npm package: @gecosuy/angular-components-form
Description: Librería de componentes asociados a formularios
Latest version: 19.0.0

# Angular Componentes | Form

Librería de componentes Angular reutilizables propios de Gecos.  
Contiene componentes de formulario, como inputs, date picker, iconos, etc.

# Instalación

`npm install @gecosuy/angular-components-form`

# Requerimientos

Se detallan los requerimientos que debe cumplir la app donde se quiera utilizar esta librería:

-   tener Angular Material incorporado
-   tener algunos retoques globales de angular material que pueden afectar a componentes de esta lib pero también a otros componentes de la app que usen material (por ejemplo ver la `app-tester` donde se realizan algunos retoques en `custom-meterial.scss` que mejoran los componentes de esta lib)
-   tener determinados iconos definidos que son necesarios en algunos componentes de esta librería

# Theming

El theming de los componentes se realiza por medio de variables CSS.  
A continuación se detallan las variables CSS generales que afectan a mas de un componente.
Luego en la siguiente sección, en cada componente, se mencionan otras variables CSS propias del componente.

-   `--gecos-form-primary`: color principal de destaque
-   `--gecos-form-front`: color para fuentes, etc.
-   `--gecos-form-background`: color de fondo
-   `--gecos-form-muted`: color para marcar cosas menos importantes

Recordar que las variables CSS pueden ser sobreescritas dentro de clases CSS con el fin de aplicar ese valor para una sección/componente específica. Mediante esto se puede por ejemplo aplicar un valor a un componente cuando se usa en una página y otro valor al mismo componente cuando se usa en otra página.

# Componentes

## Icon

Componente que despliega un icono.  
Por el momento solo compatible con desplegar iconos SVG indicando el alias, pero podría extenderse para soportar iconos de FontAwesome u otros.

### Uso

Se usa mediante

```html
<gecos-icon [alias]="'[icon_name]'"></gecos-icon>
```

```typescript
constructor(iconRegistry: MatIconRegistry, sanitizer: DomSanitizer) {
    iconRegistry.addSvgIcon('[icon_name]', sanitizer.bypassSecurityTrustResourceUrl('assets/icons/[icon_name].svg'));
}
```

Donde `icon_name` es el alias del icono que debe estar registrado de la siguiente forma en el `AppModule`:

Ver ejemplo de uso y theming en la `app-tester` de este repositorio.

### Theming

Para customizar el color simplemente setear la propiedad `color` por CSS.  
Para customizar el tamaño setear las propiedades `height` y `width` del mat-icon interno por CSS mediante `::ng-deep mat-icon`.

## Tag

Componente que despliega un tag de un determinado color. El tag ajusta automáticamente el color de fondo al mismo color pero con una opacidad.

### Uso

Se usa mediante

```html
<gecos-tag [text]="'Hola'" [mini]="true|false" [inverted]="true|false"></gecos-tag>
```

Ver ejemplo de uso y theming en la `app-tester` de este repositorio.

### Theming

Para customizar el color simplemente setear la propiedad `color` por CSS.  
Además, cuando se usa con `[inverted]="true"` entonces se puede customizar el color del texto mediante la propiedad `--gecos-tag-inverted-text`.

## Chip

Componente que despliega un chip de un determinado color. El chip es estilo tag y ajusta automáticamente el color de fondo al mismo color pero con una opacidad.

### Uso

Se usa mediante

```html
<gecos-chip [content]="'Valor 1'" [clearIcon]="'remove_chip'"></gecos-chip>
```

`clearIcon` es el alias del icono a usar para mostrar opción de remover el chip. Por defecto es 'close' y si se pasa undefined entonces no se da esa opción.

Ver ejemplo de uso y theming en la `app-tester` de este repositorio.

### Theming

El color es tomado de la variable especifica `--gecos-chip-rgb` que **debe estar definida en RGB**.

## Date Picker

Componente para un date picker de material.  
Funcionalidades:

-   simplifica el uso respecto de usarlo como dice la doc de material porque de otro forma hay que agregar varias lineas de html
-   agrega la opcion de un icono delete para limpiar la fecha

Compatible con Angular Forms, implementado con https://blog.angular-university.io/angular-custom-form-controls.

### Uso

Se usa mediante

```html
<gecos-date-picker [label]="'Fecha'" [clearIcon]="'clear'"></gecos-date-picker>
```

`clearIcon` es el alias del icono a usar para mostrar opción de limpiar la fecha. Por defecto es 'close' y si se pasa undefined entonces no se da esa opción.

Ver ejemplo de uso y theming en la `app-tester` de este repositorio.

### Theming

El color del icono de toogle es tomado de la variable especifica `--gecos-date-picker-toggle` y si esta no está definida entonces es tomado de la global de la librería `--gecos-form-primary`.  
El color del icono de clear es tomado de la variable global de la librería `--gecos-form-muted`.

## Number Input

Componente para manejar un input numérico con las siguientes características:

-   Se transforma en textual cuando no se está editando y permite formatear el número con un prefijo/postfijo de moneda o unidad
-   Opcionalmente inicia con el foco
-   Puede permitir o no negativos
-   Soporta indicarle cantidad de decimales a permitir
-   Opcionalmente muestra icono suffix
-   Se puede indicar si se quieren reportar cambios de valor cuando se pierde el foco o se da enter o si se quieren por cada digitado parcial

Compatible con Angular Forms, implementado con https://blog.angular-university.io/angular-custom-form-controls.

### Uso

Se usa mediante

```html
<gecos-number-input
    [placeholder]="'Monto'"
    [currency]="'$'"
    [ngModel]="value"
    (ngModelChange)="onNumberChange($event)"
></gecos-number-input>
```

Ver ejemplos de uso y theming en la `app-tester` de este repositorio.

### Theming

El color del icono de suffix es tomado de la variable especifica `--gecos-number-input-suffix` y si esta no está definida entonces es tomado de la global de la librería `--gecos-form-primary`.

## Autocomplete

Componente genérico para un input con autocomplete con las siguientes características:

-   Autofiltrado por el texto ingresado sobre un conjunto de elementos que NO son paginados y se deben pasar como entrada
-   Los datos deben implementar AutocompleteData que define campo sobre el que filtrar y campo a mostrar, el cliente es el encargado de cargar estos campos a todos los elementos de la lista de datos
-   Opcionalmente muestra opcion para limpiar el contenido
-   Optionalmente muestra un icono decorativo de suffix al final del input
-   Optionalmente se puede indicar perder el foco al seleccionar un valor o limpiarlo

Manejo de mensajes de error:

-   Soporta que si el control es invalid, se muestra el mensaje de error mediante <mat-error>

PROBLEMAS:

-   No funciona del todo bien cuando se usa ngModel, no informa de cambios de valor y no muestra error, por tanto **NO usar con ngModel**

Compatible con Angular Forms, implementado con https://blog.angular-university.io/angular-custom-form-controls.

### Uso

Ver ejemplo de uso y theming en la `app-tester` de este repositorio.

### Theming

El color del icono de suffix es tomado de la variable especifica `--gecos-autocomplete-suffix` y si esta no está definida entonces es tomado de la global de la librería `--gecos-form-primary`.  
El color del icono de clear es tomado de la variable global de la librería `--gecos-form-muted`.

## Global Filter

Componente para un textfield de filtro universal con:

-   aviso de cambio de valor con enter o perdida de foco
-   potencial icono para limpiar filtro

Compatible con Angular Forms, implementado con https://blog.angular-university.io/angular-custom-form-controls.

### Uso

Ver ejemplo de uso y theming en la `app-tester` de este repositorio.

### Theming

El color del icono de suffix es tomado de la variable especifica `--gecos-global-filter-suffix` y si esta no está definida entonces es tomado de la global de la librería `--gecos-form-primary`.  
El color del icono de clear es tomado de la variable global de la librería `--gecos-form-muted`.