jaspr_forms

Manejo y validación de formularios para Jaspr. Validadores declarativos, seguimiento del estado de cada campo y envío de formularios con soporte para los 3 modos de renderizado de Jaspr (static, server y client).

Características

✅ Validación declarativa: define los validadores por campo directamente en el árbol de componentes.
✅ Seguimiento del estado por campo: accede al valor, error, estado "tocado" (touched) y estado "modificado" (dirty) de cada campo.
✅ Envío asíncrono: maneja estados de carga, éxito y error al enviar el formulario.
✅ Validación en tiempo real: revalida el formulario al cambiar los validadores o los valores iniciales.
✅ Validación cruzada y personalizada: crea validadores propios con la clase Custom.
✅ Compatibilidad con los 3 modos de renderizado: funciona en renderizado estático, del lado del servidor y del lado del cliente.
✅ API familiar: la extensión context.form expone un controlador con métodos como submit(), reset() y validate().

Instalación

Agrega la dependencia a tu pubspec.yaml:

dependencies:
  jaspr_forms: ^0.1.0

Y luego importa el paquete:

import 'package:jaspr_forms/jaspr_forms.dart';

Uso básico

Envuelve tu formulario con FormBuilder y define los validadores por campo. Los campos pueden actualizar su valor con context.form.updateField(...) y el formulario se revalida automáticamente.

@client
class RegistrationForm extends StatefulComponent {
  const RegistrationForm();

  @override
  State<RegistrationForm> createState() => _RegistrationFormState();
}

class _RegistrationFormState extends State<RegistrationForm> {
  String? _submitted;

  @override
  Component build(BuildContext context) {
    return FormBuilder(
      validators: {
        'username': [
          Required(message: 'El nombre de usuario es obligatorio').call,
          MinLength(3, message: 'Debe tener al menos {min} caracteres').call,
        ],
        'email': [
          Required(message: 'El correo electrónico es obligatorio').call,
          Email(message: 'Ingresa un correo electrónico válido').call,
        ],
        'password': [
          Required(message: 'La contraseña es obligatoria').call,
          MinLength(8, message: 'Debe tener al menos {min} caracteres').call,
        ],
      },
      onSubmit: (values) async {
        // Enviar los datos a tu servidor o API.
        _submitted = values.toString();
        setState(() {});
      },
      children: [
        _FormField(name: 'username', label: 'Nombre de usuario'),
        _FormField(name: 'email', label: 'Correo electrónico'),
        _FormField(name: 'password', label: 'Contraseña', type: 'password'),
        button(
          classes: 'primary',
          disabled: context.form.isSubmitting,
          onClick: () => context.form.submit(),
          [.text(context.form.isSubmitting ? 'Enviando...' : 'Registrarse')],
        ),
        if (_submitted != null) pre([.text(_submitted!)]),
      ],
    );
  }
}

class _FormField extends StatelessComponent {
  final String name;
  final String label;
  final String? type;

  const _FormField({required this.name, required this.label, this.type});

  @override
  Component build(BuildContext context) {
    final field = context.form.field(name);
    final error = field?.error;

    return div(classes: 'form-group', [
      label([.text(label)]),
      input(
        type: type ?? InputType.text,
        onInput: (v) => context.form.updateField(name, v.toString()),
      ),
      if (error != null) div(classes: 'error-text', [.text(error)]),
    ]);
  }
}

Validadores incluidos

Validador	Descripción
`Required`	El campo no puede estar vacío.
`Email`	Valida el formato de un correo electrónico.
`MinLength`	Longitud mínima de caracteres.
`MaxLength`	Longitud máxima de caracteres.
`Pattern`	Valida contra una expresión regular (`RegExp`).
`Custom`	Permite definir tu propia función de validación.

Todos los mensajes de error aceptan el parámetro message y, en el caso de MinLength y MaxLength, puedes usar el marcador de posición {min} y {max}.

MinLength(8, message: 'Debe tener al menos {min} caracteres')

Acceso al estado del formulario

La extensión context.form devuelve un FormController con los siguientes miembros:

Miembro	Descripción
`field(String name)`	Devuelve el `FieldState` de un campo (valor, error, touched, dirty).
`values`	Mapa con los valores actuales de todos los campos.
`isValid`	`true` si todos los campos son válidos.
`isSubmitting`	`true` mientras el formulario está enviándose.
`updateField(name, value)`	Actualiza el valor de un campo y lo valida.
`setFieldError(name, err)`	Establece un error de validación manualmente.
`validate()`	Valida todos los campos y devuelve `true` si son válidos.
`submit()`	Valida y ejecuta `onSubmit`.
`reset()`	Restablece todos los campos a sus valores iniciales.
`registerField(name)`	Registra un campo que no tiene validadores.
`unregisterField(name)`	Elimina un campo del formulario.

Ejemplos

Puedes encontrar un ejemplo completo y ejecutable en el directorio example/ del paquete.

Documentación

Donaciones

Si este proyecto te resulta útil, considera hacer una donación:

Ko-fi	Litecoin

☕ Ko-fi	Ł Donaciones Litecoin

Licencia

Este proyecto está licenciado bajo la Licencia GPL-3.0+ — consulta el archivo LICENSE para más detalles.