jaspr_forms 0.1.1

Form validation and management for Jaspr. Declarative validators, field state tracking, and form submission with support for all 3 rendering modes (static/server/client).

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

• API del paquete
• Documentación de Jaspr
• Repositorio

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.