imean-service-engine-htmx-plugin 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1484 @@
+import { Context } from 'hono';
+import { z } from 'zod';
+import { Plugin, PluginPriority, PluginModuleOptionsSchema, Microservice, ModuleMetadata } from 'imean-service-engine';
+import * as hono_jsx_jsx_dev_runtime from 'hono/jsx/jsx-dev-runtime';
+
+/**
+ * HtmxAdminPlugin 类型定义
+ */
+
+/**
+ * 导航项配置
+ */
+interface NavItemConfig {
+    /** 导航标签 */
+    label: string;
+    /** 导航图标 */
+    icon?: string;
+    /** 自定义路径 */
+    href: string;
+    /** 嵌套子路由 */
+    children?: NavItemConfig[];
+}
+/**
+ * 用户信息接口
+ */
+interface UserInfo {
+    name?: string;
+    avatar?: string;
+    email?: string;
+    [key: string]: any;
+}
+/**
+ * 模块类型信息
+ */
+interface ModuleTypeInfo {
+    /** 模块标题 */
+    title: string;
+    /** 模块描述 */
+    description: string;
+    /** 模块基础路径 */
+    basePath: string;
+    /** 是否有 list 类型的模块 */
+    hasList: boolean;
+    /** 是否有 detail 类型的模块 */
+    hasDetail: boolean;
+    /** 是否有 form 类型的模块 */
+    hasForm: boolean;
+    /** 是否有 custom 类型的模块 */
+    hasCustom: boolean;
+}
+/**
+ * 面包屑项
+ */
+interface BreadcrumbItem {
+    label: string;
+    href?: string;
+}
+/**
+ * 站点配置选项
+ */
+interface HtmxAdminPluginOptions {
+    /** 站点标题 */
+    title?: string;
+    /** 站点 Logo URL（可选） */
+    logo?: string;
+    /** 管理后台路径前缀（默认 /admin） */
+    prefix?: string;
+    /** 首页路径（访问插件默认路径时重定向到此路径，如果未配置则使用第一个模块的路径） */
+    homePath?: string;
+    /** 导航配置（集中式声明导航结构，支持嵌套） */
+    navigation?: NavItemConfig[];
+    /** 获取用户信息的函数（用于显示用户信息） */
+    getUserInfo?: (ctx: Context) => UserInfo | null | Promise<UserInfo | null>;
+}
+/**
+ * 模块类型
+ */
+type ModuleType = "list" | "detail" | "form" | "custom";
+/**
+ * 模块配置选项
+ * 通用配置放在这里，不同类型页面的差异配置通过类来实现
+ */
+interface HtmxAdminModuleOptions {
+    type: ModuleType;
+    title?: string;
+    description?: string;
+    /** 是否使用管理后台布局（默认 true，设置为 false 时不使用侧边栏和头部，只使用 BaseLayout） */
+    useAdminLayout?: boolean;
+}
+/**
+ * 列表数据源接口（仅用于 list 类型）
+ */
+interface ListDatasource<T = any> {
+    /** 获取列表数据 */
+    getList(params: ListParams): Promise<ListResult<T>>;
+    /** 删除数据（可选，如果不提供则列表页不显示删除操作） */
+    deleteItem?(id: string | number): Promise<boolean>;
+}
+/**
+ * 详情数据源接口（仅用于 detail 类型）
+ */
+interface DetailDatasource<T = any> {
+    /** 获取单条数据 */
+    getItem(id: string | number): Promise<T | null>;
+    /** 删除数据（可选） */
+    deleteItem?(id: string | number): Promise<boolean>;
+}
+/**
+ * 表单数据源接口（仅用于 form 类型）
+ */
+interface FormDatasource<T = any> {
+    /** 获取单条数据（编辑时使用） */
+    getItem?(id: string | number): Promise<T | null>;
+    /** 更新数据 */
+    updateItem?(id: string | number, data: Partial<T>): Promise<T | null>;
+    /** 创建数据 */
+    createItem?(data: Partial<T>): Promise<T>;
+}
+/**
+ * 列表查询参数
+ */
+interface ListParams {
+    /** 页码（从1开始） */
+    page?: number;
+    /** 每页数量 */
+    pageSize?: number;
+    /** 排序字段 */
+    sortBy?: string;
+    /** 排序方向 */
+    sortOrder?: "asc" | "desc";
+    /** 筛选条件 */
+    filters?: Record<string, any>;
+}
+/**
+ * 列表查询结果
+ */
+interface ListResult<T> {
+    /** 数据列表 */
+    items: T[];
+    /** 总数量 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+    /** 总页数 */
+    totalPages: number;
+}
+
+/**
+ * Action Helper - 简化操作按钮定义
+ */
+/**
+ * Action Helper 类
+ * 提供便捷的方法来定义操作按钮，隐藏路径规则的具体实现
+ */
+declare class PathHelper {
+    private basePath;
+    constructor(basePath: string);
+    /**
+     * 详情页动作
+     * 生成路径: {basePath}/detail/{id}
+     * @param label 按钮标签
+     * @param dialog 是否在对话框中打开
+     */
+    detail(id: string | number, dialog?: boolean): string;
+    /**
+     * 编辑页动作
+     * 生成路径: {basePath}/edit/{id}
+     * @param dialog 是否在对话框中打开
+     */
+    edit(id: string | number, dialog?: boolean): string;
+    /**
+     * 删除动作
+     * 生成路径: {basePath}/detail/{id}，方法: DELETE
+     */
+    delete(id: string | number): string;
+    /**
+     * 新建页动作
+     * 生成路径: {basePath}/new
+     * @param label 按钮标签
+     * @param dialog 是否在对话框中打开
+     */
+    create(dialog?: boolean): string;
+    /**
+     * 列表页动作
+     * 生成路径: {basePath}/list
+     */
+    list(): string;
+    base(): string;
+}
+
+/**
+ * HtmxAdmin 上下文对象
+ * 封装请求处理过程中的状态和操作
+ */
+
+/**
+ * 通知类型
+ */
+type NotificationType = "error" | "warning" | "info" | "success";
+/**
+ * 通知项
+ */
+interface Notification {
+    type: NotificationType;
+    title: string;
+    message: string;
+}
+/**
+ * HtmxAdmin 上下文
+ * 封装请求处理过程中的所有状态和操作
+ */
+declare class HtmxAdminContext {
+    /** 模块元数据 */
+    readonly moduleMetadata: ModuleTypeInfo;
+    /** 插件选项 */
+    readonly pluginOptions: Required<HtmxAdminPluginOptions>;
+    /** Hono Context */
+    readonly ctx: Context;
+    /** 之前的模块名 */
+    readonly previousModuleName?: string;
+    /** 是否是片段请求（HTMX 请求） */
+    readonly isFragment: boolean;
+    /** 是否是对话框请求 */
+    readonly isDialog: boolean;
+    /** 用户信息 */
+    readonly userInfo: UserInfo | null;
+    /** 通知队列 */
+    readonly notifications: Notification[];
+    /** 页面标题（用于 HX-Title 和页面展示） */
+    title: string;
+    /** 页面描述（用于SEO和页面展示） */
+    description: string;
+    /** 面包屑项 */
+    breadcrumbs: BreadcrumbItem[];
+    /** 主要内容 */
+    content: any;
+    /** 需要重定向的 URL */
+    redirectUrl?: string;
+    /** 是否需要刷新页面（用于 HX-Refresh） */
+    refresh: boolean;
+    constructor(ctx: Context, userInfo: UserInfo | null, moduleMetadata: ModuleTypeInfo, pluginOptions: Required<HtmxAdminPluginOptions>);
+    /**
+     * 发送通知
+     * 通知将在响应时通过 OOB 更新到错误容器
+     */
+    sendNotification(type: NotificationType, title: string, message: string): void;
+    /**
+     * 发送错误通知（便捷方法）
+     */
+    sendError(title: string, message: string): void;
+    /**
+     * 发送警告通知（便捷方法）
+     */
+    sendWarning(title: string, message: string): void;
+    /**
+     * 发送信息通知（便捷方法）
+     */
+    sendInfo(title: string, message: string): void;
+    /**
+     * 发送成功通知（便捷方法）
+     */
+    sendSuccess(title: string, message: string): void;
+    /**
+     * 设置需要推送的 URL
+     * 用于 HX-Push-Url 响应头
+     */
+    redirect(url: string): void;
+    /**
+     * 设置需要刷新页面
+     * 用于 HX-Refresh 响应头
+     */
+    setRefresh(refresh?: boolean): void;
+    /**
+     * 检查是否有列表页面
+     * 封装 moduleMetadata 访问，避免直接访问内部属性
+     */
+    hasList(): boolean;
+    /**
+     * 检查是否有详情页面
+     * 封装 moduleMetadata 访问，避免直接访问内部属性
+     */
+    hasDetail(): boolean;
+    /**
+     * 检查是否有表单页面
+     * 封装 moduleMetadata 访问，避免直接访问内部属性
+     */
+    hasForm(): boolean;
+    /**
+     * 检查是否有自定义页面
+     * 封装 moduleMetadata 访问，避免直接访问内部属性
+     */
+    hasCustom(): boolean;
+}
+
+/**
+ * Page 模块基类
+ * 所有页面模块的基类，提供通用的属性和方法
+ */
+
+/**
+ * Page 页面模块基类
+ * 所有页面模块都继承此类，包括 ListPageModule、DetailPageModule、FormPageModule
+ *
+ * 对于 custom 类型的模块，必须实现 render 方法
+ * 对于其他类型的模块，可以重写 render 方法来自定义渲染，否则使用默认渲染逻辑
+ */
+declare abstract class PageModule {
+    /** HtmxAdmin 上下文对象 */
+    context: HtmxAdminContext;
+    /** Action Helper 实例 */
+    paths: PathHelper;
+    /**
+     * 初始化模块实例（私有方法，仅由 RouteHandler 调用）
+     * 用于设置模块的基础属性
+     */
+    __init(context: HtmxAdminContext): void;
+    /**
+     * 获取页面标题
+     * 子类可以重写此方法来返回页面标题
+     * 默认实现：使用模块名
+     */
+    getTitle(): string;
+    /**
+     * 获取页面描述
+     * 子类可以重写此方法来返回页面描述（用于SEO和页面展示）
+     * 默认实现：返回空字符串
+     */
+    getDescription(): string;
+    /**
+     * 获取面包屑
+     * 子类可以重写此方法来自定义面包屑
+     * 默认实现：首页 => 自定义页面
+     */
+    getBreadcrumbs(): BreadcrumbItem[];
+    /**
+     * 处理请求的统一入口（由 RouteHandler 调用）
+     * 默认实现：直接调用 render 方法
+     * 子类可以重写此方法来处理请求级别的逻辑（如根据 HTTP method 分发）
+     *
+     * @param adminContext HtmxAdmin 上下文对象（必需），包含请求状态和 helper 方法
+     * @returns 页面内容
+     */
+    __handle(): Promise<any>;
+    /**
+     * 渲染页面内容
+     *
+     * 所有页面模块都必须提供 render 方法
+     * - Custom 类型：必须实现此方法
+     * - List/Detail/Form 类型：基类提供默认实现，可以重写来自定义渲染
+     *
+     * @param adminContext HtmxAdmin 上下文对象（必需），包含请求状态和 helper 方法
+     *                     可以通过 adminContext.ctx 访问 Hono Context
+     */
+    abstract render(): any | Promise<any>;
+}
+
+/**
+ * Detail 模块基类
+ * 用于详情展示，继承自 PageModule
+ */
+
+/**
+ * Detail 页面模块基类
+ * 继承自 PageModule，提供详情页面的默认行为
+ *
+ * 可以重写 render 方法来自定义渲染，否则使用默认的详情渲染逻辑
+ */
+declare abstract class DetailPageModule<T = any> extends PageModule {
+    /** ID 字段名（默认 "id"） */
+    protected readonly idField: string;
+    /**
+     * 获取数据源（抽象方法，必须实现）
+     * 子类必须实现此方法来提供数据源
+     */
+    abstract getDatasource(): DetailDatasource<T>;
+    /**
+     * 获取字段标签（可选）
+     * 子类可以重写此方法来自定义字段的中文标签
+     */
+    getFieldLabel?(field: string): string;
+    /**
+     * 渲染字段值（可选）
+     * 子类可以重写此方法来自定义字段的渲染方式
+     */
+    renderField?(field: string, value: any, item: T): any;
+    /**
+     * 获取字段分组（可选）
+     * 子类可以重写此方法来定义字段分组
+     * 返回 null 或 undefined 表示不分组，平铺显示
+     */
+    getFieldGroups?(item: T): Array<{
+        title: string;
+        fields: string[];
+    }> | null;
+    /**
+     * 获取可见字段列表（可选）
+     * 子类可以重写此方法来控制字段的显示顺序和可见性
+     * 返回 null 或 undefined 表示显示所有字段
+     */
+    getVisibleFields?(item: T): string[] | null;
+    /**
+     * 获取详情页操作按钮（可选）
+     * 子类可以重写此方法来添加详情页的操作按钮
+     * 如果不定义，则根据模块元数据智能生成默认操作按钮
+     */
+    getDetailActions?(item: T): Array<{
+        label: string;
+        href: string | ((item: T) => string);
+        method?: string;
+        class?: string;
+    }>;
+    /**
+     * 渲染详情页面（默认实现）
+     * 子类可以重写此方法来自定义渲染
+     */
+    render(): Promise<any>;
+}
+
+/**
+ * Form 模块基类
+ * 用于表单（新建/编辑），继承自 PageModule
+ */
+
+/**
+ * Form 页面模块基类
+ * 继承自 PageModule，提供表单页面的默认行为
+ *
+ * 可以重写 render 方法来自定义渲染，否则使用默认的表单渲染逻辑
+ */
+declare abstract class FormPageModule<T = any> extends PageModule {
+    /** ID 字段名（默认 "id"） */
+    protected idField: string;
+    /** Zod Schema（可选，如果提供则自动生成表单字段和校验） */
+    protected schema?: z.ZodObject<any>;
+    constructor(schema?: z.ZodObject<any>);
+    /**
+     * 获取数据源（抽象方法，必须实现）
+     * 子类必须实现此方法来提供数据源
+     */
+    abstract getDatasource(): FormDatasource<T>;
+    /**
+     * 获取单条数据（编辑时使用）
+     */
+    getItem(id: string | number): Promise<T | null>;
+    /**
+     * 获取字段标签（可选）
+     * 子类可以重写此方法来自定义字段的中文标签
+     */
+    getFieldLabel?(field: string): string;
+    /**
+     * 获取表单字段定义
+     *
+     * 如果提供了 schema，则自动从 schema 生成字段定义
+     * 否则子类必须实现此方法来定义表单的字段
+     */
+    getFormFields(item: T | null): Array<{
+        name: string;
+        label: string;
+        type?: "text" | "email" | "number" | "textarea" | "select" | "date" | "datetime-local";
+        required?: boolean;
+        placeholder?: string;
+        options?: Array<{
+            value: string | number;
+            label: string;
+        }>;
+    }>;
+    /**
+     * 获取字段标签映射（可选）
+     * 用于覆盖从 schema description 提取的标签
+     */
+    getFieldLabels?(): Record<string, string>;
+    /**
+     * 获取字段占位符映射（可选）
+     */
+    getFieldPlaceholders?(): Record<string, string>;
+    /**
+     * 获取字段选项映射（可选）
+     * 用于覆盖从 schema enum 提取的选项
+     */
+    getFieldOptions?(): Record<string, Array<{
+        value: string | number;
+        label: string;
+    }>>;
+    /**
+     * 获取字段类型映射（可选）
+     * 用于覆盖自动推断的类型
+     */
+    getFieldTypes?(): Record<string, "text" | "email" | "number" | "textarea" | "select" | "date" | "datetime-local">;
+    /**
+     * 获取要排除的字段列表（可选）
+     */
+    getExcludeFields?(): string[];
+    /**
+     * 验证表单数据
+     *
+     * 如果提供了 schema，则自动使用 schema 进行校验
+     * 否则子类可以重写此方法来验证表单数据
+     */
+    validateFormData(data: Record<string, any>, item: T | null): string | null;
+    /**
+     * 处理请求的统一入口（重写基类方法）
+     * 根据 HTTP method 处理不同请求：
+     * - GET: 渲染表单页面（调用 render）
+     * - POST: 创建数据
+     * - PUT: 更新数据
+     * - DELETE: 删除数据
+     * 子类可以重写此方法来自定义请求处理逻辑
+     */
+    __handle(): Promise<any>;
+    /**
+     * 渲染表单页面（默认实现）
+     * 子类可以重写此方法来自定义渲染
+     * @param formData 表单数据（用于回填验证失败时的值）
+     */
+    render(formData?: Record<string, any>): Promise<any>;
+    /**
+     * 处理创建请求（POST）
+     */
+    private handleCreate;
+    /**
+     * 处理更新请求（PUT）
+     */
+    private handleUpdate;
+    /**
+     * 处理删除请求（DELETE）
+     * 注意：FormDatasource 不包含 deleteItem，删除操作通常由 List 或 Detail 模块处理
+     * 这里提供默认实现，子类可以重写
+     */
+    private handleDelete;
+    /**
+     * 渲染表单页面（辅助方法）
+     * 用于在验证失败时重新渲染表单页面
+     * @param adminContext 上下文对象
+     * @param item 原始数据项（编辑时）
+     * @param isEdit 是否是编辑模式
+     * @param formData 表单数据（用于回填验证失败时的值）
+     */
+    private renderFormPage;
+}
+
+/**
+ * List 模块基类
+ * 用于列表展示，继承自 PageModule
+ */
+
+/**
+ * List 页面模块基类
+ * 继承自 PageModule，提供列表页面的默认行为
+ *
+ * 可以重写 render 方法来自定义渲染，否则使用默认的列表渲染逻辑
+ */
+declare abstract class ListPageModule<T extends {
+    id: string | number;
+} = {
+    id: string | number;
+}> extends PageModule {
+    /** ID 字段名（默认 "id"） */
+    protected readonly idField: string;
+    /**
+     * 获取数据源（抽象方法，必须实现）
+     * 子类必须实现此方法来提供数据源
+     */
+    abstract getDatasource(): ListDatasource<T>;
+    /**
+     * 获取列表数据
+     */
+    getList(params: ListParams): Promise<ListResult<T>>;
+    /**
+     * 删除数据（可选，如果数据源支持删除）
+     */
+    deleteItem(id: string | number): Promise<boolean>;
+    /**
+     * 获取字段标签（可选）
+     * 子类可以重写此方法来自定义字段的中文标签
+     */
+    getFieldLabel?(field: string): string;
+    /**
+     * 自定义列渲染（可选）
+     * 子类可以重写此方法来自定义列的渲染逻辑
+     */
+    renderColumn?(field: string, value: any, item: T): any;
+    /**
+     * 获取统计信息（可选）
+     * 子类可以重写此方法来返回 KPI 统计卡片数据
+     * 返回的数组将渲染为 StatCard 组件
+     */
+    getStats?(params: ListParams): Promise<Array<{
+        title: string;
+        value: string | number;
+        change?: number;
+        changeLabel?: string;
+        iconColor?: "blue" | "green" | "yellow" | "purple" | "red" | "indigo";
+        icon?: any;
+    }>> | Array<{
+        title: string;
+        value: string | number;
+        change?: number;
+        changeLabel?: string;
+        iconColor?: "blue" | "green" | "yellow" | "purple" | "red" | "indigo";
+        icon?: any;
+    }>;
+    /**
+     * 获取筛选器配置（可选）
+     * 子类可以重写此方法来返回筛选器字段配置
+     * 返回的配置将渲染为 FilterCard 组件
+     */
+    getFilters?(params: ListParams): Array<{
+        name: string;
+        label: string;
+        options: Array<{
+            value: string | number;
+            label: string;
+            disabled?: boolean;
+        }>;
+        value?: string | number;
+        defaultValue?: string | number;
+    }>;
+    /**
+     * 获取表格标题（可选）
+     * 子类可以重写此方法来返回表格标题
+     * 如果不定义，默认使用模块名
+     */
+    getTableTitle?(): string;
+    /**
+     * 获取表格操作按钮（可选）
+     * 子类可以重写此方法来返回表格操作按钮配置（如导出、清空、刷新等）
+     * 如果不定义，默认会生成一个刷新按钮
+     */
+    getTableActions?(params: ListParams, basePath: string): Array<{
+        label: string;
+        href?: string;
+        hxGet?: string;
+        hxPost?: string;
+        hxDelete?: string;
+        variant?: "primary" | "secondary" | "danger" | "ghost";
+        hxConfirm?: string;
+    }>;
+    /**
+     * 自定义操作按钮（可选）
+     * 子类可以重写此方法来添加自定义操作按钮
+     * 如果不定义，则根据模块元数据智能生成默认操作按钮
+     */
+    getActions?(item: T): Array<{
+        label: string;
+        href: string | ((item: T) => string);
+        method?: string;
+        class?: string;
+    }>;
+    /**
+     * 渲染列表页面（默认实现）
+     * 子类可以重写此方法来自定义渲染
+     */
+    render(): Promise<any>;
+}
+
+/**
+ * 数据源接口和基础实现
+ */
+
+/**
+ * 内存数据源（完整实现，可用于 list、detail、form 类型）
+ */
+declare class MemoryListDatasource<T extends {
+    id: string | number;
+}> implements ListDatasource<T>, DetailDatasource<T>, FormDatasource<T> {
+    private data;
+    constructor(data?: T[]);
+    getList(params?: ListParams): Promise<ListResult<T>>;
+    getItem(id: string | number): Promise<T | null>;
+    deleteItem(id: string | number): Promise<boolean>;
+    updateItem(id: string | number, data: Partial<T>): Promise<T | null>;
+    createItem(data: Partial<T>): Promise<T>;
+}
+
+/**
+ * HtmxAdminPlugin - 管理后台插件
+ * 使用 HTMX + Tailwind + Hyperscript + JSX 快速构建管理后台
+ */
+
+/**
+ * HtmxAdminPlugin
+ */
+declare class HtmxAdminPlugin implements Plugin<HtmxAdminModuleOptions> {
+    readonly name = "htmx-admin-plugin";
+    readonly priority = PluginPriority.ROUTE;
+    private engine;
+    private hono;
+    private options;
+    private moduleTypeMap;
+    constructor(options?: HtmxAdminPluginOptions);
+    /**
+     * 声明Module配置Schema
+     */
+    getModuleOptionsSchema(): PluginModuleOptionsSchema<HtmxAdminModuleOptions>;
+    /**
+     * 引擎初始化钩子
+     */
+    onInit(engine: Microservice): void;
+    /**
+     * 检查并注册模块
+     */
+    private checkAndRegisterModules;
+    /**
+     * 注册路由
+     */
+    private registerRoutes;
+    /**
+     * 模块加载钩子：检查模块类型约束并注册路由
+     */
+    onModuleLoad(modules: ModuleMetadata[]): void;
+}
+
+/**
+ * 渲染工具函数
+ */
+/**
+ * 安全渲染值（支持 JSX 和字符串 HTML）
+ * 如果返回的是字符串 HTML，将其转换为 JSX 元素
+ */
+declare function safeRender(value: any): any;
+
+/**
+ * 表单组件（用于编辑和新建）
+ */
+/**
+ * 字段定义
+ */
+interface FormField$1 {
+    /** 字段名 */
+    name: string;
+    /** 字段标签 */
+    label: string;
+    /** 字段类型 */
+    type?: "text" | "email" | "number" | "textarea" | "select" | "date" | "datetime-local";
+    /** 是否必填 */
+    required?: boolean;
+    /** 占位符 */
+    placeholder?: string;
+    /** 选项（用于 select 类型） */
+    options?: Array<{
+        value: string | number;
+        label: string;
+    }>;
+    /** 自定义渲染函数 */
+    render?: (value: any, item: any) => any;
+}
+/**
+ * 表单组件 Props
+ */
+interface FormProps<T = any> {
+    /** 数据项（编辑时传入，新建时为 null） */
+    item: T | null;
+    /** 字段定义列表 */
+    fields: FormField$1[];
+    /** 提交 URL */
+    submitUrl: string;
+    /** 提交方法（默认 PUT） */
+    method?: "PUT" | "POST";
+    /** 提交后重定向 URL */
+    redirectUrl?: string;
+    /** 页面标题（默认 "编辑" 或 "新建"） */
+    title?: string;
+    /** 取消按钮 URL */
+    cancelUrl?: string;
+    /** 是否在对话框中显示 */
+    isDialog?: boolean;
+    /** 表单数据（用于回填验证失败时的值） */
+    formData?: Record<string, any>;
+}
+/**
+ * 表单组件
+ */
+declare const Form: <T extends Record<string, any>>(props: FormProps<T>) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * Zod Schema 表单工具
+ * 从 Zod Schema 自动生成表单字段定义和校验逻辑
+ */
+
+/**
+ * 从 Zod Object Schema 生成表单字段定义
+ */
+declare function generateFormFieldsFromSchema<T extends z.ZodObject<any>>(schema: T, options?: {
+    /** 字段标签映射（覆盖从 description 提取的标签） */
+    fieldLabels?: Record<string, string>;
+    /** 字段占位符映射 */
+    fieldPlaceholders?: Record<string, string>;
+    /** 字段选项映射（覆盖从 enum 提取的选项） */
+    fieldOptions?: Record<string, Array<{
+        value: string | number;
+        label: string;
+    }>>;
+    /** 字段类型映射（覆盖自动推断的类型） */
+    fieldTypes?: Record<string, FormField$1["type"]>;
+    /** 要排除的字段 */
+    excludeFields?: string[];
+}): FormField$1[];
+/**
+ * 使用 Zod Schema 验证表单数据
+ */
+declare function validateFormDataWithSchema<T extends z.ZodObject<any>>(schema: T, data: Record<string, any>): {
+    success: true;
+    data: z.infer<T>;
+} | {
+    success: false;
+    error: string;
+};
+
+/**
+ * 操作按钮组件
+ */
+interface ActionButtonProps {
+    /** 按钮文本 */
+    label: string;
+    /** 链接地址 */
+    href: string | ((item: any) => string);
+    /** HTTP 方法 */
+    method?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 数据项（用于生成动态链接） */
+    item?: any;
+}
+/**
+ * 操作按钮组件
+ */
+declare const ActionButton: (props: ActionButtonProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 最近活动卡片组件
+ */
+interface ActivityItem {
+    /** 活动描述 */
+    description: string;
+    /** 时间（如"2分钟前"） */
+    time: string;
+    /** 活动类型颜色（blue, green, purple, gray等） */
+    color?: "blue" | "green" | "purple" | "gray" | "yellow" | "red";
+}
+interface ActivityCardProps {
+    /** 标题 */
+    title: string;
+    /** 活动列表 */
+    activities: ActivityItem[];
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * 最近活动卡片组件
+ * 用于展示最近的活动记录列表
+ */
+declare const ActivityCard: (props: ActivityCardProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 徽章组件（用于标签显示）
+ */
+interface BadgeProps {
+    /** 标签文本 */
+    children: any;
+    /** 颜色主题 */
+    variant?: "blue" | "green" | "yellow" | "red" | "gray" | "purple" | "indigo";
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * 徽章组件
+ * 用于显示状态标签，如日志级别、状态等
+ */
+declare const Badge: (props: BadgeProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 按钮组件
+ */
+interface ButtonProps {
+    /** 按钮文本 */
+    children: any;
+    /** 按钮类型 */
+    variant?: "primary" | "secondary" | "danger" | "ghost";
+    /** 按钮大小 */
+    size?: "sm" | "md" | "lg";
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 自定义类名 */
+    className?: string;
+    /** HTMX 属性 */
+    hxGet?: string;
+    hxPost?: string;
+    hxPut?: string;
+    hxDelete?: string;
+    hxTarget?: string;
+    hxSwap?: string;
+    hxPushUrl?: string | boolean;
+    hxIndicator?: string;
+    hxConfirm?: string;
+    hxHeaders?: string;
+    /** 其他属性 */
+    [key: string]: any;
+}
+/**
+ * 按钮组件
+ */
+declare const Button: (props: ButtonProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 卡片组件
+ */
+interface CardProps {
+    /** 卡片内容 */
+    children: any;
+    /** 卡片标题 */
+    title?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 是否显示阴影 */
+    shadow?: boolean;
+    /** 是否显示边框 */
+    bordered?: boolean;
+    /** 是否去掉内边距 */
+    noPadding?: boolean;
+}
+/**
+ * 卡片组件
+ */
+declare const Card: (props: CardProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 详情页面组件
+ */
+/**
+ * 字段组定义
+ */
+interface FieldGroup {
+    title: string;
+    fields: string[];
+}
+/**
+ * 详情页面组件 Props
+ */
+interface DetailProps<T = any> {
+    /** 数据项 */
+    item: T;
+    /** 字段标签映射（字段名 -> 中文标签） */
+    fieldLabels?: Record<string, string>;
+    /** 字段渲染函数（字段名 -> 渲染函数） */
+    fieldRenderers?: Record<string, (value: any, item: T) => any>;
+    /** 字段分组（可选，如果不提供则平铺显示） */
+    fieldGroups?: FieldGroup[];
+    /** 可见字段列表（控制显示顺序和可见性） */
+    visibleFields?: string[];
+    /** 操作按钮 */
+    actions?: Array<{
+        label: string;
+        href: string | ((item: T) => string);
+        method?: string;
+        class?: string;
+    }>;
+    /** 页面标题（默认 "详情"） */
+    title?: string;
+    /** 是否在对话框中显示 */
+    isDialog?: boolean;
+}
+/**
+ * 详情页面组件
+ */
+declare const Detail: <T extends Record<string, any>>(props: DetailProps<T>) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * DetailContent - 详情内容组件（纯组件）
+ * 接收渲染所需的数据，渲染详情页面内容
+ */
+/**
+ * 详情内容组件 Props
+ */
+interface DetailContentProps<T = any> {
+    /** 数据项 */
+    item: T;
+    /** 字段标签映射 */
+    fieldLabels: Record<string, string>;
+    /** 字段渲染器映射 */
+    fieldRenderers?: Record<string, (value: any, item: T) => any>;
+    /** 字段分组 */
+    fieldGroups?: Array<{
+        title: string;
+        fields: string[];
+    }>;
+    /** 可见字段列表 */
+    visibleFields?: string[];
+    /** 操作按钮配置 */
+    actions?: Array<{
+        label: string;
+        href: string | ((item: T) => string);
+        method?: string;
+        class?: string;
+    }>;
+    /** 页面标题 */
+    title: string;
+    /** 是否是对话框模式 */
+    isDialog: boolean;
+}
+/**
+ * 详情内容组件
+ */
+declare function DetailContent<T extends Record<string, any> = Record<string, any>>(props: DetailContentProps<T>): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 对话框组件（Modal/Dialog）
+ */
+interface DialogProps {
+    /** 对话框标题 */
+    title?: string;
+    /** 对话框内容 */
+    children: any;
+    /** 是否显示关闭按钮 */
+    showClose?: boolean;
+    /** 关闭时的回调 URL（用于关闭对话框） */
+    closeUrl?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 对话框大小 */
+    size?: "sm" | "md" | "lg" | "xl" | "full";
+}
+/**
+ * 对话框组件
+ * 用于在模态框中显示内容，支持 HTMX 交互
+ */
+declare const Dialog: (props: DialogProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 空状态组件
+ */
+interface EmptyStateProps {
+    /** 提示文本 */
+    message?: string;
+    /** 自定义内容 */
+    children?: any;
+}
+/**
+ * 空状态组件
+ */
+declare const EmptyState: (props: EmptyStateProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+interface ErrorAlertProps {
+    /** 错误标题 */
+    title?: string;
+    /** 错误消息 */
+    message: string;
+    /** 错误类型 */
+    type?: NotificationType;
+    /** 是否显示关闭按钮 */
+    showClose?: boolean;
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * 错误提示组件
+ * 用于显示错误、警告或信息提示
+ */
+declare const ErrorAlert: (props: ErrorAlertProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 选择框组件
+ */
+interface SelectOption {
+    value: string | number;
+    label: string;
+    disabled?: boolean;
+}
+interface SelectProps {
+    /** 字段ID */
+    id?: string;
+    /** 字段名 */
+    name: string;
+    /** 字段值 */
+    value?: string | number;
+    /** 默认值 */
+    defaultValue?: string | number;
+    /** 是否必填 */
+    required?: boolean;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 选项列表 */
+    options: SelectOption[];
+    /** 占位符选项（当required为false时显示） */
+    placeholder?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 其他属性 */
+    [key: string]: any;
+}
+/**
+ * 选择框组件
+ */
+declare const Select: (props: SelectProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+interface FilterField {
+    /** 字段名 */
+    name: string;
+    /** 字段标签 */
+    label: string;
+    /** 选项列表 */
+    options: SelectOption[];
+    /** 当前值 */
+    value?: string | number;
+    /** 默认值 */
+    defaultValue?: string | number;
+}
+interface FilterCardProps {
+    /** 标题 */
+    title?: string;
+    /** 筛选字段列表 */
+    fields: FilterField[];
+    /** 筛选按钮文本 */
+    filterButtonText?: string;
+    /** 筛选按钮的 HTMX 属性 */
+    filterButtonHxGet?: string;
+    /** 需要保留的查询参数名列表（如排序参数） */
+    preserveParams?: string[];
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * 筛选卡片组件
+ * 用于展示筛选表单，包含多个下拉选择器和筛选按钮
+ */
+declare const FilterCard: (props: FilterCardProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 列表内容组件 Props
+ */
+interface ListContentProps<T = any> {
+    /** 列表查询结果 */
+    result: ListResult<T>;
+    /** 列表查询参数 */
+    params: ListParams;
+    /** 页面标题 */
+    pageTitle: string;
+    /** 页面描述 */
+    pageDescription?: string;
+    /** 表格标题 */
+    tableTitle: string;
+    /** 列定义 */
+    columns: Array<{
+        key: string;
+        label: string;
+        render?: (value: any, item: T) => any;
+    }>;
+    /** 操作按钮配置 */
+    actions?: Array<{
+        label: string;
+        href: string | ((item: T) => string);
+        method?: string;
+        class?: string;
+    }>;
+    /** 统计信息（KPI卡片） */
+    stats?: Array<{
+        title: string;
+        value: string | number;
+        change?: number;
+        changeLabel?: string;
+        iconColor?: "blue" | "green" | "yellow" | "purple" | "red" | "indigo";
+        icon?: any;
+    }>;
+    /** 筛选器配置 */
+    filters?: Array<{
+        name: string;
+        label: string;
+        options: Array<{
+            value: string | number;
+            label: string;
+            disabled?: boolean;
+        }>;
+        value?: string | number;
+        defaultValue?: string | number;
+    }>;
+    /** 表格操作按钮 */
+    tableActions?: Array<{
+        label: string;
+        href?: string;
+        hxGet?: string;
+        hxPost?: string;
+        hxDelete?: string;
+        variant?: "primary" | "secondary" | "danger" | "ghost";
+        hxConfirm?: string;
+    }>;
+    /** 是否有 form 模块（用于决定是否显示新建按钮） */
+    hasFormModule: boolean;
+    /** 新建按钮路径 */
+    createPath: string;
+    /** 列表路径（用于分页和筛选） */
+    listPath: string;
+}
+/**
+ * 列表内容组件
+ */
+declare function ListContent<T extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(props: ListContentProps<T>): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 页面标题组件
+ */
+interface PageHeaderProps {
+    /** 标题 */
+    title: string;
+    /** 描述文本 */
+    description?: string;
+    /** 右侧操作按钮 */
+    actions?: any;
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * 页面标题组件
+ */
+declare const PageHeader: (props: PageHeaderProps) => 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 const Pagination: (props: PaginationProps) => hono_jsx_jsx_dev_runtime.JSX.Element | null;
+
+/**
+ * 统计卡片组件（KPI卡片）
+ */
+interface StatCardProps {
+    /** 标题 */
+    title: string;
+    /** 数值 */
+    value: string | number;
+    /** 变化百分比（正数表示增长，负数表示下降） */
+    change?: number;
+    /** 变化描述（如"相比上月"） */
+    changeLabel?: string;
+    /** 图标颜色（blue, green, yellow, purple等） */
+    iconColor?: "blue" | "green" | "yellow" | "purple" | "red" | "indigo";
+    /** 自定义图标（SVG或emoji） */
+    icon?: any;
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * 统计卡片组件
+ * 用于展示关键指标，包含标题、数值、变化趋势和图标
+ */
+declare const StatCard: (props: StatCardProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 系统状态卡片组件
+ */
+interface StatusItem {
+    /** 状态名称 */
+    label: string;
+    /** 当前值（百分比或文本） */
+    value: string | number;
+    /** 进度条百分比（0-100） */
+    progress?: number;
+    /** 进度条颜色 */
+    color?: "blue" | "green" | "orange" | "red" | "purple" | "yellow";
+    /** 是否为文本状态（如"正常"） */
+    isText?: boolean;
+}
+interface SystemStatusCardProps {
+    /** 标题 */
+    title: string;
+    /** 状态项列表 */
+    statusItems: StatusItem[];
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * 系统状态卡片组件
+ * 用于展示系统资源使用情况，包含进度条和文本状态
+ */
+declare const SystemStatusCard: (props: SystemStatusCardProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 日期输入组件
+ */
+interface DateInputProps {
+    /** 字段ID */
+    id?: string;
+    /** 字段名 */
+    name: string;
+    /** 日期类型 */
+    type?: "date" | "datetime-local" | "time" | "month" | "week";
+    /** 字段值 */
+    value?: string;
+    /** 默认值 */
+    defaultValue?: string;
+    /** 是否必填 */
+    required?: boolean;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 是否只读 */
+    readOnly?: boolean;
+    /** 最小值 */
+    min?: string;
+    /** 最大值 */
+    max?: string;
+    /** 自定义类名 */
+    className?: string;
+    /** 其他属性 */
+    [key: string]: any;
+}
+/**
+ * 日期输入组件
+ */
+declare const DateInput: (props: DateInputProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 表单字段组件（标签 + 输入框的包装器）
+ */
+interface FormFieldProps {
+    /** 字段标签 */
+    label: string;
+    /** 字段ID（用于关联label和input） */
+    id: string;
+    /** 是否必填 */
+    required?: boolean;
+    /** 错误信息 */
+    error?: string;
+    /** 帮助文本 */
+    help?: string;
+    /** 子元素（输入框等） */
+    children: any;
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * 表单字段组件
+ * 提供统一的标签、错误提示、帮助文本样式
+ */
+declare const FormField: (props: FormFieldProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 输入框组件
+ */
+interface InputProps {
+    /** 字段ID */
+    id?: string;
+    /** 字段名 */
+    name: string;
+    /** 字段类型 */
+    type?: "text" | "email" | "password" | "number" | "tel" | "url" | "search";
+    /** 字段值 */
+    value?: string | number;
+    /** 默认值 */
+    defaultValue?: string | number;
+    /** 占位符 */
+    placeholder?: string;
+    /** 是否必填 */
+    required?: boolean;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 是否只读 */
+    readOnly?: boolean;
+    /** 最小值（用于number类型） */
+    min?: number;
+    /** 最大值（用于number类型） */
+    max?: number;
+    /** 步长（用于number类型） */
+    step?: number;
+    /** 自定义类名 */
+    className?: string;
+    /** 其他属性 */
+    [key: string]: any;
+}
+/**
+ * 输入框组件
+ */
+declare const Input: (props: InputProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 文本域组件
+ */
+interface TextareaProps {
+    /** 字段ID */
+    id?: string;
+    /** 字段名 */
+    name: string;
+    /** 字段值 */
+    value?: string;
+    /** 默认值 */
+    defaultValue?: string;
+    /** 占位符 */
+    placeholder?: string;
+    /** 是否必填 */
+    required?: boolean;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 是否只读 */
+    readOnly?: boolean;
+    /** 行数 */
+    rows?: number;
+    /** 自定义类名 */
+    className?: string;
+    /** 其他属性 */
+    [key: string]: any;
+}
+/**
+ * 文本域组件
+ */
+declare const Textarea: (props: TextareaProps) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * HtmxAdmin 组件导出
+ * 外部可用的组件通过 Components 命名空间导出
+ */
+
+declare const index_ActionButton: typeof ActionButton;
+type index_ActionButtonProps = ActionButtonProps;
+declare const index_ActivityCard: typeof ActivityCard;
+type index_ActivityCardProps = ActivityCardProps;
+type index_ActivityItem = ActivityItem;
+declare const index_Badge: typeof Badge;
+type index_BadgeProps = BadgeProps;
+declare const index_Button: typeof Button;
+type index_ButtonProps = ButtonProps;
+declare const index_Card: typeof Card;
+type index_CardProps = CardProps;
+declare const index_DateInput: typeof DateInput;
+type index_DateInputProps = DateInputProps;
+declare const index_Detail: typeof Detail;
+declare const index_DetailContent: typeof DetailContent;
+type index_DetailContentProps<T = any> = DetailContentProps<T>;
+type index_DetailProps<T = any> = DetailProps<T>;
+declare const index_Dialog: typeof Dialog;
+type index_DialogProps = DialogProps;
+declare const index_EmptyState: typeof EmptyState;
+type index_EmptyStateProps = EmptyStateProps;
+declare const index_ErrorAlert: typeof ErrorAlert;
+type index_ErrorAlertProps = ErrorAlertProps;
+type index_FieldGroup = FieldGroup;
+declare const index_FilterCard: typeof FilterCard;
+type index_FilterCardProps = FilterCardProps;
+type index_FilterField = FilterField;
+declare const index_Form: typeof Form;
+declare const index_FormField: typeof FormField;
+type index_FormFieldProps = FormFieldProps;
+type index_FormProps<T = any> = FormProps<T>;
+declare const index_Input: typeof Input;
+type index_InputProps = InputProps;
+declare const index_ListContent: typeof ListContent;
+type index_ListContentProps<T = any> = ListContentProps<T>;
+declare const index_PageHeader: typeof PageHeader;
+type index_PageHeaderProps = PageHeaderProps;
+declare const index_Pagination: typeof Pagination;
+type index_PaginationProps = PaginationProps;
+declare const index_Select: typeof Select;
+type index_SelectOption = SelectOption;
+type index_SelectProps = SelectProps;
+declare const index_StatCard: typeof StatCard;
+type index_StatCardProps = StatCardProps;
+type index_StatusItem = StatusItem;
+declare const index_SystemStatusCard: typeof SystemStatusCard;
+type index_SystemStatusCardProps = SystemStatusCardProps;
+declare const index_Textarea: typeof Textarea;
+type index_TextareaProps = TextareaProps;
+declare namespace index {
+  export { index_ActionButton as ActionButton, type index_ActionButtonProps as ActionButtonProps, index_ActivityCard as ActivityCard, type index_ActivityCardProps as ActivityCardProps, type index_ActivityItem as ActivityItem, index_Badge as Badge, type index_BadgeProps as BadgeProps, index_Button as Button, type index_ButtonProps as ButtonProps, index_Card as Card, type index_CardProps as CardProps, index_DateInput as DateInput, type index_DateInputProps as DateInputProps, index_Detail as Detail, index_DetailContent as DetailContent, type index_DetailContentProps as DetailContentProps, type index_DetailProps as DetailProps, index_Dialog as Dialog, type index_DialogProps as DialogProps, index_EmptyState as EmptyState, type index_EmptyStateProps as EmptyStateProps, index_ErrorAlert as ErrorAlert, type index_ErrorAlertProps as ErrorAlertProps, type index_FieldGroup as FieldGroup, index_FilterCard as FilterCard, type index_FilterCardProps as FilterCardProps, type index_FilterField as FilterField, index_Form as Form, index_FormField as FormField, type index_FormFieldProps as FormFieldProps, type FormField$1 as FormFieldType, type index_FormProps as FormProps, index_Input as Input, type index_InputProps as InputProps, index_ListContent as ListContent, type index_ListContentProps as ListContentProps, index_PageHeader as PageHeader, type index_PageHeaderProps as PageHeaderProps, index_Pagination as Pagination, type index_PaginationProps as PaginationProps, index_Select as Select, type index_SelectOption as SelectOption, type index_SelectProps as SelectProps, index_StatCard as StatCard, type index_StatCardProps as StatCardProps, type index_StatusItem as StatusItem, index_SystemStatusCard as SystemStatusCard, type index_SystemStatusCardProps as SystemStatusCardProps, index_Textarea as Textarea, type index_TextareaProps as TextareaProps };
+}
+
+export { type BreadcrumbItem, index as Components, type DetailDatasource, DetailPageModule, type FormDatasource, FormPageModule, HtmxAdminContext, type HtmxAdminModuleOptions, HtmxAdminPlugin, type HtmxAdminPluginOptions, type ListDatasource, ListPageModule, type ListParams, type ListResult, MemoryListDatasource, type ModuleType, PageModule, PathHelper, type UserInfo, generateFormFieldsFromSchema, safeRender, validateFormDataWithSchema };