@ram_28/kf-ai-sdk 2.0.16 → 2.0.17

package/docs/useActivityTable/README.md

@@ -0,0 +1,263 @@
+# useActivityTable
+
+Activity-integrated table hook for listing workflow instances with search, sorting, filtering, and pagination.
+
+## When to Use
+
+**Use `useActivityTable` when:**
+
+- Displaying in-progress or completed workflow activity instances
+- You need search, sort, filter, and/or pagination on activity data
+
+**Use something else when:**
+
+- Displaying BDO records (not workflow) — use [`useBDOTable`](../useBDOTable/README.md) instead
+- Building a form for an activity instance — use [`useActivityForm`](../useActivityForm/README.md) instead
+
+## Imports
+
+```tsx
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+```
+
+## Quick Start
+
+```tsx
+import { useMemo } from "react";
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+import { EmployeeInputActivity } from "@/bdo/workflows/SimpleLeaveProcess";
+
+function PendingLeaveRequests() {
+  const activity = useMemo(() => new EmployeeInputActivity(), []);
+
+  const table = useActivityTable({
+    activity,
+    status: ActivityTableStatus.InProgress,
+  });
+
+  if (table.isLoading) return <p>Loading...</p>;
+  if (table.error) return <p>Error: {table.error.message}</p>;
+
+  return (
+    <div>
+      <ul>
+        {table.rows.map((row) => (
+          <li key={row._id}>
+            {row.LeaveType.get()} — {row.StartDate.get()} to {row.EndDate.get()}
+          </li>
+        ))}
+      </ul>
+
+      <button
+        onClick={table.pagination.goToPrevious}
+        disabled={!table.pagination.canGoPrevious}
+      >
+        Previous
+      </button>
+      <span>
+        Page {table.pagination.pageNo} of {table.pagination.totalPages}
+      </span>
+      <button
+        onClick={table.pagination.goToNext}
+        disabled={!table.pagination.canGoNext}
+      >
+        Next
+      </button>
+    </div>
+  );
+}
+```
+
+## Usage Guide
+
+### Status Filter
+
+Every `useActivityTable` call requires a `status` option that determines which items are fetched:
+
+```tsx
+const [status, setStatus] = useState(ActivityTableStatus.InProgress);
+
+const table = useActivityTable({
+  activity,
+  status,
+});
+```
+
+- **`ActivityTableStatus.InProgress`** — fetches the in-progress items of the current activity
+- **`ActivityTableStatus.Completed`** — fetches the completed items of the current activity
+- Raw values are `'inprogress'` (all lowercase, no underscore) and `'completed'`
+- Always use the `ActivityTableStatus` constants — never raw strings
+- Changing status re-fetches automatically (status is part of the query key)
+
+### Accessing Row Data
+
+Rows are `ActivityInstanceType` proxies, not plain objects. Access field values through the `.get()` method on each field accessor:
+
+```tsx
+table.rows.map((row) => (
+  <tr key={row._id}>
+    <td>{row.LeaveType.get()}</td>
+    <td>{row.StartDate.get()}</td>
+    <td>{row.EndDate.get()}</td>
+    <td>{row.LeaveDays.get()}</td>
+    <td>{row.Status.get()}</td>
+  </tr>
+));
+```
+
+- `row._id` is a direct string (no `.get()` needed)
+- `row.LeaveType.get()` returns the field's current value
+- Activity system fields: `row.BPInstanceId.get()`, `row.Status.get()`, `row.AssignedTo.get()`, `row.CompletedAt.get()`
+- `row.toJSON()` converts the entire row to a plain object
+- Editable fields also have `.set()`, but this is typically not used in a table context
+- Persistence methods available on each row: `row.update()`, `row.save()`, `row.complete()`, `row.progress()`
+
+### Search
+
+Search filters results by matching a query string against a specific field. The input value updates immediately for a responsive UI, while the data fetch is debounced.
+
+```tsx
+<input
+  type="text"
+  placeholder={`Search by ${activity.EmployeeName.label}...`}
+  value={table.search.query}
+  onChange={(e) => table.search.set(activity.EmployeeName.id, e.target.value)}
+/>
+{table.search.query && (
+  <button onClick={table.search.clear}>Clear</button>
+)}
+{table.isFetching && <span>Searching...</span>}
+```
+
+- **`search.set(field, query)`** — set the field and query text. The data fetch is debounced by 300ms. Pagination resets to page 1.
+- **`search.clear()`** — clear the search field and query. Pagination resets to page 1.
+- **`search.query`** — current query string (updates immediately, API call debounced)
+- **`search.field`** — field currently being searched, or `null`
+- Queries longer than 255 characters are silently ignored.
+
+### Sorting
+
+Sorting is controlled through the `sort` object. Column headers typically use `toggle()` for click-to-sort behavior:
+
+```tsx
+<th
+  onClick={() => table.sort.toggle(activity.StartDate.id)}
+  style={{ cursor: "pointer" }}
+>
+  {activity.StartDate.label}
+  {table.sort.field === activity.StartDate.id &&
+    (table.sort.direction === "ASC" ? " ↑" : " ↓")}
+</th>
+```
+
+- **`sort.toggle(field)`** — cycles through ASC, DESC, then cleared. Toggling a different field starts at ASC.
+- **`sort.set(field, direction)`** — set the sort field and direction directly. Pass `null` for both to clear.
+- **`sort.clear()`** — remove sorting entirely.
+- **`sort.field`** / **`sort.direction`** — current sort state, or `null` when no sort is active.
+- **`initialState.sort`** format is an array of single-key objects: `[{ fieldName: "ASC" }]`.
+
+### Filtering
+
+The table includes an integrated [`useFilter`](../useFilter/README.md) instance at `table.filter`. Use it to build filter conditions that narrow down the table results:
+
+```tsx
+import { ConditionOperator } from "@ram_28/kf-ai-sdk/table";
+
+// Filter by leave type
+table.filter.addCondition({
+  Operator: ConditionOperator.EQ,
+  LHSField: activity.LeaveType.id,
+  RHSValue: "PTO",
+  RHSType: "Constant",
+});
+
+// Date range filter
+table.filter.addCondition({
+  Operator: ConditionOperator.GTE,
+  LHSField: activity.StartDate.id,
+  RHSValue: "2026-01-01",
+  RHSType: "Constant",
+});
+
+// Clear all filters
+table.filter.clearAllConditions();
+
+// Check if any filters are active
+if (table.filter.hasConditions) {
+  // ...
+}
+```
+
+- **`table.filter.addCondition(condition)`** — add a filter condition
+- **`table.filter.clearAllConditions()`** — remove all filter conditions
+- **`table.filter.hasConditions`** — `true` if any conditions are active
+- Filter changes automatically reset pagination to page 1, preventing empty pages after narrowing results.
+- See the [useFilter documentation](../useFilter/README.md) for the full filter API.
+
+### Pagination
+
+Pages are 1-indexed (they start at 1, not 0). The default page is 1 and the default page size is 10.
+
+```tsx
+<div>
+  <button
+    onClick={table.pagination.goToPrevious}
+    disabled={!table.pagination.canGoPrevious}
+  >
+    Previous
+  </button>
+  <span>
+    Page {table.pagination.pageNo} of {table.pagination.totalPages}
+    {" "}({table.pagination.totalItems} total)
+  </span>
+  <button
+    onClick={table.pagination.goToNext}
+    disabled={!table.pagination.canGoNext}
+  >
+    Next
+  </button>
+</div>
+
+<select
+  value={table.pagination.pageSize}
+  onChange={(e) => table.pagination.setPageSize(Number(e.target.value))}
+>
+  <option value={10}>10</option>
+  <option value={25}>25</option>
+  <option value={50}>50</option>
+</select>
+```
+
+- **`pagination.goToNext()`** / **`pagination.goToPrevious()`** — navigate forward/backward. No-op at boundaries.
+- **`pagination.goToPage(n)`** — jump to a specific page. Clamped to `[1, totalPages]`.
+- **`pagination.canGoNext`** / **`pagination.canGoPrevious`** — whether navigation is possible.
+- **`pagination.setPageSize(n)`** — change the page size. Resets to page 1.
+- **`pagination.pageNo`** / **`pagination.pageSize`** / **`pagination.totalPages`** / **`pagination.totalItems`** — current pagination state.
+
+### Refetching
+
+Call `refetch()` to manually refresh the table data. This refetches both the list and the count:
+
+```tsx
+const handleComplete = async (row) => {
+  await row.complete();
+  table.refetch();
+};
+```
+
+This is the standard pattern after any mutation (complete, update, save) that should be reflected in the table. Also use `table.refetch()` after closing a form dialog that modifies an activity instance.
+
+## Further Reading
+
+- [API Reference](./api_reference.md) — All options, return values, and type definitions
+- [My Pending Requests](../examples/workflow/my-pending-requests.md) — In Progress / Completed tabs
+- [Filtered Activity Table](../examples/workflow/filtered-activity-table.md) — Date range filter on activities
+
+## Common Mistakes
+
+- **Don't forget `useMemo` on the Activity instance.** `new ActivityClass()` must be wrapped in `useMemo(() => ..., [])`. Re-creating the instance on every render causes infinite refetching.
+- **Don't access row fields directly.** `row.LeaveType` is an accessor object, not the value. Use `row.LeaveType.get()` to read the value.
+- **Don't use raw strings for status.** Use `ActivityTableStatus.InProgress` and `ActivityTableStatus.Completed`, not `'inProgress'` or `'in_progress'`.
+- **Don't use 0-indexed pagination.** Pages start at 1. Passing `pageNo: 0` will produce incorrect results.
+- **Don't forget to guard on `isLoading` before rendering rows.** While loading, `rows` is an empty array. Guard with `if (table.isLoading) return <Loading />` to avoid rendering an empty table.
+- **Don't hardcode field names as strings.** Use the activity field IDs (`activity.StartDate.id`) instead of raw strings (`"StartDate"`). This keeps your code type-safe and resilient to field renames.

package/docs/useActivityTable/api_reference.md

@@ -0,0 +1,294 @@
+# useActivityTable API Reference
+
+```tsx
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+import type {
+  UseActivityTableOptionsType,
+  UseActivityTableReturnType,
+  ActivityRowType,
+  ActivityTableStatusType,
+} from "@ram_28/kf-ai-sdk/workflow";
+import type { ActivityInstanceFieldsType } from "@ram_28/kf-ai-sdk/workflow";
+```
+
+## Signature
+
+```tsx
+const table: UseActivityTableReturnType<A> = useActivityTable<A>(options: UseActivityTableOptionsType<A>);
+```
+
+## Options
+
+`UseActivityTableOptionsType<A>`
+
+- `activity: A`
+  - **Required**
+  - Activity instance with `getInProgressList()`, `getCompletedList()`, `inProgressCount()`, and `completedCount()` methods. Must be memoized with `useMemo()`.
+- `status: ActivityTableStatusType`
+  - **Required**
+  - `ActivityTableStatus.InProgress` or `ActivityTableStatus.Completed`. Determines whether in-progress or completed items are fetched.
+- `initialState`
+  - **Optional**
+  - Object with:
+    - `sort?: SortType` — Initial sort configuration. Format: `[{ "fieldName": "ASC" }]`
+    - `pagination?: PaginationStateType` — Initial page and page size. Defaults to `{ pageNo: 1, pageSize: 10 }`.
+    - `filter?: UseFilterOptionsType<ActivityRowType<A>>` — Initial filter conditions and operator.
+- `onError?: (error: Error) => void`
+  - **Optional**
+  - Called when fetching items or count fails.
+- `onSuccess?: (data: ActivityRowType<A>[]) => void`
+  - **Optional**
+  - Called with the current page rows after a successful list fetch.
+
+## Return Value
+
+`UseActivityTableReturnType<A>`
+
+Alias for `UseTableReturnType<ActivityRowType<A>>`. `ActivityRowType<A>` resolves to `ActivityInstanceType<TEntity & ActivityInstanceFieldsType, TEditable, TReadonly & ActivitySystemReadonlyType>` — inferred from the Activity's `getInProgressList()` return type. Rows are proxy objects with `.get()` accessors, persistence methods, and activity system fields.
+
+### Data
+
+- `rows: ActivityInstanceType<...>[]`
+  - Array of `ActivityInstanceType` proxy instances for the current page. Access field values via `.get()` (e.g. `row.LeaveType.get()`), not direct property access. Each row also has persistence methods (`update()`, `save()`, `complete()`, `progress()`) and activity system fields (`BPInstanceId`, `Status`, `AssignedTo`, `CompletedAt`). Empty array during initial loading.
+- `totalItems: number`
+  - Total number of records matching the current filters and search. `0` while count is loading.
+
+### Loading & Error
+
+- `isLoading: boolean`
+  - `true` during the initial load of both items and count.
+- `isFetching: boolean`
+  - `true` during any fetch including background refetches for items or count.
+- `error: Error | null`
+  - Most recent fetch error from either items or count. `null` when no error.
+
+### Search
+
+- `search.query: string`
+  - Current search input value (updated immediately on `set()`).
+- `search.field: keyof T | null`
+  - The field currently being searched. `null` when no search is active.
+- `search.set(field: keyof T, query: string): void`
+  - Set the search field and query. The input value updates immediately; the data fetch is debounced by 300 ms. Pagination resets to page 1 after the debounce. Query is capped at 255 characters.
+- `search.clear(): void`
+  - Clear the search field and query. Pagination resets to page 1.
+
+### Sort
+
+- `sort.field: keyof T | null`
+  - Currently sorted field. `null` when no sort is active.
+- `sort.direction: "ASC" | "DESC" | null`
+  - Current sort direction. `null` when no sort is active.
+- `sort.toggle(field: keyof T): void`
+  - Cycle the sort for a field: ASC -> DESC -> cleared. If a different field was sorted, starts at ASC.
+- `sort.clear(): void`
+  - Remove all sorting.
+- `sort.set(field: keyof T | null, direction: "ASC" | "DESC" | null): void`
+  - Explicitly set the sort field and direction.
+
+### Filter
+
+- `filter: UseFilterReturnType<T>`
+  - Full filter state and operations. See [useFilter reference](../useFilter/api_reference.md) for the complete API.
+
+### Pagination
+
+- `pagination.pageNo: number`
+  - Current page number (1-indexed).
+- `pagination.pageSize: number`
+  - Current number of items per page.
+- `pagination.totalPages: number`
+  - Total number of pages based on `totalItems` and `pageSize`.
+- `pagination.totalItems: number`
+  - Same as the top-level `totalItems`.
+- `pagination.canGoNext: boolean`
+  - `true` when a next page exists.
+- `pagination.canGoPrevious: boolean`
+  - `true` when a previous page exists (i.e. `pageNo > 1`).
+- `pagination.goToNext(): void`
+  - Navigate to the next page. No-op if already on the last page.
+- `pagination.goToPrevious(): void`
+  - Navigate to the previous page. No-op if already on page 1.
+- `pagination.goToPage(page: number): void`
+  - Navigate to a specific page. Clamped to `[1, totalPages]`.
+- `pagination.setPageSize(size: number): void`
+  - Change the page size. Resets to page 1.
+
+### Operations
+
+- `refetch(): Promise<ListResponseType<T>>`
+  - Manually refetch both the items and the count. Returns the list response.
+
+## Exported Constants
+
+Available from `@ram_28/kf-ai-sdk/workflow`:
+
+```typescript
+import { ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+```
+
+**ActivityTableStatus**
+
+| Key | Value | Description |
+|-----|-------|-------------|
+| `InProgress` | `"inprogress"` | Fetches the in-progress items of the current activity |
+| `Completed` | `"completed"` | Fetches the completed items of the current activity |
+
+**SortDirection** (from `@ram_28/kf-ai-sdk/table`)
+
+| Key | Value |
+|-----|-------|
+| `ASC` | `"ASC"` |
+| `DESC` | `"DESC"` |
+
+**TableDefaults** (from `@ram_28/kf-ai-sdk/table`)
+
+| Key | Value | Description |
+|-----|-------|-------------|
+| `SEARCH_DEBOUNCE_MS` | `300` | Debounce delay for search (ms) |
+| `PAGE_SIZE` | `10` | Default items per page |
+| `PAGE` | `1` | Default page number (1-indexed) |
+| `SEARCH_MAX_LENGTH` | `255` | Maximum search query length |
+
+For filter constants (`ConditionOperator`, `GroupOperator`, `RHSType`), see [useFilter reference](../useFilter/api_reference.md).
+
+## Types
+
+```typescript
+import type { ActivityInstanceType } from "@ram_28/kf-ai-sdk/workflow";
+
+// ============================================================
+// Options
+// ============================================================
+
+interface UseActivityTableOptionsType<A extends Activity<any, any, any>> {
+  activity: A;
+  status: ActivityTableStatusType;
+  initialState?: {
+    sort?: SortType;
+    pagination?: PaginationStateType;
+    filter?: UseFilterOptionsType<ActivityRowType<A>>;
+  };
+  onError?: (error: Error) => void;
+  onSuccess?: (data: ActivityRowType<A>[]) => void;
+}
+
+// ============================================================
+// Return type
+// ============================================================
+
+type UseActivityTableReturnType<A extends Activity<any, any, any>> =
+  UseTableReturnType<ActivityRowType<A>>;
+
+// ActivityRowType resolves to ActivityInstanceType<...>
+// ActivityInstanceType<TEntity, TEditable, TReadonly> provides:
+//   row._id: string                              (direct access, no .get())
+//   row.Field.get(): value                       (read field value)
+//   row.Field.set(value): void                   (editable fields only)
+//   row.Field.validate(): ValidationResultType   (single field)
+//   row.Field.label / .required / .readOnly / .defaultValue / .meta
+//   row.toJSON(): plain object
+//   row.validate(): ValidationResultType         (all fields)
+//   row.update(data): Promise                    (persist changes)
+//   row.save(data): Promise                      (commit draft)
+//   row.complete(): Promise                      (complete activity)
+//   row.progress(): Promise                      (get workflow progress)
+
+interface UseTableReturnType<T> {
+  // Data
+  rows: T[];
+  totalItems: number;
+
+  // Loading States
+  isLoading: boolean;
+  isFetching: boolean;
+
+  // Error Handling
+  error: Error | null;
+
+  // Search
+  search: {
+    query: string;
+    field: keyof T | null;
+    set: (field: keyof T, query: string) => void;
+    clear: () => void;
+  };
+
+  // Sorting
+  sort: {
+    field: keyof T | null;
+    direction: "ASC" | "DESC" | null;
+    toggle: (field: keyof T) => void;
+    clear: () => void;
+    set: (field: keyof T | null, direction: "ASC" | "DESC" | null) => void;
+  };
+
+  // Filter
+  filter: UseFilterReturnType<T>;
+
+  // Pagination
+  pagination: {
+    pageNo: number;
+    pageSize: number;
+    totalPages: number;
+    totalItems: number;
+    canGoNext: boolean;
+    canGoPrevious: boolean;
+    goToNext: () => void;
+    goToPrevious: () => void;
+    goToPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+  };
+
+  // Operations
+  refetch: () => Promise<ListResponseType<T>>;
+}
+
+// ============================================================
+// Status
+// ============================================================
+
+const ActivityTableStatus = {
+  InProgress: "inprogress",
+  Completed: "completed",
+} as const;
+
+type ActivityTableStatusType =
+  (typeof ActivityTableStatus)[keyof typeof ActivityTableStatus];
+// resolves to: "inprogress" | "completed"
+
+// ============================================================
+// Row type inference
+// ============================================================
+
+type ActivityRowType<A extends Activity<any, any, any>> =
+  A extends { getInProgressList(opts?: any): Promise<(infer R)[]> }
+    ? R
+    : never;
+
+// ============================================================
+// Activity system fields
+// ============================================================
+
+type ActivityInstanceFieldsType = {
+  _id: string;
+  BPInstanceId: string;
+  Status: "InProgress" | "Completed";
+  AssignedTo: Array<{ _id: string; _name: string }>;
+  CompletedAt: string; // ISO 8601 datetime
+};
+
+// ============================================================
+// State types
+// ============================================================
+
+interface PaginationStateType {
+  pageNo: number;
+  pageSize: number;
+}
+
+type SortOptionType = Record<string, "ASC" | "DESC">;
+type SortType = SortOptionType[];
+
+// Filter types — see useFilter reference (../useFilter/api_reference.md)
+```