@bluprynt/forms-core

Framework-agnostic engine for JSON-driven dynamic forms. Given a form schema (JSON), the engine handles field visibility via conditional logic, validates user input against type-specific rules, and produces structured form documents (JSON).

Key Capabilities

• Schema compilation — validates and compiles a JSON form definition into a runtime engine with dependency analysis and cycle detection.
• Conditional visibility — shows/hides fields and sections dynamically based on other field values, with cascading parent-child visibility and topological evaluation order.
• Type-aware validation — validates form values against per-field rules (required, min/max, pattern, date ranges, array constraints, etc.), skipping hidden fields automatically.
• Document compatibility validation — verifies that a form document's form.id and form.version match the engine's definition before field validation.
• Form definition editing — fluent builder API (FormDefinitionEditor) for programmatically constructing and modifying form schemas.
• Form values editing — fluent editor API (FormValuesEditor) for programmatically reading and writing form values against a definition, with array manipulation, validation, and visibility queries.
• Relative dates — date boundaries like "+7d" or "-1m" are resolved at evaluation time against the form's required submittedAt timestamp, enabling dynamic yet reproducible date constraints.

Quick Start

import { FormEngine } from '@bluprynt/forms-core'

// 1. Compile the form definition
const engine = new FormEngine(formDefinition)

// 2. Create a form document (with optional initial values)
const doc = engine.createFormDocument({ "1": "Alice", "2": 30 })

// 3. Compute visibility
const visibility = engine.getVisibilityMap(doc)

// 4. Validate (checks document compatibility + field rules)
const result = engine.validate(doc)
if (!result.valid) {
  result.documentErrors?.forEach(e => console.log(`Document: ${e.message}`))
  for (const [fieldId, errs] of result.fieldErrors) {
    for (const err of errs) {
      console.log(`Field ${fieldId}: ${err.message}`)
    }
  }
}

Building a Form Definition

import { FormDefinitionEditor } from '@bluprynt/forms-core'

const editor = new FormDefinitionEditor({
  id: 'my-form', version: '1.0.0', title: 'My Form', content: [],
})

editor
  .addField({ type: 'string', label: 'Name', validation: { required: true } })
  .addSection({ type: 'section', title: 'Details' })
  .addField({ type: 'number', label: 'Age' }, 2) // into section id=2

const definition = editor.toJSON()

Editing Form Values

import { FormValuesEditor } from '@bluprynt/forms-core'

// 1. Create an editor (optionally pre-populate from an existing document)
const editor = new FormValuesEditor(formDefinition)

// 2. Set field values (fluent chaining)
editor
  .setFieldValue(1, 'Alice')
  .setFieldValue(2, 30)
  .addArrayItem(6, 'TypeScript')
  .addArrayItem(6, 'React')
  .setSubmittedAt('2025-01-01T00:00:00Z')

// 3. Optionally record and resolve machine-proposed answers
editor
  .setSuggestion(1, { value: 'Alice Smith', confidence: 0.8, source: 'Passport MRZ, line 2' })
  .acceptSuggestion(1)   // copies the value across, keeps the suggestion
  .rejectSuggestion(2)   // removes a suggestion, leaves the value untouched

// 4. Validate and extract the document
const result = editor.validate()
const doc = editor.toJSON()

Suggestions live in the document's optional suggestions block and never affect validation or visibility. confidence is a 0..1 fraction. Both the block and the three metadata properties (placeholder, answer_guidelines, reference_id) on fields and sections are optional, so existing definitions and documents keep working unchanged.

Documentation

For the complete list of exported classes, types, and utilities, see API Reference.

Supported Field Types