@tnotesjs/core 0.3.0 → 0.4.0

package/vitepress/components/MindmapPreview/compat.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  normalizeMindmapMarkdown,
+  parseMarkmapFence,
+  parseMindmapReference,
+} from './compat'
+
+describe('parseMarkmapFence', () => {
+  it.each([
+    ['```markmap', {}],
+    ['```markmap 2', { initialExpandLevel: 2 }],
+    ['```markmap {2}', { initialExpandLevel: 2 }],
+    ['```markmap {initialExpandLevel=3}', { initialExpandLevel: 3 }],
+    ['```markmap [ESM 模块] 2', { title: 'ESM 模块', initialExpandLevel: 2 }],
+    ['```markmap 2 [ESM 模块]', { title: 'ESM 模块', initialExpandLevel: 2 }],
+    ['```mindmap', {}],
+    ['```mindmap [项目架构] 1', { title: '项目架构', initialExpandLevel: 1 }],
+  ])('parses %s', (input, expected) => {
+    expect(parseMarkmapFence(input)).toEqual(expected)
+  })
+})
+
+describe('parseMindmapReference', () => {
+  it.each([
+    ['<<< ./assets/tree.md', { path: './assets/tree.md' }],
+    ['<<< ./assets/tree.md [项目架构]', { path: './assets/tree.md', title: '项目架构' }],
+    ['<<< "./assets/tree with spaces.md" [项目架构]', { path: './assets/tree with spaces.md', title: '项目架构' }],
+  ])('parses %s', (input, expected) => {
+    expect(parseMindmapReference(input)).toEqual(expected)
+  })
+})
+
+describe('normalizeMindmapMarkdown', () => {
+  it('injects the default root for historical unordered-list input', () => {
+    expect(normalizeMindmapMarkdown('- A\n  - B')).toBe('# root\n\n- A\n  - B\n')
+  })
+
+  it('promotes a single legacy root item instead of rendering duplicate roots', () => {
+    expect(normalizeMindmapMarkdown('- root\n  - item1\n  - item2')).toBe(
+      '# root\n\n- item1\n- item2\n',
+    )
+    expect(normalizeMindmapMarkdown('- Custom\n  - item', { title: 'Custom' })).toBe(
+      '# Custom\n\n- item\n',
+    )
+  })
+
+  it('does not promote a matching root item when it has top-level siblings', () => {
+    expect(normalizeMindmapMarkdown('- root\n  - nested\n- sibling')).toBe(
+      '# root\n\n- root\n  - nested\n- sibling\n',
+    )
+  })
+
+  it('preserves an existing H1 and lets explicit fence metadata override it', () => {
+    const source = '# Existing\n\n- A\n'
+    expect(normalizeMindmapMarkdown(source)).toBe(source)
+    expect(normalizeMindmapMarkdown(source, { title: 'Explicit' })).toBe('# Explicit\n\n- A\n')
+  })
+
+  it('converts legacy H2/H3 sections into a nested unordered-list tree', () => {
+    const source = [
+      '# ESM',
+      '',
+      '## 基本语法',
+      '',
+      '### 导出方式',
+      '',
+      '- 命名导出',
+      '  - 统一导出',
+      '### 导入方式',
+      '- 默认导入',
+    ].join('\n')
+
+    expect(normalizeMindmapMarkdown(source)).toBe([
+      '# ESM',
+      '',
+      '- 基本语法',
+      '',
+      '  - 导出方式',
+      '',
+      '    - 命名导出',
+      '      - 统一导出',
+      '  - 导入方式',
+      '    - 默认导入',
+      '',
+    ].join('\n'))
+  })
+
+  it('is stable when normalized more than once', () => {
+    const once = normalizeMindmapMarkdown('- A\n  - B')
+    expect(normalizeMindmapMarkdown(once)).toBe(once)
+  })
+})

package/vitepress/components/MindmapPreview/compat.ts

@@ -0,0 +1,128 @@
+export interface MarkmapFenceOptions {
+  title?: string
+  initialExpandLevel?: number
+}
+
+export interface MindmapReference {
+  path: string
+  title?: string
+}
+
+function cleanHeadingText(value: string): string {
+  return value.trim().replace(/\s+#+\s*$/, '').trim()
+}
+
+function promoteLegacyRootList(body: string[], rootTitle: string): string[] {
+  const firstContentIndex = body.findIndex((line) => line.trim() !== '')
+  if (firstContentIndex < 0) return body
+
+  const firstItem = body[firstContentIndex].match(/^[-+*]\s+(.+?)\s*$/)
+  if (!firstItem || cleanHeadingText(firstItem[1]) !== rootTitle) return body
+
+  const descendants = body.slice(firstContentIndex + 1)
+  if (descendants.some((line) => line.trim() !== '' && !/^\s{2,}/.test(line))) return body
+
+  return [
+    ...body.slice(0, firstContentIndex),
+    ...descendants.map((line) => line.replace(/^ {2}/, '')),
+  ]
+}
+
+/** Parse the opening fence while retaining every legacy expand-level spelling. */
+export function parseMarkmapFence(openLine: string): MarkmapFenceOptions {
+  const fenceBody = openLine.trim().replace(/^`+\s*/, '')
+  const nameMatch = fenceBody.match(/^(mindmap|markmap)(?=\s|\{|\[|$)/)
+  if (!nameMatch) return {}
+  let rest = fenceBody.slice(nameMatch[1].length).trim()
+  const options: MarkmapFenceOptions = {}
+
+  const titleMatch = rest.match(/\[([^\]]+)\]/)
+  if (titleMatch) {
+    options.title = titleMatch[1].trim()
+    rest = `${rest.slice(0, titleMatch.index)} ${rest.slice((titleMatch.index ?? 0) + titleMatch[0].length)}`.trim()
+  }
+
+  const braceMatch = rest.match(/\{([^}]*)\}/)
+  const paramPart = braceMatch ? braceMatch[1].trim() : rest
+  const tokens = paramPart.match(/"[^"]*"|'[^']*'|\S+/g) ?? []
+  for (const [index, token] of tokens.entries()) {
+    if (/^\d+$/.test(token) && index === 0) {
+      options.initialExpandLevel = Number(token)
+      continue
+    }
+    const pair = token.match(/^([^=:\s]+)\s*(?:=|:)\s*(.+)$/)
+    if (!pair || pair[1] !== 'initialExpandLevel') continue
+    const value = pair[2].replace(/^['"]|['"]$/g, '')
+    if (/^\d+$/.test(value)) options.initialExpandLevel = Number(value)
+  }
+  return options
+}
+
+/** Parse `<<< file.md [title]`; the title is optional and paths may be quoted. */
+export function parseMindmapReference(line: string): MindmapReference | null {
+  const match = line.trim().match(/^<<<\s+(.+?)\s*$/)
+  if (!match) return null
+
+  let rest = match[1].trim()
+  let title: string | undefined
+  const titleMatch = rest.match(/\s+\[([^\]]+)\]\s*$/)
+  if (titleMatch) {
+    title = cleanHeadingText(titleMatch[1]) || undefined
+    rest = rest.slice(0, titleMatch.index).trim()
+  }
+
+  const path = rest.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/, '$1$2').trim()
+  return path ? { path, title } : null
+}
+
+export interface NormalizeMindmapOptions {
+  title?: string
+  defaultTitle?: string
+}
+
+/** Convert historical VitePress markmap input into the strict mindmap-core format. */
+export function normalizeMindmapMarkdown(
+  source: string,
+  options: NormalizeMindmapOptions = {},
+): string {
+  const lines = source.replace(/\r\n?/g, '\n').split('\n')
+  let existingTitle = ''
+  let rootIndex = -1
+
+  for (let index = 0; index < lines.length; index++) {
+    const match = lines[index].match(/^\s{0,3}#(?!#)\s+(.+?)\s*$/)
+    if (!match) continue
+    existingTitle = cleanHeadingText(match[1])
+    rootIndex = index
+    break
+  }
+
+  const rootTitle = cleanHeadingText(options.title || existingTitle || options.defaultTitle || 'root') || 'root'
+  const body: string[] = []
+  let headingDepth: number | null = null
+
+  for (let index = 0; index < lines.length; index++) {
+    if (index === rootIndex) continue
+    const line = lines[index]
+    const heading = line.match(/^\s{0,3}(#{2,6})\s+(.+?)\s*$/)
+    if (heading) {
+      headingDepth = heading[1].length - 2
+      body.push(`${'  '.repeat(headingDepth)}- ${cleanHeadingText(heading[2])}`)
+      continue
+    }
+
+    const listItem = line.match(/^(\s*)([-+*])\s+(.+)$/)
+    if (listItem && headingDepth !== null) {
+      body.push(`${'  '.repeat(headingDepth + 1)}${line}`)
+      continue
+    }
+    body.push(line)
+  }
+
+  const normalizedBody = promoteLegacyRootList(body, rootTitle)
+  while (normalizedBody[0]?.trim() === '') normalizedBody.shift()
+  while (normalizedBody[normalizedBody.length - 1]?.trim() === '') normalizedBody.pop()
+  return normalizedBody.length > 0
+    ? `# ${rootTitle}\n\n${normalizedBody.join('\n')}\n`
+    : `# ${rootTitle}\n`
+}

package/vitepress/components/MindmapPreview/expandLevel.test.ts

@@ -0,0 +1,40 @@
+import { MindmapSession } from '@tnotesjs/mindmap-core'
+import { describe, expect, it } from 'vitest'
+
+import { applyInitialExpandLevel, normalizeExpandLevel } from './expandLevel'
+
+function createSession(): MindmapSession {
+  return new MindmapSession({
+    markdown: '# root\n\n- 一级\n  - 二级\n    - 三级\n',
+    fileName: 'expand-level.tn-mindmap.md',
+  })
+}
+
+function visibleLabels(session: MindmapSession): string[] {
+  const result: string[] = []
+  const visit = (node: typeof session.document.root) => {
+    result.push(node.content.text)
+    if (!node.collapsed) node.children.forEach(visit)
+  }
+  visit(session.document.root)
+  return result
+}
+
+describe('applyInitialExpandLevel', () => {
+  it('clamps the minimum level to one', () => {
+    expect(normalizeExpandLevel(0)).toBe(1)
+    expect(normalizeExpandLevel(-2)).toBe(1)
+  })
+
+  it('shows only root and first-level children for level one', () => {
+    const session = createSession()
+    applyInitialExpandLevel(session, 1)
+    expect(visibleLabels(session)).toEqual(['root', '一级'])
+  })
+
+  it('shows root, first-level and second-level children for level two', () => {
+    const session = createSession()
+    applyInitialExpandLevel(session, 2)
+    expect(visibleLabels(session)).toEqual(['root', '一级', '二级'])
+  })
+})

package/vitepress/components/MindmapPreview/expandLevel.ts

@@ -0,0 +1,28 @@
+import type { MindmapNode, MindmapSession } from '@tnotesjs/mindmap-core'
+
+export function normalizeExpandLevel(value: number): number {
+  return Math.max(1, Math.trunc(Number(value) || 1))
+}
+
+function childLevel(node: MindmapNode, root: MindmapNode): number {
+  let level = 0
+  let current: MindmapNode | null = node
+  while (current && current !== root) {
+    level += 1
+    current = current.parent
+  }
+  return level
+}
+
+/**
+ * Level 1 renders root + direct children; level 2 additionally renders
+ * grandchildren. Nodes at the last visible level are collapsed.
+ */
+export function applyInitialExpandLevel(session: MindmapSession, value: number): void {
+  const visibleLevel = normalizeExpandLevel(value)
+  const root = session.document.root
+  session.document.traverse((node) => {
+    if (node === root || node.children.length === 0) return
+    session.setCollapsed(node.id, childLevel(node, root) >= visibleLevel)
+  })
+}

package/vitepress/components/MindmapPreview/legacyCorpus.test.ts

@@ -0,0 +1,57 @@
+import { parseMarkdown } from '@tnotesjs/mindmap-core'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+import {
+  normalizeMindmapMarkdown,
+  parseMarkmapFence,
+  parseMindmapReference,
+} from './compat'
+
+const tnotesRoot = path.resolve(fileURLToPath(new URL('../../../../', import.meta.url)))
+const noteFiles = [
+  'TNotes.canvas/notes/0035. 使用 ctx.drawImage 引入图像/README.md',
+  'TNotes.docs/notes/0013. Mindmap/README.md',
+  'TNotes.docs/notes/0014. 分仓库模式/README.md',
+  'TNotes.javascript/notes/0070. CommonJS/README.md',
+  'TNotes.javascript/notes/0071. ESM/README.md',
+  'TNotes.sql/notes/0001. MySQL 8 从入门到精通/README.md',
+  'TNotes.vite/notes/0014. vite 思维导图/README.md',
+].map((relative) => path.join(tnotesRoot, relative))
+
+const corpusAvailable = noteFiles.every((file) => fs.existsSync(file))
+
+describe.skipIf(!corpusAvailable)('legacy TNotes markmap corpus', () => {
+  it('normalizes every historical block into valid mindmap-core Markdown', () => {
+    const diagnostics: string[] = []
+    let blockCount = 0
+
+    for (const noteFile of noteFiles) {
+      const note = fs.readFileSync(noteFile, 'utf8')
+      const blocks = note.matchAll(/^(```(?:mindmap|markmap)[^\n]*)\n([\s\S]*?)^```\s*$/gm)
+      for (const match of blocks) {
+        blockCount += 1
+        const options = parseMarkmapFence(match[1])
+        let source = match[2]
+        const reference = parseMindmapReference(
+          source.split('\n').find((line) => line.trim()) ?? '',
+        )
+        if (reference) {
+          source = fs.readFileSync(path.resolve(path.dirname(noteFile), reference.path), 'utf8')
+        }
+        const normalized = normalizeMindmapMarkdown(source, {
+          title: options.title || reference?.title,
+        })
+        const result = parseMarkdown(normalized, path.basename(noteFile))
+        if (!result.valid) {
+          diagnostics.push(`${noteFile}\n${result.diagnostics.map((item) => item.message).join('\n')}`)
+        }
+      }
+    }
+
+    expect(blockCount).toBe(16)
+    expect(diagnostics).toEqual([])
+  })
+})

package/vitepress/configs/markdown.config.ts

@@ -11,6 +11,11 @@ import markdownItTaskLists from 'markdown-it-task-lists'
 import path from 'path'
 
 import { generateAnchor } from '../../utils'
+import {
+  normalizeMindmapMarkdown,
+  parseMarkmapFence,
+  parseMindmapReference,
+} from '../components/MindmapPreview/compat'
 
 import type MarkdownIt from 'markdown-it'
 import type { MarkdownOptions } from 'vitepress'
@@ -66,17 +71,13 @@ const simpleMermaidMarkdown = (md: MarkdownIt) => {
 }
 
 /**
- * MarkMap 容器配置
+ * Mindmap 容器配置（兼容旧的 markmap 围栏名）
  */
-function configureMarkMapContainer(md: MarkdownIt) {
-  // 先保留 container 的解析（负责把 ```markmap ``` 识别成 container tokens）
-  // 但让它本身不输出任何 HTML（render 返回空）
+function configureMindmapContainer(md: MarkdownIt) {
   md.use(markdownItContainer, 'markmap', {
     marker: '`',
     validate(params: string) {
-      // 接受 "markmap", "markmap{...}" 或 "markmap key=val ..." 等写法
-      const p = (params || '').trim()
-      return p.startsWith('markmap')
+      return (params || '').trim().startsWith('markmap')
     },
     render() {
       return ''
@@ -93,11 +94,13 @@ function configureMarkMapContainer(md: MarkdownIt) {
     for (let i = 0; i < tokens.length; i++) {
       const t = tokens[i]
       if (t.type === 'container_markmap_open') {
+        const containerName = 'markmap'
+        const closeType = 'container_markmap_close'
         // 找到对应的 close token
         let j = i + 1
         while (
           j < tokens.length &&
-          tokens[j].type !== 'container_markmap_close'
+          tokens[j].type !== closeType
         )
           j++
         if (j >= tokens.length) continue // safety
@@ -109,9 +112,12 @@ function configureMarkMapContainer(md: MarkdownIt) {
 
         // 1) 从开头 fence 行解析参数（支持 `{a=1 b="x"}`、`a=1 b="x"`，并支持单个数字 shorthand）
         const params: { [key: string]: any; initialExpandLevel?: number } = {}
+        let explicitTitle: string | undefined
 
         if (open.map && typeof open.map[0] === 'number') {
           const openLine = (lines[open.map[0]] || '').trim()
+          const fenceOptions = parseMarkmapFence(openLine)
+          explicitTitle = fenceOptions.title
           let paramPart = ''
 
           // 优先匹配大括号形式 ```markmap{...}
@@ -121,10 +127,13 @@ function configureMarkMapContainer(md: MarkdownIt) {
           } else {
             // 否则尝试去掉前缀 ``` 和 markmap，剩下的作为参数部分
             const after = openLine.replace(/^`+\s*/, '')
-            if (after.startsWith('markmap')) {
-              paramPart = after.slice('markmap'.length).trim()
+            if (after.startsWith(containerName)) {
+              paramPart = after.slice(containerName.length).trim()
             }
           }
+          if (fenceOptions.initialExpandLevel !== undefined) {
+            params.initialExpandLevel = fenceOptions.initialExpandLevel
+          }
 
           if (paramPart) {
             // 使用正则按 token 切分：保持用引号包裹的片段为单个 token（支持包含空格）
@@ -179,10 +188,11 @@ function configureMarkMapContainer(md: MarkdownIt) {
         // --- 检查第一非空行是否为引用语法 ---
         const firstNonEmptyLine =
           (content || '').split('\n').find((ln) => ln.trim() !== '') || ''
-        const refMatch = firstNonEmptyLine.trim().match(/^<<<\s*(.+)$/)
-        if (refMatch) {
-          // 提取引用路径，支持引号包裹
-          const refRaw = refMatch[1].trim().replace(/^['"]|['"]$/g, '')
+        const reference = parseMindmapReference(firstNonEmptyLine)
+        let referencedTitle: string | undefined
+        if (reference) {
+          const refRaw = reference.path
+          referencedTitle = reference.title
 
           // 尝试同步读取文件内容（兼容常见 Node 环境）
           try {
@@ -213,12 +223,14 @@ function configureMarkMapContainer(md: MarkdownIt) {
           } catch (err) {
             // 读取失败：将错误写入 content 以便排查（不会让流程直接崩溃）
             const errorMsg = err instanceof Error ? err.message : String(err)
-            content = `Failed to load referenced file: ${esc(
-              String(refRaw)
-            )}\n\nError: ${esc(errorMsg)}`
+            content = `- Failed to load referenced file: ${esc(String(refRaw))}\n  - Error: ${esc(errorMsg)}`
           }
         }
 
+        content = normalizeMindmapMarkdown(content, {
+          title: explicitTitle || referencedTitle,
+        })
+
         // 3) 构造组件标签并把参数注入为 props
         const encodedContent = encodeURIComponent(content.trim())
         let propsStr = `content="${encodedContent}"`
@@ -232,7 +244,7 @@ function configureMarkMapContainer(md: MarkdownIt) {
           }
         }
 
-        const html = `<MarkMap ${propsStr}></MarkMap>\n`
+        const html = `<MindmapPreview ${propsStr}></MindmapPreview>\n`
 
         // 创建 html_block token
         const htmlToken = new state.Token('html_block', '', 0)
@@ -247,6 +259,50 @@ function configureMarkMapContainer(md: MarkdownIt) {
   })
 }
 
+/** Canonical `mindmap` fence. Legacy `markmap` stays on its historical container path. */
+function configureMindmapFence(md: MarkdownIt) {
+  const fence = md.renderer.rules.fence
+    ? md.renderer.rules.fence.bind(md.renderer.rules)
+    : () => ''
+
+  md.renderer.rules.fence = (tokens, index, options, env, slf) => {
+    const token = tokens[index]
+    const info = token.info.trim()
+    if (!/^mindmap(?=\s|\{|\[|$)/.test(info)) {
+      return fence(tokens, index, options, env, slf)
+    }
+
+    const fenceOptions = parseMarkmapFence(info)
+    let content = token.content
+    const firstNonEmptyLine = content.split('\n').find((line) => line.trim()) ?? ''
+    const reference = parseMindmapReference(firstNonEmptyLine)
+
+    if (reference) {
+      const possibleRel = env?.relativePath || env?.path || env?.filePath || env?.file || ''
+      const refFullPath = path.isAbsolute(reference.path)
+        ? reference.path
+        : path.resolve(process.cwd(), possibleRel ? path.dirname(possibleRel) : '', reference.path)
+      try {
+        content = fs.readFileSync(refFullPath, 'utf8')
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        content = `- Failed to load referenced file: ${reference.path}\n  - Error: ${message}`
+      }
+    }
+
+    content = normalizeMindmapMarkdown(content, {
+      title: fenceOptions.title || reference?.title,
+    })
+    const props = [
+      `content="${encodeURIComponent(content.trim())}"`,
+      fenceOptions.initialExpandLevel === undefined
+        ? ''
+        : `:initialExpandLevel="${fenceOptions.initialExpandLevel}"`,
+    ].filter(Boolean).join(' ')
+    return `<MindmapPreview ${props}></MindmapPreview>\n`
+  }
+}
+
 /**
  * Swiper 容器配置
  */
@@ -340,8 +396,9 @@ export function getMarkdownConfig(): MarkdownOptions {
       // 添加 Mermaid 支持
       simpleMermaidMarkdown(md)
 
-      // 添加 MarkMap 支持
-      configureMarkMapContainer(md)
+      // 添加 Mindmap 支持，并继续兼容旧 MarkMap 围栏
+      configureMindmapContainer(md)
+      configureMindmapFence(md)
 
       // 添加任务列表支持
       md.use(markdownItTaskLists)

package/vitepress/theme/index.ts

@@ -22,8 +22,8 @@ import Footprints from '../components/Footprints/Footprints.vue'
 import { useRenameOverlay } from '../components/Layout/composables/useRenameOverlay'
 import { redirectAfterRename } from '../components/Layout/composables/useRenameRedirect'
 import Layout from '../components/Layout/Layout.vue'
-import MarkMap from '../components/MarkMap/MarkMap.vue'
 import Mermaid from '../components/Mermaid/Mermaid.vue'
+import MindmapPreview from '../components/MindmapPreview/MindmapPreview.vue'
 import NotesTable from '../components/NotesTable/NotesTable.vue'
 import SidebarCard from '../components/SidebarCard/SidebarCard.vue'
 import Tooltip from '../components/Tooltip/Tooltip.vue'
@@ -45,7 +45,9 @@ function registerCoreComponents(ctx: EnhanceAppContext) {
   app.component('Footprints', Footprints)
   app.component('F', Footprints)
   app.component('SidebarCard', SidebarCard)
-  app.component('MarkMap', MarkMap)
+  // Keep the historical component name so existing note fences need no migration.
+  app.component('MarkMap', MindmapPreview)
+  app.component('MindmapPreview', MindmapPreview)
   app.component('Mermaid', Mermaid)
   app.component('NotesTable', NotesTable)
   app.component('N', NotesTable)

package/vitepress/theme/styles/index.scss

@@ -17,7 +17,6 @@
 
 /* 4. 组件全局层：跨组件共享的样式 */
 @use './components/swiper';
-@use './components/markmap';
 @use './components/collapse';
 /**
  * !404 不是一个有效的 Sass 标识符（不能以数字开头），需要为它添加一个别名