CharacterCounter

This project was generated using Angular CLI version 20.1.0.

Code scaffolding

Angular CLI includes powerful code scaffolding tools. To generate a new component, run:

ng generate component component-name

For a complete list of available schematics (such as components, directives, or pipes), run:

ng generate --help

Building

To build the library, run:

@cbm-common/character-counter

Documentación en español para la librería @cbm-common/character-counter.

Resumen

character-counter proporciona una directiva Angular (standalone) llamada cbmCharacterCounter que añade un contador visual de caracteres al lado de una etiqueta (label). Está diseñada para integrarse con formularios reactivos (FormControl) y muestra el número de caracteres escritos respecto a un máximo configurado, o solo el conteo si se habilita onlyCount.

Características principales

• Standalone directive compatible con Angular 20.
• Se conecta a un FormControl para observar cambios y sincronizar el contador.
• Requiere que la etiqueta tenga el atributo for apuntando al id del input asociado.
• Añade clases CSS (text-info / text-danger) según si se excede el máximo.

Requisitos

• Angular >= 20.x
• Declarar la directiva en los puntos donde se use (es standalone, puede importarse directamente).

Instalación

Desde npm (si el paquete está publicado):

npm install @cbm-common/character-counter

Si trabajas en el monorepo local, puedes importar la directiva directamente desde el paquete local o usar ng build y probar desde dist/.

Export y archivo principal

La librería exporta la directiva desde public-api.ts y index.ts:

• CbmCharacterCounterDirective (archivo: src/lib/character-counter.directive.ts).

API / Inputs

La directiva expone tres inputs:

• control: FormControl<any> (obligatorio para el conteo automático) — FormControl con el que se sincroniza el contador.
• maxChars: number (opcional, default 100) — número máximo de caracteres que se muestran en la leyenda X de Y.
• onlyCount: boolean (opcional, default false) — si true mostrará únicamente X Caracteres (sin mostrar el máximo ni icono).

Comportamiento esperado

• Al inicializar, la directiva requiere que el label donde se aplica tenga el atributo for apuntando al id del input objetivo. Si no existe, se registra un error en consola y la directiva no continúa.
• La directiva busca el input con ese id dentro del contenedor padre del label (o en sus descendientes). Si no lo encuentra, muestra un error en consola.
• Cuando hay un FormControl ligado, la directiva suscribe a valueChanges (y toma el valor inicial) para actualizar el contador.
• También se suscribe al evento input del elemento input para detectar cambios provenientes del usuario.
• Si el número de caracteres excede maxChars, la directiva añade la clase text-danger al contenedor del contador; en caso contrario aplica text-info.

Uso (ejemplos)

Ejemplo mínimo con formularios reactivos:

<!-- En el template -->
<label for="my-input" cbmCharacterCounter [control]="myControl" [maxChars]="50">Mi campo</label>
<input id="my-input" [formControl]="myControl" type="text" />

En el componente TS:

import { FormControl } from '@angular/forms';

export class MiComponente {
   myControl = new FormControl('');
}

Ejemplo con onlyCount:

<label for="ro-input" cbmCharacterCounter [control]="roControl" [onlyCount]="true">Sólo conteo</label>
<input id="ro-input" [formControl]="roControl" readonly />

Notas de estilo y dependencias visuales

La directiva crea dinámicamente elementos HTML y aplica clases:

• ti-pencil y fs-3 para el icono (si onlyCount es false).
• mx-1 para separación interna.
• text-info y text-danger para los estados (normal / excedido).

Estas clases no están definidas por la librería; dependen de tu proyecto (por ejemplo, icon font, Bootstrap o utilidades Tailwind). Ajusta tu hoja de estilos global para que ti-pencil, text-info, text-danger y demás clases existan si quieres controlar la apariencia exactamente.

Buenas prácticas y requisitos HTML

• Asegúrate de que la label y el input estén dentro del mismo contenedor padre o que el input sea accesible por document.querySelector desde ese contenedor.
• No olvides pasar el FormControl correcto. Si no se pasa control, la directiva no podrá suscribirse a valueChanges y mostrará únicamente el contador que recibe desde el evento input.

Errores comunes / Solución de problemas

• "Es obligatorio definir el artributo "for"" — Significa que tu label no tiene el atributo for que apunte al id del input; añádelo.
• "No se encontro ningún input con el id X" — Revisa que el id del input coincida exactamente y que el input esté en el DOM o dentro del mismo contenedor padre.
• El contador aparece pero sin formato — Revisa que las clases CSS mencionadas existan en tu proyecto.

Pruebas

La librería incluye un archivo de pruebas unitarias (character-counter.directive.spec.ts). Ejecuta las pruebas con el command del workspace:

ng test

Build y publicación

Para compilar la librería en este monorepo:

ng build character-counter

Los artefactos se generan en dist/character-counter. Si vas a publicar en npm:

cd dist/character-counter
npm publish

Si el paquete es privado o con scope, configura tu .npmrc con el registro y token correspondientes.

Contribuciones

Si deseas aportar mejoras, crea un issue o PR que describa el cambio. Para cambios visuales, incluye capturas o ejemplos en el README.

Contacto

Para dudas o soporte sobre la directiva, revisa el código en src/lib/character-counter.directive.ts o abre un issue en el repositorio donde se aloja este monorepo.

Documentación generada con contexto directo del código fuente de la directiva.