@ram_28/kf-ai-sdk 2.0.14 → 2.0.16

package/docs/useActivityTable.md

@@ -0,0 +1,418 @@
+# useActivityTable
+
+Hook for listing workflow activity (business process) instances with search, sort, filter, and pagination.
+
+## Imports
+
+```typescript
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+import type {
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityRowType,
+  ActivityInstanceFieldsType,
+} from "@ram_28/kf-ai-sdk/workflow";
+```
+
+---
+
+## Common Mistakes (READ FIRST)
+
+### 1. Passing a Workflow instead of an Activity
+
+The `activity` property must be an `Activity` instance, not a `Workflow` instance.
+
+```typescript
+// ❌ WRONG — passing the workflow class
+const wf = new SimpleLeaveProcess();
+useActivityTable({ activity: wf, status: ActivityTableStatus.InProgress });
+
+// ✅ CORRECT — pass the activity instance
+const activity = new SimpleLeaveProcess().employeeInputActivity();
+useActivityTable({ activity, status: ActivityTableStatus.InProgress });
+```
+
+### 2. Using string literals instead of ActivityTableStatus
+
+While string literals work at runtime, always use the `ActivityTableStatus` constant for type safety and readability.
+
+```typescript
+// ❌ WRONG — raw string (no type safety, easy to typo)
+useActivityTable({ activity, status: "inProgress" });
+useActivityTable({ activity, status: "in_progress" });
+
+// ✅ CORRECT — use the constant
+useActivityTable({ activity, status: ActivityTableStatus.InProgress });
+useActivityTable({ activity, status: ActivityTableStatus.Completed });
+```
+
+### 3. Forgetting to memoize the activity instance
+
+Like BDO instances passed to `useBDOTable`, the activity instance should be memoized to prevent unnecessary re-renders and refetches.
+
+```typescript
+// ❌ WRONG — creates a new activity on every render
+const activity = new SimpleLeaveProcess().employeeInputActivity();
+useActivityTable({ activity, status: ActivityTableStatus.InProgress });
+
+// ✅ CORRECT — memoize with useMemo
+const activity = useMemo(
+  () => new SimpleLeaveProcess().employeeInputActivity(),
+  [],
+);
+useActivityTable({ activity, status: ActivityTableStatus.InProgress });
+```
+
+### 4. Calling `.get()` on activity table rows
+
+Table rows are plain objects, not `ActivityInstance` proxies. There is no `.get()` method.
+
+```typescript
+// ❌ WRONG — rows are plain objects
+row.StartDate.get();
+row.Status.get();
+
+// ✅ CORRECT — access values directly
+row.StartDate;
+row.Status;
+```
+
+---
+
+## Example: Employee Leave Request Table
+
+Display in-progress leave requests with search, pagination, and a detail view.
+
+```tsx
+import { useMemo, useState } from "react";
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+import type { ActivityRowType } from "@ram_28/kf-ai-sdk/workflow";
+import {
+  SimpleLeaveProcess,
+  EmployeeInputActivity,
+} from "@/bdo/workflows/SimpleLeaveProcess";
+
+function EmployeeLeaveTable() {
+  const activity = useMemo(() => new SimpleLeaveProcess().employeeInputActivity(), []);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  const {
+    rows,
+    totalItems,
+    isLoading,
+    isFetching,
+    error,
+    search,
+    sort,
+    pagination,
+    refetch,
+  } = useActivityTable({
+    activity,
+    status: ActivityTableStatus.InProgress,
+    initialState: {
+      pagination: { pageNo: 1, pageSize: 10 },
+    },
+    onError: (err) => console.error("Failed to load leave requests:", err.message),
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>My Leave Requests ({totalItems})</h2>
+
+      {/* Search */}
+      <div>
+        <input
+          type="text"
+          placeholder="Search by leave type..."
+          value={search.query}
+          onChange={(e) => search.set(activity.LeaveType.id, e.target.value)}
+        />
+        {search.query && <button onClick={search.clear}>Clear</button>}
+        {isFetching && <span>Loading...</span>}
+      </div>
+
+      {/* Table */}
+      <table>
+        <thead>
+          <tr>
+            <th>ID</th>
+            <th>Status</th>
+            <th>Assigned To</th>
+            <th
+              style={{ cursor: "pointer" }}
+              onClick={() => sort.toggle(activity.LeaveType.id)}
+            >
+              Leave Type
+            </th>
+            <th>Start Date</th>
+            <th>End Date</th>
+            <th>Days</th>
+            <th>Action</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={row._id}>
+              <td>{row._id}</td>
+              <td>{row.Status}</td>
+              <td>{row.AssignedTo.map((u) => u._name).join(", ")}</td>
+              <td>{row.LeaveType}</td>
+              <td>{row.StartDate}</td>
+              <td>{row.EndDate}</td>
+              <td>{row.LeaveDays}</td>
+              <td>
+                <button onClick={() => setSelectedId(row._id)}>View</button>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      {/* Pagination */}
+      <div>
+        <button
+          onClick={pagination.goToPrevious}
+          disabled={!pagination.canGoPrevious}
+        >
+          Previous
+        </button>
+        <span>
+          Page {pagination.pageNo} of {pagination.totalPages}
+        </span>
+        <button
+          onClick={pagination.goToNext}
+          disabled={!pagination.canGoNext}
+        >
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Example: Manager Approval Table
+
+Display pending approvals with status tabs for in-progress and completed items.
+
+```tsx
+import { useMemo, useState } from "react";
+import {
+  useActivityTable,
+  ActivityTableStatus,
+} from "@ram_28/kf-ai-sdk/workflow";
+import type { ActivityRowType } from "@ram_28/kf-ai-sdk/workflow";
+import { SimpleLeaveProcess } from "@/bdo/workflows/SimpleLeaveProcess";
+
+type StatusTab = "inprogress" | "completed";
+
+function ManagerApprovalTable() {
+  const activity = useMemo(
+    () => new SimpleLeaveProcess().managerApprovalActivity(),
+    [],
+  );
+  const [activeTab, setActiveTab] = useState<StatusTab>("inprogress");
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  const {
+    rows,
+    totalItems,
+    isLoading,
+    isFetching,
+    error,
+    search,
+    sort,
+    filter,
+    pagination,
+    refetch,
+  } = useActivityTable({
+    activity,
+    status: activeTab,
+    initialState: {
+      pagination: { pageNo: 1, pageSize: 10 },
+    },
+    onError: (err) => console.error("Fetch failed:", err.message),
+  });
+
+  if (selectedId) {
+    return (
+      <ApprovalForm
+        activityInstanceId={selectedId}
+        onComplete={() => {
+          setSelectedId(null);
+          refetch();
+        }}
+      />
+    );
+  }
+
+  return (
+    <div>
+      {/* Status tabs */}
+      <div>
+        <button
+          onClick={() => setActiveTab("inprogress")}
+          disabled={activeTab === "inprogress"}
+        >
+          Pending
+        </button>
+        <button
+          onClick={() => setActiveTab("completed")}
+          disabled={activeTab === "completed"}
+        >
+          Completed
+        </button>
+      </div>
+
+      <h2>
+        {activeTab === "inprogress" ? "Pending" : "Completed"} Approvals ({totalItems})
+      </h2>
+
+      {isLoading && <div>Loading...</div>}
+      {error && <div>Error: {error.message}</div>}
+
+      {/* Table */}
+      <table>
+        <thead>
+          <tr>
+            <th>ID</th>
+            <th
+              style={{ cursor: "pointer" }}
+              onClick={() => sort.toggle("Status")}
+            >
+              Status
+              {sort.field === "Status" && (
+                <span>{sort.direction === "ASC" ? " ↑" : " ↓"}</span>
+              )}
+            </th>
+            <th>Assigned To</th>
+            <th>Approved</th>
+            <th>Reason</th>
+            {activeTab === "inprogress" && <th>Action</th>}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={row._id}>
+              <td>{row._id}</td>
+              <td>{row.Status}</td>
+              <td>{row.AssignedTo.map((u) => u._name).join(", ")}</td>
+              <td>{row.ManagerApproved ? "Yes" : "No"}</td>
+              <td>{row.ManagerReason}</td>
+              {activeTab === "inprogress" && (
+                <td>
+                  <button onClick={() => setSelectedId(row._id)}>Review</button>
+                </td>
+              )}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      {/* Pagination */}
+      <div>
+        <button
+          onClick={pagination.goToPrevious}
+          disabled={!pagination.canGoPrevious}
+        >
+          Previous
+        </button>
+        <span>
+          Page {pagination.pageNo} of {pagination.totalPages}
+        </span>
+        <button
+          onClick={pagination.goToNext}
+          disabled={!pagination.canGoNext}
+        >
+          Next
+        </button>
+        <select
+          value={pagination.pageSize}
+          onChange={(e) => pagination.setPageSize(Number(e.target.value))}
+        >
+          <option value={10}>10 per page</option>
+          <option value={25}>25 per page</option>
+          <option value={50}>50 per page</option>
+        </select>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Type Definitions
+
+### ActivityTableStatus
+
+```typescript
+export const ActivityTableStatus = {
+  InProgress: "inprogress",
+  Completed: "completed",
+} as const;
+
+export type ActivityTableStatusType =
+  (typeof ActivityTableStatus)[keyof typeof ActivityTableStatus];
+```
+
+### ActivityRowType\<A\>
+
+Row type for activity table data. System fields and entity fields are flat at the top level.
+
+```typescript
+export type ActivityRowType<A extends Activity<any, any, any>> =
+  A extends Activity<infer E, any, any>
+    ? ActivityInstanceFieldsType & E
+    : never;
+```
+
+### UseActivityTableOptionsType\<A\>
+
+```typescript
+export interface UseActivityTableOptionsType<A extends Activity<any, any, any>> {
+  /** The activity instance to fetch data for */
+  activity: A;
+
+  /** Which activity instances to fetch — determines endpoint */
+  status: ActivityTableStatusType;
+
+  /** Initial state for sort, pagination, and filter */
+  initialState?: {
+    sort?: SortType;
+    pagination?: PaginationStateType;
+    filter?: UseFilterOptionsType<ActivityRowType<A>>;
+  };
+
+  /** Called when data fetch fails */
+  onError?: (error: Error) => void;
+
+  /** Called with fetched rows after successful load */
+  onSuccess?: (data: ActivityRowType<A>[]) => void;
+}
+```
+
+### UseActivityTableReturnType\<A\>
+
+```typescript
+export type UseActivityTableReturnType<A extends Activity<any, any, any>> =
+  UseTableReturnType<ActivityRowType<A>>;
+```
+
+The return type is identical to `UseTableReturnType`. All properties — `rows`, `totalItems`, `isLoading`, `isFetching`, `error`, `search`, `sort`, `filter`, `pagination`, and `refetch` — behave the same.
+
+---
+
+## Search, Sort, Filter, and Pagination
+
+`useActivityTable` supports `initialState`, `onError`, and `onSuccess` options.
+
+- **Search** — `search.set(field, query)`, `search.clear()`, 300ms debounce
+- **Sort** — `sort.toggle(field)`, `sort.set(field, direction)`, `sort.clear()`
+- **Filter** — `filter.addCondition(...)`, `filter.removeCondition(...)`, `filter.clearAllConditions()`
+- **Pagination** — `pagination.goToNext()`, `pagination.goToPrevious()`, `pagination.goToPage(n)`, `pagination.setPageSize(n)`

package/docs/{useForm.md → useBDOForm.md}

@@ -1,13 +1,13 @@
-# Form SDK API
+# useBDOForm
 
-React hook for forms with validation, API integration, and typed field handling.
+React hook for BDO forms with validation, API integration, and typed field handling.
 
 ## Imports
 
 ```typescript
-import { useForm } from "@ram_28/kf-ai-sdk/form";
+import { useBDOForm } from "@ram_28/kf-ai-sdk/form";
 import { ValidationMode, FormOperation } from "@ram_28/kf-ai-sdk/form";
-import type { UseFormOptionsType, UseFormReturnType, FormItemType, FormRegisterType, HandleSubmitType } from "@ram_28/kf-ai-sdk/form/types";
+import type { UseBDOFormOptionsType, UseBDOFormReturnType, FormItemType, FormRegisterType, HandleSubmitType } from "@ram_28/kf-ai-sdk/form/types";
 import type { CreateUpdateResponseType } from "@ram_28/kf-ai-sdk/api/types";
 
 // Pre-built components for special field types
@@ -20,34 +20,34 @@ import { FileUpload } from "@/components/ui/file-upload";
 
 ## Common Mistakes (READ FIRST)
 
-### 1. Missing `operation` in useForm options (TS2345)
+### 1. Missing `operation` in useBDOForm options (TS2345)
 
 ALWAYS include `operation`. Without it, TypeScript cannot resolve the union type.
 
 ```typescript
 // ❌ WRONG — missing operation (TS2345)
-useForm({ bdo: product, mode: ValidationMode.OnBlur });
+useBDOForm({ bdo: product, mode: ValidationMode.OnBlur });
 
 // ✅ CORRECT — always include operation
-useForm({ bdo: product, operation: FormOperation.Create, mode: ValidationMode.OnBlur });
-useForm({ bdo: product, operation: FormOperation.Update, recordId: id, mode: ValidationMode.OnBlur });
+useBDOForm({ bdo: product, operation: FormOperation.Create, mode: ValidationMode.OnBlur });
+useBDOForm({ bdo: product, operation: FormOperation.Update, recordId: id, mode: ValidationMode.OnBlur });
 ```
 
-### 2. Annotating ternary with UseFormOptionsType (TS2322)
+### 2. Annotating ternary with UseBDOFormOptionsType (TS2322)
 
-`UseFormOptionsType` is a discriminated union. Type-annotating a variable prevents TS narrowing. NEVER annotate — call useForm inline in each branch.
+`UseBDOFormOptionsType` is a discriminated union. Type-annotating a variable prevents TS narrowing. NEVER annotate — call useBDOForm inline in each branch.
 
 ```typescript
 // ❌ WRONG — type annotation prevents union narrowing (TS2322)
-const options: UseFormOptionsType<typeof bdo> = id
+const options: UseBDOFormOptionsType<typeof bdo> = id
   ? { bdo, operation: FormOperation.Update, recordId: id, mode: ValidationMode.OnBlur }
   : { bdo, operation: FormOperation.Create, mode: ValidationMode.OnBlur };
-const formResult = useForm(options);
+const formResult = useBDOForm(options);
 
-// ✅ CORRECT — call useForm inline, no type annotation
+// ✅ CORRECT — call useBDOForm inline, no type annotation
 const formResult = id
-  ? useForm({ bdo, operation: FormOperation.Update, recordId: id, mode: ValidationMode.OnBlur })
-  : useForm({ bdo, operation: FormOperation.Create, mode: ValidationMode.OnBlur });
+  ? useBDOForm({ bdo, operation: FormOperation.Update, recordId: id, mode: ValidationMode.OnBlur })
+  : useBDOForm({ bdo, operation: FormOperation.Create, mode: ValidationMode.OnBlur });
 const { register, handleSubmit, watch, setValue, item, formState: { errors, isSubmitting }, isLoading } = formResult;
 ```
 
@@ -161,11 +161,11 @@ const onSuccess = (data: CreateUpdateResponseType) => { toast.success("Saved");
 
 ```typescript
 // ❌ WRONG
-useForm<ProductFieldType>({ ... });
+useBDOForm<ProductFieldType>({ ... });
 
 // ✅ CORRECT — pass BDO class instance
 const product = useMemo(() => new SellerProduct(), []);
-useForm({ bdo: product, operation: FormOperation.Create, mode: ValidationMode.OnBlur });
+useBDOForm({ bdo: product, operation: FormOperation.Create, mode: ValidationMode.OnBlur });
 ```
 
 ### 9. Wrong default values for date fields
@@ -187,7 +187,7 @@ defaultValues: { start_date: undefined }
 
 import { useMemo } from "react";
 import { useNavigate, useParams } from "react-router-dom";
-import { useForm, ValidationMode, FormOperation } from "@ram_28/kf-ai-sdk/form";
+import { useBDOForm, ValidationMode, FormOperation } from "@ram_28/kf-ai-sdk/form";
 import type { CreateUpdateResponseType } from "@ram_28/kf-ai-sdk/api/types";
 import { AdminProduct } from "@/bdo/admin/Product";
 import { ReferenceSelect } from "@/components/ui/reference-select";
@@ -203,8 +203,8 @@ export default function ProductForm() {
 
   // Create/Edit ternary — NO type annotation on result
   const formResult = id
-    ? useForm({ bdo, operation: FormOperation.Update, recordId: id, mode: ValidationMode.OnBlur })
-    : useForm({ bdo, operation: FormOperation.Create, mode: ValidationMode.OnBlur });
+    ? useBDOForm({ bdo, operation: FormOperation.Update, recordId: id, mode: ValidationMode.OnBlur })
+    : useBDOForm({ bdo, operation: FormOperation.Create, mode: ValidationMode.OnBlur });
 
   const { register, handleSubmit, watch, setValue, item, formState: { errors, isSubmitting }, isLoading } = formResult;
 
@@ -310,19 +310,19 @@ export default function ProductForm() {
 
 ## Type Definitions
 
-### UseFormOptionsType (Discriminated Union)
+### UseBDOFormOptionsType (Discriminated Union)
 
 ```typescript
-type UseFormOptionsType<B extends BaseBdo<any, any, any>> =
+type UseBDOFormOptionsType<B extends BaseBdo<any, any, any>> =
   | { bdo: B; operation: "create"; defaultValues?: Partial<EditableFieldType>; mode?: ValidationModeType; }
   | { bdo: B; operation: "update"; recordId: string; mode?: ValidationModeType; }
   | { bdo: B; recordId?: string; defaultValues?: Partial<EditableFieldType>; mode?: ValidationModeType; };
 ```
 
-### UseFormReturnType
+### UseBDOFormReturnType
 
 ```typescript
-interface UseFormReturnType<B> {
+interface UseBDOFormReturnType<B> {
   item: FormItemType<EditableFieldType, ReadonlyFieldType>;  // Field accessors (.get(), .set(), .upload())
   register: FormRegisterType;       // Auto-disables readonly fields
   handleSubmit: HandleSubmitType;   // Auto-calls bdo.create() or bdo.update()