/* Copyright (c) 2025 Bernier LLC

This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC. */

@bernierllc/tasks

A fully abstracted, pluggable tasks/pending actions system for Next.js applications. This package provides user-specific and group tasks, action completion tracking, admin analytics, and seamless integration capabilities.

What's New

• Admin Features: Manage task types, view analytics, and audit task history with new admin components
• Analytics Dashboard: Visualize task completion rates, breakdowns, and averages
• History & Auditing: Track all actions and changes on tasks
• Comprehensive Documentation: See Admin Features and API Reference
• Expanded Test Coverage: All features are covered by tests using real data and in-memory services

Features

• User & Group Tasks: Support for individual user tasks and group-wide tasks
• Priority Management: Urgent, high, and normal priority levels with visual indicators
• Task Types: Extensible task type system with custom icons and default priorities
• Real-time Updates: Auto-refresh capabilities with configurable intervals
• Advanced Filtering: Search, filter by priority, type, status, and date ranges
• Completion Tracking: Task completion with optional notes and audit trail
• Responsive UI: Modern, accessible components built with React and TypeScript
• Type Safety: Full TypeScript support with Zod validation schemas
• Admin Features: Manage task types, view analytics, and audit task history
• Analytics Dashboard: Visualize task completion rates, breakdowns, and averages
• History & Auditing: Track all actions and changes on tasks
• Extensible API: Easily integrate with your own backend endpoints

Documentation

• Getting Started
• Admin Features
• API Reference
• Examples

Installation

npm install @bernierllc/tasks

Quick Start

Basic Usage

import { TasksPanel } from '@bernierllc/tasks';

function MyApp() {
  return (
    <div className="container mx-auto p-4">
      <TasksPanel 
        userId="user-123"
        showCreateButton={true}
        showFilters={true}
        showTabs={true}
      />
    </div>
  );
}

Using the Hook

import { useTasks } from '@bernierllc/tasks';

function TaskList() {
  const { 
    tasks, 
    loading, 
    error, 
    createTask, 
    completeTask 
  } = useTasks({
    initialFilters: { userId: 'user-123' },
    autoRefresh: true,
    refreshInterval: 30000
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div>
      {tasks.map(task => (
        <div key={task.id}>
          <h3>{task.title}</h3>
          <p>{task.description}</p>
          <button onClick={() => completeTask(task.id, { completedBy: 'user-123' })}>
            Complete
          </button>
        </div>
      ))}
    </div>
  );
}

Individual Task Card

import { TaskCard } from '@bernierllc/tasks';

function TaskItem({ task }) {
  return (
    <TaskCard
      task={task}
      onComplete={async (id, request) => {
        // Handle task completion
        console.log('Task completed:', id, request);
      }}
      onUpdate={async (id, updates) => {
        // Handle task updates
        console.log('Task updated:', id, updates);
      }}
      onDelete={async (id) => {
        // Handle task deletion
        console.log('Task deleted:', id);
      }}
    />
  );
}

Admin Features

Task Types Management

import { AdminTaskTypes } from '@bernierllc/tasks';

function TaskTypesAdmin() {
  return <AdminTaskTypes />;
}

Analytics Dashboard

import { AdminTaskAnalytics } from '@bernierllc/tasks';

function TaskAnalytics() {
  return <AdminTaskAnalytics />;
}

Task History

import { TaskHistory } from '@bernierllc/tasks';

function TaskHistoryPanel() {
  return <TaskHistory userId="user-123" />;
}

See Admin Features documentation for full details and customization options.

API Reference

See the API Reference for full details on all endpoints, request/response schemas, and integration examples.

Main Endpoints

• GET /api/tasks - List tasks with optional query parameters
• POST /api/tasks - Create a new task
• PATCH /api/tasks/:id - Update a task
• DELETE /api/tasks/:id - Delete a task
• POST /api/tasks/:id/complete - Complete a task
• GET /api/task-types - List task types
• POST /api/task-types - Create a new task type
• PATCH /api/task-types/:id - Update a task type
• DELETE /api/task-types/:id - Delete a task type
• GET /api/tasks/analytics - Get analytics dashboard data
• GET /api/tasks/history - Get task action history

Styling

The components use Tailwind CSS classes for styling. Make sure Tailwind CSS is included in your project.

Examples

See the examples/ directory for complete usage examples:

• Basic usage with Next.js
• Advanced filtering and search
• Custom task types
• Integration with authentication systems
• Admin dashboard and analytics

Testing

• All features are covered by tests (components, hooks, services, schemas)
• Tests use real data and in-memory services (no mocks)
• To run tests:

npm test

or (from monorepo root):

npm run test --workspace=@bernierllc/tasks

Publishing

• Prepublish validation: license and package validation are run automatically
• All files include the required license header
• To publish all packages:

npm run publish:all

• See NPM_PUBLISH_CHECKLIST.md for details

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

ISC - See LICENSE file for details.

Monorepo Workspaces & Dependency Management

This package is part of a monorepo using npm workspaces. All dependencies are hoisted to the root. Always run npm install from the root directory.

React 19 and Testing Library Compatibility

This package uses React 19.1.0. If you see peer dependency warnings with Testing Library, use:

npm install --legacy-peer-deps

This is a temporary workaround until official support is released.