cdp-material-sdk 0.0.5

package/docs/component-development/recipes//346/216/245/345/205/245/347/254/254/344/270/211/346/226/271React/347/273/204/344/273/266/345/272/223.md

@@ -0,0 +1,209 @@
+---
+type: recipe
+capability: third-party-react
+related:
+  - recipes/使用Adapter适配组件API.md
+  - recipes/配置DOM根节点注入.md
+  - recipes/配置Loading策略.md
+  - reference/SDK导入边界.md
+  - reference/示例代码索引.md
+---
+# 接入第三方 React 组件库
+
+本文说明如何将 Ant Design、Arco、Material UI、ECharts 或自研 UI Kit 中的组件包装成 CDP 组件。
+
+---
+
+## 适用场景
+
+- 你不是从零写 UI，而是包装已有 React 组件。
+- 第三方组件的 props、事件或 loading 名称与 CDP 默认约定不同。
+- 第三方组件没有提供宿主根节点属性注入入口。
+
+---
+
+## 可以跳过的情况
+
+如果你完全控制组件源码，并且组件已经按 CDP 契约接收 `value`、`onChange`、`slotProps.root`，可以直接阅读 [开发最小可运行组件](../getting-started/03-开发最小可运行组件.md)。
+
+---
+
+## 推荐方式：写一层 CDP Wrapper
+
+不要直接把第三方组件裸注册给 CDP。推荐写一个 wrapper：
+
+```tsx
+import { forwardRef } from 'react';
+import { Button } from 'antd';
+import type { BaseUIProps } from 'cdp-material-sdk/portable';
+
+export interface AcmeButtonProps extends BaseUIProps<HTMLDivElement> {
+  text?: string;
+  type?: 'primary' | 'default';
+  loading?: boolean;
+  onClick?: () => void;
+}
+
+export const AcmeButton = forwardRef<HTMLDivElement, AcmeButtonProps>((props, ref) => {
+  const { text = '按钮', type = 'default', loading, onClick, slotProps } = props;
+
+  return (
+    <div {...slotProps?.root} ref={ref}>
+      <Button type={type} loading={loading} onClick={onClick}>
+        {text}
+      </Button>
+    </div>
+  );
+});
+```
+
+这样做的好处：
+
+- CDP 的根节点注入有稳定 DOM 目标。
+- 可以把第三方组件 API 转成 CDP 友好的 props。
+- 后续添加 actions、state、events 更容易。
+- 不需要修改第三方组件源码。
+
+---
+
+## 场景 1：第三方组件 value / onChange 名称不同
+
+例如第三方组件使用：
+
+```tsx
+<ThirdSelect selectedValue={value} onSelectedValueChange={onChange} />
+```
+
+Wrapper 中转换：
+
+```tsx
+export const AcmeSelect = forwardRef<HTMLDivElement, AcmeSelectProps>((props, ref) => {
+  const { value, onChange, slotProps } = props;
+
+  return (
+    <div {...slotProps?.root} ref={ref}>
+      <ThirdSelect
+        selectedValue={value}
+        onSelectedValueChange={onChange}
+      />
+    </div>
+  );
+});
+```
+
+如果只是 props 名称映射，也可以参考 [使用 Adapter 适配组件 API](./使用Adapter适配组件API.md)。
+
+---
+
+## 场景 2：第三方组件没有根 DOM 注入入口
+
+推荐外层包一层 DOM：
+
+```tsx
+return (
+  <div {...slotProps?.root} ref={ref}>
+    <ThirdComponent {...thirdProps} />
+  </div>
+);
+```
+
+对应 manifest：
+
+```ts
+import { INJECT_PATH_SLOT_PROPS } from 'cdp-material-sdk/portable';
+
+engine: {
+  render: {
+    injection: {
+      rootPath: INJECT_PATH_SLOT_PROPS,
+    },
+  },
+},
+```
+
+如果无法包裹或不想改 wrapper，可不声明 `rootPath`，由宿主外层 `<div>` 兜底。但这通常只适合临时接入或黑盒组件。
+
+---
+
+## 场景 3：第三方组件已有 loading 能力
+
+如果第三方组件支持 `loading`：
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'native',
+    },
+  },
+},
+```
+
+如果第三方组件的 loading prop 叫 `spinning`：
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'native',
+      propName: 'spinning',
+    },
+  },
+},
+```
+
+注意：`native` 不只是显示动画，组件在 loading 时必须阻断用户交互。
+
+---
+
+## 场景 4：第三方组件没有 loading 能力
+
+使用 wrapper 策略：
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'wrapper',
+      wrapperType: 'spin',
+    },
+  },
+},
+```
+
+宿主会在组件外部渲染遮罩或占位效果。
+
+---
+
+## 场景 5：第三方组件事件名不同
+
+例如第三方组件暴露 `onRowClick`，你希望它成为 CDP 的点击事件或自定义事件。
+
+可选方案：
+
+1. Wrapper 内转换为 CDP 默认事件 prop。
+2. 使用 `adapter.events` 或 `adapter.customEvents` 映射。
+
+详见 [声明事件](./声明事件.md) 和 [使用 Adapter 适配组件 API](./使用Adapter适配组件API.md)。
+
+---
+
+## 自检
+
+- [ ] Wrapper 根节点透传了 `slotProps.root`。
+- [ ] Manifest 声明了正确的 `engine.render.injection.rootPath`。
+- [ ] 第三方组件的 value、事件、loading 名称已转换或通过 adapter 映射。
+- [ ] `validateManifest()` 无 error。
+- [ ] React 相关依赖没有打入 bundle。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 任务 Recipe：[使用Adapter适配组件API](./使用Adapter适配组件API.md)
+- 任务 Recipe：[配置DOM根节点注入](./配置DOM根节点注入.md)
+- 任务 Recipe：[配置Loading策略](./配置Loading策略.md)
+- SDK 导入边界：[SDK导入边界](../reference/SDK导入边界.md)
+- 示例索引：[示例代码索引](../reference/示例代码索引.md)

package/docs/component-development/recipes//351/205/215/347/275/256DOM/346/240/271/350/212/202/347/202/271/346/263/250/345/205/245.md

@@ -0,0 +1,222 @@
+---
+type: recipe
+capability: rootpath
+related:
+  - reference/引擎基础能力模型.md
+  - reference/DOM根节点注入模型.md
+  - reference/Manifest字段参考.md
+  - reference/validateManifest校验规则.md
+  - recipes/接入第三方React组件库.md
+---
+# 配置 DOM 根节点注入
+
+DOM 根节点注入用于告诉宿主：组件真实 DOM 根节点应该从 props 的哪个位置接收宿主注入。
+
+字段路径：`manifest.engine.render.injection.rootPath`。
+
+`rootPath` 是 SDK 字段名。对正式组件来说，DOM 根节点注入是必须确认的交付点。它影响宿主赋予的基础能力能否准确落到组件真实根节点，尤其是设计器选中、路径定位和显隐控制。
+
+---
+
+## 适用场景
+
+- 组件需要被设计器选中、定位或控制显隐。
+- 组件希望宿主把基础能力所需的 props 和 ref 注入到真实 DOM 根节点。
+- 组件包装了第三方组件，需要决定注入到 wrapper 还是内部根节点。
+- 组件需要可靠响应宿主基础显隐能力，例如 `setHidden` 和 `toggleHidden`。
+
+---
+
+## 可以跳过的情况
+
+如果组件是完全黑盒组件，或只是临时接入，可以不声明 `rootPath`。宿主会在外层套 `<div>` 兜底。
+
+但正式组件建议显式声明并透传根节点属性。
+
+---
+
+## 引擎基础能力与 DOM 根节点
+
+宿主会为所有组件补充基础能力，包括：
+
+| 能力 | 说明 | 组件作者要确认什么 |
+|------|------|-------------------|
+| `hidden` prop | 当前组件是否隐藏 | 不要把它误覆盖成其他语义 |
+| `getHidden` / `setHidden` / `toggleHidden` | 获取、设置、切换显隐状态 | 不要在 manifest 中重复声明同名 action |
+| `hidden` state | 暴露当前显隐状态 | 不要在 manifest 中重复声明同名 state |
+| `mount` / `unmount` events | 基础生命周期事件 | 不需要为普通组件重复声明 |
+
+组件作者不需要关心宿主内部如何实现这些能力，只需要确认 DOM 根节点注入位置正确。若 `rootPath` 没有指向真实根节点，显隐、选中框和调试定位都可能偏移。
+
+完整模型见 [引擎基础能力模型](../reference/引擎基础能力模型.md)。
+
+---
+
+## 推荐方式：slotProps.root
+
+组件：
+
+```tsx
+import { forwardRef } from 'react';
+import type { BaseUIProps } from 'cdp-material-sdk/portable';
+
+export const MyCard = forwardRef<HTMLDivElement, BaseUIProps<HTMLDivElement>>((props, ref) => {
+  const { slotProps } = props;
+
+  return (
+    <div {...slotProps?.root} ref={ref}>
+      内容
+    </div>
+  );
+});
+```
+
+Manifest：
+
+```ts
+import { INJECT_PATH_SLOT_PROPS } from 'cdp-material-sdk/portable';
+
+engine: {
+  render: {
+    injection: {
+      rootPath: INJECT_PATH_SLOT_PROPS,
+    },
+  },
+},
+```
+
+确认点：
+
+- `slotProps.root` 必须展开到真实 DOM 节点。
+- `ref` 应落到同一个根 DOM，避免系统属性和 ref 分离。
+- 不要只把 `slotProps.root` 传给不会透传 DOM 属性的第三方 React 组件。
+
+---
+
+## 直接注入根 props
+
+如果组件本身的 props 会直接透传到根 DOM，可以使用 `$root`：
+
+```ts
+engine: {
+  render: {
+    injection: {
+      rootPath: '$root',
+    },
+  },
+},
+```
+
+适合简单原子组件，但要确认组件不会把系统属性传给错误的内部节点。
+
+确认点：
+
+- 组件根 props 必须最终透传到真实 DOM。
+- 如果组件内部还有 wrapper 或第三方组件，优先改用 `slotProps.root`。
+
+---
+
+## 自定义 rootPath
+
+如果组件的根 DOM 注入入口在自定义路径上，也可以声明：
+
+```ts
+engine: {
+  render: {
+    injection: {
+      rootPath: 'containerProps.root',
+    },
+  },
+},
+```
+
+组件必须确保该路径最终透传到真实 DOM：
+
+```tsx
+const { containerProps } = props;
+
+return <section {...containerProps?.root}>内容</section>;
+```
+
+自定义路径是合法选择。`validateManifest()` 可能会给出提示，提醒作者确认透传是否完成；如果已经按规则实现，可以忽略该提示。
+
+---
+
+## 不声明 DOM 根节点注入
+
+不声明时，宿主会外层包裹 `<div>` 兜底。
+
+适合：
+
+- 黑盒第三方组件。
+- 临时验证组件。
+- 作者无法控制组件根节点。
+
+不适合：
+
+- 长期维护的正式组件。
+- 对 DOM 结构、布局、选择态有严格要求的组件。
+- 需要精确显隐控制的组件。
+
+---
+
+## 选择表
+
+| 场景 | 推荐 |
+|------|------|
+| 组件可改源码 | `INJECT_PATH_SLOT_PROPS` |
+| props 会直接透传到根 DOM | `$root` |
+| 第三方组件外层 wrapper | `INJECT_PATH_SLOT_PROPS` |
+| 注入入口是自定义路径 | 自定义 `rootPath` |
+| 完全黑盒组件 | 不声明，使用宿主兜底 |
+
+如果不确定，正式组件优先选择 `INJECT_PATH_SLOT_PROPS`，并在组件根 DOM 展开 `slotProps.root`。
+
+---
+
+## 验收步骤
+
+1. 在 manifest 中声明 `engine.render.injection.rootPath`。
+2. 在组件实现中把对应 props 展开到真实根 DOM。
+3. 在宿主中选中该组件，确认选中框与真实视觉区域一致。
+4. 触发显隐控制，确认目标组件的显示/隐藏效果符合预期。
+5. 如果使用自定义路径，确认路径上的 props 没有被中间组件吞掉。
+
+---
+
+## 自检
+
+- [ ] rootPath 指向的 props 最终透传到了真实 DOM。
+- [ ] 设计器选中框、路径定位和真实 DOM 区域一致。
+- [ ] `setHidden` / `toggleHidden` 后，目标组件的显示/隐藏效果符合预期。
+- [ ] 没有在 manifest 中重复声明宿主基础 `hidden` action / state。
+- [ ] 不需要 rootPath 时，确认接受宿主外层 `<div>` 兜底。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### 声明了 `INJECT_PATH_SLOT_PROPS`，但组件没有透传 `slotProps.root`
+
+设计器可能无法选中组件，或显隐控制不符合预期。
+
+### rootPath 只落到了第三方 React 组件
+
+如果第三方组件不透传未知 DOM 属性，宿主注入无法到达真实 DOM。请在外层加 wrapper DOM，并把 `slotProps.root` 展开到 wrapper 上。
+
+### 自定义 rootPath 指向了非 DOM 组件
+
+系统属性必须最终落到真实 DOM 节点。不要只传给不会透传 DOM 属性的第三方组件。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[DOM根节点注入模型](../reference/DOM根节点注入模型.md)
+- 模型参考：[引擎基础能力模型](../reference/引擎基础能力模型.md)
+- 字段参考：[Manifest字段参考](../reference/Manifest字段参考.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 任务 Recipe：[接入第三方React组件库](./接入第三方React组件库.md)

package/docs/component-development/recipes//351/205/215/347/275/256Loading/347/255/226/347/225/245.md

@@ -0,0 +1,198 @@
+---
+type: recipe
+capability: loading
+related:
+  - reference/Loading策略模型.md
+  - reference/Manifest字段参考.md
+  - reference/validateManifest校验规则.md
+  - recipes/声明动作与状态.md
+---
+# 配置 Loading 策略
+
+Loading 策略用于声明宿主如何控制组件加载态。
+
+字段路径：`manifest.engine.render.loading`。
+
+---
+
+## 适用场景
+
+- 组件需要响应外部流程的 `setLoading`。
+- 组件已有 loading prop，需要让宿主接管。
+- 组件没有 loading 能力，希望宿主用遮罩兜底。
+
+---
+
+## 可以跳过的情况
+
+- 组件不需要被外部流程控制 Loading。
+- 组件内部有复杂异步状态，并且不希望宿主接管。
+- 组件只是静态展示。
+
+不声明时等价于不启用 Loading Feature。
+
+---
+
+## 策略总览
+
+| 策略 | 适合场景 | 宿主行为 |
+|------|----------|----------|
+| `native` | 组件已有 loading prop | 注入 `loading` 或 `propName` 指定的 prop |
+| `wrapper` | 组件没有 loading prop，但可以整体遮罩 | 渲染外层遮罩或占位 |
+| `none` | 组件内部自控 loading | 宿主不接管 |
+
+---
+
+## native
+
+适合 Button、Select、Upload 等已有 loading prop 的组件。
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'native',
+    },
+  },
+},
+```
+
+如果 prop 名不是 `loading`：
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'native',
+      propName: 'spinning',
+    },
+  },
+},
+```
+
+作者职责：
+
+- 组件必须接收对应 loading prop。
+- loading 为 true 时，组件必须阻断用户交互。
+- 不要只显示动画但仍允许点击或输入。
+
+---
+
+## wrapper
+
+适合 Card、Chart、PreviewPanel 等没有 loading prop 的展示组件。
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'wrapper',
+      wrapperType: 'spin',
+      wrapperProps: {
+        size: 'large',
+      },
+    },
+  },
+},
+```
+
+当前内置 `wrapperType`：
+
+| wrapperType | 说明 |
+|-------------|------|
+| `wave` | 默认通用遮罩 |
+| `spin` | 常规加载中 |
+| `skeleton` | 骨架屏占位 |
+| 自定义组件 type | 宿主注册过对应 wrapper 组件时使用 |
+
+`spin` 和 `wave` 可使用 `setLoading({ loading: true, text })` 的 `text` 参数。`skeleton` 不使用提示文字。
+
+---
+
+## none
+
+适合 Table、TreeTable、AsyncSelect、复杂业务面板等内部 loading 状态复杂的组件。
+
+```ts
+engine: {
+  render: {
+    loading: {
+      strategy: 'none',
+    },
+  },
+},
+```
+
+如果仍希望外部流程能控制组件 loading，请自己声明并实现 actions：
+
+```ts
+actions: {
+  setLoading: {
+    title: '设置加载状态',
+    params: {
+      type: 'object',
+      required: ['loading'],
+      properties: {
+        loading: { type: 'boolean', title: '是否加载中' },
+      },
+    },
+    returns: { type: 'boolean' },
+  },
+  getLoading: {
+    title: '获取加载状态',
+    returns: { type: 'boolean' },
+  },
+},
+```
+
+---
+
+## 选择表
+
+| 组件情况 | 推荐策略 |
+|----------|----------|
+| 已有 `loading` prop，且能禁用交互 | `native` |
+| loading prop 名不是 `loading` | `native + propName` |
+| 没有 loading prop，但可以整体遮罩 | `wrapper` |
+| 适合骨架屏 | `wrapper + skeleton` |
+| 内部有复杂异步状态 | `none` |
+| 复杂组件仍需外部控制 loading | `none + 自定义 actions` |
+| 不确定 | 优先 `wrapper` |
+
+---
+
+## 自检
+
+- [ ] 字段路径写成 `engine.render.loading`。
+- [ ] `native` 模式下组件能接收 loading prop，并阻断交互。
+- [ ] `propName` 与组件实际 prop 名一致。
+- [ ] `wrapper` 模式下组件可以被整体遮罩。
+- [ ] `none` 模式下没有误以为宿主会自动注入 loading。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### 把 `loading` 写成 `manifest.engine.loading`
+
+正确路径是 `manifest.engine.render.loading`。
+
+### native 模式只显示动画，不阻断交互
+
+这是组件实现问题。`native` 要求组件在 loading 时不可继续触发用户操作。
+
+### Table 使用 wrapper 后局部 loading 体验不符合预期
+
+复杂数据组件通常应使用 `none`，由组件内部管理 loading。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[Loading策略模型](../reference/Loading策略模型.md)
+- 字段参考：[Manifest字段参考](../reference/Manifest字段参考.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 任务 Recipe：[声明动作与状态](./声明动作与状态.md)