@opencrvs/toolkit 1.9.8-rc.34c53bf → 1.9.8-rc.48851c5

package/dist/commons/conditionals/conditionals.d.ts

@@ -70,6 +70,9 @@ type FieldReference = {
     $$field: string;
     $$subfield: string[];
 };
+type CodeToEvaluate = {
+    $$code: string;
+};
 /**
  * Generate conditional rules for current date
  */
@@ -89,6 +92,7 @@ export declare const user: typeof userSerializer & {
     };
 };
 export declare function isFieldReference(value: unknown): value is FieldReference;
+export declare function isCodeToEvaluate(value: unknown): value is CodeToEvaluate;
 /** Check if an event flag is present */
 export declare function flag(flagvalue: string): JSONSchema;
 /** Check if an event flag is present */
@@ -170,6 +174,99 @@ export declare function createFieldConditionals(fieldId: string): {
              */
             matches(pattern: string): JSONSchema;
             isBetween(min: number, max: number): JSONSchema;
+            /**
+             * Executes a custom validation function defined by country configuration.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted as part of the JSON Schema.
+             * It is deserialized just-in-time during validation on the client.
+             *
+             * @param fn - Validation function that receives the field value and form context.
+             *             Must return true if valid, false if invalid.
+             *
+             * @returns JSONSchema conditional for AJV validation
+             *
+             * @example
+             * // Simple age validation
+             * field('age').customClientValidator((value, ctx) => {
+             *   return value >= 18
+             * })
+             *
+             * @example
+             * // Cross-field validation: child DOB must be after mother DOB
+             * field('child.dob').customClientValidator((value, ctx) => {
+             *   const motherDob = ctx.$form['mother.dob']
+             *   if (!motherDob || !value) return false
+             *   return new Date(value) > new Date(motherDob)
+             * })
+             *
+             * @example
+             * // Two number fields validated together
+             * field('fieldA').customClientValidator((value, ctx) => {
+             *   const fieldB = ctx.$form['fieldB']
+             *   if (!fieldB) return false
+             *   return value + fieldB > 100
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend validation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Must return boolean: true = valid, false = invalid
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => boolean): JSONSchema;
+            /**
+             * Defines a client-side computation function for dynamic field values.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted to the client,
+             * where it is deserialized and executed to compute field values dynamically.
+             *
+             * @param fn - Computation function that receives the field value and form context.
+             *             Returns the computed value (any type).
+             *
+             * @returns CodeToEvaluate object for client-side execution
+             *
+             * @example
+             * // Concatenate first and last name
+             * field('fullName').customClientEvaluation((value, ctx) => {
+             *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+             * })
+             *
+             * @example
+             * // Calculate age from date of birth
+             * field('childAge').customClientEvaluation((value, ctx) => {
+             *   const dob = ctx.$form['child.dob']
+             *   if (!dob) return undefined
+             *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+             *   return age
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend computation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Should return the computed value (any type)
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => any): {
+                $$code: string;
+            };
             getId: () => {
                 fieldId: string;
             };
@@ -229,6 +326,99 @@ export declare function createFieldConditionals(fieldId: string): {
          */
         matches(pattern: string): JSONSchema;
         isBetween(min: number, max: number): JSONSchema;
+        /**
+         * Executes a custom validation function defined by country configuration.
+         *
+         * **Use this as a last resort when predefined toolkit methods are insufficient.**
+         *
+         * The function is serialized via toString() and transmitted as part of the JSON Schema.
+         * It is deserialized just-in-time during validation on the client.
+         *
+         * @param fn - Validation function that receives the field value and form context.
+         *             Must return true if valid, false if invalid.
+         *
+         * @returns JSONSchema conditional for AJV validation
+         *
+         * @example
+         * // Simple age validation
+         * field('age').customClientValidator((value, ctx) => {
+         *   return value >= 18
+         * })
+         *
+         * @example
+         * // Cross-field validation: child DOB must be after mother DOB
+         * field('child.dob').customClientValidator((value, ctx) => {
+         *   const motherDob = ctx.$form['mother.dob']
+         *   if (!motherDob || !value) return false
+         *   return new Date(value) > new Date(motherDob)
+         * })
+         *
+         * @example
+         * // Two number fields validated together
+         * field('fieldA').customClientValidator((value, ctx) => {
+         *   const fieldB = ctx.$form['fieldB']
+         *   if (!fieldB) return false
+         *   return value + fieldB > 100
+         * })
+         *
+         * @remarks
+         * Limitations:
+         * - Client-side only. For backend validation, use country config event triggers.
+         * - Cannot reference external libraries (lodash, etc.)
+         * - Function must be pure — no side effects, no closures over external state
+         * - Function must be serialisable via toString()
+         * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+         * - Must return boolean: true = valid, false = invalid
+         *
+         * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+         */
+        customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+            $form: EventState | Record<string, unknown>;
+        }) => boolean): JSONSchema;
+        /**
+         * Defines a client-side computation function for dynamic field values.
+         *
+         * **Use this as a last resort when predefined toolkit methods are insufficient.**
+         *
+         * The function is serialized via toString() and transmitted to the client,
+         * where it is deserialized and executed to compute field values dynamically.
+         *
+         * @param fn - Computation function that receives the field value and form context.
+         *             Returns the computed value (any type).
+         *
+         * @returns CodeToEvaluate object for client-side execution
+         *
+         * @example
+         * // Concatenate first and last name
+         * field('fullName').customClientEvaluation((value, ctx) => {
+         *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+         * })
+         *
+         * @example
+         * // Calculate age from date of birth
+         * field('childAge').customClientEvaluation((value, ctx) => {
+         *   const dob = ctx.$form['child.dob']
+         *   if (!dob) return undefined
+         *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+         *   return age
+         * })
+         *
+         * @remarks
+         * Limitations:
+         * - Client-side only. For backend computation, use country config event triggers.
+         * - Cannot reference external libraries (lodash, etc.)
+         * - Function must be pure — no side effects, no closures over external state
+         * - Function must be serialisable via toString()
+         * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+         * - Should return the computed value (any type)
+         *
+         * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+         */
+        customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+            $form: EventState | Record<string, unknown>;
+        }) => any): {
+            $$code: string;
+        };
         getId: () => {
             fieldId: string;
         };
@@ -302,6 +492,99 @@ export declare function createFieldConditionals(fieldId: string): {
              */
             matches(pattern: string): JSONSchema;
             isBetween(min: number, max: number): JSONSchema;
+            /**
+             * Executes a custom validation function defined by country configuration.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted as part of the JSON Schema.
+             * It is deserialized just-in-time during validation on the client.
+             *
+             * @param fn - Validation function that receives the field value and form context.
+             *             Must return true if valid, false if invalid.
+             *
+             * @returns JSONSchema conditional for AJV validation
+             *
+             * @example
+             * // Simple age validation
+             * field('age').customClientValidator((value, ctx) => {
+             *   return value >= 18
+             * })
+             *
+             * @example
+             * // Cross-field validation: child DOB must be after mother DOB
+             * field('child.dob').customClientValidator((value, ctx) => {
+             *   const motherDob = ctx.$form['mother.dob']
+             *   if (!motherDob || !value) return false
+             *   return new Date(value) > new Date(motherDob)
+             * })
+             *
+             * @example
+             * // Two number fields validated together
+             * field('fieldA').customClientValidator((value, ctx) => {
+             *   const fieldB = ctx.$form['fieldB']
+             *   if (!fieldB) return false
+             *   return value + fieldB > 100
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend validation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Must return boolean: true = valid, false = invalid
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => boolean): JSONSchema;
+            /**
+             * Defines a client-side computation function for dynamic field values.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted to the client,
+             * where it is deserialized and executed to compute field values dynamically.
+             *
+             * @param fn - Computation function that receives the field value and form context.
+             *             Returns the computed value (any type).
+             *
+             * @returns CodeToEvaluate object for client-side execution
+             *
+             * @example
+             * // Concatenate first and last name
+             * field('fullName').customClientEvaluation((value, ctx) => {
+             *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+             * })
+             *
+             * @example
+             * // Calculate age from date of birth
+             * field('childAge').customClientEvaluation((value, ctx) => {
+             *   const dob = ctx.$form['child.dob']
+             *   if (!dob) return undefined
+             *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+             *   return age
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend computation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Should return the computed value (any type)
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => any): {
+                $$code: string;
+            };
             getId: () => {
                 fieldId: string;
             };
@@ -370,6 +653,99 @@ export declare function createFieldConditionals(fieldId: string): {
              */
             matches(pattern: string): JSONSchema;
             isBetween(min: number, max: number): JSONSchema;
+            /**
+             * Executes a custom validation function defined by country configuration.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted as part of the JSON Schema.
+             * It is deserialized just-in-time during validation on the client.
+             *
+             * @param fn - Validation function that receives the field value and form context.
+             *             Must return true if valid, false if invalid.
+             *
+             * @returns JSONSchema conditional for AJV validation
+             *
+             * @example
+             * // Simple age validation
+             * field('age').customClientValidator((value, ctx) => {
+             *   return value >= 18
+             * })
+             *
+             * @example
+             * // Cross-field validation: child DOB must be after mother DOB
+             * field('child.dob').customClientValidator((value, ctx) => {
+             *   const motherDob = ctx.$form['mother.dob']
+             *   if (!motherDob || !value) return false
+             *   return new Date(value) > new Date(motherDob)
+             * })
+             *
+             * @example
+             * // Two number fields validated together
+             * field('fieldA').customClientValidator((value, ctx) => {
+             *   const fieldB = ctx.$form['fieldB']
+             *   if (!fieldB) return false
+             *   return value + fieldB > 100
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend validation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Must return boolean: true = valid, false = invalid
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => boolean): JSONSchema;
+            /**
+             * Defines a client-side computation function for dynamic field values.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted to the client,
+             * where it is deserialized and executed to compute field values dynamically.
+             *
+             * @param fn - Computation function that receives the field value and form context.
+             *             Returns the computed value (any type).
+             *
+             * @returns CodeToEvaluate object for client-side execution
+             *
+             * @example
+             * // Concatenate first and last name
+             * field('fullName').customClientEvaluation((value, ctx) => {
+             *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+             * })
+             *
+             * @example
+             * // Calculate age from date of birth
+             * field('childAge').customClientEvaluation((value, ctx) => {
+             *   const dob = ctx.$form['child.dob']
+             *   if (!dob) return undefined
+             *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+             *   return age
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend computation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Should return the computed value (any type)
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => any): {
+                $$code: string;
+            };
             getId: () => {
                 fieldId: string;
             };
@@ -437,6 +813,99 @@ export declare function createFieldConditionals(fieldId: string): {
              */
             matches(pattern: string): JSONSchema;
             isBetween(min: number, max: number): JSONSchema;
+            /**
+             * Executes a custom validation function defined by country configuration.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted as part of the JSON Schema.
+             * It is deserialized just-in-time during validation on the client.
+             *
+             * @param fn - Validation function that receives the field value and form context.
+             *             Must return true if valid, false if invalid.
+             *
+             * @returns JSONSchema conditional for AJV validation
+             *
+             * @example
+             * // Simple age validation
+             * field('age').customClientValidator((value, ctx) => {
+             *   return value >= 18
+             * })
+             *
+             * @example
+             * // Cross-field validation: child DOB must be after mother DOB
+             * field('child.dob').customClientValidator((value, ctx) => {
+             *   const motherDob = ctx.$form['mother.dob']
+             *   if (!motherDob || !value) return false
+             *   return new Date(value) > new Date(motherDob)
+             * })
+             *
+             * @example
+             * // Two number fields validated together
+             * field('fieldA').customClientValidator((value, ctx) => {
+             *   const fieldB = ctx.$form['fieldB']
+             *   if (!fieldB) return false
+             *   return value + fieldB > 100
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend validation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Must return boolean: true = valid, false = invalid
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => boolean): JSONSchema;
+            /**
+             * Defines a client-side computation function for dynamic field values.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted to the client,
+             * where it is deserialized and executed to compute field values dynamically.
+             *
+             * @param fn - Computation function that receives the field value and form context.
+             *             Returns the computed value (any type).
+             *
+             * @returns CodeToEvaluate object for client-side execution
+             *
+             * @example
+             * // Concatenate first and last name
+             * field('fullName').customClientEvaluation((value, ctx) => {
+             *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+             * })
+             *
+             * @example
+             * // Calculate age from date of birth
+             * field('childAge').customClientEvaluation((value, ctx) => {
+             *   const dob = ctx.$form['child.dob']
+             *   if (!dob) return undefined
+             *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+             *   return age
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend computation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Should return the computed value (any type)
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => any): {
+                $$code: string;
+            };
             getId: () => {
                 fieldId: string;
             };
@@ -494,6 +963,99 @@ export declare function createFieldConditionals(fieldId: string): {
          */
         matches(pattern: string): JSONSchema;
         isBetween(min: number, max: number): JSONSchema;
+        /**
+         * Executes a custom validation function defined by country configuration.
+         *
+         * **Use this as a last resort when predefined toolkit methods are insufficient.**
+         *
+         * The function is serialized via toString() and transmitted as part of the JSON Schema.
+         * It is deserialized just-in-time during validation on the client.
+         *
+         * @param fn - Validation function that receives the field value and form context.
+         *             Must return true if valid, false if invalid.
+         *
+         * @returns JSONSchema conditional for AJV validation
+         *
+         * @example
+         * // Simple age validation
+         * field('age').customClientValidator((value, ctx) => {
+         *   return value >= 18
+         * })
+         *
+         * @example
+         * // Cross-field validation: child DOB must be after mother DOB
+         * field('child.dob').customClientValidator((value, ctx) => {
+         *   const motherDob = ctx.$form['mother.dob']
+         *   if (!motherDob || !value) return false
+         *   return new Date(value) > new Date(motherDob)
+         * })
+         *
+         * @example
+         * // Two number fields validated together
+         * field('fieldA').customClientValidator((value, ctx) => {
+         *   const fieldB = ctx.$form['fieldB']
+         *   if (!fieldB) return false
+         *   return value + fieldB > 100
+         * })
+         *
+         * @remarks
+         * Limitations:
+         * - Client-side only. For backend validation, use country config event triggers.
+         * - Cannot reference external libraries (lodash, etc.)
+         * - Function must be pure — no side effects, no closures over external state
+         * - Function must be serialisable via toString()
+         * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+         * - Must return boolean: true = valid, false = invalid
+         *
+         * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+         */
+        customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+            $form: EventState | Record<string, unknown>;
+        }) => boolean): JSONSchema;
+        /**
+         * Defines a client-side computation function for dynamic field values.
+         *
+         * **Use this as a last resort when predefined toolkit methods are insufficient.**
+         *
+         * The function is serialized via toString() and transmitted to the client,
+         * where it is deserialized and executed to compute field values dynamically.
+         *
+         * @param fn - Computation function that receives the field value and form context.
+         *             Returns the computed value (any type).
+         *
+         * @returns CodeToEvaluate object for client-side execution
+         *
+         * @example
+         * // Concatenate first and last name
+         * field('fullName').customClientEvaluation((value, ctx) => {
+         *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+         * })
+         *
+         * @example
+         * // Calculate age from date of birth
+         * field('childAge').customClientEvaluation((value, ctx) => {
+         *   const dob = ctx.$form['child.dob']
+         *   if (!dob) return undefined
+         *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+         *   return age
+         * })
+         *
+         * @remarks
+         * Limitations:
+         * - Client-side only. For backend computation, use country config event triggers.
+         * - Cannot reference external libraries (lodash, etc.)
+         * - Function must be pure — no side effects, no closures over external state
+         * - Function must be serialisable via toString()
+         * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+         * - Should return the computed value (any type)
+         *
+         * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+         */
+        customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+            $form: EventState | Record<string, unknown>;
+        }) => any): {
+            $$code: string;
+        };
         getId: () => {
             fieldId: string;
         };
@@ -568,6 +1130,99 @@ export declare function createFieldConditionals(fieldId: string): {
              */
             matches(pattern: string): JSONSchema;
             isBetween(min: number, max: number): JSONSchema;
+            /**
+             * Executes a custom validation function defined by country configuration.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted as part of the JSON Schema.
+             * It is deserialized just-in-time during validation on the client.
+             *
+             * @param fn - Validation function that receives the field value and form context.
+             *             Must return true if valid, false if invalid.
+             *
+             * @returns JSONSchema conditional for AJV validation
+             *
+             * @example
+             * // Simple age validation
+             * field('age').customClientValidator((value, ctx) => {
+             *   return value >= 18
+             * })
+             *
+             * @example
+             * // Cross-field validation: child DOB must be after mother DOB
+             * field('child.dob').customClientValidator((value, ctx) => {
+             *   const motherDob = ctx.$form['mother.dob']
+             *   if (!motherDob || !value) return false
+             *   return new Date(value) > new Date(motherDob)
+             * })
+             *
+             * @example
+             * // Two number fields validated together
+             * field('fieldA').customClientValidator((value, ctx) => {
+             *   const fieldB = ctx.$form['fieldB']
+             *   if (!fieldB) return false
+             *   return value + fieldB > 100
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend validation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Must return boolean: true = valid, false = invalid
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => boolean): JSONSchema;
+            /**
+             * Defines a client-side computation function for dynamic field values.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted to the client,
+             * where it is deserialized and executed to compute field values dynamically.
+             *
+             * @param fn - Computation function that receives the field value and form context.
+             *             Returns the computed value (any type).
+             *
+             * @returns CodeToEvaluate object for client-side execution
+             *
+             * @example
+             * // Concatenate first and last name
+             * field('fullName').customClientEvaluation((value, ctx) => {
+             *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+             * })
+             *
+             * @example
+             * // Calculate age from date of birth
+             * field('childAge').customClientEvaluation((value, ctx) => {
+             *   const dob = ctx.$form['child.dob']
+             *   if (!dob) return undefined
+             *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+             *   return age
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend computation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Should return the computed value (any type)
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => any): {
+                $$code: string;
+            };
             getId: () => {
                 fieldId: string;
             };
@@ -627,6 +1282,99 @@ export declare function createFieldConditionals(fieldId: string): {
          */
         matches(pattern: string): JSONSchema;
         isBetween(min: number, max: number): JSONSchema;
+        /**
+         * Executes a custom validation function defined by country configuration.
+         *
+         * **Use this as a last resort when predefined toolkit methods are insufficient.**
+         *
+         * The function is serialized via toString() and transmitted as part of the JSON Schema.
+         * It is deserialized just-in-time during validation on the client.
+         *
+         * @param fn - Validation function that receives the field value and form context.
+         *             Must return true if valid, false if invalid.
+         *
+         * @returns JSONSchema conditional for AJV validation
+         *
+         * @example
+         * // Simple age validation
+         * field('age').customClientValidator((value, ctx) => {
+         *   return value >= 18
+         * })
+         *
+         * @example
+         * // Cross-field validation: child DOB must be after mother DOB
+         * field('child.dob').customClientValidator((value, ctx) => {
+         *   const motherDob = ctx.$form['mother.dob']
+         *   if (!motherDob || !value) return false
+         *   return new Date(value) > new Date(motherDob)
+         * })
+         *
+         * @example
+         * // Two number fields validated together
+         * field('fieldA').customClientValidator((value, ctx) => {
+         *   const fieldB = ctx.$form['fieldB']
+         *   if (!fieldB) return false
+         *   return value + fieldB > 100
+         * })
+         *
+         * @remarks
+         * Limitations:
+         * - Client-side only. For backend validation, use country config event triggers.
+         * - Cannot reference external libraries (lodash, etc.)
+         * - Function must be pure — no side effects, no closures over external state
+         * - Function must be serialisable via toString()
+         * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+         * - Must return boolean: true = valid, false = invalid
+         *
+         * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+         */
+        customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+            $form: EventState | Record<string, unknown>;
+        }) => boolean): JSONSchema;
+        /**
+         * Defines a client-side computation function for dynamic field values.
+         *
+         * **Use this as a last resort when predefined toolkit methods are insufficient.**
+         *
+         * The function is serialized via toString() and transmitted to the client,
+         * where it is deserialized and executed to compute field values dynamically.
+         *
+         * @param fn - Computation function that receives the field value and form context.
+         *             Returns the computed value (any type).
+         *
+         * @returns CodeToEvaluate object for client-side execution
+         *
+         * @example
+         * // Concatenate first and last name
+         * field('fullName').customClientEvaluation((value, ctx) => {
+         *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+         * })
+         *
+         * @example
+         * // Calculate age from date of birth
+         * field('childAge').customClientEvaluation((value, ctx) => {
+         *   const dob = ctx.$form['child.dob']
+         *   if (!dob) return undefined
+         *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+         *   return age
+         * })
+         *
+         * @remarks
+         * Limitations:
+         * - Client-side only. For backend computation, use country config event triggers.
+         * - Cannot reference external libraries (lodash, etc.)
+         * - Function must be pure — no side effects, no closures over external state
+         * - Function must be serialisable via toString()
+         * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+         * - Should return the computed value (any type)
+         *
+         * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+         */
+        customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+            $form: EventState | Record<string, unknown>;
+        }) => any): {
+            $$code: string;
+        };
         getId: () => {
             fieldId: string;
         };
@@ -701,6 +1449,99 @@ export declare function createFieldConditionals(fieldId: string): {
              */
             matches(pattern: string): JSONSchema;
             isBetween(min: number, max: number): JSONSchema;
+            /**
+             * Executes a custom validation function defined by country configuration.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted as part of the JSON Schema.
+             * It is deserialized just-in-time during validation on the client.
+             *
+             * @param fn - Validation function that receives the field value and form context.
+             *             Must return true if valid, false if invalid.
+             *
+             * @returns JSONSchema conditional for AJV validation
+             *
+             * @example
+             * // Simple age validation
+             * field('age').customClientValidator((value, ctx) => {
+             *   return value >= 18
+             * })
+             *
+             * @example
+             * // Cross-field validation: child DOB must be after mother DOB
+             * field('child.dob').customClientValidator((value, ctx) => {
+             *   const motherDob = ctx.$form['mother.dob']
+             *   if (!motherDob || !value) return false
+             *   return new Date(value) > new Date(motherDob)
+             * })
+             *
+             * @example
+             * // Two number fields validated together
+             * field('fieldA').customClientValidator((value, ctx) => {
+             *   const fieldB = ctx.$form['fieldB']
+             *   if (!fieldB) return false
+             *   return value + fieldB > 100
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend validation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Must return boolean: true = valid, false = invalid
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => boolean): JSONSchema;
+            /**
+             * Defines a client-side computation function for dynamic field values.
+             *
+             * **Use this as a last resort when predefined toolkit methods are insufficient.**
+             *
+             * The function is serialized via toString() and transmitted to the client,
+             * where it is deserialized and executed to compute field values dynamically.
+             *
+             * @param fn - Computation function that receives the field value and form context.
+             *             Returns the computed value (any type).
+             *
+             * @returns CodeToEvaluate object for client-side execution
+             *
+             * @example
+             * // Concatenate first and last name
+             * field('fullName').customClientEvaluation((value, ctx) => {
+             *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+             * })
+             *
+             * @example
+             * // Calculate age from date of birth
+             * field('childAge').customClientEvaluation((value, ctx) => {
+             *   const dob = ctx.$form['child.dob']
+             *   if (!dob) return undefined
+             *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+             *   return age
+             * })
+             *
+             * @remarks
+             * Limitations:
+             * - Client-side only. For backend computation, use country config event triggers.
+             * - Cannot reference external libraries (lodash, etc.)
+             * - Function must be pure — no side effects, no closures over external state
+             * - Function must be serialisable via toString()
+             * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+             * - Should return the computed value (any type)
+             *
+             * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+             */
+            customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+                $form: EventState | Record<string, unknown>;
+            }) => any): {
+                $$code: string;
+            };
             getId: () => {
                 fieldId: string;
             };
@@ -760,6 +1601,99 @@ export declare function createFieldConditionals(fieldId: string): {
          */
         matches(pattern: string): JSONSchema;
         isBetween(min: number, max: number): JSONSchema;
+        /**
+         * Executes a custom validation function defined by country configuration.
+         *
+         * **Use this as a last resort when predefined toolkit methods are insufficient.**
+         *
+         * The function is serialized via toString() and transmitted as part of the JSON Schema.
+         * It is deserialized just-in-time during validation on the client.
+         *
+         * @param fn - Validation function that receives the field value and form context.
+         *             Must return true if valid, false if invalid.
+         *
+         * @returns JSONSchema conditional for AJV validation
+         *
+         * @example
+         * // Simple age validation
+         * field('age').customClientValidator((value, ctx) => {
+         *   return value >= 18
+         * })
+         *
+         * @example
+         * // Cross-field validation: child DOB must be after mother DOB
+         * field('child.dob').customClientValidator((value, ctx) => {
+         *   const motherDob = ctx.$form['mother.dob']
+         *   if (!motherDob || !value) return false
+         *   return new Date(value) > new Date(motherDob)
+         * })
+         *
+         * @example
+         * // Two number fields validated together
+         * field('fieldA').customClientValidator((value, ctx) => {
+         *   const fieldB = ctx.$form['fieldB']
+         *   if (!fieldB) return false
+         *   return value + fieldB > 100
+         * })
+         *
+         * @remarks
+         * Limitations:
+         * - Client-side only. For backend validation, use country config event triggers.
+         * - Cannot reference external libraries (lodash, etc.)
+         * - Function must be pure — no side effects, no closures over external state
+         * - Function must be serialisable via toString()
+         * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+         * - Must return boolean: true = valid, false = invalid
+         *
+         * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+         */
+        customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+            $form: EventState | Record<string, unknown>;
+        }) => boolean): JSONSchema;
+        /**
+         * Defines a client-side computation function for dynamic field values.
+         *
+         * **Use this as a last resort when predefined toolkit methods are insufficient.**
+         *
+         * The function is serialized via toString() and transmitted to the client,
+         * where it is deserialized and executed to compute field values dynamically.
+         *
+         * @param fn - Computation function that receives the field value and form context.
+         *             Returns the computed value (any type).
+         *
+         * @returns CodeToEvaluate object for client-side execution
+         *
+         * @example
+         * // Concatenate first and last name
+         * field('fullName').customClientEvaluation((value, ctx) => {
+         *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+         * })
+         *
+         * @example
+         * // Calculate age from date of birth
+         * field('childAge').customClientEvaluation((value, ctx) => {
+         *   const dob = ctx.$form['child.dob']
+         *   if (!dob) return undefined
+         *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+         *   return age
+         * })
+         *
+         * @remarks
+         * Limitations:
+         * - Client-side only. For backend computation, use country config event triggers.
+         * - Cannot reference external libraries (lodash, etc.)
+         * - Function must be pure — no side effects, no closures over external state
+         * - Function must be serialisable via toString()
+         * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+         * - Should return the computed value (any type)
+         *
+         * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+         */
+        customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+            $form: EventState | Record<string, unknown>;
+        }) => any): {
+            $$code: string;
+        };
         getId: () => {
             fieldId: string;
         };
@@ -817,6 +1751,99 @@ export declare function createFieldConditionals(fieldId: string): {
      */
     matches(pattern: string): JSONSchema;
     isBetween(min: number, max: number): JSONSchema;
+    /**
+     * Executes a custom validation function defined by country configuration.
+     *
+     * **Use this as a last resort when predefined toolkit methods are insufficient.**
+     *
+     * The function is serialized via toString() and transmitted as part of the JSON Schema.
+     * It is deserialized just-in-time during validation on the client.
+     *
+     * @param fn - Validation function that receives the field value and form context.
+     *             Must return true if valid, false if invalid.
+     *
+     * @returns JSONSchema conditional for AJV validation
+     *
+     * @example
+     * // Simple age validation
+     * field('age').customClientValidator((value, ctx) => {
+     *   return value >= 18
+     * })
+     *
+     * @example
+     * // Cross-field validation: child DOB must be after mother DOB
+     * field('child.dob').customClientValidator((value, ctx) => {
+     *   const motherDob = ctx.$form['mother.dob']
+     *   if (!motherDob || !value) return false
+     *   return new Date(value) > new Date(motherDob)
+     * })
+     *
+     * @example
+     * // Two number fields validated together
+     * field('fieldA').customClientValidator((value, ctx) => {
+     *   const fieldB = ctx.$form['fieldB']
+     *   if (!fieldB) return false
+     *   return value + fieldB > 100
+     * })
+     *
+     * @remarks
+     * Limitations:
+     * - Client-side only. For backend validation, use country config event triggers.
+     * - Cannot reference external libraries (lodash, etc.)
+     * - Function must be pure — no side effects, no closures over external state
+     * - Function must be serialisable via toString()
+     * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+     * - Must return boolean: true = valid, false = invalid
+     *
+     * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+     */
+    customClientValidator(fn: (value: unknown, context: CommonConditionalParameters & {
+        $form: EventState | Record<string, unknown>;
+    }) => boolean): JSONSchema;
+    /**
+     * Defines a client-side computation function for dynamic field values.
+     *
+     * **Use this as a last resort when predefined toolkit methods are insufficient.**
+     *
+     * The function is serialized via toString() and transmitted to the client,
+     * where it is deserialized and executed to compute field values dynamically.
+     *
+     * @param fn - Computation function that receives the field value and form context.
+     *             Returns the computed value (any type).
+     *
+     * @returns CodeToEvaluate object for client-side execution
+     *
+     * @example
+     * // Concatenate first and last name
+     * field('fullName').customClientEvaluation((value, ctx) => {
+     *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+     * })
+     *
+     * @example
+     * // Calculate age from date of birth
+     * field('childAge').customClientEvaluation((value, ctx) => {
+     *   const dob = ctx.$form['child.dob']
+     *   if (!dob) return undefined
+     *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+     *   return age
+     * })
+     *
+     * @remarks
+     * Limitations:
+     * - Client-side only. For backend computation, use country config event triggers.
+     * - Cannot reference external libraries (lodash, etc.)
+     * - Function must be pure — no side effects, no closures over external state
+     * - Function must be serialisable via toString()
+     * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+     * - Should return the computed value (any type)
+     *
+     * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+     */
+    customClientEvaluation(fn: (value: unknown, context: CommonConditionalParameters & {
+        $form: EventState | Record<string, unknown>;
+    }) => any): {
+        $$code: string;
+    };
     getId: () => {
         fieldId: string;
     };