imean-service-engine-htmx-plugin 2.6.0 → 2.8.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Context } from 'hono';
-import { z } from 'zod';
-import { Plugin, PluginPriority, Microservice } from 'imean-service-engine';
+import { z, Plugin, PluginPriority, Microservice } from 'imean-service-engine';
+import { z as z$1 } from 'zod';
 import * as hono_jsx_jsx_dev_runtime from 'hono/jsx/jsx-dev-runtime';
 
 /**
@@ -84,6 +84,39 @@ declare abstract class PageModel {
  * HtmxAdminPlugin 核心类型定义
  */
 
+/**
+ * 操作按钮配置
+ */
+interface ActionButton {
+    /** 按钮文本 */
+    label: string;
+    /** 链接地址（页面模式使用） */
+    href?: string;
+    /** HTTP 方法 */
+    method?: "get" | "post" | "put" | "delete";
+    /** 按钮样式 */
+    variant?: "primary" | "secondary" | "danger" | "ghost";
+    /** HTMX GET 请求（弹窗模式使用） */
+    hxGet?: string;
+    /** HTMX POST 请求 */
+    hxPost?: string;
+    /** HTMX PUT 请求 */
+    hxPut?: string;
+    /** HTMX DELETE 请求 */
+    hxDelete?: string;
+    /** 确认提示 */
+    confirm?: string;
+    /** 是否关闭弹窗（设置为 true 时，点击按钮会自动关闭弹窗，无需写代码） */
+    close?: boolean;
+    /** 是否提交表单（设置为 true 时，按钮会提交指定的表单，需要配合 formId 使用） */
+    submit?: boolean;
+    /** 表单 ID（当 submit 为 true 时，指定要提交的表单 ID） */
+    formId?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 链接目标（如 "_blank" 表示新窗口打开） */
+    target?: string;
+}
 /**
  * 对话框大小类型
  */
@@ -167,6 +200,17 @@ interface FieldGroup {
     /** 该分组包含的字段名列表 */
     fields: string[];
 }
+/**
+ * 表单分组配置
+ */
+interface FormGroup {
+    /** 分组标签 */
+    label: string;
+    /** 该分组包含的字段名列表 */
+    fields: ModelField[];
+    /** 该分组对应的 Zod Schema */
+    schema: z.ZodObject<any>;
+}
 /**
  * Feature 类型
  */
@@ -390,20 +434,101 @@ interface FormField {
     /** HTML input step 属性（用于 number 类型，支持小数） */
     step?: string | number;
 }
+/**
+ * 字段渲染器属性
+ * 统一接口，可在不同 Feature 中复用
+ */
+interface FieldRendererProps<T = any, K extends keyof T = keyof T> {
+    /** 字段值 */
+    value: T[K];
+    /** 完整的初始数据项 */
+    item: Partial<T>;
+    /** 字段名 */
+    name: string;
+    /** 字段标签(没有会使用name的值作为标签) */
+    label: string;
+}
 /**
  * 表单字段渲染器属性
  * 统一接口，可在不同 Feature 中复用
  */
-interface FormFieldRendererProps<T = any> {
+interface FormFieldRendererProps<T = any, K extends keyof T = keyof T> extends FieldRendererProps<T, K> {
     /** 字段定义 */
     field: FormField;
-    /** 当前值（已解析的对象/数组，不是 JSON 字符串） */
-    value: any;
-    /** 完整的初始数据项（用于编辑模式，包含所有字段的完整数据） */
-    item?: Partial<T>;
-    /** 字段名（用于更新隐藏字段） */
-    name: string;
 }
+/**
+ * 字段渲染器
+ * 用于渲染字段，可用于自定义渲染器
+ */
+interface FieldRenderer<T extends FieldRendererProps = FieldRendererProps> {
+    (props: T): any;
+}
+/**
+ * 表单字段渲染器类型别名
+ * 用于统一表单字段渲染器的类型定义
+ * 支持字段名泛型，可以根据字段名推导出对应的值类型
+ */
+type FormFieldRenderer<T = any, K extends keyof T = keyof T> = FieldRenderer<FormFieldRendererProps<T, K>>;
+/**
+ * 表单字段渲染器映射类型
+ * 根据字段名自动推导对应的值类型，并严格约束 key 只能是 T 的字段名
+ *
+ * 使用方式：
+ * ```typescript
+ * formFieldRenderers: {
+ *   banners: (props) => {
+ *     // props.value 自动推导为 T["banners"] 类型
+ *     return <BannerEditor {...props} value={props.value} />;
+ *   }
+ * }
+ * ```
+ *
+ * TypeScript 会根据字段名自动推导对应的值类型，无需手动添加类型注解
+ * key 约束：只能使用 T 中存在的字段名，拼写错误会被 TypeScript 检查出来
+ * 例如：如果写成了 "tgas" 而不是 "tags"，TypeScript 会报错
+ *
+ * 注意：为了支持类型推导，移除了索引签名，运行时访问字符串键时需要使用类型断言
+ */
+/**
+ * 表单字段渲染器映射类型
+ * 根据字段名自动推导对应的值类型，并严格约束 key 只能是 T 的字段名
+ *
+ * 使用方式：
+ * ```typescript
+ * formFieldRenderers: {
+ *   banners: (props) => {
+ *     // props.value 自动推导为 T["banners"] 类型
+ *     return <BannerEditor {...props} value={props.value} />;
+ *   }
+ * }
+ * ```
+ *
+ * TypeScript 会根据字段名自动推导对应的值类型，无需手动添加类型注解
+ * key 约束：只能使用 T 中存在的字段名，拼写错误会被 TypeScript 检查出来
+ * 例如：如果写成了 "tgas" 而不是 "tags"，TypeScript 会报错
+ *
+ * 注意：为了支持类型推导，移除了索引签名，运行时访问字符串键时需要使用类型断言
+ */
+type FormFieldRendererMap<T = any> = {
+    [K in keyof T]?: FormFieldRenderer<T, K>;
+};
+/**
+ * 字段渲染器类型别名（用于详情页等非表单场景）
+ * 用于统一字段渲染器的类型定义
+ * 支持字段名泛型，可以根据字段名推导出对应的值类型
+ */
+type FieldRendererType<T = any, K extends keyof T = keyof T> = FieldRenderer<FieldRendererProps<T, K>>;
+/**
+ * 字段渲染器映射类型
+ * 根据字段名自动推导对应的值类型
+ * 使用 Record 类型保持兼容性，但在使用时可以通过类型断言获得字段级别的类型推导
+ *
+ * 注意：在使用时，TypeScript 会根据字段名自动推导对应的值类型
+ * 例如：fieldRenderers.banners 的类型会被推导为 FieldRendererType<T, "banners">
+ */
+type FieldRendererTypeMap<T = any> = {
+    [K in keyof T]?: FieldRendererType<T, K>;
+} & Record<string, FieldRendererType<T, any> | undefined> & Partial<Record<keyof T, FieldRendererType<T, keyof T>>>;
 
 /**
  * Feature 基类
@@ -426,15 +551,16 @@ declare abstract class BaseFeature implements Feature {
     /** 是否允许点击遮罩区域关闭弹窗（默认 true，设置为 false 时只能通过关闭按钮关闭） */
     closeOnBackdropClick?: boolean;
     /** Schema（可选，由子类在构造函数中设置） */
-    protected schema?: z.ZodObject<any>;
+    protected schema: z$1.ZodObject<any>;
     /** 解析后的字段列表（可选，由子类在构造函数中设置） */
-    protected fields?: ModelField[];
+    protected fields: ModelField[];
     constructor(options: {
         name: string;
         type: FeatureType;
         permission: string | null;
         dialogSize?: DialogSize;
         closeOnBackdropClick?: boolean;
+        schema?: z$1.ZodObject<any>;
     });
     /**
      * 获取动态标题（默认实现：返回 PageMetadata 的 title）
@@ -468,6 +594,11 @@ declare abstract class BaseFeature implements Feature {
     render?(context: FeatureContext): Promise<any>;
 }
 
+/**
+ * 表单 Feature 基类
+ * 提供创建和编辑 Feature 的公共逻辑
+ */
+
 /**
  * 表单操作类型
  */
@@ -484,7 +615,9 @@ declare abstract class BaseFormFeature<T extends {
     /** 当前请求的表单 ID（用于在 render 和 getActions 之间共享） */
     private currentFormId?;
     /** 自定义表单字段渲染器 */
-    protected formFieldRenderers?: Record<string, (props: FormFieldRendererProps<T>) => any>;
+    protected formFieldRenderers?: {
+        [K in keyof T]?: FormFieldRenderer<T, K>;
+    };
     /**
      * 获取或生成表单 ID（确保在同一个请求中保持一致）
      */
@@ -497,6 +630,7 @@ declare abstract class BaseFormFeature<T extends {
         closeOnBackdropClick?: boolean;
         getTitle?: (context: FeatureContext, item?: T) => string | Promise<string>;
         getDescription?: (context: FeatureContext, item?: T) => string | Promise<string> | undefined;
+        schema?: z.ZodObject<any>;
     });
     /**
      * 获取表单操作类型
@@ -591,6 +725,10 @@ declare class CustomFeature extends BaseFeature {
     render(context: FeatureContext): Promise<any>;
 }
 
+/**
+ * 默认创建 Feature
+ */
+
 /**
  * 默认创建 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -601,7 +739,7 @@ declare class DefaultCreateFeature<T extends {
     private createItem;
     constructor(options: {
         /** 表单数据的 Schema（用于验证和字段推断） */
-        schema: z.ZodObject<any>;
+        schema: z$1.ZodObject<any>;
         createItem: (data: Partial<T>) => Promise<T>;
         permissionPrefix: string;
         permission?: string;
@@ -616,7 +754,7 @@ declare class DefaultCreateFeature<T extends {
         /** 字段分组配置（可选，用于将字段分组展示为 Tab） */
         groups?: FieldGroup[];
         /** 自定义表单字段渲染器 */
-        formFieldRenderers?: Record<string, (props: FormFieldRendererProps<T>) => any>;
+        formFieldRenderers?: FormFieldRendererMap<T>;
     });
     getFormAction(): "create";
     getRoutes(): ({
@@ -676,7 +814,7 @@ declare class DefaultDetailFeature<T extends {
     private groups?;
     constructor(options: {
         /** 详情数据的 Schema（用于字段推断和显示） */
-        schema: z.ZodObject<any>;
+        schema: z$1.ZodObject<any>;
         getItem: (id: string | number) => Promise<T | null>;
         permissionPrefix: string;
         permission?: string;
@@ -689,7 +827,7 @@ declare class DefaultDetailFeature<T extends {
         /** 详情显示字段名（可选，不提供则显示 schema 中的所有字段） */
         detailFieldNames?: string[];
         /** 自定义字段渲染函数（可选，key 为字段名，value 为渲染函数） */
-        fieldRenderers?: Record<string, (value: any, item: T) => any>;
+        fieldRenderers?: FieldRendererTypeMap<T>;
         /** 字段分组配置（可选，用于将字段分组展示为卡片） */
         groups?: FieldGroup[];
     });
@@ -703,6 +841,10 @@ declare class DefaultDetailFeature<T extends {
     getActions(context: FeatureContext): Promise<any>;
 }
 
+/**
+ * 默认编辑 Feature
+ */
+
 /**
  * 默认编辑 Feature
  * 类型通过 schema 的 z.infer 推断
@@ -714,7 +856,7 @@ declare class DefaultEditFeature<T extends {
     private updateItem;
     constructor(options: {
         /** 表单数据的 Schema（用于验证和字段推断） */
-        schema: z.ZodObject<any>;
+        schema: z$1.ZodObject<any>;
         getItem: (id: string | number) => Promise<T | null>;
         updateItem: (id: string | number, data: Partial<T>) => Promise<T | null>;
         permissionPrefix: string;
@@ -730,7 +872,7 @@ declare class DefaultEditFeature<T extends {
         /** 字段分组配置（可选，用于将字段分组展示为 Tab） */
         groups?: FieldGroup[];
         /** 自定义表单字段渲染器 */
-        formFieldRenderers?: Record<string, (props: FormFieldRendererProps<T>) => any>;
+        formFieldRenderers?: FormFieldRendererMap<T>;
     });
     getFormAction(): "edit";
     getRoutes(): ({
@@ -770,7 +912,7 @@ declare class DefaultListFeature<T extends {
     private openMode?;
     constructor(options: {
         /** 列表数据的 Schema（用于字段推断和显示） */
-        schema: z.ZodObject<any>;
+        schema: z$1.ZodObject<any>;
         /** 获取列表数据的函数 */
         getList: (params: ListParams) => Promise<ListResult<T>>;
         /** 删除数据的函数（可选，不提供则列表不显示删除操作） */
@@ -786,9 +928,9 @@ declare class DefaultListFeature<T extends {
         /** 列表显示字段名（可选，不提供则显示 schema 中的所有字段） */
         listFieldNames?: string[];
         /** 筛选表单的 Schema（可选，不提供则不显示筛选表单） */
-        filterSchema?: z.ZodObject<any>;
-        /** 自定义列渲染函数（可选，key 为字段名，value 为渲染函数） */
-        columnRenderers?: Record<string, (value: any, item: T) => any>;
+        filterSchema?: z$1.ZodObject<any>;
+        /** 自定义列渲染器（可选，使用统一的 FieldRendererTypeMap 接口） */
+        columnRenderers?: FieldRendererTypeMap<T>;
         /** 打开方式配置（可选，默认为 dialog）
          * - create: 新建按钮的打开方式（默认 "dialog"）
          * - detail: 查看按钮的打开方式（默认 "dialog"）
@@ -935,17 +1077,213 @@ interface ErrorAlertProps {
  */
 declare function ErrorAlert(props: ErrorAlertProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
+interface FilterFormProps {
+    /** 筛选字段 */
+    fields: FormField[];
+    /** 列表路径（用于提交筛选表单） */
+    listPath: string;
+    /** 当前筛选参数 */
+    currentFilters?: Record<string, any>;
+}
+/**
+ * 筛选表单组件
+ */
+declare function FilterForm(props: FilterFormProps): hono_jsx_jsx_dev_runtime.JSX.Element | null;
+
+/**
+ * 面包屑组件
+ */
+interface BreadcrumbItem {
+    label: string;
+    href?: string;
+}
+interface BreadcrumbProps {
+    items: BreadcrumbItem[];
+}
+/**
+ * 面包屑组件
+ */
+declare function Breadcrumb(props: BreadcrumbProps): hono_jsx_jsx_dev_runtime.JSX.Element | null;
+
+interface HeaderProps {
+    /** 面包屑项 */
+    breadcrumbs?: BreadcrumbItem[];
+    /** 用户信息 */
+    userInfo?: UserInfo | null;
+    /** 退出登录的URL */
+    logoutUrl?: string;
+    /** 页面标题（当没有面包屑时显示） */
+    title?: string;
+}
+/**
+ * 头部组件
+ */
+declare function Header(props: HeaderProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
 /**
  * 加载条组件
  * 用于显示 HTMX 请求的加载状态
  */
 declare function LoadingBar(): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-interface ObjectEditorProps extends FormFieldRendererProps {
-    /** 对象的 Zod schema（用于自动渲染结构） */
-    objectSchema?: z.ZodObject<any>;
+/**
+ * 表格组件
+ */
+/**
+ * 表格组件 Props
+ */
+interface TableProps<T = any> {
+    /** 数据列表 */
+    items: T[];
+    /** 列定义 */
+    columns: Array<{
+        key: string;
+        label: string;
+        render?: (value: any, item: T) => any;
+    }>;
+    /** 操作列 */
+    actions?: Array<{
+        label: string;
+        href: (item: T) => string;
+        method?: string;
+        class?: string;
+        target?: string;
+    }>;
+    /** 分页信息 */
+    pagination?: {
+        page: number;
+        pageSize: number;
+        total: number;
+        totalPages: number;
+        baseUrl: string;
+        currentParams?: Record<string, string | number | undefined>;
+    };
+    /** 表格标题 */
+    title?: string;
+    /** 表格操作按钮（如导出、清空、刷新等） */
+    tableActions?: Array<{
+        label: string;
+        href?: string;
+        hxGet?: string;
+        hxPost?: string;
+        hxDelete?: string;
+        variant?: "primary" | "secondary" | "danger" | "ghost";
+        hxConfirm?: string;
+    }>;
+    /** 操作列样式（link 或 button） */
+    actionStyle?: "link" | "button";
 }
-declare function ObjectEditor(props: ObjectEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+/**
+ * 表格组件
+ */
+declare function Table<T extends {
+    id: string | number;
+}>(props: TableProps<T>): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 分页组件
+ */
+interface PaginationProps {
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+    /** 总记录数 */
+    total: number;
+    /** 总页数 */
+    totalPages: number;
+    /** 基础 URL */
+    baseUrl: string;
+    /** 当前查询参数（用于保留筛选条件等） */
+    currentParams?: Record<string, string | number | undefined>;
+}
+/**
+ * 分页组件
+ */
+declare function Pagination(props: PaginationProps): hono_jsx_jsx_dev_runtime.JSX.Element | null;
+
+/**
+ * 卡片组件
+ */
+interface CardProps {
+    /** 卡片内容 */
+    children: any;
+    /** 卡片标题 */
+    title?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 是否显示阴影 */
+    shadow?: boolean;
+    /** 是否显示边框 */
+    bordered?: boolean;
+    /** 是否去掉内边距 */
+    noPadding?: boolean;
+}
+/**
+ * 卡片组件
+ */
+declare function Card(props: CardProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 空状态组件
+ */
+interface EmptyStateProps {
+    /** 提示文本 */
+    message?: string;
+    /** 自定义内容 */
+    children?: any;
+}
+/**
+ * 空状态组件
+ */
+declare function EmptyState(props: EmptyStateProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 按钮组件
+ * 只负责样式，其他属性（如 HTMX 属性）通过解构动态传递
+ */
+interface ButtonProps {
+    /** 按钮文本 */
+    children: any;
+    /** 按钮类型 */
+    variant?: "primary" | "secondary" | "danger" | "ghost";
+    /** 按钮大小 */
+    size?: "sm" | "md" | "lg";
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 自定义类名 */
+    className?: string;
+    /** 其他属性（包括 HTMX 属性、href 等） */
+    [key: string]: any;
+}
+/**
+ * 按钮组件
+ * 只负责样式，其他属性通过解构动态传递
+ */
+declare function Button(props: ButtonProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+interface PermissionDeniedContentProps {
+    /** 操作ID（权限标识） */
+    operationId?: string;
+    /** 请求路径 */
+    fromPath?: string;
+    /** 错误消息 */
+    message?: string;
+    /** 用户信息 */
+    userInfo?: UserInfo | null;
+    /** 插件选项 */
+    pluginOptions?: HtmxAdminPluginOptions;
+    /** 是否在弹框中显示（用于 HTMX 请求） */
+    isDialog?: boolean;
+}
+/**
+ * 权限提示内容组件（用于弹框或页面）
+ */
+declare function PermissionDeniedContent(props: PermissionDeniedContentProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+/**
+ * 权限提示页面组件（完整页面，用于整页加载）
+ */
+declare function PermissionDeniedPage(props: PermissionDeniedContentProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
 interface StringArrayEditorProps extends FormFieldRendererProps {
     /** 占位符文本（可选） */
@@ -973,6 +1311,38 @@ interface TagsEditorProps extends FormFieldRendererProps {
  */
 declare function TagsEditor(props: TagsEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
+interface ObjectEditorProps extends FormFieldRendererProps {
+    /** 对象的 Zod schema（用于自动渲染结构） */
+    objectSchema?: z$1.ZodObject<any>;
+}
+declare function ObjectEditor(props: ObjectEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 详情页字段渲染器
+ * 根据字段类型和值类型智能渲染字段值
+ */
+
+/**
+ * 默认详情字段渲染器
+ * 根据字段类型和值类型选择渲染方式
+ */
+declare function DetailFieldRenderer<T = any, K extends keyof T = keyof T>(props: FieldRendererProps<T, K> & {
+    /** 字段定义（可选，用于根据字段类型渲染） */
+    field?: ModelField;
+}): any;
+
+/**
+ * 列表列渲染器
+ * 根据字段类型和值类型智能渲染列值
+ * 列表列渲染通常比详情页更简洁
+ */
+
+/**
+ * 默认列渲染器
+ * 根据字段类型和值类型选择渲染方式
+ */
+declare function ColumnRenderer(value: any, field?: ModelField): any;
+
 /**
  * 可拖拽排序列表组件
  * 使用 HTML5 原生拖放 API 实现拖拽排序
@@ -1010,4 +1380,4 @@ interface SortableListProps {
  */
 declare function SortableList(props: SortableListProps): 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, ObjectEditor, type ObjectEditorProps, type PageMetadata, PageModel, type PermissionResult, SortableList, StringArrayEditor, type StringArrayEditorProps, TagsEditor, type TagsEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };
+export { type ActionButton, type AuthProvider, BaseFeature, BaseFormFeature, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, ColumnRenderer, CustomFeature, DefaultCreateFeature, DefaultDeleteFeature, DefaultDetailFeature, DefaultEditFeature, DefaultListFeature, DetailFieldRenderer, Dialog, type DialogProps, type DialogSize, EmptyState, type EmptyStateProps, ErrorAlert, type ErrorAlertProps, type Feature, type FeatureContext, type FeatureType, type FieldGroup, type FieldMetadata, type FieldRenderer, type FieldRendererProps, type FieldRendererType, type FieldRendererTypeMap, FilterForm, type FormAction, type FormField, type FormFieldRenderer, type FormFieldRendererMap, type FormFieldRendererProps, type FormGroup, Header, type HeaderProps, HtmxAdminPlugin, type HtmxAdminPluginOptions, type ListParams, type ListResult, LoadingBar, type ModelField, type NavItemConfig, type Notification, type NotificationType$1 as NotificationType, ObjectEditor, type ObjectEditorProps, type OpenMode, type PageMetadata, PageModel, Pagination, type PaginationProps, PermissionDeniedContent, type PermissionDeniedContentProps, PermissionDeniedPage, type PermissionResult, type ResolvedHtmxAdminPluginOptions, SortableList, type SortableListProps, StringArrayEditor, type StringArrayEditorProps, Table, type TableProps, TagsEditor, type TagsEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };