@ram_28/kf-ai-sdk 1.0.20 → 1.0.22

package/sdk/base-types.ts

@@ -25,6 +25,8 @@ export type {
   CurrencyValueType,
   JSONFieldType,
   ReferenceFieldType,
+  ExtractReferenceType,
+  ExtractFetchFieldType,
 
   // JSON types
   JSONValueType,

package/sdk/components/hooks/useForm/apiClient.ts

@@ -135,7 +135,62 @@ export async function submitFormData<T = any>(
 // ============================================================
 
 /**
- * Fetch reference field data
+ * Fetch reference field data using the fetchField API
+ * This correctly uses instance context for filter evaluation
+ */
+export async function fetchReferenceFieldData(
+  boId: string,
+  instanceId: string,
+  fieldId: string
+): Promise<Array<{ Value: string; Label: string }>> {
+  try {
+    // Calls GET /{boId}/{instanceId}/field/{fieldId}/fetch
+    return await api(boId).fetchField(instanceId, fieldId);
+  } catch (error) {
+    console.error(`Reference data fetch error for ${fieldId}:`, error);
+    return [];
+  }
+}
+
+/**
+ * Fetch all reference data for a form
+ * @param boId - The Business Object ID
+ * @param instanceId - The instance ID (draftId for create, recordId for update)
+ * @param referenceFieldIds - Array of reference field IDs to fetch
+ */
+export async function fetchAllReferenceFieldData(
+  boId: string,
+  instanceId: string,
+  referenceFieldIds: string[]
+): Promise<Record<string, Array<{ Value: string; Label: string }>>> {
+  const referenceData: Record<string, Array<{ Value: string; Label: string }>> = {};
+
+  // Fetch all reference data in parallel
+  const fetchPromises = referenceFieldIds.map(async (fieldId) => {
+    try {
+      const data = await fetchReferenceFieldData(boId, instanceId, fieldId);
+      return [fieldId, data] as const;
+    } catch (error) {
+      console.warn(`Failed to fetch reference data for ${fieldId}:`, error);
+      return [fieldId, []] as const;
+    }
+  });
+
+  const results = await Promise.allSettled(fetchPromises);
+
+  results.forEach((result) => {
+    if (result.status === "fulfilled") {
+      const [fieldId, data] = result.value;
+      referenceData[fieldId] = [...data];
+    }
+  });
+
+  return referenceData;
+}
+
+/**
+ * @deprecated Use fetchReferenceFieldData instead
+ * Legacy function that fetches reference data using list() API
  */
 export async function fetchReferenceData(
   businessObject: string,
@@ -171,7 +226,8 @@ export async function fetchReferenceData(
 }
 
 /**
- * Fetch all reference data for a schema
+ * @deprecated Use fetchAllReferenceFieldData instead
+ * Legacy function that fetches all reference data using list() API
  */
 export async function fetchAllReferenceData(
   referenceFields: Record<string, any>
@@ -239,18 +295,26 @@ export function validateFormData<T>(
  * Clean form data before submission
  * - For create: returns all non-computed, non-undefined fields
  * - For update: returns only fields that changed from originalData
+ * - Transforms Reference fields to JSON format expected by backend
+ *
+ * @param data - Form data to clean
+ * @param computedFields - Array of computed field names to exclude
+ * @param operation - "create" or "update"
+ * @param originalData - Original data for comparison (update only)
+ * @param fieldTypes - Map of field names to their BDO types (e.g., { "SupplierInfo": "Reference" })
  */
 export function cleanFormData<T>(
   data: Partial<T>,
   computedFields: string[],
   operation: FormOperationType = "create",
-  originalData?: Partial<T>
+  originalData?: Partial<T>,
+  fieldTypes?: Record<string, string>
 ): Partial<T> {
   const cleanedData: Partial<T> = {};
 
   Object.keys(data).forEach((key) => {
     const fieldKey = key as keyof T;
-    const value = data[fieldKey];
+    let value = data[fieldKey];
 
     // Skip computed fields
     if (computedFields.includes(key)) {
@@ -262,6 +326,12 @@ export function cleanFormData<T>(
       return;
     }
 
+    // Transform Reference fields to JSON format expected by backend
+    // Backend expects: {"_id": "...", "_name": "..."} or a JSON string that parses to this
+    if (fieldTypes?.[key] === "Reference" && value !== null) {
+      value = transformReferenceValue(value) as any;
+    }
+
     // For create: include all non-computed, non-undefined fields
     if (operation === "create") {
       cleanedData[fieldKey] = value;
@@ -289,6 +359,50 @@ export function cleanFormData<T>(
   return cleanedData;
 }
 
+/**
+ * Transform a Reference/Lookup field value to the format expected by backend
+ *
+ * Backend expects Reference fields as either:
+ * - A dict with at minimum {"_id": "..."}
+ * - For Lookup fields, the full referenced record can be passed
+ * - A JSON string that parses to this format
+ *
+ * This function handles various input formats:
+ * - Plain string ID: "SUPP-001" → {"_id": "SUPP-001"}
+ * - Object with _id: preserves ALL properties (for lookup fields with full data)
+ * - JSON string: '{"_id": "..."}' → parsed and validated
+ */
+export function transformReferenceValue(value: any): Record<string, any> | null {
+  if (value === null || value === undefined || value === "") {
+    return null;
+  }
+
+  // Already an object with _id - preserve ALL properties (for lookup fields with full data)
+  if (typeof value === "object" && value._id) {
+    return { ...value };
+  }
+
+  // String value - could be plain ID or JSON string
+  if (typeof value === "string") {
+    // Try to parse as JSON first
+    try {
+      const parsed = JSON.parse(value);
+      if (typeof parsed === "object" && parsed._id) {
+        return { ...parsed };
+      }
+      // Parsed but not a valid reference object - treat original as ID
+    } catch {
+      // Not valid JSON - treat as plain ID string
+    }
+
+    // Plain string ID
+    return { _id: value };
+  }
+
+  // Unknown format - return as-is (let backend handle/reject it)
+  return value;
+}
+
 // ============================================================
 // ERROR HANDLING
 // ============================================================

package/sdk/components/hooks/useForm/types.ts

@@ -304,6 +304,15 @@ export interface UseFormOptionsType<
    * @default "interactive"
    */
   interactionMode?: InteractionModeType;
+
+  /**
+   * Enable draft API calls in update mode
+   * When false (default), no draft API calls (e.g., /instance_id/draft) are made during
+   * field blur in update mode. The update API is only called on form submission.
+   * When true, draft API calls are made on blur for computed field dependencies.
+   * @default false
+   */
+  enableDraftInUpdateMode?: boolean;
 }
 
 // ============================================================

package/sdk/components/hooks/useForm/useForm.ts

@@ -16,14 +16,14 @@ import type {
   FormFieldConfigType,
 } from "./types";
 
-import { processSchema, extractReferenceFields } from "./schemaParser.utils";
+import { processSchema } from "./schemaParser.utils";
 
 import {
   fetchFormSchemaWithCache,
   fetchRecord,
   submitFormData,
-  fetchAllReferenceData,
   cleanFormData,
+  transformReferenceValue,
 } from "./apiClient";
 
 import { api } from "../../../api";
@@ -40,7 +40,7 @@ import {
 // ============================================================
 
 export function useForm<T extends Record<string, any> = Record<string, any>>(
-  options: UseFormOptionsType<T>
+  options: UseFormOptionsType<T>,
 ): UseFormReturnType<T> {
   const {
     source,
@@ -54,6 +54,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     skipSchemaFetch = false,
     schema: manualSchema,
     interactionMode = "interactive",
+    enableDraftInUpdateMode = false,
   } = options;
 
   // Derived interaction mode flags
@@ -63,9 +64,13 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
   // STATE MANAGEMENT
   // ============================================================
 
-  const [schemaConfig, setSchemaConfig] =
-    useState<FormSchemaConfigType | null>(null);
-  const [referenceData, setReferenceData] = useState<Record<string, any[]>>({});
+  const [schemaConfig, setSchemaConfig] = useState<FormSchemaConfigType | null>(
+    null,
+  );
+  // Reference data for cross-field validation - populated lazily by UI components if needed
+  const [referenceData, _setReferenceData] = useState<Record<string, any[]>>(
+    {},
+  );
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [lastFormValues] = useState<Partial<T>>({});
 
@@ -176,22 +181,11 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         const processed = processSchema(
           schema as any,
           {}, // Pass empty object - validation functions get live values from react-hook-form
-          userRole
+          userRole,
         );
         setSchemaConfig(processed);
-
-        // Fetch reference data for reference fields
-        const refFields = extractReferenceFields(processed);
-        if (Object.keys(refFields).length > 0) {
-          fetchAllReferenceData(refFields)
-            .then(setReferenceData)
-            .catch((err) => {
-              const error = toError(err);
-              console.warn("Failed to fetch reference data:", error);
-              // Notify via callback but don't block form - reference data is non-critical
-              onSchemaErrorRef.current?.(error);
-            });
-        }
+        // Reference data is fetched lazily by UI components when dropdowns are opened
+        // using the fetchField API with proper instance context (draftId/recordId)
       } catch (error) {
         console.error("Schema processing failed:", error);
         onSchemaErrorRef.current?.(toError(error));
@@ -219,7 +213,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       !schemaConfig ||
       !enabled ||
       draftId ||
-      draftCreationStartedRef.current  // Prevent duplicate calls in React strict mode
+      draftCreationStartedRef.current // Prevent duplicate calls in React strict mode
     ) {
       return;
     }
@@ -321,7 +315,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       const field = schemaConfig.fields[fieldName];
       if (field._bdoField.Formula) {
         const fieldDeps = getFieldDependencies(
-          field._bdoField.Formula.ExpressionTree
+          field._bdoField.Formula.ExpressionTree,
         );
         fieldDeps.forEach((dep) => {
           // Only add non-computed fields as dependencies
@@ -353,14 +347,20 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         return;
       }
 
-      // Determine if draft should be triggered based on interaction mode
-      // For update mode, always behave as non-interactive (only trigger for computed deps)
+      // Determine if draft should be triggered based on interaction mode and configuration
+      // For update mode: skip draft API calls unless explicitly enabled via enableDraftInUpdateMode
       // Interactive mode (create only): Always trigger draft API on blur
       // Non-interactive mode: Only trigger for computed field dependencies
-      const shouldTrigger = (isInteractiveMode && operation !== "update")
-        ? true // Interactive mode (create only): always trigger
-        : (computedFieldDependencies.length > 0 &&
-              computedFieldDependencies.includes(fieldName as Path<T>));
+      if (operation === "update" && !enableDraftInUpdateMode) {
+        // Skip draft API calls in update mode when enableDraftInUpdateMode is false (default)
+        return;
+      }
+
+      const shouldTrigger =
+        isInteractiveMode && operation !== "update"
+          ? true // Interactive mode (create only): always trigger
+          : computedFieldDependencies.length > 0 &&
+            computedFieldDependencies.includes(fieldName as Path<T>);
 
       if (!shouldTrigger) {
         return;
@@ -422,7 +422,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
 
             // Get computed field names to exclude from payload
             const computedFieldNames = new Set(
-              schemaConfig.computedFields || []
+              schemaConfig.computedFields || [],
             );
 
             // Find fields that changed from baseline (excluding computed fields)
@@ -430,7 +430,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
               // Skip _id and computed fields
               if (key === "_id" || computedFieldNames.has(key)) return;
 
-              const currentValue = (currentValues as any)[key];
+              let currentValue = (currentValues as any)[key];
               const baselineValue = (baseline as any)[key];
 
               // Include if value has changed (using JSON.stringify for deep comparison)
@@ -443,6 +443,11 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 currentValue !== undefined;
 
               if (hasChanged && isNonEmpty) {
+                // Transform Reference fields to format expected by backend
+                const fieldConfig = schemaConfig.fields[key];
+                if (fieldConfig?._bdoField?.Type === "Reference") {
+                  currentValue = transformReferenceValue(currentValue);
+                }
                 (changedFields as any)[key] = currentValue;
               }
             });
@@ -470,7 +475,10 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
             let computedFieldsResponse;
             if (operation === "update" && recordId) {
               // Update mode: use draftPatch (both interactive and non-interactive)
-              computedFieldsResponse = await client.draftPatch(recordId, payload);
+              computedFieldsResponse = await client.draftPatch(
+                recordId,
+                payload,
+              );
             } else if (isInteractiveMode && draftId) {
               // Interactive create: use draftInteraction with _id
               computedFieldsResponse = await client.draftInteraction(payload);
@@ -493,7 +501,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                       shouldValidate: false,
                     });
                   }
-                }
+                },
               );
 
               // Update baseline with computed fields from successful API response
@@ -502,7 +510,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                   if (computedFieldNames.has(fieldName)) {
                     (lastSyncedValuesRef.current as any)[fieldName] = value;
                   }
-                }
+                },
               );
             }
           } catch (error) {
@@ -531,7 +539,8 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       computedFieldDependencies,
       isInteractiveMode,
       draftId,
-    ]
+      enableDraftInUpdateMode,
+    ],
   );
 
   // ============================================================
@@ -553,18 +562,16 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
 
     // Cross-field validation
     // Transform ValidationRule[] to the format expected by validateCrossField
-    const transformedRules = schemaConfig.crossFieldValidation.map(
-      (rule) => ({
-        Id: rule.Id,
-        Condition: { ExpressionTree: rule.ExpressionTree },
-        Message: rule.Message || `Validation failed for ${rule.Name}`,
-      })
-    );
+    const transformedRules = schemaConfig.crossFieldValidation.map((rule) => ({
+      Id: rule.Id,
+      Condition: { ExpressionTree: rule.ExpressionTree },
+      Message: rule.Message || `Validation failed for ${rule.Name}`,
+    }));
 
     const crossFieldErrors = validateCrossField(
       transformedRules,
       values as any,
-      referenceData
+      referenceData,
     );
 
     if (crossFieldErrors.length > 0) {
@@ -603,11 +610,14 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
    */
   const handleSubmit = useCallback(
     (
-      onSuccess?: (data: T, e?: React.BaseSyntheticEvent) => void | Promise<void>,
+      onSuccess?: (
+        data: T,
+        e?: React.BaseSyntheticEvent,
+      ) => void | Promise<void>,
       onError?: (
         error: import("react-hook-form").FieldErrors<T> | Error,
-        e?: React.BaseSyntheticEvent
-      ) => void | Promise<void>
+        e?: React.BaseSyntheticEvent,
+      ) => void | Promise<void>,
     ) => {
       return rhfForm.handleSubmit(
         // RHF onValid handler - validation passed, now do cross-field + API
@@ -627,13 +637,13 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 Id: rule.Id,
                 Condition: { ExpressionTree: rule.ExpressionTree },
                 Message: rule.Message || `Validation failed for ${rule.Name}`,
-              })
+              }),
             );
 
             const crossFieldErrors = validateCrossField(
               transformedRules,
               data as any,
-              referenceData
+              referenceData,
             );
 
             if (crossFieldErrors.length > 0) {
@@ -649,12 +659,21 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
               return;
             }
 
+            // Extract field types from schema for Reference field transformation
+            const fieldTypes: Record<string, string> = {};
+            Object.entries(schemaConfig.fields).forEach(
+              ([fieldName, field]) => {
+                fieldTypes[fieldName] = field._bdoField.Type;
+              },
+            );
+
             // Clean data for submission
             const cleanedData = cleanFormData(
               data as any,
               schemaConfig.computedFields,
               operation,
-              recordData as Partial<T> | undefined
+              recordData as Partial<T> | undefined,
+              fieldTypes,
             );
 
             let result;
@@ -667,7 +686,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 // Interactive create: must have draftId
                 if (!draftId) {
                   throw new Error(
-                    "Interactive create mode requires a draft ID. Draft creation may have failed."
+                    "Interactive create mode requires a draft ID. Draft creation may have failed.",
                   );
                 }
                 // POST /{bdo_id}/draft with _id in payload
@@ -687,7 +706,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 source,
                 operation,
                 cleanedData,
-                recordId
+                recordId,
               );
 
               if (!result.success) {
@@ -716,7 +735,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         // RHF onInvalid handler - validation failed
         (errors, event) => {
           onError?.(errors, event);
-        }
+        },
       );
     },
     [
@@ -729,7 +748,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       recordData,
       isInteractiveMode,
       draftId,
-    ]
+    ],
   );
 
   // ============================================================
@@ -740,7 +759,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     <K extends keyof T>(fieldName: K): FormFieldConfigType | null => {
       return schemaConfig?.fields[fieldName as string] || null;
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   const getFields = useCallback((): Record<keyof T, FormFieldConfigType> => {
@@ -758,7 +777,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     <K extends keyof T>(fieldName: K): boolean => {
       return !!schemaConfig?.fields[fieldName as string];
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   const isFieldRequired = useCallback(
@@ -767,7 +786,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         schemaConfig?.requiredFields.includes(fieldName as string) || false
       );
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   const isFieldComputed = useCallback(
@@ -776,7 +795,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         schemaConfig?.computedFields.includes(fieldName as string) || false
       );
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   // ============================================================
@@ -806,12 +825,12 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
 
   const computedFields = useMemo<Array<keyof T>>(
     () => (schemaConfig?.computedFields as Array<keyof T>) || [],
-    [schemaConfig]
+    [schemaConfig],
   );
 
   const requiredFields = useMemo<Array<keyof T>>(
     () => (schemaConfig?.requiredFields as Array<keyof T>) || [],
-    [schemaConfig]
+    [schemaConfig],
   );
 
   // ============================================================
@@ -864,7 +883,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                   value,
                   [rule],
                   currentValues,
-                  lastFormValues as T | undefined
+                  lastFormValues as T | undefined,
                 );
                 if (!result.isValid) {
                   return result.message || rule.Message || "Invalid value";
@@ -936,7 +955,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         onBlur: enhancedOnBlur,
       });
     },
-    [rhfForm, validationRules, triggerComputationAfterValidation, mode]
+    [rhfForm, validationRules, triggerComputationAfterValidation, mode],
   );
 
   return {

package/sdk/index.ts

@@ -92,6 +92,9 @@ export type {
   LookupFieldType,
   ArrayFieldType,
   JSONFieldType,
+  ReferenceFieldType,
+  ExtractReferenceType,
+  ExtractFetchFieldType,
 } from './types/base-fields';
 
 // ============================================================