@ram_28/kf-ai-sdk 2.0.15 → 2.0.16

package/docs/workflow.md

@@ -97,62 +97,12 @@ type ActivityInstanceFieldsType = {
 
 See the dedicated [useActivityTable documentation](./useActivityTable.md) for `ActivityTableStatus`, `ActivityRowType`, `UseActivityTableOptionsType`, and `UseActivityTableReturnType`.
 
-**Key change:** Entity fields are now nested under `ADO` instead of being flattened at the top level. Access entity fields as `row.ADO.FieldName`.
+Entity fields and system fields are flat at the top level, same as BDO tables. Access entity fields as `row.FieldName`.
 
 
-### UseActivityFormOptions\<A\>
+### UseActivityFormOptions\<A\> / UseActivityFormReturn\<A\>
 
-```typescript
-interface UseActivityFormOptions<A extends Activity<any, any, any>> {
-  /** Activity instance identifier (from wf.start() or getInProgressList()) */
-  activity_instance_id: string;
-
-  /** Default form values */
-  defaultValues?: Partial<ExtractActivityEditable<A>>;
-
-  /** Validation mode (default: "onBlur") */
-  mode?: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
-
-  /** Whether to load activity data on mount (default: true) */
-  enabled?: boolean;
-}
-```
-
-### UseActivityFormReturn\<A\>
-
-```typescript
-interface UseActivityFormReturn<A extends Activity<any, any, any>> {
-  // Core
-  item: FormItemType<EditableFields, ReadonlyFields>;
-  activity: A;
-  register: FormRegisterType<EditableFields, ReadonlyFields>;
-  handleSubmit: HandleSubmitType;    // Save the activity form
-  handleComplete: HandleSubmitType;  // Complete the activity
-
-  // RHF methods
-  watch: UseFormWatch;
-  setValue: UseFormSetValue;
-  getValues: UseFormGetValues;
-  reset: UseFormReset;
-  trigger: UseFormTrigger;
-  control: Control;
-
-  // Form state
-  errors: FieldErrors;
-  isValid: boolean;
-  isDirty: boolean;
-  isSubmitting: boolean;
-  isSubmitSuccessful: boolean;
-
-  // Loading
-  isLoading: boolean;
-  loadError: Error | null;
-  hasError: boolean;
-
-  // Operations
-  clearErrors: () => void;
-}
-```
+See the dedicated [useActivityForm documentation](./useActivityForm.md) for the full type definitions.
 
 ### File & Image Types
 
@@ -303,22 +253,46 @@ for (const item of result.Data) {
 }
 ```
 
-### inProgressMetrics(options?)
+### inProgressCount(options?)
 
-Get count of in-progress activity instances. Returns `CountResponseType` (`{ Count: number }`).
+Get count of in-progress activity instances. Returns `number`.
 
 ```typescript
-const { Count } = await activity.inProgressMetrics();
-console.log('In-progress count:', Count);
+const count = await activity.inProgressCount();
+console.log('In-progress count:', count);
 ```
 
-### completedMetrics(options?)
+### completedCount(options?)
 
-Get count of completed activity instances. Returns `CountResponseType` (`{ Count: number }`).
+Get count of completed activity instances. Returns `number`.
 
 ```typescript
-const { Count } = await activity.completedMetrics();
-console.log('Completed count:', Count);
+const count = await activity.completedCount();
+console.log('Completed count:', count);
+```
+
+### inProgressMetric(options)
+
+Get aggregated metrics for in-progress activity instances. Accepts `Omit<MetricOptionsType, 'Type'>` for custom aggregations (Sum, Avg, Count, etc.). Returns `MetricResponseType` (`{ Data: Record<string, any>[] }`).
+
+```typescript
+const result = await activity.inProgressMetric({
+  GroupBy: ['Status'],
+  Metric: [{ Field: '_id', Type: 'Count' }],
+});
+console.log(result.Data);
+```
+
+### completedMetric(options)
+
+Get aggregated metrics for completed activity instances. Same signature as `inProgressMetric`.
+
+```typescript
+const result = await activity.completedMetric({
+  GroupBy: [],
+  Metric: [{ Field: 'LeaveDays', Type: 'Sum' }],
+});
+console.log('Total leave days:', result.Data[0]?.sum_LeaveDays);
 ```
 
 ### getInstance(instanceId)
@@ -351,65 +325,7 @@ const progress = await instance.progress();           // get progress (ActivityP
 
 ## useActivityForm Hook
 
-React hook for building forms bound to workflow activity input fields. Integrates with `react-hook-form`.
-
-### Options
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `activity_instance_id` | `string` | *required* | Activity instance ID (from `wf.start()` or `getInProgressList()`) |
-| `defaultValues` | `Partial<Editable>` | `{}` | Initial form values |
-| `mode` | `"onBlur" \| "onChange" \| "onSubmit" \| "onTouched" \| "all"` | `"onBlur"` | Validation timing |
-| `enabled` | `boolean` | `true` | Whether to load activity data on mount |
-
-### Lifecycle
-
-```
-Mount
-  |
-  |-> Load activity instance data -> populate form
-  |
-  v
-User edits field -> blurs
-  |
-  |-> Field validation (BaseField.validate)
-  |-> If valid + readonly fields exist -> update computed fields
-  |
-  v
-User clicks Save
-  |
-  |-> handleSubmit -> save activity data
-  |
-  v
-User clicks Complete
-  |
-  |-> handleComplete -> complete activity
-```
-
-### Return Value
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `item` | `FormItemType` | Proxy with typed field accessors (`.get()`, `.set()`, `.meta`) |
-| `activity` | `A` | The Activity instance |
-| `register` | `FormRegisterType` | Smart register (auto-disables readonly fields) |
-| `handleSubmit` | `HandleSubmitType` | Save activity data |
-| `handleComplete` | `HandleSubmitType` | Complete the activity |
-| `watch` | `UseFormWatch` | Watch field values |
-| `setValue` | `UseFormSetValue` | Set field value programmatically |
-| `getValues` | `UseFormGetValues` | Get current field values |
-| `reset` | `UseFormReset` | Reset form to default values |
-| `trigger` | `UseFormTrigger` | Trigger validation |
-| `control` | `Control` | RHF control (for Controller components) |
-| `errors` | `FieldErrors` | Validation errors |
-| `isValid` | `boolean` | Form is valid |
-| `isDirty` | `boolean` | Form has been modified |
-| `isSubmitting` | `boolean` | Currently submitting |
-| `isSubmitSuccessful` | `boolean` | Last submission succeeded |
-| `isLoading` | `boolean` | Loading activity data |
-| `loadError` | `Error \| null` | Load error |
-| `hasError` | `boolean` | Any error active |
-| `clearErrors` | `() => void` | Clear all form errors |
+See the dedicated [useActivityForm documentation](./useActivityForm.md) for the full API reference, type definitions, and examples.
 
 ---
 
@@ -417,7 +333,7 @@ User clicks Complete
 
 See the dedicated [useActivityTable documentation](./useActivityTable.md) for the full API reference, type definitions, and examples.
 
-`useActivityTable` now wraps the base `useTable` hook, providing the same search, sort, filter, and pagination capabilities as BDO tables. Entity fields are accessed via `row.ADO.FieldName`.
+`useActivityTable` provides search, sort, filter, and pagination capabilities, same as `useBDOTable`. Entity fields are accessed at the top level (e.g., `row.FieldName`).
 
 ---
 
@@ -439,115 +355,7 @@ const progress = await wf.progress(BPInstanceId);
 
 ### Step 2 — React component with useActivityForm
 
-```tsx
-import { useMemo } from "react";
-import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
-import type { UseActivityFormOptions } from "@ram_28/kf-ai-sdk/workflow";
-import type { FieldErrors } from "react-hook-form";
-import { SimpleLeaveProcess, EmployeeInputActivity } from "@/bdo/workflows/SimpleLeaveProcess";
-
-interface LeaveRequestFormProps {
-  activityInstanceId: string;
-  onComplete: () => void;
-}
-
-function LeaveRequestForm({ activityInstanceId, onComplete }: LeaveRequestFormProps) {
-  // 1. Get the typed activity from the workflow
-  const activity = useMemo(() => new SimpleLeaveProcess().employeeInputActivity(), []);
-
-  // 2. Hook options
-  const options: UseActivityFormOptions<EmployeeInputActivity> = {
-    activity_instance_id: activityInstanceId,
-    defaultValues: {
-      StartDate: undefined,
-      EndDate: undefined,
-      LeaveType: undefined,
-    },
-    mode: "onBlur",
-  };
-
-  // 3. Initialize hook
-  const {
-    register,
-    handleSubmit,
-    handleComplete,
-    item,
-    errors,
-    isLoading,
-    isSubmitting,
-    loadError,
-  } = useActivityForm(activity, options);
-
-  if (isLoading) return <div>Loading...</div>;
-  if (loadError) return <div>Error: {loadError.message}</div>;
-
-  // 4. Handlers
-  const onSaveSuccess = (): void => {
-    console.log("Saved!");
-  };
-
-  const onCompleteSuccess = (): void => {
-    console.log("Leave request submitted!");
-    onComplete();
-  };
-
-  const onError = (error: FieldErrors | Error): void => {
-    if (error instanceof Error) {
-      console.error("API Error:", error.message);
-    } else {
-      console.error("Validation errors:", error);
-    }
-  };
-
-  return (
-    <form>
-      <h2>Leave Request</h2>
-
-      {/* Start Date */}
-      <div>
-        <label>{activity.StartDate.label}</label>
-        <input type="date" {...register(activity.StartDate.id)} />
-        {errors.StartDate && <span>{errors.StartDate.message}</span>}
-      </div>
-
-      {/* End Date */}
-      <div>
-        <label>{activity.EndDate.label}</label>
-        <input type="date" {...register(activity.EndDate.id)} />
-        {errors.EndDate && <span>{errors.EndDate.message}</span>}
-      </div>
-
-      {/* Leave Type */}
-      <div>
-        <label>{activity.LeaveType.label}</label>
-        <select {...register(activity.LeaveType.id)}>
-          <option value="">Select type</option>
-          <option value="PTO">PTO</option>
-          <option value="Sick">Sick</option>
-          <option value="Parental">Parental</option>
-        </select>
-        {errors.LeaveType && <span>{errors.LeaveType.message}</span>}
-      </div>
-
-      {/* Leave Days (readonly — auto-disabled, computed by server) */}
-      <div>
-        <label>{activity.LeaveDays.label}</label>
-        <input type="number" {...register(activity.LeaveDays.id)} />
-      </div>
-
-      {/* Actions */}
-      <div>
-        <button type="button" onClick={handleSubmit(onSaveSuccess, onError)}>
-          {isSubmitting ? "Saving..." : "Save Draft"}
-        </button>
-        <button type="button" onClick={handleComplete(onCompleteSuccess, onError)}>
-          {isSubmitting ? "Submitting..." : "Submit Leave Request"}
-        </button>
-      </div>
-    </form>
-  );
-}
-```
+See [useActivityForm](./useActivityForm.md) for the full form component example.
 
 ### Full flow orchestration
 
@@ -592,7 +400,8 @@ import { SimpleLeaveProcess, ManagerApprovalActivity } from "@/bdo/workflows/Sim
 const wf = new SimpleLeaveProcess();
 const activity = wf.managerApprovalActivity();
 
-  const { rows, totalItems, isLoading, error, pagination, refetch } = useActivityTable(activity, {
+  const { rows, totalItems, isLoading, error, pagination, refetch } = useActivityTable({
+    activity,
     status: ActivityTableStatus.InProgress,
     initialState: {
       pagination: { pageNo: 1, pageSize: 10 },
@@ -634,8 +443,8 @@ const activity = wf.managerApprovalActivity();
               <td>{row._id}</td>
               <td>{row.Status}</td>
               <td>{row.AssignedTo.map((u) => u._name).join(", ")}</td>
-              <td>{row.ADO.ManagerApproved ? "Yes" : "No"}</td>
-              <td>{row.ADO.ManagerReason}</td>
+              <td>{row.ManagerApproved ? "Yes" : "No"}</td>
+              <td>{row.ManagerReason}</td>
               <td>
                 <button onClick={() => setSelectedId(row._id)}>Review</button>
               </td>
@@ -655,74 +464,7 @@ const activity = wf.managerApprovalActivity();
 
 ### Step 2 — Approval form component
 
-```tsx
-import { useMemo } from "react";
-import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
-import type { UseActivityFormOptions } from "@ram_28/kf-ai-sdk/workflow";
-import type { FieldErrors } from "react-hook-form";
-import { SimpleLeaveProcess, ManagerApprovalActivity } from "@/bdo/workflows/SimpleLeaveProcess";
-
-interface ApprovalFormProps {
-  activityInstanceId: string;
-  onComplete: () => void;
-}
-
-function ApprovalForm({ activityInstanceId, onComplete }: ApprovalFormProps) {
-  const activity = useMemo(() => new SimpleLeaveProcess().managerApprovalActivity(), []);
-
-  const options: UseActivityFormOptions<ManagerApprovalActivity> = {
-    activity_instance_id: activityInstanceId,
-    defaultValues: {
-      ManagerApproved: false,
-      ManagerReason: "",
-    },
-    mode: "onBlur",
-  };
-
-  const {
-    register,
-    handleComplete,
-    errors,
-    isLoading,
-    isSubmitting,
-    loadError,
-  } = useActivityForm(activity, options);
-
-  if (isLoading) return <div>Loading...</div>;
-  if (loadError) return <div>Error: {loadError.message}</div>;
-
-  const onSuccess = (): void => {
-    console.log("Approval submitted!");
-    onComplete();
-  };
-
-  const onError = (error: FieldErrors | Error): void => {
-    if (error instanceof Error) console.error("API Error:", error.message);
-  };
-
-  return (
-    <form>
-      <h2>Leave Approval</h2>
-
-      <div>
-        <label>
-          <input type="checkbox" {...register(activity.ManagerApproved.id)} />
-          {activity.ManagerApproved.label}
-        </label>
-      </div>
-
-      <div>
-        <label>{activity.ManagerReason.label}</label>
-        <textarea {...register(activity.ManagerReason.id)} rows={4} />
-      </div>
-
-      <button type="button" onClick={handleComplete(onSuccess, onError)}>
-        {isSubmitting ? "Submitting..." : "Submit Decision"}
-      </button>
-    </form>
-  );
-}
-```
+See [useActivityForm](./useActivityForm.md) for the full approval form component example.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "2.0.15",
+  "version": "2.0.16",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",
@@ -189,7 +189,7 @@
     "react",
     "hooks",
     "typescript",
-    "useForm",
+    "useBDOForm",
     "useTable",
     "useFilter",
     "bdo",

package/sdk/bdo/core/BaseBdo.ts

@@ -127,7 +127,7 @@ export abstract class BaseBdo<
   /**
    * Load backend metadata for expression-based validation
    *
-   * Called by useForm after fetching schema from the backend.
+   * Called by useBDOForm after fetching schema from the backend.
    * This enables expression-based validation rules to be used
    * in addition to type validation.
    *
@@ -241,7 +241,7 @@ export abstract class BaseBdo<
   }
 
   // ============================================================
-  // DRAFT OPERATIONS (for useForm integration)
+  // DRAFT OPERATIONS (for useBDOForm integration)
   // ============================================================
 
   /**

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

@@ -18,7 +18,7 @@ import type {
   FormItemType,
   EditableFormFieldAccessorType,
   ReadonlyFormFieldAccessorType,
-} from '../useForm/types';
+} from '../useBDOForm/types';
 import type { Activity } from '../../../workflow/Activity';
 import type {
   ExtractActivityEditable,

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

@@ -10,7 +10,7 @@ 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';
+import { validateConstraints } from '../useBDOForm/createResolver';
 
 /**
  * Creates a React Hook Form resolver for Activity field validation.

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

@@ -2,7 +2,7 @@
 // TYPE DEFINITIONS FOR useActivityForm HOOK
 // ============================================================
 // BDO-aligned types for the Activity pattern.
-// Reuses shared types from useForm where identical.
+// Reuses shared types from useBDOForm where identical.
 
 import type {
   UseFormWatch,
@@ -16,14 +16,14 @@ import type {
 
 import type { Activity } from '../../../workflow/Activity';
 
-// Reuse shared types from useForm — identical interfaces, no duplication
+// Reuse shared types from useBDOForm — identical interfaces, no duplication
 import type {
   HandleSubmitType,
   FormItemType,
   FormRegisterType,
   EditableFormFieldAccessorType,
   ReadonlyFormFieldAccessorType,
-} from '../useForm/types';
+} from '../useBDOForm/types';
 
 // Re-export for consumers who import from this module
 export type {
@@ -89,7 +89,7 @@ export interface UseActivityFormOptions<A extends Activity<any, any, any>> {
 // ============================================================
 
 /**
- * useActivityForm hook return type — mirrors useForm return structure
+ * useActivityForm hook return type — mirrors useBDOForm return structure
  */
 export interface UseActivityFormReturn<A extends Activity<any, any, any>> {
   /** Item proxy with typed field accessors */