✨ material-dynamic-forms

¡Crea formularios dinámicos, potentes y configurables en Angular usando Material Design! 🚀

---

¿Qué es esta librería? 🤔

material-dynamic-forms es una herramienta para generar formularios dinámicos en Angular, completamente personalizados desde la configuración, compatibles con Angular Material y preparados para casos de uso avanzados como formularios dependientes, campos dinámicos, validaciones, autocompletados y más.

---

Instalación 🛠️

npm install material-dynamic-forms

Agrega el módulo en tu aplicación:

import { DynamicFormModule } from 'material-dynamic-forms';

@NgModule({
  imports: [
    // ...
    DynamicFormModule,
  ],
})
export class AppModule {}

---

Uso Básico 🚦

<lib-dynamic-form
  [fieldGroups]="formularioAgrupado"
  [baseUrl]="urlApi"
  [isEdit]="modoEdicion"
  (changeValueSelected)="onChangeValue($event)">
</lib-dynamic-form>

• fieldGroups: Arreglo de grupos de campos dinámicos (ver ejemplos abajo).
• baseUrl: URL base para consumir APIs de selects dinámicos.
• isEdit: Indica si el formulario está en modo edición.
• changeValueSelected: Output para escuchar cambios de campos.

---

Cómo se define un formulario dinámico 📐

El formulario se define con un array de IFieldGroup, donde cada grupo incluye un título, cantidad de columnas y una lista de campos (IFieldDynamicForm).

Ejemplo de definición

const formularioAgrupado: IFieldGroup[] = [
  {
    title: 'Datos Personales',
    countColumns: 2,
    fields: [
      {
        label: 'Nombre',
        name: 'nombre',
        type: eDataType.input,
        placeholder: 'Ingrese su nombre',
        visible: true,
        validation: [Validators.required]
      },
      {
        label: 'Fecha de nacimiento',
        name: 'fechaNacimiento',
        type: eDataType.date,
        visible: true
      }
    ]
  }
];

---

Interfaz de campo (IFieldDynamicForm) 🧩

Propiedad	Tipo	Descripción
label	string	Texto visible en el campo
name	string	Nombre de control (formControlName)
type	eDataType	Tipo de campo (input, select, date, etc)
placeholder	string	Texto de ayuda (opcional)
options	array	Opciones para selects/autocompletes
visible	boolean	Si el campo se muestra o no
disabled	boolean	Si el campo está deshabilitado
validation	ValidatorFn[]	Validaciones Angular (requerido, patrón, etc)
apiUrl	string	URL para cargar opciones dinámicamente
dependency	string	Campo del cual depende este campo
valueDependency	objeto	Dependencia para habilitar según valor de otro campo
externalDependencies	string[]	Dependencias externas para selects dinámicos
multiple	boolean	Selección múltiple (en selects)
colspan	number	Cuántas columnas ocupa el campo
...	...	¡Hay muchas más! (ver abajo)

Tipos de campo (eDataType) 🎛️

• input: Campo de texto simple
• select: Selector desplegable
• date: Selector de fecha
• checkbox: Checkbox
• select_search: Select con buscador
• tex_area: Área de texto
• button, button_toggle: Botones
• select_chips: Select con selección múltiple tipo "chips"
• select_autocomplete / input_autocomplete: Autocompletes
• ... y más

Dependencias y dinámicas avanzadas 🔗

Puedes:

• Habilitar/inhabilitar campos según valores de otros (valueDependency, valueExcludeDependency)
• Consumir APIs para cargar opciones de selects según dependencias o filtros
• Usar funciones para validar rangos de fechas, filtrar fechas válidas, etc.

---

Interfaz de grupo (IFieldGroup) 🏷️

Propiedad	Tipo	Descripción
title	string	Título del grupo
countColumns	number	Número de columnas en el grid
fields	IFieldDynamicForm[]	Lista de campos
isRangeValidator	boolean	Si aplica validación de rango (opcional)

---

Ejemplo completo 🌟

import { eDataType, IFieldGroup } from 'material-dynamic-forms';

const grupos: IFieldGroup[] = [
  {
    title: 'Información Básica',
    countColumns: 2,
    fields: [
      {
        label: 'Correo Electrónico',
        name: 'email',
        type: eDataType.input,
        placeholder: 'ejemplo@correo.com',
        visible: true,
        validation: [Validators.required, Validators.email]
      },
      {
        label: 'País',
        name: 'pais',
        type: eDataType.select,
        visible: true,
        apiUrl: '/api/paises',
        options: [],
        valueTOShow: 'nombre'
      }
    ]
  }
];

---

Métodos y outputs principales 🧑‍💻

• (changeValueSelected): Output para reaccionar a cambios en los campos.
• getForm(): Método para obtener el FormGroup subyacente.
• externalDependenciesValuesChanged: Output para detectar cambios en dependencias externas.

---

Personalización y buenas prácticas 👩‍🎨

• Puedes crear validadores personalizados y pasarlos a los campos.
• Usa dependencias entre campos para formularios complejos.
• Aprovecha la integración con Angular Material para una UI consistente.

---

API pública (servicio) 🔍

El servicio DynamicFormService permite:

• Inicializar formularios (functionInitComponent)
• Gestionar dependencias internas y externas
• Extraer valores mapeados del formulario (functionGetFormValue)
• Construir URLs dinámicas para selects dependientes

---

Publicar en NPM 🚀

Si eres el mantenedor, puedes publicar la librería así:

ng build dynamic-form
cd dist/dynamic-form
npm publish --access public

Asegúrate de tener configurado tu usuario en npm y permisos para publicar.

---

Contribuir 🤝

¿Ideas, bugs o mejoras? ¡Tu feedback es bienvenido! Haz un PR o abre un issue en el repo.

---

Licencia 📄

Este proyecto está licenciado bajo la licencia MIT. Véase el archivo LICENSE para más detalles.

---

Créditos y agradecimientos 🙌

Desarrollado con ❤️ por softcomsas.

---

Para ver más ejemplos y documentación, consulta los archivos en la carpeta /projects/dynamic-form del repo.