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

package/docs/useBDOTable.md

@@ -0,0 +1,284 @@
+# useBDOTable
+
+Hook for BDO (Business Data Object) tables with search, sort, filter, and pagination. Pass a BDO instance and the hook handles the rest.
+
+## Imports
+
+```typescript
+import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
+import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/table";
+import type { UseBDOTableOptionsType, UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
+```
+
+---
+
+## Common Mistakes (READ FIRST)
+
+### 1. Passing `source` instead of `bdo`
+
+`useBDOTable` takes a `bdo` instance, NOT a `source` string.
+
+```typescript
+// ❌ WRONG — source is not a valid property on useBDOTable
+useBDOTable({ source: product.meta._id });
+
+// ✅ CORRECT — pass the BDO instance
+useBDOTable({ bdo: product });
+```
+
+### 2. Passing a raw object instead of a BDO instance
+
+The `bdo` property expects an object with a `meta` property containing `_id` and `name`. A plain object or entity type will not work.
+
+```typescript
+// ❌ WRONG — plain object without meta
+useBDOTable({ bdo: { _id: 'BO_Product', name: 'Product' } });
+
+// ✅ CORRECT — a BDO class instance
+const product = useMemo(() => new BuyerProduct(), []);
+useBDOTable({ bdo: product });
+```
+
+### 3. Recreating the BDO on every render
+
+Constructing the BDO inside the component body without `useMemo` creates a new instance on every render, which destabilizes the query key and causes infinite refetching.
+
+```typescript
+// ❌ WRONG — new instance every render
+function ProductsTable() {
+  const product = new BuyerProduct();
+  const table = useBDOTable({ bdo: product }); // infinite refetch loop
+}
+
+// ✅ CORRECT — memoize the instance
+function ProductsTable() {
+  const product = useMemo(() => new BuyerProduct(), []);
+  const table = useBDOTable({ bdo: product });
+}
+```
+
+### 4. Using `columns` with useBDOTable
+
+`useBDOTable` does not accept a `columns` property. Column definitions are a UI concern handled in your rendering logic, not in the hook options.
+
+```typescript
+// ❌ WRONG — columns is not a hook option
+useBDOTable({
+  bdo: product,
+  columns: [{ fieldId: 'Title', label: 'Title' }],
+});
+
+// ✅ CORRECT — define columns separately for rendering
+const columns = [
+  { fieldId: product.Title.id, label: product.Title.label },
+  { fieldId: product.Price.id, label: product.Price.label },
+];
+const table = useBDOTable({ bdo: product });
+```
+
+### 5. Calling `.get()` on table rows
+
+Table `rows` are plain objects, NOT `ItemType`. The `.get()` accessor is only available on items returned by `bdo.get()`, `bdo.create()`, or the `useBDOForm` item proxy.
+
+```typescript
+// ❌ WRONG — rows are plain objects, not ItemType
+table.rows.map((row) => row.Title.get());
+
+// ✅ CORRECT — access properties directly
+table.rows.map((row) => row.Title);
+```
+
+### 6. Wrong initialState property names
+
+This is not react-table. Do not use react-table naming conventions.
+
+```typescript
+// ❌ WRONG — sorting and pageIndex are react-table names
+useBDOTable({
+  bdo: product,
+  initialState: { sorting: [...], pagination: { pageIndex: 0, pageSize: 10 } },
+});
+
+// ✅ CORRECT — use sort and pageNo (1-indexed)
+useBDOTable({
+  bdo: product,
+  initialState: {
+    sort: [{ [product.Title.id]: 'ASC' }],
+    pagination: { pageNo: 1, pageSize: 10 },
+  },
+});
+```
+
+---
+
+## Complete Example
+
+A product listing page with search, filter, sort, and pagination.
+
+```tsx
+import { useMemo, useState } from "react";
+import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
+import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/table";
+import type { UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
+import { BuyerProduct } from "../bdo/buyer/Product";
+import type { BuyerProductFieldType } from "../bdo/buyer/Product";
+
+function ProductListPage() {
+  const productBdo = useMemo(() => new BuyerProduct(), []);
+  const [selectedCategory, setSelectedCategory] = useState("all");
+
+  const table: UseBDOTableReturnType<BuyerProductFieldType> =
+    useBDOTable<BuyerProductFieldType>({
+      bdo: productBdo,
+      initialState: {
+        sort: [{ [productBdo.Title.id]: "ASC" }],
+        pagination: { pageNo: 1, pageSize: 10 },
+      },
+      onError: (error) => {
+        console.error("Table fetch failed:", error.message);
+      },
+      onSuccess: (data) => {
+        console.log("Loaded", data.length, "rows");
+      },
+    });
+
+  const handleCategoryChange = (category: string) => {
+    setSelectedCategory(category);
+    table.filter.clearAllConditions();
+    if (category !== "all") {
+      table.filter.addCondition({
+        LHSField: productBdo.Category.id,
+        Operator: ConditionOperator.EQ,
+        RHSValue: category,
+        RHSType: RHSType.Constant,
+      });
+    }
+  };
+
+  if (table.isLoading) return <div>Loading...</div>;
+  if (table.error) {
+    return (
+      <div>
+        <p>Error: {table.error.message}</p>
+        <button onClick={() => table.refetch()}>Retry</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {/* Search */}
+      <input
+        type="text"
+        placeholder="Search products..."
+        value={table.search.query}
+        onChange={(e) => table.search.set(productBdo.Title.id, e.target.value)}
+      />
+      {table.search.query && (
+        <button onClick={table.search.clear}>Clear Search</button>
+      )}
+
+      {/* Category Filter */}
+      <select
+        value={selectedCategory}
+        onChange={(e) => handleCategoryChange(e.target.value)}
+      >
+        <option value="all">All Categories</option>
+        <option value="Electronics">Electronics</option>
+        <option value="Books">Books</option>
+      </select>
+
+      {/* Sort */}
+      <select
+        onChange={(e) => {
+          const [field, dir] = e.target.value.split(":");
+          table.sort.set(field, dir as "ASC" | "DESC");
+        }}
+      >
+        <option value={`${productBdo.Title.id}:ASC`}>Name A-Z</option>
+        <option value={`${productBdo.Price.id}:ASC`}>Price: Low to High</option>
+        <option value={`${productBdo.Price.id}:DESC`}>Price: High to Low</option>
+      </select>
+
+      {/* Results */}
+      <p>{table.totalItems} results</p>
+      <div>
+        {table.rows.map((row) => (
+          <div key={row._id}>
+            <h3>{row.Title}</h3>
+            <p>${row.Price}</p>
+            <p>{row.Category}</p>
+          </div>
+        ))}
+      </div>
+
+      {/* 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>
+  );
+}
+```
+
+---
+
+## Type Definitions
+
+### UseBDOTableOptionsType
+
+```typescript
+export interface UseBDOTableOptionsType<T> {
+  /** BDO instance — only meta._id is used (for API routing) */
+  bdo: {
+    meta: { readonly _id: string; readonly name: string };
+  };
+
+  /** Initial state */
+  initialState?: {
+    sort?: SortType;
+    pagination?: PaginationStateType;
+    filter?: UseFilterOptionsType<T>;
+  };
+
+  /** Error callback */
+  onError?: (error: Error) => void;
+
+  /** Success callback — receives rows from current page */
+  onSuccess?: (data: T[]) => void;
+}
+```
+
+### UseBDOTableReturnType
+
+```typescript
+export type UseBDOTableReturnType<T> = UseTableReturnType<T>;
+```
+
+The return type is identical to `UseTableReturnType<T>`. All properties — `rows`, `totalItems`, `isLoading`, `isFetching`, `error`, `search`, `sort`, `filter`, `pagination`, and `refetch` — behave the same.
+
+---
+
+## Search, Sort, Filter, and Pagination
+
+`useBDOTable` supports `initialState`, `onError`, and `onSuccess` options.
+
+- **Search** — `table.search.set(field, query)`, `table.search.clear()`, 300ms debounce
+- **Sort** — `table.sort.toggle(field)`, `table.sort.set(field, direction)`, `table.sort.clear()`
+- **Filter** — `table.filter.addCondition(...)`, `table.filter.removeCondition(...)`, `table.filter.clearAllConditions()`
+- **Pagination** — `table.pagination.goToNext()`, `table.pagination.goToPrevious()`, `table.pagination.goToPage(n)`, `table.pagination.setPageSize(n)`
+

package/docs/useFilter.md

@@ -0,0 +1,188 @@
+# Filter SDK API
+
+React hook for building filter conditions for tables, forms, and API calls.
+
+## Imports
+
+```typescript
+import { useFilter, isCondition, isConditionGroup, ConditionOperator, GroupOperator, FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+import type { UseFilterOptionsType, UseFilterReturnType, ConditionType, ConditionGroupType, FilterType } from "@ram_28/kf-ai-sdk/filter/types";
+```
+
+---
+
+## Common Mistakes (READ FIRST)
+
+### 1. Importing `RHSType` instead of `FilterValueSource`
+
+There is NO named export `RHSType`. Import `FilterValueSource`. The JSON key IS called `RHSType`, but the value comes from `FilterValueSource`.
+
+```typescript
+// ❌ WRONG — RHSType is not an importable enum
+import { RHSType } from "@ram_28/kf-ai-sdk/filter";
+
+// ✅ CORRECT
+import { FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+{ RHSType: FilterValueSource.Constant }
+```
+
+### 2. Wrong field name casing in ConditionType
+
+`ConditionType` uses **PascalCase**: `Operator`, `LHSField`, `RHSValue`, `RHSType`. NOT camelCase.
+
+```typescript
+// ❌ WRONG — camelCase
+{ operator: "EQ", lhsField: "status", rhsValue: "Active" }
+
+// ✅ CORRECT — PascalCase
+{ Operator: ConditionOperator.EQ, LHSField: bdo.status.id, RHSValue: "Active", RHSType: FilterValueSource.Constant }
+```
+
+### 3. Mixing hook init format with API format
+
+Hook init (`UseFilterOptionsType`) uses lowercase `conditions`/`operator`. API format (`FilterType`/`ConditionType`) uses uppercase `Condition`/`Operator`.
+
+```typescript
+// Hook initialization — lowercase
+useTable({ initialState: { filter: { conditions: [...], operator: "And" } } });
+
+// API calls — uppercase
+bdo.list({ Filter: { Operator: "And", Condition: [...] } });
+```
+
+### 4. Hardcoded operator strings
+
+ALWAYS use `ConditionOperator` constants. NEVER write `"Equals"`, `"equals"`, or `"eq"`.
+
+```typescript
+// ❌ WRONG
+{ Operator: "Equals" }  { Operator: "equals" }  { Operator: "eq" }
+
+// ✅ CORRECT
+{ Operator: ConditionOperator.EQ }    // "EQ"
+{ Operator: ConditionOperator.Contains }  // "Contains"
+```
+
+### 5. Accessing `filter.conditions` instead of `filter.items`
+
+```typescript
+// ❌ WRONG — conditions does NOT exist
+filter.conditions.length
+
+// ✅ CORRECT
+filter.items.length
+filter.hasConditions  // boolean shortcut
+```
+
+### 6. Using `as const` on Operator values
+
+```typescript
+// ❌ WRONG — causes narrowing errors in arrays
+[{ Operator: ConditionOperator.EQ as const, ... }]
+
+// ✅ CORRECT — type the array
+const conditions: Omit<ConditionType, "id">[] = [{ Operator: ConditionOperator.EQ, ... }];
+```
+
+---
+
+## Constants
+
+```typescript
+// Condition operators
+ConditionOperator.EQ  ConditionOperator.NE       // Equal, Not Equal
+ConditionOperator.GT  ConditionOperator.GTE      // Greater Than (or Equal)
+ConditionOperator.LT  ConditionOperator.LTE      // Less Than (or Equal)
+ConditionOperator.Contains  ConditionOperator.NotContains  // String contains
+ConditionOperator.IN  ConditionOperator.NIN       // Value in/not-in list
+ConditionOperator.Empty  ConditionOperator.NotEmpty  // Null/empty check
+ConditionOperator.Between  ConditionOperator.NotBetween  // Range
+
+// Group operators
+GroupOperator.And  GroupOperator.Or  GroupOperator.Not
+
+// RHS value source (KEY is "RHSType", VALUE from FilterValueSource)
+FilterValueSource.Constant     // "Constant" — literal value
+FilterValueSource.BDOField     // "BDOField" — compare against another field
+FilterValueSource.AppVariable  // "AppVariable" — app variable
+```
+
+---
+
+## Type Definitions
+
+```typescript
+interface ConditionType<T = any> {
+  id?: string;                           // Auto-generated
+  Operator: ConditionOperatorType;       // PascalCase
+  LHSField: keyof T | string;
+  RHSValue: any;
+  RHSType?: "Constant" | "BDOField" | "AppVariable";
+}
+
+interface ConditionGroupType<T = any> {
+  id?: string;
+  Operator: "And" | "Or" | "Not";
+  Condition: Array<ConditionType<T> | ConditionGroupType<T>>;
+}
+
+interface UseFilterOptionsType<T = any> {    // lowercase — hook init
+  conditions?: Array<ConditionType<T> | ConditionGroupType<T>>;
+  operator?: "And" | "Or" | "Not";
+}
+
+interface UseFilterReturnType<T = any> {
+  operator: "And" | "Or" | "Not";
+  items: Array<ConditionType<T> | ConditionGroupType<T>>;
+  payload: FilterType<T> | undefined;     // API-ready, undefined if empty
+  hasConditions: boolean;
+  addCondition: (condition: Omit<ConditionType<T>, "id">, parentId?: string) => string;
+  addConditionGroup: (operator: "And" | "Or" | "Not", parentId?: string) => string;
+  updateCondition: (id: string, updates: Partial<Omit<ConditionType<T>, "id">>) => void;
+  removeCondition: (id: string) => void;
+  clearAllConditions: () => void;
+  setRootOperator: (op: "And" | "Or" | "Not") => void;
+}
+```
+
+---
+
+## Usage Example
+
+```tsx
+import { useFilter, ConditionOperator, GroupOperator, FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+import type { UseFilterOptionsType } from "@ram_28/kf-ai-sdk/filter/types";
+
+// Standalone filter
+const filter = useFilter<AdminProductFieldType>();
+filter.addCondition({ Operator: ConditionOperator.EQ, LHSField: bdo.status.id, RHSValue: "Active", RHSType: FilterValueSource.Constant });
+filter.addCondition({ Operator: ConditionOperator.GT, LHSField: bdo.unit_price.id, RHSValue: 100, RHSType: FilterValueSource.Constant });
+
+// With useTable initialState
+const table = useTable<AdminProductFieldType>({
+  source: bdo.meta._id,
+  columns,
+  initialState: {
+    filter: {
+      conditions: [
+        { Operator: ConditionOperator.EQ, LHSField: "_created_by", RHSValue: user._id, RHSType: FilterValueSource.Constant },
+      ],
+      operator: GroupOperator.And,
+    },
+  },
+});
+
+// Dynamic filter with useEffect
+useEffect(() => {
+  table.filter.clearAllConditions();
+  if (status !== "all") {
+    table.filter.addCondition({ Operator: ConditionOperator.EQ, LHSField: bdo.status.id, RHSValue: status, RHSType: FilterValueSource.Constant });
+  }
+}, [status]);
+
+// Nested: Category = "Electronics" AND (Price < 100 OR OnSale = true)
+filter.addCondition({ Operator: ConditionOperator.EQ, LHSField: bdo.category.id, RHSValue: "Electronics", RHSType: FilterValueSource.Constant });
+const orGroupId = filter.addConditionGroup(GroupOperator.Or);
+filter.addCondition({ Operator: ConditionOperator.LT, LHSField: bdo.price.id, RHSValue: 100, RHSType: FilterValueSource.Constant }, orGroupId);
+filter.addCondition({ Operator: ConditionOperator.EQ, LHSField: bdo.on_sale.id, RHSValue: true, RHSType: FilterValueSource.Constant }, orGroupId);
+```