From c8620e6e1bf1cb7daae8579165b318f56cf9a222 Mon Sep 17 00:00:00 2001 From: cruldra Date: Sun, 27 Sep 2026 21:39:15 +0800 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor(vscode):=20?= =?UTF-8?q?=E7=9C=8B=E6=9D=BF=E7=9A=84=E6=82=AC=E5=81=9C=E6=8F=90=E7=A4=BA?= =?UTF-8?q?=E4=B9=9F=E6=94=B9=E8=B5=B0=20data-tooltip=EF=BC=8C=E6=8F=92?= =?UTF-8?q?=E4=BB=B6=E7=BD=91=E9=A1=B5=E5=8F=AA=E5=89=A9=E4=B8=80=E6=9D=A1?= =?UTF-8?q?=E6=8F=90=E7=A4=BA=E7=9A=84=E8=B7=AF=EF=BC=9Blint=20=E7=A6=81?= =?UTF-8?q?=E6=AD=A2=E5=8E=9F=E7=94=9F=20title?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 看板剩下的原生 title（顶栏按钮、工单卡片、工单详情、会话、Profile 表、改动文件树和 diff、属性表）全部改成 data-tooltip， 禁用的按钮照样弹；只有图标、原来只靠 title 当名字的（审查勾、生成说明、属性说明的 i 图标、没头像的归属人）补上 aria-label - 提示框按原文换行：摘修复弹框里「迁移」列的几个文件一行一个 - 代码阅读 Markdown 链接的标题写成 data-tooltip - eslint 规则：网页 TSX 的 DOM 元素上写 title 报错，iframe 和组件自己的 title 属性不算 --- docs/superpowers/specs/code-reader/spec.md | 4 ++-- vscode/eslint.config.mjs | 11 +++++++++++ .../webview-ui/src/codeReader/markdown.test.ts | 5 +++++ vscode/webview-ui/src/codeReader/markdown.ts | 14 ++++++++++++++ vscode/webview-ui/src/components/BottomTabs.tsx | 2 +- .../src/components/CherryPickModal.tsx | 2 +- vscode/webview-ui/src/components/IssueCard.tsx | 10 ++++++---- .../src/components/IssueDetailPanel.tsx | 10 +++++----- .../src/components/ManagedSessionsPanel.tsx | 12 ++++++------ vscode/webview-ui/src/components/PanelHeader.tsx | 16 ++++++++-------- vscode/webview-ui/src/components/ProfileGrid.tsx | 12 ++++++------ .../src/components/prFiles/FileDiffPane.tsx | 9 ++++++--- .../src/components/prFiles/FileTree.tsx | 10 ++++++---- .../webview-ui/src/components/property-grid.tsx | 10 ++++++---- vscode/webview-ui/src/components/ui/tooltip.tsx | 5 +++-- 15 files changed, 86 insertions(+), 46 deletions(-) diff --git a/docs/superpowers/specs/code-reader/spec.md b/docs/superpowers/specs/code-reader/spec.md index 9c1a14a..e93c59b 100644 --- a/docs/superpowers/specs/code-reader/spec.md +++ b/docs/superpowers/specs/code-reader/spec.md @@ -130,7 +130,7 @@ 这组图标由插件自己定义，是一个封闭的集合：契约里的 `KIND_ICON_NAMES`（上表 18 个加库规则用的 6 个，lucide 的 kebab-case 名字），类型 `KindIconName` 是它们的联合，`KindBadge.icon` 只能写其中一个，写别的是类型错误。webview 给每个名字配一个逐个 import 的 lucide 图标组件（`kindIcons.tsx` 的 `KIND_ICON_COMPONENTS`，打包只带这些，预览脚本约 157 kB）；webview 的 `KindIconName` 照契约手抄，`kindIconNames.test.ts` 核对两边一样。规则要新图标就把名字加进这组、在 webview 配上图标，没有按任意名字找图标的路。 - 右上角的图标按钮（原型组件 `Reader / BlockTools`，普通块、属性表块、库规则的卡片共用）：只有图标、不带字，名字写在悬停提示和 `aria-label` 里；整排是 `role="group"`（`aria-label="块操作"`）。先是「问 AI」（sparkles 图标，点开 / 收起块下面的问答区，展开时带按下的底色、`aria-expanded`；文件不在工作区文件夹里时没有，见「问 AI」），再是「编辑 / 预览」切换：预览时铅笔「编辑」，编辑时眼睛「预览」、带按下的底色（`--vscode-toolbar-activeBackground`）。按钮宽 24px、高 20px（和种类图标同高），图标 14px、`descriptionForeground` 色；悬停 `--vscode-toolbar-hoverBackground`，键盘聚焦描 1px `--vscode-focusBorder`；Tab 能走到，回车 / 空格切换。 -- 悬停提示（整个预览只走这一条路，看板 webview 共用同一个组件）：带提示的元素只写 `data-tooltip="提示"`（名字照旧写在 `aria-label` 里），页面根上挂一个 `TooltipHost`（`webview-ui/src/components/ui/tooltip.tsx`）统一弹，不用原生 `title`。原因：macOS 上 VS Code 带的 Electron（1.139 是 Electron 43）只在鼠标压着带 `title` 的元素自身边缘时才弹原生提示，停在它里面的图标、文字上不弹（electron/electron#49843，Electron 38 起），种类图标 20px 的框几乎被 16px 的图形占满，基本弹不出来；样子也是系统的。样子照 VS Code 的悬停框：`--vscode-editorHoverWidget-background` 底、`--vscode-editorHoverWidget-border` 边框、`--vscode-editorHoverWidget-foreground` 字、`0 2px 8px --vscode-widget-shadow` 阴影，11px 字，圆角 4px，最宽 22rem；优先在元素上方，上方放不下翻到下方，水平对着元素中间，贴边留 8px，不接鼠标。鼠标停 500ms 才弹，在同一个元素里移动不重新计时，已经弹着时移到另一个带提示的元素上立刻换；移开、移出页面、按下鼠标、按任意键（含 Esc）、滚动就收，收了之后鼠标不离开这个元素不再弹。键盘把焦点移到带提示的元素上（`:focus-visible`）立刻弹，焦点离开就收；提示不是元素自己的名字（`aria-label` 或它的字）时用 `aria-describedby` 挂到元素上，读屏当描述念。 +- 悬停提示（整个插件的网页只走这一条路，预览和看板共用同一个组件）：带提示的元素只写 `data-tooltip="提示"`（名字照旧写在 `aria-label` 里，只有图标的按钮必须有 `aria-label`），页面根上挂一个 `TooltipHost`（`webview-ui/src/components/ui/tooltip.tsx`）统一弹，不用原生 `title`；提示里的换行照样换行（看板摘修复弹框里「迁移」列出的几个文件一行一个）；注释、回答里 Markdown 链接的标题（`[文字](网址 "标题")`）也写成 `data-tooltip`。网页的 TSX 里写原生 `title` 属性是 lint 错误（`vscode/eslint.config.mjs`），只有 `iframe` 这种必须带标题的元素例外，组件自己叫 `title` 的属性不算。原因：macOS 上 VS Code 带的 Electron（1.139 是 Electron 43）只在鼠标压着带 `title` 的元素自身边缘时才弹原生提示，停在它里面的图标、文字上不弹（electron/electron#49843，Electron 38 起），种类图标 20px 的框几乎被 16px 的图形占满，基本弹不出来；样子也是系统的。样子照 VS Code 的悬停框：`--vscode-editorHoverWidget-background` 底、`--vscode-editorHoverWidget-border` 边框、`--vscode-editorHoverWidget-foreground` 字、`0 2px 8px --vscode-widget-shadow` 阴影，11px 字，圆角 4px，最宽 22rem；优先在元素上方，上方放不下翻到下方，水平对着元素中间，贴边留 8px，不接鼠标。鼠标停 500ms 才弹，在同一个元素里移动不重新计时，已经弹着时移到另一个带提示的元素上立刻换；移开、移出页面、按下鼠标、按任意键（含 Esc）、滚动就收，收了之后鼠标不离开这个元素不再弹。键盘把焦点移到带提示的元素上（`:focus-visible`）立刻弹，焦点离开就收；提示不是元素自己的名字（`aria-label` 或它的字）时用 `aria-describedby` 挂到元素上，读屏当描述念。 - 种类图标和底色按种类区分（颜色见「颜色」）；注释块虚线框。 - 内容两种状态，每块单独切： - 预览：函数、类、枚举、异常、导入、常量、变量块是属性表（见下节），注释块是 Markdown 说明（见「注释的 Markdown 排版」），其余块是一行译文；按词着色，等宽字体（中文部分用系统中文字体回退）。一行译文的块带说明（Python 字段的属性 docstring）时，说明按 Markdown 排在译文下面。 @@ -1453,7 +1453,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面（React，Vit - 复制出什么（`explorer/copyText.test.ts`）：文件、目录的名字 / 相对路径 / 绝对路径；不带后缀只去最后一个扩展名（`a.test.ts`、`archive.tar.gz`），`.env` 原样、`.env.local` → `.env`、没有扩展名的原样；相对路径总用 `/`，绝对路径照本机写法（Windows 反斜杠）。 - 块右上角的图标按钮（webview `BlockTools.test.tsx`，渲染成 HTML）：一组一个按钮、没有字、悬停提示（`data-tooltip`，没有原生 `title`）和 `aria-label` 是「编辑」/「预览」、有图标、编辑时带按下标记；给了「问 AI」时它排在前面、只有图标、问答区展开时带按下标记和 `aria-expanded`。 - 块的种类图标（webview `kindIcons.test.tsx`，渲染成 HTML）：内置种类的图标和原型一一对应；这组里每个名字画的就是 lucide 里同名的图标；webview 配了图标的名字和契约的 `KIND_ICON_NAMES` 一样、没有多的（`kindIconNames.test.ts`）；只有图标、没有字，`role="img"`，悬停提示（`data-tooltip`，没有原生 `title`） 和 `aria-label` 是种类名，20px 的框、16px 的图形；库规则的卡片用规则给的图标。各库规则的测试核对 `badge` 的名字、颜色、图标。 -- 悬停提示（webview `components/ui/tooltip.test.ts`）：停 500ms 才弹、在同一个元素里移动不重新计时、没等到就移开不弹、弹着时移到另一个上立刻换、移到没提示的地方就收、按下鼠标 / 按键 / 滚动就收且鼠标不离开不再弹、等着弹时按下这次不弹、键盘聚焦立刻弹失焦收、提示是空的不弹；位置在上方、上方放不下翻到下方、左右钳在视口内。页面上（无头 Chrome，真的移鼠标、按 Tab）：种类图标中心点命中的是图标里的线条、没有盖在上面的东西；停 250ms 还没弹、停满 500ms 在图标上方弹「函数」「接口」，颜色是悬停框的那组变量；Tab 到「编辑」立刻弹、Esc 收；页面上没有原生 `title`。亮、暗两套颜色都看过。 +- 悬停提示（webview `components/ui/tooltip.test.ts`）：停 500ms 才弹、在同一个元素里移动不重新计时、没等到就移开不弹、弹着时移到另一个上立刻换、移到没提示的地方就收、按下鼠标 / 按键 / 滚动就收且鼠标不离开不再弹、等着弹时按下这次不弹、键盘聚焦立刻弹失焦收、提示是空的不弹；位置在上方、上方放不下翻到下方、左右钳在视口内。Markdown 链接的标题写成 `data-tooltip`（`markdown.test.ts`）；网页 TSX 里的原生 `title` 由 lint 规则拦（`button`、`span` 上报错，`iframe`、组件属性不报）。页面上（无头 Chrome，真的移鼠标、按 Tab）：种类图标中心点命中的是图标里的线条、没有盖在上面的东西；停 250ms 还没弹、停满 500ms 在图标上方弹「函数」「接口」，颜色是悬停框的那组变量；Tab 到「编辑」立刻弹、Esc 收；页面上没有原生 `title`；看板上「待接管」、禁用的 .env 锁按钮（禁用的按钮照样弹）、刷新按钮、摘修复弹框里「迁移」的三行文件名（一行一个）都弹，Tab 到按钮立刻弹、Esc 收。亮、暗两套颜色都看过。 - 问 AI： - 位置记号（`qa/anchor.test.ts`，真实的 Python 解析）：有名字 / 没名字的块的记号、同一层重复的编号、两个函数里一样的条件互不影响；上面插几行、改空白记号不变；改别的函数的名字只动它和它里面的块；没名字的块自己的源码改了记号变、有名字的块改签名不变。 - 存法（`qa/qaMap.test.ts`）：记一次、删一次、删光不挂 / 不记；文件缺失、解析失败、不是对象当没有；认不出的块和问答跳过、没会话 id 的照认；再问时接着这块最近那条的会话（删了最近的接着剩下里最近的，没问过、没记会话 id 的重新开）；用哪个 profile 答的跟着这条存、读得回来，没有的、空的、不是字符串的当没有；手改的顺序、重复的块读进来整理好；写出来排好序、两格缩进、读得回来、删光留 `{}`；改名、挪目录、删除跟着走。图片：文件名跟着这条存、读得回来，跑到别处的路径、不是字符串的名字跳过；删一次问答它的图片跟着删、别的留着；源文件删了图片跟着删，改名、挪目录图片不动。 diff --git a/vscode/eslint.config.mjs b/vscode/eslint.config.mjs index ee5c5c0..1dd1d7d 100644 --- a/vscode/eslint.config.mjs +++ b/vscode/eslint.config.mjs @@ -22,4 +22,15 @@ export default antfu( }], }, }, + { + // webview 的悬停提示只走 components/ui/tooltip.tsx（元素上写 data-tooltip）：原生 title 在 macOS 的 VS Code 里鼠标停在元素里面不弹 + // （electron/electron#49843），样式也是系统的。只有必须带 title 的元素（iframe 的标题）例外；组件自己的 title 属性（大写开头）不算 + files: ['webview-ui/src/**/*.tsx'], + rules: { + 'no-restricted-syntax': ['error', 'TSEnumDeclaration[const=true]', 'TSExportAssignment', { + selector: 'JSXOpeningElement[name.name=/^[a-z]/]:not([name.name="iframe"]) > JSXAttribute[name.name="title"]', + message: '悬停提示写 data-tooltip（components/ui/tooltip.tsx 统一弹），不用原生 title；图标按钮的名字写 aria-label', + }], + }, + }, ) diff --git a/vscode/webview-ui/src/codeReader/markdown.test.ts b/vscode/webview-ui/src/codeReader/markdown.test.ts index 1788192..a92ed79 100644 --- a/vscode/webview-ui/src/codeReader/markdown.test.ts +++ b/vscode/webview-ui/src/codeReader/markdown.test.ts @@ -39,4 +39,9 @@ describe('renderMarkdown', () => { expect(renderMarkdown('[相对](./x.md)')).not.toContain(' { + expect(renderMarkdown('[文档](https://example.com "接口说明")')).toBe('

文档

\n') + expect(renderMarkdown('[文档](https://example.com "")')).toBe('

文档

\n') + }) }) diff --git a/vscode/webview-ui/src/codeReader/markdown.ts b/vscode/webview-ui/src/codeReader/markdown.ts index b7f1fce..b37b80c 100644 --- a/vscode/webview-ui/src/codeReader/markdown.ts +++ b/vscode/webview-ui/src/codeReader/markdown.ts @@ -8,6 +8,20 @@ import MarkdownIt from 'markdown-it' const md = new MarkdownIt({ html: false, linkify: true }).disable('image') md.validateLink = url => /^(?:https?|mailto):/i.test(url) +/** 链接的标题（`[文字](网址 "标题")`）写成 data-tooltip，和页面上别的悬停提示走同一个提示框（components/ui/tooltip.tsx），不用原生 title。 */ +md.core.ruler.push('link_title_tooltip', (state) => { + for (const block of state.tokens) { + for (const token of block.children ?? []) { + const title = token.type === 'link_open' ? token.attrGet('title') : null + if (title === null) + continue + token.attrs = token.attrs!.filter(([name]) => name !== 'title') + if (title) + token.attrSet('data-tooltip', title) + } + } +}) + /** 最近渲染过的文字 → HTML，最多留 CACHE_SIZE 段，最久没用的先丢。 */ const CACHE_SIZE = 500 const cache = new Map() diff --git a/vscode/webview-ui/src/components/BottomTabs.tsx b/vscode/webview-ui/src/components/BottomTabs.tsx index 48bc9f2..6786416 100644 --- a/vscode/webview-ui/src/components/BottomTabs.tsx +++ b/vscode/webview-ui/src/components/BottomTabs.tsx @@ -227,7 +227,7 @@ function TabButton({ active, onClick, icon, title, badge }: TabButtonProps) {