@ram_28/kf-ai-sdk 1.0.18 → 1.0.20

package/docs/QUICK_REFERENCE.md

@@ -1,6 +1,8 @@
 # KF AI SDK - Quick Reference
 
-## Installation & Setup
+Quick reference for common operations. See individual hook docs for detailed examples.
+
+## Installation
 
 ```bash
 npm install @ram_28/kf-ai-sdk
@@ -8,521 +10,241 @@ npm install @ram_28/kf-ai-sdk
 
 ```typescript
 import { setApiBaseUrl } from "@ram_28/kf-ai-sdk/api";
-
-// Configure API base URL (without /api/app - SDK adds proper paths automatically)
 setApiBaseUrl("https://api.your-domain.com");
 ```
 
-## useTable Hook
+---
+
+## useTable
 
-### Basic Usage
+[Full Documentation](./useTable.md)
 
 ```typescript
 import { useTable } from "@ram_28/kf-ai-sdk/table";
-import type { UseTableOptionsType, UseTableReturnType, ColumnDefinitionType } from "@ram_28/kf-ai-sdk/table/types";
 
-const table = useTable<ProductType>({
-  source: "BDO_AmazonProductMaster",
+const table = useTable<Product>({
+  source: "BDO_Products",
   columns: [
     { fieldId: "Title", enableSorting: true },
-    { fieldId: "Price", enableSorting: true, enableFiltering: true },
+    { fieldId: "Price", enableSorting: true },
   ],
+  initialState: {
+    pagination: { pageNo: 1, pageSize: 10 },
+  },
 });
 ```
 
-### Key Properties
+| Property | Description |
+|----------|-------------|
+| `table.rows` | Current data |
+| `table.isLoading` | Loading state |
+| `table.search.setQuery(q)` | Set search |
+| `table.sort.toggle(field)` | Toggle sort |
+| `table.filter.addCondition({...})` | Add filter |
+| `table.pagination.goToNext()` | Next page |
 
-| Property              | Type                       | Description        |
-| --------------------- | -------------------------- | ------------------ |
-| `rows`                | `T[]`                      | Current table data |
-| `isLoading`           | `boolean`                  | Loading state      |
-| `totalItems`          | `number`                   | Total count        |
-| `search.query`        | `string`                   | Current search     |
-| `search.setQuery`     | `(query: string) => void`  | Update search      |
-| `sort.toggle`         | `(field: keyof T) => void` | Toggle sort        |
-| `pagination.goToNext` | `() => void`               | Next page          |
-| `filter.addCondition` | `(condition) => string`    | Add filter         |
+---
 
-## useForm Hook
+## useForm
 
-### Basic Usage
+[Full Documentation](./useForm.md)
 
 ```typescript
 import { useForm } from "@ram_28/kf-ai-sdk/form";
-import type { UseFormOptionsType, UseFormReturnType, FormFieldConfigType } from "@ram_28/kf-ai-sdk/form/types";
 
-const form = useForm<ProductType>({
-  source: "BDO_AmazonProductMaster",
+const form = useForm<Product>({
+  source: "BDO_Products",
   operation: "create", // or "update"
-  userRole: "Seller",
-  onComputationRule: async (context) => {
-    // Handle server-side computation rules
-    const result = await api(context.source).update(id, data);
-    return result.computedFields;
-  },
+  recordId: "...",     // for update
 });
 ```
 
-### Key Properties
-
-| Property       | Type                                 | Description    |
-| -------------- | ------------------------------------ | -------------- |
-| `register`     | `(name, options?) => RegisterReturn` | Register field |
-| `handleSubmit` | `() => (e?) => Promise<void>`        | Submit handler |
-| `errors`       | `FieldErrors<T>`                     | Form errors    |
-| `isValid`      | `boolean`                            | Form validity  |
-| `isSubmitting` | `boolean`                            | Submit state   |
-| `getField`     | `(fieldName) => ProcessedField`      | Field metadata |
+| Property | Description |
+|----------|-------------|
+| `form.register(field)` | Register input |
+| `form.handleSubmit(onSuccess, onError)` | Submit handler |
+| `form.errors` | Validation errors |
+| `form.isValid` | Form validity |
+| `form.getField(name)` | Field metadata |
+| `form.watch(field)` | Watch value |
 
-### Field Permissions
-
-```typescript
-const field = form.getField("Price");
-if (field.permission.editable) {
-  // Field is editable for current role
-}
-if (field.permission.hidden) {
-  // Field should not be displayed
-}
-```
+---
 
-## Business Object Classes
+## useKanban
 
-### Role-Based Access
+[Full Documentation](./useKanban.md)
 
 ```typescript
-// Admin - Full access
-const adminProducts = new AmazonProductMaster("Admin");
-
-// Seller - Limited access
-const sellerProducts = new AmazonProductMaster("Seller");
+import { useKanban } from "@ram_28/kf-ai-sdk/kanban";
 
-// Buyer - Read-only
-const buyerProducts = new AmazonProductMaster("Buyer");
+const kanban = useKanban<TaskData>({
+  source: "BDO_Tasks",
+  columns: [
+    { id: "todo", title: "To Do", position: 0 },
+    { id: "done", title: "Done", position: 1 },
+  ],
+  enableDragDrop: true,
+});
 ```
 
-### CRUD Operations
+| Property | Description |
+|----------|-------------|
+| `kanban.columns` | Columns with cards |
+| `kanban.createCard({...})` | Create card |
+| `kanban.moveCard(id, columnId)` | Move card |
+| `kanban.getCardProps(card)` | Drag props |
+| `kanban.filter.addCondition({...})` | Filter cards |
 
-```typescript
-// Create
-const result = await products.create({
-  ASIN: "B08N5WRWNW",
-  Title: "Product Name",
-  Price: 49.99,
-});
+---
 
-// Read
-const product = await products.get("PROD-001");
+## useFilter
 
-// Update
-await products.update("PROD-001", { Price: 44.99 });
+[Full Documentation](./useFilter.md)
 
-// Delete (Admin only)
-await products.delete("PROD-001");
+```typescript
+import { useFilter, isCondition, isConditionGroup } from "@ram_28/kf-ai-sdk/filter";
 
-// List with options
-const list = await products.list({
-  Sort: [{ Price: "DESC" }],
-  PageSize: 20,
-  Filter: {
-    Operator: "AND",
-    Condition: [
-      { LhsField: "Category", Operator: "EQ", RhsValue: "Electronics" },
-    ],
-  },
+const filter = useFilter({
+  initialOperator: "And",
 });
 ```
 
-## Performance Optimizations
-
-### Expression Caching
-
-```typescript
-import { clearExpressionCache } from "@ram_28/kf-ai-sdk/form";
-
-// Clear cache when role changes
-clearExpressionCache();
-```
+| Property | Description |
+|----------|-------------|
+| `filter.addCondition({...})` | Add condition |
+| `filter.addConditionGroup(op)` | Add group |
+| `filter.clearAllConditions()` | Clear all |
+| `filter.payload` | API-ready payload |
+| `filter.hasConditions` | Has filters |
 
-### Dependency Tracking
+### Operators
 
-```typescript
-// Automatically optimized - only watches relevant fields
-const form = useForm({
-  source: "BDO_AmazonProductMaster",
-  // Price changes will only trigger discount recalculation
-});
-```
+| Operator | Description |
+|----------|-------------|
+| `EQ`, `NE` | Equal, Not Equal |
+| `GT`, `GTE`, `LT`, `LTE` | Comparisons |
+| `Between`, `NotBetween` | Range |
+| `IN`, `NIN` | List match |
+| `Contains`, `NotContains` | Text search |
+| `Empty`, `NotEmpty` | Null check |
 
-## Rule Types
+---
 
-| Rule Type          | Execution   | Purpose           | Example             |
-| ------------------ | ----------- | ----------------- | ------------------- |
-| **Validation**     | Client-side | Field validation  | ASIN format check   |
-| **Computation**    | Server-side | Calculated fields | Discount percentage |
-| **Business Logic** | Server-side | Complex logic     | Inventory updates   |
+## useAuth
 
-### Rule Implementation
+[Full Documentation](./useAuth.md)
 
 ```typescript
-// Client-side validation (automatic)
-"LENGTH(ASIN) == 10 AND MATCHES(ASIN, '^[A-Z0-9]{10}$')";
+import { useAuth, AuthProvider } from "@ram_28/kf-ai-sdk/auth";
 
-// Server-side computation (triggers API call)
-"IF(MRP > 0, ((MRP - Price) / MRP) * 100, 0)";
-```
-
-## Error Handling
-
-### Form Errors
+// Wrap app
+<AuthProvider config={{ sessionEndpoint: "/api/id" }}>
+  <App />
+</AuthProvider>
 
-```typescript
-const form = useForm({
-  onError: (error) => toast.error(error.message),
-  onSubmitError: (error) => {
-    if (error.code === "VALIDATION_FAILED") {
-      // Handle validation errors
-    }
-  },
-});
+// Use in components
+const auth = useAuth();
 ```
 
-### API Errors
+| Property | Description |
+|----------|-------------|
+| `auth.user` | Current user |
+| `auth.isAuthenticated` | Auth status |
+| `auth.login(provider?)` | Sign in |
+| `auth.logout()` | Sign out |
+| `auth.hasRole(role)` | Check role |
+| `auth.hasAnyRole(roles)` | Check roles |
 
-```typescript
-try {
-  await products.create(data);
-} catch (error) {
-  switch (error.code) {
-    case "PERMISSION_DENIED":
-      // Handle permission error
-      break;
-    case "VALIDATION_FAILED":
-      // Handle validation error
-      break;
-    default:
-    // Handle other errors
-  }
-}
-```
+---
 
-## Filter Conditions
+## Common Patterns
 
-### Basic Filters
+### Filter by Category
 
 ```typescript
+table.filter.clearAllConditions();
 table.filter.addCondition({
-  fieldName: "Price",
-  operator: "GT",
-  value: 50,
+  Operator: "EQ",
+  LHSField: "Category",
+  RHSValue: "Electronics",
 });
 ```
 
-### Complex Filters
+### Filter by Date Range
 
 ```typescript
 table.filter.addCondition({
-  fieldName: "Category",
-  operator: "IN",
-  value: ["Electronics", "Books"],
+  Operator: "Between",
+  LHSField: "CreatedAt",
+  RHSValue: [startDate, endDate],
 });
+```
 
+### My Tasks Filter
+
+```typescript
 table.filter.addCondition({
-  fieldName: "Price",
-  operator: "BETWEEN",
-  value: { min: 10, max: 100 },
+  Operator: "EQ",
+  LHSField: "AssignedTo",
+  RHSValue: currentUserId,
 });
-
-table.filter.setLogicalOperator("AND");
 ```
 
-## Sorting & Pagination
-
-### Sorting
+### Sortable Column Header
 
 ```typescript
-// Toggle sort on click
-<th onClick={() => table.sort.toggle("Title")}>
-  Title {table.sort.field === "Title" && table.sort.direction}
+<th onClick={() => table.sort.toggle("Price")}>
+  Price {table.sort.field === "Price" && (table.sort.direction === "asc" ? "↑" : "↓")}
 </th>
 ```
 
-### Pagination
+### Pagination Controls
 
 ```typescript
-<button
-  disabled={!table.pagination.canGoPrevious}
-  onClick={table.pagination.goToPrevious}
->
+<button onClick={table.pagination.goToPrevious} disabled={!table.pagination.canGoPrevious}>
   Previous
 </button>
-
-<span>
-  Page {table.pagination.currentPage} of {table.pagination.totalPages}
-</span>
-
-<button
-  disabled={!table.pagination.canGoNext}
-  onClick={table.pagination.goToNext}
->
+<span>Page {table.pagination.pageNo} of {table.pagination.totalPages}</span>
+<button onClick={table.pagination.goToNext} disabled={!table.pagination.canGoNext}>
   Next
 </button>
 ```
 
-## Permission Checks
-
-### Role-Based Field Access
+### Protected Route
 
 ```typescript
-// Check if field is editable
-const canEdit = form.getField("Cost")?.permission.editable;
-
-// Conditional rendering based on permissions
-{form.getField("Cost")?.permission.readable && (
-  <input {...form.register("Cost")} disabled={!canEdit} />
-)}
-```
-
-### Method Permissions
-
-```typescript
-// TypeScript enforces this at compile time
-const buyerProducts = AmazonProducts.Buyer();
-// buyerProducts.create() // ❌ Compile error
-// buyerProducts.delete() // ❌ Compile error
-const products = await buyerProducts.list(); // ✅ OK
-```
-
-## Common Patterns
-
-### Search with Debouncing
-
-```typescript
-const [search, setSearch] = useState("");
-
-useEffect(() => {
-  const timer = setTimeout(() => {
-    table.search.setQuery(search);
-  }, 300);
-
-  return () => clearTimeout(timer);
-}, [search, table.search]);
-
-<input
-  value={search}
-  onChange={(e) => setSearch(e.target.value)}
-  placeholder="Search..."
-/>
-```
-
-### Dynamic Field Rendering
-
-```typescript
-const fields = form.getFields();
-
-{Object.entries(fields).map(([fieldName, field]) => {
-  if (field.permission.hidden) return null;
-
-  return (
-    <div key={fieldName}>
-      <label>{field.label}</label>
-      <input
-        {...form.register(fieldName)}
-        disabled={!field.permission.editable}
-        type={field.type}
-      />
-    </div>
-  );
-})}
-```
-
-### Conditional Business Logic
-
-```typescript
-const form = useForm({
-  onComputationRule: async (context) => {
-    switch (context.ruleType) {
-      case "Computation":
-        // Handle computation rules
-        return await calculateFields(context);
-      case "BusinessLogic":
-        // Handle business logic rules
-        return await executeBusinessLogic(context);
-    }
-  },
-});
-```
-
-## Type Definitions
-
-### Hook Types
-
-```typescript
-// useTable types
-import type {
-  UseTableOptionsType,
-  UseTableReturnType,
-  ColumnDefinitionType,
-} from '@ram_28/kf-ai-sdk/table/types';
-
-// useFilter types
-import type {
-  UseFilterOptionsType,
-  UseFilterReturnType,
-  ConditionType,
-  ConditionGroupType,
-  FilterType,
-} from '@ram_28/kf-ai-sdk/filter/types';
-
-// useForm types
-import type {
-  UseFormOptionsType,
-  UseFormReturnType,
-  FormFieldConfigType,
-  FormSchemaConfigType,
-  FormOperationType,
-  BDOSchemaType,
-} from '@ram_28/kf-ai-sdk/form/types';
-
-// useKanban types
-import type {
-  UseKanbanOptionsType,
-  UseKanbanReturnType,
-  KanbanCardType,
-  KanbanColumnType,
-  ColumnConfigType,
-} from '@ram_28/kf-ai-sdk/kanban/types';
-
-// useAuth types
-import type {
-  UseAuthReturnType,
-  UserDetailsType,
-  AuthStatusType,
-  AuthProviderPropsType,
-  LoginOptionsType,
-  LogoutOptionsType,
-} from '@ram_28/kf-ai-sdk/auth/types';
-```
-
-### Common Types
-
-```typescript
-import type {
-  // Filter operators
-  ConditionOperatorType,      // "EQ" | "NE" | "GT" | "GTE" | "LT" | "LTE" | "Between" | "NotBetween" | "IN" | "NIN" | "Empty" | "NotEmpty" | "Contains" | "NotContains" | "MinLength" | "MaxLength"
-  ConditionGroupOperatorType, // "And" | "Or" | "Not"
-  FilterRHSTypeType,          // "Constant" | "BOField" | "AppVariable"
-
-  // API types
-  ListOptionsType,
-  ListResponseType,
-  CreateUpdateResponseType,
-} from '@ram_28/kf-ai-sdk/api/types';
-```
-
-### Base Field Types
-
-```typescript
-import type {
-  IdFieldType,
-  StringFieldType,
-  TextAreaFieldType,
-  NumberFieldType,
-  BooleanFieldType,
-  DateFieldType,
-  DateTimeFieldType,
-  CurrencyFieldType,
-  SelectFieldType,
-  LookupFieldType,
-  ReferenceFieldType,
-} from '@ram_28/kf-ai-sdk/types';
-```
-
-### Quick Type Summary
-
-| Type | Values/Purpose |
-|------|----------------|
-| `ConditionOperatorType` | `"EQ"`, `"NE"`, `"GT"`, `"GTE"`, `"LT"`, `"LTE"`, `"Between"`, `"NotBetween"`, `"IN"`, `"NIN"`, `"Empty"`, `"NotEmpty"`, `"Contains"`, `"NotContains"`, `"MinLength"`, `"MaxLength"` |
-| `ConditionGroupOperatorType` | `"And"`, `"Or"`, `"Not"` (title case) |
-| `FormOperationType` | `"create"`, `"update"` |
-| `AuthStatusType` | `"loading"`, `"authenticated"`, `"unauthenticated"` |
-| `FilterRHSTypeType` | `"Constant"`, `"BOField"`, `"AppVariable"` |
-
-## Debugging Tips
-
-### Debug Table Issues
-
-```typescript
-console.log("Table state:", {
-  isLoading: table.isLoading,
-  totalItems: table.totalItems,
-  currentPage: table.pagination.currentPage,
-  filters: table.filter.conditions,
-  sort: { field: table.sort.field, direction: table.sort.direction },
-});
+function ProtectedRoute({ children }) {
+  const auth = useAuth();
+  if (auth.isLoading) return <div>Loading...</div>;
+  if (!auth.isAuthenticated) return <div>Please sign in</div>;
+  return children;
+}
 ```
 
-### Debug Form Issues
+### Role-Based UI
 
 ```typescript
-console.log("Form state:", {
-  isValid: form.isValid,
-  errors: form.errors,
-  values: form.watch(),
-  schema: form.processedSchema,
-});
+{auth.hasRole("Admin") && <AdminPanel />}
+{auth.hasAnyRole(["Seller", "Admin"]) && <ProductManagement />}
 ```
 
-### Debug API Issues
-
-```typescript
-import { getApiBaseUrl, getDefaultHeaders } from "@ram_28/kf-ai-sdk/api";
-
-console.log("API Config:", {
-  baseUrl: getApiBaseUrl(),
-  headers: getDefaultHeaders(),
-});
-```
-
-## Configuration
+---
 
-### API Setup
+## Type Imports
 
 ```typescript
-import { setApiBaseUrl, setDefaultHeaders } from "@ram_28/kf-ai-sdk/api";
+// Table
+import type { UseTableOptionsType, UseTableReturnType, ColumnDefinitionType } from "@ram_28/kf-ai-sdk/table/types";
 
-// Set base URL - SDK automatically appends /api/app/{bo_id} paths
-setApiBaseUrl("https://api.example.com");
-setDefaultHeaders({
-  Authorization: `Bearer ${token}`,
-  "X-API-Version": "1.0",
-});
-```
+// Form
+import type { UseFormOptionsType, UseFormReturnType, FormFieldConfigType } from "@ram_28/kf-ai-sdk/form/types";
 
-### React Query Setup
+// Kanban
+import type { UseKanbanOptionsType, UseKanbanReturnType, KanbanCardType, ColumnConfigType } from "@ram_28/kf-ai-sdk/kanban/types";
 
-```typescript
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutes
-      gcTime: 10 * 60 * 1000     // 10 minutes
-    }
-  }
-});
+// Filter
+import type { ConditionType, ConditionGroupType, ConditionOperatorType, FilterType } from "@ram_28/kf-ai-sdk/filter/types";
 
-<QueryClientProvider client={queryClient}>
-  <App />
-</QueryClientProvider>
+// Auth
+import type { UseAuthReturnType, UserDetailsType, AuthStatusType } from "@ram_28/kf-ai-sdk/auth/types";
 ```
-
----
-
-## Quick Links
-
-- [Full Implementation Guide](./IMPLEMENTATION_GUIDE.md)
-- [Examples Directory](./examples/)
-- [API Documentation](./api-docs/)
-- [Business Object Schemas](./schemas/)