cdp-material-sdk 0.0.5

package/docs/component-development/README.md

@@ -0,0 +1,176 @@
+# CDP 组件开发入口
+
+本文档面向 **CDP 组件作者**，包括内部组件开发者、第三方组件包作者，以及基于已有 UI 组件库做二次封装的团队。
+
+如果你要开发、接入、扩展或排查一个组件包，请从这里开始。
+
+---
+
+## 1. 先确认你的场景
+
+### 我是第一次接入 CDP，要从零创建组件库工程
+
+按顺序阅读：
+
+1. [创建或接入组件库工程](./getting-started/01-创建或接入组件库工程.md)
+2. [创建组件包并注册](./getting-started/02-创建组件包并注册.md)
+3. [开发最小可运行组件](./getting-started/03-开发最小可运行组件.md)
+4. [构建发布与宿主接入](./getting-started/04-构建发布与宿主接入.md)
+5. [自检与排错](./getting-started/05-自检与排错.md)
+
+### 我已经有一个组件包，要往里面加新组件
+
+适合团队协作场景：组件包工程已经存在，当前任务只是新增一个组件。
+
+建议阅读：
+
+1. [开发最小可运行组件](./getting-started/03-开发最小可运行组件.md)
+2. [创建组件包并注册](./getting-started/02-创建组件包并注册.md) 的「往已有组件包新增组件」小节
+3. 按需选择 `recipes/` 下的能力文档
+4. [自检与排错](./getting-started/05-自检与排错.md)
+
+### 我要把第三方 React 组件库接入 CDP
+
+适合包装 Ant Design、Arco、Material UI、ECharts、自研 UI Kit 等场景。
+
+建议阅读：
+
+1. [接入第三方 React 组件库](./recipes/接入第三方React组件库.md)
+2. [使用 Adapter 适配组件 API](./recipes/使用Adapter适配组件API.md)
+3. [配置 DOM 根节点注入](./recipes/配置DOM根节点注入.md)
+4. [配置 Loading 策略](./recipes/配置Loading策略.md)
+5. [自检与排错](./getting-started/05-自检与排错.md)
+
+### 我要让组件参与表单或数据流
+
+阅读：
+
+- [声明数据字段组件](./recipes/声明数据字段组件.md)
+- [声明数据容器组件](./recipes/声明数据容器组件.md)
+- [Traits 能力模型](./reference/Traits能力模型.md)
+
+### 我要让组件承载子组件（布局容器）
+
+阅读：
+
+- [声明布局容器组件](./recipes/声明布局容器组件.md)
+- [声明插槽](./recipes/声明插槽.md)
+- [Traits 能力模型](./reference/Traits能力模型.md)
+
+### 我要调整组件在设计器中的展示
+
+阅读：
+
+- [配置设计器元信息](./recipes/配置设计器元信息.md)
+- [Manifest 字段参考](./reference/Manifest字段参考.md)
+
+### 我要让组件对外触发事件
+
+事件是可选能力。只有组件需要通知宿主或编排系统时才需要声明。
+
+阅读：
+
+- [声明事件](./recipes/声明事件.md)
+- [Events 模型](./reference/Events模型.md)
+
+### 我要让流程或 AI 调用组件方法
+
+阅读：
+
+- [声明动作与状态](./recipes/声明动作与状态.md)
+- [Actions / State 模型](./reference/ActionsState模型.md)
+
+### 我要给组件提供可拖入区域或模板区域
+
+阅读：
+
+- [声明插槽](./recipes/声明插槽.md)
+- [Slots 模型](./reference/Slots模型.md)
+
+### 我要处理根节点注入、Loading 或渲染策略
+
+阅读：
+
+- [配置 DOM 根节点注入](./recipes/配置DOM根节点注入.md)
+- [配置 Loading 策略](./recipes/配置Loading策略.md)
+- [DOM 根节点注入模型](./reference/DOM根节点注入模型.md)
+- [Loading 策略模型](./reference/Loading策略模型.md)
+
+### 我遇到了 warning、error 或接入后不生效
+
+阅读：
+
+- [自检与排错](./getting-started/05-自检与排错.md)
+- [validateManifest 校验规则](./reference/validateManifest校验规则.md)
+- [FAQ](./FAQ.md)
+
+### 我要找可复制的模板或示例代码
+
+阅读：
+
+- [示例代码索引](./reference/示例代码索引.md)
+
+---
+
+## 2. 文档分层
+
+| 层级 | 作用 | 读者 |
+|------|------|------|
+| `getting-started/` | 完成一个可交付组件包的最小闭环 | 新接入作者、团队负责人 |
+| `recipes/` | 按需启用某项组件能力 | 正在实现具体组件能力的作者 |
+| `reference/` | 查字段、查模型、查校验规则 | 所有作者、AI Skill |
+| `FAQ.md` | 高频问题与排错入口 | 所有作者 |
+
+---
+
+## 3. 最小必需路径和可选能力
+
+组件接入 CDP 的最小必需路径只有 5 件事：
+
+1. 使用 React 或 React wrapper 暴露组件。
+2. 为组件编写 `ComponentManifest`。
+3. 将组件和 manifest 放入 `EngineComponentPackage.components`。
+4. 在 `EngineComponentPlugin.install()` 中调用 `api.registerPackage(pkg)`。
+5. 使用 `validateManifest()` 自检，确保没有 error。
+
+以下能力都不是强制的：
+
+| 能力 | 什么时候需要 | 不需要时 |
+|------|--------------|----------|
+| `events` | 组件需要通知宿主，例如点击、值变化、行选择 | 不声明 |
+| `actions` | 外部流程需要命令式调用组件 | 不声明 |
+| `state` | 外部表达式需要读取组件内部运行时状态 | 不声明 |
+| `DATA_FIELD` | 组件参与数据值管理 | 不声明该 trait |
+| `DATA_CONTAINER` | 组件要管理子字段的数据作用域 | 不声明该 trait |
+| `LAYOUT_CONTAINER` | 组件作为布局容器承载子组件 | 不声明该 trait |
+| `slots` | 组件需要可拖入或模板化区域 | 不声明 |
+| `nesting` | 需要限制子组件类型、最少/最多数量、或者只能作为某些父组件的子节点 | 不声明 |
+| `meta.icon` / `subGroup` / `hiddenInComponentList` | 需要调整设计器中的展示 | 不声明 |
+| `usage` | 给 AI 与设计器提供使用提示 | 不声明 |
+| `adapter` | 组件 API 与 CDP 默认约定不一致 | 不声明 |
+| `engine.render.loading` | 组件需要被流程控制 Loading | 不声明或使用 `none` |
+
+---
+
+## 4. 面向未来 Skill 的约定
+
+本文档按「任务路径 + 可选能力 Recipe + 模型参考 + 自检排错 + FAQ」组织。每个 Recipe 都尽量包含：
+
+- **适用场景：** 什么时候需要。
+- **可以跳过的情况：** 避免把可选能力误认为必做流程。
+- **输入：** 作者已有的组件、manifest 或组件包。
+- **输出：** 完成后应该得到什么。
+- **步骤：** 可人工执行，也可由 AI Skill 执行。
+- **自检：** 使用 `validateManifest()` 或运行时诊断确认结果。
+
+`reference/` 只维护稳定事实源：字段语义、模型边界、约束摘要和校验入口，不维护完整任务流程。
+
+`reference/validateManifest校验规则.md` 是校验级别事实源：哪些规则是 error、哪些规则是 warning，应优先在这里维护。
+
+`recipes/`、`reference/`、`getting-started/` 和 `FAQ.md` 文档顶部使用 frontmatter 声明：
+
+- `type`：文档层级，例如 `recipe`、`reference`、`getting-started` 或 `faq`。
+- `capability`：能力标识，例如 `events`、`actions-state`、`rootpath`。
+- `related`：相关文档路径，供作者和 AI Skill 建立任务、模型和校验之间的导航关系。
+
+每篇能力文档末尾应保留「关联文档」或「任务路径」区块。AI Skill 应先读取目标任务的 Recipe，再读取对应 Reference 和 validateManifest 校验规则。

package/docs/component-development/getting-started/01-/345/210/233/345/273/272/346/210/226/346/216/245/345/205/245/347/273/204/344/273/266/345/272/223/345/267/245/347/250/213.md

@@ -0,0 +1,172 @@
+---
+type: getting-started
+capability: project-setup
+related:
+  - getting-started/02-创建组件包并注册.md
+  - getting-started/03-开发最小可运行组件.md
+  - reference/SDK导入边界.md
+---
+# 01 - 创建或接入组件库工程
+
+本文说明如何准备一个可交付给 CDP 宿主加载的组件库工程。
+
+这一步是**建议流程**，不是强制流程。CDP 真正关心的是最终产物：一个可被动态导入的 ESM 插件，以及其中注册的 `EngineComponentPackage`。
+
+---
+
+## 适用场景
+
+- 你要从零创建一个第三方组件包工程。
+- 你已有 UI 组件库，希望新增一个 CDP 适配层。
+- 你在团队内维护一个长期演进的组件包。
+
+如果你已经有组件包工程，并且只是新增组件，可以直接阅读 [开发最小可运行组件](./03-开发最小可运行组件.md)。
+
+---
+
+## 推荐目录结构
+
+```text
+my-cdp-components/
+├── src/
+│   ├── components/
+│   │   └── MyButton/
+│   │       ├── index.tsx
+│   │       └── manifest.ts
+│   ├── manifests.ts
+│   └── plugin.ts
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── README.md
+```
+
+目录说明：
+
+| 路径 | 职责 |
+|------|------|
+| `src/components/*/index.tsx` | React 组件或第三方组件 wrapper |
+| `src/components/*/manifest.ts` | 单组件的 `ComponentManifest` |
+| `src/manifests.ts` | 汇总组件注册项，便于团队协作审查 |
+| `src/plugin.ts` | 导出 `EngineComponentPlugin`，宿主加载入口 |
+| `vite.config.ts` | 将插件构建为 ESM library |
+
+---
+
+## 安装 SDK
+
+推荐从 npm 安装最新版：
+
+```bash
+npm install cdp-material-sdk@latest react react-dom
+```
+
+如需锁定到精确版本：
+
+```bash
+npm install cdp-material-sdk@<version> react react-dom
+```
+
+无 npm 访问时，可回退到 GitHub Release `.tgz`：
+
+```bash
+npm install https://github.com/GroovyKetchup/cdp-material-sdk/releases/download/v<version>/cdp-material-sdk-<version>.tgz
+```
+
+`react` 与 `react-dom` 是 peer dependency，需要由组件作者侧显式安装（建议 19.x）。
+
+默认导入入口：
+
+```ts
+import type { ComponentManifest, EngineComponentPlugin } from 'cdp-material-sdk/portable';
+```
+
+导入边界：
+
+| 入口 | 用途 |
+|------|------|
+| `cdp-material-sdk/portable` | 默认入口。用于声明 manifest、组件包、插件、traits、校验工具 |
+| `cdp-material-sdk/host-react` | 仅在确认与宿主共享 React runtime 和 Context 身份时使用 |
+
+---
+
+## package.json 关键约束
+
+```jsonc
+{
+  "name": "@myorg/cdp-components",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "peerDependencies": {
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
+  },
+  "dependencies": {
+    "cdp-material-sdk": "<tgz-url-or-version>"
+  }
+}
+```
+
+关键点：
+
+- **不要把 React 打进 bundle。** `react`、`react-dom`、`react/jsx-runtime` 应由宿主提供。
+- `cdp-material-sdk/portable` 可以作为依赖使用。
+- UI 组件库是否 externalize 需要与宿主协商；默认可以打入 bundle。
+
+---
+
+## Vite library mode 参考
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import dts from 'vite-plugin-dts';
+
+export default defineConfig({
+  plugins: [react(), dts()],
+  build: {
+    lib: {
+      entry: 'src/plugin.ts',
+      formats: ['es'],
+      fileName: 'index',
+    },
+    rollupOptions: {
+      external: ['react', 'react/jsx-runtime', 'react-dom'],
+    },
+  },
+});
+```
+
+---
+
+## 团队协作建议
+
+如果组件包由多人维护，建议约定：
+
+- 每个组件独立目录，组件实现和 manifest 放在一起。
+- 组件 `type` 使用命名空间，例如 `acme.Button`、`acme.UserCard`。
+- 新增组件只修改自己的目录和组件注册清单。
+- 每次新增组件都运行 [自检与排错](./05-自检与排错.md)。
+- 不直接依赖宿主源码路径或未从 `cdp-material-sdk` 公开入口导出的模块。
+
+---
+
+## 完成标准
+
+- [ ] 工程可以执行 `npm run build`。
+- [ ] 构建产物是 ESM。
+- [ ] React 相关依赖没有被打入 bundle。
+- [ ] 工程中只从 `cdp-material-sdk/portable` 或必要的 `host-react` 入口导入 SDK API。
+- [ ] 已准备 `src/plugin.ts` 作为宿主加载入口。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 关联文档：[02-创建组件包并注册](./02-创建组件包并注册.md)
+- 关联文档：[03-开发最小可运行组件](./03-开发最小可运行组件.md)
+- SDK 导入边界：[SDK导入边界](../reference/SDK导入边界.md)

package/docs/component-development/getting-started/02-/345/210/233/345/273/272/347/273/204/344/273/266/345/214/205/345/271/266/346/263/250/345/206/214.md

@@ -0,0 +1,185 @@
+---
+type: getting-started
+capability: package-registration
+related:
+  - getting-started/03-开发最小可运行组件.md
+  - reference/示例代码索引.md
+  - reference/SDK导入边界.md
+---
+# 02 - 创建组件包并注册
+
+组件包是 CDP 识别和加载组件的发布单元。一个组件包可以包含 1 个或多个组件。
+
+---
+
+## 适用场景
+
+- 你要创建新的组件包。
+- 你已经有组件包，要往里面新增组件。
+- 你需要理解 `EngineComponentPackage` 和 `EngineComponentPlugin` 的关系。
+
+---
+
+## 核心模型
+
+```text
+React Component + ComponentManifest
+        ↓
+EngineComponentRegistration
+        ↓
+EngineComponentPackage
+        ↓
+EngineComponentPlugin.install(api)
+        ↓
+api.registerPackage(pkg)
+```
+
+关键类型：
+
+```ts
+import type {
+  EngineComponentPackage,
+  EngineComponentPlugin,
+  EngineComponentRegistration,
+} from 'cdp-material-sdk/portable';
+```
+
+---
+
+## 创建组件包
+
+```ts
+import type { EngineComponentPackage } from 'cdp-material-sdk/portable';
+import { MyButton } from './components/MyButton';
+import { myButtonManifest } from './components/MyButton/manifest';
+
+export const myPackage: EngineComponentPackage = {
+  id: '@acme/cdp-components',
+  version: '1.0.0',
+  components: [
+    {
+      manifest: myButtonManifest,
+      component: MyButton,
+    },
+  ],
+};
+```
+
+字段说明：
+
+| 字段 | 说明 |
+|------|------|
+| `id` | 组件包唯一标识，建议与 npm 包名一致 |
+| `version` | 组件包版本 |
+| `components` | 组件注册列表，每项包含 `manifest` 和 React 组件 |
+| `compatibility` | 可选，用于声明 SDK 或引擎版本兼容范围 |
+
+---
+
+## 创建插件入口
+
+```ts
+import type { EngineComponentPlugin } from 'cdp-material-sdk/portable';
+import { myPackage } from './package';
+
+const plugin: EngineComponentPlugin = {
+  id: myPackage.id,
+  version: myPackage.version,
+  compatibility: myPackage.compatibility,
+  install: (api) => {
+    api.registerPackage(myPackage);
+  },
+};
+
+export default plugin;
+```
+
+建议优先使用 `api.registerPackage(pkg)`，而不是逐个调用 `api.registerComponent()`。这样更利于版本管理和卸载回滚。
+
+---
+
+## 往已有组件包新增组件
+
+这是团队协作中最常见的场景。
+
+### 1. 新建组件目录
+
+```text
+src/components/UserCard/
+├── index.tsx
+└── manifest.ts
+```
+
+### 2. 导出组件注册项
+
+```ts
+import type { EngineComponentRegistration } from 'cdp-material-sdk/portable';
+import { UserCard } from './index';
+import { userCardManifest } from './manifest';
+
+export const userCardRegistration: EngineComponentRegistration = {
+  manifest: userCardManifest,
+  component: UserCard,
+};
+```
+
+### 3. 加入组件包清单
+
+```ts
+import type { EngineComponentPackage } from 'cdp-material-sdk/portable';
+import { myButtonRegistration } from './components/MyButton/registration';
+import { userCardRegistration } from './components/UserCard/registration';
+
+export const myPackage: EngineComponentPackage = {
+  id: '@acme/cdp-components',
+  version: '1.1.0',
+  components: [
+    myButtonRegistration,
+    userCardRegistration,
+  ],
+};
+```
+
+### 4. 更新版本
+
+新增对外组件时，建议更新组件包版本。团队可以按语义化版本约定：
+
+| 变更 | 建议 |
+|------|------|
+| 新增组件 | minor |
+| 修复组件内部 bug | patch |
+| 删除组件或修改已有组件 `type` | major |
+
+---
+
+## 命名建议
+
+| 对象 | 建议 | 示例 |
+|------|------|------|
+| 包 id | 与包名一致 | `@acme/cdp-components` |
+| 组件 type | 带组织前缀 | `acme.UserCard` |
+| 组件目录 | PascalCase | `UserCard` |
+| manifest 变量 | camelCase | `userCardManifest` |
+| registration 变量 | camelCase | `userCardRegistration` |
+
+---
+
+## 自检
+
+每次新增或修改组件包后，至少检查：
+
+- [ ] `components` 中每个组件都有唯一 `manifest.type`。
+- [ ] `plugin.id` 与 `package.id` 一致。
+- [ ] `plugin.version` 与 `package.version` 一致。
+- [ ] 每个 manifest 通过 `validateManifest()`。
+- [ ] 新增组件已加入 `EngineComponentPackage.components`。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 关联文档：[03-开发最小可运行组件](./03-开发最小可运行组件.md)
+- 示例索引：[示例代码索引](../reference/示例代码索引.md)
+- SDK 导入边界：[SDK导入边界](../reference/SDK导入边界.md)