Public API Reference

This document is the definitive reference for everything exported from @dfbe/core. These are the only symbols you should import in a consumer application.

For builder tooling exports (VALIDATION_REGISTRY, FIELD_TYPE_CATEGORY_MAP), see the Validation Registry doc.

Entry Points

@dfbe/core — Main Engine

Components

<FormEngineProvider>

Root context provider. Initializes react-hook-form, compiles dynamic Zod schemas, and manages multi-step navigation.

import { FormEngineProvider } from "@dfbe/core";

See Basic Usage for full props reference.

<FieldRenderer>

Headless dispatcher that resolves a field definition to the matching component in the ComponentRegistry.

import { FieldRenderer } from "@dfbe/core";

See Basic Usage for full props reference.

Hooks

useFormEngine()

Access navigation state, form methods, and validated data from within any descendant of FormEngineProvider.

import { useFormEngine } from "@dfbe/core";

- **Navigation Actions**: `handleNext`, `handleBack`, `setStepGuard`.
- **Form State**: `currentStep`, `currentStepIndex`, `isFirstStep`, `isLastStep`.
- **Logic State**: `showSummary`, `validatedData`.
- **API Registry**: `customSteps` (StepComponentRegistry).

#### `setStepGuard(callback: StepGuard | null)`
Registers an async callback that executes when the user clicks "Next". If it returns `false`, navigation is blocked.

```tsx
const { setStepGuard } = useFormEngine();

useEffect(() => {
  setStepGuard(async () => {
    const ok = await validateExternalData();
    return ok;
  });
  return () => setStepGuard(null);
}, []);

useResourceFetcher(props)

Low-level hook for async data fetching with caching and cascading. Used internally by FieldRenderer. You can use it directly for custom adapters.

import { useResourceFetcher } from "@dfbe/core";

const { options, loading, error, retry } = useResourceFetcher({
  registry: resourceRegistry,
  resource: "cities",
  dependsOn: "province",
  dependsOnParam: "provinceId",
  fieldName: "city",
});

Context

ComponentRegistryContext

React Context that holds the ComponentRegistry. Wrap your app with a Provider to inject your UI components.

import { ComponentRegistryContext } from "@dfbe/core";

<ComponentRegistryContext.Provider value={myRegistry}>
  <FormEngineProvider schema={schema}>{/* ... */}</FormEngineProvider>
</ComponentRegistryContext.Provider>;

See Rendering & Registry for how to build and inject a registry.

StepRegistryContext

React Context that holds the StepComponentRegistry for custom steps.

import { StepRegistryContext } from "@dfbe/core";

<StepRegistryContext.Provider value={myStepRegistry}>
  <FormEngineProvider schema={schema}>{/* ... */}</FormEngineProvider>
</StepRegistryContext.Provider>;

Library Functions (Advanced Use)

These functions power the engine internals. They are exported for advanced consumers who need to extend or test engine logic directly.

generateZodSchema(fields, formValues, datasetLookups?)

Compiles a flat array of FormFieldDefinition objects into a live Zod schema. Called internally on every validation cycle.

import { generateZodSchema } from "@dfbe/core";

const schema = generateZodSchema(allFields, currentValues, datasetLookups);
const result = schema.safeParse(data);

evaluateFieldEffects(field, formValues)

Runs all rules for a single field and returns its computed state (visible, required, disabled, label, helperText, computedValue).

import { evaluateFieldEffects } from "@dfbe/core";

const state = evaluateFieldEffects(field, formValues);
if (!state.visible) return null;

extractFieldDependencies(field)

Returns the array of field names that a given field's rules and visibleIf depend on. Used by FieldRenderer to set up selective useWatch subscriptions.

import { extractFieldDependencies } from "@dfbe/core";

const deps = extractFieldDependencies(field);
// e.g. ["employment_status", "has_experience"]

evaluateLogic(node, formValues, depth?)

Recursively evaluates a LogicNode (single condition or group) against the current form values.

import { evaluateLogic } from "@dfbe/core";

const isTrue = evaluateLogic(rule.condition, formValues);

getNestedValue(obj, path)

Resolves a dot-notation path string into a value from an object. Safe — returns undefined if any segment is null/undefined.

import { getNestedValue } from "@dfbe/core";

const value = getNestedValue(formState, "profile.education.university.id");

interpolateString(template, formValues)

Replaces {{fieldName}} tokens in a string with live values from the form state.

import { interpolateString } from "@dfbe/core";

const label = interpolateString("Hello {{firstName}}!", { firstName: "Budi" });
// "Hello Budi!"

computeValue(template, formValues)

Interpolates a template string and optionally evaluates it as a math expression.

import { computeValue } from "@dfbe/core";

const result = computeValue("{{price}} * {{qty}}", { price: 50000, qty: 3 });
// 150000

evaluateMath(expression)

Safely evaluates a pure numeric math expression string. Returns the original string if unsafe or invalid.

import { evaluateMath } from "@dfbe/core";

evaluateMath("10 * 3 + 5"); // 35
evaluateMath("alert(1)"); // "alert(1)" — rejected by regex guard

evaluateCondition(condition, formValues)

Evaluates a single VisibleIfCondition (deprecated visibleIf schema). Wraps evaluateSingleCondition.

import { evaluateCondition } from "@dfbe/core";

const isVisible = evaluateCondition(field.visibleIf, formValues);

Types

All TypeScript types are exported for use in consumer applications:

import type {
  // Schema structure
  FormSchema,
  FormStep,
  FormSection,
  FormFieldDefinition,
  FieldType,
  ValidationRules,
  DataSource,
  OptionItem,
  DatasetConfig,
  DatasetConfigItem,
  ResourceRegistryEntry,
  FormTheme,
  FormSchedule,
  LayoutConfig,
  LayoutWrapper,
  LayoutWrapperProps,

  // Conditional logic
  LogicNode,
  ConditionNode,
  ConditionGroup,
  ConditionOperator,
  Rule,
  RuleEffect,
  VisibleIfCondition, // @deprecated

  // Engine types
  ComponentRegistry,
  FieldAdapterProps,
  StepComponentRegistry,
  CustomStepProps,
  StepGuard,
  FormSchemaJSON, // inferred type from the Zod validator
  ValidationCategory,
  ValidationRuleDefinition, // from @dfbe/core/registry

  // Type Guards
  isCustomStep,
  isSchemaStep,
} from "@dfbe/core";

@dfbe/core/validator

Provides Zod schemas for validating a FormSchema JSON object at build time or in the Studio.

import { formSchemaValidator, FormSchemaJSON } from "@dfbe/core/validator";

const result = formSchemaValidator.safeParse(rawJson);
if (!result.success) {
  console.error("Invalid schema:", result.error.flatten());
}

Also exports individual sub-schemas for partial validation: fieldTypeSchema, conditionOperatorSchema, validationRulesSchema, formFieldDefinitionSchema, formSectionSchema, formStepSchema, ruleSchema, ruleEffectSchema, logicNodeSchema, and more.

@dfbe/core/registry

Provides metadata about available validation rules, used by the Studio's Property Panel.

import { VALIDATION_REGISTRY, FIELD_TYPE_CATEGORY_MAP } from "@dfbe/core/registry";

See Validation Registry for full documentation.