@ram_28/kf-ai-sdk 2.0.14 → 2.0.16

package/sdk/components/hooks/useBDOForm/shared.ts

@@ -0,0 +1,250 @@
+// ============================================================
+// SHARED FORM UTILITIES
+// ============================================================
+// Coercion functions shared between useBDOForm and useActivityForm.
+
+import type {
+  UseFormReturn,
+  Control,
+  Path,
+  FieldValues,
+} from 'react-hook-form';
+import type { MutableRefObject } from 'react';
+import type { BaseField } from '../../../bdo/fields/BaseField';
+
+/** Coerce form value to match field's expected type (HTML inputs return strings) */
+export function coerceFieldValue(
+  field: BaseField<unknown>,
+  value: unknown,
+): unknown {
+  const type = field.meta.Type;
+  if (typeof value === 'string' && type === 'Number') {
+    return value === '' ? undefined : Number(value);
+  }
+  // Date/DateTime: empty string → undefined (don't send to backend)
+  if (
+    typeof value === 'string' &&
+    value === '' &&
+    (type === 'Date' || type === 'DateTime')
+  ) {
+    return undefined;
+  }
+  // DateTime: normalize to HH:MM:SS and ensure Z suffix for API request format
+  if (typeof value === 'string' && value !== '' && type === 'DateTime') {
+    let normalized = value;
+    if (normalized.endsWith('Z')) normalized = normalized.slice(0, -1);
+    // HTML datetime-local may omit seconds (e.g. "2026-02-18T15:12")
+    const timePart = normalized.split('T')[1] || '';
+    if ((timePart.match(/:/g) || []).length === 1) {
+      normalized += ':00';
+    }
+    return normalized + 'Z';
+  }
+  return value;
+}
+
+/**
+ * Strip trailing Z from DateTime response values for HTML datetime-local inputs.
+ * Takes a fields map (use bdo.getFields() for BDO forms).
+ */
+export function coerceRecordForForm(
+  fields: Record<string, BaseField<unknown>>,
+  data: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...data };
+  for (const [key, value] of Object.entries(result)) {
+    if (
+      typeof value === 'string' &&
+      fields[key]?.meta.Type === 'DateTime' &&
+      value.endsWith('Z')
+    ) {
+      result[key] = value.slice(0, -1);
+    }
+  }
+  return result;
+}
+
+// ============================================================
+// SYNC UTILITIES
+// ============================================================
+// Shared per-field sync pattern used by useBDOForm and useActivityForm.
+//   createSyncField         → validate → coerce → API call → reset dirty → update readonly
+//   createEnhancedRegister  → inject syncField into register's onBlur/onChange
+//   createEnhancedControl   → inject syncField into Controller's control.register
+
+/** API function signature for per-field sync */
+export type SyncApiFnType = (
+  fieldName: string,
+  value: unknown,
+) => Promise<unknown>;
+
+export interface CreateSyncFieldOptionsType {
+  apiFn: SyncApiFnType;
+  allFields: Record<string, BaseField<unknown>>;
+  readonlyFieldNames: string[];
+  rhf: UseFormReturn;
+  isComputingRef: MutableRefObject<boolean>;
+}
+
+/**
+ * Factory that returns a `syncField(fieldName)` function.
+ * Validates the field, coerces its value, sends it to the API,
+ * resets dirty state, and updates computed/readonly fields from the response.
+ */
+export function createSyncField(
+  opts: CreateSyncFieldOptionsType,
+): (fieldName: string) => Promise<void> {
+  const { apiFn, allFields, readonlyFieldNames, rhf, isComputingRef } = opts;
+
+  return async (fieldName: string) => {
+    if (isComputingRef.current) return;
+    isComputingRef.current = true;
+
+    try {
+      const isValid = await rhf.trigger(fieldName as Path<FieldValues>);
+      if (!isValid) return;
+
+      const rawValue = rhf.getValues(fieldName as any);
+      const field = allFields[fieldName];
+      const value = field ? coerceFieldValue(field, rawValue) : rawValue;
+
+      const response = await apiFn(fieldName, value);
+
+      // If apiFn chose not to sync (e.g. draft not ready), skip cleanup
+      if (response === undefined) return;
+
+      // Field saved — reset dirty state so it's not re-sent on submit
+      rhf.resetField(fieldName as Path<FieldValues>, {
+        defaultValue: rawValue,
+        keepTouched: true,
+        keepError: true,
+      } as any);
+
+      // Update computed/readonly fields from response
+      if (response && typeof response === 'object') {
+        const responseData =
+          (response as any).Data ?? (response as any);
+        if (responseData && typeof responseData === 'object') {
+          const readonlySet = new Set(readonlyFieldNames);
+          for (const key of Object.keys(responseData)) {
+            if (readonlySet.has(key) && responseData[key] !== undefined) {
+              const current = rhf.getValues(key as any);
+              if (current !== responseData[key]) {
+                rhf.setValue(
+                  key as Path<FieldValues>,
+                  responseData[key] as any,
+                  { shouldDirty: false, shouldValidate: false },
+                );
+              }
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.warn('syncField failed:', error);
+    } finally {
+      isComputingRef.current = false;
+    }
+  };
+}
+
+export interface CreateEnhancedRegisterOptionsType {
+  rhf: UseFormReturn;
+  allFields: Record<string, BaseField<unknown>>;
+  syncField: (fieldName: string) => Promise<void>;
+  syncOnBlur: boolean;
+  syncOnChange: boolean;
+}
+
+/**
+ * Factory that returns an enhanced `register` function.
+ * Injects syncField into onBlur/onChange based on mode, and auto-disables readonly fields.
+ */
+export function createEnhancedRegister(
+  opts: CreateEnhancedRegisterOptionsType,
+) {
+  const { rhf, allFields, syncField, syncOnBlur, syncOnChange } = opts;
+
+  return (name: string, registerOptions?: any) => {
+    const field = allFields[name];
+    const isReadonly = field ? field.readOnly : false;
+
+    const result = rhf.register(name as Path<FieldValues>, {
+      ...registerOptions,
+      ...(syncOnBlur
+        ? {
+            onBlur: async (e: any) => {
+              await registerOptions?.onBlur?.(e);
+              await syncField(name);
+            },
+          }
+        : {}),
+      ...(syncOnChange
+        ? {
+            onChange: async (e: any) => {
+              await registerOptions?.onChange?.(e);
+              await syncField(name);
+            },
+          }
+        : {}),
+      ...(isReadonly ? { disabled: true } : {}),
+    });
+
+    if (isReadonly) {
+      return { ...result, disabled: true as const };
+    }
+
+    return result;
+  };
+}
+
+export interface CreateEnhancedControlOptionsType {
+  control: Control;
+  syncField: (fieldName: string) => Promise<void>;
+  syncOnBlur: boolean;
+  syncOnChange: boolean;
+}
+
+/**
+ * Factory that returns a Proxy over RHF's `control` object.
+ * Intercepts `control.register` to inject syncField into onChange/onBlur
+ * for Controller components.
+ */
+export function createEnhancedControl(
+  opts: CreateEnhancedControlOptionsType,
+): Control {
+  const { control, syncField, syncOnBlur, syncOnChange } = opts;
+
+  return new Proxy(control, {
+    get(target, prop, receiver) {
+      if (prop === 'register') {
+        return (name: string, options?: any) => {
+          const result = target.register(name as any, options);
+          const originalOnChange = result.onChange;
+          const originalOnBlur = result.onBlur;
+
+          return {
+            ...result,
+            ...(syncOnChange
+              ? {
+                  onChange: async (event: any) => {
+                    await originalOnChange(event);
+                    await syncField(name);
+                  },
+                }
+              : {}),
+            ...(syncOnBlur
+              ? {
+                  onBlur: async (event: any) => {
+                    await originalOnBlur(event);
+                    await syncField(name);
+                  },
+                }
+              : {}),
+          };
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}

package/sdk/components/hooks/{useForm → useBDOForm}/types.ts

@@ -33,7 +33,7 @@ export type AllFieldsType<B> = ExtractEditableType<B> & ExtractReadonlyType<B> &
 // BDO CAPABILITY CONSTRAINTS
 // ============================================================
 
-/** Minimum BDO shape required for any useForm usage */
+/** Minimum BDO shape required for any useBDOForm usage */
 interface BaseBdoShape {
   readonly meta: BdoMetaType;
   getFields(): Record<string, BaseField<unknown>>;
@@ -81,13 +81,13 @@ export type HandleSubmitType<TRead = unknown> = (
 // OPTIONS TYPE
 // ============================================================
 
-export type UseFormOptionsType<B extends BaseBdo<any, any, any>> =
-  | UseFormCreateOptionsType<B>
-  | UseFormUpdateOptionsType<B>
-  | UseFormAutoOptionsType<B>;
+export type UseBDOFormOptionsType<B extends BaseBdo<any, any, any>> =
+  | UseBDOFormCreateOptionsType<B>
+  | UseBDOFormUpdateOptionsType<B>
+  | UseBDOFormAutoOptionsType<B>;
 
 /** Options when operation is explicitly "create" — BDO must have create() */
-interface UseFormCreateOptionsType<B extends BaseBdo<any, any, any>> {
+interface UseBDOFormCreateOptionsType<B extends BaseBdo<any, any, any>> {
   bdo: B & CreatableBdo<ExtractEditableType<B>>;
   operation: "create";
   recordId?: undefined;
@@ -99,7 +99,7 @@ interface UseFormCreateOptionsType<B extends BaseBdo<any, any, any>> {
 }
 
 /** Options when operation is explicitly "update" — BDO must have get() + update() */
-interface UseFormUpdateOptionsType<B extends BaseBdo<any, any, any>> {
+interface UseBDOFormUpdateOptionsType<B extends BaseBdo<any, any, any>> {
   bdo: B & UpdatableBdo<ExtractEditableType<B>>;
   operation: "update";
   recordId: string;
@@ -111,7 +111,7 @@ interface UseFormUpdateOptionsType<B extends BaseBdo<any, any, any>> {
 }
 
 /** Options when operation is auto-inferred — BDO must support both */
-interface UseFormAutoOptionsType<B extends BaseBdo<any, any, any>> {
+interface UseBDOFormAutoOptionsType<B extends BaseBdo<any, any, any>> {
   bdo: B & FormBdo<ExtractEditableType<B>>;
   operation?: undefined;
   recordId?: string;
@@ -187,7 +187,7 @@ export type FormItemType<
 // RETURN TYPE
 // ============================================================
 
-export interface UseFormReturnType<B extends BaseBdo<any, any, any>> {
+export interface UseBDOFormReturnType<B extends BaseBdo<any, any, any>> {
   // Item with typed accessors
   item: FormItemType<ExtractEditableType<B>, ExtractReadonlyType<B>>;
 

package/sdk/components/hooks/{useForm/useForm.ts → useBDOForm/useBDOForm.ts}

@@ -4,61 +4,30 @@ import {
   type FieldValues,
   type FieldErrors,
   type Control,
-  type RegisterOptions,
   type UseFormReturn as RHFUseFormReturn,
 } from "react-hook-form";
 import { useQuery } from "@tanstack/react-query";
 import { createResolver } from "./createResolver";
 import { createItemProxy } from "./createItemProxy";
+import {
+  coerceFieldValue,
+  coerceRecordForForm,
+  createSyncField,
+  createEnhancedRegister,
+  createEnhancedControl,
+} from "./shared";
 import { getBdoSchema } from "../../../api/metadata";
 import { api } from "../../../api/client";
 import type { BaseBdo } from "../../../bdo";
 import type { CreateUpdateResponseType } from "../../../types/common";
-import type { BaseField } from "../../../bdo/fields/BaseField";
 import type {
-  UseFormOptionsType,
-  UseFormReturnType,
+  UseBDOFormOptionsType,
+  UseBDOFormReturnType,
   HandleSubmitType,
   AllFieldsType,
   UpdatableBdo,
 } from "./types";
 
-/** Coerce form value to match field's expected type (HTML inputs return strings) */
-function coerceFieldValue(field: BaseField<unknown>, value: unknown): unknown {
-  const type = field.meta.Type;
-  if (typeof value === "string" && type === "Number") {
-    return value === "" ? undefined : Number(value);
-  }
-  // Date/DateTime: empty string → undefined (don't send to backend)
-  if (typeof value === "string" && value === "" && (type === "Date" || type === "DateTime")) {
-    return undefined;
-  }
-  // DateTime: normalize to HH:MM:SS and ensure Z suffix for API request format
-  if (typeof value === "string" && value !== "" && type === "DateTime") {
-    let normalized = value;
-    if (normalized.endsWith("Z")) normalized = normalized.slice(0, -1);
-    // HTML datetime-local may omit seconds (e.g. "2026-02-18T15:12")
-    const timePart = normalized.split("T")[1] || "";
-    if ((timePart.match(/:/g) || []).length === 1) {
-      normalized += ":00";
-    }
-    return normalized + "Z";
-  }
-  return value;
-}
-
-/** Strip trailing Z from DateTime response values for HTML datetime-local inputs */
-function coerceRecordForForm(bdo: BaseBdo<any, any, any>, data: Record<string, unknown>): Record<string, unknown> {
-  const fields = bdo.getFields();
-  const result = { ...data };
-  for (const [key, value] of Object.entries(result)) {
-    if (typeof value === "string" && fields[key]?.meta.Type === "DateTime" && value.endsWith("Z")) {
-      result[key] = value.slice(0, -1);
-    }
-  }
-  return result;
-}
-
 /**
  * A form hook that integrates with React Hook Form.
  *
@@ -71,11 +40,11 @@ function coerceRecordForForm(bdo: BaseBdo<any, any, any>, data: Record<string, u
  * - 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
- * - Draft auto-save: creates draft on form open, patches on field changes
+ * - Per-field sync: validates, sends to API, resets dirty, updates computed fields
  */
-export function useForm<B extends BaseBdo<any, any, any>>(
-  options: UseFormOptionsType<B>,
-): UseFormReturnType<B> {
+export function useBDOForm<B extends BaseBdo<any, any, any>>(
+  options: UseBDOFormOptionsType<B>,
+): UseBDOFormReturnType<B> {
   const {
     bdo,
     recordId,
@@ -112,7 +81,7 @@ export function useForm<B extends BaseBdo<any, any, any>>(
     queryKey: ["form-record", bdo.meta._id, recordId],
     queryFn: async () => {
       const item = await (bdo as unknown as UpdatableBdo).get(recordId!);
-      return coerceRecordForForm(bdo, item.toJSON() as Record<string, unknown>);
+      return coerceRecordForForm(bdo.getFields(), item.toJSON() as Record<string, unknown>);
     },
     enabled: operation === "update" && !!recordId,
     staleTime: 0,
@@ -199,66 +168,71 @@ export function useForm<B extends BaseBdo<any, any, any>>(
   );
 
   // ============================================================
-  // SMART REGISTER (auto-disables readonly fields)
+  // PER-FIELD SYNC (validate → API call → reset dirty → update computed)
   // ============================================================
 
   const fields = bdo.getFields();
+  const isComputingRef = useRef(false);
 
-  const smartRegister = useCallback(
-    (name: string, registerOptions?: RegisterOptions) => {
-      const rhfResult = form.register(name as any, registerOptions);
-      if (fields[name]?.readOnly) {
-        return { ...rhfResult, disabled: true };
-      }
-      return rhfResult;
-    },
-    [form, fields],
+  const readonlyFieldNames = useMemo<string[]>(
+    () => Object.keys(fields).filter((k) => fields[k].readOnly),
+    [fields],
   );
 
-  // ============================================================
-  // DRAFT AUTO-SAVE (Create Mode - patch dirty fields on change)
-  // ============================================================
-
-  const draftPatchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  useEffect(() => {
-    if (operation !== "create" || !draftData?._id) return;
-
-    const subscription = form.watch((_values, { type }) => {
-      if (type !== "change") return;
-
-      if (draftPatchTimeoutRef.current) {
-        clearTimeout(draftPatchTimeoutRef.current);
+  const syncApiFn = useCallback(
+    async (fieldName: string, value: unknown) => {
+      if (operation === "create" && draftData?._id) {
+        return api(bdo.meta._id).draftInteraction({
+          _id: draftData._id,
+          [fieldName]: value,
+        });
+      } else if (operation === "update" && recordId) {
+        return api(bdo.meta._id).update(recordId, {
+          [fieldName]: value,
+        });
       }
+    },
+    [operation, draftData, recordId, bdo],
+  );
 
-      draftPatchTimeoutRef.current = setTimeout(async () => {
-        const currentValues = form.getValues();
-        const dirtyFields = form.formState.dirtyFields;
-        const dirtyData: Record<string, unknown> = {};
+  const syncField = useMemo(
+    () =>
+      createSyncField({
+        apiFn: syncApiFn,
+        allFields: fields,
+        readonlyFieldNames,
+        rhf: form,
+        isComputingRef,
+      }),
+    [syncApiFn, fields, readonlyFieldNames, form],
+  );
 
-        for (const [key, value] of Object.entries(currentValues)) {
-          if (fields[key] && !fields[key].readOnly && dirtyFields[key]) {
-            dirtyData[key] = coerceFieldValue(fields[key], value);
-          }
-        }
+  const syncOnChange = mode === "onChange" || mode === "all";
+  const syncOnBlur =
+    mode === "onBlur" || mode === "onTouched" || mode === "all";
+
+  const smartRegister = useMemo(
+    () =>
+      createEnhancedRegister({
+        rhf: form,
+        allFields: fields,
+        syncField,
+        syncOnBlur,
+        syncOnChange,
+      }),
+    [form, fields, syncField, syncOnBlur, syncOnChange],
+  );
 
-        if (Object.keys(dirtyData).length > 0) {
-          try {
-            await api(bdo.meta._id).draftInteraction({ _id: draftData._id, ...dirtyData });
-          } catch {
-            // Draft auto-save is best-effort — don't block user interaction
-          }
-        }
-      }, 800);
-    });
-
-    return () => {
-      subscription.unsubscribe();
-      if (draftPatchTimeoutRef.current) {
-        clearTimeout(draftPatchTimeoutRef.current);
-      }
-    };
-  }, [form, operation, draftData, fields, bdo]);
+  const enhancedControl = useMemo(
+    () =>
+      createEnhancedControl({
+        control: form.control,
+        syncField,
+        syncOnBlur,
+        syncOnChange,
+      }),
+    [form.control, syncField, syncOnBlur, syncOnChange],
+  );
 
   // ============================================================
   // CUSTOM HANDLE SUBMIT (with API call + payload filtering)
@@ -332,7 +306,7 @@ export function useForm<B extends BaseBdo<any, any, any>>(
     getValues: form.getValues as any,
     reset: form.reset as any,
     trigger: form.trigger as any,
-    control: form.control as unknown as Control<AllFieldsType<B>>,
+    control: enhancedControl as unknown as Control<AllFieldsType<B>>,
     formState: form.formState as any,
 
     errors: form.formState.errors as any,

package/sdk/components/hooks/useBDOTable/index.ts

@@ -0,0 +1,2 @@
+export { useBDOTable } from './useBDOTable';
+export type { UseBDOTableOptionsType, UseBDOTableReturnType } from './types';

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

@@ -0,0 +1,22 @@
+import type { UseTableReturnType, PaginationStateType } from '../useTable/types';
+import type { UseFilterOptionsType } from '../useFilter/types';
+import type { SortType } from '../../../types/common';
+
+export interface UseBDOTableOptionsType<T> {
+  /** BDO instance — only meta._id is used (for API routing) */
+  bdo: {
+    meta: { readonly _id: string; readonly name: string };
+  };
+  /** Initial state */
+  initialState?: {
+    sort?: SortType;
+    pagination?: PaginationStateType;
+    filter?: UseFilterOptionsType<T>;
+  };
+  /** Error callback */
+  onError?: (error: Error) => void;
+  /** Success callback — receives rows from current page */
+  onSuccess?: (data: T[]) => void;
+}
+
+export type UseBDOTableReturnType<T> = UseTableReturnType<T>;

package/sdk/components/hooks/useBDOTable/useBDOTable.ts

@@ -0,0 +1,16 @@
+import { api } from '../../../api/client';
+import { useTable } from '../useTable';
+import type { UseBDOTableOptionsType, UseBDOTableReturnType } from './types';
+
+export function useBDOTable<T = any>(
+  options: UseBDOTableOptionsType<T>,
+): UseBDOTableReturnType<T> {
+  const { bdo, ...rest } = options;
+
+  return useTable<T>({
+    queryKey: ['table', bdo.meta._id],
+    listFn: (opts) => api<T>(bdo.meta._id).list(opts),
+    countFn: (opts) => api<T>(bdo.meta._id).count(opts),
+    ...rest,
+  });
+}

package/sdk/components/hooks/useTable/index.ts

@@ -1,9 +1,9 @@
 // Main hook
-export { useTable } from "./useTable";
+export { useTable } from './useTable';
 
 // Types
 export type {
-  ColumnDefinitionType,
   UseTableOptionsType,
   UseTableReturnType,
-} from "./types";
+  PaginationStateType,
+} from './types';

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

@@ -1,8 +1,10 @@
-import type { ListResponseType, SortType, ColumnDefinitionType } from "../../../types/common";
-
-// Re-export ColumnDefinitionType for backwards compatibility
-export type { ColumnDefinitionType };
-import type { UseFilterReturnType, UseFilterOptionsType } from "../useFilter";
+import type {
+  ListResponseType,
+  ListOptionsType,
+  CountResponseType,
+  SortType,
+} from '../../../types/common';
+import type { UseFilterReturnType, UseFilterOptionsType } from '../useFilter';
 
 // ============================================================
 // STATE TYPE DEFINITIONS
@@ -23,10 +25,12 @@ export interface PaginationStateType {
 // ============================================================
 
 export interface UseTableOptionsType<T> {
-  /** Data source identifier */
-  source: string;
-  /** Column configurations */
-  columns: ColumnDefinitionType<T>[];
+  /** Unique query key for React Query caching */
+  queryKey: string[];
+  /** Fetch list data (POST with filter/sort/pagination) */
+  listFn: (options: ListOptionsType) => Promise<ListResponseType<T>>;
+  /** Fetch count (POST with filter only) */
+  countFn: (options: ListOptionsType) => Promise<CountResponseType>;
   /** Initial state */
   initialState?: {
     /** Sort configuration: [{ "fieldName": "ASC" }] */
@@ -38,7 +42,7 @@ export interface UseTableOptionsType<T> {
   };
   /** Error callback */
   onError?: (error: Error) => void;
-  /** Success callback */
+  /** Success callback — receives rows from current page */
   onSuccess?: (data: T[]) => void;
 }
 
@@ -65,10 +69,10 @@ export interface UseTableReturnType<T> {
   // Sorting (Flat Access)
   sort: {
     field: keyof T | null;
-    direction: "ASC" | "DESC" | null;
+    direction: 'ASC' | 'DESC' | null;
     toggle: (field: keyof T) => void;
     clear: () => void;
-    set: (field: keyof T, direction: "ASC" | "DESC") => void;
+    set: (field: keyof T | null, direction: 'ASC' | 'DESC' | null) => void;
   };
 
   // Filter (Simplified chainable API)