imean-service-engine-htmx-plugin 2.1.1 → 2.3.0

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import { Context } from 'hono';
 import { z } from 'zod';
 import { Plugin, PluginPriority, Microservice } from 'imean-service-engine';
 import * as hono_jsx_jsx_dev_runtime from 'hono/jsx/jsx-dev-runtime';
+import * as hono_utils_html from 'hono/utils/html';
 
 /**
  * HtmxAdminPlugin 核心类型定义
@@ -39,11 +40,17 @@ interface ActionButton {
     onClick?: string;
     /** 自定义类名 */
     className?: string;
+    /** 链接目标（如 "_blank" 表示新窗口打开） */
+    target?: string;
 }
 /**
  * 对话框大小类型
  */
 type DialogSize = "sm" | "md" | "lg" | "xl" | "full";
+/**
+ * 打开方式类型
+ */
+type OpenMode = "dialog" | "page" | "newWindow";
 /**
  * 页面元数据配置
  */
@@ -105,9 +112,20 @@ interface ModelField {
         value: string | number;
         label: string;
     }>;
+    /** HTML input step 属性（用于 number 类型，支持小数） */
+    step?: string | number;
     /** 原始 Zod Schema（用于验证等） */
     schema: any;
 }
+/**
+ * 字段分组配置
+ */
+interface FieldGroup {
+    /** 分组标签 */
+    label: string;
+    /** 该分组包含的字段名列表 */
+    fields: string[];
+}
 /**
  * Feature 类型
  */
@@ -316,6 +334,21 @@ interface FormField {
         value: string | number;
         label: string;
     }>;
+    /** HTML input step 属性（用于 number 类型，支持小数） */
+    step?: string | number;
+}
+/**
+ * 表单字段渲染器属性
+ */
+interface FormFieldRendererProps<T = any> {
+    /** 字段定义 */
+    field: FormField;
+    /** 当前值（已解析的对象/数组，不是 JSON 字符串） */
+    value: any;
+    /** 完整的初始数据 */
+    initialData?: Partial<T>;
+    /** 字段名（用于更新隐藏字段） */
+    fieldName: string;
 }
 
 /**
@@ -458,11 +491,6 @@ declare abstract class BaseFeature implements Feature {
     render?(context: FeatureContext): Promise<any>;
 }
 
-/**
- * 表单 Feature 基类
- * 提供创建和编辑 Feature 的公共逻辑
- */
-
 /**
  * 表单操作类型
  */
@@ -478,6 +506,8 @@ declare abstract class BaseFormFeature<T extends {
     protected descriptionGetter?: (context: FeatureContext, item?: T) => string | Promise<string> | undefined;
     /** 当前请求的表单 ID（用于在 render 和 getActions 之间共享） */
     private currentFormId?;
+    /** 自定义表单字段渲染器 */
+    protected formFieldRenderers?: Record<string, (props: FormFieldRendererProps<T>) => any>;
     /**
      * 获取或生成表单 ID（确保在同一个请求中保持一致）
      */
@@ -533,6 +563,7 @@ declare abstract class BaseFormFeature<T extends {
      */
     handle(context: FeatureContext): Promise<any>;
     protected formFieldNames?: string[];
+    protected groups?: FieldGroup[];
     /**
      * 渲染表单页面
      */
@@ -583,10 +614,6 @@ declare class CustomFeature extends BaseFeature {
     render(context: FeatureContext): Promise<any>;
 }
 
-/**
- * 默认创建 Feature
- */
-
 /**
  * 默认创建 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -609,6 +636,10 @@ declare class DefaultCreateFeature<T extends {
         getDescription?: (context: FeatureContext) => string | Promise<string> | undefined;
         /** 表单字段名（可选，不提供则显示 schema 中的所有字段） */
         formFieldNames?: string[];
+        /** 字段分组配置（可选，用于将字段分组展示为 Tab） */
+        groups?: FieldGroup[];
+        /** 自定义表单字段渲染器 */
+        formFieldRenderers?: Record<string, (props: FormFieldRendererProps<T>) => any>;
     });
     getFormAction(): "create";
     getRoutes(): ({
@@ -665,6 +696,8 @@ declare class DefaultDetailFeature<T extends {
     private titleGetter?;
     private descriptionGetter?;
     private detailFieldNames?;
+    private fieldRenderers?;
+    private groups?;
     constructor(options: {
         /** 详情数据的 Schema（用于字段推断和显示） */
         schema: z.ZodObject<any>;
@@ -680,6 +713,10 @@ declare class DefaultDetailFeature<T extends {
         getDescription?: (item: T, context: FeatureContext) => string | Promise<string> | undefined;
         /** 详情显示字段名（可选，不提供则显示 schema 中的所有字段） */
         detailFieldNames?: string[];
+        /** 自定义字段渲染函数（可选，key 为字段名，value 为渲染函数） */
+        fieldRenderers?: Record<string, (value: any, item: T) => any>;
+        /** 字段分组配置（可选，用于将字段分组展示为卡片） */
+        groups?: FieldGroup[];
     });
     getTitle(context: FeatureContext): Promise<string>;
     getDescription(context: FeatureContext): Promise<string | undefined>;
@@ -691,10 +728,6 @@ declare class DefaultDetailFeature<T extends {
     getActions(context: FeatureContext): Promise<ActionButton[]>;
 }
 
-/**
- * 默认编辑 Feature
- */
-
 /**
  * 默认编辑 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -719,6 +752,10 @@ declare class DefaultEditFeature<T extends {
         getDescription?: (item: T, context: FeatureContext) => string | Promise<string> | undefined;
         /** 表单字段名（可选，不提供则显示 schema 中的所有字段） */
         formFieldNames?: string[];
+        /** 字段分组配置（可选，用于将字段分组展示为 Tab） */
+        groups?: FieldGroup[];
+        /** 自定义表单字段渲染器 */
+        formFieldRenderers?: Record<string, (props: FormFieldRendererProps<T>) => any>;
     });
     getFormAction(): "edit";
     getRoutes(): ({
@@ -755,6 +792,7 @@ declare class DefaultListFeature<T extends {
     private listFieldNames?;
     private filterSchema?;
     private columnRenderers?;
+    private openMode?;
     constructor(options: {
         /** 列表数据的 Schema（用于字段推断和显示） */
         schema: z.ZodObject<any>;
@@ -776,6 +814,16 @@ declare class DefaultListFeature<T extends {
         filterSchema?: z.ZodObject<any>;
         /** 自定义列渲染函数（可选，key 为字段名，value 为渲染函数） */
         columnRenderers?: Record<string, (value: any, item: T) => any>;
+        /** 打开方式配置（可选，默认为 dialog）
+         * - create: 新建按钮的打开方式（默认 "dialog"）
+         * - detail: 查看按钮的打开方式（默认 "dialog"）
+         * - edit: 编辑按钮的打开方式（默认 "dialog"）
+         */
+        openMode?: {
+            create?: OpenMode;
+            detail?: OpenMode;
+            edit?: OpenMode;
+        };
     });
     getRoutes(): {
         method: "get";
@@ -875,6 +923,8 @@ interface DialogProps {
     closeOnBackdropClick?: boolean;
     /** 操作按钮（在 Footer 中显示，固定在底部） */
     actions?: ActionButton[];
+    /** 是否固定内容区域高度（用于表单等需要固定高度的场景，避免切换 Tab 时高度变化） */
+    fixedContentHeight?: boolean;
 }
 declare function Dialog(props: DialogProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
@@ -908,4 +958,39 @@ declare function ErrorAlert(props: ErrorAlertProps): hono_jsx_jsx_dev_runtime.JS
  */
 declare function LoadingBar(): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-export { type AuthProvider, BaseFeature, CustomFeature, DefaultCreateFeature, DefaultDeleteFeature, DefaultDetailFeature, DefaultEditFeature, DefaultListFeature, Dialog, type DialogProps, type DialogSize, ErrorAlert, type ErrorAlertProps, type Feature, type FeatureContext, type FeatureType, type FieldMetadata, HtmxAdminPlugin, type HtmxAdminPluginOptions, type ListParams, type ListResult, LoadingBar, type NavItemConfig, type Notification, type NotificationType$1 as NotificationType, type PageMetadata, PageModel, type PermissionResult, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };
+interface ObjectEditorProps {
+    /** 字段定义 */
+    field: any;
+    /** 当前值（对象，已解析） */
+    value: Record<string, any> | null;
+    /** 完整的初始数据 */
+    initialData?: any;
+    /** 字段名（用于更新隐藏字段） */
+    fieldName: string;
+    /** 对象的 Zod schema（用于自动渲染结构） */
+    objectSchema?: z.ZodObject<any>;
+}
+declare function ObjectEditor(props: ObjectEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 字符串数组编辑器组件
+ * 支持增加、删除和拖放排序功能
+ * 使用 Alpine.js 管理状态，通过隐藏字段与表单系统同步数据
+ */
+interface StringArrayEditorProps {
+    /** 字段定义 */
+    field: any;
+    /** 当前值（字符串数组，已解析） */
+    value: string[] | null;
+    /** 完整的初始数据 */
+    initialData?: any;
+    /** 字段名（用于更新隐藏字段） */
+    fieldName: string;
+    /** 占位符文本（可选） */
+    placeholder?: string;
+    /** 是否允许空值（默认 false） */
+    allowEmpty?: boolean;
+}
+declare function StringArrayEditor(props: StringArrayEditorProps): hono_utils_html.HtmlEscapedString | Promise<hono_utils_html.HtmlEscapedString>;
+
+export { type AuthProvider, BaseFeature, CustomFeature, DefaultCreateFeature, DefaultDeleteFeature, DefaultDetailFeature, DefaultEditFeature, DefaultListFeature, Dialog, type DialogProps, type DialogSize, ErrorAlert, type ErrorAlertProps, type Feature, type FeatureContext, type FeatureType, type FieldMetadata, HtmxAdminPlugin, type HtmxAdminPluginOptions, type ListParams, type ListResult, LoadingBar, type NavItemConfig, type Notification, type NotificationType$1 as NotificationType, ObjectEditor, type ObjectEditorProps, type PageMetadata, PageModel, type PermissionResult, StringArrayEditor, type StringArrayEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Context } from 'hono';
 import { z } from 'zod';
 import { Plugin, PluginPriority, Microservice } from 'imean-service-engine';
 import * as hono_jsx_jsx_dev_runtime from 'hono/jsx/jsx-dev-runtime';
+import * as hono_utils_html from 'hono/utils/html';
 
 /**
  * HtmxAdminPlugin 核心类型定义
@@ -39,11 +40,17 @@ interface ActionButton {
     onClick?: string;
     /** 自定义类名 */
     className?: string;
+    /** 链接目标（如 "_blank" 表示新窗口打开） */
+    target?: string;
 }
 /**
  * 对话框大小类型
  */
 type DialogSize = "sm" | "md" | "lg" | "xl" | "full";
+/**
+ * 打开方式类型
+ */
+type OpenMode = "dialog" | "page" | "newWindow";
 /**
  * 页面元数据配置
  */
@@ -105,9 +112,20 @@ interface ModelField {
         value: string | number;
         label: string;
     }>;
+    /** HTML input step 属性（用于 number 类型，支持小数） */
+    step?: string | number;
     /** 原始 Zod Schema（用于验证等） */
     schema: any;
 }
+/**
+ * 字段分组配置
+ */
+interface FieldGroup {
+    /** 分组标签 */
+    label: string;
+    /** 该分组包含的字段名列表 */
+    fields: string[];
+}
 /**
  * Feature 类型
  */
@@ -316,6 +334,21 @@ interface FormField {
         value: string | number;
         label: string;
     }>;
+    /** HTML input step 属性（用于 number 类型，支持小数） */
+    step?: string | number;
+}
+/**
+ * 表单字段渲染器属性
+ */
+interface FormFieldRendererProps<T = any> {
+    /** 字段定义 */
+    field: FormField;
+    /** 当前值（已解析的对象/数组，不是 JSON 字符串） */
+    value: any;
+    /** 完整的初始数据 */
+    initialData?: Partial<T>;
+    /** 字段名（用于更新隐藏字段） */
+    fieldName: string;
 }
 
 /**
@@ -458,11 +491,6 @@ declare abstract class BaseFeature implements Feature {
     render?(context: FeatureContext): Promise<any>;
 }
 
-/**
- * 表单 Feature 基类
- * 提供创建和编辑 Feature 的公共逻辑
- */
-
 /**
  * 表单操作类型
  */
@@ -478,6 +506,8 @@ declare abstract class BaseFormFeature<T extends {
     protected descriptionGetter?: (context: FeatureContext, item?: T) => string | Promise<string> | undefined;
     /** 当前请求的表单 ID（用于在 render 和 getActions 之间共享） */
     private currentFormId?;
+    /** 自定义表单字段渲染器 */
+    protected formFieldRenderers?: Record<string, (props: FormFieldRendererProps<T>) => any>;
     /**
      * 获取或生成表单 ID（确保在同一个请求中保持一致）
      */
@@ -533,6 +563,7 @@ declare abstract class BaseFormFeature<T extends {
      */
     handle(context: FeatureContext): Promise<any>;
     protected formFieldNames?: string[];
+    protected groups?: FieldGroup[];
     /**
      * 渲染表单页面
      */
@@ -583,10 +614,6 @@ declare class CustomFeature extends BaseFeature {
     render(context: FeatureContext): Promise<any>;
 }
 
-/**
- * 默认创建 Feature
- */
-
 /**
  * 默认创建 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -609,6 +636,10 @@ declare class DefaultCreateFeature<T extends {
         getDescription?: (context: FeatureContext) => string | Promise<string> | undefined;
         /** 表单字段名（可选，不提供则显示 schema 中的所有字段） */
         formFieldNames?: string[];
+        /** 字段分组配置（可选，用于将字段分组展示为 Tab） */
+        groups?: FieldGroup[];
+        /** 自定义表单字段渲染器 */
+        formFieldRenderers?: Record<string, (props: FormFieldRendererProps<T>) => any>;
     });
     getFormAction(): "create";
     getRoutes(): ({
@@ -665,6 +696,8 @@ declare class DefaultDetailFeature<T extends {
     private titleGetter?;
     private descriptionGetter?;
     private detailFieldNames?;
+    private fieldRenderers?;
+    private groups?;
     constructor(options: {
         /** 详情数据的 Schema（用于字段推断和显示） */
         schema: z.ZodObject<any>;
@@ -680,6 +713,10 @@ declare class DefaultDetailFeature<T extends {
         getDescription?: (item: T, context: FeatureContext) => string | Promise<string> | undefined;
         /** 详情显示字段名（可选，不提供则显示 schema 中的所有字段） */
         detailFieldNames?: string[];
+        /** 自定义字段渲染函数（可选，key 为字段名，value 为渲染函数） */
+        fieldRenderers?: Record<string, (value: any, item: T) => any>;
+        /** 字段分组配置（可选，用于将字段分组展示为卡片） */
+        groups?: FieldGroup[];
     });
     getTitle(context: FeatureContext): Promise<string>;
     getDescription(context: FeatureContext): Promise<string | undefined>;
@@ -691,10 +728,6 @@ declare class DefaultDetailFeature<T extends {
     getActions(context: FeatureContext): Promise<ActionButton[]>;
 }
 
-/**
- * 默认编辑 Feature
- */
-
 /**
  * 默认编辑 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -719,6 +752,10 @@ declare class DefaultEditFeature<T extends {
         getDescription?: (item: T, context: FeatureContext) => string | Promise<string> | undefined;
         /** 表单字段名（可选，不提供则显示 schema 中的所有字段） */
         formFieldNames?: string[];
+        /** 字段分组配置（可选，用于将字段分组展示为 Tab） */
+        groups?: FieldGroup[];
+        /** 自定义表单字段渲染器 */
+        formFieldRenderers?: Record<string, (props: FormFieldRendererProps<T>) => any>;
     });
     getFormAction(): "edit";
     getRoutes(): ({
@@ -755,6 +792,7 @@ declare class DefaultListFeature<T extends {
     private listFieldNames?;
     private filterSchema?;
     private columnRenderers?;
+    private openMode?;
     constructor(options: {
         /** 列表数据的 Schema（用于字段推断和显示） */
         schema: z.ZodObject<any>;
@@ -776,6 +814,16 @@ declare class DefaultListFeature<T extends {
         filterSchema?: z.ZodObject<any>;
         /** 自定义列渲染函数（可选，key 为字段名，value 为渲染函数） */
         columnRenderers?: Record<string, (value: any, item: T) => any>;
+        /** 打开方式配置（可选，默认为 dialog）
+         * - create: 新建按钮的打开方式（默认 "dialog"）
+         * - detail: 查看按钮的打开方式（默认 "dialog"）
+         * - edit: 编辑按钮的打开方式（默认 "dialog"）
+         */
+        openMode?: {
+            create?: OpenMode;
+            detail?: OpenMode;
+            edit?: OpenMode;
+        };
     });
     getRoutes(): {
         method: "get";
@@ -875,6 +923,8 @@ interface DialogProps {
     closeOnBackdropClick?: boolean;
     /** 操作按钮（在 Footer 中显示，固定在底部） */
     actions?: ActionButton[];
+    /** 是否固定内容区域高度（用于表单等需要固定高度的场景，避免切换 Tab 时高度变化） */
+    fixedContentHeight?: boolean;
 }
 declare function Dialog(props: DialogProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
@@ -908,4 +958,39 @@ declare function ErrorAlert(props: ErrorAlertProps): hono_jsx_jsx_dev_runtime.JS
  */
 declare function LoadingBar(): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-export { type AuthProvider, BaseFeature, CustomFeature, DefaultCreateFeature, DefaultDeleteFeature, DefaultDetailFeature, DefaultEditFeature, DefaultListFeature, Dialog, type DialogProps, type DialogSize, ErrorAlert, type ErrorAlertProps, type Feature, type FeatureContext, type FeatureType, type FieldMetadata, HtmxAdminPlugin, type HtmxAdminPluginOptions, type ListParams, type ListResult, LoadingBar, type NavItemConfig, type Notification, type NotificationType$1 as NotificationType, type PageMetadata, PageModel, type PermissionResult, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };
+interface ObjectEditorProps {
+    /** 字段定义 */
+    field: any;
+    /** 当前值（对象，已解析） */
+    value: Record<string, any> | null;
+    /** 完整的初始数据 */
+    initialData?: any;
+    /** 字段名（用于更新隐藏字段） */
+    fieldName: string;
+    /** 对象的 Zod schema（用于自动渲染结构） */
+    objectSchema?: z.ZodObject<any>;
+}
+declare function ObjectEditor(props: ObjectEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 字符串数组编辑器组件
+ * 支持增加、删除和拖放排序功能
+ * 使用 Alpine.js 管理状态，通过隐藏字段与表单系统同步数据
+ */
+interface StringArrayEditorProps {
+    /** 字段定义 */
+    field: any;
+    /** 当前值（字符串数组，已解析） */
+    value: string[] | null;
+    /** 完整的初始数据 */
+    initialData?: any;
+    /** 字段名（用于更新隐藏字段） */
+    fieldName: string;
+    /** 占位符文本（可选） */
+    placeholder?: string;
+    /** 是否允许空值（默认 false） */
+    allowEmpty?: boolean;
+}
+declare function StringArrayEditor(props: StringArrayEditorProps): hono_utils_html.HtmlEscapedString | Promise<hono_utils_html.HtmlEscapedString>;
+
+export { type AuthProvider, BaseFeature, CustomFeature, DefaultCreateFeature, DefaultDeleteFeature, DefaultDetailFeature, DefaultEditFeature, DefaultListFeature, Dialog, type DialogProps, type DialogSize, ErrorAlert, type ErrorAlertProps, type Feature, type FeatureContext, type FeatureType, type FieldMetadata, HtmxAdminPlugin, type HtmxAdminPluginOptions, type ListParams, type ListResult, LoadingBar, type NavItemConfig, type Notification, type NotificationType$1 as NotificationType, ObjectEditor, type ObjectEditorProps, type PageMetadata, PageModel, type PermissionResult, StringArrayEditor, type StringArrayEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };