@ram_28/kf-ai-sdk 2.0.19 → 2.0.20-beta.1

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

@@ -1,90 +0,0 @@
-# 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

@@ -1,47 +0,0 @@
-# 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

@@ -1,72 +0,0 @@
-# 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

@@ -1,49 +0,0 @@
-# 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)

package/docs/fields/README.md

@@ -1,141 +0,0 @@
-# Fields
-
-Field classes are the typed metadata layer for BDO properties. 13 classes extend `BaseField<T>`, each storing raw backend meta and exposing getters + `validate()`.
-
-## Imports
-
-```typescript
-import {
-  StringField,
-  NumberField,
-  BooleanField,
-  DateField,
-  DateTimeField,
-  TextField,
-  SelectField,
-  ReferenceField,
-  UserField,
-  FileField,
-  ImageField,
-  ArrayField,
-  ObjectField,
-} from "@ram_28/kf-ai-sdk/bdo";
-import type {
-  StringFieldType,
-  NumberFieldType,
-  BooleanFieldType,
-  DateFieldType,
-  DateTimeFieldType,
-  TextFieldType,
-  SelectFieldType,
-  ReferenceFieldType,
-  UserFieldType,
-  FileFieldType,
-  ImageFieldType,
-  FileType,
-  ArrayFieldType,
-  ObjectFieldType,
-} from "@ram_28/kf-ai-sdk/types";
-```
-
-## Common Mistakes (READ FIRST)
-
-1. **`item.Title` is not the value** — Use `item.Title.get()` to read, `.set()` to write.
-2. **Don't confuse `StringField` (class) with `StringFieldType` (type alias)** — Different modules.
-3. **`fetchOptions()` requires a parent BDO** — Standalone fields will throw.
-4. **SelectField meta `Type` is `"String"`** — `Constraint.Enum` differentiates it.
-5. **Always use pre-built components for File/Image** — `<FileUpload>`, `<ImageUpload>`, `<FilePreview>`, `<ImageThumbnail>`.
-
-## Quick Start
-
-```typescript
-// Declare on a BDO class
-readonly Title = new StringField({
-  _id: "Title", Name: "Title", Type: "String",
-  Constraint: { Required: true, Length: 255 },
-});
-
-// Access metadata
-bdo.Title.id;       // "Title"
-bdo.Title.label;    // "Title"
-bdo.Title.required; // true
-bdo.Title.length;   // 255
-
-// Read/write via Item proxy
-const item = await bdo.get("abc123");
-item.Title.get();      // "My Product"
-item.Title.set("New"); // update
-
-// Form binding
-<input {...register(bdo.Title.id)} />
-```
-
-## BaseField Contract
-
-All fields share these getters: `id`, `label`, `readOnly`, `required`, `defaultValue`, `primaryKey`, `meta`.
-
-Abstract method: `validate(value: T | undefined): ValidationResultType` → `{ valid, errors }`.
-
-## Quick Reference
-
-| Class                  | Value Type         | Extra Getters                                     | Async            |
-| ---------------------- | ------------------ | ------------------------------------------------- | ---------------- |
-| `StringField`          | `string`           | `length`                                          | —                |
-| `NumberField`          | `number`           | `integerPart`, `fractionPart`                     | —                |
-| `BooleanField`         | `boolean`          | —                                                 | —                |
-| `DateField`            | `YYYY-MM-DD`       | —                                                 | —                |
-| `DateTimeField`        | ISO string         | `precision`                                       | —                |
-| `TextField`            | `string`           | `format`                                          | —                |
-| `SelectField<T>`       | `T`                | `options`                                         | `fetchOptions()` |
-| `ReferenceField<TRef>` | `TRef`             | `referenceBdo`, `referenceFields`, `searchFields` | `fetchOptions()` |
-| `UserField`            | `{ _id, _name }`   | `businessEntity`                                  | `fetchOptions()` |
-| `FileField`            | `FileType[]`       | —                                                 | —                |
-| `ImageField`           | `FileType \| null` | —                                                 | —                |
-| `ArrayField<T>`        | `T[]`              | `elementType`                                     | —                |
-| `ObjectField<T>`       | `T`                | `properties`                                      | —                |
-
-## Form Binding Patterns
-
-| Field Type | Pattern                                   | Key Detail                                                                     |
-| ---------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
-| String     | `register()`                              | `maxLength={field.length}`                                                     |
-| Number     | `register()` with `type="number"`         | `step` from `fractionPart` (e.g. `2` → `"0.01"`, none → `"1"`)                 |
-| Boolean    | `watch()` + `setValue()`                  | Checkboxes don't fire native change — never use `register()`                   |
-| Date       | `register()` with `type="date"`           | Strict `YYYY-MM-DD` — never default to `""`                                    |
-| DateTime   | `register()` with `type="datetime-local"` | `step="0.001"` for `"Millisecond"` precision — never default to `""`           |
-| Text       | `register()` with `<textarea>`            | Check `field.format` (`"Plain"` \| `"Markdown"`) for conditional rendering     |
-| Select     | `watch()` + `setValue()`                  | Static `field.options` from `Constraint.Enum`, or dynamic via `fetchOptions()` |
-| Reference  | `watch()` + `setValue()`                  | Stores **full object**, not just ID — use `<ReferenceSelect>` component        |
-| User       | `watch()` + `setValue()`                  | `{ _id, _name }` shape — use `fetchOptions()` + dropdown                       |
-| File       | Component only                            | `<FileUpload>` (edit) / `<FilePreview>` (read-only)                            |
-| Image      | Component only                            | `<ImageUpload>` (edit) / `<ImageThumbnail>` (read-only)                        |
-
-## fetchOptions() Pattern
-
-SelectField, ReferenceField, and UserField share this pattern:
-
-```tsx
-const [dropdownOpen, setDropdownOpen] = useState(false);
-const { data: options = [] } = useQuery({
-  queryKey: ["options", bdo.meta._id, field.id, item._id],
-  queryFn: () => field.fetchOptions(item._id!),
-  enabled: dropdownOpen && !!item._id,
-  staleTime: Infinity,
-});
-```
-
-## UI Components
-
-| Component           | Field     | Mode      | Key Props                                         |
-| ------------------- | --------- | --------- | ------------------------------------------------- |
-| `<ReferenceSelect>` | Reference | Edit      | `bdoField`, `instanceId`, `value`, `onChange`     |
-| `<FileUpload>`      | File      | Edit      | `field`, `value`, `boId`, `instanceId`, `fieldId` |
-| `<ImageUpload>`     | Image     | Edit      | `field`, `value`, `boId`, `instanceId`, `fieldId` |
-| `<FilePreview>`     | File      | Read-only | `boId`, `instanceId`, `fieldId`, `value`          |
-| `<ImageThumbnail>`  | Image     | Read-only | `boId`, `instanceId`, `fieldId`, `value`          |
-
-## Further Reading
-
-- [API Reference](./api_reference.md) — Type signatures for BaseField and all 13 classes
-- [Primitive Fields](../examples/fields/primitive-fields.md) · [Complex Fields](../examples/fields/complex-fields.md)
-- [BDO](../bdo/README.md) · [useBDOForm](../useBDOForm/README.md)

package/docs/fields/api_reference.md

@@ -1,134 +0,0 @@
-# Fields API Reference
-
-```typescript
-import { StringField, NumberField, BooleanField, DateField, DateTimeField,
-  TextField, SelectField, ReferenceField, UserField,
-  FileField, ImageField, ArrayField, ObjectField } from "@ram_28/kf-ai-sdk/bdo";
-import type { BaseFieldMetaType, ValidationResultType, SelectOptionType,
-  EditableFieldAccessorType, ReadonlyFieldAccessorType } from "@ram_28/kf-ai-sdk/bdo/types";
-import type { StringFieldType, NumberFieldType, BooleanFieldType,
-  DateFieldType, DateTimeFieldType, TextFieldType, SelectFieldType,
-  ReferenceFieldType, UserFieldType, FileFieldType, ImageFieldType, FileType,
-  ArrayFieldType, ObjectFieldType } from "@ram_28/kf-ai-sdk/types";
-```
-
-## BaseField\<T\>
-
-Abstract base class for all field definitions. Constructor: `new(meta: BaseFieldMetaType)`.
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `id` | `string` | `meta._id` |
-| `label` | `string` | `meta.Name` (falls back to `id`) |
-| `readOnly` | `boolean` | `meta.ReadOnly ?? false` |
-| `required` | `boolean` | `meta.Constraint?.Required ?? meta.Required ?? false` |
-| `defaultValue` | `unknown` | `meta.DefaultValue ?? meta.Constraint?.DefaultValue` |
-| `primaryKey` | `boolean` | `meta.Constraint?.PrimaryKey ?? false` |
-| `meta` | `BaseFieldMetaType` | Full raw backend meta |
-| `validate()` | `(value: T \| undefined) => ValidationResultType` | Abstract — overridden per subclass |
-
-## All Fields
-
-| Class | Meta Type | Extra Properties | validate() |
-|-------|-----------|-----------------|------------|
-| `StringField` | `StringFieldMetaType` | `length: number \| undefined` | Rejects non-string |
-| `NumberField` | `NumberFieldMetaType` | `integerPart: number` (default 9), `fractionPart: number \| undefined` | Rejects NaN, non-number |
-| `BooleanField` | `BooleanFieldMetaType` | — | Rejects non-boolean |
-| `DateField` | `DateFieldMetaType` | — | Rejects non-`YYYY-MM-DD`, invalid dates |
-| `DateTimeField` | `DateTimeFieldMetaType` | `precision: "Second" \| "Millisecond"` | Rejects unparseable date strings |
-| `TextField` | `TextFieldMetaType` | `format: "Plain" \| "Markdown"` | Rejects non-string |
-| `SelectField<T>` | `SelectFieldMetaType` | `options: readonly SelectOptionType<T>[]` | Rejects values not in options (skipped if empty) |
-| `ReferenceField<TRef>` | `ReferenceFieldMetaType` | `referenceBdo: string`, `referenceFields: readonly string[]`, `searchFields: readonly string[]` | Rejects non-object, missing `_id` |
-| `UserField` | `UserFieldMetaType` | `businessEntity: string \| undefined` | Rejects non-object, missing `_id` |
-| `FileField` | `FileFieldMetaType` | — | Rejects non-array, items without `_id` |
-| `ImageField` | `ImageFieldMetaType` | — | Rejects non-object, missing `_id`/`FileName` |
-| `ArrayField<T>` | `ArrayFieldMetaType` | `elementType: BaseFieldMetaType \| undefined` | Rejects non-array |
-| `ObjectField<T>` | `ObjectFieldMetaType` | `properties: Record<string, unknown> \| undefined` | Rejects non-object, arrays |
-
-All validate() methods accept `undefined` and `null`.
-
-## Async Methods
-
-| Class | Method | Signature |
-|-------|--------|-----------|
-| `SelectField<T>` | `fetchOptions` | `(instanceId?: string) => Promise<SelectOptionType<T>[]>` |
-| `ReferenceField<TRef>` | `fetchOptions` | `(instanceId?: string) => Promise<TRef[]>` |
-| `UserField` | `fetchOptions` | `(instanceId?: string) => Promise<UserFieldType[]>` |
-
-`instanceId` defaults to `"draft"`. Requires field to be bound to a parent BDO.
-
-## Types
-
-### SelectOptionType\<T\>
-
-```typescript
-interface SelectOptionType<T = string> {
-  value: T;
-  label: string;
-  disabled?: boolean;
-}
-```
-
-### FileType
-
-```typescript
-interface FileType {
-  _id: string;
-  _name: string;
-  FileName: string;
-  FileExtension: string;
-  Size: number;
-  ContentType: string;
-}
-```
-
-### ValidationResultType
-
-```typescript
-interface ValidationResultType {
-  valid: boolean;
-  errors: string[];
-}
-```
-
-### Runtime Accessor Types
-
-```typescript
-interface EditableFieldAccessorType<T> {
-  get(): T | undefined;
-  getOrDefault(fallback: T): T;
-  set(value: T): void;
-  validate(): ValidationResultType;
-  readonly label: string;
-  readonly required: boolean;
-  readonly readOnly: boolean;
-  readonly defaultValue: unknown;
-  readonly meta: BaseFieldMetaType;
-}
-
-// ReadonlyFieldAccessorType<T> — same but no set()
-```
-
-### Value Type Aliases
-
-| Type | Resolves To |
-|------|-------------|
-| `StringFieldType` | `string` |
-| `TextFieldType` | `string` |
-| `NumberFieldType` | `number` |
-| `BooleanFieldType` | `boolean` |
-| `DateFieldType` | `YYYY-MM-DD` (template literal) |
-| `DateTimeFieldType` | `YYYY-MM-DDThh:mm:ssZ` (template literal) |
-| `SelectFieldType<T>` | `T` |
-| `ReferenceFieldType<TRef>` | `TRef` |
-| `UserFieldType` | `{ _id: string; _name: string }` |
-| `ImageFieldType` | `FileType \| null` |
-| `FileFieldType` | `FileType[]` |
-| `ArrayFieldType<T>` | `T[]` |
-| `ObjectFieldType<T>` | `T` |
-
-### Supported File Extensions
-
-**Image fields** — jpg, jpeg, png, gif, webp, bmp, tiff, tif, heic, heif
-
-**File fields** — all image extensions plus: mp4, mov, avi, webm, mkv, m4v, wmv, flv, pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, zip