@ticatec/uniface-flexi-module 0.0.2

package/FLEXI_CONTEXT_GUIDE_CN.md

@@ -0,0 +1,172 @@
+# FlexiContext 类文档
+
+`FlexiContext` 是一个用于管理数据字典加载的单例上下文类，采用 TypeScript 实现。它通过异步方式加载指定的数据字典，并提供统一的访问接口。
+
+---
+
+## 目录
+- [概述](#概述)
+- [类型定义](#类型定义)
+- [静态方法](#静态方法)
+    - [`initialize`](#initialize)
+    - [`getInstance`](#getinstance)
+- [实例方法](#实例方法)
+    - [`loadDictionaries`](#loaddictionaries)
+- [使用示例](#使用示例)
+- [注意事项](#注意事项)
+
+---
+
+## 概述
+
+`FlexiContext` 是一个全局单例类，用于统一管理数据字典的加载逻辑。  
+它依赖一个外部传入的 `DictionaryLoad` 函数来实际执行字典数据的获取。
+
+```ts
+export type DictionaryLoad = (dicNames: Array<string>) => Promise<any>;
+export type Dictionaries = { [key: string]: Array<any> };
+```
+
+---
+
+## 类型定义
+
+| 类型 | 说明 |
+|------|------|
+| `DictionaryLoad` | 字典加载函数，接收字典名称数组，返回 `Promise<any>` |
+| `Dictionaries` | 返回的字典数据结构，键为字典名，值为对应数据数组 |
+
+---
+
+## 静态方法
+
+### `initialize`
+
+初始化 `FlexiContext` 单例。
+
+```ts
+static initialize(dictLoad: DictionaryLoad): FlexiContext
+```
+
+**参数：**
+- `dictLoad`: `DictionaryLoad` - 用于实际加载字典数据的函数
+
+**返回值：** `FlexiContext` 实例
+
+> 必须在调用 `getInstance()` 前先执行 `initialize`，否则会抛出错误。
+
+---
+
+### `getInstance`
+
+获取已初始化的单例实例。
+
+```ts
+static getInstance(): FlexiContext
+```
+
+**返回值：** `FlexiContext` 实例
+
+**异常：**
+- 若未调用 `initialize` 初始化，将抛出错误：
+  ```
+  Error: FlexiContext hasn't been initialized.
+  ```
+
+---
+
+## 实例方法
+
+### `loadDictionaries`
+
+异步加载一个或多个数据字典。
+
+```ts
+async loadDictionaries(dicNames: Array<string> | string): Promise<Dictionaries>
+```
+
+**参数：**
+- `dicNames`: `string[] | string` - 要加载的字典名称（支持单个字符串或数组）
+
+**返回值：** `Promise<Dictionaries>`  
+返回一个对象，键为字典名称，值为对应的数据数组。
+
+**行为：**
+- 若传入空数组或空字符串，返回空对象 `{}`。
+- 自动将单个字符串转换为数组处理。
+
+---
+
+## 使用示例
+
+### 1. 初始化与基本使用
+
+```ts
+import FlexiContext from './FlexiContext';
+
+// 定义字典加载函数（实际项目中可能从 API 获取）
+const dictLoad: DictionaryLoad = async (dicNames: string[]) => {
+    console.log('正在加载字典:', dicNames);
+    // 模拟 API 调用
+    const mockData: any = {
+        'gender': [
+            { value: 1, label: '男' },
+            { value: 2, label: '女' }
+        ],
+        'status': [
+            { value: 0, label: '禁用' },
+            { value: 1, label: '启用' }
+        ]
+    };
+    return dicNames.reduce((acc, name) => {
+        acc[name] = mockData[name] || [];
+        return acc;
+    }, {} as any);
+};
+
+// 初始化
+FlexiContext.initialize(dictLoad);
+
+// 获取实例
+const context = FlexiContext.getInstance();
+
+// 加载字典
+async function loadData() {
+    const dicts = await context.loadDictionaries(['gender', 'status']);
+    console.log(dicts);
+    // 输出:
+    // {
+    //   gender: [ { value: 1, label: '男' }, { value: 2, label: '女' } ],
+    //   status: [ { value: 0, label: '禁用' }, { value: 1, label: '启用' } ]
+    // }
+}
+
+loadData();
+```
+
+### 2. 加载单个字典
+
+```ts
+const dict = await context.loadDictionaries('gender');
+console.log(dict.gender); // [{ value: 1, label: '男' }, ...]
+```
+
+---
+
+## 注意事项
+
+1. **必须先初始化**  
+   在使用 `getInstance()` 前必须调用 `initialize`，否则会抛出异常。
+
+2. **单例模式**  
+   多次调用 `initialize` 只会生效第一次，后续调用返回同一实例。
+
+3. **字典加载函数责任**  
+   `dictLoad` 函数需自行处理：
+    - 网络请求
+    - 缓存策略
+    - 错误处理
+    - 数据格式标准化
+
+4. **空输入处理**  
+   传入空数组或空字符串将返回 `{}`，不会触发实际加载。

package/MODULE_LOADER_CN.md

@@ -0,0 +1,228 @@
+# ModuleLoader 类文档
+
+`ModuleLoader` 是一个**单例模块加载器**，用于动态加载模块并提供**缓存机制**，确保同一模块只加载一次，后续请求直接返回缓存实例。适用于按需加载组件、插件、微前端模块等场景。
+
+---
+
+## 目录
+- [概述](#概述)
+- [类型定义](#类型定义)
+- [静态方法](#静态方法)
+    - [`initialize`](#initialize)
+- [实例方法](#实例方法)
+    - [`load`](#load)
+- [使用示例](#使用示例)
+- [高级用法](#高级用法)
+- [注意事项](#注意事项)
+
+---
+
+## 概述
+
+`ModuleLoader` 采用 **单例模式 + 依赖注入** 设计，通过外部传入的 `loadModule` 函数实现模块的实际加载逻辑，内部使用 `Map` 实现高效缓存。可以配合`Sandbox`一起使用，实现动态代码的加载和实现。
+
+```ts
+export type LoadModule = (params: any) => Promise<any>;
+```
+
+> 典型应用场景：动态加载远程组件、微前端模块、懒加载插件等。
+
+---
+
+## 类型定义
+
+| 类型 | 说明 |
+|------|------|
+| `LoadModule` | 模块加载函数，接收任意参数，返回 `Promise<any>` |
+
+---
+
+## 静态方法
+
+### `initialize`
+
+初始化 `ModuleLoader` 单例实例。
+
+```ts
+static initialize(loadModule: LoadModule): ModuleLoader
+```
+
+**参数：**
+- `loadModule`: `LoadModule` - 实际执行模块加载的函数
+
+**返回值：** `ModuleLoader` 实例
+
+> 必须先调用 `initialize`，后续才能使用 `load` 方法。
+
+---
+
+## 实例方法
+
+### `load`
+
+通过唯一键加载模块，支持缓存。
+
+```ts
+async load(key: string, params: any): Promise<any>
+```
+
+**参数：**
+- `key`: `string` - 模块的唯一标识符（用于缓存）
+- `params`: `any` - 传递给 `loadModule` 函数的参数
+
+**返回值：** `Promise<any>` - 已加载的模块实例
+
+**行为：**
+1. 若缓存中已存在 `key` → 直接返回缓存模块
+2. 否则调用 `this.#loadModule(params)` 加载 → 缓存结果 → 返回
+
+---
+
+## 使用示例
+
+### 1. 基础使用：动态加载远程组件
+
+```ts
+import ModuleLoader, {LoadModule} from '@ticatec/uniface-flexi-module/ModuleLoader';
+import Sandbox from "@ticatec/uniface-flexi-module/Sandbox";
+import axios from "axios";
+
+// 定义模块加载函数（例如使用 import() 动态导入）
+const loadModule: LoadModule = async (params: any) => {
+    return axios.get('./scripts', {params})
+};
+
+// 初始化 ModuleLoader
+ModuleLoader.initialize(loadModule);
+Sandbox.initialize({AppModule}, [''])
+
+// 使用示例
+async function loadComponents() {
+    const loader = ModuleLoader.getInstance(); 
+
+    // 首次加载
+    const userFormScript = await loader.load({form: 'UserForm'});
+    
+    
+}
+```
+
+---
+
+### 2. 加载微前端模块（SystemJS 示例）
+
+```ts
+const systemJsLoader: LoadModule = async (params: { name: string; url: string }) => {
+    await System.import(params.url);
+    return System.get(params.name);
+};
+
+ModuleLoader.initialize(systemJsLoader);
+
+const qiankunApp = await ModuleLoader
+    .initialize(systemJsLoader)
+    .load('qiankun-app', { name: 'app1', url: 'https://app.example.com/app.js' });
+```
+
+---
+
+### 3. 加载配置驱动的插件
+
+```ts
+const pluginLoader: LoadModule = async (pluginConfig: { id: string; entry: string }) => {
+    const resp = await fetch(pluginConfig.entry);
+    const code = await resp.text();
+    const module = { exports: {} };
+    const factory = new Function('module', 'exports', code);
+    factory(module, module.exports);
+    return module.exports;
+};
+
+ModuleLoader.initialize(pluginLoader);
+
+const editorPlugin = await ModuleLoader
+    .initialize(pluginLoader)
+    .load('rich-editor', {
+        id: 'editor-v1',
+        entry: '/plugins/editor.js'
+    });
+```
+
+---
+
+## 高级用法
+
+### 自定义缓存策略（扩展）
+
+```ts
+class SmartModuleLoader extends ModuleLoader {
+    private ttl: Map<string, number> = new Map(); // 缓存过期时间
+
+    async loadWithTTL(key: string, params: any, ttlMs: number) {
+        const now = Date.now();
+        if (this.modules.has(key)) {
+            const cachedTime = this.ttl.get(key)!;
+            if (now - cachedTime < ttlMs) {
+                return this.modules.get(key);
+            }
+            this.modules.delete(key);
+            this.ttl.delete(key);
+        }
+
+        const module = await this.#loadModule(params);
+        this.modules.set(key, module);
+        this.ttl.set(key, now);
+        return module;
+    }
+}
+```
+
+---
+
+## 注意事项
+
+| 项目 | 说明 |
+|------|------|
+| **单例生命周期** | 整个应用生命周期内只有一份实例 |
+| **必须先初始化** | 未调用 `initialize` 直接使用将导致 `undefined` 行为 |
+| **缓存永久有效** | 当前实现无过期机制，适合静态模块 |
+| **键名敏感** | `key` 区分大小写，建议统一命名规范 |
+| **参数不参与缓存键** | 相同 `key` 不同 `params` 仍返回同一模块 |
+
+---
+
+## 示例项目结构
+
+```
+src/
+├── loader/
+│   └── ModuleLoader.ts
+├── modules/
+│   ├── UserProfile.js
+│   └── Dashboard.js
+├── services/
+│   └── remoteLoader.ts     # 实现 loadModule 逻辑
+├── App.ts
+└── types/
+    └── loader.d.ts
+```
+
+---
+
+## API 汇总
+
+| 方法 | 类型 | 描述 |
+|------|------|------|
+| `initialize` | `static` | 初始化单例 |
+| `load` | `async` | 加载并缓存模块 |
+
+---
+
+**版本**: 1.0.0  
+**语言**: TypeScript  
+**设计模式**: 单例 + 缓存代理  
+**适用场景**: 动态 import、微前端、插件系统、按需加载
+
+---
+
+> 推荐与 `FlexiContext` 结合使用，实现**字典 + 模块**统一加载管理。

package/README.md

@@ -0,0 +1,307 @@
+# @ticatec/uniface-flexi-form
+
+A flexible form framework for Svelte applications with dynamic field types, criteria panels, and modular components.
+
+## Features
+
+- 🚀 **Dynamic Form Generation**: Create forms dynamically from JSON schemas
+- 🎨 **Multiple Field Types**: Support for text, number, date, select, multi-select, and more
+- 🔍 **Criteria Panel**: Advanced search and filtering capabilities
+- 📱 **Responsive Design**: Mobile-friendly and adaptable layouts
+- 🧩 **Modular Architecture**: Easily extensible with custom components
+- 🎯 **Type Safety**: Full TypeScript support with comprehensive type definitions
+- 🎭 **Svelte 5 Ready**: Built for the latest Svelte version
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-flexi-form
+```
+
+## Quick Start
+
+```typescript
+import { FlexiForm, registerFormFieldBuilder } from '@ticatec/uniface-flexi-form';
+import '@ticatec/uniface-flexi-form/uniface-flexi-form.css';
+
+// Register form field builders
+registerFormFieldBuilder();
+
+// Define your form schema
+const formSchema = {
+  id: 'user-form',
+  title: 'User Information',
+  fields: [
+    {
+      id: 'name',
+      type: 'text-editor',
+      label: 'Name',
+      required: true
+    },
+    {
+      id: 'email',
+      type: 'text-editor',
+      label: 'Email',
+      required: true
+    },
+    {
+      id: 'birthDate',
+      type: 'date-picker',
+      label: 'Birth Date'
+    }
+  ]
+};
+```
+
+```svelte
+<script>
+  import { FlexiFormPage } from '@ticatec/uniface-flexi-form';
+  
+  export let formSchema;
+  export let formData = {};
+</script>
+
+<FlexiFormPage 
+  schema={formSchema} 
+  bind:data={formData} 
+/>
+```
+
+## Available Field Types
+
+The framework supports various field types out of the box:
+
+- `text-editor` - Text input field
+- `memo-editor` - Multi-line text area
+- `number-editor` - Number input field
+- `unit-number-editor` - Number input field with unit support
+- `date-picker` - Date selection field
+- `datetime-picker` - Date and time selection field
+- `options-selector` - Single select dropdown
+- `options-multi-selector` - Multi-select dropdown
+- `cascade-options-selector` - Cascading select field
+- `input-options-selector` - Select with input capability
+- `-` - Break line / separator
+- `unknown-type` - Fallback for unknown field types
+
+## Core Components
+
+### FlexiForm
+The main form component that renders dynamic forms based on schemas.
+
+```typescript
+import { FlexiForm } from '@ticatec/uniface-flexi-form';
+```
+
+### FlexiFormPage
+A page-level component for full-page forms.
+
+```typescript
+import { FlexiFormPage } from '@ticatec/uniface-flexi-form';
+```
+
+### FlexiFormDialog
+A dialog/modal component for forms.
+
+```typescript
+import { FlexiFormDialog } from '@ticatec/uniface-flexi-form';
+```
+
+### CriteriaPanel
+Advanced search and filtering panel.
+
+```typescript
+import CriteriaPanel from '@ticatec/uniface-flexi-form/criteria-panel';
+```
+
+## Schema Structure
+
+```typescript
+interface FlexiFormSchema {
+  mode?: LayoutMode;
+  arrangement?: Arrangement;
+  props?: any;
+  elements: FormElements;
+  label$style?: string;
+  variant?: 'filled' | 'outlined' | '';
+  actions?: Array<FormActionSchema>;
+  style?: string;
+}
+
+interface FlexiCardSchema {
+  title?: string;
+  mode?: LayoutMode;
+  props?: any;
+  arrangement?: Arrangement;
+  label$style?: string;
+  attrs?: any;
+  fields: Array<FlexiFieldSchema | FlexiCompositeFieldSchema>;
+  readonly?: boolean;
+  disabled?: boolean;
+  variant?: 'filled' | 'outlined' | '';
+  foldable?: boolean;
+  actions?: Array<ActionSchema>;
+}
+
+interface FlexiCompositeSchema {
+  type?: 'block';
+  title?: string;
+  fields: Array<FlexiFieldSchema>;
+  readonly?: boolean;
+  disabled?: boolean;
+  label$style?: string;
+  variant?: string;
+  mode?: LayoutMode;
+  props?: any;
+  arrangement?: Arrangement;
+}
+
+interface FlexiCompositeFieldSchema {
+  type: "composite";
+  keyField?: string;
+  name: string;
+  composite: string;
+  cell?: any;
+}
+
+interface FlexiFieldSchema {
+  type: string;
+  keyField: string;
+  name: string;
+  dictName?: string;
+  label: string;
+  variant?: "" | "outlined" | "filled";
+  readonly?: boolean;
+  disabled?: boolean;
+  required?: boolean;
+  events?: Record<string, string>;
+  cell?: any;
+  props?: any;
+}
+```
+
+## Advanced Usage
+
+### Custom Field Registration
+
+```typescript
+import { ComponentBuilder } from '@ticatec/uniface-flexi-form/flexi-form/lib/ComponentBuilder';
+
+const componentBuilder = ComponentBuilder.getInstance();
+
+// Register a custom field type
+componentBuilder.register('custom-field', (schema, dictLoader) => ({
+  component: CustomFieldComponent,
+  props: schema.props
+}));
+```
+
+### Form Validation
+
+**Note: Form validation is currently in development**. The framework has the infrastructure for validation with error tracking in FlexiField, but full validation implementation is not yet complete. Future versions will integrate with `@ticatec/web-bean-validator` for comprehensive validation support.
+
+```typescript
+// Basic field definition (validation features coming soon)
+const fieldSchema = {
+  type: 'text-editor',
+  keyField: 'email',
+  name: 'email',
+  label: 'Email',
+  required: true,
+  props: {
+    placeholder: 'Enter email address'
+  }
+};
+```
+
+### Styling and Theming
+
+The framework comes with default styles that can be customized:
+
+```scss
+@import '@ticatec/uniface-flexi-form/uniface-flexi-form.css';
+
+// Override default styles
+.flexi-form {
+  --primary-color: #your-brand-color;
+  --border-radius: 8px;
+  --spacing: 16px;
+}
+```
+
+## API Reference
+
+### Core Exports
+
+```typescript
+// Main module
+import FlexiContext from '@ticatec/uniface-flexi-form';
+
+// Form components
+import { 
+  FlexiForm, 
+  FlexiCard, 
+  FlexiField, 
+  FlexiFormPage, 
+  FlexiFormDialog,
+  ComponentBuilder,
+  registerFormFieldBuilder 
+} from '@ticatec/uniface-flexi-form/flexi-form';
+
+// Schema types
+import type { 
+  FlexiFormSchema, 
+  FlexiCardSchema, 
+  FlexiCompositeSchema, 
+  FlexiCompositeFieldSchema, 
+  FlexiFieldSchema 
+} from '@ticatec/uniface-flexi-form/flexi-form/Schema';
+
+// Type definitions
+import type { 
+  LayoutMode, 
+  Arrangement, 
+  Visibility 
+} from '@ticatec/uniface-flexi-form/flexi-form/lib';
+
+// Criteria panel
+import CriteriaPanel, { 
+  FlexiCriteriaSet, 
+  FlexiCriteriaField 
+} from '@ticatec/uniface-flexi-form/criteria-panel';
+
+// Utilities
+import utils from '@ticatec/uniface-flexi-form/utils';
+```
+
+## Development
+
+### Building the Library
+
+```bash
+npm run build
+```
+
+### Development Mode
+
+```bash
+npm run dev
+```
+
+### Type Checking
+
+```bash
+npm run check
+```
+
+## Contributing
+
+We welcome contributions! Please read our contributing guidelines and submit pull requests to our repository.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+For support and questions, please open an issue on our [GitHub repository](https://github.com/ticatec-auckland/uniface-flexi-form/issues).