component-auto-docs 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "component-auto-docs",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Component docs automation CLI for uni-app component libraries.",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "SHARING.md"
   ],
   "peerDependencies": {
+    "@vue/compiler-sfc": ">=3.4.0",
     "typescript": ">=5.0.0"
   },
   "engines": {

package/templates/docs/components/README.md

@@ -69,7 +69,7 @@ pnpm exec component-auto-docs gen
 pnpm exec component-auto-docs check
 ```
 
-`scaffold` 会复制 `docs.config.mjs`、`src/docs/runtime/*`、`src/docs/index.vue` 和本文档规范，并向 `package.json` 写入 `docs:init`、`docs:gen`、`docs:check`、`docs:dev` 脚本。已有文件默认跳过；如需覆盖模板文件和脚本，可使用：
+`scaffold` 会复制 `docs.config.mjs`、`src/docs/runtime/*`、`src/docs/index.vue` 和本文档规范，并向 `package.json` 写入 `docs:scaffold`、`docs:init`、`docs:gen`、`docs:check`、`docs:dev` 脚本。已有文件默认跳过；如需覆盖模板文件和脚本，可使用：
 
 ```bash
 pnpm exec component-auto-docs scaffold --force

package/templates/src/docs/runtime/component-doc-page.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { computed, ref } from 'vue';
+
 type DocItem = {
   name: string;
   title?: string;
@@ -26,13 +28,49 @@ type ComponentDoc = {
   related: string[];
 };
 
-withDefaults(defineProps<{
-  doc: ComponentDoc;
-  showControls?: boolean;
-}>(), {
-  showControls: true,
+const props = withDefaults(
+  defineProps<{
+    doc: ComponentDoc;
+    showControls?: boolean;
+  }>(),
+  {
+    showControls: true,
+  },
+);
+
+const activeTab = ref('preview');
+
+const docTabs = computed(() => {
+  const tabs = [{ key: 'preview', label: '预览' }];
+
+  if (props.doc.props.length || props.doc.events.length || props.doc.slots.length) {
+    tabs.push({ key: 'api', label: 'API' });
+  }
+
+  if (props.doc.examples.length) {
+    tabs.push({ key: 'examples', label: '示例' });
+  }
+
+  if (
+    props.doc.useWhen.length ||
+    props.doc.avoidWhen.length ||
+    props.doc.notes.length ||
+    props.doc.related.length
+  ) {
+    tabs.push({ key: 'guide', label: '说明' });
+  }
+
+  return tabs;
+});
+
+const currentTab = computed(() => {
+  return docTabs.value.some((tab) => tab.key === activeTab.value) ? activeTab.value : 'preview';
 });
 
+function chooseTab(tabKey: string) {
+  activeTab.value = tabKey;
+}
+
 function formatDefault(value: unknown) {
   if (value === null || value === undefined || value === '') return '-';
 
@@ -49,96 +87,116 @@ function formatDefault(value: unknown) {
         <text class="doc-description">{{ doc.description }}</text>
       </view>
 
-      <view class="doc-section">
-        <text class="section-title">真实组件预览</text>
-        <view class="preview-panel">
-          <slot name="preview">
-            <text class="empty-text">暂无可交互预览</text>
-          </slot>
-        </view>
-      </view>
-
-      <view v-if="showControls && $slots.controls" class="doc-section">
-        <text class="section-title">Props 控制面板</text>
-        <slot name="controls"></slot>
+      <view class="doc-tabs">
+        <text
+          v-for="tab in docTabs"
+          :key="tab.key"
+          class="doc-tab"
+          :class="{ active: currentTab === tab.key }"
+          @click="chooseTab(tab.key)"
+        >
+          {{ tab.label }}
+        </text>
       </view>
 
-      <view v-if="$slots.code" class="doc-section">
-        <text class="section-title">当前代码片段预览</text>
-        <slot name="code"></slot>
-      </view>
+      <view v-if="currentTab === 'preview'" class="doc-tab-panel">
+        <view class="doc-section">
+          <text class="section-title">真实组件预览</text>
+          <view class="preview-panel">
+            <slot name="preview">
+              <text class="empty-text">暂无可交互预览</text>
+            </slot>
+          </view>
+        </view>
 
-      <view class="doc-section">
-        <text class="section-title">何时使用</text>
-        <view v-for="item in doc.useWhen" :key="item" class="text-card">{{ item }}</view>
-      </view>
+        <view v-if="showControls && $slots.controls" class="doc-section">
+          <text class="section-title">Props 控制面板</text>
+          <slot name="controls"></slot>
+        </view>
 
-      <view class="doc-section">
-        <text class="section-title">不建议使用</text>
-        <view v-for="item in doc.avoidWhen" :key="item" class="text-card is-warning">
-          {{ item }}
+        <view v-if="$slots.code" class="doc-section">
+          <text class="section-title">当前代码片段预览</text>
+          <slot name="code"></slot>
         </view>
       </view>
 
-      <view class="doc-section">
-        <text class="section-title">Props</text>
-        <view v-for="prop in doc.props" :key="prop.name" class="api-card">
-          <view class="api-card-head">
-            <text class="api-name">{{ prop.name }}</text>
-            <view class="api-head-meta">
-              <text class="api-pill">{{ prop.type }}</text>
-              <text class="api-pill">default: {{ formatDefault(prop.default) }}</text>
-              <text v-if="prop.required" class="api-pill is-required">必填</text>
+      <view v-else-if="currentTab === 'api'" class="doc-tab-panel">
+        <view v-if="doc.props.length" class="doc-section">
+          <text class="section-title">Props</text>
+          <view v-for="prop in doc.props" :key="prop.name" class="api-card">
+            <view class="api-card-head">
+              <text class="api-name">{{ prop.name }}</text>
+              <view class="api-head-meta">
+                <text class="api-pill">{{ prop.type }}</text>
+                <text class="api-pill">default: {{ formatDefault(prop.default) }}</text>
+                <text v-if="prop.required" class="api-pill is-required">必填</text>
+              </view>
+            </view>
+            <text class="api-desc">{{ prop.description || '暂无说明' }}</text>
+            <view v-if="prop.values?.length" class="chip-list">
+              <text v-for="value in prop.values" :key="value" class="chip">{{ value }}</text>
             </view>
           </view>
-          <text class="api-desc">{{ prop.description || '暂无说明' }}</text>
-          <view v-if="prop.values?.length" class="chip-list">
-            <text v-for="value in prop.values" :key="value" class="chip">{{ value }}</text>
+        </view>
+
+        <view v-if="doc.events.length" class="doc-section">
+          <text class="section-title">Events</text>
+          <view v-for="event in doc.events" :key="event.name" class="api-card">
+            <view class="api-card-head">
+              <text class="api-name">{{ event.name }}</text>
+              <text class="api-pill">{{ event.type }}</text>
+            </view>
+            <text class="api-desc">{{ event.description || '暂无说明' }}</text>
           </view>
         </view>
-      </view>
 
-      <view class="doc-section">
-        <text class="section-title">Events</text>
-        <view v-for="event in doc.events" :key="event.name" class="api-card">
-          <view class="api-card-head">
-            <text class="api-name">{{ event.name }}</text>
-            <text class="api-pill">{{ event.type }}</text>
+        <view v-if="doc.slots.length" class="doc-section">
+          <text class="section-title">Slots</text>
+          <view v-for="slot in doc.slots" :key="slot.name" class="api-card">
+            <view class="api-card-head">
+              <text class="api-name">{{ slot.name }}</text>
+            </view>
+            <text class="api-desc">{{ slot.description || '暂无说明' }}</text>
           </view>
-          <text class="api-desc">{{ event.description || '暂无说明' }}</text>
         </view>
       </view>
 
-      <view class="doc-section">
-        <text class="section-title">Slots</text>
-        <view v-for="slot in doc.slots" :key="slot.name" class="api-card">
-          <view class="api-card-head">
-            <text class="api-name">{{ slot.name }}</text>
+      <view v-else-if="currentTab === 'examples'" class="doc-tab-panel">
+        <view class="doc-section">
+          <text class="section-title">示例代码</text>
+          <view v-for="example in doc.examples" :key="example.code" class="example-card">
+            <text class="example-title">{{ example.title }}</text>
+            <text v-if="example.description" class="example-desc">{{ example.description }}</text>
+            <view class="code-card">
+              <text class="code-text">{{ example.code }}</text>
+            </view>
           </view>
-          <text class="api-desc">{{ slot.description || '暂无说明' }}</text>
         </view>
       </view>
 
-      <view class="doc-section">
-        <text class="section-title">注意事项</text>
-        <view v-for="item in doc.notes" :key="item" class="text-card">{{ item }}</view>
-      </view>
+      <view v-else-if="currentTab === 'guide'" class="doc-tab-panel">
+        <view v-if="doc.useWhen.length" class="doc-section">
+          <text class="section-title">何时使用</text>
+          <view v-for="item in doc.useWhen" :key="item" class="text-card">{{ item }}</view>
+        </view>
 
-      <view class="doc-section">
-        <text class="section-title">示例代码</text>
-        <view v-for="example in doc.examples" :key="example.code" class="example-card">
-          <text class="example-title">{{ example.title }}</text>
-          <text v-if="example.description" class="example-desc">{{ example.description }}</text>
-          <view class="code-card">
-            <text class="code-text">{{ example.code }}</text>
+        <view v-if="doc.avoidWhen.length" class="doc-section">
+          <text class="section-title">不建议使用</text>
+          <view v-for="item in doc.avoidWhen" :key="item" class="text-card is-warning">
+            {{ item }}
           </view>
         </view>
-      </view>
 
-      <view v-if="doc.related.length" class="doc-section">
-        <text class="section-title">相关组件</text>
-        <view class="chip-list">
-          <text v-for="item in doc.related" :key="item" class="chip">{{ item }}</text>
+        <view v-if="doc.notes.length" class="doc-section">
+          <text class="section-title">注意事项</text>
+          <view v-for="item in doc.notes" :key="item" class="text-card">{{ item }}</view>
+        </view>
+
+        <view v-if="doc.related.length" class="doc-section">
+          <text class="section-title">相关组件</text>
+          <view class="chip-list">
+            <text v-for="item in doc.related" :key="item" class="chip">{{ item }}</text>
+          </view>
         </view>
       </view>
     </view>
@@ -211,6 +269,43 @@ page {
   font-size: 26rpx;
 }
 
+.doc-tabs {
+  position: sticky;
+  top: 0;
+  z-index: 5;
+  display: flex;
+  flex-direction: row;
+  gap: 10rpx;
+  padding: 18rpx 0 8rpx;
+  overflow-x: auto;
+  background: #f4f7fb;
+}
+
+.doc-tab {
+  box-sizing: border-box;
+  flex: 0 0 auto;
+  min-width: 124rpx;
+  padding: 13rpx 20rpx;
+  font-size: 25rpx;
+  font-weight: 600;
+  line-height: 1.35;
+  color: #475569;
+  text-align: center;
+  background: #fff;
+  border: 1rpx solid #d9e2ef;
+  border-radius: 8rpx;
+}
+
+.doc-tab.active {
+  color: #fff;
+  background: #2563eb;
+  border-color: #2563eb;
+}
+
+.doc-tab-panel {
+  width: 100%;
+}
+
 .doc-section {
   display: flex;
   flex-direction: column;

package/templates/src/docs/runtime/use-auto-component-doc.ts

@@ -1,4 +1,4 @@
-import { computed, reactive, watch } from 'vue';
+import { computed, reactive, ref, watch } from 'vue';
 
 export type DocItem = {
   name: string;
@@ -11,6 +11,18 @@ export type DocItem = {
   code?: string;
 };
 
+export type ComponentPreview = {
+  source?: string;
+  kind?: 'inline' | 'form' | 'data-list' | 'measure' | 'overlay' | 'page-shell' | 'native' | 'composite';
+  code?: string;
+  props?: Record<string, unknown>;
+  slots?: Record<string, string>;
+  vModel?: {
+    prop?: string;
+    variable?: string;
+  };
+};
+
 export type ComponentDoc = {
   name: string;
   title: string;
@@ -19,6 +31,7 @@ export type ComponentDoc = {
   props: DocItem[];
   events: DocItem[];
   slots: DocItem[];
+  preview?: ComponentPreview | null;
   examples: DocItem[];
   useWhen: string[];
   avoidWhen: string[];
@@ -28,6 +41,7 @@ export type ComponentDoc = {
 
 export function useAutoComponentDoc(doc: ComponentDoc) {
   const propControls = reactive<Record<string, unknown>>({});
+  const overlayPreviewVisible = ref(false);
 
   function isBooleanProp(prop: DocItem) {
     return (prop.type || '').toLowerCase().includes('boolean');
@@ -51,20 +65,6 @@ export function useAutoComponentDoc(doc: ComponentDoc) {
     return type.includes('object') || type.includes('Object');
   }
 
-  function getFallbackNumber(prop: DocItem) {
-    const name = prop.name.toLowerCase();
-
-    if (name === 'modelvalue') return 1;
-    if (name.includes('percent')) return 60;
-    if (name.includes('size') || name.includes('font')) return 32;
-    if (name === 'w' || name.includes('width')) return 240;
-    if (name === 'h' || name.includes('height')) return 80;
-    if (name.includes('max')) return 10;
-    if (name.includes('min')) return 0;
-
-    return 1;
-  }
-
   function parseNumberValue(value: unknown) {
     if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
     if (typeof value !== 'string') return undefined;
@@ -78,36 +78,28 @@ export function useAutoComponentDoc(doc: ComponentDoc) {
     return Number.isFinite(numberValue) ? numberValue : undefined;
   }
 
-  function getSampleValue(prop: DocItem) {
-    if (prop.default !== null && prop.default !== undefined && prop.default !== '') {
-      if (isNumberProp(prop)) return parseNumberValue(prop.default) ?? getFallbackNumber(prop);
+  function hasPreviewProp(propName: string) {
+    return Boolean(doc.preview?.props && Object.prototype.hasOwnProperty.call(doc.preview.props, propName));
+  }
+
+  function formatInitialControlValue(prop: DocItem, value: unknown) {
+    if ((isArrayProp(prop) || isObjectProp(prop)) && typeof value !== 'string') {
+      return JSON.stringify(value ?? (isArrayProp(prop) ? [] : {}), null, 2);
+    }
+
+    return value;
+  }
 
-      return prop.default;
+  function getSampleValue(prop: DocItem) {
+    if (hasPreviewProp(prop.name)) {
+      return formatInitialControlValue(prop, doc.preview?.props?.[prop.name]);
     }
 
-    if (prop.values?.length) return prop.values[0];
-
-    const name = prop.name.toLowerCase();
-
-    if (isBooleanProp(prop)) return false;
-    if (isNumberProp(prop)) return getFallbackNumber(prop);
-    if (isArrayProp(prop)) {
-      return JSON.stringify(
-        [
-          { label: '选项一', value: 'one' },
-          { label: '选项二', value: 'two' },
-        ],
-        null,
-        2,
-      );
+    if (prop.default !== null && prop.default !== undefined && prop.default !== '') {
+      if (isNumberProp(prop)) return parseNumberValue(prop.default) ?? '';
+
+      return formatInitialControlValue(prop, prop.default);
     }
-    if (isObjectProp(prop)) 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';
 
     return '';
   }
@@ -147,6 +139,8 @@ export function useAutoComponentDoc(doc: ComponentDoc) {
   }
 
   function resetControls() {
+    overlayPreviewVisible.value = false;
+
     for (const prop of doc.props) {
       propControls[prop.name] = getSampleValue(prop);
     }
@@ -166,18 +160,61 @@ export function useAutoComponentDoc(doc: ComponentDoc) {
     return result;
   });
 
+  const isOverlayPreview = computed(() => doc.preview?.kind === 'overlay');
+
+  const overlayModelProp = computed(() => {
+    if (!isOverlayPreview.value) return '';
+
+    const configuredProp = doc.preview?.vModel?.prop;
+    if (configuredProp && doc.props.some((prop) => prop.name === configuredProp)) return configuredProp;
+
+    const modelProp = doc.props.find((prop) => prop.name === 'modelValue' && isBooleanProp(prop));
+    return modelProp?.name || '';
+  });
+
+  const renderedPreviewProps = computed(() => {
+    const result = { ...previewProps.value };
+
+    if (isOverlayPreview.value && overlayModelProp.value) {
+      result[overlayModelProp.value] = overlayPreviewVisible.value;
+    }
+
+    return result;
+  });
+
   const slotText = computed(() => {
-    if (!doc.slots.length) return '示例内容';
+    return doc.preview?.slots?.default || '';
+  });
 
-    return doc.slots.some((slot) => slot.name === 'default') ? '示例内容' : '';
+  const previewKey = computed(() => {
+    return JSON.stringify({
+      props: renderedPreviewProps.value,
+      slot: slotText.value,
+    });
   });
 
+  const overlayTriggerText = computed(() => {
+    return overlayPreviewVisible.value ? '重新打开预览' : '打开预览';
+  });
+
+  function openOverlayPreview() {
+    overlayPreviewVisible.value = true;
+  }
+
+  function handlePreviewModelValueUpdate(propName: string, value: unknown) {
+    setControlValue(propName, value);
+
+    if (isOverlayPreview.value && propName === overlayModelProp.value) {
+      overlayPreviewVisible.value = Boolean(value);
+    }
+  }
+
   const codeSnippet = computed(() => {
     const attrs = doc.props
       .map((prop) => {
         const value = parseControlValue(prop, propControls[prop.name]);
         if (value === '' || value === null || value === undefined) return '';
-        if (prop.name === 'modelValue') return 'v-model="value"';
+        if (prop.name === 'modelValue') return `v-model="${doc.preview?.vModel?.variable || 'value'}"`;
         if (typeof value === 'boolean') return value ? prop.name : `:${prop.name}="false"`;
         if (typeof value === 'number') return `:${prop.name}="${value}"`;
         if (Array.isArray(value) || typeof value === 'object') return `:${prop.name}="${prop.name}"`;
@@ -194,8 +231,14 @@ export function useAutoComponentDoc(doc: ComponentDoc) {
   return {
     propControls,
     previewProps,
+    renderedPreviewProps,
+    previewKey,
     slotText,
     codeSnippet,
+    isOverlayPreview,
+    overlayTriggerText,
+    openOverlayPreview,
+    handlePreviewModelValueUpdate,
     isBooleanProp,
     isNumberProp,
     isArrayProp,