@ram_28/kf-ai-sdk 2.0.16 → 2.0.18

package/docs/useBDOForm/api_reference.md

@@ -0,0 +1,244 @@
+# useBDOForm API Reference
+
+```tsx
+import { useBDOForm } from "@ram_28/kf-ai-sdk/form";
+import type {
+  UseBDOFormOptionsType,
+  UseBDOFormReturnType,
+} from "@ram_28/kf-ai-sdk/form/types";
+```
+
+## Signature
+
+```tsx
+const form: UseBDOFormReturnType<SellerProduct> = useBDOForm(options: UseBDOFormOptionsType<SellerProduct>);
+```
+
+## Options
+
+`UseBDOFormOptionsType<B>`
+
+- `bdo: B extends BaseBdo<any, any, any>`
+  - **Required**
+  - BDO instance. Must be memoized with `useMemo()`.
+- `recordId: string | undefined`
+  - **Optional** · Defaults to `undefined`
+  - Record ID to edit. When present, the hook fetches the record and enters update mode. When absent, enters create mode.
+
+## Return Value
+
+`UseBDOFormReturnType<B>`
+
+### Instance
+
+- `item: FormItemType<TEditable, TReadonly>`
+  - The current record instance. Each field is an accessor with methods to read, write, and validate. See [Instance and Field Accessors](#instance-and-field-accessors).
+- `bdo: B`
+  - The BDO instance passed in.
+
+### Form Methods
+
+- `register: FormRegisterType<TEditable, TReadonly>`
+  - Registers an input field. Auto-disables readonly fields (`{ disabled: true }`).
+- `handleSubmit: HandleSubmitType<CreateUpdateResponseType>`
+  - Validates, calls API, invokes callbacks. See [handleSubmit](#handlesubmit).
+- `watch: UseFormWatch<AllFieldsType<B>>`
+  - Standard RHF `watch`. Typed to all fields (editable + readonly + system).
+- `setValue: UseFormSetValue<ExtractEditableType<B>>`
+  - Standard RHF `setValue`. Typed to editable fields only.
+- `getValues: UseFormGetValues<AllFieldsType<B>>`
+  - Returns all field values.
+- `reset: UseFormReset<AllFieldsType<B>>`
+  - Resets form to given values or defaults.
+- `trigger: UseFormTrigger<AllFieldsType<B>>`
+  - Manually triggers validation for specific or all fields.
+- `control: Control<AllFieldsType<B>>`
+  - RHF control for `Controller` components.
+
+### Form State
+
+- `formState: FormState<AllFieldsType<B>>`
+  - Full RHF form state object.
+- `errors: FieldErrors<AllFieldsType<B>>`
+  - Validation errors by field name. Each entry has `type` and `message`.
+- `isDirty: boolean`
+  - `true` if any field has been modified.
+- `isValid: boolean`
+  - `true` if all fields pass validation.
+- `isSubmitting: boolean`
+  - `true` during submission (from button click to API response).
+- `isSubmitSuccessful: boolean`
+  - `true` after a successful submission.
+- `dirtyFields: Partial<Record<keyof AllFieldsType<B>, boolean>>`
+  - Which fields have been modified.
+
+### Loading & Error
+
+- `isLoading: boolean`
+  - `true` while fetching the record (update mode) or creating the draft (create mode). Guard form render on this.
+- `isFetching: boolean`
+  - `true` during refetches in update mode (including background refetches).
+- `loadError: Error | null`
+  - Error from record fetch or draft creation.
+- `draftId: string | undefined`
+  - Draft record ID in create mode.
+- `isCreatingDraft: boolean | undefined`
+  - `true` while the initial draft is being created.
+
+## handleSubmit
+
+```typescript
+type HandleSubmitType<TRead> = (
+  onSuccess?: (data: TRead, e?: React.BaseSyntheticEvent) => void | Promise<void>,
+  onError?: (error: FieldErrors | Error, e?: React.BaseSyntheticEvent) => void | Promise<void>,
+) => (e?: React.BaseSyntheticEvent) => Promise<void>;
+```
+
+Curried function. Pass to `<form onSubmit={handleSubmit(onSuccess, onError)}>`.
+
+- `onSuccess(data, e?)`
+  - Called with `CreateUpdateResponseType` (`{ _id: string }`) after a successful API call.
+- `onError(error, e?)`
+  - Called with `FieldErrors` if validation fails, or `Error` if the API call fails.
+
+## Instance and Field Accessors
+
+`item` represents the current record. Each field on `item` is an accessor object.
+
+### Instance Members (`item`)
+
+- `_id: string | undefined`
+  - Current record ID.
+- `toJSON(): Partial<TEditable & TReadonly>`
+  - All form values as a plain object.
+- `validate(): Promise<boolean>`
+  - Triggers validation for all fields. Returns `true` if valid.
+
+### Editable Field (`item.FieldName`)
+
+- `get(): T | undefined`
+  - Current value from form state.
+- `getOrDefault(fallback: T): T`
+  - Value or fallback if null/undefined.
+- `set(value: T): void`
+  - Sets the field value.
+- `validate(): ValidationResultType`
+  - Validates the current value. Returns `{ valid: boolean, errors: string[] }`.
+- `label: string`
+  - Display label from field metadata.
+- `required: boolean`
+  - Whether the field is required.
+- `readOnly: boolean`
+  - Always `false` for editable fields.
+- `defaultValue: unknown`
+  - Default value from metadata.
+- `meta: BaseFieldMetaType`
+  - Raw field metadata.
+
+### Readonly Field (`item.FieldName`)
+
+Same as editable except: no `set()` method, `readOnly` is always `true`.
+
+## Types
+
+```typescript
+// Options
+interface UseBDOFormOptionsType<B extends BaseBdo<any, any, any>> {
+  bdo: B;
+  recordId?: string;
+}
+
+// Return type
+interface UseBDOFormReturnType<B extends BaseBdo<any, any, any>> {
+  item: FormItemType<ExtractEditableType<B>, ExtractReadonlyType<B>>;
+  bdo: B;
+
+  register: FormRegisterType<ExtractEditableType<B>, ExtractReadonlyType<B>>;
+  handleSubmit: HandleSubmitType<CreateUpdateResponseType>;
+  watch: UseFormWatch<AllFieldsType<B>>;
+  setValue: UseFormSetValue<ExtractEditableType<B>>;
+  getValues: UseFormGetValues<AllFieldsType<B>>;
+  reset: UseFormReset<AllFieldsType<B>>;
+  trigger: UseFormTrigger<AllFieldsType<B>>;
+  control: Control<AllFieldsType<B>>;
+
+  formState: FormState<AllFieldsType<B>>;
+  errors: FieldErrors<AllFieldsType<B>>;
+  isDirty: boolean;
+  isValid: boolean;
+  isSubmitting: boolean;
+  isSubmitSuccessful: boolean;
+  dirtyFields: Partial<Record<keyof AllFieldsType<B>, boolean>>;
+
+  isLoading: boolean;
+  isFetching: boolean;
+  loadError: Error | null;
+
+  draftId?: string;
+  isCreatingDraft?: boolean;
+}
+
+// handleSubmit signature
+type HandleSubmitType<TRead = unknown> = (
+  onSuccess?: (data: TRead, e?: React.BaseSyntheticEvent) => void | Promise<void>,
+  onError?: (error: FieldErrors | Error, e?: React.BaseSyntheticEvent) => void | Promise<void>,
+) => (e?: React.BaseSyntheticEvent) => Promise<void>;
+
+// Instance type
+type FormItemType<TEditable, TReadonly> = {
+  [K in keyof TEditable]: EditableFormFieldAccessorType<TEditable[K]>;
+} & {
+  [K in keyof TReadonly]: ReadonlyFormFieldAccessorType<TReadonly[K]>;
+} & {
+  readonly _id: string | undefined;
+  toJSON(): Partial<TEditable & TReadonly>;
+  validate(): Promise<boolean>;
+};
+
+interface EditableFormFieldAccessorType<T> {
+  readonly label: string;
+  readonly required: boolean;
+  readonly readOnly: boolean;
+  readonly defaultValue: unknown;
+  readonly meta: BaseFieldMetaType;
+  get(): T | undefined;
+  getOrDefault(fallback: T): T;
+  set(value: T): void;
+  validate(): ValidationResultType;
+}
+
+interface ReadonlyFormFieldAccessorType<T> {
+  readonly label: string;
+  readonly required: boolean;
+  readonly readOnly: boolean;
+  readonly defaultValue: unknown;
+  readonly meta: BaseFieldMetaType;
+  get(): T | undefined;
+  getOrDefault(fallback: T): T;
+  validate(): ValidationResultType;
+}
+
+// Smart register
+type FormRegisterType<TEditable, TReadonly> = <
+  K extends keyof TEditable | keyof TReadonly | string
+>(
+  name: K & string,
+  options?: RegisterOptions,
+) => K extends keyof TReadonly
+  ? UseFormRegisterReturn & { disabled: true }
+  : UseFormRegisterReturn;
+
+// Helpers
+type ExtractEditableType<B> = B extends BaseBdo<any, infer E, any> ? E : never;
+type ExtractReadonlyType<B> = B extends BaseBdo<any, any, infer R> ? R : never;
+type AllFieldsType<B> = ExtractEditableType<B> & ExtractReadonlyType<B> & SystemFieldsType;
+
+interface ValidationResultType {
+  valid: boolean;
+  errors: string[];
+}
+
+interface CreateUpdateResponseType {
+  _id: string;
+}
+```

package/docs/useBDOTable/README.md

@@ -0,0 +1,242 @@
+# useBDOTable
+
+BDO-integrated table hook with data fetching, search, sorting, filtering, and pagination.
+
+## When to Use
+
+**Use `useBDOTable` when:**
+
+- Displaying a list of BDO records in a table
+- You need search, sort, filter, and/or pagination
+
+**Use something else when:**
+
+- Displaying workflow/activity records — use [`useActivityTable`](../useActivityTable/README.md) instead
+- Building a form — use [`useBDOForm`](../useBDOForm/README.md) instead
+
+## Imports
+
+```tsx
+import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
+```
+
+## Quick Start
+
+```tsx
+import { useMemo } from "react";
+import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
+import { BuyerProduct } from "@/bdo/buyer/Product";
+
+function ProductsPage() {
+  const product = useMemo(() => new BuyerProduct(), []);
+
+  const table = useBDOTable({
+    bdo: product,
+    initialState: {
+      sort: [{ Title: "ASC" }],
+      pagination: { pageNo: 1, pageSize: 10 },
+    },
+  });
+
+  if (table.isLoading) return <p>Loading...</p>;
+  if (table.error) return <p>Error: {table.error.message}</p>;
+
+  return (
+    <div>
+      <ul>
+        {table.rows.map((row) => (
+          <li key={row._id}>
+            {row.Title.get()} - ${row.Price.get()}
+          </li>
+        ))}
+      </ul>
+
+      <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>
+  );
+}
+```
+
+## Usage Guide
+
+### Accessing Row Data
+
+Rows are `ItemType` instances, not plain objects. Access field values through the `.get()` method on each field accessor:
+
+```tsx
+table.rows.map((row) => (
+  <tr key={row._id}>
+    <td>{row.Title.get()}</td>
+    <td>{row.Category.get()}</td>
+    <td>${row.Price.get()}</td>
+  </tr>
+));
+```
+
+- `row._id` is a direct string (no `.get()` needed)
+- `row.Title.get()` returns the field's current value
+- `row.toJSON()` converts the entire row to a plain object
+- Editable rows also have `.set()`, but this is typically not used in a table context
+
+### Search
+
+Search filters results by matching a query string against a specific field. The input value updates immediately for a responsive UI, while the API call is debounced.
+
+```tsx
+<input
+  type="text"
+  placeholder={`Search by ${product.Title.label}...`}
+  value={table.search.query}
+  onChange={(e) => table.search.set(product.Title.id, e.target.value)}
+/>
+{table.search.query && (
+  <button onClick={table.search.clear}>Clear</button>
+)}
+{table.isFetching && <span>Searching...</span>}
+```
+
+- **`search.set(field, query)`** -- set the field and query text. The API call is debounced by 300ms. Pagination resets to page 1.
+- **`search.clear()`** -- clear the search field and query. Pagination resets to page 1.
+- **`search.query`** -- current query string (updates immediately, API call debounced)
+- **`search.field`** -- field currently being searched, or `null`
+- Queries longer than 255 characters are silently ignored.
+
+### Sorting
+
+Sorting is controlled through the `sort` object. Column headers typically use `toggle()` for click-to-sort behavior:
+
+```tsx
+<th
+  onClick={() => table.sort.toggle(product.Title.id)}
+  style={{ cursor: "pointer" }}
+>
+  {product.Title.label}
+  {table.sort.field === product.Title.id &&
+    (table.sort.direction === "ASC" ? " ↑" : " ↓")}
+</th>
+```
+
+- **`sort.toggle(field)`** -- cycles through ASC, DESC, then cleared. Toggling a different field starts at ASC.
+- **`sort.set(field, direction)`** -- set the sort field and direction directly. Pass `null` for both to clear.
+- **`sort.clear()`** -- remove sorting entirely.
+- **`sort.field`** / **`sort.direction`** -- current sort state, or `null` when no sort is active.
+- **`initialState.sort`** format is an array of single-key objects: `[{ fieldName: "ASC" }]`.
+
+### Filtering
+
+The table includes an integrated [`useFilter`](../useFilter/README.md) instance at `table.filter`. Use it to build filter conditions that narrow down the table results:
+
+```tsx
+import { ConditionOperator } from "@ram_28/kf-ai-sdk/table";
+
+// Exact match
+table.filter.addCondition({
+  Operator: ConditionOperator.EQ,
+  LHSField: product.Category.id,
+  RHSValue: "Electronics",
+  RHSType: "Constant",
+});
+
+// Range filter
+table.filter.addCondition({
+  Operator: ConditionOperator.GTE,
+  LHSField: product.Price.id,
+  RHSValue: 100,
+});
+
+// Clear all filters
+table.filter.clearAllConditions();
+
+// Check if any filters are active
+if (table.filter.hasConditions) {
+  // ...
+}
+```
+
+- **`table.filter.addCondition(condition)`** -- add a filter condition
+- **`table.filter.clearAllConditions()`** -- remove all filter conditions
+- **`table.filter.hasConditions`** -- `true` if any conditions are active
+- Filter changes automatically reset pagination to page 1, preventing empty pages after narrowing results.
+- See the [useFilter documentation](../useFilter/README.md) for the full filter API.
+
+### Pagination
+
+Pages are 1-indexed (they start at 1, not 0). The default page is 1 and the default page size is 10.
+
+```tsx
+<div>
+  <button
+    onClick={table.pagination.goToPrevious}
+    disabled={!table.pagination.canGoPrevious}
+  >
+    Previous
+  </button>
+  <span>
+    Page {table.pagination.pageNo} of {table.pagination.totalPages}
+    {" "}({table.pagination.totalItems} total)
+  </span>
+  <button
+    onClick={table.pagination.goToNext}
+    disabled={!table.pagination.canGoNext}
+  >
+    Next
+  </button>
+</div>
+
+<select
+  value={table.pagination.pageSize}
+  onChange={(e) => table.pagination.setPageSize(Number(e.target.value))}
+>
+  <option value={10}>10</option>
+  <option value={25}>25</option>
+  <option value={50}>50</option>
+</select>
+```
+
+- **`pagination.goToNext()`** / **`pagination.goToPrevious()`** -- navigate forward/backward. No-op at boundaries.
+- **`pagination.goToPage(n)`** -- jump to a specific page. Clamped to `[1, totalPages]`.
+- **`pagination.canGoNext`** / **`pagination.canGoPrevious`** -- whether navigation is possible.
+- **`pagination.setPageSize(n)`** -- change the page size. Resets to page 1.
+- **`pagination.pageNo`** / **`pagination.pageSize`** / **`pagination.totalPages`** / **`pagination.totalItems`** -- current pagination state.
+
+### Refetching
+
+Call `refetch()` to manually refresh the table data. This refetches both the list and the count:
+
+```tsx
+const handleDelete = async (id: string) => {
+  await product.delete(id);
+  table.refetch();
+};
+```
+
+This is the standard pattern after any mutation (create, update, delete) that should be reflected in the table.
+
+## Further Reading
+
+- [API Reference](./api_reference.md) -- All options, return values, and type definitions
+- [Product Listing](../examples/bdo/product-listing.md) -- Table with search, sorting, pagination
+- [Edit Product Dialog](../examples/bdo/edit-product-dialog.md) -- Table + edit dialog + refetch
+- [Filtered Product Table](../examples/bdo/filtered-product-table.md) -- Category + price range filters
+
+## 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 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.