cdp-material-sdk 0.0.5

package/docs/component-development/getting-started/03-/345/274/200/345/217/221/346/234/200/345/260/217/345/217/257/350/277/220/350/241/214/347/273/204/344/273/266.md

@@ -0,0 +1,196 @@
+---
+type: getting-started
+capability: minimum-component
+related:
+  - reference/Manifest字段参考.md
+  - reference/DOM根节点注入模型.md
+  - reference/validateManifest校验规则.md
+  - reference/示例代码索引.md
+---
+# 03 - 开发最小可运行组件
+
+本文说明如何开发一个最小可被 CDP 宿主加载、渲染和识别的组件。
+
+---
+
+## 适用场景
+
+- 你要从零开发一个 CDP 组件。
+- 你要往已有组件包里新增组件。
+- 你要先跑通最小闭环，再按需添加事件、动作、状态、插槽或数据能力。
+
+---
+
+## 最小输出
+
+一个最小组件通常包含：
+
+```text
+MyText/
+├── index.tsx
+└── manifest.ts
+```
+
+---
+
+## 1. 编写 React 组件
+
+```tsx
+import { forwardRef } from 'react';
+import type { BaseUIProps } from 'cdp-material-sdk/portable';
+
+export interface MyTextProps extends BaseUIProps<HTMLDivElement> {
+  text?: string;
+}
+
+export const MyText = forwardRef<HTMLDivElement, MyTextProps>((props, ref) => {
+  const { text = 'Hello CDP', slotProps } = props;
+
+  return (
+    <div {...slotProps?.root} ref={ref}>
+      {text}
+    </div>
+  );
+});
+
+export default MyText;
+```
+
+关键要求：
+
+- 使用 React 组件或 React wrapper。
+- 推荐使用 `forwardRef`，后续可扩展 actions 和 state。
+- 接收 `BaseUIProps`。
+- 将 `slotProps.root` 透传到真实 DOM 根节点。
+
+---
+
+## 2. 编写 ComponentManifest
+
+```ts
+import {
+  COMPONENT_CATEGORY,
+  INJECT_PATH_SLOT_PROPS,
+  type ComponentManifest,
+} from 'cdp-material-sdk/portable';
+
+export const myTextManifest = {
+  type: 'acme.MyText',
+  meta: {
+    title: '文本',
+    category: COMPONENT_CATEGORY.GENERAL,
+    description: '一个最小文本组件',
+  },
+  engine: {
+    render: {
+      injection: {
+        rootPath: INJECT_PATH_SLOT_PROPS,
+      },
+    },
+  },
+  props: {
+    type: 'object',
+    properties: {
+      text: {
+        type: 'string',
+        title: '文本内容',
+        default: 'Hello CDP',
+      },
+    },
+  },
+  usage: {
+    tips: ['适合展示短文本'],
+    warnings: ['不建议用于长篇富文本'],
+  },
+} satisfies ComponentManifest;
+```
+
+最小必填项：
+
+| 字段 | 说明 |
+|------|------|
+| `type` | 组件唯一标识 |
+| `meta.title` | 组件显示名 |
+| `meta.category` | 组件分类 |
+
+推荐声明：
+
+| 字段 | 说明 |
+|------|------|
+| `props` | 可配置属性的 JSON Schema |
+| `engine.render.injection.rootPath` | 宿主根节点属性注入位置 |
+| `usage.tips` / `usage.warnings` | 面向 AI 与设计器的使用提示，让组件从一开始就具备可读语义 |
+| `meta.description` | 面向使用者的一句话说明 |
+
+---
+
+## 3. 加入组件包
+
+```ts
+import type { EngineComponentPackage } from 'cdp-material-sdk/portable';
+import { MyText } from './components/MyText';
+import { myTextManifest } from './components/MyText/manifest';
+
+export const myPackage: EngineComponentPackage = {
+  id: '@acme/cdp-components',
+  version: '1.0.0',
+  components: [
+    {
+      manifest: myTextManifest,
+      component: MyText,
+    },
+  ],
+};
+```
+
+---
+
+## 4. 按需添加能力
+
+最小组件不需要声明所有能力。按需求选择：
+
+| 需求 | 下一步 |
+|------|--------|
+| 参与表单值管理 | [声明数据字段组件](../recipes/声明数据字段组件.md) |
+| 作为数据容器 | [声明数据容器组件](../recipes/声明数据容器组件.md) |
+| 作为布局容器承载子组件 | [声明布局容器组件](../recipes/声明布局容器组件.md) |
+| 触发事件 | [声明事件](../recipes/声明事件.md) |
+| 暴露方法或状态 | [声明动作与状态](../recipes/声明动作与状态.md) |
+| 提供可拖入区域 | [声明插槽](../recipes/声明插槽.md) |
+| 调整设计器中的展示（图标、分组、隐藏） | [配置设计器元信息](../recipes/配置设计器元信息.md) |
+| 接入第三方组件库 | [接入第三方 React 组件库](../recipes/接入第三方React组件库.md) |
+| 配置 Loading | [配置 Loading 策略](../recipes/配置Loading策略.md) |
+
+---
+
+## 自检
+
+```ts
+import { validateManifest, printValidationResult } from 'cdp-material-sdk/portable';
+import { myTextManifest } from './components/MyText/manifest';
+
+const result = validateManifest(myTextManifest);
+printValidationResult(result);
+
+if (!result.valid) {
+  process.exitCode = 1;
+}
+```
+
+完成标准：
+
+- [ ] `validateManifest()` 没有 error。
+- [ ] 组件能被加入 `EngineComponentPackage.components`。
+- [ ] 组件根 DOM 能收到 `slotProps.root`。
+- [ ] 没有直接依赖宿主内部模块。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 字段参考：[Manifest字段参考](../reference/Manifest字段参考.md)
+- 模型参考：[DOM根节点注入模型](../reference/DOM根节点注入模型.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 示例索引：[示例代码索引](../reference/示例代码索引.md)

package/docs/component-development/getting-started/04-/346/236/204/345/273/272/345/217/221/345/270/203/344/270/216/345/256/277/344/270/273/346/216/245/345/205/245.md

@@ -0,0 +1,147 @@
+---
+type: getting-started
+capability: build-and-release
+related:
+  - reference/SDK导入边界.md
+  - reference/validateManifest校验规则.md
+---
+# 04 - 构建发布与宿主接入
+
+本文说明组件包如何构建成宿主可加载的 ESM 插件，以及交付时需要提供哪些信息。
+
+---
+
+## 适用场景
+
+- 你已经完成组件和 `EngineComponentPlugin`。
+- 你要将组件包交付给 CDP 宿主加载。
+- 你要确认 bundle 依赖处理是否正确。
+
+---
+
+## 构建目标
+
+宿主期望加载一个 ESM 模块。该模块应导出 `EngineComponentPlugin`，通常使用 default export：
+
+```ts
+import type { EngineComponentPlugin } from 'cdp-material-sdk/portable';
+import { myPackage } from './package';
+
+const plugin: EngineComponentPlugin = {
+  id: myPackage.id,
+  version: myPackage.version,
+  install: (api) => {
+    api.registerPackage(myPackage);
+  },
+};
+
+export default plugin;
+```
+
+---
+
+## Vite 构建配置
+
+```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'],
+    },
+  },
+});
+```
+
+---
+
+## 依赖处理
+
+| 依赖 | 推荐处理 |
+|------|----------|
+| `react` | `peerDependencies` + externalize，由宿主提供 |
+| `react-dom` | `peerDependencies` + externalize，由宿主提供 |
+| `react/jsx-runtime` | externalize |
+| `cdp-material-sdk/portable` | 可作为普通依赖使用 |
+| `cdp-material-sdk/host-react` | 仅当确认共享宿主 React Context 时使用 |
+| UI 组件库 | 默认打入 bundle；如需共享，需与宿主协商 externalize |
+
+---
+
+## 交付给宿主的信息
+
+正式交付时，至少提供：
+
+| 信息 | 示例 |
+|------|------|
+| 组件包 id | `@acme/cdp-components` |
+| 版本 | `1.0.0` |
+| ESM URL | `/packages/acme-cdp-components/index.js` |
+| integrity | `sha384-...` |
+| 组件清单 | `acme.MyText`、`acme.UserCard` |
+| SDK 版本 | `cdp-material-sdk@0.0.4` |
+
+后端下发字段由宿主侧契约决定，通常包含 `id`、`version`、`url`、`integrity`。
+
+---
+
+## Build Checklist
+
+- [ ] `npm run build` 能成功输出 ESM。
+- [ ] 入口文件默认导出 `EngineComponentPlugin`。
+- [ ] `react`、`react-dom`、`react/jsx-runtime` 没有打进 bundle。
+- [ ] `EngineComponentPlugin.id` 与 `EngineComponentPackage.id` 一致。
+- [ ] `EngineComponentPlugin.version` 与 `EngineComponentPackage.version` 一致。
+- [ ] 每个组件的 `manifest.type` 唯一且稳定。
+- [ ] 每个 manifest 通过 `validateManifest()`。
+- [ ] 如果使用 `host-react`，已确认外部 bundle 与宿主共享同一份 React runtime 和 Context 身份。
+
+---
+
+## 交付模式对比
+
+| 模式 | 适用阶段 | 说明 |
+|------|----------|------|
+| 同源 URL 直载 | 联调、灰度、内部验证 | 宿主通过 URL 动态导入 ESM |
+| 独立 npm / tgz 包 | 正式交付、版本管理 | 独立仓库构建后发布产物 |
+| 文档内模板 | 快速复制、理解 authoring 方式 | 以本文和 [示例代码索引](../reference/示例代码索引.md) 为准 |
+
+---
+
+## 常见错误
+
+### 把 React 打进 bundle
+
+现象：组件渲染、Context 或 ref 行为异常。
+
+处理：检查构建产物和 `rollupOptions.external`，确保 `react`、`react-dom`、`react/jsx-runtime` 被 externalize。
+
+### 插件没有 default export
+
+现象：宿主动态导入模块后无法解析插件。
+
+处理：确保入口文件 `export default plugin`。
+
+### 修改了已有组件 type
+
+现象：旧页面或旧 DSL 找不到组件。
+
+处理：`type` 是稳定协议。重命名应作为破坏性变更处理，并提供迁移方案。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- SDK 导入边界：[SDK导入边界](../reference/SDK导入边界.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)

package/docs/component-development/getting-started/05-/350/207/252/346/243/200/344/270/216/346/216/222/351/224/231.md

@@ -0,0 +1,186 @@
+---
+type: getting-started
+capability: validation-and-troubleshooting
+related:
+  - reference/validateManifest校验规则.md
+  - reference/Manifest字段参考.md
+  - FAQ.md
+---
+# 05 - 自检与排错
+
+本文说明组件作者如何在交付前自检 manifest、组件 ref 契约、根节点注入和打包产物。
+
+---
+
+## 适用场景
+
+- 新增或修改组件后，需要确认契约是否正确。
+- 组件已经接入宿主，但渲染、事件、动作或状态不生效。
+- 构建后的组件包需要交付给宿主。
+
+---
+
+## 1. Manifest 静态校验
+
+`cdp-material-sdk/portable` 提供纯函数校验工具：
+
+```ts
+import {
+  validateManifest,
+  printValidationResult,
+} from 'cdp-material-sdk/portable';
+import { myManifest } from './components/MyComponent/manifest';
+
+const result = validateManifest(myManifest);
+printValidationResult(result);
+
+if (!result.valid) {
+  process.exitCode = 1;
+}
+```
+
+批量校验：
+
+```ts
+import {
+  validateManifests,
+  printValidationResult,
+} from 'cdp-material-sdk/portable';
+import { myPackage } from './package';
+
+const result = validateManifests(
+  myPackage.components.map((item) => item.manifest),
+);
+
+printValidationResult(result);
+
+if (!result.valid) {
+  process.exitCode = 1;
+}
+```
+
+建议在组件包工程中提供脚本：
+
+```jsonc
+{
+  "scripts": {
+    "validate:manifest": "tsx scripts/validate-manifests.ts"
+  }
+}
+```
+
+---
+
+## 2. Actions / State 运行时诊断
+
+如果组件声明了 `actions` 或 `state`，还需要确认 ref 实际暴露了对应能力。
+
+```ts
+import {
+  COMPONENT_STATE_KEY,
+  diagnoseMissingActionImpls,
+  diagnoseMissingStateKeys,
+} from 'cdp-material-sdk/portable';
+
+const refValue = ref.current;
+
+const missingActions = diagnoseMissingActionImpls(
+  Object.keys(myManifest.actions ?? {}),
+  refValue,
+);
+
+const missingStateKeys = diagnoseMissingStateKeys(
+  myManifest,
+  refValue?.[COMPONENT_STATE_KEY],
+);
+```
+
+如果 `missingActions` 或 `missingStateKeys` 非空，说明 manifest 声明和组件实现不一致。
+
+---
+
+## 3. rootPath 注入自检
+
+检查组件根节点是否拿到宿主注入属性：
+
+- `data-id`
+- `data-path`
+- `data-engine-hidden`
+
+推荐写法：
+
+```tsx
+<div {...slotProps?.root}>...</div>
+```
+
+对应 manifest：
+
+```ts
+import { INJECT_PATH_SLOT_PROPS } from 'cdp-material-sdk/portable';
+
+engine: {
+  render: {
+    injection: {
+      rootPath: INJECT_PATH_SLOT_PROPS,
+    },
+  },
+},
+```
+
+如果你使用自定义 `rootPath`，请确认该路径上的 props 最终透传到了真实 DOM 根节点。
+
+---
+
+## 4. 打包自检
+
+构建后检查：
+
+- [ ] 产物是 ESM。
+- [ ] `react`、`react-dom`、`react/jsx-runtime` 已 externalize。
+- [ ] 入口模块能解析出 `EngineComponentPlugin`。
+- [ ] `plugin.install(api)` 调用了 `api.registerPackage(pkg)`。
+- [ ] `pkg.components` 包含所有对外组件。
+- [ ] 没有从宿主源码路径或未公开的内部模块导入。
+
+---
+
+## 5. 常见现象与处理
+
+| 现象 | 优先检查 |
+|------|----------|
+| 组件能渲染，但设计器无法选中 | `rootPath` 是否声明并透传到真实 DOM |
+| Action 调用无效 | manifest `actions` 和 `useImperativeHandle` 暴露方法是否一致 |
+| State 表达式读不到 | 是否使用 `COMPONENT_STATE_KEY` 暴露状态 |
+| 自定义事件不触发 | `customEvents` 是否声明，`adapter.customEvents` 是否引用同一事件名 |
+| Loading 不生效 | `engine.render.loading.strategy` 是否符合组件实际能力 |
+| 表单值不更新 | 是否声明 `DATA_FIELD`，组件是否接收 `value` 并调用 `onChange` |
+| 容器内字段写错位置 | 数据容器是否正确建立 DataScope，字段是否有 `name` |
+
+---
+
+## 6. Error 与 Warning 的处理原则
+
+| 级别 | 处理建议 |
+|------|----------|
+| error | 必须修复，否则不应交付 |
+| warning | 需要确认是否符合预期；如果已按规则实现，可以记录并接受 |
+
+例如自定义 `rootPath` 会提示作者确认 props 是否透传到根 DOM。若组件已经按规则实现，可忽略该提示。
+
+---
+
+## 参考
+
+- [validateManifest 校验规则](../reference/validateManifest校验规则.md)
+- [DOM 根节点注入模型](../reference/DOM根节点注入模型.md)
+- [Actions / State 模型](../reference/ActionsState模型.md)
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 字段参考：[Manifest字段参考](../reference/Manifest字段参考.md)
+- FAQ：[FAQ](../FAQ.md)

package/docs/component-development/recipes//344/275/277/347/224/250Adapter/351/200/202/351/205/215/347/273/204/344/273/266API.md

@@ -0,0 +1,131 @@
+---
+type: recipe
+capability: adapter
+related:
+  - reference/Events模型.md
+  - reference/validateManifest校验规则.md
+  - recipes/接入第三方React组件库.md
+---
+# 使用 Adapter 适配组件 API
+
+Adapter 用于把组件自身 API 映射到 CDP 约定。它适合接入第三方组件库或历史组件。
+
+---
+
+## 适用场景
+
+- 第三方组件的 prop 名与 CDP 默认名不同。
+- 第三方组件的事件 prop 名不同。
+- 需要对传入 props 做轻量转换。
+
+---
+
+## 可以跳过的情况
+
+- 你可以在 wrapper 内直接转换 API。
+- 组件本身已经使用 `value`、`onChange`、`onClick` 等 CDP 约定。
+- 适配逻辑复杂，需要在组件代码中处理。
+
+---
+
+## propMapping
+
+将 CDP prop 名映射为组件实际 prop 名：
+
+```ts
+adapter: {
+  propMapping: {
+    loading: 'spinning',
+    value: 'selectedValue',
+  },
+},
+```
+
+适合简单重命名。
+
+---
+
+## events 映射
+
+标准事件映射：
+
+```ts
+events: {
+  click: { title: '点击' },
+},
+adapter: {
+  events: {
+    click: {
+      propName: 'onPress',
+    },
+  },
+},
+```
+
+自定义事件映射：
+
+```ts
+customEvents: {
+  'acme:rowClick': {
+    title: '行点击',
+    payloadSchema: { type: 'object' },
+  },
+},
+adapter: {
+  customEvents: {
+    'acme:rowClick': {
+      propName: 'onRowClick',
+    },
+  },
+},
+```
+
+---
+
+## mapProps
+
+当静态映射不够时，可以使用 `mapProps`：
+
+```ts
+adapter: {
+  mapProps: (props) => ({
+    ...props,
+    selectedValue: props.value,
+    onSelectedValueChange: props.onChange,
+  }),
+},
+```
+
+注意：`mapProps` 是逃生舱。优先使用 wrapper 或 `propMapping`，避免把复杂逻辑藏在 manifest 中。
+
+---
+
+## 自检
+
+- [ ] adapter 标准事件已经先在 `events` 声明。
+- [ ] adapter 自定义事件已经先在 `customEvents` 声明。
+- [ ] 每个 adapter event 都有 `propName`。
+- [ ] `propMapping` 没有和 wrapper 内转换重复冲突。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### Adapter 引用了未声明事件
+
+先声明事件，再用 adapter 映射。否则 `validateManifest()` 会报错。
+
+### 把复杂业务逻辑写进 mapProps
+
+`mapProps` 只适合轻量适配。复杂逻辑应该写在 React wrapper 中。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[Events模型](../reference/Events模型.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 任务 Recipe：[接入第三方React组件库](./接入第三方React组件库.md)