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

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

package/docs/useActivityForm/README.md

@@ -1,244 +0,0 @@
-# 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()` (see [Fields — Selection & Reference](../fields/README.md#selection--reference-fields) for full patterns):
-
-```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
-- [Fields](../fields/README.md) — All 13 field classes, constraint getters, and attachment methods
-- [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
-- [Primitive Fields](../examples/fields/primitive-fields.md) — Form with String, Number, Boolean, Date, DateTime, Text
-- [Complex Fields](../examples/fields/complex-fields.md) — Form with Select, Reference, User, File, Image
-
-## 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.