@ram_28/kf-ai-sdk 1.0.0

package/sdk/components/hooks/index.ts

@@ -0,0 +1,34 @@
+// Table hook
+export { useTable } from "./useTable";
+export type {
+  UseTableOptions,
+  UseTableReturn,
+  ColumnDefinition,
+} from "./useTable";
+
+// Form hook
+export { useForm } from "./useForm";
+export type {
+  UseFormOptions,
+  UseFormReturn,
+  BackendFieldDefinition,
+  ProcessedField,
+  ProcessedSchema,
+  FormOperation,
+  FormMode,
+  ValidationResult,
+  SubmissionResult,
+} from "./useForm";
+
+// Kanban hook
+export { useKanban } from "./useKanban";
+export type {
+  UseKanbanOptions,
+  UseKanbanReturn,
+  KanbanCard,
+  KanbanColumn,
+  ColumnDefinition as KanbanColumnDefinition,
+} from "./useKanban";
+
+// Filter hook
+export * from "./useFilter";

package/sdk/components/hooks/useFilter/index.ts

@@ -0,0 +1,37 @@
+// Main hook export
+export { useFilter } from './useFilter';
+
+// Type exports
+export type {
+  FilterConditionWithId,
+  TypedFilterConditionInput,
+  FilterState,
+  FieldDefinition,
+  ValidationResult,
+  ValidationError,
+  UseFilterOptions,
+  UseFilterReturn
+} from './types';
+
+// Validation utilities
+export {
+  validateNumberValue,
+  validateDateValue,
+  validateCurrencyValue,
+  validateStringValue,
+  validateBooleanValue,
+  validateSelectValue,
+  getDefaultFieldDefinition,
+  createFieldDefinitionsFromSample
+} from './validation.utils';
+
+// Payload building utilities
+export {
+  buildFilterPayload,
+  buildFilterPayloadFromState,
+  validateFilterPayload,
+  cloneFilterPayload,
+  mergeFilterPayloads,
+  filterPayloadToString,
+  areFilterPayloadsEqual
+} from './payloadBuilder.utils';

package/sdk/components/hooks/useFilter/payloadBuilder.utils.ts

@@ -0,0 +1,298 @@
+import type { Filter, FilterCondition, FilterLogical, LogicalOperator } from "../../../types/common";
+import type { FilterConditionWithId, FilterState } from "../useFilter";
+
+// ============================================================
+// PAYLOAD BUILDING UTILITIES
+// ============================================================
+
+/**
+ * Helper to check if operator is a logical operator
+ */
+const isLogicalOperator = (operator: string): operator is LogicalOperator => {
+  return operator === 'And' || operator === 'Or' || operator === 'Not';
+};
+
+/**
+ * Convert a single FilterConditionWithId to API format (FilterCondition or FilterLogical)
+ */
+const buildCondition = (condition: FilterConditionWithId): FilterCondition | FilterLogical => {
+  // Check if this is a logical operator (nested group)
+  if (isLogicalOperator(condition.operator)) {
+    // Build nested logical filter
+    return {
+      Operator: condition.operator,
+      Condition: (condition.children || [])
+        .filter(child => child.isValid)
+        .map(child => buildCondition(child))
+    };
+  } else {
+    // Build simple condition
+    return {
+      Operator: condition.operator,
+      LHSField: condition.lhsField!,
+      RHSValue: condition.rhsValue,
+      RHSType: condition.rhsType || "Constant"
+    };
+  }
+};
+
+/**
+ * Build SDK Filter payload from filter state
+ * Returns undefined if no valid conditions exist
+ * Supports both flat and nested filter structures
+ */
+export const buildFilterPayload = (
+  conditions: FilterConditionWithId[],
+  logicalOperator: LogicalOperator
+): Filter | undefined => {
+  // Return undefined if no conditions
+  if (conditions.length === 0) {
+    return undefined;
+  }
+
+  // Filter out invalid conditions
+  const validConditions = conditions.filter(condition => condition.isValid);
+
+  // Return undefined if no valid conditions
+  if (validConditions.length === 0) {
+    return undefined;
+  }
+
+  // Build the filter payload
+  return {
+    Operator: logicalOperator,
+    Condition: validConditions.map(buildCondition)
+  };
+};
+
+/**
+ * Build filter payload from complete filter state
+ */
+export const buildFilterPayloadFromState = (state: FilterState): Filter | undefined => {
+  return buildFilterPayload(state.conditions, state.logicalOperator);
+};
+
+/**
+ * Validate that a filter payload is well-formed (supports nested filters)
+ */
+export const validateFilterPayload = (filter: Filter | undefined): boolean => {
+  if (!filter) {
+    return true; // undefined filter is valid (no filtering)
+  }
+
+  // Check operator
+  if (!filter.Operator || !['And', 'Or', 'Not'].includes(filter.Operator)) {
+    return false;
+  }
+
+  // Check conditions array
+  if (!Array.isArray(filter.Condition) || filter.Condition.length === 0) {
+    return false;
+  }
+
+  // Not operator can only have one child
+  if (filter.Operator === 'Not' && filter.Condition.length !== 1) {
+    return false;
+  }
+
+  // Validate each condition recursively
+  return filter.Condition.every(condition => {
+    if (!condition.Operator) {
+      return false;
+    }
+
+    // Check if this is a logical operator (nested)
+    if (isLogicalOperator(condition.Operator)) {
+      // Recursively validate nested filter
+      return validateFilterPayload(condition as FilterLogical);
+    } else {
+      // Validate simple condition
+      const simpleCondition = condition as FilterCondition;
+      return (
+        simpleCondition.LHSField !== undefined &&
+        simpleCondition.RHSValue !== undefined &&
+        (simpleCondition.RHSType === undefined || ['Constant', 'BOField', 'AppVariable'].includes(simpleCondition.RHSType))
+      );
+    }
+  });
+};
+
+/**
+ * Deep clone a filter condition (supports nested filters)
+ */
+const cloneCondition = (condition: FilterCondition | FilterLogical): FilterCondition | FilterLogical => {
+  if (isLogicalOperator(condition.Operator)) {
+    // Clone logical filter recursively
+    return {
+      Operator: condition.Operator,
+      Condition: (condition as FilterLogical).Condition.map(cloneCondition)
+    };
+  } else {
+    // Clone simple condition
+    const simpleCondition = condition as FilterCondition;
+    return {
+      Operator: simpleCondition.Operator,
+      LHSField: simpleCondition.LHSField,
+      RHSValue: simpleCondition.RHSValue,
+      RHSType: simpleCondition.RHSType
+    };
+  }
+};
+
+/**
+ * Deep clone a filter payload (supports nested filters)
+ */
+export const cloneFilterPayload = (filter: Filter | undefined): Filter | undefined => {
+  if (!filter) {
+    return undefined;
+  }
+
+  return {
+    Operator: filter.Operator,
+    Condition: filter.Condition.map(cloneCondition)
+  };
+};
+
+/**
+ * Merge multiple filter payloads with a logical operator
+ */
+export const mergeFilterPayloads = (
+  filters: (Filter | undefined)[],
+  operator: LogicalOperator
+): Filter | undefined => {
+  const validFilters = filters.filter((filter): filter is Filter =>
+    filter !== undefined && validateFilterPayload(filter)
+  );
+
+  if (validFilters.length === 0) {
+    return undefined;
+  }
+
+  if (validFilters.length === 1) {
+    return cloneFilterPayload(validFilters[0]);
+  }
+
+  // Flatten all conditions
+  const allConditions = validFilters.flatMap(filter => filter.Condition);
+
+  return {
+    Operator: operator,
+    Condition: allConditions
+  };
+};
+
+/**
+ * Convert filter condition to a human-readable string (supports nested filters)
+ */
+const conditionToString = (condition: FilterCondition | FilterLogical): string => {
+  if (isLogicalOperator(condition.Operator)) {
+    // Handle logical filter
+    const logicalFilter = condition as FilterLogical;
+    const childStrings = logicalFilter.Condition.map(conditionToString);
+
+    if (childStrings.length === 1) {
+      return condition.Operator === 'Not'
+        ? `NOT (${childStrings[0]})`
+        : childStrings[0];
+    }
+
+    return `(${childStrings.join(` ${condition.Operator} `)})`;
+  } else {
+    // Handle simple condition
+    const simpleCondition = condition as FilterCondition;
+    const rhsDisplay = Array.isArray(simpleCondition.RHSValue)
+      ? `[${simpleCondition.RHSValue.join(', ')}]`
+      : String(simpleCondition.RHSValue);
+
+    return `${simpleCondition.LHSField} ${simpleCondition.Operator} ${rhsDisplay}`;
+  }
+};
+
+/**
+ * Convert filter payload to a human-readable string for debugging (supports nested filters)
+ */
+export const filterPayloadToString = (filter: Filter | undefined): string => {
+  if (!filter) {
+    return "No filters";
+  }
+
+  const conditionStrings = filter.Condition.map(conditionToString);
+
+  if (conditionStrings.length === 1) {
+    return conditionStrings[0];
+  }
+
+  return `(${conditionStrings.join(` ${filter.Operator} `)})`;
+};
+
+/**
+ * Check if two conditions are equivalent (supports nested filters)
+ */
+const areConditionsEqual = (
+  condition1: FilterCondition | FilterLogical,
+  condition2: FilterCondition | FilterLogical
+): boolean => {
+  // Different operators
+  if (condition1.Operator !== condition2.Operator) {
+    return false;
+  }
+
+  // Check if logical operators
+  if (isLogicalOperator(condition1.Operator)) {
+    const logical1 = condition1 as FilterLogical;
+    const logical2 = condition2 as FilterLogical;
+
+    // Different number of children
+    if (logical1.Condition.length !== logical2.Condition.length) {
+      return false;
+    }
+
+    // Recursively compare all children
+    return logical1.Condition.every((child1, index) =>
+      areConditionsEqual(child1, logical2.Condition[index])
+    );
+  } else {
+    // Compare simple conditions
+    const simple1 = condition1 as FilterCondition;
+    const simple2 = condition2 as FilterCondition;
+
+    return (
+      simple1.LHSField === simple2.LHSField &&
+      JSON.stringify(simple1.RHSValue) === JSON.stringify(simple2.RHSValue) &&
+      simple1.RHSType === simple2.RHSType
+    );
+  }
+};
+
+/**
+ * Check if two filter payloads are equivalent (supports nested filters)
+ */
+export const areFilterPayloadsEqual = (
+  filter1: Filter | undefined,
+  filter2: Filter | undefined
+): boolean => {
+  // Both undefined
+  if (!filter1 && !filter2) {
+    return true;
+  }
+
+  // One undefined, one defined
+  if (!filter1 || !filter2) {
+    return false;
+  }
+
+  // Different operators
+  if (filter1.Operator !== filter2.Operator) {
+    return false;
+  }
+
+  // Different number of conditions
+  if (filter1.Condition.length !== filter2.Condition.length) {
+    return false;
+  }
+
+  // Compare each condition recursively
+  return filter1.Condition.every((condition1, index) =>
+    areConditionsEqual(condition1, filter2.Condition[index])
+  );
+};

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

@@ -0,0 +1,158 @@
+import type { Filter, FilterOperator, FilterRHSType, LogicalOperator } from "../../../types/common";
+
+// ============================================================
+// TYPE DEFINITIONS
+// ============================================================
+
+/**
+ * Internal filter condition with ID for management
+ * Supports both simple conditions and nested logical groups
+ */
+export interface FilterConditionWithId {
+  /** Unique identifier for internal management */
+  id: string;
+  /** Filter operator (can be condition or logical operator) */
+  operator: FilterOperator | LogicalOperator;
+  /** Left-hand side field name (required for condition operators) */
+  lhsField?: string;
+  /** Right-hand side value (required for condition operators) */
+  rhsValue?: any;
+  /** Right-hand side type (defaults to Constant) */
+  rhsType?: FilterRHSType;
+  /** Nested conditions (for logical operators: And, Or, Not) */
+  children?: FilterConditionWithId[];
+  /** Validation state */
+  isValid: boolean;
+  /** Specific validation errors */
+  validationErrors?: string[];
+}
+
+/**
+ * Type-safe filter condition input (for addCondition)
+ * Constrains lhsField to keys of T for compile-time type checking
+ */
+export interface TypedFilterConditionInput<T> {
+  /** Filter operator (can be condition or logical operator) */
+  operator: FilterOperator | LogicalOperator;
+  /** Left-hand side field name - constrained to keyof T */
+  lhsField?: keyof T & string;
+  /** Right-hand side value */
+  rhsValue?: T[keyof T] | T[keyof T][] | any;
+  /** Right-hand side type (defaults to Constant) */
+  rhsType?: FilterRHSType;
+  /** Nested conditions (for logical operators: And, Or, Not) */
+  children?: TypedFilterConditionInput<T>[];
+}
+
+export interface FilterState {
+  /** Logical operator for combining conditions */
+  logicalOperator: LogicalOperator;
+  /** Array of filter conditions with IDs */
+  conditions: FilterConditionWithId[];
+}
+
+export interface FieldDefinition {
+  /** Field data type */
+  type: 'string' | 'number' | 'date' | 'boolean' | 'currency' | 'select';
+  /** Operators allowed for this field type */
+  allowedOperators: FilterOperator[];
+  /** Custom value validation function */
+  validateValue?: (value: any, operator: FilterOperator) => ValidationResult;
+  /** Value transformation function */
+  transformValue?: (value: any) => any;
+  /** Options for select fields */
+  selectOptions?: Array<{ label: string; value: any }>;
+}
+
+export interface ValidationResult {
+  /** Whether the validation passed */
+  isValid: boolean;
+  /** Array of error messages */
+  errors: string[];
+}
+
+export interface ValidationError {
+  /** ID of the condition with errors */
+  conditionId: string;
+  /** Field name */
+  field: string;
+  /** Error message */
+  message: string;
+}
+
+export interface UseFilterOptions<T = any> {
+  /** Initial filter conditions */
+  initialConditions?: FilterConditionWithId[];
+  /** Initial logical operator */
+  initialLogicalOperator?: LogicalOperator;
+  /** Field definitions for validation */
+  fieldDefinitions?: Record<keyof T, FieldDefinition>;
+  /** Whether to validate conditions on change */
+  validateOnChange?: boolean;
+  /** Callback when condition is added */
+  onConditionAdd?: (condition: FilterConditionWithId) => void;
+  /** Callback when condition is updated */
+  onConditionUpdate?: (condition: FilterConditionWithId) => void;
+  /** Callback when condition is removed */
+  onConditionRemove?: (conditionId: string) => void;
+  /** Callback when validation errors occur */
+  onValidationError?: (errors: ValidationError[]) => void;
+}
+
+export interface UseFilterReturn<T = any> {
+  // Current state
+  /** Array of current filter conditions */
+  conditions: FilterConditionWithId[];
+  /** Current logical operator */
+  logicalOperator: LogicalOperator;
+  /** SDK-formatted filter payload for API calls */
+  filterPayload: Filter | undefined;
+  /** Overall validation state */
+  isValid: boolean;
+  /** Array of validation errors */
+  validationErrors: ValidationError[];
+
+  // Condition management
+  /** Add a new filter condition (type-safe: lhsField constrained to keyof T) */
+  addCondition: (condition: TypedFilterConditionInput<T>) => string;
+  /** Update an existing condition */
+  updateCondition: (id: string, updates: Partial<TypedFilterConditionInput<T>>) => boolean;
+  /** Remove a condition by ID */
+  removeCondition: (id: string) => boolean;
+  /** Clear all conditions */
+  clearConditions: () => void;
+  /** Get a specific condition by ID */
+  getCondition: (id: string) => FilterConditionWithId | undefined;
+
+  // Logical operator management
+  /** Set the root logical operator */
+  setLogicalOperator: (operator: LogicalOperator) => void;
+
+  // Bulk operations
+  /** Replace all conditions */
+  setConditions: (conditions: FilterConditionWithId[]) => void;
+  /** Replace a specific condition */
+  replaceCondition: (id: string, newCondition: TypedFilterConditionInput<T>) => boolean;
+
+  // Validation
+  /** Validate a single condition */
+  validateCondition: (condition: Partial<FilterConditionWithId>) => ValidationResult;
+  /** Validate all current conditions */
+  validateAllConditions: () => ValidationResult;
+
+  // State management
+  /** Export current filter state */
+  exportState: () => FilterState;
+  /** Import a filter state */
+  importState: (state: FilterState) => void;
+  /** Reset to initial state */
+  resetToInitial: () => void;
+
+  // Utilities
+  /** Get total number of conditions */
+  getConditionCount: () => number;
+  /** Whether any conditions exist */
+  hasConditions: boolean;
+  /** Whether more conditions can be added */
+  canAddCondition: boolean;
+}