cdp-material-sdk 0.0.5

package/docs/component-development/recipes//351/205/215/347/275/256/350/256/276/350/256/241/345/231/250/345/205/203/344/277/241/346/201/257.md

@@ -0,0 +1,153 @@
+---
+type: recipe
+capability: designer-meta
+related:
+  - reference/Manifest字段参考.md
+  - getting-started/03-开发最小可运行组件.md
+  - reference/validateManifest校验规则.md
+---
+# 配置设计器元信息
+
+`meta` 中的几个字段决定组件在设计器物料面板里如何被找到、如何被分组、是否可见。它们不影响运行时渲染，但直接影响设计器使用体验和 AI 工具识别。
+
+---
+
+## 适用场景
+
+- 组件需要更友好的图标或显示名。
+- 组件应该归到分类下的某个子分组。
+- 组件是某个父组件的内部部件，不应单独出现在物料面板。
+
+---
+
+## 可以跳过的情况
+
+- 组件用默认分类、不需要图标、希望直接出现在物料面板。
+- 组件还在最小实现阶段，先按 [03-开发最小可运行组件](../getting-started/03-开发最小可运行组件.md) 跑通再回来配置。
+
+---
+
+## 字段总览
+
+| 字段 | 类型 | 默认 | 影响 |
+|------|------|------|------|
+| `meta.title` | `string` | 必填 | 物料面板显示名、设计器节点名 |
+| `meta.description` | `string` | 无 | 物料面板 Tooltip、AI 工具理解组件用途 |
+| `meta.category` | `ComponentCategory` | 必填 | 物料面板顶层分类 |
+| `meta.subGroup` | `string` | 无 | 在 `category` 下进一步分组 |
+| `meta.icon` | `string` | 无 | 物料面板图标、设计器节点图标 |
+| `meta.hiddenInComponentList` | `boolean` | `false` | 是否在物料面板中隐藏 |
+
+---
+
+## 配置示例
+
+```ts
+import {
+  COMPONENT_CATEGORY,
+  type ComponentManifest,
+} from 'cdp-material-sdk/portable';
+
+export const acmeAvatarManifest = {
+  type: 'acme.Avatar',
+  meta: {
+    title: '头像',
+    description: '用于展示用户头像、首字母或占位图',
+    category: COMPONENT_CATEGORY.DATA_DISPLAY,
+    subGroup: '用户信息',
+    icon: 'user-circle',
+  },
+  // ...
+} satisfies ComponentManifest;
+```
+
+---
+
+## icon
+
+`meta.icon` 是字符串，具体含义由设计器决定。常见约定：
+
+- 设计器内置图标库的图标名（例如 `user-circle`、`table-2`）。
+- 组件包随附的 SVG 资源标识（如 `acme://icons/avatar`）。
+- 远程图标 URL（部分设计器支持）。
+
+经验法则：
+
+- 优先使用设计器内置图标库，跨组件保持视觉一致。
+- 不写就会用分类的默认图标，作者在最小实现阶段可以先不填。
+- 不要把业务态图标（如「在线 / 离线」）放进 `icon`，那是组件运行时的渲染范围。
+
+---
+
+## subGroup
+
+`subGroup` 在 `category` 之下做二次分组，物料面板会把同一 `subGroup` 的组件聚合显示。
+
+| 用法 | 示例 |
+|------|------|
+| 同分类下的功能子集 | `category: DATA_ENTRY`、`subGroup: '日期时间'` |
+| 同源组件聚合 | `category: DATA_DISPLAY`、`subGroup: '用户信息'` |
+| 业务领域聚合 | `category: GENERAL`、`subGroup: '工作流'` |
+
+经验法则：
+
+- 同包内尽量复用相同的 `subGroup` 字符串，避免出现「日期时间」「日期 / 时间」「日期类」这种近义但不同的分组。
+- 跨包的 `subGroup` 由设计器决定是否合并展示，不要依赖跨包合并行为。
+
+---
+
+## hiddenInComponentList
+
+声明 `hiddenInComponentList: true` 后，组件不会出现在物料面板，但仍可以：
+
+- 通过父组件的 `slots.allowedChildren` 或 `nesting.allowedChildren` 被自动加入。
+- 被设计器复制粘贴、撤销恢复。
+- 在运行时渲染。
+
+典型场景：
+
+- **父子绑定的子部件**：例如 `acme.TabPane`、`acme.StepItem`、`acme.TableColumn`，必须在父容器里使用，不应单独拖入。
+- **内部辅助组件**：例如某个仅在 wrapper 中使用的中间层组件。
+- **过渡期废弃组件**：保持 `type` 兼容性，但不希望新页面再使用。
+
+经验法则：
+
+- 子部件类组件几乎都应该 `hiddenInComponentList: true`，并通过父组件的 `nesting` / `slots` 暴露入口。
+- 不要用 `hiddenInComponentList` 来"软删除"组件——保留 manifest 但不可见会让维护者困惑。彻底废弃应通过版本号或 `alias` 标记。
+
+---
+
+## 自检
+
+- [ ] `meta.title` 与 `meta.description` 都是面向使用者的可读文案。
+- [ ] `meta.category` 选择合适的顶层分类。
+- [ ] 同包内 `subGroup` 字符串保持一致。
+- [ ] `meta.icon` 引用设计器或组件包能够解析的标识。
+- [ ] 子部件类组件已声明 `hiddenInComponentList: true`，并由父组件通过 `nesting` / `slots` 暴露。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### 用 hiddenInComponentList 隐藏未实现的组件
+
+物料面板看不到，但 manifest 仍会被加载、校验。请直接不导出该组件，或用包级开关控制。
+
+### 在 title 里塞业务前缀
+
+`meta.title` 是物料面板的显示名，建议简洁可读（"头像"、"日期选择"）。业务来源信息可以放进 `description`，或通过 `subGroup` 分组。
+
+### subGroup 写得太散
+
+每写一次新的 `subGroup` 字符串，物料面板就会多一个分组。同一类组件若要聚合，请在包内复用同一个常量。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 字段参考：[Manifest字段参考](../reference/Manifest字段参考.md)
+- 起步流程：[03-开发最小可运行组件](../getting-started/03-开发最小可运行组件.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)

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

@@ -0,0 +1,124 @@
+---
+type: reference
+capability: actions-state
+related:
+  - recipes/声明动作与状态.md
+  - reference/validateManifest校验规则.md
+  - reference/示例代码索引.md
+---
+# Actions / State 模型
+
+Actions 和 State 共用 React ref 通道：组件通过 `useImperativeHandle` 暴露方法和只读运行时状态。
+
+---
+
+## Actions
+
+Action 是宿主调用组件的方法。
+
+Manifest：
+
+```ts
+actions: {
+  refresh: {
+    title: '刷新',
+    returns: { type: 'boolean' },
+  },
+}
+```
+
+实现：
+
+```tsx
+useImperativeHandle(ref, () => ({
+  refresh: async () => true,
+}), []);
+```
+
+规则：
+
+- `actions.*.title` 必填。
+- `params` 如果声明，`type` 必须是 `object`。
+- `returns` 建议声明。
+- action key 必须和 ref 方法名一致。
+
+---
+
+## State
+
+State 是组件暴露给宿主的只读运行时快照。
+
+Manifest：
+
+```ts
+state: {
+  highlighted: {
+    title: '高亮状态',
+    schema: { type: 'boolean' },
+  },
+}
+```
+
+实现：
+
+```tsx
+import { COMPONENT_STATE_KEY } from 'cdp-material-sdk/portable';
+
+useImperativeHandle(ref, () => ({
+  [COMPONENT_STATE_KEY]: {
+    highlighted,
+  },
+}), [highlighted]);
+```
+
+规则：
+
+- `state.*.title` 必填。
+- `state.*.schema` 必填。
+- state key 必须出现在 `COMPONENT_STATE_KEY` 对象中。
+- state 是只读的；修改组件应通过 action。
+
+---
+
+## 诊断工具
+
+```ts
+import {
+  COMPONENT_STATE_KEY,
+  diagnoseMissingActionImpls,
+  diagnoseMissingStateKeys,
+} from 'cdp-material-sdk/portable';
+
+const missingActions = diagnoseMissingActionImpls(
+  Object.keys(manifest.actions ?? {}),
+  ref.current,
+);
+
+const missingStates = diagnoseMissingStateKeys(
+  manifest,
+  ref.current?.[COMPONENT_STATE_KEY],
+);
+```
+
+---
+
+## 模型边界
+
+| 边界 | 说明 |
+|------|------|
+| action key 与 ref 方法 | manifest 中声明的 action key 是宿主调用 ref 方法的名称 |
+| action params | 声明参数时，`params.type` 必须是 `object` |
+| state 写操作 | State 是只读运行时快照，需要修改组件时应通过 action |
+| 诊断工具 | 实现一致性检查见任务文档和 `diagnoseMissingActionImpls()` / `diagnoseMissingStateKeys()` |
+
+具体 error / warning 级别见 [validateManifest 校验规则](./validateManifest校验规则.md)。
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 任务 Recipe：[声明动作与状态](../recipes/声明动作与状态.md)
+- 校验规则：[validateManifest校验规则](./validateManifest校验规则.md)
+- 示例索引：[示例代码索引](./示例代码索引.md)

package/docs/component-development/reference/DOM/346/240/271/350/212/202/347/202/271/346/263/250/345/205/245/346/250/241/345/236/213.md

@@ -0,0 +1,125 @@
+---
+type: reference
+capability: rootpath
+related:
+  - reference/引擎基础能力模型.md
+  - recipes/配置DOM根节点注入.md
+  - reference/Manifest字段参考.md
+  - reference/validateManifest校验规则.md
+---
+# DOM 根节点注入模型
+
+DOM 根节点注入定义宿主把组件基础能力所需的根节点 props 注入到组件 props 的位置。
+
+字段路径：`manifest.engine.render.injection.rootPath`。
+
+`rootPath` 是 SDK 字段名。对组件作者来说，可以把它理解为“组件真实 DOM 根节点在哪里接收宿主注入”。
+
+DOM 根节点注入不是单纯的 DOM 标记配置。它决定宿主赋予组件的基础能力能否与真实 DOM 对齐，尤其影响设计器选中、路径定位和显隐控制。基础能力模型见 [引擎基础能力模型](./引擎基础能力模型.md)。
+
+---
+
+## 宿主需要注入什么
+
+宿主会向组件根节点注入实现基础能力所需的 props 和 ref。组件作者不需要关心宿主内部使用了哪些 DOM 标记，只需要确保这些 props 最终落到真实 DOM 节点上。
+
+---
+
+## 为什么 DOM 根节点注入是必确认项
+
+| 如果注入位置正确 | 如果注入位置不正确 |
+|-------------------|---------------------|
+| 设计器能定位和选中组件根节点 | 选中框可能偏移或找不到目标 DOM |
+| 路径定位能与真实组件区域对齐 | 路径定位不稳定 |
+| 显隐控制能作用于真实组件根节点 | 显隐控制可能只影响 wrapper 或无效节点 |
+| ref 和系统属性能进入正确节点 | 运行时能力可能无法与组件 DOM 对齐 |
+
+因此，正式组件开发时应把 DOM 根节点注入当作交付前必须确认的契约，而不是可选优化。
+
+---
+
+## 支持的模式
+
+| rootPath 字段值 | 说明 | 推荐场景 |
+|----------|------|----------|
+| 不声明 | 宿主外层 `<div>` 兜底 | 黑盒组件、临时接入 |
+| `$root` | 直接合并到组件 props 根层 | props 会透传到根 DOM 的原子组件 |
+| `slotProps.root` | 注入到 `slotProps.root` | 推荐默认方式 |
+| 自定义路径 | 注入到指定 props 路径 | 包装组件或特殊组件 API |
+
+---
+
+## 推荐模式：`slotProps.root`
+
+```tsx
+<div {...slotProps?.root}>...</div>
+```
+
+```ts
+import { INJECT_PATH_SLOT_PROPS } from 'cdp-material-sdk/portable';
+
+engine: {
+  render: {
+    injection: {
+      rootPath: INJECT_PATH_SLOT_PROPS,
+    },
+  },
+},
+```
+
+---
+
+## 自定义路径
+
+自定义路径不是错误，但作者必须负责透传：
+
+```ts
+engine: {
+  render: {
+    injection: {
+      rootPath: 'containerProps.root',
+    },
+  },
+},
+```
+
+```tsx
+<section {...props.containerProps?.root}>...</section>
+```
+
+`validateManifest()` 会提示确认透传是否完成。若已按规则实现，可忽略该 warning。
+
+---
+
+## 选择建议
+
+| 场景 | 建议 |
+|------|------|
+| 新组件 | `slotProps.root` |
+| 包装第三方组件 | wrapper 外层 DOM + `slotProps.root` |
+| 原子 DOM 组件 | `$root` |
+| 黑盒组件 | 不声明 rootPath |
+
+---
+
+## 模型边界
+
+| 边界 | 说明 |
+|------|------|
+| 真实 DOM | 宿主系统属性需要最终落到真实 DOM 节点，不能只停留在不会透传 DOM 属性的 React 组件上 |
+| 宿主兜底 | 不声明 rootPath 时，宿主可以外层 wrapper 兜底，但可能影响 DOM 结构 |
+| 自定义路径 | 合法，但作者必须确认该路径会透传到 DOM |
+| 基础能力 | 基础能力由宿主提供，DOM 根节点注入负责让这些能力与真实 DOM 对齐 |
+
+具体 warning 处理建议见 [validateManifest 校验规则](./validateManifest校验规则.md)。
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[引擎基础能力模型](./引擎基础能力模型.md)
+- 任务 Recipe：[配置DOM根节点注入](../recipes/配置DOM根节点注入.md)
+- 字段参考：[Manifest字段参考](./Manifest字段参考.md)
+- 校验规则：[validateManifest校验规则](./validateManifest校验规则.md)

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

@@ -0,0 +1,170 @@
+---
+type: reference
+capability: events
+related:
+  - recipes/声明事件.md
+  - recipes/使用Adapter适配组件API.md
+  - reference/validateManifest校验规则.md
+  - reference/示例代码索引.md
+---
+# Events 模型
+
+Events 用于描述组件会向宿主发出的通知。事件是可选能力，不需要对外通知时可以不声明。
+
+声明事件时优先使用标准事件；只有标准事件无法表达业务语义或 payload 结构时，才声明自定义事件。
+
+---
+
+## 事件类型
+
+| 类型 | 声明位置 | 说明 |
+|------|----------|------|
+| 标准事件 | `events` | 宿主协议内置事件，例如 `click`、`valueChange` |
+| 自定义事件 | `customEvents` | 组件或业务自定义事件，必须 namespaced |
+| Adapter 事件 | `adapter.events` / `adapter.customEvents` | 将组件实际事件 prop、回调参数和作用域映射到 manifest 事件 |
+
+---
+
+## 标准事件
+
+```ts
+events: {
+  click: { title: '点击' },
+  valueChange: { title: '值变化' },
+}
+```
+
+标准事件类型必须属于 SDK 定义的事件协议。
+
+标准事件表：
+
+| type | 含义 | 标准 payload | 标准 props |
+|------|------|--------------|------------|
+| `mount` | 组件挂载 | 无 | `onMount` |
+| `unmount` | 组件卸载 | 无 | `onUnmount` |
+| `click` | 点击 | 无 | `onClick` |
+| `focus` | 聚焦 | 无 | `onFocus` |
+| `blur` | 失焦 | 无 | `onBlur` |
+| `valueChange` | 主值变化 | `{ newValue: any; oldValue: any }` | `onChange` |
+| `itemClick` | 条目点击 | `{ index: number; item: Record<string, any> }` | `onItemClick` |
+| `itemDoubleClick` | 条目双击 | `{ index: number; item: Record<string, any> }` | `onItemDoubleClick` |
+| `itemRightClick` | 条目右键点击 | `{ index: number; item: Record<string, any> }` | `onItemRightClick` |
+| `itemLongPress` | 条目长按 | `{ index: number; item: Record<string, any> }` | `onItemLongPress` |
+| `dataFetch` | 请求数据 | `{ panelCode: string; condition?: Record<string, any>; keyword?: string; pageNo?: number; pageSize?: number; orderBy?: Array<Record<string, unknown>>; advancedConditions?: Record<string, unknown>; fieldInfo?: { fieldName: string } }` | `onDataFetch` |
+
+这里的标准 props 是组件作者建议暴露的回调 prop 名。第三方组件实际 prop 名不同，或回调参数不符合标准 payload 时，使用 Adapter 映射。
+
+---
+
+## 自定义事件
+
+```ts
+customEvents: {
+  'acme:rowClick': {
+    title: '行点击',
+    payloadSchema: {
+      type: 'object',
+      properties: {
+        rowKey: { type: 'string' },
+      },
+    },
+  },
+}
+```
+
+规则：
+
+- 事件名必须是 namespaced 形态，例如 `acme:rowClick`。
+- 必须声明 `payloadSchema`。
+
+---
+
+## Adapter 映射
+
+Adapter 用于把组件实际 props 和回调参数转换为 CDP 事件协议。它适合第三方组件 prop 名不同，或回调参数需要转换成标准 payload 的场景。完整用法见 [使用 Adapter 适配组件 API](../recipes/使用Adapter适配组件API.md)。
+
+标准事件 prop 名不同：
+
+```ts
+events: {
+  click: { title: '点击' },
+},
+adapter: {
+  events: {
+    click: {
+      propName: 'onPress',
+    },
+  },
+},
+```
+
+标准事件 payload 不同：
+
+```ts
+events: {
+  valueChange: { title: '值变化' },
+},
+adapter: {
+  events: {
+    valueChange: {
+      propName: 'onSelectedValueChange',
+      transform: (nextValue, previousValue) => ({
+        newValue: nextValue,
+        oldValue: previousValue,
+      }),
+    },
+  },
+},
+```
+
+自定义事件映射：
+
+```ts
+customEvents: {
+  'acme:rowAction': {
+    title: '行操作',
+    payloadSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string' },
+        rowKey: { type: 'string' },
+      },
+    },
+  },
+},
+adapter: {
+  customEvents: {
+    'acme:rowAction': {
+      propName: 'onRowAction',
+      transform: (action, record) => ({
+        action,
+        rowKey: record.id,
+      }),
+    },
+  },
+},
+```
+
+Adapter 只能映射已经声明过的事件。具体校验级别见 [validateManifest 校验规则](./validateManifest校验规则.md)。
+
+---
+
+## 事件与 actions 的区别
+
+| 对比 | Events | Actions |
+|------|--------|---------|
+| 方向 | 组件通知宿主 | 宿主调用组件 |
+| 触发者 | 组件内部行为 | 外部流程、指令或 AI |
+| 示例 | 点击、值变化、行选择 | 刷新、清空、聚焦 |
+
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 任务 Recipe：[声明事件](../recipes/声明事件.md)
+- 任务 Recipe：[使用Adapter适配组件API](../recipes/使用Adapter适配组件API.md)
+- 校验规则：[validateManifest校验规则](./validateManifest校验规则.md)
+- 示例索引：[示例代码索引](./示例代码索引.md)

package/docs/component-development/reference/Loading/347/255/226/347/225/245/346/250/241/345/236/213.md

@@ -0,0 +1,140 @@
+---
+type: reference
+capability: loading
+related:
+  - recipes/配置Loading策略.md
+  - reference/Manifest字段参考.md
+  - recipes/声明动作与状态.md
+---
+# Loading 策略模型
+
+Loading 策略定义在 `manifest.engine.render.loading`，用于声明宿主如何控制组件加载态。
+
+---
+
+## 字段定义
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'native' | 'wrapper' | 'none',
+      propName?: string,
+      wrapperType?: 'spin' | 'skeleton' | 'wave' | string,
+      wrapperProps?: Record<string, any>,
+    },
+  },
+},
+```
+
+---
+
+## 策略能力表
+
+| strategy | 注入 props | 自动 actions | Overlay | `setLoading.text` |
+|----------|------------|--------------|---------|-------------------|
+| `native` | 是，默认 `loading` | `getLoading` / `setLoading` | 否 | 否 |
+| `wrapper + spin` | 否 | `getLoading` / `setLoading` | 是 | 是 |
+| `wrapper + wave` | 否 | `getLoading` / `setLoading` | 是 | 是 |
+| `wrapper + skeleton` | 否 | `getLoading` / `setLoading` | 是 | 否 |
+| `none` | 否 | 否 | 否 | 否 |
+
+---
+
+## native
+
+`native` 表示组件自己支持 loading prop。
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'native',
+      propName: 'spinning',
+    },
+  },
+},
+```
+
+规则：
+
+- `propName` 不填时，宿主注入 `loading`。
+- `propName` 填写后，宿主会将 `loading` 映射到该 prop。
+- 组件必须在 loading 为 true 时阻断交互。
+
+---
+
+## wrapper
+
+`wrapper` 表示宿主在组件外部提供遮罩或占位。
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'wrapper',
+      wrapperType: 'wave',
+      wrapperProps: {},
+    },
+  },
+},
+```
+
+内置 wrapper：
+
+| wrapperType | 说明 |
+|-------------|------|
+| `wave` | 默认遮罩 |
+| `spin` | 旋转加载 |
+| `skeleton` | 骨架屏 |
+
+自定义 `wrapperType` 会按组件 type 查找宿主已注册组件。未找到时，开发环境会提示并回退到 `wave`。
+
+---
+
+## none
+
+`none` 表示宿主不接管 loading。
+
+适合：
+
+- Table。
+- TreeTable。
+- AsyncSelect。
+- 内部有复杂请求状态的业务组件。
+
+如需外部控制，请自行声明并实现 `setLoading` / `getLoading` actions。
+
+---
+
+## 与 actions 的关系
+
+当 strategy 为 `native` 或 `wrapper` 时，宿主会自动提供：
+
+- `getLoading`
+- `setLoading`
+
+当 strategy 为 `none` 或不声明 loading 时，宿主不会自动提供这些 actions。
+
+---
+
+## 模型边界
+
+| 边界 | 说明 |
+|------|------|
+| 字段路径 | Loading 策略位于 `engine.render.loading`，不是 `engine.loading` |
+| `native` | 宿主注入 loading prop，组件自身必须阻断交互 |
+| `wrapper` | 宿主在组件外部提供遮罩或占位，不注入 loading prop |
+| `none` | 宿主不接管 loading，也不自动提供 loading actions |
+
+任务选型和自检步骤见 [配置 Loading 策略](../recipes/配置Loading策略.md)。
+
+---
+
+## 任务路径
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 任务 Recipe：[配置Loading策略](../recipes/配置Loading策略.md)
+- 字段参考：[Manifest字段参考](./Manifest字段参考.md)
+- 任务 Recipe：[声明动作与状态](../recipes/声明动作与状态.md)