2-07 · 文档站架构（下）：demo 三件套

  markdown: {
    config(md) {
      demoMdPlugin(md);
      tableWrapperMdPlugin(md);
    }
  },

/**
 * Sandbox 判断逻辑（简化版）
 *
 * 参考 Element Plus 的处理方式：不做复杂的 AST 分析，依赖组件自包含样式。
 * 仅对原生 table 系列标签启用 sandbox，因为 VitePress prose 样式对 table 有全局定义。
 *
 * 显式控制：
 * - <!-- demo-sandbox:on --> 强制开启
 * - <!-- demo-sandbox:off --> 强制关闭
 */
const tableTags = new Set(["table", "thead", "tbody", "tfoot", "tr", "th", "td"]);
const sandboxOnPattern = /<!--\s*@demo-sandbox\s*-->|<!--\s*demo-sandbox:on\s*-->/i;
const sandboxOffPattern = /<!--\s*demo-sandbox:off\s*-->/i;

function shouldEnableSandbox(source: string): boolean {
  // 显式关闭
  if (sandboxOffPattern.test(source)) {
    return false;
  }

  // 显式开启
  if (sandboxOnPattern.test(source)) {
    return true;
  }

  // 检查是否包含原生 table 标签（通过简单正则，避免复杂 AST 分析）
  const templateMatch = source.match(/<template[^>]*>([\s\S]*?)<\/template>/i);
  if (!templateMatch) {
    return false;
  }

  const templateContent = templateMatch[1];
  for (const tag of tableTags) {
    // 匹配原生标签（不带命名空间前缀，不是 xy-table 等）
    const pattern = new RegExp(`<${tag}(?:\\s|>|\\/)`, "i");
    if (pattern.test(templateContent)) {
      return true;
    }
  }

  return false;
}

function createDemoContainer(md: MarkdownRenderer): ContainerOpts {
  return {
    validate(params) {
      return /^demo\s*(.*)$/.test(params.trim());
    },

    render(tokens, idx) {
      const matched = tokens[idx].info.trim().match(/^demo\s*(.*)$/);

      if (tokens[idx].nesting === 1) {
        // 路径来源有两种语法：
        // 1. 单行: :::demo path/to/example  → 路径在 matched[1]，无描述
        // 2. 两行: :::demo description\npath/to/example\n:::  → 描述在 matched[1]，路径在后续 token 中
        // 通过路径模式（纯 ASCII 字母数字 + 连字符/斜杠/点）判断 matched[1] 是否为路径
        let sourceFile = "";
        let description = "";
        const matchedPath = matched?.[1] ?? "";
        const isPathLike = /^[a-zA-Z0-9_/.-]+$/.test(matchedPath);
        if (isPathLike) {
          sourceFile = matchedPath;
        } else {
          description = matchedPath;
          for (let i = idx + 2; i < tokens.length; i++) {
            const token = tokens[i];
            if (token.type === "container_demo_close") break;
            const content = token.children?.[0]?.content?.trim() ?? "";
            if (content && content !== ":::" && /^#[^]/.test(content) === false) {
              sourceFile = content;
              break;
            }
          }
        }

        // 解析示例文件路径
        const sourcePath = path.resolve(examplesRoot, `${sourceFile}.vue`);

        if (!sourceFile || !fs.existsSync(sourcePath)) {
          throw new Error(`Incorrect source file: ${sourceFile}`);
        }

        const demoPath = sourceFile;

        const source = fs.readFileSync(sourcePath, "utf-8");
        const jsSource = sfcTs2js(source);
        // 使用原始 sourceFile 生成组件名，与 markdown-transform.ts 保持一致
        const componentName = getDemoComponentName(sourceFile);
        const needsSandbox = shouldEnableSandbox(source);
        const renderCode = (code: string) =>
          md.render(`\`\`\`vue\n${code}${code.endsWith("\n") ? "" : "\n"}\`\`\``);
        const encodedDescription = encodeURIComponent(md.render(description));
        const sourceItems = [
          { label: "TS", raw: source, rendered: renderCode(source) },
          { label: "JS", raw: jsSource, rendered: renderCode(jsSource) }
        ];

        setDemoSource(demoPath, sourceItems);

        return `<Demo :source-loader="${componentName}SourceLoader" path="${demoPath}" description="${encodedDescription}"${needsSandbox ? " sandbox" : ""}>
  <template #source><${componentName} /></template>`;
      }

      return "</Demo>\n";
    }
  };
}

export function demoMdPlugin(md: MarkdownRenderer) {
  md.use(mdContainer, "demo", createDemoContainer(md));
}

:::demo loading 和 empty 的优先级是固定的，错误态仍然建议由页面层自己承接。
pro/pro-table/states
:::

<Demo :source-loader="XyDemoButtonBasicSourceLoader" path="button/basic" description="..." sandbox?>
  <template #source><XyDemoButtonBasic /></template>

function injectImports(code: string, id: string, demoPaths: string[]) {
  const examplesRoot = resolveExamplesRoot(id);
  const declarations = demoPaths.map((demoPath) => {
    const componentName = getDemoComponentName(demoPath);
    const examplePath = path.resolve(examplesRoot, `${demoPath}.vue`);
    let relativePath = path.relative(path.dirname(id), examplePath).replaceAll(path.sep, "/");

    if (!relativePath.startsWith(".")) {
      relativePath = `./${relativePath}`;
    }

    return [
      `const ${componentName} = defineAsyncComponent(() => import("${relativePath}"));`,
      `const ${componentName}SourceLoader = () => import("virtual:xy-demo-source:${demoPath}");`
    ].join("\n");
  });
  const injectedBlock = `import { defineAsyncComponent } from "vue";\n${declarations.join("\n")}`;

  const existingScriptSetup = code.match(/<script\s+setup\b[^>]*>/);

  if (existingScriptSetup?.index !== undefined) {
    const insertAt = existingScriptSetup.index + existingScriptSetup[0].length;

    return `${code.slice(0, insertAt)}\n${injectedBlock}${code.slice(insertAt)}`;
  }

  const script = `
<script setup lang="ts">
${injectedBlock}
</script>
`;

  const frontmatterEnds = code.indexOf("---\n", 3);

  if (frontmatterEnds >= 0) {
    return `${code.slice(0, frontmatterEnds + 4)}\n${script}${code.slice(frontmatterEnds + 4)}`;
  }

  return `${script}\n${code}`;
}

export function markdownTransform(): Plugin {
  return {
    name: "xiaoye-docs-md-transform",
    enforce: "pre",
    transform(code, id) {
      if (!id.endsWith(".md")) {
        return;
      }

      const docsRoot = `${path.sep}apps${path.sep}docs${path.sep}`;
      const isComponentDoc = id.includes(`${docsRoot}components${path.sep}`);
      const isProComponentDoc = id.includes(`${docsRoot}pro-components${path.sep}`);
      const isExampleDoc = id.includes(`${docsRoot}examples${path.sep}`);
      if (!isComponentDoc && !isProComponentDoc && !isExampleDoc) {
        return;
      }

      const demoPaths = extractDemoPaths(code);

      if (!demoPaths.length) {
        return;
      }

      return injectImports(code, id, demoPaths);
    }
  };
}

import type { Plugin } from "vite";
import { getDemoSource } from "../utils/demo-source";

const VIRTUAL_PREFIX = "virtual:xy-demo-source:";
const RESOLVED_VIRTUAL_PREFIX = `\0${VIRTUAL_PREFIX}`;

// 缓存引用，用于热更新时清空
let registryRef: Map<string, unknown> | null = null;

export function demoSourcePlugin(): Plugin {
  return {
    name: "xiaoye-docs-demo-source",
    async configureServer(_server) {
      // 获取 registry 引用
      const { getDemoSourceRegistry } = (await import("../utils/demo-source")) as {
        getDemoSourceRegistry: () => Map<string, unknown>;
      };
      registryRef = getDemoSourceRegistry();
    },
    handleHotUpdate({ file, server }) {
      if (file.endsWith(".vue") && registryRef) {
        registryRef.clear();
        server.ws.send({ type: "full-reload" });
      }
    },
    resolveId(id) {
      if (!id.startsWith(VIRTUAL_PREFIX)) {
        return;
      }

      return `${RESOLVED_VIRTUAL_PREFIX}${id.slice(VIRTUAL_PREFIX.length)}`;
    },
    load(id) {
      if (!id.startsWith(RESOLVED_VIRTUAL_PREFIX)) {
        return;
      }

      const demoPath = id.slice(RESOLVED_VIRTUAL_PREFIX.length);
      const sources = getDemoSource(demoPath);

      if (!sources) {
        throw new Error(`Missing registered demo sources: ${demoPath}`);
      }

      return `export default ${JSON.stringify(sources)};`;
    }
  };
}

export interface DemoSourceItem {
  label: string;
  raw: string;
  rendered: string;
}

const demoSourceRegistry = new Map<string, DemoSourceItem[]>();

export function setDemoSource(path: string, sources: DemoSourceItem[]) {
  demoSourceRegistry.set(path, sources);
}

export function getDemoSource(path: string) {
  return demoSourceRegistry.get(path);
}

export function getDemoSourceRegistry() {
  return demoSourceRegistry;
}

function toPascalCase(value: string) {
  return value
    .split(/[-/]/g)
    .filter(Boolean)
    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
    .join("");
}

export function getDemoComponentName(demoPath: string) {
  return `XyDemo${toPascalCase(demoPath)}`;
}

export function extractDemoPaths(code: string) {
  const lines = code.split(/\r?\n/);
  const paths: string[] = [];

  for (let index = 0; index < lines.length; index += 1) {
    const trimmed = lines[index].trim();
    const matched = trimmed.match(/^:::\s*demo\s*(.*)$/);

    if (!matched) {
      continue;
    }

    // 单行形式: :::demo path/to/example — 路径在 matched[1]
    const afterDemo = matched[1]?.trim();
    if (afterDemo) {
      // 判断 matched[1] 是否像文件路径（纯 ASCII 字母数字+连字符/斜杠/点）
      if (/^[a-zA-Z0-9_/.-]+$/.test(afterDemo)) {
        paths.push(afterDemo);
        continue;
      }
    }

    // 两行形式: :::demo description\npath/to/example\n:::
    let cursor = index + 1;

    while (cursor < lines.length) {
      const line = lines[cursor].trim();

      if (!line) {
        cursor += 1;
        continue;
      }

      if (line === ":::") {
        break;
      }

      paths.push(line);
      break;
    }
  }

  return [...new Set(paths)];
}

import { JsxEmit, ModuleKind, ScriptTarget, transpileModule } from "typescript";

export function sfcTs2js(content: string) {
  const scriptReg = /<script([\s\S]*?)lang="(ts|tsx)"([\s\S]*?)>([\s\S]*?)<\/script>/;
  const matched = content.match(scriptReg);

  if (!matched || matched.index === undefined) {
    return content;
  }

  const lang = matched[2];
  const attrsBefore = matched[1].replace(/\s+$/, "");
  const attrsAfter = matched[3].replace(/\s+$/, "");
  const script = matched[4];
  const header = content.slice(0, matched.index);
  const footer = content.slice(matched.index + matched[0].length);
  const jsLangAttr = lang === "tsx" ? ' lang="jsx"' : "";
  const attrs = `${attrsBefore}${attrsAfter}`.replace(/\s+/g, " ").trim();
  const normalizedAttrs = attrs
    .replace(/\blang="(ts|tsx)"/, "")
    .replace(/\s+/g, " ")
    .trim();
  const openTag = `<script${normalizedAttrs ? ` ${normalizedAttrs}` : ""}${jsLangAttr}>`;

  return `${header}${openTag}\n${ts2Js(script)}\n</script>${footer}`;
}

function ts2Js(content: string) {
  const beforeTransformContent = content.replace(/\n(\s)*\n/g, "\n// blankline\n");
  const result = transpileModule(beforeTransformContent, {
    compilerOptions: {
      module: ModuleKind.ESNext,
      target: ScriptTarget.ESNext,
      verbatimModuleSyntax: true,
      jsx: JsxEmit.Preserve
    }
  });

  return result.outputText
    .trim()
    .replace(/(\/\/ blankline(\n)?)+/g, "\n")
    .replace(/\nexport\s*\{\s*\};?\s*$/g, "")
    .trim();
}

import { ref } from "vue";
const kw = ref("");

import { XyCard } from "../../components";
import { ref } from "vue";
const kw = ref("");

<script setup lang="ts">
import { reactive } from "vue";

const model = reactive({
  name: ""
});

import { reactive } from "vue";
// blankline
const model = reactive({
    name: ""
});

:::demo 用 `type` 和 `plain` 快速区分主次操作，不需要先堆很多视觉变体。
button/basic
:::

<template>
  <!-- 按钮类型：展示 Button 组件的 5 种语义类型 -->
  <div class="demo-button-basic">
    <xy-card shadow="never">
      <template #header>
        <div class="demo-button-basic__header">
          <strong>基础用法</strong>
          <xy-tag status="neutral" round>语义类型</xy-tag>
        </div>
      </template>
      <xy-space wrap>
        <xy-button>默认按钮</xy-button>
        <xy-button type="primary">主要按钮</xy-button>
        <xy-button type="success">成功按钮</xy-button>
        <xy-button type="warning">提醒按钮</xy-button>
        <xy-button type="danger">危险按钮</xy-button>
      </xy-space>
    </xy-card>
  </div>
</template>

<style scoped>
.demo-button-basic {
  max-width: 640px;
}

.demo-button-basic__header {
  display: flex;
  align-items: center;
  gap: 10px;
}
</style>

const props = defineProps<{
  path: string;
  description: string;
  sandbox?: boolean;
  sourceLoader?: () => Promise<{ default: DemoSourceItem[] }>;
}>();

const storageKey = "xy-docs-demo-lang";
const expanded = ref(false);
const copied = ref(false);
const activeLang = ref("TS");
const sourceItems = ref<DemoSourceItem[]>([]);
const sourcesLoading = ref(false);
const sourcesLoaded = ref(false);
let copiedTimer: ReturnType<typeof setTimeout> | null = null;

const { theme } = useData();

const decodedDescription = computed(() => decodeURIComponent(props.description));
const currentSource = computed(
  () => sourceItems.value.find((item) => item.label === activeLang.value) ?? sourceItems.value[0]
);

async function ensureSourcesLoaded() {
  if (sourcesLoaded.value || sourcesLoading.value || !props.sourceLoader) {
    return;
  }

  sourcesLoading.value = true;

  try {
    const module = await props.sourceLoader();
    sourceItems.value = module.default.filter((item) => item.raw.trim().length > 0);
    sourcesLoaded.value = true;
  } finally {
    sourcesLoading.value = false;
  }
}

  <div class="vp-demo" :class="{ 'vp-demo--table': isTableDemo }">
    <div class="vp-demo__showcase">
      <div v-if="needsSandbox" class="xy-doc-sandbox">
        <slot name="source" />
      </div>
      <slot v-else name="source" />
    </div>

    <div v-else-if="expanded && currentSource" class="vp-demo__source">
      <div class="vp-demo__source-inner" v-html="currentSource.rendered" />
    </div>

    build: {
      // VitePress 1.6 依赖 cssCodeSplit:false 合并 CSS 并注入每个页面的 head；
      // 覆盖为 true 会导致构建产物全部样式丢失（dev 不受影响，故此前未暴露）。
      chunkSizeWarningLimit: 700,