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

package/dist/index.d.mts

@@ -3,55 +3,6 @@ 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';
 
-/**
- * 组件系统上下文
- * 提供渲染上下文和组件上下文
- */
-
-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 MethodConfig {
-    method?: "get" | "post" | "put" | "delete";
-    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 注册表
  */
@@ -396,8 +347,6 @@ interface HtmxAdminPluginOptions {
     navigation?: NavItemConfig[];
     /** 认证提供者（用于鉴权和权限控制） */
     authProvider?: AuthProvider;
-    /** 组件配置（可选，用于注册组件） */
-    components?: HtmxComponent<any>[];
     /** 页面配置（可选，用于注册页面） */
     pages: PageModel[];
 }
@@ -410,7 +359,7 @@ interface HtmxAdminPluginOptions {
  * - 让类型系统更准确地反映实际的数据状态
  * - 减少类型错误和运行时检查
  */
-type ResolvedHtmxAdminPluginOptions = Required<Pick<HtmxAdminPluginOptions, "title" | "prefix" | "navigation" | "pages" | "components">> & Pick<HtmxAdminPluginOptions, "logo" | "homePath" | "authProvider" | "pages" | "components">;
+type ResolvedHtmxAdminPluginOptions = Required<Pick<HtmxAdminPluginOptions, "title" | "prefix" | "navigation" | "pages">> & Pick<HtmxAdminPluginOptions, "logo" | "homePath" | "authProvider" | "pages">;
 /**
  * 导航项配置
  */
@@ -443,16 +392,17 @@ interface FormField {
 }
 /**
  * 表单字段渲染器属性
+ * 统一接口，可在不同 Feature 中复用
  */
 interface FormFieldRendererProps<T = any> {
     /** 字段定义 */
     field: FormField;
     /** 当前值（已解析的对象/数组，不是 JSON 字符串） */
     value: any;
-    /** 完整的初始数据 */
-    initialData?: Partial<T>;
+    /** 完整的初始数据项（用于编辑模式，包含所有字段的完整数据） */
+    item?: Partial<T>;
     /** 字段名（用于更新隐藏字段） */
-    fieldName: string;
+    name: string;
 }
 
 /**
@@ -874,7 +824,6 @@ declare class HtmxAdminPlugin implements Plugin {
     readonly options: ResolvedHtmxAdminPluginOptions;
     private serviceName;
     private pages;
-    private componentHandler;
     constructor(options?: HtmxAdminPluginOptions);
     private initPages;
     /**
@@ -955,6 +904,8 @@ interface DialogProps {
 /**
  * 对话框组件
  * 用于在模态框中显示内容，支持 HTMX 交互
+ * 支持多开：每个对话框都有唯一 ID，可以同时打开多个对话框
+ * 使用 Alpine.js 实现关闭逻辑
  */
 declare function Dialog(props: DialogProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
@@ -975,6 +926,8 @@ interface ErrorAlertProps {
     className?: string;
     /** 自动关闭时间（毫秒），0 表示不自动关闭 */
     autoClose?: number;
+    /** HTMX OOB swap 属性 */
+    "hx-swap-oob"?: string;
 }
 /**
  * 错误提示组件
@@ -988,40 +941,13 @@ declare function ErrorAlert(props: ErrorAlertProps): hono_jsx_jsx_dev_runtime.JS
  */
 declare function LoadingBar(): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-interface ObjectEditorProps {
-    /** 字段定义 */
-    field: any;
-    /** 当前值（对象，已解析） */
-    value: Record<string, any> | null;
-    /** 完整的初始数据 */
-    initialData?: any;
-    /** 字段名（用于更新隐藏字段） */
-    fieldName: string;
+interface ObjectEditorProps extends FormFieldRendererProps {
     /** 对象的 Zod schema（用于自动渲染结构） */
     objectSchema?: z.ZodObject<any>;
 }
 declare function ObjectEditor(props: ObjectEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-/**
- * 字符串数组编辑器组件（Alpine.js 版本）
- * 使用 Alpine.js 实现纯 JSX 交互式组件
- *
- * 设计原则：
- * - 使用 Alpine.js 的 x-data 定义状态
- * - 尽量使用声明式语法，避免在 HTML 中写方法
- * - 使用 x-model、x-show、x-for 等 Alpine.js 指令
- * - 支持拖放排序（使用 SortableList 组件）
- * - 表单提交：通过 form-data-processor 自动解析嵌套结构和压缩数组索引
- */
-interface StringArrayEditorProps {
-    /** 字段定义 */
-    field: any;
-    /** 当前值（字符串数组，已解析） */
-    value: string[] | null;
-    /** 完整的初始数据 */
-    initialData?: any;
-    /** 字段名（用于更新隐藏字段） */
-    fieldName: string;
+interface StringArrayEditorProps extends FormFieldRendererProps {
     /** 占位符文本（可选） */
     placeholder?: string;
     /** 是否允许空值（默认 false） */
@@ -1035,26 +961,7 @@ interface StringArrayEditorProps {
  */
 declare function StringArrayEditor(props: StringArrayEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-/**
- * 标签编辑器组件（Alpine.js 版本）
- * 使用 Alpine.js 实现纯 JSX 交互式组件
- *
- * 设计原则：
- * - 使用 Alpine.js 的 x-data 定义状态
- * - 尽量使用声明式语法，避免在 HTML 中写方法
- * - 使用 x-model、x-show、x-for 等 Alpine.js 指令
- * - 支持拖放排序（使用 SortableList 组件）
- * - 表单提交：通过 form-data-processor 自动解析嵌套结构和压缩数组索引
- */
-interface TagsEditorProps {
-    /** 字段定义 */
-    field: any;
-    /** 当前值（字符串数组，已解析） */
-    value: string[] | null;
-    /** 完整的初始数据 */
-    initialData?: any;
-    /** 字段名（用于更新隐藏字段） */
-    fieldName: string;
+interface TagsEditorProps extends FormFieldRendererProps {
     /** 占位符文本（可选） */
     placeholder?: string;
     /** 是否允许空值（默认 false） */
@@ -1066,4 +973,41 @@ interface TagsEditorProps {
  */
 declare function TagsEditor(props: TagsEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-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, StringArrayEditor, type StringArrayEditorProps, TagsEditor, type TagsEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };
+/**
+ * 可拖拽排序列表组件
+ * 使用 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, SortableList, StringArrayEditor, type StringArrayEditorProps, TagsEditor, type TagsEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };

package/dist/index.d.ts

@@ -3,55 +3,6 @@ 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';
 
-/**
- * 组件系统上下文
- * 提供渲染上下文和组件上下文
- */
-
-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 MethodConfig {
-    method?: "get" | "post" | "put" | "delete";
-    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 注册表
  */
@@ -396,8 +347,6 @@ interface HtmxAdminPluginOptions {
     navigation?: NavItemConfig[];
     /** 认证提供者（用于鉴权和权限控制） */
     authProvider?: AuthProvider;
-    /** 组件配置（可选，用于注册组件） */
-    components?: HtmxComponent<any>[];
     /** 页面配置（可选，用于注册页面） */
     pages: PageModel[];
 }
@@ -410,7 +359,7 @@ interface HtmxAdminPluginOptions {
  * - 让类型系统更准确地反映实际的数据状态
  * - 减少类型错误和运行时检查
  */
-type ResolvedHtmxAdminPluginOptions = Required<Pick<HtmxAdminPluginOptions, "title" | "prefix" | "navigation" | "pages" | "components">> & Pick<HtmxAdminPluginOptions, "logo" | "homePath" | "authProvider" | "pages" | "components">;
+type ResolvedHtmxAdminPluginOptions = Required<Pick<HtmxAdminPluginOptions, "title" | "prefix" | "navigation" | "pages">> & Pick<HtmxAdminPluginOptions, "logo" | "homePath" | "authProvider" | "pages">;
 /**
  * 导航项配置
  */
@@ -443,16 +392,17 @@ interface FormField {
 }
 /**
  * 表单字段渲染器属性
+ * 统一接口，可在不同 Feature 中复用
  */
 interface FormFieldRendererProps<T = any> {
     /** 字段定义 */
     field: FormField;
     /** 当前值（已解析的对象/数组，不是 JSON 字符串） */
     value: any;
-    /** 完整的初始数据 */
-    initialData?: Partial<T>;
+    /** 完整的初始数据项（用于编辑模式，包含所有字段的完整数据） */
+    item?: Partial<T>;
     /** 字段名（用于更新隐藏字段） */
-    fieldName: string;
+    name: string;
 }
 
 /**
@@ -874,7 +824,6 @@ declare class HtmxAdminPlugin implements Plugin {
     readonly options: ResolvedHtmxAdminPluginOptions;
     private serviceName;
     private pages;
-    private componentHandler;
     constructor(options?: HtmxAdminPluginOptions);
     private initPages;
     /**
@@ -955,6 +904,8 @@ interface DialogProps {
 /**
  * 对话框组件
  * 用于在模态框中显示内容，支持 HTMX 交互
+ * 支持多开：每个对话框都有唯一 ID，可以同时打开多个对话框
+ * 使用 Alpine.js 实现关闭逻辑
  */
 declare function Dialog(props: DialogProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
@@ -975,6 +926,8 @@ interface ErrorAlertProps {
     className?: string;
     /** 自动关闭时间（毫秒），0 表示不自动关闭 */
     autoClose?: number;
+    /** HTMX OOB swap 属性 */
+    "hx-swap-oob"?: string;
 }
 /**
  * 错误提示组件
@@ -988,40 +941,13 @@ declare function ErrorAlert(props: ErrorAlertProps): hono_jsx_jsx_dev_runtime.JS
  */
 declare function LoadingBar(): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-interface ObjectEditorProps {
-    /** 字段定义 */
-    field: any;
-    /** 当前值（对象，已解析） */
-    value: Record<string, any> | null;
-    /** 完整的初始数据 */
-    initialData?: any;
-    /** 字段名（用于更新隐藏字段） */
-    fieldName: string;
+interface ObjectEditorProps extends FormFieldRendererProps {
     /** 对象的 Zod schema（用于自动渲染结构） */
     objectSchema?: z.ZodObject<any>;
 }
 declare function ObjectEditor(props: ObjectEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-/**
- * 字符串数组编辑器组件（Alpine.js 版本）
- * 使用 Alpine.js 实现纯 JSX 交互式组件
- *
- * 设计原则：
- * - 使用 Alpine.js 的 x-data 定义状态
- * - 尽量使用声明式语法，避免在 HTML 中写方法
- * - 使用 x-model、x-show、x-for 等 Alpine.js 指令
- * - 支持拖放排序（使用 SortableList 组件）
- * - 表单提交：通过 form-data-processor 自动解析嵌套结构和压缩数组索引
- */
-interface StringArrayEditorProps {
-    /** 字段定义 */
-    field: any;
-    /** 当前值（字符串数组，已解析） */
-    value: string[] | null;
-    /** 完整的初始数据 */
-    initialData?: any;
-    /** 字段名（用于更新隐藏字段） */
-    fieldName: string;
+interface StringArrayEditorProps extends FormFieldRendererProps {
     /** 占位符文本（可选） */
     placeholder?: string;
     /** 是否允许空值（默认 false） */
@@ -1035,26 +961,7 @@ interface StringArrayEditorProps {
  */
 declare function StringArrayEditor(props: StringArrayEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-/**
- * 标签编辑器组件（Alpine.js 版本）
- * 使用 Alpine.js 实现纯 JSX 交互式组件
- *
- * 设计原则：
- * - 使用 Alpine.js 的 x-data 定义状态
- * - 尽量使用声明式语法，避免在 HTML 中写方法
- * - 使用 x-model、x-show、x-for 等 Alpine.js 指令
- * - 支持拖放排序（使用 SortableList 组件）
- * - 表单提交：通过 form-data-processor 自动解析嵌套结构和压缩数组索引
- */
-interface TagsEditorProps {
-    /** 字段定义 */
-    field: any;
-    /** 当前值（字符串数组，已解析） */
-    value: string[] | null;
-    /** 完整的初始数据 */
-    initialData?: any;
-    /** 字段名（用于更新隐藏字段） */
-    fieldName: string;
+interface TagsEditorProps extends FormFieldRendererProps {
     /** 占位符文本（可选） */
     placeholder?: string;
     /** 是否允许空值（默认 false） */
@@ -1066,4 +973,41 @@ interface TagsEditorProps {
  */
 declare function TagsEditor(props: TagsEditorProps): hono_jsx_jsx_dev_runtime.JSX.Element;
 
-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, StringArrayEditor, type StringArrayEditorProps, TagsEditor, type TagsEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };
+/**
+ * 可拖拽排序列表组件
+ * 使用 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, SortableList, StringArrayEditor, type StringArrayEditorProps, TagsEditor, type TagsEditorProps, type UserInfo, checkUserPermission, getUserInfo, modelNameToPath, parseListParams };