@tnotesjs/ui 0.2.1 → 0.3.0

package/README.md

@@ -8,6 +8,55 @@ TNotes 内置块的 Vue 组件。消费方：`@tnotesjs/ssg`、Desk。需要 `vu
 pnpm add @tnotesjs/ui
 ```
 
+### 代码块（`CodeBlock` / `CodeGroup`）
+
+默认行为跟 VitePress 一致，**任何情况下都不限制高度**：
+
+- 宽度不超出正文容器，超长单行在代码块内横向滚动，页面不会被撑宽；
+- 原始换行与缩进原样保留（`white-space: pre`），不强制换行；
+- 高度一律由内容撑开：**没有 `max-height`、不会出现内部纵向滚动**，哪怕上万行也照直铺开。
+
+**折叠是页面内的视图状态**：每个代码块标题左侧都有折叠 Icon，点一下把代码内容
+整体隐藏（只剩标题栏，跟折叠标题一样），再点展开。状态**只存在当前页面的内存里** ——
+不写进 markdown、不写 localStorage，刷新或重新进入页面一律回到展开。
+代码分组切换 tab 时，新露出来的面板若处于收起状态会自动展开。
+
+````md
+```js
+console.log('每个代码块标题左侧都有折叠 Icon')
+```
+
+```ts:line-numbers {2} [multi.ts]
+function add(a: number, b: number) {
+  const sum = a + b
+  return sum
+}
+```
+
+```text [one-line.txt]
+这一行很长很长……它在代码块内横向滚动，不会把页面撑宽
+```
+
+```js [long.js]
+// 多少行都直接铺开：没有 max-height，也没有内部纵向滚动条
+```
+
+::: code-group
+
+```js [a-short.js]
+console.log('a')
+```
+
+```ts [b-long.ts]
+// 每个 tab 的代码同样可折叠；切换 tab 会自动展开收起的面板
+```
+
+:::
+````
+
+作者不需要写任何额外标记，也不需要“声明”某个代码块可折叠。站点读者与编辑器
+（Desk）行为一致。
+
 ### `BilibiliVideo`
 
 | Prop       | Default  |
@@ -51,3 +100,35 @@ pnpm add @tnotesjs/ui
 | `enableCopy`         | `true`    |
 | `enableFullscreen`   | `true`    |
 | `enableCenterToggle` | `true`    |
+
+### `MindmapEditor`（`@tnotesjs/ui/mindmap-editor`）
+
+思维导图编辑器的**唯一实现**。`@tnotesjs/ui/mindmap` 那个块（`Mindmap.vue`）是给 SSG / Desk 笔记
+内嵌用的「预览 + 可选编辑」；本入口导出它内部复用的编辑器组件，供自带页面外壳的宿主直接组装。
+当前宿主：`apps/mindmap-web`、`apps/mindmap-vscode`。
+
+| 导出                                                                          | 说明                                           |
+| ----------------------------------------------------------------------------- | ---------------------------------------------- |
+| `MindmapView`                                                                 | 脑图画布（含选区工具条 / 右键菜单 / 链接浮层） |
+| `OutlineView`                                                                 | 大纲视图（拖拽、行内富文本、折叠）             |
+| `MarkdownView`                                                                | 源码视图（防抖回流 + 诊断定位）                |
+| `SearchBar`                                                                   | 三视图共用的搜索条                             |
+| `FocusBreadcrumbs`                                                            | 进入主题后的面包屑（与主 barrel 同源）         |
+| `AppIcon` / `IconButton` / `CollapseMenu`                                     | 外壳按钮与图标                                 |
+| `CanvasContextMenu` / `LinkPopover` / `RichInlineEditor` / `SelectionToolbar` | 上面几个组件的组成件，供未来宿主自行组装       |
+| `insertImageIntoSource`                                                       | 源码视图的整节点图片插入                       |
+| `pasteCanvasOutline` / `readMindmapClipboard` / `writeMindmapClipboard`       | 脑图剪贴板（含无权限时的进程内回退）           |
+| `resolveAfterDropLevel` / `DropLevel`                                         | 大纲拖拽落点解析                               |
+| `primaryShortcut` / `altShortcut` / `isApplePlatform`                         | 平台快捷键文案                                 |
+
+**浮层挂载点（`teleportTo`）**：`MindmapView`（并透传给 `CanvasContextMenu` / `LinkPopover`）接受
+`teleportTo?: string`。默认 `undefined` = 就地渲染——浮层是 `position: fixed`，嵌在笔记里的宿主
+（Desk / SSG）teleport 到 `body` 会脱离笔记的层叠上下文。整页宿主传 `'body'`。
+
+**宿主职责（不属于本包）**：`MindmapSession` 的归属与生命周期、`--mm-*` 主题变量
+（`--mm-canvas-bg` / `--mm-panel-bg` / `--mm-border` / `--mm-text` / `--mm-text-dim` / `--mm-hover` /
+`--mm-selected-bg` / `--mm-accent` / `--mm-edit-bg`）、落盘、图片写入、宿主快捷键到组件
+`defineExpose` 钩子的桥接（`OutlineView` 的 `locateNode` / `selectAllFromHost` / `undoFromHost` /
+`redoFromHost`，`MarkdownView` 的 `selectAllFromHost` / `flushDraft`）。
+
+改公共交互只改这里一处，三个宿主同时生效。

package/dist/code/highlight.d.ts

@@ -1,5 +1,43 @@
 import { HighlighterCore } from 'shiki/core';
 
+/**
+ * 代码块折叠：**纯视图状态**，只存在于当前页面的内存里。
+ *
+ * - 不进 markdown，不写 localStorage：刷新 / 重新进入页面后一律**默认展开**；
+ * - 折叠 = 代码内容整体隐藏，只剩标题栏（跟折叠标题一样，不是「露出前几行」）；
+ * - 默认（未折叠）不做任何高度限制：不管多少行都由内容撑开，没有 max-height、
+ *   没有内部纵向滚动，超长单行在代码块内横向滚动；
+ * - 每个代码块标题左侧都有折叠 Icon，点击在收起 / 展开之间切换。
+ *
+ * DOM 是唯一状态源（`is-collapsed` class + `aria-expanded`），因此 SSR 出来的静态
+ * HTML 和客户端补强（`hydrateIslands`）以及 Vue 组件本身共用一套契约。
+ */
+/** 收起状态挂在代码块根节点上的 class。 */
+declare const CODE_BLOCK_COLLAPSED_CLASS = "is-collapsed";
+/** 代码块根节点（`.tn-code-block`）或它内部任意节点 → 根节点。 */
+declare function codeBlockFrom(node: Element | null | undefined): HTMLElement | null;
+declare function isCodeBlockCollapsed(block: Element | null | undefined): boolean;
+/** 面板 / 容器里的第一个代码块（代码分组的面板就是这种结构）。 */
+declare function codeBlockIn(root: ParentNode | null | undefined): HTMLElement | null;
+declare function collapseButtonLabel(collapsed: boolean): string;
+/**
+ * 同步折叠按钮的可访问状态。
+ *
+ * 代码分组把按钮放在 tab 行里（面板自带的那个会被 tab 盖住），两处按钮共用这套 chrome。
+ */
+declare function applyCollapseChrome(button: Element | null, collapsed: boolean): void;
+/** 设置某个代码块的收起状态（`is-collapsed` 决定内容是否隐藏，见 code.css）。 */
+declare function setCodeBlockCollapsed(block: Element | null, collapsed: boolean): void;
+/** 切换收起状态，返回切换后的状态。 */
+declare function toggleCodeBlockCollapsed(block: Element | null): boolean;
+/**
+ * 展开 root 里所有被收起的代码块。
+ *
+ * 代码分组切换 tab 时用它：新露出来的面板如果是收起状态，自动展开，
+ * 读者不会只看到一个标题栏。
+ */
+declare function expandCollapsedCodeBlocks(root: ParentNode | null | undefined): void;
+
 interface CodeMeta {
     language: string;
     title: string;
@@ -39,4 +77,4 @@ declare function prepareCodeHighlighter(languages?: string[]): Promise<Highlight
 declare function highlightCodeSync(code: string, info?: string): string;
 declare function highlightCode(code: string, info?: string): Promise<string>;
 
-export { type CodeMeta, SHARED_CODE_GROUP_CONTRACT, highlightCode, highlightCodeSync, normalizeCodeLanguage, parseCodeMeta, prepareCodeHighlighter };
+export { CODE_BLOCK_COLLAPSED_CLASS, type CodeMeta, SHARED_CODE_GROUP_CONTRACT, applyCollapseChrome, codeBlockFrom, codeBlockIn, collapseButtonLabel, expandCollapsedCodeBlocks, highlightCode, highlightCodeSync, isCodeBlockCollapsed, normalizeCodeLanguage, parseCodeMeta, prepareCodeHighlighter, setCodeBlockCollapsed, toggleCodeBlockCollapsed };

package/dist/code/highlight.js

@@ -2,6 +2,50 @@
 import { createHighlighterCore } from "shiki/core";
 import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
 import { bundledLanguages, bundledLanguagesAlias } from "shiki/langs";
+
+// src/code/collapse.ts
+var CODE_BLOCK_COLLAPSED_CLASS = "is-collapsed";
+function codeBlockFrom(node) {
+  if (!node) return null;
+  if (node.classList.contains("tn-code-block")) return node;
+  return node.closest(".tn-code-block") ?? null;
+}
+function isCodeBlockCollapsed(block) {
+  return Boolean(block?.classList.contains(CODE_BLOCK_COLLAPSED_CLASS));
+}
+function codeBlockIn(root) {
+  return root?.querySelector(".tn-code-block") ?? null;
+}
+function collapseButtonLabel(collapsed) {
+  return collapsed ? "\u5C55\u5F00\u4EE3\u7801" : "\u6536\u8D77\u4EE3\u7801";
+}
+function applyCollapseChrome(button, collapsed) {
+  if (!button) return;
+  button.classList.toggle(CODE_BLOCK_COLLAPSED_CLASS, collapsed);
+  button.setAttribute("aria-expanded", collapsed ? "false" : "true");
+  const label = collapseButtonLabel(collapsed);
+  button.setAttribute("aria-label", label);
+  if (button instanceof HTMLElement) button.title = label;
+}
+function setCodeBlockCollapsed(block, collapsed) {
+  if (!block) return;
+  block.classList.toggle(CODE_BLOCK_COLLAPSED_CLASS, collapsed);
+  applyCollapseChrome(block.querySelector(".tn-code-block__collapse-btn"), collapsed);
+}
+function toggleCodeBlockCollapsed(block) {
+  const next = !isCodeBlockCollapsed(block);
+  setCodeBlockCollapsed(block, next);
+  return next;
+}
+function expandCollapsedCodeBlocks(root) {
+  if (!root) return;
+  if ("classList" in root && isCodeBlockCollapsed(root)) {
+    setCodeBlockCollapsed(root, false);
+  }
+  root.querySelectorAll(`.tn-code-block.${CODE_BLOCK_COLLAPSED_CLASS}`).forEach((block) => setCodeBlockCollapsed(block, false));
+}
+
+// src/code/highlight.ts
 var SHARED_CODE_GROUP_CONTRACT = {
   source: [
     "::: code-group",
@@ -120,10 +164,19 @@ async function highlightCode(code, info = "") {
   return highlightCodeSync(code, info);
 }
 export {
+  CODE_BLOCK_COLLAPSED_CLASS,
   SHARED_CODE_GROUP_CONTRACT,
+  applyCollapseChrome,
+  codeBlockFrom,
+  codeBlockIn,
+  collapseButtonLabel,
+  expandCollapsedCodeBlocks,
   highlightCode,
   highlightCodeSync,
+  isCodeBlockCollapsed,
   normalizeCodeLanguage,
   parseCodeMeta,
-  prepareCodeHighlighter
+  prepareCodeHighlighter,
+  setCodeBlockCollapsed,
+  toggleCodeBlockCollapsed
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tnotesjs/ui",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Shared Vue UI for TNotes built-in blocks — consumed by the TNotes SSG and Desk.",
   "type": "module",
   "exports": {
@@ -60,6 +60,11 @@
       "types": "./src/entries/excalidraw-editor.ts",
       "import": "./src/entries/excalidraw-editor.ts",
       "default": "./src/entries/excalidraw-editor.ts"
+    },
+    "./mindmap-editor": {
+      "types": "./src/entries/mindmap-editor.ts",
+      "import": "./src/entries/mindmap-editor.ts",
+      "default": "./src/entries/mindmap-editor.ts"
     }
   },
   "files": [
@@ -86,14 +91,20 @@
     "@tnotesjs/mindmap-core": "^0.2.2"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/react": "^18.3.31",
     "@types/react-dom": "^18.0.0",
     "@vitejs/plugin-vue": "^6.0.8",
+    "eslint": "^10.8.1",
+    "eslint-plugin-vue": "^10.10.0",
+    "globals": "^17.11.0",
     "happy-dom": "^20.12.0",
     "tsup": "8.5.1",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.11",
-    "vue": "^3.5.25"
+    "vue": "^3.5.25",
+    "vue-eslint-parser": "^10.4.1"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -104,12 +115,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tnotesjs/tnotesjs.git",
+    "url": "git+https://github.com/tnotesjs/tnotes.git",
     "directory": "packages/ui"
   },
-  "homepage": "https://github.com/tnotesjs/tnotesjs/tree/main/packages/ui#readme",
+  "homepage": "https://github.com/tnotesjs/tnotes/tree/main/packages/ui#readme",
   "bugs": {
-    "url": "https://github.com/tnotesjs/tnotesjs/issues"
+    "url": "https://github.com/tnotesjs/tnotes/issues"
   },
   "keywords": [
     "tnotesjs",
@@ -121,6 +132,8 @@
   "scripts": {
     "build": "tsup src/code/highlight.ts src/components/Footprints/parse.ts src/components/Mindmap/markdown.ts src/markdown/image.ts --format esm --dts --out-dir dist --clean",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run"
+    "test": "vitest run",
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint . --fix"
   }
 }

package/src/code/collapse.ts

@@ -0,0 +1,79 @@
+/**
+ * 代码块折叠：**纯视图状态**，只存在于当前页面的内存里。
+ *
+ * - 不进 markdown，不写 localStorage：刷新 / 重新进入页面后一律**默认展开**；
+ * - 折叠 = 代码内容整体隐藏，只剩标题栏（跟折叠标题一样，不是「露出前几行」）；
+ * - 默认（未折叠）不做任何高度限制：不管多少行都由内容撑开，没有 max-height、
+ *   没有内部纵向滚动，超长单行在代码块内横向滚动；
+ * - 每个代码块标题左侧都有折叠 Icon，点击在收起 / 展开之间切换。
+ *
+ * DOM 是唯一状态源（`is-collapsed` class + `aria-expanded`），因此 SSR 出来的静态
+ * HTML 和客户端补强（`hydrateIslands`）以及 Vue 组件本身共用一套契约。
+ */
+
+/** 收起状态挂在代码块根节点上的 class。 */
+export const CODE_BLOCK_COLLAPSED_CLASS = 'is-collapsed'
+
+/** 代码块根节点（`.tn-code-block`）或它内部任意节点 → 根节点。 */
+export function codeBlockFrom(node: Element | null | undefined): HTMLElement | null {
+  if (!node) return null
+  if (node.classList.contains('tn-code-block')) return node as HTMLElement
+  return (node.closest('.tn-code-block') as HTMLElement | null) ?? null
+}
+
+export function isCodeBlockCollapsed(block: Element | null | undefined): boolean {
+  return Boolean(block?.classList.contains(CODE_BLOCK_COLLAPSED_CLASS))
+}
+
+/** 面板 / 容器里的第一个代码块（代码分组的面板就是这种结构）。 */
+export function codeBlockIn(root: ParentNode | null | undefined): HTMLElement | null {
+  return root?.querySelector<HTMLElement>('.tn-code-block') ?? null
+}
+
+export function collapseButtonLabel(collapsed: boolean): string {
+  return collapsed ? '展开代码' : '收起代码'
+}
+
+/**
+ * 同步折叠按钮的可访问状态。
+ *
+ * 代码分组把按钮放在 tab 行里（面板自带的那个会被 tab 盖住），两处按钮共用这套 chrome。
+ */
+export function applyCollapseChrome(button: Element | null, collapsed: boolean): void {
+  if (!button) return
+  button.classList.toggle(CODE_BLOCK_COLLAPSED_CLASS, collapsed)
+  button.setAttribute('aria-expanded', collapsed ? 'false' : 'true')
+  const label = collapseButtonLabel(collapsed)
+  button.setAttribute('aria-label', label)
+  if (button instanceof HTMLElement) button.title = label
+}
+
+/** 设置某个代码块的收起状态（`is-collapsed` 决定内容是否隐藏，见 code.css）。 */
+export function setCodeBlockCollapsed(block: Element | null, collapsed: boolean): void {
+  if (!block) return
+  block.classList.toggle(CODE_BLOCK_COLLAPSED_CLASS, collapsed)
+  applyCollapseChrome(block.querySelector('.tn-code-block__collapse-btn'), collapsed)
+}
+
+/** 切换收起状态，返回切换后的状态。 */
+export function toggleCodeBlockCollapsed(block: Element | null): boolean {
+  const next = !isCodeBlockCollapsed(block)
+  setCodeBlockCollapsed(block, next)
+  return next
+}
+
+/**
+ * 展开 root 里所有被收起的代码块。
+ *
+ * 代码分组切换 tab 时用它：新露出来的面板如果是收起状态，自动展开，
+ * 读者不会只看到一个标题栏。
+ */
+export function expandCollapsedCodeBlocks(root: ParentNode | null | undefined): void {
+  if (!root) return
+  if ('classList' in root && isCodeBlockCollapsed(root as Element)) {
+    setCodeBlockCollapsed(root as Element, false)
+  }
+  root
+    .querySelectorAll<HTMLElement>(`.tn-code-block.${CODE_BLOCK_COLLAPSED_CLASS}`)
+    .forEach((block) => setCodeBlockCollapsed(block, false))
+}

package/src/code/highlight.ts

@@ -2,6 +2,18 @@ import { createHighlighterCore, type HighlighterCore, type ShikiTransformer } fr
 import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
 import { bundledLanguages, bundledLanguagesAlias } from 'shiki/langs'
 
+export {
+  CODE_BLOCK_COLLAPSED_CLASS,
+  applyCollapseChrome,
+  codeBlockFrom,
+  codeBlockIn,
+  collapseButtonLabel,
+  expandCollapsedCodeBlocks,
+  isCodeBlockCollapsed,
+  setCodeBlockCollapsed,
+  toggleCodeBlockCollapsed
+} from './collapse'
+
 export interface CodeMeta {
   language: string
   title: string

package/src/components/CodeBlock/CodeBlock.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed, onBeforeUnmount, onServerPrefetch, ref, watch } from 'vue'
 import { highlightCode, parseCodeMeta } from '../../code/highlight'
+import { toggleCodeBlockCollapsed } from '../../code/collapse'
 import { copyText } from '../../browser/clipboard'
 
 const props = withDefaults(
@@ -14,6 +15,11 @@ const props = withDefaults(
   { info: '', lineNumbers: true }
 )
 const meta = computed(() => parseCodeMeta(props.info, props.lineNumbers))
+/**
+ * 折叠是**纯视图状态**：默认展开、不落库、不写 localStorage，刷新后回到展开。
+ * 每个代码块标题左侧都有折叠 Icon，点击把代码内容整体隐藏 / 显示。
+ */
+const root = ref<HTMLElement>()
 const html = ref(props.highlightedHtml || '')
 const error = ref('')
 const copied = ref(false)
@@ -53,6 +59,9 @@ async function copy(): Promise<void> {
     error.value = '复制失败，请检查剪贴板权限'
   }
 }
+function toggleCollapse(): void {
+  toggleCodeBlockCollapsed(root.value ?? null)
+}
 function closeFullscreen(): void {
   fullscreen.value = false
   trigger.value?.focus({ preventScroll: true })
@@ -64,15 +73,38 @@ onBeforeUnmount(() => {
 </script>
 
 <template>
-  <section class="tn-code-block" :class="{ 'has-line-numbers': meta.lineNumbers }">
+  <section ref="root" class="tn-code-block" :class="{ 'has-line-numbers': meta.lineNumbers }">
     <header class="tn-code-block__header">
+      <button
+        type="button"
+        class="tn-code-block__icon-btn tn-code-block__collapse-btn"
+        aria-expanded="true"
+        aria-label="收起代码"
+        title="收起代码"
+        @click="toggleCollapse"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path d="m6 9 6 6 6-6" />
+        </svg>
+      </button>
       <span class="tn-code-block__title">{{ title || meta.title }}</span>
       <slot name="language" :language="meta.language"
         ><span class="tn-code-block__language">{{ meta.language }}</span></slot
       >
       <button
         type="button"
-        class="tn-code-block__icon-btn"
+        class="tn-code-block__icon-btn tn-code-block__copy-btn"
         :aria-label="copied ? '已复制' : '复制代码'"
         @click="copy"
       >
@@ -111,7 +143,7 @@ onBeforeUnmount(() => {
       <button
         ref="trigger"
         type="button"
-        class="tn-code-block__icon-btn"
+        class="tn-code-block__icon-btn tn-code-block__fullscreen-btn"
         aria-label="全屏代码"
         @click="fullscreen = true"
       >
@@ -135,8 +167,10 @@ onBeforeUnmount(() => {
       </button>
     </header>
     <slot>
-      <div v-if="html" class="tn-code-block__content" v-html="html" />
-      <pre v-else class="tn-code-block__plain"><code>{{ code }}</code></pre>
+      <div class="tn-code-block__content">
+        <div v-if="html" v-html="html" />
+        <pre v-else class="tn-code-block__plain"><code>{{ code }}</code></pre>
+      </div>
     </slot>
     <p v-if="error" role="status" class="tn-code-block__error">{{ error }}</p>
     <Teleport v-if="fullscreen" to="body">

package/src/components/CodeGroup/CodeGroup.vue

@@ -2,6 +2,13 @@
 import { nextTick, onMounted, ref, watch } from 'vue'
 import CodeBlock from '../CodeBlock/CodeBlock.vue'
 import { parseCodeMeta } from '../../code/highlight'
+import {
+  applyCollapseChrome,
+  codeBlockIn,
+  expandCollapsedCodeBlocks,
+  isCodeBlockCollapsed,
+  toggleCodeBlockCollapsed
+} from '../../code/collapse'
 
 export interface CodeGroupItem {
   code?: string
@@ -11,16 +18,47 @@ export interface CodeGroupItem {
 }
 const props = defineProps<{ items: CodeGroupItem[] }>()
 const root = ref<HTMLElement>()
+const collapseButton = ref<HTMLButtonElement>()
 const active = ref(0)
-function syncPanels(): void {
-  const panels =
-    root.value?.querySelectorAll<HTMLElement>(
+
+function panels(): HTMLElement[] {
+  return [
+    ...(root.value?.querySelectorAll<HTMLElement>(
       ':scope > .tn-code-group__panels > .tn-code-group__panel'
-    ) ?? []
-  panels.forEach((panel, index) => {
+    ) ?? [])
+  ]
+}
+
+function activePanel(): HTMLElement | null {
+  return panels()[active.value] ?? null
+}
+
+function activeBlock(): HTMLElement | null {
+  return codeBlockIn(activePanel())
+}
+
+function toggleCollapse(): void {
+  const block = activeBlock()
+  if (!block) return
+  toggleCodeBlockCollapsed(block)
+  applyCollapseChrome(collapseButton.value ?? null, isCodeBlockCollapsed(block))
+}
+
+/** 面板自带的那颗折叠按钮在分组里会被 tab 行盖住，所以 chrome 挂在 tab 行这颗上。 */
+function syncCollapseButton(): void {
+  applyCollapseChrome(collapseButton.value ?? null, isCodeBlockCollapsed(activeBlock()))
+}
+
+function syncPanels(): void {
+  const list = panels()
+  list.forEach((panel, index) => {
     panel.hidden = index !== active.value
   })
+  // 切到的面板如果处于收起状态就自动展开：读者不该看到一片被裁掉的代码。
+  expandCollapsedCodeBlocks(activePanel())
+  syncCollapseButton()
 }
+
 watch(active, syncPanels, { flush: 'post' })
 watch(
   () => props.items.length,
@@ -30,6 +68,7 @@ watch(
   }
 )
 onMounted(syncPanels)
+
 function navigate(event: KeyboardEvent, index: number): void {
   let next = index
   if (event.key === 'ArrowRight') next = (index + 1) % props.items.length
@@ -40,19 +79,43 @@ function navigate(event: KeyboardEvent, index: number): void {
   event.preventDefault()
   active.value = next
   ;(event.currentTarget as HTMLElement).parentElement
-    ?.querySelectorAll<HTMLButtonElement>('button')
+    ?.querySelectorAll<HTMLButtonElement>('button[role="tab"]')
     [next]?.focus()
 }
 </script>
 
 <template>
-  <section ref="root" class="tn-code-group">
+  <section ref="root" class="tn-code-group" :class="{ 'has-tabs': items.length > 1 }">
     <div
       v-if="items.length > 1"
       class="tn-code-group__tabs code-group-tabs"
       role="tablist"
       aria-label="代码分组"
     >
+      <button
+        ref="collapseButton"
+        type="button"
+        class="tn-code-block__icon-btn tn-code-group__collapse-btn"
+        aria-expanded="true"
+        aria-label="收起代码"
+        title="收起代码"
+        @click="toggleCollapse"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path d="m6 9 6 6 6-6" />
+        </svg>
+      </button>
       <button
         v-for="(item, index) in items"
         :key="item.key || index"

package/src/components/Mindmap/Mindmap.vue

@@ -786,19 +786,20 @@ onBeforeUnmount(() => {
   transition: opacity 0.2s;
 }
 
-/* Editable Desk island: chrome must stay hittable. */
-.mindmap-preview.is-editable > .mindmap-preview-actions {
-  opacity: 1;
-  pointer-events: auto;
-}
-
+/* 工具条按需出现：hover、聚焦（键盘 Tab 进来也算）、画布交互中、全屏。
+   Desk 的可编辑岛原本额外钉了 `opacity: 1`（旧注释：“chrome must stay hittable”），
+   结果每张脑图右上角常驻一排按钮，既像噪声又占掉画布右上角的拖拽区；
+   可点击性并没丢 —— 指针进入即 hover 显现，`:focus-within` 保住键盘路径。
+   只读岛（站点）本来就是这套行为，这里让两边一致。 */
 .mindmap-preview-tabs {
   display: flex;
   gap: 4px;
 }
 
 .mindmap-preview:hover > .mindmap-preview-actions,
+.mindmap-preview:focus-within > .mindmap-preview-actions,
 .mindmap-preview-actions:focus-within,
+.mindmap-preview.is-interaction-active > .mindmap-preview-actions,
 .mindmap-preview.is-fullscreen > .mindmap-preview-actions,
 .mindmap-preview:fullscreen > .mindmap-preview-actions {
   opacity: 1;