cdp-material-sdk 0.0.9 → 0.0.10

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

@@ -10,38 +10,62 @@ related:
 ---
 # 声明布局容器组件
 
-布局容器组件用于承载子组件，例如 Card、Grid、Tabs、Collapse、Section 等。
+`LAYOUT_CONTAINER` trait 用于声明组件具备一个**默认 children 区域**——设计器中拖入的子节点会被宿主递归渲染并作为 React `children` 传入组件。
 
-`LAYOUT_CONTAINER` 与 `DATA_CONTAINER` **不互斥**：只要组件同时承载子组件、又管理子字段数据作用域，就应同时声明两个 trait。典型代表是 Form：既是布局容器（拖入字段子组件），又是数据容器（管理表单值）。
+`LAYOUT_CONTAINER` 与 `DATA_CONTAINER` **不互斥**：Form 这类组件既需要默认 children 区域承载字段子组件、又需要管理表单值，应同时声明两个 trait。
+
+---
+
+## LAYOUT_CONTAINER 与 slots 是两条独立路径
+
+宿主在运行时**独立判断**这两个开关，互不依赖：
+
+| 接子节点的方式 | 是否需要 LAYOUT_CONTAINER | 是否需要 `manifest.slots` 声明 |
+|---|:---:|:---:|
+| 默认 children 区域（用户在画布拖入子节点） | ✅ | ❌ |
+| 命名 / 作用域 / 动态插槽（用户填充具名区域） | ❌ | ✅ |
+| 两者并存（既有匿名主区又有 header / footer 等具名区） | ✅ | ✅ |
+| 两者都没有（按钮、输入框） | ❌ | ❌ |
+
+只通过具名插槽接子内容的组件**不需要** `LAYOUT_CONTAINER` trait，直接走 [声明插槽](./声明插槽.md)。
 
 ---
 
 ## 适用场景
 
-- 组件提供一个可放置子组件的区域。
-- 组件可能限制子组件的类型、最少/最多数量。
-- 不论组件是否还参与数据作用域。只要可以拖入子组件，就应声明 `LAYOUT_CONTAINER`。
+- 组件需要一个默认的、匿名的子组件区域，由用户在设计器拖入子节点。
+- 组件需要按 `nesting` 约束限制子组件类型、最少/最多数量。
 
 ---
 
 ## 可以跳过的情况
 
 - 组件只是单纯的展示组件，没有子内容。
-- 子内容只以命名/作用域/动态区域出现，不需要默认 children 区域，应改用 [声明插槽](./声明插槽.md)。
+- 子内容只以命名 / 作用域 / 动态插槽出现，没有默认 children 区域 → 走 [声明插槽](./声明插槽.md)。
 - 组件是数据容器但不接受子组件（例如只接 props 的表格），只需要 [声明数据容器组件](./声明数据容器组件.md)。
 
 ---
 
-## 选择 children、slots 还是 nesting
+## 选择 children + nesting 还是 slots
+
+| 子节点形态 | 推荐方案 | 例子 |
+|---|---|---|
+| 通用匿名子区域 | `LAYOUT_CONTAINER`（无 `nesting`） | Card、Section、Grid |
+| 单一/受限类型的重复子节点（强组合关系） | `LAYOUT_CONTAINER` + `nesting.allowedChildren` / `allowedParents` | Tabs/TabPane、Steps/Step、Form/FormItem、Collapse/Panel |
+| 多个不同语义的具名区域 | `slots`（**不需要** LAYOUT_CONTAINER） | Modal 的 footer、Card 的 header/extra |
+| 数据驱动的多个子区域 | 动态 / 作用域 `slots` | Table 列模板、List 行模板 |
+| 既有匿名主区又有具名扩展区 | `LAYOUT_CONTAINER` + `slots` | Section + header/footer |
+
+### DSL / 低代码场景的归类原则
+
+**单一类型重复的子节点关系优先用 children + nesting，不用 slots**：
+
+- **children + nesting**：子节点是**真正的 DSL 节点**，在节点树中可独立选中、配置、命名、移动、复制粘贴。
+- **slots**：slot 内容是 slot 项的填充物，节点树中会被嵌套在 slot 名下，结构表达更"封闭"。
 
-| 场景 | 推荐方案 |
-|------|----------|
-| 一个匿名的子组件区域 | `children` + `LAYOUT_CONTAINER` |
-| 多个具名区域（header / footer / actions） | `slots` |
-| 子区域带运行时上下文（行数据、列定义） | 作用域 `slots` |
-| 同时限制可放入的组件类型或数量 | 加 `nesting` |
+Tabs/TabPane、Steps/Step、Form/FormItem、Collapse/Panel 这类**强组合关系**应走 children + nesting，用 `nesting.allowedChildren` / `allowedParents` 锁定可拖入的子类型与父类型。
 
-`children` 模式与 `slots` 模式可以共存：组件可以同时有默认 `children` 区域和若干命名插槽。
+slots 更适合"多个不同语义的装饰区/扩展区"和"数据驱动的模板区域"。
 
 ---
 

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

@@ -126,9 +126,11 @@ slots: {
 
 宿主无法生成稳定 slot 名称，`validateManifest()` 会报错。
 
-### 普通容器只声明 LAYOUT_CONTAINER，不声明 slots
+### 把多个固定区域都塞进默认 children
 
-如果组件有明确可填充区域，建议声明 slots。`LAYOUT_CONTAINER` 只说明组件具备布局容器能力，slots 才说明具体区域。
+`LAYOUT_CONTAINER` 只控制**默认 children 区域**的开关，与 `slots` 是两条独立机制。如果组件有 header / footer / extra 等多个固定区域，应声明 `slots` 让宿主分别注入到 `_slots[name]`，不要把它们都挤进 `children`，否则设计器和 AI 工具会失去结构信息。
+
+只用 slots 接子内容的组件**不需要**声明 `LAYOUT_CONTAINER` trait。
 
 ---
 

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

@@ -37,7 +37,8 @@ related:
 2. 在 `meta.valueSchema` 中描述 value 类型。
 3. 组件接收 `value`，值变化时调用 `onChange(nextValue)`。
 4. 如组件支持只读/必填/标签语义，分别接收并应用 `readOnly` / `required` / `label`；置于容器内时支持 `name`。
-5. 一般不需要自己声明 `value` / `readOnly` / `required` / `name` / `label` / `labelStrategy` props，也不需要重复声明 `getValue` / `setValue` / `getReadOnly` / `setReadOnly` / `toggleReadOnly` / `getRequired` / `setRequired` / `toggleRequired` / `triggerValueChange` actions、`value` / `readOnly` / `required` state 或 `valueChange` event——它们由引擎在 `DATA_FIELD` trait 上自动注入并按 `valueSchema` 特化。重复声明会**覆盖**引擎版本，会丢失自动特化；**仅在确有特化需求**（如定制 setValue 取值规则）时才建议显式覆盖。完整字段规格见 [Traits能力模型 · DATA_FIELD](../reference/Traits能力模型.md#data_field)。
+5. 如组件支持 `placeholder`，**仅在可编辑态显示**；`readOnly` / `disabled` 等非编辑态默认隐藏占位提示，避免与已锁定的真实值混淆。
+6. 一般不需要自己声明 `value` / `readOnly` / `required` / `name` / `label` / `labelStrategy` props，也不需要重复声明 `getValue` / `setValue` / `getReadOnly` / `setReadOnly` / `toggleReadOnly` / `getRequired` / `setRequired` / `toggleRequired` / `triggerValueChange` actions、`value` / `readOnly` / `required` state 或 `valueChange` event——它们由引擎在 `DATA_FIELD` trait 上自动注入并按 `valueSchema` 特化。重复声明会**覆盖**引擎版本，会丢失自动特化；**仅在确有特化需求**（如定制 setValue 取值规则）时才建议显式覆盖。完整字段规格见 [Traits能力模型 · DATA_FIELD](../reference/Traits能力模型.md#data_field)。
 
 ---
 
@@ -68,7 +69,8 @@ export const AcmeInput = forwardRef<HTMLInputElement, AcmeInputProps>((props, re
       readOnly={readOnly}
       required={required}
       name={name}
-      placeholder={placeholder}
+      // placeholder 仅在可编辑态显示；只读态隐藏
+      placeholder={readOnly ? undefined : placeholder}
       onChange={(event) => onChange?.(event.target.value)}
     />
   );
@@ -215,6 +217,7 @@ export const AcmeSelect = forwardRef<HTMLDivElement, AcmeSelectProps>((props, re
 - [ ] `meta.valueSchema` 描述了 value 类型。
 - [ ] 组件接收 `value`，值变化时调用 `onChange(nextValue)`。
 - [ ] 组件按需接收并应用 `readOnly` / `required` / `name` / `label` / `labelStrategy`（不必全部支持，但接收的 prop 必须真正生效）。
+- [ ] 若支持 `placeholder`，已确保仅在可编辑态显示，`readOnly` / `disabled` 时隐藏。
 - [ ] manifest 中没有不必要地重复声明 DATA_FIELD 自动注入的 props / actions / state / events；确有覆盖的，能明确说出特化原因。
 - [ ] `validateManifest()` 没有 error。
 
@@ -234,6 +237,10 @@ export const AcmeSelect = forwardRef<HTMLDivElement, AcmeSelectProps>((props, re
 
 在自己的 manifest 里再写一遍 `value` prop、`getValue` / `setValue` action、`valueChange` event 等，会**覆盖**引擎注入的版本，并**丢失 `valueSchema` 自动特化**。默认只写**业务专属**的 props（如 `placeholder`）和事件；仅在**确有特化需求**时才显式覆盖自动注入的字段，并在代码/PR 中说明原因。
 
+### `placeholder` 在只读/禁用态仍然显示
+
+占位提示与已锁定的真实值同时出现，会让使用者误解控件状态。约定是**只在可编辑态显示** `placeholder`，进入 `readOnly` / `disabled` 时清空或不传该 prop（如 `placeholder={readOnly ? undefined : placeholder}`）。
+
 ### 接收了 `readOnly` / `required` 却没有真正生效
 
 引擎会注入 `readOnly` / `required` 并在 state 中持续更新；如果组件渲染时忽略这两个 prop，事件编排里 `setReadOnly` / `toggleRequired` 等 action 看起来生效（state 变了）但 UI 不变，会让使用者困惑。要么接收并应用，要么不接收（说明组件不支持该语义）。

package/docs/component-development/reference/Traits/350/203/275/345/212/233/346/250/241/345/236/213.md

@@ -22,7 +22,7 @@ Traits 之间不互斥，一个组件可以同时声明多个 trait。例如 For
 |-------|------|----------|------------|
 | `Data.Field` | `COMPONENT_TRAIT.DATA_FIELD` | Input、Select、Switch、DatePicker | 组件是一个数据字段 |
 | `Data.Container` | `COMPONENT_TRAIT.DATA_CONTAINER` | Form、Table、List、CardList | 组件管理一组数据作用域 |
-| `Layout.Container` | `COMPONENT_TRAIT.LAYOUT_CONTAINER` | Card、Grid、Tabs、Collapse | 组件可以承载子组件或插槽内容 |
+| `Layout.Container` | `COMPONENT_TRAIT.LAYOUT_CONTAINER` | 通用容器：Card、Grid、Section；强组合关系：Tabs、Steps、Form（带 `nesting` 类型约束） | 组件具备**默认 children 区域**（与 `manifest.slots` 是两条独立机制） |
 | `Interaction.Clickable` | `COMPONENT_TRAIT.INTERACTION_CLICKABLE` | Button、Link、ClickableCard | 组件具备点击交互语义 |
 
 ---
@@ -112,15 +112,21 @@ Traits 之间不互斥，一个组件可以同时声明多个 trait。例如 For
 
 ### 什么时候声明
 
-组件可以承载子组件、插槽或模板内容。
+组件需要一个**默认 children 区域**：设计器中拖入的子节点会被宿主递归渲染并作为 React `children` 传入。
+
+只通过命名 / 作用域 / 动态插槽承载子内容的组件**不需要**声明此 trait，直接通过 `manifest.slots` 即可。
 
 ### 作者要做什么
 
 - 声明 `COMPONENT_TRAIT.LAYOUT_CONTAINER`。
-- 在组件实现中渲染 `children`（单一区域）或对应 slot 内容（多具名区域）。
-- 需要限制子组件类型、最少/最多数量、或能作为子节点的父组件时，声明 `nesting`。
+- 在组件实现中渲染 `children`。
+- 需要限制默认 children 区域的子组件类型、最少/最多数量、或能作为子节点的父组件时，声明 `nesting`。
 - 详细任务步骤见 [声明布局容器组件](../recipes/声明布局容器组件.md)。
 
+### 与 slots 的关系
+
+宿主在运行时独立判断 `LAYOUT_CONTAINER` trait 与 `manifest.slots`：前者控制默认 children 区域，后者控制具名插槽。两者可以并存，也可以独立使用。
+
 ### 宿主可据此做什么
 
 - 在设计器中允许拖入子组件。
@@ -170,9 +176,11 @@ meta: {
 | 组件场景 | 推荐 traits |
 |----------|-------------|
 | 输入框、选择器、开关 | `DATA_FIELD` |
-| 表单 | `DATA_CONTAINER` + `LAYOUT_CONTAINER` |
-| 表格、列表 | `DATA_CONTAINER`，按需加 `LAYOUT_CONTAINER` |
-| 卡片、栅格、Tabs | `LAYOUT_CONTAINER` |
+| 表单 | `DATA_CONTAINER` + `LAYOUT_CONTAINER`（搭配 `nesting.allowedChildren` 锁定 FormItem 等） |
+| 表格、列表 | `DATA_CONTAINER`，列/行模板用动态 / 作用域 `slots` |
+| 卡片、栅格、Section（通用 children 区域） | `LAYOUT_CONTAINER` |
+| Tabs / Steps / Collapse（强组合关系） | `LAYOUT_CONTAINER` + `nesting`（子/父类型约束） |
+| Modal / Card 的多具名扩展区（header / footer） | `slots` |
 | 按钮、链接 | `INTERACTION_CLICKABLE` |
 | 普通文本展示 | 可不声明 |
 
@@ -184,7 +192,7 @@ meta: {
 |------|------|
 | `DATA_FIELD` | 仅用于有主要业务值且能回写的组件 |
 | `DATA_CONTAINER` | 用于管理子字段数据作用域；必须在子组件渲染区域提供 `DataScope`。与 `LAYOUT_CONTAINER` 不互斥，Form 这类容器应同时声明 |
-| `LAYOUT_CONTAINER` | 表示可承载子内容；有明确区域时建议同时声明 slots |
+| `LAYOUT_CONTAINER` | 控制**默认 children 区域**开关，仅影响 `schema.children` 是否被宿主递归渲染。具名子区域走 `manifest.slots`，与本 trait 互不依赖 |
 | `INTERACTION_CLICKABLE` | 表示具备点击语义；需要编排响应时再声明 click event |
 
 数据 trait 与 `meta.valueSchema` 的校验级别见 [validateManifest 校验规则](./validateManifest校验规则.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-material-sdk",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "license": "MIT",
   "publishConfig": {
     "access": "public",