@object-ui/plugin-kanban 3.0.3 → 3.1.0

package/src/KanbanImpl.tsx

@@ -25,17 +25,21 @@ import {
   verticalListSortingStrategy,
 } from "@dnd-kit/sortable"
 import { CSS } from "@dnd-kit/utilities"
-import { Badge, Card, CardHeader, CardTitle, CardDescription, CardContent, ScrollArea } from "@object-ui/components"
+import { Badge, Card, CardHeader, CardTitle, CardDescription, CardContent, ScrollArea, Button, Input } from "@object-ui/components"
 import { useHasDndProvider, useDnd } from "@object-ui/react"
+import { Plus } from "lucide-react"
 
 // Utility function to merge class names (inline to avoid external dependency)
 const cn = (...classes: (string | undefined)[]) => classes.filter(Boolean).join(' ')
 
+const UNCATEGORIZED_LANE = 'Uncategorized'
+
 export interface KanbanCard {
   id: string
   title: string
   description?: string
   badges?: Array<{ label: string; variant?: "default" | "secondary" | "destructive" | "outline" }>
+  coverImage?: string
   [key: string]: any
 }
 
@@ -47,14 +51,67 @@ export interface KanbanColumn {
   className?: string
 }
 
+export interface ConditionalFormattingRule {
+  field: string
+  operator: 'equals' | 'not_equals' | 'contains' | 'in'
+  value: string | string[]
+  backgroundColor?: string
+  borderColor?: string
+}
+
 export interface KanbanBoardProps {
   columns: KanbanColumn[]
   onCardMove?: (cardId: string, fromColumnId: string, toColumnId: string, newIndex: number) => void
   onCardClick?: (card: KanbanCard) => void
   className?: string
+  quickAdd?: boolean
+  onQuickAdd?: (columnId: string, title: string) => void
+  coverImageField?: string
+  conditionalFormatting?: ConditionalFormattingRule[]
+  /** Field name for swimlane rows (2D grouping) */
+  swimlaneField?: string
 }
 
-function SortableCard({ card, onCardClick }: { card: KanbanCard; onCardClick?: (card: KanbanCard) => void }) {
+/**
+ * Evaluate conditional formatting rules for a card.
+ * Returns CSS style overrides for backgroundColor and borderColor.
+ */
+function getCardStyles(card: KanbanCard, rules?: ConditionalFormattingRule[]): React.CSSProperties {
+  if (!rules || rules.length === 0) return {}
+
+  for (const rule of rules) {
+    const fieldValue = card[rule.field]
+    if (fieldValue === undefined || fieldValue === null) continue
+
+    let matches = false
+    const strValue = String(fieldValue)
+
+    switch (rule.operator) {
+      case 'equals':
+        matches = strValue === String(rule.value)
+        break
+      case 'not_equals':
+        matches = strValue !== String(rule.value)
+        break
+      case 'contains':
+        matches = strValue.toLowerCase().includes(String(rule.value).toLowerCase())
+        break
+      case 'in':
+        matches = Array.isArray(rule.value) && rule.value.includes(strValue)
+        break
+    }
+
+    if (matches) {
+      return {
+        ...(rule.backgroundColor ? { backgroundColor: rule.backgroundColor } : {}),
+        ...(rule.borderColor ? { borderColor: rule.borderColor } : {}),
+      }
+    }
+  }
+  return {}
+}
+
+function SortableCard({ card, onCardClick, conditionalFormatting }: { card: KanbanCard; onCardClick?: (card: KanbanCard) => void; conditionalFormatting?: ConditionalFormattingRule[] }) {
   const {
     attributes,
     listeners,
@@ -70,11 +127,23 @@ function SortableCard({ card, onCardClick }: { card: KanbanCard; onCardClick?: (
     opacity: isDragging ? 0.5 : undefined,
   }
 
+  const cardStyles = getCardStyles(card, conditionalFormatting)
+
   return (
     <div ref={setNodeRef} style={style} {...attributes} {...listeners} role="listitem" aria-label={card.title}
       onClick={() => onCardClick?.(card)}
     >
-      <Card className="mb-2 cursor-grab active:cursor-grabbing border-border bg-card/60 hover:border-primary/40 hover:shadow-lg hover:shadow-primary/10 transition-all duration-300 group touch-manipulation">
+      <Card className="mb-2 cursor-grab active:cursor-grabbing border-border border-l-4 border-l-primary/40 bg-card/60 hover:border-primary/40 hover:shadow-lg hover:shadow-primary/10 transition-all duration-300 group touch-manipulation" style={cardStyles}>
+        {card.coverImage && (
+          <div className="w-full h-32 overflow-hidden rounded-t-lg">
+            <img
+              src={card.coverImage}
+              alt=""
+              className="w-full h-full object-cover"
+              loading="lazy"
+            />
+          </div>
+        )}
         <CardHeader className="p-2 sm:p-4">
           <CardTitle className="text-xs sm:text-sm font-medium font-mono tracking-tight text-foreground group-hover:text-primary transition-colors">{card.title}</CardTitle>
           {card.description && (
@@ -99,14 +168,77 @@ function SortableCard({ card, onCardClick }: { card: KanbanCard; onCardClick?: (
   )
 }
 
-function KanbanColumn({
+function QuickAddForm({ columnId, onAdd }: { columnId: string; onAdd: (columnId: string, title: string) => void }) {
+  const [isAdding, setIsAdding] = React.useState(false)
+  const [title, setTitle] = React.useState('')
+  const inputRef = React.useRef<HTMLInputElement>(null)
+
+  const handleSubmit = () => {
+    const trimmed = title.trim()
+    if (trimmed) {
+      onAdd(columnId, trimmed)
+      setTitle('')
+    }
+    setIsAdding(false)
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter') {
+      e.preventDefault()
+      handleSubmit()
+    } else if (e.key === 'Escape') {
+      setTitle('')
+      setIsAdding(false)
+    }
+  }
+
+  if (!isAdding) {
+    return (
+      <Button
+        variant="ghost"
+        size="sm"
+        className="w-full mt-2 text-muted-foreground hover:text-foreground"
+        onClick={() => {
+          setIsAdding(true)
+          setTimeout(() => inputRef.current?.focus(), 0)
+        }}
+      >
+        <Plus className="h-4 w-4 mr-1" />
+        Add Card
+      </Button>
+    )
+  }
+
+  return (
+    <div className="mt-2 space-y-2">
+      <Input
+        ref={inputRef}
+        value={title}
+        onChange={(e) => setTitle(e.target.value)}
+        onKeyDown={handleKeyDown} 
+        onBlur={handleSubmit}
+        placeholder="Enter card title..."
+        className="text-sm"
+        autoFocus
+      />
+    </div>
+  )
+}
+
+function KanbanColumnView({
   column,
   cards,
   onCardClick,
+  quickAdd,
+  onQuickAdd,
+  conditionalFormatting,
 }: {
   column: KanbanColumn
   cards: KanbanCard[]
   onCardClick?: (card: KanbanCard) => void
+  quickAdd?: boolean
+  onQuickAdd?: (columnId: string, title: string) => void
+  conditionalFormatting?: ConditionalFormattingRule[]
 }) {
   const safeCards = cards || [];
   const { setNodeRef } = useSortable({
@@ -128,14 +260,14 @@ function KanbanColumn({
         column.className
       )}
     >
-      <div className="p-3 sm:p-4 border-b border-border/50 bg-muted/20">
+      <div className="p-3 sm:p-4 border-b border-border/50 bg-muted/30 rounded-t-lg">
         <div className="flex items-center justify-between">
           <h3 id={`kanban-col-${column.id}`} className="font-mono text-xs sm:text-sm font-semibold tracking-wider text-primary/90 uppercase truncate">{column.title}</h3>
           <div className="flex items-center gap-2">
-            <span className="font-mono text-xs text-muted-foreground" aria-label={`${safeCards.length} cards${column.limit ? ` of ${column.limit} maximum` : ''}`}>
+            <Badge variant="secondary" className="text-xs font-mono tabular-nums">
               {safeCards.length}
               {column.limit && ` / ${column.limit}`}
-            </span>
+            </Badge>
             {isLimitExceeded && (
               <Badge variant="destructive" className="text-xs">
                 Full
@@ -150,11 +282,19 @@ function KanbanColumn({
           strategy={verticalListSortingStrategy}
         >
           <div className="space-y-2" role="list" aria-label={`${column.title} cards`}>
+            {safeCards.length === 0 && (
+              <div className="flex flex-col items-center justify-center py-8 text-muted-foreground/50">
+                <span className="text-xs font-mono">No cards</span>
+              </div>
+            )}
             {safeCards.map((card) => (
-              <SortableCard key={card.id} card={card} onCardClick={onCardClick} />
+              <SortableCard key={card.id} card={card} onCardClick={onCardClick} conditionalFormatting={conditionalFormatting} />
             ))}
           </div>
         </SortableContext>
+        {quickAdd && onQuickAdd && (
+          <QuickAddForm columnId={column.id} onAdd={onQuickAdd} />
+        )}
       </ScrollArea>
     </div>
   )
@@ -166,22 +306,36 @@ function DndBridge({ children }: { children: (dnd: ReturnType<typeof useDnd>) =>
   return <>{children(dnd)}</>
 }
 
-export default function KanbanBoard({ columns, onCardMove, onCardClick, className }: KanbanBoardProps) {
+export default function KanbanBoard({ columns, onCardMove, onCardClick, className, quickAdd, onQuickAdd, coverImageField, conditionalFormatting, swimlaneField }: KanbanBoardProps) {
   const hasDnd = useHasDndProvider()
 
   if (hasDnd) {
     return (
       <DndBridge>
-        {(dnd) => <KanbanBoardInner columns={columns} onCardMove={onCardMove} onCardClick={onCardClick} className={className} dnd={dnd} />}
+        {(dnd) => <KanbanBoardInner columns={columns} onCardMove={onCardMove} onCardClick={onCardClick} className={className} dnd={dnd} quickAdd={quickAdd} onQuickAdd={onQuickAdd} coverImageField={coverImageField} conditionalFormatting={conditionalFormatting} swimlaneField={swimlaneField} />}
       </DndBridge>
     )
   }
 
-  return <KanbanBoardInner columns={columns} onCardMove={onCardMove} onCardClick={onCardClick} className={className} dnd={null} />
+  return <KanbanBoardInner columns={columns} onCardMove={onCardMove} onCardClick={onCardClick} className={className} dnd={null} quickAdd={quickAdd} onQuickAdd={onQuickAdd} coverImageField={coverImageField} conditionalFormatting={conditionalFormatting} swimlaneField={swimlaneField} />
 }
 
-function KanbanBoardInner({ columns, onCardMove, onCardClick, className, dnd }: KanbanBoardProps & { dnd: ReturnType<typeof useDnd> | null }) {
+function KanbanBoardInner({ columns, onCardMove, onCardClick, className, dnd, quickAdd, onQuickAdd, coverImageField: _coverImageField, conditionalFormatting, swimlaneField }: KanbanBoardProps & { dnd: ReturnType<typeof useDnd> | null }) {
   const [activeCard, setActiveCard] = React.useState<KanbanCard | null>(null)
+
+  // Persist collapsed swimlane state per swimlaneField
+  const storageKey = swimlaneField ? `objectui:kanban-collapsed:${swimlaneField}` : null
+  const [collapsedLanes, setCollapsedLanes] = React.useState<Set<string>>(() => {
+    if (!storageKey) return new Set()
+    try {
+      const stored = localStorage.getItem(storageKey)
+      if (stored) {
+        const parsed = JSON.parse(stored)
+        if (Array.isArray(parsed)) return new Set(parsed.filter((v): v is string => typeof v === 'string'))
+      }
+    } catch { /* ignore corrupt data */ }
+    return new Set()
+  })
   
   // Ensure we always have valid columns with cards array
   const safeColumns = React.useMemo(() => {
@@ -197,6 +351,30 @@ function KanbanBoardInner({ columns, onCardMove, onCardClick, className, dnd }:
     setBoardColumns(safeColumns)
   }, [safeColumns])
 
+  // Compute swimlane rows when swimlaneField is provided
+  const swimlanes = React.useMemo(() => {
+    if (!swimlaneField) return null
+    const allCards = boardColumns.flatMap(col => col.cards)
+    const laneValues = new Set<string>()
+    allCards.forEach(card => {
+      const val = card[swimlaneField]
+      laneValues.add(val != null ? String(val) : UNCATEGORIZED_LANE)
+    })
+    return Array.from(laneValues).sort()
+  }, [boardColumns, swimlaneField])
+
+  const toggleLane = React.useCallback((lane: string) => {
+    setCollapsedLanes(prev => {
+      const next = new Set(prev)
+      if (next.has(lane)) next.delete(lane)
+      else next.add(lane)
+      if (storageKey) {
+        try { localStorage.setItem(storageKey, JSON.stringify([...next])) } catch { /* quota exceeded */ }
+      }
+      return next
+    })
+  }, [storageKey])
+
   const sensors = useSensors(
     useSensor(PointerSensor, {
       activationConstraint: {
@@ -334,19 +512,84 @@ function KanbanBoardInner({ columns, onCardMove, onCardClick, className, dnd }:
         <span>{boardColumns.length} columns</span>
         <span>← Swipe to navigate →</span>
       </div>
-      <div className={cn("flex gap-3 sm:gap-4 overflow-x-auto snap-x snap-mandatory p-2 sm:p-4 [-webkit-overflow-scrolling:touch]", className)} role="region" aria-label="Kanban board">
-        {boardColumns.map((column) => (
-          <KanbanColumn
-            key={column.id}
-            column={column}
-            cards={column.cards}
-            onCardClick={onCardClick}
-          />
-        ))}
-      </div>
+
+      {swimlanes ? (
+        /* Swimlane (2D) layout */
+        <div className={cn("flex flex-col gap-1 p-2 sm:p-4 min-w-0 overflow-hidden", className)} role="region" aria-label="Kanban board with swimlanes">
+          {/* Column headers */}
+          <div className="flex gap-3 sm:gap-4 pl-36 sm:pl-44 overflow-x-auto">
+            {boardColumns.map(col => (
+              <div key={col.id} className="w-[85vw] sm:w-80 flex-shrink-0 text-center">
+                <span className="font-mono text-xs sm:text-sm font-semibold tracking-wider text-primary/90 uppercase">{col.title}</span>
+                <span className="ml-2 font-mono text-xs text-muted-foreground">({col.cards.length})</span>
+              </div>
+            ))}
+          </div>
+
+          {/* Swimlane rows */}
+          {swimlanes.map(lane => {
+            const isCollapsed = collapsedLanes.has(lane)
+            const laneCardCount = boardColumns.reduce((sum, col) =>
+              sum + col.cards.filter(c => (c[swimlaneField!] != null ? String(c[swimlaneField!]) : UNCATEGORIZED_LANE) === lane).length, 0)
+
+            return (
+              <div key={lane} className="border rounded-lg bg-muted/10">
+                {/* Lane header */}
+                <button
+                  className="w-full flex items-center gap-2 px-3 py-2 text-left hover:bg-muted/30 transition-colors"
+                  onClick={() => toggleLane(lane)}
+                  aria-expanded={!isCollapsed}
+                >
+                  <span className={cn("transition-transform text-xs", isCollapsed ? "" : "rotate-90")}>▶</span>
+                  <span className="font-mono text-xs font-semibold text-muted-foreground uppercase tracking-wider">{lane}</span>
+                  <span className="font-mono text-xs text-muted-foreground">({laneCardCount})</span>
+                </button>
+
+                {/* Lane content */}
+                {!isCollapsed && (
+                  <div className="flex gap-3 sm:gap-4 overflow-x-auto px-2 pb-3 pl-36 sm:pl-44">
+                    {boardColumns.map(col => {
+                      const laneCards = col.cards.filter(c =>
+                        (c[swimlaneField!] != null ? String(c[swimlaneField!]) : UNCATEGORIZED_LANE) === lane
+                      )
+                      return (
+                        <div key={col.id} className="w-[85vw] sm:w-80 flex-shrink-0 min-h-[60px] rounded-md bg-card/20 p-2">
+                          <SortableContext items={laneCards.map(c => c.id)} strategy={verticalListSortingStrategy}>
+                            <div className="space-y-2" role="list" aria-label={`${col.title} - ${lane} cards`}>
+                              {laneCards.map(card => (
+                                <SortableCard key={card.id} card={card} onCardClick={onCardClick} conditionalFormatting={conditionalFormatting} />
+                              ))}
+                            </div>
+                          </SortableContext>
+                        </div>
+                      )
+                    })}
+                  </div>
+                )}
+              </div>
+            )
+          })}
+        </div>
+      ) : (
+        /* Standard flat layout */
+        <div className={cn("flex gap-3 sm:gap-4 overflow-x-auto snap-x snap-mandatory p-2 sm:p-4 bg-muted/10 rounded-lg [-webkit-overflow-scrolling:touch] min-w-0", className)} role="region" aria-label="Kanban board">
+          {boardColumns.map((column) => (
+            <KanbanColumnView
+              key={column.id}
+              column={column}
+              cards={column.cards}
+              onCardClick={onCardClick}
+              quickAdd={quickAdd}
+              onQuickAdd={onQuickAdd}
+              conditionalFormatting={conditionalFormatting}
+            />
+          ))}
+        </div>
+      )}
+
       <DragOverlay>
         <div aria-live="assertive" aria-label={activeCard ? `Dragging ${activeCard.title}` : undefined}>
-          {activeCard ? <SortableCard card={activeCard} /> : null}
+          {activeCard ? <SortableCard card={activeCard} conditionalFormatting={conditionalFormatting} /> : null}
         </div>
       </DragOverlay>
     </DndContext>

package/src/ObjectKanban.tsx

@@ -10,6 +10,7 @@ import React, { useEffect, useState, useMemo } from 'react';
 import type { DataSource } from '@object-ui/types';
 import { useDataScope, useNavigationOverlay } from '@object-ui/react';
 import { NavigationOverlay } from '@object-ui/components';
+import { extractRecords, buildExpandFields } from '@object-ui/core';
 import { KanbanRenderer } from './index';
 import { KanbanSchema } from './types';
 
@@ -57,25 +58,19 @@ export const ObjectKanban: React.FC<ObjectKanbanProps> = ({
   useEffect(() => {
     let isMounted = true;
     const fetchData = async () => {
-        if (!dataSource || !schema.objectName) return;
+        if (!dataSource || typeof dataSource.find !== 'function' || !schema.objectName) return;
         if (isMounted) setLoading(true);
         try {
+            // Auto-inject $expand for lookup/master_detail fields
+            const expand = buildExpandFields(objectDef?.fields);
             const results = await dataSource.find(schema.objectName, {
                 options: { $top: 100 },
-                $filter: schema.filter
+                $filter: schema.filter,
+                ...(expand.length > 0 ? { $expand: expand } : {}),
             });
             
             // Handle { value: [] } OData shape or { data: [] } shape or direct array
-            let data: any[] = [];
-            if (Array.isArray(results)) {
-                data = results;
-            } else if (results && typeof results === 'object') {
-                if (Array.isArray((results as any).value)) {
-                    data = (results as any).value;
-                } else if (Array.isArray((results as any).data)) {
-                    data = (results as any).data;
-                }
-            }
+            const data = extractRecords(results);
 
             console.log(`[ObjectKanban] Extracted data (length: ${data.length})`);
 
@@ -96,7 +91,7 @@ export const ObjectKanban: React.FC<ObjectKanbanProps> = ({
         fetchData();
     }
     return () => { isMounted = false; };
-  }, [schema.objectName, dataSource, boundData, schema.data, schema.filter, (props as any).data]);
+  }, [schema.objectName, dataSource, boundData, schema.data, schema.filter, (props as any).data, objectDef]);
 
   // Determine which data to use: props.data -> bound -> inline -> fetched
   const rawData = (props as any).data || boundData || schema.data || fetchedData;
@@ -122,16 +117,31 @@ export const ObjectKanban: React.FC<ObjectKanbanProps> = ({
        } 
     }
 
-    // Default to 'name'
-    const finalTitleField = titleField || 'name';
-    
-    return rawData.map(item => ({
-      ...item,
-      // Ensure id exists
-      id: item.id || item._id,
-      // Map title
-      title: item[finalTitleField] || item.title || 'Untitled',
-    }));
+    // Common title field names to try as fallback
+    const TITLE_FALLBACK_FIELDS = ['name', 'title', 'subject', 'label', 'display_name'];
+
+    return rawData.map(item => {
+      // If a specific title field was configured, try it first
+      let resolvedTitle = titleField ? item[titleField] : undefined;
+
+      // Fallback: try common field names
+      if (!resolvedTitle) {
+        for (const field of TITLE_FALLBACK_FIELDS) {
+          if (item[field]) {
+            resolvedTitle = item[field];
+            break;
+          }
+        }
+      }
+
+      return {
+        ...item,
+        // Ensure id exists
+        id: item.id || item._id,
+        // Map title
+        title: resolvedTitle || 'Untitled',
+      };
+    });
   }, [rawData, schema, objectDef]);
 
   // Generate columns if missing but groupBy is present
@@ -173,11 +183,16 @@ export const ObjectKanban: React.FC<ObjectKanbanProps> = ({
   }, [schema.columns, schema.groupBy, effectiveData, objectDef]);
 
   // Clone schema to inject data and className
+  // Use grouping.fields[0].field as swimlaneField fallback when no explicit swimlaneField
+  const effectiveSwimlaneField = schema.swimlaneField
+    || (schema.grouping?.fields?.[0]?.field);
+
   const effectiveSchema = {
       ...schema,
       data: effectiveData,
       columns: effectiveColumns,
-      className: className || schema.className
+      className: className || schema.className,
+      ...(effectiveSwimlaneField ? { swimlaneField: effectiveSwimlaneField } : {}),
   };
 
   const navigation = useNavigationOverlay({

package/src/__tests__/KanbanGrouping.test.tsx

@@ -0,0 +1,164 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, act } from '@testing-library/react';
+import React, { Suspense } from 'react';
+
+// Mock dnd-kit
+vi.mock('@dnd-kit/core', () => ({
+  DndContext: ({ children }: any) => <div data-testid="dnd-context">{children}</div>,
+  DragOverlay: ({ children }: any) => <div data-testid="drag-overlay">{children}</div>,
+  PointerSensor: vi.fn(),
+  TouchSensor: vi.fn(),
+  useSensor: vi.fn(),
+  useSensors: () => [],
+  closestCorners: vi.fn(),
+}));
+
+vi.mock('@dnd-kit/sortable', () => ({
+  SortableContext: ({ children }: any) => <div data-testid="sortable-context">{children}</div>,
+  useSortable: () => ({
+    attributes: {},
+    listeners: {},
+    setNodeRef: vi.fn(),
+    transform: null,
+    transition: null,
+    isDragging: false,
+  }),
+  arrayMove: (array: any[], from: number, to: number) => {
+    const newArray = [...array];
+    newArray.splice(to, 0, newArray.splice(from, 1)[0]);
+    return newArray;
+  },
+  verticalListSortingStrategy: vi.fn(),
+}));
+
+vi.mock('@dnd-kit/utilities', () => ({
+  CSS: {
+    Transform: {
+      toString: () => '',
+    },
+  },
+}));
+
+vi.mock('@object-ui/components', () => ({
+  Badge: ({ children, ...props }: any) => <span {...props}>{children}</span>,
+  Card: ({ children, ...props }: any) => <div {...props}>{children}</div>,
+  CardHeader: ({ children, ...props }: any) => <div {...props}>{children}</div>,
+  CardTitle: ({ children, ...props }: any) => <div {...props}>{children}</div>,
+  CardDescription: ({ children, ...props }: any) => <div {...props}>{children}</div>,
+  CardContent: ({ children, ...props }: any) => <div {...props}>{children}</div>,
+  ScrollArea: ({ children, ...props }: any) => <div {...props}>{children}</div>,
+  Button: ({ children, ...props }: any) => <button {...props}>{children}</button>,
+  Input: (props: any) => <input {...props} />,
+  Skeleton: ({ className }: any) => <div data-testid="skeleton" className={className} />,
+  NavigationOverlay: ({ children, selectedRecord }: any) => (
+    selectedRecord ? <div data-testid="navigation-overlay">{children(selectedRecord)}</div> : null
+  ),
+}));
+
+vi.mock('@object-ui/react', () => ({
+  useHasDndProvider: () => false,
+  useDnd: () => ({
+    startDrag: vi.fn(),
+    endDrag: vi.fn(),
+  }),
+  useDataScope: () => undefined,
+  useNavigationOverlay: () => ({
+    isOverlay: false,
+    handleClick: vi.fn(),
+    selectedRecord: null,
+    isOpen: false,
+    close: vi.fn(),
+    setIsOpen: vi.fn(),
+    mode: 'page' as const,
+  }),
+}));
+
+vi.mock('lucide-react', () => ({
+  Plus: () => <span>+</span>,
+}));
+
+// Import KanbanBoard (the impl) directly to avoid lazy-loading issues in tests
+import KanbanBoard from '../KanbanImpl';
+
+const mockColumns = [
+  {
+    id: 'todo',
+    title: 'To Do',
+    cards: [
+      { id: 'c1', title: 'Task 1', priority: 'High', team: 'Frontend' },
+      { id: 'c2', title: 'Task 2', priority: 'Low', team: 'Backend' },
+    ],
+  },
+  {
+    id: 'done',
+    title: 'Done',
+    cards: [
+      { id: 'c3', title: 'Task 3', priority: 'High', team: 'Frontend' },
+      { id: 'c4', title: 'Task 4', priority: 'Medium', team: 'Backend' },
+    ],
+  },
+];
+
+describe('ObjectKanban grouping config → swimlaneField mapping', () => {
+  it('uses grouping field as swimlane when passed to KanbanImpl', () => {
+    // This simulates what ObjectKanban does: map grouping.fields[0].field to swimlaneField
+    render(<KanbanBoard columns={mockColumns} swimlaneField="team" />);
+
+    // Swimlane layout should render
+    expect(screen.getByRole('region', { name: 'Kanban board with swimlanes' })).toBeInTheDocument();
+
+    // Swimlane headers for each team
+    expect(screen.getByText('Backend')).toBeInTheDocument();
+    expect(screen.getByText('Frontend')).toBeInTheDocument();
+  });
+
+  it('renders flat kanban when no swimlane/grouping is provided', () => {
+    render(<KanbanBoard columns={mockColumns} />);
+
+    // Flat layout renders "Kanban board"
+    expect(screen.getByRole('region', { name: 'Kanban board' })).toBeInTheDocument();
+    expect(screen.queryByRole('region', { name: 'Kanban board with swimlanes' })).not.toBeInTheDocument();
+  });
+
+  describe('ObjectKanban swimlaneField resolution logic', () => {
+    // Test the resolution logic independently (same as ObjectKanban.tsx effectiveSwimlaneField)
+    function resolveEffectiveSwimlaneField(
+      swimlaneField?: string,
+      grouping?: { fields: Array<{ field: string; order: string; collapsed: boolean }> },
+    ): string | undefined {
+      return swimlaneField || grouping?.fields?.[0]?.field;
+    }
+
+    it('prefers explicit swimlaneField over grouping', () => {
+      const result = resolveEffectiveSwimlaneField('priority', {
+        fields: [{ field: 'team', order: 'asc', collapsed: false }],
+      });
+      expect(result).toBe('priority');
+    });
+
+    it('falls back to grouping.fields[0].field when no swimlaneField', () => {
+      const result = resolveEffectiveSwimlaneField(undefined, {
+        fields: [{ field: 'team', order: 'asc', collapsed: false }],
+      });
+      expect(result).toBe('team');
+    });
+
+    it('returns undefined when neither swimlaneField nor grouping is set', () => {
+      const result = resolveEffectiveSwimlaneField(undefined, undefined);
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined when grouping has empty fields array', () => {
+      const result = resolveEffectiveSwimlaneField(undefined, { fields: [] });
+      expect(result).toBeUndefined();
+    });
+  });
+});