cdp-material-sdk 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cdp-material-sdk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# cdp-material-sdk
+
+`cdp-material-sdk` 是面向独立仓库外部作者的公开 SDK，用于编写真实 React 组件包并向宿主注册 `ComponentManifest`、`EngineComponentPackage` 与 `EngineComponentPlugin`。
+
+## 适用对象
+
+- 在独立仓库中开发第三方 React 组件包的作者
+- 需要基于稳定公开边界验证宿主集成的工程团队
+
+## 安装
+
+从 npm 安装最新版（推荐）：
+
+```bash
+npm install cdp-material-sdk@latest react react-dom
+```
+
+如需锁定到精确版本：
+
+```bash
+npm install cdp-material-sdk@<version> react react-dom
+```
+
+无 npm 访问时，可回退到 GitHub Release `.tgz`：
+
+```bash
+npm install https://github.com/GroovyKetchup/cdp-material-sdk/releases/download/v<version>/cdp-material-sdk-<version>.tgz
+```
+
+`react` 与 `react-dom` 是 peer dependency，需要由组件作者侧显式安装（建议 19.x）。
+
+## 推荐入口
+
+- `cdp-material-sdk/portable`
+  - 独立仓库作者默认入口
+  - 适合直接打入外部 bundle
+- `cdp-material-sdk/host-react`
+  - 仅用于需要与宿主共享 React runtime / Context identity 的 helper（如 `DataScope`、`useDataContainer`、`useDataContainerApi`）
+  - 不作为独立 bundle 的可移植保证范围
+- `cdp-material-sdk`
+  - 兼容根入口
+
+## 起步与组件开发指南
+
+完整的组件开发流程、能力 Recipe、模型 Reference 与 FAQ 见 [`docs/component-development`](./docs/component-development/README.md)。
+
+新接入作者建议按以下顺序阅读：
+
+1. [创建或接入组件库工程](./docs/component-development/getting-started/01-创建或接入组件库工程.md)
+2. [创建组件包并注册](./docs/component-development/getting-started/02-创建组件包并注册.md)
+3. [开发最小可运行组件](./docs/component-development/getting-started/03-开发最小可运行组件.md)
+4. [构建发布与宿主接入](./docs/component-development/getting-started/04-构建发布与宿主接入.md)
+5. [自检与排错](./docs/component-development/getting-started/05-自检与排错.md)
+
+按需启用的能力 Recipe（数据字段 / 数据容器 / 布局容器 / 事件 / 动作与状态 / 插槽 / 设计器元信息 / Adapter / Loading 等）见 [`docs/component-development/recipes`](./docs/component-development/recipes/)，模型与字段参考见 [`docs/component-development/reference`](./docs/component-development/reference/)。
+
+## 仓库维护与发布
+
+- `npm run release:check`：发布前自检（build + `npm pack --dry-run`）
+- `npm pack`：生成 `cdp-material-sdk-<version>.tgz` 用于离线分发
+- `.github/workflows/release.yml`：在打 `v*` tag 时自动 build、上传 GitHub Release artifact，并通过 `npm publish --provenance --access public` 发布到 npm（依赖仓库 secret `NPM_TOKEN`）
+
+## 边界说明
+
+- `public/external-packages/*` 在宿主仓库中仅承担 transport smoke demo 角色
+- 独立仓库作者应优先使用 `cdp-material-sdk/portable`
+- `cdp-material-sdk/host-react` 只适用于宿主 React runtime / Context 身份已统一的场景

package/dist/DataScope-B7ffH5qN.js

@@ -0,0 +1,106 @@
+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
+};

package/dist/components/core/types.d.ts

@@ -0,0 +1,16 @@
+import type { HTMLAttributes, RefAttributes } from 'react';
+/**
+ * 宿主注入根 DOM 属性时使用的标准路径。
+ * 外部作者组件应将 `slotProps.root` 透传到实际渲染的根节点，
+ * 以便宿主挂载 ref 和 DOM 属性。
+ */
+export declare const INJECT_PATH_SLOT_PROPS = "slotProps.root";
+/**
+ * 支持宿主注入 slot props 的基础属性结构。
+ */
+export interface BaseUIProps<RootDOM extends HTMLElement = HTMLElement> {
+    slotProps?: {
+        root?: HTMLAttributes<RootDOM> & RefAttributes<RootDOM>;
+        [key: string]: any;
+    };
+}

package/dist/components/data-scope/DataScope.d.ts

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react';
+import { type FieldState } from '../../context/DataScopeContext';
+export interface DataScopeProps {
+    /**
+     * 相对路径函数，决定子字段在数据容器值内的访问位置。
+     *
+     * 例：
+     * - Form: `(childId) => childId`               → `components.X.value.fieldName`
+     * - TableRow: `(childId) => `[${i}].${childId}`` → `components.X.value[0].fieldName`
+     *
+     * 默认值: `(childId) => childId`。
+     */
+    relativePath?: (childId: string) => string;
+    /**
+     * 数据实体（适用于会随数据重新 render 的组件，如 Table 行）。
+     * 与 `getRecord` 二选一。
+     */
+    record?: unknown;
+    /**
+     * 数据实体获取函数（适用于不会随数据重新 render 的组件，如 Form）。
+     * 与 `record` 二选一。
+     */
+    getRecord?: () => unknown;
+    /** 当前作用域索引（如表格行索引）。 */
+    index?: number;
+    /** 字段注册接口，由数据容器组件实现。 */
+    registerField?: (field: FieldState) => void;
+    unregisterField?: (id: string) => void;
+    children: ReactNode;
+}
+/**
+ * `DataScope` 用于建立数据作用域：
+ *
+ * 1. 路径解析 — 自动用最近一层 `DataContainerRuntimeContext` 的 `componentId`，
+ *    结合 `relativePath` 拼接出页面 store 绝对路径。
+ * 2. 数据实体注入 — 使用 Ref + Getter 模式，让 `record` 变化不会触发后代重渲染。
+ * 3. 索引注入 — 暴露当前作用域索引（排序/增删时合理触发更新）。
+ * 4. 字段状态注册 — 透传 `registerField` / `unregisterField`，便于容器聚合字段元信息。
+ *
+ * 设计约束：
+ * - `DataScope` 必须被包裹在数据容器组件内部，由数据容器经
+ *   `DataContainerRuntimeContext` 提供 `componentId`。组件作者无需也不应
+ *   显式传入 `componentId`。
+ */
+export declare const DataScope: ({ relativePath, record, getRecord: getRecordProp, index, registerField, unregisterField, children, }: DataScopeProps) => import("react/jsx-runtime").JSX.Element;

package/dist/constants/event.d.ts

@@ -0,0 +1,22 @@
+export declare const NOTIFY_TIMING: {
+    readonly BEFORE: "before";
+    readonly AFTER: "after";
+    readonly BOTH: "both";
+};
+export declare const NOTIFY_ERROR_STRATEGY: {
+    readonly IGNORE: "ignore";
+    readonly STOP: "stop";
+};
+export declare const ENGINE_EVENT_TYPE: {
+    readonly MOUNT: "mount";
+    readonly UNMOUNT: "unmount";
+    readonly CLICK: "click";
+    readonly FOCUS: "focus";
+    readonly BLUR: "blur";
+    readonly VALUE_CHANGE: "valueChange";
+    readonly ITEM_CLICK: "itemClick";
+    readonly ITEM_DOUBLE_CLICK: "itemDoubleClick";
+    readonly ITEM_RIGHT_CLICK: "itemRightClick";
+    readonly ITEM_LONG_PRESS: "itemLongPress";
+    readonly DATA_FETCH: "dataFetch";
+};

package/dist/context/DataContainerRuntimeContext.d.ts

@@ -0,0 +1,16 @@
+import type { RefObject } from 'react';
+/**
+ * 由宿主数据容器组件提供的运行时元数据。
+ *
+ * 它让 host-react 辅助函数能够推断当前生效的 `componentId`，并在
+ * 容器首次把值写入页面 store 之前，先暴露初始默认值。
+ */
+export interface DataContainerRuntimeContextValue<T = unknown> {
+    componentId: string;
+    initialDefaultValueRef: RefObject<T | undefined>;
+    hasInitializedRef: RefObject<boolean>;
+}
+/**
+ * 承载当前数据容器运行时元数据的 React context。
+ */
+export declare const DataContainerRuntimeContext: import("react").Context<DataContainerRuntimeContextValue<unknown> | null>;

package/dist/context/DataScopeContext.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 把 DataScope 内部使用的相对字段名解析为页面 store 绝对路径。
+ */
+export type PathResolver = (childId: string) => string;
+/**
+ * 用于在组件间传递的延迟作用域，避免在数据频繁变化时触发下游重渲染。
+ */
+export interface LazyScope {
+    /** 数据实体获取器。 */
+    getRecord: () => unknown;
+    /** 当前作用域索引（如表格行索引）。 */
+    index?: number;
+}
+/**
+ * 由数据字段组件向上注册的字段状态。
+ * 数据容器组件可以据此聚合字段元信息，例如校验态、读写态、显隐态等。
+ */
+export interface FieldState {
+    /** 字段唯一 ID，可能是组件 ID 或嵌套字段 fullPath。 */
+    id: string;
+    /** props 上的字段名。 */
+    name?: string;
+    /** props 上的字段标签。 */
+    label?: string;
+    hidden: boolean;
+    /** 组件内部 readOnly 状态，不包含 Form 全局状态。 */
+    readOnly: boolean;
+    /** 组件 props 上的 required 可能被动作修改，需要上报。 */
+    required?: boolean;
+}
+/**
+ * DataScope 提供给后代组件的上下文值。
+ */
+export interface DataScopeContextValue {
+    resolvePath: PathResolver;
+    inScope: boolean;
+    /**
+     * 数据实体获取函数，引用稳定，避免数据变化触发下游重渲染。
+     */
+    getRecord: () => unknown;
+    /** 当前作用域索引（如表格行索引）。 */
+    index?: number;
+    /** 字段注册接口，由数据容器组件提供。 */
+    registerField?: (field: FieldState) => void;
+    unregisterField?: (id: string) => void;
+}
+/**
+ * 当前数据作用域的 React context。
+ * 数据字段组件通过它解析字段路径、读取记录和注册字段状态。
+ */
+export declare const DataScopeContext: import("react").Context<DataScopeContextValue | null>;

package/dist/context/PageContext.d.ts

@@ -0,0 +1,26 @@
+import type { StoreApi } from 'zustand';
+/**
+ * 宿主页面状态树中每个组件对应的最小状态结构。
+ */
+export interface MaterialSdkComponentState {
+    value?: unknown;
+}
+/**
+ * `cdp-material-sdk/host-react` 辅助函数依赖的宿主页面 store 结构。
+ */
+export interface MaterialSdkPageStoreState {
+    components: Record<string, MaterialSdkComponentState>;
+    setComponentData: (componentId: string, data: unknown) => void;
+    resetComponentData: (componentId: string) => void;
+}
+export type MaterialSdkPageStoreApi = StoreApi<MaterialSdkPageStoreState>;
+/**
+ * 为 host-react 辅助函数暴露宿主页面 store 的 React context 值。
+ */
+export interface MaterialSdkPageContextValue {
+    store: MaterialSdkPageStoreApi | null;
+}
+/**
+ * 供 host-react 辅助函数读写组件数据的 React context。
+ */
+export declare const PageContext: import("react").Context<MaterialSdkPageContextValue | null>;

package/dist/hooks/useConcurrentLoading.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 面向重叠异步操作的引用计数式 loading 控制器。
+ */
+export interface useConcurrentLoadingReturn {
+    isLoading: boolean;
+    loadingText: string | undefined;
+    startLoading: (text?: string) => boolean;
+    stopLoading: () => boolean;
+    getLoading: () => boolean;
+    resetLoading: () => void;
+}
+/**
+ * 在多次并发 `startLoading` / `stopLoading` 调用之间维护 loading 状态，
+ * 并为当前活跃任务暴露共享的 loading 文案。
+ */
+export declare const useConcurrentLoading: () => useConcurrentLoadingReturn;

package/dist/hooks/useDataContainer.d.ts

@@ -0,0 +1,61 @@
+import { type DataContainerRuntimeContextValue } from '../context/DataContainerRuntimeContext';
+/**
+ * 面向数据容器的命令式访问接口。
+ * 可通过显式 `componentId`，或最近一层 `DataContainerRuntimeContext`
+ * 自动解析目标数据容器。
+ */
+export interface UseDataContainerApiResult<T = any> {
+    /**
+     * 获取当前数据容器的值。
+     */
+    getContainerData: () => T | undefined;
+    /**
+     * 设置数据容器的值。
+     */
+    setContainerData: (data: T) => void;
+    /**
+     * 将数据容器的值重置到初始状态。
+     */
+    resetContainerData: () => void;
+}
+/**
+ * 响应式的数据容器访问结果，并附带 `useDataContainerApi` 返回的
+ * 命令式辅助函数。
+ */
+export interface UseDataContainerResult<T = any> extends UseDataContainerApiResult<T> {
+    /**
+     * 当前数据容器的值。
+     */
+    containerData: T | undefined;
+}
+/**
+ * 判断主机 React 数据容器辅助函数当前是否应临时回退到运行时提供的
+ * 初始默认值。
+ *
+ * 只有当运行时上下文匹配，且容器尚未把首个值写入 store 时，才会触发
+ * 这一路径。
+ */
+export declare const shouldUseDataContainerRuntimeFallback: (componentId: string | undefined, runtimeContext: DataContainerRuntimeContextValue | null, currentValue: unknown) => boolean;
+/**
+ * 将 runtime fallback 与当前 store 值按 initComponentData 的同一套语义合并。
+ * 维护要求：任何初始值合并规则的调整都应复用 mergeComponentInitialValue，
+ * 避免 getContainerData()/containerData 与 initComponentData 的语义漂移。
+ */
+export declare const resolveDataContainerRuntimeValue: <T = any>(componentId: string | undefined, runtimeContext: DataContainerRuntimeContextValue | null, currentValue: T | undefined) => T | undefined;
+/**
+ * 提供对数据容器值的命令式读取、写入与重置能力。
+ * 如果未传入 `componentId`，则自动使用最近一层
+ * `DataContainerRuntimeContext` 中的目标组件。
+ */
+export declare function useDataContainerApi<T = any>(): UseDataContainerApiResult<T>;
+export declare function useDataContainerApi<T = any>(componentId: string): UseDataContainerApiResult<T>;
+export declare function useDataContainerApi<T = any>(componentId?: string | undefined): UseDataContainerApiResult<T>;
+/**
+ * 订阅数据容器值，并同时返回当前值与 `useDataContainerApi` 提供的
+ * 命令式辅助函数。
+ * 如果未传入 `componentId`，则自动使用最近一层
+ * `DataContainerRuntimeContext` 中的目标组件。
+ */
+export declare function useDataContainer<T = any>(): UseDataContainerResult<T>;
+export declare function useDataContainer<T = any>(componentId: string): UseDataContainerResult<T>;
+export declare function useDataContainer<T = any>(componentId?: string | undefined): UseDataContainerResult<T>;

package/dist/hooks/useDualLoading.d.ts

@@ -0,0 +1,22 @@
+import type { RefObject } from 'react';
+/**
+ * 将动作触发的 loading 与后台数据 loading 分离建模，
+ * 同时仍然对外暴露统一的组合 loading 状态。
+ */
+export interface UseDualLoadingReturn {
+    actionLoading: boolean;
+    actionLoadingText: string | undefined;
+    startActionLoading: (text?: string) => boolean;
+    stopActionLoading: () => boolean;
+    getActionLoading: () => boolean;
+    resetActionLoading: () => void;
+    dataLoading: boolean;
+    setDataLoading: (loading: boolean) => void;
+    isLoading: boolean;
+    isLoadingRef: RefObject<boolean>;
+}
+/**
+ * 将 `useConcurrentLoading` 与显式的数据 loading 标记组合起来，
+ * 让 UI 代码可以区分动作 loading 与后台数据获取。
+ */
+export declare const useDualLoading: () => UseDualLoadingReturn;

package/dist/host-react.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 宿主耦合的辅助导出，要求与宿主应用共享 React context 与运行时实例。
+ * 除非你明确需要接入 `PageContext` 或 `DataContainerRuntimeContext`，
+ * 否则应优先使用 `cdp-material-sdk/portable`。
+ */
+export { PageContext } from './context/PageContext';
+export type { MaterialSdkPageContextValue, MaterialSdkPageStoreApi, MaterialSdkPageStoreState } from './context/PageContext';
+export { DataContainerRuntimeContext } from './context/DataContainerRuntimeContext';
+export type { DataContainerRuntimeContextValue } from './context/DataContainerRuntimeContext';
+export { useDataContainer, useDataContainerApi, resolveDataContainerRuntimeValue, shouldUseDataContainerRuntimeFallback } from './hooks/useDataContainer';
+export type { UseDataContainerApiResult, UseDataContainerResult } from './hooks/useDataContainer';
+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';

package/dist/host-react.js

@@ -0,0 +1,11 @@
+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";
+export {
+  e as DataContainerRuntimeContext,
+  n as DataScope,
+  o as DataScopeContext,
+  s as PageContext,
+  i as resolveDataContainerRuntimeValue,
+  r as shouldUseDataContainerRuntimeFallback,
+  u as useDataContainer,
+  C as useDataContainerApi
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './portable';
+export * from './host-react';

package/dist/index.js

@@ -0,0 +1,42 @@
+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";
+export {
+  e as CATEGORY_LABELS,
+  t as COMPONENT_CATEGORY,
+  n as COMPONENT_STATE_KEY,
+  i as COMPONENT_TRAIT,
+  o as DYNAMIC_ENUM_KEY,
+  K as DataContainerRuntimeContext,
+  h as DataScope,
+  x as DataScopeContext,
+  E as ENGINE_EVENT_TYPE,
+  T as INJECT_PATH_ROOT,
+  _ as INJECT_PATH_SLOT_PROPS,
+  O as LOADING_PROP_NAME,
+  N as LOADING_STRATEGY,
+  R as LOADING_WRAPPER_TYPE,
+  r as NOTIFY_ERROR_STRATEGY,
+  A as NOTIFY_TIMING,
+  C as OptionItemSchema,
+  S as OptionsSchema,
+  V as PageContext,
+  l as RemoteOptionConfigSchema,
+  u as SLOT_KEY,
+  D as STANDARD_EVENT_KEYS,
+  m as diagnoseMissingActionImpls,
+  I as diagnoseMissingStateKeys,
+  P as isCustomEventKey,
+  d 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,
+  k as useDataContainerApi,
+  L as useDualLoading,
+  G as validateManifest,
+  v as validateManifests
+};

package/dist/plugin.d.ts

@@ -0,0 +1,45 @@
+import type { ComponentType } from 'react';
+import type { ComponentManifest } from './protocol/manifest';
+/**
+ * 将组件清单与其对应的 React 实现绑定在一起。
+ */
+export interface EngineComponentRegistration {
+    manifest: ComponentManifest;
+    component: ComponentType<any>;
+}
+/**
+ * 可选的版本兼容提示，供消费方判断当前 SDK 或引擎版本是否可接受。
+ */
+export interface EngineComponentPackageCompatibility {
+    sdkVersion?: string;
+    engineVersion?: string;
+}
+/**
+ * 由作者定义组件组成、可作为一个物料包统一分发的发布单元。
+ */
+export interface EngineComponentPackage {
+    id: string;
+    version: string;
+    components: EngineComponentRegistration[];
+    compatibility?: EngineComponentPackageCompatibility;
+}
+/**
+ * 插件在安装阶段可以调用的宿主侧回调。
+ */
+export interface EnginePluginAPI {
+    registerComponent: (manifest: ComponentManifest, component: ComponentType<any>) => void;
+    registerPackage: (pkg: EngineComponentPackage) => void;
+    unregisterPackage: (packageId: string) => void;
+}
+/**
+ * 可被宿主运行时消费的插件入口。
+ *
+ * 插件通常会在 `install` 中注册一个或多个组件，或直接注册整个
+ * `EngineComponentPackage`。
+ */
+export interface EngineComponentPlugin {
+    id: string;
+    version: string;
+    compatibility?: EngineComponentPackageCompatibility;
+    install: (api: EnginePluginAPI) => void | Promise<void>;
+}

package/dist/portable.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 面向独立分发物料包的公开 authoring 入口。
+ * 第三方组件与插件默认应优先从这里导入。
+ */
+export * from './plugin';
+export * from './hooks/useConcurrentLoading';
+export * from './hooks/useDualLoading';
+export * from './protocol/adapter';
+export * from './protocol/common-schemas';
+export * from './protocol/events';
+export * from './protocol/manifest';
+export * from './protocol/manifest-types';
+export * from './protocol/traits';
+export { ENGINE_EVENT_TYPE, NOTIFY_ERROR_STRATEGY, NOTIFY_TIMING } from './constants/event';
+export { COMPONENT_CATEGORY, CATEGORY_LABELS } from './types/category';
+export type { ComponentCategory } from './types/category';
+export { INJECT_PATH_SLOT_PROPS } from './components/core/types';
+export type { BaseUIProps } from './components/core/types';
+export { validateManifest, validateManifests, diagnoseMissingActionImpls, diagnoseMissingStateKeys, printValidationResult, printSingleValidationResult, } from './validation/validateManifest';
+export type { ValidationError, ValidationResult } from './validation/validateManifest';

package/dist/portable.js

@@ -0,0 +1,33 @@
+import { C as e, a as E, b as i, c as n, D as t, E as T, I as _, d as O, L as N, e as o, f as A, N as R, g as S, O as I, h as P, R as Y, S as d, i as l, j as C, k as M, l as m, m as r, n as L, o as g, p, q as G, u, r as D, v, s as K } from "./validateManifest-CYqjvQe_.js";
+export {
+  e as CATEGORY_LABELS,
+  E as COMPONENT_CATEGORY,
+  i as COMPONENT_STATE_KEY,
+  n as COMPONENT_TRAIT,
+  t as DYNAMIC_ENUM_KEY,
+  T as ENGINE_EVENT_TYPE,
+  _ as INJECT_PATH_ROOT,
+  O as INJECT_PATH_SLOT_PROPS,
+  N as LOADING_PROP_NAME,
+  o as LOADING_STRATEGY,
+  A as LOADING_WRAPPER_TYPE,
+  R as NOTIFY_ERROR_STRATEGY,
+  S as NOTIFY_TIMING,
+  I as OptionItemSchema,
+  P as OptionsSchema,
+  Y as RemoteOptionConfigSchema,
+  d as SLOT_KEY,
+  l as STANDARD_EVENT_KEYS,
+  C as diagnoseMissingActionImpls,
+  M as diagnoseMissingStateKeys,
+  m as isCustomEventKey,
+  r as isStandardEventKey,
+  L as normalizeAdapterEvents,
+  g as normalizeManifestEvents,
+  p as printSingleValidationResult,
+  G as printValidationResult,
+  u as useConcurrentLoading,
+  D as useDualLoading,
+  v as validateManifest,
+  K as validateManifests
+};