cdp-material-sdk 0.0.5

package/docs/component-development/reference/Manifest/345/255/227/346/256/265/345/217/202/350/200/203.md

@@ -0,0 +1,251 @@
+---
+type: reference
+capability: manifest
+related:
+  - getting-started/03-开发最小可运行组件.md
+  - recipes/声明布局容器组件.md
+  - recipes/配置设计器元信息.md
+  - reference/validateManifest校验规则.md
+  - reference/示例代码索引.md
+---
+# Manifest 字段参考
+
+`ComponentManifest` 是 CDP 组件的静态描述。组件作者通过它声明组件的身份、能力、配置项、事件、动作、状态和渲染策略。
+
+---
+
+## 顶层字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `type` | `string` | 是 | 组件唯一标识，建议带组织前缀 |
+| `alias` | `string[]` | 否 | 历史别名或兼容名 |
+| `meta` | `object` | 是 | 基本信息 |
+| `traits` | `ComponentTrait[]` | 否 | 能力声明 |
+| `props` | `ObjectSchema` | 否 | 可配置 props 的 JSON Schema |
+| `events` | `EventSpec[]` | 否 | 标准事件声明 |
+| `customEvents` | `Record<string, CustomEventSpec>` | 否 | 自定义事件声明 |
+| `actions` | `Record<string, ActionSpec>` | 否 | 组件动作声明 |
+| `state` | `Record<string, StateSpec>` | 否 | 运行时状态声明 |
+| `slots` | `Record<string, SlotDefinition>` | 否 | 插槽声明 |
+| `adapter` | `ComponentAdapter` | 否 | API 适配器 |
+| `engine` | `EnginePolicies` | 否 | 宿主渲染策略 |
+| `nesting` | `object` | 否 | 嵌套约束 |
+| `usage` | `AIUsageSpec` | 否 | 面向 AI 的使用提示 |
+
+---
+
+## meta
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `title` | `string` | 是 | 组件显示名 |
+| `category` | `ComponentCategory` | 是 | 组件分类 |
+| `valueSchema` | `JSONSchema7` | 否 | 组件 value 类型描述 |
+| `icon` | `string` | 否 | 图标 |
+| `description` | `string` | 否 | 组件说明 |
+| `hiddenInComponentList` | `boolean` | 否 | 是否在物料面板隐藏 |
+| `subGroup` | `string` | 否 | 物料面板子分组 |
+
+设计器相关字段（`icon` / `subGroup` / `hiddenInComponentList`）的选型与示例见 [配置设计器元信息](../recipes/配置设计器元信息.md)。
+
+---
+
+## engine.render.injection
+
+```ts
+engine: {
+  render: {
+    injection: {
+      rootPath: INJECT_PATH_SLOT_PROPS,
+    },
+  },
+},
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `rootPath` | `string` | 宿主根节点属性注入位置 |
+
+详见 [DOM 根节点注入模型](./DOM根节点注入模型.md)。
+
+---
+
+## engine.render.loading
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'native',
+      propName: 'spinning',
+    },
+  },
+},
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `strategy` | `'native' \| 'wrapper' \| 'none'` | Loading 接管策略 |
+| `propName` | `string` | `native` 模式下注入的 prop 名 |
+| `wrapperType` | `'spin' \| 'skeleton' \| 'wave' \| string` | `wrapper` 模式的遮罩类型 |
+| `wrapperProps` | `Record<string, any>` | 传给 wrapper 的额外参数 |
+
+详见 [Loading 策略模型](./Loading策略模型.md)。
+
+---
+
+## actions
+
+```ts
+actions: {
+  refresh: {
+    title: '刷新',
+    description: '重新加载数据',
+    params: { type: 'object' },
+    returns: { type: 'boolean' },
+  },
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `title` | 是 | 动作显示名 |
+| `description` | 否 | 动作说明 |
+| `params` | 否 | 参数 JSON Schema，声明时 `type` 必须是 `object` |
+| `returns` | 否 | 返回值 JSON Schema，建议声明 |
+
+---
+
+## state
+
+```ts
+state: {
+  selectedRowKeys: {
+    title: '选中行',
+    schema: { type: 'array', items: { type: 'string' } },
+  },
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `title` | 是 | 状态显示名 |
+| `description` | 否 | 状态说明 |
+| `schema` | 是 | 状态值 JSON Schema |
+
+---
+
+## slots
+
+```ts
+slots: {
+  header: {
+    title: '头部',
+    description: '头部内容',
+  },
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `title` | 插槽显示名，必填 |
+| `description` | 插槽说明 |
+| `defaultEnabled` | 是否默认启用 |
+| `allowedChildren` | 允许的子组件类型 |
+| `scoped` | 是否作用域插槽 |
+| `scopeDescription` | 作用域数据说明 |
+| `dynamic` | 是否动态插槽 |
+| `dynamicSource` | 动态插槽来源 props 路径 |
+| `dynamicFilter` | 动态插槽过滤字段 |
+| `dynamicKey` | 动态插槽 key 模板 |
+| `dynamicTitle` | 动态插槽标题模板 |
+
+---
+
+## nesting
+
+`nesting` 用于约束容器与子组件的嵌套关系。
+
+```ts
+nesting: {
+  allowedChildren: ['acme.TabPane'],
+  allowedParents: ['acme.Tabs'],
+  minChildren: 1,
+  maxChildren: 12,
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `allowedChildren` | `string[]` | 允许放入的子组件 `type` 列表 |
+| `allowedParents` | `string[]` | 限制本组件只能作为这些父组件的子节点 |
+| `minChildren` | `number` | 最少子组件数量 |
+| `maxChildren` | `number` | 最多子组件数量 |
+
+`nesting` 约束面向默认 `children` 区域；具名插槽另有 `slots[*].allowedChildren` 独立约束。
+
+任务步骤见 [声明布局容器组件](../recipes/声明布局容器组件.md)。
+
+---
+
+## usage
+
+`usage` 用于给 AI 或设计器提供额外提示，建议组件从最小实现开始就声明。
+
+```ts
+usage: {
+  tips: ['适合展示短文本'],
+  warnings: ['不建议用于长篇富文本'],
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `tips` | `string[]` | 使用建议、适用场景等正向提示 |
+| `warnings` | `string[]` | 不适用场景、常见误用提醒 |
+
+---
+
+## 最小示例
+
+```ts
+import {
+  COMPONENT_CATEGORY,
+  INJECT_PATH_SLOT_PROPS,
+  type ComponentManifest,
+} from 'cdp-material-sdk/portable';
+
+export const manifest = {
+  type: 'acme.Text',
+  meta: {
+    title: '文本',
+    category: COMPONENT_CATEGORY.GENERAL,
+  },
+  engine: {
+    render: {
+      injection: {
+        rootPath: INJECT_PATH_SLOT_PROPS,
+      },
+    },
+  },
+  props: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', title: '文本内容' },
+    },
+  },
+} satisfies ComponentManifest;
+```
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 关联文档：[03-开发最小可运行组件](../getting-started/03-开发最小可运行组件.md)
+- 任务 Recipe：[声明布局容器组件](../recipes/声明布局容器组件.md)
+- 任务 Recipe：[配置设计器元信息](../recipes/配置设计器元信息.md)
+- 校验规则：[validateManifest校验规则](./validateManifest校验规则.md)
+- 示例索引：[示例代码索引](./示例代码索引.md)

package/docs/component-development/reference/SDK/345/257/274/345/205/245/350/276/271/347/225/214.md

@@ -0,0 +1,119 @@
+---
+type: reference
+capability: sdk-boundary
+related:
+  - getting-started/01-创建或接入组件库工程.md
+  - recipes/接入第三方React组件库.md
+  - reference/示例代码索引.md
+---
+# SDK 导入边界
+
+第三方组件作者应只依赖 `cdp-material-sdk` 的公开入口，不应导入宿主内部实现。
+
+---
+
+## 推荐入口
+
+### `cdp-material-sdk/portable`
+
+默认入口，适合绝大多数组件作者。
+
+可用于：
+
+- `ComponentManifest`
+- `EngineComponentPackage`
+- `EngineComponentPlugin`
+- `COMPONENT_TRAIT`
+- `COMPONENT_CATEGORY`
+- `INJECT_PATH_SLOT_PROPS`
+- `BaseUIProps`
+- `COMPONENT_STATE_KEY`
+- `validateManifest()`
+- `diagnoseMissingActionImpls()`
+- `diagnoseMissingStateKeys()`
+
+示例：
+
+```ts
+import {
+  COMPONENT_CATEGORY,
+  COMPONENT_TRAIT,
+  INJECT_PATH_SLOT_PROPS,
+  validateManifest,
+  type ComponentManifest,
+  type EngineComponentPlugin,
+} from 'cdp-material-sdk/portable';
+```
+
+---
+
+### `cdp-material-sdk/host-react`
+
+宿主耦合入口，只有在确认组件包与宿主共享 React runtime 和 Context 身份时使用。
+
+可用于：
+
+- `DataScope`
+- `useDataContainer`
+- `useDataContainerApi`
+- `PageContext`
+
+如果不能确认共享 runtime，请不要使用该入口。
+
+---
+
+## 不建议依赖的对象
+
+第三方作者不应导入：
+
+- 宿主源码路径。
+- 未从 `cdp-material-sdk/portable` 或 `cdp-material-sdk/host-react` 导出的对象。
+- 组件加载、注册、运行时增强、页面状态管理等宿主内部模块。
+
+这些对象属于宿主实现细节，不承诺作为第三方兼容契约。第三方组件包只应面向 SDK 公开入口编程。
+
+---
+
+## 依赖处理
+
+| 依赖 | 建议 |
+|------|------|
+| `react` | peerDependency + externalize |
+| `react-dom` | peerDependency + externalize |
+| `react/jsx-runtime` | externalize |
+| `cdp-material-sdk/portable` | 普通依赖 |
+| `cdp-material-sdk/host-react` | 仅在确认共享 runtime 时使用 |
+
+---
+
+## 安装
+
+推荐从 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）。
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 关联文档：[01-创建或接入组件库工程](../getting-started/01-创建或接入组件库工程.md)
+- 任务 Recipe：[接入第三方React组件库](../recipes/接入第三方React组件库.md)
+- 示例索引：[示例代码索引](./示例代码索引.md)

package/docs/component-development/reference/Slots/346/250/241/345/236/213.md

@@ -0,0 +1,110 @@
+---
+type: reference
+capability: slots
+related:
+  - recipes/声明插槽.md
+  - reference/validateManifest校验规则.md
+  - reference/Traits能力模型.md
+---
+# Slots 模型
+
+Slots 描述组件可被填充的内容区域。插槽是可选能力，只有组件需要承载子内容时才声明。
+
+---
+
+## 插槽类型
+
+| 类型 | 适用场景 | 关键字段 |
+|------|----------|----------|
+| 命名插槽 | 固定区域，如 header、footer | `title` |
+| 作用域插槽 | 子内容需要上下文，如当前行数据 | `scoped`、`scopeDescription` |
+| 动态插槽 | 根据 props 数组生成多个插槽 | `dynamic`、`dynamicSource`、`dynamicKey` |
+
+---
+
+## 命名插槽
+
+```ts
+slots: {
+  header: {
+    title: '头部',
+  },
+}
+```
+
+组件消费：
+
+```tsx
+const { _slots } = props;
+return <header>{_slots?.header}</header>;
+```
+
+---
+
+## 作用域插槽
+
+```ts
+slots: {
+  rowActions: {
+    title: '行操作',
+    scoped: true,
+    scopeDescription: '提供当前行 record 和 rowIndex',
+  },
+}
+```
+
+`scopeDescription` 能帮助设计器用户和 AI 理解可用上下文。
+
+---
+
+## 动态插槽
+
+```ts
+slots: {
+  columnSlot: {
+    title: '列模板',
+    dynamic: true,
+    dynamicSource: 'columns',
+    dynamicKey: 'col:{dataIndex}',
+    dynamicTitle: '列：{title}',
+    scoped: true,
+    scopeDescription: '提供当前行 record',
+  },
+}
+```
+
+动态插槽必须声明 `dynamicSource` 和 `dynamicKey`。
+
+---
+
+## 模型约束摘要
+
+| 约束 | 说明 |
+|------|------|
+| `title` | 每个 slot 都应有可读显示名 |
+| `dynamicSource` / `dynamicKey` | 动态 slot 必须声明来源和稳定 key 模板 |
+| `scopeDescription` | 作用域 slot 建议说明可用上下文 |
+| `allowedChildren` | 用于限制可插入的子组件类型 |
+
+具体 error / warning 级别见 [validateManifest 校验规则](./validateManifest校验规则.md)。
+
+---
+
+## 选择建议
+
+| 场景 | 推荐 |
+|------|------|
+| 固定内容区域 | 命名插槽 |
+| 表格行操作 | 作用域插槽 |
+| 表格列模板 | 动态 + 作用域插槽 |
+| 简单展示组件 | 不声明 slots |
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 任务 Recipe：[声明插槽](../recipes/声明插槽.md)
+- 校验规则：[validateManifest校验规则](./validateManifest校验规则.md)
+- 模型参考：[Traits能力模型](./Traits能力模型.md)

package/docs/component-development/reference/Traits/350/203/275/345/212/233/346/250/241/345/236/213.md

@@ -0,0 +1,165 @@
+---
+type: reference
+capability: traits
+related:
+  - recipes/声明数据字段组件.md
+  - recipes/声明数据容器组件.md
+  - recipes/声明布局容器组件.md
+  - recipes/声明插槽.md
+  - reference/validateManifest校验规则.md
+---
+# Traits 能力模型
+
+Traits 用于声明组件具备什么能力。它不是样式分类，而是宿主、设计器、表达式和 AI 工具理解组件角色的协议。
+
+Traits 之间不互斥，一个组件可以同时声明多个 trait。例如 Form 同时是 `DATA_CONTAINER`（管理表单值）与 `LAYOUT_CONTAINER`（拖入字段子组件）；ClickableCard 可以同时是 `LAYOUT_CONTAINER` 与 `INTERACTION_CLICKABLE`。
+
+---
+
+## Trait 总览
+
+| Trait | 常量 | 适用组件 | 声明后含义 |
+|-------|------|----------|------------|
+| `Data.Field` | `COMPONENT_TRAIT.DATA_FIELD` | Input、Select、Switch、DatePicker | 组件是一个数据字段 |
+| `Data.Container` | `COMPONENT_TRAIT.DATA_CONTAINER` | Form、Table、List、CardList | 组件管理一组数据作用域 |
+| `Layout.Container` | `COMPONENT_TRAIT.LAYOUT_CONTAINER` | Card、Grid、Tabs、Collapse | 组件可以承载子组件或插槽内容 |
+| `Interaction.Clickable` | `COMPONENT_TRAIT.INTERACTION_CLICKABLE` | Button、Link、ClickableCard | 组件具备点击交互语义 |
+
+---
+
+## DATA_FIELD
+
+### 什么时候声明
+
+组件有一个主要业务值，并通过 `value` / `onChange` 与宿主同步。
+
+### 作者要做什么
+
+- 声明 `COMPONENT_TRAIT.DATA_FIELD`。
+- 声明 `meta.valueSchema`。
+- 组件接收 `value`。
+- 值变化时调用 `onChange(nextValue)`。
+
+### 宿主可据此做什么
+
+- 注入和回写字段值。
+- 在数据容器内按字段名组织值。
+- 让表达式、设计器和 AI 工具识别 value 类型。
+- 基于 `valueSchema` 推断标准 value 状态。
+
+---
+
+## DATA_CONTAINER
+
+### 什么时候声明
+
+组件自身管理子字段的数据空间，例如 Form 或 Table。
+
+### 作者要做什么
+
+- 声明 `COMPONENT_TRAIT.DATA_CONTAINER`。
+- 声明 `meta.valueSchema` 描述容器数据结构。
+- 在子组件渲染区域用 `DataScope`（从 `cdp-material-sdk/host-react` 导入）建立数据作用域；`DataScope` 不接受 `componentId` 入参，由引擎运行时自动装配。
+- 如需读写容器数据，使用 `cdp-material-sdk/host-react` 中的 `useDataContainer` / `useDataContainerApi`。
+
+### 宿主可据此做什么
+
+- 为容器分配独立数据空间。
+- 支持子字段写入容器 value。
+- 让表达式和 AI 工具理解容器数据结构。
+- 基于 `DataScope` 提供的作用域，在表达式、设计器、表单校验中准确定位子字段。
+
+---
+
+## LAYOUT_CONTAINER
+
+### 什么时候声明
+
+组件可以承载子组件、插槽或模板内容。
+
+### 作者要做什么
+
+- 声明 `COMPONENT_TRAIT.LAYOUT_CONTAINER`。
+- 在组件实现中渲染 `children`（单一区域）或对应 slot 内容（多具名区域）。
+- 需要限制子组件类型、最少/最多数量、或能作为子节点的父组件时，声明 `nesting`。
+- 详细任务步骤见 [声明布局容器组件](../recipes/声明布局容器组件.md)。
+
+### 宿主可据此做什么
+
+- 在设计器中允许拖入子组件。
+- 根据 `nesting` 约束过滤可拖入的组件与数量。
+- 识别组件的布局容器语义。
+
+---
+
+## INTERACTION_CLICKABLE
+
+### 什么时候声明
+
+组件的核心行为是点击，例如 Button、Link、IconButton 或可点击卡片。
+
+### 作者要做什么
+
+- 声明 `COMPONENT_TRAIT.INTERACTION_CLICKABLE`。
+- 如果需要触发编排，声明 `events: { click: { title: '点击' } }`。
+- 组件实际触发点击时调用对应 `onClick`。
+
+### 宿主可据此做什么
+
+- 识别组件具备点击交互能力。
+- 将点击能力展示给设计器、事件系统或 AI 工具。
+
+---
+
+## Traits 与 valueSchema
+
+声明 `DATA_FIELD` 或 `DATA_CONTAINER` 时，建议同时声明 `meta.valueSchema`。
+
+```ts
+traits: [COMPONENT_TRAIT.DATA_FIELD],
+meta: {
+  title: '输入框',
+  category: COMPONENT_CATEGORY.DATA_ENTRY,
+  valueSchema: { type: 'string', default: '' },
+},
+```
+
+如果声明了数据 trait 但缺少 `valueSchema`，`validateManifest()` 会给出 warning。
+
+---
+
+## 选择表
+
+| 组件场景 | 推荐 traits |
+|----------|-------------|
+| 输入框、选择器、开关 | `DATA_FIELD` |
+| 表单 | `DATA_CONTAINER` + `LAYOUT_CONTAINER` |
+| 表格、列表 | `DATA_CONTAINER`，按需加 `LAYOUT_CONTAINER` |
+| 卡片、栅格、Tabs | `LAYOUT_CONTAINER` |
+| 按钮、链接 | `INTERACTION_CLICKABLE` |
+| 普通文本展示 | 可不声明 |
+
+---
+
+## 模型边界
+
+| 边界 | 说明 |
+|------|------|
+| `DATA_FIELD` | 仅用于有主要业务值且能回写的组件 |
+| `DATA_CONTAINER` | 用于管理子字段数据作用域；必须在子组件渲染区域提供 `DataScope`。与 `LAYOUT_CONTAINER` 不互斥，Form 这类容器应同时声明 |
+| `LAYOUT_CONTAINER` | 表示可承载子内容；有明确区域时建议同时声明 slots |
+| `INTERACTION_CLICKABLE` | 表示具备点击语义；需要编排响应时再声明 click event |
+
+数据 trait 与 `meta.valueSchema` 的校验级别见 [validateManifest 校验规则](./validateManifest校验规则.md)。
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 任务 Recipe：[声明数据字段组件](../recipes/声明数据字段组件.md)
+- 任务 Recipe：[声明数据容器组件](../recipes/声明数据容器组件.md)
+- 任务 Recipe：[声明布局容器组件](../recipes/声明布局容器组件.md)
+- 任务 Recipe：[声明插槽](../recipes/声明插槽.md)
+- 校验规则：[validateManifest校验规则](./validateManifest校验规则.md)