cdp-material-sdk 0.0.5 → 0.0.9

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

@@ -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` 状态联动。
 
 ---
 

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.5",
+  "version": "0.0.9",
   "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
-};