@ram_28/kf-ai-sdk 1.0.19 → 1.0.20

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,

package/sdk/index.ts

@@ -1,16 +1,160 @@
-// Core SDK exports
+// ============================================================
+// @ram_28/kf-ai-sdk - Main Entry Point
+// ============================================================
+// This is the primary export file for the SDK, providing a unified
+// interface to all hooks, types, utilities, and API functions.
 
-// Type system
-export * from './types';
+// ============================================================
+// HOOKS - Core functionality for building applications
+// ============================================================
 
-// API client
-export * from './api';
+// Table hook - Data tables with sorting, pagination, and filtering
+export { useTable } from './components/hooks/useTable';
+export type {
+  UseTableOptionsType,
+  UseTableReturnType,
+} from './components/hooks/useTable';
 
-// Utilities
-export * from './utils';
+// Form hook - Schema-driven forms with validation
+export { useForm } from './components/hooks/useForm';
+export type {
+  UseFormOptionsType,
+  UseFormReturnType,
+  FormFieldConfigType,
+  FormSchemaConfigType,
+} from './components/hooks/useForm';
 
-// Components
-export * from './components';
+// Kanban hook - Kanban board state management
+export { useKanban } from './components/hooks/useKanban';
+export type {
+  UseKanbanOptionsType,
+  UseKanbanReturnType,
+  KanbanCardType,
+  KanbanColumnType,
+  ColumnConfigType,
+} from './components/hooks/useKanban';
+
+// Filter hook - Advanced filtering with logical operators
+export { useFilter, isCondition, isConditionGroup } from './components/hooks/useFilter';
+export type {
+  UseFilterOptionsType,
+  UseFilterReturnType,
+} from './components/hooks/useFilter';
+
+// ============================================================
+// AUTHENTICATION - User authentication and authorization
+// ============================================================
+
+export { AuthProvider, useAuth } from './auth';
+export type {
+  UseAuthReturnType,
+  UserDetailsType,
+  AuthStatusType,
+  AuthProviderPropsType,
+} from './auth/types';
+
+// ============================================================
+// API CLIENT - Type-safe CRUD operations
+// ============================================================
+
+export { api, setApiBaseUrl, getApiBaseUrl, getBdoSchema } from './api';
+
+// ============================================================
+// TYPES - Core type definitions
+// ============================================================
+
+// Common types
+export type {
+  SortType,
+  SortDirectionType,
+  FilterType,
+  ConditionType,
+  ConditionGroupType,
+  ConditionOperatorType,
+  ConditionGroupOperatorType,
+  ListResponseType,
+  ListOptionsType,
+  ColumnDefinitionType,
+} from './types/common';
+
+// Base field types
+export type {
+  IdFieldType,
+  StringFieldType,
+  TextAreaFieldType,
+  NumberFieldType,
+  LongFieldType,
+  BooleanFieldType,
+  DateFieldType,
+  DateTimeFieldType,
+  CurrencyFieldType,
+  SelectFieldType,
+  LookupFieldType,
+  ArrayFieldType,
+  JSONFieldType,
+} from './types/base-fields';
 
-// Authentication
+// ============================================================
+// UTILITIES - Helper functions
+// ============================================================
+
+// Formatting utilities
+export {
+  formatCurrency,
+  formatDate,
+  formatDateTime,
+  formatNumber,
+  formatBoolean,
+  formatArray,
+  formatJSON,
+  formatFieldValue,
+} from './utils/formatting';
+
+// Class name utility
+export { cn } from './utils/cn';
+
+// Error handling utilities
+export {
+  toError,
+  isError,
+  getErrorMessage,
+  isNetworkError,
+  isTimeoutError,
+  isAbortError,
+  tryCatch,
+  wrapError,
+} from './utils/error-handling';
+
+// API utilities
+export {
+  buildListOptions,
+  buildCountOptions,
+  combineFilters,
+} from './utils/api';
+
+// ============================================================
+// UI COMPONENTS - Pre-built React components
+// ============================================================
+
+export {
+  Kanban,
+  KanbanColumn,
+  KanbanColumnHeader,
+  KanbanColumnTitle,
+  KanbanColumnContent,
+  KanbanCard,
+  KanbanCardTitle,
+  KanbanCardDescription,
+  KanbanColumnFooter,
+} from './components/ui';
+
+// ============================================================
+// LEGACY EXPORTS - For backwards compatibility
+// ============================================================
+
+// Re-export everything from submodules for backwards compatibility
+export * from './types';
+export * from './api';
+export * from './utils';
+export * from './components';
 export * from './auth';

package/sdk/table.types.ts

@@ -10,4 +10,7 @@ export type {
 
   // Column definition
   ColumnDefinitionType,
+
+  // State types
+  PaginationStateType,
 } from './components/hooks/useTable/types';

package/sdk/types/common.ts

@@ -37,14 +37,15 @@ export type FilterRHSTypeType = "Constant" | "BOField" | "AppVariable";
 
 /**
  * Leaf condition (actual field comparison)
+ * @template T - Data type for type-safe field names (defaults to any)
  */
-export interface ConditionType {
+export interface ConditionType<T = any> {
   /** Optional ID for hook state management (omitted in API payload) */
   id?: string;
   /** Condition operator */
   Operator: ConditionOperatorType;
-  /** Left-hand side field name */
-  LHSField: string;
+  /** Left-hand side field name (keyof T when generic is provided) */
+  LHSField: T extends any ? keyof T | string : string;
   /** Right-hand side value */
   RHSValue: any;
   /** Right-hand side type (optional, defaults to Constant) */
@@ -53,20 +54,22 @@ export interface ConditionType {
 
 /**
  * Group combining conditions (recursive structure)
+ * @template T - Data type for type-safe field names (defaults to any)
  */
-export interface ConditionGroupType {
+export interface ConditionGroupType<T = any> {
   /** Optional ID for hook state management (omitted in API payload) */
   id?: string;
   /** Group operator (And, Or, Not) */
   Operator: ConditionGroupOperatorType;
   /** Nested conditions (can be Condition or ConditionGroup) */
-  Condition: Array<ConditionType | ConditionGroupType>;
+  Condition: Array<ConditionType<T> | ConditionGroupType<T>>;
 }
 
 /**
  * Root filter type (alias for ConditionGroup)
+ * @template T - Data type for type-safe field names (defaults to any)
  */
-export type FilterType = ConditionGroupType;
+export type FilterType<T = any> = ConditionGroupType<T>;
 
 /**
  * DateTime encoding format used by the API
@@ -296,3 +299,25 @@ export interface FetchFieldResponseType {
   /** Array of field options */
   Data: FetchFieldOptionType[];
 }
+
+// ============================================================
+// SHARED COMPONENT TYPES
+// ============================================================
+
+/**
+ * Column definition for data display and behavior
+ * Used by useTable and useKanban for defining field configurations
+ * @template T - Data type for type-safe field names
+ */
+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 field */
+  enableSorting?: boolean;
+  /** Enable filtering for this field */
+  enableFiltering?: boolean;
+  /** Custom transform function (overrides auto-formatting) */
+  transform?: (value: any, item: T) => React.ReactNode;
+}

package/sdk/utils/api/buildListOptions.ts

@@ -0,0 +1,120 @@
+// ============================================================
+// BUILD LIST OPTIONS UTILITY
+// ============================================================
+// Shared utility for building API list options across hooks
+
+import type { ListOptionsType, FilterType, SortType } from "../../types/common";
+
+/**
+ * Options for building list API request options
+ */
+export interface BuildListOptionsParams<T = any> {
+  /** Search query string */
+  search?: string;
+  /** Filter payload */
+  filter?: FilterType<T>;
+  /** Sort configuration */
+  sort?: {
+    field: keyof T | null;
+    direction: "asc" | "desc" | null;
+  };
+  /** Sort array in API format */
+  sortArray?: SortType;
+  /** Pagination settings */
+  pagination?: {
+    pageNo: number;
+    pageSize: number;
+  };
+}
+
+/**
+ * Build list options for count queries
+ * Excludes pagination and sorting (they don't affect count)
+ */
+export function buildCountOptions<T = any>(
+  params: Pick<BuildListOptionsParams<T>, "search" | "filter">
+): ListOptionsType {
+  const opts: ListOptionsType = {};
+
+  if (params.search) {
+    opts.Search = params.search;
+  }
+
+  if (params.filter) {
+    opts.Filter = params.filter;
+  }
+
+  return opts;
+}
+
+/**
+ * Build list options for data queries
+ * Includes all options: search, filter, sort, pagination
+ */
+export function buildListOptions<T = any>(
+  params: BuildListOptionsParams<T>
+): ListOptionsType {
+  const opts: ListOptionsType = buildCountOptions({
+    search: params.search,
+    filter: params.filter,
+  });
+
+  // Add sorting - convert internal format to API format
+  if (params.sort?.field && params.sort?.direction) {
+    opts.Sort = [
+      {
+        [String(params.sort.field)]:
+          params.sort.direction === "asc" ? "ASC" : "DESC",
+      },
+    ];
+  } else if (params.sortArray) {
+    opts.Sort = params.sortArray;
+  }
+
+  // Add pagination
+  if (params.pagination) {
+    opts.Page = params.pagination.pageNo;
+    opts.PageSize = params.pagination.pageSize;
+  }
+
+  return opts;
+}
+
+/**
+ * Combine filter payload with additional column filter
+ * Used for kanban column-specific queries
+ */
+export function combineFilters<T = any>(
+  baseFilter: FilterType<T> | undefined,
+  additionalCondition: {
+    LHSField: string;
+    Operator: string;
+    RHSValue: any;
+    RHSType?: string;
+  }
+): FilterType<T> {
+  const columnFilterObject = {
+    ...additionalCondition,
+    RHSType: additionalCondition.RHSType || "Constant",
+  };
+
+  if (!baseFilter) {
+    return {
+      Operator: "And",
+      Condition: [columnFilterObject],
+    } as FilterType<T>;
+  }
+
+  // If base is And, append. If base is Or/Not, wrap in new And.
+  if (baseFilter.Operator === "And") {
+    return {
+      ...baseFilter,
+      Condition: [...(baseFilter.Condition || []), columnFilterObject],
+    } as FilterType<T>;
+  }
+
+  return {
+    Operator: "And",
+    Condition: [baseFilter, columnFilterObject],
+  } as FilterType<T>;
+}

package/sdk/utils/api/index.ts

@@ -0,0 +1,2 @@
+// API utilities
+export * from "./buildListOptions";