Native Component Doc

Native UI 组件文档工作流

为 @skyroc/native-ui（React Native + Uniwind）编写文档的专用工作流。

这不是 web-ui 那套。native 的 <Demo> 会把 demo 源码整份渲染出来、右栏还有整页手机预览， 因此不写内联代码块、demo 一律具名导出、每个 demo 都要在汇总页里串一遍。 与 component-doc（web-ui 用）的差异见文末「与 web-ui 文档规范的差异」。

文件定位规则

给定组件名 $COMPONENT（如 ActionSheet），转 kebab-case $slug（如 action-sheet）：

文档基础设施（了解即可，不必每次都读）：

侧边栏分组

content/docs/components/ 下按 fumadocs 路由组分组，路由组不进 URL（(general)/button.mdx → /docs/components/button）。 写完文档后必须把 $slug 加进对应分组的 meta.json 的 pages 里（meta.json 已预置全部规划中的 slug，通常只需确认位置正确）。

meta.json 里列了但文件还不存在的 slug 会被 fumadocs 静默跳过（resolveFolderItem 找不到 node 直接 return），所以预置清单不会报错。

meta.json 里不要写 "collapsible": false。fumadocs-ui 16.14.4 的 SidebarFolderTrigger 在 collapsible: false 分支直接渲染成 jsx("div", { ...props })，而上层 （layouts/docs/slots/sidebar.js:220）传下来的 className 是个 (state) => string 函数 —— 函数原样落到 DOM 上，React 报 Invalid value for prop \className` on <div> tag，分组标题也因此丢掉全部样式类。 collapsible走默认的true时，trigger 渲染成 Base UI 的Collapsible.Trigger，函数 className 会被 useRenderElement 正常解析。defaultOpen: true已经能让分组默认展开，不需要collapsible: false`。

执行流程

Phase 1：读源码与 demo，做一致性校验

1. 读 packages/native/ui/src/components/$slug/ 全部文件
   • index.ts：实际导出了哪些组件、哪些类型
   • types.ts：public props 与类型别名
   • *-variants.ts：slots / variants / compoundVariants / defaultVariants —— 表格里的每一行数值都从这里抄，不要凭印象写
   • 主组件 *.tsx：props 实际怎么解构、默认值在哪、有没有 hitSlop / accessibilityState / TextClassContext / Portal 之类的 RN 特有行为
2. 读 apps/native-ui-playground/src/demos/$slug/ 全部 demo + index.tsx 汇总页
   • 汇总页的 <Section title/description> 就是天然的章节大纲，文档章节直接对齐它
3. 已有文档就读一遍，判断是补全还是重写
4. 参考范例：docs/native-ui-docs/content/docs/components/(general)/button.mdx（当前唯一的完整样板）

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

文档不是 API 想象稿，从源码 / 类型 / variants / demo 四者交叉验证：

• types.ts 声明的 props，主组件是否真的解构并使用
• 默认值实际在哪里设置（defaultVariants vs 组件内 = false），两处不一致时以运行时为准
• classNames 的每个 slot 是否真的接到了对应节点上
• index.ts 是否真的导出了你要写进文档的类型
• RN 特有：hitSlop、accessibilityRole / accessibilityState、Pressable 透传、TextClassContext 继承范围、Portal / Modal 挂载点

发现类型/API 承诺与实现不一致时：先明确指出这是实现问题；能改就改实现或类型，不要在文档里绕过去；不能改就在最终说明里列为风险，并且不在文档中承诺未实现的能力。不允许靠降低文档表述来掩盖实现 bug。

Phase 2：写文档

MDX 结构

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

概述段落：组件做什么、基于什么 RN 原语封装、有什么与众不同的行为。

\`\`\`tsx
import { $COMPONENT } from '@skyroc/native-ui';
\`\`\`

## 基础用法

<Demo src="@playground/$slug/$DemoBasic" />

## 何时使用

- 使用场景 / 移动端取舍
- 与相似组件的区分（如 Popup vs Sheet vs ActionSheet）

## 功能章节（variant / color / size / shape / ...）

说明文字 +（枚举类的）表格

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

补充说明：容易踩的坑、和 web 端行为不同的地方

## 无障碍

role / accessibilityState / 热区 等 RN 专属说明（有就写）

## API

### $COMPONENT

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

## 类型

\`\`\`ts
import type { ... } from '@skyroc/native-ui';
\`\`\`

<UnionType ... />
<TypeTable data={[...]} />

Demo 引用规则（native 专属）

• 格式：<Demo src="@playground/$slug/$DemoName" />，没有 modules/ 这一层（那是 web-ui 的）
• 不要在 <Demo> 后面贴内联代码块。<Demo> 已经把整份 demo 源码渲染在预览下方了，内联代码是重复噪音
• 覆盖率要求：src/demos/$slug/index.tsx 里串的每个子 demo，文档必须有且仅有一处 <Demo> 引用。章节顺序也尽量对齐汇总页
• demo 缺失时必须补 demo，不能因为没 demo 就只写文字

写完用这条命令核对覆盖率（无输出即一一对应）：

slug=button; group='(general)'
diff \
  <(ls apps/native-ui-playground/src/demos/$slug | grep -v '^index' | sed 's/\.tsx$//' | sort) \
  <(grep -o "@playground/$slug/[A-Za-z0-9]*" "docs/native-ui-docs/content/docs/components/$group/$slug.mdx" | sed 's|.*/||' | sort -u)

新建 Playground Demo 的规范

1. 路径：apps/native-ui-playground/src/demos/$slug/$DemoName.tsx，$DemoName 以组件名开头（ButtonLoading、CellSize）
2. 必须具名导出，且导出名 === 文件名 —— demo-preview.tsx 是按模块名去取 mod[exportName] 的，写成 export default 或改名都会拿不到组件
3. 模板：

import { Button } from '@skyroc/native-ui';
import { View } from 'react-native';

const ButtonLoading = () => {
  return (
    <View className="gap-3 bg-background p-4">
      {/* ... */}
    </View>
  );
};

export { ButtonLoading };

4. 约束：
   • 不写 'use client'（RN，不是 Next 客户端组件）
   • 从 @skyroc/native-ui 导入组件，不从内部路径导入
   • 容器统一 View + uniwind 类名，带上 bg-background p-4，保证在文档预览的手机框里边距一致
   • 每个 demo 只聚焦一个功能点，自包含，不依赖同目录 shared.tsx
   • 需要文字就用 @skyroc/native-ui 的 Text，才能继承 TextClassContext
5. 同步汇总页：在 src/demos/$slug/index.tsx 里 import 并加一个 <Section title description>。汇总页只负责串场，不要把示例代码写回去
6. 确认整页路由存在：apps/native-ui-playground/app/components/$slug.tsx。它是文档右栏分栏预览的来源（resolvePlaygroundPage 按最后一段 slug 找同名文件），缺了文档就退回单栏