A comprehensive React component library for task management and timeline visualization
npm install @tasks-timeline/componentsA comprehensive, production-ready React component library for building task management and timeline visualization applications.


⨠11 Professional UI Components
- Task list with multiple grouping strategies (day, year, backlog)
- Task item with status, priority, and action controls
- AI-powered input bar for natural language task creation
- Comprehensive task editor with full configuration
- Settings and help modals
- Toast notifications
- Icon component wrapper
š£ Custom React Hooks
- Task filtering and search
- Task statistics and progress tracking
- AI agent integration (Gemini, OpenAI, Anthropic)
- Voice input handling
š¦ Complete TypeScript Support
- Fully typed components and hooks
- Comprehensive type definitions
- Excellent IDE autocomplete
šØ Modern Styling
- Tailwind CSS v4 integration
- Radix UI components
- Responsive design
- Dark mode support
``bash`
npm install @tasks-timeline/componentsor
pnpm add @tasks-timeline/components
`typescript
import React, { useState } from "react";
import {
TodoList,
InputBar,
type Task,
} from "@tasks-timeline/components";
import "@tasks-timeline/components/styles";
function App() {
const [tasks, setTasks] = useState
const handleAddTask = (task: Task) => {
setTasks([...tasks, task]);
};
return (
export default App;
`
The library supports efficient external synchronization with databases, REST APIs, or cloud services through operation-based callbacks:
`typescript
import { TasksTimelineApp } from "@tasks-timeline/components";
function App() {
return (
onTaskAdded={async (task) => {
await fetch("/api/tasks", {
method: "POST",
body: JSON.stringify(task),
});
}}
// Called when a task is updated (only serializes the changed task)
onTaskUpdated={async (task, previous) => {
await fetch(/api/tasks/${task.id}, {/api/tasks/${taskId}
method: "PATCH",
body: JSON.stringify(task),
});
}}
// Called when a task is deleted (only sends the task ID)
onTaskDeleted={async (taskId, previous) => {
await fetch(, {`
method: "DELETE",
});
}}
/>
);
}
Performance Benefits:
- ā
99% less data transfer (1KB vs 100KB for single task updates)
- ā
50-80% fewer database writes (change detection skips no-ops)
- ā
Granular updates (UPDATE one row, not replace entire table)
- ā
Perfect for REST APIs, GraphQL, Firebase, or any external storage
Firebase Example:
`typescript
import { doc, setDoc, updateDoc, deleteDoc } from "firebase/firestore";
await setDoc(doc(db, "tasks", task.id), task);
}}
onTaskUpdated={async (task) => {
await updateDoc(doc(db, "tasks", task.id), task);
}}
onTaskDeleted={async (taskId) => {
await deleteDoc(doc(db, "tasks", taskId));
}}
/>
`
LocalStorage with Granular Updates:
`typescript`
const tasks = JSON.parse(localStorage.getItem("tasks") || "[]");
const updated = tasks.map((t) => (t.id === task.id ? task : t));
localStorage.setItem("tasks", JSON.stringify(updated));
}}
/>
> Note: Callbacks are optional. The component uses the repository pattern as a fallback for backwards compatibility.
`typescript`
import {
TaskItem,
TaskEditModal,
SettingsModal,
} from "@tasks-timeline/components";
`typescript
import {
useTaskFiltering,
useTaskStats,
useAIAgent,
} from "@tasks-timeline/components/hooks";
function MyComponent({ tasks }) {
const { filteredTasks, filters } = useTaskFiltering(tasks, {
statuses: ["todo", "scheduled"],
priorities: ["high"],
});
const stats = useTaskStats(tasks);
return (
Total: {stats.total}, Completed: {stats.completed}
Components
| Component | Description |
| ---------------- | ------------------------------------------- |
|
TodoList | Main container component with task grouping |
| TaskItem | Individual task display with actions |
| InputBar | Create/edit tasks with AI support |
| DaySection | Tasks grouped by day |
| YearSection | Tasks grouped by year |
| BacklogSection | Unscheduled tasks view |
| TaskEditModal | Full-featured task editor |
| SettingsModal | Application settings |
| HelpModal | Help and documentation |
| Toast | Notification system |
| Icon | Icon wrapper for Lucide icons |Hooks
$3
Filter tasks by status, priority, category, tags, and custom scripts.
`typescript
const { filteredTasks, filters, setFilters } = useTaskFiltering(
tasks,
initialFilters
);
`$3
Calculate task statistics including completion percentage, counts by status, etc.
`typescript
const stats = useTaskStats(tasks);
// { total, completed, byStatus, byPriority, ... }
`$3
Integrate AI for task processing and insights.
`typescript
const { processTask, generateSuggestions, isLoading } = useAIAgent(
settings.aiConfig
);
`$3
Handle browser voice input or Whisper API integration.
`typescript
const { transcript, isListening, startListening, stopListening } =
useVoiceInput();
`Types
`typescript
type Priority = "low" | "medium" | "high";
type TaskStatus =
| "done"
| "scheduled"
| "todo"
| "due"
| "overdue"
| "cancelled"
| "unplanned";interface Task {
id: string;
title: string;
description?: string;
status: TaskStatus;
priority: Priority;
dueDate?: string;
category?: string;
tags: Tag[];
isRecurring?: boolean;
// ... and more
}
interface AppSettings {
theme: "light" | "dark" | "midnight" | "coffee";
dateFormat: string;
showCompleted: boolean;
// ... and more
}
`Styling
$3
`typescript
import "@tasks-timeline/components/styles";
`$3
The library uses Tailwind CSS v4. Ensure your project has Tailwind configured:
`typescript
// vite.config.ts
import tailwindcss from "@tailwindcss/vite";export default {
plugins: [tailwindcss()],
};
`$3
Components use Tailwind classes and can be customized through props and CSS overrides:
`typescript
`Configuration
$3
`typescript
interface TasksTimelineAppProps {
className?: string;
taskRepository?: TaskRepository;
settingsRepository?: SettingsRepository;
apiKey?: string;
systemInDarkMode?: boolean;
onItemClick?: (item: Task) => void; // External synchronization callbacks (v0.0.4+)
onTaskAdded?: (task: Task) => void | Promise;
onTaskUpdated?: (task: Task, previous: Task) => void | Promise;
onTaskDeleted?: (taskId: string, previous: Task) => void | Promise;
}
`Synchronization Strategy:
- If callbacks (
onTaskAdded, etc.) are provided, they take priority
- Otherwise, falls back to taskRepository methods
- Callbacks receive both new and previous state for conflict resolution
- All callbacks support async/await for database operations$3
`typescript
const settings: AppSettings = {
theme: "dark",
dateFormat: "MMM d, yyyy",
// ...
};
`$3
`typescript
const settings: AppSettings = {
aiConfig: {
enabled: true,
activeProvider: "gemini",
providers: {
gemini: {
apiKey: "your-api-key",
model: "gemini-3-flash-preview",
baseUrl: "",
},
// ... other providers
},
},
};
`Development
$3
`bash
git clone
cd tasks-timeline
pnpm install
`$3
`bash
pnpm dev
`$3
`bash
pnpm storybook
`$3
`bash
pnpm build:lib
`$3
`bash
pnpm build
`Project Structure
`
src/
āāā components/ # UI Components
āāā hooks/ # Custom React Hooks
āāā types.ts # Type Definitions
āāā utils.ts # Utilities
āāā storage.ts # Browser Storage
āāā App.tsx # Demo Application
āāā index.ts # Library Entry Point
`Development
$3
`bash
Install dependencies
pnpm installStart Storybook (interactive documentation)
pnpm storybookRun type checking
pnpm type-checkRun linter
pnpm lintBuild library
pnpm build
`$3
The
examples/app/ directory contains a fully functional demo application:`bash
Run example app
pnpm dev:exampleBuild example app
pnpm build:example
`Publishing
$3
This project uses GitHub Actions to automate the build, testing, and publishing process.
Requirements:
1. Set up
NPM_TOKEN secret in GitHub repository settings
2. Ensure main branch is protected with required status checksTo publish a new version:
`bash
1. Update version in package.json
npm version patch # or minor/major2. Push to trigger GitHub Actions workflow
git push origin main --tags
`The workflow will automatically:
- ā
Run all tests (lint, type-check, build)
- ā
Create a GitHub release
- ā
Publish to npm
- ā
Deploy Storybook to GitHub Pages
Alternative: Use
npm publish directly (requires npm authentication):`bash
npm publish --access public
`See .github/WORKFLOW_SETUP.md for detailed setup and troubleshooting.
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines on:
- Setting up your development environment
- Code style and standards
- Adding new components or hooks
- Writing Storybook stories
- Submitting pull requests
- Commit message conventions
Quick start for contributors:
`bash
git clone
cd tasks-timeline
pnpm install
pnpm storybook # View components
pnpm type-check # Verify types
pnpm lint # Check code style
`Documentation
- See LIBRARY_SETUP.md for detailed setup and architecture
- Visit Storybook (run
pnpm storybook`) for interactive component documentation- Chrome/Edge (latest 2 versions)
- Firefox (latest 2 versions)
- Safari 14+
- React 18.2.0+
- React DOM 18.2.0+
MIT Ā© zhuwenq