npm package: @gongfu/kanban
Description: A modern kanban board SDK with drag-and-drop support
Author: Kongfu Team
Latest version: 0.2.0

# @kongfu/kanban

A modern, flexible kanban board SDK for React applications with drag-and-drop support.

[![npm version](https://img.shields.io/npm/v/@kongfu/kanban.svg)](https://www.npmjs.com/package/@kongfu/kanban)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🎯 **Drag & Drop** - Smooth drag and drop powered by @dnd-kit
- 🎨 **Customizable** - Flexible theming and component customization
- 📱 **Responsive** - Works on desktop and mobile devices
- 🌍 **i18n Ready** - Built-in support for multiple languages
- ⚡ **Performance** - Optimized rendering with Zustand state management
- 🔍 **Search & Filter** - Built-in search and filtering capabilities
- 📊 **Statistics** - Real-time task statistics
- 🎭 **Multiple Views** - Board, list, calendar, and timeline views (coming soon)
- ✅ **TypeScript** - Full TypeScript support

## Installation

```bash
npm install @kongfu/kanban
# or
yarn add @kongfu/kanban
# or
pnpm add @kongfu/kanban
```

## Quick Start

```tsx
import { Kanban } from '@kongfu/kanban';
import '@kongfu/kanban/styles.css';

const columns = [
  { id: 'todo', title: 'To Do', order: 0 },
  { id: 'in-progress', title: 'In Progress', order: 1 },
  { id: 'done', title: 'Done', order: 2 },
];

const tasks = [
  {
    id: '1',
    title: 'Create kanban board',
    status: 'todo',
    order: 0,
    createdAt: new Date(),
    updatedAt: new Date(),
  },
  {
    id: '2',
    title: 'Add drag and drop',
    status: 'in-progress',
    order: 0,
    priority: 'high',
    createdAt: new Date(),
    updatedAt: new Date(),
  },
];

function App() {
  return (
    <div style={{ height: '600px' }}>
      <Kanban
        columns={columns}
        tasks={tasks}
        onTaskCreate={(task) => console.log('Create task:', task)}
        onTaskUpdate={(id, updates) => console.log('Update task:', id, updates)}
        onTaskMove={(id, from, to, order) => console.log('Move task:', id, from, to, order)}
      />
    </div>
  );
}
```

## Advanced Usage

### Custom Card Rendering

```tsx
<Kanban
  columns={columns}
  tasks={tasks}
  renderCard={(task) => (
    <div className="custom-card">
      <h3>{task.title}</h3>
      <p>{task.description}</p>
      <div className="custom-footer">
        {task.assignee?.name}
      </div>
    </div>
  )}
/>
```

### With Filters

```tsx
const filters = [
  {
    id: 'priority',
    label: 'Priority',
    type: 'select',
    field: 'priority',
    options: [
      { label: 'Low', value: 'low' },
      { label: 'Normal', value: 'normal' },
      { label: 'High', value: 'high' },
      { label: 'Urgent', value: 'urgent' },
    ],
  },
  {
    id: 'assignee',
    label: 'Assignee',
    type: 'multiselect',
    field: 'assignee',
    options: [
      { label: 'John Doe', value: 'john' },
      { label: 'Jane Smith', value: 'jane' },
    ],
  },
];

<Kanban
  columns={columns}
  tasks={tasks}
  filters={filters}
  showFilters={true}
  showSearch={true}
/>
```

### Column Limits

```tsx
const columnsWithLimits = [
  { id: 'todo', title: 'To Do', order: 0 },
  { id: 'in-progress', title: 'In Progress', order: 1, limit: 3 },
  { id: 'done', title: 'Done', order: 2 },
];

<Kanban
  columns={columnsWithLimits}
  tasks={tasks}
/>
```

### Using the Store

```tsx
import { useKanbanStore } from '@kongfu/kanban';

function KanbanControls() {
  const {
    tasks,
    selectedTasks,
    bulkUpdateTasks,
    bulkDeleteTasks,
    clearSelection,
  } = useKanbanStore();

  const handleBulkComplete = () => {
    bulkUpdateTasks(selectedTasks, { status: 'done' });
    clearSelection();
  };

  const handleBulkDelete = () => {
    if (confirm('Delete selected tasks?')) {
      bulkDeleteTasks(selectedTasks);
      clearSelection();
    }
  };

  return (
    <div>
      {selectedTasks.length > 0 && (
        <>
          <button onClick={handleBulkComplete}>
            Mark as Done ({selectedTasks.length})
          </button>
          <button onClick={handleBulkDelete}>
            Delete ({selectedTasks.length})
          </button>
        </>
      )}
    </div>
  );
}
```

### Dark Mode

```tsx
<Kanban
  columns={columns}
  tasks={tasks}
  mode="dark"
  theme={{
    primaryColor: '#3b82f6',
    backgroundColor: '#1f2937',
    cardBackgroundColor: '#374151',
    textColor: '#f9fafb',
    borderColor: '#4b5563',
  }}
/>
```

## API Reference

### Kanban Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `KanbanColumn[]` | `[]` | Column definitions |
| `tasks` | `KanbanTask[]` | `[]` | Initial tasks |
| `mode` | `'light' \| 'dark'` | `'light'` | Color mode |
| `readOnly` | `boolean` | `false` | Disable editing |
| `showAddCard` | `boolean` | `true` | Show add task button |
| `showColumnActions` | `boolean` | `true` | Show column actions |
| `showCardActions` | `boolean` | `true` | Show card actions |
| `showFilters` | `boolean` | `true` | Show filter button |
| `showSearch` | `boolean` | `true` | Show search input |
| `showStats` | `boolean` | `true` | Show statistics |
| `cardHeight` | `'compact' \| 'normal' \| 'expanded'` | `'normal'` | Card display size |
| `animation` | `boolean` | `true` | Enable animations |
| `theme` | `KanbanTheme` | - | Custom theme |
| `locale` | `'en' \| 'zh-CN'` | `'en'` | UI language |
| `filters` | `FilterConfig[]` | - | Filter configurations |
| `onTaskCreate` | `(task, columnId) => Promise<KanbanTask>` | - | Task creation handler |
| `onTaskUpdate` | `(taskId, updates) => Promise<void>` | - | Task update handler |
| `onTaskDelete` | `(taskId) => Promise<void>` | - | Task deletion handler |
| `onTaskMove` | `(taskId, from, to, order) => Promise<void>` | - | Task move handler |
| `onTaskClick` | `(task) => void` | - | Task click handler |
| `renderCard` | `(task) => ReactNode` | - | Custom card renderer |
| `renderColumn` | `(column, children) => ReactNode` | - | Custom column renderer |

### Task Interface

```typescript
interface KanbanTask {
  id: string;
  title: string;
  description?: string;
  status: string;
  priority?: 'low' | 'normal' | 'high' | 'urgent';
  assignee?: {
    id: string;
    name: string;
    avatar?: string;
  };
  tags?: Array<{
    id: string;
    name: string;
    color: string;
  }>;
  dueDate?: Date;
  createdAt: Date;
  updatedAt: Date;
  order: number;
  subtasks?: Array<{
    id: string;
    title: string;
    completed: boolean;
  }>;
  attachments?: Array<{
    id: string;
    name: string;
    url: string;
    type: string;
    size: number;
  }>;
}
```

### Column Interface

```typescript
interface KanbanColumn {
  id: string;
  title: string;
  color?: string;
  icon?: ReactNode;
  limit?: number;
  collapsed?: boolean;
  order: number;
}
```

## Styling

The component comes with default styles that you can import:

```tsx
import '@kongfu/kanban/styles.css';
```

You can also customize the appearance using:

1. **CSS Variables** - Override default CSS variables
2. **Theme Object** - Pass a custom theme object
3. **Custom Classes** - Add your own CSS classes
4. **Render Props** - Complete control over rendering

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

## License

MIT © Kongfu Team