@bluprynt/forms-core 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1200 @@
+//#region src/types/conditions.d.ts
+/**
+ * A leaf condition that compares a single field's value against an expected value.
+ *
+ * @property field - Numeric id of the field whose value is tested.
+ * @property op - Comparison operator. `set`/`notset` ignore {@link value};
+ *   `in`/`notin` expect {@link value} to be an array.
+ * @property value - The reference value for the comparison. Optional for
+ *   `set`/`notset` operators.
+ */
+type SimpleCondition = {
+  field: number;
+  op: 'set' | 'notset' | 'eq' | 'ne' | 'lt' | 'gt' | 'lte' | 'gte' | 'in' | 'notin';
+  value?: unknown;
+};
+/**
+ * A compound condition that combines child conditions with logical AND or OR.
+ *
+ * - `{ and: [...] }` -- all child conditions must be true.
+ * - `{ or: [...] }` -- at least one child condition must be true.
+ */
+type CompoundCondition = {
+  and: Condition[];
+} | {
+  or: Condition[];
+};
+/**
+ * A condition controlling visibility of a field or section.
+ * Can be a {@link SimpleCondition} or a {@link CompoundCondition} that
+ * recursively nests other conditions.
+ */
+type Condition = SimpleCondition | CompoundCondition;
+//#endregion
+//#region src/condition-evaluator.d.ts
+/**
+ * Context passed to condition evaluation methods.
+ *
+ * @property values - Current form values keyed by stringified field id.
+ * @property visibilityMap - Pre-computed visibility map. When provided, a
+ *   reference to a hidden field is treated as "not set" regardless of its
+ *   actual value.
+ * @property now - Reference date for resolving relative date expressions in
+ *   condition values.
+ */
+type EvaluationContext = {
+  values: Record<string, unknown>;
+  visibilityMap?: Map<number, boolean>;
+  now: Date;
+};
+/**
+ * Evaluates condition trees against form state.
+ *
+ * Supports three kinds of conditions:
+ * - **Simple** ({@link SimpleCondition}): compares a single field's value
+ *   using one of the supported operators (`set`, `notset`, `eq`, `ne`, `lt`,
+ *   `gt`, `lte`, `gte`, `in`, `notin`).
+ * - **Compound AND**: `{ and: [...] }` -- all child conditions must be true.
+ * - **Compound OR**: `{ or: [...] }` -- at least one child condition must be true.
+ *
+ * **Hidden-field rule**: when a `visibilityMap` is provided and the
+ * referenced field is hidden (`false`), the condition evaluates as if the
+ * field has no value. This means `notset` returns `true` and all other
+ * operators return `false`.
+ *
+ * **Date handling**: condition values that are relative date expressions
+ * (e.g. `"+7d"`) are resolved against `ctx.now` before comparison.
+ */
+declare class ConditionEvaluator {
+  /**
+   * Evaluates a condition tree against the current form state.
+   *
+   * @param condition - The condition to evaluate (simple or compound).
+   * @param ctx - Evaluation context containing form values and optional
+   *   visibility/date overrides.
+   * @returns `true` if the condition is satisfied, `false` otherwise.
+   */
+  evalCondition(condition: Condition, ctx: EvaluationContext): boolean;
+  private evalSimple;
+  private resolveIfDate;
+  private compareTo;
+}
+//#endregion
+//#region src/types/field-types.d.ts
+/**
+ * Union of all supported form field types.
+ *
+ * - `string` -- free-text input
+ * - `number` -- numeric input
+ * - `boolean` -- true/false toggle
+ * - `date` -- date picker (ISO-8601 string value)
+ * - `select` -- single selection from a predefined list
+ * - `array` -- ordered list of values whose item type is any non-array field type
+ * - `file` -- file upload (stores name, MIME type, size, URL)
+ */
+type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'select' | 'array' | 'file';
+/**
+ * Discriminator for every content node in a form definition.
+ * Includes all {@link FieldType} values plus `'section'` for grouping containers.
+ */
+type ContentItemType = FieldType | 'section';
+//#endregion
+//#region src/types/select-option.d.ts
+/**
+ * A single option within a `select` field's predefined list.
+ *
+ * @property value - The stored value when this option is chosen.
+ * @property label - Human-readable display text for this option.
+ */
+type SelectOption = {
+  value: string | number;
+  label: string;
+};
+//#endregion
+//#region src/types/array-item-def.d.ts
+/**
+ * Schema for individual items inside an `array` field.
+ *
+ * Nested arrays are not allowed, so `type` excludes `'array'`.
+ * Items do not have their own id or condition -- they inherit the parent
+ * array field's identity and visibility.
+ *
+ * @property type - The scalar field type for each item in the array.
+ * @property label - Display label for the item.
+ * @property description - Optional description shown to the user.
+ * @property validation - Validation rules applied to each individual item.
+ * @property options - Required when {@link type} is `'select'`; the list of
+ *   allowed values.
+ */
+type ArrayItemDef = {
+  type: Exclude<FieldType, 'array'>;
+  label: string;
+  description?: string;
+  validation?: Record<string, unknown>;
+  options?: SelectOption[];
+};
+//#endregion
+//#region src/types/validation/array.d.ts
+/**
+ * Validation rules for `array` fields.
+ *
+ * @property minItems - Minimum number of items the array must contain (inclusive).
+ * @property maxItems - Maximum number of items the array may contain (inclusive).
+ */
+type ArrayValidation = {
+  minItems?: number;
+  maxItems?: number;
+};
+//#endregion
+//#region src/types/validation/boolean.d.ts
+/**
+ * Validation rules for `boolean` fields.
+ *
+ * @property required - Whether an explicit `true` or `false` must be provided.
+ */
+type BooleanValidation = {
+  required?: boolean;
+};
+//#endregion
+//#region src/types/validation/date.d.ts
+/**
+ * Validation rules for `date` fields.
+ *
+ * Date boundaries can be absolute ISO-8601 strings or relative date
+ * expressions (e.g. `"+7d"`, `"-1m"`). Relative dates are resolved at
+ * validation time.
+ *
+ * @property required - Whether a value must be provided.
+ * @property minDate - Earliest allowed date (inclusive). Absolute or relative.
+ * @property maxDate - Latest allowed date (inclusive). Absolute or relative.
+ */
+type DateValidation = {
+  required?: boolean;
+  minDate?: string;
+  maxDate?: string;
+};
+//#endregion
+//#region src/types/validation/file.d.ts
+/**
+ * Validation rules for `file` fields.
+ *
+ * @property required - Whether a file must be uploaded.
+ */
+type FileValidation = {
+  required?: boolean;
+};
+//#endregion
+//#region src/types/validation/number.d.ts
+/**
+ * Validation rules for `number` fields.
+ *
+ * @property required - Whether a value must be provided.
+ * @property min - Minimum allowed value (inclusive).
+ * @property max - Maximum allowed value (inclusive).
+ */
+type NumberValidation = {
+  required?: boolean;
+  min?: number;
+  max?: number;
+};
+//#endregion
+//#region src/types/validation/select.d.ts
+/**
+ * Validation rules for `select` fields.
+ *
+ * @property required - Whether an option must be chosen.
+ */
+type SelectValidation = {
+  required?: boolean;
+};
+//#endregion
+//#region src/types/validation/string.d.ts
+/**
+ * Validation rules for `string` fields.
+ *
+ * @property required - Whether a non-empty value must be provided.
+ * @property minLength - Minimum character count (inclusive).
+ * @property maxLength - Maximum character count (inclusive).
+ * @property pattern - Regular expression the value must match.
+ * @property patternMessage - Custom error message shown when `pattern` fails.
+ */
+type StringValidation = {
+  required?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  patternMessage?: string;
+};
+//#endregion
+//#region src/types/validation/type-specific.d.ts
+/**
+ * Union of all type-specific validation rule shapes.
+ * The applicable shape depends on the field's {@link FieldType}.
+ */
+type TypeSpecificValidation = StringValidation | NumberValidation | BooleanValidation | DateValidation | SelectValidation | ArrayValidation | FileValidation;
+//#endregion
+//#region src/types/field-entry.d.ts
+/**
+ * Flattened representation of a field or section stored in the engine's
+ * internal registry.
+ *
+ * Created during {@link prepare} by walking the form definition tree.
+ * Every content item (field or section) gets exactly one `FieldEntry`.
+ *
+ * @property id - Unique numeric identifier within the form.
+ * @property type - Discriminator: one of the {@link FieldType} values or `'section'`.
+ * @property condition - Visibility condition, if any.
+ * @property validation - Validation rules, if any (always `undefined` for sections).
+ * @property parentId - Id of the containing section, or `undefined` for top-level items.
+ * @property options - Select options (only for `select` fields).
+ * @property item - Array item definition (only for `array` fields).
+ * @property label - Display label (only for fields, `undefined` for sections).
+ * @property title - Display title (only for sections, `undefined` for fields).
+ */
+type FieldEntry = {
+  id: number;
+  type: ContentItemType;
+  condition: Condition | undefined;
+  validation: TypeSpecificValidation | undefined;
+  parentId: number | undefined;
+  options: SelectOption[] | undefined;
+  item: ArrayItemDef | undefined;
+  label: string | undefined;
+  title: string | undefined;
+};
+//#endregion
+//#region src/dependency-graph.d.ts
+/**
+ * Manages the condition dependency graph for form fields.
+ *
+ * Built from the field registry during engine preparation. Provides:
+ * - Forward dependency graph (`graph`): answers "if field X changes, which
+ *   items need to re-evaluate their visibility?"
+ * - Topological ordering (`topologicalOrder`): guarantees that when computing
+ *   visibility, every item is evaluated after the fields it depends on.
+ * - Affected-ids lookup (`getAffectedIds`): returns all transitively
+ *   affected item ids when a field value changes (lazily cached).
+ *
+ * Static methods (`extractFieldRefs`, `detectCycle`) can be used before
+ * constructing an instance, e.g. during semantic validation.
+ */
+declare class DependencyGraph {
+  /**
+   * Forward adjacencyMap map: key is a field id, value is the set of item ids
+   * whose conditions reference that field.
+   */
+  readonly graph: Map<number, Set<number>>;
+  /**
+   * Item ids in topological order. Dependencies come before dependents.
+   */
+  readonly topologicalOrder: number[];
+  private readonly registry;
+  private readonly affectedCache;
+  /**
+   * @param registry - The engine's field registry (built during preparation).
+   */
+  constructor(registry: Map<number, FieldEntry>);
+  /**
+   * Extracts the set of field ids referenced by a condition tree.
+   *
+   * Recursively walks compound conditions (`and`/`or`) and collects the
+   * `field` property from every leaf {@link SimpleCondition}.
+   *
+   * @param condition - A simple or compound condition.
+   * @returns Set of all unique field ids that appear in the condition.
+   */
+  static extractFieldRefs(condition: Condition): Set<number>;
+  /**
+   * Detects circular dependencies in the condition graph.
+   *
+   * Uses DFS-based cycle detection (white/gray/black coloring). If a cycle
+   * is found, the function reconstructs and returns a human-readable path
+   * string (e.g. `"1 -> 2 -> 3 -> 1"`).
+   *
+   * @param registry - The engine's field registry.
+   * @returns An array of field ids forming the cycle, or `undefined` if no cycle exists.
+   */
+  static detectCycle(registry: Map<number, FieldEntry>): number[] | undefined;
+  /**
+   * Returns the set of item ids whose visibility could change when the given
+   * field's value changes.
+   *
+   * Performs a transitive expansion of the forward dependency graph starting
+   * from the field's direct dependents. Results are memoized for subsequent
+   * calls with the same `fieldId`.
+   *
+   * @param fieldId - Id of the field whose value changed.
+   * @returns Set of all transitively affected item ids. Empty set if no items
+   *   depend on `fieldId`.
+   */
+  getAffectedIds(fieldId: number): Set<number>;
+  private static collectRefs;
+  private static dfs;
+  private static reconstructCycle;
+  /**
+   * Builds the forward dependency graph from the registry.
+   */
+  private buildGraph;
+  /**
+   * Produces a topological ordering using Kahn's algorithm.
+   */
+  private buildTopologicalOrder;
+  /**
+   * Expands a set of item ids to include all transitive dependents via BFS.
+   */
+  private expandTransitiveDependencies;
+}
+//#endregion
+//#region src/types/form-values.d.ts
+/**
+ * A flat key-value map of user-submitted form data.
+ *
+ * Keys are stringified field ids (e.g. `"1"`, `"42"`). Values are the raw
+ * data entered by the user, typed according to the field's {@link FieldType}.
+ */
+type FormValues = Record<string, unknown>;
+/**
+ * A complete form document containing form metadata and user-submitted values.
+ *
+ * This is the serialization/storage format for filled forms. The `form`
+ * property links the document back to the schema that produced it, and
+ * `values` holds the flat field data.
+ *
+ * @property form - Metadata identifying the form schema.
+ * @property form.id - The form schema's unique identifier (from {@link FormDefinition.id}).
+ * @property form.version - The form schema's version (from {@link FormDefinition.version}).
+ * @property values - Flat key-value map of user-submitted data.
+ */
+type FormDocument = {
+  form: {
+    id: string;
+    version: string;
+    submittedAt: string;
+  };
+  values: FormValues;
+};
+//#endregion
+//#region src/types/validation-results.d.ts
+/**
+ * Machine-readable codes for all field-level validation rules.
+ *
+ * | Code | Applies to |
+ * |------|------------|
+ * | `REQUIRED` | All field types |
+ * | `TYPE` | All field types (value has wrong runtime type) |
+ * | `MIN_LENGTH` | `string` |
+ * | `MAX_LENGTH` | `string` |
+ * | `PATTERN` | `string` |
+ * | `MIN` | `number` |
+ * | `MAX` | `number` |
+ * | `MIN_DATE` | `date` |
+ * | `MAX_DATE` | `date` |
+ * | `INVALID_DATE` | `date` (unparseable value) |
+ * | `INVALID_OPTION` | `select` (value not in options list) |
+ * | `MIN_ITEMS` | `array` |
+ * | `MAX_ITEMS` | `array` |
+ */
+type FieldValidationRule = 'REQUIRED' | 'TYPE' | 'MIN_LENGTH' | 'MAX_LENGTH' | 'PATTERN' | 'MIN' | 'MAX' | 'MIN_DATE' | 'MAX_DATE' | 'INVALID_DATE' | 'INVALID_OPTION' | 'MIN_ITEMS' | 'MAX_ITEMS';
+/**
+ * A single validation error for a specific field.
+ *
+ * @property fieldId - Numeric id of the field that failed validation.
+ * @property rule - Machine-readable rule code from {@link FieldValidationRule}.
+ * @property message - Human-readable error description.
+ * @property params - Optional parameters providing context (e.g. `{ minLength: 5, actual: 3 }`).
+ * @property itemIndex - For array fields, the zero-based index of the item
+ *   that failed validation. `undefined` for non-array fields.
+ */
+type FieldValidationError = {
+  fieldId: number;
+  rule: FieldValidationRule;
+  message: string;
+  params?: Record<string, unknown>;
+  itemIndex?: number;
+};
+/**
+ * Machine-readable codes for all document-level validation errors.
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `SCHEMA_INVALID` | The form definition does not conform to the JSON schema. |
+ * | `DUPLICATE_ID` | Two or more content items share the same numeric id. |
+ * | `NESTING_DEPTH` | A section is nested deeper than the allowed 3 levels. |
+ * | `UNKNOWN_FIELD_REF` | A condition references a field id that does not exist in the form. |
+ * | `CONDITION_REFS_SECTION` | A condition references a section id; sections have no value to compare. |
+ * | `INVALID_MIN_MAX` | A field's minimum constraint exceeds its maximum constraint. |
+ * | `INVALID_REGEX` | String field `pattern` is not a valid regular expression. |
+ * | `CIRCULAR_DEPENDENCY` | Condition dependencies form a cycle (A depends on B depends on A). |
+ * | `FORM_ID_MISMATCH` | The document's form id does not match the engine's form definition id. |
+ * | `FORM_VERSION_MISMATCH` | The document's form version does not match the engine's form definition version. |
+ * | `FORM_SUBMITTED_AT_MISSING` | The document's submittedAt field is missing. |
+ * | `FORM_SUBMITTED_AT_INVALID` | The document's submittedAt field is not a valid date. |
+ */
+type DocumentValidationErrorCode = 'SCHEMA_INVALID' | 'DUPLICATE_ID' | 'NESTING_DEPTH' | 'UNKNOWN_FIELD_REF' | 'CONDITION_REFS_SECTION' | 'INVALID_MIN_MAX' | 'INVALID_REGEX' | 'CIRCULAR_DEPENDENCY' | 'FORM_ID_MISMATCH' | 'FORM_VERSION_MISMATCH' | 'FORM_SUBMITTED_AT_MISSING' | 'FORM_SUBMITTED_AT_INVALID';
+/**
+ * A single validation error found during form definition or document validation.
+ *
+ * @property code - Machine-readable error code from {@link DocumentValidationErrorCode}.
+ * @property message - Human-readable error description.
+ * @property params - Optional parameters providing context (e.g. `{ expected, actual }`).
+ * @property itemId - Id of the content item involved, when applicable.
+ */
+type DocumentValidationError = {
+  code: DocumentValidationErrorCode;
+  message: string;
+  params?: Record<string, unknown>;
+  itemId?: number;
+};
+/**
+ * Aggregated result of validating all visible form fields.
+ *
+ * @property valid - `true` when `fieldErrors` is empty and no `documentErrors` exist.
+ * @property fieldErrors - Map from field id to its validation errors.
+ *   Empty map when `valid` is `true`. Fields with no errors have no entry.
+ * @property documentErrors - Document-level compatibility errors, if any.
+ */
+type FormValidationResult = {
+  valid: boolean;
+  fieldErrors: Map<number, FieldValidationError[]>;
+  documentErrors?: DocumentValidationError[];
+};
+//#endregion
+//#region src/field-validator.d.ts
+/**
+ * Validates form values against the schema's validation rules.
+ *
+ * **Which fields are validated:**
+ * - Only fields (not sections) are validated.
+ * - Hidden fields (those with `visibilityMap.get(id) === false`) are skipped
+ *   entirely -- they produce no errors regardless of their value.
+ *
+ * **How each field type is validated:**
+ * - `string` -- `required`, `minLength`, `maxLength`, `pattern`.
+ * - `number` -- `required`, `min`, `max`.
+ * - `boolean` -- `required` (must be explicitly `true` or `false`).
+ * - `date` -- `required`, `minDate`, `maxDate`. Relative date boundaries
+ *   are resolved against `now`.
+ * - `select` -- `required`, plus the value must be one of the defined options.
+ * - `array` -- `minItems`, `maxItems`, plus each item is validated
+ *   individually according to the array's {@link ArrayItemDef}. Item-level
+ *   errors carry an `itemIndex`.
+ *
+ * For all types, if `required` fails, no further rules are checked for that
+ * field (early return). If the value is empty/absent and `required` is not
+ * set, no errors are produced.
+ */
+declare class FieldValidator {
+  private readonly registry;
+  private readonly validators;
+  /**
+   * @param registry - The engine's field registry.
+   */
+  constructor(registry: Map<number, FieldEntry>);
+  /**
+   * Validates form values against the schema's validation rules.
+   *
+   * @param values - The form values to validate, keyed by stringified field id.
+   * @param visibilityMap - Pre-computed visibility map for all items.
+   * @param now - Reference date for resolving relative date expressions.
+   *   Defaults to `new Date()`.
+   * @returns A {@link FormValidationResult} with `valid: true` when no errors
+   *   exist, or `valid: false` with a populated `fieldErrors` map.
+   */
+  validate(values: FormValues, visibilityMap: Map<number, boolean>, now?: Date): FormValidationResult;
+  private validateField;
+}
+//#endregion
+//#region src/types/form-definition.d.ts
+/**
+ * Top-level form definition object representing a complete form schema.
+ *
+ * This is the JSON document that authors create and publish. It is passed to
+ * {@link prepare} to produce a {@link FormEngine}.
+ *
+ * @property id - Globally unique identifier for the form schema.
+ * @property version - Schema version string (e.g. `"1.0.0"`).
+ * @property title - Human-readable title of the form.
+ * @property description - Optional description of the form's purpose.
+ * @property content - Ordered list of top-level fields and sections.
+ */
+type FormDefinition = {
+  id: string;
+  version: string;
+  title: string;
+  description?: string;
+  content: ContentItem[];
+};
+/**
+ * A single node in the form definition tree -- either a field or a section.
+ */
+type ContentItem = FieldContentItem | SectionContentItem;
+/**
+ * A field node within the form definition tree.
+ *
+ * @property id - Unique numeric identifier.
+ * @property type - The field's data type.
+ * @property label - Display label shown to the user.
+ * @property description - Optional help text.
+ * @property condition - Visibility condition that controls whether this field is shown.
+ * @property validation - Type-specific validation rules.
+ * @property options - Allowed values (required for `select` fields).
+ * @property item - Item schema (required for `array` fields).
+ */
+type FieldContentItem = {
+  id: number;
+  type: FieldType;
+  label: string;
+  description?: string;
+  condition?: Condition;
+  validation?: TypeSpecificValidation;
+  options?: SelectOption[];
+  item?: ArrayItemDef;
+};
+/**
+ * A section node that groups fields and/or child sections.
+ *
+ * Sections can be nested up to 3 levels deep.
+ *
+ * @property id - Unique numeric identifier.
+ * @property type - Always `'section'`.
+ * @property title - Display title for the section.
+ * @property description - Optional description.
+ * @property condition - Visibility condition. When hidden, all descendant
+ *   fields and sections are also hidden.
+ * @property content - Ordered list of child content items.
+ */
+type SectionContentItem = {
+  id: number;
+  type: 'section';
+  title: string;
+  description?: string;
+  condition?: Condition;
+  content: ContentItem[];
+};
+//#endregion
+//#region src/form-definition-editor.d.ts
+/**
+ * Descriptor for a field to be added via the editor.
+ * `id` is optional -- when omitted the editor auto-assigns the next available id.
+ */
+type FieldDescriptor = Omit<FieldContentItem, 'id'> & {
+  id?: number;
+};
+/**
+ * Descriptor for a section to be added via the editor.
+ * `id` is optional -- when omitted the editor auto-assigns the next available id.
+ * `content` defaults to an empty array (items are added separately).
+ */
+type SectionDescriptor = Omit<SectionContentItem, 'id' | 'content'> & {
+  id?: number;
+  content?: ContentItem[];
+};
+/**
+ * Flat info about a content item returned by listing methods.
+ */
+type ContentItemInfo = {
+  id: number;
+  type: ContentItem['type'];
+  label?: string;
+  title?: string;
+  parentId: number | undefined;
+};
+/**
+ * Mutable editor for building and modifying a {@link FormDefinition}.
+ *
+ * Operates directly on the definition tree. All mutating methods return
+ * `this` for fluent chaining.
+ *
+ * @example
+ * ```ts
+ * 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()
+ * ```
+ */
+declare class FormDefinitionEditor {
+  private definition;
+  constructor(definition: FormDefinition);
+  setTitle(title: string): this;
+  setDescription(description: string | undefined): this;
+  setVersion(version: string): this;
+  setId(id: string): this;
+  /**
+   * Returns the next available numeric id (max existing + 1).
+   */
+  nextId(): number;
+  /**
+   * Adds a field to the form.
+   *
+   * @param descriptor - Field properties. `id` is auto-assigned if omitted.
+   * @param parentId - Section id to add into. `undefined` for top-level.
+   * @param index - Position within the parent's content array. Appends if omitted.
+   * @returns `this` for chaining.
+   * @throws If `parentId` references a non-existent or non-section item, or if the id already exists.
+   */
+  addField(descriptor: FieldDescriptor, parentId?: number, index?: number): this;
+  /**
+   * Adds a section to the form.
+   *
+   * @param descriptor - Section properties. `id` is auto-assigned if omitted.
+   * @param parentId - Parent section id. `undefined` for top-level.
+   * @param index - Position within the parent's content array. Appends if omitted.
+   * @returns `this` for chaining.
+   * @throws If `parentId` references a non-existent or non-section item, or if the id already exists.
+   */
+  addSection(descriptor: SectionDescriptor, parentId?: number, index?: number): this;
+  /**
+   * Updates properties of an existing field.
+   *
+   * Cannot change `id` or `type`. Use {@link removeItem} + {@link addField}
+   * to change the type.
+   */
+  updateField(id: number, updates: Partial<Omit<FieldContentItem, 'id' | 'type'>>): this;
+  /**
+   * Updates properties of an existing section.
+   *
+   * Cannot change `id`, `type`, or `content` directly. Use add/remove methods
+   * for content manipulation.
+   */
+  updateSection(id: number, updates: Partial<Omit<SectionContentItem, 'id' | 'type' | 'content'>>): this;
+  /**
+   * Removes a field or section (and all its descendants) by id.
+   *
+   * @returns `this` for chaining.
+   * @throws If the id is not found.
+   */
+  removeItem(id: number): this;
+  /**
+   * Moves an item to a new parent and/or position.
+   *
+   * @param id - Id of the item to move.
+   * @param targetParentId - Destination section id, or `undefined` for top-level.
+   * @param index - Position in the target content array. Appends if omitted.
+   */
+  moveItem(id: number, targetParentId: number | undefined, index?: number): this;
+  /**
+   * Returns a flat list of all content items (fields + sections) with parent info.
+   */
+  listAll(): ContentItemInfo[];
+  /**
+   * Returns a flat list of all fields (excludes sections).
+   */
+  listFields(): ContentItemInfo[];
+  /**
+   * Returns a flat list of all sections.
+   */
+  listSections(): ContentItemInfo[];
+  /**
+   * Returns the content item with the given id, or `undefined` if not found.
+   */
+  getItem(id: number): ContentItem | undefined;
+  /**
+   * Sets or clears the validation rules for a field.
+   */
+  setValidation(id: number, validation: TypeSpecificValidation | undefined): this;
+  /**
+   * Sets or clears the visibility condition for a field or section.
+   */
+  setCondition(id: number, condition: Condition | undefined): this;
+  /**
+   * Sets the select options for a `select` field.
+   */
+  setOptions(id: number, options: SelectOption[]): this;
+  /**
+   * Sets the item definition for an `array` field.
+   */
+  setArrayItem(id: number, itemDef: ArrayItemDef): this;
+  /**
+   * Sets the label for a field.
+   */
+  setLabel(id: number, label: string): this;
+  /**
+   * Sets the description for a field or section.
+   */
+  setFieldDescription(id: number, description: string | undefined): this;
+  /**
+   * Returns a deep clone of the current form definition.
+   */
+  toJSON(): FormDefinition;
+  private findItem;
+  private assertIdAvailable;
+  private insertItem;
+  private getTargetContent;
+  private removeFromContent;
+  private walkAll;
+  private walkAllWithParent;
+  private collectDescendantIds;
+}
+//#endregion
+//#region src/form-definition-validator.d.ts
+/**
+ * Validates form definitions at both the structural (JSON Schema) and
+ * semantic levels.
+ *
+ * Used by {@link FormEngine} during construction before building the engine.
+ *
+ * ### Schema validation (`validateSchema`)
+ * Validates raw input against the form definition JSON Schema. Returns
+ * `SCHEMA_INVALID` issues for every violation found.
+ *
+ * ### Semantic validation (`validate`)
+ * Checks for logical issues that go beyond JSON schema validity:
+ * 1. **Duplicate IDs** (`DUPLICATE_ID`) -- every content item id must be unique.
+ * 2. **Nesting depth** (`NESTING_DEPTH`) -- sections may not be nested more
+ *    than 3 levels deep.
+ * 3. **Unknown field references** (`UNKNOWN_FIELD_REF`) -- conditions must
+ *    only reference field ids that exist in the registry.
+ * 4. **Condition references section** (`CONDITION_REFS_SECTION`) -- conditions
+ *    must not reference section ids, because sections have no values.
+ * 5. **Constraint contradictions** (`INVALID_MIN_MAX`) -- e.g. `minLength > maxLength`,
+ *    `min > max`, `minDate > maxDate` (absolute dates only), `minItems > maxItems`.
+ * 6. **Invalid regex** (`INVALID_REGEX`) -- string field `pattern` values must
+ *    be valid regular expressions.
+ */
+declare class FormDefinitionValidator {
+  /**
+   * Validates raw input against the form definition JSON schema.
+   *
+   * @param input - The raw input to validate.
+   * @returns Array of `SCHEMA_INVALID` issues. Empty when the input conforms to the schema.
+   */
+  validateSchema(input: unknown): DocumentValidationError[];
+  /**
+   * Validates a form definition semantically.
+   *
+   * @param definition - The form definition to validate.
+   * @param registry - The flattened field registry built from the definition.
+   * @returns Array of issues found. Empty if the definition is semantically valid.
+   */
+  validate(definition: FormDefinition, registry: Map<number, FieldEntry>): DocumentValidationError[];
+  private checkDuplicateIds;
+  private checkNestingDepth;
+  private checkConditionRefs;
+  private checkConditionRefsSection;
+  private checkConstraintContradictions;
+  private checkInvalidRegex;
+  private walkItems;
+}
+//#endregion
+//#region src/types/form-snapshot.d.ts
+/**
+ * A point-in-time snapshot pairing a {@link FormDefinition} with a
+ * {@link FormDocument}.
+ *
+ * @property definition - The form schema that describes the structure.
+ * @property document - The filled form data.
+ */
+type FormSnapshot = {
+  definition: FormDefinition;
+  document: FormDocument;
+};
+//#endregion
+//#region src/form-engine.d.ts
+/**
+ * The runtime form engine.
+ *
+ * Created by passing a {@link FormDefinition} to the constructor. The
+ * construction lifecycle is:
+ *
+ * 1. **Build field registry** -- walks the definition tree depth-first,
+ *    creating a flat {@link FieldEntry} for every field and section while
+ *    recording document-order ids in `contentOrder`.
+ * 2. **Semantic validation** -- checks for duplicate ids, excessive nesting,
+ *    unknown/invalid condition references, constraint contradictions, and
+ *    invalid regex patterns.
+ * 3. **Cycle detection** -- verifies that condition dependencies form a DAG
+ *    (no circular references).
+ * 4. **Error reporting** -- if any issues were found in steps 2-3, throws a
+ *    {@link DocumentError} containing all issues.
+ * 5. **Build dependency graph** -- creates a forward adjacency map so the
+ *    engine can quickly determine which items are affected when a field
+ *    value changes.
+ * 6. **Topological sort** -- orders all items so that dependencies are
+ *    evaluated before dependents (used by `getVisibilityMap`).
+ * 7. **Assemble components** -- creates internal {@link ConditionEvaluator},
+ *    {@link VisibilityResolver}, and {@link FieldValidator} instances.
+ *
+ * @example
+ * ```ts
+ * const engine = new FormEngine(myFormDefinition);
+ * const visibility = engine.getVisibilityMap(formValues);
+ * const result = engine.validate(formValues);
+ * ```
+ */
+declare class FormEngine {
+  private readonly registry;
+  private readonly depGraph;
+  private readonly visibilityResolver;
+  private readonly fieldValidator;
+  private readonly definition;
+  private readonly formId;
+  private readonly formVersion;
+  /**
+   * Ordered list of all content item ids in depth-first document order.
+   * Matches the order in which items appear in the form definition.
+   */
+  readonly contentOrder: readonly number[];
+  /**
+   * Compiles a {@link FormDefinition} into a ready-to-use engine.
+   *
+   * @param definition - A complete form definition to compile.
+   * @throws {DocumentError} If the definition contains semantic issues
+   *   or circular condition dependencies.
+   */
+  constructor(definition: FormDefinition);
+  /**
+   * Creates a {@link FormDocument} pre-populated with the form schema's
+   * id and version.
+   *
+   * @param values - Optional initial field values. Defaults to an empty object.
+   * @returns A new form document ready for use with engine methods.
+   */
+  createFormDocument(values?: FormValues): FormDocument;
+  /**
+   * Serializes the form definition and document into a single {@link FormSnapshot}.
+   *
+   * The snapshot contains the original {@link FormDefinition} used to construct
+   * the engine and the provided {@link FormDocument}. No validation is performed;
+   * call {@link validate} separately if needed.
+   *
+   * @param doc - The form document to include in the snapshot.
+   * @returns A snapshot containing both the definition and the document.
+   */
+  dumpDocument(doc: FormDocument): FormSnapshot;
+  /**
+   * Loads a {@link FormDocument} from a previously created {@link FormSnapshot}.
+   *
+   * Verifies that the snapshot's form definition matches the engine's
+   * compiled definition by comparing id and version. Throws a
+   * {@link DocumentError} if there is a mismatch.
+   *
+   * @param snapshot - A snapshot previously produced by {@link dumpDocument}.
+   * @returns The form document from the snapshot.
+   * @throws {DocumentError} If the snapshot's definition id or version
+   *   does not match the engine's.
+   */
+  loadDocument(snapshot: FormSnapshot): FormDocument;
+  /**
+   * Determines whether a field or section is visible given the current form document.
+   *
+   * Evaluates the item's own condition and walks up the parent chain --
+   * an item is hidden if any ancestor is hidden.
+   *
+   * @param id - Numeric id of the field or section.
+   * @param doc - Current form document.
+   * @returns `true` if the item should be displayed, `false` otherwise.
+   */
+  isVisible(id: number, doc: FormDocument): boolean;
+  /**
+   * Computes visibility for every field and section in topological order.
+   *
+   * The resulting map is keyed by item id. Items whose conditions depend on
+   * other items are evaluated after their dependencies, ensuring correct
+   * cascading visibility (e.g. a hidden parent hides all children).
+   *
+   * @param doc - Current form document.
+   * @returns Map from item id to visibility boolean.
+   */
+  getVisibilityMap(doc: FormDocument): Map<number, boolean>;
+  /**
+   * Returns the set of item ids whose visibility may change when the
+   * specified field's value changes.
+   *
+   * Includes transitive dependents -- if field A controls field B, and
+   * field B controls field C, changing A returns `{B, C}`.
+   * Results are cached for the lifetime of the engine.
+   *
+   * @param fieldId - Id of the field that changed.
+   * @returns Set of affected item ids (does not include `fieldId` itself unless
+   *   it is part of a dependency chain).
+   */
+  getAffectedIds(fieldId: number): Set<number>;
+  /**
+   * Validates form values against the schema's validation rules.
+   *
+   * Only visible fields are validated -- hidden fields are skipped entirely.
+   * Sections are never validated directly. For array fields, each item is
+   * validated individually according to the array's item definition.
+   *
+   * The reference time for relative date validation is derived from
+   * `doc.form.submittedAt`. If that value is missing or unparseable, a
+   * document-level error is reported and `new Date()` is used as fallback.
+   *
+   * @param doc - Current form document to validate.
+   * @returns Validation result with a `valid` flag and a `fieldErrors` map.
+   */
+  validate(doc: FormDocument): FormValidationResult;
+  /**
+   * Retrieves the internal {@link FieldEntry} for a given id.
+   *
+   * @param id - Numeric id of the field or section.
+   * @returns The field entry, or `undefined` if the id is not in the registry.
+   */
+  getFieldDef(id: number): FieldEntry | undefined;
+  private static parseNow;
+  private static walkContent;
+}
+//#endregion
+//#region src/form-values-editor.d.ts
+/**
+ * Mutable editor for building and modifying form values against a {@link FormDefinition}.
+ *
+ * Wraps a {@link FormEngine} and a mutable {@link FormDocument}. All mutating
+ * methods return `this` for fluent chaining.
+ *
+ * @example
+ * ```ts
+ * const editor = new FormValuesEditor(definition)
+ * editor
+ *   .setFieldValue(1, 'Alice')
+ *   .setFieldValue(2, 30)
+ *   .setSubmittedAt('2025-01-01T00:00:00Z')
+ *
+ * const result = editor.validate()
+ * const doc = editor.toJSON()
+ * ```
+ */
+declare class FormValuesEditor {
+  private readonly engine;
+  private doc;
+  /**
+   * Creates a new editor for the given form definition.
+   *
+   * @param definition - The form definition to edit values against.
+   * @param doc - An existing document to pre-populate. Deep-cloned internally.
+   *   When omitted a blank document is created via {@link FormEngine.createFormDocument}.
+   */
+  constructor(definition: FormDefinition, doc?: FormDocument);
+  /**
+   * Returns the current value of a field.
+   *
+   * @param fieldId - Numeric id of the field.
+   * @returns The field value, or `undefined` if not set.
+   */
+  getFieldValue(fieldId: number): unknown;
+  /**
+   * Sets the value of a field.
+   *
+   * @param fieldId - Numeric id of the field.
+   * @param value - The value to set.
+   * @returns `this` for chaining.
+   * @throws If `fieldId` is unknown or references a section.
+   */
+  setFieldValue(fieldId: number, value: unknown): this;
+  /**
+   * Removes the value of a field.
+   *
+   * @param fieldId - Numeric id of the field.
+   * @returns `this` for chaining.
+   */
+  clearFieldValue(fieldId: number): this;
+  /**
+   * Appends an item to an array field.
+   *
+   * If the field currently has no value, it is initialized to an empty array
+   * before appending.
+   *
+   * @param fieldId - Numeric id of the array field.
+   * @param value - The value to append. Defaults to `undefined`.
+   * @returns `this` for chaining.
+   * @throws If `fieldId` is not an array field.
+   */
+  addArrayItem(fieldId: number, value?: unknown): this;
+  /**
+   * Removes an item from an array field by index.
+   *
+   * @param fieldId - Numeric id of the array field.
+   * @param index - Zero-based index of the item to remove.
+   * @returns `this` for chaining.
+   * @throws If `fieldId` is not an array field or the index is out of bounds.
+   */
+  removeArrayItem(fieldId: number, index: number): this;
+  /**
+   * Moves an item within an array field from one index to another.
+   *
+   * @param fieldId - Numeric id of the array field.
+   * @param fromIndex - Current zero-based index of the item.
+   * @param toIndex - Target zero-based index.
+   * @returns `this` for chaining.
+   * @throws If `fieldId` is not an array field or either index is out of bounds.
+   */
+  moveArrayItem(fieldId: number, fromIndex: number, toIndex: number): this;
+  /**
+   * Sets the value of an item at a specific index in an array field.
+   *
+   * @param fieldId - Numeric id of the array field.
+   * @param index - Zero-based index of the item to set.
+   * @param value - The new value for the item.
+   * @returns `this` for chaining.
+   * @throws If `fieldId` is not an array field or the index is out of bounds.
+   */
+  setArrayItem(fieldId: number, index: number, value: unknown): this;
+  /**
+   * Sets the `submittedAt` timestamp on the document.
+   *
+   * @param submittedAt - ISO 8601 timestamp string.
+   * @returns `this` for chaining.
+   */
+  setSubmittedAt(submittedAt: string): this;
+  /**
+   * Validates the current document against the form definition.
+   *
+   * Delegates to {@link FormEngine.validate}.
+   *
+   * @returns The validation result.
+   */
+  validate(): FormValidationResult;
+  /**
+   * Computes visibility for every field and section.
+   *
+   * Delegates to {@link FormEngine.getVisibilityMap}.
+   *
+   * @returns Map from item id to visibility boolean.
+   */
+  getVisibilityMap(): Map<number, boolean>;
+  /**
+   * Determines whether a field or section is visible given current values.
+   *
+   * Delegates to {@link FormEngine.isVisible}.
+   *
+   * @param id - Numeric id of the field or section.
+   * @returns `true` if the item should be displayed.
+   */
+  isVisible(id: number): boolean;
+  /**
+   * Returns a deep clone of the current form document.
+   *
+   * @returns A new serializable {@link FormDocument} instance.
+   */
+  toJSON(): FormDocument;
+  /**
+   * Asserts that `fieldId` exists in the registry and is not a section.
+   */
+  private assertField;
+  /**
+   * Asserts that `fieldId` is an array field and returns the current array value.
+   * Throws if the field is not an array type or the current value is not an array.
+   */
+  private assertArray;
+  /**
+   * Returns the array value for `fieldId`, initializing to `[]` if not yet set.
+   */
+  private getOrInitArray;
+}
+//#endregion
+//#region src/types/errors.d.ts
+/**
+ * Error thrown when form definition or document validation fails.
+ *
+ * Inspect {@link errors} for structured programmatic access to all
+ * validation issues.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const engine = new FormEngine(definition);
+ * } catch (err) {
+ *   if (err instanceof DocumentError) {
+ *     for (const e of err.errors) {
+ *       console.log(e.code, e.message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class DocumentError extends Error {
+  /** Structured list of all validation errors. */
+  readonly errors: DocumentValidationError[];
+  /**
+   * @param errors - One or more validation errors that caused the error.
+   */
+  constructor(errors: DocumentValidationError[]);
+}
+//#endregion
+//#region src/types/file-value.d.ts
+/**
+ * Metadata for an uploaded file.
+ *
+ * The engine does not handle actual file upload -- the consumer handles upload
+ * and produces the `FileValue` object.
+ *
+ * @property name - Original file name.
+ * @property mimeType - MIME type of the file.
+ * @property size - File size in bytes.
+ * @property url - URL where the file can be accessed.
+ */
+type FileValue = {
+  name: string;
+  mimeType: string;
+  size: number;
+  url: string;
+};
+//#endregion
+//#region src/visibility-resolver.d.ts
+/**
+ * Computes field and section visibility for a form.
+ *
+ * Provides two modes of visibility computation:
+ * - **Single-item** (`isVisible`): evaluates one item's condition plus its
+ *   parent chain. Does not use the hidden-field rule.
+ * - **Bulk** (`getVisibilityMap`): evaluates all items in topological order
+ *   with the hidden-field rule applied (references to hidden fields are
+ *   treated as "not set").
+ */
+declare class VisibilityResolver {
+  private readonly registry;
+  private readonly conditionEvaluator;
+  private readonly topologicalOrder;
+  /**
+   * @param registry - The engine's field registry.
+   * @param conditionEvaluator - Evaluator for condition trees.
+   * @param topologicalOrder - Item ids in topological order (from {@link DependencyGraph}).
+   */
+  constructor(registry: Map<number, FieldEntry>, conditionEvaluator: ConditionEvaluator, topologicalOrder: number[]);
+  /**
+   * Determines whether a single field or section is visible.
+   *
+   * Evaluation logic:
+   * 1. If the item has its own condition, evaluate it. If `false`, the item is hidden.
+   * 2. If the item has a parent section, recursively check parent visibility.
+   *    An item is hidden whenever any ancestor is hidden.
+   * 3. Items without conditions and without hidden parents are visible.
+   *
+   * Unlike {@link getVisibilityMap}, this method does not use the
+   * pre-computed visibility map and does not apply the hidden-field rule.
+   * Use it for one-off visibility checks; prefer `getVisibilityMap` when
+   * evaluating many items at once.
+   *
+   * @param id - Numeric id of the field or section to check.
+   * @param values - Current form values.
+   * @param now - Reference date for relative date expressions.
+   * @returns `true` if the item should be displayed.
+   */
+  isVisible(id: number, values: FormValues, now: Date): boolean;
+  /**
+   * Computes visibility for all fields and sections in a single pass.
+   *
+   * Iterates in topological order so that every item is evaluated after the
+   * fields its condition depends on. This enables the **hidden-field rule**:
+   * if a condition references a field that has already been determined hidden,
+   * that field is treated as "not set".
+   *
+   * Cascading parent visibility is also enforced -- if a parent section is
+   * hidden, all its children are immediately marked hidden without evaluating
+   * their own conditions.
+   *
+   * @param values - Current form values.
+   * @param now - Reference date for relative date expressions.
+   * @returns Map from item id to visibility boolean (`true` = visible).
+   */
+  getVisibilityMap(values: FormValues, now: Date): Map<number, boolean>;
+}
+//#endregion
+export { type ArrayItemDef, type ArrayValidation, type BooleanValidation, type CompoundCondition, type Condition, ConditionEvaluator, type ContentItem, type ContentItemInfo, type ContentItemType, type DateValidation, DependencyGraph, DocumentError, type DocumentValidationError, type DocumentValidationErrorCode, type EvaluationContext, type FieldContentItem, type FieldDescriptor, type FieldEntry, type FieldType, type FieldValidationError, type FieldValidationRule, FieldValidator, type FileValidation, type FileValue, type FormDefinition, FormDefinitionEditor, FormDefinitionValidator, type FormDocument, FormEngine, type FormSnapshot, type FormValidationResult, type FormValues, FormValuesEditor, type NumberValidation, type SectionContentItem, type SectionDescriptor, type SelectOption, type SelectValidation, type SimpleCondition, type StringValidation, type TypeSpecificValidation, VisibilityResolver };
+//# sourceMappingURL=index.d.cts.map