Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsxindex 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: StactiveTreePath,'',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.tsindex 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.tsindex 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,}) => {