Using FormEngine Directly

FormEngine API

import { FormEngine } from '@atlas-forms/form-engine-js';
import { parseSchema } from '@atlas-forms/schema-js';

const schema       = parseSchema(rawJson);
const initialValues = { country: 'UK', vatRegistered: false };
const engine       = new FormEngine(schema, initialValues);

// Reading values
const firstName  = engine.getValue('first-name');
const allValues  = engine.getValues();  // { 'first-name': '', 'last-name': '', ... }

// Writing values
engine.setValue('first-name', 'Jane');
engine.setValues({ 'first-name': 'Jane', 'last-name': 'Smith' });

// Validation
const errors = await engine.validate();
// Returns: { 'email': 'Must be a valid email address', ... }

const fieldError = await engine.validateField('email');
// Returns: 'Must be a valid email address' or null

// Events
engine.on('change', (fieldId: string, value: any) => {
  console.log(`${fieldId} changed to`, value);
});

// Schema access
const schema       = engine.getSchema();
const control      = engine.getControl('email');    // FormControl | undefined
const section      = engine.getSection('personal'); // FormSection | undefined
const computedVal  = engine.getComputedValue('total'); // Evaluates computed expression

// Reset
engine.reset();       // Reset to initialValues
engine.reset(newValues); // Reset to a different set of values

Using engine from useAtlasForm

// Inside a component within FormStateProvider
import { useAtlasForm } from '@atlas-forms/player-components-react';

const MyComponent: React.FC = () => {
  const { engine } = useAtlasForm();

  // Programmatically validate and get all errors
  const handlePreValidate = async () => {
    const errors = await engine.validate();
    if (Object.keys(errors).length === 0) {
      console.log('All fields valid!');
    }
  };

  // Access a computed field value directly
  const totalAmount = engine.getComputedValue('invoice-total');

  // Export form data as structured JSON for external processing
  const exportData = () => {
    return {
      schema: engine.getSchema().metadata,
      values: engine.getValues()
    };
  };
};

Headless Usage (No React)

// Server-side form processing — validate submitted data against schema
import { FormEngine } from '@atlas-forms/form-engine-js';
import { parseSchema } from '@atlas-forms/schema-js';
import { registerAllValidators } from './validators';

registerAllValidators();

async function validateFormSubmission(
  schemaJson: object,
  submittedValues: Record<string, any>
): Promise<Record<string, string>> {
  const schema = parseSchema(schemaJson);
  const engine = new FormEngine(schema, submittedValues);
  return await engine.validate();
}

// Usage in an API endpoint
const errors = await validateFormSubmission(schema, req.body);
if (Object.keys(errors).length > 0) {
  return res.status(422).json({ errors });
}