@ram_28/kf-ai-sdk 1.0.9 → 1.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "1.0.9",
+  "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

@@ -6,8 +6,6 @@ import type {
   UseFormRegister,
   Mode,
   FieldValues as RHFFieldValues,
-  SubmitHandler,
-  SubmitErrorHandler,
   FieldErrors,
   Path,
   PathValue,
@@ -21,15 +19,23 @@ import type {
 // ============================================================
 
 /**
- * Extended handleSubmit that allows optional callbacks
- * When no callback is provided, uses the SDK's built-in submit function
+ * HandleSubmit follows React Hook Form's signature pattern
+ *
+ * - onSuccess: Called with the API response data on successful submission
+ * - onError: Called with either FieldErrors (validation failed) or Error (API failed)
+ *
+ * Internal flow:
+ * 1. RHF validation + Cross-field validation → FAILS → onError(fieldErrors)
+ * 2. Clean data & call API → FAILS → onError(apiError)
+ * 3. SUCCESS → onSuccess(responseData)
  */
-export type ExtendedHandleSubmit<T extends RHFFieldValues> = {
-  (
-    onValid?: SubmitHandler<T>,
-    onInvalid?: SubmitErrorHandler<T>
-  ): (e?: React.BaseSyntheticEvent) => Promise<void>;
-};
+export type HandleSubmit<T extends RHFFieldValues> = (
+  onSuccess?: (data: T, e?: React.BaseSyntheticEvent) => void | Promise<void>,
+  onError?: (
+    error: FieldErrors<T> | Error,
+    e?: React.BaseSyntheticEvent
+  ) => void | Promise<void>
+) => (e?: React.BaseSyntheticEvent) => Promise<void>;
 
 // ============================================================
 // EXPRESSION TREE TYPES
@@ -223,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)
  */
@@ -276,18 +289,9 @@ export interface UseFormOptions<
   /** User role for permission enforcement */
   userRole?: string;
 
-  /** Success callback */
-  onSuccess?: (data: T) => void;
-
-  /** Error callback */
-  onError?: (error: Error) => void;
-
-  /** Schema load error callback */
+  /** Schema load error callback (separate concern from form submission) */
   onSchemaError?: (error: Error) => void;
 
-  /** Submit error callback */
-  onSubmitError?: (error: Error) => void;
-
   /** Skip schema fetching (use for testing) */
   skipSchemaFetch?: boolean;
 
@@ -298,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;
 }
 
 // ============================================================
@@ -448,8 +461,38 @@ export interface UseFormReturn<
     options?: RegisterOptions<T, K>
   ) => ReturnType<UseFormRegister<T>>;
 
-  /** Handle form submission - automatically uses SDK's submit logic */
-  handleSubmit: () => (e?: React.BaseSyntheticEvent) => Promise<void>;
+  /**
+   * Handle form submission with optional callbacks
+   *
+   * @example
+   * // Basic usage - no callbacks
+   * <form onSubmit={form.handleSubmit()}>
+   *
+   * @example
+   * // With success callback
+   * <form onSubmit={form.handleSubmit((data) => {
+   *   toast.success("Saved!");
+   *   navigate("/products/" + data._id);
+   * })}>
+   *
+   * @example
+   * // With both callbacks
+   * <form onSubmit={form.handleSubmit(
+   *   (data) => toast.success("Saved!"),
+   *   (error) => {
+   *     if (error instanceof Error) {
+   *       toast.error(error.message); // API error
+   *     } else {
+   *       toast.error("Please fix the form errors"); // Validation errors
+   *     }
+   *   }
+   * )}>
+   *
+   * @example
+   * // Programmatic submission
+   * await form.handleSubmit(onSuccess, onError)();
+   */
+  handleSubmit: HandleSubmit<T>;
 
   /** Watch field values with strict typing */
   watch: <K extends Path<T> | readonly Path<T>[]>(
@@ -509,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
   // ============================================================
@@ -516,9 +569,6 @@ export interface UseFormReturn<
   /** Schema fetch error */
   loadError: Error | null;
 
-  /** Form submission error */
-  submitError: Error | null;
-
   /** Any error active */
   hasError: boolean;
 
@@ -561,9 +611,6 @@ export interface UseFormReturn<
   // OPERATIONS
   // ============================================================
 
-  /** Submit form manually */
-  submit: () => Promise<void>;
-
   /** Refresh schema */
   refreshSchema: () => Promise<void>;