# 演示与文档约定

本站的演示与 API 文档都由源码驱动，新增组件时只需按下面的顺序补齐三处内容。

## 目录结构

```text
docs/
├── .vitepress/
│   ├── components.ts            # 组件元数据清单（唯一数据源）
│   ├── config.ts                # 站点配置、侧边栏、markdown 插件
│   ├── plugins/
│   │   ├── docgen.ts            # vue-docgen-api 解析，产出虚拟模块
│   │   └── ssr-stub.ts          # SSR 阶段替换 timi-web
│   └── theme/
│       ├── index.ts             # 主题入口，注册 TDesign Mobile 与自定义组件
│       ├── containers/          # :::preview 的预览容器
│       └── components/          # api-table 等文档组件
├── demos/                       # 演示组件，按组件名分目录
│   ├── ai/                      # AI 演示共用的假流
│   └── scenarios/               # 跨组件的组合场景演示
├── components/                  # 组件文档页
└── scenarios/                   # 组合场景文档页
```

单组件文档只回答「这个组件怎么用」，跨组件的协作方式放在 `scenarios/` 下。

## 新增一个组件

### 1. 登记元数据

在 `docs/.vitepress/components.ts` 的 `COMPONENT_LIST` 中追加一项。侧边栏导航、API 数据解析都从这里读取：

```ts
{
	name: "CodeEditor",              // 必须与组件 defineOptions 的 name 一致
	title: "CodeEditor 代码编辑器",
	description: "带行号、语法高亮与查找替换的代码输入框。",
	category: "编辑器组件",
	entry: "src/components/code-editor/index.vue"
}
```

### 2. 编写演示

演示组件放在 `docs/demos/<文档路径>/` 下。演示直接引用 `src` 源码，改组件会即时热更新：

```vue
<script lang="ts" setup>
import { ref } from "vue";
import { CodeEditor } from "timi-tdesign-mobile";

const code = ref("");
</script>

<template>
	<code-editor v-model="code" />
</template>
```

### 3. 编写文档页

在 `docs/components/` 下建立同名 markdown，用 `:::preview` 容器引用演示：

````md
# CodeEditor 代码编辑器

带行号、语法高亮与查找替换的代码输入框。

## 基础用法

:::preview 基础用法 || 通过 v-model 双向绑定内容

demo-preview=../demos/code-editor/basic.vue

:::

## API

<api-table name="CodeEditor" />
````

路径以 markdown 文件所在位置为基准，因此 `docs/components/` 下的页面统一使用 `../demos/`。

## 文档路径的来历

`index.vue` 取所在**目录名**，具名文件取**文件名**——`ai` 目录下有多个组件，只靠目录名会全部撞成 `ai`。两者都会再转成短横线形式，`AiChatComposer` 得到 `ai-chat-composer`。需要特殊路径时用元数据里的 `slug` 覆盖。

## API 表从哪来

`<api-table>` 的数据由 `vue-docgen-api` 在构建期解析组件源码得到，通过虚拟模块 `virtual:timi-api` 交给页面渲染。因此不需要手写 props / events / slots 表格，改源码后文档自动更新。

想让说明出现在表里，就在 props 类型上写 JSDoc 注释：

```ts
const props = withDefaults(defineProps<{
	/** 距离底部小于等于该值时触发 */
	distance?: number;
}>(), {
	distance: 120
});
```

某个组件解析失败时只会让该组件的 API 区降级为空，不会影响整站构建；构建日志里会打出对应的组件名。

## 演示统一放在手机视口里

这是移动端组件库，按桌面宽度铺开会失去真实形态。容器把演示收在 `26rem` 宽的视口内，宽度可以通过 CSS 变量调整：

```less
.tui-demo {
	--tui-demo-viewport: 30rem;
}
```

需要全宽的演示（如整页骨架）可以在自己的样式里覆盖这个变量。

## 关于 SSR

`timi-web` 的构建产物在模块顶层访问 `window`，无法在 Node 中加载，而主题必须静态引入它来注册 `v-popup` 指令。因此 SSR 阶段由 `ssr-stub.ts` 提供空实现。

演示组件本身以 `clientOnly` 延迟渲染，不需要额外处理 SSR，但也别把它当作服务端渲染能力的验证。