Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(web-studio): make context tree keyboard-operable (#4301)

Onefly4738df667ea4
diff --git a/web-studio/package-lock.json b/web-studio/package-lock.json
index eac84dceb..ab4ff93e3 100644
--- a/web-studio/package-lock.json
+++ b/web-studio/package-lock.json
@@ -76,6 +76,7 @@
"@tanstack/router-plugin": "latest",
"@testing-library/dom": "^10.4.1",
"@testing-library/react": "^16.3.0",
+ "@testing-library/user-event": "^14.6.6",
"@types/node": "^22.10.2",
"@types/react": "^19.2.0",
"@types/react-dom": "^19.2.0",
@@ -4272,6 +4273,20 @@
}
}
},
+ "node_modules/@testing-library/user-event": {
+ "version": "14.6.6",
+ "resolved": "https://registry.npmjs.org/@testing-library/user-event/-/user-event-14.6.6.tgz",
+ "integrity": "sha512-Jbs9FpkkIDw8FgSc6kOVsOv8JuuqGAL7J4X1oot77JxAoDlkNn2GRkd0aYRVuQ+pVQAiHWVkE4rX/dkF5fBiCw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=12",
+ "npm": ">=6"
+ },
+ "peerDependencies": {
+ "@testing-library/dom": ">=7.21.4"
+ }
+ },
"node_modules/@tokenizer/inflate": {
"version": "0.4.1",
"resolved": "https://registry.npmjs.org/@tokenizer/inflate/-/inflate-0.4.1.tgz",
diff --git a/web-studio/package.json b/web-studio/package.json
index 4b0450611..81647098f 100644
--- a/web-studio/package.json
+++ b/web-studio/package.json
@@ -86,6 +86,7 @@
"@tanstack/router-plugin": "latest",
"@testing-library/dom": "^10.4.1",
"@testing-library/react": "^16.3.0",
+ "@testing-library/user-event": "^14.6.6",
"@types/node": "^22.10.2",
"@types/react": "^19.2.0",
"@types/react-dom": "^19.2.0",
diff --git a/web-studio/src/i18n/locales/en/activity.ts b/web-studio/src/i18n/locales/en/activity.ts
index 632f65d7a..31c08e881 100644
--- a/web-studio/src/i18n/locales/en/activity.ts
+++ b/web-studio/src/i18n/locales/en/activity.ts
@@ -156,7 +156,9 @@ const activity = {
title: 'Context tree',
addResource: 'Add resource',
abstractLevel: 'L0',
+ collapseDirectory: 'Collapse {{name}}',
empty: 'empty',
+ expandDirectory: 'Expand {{name}}',
loading: 'loading',
overviewLevel: 'L1',
search: 'Search context',
diff --git a/web-studio/src/i18n/locales/zh-CN/activity.ts b/web-studio/src/i18n/locales/zh-CN/activity.ts
index 57712e007..9299cfce3 100644
--- a/web-studio/src/i18n/locales/zh-CN/activity.ts
+++ b/web-studio/src/i18n/locales/zh-CN/activity.ts
@@ -148,7 +148,9 @@ const activity = {
title: '上下文树',
addResource: '添加资源',
abstractLevel: 'L0',
+ collapseDirectory: '收起 {{name}}',
empty: '空',
+ expandDirectory: '展开 {{name}}',
loading: '加载中',
overviewLevel: 'L1',
search: '搜索上下文',
diff --git a/web-studio/src/routes/playground/-components/context-explorer.test.tsx b/web-studio/src/routes/playground/-components/context-explorer.test.tsx
new file mode 100644
index 000000000..e65cb18c0
--- /dev/null
+++ b/web-studio/src/routes/playground/-components/context-explorer.test.tsx
@@ -0,0 +1,191 @@
+// @vitest-environment jsdom
+
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { VikingFsEntry } from '#/routes/resources/-types/viking-fm'
+
+import { ContextTree } from './context-explorer'
+
+const { useVikingFsListMock } = vi.hoisted(() => ({
+ useVikingFsListMock: vi.fn(),
+}))
+
+vi.mock('#/routes/resources/-hooks/viking-fm', () => ({
+ useVikingFsList: useVikingFsListMock,
+}))
+
+vi.mock('react-i18next', () => ({
+ useTranslation: () => ({
+ t: (key: string, options?: { name?: string }) => {
+ if (key === 'explorer.title') return 'Context tree'
+ if (key === 'explorer.expandDirectory') {
+ return `Expand ${options?.name}`
+ }
+ if (key === 'explorer.collapseDirectory') {
+ return `Collapse ${options?.name}`
+ }
+ if (key === 'explorer.namespaces.resources') {
+ return 'External resources the Agent can reference'
+ }
+ return key
+ },
+ }),
+}))
+
+const directory: VikingFsEntry = {
+ abstract: '',
+ isDir: true,
+ modTime: '2026-08-24 12:00',
+ modTimestamp: 1,
+ name: 'resources',
+ overview: '',
+ size: '',
+ sizeBytes: null,
+ uri: 'viking://resources',
+}
+
+const file: VikingFsEntry = {
+ abstract: '',
+ isDir: false,
+ modTime: '2026-08-24 12:00',
+ modTimestamp: 1,
+ name: 'guide.md',
+ overview: '',
+ size: '1 KB',
+ sizeBytes: 1024,
+ uri: 'viking://resources/guide.md',
+}
+
+beforeEach(() => {
+ useVikingFsListMock.mockImplementation((uri: string) => ({
+ data: { entries: uri === 'viking://' ? [directory] : [file] },
+ isError: false,
+ isLoading: false,
+ }))
+ vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+ callback(0)
+ return 1
+ })
+ Element.prototype.scrollIntoView = vi.fn()
+})
+
+afterEach(() => {
+ cleanup()
+ vi.clearAllMocks()
+ vi.unstubAllGlobals()
+})
+
+function renderTree({
+ currentUri = 'viking://',
+ expandedKeys = new Set<string>(),
+ selectedFileUri = null,
+}: {
+ currentUri?: string
+ expandedKeys?: Set<string>
+ selectedFileUri?: string | null
+} = {}) {
+ const onExpandedKeysChange = vi.fn()
+ const onSelectDirectory = vi.fn()
+ const onSelectFile = vi.fn()
+
+ render(
+ <ContextTree
+ currentUri={currentUri}
+ expandedKeys={expandedKeys}
+ onExpandedKeysChange={onExpandedKeysChange}
+ onSelectDirectory={onSelectDirectory}
+ onSelectFile={onSelectFile}
+ selectedFileUri={selectedFileUri}
+ />,
+ )
+
+ return { onExpandedKeysChange, onSelectDirectory, onSelectFile }
+}
+
+describe('ContextTree keyboard semantics', () => {
+ it('renders native controls in a labelled, nested list', () => {
+ renderTree({
+ expandedKeys: new Set([directory.uri]),
+ selectedFileUri: file.uri,
+ })
+
+ const rootList = screen.getByRole('list', { name: 'Context tree' })
+ const disclosure = screen.getByRole('button', {
+ name: 'Collapse resources',
+ })
+ const directorySelection = screen.getByRole('button', {
+ name: 'resources',
+ })
+ const fileSelection = screen.getByRole('button', { name: 'guide.md' })
+
+ expect(rootList.contains(directorySelection)).toBe(true)
+ expect(disclosure.getAttribute('aria-expanded')).toBe('true')
+ expect(disclosure.getAttribute('title')).toBe('Collapse resources')
+ expect(directorySelection.tabIndex).toBe(0)
+ expect(fileSelection.tabIndex).toBe(0)
+ expect(fileSelection.getAttribute('aria-current')).toBe('location')
+
+ fileSelection.focus()
+ expect(document.activeElement).toBe(fileSelection)
+
+ const directoryItem = directorySelection.closest('li')
+ const childList = fileSelection.closest('ul')
+ expect(directoryItem).toBeTruthy()
+ expect(childList?.parentElement).toBe(directoryItem)
+ })
+
+ it('activates disclosure with Enter without selecting the directory', async () => {
+ const user = userEvent.setup()
+ const { onExpandedKeysChange, onSelectDirectory, onSelectFile } =
+ renderTree()
+
+ const disclosure = screen.getByRole('button', {
+ name: 'Expand resources',
+ })
+ expect(disclosure.getAttribute('aria-expanded')).toBe('false')
+
+ await user.tab()
+ expect(document.activeElement).toBe(disclosure)
+ await user.keyboard('{Enter}')
+
+ expect(onExpandedKeysChange).toHaveBeenCalledOnce()
+ expect(onExpandedKeysChange.mock.calls[0]?.[0]).toEqual(
+ new Set([directory.uri]),
+ )
+ expect(onSelectDirectory).not.toHaveBeenCalled()
+ expect(onSelectFile).not.toHaveBeenCalled()
+ })
+
+ it('selects directories with Space and files with Enter', async () => {
+ const user = userEvent.setup()
+ const { onExpandedKeysChange, onSelectDirectory, onSelectFile } =
+ renderTree({ expandedKeys: new Set([directory.uri]) })
+
+ const disclosure = screen.getByRole('button', {
+ name: 'Collapse resources',
+ })
+ const directorySelection = screen.getByRole('button', {
+ name: 'resources',
+ })
+ const fileSelection = screen.getByRole('button', { name: 'guide.md' })
+
+ await user.tab()
+ expect(document.activeElement).toBe(disclosure)
+ await user.tab()
+ expect(document.activeElement).toBe(directorySelection)
+ await user.keyboard(' ')
+ await user.tab()
+ expect(document.activeElement).toBe(fileSelection)
+ await user.keyboard('{Enter}')
+
+ expect(onSelectDirectory).toHaveBeenCalledOnce()
+ expect(onSelectDirectory).toHaveBeenCalledWith(
+ expect.objectContaining({ uri: directory.uri }),
+ )
+ expect(onSelectFile).toHaveBeenCalledOnce()
+ expect(onSelectFile).toHaveBeenCalledWith(file)
+ expect(onExpandedKeysChange).not.toHaveBeenCalled()
+ })
+})
diff --git a/web-studio/src/routes/playground/-components/context-explorer.tsx b/web-studio/src/routes/playground/-components/context-explorer.tsx
index 65bd60d65..2a41a6580 100644
--- a/web-studio/src/routes/playground/-components/context-explorer.tsx
+++ b/web-studio/src/routes/playground/-components/context-explorer.tsx
@@ -25,6 +25,8 @@ const TREE_INDENT_WIDTH = 16
const TREE_ROW_PADDING = 6
const TREE_GUIDE_OFFSET = 8
const TREE_CHILD_CONTENT_OFFSET = 26
+const TREE_CONTROL_SIZE = 16
+const TREE_CONTROL_GAP = 6
export function ContextExplorerHeader({
activeTaskCount,
@@ -188,28 +190,34 @@ export function ContextTree({
{t('explorer.empty')}
</div>
) : (
- namespaces.map((entry) => {
- const normalizedName = entry.name.toLowerCase()
- const descriptionKey = NAMESPACE_DESCRIPTION_KEYS[normalizedName]
+ <ul
+ role="list"
+ aria-label={t('explorer.title')}
+ className="m-0 min-w-0 list-none p-0"
+ >
+ {namespaces.map((entry) => {
+ const normalizedName = entry.name.toLowerCase()
+ const descriptionKey = NAMESPACE_DESCRIPTION_KEYS[normalizedName]
- return (
- <ContextTreeNode
- key={entry.uri}
- currentUri={currentUri}
- entry={{
- ...entry,
- name: entry.name,
- abstract: descriptionKey ? t(descriptionKey) : entry.abstract,
- }}
- expandedKeys={expandedKeys}
- level={0}
- onExpandedKeysChange={onExpandedKeysChange}
- onSelectDirectory={onSelectDirectory}
- onSelectFile={onSelectFile}
- selectedFileUri={selectedFileUri}
- />
- )
- })
+ return (
+ <ContextTreeNode
+ key={entry.uri}
+ currentUri={currentUri}
+ entry={{
+ ...entry,
+ name: entry.name,
+ abstract: descriptionKey ? t(descriptionKey) : entry.abstract,
+ }}
+ expandedKeys={expandedKeys}
+ level={0}
+ onExpandedKeysChange={onExpandedKeysChange}
+ onSelectDirectory={onSelectDirectory}
+ onSelectFile={onSelectFile}
+ selectedFileUri={selectedFileUri}
+ />
+ )
+ })}
+ </ul>
)}
</div>
)
@@ -265,6 +273,11 @@ export function ContextTreeNode({
const isSelected = isDirSelected || isFileSelected
const namespaceHint = level === 0 ? entry.abstract : ''
const rowRef = useRef<HTMLDivElement>(null)
+ const disclosureLabel = entry.isDir
+ ? t(isOpen ? 'explorer.collapseDirectory' : 'explorer.expandDirectory', {
+ name: entry.name,
+ })
+ : ''
const shouldLoadChildren = entry.isDir && isOpen
const listQuery = useVikingFsList(
entry.uri,
@@ -311,85 +324,99 @@ export function ContextTreeNode({
}, [entry, isOpen, isSelected, onSelectDirectory, onSelectFile, toggle])
return (
- <div className="relative min-w-0">
+ <li className="relative min-w-0 list-none">
<TreeIndentGuides level={level} />
<div
ref={rowRef}
className={cn(
- 'group relative z-10 flex h-7 cursor-pointer select-none items-center gap-1.5 rounded-md px-1.5 text-xs transition-colors',
+ 'group relative z-10 h-7 select-none rounded-md text-xs transition-colors',
isSelected
? 'bg-muted text-foreground'
: 'text-muted-foreground hover:bg-muted/55 hover:text-foreground',
)}
- style={{ paddingLeft: treeRowPadding(level) }}
- onClick={select}
>
{entry.isDir ? (
<button
type="button"
- className="inline-flex size-4 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors group-hover:text-foreground"
- onClick={(event) => {
- event.stopPropagation()
- toggle()
- }}
+ aria-expanded={isOpen}
+ aria-label={disclosureLabel}
+ title={disclosureLabel}
+ className="absolute top-1/2 z-20 inline-flex size-4 -translate-y-1/2 cursor-pointer items-center justify-center rounded-sm text-muted-foreground outline-none transition-colors group-hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
+ style={{ left: treeRowPadding(level) }}
+ onClick={toggle}
>
<ChevronRightIcon
+ aria-hidden="true"
className={cn(
'size-3 transition-transform',
isOpen && 'rotate-90',
)}
/>
</button>
- ) : (
- <span className="size-4 shrink-0" />
- )}
- {entry.isDir ? (
- <FolderIcon
+ ) : null}
+ <button
+ type="button"
+ aria-label={entry.name}
+ aria-current={isSelected ? 'location' : undefined}
+ className="absolute inset-0 z-10 flex min-w-0 cursor-pointer items-center gap-1.5 rounded-md pr-1.5 text-left outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
+ style={{ paddingLeft: treeSelectionPadding(level, entry.isDir) }}
+ onClick={select}
+ >
+ {!entry.isDir ? (
+ <span aria-hidden="true" className="size-4 shrink-0" />
+ ) : null}
+ {entry.isDir ? (
+ <FolderIcon
+ aria-hidden="true"
+ className={cn(
+ 'size-4 shrink-0',
+ isOpen ? 'text-primary/80' : 'text-muted-foreground',
+ )}
+ />
+ ) : (
+ <FileTextIcon
+ aria-hidden="true"
+ className="size-4 shrink-0 text-muted-foreground"
+ />
+ )}
+ <span
className={cn(
- 'size-4 shrink-0',
- isOpen ? 'text-primary/80' : 'text-muted-foreground',
+ 'truncate',
+ namespaceHint ? 'shrink-0 text-foreground' : 'min-w-0 flex-1',
)}
- />
- ) : (
- <FileTextIcon className="size-4 shrink-0 text-muted-foreground" />
- )}
- <span
- className={cn(
- 'truncate',
- namespaceHint ? 'shrink-0 text-foreground' : 'min-w-0 flex-1',
- )}
- >
- {entry.name}
- </span>
- {namespaceHint ? (
- <span className="min-w-0 flex-1 truncate font-sans text-xs text-muted-foreground">
- {namespaceHint}
- </span>
- ) : null}
- {entry.name === '_abstract.md' ? (
- <span className="shrink-0 rounded bg-muted px-1 font-sans text-[10px] text-muted-foreground">
- {t('explorer.abstractLevel')}
- </span>
- ) : entry.name === '_overview.md' ? (
- <span className="shrink-0 rounded bg-muted px-1 font-sans text-[10px] text-muted-foreground">
- {t('explorer.overviewLevel')}
+ >
+ {entry.name}
</span>
- ) : null}
+ {namespaceHint ? (
+ <span className="min-w-0 flex-1 truncate font-sans text-xs text-muted-foreground">
+ {namespaceHint}
+ </span>
+ ) : null}
+ {entry.name === '_abstract.md' ? (
+ <span className="shrink-0 rounded bg-muted px-1 font-sans text-[10px] text-muted-foreground">
+ {t('explorer.abstractLevel')}
+ </span>
+ ) : entry.name === '_overview.md' ? (
+ <span className="shrink-0 rounded bg-muted px-1 font-sans text-[10px] text-muted-foreground">
+ {t('explorer.overviewLevel')}
+ </span>
+ ) : null}
+ </button>
</div>
{entry.isDir && isOpen ? (
- <div className="relative min-w-0">
- {listQuery.isLoading ? (
- <div
- className="relative flex h-7 items-center gap-2 px-1.5 text-xs text-muted-foreground"
- style={{ paddingLeft: treeChildContentPadding(level) }}
- >
- <TreeIndentGuides level={level + 1} />
- <Loader2Icon className="size-3 animate-spin" />
- {t('explorer.loading')}
- </div>
- ) : children.length > 0 ? (
- children.map((child) => (
+ listQuery.isLoading ? (
+ <div
+ className="relative flex h-7 items-center gap-2 px-1.5 text-xs text-muted-foreground"
+ style={{ paddingLeft: treeChildContentPadding(level) }}
+ >
+ <TreeIndentGuides level={level + 1} />
+ <Loader2Icon className="size-3 animate-spin" />
+ {t('explorer.loading')}
+ </div>
+ ) : children.length > 0 ? (
+ <ul role="list" className="m-0 min-w-0 list-none p-0">
+ {children.map((child) => (
<ContextTreeNode
key={child.uri}
currentUri={currentUri}
@@ -401,19 +428,19 @@ export function ContextTreeNode({
onSelectFile={onSelectFile}
selectedFileUri={selectedFileUri}
/>
- ))
- ) : (
- <div
- className="relative h-7 px-1.5 text-xs leading-7 text-muted-foreground/60"
- style={{ paddingLeft: treeChildContentPadding(level) }}
- >
- <TreeIndentGuides level={level + 1} />
- {t('explorer.empty')}
- </div>
- )}
- </div>
+ ))}
+ </ul>
+ ) : (
+ <div
+ className="relative h-7 px-1.5 text-xs leading-7 text-muted-foreground/60"
+ style={{ paddingLeft: treeChildContentPadding(level) }}
+ >
+ <TreeIndentGuides level={level + 1} />
+ {t('explorer.empty')}
+ </div>
+ )
) : null}
- </div>
+ </li>
)
}
@@ -441,6 +468,13 @@ export function treeRowPadding(level: number): string {
return `${level * TREE_INDENT_WIDTH + TREE_ROW_PADDING}px`
}
+function treeSelectionPadding(level: number, hasDisclosure: boolean): string {
+ const disclosureOffset = hasDisclosure
+ ? TREE_CONTROL_SIZE + TREE_CONTROL_GAP
+ : 0
+ return `${level * TREE_INDENT_WIDTH + TREE_ROW_PADDING + disclosureOffset}px`
+}
+
export function treeChildContentPadding(level: number): string {
return `${(level + 1) * TREE_INDENT_WIDTH + TREE_CHILD_CONTENT_OFFSET}px`
}