@tuturuuu/utils 0.0.3 → 0.6.0

package/src/task-helpers.ts

@@ -0,0 +1,241 @@
+/**
+ * Utility functions for task management and calculations
+ */
+import type { Active, Over } from '@dnd-kit/core';
+import type { TaskPriority } from '@tuturuuu/types/primitives/Priority';
+
+interface Task {
+  id: string;
+  name: string;
+  description?: string;
+  priority?: TaskPriority | null;
+  created_at?: string;
+  updated_at?: string;
+  end_date?: string | null;
+  boardId: string;
+  boardName: string;
+  listName: string;
+  listStatus?: string;
+  archived?: boolean;
+  completed_at?: string;
+  closed_at?: string;
+  finished_at?: string;
+  done_at?: string;
+  [key: string]: unknown;
+}
+
+interface BoardMetrics {
+  id: string;
+  totalTasks: number;
+  completedTasks: number;
+  overdueTasks: number;
+  highPriorityTasks: number;
+  progressPercentage: number;
+}
+
+interface DraggableData {
+  type: 'Task' | 'Column';
+  task?: unknown;
+  column?: unknown;
+}
+
+export function hasDraggableData(
+  element: Active | Over | null
+): element is Active | Over {
+  if (!element) return false;
+  if (!element.data?.current) return false;
+
+  const data = element.data.current as DraggableData;
+
+  if (data.type === 'Task' && !data.task) return false;
+  if (data.type === 'Column' && !data.column) return false;
+
+  return data.type === 'Task' || data.type === 'Column';
+}
+
+/**
+ * Calculate the number of days a task is overdue
+ * @param dueDate The task's due date
+ * @returns Number of days the task is overdue
+ */
+export function calculateOverdueDays(dueDate: string | Date): number {
+  const due = new Date(dueDate);
+  return Math.ceil((Date.now() - due.getTime()) / (1000 * 60 * 60 * 24));
+}
+
+/**
+ * Safe utility to get completion date from various possible fields
+ * @param task Task object with potential completion date fields
+ * @returns Date object or null if no valid completion date found
+ */
+export function getTaskCompletionDate(task: Task): Date | null {
+  const possibleFields = [
+    'updated_at',
+    'completed_at',
+    'closed_at',
+    'finished_at',
+    'done_at',
+  ];
+
+  // First try to get explicit completion dates
+  for (const field of possibleFields) {
+    const dateStr = task[field];
+    if (dateStr) {
+      const date = new Date(dateStr as string);
+      if (!Number.isNaN(date.getTime()) && date.getTime() > 0) {
+        return date;
+      }
+    }
+  }
+
+  // Fallback: if task is completed but no completion date, use updated_at or created_at as estimate
+  if (
+    task.listStatus === 'done' ||
+    task.listStatus === 'closed' ||
+    task.archived
+  ) {
+    // Try updated_at first (might indicate when status was changed)
+    if (task.updated_at) {
+      const date = new Date(task.updated_at);
+      if (!Number.isNaN(date.getTime()) && date.getTime() > 0) {
+        return date;
+      }
+    }
+
+    // Last resort: use creation date (not ideal but better than nothing)
+    if (task.created_at) {
+      const date = new Date(task.created_at);
+      if (!Number.isNaN(date.getTime()) && date.getTime() > 0) {
+        return date;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get status color for task visualization
+ * @param status Task status string
+ * @returns CSS class name for background color
+ */
+export function getStatusColor(status: string): string {
+  switch (status) {
+    case 'done':
+    case 'closed':
+      return 'bg-green-500';
+    case 'review':
+      return 'bg-orange-500';
+    case 'active':
+      return 'bg-blue-500';
+    default:
+      return 'bg-gray-400';
+  }
+}
+
+/**
+ * Filter tasks based on board selection and status
+ * @param tasks Array of tasks to filter
+ * @param boardId Board ID to filter by (null for all boards)
+ * @param statusFilter Status filter to apply
+ * @returns Filtered array of tasks
+ */
+export function filterTasks(
+  tasks: Task[],
+  boardId: string | null,
+  statusFilter: 'all' | 'not_started' | 'active' | 'review' | 'done' | 'closed'
+): Task[] {
+  let filtered = tasks;
+
+  // Filter by board
+  if (boardId) {
+    filtered = filtered.filter((task) => task.boardId === boardId);
+  }
+
+  // Filter by status
+  if (statusFilter !== 'all') {
+    filtered = filtered.filter((task) => {
+      const taskStatus = task.listStatus || 'not_started';
+      return taskStatus === statusFilter;
+    });
+  }
+
+  return filtered;
+}
+
+/**
+ * Group tasks by their status
+ * @param tasks Array of tasks to group
+ * @returns Object with tasks grouped by status
+ */
+export function groupTasksByStatus(tasks: Task[]): Record<string, Task[]> {
+  const groups: Record<string, Task[]> = {
+    not_started: [],
+    active: [],
+    done: [],
+    closed: [],
+  };
+
+  tasks.forEach((task) => {
+    if (task.archived || task.listStatus === 'done') {
+      groups.done?.push(task);
+    } else if (task.listStatus === 'closed') {
+      groups.closed?.push(task);
+    } else if (task.listStatus === 'active') {
+      groups.active?.push(task);
+    } else {
+      groups.not_started?.push(task);
+    }
+  });
+
+  return groups;
+}
+
+/**
+ * Calculate filtered metrics for boards based on selection
+ * @param data Array of board data
+ * @param selectedBoard Board ID to filter by (null for all boards)
+ * @returns Aggregated metrics
+ */
+export function getFilteredMetrics(
+  data: BoardMetrics[],
+  selectedBoard: string | null
+) {
+  const filteredData = selectedBoard
+    ? data.filter((board) => board.id === selectedBoard)
+    : data;
+
+  const totalTasks = filteredData.reduce(
+    (sum, board) => sum + board.totalTasks,
+    0
+  );
+  const totalCompleted = filteredData.reduce(
+    (sum, board) => sum + board.completedTasks,
+    0
+  );
+  const totalOverdue = filteredData.reduce(
+    (sum, board) => sum + board.overdueTasks,
+    0
+  );
+  const totalHighPriority = filteredData.reduce(
+    (sum, board) => sum + board.highPriorityTasks,
+    0
+  );
+  const avgProgress =
+    filteredData.length > 0
+      ? Math.round(
+          filteredData.reduce(
+            (sum, board) => sum + board.progressPercentage,
+            0
+          ) / filteredData.length
+        )
+      : 0;
+
+  return {
+    totalTasks,
+    totalCompleted,
+    totalOverdue,
+    totalHighPriority,
+    avgProgress,
+  };
+}

package/src/task-list-status.ts

@@ -0,0 +1,62 @@
+import type { SupportedColor } from '@tuturuuu/types/primitives/SupportedColors';
+import type { TaskBoardStatus } from '@tuturuuu/types/primitives/TaskBoard';
+
+export const TASK_BOARD_STATUSES = [
+  'documents',
+  'not_started',
+  'active',
+  'review',
+  'done',
+  'closed',
+] as const satisfies readonly TaskBoardStatus[];
+
+export const TASK_BOARD_WORKFLOW_STATUSES = [
+  'not_started',
+  'active',
+  'review',
+  'done',
+  'closed',
+] as const satisfies readonly TaskBoardStatus[];
+
+export function isTaskBoardStatus(
+  status: string | null | undefined
+): status is TaskBoardStatus {
+  return TASK_BOARD_STATUSES.includes(status as TaskBoardStatus);
+}
+
+export function isTaskBoardCompletedStatus(status: string | null | undefined) {
+  return status === 'done';
+}
+
+export function isTaskBoardResolvedStatus(status: string | null | undefined) {
+  return (
+    status === 'review' ||
+    isTaskBoardCompletedStatus(status) ||
+    status === 'closed'
+  );
+}
+
+export function isTaskBoardTerminalStatus(status: string | null | undefined) {
+  return status === 'done' || status === 'closed';
+}
+
+export function getDefaultTaskListColorForStatus(
+  status: string | null | undefined
+): SupportedColor {
+  switch (status) {
+    case 'documents':
+      return 'CYAN';
+    case 'not_started':
+      return 'GRAY';
+    case 'active':
+      return 'BLUE';
+    case 'review':
+      return 'ORANGE';
+    case 'done':
+      return 'GREEN';
+    case 'closed':
+      return 'PURPLE';
+    default:
+      return 'GRAY';
+  }
+}

package/src/task-overrides.ts

@@ -0,0 +1,82 @@
+import type {
+  TaskUserOverride,
+  TaskWithRelations,
+  UserBoardListOverride,
+} from '@tuturuuu/types';
+
+/**
+ * When self_managed is true, applies personal overrides to task fields.
+ * Returns a new task object with effective values; never mutates the original.
+ */
+export function resolveEffectiveValues(
+  task: TaskWithRelations,
+  overrides: TaskUserOverride | null | undefined
+): TaskWithRelations {
+  if (!overrides?.self_managed) return task;
+
+  return {
+    ...task,
+    priority:
+      overrides.priority_override !== null
+        ? overrides.priority_override
+        : task.priority,
+    end_date:
+      overrides.due_date_override !== null
+        ? overrides.due_date_override
+        : task.end_date,
+    estimation_points:
+      overrides.estimation_override !== null
+        ? overrides.estimation_override
+        : task.estimation_points,
+  };
+}
+
+/**
+ * Checks whether a task should be hidden from My Tasks based on:
+ * 1. Personal completion (completed_at is set)
+ * 2. Personal unassignment (personally_unassigned is true)
+ * 3. Board/list override status being 'done' or 'closed'
+ */
+export function isPersonallyHidden(
+  task: TaskWithRelations,
+  overrides: TaskUserOverride | null | undefined,
+  boardListOverrides: UserBoardListOverride[]
+): boolean {
+  // Check personal completion
+  if (overrides?.completed_at) return true;
+
+  // Check personal unassignment
+  if (overrides?.personally_unassigned) return true;
+
+  // Check board-level override
+  const boardId = task.list?.board?.id;
+  if (boardId) {
+    const boardOverride = boardListOverrides.find(
+      (o) => o.scope_type === 'board' && o.board_id === boardId
+    );
+    if (
+      boardOverride &&
+      (boardOverride.personal_status === 'done' ||
+        boardOverride.personal_status === 'closed')
+    ) {
+      return true;
+    }
+  }
+
+  // Check list-level override
+  const listId = task.list?.id;
+  if (listId) {
+    const listOverride = boardListOverrides.find(
+      (o) => o.scope_type === 'list' && o.list_id === listId
+    );
+    if (
+      listOverride &&
+      (listOverride.personal_status === 'done' ||
+        listOverride.personal_status === 'closed')
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}