@ram_28/kf-ai-sdk 1.0.19 → 1.0.21

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

@@ -5,6 +5,7 @@
 
 import { api, getBdoSchema } from "../../../api";
 import type { BDOSchemaType, FormOperationType, SubmissionResultType } from "./types";
+import { toError } from "../../../utils/error-handling";
 
 // ============================================================
 // SCHEMA FETCHING
@@ -47,7 +48,7 @@ export async function fetchFormSchemaWithRetry(
     try {
       return await fetchFormSchema(source);
     } catch (error) {
-      lastError = error as Error;
+      lastError = toError(error);
 
       if (attempt < maxRetries) {
         // Wait before retrying (exponential backoff)
@@ -134,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,
@@ -170,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>
@@ -238,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)) {
@@ -261,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;
@@ -288,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/useForm.ts

@@ -16,19 +16,20 @@ 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";
 
 import { validateCrossField } from "./expressionValidator.utils";
+import { toError } from "../../../utils/error-handling";
 import {
   validateFieldOptimized,
   getFieldDependencies,
@@ -39,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,
@@ -62,9 +63,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>>({});
 
@@ -175,20 +180,14 @@ 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(console.warn);
-        }
+        // 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?.(error as Error);
+        onSchemaErrorRef.current?.(toError(error));
       }
     }
   }, [schema, userRole]); // Removed onSchemaError - using ref instead
@@ -213,7 +212,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;
     }
@@ -221,6 +220,9 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     // Mark as started immediately to prevent duplicate calls
     draftCreationStartedRef.current = true;
 
+    // Track if effect is still active (for cleanup/race condition handling)
+    let isActive = true;
+
     const createInitialDraft = async () => {
       setIsCreatingDraft(true);
       setDraftError(null);
@@ -230,6 +232,9 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         // Call PATCH /{bdo_id}/draft with empty payload to get draft ID
         const response = await client.draftInteraction({});
 
+        // Check if effect is still active before setting state
+        if (!isActive) return;
+
         // Store the draft ID
         setDraftId(response._id);
 
@@ -249,16 +254,27 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
           });
         }
       } catch (error) {
+        // Check if effect is still active before setting state
+        if (!isActive) return;
+
         console.error("Failed to create initial draft:", error);
-        setDraftError(error as Error);
+        setDraftError(toError(error));
         // Reset the ref on error so it can be retried
         draftCreationStartedRef.current = false;
       } finally {
-        setIsCreatingDraft(false);
+        // Check if effect is still active before setting state
+        if (isActive) {
+          setIsCreatingDraft(false);
+        }
       }
     };
 
     createInitialDraft();
+
+    // Cleanup function to handle unmount during async operation
+    return () => {
+      isActive = false;
+    };
   }, [isInteractiveMode, operation, schemaConfig, enabled, draftId, source]);
   // Note: rhfForm removed from deps - we use ref pattern to avoid dependency loops
 
@@ -298,7 +314,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
@@ -331,12 +347,14 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       }
 
       // Determine if draft should be triggered based on interaction mode
-      // Interactive mode: Always trigger draft API on blur
+      // For update mode, always behave as non-interactive (only trigger for computed deps)
+      // Interactive mode (create only): Always trigger draft API on blur
       // Non-interactive mode: Only trigger for computed field dependencies
-      const shouldTrigger = isInteractiveMode
-        ? true // Interactive mode: always trigger
-        : (computedFieldDependencies.length > 0 &&
-              computedFieldDependencies.includes(fieldName as Path<T>));
+      const shouldTrigger =
+        isInteractiveMode && operation !== "update"
+          ? true // Interactive mode (create only): always trigger
+          : computedFieldDependencies.length > 0 &&
+            computedFieldDependencies.includes(fieldName as Path<T>);
 
       if (!shouldTrigger) {
         return;
@@ -398,7 +416,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)
@@ -406,7 +424,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)
@@ -419,6 +437,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;
               }
             });
@@ -446,7 +469,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);
@@ -469,7 +495,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                       shouldValidate: false,
                     });
                   }
-                }
+                },
               );
 
               // Update baseline with computed fields from successful API response
@@ -478,7 +504,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                   if (computedFieldNames.has(fieldName)) {
                     (lastSyncedValuesRef.current as any)[fieldName] = value;
                   }
-                }
+                },
               );
             }
           } catch (error) {
@@ -507,7 +533,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       computedFieldDependencies,
       isInteractiveMode,
       draftId,
-    ]
+    ],
   );
 
   // ============================================================
@@ -529,18 +555,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) {
@@ -579,11 +603,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
@@ -603,13 +630,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) {
@@ -625,12 +652,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;
@@ -643,7 +679,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
@@ -653,8 +689,8 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 } as any);
                 result = { success: true, data: response };
               } else {
-                // Interactive update: POST /{bdo_id}/{id}/draft
-                const response = await client.draftUpdate(recordId!, cleanedData);
+                // Update operation - always use direct update API (non-interactive)
+                const response = await client.update(recordId!, cleanedData);
                 result = { success: true, data: response };
               }
             } else {
@@ -663,7 +699,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
                 source,
                 operation,
                 cleanedData,
-                recordId
+                recordId,
               );
 
               if (!result.success) {
@@ -684,7 +720,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
             await onSuccess?.(result.data || data, event);
           } catch (error) {
             // API error - call onError with Error object
-            onError?.(error as Error, event);
+            onError?.(toError(error), event);
           } finally {
             setIsSubmitting(false);
           }
@@ -692,7 +728,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         // RHF onInvalid handler - validation failed
         (errors, event) => {
           onError?.(errors, event);
-        }
+        },
       );
     },
     [
@@ -705,7 +741,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       recordData,
       isInteractiveMode,
       draftId,
-    ]
+    ],
   );
 
   // ============================================================
@@ -716,7 +752,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> => {
@@ -734,7 +770,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(
@@ -743,7 +779,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         schemaConfig?.requiredFields.includes(fieldName as string) || false
       );
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   const isFieldComputed = useCallback(
@@ -752,7 +788,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         schemaConfig?.computedFields.includes(fieldName as string) || false
       );
     },
-    [schemaConfig]
+    [schemaConfig],
   );
 
   // ============================================================
@@ -782,12 +818,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],
   );
 
   // ============================================================
@@ -840,7 +876,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";
@@ -912,7 +948,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
         onBlur: enhancedOnBlur,
       });
     },
-    [rhfForm, validationRules, triggerComputationAfterValidation, mode]
+    [rhfForm, validationRules, triggerComputationAfterValidation, mode],
   );
 
   return {
@@ -940,7 +976,7 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     isCreatingDraft,
 
     // Error handling
-    loadError: loadError as Error | null,
+    loadError: loadError ? toError(loadError) : null,
     hasError,
 
     // Schema information

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

@@ -4,8 +4,11 @@
 // Core TypeScript interfaces for the kanban board functionality
 // Following patterns from useTable and useForm
 
-import type { ConditionType, ConditionGroupType, UseFilterReturnType } from "../useFilter";
-import type { ConditionGroupOperatorType } from "../../../types/common";
+import type { UseFilterReturnType, UseFilterOptionsType } from "../useFilter";
+import type { ColumnDefinitionType } from "../../../types/common";
+
+// Re-export ColumnDefinitionType for backwards compatibility
+export type { ColumnDefinitionType };
 
 // ============================================================
 // CORE DATA STRUCTURES
@@ -95,23 +98,6 @@ export interface KanbanColumnType<T = Record<string, any>> {
   _modified_at?: Date;
 }
 
-/**
- * Column definition for display and behavior
- * Similar to ColumnDefinition in useTable
- */
-export interface ColumnDefinitionType<T> {
-  /** Field name from the card type */
-  fieldId: keyof T;
-  /** Display label (optional, defaults to fieldId) */
-  label?: string;
-  /** Enable sorting for this field */
-  enableSorting?: boolean;
-  /** Enable filtering for this field */
-  enableFiltering?: boolean;
-  /** Custom transform function (overrides auto-formatting) */
-  transform?: (value: any, card: T) => React.ReactNode;
-}
-
 // ============================================================
 // DRAG & DROP TYPES
 // ============================================================
@@ -195,10 +181,8 @@ export interface UseKanbanOptionsType<T> {
 
   /** Initial state */
   initialState?: {
-    /** Initial filter conditions */
-    filters?: Array<ConditionType | ConditionGroupType>;
-    /** Initial filter operator for combining filter conditions */
-    filterOperator?: ConditionGroupOperatorType;
+    /** Initial filter configuration: { conditions, operator } */
+    filter?: UseFilterOptionsType;
     /** Initial search query */
     search?: string;
     /** Initial column order */