@ram_28/kf-ai-sdk 1.0.16 → 1.0.19

package/docs/useTable.md

@@ -0,0 +1,372 @@
+# useTable
+
+## Brief Description
+
+- Provides complete table state management including data fetching, sorting, filtering, search, and pagination
+- Integrates with `useFilter` for advanced filtering capabilities with nested condition groups
+- Handles API interactions automatically using React Query for caching and background refetching
+- Returns flattened state accessors (`sort.field`, `pagination.currentPage`) for easy component integration
+
+## Type Reference
+
+```typescript
+import { useTable } from "@ram_28/kf-ai-sdk/table";
+import { isCondition, isConditionGroup } from "@ram_28/kf-ai-sdk/filter";
+import type {
+  UseTableOptionsType,
+  UseTableReturnType,
+  ColumnDefinitionType,
+} from "@ram_28/kf-ai-sdk/table/types";
+import type {
+  ConditionType,
+  ConditionGroupType,
+  ConditionOperatorType,
+  ConditionGroupOperatorType,
+  FilterType,
+  UseFilterReturnType,
+} from "@ram_28/kf-ai-sdk/filter/types";
+import type { ListResponseType } from "@ram_28/kf-ai-sdk/api/types";
+
+// Condition operators for comparing field values
+type ConditionOperatorType =
+  | "EQ" | "NE" | "GT" | "GTE" | "LT" | "LTE"
+  | "Between" | "NotBetween"
+  | "IN" | "NIN"
+  | "Empty" | "NotEmpty"
+  | "Contains" | "NotContains"
+  | "MinLength" | "MaxLength";
+
+// Group operators for combining conditions
+type ConditionGroupOperatorType = "And" | "Or" | "Not";
+
+// Column configuration
+interface ColumnDefinitionType<T> {
+  fieldId: keyof T;
+  label?: string;
+  enableSorting?: boolean;
+  enableFiltering?: boolean;
+  transform?: (value: any, row: T) => React.ReactNode;
+}
+
+// Hook options
+interface UseTableOptionsType<T> {
+  source: string;
+  columns: ColumnDefinitionType<T>[];
+  enableSorting?: boolean;
+  enableFiltering?: boolean;
+  enablePagination?: boolean;
+  initialState?: {
+    pagination?: { pageNo: number; pageSize: number };
+    sorting?: { field: keyof T; direction: "asc" | "desc" };
+    filters?: Array<ConditionType | ConditionGroupType>;
+    filterOperator?: ConditionGroupOperatorType;
+  };
+  onError?: (error: Error) => void;
+  onSuccess?: (data: T[]) => void;
+}
+
+// Hook return type
+interface UseTableReturnType<T> {
+  // Data
+  rows: T[];
+  totalItems: number;
+
+  // Loading states
+  isLoading: boolean;
+  isFetching: boolean;
+  error: Error | null;
+
+  // Search
+  search: {
+    query: string;
+    setQuery: (value: string) => void;
+    clear: () => void;
+  };
+
+  // Sort
+  sort: {
+    field: keyof T | null;
+    direction: "asc" | "desc" | null;
+    toggle: (field: keyof T) => void;
+    clear: () => void;
+    set: (field: keyof T, direction: "asc" | "desc") => void;
+  };
+
+  // Filter (uses useFilter internally)
+  filter: UseFilterReturnType;
+
+  // Pagination
+  pagination: {
+    currentPage: 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>>;
+}
+
+// API response structure
+interface ListResponseType<T> {
+  Data: T[];
+}
+```
+
+## Usage Example
+
+```tsx
+import { useTable } from "@ram_28/kf-ai-sdk/table";
+import { isCondition, isConditionGroup } from "@ram_28/kf-ai-sdk/filter";
+import type {
+  UseTableOptionsType,
+  UseTableReturnType,
+  ColumnDefinitionType,
+} from "@ram_28/kf-ai-sdk/table/types";
+import type {
+  ConditionType,
+  ConditionGroupType,
+  ConditionOperatorType,
+  ConditionGroupOperatorType,
+  FilterType,
+  UseFilterReturnType,
+} from "@ram_28/kf-ai-sdk/filter/types";
+import type { ListResponseType } from "@ram_28/kf-ai-sdk/api/types";
+import { Product, ProductType } from "../sources";
+import { Roles } from "../sources/roles";
+
+// Get the typed product for the Buyer role
+type BuyerProduct = ProductType<typeof Roles.Buyer>;
+
+function ProductsPage() {
+  // Instantiate the Product source with role
+  const product = new Product(Roles.Buyer);
+
+  // Column definitions with type safety
+  const columns: ColumnDefinitionType<BuyerProduct>[] = [
+    { fieldId: "Title", label: "Name", enableSorting: true },
+    {
+      fieldId: "Price",
+      label: "Price",
+      enableSorting: true,
+      transform: (value) => `$${value.toFixed(2)}`,
+    },
+    { fieldId: "Category", label: "Category", enableSorting: true, enableFiltering: true },
+    { fieldId: "Stock", label: "Stock", enableSorting: true },
+  ];
+
+  // Hook configuration with full options
+  const options: UseTableOptionsType<BuyerProduct> = {
+    source: product._id, // Use the Business Object ID from the Product class
+    columns,
+    enableSorting: true,
+    enableFiltering: true,
+    enablePagination: true,
+    initialState: {
+      pagination: { pageNo: 1, pageSize: 10 },
+      sorting: { field: "_created_at", direction: "desc" },
+      filterOperator: "And",
+    },
+    onError: (error: Error) => console.error("Table error:", error.message),
+    onSuccess: (data: BuyerProduct[]) => console.log("Loaded", data.length, "products"),
+  };
+
+  const table: UseTableReturnType<BuyerProduct> = useTable<BuyerProduct>(options);
+
+  // Access filter functionality (UseFilterReturnType)
+  const filterState: UseFilterReturnType = table.filter;
+
+  // Add a filter with dynamic operator selection
+  const addFilter = (field: keyof BuyerProduct, operator: ConditionOperatorType, value: any) => {
+    table.filter.addCondition({
+      Operator: operator,
+      LHSField: field as string,
+      RHSValue: value,
+    });
+  };
+
+  // Add a simple filter condition
+  const filterByCategory = (category: string) => {
+    table.filter.clearAllConditions();
+    addFilter("Category", "EQ", category);
+  };
+
+  // Add a complex nested filter (Price > 100 OR Stock < 10)
+  const addComplexFilter = () => {
+    const groupId = table.filter.addConditionGroup("Or");
+    table.filter.addCondition({ Operator: "GT", LHSField: "Price", RHSValue: 100 }, groupId);
+    table.filter.addCondition({ Operator: "LT", LHSField: "Stock", RHSValue: 10 }, groupId);
+  };
+
+  // Display active filters using type guards
+  const renderActiveFilters = () => (
+    <div className="active-filters">
+      {table.filter.items.map((item) => {
+        if (isCondition(item)) {
+          return (
+            <span key={item.id} className="filter-tag">
+              {item.LHSField} {item.Operator} {String(item.RHSValue)}
+              <button onClick={() => table.filter.removeCondition(item.id!)}>×</button>
+            </span>
+          );
+        }
+        if (isConditionGroup(item)) {
+          return (
+            <span key={item.id} className="filter-group-tag">
+              {item.Operator} Group ({item.Condition.length} conditions)
+              <button onClick={() => table.filter.removeCondition(item.id!)}>×</button>
+            </span>
+          );
+        }
+        return null;
+      })}
+    </div>
+  );
+
+  // Toggle filter logic operator
+  const toggleFilterLogic = () => {
+    const next: ConditionGroupOperatorType = table.filter.operator === "And" ? "Or" : "And";
+    table.filter.setRootOperator(next);
+  };
+
+  // Refetch data manually
+  const handleRefresh = async () => {
+    const response: ListResponseType<BuyerProduct> = await table.refetch();
+    console.log(`Refreshed: ${response.Data.length} items`);
+  };
+
+  // Access filter payload for debugging
+  const getFilterPayload = (): FilterType | undefined => {
+    return table.filter.payload;
+  };
+
+  if (table.isLoading) {
+    return <div>Loading products...</div>;
+  }
+
+  if (table.error) {
+    return <div>Error: {table.error.message}</div>;
+  }
+
+  return (
+    <div className="products-page">
+      {/* Search */}
+      <div className="search-bar">
+        <input
+          type="text"
+          placeholder="Search products..."
+          value={table.search.query}
+          onChange={(e) => table.search.setQuery(e.target.value)}
+        />
+        <button onClick={table.search.clear}>Clear</button>
+      </div>
+
+      {/* Filter Controls */}
+      <div className="filter-controls">
+        <button onClick={() => filterByCategory("Electronics")}>Electronics</button>
+        <button onClick={() => filterByCategory("Books")}>Books</button>
+        <button onClick={addComplexFilter}>Add Complex Filter</button>
+        <button onClick={toggleFilterLogic}>
+          Logic: {table.filter.operator}
+        </button>
+        {table.filter.hasConditions && (
+          <button onClick={() => table.filter.clearAllConditions()}>Clear All Filters</button>
+        )}
+      </div>
+
+      {/* Active Filters */}
+      {renderActiveFilters()}
+
+      {/* Table */}
+      <table>
+        <thead>
+          <tr>
+            {columns.map((col) => (
+              <th
+                key={String(col.fieldId)}
+                onClick={() => col.enableSorting && table.sort.toggle(col.fieldId)}
+                style={{ cursor: col.enableSorting ? "pointer" : "default" }}
+              >
+                {col.label || String(col.fieldId)}
+                {table.sort.field === col.fieldId && (
+                  <span>{table.sort.direction === "asc" ? " ↑" : " ↓"}</span>
+                )}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {table.rows.map((row: BuyerProduct) => (
+            <tr key={row._id}>
+              <td>{row.Title}</td>
+              <td>${row.Price.toFixed(2)}</td>
+              <td>{row.Category}</td>
+              <td>{row.Stock}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      {/* Pagination */}
+      <div className="pagination">
+        <button
+          onClick={table.pagination.goToPrevious}
+          disabled={!table.pagination.canGoPrevious}
+        >
+          Previous
+        </button>
+        <span>
+          Page {table.pagination.currentPage} of {table.pagination.totalPages}
+          ({table.pagination.totalItems} total)
+        </span>
+        <button
+          onClick={table.pagination.goToNext}
+          disabled={!table.pagination.canGoNext}
+        >
+          Next
+        </button>
+        <select
+          value={table.pagination.pageSize}
+          onChange={(e) => table.pagination.setPageSize(Number(e.target.value))}
+        >
+          <option value={10}>10 per page</option>
+          <option value={25}>25 per page</option>
+          <option value={50}>50 per page</option>
+        </select>
+        <input
+          type="number"
+          min={1}
+          max={table.pagination.totalPages}
+          placeholder="Go to page"
+          onKeyDown={(e) => {
+            if (e.key === "Enter") {
+              table.pagination.goToPage(Number((e.target as HTMLInputElement).value));
+            }
+          }}
+        />
+      </div>
+
+      {/* Actions */}
+      <div className="table-actions">
+        <button onClick={handleRefresh} disabled={table.isFetching}>
+          {table.isFetching ? "Refreshing..." : "Refresh"}
+        </button>
+        <button onClick={() => table.sort.clear()}>Clear Sort</button>
+        <button onClick={() => table.sort.set("Price", "desc")}>Sort by Price (desc)</button>
+      </div>
+
+      {/* Debug: Filter payload */}
+      <details>
+        <summary>Filter Payload (Debug)</summary>
+        <pre>{JSON.stringify(getFilterPayload(), null, 2)}</pre>
+      </details>
+    </div>
+  );
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "1.0.16",
+  "version": "1.0.19",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",
@@ -156,11 +156,13 @@
         "types": "./dist/base-types.d.ts",
         "default": "./dist/types.cjs"
       }
-    }
+    },
+    "./docs/*": "./docs/*"
   },
   "files": [
     "dist",
     "sdk",
+    "docs",
     "README.md",
     "LICENSE"
   ],

package/sdk/api/client.ts

@@ -379,7 +379,13 @@ export function api<T = any>(bo_id: string): ResourceClient<T> {
         );
       }
 
-      return response.json();
+      const json = await response.json();
+      // API returns {"Data":{"_id":"..."},"ValidationFailures":[]}
+      // Extract _id from Data wrapper and return flat structure
+      return {
+        ...json.Data,
+        _id: json.Data._id,
+      };
     },
 
     // ============================================================

package/sdk/components/hooks/useForm/useForm.ts

@@ -81,6 +81,9 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
   // This allows us to detect changes since the last draft, not since form init
   const lastSyncedValuesRef = useRef<Partial<T> | null>(null);
 
+  // Track if draft creation has started (prevents duplicate calls in React strict mode)
+  const draftCreationStartedRef = useRef(false);
+
   // Stable callback ref to prevent dependency loops
   const onSchemaErrorRef = useRef(onSchemaError);
 
@@ -209,11 +212,15 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       operation !== "create" ||
       !schemaConfig ||
       !enabled ||
-      draftId
+      draftId ||
+      draftCreationStartedRef.current  // Prevent duplicate calls in React strict mode
     ) {
       return;
     }
 
+    // Mark as started immediately to prevent duplicate calls
+    draftCreationStartedRef.current = true;
+
     const createInitialDraft = async () => {
       setIsCreatingDraft(true);
       setDraftError(null);
@@ -244,13 +251,16 @@ export function useForm<T extends Record<string, any> = Record<string, any>>(
       } catch (error) {
         console.error("Failed to create initial draft:", error);
         setDraftError(error as Error);
+        // Reset the ref on error so it can be retried
+        draftCreationStartedRef.current = false;
       } finally {
         setIsCreatingDraft(false);
       }
     };
 
     createInitialDraft();
-  }, [isInteractiveMode, operation, schemaConfig, enabled, draftId, source, rhfForm]);
+  }, [isInteractiveMode, operation, schemaConfig, enabled, draftId, source]);
+  // Note: rhfForm removed from deps - we use ref pattern to avoid dependency loops
 
   // ============================================================
   // COMPUTED FIELD DEPENDENCY TRACKING AND OPTIMIZATION

package/sdk/components/hooks/useKanban/context.ts

@@ -1,13 +1,15 @@
 import { createContext, useContext } from "react";
-import { UseKanbanReturnType } from "./types";
+import type { UseKanbanReturnType } from "./types";
 
-export const KanbanContext = createContext<UseKanbanReturnType<any> | null>(null);
+export const KanbanContext = createContext<UseKanbanReturnType<any> | null>(
+  null,
+);
 
 export function useKanbanContext<T extends Record<string, any> = any>() {
   const context = useContext(KanbanContext);
   if (!context) {
     throw new Error(
-      "Kanban components must be used within a KanbanBoard component"
+      "Kanban components must be used within a KanbanBoard component",
     );
   }
   return context as UseKanbanReturnType<T>;