cdp-material-sdk 0.0.8 → 0.0.10

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

@@ -147,6 +147,102 @@ actions: {
 
 ---
 
+## 自实现 loading 的 hook
+
+`none` 策略下组件得自己维护 loading state。SDK 在 `cdp-material-sdk/portable` 提供两个**纯 React、无宿主耦合**的便利 hook，避免每家组件重复实现引用计数与 dual-loading 合并逻辑。
+
+### useConcurrentLoading：并发动作 loading
+
+适合按钮上同时挂多个异步动作、或同一组件可能并发触发多次请求的场景。返回的 `startLoading` / `stopLoading` 是**引用计数式**的——后到的 stop 不会误清先到的 start。
+
+```tsx
+import { useConcurrentLoading } from 'cdp-material-sdk/portable';
+
+export function AcmePanel() {
+  const { isLoading, loadingText, startLoading, stopLoading } = useConcurrentLoading();
+
+  const handleSave = async () => {
+    startLoading('保存中…');
+    try {
+      await saveToServer();
+    } finally {
+      stopLoading();
+    }
+  };
+
+  return (
+    <button disabled={isLoading} onClick={handleSave}>
+      {isLoading ? loadingText ?? '处理中…' : '保存'}
+    </button>
+  );
+}
+```
+
+返回值要点：
+
+- `isLoading` 是触发重渲染的状态值，可直接驱动 UI。
+- `getLoading()` 是 ref 读取，适合放进 `useCallback`、事件处理器中按需读取，无需进依赖列表。
+- `loadingText` 由最近一次 `startLoading(text)` 设置；不传 `text` 则保持上次值。
+
+### useDualLoading：动作 loading 与数据 loading 分离
+
+适合 Table、查询面板这类**同时存在「按钮触发的动作」与「后台数据请求」**的组件。两类 loading 单独建模，但对外仍暴露统一的 `isLoading`。
+
+```tsx
+import { useEffect } from 'react';
+import { useDualLoading } from 'cdp-material-sdk/portable';
+
+export function AcmeTable({ query }) {
+  const {
+    actionLoading,         // 动作触发的 loading（引用计数）
+    startActionLoading,
+    stopActionLoading,
+    dataLoading,           // 数据请求 loading（布尔）
+    setDataLoading,
+    isLoading,             // 二者的 OR
+    isLoadingRef,          // 引用稳定的最新值
+  } = useDualLoading();
+
+  // 数据请求：标记 dataLoading
+  useEffect(() => {
+    let cancelled = false;
+    setDataLoading(true);
+    fetchRows(query).finally(() => {
+      if (!cancelled) setDataLoading(false);
+    });
+    return () => { cancelled = true; };
+  }, [query, setDataLoading]);
+
+  // 行内动作：标记 actionLoading
+  const handleRowDelete = async (id: string) => {
+    startActionLoading('删除中…');
+    try {
+      await deleteRow(id);
+    } finally {
+      stopActionLoading();
+    }
+  };
+
+  return <TableUi loading={isLoading} onDelete={handleRowDelete} />;
+}
+```
+
+要点：
+
+- 用 `dataLoading` 表达「后台拉数据」，用 `actionLoading` 表达「用户动作触发的并发任务」，二者互不污染。
+- 对外通过 `isLoading` 对接 UI 即可，不必在外层组合两个布尔。
+- `isLoadingRef.current` 提供引用稳定的最新值，方便在事件回调里判断「当前是否仍处于 loading」而不必把状态加进依赖列表。
+
+### 与 manifest loading 策略的搭配
+
+| 场景 | manifest 策略 | hook |
+|------|---------------|------|
+| 完全交给宿主 | `native` 或 `wrapper` | 不需要 |
+| 宿主只接管视觉、组件内部仍想细分 loading | `wrapper` + 这两个 hook | `useConcurrentLoading` 或 `useDualLoading`，组件内部用 hook 状态驱动局部 UI，宿主负责整体遮罩 |
+| 完全自管 | `none` + 自定义 `setLoading` / `getLoading` actions | 推荐 `useConcurrentLoading`；用 hook 的 `getLoading` 实现 action 的 `getLoading`，用 `startLoading` / `stopLoading` 实现 action 的 `setLoading` |
+
+---
+
 ## 选择表
 
 | 组件情况 | 推荐策略 |

package/docs/component-development/reference/Manifest/345/255/227/346/256/265/345/217/202/350/200/203.md

@@ -22,7 +22,7 @@ related:
 | `alias` | `string[]` | 否 | 历史别名或兼容名 |
 | `meta` | `object` | 是 | 基本信息 |
 | `traits` | `ComponentTrait[]` | 否 | 能力声明 |
-| `props` | `ObjectSchema` | 否 | 可配置 props 的 JSON Schema |
+| `props` | `ObjectSchema` | 否 | 可配置 props 的 JSON Schema，详见 [声明 props](../recipes/声明props.md) |
 | `events` | `EventSpec[]` | 否 | 标准事件声明 |
 | `customEvents` | `Record<string, CustomEventSpec>` | 否 | 自定义事件声明 |
 | `actions` | `Record<string, ActionSpec>` | 否 | 组件动作声明 |
@@ -245,6 +245,7 @@ export const manifest = {
 本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
 
 - 关联文档：[03-开发最小可运行组件](../getting-started/03-开发最小可运行组件.md)
+- 任务 Recipe：[声明 props](../recipes/声明props.md)
 - 任务 Recipe：[声明布局容器组件](../recipes/声明布局容器组件.md)
 - 任务 Recipe：[配置设计器元信息](../recipes/配置设计器元信息.md)
 - 校验规则：[validateManifest校验规则](./validateManifest校验规则.md)

package/docs/component-development/reference/SDK/345/257/274/345/205/245/350/276/271/347/225/214.md

@@ -31,6 +31,7 @@ related:
 - `validateManifest()`
 - `diagnoseMissingActionImpls()`
 - `diagnoseMissingStateKeys()`
+- `useConcurrentLoading` / `useDualLoading`（组件自实现 loading 时的开箱即用 hook）
 
 示例：
 
@@ -53,10 +54,10 @@ import {
 
 可用于：
 
-- `DataScope`
-- `useDataContainer`
-- `useDataContainerApi`
-- `PageContext`
+- `DataScope` / `DataScopeContext` / 类型 `FieldState` / `LazyScope` / `PathResolver`
+- `useDataContainer` / `useDataContainerApi`
+- `useFieldRegistry`（与 `DataScope` 配套，给数据容器组件聚合子字段状态）
+- `PageContext` / `DataContainerRuntimeContext`
 
 如果不能确认共享 runtime，请不要使用该入口。
 

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 | 组件具备点击交互语义 |
 
 ---
@@ -37,15 +37,52 @@ Traits 之间不互斥，一个组件可以同时声明多个 trait。例如 For
 
 - 声明 `COMPONENT_TRAIT.DATA_FIELD`。
 - 声明 `meta.valueSchema`。
-- 组件接收 `value`。
-- 值变化时调用 `onChange(nextValue)`。
+- 组件接收并渲染 `value`，值变化时调用 `onChange(nextValue)`。
+- 如组件支持只读/必填/标签语义，分别接收 `readOnly` / `required` / `label`；置于数据容器内时支持 `name`。
+
+下列 props / actions / state / events 由引擎在声明 `DATA_FIELD` 后**自动注入并合并到 manifest**，作者一般**不需要**在自己的 manifest 中重复声明——重复声明会**覆盖**引擎注入的版本（包括 `valueSchema` 自动特化），破坏对外行为一致性。仅当组件**确有特化需求**（例如定制 `setValue.params` 取值规则）时，才建议显式声明覆盖：
+
+#### 自动注入的 props
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `value` | 由 `meta.valueSchema` 决定 | 字段当前值 |
+| `readOnly` | `boolean` | 是否只读 |
+| `required` | `boolean` | 是否必填 |
+| `name` | `string` | 字段名（容器内组织值用） |
+| `label` | `string` | 显示标签 |
+| `labelStrategy` | 标签策略对象 | 字段级标签策略局部覆盖；未设置时向上继承（FieldLayout / Form / Page / 默认） |
+
+#### 自动注入的 actions
+
+| Action | 说明 |
+|--------|------|
+| `getValue` | 获取当前值；返回类型由 `valueSchema` 特化 |
+| `setValue({ value, triggerEvent? })` | 设置值；返回 `{ newValue, oldValue }`；`triggerEvent` 默认 `true` |
+| `getReadOnly` / `setReadOnly({ readOnly })` / `toggleReadOnly` | 只读状态读写与切换 |
+| `getRequired` / `setRequired({ required })` / `toggleRequired` | 必填状态读写与切换 |
+| `triggerValueChange({ newValue?, oldValue? })` | 手动触发 `valueChange` 事件，用于 `updateFields` / 直写 Store 等绕过 `setValue` 的场景 |
+
+#### 自动注入的 state
+
+| State | Schema | 说明 |
+|-------|--------|------|
+| `value` | `meta.valueSchema` | 当前值；schema 由 `valueSchema` 自动透传 |
+| `readOnly` | `boolean` | 当前只读状态 |
+| `required` | `boolean` | 当前必填状态 |
+
+#### 自动注入的 events
+
+| Event | 说明 |
+|-------|------|
+| `valueChange` | 值变更事件；`onChange(nextValue)` 或 `setValue` 默认触发；可被事件编排消费 |
 
 ### 宿主可据此做什么
 
-- 注入和回写字段值。
-- 在数据容器内按字段名组织值。
-- 让表达式、设计器和 AI 工具识别 value 类型。
-- 基于 `valueSchema` 推断标准 value 状态。
+- 注入和回写字段值，在数据容器内按 `name` 组织值。
+- 让表达式、设计器和 AI 工具识别 value 类型与字段语义。
+- 基于 `valueSchema` 自动特化 `getValue` / `setValue` / `state.value` 的类型描述。
+- 统一管理只读/必填状态，支持事件编排基于 `readOnly` / `required` / `value` 状态联动。
 
 ---
 
@@ -75,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 区域，后者控制具名插槽。两者可以并存，也可以独立使用。
+
 ### 宿主可据此做什么
 
 - 在设计器中允许拖入子组件。
@@ -133,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` |
 | 普通文本展示 | 可不声明 |
 
@@ -147,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/docs/component-development/reference//345/274/225/346/223/216/345/237/272/347/241/200/350/203/275/345/212/233/346/250/241/345/236/213.md

@@ -9,7 +9,7 @@ related:
 ---
 # 引擎基础能力模型
 
-引擎基础能力是宿主自动赋予所有组件的通用运行时能力。组件作者通常不需要在 manifest 中重复声明这些能力，只需要避免冲突，并确保组件根节点能承接宿主注入。
+引擎基础能力是宿主自动赋予所有组件的通用运行时能力。组件作者一般不需要在 manifest 中重复声明这些能力——它们由宿主统一注入，重复声明会**覆盖**宿主版本，破坏对外行为的一致性。仅当组件**确有特化需求**时，才建议显式声明覆盖。
 
 ---
 
@@ -17,24 +17,26 @@ related:
 
 | 能力 | 外部含义 | 组件作者需要做什么 |
 |------|----------|-------------------|
-| `hidden` prop | 宿主告诉组件当前是否隐藏 | 可按需读取，但不要改成其他业务语义 |
-| `getHidden` action | 外部流程读取组件显隐状态 | 不要重复声明同名 action |
-| `setHidden` action | 外部流程设置组件显隐状态 | 不要重复声明同名 action |
-| `toggleHidden` action | 外部流程切换组件显隐状态 | 不要重复声明同名 action |
-| `hidden` state | 外部表达式、编排或 AI 读取当前显隐状态 | 不要重复声明同名 state |
-| `mount` / `unmount` events | 基础生命周期通知 | 普通组件不需要重复声明 |
+| `hidden` prop | 宿主告诉组件当前是否隐藏 | 可按需读取；不建议改写为其他业务语义 |
+| `getHidden` action | 外部流程读取组件显隐状态 | 默认不声明；如需特化（例如不同的 returns 描述）再显式覆盖 |
+| `setHidden` action | 外部流程设置组件显隐状态 | 默认不声明；如需特化再显式覆盖 |
+| `toggleHidden` action | 外部流程切换组件显隐状态 | 默认不声明；如需特化再显式覆盖 |
+| `hidden` state | 外部表达式、编排或 AI 读取当前显隐状态 | 默认不声明；如需特化 schema 再显式覆盖 |
+| `mount` / `unmount` events | 基础生命周期通知 | 默认不声明；普通组件无需重复 |
+
+> 显式声明同名字段会覆盖宿主默认版本，请确认特化是必要的，并在 review 时让上游能识别这是有意覆盖。
 
 ---
 
 ## 与组件 manifest 的关系
 
-基础能力由宿主在运行时补充。第三方组件 manifest 应只声明组件自己的业务能力，例如：
+基础能力由宿主在运行时补充。第三方组件 manifest 通常只需声明组件自己的业务能力，例如：
 
 - 业务 actions，例如 `refresh`、`clear`、`focus`。
 - 业务 state，例如 `selectedRows`、`keyword`。
 - 业务 events，例如 `valueChange`、`itemClick` 或自定义事件。
 
-不要为了获得显隐控制而在 manifest 中手写 `getHidden`、`setHidden`、`toggleHidden` 或 `hidden` state。
+一般不需要为了获得显隐控制而在 manifest 中手写 `getHidden`、`setHidden`、`toggleHidden` 或 `hidden` state；只在确有特化需求时再覆盖。
 
 ---
 

package/package.json

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

package/dist/DataScope-B7ffH5qN.js

@@ -1,106 +0,0 @@
-import { createContext as D, useContext as f, useCallback as l, useRef as j, useMemo as E } from "react";
-import { useStore as O } from "zustand";
-import { cloneDeep as i, has as g, set as M } from "lodash-es";
-import { jsx as k } from "react/jsx-runtime";
-const b = D(null), d = D(null), x = "value", m = (t) => t !== null && typeof t == "object" && !Array.isArray(t), p = (t) => Array.isArray(t) && t.every((n) => n === void 0 || m(n)), C = (t, n, e = [x]) => {
-  if (!g(t, e)) {
-    M(t, e, i(n));
-    return;
-  }
-  if (p(n)) {
-    n.forEach((r, o) => {
-      C(t, r, [...e, o]);
-    });
-    return;
-  }
-  if (m(n))
-    for (const [r, o] of Object.entries(n))
-      C(
-        t,
-        o,
-        [...e, r]
-      );
-}, $ = (t, n) => {
-  if (n === void 0)
-    return t;
-  if (t === void 0)
-    return i(n);
-  const e = p(n), r = p(t), o = Array.isArray(n), s = Array.isArray(t), u = m(n), a = m(t);
-  if (o !== s || u !== a)
-    return i(n);
-  if ((o || s) && (!e || !r))
-    return i(n);
-  if (e !== r || u !== a)
-    return i(n);
-  if (!e && !u)
-    return i(n);
-  const c = { value: i(n) };
-  return C(c, t), c.value;
-}, P = (t) => t === void 0 || t !== null && typeof t == "object", K = (t, n, e) => !t || !n || t !== n.componentId || n.hasInitializedRef.current || n.initialDefaultValueRef.current === void 0 ? !1 : P(e), I = (t, n, e) => K(t, n, e) ? $(e, n?.initialDefaultValueRef.current) : e;
-function U(t) {
-  const n = f(b), e = f(d), r = n?.store ?? null, o = t ?? e?.componentId, s = l(() => {
-    const c = r && o ? r.getState().components[o]?.value : void 0;
-    return I(o, e, c);
-  }, [o, e, r]), u = l((c) => {
-    !r || !o || r.getState().setComponentData(o, c);
-  }, [o, r]), a = l(() => {
-    !r || !o || r.getState().resetComponentData(o);
-  }, [o, r]);
-  return { getContainerData: s, setContainerData: u, resetContainerData: a };
-}
-function T(t) {
-  const n = U(t), e = f(b), r = f(d), o = e?.store ?? null, s = t ?? r?.componentId;
-  return {
-    containerData: o ? I(
-      s,
-      r,
-      O(o, (a) => s ? a.components[s]?.value : void 0)
-    ) : void 0,
-    ...n
-  };
-}
-const Y = D(null), _ = "components", h = "value", w = (t, n) => `${_}.${t}.${h}.${n}`, q = ({
-  relativePath: t,
-  record: n,
-  getRecord: e,
-  index: r,
-  registerField: o,
-  unregisterField: s,
-  children: u
-}) => {
-  const a = f(d);
-  if (!a?.componentId)
-    throw new Error(
-      "[cdp-material-sdk] DataScope 必须在数据容器组件内部使用，请确保上层提供 DataContainerRuntimeContext。"
-    );
-  const c = a.componentId, y = l(
-    (v) => {
-      const S = t ? t(v) : v;
-      return w(c, S);
-    },
-    [c, t]
-  ), A = j(n);
-  A.current = n;
-  const R = E(
-    () => ({
-      resolvePath: y,
-      inScope: !0,
-      getRecord: e ?? (() => A.current),
-      index: r,
-      registerField: o,
-      unregisterField: s
-    }),
-    [y, e, r, o, s]
-  );
-  return /* @__PURE__ */ k(Y.Provider, { value: R, children: u });
-};
-export {
-  d as D,
-  b as P,
-  q as a,
-  Y as b,
-  U as c,
-  I as r,
-  K as s,
-  T as u
-};