Core API

import { createEngine } from "@squaredr/fieldcraft-core";

const engine = createEngine(schema, options?);

// Get current state snapshot
engine.getState(): FormState

// Subscribe to state changes (returns unsubscribe function)
engine.subscribe(listener: (state: FormState) => void): () => void

// Set a single field value
engine.setValue(fieldId: string, value: unknown): void

// Set multiple field values at once
engine.setValues(values: Record<string, unknown>): void

// Mark a field as touched (triggers error display)
engine.touchField(fieldId: string): void

// Clear a field value
engine.clearField(fieldId: string): void

// Move to next section
engine.nextSection(): void

// Move to previous section
engine.prevSection(): void

// Jump to a section by ID
engine.jumpTo(sectionId: string): void

// Get all visible sections (respects showIf)
engine.getVisibleSections(): Section[]

// Get visible fields in a section
engine.getVisibleFields(sectionId: string): Question[]

// Field state queries
engine.isFieldVisible(fieldId: string): boolean
engine.isFieldRequired(fieldId: string): boolean
engine.isFieldDisabled(fieldId: string): boolean
engine.getFieldError(fieldId: string): string[] | undefined

// Schema access
engine.getSchema(): FormEngineSchema
engine.getSectionById(sectionId: string): Section | undefined
engine.getQuestionById(questionId: string): Question | undefined

// Validate the entire form
engine.validate(): ValidationResult

// Validate a specific section
engine.validateSection(sectionId: string): ValidationResult

// ValidationResult shape:
// {
//   valid: boolean;
//   errors: Record<string, string[]>;
//   firstErrorFieldId?: string;
//   firstErrorSectionId?: string;
// }

// Submit the form (validates first, then runs adapters)
engine.submit(): Promise<SubmitResult>

// SubmitResult shape:
// {
//   success: boolean;
//   adapterResults: {
//     adapterName: string;
//     success: boolean;
//     error?: string;
//   }[];
// }

// Save current state as a draft
engine.saveDraft(): Promise<void>

// Load a saved draft (returns true if found)
engine.loadDraft(): Promise<boolean>

// Delete the saved draft
engine.clearDraft(): void

// Clean up subscriptions and timers
engine.destroy(): void

type FormState = {
  // Values & errors
  values: Record<string, unknown>;
  errors: Record<string, string[]>;
  touched: Record<string, boolean>;
  isDirty: boolean;

  // Submission
  isSubmitting: boolean;
  isSubmitted: boolean;
  submitError?: string;
  submitAttempted: boolean;

  // Navigation
  currentSectionId: string;
  currentSectionIndex: number;
  totalVisibleSections: number;
  progressPercent: number;
  visibleSectionIds: string[];
  visitedSectionIds: string[];
  canGoNext: boolean;
  canGoPrev: boolean;
  isCurrentSectionValid: boolean;

  // Scoring
  scores: Record<string, number>;
  totalScore?: number;

  // Drafts
  hasDraft: boolean;
  lastDraftSavedAt?: string;
};

import { validateSchema, FormEngineSchemaError } from "@squaredr/fieldcraft-core";

try {
  const schema = validateSchema(rawData);
  // schema is typed FormEngineSchema
} catch (err) {
  if (err instanceof FormEngineSchemaError) {
    console.error(err.issues); // ZodIssue[]
  }
}

import { createHttpAdapter } from "@squaredr/fieldcraft-core";

const adapter = createHttpAdapter({
  url: "https://api.example.com/responses",
  method: "POST",                           // default
  headers: { Authorization: "Bearer ..." },
  timeout: 10000,
  transform: (response) => ({              // optional
    ...response,
    extra: "metadata",
  }),
});

import { generateSessionToken } from "@squaredr/fieldcraft-core";

const token = generateSessionToken(); // e.g. "a1b2c3d4-e5f6-7890-abcd-ef1234567890"