@pactor-app/core 0.1.0 → 1.0.0

package/dist/index.cjs

@@ -22,10 +22,32 @@ var index_exports = {};
 __export(index_exports, {
   RUNTIME_SCOPES: () => RUNTIME_SCOPES,
   Registry: () => Registry,
-  createI18nContext: () => createI18nContext
+  createI18nContext: () => createI18nContext,
+  isDslSourceRef: () => isDslSourceRef,
+  resolveRootNodes: () => resolveRootNodes
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/node.ts
+function isDslSourceRef(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const source = value.source;
+  return typeof source === "object" && source !== null && (source.type === "service" || source.type === "http");
+}
+
+// src/document.ts
+function resolveRootNodes(pageDsl) {
+  if (pageDsl.body) {
+    return [pageDsl.body];
+  }
+  if (Array.isArray(pageDsl.children)) {
+    return pageDsl.children;
+  }
+  return [];
+}
+
 // src/scope.ts
 var RUNTIME_SCOPES = [
   "global",
@@ -123,5 +145,7 @@ function createI18nContext(options = {}) {
 0 && (module.exports = {
   RUNTIME_SCOPES,
   Registry,
-  createI18nContext
+  createI18nContext,
+  isDslSourceRef,
+  resolveRootNodes
 });

package/dist/index.d.cts

@@ -38,18 +38,60 @@ interface ActionConfig {
 }
 /** 事件映射：事件名 → 单个或多个动作 */
 type EventMap = Record<string, ActionConfig | ActionConfig[]>;
-/** UI DSL 树基础节点 */
-interface DslNode {
+/**
+ * 动态 DSL 引用（设计文档：DSL 各位置支持远端加载）：
+ * `source` 为二选一形态——`service`（经 ServiceRegistry 调用）或
+ * `http`（经 HttpAdapter 请求），返回 DSL 内容（PageDsl / DslNode / DslNode[]）；
+ * `params` 值可含表达式字符串，按**首次解析时**的作用域求值一次（不做联动重载）。
+ * `placeholder` 为解析期间渲染的占位子树（缺省渲染空）。
+ */
+interface DslSourceRef {
+    source: {
+        type: 'service';
+        service: string;
+        params?: Record<string, unknown>;
+    } | {
+        type: 'http';
+        request: {
+            method?: string;
+            url: string;
+            params?: Record<string, unknown>;
+            headers?: Record<string, string>;
+        };
+    };
+    placeholder?: DslNode;
+}
+/** DslSourceRef 类型守卫 */
+declare function isDslSourceRef(value: unknown): value is DslSourceRef;
+/** 子树元素：内联节点或动态引用（children 数组中可混排） */
+type DslChildrenItem = DslNode | DslSourceRef;
+/** 子树声明：内联数组（元素可为节点或动态引用混排），或整体远端动态引用 */
+type DslChildren = DslChildrenItem[] | DslSourceRef;
+/** UI DSL 树基础节点共有字段 */
+interface DslNodeBase {
     id?: string;
-    /** 组件类型，对应 Component Registry 中的注册名 */
-    type: string;
     props?: Record<string, unknown>;
-    children?: DslNode[];
+    children?: DslChildren;
     events?: EventMap;
     permission?: PermissionConfig;
     /** 条件渲染 */
     when?: ConditionConfig;
 }
+/** 组件节点：`type` 对应 Component Registry 中的注册名 */
+interface DslComponentNode extends DslNodeBase {
+    type: string;
+    component?: undefined;
+}
+/**
+ * 引用节点：`component` 引用页面级命名组件（PageDsl.components）的 key，
+ * 渲染该子树；引用处的 props / events 覆盖定义处同名字段
+ */
+interface DslReferenceNode extends DslNodeBase {
+    component: string;
+    type?: undefined;
+}
+/** UI DSL 树节点：组件节点（type）与引用节点（component）二选一 */
+type DslNode = DslComponentNode | DslReferenceNode;
 
 /**
  * DSL 文档结构（设计文档第 9、10、37 节）。
@@ -67,6 +109,10 @@ interface RequiresConfig {
 interface PageMeta {
     id: string;
     title?: string;
+    /** 页面名称（标识用途，区别于展示的 title） */
+    name?: string;
+    /** 页面描述 */
+    description?: string;
     /** 页面类型 / Page Pattern，如 "list"、"detail"、"form" */
     type?: string;
     permission?: PermissionConfig;
@@ -81,6 +127,15 @@ interface DataSourceConfig {
     autoLoad?: boolean;
     /** 调用参数，值可含表达式字符串 */
     params?: Record<string, unknown>;
+    /**
+     * 选项字段映射（该数据源用作选项源时声明）：加载结果为数组时，
+     * 每项归一化出 `{ label, value, disabled }` 键（原字段保留），
+     * 供 Select 等组件经 `${data.x}` 直接绑定
+     */
+    valueField?: string;
+    labelField?: string;
+    /** 选项禁用标记字段：数组项中该字段为真值时选项禁用 */
+    disabledField?: string;
     /** type 为 http 时的请求描述 */
     request?: {
         method?: string;
@@ -107,13 +162,47 @@ interface PageDsl {
     dsl: DslVersion;
     requires?: RequiresConfig;
     page: PageMeta;
+    /** 页面扩展元数据（自由键值，如 version / author / 业务自定义标记），Runtime 不消费，仅供宿主与工具链读取 */
+    meta?: Record<string, unknown>;
     /** 页面初始状态 */
     state?: Record<string, unknown>;
     dataSources?: Record<string, DataSourceConfig>;
+    /**
+     * 页面级命名动作定义：动作名 → 单个动作或动作数组，
+     * 供事件中的 `call` 动作按名引用复用（以调用方作用域执行，
+     * `${row}` / `${event}` 等局部作用域原样可用）
+     */
+    actions?: Record<string, ActionConfig | ActionConfig[]>;
+    /**
+     * 页面级命名组件定义（设计文档第 50 节 Fragment 的页面局部形态）：
+     * 组件名 → DslNode 子树（或 DslSourceRef 动态引用，引用处渲染时惰性解析），
+     * body 中以 `{ component: '名称' }` 引用节点复用，防止 DSL 嵌套过深；
+     * 以引用处作用域渲染
+     */
+    components?: Record<string, DslNode | DslSourceRef>;
     lifecycle?: LifecycleConfig;
-    /** UI 树根 */
+    /**
+     * UI 树根（单个 DslNode）。
+     * 与根级 `children` 为两种等价声明形态：`body` 存在时优先使用 `body`；
+     * `body` 缺失且 `children` 存在时以根级 `children` 作为 UI 树
+     * （隐式片段根，无需 Page 等包装节点，DSL 可描述页面局部）；
+     * 两者均缺失时按空树处理。读取入口见 `resolveRootNodes`
+     */
     body?: DslNode;
+    /**
+     * UI 树根（`body` 缺失时生效）：数组形态（元素可为 DslNode 或
+     * DslSourceRef 混排）或整体动态引用
+     */
+    children?: DslChildren;
 }
+/**
+ * 读取 Page DSL 的 UI 树根元素列表（官方入口）：
+ * `body` 存在 → `[body]`；根级 `children` 为数组 → 原样返回
+ * （元素可为 DslNode 或 DslSourceRef）；根级 `children` 为整体
+ * DslSourceRef 或缺失 → 空数组（整体引用形态由渲染入口经
+ * DslSourceBoundary 异步解析）
+ */
+declare function resolveRootNodes(pageDsl: PageDsl): DslChildrenItem[];
 /** Fragment DSL（第 50 节）：可复用的 UI 片段 */
 interface FragmentDsl {
     dsl: DslVersion;
@@ -214,4 +303,4 @@ interface CreateI18nOptions {
  */
 declare function createI18nContext(options?: CreateI18nOptions): I18nContext;
 
-export { type ActionConfig, type ApplicationDsl, type ConditionConfig, type CreateI18nOptions, type DataSourceConfig, type DataSourceType, type DslNode, type DslVersion, type EventMap, type ExpressionString, type FragmentDsl, type I18nContext, type I18nMessages, type I18nParams, type LifecycleConfig, type LifecycleEventName, type Locale, type PageDsl, type PageMeta, type PermissionConfig, type PermissionDeniedStrategy, RUNTIME_SCOPES, Registry, type RequiresConfig, type RuntimeScope, createI18nContext };
+export { type ActionConfig, type ApplicationDsl, type ConditionConfig, type CreateI18nOptions, type DataSourceConfig, type DataSourceType, type DslChildren, type DslChildrenItem, type DslComponentNode, type DslNode, type DslNodeBase, type DslReferenceNode, type DslSourceRef, type DslVersion, type EventMap, type ExpressionString, type FragmentDsl, type I18nContext, type I18nMessages, type I18nParams, type LifecycleConfig, type LifecycleEventName, type Locale, type PageDsl, type PageMeta, type PermissionConfig, type PermissionDeniedStrategy, RUNTIME_SCOPES, Registry, type RequiresConfig, type RuntimeScope, createI18nContext, isDslSourceRef, resolveRootNodes };

package/dist/index.d.ts

@@ -38,18 +38,60 @@ interface ActionConfig {
 }
 /** 事件映射：事件名 → 单个或多个动作 */
 type EventMap = Record<string, ActionConfig | ActionConfig[]>;
-/** UI DSL 树基础节点 */
-interface DslNode {
+/**
+ * 动态 DSL 引用（设计文档：DSL 各位置支持远端加载）：
+ * `source` 为二选一形态——`service`（经 ServiceRegistry 调用）或
+ * `http`（经 HttpAdapter 请求），返回 DSL 内容（PageDsl / DslNode / DslNode[]）；
+ * `params` 值可含表达式字符串，按**首次解析时**的作用域求值一次（不做联动重载）。
+ * `placeholder` 为解析期间渲染的占位子树（缺省渲染空）。
+ */
+interface DslSourceRef {
+    source: {
+        type: 'service';
+        service: string;
+        params?: Record<string, unknown>;
+    } | {
+        type: 'http';
+        request: {
+            method?: string;
+            url: string;
+            params?: Record<string, unknown>;
+            headers?: Record<string, string>;
+        };
+    };
+    placeholder?: DslNode;
+}
+/** DslSourceRef 类型守卫 */
+declare function isDslSourceRef(value: unknown): value is DslSourceRef;
+/** 子树元素：内联节点或动态引用（children 数组中可混排） */
+type DslChildrenItem = DslNode | DslSourceRef;
+/** 子树声明：内联数组（元素可为节点或动态引用混排），或整体远端动态引用 */
+type DslChildren = DslChildrenItem[] | DslSourceRef;
+/** UI DSL 树基础节点共有字段 */
+interface DslNodeBase {
     id?: string;
-    /** 组件类型，对应 Component Registry 中的注册名 */
-    type: string;
     props?: Record<string, unknown>;
-    children?: DslNode[];
+    children?: DslChildren;
     events?: EventMap;
     permission?: PermissionConfig;
     /** 条件渲染 */
     when?: ConditionConfig;
 }
+/** 组件节点：`type` 对应 Component Registry 中的注册名 */
+interface DslComponentNode extends DslNodeBase {
+    type: string;
+    component?: undefined;
+}
+/**
+ * 引用节点：`component` 引用页面级命名组件（PageDsl.components）的 key，
+ * 渲染该子树；引用处的 props / events 覆盖定义处同名字段
+ */
+interface DslReferenceNode extends DslNodeBase {
+    component: string;
+    type?: undefined;
+}
+/** UI DSL 树节点：组件节点（type）与引用节点（component）二选一 */
+type DslNode = DslComponentNode | DslReferenceNode;
 
 /**
  * DSL 文档结构（设计文档第 9、10、37 节）。
@@ -67,6 +109,10 @@ interface RequiresConfig {
 interface PageMeta {
     id: string;
     title?: string;
+    /** 页面名称（标识用途，区别于展示的 title） */
+    name?: string;
+    /** 页面描述 */
+    description?: string;
     /** 页面类型 / Page Pattern，如 "list"、"detail"、"form" */
     type?: string;
     permission?: PermissionConfig;
@@ -81,6 +127,15 @@ interface DataSourceConfig {
     autoLoad?: boolean;
     /** 调用参数，值可含表达式字符串 */
     params?: Record<string, unknown>;
+    /**
+     * 选项字段映射（该数据源用作选项源时声明）：加载结果为数组时，
+     * 每项归一化出 `{ label, value, disabled }` 键（原字段保留），
+     * 供 Select 等组件经 `${data.x}` 直接绑定
+     */
+    valueField?: string;
+    labelField?: string;
+    /** 选项禁用标记字段：数组项中该字段为真值时选项禁用 */
+    disabledField?: string;
     /** type 为 http 时的请求描述 */
     request?: {
         method?: string;
@@ -107,13 +162,47 @@ interface PageDsl {
     dsl: DslVersion;
     requires?: RequiresConfig;
     page: PageMeta;
+    /** 页面扩展元数据（自由键值，如 version / author / 业务自定义标记），Runtime 不消费，仅供宿主与工具链读取 */
+    meta?: Record<string, unknown>;
     /** 页面初始状态 */
     state?: Record<string, unknown>;
     dataSources?: Record<string, DataSourceConfig>;
+    /**
+     * 页面级命名动作定义：动作名 → 单个动作或动作数组，
+     * 供事件中的 `call` 动作按名引用复用（以调用方作用域执行，
+     * `${row}` / `${event}` 等局部作用域原样可用）
+     */
+    actions?: Record<string, ActionConfig | ActionConfig[]>;
+    /**
+     * 页面级命名组件定义（设计文档第 50 节 Fragment 的页面局部形态）：
+     * 组件名 → DslNode 子树（或 DslSourceRef 动态引用，引用处渲染时惰性解析），
+     * body 中以 `{ component: '名称' }` 引用节点复用，防止 DSL 嵌套过深；
+     * 以引用处作用域渲染
+     */
+    components?: Record<string, DslNode | DslSourceRef>;
     lifecycle?: LifecycleConfig;
-    /** UI 树根 */
+    /**
+     * UI 树根（单个 DslNode）。
+     * 与根级 `children` 为两种等价声明形态：`body` 存在时优先使用 `body`；
+     * `body` 缺失且 `children` 存在时以根级 `children` 作为 UI 树
+     * （隐式片段根，无需 Page 等包装节点，DSL 可描述页面局部）；
+     * 两者均缺失时按空树处理。读取入口见 `resolveRootNodes`
+     */
     body?: DslNode;
+    /**
+     * UI 树根（`body` 缺失时生效）：数组形态（元素可为 DslNode 或
+     * DslSourceRef 混排）或整体动态引用
+     */
+    children?: DslChildren;
 }
+/**
+ * 读取 Page DSL 的 UI 树根元素列表（官方入口）：
+ * `body` 存在 → `[body]`；根级 `children` 为数组 → 原样返回
+ * （元素可为 DslNode 或 DslSourceRef）；根级 `children` 为整体
+ * DslSourceRef 或缺失 → 空数组（整体引用形态由渲染入口经
+ * DslSourceBoundary 异步解析）
+ */
+declare function resolveRootNodes(pageDsl: PageDsl): DslChildrenItem[];
 /** Fragment DSL（第 50 节）：可复用的 UI 片段 */
 interface FragmentDsl {
     dsl: DslVersion;
@@ -214,4 +303,4 @@ interface CreateI18nOptions {
  */
 declare function createI18nContext(options?: CreateI18nOptions): I18nContext;
 
-export { type ActionConfig, type ApplicationDsl, type ConditionConfig, type CreateI18nOptions, type DataSourceConfig, type DataSourceType, type DslNode, type DslVersion, type EventMap, type ExpressionString, type FragmentDsl, type I18nContext, type I18nMessages, type I18nParams, type LifecycleConfig, type LifecycleEventName, type Locale, type PageDsl, type PageMeta, type PermissionConfig, type PermissionDeniedStrategy, RUNTIME_SCOPES, Registry, type RequiresConfig, type RuntimeScope, createI18nContext };
+export { type ActionConfig, type ApplicationDsl, type ConditionConfig, type CreateI18nOptions, type DataSourceConfig, type DataSourceType, type DslChildren, type DslChildrenItem, type DslComponentNode, type DslNode, type DslNodeBase, type DslReferenceNode, type DslSourceRef, type DslVersion, type EventMap, type ExpressionString, type FragmentDsl, type I18nContext, type I18nMessages, type I18nParams, type LifecycleConfig, type LifecycleEventName, type Locale, type PageDsl, type PageMeta, type PermissionConfig, type PermissionDeniedStrategy, RUNTIME_SCOPES, Registry, type RequiresConfig, type RuntimeScope, createI18nContext, isDslSourceRef, resolveRootNodes };

package/dist/index.js

@@ -1,3 +1,23 @@
+// src/node.ts
+function isDslSourceRef(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const source = value.source;
+  return typeof source === "object" && source !== null && (source.type === "service" || source.type === "http");
+}
+
+// src/document.ts
+function resolveRootNodes(pageDsl) {
+  if (pageDsl.body) {
+    return [pageDsl.body];
+  }
+  if (Array.isArray(pageDsl.children)) {
+    return pageDsl.children;
+  }
+  return [];
+}
+
 // src/scope.ts
 var RUNTIME_SCOPES = [
   "global",
@@ -94,5 +114,7 @@ function createI18nContext(options = {}) {
 export {
   RUNTIME_SCOPES,
   Registry,
-  createI18nContext
+  createI18nContext,
+  isDslSourceRef,
+  resolveRootNodes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pactor-app/core",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Pactor core: DSL protocol types and generic Registry (React-free, zero dependencies)",
   "keywords": [
     "pactor",