cdp-material-sdk 0.0.8 → 0.0.10

package/dist/hooks/useFieldRegistry.d.ts

@@ -0,0 +1,36 @@
+import type { FieldState } from '../context/DataScopeContext';
+/**
+ * 字段注册表 Hook —— 数据容器组件的便利工具。
+ *
+ * 与 `DataScope` 配对使用：DataScope 通过 `registerField` / `unregisterField`
+ * 把后代字段的实时状态（隐藏、只读、必填等）上报到容器；本 Hook 提供 Ref 支撑的
+ * 注册表实现，避免频繁重渲染。
+ *
+ * 典型用法：
+ * ```tsx
+ * const { registerField, unregisterField, getAllFieldStates } = useFieldRegistry();
+ *
+ * return (
+ *   <DataScope
+ *     registerField={registerField}
+ *     unregisterField={unregisterField}
+ *     getRecord={getValue}
+ *   >
+ *     {children}
+ *   </DataScope>
+ * );
+ * ```
+ */
+export interface UseFieldRegistryResult {
+    /** 注册或更新字段状态。建议在子组件 useEffect 中调用。 */
+    registerField: (field: FieldState) => void;
+    /** 注销字段。建议在子组件卸载时调用。 */
+    unregisterField: (id: string) => void;
+    /** 读取单个字段状态。 */
+    getFieldState: (id: string) => FieldState | undefined;
+    /** 读取全部字段状态快照。 */
+    getAllFieldStates: () => FieldState[];
+    /** 清空注册表。 */
+    clearRegistry: () => void;
+}
+export declare function useFieldRegistry(): UseFieldRegistryResult;

package/dist/host-react.d.ts

@@ -13,3 +13,5 @@ export { DataScope } from './components/data-scope/DataScope';
 export type { DataScopeProps } from './components/data-scope/DataScope';
 export { DataScopeContext } from './context/DataScopeContext';
 export type { DataScopeContextValue, FieldState, LazyScope, PathResolver } from './context/DataScopeContext';
+export { useFieldRegistry } from './hooks/useFieldRegistry';
+export type { UseFieldRegistryResult } from './hooks/useFieldRegistry';

package/dist/host-react.js

@@ -1,11 +1,12 @@
-import { D as e, a as n, b as o, P as s, r as i, s as r, u, c as C } from "./DataScope-B7ffH5qN.js";
+import { D as t, a as s, b as n, P as o, r as i, s as r, u, c as C, d as D } from "./useFieldRegistry-CwjlA-ja.js";
 export {
-  e as DataContainerRuntimeContext,
-  n as DataScope,
-  o as DataScopeContext,
-  s as PageContext,
+  t as DataContainerRuntimeContext,
+  s as DataScope,
+  n as DataScopeContext,
+  o as PageContext,
   i as resolveDataContainerRuntimeValue,
   r as shouldUseDataContainerRuntimeFallback,
   u as useDataContainer,
-  C as useDataContainerApi
+  C as useDataContainerApi,
+  D as useFieldRegistry
 };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { C as e, a as t, b as n, c as i, D as o, E, I as T, d as _, L as O, e as N, f as R, N as r, g as A, O as C, h as S, R as l, S as u, i as D, j as m, k as I, l as P, m as d, n as p, o as Y, p as M, q as c, u as g, r as L, v as G, s as v } from "./validateManifest-CYqjvQe_.js";
-import { D as K, a as h, b as x, P as V, r as b, s as y, u as F, c as k } from "./DataScope-B7ffH5qN.js";
+import { C as e, a as t, b as n, c as i, D as o, E, I as T, d as _, L as O, e as N, f as R, N as r, g as A, O as C, h as l, R as S, S as u, i as D, j as d, k as m, l as I, m as P, n as p, o as Y, p as M, q as g, u as c, r as L, v as G, s as v } from "./validateManifest-CYqjvQe_.js";
+import { D as K, a as h, b as x, P as V, r as y, s as F, u as b, c as k, d as z } from "./useFieldRegistry-CwjlA-ja.js";
 export {
   e as CATEGORY_LABELS,
   t as COMPONENT_CATEGORY,
@@ -18,25 +18,26 @@ export {
   r as NOTIFY_ERROR_STRATEGY,
   A as NOTIFY_TIMING,
   C as OptionItemSchema,
-  S as OptionsSchema,
+  l as OptionsSchema,
   V as PageContext,
-  l as RemoteOptionConfigSchema,
+  S as RemoteOptionConfigSchema,
   u as SLOT_KEY,
   D as STANDARD_EVENT_KEYS,
-  m as diagnoseMissingActionImpls,
-  I as diagnoseMissingStateKeys,
-  P as isCustomEventKey,
-  d as isStandardEventKey,
+  d as diagnoseMissingActionImpls,
+  m as diagnoseMissingStateKeys,
+  I as isCustomEventKey,
+  P as isStandardEventKey,
   p as normalizeAdapterEvents,
   Y as normalizeManifestEvents,
   M as printSingleValidationResult,
-  c as printValidationResult,
-  b as resolveDataContainerRuntimeValue,
-  y as shouldUseDataContainerRuntimeFallback,
-  g as useConcurrentLoading,
-  F as useDataContainer,
+  g as printValidationResult,
+  y as resolveDataContainerRuntimeValue,
+  F as shouldUseDataContainerRuntimeFallback,
+  c as useConcurrentLoading,
+  b as useDataContainer,
   k as useDataContainerApi,
   L as useDualLoading,
+  z as useFieldRegistry,
   G as validateManifest,
   v as validateManifests
 };

package/dist/useFieldRegistry-CwjlA-ja.js

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

package/docs/component-development/README.md

@@ -57,6 +57,16 @@
 - [声明插槽](./recipes/声明插槽.md)
 - [Traits 能力模型](./reference/Traits能力模型.md)
 
+### 我要声明组件对外的可配置项（props）
+
+`props` 是组件向设计器、表达式和 AI 工具暴露的可配置项契约（标准 JSON Schema）。
+
+阅读：
+
+- [声明 props](./recipes/声明props.md)
+- [Manifest 字段参考](./reference/Manifest字段参考.md)
+- [Traits 能力模型](./reference/Traits能力模型.md)（理解 trait 自动注入 props 的边界）
+
 ### 我要调整组件在设计器中的展示
 
 阅读：

package/docs/component-development/recipes//344/275/277/347/224/250Adapter/351/200/202/351/205/215/347/273/204/344/273/266API.md

@@ -12,19 +12,53 @@ Adapter 用于把组件自身 API 映射到 CDP 约定。它适合接入第三
 
 ---
 
-## 适用场景
+## wrapper vs adapter 决策框架
 
-- 第三方组件的 prop 名与 CDP 默认名不同。
-- 第三方组件的事件 prop 名不同。
-- 需要对传入 props 做轻量转换。
+接入第三方组件、或组件 prop / 事件名不符合 CDP 约定时，有两条路径：用 manifest 的 **adapter** 在引擎层声明映射、或在 React **wrapper** 内手写转换。**按"层"做选择，不要按"默认优先谁"**——adapter 与 wrapper 各自有原生擅长的层。
+
+### 三层视角
+
+| 层 | 适配诉求 | adapter 原生能力 | 推荐 |
+|----|---------|-----------------|------|
+| 事件层 | 改 prop 名（`onClick` → `onPress`） | `events[K].propName` / `customEvents[K].propName` | **adapter** |
+| 事件层 | reshape payload 到 CDP 标准 payload | `events[K].transform`（类型化到 `EngineEventProtocol[K]`）/ `customEvents[K].transform` | **adapter** |
+| 事件层 | 提取作用域 record / index | `events[K].toScope` / `customEvents[K].toScope` | **adapter** |
+| Props 层 | 改 prop 名（`value` → `selectedValue`） | `propMapping` | **adapter** |
+| Props 层 | 值转换 / 默认值 / 受控-非受控调谐 | 仅 `mapProps`（**逃生舱**） | **wrapper** |
+| 结构层 | children / slots / ref 转发 / 副作用 | — | **wrapper** |
+
+### 事件层为什么是 adapter 的主场
+
+`StandardEventBinding<K>` / `CustomEventBinding` 的能力是 **propName + transform + toScope**，三者合起来覆盖了"换名 + 重塑 payload + 提取作用域"——CDP 标准事件的全部适配诉求。`transform` 的返回类型还约束到 `EngineEventProtocol[K]`，是**类型化**的转换。这正是它的设计目标，**不是逃生舱**。
+
+写在 wrapper 里反而要重新构造一份相同的 payload，丢失类型约束，并把协议形状渗透到组件源码。
+
+### Props 层的分界线在"是否需要值变换"
+
+- **只是改名** → `adapter.propMapping` 一行配置，组件保留原生 API。
+- **要做值变换、补默认值、做受控转换、加副作用、需要 ref**：adapter 仅有 `mapProps` 这条路，而 `mapProps` 是真正的逃生舱（无类型、不可静态分析、复杂逻辑藏在 manifest）。这种场景**回到 wrapper**。
+
+### 结构层永远是 wrapper
+
+children/slots 渲染、ref 转发、`useEffect` 副作用、错误边界——这些都不在 adapter 的能力范围。
+
+### 协议解耦
+
+- **wrapper**：把第三方原生 API 锁在内部，对外暴露 CDP 形状。**适配层在 React 里**，组件依赖 `BaseUIProps` / `slotProps` / `cdp-material-sdk/portable` 类型。
+- **adapter**：组件保留原生 API，CDP 形状的转换写在 manifest。**适配层在 manifest 里**，组件不引入 CDP 类型依赖，可被非 CDP 项目复用。
+
+两者方向相反，按上面三层选择，不必把协议解耦当作单一论据。
+
+### 同一个组件的混合策略
+
+事件层用 adapter、props 值层用 wrapper 是常见组合——只要 wrapper 输出的 props 能让 adapter 在引擎层补上事件映射即可。**不要在两层都做同样的事**，否则会重复甚至冲突。
 
 ---
 
-## 可以跳过的情况
+## 可以跳过 adapter 的情况
 
-- 你可以在 wrapper 内直接转换 API。
-- 组件本身已经使用 `value`、`onChange`、`onClick` 等 CDP 约定。
-- 适配逻辑复杂，需要在组件代码中处理。
+- 组件本身已经使用 CDP 约定（`value` / `onChange` / `onClick` / 标准 payload）。
+- 全部适配诉求都在结构层或 props 值层 → 走 wrapper 即可。
 
 ---
 
@@ -47,7 +81,15 @@ adapter: {
 
 ## events 映射
 
-标准事件映射：
+`StandardEventBinding<K>` / `CustomEventBinding` 提供三个原语：
+
+| 字段 | 作用 |
+|------|------|
+| `propName` | 第三方组件实际触发回调的 prop 名（如 `onPress`、`onSelectedValueChange`） |
+| `transform(...args)` | 把第三方回调参数 reshape 成 CDP 标准 payload；标准事件返回类型受 `EngineEventProtocol[K]` 约束 |
+| `toScope(...args)` | 从回调参数中提取 `{ record, index }`，用于 List/Table 行项事件的作用域 |
+
+### 标准事件 — 仅改名
 
 ```ts
 events: {
@@ -62,29 +104,75 @@ adapter: {
 },
 ```
 
-自定义事件映射：
+### 标准事件 — 改名 + payload 重塑
+
+第三方组件回调签名是 `(event, value) => void`，但 CDP `valueChange` 的 payload 形状是 `{ value }`：
+
+```ts
+events: {
+  valueChange: { title: '值变化' },
+},
+adapter: {
+  events: {
+    valueChange: {
+      propName: 'onSelectedValueChange',
+      transform: (event, value) => ({ value }),
+    },
+  },
+},
+```
+
+`transform` 的返回类型由 `EngineEventProtocol['valueChange']` 自动约束，少写错。
+
+### 自定义事件 — 改名 + payload + scope
+
+行项点击常见形态：第三方 List 的 `onItemTap(item, index)`，CDP 侧声明为带作用域的自定义事件：
 
 ```ts
 customEvents: {
   'acme:rowClick': {
     title: '行点击',
-    payloadSchema: { type: 'object' },
+    payloadSchema: {
+      type: 'object',
+      properties: {
+        rowId: { type: 'string' },
+      },
+    },
   },
 },
 adapter: {
   customEvents: {
     'acme:rowClick': {
-      propName: 'onRowClick',
+      propName: 'onItemTap',
+      transform: (item) => ({ rowId: item.id }),
+      toScope: (item, index) => ({ record: item, index }),
     },
   },
 },
 ```
 
+`toScope` 让事件编排能基于"哪一行"组织上下文，无需在 wrapper 中手写作用域注入。
+
 ---
 
-## mapProps
+## propMapping
 
-当静态映射不够时，可以使用 `mapProps`：
+将 CDP prop 名映射为组件实际 prop 名（**只重命名，不变换值**）：
+
+```ts
+adapter: {
+  propMapping: {
+    loading: 'spinning',
+    value: 'selectedValue',
+  },
+},
+```
+
+---
+
+## mapProps（逃生舱）
+
+`propMapping` 不能做值变换、默认值、受控调谐等。adapter 在 props 层只剩 `mapProps` 这条路：
 
 ```ts
 adapter: {
@@ -96,29 +184,39 @@ adapter: {
 },
 ```
 
-注意：`mapProps` 是逃生舱。优先使用 wrapper 或 `propMapping`，避免把复杂逻辑藏在 manifest 中。
+`mapProps` 无类型约束、不可静态分析，是真正的逃生舱。需要在 props 层做超出"改名"的事情时，**优先回到 wrapper**，不要把复杂逻辑藏在 manifest 中。
 
 ---
 
 ## 自检
 
-- [ ] adapter 标准事件已经先在 `events` 声明。
-- [ ] adapter 自定义事件已经先在 `customEvents` 声明。
-- [ ] 每个 adapter event 都有 `propName`。
-- [ ] `propMapping` 没有和 wrapper 内转换重复冲突。
+- [ ] adapter 标准事件已经先在 `events` 声明，自定义事件已经先在 `customEvents` 声明。
+- [ ] adapter event 的 `propName` 与第三方组件实际回调 prop 名一致。
+- [ ] 需要 reshape payload 时使用 `transform`，类型对齐到 `EngineEventProtocol[K]`（标准事件）或 `payloadSchema`（自定义事件）。
+- [ ] 需要作用域的事件（List / Table 行项）使用 `toScope` 提取 `{ record, index }`。
+- [ ] `propMapping` 只用于纯重命名；值变换 / 默认值 / 受控转换走 wrapper。
+- [ ] `mapProps` 仅在没有 wrapper 控制权且必须保留 manifest 即真相时使用。
 - [ ] `validateManifest()` 没有 error。
 
 ---
 
 ## 常见错误
 
-### Adapter 引用了未声明事件
+### Adapter 引用了未声明的事件
+
+`adapter.events` / `adapter.customEvents` 中的 key，必须先在 manifest 的 `events` / `customEvents` 中声明，否则 `validateManifest()` 会报错。
+
+### 在 wrapper 里再 reshape 一次 payload
+
+如果已经用 `adapter.events.transform` 做了 payload 重塑，wrapper 不要再做一次——会出现两层映射叠加，或者 wrapper 输出的 payload 与 `EngineEventProtocol[K]` 形状不匹配。事件层适配只在一处做。
+
+### 用 `mapProps` 做改名
 
-先声明事件，再用 adapter 映射。否则 `validateManifest()` 会报错。
+改名用 `propMapping`；`mapProps` 留给真正需要值变换的场景。把改名塞进 `mapProps` 会让校验和阅读都变难。
 
-### 把复杂业务逻辑写进 mapProps
+### 把 `mapProps` 当主力
 
-`mapProps` 只适合轻量适配。复杂逻辑应该写在 React wrapper 中。
+`mapProps` 无类型、藏逻辑，应该是逃生舱而不是主力。出现复杂值变换、默认值或受控-非受控转换时，回到 wrapper，让组件作者用 TS 类型表达约束。
 
 ---