Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Keep sidebar keyboard focus on the row the user focused (#4808)

Nick Gomez3f6ccbaab736
diff --git a/.changeset/sidebar-keyboard-focus-survives-file-changes.md b/.changeset/sidebar-keyboard-focus-survives-file-changes.md
new file mode 100644
index 000000000..81be1413d
--- /dev/null
+++ b/.changeset/sidebar-keyboard-focus-survives-file-changes.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Sidebar keyboard focus no longer jumps to the open document when a background file change lands, so arrow keys and shortcuts keep acting on the row you chose. Renaming the open document still moves focus, because that changes which document is active.
diff --git a/packages/app/src/components/FileTree.selection-mirror.dom.test.tsx b/packages/app/src/components/FileTree.selection-mirror.dom.test.tsx
index 823add82a..689d44444 100644
--- a/packages/app/src/components/FileTree.selection-mirror.dom.test.tsx
+++ b/packages/app/src/components/FileTree.selection-mirror.dom.test.tsx
@@ -1,9 +1,11 @@
/** Exercises `render` + `userEvent` under the jsdom substrate (precedent #43). */
+import { FileTree } from '@pierre/trees';
import { cleanup, render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { useRef, useState } from 'react';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { revealActiveRow } from './file-tree-reveal';
import { useSelectionMirror } from './use-selection-mirror';
interface StubItem {
@@ -18,14 +20,19 @@ interface StubItem {
getFocusCount: () => number;
}
+type ExpansionOnlyModel = Pick<StubModel, 'getItem' | 'getSelectedPaths' | 'getFocusedPath'>;
+
interface StubModel {
getItem: (path: string) => StubItem | null;
getSelectedPaths: () => string[];
+ getFocusedPath: () => string | null;
+ addPath: (path: string) => void;
}
function makeStubModel(paths: string[]): StubModel {
const items = new Map<string, StubItem>();
- for (const p of paths) {
+ let focusedPath: string | null = null;
+ const addPath = (p: string) => {
let selected = false;
let focusCount = 0;
items.set(p, {
@@ -41,10 +48,14 @@ function makeStubModel(paths: string[]): StubModel {
expand: () => {},
focus: () => {
focusCount += 1;
+ focusedPath = p;
},
isDirectory: () => false,
getFocusCount: () => focusCount,
});
+ };
+ for (const p of paths) {
+ addPath(p);
}
return {
getItem: (path: string) => items.get(path) ?? null,
@@ -52,11 +63,20 @@ function makeStubModel(paths: string[]): StubModel {
Array.from(items.entries())
.filter(([, it]) => it.isSelected())
.map(([p]) => p),
+ getFocusedPath: () => focusedPath,
+ addPath,
};
}
-function Harness({ initialPath, model }: { initialPath: string | null; model: StubModel }) {
+interface HarnessModel {
+ getItem: (path: string) => unknown;
+ getSelectedPaths: () => readonly string[];
+ getFocusedPath: () => string | null;
+}
+
+function Harness({ initialPath, model }: { initialPath: string | null; model: HarnessModel }) {
const [activeTreePath, setActiveTreePath] = useState<string | null>(initialPath);
+ const [treePathsSignature, setTreePathsSignature] = useState('initial');
const suppressSelectionRef = useRef(false);
useSelectionMirror(
@@ -65,10 +85,18 @@ function Harness({ initialPath, model }: { initialPath: string | null; model: St
activeTreePath,
'',
suppressSelectionRef,
+ treePathsSignature,
);
return (
<>
+ <button
+ type="button"
+ data-testid="repopulate"
+ onClick={() => setTreePathsSignature((previous) => `${previous}+`)}
+ >
+ repopulate
+ </button>
<button type="button" data-testid="set-A" onClick={() => setActiveTreePath('A.md')}>
A
</button>
@@ -186,12 +214,13 @@ describe('FileTree selection-mirror (Tier-3 mount)', () => {
},
],
]);
- const model: StubModel = {
+ const model: ExpansionOnlyModel = {
getItem: (path: string) => items.get(path) ?? null,
getSelectedPaths: () =>
Array.from(items.entries())
.filter(([, it]) => it.isSelected())
.map(([p]) => p),
+ getFocusedPath: () => null,
};
function PartiallyHiddenHarness() {
const suppressSelectionRef = useRef(false);
@@ -247,9 +276,10 @@ describe('FileTree selection-mirror (Tier-3 mount)', () => {
},
],
]);
- const model: StubModel = {
+ const model: ExpansionOnlyModel = {
getItem: (path: string) => items.get(path) ?? null,
getSelectedPaths: () => [],
+ getFocusedPath: () => null,
};
function AncestorHarness() {
const suppressSelectionRef = useRef(false);
@@ -292,6 +322,150 @@ describe('FileTree selection-mirror (Tier-3 mount)', () => {
expect(model.getSelectedPaths()).toEqual(['A.md']);
});
+ test('a repopulation re-run leaves keyboard focus on the row the user focused', async () => {
+ const user = userEvent.setup();
+ const model = makeStubModel(['A.md', 'B.md', 'folder/']);
+ render(<Harness initialPath="A.md" model={model} />);
+
+ model.getItem('folder/')?.focus();
+ expect(model.getFocusedPath()).toBe('folder/');
+ const activeFocusCountBefore = model.getItem('A.md')?.getFocusCount();
+
+ await user.click(screen.getByTestId('repopulate'));
+
+ expect(model.getFocusedPath()).toBe('folder/');
+ expect(model.getItem('A.md')?.getFocusCount()).toBe(activeFocusCountBefore);
+ expect(model.getSelectedPaths()).toEqual(['A.md']);
+ });
+
+ test('a true activation still claims focus even while another row holds it', async () => {
+ const user = userEvent.setup();
+ const model = makeStubModel(['A.md', 'B.md', 'folder/']);
+ render(<Harness initialPath="A.md" model={model} />);
+
+ model.getItem('folder/')?.focus();
+ expect(model.getFocusedPath()).toBe('folder/');
+
+ await user.click(screen.getByTestId('set-B'));
+
+ expect(model.getFocusedPath()).toBe('B.md');
+ });
+
+ test('a real drop of the focused row leaves focus where @pierre/trees resolves it', async () => {
+ const user = userEvent.setup();
+ const model = new FileTree({ paths: ['A.md', 'afolder/x.md', 'zfolder/sibling.md'] });
+ model.getItem('zfolder/')?.expand();
+ render(<Harness initialPath="A.md" model={model} />);
+
+ model.getItem('zfolder/sibling.md')?.focus();
+ expect(model.getFocusedPath()).toBe('zfolder/sibling.md');
+
+ model.resetPaths(['A.md', 'afolder/x.md']);
+ const fallback = model.getFocusedPath();
+ expect(fallback).not.toBeNull();
+ expect(fallback).not.toBe('A.md');
+
+ await user.click(screen.getByTestId('repopulate'));
+
+ expect(model.getFocusedPath()).toBe(fallback);
+ expect(model.getSelectedPaths()).toEqual(['A.md']);
+ });
+
+ test('an activation whose row appears only on a later repopulation claims keyboard focus', async () => {
+ const user = userEvent.setup();
+ const model = makeStubModel(['folder/', 'B.md']);
+ render(<Harness initialPath="A.md" model={model} />);
+
+ model.getItem('folder/')?.focus();
+ expect(model.getFocusedPath()).toBe('folder/');
+ expect(model.getSelectedPaths()).toEqual([]);
+
+ model.addPath('A.md');
+ await user.click(screen.getByTestId('repopulate'));
+
+ expect(model.getFocusedPath()).toBe('A.md');
+ expect(model.getSelectedPaths()).toEqual(['A.md']);
+ });
+
+ test('re-activating a document after the active path was cleared claims keyboard focus', async () => {
+ const user = userEvent.setup();
+ const model = makeStubModel(['folder/', 'A.md', 'B.md']);
+ render(<Harness initialPath="A.md" model={model} />);
+
+ await user.click(screen.getByTestId('set-null'));
+ expect(model.getSelectedPaths()).toEqual([]);
+
+ model.getItem('folder/')?.focus();
+ expect(model.getFocusedPath()).toBe('folder/');
+
+ await user.click(screen.getByTestId('set-A'));
+
+ expect(model.getFocusedPath()).toBe('A.md');
+ expect(model.getSelectedPaths()).toEqual(['A.md']);
+ });
+
+ test('a real drop of a nested focused row leaves focus on the surviving folder, not the first row', async () => {
+ const user = userEvent.setup();
+ const model = new FileTree({
+ paths: ['A.md', 'afolder/x.md', 'zfolder/nested.md', 'zfolder/sibling.md'],
+ });
+ model.getItem('afolder/')?.expand();
+ model.getItem('zfolder/')?.expand();
+ render(<Harness initialPath="A.md" model={model} />);
+
+ model.getItem('zfolder/nested.md')?.focus();
+ expect(model.getFocusedPath()).toBe('zfolder/nested.md');
+
+ model.resetPaths(['A.md', 'afolder/x.md', 'zfolder/sibling.md']);
+ const fallback = model.getFocusedPath();
+ expect(fallback).toBe('zfolder/');
+
+ await user.click(screen.getByTestId('repopulate'));
+
+ expect(model.getFocusedPath()).toBe(fallback);
+ expect(model.getSelectedPaths()).toEqual(['A.md']);
+ });
+
+ test('returning to a document after one with no tree row claims keyboard focus', async () => {
+ const user = userEvent.setup();
+ const model = makeStubModel(['A.md', 'B.md', 'folder/']);
+ render(<Harness initialPath="A.md" model={model} />);
+
+ model.getItem('folder/')?.focus();
+ expect(model.getFocusedPath()).toBe('folder/');
+
+ await user.click(screen.getByTestId('set-absent'));
+ await user.click(screen.getByTestId('set-A'));
+
+ expect(model.getFocusedPath()).toBe('A.md');
+ expect(model.getSelectedPaths()).toEqual(['A.md']);
+ });
+
+ test('a suppressed claim also withholds the active row reveal, and an activation restores it', async () => {
+ const user = userEvent.setup();
+ const model = makeStubModel(['A.md', 'B.md', 'folder/']);
+ render(<Harness initialPath="A.md" model={model} />);
+
+ model.getItem('folder/')?.focus();
+ await user.click(screen.getByTestId('repopulate'));
+
+ const scrollAfterRepopulation = vi.fn();
+ revealActiveRow(
+ { getFocusedPath: () => model.getFocusedPath(), scrollToPath: scrollAfterRepopulation },
+ 'A.md',
+ );
+ expect(scrollAfterRepopulation).not.toHaveBeenCalled();
+
+ await user.click(screen.getByTestId('set-B'));
+
+ const scrollAfterActivation = vi.fn();
+ revealActiveRow(
+ { getFocusedPath: () => model.getFocusedPath(), scrollToPath: scrollAfterActivation },
+ 'B.md',
+ );
+ expect(scrollAfterActivation).toHaveBeenCalledTimes(1);
+ });
+
test('unmount drains the queueMicrotask cleanup without React post-unmount warning', async () => {
const model = makeStubModel(['A.md', 'B.md', 'C.md']);
const { unmount } = render(<Harness initialPath="A.md" model={model} />);
diff --git a/packages/app/src/components/use-selection-mirror.ts b/packages/app/src/components/use-selection-mirror.ts
index 12e68c6ec..35a242ad4 100644
--- a/packages/app/src/components/use-selection-mirror.ts
+++ b/packages/app/src/components/use-selection-mirror.ts
@@ -1,5 +1,5 @@
import type { FileTreeDirectoryHandle, FileTree as PierreFileTreeModel } from '@pierre/trees';
-import { type RefObject, useEffect } from 'react';
+import { type RefObject, useEffect, useRef } from 'react';
export function asDirectoryHandle(
item: ReturnType<PierreFileTreeModel['getItem']>,
@@ -22,6 +22,14 @@ function selectOnlyTreeItem(
}
}
+function keyboardFocusIsHeldByAnotherRow(
+ model: Pick<PierreFileTreeModel, 'getFocusedPath'>,
+ activeTreePath: string,
+): boolean {
+ const focusedPath = model.getFocusedPath();
+ return focusedPath !== null && focusedPath !== activeTreePath;
+}
+
function deselectAllTreeItems(model: PierreFileTreeModel): void {
for (const selectedPath of model.getSelectedPaths()) {
model.getItem(selectedPath)?.deselect();
@@ -35,6 +43,8 @@ export function useSelectionMirror(
suppressSelectionRef: RefObject<boolean>,
treePathsSignature: string,
): void {
+ const lastActiveTreePathRef = useRef<string | null>(null);
+
// biome-ignore lint/correctness/useExhaustiveDependencies: `treePathsSignature` is a re-run trigger, not a value read in the closure — it forces the mirror to re-assert selection after `model.resetPaths` rebuilds the tree. Sibling pattern: the reset + reveal-active-row effects in FileTree.tsx.
useEffect(() => {
const releaseSelectionSuppression = () => {
@@ -44,6 +54,7 @@ export function useSelectionMirror(
};
suppressSelectionRef.current = true;
if (!activeTreePath) {
+ lastActiveTreePathRef.current = null;
deselectAllTreeItems(model);
releaseSelectionSuppression();
return;
@@ -59,17 +70,26 @@ export function useSelectionMirror(
}
const item = model.getItem(activeTreePath);
if (!item) {
+ lastActiveTreePathRef.current = null;
deselectAllTreeItems(model);
releaseSelectionSuppression();
return;
}
- if (model.getSelectedPaths().length > 1 && item.isSelected()) {
+ const activeTreePathChanged = lastActiveTreePathRef.current !== activeTreePath;
+ lastActiveTreePathRef.current = activeTreePath;
+ const claimKeyboardFocus = () => {
+ if (!activeTreePathChanged && keyboardFocusIsHeldByAnotherRow(model, activeTreePath)) {
+ return;
+ }
item.focus();
+ };
+ if (model.getSelectedPaths().length > 1 && item.isSelected()) {
+ claimKeyboardFocus();
releaseSelectionSuppression();
return;
}
selectOnlyTreeItem(model, item);
- item.focus();
+ claimKeyboardFocus();
releaseSelectionSuppression();
}, [
activeAncestorTreePathsSignature,
diff --git a/packages/app/tests/stress/reveal-on-activate.e2e.ts b/packages/app/tests/stress/reveal-on-activate.e2e.ts
index 92b5ba364..b26a19b02 100644
--- a/packages/app/tests/stress/reveal-on-activate.e2e.ts
+++ b/packages/app/tests/stress/reveal-on-activate.e2e.ts
@@ -53,6 +53,29 @@ async function gotoAndAwaitTree(page: Page, path: string): Promise<void> {
await expect(sidebar(page).getByRole('treeitem').first()).toBeVisible({ timeout: 30_000 });
}
+async function focusIsInsideFileTree(page: Page, survivingRowPath: string): Promise<boolean> {
+ return page.evaluate((rowPath) => {
+ let element: Element | null = document.activeElement;
+ while (element?.shadowRoot?.activeElement != null) {
+ element = element.shadowRoot.activeElement;
+ }
+ if (element?.closest('[role="tree"]') == null) return false;
+ const root = element.getRootNode();
+ if (!(root instanceof ShadowRoot)) return false;
+ return root.querySelector(`[data-item-path="${rowPath}"]`) != null;
+ }, survivingRowPath);
+}
+
+async function focusedRowLabel(page: Page): Promise<string | null> {
+ return page.evaluate(() => {
+ let element: Element | null = document.activeElement;
+ while (element?.shadowRoot?.activeElement != null) {
+ element = element.shadowRoot.activeElement;
+ }
+ return element?.getAttribute('aria-label') ?? null;
+ });
+}
+
async function expandFolder(page: Page) {
await folderRow(page).focus();
await folderRow(page).press('ArrowRight');
@@ -197,6 +220,44 @@ test('activation does not steal focus from the editor', async ({ page }) => {
expect(focusInSidebar).toBe(false);
});
+test('a background page-list change leaves keyboard focus on the row the user focused', async ({
+ page,
+ api,
+}) => {
+ await gotoAndAwaitTree(page, `/#/test-doc`);
+ await fileRow(page, 'test-doc.md').waitFor({ state: 'visible', timeout: 15_000 });
+
+ await expect(folderRow(page)).toHaveAttribute('aria-expanded', 'false');
+ await folderRow(page).focus();
+ await expect.poll(() => focusedRowLabel(page)).toBe('sidebar-folder');
+
+ await api.createPage('zz-background-doc.md');
+ await fileRow(page, 'zz-background-doc.md').waitFor({ state: 'visible', timeout: 15_000 });
+
+ await expect.poll(() => focusedRowLabel(page)).toBe('sidebar-folder');
+
+ await page.keyboard.press('ArrowRight');
+ await expect(folderRow(page)).toHaveAttribute('aria-expanded', 'true');
+});
+
+test('a background deletion of the focused row leaves keyboard focus inside the tree', async ({
+ page,
+ workerServer,
+}) => {
+ await gotoAndAwaitTree(page, `/#/test-doc`);
+ await fileRow(page, 'test-doc.md').waitFor({ state: 'visible', timeout: 15_000 });
+ await expandFolder(page);
+ await fileRow(page, 'nested-doc.md').waitFor({ state: 'visible', timeout: 15_000 });
+
+ await fileRow(page, 'nested-doc.md').focus();
+ await expect.poll(() => focusedRowLabel(page)).toBe('nested-doc.md');
+
+ await deletePathIfExists(workerServer.baseURL, 'file', 'sidebar-folder/nested-doc');
+ await fileRow(page, 'nested-doc.md').waitFor({ state: 'detached', timeout: 15_000 });
+
+ await expect.poll(() => focusIsInsideFileTree(page, 'sidebar-folder/')).toBe(true);
+});
+
test('hovering a sidebar row surfaces its full relative path as a title (VS Code parity)', async ({
page,
}) => {