@ram_28/kf-ai-sdk 2.0.15 → 2.0.17

package/docs/examples/bdo/filtered-product-table.md

@@ -0,0 +1,100 @@
+# Filtered Product Table
+
+> Filter products by category and price range using the integrated `table.filter` API.
+
+```tsx
+import { useState, useMemo } from "react";
+import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
+import type { UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
+import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
+import { BuyerProduct } from "@/bdo/buyer/Product";
+
+export default function FilteredProductTable() {
+  const product = useMemo(() => new BuyerProduct(), []);
+  const table: UseBDOTableReturnType<BuyerProduct> = useBDOTable({ bdo: product });
+
+  // ── Category filter (single EQ condition) ─────────────────────
+  const [categoryFilter, setCategoryFilter] = useState("");
+  const [categoryConditionId, setCategoryConditionId] = useState<string | null>(null);
+
+  const handleCategoryFilter = (value: string) => {
+    if (categoryConditionId) {
+      table.filter.removeCondition(categoryConditionId);
+      setCategoryConditionId(null);
+    }
+    setCategoryFilter(value);
+    if (value && value !== "all") {
+      const id = table.filter.addCondition({
+        LHSField: "Category",
+        Operator: ConditionOperator.EQ,
+        RHSType: RHSType.Constant,
+        RHSValue: value,
+      });
+      setCategoryConditionId(id);
+    }
+  };
+
+  // ── Price range filter (GTE + LTE conditions) ─────────────────
+  const [minPrice, setMinPrice] = useState("");
+  const [maxPrice, setMaxPrice] = useState("");
+  const [minPriceConditionId, setMinPriceConditionId] = useState<string | null>(null);
+  const [maxPriceConditionId, setMaxPriceConditionId] = useState<string | null>(null);
+
+  const applyPriceFilter = () => {
+    if (minPriceConditionId) { table.filter.removeCondition(minPriceConditionId); setMinPriceConditionId(null); }
+    if (maxPriceConditionId) { table.filter.removeCondition(maxPriceConditionId); setMaxPriceConditionId(null); }
+
+    if (minPrice !== "") {
+      const id = table.filter.addCondition({
+        LHSField: "Price", Operator: ConditionOperator.GTE, RHSType: RHSType.Constant, RHSValue: Number(minPrice),
+      });
+      setMinPriceConditionId(id);
+    }
+    if (maxPrice !== "") {
+      const id = table.filter.addCondition({
+        LHSField: "Price", Operator: ConditionOperator.LTE, RHSType: RHSType.Constant, RHSValue: Number(maxPrice),
+      });
+      setMaxPriceConditionId(id);
+    }
+  };
+
+  if (table.isLoading) return <p>Loading...</p>;
+
+  return (
+    <div>
+      {/* Category dropdown */}
+      <select value={categoryFilter} onChange={(e) => handleCategoryFilter(e.target.value)}>
+        <option value="all">All categories</option>
+        {product.Category.options.map((opt) => (
+          <option key={opt.value} value={opt.value}>{opt.label}</option>
+        ))}
+      </select>
+
+      {/* Price range */}
+      <input type="number" placeholder="Min" value={minPrice} onChange={(e) => setMinPrice(e.target.value)} />
+      <input type="number" placeholder="Max" value={maxPrice} onChange={(e) => setMaxPrice(e.target.value)} />
+      <button onClick={applyPriceFilter}>Apply</button>
+
+      {/* Table */}
+      <table>
+        <tbody>
+          {table.rows.map((row) => (
+            <tr key={row._id}>
+              <td>{row.Title.get()}</td>
+              <td>${row.Price.get()?.toFixed(2)}</td>
+              <td>{row.Category.get()}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+```
+
+## Key Patterns
+
+- **`addCondition()` returns an ID** -- store it in state to remove the condition later with `removeCondition(id)`
+- **Category filter** -- single `ConditionOperator.EQ` condition; remove-then-add on every change
+- **Price range** -- two separate conditions (`GTE` and `LTE`), each tracked by its own ID
+- **Filter changes auto-reset pagination** -- when conditions change, the table resets to page 1

package/docs/examples/bdo/product-listing.md

@@ -0,0 +1,73 @@
+# Product Listing
+
+> Browse products with search, sortable columns, and pagination using `useBDOTable`.
+
+```tsx
+import { useMemo } from "react";
+import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
+import type { UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
+import { BuyerProduct } from "@/bdo/buyer/Product";
+
+export default function ProductListingPage() {
+  const product = useMemo(() => new BuyerProduct(), []);
+  const table: UseBDOTableReturnType<BuyerProduct> = useBDOTable({
+    bdo: product,
+    initialState: { sort: [{ _created_at: "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>
+      {/* Search */}
+      <input
+        placeholder="Search by title..."
+        value={table.search.query}
+        onChange={(e) => table.search.set("Title", e.target.value)}
+      />
+      {table.search.query && <button onClick={table.search.clear}>Clear</button>}
+
+      {/* Table with sortable headers */}
+      <table>
+        <thead>
+          <tr>
+            <th onClick={() => table.sort.toggle("Title")} style={{ cursor: "pointer" }}>
+              {product.Title.label}
+              {table.sort.field === "Title" && (table.sort.direction === "ASC" ? " ↑" : " ↓")}
+            </th>
+            <th onClick={() => table.sort.toggle("Price")} style={{ cursor: "pointer" }}>
+              {product.Price.label}
+              {table.sort.field === "Price" && (table.sort.direction === "ASC" ? " ↑" : " ↓")}
+            </th>
+            <th>{product.Category.label}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {table.rows.map((row) => (
+            <tr key={row._id}>
+              <td>{row.Title.get()}</td>
+              <td>${row.Price.get()?.toFixed(2)}</td>
+              <td>{row.Category.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
+
+- **`row.Field.get()`** -- rows are `ItemType` proxies; always use `.get()` to read values
+- **`search.set(field, query)`** -- updates the input instantly, debounces the API call (300ms)
+- **`sort.toggle(field)`** -- cycles ASC → DESC → cleared on each click
+- **Pagination** -- `canGoNext`/`canGoPrevious` disable buttons at boundaries; `pageNo`, `totalPages` for display

package/docs/examples/bdo/supplier-dropdown.md

@@ -0,0 +1,60 @@
+# Supplier Dropdown
+
+> Lazy-load ReferenceField options when the dropdown opens using `useQuery`.
+
+```tsx
+import { useState, useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useBDOForm } from "@ram_28/kf-ai-sdk/form";
+import type { UseBDOFormReturnType } from "@ram_28/kf-ai-sdk/form/types";
+import { BuyerProduct } from "@/bdo/buyer/Product";
+import type { ProductSupplierRefType } from "@/bdo/buyer/Product";
+
+export default function SupplierDropdown({ recordId }: { recordId?: string }) {
+  const [dropdownOpen, setDropdownOpen] = useState(false);
+  const product = useMemo(() => new BuyerProduct(), []);
+
+  const { watch, setValue, item }: UseBDOFormReturnType<BuyerProduct> = useBDOForm({ bdo: product, recordId });
+
+  // Lazy-load options only when dropdown opens and item has an _id
+  const { data: suppliers = [], isFetching } = useQuery<ProductSupplierRefType[]>({
+    queryKey: ["supplier-options", item._id],
+    queryFn: () => product.SupplierInfo.fetchOptions(item._id!),
+    enabled: dropdownOpen && !!item._id,
+    staleTime: Infinity,
+  });
+
+  const currentSupplier = watch(product.SupplierInfo.id);
+
+  return (
+    <div>
+      <label>{product.SupplierInfo.label}</label>
+      <select
+        value={currentSupplier?._id ?? ""}
+        onFocus={() => setDropdownOpen(true)}
+        onChange={(e) => {
+          const supplier = suppliers.find((s) => s._id === e.target.value);
+          if (supplier) setValue(product.SupplierInfo.id, supplier);
+        }}
+      >
+        <option value="">{currentSupplier?.SupplierName ?? "Select supplier"}</option>
+        {isFetching ? (
+          <option disabled>Loading...</option>
+        ) : (
+          suppliers.map((s) => (
+            <option key={s._id} value={s._id}>{s.SupplierName}</option>
+          ))
+        )}
+      </select>
+    </div>
+  );
+}
+```
+
+## Key Patterns
+
+- **`enabled: dropdownOpen && !!item._id`** -- options aren't fetched until the dropdown opens and the draft/record has an ID
+- **`fetchOptions(instanceId)`** -- loads reference options for the current record context
+- **`watch()` + `setValue()`** -- reads/writes the entire reference object (`{ _id, SupplierName }`)
+- **`referenceFields`** -- `product.SupplierInfo.referenceFields` lists the fields fetched from the referenced BDO
+- **`staleTime: Infinity`** -- options are cached and not refetched on re-focus

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)