API Reference

Complete API documentation for @schema-engine/forms-react.

createReactFormComposer

Factory function to create a React-specific form composer:

function createReactFormComposer(): FormComposer;

FormEngineProvider

Provider component that supplies the engine and adapter to the component tree:

<FormEngineProvider engine={formEngine} adapter={rhfAdapter}>
	{children}
</FormEngineProvider>

Prop	Type	Default	Description
`engine`	`FormEngine`	required	The built form engine
`adapter`	`FormAdapter`	`rhfAdapter`	Form library adapter
`children`	`ReactNode`	required	Child components

FormRenderer

Main component for rendering forms:

<FormRenderer
	config={formConfig}
	onSubmit={handleSubmit}
	defaultValues={defaultValues}
/>

Prop	Type	Description
`config`	`FormConfig`	Form configuration object
`onSubmit`	`(data) => void`	Submit handler
`defaultValues`	`object`	Initial form values

Hooks

useFormEngine

function useFormEngine(): {
	engine: FormEngine;
	executeAction?: (action: FormActionConfig) => Promise<{ success: boolean; error?: string }>;
};

useFormInstance

function useFormInstance(): UseFormReturn;

Returns the React Hook Form instance with all its methods (getValues, setValue, trigger, formState, etc.).

useFormInstanceActions

function useFormInstanceActions(): {
	currentStep: number;
	totalSteps: number;
	goToStep: (step: number) => void;
	goToNext: () => void;
	goToPrevious: () => void;
	stepStates?: {
		completed: boolean[];
		valid: boolean[];
		visited: boolean[];
	};
	navigation: {
		canGoNext: boolean;
		canGoPrevious: boolean;
		isFirstStep: boolean;
		isLastStep: boolean;
		goToStep: (step: number) => void;
		goToNextStep: () => void;
		goToPreviousStep: () => void;
	};
	dispatchTrigger: (trigger: FormActionTrigger, extraMetadata?: Record<string, unknown>) => Promise<ActionExecutionResult[]>;
	dispatchTriggerSync: (trigger: FormActionTrigger, extraMetadata?: Record<string, unknown>) => void;
};

useControlledFormElement

function useControlledFormElement(config: ElementConfig): {
	field: ControllerRenderProps;
	fieldState: ControllerFieldState;
	formState: UseFormStateReturn;
	value: any;
	error: string | undefined;
	isDirty: boolean;
	isTouched: boolean;
	isRequired: boolean;
	onChange: (value: any) => void;
	onBlur: () => void;
	fieldProps: object;
	labelProps: object;
	errorProps: object | null;
	containerStyles: object;
	gridStyles: object;
	config: ElementConfig;
	combineHandlers: <T>(controller: (v: T) => void, props?: (v: T) => void) => (v: T) => void;
};

useActionDispatcher

function useActionDispatcher(engine: FormEngine): ActionDispatcher;

useConstraintLogic

function useConstraintLogic(
	constraints?: ConstraintLogic[],
	baseRequired?: boolean,
	fieldPath?: string
): {
	isVisible: boolean;
	isDisabled: boolean;
	isRequired: boolean;
};

useGDPRConsent

function useGDPRConsent(): {
	hasConsent: () => boolean;
	grantConsent: () => void;
	revokeConsent: () => void;
	needsUpdate: () => boolean;
	getConsent: () => ConsentData | null;
};

useGTMTracker

function useGTMTracker(): {
	isAvailable: () => boolean;
	push: (event: string, data?: Record<string, any>) => void;
	pushFormEvent: (eventType: string, formData?: Record<string, any>, metadata?: Record<string, any>) => void;
	initialize: (containerId: string) => void;
};

Types

FormConfig

interface FormConfig {
	id: string;
	title?: string;
	description?: string;
	steps: StepConfig[];
	stepper?: StepperConfig;
	actions?: ActionConfig[];
}

StepConfig

interface StepConfig {
	id: string;
	title?: string;
	description?: string;
	elements: ElementConfig[];
	layout?: LayoutConfig;
	grid?: GridLayoutConfig;
}

ElementConfig

interface ElementConfig {
	$type: string;
	id?: string;
	name: string;
	label?: string;
	rules?: ValidationRule[];  // Note: "rules" not "validation"
	constraints?: ConstraintLogic[];
	grid?: ElementGridConfig;
	// ... type-specific properties
}

LayoutConfig

interface LayoutConfig {
	$type: string;  // Note: "$type" not "id"
	// ... layout-specific properties (maxWidth, padding, etc.)
}

StepperConfig

interface StepperConfig {
	$type: string;  // Note: "$type" not "id"
	// ... stepper-specific properties
}