Form Engine Introduction

Learn how the Form Engine works - from architecture to validation, payload generation, and the complete form lifecycle.

Form Architecture

The Form Engine follows a schema-first, name-mapped architecture that ensures consistency between validation rules and UI components. This approach provides type safety, automatic binding, and seamless integration between form definition and user interaction.

Core Architecture Principles

  • Schema-First Design: Validation schema serves as the single source of truth
  • Name-Based Binding: Automatic connection between validation rules and UI components
  • Reactive Form Management: Real-time validation and state management
  • Type Safety: Built-in TypeScript interfaces for validation rules
flowchart TB subgraph Form_Component["Form Component"] subgraph validatorSchema["Validator Schema
Source of Truth"] E["email: string"] P["phoneNumber: string"] end subgraph UI_Components["UI Components
Rendered by Component Engine"] C1["type: text
name: email"] C2["type: text
name: phoneNumber"] Cx["type: text
name: unknown"] B["type: button
btnType: submit"] end end %% Name-based bindings E -. "binds by name" .-> C1 P -. "binds by name" .-> C2 Cx -. "no matching field
in schema" .-> validatorSchema %% Reactive Form build & payload C1 --> RF[("Reactive Form")] C2 --> RF RF --> SER{{"Serialize Form"}} SER --> BODY["Request Body:
email, phoneNumber"] %% Submission flow BODY --> OS["onSubmit:
method, action,
target, group"] OS --> API[("HTTP POST /users")] API --> RESP["Response →
Component Engine
renders result"]

Architecture Components Overview

Component Purpose Key Features
Validator Schema Defines data structure and validation rules Type definitions, validation constraints, required fields, custom patterns
UI Components Renders interactive form elements Input fields, labels, buttons, containers, responsive design
Reactive Form Manages form state and validation Real-time validation, error handling, form submission
Component Engine Processes and renders form components Dynamic rendering, component lifecycle, event handling
Submission Handler Processes form data and sends to API HTTP methods, endpoint configuration, response handling

Key Benefits of This Architecture

  • Consistency: Validation rules and UI are always synchronized
  • Maintainability: Single source of truth for form behavior
  • Scalability: Easy to add new fields and validation rules
  • Type Safety: Built-in TypeScript support prevents runtime errors
  • Developer Experience: Clear separation of concerns and intuitive API

Validation Schema Example

The validation schema defines the structure, types, and validation rules for form fields. This example shows how email and phone number fields are defined with specific validation patterns, and how they map to UI components through name-based binding.

flowchart LR subgraph validatorSchema E["email:string, email()"] P["phoneNumber:string, pattern=^\d{10}$, min=10, max=10"] end subgraph UI Components C1["type:text, name:email"] C2["type:text, name:phoneNumber"] Cx["type:text, name:unknown"] end E -- binds by name --> C1 P -- binds by name --> C2 Cx -. no field in schema .-> validatorSchema C1 & C2 --> RF[(Reactive Form)] RF --> BODY["Serialize"] --> OUT["{ email, phoneNumber }"]

Validation Schema Structure

Field Type Validation Rules Description
email string email() function Validates email format using built-in email validator
phoneNumber string pattern=^\d{10}$, min=10, max=10 Must be exactly 10 digits using regex pattern

Validation Schema Best Practices

  • Field Naming: Use descriptive names that match your API payload structure
  • Type Consistency: Ensure validation types match expected data types
  • Required Fields: Mark essential fields as required to prevent incomplete submissions
  • Pattern Validation: Use regex patterns for format-specific validation (phone, postal codes, etc.)
  • Length Constraints: Set appropriate min/max lengths for data quality

Validation Schema Diagram

flowchart LR subgraph validatorSchema E["email:string, email()"] P["phoneNumber:string, pattern=^\d{10}$, min=10, max=10"] end subgraph UI Components C1["type:text, name:email"] C2["type:text, name:phoneNumber"] Cx["type:text, name:unknown"] end E -- binds by name --> C1 P -- binds by name --> C2 Cx -. no field in schema .-> validatorSchema C1 & C2 --> RF[(Reactive Form)] RF --> BODY["Serialize"] --> OUT["{ email, phoneNumber }"]

Component (UI)

The Component (UI) system demonstrates how form components are organized in a hierarchical structure using groups and containers. This approach provides flexible layout management and component organization for complex form designs.

flowchart TD %% Master component contains everything subgraph MasterComponent M[type: form] end %% Group (container) subgraph GP["type: group (components)"] direction TB %% Group contains two nested groups subgraph G1["type: group"] direction TB L1[type: label] T1[name: email, type: text] end subgraph G2["type: group"] direction TB L2[type: label] T2[name: phone, type: text] end end %% wiring M --> GP GP --> G1 GP --> G2 G1 --> L1 G1 --> T1 G2 --> L2 G2 --> T2

Component Hierarchy Structure

Level Component Type Purpose Properties
Level 1 form Master container for the entire form Contains validatorSchema and components array
Level 2 group Organizes related components Can contain other groups or individual components
Level 3 label + input Form field with descriptive label name property must match validation schema

Component Organization Benefits

  • Logical Grouping: Related fields are visually and functionally grouped together
  • Responsive Layout: Groups can be styled to adapt to different screen sizes
  • Maintainability: Clear structure makes forms easier to modify and extend
  • Accessibility: Proper grouping improves screen reader navigation
  • Validation Context: Groups can have their own validation rules and error handling

Core Components

The Form Engine consists of four main areas, each with specialized functionality:

Introduction

Learn the fundamentals of the Form Engine, including core concepts and getting started guides.

  • Overview and architecture
  • Getting started tutorial
  • Core concepts and terminology
Explore Validation Schema

Validation Schema (Payload)

Define comprehensive validation rules and data schemas for your forms.

  • Schema definition basics
  • Field types and validation rules
  • Custom and async validators
Learn Validation

Components (UI)

Build beautiful, interactive form interfaces with our component library.

  • Input and selection fields
  • Custom component development
  • Styling and theming system
Browse Components

Submission (Action)

Handle form submissions with powerful processing and integration capabilities.

  • Form submission handlers
  • Data processing workflows
  • External system integrations
Handle Submissions

Getting Started Workflow

  • Step 1: Define your validation schema based on your API requirements
  • Step 2: Create form components that match your validation schema field names
  • Step 3: Configure form submission settings (method, action, target)
  • Step 4: Test form validation and submission flow
  • Step 5: Customize styling and add advanced features as needed