component-auto-docs 0.1.1 → 0.1.2

package/core/generate-component-docs.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { parse as parseSfc } from '@vue/compiler-sfc';
 import ts from 'typescript';
 
 const rootDir = process.cwd();
@@ -107,7 +108,7 @@ function createPageRouteEntry(routePath, title) {
       "style": {
         "navigationBarTitleText": "${title}"
       }
-    },
+},
 `;
 }
 
@@ -280,12 +281,29 @@ function readLiteralValue(node, sourceFile) {
   return node.getText(sourceFile);
 }
 
-function extractSfcBlock(source, tagName, matcher = () => true) {
-  const blockPattern = new RegExp(`<${tagName}\\b([^>]*)>([\\s\\S]*?)<\\/${tagName}>`, 'gi');
-  const blocks = [...source.matchAll(blockPattern)];
-  const block = blocks.find((item) => matcher(item[1]));
+function formatSfcParseError(error) {
+  if (typeof error === 'string') return error;
+  if (error?.message) return error.message;
 
-  return block?.[2] || '';
+  return String(error);
+}
+
+function readSfcBlocks(filePath) {
+  const source = fs.readFileSync(filePath, 'utf8');
+  const { descriptor, errors } = parseSfc(source, { filename: filePath });
+
+  if (errors.length) {
+    throw new Error(
+      `Failed to parse Vue SFC ${toPosix(path.relative(rootDir, filePath))}: ${errors
+        .map(formatSfcParseError)
+        .join('; ')}`,
+    );
+  }
+
+  return {
+    script: descriptor.scriptSetup?.content || descriptor.script?.content || '',
+    template: descriptor.template?.content || '',
+  };
 }
 
 function parseJsdoc(script) {
@@ -675,6 +693,7 @@ function normalizeExamples(metaExamples = [], jsdocExamples = []) {
     const normalized = typeof example === 'string' ? { title: '示例', description: '', code: example } : example;
     const code = normalized.code?.trim();
     if (!code || seen.has(code)) continue;
+    if (normalized.title === '基础用法' && normalized.description?.startsWith('自动根据 ')) continue;
 
     seen.add(code);
     examples.push({
@@ -687,6 +706,525 @@ function normalizeExamples(metaExamples = [], jsdocExamples = []) {
   return examples;
 }
 
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function kebabToCamel(text) {
+  return text.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function decodeHtmlText(text) {
+  return text
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+function getObjectKeyText(nameNode, sourceFile) {
+  if (!nameNode) return '';
+  if (ts.isIdentifier(nameNode) || ts.isStringLiteralLike(nameNode) || ts.isNumericLiteral(nameNode)) {
+    return nameNode.text;
+  }
+
+  return nameNode.getText(sourceFile).replace(/^['"]|['"]$/g, '');
+}
+
+function getIdentifierSampleValue(name) {
+  const samples = {
+    text: '这是一段足够长的公告文字，用于触发滚动预览效果',
+    title: '标题',
+    content: '内容',
+    label: '选项',
+    value: '1',
+    name: '名称',
+    status: 'done',
+    time: '10:30',
+    src: '/static/icon/avatar.svg',
+    url: '/static/icon/avatar.svg',
+    poster: '/static/icon/avatar.svg',
+  };
+
+  return samples[name] || name;
+}
+
+function evaluateStaticNode(node, sourceFile, bindings = {}, options = {}) {
+  if (!node) return undefined;
+
+  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)) {
+    return evaluateStaticNode(node.expression, sourceFile, bindings, options);
+  }
+
+  if (ts.isStringLiteralLike(node) || ts.isNoSubstitutionTemplateLiteral(node)) return decodeHtmlText(node.text);
+  if (ts.isNumericLiteral(node)) return Number(node.text);
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+
+  if (ts.isIdentifier(node)) {
+    if (Object.prototype.hasOwnProperty.call(bindings, node.text)) return bindings[node.text];
+
+    return options.allowIdentifierFallback ? getIdentifierSampleValue(node.text) : undefined;
+  }
+
+  if (ts.isArrayLiteralExpression(node)) {
+    return node.elements
+      .map((item) => evaluateStaticNode(item, sourceFile, bindings, { ...options, allowIdentifierFallback: true }))
+      .filter((item) => item !== undefined);
+  }
+
+  if (ts.isObjectLiteralExpression(node)) {
+    const result = {};
+
+    for (const property of node.properties) {
+      if (ts.isPropertyAssignment(property)) {
+        const key = getObjectKeyText(property.name, sourceFile);
+        if (!key) continue;
+        const value = evaluateStaticNode(property.initializer, sourceFile, bindings, {
+          ...options,
+          allowIdentifierFallback: true,
+        });
+        if (value !== undefined) result[key] = value;
+      }
+
+      if (ts.isShorthandPropertyAssignment(property)) {
+        const key = property.name.text;
+        result[key] = Object.prototype.hasOwnProperty.call(bindings, key) ? bindings[key] : getIdentifierSampleValue(key);
+      }
+    }
+
+    return result;
+  }
+
+  return undefined;
+}
+
+function evaluateStaticExpression(expression, bindings = {}) {
+  const source = `const __value = (${expression});`;
+  const sourceFile = ts.createSourceFile('preview-expression.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const statement = sourceFile.statements[0];
+  const declaration = statement?.declarationList?.declarations?.[0];
+
+  return evaluateStaticNode(declaration?.initializer, sourceFile, bindings, { allowIdentifierFallback: false });
+}
+
+function parseExampleBindings(code) {
+  const bindings = {};
+  const declarationPattern = /(?:const|let|var)\s+([\w$\u00a0-\uffff]+)\s*=\s*([^;\n]+)/g;
+  let match;
+
+  while ((match = declarationPattern.exec(code))) {
+    const [, name, expression] = match;
+    const value = evaluateStaticExpression(expression, bindings);
+    if (value !== undefined) bindings[name] = value;
+  }
+
+  return bindings;
+}
+
+function parseExampleExpression(expression, bindings = {}) {
+  const value = expression.trim();
+  if (!value) return undefined;
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === 'null') return null;
+
+  const quoted = value.match(/^(['"])([\s\S]*)\1$/);
+  if (quoted) return decodeHtmlText(quoted[2]);
+
+  if (value.startsWith('{') || value.startsWith('[')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      // Fall through to the TypeScript AST evaluator for JS-style literals.
+    }
+  }
+
+  return evaluateStaticExpression(value, bindings);
+}
+
+function coerceStaticExampleValue(rawValue, prop) {
+  if (rawValue === undefined) return true;
+
+  const type = prop?.type || '';
+  const value = decodeHtmlText(rawValue);
+  if (type.includes('array') || type.includes('Array') || type.includes('object') || type.includes('Object')) {
+    const parsed = parseExampleExpression(value);
+    if (parsed !== undefined) return parsed;
+  }
+
+  if (type.includes('boolean')) return value === 'true';
+  if (type.includes('number') || type.includes('Number')) {
+    const numberValue = Number(value);
+    return Number.isFinite(numberValue) ? numberValue : value;
+  }
+
+  return value;
+}
+
+function normalizeSlotContent(content) {
+  return decodeHtmlText(content)
+    .replace(/<[^>]+>/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+const previewKinds = new Set([
+  'inline',
+  'form',
+  'data-list',
+  'measure',
+  'overlay',
+  'page-shell',
+  'native',
+  'composite',
+]);
+
+const commentPreviewKindRules = [
+  {
+    kind: 'page-shell',
+    keywords: ['页面根', '页面容器', '页面壳', '页面布局', '标题栏', '导航栏', '状态栏', '安全区', 'safearea', 'status bar'],
+  },
+  {
+    kind: 'measure',
+    keywords: ['跑马灯', '内容超出', '超出时', '横向滚动', '循环滚动', '滚动到', '吸顶', '尺寸测量', '测量', 'selectorquery'],
+  },
+  {
+    kind: 'overlay',
+    keywords: ['弹窗', '弹层', '浮层', '遮罩', 'popover', 'popup', 'dialog', 'modal'],
+  },
+  {
+    kind: 'native',
+    keywords: ['上传', '图片预览', '预览图片', '二维码', 'qrcode', 'canvas', 'video', '视频', '拨打', '联系', '原生能力', '相册'],
+  },
+  {
+    kind: 'composite',
+    keywords: ['装修', '设计页', '楼层', '复合', '业务组件', '复杂业务'],
+  },
+  {
+    kind: 'data-list',
+    keywords: ['列表', '数据列表', '树形', '树节点', '时间线', '步骤', '瀑布流', 'tabs', '选项卡'],
+  },
+  {
+    kind: 'form',
+    keywords: ['输入', '表单', '选择', '选择器', '勾选', '单选', '多选', '开关', '验证码', 'textarea', 'input', 'radio', 'checkbox', 'switch'],
+  },
+];
+
+function normalizePreviewKind(kind) {
+  return previewKinds.has(kind) ? kind : '';
+}
+
+function textIncludesAny(text, keywords) {
+  const normalizedText = text.toLowerCase();
+
+  return keywords.some((keyword) => normalizedText.includes(keyword.toLowerCase()));
+}
+
+function inferPreviewKindFromText(text) {
+  if (!text) return '';
+
+  for (const rule of commentPreviewKindRules) {
+    if (textIncludesAny(text, rule.keywords)) return rule.kind;
+  }
+
+  return '';
+}
+
+function inferPreviewKindFromStructure(componentName, props, events, slots) {
+  const lowerName = componentName.toLowerCase();
+  const propNames = new Set(props.map((prop) => prop.name));
+  const hasModel = propNames.has('modelValue');
+  const hasListData = props.some((prop) => ['items', 'list', 'range', 'tabs', 'arr', 'data', 'options'].includes(prop.name));
+  const hasUploadLike = /upload|qrcode|video|contact/.test(lowerName);
+  const hasPageShellName = /page|header|footer|safearea|status-bar/.test(lowerName);
+  const hasOverlayName = /dialog|pop|popover|modal|popup/.test(lowerName);
+  const hasMeasureName = /marquee|tabs-scroll|swiper/.test(lowerName);
+  const hasDataName = /list|tree|timeline|steps|tabs/.test(lowerName);
+
+  if (hasPageShellName) return 'page-shell';
+  if (hasMeasureName) return 'measure';
+  if (hasOverlayName) return 'overlay';
+  if (hasUploadLike) return 'native';
+  if (/design|calculate|citys/.test(lowerName)) return 'composite';
+  if (hasDataName || hasListData) return 'data-list';
+  if (hasModel || /input|textarea|radio|checkbox|switch|slider|sms|search/.test(lowerName)) return 'form';
+  if (events.some((event) => event.name === 'click') || slots.length) return 'inline';
+
+  return 'inline';
+}
+
+function inferPreviewKind(componentName, props, events, slots, jsdoc, metaPreview) {
+  const explicitKind = normalizePreviewKind(metaPreview?.kind);
+  if (explicitKind) return explicitKind;
+
+  const jsdocKind = inferPreviewKindFromText(jsdoc.description);
+  if (jsdocKind) return jsdocKind;
+
+  return inferPreviewKindFromStructure(componentName, props, events, slots);
+}
+
+function isBooleanType(type = '') {
+  return type.toLowerCase().includes('boolean');
+}
+
+function isNumberType(type = '') {
+  return type.includes('number') || type.includes('Number');
+}
+
+function isArrayType(type = '') {
+  return type.includes('array') || type.includes('Array') || type.endsWith('[]');
+}
+
+function isObjectType(type = '') {
+  return type.includes('object') || type.includes('Object') || /\{[\s\S]*\}/.test(type);
+}
+
+function getPropByName(props, name) {
+  return props.find((prop) => prop.name === name);
+}
+
+function getFirstOptionValue(previewProps) {
+  const options = previewProps.items || previewProps.options || previewProps.range || previewProps.tabs || previewProps.list;
+  if (!Array.isArray(options) || !options.length) return undefined;
+
+  const first = options[0];
+  if (first && typeof first === 'object') return first.value ?? first.id ?? first.key ?? first.name ?? first.label;
+
+  return first;
+}
+
+function createListMock(componentName, propName) {
+  if (/timeline/.test(componentName)) {
+    return [
+      { label: '提交订单', time: '10:00' },
+      { label: '商家确认', time: '10:30' },
+    ];
+  }
+
+  if (/steps/.test(componentName)) {
+    return [
+      { name: '提交订单', status: 'done' },
+      { name: '支付成功', status: 'active' },
+      { name: '等待发货', status: 'todo' },
+    ];
+  }
+
+  if (/tree/.test(componentName)) {
+    return [
+      {
+        label: '一级节点',
+        value: '1',
+        children: [{ label: '二级节点', value: '1-1' }],
+      },
+    ];
+  }
+
+  if (/radar/.test(componentName)) {
+    return [
+      { n: '服务', p: 90 },
+      { n: '物流', p: 80 },
+      { n: '质量', p: 88 },
+    ];
+  }
+
+  if (propName === 'tabs') return ['精选', '最新', '销量'];
+  if (propName === 'range') return ['男', '女', '保密'];
+  if (propName === 'arr') {
+    return [
+      { src: '/static/icon/avatar.svg', title: '示例图片' },
+      { src: '/static/icon/tab-home.png', title: '示例图片' },
+    ];
+  }
+
+  return [
+    { label: '选项一', value: '1' },
+    { label: '选项二', value: '2' },
+  ];
+}
+
+function createObjectMock(propName) {
+  if (propName === 'value') return { label: '示例', value: '1' };
+
+  return { label: '示例', value: '1' };
+}
+
+function createNamedPropMock(componentName, prop, kind, previewProps) {
+  const { name, type } = prop;
+
+  if (name === 'modelValue') {
+    const firstOptionValue = getFirstOptionValue(previewProps);
+    if (firstOptionValue !== undefined) return firstOptionValue;
+    if (kind === 'overlay' && isBooleanType(type)) return false;
+    if (isBooleanType(type)) return true;
+    if (isNumberType(type)) return 1;
+
+    return '1';
+  }
+
+  if (name === 'checked') return true;
+  if (name === 'active') return 0;
+  if (name === 'percent') return 60;
+  if (name === 'num' || name === 'count') return 3;
+  if (name === 'phone') return '13800138000';
+  if (name === 'text') {
+    return kind === 'measure' || /marquee/.test(componentName)
+      ? '这是一段足够长的公告文字，用于触发跑马灯滚动预览效果'
+      : '示例文本';
+  }
+  if (name === 'title') return '标题';
+  if (name === 'placeholder') return '请选择';
+  if (name === 'src' || name === 'poster' || name === 'icon') return '/static/icon/avatar.svg';
+  if (name === 'code') return 'preview-code';
+  if (name === 'label') return 'label';
+  if (name === 'time') return 'time';
+  if (name === 'valueKey') return 'value';
+  if (name === 'labelKey') return 'label';
+
+  if (['items', 'list', 'range', 'tabs', 'arr', 'options'].includes(name) || isArrayType(type)) {
+    return createListMock(componentName, name);
+  }
+
+  if (isObjectType(type)) return createObjectMock(name);
+  if (isBooleanType(type)) return false;
+  if (isNumberType(type)) return 1;
+
+  return '';
+}
+
+function shouldAutoMockProp(prop, kind) {
+  if (kind === 'overlay') return ['modelValue', 'title'].includes(prop.name);
+  if (kind === 'measure') return ['text', 'tabs', 'arr', 'list'].includes(prop.name);
+  if (kind === 'data-list') return ['items', 'list', 'range', 'tabs', 'arr', 'options', 'active', 'modelValue'].includes(prop.name);
+  if (kind === 'form') return ['items', 'range', 'options', 'tabs', 'modelValue'].includes(prop.name);
+
+  return false;
+}
+
+function applyPreviewMocks(componentName, props, preview, kind) {
+  const previewProps = { ...(preview.props || {}) };
+
+  for (const prop of props) {
+    if (Object.prototype.hasOwnProperty.call(previewProps, prop.name)) continue;
+    if (!shouldAutoMockProp(prop, kind)) continue;
+
+    const value = createNamedPropMock(componentName, prop, kind, previewProps);
+    if (value !== '' && value !== undefined) previewProps[prop.name] = value;
+  }
+
+  if (kind === 'overlay') {
+    const modelProp = getPropByName(props, 'modelValue');
+    if (modelProp && isBooleanType(modelProp.type)) previewProps.modelValue = false;
+  }
+
+  const previewSlots = { ...(preview.slots || {}) };
+  if (!previewSlots.default && kind === 'overlay') previewSlots.default = '这里是弹层内容';
+  if (!previewSlots.default && props.length === 0) previewSlots.default = '内容';
+
+  return {
+    ...preview,
+    props: previewProps,
+    slots: previewSlots,
+  };
+}
+
+function inferPreviewFromExamples(componentName, props, examples, kind) {
+  const escapedName = escapeRegExp(componentName);
+  const propMap = new Map(props.map((prop) => [prop.name.toLowerCase(), prop]));
+
+  for (const example of examples) {
+    const code = example.code || '';
+    const bindings = parseExampleBindings(code);
+    const closedMatch = code.match(new RegExp(`<${escapedName}\\b([^>]*)>([\\s\\S]*?)<\\/${escapedName}>`, 'i'));
+    const selfClosingMatch = closedMatch ? null : code.match(new RegExp(`<${escapedName}\\b([^>]*)\\/\\s*>`, 'i'));
+    const match = closedMatch || selfClosingMatch;
+    if (!match) continue;
+
+    const attrs = match[1] || '';
+    const propsFromExample = {};
+    const slots = {};
+    const preview = {
+      source: 'example',
+      code: example.code,
+      props: propsFromExample,
+      slots,
+    };
+    const attrPattern = /([:@]?[\w:$-]+|v-model(?::[\w-]+)?)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+    let attrMatch;
+
+    while ((attrMatch = attrPattern.exec(attrs))) {
+      const rawName = attrMatch[1];
+      const rawValue = attrMatch[2] ?? attrMatch[3] ?? attrMatch[4];
+      if (!rawName || rawName.startsWith('@')) continue;
+
+      if (rawName.startsWith('v-model')) {
+        const [, modelName] = rawName.split(':');
+        const propName = modelName ? kebabToCamel(modelName) : 'modelValue';
+        const prop = propMap.get(propName.toLowerCase());
+        preview.vModel = {
+          prop: propName,
+          variable: rawValue || 'value',
+        };
+        if (prop?.default !== null && prop?.default !== undefined && prop.default !== '') {
+          propsFromExample[propName] = prop.default;
+        }
+        continue;
+      }
+
+      const isDynamic = rawName.startsWith(':');
+      const attrName = isDynamic ? rawName.slice(1) : rawName;
+      const propName = kebabToCamel(attrName);
+      const prop = propMap.get(propName.toLowerCase());
+      if (!prop) continue;
+
+      let value = isDynamic ? parseExampleExpression(rawValue || '', bindings) : coerceStaticExampleValue(rawValue, prop);
+      if (isDynamic && value === undefined) {
+        value = createNamedPropMock(componentName, prop, kind, propsFromExample);
+      }
+      if (value !== undefined && value !== '') propsFromExample[prop.name] = value;
+    }
+
+    if (closedMatch) {
+      const defaultSlot = normalizeSlotContent(closedMatch[2] || '');
+      if (defaultSlot) slots.default = defaultSlot;
+    }
+
+    return preview;
+  }
+
+  return null;
+}
+
+function normalizePreviewConfig(preview) {
+  if (!preview || typeof preview !== 'object') return null;
+
+  return {
+    source: preview.source || 'meta',
+    kind: normalizePreviewKind(preview.kind),
+    code: preview.code,
+    props: preview.props && typeof preview.props === 'object' ? preview.props : {},
+    slots: preview.slots && typeof preview.slots === 'object' ? preview.slots : preview.slot ? { default: preview.slot } : {},
+    vModel: preview.vModel,
+  };
+}
+
+function buildPreview(componentName, props, events, slots, examples, jsdoc, metaPreview) {
+  const kind = inferPreviewKind(componentName, props, events, slots, jsdoc, metaPreview);
+  const preview = normalizePreviewConfig(metaPreview) || inferPreviewFromExamples(componentName, props, examples, kind) || {
+    source: 'inferred',
+    props: {},
+    slots: {},
+  };
+
+  return {
+    ...applyPreviewMocks(componentName, props, preview, kind),
+    kind: preview.kind || kind,
+  };
+}
+
 function findAllComponentDirs() {
   if (!fs.existsSync(componentRoot)) return [];
 
@@ -758,69 +1296,10 @@ function buildUsageHints(componentName, title, props, events, slots) {
   return { useWhen, avoidWhen, notes };
 }
 
-function buildSamplePropValue(prop) {
-  if (prop.default !== null && prop.default !== undefined && prop.default !== '') return prop.default;
-  if (prop.values?.length) return prop.values[0];
-
-  const type = prop.type || '';
-  const name = prop.name.toLowerCase();
-
-  if (type.includes('boolean')) return false;
-  if (type.includes('number') || type.includes('Number')) {
-    if (name.includes('percent')) return 60;
-    if (name.includes('max')) return 10;
-    if (name.includes('min')) return 0;
-    if (name.includes('size')) return 32;
-    if (name === 'w' || name.includes('width')) return 240;
-    if (name === 'h' || name.includes('height')) return 80;
-    return 1;
-  }
-  if (type.includes('Array') || type.includes('array') || ['items', 'list', 'range', 'tabs', 'arr'].includes(prop.name)) {
-    return [
-      { label: '选项一', value: 'one' },
-      { label: '选项二', value: 'two' },
-    ];
-  }
-  if (type.includes('Object') || type.includes('object')) return {};
-  if (name.includes('placeholder')) return '请输入';
-  if (name.includes('title')) return '标题';
-  if (name.includes('label')) return '标签';
-  if (name.includes('text') || name.includes('content')) return '示例内容';
-  if (name.includes('phone')) return '13800000000';
-  if (name === 'icon') return '/static/icon/avatar.svg';
-  if (name === 'src' || name.includes('poster')) return '';
-
-  return '';
-}
-
-function renderExampleFromProps(componentName, props) {
-  const importantProps = props
-    .filter((prop) => prop.required || ['modelValue', 'title', 'text', 'label', 'items', 'range', 'tabs', 'src', 'icon', 'type', 'size'].includes(prop.name))
-    .slice(0, 5);
-  const attrs = importantProps
-    .map((prop) => {
-      if (prop.name === 'modelValue') return 'v-model="value"';
-      const value = buildSamplePropValue(prop);
-      if (typeof value === 'boolean') return value ? prop.name : `:${prop.name}="false"`;
-      if (typeof value === 'number') return `:${prop.name}="${value}"`;
-      if (Array.isArray(value) || (value && typeof value === 'object')) return `:${prop.name}="${prop.name}"`;
-      if (!value) return '';
-
-      return `${prop.name}="${value}"`;
-    })
-    .filter(Boolean)
-    .join(' ');
-  const attrText = attrs ? ` ${attrs}` : '';
-
-  return `<${componentName}${attrText}>示例内容</${componentName}>`;
-}
-
 function inferComponentInfo(componentDir) {
   const componentName = path.basename(componentDir);
   const componentFile = findComponentFile(componentDir);
-  const sfcSource = fs.readFileSync(componentFile, 'utf8');
-  const script = extractSfcBlock(sfcSource, 'script', (attrs) => attrs.includes('setup'));
-  const template = extractSfcBlock(sfcSource, 'template');
+  const { script, template } = readSfcBlocks(componentFile);
   const jsdoc = parseJsdoc(script);
   const aliases = collectTypeAliases(componentDir);
   const props = extractProps(script, componentFile, aliases, jsdoc);
@@ -842,7 +1321,6 @@ function inferInitialMeta(componentDir) {
   const examples = normalizeExamples([], jsdoc.examples);
   const title = jsdoc.description?.split('\n')[0]?.trim() || toTitleCase(componentName);
   const usageHints = buildUsageHints(componentName, title, props, events, slots);
-  const exampleCode = renderExampleFromProps(componentName, props);
 
   return {
     title,
@@ -852,15 +1330,7 @@ function inferInitialMeta(componentDir) {
     avoidWhen: usageHints.avoidWhen,
     related: [],
     notes: usageHints.notes,
-    examples: examples.length
-      ? examples
-      : [
-          {
-            title: '基础用法',
-            description: `自动根据 ${componentName} 的 props 生成，可按业务语义继续调整。`,
-            code: exampleCode,
-          },
-        ],
+    examples,
   };
 }
 
@@ -881,6 +1351,10 @@ function mergeMeta(existingMeta, inferredMeta) {
     }
   }
 
+  if (Array.isArray(merged.examples)) {
+    merged.examples = normalizeExamples(merged.examples, inferredMeta.examples || []);
+  }
+
   return merged;
 }
 
@@ -892,7 +1366,30 @@ function isAutoGeneratedDocPage(filePath) {
 }
 
 function renderGeneratedControlStyles() {
-  return `.control-panel,
+  return `.preview-actions {
+  display: flex;
+  flex-direction: row;
+  justify-content: flex-start;
+  width: 100%;
+  margin-bottom: 16rpx;
+}
+
+.preview-open-btn {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 64rpx;
+  padding: 0 24rpx;
+  font-size: 26rpx;
+  font-weight: 600;
+  line-height: 1.35;
+  color: #fff;
+  background: #2563eb;
+  border-radius: 8rpx;
+}
+
+.control-panel,
 .control-list {
   box-sizing: border-box;
   display: flex;
@@ -1052,9 +1549,14 @@ import doc from './data.json';
 
 const {
   propControls,
-  previewProps,
+  renderedPreviewProps,
+  previewKey,
   slotText,
   codeSnippet,
+  isOverlayPreview,
+  overlayTriggerText,
+  openOverlayPreview,
+  handlePreviewModelValueUpdate,
   isBooleanProp,
   isNumberProp,
   isArrayProp,
@@ -1070,7 +1572,11 @@ const {
   <${componentDocPageName} :doc="doc" :show-controls="doc.props.length > 0">
     <template #preview>
       <view class="preview-frame">
-        <${importName} v-bind="previewProps">
+        <view v-if="isOverlayPreview" class="preview-actions">
+          <text class="preview-open-btn" @click="openOverlayPreview">{{ overlayTriggerText }}</text>
+        </view>
+
+        <${importName} :key="previewKey" v-bind="renderedPreviewProps" @update:modelValue="handlePreviewModelValueUpdate('modelValue', $event)">
           {{ slotText }}
         </${importName}>
       </view>
@@ -1271,15 +1777,15 @@ function collectComponentDoc(componentDir) {
   if (!componentFile) return null;
 
   const componentName = path.basename(componentDir);
-  const sfcSource = fs.readFileSync(componentFile, 'utf8');
-  const script = extractSfcBlock(sfcSource, 'script', (attrs) => attrs.includes('setup'));
-  const template = extractSfcBlock(sfcSource, 'template');
+  const { script, template } = readSfcBlocks(componentFile);
   const meta = readJson(getMetaFile(componentDir));
   const jsdoc = parseJsdoc(script);
   const aliases = collectTypeAliases(componentDir);
   const props = extractProps(script, componentFile, aliases, jsdoc);
   const events = extractEvents(script, componentFile, jsdoc);
   const slots = extractSlots(template);
+  const examples = normalizeExamples(meta.examples, jsdoc.examples);
+  const preview = buildPreview(componentName, props, events, slots, examples, jsdoc, meta.preview);
 
   const component = {
     name: componentName,
@@ -1291,7 +1797,8 @@ function collectComponentDoc(componentDir) {
     props,
     events,
     slots,
-    examples: normalizeExamples(meta.examples, jsdoc.examples),
+    preview,
+    examples,
     useWhen: meta.useWhen || [],
     avoidWhen: meta.avoidWhen || [],
     notes: meta.notes || [],