@ram_28/kf-ai-sdk 1.0.10 → 1.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",

package/sdk/api/client.ts

@@ -69,6 +69,15 @@ export interface ResourceClient<T = any> {
    */
   draftPatch(id: string, data: Partial<T>): Promise<DraftResponse>;
 
+  /**
+   * Interactive draft - create/update draft without instance ID
+   * PATCH /{bo_id}/draft
+   * Used in interactive mode for create operations
+   */
+  draftInteraction(
+    data: Partial<T> & { _id?: string }
+  ): Promise<DraftResponse & { _id: string }>;
+
   // ============================================================
   // QUERY OPERATIONS
   // ============================================================
@@ -355,6 +364,24 @@ export function api<T = any>(bo_id: string): ResourceClient<T> {
       return response.json();
     },
 
+    async draftInteraction(
+      data: Partial<T> & { _id?: string }
+    ): Promise<DraftResponse & { _id: string }> {
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/draft`, {
+        method: "PATCH",
+        headers: defaultHeaders,
+        body: JSON.stringify(data),
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to create interactive draft for ${bo_id}: ${response.statusText}`
+        );
+      }
+
+      return response.json();
+    },
+
     // ============================================================
     // QUERY OPERATIONS
     // ============================================================

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

@@ -229,6 +229,13 @@ export interface BDOSchema {
  */
 export type FormOperation = "create" | "update";
 
+/**
+ * Form interaction mode
+ * - "interactive" (default): Real-time server-side validation and computation on every field blur
+ * - "non-interactive": Draft only for computed field dependencies (legacy behavior)
+ */
+export type InteractionMode = "interactive" | "non-interactive";
+
 /**
  * Form validation mode (from react-hook-form)
  */
@@ -295,8 +302,17 @@ export interface UseFormOptions<
    * Trigger draft API call on every field change (after validation passes)
    * If true: draft API is called for any field change
    * If false (default): draft API is called only when computed field dependencies change
+   * @deprecated Use interactionMode: "interactive" instead
    */
   draftOnEveryChange?: boolean;
+
+  /**
+   * Form interaction mode
+   * - "interactive" (default): Real-time server-side validation and computation on every field blur
+   * - "non-interactive": Draft only for computed field dependencies (legacy behavior)
+   * @default "interactive"
+   */
+  interactionMode?: InteractionMode;
 }
 
 // ============================================================
@@ -536,6 +552,16 @@ export interface UseFormReturn<
   /** Any loading state active */
   isLoading: boolean;
 
+  // ============================================================
+  // INTERACTIVE MODE STATE
+  // ============================================================
+
+  /** Draft ID for interactive create mode */
+  draftId: string | null;
+
+  /** Whether draft is being created (interactive create only) */
+  isCreatingDraft: boolean;
+
   // ============================================================
   // ERROR HANDLING
   // ============================================================

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

@@ -53,8 +53,12 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     skipSchemaFetch = false,
     schema: manualSchema,
     draftOnEveryChange = false,
+    interactionMode = "interactive",
   } = options;
 
+  // Derived interaction mode flags
+  const isInteractiveMode = interactionMode === "interactive";
+
   // ============================================================
   // STATE MANAGEMENT
   // ============================================================
@@ -65,6 +69,11 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [lastFormValues] = useState<Partial<T>>({});
 
+  // Interactive mode state
+  const [draftId, setDraftId] = useState<string | null>(null);
+  const [isCreatingDraft, setIsCreatingDraft] = useState(false);
+  const [draftError, setDraftError] = useState<Error | null>(null);
+
   // Prevent infinite loop in API calls
   const isComputingRef = useRef(false);
   const computeTimeoutRef = useRef<NodeJS.Timeout | null>(null);
@@ -189,6 +198,61 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     }
   }, [schemaError]);
 
+  // ============================================================
+  // INTERACTIVE MODE - INITIAL DRAFT CREATION
+  // ============================================================
+
+  // Create initial draft for interactive create mode
+  useEffect(() => {
+    // Only run for interactive mode + create operation + schema loaded + no draft yet
+    if (
+      !isInteractiveMode ||
+      operation !== "create" ||
+      !schemaConfig ||
+      !enabled ||
+      draftId
+    ) {
+      return;
+    }
+
+    const createInitialDraft = async () => {
+      setIsCreatingDraft(true);
+      setDraftError(null);
+
+      try {
+        const client = api<T>(source);
+        // Call PATCH /{bdo_id}/draft with empty payload to get draft ID
+        const response = await client.draftInteraction({});
+
+        // Store the draft ID
+        setDraftId(response._id);
+
+        // Apply any computed fields returned from API
+        if (response && typeof response === "object") {
+          Object.entries(response).forEach(([fieldName, value]) => {
+            // Skip _id as it's the draft ID, not a form field
+            if (fieldName === "_id") return;
+
+            const currentValue = rhfForm.getValues(fieldName as any);
+            if (currentValue !== value) {
+              rhfForm.setValue(fieldName as any, value as any, {
+                shouldDirty: false,
+                shouldValidate: false,
+              });
+            }
+          });
+        }
+      } catch (error) {
+        console.error("Failed to create initial draft:", error);
+        setDraftError(error as Error);
+      } finally {
+        setIsCreatingDraft(false);
+      }
+    };
+
+    createInitialDraft();
+  }, [isInteractiveMode, operation, schemaConfig, enabled, draftId, source, rhfForm]);
+
   // ============================================================
   // COMPUTED FIELD DEPENDENCY TRACKING AND OPTIMIZATION
   // ============================================================
@@ -253,21 +317,29 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
   // Manual computation trigger - called on blur after validation passes
   const triggerComputationAfterValidation = useCallback(
     async (fieldName: string) => {
-      if (!schemaConfig || computedFieldDependencies.length === 0) {
+      if (!schemaConfig) {
         return;
       }
 
-      // Check if this field is a dependency for any computed fields
-      // If draftOnEveryChange is true, trigger for all fields
-      // If false (default), only trigger for computed field dependencies
-      const shouldTrigger =
-        draftOnEveryChange ||
-        computedFieldDependencies.includes(fieldName as Path<T>);
+      // Determine if draft should be triggered based on interaction mode
+      // Interactive mode: Always trigger draft API on blur
+      // Non-interactive mode: Only trigger for computed field dependencies (legacy behavior)
+      const shouldTrigger = isInteractiveMode
+        ? true // Interactive mode: always trigger
+        : (computedFieldDependencies.length > 0 &&
+            (draftOnEveryChange ||
+              computedFieldDependencies.includes(fieldName as Path<T>)));
 
       if (!shouldTrigger) {
         return;
       }
 
+      // For interactive create, check that we have a draftId (except for initial draft creation)
+      if (isInteractiveMode && operation === "create" && !draftId) {
+        console.warn("Interactive create mode: waiting for draft ID");
+        return;
+      }
+
       // Prevent concurrent API calls
       if (isComputingRef.current) {
         return;
@@ -305,6 +377,11 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
               (changedFields as any)._id = (currentValues as any)._id;
             }
 
+            // For interactive create mode, include draft _id
+            if (isInteractiveMode && operation === "create" && draftId) {
+              (changedFields as any)._id = draftId;
+            }
+
             // Use lastSyncedValues if available, otherwise use recordData (for update) or empty object (for create)
             const baseline =
               lastSyncedValuesRef.current ??
@@ -357,10 +434,18 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
 
             lastSyncedValuesRef.current = baselineBeforeApiCall;
 
-            const computedFieldsResponse =
-              operation === "update" && recordId
-                ? await client.draftPatch(recordId, payload)
-                : await client.draft(payload);
+            // Choose API method based on operation and interaction mode
+            let computedFieldsResponse;
+            if (operation === "update" && recordId) {
+              // Update mode: use draftPatch (both interactive and non-interactive)
+              computedFieldsResponse = await client.draftPatch(recordId, payload);
+            } else if (isInteractiveMode && draftId) {
+              // Interactive create: use draftInteraction with _id
+              computedFieldsResponse = await client.draftInteraction(payload);
+            } else {
+              // Non-interactive create: use draft (POST)
+              computedFieldsResponse = await client.draft(payload);
+            }
 
             // Apply computed fields returned from API
             if (
@@ -413,6 +498,8 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       rhfForm,
       computedFieldDependencies,
       draftOnEveryChange,
+      isInteractiveMode,
+      draftId,
     ]
   );
 
@@ -539,21 +626,51 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
               recordData as Partial<T> | undefined
             );
 
-            // Submit data to API
-            const result = await submitFormData<T>(
-              source,
-              operation,
-              cleanedData,
-              recordId
-            );
+            let result;
 
-            if (!result.success) {
-              throw result.error || new Error("Submission failed");
+            if (isInteractiveMode) {
+              // Interactive mode submission
+              const client = api<T>(source);
+
+              if (operation === "create") {
+                // Interactive create: must have draftId
+                if (!draftId) {
+                  throw new Error(
+                    "Interactive create mode requires a draft ID. Draft creation may have failed."
+                  );
+                }
+                // POST /{bdo_id}/draft with _id in payload
+                const response = await client.draft({
+                  ...cleanedData,
+                  _id: draftId,
+                } as any);
+                result = { success: true, data: response };
+              } else {
+                // Interactive update: POST /{bdo_id}/{id}/draft
+                const response = await client.draftUpdate(recordId!, cleanedData);
+                result = { success: true, data: response };
+              }
+            } else {
+              // Non-interactive mode: use existing submitFormData
+              result = await submitFormData<T>(
+                source,
+                operation,
+                cleanedData,
+                recordId
+              );
+
+              if (!result.success) {
+                throw result.error || new Error("Submission failed");
+              }
             }
 
             // Reset form for create operations
             if (operation === "create") {
               rhfForm.reset();
+              // Clear draft state for interactive mode
+              if (isInteractiveMode) {
+                setDraftId(null);
+              }
             }
 
             // Success callback with response data
@@ -579,6 +696,8 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       operation,
       recordId,
       recordData,
+      isInteractiveMode,
+      draftId,
     ]
   );
 
@@ -645,10 +764,13 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
   // COMPUTED PROPERTIES
   // ============================================================
 
+  // Loading state includes interactive mode draft creation
   const isLoadingInitialData =
-    isLoadingSchema || (operation === "update" && isLoadingRecord);
+    isLoadingSchema ||
+    (operation === "update" && isLoadingRecord) ||
+    (isInteractiveMode && operation === "create" && isCreatingDraft);
   const isLoading = isLoadingInitialData || isSubmitting;
-  const loadError = schemaError || recordError;
+  const loadError = schemaError || recordError || draftError;
   const hasError = !!loadError;
 
   const computedFields = useMemo<Array<keyof T>>(
@@ -809,6 +931,10 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     isLoadingRecord,
     isLoading,
 
+    // Interactive mode state
+    draftId,
+    isCreatingDraft,
+
     // Error handling
     loadError: loadError as Error | null,
     hasError,