@uplink-protocol/form-controller

A lightweight yet powerful form management system for building dynamic, multi-step forms with advanced validation capabilities. This module is part of the Odyssey Uplink Protocol.

Features

• Flexible Form Structure - Support for both single-step and multi-step forms
• Built-in Validation - Comprehensive validation rules out of the box
• Dynamic Validation - Context-aware validators that can react to other field values
• Enhanced Validation - Support for multiple validation errors and per-validation error messages
• Reactive State Management - Subscribe to state changes for reactive UI updates
• Progressive Form Building - Add or remove steps dynamically
• Framework Agnostic - Works with any UI library or vanilla JavaScript

Installation

npm install @uplink-protocol/form-controller

Basic Usage

// Import the form controller
const { FormController } = require('@uplink-protocol/form-controller');

// Define your form configuration
const formConfig = {
  steps: [
    {
      id: 'contact',
      title: 'Contact Information',
      fields: {
        name: {
          id: 'name',
          type: 'text',
          label: 'Full Name',
          required: true,
          value: ''
        },
        email: {
          id: 'email',
          type: 'email',
          label: 'Email Address',
          required: true,
          value: '',
          validation: {
            pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
          }
        }
      }
    }
  ]
};

// Initialize the form controller
const form = FormController(formConfig);

// Update field values
form.methods.updateField('contact', 'name', 'John Doe');

// Validate the form
if (form.methods.validateForm(true)) {
  // Form is valid, get the data
  const formData = form.methods.getFlatData();
  console.log('Form data:', formData);
}

Multi-step Form Example

const wizardForm = FormController({
  steps: [
    {
      id: 'personal',
      title: 'Personal Details',
      fields: {
        // Personal info fields
      }
    },
    {
      id: 'address',
      title: 'Address Information',
      fields: {
        // Address fields
      }
    },
    {
      id: 'preferences',
      title: 'User Preferences',
      fields: {
        // Preferences fields
      }
    }
  ]
});

// Navigate between steps
wizardForm.methods.nextStep();  // Advance to next step if current is valid
wizardForm.methods.prevStep();  // Go back to previous step
wizardForm.methods.goToStep(1); // Jump to specific step

// Check current status
const isLastStep = wizardForm.bindings.isLastStep.current;
const isFormValid = wizardForm.bindings.isFormValid.current;

Dynamic Validation

// Register a custom validator
form.methods.registerValidator('matchesPassword', (value, context) => {
  if (value !== context.formData.password) {
    return 'Passwords do not match';
  }
  return true;
});

// Use in a field definition
const confirmPasswordField = {
  id: 'confirmPassword',
  type: 'password',
  label: 'Confirm Password',
  validation: {
    dynamicValidator: 'matchesPassword'
  }
};

Enhanced Validation

// Field with per-validation error messages
const passwordField = {
  id: 'password',
  type: 'password',
  label: 'Password',
  validation: {
    required: true,
    minLength: 8,
    pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}$/,
    // Specific error messages for each validation rule
    errorMessages: {
      required: 'Password is required',
      minLength: 'Password must be at least 8 characters long',
      pattern: 'Password must include uppercase, lowercase, and numbers'
    },
    // Enable multiple error collection
    collectAllErrors: true
  }
};

// Field with multiple dynamic validators
const usernameField = {
  id: 'username',
  type: 'text',
  label: 'Username',
  validation: {
    required: true,
    // Multiple dynamic validators with custom parameters
    dynamicValidators: [
      {
        name: 'uniqueUsername', 
        params: { checkDatabase: true },
        errorMessage: 'This username is already taken'
      },
      {
        name: 'allowedCharacters',
        errorMessage: 'Username can only contain letters, numbers, and underscores'
      }
    ],
    collectAllErrors: true
  }
};

Reactive UI Updates

// Subscribe to form data changes
form.bindings.formData.subscribe(data => {
  console.log('Form data updated:', data);
  updateUI(data);
});

// Subscribe to validation errors
form.bindings.fieldErrors.subscribe(errors => {
  displayErrors(errors);
});

Documentation

For detailed documentation and examples, see:

• Features Guide - Comprehensive listing of all features and capabilities
• Usage Guide - Step-by-step guide to using the form controller
• Validation Guide - In-depth guide to validation capabilities
• Technical Guide - Implementation details and best practices
• TypeScript Usage - Guide to using the form controller with TypeScript
• Extensibility Guide - Guide to extending the FormControllerClass for custom behavior
• API Reference - Auto-generated API documentation with types and examples

Use Cases

• Multi-step Wizards - Build complex, multi-step registration or checkout flows
• Dynamic Forms - Create forms that adapt based on user input
• Complex Validation - Implement interdependent field validation rules
• Form State Management - Maintain form state separate from UI components

License

MIT © Odyssey Uplink Protocol Team