@ram_28/kf-ai-sdk 1.0.22 → 1.0.24

package/docs/datetime.md

@@ -0,0 +1,144 @@
+# Date & DateTime Handling
+
+Working with Date and DateTime fields in the SDK.
+
+## API Response Format
+
+The backend returns dates in encoded format:
+- **Date**: `{ "$__d__": "YYYY-MM-DD" }`
+- **DateTime**: `{ "$__dt__": unix_timestamp_seconds }`
+
+## Imports
+
+```typescript
+// Decoding & formatting for API
+import {
+  decodeDate,
+  decodeDateTime,
+  formatDate,
+  formatDateTime,
+  parseDate,
+  parseDateTime,
+} from "@ram_28/kf-ai-sdk/api";
+
+// UI display formatting
+import {
+  formatDate,
+  formatDateTime
+} from "@ram_28/kf-ai-sdk/utils";
+```
+
+## Decoding API Responses
+
+Convert encoded dates to JavaScript Date objects.
+
+### decodeDate
+```typescript
+const apiResponse = { "$__d__": "2025-03-15" };
+const date = decodeDate(apiResponse);
+// => Date object for March 15, 2025
+```
+
+### decodeDateTime
+```typescript
+const apiResponse = { "$__dt__": 1769110463 };
+const date = decodeDateTime(apiResponse);
+// => Date object with full timestamp
+```
+
+## Formatting for API Requests
+
+Convert Date objects to strings the API expects.
+
+### formatDate (API)
+```typescript
+import { formatDate } from "@ram_28/kf-ai-sdk/api";
+
+const date = new Date(2025, 2, 15);
+formatDate(date); // => "2025-03-15"
+```
+
+### formatDateTime (API)
+```typescript
+import { formatDateTime } from "@ram_28/kf-ai-sdk/api";
+
+const date = new Date(2025, 2, 15, 10, 30, 45);
+formatDateTime(date); // => "2025-03-15 10:30:45"
+```
+
+## Formatting for UI Display
+
+Convert Date objects to human-readable strings.
+
+### formatDate (UI)
+```typescript
+import { formatDate } from "@ram_28/kf-ai-sdk/utils";
+
+const date = new Date(2025, 2, 15);
+formatDate(date, 'short');  // => "3/15/25"
+formatDate(date, 'medium'); // => "Mar 15, 2025"
+formatDate(date, 'long');   // => "March 15, 2025"
+```
+
+### formatDateTime (UI)
+```typescript
+import { formatDateTime } from "@ram_28/kf-ai-sdk/utils";
+
+const date = new Date(2025, 2, 15, 10, 30, 45);
+formatDateTime(date, 'short');  // => "3/15/25, 10:30 AM"
+formatDateTime(date, 'medium'); // => "Mar 15, 2025, 10:30:45 AM"
+formatDateTime(date, 'long');   // => "March 15, 2025 at 10:30:45 AM"
+```
+
+## Common Patterns
+
+### Display a date from API response
+```typescript
+import { decodeDate } from "@ram_28/kf-ai-sdk/api";
+import { formatDate } from "@ram_28/kf-ai-sdk/utils";
+
+function displayDate(encodedDate: { $__d__: string }) {
+  const date = decodeDate(encodedDate);
+  return formatDate(date, 'medium');
+}
+
+// Usage in component
+<span>{displayDate(record.OrderDate)}</span>
+```
+
+### Display created/modified timestamps
+```typescript
+import { decodeDateTime } from "@ram_28/kf-ai-sdk/api";
+import { formatDateTime } from "@ram_28/kf-ai-sdk/utils";
+
+function displayTimestamp(encodedDateTime: { $__dt__: number }) {
+  const date = decodeDateTime(encodedDateTime);
+  return formatDateTime(date, 'medium');
+}
+
+// Usage
+<span>Created: {displayTimestamp(record._created_at)}</span>
+<span>Modified: {displayTimestamp(record._modified_at)}</span>
+```
+
+### Submit a date to the API
+```typescript
+import { formatDate } from "@ram_28/kf-ai-sdk/api";
+
+// From a date picker value
+const datePickerValue = "2025-03-15"; // HTML date input value
+// Already in correct format, use directly
+
+// From a Date object
+const dateObj = new Date();
+const apiValue = formatDate(dateObj); // => "2025-03-15"
+```
+
+## Type Definitions
+
+```typescript
+import type {
+  DateEncodedType,      // { $__d__: string }
+  DateTimeEncodedType,  // { $__dt__: number }
+} from "@ram_28/kf-ai-sdk/api";
+```

package/docs/useFilter.md

@@ -36,40 +36,87 @@ type ConditionGroupOperatorType = "And" | "Or" | "Not";
 
 // Single condition (generic for type-safe LHSField)
 interface ConditionType<T = any> {
+  // Auto-generated unique identifier
   id?: string;
+
+  // Comparison operator (EQ, GT, Contains, etc.)
   Operator: ConditionOperatorType;
-  LHSField: keyof T | string;  // Type-safe when T is provided
+
+  // Field name to compare
+  LHSField: keyof T | string;
+
+  // Value to compare against
   RHSValue: any;
+
+  // Value type (default: "Constant")
   RHSType?: "Constant" | "BOField" | "AppVariable";
 }
 
 // Condition group (can contain conditions or nested groups)
 interface ConditionGroupType<T = any> {
+  // Auto-generated unique identifier
   id?: string;
+
+  // Group operator (And, Or, Not)
   Operator: ConditionGroupOperatorType;
+
+  // Nested conditions or groups
   Condition: Array<ConditionType<T> | ConditionGroupType<T>>;
 }
 
 // Hook options (also used for initialState in useTable/useKanban)
 interface UseFilterOptionsType<T = any> {
+  // Initial conditions to populate the filter
   conditions?: Array<ConditionType<T> | ConditionGroupType<T>>;
+
+  // Root operator for combining conditions (default: "And")
   operator?: ConditionGroupOperatorType;
 }
 
 // Hook return type (generic for type-safe field names)
 interface UseFilterReturnType<T = any> {
+  // ============================================================
+  // STATE
+  // ============================================================
+
+  // Current root operator (And, Or, Not)
   operator: ConditionGroupOperatorType;
+
+  // All conditions and groups at root level
   items: Array<ConditionType<T> | ConditionGroupType<T>>;
+
+  // API-ready filter payload (undefined if no conditions)
   payload: FilterType<T> | undefined;
+
+  // True when at least one condition exists
   hasConditions: boolean;
 
+  // ============================================================
+  // METHODS
+  // ============================================================
+
+  // Add a condition, optionally to a parent group. Returns the new condition's ID
   addCondition: (condition: Omit<ConditionType<T>, "id">, parentId?: string) => string;
+
+  // Add a condition group, optionally to a parent group. Returns the new group's ID
   addConditionGroup: (operator: ConditionGroupOperatorType, parentId?: string) => string;
+
+  // Update a condition's properties (Operator, LHSField, RHSValue)
   updateCondition: (id: string, updates: Partial<Omit<ConditionType<T>, "id">>) => void;
+
+  // Change a group's operator (And, Or, Not)
   updateGroupOperator: (id: string, operator: ConditionGroupOperatorType) => void;
+
+  // Remove a condition or group by ID
   removeCondition: (id: string) => void;
+
+  // Get a condition or group by ID
   getCondition: (id: string) => ConditionType<T> | ConditionGroupType<T> | undefined;
+
+  // Remove all conditions and groups
   clearAllConditions: () => void;
+
+  // Change the root operator
   setRootOperator: (operator: ConditionGroupOperatorType) => void;
 }
 ```
@@ -126,18 +173,14 @@ Use the generic type parameter to get TypeScript validation on field names.
 
 ```tsx
 import { useFilter } from "@ram_28/kf-ai-sdk/filter";
+import { Product, type ProductForRole } from "../sources";
+import { Roles } from "../sources/roles";
 
-interface Product {
-  _id: string;
-  Title: string;
-  Price: number;
-  Category: string;
-  Stock: number;
-}
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function TypeSafeFilter() {
   // Pass the type parameter for type-safe LHSField
-  const filter = useFilter<Product>();
+  const filter = useFilter<BuyerProduct>();
 
   const addCategoryFilter = () => {
     filter.addCondition({
@@ -150,7 +193,7 @@ function TypeSafeFilter() {
   const addInvalidFilter = () => {
     filter.addCondition({
       Operator: "EQ",
-      LHSField: "InvalidField",  // TypeScript error: not a key of Product
+      LHSField: "InvalidField",  // TypeScript error: not a key of BuyerProduct
       RHSValue: "test",
     });
   };
@@ -173,16 +216,13 @@ function TypeSafeFilter() {
 ```tsx
 import { useFilter } from "@ram_28/kf-ai-sdk/filter";
 import type { UseFilterOptionsType } from "@ram_28/kf-ai-sdk/filter/types";
+import { Product, type ProductForRole } from "../sources";
+import { Roles } from "../sources/roles";
 
-interface Product {
-  _id: string;
-  Title: string;
-  Price: number;
-  Category: string;
-}
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 // Type-safe filter options
-const initialFilter: UseFilterOptionsType<Product> = {
+const initialFilter: UseFilterOptionsType<BuyerProduct> = {
   conditions: [
     { Operator: "EQ", LHSField: "Category", RHSValue: "Electronics" },
     { Operator: "GT", LHSField: "Price", RHSValue: 100 },
@@ -191,7 +231,7 @@ const initialFilter: UseFilterOptionsType<Product> = {
 };
 
 // Use with useFilter
-const filter = useFilter<Product>(initialFilter);
+const filter = useFilter<BuyerProduct>(initialFilter);
 ```
 
 ---