@ram_28/kf-ai-sdk 2.0.14 → 2.0.15

package/sdk/components/hooks/index.ts

@@ -1,10 +1,33 @@
-// Table hook
-export { useTable } from "./useTable";
+// Table hook (base)
+export { useTable } from './useTable';
 export type {
   UseTableOptionsType,
   UseTableReturnType,
-  ColumnDefinitionType,
-} from "./useTable";
+  PaginationStateType,
+} from './useTable';
+
+// BDO table hook
+export { useBDOTable } from './useBDOTable';
+export type {
+  UseBDOTableOptionsType,
+  UseBDOTableReturnType,
+} from './useBDOTable';
+
+// Activity table hook
+export { useActivityTable, ActivityTableStatus } from './useActivityTable';
+export type {
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityTableStatusType,
+  ActivityRowType,
+} from './useActivityTable';
+
+// Activity form hook
+export { useActivityForm } from './useActivityForm';
+export type {
+  UseActivityFormOptions,
+  UseActivityFormReturn,
+} from './useActivityForm';
 
 // Filter hook
-export * from "./useFilter";
+export * from './useFilter';

package/sdk/components/hooks/useActivityForm/createActivityItemProxy.ts

@@ -0,0 +1,400 @@
+// ============================================================
+// ACTIVITY ITEM PROXY
+// ============================================================
+// Proxy-based item that delegates to RHF for state management.
+// Follows the same pattern as createItemProxy for BaseBdo,
+// adapted for Activity. Attachment methods call
+// createResourceClient() directly (matching BDO's api() pattern).
+
+import type { UseFormReturn, Path, FieldValues } from 'react-hook-form';
+import type { BaseFieldMetaType } from '../../../bdo/core/types';
+import type { BaseField } from '../../../bdo/fields/BaseField';
+import type { FileType } from '../../../types/base-fields';
+import type {
+  FileDownloadResponseType,
+  AttachmentViewType,
+} from '../../../types/common';
+import type {
+  FormItemType,
+  EditableFormFieldAccessorType,
+  ReadonlyFormFieldAccessorType,
+} from '../useForm/types';
+import type { Activity } from '../../../workflow/Activity';
+import type {
+  ExtractActivityEditable,
+  ExtractActivityReadonly,
+} from './types';
+import { createResourceClient } from '../../../api/client';
+import {
+  validateFileExtension,
+  extractFileExtension,
+} from '../../../bdo/fields/attachment-constants';
+
+/**
+ * Creates a Proxy-based Item that delegates to RHF for state management.
+ *
+ * Key principle: Item has NO state. It's a view over RHF's state.
+ * Editable fields get set(), readonly fields do not.
+ *
+ * Activity forms always have an instance ID (no draft creation needed),
+ * so attachment operations use the provided instanceId directly.
+ *
+ * @param activity - The Activity instance for field metadata
+ * @param form - The RHF useForm return object
+ * @param instanceId - The activity instance ID
+ * @returns FormItemType proxy
+ */
+export function createActivityItemProxy<A extends Activity<any, any, any>>(
+  activity: A,
+  form: UseFormReturn<FieldValues>,
+  instanceId: string,
+): FormItemType<ExtractActivityEditable<A>, ExtractActivityReadonly<A>> {
+  const fields = activity._getFields();
+  const accessorCache = new Map<
+    string,
+    | EditableFormFieldAccessorType<unknown>
+    | ReadonlyFormFieldAccessorType<unknown>
+  >();
+
+  // Resource client for attachment operations — same pattern as BDO's api(boId)
+  const activityBasePath = `/api/app/process/${activity.meta.businessProcessId}/${activity.meta.activityId}`;
+  const activityApi = createResourceClient(activityBasePath);
+
+  /**
+   * Defensive helper — throws if no instance ID is available.
+   * Activity forms always have an instance, so this is a safety net.
+   */
+  function requireInstanceId(): string {
+    if (!instanceId) {
+      throw new Error(
+        'Cannot perform attachment operation: no activity instance ID',
+      );
+    }
+    return instanceId;
+  }
+
+  return new Proxy(
+    {} as FormItemType<ExtractActivityEditable<A>, ExtractActivityReadonly<A>>,
+    {
+      get(_, prop: string | symbol) {
+        // Handle symbol properties (e.g., Symbol.toStringTag)
+        if (typeof prop === 'symbol') {
+          return undefined;
+        }
+
+        // Direct _id access (not an accessor, just the value)
+        if (prop === '_id') {
+          return instanceId;
+        }
+
+        // toJSON returns all form values as plain object
+        if (prop === 'toJSON') {
+          return () => form.getValues();
+        }
+
+        // validate triggers RHF validation for all fields
+        if (prop === 'validate') {
+          return () => form.trigger();
+        }
+
+        // Return cached accessor if available
+        if (accessorCache.has(prop)) {
+          return accessorCache.get(prop);
+        }
+
+        // Field accessor
+        const bdoField = fields[prop] as BaseField<unknown> | undefined;
+        const fieldMeta: BaseFieldMetaType = bdoField?.meta ?? {
+          _id: prop,
+          Name: prop,
+          Type: 'String',
+        };
+        const isReadOnly = bdoField?.readOnly ?? false;
+
+        // Base validate function
+        const validate = () => {
+          if (bdoField) {
+            return bdoField.validate(
+              form.getValues(prop as Path<FieldValues>),
+            );
+          }
+          return { valid: true, errors: [] };
+        };
+
+        // Shared getOrDefault helper
+        const getOrDefault = (fallback: unknown) => {
+          const value = form.getValues(prop as Path<FieldValues>);
+          return value !== undefined && value !== null ? value : fallback;
+        };
+
+        // Only add set() for editable fields
+        if (!isReadOnly) {
+          // Defensive get(): File fields return [] instead of null/undefined
+          const fieldGet = () => {
+            const val = form.getValues(prop as Path<FieldValues>);
+            if (fieldMeta.Type === 'File') return val ?? [];
+            return val;
+          };
+
+          const accessor: EditableFormFieldAccessorType<unknown> = {
+            label: bdoField?.label ?? prop,
+            required: bdoField?.required ?? false,
+            readOnly: false,
+            defaultValue: bdoField?.defaultValue,
+            meta: fieldMeta,
+            get: fieldGet,
+            getOrDefault,
+            set: (value: unknown) => {
+              form.setValue(prop as Path<FieldValues>, value as any, {
+                shouldDirty: true,
+                shouldTouch: true,
+                shouldValidate: false,
+              });
+            },
+            validate,
+          };
+
+          // Enrich Image/File field accessors with attachment methods
+          if (fieldMeta.Type === 'Image' || fieldMeta.Type === 'File') {
+            if (fieldMeta.Type === 'Image') {
+              // Image: single file upload
+              (accessor as any).upload = async (
+                file: File,
+              ): Promise<FileType> => {
+                validateFileExtension(file.name, 'Image');
+                const id = requireInstanceId();
+
+                const [uploadInfo] = await activityApi.getUploadUrl(
+                  id,
+                  prop,
+                  [
+                    {
+                      FileName: file.name,
+                      Size: file.size,
+                      FileExtension: extractFileExtension(file.name),
+                    },
+                  ],
+                );
+                await fetch(uploadInfo.UploadUrl.URL, {
+                  method: 'PUT',
+                  headers: { 'Content-Type': uploadInfo.ContentType },
+                  body: file,
+                });
+                const metadata: FileType = {
+                  _id: uploadInfo._id,
+                  _name: uploadInfo._name,
+                  FileName: uploadInfo.FileName,
+                  FileExtension: uploadInfo.FileExtension,
+                  Size: uploadInfo.Size,
+                  ContentType: uploadInfo.ContentType,
+                };
+                form.setValue(prop as Path<FieldValues>, metadata as any, {
+                  shouldDirty: true,
+                });
+                return metadata;
+              };
+
+              (accessor as any).deleteAttachment =
+                async (): Promise<void> => {
+                  const val = form.getValues(
+                    prop as Path<FieldValues>,
+                  ) as any;
+                  const id = requireInstanceId();
+                  if (!val?._id)
+                    throw new Error(`${prop} has no image to delete`);
+                  await activityApi.deleteAttachment(id, prop, val._id);
+                  form.setValue(prop as Path<FieldValues>, null as any, {
+                    shouldDirty: true,
+                  });
+                };
+
+              (accessor as any).getDownloadUrl = async (
+                viewType?: AttachmentViewType,
+              ): Promise<FileDownloadResponseType> => {
+                const val = form.getValues(
+                  prop as Path<FieldValues>,
+                ) as any;
+                const id = requireInstanceId();
+                if (!val?._id)
+                  throw new Error(`${prop} has no image`);
+                return activityApi.getDownloadUrl(
+                  id,
+                  prop,
+                  val._id,
+                  viewType,
+                );
+              };
+            } else {
+              // File field — multi-file
+              (accessor as any).upload = async (
+                files: File[],
+              ): Promise<FileType[]> => {
+                for (const file of files)
+                  validateFileExtension(file.name, 'File');
+                const id = requireInstanceId();
+
+                const requests = files.map((file) => ({
+                  FileName: file.name,
+                  Size: file.size,
+                  FileExtension: extractFileExtension(file.name),
+                }));
+                const uploadInfos = await activityApi.getUploadUrl(
+                  id,
+                  prop,
+                  requests,
+                );
+                const uploaded: FileType[] = await Promise.all(
+                  files.map(async (file, i) => {
+                    await fetch(uploadInfos[i].UploadUrl.URL, {
+                      method: 'PUT',
+                      headers: {
+                        'Content-Type': uploadInfos[i].ContentType,
+                      },
+                      body: file,
+                    });
+                    return {
+                      _id: uploadInfos[i]._id,
+                      _name: uploadInfos[i]._name,
+                      FileName: uploadInfos[i].FileName,
+                      FileExtension: uploadInfos[i].FileExtension,
+                      Size: uploadInfos[i].Size,
+                      ContentType: uploadInfos[i].ContentType,
+                    };
+                  }),
+                );
+                const current =
+                  (form.getValues(prop as Path<FieldValues>) as
+                    | FileType[]
+                    | undefined) ?? [];
+                form.setValue(
+                  prop as Path<FieldValues>,
+                  [...current, ...uploaded] as any,
+                  { shouldDirty: true },
+                );
+                return uploaded;
+              };
+
+              (accessor as any).deleteAttachment = async (
+                attachmentId: string,
+              ): Promise<void> => {
+                const current =
+                  (form.getValues(prop as Path<FieldValues>) as any[]) ?? [];
+                const id = requireInstanceId();
+                await activityApi.deleteAttachment(id, prop, attachmentId);
+                form.setValue(
+                  prop as Path<FieldValues>,
+                  current.filter((f) => f._id !== attachmentId) as any,
+                  { shouldDirty: true },
+                );
+              };
+
+              (accessor as any).getDownloadUrl = async (
+                attachmentId: string,
+                viewType?: AttachmentViewType,
+              ): Promise<FileDownloadResponseType> => {
+                const id = requireInstanceId();
+                return activityApi.getDownloadUrl(
+                  id,
+                  prop,
+                  attachmentId,
+                  viewType,
+                );
+              };
+
+              (accessor as any).getDownloadUrls = async (
+                viewType?: AttachmentViewType,
+              ): Promise<FileDownloadResponseType[]> => {
+                const id = requireInstanceId();
+                return activityApi.getDownloadUrls(id, prop, viewType);
+              };
+            }
+          }
+
+          accessorCache.set(prop, accessor);
+          return accessor;
+        }
+
+        // Defensive get() for readonly accessor too
+        const readonlyGet = () => {
+          const val = form.getValues(prop as Path<FieldValues>);
+          if (fieldMeta.Type === 'File') return val ?? [];
+          return val;
+        };
+
+        const accessor: ReadonlyFormFieldAccessorType<unknown> = {
+          label: bdoField?.label ?? prop,
+          required: bdoField?.required ?? false,
+          readOnly: true,
+          defaultValue: bdoField?.defaultValue,
+          meta: fieldMeta,
+          get: readonlyGet,
+          getOrDefault,
+          validate,
+        };
+
+        // Enrich readonly Image/File field accessors with download methods
+        if (fieldMeta.Type === 'Image' || fieldMeta.Type === 'File') {
+          if (fieldMeta.Type === 'Image') {
+            (accessor as any).getDownloadUrl = async (
+              viewType?: AttachmentViewType,
+            ): Promise<FileDownloadResponseType> => {
+              const val = form.getValues(
+                prop as Path<FieldValues>,
+              ) as any;
+              const id = requireInstanceId();
+              if (!val?._id)
+                throw new Error(`${prop} has no image to download`);
+              return activityApi.getDownloadUrl(
+                id,
+                prop,
+                val._id,
+                viewType,
+              );
+            };
+          } else {
+            (accessor as any).getDownloadUrl = async (
+              attachmentId: string,
+              viewType?: AttachmentViewType,
+            ): Promise<FileDownloadResponseType> => {
+              const id = requireInstanceId();
+              return activityApi.getDownloadUrl(
+                id,
+                prop,
+                attachmentId,
+                viewType,
+              );
+            };
+            (accessor as any).getDownloadUrls = async (
+              viewType?: AttachmentViewType,
+            ): Promise<FileDownloadResponseType[]> => {
+              const id = requireInstanceId();
+              return activityApi.getDownloadUrls(id, prop, viewType);
+            };
+          }
+        }
+
+        accessorCache.set(prop, accessor);
+        return accessor;
+      },
+
+      has(_, prop) {
+        if (typeof prop === 'symbol') return false;
+        if (prop === '_id' || prop === 'toJSON' || prop === 'validate')
+          return true;
+        return prop in fields;
+      },
+
+      ownKeys(_) {
+        return [...Object.keys(fields), '_id', 'toJSON', 'validate'];
+      },
+
+      getOwnPropertyDescriptor(_, prop) {
+        if (typeof prop === 'symbol') return undefined;
+        return {
+          configurable: true,
+          enumerable: prop !== 'toJSON' && prop !== 'validate',
+        };
+      },
+    },
+  );
+}

package/sdk/components/hooks/useActivityForm/createActivityResolver.ts

@@ -0,0 +1,87 @@
+// ============================================================
+// ACTIVITY RESOLVER
+// ============================================================
+// RHF resolver for Activity field validation.
+// Accepts either an Activity instance or a fields map (for
+// metadata-driven forms). Validates using BaseField.validate()
+// plus constraint validation (required, length, number precision).
+
+import type { FieldValues } from 'react-hook-form';
+import type { Activity } from '../../../workflow/Activity';
+import type { BaseField } from '../../../bdo/fields/BaseField';
+import type { ValidationResultType } from '../../../bdo/core/types';
+import { validateConstraints } from '../useForm/createResolver';
+
+/**
+ * Creates a React Hook Form resolver for Activity field validation.
+ *
+ * Validates only editable fields using BaseField.validate() + constraint checks.
+ * Readonly fields (readOnly: true) are skipped.
+ *
+ * @param activityOrFields - An Activity instance or a Record of field name to BaseField
+ * @returns RHF Resolver function
+ */
+export function createActivityResolver<A extends Activity<any, any, any>>(
+  activityOrFields: A | Record<string, BaseField<unknown>>,
+) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return async (values: FieldValues, _context: any, options: any) => {
+    const errors: Record<string, { type: string; message: string }> = {};
+
+    // Accept either an Activity instance or a raw fields map
+    const fields: Record<string, BaseField<unknown>> =
+      '_getFields' in activityOrFields
+        ? (activityOrFields as A)._getFields()
+        : activityOrFields;
+
+    // If validating specific fields (blur/change), only validate those
+    // If validating all (submit), options.names is undefined
+    const fieldsToValidate = options?.names ?? Object.keys(fields);
+
+    for (const fieldName of fieldsToValidate) {
+      const field = fields[fieldName];
+      if (!field) continue;
+
+      // Skip validation for readonly fields
+      if (field.readOnly) continue;
+
+      let value = values[fieldName];
+
+      // Coerce string values from HTML inputs to the expected type
+      if (typeof value === 'string' && field.meta.Type === 'Number') {
+        value = value === '' ? undefined : Number(value);
+      }
+
+      // 1. Type validation
+      const typeResult: ValidationResultType = (
+        field as BaseField<unknown>
+      ).validate(value);
+
+      if (!typeResult.valid && typeResult.errors.length > 0) {
+        errors[fieldName] = {
+          type: 'validate',
+          message: typeResult.errors[0] || `${fieldName} is invalid`,
+        };
+        continue;
+      }
+
+      // 2. Constraint validation (required, length, number precision)
+      const constraintResult = validateConstraints(
+        field as BaseField<unknown>,
+        value,
+      );
+      if (!constraintResult.valid && constraintResult.errors.length > 0) {
+        errors[fieldName] = {
+          type: 'constraint',
+          message: constraintResult.errors[0],
+        };
+      }
+    }
+
+    // Return format for RHF resolver
+    if (Object.keys(errors).length === 0) {
+      return { values, errors: {} };
+    }
+    return { values: {}, errors };
+  };
+}

package/sdk/{workflow/components → components/hooks}/useActivityForm/types.ts

@@ -12,9 +12,9 @@ import type {
   UseFormTrigger,
   Control,
   FieldErrors,
-} from "react-hook-form";
+} from 'react-hook-form';
 
-import type { Activity } from "../../Activity";
+import type { Activity } from '../../../workflow/Activity';
 
 // Reuse shared types from useForm — identical interfaces, no duplication
 import type {
@@ -23,7 +23,7 @@ import type {
   FormRegisterType,
   EditableFormFieldAccessorType,
   ReadonlyFormFieldAccessorType,
-} from "../../../components/hooks/useForm/types";
+} from '../useForm/types';
 
 // Re-export for consumers who import from this module
 export type {
@@ -75,7 +75,7 @@ export interface UseActivityFormOptions<A extends Activity<any, any, any>> {
    * Validation mode — controls when validation runs
    * @default "onBlur"
    */
-  mode?: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
+  mode?: 'onBlur' | 'onChange' | 'onSubmit' | 'onTouched' | 'all';
 
   /**
    * Whether to enable activity.read() on mount
@@ -99,12 +99,15 @@ export interface UseActivityFormReturn<A extends Activity<any, any, any>> {
   activity: A;
 
   /** Smart register with auto-disable for readonly fields */
-  register: FormRegisterType<ExtractActivityEditable<A>, ExtractActivityReadonly<A>>;
+  register: FormRegisterType<
+    ExtractActivityEditable<A>,
+    ExtractActivityReadonly<A>
+  >;
 
-  /** Handle form submission — calls activity.update() + activity.draftEnd() */
+  /** Handle form submission — calls activity.update() */
   handleSubmit: HandleSubmitType<AllActivityFields<A>>;
 
-  /** Handle form completion — calls activity.complete() */
+  /** Handle form completion — calls activity.update() + activity.complete() */
   handleComplete: HandleSubmitType<AllActivityFields<A>>;
 
   /** Watch field values */
@@ -148,15 +151,25 @@ export interface UseActivityFormReturn<A extends Activity<any, any, any>> {
   // LOADING STATES
   // ============================================================
 
-  /** True during activity.read() */
+  /** True during activity.read() or metadata fetch */
   isLoading: boolean;
 
+  /** True while BP metadata and context schemas are loading */
+  isMetadataLoading: boolean;
+
   /** Schema/data load error */
   loadError: Error | null;
 
   /** Any error active */
   hasError: boolean;
 
+  // ============================================================
+  // METADATA (optional — for consumers that need raw metadata)
+  // ============================================================
+
+  /** Raw BP metadata (BDOBlob) — available after metadata fetch completes */
+  bpMetadata: Record<string, unknown> | null;
+
   // ============================================================
   // OPERATIONS
   // ============================================================