@opencrvs/toolkit 1.9.8-rc.0cafd28 → 1.9.8-rc.0cf339f

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

@@ -5,6 +5,7 @@ import { PartialSchema as AjvJSONSchemaType } from 'ajv/dist/types/json-schema';
 import { userSerializer } from '../events/serializers/user/serializer';
 import { UUID } from '../uuid';
 import { todayDateTimeValueSerializer } from '../events/serializers/date/serializer';
+import { EventStatus } from '../events/EventMetadata';
 /** @knipignore */
 export type JSONSchema = {
     $id: string;
@@ -28,7 +29,11 @@ export type FormConditionalParameters = CommonConditionalParameters & {
         id: UUID;
     }>;
 };
-export type ConditionalParameters = UserConditionalParameters | EventConditionalParameters | FormConditionalParameters;
+export type EventStateConditionalParameters = CommonConditionalParameters & {
+    $flags: string[];
+    $status: EventStatus;
+};
+export type ConditionalParameters = UserConditionalParameters | EventConditionalParameters | FormConditionalParameters | EventStateConditionalParameters;
 type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 type AjvJSONSchema = AjvJSONSchemaType<UnionToIntersection<ConditionalParameters>>;
 /**
@@ -65,6 +70,9 @@ type FieldReference = {
     $$field: string;
     $$subfield: string[];
 };
+type CodeToEvaluate = {
+    $$code: string;
+};
 /**
  * Generate conditional rules for current date
  */
@@ -84,6 +92,11 @@ 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 */
+export declare function status(statusValue: EventStatus): JSONSchema;
 /**
  * Generate conditional rules for a form field.
  *
@@ -161,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;
             };
@@ -220,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;
         };
@@ -293,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;
             };
@@ -361,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;
             };
@@ -428,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;
             };
@@ -485,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;
         };
@@ -559,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;
             };
@@ -618,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;
         };
@@ -692,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;
             };
@@ -751,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;
         };
@@ -808,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;
     };