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.

fix(web): keep the board scrollable while the issue detail panel is open (#288)

Ahmad Othman Ammar Adi1ebac8a6e024
diff --git a/apps/web/src/features/issue/components/detail/IssueDetail.tsx b/apps/web/src/features/issue/components/detail/IssueDetail.tsx
index f54168fa..ccb31db9 100644
--- a/apps/web/src/features/issue/components/detail/IssueDetail.tsx
+++ b/apps/web/src/features/issue/components/detail/IssueDetail.tsx
@@ -1,9 +1,10 @@
-import { useState } from 'react';
+import { useRef, useState } from 'react';
import { Maximize2, X } from 'lucide-react';
import { type ProjectDetail, type IssueDetail as IssueDetailRow } from '@/lib/api';
import IssueDetailContent from './IssueDetailContent';
import IssueActionsBar from '../actions/IssueActionsBar';
import { useExitOnEscape } from '@/hooks/useExitOnEscape';
+import { useExitOnClickOutside } from '../../hooks/useExitOnClickOutside';
import { Button } from '@/components/ui/button';
import { useTranslations } from 'next-intl';
@@ -25,19 +26,23 @@ export default function IssueDetail({
const t = useTranslations('issue');
const tCommon = useTranslations('common');
const [issue, setIssue] = useState<IssueDetailRow | null>(null);
+ const panelRef = useRef<HTMLDivElement>(null);
useExitOnEscape(onClose);
+ useExitOnClickOutside(panelRef, onClose);
return (
<div
// Above the floating chat button (z-40), which sits in the corner the panel's
// last-comment bubble uses.
- className="fixed inset-0 z-50 flex"
- onClick={(e) => e.target === e.currentTarget && onClose()}
+ className="pointer-events-none fixed inset-0 z-50 flex"
>
{/* No padding at the top: the sticky header carries it, so it can sit flush
against the panel edge with nothing showing above it. */}
- <div className="ms-auto flex h-full w-full flex-col overflow-y-auto border-s bg-card px-5 pt-0 pb-5 sm:w-[720px] sm:max-w-[92vw] sm:px-8">
+ <div
+ ref={panelRef}
+ className="pointer-events-auto ms-auto flex h-full w-full flex-col overflow-y-auto border-s bg-card px-5 pt-0 pb-5 sm:w-[720px] sm:max-w-[92vw] sm:px-8"
+ >
{/* The header stays at the top while the body scrolls under it. Negative
margins cancel the panel padding so its translucent, blurred backdrop
spans the full panel width. */}
diff --git a/apps/web/src/features/issue/hooks/useExitOnClickOutside.test.tsx b/apps/web/src/features/issue/hooks/useExitOnClickOutside.test.tsx
new file mode 100644
index 00000000..0d609f48
--- /dev/null
+++ b/apps/web/src/features/issue/hooks/useExitOnClickOutside.test.tsx
@@ -0,0 +1,173 @@
+import assert from 'node:assert/strict';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { act, useRef } from 'react';
+import type { Root } from 'react-dom/client';
+import { JSDOM } from 'jsdom';
+import { useExitOnClickOutside } from './useExitOnClickOutside';
+
+const replacedGlobals = [
+ 'window',
+ 'document',
+ 'navigator',
+ 'Node',
+ 'Element',
+ 'HTMLElement',
+ 'Event',
+ 'MouseEvent',
+ 'IS_REACT_ACT_ENVIRONMENT',
+] as const;
+
+// The app renders into one child of the body, so the surface and the page behind it
+// share a layer. An overlay is appended as a further child of the body.
+const markup =
+ '<!doctype html><div data-testid="app"><div id="root"></div>' +
+ '<div data-testid="page">Board</div></div>';
+
+let dom: JSDOM;
+let root: Root;
+let exits: number;
+let documentListeners: number;
+let originalGlobalDescriptors: Map<string, PropertyDescriptor | undefined>;
+
+function Surface() {
+ const ref = useRef<HTMLDivElement>(null);
+ useExitOnClickOutside(ref, () => {
+ exits += 1;
+ });
+
+ return (
+ <div ref={ref} data-testid="surface">
+ <button type="button" data-testid="inside">
+ Inside
+ </button>
+ </div>
+ );
+}
+
+function render() {
+ act(() => root.render(<Surface />));
+}
+
+function element(testId: string): HTMLElement {
+ const found = document.querySelector<HTMLElement>(`[data-testid="${testId}"]`);
+ assert.ok(found);
+ return found;
+}
+
+function dispatch(target: HTMLElement, type: string) {
+ act(() => target.dispatchEvent(new window.MouseEvent(type, { bubbles: true })));
+}
+
+function appendOverlayLayer(): HTMLElement {
+ const layer = document.createElement('div');
+ const target = document.createElement('button');
+ target.type = 'button';
+ layer.append(target);
+ document.body.append(layer);
+ return target;
+}
+
+beforeEach(async () => {
+ originalGlobalDescriptors = new Map(
+ replacedGlobals.map((name) => [name, Object.getOwnPropertyDescriptor(globalThis, name)]),
+ );
+ dom = new JSDOM(markup, { url: 'https://example.test/project/KEY' });
+ exits = 0;
+ documentListeners = 0;
+
+ // Counts the hook's own registrations so the unmount case fails without the cleanup.
+ const { document: doc } = dom.window;
+ const add = doc.addEventListener.bind(doc);
+ const remove = doc.removeEventListener.bind(doc);
+ const counted = (type: string) => type === 'click' || type === 'pointerdown';
+ type Listener = Parameters<typeof add>[1];
+ type Options = Parameters<typeof add>[2];
+ doc.addEventListener = (type: string, listener: Listener, options?: Options) => {
+ if (counted(type)) documentListeners += 1;
+ add(type, listener, options);
+ };
+ doc.removeEventListener = (type: string, listener: Listener, options?: Options) => {
+ if (counted(type)) documentListeners -= 1;
+ remove(type, listener, options);
+ };
+
+ Object.defineProperties(globalThis, {
+ window: { configurable: true, value: dom.window },
+ document: { configurable: true, value: doc },
+ navigator: { configurable: true, value: dom.window.navigator },
+ Node: { configurable: true, value: dom.window.Node },
+ Element: { configurable: true, value: dom.window.Element },
+ HTMLElement: { configurable: true, value: dom.window.HTMLElement },
+ Event: { configurable: true, value: dom.window.Event },
+ MouseEvent: { configurable: true, value: dom.window.MouseEvent },
+ IS_REACT_ACT_ENVIRONMENT: { configurable: true, value: true },
+ });
+
+ const { createRoot } = await import('react-dom/client');
+ const rootElement = doc.querySelector('#root');
+ assert.ok(rootElement);
+ root = createRoot(rootElement);
+});
+
+afterEach(() => {
+ act(() => root.unmount());
+ dom.window.close();
+ for (const [name, descriptor] of originalGlobalDescriptors) {
+ if (descriptor) Object.defineProperty(globalThis, name, descriptor);
+ else Reflect.deleteProperty(globalThis, name);
+ }
+});
+
+describe('useExitOnClickOutside', () => {
+ it('exits on a click on the page behind the surface', () => {
+ render();
+ dispatch(element('page'), 'click');
+ assert.equal(exits, 1);
+ });
+
+ it('stays on a click inside the surface', () => {
+ render();
+ dispatch(element('inside'), 'click');
+ assert.equal(exits, 0);
+ });
+
+ it('stays on a click in an overlay, which is its own child of the body', () => {
+ render();
+ dispatch(appendOverlayLayer(), 'click');
+ assert.equal(exits, 0);
+ });
+
+ // A field inside the surface saves on blur, which the browser fires between
+ // pointerdown and click. Exiting on the earlier event would drop the edit.
+ it('ignores a press, so a field saving on blur commits before the surface closes', () => {
+ render();
+ dispatch(element('page'), 'pointerdown');
+ dispatch(element('page'), 'mousedown');
+ assert.equal(exits, 0);
+ });
+
+ // A click reports the common ancestor of press and release, so selecting text in the
+ // surface and releasing over the page reports an element outside it.
+ it('stays when the gesture started inside the surface', () => {
+ render();
+ dispatch(element('inside'), 'pointerdown');
+ dispatch(element('page'), 'click');
+ assert.equal(exits, 0);
+ });
+
+ it('exits again on the next gesture that starts outside', () => {
+ render();
+ dispatch(element('inside'), 'pointerdown');
+ dispatch(element('page'), 'click');
+ dispatch(element('page'), 'pointerdown');
+ dispatch(element('page'), 'click');
+ assert.equal(exits, 1);
+ });
+
+ it('removes its document listeners when the surface unmounts', () => {
+ render();
+ assert.equal(documentListeners, 2);
+ act(() => root.render(null));
+ assert.equal(documentListeners, 0);
+ });
+});
diff --git a/apps/web/src/features/issue/hooks/useExitOnClickOutside.ts b/apps/web/src/features/issue/hooks/useExitOnClickOutside.ts
new file mode 100644
index 00000000..bf6a8740
--- /dev/null
+++ b/apps/web/src/features/issue/hooks/useExitOnClickOutside.ts
@@ -0,0 +1,49 @@
+import { useEffect, useRef, type RefObject } from 'react';
+
+// Closes a surface when a click lands outside it. The listener sits on the document
+// because the surface does not cover the viewport: the page behind it stays scrollable
+// and clickable, so there is no backdrop element to take the click.
+//
+// The layer check keeps the surface open under its own overlays. A popover, dropdown,
+// select, dialog or toast is its own child of the body, so none of them have to be named
+// here. That holds while the app renders into one child of the body: an element wrapping
+// the providers would put those overlays in the surface's own layer and a click in one
+// would close it.
+//
+// Click, not pointerdown: a field that saves on blur commits before the surface closes,
+// and a scrollbar drag or a right-click raises no click at all.
+//
+// A click reports the common ancestor of press and release, so selecting text in the
+// surface and releasing over the page reports an element outside it. The press decides:
+// a gesture that started inside the surface never exits, which is what keeps a selection
+// dragged out of it from closing it. The handler is kept in a ref so the listeners are
+// registered once and always call the latest onExit.
+export function useExitOnClickOutside(ref: RefObject<HTMLElement | null>, onExit: () => void) {
+ const onExitRef = useRef(onExit);
+ onExitRef.current = onExit;
+
+ useEffect(() => {
+ let pressedInside = false;
+
+ function onPointerDown(e: PointerEvent) {
+ const surface = ref.current;
+ pressedInside = !!surface && e.target instanceof Node && surface.contains(e.target);
+ }
+
+ function onClick(e: MouseEvent) {
+ const surface = ref.current;
+ if (pressedInside) return;
+ if (!surface || !(e.target instanceof Element)) return;
+ if (surface.contains(e.target)) return;
+ if (!surface.closest('body > *')?.contains(e.target)) return;
+ onExitRef.current();
+ }
+
+ document.addEventListener('pointerdown', onPointerDown, true);
+ document.addEventListener('click', onClick);
+ return () => {
+ document.removeEventListener('pointerdown', onPointerDown, true);
+ document.removeEventListener('click', onClick);
+ };
+ }, [ref]);
+}