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

package/dist/index.d.mts

@@ -105,9 +105,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 +327,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 +484,6 @@ declare abstract class BaseFeature implements Feature {
     render?(context: FeatureContext): Promise<any>;
 }
 
-/**
- * 表单 Feature 基类
- * 提供创建和编辑 Feature 的公共逻辑
- */
-
 /**
  * 表单操作类型
  */
@@ -478,6 +499,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 +556,7 @@ declare abstract class BaseFormFeature<T extends {
      */
     handle(context: FeatureContext): Promise<any>;
     protected formFieldNames?: string[];
+    protected groups?: FieldGroup[];
     /**
      * 渲染表单页面
      */
@@ -583,10 +607,6 @@ declare class CustomFeature extends BaseFeature {
     render(context: FeatureContext): Promise<any>;
 }
 
-/**
- * 默认创建 Feature
- */
-
 /**
  * 默认创建 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -609,6 +629,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 +689,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 +706,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 +721,6 @@ declare class DefaultDetailFeature<T extends {
     getActions(context: FeatureContext): Promise<ActionButton[]>;
 }
 
-/**
- * 默认编辑 Feature
- */
-
 /**
  * 默认编辑 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -719,6 +745,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(): ({
@@ -829,6 +859,70 @@ declare class HtmxAdminPlugin implements Plugin {
  */
 declare function getUserInfo(ctx: Context, authProvider?: AuthProvider): Promise<UserInfo | null>;
 
+/**
+ * 表单字段渲染器的 Alpine.js x-data 工具函数
+ * 提供统一的模式，简化自定义表单字段渲染器的开发
+ */
+interface FormFieldXDataOptions {
+    /** 字段名（用于更新隐藏字段） */
+    fieldName: string;
+    /** 数据对象的键名（如 'banners', 'items' 等） */
+    dataKey: string;
+    /** 默认值（如 [] 或 {}） */
+    defaultValue?: any;
+    /** 额外的数据属性 */
+    customData?: Record<string, any>;
+    /** 自定义方法（方法名 -> 方法体字符串） */
+    customMethods?: Record<string, string>;
+    /** 是否使用 x-effect 自动同步（默认 false，需要在方法中手动调用 updateHiddenField） */
+    autoSync?: boolean;
+}
+/**
+ * 创建表单字段的 Alpine.js x-data 字符串
+ *
+ * @example
+ * ```tsx
+ * const xData = createFormFieldXData({
+ *   fieldName: 'banners',
+ *   dataKey: 'banners',
+ *   defaultValue: [],
+ *   customMethods: {
+ *     addBanner() {
+ *       this.banners.push({ url: '', alt: '', order: this.banners.length });
+ *       this.updateHiddenField();
+ *     },
+ *     removeBanner(index) {
+ *       this.banners.splice(index, 1);
+ *       this.updateHiddenField();
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function createFormFieldXData(options: FormFieldXDataOptions): string;
+/**
+ * 表单字段渲染器包装器组件的属性
+ */
+interface FormFieldWrapperProps {
+    /** 字段名 */
+    fieldName: string;
+    /** 初始值（会被序列化为 JSON） */
+    initialValue: any;
+    /** x-data 字符串 */
+    xData: string;
+    /** 是否使用 x-effect 自动同步 */
+    autoSync?: boolean;
+    /** 子元素（组件 UI） */
+    children: any;
+    /** 额外的 className */
+    className?: string;
+}
+/**
+ * 表单字段渲染器包装器组件
+ * 自动处理隐藏字段、x-data、data-initial-value 等固定模式
+ */
+declare function FormFieldWrapper(props: FormFieldWrapperProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
 /**
  * 参数解析工具函数
  */
@@ -875,6 +969,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 +1004,4 @@ 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 };
+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, FormFieldWrapper, 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, createFormFieldXData, getUserInfo, modelNameToPath, parseListParams };

package/dist/index.d.ts

@@ -105,9 +105,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 +327,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 +484,6 @@ declare abstract class BaseFeature implements Feature {
     render?(context: FeatureContext): Promise<any>;
 }
 
-/**
- * 表单 Feature 基类
- * 提供创建和编辑 Feature 的公共逻辑
- */
-
 /**
  * 表单操作类型
  */
@@ -478,6 +499,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 +556,7 @@ declare abstract class BaseFormFeature<T extends {
      */
     handle(context: FeatureContext): Promise<any>;
     protected formFieldNames?: string[];
+    protected groups?: FieldGroup[];
     /**
      * 渲染表单页面
      */
@@ -583,10 +607,6 @@ declare class CustomFeature extends BaseFeature {
     render(context: FeatureContext): Promise<any>;
 }
 
-/**
- * 默认创建 Feature
- */
-
 /**
  * 默认创建 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -609,6 +629,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 +689,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 +706,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 +721,6 @@ declare class DefaultDetailFeature<T extends {
     getActions(context: FeatureContext): Promise<ActionButton[]>;
 }
 
-/**
- * 默认编辑 Feature
- */
-
 /**
  * 默认编辑 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -719,6 +745,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(): ({
@@ -829,6 +859,70 @@ declare class HtmxAdminPlugin implements Plugin {
  */
 declare function getUserInfo(ctx: Context, authProvider?: AuthProvider): Promise<UserInfo | null>;
 
+/**
+ * 表单字段渲染器的 Alpine.js x-data 工具函数
+ * 提供统一的模式，简化自定义表单字段渲染器的开发
+ */
+interface FormFieldXDataOptions {
+    /** 字段名（用于更新隐藏字段） */
+    fieldName: string;
+    /** 数据对象的键名（如 'banners', 'items' 等） */
+    dataKey: string;
+    /** 默认值（如 [] 或 {}） */
+    defaultValue?: any;
+    /** 额外的数据属性 */
+    customData?: Record<string, any>;
+    /** 自定义方法（方法名 -> 方法体字符串） */
+    customMethods?: Record<string, string>;
+    /** 是否使用 x-effect 自动同步（默认 false，需要在方法中手动调用 updateHiddenField） */
+    autoSync?: boolean;
+}
+/**
+ * 创建表单字段的 Alpine.js x-data 字符串
+ *
+ * @example
+ * ```tsx
+ * const xData = createFormFieldXData({
+ *   fieldName: 'banners',
+ *   dataKey: 'banners',
+ *   defaultValue: [],
+ *   customMethods: {
+ *     addBanner() {
+ *       this.banners.push({ url: '', alt: '', order: this.banners.length });
+ *       this.updateHiddenField();
+ *     },
+ *     removeBanner(index) {
+ *       this.banners.splice(index, 1);
+ *       this.updateHiddenField();
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function createFormFieldXData(options: FormFieldXDataOptions): string;
+/**
+ * 表单字段渲染器包装器组件的属性
+ */
+interface FormFieldWrapperProps {
+    /** 字段名 */
+    fieldName: string;
+    /** 初始值（会被序列化为 JSON） */
+    initialValue: any;
+    /** x-data 字符串 */
+    xData: string;
+    /** 是否使用 x-effect 自动同步 */
+    autoSync?: boolean;
+    /** 子元素（组件 UI） */
+    children: any;
+    /** 额外的 className */
+    className?: string;
+}
+/**
+ * 表单字段渲染器包装器组件
+ * 自动处理隐藏字段、x-data、data-initial-value 等固定模式
+ */
+declare function FormFieldWrapper(props: FormFieldWrapperProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
 /**
  * 参数解析工具函数
  */
@@ -875,6 +969,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 +1004,4 @@ 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 };
+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, FormFieldWrapper, 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, createFormFieldXData, getUserInfo, modelNameToPath, parseListParams };