@archeon.ai/taskboard-core

A powerful, reusable task management package for React applications with Kanban board, story points, and sprint planning capabilities.

Features

• 🎯 Kanban Board with drag-and-drop functionality
• 📊 Story Points System with automatic hour conversion (1 point = 4 hours)
• 🎨 Priority-based Organization (P0-P5 with color coding)
• 📁 Project-based Task Separation (multiple projects in tabs)
• 🏃 Sprint Calculation with team capacity planning
• 📈 Progress Tracking with completion percentages
• 👥 Team Member Assignment and workload distribution
• ⚡ Real-time Updates with React Query
• 📱 Responsive Design with Tailwind CSS
• 🔧 Fully Customizable configuration system

Installation

npm install @archeon.ai/taskboard-core
# or
yarn add @archeon.ai/taskboard-core

Quick Start

1. Basic Setup

import React from 'react';
import { TaskProvider, TaskBoard } from '@taskboard/core';

function App() {
  return (
    <TaskProvider
      config={{
        teamMembers: [
          { id: 'john', name: 'John Doe', capacity_hours_per_week: 40 },
          { id: 'jane', name: 'Jane Smith', capacity_hours_per_week: 40 },
        ],
        projects: [
          { id: 'project1', name: 'Project Alpha' },
          { id: 'project2', name: 'Project Beta' },
        ],
      }}
    >
      <TaskBoard
        project="project1"
        tasks={[]}
        onTaskCreate={(data) => console.log('Create task:', data)}
        onTaskUpdate={(id, data) => console.log('Update task:', id, data)}
        onTaskMove={(data) => console.log('Move task:', data)}
      />
    </TaskProvider>
  );
}

2. With Supabase Integration

import React from 'react';
import { TaskProvider, TaskBoard, SupabaseAdapter } from '@taskboard/core';

const supabaseAdapter = new SupabaseAdapter({
  url: 'your-supabase-url',
  anonKey: 'your-supabase-anon-key',
});

function App() {
  return (
    <TaskProvider
      config={{
        adapter: supabaseAdapter,
        teamMembers: [
          { id: 'john', name: 'John Doe' },
          { id: 'jane', name: 'Jane Smith' },
        ],
      }}
    >
      <TaskBoard
        project="exe"
        tasks={[]}
        onTaskCreate={(data) => console.log('Create task:', data)}
        onTaskUpdate={(id, data) => console.log('Update task:', id, data)}
        onTaskMove={(data) => console.log('Move task:', data)}
      />
    </TaskProvider>
  );
}

Components

TaskBoard

The main Kanban board component with drag-and-drop functionality.

import { TaskBoard } from '@taskboard/core';

<TaskBoard
  project="exe"
  tasks={tasks}
  onTaskMove={handleTaskMove}
  onTaskCreate={handleTaskCreate}
  onTaskUpdate={handleTaskUpdate}
  onTaskDelete={handleTaskDelete}
  onTaskView={handleTaskView}
  isAdmin={true}
  loading={false}
  error={null}
/>;

Props:

• project: Project - Project identifier
• tasks: Task[] - Array of tasks
• onTaskMove?: (data: TaskMoveData) => void - Handle task movement
• onTaskCreate?: (data: CreateTaskData) => void - Handle task creation
• onTaskUpdate?: (taskId: string, data: UpdateTaskData) => void - Handle task updates
• onTaskDelete?: (taskId: string) => void - Handle task deletion
• onTaskView?: (task: Task) => void - Handle task viewing
• isAdmin?: boolean - Admin permissions
• loading?: boolean - Loading state
• error?: string - Error message

TaskCard

Individual task display component.

import { TaskCard } from '@taskboard/core';

<TaskCard
  task={task}
  onEdit={handleEdit}
  onDelete={handleDelete}
  onStatusChange={handleStatusChange}
  onView={handleView}
  isEditable={true}
  showActions={true}
/>;

CreateTaskModal

Modal for creating new tasks.

import { CreateTaskModal } from '@taskboard/core';

<CreateTaskModal
  isOpen={isModalOpen}
  onClose={() => setIsModalOpen(false)}
  onCreate={handleCreateTask}
  project="exe"
  teamMembers={teamMembers}
  loading={isCreating}
/>;

SprintCalculator

Sprint planning and capacity calculation widget.

import { SprintCalculator } from '@taskboard/core';

<SprintCalculator
  tasks={tasks}
  teamSize={4}
  workingHoursPerWeek={40}
  sprintDurationWeeks={2}
  onSprintUpdate={handleSprintUpdate}
/>;

Hooks

useTasks

Fetch tasks with filtering and sorting.

import { useTasks } from '@taskboard/core';

const {
  data: tasks,
  isLoading,
  error,
} = useTasks({
  project: 'exe',
  status: 'in_progress',
  owner: 'john',
});

useCreateTask

Create new tasks with optimistic updates.

import { useCreateTask } from '@taskboard/core';

const createTask = useCreateTask();

const handleCreate = () => {
  createTask.mutate({
    title: 'New Task',
    description: 'Task description',
    owner: 'john',
    department: 'tech',
    priority_level: 'p2',
    hours_needed: 8,
    project: 'exe',
  });
};

useUpdateTask

Update existing tasks with optimistic updates.

import { useUpdateTask } from '@taskboard/core';

const updateTask = useUpdateTask();

const handleUpdate = (taskId: string) => {
  updateTask.mutate({
    id: taskId,
    data: {
      status: 'completed',
      estimated_completion: 100,
    },
  });
};

useMoveTask

Handle drag-and-drop task movement.

import { useMoveTask } from '@taskboard/core';

const moveTask = useMoveTask();

const handleMove = (
  taskId: string,
  newPriority: PriorityLevel,
  newOrder: number
) => {
  moveTask.mutate({
    taskId,
    newPriority,
    newOrder,
    newStatus: 'in_progress',
  });
};

Configuration

TaskBoardConfig

interface TaskBoardConfig {
  storyPoints: number[]; // [1, 2, 3, 5, 8, 10, 15, 20, 25, 30, 40]
  priorities: PriorityLevel[]; // ['p0', 'p1', 'p2', 'p3', 'p4', 'p5']
  statuses: TaskStatus[]; // ['backlog', 'in_progress', 'completed', 'cancelled']
  teamMembers: TeamMember[]; // Team member definitions
  projects: ProjectInfo[]; // Project definitions
  workingHoursPerWeek?: number; // Default: 40
  sprintDurationWeeks?: number; // Default: 2
}

Custom Configuration

const customConfig = {
  storyPoints: [1, 2, 5, 8, 13, 21], // Fibonacci sequence
  priorities: ['urgent', 'high', 'medium', 'low'],
  teamMembers: [
    { id: 'dev1', name: 'Developer 1', capacity_hours_per_week: 40 },
    { id: 'dev2', name: 'Developer 2', capacity_hours_per_week: 35 },
  ],
  projects: [
    { id: 'frontend', name: 'Frontend Development' },
    { id: 'backend', name: 'Backend Development' },
  ],
  workingHoursPerWeek: 40,
  sprintDurationWeeks: 2,
};

<TaskProvider config={customConfig}>{/* Your components */}</TaskProvider>;

Story Points System

The package includes a comprehensive story points system:

• 0.25 Points = 1 hour (micro task)
• 0.5 Points = 2 hours (tiny task)
• 1 Point = 4 hours (half day)
• 2 Points = 8 hours (1 day)
• 3 Points = 12 hours (1.5 days)
• 5 Points = 20 hours (2.5 days)
• 8 Points = 32 hours (4 days)
• 10 Points = 40 hours (1 week)
• 15 Points = 60 hours (1.5 weeks)
• 20 Points = 80 hours (2 weeks)

Story Points Utilities

import {
  storyPointsToHours,
  hoursToStoryPoints,
  getStoryPointsDescription,
  getStoryPointsColor,
} from '@archeon.ai/taskboard-core';

const hours = storyPointsToHours(5); // 20
const points = hoursToStoryPoints(16); // 4
const description = getStoryPointsDescription(8); // "Tarea grande, casi 1 semana (32h)"
const color = getStoryPointsColor(10); // "#f97316"

Priority System

Six priority levels with color coding:

• P0 (Critical) - Red (#ef4444)
• P1 (High) - Orange (#f97316)
• P2 (Medium-High) - Yellow (#eab308)
• P3 (Medium) - Green (#22c55e)
• P4 (Low) - Blue (#3b82f6)
• P5 (Backlog) - Gray (#6b7280)

Database Schema

The package includes a complete PostgreSQL schema with:

• Tasks table with all necessary fields
• Proper indexes for performance
• Row Level Security (RLS) policies
• Audit trail with task history
• Soft delete support
• Automatic timestamp management

See database/schema.sql for the complete schema.

API Integration

Supabase Integration

import { SupabaseAdapter } from '@taskboard/core';

const adapter = new SupabaseAdapter({
  url: 'https://your-project.supabase.co',
  anonKey: 'your-anon-key',
});

// Use with TaskProvider
<TaskProvider config={{ adapter }}>{/* Your components */}</TaskProvider>;

Custom API Integration

import { TaskService } from '@taskboard/core';

const taskService = new TaskService({
  baseUrl: 'https://your-api.com',
  apiKey: 'your-api-key',
});

// Use with hooks
const { data: tasks } = useTasks();

Styling

The package uses Tailwind CSS with custom component classes. Import the styles:

import '@taskboard/core/dist/styles.css';

Custom Styling

You can customize the appearance by overriding CSS variables or using Tailwind's configuration:

/* Override priority colors */
.priority-p0 {
  @apply bg-red-600;
}
.priority-p1 {
  @apply bg-orange-600;
}

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import {
  Task,
  CreateTaskData,
  UpdateTaskData,
  TaskMoveData,
} from '@taskboard/core';

const task: Task = {
  id: 'uuid',
  int: 1,
  title: 'Task Title',
  // ... other properties
};

Examples

Check the examples/ directory for complete implementation examples:

• Basic Next.js setup
• Supabase integration
• Custom configuration
• Multi-project setup

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions
• 📧 Email