@allpepper/task-orchestrator-tui 1.0.0

package/src/ui/hooks/use-debounce.ts

@@ -0,0 +1,37 @@
+import { useState, useEffect } from 'react';
+
+/**
+ * Debounces a value by delaying updates until the value has stopped changing
+ * for the specified delay period.
+ *
+ * @param value - The value to debounce
+ * @param delay - The delay in milliseconds
+ * @returns The debounced value
+ *
+ * @example
+ * ```tsx
+ * const searchQuery = useDebounce(inputValue, 500);
+ *
+ * useEffect(() => {
+ *   // This will only run 500ms after user stops typing
+ *   performSearch(searchQuery);
+ * }, [searchQuery]);
+ * ```
+ */
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    // Set up a timer to update the debounced value after the delay
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    // Clean up the timer if value changes before delay completes
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/src/ui/hooks/use-feature-kanban.ts

@@ -0,0 +1,151 @@
+import { useState, useEffect, useCallback, useMemo } from 'react';
+import { useAdapter } from '../context/adapter-context';
+import type { Feature, FeatureStatus } from 'task-orchestrator-bun/src/domain/types';
+import type { BoardFeature, FeatureBoardColumn } from '../lib/types';
+
+/**
+ * Feature-status columns for the feature-based Kanban board
+ */
+export const FEATURE_KANBAN_STATUSES = [
+  { id: 'draft', title: 'Draft', status: 'DRAFT' },
+  { id: 'planning', title: 'Planning', status: 'PLANNING' },
+  { id: 'in-development', title: 'In Development', status: 'IN_DEVELOPMENT' },
+  { id: 'testing', title: 'Testing', status: 'TESTING' },
+  { id: 'validating', title: 'Validating', status: 'VALIDATING' },
+  { id: 'pending-review', title: 'Pending Review', status: 'PENDING_REVIEW' },
+  { id: 'blocked', title: 'Blocked', status: 'BLOCKED' },
+  { id: 'on-hold', title: 'On Hold', status: 'ON_HOLD' },
+  { id: 'deployed', title: 'Deployed', status: 'DEPLOYED' },
+  { id: 'completed', title: 'Completed', status: 'COMPLETED' },
+  { id: 'archived', title: 'Archived', status: 'ARCHIVED' },
+] as const;
+
+interface UseFeatureKanbanReturn {
+  columns: FeatureBoardColumn[];
+  loading: boolean;
+  error: string | null;
+  refresh: () => void;
+  moveFeature: (featureId: string, newStatus: string) => Promise<boolean>;
+}
+
+/**
+ * Hook for managing the feature-based Kanban board.
+ *
+ * Fetches features and tasks for a project, groups features by their status
+ * into columns, and nests tasks within each feature card.
+ */
+export function useFeatureKanban(projectId: string): UseFeatureKanbanReturn {
+  const { adapter } = useAdapter();
+  const [features, setFeatures] = useState<Feature[]>([]);
+  const [tasksByFeature, setTasksByFeature] = useState<Map<string, import('task-orchestrator-bun/src/domain/types').Task[]>>(new Map());
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [refreshTrigger, setRefreshTrigger] = useState(0);
+
+  const refresh = useCallback(() => {
+    setRefreshTrigger((prev) => prev + 1);
+  }, []);
+
+  const loadData = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+
+    const [featuresResult, tasksResult] = await Promise.all([
+      adapter.getFeatures({ projectId }),
+      adapter.getTasks({ projectId }),
+    ]);
+
+    if (!featuresResult.success) {
+      setError(featuresResult.error);
+      setLoading(false);
+      return;
+    }
+
+    if (!tasksResult.success) {
+      setError(tasksResult.error);
+      setLoading(false);
+      return;
+    }
+
+    setFeatures(featuresResult.data);
+
+    // Group tasks by featureId
+    const grouped = new Map<string, import('task-orchestrator-bun/src/domain/types').Task[]>();
+    for (const task of tasksResult.data) {
+      if (task.featureId) {
+        const list = grouped.get(task.featureId) || [];
+        list.push(task);
+        grouped.set(task.featureId, list);
+      }
+    }
+    setTasksByFeature(grouped);
+    setLoading(false);
+  }, [adapter, projectId]);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData, refreshTrigger]);
+
+  const columns = useMemo<FeatureBoardColumn[]>(() => {
+    return FEATURE_KANBAN_STATUSES.map((statusDef) => {
+      const columnFeatures = features
+        .filter((f) => f.status === statusDef.status)
+        .map((f): BoardFeature => {
+          const tasks = tasksByFeature.get(f.id) || [];
+          return {
+            ...f,
+            tasks,
+            taskCounts: {
+              total: tasks.length,
+              completed: tasks.filter((t) => t.status === 'COMPLETED' || t.status === 'DEPLOYED').length,
+            },
+          };
+        });
+
+      return {
+        id: statusDef.id,
+        title: statusDef.title,
+        status: statusDef.status,
+        features: columnFeatures,
+      };
+    });
+  }, [features, tasksByFeature]);
+
+  const moveFeature = useCallback(
+    async (featureId: string, newStatus: string): Promise<boolean> => {
+      // Find feature in current data
+      const feature = features.find((f) => f.id === featureId);
+      if (!feature) {
+        refresh();
+        return false;
+      }
+
+      try {
+        const result = await adapter.setFeatureStatus(
+          featureId,
+          newStatus as FeatureStatus,
+          feature.version
+        );
+
+        if (result.success) {
+          refresh();
+          return true;
+        } else {
+          refresh();
+          return false;
+        }
+      } catch (_err) {
+        return false;
+      }
+    },
+    [adapter, features, refresh]
+  );
+
+  return {
+    columns,
+    loading,
+    error,
+    refresh,
+    moveFeature,
+  };
+}

package/src/ui/hooks/use-kanban.ts

@@ -0,0 +1,96 @@
+import { useMemo, useCallback } from 'react';
+import { useAdapter } from '../context/adapter-context';
+import type { Task } from 'task-orchestrator-bun/src/domain/types';
+import type { BoardColumn } from '../lib/types';
+import { useBoardData } from './use-data';
+
+/**
+ * Standard Kanban column definitions
+ */
+const KANBAN_STATUSES = [
+  { id: 'pending', title: 'Pending', status: 'PENDING' },
+  { id: 'in-progress', title: 'In Progress', status: 'IN_PROGRESS' },
+  { id: 'in-review', title: 'In Review', status: 'IN_REVIEW' },
+  { id: 'blocked', title: 'Blocked', status: 'BLOCKED' },
+  { id: 'completed', title: 'Completed', status: 'COMPLETED' },
+] as const;
+
+interface UseKanbanReturn {
+  columns: BoardColumn[];
+  loading: boolean;
+  error: string | null;
+  refresh: () => void;
+  moveTask: (taskId: string, newStatus: string) => Promise<boolean>;
+}
+
+/**
+ * Hook for managing Kanban board state
+ *
+ * Fetches tasks for a project and organizes them into Kanban columns by status.
+ * Provides functionality to move tasks between columns with optimistic updates.
+ *
+ * @param projectId - The project ID to fetch tasks for
+ * @returns Kanban board state and operations
+ */
+export function useKanban(projectId: string): UseKanbanReturn {
+  const { adapter } = useAdapter();
+  const { columnsByStatus, loading, error, refresh } = useBoardData(projectId);
+
+  const columns = useMemo<BoardColumn[]>(() => (
+    KANBAN_STATUSES.map((statusDef) => ({
+      id: statusDef.id,
+      title: statusDef.title,
+      status: statusDef.status,
+      tasks: (columnsByStatus.get(statusDef.status) || []).map((card) => card.task),
+    }))
+  ), [columnsByStatus]);
+
+  /**
+   * Move a task to a new status
+   *
+   * @param taskId - ID of the task to move
+   * @param newStatus - New status to assign
+   * @returns true if successful, false otherwise
+   */
+  const moveTask = useCallback(
+    async (taskId: string, newStatus: string): Promise<boolean> => {
+      // Find the task in current columns
+      let task: Task | undefined;
+      for (const column of columns) {
+        task = column.tasks.find((t) => t.id === taskId);
+        if (task) break;
+      }
+
+      if (!task) {
+        // Board may be stale; ask the caller to refresh and retry.
+        refresh();
+        return false;
+      }
+
+      try {
+        // Call adapter to update task status
+        const result = await adapter.setTaskStatus(taskId, newStatus as any, task.version);
+
+        if (result.success) {
+          // Refresh the board on success
+          refresh();
+          return true;
+        } else {
+          refresh();
+          return false;
+        }
+      } catch (_err) {
+        return false;
+      }
+    },
+    [adapter, columns, refresh]
+  );
+
+  return {
+    columns,
+    loading,
+    error,
+    refresh,
+    moveTask,
+  };
+}

package/src/ui/hooks/use-navigation.tsx

@@ -0,0 +1,94 @@
+import React, { createContext, useContext, useState, type ReactNode } from 'react';
+import { Screen, type NavigationState } from '../lib/types';
+
+/**
+ * Navigation context interface
+ */
+interface NavigationContextValue {
+  screen: Screen;
+  params: Record<string, unknown>;
+  push(screen: Screen, params?: Record<string, unknown>): void;
+  pop(): void;
+  replace(screen: Screen, params?: Record<string, unknown>): void;
+  reset(): void;
+  canGoBack: boolean;
+}
+
+/**
+ * Navigation context for TUI routing
+ */
+const NavigationContext = createContext<NavigationContextValue | undefined>(undefined);
+
+/**
+ * Provider props
+ */
+interface NavigationProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Navigation provider that manages the screen stack
+ */
+export function NavigationProvider({ children }: NavigationProviderProps) {
+  const [state, setState] = useState<NavigationState>({
+    stack: [{ screen: Screen.Dashboard, params: {} }],
+  });
+
+  const currentStackItem = state.stack[state.stack.length - 1]!;
+
+  const push = (screen: Screen, params: Record<string, unknown> = {}) => {
+    setState((prev: NavigationState) => ({
+      stack: [...prev.stack, { screen, params }],
+    }));
+  };
+
+  const pop = () => {
+    setState((prev: NavigationState) => {
+      if (prev.stack.length <= 1) {
+        return prev;
+      }
+      return {
+        stack: prev.stack.slice(0, -1),
+      };
+    });
+  };
+
+  const replace = (screen: Screen, params: Record<string, unknown> = {}) => {
+    setState((prev: NavigationState) => ({
+      stack: [...prev.stack.slice(0, -1), { screen, params }],
+    }));
+  };
+
+  const reset = () => {
+    setState({
+      stack: [{ screen: Screen.Dashboard, params: {} }],
+    });
+  };
+
+  const value: NavigationContextValue = {
+    screen: currentStackItem.screen,
+    params: currentStackItem.params,
+    push,
+    pop,
+    replace,
+    reset,
+    canGoBack: state.stack.length > 1,
+  };
+
+  return (
+    <NavigationContext.Provider value={value}>
+      {children}
+    </NavigationContext.Provider>
+  );
+}
+
+/**
+ * Hook to access navigation state and actions
+ */
+export function useNavigation(): NavigationContextValue {
+  const context = useContext(NavigationContext);
+  if (!context) {
+    throw new Error('useNavigation must be used within a NavigationProvider');
+  }
+  return context;
+}

package/src/ui/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Task Orchestrator UI - Shared Layer
+ *
+ * Platform-agnostic foundation for TUI, web, and Electron renderers.
+ */
+
+// Themes
+export { darkTheme } from './themes/dark';
+export { lightTheme } from './themes/light';
+export type { Theme, TaskCounts, StatusKey } from './themes/types';
+
+// Lib - Types
+export {
+  Screen,
+  type ScreenParams,
+  type NavigationState,
+  type Shortcut,
+  type TreeNode,
+  type FeatureWithTasks,
+  type BoardColumn,
+  type SearchResults,
+  type DependencyInfo,
+  type ProjectOverview,
+  type FeatureOverview,
+} from './lib/types';
+
+// Lib - Format utilities
+export {
+  timeAgo,
+  truncateId,
+  truncateText,
+  pluralize,
+  formatTaskCount,
+  formatCount,
+  formatStatus,
+  formatPriority,
+} from './lib/format';
+
+// Lib - Color utilities
+export {
+  getStatusColor,
+  getPriorityColor,
+  getPriorityDots,
+  getSemanticColor,
+  isActiveStatus,
+  isBlockedStatus,
+  isCompletedStatus,
+} from './lib/colors';
+
+// Adapters
+export type {
+  DataAdapter,
+  Result,
+  SearchParams,
+  FeatureSearchParams,
+  TaskSearchParams,
+} from './adapters/types';
+export { DirectAdapter } from './adapters/direct';
+
+// Context
+export { ThemeProvider, useTheme } from './context/theme-context';
+export { AdapterProvider, useAdapter } from './context/adapter-context';
+
+// Hooks
+export { NavigationProvider, useNavigation } from './hooks/use-navigation';
+export {
+  useProjects,
+  useProjectOverview,
+  useProjectTree,
+  useTask,
+  useSearch,
+} from './hooks/use-data';
+export { useDebounce } from './hooks/use-debounce';

package/src/ui/lib/colors.ts

@@ -0,0 +1,79 @@
+import type { Theme, StatusKey } from '../themes/types';
+import type { Priority } from 'task-orchestrator-bun/src/domain/types';
+
+/**
+ * Get the color for a status value
+ * Falls back to muted color if status not found
+ */
+export function getStatusColor(status: string, theme: Theme): string {
+  const color = theme.colors.status[status as StatusKey];
+  return color ?? theme.colors.muted;
+}
+
+/**
+ * Get the color for a priority value
+ */
+export function getPriorityColor(priority: Priority, theme: Theme): string {
+  return theme.colors.priority[priority] ?? theme.colors.muted;
+}
+
+/**
+ * Get priority dots visual indicator
+ * HIGH: ●●● (3 filled)
+ * MEDIUM: ●●○ (2 filled)
+ * LOW: ●○○ (1 filled)
+ */
+export function getPriorityDots(priority: Priority): string {
+  switch (priority) {
+    case 'HIGH':
+      return '●●●';
+    case 'MEDIUM':
+      return '●●○';
+    case 'LOW':
+      return '●○○';
+    default:
+      return '○○○';
+  }
+}
+
+/**
+ * Get a semantic color from theme
+ */
+export function getSemanticColor(
+  type: 'success' | 'warning' | 'error' | 'info',
+  theme: Theme
+): string {
+  return theme.colors[type];
+}
+
+/**
+ * Determine if a status represents an "active" state
+ */
+export function isActiveStatus(status: string): boolean {
+  const activeStatuses = [
+    'IN_PROGRESS',
+    'IN_DEVELOPMENT',
+    'IN_REVIEW',
+    'TESTING',
+    'VALIDATING',
+    'INVESTIGATING',
+    'READY_FOR_QA',
+  ];
+  return activeStatuses.includes(status);
+}
+
+/**
+ * Determine if a status represents a "blocked" state
+ */
+export function isBlockedStatus(status: string): boolean {
+  const blockedStatuses = ['BLOCKED', 'ON_HOLD', 'CHANGES_REQUESTED'];
+  return blockedStatuses.includes(status);
+}
+
+/**
+ * Determine if a status represents a "completed" state
+ */
+export function isCompletedStatus(status: string): boolean {
+  const completedStatuses = ['COMPLETED', 'DEPLOYED', 'ARCHIVED', 'CANCELLED'];
+  return completedStatuses.includes(status);
+}

package/src/ui/lib/format.ts

@@ -0,0 +1,114 @@
+/**
+ * Format a date as a relative time string
+ * @example timeAgo(new Date(Date.now() - 3600000)) // "1h ago"
+ */
+export function timeAgo(date: Date): string {
+  const now = new Date();
+  const seconds = Math.floor((now.getTime() - date.getTime()) / 1000);
+
+  if (seconds < 60) {
+    return 'just now';
+  }
+
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) {
+    return `${minutes}m ago`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) {
+    return `${hours}h ago`;
+  }
+
+  const days = Math.floor(hours / 24);
+  if (days < 7) {
+    return `${days}d ago`;
+  }
+
+  const weeks = Math.floor(days / 7);
+  if (weeks < 4) {
+    return `${weeks}w ago`;
+  }
+
+  const months = Math.floor(days / 30);
+  if (months < 12) {
+    return `${months}mo ago`;
+  }
+
+  const years = Math.floor(days / 365);
+  return `${years}y ago`;
+}
+
+/**
+ * Truncate a UUID or ID for display
+ * @example truncateId('550e8400-e29b-41d4-a716-446655440000') // "550e84..."
+ */
+export function truncateId(id: string, length: number = 6): string {
+  if (id.length <= length + 3) {
+    return id;
+  }
+  return `${id.slice(0, length)}...`;
+}
+
+/**
+ * Truncate text with ellipsis
+ * @example truncateText('Long text here', 8) // "Long t..."
+ */
+export function truncateText(text: string, maxLength: number): string {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  if (maxLength <= 3) {
+    return text.slice(0, maxLength);
+  }
+  return `${text.slice(0, maxLength - 3)}...`;
+}
+
+/**
+ * Pluralize a word based on count
+ * @example pluralize(1, 'task') // "task"
+ * @example pluralize(5, 'task') // "tasks"
+ */
+export function pluralize(count: number, singular: string, plural?: string): string {
+  if (count === 1) {
+    return singular;
+  }
+  return plural ?? `${singular}s`;
+}
+
+/**
+ * Format task counts for display
+ * @example formatTaskCount({ completed: 5, total: 12 }) // "5/12 tasks"
+ */
+export function formatTaskCount(counts: { total: number; byStatus: Record<string, number> }): string {
+  const completed = counts.byStatus['COMPLETED'] ?? 0;
+  return `${completed}/${counts.total} ${pluralize(counts.total, 'task')}`;
+}
+
+/**
+ * Format a count with label
+ * @example formatCount(5, 'task') // "5 tasks"
+ */
+export function formatCount(count: number, singular: string, plural?: string): string {
+  return `${count} ${pluralize(count, singular, plural)}`;
+}
+
+/**
+ * Format a status string for display (convert to title case)
+ * @example formatStatus('IN_PROGRESS') // "In Progress"
+ */
+export function formatStatus(status: string): string {
+  return status
+    .toLowerCase()
+    .split('_')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * Format a priority for display
+ * @example formatPriority('HIGH') // "High"
+ */
+export function formatPriority(priority: string): string {
+  return priority.charAt(0).toUpperCase() + priority.slice(1).toLowerCase();
+}