cdp-material-sdk 0.0.5

package/docs/component-development/recipes//345/243/260/346/230/216/346/217/222/346/247/275.md

@@ -0,0 +1,141 @@
+---
+type: recipe
+capability: slots
+related:
+  - reference/Slots模型.md
+  - reference/validateManifest校验规则.md
+  - reference/示例代码索引.md
+---
+# 声明插槽
+
+插槽用于让组件提供可被设计器填充的区域，例如卡片内容区、表格列模板、列表项模板等。
+
+---
+
+## 适用场景
+
+- 组件需要承载子组件。
+- 组件有固定区域允许业务方拖入内容。
+- 组件需要按数据行渲染模板。
+
+---
+
+## 可以跳过的情况
+
+- 组件不承载子组件。
+- 组件只通过 props 配置内容。
+- 组件只是一个单一输入或展示控件。
+
+---
+
+## 命名插槽
+
+最常见，也最推荐第三方作者优先使用。
+
+```ts
+slots: {
+  header: {
+    title: '头部',
+    description: '卡片头部内容',
+  },
+  body: {
+    title: '内容',
+    description: '卡片主体内容',
+  },
+}
+```
+
+组件通过宿主注入的 `_slots` 消费：
+
+```tsx
+export function Card(props: any) {
+  const { _slots } = props;
+
+  return (
+    <section>
+      <header>{_slots?.header}</header>
+      <main>{_slots?.body}</main>
+    </section>
+  );
+}
+```
+
+---
+
+## 作用域插槽
+
+适合表格行、列表项这类需要向子内容提供上下文的场景。
+
+```ts
+slots: {
+  rowActions: {
+    title: '行操作',
+    scoped: true,
+    scopeDescription: '提供当前行 record 和 rowIndex',
+  },
+}
+```
+
+`scopeDescription` 不是强制字段，但建议声明，方便设计器和 AI 理解上下文。
+
+---
+
+## 动态插槽
+
+适合根据 props 数组生成多个插槽，例如表格列模板。
+
+```ts
+slots: {
+  columnSlot: {
+    title: '列模板',
+    dynamic: true,
+    dynamicSource: 'columns',
+    dynamicKey: 'col:{dataIndex}',
+    dynamicTitle: '列：{title}',
+    scoped: true,
+    scopeDescription: '提供当前行 record',
+  },
+}
+```
+
+动态插槽必须声明：
+
+- `dynamicSource`
+- `dynamicKey`
+
+---
+
+## 自检
+
+- [ ] 每个 slot 都有 `title`。
+- [ ] 动态 slot 声明了 `dynamicSource` 和 `dynamicKey`。
+- [ ] 作用域 slot 建议声明 `scopeDescription`。
+- [ ] `allowedChildren` 如果声明，必须是字符串数组。
+- [ ] 组件实际渲染了 `_slots` 或 `_scopedSlots`。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### 声明了 slot，但组件没有渲染
+
+设计器会显示插槽，但运行时不会看到内容。请确认组件消费了对应 `_slots[name]`。
+
+### 动态 slot 缺少 dynamicKey
+
+宿主无法生成稳定 slot 名称，`validateManifest()` 会报错。
+
+### 普通容器只声明 LAYOUT_CONTAINER，不声明 slots
+
+如果组件有明确可填充区域，建议声明 slots。`LAYOUT_CONTAINER` 只说明组件具备布局容器能力，slots 才说明具体区域。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[Slots模型](../reference/Slots模型.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 示例索引：[示例代码索引](../reference/示例代码索引.md)

package/docs/component-development/recipes//345/243/260/346/230/216/346/225/260/346/215/256/345/255/227/346/256/265/347/273/204/344/273/266.md

@@ -0,0 +1,147 @@
+---
+type: recipe
+capability: data-field
+related:
+  - reference/Traits能力模型.md
+  - reference/Manifest字段参考.md
+  - reference/validateManifest校验规则.md
+  - recipes/使用Adapter适配组件API.md
+---
+# 声明数据字段组件
+
+数据字段组件用于接入 CDP 的值管理，例如输入框、选择器、开关、日期选择器等。
+
+---
+
+## 适用场景
+
+- 组件有一个主要业务值。
+- 组件需要接收 `value` 并通过 `onChange` 回传新值。
+- 组件需要被表单、表达式或 AI 工具识别为数据字段。
+
+---
+
+## 可以跳过的情况
+
+- 组件只是展示内容，不参与数据写入。
+- 组件的值完全由内部管理，不需要暴露给 CDP。
+- 组件是容器，管理的是子字段数据，此时应阅读 [声明数据容器组件](./声明数据容器组件.md)。
+
+---
+
+## 作者职责
+
+1. 在 `traits` 中声明 `COMPONENT_TRAIT.DATA_FIELD`。
+2. 在 `meta.valueSchema` 中描述 value 类型。
+3. 组件接收 `value`。
+4. 值变化时调用 `onChange(nextValue)`。
+5. 如果组件在容器内使用，建议支持 `name` prop。
+
+---
+
+## 示例
+
+```tsx
+import { forwardRef } from 'react';
+import type { BaseUIProps } from 'cdp-material-sdk/portable';
+
+export interface AcmeInputProps extends BaseUIProps<HTMLInputElement> {
+  value?: string;
+  onChange?: (value: string) => void;
+}
+
+export const AcmeInput = forwardRef<HTMLInputElement, AcmeInputProps>((props, ref) => {
+  const { value = '', onChange, slotProps } = props;
+
+  return (
+    <input
+      {...slotProps?.root}
+      ref={ref}
+      value={value}
+      onChange={(event) => onChange?.(event.target.value)}
+    />
+  );
+});
+```
+
+Manifest：
+
+```ts
+import {
+  COMPONENT_CATEGORY,
+  COMPONENT_TRAIT,
+  INJECT_PATH_SLOT_PROPS,
+  type ComponentManifest,
+} from 'cdp-material-sdk/portable';
+
+export const acmeInputManifest = {
+  type: 'acme.Input',
+  traits: [COMPONENT_TRAIT.DATA_FIELD],
+  meta: {
+    title: '输入框',
+    category: COMPONENT_CATEGORY.DATA_ENTRY,
+    valueSchema: { type: 'string', default: '' },
+  },
+  engine: {
+    render: {
+      injection: {
+        rootPath: INJECT_PATH_SLOT_PROPS,
+      },
+    },
+  },
+  props: {
+    type: 'object',
+    properties: {
+      placeholder: { type: 'string', title: '占位提示' },
+    },
+  },
+  events: {
+    valueChange: { title: '值变化' },
+  },
+} satisfies ComponentManifest;
+```
+
+---
+
+## 声明后会得到什么
+
+| 能力 | 说明 |
+|------|------|
+| 值注入 | 宿主向组件注入当前 `value` |
+| 值回写 | 组件调用 `onChange` 后，宿主更新值 |
+| 类型识别 | 设计器、表达式和 AI 工具可读取 `meta.valueSchema` |
+| 容器协同 | 在数据容器内，字段可按 `name` 写入容器 value |
+| 自动状态补充 | 宿主可基于数据能力补充标准 value 状态 |
+
+---
+
+## 自检
+
+- [ ] `traits` 包含 `COMPONENT_TRAIT.DATA_FIELD`。
+- [ ] `meta.valueSchema` 描述了 value 类型。
+- [ ] 组件接收 `value`。
+- [ ] 值变化时调用 `onChange(nextValue)`。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### 只声明 trait，但没有 `valueSchema`
+
+这会影响设计器和 AI 工具推断数据类型。`validateManifest()` 会给出 warning。
+
+### 使用第三方组件但没有转换 value/onChange
+
+如果第三方组件使用 `selectedValue`、`onSelectedValueChange` 等命名，需要在 wrapper 内转换，或阅读 [使用 Adapter 适配组件 API](./使用Adapter适配组件API.md)。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[Traits能力模型](../reference/Traits能力模型.md)
+- 字段参考：[Manifest字段参考](../reference/Manifest字段参考.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 任务 Recipe：[使用Adapter适配组件API](./使用Adapter适配组件API.md)

package/docs/component-development/recipes//345/243/260/346/230/216/346/225/260/346/215/256/345/256/271/345/231/250/347/273/204/344/273/266.md

@@ -0,0 +1,258 @@
+---
+type: recipe
+capability: data-container
+related:
+  - reference/Traits能力模型.md
+  - reference/Manifest字段参考.md
+  - reference/validateManifest校验规则.md
+  - recipes/声明插槽.md
+---
+# 声明数据容器组件
+
+数据容器组件用于管理一组子字段的数据作用域，例如 Form、Table、List、CardList 等。
+
+---
+
+## 适用场景
+
+- 组件内部会渲染子字段。
+- 子字段的值应该写入容器的 value 中。
+- 容器需要读取、设置或重置自己的数据。
+
+---
+
+## 可以跳过的情况
+
+- 组件只是布局容器，不管理数据，应该使用 `LAYOUT_CONTAINER`。
+- 组件只是单个输入字段，应该使用 `DATA_FIELD`。
+- 组件只展示数据，不承载子字段写入。
+
+---
+
+## 作者职责
+
+1. 声明 `COMPONENT_TRAIT.DATA_CONTAINER`。
+2. 在 `meta.valueSchema` 中描述容器 value 结构。
+3. 在子组件渲染区域用 `DataScope` 建立数据作用域，由它负责字段路径解析与记录注入。
+4. 如需读写容器数据，使用 `cdp-material-sdk/host-react` 中的 `useDataContainer` / `useDataContainerApi`。
+
+`DataScope` 由 SDK 统一提供，作者不需要传 `componentId`，引擎会自动完成运行时上下文装配。
+
+---
+
+## Manifest 示例
+
+```ts
+import {
+  COMPONENT_CATEGORY,
+  COMPONENT_TRAIT,
+  INJECT_PATH_SLOT_PROPS,
+  type ComponentManifest,
+} from 'cdp-material-sdk/portable';
+
+export const acmeFormManifest = {
+  type: 'acme.Form',
+  traits: [COMPONENT_TRAIT.DATA_CONTAINER, COMPONENT_TRAIT.LAYOUT_CONTAINER],
+  meta: {
+    title: '表单',
+    category: COMPONENT_CATEGORY.DATA_ENTRY,
+    valueSchema: {
+      type: 'object',
+      default: {},
+    },
+  },
+  engine: {
+    render: {
+      injection: {
+        rootPath: INJECT_PATH_SLOT_PROPS,
+      },
+    },
+  },
+  slots: {
+    default: {
+      title: '表单内容',
+      description: '放置表单字段',
+    },
+  },
+} satisfies ComponentManifest;
+```
+
+---
+
+## 提供数据作用域
+
+数据容器组件在子组件渲染区域包一层 `DataScope`，使内部字段组件能解析字段路径、读取当前记录、注册字段状态。
+
+### DataScope 入参
+
+| 入参 | 何时传 | 说明 |
+|------|--------|------|
+| `getRecord` | 对象型容器（Form） | 记录获取函数。各字段实时读取最新容器数据，避免 record 变化触发后代重渲染。 |
+| `record` | 数组型容器（Table、CardList 每行） | 当前作用域的记录实例。与 `getRecord` 二选一。 |
+| `relativePath` | 数组型容器 | 决定子字段在容器 value 内的访问位置，例如 `(childId) => `[${index}].${childId}``。默认为 `(childId) => childId`。 |
+| `index` | 数组型容器 | 当前作用域索引，供子组件读取。 |
+| `registerField` / `unregisterField` | 需要聚合字段状态的容器（Form） | 让子字段上报 `hidden` / `readOnly` / `required` / `label` 等状态。不需要可省略。 |
+
+### 示例：Form 这类对象型容器
+
+```tsx
+import { useCallback } from 'react';
+import { DataScope, useDataContainerApi } from 'cdp-material-sdk/host-react';
+import { useFieldRegistry } from './useFieldRegistry';
+
+export function AcmeForm({ children }) {
+  const { getContainerData } = useDataContainerApi<Record<string, unknown>>();
+
+  // 实时获取最新表单数据，依赖项只有 getContainerData，引用稳定
+  const getCurrentFormData = useCallback(
+    () => getContainerData() ?? {},
+    [getContainerData],
+  );
+
+  // useFieldRegistry 内部用 ref 维护字段表，register/unregister 引用稳定
+  const { registerField, unregisterField } = useFieldRegistry();
+
+  return (
+    <DataScope
+      getRecord={getCurrentFormData}
+      registerField={registerField}
+      unregisterField={unregisterField}
+    >
+      {children}
+    </DataScope>
+  );
+}
+```
+
+要点：
+
+- `getRecord` 推荐用 `useCallback` 包，避免每次 render 给 `DataScope` 传新函数引用。
+- `registerField` / `unregisterField` 需保证引用稳定，避免子字段重复注册。
+- 不需要也不要传 `componentId`。
+
+### 示例：Table 这类数组型容器
+
+```tsx
+import { DataScope } from 'cdp-material-sdk/host-react';
+
+export function TableRows({ rows, renderCells }) {
+  return rows.map((row, index) => (
+    <DataScope
+      key={getRowKey(row)}
+      relativePath={(childId) => `[${index}].${childId}`}
+      record={row}
+      index={index}
+    >
+      {renderCells(row, index)}
+    </DataScope>
+  ));
+}
+```
+
+要点：
+
+- 每行一个 `DataScope`，`record` 直接传本行数据。
+- `relativePath` 用于拼接表格下标 + 子字段，让子组件拿到容器 value 内的绝对路径。
+- 数组型容器通常不需要 `registerField`；每行是独立作用域。
+
+---
+
+## 读取和设置容器数据
+
+只有在确认组件包与宿主共享 React runtime 和 Context 身份时，才使用 `host-react`。SDK 提供两个 hook：
+
+| Hook | 返回值 | 是否订阅容器数据变化 | 典型场景 |
+|------|--------|----------------------|----------|
+| `useDataContainerApi` | `{ getContainerData, setContainerData, resetContainerData }` | 否 | 事件回调、`useImperativeHandle` 暴露的动作、`useCallback` 内部按需取值；容器自身不依赖数据触发重渲染 |
+| `useDataContainer` | 在 `useDataContainerApi` 基础上额外返回 `containerData` | 是 | 需要随容器值变化重渲染的展示场景，例如调试预览、汇总统计 |
+
+经验法则：
+
+- 默认用 `useDataContainerApi`。命令式 API 引用稳定，可放进 `useCallback` 依赖列表，避免不必要的重渲染。
+- 只有当组件 UI 必须随容器值变化而刷新时，才用 `useDataContainer`，因为它会让组件订阅整个容器值。
+- 子字段读取自身值不要走这两个 hook，应通过 `DataScope` 解析的字段路径，由字段层 hook 处理。
+
+### 示例：命令式读取（推荐默认）
+
+```tsx
+import { useCallback } from 'react';
+import { useDataContainerApi } from 'cdp-material-sdk/host-react';
+
+export function AcmeFormSubmit() {
+  const { getContainerData, setContainerData } = useDataContainerApi<Record<string, unknown>>();
+
+  const handleSubmit = useCallback(() => {
+    const formData = getContainerData() ?? {};
+    submitToServer(formData);
+  }, [getContainerData]);
+
+  return <button onClick={handleSubmit}>提交</button>;
+}
+```
+
+### 示例：响应式订阅（仅在需要时用）
+
+```tsx
+import { useDataContainer } from 'cdp-material-sdk/host-react';
+
+export function FormPreview() {
+  const { containerData } = useDataContainer<Record<string, unknown>>();
+  return <pre>{JSON.stringify(containerData, null, 2)}</pre>;
+}
+```
+
+如果无法确认共享 runtime，请不要依赖 `host-react`，改为通过 props、events 或 actions 与宿主交互。
+
+---
+
+## valueSchema 选择
+
+| 容器类型 | 推荐 valueSchema |
+|----------|------------------|
+| Form | `{ type: 'object', default: {} }` |
+| Table | `{ type: 'array', default: [], items: { type: 'object' } }` |
+| CardList | `{ type: 'array', default: [], items: { type: 'object' } }` |
+| KeyValueMap | `{ type: 'object', additionalProperties: true }` |
+
+---
+
+## 自检
+
+- [ ] `traits` 包含 `COMPONENT_TRAIT.DATA_CONTAINER`。
+- [ ] `meta.valueSchema` 描述容器数据结构。
+- [ ] 在子组件渲染区域用 `DataScope` 建立了数据作用域，未传 `componentId`。
+- [ ] `getRecord` / `registerField` / `unregisterField` 引用稳定（`useCallback` 或 ref 包装）。
+- [ ] 如果允许拖入子组件，声明了 `LAYOUT_CONTAINER` 或 slots。
+- [ ] 如果使用 `host-react`，已确认与宿主共享 React runtime。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### 把普通布局容器声明成 DATA_CONTAINER
+
+如果组件只是 Card、Grid、Tabs 这类布局组件，不管理子字段数据，不应声明 `DATA_CONTAINER`。
+
+### 声明了 DATA_CONTAINER 但没有 valueSchema
+
+这会影响设计器、表达式和 AI 工具理解容器数据结构。`validateManifest()` 会给出 warning。
+
+### 声明了 DATA_CONTAINER 但没有提供 DataScope
+
+子字段无法解析容器内的字段路径，表达式、AI 工具和字段状态注册都会失效。请在子组件渲染区域包一层 `DataScope`。
+
+### 给 DataScope 传 inline 函数
+
+在 `DataScope` 上直接写 `getRecord={() => ...}` 或 `registerField={(field) => ...}` 会导致每次父组件 render 都生成新引用，子字段可能重复订阅/重复注册。请使用 `useCallback` 或稳定引用。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[Traits能力模型](../reference/Traits能力模型.md)
+- 字段参考：[Manifest字段参考](../reference/Manifest字段参考.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 任务 Recipe：[声明插槽](./声明插槽.md)