@ram_28/kf-ai-sdk 2.0.28 → 2.0.29

package/docs/bdo/README.md

@@ -25,6 +25,26 @@ import type { ListOptionsType } from "@ram_28/kf-ai-sdk/api/types";
    ```typescript
    const product = useMemo(() => new AdminProduct(), []);
    ```
+5. **`Filter` must be `ConditionGroupType`** — Always wrap conditions in `{ Operator: "And", Condition: [...] }`. Never pass a flat condition:
+   ```typescript
+   // ❌ WRONG — flat ConditionType causes TS2322
+   await product.list({ Filter: { Operator: "EQ", LHSField: "Category", RHSValue: "Electronics" } });
+   // ✅ CORRECT — ConditionGroupType wrapper
+   await product.list({ Filter: { Operator: "And", Condition: [
+     { Operator: "EQ", LHSField: "Category", RHSValue: "Electronics", RHSType: "Constant" }
+   ] } });
+   ```
+6. **Use `PageSize` and `Page`, not `Take` or `Limit`** — `ListOptionsType` uses `PageSize` (number of items per page) and `Page` (1-indexed page number).
+7. **Never spread ItemType proxies.** `list()`, `get()`, and `create()` return proxied `ItemType` objects. Spreading `{ ...item, extraProp }` copies enumerable keys but destroys the proxy — `.get()` and `.set()` stop working. Instead, wrap in a container object:
+   ```typescript
+   // ❌ WRONG — proxy is destroyed, .get() fails at runtime
+   const enriched = items.map(item => ({ ...item, extra: fetchedData }));
+   enriched[0].Title.get(); // TypeError: get is not a function
+
+   // ✅ CORRECT — proxy preserved in container
+   const enriched = items.map(item => ({ entry: item, extra: fetchedData }));
+   enriched[0].entry.Title.get(); // works
+   ```
 
 ## Quick Start
 

package/docs/fields/README.md

@@ -64,8 +64,11 @@ This applies to ALL field types: `StringField.get()` → `string | undefined`, `
 2. **`.get()` returns `T | undefined`** — Always null-guard before passing to `new Date()`, `format()`, template literals, or typed function parameters. See section above.
 3. **Don't confuse `StringField` (class) with `StringFieldType` (type alias)** — Different modules.
 4. **`fetchOptions()` requires a parent BDO** — Standalone fields will throw.
-5. **SelectField meta `Type` is `"String"`** — `Constraint.Enum` differentiates it.
+5. **SelectField meta `Type` is `"String"`** — `Constraint.Enum` differentiates it. Only `SelectField` has the `.options` getter. `StringField` (even with an enum constraint) does NOT have `.options` — you must hardcode the enum values from the BDO file.
 6. **Always use pre-built components for File/Image** — `<FileUpload>`, `<ImageUpload>`, `<FilePreview>`, `<ImageThumbnail>`.
+7. **`<ImageUpload>` / `<FileUpload>` ONLY work with `ImageField` / `FileField`** — Never use them for `TextField` or `StringField`, even if the field name contains "image" or "file". A `TextField` named `image_urls` is still a text field — render it with `<Textarea>` or `<Input>`, not `<ImageUpload>`. Determine the component from the **field class** in the BDO file, not the field name.
+8. **`<ImageUpload>` / `<FileUpload>` `field` prop MUST be `item.Field`, NOT `bdo.Field`** — The `upload()` and `deleteAttachment()` methods live on the form item accessor (created by the Item proxy), not on the BDO field class. Passing `bdo.Field` causes silent upload failures.
+9. **BooleanField: use `watch()` + `setValue()`, never `register()`** — `<Switch>` and `<Checkbox>` components don't fire native change events. Using `register()` means the value never updates on toggle.
 
 ## Quick Start
 

package/docs/useActivityForm/README.md

@@ -242,3 +242,4 @@ item.StartDate.readOnly;             // is readonly?
 - **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.
+- **Don't pass a single options object.** `useActivityForm` takes 2 arguments: `useActivityForm(activity, { activity_instance_id })`. This is different from `useActivityTable` which takes a single object `useActivityTable({ activity, status })`. Passing `useActivityForm({ activity, activity_instance_id })` causes a type error.

package/docs/useActivityTable/README.md

@@ -261,3 +261,5 @@ This is the standard pattern after any mutation (complete, update, save) that sh
 - **Don't use 0-indexed pagination.** Pages start at 1. Passing `pageNo: 0` will produce incorrect results.
 - **Don't forget to guard on `isLoading` before rendering rows.** While loading, `rows` is an empty array. Guard with `if (table.isLoading) return <Loading />` to avoid rendering an empty table.
 - **Don't hardcode field names as strings.** Use the activity field IDs (`activity.StartDate.id`) instead of raw strings (`"StartDate"`). This keeps your code type-safe and resilient to field renames.
+- **Don't use `table.data`** — the property is `table.rows`, same as `useBDOTable`.
+- **`initialState.sort` format is `[{ fieldName: "ASC" }]`** — NOT `{ field, direction }`. Write `sort: [{ StartDate: "DESC" }]`, not `sort: [{ field: "StartDate", direction: "desc" }]`.

package/docs/useBDOForm/README.md

@@ -170,6 +170,32 @@ item.Title.readOnly;             // is readonly?
 - **Don't forget `useMemo` on the BDO.** `new BdoClass()` must be wrapped in `useMemo(() => ..., [])`. Re-creating the instance on every render breaks the hook.
 - **Don't set date `defaultValues` to empty string.** Use `undefined` instead. Empty strings cause type validation errors for Date and DateTime fields.
 - **Don't mix `register()` and `watch()`+`setValue()` for the same field.** Pick one approach per field. `register()` for native inputs, `watch()`+`setValue()` for custom components.
-- **Don't use `register()` for select, checkbox, or reference components.** They don't fire native change events. Use `watch()` + `setValue()`.
+- **Don't use `register()` for select, checkbox, switch, or reference components.** They don't fire native change events. Use `watch()` + `setValue()`.
 - **Don't call `bdo.create()` or `bdo.update()` manually.** `handleSubmit` handles the API call. Calling them yourself will double-submit.
+- **`handleSubmit` is curried — pass it directly to `onSubmit`, don't call it inside a handler.** It takes `(onSuccess, onError)` and returns an event handler. Write `<form onSubmit={handleSubmit(onSuccess, onError)}>`. NEVER write `<form onSubmit={(e) => handleSubmit(data)}>` or `await handleSubmit(data)` — this passes the wrong argument and the API call never fires.
+  ```tsx
+  // ❌ WRONG — handleSubmit receives FormEvent, not form data. API never fires.
+  const onSubmit = async (data) => { await handleSubmit(data); };
+  <form onSubmit={onSubmit}>
+
+  // ✅ CORRECT — handleSubmit wraps your callback, validates, calls API, then invokes onSuccess
+  <form onSubmit={handleSubmit(
+    (result) => { toast.success("Created"); navigate("/products"); },
+    (error) => { toast.error("Failed"); }
+  )}>
+  ```
 - **Don't render the form before `isLoading` is false.** In create mode, the draft is being allocated. In update mode, the record is being fetched. Guard with `if (isLoading) return <Loading />`.
+- **There is no `operation` field.** Create vs. update mode is determined solely by `recordId`: absent = create, present = update. Never pass `operation: "create"` or `operation: "update"`.
+- **Guard `loadError` in edit forms.** After the `isLoading` check, add `if (loadError) return <ErrorMessage />` before rendering the form. Without this, `item` may be undefined in update mode.
+  ```tsx
+  if (isLoading) return <Loading />;
+  if (loadError) return <p>Error: {loadError.message}</p>;
+  ```
+- **Don't pass `operation` even though the SDK type supports it.** The SDK has `UseBDOFormAutoOptionsType` that auto-infers create/update from `recordId`. Passing `operation: "update"` requires `recordId: string` (not `string | undefined`), causing TS errors with `useParams()`. Omit `operation` entirely:
+  ```tsx
+  // ❌ WRONG — TS2345 when id is string | undefined from useParams
+  useBDOForm({ bdo, recordId: id, operation: "update" })
+
+  // ✅ CORRECT — auto mode handles string | undefined
+  useBDOForm({ bdo, recordId: id })
+  ```

package/docs/useBDOTable/README.md

@@ -237,7 +237,17 @@ This is the standard pattern after any mutation (create, update, delete) that sh
 ## Common Mistakes
 
 - **Don't forget `useMemo` on the BDO.** `new BdoClass()` must be wrapped in `useMemo(() => ..., [])`. Re-creating the instance on every render causes infinite refetching.
+- **Don't use `table.data`** — the property is `table.rows`. Other table libraries use `data`, but this SDK uses `rows`.
+- **Don't use `table.setSearch()`** — the correct API is `table.search.set(field, query)` with two arguments: field ID and query string.
 - **Don't access row fields directly.** `row.Title` is an accessor object, not the value. Use `row.Title.get()` to read the value.
 - **Don't use 0-indexed pagination.** Pages start at 1. Passing `pageNo: 0` will produce incorrect results.
 - **Don't forget to guard on `isLoading` before rendering rows.** While loading, `rows` is an empty array. Guard with `if (table.isLoading) return <Loading />` to avoid rendering an empty table.
 - **Don't hardcode field names as strings.** Use the BDO field IDs (`product.Title.id`) instead of raw strings (`"Title"`). This keeps your code type-safe and resilient to field renames.
+- **`initialState.sort` format is `[{ fieldName: "ASC" }]`** — a single-key object, NOT `{ field, direction }`. Other libraries use `{ field: "Title", direction: "asc" }` but this SDK uses `[{ Title: "ASC" }]`. Note: the direction is uppercase `"ASC"` or `"DESC"`.
+  ```tsx
+  // ❌ WRONG — { field, direction } format from other libraries
+  initialState: { sort: [{ field: product.Title.id, direction: "desc" }] }
+  // ✅ CORRECT — single-key object with uppercase direction
+  initialState: { sort: [{ Title: "DESC" }] }
+  ```
+- **Don't pass `bdo.field` where `bdo.field.id` is expected.** `bdo.Title` is a `StringField` object, not a string. Use `bdo.Title.id` to get the field ID string. Passing the field object causes TS2322 (`StringField` not assignable to `string`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "2.0.28",
+  "version": "2.0.29",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",