Component Doc

Component Documentation Workflow

为 @skyroc/web-ui 组件库编写文档的专用工作流。

文件定位规则

给定组件名 $COMPONENT（用户输入，如 Button），将其转为 kebab-case $slug（如 button），然后按以下路径查找：

文档基础设施文件（不需要每次都读，但需要了解）：

执行流程

Phase 1: 源码阅读与行为校验

1. 读取 packages/web/ui/shadcn/src/components/$slug/ 下所有文件
   • 重点关注：index.ts（导出）、types.ts（Props 定义）、*-variants.ts（样式变体）、主组件文件
2. 读取 apps/web-ui-playground/src/app/[locale]/(demo)/$slug/modules/ 下所有 demo
   • 如果目录不存在或 demo 数量不足以覆盖文档需要的功能章节，标记为"需创建 demo"
3. 如果 preset 包装器存在，读取 packages/web/ui/shadcn/src/preset/$slug/ 了解预设封装和 useComponentConfig 集成
4. 如果已有文档 MDX，读取 apps/web-ui-docs/content/docs/components/$slug.mdx
5. 读取一个已完成的文档作为参考模板（优先 alert.mdx，其次 button.mdx）

实现一致性校验（必须执行）

文档不是 API 想象稿，必须从 源码、类型、demo、实际行为 四者交叉验证。

写文档前必须同时检查：

• types.ts 声明了哪些 public props / types
• 主组件实际解构了哪些 props
• props 是否真的传递给对应子组件或底层库
• 默认值实际在哪里设置
• classNames / slot props / size / variant / color 等样式控制是否真的生效
• index.ts 实际导出了哪些组件和类型

如果发现 类型/API 承诺 与 实现行为 不一致：

1. 先明确指出这是实现问题或 API 语义不一致
2. 如果任务允许修改代码，应优先修实现或类型，而不是在文档里规避
3. 如果不能修改实现，必须在最终说明中列为风险/阻塞，并在文档中避免承诺未实现能力
4. 不允许只降低文档表述来掩盖实现 bug

典型例子：

• BottomSheetProps.size 声明为主组件尺寸，但主组件没有传给 BottomSheetContent：这是实现 bug，应提出或修复
• props 被解构但没有使用：不要在文档中承诺该能力已生效
• 类型继承了底层库 props，但封装组件覆盖或丢弃了其中一部分：以实际封装行为为准

Phase 2: 文档编写

MDX 结构（必须遵循）

---
title: $COMPONENT
description: 一句话描述组件用途
---

组件概述段落。

\`\`\`tsx
import { ... } from '@skyroc/web-ui';
\`\`\`

## 何时使用

- 使用场景 1
- 使用场景 2
- 与相似组件的区分

## 功能章节 1（如"颜色"、"变体"、"尺寸"等）

说明文字 + 表格（可选）

<Demo src="@playground/$slug/modules/DemoName" />

\`\`\`tsx
// 内联代码作为 API 快速参考
<Component prop="value" />
\`\`\`

## 功能章节 N

...

## API

### $COMPONENT

通用属性参考说明。

<PropsTable data={[...]} />

### 子组件（如有）

<PropsTable data={[...]} />

## 类型

<TypeTable data={[...]} />
<UnionType name="..." description="..." type="..." />

Demo + 内联代码的组合模式（必须遵循）

每个功能章节的示例由两部分组成，缺一不可：

1. <Demo> 标签（必须）：引用 playground 源码，用户可在文档中看到交互式 live demo 和完整源码。
2. 内联代码块（推荐）：紧跟在 <Demo> 后面，提供简洁的 API 用法速查。

内联代码块的编写原则：

• 不需要完整组件结构，只展示关键 API 用法（最核心的 props 组合）
• Hooks 类的章节用 1-3 行代码展示调用签名即可
• 如果 Demo 本身已经足够简单直观，可以省略内联代码
• 纯展示类章节（如尺寸枚举、变体枚举）可以用表格代替内联代码

示例：

## 受控模式

通过 `page` + `onPageChange` 实现受控分页。

<Demo src="@playground/pagination/modules/Controlled" />

\`\`\`tsx
const [page, setPage] = useState(1);

<Pagination
  total={200}
  itemsPerPage={10}
  page={page}
  onPageChange={setPage}
/>
\`\`\`

PropsTable 书写规则

• type 字段：短字面量联合类型必须直接内联，不要另起 PascalCase 类型名，也不要在 ## 类型 区域写 <UnionType>。
• 典型需要内联的类型：
  • 主题色："'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'carbon' | 'secondary' | 'accent'"
  • 尺寸："'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'"
  • 状态 / 方向 / 位置 / 形状等短联合："boolean | 'indeterminate'"、"'horizontal' | 'vertical'"、"'left' | 'right'"、"'square' | 'rounded'"
• 对象类型、复杂派生类型、外部库大型类型、子组件 Props、classNames/slots 配置，使用 PascalCase 类型名引用。
• PascalCase 类型名由 typeToReactNode 自动渲染为蓝色可点击链接，跳转到当前页类型定义或 type-registry.ts 注册的跨页锚点。
• default 用字符串表示，如 "'md'"、'false'
• required: true 仅在属性必填时添加

类型完整性规则（严格遵循）

核心原则：PropsTable / TypeTable 中出现的每一个非内置 PascalCase 类型名，都必须在当前页 ## 类型 区域有对应定义，或在 type-registry.ts 中注册了跨页面链接。不允许出现"引用了但未定义"的类型。

检查清单（写完文档后逐项核对）：

1. 遍历所有 <PropsTable> 的 type 字段，收集全部 PascalCase 类型名
2. 遍历所有 <TypeTable> 的 fields[].type，收集全部 PascalCase 类型名
3. 排除内置类型（ReactNode、HTMLElement、Record、Partial 等，见 type-anchor.tsx 的 BUILTIN_TYPE_NAMES）
4. 对剩余的每一个类型名，确认以下之一成立：
   • 在当前页的 <TypeTable> 中作为 name 定义
   • 在当前页的 <UnionType> 中作为 name 定义
   • 在 type-registry.ts 中注册了跨页面链接
5. 如有遗漏，补充定义后再输出
6. 如果遗漏类型只是短字面量联合类型（如 ThemeSize、ThemeColor、方向、位置、形状、简单状态），不要补 <UnionType>，应改为在 type 字段直接内联。

特别注意：

• 子组件 Props 类型：如果组件有 titleProps: AlertTitleProps、descriptionProps: AlertDescriptionProps 等 props，这些类型也必须在 TypeTable 中定义，包含各自的字段列表
• 组件本目录导出的 public 类型：index.ts / types.ts 导出的 Props、ClassNames/Ui、Slots、ItemData、Option、Variant 等类型，都必须在当前页类型区定义或跨页注册
• 封装依赖类型：如果组件类型继承 StyledComponentProps<T>、HTMLComponentProps<T>、Radix Props、Vaul Props 等，需要在类型区说明这些包装类型和关键字段
• 不要展开无关大类型：如果引用外部组件的大型 Props（如 ButtonProps、DropdownMenuProps），且该类型不属于当前组件，可以只引用并通过 type-registry.ts 跨页链接；不要在当前页复制展开全部字段
• 共享主题类型：ThemeColor、ThemeSize 这类短联合直接内联；ClassValue 这类复杂类型可以在类型区保留定义。
• BUILTIN_TYPE_NAMES 维护：如果文档中用到了 PascalCase 类型名但它并非当前组件定义的自定义类型（如 DeepPartial、ElementType、StandardSchema、Values 等泛型/外部类型），需要确认它已在 type-anchor.tsx 的 BUILTIN_TYPE_NAMES 中注册。如果没有注册，会生成错误的本地锚点链接。遇到这种情况需要将其添加到 BUILTIN_TYPE_NAMES 中。