Add shared sidebar section controls (#5585)

## Thinking Path

> - Paperclip is the control plane for AI-agent companies.
> - The board UI sidebar is one of the main ways operators scan active
agents and projects.
> - Agents and projects had duplicated section header behavior, which
made collapse controls, add actions, and future section menus harder to
keep consistent.
> - Operators also need lightweight ways to switch between their curated
sidebar order and common scan orders like alphabetical or recent
activity.
> - This pull request introduces a shared sidebar section header and
uses it for the Agents and Projects sidebar sections.
> - The benefit is a more consistent sidebar surface with reusable
header controls and persisted sort modes without losing the existing
drag-ordered Top view.

## What Changed

- Added a reusable `SidebarSection` component that supports collapsible
content, header actions, and section dropdown menus.
- Updated the Agents sidebar section to use the shared header and add
persisted `Top`, `Alphabetical`, and `Recent` sort modes.
- Updated the Projects sidebar section to use the shared header and add
persisted `Top`, `Alphabetical`, and `Recent` sort modes.
- Added local-storage helpers and cross-tab update events for
agent/project sidebar sort preferences.
- Added focused component coverage for the shared section behavior and
the updated Agents/Projects sidebar ordering paths.

## Verification

- `pnpm run preflight:workspace-links && pnpm exec vitest run
ui/src/components/SidebarSection.test.tsx
ui/src/components/SidebarProjects.test.tsx
ui/src/components/SidebarAgents.test.tsx`
  - 3 test files passed
  - 18 tests passed

## Risks

- Low-to-moderate UI risk: this changes sidebar section header
interactions and adds persisted client-side sort preferences.
- Drag ordering is intentionally limited to `Top` mode; non-top modes
render sorted lists and do not persist drag order changes.
- No database migrations or API contract changes.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex coding agent, GPT-5-based model, tool-use enabled; exact
hosted model build/context-window identifier was not exposed in this
session.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/lib/agent-order.ts

@@ -1,19 +1,32 @@
 import type { Agent } from "@paperclipai/shared";
 
 export const AGENT_ORDER_UPDATED_EVENT = "paperclip:agent-order-updated";
+export const AGENT_SORT_MODE_UPDATED_EVENT = "paperclip:agent-sort-mode-updated";
 const AGENT_ORDER_STORAGE_PREFIX = "paperclip.agentOrder";
+const AGENT_SORT_MODE_STORAGE_PREFIX = "paperclip.agentSortMode";
 const ANONYMOUS_USER_ID = "anonymous";
 
+export type AgentSidebarSortMode = "top" | "alphabetical" | "recent";
+
 type AgentOrderUpdatedDetail = {
   storageKey: string;
   orderedIds: string[];
 };
 
+export type AgentSortModeUpdatedDetail = {
+  storageKey: string;
+  sortMode: AgentSidebarSortMode;
+};
+
 function normalizeIdList(value: unknown): string[] {
   if (!Array.isArray(value)) return [];
   return value.filter((item): item is string => typeof item === "string" && item.length > 0);
 }
 
+function normalizeSortMode(value: unknown): AgentSidebarSortMode {
+  return value === "alphabetical" || value === "recent" || value === "top" ? value : "top";
+}
+
 function resolveUserId(userId: string | null | undefined): string {
   if (!userId) return ANONYMOUS_USER_ID;
   const trimmed = userId.trim();
@@ -24,6 +37,10 @@ export function getAgentOrderStorageKey(companyId: string, userId: string | null
   return `${AGENT_ORDER_STORAGE_PREFIX}:${companyId}:${resolveUserId(userId)}`;
 }
 
+export function getAgentSortModeStorageKey(companyId: string, userId: string | null | undefined): string {
+  return `${AGENT_SORT_MODE_STORAGE_PREFIX}:${companyId}:${resolveUserId(userId)}`;
+}
+
 export function readAgentOrder(storageKey: string): string[] {
   try {
     const raw = localStorage.getItem(storageKey);
@@ -34,6 +51,14 @@ export function readAgentOrder(storageKey: string): string[] {
   }
 }
 
+export function readAgentSortMode(storageKey: string): AgentSidebarSortMode {
+  try {
+    return normalizeSortMode(localStorage.getItem(storageKey));
+  } catch {
+    return "top";
+  }
+}
+
 export function writeAgentOrder(storageKey: string, orderedIds: string[]) {
   const normalized = normalizeIdList(orderedIds);
   try {
@@ -50,6 +75,22 @@ export function writeAgentOrder(storageKey: string, orderedIds: string[]) {
   }
 }
 
+export function writeAgentSortMode(storageKey: string, sortMode: AgentSidebarSortMode) {
+  const normalized = normalizeSortMode(sortMode);
+  try {
+    localStorage.setItem(storageKey, normalized);
+  } catch {
+    // Ignore storage write failures in restricted browser contexts.
+  }
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(
+      new CustomEvent<AgentSortModeUpdatedDetail>(AGENT_SORT_MODE_UPDATED_EVENT, {
+        detail: { storageKey, sortMode: normalized },
+      }),
+    );
+  }
+}
+
 export function sortAgentsByDefaultSidebarOrder(agents: Agent[]): Agent[] {
   if (agents.length === 0) return [];
 

ui/src/lib/project-order.ts

@@ -1,19 +1,32 @@
 import type { Project } from "@paperclipai/shared";
 
 export const PROJECT_ORDER_UPDATED_EVENT = "paperclip:project-order-updated";
+export const PROJECT_SORT_MODE_UPDATED_EVENT = "paperclip:project-sort-mode-updated";
 const PROJECT_ORDER_STORAGE_PREFIX = "paperclip.projectOrder";
+const PROJECT_SORT_MODE_STORAGE_PREFIX = "paperclip.projectSortMode";
 const ANONYMOUS_USER_ID = "anonymous";
 
+export type ProjectSidebarSortMode = "top" | "alphabetical" | "recent";
+
 type ProjectOrderUpdatedDetail = {
   storageKey: string;
   orderedIds: string[];
 };
 
+export type ProjectSortModeUpdatedDetail = {
+  storageKey: string;
+  sortMode: ProjectSidebarSortMode;
+};
+
 function normalizeIdList(value: unknown): string[] {
   if (!Array.isArray(value)) return [];
   return value.filter((item): item is string => typeof item === "string" && item.length > 0);
 }
 
+function normalizeSortMode(value: unknown): ProjectSidebarSortMode {
+  return value === "alphabetical" || value === "recent" || value === "top" ? value : "top";
+}
+
 function resolveUserId(userId: string | null | undefined): string {
   if (!userId) return ANONYMOUS_USER_ID;
   const trimmed = userId.trim();
@@ -24,6 +37,10 @@ export function getProjectOrderStorageKey(companyId: string, userId: string | nu
   return `${PROJECT_ORDER_STORAGE_PREFIX}:${companyId}:${resolveUserId(userId)}`;
 }
 
+export function getProjectSortModeStorageKey(companyId: string, userId: string | null | undefined): string {
+  return `${PROJECT_SORT_MODE_STORAGE_PREFIX}:${companyId}:${resolveUserId(userId)}`;
+}
+
 export function readProjectOrder(storageKey: string): string[] {
   try {
     const raw = localStorage.getItem(storageKey);
@@ -34,6 +51,14 @@ export function readProjectOrder(storageKey: string): string[] {
   }
 }
 
+export function readProjectSortMode(storageKey: string): ProjectSidebarSortMode {
+  try {
+    return normalizeSortMode(localStorage.getItem(storageKey));
+  } catch {
+    return "top";
+  }
+}
+
 export function writeProjectOrder(storageKey: string, orderedIds: string[]) {
   const normalized = normalizeIdList(orderedIds);
   try {
@@ -50,6 +75,22 @@ export function writeProjectOrder(storageKey: string, orderedIds: string[]) {
   }
 }
 
+export function writeProjectSortMode(storageKey: string, sortMode: ProjectSidebarSortMode) {
+  const normalized = normalizeSortMode(sortMode);
+  try {
+    localStorage.setItem(storageKey, normalized);
+  } catch {
+    // Ignore storage write failures in restricted browser contexts.
+  }
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(
+      new CustomEvent<ProjectSortModeUpdatedDetail>(PROJECT_SORT_MODE_UPDATED_EVENT, {
+        detail: { storageKey, sortMode: normalized },
+      }),
+    );
+  }
+}
+
 export function sortProjectsByStoredOrder(projects: Project[], orderedIds: string[]): Project[] {
   if (projects.length === 0) return [];
   if (orderedIds.length === 0) return projects;