@ticatec/uniface-flexi-module 0.0.2

package/README_CN.md

@@ -0,0 +1,51 @@
+# @ticatec/uniface-flexi-form
+
+为 Svelte 应用程序提供动态表单、条件面板和动态数据表的灵活表单框架。
+
+## 特性
+
+- 🚀 **动态表单生成**：基于 JSON 配置动态创建表单
+- 🎨 **多种字段类型**：支持文本、数字、日期、选择、多选等多种类型
+- 🔍 **条件面板**：高级搜索和筛选功能
+- 📱 **响应式设计**：移动友好和自适应布局
+- 🧩 **模块化架构**：易于扩展自定义组件
+- 🎯 **类型安全**：完整的 TypeScript 支持和全面的类型定义
+- 🎭 **Svelte 5 就绪**：为最新的 Svelte 版本构建
+
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-flexi-form
+```
+
+
+## 使用方法
+
+1. 初始化`FlexContext`，设置通用数据字典加载的接口
+2. 初始化`ModuleLoader`，设置读取动态模块的的加载接口
+3. 初始化`Sandbox`，注入基础类，公共对象等。
+4. 使用ModuleLoader加载指定的动态模块，然后前台展示
+
+
+## 组件
+
+- `FlexiContext` [详情](./FLEXI_CONTEXT_GUIDE_CN.md)
+- `ModuleLoader` [详情](./MODULE_LOADER_CN.md)
+- `Sandbox` [详情](./SANDBOX_CN.md)
+- 动态表单 `FlexiForm` [详情](./FLEXIFORM_GUIDE_CN.md)
+- 条件面板 `FlexiCriteriaSet` [详情](./FLEXICRITERIASET_GUIDE_CN.md)
+- 动态数据表 `FlexiDataTable` [详情](./FLEXIDATATABLE_GUIDE_CN.md)
+- 动态数据展示 **TODO**
+
+## 贡献
+
+我们欢迎贡献！请阅读我们的贡献指南并向我们的仓库提交 pull request。
+
+## 许可证
+
+MIT 许可证 - 详情请见 LICENSE 文件。
+
+## 支持
+
+如需支持和问题咨询，请在我们的 [GitHub 仓库](https://github.com/ticatec-auckland/uniface-flexi-form/issues) 中开启 issue。

package/SANDBOX_CN.md

@@ -0,0 +1,201 @@
+# Sandbox 类文档
+
+`Sandbox` 是一个**单例沙盒执行环境**，用于在隔离的上下文中**安全执行动态 JavaScript 代码**（如用户生成的表单逻辑、插件脚本等）。  
+通过 `Proxy` 代理与 `with` 语句结合，提供受控的变量访问，防止污染全局作用域。
+
+---
+
+## 目录
+- [概述](#概述)
+- [核心机制](#核心机制)
+- [静态方法](#静态方法)
+    - [`initialize`](#initialize)
+- [实例方法](#实例方法)
+    - [`createFormClass`](#createformclass)
+- [使用示例](#使用示例)
+- [安全机制说明](#安全机制说明)
+- [高级用法](#高级用法)
+- [注意事项](#注意事项)
+
+---
+
+## 概述
+
+`Sandbox` 设计目标：
+- 安全执行不受信任的代码
+- 注入指定上下文变量
+- 防止访问未授权的全局对象
+- 提供友好的变量访问体验（类似全局可用）
+
+```ts
+export default class Sandbox { ... }
+```
+
+> 典型应用：动态表单引擎、插件系统、用户自定义逻辑、微前端脚本隔离。
+
+---
+
+## 核心机制
+
+| 机制 | 说明 |
+|------|------|
+| **单例模式** | 全局唯一沙盒实例 |
+| **依赖注入** | 通过 `injectedKeys` 指定可访问变量 |
+| **Proxy 代理** | 控制 `in` 和 `get` 访问行为 |
+| **with + const 解构** | 让注入变量在代码中像全局变量一样使用 |
+| **双重上下文来源** | 支持 `ctx` 和 `ctx.window` 两个来源 |
+
+---
+
+## 静态方法
+
+### `initialize`
+
+初始化 `Sandbox` 单例实例。
+
+```ts
+static initialize(ctx: any, injectedKeys: Array<string>): Sandbox
+```
+
+**参数：**
+- `ctx`: `any` - 基础上下文对象（通常包含工具函数、API 等）
+- `injectedKeys`: `string[]` - 允许注入到沙盒的变量名列表
+
+**返回值：** `Sandbox` 实例
+
+> 必须先调用 `initialize`，否则无法使用 `createFormClass`。
+
+---
+
+## 实例方法
+
+### `createFormClass`
+
+在沙盒中执行代码字符串，生成表单类逻辑。
+
+```ts
+createFormClass(code: string): any
+```
+
+**参数：**
+- `code`: `string` - 要执行的 JS 代码（支持 `return` 一个类或对象）
+
+**返回值：** 代码执行结果（通常是一个类构造函数或配置对象）
+
+**执行流程：**
+1. 提取 `injectedKeys` 中存在的变量 → 注入 `injected`
+2. 合并 `ctx` + `injected` → 形成 `sandboxContext`
+3. 创建 `Proxy` 代理，控制变量访问
+4. 使用 `with (sandbox) { const xxx = sandbox.xxx; ...code }`
+5. 通过 `new Function` 执行包装后的代码
+
+---
+
+## 使用示例
+
+### 1. 基础使用：执行表单验证逻辑
+
+```ts
+import Sandbox from './Sandbox';
+
+// 准备上下文
+const context = {
+    utils: {
+        isEmail: (str) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(str),
+        required: (val) => val != null && val !== ''
+    },
+    api: {
+        submitForm: async (data) => {
+            console.log('提交表单:', data);
+            return { success: true };
+        }
+    },
+    window: window // 允许访问部分全局对象（如 console, Math）
+};
+
+// 定义可注入的变量
+const injectedKeys = ['utils', 'api', 'console', 'Math', 'Date'];
+
+// 初始化沙盒
+Sandbox.initialize(context, injectedKeys);
+
+const sandbox = Sandbox.initialize(context, injectedKeys);
+
+// 用户编写的动态代码
+const userCode = `
+    class UserForm {
+        constructor(data) {
+            this.data = data;
+        }
+
+        validate() {
+            if (!utils.required(this.data.email)) return '邮箱必填';
+            if (!utils.isEmail(this.data.email)) return '邮箱格式错误';
+            return null;
+        }
+
+        async submit() {
+            const error = this.validate();
+            if (error) throw new Error(error);
+            return await api.submitForm(this.data);
+        }
+    }
+
+    return UserForm;
+`;
+
+// 执行并获取类
+const UserFormClass = sandbox.createFormClass(userCode);
+
+// 使用
+const form = new UserFormClass({ email: 'test@example.com' });
+form.submit().then(console.log).catch(console.error);
+```
+
+---
+
+## 安全机制说明
+
+| 机制 | 效果 |
+|------|------|
+| `injectedKeys` 白名单 | 仅允许显式声明的变量可访问 |
+| `Proxy.has` 控制 | `key in sandbox` 行为受控 |
+| `Proxy.get` 警告 | 访问未定义变量时 `console.warn` |
+| 无 `window` 直接暴露 | 必须通过 `injectedKeys` 授权 |
+| `with` + `const` 解构 | 避免 `with` 污染外部作用域 |
+
+> 注意：`new Function` 本身不解析词法作用域，天然隔离外部变量。
+
+---
+
+### 动态注入运行时变量
+
+```ts
+const dynamicCtx = { currentUser: null };
+Sandbox.initialize({ ...context, dynamicCtx }, [...injectedKeys, 'currentUser']);
+
+// 后续更新
+dynamicCtx.currentUser = { id: 1, name: 'Alice' };
+```
+
+---
+
+## 注意事项
+
+| 项目 | 说明 |
+|------|------|
+| **必须初始化** | 未调用 `initialize` 将导致 `instance` 为 `undefined` |
+| **injectedKeys 必须精确** | 多注入风险，少注入功能缺失 |
+| **避免注入危险对象** | 如 `eval`, `Function`, `window.fetch`（视需求） |
+| **性能注意** | `new Function` 有编译开销，建议缓存编译结果 |
+| **不支持 ES6 import** | 动态代码中无法使用 `import`，需通过注入提供 |
+| **调试建议** | 开发时可临时注入 `console` 便于调试 |
+
+---
+
+## API 汇总
+
+| 方法 | 类型 | 描述 |
+|------|------|------|
+| `initialize` | `static` | 初始化沙盒上下文 |
+| `createFormClass` | `instance` | 执行动态代码 |

package/dist/FlexiContext.d.ts

@@ -0,0 +1,28 @@
+export type DictionaryLoad = (dicNames: Array<string>) => Promise<any>;
+export type Dictionaries = {
+    [key: string]: Array<any>;
+};
+export default class FlexiContext {
+    private readonly _dicLoad;
+    private static instance;
+    /**
+     * 初始化Context
+     * @param dictLoad
+     */
+    static initialize(dictLoad: DictionaryLoad): FlexiContext;
+    /**
+     * 获取单例实例
+     */
+    static getInstance(): FlexiContext;
+    /**
+     * 构造函数
+     * @private
+     * @param dictLoad
+     */
+    private constructor();
+    /**
+     * 读取数据字典
+     * @param dicNames
+     */
+    loadDictionaries(dicNames: Array<string> | string): Promise<Dictionaries>;
+}

package/dist/FlexiContext.js

@@ -0,0 +1,45 @@
+import { registerFormFieldBuilder } from "./flexi-form";
+import { registerCriteriaFieldBuilder } from "./criteria-panel";
+export default class FlexiContext {
+    _dicLoad;
+    static instance;
+    /**
+     * 初始化Context
+     * @param dictLoad
+     */
+    static initialize(dictLoad) {
+        if (FlexiContext.instance == null) {
+            console.log('初始化FlexContext');
+            const instance = new FlexiContext(dictLoad);
+            FlexiContext.instance = instance;
+            registerFormFieldBuilder();
+            registerCriteriaFieldBuilder();
+        }
+        return FlexiContext.instance;
+    }
+    /**
+     * 获取单例实例
+     */
+    static getInstance() {
+        if (!FlexiContext.instance) {
+            throw new Error("FlexiContext hasn't been initialized.");
+        }
+        return FlexiContext.instance;
+    }
+    /**
+     * 构造函数
+     * @private
+     * @param dictLoad
+     */
+    constructor(dictLoad) {
+        this._dicLoad = dictLoad;
+    }
+    /**
+     * 读取数据字典
+     * @param dicNames
+     */
+    async loadDictionaries(dicNames) {
+        dicNames = Array.isArray(dicNames) ? dicNames : [dicNames];
+        return dicNames.length > 0 ? await this._dicLoad(dicNames) : {};
+    }
+}

package/dist/ModuleLoader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 模块加载函数的类型定义
+ * @param params - 传递给模块加载器的参数
+ * @returns 返回已加载模块的Promise
+ */
+export type LoadModule = (params: any) => Promise<any>;
+/**
+ * 单例模块加载器，为动态加载的模块提供缓存功能
+ * 确保模块只加载一次，后续请求返回缓存实例
+ */
+export default class ModuleLoader {
+    #private;
+    /**
+     * ModuleLoader的单例实例
+     */
+    private static instance;
+    /**
+     * 按键存储已加载模块的缓存映射
+     */
+    private modules;
+    /**
+     * 私有构造函数，用于强制单例模式
+     * @param loadModule - 处理模块加载的函数
+     */
+    private constructor();
+    /**
+     * 初始化单例ModuleLoader实例
+     * @param loadModule - 处理模块加载的函数
+     * @returns ModuleLoader的单例实例
+     */
+    static initialize(loadModule: LoadModule): ModuleLoader;
+    /**
+     * 通过键加载模块，支持缓存
+     * 如果模块已存在于缓存中，则返回缓存版本
+     * 否则使用提供的loadModule函数加载模块并缓存
+     * @param key - 模块的唯一标识符
+     * @param params - 传递给模块加载器的参数
+     * @returns 返回已加载模块的Promise
+     */
+    load(key: string, params: any): Promise<any>;
+}

package/dist/ModuleLoader.js

@@ -0,0 +1,55 @@
+/**
+ * 单例模块加载器，为动态加载的模块提供缓存功能
+ * 确保模块只加载一次，后续请求返回缓存实例
+ */
+export default class ModuleLoader {
+    /**
+     * ModuleLoader的单例实例
+     */
+    static instance;
+    /**
+     * 私有模块加载函数
+     */
+    #loadModule;
+    /**
+     * 按键存储已加载模块的缓存映射
+     */
+    modules;
+    /**
+     * 私有构造函数，用于强制单例模式
+     * @param loadModule - 处理模块加载的函数
+     */
+    constructor(loadModule) {
+        this.#loadModule = loadModule;
+        this.modules = new Map;
+    }
+    /**
+     * 初始化单例ModuleLoader实例
+     * @param loadModule - 处理模块加载的函数
+     * @returns ModuleLoader的单例实例
+     */
+    static initialize(loadModule) {
+        if (ModuleLoader.instance == null) {
+            ModuleLoader.instance = new ModuleLoader(loadModule);
+        }
+        return ModuleLoader.instance;
+    }
+    /**
+     * 通过键加载模块，支持缓存
+     * 如果模块已存在于缓存中，则返回缓存版本
+     * 否则使用提供的loadModule函数加载模块并缓存
+     * @param key - 模块的唯一标识符
+     * @param params - 传递给模块加载器的参数
+     * @returns 返回已加载模块的Promise
+     */
+    async load(key, params) {
+        if (this.modules.has(key)) {
+            return this.modules.get(key);
+        }
+        else {
+            const module = await this.#loadModule(params);
+            this.modules.set(key, module);
+            return module;
+        }
+    }
+}

package/dist/Sandbox.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 单例沙盒类，用于在隔离环境中安全执行代码
+ * 提供上下文注入和代理机制来控制代码执行环境
+ */
+export default class Sandbox {
+    #private;
+    /**
+     * Sandbox的单例实例
+     */
+    private static instance;
+    /**
+     * 私有构造函数，用于强制单例模式
+     * @param ctx - 沙盒执行上下文
+     * @param injectedKeys - 需要注入的变量键名数组
+     */
+    private constructor();
+    /**
+     * 初始化单例Sandbox实例
+     * @param ctx - 沙盒执行上下文
+     * @param injectedKeys - 需要注入的变量键名数组
+     * @returns Sandbox的单例实例
+     */
+    static initialize(ctx: any, injectedKeys: Array<string>): Sandbox;
+    /**
+     * 在沙盒环境中创建并执行表单类代码
+     * 使用代理模式控制变量访问，确保代码在安全的上下文中执行
+     * @param code - 要执行的JavaScript代码字符串
+     * @param ctx
+     * @param keys
+     * @returns 代码执行结果
+     */
+    createFormClass(code: string, ctx?: any, keys?: Array<string>): any;
+}

package/dist/Sandbox.js

@@ -0,0 +1,101 @@
+import FlexiContext from "./FlexiContext";
+import { ModuleLoader } from "./index";
+import FlexiForm from "./flexi-form/flexi_form/FlexiForm";
+import FlexiCard from "./flexi-form/flexi_card/FlexiCard";
+import FlexiComposite from "./flexi-form/flexi_composite/FlexiComposite";
+import FlexiCriteriaSet from "./criteria-panel/lib/FlexiCriteriaSet";
+import FlexiDataTable from "./flexi-datatable/FlexiDataTable";
+import { Visibility } from "./flexi-form/lib";
+import { FlexiFormDialog } from "./flexi-form";
+import { FlexiFormPage } from "./flexi-form";
+/**
+ * 单例沙盒类，用于在隔离环境中安全执行代码
+ * 提供上下文注入和代理机制来控制代码执行环境
+ */
+export default class Sandbox {
+    /**
+     * 私有上下文对象，包含沙盒执行环境
+     */
+    #ctx;
+    /**
+     * 私有注入键数组，定义需要注入到沙盒的变量名
+     */
+    #injectedKeys;
+    /**
+     * Sandbox的单例实例
+     */
+    static instance;
+    /**
+     * 私有构造函数，用于强制单例模式
+     * @param ctx - 沙盒执行上下文
+     * @param injectedKeys - 需要注入的变量键名数组
+     */
+    constructor(ctx, injectedKeys) {
+        this.#ctx = { ...ctx, Visibility, FlexiContext, ModuleLoader, FlexiForm, FlexiCard, FlexiComposite, FlexiCriteriaSet, FlexiDataTable, FlexiFormPage, FlexiFormDialog };
+        this.#injectedKeys = [...injectedKeys, 'Dialog', 'MessageBox', 'Indicator', 'Toast'];
+    }
+    /**
+     * 初始化单例Sandbox实例
+     * @param ctx - 沙盒执行上下文
+     * @param injectedKeys - 需要注入的变量键名数组
+     * @returns Sandbox的单例实例
+     */
+    static initialize(ctx, injectedKeys) {
+        if (Sandbox.instance == null) {
+            Sandbox.instance = new Sandbox(ctx, injectedKeys);
+        }
+        return Sandbox.instance;
+    }
+    /**
+     * 在沙盒环境中创建并执行表单类代码
+     * 使用代理模式控制变量访问，确保代码在安全的上下文中执行
+     * @param code - 要执行的JavaScript代码字符串
+     * @param ctx
+     * @param keys
+     * @returns 代码执行结果
+     */
+    createFormClass(code, ctx = {}, keys = []) {
+        const injected = {};
+        ctx = { ...this.#ctx, ...ctx };
+        keys = [...new Set([...this.#injectedKeys, ...keys])];
+        for (const key of keys) {
+            if (ctx.window && key in ctx.window) {
+                injected[key] = ctx.window[key];
+            }
+            else if (key in ctx) {
+                injected[key] = ctx[key];
+            }
+        }
+        // 组合最终上下文
+        const sandboxContext = { ...this.#ctx, ...injected };
+        const self = this;
+        const sandbox = new Proxy(sandboxContext, {
+            has(target, key) {
+                // 如果在 sandboxContext 或 window 中存在
+                if (key in target)
+                    return true;
+                if (self.#ctx.window && key in self.#ctx.window)
+                    return true;
+                return false; // 不存在就返回 false
+            },
+            get(target, key) {
+                if (key in target)
+                    return target[key];
+                if (self.#ctx.window && key in self.#ctx.window)
+                    return self.#ctx.window[key];
+                console.warn(`Sandbox: ${String(key)} not found`);
+                return undefined;
+            }
+        });
+        const wrappedCode = `
+    with (sandbox) {
+        ${Object.keys(sandbox).map(k => `const ${k} = sandbox.${k};`).join('\n')}
+        
+        ${code}
+    }
+  `;
+        console.log('sandbox code: ', wrappedCode);
+        const fn = new Function('sandbox', wrappedCode);
+        return fn(sandbox);
+    }
+}

package/dist/criteria-panel/CriteriaFieldsPanel.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">import { onMount } from "svelte";
+import SearchField from "./components/SearchField.svelte";
+export let criteriaSet;
+export let criteria;
+let variant = criteriaSet.variant;
+let fields = [...criteriaSet.fields];
+let arrangement = criteriaSet.arrangement;
+let label$style = criteriaSet.label$style;
+onMount(async () => {
+    criteriaSet.setInvalidateHandler(() => {
+        fields = [...criteriaSet.fields];
+    });
+});
+</script>
+
+<div class="uniface-flexi-criteria-panel {arrangement==='horizontal' ? 'field-layout-horizontal' : ''}">
+    {#if fields}
+        {#each fields as field}
+            {#if field.visible}
+                <SearchField {label$style} size={field.size} label={field.label}>
+                    <svelte:component this={field.component} props={field.props} {...field.keys} events={field.events} {variant} bind:criteria/>
+                </SearchField>
+            {/if}
+        {/each}
+    {/if}
+</div>

package/dist/criteria-panel/CriteriaFieldsPanel.svelte.d.ts

@@ -0,0 +1,22 @@
+import type FlexiCriteriaSet from "./lib/FlexiCriteriaSet";
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: Props & {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const CriteriaFieldsPanel: $$__sveltets_2_IsomorphicComponent<{
+    criteriaSet: FlexiCriteriaSet;
+    criteria: any;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type CriteriaFieldsPanel = InstanceType<typeof CriteriaFieldsPanel>;
+export default CriteriaFieldsPanel;

package/dist/criteria-panel/components/CascadeSelectSearchField.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">import CascadeOptionSelect from "@ticatec/uniface-element/CascadeOptionsSelect";
+export let keyField;
+export let textField;
+export let criteria;
+export let props = null;
+export let variant;
+export let events = null;
+</script>
+
+<CascadeOptionSelect {...props} {...events} {variant} text={criteria[textField]} bind:value={criteria[keyField]}/>

package/dist/criteria-panel/components/CascadeSelectSearchField.svelte.d.ts

@@ -0,0 +1,25 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: Props & {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const CascadeSelectSearchField: $$__sveltets_2_IsomorphicComponent<{
+    keyField: any;
+    textField: any;
+    criteria: any;
+    props?: any;
+    variant: any;
+    events?: any;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type CascadeSelectSearchField = InstanceType<typeof CascadeSelectSearchField>;
+export default CascadeSelectSearchField;

package/dist/criteria-panel/components/DateRangeField.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">import DateRange from "@ticatec/uniface-element/DateRange";
+export let fromField;
+export let toField;
+export let criteria;
+export let props;
+export let variant;
+export let events = null;
+</script>
+
+
+<DateRange {...props} {...events} {variant} bind:fromValue={criteria[fromField]} bind:toValue={criteria[toField]}/>

package/dist/criteria-panel/components/DateRangeField.svelte.d.ts

@@ -0,0 +1,25 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: Props & {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const DateRangeField: $$__sveltets_2_IsomorphicComponent<{
+    fromField: any;
+    toField: any;
+    criteria: any;
+    props: any;
+    variant: any;
+    events?: any;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type DateRangeField = InstanceType<typeof DateRangeField>;
+export default DateRangeField;