@ram_28/kf-ai-sdk 2.0.2 → 2.0.3

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

@@ -0,0 +1,251 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import type { UseFormReturn, FieldValues } from "react-hook-form";
+import type { BaseField } from "../../../bdo/fields/BaseField";
+import type { InteractiveCreatableBdo } from "./types";
+
+// ============================================================
+// TYPES
+// ============================================================
+
+interface UseDraftInteractionOptions {
+  /** The BDO instance — must expose interactive draft methods */
+  bdo: InteractiveCreatableBdo;
+  /** RHF form instance */
+  form: UseFormReturn<FieldValues>;
+  /** RHF validation mode */
+  mode: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
+  /** BDO field definitions (for determining dirty fields) */
+  fields: Record<string, BaseField<unknown>>;
+  /** Whether interactive mode is enabled */
+  enabled: boolean;
+}
+
+interface UseDraftInteractionReturn {
+  draftId: string | undefined;
+  isInitializingDraft: boolean;
+  isInteracting: boolean;
+  interactionError: Error | null;
+  triggerInteraction: () => void;
+  commitDraft: (dirtyData: Record<string, unknown>) => Promise<unknown>;
+}
+
+// ============================================================
+// DEBOUNCE DELAY
+// ============================================================
+
+const DEBOUNCE_MS = 300;
+
+// ============================================================
+// HOOK
+// ============================================================
+
+export function useDraftInteraction(
+  options: UseDraftInteractionOptions,
+): UseDraftInteractionReturn {
+  const { bdo, form, mode, fields, enabled } = options;
+
+  // ============================================================
+  // STATE
+  // ============================================================
+
+  const [draftId, setDraftId] = useState<string | undefined>(undefined);
+  const [isInitializingDraft, setIsInitializingDraft] = useState(false);
+  const [isInteracting, setIsInteracting] = useState(false);
+  const [interactionError, setInteractionError] = useState<Error | null>(null);
+
+  // ============================================================
+  // REFS (for concurrency control & loop prevention)
+  // ============================================================
+
+  /** Tracks the latest interaction call — stale responses are discarded */
+  const interactionCounterRef = useRef(0);
+
+  /** Prevents re-trigger when applying computed values via setValue */
+  const isApplyingComputedRef = useRef(false);
+
+  /** Debounce timer for onChange mode */
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  /** AbortController for cleanup on unmount */
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  // ============================================================
+  // DRAFT INITIALIZATION (Create mode only)
+  // ============================================================
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    let cancelled = false;
+    setIsInitializingDraft(true);
+
+    const controller = new AbortController();
+    abortControllerRef.current = controller;
+
+    bdo
+      .draftInteraction({})
+      .then((response) => {
+        if (cancelled || controller.signal.aborted) return;
+        const id = response._id;
+        setDraftId(id);
+        // Set _id into form without marking dirty
+        form.setValue("_id" as any, id, { shouldDirty: false });
+        setInteractionError(null);
+      })
+      .catch((error) => {
+        if (cancelled || controller.signal.aborted) return;
+        setInteractionError(error instanceof Error ? error : new Error(String(error)));
+      })
+      .finally(() => {
+        if (!cancelled) setIsInitializingDraft(false);
+      });
+
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [enabled, bdo, form]);
+
+  // ============================================================
+  // CORE INTERACTION LOGIC
+  // ============================================================
+
+  const executeInteraction = useCallback(async () => {
+    if (!enabled || !draftId) return;
+    if (isApplyingComputedRef.current) return;
+
+    // Build payload from dirty fields
+    const dirtyFields = form.formState.dirtyFields;
+    const allValues = form.getValues();
+    const payload: Record<string, unknown> = {};
+
+    for (const [key, isDirty] of Object.entries(dirtyFields)) {
+      if (isDirty && fields[key] && !fields[key].readOnly) {
+        payload[key] = allValues[key];
+      }
+    }
+
+    // Skip if nothing changed
+    if (Object.keys(payload).length === 0) return;
+
+    // Increment counter for concurrency control
+    const currentCounter = ++interactionCounterRef.current;
+
+    setIsInteracting(true);
+
+    try {
+      const response = await bdo.draftInteraction({
+        _id: draftId,
+        ...payload,
+      } as any);
+
+      // Only apply if this is still the latest interaction
+      if (currentCounter !== interactionCounterRef.current) return;
+
+      // Apply computed values back to form
+      isApplyingComputedRef.current = true;
+      try {
+        for (const [key, value] of Object.entries(response)) {
+          // Skip _id and fields the user has dirty (don't overwrite user input)
+          if (key === "_id") continue;
+          if (dirtyFields[key]) continue;
+
+          form.setValue(key as any, value, {
+            shouldDirty: false,
+            shouldValidate: false,
+          });
+        }
+      } finally {
+        // Reset flag after React settles
+        // Using setTimeout(0) ensures setValue batch is complete
+        setTimeout(() => {
+          isApplyingComputedRef.current = false;
+        }, 0);
+      }
+
+      setInteractionError(null);
+    } catch (error) {
+      // Only set error if this is still the latest interaction
+      if (currentCounter !== interactionCounterRef.current) return;
+      setInteractionError(error instanceof Error ? error : new Error(String(error)));
+    } finally {
+      if (currentCounter === interactionCounterRef.current) {
+        setIsInteracting(false);
+      }
+    }
+  }, [enabled, draftId, form, fields, bdo]);
+
+  // ============================================================
+  // TRIGGER INTERACTION (with optional debounce)
+  // ============================================================
+
+  const triggerInteraction = useCallback(() => {
+    if (!enabled) return;
+
+    // For onChange/all modes, debounce the interaction
+    if (mode === "onChange" || mode === "all") {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      debounceTimerRef.current = setTimeout(() => {
+        executeInteraction();
+      }, DEBOUNCE_MS);
+    } else {
+      // For onBlur/onTouched/onSubmit, trigger immediately
+      executeInteraction();
+    }
+  }, [enabled, mode, executeInteraction]);
+
+  // ============================================================
+  // COMMIT DRAFT (for handleSubmit)
+  // ============================================================
+
+  const commitDraft = useCallback(
+    async (dirtyData: Record<string, unknown>): Promise<unknown> => {
+      return bdo.draft({
+        _id: draftId,
+        ...dirtyData,
+      } as any);
+    },
+    [bdo, draftId],
+  );
+
+  // ============================================================
+  // CLEANUP
+  // ============================================================
+
+  useEffect(() => {
+    return () => {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      abortControllerRef.current?.abort();
+    };
+  }, []);
+
+  // ============================================================
+  // DISABLED MODE (return no-ops)
+  // ============================================================
+
+  if (!enabled) {
+    return {
+      draftId: undefined,
+      isInitializingDraft: false,
+      isInteracting: false,
+      interactionError: null,
+      triggerInteraction: () => {},
+      commitDraft: async () => {
+        throw new Error("Draft interaction is not enabled");
+      },
+    };
+  }
+
+  return {
+    draftId,
+    isInitializingDraft,
+    isInteracting,
+    interactionError,
+    triggerInteraction,
+    commitDraft,
+  };
+}

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

@@ -10,6 +10,7 @@ import {
 import { useQuery } from "@tanstack/react-query";
 import { createResolver } from "./createResolver";
 import { createItemProxy } from "./createItemProxy";
+import { useDraftInteraction } from "./useDraftInteraction";
 import { getBdoSchema } from "../../../api/metadata";
 import type { BaseBdo } from "../../../bdo";
 import type {
@@ -19,6 +20,7 @@ import type {
   AllFieldsType,
   CreatableBdo,
   UpdatableBdo,
+  InteractiveCreatableBdo,
 } from "./types";
 
 /**
@@ -33,6 +35,7 @@ import type {
  * - Smart register: auto-disables readonly fields
  * - Payload filtering: handleSubmit auto-filters to editable fields only
  * - Constraint validation: auto-validates required, length, etc. from field meta
+ * - Interactive draft mode: real-time server-side computation on field blur/change
  */
 export function useForm<B extends BaseBdo<any, any, any>>(
   options: UseFormOptionsType<B>,
@@ -43,11 +46,30 @@ export function useForm<B extends BaseBdo<any, any, any>>(
     operation: explicitOperation,
     defaultValues,
     mode = "onBlur",
-    enableDraft: _enableDraft = false,
+    enableDraft,
     enableConstraintValidation,
     enableExpressionValidation,
   } = options;
 
+  // ============================================================
+  // INTERACTION MODE RESOLUTION
+  // ============================================================
+
+  const explicitInteractionMode = (options as any).interactionMode as
+    | "interactive"
+    | "non-interactive"
+    | undefined;
+
+  const interactionMode =
+    explicitInteractionMode ??
+    (enableDraft === true
+      ? "interactive"
+      : enableDraft === false
+        ? "non-interactive"
+        : "interactive");
+
+  const isInteractive = interactionMode === "interactive";
+
   // Infer operation from recordId if not explicitly provided
   const operation = explicitOperation ?? (recordId ? "update" : "create");
 
@@ -114,6 +136,31 @@ export function useForm<B extends BaseBdo<any, any, any>>(
       operation === "update" && record ? (record as FieldValues) : undefined,
   });
 
+  // ============================================================
+  // FIELD DEFINITIONS
+  // ============================================================
+
+  const fields = bdo.getFields();
+
+  // ============================================================
+  // DRAFT INTERACTION
+  // ============================================================
+
+  const {
+    draftId,
+    isInitializingDraft,
+    isInteracting,
+    interactionError,
+    triggerInteraction,
+    commitDraft,
+  } = useDraftInteraction({
+    bdo: bdo as unknown as InteractiveCreatableBdo,
+    form,
+    mode,
+    fields,
+    enabled: isInteractive && operation === "create",
+  });
+
   // ============================================================
   // ITEM PROXY
   // ============================================================
@@ -125,11 +172,9 @@ export function useForm<B extends BaseBdo<any, any, any>>(
   );
 
   // ============================================================
-  // SMART REGISTER (auto-disables readonly fields)
+  // SMART REGISTER (auto-disables readonly fields + interaction trigger)
   // ============================================================
 
-  const fields = bdo.getFields();
-
   const smartRegister = useCallback(
     (name: string, registerOptions?: RegisterOptions) => {
       const rhfResult = form.register(name as any, registerOptions);
@@ -139,11 +184,44 @@ export function useForm<B extends BaseBdo<any, any, any>>(
         return { ...rhfResult, disabled: true };
       }
 
+      // In interactive mode, wrap onBlur for blur-triggered interaction
+      if (
+        isInteractive &&
+        (mode === "onBlur" || mode === "onTouched" || mode === "all")
+      ) {
+        const originalOnBlur = rhfResult.onBlur;
+        return {
+          ...rhfResult,
+          onBlur: async (e: React.FocusEvent) => {
+            await originalOnBlur(e); // RHF validation first
+            triggerInteraction(); // then server interaction
+          },
+        };
+      }
+
       return rhfResult;
     },
-    [form, fields],
+    [form, fields, isInteractive, mode, triggerInteraction],
   );
 
+  // ============================================================
+  // WATCH SUBSCRIPTION (for onChange/all mode interaction)
+  // ============================================================
+
+  useEffect(() => {
+    if (!isInteractive || (mode !== "onChange" && mode !== "all")) return;
+
+    const subscription = form.watch((_value, { type }) => {
+      // RHF fires with type: "change" for user input,
+      // type: undefined for programmatic setValue — prevents re-trigger loops
+      if (type === "change") {
+        triggerInteraction(); // debounced inside useDraftInteraction
+      }
+    });
+
+    return () => subscription.unsubscribe();
+  }, [isInteractive, mode, form, triggerInteraction]);
+
   // ============================================================
   // CUSTOM HANDLE SUBMIT (with API call + payload filtering)
   // ============================================================
@@ -155,31 +233,34 @@ export function useForm<B extends BaseBdo<any, any, any>>(
         async (data, e) => {
           try {
             const filteredData: Record<string, unknown> = {};
+            let result: unknown;
 
-            if (operation === "create") {
-              // Create mode - send all known, non-readonly fields
+            if (isInteractive && operation === "create") {
+              // Interactive create - send only dirty, non-readonly fields
+              // (record already exists from init, so only send changes)
+              const dirtyFields = form.formState.dirtyFields;
+              for (const [key, value] of Object.entries(data)) {
+                if (fields[key] && !fields[key].readOnly && dirtyFields[key]) {
+                  filteredData[key] = value;
+                }
+              }
+              result = await commitDraft(filteredData);
+            } else if (operation === "create") {
+              // Non-interactive create - send all known, non-readonly fields
               for (const [key, value] of Object.entries(data)) {
                 if (fields[key] && !fields[key].readOnly) {
                   filteredData[key] = value;
                 }
               }
+              result = await (bdo as unknown as CreatableBdo).create(filteredData);
             } else {
-              // Update mode - send only known, non-readonly, dirty fields
+              // Update (always non-interactive) - send only dirty, non-readonly fields
               const dirtyFields = form.formState.dirtyFields;
               for (const [key, value] of Object.entries(data)) {
                 if (fields[key] && !fields[key].readOnly && dirtyFields[key]) {
                   filteredData[key] = value;
                 }
               }
-            }
-
-            let result: unknown;
-
-            if (operation === "create") {
-              // Safe: create operation requires CreatableBdo (enforced by UseFormOptionsType)
-              result = await (bdo as unknown as CreatableBdo).create(filteredData);
-            } else {
-              // Safe: update operation requires UpdatableBdo (enforced by UseFormOptionsType)
               result = await (bdo as unknown as UpdatableBdo).update(recordId!, filteredData);
             }
 
@@ -196,7 +277,7 @@ export function useForm<B extends BaseBdo<any, any, any>>(
         },
       );
     },
-    [form, bdo, operation, recordId, fields],
+    [form, bdo, operation, recordId, fields, isInteractive, commitDraft],
   );
 
   // ============================================================
@@ -236,10 +317,16 @@ export function useForm<B extends BaseBdo<any, any, any>>(
     dirtyFields: form.formState.dirtyFields as any,
 
     // Loading states
-    isLoading: isLoadingRecord,
+    isLoading: isLoadingRecord || isInitializingDraft,
     isFetching: isFetchingRecord,
 
     // Error
     loadError: recordError as Error | null,
+
+    // Draft / Interactive mode
+    draftId,
+    isInitializingDraft,
+    isInteracting,
+    interactionError,
   };
 }

package/sdk/form.types.ts

@@ -14,4 +14,5 @@ export type {
   ExtractEditableType,
   ExtractReadonlyType,
   AllFieldsType,
+  InteractiveCreatableBdo,
 } from "./components/hooks/useForm";

package/sdk/index.ts

@@ -40,6 +40,12 @@ export type {
 
 export { api, setApiBaseUrl, getApiBaseUrl, getBdoSchema } from './api';
 
+// ============================================================
+// WORKFLOW CLIENT - Business Process / Activity operations
+// ============================================================
+
+export { Workflow, useActivityForm } from './workflow';
+
 // ============================================================
 // TYPES - Core type definitions
 // ============================================================

package/sdk/types/constants.ts

@@ -211,9 +211,9 @@ export const FormOperation = {
  * });
  */
 export const InteractionMode = {
-  /** Real-time server-side validation and computation on every field blur */
+  /** Real-time server-side validation and computation on field blur/change */
   Interactive: "interactive",
-  /** Draft only for computed field dependencies */
+  /** No server interaction during editing — submit only */
   NonInteractive: "non-interactive",
 } as const;
 

package/sdk/workflow/Activity.ts

@@ -0,0 +1,181 @@
+// ============================================================
+// ACTIVITY BASE CLASS
+// ============================================================
+// Lean abstract base class for typed workflow activities.
+// Replaces ActivityForm — no public getFields(), no phantom types,
+// no exported meta type.
+//
+// Each activity subclass defines:
+//   - meta: { businessProcessId, activityId }
+//   - Typed field instances as class properties
+//
+// Methods:
+//   activity.getInstanceList(options)  // list activity instances
+//   activity.instanceMetrics(options)  // get aggregated metrics
+//   activity.getInstance(instanceId)   // get typed ActivityInstance
+
+import { Workflow } from "./client";
+import { createActivityInstance } from "./ActivityInstance";
+import type { ActivityInstanceType } from "./ActivityInstance";
+import type { ActivityInstanceFieldsType, ActivityOperations } from "./types";
+import type {
+  ListOptionsType,
+  ListResponseType,
+  MetricOptionsType,
+  MetricResponseType,
+} from "../types/common";
+import { BaseField } from "../bdo/fields/BaseField";
+
+// ============================================================
+// ABSTRACT BASE CLASS
+// ============================================================
+
+/**
+ * Abstract base class for workflow activities.
+ *
+ * Extend this class to define typed activity input fields.
+ * Each activity is a typed class with field definitions and data operations.
+ *
+ * @template TEntity - The full entity type with all fields
+ * @template TEditable - Fields the user can edit
+ * @template TReadonly - Fields that are read-only (computed / system)
+ *
+ * @example
+ * ```typescript
+ * class EmployeeInputActivity extends Activity<
+ *   EmployeeInputEntityType,
+ *   EmployeeInputEditable,
+ *   EmployeeInputReadonly
+ * > {
+ *   readonly meta = {
+ *     businessProcessId: "SimpleLeaveProcess",
+ *     activityId: "EMPLOYEE_INPUT",
+ *   };
+ *
+ *   readonly StartDate = new DateTimeField({ id: "StartDate", label: "Start Date" });
+ *   readonly EndDate = new DateTimeField({ id: "EndDate", label: "End Date" });
+ *   readonly LeaveDays = new NumberField({ id: "LeaveDays", label: "Leave Days", editable: false });
+ * }
+ *
+ * const activity = new EmployeeInputActivity();
+ * const items = await activity.getInstanceList({ Page: 1, PageSize: 10 });
+ * const instance = await activity.getInstance("inst_123");
+ * instance.StartDate.get();  // typed value
+ * instance.StartDate.set("2026-03-01");
+ * await instance.update({ StartDate: "2026-03-01" });
+ * ```
+ */
+export abstract class Activity<
+  TEntity extends Record<string, unknown>,
+  TEditable extends Record<string, unknown> = TEntity,
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  TReadonly extends Record<string, unknown> = {},
+> {
+  /**
+   * Activity metadata — identifies the business process and activity
+   */
+  abstract readonly meta: {
+    readonly businessProcessId: string;
+    readonly activityId: string;
+  };
+
+  // ============================================================
+  // ACTIVITY OPERATIONS (internal)
+  // ============================================================
+
+  /**
+   * Get ActivityOperations for this activity.
+   * @internal
+   */
+  private _ops(): ActivityOperations<TEntity> {
+    return new Workflow<TEntity>(this.meta.businessProcessId)
+      .activity(this.meta.activityId);
+  }
+
+  // ============================================================
+  // FIELD DISCOVERY (internal)
+  // ============================================================
+
+  private _fieldsCache: Record<string, BaseField<unknown>> | null = null;
+
+  /**
+   * Discover BaseField instances from subclass properties.
+   * @internal
+   */
+  private _discoverFields(): Record<string, BaseField<unknown>> {
+    if (this._fieldsCache) return this._fieldsCache;
+
+    const fields: Record<string, BaseField<unknown>> = {};
+    for (const key of Object.keys(this)) {
+      const value = (this as Record<string, unknown>)[key];
+      if (value instanceof BaseField) {
+        fields[key] = value;
+      }
+    }
+
+    this._fieldsCache = fields;
+    return fields;
+  }
+
+  // ============================================================
+  // PUBLIC METHODS
+  // ============================================================
+
+  /**
+   * List activity instances with optional filtering/pagination.
+   */
+  async getInstanceList(
+    options?: ListOptionsType,
+  ): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
+    return this._ops().list(options);
+  }
+
+  /**
+   * Get aggregated metrics for activity instances.
+   */
+  async instanceMetrics(
+    options: Omit<MetricOptionsType, "Type">,
+  ): Promise<MetricResponseType> {
+    return this._ops().metric(options);
+  }
+
+  /**
+   * Get a typed ActivityInstance with field accessors and persistence methods.
+   *
+   * @param instanceId - The activity instance identifier
+   * @returns ActivityInstance with typed field accessors
+   */
+  async getInstance(
+    instanceId: string,
+  ): Promise<ActivityInstanceType<TEntity, TEditable, TReadonly>> {
+    const ops = this._ops();
+    const data = await ops.read(instanceId);
+    const fields = this._discoverFields();
+    return createActivityInstance<TEntity, TEditable, TReadonly>(
+      ops,
+      instanceId,
+      data as TEntity,
+      fields,
+    );
+  }
+
+  // ============================================================
+  // INTERNAL ACCESSORS (used by useActivityForm hook)
+  // ============================================================
+
+  /**
+   * Get discovered fields — used internally by useActivityForm hook.
+   * @internal
+   */
+  _getFields(): Record<string, BaseField<unknown>> {
+    return this._discoverFields();
+  }
+
+  /**
+   * Get ActivityOperations — used internally by useActivityForm hook.
+   * @internal
+   */
+  _getOps(): ActivityOperations<TEntity> {
+    return this._ops();
+  }
+}