@ram_28/kf-ai-sdk 2.0.16 → 2.0.18

package/docs/examples/fields/primitive-fields.md

@@ -0,0 +1,217 @@
+# Primitive Fields
+
+> Complete form demonstrating all primitive field types with the correct form binding pattern for each: String, Number, Boolean, Date, DateTime, and Text.
+
+```tsx
+import { useMemo } from "react";
+import { useBDOForm } from "@ram_28/kf-ai-sdk/form";
+import type { UseBDOFormReturnType } from "@ram_28/kf-ai-sdk/form/types";
+import { AdminFieldTest } from "@/bdo/admin/FieldTest";
+import {
+  Field,
+  FieldContent,
+  FieldLabel,
+  FieldError,
+} from "@/components/ui/field";
+import { Input } from "@/components/ui/input";
+import { Checkbox } from "@/components/ui/checkbox";
+
+export default function PrimitiveFieldsForm({ recordId }: { recordId?: string }) {
+  const fieldTest = useMemo(() => new AdminFieldTest(), []);
+
+  const {
+    register,
+    handleSubmit,
+    errors,
+    watch,
+    setValue,
+    isLoading,
+    isSubmitting,
+  }: UseBDOFormReturnType<AdminFieldTest> = useBDOForm({
+    bdo: fieldTest,
+    recordId,
+  });
+
+  if (isLoading) return <p>Loading...</p>;
+
+  return (
+    <form onSubmit={handleSubmit((data) => console.log("Saved", data._id))}>
+      {/* ───────────────────────────────────────────────── */}
+      {/* StringField — register() for native text inputs  */}
+      {/* ───────────────────────────────────────────────── */}
+      <Field>
+        <FieldLabel>
+          {fieldTest.Name.label} {fieldTest.Name.required && <span>*</span>}
+        </FieldLabel>
+        <FieldContent>
+          <Input
+            {...register(fieldTest.Name.id)}
+            maxLength={fieldTest.Name.length}
+            placeholder="Enter name"
+          />
+          {fieldTest.Name.length && (
+            <span className="text-xs text-gray-500">
+              Max {fieldTest.Name.length} characters
+            </span>
+          )}
+        </FieldContent>
+        {errors.Name && <FieldError>{errors.Name.message}</FieldError>}
+      </Field>
+
+      {/* ───────────────────────────────────────────────── */}
+      {/* NumberField — register() with type="number"      */}
+      {/* Derive step from fractionPart                    */}
+      {/* ───────────────────────────────────────────────── */}
+      <Field>
+        <FieldLabel>
+          {fieldTest.Amount.label} {fieldTest.Amount.required && <span>*</span>}
+        </FieldLabel>
+        <FieldContent>
+          <Input
+            type="number"
+            step={
+              fieldTest.Amount.fractionPart
+                ? `0.${"0".repeat(fieldTest.Amount.fractionPart - 1)}1`
+                : "1"
+            }
+            {...register(fieldTest.Amount.id)}
+            placeholder="0.00"
+          />
+          <span className="text-xs text-gray-500">
+            IntegerPart: {fieldTest.Amount.integerPart}, FractionPart: {fieldTest.Amount.fractionPart ?? "none"}
+          </span>
+        </FieldContent>
+        {errors.Amount && <FieldError>{errors.Amount.message}</FieldError>}
+      </Field>
+
+      {/* Integer-only number (no fractionPart → step="1") */}
+      <Field>
+        <FieldLabel>{fieldTest.Quantity.label}</FieldLabel>
+        <FieldContent>
+          <Input
+            type="number"
+            step="1"
+            {...register(fieldTest.Quantity.id)}
+            placeholder="0"
+          />
+        </FieldContent>
+        {errors.Quantity && <FieldError>{errors.Quantity.message}</FieldError>}
+      </Field>
+
+      {/* ───────────────────────────────────────────────── */}
+      {/* BooleanField — watch() + setValue(), NOT register */}
+      {/* Checkbox doesn't fire native change events       */}
+      {/* ───────────────────────────────────────────────── */}
+      <Field>
+        <div className="flex items-center gap-3">
+          <Checkbox
+            id={fieldTest.IsEnabled.id}
+            checked={watch(fieldTest.IsEnabled.id) ?? false}
+            onCheckedChange={(checked) =>
+              setValue(fieldTest.IsEnabled.id, checked === true)
+            }
+          />
+          <FieldLabel htmlFor={fieldTest.IsEnabled.id}>
+            {fieldTest.IsEnabled.label}
+          </FieldLabel>
+        </div>
+      </Field>
+
+      {/* ───────────────────────────────────────────────── */}
+      {/* DateField — register() with type="date"          */}
+      {/* Strict YYYY-MM-DD — never default to ""          */}
+      {/* ───────────────────────────────────────────────── */}
+      <Field>
+        <FieldLabel>
+          {fieldTest.StartDate.label} {fieldTest.StartDate.required && <span>*</span>}
+        </FieldLabel>
+        <FieldContent>
+          <Input type="date" {...register(fieldTest.StartDate.id)} />
+        </FieldContent>
+        {errors.StartDate && <FieldError>{errors.StartDate.message}</FieldError>}
+      </Field>
+
+      {/* ───────────────────────────────────────────────── */}
+      {/* DateTimeField — register() with datetime-local   */}
+      {/* Add step for Millisecond precision               */}
+      {/* ───────────────────────────────────────────────── */}
+      <Field>
+        <FieldLabel>{fieldTest.CreatedOn.label}</FieldLabel>
+        <FieldContent>
+          <Input
+            type="datetime-local"
+            step={fieldTest.CreatedOn.precision === "Millisecond" ? "0.001" : undefined}
+            {...register(fieldTest.CreatedOn.id)}
+          />
+          <span className="text-xs text-gray-500">
+            Precision: {fieldTest.CreatedOn.precision}
+          </span>
+        </FieldContent>
+        {errors.CreatedOn && <FieldError>{errors.CreatedOn.message}</FieldError>}
+      </Field>
+
+      {/* ───────────────────────────────────────────────── */}
+      {/* TextField — register() with <textarea>           */}
+      {/* Conditional rendering based on format            */}
+      {/* ───────────────────────────────────────────────── */}
+      <Field>
+        <FieldLabel>{fieldTest.Description.label}</FieldLabel>
+        <FieldContent>
+          <textarea
+            {...register(fieldTest.Description.id)}
+            rows={4}
+            placeholder="Enter plain text description"
+            className="flex w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm"
+          />
+          <span className="text-xs text-gray-500">
+            Format: {fieldTest.Description.format}
+          </span>
+        </FieldContent>
+        {errors.Description && <FieldError>{errors.Description.message}</FieldError>}
+      </Field>
+
+      {/* Markdown text field — use a markdown editor */}
+      <Field>
+        <FieldLabel>{fieldTest.RichContent.label}</FieldLabel>
+        <FieldContent>
+          {fieldTest.RichContent.format === "Markdown" ? (
+            <textarea
+              {...register(fieldTest.RichContent.id)}
+              rows={6}
+              placeholder="Enter markdown content..."
+              className="flex w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm font-mono"
+            />
+          ) : (
+            <textarea
+              {...register(fieldTest.RichContent.id)}
+              rows={4}
+              className="flex w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm"
+            />
+          )}
+          <span className="text-xs text-gray-500">
+            Format: {fieldTest.RichContent.format}
+          </span>
+        </FieldContent>
+        {errors.RichContent && <FieldError>{errors.RichContent.message}</FieldError>}
+      </Field>
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? "Saving..." : "Save"}
+      </button>
+    </form>
+  );
+}
+```
+
+## Key Patterns
+
+- **`register()` works for** String, Number, Date, DateTime, Text — native HTML inputs that fire change events
+- **`watch()` + `setValue()` needed for** Boolean — Checkbox components don't fire native change events, so `register()` won't pick up value changes
+- **Constraint-derived getters**:
+  - `field.length` — max characters (StringField)
+  - `field.integerPart` / `field.fractionPart` — numeric precision (NumberField)
+  - `field.precision` — `"Second"` or `"Millisecond"` (DateTimeField)
+  - `field.format` — `"Plain"` or `"Markdown"` (TextField)
+- **Never default Date/DateTime to empty string** — Use `undefined` for unset dates. Empty strings (`""`) fail DateField validation (`YYYY-MM-DD` regex) and produce confusing errors
+- **Derive `step` from `fractionPart`** — `fractionPart: 2` → `step="0.01"`, no `fractionPart` → `step="1"` (integer only)
+- **Conditional rendering for TextField** — Check `field.format` to switch between `<textarea>` and a markdown editor

package/docs/examples/workflow/approve-leave-request.md

@@ -0,0 +1,76 @@
+# Approve Leave Request
+
+> Manager reviews readonly employee data and approves/rejects using `useActivityForm`.
+
+```tsx
+import { useMemo } from "react";
+import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
+import type { UseActivityFormReturn } from "@ram_28/kf-ai-sdk/workflow";
+import { ManagerApprovalActivity } from "@/workflow/leave";
+
+export default function ApprovalForm({ instanceId, onClose }: { instanceId: string; onClose: () => void }) {
+  const activity = useMemo(() => new ManagerApprovalActivity(), []);
+
+  const { register, handleSubmit, errors, isLoading, isSubmitting, watch, setValue }: UseActivityFormReturn<ManagerApprovalActivity> =
+    useActivityForm(activity, { activity_instance_id: instanceId, mode: "onBlur" });
+
+  if (isLoading) return <p>Loading...</p>;
+
+  return (
+    <div>
+      {/* Readonly context fields — auto-disabled by register() */}
+      <div>
+        <label>{activity.EmployeeName.label}</label>
+        <input {...register(activity.EmployeeName.id)} className="bg-gray-100" />
+      </div>
+      <div>
+        <label>{activity.StartDate.label}</label>
+        <input type="date" {...register(activity.StartDate.id)} className="bg-gray-100" />
+      </div>
+      <div>
+        <label>{activity.EndDate.label}</label>
+        <input type="date" {...register(activity.EndDate.id)} className="bg-gray-100" />
+      </div>
+      <div>
+        <label>{activity.LeaveDays.label}</label>
+        <input type="number" {...register(activity.LeaveDays.id)} className="bg-gray-100" />
+      </div>
+
+      <hr />
+
+      {/* 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>
+
+      <div>
+        <label>{activity.ManagerReason.label}</label>
+        <textarea {...register(activity.ManagerReason.id)} rows={3} placeholder="Reason for approval or rejection..." />
+        {errors.ManagerReason && <p>{errors.ManagerReason.message}</p>}
+      </div>
+
+      <button onClick={onClose}>Cancel</button>
+      <button disabled={isSubmitting} onClick={handleSubmit(() => onClose(), console.error)}>
+        {watch(activity.ManagerApproved.id) ? "Approve" : "Reject"} & Submit
+      </button>
+    </div>
+  );
+}
+```
+
+## Key Patterns
+
+- **Readonly context fields** -- fields from the prior employee activity have `ReadOnly: true` and are auto-disabled by `register()`
+- **Editable decision fields** -- `ManagerApproved` and `ManagerReason` are the only editable fields
+- **Checkbox with `watch()` + `setValue()`** -- booleans use `e.target.checked`, not `e.target.value`
+- **Dynamic submit label** -- `watch(activity.ManagerApproved.id)` drives the button text
+- **`handleSubmit` completes the approval** -- validates, syncs remaining fields, then completes the activity

package/docs/examples/workflow/filtered-activity-table.md

@@ -0,0 +1,101 @@
+# Filtered Activity Table
+
+> Filter activity instances by date range using `useActivityTable` with the integrated `table.filter` API.
+
+```tsx
+import { useState, useMemo } from "react";
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+import type { UseActivityTableReturnType } from "@ram_28/kf-ai-sdk/workflow";
+import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
+import { EmployeeInputActivity } from "@/workflow/leave";
+
+export default function FilteredActivityTable() {
+  const activity = useMemo(() => new EmployeeInputActivity(), []);
+  const table: UseActivityTableReturnType<EmployeeInputActivity> = useActivityTable({ activity, status: ActivityTableStatus.InProgress });
+
+  // ── Date range filter on StartDate ─────────────────────────────
+  const [startDateFrom, setStartDateFrom] = useState("");
+  const [startDateTo, setStartDateTo] = useState("");
+  const [fromConditionId, setFromConditionId] = useState<string | null>(null);
+  const [toConditionId, setToConditionId] = useState<string | null>(null);
+
+  const applyDateFilter = () => {
+    if (fromConditionId) { table.filter.removeCondition(fromConditionId); setFromConditionId(null); }
+    if (toConditionId) { table.filter.removeCondition(toConditionId); setToConditionId(null); }
+
+    if (startDateFrom) {
+      const id = table.filter.addCondition({
+        LHSField: activity.StartDate.id,
+        Operator: ConditionOperator.GTE,
+        RHSType: RHSType.Constant,
+        RHSValue: startDateFrom,
+      });
+      setFromConditionId(id);
+    }
+    if (startDateTo) {
+      const id = table.filter.addCondition({
+        LHSField: activity.StartDate.id,
+        Operator: ConditionOperator.LTE,
+        RHSType: RHSType.Constant,
+        RHSValue: startDateTo,
+      });
+      setToConditionId(id);
+    }
+  };
+
+  const clearDateFilter = () => {
+    if (fromConditionId) { table.filter.removeCondition(fromConditionId); setFromConditionId(null); }
+    if (toConditionId) { table.filter.removeCondition(toConditionId); setToConditionId(null); }
+    setStartDateFrom("");
+    setStartDateTo("");
+  };
+
+  if (table.isLoading) return <p>Loading...</p>;
+
+  return (
+    <div>
+      {/* Date range filter */}
+      <div>
+        <label>From</label>
+        <input type="date" value={startDateFrom} onChange={(e) => setStartDateFrom(e.target.value)} />
+        <label>To</label>
+        <input type="date" value={startDateTo} onChange={(e) => setStartDateTo(e.target.value)} />
+        <button onClick={applyDateFilter}>Apply</button>
+        {table.filter.hasConditions && <button onClick={clearDateFilter}>Clear</button>}
+      </div>
+
+      {/* Table */}
+      <table>
+        <thead>
+          <tr>
+            <th>{activity.StartDate.label}</th>
+            <th>{activity.EndDate.label}</th>
+            <th>{activity.LeaveType.label}</th>
+            <th>{activity.LeaveDays.label}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {table.rows.map((row) => (
+            <tr key={row._id}>
+              <td>{row.StartDate.get()}</td>
+              <td>{row.EndDate.get()}</td>
+              <td>{row.LeaveType.get()}</td>
+              <td>{row.LeaveDays.get()}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      <span>Page {table.pagination.pageNo} of {table.pagination.totalPages}</span>
+    </div>
+  );
+}
+```
+
+## Key Patterns
+
+- **Date range with GTE + LTE** -- two separate conditions tracked by their own IDs
+- **`addCondition()` returns an ID** -- store it to later remove the condition with `removeCondition(id)`
+- **`table.filter.hasConditions`** -- show a "Clear" button only when filters are active
+- **Filter changes auto-reset pagination** -- the table resets to page 1 when conditions change
+- **Same filter API as `useBDOTable`** -- `table.filter` works identically in both BDO and Activity tables

package/docs/examples/workflow/my-pending-requests.md

@@ -0,0 +1,90 @@
+# My Pending Requests
+
+> Employee views leave requests in In Progress / Completed tabs using `useActivityTable`.
+
+```tsx
+import { useState, useMemo } from "react";
+import { useActivityTable, ActivityTableStatus } from "@ram_28/kf-ai-sdk/workflow";
+import type { UseActivityTableReturnType } from "@ram_28/kf-ai-sdk/workflow";
+import { EmployeeInputActivity } from "@/workflow/leave";
+
+export default function MyPendingRequests({ onOpenForm }: { onOpenForm: (instanceId: string, bpInstanceId: string) => void }) {
+  const [status, setStatus] = useState(ActivityTableStatus.InProgress);
+  const activity = useMemo(() => new EmployeeInputActivity(), []);
+
+  const table: UseActivityTableReturnType<EmployeeInputActivity> = useActivityTable({
+    activity,
+    status,
+    initialState: { sort: [{ StartDate: "DESC" }], pagination: { pageNo: 1, pageSize: 10 } },
+  });
+
+  if (table.isLoading) return <p>Loading...</p>;
+  if (table.error) return <p>Error: {table.error.message}</p>;
+
+  return (
+    <div>
+      {/* Tab switcher */}
+      <div>
+        <button onClick={() => setStatus(ActivityTableStatus.InProgress)}
+          style={{ fontWeight: status === ActivityTableStatus.InProgress ? "bold" : "normal" }}>
+          My Requests
+        </button>
+        <button onClick={() => setStatus(ActivityTableStatus.Completed)}
+          style={{ fontWeight: status === ActivityTableStatus.Completed ? "bold" : "normal" }}>
+          Completed
+        </button>
+      </div>
+
+      <table>
+        <thead>
+          <tr>
+            <th onClick={() => table.sort.toggle(activity.StartDate.id)} style={{ cursor: "pointer" }}>
+              {activity.StartDate.label}
+            </th>
+            <th>{activity.EndDate.label}</th>
+            <th>{activity.LeaveType.label}</th>
+            <th>{activity.LeaveDays.label}</th>
+            <th>Status</th>
+            {status === ActivityTableStatus.Completed && <th>Completed At</th>}
+          </tr>
+        </thead>
+        <tbody>
+          {table.rows.map((row) => (
+            <tr
+              key={row._id}
+              style={{ cursor: status === ActivityTableStatus.InProgress ? "pointer" : "default" }}
+              onClick={() => {
+                if (status === ActivityTableStatus.InProgress) {
+                  onOpenForm(row._id, row.BPInstanceId.get());
+                }
+              }}
+            >
+              <td>{row.StartDate.get()}</td>
+              <td>{row.EndDate.get()}</td>
+              <td>{row.LeaveType.get()}</td>
+              <td>{row.LeaveDays.get()}</td>
+              <td>{row.Status.get()}</td>
+              {status === ActivityTableStatus.Completed && <td>{row.CompletedAt.get()}</td>}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      {/* Pagination */}
+      <div>
+        <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>
+    </div>
+  );
+}
+```
+
+## Key Patterns
+
+- **`ActivityTableStatus.InProgress` / `Completed`** -- changing `status` state triggers an automatic refetch
+- **Activity system fields** -- `row.Status.get()`, `row.CompletedAt.get()`, `row.BPInstanceId.get()` are available on every row
+- **Conditional `CompletedAt` column** -- only rendered in the Completed tab
+- **Clickable rows only in InProgress** -- completed rows are read-only and don't open a form dialog
+- **`row.BPInstanceId.get()`** -- passed along when opening a form, needed for workflow progress tracking

package/docs/examples/workflow/start-new-workflow.md

@@ -0,0 +1,47 @@
+# Start New Workflow
+
+> "New Request" button calls `workflow.start()` and opens the form with the returned instance ID.
+
+```tsx
+import { useState, useMemo, useCallback } from "react";
+import { Workflow } from "@ram_28/kf-ai-sdk/workflow";
+import type { WorkflowStartResponseType } from "@ram_28/kf-ai-sdk/workflow";
+import type { EmployeeInputEntityType } from "@/workflow/leave";
+
+export default function StartNewWorkflow({ onOpenForm }: { onOpenForm: (instanceId: string, bpInstanceId: string) => void }) {
+  const [isStarting, setIsStarting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const workflow = useMemo(() => new Workflow<EmployeeInputEntityType>("SimpleLeaveProcess"), []);
+
+  const handleNewRequest = useCallback(async () => {
+    try {
+      setIsStarting(true);
+      setError(null);
+      const result: WorkflowStartResponseType = await workflow.start();
+      // result: { BPInstanceId, ActivityId, _id }
+      onOpenForm(result._id, result.BPInstanceId);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to start workflow");
+    } finally {
+      setIsStarting(false);
+    }
+  }, [workflow, onOpenForm]);
+
+  return (
+    <div>
+      <button onClick={handleNewRequest} disabled={isStarting}>
+        {isStarting ? "Starting..." : "New Request"}
+      </button>
+      {error && <p>{error}</p>}
+    </div>
+  );
+}
+```
+
+## Key Patterns
+
+- **`workflow.start()`** -- creates a new process instance and returns `{ BPInstanceId, ActivityId, _id }`
+- **`BPInstanceId`** -- identifies the workflow instance; used for `workflow.progress()`
+- **`_id`** -- the first activity instance ID; passed to `useActivityForm` as `activity_instance_id`
+- **Workflow constructor** -- `new Workflow<TEntity>("BusinessProcessId")` takes the process ID string

package/docs/examples/workflow/submit-leave-request.md

@@ -0,0 +1,72 @@
+# Submit Leave Request
+
+> Employee fills in dates, leave type, and reason, then submits using `useActivityForm`.
+
+```tsx
+import { useMemo } from "react";
+import { useActivityForm } from "@ram_28/kf-ai-sdk/workflow";
+import type { UseActivityFormReturn } from "@ram_28/kf-ai-sdk/workflow";
+import { EmployeeInputActivity } from "@/workflow/leave";
+
+export default function LeaveRequestForm({ instanceId, onClose }: { instanceId: string; onClose: () => void }) {
+  const activity = useMemo(() => new EmployeeInputActivity(), []);
+
+  const { register, handleSubmit, errors, isLoading, isSubmitting, watch, setValue }: UseActivityFormReturn<EmployeeInputActivity> =
+    useActivityForm(activity, { activity_instance_id: instanceId, mode: "onBlur" });
+
+  if (isLoading) return <p>Loading...</p>;
+
+  return (
+    <form>
+      <div>
+        <label>{activity.StartDate.label} {activity.StartDate.required && <span>*</span>}</label>
+        <input type="date" {...register(activity.StartDate.id)} />
+        {errors.StartDate && <p>{errors.StartDate.message}</p>}
+      </div>
+
+      <div>
+        <label>{activity.EndDate.label} {activity.EndDate.required && <span>*</span>}</label>
+        <input type="date" {...register(activity.EndDate.id)} />
+        {errors.EndDate && <p>{errors.EndDate.message}</p>}
+      </div>
+
+      {/* Select field — watch/setValue, not register */}
+      <div>
+        <label>{activity.LeaveType.label} {activity.LeaveType.required && <span>*</span>}</label>
+        <select value={watch(activity.LeaveType.id) ?? ""} onChange={(e) => setValue(activity.LeaveType.id, e.target.value)}>
+          <option value="">Select leave type</option>
+          {activity.LeaveType.options.map((opt) => (
+            <option key={opt.value} value={opt.value}>{opt.label}</option>
+          ))}
+        </select>
+        {errors.LeaveType && <p>{errors.LeaveType.message}</p>}
+      </div>
+
+      <div>
+        <label>{activity.Reason.label}</label>
+        <textarea {...register(activity.Reason.id)} rows={3} placeholder="Reason for leave..." />
+        {errors.Reason && <p>{errors.Reason.message}</p>}
+      </div>
+
+      {/* Readonly computed field — auto-disabled by register() */}
+      <div>
+        <label>{activity.LeaveDays.label} (computed)</label>
+        <input type="number" {...register(activity.LeaveDays.id)} />
+      </div>
+
+      <button type="button" onClick={onClose}>Cancel</button>
+      <button type="button" disabled={isSubmitting} onClick={handleSubmit(() => onClose(), console.error)}>
+        Submit Request
+      </button>
+    </form>
+  );
+}
+```
+
+## Key Patterns
+
+- **`useActivityForm(activity, { activity_instance_id })`** -- the instance ID comes from `workflow.start()` or a table row
+- **`handleSubmit` completes the activity** -- validates, sends dirty fields, then completes to advance the workflow
+- **Readonly fields auto-disabled** -- `LeaveDays` has `ReadOnly: true`, so `register()` returns `{ disabled: true }`
+- **`watch()` + `setValue()` for selects** -- custom components that don't fire native change events
+- **Per-field sync** -- changes are auto-saved on blur/change; no manual save button needed

package/docs/examples/workflow/workflow-progress.md

@@ -0,0 +1,49 @@
+# Workflow Progress
+
+> Display progress badges for each activity in a workflow instance using `workflow.progress()`.
+
+```tsx
+import { useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { Workflow } from "@ram_28/kf-ai-sdk/workflow";
+import type { ActivityProgressType } from "@ram_28/kf-ai-sdk/workflow";
+import type { EmployeeInputEntityType } from "@/workflow/leave";
+
+export default function WorkflowProgressBadges({ bpInstanceId }: { bpInstanceId: string }) {
+  const workflow = useMemo(() => new Workflow<EmployeeInputEntityType>("SimpleLeaveProcess"), []);
+
+  const { data: progress } = useQuery<ActivityProgressType[]>({
+    queryKey: ["workflow-progress", bpInstanceId],
+    queryFn: () => workflow.progress(bpInstanceId),
+    staleTime: 0,
+  });
+
+  if (!progress) return null;
+
+  return (
+    <div style={{ display: "flex", gap: "8px" }}>
+      {progress.map((entry: ActivityProgressType) => (
+        <span
+          key={entry.ActivityId}
+          style={{
+            padding: "4px 12px",
+            borderRadius: "12px",
+            fontSize: "12px",
+            backgroundColor: entry.Status === "COMPLETED" ? "#dcfce7" : "#fef9c3",
+            color: entry.Status === "COMPLETED" ? "#166534" : "#854d0e",
+          }}
+        >
+          {entry._name} — {entry.Status === "COMPLETED" ? "Done" : "In Progress"}
+        </span>
+      ))}
+    </div>
+  );
+}
+```
+
+## Key Patterns
+
+- **`workflow.progress(bpInstanceId)`** -- returns `ActivityProgressType[]`, one entry per activity in the process
+- **`ActivityProgressType`** -- each entry has `ActivityId`, `_name`, `Status` (`"COMPLETED"` or `"IN_PROGRESS"`), `CompletedAt`, `CompletedBy`
+- **`BPInstanceId`** -- comes from `workflow.start()` (new requests) or `row.BPInstanceId.get()` (existing table rows)
+- **`staleTime: 0`** -- always refetch progress when the component mounts (progress changes as activities complete)