beads-kanban-ui 0.1.0 → 0.1.1

package/src/hooks/use-epics.ts

@@ -1,173 +0,0 @@
-"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

@@ -1,111 +0,0 @@
-"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

@@ -1,282 +0,0 @@
-"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

@@ -1,61 +0,0 @@
-"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,
-  };
-}