cdp-material-sdk 0.0.5

package/docs/component-development/recipes//345/243/260/346/230/216/344/272/213/344/273/266.md

@@ -0,0 +1,229 @@
+---
+type: recipe
+capability: events
+related:
+  - reference/Events模型.md
+  - reference/validateManifest校验规则.md
+  - reference/示例代码索引.md
+---
+# 声明事件
+
+事件用于让组件向 CDP 宿主发出通知，例如值变化、点击、聚焦、行点击或业务自定义事件。
+
+---
+
+## 适用场景
+
+- 组件需要触发页面编排、指令或 AI 流程。
+- 组件内部发生某个业务动作，需要通知宿主。
+- 第三方组件事件名与 CDP 默认事件名不同，需要映射。
+
+---
+
+## 可以跳过的情况
+
+- 组件没有需要对外通知的行为。
+- 组件只是静态展示。
+- 组件只需要被外部调用方法，应使用 actions，而不是 events。
+
+---
+
+## 标准事件
+
+优先检查需求是否能落到标准事件。标准事件能覆盖时，不要额外声明自定义事件。
+
+常用标准事件：
+
+| type | 适合场景 | 标准 payload | 推荐 props |
+|------|----------|--------------|------------|
+| `click` | 按钮、链接、卡片点击 | 无 | `onClick` |
+| `focus` | 输入、选择器聚焦 | 无 | `onFocus` |
+| `blur` | 输入、选择器失焦 | 无 | `onBlur` |
+| `valueChange` | 输入值、选择值变化 | `{ newValue; oldValue }` | `onChange` |
+| `itemClick` | 表格行、列表项点击 | `{ index; item }` | `onItemClick` |
+| `itemDoubleClick` | 表格行、列表项双击 | `{ index; item }` | `onItemDoubleClick` |
+| `itemRightClick` | 表格行、列表项右键点击 | `{ index; item }` | `onItemRightClick` |
+| `itemLongPress` | 移动端列表项长按 | `{ index; item }` | `onItemLongPress` |
+| `dataFetch` | 组件请求外部数据 | 数据请求参数对象 | `onDataFetch` |
+
+完整标准事件协议见 [Events 模型](../reference/Events模型.md)。
+
+标准事件写在 `manifest.events` 中：
+
+```ts
+events: {
+  valueChange: { title: '值变化' },
+  click: { title: '点击' },
+  focus: { title: '聚焦' },
+  blur: { title: '失焦' },
+}
+```
+
+组件实现通常通过对应 props 触发：
+
+```tsx
+<button onClick={onClick}>提交</button>
+```
+
+数据字段组件通常通过 `onChange(nextValue)` 触发值变化。
+
+---
+
+## props 与 payload 转换
+
+如果组件已经使用推荐 props，并且回调参数符合标准 payload，可以直接声明标准事件。
+
+```tsx
+export function AcmeButton({ onClick }: { onClick?: () => void }) {
+  return <button onClick={onClick}>提交</button>;
+}
+```
+
+如果第三方组件 prop 名不同，但语义仍是标准事件，使用 `adapter.events` 映射 prop：
+
+```ts
+events: {
+  click: { title: '点击' },
+},
+adapter: {
+  events: {
+    click: {
+      propName: 'onPress',
+    },
+  },
+},
+```
+
+如果第三方组件回调参数不同，使用 `transform` 转换为标准 payload：
+
+```ts
+events: {
+  valueChange: { title: '值变化' },
+},
+adapter: {
+  events: {
+    valueChange: {
+      propName: 'onSelectedValueChange',
+      transform: (nextValue, previousValue) => ({
+        newValue: nextValue,
+        oldValue: previousValue,
+      }),
+    },
+  },
+},
+```
+
+如果回调来自列表、表格等作用域场景，可以同时用 `toScope` 提供当前行上下文：
+
+```ts
+events: {
+  itemClick: { title: '行点击' },
+},
+adapter: {
+  events: {
+    itemClick: {
+      propName: 'onRowClick',
+      transform: (record, index) => ({
+        item: record,
+        index,
+      }),
+      toScope: (record, index) => ({
+        record,
+        index,
+      }),
+    },
+  },
+},
+```
+
+更完整的 Adapter 用法见 [使用 Adapter 适配组件 API](./使用Adapter适配组件API.md)。
+
+---
+
+## 自定义事件
+
+只有标准事件无法表达业务语义或 payload 结构时，才声明自定义事件。
+
+自定义事件需要 namespaced 命名，并声明 `payloadSchema`：
+
+```ts
+customEvents: {
+  'acme:rowAction': {
+    title: '行点击',
+    payloadSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string' },
+        rowKey: { type: 'string' },
+        record: { type: 'object' },
+      },
+    },
+  },
+}
+```
+
+命名建议：
+
+| 类型 | 示例 |
+|------|------|
+| 组织前缀 | `acme:rowAction` |
+| 组件前缀 | `table:rowAction` |
+| 业务前缀 | `order:approved` |
+
+---
+
+## 第三方组件事件名不同
+
+如果第三方组件使用 `onRowAction`，可以用 adapter 映射：
+
+```ts
+adapter: {
+  customEvents: {
+    'acme:rowAction': {
+      propName: 'onRowAction',
+      transform: (action, record) => ({
+        action,
+        rowKey: record.id,
+        record,
+      }),
+    },
+  },
+},
+```
+
+注意：adapter 中引用的标准事件必须先在 `events` 声明；自定义事件必须先在 `customEvents` 声明。
+
+---
+
+## 自检
+
+- [ ] 不需要事件的组件没有强行声明事件。
+- [ ] 已优先检查是否能使用标准事件。
+- [ ] 标准事件写在 `events`。
+- [ ] 第三方组件 prop 名不同或 payload 不同时，已使用 `adapter.events` / `adapter.customEvents` 映射。
+- [ ] 自定义事件写在 `customEvents`，并声明 `payloadSchema`。
+- [ ] 自定义事件名是 namespaced 形态，例如 `acme:rowAction`。
+- [ ] adapter 事件引用了已经声明的事件。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### adapter 中声明了事件，但 manifest 没有声明
+
+`validateManifest()` 会报错。先在 `events` 或 `customEvents` 中声明，再在 adapter 中映射。
+
+### 自定义事件没有 payloadSchema
+
+自定义事件必须声明 payload 结构，方便设计器和 AI 工具理解事件数据。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[Events模型](../reference/Events模型.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 示例索引：[示例代码索引](../reference/示例代码索引.md)

package/docs/component-development/recipes//345/243/260/346/230/216/345/212/250/344/275/234/344/270/216/347/212/266/346/200/201.md

@@ -0,0 +1,188 @@
+---
+type: recipe
+capability: actions-state
+related:
+  - reference/ActionsState模型.md
+  - reference/validateManifest校验规则.md
+  - reference/示例代码索引.md
+---
+# 声明动作与状态
+
+动作（Actions）用于让外部流程命令式调用组件；状态（State）用于让外部表达式只读访问组件内部运行时数据。
+
+---
+
+## 适用场景
+
+- 外部流程需要调用组件方法，例如刷新、清空、展开、聚焦。
+- 外部表达式需要读取组件内部状态，例如选中行、搜索条件、高亮状态。
+- AI 或编排系统需要知道组件支持哪些命令。
+
+---
+
+## 可以跳过的情况
+
+- 组件只是根据 props 渲染，不需要暴露命令式方法。
+- 组件内部状态不需要被外部表达式读取。
+- 组件只是向外通知行为，此时应使用 events。
+
+---
+
+## 声明 actions
+
+Manifest：
+
+```ts
+actions: {
+  refresh: {
+    title: '刷新',
+    description: '重新加载数据',
+    returns: { type: 'boolean' },
+  },
+  setKeyword: {
+    title: '设置关键词',
+    params: {
+      type: 'object',
+      required: ['keyword'],
+      properties: {
+        keyword: { type: 'string', title: '关键词' },
+      },
+    },
+    returns: { type: 'boolean' },
+  },
+}
+```
+
+组件实现：
+
+```tsx
+import { forwardRef, useImperativeHandle, useState } from 'react';
+
+export const SearchPanel = forwardRef((props, ref) => {
+  const [keyword, setKeywordState] = useState('');
+
+  useImperativeHandle(ref, () => ({
+    refresh: async () => {
+      await reload();
+      return true;
+    },
+    setKeyword: ({ keyword }: { keyword: string }) => {
+      setKeywordState(keyword);
+      return true;
+    },
+  }), []);
+
+  return <div />;
+});
+```
+
+---
+
+## 声明 state
+
+Manifest：
+
+```ts
+state: {
+  keyword: {
+    title: '关键词',
+    schema: { type: 'string' },
+  },
+  selectedRowKeys: {
+    title: '选中行',
+    schema: { type: 'array', items: { type: 'string' } },
+  },
+}
+```
+
+组件实现：
+
+```tsx
+import { forwardRef, useImperativeHandle, useState } from 'react';
+import { COMPONENT_STATE_KEY } from 'cdp-material-sdk/portable';
+
+export const TablePanel = forwardRef((props, ref) => {
+  const [keyword, setKeyword] = useState('');
+  const [selectedRowKeys, setSelectedRowKeys] = useState<string[]>([]);
+
+  useImperativeHandle(ref, () => ({
+    clearSelection: () => setSelectedRowKeys([]),
+    [COMPONENT_STATE_KEY]: {
+      keyword,
+      selectedRowKeys,
+    },
+  }), [keyword, selectedRowKeys]);
+
+  return <div />;
+});
+```
+
+---
+
+## 实现要点
+
+| 项目 | 规则 |
+|------|------|
+| Action 名称 | manifest 中声明的 key 必须和 ref 暴露的方法名一致 |
+| Action 参数 | `params.type` 必须是 `object` |
+| Action 返回值 | 建议声明 `returns`；校验级别见 [validateManifest 校验规则](../reference/validateManifest校验规则.md) |
+| State key | manifest 中声明的 state key 必须出现在 `COMPONENT_STATE_KEY` 对象中 |
+| State 修改 | 外部表达式只读访问；修改应通过 action 完成 |
+| deps | 暴露在 state 中的值必须进入 `useImperativeHandle` 依赖数组 |
+
+---
+
+## 自检
+
+```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],
+);
+```
+
+完成标准：
+
+- [ ] `actions.*.title` 已声明。
+- [ ] 有参数的 action 使用 `params.type = 'object'`。
+- [ ] ref 暴露了所有声明的 action 方法。
+- [ ] `state.*.title` 和 `state.*.schema` 已声明。
+- [ ] `COMPONENT_STATE_KEY` 中暴露了所有声明的 state key。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### 只写了 manifest.actions，没有实现 ref 方法
+
+宿主无法调用该 action。使用 `diagnoseMissingActionImpls()` 检查。
+
+### 直接写 `__state` 字符串
+
+推荐使用 `COMPONENT_STATE_KEY`，避免保留 key 拼写不一致。
+
+### State 用于写操作
+
+State 是只读运行时快照。需要修改组件时，请暴露 action。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[ActionsState模型](../reference/ActionsState模型.md)
+- 校验规则：[validateManifest校验规则](../reference/validateManifest校验规则.md)
+- 示例索引：[示例代码索引](../reference/示例代码索引.md)

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

@@ -0,0 +1,221 @@
+---
+type: recipe
+capability: layout-container
+related:
+  - reference/Traits能力模型.md
+  - reference/Manifest字段参考.md
+  - reference/Slots模型.md
+  - recipes/声明插槽.md
+  - recipes/声明数据容器组件.md
+---
+# 声明布局容器组件
+
+布局容器组件用于承载子组件，例如 Card、Grid、Tabs、Collapse、Section 等。
+
+`LAYOUT_CONTAINER` 与 `DATA_CONTAINER` **不互斥**：只要组件同时承载子组件、又管理子字段数据作用域，就应同时声明两个 trait。典型代表是 Form：既是布局容器（拖入字段子组件），又是数据容器（管理表单值）。
+
+---
+
+## 适用场景
+
+- 组件提供一个可放置子组件的区域。
+- 组件可能限制子组件的类型、最少/最多数量。
+- 不论组件是否还参与数据作用域。只要可以拖入子组件，就应声明 `LAYOUT_CONTAINER`。
+
+---
+
+## 可以跳过的情况
+
+- 组件只是单纯的展示组件，没有子内容。
+- 子内容只以命名/作用域/动态区域出现，不需要默认 children 区域，应改用 [声明插槽](./声明插槽.md)。
+- 组件是数据容器但不接受子组件（例如只接 props 的表格），只需要 [声明数据容器组件](./声明数据容器组件.md)。
+
+---
+
+## 选择 children、slots 还是 nesting
+
+| 场景 | 推荐方案 |
+|------|----------|
+| 一个匿名的子组件区域 | `children` + `LAYOUT_CONTAINER` |
+| 多个具名区域（header / footer / actions） | `slots` |
+| 子区域带运行时上下文（行数据、列定义） | 作用域 `slots` |
+| 同时限制可放入的组件类型或数量 | 加 `nesting` |
+
+`children` 模式与 `slots` 模式可以共存：组件可以同时有默认 `children` 区域和若干命名插槽。
+
+---
+
+## 作者职责
+
+1. 声明 `COMPONENT_TRAIT.LAYOUT_CONTAINER`，如果同时是数据容器，同时声明 `COMPONENT_TRAIT.DATA_CONTAINER`。
+2. 在组件实现里渲染 `children`（或对应 slot 内容）。
+3. 如需限制嵌套关系，声明 `nesting`。
+4. 如果同时声明了 `DATA_CONTAINER`，还需按 [声明数据容器组件](./声明数据容器组件.md) 中的要求包 `DataScope`。
+5. 与设计器交互的元信息（图标、分组、隐藏）见 [配置设计器元信息](./配置设计器元信息.md)。
+
+---
+
+## Manifest 示例
+
+### 单一 children 区域（Card 类）
+
+```ts
+import {
+  COMPONENT_CATEGORY,
+  COMPONENT_TRAIT,
+  INJECT_PATH_SLOT_PROPS,
+  type ComponentManifest,
+} from 'cdp-material-sdk/portable';
+
+export const acmeCardManifest = {
+  type: 'acme.Card',
+  traits: [COMPONENT_TRAIT.LAYOUT_CONTAINER],
+  meta: {
+    title: '卡片',
+    category: COMPONENT_CATEGORY.LAYOUT,
+    description: '带边框和阴影的内容容器',
+  },
+  engine: {
+    render: {
+      injection: {
+        rootPath: INJECT_PATH_SLOT_PROPS,
+      },
+    },
+  },
+  props: {
+    type: 'object',
+    properties: {
+      title: { type: 'string', title: '标题' },
+    },
+  },
+} satisfies ComponentManifest;
+```
+
+组件实现：
+
+```tsx
+export const AcmeCard = forwardRef<HTMLDivElement, AcmeCardProps>((props, ref) => {
+  const { title, children, slotProps } = props;
+  return (
+    <div {...slotProps?.root} ref={ref} className="acme-card">
+      {title && <header>{title}</header>}
+      <div className="acme-card-body">{children}</div>
+    </div>
+  );
+});
+```
+
+### 限制嵌套关系（Tabs / FormItem 类）
+
+```ts
+nesting: {
+  allowedChildren: ['acme.TabPane'],
+  minChildren: 1,
+  maxChildren: 12,
+},
+```
+
+### 同时是数据容器（Form 类）
+
+Form 这类组件同时承载字段子组件、又管理表单值，需同时声明两个 trait：
+
+```ts
+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
+} satisfies ComponentManifest;
+```
+
+这种情况下：
+
+- 本文档负责 `LAYOUT_CONTAINER` 部分：渲染 `children`、声明 `nesting`。
+- `DATA_CONTAINER` 部分（`valueSchema`、`DataScope`、字段路径解析）走 [声明数据容器组件](./声明数据容器组件.md)。
+
+---
+
+## nesting 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `allowedChildren` | `string[]` | 允许放入的子组件 `type` 列表，留空表示不限制 |
+| `allowedParents` | `string[]` | 限制本组件只能作为这些父组件的子节点 |
+| `minChildren` | `number` | 最少子组件数量，常用于 Tabs、Steps |
+| `maxChildren` | `number` | 最多子组件数量，常用于固定栅格 |
+
+经验法则：
+
+- 组合关系强（Tabs/TabPane、Steps/Step、Form/FormItem）建议同时声明 `allowedChildren` 与 `allowedParents`。
+- 通用容器（Card、Section）通常不需要 `nesting`，避免过度约束。
+- `nesting` 与 `slots.allowedChildren` 不互斥：前者约束默认 children 区域，后者约束具名 slot 区域。
+
+---
+
+## children 与 slots 共存
+
+```ts
+traits: [COMPONENT_TRAIT.LAYOUT_CONTAINER],
+slots: {
+  header: { title: '头部' },
+  footer: { title: '底部' },
+},
+```
+
+组件实现：
+
+```tsx
+const { children, _slots, slotProps } = props;
+return (
+  <section {...slotProps?.root}>
+    {_slots?.header && <header>{_slots.header}</header>}
+    <div className="body">{children}</div>
+    {_slots?.footer && <footer>{_slots.footer}</footer>}
+  </section>
+);
+```
+
+`children` 用于主内容区，`slots` 用于具名扩展区，两者由设计器分别提供拖拽入口。
+
+---
+
+## 自检
+
+- [ ] `traits` 包含 `COMPONENT_TRAIT.LAYOUT_CONTAINER`。
+- [ ] 组件实现已渲染 `children`（或对应 slot 内容）。
+- [ ] 如声明了 `nesting`，`allowedChildren` / `allowedParents` 中的 type 真实存在。
+- [ ] 如同时使用 `children` 与 `slots`，没有把 children 当成隐式 slot 处理。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### 把数据容器仅声明成布局容器
+
+容器同时承载字段子组件、又管理表单值（例如 Form）时，两个 trait 都要声明，并按数据容器 recipe 提供 `DataScope`。只声明 `LAYOUT_CONTAINER` 会丢失数据语义、表达式和 AI 工具无法识别表单值结构。
+
+### nesting.allowedChildren 写了不存在的 type
+
+设计器会过滤所有候选组件，导致用户在容器内拖不进任何组件。建议用常量或 type 集合维护。
+
+### 用 children 模拟具名插槽
+
+如果有 header / footer / extra 等多个区域，请直接声明 `slots`。把多个区域塞进 `children` 会让设计器和 AI 工具失去结构信息。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 模型参考：[Traits能力模型](../reference/Traits能力模型.md)
+- 字段参考：[Manifest字段参考](../reference/Manifest字段参考.md)
+- 模型参考：[Slots模型](../reference/Slots模型.md)
+- 任务 Recipe：[声明插槽](./声明插槽.md)
+- 任务 Recipe：[声明数据容器组件](./声明数据容器组件.md)
+- 任务 Recipe：[配置设计器元信息](./配置设计器元信息.md)