@pactor-app/runtime 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,447 @@
+import { PermissionConfig, Registry, ActionConfig, DataSourceConfig, PageMeta, I18nContext, DslNode, PageDsl, LifecycleEventName } from '@pactor-app/core';
+import { ExpressionScope } from '@pactor-app/expression';
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { DslValidationError } from '@pactor-app/schema';
+
+/**
+ * 适配接口（设计文档第 15、17 节，决策 D2）：
+ *
+ * 动作能力边界 —— `navigate` / 权限判定 / HTTP 传输依赖上层模块
+ * （@pactor-app/router / @pactor-app/permission / 宿主应用），本包只定义接口与
+ * 默认实现，真实现经 `createRuntimeContext` 注入。
+ */
+/**
+ * 权限适配接口：检查权限配置（string / string[] 任一命中即放行 /
+ * `{ code, denied }` 对象形式）。三种形态均只判定"有没有权限"——
+ * 对象形式只检查 `code`，denied 策略由 Renderer / Guard 解释。
+ */
+interface PermissionAdapter {
+    check(permission: PermissionConfig): boolean;
+}
+/** 路由适配接口 */
+interface RouterAdapter {
+    navigate(to: string): void;
+}
+/** HTTP 请求描述（与 DataSourceConfig.request 结构对齐） */
+interface HttpRequestConfig {
+    method?: string;
+    url: string;
+    params?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+/** HTTP 适配接口：统一出口，便于测试替换与统一认证 */
+interface HttpAdapter {
+    request(config: HttpRequestConfig): Promise<unknown>;
+}
+/** 默认权限适配器：全部放行（真实权限由 @pactor-app/permission 提供） */
+declare function createDefaultPermissionAdapter(): PermissionAdapter;
+/** 默认路由适配器：no-op 并告警（真实导航由 @pactor-app/router 提供） */
+declare function createDefaultRouterAdapter(): RouterAdapter;
+/**
+ * 默认 HTTP 适配器：基于全局 fetch。
+ * GET/HEAD 请求把 params 拼到 query string；body 统一 JSON 编码；
+ * 非 2xx 响应抛错；响应优先按 JSON 解析，失败则返回原文本。
+ */
+declare function createFetchHttpAdapter(): HttpAdapter;
+
+/** 动作执行结果：全程受控，不向 UI 层抛未捕获异常 */
+interface ActionResult {
+    ok: boolean;
+    data?: unknown;
+    error?: Error;
+    /** condition 求值为 false 时跳过执行 */
+    skipped?: boolean;
+}
+/** handler 可见的执行上下文 */
+interface ActionContext {
+    /** 完整 RuntimeContext（state / data / services / http 等） */
+    context: RuntimeContext;
+    /** 本次执行的求值作用域（含事件等局部作用域） */
+    scope: ExpressionScope;
+    /** 以当前局部作用域执行子动作（编排动作用） */
+    execute(action: ActionConfig): Promise<ActionResult>;
+}
+type ActionHandler = (action: ActionConfig, ctx: ActionContext) => ActionResult | Promise<ActionResult>;
+/** Action Registry：动作名 → handler（设计文档第 17 节） */
+type ActionRegistry = Registry<ActionHandler>;
+/**
+ * Action 引擎（设计文档第 17 节，决策 D4）。
+ *
+ * 执行管线：求值 `condition`（false 则跳过，返回 `{ ok: true, skipped: true }`）
+ * → 检查 `permission`（拒绝返回 `{ ok: false }`）→ 查 ActionRegistry 执行。
+ * 未注册动作返回受控失败；任何异常收敛为 `{ ok: false, error }`。
+ *
+ * 命名动作结果（设计文档第 48 节，决策 D2）：动作声明 `id` 时，
+ * 执行完成（含 skipped / 失败）后把结果写入 context 级 `actionResults`
+ * ——成功时为 `result.data`，失败时为 `{ ok: false, error }`；
+ * 经 buildScope 的 `actions` 键供后续动作引用（`${actions.<id>}`）。
+ * 未命名动作行为不变。
+ */
+declare class ActionEngine {
+    private readonly context;
+    constructor(context: RuntimeContext);
+    execute(action: ActionConfig, localScope?: ExpressionScope): Promise<ActionResult>;
+    /** 命名动作结果落盘：成功 → data；失败 → `{ ok: false, error }` */
+    private recordNamedResult;
+    /** 事件动作数组按声明顺序串行执行 */
+    executeAll(actions: ActionConfig | ActionConfig[], localScope?: ExpressionScope): Promise<ActionResult[]>;
+}
+
+/** 单个数据源的运行时状态 */
+interface DataSourceStatus {
+    loading: boolean;
+    error?: Error;
+    data?: unknown;
+}
+interface DataStoreDeps {
+    dataSources: Record<string, DataSourceConfig>;
+    services: ServiceRegistry;
+    http: HttpAdapter;
+    /** 加载前取当前表达式作用域（params / request 求值用） */
+    getScope: () => ExpressionScope;
+}
+/**
+ * DataStore：DataSource 运行时（设计文档第 19 节，决策 D3）。
+ *
+ * 按数据源名维护 `{ loading, error, data }`；按类型分派加载
+ * （static / service / http；computed / resource 留待后续迭代）。
+ * 错误一律写入 `error` 状态，绝不抛到渲染层。
+ */
+declare class DataStore {
+    private readonly configs;
+    private readonly services;
+    private readonly http;
+    private readonly getScope;
+    private readonly statuses;
+    private readonly listeners;
+    private version;
+    constructor(deps: DataStoreDeps);
+    /** 状态快照（未知名返回空状态，不抛错） */
+    get(name: string): DataSourceStatus;
+    /** 同 `get(name)`，语义化别名 */
+    getStatus(name: string): DataSourceStatus;
+    getData(name: string): unknown;
+    /** 各数据源当前数据，供表达式作用域的 `data` 键使用 */
+    getAllData(): Record<string, unknown>;
+    subscribe(listener: () => void): () => void;
+    /** 版本号，供 `useSyncExternalStore` 的 getSnapshot 使用 */
+    getVersion(): number;
+    /** 触发所有 `autoLoad: true` 的数据源（PageRuntime 初始化阶段调用） */
+    init(): Promise<void[]>;
+    /**
+     * 加载指定数据源。状态流转：开始置 loading 并清空 error；
+     * 成功写入 data；失败写入 error（保留旧 data）。MUST NOT 抛出。
+     */
+    load(name: string): Promise<void>;
+    /** 重新加载指定数据源（语义同 `load`，供模板与 Action 调用） */
+    refresh(name: string): Promise<void>;
+    /**
+     * reload 语义：指定名称时刷新该数据源；
+     * 缺省时刷新全部 autoLoad 数据源（供 Action 引擎 `reload` 动作调用）。
+     */
+    reload(name?: string): Promise<void | void[]>;
+    private autoLoadNames;
+    private loadByType;
+    private update;
+}
+
+/**
+ * StateStore：框架无关的最小状态容器（设计文档第 15 节，决策 D1）。
+ *
+ * 手写约百行、零依赖，不引入 Zustand；React 侧经 `useSyncExternalStore`
+ * 订阅（见 renderer/）。所有写入均为不可变更新，`reset()` 因此可以安全地
+ * 恢复到创建时的初始值。
+ */
+declare class StateStore {
+    private state;
+    private readonly initialState;
+    private readonly listeners;
+    private version;
+    constructor(initialState?: Record<string, unknown>);
+    /** 当前完整 state 对象 */
+    getState(): Record<string, unknown>;
+    /** 按点路径读取，如 `get('user.name')`；路径不存在时返回 undefined */
+    get(path: string): unknown;
+    /** 对象合并：`set({ b: 3 })` */
+    set(patch: Record<string, unknown>): void;
+    /** 路径写入：`set('user.name', 'Bob')` */
+    set(path: string, value: unknown): void;
+    /** 恢复为创建时的初始值 */
+    reset(): void;
+    /** 订阅变化，返回退订函数 */
+    subscribe(listener: () => void): () => void;
+    /**
+     * 单调递增的版本号，供 `useSyncExternalStore` 的 getSnapshot 使用
+     * （V1 简化策略：任一变化重渲染整棵 DSL 树）。
+     */
+    getVersion(): number;
+    private notify;
+}
+
+/** 业务服务函数：以求值后的 params 调用（如 `customer.list`） */
+type ServiceHandler = (params: Record<string, unknown>) => unknown | Promise<unknown>;
+/** Service Registry：服务名 → 服务函数（设计文档第 18 节） */
+type ServiceRegistry = Registry<ServiceHandler>;
+/**
+ * Component Registry：组件类型名 → 组件条目。
+ *
+ * 条目在 renderer/ 中被作为 React 组件使用（可为组件或
+ * `{ component, withScope }` 包装）；本层为保持零 React 依赖，
+ * 类型放宽为 unknown，由注册方保证。
+ */
+type ComponentRegistry = Registry<unknown>;
+/** Capability Registry（设计文档第 37 节预留） */
+type CapabilityRegistry = Registry<unknown>;
+/**
+ * Form 句柄（表单联动桥，决策同 UiBridge）：
+ * Form 组件挂载时注册、卸载注销；`form.setValues` 动作经它写入字段值。
+ * setValues 不触发校验与 onValuesChange（避免联动循环）。
+ */
+interface FormHandle {
+    setValues(values: Record<string, unknown>): void;
+}
+/** Form Registry：表单名 → 句柄（缺省名 'default'） */
+type FormRegistry = Registry<FormHandle>;
+/** 路由上下文：参数 + 导航能力（navigate 委托给 RouterAdapter） */
+interface RouteContext {
+    params: Record<string, unknown>;
+    query: Record<string, unknown>;
+    navigate(to: string): void;
+}
+/**
+ * RuntimeContext（设计文档第 15 节，决策 D2）：
+ * 普通 TS 对象，非 React 代码直接持有；Renderer 经 React Context 透传。
+ */
+interface RuntimeContext {
+    app: Record<string, unknown>;
+    page: Partial<PageMeta>;
+    state: StateStore;
+    data: DataStore;
+    route: RouteContext;
+    user: Record<string, unknown>;
+    services: ServiceRegistry;
+    components: ComponentRegistry;
+    actions: ActionRegistry;
+    /** 表单句柄注册表：Form 组件挂载注册，`form.setValues` 动作寻址 */
+    forms: FormRegistry;
+    /**
+     * 命名动作结果记录（设计文档第 48 节，决策 D2）：
+     * 带 `id` 的动作执行完成后写入——成功时为结果数据，失败时为
+     * `{ ok: false, error }`；经 `buildScope` 以 `actions` 键暴露给
+     * 表达式（`${actions.<id>.success}`）。页面级共享：同一
+     * RuntimeContext 的所有事件分发读写同一记录，PageRuntime
+     * destroy 时清理。
+     */
+    actionResults: Record<string, unknown>;
+    permission: PermissionAdapter;
+    capabilities: CapabilityRegistry;
+    /** HTTP 出口适配器（DataSource / request 动作共用） */
+    http: HttpAdapter;
+    /** 当前语言代码（如 'zh-CN'） */
+    locale: string;
+    /** i18n 上下文：提供 `t(key, params?)` 翻译函数 */
+    i18n: I18nContext;
+}
+interface CreateRuntimeContextOptions {
+    app?: Record<string, unknown>;
+    page?: Partial<PageMeta>;
+    /** 页面初始 state */
+    state?: Record<string, unknown>;
+    dataSources?: Record<string, DataSourceConfig>;
+    route?: {
+        params?: Record<string, unknown>;
+        query?: Record<string, unknown>;
+    };
+    user?: Record<string, unknown>;
+    services?: ServiceRegistry;
+    components?: ComponentRegistry;
+    actions?: ActionRegistry;
+    forms?: FormRegistry;
+    permission?: PermissionAdapter;
+    router?: RouterAdapter;
+    http?: HttpAdapter;
+    capabilities?: CapabilityRegistry;
+    /** 当前语言代码（缺省 'zh-CN'） */
+    locale?: string;
+    /** 回退语言代码（缺省 'zh-CN'） */
+    defaultLocale?: string;
+    /** 翻译消息表 */
+    messages?: Record<string, string | Record<string, string>>;
+}
+/**
+ * 组装 RuntimeContext。默认情形下 registries 为空 Registry 实例、
+ * adapters 为默认空实现（permission 放行、navigate no-op、http 走 fetch）。
+ *
+ * 注意：本工厂不注册内置动作；`createPageRuntime` 会自动注册，
+ * 独立使用上下文时可调用 `registerBuiltinActions(context.actions)`。
+ */
+declare function createRuntimeContext(options?: CreateRuntimeContextOptions): RuntimeContext;
+/** 表达式局部作用域（row / rowIndex / event / item 等） */
+type LocalScope = ExpressionScope;
+
+/**
+ * 组装表达式求值作用域（设计文档第 15、16 节，决策 D2）：
+ *
+ * - `state` / `data` 取 Store 当前值快照
+ * - `form` 为 state 的 `form` 路径别名（Form 提交写入 `state.form`，
+ *   使 `${form.<field>}` 可用，设计文档第 15 节 form 作用域层级）
+ * - 另含 `app` / `page` / `route` / `user` / `params`（route.params 的别名）
+ * - `actions` 为命名动作结果记录（`ActionConfig.id` 执行结果，
+ *   设计文档第 48 节），引用同一可变记录，后写入的结果立即可见
+ * - 局部作用域（`row` / `rowIndex` / `event` / `item` 等）覆盖同名全局键
+ */
+declare function buildScope(context: RuntimeContext, local?: ExpressionScope): ExpressionScope;
+
+declare const I18nContextProvider: react.Provider<I18nContext | null>;
+/** 在 React 组件内获取 i18n 上下文；未包裹 I18nContextProvider 时返回缺省上下文 */
+declare function useI18n(): I18nContext;
+
+/**
+ * 内置 UI 无关标准动作（设计文档第 17 节，决策 D4）。
+ *
+ * `navigate` / `message` / `confirm` / `overlay.*` 依赖上层模块，
+ * 不在此处实现，由 @pactor-app/router / @pactor-app/ui 的 interaction 层注册。
+ * 已注册的同名动作不会被覆盖。
+ */
+declare function registerBuiltinActions(registry: ActionRegistry): void;
+
+type AnyComponent = ComponentType<any>;
+/**
+ * 组件注册条目：直接注册组件，或以 `{ component, withScope: true }`
+ * 声明组件自行渲染 children（经 `useRenderer().renderChildren`
+ * 注入行 / 项等局部作用域，此时原始 DSL children 以 `dslChildren` prop 传入）。
+ */
+interface ScopedComponentEntry {
+    component: AnyComponent;
+    withScope?: boolean;
+}
+type ComponentEntry = AnyComponent | ScopedComponentEntry;
+interface DslRendererProps {
+    context: RuntimeContext;
+    node?: DslNode;
+    engine?: ActionEngine;
+    /**
+     * 附加子树（最小补充）：渲染在 RendererContextProvider 之内、
+     * DSL 根节点之后，供 OverlayHost 等宿主把扩展 UI 挂进
+     * Renderer 上下文（children 内可 `useRenderer()`）。
+     */
+    children?: ReactNode;
+}
+/**
+ * React Renderer（设计文档第 21 节，决策 D5）。
+ *
+ * 函数式递归渲染：组件一律经 ComponentRegistry 解析（禁止按类型名
+ * 硬编码分支）；props 深度表达式解析；`when` 条件渲染；`events`
+ * 绑定到 Action 引擎；`permission` 经 PermissionAdapter 检查，
+ * 无权限时按 denied 策略处理（hidden 不渲染 / 注入 disabled /
+ * 注入 readOnly）。V1 简化策略：根节点订阅整个 StateStore /
+ * DataStore，任一变化重渲染整棵 DSL 树。
+ */
+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 友好，
+ * 不抛错也不渲染空白。
+ */
+declare function UnsupportedComponent({ type }: {
+    type: string;
+}): react.JSX.Element;
+
+/** Page DSL 校验失败错误：内含结构化错误列表 */
+declare class PageRuntimeError extends Error {
+    readonly errors: DslValidationError[];
+    constructor(errors: DslValidationError[]);
+}
+/**
+ * PageRuntime（设计文档第 20、89 节，决策 D6）：
+ * PageDsl → 校验 → RuntimeContext → 初始化 state / dataSources（autoLoad）
+ * → 生命周期 → 渲染 body 的完整链路。
+ */
+interface PageRuntime {
+    readonly pageDsl: PageDsl;
+    readonly context: RuntimeContext;
+    readonly engine: ActionEngine;
+    /** 初始化完成的 Promise（autoLoad 触发 + onInit + onLoad 执行完毕） */
+    readonly initialized: Promise<void>;
+    /** 是否已销毁 */
+    readonly destroyed: boolean;
+    /** 渲染 body 子树；未配置 body 时渲染空内容 */
+    render(): ReactNode;
+    /** 宿主（Router）触发生命周期：onReady */
+    ready(): Promise<void>;
+    /** 宿主（Router）触发生命周期：onShow */
+    show(): Promise<void>;
+    /** 宿主（Router）触发生命周期：onHide */
+    hide(): Promise<void>;
+    /** 触发 onDestroy 并清理订阅 */
+    destroy(): Promise<void>;
+    /** 订阅生命周期事件，返回退订函数 */
+    onLifecycle(listener: (event: LifecycleEventName) => void): () => void;
+}
+/**
+ * 创建 PageRuntime：
+ * 1. `validatePageDsl` 校验，失败抛 `PageRuntimeError`（含结构化错误列表）
+ * 2. `createRuntimeContext`（page meta + 初始 state + registries / adapters）
+ * 3. 注册 8 个 UI 无关内置动作
+ * 4. 初始化 DataSources，触发 autoLoad
+ * 5. 生命周期：onInit（创建后）→ onLoad（首次加载完成）自动执行；
+ *    onReady / onShow / onHide / onDestroy 由宿主经方法触发
+ */
+declare function createPageRuntime(pageDsl: PageDsl, options?: CreateRuntimeContextOptions): PageRuntime;
+/**
+ * React 组件形式的渲染入口。
+ *
+ * `children`（最小补充，供 OverlayHost 等宿主扩展使用）渲染在
+ * DslRenderer 的 React Context 之内——即页面 body 渲染完成后、
+ * 同一 Renderer 上下文下，因此 children 内的组件可使用
+ * `useRenderer()` 等 Renderer 能力。未传 children 时行为与此前一致。
+ */
+declare function PageRuntimeView({ runtime, children, }: {
+    runtime: PageRuntime;
+    children?: ReactNode;
+}): react.JSX.Element;
+
+interface ResolveDeepOptions {
+    /**
+     * 返回 true 时该对象（及其子树）不求值、原样保留。
+     * Action 引擎用它跳过 params 中内嵌的子动作配置
+     * （`sequence` / `parallel` / `if` 的子动作须在各自执行时
+     * 按当时的 state 求值，不能随父动作提前求值）。
+     */
+    isOpaque?: (value: Record<string, unknown>) => boolean;
+}
+/**
+ * 深度表达式求值（设计文档第 21 节，D5）：
+ *
+ * - 字符串经 @pactor-app/expression `resolveTemplate` 求值
+ *   （整体单表达式保留原始类型，无 `${` 快速返回）
+ * - 数组 / 普通对象递归处理
+ * - 其余类型原样保留
+ */
+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 };