@ram_28/kf-ai-sdk 2.0.12 → 2.0.13

package/docs/useFilter.md

@@ -1,1662 +1,188 @@
 # Filter SDK API
 
-This Filter SDK API provides necessary React-hooks and Components to build the
-Filter for using it when making api calls and building form component.
-
-Here is the example of Build and manage filter conditions with support for nested groups and complex logic.
-
-You SHOULD only use this API to building Table, Form, any other api call with that requires Filter.
+React hook for building filter conditions for tables, forms, and API calls.
 
 ## Imports
 
 ```typescript
-import {
-  useFilter,
-  isCondition,
-  isConditionGroup,
-  ConditionOperator,
-  GroupOperator,
-  RHSType,
-} from "@ram_28/kf-ai-sdk/filter";
-import type {
-  UseFilterOptionsType,
-  UseFilterReturnType,
-  ConditionType,
-  ConditionGroupType,
-  ConditionOperatorType,
-  ConditionGroupOperatorType,
-  FilterType,
-} from "@ram_28/kf-ai-sdk/filter/types";
-```
-
-## Constants
-
-Use the provided constants instead of hardcoded strings for type-safety:
-
-```typescript
-// Condition operators
-ConditionOperator.EQ        // "EQ"
-ConditionOperator.NE        // "NE"
-ConditionOperator.GT        // "GT"
-ConditionOperator.GTE       // "GTE"
-ConditionOperator.LT        // "LT"
-ConditionOperator.LTE       // "LTE"
-ConditionOperator.Between   // "Between"
-ConditionOperator.NotBetween // "NotBetween"
-ConditionOperator.IN        // "IN"
-ConditionOperator.NIN       // "NIN"
-ConditionOperator.Empty     // "Empty"
-ConditionOperator.NotEmpty  // "NotEmpty"
-ConditionOperator.Contains  // "Contains"
-ConditionOperator.NotContains // "NotContains"
-ConditionOperator.MinLength // "MinLength"
-ConditionOperator.MaxLength // "MaxLength"
-
-// Group operators
-GroupOperator.And  // "And"
-GroupOperator.Or   // "Or"
-GroupOperator.Not  // "Not"
-
-// RHS types
-RHSType.Constant    // "Constant"
-RHSType.BDOField    // "BDOField"
-RHSType.AppVariable // "AppVariable"
-```
-
-## Type Definitions
-
-```typescript
-// Condition operators
-type ConditionOperatorType =
-  | "EQ"
-  | "NE" // Equal, Not Equal
-  | "GT"
-  | "GTE" // Greater Than, Greater Than or Equal
-  | "LT"
-  | "LTE" // Less Than, Less Than or Equal
-  | "Between"
-  | "NotBetween"
-  | "IN"
-  | "NIN" // In List, Not In List
-  | "Empty"
-  | "NotEmpty"
-  | "Contains"
-  | "NotContains"
-  | "MinLength"
-  | "MaxLength";
-
-// Group operators
-type ConditionGroupOperatorType = "And" | "Or" | "Not";
-
-// Single condition (generic for type-safe LHSField)
-interface ConditionType<T = any> {
-  // Auto-generated unique identifier
-  id?: string;
-
-  // Comparison operator (EQ, GT, Contains, etc.)
-  Operator: ConditionOperatorType;
-
-  // Field name to compare
-  LHSField: keyof T | string;
-
-  // Value to compare against
-  RHSValue: any;
-
-  // Value type (default: "Constant")
-  RHSType?: "Constant" | "BDOField" | "AppVariable";
-}
-
-// Condition group (can contain conditions or nested groups)
-interface ConditionGroupType<T = any> {
-  // Auto-generated unique identifier
-  id?: string;
-
-  // Group operator (And, Or, Not)
-  Operator: ConditionGroupOperatorType;
-
-  // Nested conditions or groups
-  Condition: Array<ConditionType<T> | ConditionGroupType<T>>;
-}
-
-// Hook options (also used for initialState in useTable/useKanban)
-interface UseFilterOptionsType<T = any> {
-  // Initial conditions to populate the filter
-  conditions?: Array<ConditionType<T> | ConditionGroupType<T>>;
-
-  // Root operator for combining conditions (default: "And")
-  operator?: ConditionGroupOperatorType;
-}
-
-// Hook return type (generic for type-safe field names)
-interface UseFilterReturnType<T = any> {
-  // ============================================================
-  // STATE
-  // ============================================================
-
-  // Current root operator (And, Or, Not)
-  operator: ConditionGroupOperatorType;
-
-  // All conditions and groups at root level
-  items: Array<ConditionType<T> | ConditionGroupType<T>>;
-
-  // API-ready filter payload (undefined if no conditions)
-  payload: FilterType<T> | undefined;
-
-  // True when at least one condition exists
-  hasConditions: boolean;
-
-  // ============================================================
-  // METHODS
-  // ============================================================
-
-  // Add a condition, optionally to a parent group. Returns the new condition's ID
-  addCondition: (
-    condition: Omit<ConditionType<T>, "id">,
-    parentId?: string,
-  ) => string;
-
-  // Add a condition group, optionally to a parent group. Returns the new group's ID
-  addConditionGroup: (
-    operator: ConditionGroupOperatorType,
-    parentId?: string,
-  ) => string;
-
-  // Update a condition's properties (Operator, LHSField, RHSValue)
-  updateCondition: (
-    id: string,
-    updates: Partial<Omit<ConditionType<T>, "id">>,
-  ) => void;
-
-  // Change a group's operator (And, Or, Not)
-  updateGroupOperator: (
-    id: string,
-    operator: ConditionGroupOperatorType,
-  ) => void;
-
-  // Remove a condition or group by ID
-  removeCondition: (id: string) => void;
-
-  // Get a condition or group by ID
-  getCondition: (
-    id: string,
-  ) => ConditionType<T> | ConditionGroupType<T> | undefined;
-
-  // Remove all conditions and groups
-  clearAllConditions: () => void;
-
-  // Change the root operator
-  setRootOperator: (operator: ConditionGroupOperatorType) => void;
-}
-```
-
-## Operator Applicability
-
-| Operator              | Applicable Field Types |
-| --------------------- | ---------------------- |
-| EQ, NE                | All types              |
-| GT, GTE, LT, LTE      | number, date, currency |
-| Between, NotBetween   | number, date, currency |
-| IN, NIN               | All types              |
-| Empty, NotEmpty       | All types              |
-| Contains, NotContains | string, reference/user (with dot notation) |
-| MinLength, MaxLength  | string, array          |
-| Length                 | array                  |
-
-## Basic Example
-
-Create a simple filter with one condition.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-
-function SimpleFilter() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const filter = useFilter();
-
-  const addCategoryFilter = () => {
-    filter.addCondition({
-      Operator: ConditionOperator.EQ,
-      LHSField: product.Category.id,
-      RHSValue: "Electronics",
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={addCategoryFilter}>Filter by Electronics</button>
-      <button
-        onClick={filter.clearAllConditions}
-        disabled={!filter.hasConditions}
-      >
-        Clear
-      </button>
-      <p>Active filters: {filter.items.length}</p>
-    </div>
-  );
-}
-```
-
----
-
-## Type-Safe Filtering
-
-Use the generic type parameter to get TypeScript validation on field names.
-
-### With Generic Type
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-import type { BuyerProductFieldType } from "../bdo/buyer/Product";
-
-function TypeSafeFilter() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  // Pass the type parameter for type-safe LHSField
-  const filter = useFilter<BuyerProductFieldType>();
-
-  const addCategoryFilter = () => {
-    filter.addCondition({
-      Operator: ConditionOperator.EQ,
-      LHSField: product.Category.id, // Type-safe via BDO field
-      RHSValue: "Electronics",
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  const addInvalidFilter = () => {
-    filter.addCondition({
-      Operator: ConditionOperator.EQ,
-      LHSField: "InvalidField", // TypeScript error: not a key of BuyerProductFieldType
-      RHSValue: "test",
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={addCategoryFilter}>Filter by Category</button>
-    </div>
-  );
-}
-```
-
-### UseFilterOptionsType for Initial State
-
-`UseFilterOptionsType<T>` is used for:
-
-- Initializing `useFilter` directly
-- Setting `initialState.filter` in `useTable`
-- Setting `initialState.filter` in `useKanban`
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, GroupOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import type { UseFilterOptionsType } from "@ram_28/kf-ai-sdk/filter/types";
-import { BuyerProduct } from "../bdo/buyer/Product";
-import type { BuyerProductFieldType } from "../bdo/buyer/Product";
-
-function FilterWithInitialState() {
-  const product = useMemo(() => new BuyerProduct(), []);
-
-  // Type-safe filter options
-  const initialFilter: UseFilterOptionsType<BuyerProductFieldType> = {
-    conditions: [
-      {
-        Operator: ConditionOperator.EQ,
-        LHSField: product.Category.id,
-        RHSValue: "Electronics",
-        RHSType: RHSType.Constant,
-      },
-      {
-        Operator: ConditionOperator.GT,
-        LHSField: product.Price.id,
-        RHSValue: 100,
-        RHSType: RHSType.Constant,
-      },
-    ],
-    operator: GroupOperator.And,
-  };
-
-  // Use with useFilter
-  const filter = useFilter<BuyerProductFieldType>(initialFilter);
-}
-```
-
----
-
-## Condition Types
-
-### Equality (EQ, NE)
-
-Match or exclude exact values.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-
-function EqualityFilters() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const filter = useFilter();
-
-  // Exact match
-  const filterByStatus = (status: string) => {
-    filter.addCondition({
-      Operator: ConditionOperator.EQ,
-      LHSField: product.Status.id,
-      RHSValue: status,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Exclude a value
-  const excludeStatus = (status: string) => {
-    filter.addCondition({
-      Operator: ConditionOperator.NE,
-      LHSField: product.Status.id,
-      RHSValue: status,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={() => filterByStatus("Active")}>Active Only</button>
-      <button onClick={() => excludeStatus("Archived")}>
-        Exclude Archived
-      </button>
-    </div>
-  );
-}
-```
-
-### Comparison (GT, GTE, LT, LTE)
-
-Filter by numeric or date comparisons.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-
-function ComparisonFilters() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const filter = useFilter();
-
-  // Price greater than
-  const filterByMinPrice = (minPrice: number) => {
-    filter.addCondition({
-      Operator: ConditionOperator.GT,
-      LHSField: product.Price.id,
-      RHSValue: minPrice,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Stock less than or equal
-  const filterLowStock = (threshold: number) => {
-    filter.addCondition({
-      Operator: ConditionOperator.LTE,
-      LHSField: product.Stock.id,
-      RHSValue: threshold,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Date comparison (using system field)
-  const filterRecent = () => {
-    const lastWeek = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
-    filter.addCondition({
-      Operator: ConditionOperator.GTE,
-      LHSField: "_created_at",  // System field
-      RHSValue: lastWeek,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={() => filterByMinPrice(100)}>Price > $100</button>
-      <button onClick={() => filterLowStock(10)}>Low Stock</button>
-      <button onClick={filterRecent}>Created This Week</button>
-    </div>
-  );
-}
-```
-
-### Range (Between, NotBetween)
-
-Filter values within or outside a range.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-import { BuyerOrder } from "../bdo/buyer/Order";
-
-function RangeFilters() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const order = useMemo(() => new BuyerOrder(), []);
-  const filter = useFilter();
-
-  // Price between range
-  const filterPriceRange = (min: number, max: number) => {
-    filter.addCondition({
-      Operator: ConditionOperator.Between,
-      LHSField: product.Price.id,
-      RHSValue: [min, max],
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Date range
-  const filterDateRange = (startDate: string, endDate: string) => {
-    filter.addCondition({
-      Operator: ConditionOperator.Between,
-      LHSField: order.OrderDate.id,
-      RHSValue: [startDate, endDate],
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Exclude range
-  const excludePriceRange = (min: number, max: number) => {
-    filter.addCondition({
-      Operator: ConditionOperator.NotBetween,
-      LHSField: product.Price.id,
-      RHSValue: [min, max],
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={() => filterPriceRange(50, 200)}>$50 - $200</button>
-      <button onClick={() => excludePriceRange(0, 10)}>
-        Exclude Under $10
-      </button>
-    </div>
-  );
-}
-```
-
-### List (IN, NIN)
-
-Match against a list of values.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-
-function ListFilters() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const filter = useFilter();
-
-  // Match any in list
-  const filterByCategories = (categories: string[]) => {
-    filter.addCondition({
-      Operator: ConditionOperator.IN,
-      LHSField: product.Category.id,
-      RHSValue: categories,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Exclude list
-  const excludeCategories = (categories: string[]) => {
-    filter.addCondition({
-      Operator: ConditionOperator.NIN,
-      LHSField: product.Category.id,
-      RHSValue: categories,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={() => filterByCategories(["Electronics", "Computers"])}>
-        Electronics & Computers
-      </button>
-      <button onClick={() => excludeCategories(["Clearance", "Discontinued"])}>
-        Exclude Clearance
-      </button>
-    </div>
-  );
-}
-```
-
-### Text (Contains, NotContains)
-
-Search within text fields.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-
-function TextFilters() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const filter = useFilter();
-
-  // Contains text
-  const filterByKeyword = (keyword: string) => {
-    filter.addCondition({
-      Operator: ConditionOperator.Contains,
-      LHSField: product.Title.id,
-      RHSValue: keyword,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Does not contain
-  const excludeKeyword = (keyword: string) => {
-    filter.addCondition({
-      Operator: ConditionOperator.NotContains,
-      LHSField: product.Description.id,
-      RHSValue: keyword,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  return (
-    <div>
-      <input
-        placeholder="Search..."
-        onKeyDown={(e) => {
-          if (e.key === "Enter") {
-            filterByKeyword((e.target as HTMLInputElement).value);
-          }
-        }}
-      />
-    </div>
-  );
-}
-```
-
-### Empty Checks (Empty, NotEmpty)
-
-Filter by presence or absence of values.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { Task } from "../bdo/Task";
-
-function EmptyFilters() {
-  const task = useMemo(() => new Task(), []);
-  const filter = useFilter();
-
-  // Has no value
-  const filterUnassigned = () => {
-    filter.addCondition({
-      Operator: ConditionOperator.Empty,
-      LHSField: task.AssignedTo.id,
-      RHSValue: null,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Has a value
-  const filterAssigned = () => {
-    filter.addCondition({
-      Operator: ConditionOperator.NotEmpty,
-      LHSField: task.AssignedTo.id,
-      RHSValue: null,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={filterUnassigned}>Unassigned Tasks</button>
-      <button onClick={filterAssigned}>Assigned Tasks</button>
-    </div>
-  );
-}
+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";
 ```
 
 ---
 
-## Filtering Reference & User Fields
-
-Reference and User fields are stored as JSON objects (`{ _id, _name, ... }`). The backend automatically targets the `_id` sub-field when filtering these fields. User and Reference fields behave identically for filtering.
-
-### Supported Operators
-
-| Operator | Supported | Notes |
-| --- | --- | --- |
-| EQ, NE | Yes | Compares against `_id` by default |
-| IN, NIN | Yes | List of IDs |
-| Empty, NotEmpty | Yes | Checks if field is null/unset |
-| Contains, NotContains | Only with dot notation | e.g., `"Vendor._name"` |
-| GT, GTE, LT, LTE, Between | No | Raises backend error |
-
-### Filter by ID (Default)
-
-When filtering a Reference or User field, pass the `_id` string directly as `RHSValue`. The backend automatically compares against the `_id` sub-field.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { AdminCartItem } from "../bdo/admin/CartItem";
-
-function ReferenceFilter() {
-  const cartItem = useMemo(() => new AdminCartItem(), []);
-  const filter = useFilter();
-
-  // Filter cart items by a specific product ID
-  const filterByProduct = (productId: string) => {
-    filter.addCondition({
-      Operator: ConditionOperator.EQ,
-      LHSField: cartItem.ProductInfo.id,
-      RHSValue: productId,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Filter by multiple product IDs
-  const filterByProducts = (productIds: string[]) => {
-    filter.addCondition({
-      Operator: ConditionOperator.IN,
-      LHSField: cartItem.ProductInfo.id,
-      RHSValue: productIds,
-      RHSType: RHSType.Constant,
-    });
-  };
+## Common Mistakes (READ FIRST)
 
-  // Filter unassigned items (reference is empty)
-  const filterUnlinked = () => {
-    filter.addCondition({
-      Operator: ConditionOperator.Empty,
-      LHSField: cartItem.ProductInfo.id,
-      RHSValue: null,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={() => filterByProduct("PROD_001")}>
-        Filter by Product
-      </button>
-      <button onClick={() => filterByProducts(["PROD_001", "PROD_002"])}>
-        Filter by Multiple
-      </button>
-      <button onClick={filterUnlinked}>Unlinked Items</button>
-    </div>
-  );
-}
-```
+### 1. Importing `RHSType` instead of `FilterValueSource`
 
-### Filter by Name (Dot Notation)
+There is NO named export `RHSType`. Import `FilterValueSource`. The JSON key IS called `RHSType`, but the value comes from `FilterValueSource`.
 
-Use dot notation in `LHSField` to filter on a nested sub-field like `_name`. This skips the default `_id` targeting and compares against the specified path.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { AdminCartItem } from "../bdo/admin/CartItem";
-
-function ReferenceNameFilter() {
-  const cartItem = useMemo(() => new AdminCartItem(), []);
-  const filter = useFilter();
-
-  // Search product name within the reference field
-  const searchProductName = (name: string) => {
-    filter.addCondition({
-      Operator: ConditionOperator.Contains,
-      LHSField: `${cartItem.ProductInfo.id}._name`,
-      RHSValue: name,
-      RHSType: RHSType.Constant,
-    });
-  };
+```typescript
+// ❌ WRONG — RHSType is not an importable enum
+import { RHSType } from "@ram_28/kf-ai-sdk/filter";
 
-  return (
-    <input
-      placeholder="Search by product name..."
-      onKeyDown={(e) => {
-        if (e.key === "Enter") {
-          searchProductName((e.target as HTMLInputElement).value);
-        }
-      }}
-    />
-  );
-}
+// ✅ CORRECT
+import { FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+{ RHSType: FilterValueSource.Constant }
 ```
 
-### Filter System User Fields
+### 2. Wrong field name casing in ConditionType
 
-System fields `_created_by` and `_modified_by` are User fields. Filter them the same way.
+`ConditionType` uses **PascalCase**: `Operator`, `LHSField`, `RHSValue`, `RHSType`. NOT camelCase.
 
-```tsx
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-
-function UserFieldFilter() {
-  const filter = useFilter();
-
-  // Filter by creator (using user's _id)
-  const filterByCreator = (userId: string) => {
-    filter.addCondition({
-      Operator: ConditionOperator.EQ,
-      LHSField: "_created_by",
-      RHSValue: userId,
-      RHSType: RHSType.Constant,
-    });
-  };
-
-  // Search by creator name
-  const searchByCreatorName = (name: string) => {
-    filter.addCondition({
-      Operator: ConditionOperator.Contains,
-      LHSField: "_created_by._name",
-      RHSValue: name,
-      RHSType: RHSType.Constant,
-    });
-  };
+```typescript
+// ❌ WRONG — camelCase
+{ operator: "EQ", lhsField: "status", rhsValue: "Active" }
 
-  return (
-    <div>
-      <button onClick={() => filterByCreator("USR_001")}>My Items</button>
-      <input
-        placeholder="Search by creator..."
-        onKeyDown={(e) => {
-          if (e.key === "Enter") {
-            searchByCreatorName((e.target as HTMLInputElement).value);
-          }
-        }}
-      />
-    </div>
-  );
-}
+// ✅ CORRECT — PascalCase
+{ Operator: ConditionOperator.EQ, LHSField: bdo.status.id, RHSValue: "Active", RHSType: FilterValueSource.Constant }
 ```
 
-### RHSValue Formats
-
-The backend accepts multiple `RHSValue` formats for Reference/User fields:
-
-| Format | Example | When to use |
-| --- | --- | --- |
-| String ID | `"PROD_001"` | Simplest — use when you have the ID |
-| Object with `_id` | `{ _id: "PROD_001", _name: "Widget" }` | Backend extracts `_id` automatically |
-| Array of IDs | `["PROD_001", "PROD_002"]` | With `IN` / `NIN` operators |
-| Array of objects | `[{ _id: "PROD_001" }, { _id: "PROD_002" }]` | With `IN` / `NIN` — backend extracts each `_id` |
-
-> **Tip:** Prefer passing the string ID directly. Passing the full object works but adds unnecessary payload size.
-
----
-
-## Condition Groups
-
-### AND Logic
-
-All conditions must match.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, GroupOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-
-function AndFilter() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const filter = useFilter({
-    operator: GroupOperator.And,
-  });
+### 3. Mixing hook init format with API format
 
-  const applyFilters = () => {
-    filter.clearAllConditions();
+Hook init (`UseFilterOptionsType`) uses lowercase `conditions`/`operator`. API format (`FilterType`/`ConditionType`) uses uppercase `Condition`/`Operator`.
 
-    // Category AND Price AND InStock - all must be true
-    filter.addCondition({
-      Operator: ConditionOperator.EQ,
-      LHSField: product.Category.id,
-      RHSValue: "Electronics",
-      RHSType: RHSType.Constant,
-    });
-    filter.addCondition({
-      Operator: ConditionOperator.LTE,
-      LHSField: product.Price.id,
-      RHSValue: 500,
-      RHSType: RHSType.Constant,
-    });
-    filter.addCondition({
-      Operator: ConditionOperator.GT,
-      LHSField: product.Stock.id,
-      RHSValue: 0,
-      RHSType: RHSType.Constant,
-    });
-  };
+```typescript
+// Hook initialization — lowercase
+useTable({ initialState: { filter: { conditions: [...], operator: "And" } } });
 
-  return (
-    <div>
-      <button onClick={applyFilters}>Electronics under $500, In Stock</button>
-      <p>Root operator: {filter.operator}</p>
-    </div>
-  );
-}
+// API calls — uppercase
+bdo.list({ Filter: { Operator: "And", Condition: [...] } });
 ```
 
-### OR Logic
+### 4. Hardcoded operator strings
 
-Any condition can match.
+ALWAYS use `ConditionOperator` constants. NEVER write `"Equals"`, `"equals"`, or `"eq"`.
 
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, GroupOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { Task } from "../bdo/Task";
-
-function OrFilter() {
-  const task = useMemo(() => new Task(), []);
-  const filter = useFilter({
-    operator: GroupOperator.Or,
-  });
-
-  const applyFilters = () => {
-    filter.clearAllConditions();
-
-    // High priority OR Overdue - either can match
-    filter.addCondition({
-      Operator: ConditionOperator.EQ,
-      LHSField: task.Priority.id,
-      RHSValue: "High",
-      RHSType: RHSType.Constant,
-    });
-    filter.addCondition({
-      Operator: ConditionOperator.LT,
-      LHSField: task.DueDate.id,
-      RHSValue: new Date().toISOString(),
-      RHSType: RHSType.Constant,
-    });
-  };
+```typescript
+// ❌ WRONG
+{ Operator: "Equals" }  { Operator: "equals" }  { Operator: "eq" }
 
-  return <button onClick={applyFilters}>Urgent Tasks</button>;
-}
+// ✅ CORRECT
+{ Operator: ConditionOperator.EQ }    // "EQ"
+{ Operator: ConditionOperator.Contains }  // "Contains"
 ```
 
-### Nested Groups
-
-Combine AND and OR logic.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, GroupOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-
-function NestedFilter() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const filter = useFilter({
-    operator: GroupOperator.And,
-  });
-
-  // Build: Category = "Electronics" AND (Price < 100 OR OnSale = true)
-  const applyComplexFilter = () => {
-    filter.clearAllConditions();
-
-    // Root level condition
-    filter.addCondition({
-      Operator: ConditionOperator.EQ,
-      LHSField: product.Category.id,
-      RHSValue: "Electronics",
-      RHSType: RHSType.Constant,
-    });
-
-    // Create nested OR group
-    const orGroupId = filter.addConditionGroup(GroupOperator.Or);
+### 5. Accessing `filter.conditions` instead of `filter.items`
 
-    // Add conditions to the OR group
-    filter.addCondition(
-      {
-        Operator: ConditionOperator.LT,
-        LHSField: product.Price.id,
-        RHSValue: 100,
-        RHSType: RHSType.Constant,
-      },
-      orGroupId,
-    );
-
-    filter.addCondition(
-      {
-        Operator: ConditionOperator.EQ,
-        LHSField: product.OnSale.id,
-        RHSValue: true,
-        RHSType: RHSType.Constant,
-      },
-      orGroupId,
-    );
-  };
+```typescript
+// ❌ WRONG — conditions does NOT exist
+filter.conditions.length
 
-  return <button onClick={applyComplexFilter}>Affordable Electronics</button>;
-}
+// ✅ CORRECT
+filter.items.length
+filter.hasConditions  // boolean shortcut
 ```
 
-### Deep Nesting
-
-Create multiple levels of nested groups.
+### 6. Using `as const` on Operator values
 
-```tsx
-import { useFilter, ConditionOperator, GroupOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-
-function DeepNestedFilter() {
-  const filter = useFilter();
-
-  // Build: (A AND B) OR (C AND D)
-  // Generic example - for real usage, use bdo.field.id for LHSField
-  const buildFilter = () => {
-    filter.clearAllConditions();
-    filter.setRootOperator(GroupOperator.Or);
-
-    // First AND group
-    const group1 = filter.addConditionGroup(GroupOperator.And);
-    filter.addCondition(
-      { Operator: ConditionOperator.EQ, LHSField: "Type", RHSValue: "A", RHSType: RHSType.Constant },
-      group1,
-    );
-    filter.addCondition(
-      { Operator: ConditionOperator.GT, LHSField: "Value", RHSValue: 10, RHSType: RHSType.Constant },
-      group1,
-    );
-
-    // Second AND group
-    const group2 = filter.addConditionGroup(GroupOperator.And);
-    filter.addCondition(
-      { Operator: ConditionOperator.EQ, LHSField: "Type", RHSValue: "B", RHSType: RHSType.Constant },
-      group2,
-    );
-    filter.addCondition(
-      { Operator: ConditionOperator.LT, LHSField: "Value", RHSValue: 5, RHSType: RHSType.Constant },
-      group2,
-    );
-  };
+```typescript
+// ❌ WRONG — causes narrowing errors in arrays
+[{ Operator: ConditionOperator.EQ as const, ... }]
 
-  return <button onClick={buildFilter}>Apply Complex Filter</button>;
-}
+// ✅ CORRECT — type the array
+const conditions: Omit<ConditionType, "id">[] = [{ Operator: ConditionOperator.EQ, ... }];
 ```
 
 ---
 
-## Displaying Filters
-
-### Render Active Filters
-
-Show current filter conditions with remove buttons.
-
-```tsx
-import { isCondition, isConditionGroup } from "@ram_28/kf-ai-sdk/filter";
-
-function ActiveFilters() {
-  const filter = useFilter();
-
-  const renderItem = (item: ConditionType | ConditionGroupType) => {
-    if (isCondition(item)) {
-      return (
-        <span key={item.id} className="filter-tag">
-          {item.LHSField} {item.Operator} {String(item.RHSValue)}
-          <button onClick={() => filter.removeCondition(item.id!)}>x</button>
-        </span>
-      );
-    }
-
-    if (isConditionGroup(item)) {
-      return (
-        <span key={item.id} className="filter-group">
-          {item.Operator} ({item.Condition.length} conditions)
-          <button onClick={() => filter.removeCondition(item.id!)}>x</button>
-        </span>
-      );
-    }
-
-    return null;
-  };
-
-  return (
-    <div className="active-filters">
-      {filter.items.map(renderItem)}
-      {filter.hasConditions && (
-        <button onClick={filter.clearAllConditions}>Clear All</button>
-      )}
-    </div>
-  );
-}
-```
-
-### Recursive Tree Display
-
-Display nested filter structure as a tree.
-
-```tsx
-function FilterTree() {
-  const filter = useFilter();
-
-  const renderNode = (item: ConditionType | ConditionGroupType, depth = 0) => {
-    const indent = { marginLeft: depth * 20 };
-
-    if (isCondition(item)) {
-      return (
-        <div key={item.id} style={indent} className="filter-condition">
-          {item.LHSField} {item.Operator} {JSON.stringify(item.RHSValue)}
-        </div>
-      );
-    }
+## Constants
 
-    if (isConditionGroup(item)) {
-      return (
-        <div key={item.id} style={indent} className="filter-group">
-          <strong>{item.Operator}</strong>
-          {item.Condition.map((child) => renderNode(child, depth + 1))}
-        </div>
-      );
-    }
+```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
 
-    return null;
-  };
+// Group operators
+GroupOperator.And  GroupOperator.Or  GroupOperator.Not
 
-  return (
-    <div className="filter-tree">
-      <div className="root">
-        <strong>Root: {filter.operator}</strong>
-      </div>
-      {filter.items.map((item) => renderNode(item, 1))}
-    </div>
-  );
-}
+// 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
 ```
 
 ---
 
-## Modifying Filters
-
-### Update a Condition
-
-Change an existing condition's values.
-
-```tsx
-import { useMemo, useState } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import type { ConditionOperatorType } from "@ram_28/kf-ai-sdk/filter/types";
-import { BuyerProduct } from "../bdo/buyer/Product";
-
-function EditableFilter() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const filter = useFilter();
-  const [conditionId, setConditionId] = useState<string | null>(null);
-
-  const addFilter = () => {
-    const id = filter.addCondition({
-      Operator: ConditionOperator.GT,
-      LHSField: product.Price.id,
-      RHSValue: 50,
-      RHSType: RHSType.Constant,
-    });
-    setConditionId(id);
-  };
-
-  const updateValue = (newValue: number) => {
-    if (conditionId) {
-      filter.updateCondition(conditionId, { RHSValue: newValue });
-    }
-  };
-
-  const updateOperator = (operator: ConditionOperatorType) => {
-    if (conditionId) {
-      filter.updateCondition(conditionId, { Operator: operator });
-    }
-  };
+## Type Definitions
 
-  return (
-    <div>
-      <button onClick={addFilter}>Add Price Filter</button>
-      {conditionId && (
-        <div>
-          <select
-            onChange={(e) =>
-              updateOperator(e.target.value as ConditionOperatorType)
-            }
-          >
-            <option value={ConditionOperator.GT}>Greater Than</option>
-            <option value={ConditionOperator.LT}>Less Than</option>
-            <option value={ConditionOperator.EQ}>Equals</option>
-          </select>
-          <input
-            type="number"
-            defaultValue={50}
-            onChange={(e) => updateValue(Number(e.target.value))}
-          />
-        </div>
-      )}
-    </div>
-  );
+```typescript
+interface ConditionType<T = any> {
+  id?: string;                           // Auto-generated
+  Operator: ConditionOperatorType;       // PascalCase
+  LHSField: keyof T | string;
+  RHSValue: any;
+  RHSType?: "Constant" | "BDOField" | "AppVariable";
 }
-```
 
-### Change Group Operator
-
-Toggle between AND/OR for a group.
-
-```tsx
-import { useState } from "react";
-import { useFilter, ConditionOperator, GroupOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import type { ConditionGroupType } from "@ram_28/kf-ai-sdk/filter/types";
-
-function ToggleableGroupOperator() {
-  const filter = useFilter();
-  const [groupId, setGroupId] = useState<string | null>(null);
-
-  // Generic example - for real usage, use bdo.field.id for LHSField
-  const createGroup = () => {
-    const id = filter.addConditionGroup(GroupOperator.And);
-    filter.addCondition(
-      { Operator: ConditionOperator.EQ, LHSField: "FieldA", RHSValue: 1, RHSType: RHSType.Constant },
-      id,
-    );
-    filter.addCondition(
-      { Operator: ConditionOperator.EQ, LHSField: "FieldB", RHSValue: 2, RHSType: RHSType.Constant },
-      id,
-    );
-    setGroupId(id);
-  };
-
-  const toggleOperator = () => {
-    if (groupId) {
-      const group = filter.getCondition(groupId) as ConditionGroupType;
-      const newOp = group.Operator === GroupOperator.And ? GroupOperator.Or : GroupOperator.And;
-      filter.updateGroupOperator(groupId, newOp);
-    }
-  };
-
-  return (
-    <div>
-      <button onClick={createGroup}>Create Group</button>
-      {groupId && <button onClick={toggleOperator}>Toggle AND/OR</button>}
-    </div>
-  );
+interface ConditionGroupType<T = any> {
+  id?: string;
+  Operator: "And" | "Or" | "Not";
+  Condition: Array<ConditionType<T> | ConditionGroupType<T>>;
 }
-```
-
----
-
-## Using Filter Payload
 
-### Get API-Ready Payload
-
-Access the filter structure for API calls.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "../bdo/buyer/Product";
-
-function FilterWithApi() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const filter = useFilter();
-
-  const fetchFiltered = async () => {
-    const payload = filter.payload;
-
-    if (!payload) {
-      console.log("No filters applied");
-      return;
-    }
-
-    // Payload is ready for API - no internal IDs included
-    const response = await fetch("/api/products", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ Filter: payload }),
-    });
-
-    return response.json();
-  };
-
-  return (
-    <div>
-      <button
-        onClick={() =>
-          filter.addCondition({
-            Operator: ConditionOperator.EQ,
-            LHSField: product.Status.id,
-            RHSValue: "Active",
-            RHSType: RHSType.Constant,
-          })
-        }
-      >
-        Add Filter
-      </button>
-      <button onClick={fetchFiltered}>Fetch Data</button>
-
-      <pre>{JSON.stringify(filter.payload, null, 2)}</pre>
-    </div>
-  );
+interface UseFilterOptionsType<T = any> {    // lowercase — hook init
+  conditions?: Array<ConditionType<T> | ConditionGroupType<T>>;
+  operator?: "And" | "Or" | "Not";
 }
-```
-
-### Initialize with Existing Filters
-
-Load filters from saved state.
-
-```tsx
-import { useMemo } from "react";
-import { useFilter, ConditionOperator, GroupOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import type { ConditionType, ConditionGroupType } from "@ram_28/kf-ai-sdk/filter/types";
-import { BuyerProduct } from "../bdo/buyer/Product";
 
-function FilterWithInitialState() {
-  const product = useMemo(() => new BuyerProduct(), []);
-
-  const savedFilters: Array<ConditionType | ConditionGroupType> = [
-    {
-      Operator: ConditionOperator.EQ,
-      LHSField: product.Status.id,
-      RHSValue: "Active",
-      RHSType: RHSType.Constant,
-    },
-    {
-      Operator: ConditionOperator.GT,
-      LHSField: product.Price.id,
-      RHSValue: 100,
-      RHSType: RHSType.Constant,
-    },
-  ];
-
-  const filter = useFilter({
-    conditions: savedFilters,
-    operator: GroupOperator.And,
-  });
-
-  return (
-    <div>
-      <p>Loaded {filter.items.length} filters</p>
-      {/* filter UI */}
-    </div>
-  );
+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;
 }
 ```
 
 ---
 
-## Payload Structure
-
-The `filter.payload` property returns the filter structure ready for API consumption. Here are examples of what the JSON looks like for different scenarios.
-
-### Single Condition
-
-```tsx
-import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-
-filter.addCondition({
-  Operator: ConditionOperator.EQ,
-  LHSField: product.Status.id,
-  RHSValue: "Active",
-  RHSType: RHSType.Constant,
-});
-```
-
-Produces:
-
-```json
-{
-  "Operator": "And",
-  "Condition": [
-    {
-      "Operator": "EQ",
-      "LHSField": "Status",
-      "RHSValue": "Active",
-      "RHSType": "Constant"
-    }
-  ]
-}
-```
-
-### Multiple Conditions (AND)
+## Usage Example
 
 ```tsx
-import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-
-filter.addCondition({
-  Operator: ConditionOperator.EQ,
-  LHSField: product.Category.id,
-  RHSValue: "Electronics",
-  RHSType: RHSType.Constant,
-});
-filter.addCondition({
-  Operator: ConditionOperator.GT,
-  LHSField: product.Price.id,
-  RHSValue: 100,
-  RHSType: RHSType.Constant,
-});
-filter.addCondition({
-  Operator: ConditionOperator.LTE,
-  LHSField: product.Stock.id,
-  RHSValue: 50,
-  RHSType: RHSType.Constant,
-});
-```
+import { useFilter, ConditionOperator, GroupOperator, FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+import type { UseFilterOptionsType } from "@ram_28/kf-ai-sdk/filter/types";
 
-Produces:
+// 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 });
 
-```json
-{
-  "Operator": "And",
-  "Condition": [
-    {
-      "Operator": "EQ",
-      "LHSField": "Category",
-      "RHSValue": "Electronics",
-      "RHSType": "Constant"
-    },
-    {
-      "Operator": "GT",
-      "LHSField": "Price",
-      "RHSValue": 100,
-      "RHSType": "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,
     },
-    {
-      "Operator": "LTE",
-      "LHSField": "Stock",
-      "RHSValue": 50,
-      "RHSType": "Constant"
-    }
-  ]
-}
-```
-
-### Nested Groups
-
-```tsx
-import { ConditionOperator, GroupOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-
-// Root: AND
-// Category = "Electronics" AND (Price < 100 OR OnSale = true)
-filter.addCondition({
-  Operator: ConditionOperator.EQ,
-  LHSField: product.Category.id,
-  RHSValue: "Electronics",
-  RHSType: RHSType.Constant,
-});
-const orGroupId = filter.addConditionGroup(GroupOperator.Or);
-filter.addCondition(
-  {
-    Operator: ConditionOperator.LT,
-    LHSField: product.Price.id,
-    RHSValue: 100,
-    RHSType: RHSType.Constant,
-  },
-  orGroupId,
-);
-filter.addCondition(
-  {
-    Operator: ConditionOperator.EQ,
-    LHSField: product.OnSale.id,
-    RHSValue: true,
-    RHSType: RHSType.Constant,
   },
-  orGroupId,
-);
-```
-
-Produces:
-
-```json
-{
-  "Operator": "And",
-  "Condition": [
-    {
-      "Operator": "EQ",
-      "LHSField": "Category",
-      "RHSValue": "Electronics",
-      "RHSType": "Constant"
-    },
-    {
-      "Operator": "Or",
-      "Condition": [
-        {
-          "Operator": "LT",
-          "LHSField": "Price",
-          "RHSValue": 100,
-          "RHSType": "Constant"
-        },
-        {
-          "Operator": "EQ",
-          "LHSField": "OnSale",
-          "RHSValue": true,
-          "RHSType": "Constant"
-        }
-      ]
-    }
-  ]
-}
-```
-
-### Range Values (Between)
-
-```tsx
-import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-
-filter.addCondition({
-  Operator: ConditionOperator.Between,
-  LHSField: product.Price.id,
-  RHSValue: [50, 200],
-  RHSType: RHSType.Constant,
-});
-```
-
-Produces:
-
-```json
-{
-  "Operator": "And",
-  "Condition": [
-    {
-      "Operator": "Between",
-      "LHSField": "Price",
-      "RHSValue": [50, 200],
-      "RHSType": "Constant"
-    }
-  ]
-}
-```
-
-### List Values (IN)
-
-```tsx
-import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-
-filter.addCondition({
-  Operator: ConditionOperator.IN,
-  LHSField: product.Category.id,
-  RHSValue: ["Electronics", "Computers", "Accessories"],
-  RHSType: RHSType.Constant,
 });
-```
-
-Produces:
-
-```json
-{
-  "Operator": "And",
-  "Condition": [
-    {
-      "Operator": "IN",
-      "LHSField": "Category",
-      "RHSValue": ["Electronics", "Computers", "Accessories"],
-      "RHSType": "Constant"
-    }
-  ]
-}
-```
-
-> **Note:** The `RHSType` field defaults to `"Constant"` and is automatically added to the payload. Other possible values are `"BDOField"` (reference another BDO field) and `"AppVariable"` (reference an application variable).
-
-### Reference Field (EQ)
-
-```tsx
-import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-
-filter.addCondition({
-  Operator: ConditionOperator.EQ,
-  LHSField: cartItem.ProductInfo.id,
-  RHSValue: "PROD_001",
-  RHSType: RHSType.Constant,
-});
-```
-
-Produces:
-
-```json
-{
-  "Operator": "And",
-  "Condition": [
-    {
-      "Operator": "EQ",
-      "LHSField": "ProductInfo",
-      "RHSValue": "PROD_001",
-      "RHSType": "Constant"
-    }
-  ]
-}
-```
-
-### Reference Field Nested Path (Contains)
-
-```tsx
-filter.addCondition({
-  Operator: ConditionOperator.Contains,
-  LHSField: `${cartItem.ProductInfo.id}._name`,
-  RHSValue: "Widget",
-  RHSType: RHSType.Constant,
-});
-```
 
-Produces:
-
-```json
-{
-  "Operator": "And",
-  "Condition": [
-    {
-      "Operator": "Contains",
-      "LHSField": "ProductInfo._name",
-      "RHSValue": "Widget",
-      "RHSType": "Constant"
-    }
-  ]
-}
-```
-
-### Field-to-Field Comparison (BDOField)
-
-Use `RHSType.BDOField` to compare one field against another field instead of a constant value.
-
-```tsx
-// Filter where Quantity exceeds Stock (field vs field)
-filter.addCondition({
-  Operator: ConditionOperator.GT,
-  LHSField: cartItem.Quantity.id,
-  RHSValue: cartItem.Stock.id,
-  RHSType: RHSType.BDOField,
-});
-```
-
-Produces:
-
-```json
-{
-  "Operator": "And",
-  "Condition": [
-    {
-      "Operator": "GT",
-      "LHSField": "Quantity",
-      "RHSValue": "Stock",
-      "RHSType": "BDOField"
-    }
-  ]
-}
-```
-
----
-
-## Common Mistakes
-
-### 1. Inventing RHSType values
-
-Only three RHSType values exist. Any other string causes TS2322.
-
-```typescript
-// ❌ WRONG — these values don't exist
-{ RHSType: "Value" }
-{ RHSType: "Literal" }
-{ RHSType: "Field" }
-
-// ✅ CORRECT — only these three values
-{ RHSType: RHSType.Constant }    // "Constant"
-{ RHSType: RHSType.BDOField }    // "BDOField"
-{ RHSType: RHSType.AppVariable } // "AppVariable"
-```
-
-### 2. Accessing `filter.conditions` instead of `filter.items`
-
-`UseFilterReturnType` does NOT have a `conditions` property. The conditions array is called `items`.
-
-```typescript
-// ❌ WRONG — conditions does NOT exist on UseFilterReturnType
-filter.conditions
-filter.conditions.length
-
-// ✅ CORRECT — use items
-filter.items
-filter.items.length
-filter.hasConditions  // boolean shortcut
-```
-
-### 3. Mixing hook init format with API format
-
-`UseFilterOptionsType` (for hook initialization) uses lowercase. `FilterType` (for API calls) uses uppercase. NEVER mix them.
-
-```typescript
-// Hook initialization (UseFilterOptionsType) — lowercase, plural
-useTable({
-  initialState: {
-    filter: { conditions: [...], operator: "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 });
   }
-});
-
-// API calls (FilterType) — uppercase, singular
-bdo.list({
-  Filter: { Operator: "And", Condition: [...] }
-});
-```
-
-### 4. Using `as const` on Operator values
-
-```typescript
-// ❌ WRONG — as const causes TypeScript narrowing errors in arrays
-const conditions = [
-  { Operator: ConditionOperator.EQ as const, ... }
-];
-
-// ✅ CORRECT — type the array instead
-const conditions: Omit<ConditionType, "id">[] = [
-  { Operator: ConditionOperator.EQ, ... }
-];
-```
-
-### 5. Filtering Reference/User fields without _id
+}, [status]);
 
-The backend automatically targets `_id` when you filter a Reference or User field by name. Do NOT manually append `._id` unless you specifically want to bypass the backend's auto-extraction.
-
-```typescript
-// ❌ WRONG — unnecessary, and disables auto-extraction of _id from objects
-{ LHSField: "ProductInfo._id", Operator: "EQ", RHSValue: { _id: "P1", _name: "Widget" } }
-
-// ✅ CORRECT — backend auto-targets _id
-{ LHSField: "ProductInfo", Operator: "EQ", RHSValue: "P1" }
-
-// ✅ CORRECT — backend extracts _id from the object
-{ LHSField: "ProductInfo", Operator: "EQ", RHSValue: { _id: "P1", _name: "Widget" } }
-
-// ✅ CORRECT — dot notation for filtering by _name
-{ LHSField: "ProductInfo._name", Operator: "Contains", RHSValue: "Widget" }
+// 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);
 ```