340 lines
13 KiB
Markdown
340 lines
13 KiB
Markdown
# Proposal: MNote Main Tab 键盘导航与 MRU 行为
|
||
|
||
> 日期：2026-05-21
|
||
>
|
||
> 状态：proposed
|
||
>
|
||
> 来源：[Reasonix Worker B](../../.codex/reasonix-tasks/2026-05-21-sidex-worker-b-tab-keyboard-mru.md)
|
||
>
|
||
> 参考：Sidex `MultiEditorTabsControl`、MNote `activateMainEditorTab` / `bindMainEditorPageTab` / `resourceTabMru`
|
||
|
||
---
|
||
|
||
## 1. 目标
|
||
|
||
在现有主编辑区 tab strip 上增加轻量键盘导航和 MRU 回退行为，不引入完整 VSCode tab control 体系。
|
||
|
||
| 行为 | Sidex 做法 | MNote 对应 |
|
||
|------|-----------|-----------|
|
||
| 左右箭头 roving focus | `KEY_UP` → `ArrowLeft/Right` 计算相邻 editorIndex | tab strip `keydown` → 循环 `resourceTabRegistry` + page tab |
|
||
| Enter/Space 激活 | `KEY_UP` → `groupView.openEditor(editor)` | `activateMainEditorTab(objectIdentity)` |
|
||
| Home/End 跳转 | 计算 `editorIndex=0` 或 `count-1` | 跳转到 page tab (Home) 或最后一个 resource tab (End) |
|
||
| 关闭后 MRU 回退 | VSCode 的 `MRU` 排序 | 已有 `lastActiveResourceTabKey()`，需确认行为正确 |
|
||
| 关闭 active tab 后 focus 迁移 | 激活 MRU 中下一个 tab | `closeResourceTab` 最后调用 `activateMainEditorTab(lastActiveResourceTabKey())` |
|
||
|
||
---
|
||
|
||
## 2. 需要修改的源码函数
|
||
|
||
所有修改均位于 `rust/crates/mnote-web/src/routes/web_shell.rs`。
|
||
|
||
### 2.1 新增函数：`bindMainEditorTabStrip()`
|
||
|
||
**位置**：紧接 `bindMainEditorPageTab`（约 line 3450）。
|
||
|
||
```javascript
|
||
const bindMainEditorTabStrip = () => {
|
||
const nodes = resourceTabHostNodes();
|
||
if (!(nodes.strip instanceof HTMLElement)) return;
|
||
if (nodes.strip.getAttribute('data-mnote-tab-strip-bound') === 'true') return;
|
||
nodes.strip.setAttribute('data-mnote-tab-strip-bound', 'true');
|
||
|
||
// Helper: collect all tab buttons in DOM order (page tab first, then resource tabs)
|
||
const collectTabs = () => {
|
||
const tabs = [];
|
||
if (nodes.pageTab instanceof HTMLElement && nodes.pageTab.isConnected) tabs.push(nodes.pageTab);
|
||
resourceTabRegistry.forEach((entry) => {
|
||
if (entry.tab instanceof HTMLElement && entry.tab.isConnected) tabs.push(entry.tab);
|
||
});
|
||
return tabs;
|
||
};
|
||
|
||
// Helper: find currently focused tab index
|
||
const findFocusedIndex = (tabs) => {
|
||
const active = document.activeElement;
|
||
return tabs.findIndex((tab) => tab === active);
|
||
};
|
||
|
||
nodes.strip.addEventListener('keydown', (event) => {
|
||
const tabs = collectTabs();
|
||
if (tabs.length === 0) return;
|
||
const focusedIndex = findFocusedIndex(tabs);
|
||
let targetIndex = -1;
|
||
|
||
switch (event.key) {
|
||
case 'ArrowRight': {
|
||
event.preventDefault();
|
||
targetIndex = focusedIndex >= 0
|
||
? (focusedIndex + 1) % tabs.length
|
||
: tabs.findIndex((t) => t.getAttribute('aria-selected') === 'true');
|
||
if (targetIndex < 0) targetIndex = 0;
|
||
break;
|
||
}
|
||
case 'ArrowLeft': {
|
||
event.preventDefault();
|
||
targetIndex = focusedIndex >= 0
|
||
? (focusedIndex - 1 + tabs.length) % tabs.length
|
||
: tabs.findIndex((t) => t.getAttribute('aria-selected') === 'true');
|
||
if (targetIndex < 0) targetIndex = 0;
|
||
break;
|
||
}
|
||
case 'Home': {
|
||
event.preventDefault();
|
||
targetIndex = 0;
|
||
break;
|
||
}
|
||
case 'End': {
|
||
event.preventDefault();
|
||
targetIndex = tabs.length - 1;
|
||
break;
|
||
}
|
||
case 'Enter':
|
||
case ' ': { // Space
|
||
event.preventDefault();
|
||
const activeTab = tabs[focusedIndex >= 0 ? focusedIndex
|
||
: tabs.findIndex((t) => t.getAttribute('aria-selected') === 'true')];
|
||
if (activeTab) activeTab.click();
|
||
return;
|
||
}
|
||
default:
|
||
return; // don't re-focus
|
||
}
|
||
|
||
if (targetIndex >= 0 && targetIndex < tabs.length) {
|
||
tabs[targetIndex].focus();
|
||
}
|
||
});
|
||
};
|
||
```
|
||
|
||
**设计理由**：
|
||
|
||
- 使用 `keydown` 而非 `keyup`（Sidex 用 `KEY_UP` 是为了与 `StandardKeyboardEvent` 兼容，但 MNote 无此抽象）：`keydown` 捕获更快、防止浏览器默认滚动。
|
||
- `collectTabs()` 每次实时查询 DOM 顺序，避免缓存过期。
|
||
- `Enter`/`Space` 复用已有 `click` 事件处理（`createResourceTabDom` 中已有 click handler）。
|
||
- 只处理 `strip` 上的事件，利用事件冒泡获取已在 DOM 内的所有 tab。
|
||
|
||
### 2.2 修改 `bindMainEditorPageTab()`（约 line 3450）
|
||
|
||
当前函数只绑定 page tab 的 `click`。需在末尾追加：
|
||
|
||
```javascript
|
||
// 同时也绑定 tab strip 键盘导航
|
||
bindMainEditorTabStrip();
|
||
```
|
||
|
||
或在 `bindMainEditorPageTab` 返回前调用一次。
|
||
|
||
### 2.3 修改 `createResourceTabDom()`（约 line 3507）
|
||
|
||
新创建的 resource tab 已有 `tabindex="-1"` 初始值。**无需额外修改**，因为 `activateMainEditorTab` 已正确设置 active tab 的 `tabindex="0"`，其他 tab `tabindex="-1"`。
|
||
|
||
但需要确认：`activateMainEditorTab` 遍历 `resourceTabRegistry` 时，**page tab 和 resource tab 的 `tabindex` 一致性**。当前实现：
|
||
|
||
```javascript
|
||
// activateMainEditorTab 中（line 3428-3442）
|
||
if (nodes.pageTab instanceof HTMLElement) {
|
||
nodes.pageTab.setAttribute('tabindex', activePage ? '0' : '-1');
|
||
}
|
||
// resource tabs:
|
||
entry.tab.setAttribute('tabindex', active ? '0' : '-1');
|
||
```
|
||
|
||
→ 已满足 roving tabindex 的前置条件。**无需修改**。
|
||
|
||
### 2.4 修改 `closeResourceTab()`（约 line 3461）
|
||
|
||
当前关闭后通过 `activateMainEditorTab(lastActiveResourceTabKey())` 回退。但 focus 未迁移到新激活的 tab。需在 `activateMainEditorTab` 调用后**追加 focus**：
|
||
|
||
```javascript
|
||
// closeResourceTab 末尾，将 focus 移到新激活的 tab
|
||
const nextKey = lastActiveResourceTabKey();
|
||
activateMainEditorTab(nextKey);
|
||
// 新激活 tab 获得 focus
|
||
const nextTab = nextKey
|
||
? resourceTabRegistry.get(nextKey)?.tab
|
||
: nodes.pageTab;
|
||
if (nextTab instanceof HTMLElement) nextTab.focus();
|
||
```
|
||
|
||
### 2.5 确认 MRU 行为（`touchResourceTabMru` + `lastActiveResourceTabKey`）
|
||
|
||
现有 MRU 实现已足够：
|
||
|
||
```javascript
|
||
// touchResourceTabMru (line 3289-3295)
|
||
const touchResourceTabMru = (key) => {
|
||
const id = String(key || '').trim();
|
||
if (!id) return;
|
||
const index = resourceTabMru.indexOf(id);
|
||
if (index >= 0) resourceTabMru.splice(index, 1);
|
||
resourceTabMru.unshift(id);
|
||
if (resourceTabMru.length > resourceTabMruMax) resourceTabMru.length = resourceTabMruMax;
|
||
};
|
||
|
||
// lastActiveResourceTabKey (line 3309-3313)
|
||
const lastActiveResourceTabKey = () => {
|
||
for (const key of resourceTabMru) {
|
||
if (resourceTabRegistry.has(key)) return key;
|
||
}
|
||
return '';
|
||
};
|
||
```
|
||
|
||
**行为验证**：
|
||
- 激活一个 tab → `touchResourceTabMru(key)` 将其移到队列头部
|
||
- 关闭当前 tab → `removeFromResourceTabMru(key)` 移除 → `lastActiveResourceTabKey()` 返回 MRU 中第一个仍存在 registry 的 key
|
||
- 如果没有任何 resource tab 存活 → 返回 `''` → `activateMainEditorTab('')` 激活 page tab
|
||
|
||
→ **可用，无需修改 MRU 核心逻辑**。
|
||
|
||
---
|
||
|
||
## 3. 需新增的 CSS（`styles.rs`）
|
||
|
||
### 3.1 Focus 可见样式
|
||
|
||
当前 `mnote-main-tab` 没有 `:focus-visible` 样式。添加：
|
||
|
||
```css
|
||
.mnote-main-tab:focus-visible {
|
||
outline: 2px solid var(--atelier-primary, #006E28);
|
||
outline-offset: -2px;
|
||
}
|
||
```
|
||
|
||
### 3.2 可选：resource tab DOM 顺序保证
|
||
|
||
如果 resource tab 需要在 DOM 中保持 MRU 可见顺序（而非插入顺序），则 `createResourceTabDom` 中 `nodes.strip.append(tab)` 需改为按 MRU 顺序插入。但**当前不要求**——tabs 按打开顺序排列，MRU 只控制回退。
|
||
|
||
---
|
||
|
||
## 4. 需要更新的 contract test
|
||
|
||
文件：`rust/crates/mnote-web/src/routes/web_shell.rs` 末尾的 Rust 单元测试（约 line 4528+）。
|
||
|
||
### 4.1 新增 assert
|
||
|
||
```rust
|
||
assert!(html.contains("data-mnote-tab-strip-bound"));
|
||
assert!(html.contains("bindMainEditorTabStrip"));
|
||
```
|
||
|
||
即检查生成的 JS 中包含 `bindMainEditorTabStrip` 函数的定义字符串和 `data-mnote-tab-strip-bound` guard attribute。
|
||
|
||
### 4.2 已有断言确认
|
||
|
||
以下已有断言确保关键 tab DOM 结构存在：
|
||
|
||
```rust
|
||
assert!(html.contains("data-mnote-main-tab-strip")); // line 4538
|
||
assert!(html.contains("[data-mnote-main-tab=\"page\"] .mnote-main-tab-title")); // line 4541
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 需要新增的 smoke test
|
||
|
||
新建 `scripts/task475-editor-tab-keyboard-mru-smoke.js`（参考 `task457` 的 Playwright harness 写法）。
|
||
|
||
### 5.1 测试断言
|
||
|
||
| # | 断言 | 方法 |
|
||
|---|------|------|
|
||
| 1 | tab strip 可接收 keyboard focus | 在 strip 上 `page.keyboard.press('ArrowRight')` 后检查 `document.activeElement` 属于 `[data-mnote-main-tab]` |
|
||
| 2 | ArrowRight 循环聚焦 | focus page tab → ArrowRight → focused tab 应为第一个 resource tab |
|
||
| 3 | ArrowLeft 反向循环 | focus 第二个 resource tab → ArrowLeft → focused tab 应为第一个 resource tab |
|
||
| 4 | Home 跳到第一个 tab | focus 任意 resource tab → Home → focused 应为 page tab |
|
||
| 5 | End 跳到最后一个 tab | focus page tab → End → focused 应为最后一个 resource tab |
|
||
| 6 | Enter 激活 focused tab | ArrowRight 到 resource tab → Enter → 该 tab 应 `aria-selected="true"` |
|
||
| 7 | Space 激活 focused tab | 同上，使用 Space |
|
||
| 8 | 关闭 active tab 后 focus 迁移 | 打开 2 个 resource tab，激活第二个 → close → focus 应回到 MRU 中的第一个 |
|
||
| 9 | 关闭最后一个 resource tab 后回退 page tab | 打开 1 个 resource tab → close → page tab 应激活且 focused |
|
||
| 10 | `resourceTabMru` 顺序正确 | 打开 tab A、B、C，激活 B → 检查 MRU 数组头部是 B |
|
||
|
||
### 5.2 辅助函数
|
||
|
||
```javascript
|
||
// 获取当前 focused tab 的 identity
|
||
const getActiveTabId = () => page.evaluate(() => {
|
||
const active = document.activeElement;
|
||
return active?.getAttribute('data-mnote-main-tab') || null;
|
||
});
|
||
|
||
// 检查 aria-selected
|
||
const getSelectedTabId = () => page.evaluate(() => {
|
||
const selected = document.querySelector('[data-mnote-main-tab][aria-selected="true"]');
|
||
return selected?.getAttribute('data-mnote-main-tab') || null;
|
||
});
|
||
|
||
// 获取 MRU 队列
|
||
const getMruQueue = () => page.evaluate(() => {
|
||
// 通过 window 对象暴露（需在 web_shell.rs 中给 window.__mnoteResourceTabMru 赋值）
|
||
return window.__mnoteResourceTabMru || [];
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 6. DOM 状态总结
|
||
|
||
执行后，main tab 的 DOM 状态契约：
|
||
|
||
| Attribute / Property | 用途 | 取值 |
|
||
|----------------------|------|------|
|
||
| `data-mnote-main-tab-strip` | tab strip 根元素 | `"true"` |
|
||
| `data-mnote-tab-strip-bound` | 防止重复绑定 keyboard handler | `"true"`（JS 运行时设置） |
|
||
| `aria-selected="true"` | 当前激活 tab | 仅一个 tab 有 |
|
||
| `tabindex="0"` | 当前可聚焦 tab（roving） | 与 `aria-selected` 同步 |
|
||
| `tabindex="-1"` | 不可直接聚焦 tab | 其他所有 tab |
|
||
| `data-mnote-main-tab="page"` | page tab 标识 | SSR 初始 |
|
||
| `data-mnote-main-tab="<identity>"` | resource tab 标识 | JS 创建 |
|
||
| `class="mnote-main-tab"` | 所有 tab 共享 class | 全部 |
|
||
| `class="is-active"` | 当前激活 tab | 与 `aria-selected` 同步 |
|
||
| `role="tab"` | ARIA tab role | 全部 |
|
||
|
||
---
|
||
|
||
## 7. 风险与边界情况
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
|------|------|------|
|
||
| keyboard 事件与编辑器快捷键冲突 | ArrowLeft/Right 被编辑区拦截 | 事件只在 `focus` 位于 tab strip 内时触发（`document.activeElement` 检查） |
|
||
| `resourceTabRegistry` 遍历顺序不确定 | `collectTabs()` 中 tab 顺序可能乱序 | `collectTabs()` 顺序：page tab 固定首位 + `resourceTabRegistry.forEach`（V8 中 `Map.forEach` 按插入顺序） |
|
||
| 关闭 tab 时 DOM 元素刚被 remove | `isConnected` 检查失败 | `closeResourceTab` 需要先查 nextTab，再删当前 tab 或重新查询 |
|
||
| 多个 resource tab 同时关闭 | MRU 队列清空后无回退 | `lastActiveResourceTabKey()` 返回 `''` 已正确处理 |
|
||
| 与 Worker A 的并行修改冲突 | `web_shell.rs` 中函数顺序和行号漂移 | 本 proposal 以函数名定位，不依赖行号 |
|
||
|
||
---
|
||
|
||
## 8. 实现顺序（最小安全步骤）
|
||
|
||
```
|
||
Step 1: 在 bindMainEditorPageTab 后新增 bindMainEditorTabStrip 函数
|
||
实现 keydown 事件委托 + collectTabs + 箭头/Home/End/Enter/Space
|
||
|
||
Step 2: 修改 closeResourceTab 末尾
|
||
在 activateMainEditorTab 后将 focus 移到新激活 tab
|
||
|
||
Step 3: 在 styles.rs 中补 :focus-visible 样式
|
||
|
||
Step 4: 更新 Rust contract test（新增 bindMainEditorTabStrip / data-mnote-tab-strip-bound 断言）
|
||
|
||
Step 5: 新建 scripts/task475-editor-tab-keyboard-mru-smoke.js
|
||
实现 10 个测试断言
|
||
|
||
Step 6: 验收
|
||
cargo test -p mnote-web web_shell -- --test-threads=1
|
||
node scripts/task475-editor-tab-keyboard-mru-smoke.js
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 非目标（明确不做的）
|
||
|
||
- 不实现 tab 拖拽排序
|
||
- 不实现 `Ctrl+Tab` / `Ctrl+Shift+Tab` 的 MRU 循环（那是全局快捷键，不是 tab strip keyboard 行为）
|
||
- 不实现 close others / close right 菜单
|
||
- 不改变 page/resource tab identity 机制
|
||
- 不添加 tab overflow 滚动
|