imean-service-engine-htmx-plugin 2.3.1 → 2.5.0

package/dist/index.d.mts

@@ -2,47 +2,137 @@ 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 核心类型定义
+ * 组件系统上下文
+ * 提供渲染上下文和组件上下文
  */
 
+declare class RenderContext<TProps = any, TState = any> {
+    readonly prefix: string;
+    readonly instanceId: string;
+    readonly componentName: string;
+    constructor(prefix: string, instanceId: string, componentName: string);
+    $id(): string;
+    setState(state: Partial<TState>): void;
+    get state(): TState;
+    get props(): TProps;
+    url(methodName: string, params?: Record<string, any>): string;
+    callMethod(methodName: string, params: Record<string, string>): any;
+}
+declare class ComponentContext extends RenderContext {
+    readonly ctx: Context;
+    constructor(prefix: string, ctx: Context, componentName: string);
+    params(): Promise<Record<string, any>>;
+    query(): Record<string, string>;
+    body(): Promise<any>;
+}
+
 /**
- * 操作按钮配置
+ * 组件系统核心
+ * 提供组件基类、方法装饰器和组件注册功能
  */
-interface ActionButton {
-    /** 按钮文本 */
-    label: string;
-    /** 链接地址（页面模式使用） */
-    href?: string;
-    /** HTTP 方法 */
+
+interface MethodConfig {
     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 时，点击按钮会自动关闭弹窗，无需写 Hyperscript 代码） */
-    close?: boolean;
-    /** 是否提交表单（设置为 true 时，按钮会提交指定的表单，需要配合 formId 使用） */
-    submit?: boolean;
-    /** 表单 ID（当 submit 为 true 时，指定要提交的表单 ID） */
-    formId?: string;
-    /** 自定义点击事件（如关闭弹窗，当 close 为 true 时此属性会被忽略） */
-    onClick?: string;
-    /** 自定义类名 */
-    className?: string;
-    /** 链接目标（如 "_blank" 表示新窗口打开） */
-    target?: string;
+    path?: string;
+}
+declare function Method(config?: MethodConfig): (target: any, propertyKey: string, _descriptor: PropertyDescriptor) => void;
+declare abstract class HtmxComponent<TProps = any> {
+    readonly name: string;
+    prefix: string;
+    constructor(name: string);
+    readonly Component: (props: TProps) => any;
+    protected abstract render(ctx: RenderContext, props: TProps): any;
+    getScript?(): any;
+    static getMethods(component: HtmxComponent<any>): Map<string, {
+        method: "get" | "post" | "put" | "delete";
+        path?: string;
+        handler: (ctx: ComponentContext) => Promise<Response>;
+    }>;
 }
+
+/**
+ * Feature 注册表
+ */
+
+/**
+ * Feature 注册表
+ * 类型通过 model.schema 的 z.infer 推断
+ */
+declare class FeatureRegistry {
+    private features;
+    private model;
+    constructor(model: PageModel);
+    /**
+     * 注册 Feature
+     */
+    register(name: string, feature: Feature): void;
+    /**
+     * 快捷方法：注册列表 Feature
+     */
+    list(feature: Feature): void;
+    /**
+     * 快捷方法：注册详情 Feature
+     */
+    detail(feature: Feature): void;
+    /**
+     * 快捷方法：注册创建 Feature
+     */
+    create(feature: Feature): void;
+    /**
+     * 快捷方法：注册编辑 Feature
+     */
+    edit(feature: Feature): void;
+    /**
+     * 快捷方法：注册删除 Feature
+     */
+    delete(feature: Feature): void;
+    /**
+     * 快捷方法：注册自定义 Feature
+     */
+    custom(name: string, feature: Feature): void;
+    /**
+     * 获取所有注册的 Feature
+     */
+    getAll(): Feature[];
+    /**
+     * 获取指定 Feature
+     */
+    get(name: string): Feature | undefined;
+}
+
+/**
+ * PageModel 基类
+ * 统一处理有数据模型和无数据模型的场景
+ */
+
+/**
+ * PageModel 基类
+ * 不再包含 schema，schema 由各个 Feature 指定
+ */
+declare abstract class PageModel {
+    readonly modelName: string;
+    readonly features: FeatureRegistry;
+    private metadata;
+    /**
+     * 构造函数
+     * @param modelName 模型/页面名称（用于路由和权限）
+     * @param metadata 页面元数据（可选，如果提供则不需要实现 getMetadata）
+     */
+    constructor(modelName: string, metadata?: PageMetadata);
+    /**
+     * 获取页面元数据
+     * 如果构造函数提供了 metadata，直接返回
+     * 否则调用子类实现
+     */
+    getMetadata(): PageMetadata;
+}
+
+/**
+ * HtmxAdminPlugin 核心类型定义
+ */
+
 /**
  * 对话框大小类型
  */
@@ -209,8 +299,8 @@ interface Feature {
     getTitle?(context: FeatureContext): string | Promise<string>;
     /** 获取动态描述（可选，会覆盖 PageMetadata 的 description） */
     getDescription?(context: FeatureContext): string | Promise<string> | undefined | Promise<string | undefined>;
-    /** 获取操作按钮（可选，根据 isDialog 返回不同的按钮配置） */
-    getActions?(context: FeatureContext): ActionButton[] | Promise<ActionButton[]>;
+    /** 获取操作按钮（可选，返回 JSX，用于在 layout 中渲染） */
+    getActions?(context: FeatureContext): any | Promise<any>;
     /** 路由配置（必须实现） */
     getRoutes(): Array<{
         method: "get" | "post" | "put" | "delete";
@@ -306,7 +396,21 @@ interface HtmxAdminPluginOptions {
     navigation?: NavItemConfig[];
     /** 认证提供者（用于鉴权和权限控制） */
     authProvider?: AuthProvider;
+    /** 组件配置（可选，用于注册组件） */
+    components?: HtmxComponent<any>[];
+    /** 页面配置（可选，用于注册页面） */
+    pages: PageModel[];
 }
+/**
+ * 已解析的插件配置选项（已处理默认值，所有必需字段都是非可选的）
+ *
+ * 设计原则：如果在上层已经处理了默认值，那么向下传递时就不应该是可选类型。
+ * 这样可以：
+ * - 避免重复的默认值处理
+ * - 让类型系统更准确地反映实际的数据状态
+ * - 减少类型错误和运行时检查
+ */
+type ResolvedHtmxAdminPluginOptions = Required<Pick<HtmxAdminPluginOptions, "title" | "prefix" | "navigation" | "pages" | "components">> & Pick<HtmxAdminPluginOptions, "logo" | "homePath" | "authProvider" | "pages" | "components">;
 /**
  * 导航项配置
  */
@@ -351,83 +455,6 @@ interface FormFieldRendererProps<T = any> {
     fieldName: string;
 }
 
-/**
- * Feature 注册表
- */
-
-/**
- * Feature 注册表
- * 类型通过 model.schema 的 z.infer 推断
- */
-declare class FeatureRegistry {
-    private features;
-    private model;
-    constructor(model: PageModel);
-    /**
-     * 注册 Feature
-     */
-    register(name: string, feature: Feature): void;
-    /**
-     * 快捷方法：注册列表 Feature
-     */
-    list(feature: Feature): void;
-    /**
-     * 快捷方法：注册详情 Feature
-     */
-    detail(feature: Feature): void;
-    /**
-     * 快捷方法：注册创建 Feature
-     */
-    create(feature: Feature): void;
-    /**
-     * 快捷方法：注册编辑 Feature
-     */
-    edit(feature: Feature): void;
-    /**
-     * 快捷方法：注册删除 Feature
-     */
-    delete(feature: Feature): void;
-    /**
-     * 快捷方法：注册自定义 Feature
-     */
-    custom(name: string, feature: Feature): void;
-    /**
-     * 获取所有注册的 Feature
-     */
-    getAll(): Feature[];
-    /**
-     * 获取指定 Feature
-     */
-    get(name: string): Feature | undefined;
-}
-
-/**
- * PageModel 基类
- * 统一处理有数据模型和无数据模型的场景
- */
-
-/**
- * PageModel 基类
- * 不再包含 schema，schema 由各个 Feature 指定
- */
-declare abstract class PageModel {
-    readonly modelName: string;
-    readonly features: FeatureRegistry;
-    private metadata;
-    /**
-     * 构造函数
-     * @param modelName 模型/页面名称（用于路由和权限）
-     * @param metadata 页面元数据（可选，如果提供则不需要实现 getMetadata）
-     */
-    constructor(modelName: string, metadata?: PageMetadata);
-    /**
-     * 获取页面元数据
-     * 如果构造函数提供了 metadata，直接返回
-     * 否则调用子类实现
-     */
-    getMetadata(): PageMetadata;
-}
-
 /**
  * Feature 基类
  * 提供所有 Feature 的公共属性和默认实现
@@ -470,10 +497,10 @@ declare abstract class BaseFeature implements Feature {
      */
     getDescription(context: FeatureContext): Promise<string | undefined>;
     /**
-     * 获取操作按钮（默认实现：返回空数组）
-     * 子类可以覆盖此方法以提供操作按钮
+     * 获取操作按钮（默认实现：返回 null）
+     * 子类可以覆盖此方法以提供操作按钮（返回 JSX）
      */
-    getActions(context: FeatureContext): Promise<ActionButton[]>;
+    getActions(context: FeatureContext): Promise<any>;
     /**
      * 获取路由配置（必须实现）
      */
@@ -482,11 +509,11 @@ declare abstract class BaseFeature implements Feature {
         path: string;
     }>;
     /**
-     * 处理请求（可选，如果实现了 handle，则优先使用 handle）
+     * 处理请求
      */
-    handle?(context: FeatureContext): Promise<any>;
+    handle(context: FeatureContext): Promise<any>;
     /**
-     * 渲染页面（可选，如果 handle 不存在或返回 undefined，则使用 render）
+     * 渲染页面
      */
     render?(context: FeatureContext): Promise<any>;
 }
@@ -569,9 +596,9 @@ declare abstract class BaseFormFeature<T extends {
      */
     render(context: FeatureContext, initialData?: Partial<T>): Promise<any>;
     /**
-     * 获取操作按钮
+     * 获取操作按钮（返回 JSX）
      */
-    getActions(context: FeatureContext): Promise<ActionButton[]>;
+    getActions(context: FeatureContext): Promise<any>;
 }
 
 /**
@@ -692,7 +719,6 @@ declare class DefaultDetailFeature<T extends {
     id: string | number;
 } = any> extends BaseFeature {
     private getItem;
-    private deleteItem?;
     private titleGetter?;
     private descriptionGetter?;
     private detailFieldNames?;
@@ -702,7 +728,6 @@ declare class DefaultDetailFeature<T extends {
         /** 详情数据的 Schema（用于字段推断和显示） */
         schema: z.ZodObject<any>;
         getItem: (id: string | number) => Promise<T | null>;
-        deleteItem?: (id: string | number) => Promise<boolean>;
         permissionPrefix: string;
         permission?: string;
         dialogSize?: DialogSize;
@@ -725,7 +750,7 @@ declare class DefaultDetailFeature<T extends {
         path: string;
     }[];
     render(context: FeatureContext): Promise<any>;
-    getActions(context: FeatureContext): Promise<ActionButton[]>;
+    getActions(context: FeatureContext): Promise<any>;
 }
 
 /**
@@ -830,7 +855,7 @@ declare class DefaultListFeature<T extends {
         path: string;
     }[];
     render(context: FeatureContext): Promise<any>;
-    getActions(context: FeatureContext): Promise<ActionButton[]>;
+    getActions(context: FeatureContext): Promise<any>;
 }
 
 /**
@@ -846,18 +871,16 @@ declare class HtmxAdminPlugin implements Plugin {
     readonly priority = PluginPriority.ROUTE;
     private engine;
     private hono;
-    private options;
+    readonly options: ResolvedHtmxAdminPluginOptions;
     private serviceName;
     private pages;
+    private componentHandler;
     constructor(options?: HtmxAdminPluginOptions);
+    private initPages;
     /**
-     * 注册页面（统一接口，支持有模型和无模型）
-     */
-    registerPage(page: PageModel): this;
-    /**
-     * 批量注册页面
+     * 注册页面
      */
-    registerPages(...pages: PageModel[]): this;
+    private registerPage;
     /**
      * 引擎初始化钩子
      */
@@ -908,6 +931,9 @@ interface PermissionCheckResult {
  */
 declare function checkUserPermission(requiredPermission: string | null, userPermissions: string[]): PermissionCheckResult;
 
+/**
+ * 对话框组件（Modal/Dialog）
+ */
 interface DialogProps {
     /** 对话框标题 */
     title?: string;
@@ -921,11 +947,15 @@ interface DialogProps {
     size?: "sm" | "md" | "lg" | "xl" | "full";
     /** 是否允许点击遮罩区域关闭（默认 true，设置为 false 时只能通过关闭按钮关闭） */
     closeOnBackdropClick?: boolean;
-    /** 操作按钮（在 Footer 中显示，固定在底部） */
-    actions?: ActionButton[];
+    /** 操作按钮（在 Footer 中显示，固定在底部，通过 JSX 方式渲染） */
+    actions?: any;
     /** 是否固定内容区域高度（用于表单等需要固定高度的场景，避免切换 Tab 时高度变化） */
     fixedContentHeight?: boolean;
 }
+/**
+ * 对话框组件
+ * 用于在模态框中显示内容，支持 HTMX 交互
+ */
 declare function Dialog(props: DialogProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
 /**
@@ -973,9 +1003,15 @@ interface ObjectEditorProps {
 declare function ObjectEditor(props: ObjectEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
 /**
- * 字符串数组编辑器组件
- * 支持增加、删除和拖放排序功能
- * 使用 Alpine.js 管理状态，通过隐藏字段与表单系统同步数据
+ * 字符串数组编辑器组件（Alpine.js 版本）
+ * 使用 Alpine.js 实现纯 JSX 交互式组件
+ *
+ * 设计原则：
+ * - 使用 Alpine.js 的 x-data 定义状态
+ * - 尽量使用声明式语法，避免在 HTML 中写方法
+ * - 使用 x-model、x-show、x-for 等 Alpine.js 指令
+ * - 支持拖放排序（使用 SortableList 组件）
+ * - 表单提交：通过 form-data-processor 自动解析嵌套结构和压缩数组索引
  */
 interface StringArrayEditorProps {
     /** 字段定义 */
@@ -990,14 +1026,25 @@ interface StringArrayEditorProps {
     placeholder?: string;
     /** 是否允许空值（默认 false） */
     allowEmpty?: boolean;
+    /** 输入框行数（默认 1，大于 1 时使用 textarea） */
+    rows?: number;
 }
-declare function StringArrayEditor(props: StringArrayEditorProps): hono_utils_html.HtmlEscapedString | Promise<hono_utils_html.HtmlEscapedString>;
+/**
+ * 字符串数组编辑器组件（Alpine.js 版本）
+ * 使用 Alpine.js 的 x-data 和指令实现交互
+ */
+declare function StringArrayEditor(props: StringArrayEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
 /**
- * 标签编辑器组件
- * 支持增加、删除和拖放排序功能
- * 使用更紧凑的标签样式布局，适合维护 tags
- * 使用 Alpine.js 管理状态，通过隐藏字段与表单系统同步数据
+ * 标签编辑器组件（Alpine.js 版本）
+ * 使用 Alpine.js 实现纯 JSX 交互式组件
+ *
+ * 设计原则：
+ * - 使用 Alpine.js 的 x-data 定义状态
+ * - 尽量使用声明式语法，避免在 HTML 中写方法
+ * - 使用 x-model、x-show、x-for 等 Alpine.js 指令
+ * - 支持拖放排序（使用 SortableList 组件）
+ * - 表单提交：通过 form-data-processor 自动解析嵌套结构和压缩数组索引
  */
 interface TagsEditorProps {
     /** 字段定义 */
@@ -1013,6 +1060,47 @@ interface TagsEditorProps {
     /** 是否允许空值（默认 false） */
     allowEmpty?: boolean;
 }
-declare function TagsEditor(props: TagsEditorProps): hono_utils_html.HtmlEscapedString | Promise<hono_utils_html.HtmlEscapedString>;
+/**
+ * 标签编辑器组件（Alpine.js 版本）
+ * 使用 Alpine.js 的 x-data 和指令实现交互
+ */
+declare function TagsEditor(props: TagsEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
+
+/**
+ * 可拖拽排序列表组件
+ * 使用 HTML5 原生拖放 API 实现拖拽排序
+ *
+ * 设计原则：
+ * - 使用 Alpine.js 管理状态和事件处理
+ * - 使用 HTML5 原生拖放 API（draggable、x-on:dragstart、x-on:dragover、x-on:drop）
+ * - 高阶组件，可以包裹任何子元素
+ * - 使用事件委托，在容器上统一处理所有拖拽事件
+ * - 所有事件处理使用 Alpine.js 声明式语法
+ */
+interface SortableListProps {
+    /** 子元素 */
+    children: any;
+    /** 自定义类名 */
+    className?: string;
+    /** 拖拽手柄选择器（可选，如果提供，只有手柄可拖拽） */
+    handle?: string;
+    /** 拖拽时的样式类名（可选） */
+    draggingClass?: string;
+    /** 拖拽悬停时的样式类名（可选） */
+    dragOverClass?: string;
+    /** 排序变化回调（可选） */
+    onSortableChange?: (detail: {
+        oldIndex: number;
+        newIndex: number;
+    }) => void;
+    /** 其他属性 */
+    [key: string]: any;
+}
+/**
+ * 可拖拽排序列表组件
+ * 使用 HTML5 原生拖放 API 和 Alpine.js 声明式语法
+ * 使用事件委托在容器上统一处理所有拖拽事件
+ */
+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, StringArrayEditor, type StringArrayEditorProps, TagsEditor, type TagsEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };
+export { type AuthProvider, BaseFeature, ComponentContext, 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, HtmxComponent, type ListParams, type ListResult, LoadingBar, Method, type NavItemConfig, type Notification, type NotificationType, ObjectEditor, type ObjectEditorProps, type PageMetadata, PageModel, type PermissionResult, RenderContext, SortableList, StringArrayEditor, type StringArrayEditorProps, TagsEditor, type TagsEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };