# xycomponents

> 一个用于构建自研 `xy-*` 组件的 Vue 3 组件库项目。

`xycomponents` 把组件库打包、文档站点、Markdown Demo 展示能力放在同一个项目里，适合逐步沉淀自研基础组件、业务组件和组件官网。

更适合 GitHub 访客快速了解项目的中文介绍见 [组件库中文介绍](./docs/INTRODUCTION.zh-CN.md)。

## 开始前先做这一步

npm 包名为 `@czxingyu/xycomponents`，组件库品牌名仍为 `xycomponents`。

公共 Vue 组件名使用 `Xy` 前缀，模板标签统一使用 `xy-` 前缀，例如 `<xy-button>` 和 `<xy-input>`。

## 主题定制

这个项目本身是一套无预设主题的基础框架。

它不会强行绑定某套业务视觉风格。你需要根据自己的产品和品牌规范，自定义颜色体系、设计 Token、组件外观以及各种主题效果。

## 这个项目适合做什么

当你希望：

- 构建使用 `xy-` 前缀的自研 Vue 组件库
- 将组件源码、示例和文档统一维护
- 输出带类型声明的 Vue 3 组件包
- 用 Markdown 写文档，同时直接嵌入真实 Vue Demo
- 同时维护中英文文档页面
- 构建自己的主题体系，而不是继承一套固定视觉方案

那么可以直接基于这个仓库继续开发。

## 当前内置能力

- Vue 3 + TypeScript + Vite
- 提供组件官网可直接使用的自研基础组件
- 支持模块化构建、Bundled ESM、UMD 三种产物
- 自动生成组件类型声明
- 自定义 Markdown 转 Vue 文档渲染链路
- Demo 代码展示、源码提取与热更新
- 集成 UnoCSS、Vue Router、Pinia、Vue I18n
- 不内置业务主题，方便按你的品牌体系进行定制
- 已包含可直接扩展的示例组件和文档页面

## 快速开始

### 环境要求

- Node.js `^20.19.0 || >=22.12.0`
- pnpm `10.32.1`

### 在应用中安装

```bash
npm install @czxingyu/xycomponents
pnpm add @czxingyu/xycomponents
yarn add @czxingyu/xycomponents
```

```ts
import XyComponents from "@czxingyu/xycomponents";
import "@czxingyu/xycomponents/style";

app.use(XyComponents);
```

### 安装本仓库依赖

```bash
pnpm install
```

### 启动文档站

```bash
pnpm run docs:dev
```

本地开发地址为 [http://localhost:6878](http://localhost:6878)。

### 构建组件库

```bash
pnpm run build
```

### 其他常用命令

```bash
pnpm run check
pnpm test
pnpm run test:e2e
pnpm run audit:components
pnpm run ci
pnpm run check:esm-import
pnpm run check:packed-consumer
pnpm run docs:build
pnpm run docs:preview
pnpm run type-check
```

## 面向 AI 使用的 CLI 与 Skills

CLI 随 `@czxingyu/xycomponents` 发布，**版本与 npm 包一致**。业务项目在本地安装后通过 `pnpm exec` 调用；升级库时重新 `pnpm add` 即可同步 CLI。

```bash
pnpm add @czxingyu/xycomponents
pnpm exec xycomponents doctor --json
pnpm exec xycomponents components --json
pnpm exec xycomponents component button --json
pnpm exec xycomponents snippet button --example primary
pnpm exec xycomponents migrate link --json
pnpm exec xycomponents package --json
```

**不要**全局安装 CLI，避免 AI 查到与项目 `package.json` 不一致的 API。

### Cursor Skills

[`skills/`](./skills/) 提供 `xycomponents-shared`（安装与接入）和 `xycomponents-cli`（命令与 JSON 工作流）。业务项目复制到 `.cursor/skills/` 或从 `node_modules/@czxingyu/xycomponents/skills/` 复制；详见 [`skills/README.md`](./skills/README.md)。本仓库维护者已在 [`.cursor/skills/`](./.cursor/skills/) 启用同名 Skill。

CLI 以详细级元数据覆盖全部已文档化组件。统一组件清单位于 [`component-groups.ts`](./docs/src/pages/components/component-groups.ts)。组件生成器会原子写入 [`generated-components.ts`](./cli/metadata/generated-components.ts) 的详细元数据基线；成熟后可移入 [`cli/metadata/`](./cli/metadata/)。Schema v3 提供生命周期记录与 retired tombstone；改 deprecated/retired API 前先 `pnpm exec xycomponents migrate <name> --json`。

## 全局组件类型

使用默认插件 `app.use(XyComponents)` 的应用，可在环境声明文件中显式启用全部全局组件的模板类型：

```ts
/// <reference types="@czxingyu/xycomponents/global" />
```

仅按需导入组件的项目无需启用。发布门禁会验证默认插件实际注册的 89 个组件与 `GlobalComponents` 声明完全一致，并用真实 Vue SFC 校验 Props、Events 和 Slots。

## 目录结构

```text
.
├─ cli/                        # 面向 AI 的组件元数据与 CLI 入口
├─ components/                 # 业务组件源码目录
│  ├─ button/
│  └─ form/
├─ docs/                       # 文档站应用
│  ├─ src/pages/               # Markdown 页面与首页
│  ├─ src/components/demo/     # Demo 渲染与源码展示
│  └─ plugins/markdown/        # Markdown / Demo 转换插件
├─ vite.build.config.ts        # 保留模块结构的组件构建
├─ vite.cli.config.ts          # CLI 二进制构建
├─ vite.esm.config.ts          # ESM 打包构建
├─ vite.umd.config.ts          # UMD 打包构建
└─ global.d.ts                 # 全局组件类型声明
```

## 开发方式

### 1. 新增组件

先用生成器同步建立源码、类型、测试、文档、Demo、导出、全局类型和 AI CLI 元数据：

```bash
pnpm generate:component -- UserCard --title 用户卡片 --group data-display --description 展示用户资料。
```

然后把生成的行为、类型、测试、文档、Demo 和 AI 元数据替换为真实契约。未完成的文件会保留 `@xy-component-placeholder`，`pnpm run audit:components` 会按文件列出缺口并阻止合并；只能在对应内容真正实现后逐项移除标记。

### 2. 编写文档页面

在 [`docs/src/pages/`](./docs/src/pages) 下新增 Markdown 文档。当前项目通过 `import.meta.glob` 自动把 `.md` 页面注册成路由。

推荐沿用以下多语言命名方式：

- `*.zh-CN.md`
- `*.en-US.md`

当前路由默认语言是 `zh-CN`，非默认语言会自动附加后缀路由。

### 3. 为文档补充 Demo

在文档页面同级的 `demo/` 目录中放置示例文件，然后在 Markdown 中这样引用：

```md
<demo-group>
  <demo src="./demo/basic.vue">基础示例</demo>
</demo-group>
```

这样文档系统会自动完成：

- 渲染实时 Vue 示例
- 提取源码内容
- 生成高亮代码块
- 开发时热更新 Demo 元数据

## 构建产物说明

执行 `pnpm run build` 后，会输出五类产物：

- `dist/` 下保留模块结构的组件文件
- `dist/index.esm.js` ESM 入口包
- `dist/assets/*` 下供完整 ESM 相对加载的 Empty、Result 图片
- `dist/index.lite.esm.js` 精简 ESM 聚合入口
- `dist/index.umd.js` UMD 入口包

这让它既适合按模块引入，也适合整体打包发布。

可选的 `@czxingyu/xycomponents/lite` 插件会排除包含较大图片资源的 Empty、List、Result、Table 和 Transfer 组件族，并保留组件内部常用图标。业务图标可以在应用挂载前按需注册：

```ts
import XyComponentsLite, { setXyIconLoader } from "@czxingyu/xycomponents/lite";
import "@czxingyu/xycomponents/lite/style";

setXyIconLoader(
  "environment-outlined",
  () => import("@ant-design/icons-vue/EnvironmentOutlined"),
);
app.use(XyComponentsLite);
```

稳定排除清单和维护规则见 [`docs/maintenance/lite-entry.md`](./docs/maintenance/lite-entry.md)。

## 项目实现特点

- 文档站会把 Markdown 页面直接当作 Vue 组件处理。
- Demo SFC 支持通过自定义 `<docs>` 区块声明说明文案。
- 文档站通过本地包入口直接加载当前工作区组件，所以文档展示内容与组件源码始终同步。
- 主题、排版、控件尺寸和组件变量统一维护在 [`components/style/vars.css`](./components/style/vars.css)；需要扩展时新增或复用 token，不在组件中硬编码。

## 运维入口

1. 扩展基础库前先看 [`library-readiness.md`](./docs/maintenance/library-readiness.md) 的完成度与边界。
2. 新增能力遵循 [`component-development.md`](./docs/maintenance/component-development.md)，修 Bug 遵循 [`ai-bugfix.md`](./docs/maintenance/ai-bugfix.md)。
3. 提交前运行 `pnpm run ci`，统一校验运行时导出、全局类型、文档 API、浏览器关键流、全部包格式和真实 tarball 消费者。

## English README

默认英文说明见 [`README.md`](./README.md)。