@ram_28/kf-ai-sdk 2.0.15 → 2.0.17

package/docs/useBDOTable.md

@@ -1,317 +0,0 @@
-# useBDOTable
-
-Thin wrapper around `useTable` for BDO (Business Data Object) tables. Instead of manually wiring up `queryKey`, `listFn`, and `countFn`, you 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 `meta`, `list()`, and `count()`. A plain object or entity type will not work.
-
-```typescript
-// ❌ WRONG — plain object without list/count methods
-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 `useForm` 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 with list() and count() methods */
-  bdo: {
-    meta: { readonly _id: string; readonly name: string };
-    list(options?: any): Promise<any>;
-    count(options?: any): Promise<any>;
-  };
-
-  /** 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
-
-These features are inherited from the base `useTable` hook. `useBDOTable` passes `initialState`, `onError`, and `onSuccess` straight through.
-
-- **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)`
-
----
-
-## Migration Guide: `useTable` to `useBDOTable`
-
-### Before (useTable)
-
-```typescript
-const table = useTable<BuyerProductFieldType>({
-  queryKey: ["table", product.meta._id],
-  listFn: (opts) => product.list(opts),
-  countFn: (opts) => product.count(opts),
-  initialState: { sort: [{ [product.Title.id]: "ASC" }], pagination: { pageNo: 1, pageSize: 10 } },
-});
-```
-
-### After (useBDOTable)
-
-```typescript
-const table = useBDOTable<BuyerProductFieldType>({
-  bdo: product,
-  initialState: { sort: [{ [product.Title.id]: "ASC" }], pagination: { pageNo: 1, pageSize: 10 } },
-});
-```
-
-| Property | `useTable` | `useBDOTable` |
-|----------|-----------|---------------|
-| Data source | `queryKey` + `listFn` + `countFn` | `bdo` (single property) |
-| Query key | Manual: `["table", bdo.meta._id]` | Automatic: derived from `bdo.meta._id` |
-| List function | Manual: `(opts) => bdo.list(opts)` | Automatic: bound from `bdo.list()` |
-| Count function | Manual: `(opts) => bdo.count(opts)` | Automatic: bound from `bdo.count()` |
-| Return type | `UseTableReturnType<T>` | `UseBDOTableReturnType<T>` (alias) |

package/docs/useFilter.md

@@ -1,188 +0,0 @@
-# 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);
-```