Add projects page sorting

Co-Authored-By: Paperclip <noreply@paperclip.ing>

ui/src/components/EntityRow.tsx

@@ -12,6 +12,7 @@ interface EntityRowProps {
   to?: string;
   onClick?: () => void;
   className?: string;
+  reserveSubtitleSpace?: boolean;
 }
 
 export function EntityRow({
@@ -24,6 +25,7 @@ export function EntityRow({
   to,
   onClick,
   className,
+  reserveSubtitleSpace,
 }: EntityRowProps) {
   const isClickable = !!(to || onClick);
   const classes = cn(
@@ -45,8 +47,13 @@ export function EntityRow({
           )}
           <span className="truncate">{title}</span>
         </div>
-        {subtitle && (
-          <p className="text-xs text-muted-foreground truncate mt-0.5">{subtitle}</p>
+        {(subtitle || reserveSubtitleSpace) && (
+          <p
+            className={cn("text-xs text-muted-foreground truncate mt-0.5 min-h-4", !subtitle && "invisible")}
+            aria-hidden={!subtitle}
+          >
+            {subtitle}
+          </p>
         )}
       </div>
       {trailing && <div className="flex items-center gap-2 shrink-0">{trailing}</div>}

ui/src/pages/Projects.test.tsx

@@ -0,0 +1,164 @@
+// @vitest-environment jsdom
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { Project } from "@paperclipai/shared";
+import { act, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Projects } from "./Projects";
+
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const mockProjectsApi = vi.hoisted(() => ({
+  list: vi.fn(),
+}));
+const mockOpenNewProject = vi.hoisted(() => vi.fn());
+const mockSetBreadcrumbs = vi.hoisted(() => vi.fn());
+
+vi.mock("../api/projects", () => ({ projectsApi: mockProjectsApi }));
+vi.mock("@/lib/router", () => ({
+  Link: ({ children, to }: { children?: ReactNode; to: string }) => <a href={to}>{children}</a>,
+}));
+vi.mock("../context/CompanyContext", () => ({
+  useCompany: () => ({ selectedCompanyId: "company-1" }),
+}));
+vi.mock("../context/DialogContext", () => ({
+  useDialogActions: () => ({ openNewProject: mockOpenNewProject }),
+}));
+vi.mock("../context/BreadcrumbContext", () => ({
+  useBreadcrumbs: () => ({ setBreadcrumbs: mockSetBreadcrumbs }),
+}));
+
+function project(overrides: Partial<Project>): Project {
+  const now = new Date("2026-05-01T00:00:00Z");
+  return {
+    id: "project-1",
+    companyId: "company-1",
+    urlKey: "project-1",
+    goalId: null,
+    goalIds: [],
+    goals: [],
+    name: "Project",
+    description: null,
+    status: "in_progress",
+    leadAgentId: null,
+    targetDate: null,
+    color: "#14b8a6",
+    env: null,
+    pauseReason: null,
+    pausedAt: null,
+    executionWorkspacePolicy: null,
+    codebase: {
+      workspaceId: null,
+      repoUrl: null,
+      repoRef: null,
+      defaultRef: null,
+      repoName: null,
+      localFolder: null,
+      managedFolder: "/tmp/project-1",
+      effectiveLocalFolder: "/tmp/project-1",
+      origin: "managed_checkout",
+    },
+    workspaces: [],
+    primaryWorkspace: null,
+    archivedAt: null,
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+async function renderProjects(container: HTMLElement) {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  let root: Root | null = null;
+
+  await act(async () => {
+    root = createRoot(container);
+    root.render(
+      <QueryClientProvider client={queryClient}>
+        <Projects />
+      </QueryClientProvider>,
+    );
+  });
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+  return root;
+}
+
+function projectLinkNames(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll<HTMLAnchorElement>("a[href^='/projects/']")).map((link) => {
+    const title = link.querySelector("span.truncate");
+    return title?.textContent ?? "";
+  });
+}
+
+describe("Projects", () => {
+  let root: Root | null = null;
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    mockProjectsApi.list.mockResolvedValue([
+      project({
+        id: "project-bravo",
+        urlKey: "bravo",
+        name: "Bravo",
+        description: null,
+        updatedAt: new Date("2026-05-02T00:00:00Z"),
+      }),
+      project({
+        id: "project-alpha",
+        urlKey: "alpha",
+        name: "Alpha",
+        description: "First project",
+        updatedAt: new Date("2026-05-01T00:00:00Z"),
+      }),
+      project({
+        id: "project-charlie",
+        urlKey: "charlie",
+        name: "Charlie",
+        description: null,
+        updatedAt: new Date("2026-05-03T00:00:00Z"),
+      }),
+    ]);
+  });
+
+  afterEach(() => {
+    act(() => root?.unmount());
+    root = null;
+    container.remove();
+    vi.clearAllMocks();
+  });
+
+  it("sorts projects by name by default and can switch sort mode", async () => {
+    root = await renderProjects(container);
+
+    expect(projectLinkNames(container)).toEqual(["Alpha", "Bravo", "Charlie"]);
+
+    const select = container.querySelector("select");
+    expect(select).not.toBeNull();
+
+    await act(async () => {
+      select!.value = "updated";
+      select!.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+
+    expect(projectLinkNames(container)).toEqual(["Charlie", "Bravo", "Alpha"]);
+  });
+
+  it("reserves description line height for projects without descriptions", async () => {
+    root = await renderProjects(container);
+
+    const bravoLink = Array.from(container.querySelectorAll<HTMLAnchorElement>("a")).find((link) =>
+      link.textContent?.includes("Bravo"),
+    );
+    const hiddenDescriptionLine = bravoLink?.querySelector("p[aria-hidden='true']");
+
+    expect(hiddenDescriptionLine).not.toBeNull();
+    expect(hiddenDescriptionLine?.className).toContain("min-h-4");
+  });
+});

ui/src/pages/Projects.tsx

@@ -1,5 +1,6 @@
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { useQuery } from "@tanstack/react-query";
+import type { Project } from "@paperclipai/shared";
 import { projectsApi } from "../api/projects";
 import { useCompany } from "../context/CompanyContext";
 import { useDialogActions } from "../context/DialogContext";
@@ -11,12 +12,67 @@ import { EmptyState } from "../components/EmptyState";
 import { PageSkeleton } from "../components/PageSkeleton";
 import { formatDate, projectUrl } from "../lib/utils";
 import { Button } from "@/components/ui/button";
-import { Hexagon, Plus } from "lucide-react";
+import { ArrowUpDown, Hexagon, Plus } from "lucide-react";
+
+type ProjectSortMode = "name" | "updated" | "targetDate" | "status";
+
+const PROJECT_SORT_LABELS: Record<ProjectSortMode, string> = {
+  name: "Name",
+  updated: "Recently updated",
+  targetDate: "Target date",
+  status: "Status",
+};
+
+const PROJECT_STATUS_RANK: Record<Project["status"], number> = {
+  in_progress: 0,
+  planned: 1,
+  backlog: 2,
+  completed: 3,
+  cancelled: 4,
+};
+
+function projectTime(project: Project, field: "createdAt" | "updatedAt"): number {
+  const value = project[field];
+  const time = value instanceof Date ? value.getTime() : new Date(value).getTime();
+  return Number.isFinite(time) ? time : 0;
+}
+
+function compareProjectNames(left: Project, right: Project): number {
+  const nameDiff = left.name.localeCompare(right.name, undefined, { sensitivity: "base" });
+  return nameDiff !== 0 ? nameDiff : left.id.localeCompare(right.id);
+}
+
+function compareTargetDates(left: Project, right: Project): number {
+  if (!left.targetDate && !right.targetDate) return compareProjectNames(left, right);
+  if (!left.targetDate) return 1;
+  if (!right.targetDate) return -1;
+
+  const dateDiff = left.targetDate.localeCompare(right.targetDate);
+  return dateDiff !== 0 ? dateDiff : compareProjectNames(left, right);
+}
+
+function sortProjects(projects: Project[], sortMode: ProjectSortMode): Project[] {
+  return [...projects].sort((left, right) => {
+    if (sortMode === "updated") {
+      const updatedDiff = projectTime(right, "updatedAt") - projectTime(left, "updatedAt");
+      return updatedDiff !== 0 ? updatedDiff : compareProjectNames(left, right);
+    }
+    if (sortMode === "targetDate") {
+      return compareTargetDates(left, right);
+    }
+    if (sortMode === "status") {
+      const statusDiff = PROJECT_STATUS_RANK[left.status] - PROJECT_STATUS_RANK[right.status];
+      return statusDiff !== 0 ? statusDiff : compareProjectNames(left, right);
+    }
+    return compareProjectNames(left, right);
+  });
+}
 
 export function Projects() {
   const { selectedCompanyId } = useCompany();
   const { openNewProject } = useDialogActions();
   const { setBreadcrumbs } = useBreadcrumbs();
+  const [sortMode, setSortMode] = useState<ProjectSortMode>("name");
 
   useEffect(() => {
     setBreadcrumbs([{ label: "Projects" }]);
@@ -31,6 +87,10 @@ export function Projects() {
     () => (allProjects ?? []).filter((p) => !p.archivedAt),
     [allProjects],
   );
+  const sortedProjects = useMemo(
+    () => sortProjects(projects, sortMode),
+    [projects, sortMode],
+  );
 
   if (!selectedCompanyId) {
     return <EmptyState icon={Hexagon} message="Select a company to view projects." />;
@@ -42,7 +102,22 @@ export function Projects() {
 
   return (
     <div className="space-y-4">
-      <div className="flex items-center justify-end">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <label className="flex items-center gap-2 text-sm text-muted-foreground">
+          <ArrowUpDown className="h-4 w-4" />
+          <span>Sort</span>
+          <select
+            className="rounded-md border border-border bg-background px-2.5 py-1.5 text-sm text-foreground outline-none transition-colors hover:bg-accent/50 focus-visible:ring-2 focus-visible:ring-ring"
+            value={sortMode}
+            onChange={(event) => setSortMode(event.target.value as ProjectSortMode)}
+          >
+            {(Object.keys(PROJECT_SORT_LABELS) as ProjectSortMode[]).map((value) => (
+              <option key={value} value={value}>
+                {PROJECT_SORT_LABELS[value]}
+              </option>
+            ))}
+          </select>
+        </label>
         <Button size="sm" variant="outline" onClick={openNewProject}>
           <Plus className="h-4 w-4 mr-1" />
           Add Project
@@ -62,11 +137,12 @@ export function Projects() {
 
       {projects.length > 0 && (
         <div className="border border-border">
-          {projects.map((project) => (
+          {sortedProjects.map((project) => (
             <EntityRow
               key={project.id}
               title={project.name}
               subtitle={project.description ?? undefined}
+              reserveSubtitleSpace
               to={projectUrl(project)}
               trailing={
                 <div className="flex items-center gap-3">