@ram_28/kf-ai-sdk 2.0.16 → 2.0.17

package/docs/useActivityForm/README.md

@@ -0,0 +1,241 @@
+# useActivityForm
+
+Form hook for workflow activities with automatic per-field sync and a single `handleSubmit` to complete the activity and advance the workflow.
+
+## When to Use
+
+**Use `useActivityForm` when:**
+
+- Building a form for a workflow activity (employee leave request, manager approval, etc.)
+- You need `handleSubmit` to complete the activity and advance the workflow
+- Fields from prior activities should appear as readonly context
+
+**Use something else when:**
+
+- Building a BDO record form — use [`useBDOForm`](../useBDOForm/README.md) instead
+- Listing activity instances in a table — use [`useActivityTable`](../useActivityTable/README.md) instead
+
+## Imports
+
+```tsx
+import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
+```
+
+## Quick Start
+
+```tsx
+import { useMemo } from "react";
+import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
+import { EmployeeInputActivity } from "@/workflow/leave";
+
+function LeaveRequestForm({ instanceId }: { instanceId: string }) {
+  const activity = useMemo(() => new EmployeeInputActivity(), []);
+
+  const { register, handleSubmit, errors, isLoading, isSubmitting } =
+    useActivityForm(activity, { activity_instance_id: instanceId });
+
+  if (isLoading) return <p>Loading...</p>;
+
+  return (
+    <form>
+      <label>{activity.StartDate.label}</label>
+      <input type="date" {...register(activity.StartDate.id)} />
+      {errors.StartDate && <p>{errors.StartDate.message}</p>}
+
+      <label>{activity.EndDate.label}</label>
+      <input type="date" {...register(activity.EndDate.id)} />
+      {errors.EndDate && <p>{errors.EndDate.message}</p>}
+
+      <button type="button" disabled={isSubmitting}
+        onClick={handleSubmit(() => {}, console.error)}>
+        Submit Request
+      </button>
+    </form>
+  );
+}
+```
+
+## Usage Guide
+
+### Registering Fields
+
+Use the Activity instance's field to get the field ID, label, and metadata — never hardcode field names as strings.
+
+```tsx
+<label>{activity.StartDate.label} {activity.StartDate.required && <span>*</span>}</label>
+<input type="date" {...register(activity.StartDate.id)} />
+{errors.StartDate && <p>{errors.StartDate.message}</p>}
+```
+
+For **select, reference, boolean, and other custom components** that don't fire native change events, use `watch()` + `setValue()` instead of `register()`:
+
+```tsx
+<Select
+  value={watch(activity.LeaveType.id) ?? ""}
+  onValueChange={(v) => setValue(activity.LeaveType.id, v)}
+>
+  <SelectTrigger>
+    <SelectValue placeholder="Select leave type" />
+  </SelectTrigger>
+  <SelectContent>
+    {activity.LeaveType.options.map((opt) => (
+      <SelectItem key={opt.value} value={opt.value}>
+        {opt.label}
+      </SelectItem>
+    ))}
+  </SelectContent>
+</Select>
+```
+
+Readonly fields are auto-disabled by `register()` — no manual disable needed.
+
+### Context-Derived Readonly Fields
+
+When a workflow has multiple activities, fields from prior activities appear as readonly context. The hook discovers them automatically from BP metadata, and `register()` returns `{ disabled: true }` for them.
+
+In a manager approval form, the employee's StartDate, EndDate, LeaveType, and LeaveDays are readonly context, while ManagerApproved and ManagerReason are editable:
+
+```tsx
+import { useMemo } from "react";
+import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
+import { ManagerApprovalActivity } from "@/workflow/leave";
+
+function ManagerApprovalForm({ instanceId }: { instanceId: string }) {
+  const activity = useMemo(() => new ManagerApprovalActivity(), []);
+
+  const { register, handleSubmit, errors, isLoading, isSubmitting, watch, setValue } =
+    useActivityForm(activity, { activity_instance_id: instanceId });
+
+  if (isLoading) return <p>Loading...</p>;
+
+  return (
+    <div>
+      {/* Readonly context from employee's activity — auto-disabled */}
+      <label>{activity.StartDate.label}</label>
+      <input type="date" {...register(activity.StartDate.id)} className="bg-gray-100" />
+
+      <label>{activity.EndDate.label}</label>
+      <input type="date" {...register(activity.EndDate.id)} className="bg-gray-100" />
+
+      <label>{activity.LeaveDays.label}</label>
+      <input type="number" {...register(activity.LeaveDays.id)} className="bg-gray-100" />
+
+      {/* Editable manager decision fields */}
+      <div>
+        <input
+          type="checkbox"
+          checked={watch(activity.ManagerApproved.id) ?? false}
+          onChange={(e) => setValue(activity.ManagerApproved.id, e.target.checked)}
+        />
+        <label>
+          {activity.ManagerApproved.label}
+          {activity.ManagerApproved.required && <span> *</span>}
+        </label>
+        {errors.ManagerApproved && <p>{errors.ManagerApproved.message}</p>}
+      </div>
+
+      <label>{activity.ManagerReason.label}</label>
+      <textarea {...register(activity.ManagerReason.id)} rows={3} />
+      {errors.ManagerReason && <p>{errors.ManagerReason.message}</p>}
+
+      <button type="button" disabled={isSubmitting}
+        onClick={handleSubmit(() => {}, console.error)}>
+        Complete Review
+      </button>
+    </div>
+  );
+}
+```
+
+### Validation
+
+Validation happens automatically. The hook validates field types, constraints (required, length, integerPart/fractionPart), and backend expression rules — all without any manual configuration.
+
+Errors appear in `errors.FieldName.message`:
+
+```tsx
+{errors.StartDate && <p>{errors.StartDate.message}</p>}
+```
+
+### Handling Submit
+
+Per-field sync automatically saves changes on blur/change via `activity.update()`, so there's no need for a manual save button. When the user is ready, `handleSubmit` validates the form, sends any remaining dirty fields, then completes the activity to advance the workflow.
+
+`handleSubmit` is curried: `(onSuccess?, onError?) => (event?) => Promise<void>`.
+
+- **`onSuccess(result)`** — Called with `CreateUpdateResponseType` (`{ _id: string }`) after the activity is completed.
+- **`onError(error)`** — Called with `FieldErrors` (validation failure) or `Error` (API failure).
+
+```tsx
+<button type="button" disabled={isSubmitting}
+  onClick={handleSubmit(() => { toast.success("Submitted"); onClose(); }, console.error)}>
+  Submit Request
+</button>
+```
+
+To validate before showing a confirmation dialog, use `trigger()`:
+
+```tsx
+const handleSubmitWithConfirm = async () => {
+  const valid = await trigger();
+  if (!valid) return;
+  // Show confirmation UI, then invoke:
+  handleSubmit(onSuccess, onError)(); // note the double invocation — curried
+};
+```
+
+> **Don't** call `activity.update()` or `activity.complete()` manually — `handleSubmit` does it for you.
+
+### Working with `item`
+
+`item` represents the current activity instance. Each field on `item` is an accessor with methods to read, write, and validate that field's value.
+
+**Instance-level members:**
+
+```tsx
+const { item } = useActivityForm(activity, { activity_instance_id: instanceId });
+
+item._id;              // current activity instance ID
+item.toJSON();         // all form values as plain object
+await item.validate(); // trigger validation for all fields
+```
+
+**Field-level accessors** (`item.FieldName`):
+
+```tsx
+// Read/write
+item.StartDate.get();                // current value
+item.LeaveDays.getOrDefault(0);      // value or fallback
+item.StartDate.set("2026-03-01");    // update value
+
+// Validate
+item.StartDate.validate();           // { valid: boolean, errors: string[] }
+
+// Metadata
+item.StartDate.label;                // display label
+item.StartDate.required;             // is required?
+item.StartDate.readOnly;             // is readonly?
+```
+
+**When to use `item` vs `register`/`watch`/`setValue`:**
+
+- Use `register()` for standard HTML inputs (text, number, date)
+- Use `watch()` + `setValue()` for custom components (select, checkbox, reference)
+- Use `item.Field.get()` / `item.Field.set()` for programmatic read/write (event handlers, computed logic)
+
+## Further Reading
+
+- [API Reference](./api_reference.md) — All options, return values, and type definitions
+- [Submit Leave Request](../examples/workflow/submit-leave-request.md) — Employee form submission
+- [Approve Leave Request](../examples/workflow/approve-leave-request.md) — Manager approval with readonly context
+- [Start New Workflow](../examples/workflow/start-new-workflow.md) — `workflow.start()` flow
+
+## Common Mistakes
+
+- **Don't forget `useMemo` on the Activity.** `new ActivityClass()` must be wrapped in `useMemo(() => ..., [])`. Re-creating the instance on every render breaks the hook.
+- **Don't create a manual save button.** Per-field sync handles auto-saving on blur/change. `handleSubmit` is for completing the activity, not saving drafts.
+- **Don't set date `defaultValues` to empty string.** Use `undefined` instead. Empty strings cause type validation errors for Date and DateTime fields.
+- **Don't use `register()` for select, checkbox, or reference components.** They don't fire native change events. Use `watch()` + `setValue()`.
+- **Don't call `activity.update()` or `activity.complete()` manually.** `handleSubmit` handles the API calls. Calling them yourself will double-submit.
+- **Don't render the form before `isLoading` is false.** The activity data and metadata are being fetched. Guard with `if (isLoading) return <Loading />`.
+- **Don't forget `activity_instance_id` is required.** This is the activity instance ID (from `workflow.start()` or `getInProgressList()`), not a BDO record ID.

package/docs/useActivityForm/api_reference.md

@@ -0,0 +1,279 @@
+# useActivityForm API Reference
+
+```tsx
+import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
+import type {
+  UseActivityFormOptions,
+  UseActivityFormReturn,
+} from "@ram_28/kf-ai-sdk/workflow";
+```
+
+## Signature
+
+```tsx
+const form: UseActivityFormReturn<EmployeeInputActivity> = useActivityForm(
+  activity: EmployeeInputActivity,
+  options: UseActivityFormOptions<EmployeeInputActivity>,
+);
+```
+
+First argument is the Activity instance (positional). Second argument is the options object.
+
+## Options
+
+`UseActivityFormOptions<A>`
+
+- `activity_instance_id: string`
+  - **Required**
+  - Activity instance ID. From `workflow.start()` response or `getInProgressList()` rows.
+- `defaultValues?: Partial<ExtractActivityEditable<A>>`
+  - **Optional** · Defaults to `{}`
+  - Initial form values before server data loads. Server data wins on merge.
+- `mode?: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all"`
+  - **Optional** · Defaults to `"onBlur"`
+  - RHF validation mode. Also controls when per-field server sync fires.
+- `enabled?: boolean`
+  - **Optional** · Defaults to `true`
+  - Set `false` to defer `activity.read()` until the instance ID is available.
+
+## Return Value
+
+`UseActivityFormReturn<A>`
+
+### Instance
+
+- `item: FormItemType<TEditable, TReadonly>`
+  - The current activity instance. Each field is an accessor with methods to read, write, and validate. See [Instance and Field Accessors](#instance-and-field-accessors).
+- `activity: A`
+  - The Activity instance passed to the hook.
+
+### Form Methods
+
+- `register: FormRegisterType<TEditable, TReadonly>`
+  - Registers an input field. Auto-disables readonly fields (`{ disabled: true }`).
+- `handleSubmit: HandleSubmitType<CreateUpdateResponseType>`
+  - Validates, updates any remaining dirty fields, then completes the activity. See [handleSubmit](#handlesubmit).
+- `watch: UseFormWatch<AllActivityFields<A>>`
+  - Standard RHF `watch`. Typed to all fields (editable + readonly).
+- `setValue: UseFormSetValue<ExtractActivityEditable<A>>`
+  - Standard RHF `setValue`. Typed to editable fields only.
+- `getValues: UseFormGetValues<AllActivityFields<A>>`
+  - Returns all field values.
+- `reset: UseFormReset<AllActivityFields<A>>`
+  - Resets form to given values or defaults.
+- `trigger: UseFormTrigger<AllActivityFields<A>>`
+  - Manually triggers validation for specific or all fields.
+- `control: Control<AllActivityFields<A>>`
+  - RHF control for `Controller` components.
+
+### Form State
+
+- `errors: FieldErrors<AllActivityFields<A>>`
+  - Validation errors by field name. Each entry has `type` and `message`.
+- `isValid: boolean`
+  - `true` if all fields pass validation.
+- `isDirty: boolean`
+  - `true` if any field has been modified.
+- `isSubmitting: boolean`
+  - `true` during `handleSubmit` (from button click to API response).
+- `isSubmitSuccessful: boolean`
+  - `true` after the last submission succeeded.
+
+### Loading & Error
+
+- `isLoading: boolean`
+  - `true` during initial data + metadata loading. Guard form render on this.
+- `isMetadataLoading: boolean`
+  - `true` while BP metadata is being fetched.
+- `loadError: Error | null`
+  - Error from `activity.read()`.
+- `hasError: boolean`
+  - `true` when `loadError` is non-null.
+
+### Other
+
+- `bpMetadata: Record<string, unknown> | null`
+  - Raw BP metadata blob. `null` while loading.
+- `clearErrors: () => void`
+  - Clear all form validation errors.
+
+## handleSubmit
+
+```typescript
+type HandleSubmitType<TRead> = (
+  onSuccess?: (data: TRead, e?: React.BaseSyntheticEvent) => void | Promise<void>,
+  onError?: (error: FieldErrors | Error, e?: React.BaseSyntheticEvent) => void | Promise<void>,
+) => (e?: React.BaseSyntheticEvent) => Promise<void>;
+```
+
+Curried function. Pass to an `onClick` handler: `onClick={handleSubmit(onSuccess, onError)}`.
+
+**Behavior:**
+1. Validates all fields via the resolver (type + constraint).
+2. Collects dirty, non-readonly fields and sends them via `activity.update()`.
+3. Calls `activity.complete()` to advance the workflow.
+4. Invokes `onSuccess` with the complete response.
+
+- `onSuccess(result, e?)`
+  - Called with `CreateUpdateResponseType` (`{ _id: string }`) after the activity is completed and the workflow advances.
+- `onError(error, e?)`
+  - Called with `FieldErrors` if validation fails, or `Error` if the API call fails.
+
+If no dirty fields exist, the update call is skipped but `complete()` is still called.
+
+> Per-field sync handles auto-saving on blur/change. `handleSubmit` is for completing the activity, not saving drafts.
+
+## Instance and Field Accessors
+
+`item` represents the current activity instance. Each field on `item` is an accessor object.
+
+### Instance Members (`item`)
+
+- `_id: string | undefined`
+  - Current activity instance ID.
+- `toJSON(): Partial<TEditable & TReadonly>`
+  - All form values as a plain object.
+- `validate(): Promise<boolean>`
+  - Triggers validation for all fields. Returns `true` if valid.
+
+### Editable Field (`item.FieldName`)
+
+- `get(): T | undefined`
+  - Current value from form state.
+- `getOrDefault(fallback: T): T`
+  - Value or fallback if null/undefined.
+- `set(value: T): void`
+  - Sets the field value.
+- `validate(): ValidationResultType`
+  - Validates the current value. Returns `{ valid: boolean, errors: string[] }`.
+- `label: string`
+  - Display label from field metadata.
+- `required: boolean`
+  - Whether the field is required.
+- `readOnly: boolean`
+  - Always `false` for editable fields.
+- `defaultValue: unknown`
+  - Default value from metadata.
+- `meta: BaseFieldMetaType`
+  - Raw field metadata.
+
+### Readonly Field (`item.FieldName`)
+
+Same as editable except: no `set()` method, `readOnly` is always `true`.
+
+## Types
+
+```typescript
+// ---- Generic extraction helpers ----
+
+type ExtractActivityEntity<A> =
+  A extends Activity<infer E, any, any> ? E : never;
+
+type ExtractActivityEditable<A> =
+  A extends Activity<any, infer E, any> ? E : never;
+
+type ExtractActivityReadonly<A> =
+  A extends Activity<any, any, infer R> ? R : never;
+
+type AllActivityFields<A> =
+  ExtractActivityEditable<A> & ExtractActivityReadonly<A>;
+
+// ---- Hook options ----
+
+interface UseActivityFormOptions<A extends Activity<any, any, any>> {
+  activity_instance_id: string;
+  defaultValues?: Partial<ExtractActivityEditable<A>>;
+  mode?: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
+  enabled?: boolean;
+}
+
+// ---- Hook return type ----
+
+interface UseActivityFormReturn<A extends Activity<any, any, any>> {
+  item: FormItemType<ExtractActivityEditable<A>, ExtractActivityReadonly<A>>;
+  activity: A;
+
+  register: FormRegisterType<ExtractActivityEditable<A>, ExtractActivityReadonly<A>>;
+  handleSubmit: HandleSubmitType<CreateUpdateResponseType>;
+  watch: UseFormWatch<AllActivityFields<A>>;
+  setValue: UseFormSetValue<ExtractActivityEditable<A>>;
+  getValues: UseFormGetValues<AllActivityFields<A>>;
+  reset: UseFormReset<AllActivityFields<A>>;
+  trigger: UseFormTrigger<AllActivityFields<A>>;
+  control: Control<AllActivityFields<A>>;
+
+  errors: FieldErrors<AllActivityFields<A>>;
+  isValid: boolean;
+  isDirty: boolean;
+  isSubmitting: boolean;
+  isSubmitSuccessful: boolean;
+
+  isLoading: boolean;
+  isMetadataLoading: boolean;
+  loadError: Error | null;
+  hasError: boolean;
+
+  bpMetadata: Record<string, unknown> | null;
+  clearErrors: () => void;
+}
+
+// ---- Shared types ----
+
+type HandleSubmitType<TRead = unknown> = (
+  onSuccess?: (
+    data: TRead,
+    e?: React.BaseSyntheticEvent,
+  ) => void | Promise<void>,
+  onError?: (
+    error: FieldErrors | Error,
+    e?: React.BaseSyntheticEvent,
+  ) => void | Promise<void>,
+) => (e?: React.BaseSyntheticEvent) => Promise<void>;
+
+type FormRegisterType<TEditable, TReadonly> = <
+  K extends keyof TEditable | keyof TReadonly | string
+>(
+  name: K & string,
+  options?: RegisterOptions,
+) => K extends keyof TReadonly
+  ? UseFormRegisterReturn & { disabled: true }
+  : UseFormRegisterReturn;
+
+type FormItemType<TEditable, TReadonly> = {
+  [K in keyof TEditable]: EditableFormFieldAccessorType<TEditable[K]>;
+} & {
+  [K in keyof TReadonly]: ReadonlyFormFieldAccessorType<TReadonly[K]>;
+} & {
+  readonly _id: string | undefined;
+  toJSON(): Partial<TEditable & TReadonly>;
+  validate(): Promise<boolean>;
+};
+
+interface EditableFormFieldAccessorType<T> {
+  readonly label: string;
+  readonly required: boolean;
+  readonly readOnly: false;
+  readonly defaultValue: unknown;
+  readonly meta: BaseFieldMetaType;
+  get(): T | undefined;
+  getOrDefault(fallback: T): T;
+  set(value: T): void;
+  validate(): ValidationResultType;
+}
+
+interface ReadonlyFormFieldAccessorType<T> {
+  readonly label: string;
+  readonly required: boolean;
+  readonly readOnly: true;
+  readonly defaultValue: unknown;
+  readonly meta: BaseFieldMetaType;
+  get(): T | undefined;
+  getOrDefault(fallback: T): T;
+  validate(): ValidationResultType;
+}
+
+interface ValidationResultType {
+  valid: boolean;
+  errors: string[];
+}
+```