@bluprynt/forms-core 3.0.0 → 4.1.0

package/dist/index.cjs

@@ -110,6 +110,18 @@ const resolveRelativeDate = (relative, now) => {
 *
 * **Date handling**: condition values that are relative date expressions
 * (e.g. `"+7d"`) are resolved against `ctx.now` before comparison.
+*
+* **Multiselect handling**: when `ctx.fieldTypes` reports the referenced field
+* as `multiselect`, its array value is compared as a set instead of a scalar:
+* `set` means "at least one option chosen", `eq`/`ne` compare set membership
+* ignoring order and duplicates, `in`/`notin` test whether *any* chosen option
+* appears in the condition's list, and the ordering operators are always
+* `false`. Fields of every other type -- including `array` -- keep the original
+* scalar semantics.
+*
+* **Object-valued fields** (`file`, `sustainability`) go through the scalar path
+* too, so only `set`/`notset` are meaningful: any object present counts as
+* `set`, and `eq`/`ne`/`in`/`notin` compare by reference and so never match.
 */
 var ConditionEvaluator = class {
 	/**
@@ -128,6 +140,7 @@ var ConditionEvaluator = class {
 	evalSimple(cond, ctx) {
 		if (ctx.visibilityMap && ctx.visibilityMap.get(cond.field) === false) return cond.op === "notset";
 		const fieldValue = ctx.values[String(cond.field)];
+		if (ctx.fieldTypes?.get(cond.field) === "multiselect") return this.evalMultiselect(cond, fieldValue);
 		switch (cond.op) {
 			case "set": return fieldValue !== null && fieldValue !== void 0 && fieldValue !== "";
 			case "notset": return fieldValue === null || fieldValue === void 0 || fieldValue === "";
@@ -142,6 +155,32 @@ var ConditionEvaluator = class {
 			default: return false;
 		}
 	}
+	evalMultiselect(cond, fieldValue) {
+		const selected = Array.isArray(fieldValue) ? fieldValue : [];
+		const candidates = cond.value;
+		switch (cond.op) {
+			case "set": return selected.length > 0;
+			case "notset": return selected.length === 0;
+			case "eq": return this.sameSet(selected, candidates);
+			case "ne": return !this.sameSet(selected, candidates);
+			case "in": return Array.isArray(candidates) && selected.some((item) => candidates.includes(item));
+			case "notin": return Array.isArray(candidates) && !selected.some((item) => candidates.includes(item));
+			default: return false;
+		}
+	}
+	/**
+	* Compares the chosen options against a condition value as sets, ignoring
+	* order and duplicates. A scalar condition value is read as a one-element
+	* set, so `{ op: 'eq', value: 'a' }` means "`a` is the only option chosen".
+	*/
+	sameSet(selected, expected) {
+		const expectedItems = Array.isArray(expected) ? expected : [expected];
+		const selectedSet = new Set(selected);
+		const expectedSet = new Set(expectedItems);
+		if (selectedSet.size !== expectedSet.size) return false;
+		for (const item of expectedSet) if (!selectedSet.has(item)) return false;
+		return true;
+	}
 	resolveIfDate(value, now) {
 		if (isRelativeDate(value)) return resolveRelativeDate(value, now);
 		return value;
@@ -402,6 +441,93 @@ var DependencyGraph = class DependencyGraph {
 	}
 };
 //#endregion
+//#region src/validators/array-obj-validator.ts
+const isRow = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Validates an `array_obj` field: the row list itself, then every sub-field of
+* every row.
+*
+* Sub-field errors keep the container's `fieldId` -- matching the key the
+* `fieldErrors` map stores them under -- and carry `itemIndex` (the row) plus
+* `itemFieldId` (the sub-field). A row-level `TYPE` error carries `itemIndex`
+* only.
+*/
+var ArrayObjValidator = class {
+	validate(ctx) {
+		const { fieldId, value, now } = ctx;
+		const { items, validateField } = ctx;
+		const validation = ctx.validation;
+		const errors = [];
+		if (value === null || value === void 0) return errors;
+		if (!Array.isArray(value)) {
+			errors.push({
+				fieldId,
+				rule: "TYPE",
+				message: "Must be an array",
+				params: { expectedType: "array" }
+			});
+			return errors;
+		}
+		if (validation?.minItems !== void 0 && value.length < validation.minItems) errors.push({
+			fieldId,
+			rule: "MIN_ITEMS",
+			message: `Must have at least ${validation.minItems} items`,
+			params: {
+				minItems: validation.minItems,
+				actual: value.length
+			}
+		});
+		if (validation?.maxItems !== void 0 && value.length > validation.maxItems) errors.push({
+			fieldId,
+			rule: "MAX_ITEMS",
+			message: `Must have at most ${validation.maxItems} items`,
+			params: {
+				maxItems: validation.maxItems,
+				actual: value.length
+			}
+		});
+		if (!items) return errors;
+		for (let i = 0; i < value.length; i++) {
+			const raw = value[i];
+			if (raw !== null && raw !== void 0 && !isRow(raw)) {
+				errors.push({
+					fieldId,
+					rule: "TYPE",
+					message: "Must be an object",
+					params: { expectedType: "object" },
+					itemIndex: i
+				});
+				continue;
+			}
+			const row = isRow(raw) ? raw : {};
+			for (const subField of items) {
+				if (subField.type === "static") continue;
+				const fakeEntry = {
+					id: subField.id,
+					type: subField.type,
+					condition: void 0,
+					validation: subField.validation,
+					parentId: fieldId,
+					options: subField.options,
+					item: void 0,
+					items: void 0,
+					label: subField.label,
+					title: void 0
+				};
+				const subErrors = validateField(subField.id, row[String(subField.id)], fakeEntry, now);
+				errors.push(...subErrors.map((err) => ({
+					...err,
+					fieldId,
+					itemIndex: i,
+					itemFieldId: subField.id,
+					message: `${subField.label}: ${err.message}`
+				})));
+			}
+		}
+		return errors;
+	}
+};
+//#endregion
 //#region src/validators/array-validator.ts
 var ArrayValidator = class {
 	validate(ctx) {
@@ -437,7 +563,7 @@ var ArrayValidator = class {
 				actual: value.length
 			}
 		});
-		if (item) for (let i = 0; i < value.length; i++) {
+		if (item && item.type !== "static") for (let i = 0; i < value.length; i++) {
 			const fakeEntry = {
 				id: fieldId,
 				type: item.type,
@@ -446,6 +572,7 @@ var ArrayValidator = class {
 				parentId: void 0,
 				options: item.options,
 				item: void 0,
+				items: void 0,
 				label: item.label,
 				title: void 0
 			};
@@ -459,6 +586,32 @@ var ArrayValidator = class {
 	}
 };
 //#endregion
+//#region src/validators/blockchain-validator.ts
+var BlockchainValidator = class {
+	validate(ctx) {
+		const { fieldId, value } = ctx;
+		const validation = ctx.validation;
+		const errors = [];
+		const isEmpty = value === null || value === void 0 || value === "";
+		if (validation?.required && isEmpty) {
+			errors.push({
+				fieldId,
+				rule: "REQUIRED",
+				message: "Value is required"
+			});
+			return errors;
+		}
+		if (isEmpty) return errors;
+		if (typeof value !== "string") errors.push({
+			fieldId,
+			rule: "TYPE",
+			message: "Must be a blockchain address string",
+			params: { expectedType: "blockchain" }
+		});
+		return errors;
+	}
+};
+//#endregion
 //#region src/validators/boolean-validator.ts
 var BooleanValidator = class {
 	validate(ctx) {
@@ -556,6 +709,51 @@ var FileValidator = class {
 	}
 };
 //#endregion
+//#region src/validators/multiselect-validator.ts
+/**
+* Validates `multiselect` fields, whose value is an array of the chosen
+* options' `value`s.
+*
+* An absent value and an empty array both count as "nothing selected", so both
+* fail `required`. Option membership is reported as a single field-level
+* `INVALID_OPTION` error rather than one error per offending element: the
+* viewer filters out errors carrying an `itemIndex` on the non-array render
+* path, so indexed errors would never be displayed.
+*/
+var MultiselectValidator = class {
+	validate(ctx) {
+		const { fieldId, value } = ctx;
+		const validation = ctx.validation;
+		const options = ctx.options;
+		const errors = [];
+		const isEmpty = value === null || value === void 0 || Array.isArray(value) && value.length === 0;
+		if (validation?.required && isEmpty) {
+			errors.push({
+				fieldId,
+				rule: "REQUIRED",
+				message: "Value is required"
+			});
+			return errors;
+		}
+		if (isEmpty) return errors;
+		if (!Array.isArray(value)) {
+			errors.push({
+				fieldId,
+				rule: "TYPE",
+				message: "Must be an array",
+				params: { expectedType: "multiselect" }
+			});
+			return errors;
+		}
+		if (options && value.some((selected) => !options.some((opt) => opt.value === selected))) errors.push({
+			fieldId,
+			rule: "INVALID_OPTION",
+			message: "Value is not a valid option"
+		});
+		return errors;
+	}
+};
+//#endregion
 //#region src/validators/number-validator.ts
 var NumberValidator = class {
 	validate(ctx) {
@@ -683,6 +881,53 @@ var StringValidator = class {
 	}
 };
 //#endregion
+//#region src/validators/sustainability-validator.ts
+const OPTIONAL_TEXT_PROPERTIES = ["ccri", "cmc"];
+var SustainabilityValidator = class {
+	validate(ctx) {
+		const { fieldId, value } = ctx;
+		const validation = ctx.validation;
+		const errors = [];
+		if (value === null || value === void 0) {
+			if (validation?.required) errors.push({
+				fieldId,
+				rule: "REQUIRED",
+				message: "Value is required"
+			});
+			return errors;
+		}
+		if (typeof value !== "object" || Array.isArray(value)) {
+			errors.push({
+				fieldId,
+				rule: "TYPE",
+				message: "Must be a valid sustainability object",
+				params: { expectedType: "sustainability" }
+			});
+			return errors;
+		}
+		const record = value;
+		const address = record.address ?? "";
+		if (typeof address !== "string" || OPTIONAL_TEXT_PROPERTIES.some((key) => !isOptionalText(record[key]))) {
+			errors.push({
+				fieldId,
+				rule: "TYPE",
+				message: "Must be a valid sustainability object",
+				params: { expectedType: "sustainability" }
+			});
+			return errors;
+		}
+		if (validation?.required && address === "") errors.push({
+			fieldId,
+			rule: "REQUIRED",
+			message: "Value is required"
+		});
+		return errors;
+	}
+};
+function isOptionalText(value) {
+	return value === void 0 || value === null || typeof value === "string";
+}
+//#endregion
 //#region src/field-validator.ts
 /**
 * Validates form values against the schema's validation rules.
@@ -699,9 +944,19 @@ var StringValidator = class {
 * - `date` -- `required`, `minDate`, `maxDate`. Relative date boundaries
 *   are resolved against `now`.
 * - `select` -- `required`, plus the value must be one of the defined options.
+* - `multiselect` -- `required` (an absent value and an empty array both fail),
+*   plus every selected value must be one of the defined options.
+* - `static` -- never validated; static blocks hold no value.
+* - `blockchain` -- `required` only. The CAIP address format is never checked.
+* - `sustainability` -- `required` (the value's `address` must be a non-empty
+*   string) plus a shape check; `ccri` and `cmc` are optional text.
 * - `array` -- `minItems`, `maxItems`, plus each item is validated
 *   individually according to the array's {@link ArrayItemDef}. Item-level
 *   errors carry an `itemIndex`.
+* - `array_obj` -- `minItems`, `maxItems`, plus every sub-field of every row is
+*   validated according to the field's {@link ArrayObjItemDef} list. Sub-field
+*   errors carry an `itemIndex` (the row) and an `itemFieldId` (the sub-field),
+*   while `fieldId` stays the container's id.
 *
 * 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
@@ -721,8 +976,12 @@ var FieldValidator = class {
 			boolean: new BooleanValidator(),
 			date: new DateValidator(),
 			select: new SelectValidator(),
+			multiselect: new MultiselectValidator(),
 			array: new ArrayValidator(),
-			file: new FileValidator()
+			array_obj: new ArrayObjValidator(),
+			file: new FileValidator(),
+			blockchain: new BlockchainValidator(),
+			sustainability: new SustainabilityValidator()
 		};
 	}
 	/**
@@ -763,6 +1022,17 @@ var FieldValidator = class {
 			};
 			return validator.validate(ctx);
 		}
+		if (entry.type === "array_obj") {
+			const ctx = {
+				fieldId,
+				value,
+				validation: entry.validation,
+				now,
+				items: entry.items,
+				validateField: this.validateField.bind(this)
+			};
+			return validator.validate(ctx);
+		}
 		return validator.validate({
 			fieldId,
 			value,
@@ -817,11 +1087,17 @@ var FormDefinitionEditor = class {
 	}
 	/**
 	* Returns the next available numeric id (max existing + 1).
+	*
+	* `array_obj` sub-field ids share the form-wide id space, so they count
+	* here too -- otherwise a new top-level field could collide with one.
 	*/
 	nextId() {
 		let max = 0;
 		this.walkAll(this.definition.content, (item) => {
 			if (item.id > max) max = item.id;
+			if (item.type === "array_obj") {
+				for (const subField of item.items ?? []) if (subField.id > max) max = subField.id;
+			}
 		});
 		return max + 1;
 	}
@@ -960,6 +1236,7 @@ var FormDefinitionEditor = class {
 		const item = this.findItem(id);
 		if (!item) throw new Error(`Item with id ${id} not found`);
 		if (item.type === "section") throw new Error("Sections do not have validation");
+		if (item.type === "static") throw new Error("Static fields do not have validation");
 		const field = item;
 		if (validation === void 0) delete field.validation;
 		else field.validation = validation;
@@ -976,12 +1253,12 @@ var FormDefinitionEditor = class {
 		return this;
 	}
 	/**
-	* Sets the select options for a `select` field.
+	* Sets the options for a `select` or `multiselect` field.
 	*/
 	setOptions(id, options) {
 		const item = this.findItem(id);
 		if (!item) throw new Error(`Item with id ${id} not found`);
-		if (item.type !== "select") throw new Error(`Field ${id} is not a select field`);
+		if (item.type !== "select" && item.type !== "multiselect") throw new Error(`Field ${id} is not a select or multiselect field`);
 		const field = item;
 		field.options = options;
 		return this;
@@ -998,6 +1275,94 @@ var FormDefinitionEditor = class {
 		return this;
 	}
 	/**
+	* Replaces the whole sub-field list of an `array_obj` field.
+	*
+	* @throws If the id is not found or does not refer to an `array_obj` field.
+	*/
+	setArrayItems(id, itemDefs) {
+		this.assertArrayObjField(id).items = itemDefs;
+		return this;
+	}
+	/**
+	* Returns the sub-field list of an `array_obj` field.
+	*
+	* @throws If the id is not found or does not refer to an `array_obj` field.
+	*/
+	getArrayItems(id) {
+		return this.assertArrayObjField(id).items ?? [];
+	}
+	/**
+	* Sets or clears the layout hint of an `array_obj` field.
+	*
+	* Presentation metadata only -- the engine never reads it. Passing
+	* `undefined` removes the key, which reads as `'list'`.
+	*
+	* @throws If the id is not found or does not refer to an `array_obj` field.
+	*/
+	setArrayKind(id, kind) {
+		const field = this.assertArrayObjField(id);
+		if (kind === void 0) delete field.kind;
+		else field.kind = kind;
+		return this;
+	}
+	/**
+	* Appends a sub-field to an `array_obj` field. The sub-field's `id` is
+	* auto-assigned when omitted.
+	*
+	* @returns The id of the sub-field that was added.
+	* @throws If the id is not found, does not refer to an `array_obj` field,
+	*   or the requested sub-field id is already taken.
+	*/
+	addArrayItemField(id, subField) {
+		const field = this.assertArrayObjField(id);
+		const subFieldId = subField.id ?? this.nextId();
+		this.assertIdAvailable(subFieldId);
+		field.items?.push({
+			...subField,
+			id: subFieldId
+		});
+		return subFieldId;
+	}
+	/**
+	* Merges properties into an existing `array_obj` sub-field.
+	*
+	* Like {@link updateField}, omitted properties are kept rather than
+	* removed -- pass a property explicitly as `undefined` to clear it.
+	*
+	* @throws If the field or the sub-field is not found.
+	*/
+	updateArrayItemField(id, subFieldId, patch) {
+		const subField = this.assertArrayObjField(id).items?.find((f) => f.id === subFieldId);
+		if (!subField) throw new Error(`Sub-field with id ${subFieldId} not found in field ${id}`);
+		Object.assign(subField, patch, { id: subFieldId });
+		return this;
+	}
+	/**
+	* Removes a sub-field from an `array_obj` field.
+	*
+	* @throws If the field or the sub-field is not found.
+	*/
+	removeArrayItemField(id, subFieldId) {
+		const field = this.assertArrayObjField(id);
+		const index = field.items?.findIndex((f) => f.id === subFieldId) ?? -1;
+		if (index < 0) throw new Error(`Sub-field with id ${subFieldId} not found in field ${id}`);
+		field.items?.splice(index, 1);
+		return this;
+	}
+	/**
+	* Moves a sub-field of an `array_obj` field to another position.
+	*
+	* @throws If the field is not found or either index is out of range.
+	*/
+	moveArrayItemField(id, fromIndex, toIndex) {
+		const items = this.assertArrayObjField(id).items ?? [];
+		if (fromIndex < 0 || fromIndex >= items.length) throw new Error(`Index ${fromIndex} out of range`);
+		if (toIndex < 0 || toIndex >= items.length) throw new Error(`Index ${toIndex} out of range`);
+		const [moved] = items.splice(fromIndex, 1);
+		if (moved) items.splice(toIndex, 0, moved);
+		return this;
+	}
+	/**
 	* Sets the label for a field.
 	*/
 	setLabel(id, label) {
@@ -1009,6 +1374,18 @@ var FormDefinitionEditor = class {
 		return this;
 	}
 	/**
+	* Sets the displayed text of a `static` field.
+	*
+	* @throws If the id is not found or does not refer to a static field.
+	*/
+	setText(id, text) {
+		const item = this.findItem(id);
+		if (!item) throw new Error(`Item with id ${id} not found`);
+		if (item.type !== "static") throw new Error(`Field ${id} is not a static field`);
+		item.text = text;
+		return this;
+	}
+	/**
 	* Sets the description for a field or section.
 	*/
 	setFieldDescription(id, description) {
@@ -1019,6 +1396,41 @@ var FormDefinitionEditor = class {
 		return this;
 	}
 	/**
+	* Sets the placeholder for a field or section.
+	*
+	* Passing `undefined` removes the property. Unlike {@link updateField},
+	* which merges and therefore cannot clear, this genuinely deletes the key.
+	*/
+	setPlaceholder(id, placeholder) {
+		return this.setMetadata(id, "placeholder", placeholder);
+	}
+	/**
+	* Sets the answer guidelines for a field or section.
+	*
+	* Passing `undefined` removes the property.
+	*/
+	setAnswerGuidelines(id, answerGuidelines) {
+		return this.setMetadata(id, "answer_guidelines", answerGuidelines);
+	}
+	/**
+	* Sets the external reference id for a field or section.
+	*
+	* Passing `undefined` removes the property.
+	*/
+	setReferenceId(id, referenceId) {
+		return this.setMetadata(id, "reference_id", referenceId);
+	}
+	/**
+	* Assigns or deletes one optional string property on a field or section.
+	*/
+	setMetadata(id, property, value) {
+		const item = this.findItem(id);
+		if (!item) throw new Error(`Item with id ${id} not found`);
+		if (value === void 0) delete item[property];
+		else item[property] = value;
+		return this;
+	}
+	/**
 	* Returns a deep clone of the current form definition.
 	*/
 	toJSON() {
@@ -1033,6 +1445,30 @@ var FormDefinitionEditor = class {
 	}
 	assertIdAvailable(id) {
 		if (this.findItem(id)) throw new Error(`Item with id ${id} already exists`);
+		if (this.findArrayObjItem(id)) throw new Error(`Item with id ${id} already exists`);
+	}
+	/**
+	* Finds an `array_obj` sub-field anywhere in the definition by its id.
+	*/
+	findArrayObjItem(id) {
+		let found;
+		this.walkAll(this.definition.content, (item) => {
+			if (found || item.type !== "array_obj") return;
+			const subField = (item.items ?? []).find((f) => f.id === id);
+			if (subField) found = {
+				field: item,
+				subField
+			};
+		});
+		return found;
+	}
+	assertArrayObjField(id) {
+		const item = this.findItem(id);
+		if (!item) throw new Error(`Item with id ${id} not found`);
+		if (item.type !== "array_obj") throw new Error(`Field ${id} is not an array_obj field`);
+		const field = item;
+		if (!field.items) field.items = [];
+		return field;
 	}
 	insertItem(item, parentId, index) {
 		const target = this.getTargetContent(parentId);
@@ -1244,6 +1680,11 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 			"properties": { "required": { "type": "boolean" } },
 			"additionalProperties": false
 		},
+		"multiselectValidation": {
+			"type": "object",
+			"properties": { "required": { "type": "boolean" } },
+			"additionalProperties": false
+		},
 		"arrayValidation": {
 			"type": "object",
 			"properties": {
@@ -1258,11 +1699,35 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 			},
 			"additionalProperties": false
 		},
+		"arrayObjValidation": {
+			"type": "object",
+			"properties": {
+				"minItems": {
+					"type": "integer",
+					"minimum": 0
+				},
+				"maxItems": {
+					"type": "integer",
+					"minimum": 1
+				}
+			},
+			"additionalProperties": false
+		},
 		"fileValidation": {
 			"type": "object",
 			"properties": { "required": { "type": "boolean" } },
 			"additionalProperties": false
 		},
+		"blockchainValidation": {
+			"type": "object",
+			"properties": { "required": { "type": "boolean" } },
+			"additionalProperties": false
+		},
+		"sustainabilityValidation": {
+			"type": "object",
+			"properties": { "required": { "type": "boolean" } },
+			"additionalProperties": false
+		},
 		"selectOption": {
 			"type": "object",
 			"required": ["value", "label"],
@@ -1279,6 +1744,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "string" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"validation": { "$ref": "#/$defs/stringValidation" }
 			},
 			"additionalProperties": false
@@ -1290,6 +1758,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "number" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"validation": { "$ref": "#/$defs/numberValidation" }
 			},
 			"additionalProperties": false
@@ -1301,6 +1772,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "boolean" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"validation": { "$ref": "#/$defs/booleanValidation" }
 			},
 			"additionalProperties": false
@@ -1312,6 +1786,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "date" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"validation": { "$ref": "#/$defs/dateValidation" }
 			},
 			"additionalProperties": false
@@ -1327,6 +1804,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "select" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"options": {
 					"type": "array",
 					"minItems": 1,
@@ -1343,21 +1823,337 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "file" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"validation": { "$ref": "#/$defs/fileValidation" }
 			},
 			"additionalProperties": false
 		},
-		"arrayItem": { "oneOf": [
-			{ "$ref": "#/$defs/arrayItemString" },
-			{ "$ref": "#/$defs/arrayItemNumber" },
-			{ "$ref": "#/$defs/arrayItemBoolean" },
-			{ "$ref": "#/$defs/arrayItemDate" },
-			{ "$ref": "#/$defs/arrayItemSelect" },
-			{ "$ref": "#/$defs/arrayItemFile" }
-		] },
-		"stringField": {
+		"arrayItemBlockchain": {
 			"type": "object",
-			"required": [
+			"required": ["type", "label"],
+			"properties": {
+				"type": { "const": "blockchain" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"validation": { "$ref": "#/$defs/blockchainValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayItemSustainability": {
+			"type": "object",
+			"required": ["type", "label"],
+			"properties": {
+				"type": { "const": "sustainability" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"validation": { "$ref": "#/$defs/sustainabilityValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayItemMultiselect": {
+			"type": "object",
+			"required": [
+				"type",
+				"label",
+				"options"
+			],
+			"properties": {
+				"type": { "const": "multiselect" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"options": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/selectOption" }
+				},
+				"validation": { "$ref": "#/$defs/multiselectValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayItemStatic": {
+			"type": "object",
+			"required": ["type", "text"],
+			"properties": {
+				"type": { "const": "static" },
+				"text": { "type": "string" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" }
+			},
+			"additionalProperties": false
+		},
+		"arrayItem": { "oneOf": [
+			{ "$ref": "#/$defs/arrayItemString" },
+			{ "$ref": "#/$defs/arrayItemNumber" },
+			{ "$ref": "#/$defs/arrayItemBoolean" },
+			{ "$ref": "#/$defs/arrayItemDate" },
+			{ "$ref": "#/$defs/arrayItemSelect" },
+			{ "$ref": "#/$defs/arrayItemFile" },
+			{ "$ref": "#/$defs/arrayItemBlockchain" },
+			{ "$ref": "#/$defs/arrayItemSustainability" },
+			{ "$ref": "#/$defs/arrayItemMultiselect" },
+			{ "$ref": "#/$defs/arrayItemStatic" }
+		] },
+		"arrayObjItemString": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "string" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"validation": { "$ref": "#/$defs/stringValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItemNumber": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "number" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"validation": { "$ref": "#/$defs/numberValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItemBoolean": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "boolean" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"validation": { "$ref": "#/$defs/booleanValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItemDate": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "date" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"validation": { "$ref": "#/$defs/dateValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItemSelect": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label",
+				"options"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "select" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"options": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/selectOption" }
+				},
+				"validation": { "$ref": "#/$defs/selectValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItemMultiselect": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label",
+				"options"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "multiselect" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"options": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/selectOption" }
+				},
+				"validation": { "$ref": "#/$defs/multiselectValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItemFile": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "file" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"validation": { "$ref": "#/$defs/fileValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItemBlockchain": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "blockchain" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"validation": { "$ref": "#/$defs/blockchainValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItemSustainability": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "sustainability" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"validation": { "$ref": "#/$defs/sustainabilityValidation" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItemStatic": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"text"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "static" },
+				"text": { "type": "string" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" }
+			},
+			"additionalProperties": false
+		},
+		"arrayObjItem": { "oneOf": [
+			{ "$ref": "#/$defs/arrayObjItemString" },
+			{ "$ref": "#/$defs/arrayObjItemNumber" },
+			{ "$ref": "#/$defs/arrayObjItemBoolean" },
+			{ "$ref": "#/$defs/arrayObjItemDate" },
+			{ "$ref": "#/$defs/arrayObjItemSelect" },
+			{ "$ref": "#/$defs/arrayObjItemMultiselect" },
+			{ "$ref": "#/$defs/arrayObjItemFile" },
+			{ "$ref": "#/$defs/arrayObjItemBlockchain" },
+			{ "$ref": "#/$defs/arrayObjItemSustainability" },
+			{ "$ref": "#/$defs/arrayObjItemStatic" }
+		] },
+		"stringField": {
+			"type": "object",
+			"required": [
 				"id",
 				"type",
 				"label"
@@ -1370,6 +2166,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "string" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"condition": { "$ref": "#/$defs/condition" },
 				"validation": { "$ref": "#/$defs/stringValidation" }
 			},
@@ -1390,6 +2189,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "number" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"condition": { "$ref": "#/$defs/condition" },
 				"validation": { "$ref": "#/$defs/numberValidation" }
 			},
@@ -1410,6 +2212,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "boolean" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"condition": { "$ref": "#/$defs/condition" },
 				"validation": { "$ref": "#/$defs/booleanValidation" }
 			},
@@ -1430,6 +2235,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "date" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"condition": { "$ref": "#/$defs/condition" },
 				"validation": { "$ref": "#/$defs/dateValidation" }
 			},
@@ -1451,6 +2259,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "select" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"condition": { "$ref": "#/$defs/condition" },
 				"options": {
 					"type": "array",
@@ -1461,6 +2272,58 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 			},
 			"additionalProperties": false
 		},
+		"multiselectField": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label",
+				"options"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "multiselect" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"condition": { "$ref": "#/$defs/condition" },
+				"options": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/selectOption" }
+				},
+				"validation": { "$ref": "#/$defs/multiselectValidation" }
+			},
+			"additionalProperties": false
+		},
+		"staticField": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"text"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "static" },
+				"text": { "type": "string" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"condition": { "$ref": "#/$defs/condition" }
+			},
+			"additionalProperties": false
+		},
 		"arrayField": {
 			"type": "object",
 			"required": [
@@ -1477,12 +2340,48 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "array" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"condition": { "$ref": "#/$defs/condition" },
 				"item": { "$ref": "#/$defs/arrayItem" },
 				"validation": { "$ref": "#/$defs/arrayValidation" }
 			},
 			"additionalProperties": false
 		},
+		"arrayObjField": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label",
+				"items"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "array_obj" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"condition": { "$ref": "#/$defs/condition" },
+				"items": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/arrayObjItem" }
+				},
+				"kind": {
+					"type": "string",
+					"enum": ["list", "table"]
+				},
+				"validation": { "$ref": "#/$defs/arrayObjValidation" }
+			},
+			"additionalProperties": false
+		},
 		"fileField": {
 			"type": "object",
 			"required": [
@@ -1498,19 +2397,73 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "file" },
 				"label": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"condition": { "$ref": "#/$defs/condition" },
 				"validation": { "$ref": "#/$defs/fileValidation" }
 			},
 			"additionalProperties": false
 		},
+		"blockchainField": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "blockchain" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"condition": { "$ref": "#/$defs/condition" },
+				"validation": { "$ref": "#/$defs/blockchainValidation" }
+			},
+			"additionalProperties": false
+		},
+		"sustainabilityField": {
+			"type": "object",
+			"required": [
+				"id",
+				"type",
+				"label"
+			],
+			"properties": {
+				"id": {
+					"type": "integer",
+					"minimum": 1
+				},
+				"type": { "const": "sustainability" },
+				"label": { "type": "string" },
+				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
+				"condition": { "$ref": "#/$defs/condition" },
+				"validation": { "$ref": "#/$defs/sustainabilityValidation" }
+			},
+			"additionalProperties": false
+		},
 		"fieldItem": { "oneOf": [
 			{ "$ref": "#/$defs/stringField" },
 			{ "$ref": "#/$defs/numberField" },
 			{ "$ref": "#/$defs/booleanField" },
 			{ "$ref": "#/$defs/dateField" },
 			{ "$ref": "#/$defs/selectField" },
+			{ "$ref": "#/$defs/multiselectField" },
 			{ "$ref": "#/$defs/arrayField" },
-			{ "$ref": "#/$defs/fileField" }
+			{ "$ref": "#/$defs/arrayObjField" },
+			{ "$ref": "#/$defs/fileField" },
+			{ "$ref": "#/$defs/staticField" },
+			{ "$ref": "#/$defs/blockchainField" },
+			{ "$ref": "#/$defs/sustainabilityField" }
 		] },
 		"section": {
 			"type": "object",
@@ -1528,6 +2481,9 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 				"type": { "const": "section" },
 				"title": { "type": "string" },
 				"description": { "type": "string" },
+				"placeholder": { "type": "string" },
+				"answer_guidelines": { "type": "string" },
+				"reference_id": { "type": "string" },
 				"condition": { "$ref": "#/$defs/condition" },
 				"content": {
 					"type": "array",
@@ -1540,6 +2496,228 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 		"contentItem": { "oneOf": [{ "$ref": "#/$defs/fieldItem" }, { "$ref": "#/$defs/section" }] }
 	}
 });
+const itemRequiredProperties = new Map([
+	["string", new Set([
+		"id",
+		"type",
+		"label"
+	])],
+	["number", new Set([
+		"id",
+		"type",
+		"label"
+	])],
+	["boolean", new Set([
+		"id",
+		"type",
+		"label"
+	])],
+	["date", new Set([
+		"id",
+		"type",
+		"label"
+	])],
+	["select", new Set([
+		"id",
+		"type",
+		"label",
+		"options"
+	])],
+	["multiselect", new Set([
+		"id",
+		"type",
+		"label",
+		"options"
+	])],
+	["array", new Set([
+		"id",
+		"type",
+		"label",
+		"item"
+	])],
+	["array_obj", new Set([
+		"id",
+		"type",
+		"label",
+		"items"
+	])],
+	["file", new Set([
+		"id",
+		"type",
+		"label"
+	])],
+	["blockchain", new Set([
+		"id",
+		"type",
+		"label"
+	])],
+	["sustainability", new Set([
+		"id",
+		"type",
+		"label"
+	])],
+	["static", new Set([
+		"id",
+		"type",
+		"text"
+	])],
+	["section", new Set([
+		"id",
+		"type",
+		"title",
+		"content"
+	])]
+]);
+const itemAllowedProperties = new Map([
+	["string", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"validation"
+	])],
+	["number", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"validation"
+	])],
+	["boolean", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"validation"
+	])],
+	["date", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"validation"
+	])],
+	["select", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"options",
+		"validation"
+	])],
+	["multiselect", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"options",
+		"validation"
+	])],
+	["array", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"item",
+		"validation"
+	])],
+	["array_obj", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"items",
+		"kind",
+		"validation"
+	])],
+	["file", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"validation"
+	])],
+	["blockchain", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"validation"
+	])],
+	["sustainability", new Set([
+		"id",
+		"type",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"validation"
+	])],
+	["static", new Set([
+		"id",
+		"type",
+		"text",
+		"label",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition"
+	])],
+	["section", new Set([
+		"id",
+		"type",
+		"title",
+		"description",
+		"placeholder",
+		"answer_guidelines",
+		"reference_id",
+		"condition",
+		"content"
+	])]
+]);
 /**
 * Validates form definitions at both the structural (JSON Schema) and
 * semantic levels.
@@ -1553,12 +2731,17 @@ const validateFn = new ajv_dist_2020.default({ allErrors: true }).compile({
 * ### 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.
+*    `array_obj` sub-field ids share that id space and are checked with it.
 * 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.
+* 4. **Condition references a valueless item** (`CONDITION_REFS_SECTION`,
+*    `CONDITION_REFS_STATIC`) -- conditions must not reference section or
+*    static ids, because neither holds a value.
+* 4b. **Condition references an `array_obj` sub-field** (`CONDITION_REFS_ARRAY_OBJ_ITEM`)
+*    -- a sub-field holds one value per row, so a form-level condition cannot
+*    say which row it means.
 * 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
@@ -1573,18 +2756,177 @@ var FormDefinitionValidator = class {
 	*/
 	validateSchema(input) {
 		if (validateFn(input)) return [];
-		return (validateFn.errors ?? []).map((err) => {
+		return this.formatSchemaErrors(validateFn.errors ?? [], input);
+	}
+	formatSchemaErrors(errors, input) {
+		const issues = this.collectSchemaIssues(errors, input);
+		const dedupedIssues = this.deduplicateSchemaIssues(issues);
+		const specificIssuePaths = dedupedIssues.filter((issue) => issue.keyword !== "oneOf").map((issue) => issue.path);
+		return dedupedIssues.filter((issue) => !this.isRedundantOneOfIssue(issue, specificIssuePaths)).map((issue) => ({
+			code: "SCHEMA_INVALID",
+			message: issue.message,
+			params: {
+				path: issue.path,
+				keyword: issue.keyword,
+				...issue.property ? { property: issue.property } : {}
+			}
+		}));
+	}
+	collectSchemaIssues(errors, input) {
+		const additionalByPath = /* @__PURE__ */ new Map();
+		const issues = [];
+		for (const err of errors) {
 			const path = err.instancePath || "/";
-			const message = err.message ?? "Unknown error";
-			if (err.keyword === "additionalProperties") return {
-				code: "SCHEMA_INVALID",
-				message: `${path}: ${message}: '${err.params.additionalProperty}'`
+			if (!this.shouldKeepSchemaError(err, input)) continue;
+			if (err.keyword === "additionalProperties") {
+				const property = err.params.additionalProperty;
+				if (!property) continue;
+				if (!this.shouldKeepAdditionalPropertyError(path, property, input)) continue;
+				const properties = additionalByPath.get(path) ?? /* @__PURE__ */ new Set();
+				properties.add(property);
+				additionalByPath.set(path, properties);
+				continue;
+			}
+			issues.push(this.formatSchemaIssue(err));
+		}
+		for (const [path, properties] of additionalByPath) issues.push(this.formatAdditionalPropertiesIssue(path, [...properties].sort()));
+		return issues;
+	}
+	shouldKeepSchemaError(err, input) {
+		if (err.keyword === "const" && this.getLastPathSegment(err.instancePath) === "type") {
+			const value = this.getValueAtPath(input, this.getParentPath(err.instancePath));
+			return !(this.isRecord(value) && typeof value.type === "string" && itemAllowedProperties.has(value.type));
+		}
+		if (err.keyword !== "required") return true;
+		const missingProperty = err.params.missingProperty;
+		if (!missingProperty) return true;
+		const value = this.getValueAtPath(input, err.instancePath);
+		if (this.isRecord(value) && value.type === void 0 && this.isContentItemPath(err.instancePath)) return missingProperty === "id" || missingProperty === "type";
+		if (!this.isRecord(value) || typeof value.type !== "string") return true;
+		const requiredProperties = itemRequiredProperties.get(value.type);
+		return requiredProperties ? requiredProperties.has(missingProperty) : true;
+	}
+	shouldKeepAdditionalPropertyError(path, property, input) {
+		const value = this.getValueAtPath(input, path);
+		if (!this.isRecord(value) || typeof value.type !== "string") return true;
+		const allowedProperties = itemAllowedProperties.get(value.type);
+		return allowedProperties ? !allowedProperties.has(property) : true;
+	}
+	formatSchemaIssue(err) {
+		const path = err.instancePath || "/";
+		switch (err.keyword) {
+			case "required": {
+				const property = err.params.missingProperty ?? "unknown";
+				return {
+					path,
+					keyword: err.keyword,
+					property,
+					message: `${this.formatPath(path)} is missing required property "${property}".`
+				};
+			}
+			case "const": {
+				const propertyPath = this.formatPath(path);
+				const parentPath = this.getParentPath(path);
+				const property = this.getLastPathSegment(path);
+				return {
+					path,
+					keyword: err.keyword,
+					property,
+					message: property === "type" ? `${this.formatPath(parentPath)} has an invalid type.` : `${propertyPath} has an invalid value.`
+				};
+			}
+			case "type": {
+				const params = err.params;
+				return {
+					path,
+					keyword: err.keyword,
+					property: this.getLastPathSegment(path),
+					message: `${this.formatPath(path)} must be ${this.formatArticle(params.type)} ${params.type ?? "valid value"}.`
+				};
+			}
+			case "oneOf": return {
+				path,
+				keyword: err.keyword,
+				message: `${this.formatPath(path)} is invalid.`
 			};
-			return {
-				code: "SCHEMA_INVALID",
-				message: `${path}: ${message}`
+			default: return {
+				path,
+				keyword: err.keyword,
+				property: this.getLastPathSegment(path),
+				message: `${this.formatPath(path)} ${err.message ?? "is invalid"}.`
 			};
-		});
+		}
+	}
+	formatAdditionalPropertiesIssue(path, properties) {
+		const propertyList = properties.map((property) => `"${property}"`).join(", ");
+		const noun = properties.length === 1 ? "property" : "properties";
+		return {
+			path,
+			keyword: "additionalProperties",
+			property: properties.join(","),
+			message: `${this.formatPath(path)} has unsupported ${noun}: ${propertyList}.`
+		};
+	}
+	deduplicateSchemaIssues(issues) {
+		const seen = /* @__PURE__ */ new Set();
+		const result = [];
+		for (const issue of issues) {
+			const key = `${issue.path}:${issue.keyword}:${issue.property ?? ""}:${issue.message}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			result.push(issue);
+		}
+		return result;
+	}
+	isRedundantOneOfIssue(issue, specificIssuePaths) {
+		if (issue.keyword !== "oneOf") return false;
+		return specificIssuePaths.some((path) => path === issue.path || path.startsWith(`${issue.path}/`));
+	}
+	formatPath(path) {
+		if (!path || path === "/") return "Form definition";
+		const segments = path.split("/").filter(Boolean);
+		const parts = [];
+		for (let index = 0; index < segments.length; index += 1) {
+			const segment = segments[index];
+			const nextSegment = segments[index + 1];
+			if (segment === void 0) continue;
+			if (segment === "content" && nextSegment !== void 0 && /^\d+$/.test(nextSegment)) {
+				parts.push(`${parts.length === 0 ? "Content" : "content"} item ${Number(nextSegment) + 1}`);
+				index += 1;
+				continue;
+			}
+			if (segment === "validation" && parts.length > 0) {
+				parts[parts.length - 1] = `${parts[parts.length - 1]} validation`;
+				continue;
+			}
+			parts.push(segment);
+		}
+		return parts.join(" > ");
+	}
+	getValueAtPath(input, path) {
+		if (!path) return input;
+		return path.split("/").filter(Boolean).reduce((value, segment) => {
+			if (Array.isArray(value)) return value[Number(segment)];
+			if (this.isRecord(value)) return value[segment];
+		}, input);
+	}
+	getParentPath(path) {
+		const segments = path.split("/").filter(Boolean);
+		return segments.length > 1 ? `/${segments.slice(0, -1).join("/")}` : "/";
+	}
+	getLastPathSegment(path) {
+		return path.split("/").filter(Boolean).at(-1);
+	}
+	isContentItemPath(path) {
+		const segments = path.split("/").filter(Boolean);
+		return segments.at(-2) === "content" && /^\d+$/.test(segments.at(-1) ?? "");
+	}
+	formatArticle(value) {
+		if (!value) return "a";
+		return /^[aeiou]/i.test(value) ? "an" : "a";
+	}
+	isRecord(value) {
+		return typeof value === "object" && value !== null && !Array.isArray(value);
 	}
 	/**
 	* Validates a form definition semantically.
@@ -1597,23 +2939,52 @@ var FormDefinitionValidator = class {
 		const issues = [];
 		this.checkDuplicateIds(definition.content, issues);
 		this.checkNestingDepth(definition.content, 0, issues);
-		this.checkConditionRefs(registry, issues);
-		this.checkConditionRefsSection(registry, issues);
+		const arrayObjItemIds = this.collectArrayObjItemIds(definition.content);
+		this.checkConditionRefsArrayObjItem(registry, arrayObjItemIds, issues);
+		this.checkConditionRefs(registry, arrayObjItemIds, issues);
+		this.checkConditionRefsValueless(registry, issues);
 		this.checkConstraintContradictions(registry, issues);
 		this.checkInvalidRegex(registry, issues);
 		return issues;
 	}
 	checkDuplicateIds(content, issues) {
 		const seen = /* @__PURE__ */ new Set();
-		this.walkItems(content, (item) => {
-			if (seen.has(item.id)) issues.push({
+		const record = (id) => {
+			if (seen.has(id)) issues.push({
 				code: "DUPLICATE_ID",
-				message: `Duplicate id: ${item.id}`,
-				itemId: item.id
+				message: `Duplicate id: ${id}`,
+				itemId: id
 			});
-			else seen.add(item.id);
+			else seen.add(id);
+		};
+		this.walkItems(content, (item) => {
+			record(item.id);
+			if (item.type === "array_obj") for (const subField of item.items ?? []) record(subField.id);
 		});
 	}
+	collectArrayObjItemIds(content) {
+		const ids = /* @__PURE__ */ new Map();
+		this.walkItems(content, (item) => {
+			if (item.type !== "array_obj") return;
+			for (const subField of item.items ?? []) if (!ids.has(subField.id)) ids.set(subField.id, item.id);
+		});
+		return ids;
+	}
+	checkConditionRefsArrayObjItem(registry, arrayObjItemIds, issues) {
+		if (arrayObjItemIds.size === 0) return;
+		for (const [id, entry] of registry) {
+			if (!entry.condition) continue;
+			for (const ref of DependencyGraph.extractFieldRefs(entry.condition)) {
+				const containerId = arrayObjItemIds.get(ref);
+				if (containerId === void 0) continue;
+				issues.push({
+					code: "CONDITION_REFS_ARRAY_OBJ_ITEM",
+					message: `Condition references sub-field ${ref} of array_obj field ${containerId}, whose value is per-row and not addressable (in item ${id})`,
+					itemId: id
+				});
+			}
+		}
+	}
 	checkNestingDepth(content, depth, issues) {
 		for (const item of content) if (item.type === "section") if (depth >= 3) issues.push({
 			code: "NESTING_DEPTH",
@@ -1622,28 +2993,37 @@ var FormDefinitionValidator = class {
 		});
 		else this.checkNestingDepth(item.content, depth + 1, issues);
 	}
-	checkConditionRefs(registry, issues) {
+	checkConditionRefs(registry, arrayObjItemIds, issues) {
 		for (const [id, entry] of registry) {
 			if (!entry.condition) continue;
 			const refs = DependencyGraph.extractFieldRefs(entry.condition);
-			for (const ref of refs) if (!registry.has(ref)) issues.push({
-				code: "UNKNOWN_FIELD_REF",
-				message: `Condition references unknown field: ${ref} (in item ${id})`,
-				itemId: id
-			});
+			for (const ref of refs) {
+				if (arrayObjItemIds.has(ref)) continue;
+				if (!registry.has(ref)) issues.push({
+					code: "UNKNOWN_FIELD_REF",
+					message: `Condition references unknown field: ${ref} (in item ${id})`,
+					itemId: id
+				});
+			}
 		}
 	}
-	checkConditionRefsSection(registry, issues) {
+	checkConditionRefsValueless(registry, issues) {
 		for (const [id, entry] of registry) {
 			if (!entry.condition) continue;
 			const refs = DependencyGraph.extractFieldRefs(entry.condition);
 			for (const ref of refs) {
 				const refEntry = registry.get(ref);
-				if (refEntry && refEntry.type === "section") issues.push({
+				if (!refEntry) continue;
+				if (refEntry.type === "section") issues.push({
 					code: "CONDITION_REFS_SECTION",
 					message: `Condition references section ${ref}, which has no value (in item ${id})`,
 					itemId: id
 				});
+				if (refEntry.type === "static") issues.push({
+					code: "CONDITION_REFS_STATIC",
+					message: `Condition references static field ${ref}, which has no value (in item ${id})`,
+					itemId: id
+				});
 			}
 		}
 	}
@@ -1684,7 +3064,8 @@ var FormDefinitionValidator = class {
 					}
 					break;
 				}
-				case "array": {
+				case "array":
+				case "array_obj": {
 					const v = entry.validation;
 					if (v.minItems !== void 0 && v.maxItems !== void 0 && v.maxItems < v.minItems) issues.push({
 						code: "INVALID_MIN_MAX",
@@ -1770,6 +3151,7 @@ var VisibilityResolver = class {
 	registry;
 	conditionEvaluator;
 	topologicalOrder;
+	fieldTypes;
 	/**
 	* @param registry - The engine's field registry.
 	* @param conditionEvaluator - Evaluator for condition trees.
@@ -1779,6 +3161,7 @@ var VisibilityResolver = class {
 		this.registry = registry;
 		this.conditionEvaluator = conditionEvaluator;
 		this.topologicalOrder = topologicalOrder;
+		this.fieldTypes = new Map([...registry].map(([id, entry]) => [id, entry.type]));
 	}
 	/**
 	* Determines whether a single field or section is visible.
@@ -1805,7 +3188,8 @@ var VisibilityResolver = class {
 		if (entry.condition) {
 			if (!this.conditionEvaluator.evalCondition(entry.condition, {
 				values,
-				now
+				now,
+				fieldTypes: this.fieldTypes
 			})) return false;
 		}
 		if (entry.parentId !== void 0) return this.isVisible(entry.parentId, values, now);
@@ -1843,7 +3227,8 @@ var VisibilityResolver = class {
 				const visible = this.conditionEvaluator.evalCondition(entry.condition, {
 					values,
 					visibilityMap: result,
-					now
+					now,
+					fieldTypes: this.fieldTypes
 				});
 				result.set(id, visible);
 			} else result.set(id, true);
@@ -2110,14 +3495,16 @@ var FormEngine = class FormEngine {
 	}
 	static walkContent(content, parentId, registry, contentOrder) {
 		for (const item of content) {
+			const isValueField = item.type !== "section" && item.type !== "static";
 			const entry = {
 				id: item.id,
 				type: item.type,
 				condition: item.condition,
-				validation: item.type !== "section" ? item.validation : void 0,
+				validation: isValueField ? item.validation : void 0,
 				parentId,
-				options: item.type === "select" ? item.options : void 0,
+				options: item.type === "select" || item.type === "multiselect" ? item.options : void 0,
 				item: item.type === "array" ? item.item : void 0,
+				items: item.type === "array_obj" ? item.items : void 0,
 				label: item.type !== "section" ? item.label : void 0,
 				title: item.type === "section" ? item.title : void 0
 			};
@@ -2128,6 +3515,108 @@ var FormEngine = class FormEngine {
 	}
 };
 //#endregion
+//#region src/suggestions.ts
+/**
+* Pure helpers for reading and writing the `suggestions` block of a
+* {@link FormDocument}.
+*
+* Every function is total over legacy documents: `doc.suggestions` may be
+* `undefined` (documents written before suggestions existed) and each helper
+* treats that as "no suggestions". Writers never mutate their input -- they
+* return a new document -- and they drop the `suggestions` key entirely once it
+* would be empty, so a document that never had suggestions round-trips
+* unchanged.
+*
+* These helpers deliberately do **not** check that `fieldId` refers to an
+* existing, non-section field. That check belongs to the general-purpose
+* authoring API ({@link FormValuesEditor}); callers that already resolved a
+* field -- such as the viewer's render loop -- would only pay for it twice.
+*/
+/**
+* Returns the suggestion recorded for a field.
+*
+* @param doc - The form document to read from.
+* @param fieldId - Numeric id of the field.
+* @returns The suggestion, or `undefined` when the field has none.
+*/
+const getSuggestion = (doc, fieldId) => doc.suggestions?.[String(fieldId)];
+/**
+* Records a suggestion for a field, replacing any existing one.
+*
+* @param doc - The form document to update.
+* @param fieldId - Numeric id of the field.
+* @param suggestion - The suggestion to store. Deep-copied before storing.
+* @returns A new document carrying the suggestion.
+* @throws If `confidence` is not a finite number within `0..1`.
+*/
+const setSuggestion = (doc, fieldId, suggestion) => {
+	const { confidence } = suggestion;
+	if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw new Error(`Suggestion confidence must be a number between 0 and 1, received ${confidence}`);
+	return {
+		...doc,
+		suggestions: {
+			...doc.suggestions,
+			[String(fieldId)]: deepCopy(suggestion)
+		}
+	};
+};
+/**
+* Removes the suggestion recorded for a field, leaving the field's value alone.
+*
+* When the removed entry was the last one, the `suggestions` key is dropped
+* from the document rather than left as an empty object.
+*
+* @param doc - The form document to update.
+* @param fieldId - Numeric id of the field.
+* @returns A new document without that suggestion, or `doc` itself when there
+*   was nothing to remove.
+*/
+const removeSuggestion = (doc, fieldId) => {
+	const key = String(fieldId);
+	if (!doc.suggestions || !(key in doc.suggestions)) return doc;
+	const { [key]: _removed, ...rest } = doc.suggestions;
+	if (Object.keys(rest).length === 0) {
+		const { suggestions: _dropped, ...withoutSuggestions } = doc;
+		return withoutSuggestions;
+	}
+	return {
+		...doc,
+		suggestions: rest
+	};
+};
+/**
+* Copies a field's suggested value into the document's values, keeping the
+* suggestion in place so the origin of the answer stays visible.
+*
+* The value is deep-copied: array and object suggestions must not become
+* aliases of the stored value, or later in-place edits (e.g. appending an array
+* item) would silently rewrite the suggestion too.
+*
+* @param doc - The form document to update.
+* @param fieldId - Numeric id of the field.
+* @returns A new document with the value applied, or `doc` itself when the
+*   field has no suggestion.
+*/
+const applySuggestion = (doc, fieldId) => {
+	const suggestion = getSuggestion(doc, fieldId);
+	if (!suggestion) return doc;
+	return {
+		...doc,
+		values: {
+			...doc.values,
+			[String(fieldId)]: deepCopy(suggestion.value)
+		}
+	};
+};
+/**
+* Returns all suggestions on a document as a plain object, never `undefined`.
+*
+* @param doc - The form document to read from.
+* @returns A copy of the suggestions map. Empty when the document has none.
+*/
+const getSuggestions = (doc) => ({ ...doc.suggestions });
+const deepCopy = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
+//#endregion
 //#region src/form-values-editor.ts
 /**
 * Mutable editor for building and modifying form values against a {@link FormDefinition}.
@@ -2199,13 +3688,16 @@ var FormValuesEditor = class {
 	* 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`.
+	* @param fieldId - Numeric id of the `array` or `array_obj` field.
+	* @param value - The value to append. Defaults to `undefined` for an
+	*   `array` field and to an empty row (`{}`) for an `array_obj` field.
 	* @returns `this` for chaining.
 	* @throws If `fieldId` is not an array field.
 	*/
 	addArrayItem(fieldId, value) {
-		this.getOrInitArray(fieldId).push(value);
+		const arr = this.getOrInitArray(fieldId);
+		const entry = this.engine.getFieldDef(fieldId);
+		arr.push(value === void 0 && entry?.type === "array_obj" ? {} : value);
 		return this;
 	}
 	/**
@@ -2255,6 +3747,114 @@ var FormValuesEditor = class {
 		return this;
 	}
 	/**
+	* Returns the value of one sub-field within one row of an `array_obj` field.
+	*
+	* @param fieldId - Numeric id of the `array_obj` field.
+	* @param index - Zero-based row index.
+	* @param subFieldId - Numeric id of the sub-field.
+	* @returns The sub-field value, or `undefined` if not set.
+	* @throws If the field is not an `array_obj`, the row index is out of
+	*   bounds, or the sub-field does not belong to the field.
+	*/
+	getArrayObjValue(fieldId, index, subFieldId) {
+		return this.assertArrayObjRow(fieldId, index, subFieldId)[String(subFieldId)];
+	}
+	/**
+	* Sets the value of one sub-field within one row of an `array_obj` field.
+	*
+	* @param fieldId - Numeric id of the `array_obj` field.
+	* @param index - Zero-based row index.
+	* @param subFieldId - Numeric id of the sub-field.
+	* @param value - The value to set.
+	* @returns `this` for chaining.
+	* @throws If the field is not an `array_obj`, the row index is out of
+	*   bounds, or the sub-field does not belong to the field or is static.
+	*/
+	setArrayObjValue(fieldId, index, subFieldId, value) {
+		this.assertArrayObjRow(fieldId, index, subFieldId)[String(subFieldId)] = value;
+		return this;
+	}
+	/**
+	* Removes one sub-field's value from one row of an `array_obj` field.
+	*
+	* @returns `this` for chaining.
+	* @throws Under the same conditions as {@link setArrayObjValue}.
+	*/
+	clearArrayObjValue(fieldId, index, subFieldId) {
+		delete this.assertArrayObjRow(fieldId, index, subFieldId)[String(subFieldId)];
+		return this;
+	}
+	/**
+	* Returns the suggestion recorded for a field.
+	*
+	* @param fieldId - Numeric id of the field.
+	* @returns The suggestion, or `undefined` if the field has none.
+	*/
+	getSuggestion(fieldId) {
+		return getSuggestion(this.doc, fieldId);
+	}
+	/**
+	* Returns every suggestion on the document, keyed by stringified field id.
+	*
+	* @returns A copy of the suggestions map. Empty when there are none.
+	*/
+	getSuggestions() {
+		return getSuggestions(this.doc);
+	}
+	/**
+	* Records a suggestion for a field, replacing any existing one. The field's
+	* value is left untouched.
+	*
+	* @param fieldId - Numeric id of the field.
+	* @param suggestion - The suggestion to store.
+	* @returns `this` for chaining.
+	* @throws If `fieldId` is unknown, references a section, or `confidence`
+	*   falls outside `0..1`.
+	*/
+	setSuggestion(fieldId, suggestion) {
+		this.assertField(fieldId);
+		this.doc = setSuggestion(this.doc, fieldId, suggestion);
+		return this;
+	}
+	/**
+	* Removes the suggestion recorded for a field, leaving its value untouched.
+	*
+	* @param fieldId - Numeric id of the field.
+	* @returns `this` for chaining.
+	*/
+	clearSuggestion(fieldId) {
+		this.doc = removeSuggestion(this.doc, fieldId);
+		return this;
+	}
+	/**
+	* Accepts a field's suggestion: copies the suggested value into the field's
+	* value and **keeps** the suggestion, so its source stays visible.
+	*
+	* No-op when the field has no suggestion.
+	*
+	* @param fieldId - Numeric id of the field.
+	* @returns `this` for chaining.
+	* @throws If `fieldId` is unknown or references a section.
+	*/
+	acceptSuggestion(fieldId) {
+		this.assertField(fieldId);
+		this.doc = applySuggestion(this.doc, fieldId);
+		return this;
+	}
+	/**
+	* Rejects a field's suggestion: removes it entirely, leaving the field's
+	* value untouched.
+	*
+	* No-op when the field has no suggestion.
+	*
+	* @param fieldId - Numeric id of the field.
+	* @returns `this` for chaining.
+	*/
+	rejectSuggestion(fieldId) {
+		this.doc = removeSuggestion(this.doc, fieldId);
+		return this;
+	}
+	/**
 	* Sets the `submittedAt` timestamp on the document.
 	*
 	* @param submittedAt - ISO 8601 timestamp string.
@@ -2310,6 +3910,7 @@ var FormValuesEditor = class {
 		const entry = this.engine.getFieldDef(fieldId);
 		if (!entry) throw new Error(`Field with id ${fieldId} not found`);
 		if (entry.type === "section") throw new Error(`Item ${fieldId} is a section, not a field`);
+		if (entry.type === "static") throw new Error(`Item ${fieldId} is a static field and holds no value`);
 	}
 	/**
 	* Asserts that `fieldId` is an array field and returns the current array value.
@@ -2318,7 +3919,7 @@ var FormValuesEditor = class {
 	assertArray(fieldId) {
 		const entry = this.engine.getFieldDef(fieldId);
 		if (!entry) throw new Error(`Field with id ${fieldId} not found`);
-		if (entry.type !== "array") throw new Error(`Field ${fieldId} is not an array field`);
+		if (entry.type !== "array" && entry.type !== "array_obj") throw new Error(`Field ${fieldId} is not an array field`);
 		const val = this.doc.values[String(fieldId)];
 		if (!Array.isArray(val)) throw new Error(`Field ${fieldId} does not currently hold an array value`);
 		return val;
@@ -2329,7 +3930,7 @@ var FormValuesEditor = class {
 	getOrInitArray(fieldId) {
 		const entry = this.engine.getFieldDef(fieldId);
 		if (!entry) throw new Error(`Field with id ${fieldId} not found`);
-		if (entry.type !== "array") throw new Error(`Field ${fieldId} is not an array field`);
+		if (entry.type !== "array" && entry.type !== "array_obj") throw new Error(`Field ${fieldId} is not an array field`);
 		const key = String(fieldId);
 		let val = this.doc.values[key];
 		if (!Array.isArray(val)) {
@@ -2338,6 +3939,26 @@ var FormValuesEditor = class {
 		}
 		return val;
 	}
+	/**
+	* Asserts that `fieldId` is an `array_obj` field holding a row at `index`
+	* with a writable sub-field `subFieldId`, and returns that row.
+	* The row is created in place when it is absent or not an object.
+	*/
+	assertArrayObjRow(fieldId, index, subFieldId) {
+		const entry = this.engine.getFieldDef(fieldId);
+		if (!entry) throw new Error(`Field with id ${fieldId} not found`);
+		if (entry.type !== "array_obj") throw new Error(`Field ${fieldId} is not an array_obj field`);
+		const subField = (entry.items ?? []).find((f) => f.id === subFieldId);
+		if (!subField) throw new Error(`Sub-field ${subFieldId} does not belong to field ${fieldId}`);
+		if (subField.type === "static") throw new Error(`Sub-field ${subFieldId} is a static field and holds no value`);
+		const arr = this.assertArray(fieldId);
+		if (index < 0 || index >= arr.length) throw new Error(`Index ${index} is out of bounds for array field ${fieldId} (length ${arr.length})`);
+		const row = arr[index];
+		if (typeof row === "object" && row !== null && !Array.isArray(row)) return row;
+		const created = {};
+		arr[index] = created;
+		return created;
+	}
 };
 //#endregion
 exports.ConditionEvaluator = ConditionEvaluator;
@@ -2349,3 +3970,8 @@ exports.FormDefinitionValidator = FormDefinitionValidator;
 exports.FormEngine = FormEngine;
 exports.FormValuesEditor = FormValuesEditor;
 exports.VisibilityResolver = VisibilityResolver;
+exports.applySuggestion = applySuggestion;
+exports.getSuggestion = getSuggestion;
+exports.getSuggestions = getSuggestions;
+exports.removeSuggestion = removeSuggestion;
+exports.setSuggestion = setSuggestion;