@ram_28/kf-ai-sdk 2.0.9 → 2.0.11

package/dist/workflow.types.d.ts

@@ -1,2 +1,3 @@
 export type { ActivityInstanceFieldsType, ActivityOperations, ActivityProgressType, WorkflowStartResponseType, } from './workflow/types';
+export type { UseActivityTableOptionsType, UseActivityTableReturnType, ActivityTableStatusType, ActivityRowType, } from './workflow/components/useActivityTable/types';
 //# sourceMappingURL=workflow.types.d.ts.map

package/dist/workflow.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.types.d.ts","sourceRoot":"","sources":["../sdk/workflow.types.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"workflow.types.d.ts","sourceRoot":"","sources":["../sdk/workflow.types.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,uBAAuB,EACvB,eAAe,GAChB,MAAM,8CAA8C,CAAC"}

package/docs/api.md

@@ -277,7 +277,7 @@ interface ConditionType {
   Operator: ConditionOperatorType;
   LHSField: string;
   RHSValue: any;
-  RHSType?: "Constant" | "BOField" | "AppVariable";
+  RHSType?: "Constant" | "BDOField" | "AppVariable";
 }
 ```
 

package/docs/useFilter.md

@@ -59,7 +59,7 @@ GroupOperator.Not  // "Not"
 
 // RHS types
 RHSType.Constant    // "Constant"
-RHSType.BOField     // "BOField"
+RHSType.BDOField    // "BDOField"
 RHSType.AppVariable // "AppVariable"
 ```
 
@@ -103,7 +103,7 @@ interface ConditionType<T = any> {
   RHSValue: any;
 
   // Value type (default: "Constant")
-  RHSType?: "Constant" | "BOField" | "AppVariable";
+  RHSType?: "Constant" | "BDOField" | "AppVariable";
 }
 
 // Condition group (can contain conditions or nested groups)
@@ -198,8 +198,9 @@ interface UseFilterReturnType<T = any> {
 | Between, NotBetween   | number, date, currency |
 | IN, NIN               | All types              |
 | Empty, NotEmpty       | All types              |
-| Contains, NotContains | string only            |
-| MinLength, MaxLength  | string only            |
+| Contains, NotContains | string, reference/user (with dot notation) |
+| MinLength, MaxLength  | string, array          |
+| Length                 | array                  |
 
 ## Basic Example
 
@@ -621,6 +622,174 @@ function EmptyFilters() {
 
 ---
 
+## Filtering Reference & User Fields
+
+Reference and User fields are stored as JSON objects (`{ _id, _name, ... }`). The backend automatically targets the `_id` sub-field when filtering these fields. User and Reference fields behave identically for filtering.
+
+### Supported Operators
+
+| Operator | Supported | Notes |
+| --- | --- | --- |
+| EQ, NE | Yes | Compares against `_id` by default |
+| IN, NIN | Yes | List of IDs |
+| Empty, NotEmpty | Yes | Checks if field is null/unset |
+| Contains, NotContains | Only with dot notation | e.g., `"Vendor._name"` |
+| GT, GTE, LT, LTE, Between | No | Raises backend error |
+
+### Filter by ID (Default)
+
+When filtering a Reference or User field, pass the `_id` string directly as `RHSValue`. The backend automatically compares against the `_id` sub-field.
+
+```tsx
+import { useMemo } from "react";
+import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
+import { AdminCartItem } from "../bdo/admin/CartItem";
+
+function ReferenceFilter() {
+  const cartItem = useMemo(() => new AdminCartItem(), []);
+  const filter = useFilter();
+
+  // Filter cart items by a specific product ID
+  const filterByProduct = (productId: string) => {
+    filter.addCondition({
+      Operator: ConditionOperator.EQ,
+      LHSField: cartItem.ProductInfo.id,
+      RHSValue: productId,
+      RHSType: RHSType.Constant,
+    });
+  };
+
+  // Filter by multiple product IDs
+  const filterByProducts = (productIds: string[]) => {
+    filter.addCondition({
+      Operator: ConditionOperator.IN,
+      LHSField: cartItem.ProductInfo.id,
+      RHSValue: productIds,
+      RHSType: RHSType.Constant,
+    });
+  };
+
+  // Filter unassigned items (reference is empty)
+  const filterUnlinked = () => {
+    filter.addCondition({
+      Operator: ConditionOperator.Empty,
+      LHSField: cartItem.ProductInfo.id,
+      RHSValue: null,
+      RHSType: RHSType.Constant,
+    });
+  };
+
+  return (
+    <div>
+      <button onClick={() => filterByProduct("PROD_001")}>
+        Filter by Product
+      </button>
+      <button onClick={() => filterByProducts(["PROD_001", "PROD_002"])}>
+        Filter by Multiple
+      </button>
+      <button onClick={filterUnlinked}>Unlinked Items</button>
+    </div>
+  );
+}
+```
+
+### Filter by Name (Dot Notation)
+
+Use dot notation in `LHSField` to filter on a nested sub-field like `_name`. This skips the default `_id` targeting and compares against the specified path.
+
+```tsx
+import { useMemo } from "react";
+import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
+import { AdminCartItem } from "../bdo/admin/CartItem";
+
+function ReferenceNameFilter() {
+  const cartItem = useMemo(() => new AdminCartItem(), []);
+  const filter = useFilter();
+
+  // Search product name within the reference field
+  const searchProductName = (name: string) => {
+    filter.addCondition({
+      Operator: ConditionOperator.Contains,
+      LHSField: `${cartItem.ProductInfo.id}._name`,
+      RHSValue: name,
+      RHSType: RHSType.Constant,
+    });
+  };
+
+  return (
+    <input
+      placeholder="Search by product name..."
+      onKeyDown={(e) => {
+        if (e.key === "Enter") {
+          searchProductName((e.target as HTMLInputElement).value);
+        }
+      }}
+    />
+  );
+}
+```
+
+### Filter System User Fields
+
+System fields `_created_by` and `_modified_by` are User fields. Filter them the same way.
+
+```tsx
+import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
+
+function UserFieldFilter() {
+  const filter = useFilter();
+
+  // Filter by creator (using user's _id)
+  const filterByCreator = (userId: string) => {
+    filter.addCondition({
+      Operator: ConditionOperator.EQ,
+      LHSField: "_created_by",
+      RHSValue: userId,
+      RHSType: RHSType.Constant,
+    });
+  };
+
+  // Search by creator name
+  const searchByCreatorName = (name: string) => {
+    filter.addCondition({
+      Operator: ConditionOperator.Contains,
+      LHSField: "_created_by._name",
+      RHSValue: name,
+      RHSType: RHSType.Constant,
+    });
+  };
+
+  return (
+    <div>
+      <button onClick={() => filterByCreator("USR_001")}>My Items</button>
+      <input
+        placeholder="Search by creator..."
+        onKeyDown={(e) => {
+          if (e.key === "Enter") {
+            searchByCreatorName((e.target as HTMLInputElement).value);
+          }
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### RHSValue Formats
+
+The backend accepts multiple `RHSValue` formats for Reference/User fields:
+
+| Format | Example | When to use |
+| --- | --- | --- |
+| String ID | `"PROD_001"` | Simplest — use when you have the ID |
+| Object with `_id` | `{ _id: "PROD_001", _name: "Widget" }` | Backend extracts `_id` automatically |
+| Array of IDs | `["PROD_001", "PROD_002"]` | With `IN` / `NIN` operators |
+| Array of objects | `[{ _id: "PROD_001" }, { _id: "PROD_002" }]` | With `IN` / `NIN` — backend extracts each `_id` |
+
+> **Tip:** Prefer passing the string ID directly. Passing the full object works but adds unnecessary payload size.
+
+---
+
 ## Condition Groups
 
 ### AND Logic
@@ -1319,7 +1488,93 @@ Produces:
 }
 ```
 
-> **Note:** The `RHSType` field defaults to `"Constant"` and is automatically added to the payload. Other possible values are `"BOField"` (reference another field) and `"AppVariable"` (reference an application variable).
+> **Note:** The `RHSType` field defaults to `"Constant"` and is automatically added to the payload. Other possible values are `"BDOField"` (reference another BDO field) and `"AppVariable"` (reference an application variable).
+
+### Reference Field (EQ)
+
+```tsx
+import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
+
+filter.addCondition({
+  Operator: ConditionOperator.EQ,
+  LHSField: cartItem.ProductInfo.id,
+  RHSValue: "PROD_001",
+  RHSType: RHSType.Constant,
+});
+```
+
+Produces:
+
+```json
+{
+  "Operator": "And",
+  "Condition": [
+    {
+      "Operator": "EQ",
+      "LHSField": "ProductInfo",
+      "RHSValue": "PROD_001",
+      "RHSType": "Constant"
+    }
+  ]
+}
+```
+
+### Reference Field Nested Path (Contains)
+
+```tsx
+filter.addCondition({
+  Operator: ConditionOperator.Contains,
+  LHSField: `${cartItem.ProductInfo.id}._name`,
+  RHSValue: "Widget",
+  RHSType: RHSType.Constant,
+});
+```
+
+Produces:
+
+```json
+{
+  "Operator": "And",
+  "Condition": [
+    {
+      "Operator": "Contains",
+      "LHSField": "ProductInfo._name",
+      "RHSValue": "Widget",
+      "RHSType": "Constant"
+    }
+  ]
+}
+```
+
+### Field-to-Field Comparison (BDOField)
+
+Use `RHSType.BDOField` to compare one field against another field instead of a constant value.
+
+```tsx
+// Filter where Quantity exceeds Stock (field vs field)
+filter.addCondition({
+  Operator: ConditionOperator.GT,
+  LHSField: cartItem.Quantity.id,
+  RHSValue: cartItem.Stock.id,
+  RHSType: RHSType.BDOField,
+});
+```
+
+Produces:
+
+```json
+{
+  "Operator": "And",
+  "Condition": [
+    {
+      "Operator": "GT",
+      "LHSField": "Quantity",
+      "RHSValue": "Stock",
+      "RHSType": "BDOField"
+    }
+  ]
+}
+```
 
 ---
 
@@ -1337,7 +1592,7 @@ Only three RHSType values exist. Any other string causes TS2322.
 
 // ✅ CORRECT — only these three values
 { RHSType: RHSType.Constant }    // "Constant"
-{ RHSType: RHSType.BOField }     // "BOField"
+{ RHSType: RHSType.BDOField }    // "BDOField"
 { RHSType: RHSType.AppVariable } // "AppVariable"
 ```
 
@@ -1387,3 +1642,21 @@ const conditions: Omit<ConditionType, "id">[] = [
   { Operator: ConditionOperator.EQ, ... }
 ];
 ```
+
+### 5. Filtering Reference/User fields without _id
+
+The backend automatically targets `_id` when you filter a Reference or User field by name. Do NOT manually append `._id` unless you specifically want to bypass the backend's auto-extraction.
+
+```typescript
+// ❌ WRONG — unnecessary, and disables auto-extraction of _id from objects
+{ LHSField: "ProductInfo._id", Operator: "EQ", RHSValue: { _id: "P1", _name: "Widget" } }
+
+// ✅ CORRECT — backend auto-targets _id
+{ LHSField: "ProductInfo", Operator: "EQ", RHSValue: "P1" }
+
+// ✅ CORRECT — backend extracts _id from the object
+{ LHSField: "ProductInfo", Operator: "EQ", RHSValue: { _id: "P1", _name: "Widget" } }
+
+// ✅ CORRECT — dot notation for filtering by _name
+{ LHSField: "ProductInfo._name", Operator: "Contains", RHSValue: "Widget" }
+```

package/docs/workflow.md

@@ -11,6 +11,8 @@ import {
   Activity,
   ActivityInstance,
   useActivityForm,
+  useActivityTable,
+  ActivityTableStatus,
 } from "@ram_28/kf-ai-sdk/workflow";
 
 // Type-only exports
@@ -20,6 +22,9 @@ import type {
   WorkflowStartResponseType,
   UseActivityFormOptions,
   UseActivityFormReturn,
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityRowType,
 } from "@ram_28/kf-ai-sdk/workflow";
 
 // Field classes (for defining Activity fields)
@@ -82,11 +87,72 @@ System fields present on every activity instance. Returned alongside activity-sp
 type ActivityInstanceFieldsType = {
   _id: StringFieldType;
   Status: SelectFieldType<"InProgress" | "Completed">;
-  AssignedTo: ReferenceFieldType<{ _id: StringFieldType; username: StringFieldType }>;
+  AssignedTo: UserFieldType;
   CompletedAt: DateTimeFieldType;
 };
 ```
 
+### ActivityTableStatus (constant)
+
+```typescript
+const ActivityTableStatus = {
+  InProgress: 'inprogress',
+  Completed: 'completed',
+} as const;
+
+type ActivityTableStatusType =
+  (typeof ActivityTableStatus)[keyof typeof ActivityTableStatus];
+```
+
+### ActivityRowType\<A\>
+
+Row type for activity table data. Combines activity instance system fields with entity-specific fields.
+
+```typescript
+type ActivityRowType<A extends Activity<any, any, any>> =
+  ActivityInstanceFieldsType & ExtractActivityEntity<A>;
+```
+
+Concrete example — for `ManagerApprovalActivity` with `{ ManagerApproved: boolean, ManagerReason: string }`:
+
+```typescript
+// ActivityRowType<ManagerApprovalActivity> resolves to:
+{
+  // System fields (from ActivityInstanceFieldsType)
+  _id: string;
+  Status: "InProgress" | "Completed";
+  AssignedTo: UserFieldType;
+  CompletedAt: string;
+
+  // Entity fields (from ManagerApprovalEntityType)
+  ManagerApproved: boolean;
+  ManagerReason: string;
+}
+```
+
+### UseActivityTableOptionsType\<A\>
+
+```typescript
+interface UseActivityTableOptionsType<A extends Activity<any, any, any>> {
+  status: ActivityTableStatusType;
+  onError?: (error: Error) => void;
+  onSuccess?: (data: ActivityRowType<A>[]) => void;
+}
+```
+
+### UseActivityTableReturnType\<A\>
+
+```typescript
+interface UseActivityTableReturnType<A extends Activity<any, any, any>> {
+  rows: ActivityRowType<A>[];
+  totalItems: number;
+  isLoading: boolean;
+  isFetching: boolean;
+  error: Error | null;
+  refetch: () => Promise<ListResponseType<ActivityRowType<A>>>;
+}
+```
+
 ### UseActivityFormOptions\<A\>
 
 ```typescript
@@ -382,6 +448,40 @@ User clicks Complete
 
 ---
 
+## useActivityTable Hook
+
+React hook for listing workflow activity instances. Fetches data from
+`getInProgressList()` or `getCompletedList()` and the corresponding
+metrics endpoint.
+
+### Signature
+
+```typescript
+useActivityTable(activity: A, options: UseActivityTableOptionsType<A>)
+  : UseActivityTableReturnType<A>
+```
+
+### Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `status` | `ActivityTableStatusType` | *required* | `ActivityTableStatus.InProgress` or `ActivityTableStatus.Completed` |
+| `onError` | `(error: Error) => void` | — | Error callback |
+| `onSuccess` | `(data: ActivityRowType<A>[]) => void` | — | Success callback |
+
+### Return Value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `rows` | `ActivityRowType<A>[]` | Activity instance records (system + entity fields) |
+| `totalItems` | `number` | Total count (from metrics endpoint) |
+| `isLoading` | `boolean` | Initial load in progress |
+| `isFetching` | `boolean` | Any fetch in progress (including refetch) |
+| `error` | `Error \| null` | Fetch error |
+| `refetch` | `() => Promise<...>` | Refetch both list and metrics |
+
+---
+
 ## Use Case: Employee Creating Leave
 
 ### Step 1 — Start the workflow
@@ -542,18 +642,63 @@ function LeaveRequestPage() {
 
 ## Use Case: Manager Approving Leave
 
-### Step 1 — List in-progress items
+### Step 1 — List in-progress items with useActivityTable
 
-```typescript
-import { SimpleLeaveProcess } from "@/bdo/workflows/SimpleLeaveProcess";
+```tsx
+import { useMemo, useState } from "react";
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+import { SimpleLeaveProcess, ManagerApprovalActivity } from "@/bdo/workflows/SimpleLeaveProcess";
 
-const wf = new SimpleLeaveProcess();
-const activity = wf.managerApprovalActivity();
+function ManagerApprovalPage() {
+  const activity = useMemo(() => new SimpleLeaveProcess().managerApprovalActivity(), []);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
 
-const result = await activity.getInProgressList();
+  const { rows, totalItems, isLoading, error, refetch } = useActivityTable(activity, {
+    status: ActivityTableStatus.InProgress,
+  });
 
-for (const item of result.Data) {
-  console.log(item._id, item.Status, item.AssignedTo.username);
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  if (selectedId) {
+    return (
+      <ApprovalForm
+        activityInstanceId={selectedId}
+        onComplete={() => {
+          setSelectedId(null);
+          refetch();
+        }}
+      />
+    );
+  }
+
+  return (
+    <div>
+      <h2>Pending Approvals ({totalItems})</h2>
+      <table>
+        <thead>
+          <tr>
+            <th>ID</th>
+            <th>Status</th>
+            <th>Assigned To</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._name}</td>
+              <td>
+                <button onClick={() => setSelectedId(row._id)}>Review</button>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
 }
 ```
 
@@ -703,7 +848,7 @@ const progressList = await wf.progress(BPInstanceId);
 |-------|------|-------------|
 | `_id` | `StringFieldType` | Unique activity instance identifier |
 | `Status` | `SelectFieldType<"InProgress" \| "Completed">` | Current status |
-| `AssignedTo` | `ReferenceFieldType<UserRefType>` | Assigned user (has `._id` and `.username`) |
+| `AssignedTo` | `UserFieldType` | Assigned user (has `._id` and `._name`) |
 | `CompletedAt` | `DateTimeFieldType` | Completion timestamp (`"YYYY-MM-DDTHH:MM:SS"`) |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",

package/sdk/components/hooks/useFilter/useFilter.llm.txt

@@ -28,7 +28,7 @@ import type {
 
 ```typescript
 const filter = useFilter({
-  initialOperator: "And",
+  operator: "And",
 });
 
 // Add a condition at root level
@@ -77,8 +77,8 @@ table.filter.clearAllConditions();
 
 | Property | Type | Required | Default | Description |
 |----------|------|----------|---------|-------------|
-| `initialConditions` | `Array<ConditionType \| ConditionGroupType>` | No | `[]` | Initial filter conditions |
-| `initialOperator` | `ConditionGroupOperatorType` | No | `"And"` | Initial root operator |
+| `conditions` | `Array<ConditionType \| ConditionGroupType>` | No | `[]` | Filter conditions |
+| `operator` | `ConditionGroupOperatorType` | No | `"And"` | Operator for combining conditions |
 
 ## Return Value
 
@@ -126,7 +126,7 @@ interface ConditionType {
   Operator: ConditionOperatorType;
   LHSField: string;               // Field name to filter on
   RHSValue: any;                  // Value to compare against
-  RHSType?: FilterRHSTypeType;    // "Constant" | "BOField" | "AppVariable"
+  RHSType?: FilterRHSTypeType;    // "Constant" | "BDOField" | "AppVariable"
 }
 ```
 
@@ -271,6 +271,18 @@ const buildComplexFilter = () => {
 };
 ```
 
+### Field-to-Field Comparison (BDOField)
+
+```typescript
+// Filter where Quantity exceeds Stock (field vs field)
+filter.addCondition({
+  Operator: "GT",
+  LHSField: "Quantity",
+  RHSValue: "Stock",
+  RHSType: "BDOField",
+});
+```
+
 ### Toggle Root Operator
 
 ```typescript
@@ -356,6 +368,63 @@ table.filter.hasConditions;
 table.filter.payload;
 ```
 
+## Filtering Reference & User Fields
+
+Reference and User fields store `{ _id, _name, ... }` objects. Key rules:
+
+- **Default targets `_id`**: Pass string ID as `RHSValue`, backend auto-compares against `_id`
+- **Dot notation for nested paths**: Use `"FieldName._name"` in `LHSField` to filter by `_name` or other sub-fields
+- **Supported operators**: `EQ`, `NE`, `IN`, `NIN`, `Empty`, `NotEmpty`
+- **Contains/NotContains**: Only with dot notation (e.g., `"Vendor._name"`)
+- **GT/GTE/LT/LTE/Between**: NOT supported — raises backend error
+
+### Examples
+
+```typescript
+// Filter by reference ID
+filter.addCondition({
+  Operator: "EQ",
+  LHSField: "ProductInfo",    // field name, NOT "ProductInfo._id"
+  RHSValue: "PROD_001",       // string ID directly
+  RHSType: "Constant",
+});
+
+// Filter by multiple IDs
+filter.addCondition({
+  Operator: "IN",
+  LHSField: "ProductInfo",
+  RHSValue: ["PROD_001", "PROD_002"],
+  RHSType: "Constant",
+});
+
+// Search by reference name (dot notation)
+filter.addCondition({
+  Operator: "Contains",
+  LHSField: "ProductInfo._name",   // dot notation for nested path
+  RHSValue: "Widget",
+  RHSType: "Constant",
+});
+
+// Filter system user field
+filter.addCondition({
+  Operator: "EQ",
+  LHSField: "_created_by",
+  RHSValue: "USR_001",
+  RHSType: "Constant",
+});
+```
+
+### RHSValue Formats
+
+| Format | Example | When to use |
+|--------|---------|-------------|
+| String ID | `"PROD_001"` | Simplest — use when you have the ID |
+| Object | `{ _id: "PROD_001", _name: "Widget" }` | Backend extracts `_id` automatically |
+| Array of IDs | `["PROD_001", "PROD_002"]` | With IN/NIN operators |
+| Array of objects | `[{ _id: "PROD_001" }]` | With IN/NIN — backend extracts each `_id` |
+
+Prefer passing string IDs directly for simplicity.
+
 ## Key Behaviors
 
 1. **Auto-generated IDs**: All conditions get unique IDs via `generateId()`