@ram_28/kf-ai-sdk 2.0.15 → 2.0.16

package/docs/bdo.md

@@ -125,7 +125,7 @@ product.product_name.defaultValue  // unknown
 
 | Class | Extra Getters | Notes |
 |-------|--------------|-------|
-| `StringField` | `length` | May have `Constraint.Enum` — see useForm Mistake #3 |
+| `StringField` | `length` | May have `Constraint.Enum` — see useBDOForm Mistake #3 |
 | `NumberField` | `integerPart`, `fractionPart` | |
 | `BooleanField` | — | |
 | `DateField` | — | Format: YYYY-MM-DD |

package/docs/gaps.md

@@ -91,9 +91,9 @@ When an Item field is Image or File type, the accessor gets enriched with attach
 
 ---
 
-## docs/useForm.md
+## docs/useBDOForm.md
 
-### 6. `UseFormOptionsType` missing 3 feature flags
+### 6. `UseBDOFormOptionsType` missing 3 feature flags
 
 All three variants of the options type are missing these properties:
 
@@ -103,9 +103,9 @@ enableConstraintValidation?: boolean;   // default: true (required, length, etc.
 enableExpressionValidation?: boolean;   // default: true (backend expression rules)
 ```
 
-**Source**: `sdk/components/hooks/useForm/types.ts` lines 90-123
+**Source**: `sdk/components/hooks/useBDOForm/types.ts` lines 90-123
 
-### 7. `UseFormReturnType` missing ~half its properties
+### 7. `UseBDOFormReturnType` missing ~half its properties
 
 These properties are returned by the hook but not in the doc:
 
@@ -123,7 +123,7 @@ These properties are returned by the hook but not in the doc:
 | `draftId` | `string \| undefined` |
 | `isCreatingDraft` | `boolean` |
 
-**Source**: `sdk/components/hooks/useForm/types.ts` lines 190-232, `sdk/components/hooks/useForm/useForm.ts` lines 320-352
+**Source**: `sdk/components/hooks/useBDOForm/types.ts` lines 190-232, `sdk/components/hooks/useBDOForm/useBDOForm.ts` lines 320-352
 
 ### 8. `handleSubmit` behavior is wrong — doc says `bdo.create()`/`bdo.update()`, actual uses `api()` directly
 
@@ -138,7 +138,7 @@ result = await api(bdo.meta._id).draft(filteredData);
 result = await api(bdo.meta._id).update(recordId!, filteredData);
 ```
 
-**Source**: `sdk/components/hooks/useForm/useForm.ts` lines 296-301
+**Source**: `sdk/components/hooks/useBDOForm/useBDOForm.ts` lines 296-301
 
 ### 9. Draft mode is completely undocumented
 
@@ -151,7 +151,7 @@ The entire draft-based creation flow is absent from the doc:
 5. `isLoading` reflects `isCreatingDraft` state
 6. `draftId` and `isCreatingDraft` are returned
 
-**Source**: `sdk/components/hooks/useForm/useForm.ts` lines 125-138, 186-190, 222-261, 296-298
+**Source**: `sdk/components/hooks/useBDOForm/useBDOForm.ts` lines 125-138, 186-190, 222-261, 296-298
 
 ---
 
@@ -185,41 +185,7 @@ The complete example at line 121 has the same broken import, so the entire examp
 
 ## docs/useActivityTable.md
 
-### 11. `ActivityRowType` has `{ ADO: E }` but API returns flat data
-
-The type definition wraps entity fields under `ADO`:
-```typescript
-// sdk/components/hooks/useActivityTable/types.ts
-type ActivityRowType<A> = ActivityInstanceFieldsType & { ADO: E }
-```
-
-But the API returns flat data (no `ADO` wrapper):
-```typescript
-// sdk/workflow/Activity.ts
-async getInProgressList(): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>>
-```
-
-`useActivityTable` passes raw API data to `useTable` with **no transformation** — so runtime data is flat. All doc examples using `row.ADO.StartDate` may fail at runtime.
-
-**Source**: `sdk/components/hooks/useActivityTable/types.ts` lines 22-25, `sdk/workflow/Activity.ts` line 130, `sdk/components/hooks/useActivityTable/index.ts` lines 19-40
-
-### 12. Search, sort, filter, and pagination are non-functional
-
-The backend currently only supports GET for activity list/metric endpoints. The `_options` parameter (underscore prefix = unused) is ignored in all four methods:
-
-```typescript
-// sdk/workflow/client.ts
-// TODO: Backend currently only supports GET for list/metric endpoints.
-async inProgressList(_options?: ListOptionsType): Promise<...> {
-  const response = await fetch(`${url}/inprogress/list`, {
-    method: "GET",  // NOT POST — options are ignored
-    headers: getDefaultHeaders(),
-  });
-```
-
-The doc presents search, sort, filter, and pagination as working features with full examples, but none of these have any effect on the data returned.
-
-**Source**: `sdk/workflow/client.ts` lines 112-164
+*No remaining critical gaps — #11 (GET endpoints ignoring options) was resolved when list/metric endpoints were switched to POST.*
 
 ---
 
@@ -349,25 +315,9 @@ Also missing from the "ActivityInstance System Fields Reference" table at the bo
 
 **Source**: `sdk/workflow/types.ts` lines 49-55
 
-### 21. `getInProgressList()` / `getCompletedList()` return flat data, not ADO-nested
-
-Doc examples use `item.ADO.StartDate` — this would fail at runtime. The API returns `ActivityInstanceFieldsType & TEntity` (flat):
-
-```typescript
-// Correct access
-item.StartDate   // not item.ADO.StartDate
-
-// The ADO nesting only exists in ActivityRowType (useActivityTable hook type)
-// NOT in the raw getInProgressList() / getCompletedList() responses
-```
-
-**Source**: `sdk/workflow/Activity.ts` line 130
-
-### 22. List/metric endpoints use GET, not POST — options are ignored
-
-Same issue as #12. The doc's "Filtering Reference" section claims POST with `ListOptionsType` body works. It does not — all four methods use GET and ignore options.
+### ~~21. List/metric endpoints use GET, not POST — options are ignored~~
 
-**Source**: `sdk/workflow/client.ts` lines 112-164
+**RESOLVED**: All four list/metric endpoints now use POST with proper request bodies. Count methods construct `{ Type: "Metric", Metric: [{Field: "_id", Type: "Count"}] }` and transform the response correctly.
 
 ### 23. `activity.Field.meta.label` and `activity.Field.meta.id` don't exist
 
@@ -401,10 +351,10 @@ This affects **every** `register()` call and `<label>` in the doc's examples —
 |-----|---------------|
 | api.md | 2 |
 | bdo.md | 3 |
-| useForm.md | 4 |
+| useBDOForm.md | 4 |
 | useBDOTable.md | 1 |
-| useActivityTable.md | 2 |
+| useActivityTable.md | 0 (resolved) |
 | useFilter.md | 2 |
 | useAuth.md | 5 |
-| workflow.md | 4 |
-| **Total** | **23** |
+| workflow.md | 2 |
+| **Total** | **19** |

package/docs/useActivityForm.md

@@ -0,0 +1,393 @@
+# useActivityForm
+
+React hook for building forms bound to workflow activity input fields. Integrates with `react-hook-form`.
+
+## Imports
+
+```typescript
+import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
+import type {
+  UseActivityFormOptions,
+  UseActivityFormReturn,
+} from "@ram_28/kf-ai-sdk/workflow";
+import type { FieldErrors } from "react-hook-form";
+```
+
+---
+
+## Common Mistakes (READ FIRST)
+
+### 1. Passing a Workflow instead of an Activity
+
+`useActivityForm` takes an **Activity** instance, not a Workflow.
+
+```typescript
+// ❌ WRONG — passing a workflow
+const wf = new SimpleLeaveProcess();
+useActivityForm(wf, options);
+
+// ✅ CORRECT — get the typed activity from the workflow
+const activity = useMemo(() => new SimpleLeaveProcess().employeeInputActivity(), []);
+useActivityForm(activity, options);
+```
+
+### 2. Forgetting to memoize the activity instance
+
+Activity instances must be stable across renders, or the hook will re-fetch metadata on every render.
+
+```typescript
+// ❌ WRONG — new instance on every render
+const activity = new SimpleLeaveProcess().employeeInputActivity();
+useActivityForm(activity, options);
+
+// ✅ CORRECT — memoize with useMemo
+const activity = useMemo(() => new SimpleLeaveProcess().employeeInputActivity(), []);
+useActivityForm(activity, options);
+```
+
+### 3. Using handleSubmit instead of handleComplete to finish an activity
+
+`handleSubmit` saves the form data but does NOT complete the activity. Use `handleComplete` to save AND complete.
+
+```typescript
+// ❌ WRONG — only saves, does not complete
+<button onClick={handleSubmit(onSuccess, onError)}>Submit Leave Request</button>
+
+// ✅ CORRECT — saves AND completes the activity
+<button onClick={handleComplete(onSuccess, onError)}>Submit Leave Request</button>
+
+// ✅ ALSO CORRECT — save as draft (intentionally not completing)
+<button onClick={handleSubmit(onSaveSuccess, onError)}>Save Draft</button>
+```
+
+### 4. Calling `.get()` on form item fields
+
+Form item fields from `useActivityForm` follow the same accessor pattern as `useBDOForm`. Use `.get()` to read values programmatically, but prefer `watch()` for rendering.
+
+```tsx
+// ❌ WRONG — renders [object Object]
+<span>{item.StartDate}</span>
+
+// ✅ CORRECT — use .get() for programmatic access
+const startDate = item.StartDate.get();
+
+// ✅ CORRECT — use watch() for reactive rendering in JSX
+<span>{watch(activity.StartDate.id)}</span>
+```
+
+---
+
+## Type Definitions
+
+### UseActivityFormOptions\<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;
+}
+```
+
+---
+
+## handleSubmit vs handleComplete
+
+| | `handleSubmit` | `handleComplete` |
+|---|---|---|
+| **Saves dirty fields** | Yes | Yes |
+| **Completes the activity** | No | Yes |
+| **Use case** | Save draft / intermediate save | Final submission |
+
+Both validate the form before executing. Both only send dirty (changed) fields to the API.
+
+---
+
+## 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 |
+
+---
+
+## Example: Employee Leave Request Form
+
+```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>
+  );
+}
+```
+
+---
+
+## Example: Manager Approval Form
+
+```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>
+  );
+}
+```