@ram_28/kf-ai-sdk 1.0.19 → 1.0.21

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

@@ -7,6 +7,7 @@ import { useState, useMemo, useCallback, useRef, useEffect } from "react";
 import { useQuery, useMutation, useQueryClient, useQueries, keepPreviousData } from "@tanstack/react-query";
 import { api } from "../../../api";
 import type { ListOptionsType, ListResponseType } from "../../../types/common";
+import { toError } from "../../../utils/error-handling";
 import { useFilter } from "../useFilter";
 
 import type {
@@ -41,8 +42,13 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
 
   const [search, setSearch] = useState({
     query: initialState?.search || "",
+    debouncedQuery: initialState?.search || "",
   });
 
+  // Debounce timeout ref for search
+  const searchDebounceRef = useRef<NodeJS.Timeout | null>(null);
+  const SEARCH_DEBOUNCE_MS = 300;
+
   const [sorting] = useState({
     field: initialState?.sorting?.field || null,
     direction: initialState?.sorting?.direction || null,
@@ -81,8 +87,8 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
   // ============================================================
 
   const filter = useFilter({
-    initialConditions: initialState?.filters,
-    initialOperator: initialState?.filterOperator || "And",
+    conditions: initialState?.filter?.conditions,
+    operator: initialState?.filter?.operator || "And",
   });
 
   // Helper to generate API options for a specific column
@@ -139,13 +145,13 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
         ];
       }
 
-      // Add Search
-      if (search.query) {
-        opts.Search = search.query;
+      // Add Search (debounced)
+      if (search.debouncedQuery) {
+        opts.Search = search.debouncedQuery;
       }
 
       return opts;
-  }, [filter.payload, columnPagination, sorting, search.query]);
+  }, [filter.payload, columnPagination, sorting, search.debouncedQuery]);
 
   // ============================================================
   // COLUMN QUERY GENERATION
@@ -180,10 +186,10 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
   const cardApiOptions = useMemo((): ListOptionsType => {
       // This is for the GLOBAL count (ignoring column split)
       const opts: ListOptionsType = {};
-      if (search.query) opts.Search = search.query;
+      if (search.debouncedQuery) opts.Search = search.debouncedQuery;
       if (filter.payload) opts.Filter = filter.payload;
       return opts;
-  }, [search.query, filter.payload]);
+  }, [search.debouncedQuery, filter.payload]);
 
   const {
     data: countData,
@@ -196,7 +202,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
         return await api<KanbanCardType<T>>(source).count(cardApiOptions);
       } catch (err) {
         if (onErrorRef.current) {
-          onErrorRef.current(err as Error);
+          onErrorRef.current(toError(err));
         }
         throw err;
       }
@@ -258,7 +264,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
       if (context?.previousCards && context?.queryKey) {
         queryClient.setQueryData(context.queryKey, context.previousCards);
       }
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: (_data, _error, variables) => {
        const columnId = variables.columnId;
@@ -280,7 +286,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
       onCardUpdateRef.current?.({ _id: result.id, ...result.updates } as any);
     },
     onError: (error, _variables, _context) => {
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: () => {
        queryClient.invalidateQueries({ queryKey: ["kanban-cards", source] });
@@ -300,7 +306,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
       onCardDeleteRef.current?.(id);
     },
     onError: (error, _id, _context) => {
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: () => {
        queryClient.invalidateQueries({ queryKey: ["kanban-cards", source] });
@@ -374,7 +380,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
       if (context?.previousToData && context?.toQueryKey) {
         queryClient.setQueryData(context.toQueryKey, context.previousToData);
       }
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: (_data, _error, variables) => {
        const fromOpts = getColumnApiOptions(variables.fromColumnId);
@@ -401,7 +407,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
     },
     onSuccess: () => {},
     onError: (error, _variables, _context) => {
-      onErrorRef.current?.(error as Error);
+      onErrorRef.current?.(toError(error));
     },
     onSettled: (_data, _error, variables) => {
        const opts = getColumnApiOptions(variables.columnId);
@@ -513,11 +519,32 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
   // ============================================================
 
   const setSearchQuery = useCallback((value: string) => {
-    setSearch({ query: value });
+    // Validate search query length to prevent DoS
+    if (value.length > 255) {
+      console.warn("Search query exceeds maximum length of 255 characters");
+      return;
+    }
+
+    // Update immediate value for UI
+    setSearch((prev) => ({ ...prev, query: value }));
+
+    // Clear existing debounce timeout
+    if (searchDebounceRef.current) {
+      clearTimeout(searchDebounceRef.current);
+    }
+
+    // Debounce the actual API query update
+    searchDebounceRef.current = setTimeout(() => {
+      setSearch((prev) => ({ ...prev, debouncedQuery: value }));
+    }, SEARCH_DEBOUNCE_MS);
   }, []);
 
   const clearSearch = useCallback(() => {
-    setSearch({ query: "" });
+    // Clear debounce timeout
+    if (searchDebounceRef.current) {
+      clearTimeout(searchDebounceRef.current);
+    }
+    setSearch({ query: "", debouncedQuery: "" });
   }, []);
 
   const totalCards = countData?.Count || 0;
@@ -555,10 +582,19 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
 
   useEffect(() => {
     if (error && onErrorRef.current) {
-      onErrorRef.current(error as Error);
+      onErrorRef.current(toError(error));
     }
   }, [error]);
 
+  // Cleanup debounce timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (searchDebounceRef.current) {
+        clearTimeout(searchDebounceRef.current);
+      }
+    };
+  }, []);
+
   // ============================================================
   // RETURN OBJECT
   // ============================================================
@@ -574,7 +610,7 @@ export function useKanban<T extends Record<string, any> = Record<string, any>>(
     isUpdating,
 
     // Error Handling
-    error: error as Error | null,
+    error: error ? toError(error) : null,
 
     // Card Operations (Flat Access)
     createCard: createCardMutation.mutateAsync,

package/sdk/components/hooks/useTable/types.ts

@@ -1,46 +1,40 @@
-import type { ListResponseType, ConditionGroupOperatorType } from "../../../types/common";
-import type { ConditionType, ConditionGroupType, UseFilterReturnType } from "../useFilter";
+import type { ListResponseType, SortType, ColumnDefinitionType } from "../../../types/common";
+
+// Re-export ColumnDefinitionType for backwards compatibility
+export type { ColumnDefinitionType };
+import type { UseFilterReturnType, UseFilterOptionsType } from "../useFilter";
 
 // ============================================================
-// TYPE DEFINITIONS
+// STATE TYPE DEFINITIONS
 // ============================================================
 
-export interface ColumnDefinitionType<T> {
-  /** Field name from the data type */
-  fieldId: keyof T;
-  /** Display label (optional, defaults to fieldId) */
-  label?: string;
-  /** Enable sorting for this column */
-  enableSorting?: boolean;
-  /** Enable filtering for this column */
-  enableFiltering?: boolean;
-  /** Custom transform function (overrides auto-formatting) */
-  transform?: (value: any, row: T) => React.ReactNode;
+/**
+ * Pagination state type
+ */
+export interface PaginationStateType {
+  /** Page number (1-indexed) */
+  pageNo: number;
+  /** Number of items per page */
+  pageSize: number;
 }
 
+// ============================================================
+// TYPE DEFINITIONS
+// ============================================================
+
 export interface UseTableOptionsType<T> {
   /** Data source identifier */
   source: string;
   /** Column configurations */
   columns: ColumnDefinitionType<T>[];
-  /** Enable sorting functionality */
-  enableSorting?: boolean;
-  /** Enable filtering functionality */
-  enableFiltering?: boolean;
-  /** Enable pagination */
-  enablePagination?: boolean;
   /** Initial state */
   initialState?: {
-    pagination?: {
-      pageNo: number;
-      pageSize: number;
-    };
-    sorting?: {
-      field: keyof T;
-      direction: "asc" | "desc";
-    };
-    filters?: Array<ConditionType | ConditionGroupType>;
-    filterOperator?: ConditionGroupOperatorType;
+    /** Sort configuration: [{ "fieldName": "ASC" }] */
+    sort?: SortType;
+    /** Pagination state: { pageNo, pageSize } */
+    pagination?: PaginationStateType;
+    /** Filter state: { conditions, operator } */
+    filter?: UseFilterOptionsType<T>;
   };
   /** Error callback */
   onError?: (error: Error) => void;
@@ -77,11 +71,11 @@ export interface UseTableReturnType<T> {
   };
 
   // Filter (Simplified chainable API)
-  filter: UseFilterReturnType;
+  filter: UseFilterReturnType<T>;
 
   // Pagination (Flat Access)
   pagination: {
-    currentPage: number;
+    pageNo: number;
     pageSize: number;
     totalPages: number;
     totalItems: number;

package/sdk/components/hooks/useTable/useTable.llm.txt

@@ -28,12 +28,9 @@ const table = useTable<ProductType>({
     { fieldId: "Category", label: "Category", enableSorting: true },
     { fieldId: "Stock", label: "Stock", enableSorting: true },
   ],
-  enableSorting: true,
-  enableFiltering: true,
-  enablePagination: true,
   initialState: {
     pagination: { pageNo: 1, pageSize: 10 },
-    sorting: { field: "Title", direction: "asc" },
+    sort: [{ Title: "ASC" }],
   },
 });
 ```
@@ -46,14 +43,9 @@ const table = useTable<ProductType>({
 |----------|------|----------|-------------|
 | `source` | `string` | Yes | Data source identifier (Business Data Object name) |
 | `columns` | `ColumnDefinition<T>[]` | Yes | Column configurations |
-| `enableSorting` | `boolean` | No | Enable sorting functionality |
-| `enableFiltering` | `boolean` | No | Enable filtering functionality |
-| `enablePagination` | `boolean` | No | Enable pagination |
-| `fieldDefinitions` | `Record<keyof T, FieldDefinition>` | No | Field definitions for filter validation |
-| `initialState` | `object` | No | Initial state for pagination, sorting, filters |
+| `initialState` | `object` | No | Initial state for pagination, sorting, filters. Pagination defaults to `{ pageNo: 1, pageSize: 10 }` |
 | `onError` | `(error: Error) => void` | No | Error callback |
 | `onSuccess` | `(data: T[]) => void` | No | Success callback |
-| `onFilterError` | `(errors: ValidationError[]) => void` | No | Filter error callback |
 
 ### ColumnDefinition<T>
 
@@ -113,14 +105,14 @@ const table = useTable<ProductType>({
 | `filter.addCondition` | `(condition) => string` | Add a filter condition, returns ID |
 | `filter.updateCondition` | `(id, updates) => boolean` | Update a condition |
 | `filter.removeCondition` | `(id) => boolean` | Remove a condition |
-| `filter.clearConditions` | `() => void` | Clear all conditions |
+| `filter.clearAllConditions` | `() => void` | Clear all conditions |
 | `filter.getCondition` | `(id) => FilterConditionWithId` | Get a specific condition |
 | `filter.setLogicalOperator` | `(operator) => void` | Set logical operator |
 
 #### Pagination
 | Property | Type | Description |
 |----------|------|-------------|
-| `pagination.currentPage` | `number` | Current page (1-indexed) |
+| `pagination.pageNo` | `number` | Current page (1-indexed) |
 | `pagination.pageSize` | `number` | Items per page |
 | `pagination.totalPages` | `number` | Total number of pages |
 | `pagination.totalItems` | `number` | Total item count |
@@ -179,12 +171,9 @@ const table = useTable<SellerProduct>({
     { fieldId: "Category", label: "Category", enableSorting: true },
     { fieldId: "Stock", label: "Stock", enableSorting: true },
   ],
-  enableSorting: true,
-  enableFiltering: true,
-  enablePagination: true,
   initialState: {
     pagination: { pageNo: 1, pageSize: 10 },
-    sorting: { field: "Title", direction: "asc" },
+    sort: [{ Title: "ASC" }],
   },
 });
 
@@ -220,18 +209,15 @@ const table = useTable<SellerProduct>({
 const table = useTable<BuyerProduct>({
   source: "BDO_AmazonProductMaster",
   columns: [...],
-  enableSorting: true,
-  enableFiltering: true,
-  enablePagination: true,
   initialState: {
     pagination: { pageNo: 1, pageSize: 10 },
-    sorting: { field: "Title", direction: "asc" },
+    sort: [{ Title: "ASC" }],
   },
 });
 
 // Category filter
 const handleCategoryChange = (category: string) => {
-  table.filter.clearConditions();
+  table.filter.clearAllConditions();
   if (category !== "all") {
     table.filter.addCondition({
       lhsField: "Category",
@@ -296,7 +282,7 @@ const handleSortChange = (value: string) => {
 <Button
   onClick={() => {
     table.search.clear();
-    table.filter.clearConditions();
+    table.filter.clearAllConditions();
   }}
 >
   Clear All Filters

package/sdk/components/hooks/useTable/useTable.ts

@@ -1,7 +1,8 @@
-import { useState, useMemo, useCallback } from "react";
+import { useState, useMemo, useCallback, useRef, useEffect } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { api } from "../../../api";
 import type { ListResponseType, ListOptionsType } from "../../../types/common";
+import { toError } from "../../../utils/error-handling";
 import { useFilter } from "../useFilter";
 import type { UseTableOptionsType, UseTableReturnType } from "./types";
 
@@ -10,7 +11,8 @@ import type { UseTableOptionsType, UseTableReturnType } from "./types";
 // ============================================================
 
 interface SearchState {
-  query: string;
+  query: string; // Immediate UI value
+  debouncedQuery: string; // Debounced value for API queries
 }
 
 interface SortingState<T> {
@@ -36,12 +38,26 @@ export function useTable<T = any>(
 
   const [search, setSearch] = useState<SearchState>({
     query: "",
+    debouncedQuery: "",
   });
 
-  const [sorting, setSorting] = useState<SortingState<T>>({
-    field: options.initialState?.sorting?.field || null,
-    direction: options.initialState?.sorting?.direction || null,
-  });
+  // Debounce timeout ref for search
+  const searchDebounceRef = useRef<NodeJS.Timeout | null>(null);
+  const SEARCH_DEBOUNCE_MS = 300;
+
+  // Parse initial sort from API format [{ "fieldName": "ASC" }] to internal state
+  const getInitialSortState = (): SortingState<T> => {
+    const sortConfig = options.initialState?.sort;
+    if (sortConfig && sortConfig.length > 0) {
+      const firstSort = sortConfig[0];
+      const field = Object.keys(firstSort)[0] as keyof T;
+      const direction = firstSort[field as string]?.toLowerCase() as "asc" | "desc";
+      return { field, direction };
+    }
+    return { field: null, direction: null };
+  };
+
+  const [sorting, setSorting] = useState<SortingState<T>>(getInitialSortState);
 
   const [pagination, setPagination] = useState<PaginationState>({
     pageNo: options.initialState?.pagination?.pageNo || 1,
@@ -52,9 +68,9 @@ export function useTable<T = any>(
   // FILTER HOOK INTEGRATION
   // ============================================================
 
-  const filter = useFilter({
-    initialConditions: options.initialState?.filters,
-    initialOperator: options.initialState?.filterOperator || "And",
+  const filter = useFilter<T>({
+    conditions: options.initialState?.filter?.conditions,
+    operator: options.initialState?.filter?.operator || "And",
   });
 
   // ============================================================
@@ -65,9 +81,9 @@ export function useTable<T = any>(
   const countApiOptions = useMemo((): ListOptionsType => {
     const opts: ListOptionsType = {};
 
-    // Add search query (affects count)
-    if (search.query) {
-      opts.Search = search.query;
+    // Add debounced search query (affects count)
+    if (search.debouncedQuery) {
+      opts.Search = search.debouncedQuery;
     }
 
     // Add filter conditions (affects count)
@@ -76,7 +92,7 @@ export function useTable<T = any>(
     }
 
     return opts;
-  }, [search.query, filter.payload]);
+  }, [search.debouncedQuery, filter.payload]);
 
   // Options for list query - includes all options
   const apiOptions = useMemo((): ListOptionsType => {
@@ -92,13 +108,11 @@ export function useTable<T = any>(
     }
 
     // Add pagination
-    if (options.enablePagination) {
-      opts.Page = pagination.pageNo;
-      opts.PageSize = pagination.pageSize;
-    }
+    opts.Page = pagination.pageNo;
+    opts.PageSize = pagination.pageSize;
 
     return opts;
-  }, [countApiOptions, sorting, pagination, options.enablePagination]);
+  }, [countApiOptions, sorting, pagination]);
 
   // ============================================================
   // DATA FETCHING
@@ -121,7 +135,7 @@ export function useTable<T = any>(
         return response;
       } catch (err) {
         if (options.onError) {
-          options.onError(err as Error);
+          options.onError(toError(err));
         }
         throw err;
       }
@@ -144,7 +158,7 @@ export function useTable<T = any>(
         return await api<T>(options.source).count(countApiOptions);
       } catch (err) {
         if (options.onError) {
-          options.onError(err as Error);
+          options.onError(toError(err));
         }
         throw err;
       }
@@ -197,12 +211,43 @@ export function useTable<T = any>(
   // ============================================================
 
   const setSearchQuery = useCallback((value: string) => {
-    setSearch({ query: value });
-    setPagination((prev) => ({ ...prev, pageNo: 1 }));
+    // Validate search query length to prevent DoS
+    if (value.length > 255) {
+      console.warn("Search query exceeds maximum length of 255 characters");
+      return;
+    }
+
+    // Update immediate value for UI
+    setSearch((prev) => ({ ...prev, query: value }));
+
+    // Clear existing debounce timeout
+    if (searchDebounceRef.current) {
+      clearTimeout(searchDebounceRef.current);
+    }
+
+    // Debounce the actual API query update
+    searchDebounceRef.current = setTimeout(() => {
+      setSearch((prev) => ({ ...prev, debouncedQuery: value }));
+      setPagination((prev) => ({ ...prev, pageNo: 1 }));
+    }, SEARCH_DEBOUNCE_MS);
   }, []);
 
   const clearSearch = useCallback(() => {
-    setSearch({ query: "" });
+    // Clear debounce timeout
+    if (searchDebounceRef.current) {
+      clearTimeout(searchDebounceRef.current);
+    }
+    setSearch({ query: "", debouncedQuery: "" });
+    setPagination((prev) => ({ ...prev, pageNo: 1 }));
+  }, []);
+
+  // Cleanup debounce timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (searchDebounceRef.current) {
+        clearTimeout(searchDebounceRef.current);
+      }
+    };
   }, []);
 
   // ============================================================
@@ -263,7 +308,7 @@ export function useTable<T = any>(
     isFetching: isFetching || isCountFetching,
 
     // Error Handling
-    error: (error || countError) as Error | null,
+    error: error ? toError(error) : countError ? toError(countError) : null,
 
     // Search (Flat Access)
     search: {
@@ -286,7 +331,7 @@ export function useTable<T = any>(
 
     // Pagination (Flat Access)
     pagination: {
-      currentPage: pagination.pageNo,
+      pageNo: pagination.pageNo,
       pageSize: pagination.pageSize,
       totalPages,
       totalItems,