@ram_28/kf-ai-sdk 2.0.16 → 2.0.18

package/docs/useBDOTable/api_reference.md

@@ -0,0 +1,253 @@
+# useBDOTable API Reference
+
+```tsx
+import { useBDOTable } from '@ram_28/kf-ai-sdk/table';
+import type {
+  UseBDOTableOptionsType,
+  UseBDOTableReturnType,
+  PaginationStateType,
+} from '@ram_28/kf-ai-sdk/table/types';
+```
+
+## Signature
+
+```tsx
+const table: UseBDOTableReturnType<ProductBdo> = useBDOTable(options: UseBDOTableOptionsType<ProductBdo>);
+```
+
+## Options
+
+`UseBDOTableOptionsType<B>`
+
+- `bdo: B`
+  - **Required**
+  - BDO instance with `list()` and `count()` methods. Must be memoized with `useMemo()`.
+- `initialState`
+  - **Optional**
+  - Object with:
+    - `sort?: SortType` — Initial sort configuration. Format: `[{ "fieldName": "ASC" }]`
+    - `pagination?: PaginationStateType` — Initial page and page size. Defaults to `{ pageNo: 1, pageSize: 10 }`.
+    - `filter?: UseFilterOptionsType<T>` — Initial filter conditions and operator.
+- `onError?: (error: Error) => void`
+  - **Optional**
+  - Called when a list or count fetch fails.
+- `onSuccess?: (data: T[]) => void`
+  - **Optional**
+  - Called with the current page rows after a successful list fetch.
+
+## Return Value
+
+`UseBDOTableReturnType<B>`
+
+Alias for `UseTableReturnType<BDORowType<B>>`. `BDORowType<B>` resolves to `ItemType<TEditable, TReadonly>` — inferred from the BDO's `list()` return type. Rows are proxy objects with `.get()` accessors, not plain objects.
+
+### Data
+
+- `rows: ItemType<TEditable, TReadonly>[]`
+  - Array of `ItemType` instances for the current page. Access field values via `.get()` (e.g. `row.Title.get()`), not direct property access. Empty array during initial loading.
+- `totalItems: number`
+  - Total number of records matching the current filters and search. `0` while count is loading.
+
+### Loading & Error
+
+- `isLoading: boolean`
+  - `true` during the initial load of both list and count queries.
+- `isFetching: boolean`
+  - `true` during any fetch including background refetches for list or count.
+- `error: Error | null`
+  - Most recent fetch error from either list or count query. `null` when no error.
+
+### Search
+
+- `search.query: string`
+  - Current search input value (updated immediately on `set()`).
+- `search.field: keyof T | null`
+  - The field currently being searched. `null` when no search is active.
+- `search.set(field: keyof T, query: string): void`
+  - Set the search field and query. The input value updates immediately; the API query is debounced by 300 ms. Pagination resets to page 1 after the debounce. Query is capped at 255 characters.
+- `search.clear(): void`
+  - Clear the search field and query. Pagination resets to page 1.
+
+### Sort
+
+- `sort.field: keyof T | null`
+  - Currently sorted field. `null` when no sort is active.
+- `sort.direction: "ASC" | "DESC" | null`
+  - Current sort direction. `null` when no sort is active.
+- `sort.toggle(field: keyof T): void`
+  - Cycle the sort for a field: ASC -> DESC -> cleared. If a different field was sorted, starts at ASC.
+- `sort.clear(): void`
+  - Remove all sorting.
+- `sort.set(field: keyof T | null, direction: "ASC" | "DESC" | null): void`
+  - Explicitly set the sort field and direction.
+
+### Filter
+
+- `filter: UseFilterReturnType<T>`
+  - Full filter state and operations. See [useFilter reference](../useFilter/api_reference.md) for the complete API.
+
+### Pagination
+
+- `pagination.pageNo: number`
+  - Current page number (1-indexed).
+- `pagination.pageSize: number`
+  - Current number of items per page.
+- `pagination.totalPages: number`
+  - Total number of pages based on `totalItems` and `pageSize`.
+- `pagination.totalItems: number`
+  - Same as the top-level `totalItems`.
+- `pagination.canGoNext: boolean`
+  - `true` when a next page exists.
+- `pagination.canGoPrevious: boolean`
+  - `true` when a previous page exists (i.e. `pageNo > 1`).
+- `pagination.goToNext(): void`
+  - Navigate to the next page. No-op if already on the last page.
+- `pagination.goToPrevious(): void`
+  - Navigate to the previous page. No-op if already on page 1.
+- `pagination.goToPage(page: number): void`
+  - Navigate to a specific page. Clamped to `[1, totalPages]`.
+- `pagination.setPageSize(size: number): void`
+  - Change the page size. Resets to page 1.
+
+### Operations
+
+- `refetch(): Promise<ListResponseType<T>>`
+  - Manually refetch both the list and count queries. Returns the list response.
+
+## Exported Constants
+
+Available from `@ram_28/kf-ai-sdk/table`:
+
+```typescript
+import { SortDirection, TableDefaults } from '@ram_28/kf-ai-sdk/table';
+```
+
+**SortDirection**
+
+| Key | Value |
+|-----|-------|
+| `ASC` | `"ASC"` |
+| `DESC` | `"DESC"` |
+
+**TableDefaults**
+
+| Key | Value | Description |
+|-----|-------|-------------|
+| `SEARCH_DEBOUNCE_MS` | `300` | Debounce delay for search (ms) |
+| `PAGE_SIZE` | `10` | Default items per page |
+| `PAGE` | `1` | Default page number (1-indexed) |
+| `SEARCH_MAX_LENGTH` | `255` | Maximum search query length |
+
+For filter constants (`ConditionOperator`, `GroupOperator`, `RHSType`), see [useFilter reference](../useFilter/api_reference.md).
+
+## Types
+
+```typescript
+import type { ItemType } from '@ram_28/kf-ai-sdk/bdo/types';
+
+// ============================================================
+// Options
+// ============================================================
+
+interface UseBDOTableOptionsType<B extends BDOTableSourceType> {
+  bdo: B;
+  initialState?: {
+    sort?: SortType;
+    pagination?: PaginationStateType;
+    filter?: UseFilterOptionsType<BDORowType<B>>;
+  };
+  onError?: (error: Error) => void;
+  onSuccess?: (data: BDORowType<B>[]) => void;
+}
+
+// ============================================================
+// Return type
+// ============================================================
+
+type UseBDOTableReturnType<B extends BDOTableSourceType> =
+  UseTableReturnType<BDORowType<B>>;
+
+// When used via UseBDOTableReturnType<B>, T = ItemType<TEditable, TReadonly>
+// ItemType<TEditable, TReadonly> provides:
+//   row._id: string                            (direct access, no .get())
+//   row.Field.get(): value                     (read field value)
+//   row.Field.set(value): void                 (editable fields only)
+//   row.Field.validate(): ValidationResultType (single field)
+//   row.Field.label / .required / .readOnly / .defaultValue / .meta
+//   row.toJSON(): plain object
+//   row.validate(): ValidationResultType       (all fields)
+interface UseTableReturnType<T> {
+  // Data
+  rows: T[];
+  totalItems: number;
+
+  // Loading States
+  isLoading: boolean;
+  isFetching: boolean;
+
+  // Error Handling
+  error: Error | null;
+
+  // Search
+  search: {
+    query: string;
+    field: keyof T | null;
+    set: (field: keyof T, query: string) => void;
+    clear: () => void;
+  };
+
+  // Sorting
+  sort: {
+    field: keyof T | null;
+    direction: 'ASC' | 'DESC' | null;
+    toggle: (field: keyof T) => void;
+    clear: () => void;
+    set: (field: keyof T | null, direction: 'ASC' | 'DESC' | null) => void;
+  };
+
+  // Filter
+  filter: UseFilterReturnType<T>;
+
+  // Pagination
+  pagination: {
+    pageNo: number;
+    pageSize: number;
+    totalPages: number;
+    totalItems: number;
+    canGoNext: boolean;
+    canGoPrevious: boolean;
+    goToNext: () => void;
+    goToPrevious: () => void;
+    goToPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+  };
+
+  // Operations
+  refetch: () => Promise<ListResponseType<T>>;
+}
+
+// ============================================================
+// State types
+// ============================================================
+
+interface PaginationStateType {
+  pageNo: number;
+  pageSize: number;
+}
+
+// ============================================================
+// Sort
+// ============================================================
+
+type SortOptionType = Record<string, 'ASC' | 'DESC'>;
+type SortType = SortOptionType[];
+
+// Filter types — see useFilter reference (../useFilter/api_reference.md)
+
+// ============================================================
+// Row type inference
+// ============================================================
+
+type BDORowType<B extends BDOTableSourceType> =
+  B extends { list(opts?: any): Promise<(infer R)[]> } ? R : never;
+```

package/docs/useFilter/README.md

@@ -0,0 +1,323 @@
+# useFilter
+
+Standalone filter state manager for building composable filter conditions with nested groups.
+
+## When to Use
+
+**Use `useFilter` when:**
+
+- Building a standalone filter panel or sidebar outside of a table
+- You need a composable condition tree with nested AND/OR/NOT groups
+- Managing filter state that feeds into a custom data fetch
+
+**Use something else when:**
+
+- Filtering a BDO table — use [`useBDOTable`](../useBDOTable/README.md) (includes useFilter at `table.filter`)
+- Filtering an activity table — use [`useActivityTable`](../useActivityTable/README.md) (includes useFilter at `table.filter`)
+
+## Imports
+
+```tsx
+import { useFilter, ConditionOperator, GroupOperator, FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+import { isCondition, isConditionGroup } from "@ram_28/kf-ai-sdk/filter";
+```
+
+## Quick Start
+
+```tsx
+import { useMemo } from "react";
+import { useFilter, ConditionOperator, FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+import { AdminProduct } from "@/bdo/admin/Product";
+import type { AdminProductFieldType } from "@/bdo/admin/Product";
+
+function ProductFilter() {
+  const bdo = useMemo(() => new AdminProduct(), []);
+  const filter = useFilter<AdminProductFieldType>();
+
+  const applyStatusFilter = (status: string) => {
+    filter.clearAllConditions();
+    if (status !== "all") {
+      filter.addCondition({
+        Operator: ConditionOperator.EQ,
+        LHSField: bdo.status.id,
+        RHSValue: status,
+        RHSType: FilterValueSource.Constant,
+      });
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={() => applyStatusFilter("Active")}>Active</button>
+      <button onClick={() => applyStatusFilter("all")}>All</button>
+      <p>{filter.hasConditions ? "Filtering active" : "No filters"}</p>
+      {filter.payload && <pre>{JSON.stringify(filter.payload, null, 2)}</pre>}
+    </div>
+  );
+}
+```
+
+## Usage Guide
+
+### Adding Conditions
+
+Add leaf conditions with `addCondition()`. Each condition uses PascalCase properties: `Operator`, `LHSField`, `RHSValue`, and optionally `RHSType`. Always use constants instead of string literals.
+
+```tsx
+import { ConditionOperator, FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+
+// Exact match
+filter.addCondition({
+  Operator: ConditionOperator.EQ,
+  LHSField: bdo.category.id,
+  RHSValue: "Electronics",
+  RHSType: FilterValueSource.Constant,
+});
+
+// Range filter
+filter.addCondition({
+  Operator: ConditionOperator.Between,
+  LHSField: bdo.unit_price.id,
+  RHSValue: [100, 500],
+  RHSType: FilterValueSource.Constant,
+});
+
+// String search
+filter.addCondition({
+  Operator: ConditionOperator.Contains,
+  LHSField: bdo.description.id,
+  RHSValue: "wireless",
+  RHSType: FilterValueSource.Constant,
+});
+```
+
+### Tracking and Removing by ID
+
+`addCondition()` returns an auto-generated ID string. Store the ID to later remove or look up the condition. IDs are internal state-management artifacts -- they are stripped from `payload` automatically.
+
+```tsx
+const [statusId, setStatusId] = useState<string | null>(null);
+
+const applyStatusFilter = (status: string) => {
+  // Remove existing status condition if present
+  if (statusId) {
+    filter.removeCondition(statusId);
+    setStatusId(null);
+  }
+
+  // Add new condition and store its ID
+  if (status !== "all") {
+    const id = filter.addCondition({
+      Operator: ConditionOperator.EQ,
+      LHSField: bdo.status.id,
+      RHSValue: status,
+      RHSType: FilterValueSource.Constant,
+    });
+    setStatusId(id);
+  }
+};
+```
+
+### Updating Conditions
+
+Update a leaf condition's properties without removing and re-adding it. Use `updateCondition()` for leaf conditions and `updateGroupOperator()` for groups:
+
+```tsx
+// Change the comparison value on an existing condition
+filter.updateCondition(conditionId, {
+  RHSValue: "Books",
+});
+
+// Change a group's operator from And to Or
+filter.updateGroupOperator(groupId, GroupOperator.Or);
+```
+
+### Nested Groups
+
+Build arbitrarily deep condition trees using `addConditionGroup()`. Pass a `parentId` to nest groups inside other groups, and pass a `parentId` to `addCondition()` to add leaf conditions inside a group.
+
+This example constructs: `Status = "Active" AND (Category = "Electronics" AND Price < 500) OR (Category = "Books" AND Price < 50)`:
+
+```tsx
+import { useFilter, ConditionOperator, GroupOperator, FilterValueSource } from "@ram_28/kf-ai-sdk/filter";
+
+const filter = useFilter<AdminProductFieldType>();
+
+// Root-level condition
+filter.addCondition({
+  Operator: ConditionOperator.EQ,
+  LHSField: bdo.status.id,
+  RHSValue: "Active",
+  RHSType: FilterValueSource.Constant,
+});
+
+// Create an OR group at root level -- capture its ID
+const orGroupId = filter.addConditionGroup(GroupOperator.Or);
+
+// Nest an AND group inside the OR group for Electronics
+const electronicsGroupId = filter.addConditionGroup(GroupOperator.And, orGroupId);
+filter.addCondition(
+  {
+    Operator: ConditionOperator.EQ,
+    LHSField: bdo.category.id,
+    RHSValue: "Electronics",
+    RHSType: FilterValueSource.Constant,
+  },
+  electronicsGroupId
+);
+filter.addCondition(
+  {
+    Operator: ConditionOperator.LT,
+    LHSField: bdo.unit_price.id,
+    RHSValue: 500,
+    RHSType: FilterValueSource.Constant,
+  },
+  electronicsGroupId
+);
+
+// Nest another AND group inside the OR group for Books
+const booksGroupId = filter.addConditionGroup(GroupOperator.And, orGroupId);
+filter.addCondition(
+  {
+    Operator: ConditionOperator.EQ,
+    LHSField: bdo.category.id,
+    RHSValue: "Books",
+    RHSType: FilterValueSource.Constant,
+  },
+  booksGroupId
+);
+filter.addCondition(
+  {
+    Operator: ConditionOperator.LT,
+    LHSField: bdo.unit_price.id,
+    RHSValue: 50,
+    RHSType: FilterValueSource.Constant,
+  },
+  booksGroupId
+);
+
+// Resulting payload:
+// {
+//   Operator: "And",
+//   Condition: [
+//     { Operator: "EQ", LHSField: "status", RHSValue: "Active", RHSType: "Constant" },
+//     {
+//       Operator: "Or",
+//       Condition: [
+//         {
+//           Operator: "And",
+//           Condition: [
+//             { Operator: "EQ", LHSField: "category", RHSValue: "Electronics", RHSType: "Constant" },
+//             { Operator: "LT", LHSField: "unit_price", RHSValue: 500, RHSType: "Constant" },
+//           ],
+//         },
+//         {
+//           Operator: "And",
+//           Condition: [
+//             { Operator: "EQ", LHSField: "category", RHSValue: "Books", RHSType: "Constant" },
+//             { Operator: "LT", LHSField: "unit_price", RHSValue: 50, RHSType: "Constant" },
+//           ],
+//         },
+//       ],
+//     },
+//   ],
+// }
+```
+
+### Root Operator
+
+The root operator combines all top-level conditions. It defaults to `"And"` and can be set via the `operator` option or changed later with `setRootOperator()`:
+
+```tsx
+// Set at initialization
+const filter = useFilter<AdminProductFieldType>({
+  operator: "Or",
+});
+
+// Toggle between And and Or
+const toggleOperator = () => {
+  const next = filter.operator === GroupOperator.And ? GroupOperator.Or : GroupOperator.And;
+  filter.setRootOperator(next);
+};
+```
+
+### Reading State
+
+- **`items`** -- current conditions with IDs populated (use for UI rendering)
+- **`payload`** -- API-ready `FilterType` with IDs stripped. `undefined` when no conditions exist.
+- **`hasConditions`** -- convenience boolean (`items.length > 0`)
+- **`operator`** -- current root operator (`"And"`, `"Or"`, or `"Not"`)
+
+Guard with a falsy check before sending the payload:
+
+```tsx
+if (filter.payload) {
+  const results = await bdo.list({ Filter: filter.payload });
+}
+```
+
+### Integration with Table Hooks
+
+`useBDOTable` and `useActivityTable` embed a `useFilter` instance at `table.filter`. The API is identical -- `table.filter.addCondition()`, `table.filter.clearAllConditions()`, etc.
+
+```tsx
+const table = useBDOTable({
+  bdo: product,
+  initialState: {
+    filter: {
+      conditions: [
+        { Operator: ConditionOperator.EQ, LHSField: "status", RHSValue: "Active" },
+      ],
+      operator: "And",
+    },
+  },
+});
+
+// Same API as standalone useFilter
+table.filter.addCondition({ ... });
+table.filter.clearAllConditions();
+```
+
+- Filter changes automatically reset table pagination to page 1.
+- See [`useBDOTable`](../useBDOTable/README.md) and [`useActivityTable`](../useActivityTable/README.md) for full table documentation.
+
+### Iterating with Type Guards
+
+Use `isCondition()` and `isConditionGroup()` to distinguish between leaf conditions and groups when rendering the filter tree:
+
+```tsx
+import { isCondition, isConditionGroup } from "@ram_28/kf-ai-sdk/filter";
+
+filter.items.map((item) => {
+  if (isCondition(item)) {
+    return (
+      <li key={item.id}>
+        {String(item.LHSField)} {item.Operator} {String(item.RHSValue)}
+        <button onClick={() => filter.removeCondition(item.id!)}>Remove</button>
+      </li>
+    );
+  }
+  if (isConditionGroup(item)) {
+    return (
+      <li key={item.id}>
+        {item.Operator} group ({item.Condition.length} children)
+      </li>
+    );
+  }
+  return null;
+});
+```
+
+## Further Reading
+
+- [API Reference](./api_reference.md) -- All options, return values, constants, and type definitions
+- [Filtered Product Table](../examples/bdo/filtered-product-table.md) -- BDO table with category + price range filters
+- [Filtered Activity Table](../examples/workflow/filtered-activity-table.md) -- Activity table with date range filter
+
+## Common Mistakes
+
+- **Don't read `filter.conditions`** -- the property is `filter.items`.
+- **Don't expect `payload` to be an empty object when empty** -- it's `undefined`. Use a simple falsy check: `if (filter.payload) { ... }`.
+- **Don't use string literals** -- use `ConditionOperator.EQ`, `GroupOperator.And`, `FilterValueSource.Constant` instead.
+- **Don't expect IDs in `payload`** -- they're stripped automatically before the payload is built.
+- **Don't mix PascalCase and camelCase** -- condition properties are PascalCase (`Operator`, `LHSField`, `RHSValue`, `RHSType`), while hook options are camelCase (`conditions`, `operator`).