@pactor-app/ui 0.1.0

package/dist/interaction/index.d.cts

@@ -0,0 +1,178 @@
+import { DslNode, PageDsl } from '@pactor-app/core';
+import { ActionRegistry } from '@pactor-app/runtime';
+import * as React from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Overlay 打开配置（设计文档第 45 节，决策 D1）。
+ *
+ * 统一 `overlay.open`：modal / drawer 共用同一配置结构；
+ * `content` 为内联 DSL 子树，`page` 为动态页面引用，二者取其一。
+ */
+interface OverlayConfig {
+    /** 弹层类型 */
+    type: 'modal' | 'drawer';
+    /** 标题（antd Modal title / Drawer title） */
+    title?: string;
+    /** 宽度（antd Modal width / Drawer size，v6 起 Drawer width 废弃） */
+    width?: number | string;
+    /** 内联 DSL 内容，经 @pactor-app/runtime Renderer 渲染 */
+    content?: DslNode;
+    /** 动态页面：经 OverlayHost 注入的 resolvePage(pageId) 加载渲染 */
+    page?: {
+        pageId: string;
+    };
+    /** 传入 overlay 内容作用域的 `params` 键 */
+    params?: Record<string, unknown>;
+}
+/** 堆栈条目：配置 + 生成的 id */
+interface OverlayEntry extends OverlayConfig {
+    id: string;
+}
+/** 堆栈变化监听器：open / close 时以最新堆栈快照回调 */
+type OverlayListener = (stack: readonly OverlayEntry[]) => void;
+/**
+ * 取消语义 payload：UI 取消（X / 蒙层 / 取消按钮）或不携带 payload
+ * 的 close 以此值 resolve open 返回的 Promise。
+ */
+declare const OVERLAY_CANCEL_PAYLOAD: {
+    readonly success: false;
+};
+/**
+ * OverlayManager（设计文档第 44–46 节，决策 D1）：零 React 的
+ * Overlay 堆栈状态与 Promise 模型，可纯 Node 测试。
+ *
+ * - `open` 生成 id、入栈、通知订阅者，返回 Promise；
+ *   `close` 时以 payload resolve（缺省 payload 为取消语义
+ *   `{ success: false }`）
+ * - 嵌套即堆栈：连续 open 依次压栈，`close()` 缺省关闭栈顶
+ * - `parentScope` 为打开时刻父页面作用域的浅快照（只读约定），
+ *   供 overlay 内容以 `parent` 键访问
+ */
+declare class OverlayManager {
+    private readonly pending;
+    private readonly listeners;
+    private counter;
+    /** 缓存的堆栈快照：变化时才更换引用，供 useSyncExternalStore 使用 */
+    private snapshot;
+    /**
+     * 打开 overlay：入栈、通知，返回 Promise——close 时以 payload
+     * resolve；取消关闭（无 payload）resolve `{ success: false }`。
+     * `options.parentScope` 记录打开时刻的父作用域浅快照。
+     */
+    open(config: OverlayConfig, options?: {
+        parentScope?: Record<string, unknown>;
+    }): Promise<unknown>;
+    /**
+     * 关闭 overlay 并以 payload resolve 对应的 open Promise：
+     * - `close(id, payload)`：关闭指定条目，原样 resolve payload
+     *   （payload 缺省为取消语义 `{ success: false }`）
+     * - `close(payload)`：关闭栈顶，原样 resolve payload
+     * - `close()`：关闭栈顶，取消语义
+     * 未命中任何条目时为受控 no-op，不抛错。
+     */
+    close(idOrPayload?: string | unknown, payload?: unknown): void;
+    /** 当前堆栈快照（打开顺序，栈顶在末尾）；引用在堆栈不变时保持稳定 */
+    stack(): readonly OverlayEntry[];
+    /** 打开时记录的父作用域浅快照（只读约定）；未知 id 返回 undefined */
+    parentScopeOf(id: string): Record<string, unknown> | undefined;
+    /** 订阅堆栈变化（open / close 时通知），返回退订函数 */
+    subscribe(listener: OverlayListener): () => void;
+    /** 重建快照并通知订阅者 */
+    private commit;
+}
+
+/**
+ * modal 实例（结构化类型，仅声明本包用到的 API）：
+ * 由 InteractionProvider（shadcn 实现为 ShadcnInteractionProvider）
+ * 在 mount 时注入 UiBridge。
+ */
+interface UiModal {
+    confirm(config: {
+        title?: unknown;
+        content?: unknown;
+        onOk?: () => void;
+        onCancel?: () => void;
+    }): unknown;
+}
+/** message 实例（结构化类型）：toast 反馈四态 */
+interface UiMessage {
+    success(content: unknown): unknown;
+    error(content: unknown): unknown;
+    info(content: unknown): unknown;
+    warning(content: unknown): unknown;
+}
+/**
+ * UiBridge（决策 D3）：manager 旁路的可变引用，
+ * InteractionProvider 在 mount 时赋值、unmount 时清空；
+ * `confirm` / `message` 动作经它调用 UI 层 API，未注入时返回
+ * 受控失败而非抛出。
+ */
+interface UiBridge {
+    modal?: UiModal;
+    message?: UiMessage;
+}
+/** 创建空 UiBridge：传给 registerInteractionActions 与 InteractionProvider */
+declare function createUiBridge(): UiBridge;
+/**
+ * 注册交互动作（设计文档第 45、48 节，决策 D3）：
+ *
+ * - `overlay.open`：`params.overlay`（配置字段表达式已求值，content
+ *   DslNode 子树保留给渲染层求值）→ `manager.open`，close payload
+ *   作为动作 data 返回；父页面作用域浅快照记入 parentScope
+ * - `overlay.close`：`params.id`（缺省栈顶）+ `params.payload`
+ *   （缺省取消语义 `{ success: false }`）→ `manager.close`
+ * - `confirm`：`params.title` / `params.content` → UiBridge 注入的
+ *   modal.confirm，确认返回 data `true`，取消返回 `false`；UiBridge
+ *   未注入 modal 时返回 `{ ok: false }` 受控失败
+ * - `message`：`params.type`（success / error / info / warning，缺省
+ *   info）+ `params.text` → UiBridge 注入的 message；未注入时受控失败
+ *
+ * 已注册的同名动作不会被覆盖（与 registerBuiltinActions 同约定）。
+ */
+declare function registerInteractionActions(actions: ActionRegistry, manager: OverlayManager, ui: UiBridge): void;
+
+interface InteractionProviderProps {
+    /** registerInteractionActions 使用的同一 UiBridge（可变引用） */
+    bridge: UiBridge;
+    children?: ReactNode;
+}
+/**
+ * ShadcnInteractionProvider：与 pactor-interaction 的 InteractionProvider
+ * （antd 版）契约一致——mount 时向 UiBridge 注入自绘实现：
+ *
+ * - `modal.confirm({ title, content, onOk, onCancel })`：vendored shadcn
+ *   Dialog 渲染确认框，确定/取消回调后关闭（先关闭再回调，时序对齐 antd
+ *   Modal.confirm）；
+ * - `message.{success,error,info,warning}`：toast 栈（容器固定右上角，
+ *   自动约 3s 消失，类型色条读语义令牌）。
+ *
+ * unmount 时清空 bridge，动作退化为受控失败（与 antd 版相同）。
+ */
+declare function ShadcnInteractionProvider({ bridge, children, }: InteractionProviderProps): React.JSX.Element;
+
+/**
+ * page overlay 的页面加载函数（通常包装 @pactor-app/resource loader）：
+ * pageId → PageDsl（可异步）。
+ */
+type ResolvePageFn = (pageId: string) => PageDsl | Promise<PageDsl>;
+interface OverlayHostProps {
+    manager: OverlayManager;
+    /** page 类型 overlay 的页面加载函数；未注入时 page overlay 渲染受控错误提示 */
+    resolvePage?: ResolvePageFn;
+}
+/**
+ * ShadcnOverlayHost：与 pactor-interaction 的 OverlayHost（antd 版）契约一致——
+ * 订阅同一 OverlayManager 堆栈逐条渲染；type 为 modal 用 vendored shadcn
+ * Dialog、drawer 用自绘固定右侧面板 + 遮罩（无 drawer 原语）；title/width
+ * 原样应用；UI 取消（X / 遮罩 / Escape）触发取消语义 close（resolve
+ * `{ success: false }`）。
+ *
+ * 与 antd 版相同：必须位于 PageRuntime 的 React Context 之内；DSL content
+ * 经当前 Renderer 的 `renderChildren` 渲染，作用域注入
+ * `{ params: entry.params, parent: 父作用域快照 }`；page overlay 经注入的
+ * resolvePage 加载并创建共享宿主 registries 的子 PageRuntime。
+ */
+declare function ShadcnOverlayHost({ manager, resolvePage }: OverlayHostProps): React.JSX.Element;
+
+export { type InteractionProviderProps, OVERLAY_CANCEL_PAYLOAD, type OverlayConfig, type OverlayEntry, type OverlayHostProps, type OverlayListener, OverlayManager, type ResolvePageFn, ShadcnInteractionProvider, ShadcnOverlayHost, type UiBridge, type UiMessage, type UiModal, createUiBridge, registerInteractionActions };

package/dist/interaction/index.d.ts

@@ -0,0 +1,178 @@
+import { DslNode, PageDsl } from '@pactor-app/core';
+import { ActionRegistry } from '@pactor-app/runtime';
+import * as React from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Overlay 打开配置（设计文档第 45 节，决策 D1）。
+ *
+ * 统一 `overlay.open`：modal / drawer 共用同一配置结构；
+ * `content` 为内联 DSL 子树，`page` 为动态页面引用，二者取其一。
+ */
+interface OverlayConfig {
+    /** 弹层类型 */
+    type: 'modal' | 'drawer';
+    /** 标题（antd Modal title / Drawer title） */
+    title?: string;
+    /** 宽度（antd Modal width / Drawer size，v6 起 Drawer width 废弃） */
+    width?: number | string;
+    /** 内联 DSL 内容，经 @pactor-app/runtime Renderer 渲染 */
+    content?: DslNode;
+    /** 动态页面：经 OverlayHost 注入的 resolvePage(pageId) 加载渲染 */
+    page?: {
+        pageId: string;
+    };
+    /** 传入 overlay 内容作用域的 `params` 键 */
+    params?: Record<string, unknown>;
+}
+/** 堆栈条目：配置 + 生成的 id */
+interface OverlayEntry extends OverlayConfig {
+    id: string;
+}
+/** 堆栈变化监听器：open / close 时以最新堆栈快照回调 */
+type OverlayListener = (stack: readonly OverlayEntry[]) => void;
+/**
+ * 取消语义 payload：UI 取消（X / 蒙层 / 取消按钮）或不携带 payload
+ * 的 close 以此值 resolve open 返回的 Promise。
+ */
+declare const OVERLAY_CANCEL_PAYLOAD: {
+    readonly success: false;
+};
+/**
+ * OverlayManager（设计文档第 44–46 节，决策 D1）：零 React 的
+ * Overlay 堆栈状态与 Promise 模型，可纯 Node 测试。
+ *
+ * - `open` 生成 id、入栈、通知订阅者，返回 Promise；
+ *   `close` 时以 payload resolve（缺省 payload 为取消语义
+ *   `{ success: false }`）
+ * - 嵌套即堆栈：连续 open 依次压栈，`close()` 缺省关闭栈顶
+ * - `parentScope` 为打开时刻父页面作用域的浅快照（只读约定），
+ *   供 overlay 内容以 `parent` 键访问
+ */
+declare class OverlayManager {
+    private readonly pending;
+    private readonly listeners;
+    private counter;
+    /** 缓存的堆栈快照：变化时才更换引用，供 useSyncExternalStore 使用 */
+    private snapshot;
+    /**
+     * 打开 overlay：入栈、通知，返回 Promise——close 时以 payload
+     * resolve；取消关闭（无 payload）resolve `{ success: false }`。
+     * `options.parentScope` 记录打开时刻的父作用域浅快照。
+     */
+    open(config: OverlayConfig, options?: {
+        parentScope?: Record<string, unknown>;
+    }): Promise<unknown>;
+    /**
+     * 关闭 overlay 并以 payload resolve 对应的 open Promise：
+     * - `close(id, payload)`：关闭指定条目，原样 resolve payload
+     *   （payload 缺省为取消语义 `{ success: false }`）
+     * - `close(payload)`：关闭栈顶，原样 resolve payload
+     * - `close()`：关闭栈顶，取消语义
+     * 未命中任何条目时为受控 no-op，不抛错。
+     */
+    close(idOrPayload?: string | unknown, payload?: unknown): void;
+    /** 当前堆栈快照（打开顺序，栈顶在末尾）；引用在堆栈不变时保持稳定 */
+    stack(): readonly OverlayEntry[];
+    /** 打开时记录的父作用域浅快照（只读约定）；未知 id 返回 undefined */
+    parentScopeOf(id: string): Record<string, unknown> | undefined;
+    /** 订阅堆栈变化（open / close 时通知），返回退订函数 */
+    subscribe(listener: OverlayListener): () => void;
+    /** 重建快照并通知订阅者 */
+    private commit;
+}
+
+/**
+ * modal 实例（结构化类型，仅声明本包用到的 API）：
+ * 由 InteractionProvider（shadcn 实现为 ShadcnInteractionProvider）
+ * 在 mount 时注入 UiBridge。
+ */
+interface UiModal {
+    confirm(config: {
+        title?: unknown;
+        content?: unknown;
+        onOk?: () => void;
+        onCancel?: () => void;
+    }): unknown;
+}
+/** message 实例（结构化类型）：toast 反馈四态 */
+interface UiMessage {
+    success(content: unknown): unknown;
+    error(content: unknown): unknown;
+    info(content: unknown): unknown;
+    warning(content: unknown): unknown;
+}
+/**
+ * UiBridge（决策 D3）：manager 旁路的可变引用，
+ * InteractionProvider 在 mount 时赋值、unmount 时清空；
+ * `confirm` / `message` 动作经它调用 UI 层 API，未注入时返回
+ * 受控失败而非抛出。
+ */
+interface UiBridge {
+    modal?: UiModal;
+    message?: UiMessage;
+}
+/** 创建空 UiBridge：传给 registerInteractionActions 与 InteractionProvider */
+declare function createUiBridge(): UiBridge;
+/**
+ * 注册交互动作（设计文档第 45、48 节，决策 D3）：
+ *
+ * - `overlay.open`：`params.overlay`（配置字段表达式已求值，content
+ *   DslNode 子树保留给渲染层求值）→ `manager.open`，close payload
+ *   作为动作 data 返回；父页面作用域浅快照记入 parentScope
+ * - `overlay.close`：`params.id`（缺省栈顶）+ `params.payload`
+ *   （缺省取消语义 `{ success: false }`）→ `manager.close`
+ * - `confirm`：`params.title` / `params.content` → UiBridge 注入的
+ *   modal.confirm，确认返回 data `true`，取消返回 `false`；UiBridge
+ *   未注入 modal 时返回 `{ ok: false }` 受控失败
+ * - `message`：`params.type`（success / error / info / warning，缺省
+ *   info）+ `params.text` → UiBridge 注入的 message；未注入时受控失败
+ *
+ * 已注册的同名动作不会被覆盖（与 registerBuiltinActions 同约定）。
+ */
+declare function registerInteractionActions(actions: ActionRegistry, manager: OverlayManager, ui: UiBridge): void;
+
+interface InteractionProviderProps {
+    /** registerInteractionActions 使用的同一 UiBridge（可变引用） */
+    bridge: UiBridge;
+    children?: ReactNode;
+}
+/**
+ * ShadcnInteractionProvider：与 pactor-interaction 的 InteractionProvider
+ * （antd 版）契约一致——mount 时向 UiBridge 注入自绘实现：
+ *
+ * - `modal.confirm({ title, content, onOk, onCancel })`：vendored shadcn
+ *   Dialog 渲染确认框，确定/取消回调后关闭（先关闭再回调，时序对齐 antd
+ *   Modal.confirm）；
+ * - `message.{success,error,info,warning}`：toast 栈（容器固定右上角，
+ *   自动约 3s 消失，类型色条读语义令牌）。
+ *
+ * unmount 时清空 bridge，动作退化为受控失败（与 antd 版相同）。
+ */
+declare function ShadcnInteractionProvider({ bridge, children, }: InteractionProviderProps): React.JSX.Element;
+
+/**
+ * page overlay 的页面加载函数（通常包装 @pactor-app/resource loader）：
+ * pageId → PageDsl（可异步）。
+ */
+type ResolvePageFn = (pageId: string) => PageDsl | Promise<PageDsl>;
+interface OverlayHostProps {
+    manager: OverlayManager;
+    /** page 类型 overlay 的页面加载函数；未注入时 page overlay 渲染受控错误提示 */
+    resolvePage?: ResolvePageFn;
+}
+/**
+ * ShadcnOverlayHost：与 pactor-interaction 的 OverlayHost（antd 版）契约一致——
+ * 订阅同一 OverlayManager 堆栈逐条渲染；type 为 modal 用 vendored shadcn
+ * Dialog、drawer 用自绘固定右侧面板 + 遮罩（无 drawer 原语）；title/width
+ * 原样应用；UI 取消（X / 遮罩 / Escape）触发取消语义 close（resolve
+ * `{ success: false }`）。
+ *
+ * 与 antd 版相同：必须位于 PageRuntime 的 React Context 之内；DSL content
+ * 经当前 Renderer 的 `renderChildren` 渲染，作用域注入
+ * `{ params: entry.params, parent: 父作用域快照 }`；page overlay 经注入的
+ * resolvePage 加载并创建共享宿主 registries 的子 PageRuntime。
+ */
+declare function ShadcnOverlayHost({ manager, resolvePage }: OverlayHostProps): React.JSX.Element;
+
+export { type InteractionProviderProps, OVERLAY_CANCEL_PAYLOAD, type OverlayConfig, type OverlayEntry, type OverlayHostProps, type OverlayListener, OverlayManager, type ResolvePageFn, ShadcnInteractionProvider, ShadcnOverlayHost, type UiBridge, type UiMessage, type UiModal, createUiBridge, registerInteractionActions };

package/dist/interaction/index.js

@@ -0,0 +1,19 @@
+import {
+  OVERLAY_CANCEL_PAYLOAD,
+  OverlayManager,
+  ShadcnInteractionProvider,
+  ShadcnOverlayHost,
+  createUiBridge,
+  registerInteractionActions
+} from "../chunk-OH3U6PCM.js";
+import "../chunk-QDTVOJ5P.js";
+import "../chunk-QWZ23QLS.js";
+import "../chunk-RQHJBTEU.js";
+export {
+  OVERLAY_CANCEL_PAYLOAD,
+  OverlayManager,
+  ShadcnInteractionProvider,
+  ShadcnOverlayHost,
+  createUiBridge,
+  registerInteractionActions
+};