Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

9.5 KB
Raw Blame
import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
import { removeMember } from '@/lib/api/endpoints/members';
import {
  createTeamProject,
  copyTeamProject,
  updateTeamProject,
  archiveTeamProject,
  restoreTeamProject,
  deleteTeamProject,
} from '@/lib/api/endpoints/teams';
import {
  type Project,
  type ProjectPreferencePatch,
  type ProjectSearchFilters,
  listProjects,
  searchProjects,
  getProject,
  getBoardIssues,
  updateProject,
  updateProjectPreferences,
} from '@/lib/api/endpoints/projects';
import { nextPageParam } from '@/lib/api/core/paging';
import { qk } from '@/services/queryKeys';

export function useProjectsQuery() {
  return useQuery({ queryKey: qk.projects, queryFn: () => listProjects() });
}

const PROJECT_SEARCH_PAGE = 30;

export function useProjectSearchQuery(filters: ProjectSearchFilters, enabled = true) {
  return useInfiniteQuery({
    queryKey: qk.projectSearch(filters),
    queryFn: ({ pageParam }) =>
      searchProjects(filters, { page: pageParam, pageSize: PROJECT_SEARCH_PAGE }),
    initialPageParam: 1,
    getNextPageParam: nextPageParam,
    enabled,
  });
}

export function useUpdateProjectPreferences() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: ({ projectKey, patch }: { projectKey: string; patch: ProjectPreferencePatch }) =>
      updateProjectPreferences(projectKey, patch),
    onSuccess: (preferences, { projectKey }) => {
      qc.setQueryData<Project[]>(qk.projects, (projects) =>
        projects?.map((project) =>
          project.ref === projectKey ? { ...project, ...preferences } : project,
        ),
      );
      void qc.invalidateQueries({ queryKey: qk.projects });
    },
  });
}

// The board scaffold (columns, types, labels, custom fields, viewer). The issues
// come from useBoardIssuesQuery; the Shell composes the two.
export function useProjectQuery(projectKey: string | null) {
  return useQuery({
    queryKey: qk.project(projectKey ?? ''),
    queryFn: () => getProject(projectKey!),
    enabled: projectKey != null,
  });
}

// The board's issues plus its change marker, loaded alongside the scaffold.
export function useBoardIssuesQuery(projectKey: string | null) {
  return useQuery({
    queryKey: qk.boardIssues(projectKey ?? ''),
    queryFn: () => getBoardIssues(projectKey!),
    enabled: projectKey != null,
  });
}

// Returns a callback that invalidates a project's detail query. Used by the
// settings service mutations to refresh the project after a structural write.
export function useInvalidateProject(projectKey: string | null) {
  const qc = useQueryClient();
  return () => {
    if (projectKey) {
      void qc.invalidateQueries({ queryKey: qk.project(projectKey) });
      // A structural change (deleted/renamed label, type, column, custom field) can
      // affect how the board's issues render, so refresh the board issues too.
      void qc.invalidateQueries({ queryKey: qk.boardIssues(projectKey) });
    }
    // A structural change (renamed/deleted label, type, assignee, column, or
    // custom field) can change what an open issue detail shows — its values come
    // from the issue query, not the project — so refresh any open issue too. Only
    // the active (open) issue actually refetches.
    void qc.invalidateQueries({ queryKey: qk.anyIssue });
  };
}

// Creates a project in a team. `copyFromId` copies that project's structure instead of
// starting from a preset; the source belongs to the same team.
export function useCreateProject() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: ({
      teamId,
      copyFromId,
      input,
    }: {
      teamId: number;
      copyFromId?: number;
      input: {
        key: string;
        name: string;
        description?: string;
        include?: Record<string, boolean>;
        preset?: string;
        templateId?: number;
      };
    }) =>
      copyFromId == null
        ? createTeamProject(teamId, input)
        : copyTeamProject(teamId, copyFromId, input),
    onSuccess: (project) => {
      // Add the new project to the cached list immediately so navigating to it
      // (onCreated → setProjectKey) sticks. Otherwise the list has not refetched
      // yet and App's "unknown project key" guard bounces back to the first project.
      qc.setQueryData<Project[]>(qk.projects, (prev) => (prev ? [...prev, project] : [project]));
      void qc.invalidateQueries({ queryKey: qk.projects });
      // The team panel lists the projects of the team, so it gains the new one.
      void qc.invalidateQueries({ queryKey: qk.team(project.teamId) });
      void qc.invalidateQueries({ queryKey: qk.teams });
    },
  });
}

export function useUpdateProject() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: ({
      projectKey,
      patch,
    }: {
      projectKey: string;
      patch: { name?: string; description?: string };
    }) => updateProject(projectKey, patch),
    onSuccess: (updated, { projectKey }) => {
      // Reflect the new name/description in the cached list immediately, then
      // refetch the list and the project detail (its header and switcher read
      // the name) to reconcile.
      // Merge only the edited fields — the update response carries no `role`, so
      // spreading the whole object would wipe the caller's role in the list item.
      qc.setQueryData<Project[]>(qk.projects, (prev) =>
        prev?.map((p) =>
          p.ref === projectKey ? { ...p, name: updated.name, description: updated.description } : p,
        ),
      );
      void qc.invalidateQueries({ queryKey: qk.projects });
      void qc.invalidateQueries({ queryKey: qk.project(projectKey) });
    },
  });
}

// Renames a project of a team, or edits its description. Team owners and managers
// may, so the team route carries it rather than the project's own settings.
export function useUpdateTeamProject() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: ({
      teamId,
      projectId,
      patch,
    }: {
      teamId: number;
      projectId: number;
      projectKey: string;
      patch: { key?: string; name?: string; description?: string };
    }) => updateTeamProject(teamId, projectId, patch),
    onSuccess: (updated, { teamId, projectKey }) => {
      qc.setQueryData<Project[]>(qk.projects, (prev) =>
        prev?.map((p) =>
          p.ref === projectKey
            ? {
                ...p,
                key: updated.key,
                ref: updated.ref,
                name: updated.name,
                description: updated.description,
              }
            : p,
        ),
      );
      void qc.invalidateQueries({ queryKey: qk.projects });
      // A renamed key leaves the old ref naming no project, so its cache is dropped
      // rather than refetched.
      if (updated.ref !== projectKey) qc.removeQueries({ queryKey: qk.project(projectKey) });
      else void qc.invalidateQueries({ queryKey: qk.project(projectKey) });
      void qc.invalidateQueries({ queryKey: qk.team(teamId) });
    },
  });
}

// The project list carries only active projects, so it is refetched either way.
export function useSetTeamProjectArchived() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: ({
      teamId,
      projectId,
      archived,
    }: {
      teamId: number;
      projectId: number;
      archived: boolean;
    }) =>
      archived ? archiveTeamProject(teamId, projectId) : restoreTeamProject(teamId, projectId),
    onSuccess: (_project, { teamId }) => {
      void qc.invalidateQueries({ queryKey: qk.projects });
      void qc.invalidateQueries({ queryKey: qk.anyTeamProjects(teamId) });
    },
  });
}

// Drops the project from the cached list immediately (so it disappears even
// before the refetch resolves) and discards its now-dead per-project caches so it
// cannot be reopened with stale data. Then refetches the list to reconcile.
function forgetProject(qc: ReturnType<typeof useQueryClient>, projectKey: string) {
  qc.setQueryData<Project[]>(qk.projects, (prev) => prev?.filter((p) => p.ref !== projectKey));
  qc.removeQueries({ queryKey: qk.project(projectKey) });
  qc.removeQueries({ queryKey: qk.boardIssues(projectKey) });
  qc.removeQueries({ queryKey: qk.views(projectKey) });
  qc.removeQueries({ queryKey: qk.dashboards(projectKey) });
  qc.removeQueries({ queryKey: qk.analyticsForProject(projectKey) });
  void qc.invalidateQueries({ queryKey: qk.projects });
}

// Leave a project you are a member of (self-removal). The API refuses if you are
// the project's last owner.
export function useLeaveProject() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: ({ projectKey, userId }: { projectKey: string; userId: string }) =>
      removeMember(projectKey, userId),
    onSuccess: (_data, { projectKey }) => {
      forgetProject(qc, projectKey);
      // The team panel counts the members of each project it lists and names them.
      void qc.invalidateQueries({ queryKey: qk.anyTeam });
    },
  });
}

// Deletes a project of a team. Only a team owner may, so the team route carries it
// rather than the project's own danger zone.
export function useDeleteTeamProject() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: ({
      teamId,
      projectId,
    }: {
      teamId: number;
      projectId: number;
      projectKey: string;
    }) => deleteTeamProject(teamId, projectId),
    onSuccess: (_data, { teamId, projectKey }) => {
      forgetProject(qc, projectKey);
      void qc.invalidateQueries({ queryKey: qk.team(teamId) });
      void qc.invalidateQueries({ queryKey: qk.teams });
    },
  });
}