beads-kanban-ui 0.1.0 → 0.1.1

package/src/hooks/use-bead-filters.ts

@@ -1,261 +0,0 @@
-"use client";
-
-/**
- * Hook for filtering beads with debounced search and multi-criteria filtering.
- *
- * Provides search (with 300ms debounce), status, priority, and owner filtering
- * with a clean API for the kanban board.
- */
-
-import { useState, useMemo, useCallback, useEffect } from "react";
-import type { Bead, BeadStatus } from "@/types";
-
-/**
- * Sort field options
- */
-export type SortField = "ticket_number" | "created_at";
-
-/**
- * Sort direction options
- */
-export type SortDirection = "asc" | "desc";
-
-/**
- * Filter state for beads
- */
-export interface BeadFilters {
-  /** Search query for title and description (case-insensitive) */
-  search: string;
-  /** Status filter - empty array means all statuses */
-  statuses: BeadStatus[];
-  /** Priority filter - empty array means all priorities (0-4) */
-  priorities: number[];
-  /** Owner/agent filter - empty array means all owners */
-  owners: string[];
-  /** Sort field */
-  sortField: SortField;
-  /** Sort direction */
-  sortDirection: SortDirection;
-  /** Filter to items updated (worked on) today */
-  todayOnly: boolean;
-}
-
-/**
- * Result type for the useBeadFilters hook
- */
-export interface UseBeadFiltersResult {
-  /** Current filter state */
-  filters: BeadFilters;
-  /** Update filters (partial update supported) */
-  setFilters: (filters: Partial<BeadFilters>) => void;
-  /** Beads after applying all filters */
-  filteredBeads: Bead[];
-  /** Reset all filters to default */
-  clearFilters: () => void;
-  /** Whether any filters are active */
-  hasActiveFilters: boolean;
-  /** Count of active filter categories */
-  activeFilterCount: number;
-  /** Unique owners extracted from beads */
-  availableOwners: string[];
-  /** Debounced search value (for display) */
-  debouncedSearch: string;
-}
-
-/**
- * Default/empty filter state
- */
-const DEFAULT_FILTERS: BeadFilters = {
-  search: "",
-  statuses: [],
-  priorities: [],
-  owners: [],
-  sortField: "created_at",
-  sortDirection: "desc",
-  todayOnly: false,
-};
-
-/**
- * Hook to filter beads with debounced search and multi-criteria filtering.
- *
- * @param beads - Array of beads to filter
- * @param debounceMs - Debounce delay for search input (default 300ms)
- * @returns Filter state, setters, and filtered beads
- *
- * @example
- * ```tsx
- * function KanbanBoard({ beads }: { beads: Bead[] }) {
- *   const {
- *     filters,
- *     setFilters,
- *     filteredBeads,
- *     clearFilters,
- *     hasActiveFilters,
- *     activeFilterCount,
- *   } = useBeadFilters(beads);
- *
- *   return (
- *     <>
- *       <input
- *         value={filters.search}
- *         onChange={(e) => setFilters({ search: e.target.value })}
- *       />
- *       {hasActiveFilters && (
- *         <button onClick={clearFilters}>
- *           Clear ({activeFilterCount})
- *         </button>
- *       )}
- *       <BeadList beads={filteredBeads} />
- *     </>
- *   );
- * }
- * ```
- */
-export function useBeadFilters(
-  beads: Bead[],
-  ticketNumbers: Map<string, number>,
-  debounceMs: number = 300
-): UseBeadFiltersResult {
-  // Filter state
-  const [filters, setFiltersState] = useState<BeadFilters>(DEFAULT_FILTERS);
-
-  // Debounced search value
-  const [debouncedSearch, setDebouncedSearch] = useState("");
-
-  // Debounce the search input
-  useEffect(() => {
-    const timer = setTimeout(() => {
-      setDebouncedSearch(filters.search);
-    }, debounceMs);
-
-    return () => clearTimeout(timer);
-  }, [filters.search, debounceMs]);
-
-  /**
-   * Update filters with partial state
-   */
-  const setFilters = useCallback((partialFilters: Partial<BeadFilters>) => {
-    setFiltersState((prev) => ({
-      ...prev,
-      ...partialFilters,
-    }));
-  }, []);
-
-  /**
-   * Reset all filters to defaults
-   */
-  const clearFilters = useCallback(() => {
-    setFiltersState(DEFAULT_FILTERS);
-    setDebouncedSearch("");
-  }, []);
-
-  /**
-   * Extract unique owners from all beads
-   */
-  const availableOwners = useMemo(() => {
-    const owners = new Set<string>();
-    beads.forEach((bead) => {
-      if (bead.owner) {
-        owners.add(bead.owner);
-      }
-    });
-    return Array.from(owners).sort();
-  }, [beads]);
-
-  /**
-   * Apply all filters to beads and sort
-   */
-  const filteredBeads = useMemo(() => {
-    const { sortField, sortDirection } = filters;
-
-    // Filter beads
-    const filtered = beads.filter((bead) => {
-      // Search filter (uses debounced value for performance)
-      if (debouncedSearch) {
-        const searchLower = debouncedSearch.toLowerCase();
-        const matchesSearch =
-          bead.title.toLowerCase().includes(searchLower) ||
-          (bead.description &&
-            bead.description.toLowerCase().includes(searchLower));
-        if (!matchesSearch) return false;
-      }
-
-      // Status filter
-      if (filters.statuses.length > 0) {
-        if (!filters.statuses.includes(bead.status)) return false;
-      }
-
-      // Priority filter
-      if (filters.priorities.length > 0) {
-        if (!filters.priorities.includes(bead.priority)) return false;
-      }
-
-      // Owner filter
-      if (filters.owners.length > 0) {
-        if (!filters.owners.includes(bead.owner)) return false;
-      }
-
-      // Today filter - items updated (worked on) today, regardless of status
-      if (filters.todayOnly) {
-        const today = new Date().toISOString().split("T")[0];
-        const updatedToday = bead.updated_at.startsWith(today);
-        if (!updatedToday) return false;
-      }
-
-      return true;
-    });
-
-    // Sort the filtered results (use toSorted for immutability)
-    const sorted = filtered.toSorted((a, b) => {
-      if (sortField === "ticket_number") {
-        const aNum = ticketNumbers.get(a.id) ?? 0;
-        const bNum = ticketNumbers.get(b.id) ?? 0;
-        return sortDirection === "asc" ? aNum - bNum : bNum - aNum;
-      }
-      // created_at sort
-      const aDate = new Date(a.created_at).getTime();
-      const bDate = new Date(b.created_at).getTime();
-      return sortDirection === "asc" ? aDate - bDate : bDate - aDate;
-    });
-
-    return sorted;
-  }, [beads, debouncedSearch, filters, ticketNumbers]);
-
-  /**
-   * Check if any filters are active
-   */
-  const hasActiveFilters = useMemo(() => {
-    return (
-      filters.search !== "" ||
-      filters.statuses.length > 0 ||
-      filters.priorities.length > 0 ||
-      filters.owners.length > 0 ||
-      filters.todayOnly ||
-      filters.sortField !== DEFAULT_FILTERS.sortField ||
-      filters.sortDirection !== DEFAULT_FILTERS.sortDirection
-    );
-  }, [filters]);
-
-  /**
-   * Count active filter categories (for badge)
-   */
-  const activeFilterCount = useMemo(() => {
-    let count = 0;
-    if (filters.statuses.length > 0) count++;
-    if (filters.priorities.length > 0) count++;
-    if (filters.owners.length > 0) count++;
-    if (filters.todayOnly) count++;
-    return count;
-  }, [filters]);
-
-  return {
-    filters,
-    setFilters,
-    filteredBeads,
-    clearFilters,
-    hasActiveFilters,
-    activeFilterCount,
-    availableOwners,
-    debouncedSearch,
-  };
-}

package/src/hooks/use-beads.ts

@@ -1,162 +0,0 @@
-"use client";
-
-/**
- * Hook for loading and managing beads with real-time file watching.
- *
- * Combines the beads parser with file watcher to provide automatic
- * updates when the issues.jsonl file changes.
- */
-
-import { useState, useEffect, useCallback, useRef } from "react";
-import type { Bead, BeadStatus } from "@/types";
-import {
-  loadProjectBeads,
-  groupBeadsByStatus,
-  assignTicketNumbers,
-} from "@/lib/beads-parser";
-import { useFileWatcher } from "@/hooks/use-file-watcher";
-
-/**
- * Result type for the useBeads hook
- */
-export interface UseBeadsResult {
-  /** Array of all beads from the project */
-  beads: Bead[];
-  /** Beads grouped by status for kanban columns */
-  beadsByStatus: Record<BeadStatus, Bead[]>;
-  /** Map of bead ID to sequential ticket number (1-indexed by creation order) */
-  ticketNumbers: Map<string, number>;
-  /** Whether beads are currently being loaded */
-  isLoading: boolean;
-  /** Any error that occurred during loading */
-  error: Error | null;
-  /** Manually refresh beads from the file */
-  refresh: () => Promise<void>;
-}
-
-/**
- * Empty grouped beads object for initial state
- */
-const EMPTY_GROUPED: Record<BeadStatus, Bead[]> = {
-  open: [],
-  in_progress: [],
-  inreview: [],
-  closed: [],
-};
-
-/**
- * Hook to load and watch beads from a project directory.
- *
- * Automatically refreshes when the issues.jsonl file changes.
- *
- * @param projectPath - The absolute path to the project root
- * @returns Object containing beads, grouped beads, loading state, error, and refresh function
- *
- * @example
- * ```tsx
- * function KanbanBoard({ projectPath }: { projectPath: string }) {
- *   const { beadsByStatus, isLoading, error, refresh } = useBeads(projectPath);
- *
- *   if (isLoading) return <Loading />;
- *   if (error) return <Error message={error.message} />;
- *
- *   return (
- *     <div>
- *       <Column title="Open" beads={beadsByStatus.open} />
- *       <Column title="In Progress" beads={beadsByStatus.in_progress} />
- *       <Column title="In Review" beads={beadsByStatus.inreview} />
- *       <Column title="Closed" beads={beadsByStatus.closed} />
- *     </div>
- *   );
- * }
- * ```
- */
-export function useBeads(projectPath: string): UseBeadsResult {
-  const [beads, setBeads] = useState<Bead[]>([]);
-  const [beadsByStatus, setBeadsByStatus] =
-    useState<Record<BeadStatus, Bead[]>>(EMPTY_GROUPED);
-  const [ticketNumbers, setTicketNumbers] = useState<Map<string, number>>(
-    new Map()
-  );
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  // Track if initial load has completed
-  const hasLoadedRef = useRef(false);
-
-  /**
-   * Load beads from the project directory
-   */
-  const loadBeads = useCallback(async () => {
-    if (!projectPath) {
-      setBeads([]);
-      setBeadsByStatus(EMPTY_GROUPED);
-      setTicketNumbers(new Map());
-      setIsLoading(false);
-      return;
-    }
-
-    // Only show loading on initial load, not on refreshes
-    if (!hasLoadedRef.current) {
-      setIsLoading(true);
-    }
-
-    try {
-      const loadedBeads = await loadProjectBeads(projectPath);
-      const grouped = groupBeadsByStatus(loadedBeads);
-      const tickets = assignTicketNumbers(loadedBeads);
-
-      setBeads(loadedBeads);
-      setBeadsByStatus(grouped);
-      setTicketNumbers(tickets);
-      setError(null);
-      hasLoadedRef.current = true;
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      setError(error);
-      console.error("Failed to load beads:", error);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [projectPath]);
-
-  /**
-   * Public refresh function for manual reload
-   */
-  const refresh = useCallback(async () => {
-    await loadBeads();
-  }, [loadBeads]);
-
-  // Initial load when project path changes
-  useEffect(() => {
-    hasLoadedRef.current = false;
-    loadBeads();
-  }, [loadBeads]);
-
-  // Set up file watcher for real-time updates
-  // Note: useFileWatcher expects the project root path, not the full issues.jsonl path,
-  // because the backend watch API appends .beads/issues.jsonl to the provided path
-  const { error: watchError } = useFileWatcher(
-    projectPath,
-    loadBeads,
-    100 // 100ms debounce as per spec
-  );
-
-  // Combine any watch error with load error
-  useEffect(() => {
-    if (watchError && !error) {
-      // Only log watch errors, don't surface them as main error
-      // since the app can still function without file watching
-      console.warn("File watcher error:", watchError);
-    }
-  }, [watchError, error]);
-
-  return {
-    beads,
-    beadsByStatus,
-    ticketNumbers,
-    isLoading,
-    error,
-    refresh,
-  };
-}

package/src/hooks/use-branch-statuses.ts

@@ -1,161 +0,0 @@
-/**
- * Hook for fetching branch statuses for multiple beads
- *
- * Efficiently fetches branch status (exists, ahead, behind) for all beads
- * in a project and keeps the data updated.
- */
-
-import { useState, useEffect, useCallback, useRef } from "react";
-import { getBatchBranchStatus, type BranchStatus } from "@/lib/git";
-
-/**
- * Result type for the useBranchStatuses hook
- */
-export interface UseBranchStatusesResult {
-  /** Map of bead ID to branch status */
-  statuses: Record<string, BranchStatus>;
-  /** Whether statuses are currently being loaded */
-  isLoading: boolean;
-  /** Any error that occurred during loading */
-  error: Error | null;
-  /** Manually refresh branch statuses */
-  refresh: () => Promise<void>;
-}
-
-/**
- * Convert bead ID to expected branch name format
- *
- * @param beadId - The bead ID (e.g., "BD-001" or "project-abc123")
- * @returns The expected branch name (e.g., "bd-BD-001")
- */
-function beadIdToBranchName(beadId: string): string {
-  // If already has bd- prefix, use as-is (lowercase)
-  if (beadId.toLowerCase().startsWith("bd-")) {
-    return `bd-${beadId}`;
-  }
-  // Otherwise prefix with bd-
-  return `bd-${beadId}`;
-}
-
-/**
- * Hook to fetch and track branch statuses for beads
- *
- * @param projectPath - Absolute path to the project git repository
- * @param beadIds - Array of bead IDs to check branch status for
- * @returns Object containing statuses map, loading state, error, and refresh function
- *
- * @example
- * ```tsx
- * function KanbanBoard({ projectPath, beads }) {
- *   const beadIds = beads.map(b => b.id);
- *   const { statuses, isLoading } = useBranchStatuses(projectPath, beadIds);
- *
- *   return beads.map(bead => (
- *     <BeadCard
- *       key={bead.id}
- *       bead={bead}
- *       branchStatus={statuses[bead.id]}
- *     />
- *   ));
- * }
- * ```
- */
-export function useBranchStatuses(
-  projectPath: string,
-  beadIds: string[]
-): UseBranchStatusesResult {
-  const [statuses, setStatuses] = useState<Record<string, BranchStatus>>({});
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  // Track if initial load has completed
-  const hasLoadedRef = useRef(false);
-
-  // Store previous bead IDs to detect changes
-  const prevBeadIdsRef = useRef<string[]>([]);
-
-  /**
-   * Load branch statuses for all beads
-   */
-  const loadStatuses = useCallback(async () => {
-    if (!projectPath || beadIds.length === 0) {
-      setStatuses({});
-      setIsLoading(false);
-      return;
-    }
-
-    // Only show loading on initial load
-    if (!hasLoadedRef.current) {
-      setIsLoading(true);
-    }
-
-    try {
-      // Convert bead IDs to branch names
-      const branchNames = beadIds.map(beadIdToBranchName);
-
-      // Fetch all branch statuses in batch
-      const branchStatuses = await getBatchBranchStatus(projectPath, branchNames);
-
-      // Map back to bead IDs
-      const beadStatuses: Record<string, BranchStatus> = {};
-      beadIds.forEach((beadId) => {
-        const branchName = beadIdToBranchName(beadId);
-        beadStatuses[beadId] = branchStatuses[branchName] || {
-          exists: false,
-          ahead: 0,
-          behind: 0,
-        };
-      });
-
-      setStatuses(beadStatuses);
-      setError(null);
-      hasLoadedRef.current = true;
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      setError(error);
-      console.error("Failed to load branch statuses:", error);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [projectPath, beadIds]);
-
-  /**
-   * Public refresh function for manual reload
-   */
-  const refresh = useCallback(async () => {
-    await loadStatuses();
-  }, [loadStatuses]);
-
-  // Load statuses when project path or bead IDs change
-  useEffect(() => {
-    // Check if bead IDs have actually changed
-    const beadIdsChanged =
-      beadIds.length !== prevBeadIdsRef.current.length ||
-      beadIds.some((id, i) => id !== prevBeadIdsRef.current[i]);
-
-    if (beadIdsChanged) {
-      prevBeadIdsRef.current = [...beadIds];
-      hasLoadedRef.current = false;
-    }
-
-    loadStatuses();
-  }, [loadStatuses, beadIds]);
-
-  // Set up periodic refresh (every 30 seconds)
-  useEffect(() => {
-    if (!projectPath || beadIds.length === 0) return;
-
-    const intervalId = setInterval(() => {
-      loadStatuses();
-    }, 30000);
-
-    return () => clearInterval(intervalId);
-  }, [projectPath, beadIds.length, loadStatuses]);
-
-  return {
-    statuses,
-    isLoading,
-    error,
-    refresh,
-  };
-}