@ram_28/kf-ai-sdk 1.0.0

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

@@ -0,0 +1,482 @@
+# useKanban Hook - LLM Documentation
+
+## Overview
+
+The `useKanban` hook is a React hook for building Kanban board interfaces with:
+- Column-based card organization
+- Drag and drop support (mouse, touch, keyboard)
+- CRUD operations for cards
+- Search functionality
+- Filter support
+- Real-time state management
+- API integration with TanStack Query
+
+## Import
+
+```typescript
+import { useKanban } from "kf-ai-sdk";
+```
+
+## Basic Usage
+
+```typescript
+const COLUMNS = [
+  { id: "todo", title: "To Do", position: 0, color: "gray" },
+  { id: "inProgress", title: "In Progress", position: 1, color: "blue" },
+  { id: "done", title: "Done", position: 2, color: "green" },
+];
+
+const kanban = useKanban<TaskType>({
+  source: "BDO_Tasks",
+  columns: COLUMNS,
+  enableDragDrop: true,
+  onCardMove: (card, fromColumnId, toColumnId) => {
+    console.log(`Moved ${card.title} from ${fromColumnId} to ${toColumnId}`);
+  },
+  onError: (error) => {
+    console.error(error);
+  },
+});
+```
+
+## Configuration Options
+
+### UseKanbanOptions<T>
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `source` | `string` | Yes | - | Data source identifier (BDO name) |
+| `columns` | `ColumnDefinition[]` | Yes | - | Static column configurations |
+| `enableDragDrop` | `boolean` | No | `false` | Enable drag and drop |
+| `enableFiltering` | `boolean` | No | `false` | Enable filtering |
+| `enableSearch` | `boolean` | No | `false` | Enable search |
+| `initialSearch` | `string` | No | `""` | Initial search query |
+| `onCardMove` | `(card, fromColumnId, toColumnId) => void` | No | - | Card move callback |
+| `onCardCreate` | `(card) => void` | No | - | Card create callback |
+| `onCardUpdate` | `(card) => void` | No | - | Card update callback |
+| `onCardDelete` | `(cardId) => void` | No | - | Card delete callback |
+| `onSuccess` | `(data) => void` | No | - | Success callback |
+| `onError` | `(error) => void` | No | - | Error callback |
+| `onFilterError` | `(errors) => void` | No | - | Filter error callback |
+
+### ColumnDefinition
+
+```typescript
+interface ColumnDefinition {
+  id: string;       // Unique column identifier
+  title: string;    // Display title
+  position: number; // Display order (0-indexed)
+  color?: string;   // Optional color for header
+  limit?: number;   // Optional WIP limit
+}
+```
+
+## Return Value
+
+### UseKanbanReturn<T>
+
+#### Data
+| Property | Type | Description |
+|----------|------|-------------|
+| `columns` | `KanbanColumn<T>[]` | All columns with their cards |
+| `totalCards` | `number` | Total card count |
+
+#### Loading States
+| Property | Type | Description |
+|----------|------|-------------|
+| `isLoading` | `boolean` | Initial data loading |
+| `isFetching` | `boolean` | Background refetching |
+| `isUpdating` | `boolean` | Any mutation in progress |
+
+#### Error Handling
+| Property | Type | Description |
+|----------|------|-------------|
+| `error` | `Error \| null` | Current error state |
+
+#### Search
+| Property | Type | Description |
+|----------|------|-------------|
+| `searchQuery` | `string` | Current search query |
+| `setSearchQuery` | `(query: string) => void` | Set search query |
+| `clearSearch` | `() => void` | Clear search |
+
+#### Card Operations
+| Property | Type | Description |
+|----------|------|-------------|
+| `createCard` | `(card) => Promise<void>` | Create a new card |
+| `updateCard` | `(id, updates) => Promise<void>` | Update a card |
+| `deleteCard` | `(id) => Promise<void>` | Delete a card |
+| `moveCard` | `(cardId, toColumnId, position?) => Promise<void>` | Move card to column |
+
+#### Drag Drop State
+| Property | Type | Description |
+|----------|------|-------------|
+| `isDragging` | `boolean` | Drag operation in progress |
+| `draggedCard` | `KanbanCard<T> \| null` | Currently dragged card |
+| `handleDragStart` | `(card) => void` | Handle drag start |
+| `handleDragEnd` | `() => void` | Handle drag end |
+| `handleKeyboardMove` | `(cardId, direction) => Promise<void>` | Keyboard navigation |
+
+#### Utilities
+| Property | Type | Description |
+|----------|------|-------------|
+| `refresh` | `() => Promise<void>` | Refresh data |
+| `refetch` | `() => Promise<void>` | Refetch data |
+| `loadMore` | `(columnId: string) => void` | Load more cards |
+
+## Data Types
+
+### KanbanCard<T>
+
+```typescript
+interface KanbanCard<T = Record<string, any>> {
+  _id: string;            // Unique identifier
+  title: string;          // Card title
+  columnId: string;       // Column this card belongs to
+  position: number;       // Position within column (0-indexed)
+  _created_at?: Date;     // Creation timestamp
+  _modified_at?: Date;    // Modification timestamp
+} & T;                    // Custom fields from T
+```
+
+### KanbanColumn<T>
+
+```typescript
+interface KanbanColumn<T = Record<string, any>> {
+  _id: string;            // Unique identifier (from ColumnDefinition.id)
+  title: string;          // Column title
+  position: number;       // Position among columns
+  color?: string;         // Optional color
+  limit?: number;         // Optional WIP limit
+  cards: KanbanCard<T>[]; // Cards in this column
+}
+```
+
+## E-Commerce App Usage Example
+
+### Inventory Restocking Page (InventoryRestockingPage.tsx)
+
+```typescript
+const RESTOCKING_COLUMNS = [
+  { id: "LowStockAlert", title: "Low Stock Alert", position: 0, color: "red" },
+  { id: "OrderPlaced", title: "Order Placed", position: 1, color: "yellow" },
+  { id: "InTransit", title: "In Transit", position: 2, color: "blue" },
+  { id: "Received", title: "Received & Restocked", position: 3, color: "green" },
+];
+
+const kanban = useKanban<InventoryManagerRestocking>({
+  source: "BDO_ProductRestocking",
+  columns: RESTOCKING_COLUMNS,
+  enableDragDrop: true,
+  enableFiltering: true,
+  enableSearch: true,
+  onCardMove: (card, fromColumnId, toColumnId) => {
+    // When moving to "Received" column, show stock update modal
+    if (toColumnId === "Received") {
+      setSelectedCard(card);
+      setShowStockUpdateModal(true);
+    }
+  },
+  onError: (error) => {
+    toast.error(`Failed to move card: ${error.message}`);
+  },
+});
+
+// Search
+<Input
+  placeholder="Search by product title or SKU..."
+  value={kanban.searchQuery || ""}
+  onChange={(e) => kanban.setSearchQuery(e.target.value)}
+/>
+
+// Error handling
+{kanban.error ? (
+  <div className="text-center py-12 bg-red-50">
+    <p className="text-red-600">{kanban.error.message}</p>
+    <Button onClick={() => kanban.refetch()}>Try Again</Button>
+  </div>
+) : kanban.isLoading ? (
+  <div className="animate-spin">...</div>
+) : (
+  // Kanban board
+  <KanbanBoard instance={kanban}>
+    {kanban.columns.map((column) => (
+      <KanbanColumn key={column._id} columnId={column._id}>
+        <KanbanColumnHeader>
+          <KanbanColumnTitle>{column.title}</KanbanColumnTitle>
+          <Badge>{column.cards.length}</Badge>
+        </KanbanColumnHeader>
+
+        <KanbanColumnContent>
+          {column.cards.map((card) => (
+            <KanbanCard key={card._id} card={card}>
+              <KanbanCardTitle>{card.productTitle}</KanbanCardTitle>
+              <KanbanCardDescription>
+                <div>SKU: {card.productSKU}</div>
+                <div>Stock: {card.currentStock}</div>
+                <div>Ordered: {card.quantityOrdered}</div>
+              </KanbanCardDescription>
+              <Badge variant={getPriorityVariant(card.priority)}>
+                {card.priority}
+              </Badge>
+            </KanbanCard>
+          ))}
+        </KanbanColumnContent>
+
+        {column.cards.length >= 10 && (
+          <KanbanColumnFooter>
+            <Button onClick={() => kanban.loadMore(column._id)}>
+              Load More
+            </Button>
+          </KanbanColumnFooter>
+        )}
+      </KanbanColumn>
+    ))}
+  </KanbanBoard>
+)}
+```
+
+## Card Operations
+
+### Create Card
+
+```typescript
+await kanban.createCard({
+  title: "New Task",
+  columnId: "todo",
+  // Custom fields
+  description: "Task description",
+  priority: "High",
+});
+// Position is auto-calculated
+```
+
+### Update Card
+
+```typescript
+await kanban.updateCard(cardId, {
+  title: "Updated Title",
+  description: "New description",
+});
+```
+
+### Delete Card
+
+```typescript
+await kanban.deleteCard(cardId);
+```
+
+### Move Card
+
+```typescript
+// Move to another column
+await kanban.moveCard(cardId, "inProgress");
+
+// Move to specific position
+await kanban.moveCard(cardId, "inProgress", 2);
+```
+
+## Drag and Drop
+
+### Mouse Drag
+
+```typescript
+// Handled automatically when enableDragDrop: true
+// Use the provided getCardProps and getColumnProps for event binding
+
+const cardProps = kanban.getCardProps(card);
+const columnProps = kanban.getColumnProps(columnId);
+
+<div {...columnProps}>
+  {cards.map(card => (
+    <div {...cardProps}>{card.title}</div>
+  ))}
+</div>
+```
+
+### Keyboard Navigation
+
+```typescript
+// Move card left/right with keyboard
+await kanban.handleKeyboardMove(cardId, "left");  // Previous column
+await kanban.handleKeyboardMove(cardId, "right"); // Next column
+```
+
+### Touch Support
+
+The hook includes touch handlers for mobile devices:
+- `handleTouchStart`
+- `handleTouchMove`
+- `handleTouchEnd`
+
+## Drag Drop Manager
+
+For advanced drag and drop control, use the exported `useDragDropManager`:
+
+```typescript
+import { useDragDropManager } from "kf-ai-sdk";
+
+const dragDrop = useDragDropManager<TaskType>({
+  onCardMove: handleMove,
+  onError: handleError,
+  columns: kanban.columns,
+  announceMove: (card, from, to) => {
+    // Accessibility announcement
+    console.log(`Moved ${card.title} from ${from} to ${to}`);
+  },
+});
+```
+
+### DragDropManager Features
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isDragging` | `boolean` | Drag in progress |
+| `draggedCard` | `KanbanCard<T>` | Currently dragged card |
+| `dragOverColumn` | `string \| null` | Column being hovered |
+| `dragOverPosition` | `number \| null` | Position being hovered |
+| `dragSourceColumn` | `string \| null` | Source column |
+| `handleDragStart` | `(event, card) => void` | Start drag |
+| `handleDragOver` | `(event, columnId) => void` | Handle drag over |
+| `handleDrop` | `(event, columnId) => void` | Handle drop |
+| `handleDragEnd` | `() => void` | End drag |
+| `handleKeyDown` | `(event, card) => void` | Keyboard handler |
+| `handleTouchStart` | `(event, card) => void` | Touch start |
+| `handleTouchMove` | `(event) => void` | Touch move |
+| `handleTouchEnd` | `(event) => void` | Touch end |
+| `reset` | `() => void` | Reset state |
+
+## Context Provider
+
+For component tree access, use the KanbanContext:
+
+```typescript
+import { KanbanContext, useKanbanContext } from "kf-ai-sdk";
+
+// Provider
+<KanbanContext.Provider value={kanban}>
+  <KanbanBoard />
+</KanbanContext.Provider>
+
+// Consumer
+function KanbanCard() {
+  const kanban = useKanbanContext<TaskType>();
+  // Access kanban state and methods
+}
+```
+
+## API Client Functions
+
+The hook exports utility functions for direct API access:
+
+```typescript
+import {
+  mergeCardsIntoColumns,
+  calculateCardPosition,
+  calculateColumnPosition,
+  normalizePositions,
+  handleKanbanApiError,
+  validateApiResponse,
+} from "kf-ai-sdk";
+
+// Merge fetched cards into column structure
+const columnsWithCards = mergeCardsIntoColumns(columns, cards);
+
+// Calculate optimal position for new card
+const position = calculateCardPosition(column, insertIndex);
+
+// Normalize positions after reorder
+const normalized = normalizePositions(items);
+```
+
+## Filter Integration
+
+When `enableFiltering: true`, the hook includes filter functionality similar to useTable:
+
+```typescript
+kanban.filter.addCondition({
+  lhsField: "priority",
+  operator: "EQ",
+  rhsValue: "High",
+  rhsType: "Constant",
+});
+
+kanban.filter.clearConditions();
+```
+
+## Key Behaviors
+
+1. **Static columns**: Columns are defined at configuration time, not fetched from API
+2. **Auto-sorting**: Cards sorted by position within each column
+3. **Position auto-calculation**: New cards get position based on column length
+4. **WIP limit checking**: Drop is prevented if column limit is reached
+5. **Optimistic updates**: UI updates immediately, then syncs with server
+6. **Auto-scroll**: Scrolls horizontally during drag near edges
+7. **Accessibility**: ARIA attributes and screen reader announcements
+8. **30s stale time**: Data considered fresh for 30 seconds
+
+## API Format
+
+### Sort Format
+
+```typescript
+Sort: [
+  { columnId: "ASC" },
+  { position: "ASC" }
+]
+```
+
+### Move Card Request
+
+```typescript
+{
+  columnId: "newColumnId",
+  position: 2  // Optional
+}
+```
+
+## Architecture Notes
+
+- Built on TanStack Query for data fetching
+- Separate queries for cards and count
+- Uses `useMemo` for column processing
+- Mutations with automatic refetch on success
+- Supports generic card types with TypeScript
+- Includes comprehensive drag and drop manager
+- Context provider for component tree access
+- Full keyboard accessibility support
+
+## Error Handling
+
+```typescript
+const kanban = useKanban({
+  source: "BDO_Tasks",
+  columns: COLUMNS,
+  onError: (error) => {
+    // Handle general errors
+    toast.error(error.message);
+  },
+  onFilterError: (errors) => {
+    // Handle filter validation errors
+    errors.forEach(err => console.log(err.message));
+  },
+});
+
+// Check error state
+if (kanban.error) {
+  return <ErrorDisplay error={kanban.error} onRetry={kanban.refresh} />;
+}
+```
+
+## WIP Limits
+
+Columns can have work-in-progress limits:
+
+```typescript
+const COLUMNS = [
+  { id: "inProgress", title: "In Progress", position: 1, limit: 5 },
+];
+
+// Drop will be prevented if limit is reached
+// Error callback will be triggered with limit message
+```