@emberai-engg/task-board 0.3.0

package/README.md

@@ -0,0 +1,160 @@
+# @emberai-engg/task-board
+
+Reusable Kanban task board component with built-in create/detail UI.
+
+## Installation
+
+```bash
+npm install @emberai-engg/task-board
+```
+
+## Quick Start
+
+No render props needed. The package ships with a complete UI out of the box:
+
+```tsx
+import { TaskBoardProvider, TaskBoard } from '@emberai-engg/task-board';
+import '@emberai-engg/task-board/styles.css';
+import { apiClient } from './lib/api';
+
+function App() {
+  const user = useAuth();
+
+  return (
+    <TaskBoardProvider
+      apiClient={apiClient}
+      user={{
+        username: user.username,
+        name: user.name,
+        email: user.email,
+        apps: user.apps,
+        is_internal: user.is_internal,
+        is_reviewer: user.is_reviewer,
+      }}
+      projects={[
+        { slug: 'my-project', name: 'My Project' },
+      ]}
+    >
+      <TaskBoard onShareFeedback={() => router.push('/feedback')} />
+    </TaskBoardProvider>
+  );
+}
+```
+
+This gives you:
+- Kanban board with drag-and-drop
+- Built-in **CreateTaskModal** (two-column layout with title, structured description, priority, status, tags)
+- Built-in **TaskDetailPanel** (slide-over with properties grid, description sections, activity timeline, comments with @mentions)
+- Notification bell with polling
+- Tag filtering
+- Share links
+- Loading skeletons and empty states
+
+## Props / Config Reference
+
+### `TaskBoardProvider`
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `apiClient` | `ApiClient` | Yes | Axios-like HTTP client with auth headers |
+| `user` | `TaskBoardUser` | Yes | Current logged-in user |
+| `projects` | `Project[]` | No | Available projects |
+| `columns` | `ColumnConfig[]` | No | Column definitions (defaults to 8-column kanban) |
+| `priorities` | `PriorityConfig[]` | No | Priority levels |
+| `tags` | `TagConfig[]` | No | Predefined tags |
+| `apiBasePath` | `string` | No | API prefix (defaults to `/api/v1/taskboard`) |
+| `features` | `object` | No | Feature flags for enabling/disabling features |
+| `onTaskCreate` | `(task) => void` | No | Callback on task creation |
+| `onTaskUpdate` | `(task) => void` | No | Callback on task update |
+| `onTaskDelete` | `(id) => void` | No | Callback on task deletion |
+| `onError` | `(error) => void` | No | Error handler callback |
+
+### `TaskBoard`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `className` | `string` | CSS class for the outer container |
+| `headerActions` | `ReactNode` | Additional buttons in the header |
+| `onShareFeedback` | `() => void` | Callback for Share Feedback button. Hidden if omitted. |
+| `onTaskOpen` | `(task) => void` | Callback when a task is clicked |
+| `renderTaskDetail` | `function` | Override for task detail panel (built-in used if omitted) |
+| `renderCreateTask` | `function` | Override for create task modal (built-in used if omitted) |
+
+### Overriding built-in UI
+
+If you need custom create/detail UI, pass render props:
+
+```tsx
+<TaskBoard
+  renderCreateTask={({ projectSlug, defaultStatus, onClose, onCreate }) => (
+    <MyCustomCreateModal ... />
+  )}
+  renderTaskDetail={({ task, onClose, onUpdate }) => (
+    <MyCustomDetailPanel ... />
+  )}
+/>
+```
+
+## Using Individual Components
+
+```tsx
+import {
+  TaskCard, PriorityBadge, UserAvatar,
+  CreateTaskModal, TaskDetailPanel,
+  useTaskActions,
+} from '@emberai-engg/task-board';
+
+// Use hooks independently
+function MyCustomUI() {
+  const { createTask, moveTask } = useTaskActions(tasks, setTasks, fetchTasks);
+  // ...
+}
+
+// Use small components
+<PriorityBadge priority="high" />
+<UserAvatar name="John Smith" size="sm" showTooltip />
+```
+
+## Hooks API
+
+| Hook | Purpose |
+|------|---------|
+| `useTaskBoard()` | Board state: projects, tasks, loading, pagination |
+| `useTaskActions(tasks, setTasks, fetchTasks)` | CRUD: create, update, delete, move tasks |
+| `useTaskDetail(taskId)` | Single task: comments, activity, field updates |
+| `useShareLink()` | Copy shareable task URLs |
+
+## Feature Flags
+
+```tsx
+<TaskBoardProvider
+  features={{
+    dragAndDrop: true,      // Drag-and-drop between columns
+    comments: true,         // Comment system
+    mentions: true,         // @mention users
+    notifications: true,    // Notification bell
+    internalComments: true, // Internal-only comments
+    tags: true,             // Tag system
+    sharing: true,          // Shareable task links
+    filters: true,          // Tag filtering
+    unreadIndicators: true, // Unread dots on cards
+  }}
+/>
+```
+
+## Development
+
+```bash
+npm install
+npm run dev    # Watch mode
+npm run build  # Production build
+npm test       # Run tests
+```
+
+## Backend
+
+The `backend-reference/` folder contains a Python FastAPI reference implementation for the task board API. Copy it into your app's backend and adapt the auth and database setup to match your app. See [`backend-reference/README.md`](backend-reference/README.md) for details.
+
+## License
+
+Private — internal use only.

package/dist/index.d.mts

@@ -0,0 +1,442 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+import React__default from 'react';
+
+interface Project {
+    slug: string;
+    name: string;
+}
+interface StructuredDescription {
+    problem: string;
+    user_story: string;
+    proposed_behavior: string;
+    acceptance_criteria: string;
+    open_questions: string;
+}
+interface Task {
+    id: string;
+    project_slug: string;
+    title: string;
+    description: StructuredDescription;
+    status: string;
+    priority: string;
+    position: number;
+    created_by: string;
+    created_by_name: string;
+    comment_count: number;
+    tags?: string[];
+    created_at: string;
+    updated_at: string;
+    has_unread?: boolean;
+}
+interface ActivityEntry {
+    id: string;
+    type: string;
+    from_status: string;
+    to_status: string;
+    user: string;
+    user_name: string;
+    created_at: string;
+}
+interface Comment {
+    id: string;
+    task_id: string;
+    content: string;
+    author_id: string;
+    author_name: string;
+    is_internal?: boolean;
+    edited?: boolean;
+    edited_at?: string;
+    created_at: string;
+}
+interface Notification {
+    id: string;
+    type: string;
+    context: string;
+    actor_name: string;
+    actor_username: string;
+    task_id: string;
+    task_title: string;
+    project_slug: string;
+    snippet: string;
+    read: boolean;
+    created_at: string;
+}
+interface MentionUser {
+    username: string;
+    name: string;
+    email: string;
+}
+type TasksByStatus = Record<string, Task[]>;
+type ColumnTotals = Record<string, number>;
+type ColumnUnreads = Record<string, number>;
+interface ColumnConfig {
+    key: string;
+    label: string;
+    color: string;
+    description: string;
+}
+interface PriorityConfig {
+    value: string;
+    label: string;
+    className: string;
+}
+interface TagConfig {
+    value: string;
+    label: string;
+    className: string;
+}
+interface DescriptionSectionConfig {
+    key: keyof StructuredDescription;
+    label: string;
+}
+interface TaskBoardUser {
+    username: string;
+    name: string;
+    email: string;
+    apps: string[];
+    role?: string;
+    is_reviewer?: boolean;
+    is_internal?: boolean;
+}
+interface ApiClientConfig {
+    params?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    [key: string]: unknown;
+}
+interface ApiClient {
+    get: <T>(url: string, config?: ApiClientConfig) => Promise<{
+        data: T;
+    }>;
+    post: <T>(url: string, data?: unknown, config?: ApiClientConfig) => Promise<{
+        data: T;
+    }>;
+    put: <T>(url: string, data?: unknown, config?: ApiClientConfig) => Promise<{
+        data: T;
+    }>;
+    patch: <T>(url: string, data?: unknown, config?: ApiClientConfig) => Promise<{
+        data: T;
+    }>;
+    delete: <T>(url: string, config?: ApiClientConfig) => Promise<{
+        data: T;
+    }>;
+}
+interface ColumnResponse {
+    tasks: Task[];
+    total: number;
+    unread: number;
+}
+interface TaskDetailResponse extends Task {
+    comments: Comment[];
+    activity: ActivityEntry[];
+}
+interface NotificationCountResponse {
+    count: number;
+}
+interface CreateTaskPayload {
+    project_slug: string;
+    title: string;
+    description?: StructuredDescription;
+    priority: string;
+    status: string;
+    tags: string[];
+}
+interface UpdateTaskPayload {
+    title?: string;
+    description?: StructuredDescription;
+    priority?: string;
+    status?: string;
+    position?: number;
+    tags?: string[];
+}
+interface CreateCommentPayload {
+    content: string;
+    is_internal?: boolean;
+}
+interface EditCommentPayload {
+    content: string;
+}
+
+interface TaskBoardProps {
+    /** Optional class name for the outer container */
+    className?: string;
+    /** Optional header content (e.g., feedback link) to render in the header bar */
+    headerActions?: React__default.ReactNode;
+    /** Callback when a task detail panel should open */
+    onTaskOpen?: (task: Task) => void;
+    /** Callback for the Share Feedback button. If not provided, the button is hidden. */
+    onShareFeedback?: () => void;
+    /** Render function for the task detail panel. If omitted, uses built-in TaskDetailPanel. */
+    renderTaskDetail?: (props: {
+        task: Task;
+        onClose: () => void;
+        onUpdate: () => void;
+    }) => React__default.ReactNode;
+    /** Render function for the create task modal. If omitted, uses built-in CreateTaskModal. */
+    renderCreateTask?: (props: {
+        projectSlug: string;
+        defaultStatus: string;
+        onClose: () => void;
+        onCreate: () => void;
+    }) => React__default.ReactNode;
+}
+declare function TaskBoard({ className, headerActions, onTaskOpen, onShareFeedback, renderTaskDetail, renderCreateTask, }: TaskBoardProps): react_jsx_runtime.JSX.Element;
+
+interface TaskCardProps {
+    task: Task;
+    index: number;
+    onClick: () => void;
+    onShare: (e: React__default.MouseEvent) => void;
+    copied: boolean;
+}
+declare const TaskCard: React__default.NamedExoticComponent<TaskCardProps>;
+
+interface KanbanColumnProps {
+    column: ColumnConfig;
+    tasks: Task[];
+    totalCount: number;
+    unreadCount: number;
+    loadingMore: boolean;
+    onAddTask: () => void;
+    onTaskClick: (task: Task) => void;
+    onTaskShare: (taskId: string, e: React__default.MouseEvent) => void;
+    copiedTaskId: string | null;
+    onLoadMore: () => void;
+}
+declare function KanbanColumn({ column, tasks, totalCount, unreadCount, loadingMore, onAddTask, onTaskClick, onTaskShare, copiedTaskId, onLoadMore, }: KanbanColumnProps): react_jsx_runtime.JSX.Element;
+
+interface FilterBarProps {
+    projects: Project[];
+    selectedProject: string;
+    onSelectProject: (slug: string) => void;
+    filterTags: string[];
+    onSetFilterTags: (tags: string[]) => void;
+}
+declare function FilterBar({ projects, selectedProject, onSelectProject, filterTags, onSetFilterTags, }: FilterBarProps): react_jsx_runtime.JSX.Element;
+
+interface NotificationBellProps {
+    onOpenTask: (taskId: string, projectSlug: string) => void;
+}
+declare function NotificationBell({ onOpenTask }: NotificationBellProps): react_jsx_runtime.JSX.Element;
+
+interface PriorityBadgeProps {
+    priority: string;
+    size?: 'sm' | 'md';
+}
+declare function PriorityBadge({ priority, size }: PriorityBadgeProps): react_jsx_runtime.JSX.Element;
+
+interface UserAvatarProps {
+    name: string;
+    size?: 'xs' | 'sm' | 'md';
+    showTooltip?: boolean;
+    className?: string;
+}
+declare function UserAvatar({ name, size, showTooltip, className }: UserAvatarProps): react_jsx_runtime.JSX.Element;
+
+interface TagBadgeProps {
+    tag: string;
+    onRemove?: () => void;
+    size?: 'sm' | 'md';
+}
+declare function TagBadge({ tag, onRemove, size }: TagBadgeProps): react_jsx_runtime.JSX.Element;
+
+/** Renders text with @mentions highlighted as styled badges. */
+declare function MentionText({ text, className }: {
+    text: string;
+    className?: string;
+}): react_jsx_runtime.JSX.Element | null;
+/** Convert stored @[Name](username) to display @Name for textarea */
+declare function toDisplayText(stored: string): string;
+/** Convert display @Name back to stored @[Name](username) using a mention map */
+declare function toStoredText(display: string, mentionMap: Map<string, string>): string;
+
+interface MentionTextareaProps {
+    value: string;
+    onChange: (val: string) => void;
+    onKeyDown?: (e: React__default.KeyboardEvent<HTMLTextAreaElement>) => void;
+    placeholder?: string;
+    rows?: number;
+    className?: string;
+    disabled?: boolean;
+}
+declare function MentionTextarea({ value, onChange, onKeyDown, placeholder, rows, className, disabled, }: MentionTextareaProps): react_jsx_runtime.JSX.Element;
+
+declare function SkeletonPulse({ className }: {
+    className?: string;
+}): react_jsx_runtime.JSX.Element;
+declare function SkeletonCard(): react_jsx_runtime.JSX.Element;
+declare function BoardSkeleton(): react_jsx_runtime.JSX.Element;
+
+interface CreateTaskModalProps {
+    projectSlug: string;
+    defaultStatus?: string;
+    onClose: () => void;
+    onCreate: () => void;
+}
+declare function CreateTaskModal({ projectSlug, defaultStatus, onClose, onCreate, }: CreateTaskModalProps): react_jsx_runtime.JSX.Element;
+
+interface TaskDetailPanelProps {
+    task: Task;
+    projectSlug: string;
+    onClose: () => void;
+    onUpdate: () => void;
+}
+declare function TaskDetailPanel({ task, projectSlug, onClose, onUpdate }: TaskDetailPanelProps): react_jsx_runtime.JSX.Element;
+
+interface TaskBoardService {
+    listTasks(projectSlug: string, perColumn?: number): Promise<Record<string, ColumnResponse>>;
+    listColumnTasks(projectSlug: string, statusKey: string, offset: number, limit: number): Promise<Task[]>;
+    getTask(taskId: string): Promise<TaskDetailResponse>;
+    createTask(data: CreateTaskPayload): Promise<Task>;
+    updateTask(taskId: string, data: UpdateTaskPayload): Promise<Task>;
+    deleteTask(taskId: string): Promise<void>;
+    markTaskRead(taskId: string): Promise<void>;
+    listComments(taskId: string): Promise<Comment[]>;
+    addComment(taskId: string, data: CreateCommentPayload): Promise<Comment>;
+    editComment(taskId: string, commentId: string, data: EditCommentPayload): Promise<Comment>;
+    deleteComment(taskId: string, commentId: string): Promise<void>;
+    searchMentionUsers(query: string): Promise<MentionUser[]>;
+    getNotificationCount(): Promise<number>;
+    listNotifications(limit?: number): Promise<Notification[]>;
+    markNotificationRead(notificationId: string): Promise<void>;
+    markAllNotificationsRead(): Promise<void>;
+}
+declare function createTaskBoardService(apiClient: ApiClient, basePath?: string): TaskBoardService;
+
+interface TaskBoardConfig {
+    /** Axios-like API client with auth headers pre-configured */
+    apiClient: ApiClient;
+    /** Current logged-in user */
+    user: TaskBoardUser;
+    /** Available projects (if not provided, derived from user.apps) */
+    projects?: Project[];
+    /** Column configuration (defaults to 8-column kanban) */
+    columns?: ColumnConfig[];
+    /** Priority levels (defaults to Critical/High/Medium/Low) */
+    priorities?: PriorityConfig[];
+    /** Predefined tags (defaults to 6 built-in tags) */
+    tags?: TagConfig[];
+    /** Base API path (defaults to '/api/v1/taskboard') */
+    apiBasePath?: string;
+    /** Callbacks */
+    onTaskCreate?: (task: Task) => void;
+    onTaskUpdate?: (task: Task) => void;
+    onTaskDelete?: (taskId: string) => void;
+    onError?: (error: Error) => void;
+    onNavigate?: (path: string) => void;
+    /** Feature flags */
+    features?: {
+        dragAndDrop?: boolean;
+        comments?: boolean;
+        mentions?: boolean;
+        notifications?: boolean;
+        internalComments?: boolean;
+        tags?: boolean;
+        sharing?: boolean;
+        filters?: boolean;
+        unreadIndicators?: boolean;
+    };
+}
+interface TaskBoardContextValue {
+    service: TaskBoardService;
+    user: TaskBoardUser;
+    projects: Project[];
+    columns: ColumnConfig[];
+    priorities: PriorityConfig[];
+    tags: TagConfig[];
+    config: TaskBoardConfig;
+    features: Required<NonNullable<TaskBoardConfig['features']>>;
+}
+declare function useTaskBoardContext(): TaskBoardContextValue;
+declare function TaskBoardProvider({ children, ...config }: TaskBoardConfig & {
+    children: React__default.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare function useTaskBoard(): {
+    projects: Project[];
+    selectedProject: string;
+    setSelectedProject: React$1.Dispatch<React$1.SetStateAction<string>>;
+    tasks: TasksByStatus;
+    setTasks: React$1.Dispatch<React$1.SetStateAction<TasksByStatus>>;
+    columnTotals: ColumnTotals;
+    columnUnreads: ColumnUnreads;
+    setColumnUnreads: React$1.Dispatch<React$1.SetStateAction<ColumnUnreads>>;
+    boardLoading: boolean;
+    loadingMore: Record<string, boolean>;
+    error: string;
+    setError: React$1.Dispatch<React$1.SetStateAction<string>>;
+    successMessage: string;
+    showSuccess: (msg: string) => void;
+    fetchTasks: () => Promise<void>;
+    loadMoreTasks: (statusKey: string) => Promise<void>;
+};
+
+declare function useTaskActions(tasks: TasksByStatus, setTasks: React.Dispatch<React.SetStateAction<TasksByStatus>>, fetchTasks: () => Promise<void>): {
+    createTask: (data: CreateTaskPayload) => Promise<Task>;
+    updateTask: (taskId: string, data: UpdateTaskPayload) => Promise<Task>;
+    deleteTask: (taskId: string) => Promise<void>;
+    markTaskRead: (taskId: string) => Promise<void>;
+    moveTask: (taskId: string, sourceStatus: string, destStatus: string, sourceIndex: number, destIndex: number) => Promise<void>;
+};
+
+declare function useTaskDetail(taskId: string): {
+    comments: Comment[];
+    activity: ActivityEntry[];
+    commentsLoaded: boolean;
+    commentLoading: boolean;
+    addComment: (content: string, isInternal?: boolean) => Promise<void>;
+    editComment: (commentId: string, content: string) => Promise<void>;
+    deleteComment: (commentId: string) => Promise<void>;
+    saveField: (field: string, value: unknown) => Promise<void>;
+    refreshDetail: () => Promise<void>;
+};
+
+declare function useShareLink(): {
+    copiedTaskId: string | null;
+    copyShareLink: (taskId: string, projectSlug: string) => void;
+};
+
+declare function getPriorityStyle(priority: string): PriorityConfig;
+declare function getTagStyle(tag: string): TagConfig;
+declare function getInitials(name: string): string;
+declare function formatDate(dateStr: string): string;
+declare function formatDateTime(dateStr: string): string;
+declare function getDescriptionPreview(desc: StructuredDescription | string | undefined): string;
+declare function hasDescription(desc: StructuredDescription | string | undefined): boolean;
+declare function getUserProjects(apps: string[], allProjects: {
+    slug: string;
+    name: string;
+}[]): {
+    slug: string;
+    name: string;
+}[];
+
+declare const DEFAULT_COLUMNS: ColumnConfig[];
+declare const DEFAULT_PRIORITIES: PriorityConfig[];
+declare const PREDEFINED_TAGS: TagConfig[];
+declare const DESCRIPTION_SECTIONS: DescriptionSectionConfig[];
+declare const EMPTY_DESCRIPTION: StructuredDescription;
+declare const POSITION_GAP = 1000;
+declare const DEFAULT_PAGE_SIZE = 10;
+
+interface IconProps {
+    className?: string;
+    size?: number;
+    strokeWidth?: number;
+}
+declare const PlusIcon: React__default.FC<IconProps>;
+declare const XIcon: React__default.FC<IconProps>;
+declare const ChevronDownIcon: React__default.FC<IconProps>;
+declare const MessageSquareIcon: React__default.FC<IconProps>;
+declare const KanbanIcon: React__default.FC<IconProps>;
+declare const LinkIcon: React__default.FC<IconProps>;
+declare const CheckIcon: React__default.FC<IconProps>;
+declare const BellIcon: React__default.FC<IconProps>;
+declare const FilterIcon: React__default.FC<IconProps>;
+declare const PencilIcon: React__default.FC<IconProps>;
+declare const TrashIcon: React__default.FC<IconProps>;
+declare const LockIcon: React__default.FC<IconProps>;
+declare const FeedbackIcon: React__default.FC<IconProps>;
+
+export { type ActivityEntry, type ApiClient, type ApiClientConfig, BellIcon, BoardSkeleton, CheckIcon, ChevronDownIcon, type ColumnConfig, type ColumnResponse, type ColumnTotals, type ColumnUnreads, type Comment, type CreateCommentPayload, CreateTaskModal, type CreateTaskModalProps, type CreateTaskPayload, DEFAULT_COLUMNS, DEFAULT_PAGE_SIZE, DEFAULT_PRIORITIES, DESCRIPTION_SECTIONS, type DescriptionSectionConfig, EMPTY_DESCRIPTION, type EditCommentPayload, FeedbackIcon, FilterBar, type FilterBarProps, FilterIcon, KanbanColumn, type KanbanColumnProps, KanbanIcon, LinkIcon, LockIcon, MentionText, MentionTextarea, type MentionTextareaProps, type MentionUser, MessageSquareIcon, type Notification, NotificationBell, type NotificationBellProps, type NotificationCountResponse, POSITION_GAP, PREDEFINED_TAGS, PencilIcon, PlusIcon, PriorityBadge, type PriorityBadgeProps, type PriorityConfig, type Project, SkeletonCard, SkeletonPulse, type StructuredDescription, TagBadge, type TagBadgeProps, type TagConfig, type Task, TaskBoard, type TaskBoardConfig, type TaskBoardContextValue, type TaskBoardProps, TaskBoardProvider, type TaskBoardService, type TaskBoardUser, TaskCard, type TaskCardProps, TaskDetailPanel, type TaskDetailPanelProps, type TaskDetailResponse, type TasksByStatus, TrashIcon, type UpdateTaskPayload, UserAvatar, type UserAvatarProps, XIcon, createTaskBoardService, formatDate, formatDateTime, getDescriptionPreview, getInitials, getPriorityStyle, getTagStyle, getUserProjects, hasDescription, toDisplayText, toStoredText, useShareLink, useTaskActions, useTaskBoard, useTaskBoardContext, useTaskDetail };