feat(docs): add component documentation entries and refactor dialog

rendering

src/components/doc-data.ts

@@ -1,3 +1,5 @@
+import yaml from "js-yaml";
+
 export interface DocEntry {
   tag: string;
   icon: string;
@@ -5,350 +7,72 @@ export interface DocEntry {
   description: string;
   syntax: string;
   props: { name: string; type: string; default?: string; desc: string }[];
-  examples: string;
-  usage: string;
+  /** Markdown body (everything after frontmatter ---) */
+  body: string;
 }
 
-export const docEntries: DocEntry[] = [
-  {
-    tag: "md-dice",
-    icon: "🎲",
-    title: "骰子组件",
-    description: "点击文字执行掷骰，可用于属性检定、伤害投掷等场景。",
-    syntax: ':md-dice[2d6+d8]{key="attack"}',
-    props: [
-      {
-        name: "key",
-        type: "string",
-        desc: "URL 参数标识，结果记录到 ?dice-key=15",
-      },
-    ],
-    examples: `**攻击检定：** :md-dice[1d20+5]{key="attack"}
+/** Splits frontmatter and markdown body from a raw .md string. */
+function parseFrontmatter(raw: string): Record<string, unknown> | null {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return null;
+  try {
+    return yaml.load(match[1]) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
 
-**伤害掷骰：** :md-dice[2d6+3]{key="damage"}
+function getBody(raw: string): string {
+  const match = raw.match(/^---\n[\s\S]*?\n---\n?([\s\S]*)$/);
+  return match ? match[1] : raw;
+}
 
-**优势检定：** :md-dice[2d20k1+5]{key="advantage"}
+/** Glob import all .md files in src/doc-entries/ */
+const modules = import.meta.webpackContext("./", {
+  recursive: false,
+  regExp: /\.md$/,
+});
 
-点击掷骰文字执行投掷，再次点击重置为公式。`,
-    usage: "用于技能检定、攻击命中、伤害计算等需要随机数的场景。",
-  },
-  {
-    tag: "md-table",
-    icon: "📊",
-    title: "表格组件",
-    description:
-      "将 CSV 数据转换为可切换标签页的表格，支持随机抽取和变量引用。",
-    syntax: ":md-table[./data.csv]{roll=true remix=true}",
-    props: [
-      { name: "roll", type: "boolean", desc: "显示随机切换按钮" },
-      { name: "remix", type: "boolean", desc: "支持 {{prop}} 引用同行其他列" },
-    ],
-    examples: `**基础表格：**
-\`\`\`markdown
-:md-table[./npcs.csv]
-\`\`\`
+/** Lazy-loaded doc entries, parsed on first access. */
+let _entries: DocEntry[] | null = null;
 
-**带随机抽取：**
-\`\`\`markdown
-:md-table[./encounters.csv]{roll=true}
-\`\`\`
+export function loadDocEntries(): DocEntry[] {
+  if (_entries) return _entries;
 
-**随机 + 变量引用：**
-\`\`\`markdown
-:md-table[./quests.csv]{roll=true remix=true}
-\`\`\`
+  const entries: DocEntry[] = [];
 
-CSV 要求包含 label, body 列，可选 group 列分组。支持 YAML front matter 继承行属性。`,
-    usage: "用于 NPC 列表、遭遇表、宝物生成、随机事件等结构化数据。",
-  },
-  {
-    tag: "md-link",
-    icon: "🔗",
-    title: "链接组件",
-    description: "点击链接在当前页面内展开显示目标文章内容，支持章节定位。",
-    syntax: ":md-link[./rules.md#combat]",
-    props: [],
-    examples: `**展开完整文档：**
-:md-link[./rules.md]
+  for (const key of modules.keys()) {
+    const mod = modules(key);
+    const raw =
+      typeof mod === "string"
+        ? mod
+        : ((mod as { default?: string }).default ?? "");
+    if (!raw) continue;
 
-**展开特定章节：**
-:md-link[./rules.md#combat]
+    const fm = parseFrontmatter(raw);
+    if (!fm) continue;
 
-点击链接即可内联展开目标内容，再次点击折叠。`,
-    usage: "用于引用规则书章节、怪物数据、快速预览等场景。",
-  },
-  {
-    tag: "md-pins",
-    icon: "📍",
-    title: "标记组件",
-    description:
-      "在地图或图片上添加可编辑或固定的位置标记，支持字母或数字标签。",
-    syntax: ':md-pins[./images/map.png]{pins="A:30,40 B:10,30" fixed}',
-    props: [
-      {
-        name: "pins",
-        type: "string",
-        default: '""',
-        desc: '标记列表，格式 "A:x,y B:x,y"',
-      },
-      {
-        name: "fixed",
-        type: "boolean",
-        default: "false",
-        desc: "固定模式（只读不可编辑）",
-      },
-      {
-        name: "labelStart",
-        type: "string",
-        default: '"A"',
-        desc: "标签起始值，支持字母或数字",
-      },
-    ],
-    examples: `**固定标记（只读）：**
-:md-pins[./images/battle-map.png]{pins="A:25,50 B:75,30" fixed}
+    const body = getBody(raw);
 
-**可编辑标记：**
-:md-pins[./images/blank-map.png]
+    entries.push({
+      tag: fm.tag as string,
+      icon: fm.icon as string,
+      title: fm.title as string,
+      description: fm.description as string,
+      syntax: fm.syntax as string,
+      props: (fm.props as DocEntry["props"]) ?? [],
+      body,
+    });
+  }
 
-**数字标签：**
-:md-pins[./images/dungeon.png]{labelStart="1"}
+  // Sort alphabetically by tag
+  entries.sort((a, b) => a.tag.localeCompare(b.tag));
+  _entries = entries;
+  return entries;
+}
 
-非 fixed 模式下点击图片添加标记，点击标记删除。`,
-    usage: "用于战斗地图标注、地牢房间标记、任务地点指示等。",
-  },
-  {
-    tag: "md-font",
-    icon: "🔤",
-    title: "字体组件",
-    description:
-      "设置整个文档的字体和文字颜色，支持 Google Fonts、emfont 和系统本地字体三种来源。",
-    syntax:
-      ':md-font[Noto Sans SC]{source="google" weight="400" color="#ff00dd"}',
-    props: [
-      {
-        name: "source",
-        type: "google | emfont | local",
-        default: "local",
-        desc: "字体来源",
-      },
-      { name: "weight", type: "string", default: '"400"', desc: "字体粗细" },
-      {
-        name: "color",
-        type: "string",
-        desc: "文字颜色（CSS 颜色值，如 #ff00dd、rgb(255,0,0)）",
-      },
-    ],
-    examples: `**Google 字体：**
-:md-font[Noto Sans SC]{source="google"}
-
-**Emfont 字体：**
-:md-font[Source Han Serif]{source="emfont" weight="700"}
-
-**本地字体（默认）：**
-:md-font[STSong]
-
-**设置文字颜色：**
-:md-font[Noto Sans SC]{source="google" color="#1a1a2e"}
-
-:md-font[Noto Sans SC]{source="google" weight="700" color="crimson"}
-
-字体和颜色将应用到整个文档卡片。`,
-    usage: "用于切换文档的显示字体和文字颜色，适配不同风格需求。",
-  },
-  {
-    tag: "md-bg",
-    icon: "🖼️",
-    title: "背景组件",
-    description: "设置背景图片或纯色作为文章卡片背景，支持多种适配方式。",
-    syntax: ":md-bg[#ff00dd]",
-    props: [
-      {
-        name: "fit",
-        type: "cover | contain | fill | none | scale-down",
-        default: "cover",
-        desc: "背景适配方式（仅图片时生效）",
-      },
-    ],
-    examples: `**设置背景图：**
-:md-bg[./images/dungeon-bg.jpg]{fit="cover"}
-
-**设置纯色背景：**
-:md-bg[#2a1a3a]
-
-:md-bg[rgb(200,50,50)]
-
-:md-bg[#ff00dd]
-
-支持图片路径或任意 CSS 颜色值（hex、rgb、颜色名等）。`,
-    usage:
-      "用于营造场景氛围，如地牢、森林、城镇等不同环境的背景，或纯色区分不同主题。",
-  },
-  {
-    tag: "md-font",
-    icon: "🔤",
-    title: "字体组件",
-    description:
-      "设置整个文档的字体，支持 Google Fonts、emfont 和系统本地字体三种来源。",
-    syntax: ':md-font[Noto Sans SC]{source="google" weight="400"}',
-    props: [
-      {
-        name: "source",
-        type: "google | emfont | local",
-        default: "local",
-        desc: "字体来源",
-      },
-      { name: "weight", type: "string", default: '"400"', desc: "字体粗细" },
-    ],
-    examples: `**Google 字体：**
-:md-font[Noto Sans SC]{source="google"}
-
-**Emfont 字体：**
-:md-font[Source Han Serif]{source="emfont" weight="700"}
-
-**本地字体（默认）：**
-:md-font[STSong]
-
-字体将应用到整个文档卡片。`,
-    usage: "用于切换文档的显示字体，适配不同风格需求。",
-  },
-  {
-    tag: "md-border",
-    icon: "🖼️",
-    title: "边框组件",
-    description: "为文档卡片添加纯色或图片边框，支持指定边、样式和重复模式。",
-    syntax: ":md-border[#3b82f6]{.l .dashed}",
-    props: [
-      {
-        name: "width",
-        type: "string",
-        default: "纯色 .1mm，图片 2mm",
-        desc: "边框宽度",
-      },
-      {
-        name: "slice",
-        type: "string",
-        default: '"10"',
-        desc: "border-image-slice（仅图片模式）",
-      },
-    ],
-    examples: `**纯色左边框：**
-:md-border[#3b82f6]{.l}
-
-**虚线上下边框：**
-:md-border[red]{.t .b .dashed width=".2mm"}
-
-**图片边框：**
-:md-border[./images/frame.png]{.all .round}
-
-**左右图片竖条：**
-:md-border[./images/ornament.png]{.l .r .repeat}
-
-边 class：\`t\` \`b\` \`l\` \`r\` \`all\`（默认）\n样式 class：\`solid\` \`dashed\` \`dotted\` \`double\`\n图片 class：\`stretch\` \`repeat\` \`round\` \`space\``,
-    usage: "用于装饰文档卡片，配合背景和字体营造特定风格。",
-  },
-  {
-    tag: "md-embed",
-    icon: "📄",
-    title: "嵌入组件",
-    description: "将另一个 Markdown 文件的内容内联嵌入到当前文档中。",
-    syntax: ":md-embed[./rules.md#combat]",
-    props: [],
-    examples: `**嵌入完整文档：**
-:md-embed[./rules.md]
-
-**嵌入指定章节：**
-:md-embed[./rules.md#combat]
-
-嵌入后内容直接在当前位置显示，包括其中的表格、骰子等组件也会正常渲染。`,
-    usage: "用于在文档中引用通用规则、重复使用的数据表格等。",
-  },
-  {
-    tag: "md-deck",
-    icon: "🃏",
-    title: "卡牌组件",
-    description: "将 CSV 数据渲染为卡牌布局，支持自定义网格和图层的排版。",
-    syntax:
-      ':md-deck[./cards.csv]{grid="5x8" layers="title:1,1-5,1f8 body:1,5-8,8f3"}',
-    props: [
-      { name: "grid", type: "string", desc: "卡牌布局，格式 行x列" },
-      {
-        name: "layers",
-        type: "string",
-        desc: "图层定义，格式 字段:行,列-列,字号",
-      },
-    ],
-    examples: `**基础卡牌：**
-:md-deck[./spells.csv]{grid="3x3"}
-
-**多层卡牌：**
-:md-deck[./cards.csv]{grid="5x8" layers="title:1,1-5,1f8 body:1,5-8,8f3"}
-
-CSV 包含 label 和显示字段列，通过图层定义控制各字段的位置和大小。`,
-    usage: "用于法术卡、物品卡、NPC 卡等可打印的卡牌排版。",
-  },
-  {
-    tag: "md-yarn-spinner",
-    icon: "🧶",
-    title: "叙事线组件",
-    description: "展示 Yarn Spinner 格式的分支叙事结构，支持对话选择和分支。",
-    syntax: ":md-yarn-spinner[./story.yarn]",
-    props: [],
-    examples: `**加载叙事文件：**
-:md-yarn-spinner[./story.yarn]
-
-Yarn Spinner 是用于游戏对话系统的格式，支持选项、条件分支和变量。`,
-    usage: "用于互动故事、分支对话、冒险剧本等。",
-  },
-  {
-    tag: "md-token",
-    icon: "🪙",
-    title: "代币组件",
-    description: "展示游戏代币或棋子的图片。",
-    syntax: ":md-token[./token.png]",
-    props: [],
-    examples: `**展示代币：**
-:md-token[./goblin.png]
-
-代币图片自动渲染为圆形，适合战棋或卡牌中的棋子展示。`,
-    usage: "用于展示怪物代币、角色棋子、道具图标等。",
-  },
-  {
-    tag: "md-token-viewer",
-    icon: "🎨",
-    title: "代币预览组件",
-    description:
-      "使用 Three.js 在浏览器中 3D 渲染 3MF 格式的代币模型，支持旋转查看。",
-    syntax: ":md-token-viewer[./token.3mf]",
-    props: [],
-    examples: `**3D 预览模型：**
-:md-token-viewer[./dragon.3mf]
-
-支持鼠标拖拽旋转和自动旋转，从多角度查看模型细节。`,
-    usage: "用于 3D 打印前的代币模型预览。",
-  },
-  {
-    tag: "md-commander",
-    icon: "📋",
-    title: "命令追踪器",
-    description: "支持命令历史和游戏状态追踪，使用类 Emmet 语法创建追踪项。",
-    syntax: ":md-commander",
-    props: [],
-    examples: `**追踪 NPC 血量和防御：**
-\`\`\`
-track npc#john.dwarf.warrior[hp=4/4 ac=15 name="John"]
-\`\`\`
-
-**语法规则：**
-- \`#id\` 设置 ID
-- \`.class\` 添加类别
-- \`[attr=value]\` 设置属性
-
-**属性类型：**
-| 格式 | 显示 |
-|---|---|
-| x/y | 进度条 |
-| 整数 | 计数器 |
-| 文本 | 文本字段 |`,
-    usage: "用于追踪战斗中的 NPC 血量、AC、状态等游戏信息。",
-  },
-];
+/**
+ * Direct static array for the DocDialog sidebar — uses webpackContext
+ * so all .md files in doc-entries/ are bundled automatically.
+ */
+export const docEntries = loadDocEntries();