@pactor-app/runtime 0.1.0 → 1.1.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { PermissionConfig, Registry, ActionConfig, DataSourceConfig, PageMeta, I18nContext, DslNode, PageDsl, LifecycleEventName } from '@pactor-app/core';
+import { PermissionConfig, Registry, ActionConfig, DataSourceConfig, DslSourceRef, PageMeta, DslNode, I18nContext, DslChildren, PageDsl, LifecycleEventName } from '@pactor-app/core';
 import { ExpressionScope } from '@pactor-app/expression';
 import * as react from 'react';
-import { ComponentType, ReactNode } from 'react';
+import { ReactNode, ComponentType } from 'react';
 import { DslValidationError } from '@pactor-app/schema';
 
 /**
@@ -125,6 +125,11 @@ declare class DataStore {
     getData(name: string): unknown;
     /** 各数据源当前数据，供表达式作用域的 `data` 键使用 */
     getAllData(): Record<string, unknown>;
+    /** 各数据源的加载状态（loading / error），供表达式作用域的 `dataStatus` 键使用 */
+    getAllStatus(): Record<string, {
+        loading: boolean;
+        error?: Error;
+    }>;
     subscribe(listener: () => void): () => void;
     /** 版本号，供 `useSyncExternalStore` 的 getSnapshot 使用 */
     getVersion(): number;
@@ -147,6 +152,29 @@ declare class DataStore {
     private update;
 }
 
+interface DslSourceResolverDeps {
+    services: ServiceRegistry;
+    http: HttpAdapter;
+    /** 加载前取当前表达式作用域（params 求值用） */
+    getScope: () => ExpressionScope;
+}
+/** 缓存 key：按固定字段序拼接引用原文（避免字段顺序差异导致重复请求） */
+declare function dslSourceKey(ref: DslSourceRef): string;
+/**
+ * DslSourceResolver（spec: dsl-renderer 动态引用解析）：
+ * 按 `source.type` 分派——service 经 ServiceRegistry、http 经 HttpAdapter；
+ * `params` 表达式按**首次解析时**作用域求值一次（不做联动重载）。
+ * 结果按引用原文缓存于页面运行时生命周期（Promise 级去重：并发渲染
+ * 同一引用共享一次请求；失败同样缓存，随运行时销毁清理）。
+ */
+declare class DslSourceResolver {
+    private readonly deps;
+    private readonly cache;
+    constructor(deps: DslSourceResolverDeps);
+    resolve(ref: DslSourceRef): Promise<unknown>;
+    private load;
+}
+
 /**
  * StateStore：框架无关的最小状态容器（设计文档第 15 节，决策 D1）。
  *
@@ -235,10 +263,22 @@ interface RuntimeContext {
      * destroy 时清理。
      */
     actionResults: Record<string, unknown>;
+    /**
+     * 页面级命名动作定义（PageDsl.actions）：动作名 → 单个或多个动作，
+     * 供内置 `call` 动作按名引用复用；缺省为空对象
+     */
+    namedActions: Record<string, ActionConfig | ActionConfig[]>;
+    /**
+     * 页面级命名组件定义（PageDsl.components）：组件名 → DslNode 子树
+     * 或 DslSourceRef 动态引用，供 `component` 引用节点按名渲染；缺省为空对象
+     */
+    pageComponents: Record<string, DslNode | DslSourceRef>;
     permission: PermissionAdapter;
     capabilities: CapabilityRegistry;
     /** HTTP 出口适配器（DataSource / request 动作共用） */
     http: HttpAdapter;
+    /** 动态 DSL 引用解析器（service/http 分派 + 页面级缓存） */
+    dslSources: DslSourceResolver;
     /** 当前语言代码（如 'zh-CN'） */
     locale: string;
     /** i18n 上下文：提供 `t(key, params?)` 翻译函数 */
@@ -250,6 +290,10 @@ interface CreateRuntimeContextOptions {
     /** 页面初始 state */
     state?: Record<string, unknown>;
     dataSources?: Record<string, DataSourceConfig>;
+    /** 页面级命名动作定义（PageDsl.actions），供 `call` 动作按名引用 */
+    namedActions?: Record<string, ActionConfig | ActionConfig[]>;
+    /** 页面级命名组件定义（PageDsl.components），供 `component` 引用节点按名渲染 */
+    pageComponents?: Record<string, DslNode | DslSourceRef>;
     route?: {
         params?: Record<string, unknown>;
         query?: Record<string, unknown>;
@@ -285,6 +329,7 @@ type LocalScope = ExpressionScope;
  * 组装表达式求值作用域（设计文档第 15、16 节，决策 D2）：
  *
  * - `state` / `data` 取 Store 当前值快照
+ * - `dataStatus` 为各数据源的 `{ loading, error }` 状态（加载态/错误态展示用）
  * - `form` 为 state 的 `form` 路径别名（Form 提交写入 `state.form`，
  *   使 `${form.<field>}` 可用，设计文档第 15 节 form 作用域层级）
  * - 另含 `app` / `page` / `route` / `user` / `params`（route.params 的别名）
@@ -307,6 +352,32 @@ declare function useI18n(): I18nContext;
  */
 declare function registerBuiltinActions(registry: ActionRegistry): void;
 
+/** Renderer 经 React Context 透传给被渲染组件的能力 */
+interface RendererContextValue {
+    context: RuntimeContext;
+    engine: ActionEngine;
+    /** 当前局部作用域（row / rowIndex / event / item 等） */
+    scope: ExpressionScope;
+    /** 内部：命名组件引用链（PageDsl.components 的循环引用守卫） */
+    referenceStack?: string[];
+    /**
+     * 渲染 DSL 子节点（内联数组或 DslSourceRef 动态引用——引用形态经
+     * DslSourceBoundary 异步解析渲染）；`extraScope` 注入的局部作用域
+     * 覆盖同名全局键，且仅作用于该子树（Table 行、Repeat 项等场景，
+     * 设计文档第 21 节）。
+     */
+    renderChildren(children: DslChildren | undefined, extraScope?: ExpressionScope): ReactNode;
+}
+/** 在被渲染组件内获取 Renderer 能力（renderChildren / engine / context） */
+declare function useRenderer(): RendererContextValue;
+/**
+ * 订阅 StateStore（决策 D5）。`path` 为点路径；缺省返回整个 state。
+ * 基于 `useSyncExternalStore`，state 变化时组件重渲染。
+ */
+declare function useRuntimeState<T = unknown>(path?: string): T;
+/** 订阅指定数据源的 `{ loading, error, data }` 状态 */
+declare function useDataSource(name: string): DataSourceStatus;
+
 type AnyComponent = ComponentType<any>;
 /**
  * 组件注册条目：直接注册组件，或以 `{ component, withScope: true }`
@@ -341,28 +412,6 @@ interface DslRendererProps {
  */
 declare function DslRenderer({ context, node, engine, children }: DslRendererProps): react.JSX.Element;
 
-/** Renderer 经 React Context 透传给被渲染组件的能力 */
-interface RendererContextValue {
-    context: RuntimeContext;
-    engine: ActionEngine;
-    /** 当前局部作用域（row / rowIndex / event / item 等） */
-    scope: ExpressionScope;
-    /**
-     * 渲染 DSL 子节点；`extraScope` 注入的局部作用域覆盖同名全局键，
-     * 且仅作用于该子树（Table 行、Repeat 项等场景，设计文档第 21 节）。
-     */
-    renderChildren(children: DslNode[] | undefined, extraScope?: ExpressionScope): ReactNode;
-}
-/** 在被渲染组件内获取 Renderer 能力（renderChildren / engine / context） */
-declare function useRenderer(): RendererContextValue;
-/**
- * 订阅 StateStore（决策 D5）。`path` 为点路径；缺省返回整个 state。
- * 基于 `useSyncExternalStore`，state 变化时组件重渲染。
- */
-declare function useRuntimeState<T = unknown>(path?: string): T;
-/** 订阅指定数据源的 `{ loading, error, data }` 状态 */
-declare function useDataSource(name: string): DataSourceStatus;
-
 /**
  * 未注册组件的占位渲染（决策 D5）：展示类型名，dev 友好，
  * 不抛错也不渲染空白。
@@ -371,6 +420,22 @@ declare function UnsupportedComponent({ type }: {
     type: string;
 }): react.JSX.Element;
 
+interface DslSourceBoundaryProps {
+    context: RuntimeContext;
+    sourceRef: DslSourceRef;
+    /** 解析中渲染的内容（调用方预渲染 placeholder 子树；缺省为空） */
+    placeholder?: ReactNode;
+    /** 渲染解析结果（调用方负责形态校验与降级） */
+    children: (content: unknown) => ReactNode;
+}
+/**
+ * 动态 DSL 引用渲染边界（spec: dsl-renderer，renderer 内部组件，
+ * 非 DSL 组件类型）：解析中渲染 placeholder（缺省空）、成功交给
+ * 调用方渲染、失败告警并渲染空——MUST NOT 抛错击穿渲染层。
+ * 解析经 `context.dslSources`（Promise 级缓存去重）。
+ */
+declare function DslSourceBoundary({ context, sourceRef, placeholder, children, }: DslSourceBoundaryProps): react.JSX.Element | null;
+
 /** Page DSL 校验失败错误：内含结构化错误列表 */
 declare class PageRuntimeError extends Error {
     readonly errors: DslValidationError[];
@@ -389,7 +454,7 @@ interface PageRuntime {
     readonly initialized: Promise<void>;
     /** 是否已销毁 */
     readonly destroyed: boolean;
-    /** 渲染 body 子树；未配置 body 时渲染空内容 */
+    /** 渲染 UI 树根（body 或根级 children）；两者皆无时渲染空内容 */
     render(): ReactNode;
     /** 宿主（Router）触发生命周期：onReady */
     ready(): Promise<void>;
@@ -423,7 +488,7 @@ declare function createPageRuntime(pageDsl: PageDsl, options?: CreateRuntimeCont
 declare function PageRuntimeView({ runtime, children, }: {
     runtime: PageRuntime;
     children?: ReactNode;
-}): react.JSX.Element;
+}): ReactNode;
 
 interface ResolveDeepOptions {
     /**
@@ -444,4 +509,4 @@ interface ResolveDeepOptions {
  */
 declare function resolveDeep(value: unknown, scope: ExpressionScope, options?: ResolveDeepOptions): unknown;
 
-export { type ActionContext, ActionEngine, type ActionHandler, type ActionRegistry, type ActionResult, type CapabilityRegistry, type ComponentEntry, type ComponentRegistry, type CreateRuntimeContextOptions, type DataSourceStatus, DataStore, type DataStoreDeps, DslRenderer, type DslRendererProps, type FormHandle, type FormRegistry, type HttpAdapter, type HttpRequestConfig, I18nContextProvider, type LocalScope, type PageRuntime, PageRuntimeError, PageRuntimeView, type PermissionAdapter, type RendererContextValue, type RouteContext, type RouterAdapter, type RuntimeContext, type ScopedComponentEntry, type ServiceHandler, type ServiceRegistry, StateStore, UnsupportedComponent, buildScope, createDefaultPermissionAdapter, createDefaultRouterAdapter, createFetchHttpAdapter, createPageRuntime, createRuntimeContext, registerBuiltinActions, resolveDeep, useDataSource, useI18n, useRenderer, useRuntimeState };
+export { type ActionContext, ActionEngine, type ActionHandler, type ActionRegistry, type ActionResult, type CapabilityRegistry, type ComponentEntry, type ComponentRegistry, type CreateRuntimeContextOptions, type DataSourceStatus, DataStore, type DataStoreDeps, DslRenderer, type DslRendererProps, DslSourceBoundary, type DslSourceBoundaryProps, DslSourceResolver, type DslSourceResolverDeps, type FormHandle, type FormRegistry, type HttpAdapter, type HttpRequestConfig, I18nContextProvider, type LocalScope, type PageRuntime, PageRuntimeError, PageRuntimeView, type PermissionAdapter, type RendererContextValue, type RouteContext, type RouterAdapter, type RuntimeContext, type ScopedComponentEntry, type ServiceHandler, type ServiceRegistry, StateStore, UnsupportedComponent, buildScope, createDefaultPermissionAdapter, createDefaultRouterAdapter, createFetchHttpAdapter, createPageRuntime, createRuntimeContext, dslSourceKey, registerBuiltinActions, resolveDeep, useDataSource, useI18n, useRenderer, useRuntimeState };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { PermissionConfig, Registry, ActionConfig, DataSourceConfig, PageMeta, I18nContext, DslNode, PageDsl, LifecycleEventName } from '@pactor-app/core';
+import { PermissionConfig, Registry, ActionConfig, DataSourceConfig, DslSourceRef, PageMeta, DslNode, I18nContext, DslChildren, PageDsl, LifecycleEventName } from '@pactor-app/core';
 import { ExpressionScope } from '@pactor-app/expression';
 import * as react from 'react';
-import { ComponentType, ReactNode } from 'react';
+import { ReactNode, ComponentType } from 'react';
 import { DslValidationError } from '@pactor-app/schema';
 
 /**
@@ -125,6 +125,11 @@ declare class DataStore {
     getData(name: string): unknown;
     /** 各数据源当前数据，供表达式作用域的 `data` 键使用 */
     getAllData(): Record<string, unknown>;
+    /** 各数据源的加载状态（loading / error），供表达式作用域的 `dataStatus` 键使用 */
+    getAllStatus(): Record<string, {
+        loading: boolean;
+        error?: Error;
+    }>;
     subscribe(listener: () => void): () => void;
     /** 版本号，供 `useSyncExternalStore` 的 getSnapshot 使用 */
     getVersion(): number;
@@ -147,6 +152,29 @@ declare class DataStore {
     private update;
 }
 
+interface DslSourceResolverDeps {
+    services: ServiceRegistry;
+    http: HttpAdapter;
+    /** 加载前取当前表达式作用域（params 求值用） */
+    getScope: () => ExpressionScope;
+}
+/** 缓存 key：按固定字段序拼接引用原文（避免字段顺序差异导致重复请求） */
+declare function dslSourceKey(ref: DslSourceRef): string;
+/**
+ * DslSourceResolver（spec: dsl-renderer 动态引用解析）：
+ * 按 `source.type` 分派——service 经 ServiceRegistry、http 经 HttpAdapter；
+ * `params` 表达式按**首次解析时**作用域求值一次（不做联动重载）。
+ * 结果按引用原文缓存于页面运行时生命周期（Promise 级去重：并发渲染
+ * 同一引用共享一次请求；失败同样缓存，随运行时销毁清理）。
+ */
+declare class DslSourceResolver {
+    private readonly deps;
+    private readonly cache;
+    constructor(deps: DslSourceResolverDeps);
+    resolve(ref: DslSourceRef): Promise<unknown>;
+    private load;
+}
+
 /**
  * StateStore：框架无关的最小状态容器（设计文档第 15 节，决策 D1）。
  *
@@ -235,10 +263,22 @@ interface RuntimeContext {
      * destroy 时清理。
      */
     actionResults: Record<string, unknown>;
+    /**
+     * 页面级命名动作定义（PageDsl.actions）：动作名 → 单个或多个动作，
+     * 供内置 `call` 动作按名引用复用；缺省为空对象
+     */
+    namedActions: Record<string, ActionConfig | ActionConfig[]>;
+    /**
+     * 页面级命名组件定义（PageDsl.components）：组件名 → DslNode 子树
+     * 或 DslSourceRef 动态引用，供 `component` 引用节点按名渲染；缺省为空对象
+     */
+    pageComponents: Record<string, DslNode | DslSourceRef>;
     permission: PermissionAdapter;
     capabilities: CapabilityRegistry;
     /** HTTP 出口适配器（DataSource / request 动作共用） */
     http: HttpAdapter;
+    /** 动态 DSL 引用解析器（service/http 分派 + 页面级缓存） */
+    dslSources: DslSourceResolver;
     /** 当前语言代码（如 'zh-CN'） */
     locale: string;
     /** i18n 上下文：提供 `t(key, params?)` 翻译函数 */
@@ -250,6 +290,10 @@ interface CreateRuntimeContextOptions {
     /** 页面初始 state */
     state?: Record<string, unknown>;
     dataSources?: Record<string, DataSourceConfig>;
+    /** 页面级命名动作定义（PageDsl.actions），供 `call` 动作按名引用 */
+    namedActions?: Record<string, ActionConfig | ActionConfig[]>;
+    /** 页面级命名组件定义（PageDsl.components），供 `component` 引用节点按名渲染 */
+    pageComponents?: Record<string, DslNode | DslSourceRef>;
     route?: {
         params?: Record<string, unknown>;
         query?: Record<string, unknown>;
@@ -285,6 +329,7 @@ type LocalScope = ExpressionScope;
  * 组装表达式求值作用域（设计文档第 15、16 节，决策 D2）：
  *
  * - `state` / `data` 取 Store 当前值快照
+ * - `dataStatus` 为各数据源的 `{ loading, error }` 状态（加载态/错误态展示用）
  * - `form` 为 state 的 `form` 路径别名（Form 提交写入 `state.form`，
  *   使 `${form.<field>}` 可用，设计文档第 15 节 form 作用域层级）
  * - 另含 `app` / `page` / `route` / `user` / `params`（route.params 的别名）
@@ -307,6 +352,32 @@ declare function useI18n(): I18nContext;
  */
 declare function registerBuiltinActions(registry: ActionRegistry): void;
 
+/** Renderer 经 React Context 透传给被渲染组件的能力 */
+interface RendererContextValue {
+    context: RuntimeContext;
+    engine: ActionEngine;
+    /** 当前局部作用域（row / rowIndex / event / item 等） */
+    scope: ExpressionScope;
+    /** 内部：命名组件引用链（PageDsl.components 的循环引用守卫） */
+    referenceStack?: string[];
+    /**
+     * 渲染 DSL 子节点（内联数组或 DslSourceRef 动态引用——引用形态经
+     * DslSourceBoundary 异步解析渲染）；`extraScope` 注入的局部作用域
+     * 覆盖同名全局键，且仅作用于该子树（Table 行、Repeat 项等场景，
+     * 设计文档第 21 节）。
+     */
+    renderChildren(children: DslChildren | undefined, extraScope?: ExpressionScope): ReactNode;
+}
+/** 在被渲染组件内获取 Renderer 能力（renderChildren / engine / context） */
+declare function useRenderer(): RendererContextValue;
+/**
+ * 订阅 StateStore（决策 D5）。`path` 为点路径；缺省返回整个 state。
+ * 基于 `useSyncExternalStore`，state 变化时组件重渲染。
+ */
+declare function useRuntimeState<T = unknown>(path?: string): T;
+/** 订阅指定数据源的 `{ loading, error, data }` 状态 */
+declare function useDataSource(name: string): DataSourceStatus;
+
 type AnyComponent = ComponentType<any>;
 /**
  * 组件注册条目：直接注册组件，或以 `{ component, withScope: true }`
@@ -341,28 +412,6 @@ interface DslRendererProps {
  */
 declare function DslRenderer({ context, node, engine, children }: DslRendererProps): react.JSX.Element;
 
-/** Renderer 经 React Context 透传给被渲染组件的能力 */
-interface RendererContextValue {
-    context: RuntimeContext;
-    engine: ActionEngine;
-    /** 当前局部作用域（row / rowIndex / event / item 等） */
-    scope: ExpressionScope;
-    /**
-     * 渲染 DSL 子节点；`extraScope` 注入的局部作用域覆盖同名全局键，
-     * 且仅作用于该子树（Table 行、Repeat 项等场景，设计文档第 21 节）。
-     */
-    renderChildren(children: DslNode[] | undefined, extraScope?: ExpressionScope): ReactNode;
-}
-/** 在被渲染组件内获取 Renderer 能力（renderChildren / engine / context） */
-declare function useRenderer(): RendererContextValue;
-/**
- * 订阅 StateStore（决策 D5）。`path` 为点路径；缺省返回整个 state。
- * 基于 `useSyncExternalStore`，state 变化时组件重渲染。
- */
-declare function useRuntimeState<T = unknown>(path?: string): T;
-/** 订阅指定数据源的 `{ loading, error, data }` 状态 */
-declare function useDataSource(name: string): DataSourceStatus;
-
 /**
  * 未注册组件的占位渲染（决策 D5）：展示类型名，dev 友好，
  * 不抛错也不渲染空白。
@@ -371,6 +420,22 @@ declare function UnsupportedComponent({ type }: {
     type: string;
 }): react.JSX.Element;
 
+interface DslSourceBoundaryProps {
+    context: RuntimeContext;
+    sourceRef: DslSourceRef;
+    /** 解析中渲染的内容（调用方预渲染 placeholder 子树；缺省为空） */
+    placeholder?: ReactNode;
+    /** 渲染解析结果（调用方负责形态校验与降级） */
+    children: (content: unknown) => ReactNode;
+}
+/**
+ * 动态 DSL 引用渲染边界（spec: dsl-renderer，renderer 内部组件，
+ * 非 DSL 组件类型）：解析中渲染 placeholder（缺省空）、成功交给
+ * 调用方渲染、失败告警并渲染空——MUST NOT 抛错击穿渲染层。
+ * 解析经 `context.dslSources`（Promise 级缓存去重）。
+ */
+declare function DslSourceBoundary({ context, sourceRef, placeholder, children, }: DslSourceBoundaryProps): react.JSX.Element | null;
+
 /** Page DSL 校验失败错误：内含结构化错误列表 */
 declare class PageRuntimeError extends Error {
     readonly errors: DslValidationError[];
@@ -389,7 +454,7 @@ interface PageRuntime {
     readonly initialized: Promise<void>;
     /** 是否已销毁 */
     readonly destroyed: boolean;
-    /** 渲染 body 子树；未配置 body 时渲染空内容 */
+    /** 渲染 UI 树根（body 或根级 children）；两者皆无时渲染空内容 */
     render(): ReactNode;
     /** 宿主（Router）触发生命周期：onReady */
     ready(): Promise<void>;
@@ -423,7 +488,7 @@ declare function createPageRuntime(pageDsl: PageDsl, options?: CreateRuntimeCont
 declare function PageRuntimeView({ runtime, children, }: {
     runtime: PageRuntime;
     children?: ReactNode;
-}): react.JSX.Element;
+}): ReactNode;
 
 interface ResolveDeepOptions {
     /**
@@ -444,4 +509,4 @@ interface ResolveDeepOptions {
  */
 declare function resolveDeep(value: unknown, scope: ExpressionScope, options?: ResolveDeepOptions): unknown;
 
-export { type ActionContext, ActionEngine, type ActionHandler, type ActionRegistry, type ActionResult, type CapabilityRegistry, type ComponentEntry, type ComponentRegistry, type CreateRuntimeContextOptions, type DataSourceStatus, DataStore, type DataStoreDeps, DslRenderer, type DslRendererProps, type FormHandle, type FormRegistry, type HttpAdapter, type HttpRequestConfig, I18nContextProvider, type LocalScope, type PageRuntime, PageRuntimeError, PageRuntimeView, type PermissionAdapter, type RendererContextValue, type RouteContext, type RouterAdapter, type RuntimeContext, type ScopedComponentEntry, type ServiceHandler, type ServiceRegistry, StateStore, UnsupportedComponent, buildScope, createDefaultPermissionAdapter, createDefaultRouterAdapter, createFetchHttpAdapter, createPageRuntime, createRuntimeContext, registerBuiltinActions, resolveDeep, useDataSource, useI18n, useRenderer, useRuntimeState };
+export { type ActionContext, ActionEngine, type ActionHandler, type ActionRegistry, type ActionResult, type CapabilityRegistry, type ComponentEntry, type ComponentRegistry, type CreateRuntimeContextOptions, type DataSourceStatus, DataStore, type DataStoreDeps, DslRenderer, type DslRendererProps, DslSourceBoundary, type DslSourceBoundaryProps, DslSourceResolver, type DslSourceResolverDeps, type FormHandle, type FormRegistry, type HttpAdapter, type HttpRequestConfig, I18nContextProvider, type LocalScope, type PageRuntime, PageRuntimeError, PageRuntimeView, type PermissionAdapter, type RendererContextValue, type RouteContext, type RouterAdapter, type RuntimeContext, type ScopedComponentEntry, type ServiceHandler, type ServiceRegistry, StateStore, UnsupportedComponent, buildScope, createDefaultPermissionAdapter, createDefaultRouterAdapter, createFetchHttpAdapter, createPageRuntime, createRuntimeContext, dslSourceKey, registerBuiltinActions, resolveDeep, useDataSource, useI18n, useRenderer, useRuntimeState };