feat(ui): add collapsible sidebar rail and takeover panes (#7824)
## Thinking Path > - Paperclip is the open source control plane people use to manage AI agents, work, and company context. > - The board UI sidebar is the main way operators keep orientation across companies, projects, agents, issues, and settings. > - The existing fixed expanded sidebar competes with route-specific navigation, especially company settings and plugin routes that bring their own contextual sidebar. > - A collapsible primary rail preserves global navigation while giving contextual pages more horizontal room. > - This pull request adds a persisted collapsed rail, hover/focus peek, keyboard toggle, and a secondary sidebar takeover model for settings and plugin `routeSidebar` surfaces. > - The benefit is a denser board shell that keeps the app rail available without replacing it when a route needs its own navigation. ## Linked Issues or Issue Description Paperclip issue: PAP-10638 Create collapsible sidebar branch. Related GitHub PR found during duplicate search: #3838 (`feat/collapsible-sidebar`) covers a similar sidebar area but is a different head branch and implementation. This PR intentionally packages the work from `PAP-10638-collapsable-sidebar` into one reviewable branch. Problem description: The board shell needs a first-class collapsed sidebar mode. Contextual surfaces such as company settings and plugin route sidebars should not replace the global app sidebar; they should collapse the app sidebar to a rail and render their contextual navigation beside it. ## What Changed - Added desktop collapsed/sidebar-peek state to `SidebarContext`, including persisted user pins, route collapse requests, and forced collapse for secondary-sidebar routes. - Replaced the old resizable sidebar pane with `SidebarShell`, which supports a fixed 64px rail, persisted expanded width, keyboard/pointer resizing, and hover/focus peek overlay behavior. - Updated `Sidebar`, sidebar nav items, project/agent sections, badges, and account/company menu presentation for expanded, collapsed, and peeking states. - Added `RequestCollapsedSidebar` and `SecondarySidebar` so routes and plugin `routeSidebar` slots can request contextual sidebar layouts without replacing the primary app sidebar. - Wired company settings and plugin route sidebars into the secondary-pane takeover model. - Added focused Vitest coverage for sidebar state precedence, shell sizing, nav item rail rendering, keyboard shortcuts, layout takeover behavior, and route collapse requests. - Updated plugin authoring docs/spec references for route sidebar behavior. ## Verification Targeted local verification passed: ```sh NODE_ENV=test pnpm run preflight:workspace-links && NODE_ENV=test pnpm exec vitest run ui/src/context/SidebarContext.test.tsx ui/src/components/SidebarShell.test.tsx ui/src/components/Sidebar.test.tsx ui/src/components/Layout.test.tsx ui/src/components/RequestCollapsedSidebar.test.tsx ui/src/components/SidebarNavItem.test.tsx ui/src/components/SidebarAgents.test.tsx ui/src/components/SidebarProjects.test.tsx ui/src/components/KeyboardShortcutsCheatsheet.test.tsx ui/src/hooks/useKeyboardShortcuts.test.tsx ``` Result: 10 test files passed, 88 tests passed. Additional follow-up verification passed after review fixes: ```sh NODE_ENV=test pnpm run preflight:workspace-links && NODE_ENV=test pnpm exec vitest run ui/src/components/Layout.test.tsx ui/src/context/SidebarContext.test.tsx && pnpm --filter /ui typecheck ``` Result: 2 test files passed, 28 tests passed, and UI typecheck passed. Latest PR-head remote checks: Paperclip PR workflow, Snyk, Socket, and Greptile are green; commitperclip `review` is cancelled in its security-gate step after filing a non-blocking neutral `security-review` check. Notes: - A direct run without `NODE_ENV=test` loads React's production build in this workspace, where `act` is unavailable; the command above matches the repo stable runner's test environment. - I did not run Playwright/browser e2e or full workspace build/typecheck in this PR-creation heartbeat. - QA screenshots are attached in https://github.com/paperclipai/paperclip/pull/7824#issuecomment-4661968387 for expanded, collapsed rail, hover peek, and settings secondary-sidebar states. ## Risks - Medium UI layout risk: this changes the board shell and primary sidebar composition across many routes. - Local storage migration risk is low: new collapsed state uses a new key and existing width storage remains scoped to the sidebar width. - Plugin route risk: plugin `routeSidebar` slots now render as secondary panes on desktop, so plugin authors should confirm their route sidebar content fits a 240px contextual pane. - Mobile risk appears low because mobile keeps the drawer model and gates collapsed/peek behavior to desktop. > 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 based on GPT-5, with local shell/git/GitHub CLI tool use. Exact service-side model identifier and context window were not exposed in this runtime. ## 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 searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] 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 - [ ] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
+156
-21
@@ -1,4 +1,4 @@
|
||||
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
|
||||
import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
|
||||
import { useQuery } from "@tanstack/react-query";
|
||||
import { Outlet, useLocation, useNavigate, useNavigationType, useParams } from "@/lib/router";
|
||||
import { Sidebar } from "./Sidebar";
|
||||
@@ -17,7 +17,8 @@ import { MobileBottomNav } from "./MobileBottomNav";
|
||||
import { WorktreeBanner } from "./WorktreeBanner";
|
||||
import { DevRestartBanner } from "./DevRestartBanner";
|
||||
import { StandaloneBrowserControls } from "./StandaloneBrowserControls";
|
||||
import { ResizableSidebarPane } from "./ResizableSidebarPane";
|
||||
import { SidebarShell } from "./SidebarShell";
|
||||
import { SecondarySidebar } from "./SecondarySidebar";
|
||||
import { SidebarAccountMenu } from "./SidebarAccountMenu";
|
||||
import { useDialogActions } from "../context/DialogContext";
|
||||
import { GeneralSettingsProvider } from "../context/GeneralSettingsContext";
|
||||
@@ -48,7 +49,17 @@ function getCompanyRouteSegment(pathname: string, companyPrefix: string | undefi
|
||||
}
|
||||
|
||||
export function Layout() {
|
||||
const { sidebarOpen, setSidebarOpen, toggleSidebar, isMobile } = useSidebar();
|
||||
const {
|
||||
sidebarOpen,
|
||||
setSidebarOpen,
|
||||
toggleSidebar,
|
||||
toggleCollapsed,
|
||||
collapsed,
|
||||
peeking,
|
||||
setPeeking,
|
||||
isMobile,
|
||||
setForceCollapsed,
|
||||
} = useSidebar();
|
||||
const { openNewIssue, openOnboarding } = useDialogActions();
|
||||
const { togglePanelVisible } = usePanel();
|
||||
const {
|
||||
@@ -102,16 +113,21 @@ export function Layout() {
|
||||
}),
|
||||
[routeSidebarCompanyId, routeSidebarCompanyPrefix],
|
||||
);
|
||||
const companySidebar = routeSidebarSlot ? (
|
||||
// Takeover routes (company settings, plugin `routeSidebar`) no longer replace
|
||||
// the app `<Sidebar/>`. Instead the host collapses it to its rail and renders
|
||||
// the contextual sidebar in a second pane (PAP-10695). One resolver drives
|
||||
// both desktop (SecondarySidebar) and mobile (off-canvas drawer).
|
||||
const secondarySidebar = isCompanySettingsRoute ? (
|
||||
<CompanySettingsSidebar />
|
||||
) : routeSidebarSlot ? (
|
||||
<PluginSlotMount
|
||||
slot={routeSidebarSlot}
|
||||
context={sidebarContext}
|
||||
className="h-full w-full"
|
||||
missingBehavior="placeholder"
|
||||
/>
|
||||
) : (
|
||||
<Sidebar />
|
||||
);
|
||||
) : null;
|
||||
const hasSecondarySidebar = secondarySidebar != null;
|
||||
const { data: health } = useQuery({
|
||||
queryKey: queryKeys.health,
|
||||
queryFn: () => healthApi.get(),
|
||||
@@ -127,6 +143,16 @@ export function Layout() {
|
||||
queryFn: () => instanceSettingsApi.getGeneral(),
|
||||
}).data?.keyboardShortcuts === true;
|
||||
|
||||
// A secondary sidebar always collapses the app sidebar to its rail (still
|
||||
// peek-able) — a hard invariant that overrides the user pin while the route
|
||||
// is active, but does NOT mutate the persisted preference. Clearing the force
|
||||
// on cleanup restores the user's expanded/collapsed choice when navigating
|
||||
// off the takeover route (PAP-10694).
|
||||
useLayoutEffect(() => {
|
||||
setForceCollapsed(hasSecondarySidebar);
|
||||
return () => setForceCollapsed(false);
|
||||
}, [hasSecondarySidebar, setForceCollapsed]);
|
||||
|
||||
useEffect(() => {
|
||||
if (companiesLoading || onboardingTriggered.current) return;
|
||||
if (health?.deploymentMode === "authenticated") return;
|
||||
@@ -178,6 +204,15 @@ export function Layout() {
|
||||
]);
|
||||
|
||||
const togglePanel = togglePanelVisible;
|
||||
// Cmd/Ctrl+B: collapse/expand the pinned rail on desktop; on mobile keep
|
||||
// toggling the off-canvas drawer.
|
||||
const toggleCollapse = useCallback(() => {
|
||||
if (isMobile) {
|
||||
toggleSidebar();
|
||||
} else {
|
||||
toggleCollapsed();
|
||||
}
|
||||
}, [isMobile, toggleSidebar, toggleCollapsed]);
|
||||
const openSearch = useCallback(() => {
|
||||
document.dispatchEvent(new KeyboardEvent("keydown", {
|
||||
key: "k",
|
||||
@@ -187,6 +222,102 @@ export function Layout() {
|
||||
}));
|
||||
}, []);
|
||||
|
||||
// Peek (hover flyout) triggers for the collapsed rail. Opening has a tiny
|
||||
// delay so a pointer merely sweeping across the rail doesn't flash it open;
|
||||
// closing is debounced to avoid flicker on the rail→overlay seam. Keyboard
|
||||
// focus opens immediately so tabbing reaches the full nav. Context gates the
|
||||
// effective `peeking` to desktop + collapsed + hover-capable pointers, so
|
||||
// these handlers are inert otherwise.
|
||||
const peekTimer = useRef<number | null>(null);
|
||||
// Whether the pointer is currently over the peek panel. Used to keep the peek
|
||||
// open across focus changes (e.g. navigation steals focus to <main>) as long as
|
||||
// the user is still hovering — it should only close when they actually mouse off
|
||||
// (PAP-10676).
|
||||
const pointerInsidePanel = useRef(false);
|
||||
// When the user explicitly collapses while the pointer is still over the panel,
|
||||
// suppress re-peeking until the pointer actually leaves — otherwise the lingering
|
||||
// hover immediately re-expands the rail and the collapse "doesn't take" until the
|
||||
// mouse moves away (PAP-10676). Re-armed on the next genuine pointer-leave.
|
||||
const suppressPeekRef = useRef(false);
|
||||
const clearPeekTimer = useCallback(() => {
|
||||
if (peekTimer.current !== null) {
|
||||
window.clearTimeout(peekTimer.current);
|
||||
peekTimer.current = null;
|
||||
}
|
||||
}, []);
|
||||
const openPeek = useCallback(() => {
|
||||
clearPeekTimer();
|
||||
peekTimer.current = window.setTimeout(() => setPeeking(true), 50);
|
||||
}, [clearPeekTimer, setPeeking]);
|
||||
const openPeekImmediate = useCallback(() => {
|
||||
clearPeekTimer();
|
||||
setPeeking(true);
|
||||
}, [clearPeekTimer, setPeeking]);
|
||||
const closePeek = useCallback(() => {
|
||||
clearPeekTimer();
|
||||
peekTimer.current = window.setTimeout(() => setPeeking(false), 120);
|
||||
}, [clearPeekTimer, setPeeking]);
|
||||
// Tracked even while expanded so that, at the moment of collapse, we know
|
||||
// whether the pointer is over the panel and should suppress the re-peek.
|
||||
const handlePanelPointerEnter = useCallback(() => {
|
||||
pointerInsidePanel.current = true;
|
||||
if (collapsed && !suppressPeekRef.current) openPeek();
|
||||
}, [collapsed, openPeek]);
|
||||
const handlePanelPointerLeave = useCallback(() => {
|
||||
pointerInsidePanel.current = false;
|
||||
suppressPeekRef.current = false; // pointer left — re-arm peek for the next hover
|
||||
closePeek();
|
||||
}, [closePeek]);
|
||||
const handlePanelFocus = useCallback(() => {
|
||||
if (suppressPeekRef.current) return;
|
||||
openPeekImmediate();
|
||||
}, [openPeekImmediate]);
|
||||
// Close on focus leaving the panel only when the pointer isn't hovering it.
|
||||
// Clicking a rail/peek nav item moves focus to <main> on navigation; if the
|
||||
// mouse is still over the flyout we keep it open until the pointer leaves.
|
||||
const handlePanelBlur = useCallback(() => {
|
||||
if (pointerInsidePanel.current) return;
|
||||
closePeek();
|
||||
}, [closePeek]);
|
||||
|
||||
// Tidy up any pending peek timer on unmount.
|
||||
useEffect(() => clearPeekTimer, [clearPeekTimer]);
|
||||
|
||||
// An explicit collapse must be atomic: cancel any in-flight/active peek, and if
|
||||
// the pointer is still over the panel suppress re-peeking until it leaves, so the
|
||||
// rail doesn't immediately re-expand under the lingering hover (PAP-10676).
|
||||
const wasCollapsed = useRef(collapsed);
|
||||
useEffect(() => {
|
||||
if (collapsed !== wasCollapsed.current) {
|
||||
if (collapsed) {
|
||||
clearPeekTimer();
|
||||
setPeeking(false);
|
||||
suppressPeekRef.current = pointerInsidePanel.current;
|
||||
} else {
|
||||
suppressPeekRef.current = false;
|
||||
}
|
||||
wasCollapsed.current = collapsed;
|
||||
}
|
||||
}, [collapsed, clearPeekTimer, setPeeking]);
|
||||
|
||||
// Intentionally do NOT close the peek on navigation: clicking a nav item means
|
||||
// the pointer is still over the flyout, so it should stay open until the user
|
||||
// actually mouses off (handled by onPanelMouseLeave) or blurs out / hits Escape
|
||||
// (PAP-10676). Auto-closing here made the sidebar collapse on every page change.
|
||||
|
||||
// Escape closes an open peek without trapping the pointer.
|
||||
useEffect(() => {
|
||||
if (!peeking) return;
|
||||
const onKeyDown = (event: KeyboardEvent) => {
|
||||
if (event.key === "Escape") {
|
||||
clearPeekTimer();
|
||||
setPeeking(false);
|
||||
}
|
||||
};
|
||||
window.addEventListener("keydown", onKeyDown);
|
||||
return () => window.removeEventListener("keydown", onKeyDown);
|
||||
}, [peeking, clearPeekTimer, setPeeking]);
|
||||
|
||||
useCompanyPageMemory();
|
||||
|
||||
useKeyboardShortcuts({
|
||||
@@ -194,6 +325,7 @@ export function Layout() {
|
||||
onNewIssue: () => openNewIssue(),
|
||||
onSearch: openSearch,
|
||||
onToggleSidebar: toggleSidebar,
|
||||
onToggleCollapse: toggleCollapse,
|
||||
onTogglePanel: togglePanel,
|
||||
onShowShortcuts: () => setShortcutsOpen(true),
|
||||
});
|
||||
@@ -350,11 +482,7 @@ export function Layout() {
|
||||
>
|
||||
<div className="flex flex-1 min-h-0 overflow-hidden">
|
||||
<div className="w-60 shrink-0 overflow-hidden">
|
||||
{isCompanySettingsRoute ? (
|
||||
<CompanySettingsSidebar />
|
||||
) : (
|
||||
companySidebar
|
||||
)}
|
||||
{hasSecondarySidebar ? secondarySidebar : <Sidebar />}
|
||||
</div>
|
||||
</div>
|
||||
<SidebarAccountMenu
|
||||
@@ -363,23 +491,30 @@ export function Layout() {
|
||||
/>
|
||||
</div>
|
||||
) : (
|
||||
<div className="flex h-full flex-col shrink-0">
|
||||
<SidebarShell
|
||||
open={sidebarOpen}
|
||||
collapsed={collapsed}
|
||||
peeking={peeking}
|
||||
resizable
|
||||
onPanelMouseEnter={handlePanelPointerEnter}
|
||||
onPanelMouseLeave={handlePanelPointerLeave}
|
||||
onPanelFocusCapture={collapsed ? handlePanelFocus : undefined}
|
||||
onPanelBlurCapture={collapsed ? handlePanelBlur : undefined}
|
||||
>
|
||||
<div className="flex flex-1 min-h-0">
|
||||
<ResizableSidebarPane open={sidebarOpen} resizable className="h-full shrink-0">
|
||||
{isCompanySettingsRoute ? (
|
||||
<CompanySettingsSidebar />
|
||||
) : (
|
||||
companySidebar
|
||||
)}
|
||||
</ResizableSidebarPane>
|
||||
<Sidebar />
|
||||
</div>
|
||||
<SidebarAccountMenu
|
||||
deploymentMode={health?.deploymentMode}
|
||||
version={health?.version}
|
||||
/>
|
||||
</div>
|
||||
</SidebarShell>
|
||||
)}
|
||||
|
||||
{!isMobile && hasSecondarySidebar ? (
|
||||
<SecondarySidebar>{secondarySidebar}</SecondarySidebar>
|
||||
) : null}
|
||||
|
||||
<div className={cn("flex min-w-0 flex-col", isMobile ? "w-full" : "h-full flex-1")}>
|
||||
<div
|
||||
className={cn(
|
||||
|
||||
Reference in New Issue
Block a user