@bpmn-io/form-js-viewer 1.3.0-alpha.0 → 1.3.0

package/dist/index.cjs

@@ -67,26 +67,26 @@ const getFlavouredFeelVariableNames = (feelString, feelFlavour = 'expression', o
   return [...new Set(variables)];
 };
 
-/**
- * Get the variable name at the specified index in a given path expression.
- *
- * @param {Object} root - The root node of the path expression tree.
- * @param {number} index - The index of the variable name to retrieve.
- * @returns {string|null} The variable name at the specified index or null if index is out of bounds.
+/**
+ * Get the variable name at the specified index in a given path expression.
+ *
+ * @param {Object} root - The root node of the path expression tree.
+ * @param {number} index - The index of the variable name to retrieve.
+ * @returns {string|null} The variable name at the specified index or null if index is out of bounds.
  */
 const _getVariableNameAtPathIndex = (root, index) => {
   const accessors = _deconstructPathExpression(root);
   return accessors[index] || null;
 };
 
-/**
- * Extracts the variables which are required of the external context for a given path expression.
- * This is done by traversing the path expression tree and keeping track of the current depth relative to the external context.
- *
- * @param {Object} node - The root node of the path expression tree.
- * @param {number} initialDepth - The depth at which the root node is located in the outer context.
- * @param {Object} specialDepthAccessors - Definitions of special keywords which represent more complex accesses of the outer context.
- * @returns {Set} - A set containing the extracted variable names.
+/**
+ * Extracts the variables which are required of the external context for a given path expression.
+ * This is done by traversing the path expression tree and keeping track of the current depth relative to the external context.
+ *
+ * @param {Object} node - The root node of the path expression tree.
+ * @param {number} initialDepth - The depth at which the root node is located in the outer context.
+ * @param {Object} specialDepthAccessors - Definitions of special keywords which represent more complex accesses of the outer context.
+ * @returns {Set} - A set containing the extracted variable names.
  */
 const _smartExtractVariableNames = (node, initialDepth, specialDepthAccessors) => {
   // depth info represents the previous (initialised as null) and current depth of the current accessor in the path expression
@@ -132,11 +132,11 @@ const _smartExtractVariableNames = (node, initialDepth, specialDepthAccessors) =
   return new Set(extractedVariables);
 };
 
-/**
- * Deconstructs a path expression tree into an array of components.
- *
- * @param {Object} root - The root node of the path expression tree.
- * @returns {Array<string>} An array of components in the path expression, in the correct order.
+/**
+ * Deconstructs a path expression tree into an array of components.
+ *
+ * @param {Object} root - The root node of the path expression tree.
+ * @returns {Array<string>} An array of components in the path expression, in the correct order.
  */
 const _deconstructPathExpression = root => {
   let node = root;
@@ -155,13 +155,13 @@ const _deconstructPathExpression = root => {
   return parts.reverse();
 };
 
-/**
- * Builds a simplified feel structure tree from the given parse tree and feel string.
- * The nodes follow this structure: `{ name: string, children: Array, variableName?: string }`
- *
- * @param {Object} parseTree - The parse tree generated by a parser.
- * @param {string} feelString - The feel string used for parsing.
- * @returns {Object} The simplified feel structure tree.
+/**
+ * Builds a simplified feel structure tree from the given parse tree and feel string.
+ * The nodes follow this structure: `{ name: string, children: Array, variableName?: string }`
+ *
+ * @param {Object} parseTree - The parse tree generated by a parser.
+ * @param {string} feelString - The feel string used for parsing.
+ * @returns {Object} The simplified feel structure tree.
  */
 const _buildSimpleFeelStructureTree = (parseTree, feelString) => {
   const stack = [{
@@ -187,9 +187,9 @@ const _buildSimpleFeelStructureTree = (parseTree, feelString) => {
   return _extractFilterExpressions(stack[0].children[0]);
 };
 
-/**
- * Restructure the tree in such a way to bring filters (which create new contexts) to the root of the tree.
- * This is done to simplify the extraction of variables and match the context hierarchy.
+/**
+ * Restructure the tree in such a way to bring filters (which create new contexts) to the root of the tree.
+ * This is done to simplify the extraction of variables and match the context hierarchy.
  */
 const _extractFilterExpressions = tree => {
   const flattenedExpressionTree = {
@@ -230,25 +230,25 @@ class FeelExpressionLanguage {
     this._eventBus = eventBus;
   }
 
-  /**
-   * Determines if the given value is a FEEL expression.
-   *
-   * @param {any} value
-   * @returns {boolean}
-   *
+  /**
+   * Determines if the given value is a FEEL expression.
+   *
+   * @param {any} value
+   * @returns {boolean}
+   *
    */
   isExpression(value) {
     return minDash.isString(value) && value.startsWith('=');
   }
 
-  /**
-   * Retrieve variable names from a given FEEL expression.
-   *
-   * @param {string} expression
-   * @param {object} [options]
-   * @param {string} [options.type]
-   *
-   * @returns {string[]}
+  /**
+   * Retrieve variable names from a given FEEL expression.
+   *
+   * @param {string} expression
+   * @param {object} [options]
+   * @param {string} [options.type]
+   *
+   * @returns {string[]}
    */
   getVariableNames(expression, options = {}) {
     const {
@@ -263,13 +263,13 @@ class FeelExpressionLanguage {
     return getFlavouredFeelVariableNames(expression, type);
   }
 
-  /**
-   * Evaluate an expression.
-   *
-   * @param {string} expression
-   * @param {import('../../types').Data} [data]
-   *
-   * @returns {any}
+  /**
+   * Evaluate an expression.
+   *
+   * @param {string} expression
+   * @param {import('../../types').Data} [data]
+   *
+   * @returns {any}
    */
   evaluate(expression, data = {}) {
     if (!expression) {
@@ -294,23 +294,23 @@ FeelExpressionLanguage.$inject = ['eventBus'];
 class FeelersTemplating {
   constructor() {}
 
-  /**
-   * Determines if the given value is a feelers template.
-   *
-   * @param {any} value
-   * @returns {boolean}
-   *
+  /**
+   * Determines if the given value is a feelers template.
+   *
+   * @param {any} value
+   * @returns {boolean}
+   *
    */
   isTemplate(value) {
     return minDash.isString(value) && (value.startsWith('=') || /{{.*?}}/.test(value));
   }
 
-  /**
-   * Retrieve variable names from a given feelers template.
-   *
-   * @param {string} template
-   *
-   * @returns {string[]}
+  /**
+   * Retrieve variable names from a given feelers template.
+   *
+   * @param {string} template
+   *
+   * @returns {string[]}
    */
   getVariableNames(template) {
     if (!this.isTemplate(template)) {
@@ -336,17 +336,17 @@ class FeelersTemplating {
     }, []);
   }
 
-  /**
-   * Evaluate a template.
-   *
-   * @param {string} template
-   * @param {Object<string, any>} context
-   * @param {Object} options
-   * @param {boolean} [options.debug = false]
-   * @param {boolean} [options.strict = false]
-   * @param {Function} [options.buildDebugString]
-   *
-   * @returns
+  /**
+   * Evaluate a template.
+   *
+   * @param {string} template
+   * @param {Object<string, any>} context
+   * @param {Object} options
+   * @param {boolean} [options.debug = false]
+   * @param {boolean} [options.strict = false]
+   * @param {Function} [options.buildDebugString]
+   *
+   * @returns
    */
   evaluate(template, context = {}, options = {}) {
     const {
@@ -361,22 +361,22 @@ class FeelersTemplating {
     });
   }
 
-  /**
-  * @typedef {Object} ExpressionWithDepth
-  * @property {number} depth - The depth of the expression in the syntax tree.
-  * @property {string} expression - The extracted expression
+  /**
+  * @typedef {Object} ExpressionWithDepth
+  * @property {number} depth - The depth of the expression in the syntax tree.
+  * @property {string} expression - The extracted expression
   */
 
-  /**
-  * Extracts all feel expressions in the template along with their depth in the syntax tree.
-  * The depth is incremented for child expressions of loops to account for context drilling.
-   * @name extractExpressionsWithDepth
-  * @param {string} template - A feelers template string.
-  * @returns {Array<ExpressionWithDepth>} An array of objects, each containing the depth and the extracted expression.
-  *
-  * @example
-  * const template = "Hello {{user}}, you have:{{#loop items}}\n- {{amount}} {{name}}{{/loop}}.";
-  * const extractedExpressions = _extractExpressionsWithDepth(template);
+  /**
+  * Extracts all feel expressions in the template along with their depth in the syntax tree.
+  * The depth is incremented for child expressions of loops to account for context drilling.
+  * @name extractExpressionsWithDepth
+  * @param {string} template - A feelers template string.
+  * @returns {Array<ExpressionWithDepth>} An array of objects, each containing the depth and the extracted expression.
+  *
+  * @example
+  * const template = "Hello {{user}}, you have:{{#loop items}}\n- {{amount}} {{name}}{{/loop}}.";
+  * const extractedExpressions = _extractExpressionsWithDepth(template);
   */
   _extractExpressionsWithDepth(template) {
     // build simplified feelers syntax tree
@@ -482,10 +482,10 @@ function createInjector(bootstrapModules) {
   return injector;
 }
 
-/**
- * @param {string?} prefix
- *
- * @returns Element
+/**
+ * @param {string?} prefix
+ *
+ * @returns Element
  */
 function createFormContainer(prefix = 'fjs') {
   const container = document.createElement('div');
@@ -522,22 +522,22 @@ function generateIdForType(type) {
   return `${type}${generateIndexForType(type)}`;
 }
 
-/**
- * @template T
- * @param {T} data
- * @param {(this: any, key: string, value: any) => any} [replacer]
- * @return {T}
+/**
+ * @template T
+ * @param {T} data
+ * @param {(this: any, key: string, value: any) => any} [replacer]
+ * @return {T}
  */
 function clone(data, replacer) {
   return JSON.parse(JSON.stringify(data, replacer));
 }
 
-/**
- * Parse the schema for input variables a form might make use of
- *
- * @param {any} schema
- *
- * @return {string[]}
+/**
+ * Parse the schema for input variables a form might make use of
+ *
+ * @param {any} schema
+ *
+ * @return {string[]}
  */
 function getSchemaVariables(schema, options = {}) {
   const {
@@ -622,9 +622,9 @@ function runRecursively(formField, fn) {
   fn(formField);
 }
 
-/**
- * @typedef {object} Condition
- * @property {string} [hide]
+/**
+ * @typedef {object} Condition
+ * @property {string} [hide]
  */
 
 class ConditionChecker {
@@ -634,11 +634,11 @@ class ConditionChecker {
     this._eventBus = eventBus;
   }
 
-  /**
-   * For given data, remove properties based on condition.
-   *
-   * @param {Object<string, any>} properties
-   * @param {Object<string, any>} data
+  /**
+   * For given data, remove properties based on condition.
+   *
+   * @param {Object<string, any>} properties
+   * @param {Object<string, any>} data
    */
   applyConditions(properties, data = {}) {
     const newProperties = clone(properties);
@@ -665,13 +665,13 @@ class ConditionChecker {
     return newProperties;
   }
 
-  /**
-   * Check if given condition is met. Returns null for invalid/missing conditions.
-   *
-   * @param {string} condition
-   * @param {import('../../types').Data} [data]
-   *
-   * @returns {boolean|null}
+  /**
+   * Check if given condition is met. Returns null for invalid/missing conditions.
+   *
+   * @param {string} condition
+   * @param {import('../../types').Data} [data]
+   *
+   * @returns {boolean|null}
    */
   check(condition, data = {}) {
     if (!condition) {
@@ -692,12 +692,12 @@ class ConditionChecker {
     }
   }
 
-  /**
-   * Check if hide condition is met.
-   *
-   * @param {Condition} condition
-   * @param {Object<string, any>} data
-   * @returns {boolean}
+  /**
+   * Check if hide condition is met.
+   *
+   * @param {Condition} condition
+   * @param {Object<string, any>} data
+   * @returns {boolean}
    */
   _checkHideCondition(condition, data) {
     if (!condition.hide) {
@@ -733,12 +733,12 @@ class MarkdownRenderer {
     this._converter = new showdown.Converter();
   }
 
-  /**
-   * Render markdown to HTML.
-   *
-   * @param {string} markdown - The markdown to render
-   *
-   * @returns {string} HTML
+  /**
+   * Render markdown to HTML.
+   *
+   * @param {string} markdown - The markdown to render
+   *
+   * @returns {string} HTML
    */
   render(markdown) {
     return this._converter.makeHtml(markdown);
@@ -1886,8 +1886,8 @@ Validator.$inject = ['expressionLanguage', 'conditionChecker', 'form'];
 
 // helpers //////////
 
-/**
- * Helper function to evaluate optional FEEL validation values.
+/**
+ * Helper function to evaluate optional FEEL validation values.
  */
 function evaluateFEELValues(validate, expressionLanguage, conditionChecker, form) {
   const evaluatedValidate = {
@@ -1921,12 +1921,12 @@ function evaluateFEELValues(validate, expressionLanguage, conditionChecker, form
 }
 
 class Importer {
-  /**
-   * @constructor
-   * @param { import('./FormFieldRegistry').default } formFieldRegistry
-   * @param { import('./PathRegistry').default } pathRegistry
-   * @param { import('./FieldFactory').default } fieldFactory
-   * @param { import('./FormLayouter').default } formLayouter
+  /**
+   * @constructor
+   * @param { import('./FormFieldRegistry').default } formFieldRegistry
+   * @param { import('./PathRegistry').default } pathRegistry
+   * @param { import('./FieldFactory').default } fieldFactory
+   * @param { import('./FormLayouter').default } formLayouter
    */
   constructor(formFieldRegistry, pathRegistry, fieldFactory, formLayouter) {
     this._formFieldRegistry = formFieldRegistry;
@@ -1935,21 +1935,21 @@ class Importer {
     this._formLayouter = formLayouter;
   }
 
-  /**
-   * Import schema creating rows, fields, attaching additional
-   * information to each field and adding fields to the
-   * field registry.
-   *
-   * Additional information attached:
-   *
-   *   * `id` (unless present)
-   *   * `_parent`
-   *   * `_path`
-   *
-   * @param {any} schema
-   *
-   * @typedef {{ warnings: Error[], schema: any }} ImportResult
-   * @returns {ImportResult}
+  /**
+   * Import schema creating rows, fields, attaching additional
+   * information to each field and adding fields to the
+   * field registry.
+   *
+   * Additional information attached:
+   *
+   *   * `id` (unless present)
+   *   * `_parent`
+   *   * `_path`
+   *
+   * @param {any} schema
+   *
+   * @typedef {{ warnings: Error[], schema: any }} ImportResult
+   * @returns {ImportResult}
    */
   importSchema(schema) {
     // TODO: Add warnings
@@ -1974,12 +1974,12 @@ class Importer {
     this._pathRegistry.clear();
   }
 
-  /**
-   * @param {{[x: string]: any}} fieldAttrs
-   * @param {String} [parentId]
-   * @param {number} [index]
-   *
-   * @return {any} field
+  /**
+   * @param {{[x: string]: any}} fieldAttrs
+   * @param {String} [parentId]
+   * @param {number} [index]
+   *
+   * @return {any} field
    */
   importFormField(fieldAttrs, parentId, index) {
     const {
@@ -2004,11 +2004,11 @@ class Importer {
     return field;
   }
 
-  /**
-   * @param {Array<any>} components
-   * @param {string} parentId
-   *
-   * @return {Array<any>} imported components
+  /**
+   * @param {Array<any>} components
+   * @param {string} parentId
+   *
+   * @return {Array<any>} imported components
    */
   importFormFields(components, parentId) {
     return components.map((component, index) => {
@@ -2019,11 +2019,11 @@ class Importer {
 Importer.$inject = ['formFieldRegistry', 'pathRegistry', 'fieldFactory', 'formLayouter'];
 
 class FieldFactory {
-  /**
-   * @constructor
-   *
-   * @param  formFieldRegistry
-   * @param  formFields
+  /**
+   * @constructor
+   *
+   * @param  formFieldRegistry
+   * @param  formFields
    */
   constructor(formFieldRegistry, pathRegistry, formFields) {
     this._formFieldRegistry = formFieldRegistry;
@@ -2105,36 +2105,36 @@ class FieldFactory {
 }
 FieldFactory.$inject = ['formFieldRegistry', 'pathRegistry', 'formFields'];
 
-/**
- * The PathRegistry class manages a hierarchical structure of paths associated with form fields.
- * It enables claiming, unclaiming, and validating paths within this structure.
- *
- * Example Tree Structure:
- *
- *   [
- *     {
- *       segment: 'root',
- *       claimCount: 1,
- *       children: [
- *         {
- *           segment: 'child1',
- *           claimCount: 2,
- *           children: null  // A leaf node (closed path)
- *         },
- *         {
- *           segment: 'child2',
- *           claimCount: 1,
- *           children: [
- *             {
- *               segment: 'subChild1',
- *               claimCount: 1,
- *               children: []  // An open node (open path)
- *             }
- *           ]
- *         }
- *       ]
- *     }
- *   ]
+/**
+ * The PathRegistry class manages a hierarchical structure of paths associated with form fields.
+ * It enables claiming, unclaiming, and validating paths within this structure.
+ *
+ * Example Tree Structure:
+ *
+ *   [
+ *     {
+ *       segment: 'root',
+ *       claimCount: 1,
+ *       children: [
+ *         {
+ *           segment: 'child1',
+ *           claimCount: 2,
+ *           children: null  // A leaf node (closed path)
+ *         },
+ *         {
+ *           segment: 'child2',
+ *           claimCount: 1,
+ *           children: [
+ *             {
+ *               segment: 'subChild1',
+ *               claimCount: 1,
+ *               children: []  // An open node (open path)
+ *             }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   ]
  */
 class PathRegistry {
   constructor(formFieldRegistry, formFields) {
@@ -2217,16 +2217,16 @@ class PathRegistry {
     }
   }
 
-  /**
-   * Applies a function (fn) recursively on a given field and its children.
-   *
-   * - `field`: Starting field object.
-   * - `fn`: Function to apply.
-   * - `context`: Optional object for passing data between calls.
-   *
-   * Stops early if `fn` returns `false`. Useful for traversing the form field tree.
-   *
-   * @returns {boolean} Success status based on function execution.
+  /**
+   * Applies a function (fn) recursively on a given field and its children.
+   *
+   * - `field`: Starting field object.
+   * - `fn`: Function to apply.
+   * - `context`: Optional object for passing data between calls.
+   *
+   * Stops early if `fn` returns `false`. Useful for traversing the form field tree.
+   *
+   * @returns {boolean} Success status based on function execution.
    */
   executeRecursivelyOnFields(field, fn, context = {}) {
     let result = true;
@@ -2260,15 +2260,15 @@ class PathRegistry {
     return result;
   }
 
-  /**
-   * Generates an array representing the binding path to an underlying data object for a form field.
-   *
-   * @param {Object} field - The field object with properties: `key`, `path`, `id`, and optionally `_parent`.
-   * @param {Object} [options={}] - Configuration options.
-   * @param {Object} [options.replacements={}] - A map of field IDs to alternative path arrays.
-   * @param {Object} [options.cutoffNode] - The ID of the parent field at which to stop generating the path.
-   *
-   * @returns {(Array<string>|undefined)} An array of strings representing the binding path, or undefined if not determinable.
+  /**
+   * Generates an array representing the binding path to an underlying data object for a form field.
+   *
+   * @param {Object} field - The field object with properties: `key`, `path`, `id`, and optionally `_parent`.
+   * @param {Object} [options={}] - Configuration options.
+   * @param {Object} [options.replacements={}] - A map of field IDs to alternative path arrays.
+   * @param {Object} [options.cutoffNode] - The ID of the parent field at which to stop generating the path.
+   *
+   * @returns {(Array<string>|undefined)} An array of strings representing the binding path, or undefined if not determinable.
    */
   getValuePath(field, options = {}) {
     const {
@@ -2312,23 +2312,23 @@ const _getNextSegment = (node, segment) => {
 };
 PathRegistry.$inject = ['formFieldRegistry', 'formFields'];
 
-/**
- * @typedef { { id: String, components: Array<String> } } FormRow
- * @typedef { { formFieldId: String, rows: Array<FormRow> } } FormRows
+/**
+ * @typedef { { id: String, components: Array<String> } } FormRow
+ * @typedef { { formFieldId: String, rows: Array<FormRow> } } FormRows
  */
 
-/**
- * Maintains the Form layout in a given structure, for example
- *
- *  [
- *    {
- *      formFieldId: 'FormField_1',
- *      rows: [
- *        { id: 'Row_1', components: [ 'Text_1', 'Textdield_1', ... ]  }
- *      ]
- *    }
- *  ]
- *
+/**
+ * Maintains the Form layout in a given structure, for example
+ *
+ *  [
+ *    {
+ *      formFieldId: 'FormField_1',
+ *      rows: [
+ *        { id: 'Row_1', components: [ 'Text_1', 'Textdield_1', ... ]  }
+ *      ]
+ *    }
+ *  ]
+ *
  */
 class FormLayouter {
   constructor(eventBus) {
@@ -2338,8 +2338,8 @@ class FormLayouter {
     this._eventBus = eventBus;
   }
 
-  /**
-   * @param {FormRow} row
+  /**
+   * @param {FormRow} row
    */
   addRow(formFieldId, row) {
     let rowsPerComponent = this._rows.find(r => r.formFieldId === formFieldId);
@@ -2353,18 +2353,18 @@ class FormLayouter {
     rowsPerComponent.rows.push(row);
   }
 
-  /**
-   * @param {String} id
-   * @returns {FormRow}
+  /**
+   * @param {String} id
+   * @returns {FormRow}
    */
   getRow(id) {
     const rows = allRows(this._rows);
     return rows.find(r => r.id === id);
   }
 
-  /**
-   * @param {any} formField
-   * @returns {FormRow}
+  /**
+   * @param {any} formField
+   * @returns {FormRow}
    */
   getRowForField(formField) {
     return allRows(this._rows).find(r => {
@@ -2375,9 +2375,9 @@ class FormLayouter {
     });
   }
 
-  /**
-   * @param {String} formFieldId
-   * @returns { Array<FormRow> }
+  /**
+   * @param {String} formFieldId
+   * @returns { Array<FormRow> }
    */
   getRows(formFieldId) {
     const rowsForField = this._rows.find(r => formFieldId === r.formFieldId);
@@ -2387,15 +2387,15 @@ class FormLayouter {
     return rowsForField.rows;
   }
 
-  /**
-   * @returns {string}
+  /**
+   * @returns {string}
    */
   nextRowId() {
     return this._ids.nextPrefixed('Row_');
   }
 
-  /**
-   * @param {any} formField
+  /**
+   * @param {any} formField
    */
   calculateLayout(formField) {
     const {
@@ -2449,9 +2449,9 @@ function groupByRow(components, ids) {
   });
 }
 
-/**
- * @param {Array<FormRows>} formRows
- * @returns {Array<FormRow>}
+/**
+ * @param {Array<FormRows>} formRows
+ * @returns {Array<FormRow>}
  */
 function allRows(formRows) {
   return minDash.flatten(formRows.map(c => c.rows));
@@ -2607,11 +2607,11 @@ const FormRenderContext = preact.createContext({
 });
 var FormRenderContext$1 = FormRenderContext;
 
-/**
- * @param {string} type
- * @param {boolean} [strict]
- *
- * @returns {any}
+/**
+ * @param {string} type
+ * @param {boolean} [strict]
+ *
+ * @returns {any}
  */
 function getService(type, strict) {}
 const FormContext = preact.createContext({
@@ -2627,10 +2627,10 @@ function useService(type, strict) {
   return getService(type, strict);
 }
 
-/**
- * Returns the conditionally filtered data of a form reactively.
- * Memoised to minimize re-renders
- *
+/**
+ * Returns the conditionally filtered data of a form reactively.
+ * Memoised to minimize re-renders
+ *
  */
 function useFilteredFormData() {
   const {
@@ -2647,12 +2647,12 @@ function useFilteredFormData() {
   }, [conditionChecker, data, initialData]);
 }
 
-/**
- * Evaluate if condition is met reactively based on the conditionChecker and form data.
- *
- * @param {string | undefined} condition
- *
- * @returns {boolean} true if condition is met or no condition or condition checker exists
+/**
+ * Evaluate if condition is met reactively based on the conditionChecker and form data.
+ *
+ * @param {string | undefined} condition
+ *
+ * @returns {boolean} true if condition is met or no condition or condition checker exists
  */
 function useCondition(condition) {
   const conditionChecker = useService('conditionChecker', false);
@@ -2662,13 +2662,13 @@ function useCondition(condition) {
   }, [conditionChecker, condition, filteredData]);
 }
 
-/**
- * Evaluate a string reactively based on the expressionLanguage and form data.
- * If the string is not an expression, it is returned as is.
- * Memoised to minimize re-renders.
- *
- * @param {string} value
- *
+/**
+ * Evaluate a string reactively based on the expressionLanguage and form data.
+ * If the string is not an expression, it is returned as is.
+ * Memoised to minimize re-renders.
+ *
+ * @param {string} value
+ *
  */
 function useExpressionEvaluation(value) {
   const formData = useFilteredFormData();
@@ -2697,16 +2697,16 @@ function useKeyDownAction(targetKey, action, listenerElement = window) {
   });
 }
 
-/**
- * Retrieve readonly value of a form field, given it can be an
- * expression optionally or configured globally.
- *
- * @typedef { import('../../types').FormProperties } FormProperties
- *
- * @param {any} formField
- * @param {FormProperties} properties
- *
- * @returns {boolean}
+/**
+ * Retrieve readonly value of a form field, given it can be an
+ * expression optionally or configured globally.
+ *
+ * @typedef { import('../../types').FormProperties } FormProperties
+ *
+ * @param {any} formField
+ * @param {FormProperties} properties
+ *
+ * @returns {boolean}
  */
 function useReadonly(formField, properties = {}) {
   const expressionLanguage = useService('expressionLanguage');
@@ -2724,16 +2724,47 @@ function useReadonly(formField, properties = {}) {
   return readonly || false;
 }
 
-/**
- * Template a string reactively based on form data. If the string is not a template, it is returned as is.
- * Memoised to minimize re-renders
- *
- * @param {string} value
- * @param {Object} options
- * @param {boolean} [options.debug = false]
- * @param {boolean} [options.strict = false]
- * @param {Function} [options.buildDebugString]
- *
+function usePrevious(value, defaultValue, dependencies) {
+  const ref = hooks.useRef(defaultValue);
+  hooks.useEffect(() => ref.current = value, dependencies);
+  return ref.current;
+}
+
+/**
+ * A custom hook to manage state changes with deep comparison.
+ *
+ * @param {any} value - The current value to manage.
+ * @param {any} defaultValue - The initial default value for the state.
+ * @returns {any} - Returns the current state.
+ */
+function useDeepCompareState(value, defaultValue) {
+  const [state, setState] = hooks.useState(defaultValue);
+  const previous = usePrevious(value, defaultValue, [value]);
+  const changed = !compare(previous, value);
+  hooks.useEffect(() => {
+    if (changed) {
+      setState(value);
+    }
+  }, [changed, value]);
+  return state;
+}
+
+// helpers //////////////////////////
+
+function compare(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Template a string reactively based on form data. If the string is not a template, it is returned as is.
+ * Memoised to minimize re-renders
+ *
+ * @param {string} value
+ * @param {Object} options
+ * @param {boolean} [options.debug = false]
+ * @param {boolean} [options.strict = false]
+ * @param {Function} [options.buildDebugString]
+ *
  */
 function useTemplateEvaluation(value, options) {
   const filteredData = useFilteredFormData();
@@ -2746,17 +2777,17 @@ function useTemplateEvaluation(value, options) {
   }, [filteredData, templating, value, options]);
 }
 
-/**
- * Template a string reactively based on form data. If the string is not a template, it is returned as is.
- * If the string contains multiple lines, only the first line is returned.
- * Memoised to minimize re-renders
- *
- * @param {string} value
- * @param {Object} [options]
- * @param {boolean} [options.debug = false]
- * @param {boolean} [options.strict = false]
- * @param {Function} [options.buildDebugString]
- *
+/**
+ * Template a string reactively based on form data. If the string is not a template, it is returned as is.
+ * If the string contains multiple lines, only the first line is returned.
+ * Memoised to minimize re-renders
+ *
+ * @param {string} value
+ * @param {Object} [options]
+ * @param {boolean} [options.debug = false]
+ * @param {boolean} [options.strict = false]
+ * @param {Function} [options.buildDebugString]
+ *
  */
 function useSingleLineTemplateEvaluation(value, options = {}) {
   const evaluatedTemplate = useTemplateEvaluation(value, options);
@@ -2960,8 +2991,8 @@ function createEmptyOptions(options = {}) {
   };
 }
 
-/**
- * @enum { String }
+/**
+ * @enum { String }
  */
 const LOAD_STATES = {
   LOADING: 'loading',
@@ -2969,17 +3000,17 @@ const LOAD_STATES = {
   ERROR: 'error'
 };
 
-/**
- * @typedef {Object} ValuesGetter
- * @property {Object[]} values - The values data
- * @property {(LOAD_STATES)} state - The values data's loading state, to use for conditional rendering
+/**
+ * @typedef {Object} ValuesGetter
+ * @property {Object[]} values - The values data
+ * @property {(LOAD_STATES)} state - The values data's loading state, to use for conditional rendering
  */
 
-/**
- * A hook to load values for single and multiselect components.
- *
- * @param {Object} field - The form field to handle values for
- * @return {ValuesGetter} valuesGetter - A values getter object providing loading state and values
+/**
+ * A hook to load values for single and multiselect components.
+ *
+ * @param {Object} field - The form field to handle values for
+ * @return {ValuesGetter} valuesGetter - A values getter object providing loading state and values
  */
 function useValuesAsync (field) {
   const {
@@ -2993,11 +3024,8 @@ function useValuesAsync (field) {
     state: LOAD_STATES.LOADING
   });
   const initialData = useService('form')._getState().initialData;
-  const evaluatedValues = hooks.useMemo(() => {
-    if (valuesExpression) {
-      return useExpressionEvaluation(valuesExpression);
-    }
-  }, [valuesExpression]);
+  const expressionEvaluation = useExpressionEvaluation(valuesExpression);
+  const evaluatedValues = useDeepCompareState(expressionEvaluation || [], []);
   hooks.useEffect(() => {
     let values = [];
 
@@ -3013,8 +3041,10 @@ function useValuesAsync (field) {
       values = Array.isArray(staticValues) ? staticValues : [];
 
       // expression
-    } else if (evaluatedValues && Array.isArray(evaluatedValues)) {
-      values = evaluatedValues;
+    } else if (valuesExpression) {
+      if (evaluatedValues && Array.isArray(evaluatedValues)) {
+        values = evaluatedValues;
+      }
     } else {
       setValuesGetter(buildErrorState('No values source defined in the form definition'));
       return;
@@ -3023,7 +3053,7 @@ function useValuesAsync (field) {
     // normalize data to support primitives and partially defined objects
     values = normalizeValuesData(values);
     setValuesGetter(buildLoadedState(values));
-  }, [valuesKey, staticValues, initialData]);
+  }, [valuesKey, staticValues, initialData, valuesExpression, evaluatedValues]);
   return valuesGetter;
 }
 const buildErrorState = error => ({
@@ -3489,12 +3519,12 @@ var SvgCalendar = function SvgCalendar(props) {
 };
 var CalendarIcon = SvgCalendar;
 
-/**
- * Returns date format for the provided locale.
- * If the locale is not provided, uses the browser's locale.
- *
- * @param {string} [locale] - The locale to get date format for.
- * @returns {string} The date format for the locale.
+/**
+ * Returns date format for the provided locale.
+ * If the locale is not provided, uses the browser's locale.
+ *
+ * @param {string} [locale] - The locale to get date format for.
+ * @returns {string} The date format for the locale.
  */
 function getLocaleDateFormat(locale = 'default') {
   const parts = new Intl.DateTimeFormat(locale).formatToParts(new Date(Date.UTC(2020, 5, 5)));
@@ -3513,12 +3543,12 @@ function getLocaleDateFormat(locale = 'default') {
   }).join('');
 }
 
-/**
- * Returns readable date format for the provided locale.
- * If the locale is not provided, uses the browser's locale.
- *
- * @param {string} [locale] - The locale to get readable date format for.
- * @returns {string} The readable date format for the locale.
+/**
+ * Returns readable date format for the provided locale.
+ * If the locale is not provided, uses the browser's locale.
+ *
+ * @param {string} [locale] - The locale to get readable date format for.
+ * @returns {string} The readable date format for the locale.
  */
 function getLocaleReadableDateFormat(locale) {
   let format = getLocaleDateFormat(locale).toLowerCase();
@@ -3535,12 +3565,12 @@ function getLocaleReadableDateFormat(locale) {
   return format;
 }
 
-/**
- * Returns flatpickr config for the provided locale.
- * If the locale is not provided, uses the browser's locale.
- *
- * @param {string} [locale] - The locale to get flatpickr config for.
- * @returns {object} The flatpickr config for the locale.
+/**
+ * Returns flatpickr config for the provided locale.
+ * If the locale is not provided, uses the browser's locale.
+ *
+ * @param {string} [locale] - The locale to get flatpickr config for.
+ * @returns {object} The flatpickr config for the locale.
  */
 function getLocaleDateFlatpickrConfig(locale) {
   return flatpickerizeDateFormat(getLocaleDateFormat(locale));
@@ -3808,7 +3838,8 @@ function DropdownList(props) {
   hooks.useEffect(() => {
     const individualEntries = dropdownContainer.current.children;
     if (individualEntries.length && !mouseControl) {
-      individualEntries[focusedValueIndex].scrollIntoView({
+      const focusedEntry = individualEntries[focusedValueIndex];
+      focusedEntry && focusedEntry.scrollIntoView({
         block: 'nearest',
         inline: 'nearest'
       });
@@ -4219,10 +4250,10 @@ Datetime.config = {
   }
 };
 
-/**
- * This file must not be changed or exchanged.
- *
- * @see http://bpmn.io/license for more information.
+/**
+ * This file must not be changed or exchanged.
+ *
+ * @see http://bpmn.io/license for more information.
  */
 function Logo() {
   return jsxRuntime.jsxs("svg", {
@@ -4400,11 +4431,11 @@ const ATTR_WHITESPACE_PATTERN = /[\u0000-\u0020\u00A0\u1680\u180E\u2000-\u2029\u
 
 const FORM_ELEMENT = document.createElement('form');
 
-/**
- * Sanitize a HTML string and return the cleaned, safe version.
- *
- * @param {string} html
- * @return {string}
+/**
+ * Sanitize a HTML string and return the cleaned, safe version.
+ *
+ * @param {string} html
+ * @return {string}
  */
 
 // see https://github.com/developit/snarkdown/issues/70
@@ -4422,29 +4453,29 @@ function sanitizeHTML(html) {
   }
 }
 
-/**
- * Sanitizes an image source to ensure we only allow for data URI and links
- * that start with http(s).
- *
- * Note: Most browsers anyway do not support script execution in <img> elements.
- *
- * @param {string} src
- * @returns {string}
+/**
+ * Sanitizes an image source to ensure we only allow for data URI and links
+ * that start with http(s).
+ *
+ * Note: Most browsers anyway do not support script execution in <img> elements.
+ *
+ * @param {string} src
+ * @returns {string}
  */
 function sanitizeImageSource(src) {
   const valid = ALLOWED_IMAGE_SRC_PATTERN.test(src);
   return valid ? src : '';
 }
 
-/**
- * Recursively sanitize a HTML node, potentially
- * removing it, its children or attributes.
- *
- * Inspired by https://github.com/developit/snarkdown/issues/70
- * and https://github.com/cure53/DOMPurify. Simplified
- * for our use-case.
- *
- * @param {Element} node
+/**
+ * Recursively sanitize a HTML node, potentially
+ * removing it, its children or attributes.
+ *
+ * Inspired by https://github.com/developit/snarkdown/issues/70
+ * and https://github.com/cure53/DOMPurify. Simplified
+ * for our use-case.
+ *
+ * @param {Element} node
  */
 function sanitizeNode(node) {
   // allow text nodes
@@ -4488,13 +4519,13 @@ function sanitizeNode(node) {
   }
 }
 
-/**
- * Validates attributes for validity.
- *
- * @param {string} lcTag
- * @param {string} lcName
- * @param {string} value
- * @return {boolean}
+/**
+ * Validates attributes for validity.
+ *
+ * @param {string} lcTag
+ * @param {string} lcName
+ * @param {string} value
+ * @return {boolean}
  */
 function isValidAttribute(lcTag, lcName, value) {
   // disallow most attributes based on whitelist
@@ -6222,55 +6253,55 @@ var core = {
   validator: ['type', Validator]
 };
 
-/**
- * @typedef { import('./types').Injector } Injector
- * @typedef { import('./types').Data } Data
- * @typedef { import('./types').Errors } Errors
- * @typedef { import('./types').Schema } Schema
- * @typedef { import('./types').FormProperties } FormProperties
- * @typedef { import('./types').FormProperty } FormProperty
- * @typedef { import('./types').FormEvent } FormEvent
- * @typedef { import('./types').FormOptions } FormOptions
- *
- * @typedef { {
- *   data: Data,
- *   initialData: Data,
- *   errors: Errors,
- *   properties: FormProperties,
- *   schema: Schema
- * } } State
- *
- * @typedef { (type:FormEvent, priority:number, handler:Function) => void } OnEventWithPriority
- * @typedef { (type:FormEvent, handler:Function) => void } OnEventWithOutPriority
- * @typedef { OnEventWithPriority & OnEventWithOutPriority } OnEventType
+/**
+ * @typedef { import('./types').Injector } Injector
+ * @typedef { import('./types').Data } Data
+ * @typedef { import('./types').Errors } Errors
+ * @typedef { import('./types').Schema } Schema
+ * @typedef { import('./types').FormProperties } FormProperties
+ * @typedef { import('./types').FormProperty } FormProperty
+ * @typedef { import('./types').FormEvent } FormEvent
+ * @typedef { import('./types').FormOptions } FormOptions
+ *
+ * @typedef { {
+ *   data: Data,
+ *   initialData: Data,
+ *   errors: Errors,
+ *   properties: FormProperties,
+ *   schema: Schema
+ * } } State
+ *
+ * @typedef { (type:FormEvent, priority:number, handler:Function) => void } OnEventWithPriority
+ * @typedef { (type:FormEvent, handler:Function) => void } OnEventWithOutPriority
+ * @typedef { OnEventWithPriority & OnEventWithOutPriority } OnEventType
  */
 
 const ids = new Ids([32, 36, 1]);
 
-/**
- * The form.
+/**
+ * The form.
  */
 class Form {
-  /**
-   * @constructor
-   * @param {FormOptions} options
+  /**
+   * @constructor
+   * @param {FormOptions} options
    */
   constructor(options = {}) {
-    /**
-     * @public
-     * @type {OnEventType}
+    /**
+     * @public
+     * @type {OnEventType}
      */
     this.on = this._onEvent;
 
-    /**
-     * @public
-     * @type {String}
+    /**
+     * @public
+     * @type {String}
      */
     this._id = ids.next();
 
-    /**
-     * @private
-     * @type {Element}
+    /**
+     * @private
+     * @type {Element}
      */
     this._container = createFormContainer();
     const {
@@ -6279,9 +6310,9 @@ class Form {
       properties = {}
     } = options;
 
-    /**
-     * @private
-     * @type {State}
+    /**
+     * @private
+     * @type {State}
      */
     this._state = {
       initialData: null,
@@ -6305,9 +6336,9 @@ class Form {
     this._emit('form.clear');
   }
 
-  /**
-   * Destroy the form, removing it from DOM,
-   * if attached.
+  /**
+   * Destroy the form, removing it from DOM,
+   * if attached.
    */
   destroy() {
     // destroy form services
@@ -6318,13 +6349,13 @@ class Form {
     this._detach(false);
   }
 
-  /**
-   * Open a form schema with the given initial data.
-   *
-   * @param {Schema} schema
-   * @param {Data} [data]
-   *
-   * @return Promise<{ warnings: Array<any> }>
+  /**
+   * Open a form schema with the given initial data.
+   *
+   * @param {Schema} schema
+   * @param {Data} [data]
+   *
+   * @return Promise<{ warnings: Array<any> }>
    */
   importSchema(schema, data = {}) {
     return new Promise((resolve, reject) => {
@@ -6357,10 +6388,10 @@ class Form {
     });
   }
 
-  /**
-   * Submit the form, triggering all field validations.
-   *
-   * @returns { { data: Data, errors: Errors } }
+  /**
+   * Submit the form, triggering all field validations.
+   *
+   * @returns { { data: Data, errors: Errors } }
    */
   submit() {
     const {
@@ -6387,8 +6418,8 @@ class Form {
     });
   }
 
-  /**
-   * @returns {Errors}
+  /**
+   * @returns {Errors}
    */
   validate() {
     const formFieldRegistry = this.get('formFieldRegistry'),
@@ -6414,8 +6445,8 @@ class Form {
     return errors;
   }
 
-  /**
-   * @param {Element|string} parentNode
+  /**
+   * @param {Element|string} parentNode
    */
   attachTo(parentNode) {
     if (!parentNode) {
@@ -6433,10 +6464,10 @@ class Form {
     this._detach();
   }
 
-  /**
-   * @private
-   *
-   * @param {boolean} [emit]
+  /**
+   * @private
+   *
+   * @param {boolean} [emit]
    */
   _detach(emit = true) {
     const container = this._container,
@@ -6450,9 +6481,9 @@ class Form {
     parentNode.removeChild(container);
   }
 
-  /**
-   * @param {FormProperty} property
-   * @param {any} value
+  /**
+   * @param {FormProperty} property
+   * @param {any} value
    */
   setProperty(property, value) {
     const properties = minDash.set(this._getState().properties, [property], value);
@@ -6461,21 +6492,21 @@ class Form {
     });
   }
 
-  /**
-   * @param {FormEvent} type
-   * @param {Function} handler
+  /**
+   * @param {FormEvent} type
+   * @param {Function} handler
    */
   off(type, handler) {
     this.get('eventBus').off(type, handler);
   }
 
-  /**
-   * @private
-   *
-   * @param {FormOptions} options
-   * @param {Element} container
-   *
-   * @returns {Injector}
+  /**
+   * @private
+   *
+   * @param {FormOptions} options
+   * @param {Element} container
+   *
+   * @returns {Injector}
    */
   _createInjector(options, container) {
     const {
@@ -6494,17 +6525,17 @@ class Form {
     }, core, ...modules, ...additionalModules]);
   }
 
-  /**
-   * @private
+  /**
+   * @private
    */
   _emit(type, data) {
     this.get('eventBus').fire(type, data);
   }
 
-  /**
-   * @internal
-   *
-   * @param { { add?: boolean, field: any, remove?: number, value?: any } } update
+  /**
+   * @internal
+   *
+   * @param { { add?: boolean, field: any, remove?: number, value?: any } } update
    */
   _update(update) {
     const {
@@ -6526,15 +6557,15 @@ class Form {
     });
   }
 
-  /**
-   * @internal
+  /**
+   * @internal
    */
   _getState() {
     return this._state;
   }
 
-  /**
-   * @internal
+  /**
+   * @internal
    */
   _setState(state) {
     this._state = {
@@ -6544,22 +6575,22 @@ class Form {
     this._emit('changed', this._getState());
   }
 
-  /**
-  * @internal
+  /**
+  * @internal
   */
   _getModules() {
     return [ExpressionLanguageModule, MarkdownModule, ViewerCommandsModule];
   }
 
-  /**
-   * @internal
+  /**
+   * @internal
    */
   _onEvent(type, priority, handler) {
     this.get('eventBus').on(type, priority, handler);
   }
 
-  /**
-   * @internal
+  /**
+   * @internal
    */
   _getSubmitData() {
     const formFieldRegistry = this.get('formFieldRegistry'),
@@ -6587,16 +6618,16 @@ class Form {
     return filteredSubmitData;
   }
 
-  /**
-   * @internal
+  /**
+   * @internal
    */
   _applyConditions(toFilter, data) {
     const conditionChecker = this.get('conditionChecker');
     return conditionChecker.applyConditions(toFilter, data);
   }
 
-  /**
-   * @internal
+  /**
+   * @internal
    */
   _initializeFieldData(data) {
     const formFieldRegistry = this.get('formFieldRegistry'),
@@ -6676,6 +6707,7 @@ exports.FieldFactory = FieldFactory;
 exports.Form = Form;
 exports.FormComponent = FormComponent;
 exports.FormContext = FormContext$1;
+exports.FormField = FormField;
 exports.FormFieldRegistry = FormFieldRegistry;
 exports.FormFields = FormFields;
 exports.FormLayouter = FormLayouter;