@ram_28/kf-ai-sdk 1.0.10 → 1.0.12

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

@@ -9,11 +9,11 @@ import { useQuery } from "@tanstack/react-query";
 import type { Path } from "react-hook-form";
 
 import type {
-  UseFormOptions,
-  UseFormReturn,
-  BDOSchema,
-  FormSchemaConfig,
-  FormFieldConfig,
+  UseFormOptionsType,
+  UseFormReturnType,
+  BDOSchemaType,
+  FormSchemaConfigType,
+  FormFieldConfigType,
 } from "./types";
 
 import { processSchema, extractReferenceFields } from "./schemaParser.utils";
@@ -39,8 +39,8 @@ import {
 // ============================================================
 
 export function useForm<T extends Record<string, any> = Record<string, any>>(
-  options: UseFormOptions<T>
-): UseFormReturn<T> {
+  options: UseFormOptionsType<T>
+): UseFormReturnType<T> {
   const {
     source,
     operation,
@@ -52,19 +52,27 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     onSchemaError,
     skipSchemaFetch = false,
     schema: manualSchema,
-    draftOnEveryChange = false,
+    interactionMode = "interactive",
   } = options;
 
+  // Derived interaction mode flags
+  const isInteractiveMode = interactionMode === "interactive";
+
   // ============================================================
   // STATE MANAGEMENT
   // ============================================================
 
   const [schemaConfig, setSchemaConfig] =
-    useState<FormSchemaConfig | null>(null);
+    useState<FormSchemaConfigType | null>(null);
   const [referenceData, setReferenceData] = useState<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 +197,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 +316,28 @@ 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
+      const shouldTrigger = isInteractiveMode
+        ? true // Interactive mode: always trigger
+        : (computedFieldDependencies.length > 0 &&
+              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 +375,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 +432,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 (
@@ -412,7 +495,8 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       source,
       rhfForm,
       computedFieldDependencies,
-      draftOnEveryChange,
+      isInteractiveMode,
+      draftId,
     ]
   );
 
@@ -539,21 +623,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 (isInteractiveMode) {
+              // Interactive mode submission
+              const client = api<T>(source);
 
-            if (!result.success) {
-              throw result.error || new Error("Submission failed");
+              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 +693,8 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       operation,
       recordId,
       recordData,
+      isInteractiveMode,
+      draftId,
     ]
   );
 
@@ -587,16 +703,16 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
   // ============================================================
 
   const getField = useCallback(
-    <K extends keyof T>(fieldName: K): FormFieldConfig | null => {
+    <K extends keyof T>(fieldName: K): FormFieldConfigType | null => {
       return schemaConfig?.fields[fieldName as string] || null;
     },
     [schemaConfig]
   );
 
-  const getFields = useCallback((): Record<keyof T, FormFieldConfig> => {
-    if (!schemaConfig) return {} as Record<keyof T, FormFieldConfig>;
+  const getFields = useCallback((): Record<keyof T, FormFieldConfigType> => {
+    if (!schemaConfig) return {} as Record<keyof T, FormFieldConfigType>;
 
-    const typedFields: Record<keyof T, FormFieldConfig> = {} as any;
+    const typedFields: Record<keyof T, FormFieldConfigType> = {} as any;
     Object.entries(schemaConfig.fields).forEach(([key, field]) => {
       (typedFields as any)[key] = field;
     });
@@ -645,10 +761,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>>(
@@ -801,20 +920,21 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
     isSubmitting: rhfForm.formState.isSubmitting || isSubmitting,
     isSubmitSuccessful: rhfForm.formState.isSubmitSuccessful,
 
-    // BACKWARD COMPATIBILITY - Keep formState for existing components
-    formState: rhfForm.formState,
-
     // Loading states
     isLoadingInitialData,
     isLoadingRecord,
     isLoading,
 
+    // Interactive mode state
+    draftId,
+    isCreatingDraft,
+
     // Error handling
     loadError: loadError as Error | null,
     hasError,
 
     // Schema information
-    schema: schema as BDOSchema | null,
+    schema: schema as BDOSchemaType | null,
     schemaConfig,
     computedFields,
     requiredFields,

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

@@ -5,18 +5,18 @@
 // Follows the same structure as useForm and useTable API clients
 
 import { api } from "../../../api";
-import type { 
-  ListOptions, 
-  ListResponse, 
-  CreateUpdateResponse,
-  DeleteResponse,
-  CountResponse 
+import type {
+  ListOptionsType,
+  ListResponseType,
+  CreateUpdateResponseType,
+  DeleteResponseType,
+  CountResponseType
 } from "../../../types/common";
 import type {
-  KanbanCard,
-  KanbanColumn,
-  BulkCardUpdateRequest,
-  BulkColumnUpdateRequest
+  KanbanCardType,
+  KanbanColumnType,
+  BulkCardUpdateRequestType,
+  BulkColumnUpdateRequestType
 } from "./types";
 
 // ============================================================
@@ -28,18 +28,18 @@ import type {
  */
 export async function fetchColumns<T>(
   source: string, 
-  options?: ListOptions
-): Promise<KanbanColumn<T>[]> {
-  const client = api<KanbanColumn<T>>(source);
+  options?: ListOptionsType
+): Promise<KanbanColumnType<T>[]> {
+  const client = api<KanbanColumnType<T>>(source);
   
   // Build API options for columns query
-  const apiOptions: ListOptions = {
+  const apiOptions: ListOptionsType = {
     ...options,
     // Default sort by position if no sort specified - using correct API format
     Sort: options?.Sort || [{ position: "ASC" }]
   };
   
-  const response: ListResponse<KanbanColumn<T>> = await client.list(apiOptions);
+  const response: ListResponseType<KanbanColumnType<T>> = await client.list(apiOptions);
   
   // Initialize empty cards array for each column
   // Cards will be fetched separately and merged
@@ -54,14 +54,14 @@ export async function fetchColumns<T>(
  */
 export async function createColumn<T>(
   source: string, 
-  column: Partial<KanbanColumn<T>>
+  column: Partial<KanbanColumnType<T>>
 ): Promise<string> {
-  const client = api<KanbanColumn<T>>(source);
+  const client = api<KanbanColumnType<T>>(source);
   
   // Exclude cards array from creation payload
   const { cards, ...columnData } = column;
   
-  const response: CreateUpdateResponse = await client.create(columnData);
+  const response: CreateUpdateResponseType = await client.create(columnData);
   return response._id;
 }
 
@@ -71,9 +71,9 @@ export async function createColumn<T>(
 export async function updateColumn<T>(
   source: string,
   id: string, 
-  updates: Partial<KanbanColumn<T>>
+  updates: Partial<KanbanColumnType<T>>
 ): Promise<void> {
-  const client = api<KanbanColumn<T>>(source);
+  const client = api<KanbanColumnType<T>>(source);
   
   // Exclude cards array from update payload
   const { cards, ...columnUpdates } = updates;
@@ -99,7 +99,7 @@ export async function reorderColumns<T>(
   source: string,
   columnIds: string[]
 ): Promise<void> {
-  const client = api<KanbanColumn<T>>(source);
+  const client = api<KanbanColumnType<T>>(source);
   
   // Update position for each column
   const updates = columnIds.map((id, index) => ({
@@ -124,12 +124,12 @@ export async function reorderColumns<T>(
  */
 export async function fetchCards<T>(
   source: string,
-  options?: ListOptions
-): Promise<KanbanCard<T>[]> {
-  const client = api<KanbanCard<T>>(source);
+  options?: ListOptionsType
+): Promise<KanbanCardType<T>[]> {
+  const client = api<KanbanCardType<T>>(source);
   
   // Build API options for cards query
-  const apiOptions: ListOptions = {
+  const apiOptions: ListOptionsType = {
     ...options,
     // Default sort by column and position if no sort specified - using correct API format
     Sort: options?.Sort || [
@@ -138,7 +138,7 @@ export async function fetchCards<T>(
     ]
   };
   
-  const response: ListResponse<KanbanCard<T>> = await client.list(apiOptions);
+  const response: ListResponseType<KanbanCardType<T>> = await client.list(apiOptions);
   return response.Data;
 }
 
@@ -147,11 +147,11 @@ export async function fetchCards<T>(
  */
 export async function createCard<T>(
   source: string,
-  card: Partial<KanbanCard<T>> & { columnId: string }
+  card: Partial<KanbanCardType<T>> & { columnId: string }
 ): Promise<string> {
-  const client = api<KanbanCard<T>>(source);
+  const client = api<KanbanCardType<T>>(source);
   
-  const response: CreateUpdateResponse = await client.create(card);
+  const response: CreateUpdateResponseType = await client.create(card);
   return response._id;
 }
 
@@ -161,9 +161,9 @@ export async function createCard<T>(
 export async function updateCard<T>(
   source: string,
   id: string,
-  updates: Partial<KanbanCard<T>>
+  updates: Partial<KanbanCardType<T>>
 ): Promise<void> {
-  const client = api<KanbanCard<T>>(source);
+  const client = api<KanbanCardType<T>>(source);
   await client.update(id, updates);
 }
 
@@ -187,7 +187,7 @@ export async function moveCard<T>(
   toColumnId: string,
   position?: number
 ): Promise<void> {
-  const client = api<KanbanCard<T>>(source);
+  const client = api<KanbanCardType<T>>(source);
   
   const updates: any = {
     columnId: toColumnId,
@@ -205,7 +205,7 @@ export async function reorderCards<T>(
   cardIds: string[],
   columnId: string
 ): Promise<void> {
-  const client = api<KanbanCard<T>>(source);
+  const client = api<KanbanCardType<T>>(source);
   
   // Update position for each card
   const updates = cardIds.map((id, index) => ({
@@ -230,9 +230,9 @@ export async function reorderCards<T>(
  */
 export async function bulkUpdateCards<T>(
   source: string,
-  request: BulkCardUpdateRequest<T>
+  request: BulkCardUpdateRequestType<T>
 ): Promise<void> {
-  const client = api<KanbanCard<T>>(source);
+  const client = api<KanbanCardType<T>>(source);
   
   await Promise.all(
     request.updates.map(update => 
@@ -246,9 +246,9 @@ export async function bulkUpdateCards<T>(
  */
 export async function bulkUpdateColumns<T>(
   source: string,
-  request: BulkColumnUpdateRequest<T>
+  request: BulkColumnUpdateRequestType<T>
 ): Promise<void> {
-  const client = api<KanbanColumn<T>>(source);
+  const client = api<KanbanColumnType<T>>(source);
   
   await Promise.all(
     request.updates.map(update =>
@@ -266,7 +266,7 @@ export async function bulkMoveCards<T>(
   toColumnId: string,
   startPosition = 0
 ): Promise<void> {
-  const client = api<KanbanCard<T>>(cardSource);
+  const client = api<KanbanCardType<T>>(cardSource);
   
   const updates = cardIds.map((cardId, index) => ({
     cardId,
@@ -296,7 +296,7 @@ export async function getCardCount(
 ): Promise<number> {
   const client = api(source);
   
-  const options: ListOptions = {
+  const options: ListOptionsType = {
     Filter: {
       Operator: "And",
       Condition: [
@@ -310,7 +310,7 @@ export async function getCardCount(
     }
   };
   
-  const response: CountResponse = await client.count(options);
+  const response: CountResponseType = await client.count(options);
   return response.Count;
 }
 
@@ -319,10 +319,10 @@ export async function getCardCount(
  */
 export async function getTotalCardCount(
   source: string,
-  options?: ListOptions
+  options?: ListOptionsType
 ): Promise<number> {
   const client = api(source);
-  const response: CountResponse = await client.count(options);
+  const response: CountResponseType = await client.count(options);
   return response.Count;
 }
 
@@ -332,11 +332,11 @@ export async function getTotalCardCount(
 export async function searchCards<T>(
   source: string,
   searchQuery: string,
-  additionalOptions?: ListOptions
-): Promise<KanbanCard<T>[]> {
-  const client = api<KanbanCard<T>>(source);
+  additionalOptions?: ListOptionsType
+): Promise<KanbanCardType<T>[]> {
+  const client = api<KanbanCardType<T>>(source);
   
-  const options: ListOptions = {
+  const options: ListOptionsType = {
     ...additionalOptions,
     Search: searchQuery,
     Sort: additionalOptions?.Sort || [
@@ -345,7 +345,7 @@ export async function searchCards<T>(
     ]
   };
   
-  const response: ListResponse<KanbanCard<T>> = await client.list(options);
+  const response: ListResponseType<KanbanCardType<T>> = await client.list(options);
   return response.Data;
 }
 
@@ -357,9 +357,9 @@ export async function searchCards<T>(
  * Merge cards into their respective columns
  */
 export function mergeCardsIntoColumns<T>(
-  columns: KanbanColumn<T>[],
-  cards: KanbanCard<T>[]
-): KanbanColumn<T>[] {
+  columns: KanbanColumnType<T>[],
+  cards: KanbanCardType<T>[]
+): KanbanColumnType<T>[] {
   // Group cards by columnId
   const cardsByColumn = cards.reduce((acc, card) => {
     if (!acc[card.columnId]) {
@@ -367,7 +367,7 @@ export function mergeCardsIntoColumns<T>(
     }
     acc[card.columnId].push(card);
     return acc;
-  }, {} as Record<string, KanbanCard<T>[]>);
+  }, {} as Record<string, KanbanCardType<T>[]>);
   
   // Assign cards to their respective columns
   return columns.map(column => ({
@@ -381,7 +381,7 @@ export function mergeCardsIntoColumns<T>(
  * Calculate optimal position for inserting a new card
  */
 export function calculateCardPosition<T>(
-  column: KanbanColumn<T>,
+  column: KanbanColumnType<T>,
   insertIndex?: number
 ): number {
   if (column.cards.length === 0) {
@@ -410,7 +410,7 @@ export function calculateCardPosition<T>(
  * Calculate optimal position for inserting a new column
  */
 export function calculateColumnPosition<T>(
-  columns: KanbanColumn<T>[],
+  columns: KanbanColumnType<T>[],
   insertIndex?: number
 ): number {
   if (columns.length === 0) {
@@ -478,7 +478,7 @@ export function handleKanbanApiError(
 export function validateApiResponse<T>(
   response: any,
   expectedType: 'list' | 'single' | 'create' | 'delete'
-): response is ListResponse<T> | T | CreateUpdateResponse | DeleteResponse {
+): response is ListResponseType<T> | T | CreateUpdateResponseType | DeleteResponseType {
   switch (expectedType) {
     case 'list':
       return response && Array.isArray(response.Data);

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

@@ -1,7 +1,7 @@
 import { createContext, useContext } from "react";
-import { UseKanbanReturn } from "./types";
+import { UseKanbanReturnType } from "./types";
 
-export const KanbanContext = createContext<UseKanbanReturn<any> | null>(null);
+export const KanbanContext = createContext<UseKanbanReturnType<any> | null>(null);
 
 export function useKanbanContext<T extends Record<string, any> = any>() {
   const context = useContext(KanbanContext);
@@ -10,5 +10,5 @@ export function useKanbanContext<T extends Record<string, any> = any>() {
       "Kanban components must be used within a KanbanBoard component"
     );
   }
-  return context as UseKanbanReturn<T>;
+  return context as UseKanbanReturnType<T>;
 }