@kimposoft/plugin-sdk 0.0.0-stage → 1.1.0-tp.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +9 -0
  3. package/README.md +48 -2
  4. package/package.json +145 -4
  5. package/src/action-designer.ts +267 -0
  6. package/src/attachment-open.ts +574 -0
  7. package/src/attachment-url.ts +235 -0
  8. package/src/auth/index.ts +6 -0
  9. package/src/auth/qrcode.ts +519 -0
  10. package/src/auth/types.ts +261 -0
  11. package/src/display-style.ts +532 -0
  12. package/src/editor-frame.ts +625 -0
  13. package/src/editor-session.ts +1214 -0
  14. package/src/editor-testing.ts +838 -0
  15. package/src/editor.ts +1720 -0
  16. package/src/frame-transport.ts +516 -0
  17. package/src/frontend-routes.ts +99 -0
  18. package/src/hooks.ts +48 -0
  19. package/src/host-caps.ts +93 -0
  20. package/src/i18n.ts +238 -0
  21. package/src/im-panel.ts +132 -0
  22. package/src/image-tools.ts +91 -0
  23. package/src/index.ts +125 -0
  24. package/src/interactive-session.ts +94 -0
  25. package/src/nahida-im.ts +391 -0
  26. package/src/nahida-ws.ts +23 -0
  27. package/src/org-directory.ts +78 -0
  28. package/src/oz-realtime.ts +144 -0
  29. package/src/page.ts +591 -0
  30. package/src/print.ts +393 -0
  31. package/src/surface.ts +310 -0
  32. package/src/theme-mocks.ts +140 -0
  33. package/src/theme.ts +125 -0
  34. package/src/ui-fixtures/attachment.ts +24 -0
  35. package/src/ui-fixtures/confirm.ts +16 -0
  36. package/src/ui-fixtures/entity-picker.ts +24 -0
  37. package/src/ui-fixtures/expression-editor.ts +52 -0
  38. package/src/ui-fixtures/image-cropper.ts +23 -0
  39. package/src/ui-fixtures/index.ts +17 -0
  40. package/src/ui-fixtures/org-tri-picker.ts +19 -0
  41. package/src/ui-fixtures/prompt.ts +19 -0
  42. package/src/ui-fixtures/record-picker.ts +17 -0
  43. package/src/ui-fixtures/template-picker.ts +13 -0
  44. package/src/ui-mocks.ts +264 -0
  45. package/src/ui.ts +491 -0
  46. package/src/workflow-designer.ts +475 -0
@@ -0,0 +1,267 @@
1
+ /**
2
+ * action-designer.ts —— 动作设计器插件(surfaceType='action-designer')的公开契约。
3
+ *
4
+ * 宿主在模板设计器工具栏「动作」(或定时任务设计)里挂载 action-designer surface,并向插件提供:
5
+ * - hostBridge['domain:action-designer']:ActionDesignerHostApi(宿主实现以类型断言绑定本接口);
6
+ * - 组件 prop `input`:ActionDesignerSurfaceInput(模板模式 / 定时任务模式)。
7
+ * 动作行为文档 BehaviorDocument 是插件保存给宿主、宿主动作管线执行的结构。
8
+ *
9
+ * 本文件只承诺列出的方法与字段;宿主实现可能有更多方法,不在公开契约内的不要依赖。
10
+ *
11
+ * 挂载档(1.1.0-tp.5 起第三方可用沙箱档):
12
+ * - 第三方一律在宿主沙箱框架(iframe)里运行。宿主把框架放在一个只在 input.visible 时显示的透明全屏层里,
13
+ * 插件照常自己画遮罩与对话框(position: fixed 相对框架视口,恰好铺满页面);
14
+ * - hostBridge 上的方法全部是远程调用(返回 Promise);`interactiveSession.snapshot` 是挂载时快照,后续变化
15
+ * 经 `onChange` 回调推送,`onChange` 的返回值在沙箱档是 `Promise<() => void>`,用 `disposerOf()` 统一成同步退订;
16
+ * - 沙箱档 `domain:action-designer` 只开放 {@link ACTION_DESIGNER_FRAME_HOST_API_METHODS} 列出的方法,返回值收敛为
17
+ * `{ data, error }` 纯数据;宿主组件类能力(嵌套动作配置面板、表达式宿主、缩略图渲染器)与窗口尺寸记忆不开放。
18
+ */
19
+ import { definePluginSurface, type SurfaceCreateInput, type SurfaceMountResult } from './surface';
20
+ import type { InteractiveSessionHandle } from './interactive-session';
21
+
22
+ /** 宿主 request() 的扁平信封:成功 { data, error:null },失败 { data?, error }。 */
23
+ export interface HostResult<T> {
24
+ data?: T | null;
25
+ error?: { code?: string; message?: string; response?: { data?: unknown } } | null;
26
+ }
27
+
28
+ /** 模板模式作用域(宿主经 input.scope 传入,原样回传给宿主方法)。 */
29
+ export interface ActionDesignerScope {
30
+ appId: string;
31
+ templateId: string;
32
+ templateVersionNo: string;
33
+ designerType?: string;
34
+ pluginId?: string;
35
+ pluginInstanceId?: string;
36
+ }
37
+
38
+ /** 多语言文本:字符串或按 locale 的对象。 */
39
+ export type LocalizedText = string | Record<string, string>;
40
+
41
+ /**
42
+ * 数据动作的标准操作种类(闭集):取数到表单 / 新增 / 修改 / 删除记录。
43
+ * 与 manifest `capabilities.data_actions[].operation_kind`、Go SDK `biz.DataActionKind` 取值一致。
44
+ */
45
+ export type DataActionKind = 'fetch' | 'create' | 'update' | 'delete';
46
+
47
+ /** 数据动作种类闭集(固定顺序)。 */
48
+ export const DATA_ACTION_KINDS: readonly DataActionKind[] = ['fetch', 'create', 'update', 'delete'];
49
+
50
+ /** 判断字符串是否为数据动作种类(大小写敏感)。 */
51
+ export function isDataActionKind(value: unknown): value is DataActionKind {
52
+ return typeof value === 'string' && (DATA_ACTION_KINDS as readonly string[]).includes(value);
53
+ }
54
+
55
+ /** 动作注册中心条目(GET /api/v1/action-registry/actions 的 data.actions[])。 */
56
+ export interface ActionDefinition {
57
+ name: string;
58
+ title: LocalizedText;
59
+ description?: LocalizedText;
60
+ source: string;
61
+ plugin_id?: string;
62
+ capabilities?: {
63
+ asyncable?: boolean;
64
+ side_effecting?: boolean;
65
+ /** 表达式型参数(来源/条件/取值),设计器给表达式编辑槽位。 */
66
+ expression_based?: boolean;
67
+ scheduled_context?: boolean;
68
+ /**
69
+ * 可在用户离开后于后台继续执行:数据写入类(create / update / delete)由宿主按 operation_kind
70
+ * 推导为 true,提取(fetch,含回填本单)恒为 false;其余动作按插件声明。老宿主不下发,缺省视为 false。
71
+ */
72
+ background?: boolean;
73
+ };
74
+ params_schema?: JsonSchema;
75
+ category?: string;
76
+ sort_weight?: number;
77
+ /**
78
+ * 数据动作的操作种类:动作由插件在 manifest `capabilities.data_actions` 声明、且声明插件就是登记插件时,
79
+ * 宿主随动作目录下发;普通动作不带。老宿主不下发本字段。替代设计器可据此识别写节点(create / update / delete)
80
+ * 与取数节点,配置面板仍按 `params_schema['x-editor']`(`extract-v4` / `write-v4`)判定。
81
+ */
82
+ operation_kind?: DataActionKind;
83
+ }
84
+
85
+ /** 参数 schema(动作参数 schema 受限方言,见 Go SDK plugin/paramschema_strict.go)。 */
86
+ export interface JsonSchema {
87
+ type?: string;
88
+ enum?: unknown[];
89
+ default?: unknown;
90
+ description?: string;
91
+ minimum?: number;
92
+ maximum?: number;
93
+ properties?: Record<string, JsonSchema>;
94
+ required?: string[];
95
+ [k: string]: unknown;
96
+ }
97
+
98
+ /**
99
+ * 动作行为文档(与官方设计器保存的结构一致)。
100
+ * 约束:trigger_bindings[].scopes 取 'form' 或 'field:<字段ID>';seq 与 disabled 为零值时不写;
101
+ * 事件键见宿主 getSupportedTriggers(before-save / after-save 已退役)。
102
+ */
103
+ export interface BehaviorDocument {
104
+ trigger_bindings: TriggerBinding[];
105
+ action_groups: { group_id: string; group_guard_id?: string; ordered_node_ids: string[] }[];
106
+ action_nodes: ActionNode[];
107
+ guards: unknown[];
108
+ conditions?: unknown[];
109
+ [k: string]: unknown;
110
+ }
111
+
112
+ export interface TriggerBinding {
113
+ binding_id: string;
114
+ name?: string;
115
+ trigger_event_key?: string;
116
+ trigger_event_keys?: string[];
117
+ scope?: string;
118
+ scopes?: string[];
119
+ ordered_group_ids: string[];
120
+ disabled?: boolean;
121
+ seq?: number;
122
+ [k: string]: unknown;
123
+ }
124
+
125
+ export interface ActionNode {
126
+ node_id: string;
127
+ action_name: string;
128
+ source?: string;
129
+ name?: string;
130
+ disabled?: boolean;
131
+ params?: Record<string, unknown>;
132
+ children_node_ids?: string[];
133
+ [k: string]: unknown;
134
+ }
135
+
136
+ /** 动作文档信封(GET/PUT .../action-document 的 data)。 */
137
+ export interface ActionDocumentEnvelope {
138
+ template_id: string;
139
+ template_version_no: string;
140
+ /** 动作文档原文:宿主透传不做类型保证,插件按 BehaviorDocument 结构解析(可能为 null)。 */
141
+ actions: unknown;
142
+ checksum?: string;
143
+ content_revision: number;
144
+ version_no: number;
145
+ }
146
+
147
+ export interface TemplateTable {
148
+ data_table_id: string;
149
+ table_name: string;
150
+ table_role?: string;
151
+ }
152
+
153
+ export interface TemplateField {
154
+ field_id: string;
155
+ field_name: string;
156
+ data_type: string;
157
+ }
158
+
159
+ /** domain:action-designer 公开方法。 */
160
+ export interface ActionDesignerHostApi {
161
+ openActionDocument(scope: ActionDesignerScope): Promise<HostResult<ActionDocumentEnvelope>>;
162
+ saveActionDocument(
163
+ scope: ActionDesignerScope,
164
+ body: { actions: unknown; expectedVersionNo: number }
165
+ ): Promise<HostResult<ActionDocumentEnvelope>>;
166
+ listActionRegistry(): Promise<HostResult<{ actions: ActionDefinition[] }>>;
167
+ getSupportedTriggers(pluginId: string): Promise<string[] | null>;
168
+ listTemplateTables(appId: string, templateId: string, versionNo?: string): Promise<HostResult<{ items: TemplateTable[] }>>;
169
+ listTemplateFields(
170
+ appId: string,
171
+ templateId: string,
172
+ versionNo: string | undefined,
173
+ dataTableId: string
174
+ ): Promise<HostResult<{ items: TemplateField[] }>>;
175
+ /** 定时任务模式(input.kind='job')读取任务持有的动作文档(tp.5 起列入公开契约)。 */
176
+ openJobActionDocument?(appId: string, jobId: string): Promise<HostResult<ActionDocumentEnvelope>>;
177
+ /** 定时任务模式保存(CAS:expectedVersionNo 为打开时的 version_no)。 */
178
+ saveJobActionDocument?(
179
+ appId: string,
180
+ jobId: string,
181
+ body: { actions: unknown; expectedVersionNo: number }
182
+ ): Promise<HostResult<ActionDocumentEnvelope>>;
183
+ /** 列出本应用的模板(可按关键字过滤),供「跨模板」类动作选目标模板。 */
184
+ listAppTemplates?(appId: string, keyword?: string): Promise<HostResult<unknown>>;
185
+ /** 列出模板绑定的流程(流程类动作选流程)。 */
186
+ listTemplateWorkflows?(appId: string, templateId: string): Promise<HostResult<unknown>>;
187
+ /**
188
+ * 取本应用的应用树(与左侧菜单同一棵树,形状 `{ root }`,节点 node_type 为 root / category / resource),
189
+ * 供选模板时按「分类 → 模板」分组展示(additive)。老宿主没有本方法,调用前先判存在,缺省时退化为平铺。
190
+ */
191
+ fetchAppTree?(appId: string): Promise<HostResult<unknown>>;
192
+ }
193
+
194
+ /** 沙箱档宿主为 domain:action-designer 开放的方法白名单(与宿主沙箱档实现同口径)。 */
195
+ export const ACTION_DESIGNER_FRAME_HOST_API_METHODS = [
196
+ 'openActionDocument',
197
+ 'saveActionDocument',
198
+ 'openJobActionDocument',
199
+ 'saveJobActionDocument',
200
+ 'listActionRegistry',
201
+ 'getSupportedTriggers',
202
+ 'listTemplateTables',
203
+ 'listTemplateFields',
204
+ 'listAppTemplates',
205
+ 'listTemplateWorkflows',
206
+ 'fetchAppTree'
207
+ ] as const;
208
+
209
+ /**
210
+ * 宿主经组件 prop `input` 传入的业务形状。设计器需自己绘制弹窗(宿主不提供外壳),用 visible 控制显隐,
211
+ * 关闭前调用 requestClose()(宿主负责未保存确认,确认框 z-index 2001,插件遮罩须低于该值)。
212
+ */
213
+ export type ActionDesignerSurfaceInput =
214
+ | {
215
+ kind: 'template';
216
+ scope: ActionDesignerScope;
217
+ visible: boolean;
218
+ title?: string;
219
+ requestClose: () => Promise<boolean>;
220
+ interactiveSessionOwnership: 'inherited' | 'owned';
221
+ }
222
+ | {
223
+ kind: 'job';
224
+ appId: string;
225
+ jobId: string;
226
+ jobName?: string;
227
+ visible: boolean;
228
+ title?: string;
229
+ requestClose: () => Promise<boolean>;
230
+ interactiveSessionOwnership: 'inherited' | 'owned';
231
+ };
232
+
233
+ /**
234
+ * defineActionDesignerSurface —— 动作设计器专用的 definePluginSurface(tp.5 起):两种挂载档写法一致,
235
+ * 沙箱档自动启动框架运行时并做前端域自检(action-designer 需 frontend.surface + frontend.interactive-session)。
236
+ * 工厂拿到宿主 input(组件 prop `input` 的值)、`domain:action-designer` 与交互会话;缺任一能力即抛错(快速失败)。
237
+ */
238
+ export function defineActionDesignerSurface(
239
+ factory: (ctx: {
240
+ input: SurfaceCreateInput;
241
+ surfaceInput: ActionDesignerSurfaceInput | undefined;
242
+ hostApi: ActionDesignerHostApi;
243
+ interactiveSession: InteractiveSessionHandle;
244
+ }) => SurfaceMountResult
245
+ ): (input: SurfaceCreateInput) => SurfaceMountResult {
246
+ return definePluginSurface((input: SurfaceCreateInput) => {
247
+ if ((input.surfaceType as string) !== 'action-designer') {
248
+ throw new Error(`defineActionDesignerSurface: unsupported surface ${String(input.surfaceType)}`);
249
+ }
250
+ const bridge = (input.hostBridge ?? {}) as Record<string, unknown>;
251
+ const read = (key: string): unknown => {
252
+ try {
253
+ return bridge[key];
254
+ } catch {
255
+ // 宿主按 host_caps 裁剪的 Proxy 读未声明键会抛错:视为缺失。
256
+ return undefined;
257
+ }
258
+ };
259
+ const hostApi = read('domain:action-designer') as ActionDesignerHostApi | undefined;
260
+ const interactiveSession = read('interactiveSession') as InteractiveSessionHandle | undefined;
261
+ if (!hostApi || !interactiveSession) {
262
+ throw new Error('defineActionDesignerSurface: host_caps must include domain:action-designer and platform.interactiveSession');
263
+ }
264
+ const props = (input.props ?? {}) as Record<string, unknown>;
265
+ return factory({ input, surfaceInput: props.input as ActionDesignerSurfaceInput | undefined, hostApi, interactiveSession });
266
+ });
267
+ }