@bluprynt/forms-core 4.0.1 → 4.1.0

package/dist/index.d.cts

@@ -31,6 +31,34 @@ type CompoundCondition = {
  */
 type Condition = SimpleCondition | CompoundCondition;
 //#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
+ * - `multiselect` -- any number of selections from a predefined list; the
+ *   value is an array of the chosen options' `value`s
+ * - `array` -- ordered list of values whose item type is any non-array field type
+ * - `array_obj` -- ordered list of rows; each row is an object holding one value
+ *   per sub-field defined in the field's `items` list
+ * - `file` -- file upload (stores name, MIME type, size, URL)
+ * - `static` -- display-only text; holds no value and is never validated
+ * - `blockchain` -- a CAIP address identifying an on-chain asset. The value is
+ *   an opaque string: the engine never checks its format
+ * - `sustainability` -- sustainability data for an on-chain asset; the value is
+ *   a {@link SustainabilityValue} object (`address`, `ccri`, `cmc`)
+ */
+type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'select' | 'multiselect' | 'array' | 'array_obj' | 'file' | 'static' | 'blockchain' | 'sustainability';
+/**
+ * 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/condition-evaluator.d.ts
 /**
  * Context passed to condition evaluation methods.
@@ -41,11 +69,15 @@ type Condition = SimpleCondition | CompoundCondition;
  *   actual value.
  * @property now - Reference date for resolving relative date expressions in
  *   condition values.
+ * @property fieldTypes - Type of each item by id. Optional: when omitted every
+ *   field is compared with the default scalar semantics. Supplying it enables
+ *   the set-oriented semantics used for `multiselect` fields.
  */
 type EvaluationContext = {
   values: Record<string, unknown>;
   visibilityMap?: Map<number, boolean>;
   now: Date;
+  fieldTypes?: Map<number, ContentItemType>;
 };
 /**
  * Evaluates condition trees against form state.
@@ -64,6 +96,18 @@ type EvaluationContext = {
  *
  * **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.
  */
 declare class ConditionEvaluator {
   /**
@@ -76,29 +120,17 @@ declare class ConditionEvaluator {
    */
   evalCondition(condition: Condition, ctx: EvaluationContext): boolean;
   private evalSimple;
+  private evalMultiselect;
+  /**
+   * 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".
+   */
+  private sameSet;
   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.
@@ -113,26 +145,140 @@ type SelectOption = {
 //#endregion
 //#region src/types/array-item-def.d.ts
 /**
- * Schema for individual items inside an `array` field.
+ * Schema for a value-producing item inside an `array` field.
  *
- * Nested arrays are not allowed, so `type` excludes `'array'`.
+ * Neither list type may nest, so `type` excludes `'array'` and `'array_obj'`.
  * 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 type - The field type for each item in the array.
  * @property label - Display label for the item.
  * @property description - Optional description shown to the user.
+ * @property placeholder - Optional placeholder text for the item's input control.
+ * @property answer_guidelines - Optional guidance describing how the item should be answered.
+ * @property reference_id - Optional external reference (e.g. a regulation or questionnaire item id).
  * @property validation - Validation rules applied to each individual item.
- * @property options - Required when {@link type} is `'select'`; the list of
- *   allowed values.
+ * @property options - Required when {@link type} is `'select'` or `'multiselect'`;
+ *   the list of allowed values.
  */
-type ArrayItemDef = {
-  type: Exclude<FieldType, 'array'>;
+type ValueArrayItemDef = {
+  type: Exclude<FieldType, 'array' | 'array_obj' | 'static'>;
   label: string;
   description?: string;
+  placeholder?: string;
+  answer_guidelines?: string;
+  reference_id?: string;
   validation?: Record<string, unknown>;
   options?: SelectOption[];
 };
+/**
+ * Schema for a display-only item inside an `array` field.
+ *
+ * A static item holds no value and is never validated, so an array using one
+ * renders as many blocks as the stored array is long and contributes nothing
+ * to the document's values. Accepted for symmetry with `array_obj`, where a
+ * static sub-field is genuinely useful as a per-row caption.
+ *
+ * @property type - Always `'static'`.
+ * @property text - The text to display.
+ * @property label - Optional heading shown above {@link text}.
+ */
+type StaticArrayItemDef = {
+  type: 'static';
+  text: string;
+  label?: string;
+  description?: string;
+  placeholder?: string;
+  answer_guidelines?: string;
+  reference_id?: string;
+};
+/**
+ * Schema for individual items inside an `array` field.
+ *
+ * Narrow with `item.type === 'static'` to reach {@link StaticArrayItemDef}'s
+ * `text`, or with `item.type !== 'static'` to reach the value-item properties
+ * (`label`, `validation`, `options`).
+ */
+type ArrayItemDef = ValueArrayItemDef | StaticArrayItemDef;
+//#endregion
+//#region src/types/array-obj-item-def.d.ts
+/**
+ * Schema for a value-producing sub-field inside an `array_obj` field.
+ *
+ * Unlike an `array` item, a sub-field carries its own `id`: it is drawn from
+ * the same globally unique id space as top-level fields and is the key under
+ * which the sub-field's value is stored inside each row object.
+ *
+ * Neither list type may nest, so `type` excludes `'array'` and `'array_obj'`.
+ * Sub-fields have no `condition` -- they inherit the parent field's visibility.
+ *
+ * @property id - Unique numeric identifier, also the row-object key.
+ * @property type - The field type for this sub-field.
+ * @property label - Display label for the sub-field.
+ * @property description - Optional description shown to the user.
+ * @property placeholder - Optional placeholder text for the sub-field's input control.
+ * @property answer_guidelines - Optional guidance describing how the sub-field should be answered.
+ * @property reference_id - Optional external reference (e.g. a regulation or questionnaire item id).
+ * @property validation - Validation rules applied to this sub-field in every row.
+ * @property options - Required when {@link type} is `'select'` or `'multiselect'`;
+ *   the list of allowed values.
+ */
+type ValueArrayObjItemDef = {
+  id: number;
+  type: Exclude<FieldType, 'array' | 'array_obj' | 'static'>;
+  label: string;
+  description?: string;
+  placeholder?: string;
+  answer_guidelines?: string;
+  reference_id?: string;
+  validation?: Record<string, unknown>;
+  options?: SelectOption[];
+};
+/**
+ * Schema for a display-only sub-field inside an `array_obj` field.
+ *
+ * Holds no value and is never validated, but still occupies a position in
+ * every row -- useful as a per-row caption or separator.
+ *
+ * @property id - Unique numeric identifier. No value is ever stored under it.
+ * @property type - Always `'static'`.
+ * @property text - The text to display.
+ * @property label - Optional heading shown above {@link text}.
+ */
+type StaticArrayObjItemDef = {
+  id: number;
+  type: 'static';
+  text: string;
+  label?: string;
+  description?: string;
+  placeholder?: string;
+  answer_guidelines?: string;
+  reference_id?: string;
+};
+/**
+ * Schema for a single sub-field inside an `array_obj` field.
+ *
+ * Narrow with `item.type === 'static'` to reach {@link StaticArrayObjItemDef}'s
+ * `text`, or with `item.type !== 'static'` to reach the value-field properties
+ * (`label`, `validation`, `options`).
+ */
+type ArrayObjItemDef = ValueArrayObjItemDef | StaticArrayObjItemDef;
+/**
+ * How an `array_obj` field asks to be laid out.
+ *
+ * Purely presentation metadata: the engine never reads it, and it affects
+ * neither values, validation nor visibility. `'list'` when absent, so
+ * definitions written before it existed keep their original rendering.
+ *
+ * - `list` -- each row is a stacked block of labelled controls.
+ * - `table` -- rows share one header, one column per sub-field.
+ */
+type ArrayObjKind = 'list' | 'table';
+/**
+ * A single row of an `array_obj` field's value: a map from stringified
+ * sub-field id to that sub-field's value.
+ */
+type ArrayObjRow = Record<string, unknown>;
 //#endregion
 //#region src/types/validation/array.d.ts
 /**
@@ -146,6 +292,34 @@ type ArrayValidation = {
   maxItems?: number;
 };
 //#endregion
+//#region src/types/validation/array-obj.d.ts
+/**
+ * Validation rules for `array_obj` fields.
+ *
+ * Covers the row list itself. Per-sub-field rules live inside each entry of
+ * the field's `items` list.
+ *
+ * @property minItems - Minimum number of rows the field must contain (inclusive).
+ * @property maxItems - Maximum number of rows the field may contain (inclusive).
+ */
+type ArrayObjValidation = {
+  minItems?: number;
+  maxItems?: number;
+};
+//#endregion
+//#region src/types/validation/blockchain.d.ts
+/**
+ * Validation rules for `blockchain` fields.
+ *
+ * The value is an opaque CAIP address string -- there is deliberately no format
+ * rule, so a malformed address is the consumer's concern, not the engine's.
+ *
+ * @property required - Whether an address must be provided.
+ */
+type BlockchainValidation = {
+  required?: boolean;
+};
+//#endregion
 //#region src/types/validation/boolean.d.ts
 /**
  * Validation rules for `boolean` fields.
@@ -184,6 +358,17 @@ type FileValidation = {
   required?: boolean;
 };
 //#endregion
+//#region src/types/validation/multiselect.d.ts
+/**
+ * Validation rules for `multiselect` fields.
+ *
+ * @property required - When `true`, at least one option must be selected.
+ *   An absent value and an empty array both fail this rule.
+ */
+type MultiselectValidation = {
+  required?: boolean;
+};
+//#endregion
 //#region src/types/validation/number.d.ts
 /**
  * Validation rules for `number` fields.
@@ -226,12 +411,23 @@ type StringValidation = {
   patternMessage?: string;
 };
 //#endregion
+//#region src/types/validation/sustainability.d.ts
+/**
+ * Validation rules for `sustainability` fields.
+ *
+ * @property required - Whether the value's `address` must be a non-empty
+ *   string. `ccri` and `cmc` are always optional.
+ */
+type SustainabilityValidation = {
+  required?: boolean;
+};
+//#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;
+type TypeSpecificValidation = StringValidation | NumberValidation | BooleanValidation | DateValidation | SelectValidation | MultiselectValidation | ArrayValidation | ArrayObjValidation | FileValidation | BlockchainValidation | SustainabilityValidation;
 //#endregion
 //#region src/types/field-entry.d.ts
 /**
@@ -248,6 +444,7 @@ type TypeSpecificValidation = StringValidation | NumberValidation | BooleanValid
  * @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 items - Sub-field definitions (only for `array_obj` fields).
  * @property label - Display label (only for fields, `undefined` for sections).
  * @property title - Display title (only for sections, `undefined` for fields).
  */
@@ -259,6 +456,7 @@ type FieldEntry = {
   parentId: number | undefined;
   options: SelectOption[] | undefined;
   item: ArrayItemDef | undefined;
+  items: ArrayObjItemDef[] | undefined;
   label: string | undefined;
   title: string | undefined;
 };
@@ -345,6 +543,32 @@ declare class DependencyGraph {
   private expandTransitiveDependencies;
 }
 //#endregion
+//#region src/types/suggestion.d.ts
+/**
+ * A machine-proposed answer for a single field.
+ *
+ * Suggestions live alongside user-entered values in a {@link FormDocument} and
+ * never participate in validation or visibility. A suggestion is only ever
+ * copied into `values` when it is explicitly accepted.
+ *
+ * @property value - The proposed value, shaped like the field's own value.
+ * @property confidence - How confident the producer is, as a `0..1` fraction
+ *   (`0.3` means 30%). Range-checked on write, not on read.
+ * @property source - Human-readable explanation of why the value was proposed.
+ */
+type FieldSuggestion = {
+  value: unknown;
+  confidence: number;
+  source: string;
+};
+/**
+ * A sparse map of suggestions keyed by stringified field id (e.g. `"1"`, `"42"`),
+ * using the same key space as {@link FormValues}.
+ *
+ * Most fields have no suggestion, so keys are expected to be missing.
+ */
+type FormSuggestions = Record<string, FieldSuggestion>;
+//#endregion
 //#region src/types/form-values.d.ts
 /**
  * A flat key-value map of user-submitted form data.
@@ -364,6 +588,9 @@ type FormValues = Record<string, unknown>;
  * @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.
+ * @property suggestions - Optional sparse map of machine-proposed answers, keyed
+ *   like {@link values}. Omitted entirely on documents that have none, so
+ *   documents produced before suggestions existed remain valid unchanged.
  */
 type FormDocument = {
   form: {
@@ -372,6 +599,7 @@ type FormDocument = {
     submittedAt: string;
   };
   values: FormValues;
+  suggestions?: FormSuggestions;
 };
 //#endregion
 //#region src/types/validation-results.d.ts
@@ -391,8 +619,11 @@ type FormDocument = {
  * | `MAX_DATE` | `date` |
  * | `INVALID_DATE` | `date` (unparseable value) |
  * | `INVALID_OPTION` | `select` (value not in options list) |
- * | `MIN_ITEMS` | `array` |
- * | `MAX_ITEMS` | `array` |
+ * | `MIN_ITEMS` | `array`, `array_obj` |
+ * | `MAX_ITEMS` | `array`, `array_obj` |
+ *
+ * On a `sustainability` field `REQUIRED` means the value's `address` is missing
+ * or empty -- `ccri` and `cmc` never trigger it.
  */
 type FieldValidationRule = 'REQUIRED' | 'TYPE' | 'MIN_LENGTH' | 'MAX_LENGTH' | 'PATTERN' | 'MIN' | 'MAX' | 'MIN_DATE' | 'MAX_DATE' | 'INVALID_DATE' | 'INVALID_OPTION' | 'MIN_ITEMS' | 'MAX_ITEMS';
 /**
@@ -402,8 +633,13 @@ type FieldValidationRule = 'REQUIRED' | 'TYPE' | 'MIN_LENGTH' | 'MAX_LENGTH' | '
  * @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.
+ * @property itemIndex - For `array` and `array_obj` fields, the zero-based index
+ *   of the item or row that failed validation. `undefined` for other fields.
+ * @property itemFieldId - For `array_obj` fields, the id of the sub-field within
+ *   the row identified by {@link itemIndex}. `undefined` everywhere else,
+ *   including on a row-level `TYPE` error. Note that `fieldId` stays the
+ *   `array_obj` container's id, so it always matches the key this error is
+ *   stored under in {@link FormValidationResult.fieldErrors}.
  */
 type FieldValidationError = {
   fieldId: number;
@@ -411,6 +647,7 @@ type FieldValidationError = {
   message: string;
   params?: Record<string, unknown>;
   itemIndex?: number;
+  itemFieldId?: number;
 };
 /**
  * Machine-readable codes for all document-level validation errors.
@@ -422,6 +659,8 @@ type FieldValidationError = {
  * | `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. |
+ * | `CONDITION_REFS_STATIC` | A condition references a static field id; static blocks have no value to compare. |
+ * | `CONDITION_REFS_ARRAY_OBJ_ITEM` | A condition references an `array_obj` sub-field id; its value is per-row and not addressable. |
  * | `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). |
@@ -430,7 +669,7 @@ type FieldValidationError = {
  * | `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';
+type DocumentValidationErrorCode = 'SCHEMA_INVALID' | 'DUPLICATE_ID' | 'NESTING_DEPTH' | 'UNKNOWN_FIELD_REF' | 'CONDITION_REFS_SECTION' | 'CONDITION_REFS_STATIC' | 'CONDITION_REFS_ARRAY_OBJ_ITEM' | '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.
  *
@@ -475,9 +714,19 @@ type FormValidationResult = {
  * - `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
@@ -525,30 +774,83 @@ type FormDefinition = {
   content: ContentItem[];
 };
 /**
- * A single node in the form definition tree -- either a field or a section.
+ * A single node in the form definition tree -- a value field, a static block
+ * or a section.
+ */
+type ContentItem = AnyFieldContentItem | SectionContentItem;
+/**
+ * Any non-section node: either a value-producing field or a static block.
+ *
+ * Narrow with `item.type === 'static'` to reach {@link StaticFieldContentItem}'s
+ * `text`, or with `item.type !== 'static'` to reach the value-field properties
+ * (`label`, `validation`, `options`, `item`, `items`).
  */
-type ContentItem = FieldContentItem | SectionContentItem;
+type AnyFieldContentItem = FieldContentItem | StaticFieldContentItem;
 /**
- * A field node within the form definition tree.
+ * A value-producing field node within the form definition tree.
+ *
+ * Excludes `static`, which holds no value and has its own shape --
+ * see {@link StaticFieldContentItem}.
  *
  * @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 placeholder - Optional placeholder text for the field's input control.
+ * @property answer_guidelines - Optional guidance describing how the field should be answered.
+ * @property reference_id - Optional external reference (e.g. a regulation or questionnaire item id).
  * @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 options - Allowed values (required for `select` and `multiselect` fields).
  * @property item - Item schema (required for `array` fields).
+ * @property items - Sub-field schemas (required for `array_obj` fields).
+ * @property kind - Layout hint for `array_obj` fields (`'list'` when absent).
+ *   Presentation metadata only -- the engine never reads it.
  */
 type FieldContentItem = {
   id: number;
-  type: FieldType;
+  type: Exclude<FieldType, 'static'>;
   label: string;
   description?: string;
+  placeholder?: string;
+  answer_guidelines?: string;
+  reference_id?: string;
   condition?: Condition;
   validation?: TypeSpecificValidation;
   options?: SelectOption[];
   item?: ArrayItemDef;
+  items?: ArrayObjItemDef[];
+  kind?: ArrayObjKind;
+};
+/**
+ * A display-only text block within the form definition tree.
+ *
+ * Static blocks render alongside fields and honour their own `condition`, but
+ * they hold no value: they never appear in form values, never carry
+ * validation rules, never produce validation errors, and cannot be referenced
+ * by another item's condition.
+ *
+ * @property id - Unique numeric identifier.
+ * @property type - Always `'static'`.
+ * @property text - The text to display. This is the block's content, and the
+ *   only required property beyond `id` and `type`.
+ * @property label - Optional heading shown above {@link text}.
+ * @property description - Optional secondary text.
+ * @property placeholder - Optional presentation metadata. Opaque to the engine.
+ * @property answer_guidelines - Optional presentation metadata. Opaque to the engine.
+ * @property reference_id - Optional external reference (e.g. a regulation or questionnaire item id).
+ * @property condition - Visibility condition that controls whether this block is shown.
+ */
+type StaticFieldContentItem = {
+  id: number;
+  type: 'static';
+  text: string;
+  label?: string;
+  description?: string;
+  placeholder?: string;
+  answer_guidelines?: string;
+  reference_id?: string;
+  condition?: Condition;
 };
 /**
  * A section node that groups fields and/or child sections.
@@ -559,6 +861,9 @@ type FieldContentItem = {
  * @property type - Always `'section'`.
  * @property title - Display title for the section.
  * @property description - Optional description.
+ * @property placeholder - Optional placeholder text.
+ * @property answer_guidelines - Optional guidance describing how the section should be completed.
+ * @property reference_id - Optional external reference (e.g. a regulation or questionnaire item id).
  * @property condition - Visibility condition. When hidden, all descendant
  *   fields and sections are also hidden.
  * @property content - Ordered list of child content items.
@@ -568,6 +873,9 @@ type SectionContentItem = {
   type: 'section';
   title: string;
   description?: string;
+  placeholder?: string;
+  answer_guidelines?: string;
+  reference_id?: string;
   condition?: Condition;
   content: ContentItem[];
 };
@@ -576,10 +884,16 @@ type SectionContentItem = {
 /**
  * Descriptor for a field to be added via the editor.
  * `id` is optional -- when omitted the editor auto-assigns the next available id.
+ *
+ * Written as an explicit union rather than `Omit<AnyFieldContentItem, 'id'>`
+ * because `Omit` does not distribute over a union -- it would collapse to the
+ * properties the two members share, dropping `label` and `text`.
  */
-type FieldDescriptor = Omit<FieldContentItem, 'id'> & {
+type FieldDescriptor = (Omit<FieldContentItem, 'id'> & {
   id?: number;
-};
+}) | (Omit<StaticFieldContentItem, '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.
@@ -627,6 +941,9 @@ declare class FormDefinitionEditor {
   setId(id: string): this;
   /**
    * 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(): number;
   /**
@@ -655,7 +972,9 @@ declare class FormDefinitionEditor {
    * Cannot change `id` or `type`. Use {@link removeItem} + {@link addField}
    * to change the type.
    */
-  updateField(id: number, updates: Partial<Omit<FieldContentItem, 'id' | 'type'>>): this;
+  updateField(id: number, updates: Partial<Omit<FieldContentItem, 'id' | 'type'> & {
+    text: string;
+  }>): this;
   /**
    * Updates properties of an existing section.
    *
@@ -703,27 +1022,114 @@ declare class FormDefinitionEditor {
    */
   setCondition(id: number, condition: Condition | undefined): this;
   /**
-   * Sets the select options for a `select` field.
+   * Sets the options for a `select` or `multiselect` field.
    */
   setOptions(id: number, options: SelectOption[]): this;
   /**
    * Sets the item definition for an `array` field.
    */
   setArrayItem(id: number, itemDef: ArrayItemDef): 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: number, itemDefs: ArrayObjItemDef[]): 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: number): ArrayObjItemDef[];
+  /**
+   * 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: number, kind: ArrayObjKind | undefined): 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: number, subField: Omit<ArrayObjItemDef, 'id'> & {
+    id?: number;
+  }): number;
+  /**
+   * 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: number, subFieldId: number, patch: Partial<ArrayObjItemDef>): this;
+  /**
+   * Removes a sub-field from an `array_obj` field.
+   *
+   * @throws If the field or the sub-field is not found.
+   */
+  removeArrayItemField(id: number, subFieldId: number): 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: number, fromIndex: number, toIndex: number): this;
   /**
    * Sets the label for a field.
    */
   setLabel(id: number, label: string): 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: number, text: string): this;
   /**
    * Sets the description for a field or section.
    */
   setFieldDescription(id: number, description: string | undefined): 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: number, placeholder: string | undefined): this;
+  /**
+   * Sets the answer guidelines for a field or section.
+   *
+   * Passing `undefined` removes the property.
+   */
+  setAnswerGuidelines(id: number, answerGuidelines: string | undefined): this;
+  /**
+   * Sets the external reference id for a field or section.
+   *
+   * Passing `undefined` removes the property.
+   */
+  setReferenceId(id: number, referenceId: string | undefined): this;
+  /**
+   * Assigns or deletes one optional string property on a field or section.
+   */
+  private setMetadata;
   /**
    * Returns a deep clone of the current form definition.
    */
   toJSON(): FormDefinition;
   private findItem;
   private assertIdAvailable;
+  /**
+   * Finds an `array_obj` sub-field anywhere in the definition by its id.
+   */
+  private findArrayObjItem;
+  private assertArrayObjField;
   private insertItem;
   private getTargetContent;
   private removeFromContent;
@@ -746,12 +1152,17 @@ declare class FormDefinitionEditor {
  * ### 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
@@ -789,9 +1200,11 @@ declare class FormDefinitionValidator {
    */
   validate(definition: FormDefinition, registry: Map<number, FieldEntry>): DocumentValidationError[];
   private checkDuplicateIds;
+  private collectArrayObjItemIds;
+  private checkConditionRefsArrayObjItem;
   private checkNestingDepth;
   private checkConditionRefs;
-  private checkConditionRefsSection;
+  private checkConditionRefsValueless;
   private checkConstraintContradictions;
   private checkInvalidRegex;
   private walkItems;
@@ -1015,8 +1428,9 @@ declare class FormValuesEditor {
    * 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.
    */
@@ -1050,6 +1464,88 @@ declare class FormValuesEditor {
    * @throws If `fieldId` is not an array field or the index is out of bounds.
    */
   setArrayItem(fieldId: number, index: number, value: unknown): 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: number, index: number, subFieldId: number): unknown;
+  /**
+   * 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: number, index: number, subFieldId: number, value: unknown): 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: number, index: number, subFieldId: number): 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: number): FieldSuggestion | undefined;
+  /**
+   * Returns every suggestion on the document, keyed by stringified field id.
+   *
+   * @returns A copy of the suggestions map. Empty when there are none.
+   */
+  getSuggestions(): FormSuggestions;
+  /**
+   * 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: number, suggestion: FieldSuggestion): 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: number): 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: number): 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: number): this;
   /**
    * Sets the `submittedAt` timestamp on the document.
    *
@@ -1101,8 +1597,83 @@ declare class FormValuesEditor {
    * Returns the array value for `fieldId`, initializing to `[]` if not yet set.
    */
   private getOrInitArray;
+  /**
+   * 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.
+   */
+  private assertArrayObjRow;
 }
 //#endregion
+//#region src/suggestions.d.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.
+ */
+declare const getSuggestion: (doc: FormDocument, fieldId: number) => FieldSuggestion | undefined;
+/**
+ * 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`.
+ */
+declare const setSuggestion: (doc: FormDocument, fieldId: number, suggestion: FieldSuggestion) => FormDocument;
+/**
+ * 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.
+ */
+declare const removeSuggestion: (doc: FormDocument, fieldId: number) => FormDocument;
+/**
+ * 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.
+ */
+declare const applySuggestion: (doc: FormDocument, fieldId: number) => FormDocument;
+/**
+ * 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.
+ */
+declare const getSuggestions: (doc: FormDocument) => FormSuggestions;
+//#endregion
 //#region src/types/errors.d.ts
 /**
  * Error thrown when form definition or document validation fails.
@@ -1151,6 +1722,24 @@ type FileValue = {
   url: string;
 };
 //#endregion
+//#region src/types/sustainability-value.d.ts
+/**
+ * Sustainability data for an on-chain asset.
+ *
+ * The engine does not resolve or verify any of these -- the consumer produces
+ * the object and the engine stores it verbatim.
+ *
+ * @property address - CAIP address of the asset the data describes. Opaque to
+ *   the engine: its format is never checked.
+ * @property ccri - CCRI (Crypto Carbon Ratings Institute) reference.
+ * @property cmc - CoinMarketCap reference.
+ */
+type SustainabilityValue = {
+  address: string;
+  ccri?: string;
+  cmc?: string;
+};
+//#endregion
 //#region src/visibility-resolver.d.ts
 /**
  * Computes field and section visibility for a form.
@@ -1166,6 +1755,7 @@ declare class VisibilityResolver {
   private readonly registry;
   private readonly conditionEvaluator;
   private readonly topologicalOrder;
+  private readonly fieldTypes;
   /**
    * @param registry - The engine's field registry.
    * @param conditionEvaluator - Evaluator for condition trees.
@@ -1211,5 +1801,5 @@ declare class VisibilityResolver {
   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 };
+export { type AnyFieldContentItem, type ArrayItemDef, type ArrayObjItemDef, type ArrayObjKind, type ArrayObjRow, type ArrayObjValidation, type ArrayValidation, type BlockchainValidation, 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 FieldSuggestion, type FieldType, type FieldValidationError, type FieldValidationRule, FieldValidator, type FileValidation, type FileValue, type FormDefinition, FormDefinitionEditor, FormDefinitionValidator, type FormDocument, FormEngine, type FormSnapshot, type FormSuggestions, type FormValidationResult, type FormValues, FormValuesEditor, type MultiselectValidation, type NumberValidation, type SectionContentItem, type SectionDescriptor, type SelectOption, type SelectValidation, type SimpleCondition, type StaticArrayItemDef, type StaticArrayObjItemDef, type StaticFieldContentItem, type StringValidation, type SustainabilityValidation, type SustainabilityValue, type TypeSpecificValidation, type ValueArrayItemDef, type ValueArrayObjItemDef, VisibilityResolver, applySuggestion, getSuggestion, getSuggestions, removeSuggestion, setSuggestion };
 //# sourceMappingURL=index.d.cts.map