cdp-material-sdk 0.0.5

package/dist/validateManifest-CYqjvQe_.js

@@ -0,0 +1,355 @@
+import { useState as m, useRef as A, useEffect as h, useCallback as u, useMemo as g } from "react";
+const S = () => {
+  const [t, e] = m(0), [o, n] = m(void 0), c = A(0);
+  h(() => {
+    c.current = t;
+  }, [t]);
+  const a = u(() => c.current > 0, []), s = u((l) => (e((y) => y + 1), l && n(l), a()), [a]), p = u(() => (e((l) => {
+    const y = Math.max(0, l - 1);
+    return y === 0 && n(void 0), y;
+  }), a()), [a]), r = u(() => {
+    e(0), n(void 0);
+  }, []);
+  return g(() => ({
+    isLoading: t > 0,
+    loadingText: o,
+    startLoading: s,
+    stopLoading: p,
+    getLoading: a,
+    resetLoading: r
+  }), [a, t, o, r, s, p]);
+}, V = () => {
+  const {
+    isLoading: t,
+    loadingText: e,
+    startLoading: o,
+    stopLoading: n,
+    getLoading: c,
+    resetLoading: a
+  } = S(), [s, p] = m(!1), r = g(() => t || s, [t, s]), l = A(!1);
+  return h(() => {
+    l.current = r;
+  }, [r]), g(() => ({
+    actionLoading: t,
+    actionLoadingText: e,
+    startActionLoading: o,
+    stopActionLoading: n,
+    getActionLoading: c,
+    resetActionLoading: a,
+    dataLoading: s,
+    setDataLoading: p,
+    isLoading: r,
+    isLoadingRef: l
+  }), [
+    t,
+    e,
+    s,
+    c,
+    r,
+    a,
+    o,
+    n
+  ]);
+};
+function O(t) {
+  if (!t)
+    return [];
+  const e = [];
+  for (const [o, n] of Object.entries(t))
+    n && e.push({
+      type: o,
+      ...n
+    });
+  return e;
+}
+function _(t) {
+  if (!t)
+    return [];
+  const e = [];
+  for (const [o, n] of Object.entries(t))
+    n && e.push({
+      type: o,
+      ...n
+    });
+  return e;
+}
+function v(t) {
+  const e = O(t?.events), o = _(t?.customEvents);
+  return {
+    standard: e,
+    custom: o,
+    all: [...e, ...o],
+    allKeys: [...e.map((n) => n.type), ...o.map((n) => n.type)]
+  };
+}
+const $ = {
+  type: "object",
+  properties: {
+    label: { type: "string", title: "显示名称" },
+    value: { type: "string", title: "选项值" },
+    disabled: { type: "boolean", title: "是否禁用" }
+  }
+}, x = {
+  type: "array",
+  title: "选项列表",
+  items: $
+}, J = {
+  type: "object",
+  title: "远程选项配置",
+  properties: {
+    panelCode: { type: "string", title: "面板代码" },
+    fieldName: { type: "string", title: "字段名称" },
+    condition: {
+      type: "object",
+      title: "查询条件",
+      description: "声明式查询条件，支持表达式绑定。",
+      additionalProperties: { type: "string" }
+    }
+  }
+}, W = {
+  BEFORE: "before",
+  AFTER: "after",
+  BOTH: "both"
+}, q = {
+  IGNORE: "ignore",
+  STOP: "stop"
+}, C = {
+  MOUNT: "mount",
+  UNMOUNT: "unmount",
+  CLICK: "click",
+  FOCUS: "focus",
+  BLUR: "blur",
+  VALUE_CHANGE: "valueChange",
+  ITEM_CLICK: "itemClick",
+  ITEM_DOUBLE_CLICK: "itemDoubleClick",
+  ITEM_RIGHT_CLICK: "itemRightClick",
+  ITEM_LONG_PRESS: "itemLongPress",
+  DATA_FETCH: "dataFetch"
+}, I = Object.values(C), L = new Set(I), R = /^[^:\s]+:[^:\s]+$/;
+function f(t) {
+  return L.has(t);
+}
+function E(t) {
+  return R.test(t) && !L.has(t);
+}
+const Q = "x-dynamic-enum", X = "x-slot", P = "$root", Z = "__state";
+function D(t) {
+  if (!t)
+    return [];
+  const e = [];
+  for (const [o, n] of Object.entries(t))
+    n && e.push({
+      type: o,
+      ...n
+    });
+  return e;
+}
+function M(t) {
+  if (!t)
+    return [];
+  const e = [];
+  for (const [o, n] of Object.entries(t))
+    n && e.push({
+      type: o,
+      ...n
+    });
+  return e;
+}
+function w(t) {
+  const e = D(t?.events), o = M(t?.customEvents);
+  return {
+    standard: e,
+    custom: o,
+    all: [...e, ...o],
+    allKeys: [...e.map((n) => n.type), ...o.map((n) => n.type)]
+  };
+}
+const tt = {
+  NATIVE: "native",
+  WRAPPER: "wrapper",
+  NONE: "none"
+}, et = {
+  SPIN: "spin",
+  SKELETON: "skeleton",
+  WAVE: "wave"
+}, nt = "loading", T = {
+  DATA_FIELD: "Data.Field",
+  DATA_CONTAINER: "Data.Container",
+  LAYOUT_CONTAINER: "Layout.Container",
+  INTERACTION_CLICKABLE: "Interaction.Clickable"
+}, d = {
+  GENERAL: "General",
+  FLOAT: "Float",
+  LAYOUT: "Layout",
+  DATA_ENTRY: "DataEntry",
+  DATA_DISPLAY: "DataDisplay",
+  CHART: "Chart",
+  BUSINESS: "Business",
+  SHELL: "Shell",
+  PAGE: "Page",
+  DEV: "Dev",
+  HTML_TEMPLATE: "HtmlTemplate"
+}, ot = {
+  [d.GENERAL]: "通用",
+  [d.FLOAT]: "悬浮",
+  [d.LAYOUT]: "布局",
+  [d.DATA_ENTRY]: "录入",
+  [d.DATA_DISPLAY]: "数据展示",
+  [d.CHART]: "图表",
+  [d.BUSINESS]: "业务组件",
+  [d.SHELL]: "外壳",
+  [d.PAGE]: "页面",
+  [d.DEV]: "调试",
+  [d.HTML_TEMPLATE]: "HTML 模板"
+}, b = "slotProps.root", Y = [T.DATA_FIELD, T.DATA_CONTAINER], j = [P, b], N = ["string", "number", "boolean", "array", "object", "integer", "null"];
+function i(t, e, o, n, c) {
+  t.push({ type: e, field: o, message: n, severity: c });
+}
+function K(t, e, o) {
+  const n = t.type;
+  if (!t.meta)
+    return i(e, n, "meta", "meta 字段是必填的", "error"), !1;
+  if (t.meta.title || i(e, n, "meta.title", "title 是必填的", "error"), t.meta.category ? Object.values(d).includes(t.meta.category) || i(e, n, "meta.category", `无效的 category: ${t.meta.category}`, "error") : i(e, n, "meta.category", "category 是必填的", "error"), t.meta.valueSchema) {
+    const a = t.meta.valueSchema.type;
+    a && typeof a == "string" && !N.includes(a) && i(e, n, "meta.valueSchema.type", `无效的 valueSchema type: ${a}`, "error");
+  }
+  return t.traits?.some((a) => Y.includes(a)) && !t.meta.valueSchema && i(
+    o,
+    n,
+    "meta.valueSchema",
+    "声明了 DATA_FIELD 或 DATA_CONTAINER trait 但缺少 valueSchema——建议补充以供设计器和 AI 工具推断数据类型",
+    "warning"
+  ), !0;
+}
+function G(t, e, o) {
+  const n = t.type, c = w(t), a = new Set(c.standard.map((p) => p.type)), s = new Set(c.custom.map((p) => p.type));
+  if (c.all.length > 0 && (c.standard.forEach((p, r) => {
+    p.type || i(e, n, `events[${r}].type`, "事件类型不能为空", "error"), p.type && !f(p.type) && i(e, n, `events[${r}].type`, `标准事件类型必须属于 EngineEventProtocol: ${p.type}`, "error");
+  }), c.custom.forEach((p) => {
+    p.type || i(e, n, "customEvents.type", "自定义事件类型不能为空", "error"), p.type && !E(p.type) && i(e, n, `customEvents.${p.type}`, `自定义事件类型必须是 namespaced 形态: ${p.type}`, "error"), p.payloadSchema || i(e, n, `customEvents.${p.type}.payloadSchema`, "自定义事件必须声明 payloadSchema", "error");
+  })), t.adapter) {
+    const p = v(t.adapter);
+    p.standard.forEach((r, l) => {
+      r.type || i(e, n, `adapter.events[${l}].type`, "Adapter 事件类型不能为空", "error"), r.type && !f(r.type) && i(e, n, `adapter.events[${l}].type`, `Adapter 标准事件类型必须属于 EngineEventProtocol: ${r.type}`, "error"), r.type && f(r.type) && !a.has(r.type) && i(e, n, `adapter.events[${l}].type`, `Adapter 标准事件必须先在 manifest.events 中声明: ${r.type}`, "error"), r.propName || i(e, n, `adapter.events[${l}].propName`, "Adapter propName 不能为空", "error");
+    }), p.custom.forEach((r) => {
+      r.type || i(e, n, "adapter.customEvents.type", "Adapter 自定义事件类型不能为空", "error"), r.type && !E(r.type) && i(e, n, `adapter.customEvents.${r.type}`, `Adapter 自定义事件类型必须是 namespaced 形态: ${r.type}`, "error"), r.type && E(r.type) && !s.has(r.type) && i(e, n, `adapter.customEvents.${r.type}`, `Adapter 自定义事件必须先在 manifest.customEvents 中声明: ${r.type}`, "error"), r.propName || i(e, n, `adapter.customEvents.${r.type}.propName`, "Adapter customEvents propName 不能为空", "error");
+    });
+  }
+}
+function H(t, e, o) {
+  const n = t.type, c = t.actions;
+  if (c)
+    for (const [a, s] of Object.entries(c))
+      s && (s.title || i(e, n, `actions.${a}.title`, `动作 "${a}" 缺少 title`, "error"), s.returns || i(o, n, `actions.${a}.returns`, `动作 "${a}" 未声明 returns schema，建议补充`, "warning"), s.params && s.params.type !== "object" && i(e, n, `actions.${a}.params.type`, '动作参数 schema 的 type 必须为 "object"', "error"));
+}
+function U(t, e, o) {
+  const n = t.type, c = t.engine?.render?.injection?.rootPath;
+  c ? typeof c == "string" && !j.includes(c) && i(
+    o,
+    n,
+    "engine.render.injection.rootPath",
+    `rootPath "${c}"：请确保组件内部将该路径对应的 props 透传到根 DOM 节点。若已按规则实现可忽略此提示`,
+    "warning"
+  ) : i(
+    o,
+    n,
+    "engine.render.injection.rootPath",
+    "未声明 rootPath——引擎将在组件外层套 <div> 兜底。推荐声明 INJECT_PATH_SLOT_PROPS 并在组件根节点透传 slotProps.root",
+    "warning"
+  );
+}
+function k(t, e, o) {
+  const n = t.type, c = t.slots;
+  if (c)
+    for (const [a, s] of Object.entries(c))
+      s && (s.title || i(e, n, `slots.${a}.title`, `插槽 "${a}" 缺少 title`, "error"), s.dynamic && (s.dynamicSource || i(e, n, `slots.${a}.dynamicSource`, `动态插槽 "${a}" 缺少 dynamicSource`, "error"), s.dynamicKey || i(e, n, `slots.${a}.dynamicKey`, `动态插槽 "${a}" 缺少 dynamicKey`, "error")), s.scoped && !s.scopeDescription && i(
+        o,
+        n,
+        `slots.${a}.scopeDescription`,
+        `作用域插槽 "${a}" 建议声明 scopeDescription，帮助设计器用户理解作用域数据`,
+        "warning"
+      ), s.allowedChildren !== void 0 && !Array.isArray(s.allowedChildren) && i(e, n, `slots.${a}.allowedChildren`, `插槽 "${a}" 的 allowedChildren 必须是字符串数组`, "error"));
+}
+function F(t, e, o) {
+  const n = t.type, c = t.state;
+  if (c)
+    for (const [a, s] of Object.entries(c))
+      s && (s.title || i(e, n, `state.${a}.title`, `状态 "${a}" 缺少 title`, "error"), s.schema ? s.schema.type && typeof s.schema.type == "string" && !N.includes(s.schema.type) && i(e, n, `state.${a}.schema.type`, `状态 "${a}" 的 schema.type 无效: ${s.schema.type}`, "error") : i(e, n, `state.${a}.schema`, `状态 "${a}" 缺少 schema`, "error"));
+}
+function z(t) {
+  const e = [], o = [];
+  return t.type || i(e, t.type || "Unknown", "type", "type 字段是必填的", "error"), K(t, e, o) ? (G(t, e), H(t, e, o), F(t, e), k(t, e, o), U(t, e, o), {
+    valid: e.length === 0,
+    errors: e,
+    warnings: o
+  }) : { valid: !1, errors: e, warnings: o };
+}
+function at(t) {
+  const e = [], o = [];
+  for (const n of t) {
+    const c = z(n);
+    e.push(...c.errors), o.push(...c.warnings);
+  }
+  return {
+    valid: e.length === 0,
+    errors: e,
+    warnings: o
+  };
+}
+function st(t, e) {
+  return !t || !e ? [] : t.filter((o) => typeof e[o] != "function");
+}
+function rt(t, e) {
+  return !t?.state || !e ? [] : Object.keys(t.state).filter((o) => !(o in e));
+}
+function it(t) {
+  t.valid ? console.log("✅ 所有 Manifest 验证通过") : console.error(`❌ 发现 ${t.errors.length} 个错误`), t.errors.length > 0 && (console.error(`
+错误列表:`), t.errors.forEach((e) => {
+    console.error(`  ❌ [${e.type}] ${e.field}: ${e.message}`);
+  })), t.warnings.length > 0 && (console.warn(`
+⚠️  发现 ${t.warnings.length} 个警告`), t.warnings.forEach((e) => {
+    console.warn(`  ⚠️  [${e.type}] ${e.field}: ${e.message}`);
+  }));
+}
+function ct(t, e = "[Registry]") {
+  if (!t.valid && t.errors.length > 0) {
+    const o = t.errors[0]?.type || "Unknown";
+    console.error(`${e} ❌ Manifest validation failed for '${o}':`), t.errors.forEach((n) => console.error(`  - ${n.field}: ${n.message}`));
+  }
+  if (t.warnings.length > 0) {
+    const o = t.warnings[0]?.type || "Unknown";
+    console.warn(`${e} ⚠️  Manifest warnings for '${o}':`), t.warnings.forEach((n) => console.warn(`  - ${n.field}: ${n.message}`));
+  }
+}
+export {
+  ot as C,
+  Q as D,
+  C as E,
+  P as I,
+  nt as L,
+  q as N,
+  $ as O,
+  J as R,
+  X as S,
+  d as a,
+  Z as b,
+  T as c,
+  b as d,
+  tt as e,
+  et as f,
+  W as g,
+  x as h,
+  I as i,
+  st as j,
+  rt as k,
+  E as l,
+  f as m,
+  v as n,
+  w as o,
+  ct as p,
+  it as q,
+  V as r,
+  at as s,
+  S as u,
+  z as v
+};

package/dist/validation/validateManifest.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Manifest 校验工具
+ *
+ * 纯函数，零宿主依赖。第三方组件开发者可直接使用：
+ *
+ * ```ts
+ * import { validateManifest } from 'cdp-material-sdk/portable';
+ * const result = validateManifest(myManifest);
+ * ```
+ */
+import type { ComponentManifest } from '../protocol/manifest';
+export interface ValidationError {
+    type: string;
+    field: string;
+    message: string;
+    severity: 'error' | 'warning';
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+/**
+ * 验证单个 ComponentManifest 的完整性和正确性。
+ *
+ * 校验范围：
+ * - 必填字段（type, meta, meta.title, meta.category）
+ * - events / customEvents 合法性
+ * - adapter 与 events 对齐
+ * - actions 声明完整性（title 必填，returns 建议）
+ * - state 声明完整性（title + schema 必填）
+ * - slots 声明完整性（title 必填，动态/作用域规则）
+ * - engine.render.injection.rootPath 声明提示
+ */
+export declare function validateManifest(manifest: ComponentManifest): ValidationResult;
+/**
+ * 批量验证多个 Manifest
+ */
+export declare function validateManifests(manifests: ComponentManifest[]): ValidationResult;
+/**
+ * 比对 manifest.actions 中组件自声明的 action keys 与 ref 实际暴露的方法。
+ * 返回"声明了但未实现"的 action 名称列表。
+ *
+ * 用于宿主 DEV 模式下的挂载时诊断。
+ */
+export declare function diagnoseMissingActionImpls(componentActionKeys: readonly string[] | undefined, refValue: Record<string, any> | null | undefined): string[];
+/**
+ * 比对 manifest.state 声明的 key 与 __state 实际暴露的 key。
+ * 返回"声明了但未暴露"的 state 名称列表。
+ */
+export declare function diagnoseMissingStateKeys(manifest: Pick<ComponentManifest, 'state'> | undefined, stateValue: Record<string, any> | null | undefined): string[];
+/**
+ * 打印验证结果到控制台
+ */
+export declare function printValidationResult(result: ValidationResult): void;
+/**
+ * 打印单个组件的验证结果（简洁格式）
+ */
+export declare function printSingleValidationResult(result: ValidationResult, prefix?: string): void;

package/docs/component-development/FAQ.md

@@ -0,0 +1,203 @@
+---
+type: faq
+capability: troubleshooting
+related:
+  - README.md
+  - getting-started/05-自检与排错.md
+  - reference/validateManifest校验规则.md
+---
+# FAQ
+
+本文收集 CDP 组件开发中的高频问题。
+
+---
+
+## 我是第三方组件作者，应该先看哪份文档？
+
+先看 [README](./README.md)。它会按你的场景分流。
+
+第一次接入时，按 `getting-started/` 的顺序阅读。已有组件包新增组件时，直接看 [开发最小可运行组件](./getting-started/03-开发最小可运行组件.md) 和对应 Recipe。
+
+---
+
+## 这套文档应该怎么读？
+
+组件开发现在统一按任务组织：
+
+- `getting-started/`：完成最小接入闭环。
+- `recipes/`：按需启用数据、事件、动作、状态、插槽等能力。
+- `reference/`：查字段、查模型、查校验规则。
+- `FAQ.md`：解决常见问题。
+
+第一次接入时，建议按 `getting-started/` 顺序阅读；已有组件包新增组件时，直接查对应 Recipe 和 Reference。
+
+---
+
+## 事件、动作、状态都必须声明吗？
+
+不是。
+
+| 能力 | 是否必需 | 什么时候需要 |
+|------|----------|--------------|
+| events | 否 | 组件要通知宿主 |
+| actions | 否 | 宿主要命令式调用组件 |
+| state | 否 | 外部表达式要读取组件内部状态 |
+| slots | 否 | 组件要承载子内容 |
+| traits | 否 | 组件具备数据、布局或点击语义时声明 |
+
+最小组件只需要 React 组件、`ComponentManifest`、组件包注册和自检。
+
+---
+
+## 我已经有组件包，只想新增组件，需要看工程搭建吗？
+
+不需要。
+
+建议阅读：
+
+1. [开发最小可运行组件](./getting-started/03-开发最小可运行组件.md)
+2. [创建组件包并注册](./getting-started/02-创建组件包并注册.md) 的「往已有组件包新增组件」小节
+3. 对应能力 Recipe
+4. [自检与排错](./getting-started/05-自检与排错.md)
+
+---
+
+## 我包装 Ant Design 或 ECharts 组件，文档覆盖吗？
+
+覆盖。请从 [接入第三方 React 组件库](./recipes/接入第三方React组件库.md) 开始。
+
+推荐方式是写一层 CDP wrapper，而不是直接裸注册第三方组件。
+
+---
+
+## 组件不是 React 写的怎么办？
+
+当前 CDP 组件 runtime 是 React。非 React 组件需要自行提供 React wrapper。
+
+例如 Web Component：
+
+```tsx
+import { forwardRef } from 'react';
+import type { BaseUIProps } from 'cdp-material-sdk/portable';
+
+export const MyWebComponentWrapper = forwardRef<HTMLElement, BaseUIProps>((props, ref) => {
+  const { slotProps } = props;
+  return <my-web-component {...slotProps?.root} ref={ref} />;
+});
+```
+
+---
+
+## `rootPath` 不声明可以吗？
+
+可以。宿主会外层 `<div>` 兜底。
+
+但正式组件建议显式声明 `engine.render.injection.rootPath`，并把对应 props 透传到真实 DOM 根节点。
+
+推荐写法：
+
+```ts
+import { INJECT_PATH_SLOT_PROPS } from 'cdp-material-sdk/portable';
+
+engine: {
+  render: {
+    injection: {
+      rootPath: INJECT_PATH_SLOT_PROPS,
+    },
+  },
+},
+```
+
+---
+
+## 自定义 rootPath 出现 warning，是不是一定有问题？
+
+不是。
+
+自定义 rootPath 是合法选择。warning 的含义是提醒作者确认该路径上的 props 已经透传到真实 DOM。如果已经按规则实现，可以忽略。
+
+---
+
+## Loading 应该用 native、wrapper 还是 none？
+
+| 场景 | 推荐 |
+|------|------|
+| 组件已有 loading prop，且能阻断交互 | `native` |
+| loading prop 名不是 `loading` | `native + propName` |
+| 组件没有 loading prop，但可以整体遮罩 | `wrapper` |
+| 组件内部 loading 很复杂 | `none` |
+
+注意：正确路径是 `engine.render.loading`，不是 `engine.loading`。
+
+---
+
+## 为什么 native 模式下仍然能点击？
+
+这是组件实现问题。`native` 模式只负责注入 loading prop；组件自己必须在 loading 为 true 时阻断用户交互。
+
+---
+
+## DATA_FIELD 和 DATA_CONTAINER 有什么区别？
+
+| Trait | 作用 |
+|-------|------|
+| `DATA_FIELD` | 单个数据字段，接收 `value` 并调用 `onChange` |
+| `DATA_CONTAINER` | 数据容器，管理子字段的数据作用域 |
+
+输入框、选择器用 `DATA_FIELD`。Form、Table、List 这类容器用 `DATA_CONTAINER`。
+
+---
+
+## 声明了 DATA_FIELD 但没有 valueSchema 可以吗？
+
+可以运行，但不推荐。`validateManifest()` 会 warning。
+
+`valueSchema` 能帮助设计器、表达式和 AI 工具理解组件 value 类型。
+
+---
+
+## Action 声明了但调用失败，怎么排查？
+
+检查：
+
+1. `manifest.actions` 中的 key 是否和 ref 方法名一致。
+2. 组件是否使用 `forwardRef`。
+3. 组件是否通过 `useImperativeHandle` 暴露方法。
+4. 使用 `diagnoseMissingActionImpls()` 做运行时诊断。
+
+---
+
+## State 读不到，怎么排查？
+
+检查：
+
+1. `manifest.state` 是否声明了对应 key。
+2. 组件是否通过 `COMPONENT_STATE_KEY` 暴露状态。
+3. 状态值是否加入 `useImperativeHandle` deps。
+4. 使用 `diagnoseMissingStateKeys()` 做运行时诊断。
+
+---
+
+## 可以直接导入宿主内部模块吗？
+
+不可以。
+
+第三方作者只应依赖 `cdp-material-sdk/portable`，必要时使用 `cdp-material-sdk/host-react`。宿主内部模块不作为第三方兼容契约。
+
+---
+
+## `cdp-material-sdk/host-react` 什么时候能用？
+
+只有当外部 bundle 与宿主共享同一份 React runtime 和 Context 身份时才使用。
+
+如果无法确认，请不要使用 `host-react`，优先通过 props、events、actions 与宿主交互。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 关联文档：[README](./README.md)
+- 自检与排错：[05-自检与排错](./getting-started/05-自检与排错.md)
+- 校验规则：[validateManifest校验规则](./reference/validateManifest校验规则.md)