beads-kanban-ui 0.1.0

package/src/hooks/use-epics.ts

@@ -0,0 +1,173 @@
+"use client";
+
+/**
+ * Hook for managing epic-specific state and filtering.
+ *
+ * Derived from useBeads, provides:
+ * - Top-level beads only (no child tasks)
+ * - Separated epics and standalone tasks
+ * - Epic progress computation
+ * - Expansion state management
+ */
+
+import { useMemo, useState, useCallback } from "react";
+import type { Bead, Epic, EpicProgress } from "@/types";
+
+/**
+ * Result type for the useEpics hook
+ */
+export interface UseEpicsResult {
+  /** Top-level beads only (no children) */
+  topLevelBeads: Bead[];
+  /** Epics with computed progress */
+  epics: Epic[];
+  /** Standalone tasks (not epics, not children) */
+  standaloneTasks: Bead[];
+  /** Map of epic ID to expansion state */
+  expandedEpics: Set<string>;
+  /** Toggle epic expansion */
+  toggleEpic: (epicId: string) => void;
+  /** Expand all epics */
+  expandAll: () => void;
+  /** Collapse all epics */
+  collapseAll: () => void;
+  /** Check if epic is expanded */
+  isExpanded: (epicId: string) => boolean;
+}
+
+/**
+ * Compute progress metrics for an epic based on its children
+ */
+function computeEpicProgress(children: Bead[]): EpicProgress {
+  const total = children.length;
+  const completed = children.filter(c => c.status === 'closed').length;
+  const inProgress = children.filter(c => c.status === 'in_progress').length;
+  // Blocked = has unresolved dependencies
+  const blocked = children.filter(c => (c.deps?.length ?? 0) > 0).length;
+
+  return { total, completed, inProgress, blocked };
+}
+
+/**
+ * Type guard to check if a bead is an epic
+ */
+function isEpic(bead: Bead): bead is Epic {
+  return bead.issue_type === 'epic';
+}
+
+/**
+ * Hook to manage epic state and filtering
+ *
+ * @param beads - All beads from the project
+ * @returns Object with top-level beads, epics, tasks, and expansion controls
+ *
+ * @example
+ * ```tsx
+ * function KanbanBoard() {
+ *   const { beads } = useBeads(projectPath);
+ *   const { topLevelBeads, epics, standaloneTasks, isExpanded, toggleEpic } = useEpics(beads);
+ *
+ *   return (
+ *     <div>
+ *       {topLevelBeads.map(bead =>
+ *         isEpic(bead)
+ *           ? <EpicCard epic={bead} isExpanded={isExpanded(bead.id)} />
+ *           : <BeadCard bead={bead} />
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useEpics(beads: Bead[]): UseEpicsResult {
+  // Track expanded epic IDs
+  const [expandedEpics, setExpandedEpics] = useState<Set<string>>(new Set());
+
+  /**
+   * Filter to only top-level beads (no parent_id)
+   * This prevents child tasks from appearing in columns
+   */
+  const topLevelBeads = useMemo(() => {
+    return beads.filter(b => !b.parent_id);
+  }, [beads]);
+
+  /**
+   * Separate epics from standalone tasks and compute progress
+   */
+  const { epics, standaloneTasks } = useMemo(() => {
+    const epicsList: Epic[] = [];
+    const tasksList: Bead[] = [];
+
+    for (const bead of topLevelBeads) {
+      if (isEpic(bead)) {
+        // Resolve children from all beads (including child tasks)
+        const children = (bead.children || [])
+          .map(childId => beads.find(b => b.id === childId))
+          .filter((b): b is Bead => b !== undefined);
+
+        // Compute progress
+        const progress = computeEpicProgress(children);
+
+        epicsList.push({
+          ...bead,
+          progress
+        });
+      } else {
+        tasksList.push(bead);
+      }
+    }
+
+    return {
+      epics: epicsList,
+      standaloneTasks: tasksList
+    };
+  }, [topLevelBeads, beads]);
+
+  /**
+   * Toggle epic expansion state
+   * Uses functional update to avoid stale closure issues
+   */
+  const toggleEpic = useCallback((epicId: string) => {
+    setExpandedEpics(current => {
+      const next = new Set(current);
+      if (next.has(epicId)) {
+        next.delete(epicId);
+      } else {
+        next.add(epicId);
+      }
+      return next;
+    });
+  }, []);
+
+  /**
+   * Expand all epics
+   */
+  const expandAll = useCallback(() => {
+    setExpandedEpics(new Set(epics.map(e => e.id)));
+  }, [epics]);
+
+  /**
+   * Collapse all epics
+   */
+  const collapseAll = useCallback(() => {
+    setExpandedEpics(new Set());
+  }, []);
+
+  /**
+   * Check if an epic is expanded
+   */
+  const isExpanded = useCallback((epicId: string) => {
+    return expandedEpics.has(epicId);
+  }, [expandedEpics]);
+
+  return {
+    topLevelBeads,
+    epics,
+    standaloneTasks,
+    expandedEpics,
+    toggleEpic,
+    expandAll,
+    collapseAll,
+    isExpanded
+  };
+}

package/src/hooks/use-file-watcher.ts

@@ -0,0 +1,111 @@
+"use client";
+
+/**
+ * Hook for watching file changes via SSE (Server-Sent Events).
+ *
+ * Uses the backend API to watch for file changes and emit events
+ * to the frontend. Includes debouncing to prevent rapid-fire callbacks.
+ */
+
+import { useEffect, useState, useRef, useCallback } from "react";
+import * as api from "@/lib/api";
+
+/** Return type for the useFileWatcher hook. */
+interface UseFileWatcherResult {
+  /** Whether the file is currently being watched. */
+  isWatching: boolean;
+  /** Any error that occurred while setting up or running the watcher. */
+  error: Error | null;
+}
+
+/**
+ * Hook to watch a project's beads file for changes and trigger a callback when it changes.
+ *
+ * @param projectPath - The absolute path to the project root directory (not the issues.jsonl file).
+ *                      The backend API will append .beads/issues.jsonl to this path.
+ * @param onFileChange - Callback function to run when the file changes.
+ * @param debounceMs - Debounce interval in milliseconds (default: 100).
+ * @returns Object containing isWatching status and any error.
+ *
+ * @example
+ * ```tsx
+ * const { isWatching, error } = useFileWatcher(
+ *   "/path/to/project",
+ *   () => {
+ *     refetchIssues();
+ *   },
+ *   100
+ * );
+ * ```
+ */
+export function useFileWatcher(
+  projectPath: string,
+  onFileChange: () => void,
+  debounceMs: number = 100
+): UseFileWatcherResult {
+  const [isWatching, setIsWatching] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Use refs to store the callback and debounce timer to avoid effect re-runs
+  const callbackRef = useRef(onFileChange);
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Keep callback ref up to date
+  useEffect(() => {
+    callbackRef.current = onFileChange;
+  }, [onFileChange]);
+
+  // Debounced callback handler
+  const handleFileChange = useCallback(() => {
+    // Clear any existing debounce timer
+    if (debounceTimerRef.current) {
+      clearTimeout(debounceTimerRef.current);
+    }
+
+    // Set new debounce timer
+    debounceTimerRef.current = setTimeout(() => {
+      callbackRef.current();
+      debounceTimerRef.current = null;
+    }, debounceMs);
+  }, [debounceMs]);
+
+  useEffect(() => {
+    // Don't set up watcher if no project path provided
+    if (!projectPath) {
+      return;
+    }
+
+    let cleanup: (() => void) | null = null;
+
+    try {
+      // Set up the SSE watcher via API
+      cleanup = api.watch.beads(projectPath, () => {
+        handleFileChange();
+      });
+
+      setIsWatching(true);
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setIsWatching(false);
+    }
+
+    // Cleanup function
+    return () => {
+      // Clear any pending debounce timer
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+        debounceTimerRef.current = null;
+      }
+
+      // Close SSE connection
+      if (cleanup) {
+        cleanup();
+      }
+
+      setIsWatching(false);
+    };
+  }, [projectPath, handleFileChange]);
+
+  return { isWatching, error };
+}

package/src/hooks/use-keyboard-navigation.ts

@@ -0,0 +1,282 @@
+"use client";
+
+import { useCallback, useEffect, useState, RefObject } from "react";
+import type { Bead, BeadStatus } from "@/types";
+
+/**
+ * Column order for navigation
+ */
+const COLUMN_ORDER: BeadStatus[] = ["open", "in_progress", "inreview", "closed"];
+
+/**
+ * Column shortcuts for 'g' prefix navigation
+ */
+const COLUMN_SHORTCUTS: Record<string, BeadStatus> = {
+  o: "open",
+  p: "in_progress",
+  r: "inreview",
+  c: "closed",
+};
+
+export interface KeyboardNavigationOptions {
+  beads: Bead[];
+  beadsByStatus: Record<BeadStatus, Bead[]>;
+  selectedId: string | null;
+  onSelect: (bead: Bead) => void;
+  onOpen: (bead: Bead) => void;
+  onClose: () => void;
+  searchInputRef: RefObject<HTMLInputElement | null>;
+  isDetailOpen: boolean;
+}
+
+export interface KeyboardNavigationResult {
+  selectedId: string | null;
+  selectedColumnStatus: BeadStatus | null;
+  setSelectedId: (id: string | null) => void;
+  setSelectedColumnStatus: (status: BeadStatus | null) => void;
+  scrollToSelected: () => void;
+}
+
+/**
+ * Hook for keyboard navigation in the Kanban board
+ *
+ * Shortcuts:
+ * - j or ArrowDown: Move selection down
+ * - k or ArrowUp: Move selection up
+ * - Enter: Open selected bead detail
+ * - Escape: Close detail sheet / clear selection
+ * - /: Focus search input
+ * - g then o: Go to Open column
+ * - g then p: Go to In Progress column
+ * - g then r: Go to In Review column
+ * - g then d: Go to Done column
+ */
+export function useKeyboardNavigation({
+  beads,
+  beadsByStatus,
+  selectedId,
+  onSelect,
+  onOpen,
+  onClose,
+  searchInputRef,
+  isDetailOpen,
+}: KeyboardNavigationOptions): KeyboardNavigationResult {
+  const [internalSelectedId, setInternalSelectedId] = useState<string | null>(selectedId);
+  const [selectedColumnStatus, setSelectedColumnStatus] = useState<BeadStatus | null>(null);
+  const [awaitingColumnKey, setAwaitingColumnKey] = useState(false);
+
+  // Sync internal state with external selectedId
+  useEffect(() => {
+    setInternalSelectedId(selectedId);
+  }, [selectedId]);
+
+  /**
+   * Get the current column's beads for the selected bead
+   */
+  const getCurrentColumnBeads = useCallback((): Bead[] => {
+    if (selectedColumnStatus) {
+      return beadsByStatus[selectedColumnStatus] || [];
+    }
+    if (!internalSelectedId) {
+      // Default to first non-empty column
+      for (const status of COLUMN_ORDER) {
+        if (beadsByStatus[status]?.length > 0) {
+          return beadsByStatus[status];
+        }
+      }
+      return [];
+    }
+    // Find which column contains the selected bead
+    for (const status of COLUMN_ORDER) {
+      const columnBeads = beadsByStatus[status] || [];
+      if (columnBeads.some((b) => b.id === internalSelectedId)) {
+        return columnBeads;
+      }
+    }
+    return beads;
+  }, [internalSelectedId, selectedColumnStatus, beadsByStatus, beads]);
+
+  /**
+   * Get current index of selected bead in its column
+   */
+  const getCurrentIndex = useCallback((): number => {
+    const columnBeads = getCurrentColumnBeads();
+    if (!internalSelectedId) return -1;
+    return columnBeads.findIndex((b) => b.id === internalSelectedId);
+  }, [internalSelectedId, getCurrentColumnBeads]);
+
+  /**
+   * Move selection in a direction (up or down)
+   */
+  const moveSelection = useCallback(
+    (direction: "up" | "down") => {
+      const columnBeads = getCurrentColumnBeads();
+      if (columnBeads.length === 0) return;
+
+      const currentIndex = getCurrentIndex();
+      let newIndex: number;
+
+      if (currentIndex === -1) {
+        // No selection, select first or last based on direction
+        newIndex = direction === "down" ? 0 : columnBeads.length - 1;
+      } else {
+        newIndex =
+          direction === "down"
+            ? Math.min(currentIndex + 1, columnBeads.length - 1)
+            : Math.max(currentIndex - 1, 0);
+      }
+
+      const newBead = columnBeads[newIndex];
+      if (newBead) {
+        setInternalSelectedId(newBead.id);
+        onSelect(newBead);
+        // Update column status based on selected bead
+        for (const status of COLUMN_ORDER) {
+          if (beadsByStatus[status]?.some((b) => b.id === newBead.id)) {
+            setSelectedColumnStatus(status);
+            break;
+          }
+        }
+      }
+    },
+    [getCurrentColumnBeads, getCurrentIndex, onSelect, beadsByStatus]
+  );
+
+  /**
+   * Jump to a specific column
+   */
+  const jumpToColumn = useCallback(
+    (status: BeadStatus) => {
+      const columnBeads = beadsByStatus[status] || [];
+      setSelectedColumnStatus(status);
+      if (columnBeads.length > 0) {
+        const firstBead = columnBeads[0];
+        setInternalSelectedId(firstBead.id);
+        onSelect(firstBead);
+      } else {
+        setInternalSelectedId(null);
+      }
+    },
+    [beadsByStatus, onSelect]
+  );
+
+  /**
+   * Scroll the selected bead into view
+   */
+  const scrollToSelected = useCallback(() => {
+    if (!internalSelectedId) return;
+    const element = document.querySelector(`[data-bead-id="${internalSelectedId}"]`);
+    if (element) {
+      element.scrollIntoView({ behavior: "smooth", block: "nearest" });
+    }
+  }, [internalSelectedId]);
+
+  // Scroll into view when selection changes
+  useEffect(() => {
+    scrollToSelected();
+  }, [internalSelectedId, scrollToSelected]);
+
+  /**
+   * Handle keyboard events
+   */
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      // Don't handle if focused on an input (except for Escape)
+      const target = event.target as HTMLElement;
+      const isInputFocused =
+        target.tagName === "INPUT" ||
+        target.tagName === "TEXTAREA" ||
+        target.isContentEditable;
+
+      // Always handle Escape
+      if (event.key === "Escape") {
+        event.preventDefault();
+        if (isDetailOpen) {
+          onClose();
+        } else if (isInputFocused) {
+          target.blur();
+        } else if (internalSelectedId) {
+          setInternalSelectedId(null);
+          setSelectedColumnStatus(null);
+        }
+        setAwaitingColumnKey(false);
+        return;
+      }
+
+      // Skip other shortcuts if in input
+      if (isInputFocused) return;
+
+      // Handle 'g' prefix for column navigation
+      if (awaitingColumnKey) {
+        setAwaitingColumnKey(false);
+        const targetStatus = COLUMN_SHORTCUTS[event.key.toLowerCase()];
+        if (targetStatus) {
+          event.preventDefault();
+          jumpToColumn(targetStatus);
+        }
+        return;
+      }
+
+      switch (event.key) {
+        case "j":
+        case "ArrowDown":
+          event.preventDefault();
+          if (!isDetailOpen) {
+            moveSelection("down");
+          }
+          break;
+
+        case "k":
+        case "ArrowUp":
+          event.preventDefault();
+          if (!isDetailOpen) {
+            moveSelection("up");
+          }
+          break;
+
+        case "Enter":
+          event.preventDefault();
+          if (internalSelectedId && !isDetailOpen) {
+            const selectedBead = beads.find((b) => b.id === internalSelectedId);
+            if (selectedBead) {
+              onOpen(selectedBead);
+            }
+          }
+          break;
+
+        case "/":
+          event.preventDefault();
+          searchInputRef.current?.focus();
+          break;
+
+        case "g":
+          event.preventDefault();
+          setAwaitingColumnKey(true);
+          // Reset after timeout if no follow-up key
+          setTimeout(() => setAwaitingColumnKey(false), 1000);
+          break;
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [
+    beads,
+    internalSelectedId,
+    isDetailOpen,
+    awaitingColumnKey,
+    moveSelection,
+    jumpToColumn,
+    onOpen,
+    onClose,
+    searchInputRef,
+  ]);
+
+  return {
+    selectedId: internalSelectedId,
+    selectedColumnStatus,
+    setSelectedId: setInternalSelectedId,
+    setSelectedColumnStatus,
+    scrollToSelected,
+  };
+}

package/src/hooks/use-project.ts

@@ -0,0 +1,61 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { getProjectWithTags, type Project, type Tag } from "@/lib/db";
+
+export interface ProjectWithTags extends Project {
+  tags: Tag[];
+}
+
+interface UseProjectResult {
+  project: ProjectWithTags | null;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+/**
+ * Hook to fetch a single project by ID from SQLite
+ *
+ * @param projectId - The ID of the project to fetch
+ * @returns Object containing project data, loading state, error, and refetch function
+ */
+export function useProject(projectId: string | null): UseProjectResult {
+  const [project, setProject] = useState<ProjectWithTags | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchProject = useCallback(async () => {
+    if (!projectId) {
+      setProject(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+      const data = await getProjectWithTags(projectId);
+      setProject(data);
+    } catch (err) {
+      setError(
+        err instanceof Error ? err : new Error("Failed to fetch project")
+      );
+      setProject(null);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [projectId]);
+
+  useEffect(() => {
+    fetchProject();
+  }, [fetchProject]);
+
+  return {
+    project,
+    isLoading,
+    error,
+    refetch: fetchProject,
+  };
+}