cdp-material-sdk 0.0.5

package/docs/component-development/reference/validateManifest/346/240/241/351/252/214/350/247/204/345/210/231.md

@@ -0,0 +1,171 @@
+---
+type: reference
+capability: validation
+related:
+  - reference/Manifest字段参考.md
+  - reference/Events模型.md
+  - reference/ActionsState模型.md
+  - reference/Slots模型.md
+  - reference/DOM根节点注入模型.md
+  - reference/Loading策略模型.md
+  - reference/Traits能力模型.md
+  - getting-started/05-自检与排错.md
+---
+# validateManifest 校验规则
+
+`validateManifest()` 是 `cdp-material-sdk/portable` 提供的纯函数校验工具，可在第三方组件包工程中直接使用。
+
+---
+
+## 使用方式
+
+```ts
+import {
+  validateManifest,
+  validateManifests,
+  printValidationResult,
+} from 'cdp-material-sdk/portable';
+
+const result = validateManifest(manifest);
+printValidationResult(result);
+```
+
+返回结构：
+
+```ts
+interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationError[];
+}
+```
+
+---
+
+## 基础字段
+
+| 规则 | 级别 |
+|------|------|
+| 缺少 `type` | error |
+| 缺少 `meta` | error |
+| 缺少 `meta.title` | error |
+| 缺少 `meta.category` | error |
+| `meta.category` 不合法 | error |
+| `meta.valueSchema.type` 不合法 | error |
+
+---
+
+## Traits 与 valueSchema
+
+| 规则 | 级别 |
+|------|------|
+| 声明 `DATA_FIELD` 或 `DATA_CONTAINER`，但缺少 `meta.valueSchema` | warning |
+
+---
+
+## Events
+
+模型说明见 [Events 模型](./Events模型.md)，任务步骤见 [声明事件](../recipes/声明事件.md)。
+
+| 规则 | 级别 |
+|------|------|
+| 标准事件缺少 `type` | error |
+| 标准事件类型不属于协议 | error |
+| 自定义事件缺少 `type` | error |
+| 自定义事件名不是 namespaced 形态 | error |
+| 自定义事件缺少 `payloadSchema` | error |
+
+---
+
+## Adapter Events
+
+| 规则 | 级别 |
+|------|------|
+| adapter 标准事件缺少 `type` | error |
+| adapter 标准事件类型不属于协议 | error |
+| adapter 标准事件未先在 `events` 声明 | error |
+| adapter 标准事件缺少 `propName` | error |
+| adapter 自定义事件名不是 namespaced 形态 | error |
+| adapter 自定义事件未先在 `customEvents` 声明 | error |
+| adapter 自定义事件缺少 `propName` | error |
+
+---
+
+## Actions
+
+模型说明和诊断工具见 [Actions / State 模型](./ActionsState模型.md)，任务步骤见 [声明动作与状态](../recipes/声明动作与状态.md)。
+
+| 规则 | 级别 |
+|------|------|
+| action 缺少 `title` | error |
+| action 缺少 `returns` | warning |
+| action 声明了 `params`，但 `params.type !== 'object'` | error |
+
+---
+
+## State
+
+模型说明和诊断工具见 [Actions / State 模型](./ActionsState模型.md)。
+
+| 规则 | 级别 |
+|------|------|
+| state 缺少 `title` | error |
+| state 缺少 `schema` | error |
+| state `schema.type` 不合法 | error |
+
+---
+
+## Slots
+
+模型说明见 [Slots 模型](./Slots模型.md)，任务步骤见 [声明插槽](../recipes/声明插槽.md)。
+
+| 规则 | 级别 |
+|------|------|
+| slot 缺少 `title` | error |
+| 动态 slot 缺少 `dynamicSource` | error |
+| 动态 slot 缺少 `dynamicKey` | error |
+| 作用域 slot 缺少 `scopeDescription` | warning |
+| `allowedChildren` 不是字符串数组 | error |
+
+---
+
+## rootPath
+
+模型说明见 [DOM 根节点注入模型](./DOM根节点注入模型.md)，任务步骤见 [配置 DOM 根节点注入](../recipes/配置DOM根节点注入.md)。
+
+| 规则 | 级别 | 说明 |
+|------|------|------|
+| 未声明 `engine.render.injection.rootPath` | warning | 宿主会外层 `<div>` 兜底，建议显式声明 |
+| 使用自定义 rootPath | warning | 提醒作者确认该路径 props 已透传到真实 DOM |
+
+自定义 rootPath 是合法选择。若组件已经按规则透传，可以忽略该提示。
+
+---
+
+## Loading
+
+当前校验工具主要覆盖 manifest 结构、events、actions、state、slots 和 rootPath。`engine.render.loading` 的策略选择需作者按 [Loading 策略模型](./Loading策略模型.md) 自检。
+
+---
+
+## Error 与 Warning 处理建议
+
+| 级别 | 建议 |
+|------|------|
+| error | 必须修复 |
+| warning | 需要确认是否符合预期；确认后可接受 |
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 字段参考：[Manifest字段参考](./Manifest字段参考.md)
+- 模型参考：[Events模型](./Events模型.md)
+- 模型参考：[ActionsState模型](./ActionsState模型.md)
+- 模型参考：[Slots模型](./Slots模型.md)
+- 模型参考：[DOM根节点注入模型](./DOM根节点注入模型.md)
+- 模型参考：[Loading策略模型](./Loading策略模型.md)
+- 模型参考：[Traits能力模型](./Traits能力模型.md)
+- 自检与排错：[05-自检与排错](../getting-started/05-自检与排错.md)

package/docs/component-development/reference//345/274/225/346/223/216/345/237/272/347/241/200/350/203/275/345/212/233/346/250/241/345/236/213.md

@@ -0,0 +1,70 @@
+---
+type: reference
+capability: engine-base
+related:
+  - reference/DOM根节点注入模型.md
+  - recipes/配置DOM根节点注入.md
+  - reference/ActionsState模型.md
+  - reference/Events模型.md
+---
+# 引擎基础能力模型
+
+引擎基础能力是宿主自动赋予所有组件的通用运行时能力。组件作者通常不需要在 manifest 中重复声明这些能力，只需要避免冲突，并确保组件根节点能承接宿主注入。
+
+---
+
+## 基础能力总览
+
+| 能力 | 外部含义 | 组件作者需要做什么 |
+|------|----------|-------------------|
+| `hidden` prop | 宿主告诉组件当前是否隐藏 | 可按需读取，但不要改成其他业务语义 |
+| `getHidden` action | 外部流程读取组件显隐状态 | 不要重复声明同名 action |
+| `setHidden` action | 外部流程设置组件显隐状态 | 不要重复声明同名 action |
+| `toggleHidden` action | 外部流程切换组件显隐状态 | 不要重复声明同名 action |
+| `hidden` state | 外部表达式、编排或 AI 读取当前显隐状态 | 不要重复声明同名 state |
+| `mount` / `unmount` events | 基础生命周期通知 | 普通组件不需要重复声明 |
+
+---
+
+## 与组件 manifest 的关系
+
+基础能力由宿主在运行时补充。第三方组件 manifest 应只声明组件自己的业务能力，例如：
+
+- 业务 actions，例如 `refresh`、`clear`、`focus`。
+- 业务 state，例如 `selectedRows`、`keyword`。
+- 业务 events，例如 `valueChange`、`itemClick` 或自定义事件。
+
+不要为了获得显隐控制而在 manifest 中手写 `getHidden`、`setHidden`、`toggleHidden` 或 `hidden` state。
+
+---
+
+## 与 DOM 根节点注入的关系
+
+基础能力中的显隐、选中、定位等能力需要和组件真实 DOM 对齐。组件作者不需要关心宿主内部使用了哪些 DOM 标记，只需要确认：
+
+- 组件声明了合适的 `engine.render.injection.rootPath`。
+- rootPath 指向的 props 最终展开到了真实 DOM 节点。
+- 设计器选中、显隐控制和组件视觉区域一致。
+
+具体配置方式见 [DOM 根节点注入模型](./DOM根节点注入模型.md) 和 [配置 DOM 根节点注入](../recipes/配置DOM根节点注入.md)。
+
+---
+
+## 与 actions / state / events 的关系
+
+| 文档 | 说明 |
+|------|------|
+| [Actions / State 模型](./ActionsState模型.md) | 描述组件自定义 actions 和 state 的声明方式 |
+| [Events 模型](./Events模型.md) | 描述组件自定义事件与标准事件 |
+| [DOM 根节点注入模型](./DOM根节点注入模型.md) | 描述基础能力如何与真实 DOM 根节点对齐 |
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Reference 提供稳定模型和规则，Recipe 提供任务步骤。
+
+- 模型参考：[DOM 根节点注入模型](./DOM根节点注入模型.md)
+- 任务 Recipe：[配置DOM根节点注入](../recipes/配置DOM根节点注入.md)
+- 模型参考：[ActionsState模型](./ActionsState模型.md)
+- 模型参考：[Events模型](./Events模型.md)

package/docs/component-development/reference//347/244/272/344/276/213/344/273/243/347/240/201/347/264/242/345/274/225.md

@@ -0,0 +1,163 @@
+---
+type: reference
+capability: examples
+related:
+  - getting-started/03-开发最小可运行组件.md
+  - recipes/接入第三方React组件库.md
+  - recipes/声明事件.md
+  - recipes/声明动作与状态.md
+  - recipes/声明插槽.md
+---
+# 示例代码索引
+
+本文汇总文档内可直接参考的组件开发示例。第三方组件作者不需要访问宿主源码，也不需要依赖宿主内部测试文件。
+
+---
+
+## 最小组件包
+
+适合第一次接入或新建独立组件包。
+
+- **工程结构：** [创建或接入组件库工程](../getting-started/01-创建或接入组件库工程.md)
+- **组件包注册：** [创建组件包并注册](../getting-started/02-创建组件包并注册.md)
+- **最小组件：** [开发最小可运行组件](../getting-started/03-开发最小可运行组件.md)
+- **构建交付：** [构建发布与宿主接入](../getting-started/04-构建发布与宿主接入.md)
+- **交付前自检：** [自检与排错](../getting-started/05-自检与排错.md)
+
+---
+
+## 复制模板：组件包入口
+
+```ts
+import type {
+  EngineComponentPackage,
+  EngineComponentPlugin,
+} from 'cdp-material-sdk/portable';
+import { AcmeText } from './components/AcmeText';
+import { acmeTextManifest } from './components/AcmeText/manifest';
+
+const pkg: EngineComponentPackage = {
+  id: '@acme/cdp-components',
+  version: '1.0.0',
+  components: [
+    {
+      component: AcmeText,
+      manifest: acmeTextManifest,
+    },
+  ],
+};
+
+const plugin: EngineComponentPlugin = {
+  id: pkg.id,
+  version: pkg.version,
+  install: (api) => {
+    api.registerPackage(pkg);
+  },
+};
+
+export default plugin;
+```
+
+---
+
+## 复制模板：最小 React 组件
+
+```tsx
+import { forwardRef } from 'react';
+import type { BaseUIProps } from 'cdp-material-sdk/portable';
+
+export interface AcmeTextProps extends BaseUIProps<HTMLDivElement> {
+  text?: string;
+}
+
+export const AcmeText = forwardRef<HTMLDivElement, AcmeTextProps>((props, ref) => {
+  const { text = 'Hello CDP', slotProps } = props;
+
+  return (
+    <div {...slotProps?.root} ref={ref}>
+      {text}
+    </div>
+  );
+});
+```
+
+---
+
+## 复制模板：最小 Manifest
+
+```ts
+import {
+  COMPONENT_CATEGORY,
+  INJECT_PATH_SLOT_PROPS,
+  type ComponentManifest,
+} from 'cdp-material-sdk/portable';
+
+export const acmeTextManifest = {
+  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: '文本内容',
+        default: 'Hello CDP',
+      },
+    },
+  },
+} satisfies ComponentManifest;
+```
+
+---
+
+## 按场景查示例
+
+| 场景 | 文档 |
+|------|------|
+| 包装 Ant Design、ECharts 或自研 UI Kit | [接入第三方 React 组件库](../recipes/接入第三方React组件库.md) |
+| 输入框、选择器、开关 | [声明数据字段组件](../recipes/声明数据字段组件.md) |
+| Form、Table、List | [声明数据容器组件](../recipes/声明数据容器组件.md) |
+| 点击、值变化、行点击 | [声明事件](../recipes/声明事件.md) |
+| 刷新、清空、聚焦、读取选中项 | [声明动作与状态](../recipes/声明动作与状态.md) |
+| 卡片区、表格列模板、列表项模板 | [声明插槽](../recipes/声明插槽.md) |
+| 第三方组件 props / events 名称不同 | [使用 Adapter 适配组件 API](../recipes/使用Adapter适配组件API.md) |
+| 设计器选中、显隐、根 DOM 注入 | [配置 DOM 根节点注入](../recipes/配置DOM根节点注入.md) |
+| 外部控制加载态 | [配置 Loading 策略](../recipes/配置Loading策略.md) |
+
+---
+
+## SDK 校验工具
+
+第三方作者应从 `cdp-material-sdk/portable` 导入校验工具：
+
+```ts
+import {
+  validateManifest,
+  validateManifests,
+  printValidationResult,
+} from 'cdp-material-sdk/portable';
+```
+
+不要依赖 SDK 源码路径或宿主内部路径。
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 关联文档：[03-开发最小可运行组件](../getting-started/03-开发最小可运行组件.md)
+- 任务 Recipe：[接入第三方React组件库](../recipes/接入第三方React组件库.md)
+- 任务 Recipe：[声明事件](../recipes/声明事件.md)
+- 任务 Recipe：[声明动作与状态](../recipes/声明动作与状态.md)
+- 任务 Recipe：[声明插槽](../recipes/声明插槽.md)

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "cdp-material-sdk",
+  "version": "0.0.5",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GroovyKetchup/cdp-material-sdk.git"
+  },
+  "homepage": "https://github.com/GroovyKetchup/cdp-material-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/GroovyKetchup/cdp-material-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "node scripts/build-material-sdk.mjs && tsc -p tsconfig.build.json",
+    "pack:dry-run": "npm pack --json --dry-run",
+    "release:check": "npm run build && npm run pack:dry-run"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./portable": {
+      "types": "./dist/portable.d.ts",
+      "import": "./dist/portable.js"
+    },
+    "./host-react": {
+      "types": "./dist/host-react.d.ts",
+      "import": "./dist/host-react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/component-development",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@types/json-schema": "^7.0.15",
+    "json-schema-to-ts": "^3.1.1",
+    "lodash-es": "^4.17.21",
+    "zustand": "^5.0.9"
+  },
+  "peerDependencies": {
+    "@types/react": "^19.1.16",
+    "@types/react-dom": "^19.1.9",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
+  },
+  "devDependencies": {
+    "@types/lodash-es": "^4.17.12",
+    "@types/react": "^19.1.16",
+    "@types/react-dom": "^19.1.9",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "typescript": "~5.9.3",
+    "vite": "^7.1.7"
+  }
+}